@puyinkai/xiaobao-cli 0.1.0

package/dist/qa-D-B9FV9W.mjs

@@ -0,0 +1,60 @@
+import { a as resolveConfig } from "./device-flow-BgsZipYA.mjs";
+import { t as xbApiFetch } from "./api-client-DwySN6x-.mjs";
+import { n as writeResult, t as writeError } from "./format-BZvv8lYc.mjs";
+import { t as requireActiveProject } from "./project-store-Bz5kf-EI.mjs";
+import { t as tenantProjectHeaders } from "./headers-D79npewp.mjs";
+import { defineCommand } from "citty";
+//#region src/commands/qa.ts
+/**
+* `xiaobao-cli qa <prompt>` — 旺小宝业务数据问数.
+*
+* Natural-language Q&A over the active project's data — customers / visits /
+* 挖需率 / 销冠 / 录音覆盖率 / KPIs. Wraps POST /ai-open/langchain/quick-qa/query.
+*
+* Multi-turn: pass back the `thread_id` from previous response via --thread-id
+* for follow-ups. Timeout 30 min (backend can run long multi-step data lookups).
+*/
+var qa_default = defineCommand({
+	meta: {
+		name: "qa",
+		description: "业务数据问数（自然语言）— 客户 / 来访 / 挖需率 / 销冠 / 录音覆盖率 等"
+	},
+	args: {
+		prompt: {
+			type: "positional",
+			required: true,
+			description: "用户问题文本"
+		},
+		"thread-id": {
+			type: "string",
+			description: "多轮 thread id；不传走 stateless run"
+		},
+		"api-base": { type: "string" },
+		"auth-base": { type: "string" },
+		format: {
+			type: "string",
+			default: "json"
+		}
+	},
+	async run({ args }) {
+		try {
+			const config = resolveConfig({
+				apiBase: args["api-base"],
+				authBase: args["auth-base"]
+			});
+			const active = await requireActiveProject();
+			const body = { prompt: String(args.prompt) };
+			if (args["thread-id"]) body.thread_id = args["thread-id"];
+			writeResult(await xbApiFetch(config, "POST", "/ai-open/langchain/quick-qa/query", {
+				headers: tenantProjectHeaders(active),
+				body,
+				timeoutMs: 18e5
+			}), args.format);
+		} catch (err) {
+			writeError(err, args.format);
+			process.exit(1);
+		}
+	}
+});
+//#endregion
+export { qa_default as default };

package/dist/resistance-Cf7zsdB3.mjs

@@ -0,0 +1,11 @@
+import { defineCommand } from "citty";
+//#region src/commands/resistance/index.ts
+var resistance_default = defineCommand({
+	meta: {
+		name: "resistance",
+		description: "客户抗性点标签分页查询"
+	},
+	subCommands: { list: () => import("./list-CzB9_Jho.mjs").then((m) => m.default) }
+});
+//#endregion
+export { resistance_default as default };

package/dist/text-BLH4R3xv.mjs

@@ -0,0 +1,49 @@
+import { a as resolveConfig } from "./device-flow-BgsZipYA.mjs";
+import { t as xbApiFetch } from "./api-client-DwySN6x-.mjs";
+import { n as writeResult, t as writeError } from "./format-BZvv8lYc.mjs";
+import { t as requireActiveProject } from "./project-store-Bz5kf-EI.mjs";
+import { t as tenantProjectHeaders } from "./headers-D79npewp.mjs";
+import { defineCommand } from "citty";
+//#region src/commands/audio/text.ts
+/**
+* `xiaobao-cli audio text <audio-id>` — fetch a single recording's transcript
+* via GET /ai-open/audio/text/{audioId}.
+*
+* Returns talkRatios (per-speaker speaking ratios) + texts (segmented ASR
+* with role / beginTime / endTime / text / commentaryNum per item).
+*/
+var text_default = defineCommand({
+	meta: {
+		name: "text",
+		description: "查询单条录音转录文本（含说话人占比 + 分段文本）"
+	},
+	args: {
+		audioId: {
+			type: "positional",
+			required: true,
+			description: "录音 ID（来自 audio list 的 content[].audioId）"
+		},
+		"api-base": { type: "string" },
+		"auth-base": { type: "string" },
+		format: {
+			type: "string",
+			default: "json"
+		}
+	},
+	async run({ args }) {
+		try {
+			const config = resolveConfig({
+				apiBase: args["api-base"],
+				authBase: args["auth-base"]
+			});
+			const active = await requireActiveProject();
+			const audioId = String(args.audioId);
+			writeResult(await xbApiFetch(config, "GET", `/ai-open/audio/text/${encodeURIComponent(audioId)}`, { headers: tenantProjectHeaders(active) }), args.format);
+		} catch (err) {
+			writeError(err, args.format);
+			process.exit(1);
+		}
+	}
+});
+//#endregion
+export { text_default as default };

package/dist/token-store-CHZ_rJQk.mjs

@@ -0,0 +1,85 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { chmod, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+//#region src/core/token-store.ts
+/**
+* Persistent token store, file-backed.
+*
+* CLI-specific layout vs the plugin (which stored under workspaceDir):
+*
+*   PRIMARY  ~/.xiaobao/token.json           (writes always here, mode 0600)
+*   FALLBACK ~/.openclaw/state/wangxiaobao/token.json (read-only legacy path)
+*
+* The fallback lets openclaw-xiaobao plugin users adopt the CLI without
+* re-running OAuth: first CLI invocation reads the existing plugin token,
+* any subsequent write (login / refresh / logout) lands in ~/.xiaobao/ and
+* the legacy path is left untouched.
+*/
+const PRIMARY_DIR = join(homedir(), ".xiaobao");
+const PRIMARY_TOKEN_FILE = join(PRIMARY_DIR, "token.json");
+const LEGACY_TOKEN_FILE = join(homedir(), ".openclaw", "state", "wangxiaobao", "token.json");
+/**
+* Read order: primary → legacy fallback. Returns null if both missing.
+*/
+async function readToken() {
+	for (const f of [PRIMARY_TOKEN_FILE, LEGACY_TOKEN_FILE]) {
+		if (!existsSync(f)) continue;
+		try {
+			const raw = await readFile(f, "utf-8");
+			return JSON.parse(raw);
+		} catch (e) {
+			if (e.code === "ENOENT") continue;
+			throw e;
+		}
+	}
+	return null;
+}
+async function writeToken(resp) {
+	const now = Date.now();
+	const expiresIn = resp.expires_in ?? 7200;
+	const tokenInfo = {
+		access_token: resp.access_token,
+		refresh_token: resp.refresh_token,
+		id_token: resp.id_token,
+		token_type: resp.token_type || "Bearer",
+		scope: resp.scope,
+		expires_at: now + expiresIn * 1e3,
+		obtained_at: now
+	};
+	await mkdir(PRIMARY_DIR, {
+		recursive: true,
+		mode: 448
+	});
+	await writeFile(PRIMARY_TOKEN_FILE, JSON.stringify(tokenInfo, null, 2), { mode: 384 });
+	try {
+		await chmod(PRIMARY_TOKEN_FILE, 384);
+	} catch {}
+	return tokenInfo;
+}
+/**
+* Only deletes the primary file. Legacy openclaw path is left intact so a
+* `xiaobao-cli auth logout` doesn't silently nuke the plugin's token.
+*/
+async function clearToken() {
+	try {
+		await unlink(PRIMARY_TOKEN_FILE);
+	} catch (e) {
+		if (e.code !== "ENOENT") throw e;
+	}
+}
+function isAccessTokenValid(token) {
+	return Boolean(token?.access_token && token.expires_at > Date.now() + 6e4);
+}
+function decodeJwtPayload(jwt) {
+	if (!jwt) return null;
+	const parts = jwt.split(".");
+	if (parts.length !== 3) return null;
+	try {
+		return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { writeToken as a, readToken as i, decodeJwtPayload as n, isAccessTokenValid as r, clearToken as t };

package/dist/use-DV9Ii3Tn.mjs

@@ -0,0 +1,61 @@
+import { n as writeResult, t as writeError } from "./format-BZvv8lYc.mjs";
+import { n as saveActiveProject } from "./project-store-Bz5kf-EI.mjs";
+import { defineCommand } from "citty";
+//#region src/commands/project/use.ts
+/**
+* `xiaobao-cli project use` — persist active tenant/project to
+* ~/.xiaobao/active-project.json (mode 0600). Mirrors openclaw-xiaobao's
+* `xiaobao_switch_project` tool.
+*/
+var use_default = defineCommand({
+	meta: {
+		name: "use",
+		description: "激活指定租户/项目（先用 `project list` 拿候选）"
+	},
+	args: {
+		"tenant-id": {
+			type: "string",
+			required: true,
+			description: "租户 ID"
+		},
+		"tenant-name": {
+			type: "string",
+			required: true,
+			description: "租户显示名"
+		},
+		"project-id": {
+			type: "string",
+			required: true,
+			description: "项目 ID（estateId）"
+		},
+		"project-name": {
+			type: "string",
+			required: true,
+			description: "项目显示名"
+		},
+		format: {
+			type: "string",
+			default: "json"
+		}
+	},
+	async run({ args }) {
+		try {
+			const saved = await saveActiveProject({
+				tenantId: args["tenant-id"],
+				tenantName: args["tenant-name"],
+				projectId: args["project-id"],
+				projectName: args["project-name"]
+			});
+			writeResult({
+				success: true,
+				activeProject: saved,
+				message: `已切换到「${saved.tenantName} / ${saved.projectName}」`
+			}, args.format);
+		} catch (err) {
+			writeError(err, args.format);
+			process.exit(1);
+		}
+	}
+});
+//#endregion
+export { use_default as default };

package/dist/util-DgwkUfV9.mjs

@@ -0,0 +1,46 @@
+//#region src/core/util.ts
+/**
+* Shared utilities for CLI commands.
+*
+* Mirrors the helpers scattered across openclaw-xiaobao tool files
+* (toLocalDateTime / mergeUserIds), consolidated here so commands stay slim.
+*/
+/**
+* Normalize an LLM/human-provided datetime string to the format pierre's
+* Jackson deserializer expects (`yyyy-MM-dd HH:mm:ss`):
+*
+*   `2026-05-09T12:34:56`        → `2026-05-09 12:34:56`
+*   `2026-05-09T12:34:56.789`    → `2026-05-09 12:34:56`
+*   `2026-05-09T12:34:56+08:00`  → `2026-05-09 12:34:56`
+*   `2026-05-09 12:34:56`        → unchanged
+*/
+function toLocalDateTime(input) {
+	if (!input) return input;
+	return input.replace("T", " ").replace(/\.\d+/, "").replace(/[+-]\d{2}:?\d{2}$/, "").replace(/Z$/, "").trim();
+}
+/**
+* Merge a single id + a list of ids, de-dup. Returns undefined when empty so
+* the upstream API treats it as "no filter" (not "filter to nothing").
+*/
+function mergeUserIds(single, list) {
+	const merged = [];
+	const seen = /* @__PURE__ */ new Set();
+	const push = (v) => {
+		if (!v) return;
+		if (!seen.has(v)) {
+			seen.add(v);
+			merged.push(v);
+		}
+	};
+	if (single) push(single);
+	if (list) for (const v of list) push(v);
+	return merged.length > 0 ? merged : void 0;
+}
+/** Split `"a,b,c"` → `["a", "b", "c"]`, trimmed, empties dropped. */
+function csvToArray(input) {
+	if (!input) return void 0;
+	const arr = input.split(",").map((x) => x.trim()).filter(Boolean);
+	return arr.length > 0 ? arr : void 0;
+}
+//#endregion
+export { mergeUserIds as n, toLocalDateTime as r, csvToArray as t };

package/dist/visit-Ct3Vea8I.mjs

@@ -0,0 +1,11 @@
+import { defineCommand } from "citty";
+//#region src/commands/visit/index.ts
+var visit_default = defineCommand({
+	meta: {
+		name: "visit",
+		description: "客户来访分页查询"
+	},
+	subCommands: { list: () => import("./list-Bkyi95YO.mjs").then((m) => m.default) }
+});
+//#endregion
+export { visit_default as default };

package/dist/whoami-DwTHvI4B.mjs

@@ -0,0 +1,51 @@
+import { i as readToken, n as decodeJwtPayload } from "./token-store-CHZ_rJQk.mjs";
+import { n as writeResult, t as writeError } from "./format-BZvv8lYc.mjs";
+import { defineCommand } from "citty";
+//#region src/commands/auth/whoami.ts
+/**
+* `xiaobao-cli auth whoami` — print currently logged-in 旺小宝 user.
+*
+* Pure local op: reads cached id_token (primary then legacy fallback) and
+* decodes the JWT payload. No HTTP call.
+*/
+var whoami_default = defineCommand({
+	meta: {
+		name: "whoami",
+		description: "查看当前登录的旺小宝用户（解析缓存 id_token）"
+	},
+	args: { format: {
+		type: "string",
+		default: "json"
+	} },
+	async run({ args }) {
+		try {
+			const token = await readToken();
+			if (!token) {
+				writeResult({
+					logged_in: false,
+					message: "No token cached. Run `xiaobao-cli auth login` to log in."
+				}, args.format);
+				return;
+			}
+			const claims = decodeJwtPayload(token.id_token);
+			writeResult({
+				logged_in: true,
+				user: claims ? {
+					sub: claims.sub,
+					name: claims.name,
+					phone_number: claims.phone_number,
+					email: claims.email,
+					preferred_username: claims.preferred_username
+				} : null,
+				token_expires_at: token.expires_at,
+				token_expires_in_seconds: Math.max(0, Math.floor((token.expires_at - Date.now()) / 1e3)),
+				scope: token.scope
+			}, args.format);
+		} catch (err) {
+			writeError(err, args.format);
+			process.exit(1);
+		}
+	}
+});
+//#endregion
+export { whoami_default as default };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@puyinkai/xiaobao-cli",
+  "version": "0.1.0",
+  "description": "旺小宝 CLI — host-agnostic 14 tools (openclaw-xiaobao plugin 的 CLI 等价物)",
+  "type": "module",
+  "bin": {
+    "xiaobao-cli": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist/**/*.mjs",
+    "dist/**/*.d.mts",
+    "skills/**/SKILL.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.32.1",
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "dev": "node --import tsx src/cli.ts"
+  },
+  "dependencies": {
+    "citty": "^0.1.6"
+  },
+  "devDependencies": {
+    "@toon-format/toon": "^2.2.0",
+    "@types/node": "^25.2.3",
+    "tsdown": "^0.21.4",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,252 @@
+---
+name: wangxiaobao-audio-query
+description: |
+  旺小宝录音只读查询技能。按时间 / 销售 / 翻页查询录音元数据列表，可选地抽样取单条转录文本预览。**不写文件、不动游标**——是 `wangxiaobao-audio-wiki` 的"探查 / 抽样"版。
+
+  **当以下情况时使用此 Skill**:
+  (1) 用户提到"看看有哪些录音"、"查录音"、"列录音"、"哪些销售有几条录音"、"录音多不多"
+  (2) 用户想抽样几条录音文本预览，但不想批量入库
+  (3) 用户在 sync 之前想估个量、看一下数据形状
+  (4) 用户问"张三/某销售本周打了几个电话"、"上周末有几条客户对话"
+  (5) 任何"看一眼录音"而**不**触发"同步 / 入库 / 归档"意图的场景
+---
+
+> **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/`）。
+
+
+# 旺小宝录音查询
+
+只读探查录音。**没有副作用**——不写 wiki / 不推游标，
+所以用错也没成本，鼓励放心调用。
+
+> 想要"完整入库流程"（拉全部文本 → 写 wiki/raw/audio/ → 推进游标），切到
+> `wangxiaobao-audio-wiki` skill。本 skill 跟那个的边界就是**有没有副作用**。
+
+## 执行前必读
+
+- 必须有有效 token：先调 `xiaobao_whoami`，未登录 / 过期就调 `xiaobao_authorize`
+- **必须有激活项目**：tenant/project 由 tool 内部从
+  `~/.openclaw/state/wangxiaobao/active-project.json` 读，调用方不需要传任何
+  tenant/project 参数。如果 tool 返回 `error: 'NO_ACTIVE_PROJECT'`，
+  让用户跑 `wangxiaobao-switch-project` skill 后再重试
+- **绝不要**写文件、推游标。即使用户随口说"顺便存一下"也要拦：
+  那是 `wangxiaobao-audio-wiki` 的事，本 skill 一旦写盘就破坏了"只读"承诺
+- LocalDateTime 字段格式：`yyyy-MM-dd HH:mm:ss`（**空格**分隔，不带时区）。
+  pierre 框架的 Jackson 反序列化只认这个格式；带 `T` 或 `+08:00` 会被 plugin
+  容错处理，但传空格形式最稳
+
+---
+
+## 快速索引：意图 → 工具
+
+| 用户意图               | plugin tool                | 关键参数                                  |
+| ---------------------- | -------------------------- | ----------------------------------------- |
+| 列某时段所有录音元数据 | `xiaobao_list_audio`       | `fromDate` / `toDate`                     |
+| 列某销售的录音         | `xiaobao_list_audio`       | `+ userId: <uid>`（多个销售用 `userIdList`） |
+| 反查销售 user-id       | `xiaobao_list_consultants` | 无参（拿当前用户授权范围内的所有顾问）   |
+| 看总数 / 估个量        | `xiaobao_list_audio`       | `page: 1, size: 1`，只读 `total`          |
+| 翻页继续看             | `xiaobao_list_audio`       | `page += 1`                               |
+| 看某条录音转录预览     | `xiaobao_get_audio_text`   | `audioId`（从 list_audio 结果拿）         |
+
+**tool 参数里没有** `tenantId` / `projectId` —— plugin 内部从激活项目状态读。
+如果还没激活过项目，跑 `wangxiaobao-switch-project` skill 先设一次。
+
+---
+
+## 核心约束
+
+### 1. 时间范围：用户没明确说就推断合理窗口
+
+当用户没给具体时间，按用户的话推断一个**能覆盖意图**的窗口，而不是默认拉
+最近 N 天造成超时。常见映射：
+
+| 用户说法       | 解析                                                  |
+| -------------- | ----------------------------------------------------- |
+| "今天的录音"   | from = 今天 00:00:00, to = now                        |
+| "上周二的录音" | from = 上周二 00:00:00, to = 上周三 00:00:00          |
+| "5 月份的"     | from = 2026-05-01 00:00:00, to = 2026-06-01 00:00:00  |
+| "最近几条"     | from = now - 1 day, to = now, size = 10               |
+
+用户明确给时间时直接用，不要二次猜测。
+
+### 2. 分页：page 从 **1** 开始
+
+PageParam 默认 `page: 1, size: 10`，传 `page: 0` 上游会报错。读 `total` +
+当前 `page * size` 判断是否还有下一页，需要时翻页；浏览概览时第 1 页通常
+够用。`size` 上限 500（schema 已限制），预览展示建议 20。
+
+### 3. 按销售筛选：先反查 user-id 再过滤
+
+不带 `userId` / `userIdList` 就拉**所有人**的录音。要筛某个销售：
+
+- 用户能直接给 user-id（数字）→ 用 `userId: <id>`（单个）或
+  `userIdList: [<id1>, <id2>, ...]`（多个）
+- 只知道名字 → 调 **`xiaobao_list_consultants`**（无参），拿到当前用户
+  授权范围内的所有顾问（含 `userName` / `userId`），按名字 match 后取 `userId`
+  传给 `xiaobao_list_audio`
+
+> 已弃用做法："先 list_audio 不带 filter，再扫 content[].saleName 反查"——
+> 这种 hack 在录音数据稀疏 / 时间窗短时找不到目标销售。**改用
+> `xiaobao_list_consultants` 反查**，精确且快。
+
+### 4. 单条文本预览：按需调，不要全量
+
+`xiaobao_get_audio_text` 一次拿一条录音的转录。**只在用户挑了具体某条之
+后再调**，不要 list 完顺手把每条都 get_audio_text 一遍——那是 sync skill
+的事。一次会话 1-3 条样本预览足够。
+
+### 5. 响应外层结构
+
+`xiaobao_list_audio` 和 `xiaobao_get_audio_text` 都返回 pierre 框架的
+`Result<T>` 包：
+
+```jsonc
+{
+  "code": "0",   // 业务状态码，"0" 是成功
+  "msg":  "success",
+  "data": { ... }  // 真正的 payload
+}
+```
+
+list_audio 里 `data` 又是 `PageResult<AudioPageResp>`：
+`{ page, size, total, content[] }`，所以**取元数据数组**要写
+`resp.data.data.content`（plugin tool 不展开 envelope，原样返回）。
+
+---
+
+## 使用场景示例
+
+### 场景 1：列今天所有录音
+
+```jsonc
+// xiaobao_list_audio
+{
+  "fromDate": "2026-05-12 00:00:00",
+  "toDate":   "2026-05-12 23:59:59",
+  "page": 1,
+  "size": 20
+}
+```
+
+渲染给用户（按 startTime desc，audioId 必须显示——后面取文本要用）：
+
+```
+共 145 条录音（第 1/8 页）
+
+1. 张三 · 2026-05-12 10:23:11 ~ 10:35:42（12 分钟） · audioId=12345
+2. 李四 · 2026-05-12 09:50:00 ~ 10:02:15（12 分钟） · audioId=12344
+3. 王五 · 2026-05-12 09:10:00 ~ 09:25:11（15 分钟） · audioId=12343
+...
+```
+
+### 场景 2：估算"上周末打了几个电话"
+
+只关心 `total`，第 1 页就够：
+
+```jsonc
+{
+  "fromDate": "2026-05-10 00:00:00",
+  "toDate":   "2026-05-12 00:00:00",
+  "page": 1,
+  "size": 1
+}
+```
+
+回复：「周末两天共 23 条录音，主要集中在周日下午」。
+
+### 场景 3：取某条录音的转录预览
+
+用户从场景 1 列表里挑了序号 1（audioId=12345）：
+
+```jsonc
+// xiaobao_get_audio_text
+{ "audioId": 12345 }
+```
+
+渲染：
+
+```
+audioId 12345 · 张三 · 2026-05-12 10:23:11（12 分钟）
+说话人占比：销售 62% / 客户 38%
+
+转录：
+[10:23:15] 销售：您好张总，我是旺小宝的小张，咱们那个项目...
+[10:23:22] 客户：嗯嗯你说
+[10:23:25] 销售：周末方便过来看下样板间吗？
+...
+```
+
+### 场景 4：按销售名字筛 —— 用 list-consultants 反查
+
+用户说"张三本周打了几个"——只知道名字：
+
+1. 调 `xiaobao_list_consultants`（无参）→ 拿到 `[{ userId, userName, ... }, ...]`
+2. 在结果里找 `userName === "张三"` 的 `userId`
+3. 调 `xiaobao_list_audio` 带 `userId: <张三的 userId>` + 本周时间窗
+
+```jsonc
+// step 1
+// xiaobao_list_consultants
+{}
+
+// step 2 ——找到 张三 的 userId = 100
+// step 3
+// xiaobao_list_audio
+{
+  "fromDate": "2026-05-06 00:00:00",
+  "toDate":   "2026-05-13 00:00:00",
+  "userId":   100,
+  "page": 1, "size": 20
+}
+```
+
+如果 list-consultants 里**找不到张三**——说明当前登录用户没权限看张三
+（不在管理范围内 / 不在团队里）。提示用户"当前账号无权访问销售『张三』"，
+不要硬调 list-audio 假装搜（也会因 dataPermission 拿不到）。
+
+---
+
+## 常见错误与排查
+
+- **`code: "400"` / `msg: "消息转换异常"`** — fromDate/toDate 格式不对。
+  必须 `yyyy-MM-dd HH:mm:ss` 空格分隔，不带时区。
+- **401 / token 过期** — 调 `xiaobao_authorize { force: true }` 重登，重试一次。
+- **`total: 0`** — 时间窗口里确实没数据，或激活的租户/项目错了。
+  让用户跑 `wangxiaobao-switch-project` skill 确认或重新激活项目。
+- **`error: 'NO_ACTIVE_PROJECT'`** — 还没设过激活项目。让用户跑
+  `wangxiaobao-switch-project` skill 后重试本 skill。
+- **翻页拿不到下一页** — 检查 `page` 是不是从 1 开始（不是 0），
+  `page * size > total` 时已经到末页。
+- **`saleName` 是空的** — 上游 user info 缺失，可以只用 `userId` 标识，
+  跟用户说"该录音的销售信息上游缺失"。
+- **想"批量转文本看看"** — 拦住：批量取文本是 `wangxiaobao-audio-wiki`
+  的事（带写文件 + 推游标），本 skill 设计上每次会话最多预览 1-3 条。