AHSOpsHub CLI

AHSOpsHub 的本机 CLI，对标飞书 lark-cli 的认证、信封、Skill 和高风险确认机制。服务端按用户实时权限执行，生产开关默认关闭。

用户安装

Windows、macOS 和 Linux 使用同一条命令。安装过程中再选择要把 Skills 写到哪个 AI Agent：

npx @chuhe2640/ahsopus-cli@latest install --server <当前 AHSOpsHub 地址> --profile <dev|office|prod>

用户安装只需要 Node.js 18+（npm / npx），与飞书 CLI 一样不需要 Go。npx 会下载当前平台的预编译 ahsops 并装到 npm 全局命令。Go 1.23+ 只在从源码构建或发布 npm 包时需要。开发和生产共用这一条 CLI，用 profile 指向不同服务地址，不要发第二套包。调试 CLI 源码时不要 npm publish 到 latest，在 cli 目录运行 npx --yes . install --server <地址> --profile dev。

发布到 npm（包名挂在当前 npm 账号 chuhe2640 下）。发布前必须 npm whoami 为 chuhe2640。本机 token 失效时 PUT 会被 npm 伪装成 404 Not Found，先重新登录：

npm login --auth-type=web --scope=@chuhe2640
npm whoami
cd cli
npm publish --access public

若账号开了 2FA，经典 npm_ token 可能仍不能直发；到 npmjs.com 建 Granular Access Token（Read and write、允许 2FA 发布），写入 ~/.npmrc 的 //registry.npmjs.org/:_authToken=。

正式签名发布物仍可使用校验 SHA-256 的仓库安装器，不会静默更新，也不会绕过 macOS 代码签名／Gatekeeper 或 Windows Authenticode：

bash install.sh https://release.example.internal/ahsops 0.1.0

.\install.ps1 -ReleaseBaseUrl https://release.example.internal/ahsops -Version 0.1.0

首次使用

ahsops profile add office --server http://192.168.1.20:3000
ahsops auth login --recommend
ahsops skills install --target claude-code --scope user
ahsops doctor

Agent 登录不要阻塞等用户点浏览器：ahsops auth login --no-open --no-wait，把 verification_uri_complete 和 ahsops auth qrcode --url ... 交给用户，再用 --device-code 继续轮询。缺 --yes 的写操作退出码是 10，不是普通错误。

profile可使用HTTP或HTTPS。部门内网部署直接使用专用Mac的http://局域网IP:3000，不需要额外开关、参数或交互确认。服务端PUBLIC_APP_URL也必须使用同一个其他电脑可访问的地址；127.0.0.1只适用于浏览器和服务都在同一台机器的情况。系统已移除本地密码登录，但HTTP仍会明文传输飞书 OAuth 回调 code、Cookie、CLI Token和业务结果，这是当前部署明确接受的取舍。凭据默认存入 macOS Keychain 或 Windows Credential Manager；系统钥匙串不可用时，必须由用户在交互终端显式执行：

ahsops auth storage file-enable

文件存储使用 AES-GCM 和权限为 0600 的本机主密钥，但同一系统用户下的其他进程仍可能读取，因此不会自动降级到文件存储。

file-enable和keychain-enable会迁移全部已配置profile的现有凭据，目标存储回读和配置激活成功后才清理旧存储；切换失败时保留原凭据。若旧存储清理失败，CLI通过warnings明确列出受影响profile，但已激活的目标凭据仍可用。

设备 Token 轮询遇到短暂网络中断时会在设备码有效期内继续；如果服务端已经消费设备码但响应丢失，CLI会返回invalid_grant并要求重新登录。auth logout在远端撤销成功或服务端明确返回401时删除本机凭据；网络中断和临时服务端错误不会清理凭据，避免留下无法从终端撤销的活跃会话。

输出和写操作

默认成功输出写 stdout，错误写 stderr，格式均为 JSON 信封。可选 pretty、table、ndjson 和 csv，并支持本地 --jq。复杂请求使用：

ahsops analytics tools search --data @search.json
ahsops notification preview --data @preview.json --dry-run

受控写操作先运行 --dry-run；服务端会执行与真实操作相同的权限、对象、状态、Release和配置版本校验，然后回滚数据库事务。向用户说明实际变化后才可使用 --yes。规则正式应用、真实通知发送、资产发布/恢复和平台配置不在 v1 CLI 中开放。

每个真实写请求的幂等记录和业务变更在同一PostgreSQL事务中提交；中途故障会整体回滚，成功重试则在重新检查当前RBAC后返回原结果。CSV对可能被电子表格执行的字符串加入防护，table输出移除ANSI与终端控制字符。

开放看板

ahsops catalog list 里的开放产品都可以查：

ahsops dashboard +snapshot --product consultation-complaint-sentiment --from 2026-08-28 --to 2026-09-03
ahsops dashboard +snapshot --product xianyu-sales --from 2026-08-28 --to 2026-09-03
ahsops table query --product selected-quality --from 2026-08-28 --to 2026-09-03 --agent
ahsops asset range-export --key consignment_mail --from 2026-04-01 --to 2026-09-01 --yes

体验看板可用 --data '{"board":"consultation"}' 切咨询/客诉/舆情；snapshot 不跑 AI 诊断。闲鱼销售只读；更新、异常检测和底表导出会 409。资产按时间导出创建 asset_range_export，再用 ahsops task artifact-download 取 xlsx。

本地开发

要求 Go 1.23 或更高版本：

go test ./...
go test -race ./...
go build ./cmd/ahsops

本仓库不再使用 GitHub Actions 做 CLI 测试或签名发行。格式、契约和 go test 在本机执行。用户安装走 npm：npx @chuhe2640/ahsopus-cli@latest install。

验证边界

• go test 和交叉编译不等于 Windows 真机运行验收。
• 安装器校验 SHA-256 不等于代码签名、公证或公司软件分发审批。
• 本地 CLI 测试不等于真实 PostgreSQL 迁移、局域网HTTP多设备访问、Claude Code/Codex 前向任务或生产验收。