旺小宝 CLI 共享规则
本 skill 定义所有 xiaobao-cli 命令通用的前置约束 + 协议，其他旺小宝 skill
开始执行前 MUST 先用 Read tool 完整读取本文件。
安装
# 全局安装（推荐，长期用）
npm install -g @puyinkai/xiaobao-cli
# 或一次性用（不污染全局）
npx -y @puyinkai/xiaobao-cli <subcommand>...
装好后 xiaobao-cli --version 应返回 0.1.x。Node 22+。
三步走基础流程
任何 xiaobao-cli 命令的前置 3 步：
# 1. 登录（OAuth device flow 非阻塞 split-flow，token 自动缓存）—— 见下方
xiaobao-cli auth login --no-wait
# 2. 选激活项目（多租户 / 多项目场景必做；旺小宝是多租户业务）
xiaobao-cli project list # 列可选
xiaobao-cli project use --tenant-id ... --tenant-name ... \
--project-id ... --project-name ...
# 3. 跑业务命令（这一步往后所有 list/text/qa 命令都从激活项目读 tenant/project）
xiaobao-cli audio list --from ... --to ...
xiaobao-cli customer list --portrait 高意向
# ...
登录 —— 用 --no-wait split-flow（两步、不阻塞）
登录走 OAuth device flow，固定用下面的两步、全程不阻塞。不要跑裸
xiaobao-cli auth login —— 它会阻塞轮询、卡满一整轮对话。
# 步骤 A：发起，立即返回（约 0.5s），拿到 verification_uri
xiaobao-cli auth login --no-wait
# stdout: { "awaiting_authorization": true, "verification_uri": "...",
# "verification_link": "[点击完成旺小宝登录授权](https://...)",
# "user_code": "...", "expires_in": 300, "interval": 5, ... }
# device_code 不在 stdout —— 已安全存到 ~/.xiaobao/pending-auth.json（0600）
agent 拿到后：把 stdout 里的 verification_link 字段原样发给用户 —— 它
已经是 markdown 可点击链接 [点击完成旺小宝登录授权](https://...)，直接粘进
回复正文（不要放进代码块 —— 代码块里链接不可点击），用户点一下即可在浏览器
打开授权。不要改写链接、不要做 URL 编码。发完结束本轮，把控制权交还用户。
# 步骤 B：用户回复"授权完成"后，直接换 token（秒级）——
# device_code 已由步骤 A 存在本地，--resume 自动读取，agent 无需持有 / 传递它
xiaobao-cli auth login --resume
# stdout: { "source": "device-flow", "expires_at": ..., "scope": "..." }
device_code 有效期 expires_in 秒（约 5 分钟）。超时就重跑步骤 A。
若 token 仍有效 / refresh_token 可用，--no-wait 会直接走 cache/refresh
快速返回（source: cache / refresh），不发起新的 device flow，也无需步骤 B。
查身份 / 当前激活项目（任何时候都可以）：
xiaobao-cli auth whoami # 显示 logged_in + user 信息 + token 剩余有效期
xiaobao-cli project current # 显示当前激活的 tenant/project + updatedAt
输出协议
所有命令统一协议:
| 流 | 内容 |
|---|---|
| stdout | 结果 / 错误对象，默认 TOON 格式（省 token）；--format json 切回 JSON。均可机器解析 |
| stderr | 进度 / 人类友好错误提示 / verification URL 等。Agent 一般忽略 |
| exit code | 0 = 成功；非 0 = 失败（业务错误 / 参数错 / 网络错） |
Agent 消费时只 parse stdout JSON，stderr 是辅助。
--format 全局 flag
| 值 | 用途 |
|---|---|
toon（默认） |
TOON 格式，uniform array of objects 省 30-50% token（LLM 上下文优化） |
json |
pretty JSON，agent / 人类都能读；需要严格 JSON 时显式加 --format json |
错误对象结构
失败时 stdout 输出结构化错误（仍是合法 JSON，agent 直接 parse）:
{
"error": "NO_ACTIVE_PROJECT",
"message": "当前未设置激活项目",
"hint": "先用 `xiaobao-cli project list [--keyword <kw>]` 查看可选项目，再用 `xiaobao-cli project use ...` 激活。"
}
字段语义:
error：机器可读错误码（常量字符串，agent 用它做分支判断）message：短描述（一句话讲发生了什么）hint：actionable 命令引导（agent 直接照这条命令解决，不要再让用户自己想）
常见错误码
| code | 触发场景 | hint 内 actionable 命令 |
|---|---|---|
NOT_AUTHENTICATED |
未登录 / token 过期且 refresh_token 也失效 | xiaobao-cli auth login --no-wait（split-flow，见上方登录段） |
NO_ACTIVE_PROJECT |
没设激活项目就跑了需要 tenant/project 的命令 | xiaobao-cli project list + xiaobao-cli project use ... |
API_ERROR |
上游 ai-open / saas API 返非 2xx | 看 details.status 和 details.body，可能 token scope 不够 / 上游临时挂 |
BAD_METHOD |
api 命令传错 HTTP method |
用 GET / POST / PUT / PATCH / DELETE |
遇到 NOT_AUTHENTICATED 或 NO_ACTIVE_PROJECT 时立即按 hint 走，不要追问用户。
state 文件位置
| 文件 | 用途 | 路径 | 权限 |
|---|---|---|---|
| OAuth tokens | access_token + refresh_token + id_token + expires_at | ~/.xiaobao/token.json |
0600 |
| Active project | tenantId / tenantName / projectId / projectName / updatedAt | ~/.xiaobao/active-project.json |
0600 |
| User config（可选） | 覆盖 authBase / apiBase / scopes | ~/.xiaobao/config.json |
0600 |
| Pending auth（临时） | --no-wait split-flow 进行中的 device_code / user_code / 过期时间 |
~/.xiaobao/pending-auth.json |
0600 |
pending-auth.json 是 split-flow 的临时凭据中转：--no-wait 写入、--resume
成功换到 token 后删除，auth logout 或 device_code 过期时也会清掉。device_code
属凭据级数据，只落本地文件、绝不进 stdout / agent 上下文。
~/.openclaw/state/wangxiaobao/ fallback（向后兼容 openclaw-xiaobao plugin 用户）
读 token / active-project 时如果 ~/.xiaobao/ 没有，会自动 fallback 读
~/.openclaw/state/wangxiaobao/{token,active-project}.json。这是 plugin 用户
迁移到 CLI 的零摩擦机制：装上 CLI 直接 auth whoami / project current
就有数据，不用重新登录 / 重新选项目。
写操作（login / logout / project use）永远写到 ~/.xiaobao/，不动
openclaw 的副本（保留 plugin session 完整性）。auth logout 例外 ——
会主动清掉两边的 token，否则 fallback 读 legacy 会让"登出后 whoami 仍显示已登录"。
数据权限隔离
audio list / customer list / visit list / visit summary / focus list /
resistance list / consultant list / qa / quantum / follow * / portrait * / beautx * 所有业务命令的后端都按当前登录用户的授权范围过滤数据:
- 普通顾问：只看自己名下
- 团队长：看本团队
- 项目管理员：看本项目全部
total: 0 不一定是"没数据"，也可能是当前账号无权访问。看不到的客户 / 顾问
不是 bug，是设计如此。要扩权限找管理员。
例外 —— kb *（知识库）是项目级隔离：kb search / kb docs 按当前激活项目（estate）
返回该项目知识，不按顾问授权范围细分；kb doc / kb doc-content 按 docId 直取。
知识库面向全项目，不存在"看不到别人名下"的概念。
本地工具 —— date * 不走网络：date now/today/yesterday/weekday/add/diff/range today|yesterday|this-week|this-month|last-7-days|today-so-far
纯本地计算（默认时区 Asia/Shanghai）。所有需要时间窗的命令（visit/follow/quantum/portrait…）先用它取 from/to，
禁止凭记忆推算日期。
例外 —— admin *（super-admin 经营报表）：admin sales-report / admin token-usage
是公司级数据（经营出库/回款、LLM token 用量），不需要激活项目，且走独立白名单
（与上面按顾问授权的隔离无关；名单为空 = 全拒）。不在名单会收到
data: "不在白名单中，若有需求请联系19136123281" —— 原样转告用户并停止，不要重试。
> 后端链路：上述命令统一经 ai-open（公网开放层 / 鉴权）代理到内网业务层
> wang-ai-mcp，对调用方透明，命令用法不变。
时间格式
所有 --from / --to 用 yyyy-MM-dd HH:mm:ss（空格分隔，不带时区）。
ISO 8601 形式 2026-05-12T00:00:00+08:00 也支持，CLI 内部转换为空格形式。
时区按服务端默认（中国时区）解释，不要在 prompt 里手动换算。
generic api 命令
xiaobao-cli api <METHOD> <PATH> 是 escape hatch：调任意 wangxiaobao endpoint。
默认从 active-project 自动注入 X-Tenant-Id / X-Project-Id 等 4 个 headers
（跟 dedicated 命令一致）；要 opt-out 加 --no-default-headers。
# 跟 `consultant list` 等价（自动注入 tenant/project headers）
xiaobao-cli api GET /ai-open/consultants
# 调不需要 tenant 上下文的端点
xiaobao-cli api GET /saas/v2/estate/tenant-and-estate/by-user-id --no-default-headers
# POST + body
xiaobao-cli api POST /ai-open/audio/page --body '{"fromDate":"...","toDate":"..."}'
切勿在 prompt / agent 上下文里贴 token
access_token / refresh_token 是凭据，泄露到对话 / 公开仓库 / 截图都是事故。
agent 永远不要 cat ~/.xiaobao/token.json 打印给用户看。要查身份用
xiaobao-cli auth whoami（只显示 user info + expires，不显示 token 本身）。
