@bty/customer-service-cli 0.6.0 → 0.6.4

package/CHANGELOG.md

@@ -1,6 +1,31 @@
 # Changelog
 
-## 0.6.0 (2026-06-09)
+## 0.6.4 (2026-07-04)
+
+- `conversation transfer-human` 适配服务端 cursor 分页：移除 CLI 暴露的 `--page` 参数，CLI 自动沿 `next_cursor` 拉取全部结果并合并返回，避免深翻页请求压垮数据库。
+- `transfer-human` 客户端保留 7 天查询窗口校验，并新增最多 500 个 cursor 页的保护，超出时提示缩小查询时间范围。
+
+## 0.6.3 (2026-06-25)
+
+- 修复 `product update` / `product update-sku` 在商品数超过 100 时，对位置靠后的商品报「未找到商品 product_id=xxx」的问题：`findProduct` 由只取第一页（`page:1, pageSize:100`）改为翻页查找，直到命中目标商品或翻完所有页。
+
+## 0.6.2 (2026-06-15)
+
+- `workspace` 新增 `points-consumes` 子命令：分页查询当前工作空间的积分账户消耗流水（`POST /v1/workspace/points_consumes`），支持 `--page` / `--page-size`，CLI 固定传 `debug: true`，返回中包含服务端 `extra` 调试字段。
+- `customer-servhub-api` 的 `POST /v1/workspace/points_consumes` 新增 `debug` 请求参数：默认 `false` 不返回 `extra`，传 `true` 时返回 `extra` 方便调试。
+
+## 0.6.1 (2026-06-11)
+
+- `product` 新增 `related-knowledge` 子命令组，支持按商品维护“关联知识库”文件级绑定：
+  - `product related-knowledge list --agent <id> --product-id <id>`：列出商品绑定的 QA / 扩展知识库文件。
+  - `product related-knowledge add --agent <id> --product-id <id> --type qa|common (--file <name> | --file-id <id> --partition-id <id>)`：给商品追加绑定文件，重复文件幂等去重。
+  - `product related-knowledge remove --agent <id> --product-id <id> --type qa|common --file-id <id>`：移除指定绑定，目标不存在时保持幂等。
+  - `product related-knowledge set --agent <id> --product-id <id> --bindings <json|@file>`：覆盖商品的全部关联知识库文件。
+- `faq` / `knowledge` 新增文件侧 `bind-products` 子命令组，分别固定写入 `knowledge_type=qa` / `knowledge_type=common`：
+  - `list`：按知识库文件反查绑定商品。
+  - `add` / `remove`：read-modify-replace 维护绑定商品，重复添加或移除不存在的商品保持幂等。
+  - `set`：覆盖该文件绑定的全部商品。
+- 新增 `product-knowledge-binding-api` 客户端封装，对接 customer-servhub-api `/v1/knowledge/product-bindings*` 现有接口；CLI 不改变服务端绑定表或 sop-engine 命中逻辑。
 
 - 新增 `node-template describe [--stage <s>]`：节点编写说明书命令（AI 编写前必读）——输出每个节点的职责/可编辑面/输出契约/平台锁定段，以及该节点可 `@引用` 的变量目录。纯静态、与具体 agent 无关，无需 `--agent`。
 - `node-template` 节点 stage 新增 `image_understanding` 伪 stage（图片理解方法论可配置化，spec 2026-06-08）：`describe` / `get` / `set-draft` / `publish` / `versions` / `version` / `restore` 均纳入；发布前 `{{}}` 合法性校验白名单同步放行。

package/README.md

@@ -227,6 +227,10 @@ cs-cli workspace points-consumes-daily --start 2026-04-01 --end 2026-04-23
 | `product identify-all --agent <id>` | 一键增强学习当前 Agent 下所有待增强商品 |
 | `product sync-taobao --agent <id> [--skip-hash-check] [--sync-type <full\|incremental>]` | 触发淘宝店铺商品同步 |
 | `product sync-taobao-item --agent <id> --product-id <商品ID>` | 触发单个淘宝商品同步 |
+| `product related-knowledge list --agent <id> --product-id <商品ID>` | 列出商品详情绑定的 QA / 扩展知识库文件 |
+| `product related-knowledge add --agent <id> --product-id <商品ID> --type <qa\|common> (--file <文件名> \| --file-id <id> --partition-id <id>)` | 给商品追加关联知识库文件 |
+| `product related-knowledge remove --agent <id> --product-id <商品ID> --type <qa\|common> --file-id <id>` | 移除商品绑定的指定知识库文件 |
+| `product related-knowledge set --agent <id> --product-id <商品ID> --bindings <json\|@file>` | 覆盖商品绑定的全部知识库文件 |
 
 `product update` 支持更新的字段包括：`卖点`、`补充知识`、`tag`、`参数`、`轮播图识别结果`、`商品详情页识别结果` 等。`--update` 接受 JSON 字符串或 `@文件路径`。
 
@@ -240,6 +244,8 @@ cs-cli workspace points-consumes-daily --start 2026-04-01 --end 2026-04-23
 
 注意：这两个命令仅对已开通“高级工具”的店铺 Agent 生效。未开通高级工具时，即使 `--agent` 已绑定淘宝授权店铺，请求也可能在服务端失败。
 
+`product related-knowledge` 管理商品详情的“关联知识库”文件级绑定。`--type qa` 对应 FAQ 知识库，`--type common` 对应扩展知识库。`add` / `remove` 会先读取当前绑定，再通过服务端全量替换接口写回；重复添加或移除不存在的文件保持幂等。`--file <文件名>` 会按当前 Agent 的知识库文件列表做精确匹配；文件名不存在或不唯一时，改用 `--file-id` + `--partition-id` 显式模式。
+
 ```bash
 # 更新卖点
 cs-cli product update --agent <id> --product-id <商品ID> --update '{"卖点":"新卖点内容"}'
@@ -255,6 +261,12 @@ cs-cli product update-sku --agent <id> --sku "颜色分类:粉红" --update '{"
 
 # 更新 SKU 补充知识（按 sku_id 定位，推荐）
 cs-cli product update-sku --agent <id> --sku-id 6072595054179 --update '{"补充知识":"说明内容"}'
+
+# 给商品绑定一个 FAQ 文件
+cs-cli product related-knowledge add --agent <id> --product-id <商品ID> --type qa --file "常见问题.xlsx"
+
+# 显式 ID 模式绑定扩展知识文件
+cs-cli product related-knowledge add --agent <id> --product-id <商品ID> --type common --file-id 622474 --partition-id 12345 --file-name "售后规则.md"
 ```
 
 
@@ -405,11 +417,17 @@ CLI 把 `description` + `expected` 拼成 `content`：
 | `faq add --agent <id> --file <文件名> --questions <问题1,问题2> --answers <答案=xxx>` | 添加 FAQ 内容 |
 | `faq update --agent <id> --file <文件名> --group-id <id> [--questions <...>] [--answers <...>] [--delete-chunks <id1,id2>]` | 更新已有 FAQ 答案组（`--questions` / `--answers` / `--delete-chunks` 至少一个） |
 | `faq delete --agent <id> --file <文件名> --group-id <id>` | 删除 FAQ 答案组 |
+| `faq bind-products list --agent <id> (--file <文件名> \| --file-id <id> --partition-id <id>)` | 列出 FAQ 文件绑定的商品 |
+| `faq bind-products add --agent <id> (--file <文件名> \| --file-id <id> --partition-id <id>) --product-id <商品ID...>` | 给 FAQ 文件追加绑定商品 |
+| `faq bind-products remove --agent <id> (--file <文件名> \| --file-id <id> --partition-id <id>) --product-id <商品ID...>` | 从 FAQ 文件移除绑定商品 |
+| `faq bind-products set --agent <id> (--file <文件名> \| --file-id <id> --partition-id <id>) --product-id <商品ID...>` | 覆盖 FAQ 文件绑定的全部商品 |
 
 `faq content` 走 `GET /mebsuta/api/v1/dataset/{knowledge_id}/faq_contents`，列出文件内的答案组及其 `answer_group_id`，是 `faq update` / `faq delete` 拿 `--group-id` 的来源（`faq list` 只给文件，文件内的 group-id 要靠这条命令查）。支持 `--keyword` 搜索、`--page-size` 分页、`--next-group-id` 游标续翻。
 
 `faq update` 按 `answer_group_id` 定位目标组，POST 同一个 `faq_contents/save` 接口完成字段替换、问题替换与 chunk 级删除。`faq delete` 走 `DELETE /faq_contents/{group_id}` 整组删除。
 
+`faq bind-products` 固定写入 `knowledge_type=qa` 的商品绑定关系，适合从 FAQ 文件视角批量维护关联商品。`--file` 为精确文件名匹配；文件名不唯一时请传 `--file-id` 和 `--partition-id`。
+
 ### 扩展知识库 (`knowledge`)
 
 Agent 关联的通用规则知识库（`suffix_type=_common`），与 FAQ / 商品知识并列的第三类知识源，支持段落（chunk）级 CRUD，统一走 `/mebsuta/api/v1/dataset/{id}/contents/perform-operations`。
@@ -421,9 +439,15 @@ Agent 关联的通用规则知识库（`suffix_type=_common`），与 FAQ / 商
 | `knowledge content add --knowledge-id <id> --content <text\|@file> [--keyword <k...>] [--after <chunk_id>]` | 新增段落 |
 | `knowledge content update --knowledge-id <id> --chunk-id <id> [--content <text\|@file>] [--keyword <k...>] [--enable \| --disable]` | 更新段落（四个变更字段至少一个；未指定 `--enable` / `--disable` 时自动保留当前启停状态，避免后端 enable 必填校验失败） |
 | `knowledge content delete --knowledge-id <id> --chunk-id <id>` | 删除段落 |
+| `knowledge bind-products list --agent <id> (--file <文件名> \| --file-id <id> --partition-id <id>)` | 列出扩展知识文件绑定的商品 |
+| `knowledge bind-products add --agent <id> (--file <文件名> \| --file-id <id> --partition-id <id>) --product-id <商品ID...>` | 给扩展知识文件追加绑定商品 |
+| `knowledge bind-products remove --agent <id> (--file <文件名> \| --file-id <id> --partition-id <id>) --product-id <商品ID...>` | 从扩展知识文件移除绑定商品 |
+| `knowledge bind-products set --agent <id> (--file <文件名> \| --file-id <id> --partition-id <id>) --product-id <商品ID...>` | 覆盖扩展知识文件绑定的全部商品 |
 
 `knowledge content add` / `update` 的 `--content` 支持 `@路径` 前缀从文件读取**纯文本**（不是 JSON）。`--keyword` 为 variadic 选项，空格分隔多个关键词。
 
+`knowledge bind-products` 固定写入 `knowledge_type=common` 的商品绑定关系，适合从扩展知识文件视角批量维护关联商品。`add` / `remove` 会 read-modify-replace，重复添加或移除不存在的商品保持幂等。
+
 
 ### 会话管理 (`conversation`)
 
@@ -433,7 +457,7 @@ Agent 关联的通用规则知识库（`suffix_type=_common`），与 FAQ / 商
 | `conversation list [--agent <id>] [--equipment-id <设备ID>] [--user <用户名>] [--start <日期>] [--end <日期>]` | 搜索会话     |
 | `conversation records <conversation_id> [--page-size N] [--direction prev|next]` | 获取会话聊天记录 |
 | `conversation context-search --query <文本> [--start <时间>] [--end <时间>]` | 通过上下文内容模糊搜索对话记录（返回匹配消息详情，时间范围最多 3 天） |
-| `conversation transfer-human --agent <customer_agent_config_id> --start <时间> --end <时间> [--page N]` | 查询转人工会话及对应转人工消息记录（时间范围最多 7 天，分页大小固定 100） |
+| `conversation transfer-human --agent <customer_agent_config_id> --start <时间> --end <时间>` | 查询转人工会话及对应转人工消息记录（时间范围最多 7 天，自动 cursor 翻页） |
 
 
 ### Agent 调试 (`debug`)
@@ -441,18 +465,37 @@ Agent 关联的通用规则知识库（`suffix_type=_common`），与 FAQ / 商
 
 | 命令                                                                                                          | 说明                   |
 | ----------------------------------------------------------------------------------------------------------- | -------------------- |
-| `debug ask --agent <id> --text <消息> [--user <用户名>] [--url <图片URL>] [--conversation <会话ID>] [--timeout <秒>]` | 向 Agent 发送消息并等待回复    |
-| `debug reproduce <record_id> [--agent <id>] [--timeout <秒>] [--dry-run]` | 根据 record_id 复现 Agent 回复（自动获取上下文） |
+| `debug ask --agent <id> (--text <消息> \| --messages <json\|@file>) [--user <用户名>] [--url <图片URL>] [--conversation <会话ID>] [--mock <json\|@file>] [--data-overlay <json\|@file>] [--timeout <秒>] [--poll-interval <毫秒>]` | 向 Agent 发送消息并等待回复    |
+| `debug reproduce <record_id> [--agent <id>] [--mock <json\|@file>] [--data-overlay <json\|@file>] [--timeout <秒>] [--poll-interval <毫秒>] [--dry-run]` | 根据 record_id 复现 Agent 回复（自动获取上下文） |
+| `debug data snapshot --agent <id> [--product-id <商品ID...>]` | 生成可传给 `--data-overlay @file` 的 debug 数据覆盖 JSON |
 | `debug record <record_id>`                                                                                  | 获取记录的调试信息（flow_info），返回中包含 `trace_id` |
 | `debug trace <trace_id> [--env <dev\|prod>]`                                                                | 根据 Langfuse Trace ID 获取完整 Trace 详情（经服务端代理，默认 `prod`） |
 
 
-`debug ask` 会自动创建调试会话、发送消息、轮询等待 Agent 回复，默认最大等待 30 秒。支持 `--messages` 传入完整消息列表（JSON 或 @文件）重放 issue 对话。
+`debug ask` 会自动创建调试会话、发送消息、轮询等待 Agent 回复，默认最大等待 30 秒，默认轮询间隔 2000ms。`--text` 与 `--messages` 二选一：`--text` 发送单条消息，`--url` 只在 `--text` 模式下作为附图 URL；`--messages` 传入完整消息列表（JSON 或 @文件）重放多轮对话，既接受 JSON 数组，也接受 `conversation records` 原始 `{ "msg_list": [...] }` 对象。`--conversation` 可复用已有 debug 会话继续对话；`--mock` 可传工具结果 mock；`--data-overlay` 可传 `debug_data_overlay` JSON 或 @文件。
+
+`debug reproduce` 根据一条回复记录自动复现 Agent 回复：通过 recordId 获取关联会话和 Agent 配置，拉取完整会话记录并截取目标 record 之前的上下文，使用原始用户名创建新 debug 会话并发送。默认最大等待 60 秒，默认轮询间隔 2000ms。`--agent` 可指定另一个 Agent 复现同一段上下文（A/B 对比）；`--mock` 和 `--data-overlay` 会在复现发送时透传；`--dry-run` 仅输出截断后的 `msg_list`、mock 和 overlay，不发送。
+
+`debug data snapshot` 生成 `debug_data_overlay` v1 JSON，适合把当前 Agent 的 SOP / 商品 / 活动等数据固定成一次 debug 覆盖输入，再通过 `debug ask --data-overlay @file` 或 `debug reproduce --data-overlay @file` 复跑。`--agent <id>` 必填；`--product-id <商品ID...>` 可重复传多个商品 ID，只导出指定商品，不传则分页导出全量商品。命令输出写到 stdout，通常重定向到文件保存。
+
+```bash
+# 只导出指定商品相关 overlay
+cs-cli debug data snapshot --agent <id> --product-id 586812046546 > overlay.json
 
-`debug reproduce` 根据一条回复记录自动复现 Agent 回复：通过 recordId 获取关联会话和 Agent 配置，拉取完整会话记录并截取目标 record 之前的上下文，使用原始用户名创建新 debug 会话并发送。`--agent` 可指定另一个 Agent 复现同一段上下文（A/B 对比），`--dry-run` 仅输出上下文不发送。
+# 使用 overlay 跑一次 ask
+cs-cli debug ask --agent <id> --text "https://item.taobao.com/item.htm?id=586812046546 这个商品名称是啥" --data-overlay @overlay.json
+```
 
 `debug trace`（v0.4.0 起，**行为变更**）不再由 CLI 直连 Langfuse REST API，改为请求 customer-servhub-api 的 `GET /v1/debug/langfuse/trace/{trace_id}?env=<env>`，走 CLI 标准 Bearer 鉴权，由服务端按 env 选择 Langfuse 凭据并代理拉取 Trace。Trace ID 从 `debug record` 返回的 `trace_id` 字段获取。
 
+### 工作空间 (`workspace`)
+
+| 命令 | 说明 |
+| --- | --- |
+| `workspace list` | 列出当前账号可访问的工作空间 |
+| `workspace points-consumes [--page <n>] [--page-size <n>]` | 分页查询积分账户消耗流水，固定返回 `extra` 调试字段 |
+| `workspace points-consumes-daily [--start <YYYY-MM-DD>] [--end <YYYY-MM-DD>]` | 按天查询积分消耗趋势 |
+
 - `--env <dev|prod>`：指定 Langfuse 环境，默认 `prod`。只接受 `dev` / `prod`，传其它值命令直接报错并以非 0 退出（不发请求）。
 
 ```bash
@@ -810,12 +853,9 @@ cs-cli product add --agent <id> --data @products.json --source batch --no-identi
 # 通过上下文内容模糊搜索对话记录（自动使用当前工作空间，查询窗口最多 3 天）
 cs-cli conversation context-search --query "退款问题" --start 2026-03-22T00:00:00 --end 2026-03-22T23:59:59
 
-# 查询转人工会话及对应转人工消息记录（按 MANUAL_TAKEOVER_REQUIRED 事件时间过滤，查询窗口最多 7 天）
+# 查询转人工会话及对应转人工消息记录（按 MANUAL_TAKEOVER_REQUIRED 事件时间过滤，查询窗口最多 7 天，自动 cursor 翻页）
 cs-cli conversation transfer-human --agent <customer_agent_config_id> --start 2026-05-24T00:00:00 --end 2026-05-24T23:59:59
 
-# 查询第 2 页转人工会话
-cs-cli conversation transfer-human --agent <customer_agent_config_id> --start 2026-05-24T00:00:00 --end 2026-05-24T23:59:59 --page 2
-
 # 复现某条回复（自动获取上下文、原始用户名、Agent 配置）
 cs-cli debug reproduce <record_id>