@puyinkai/xiaobao-cli 0.1.0 → 0.1.8

package/skills/wangxiaobao-shared/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: wangxiaobao-shared
+version: 0.1.0
+description: "旺小宝 CLI 共享规则：安装方式（npm / npx），认证（OAuth device flow），激活项目，全局 flags（--format json/toon），输出协议（stdout JSON / stderr 错误 / exit code），错误码语义（NO_ACTIVE_PROJECT / NOT_AUTHENTICATED 含 hint 字段），权限隔离原则，token / active-project 文件位置（含 ~/.openclaw fallback）。任何旺小宝 skill 在执行命令前应先用 Read tool 读取本文件 —— 它定义了所有 xiaobao-cli 命令共享的前置约定。"
+metadata:
+  requires:
+    bins: ["xiaobao-cli"]
+  cliHelp: "xiaobao-cli --help"
+---
+
+# 旺小宝 CLI 共享规则
+
+本 skill 定义所有 `xiaobao-cli` 命令通用的前置约束 + 协议，**其他旺小宝 skill
+开始执行前 MUST 先用 Read tool 完整读取本文件**。
+
+## 安装
+
+```bash
+# 全局安装（推荐，长期用）
+npm install -g @puyinkai/xiaobao-cli
+
+# 或一次性用（不污染全局）
+npx -y @puyinkai/xiaobao-cli <subcommand>...
+```
+
+装好后 `xiaobao-cli --version` 应返回 `0.1.x`。Node 22+。
+
+## 三步走基础流程
+
+任何 xiaobao-cli 命令的**前置 3 步**：
+
+```bash
+# 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`** —— 它会阻塞轮询、卡满一整轮对话。
+
+```bash
+# 步骤 A：发起，立即返回（约 0.5s），拿到 verification_uri
+xiaobao-cli auth login --no-wait
+# stdout: { "awaiting_authorization": true, "verification_uri": "...",
+#           "user_code": "...", "expires_in": 300, "interval": 5, ... }
+# device_code 不在 stdout —— 已安全存到 ~/.xiaobao/pending-auth.json（0600）
+```
+
+agent 拿到后：把 `verification_uri` **原样**发给用户（放进只含 URL 的代码块，
+不要改写不要做 URL 编码），让用户浏览器打开授权，然后**结束本轮**，把控制权
+交还用户。
+
+```bash
+# 步骤 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。
+
+查身份 / 当前激活项目（任何时候都可以）：
+
+```bash
+xiaobao-cli auth whoami       # 显示 logged_in + user 信息 + token 剩余有效期
+xiaobao-cli project current   # 显示当前激活的 tenant/project + updatedAt
+```
+
+## 输出协议
+
+所有命令统一协议:
+
+| 流 | 内容 |
+| --- | --- |
+| **stdout** | 结果 / 错误对象，**JSON 格式**（默认）或 TOON 格式（`--format toon`），都是有效 JSON / 可机器解析 |
+| **stderr** | 进度 / 人类友好错误提示 / verification URL 等。Agent 一般忽略 |
+| **exit code** | 0 = 成功；非 0 = 失败（业务错误 / 参数错 / 网络错） |
+
+Agent 消费时**只 parse stdout JSON**，stderr 是辅助。
+
+### `--format` 全局 flag
+
+| 值 | 用途 |
+| --- | --- |
+| `json`（默认） | pretty JSON，agent / 人类都能读 |
+| `toon` | TOON 格式，uniform array of objects 省 30-50% token（LLM 上下文优化） |
+
+## 错误对象结构
+
+失败时 stdout 输出结构化错误（仍是合法 JSON，agent 直接 parse）:
+
+```json
+{
+  "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_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` / `focus list` / `resistance list` /
+`consultant list` 所有业务命令的后端都按**当前登录用户的授权范围**过滤数据:
+
+- 普通顾问：只看自己名下
+- 团队长：看本团队
+- 项目管理员：看本项目全部
+
+`total: 0` 不一定是"没数据"，也可能是**当前账号无权访问**。看不到的客户 / 顾问
+不是 bug，是设计如此。要扩权限找管理员。
+
+## 时间格式
+
+所有 `--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`。
+
+```bash
+# 跟 `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 本身）。

package/skills/wangxiaobao-switch-project/SKILL.md

@@ -1,65 +1,27 @@
 ---
 name: wangxiaobao-switch-project
-description: |
-  查询和切换旺小宝项目。展开当前账号下所有租户与项目，让用户选择，然后调
-  `xiaobao_switch_project` tool 把选中条目持久化到 plugin 全局激活项目状态文件
-  `~/.openclaw/state/wangxiaobao/active-project.json`（权限 0600）。后续所有
-  需要 tenant/project 上下文的 tool（list-audio / quick-qa 等）
-  都从这个文件读取，**不再需要传 tenantId/projectId 入参**。
-
-  **当以下情况时使用此 Skill**:
-  (1) 用户提到"切换项目"、"选项目"、"换项目"、"项目列表"、"选择租户和项目"
-  (2) 任意 tool 返回 `error: 'NO_ACTIVE_PROJECT'` —— 这是 plugin 的标准
-      未激活信号，要求重新走切换项目流程
-  (3) 用户准备同步录音 / 出报告 / 调旺小宝租户隔离 API，但还没设置过激活项目
-  (4) 用户想看自己有权限访问哪些租户和项目
-  (5) 用户直接点名某个项目（"切到XX项目"）—— 带 keyword 精确收敛后再确认
+version: 0.1.0
+description: "旺小宝多租户/项目切换。列出当前账号有权限的租户与项目（可按 keyword 模糊过滤收敛），让用户选择后激活到 ~/.xiaobao/active-project.json（0600）；后续所有 xiaobao-cli 命令从该文件读 tenant/project 上下文，不再需要传 tenantId/projectId 入参。高频命令: xiaobao-cli project list [--keyword <kw>]、xiaobao-cli project use --tenant-id ... --tenant-name ... --project-id ... --project-name ...。何时用：用户说切项目/选项目/换项目/项目列表/切到 XX 项目；任意 xiaobao-cli 命令返回 NO_ACTIVE_PROJECT 错误；用户准备查录音/客户/来访但还没设激活项目；用户想看自己有权限访问哪些租户和项目。"
+metadata:
+  requires:
+    bins: ["xiaobao-cli"]
+  cliHelp: "xiaobao-cli project --help"
 ---
 
-> **Host-agnostic CLI skill** — 本 skill 假设 `xiaobao-cli` 已装到 PATH
-> (`npm i -g @puyinkai/xiaobao-cli` 或 `npx -y @puyinkai/xiaobao-cli`)。
-> Agent 通过 shell 工具（Bash / Run / Shell）执行命令、读 **stdout JSON** 消费；
-> stderr 是进度/错误提示。退出码 0 = 成功，非 0 = 业务/网络错（错误对象同时打到 stdout 可解析）。
->
-> CLI 14 个子命令跟 openclaw-xiaobao plugin 14 个 tool **1:1 等价**，返回 JSON
-> 结构完全一致（`{status, ok, data: {...}}`）。skill 里看到的 `resp.data.data.xxx`
-> 取数路径直接对 stdout JSON 用 `jq` / `JSON.parse` 即可。
->
-> **plugin tool → CLI 命令翻译表（数组参数走逗号分隔）**：
->
-> | plugin tool | CLI 命令 |
-> | --- | --- |
-> | `xiaobao_authorize { force? }` | `xiaobao-cli auth login [--force]` |
-> | `xiaobao_whoami` | `xiaobao-cli auth whoami` |
-> | `xiaobao_logout` | `xiaobao-cli auth logout` |
-> | `xiaobao_list_projects { keyword? }` | `xiaobao-cli project list [--keyword <kw>]` |
-> | `xiaobao_switch_project { tenantId, tenantName, projectId, projectName }` | `xiaobao-cli project use --tenant-id ... --tenant-name ... --project-id ... --project-name ...` |
-> | `xiaobao_list_consultants` | `xiaobao-cli consultant list` |
-> | `xiaobao_list_audio { fromDate, toDate, userId?, userIdList?, page, size }` | `xiaobao-cli audio list --from "..." --to "..." [--user-id ...] [--user-id-list a,b,c] [--page N] [--size N]` |
-> | `xiaobao_get_audio_text { audioId }` | `xiaobao-cli audio text <audioId>` |
-> | `xiaobao_list_customers { ... }` | `xiaobao-cli customer list [--user-id] [--user-name] [--customer-name] [--customer-phone] [--portrait] [--from] [--to] [--page] [--size]` |
-> | `xiaobao_list_visits { ... }` | `xiaobao-cli visit list [--customer-id] [--customer-name] [--from] [--to] [--page] [--size]` |
-> | `xiaobao_list_customer_focus { visitIds, customerIds, audioIds, category, classification, fromDate, toDate, ... }` | `xiaobao-cli focus list [--visit-ids a,b] [--customer-ids a,b] [--audio-ids a,b] [--category ...] [--classification ...] [--from ...] [--to ...]` |
-> | `xiaobao_list_customer_resistance { ... }` | `xiaobao-cli resistance list [同 focus]` |
-> | `xiaobao_quick_qa { prompt, threadId? }` | `xiaobao-cli qa "<prompt>" [--thread-id ...]` |
-> | `xiaobao_api { method, path, query, body, headers }` | `xiaobao-cli api <METHOD> <PATH> [--query k=v] [--body '<json>'] [--headers k=v]` |
->
-> 用 `--format toon` 切到 TOON（uniform 数组省 30-50% token，LLM 上下文优化）；
-> 用 `--format json`（默认）保持 JSON。state 路径：`~/.xiaobao/`（fallback 读 `~/.openclaw/state/wangxiaobao/`）。
-
-
 # 旺小宝项目切换
 
+> **CRITICAL** —— 跑命令前 MUST 先用 Read tool 读取 [`../wangxiaobao-shared/SKILL.md`](../wangxiaobao-shared/SKILL.md)（一份共享文档讲清安装 / 登录 / 选项目 / 错误码 / 输出协议等所有 xiaobao-cli 命令通用的前置约定）。
+
 把当前账号下的「租户 + 项目」枚举出来让用户挑一个，确认后调
-`xiaobao_switch_project` tool 写入 plugin 全局状态文件，供后续 tool 读取。
+`xiaobao-cli project use` 写入 CLI 全局状态文件，供后续 命令 读取。
 
 ## 执行前必读
 
-- 必须先通过 `xiaobao_authorize` 完成 OAuth 登录；token 没拿到时本 skill 不能继续
+- 必须先通过 `xiaobao-cli auth login` 完成 OAuth 登录；token 没拿到时本 skill 不能继续
 - **不要**自己 fs.writeFile 写 `.env` 或任何文件——状态落地走
-  `xiaobao_switch_project` tool，由 plugin 统一管理权限和路径
+  `xiaobao-cli project use`，由 CLI 统一管理权限和路径
 - 多个项目时**必须让用户挑**，绝对不要自动选择第一个；只有一个项目时才可以自动选
-- 用户确认前不要调 switch-project tool
+- 用户确认前不要跑 wangxiaobao-switch-project skill
 
 ---
 
@@ -67,14 +29,16 @@ description: |
 
 ### 第 1 步：拿到项目列表
 
-调用 plugin tool `xiaobao_list_projects`。**可选 `keyword` 参数**对租户名/
-项目名做包含模糊过滤（大小写不敏感）：
+跑命令 `xiaobao-cli project list`，可选 `--keyword <kw>` 对租户名/项目名做
+包含模糊过滤（大小写不敏感）：
 
-- 用户已经说了想要哪个项目（如"切到盛世禧悦"）→ **直接带 `keyword`**：
-  `xiaobao_list_projects { keyword: "盛世禧悦" }`，收敛后通常只剩 1-2 条，
-  省去让用户从一长串里挑
-- 用户只说"换个项目""看看有哪些" → 不带 keyword，拉全量
-- 账号项目很多、全量列表太长 → 提示用户给个关键字，再带 `keyword` 重查
+- 用户已经说了想要哪个项目（如"切到盛世禧悦"）→ **直接带 `--keyword`**：
+  ```bash
+  xiaobao-cli project list --keyword 盛世禧悦
+  ```
+  收敛后通常只剩 1-2 条，省去让用户从一长串里挑
+- 用户只说"换个项目""看看有哪些" → 不带 `--keyword`，拉全量
+- 账号项目很多、全量列表太长 → 提示用户给个关键字，再带 `--keyword` 重查
 
 返回结构：
 ```json
@@ -90,11 +54,11 @@ description: |
 
 如果 `count == 0`：
 
-- **带了 `keyword`** → 是关键字没命中，不是没权限。提示用户换更短的关键字、
+- **带了 `--keyword`** → 是关键字没命中，不是没权限。提示用户换更短的关键字、
   或不带 keyword 看全量；**不要**直接说"没有项目"
-- **没带 `keyword`** → 账号确实没有可访问的项目，结束
+- **没带 `--keyword`** → 账号确实没有可访问的项目，结束
 
-如果 tool 报错（401 / token 过期等），先调 `xiaobao_authorize { force: true }` 重新登录，再重试一次。
+如果 命令 报错（401 / token 过期等），先调 `xiaobao-cli auth login --force` 重新登录，再重试一次。
 
 ### 第 2 步：展示并让用户选
 
@@ -110,21 +74,20 @@ description: |
 ```
 
 - **多个项目**：让用户回复编号或项目名。用户回复后，**再显示一次「即将激活的
-  租户/项目信息」并请用户确认 y/n**，确认后才调 `xiaobao_switch_project` tool
+  租户/项目信息」并请用户确认 y/n**，确认后才跑 `xiaobao-cli project use`
 - **仅一个项目**：直接告诉用户"账号下只有一个项目 X，是否激活？"等用户确认即可
 
-### 第 3 步：调 `xiaobao_switch_project` tool 落地
+### 第 3 步：跑 `xiaobao-cli project use` 落地
 
-```json
-{
-  "tenantId":    "<选中条目的 tenantId>",
-  "tenantName":  "<选中条目的 tenantName>",
-  "projectId":   "<选中条目的 projectId>",
-  "projectName": "<选中条目的 projectName>"
-}
+```bash
+xiaobao-cli project use \
+  --tenant-id   "<选中条目的 tenantId>" \
+  --tenant-name "<选中条目的 tenantName>" \
+  --project-id  "<选中条目的 projectId>" \
+  --project-name "<选中条目的 projectName>"
 ```
 
-成功返回：
+4 个 flag 都是必填。成功 stdout 返回：
 
 ```json
 {
@@ -140,7 +103,7 @@ description: |
 }
 ```
 
-状态写到 `~/.openclaw/state/wangxiaobao/active-project.json`，权限 0600。
+状态写到 `~/.xiaobao/active-project.json`，权限 0600。
 
 ---
 
@@ -152,7 +115,7 @@ description: |
 ✅ 已切换到「示例租户A / 示例项目甲」
 租户 ID: 1234
 项目 ID: 9001
-状态保存在 ~/.openclaw/state/wangxiaobao/active-project.json
+状态保存在 ~/.xiaobao/active-project.json
 
 下一步可以：
 - 查录音：让我帮你跑 wangxiaobao-audio-query / wangxiaobao-audio-wiki skill
@@ -161,10 +124,21 @@ description: |
 
 ---
 
-## 仅查看不切换
+## 仅查看 / 查当前激活
+
+| 场景 | 命令 |
+| --- | --- |
+| 看自己有哪些项目可选 | `xiaobao-cli project list` （必要时带 `--keyword <kw>` 收敛） |
+| **查当前激活的是哪个项目** | `xiaobao-cli project current` |
+| 切到新项目 | 走「流程」三步 |
+
+`project current` 直接读 `~/.xiaobao/active-project.json`（fallback
+`~/.openclaw/state/wangxiaobao/active-project.json`），返回当前激活的
+tenant/project + `updatedAt`。如果用户问"现在是哪个项目""当前激活的是啥"，
+**优先**用 `project current`，不要全量 `project list` 再让用户辨认。
 
-用户只想"看看有哪些项目"而**不切换**时，调 `xiaobao_list_projects`（必要时带
-`keyword` 收敛）渲染列表后停下来，不要调 `xiaobao_switch_project` tool。
+没激活过时 `project current` 返 `NO_ACTIVE_PROJECT` 错（同时 stdout 含
+`hint` 字段告诉怎么激活）。
 
 ---
 
@@ -172,8 +146,8 @@ description: |
 
 | 错误现象 | 根本原因 | 解决方案 |
 |---|---|---|
-| `xiaobao_list_projects` 返回 401 / token 过期 | 没登录或 refresh 失败 | 调 `xiaobao_authorize { force: true }` 重新走 device flow |
+| `xiaobao-cli project list` 返回 401 / token 过期 | 没登录或 refresh 失败 | 调 `xiaobao-cli auth login --force` 重新走 device flow |
 | `count == 0`（没带 keyword） | 账号无任何租户/项目权限 | 让用户找管理员加权限，本 skill 不继续 |
 | `count == 0`（带了 keyword） | 关键字没匹配到任何项目 | 换更短关键字 / 不带 keyword 看全量，别直接说"没项目" |
 | 用户输入的编号超出范围 | 选错了 | 重新提示当前可选编号区间 |
-| 其他 tool 仍返回 `NO_ACTIVE_PROJECT` | 没调 switch-project tool 落地 | 检查 `~/.openclaw/state/wangxiaobao/active-project.json` 是否存在，重新走本 skill |
+| 其他 命令 仍返回 `NO_ACTIVE_PROJECT` | 没跑 wangxiaobao-switch-project skill 落地 | 检查 `~/.xiaobao/active-project.json` 是否存在，重新走本 skill |

package/skills/wangxiaobao-visit-query/SKILL.md

@@ -1,83 +1,38 @@
 ---
 name: wangxiaobao-visit-query
-description: |
-  旺小宝来访分页查询 skill：按 **客户 ID / 客户姓名 / 来访时间** 分页查
-  来访记录（含接待顾问 / **录音列表 audios** / 盘客状态 / 话术命中等）。
-  **只读、不写文件、无副作用**。对应 `xiaobao_list_visits` tool。
-  排序固定 visit_time DESC。每条 visit 已直接带录音列表，问"这次来访打了
-  几条录音 / 录音多长"时**不必再调** `xiaobao_list_audio`。
-
-  **当以下情况时使用此 Skill**:
-  (1) 用户问"今天到访"、"本周来访列表"、"最近来访"
-  (2) 用户问"李女士最近几次来访"——**先调 `xiaobao_list_customers` 反查
-      customerId（wang_id），再调本 skill 带 customerId 精确过滤**（更准）
-  (3) 用户问"上周哪些客户来访"——`fromDate` / `toDate` 时间窗
-  (4) 用户问"姓张的客户什么时候来过"——`customerName` 模糊（后端 JOIN 客户表）
-  (5) 用户问"某次到访打了几条录音 / 录音多长 / 录音 fileUrl"——看
-      `audioCount` + `audios[]`（直接包含录音元数据 + 签名 URL）；
-      "盘客完成没"——看 `isPankeCompleted` / `pankeStatus`
-  (6) 任何"看到访名单 / 接待记录 / 话术命中"的开放式查询
-
-  **不要用本 skill 的场景**：
-  - 用户要的是客户**画像** / 标签 → 走 `wangxiaobao-customer-query`
-  - 用户问录音元数据 / 文本 → 走 `wangxiaobao-audio-query`
+version: 0.1.0
+description: "旺小宝客户来访分页查询：按 客户 ID / 客户姓名（模糊触发后端 JOIN）/ 来访时间窗 过滤，排序固定 visit_time DESC。每条 visit 直接带 audios 录音列表（含 audioId / fileId / startTime / duration / 签名 fileUrl），问这次来访打了几条录音 / 录音多长 / fileUrl 时不必再调 audio list。只读、不写文件、无副作用。高频命令: xiaobao-cli visit list [--customer-id <id>] [--customer-name <n>] [--from <date>] [--to <date>] [--page N] [--size N]。何时用：用户问今天到访/本周来访列表/最近来访/某客户最近几次来访/上周哪些客户来访/姓张客户什么时候来过/某次到访打了几条录音/录音 fileUrl/盘客完成没；任何看到访名单/接待记录/话术命中的开放式查询。注：customer-id 比 customer-name 精确，先用 xiaobao-cli customer list 反查 wang_id；要客户画像走 customer-query；要录音元数据走 audio-query。"
+metadata:
+  requires:
+    bins: ["xiaobao-cli"]
+  cliHelp: "xiaobao-cli visit --help"
 ---
 
-> **Host-agnostic CLI skill** — 本 skill 假设 `xiaobao-cli` 已装到 PATH
-> (`npm i -g @puyinkai/xiaobao-cli` 或 `npx -y @puyinkai/xiaobao-cli`)。
-> Agent 通过 shell 工具（Bash / Run / Shell）执行命令、读 **stdout JSON** 消费；
-> stderr 是进度/错误提示。退出码 0 = 成功，非 0 = 业务/网络错（错误对象同时打到 stdout 可解析）。
->
-> CLI 14 个子命令跟 openclaw-xiaobao plugin 14 个 tool **1:1 等价**，返回 JSON
-> 结构完全一致（`{status, ok, data: {...}}`）。skill 里看到的 `resp.data.data.xxx`
-> 取数路径直接对 stdout JSON 用 `jq` / `JSON.parse` 即可。
->
-> **plugin tool → CLI 命令翻译表（数组参数走逗号分隔）**：
->
-> | plugin tool | CLI 命令 |
-> | --- | --- |
-> | `xiaobao_authorize { force? }` | `xiaobao-cli auth login [--force]` |
-> | `xiaobao_whoami` | `xiaobao-cli auth whoami` |
-> | `xiaobao_logout` | `xiaobao-cli auth logout` |
-> | `xiaobao_list_projects { keyword? }` | `xiaobao-cli project list [--keyword <kw>]` |
-> | `xiaobao_switch_project { tenantId, tenantName, projectId, projectName }` | `xiaobao-cli project use --tenant-id ... --tenant-name ... --project-id ... --project-name ...` |
-> | `xiaobao_list_consultants` | `xiaobao-cli consultant list` |
-> | `xiaobao_list_audio { fromDate, toDate, userId?, userIdList?, page, size }` | `xiaobao-cli audio list --from "..." --to "..." [--user-id ...] [--user-id-list a,b,c] [--page N] [--size N]` |
-> | `xiaobao_get_audio_text { audioId }` | `xiaobao-cli audio text <audioId>` |
-> | `xiaobao_list_customers { ... }` | `xiaobao-cli customer list [--user-id] [--user-name] [--customer-name] [--customer-phone] [--portrait] [--from] [--to] [--page] [--size]` |
-> | `xiaobao_list_visits { ... }` | `xiaobao-cli visit list [--customer-id] [--customer-name] [--from] [--to] [--page] [--size]` |
-> | `xiaobao_list_customer_focus { visitIds, customerIds, audioIds, category, classification, fromDate, toDate, ... }` | `xiaobao-cli focus list [--visit-ids a,b] [--customer-ids a,b] [--audio-ids a,b] [--category ...] [--classification ...] [--from ...] [--to ...]` |
-> | `xiaobao_list_customer_resistance { ... }` | `xiaobao-cli resistance list [同 focus]` |
-> | `xiaobao_quick_qa { prompt, threadId? }` | `xiaobao-cli qa "<prompt>" [--thread-id ...]` |
-> | `xiaobao_api { method, path, query, body, headers }` | `xiaobao-cli api <METHOD> <PATH> [--query k=v] [--body '<json>'] [--headers k=v]` |
->
-> 用 `--format toon` 切到 TOON（uniform 数组省 30-50% token，LLM 上下文优化）；
-> 用 `--format json`（默认）保持 JSON。state 路径：`~/.xiaobao/`（fallback 读 `~/.openclaw/state/wangxiaobao/`）。
-
-
 # 旺小宝来访分页查询
 
-调 `xiaobao_list_visits` tool 查当前激活项目的来访记录。
+> **CRITICAL** —— 跑命令前 MUST 先用 Read tool 读取 [`../wangxiaobao-shared/SKILL.md`](../wangxiaobao-shared/SKILL.md)（一份共享文档讲清安装 / 登录 / 选项目 / 错误码 / 输出协议等所有 xiaobao-cli 命令通用的前置约定）。
+
+跑 `xiaobao-cli visit list` 查当前激活项目的来访记录。
 
 ## 执行前必读
 
-- 必须有有效 token：先调 `xiaobao_whoami`；未登录就 `xiaobao_authorize`
-- **必须有激活项目**：tool 内部自动读，缺失返回 `NO_ACTIVE_PROJECT`
+- 必须有有效 token：先调 `xiaobao-cli auth whoami`；未登录就 `xiaobao-cli auth login`
+- **必须有激活项目**：命令内部自动读，缺失返回 `NO_ACTIVE_PROJECT`
 - **数据权限隔离**：跟客户接口一样，按当前用户授权可见顾问范围过滤
-- LocalDateTime 格式：`yyyy-MM-dd HH:mm:ss`（空格分隔），plugin 自动转
+- LocalDateTime 格式：`yyyy-MM-dd HH:mm:ss`（空格分隔），CLI 自动转
 - **不要**写文件、出报告
 
 ---
 
 ## 快速索引：意图 → 工具
 
-| 用户意图                       | plugin tool             | 关键参数                                |
+| 用户意图                       | 命令             | 关键参数                                |
 | ------------------------------ | ----------------------- | --------------------------------------- |
-| 列时间窗内的全部来访           | `xiaobao_list_visits`   | `fromDate` / `toDate`                   |
-| 看某客户的来访历史             | `xiaobao_list_customers` → `xiaobao_list_visits` | `customerId: <反查的 wang_id>` |
-| 按客户名字模糊找来访           | `xiaobao_list_visits`   | `customerName: "张"`                    |
-| **看某次来访的录音详情**       | `xiaobao_list_visits`   | 直接读返回里的 `audios[]`（含 fileUrl） |
-| 估算总数                       | `xiaobao_list_visits`   | `page: 1, size: 1`，只读 `total`        |
+| 列时间窗内的全部来访           | `xiaobao-cli visit list`   | `--from` / `--to`                   |
+| 看某客户的来访历史             | `xiaobao-cli customer list` → `xiaobao-cli visit list` | `--customer-id 反查的 wang_id` |
+| 按客户名字模糊找来访           | `xiaobao-cli visit list`   | `--customer-name 张`                    |
+| **看某次来访的录音详情**       | `xiaobao-cli visit list`   | 直接读返回里的 `audios[]`（含 fileUrl） |
+| 估算总数                       | `xiaobao-cli visit list`   | `--page 1 --size 1`，只读 `total`        |
 
 ---
 
@@ -87,10 +42,10 @@ description: |
 
 用户说"李女士最近几次来访"——**优先**走两步：
 
-1. 调 `xiaobao_list_customers { customerName: "李女士" }` 反查到 `customerId`
-2. 调 `xiaobao_list_visits { customerId: <wang_id> }` 拿来访历史
+1. 调 `xiaobao-cli customer list { customerName: "李女士" }` 反查到 `--customer-id`
+2. 调 `xiaobao-cli visit list { customerId: <wang_id> }` 拿来访历史
 
-直接传 `customerName` 也能用（后端 JOIN customer_profile 模糊匹配），但：
+直接传 `--customer-name` 也能用（后端 JOIN customer_profile 模糊匹配），但：
 - 同名客户可能有多个（重名 "李女士"），结果混在一起不好辨认
 - JOIN 慢于纯 visit 表查询
 
@@ -152,7 +107,7 @@ description: |
 }
 ```
 
-plugin tool 又外包一层 → `resp.data.data.content`。
+CLI 又包一层 → `resp.data.data.content`。
 
 `requireSpeechHitDetail` / `salesSpeechHitDetail` 是 JSON 文本，**默认不展示给用户**
 （除非用户明确问"具体哪条话术命中了"）。
@@ -167,7 +122,7 @@ plugin tool 又外包一层 → `resp.data.data.content`。
 - 客户重新分配过
 
 用户问"张三接待了几个"——按 `userId == 张三`；问"张三名下客户来访"——按 `belongUserId == 张三`
-（**但本 tool 当前不支持按 belongUserId 过滤**，需先用 customers 反查再 customerId 过滤）。
+（**但本 命令当前不支持按 belongUserId 过滤**，需先用 customers 反查再 customerId 过滤）。
 
 ---
 
@@ -175,8 +130,8 @@ plugin tool 又外包一层 → `resp.data.data.content`。
 
 ### 场景 1：今天到访列表
 
-```jsonc
-{ "fromDate": "2026-05-13 00:00:00", "toDate": "2026-05-14 00:00:00" }
+```bash
+xiaobao-cli visit list --from "2026-05-13 00:00:00" --to "2026-05-14 00:00:00"
 ```
 
 渲染：
@@ -190,40 +145,38 @@ plugin tool 又外包一层 → `resp.data.data.content`。
 
 ### 场景 2：李女士最近 3 次来访
 
-```jsonc
-// step 1: 反查 wang_id
-// xiaobao_list_customers
-{ "customerName": "李女士", "size": 20 }
+```bash
+# step 1: 反查 wang_id
+xiaobao-cli customer list --customer-name 李女士 --size 20
 
-// step 2: 假设找到 customerId = 270072120829026305
-// xiaobao_list_visits
-{ "customerId": "270072120829026305", "page": 1, "size": 3 }
+# step 2: 假设找到 customerId = 270072120829026305
+xiaobao-cli visit list --customer-id 270072120829026305 --page 1 --size 3
 ```
 
 ### 场景 3：上周末来访高峰
 
-```jsonc
-{ "fromDate": "2026-05-10 00:00:00", "toDate": "2026-05-12 00:00:00", "page": 1, "size": 50 }
+```bash
+xiaobao-cli visit list --from "2026-05-10 00:00:00" --to "2026-05-12 00:00:00" --page 1 --size 50
 ```
 
 后处理：按 hour 聚合 → 报告"周日下午 14-16 点是峰值"。
 
 ### 场景 4：用客户名直接模糊
 
-```jsonc
-// 不知道具体客户 ID，先用名字模糊
-{ "customerName": "张", "fromDate": "2026-05-01 00:00:00", "size": 20 }
+```bash
+# 不知道具体客户 ID，先用名字模糊
+xiaobao-cli visit list --customer-name 张 --from "2026-05-01 00:00:00" --size 20
 ```
 
 回复："姓张的客户 5 月来访共 8 次，分布在 3 位客户：张先生(133****0692) 来 3 次..."
 
 ### 场景 5：直接看某次到访的录音详情
 
-```jsonc
-{ "customerId": "1685535452481236993", "page": 1, "size": 5 }
+```bash
+xiaobao-cli visit list --customer-id 1685535452481236993 --page 1 --size 5
 ```
 
-每条 visit 已带 `audios[]`，**不必再调** `xiaobao_list_audio`：
+每条 visit 已带 `audios[]`，**不必再调** `xiaobao-cli audio list`：
 
 ```
 屈哥 · 2023-07-30 14:01:03 · 接待:兰鸿建 · 12 分 · 3 条录音：
@@ -233,7 +186,7 @@ plugin tool 又外包一层 → `resp.data.data.content`。
   3. audioId=9003 · 14:12:00 ~ 14:15:30 · 3 分 · 状态:分析完成
 ```
 
-> 想看某条录音的**转录文本**还是要单独调 `xiaobao_get_audio_text`，
+> 想看某条录音的**转录文本**还是要单独调 `xiaobao-cli audio text`，
 > `audios[]` 里只有元数据 + 签名 URL，没有 transcript。
 
 ---
@@ -241,9 +194,9 @@ plugin tool 又外包一层 → `resp.data.data.content`。
 ## 常见错误与排查
 
 - **`error: 'NO_ACTIVE_PROJECT'`** — 跑 `wangxiaobao-switch-project` skill
-- **401 / token 过期** — 调 `xiaobao_authorize { force: true }` 重登
+- **401 / token 过期** — 调 `xiaobao-cli auth login --force` 重登
 - **`total: 0`** — 时间窗内确实没数据，或当前用户授权范围内没有匹配的接待顾问
 - **customerName 模糊但没匹到** — 客户名拼写差异（"李女士" vs "李小姐"）；
-  改用 `xiaobao_list_customers` 反查精确 customerId
+  改用 `xiaobao-cli customer list` 反查精确 customerId
 - **接待顾问跟归属顾问不一致** — 正常业务情况（同事代接待），不是 bug；
   必要时跟用户解释