@bty/customer-service-cli 0.1.26 → 0.2.0

package/README.md

@@ -72,11 +72,12 @@ cs-cli agent list
 
 ### 工作空间优先级
 
-| 优先级 | 来源                      | 说明         |
-| --- | ----------------------- | ---------- |
-| 1   | `--workspace <id>` 参数   | 命令行临时覆盖    |
-| 2   | `.cs-cli.json` (本地配置)   | 当前目录或祖先目录  |
-| 3   | `~/.cs-cli/config.json` | 全局默认配置     |
+| 优先级 | 来源                      | 说明                           |
+| --- | ----------------------- | ---------------------------- |
+| 0   | `CS_WORKSPACE_ID` 环境变量   | env lock，最高优先级，override 硬失败（见下方"环境变量锁定"） |
+| 1   | `--workspace <id>` 参数   | 命令行临时覆盖                      |
+| 2   | `.cs-cli.json` (本地配置)   | 当前目录或祖先目录                    |
+| 3   | `~/.cs-cli/config.json` | 全局默认配置                       |
 
 ### 使用方式
 
@@ -110,6 +111,35 @@ CLI 从当前目录向上查找 `.cs-cli.json`，找到第一个即使用其中
 
 每次写入后会提示写入的目标路径。
 
+## 环境变量锁定（sandbox / CI）
+
+当 sandbox、CI 等非交互环境预先注入以下环境变量时，cs-cli 会透明地把 env 作为凭据与上下文来源，并拒绝任何运行时 override（`--workspace` / `--agent` / `auth login` 等），避免下游脚本在上下文被静默切换时产生未定义行为。
+
+| 环境变量            | 作用                        |
+| ----------------- | ------------------------- |
+| `CS_AUTH`         | 登录凭据（等同 access token）。存在即视为"已锁定" |
+| `CS_WORKSPACE_ID` | 锁定工作空间 ID                 |
+| `CS_AGENT_ID`     | 锁定默认 agent ID             |
+
+处理逻辑：
+
+1. **env 优先**：只要环境变量有值，cs-cli 就从 env 读取，忽略本地 `credentials.json` / `.cs-cli.json` / 全局配置。
+2. **override 硬失败**：锁定后如果再通过 `--workspace` / `--agent` / `auth login` / `auth logout` / `config set-workspace` 传入不一致的值，cs-cli 立刻报错退出，不会静默覆盖。
+3. **幂等传值**：override 与 env 值完全一致时允许通过（便于脚本显式断言）。
+
+使用示例：
+
+```bash
+export CS_AUTH="<your-access-token>"
+export CS_WORKSPACE_ID="ws-abc123"
+export CS_AGENT_ID="agent-xyz"
+
+cs-cli agent list     # 直接运行，无需 auth login
+cs-cli --workspace ws-other agent list   # ❌ 报错：CS_WORKSPACE_ID 已被锁定
+```
+
+要解除锁定，清空对应环境变量即可（`unset CS_AUTH CS_WORKSPACE_ID CS_AGENT_ID`）。
+
 ## 命令速查表
 
 ### 认证 (`auth`)
@@ -170,9 +200,12 @@ CLI 从当前目录向上查找 `.cs-cli.json`，找到第一个即使用其中
 | `product get --agent <id> --product-id <商品ID>` | 获取商品详情（自动获取 db_id） |
 | `product update --agent <id> --product-id <商品ID> --update <json\|@file>` | 更新商品信息 |
 | `product update-sku --agent <id> --sku <SKU名称> --update <json\|@file>` | 更新 SKU 信息 |
+| `product learn --agent <id> --url <URL...> [--source <type>] [--no-identify]` | 通过商品 URL 异步学习（manual / identify 默认开启） |
 
 `product update` 支持更新的字段包括：`卖点`、`补充知识`、`tag`、`参数`、`轮播图识别结果`、`商品详情页识别结果` 等。`--update` 接受 JSON 字符串或 `@文件路径`。
 
+`product learn` 提交商品详情页 URL 进入异步学习队列（`/v1/knowledge/products/upload`），返回 `flow_id` 和 `knowledge_ids`。`--url` 可多值，用空格分隔；`--source` 默认 `manual`；传 `--no-identify` 可关闭自动识别。
+
 ```bash
 # 更新卖点
 cs-cli product update --agent <id> --product-id <商品ID> --update '{"卖点":"新卖点内容"}'
@@ -218,6 +251,24 @@ cs-cli product update-sku --agent <id> --sku "颜色分类:粉红" --update '{"
 | ---------------------------------------------------------------------------- | --------- |
 | `faq list --agent <id>`                                                      | 列出 FAQ 文件 |
 | `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 update` 按 `answer_group_id` 定位目标组，POST 同一个 `faq_contents/save` 接口完成字段替换、问题替换与 chunk 级删除。`faq delete` 走 `DELETE /faq_contents/{group_id}` 整组删除。
+
+### 扩展知识库 (`knowledge`)
+
+Agent 关联的通用规则知识库（`suffix_type=_common`），与 FAQ / 商品知识并列的第三类知识源，支持段落（chunk）级 CRUD，统一走 `/mebsuta/api/v1/dataset/{id}/contents/perform-operations`。
+
+| 命令 | 说明 |
+| --- | --- |
+| `knowledge list --agent <id> [--page N] [--page-size N]` | 列出 Agent 关联的扩展知识库文件 |
+| `knowledge content list --knowledge-id <id> [--page-size N] [--direction up\|down]` | 列出段落（chunk） |
+| `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 content add` / `update` 的 `--content` 支持 `@路径` 前缀从文件读取**纯文本**（不是 JSON）。`--keyword` 为 variadic 选项，空格分隔多个关键词。
 
 
 ### 会话管理 (`conversation`)
@@ -430,6 +481,42 @@ cs-cli product update-sku --agent <id> --sku "颜色分类:粉红" --update '{"
 # 添加 FAQ
 cs-cli faq add --agent <id> --file "常见问题" --questions "怎么退款,如何退款" --answers "答案=请联系客服处理退款"
 
+# 更新已有 FAQ 组答案
+cs-cli faq update --agent <id> --file "常见问题" --group-id 2 --answers "答案=请通过订单页面申请退款"
+
+# 更新 FAQ 组问题 + 删除旧 chunk
+cs-cli faq update --agent <id> --file "常见问题" --group-id 2 --questions "如何退款,怎么申请退款" --delete-chunks 3,5
+
+# 删除整个 FAQ 答案组
+cs-cli faq delete --agent <id> --file "常见问题" --group-id 2
+
+# 列出 Agent 的扩展知识库
+cs-cli knowledge list --agent <id>
+
+# 列出某扩展知识库的段落
+cs-cli knowledge content list --knowledge-id 622474
+
+# 新增段落（插入到末尾）
+cs-cli knowledge content add --knowledge-id 622474 --content "退换货需保留商品吊牌" --keyword 退换货 吊牌
+
+# 用文件内容作为段落
+cs-cli knowledge content add --knowledge-id 622474 --content @./rules.txt
+
+# 修改段落内容并重设关键词
+cs-cli knowledge content update --knowledge-id 622474 --chunk-id 2 --content "新的规则说明" --keyword 规则 说明
+
+# 停用某段落
+cs-cli knowledge content update --knowledge-id 622474 --chunk-id 2 --disable
+
+# 删除段落
+cs-cli knowledge content delete --knowledge-id 622474 --chunk-id 2
+
+# 商品 URL 异步学习
+cs-cli product learn --agent <id> --url https://detail.tmall.com/item.htm?id=997678657962
+
+# 多个 URL 一次提交，且跳过自动识别
+cs-cli product learn --agent <id> --url https://a.example/1 https://a.example/2 --no-identify
+
 # 通过上下文内容模糊搜索对话记录（自动使用当前工作空间，查询窗口最多 3 天）
 cs-cli conversation context-search --query "退款问题" --start 2026-03-22T00:00:00 --end 2026-03-22T23:59:59