wangai-cli

https://www.npmjs.com/package/wangai-cli

wangai-cli for WangClaw（Agent 优先）

所有业务请求走 MCP 网关（mcp-gateway）。状态全部由 Host（jvscrew 沙箱）通过环境变量注入；CLI 在 token 即将过期时静默续期，并通过 Host 回调写回 env。

安装

npm i -g wangai-cli@latest # 安装或更新

# 或仓库内
pnpm install && pnpm run build

Agent 快速上手

# 1. 自检（不输出 token 明文）
wangai-cli config list

# 2. 项目
wangai-cli project list
wangai-cli project use --project-id <projectId>

# 3. 业务
wangai-cli audio list --from "2026-05-01 00:00:00" --to "2026-05-02 00:00:00"

凭据与 ENV 由 Host 注入；CLI 无 config set。缺 token 时提示用户刷新会话。

仅当 XB_APP_ID=aike 时禁止 project use；其他应用（含 wangclaw）均可通过 CLI 切换。

config 命令

| 命令 | 说明 | |------|------| | config list [--format json] | 只读诊断：ENV、gateway/auth/callback URL、凭据状态（脱敏）、激活项目 |

环境变量（唯一真相源）

| 变量 | 说明 | |------|------| | ENV | test / prod（Host 注入；本地未设时默认 test） | | MCP_TOKEN | Bearer access_token | | REFRESH_TOKEN | refresh_token（续期用） | | EXPIRES_TIMES | access_token 过期时间，epoch 毫秒 | | USER_ID / USER_NAME | 当前用户；USER_ID 用于 Host 回调 URL | | TENANT_ID / TENANT_NAME | 当前租户（Host 注入） | | XB_APP_ID | aike 时禁止 project use；其他值允许 | | MCP_CLIENT_ID | refresh_token 请求可选 client_id |

网关 / 鉴权 / 回调 base URL 由 Host 注入的 ENV 选择内置 profile，在 src/core/endpoints.ts 的 PROFILES 维护。

命令列表

| 命令 | tool（params.name） | 说明 | |------|---------------------|------| | config list | — | 配置只读诊断 | | project list | project-list | 租户与项目 | | project use / current | — | 激活/查看楼盘（env + 回调） | | consultant list | consultant-list | 置业顾问 | | audio list / text / analyze | audio-* | 录音 | | customer list | customer-list | 客户画像 | | visit list / summary | visit-* | 来访 | | focus list / resistance list | focus-list / resistance-list | 标签 | | qa <message> | sql-agent | 自然语言问数(在观测云可以用observation_metadata_call_source:~wangclaw筛选所有来自wangclaw的call) | | kb search <query> | kb-search | 知识库混合检索（tenant_id + project_id） | | kb doc list | kb-doc-list | 知识库文档列表 | | kb doc get <id> | kb-doc-get | 文档元数据 | | kb doc content <id> | kb-doc-content | 文档全文（字符分页） | | quantum … | quantum-*（约 20 个） | 量子预聚合 KPI/排名/趋势；见下方 quantum 子命令 |

quantum 子命令

CLI 路径 quantum <域> <view|mode> 映射 MCP quantum-* 工具；view/mode 写在子命令名里，时间等可选参数与 BFF schema 一致。

| 命令前缀 | MCP tool | 默认 view/mode | 备注 | |----------|----------|----------------|------| | quantum visit | quantum-visit | view=summary | --stat-dimension visit_times\|customer_num | | quantum visit-realtime | quantum-visit-realtime | view=trend | trend / resistance / resistance_list / deal | | quantum visit-ongoing | quantum-visit-ongoing | mode=page | page / count | | quantum follow | quantum-follow | view=summary | --stat-dimension follow_times\|customer_num | | quantum job-performance | quantum-job-performance | view=summary | | | quantum work-quality | quantum-work-quality | view=summary | | | quantum visit-timer | quantum-visit-timer | view=summary | --metric total\|avg | | quantum usage-data consultant\|manager | quantum-usage-data | role + view | | | quantum resistance-point | quantum-resistance-point | view=distribution | | | quantum speech-sale / demand-data | 同名 | view=summary | 分页 --page / --size | | quantum hot-words / risk | 同名 | view=summary | | | quantum special-visit | quantum-special-visit | view=summary | | | quantum month-report | quantum-month-report | mode=query | query / find | | quantum deal | quantum-deal | view=status | | | quantum intent | quantum-intent | view=level | --dimension review\|ai（非 pin-talk 的 dimension view） | | quantum pin-talk | quantum-pin-talk | view=summary | --model-id 可选；models 子命令列模型 | | quantum demand-card | quantum-demand-card | view=summary | --model-id 可选 | | quantum rhetoric | quantum-rhetoric | （无 view） | |

口径说明：未传 config 时由 application 使用平台默认 CardConfig（非用户 Dashboard 卡片配置）。时间默认当天 00:00:00～次日 00:00:00。

Agent 路由：与 visit list、resistance list、qa 等重叠的 KPI/统计问题，必须优先 quantum *，见 skills/wangai-platform-quantum/SKILL.md。

示例：

wangai-cli quantum visit summary --from "2026-06-23 00:00:00" --to "2026-06-24 00:00:00"
wangai-cli quantum visit summary --stat-dimension customer_num
wangai-cli quantum intent level --dimension ai
wangai-cli quantum pin-talk models   # 列出可用销讲 model_id

api 子命令默认关闭；开发调试时在 src/core/feature-flags.ts 将 ENABLE_API_COMMAND 设为 true 后重新 build。

内部开关

| 文件 | 开关 | 说明 | |------|------|------| | src/core/feature-flags.ts | ENABLE_API_COMMAND | true 时注册 wangai-cli api |

错误码（stdout）

| code | hint 方向 | |------|-----------| | MISSING_GATEWAY | Host 设置 ENV=test | | MISSING_ACCESS_TOKEN | Host 注入 MCP_TOKEN | | MISSING_REFRESH_TOKEN | Host 注入 REFRESH_TOKEN | | ACCESS_TOKEN_EXPIRED | 确保 REFRESH_TOKEN 可续期 | | REFRESH_FAILED | Host 重新换票 | | ENV_CALLBACK_FAILED | 检查 USER_ID 与 Host 回调服务 | | NO_ACTIVE_PROJECT | Host 预置项目或 project use | | PROJECT_SWITCH_NOT_ALLOWED | XB_APP_ID=aike 时用 UI 切项目 |

输出协议

• stdout：结果或结构化错误（默认 TOON）
• stderr：人类提示
• 退出码：0 成功，非 0 失败

Auth 续期

每次 MCP 调用前，ensureAuth() 检查 EXPIRES_TIMES；距过期不足 120 秒时：

1. 用 REFRESH_TOKEN 换票
2. 回调 Host 更新 MCP_TOKEN / REFRESH_TOKEN / EXPIRES_TIMES
3. 再发起 MCP 请求

人类本地调试

env.sh 可用 App X-Auth-Token 换票并 export 到当前 shell（不经 Host 回调）：

source ./env.sh '<x-auth-token>'
wangai-cli project list

调试日志

| 项 | 说明 | | --- | --- | | 路径 | ~//home/wuying/jvscrew/files/.wangai-cli/log.jsonl（JSON Lines，追加写入） | | 错误 | 始终记录（含 Host/MCP 上游 msg、details） | | 详细 trace | 设置 WANGAI_CLI_DEBUG=1 后额外记录 HTTP/MCP 请求摘要（token 自动脱敏） |

export WANGAI_CLI_DEBUG=1
wangai-cli project use --project-id ...
tail -f ~//home/wuying/jvscrew/files/.wangai-cli/log.jsonl

License

MIT