@bty/customer-service-cli 0.6.5 → 0.6.7

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## Unreleased
+
+- 新增 `media upload` 命令与 `product supplement` 子命令组，支持商品「补充知识」图片/视频维护，与前端上传行为一致：
+  - `media upload --file <path> --type image|video [--path-prefix /ai/knowledge/supplement] [--dry-run]`：本地图片/视频先经 `/v1/upload_sts` 取 STS 凭证上传到公开 OSS（`resource_bucket`），返回公网 URL；已是 http(s) URL 直接拒绝（无需上传）。上传 key 与前端一致：`${prefix}/${timestamp}_${filename}`。图片上限 10MB、视频上限 200MB，超限/类型不符在发起上传请求前直接失败。
+  - `product supplement list --agent <id> --product-id <id>`：读取并解析商品「补充知识」条目（容错解析数组 / JSON 字符串 / 多层编码）。
+  - `product supplement add --agent <id> --product-id <id> --question <Q> --answer <A> [--image <path|url>...] [--video <path|url>...] [--dry-run] [--backup <path>]`：read-modify-write 追加一条 Q/A + 媒体，保留旧条目全量写回；本地媒体自动上传、URL 直写。
+  - `product supplement append-media --agent <id> --product-id <id> --index <n> [--image ...] [--video ...] [--dry-run] [--backup <path>]`：仅向目标下标条目追加媒体，其它条目原样保留；去重合并，未提供任何媒体时报错。
+- Dashboard 命令使用客服 API 原域名下的 `/observability` 网关前缀，无需新增地址配置。
+
+## 0.6.7 (2026-07-30)
+
+> 版本号说明：registry 实际发布序列 0.6.2 → 0.6.4 → 0.6.5 → 0.6.6（0.6.3 从未发布，0.6.4–0.6.6 由其它分支占用），故本条目落 0.6.7。
+
+- `tool workflow` 子组新增 `create` / `update` / `delete` / `describe`，直连 BetterYeah 平台（`ai-api`）程序化管理工作流（flow）本体（既有 `list` / `detail` 走 servhub 代理不变）。CODE 节点只支持 JavaScript：
+  - `tool workflow create --name <名称> --code <code|@file> [--description] [--input-vars <json|@file>] [--no-publish] [--code-node-name]`：程序生成固定 START→CODE→END 三节点骨架（`POST /v1/applications`，`config` 以 JSON 字符串提交），把 JavaScript 代码写进 CODE 节点，默认自动发布；返回 `flow_id` / `version_id` 供 `tool create --source-id` 绑定。骨架结构以真实生产 flow 实测为准（dashed-UUID 节点 id、CODE 节点默认名 `javascript_1`）。
+  - `tool workflow update <flow_id> --code <code|@file> [--no-publish]`：先 `GET /v1/applications/{id}` 取 config，定位唯一 CODE 节点替换其代码（`config` 以对象提交，与 create 的字符串相反），默认取草稿后发布；非唯一 CODE 节点 / config 形状异常在发更新前报清晰错误，不发请求。
+  - `tool workflow run <flow_id> [--input <json|@file>]`：HTTP 同步运行已发布 flow——自动 `GET /v1/workspaces/getKey/{ws}`（登录态）换应用态 Access-Key，再 `POST /v1/public_api/rest_api/{flow_id}/execute_flow`，返回 `task_id` / `status` / `run_result`；替代平台画布的 wss 执行通道（`ws_execute_flow`），实测两通道 `run_result` 一致。
+  - `tool workflow delete <flow_id> --yes`：硬删除（`DELETE /v1/applications/{id}`），缺 `--yes` 拒绝并提示。
+  - `tool workflow describe`：输出 CODE 节点（JavaScript）使用文档，依据官方「JavaScript&Python 节点」文档整理——入口 `async main()`、变量注入（START formConfig 的 `dialogue` 等）、返回值约定（裸对象、可序列化、勿套 `{data:{...}}` 信封）、内置包（CommonJS `require`：axios/dayjs/crypto）、`betteryeah` SDK（llm/knowledge/database/plugin/subFlow）与 `betterAI` 运行时对象。
+- `tool workflow create/update` 新增 `--version-desc <text>`：发布时透传平台 `version_desc`（版本历史可见，便于区分 CLI 改动）；不传则不带该键，`--no-publish` 时忽略。
+- `--code` / `--input-vars` 的值支持 `@文件路径` 读取；文件不存在时给出指向 `@` 前缀语义的可操作报错，不发请求。
+- 新增 `flow-skeleton`（纯函数骨架生成器）+ `flow-api` 客户端封装；URL path 段的 `flow_id` 统一 `encodeURIComponent`（对齐本仓既有防注入约定）。CLI 不改任何后端，不复刻 servhub 受保护模板名单——受保护 flow 由平台在 update/delete 时拒绝，CLI 如实透传。
+
 ## 0.6.5 (2026-07-14)
 
 - `debug ask` / `debug reproduce` 新增 `--mock <json|@file>`（工具结果 mock，形如 `[{ tool_name, result }]`）与 `--data-overlay <json|@file>`（本轮 `debug_data_overlay` 数据覆盖），发送时透传给 `/v1/debug/chat/agent_message`；`reproduce --dry-run` 输出中同步包含 mock 与 overlay。
@@ -14,6 +37,17 @@
 
 - 修复 `product update` / `product update-sku` 在商品数超过 100 时，对位置靠后的商品报「未找到商品 product_id=xxx」的问题：`findProduct` 由只取第一页（`page:1, pageSize:100`）改为翻页查找，直到命中目标商品或翻完所有页。
 
+## 0.6.3 (2026-06-24 · 未发布，tool 命令组实际随 0.6.7 发布)
+
+- 新增 `tool` 命令组，包装 customer-servhub-api 现有 `/v1/tool` 接口管理 Agent 的自定义/覆盖工具（增删改查）：
+  - `tool list --agent <id>`：列出该 Agent 配置已绑定的工具（custom + system）。
+  - `tool create --agent <id> --name <名称> --key <标识> --source-id <flow_id> [--description] [--source-type] [--invocation-mode] [--input-vars <json>]`：创建绑定工作流（flow）的自定义工具；`source_type` 默认 `flow`、`invocation_mode` 默认 `on_demand`、`workspace_id` 由当前工作空间回填。
+  - `tool update <tool_id> [...]`：局部更新，仅透传实际提供的字段（蛇形键名映射，未提供字段不进请求体）。
+  - `tool delete <tool_id>`：软删除工具。
+  - `tool workflow list [--keyword]` / `tool workflow detail <flow_id>`：发现可绑定工作流及其入参，辅助 `create` 取 `source_id` / 填 `--input-vars`。
+- 非法 `--invocation-mode` 在发请求前本地报错（可选值 `must_invoke` / `on_demand` / `on_demand_async`）。
+- 新增 `tool-api` 客户端封装，仅消费现有接口；CLI 不改变服务端工具表或 sop-engine 的工具执行逻辑。
+
 ## 0.6.2 (2026-06-15)
 
 - `workspace` 新增 `points-consumes` 子命令：分页查询当前工作空间的积分账户消耗流水（`POST /v1/workspace/points_consumes`），支持 `--page` / `--page-size`，CLI 固定传 `debug: true`，返回中包含服务端 `extra` 调试字段。

package/README.md

@@ -29,6 +29,7 @@ pnpm build
 | 服务             | 默认地址                                          |
 | -------------- | --------------------------------------------- |
 | 客服 API         | `https://customer-servhub-api.betteryeah.com` |
+| Dashboard 只读 API | 客服 API 地址追加 `/observability`                  |
 | AI API         | `https://ai-api.betteryeah.com`               |
 | Customer Agent | `https://customer-agent.bantouyan.com`        |
 | Langfuse       | `http://192.168.40.10:3000`                   |
@@ -41,6 +42,8 @@ pnpm build
 cs-cli config set --cs-api https://your-api.example.com
 ```
 
+Dashboard 命令会自动请求该地址下的 `/observability/v1/dashboard/**`。
+
 ### API 地址优先级
 
 每个 API 地址的读取顺序为 `环境变量 > config.json > 内置默认值`。环境变量为 `undefined` 或空字符串 `""` 都视为未设置，继续向下 fallback。
@@ -214,6 +217,26 @@ cs-cli workspace points-consumes-daily --start 2026-04-01 --end 2026-04-23
 | `sa delete --agent <id> --id <SA_ID> --first-label <一级标签> --second-label <二级标签>` | 删除场景动作 |
 | `sa versions --agent <id> --id <SA_ID>` | 查看修改记录 |
 
+### 工具 (`tool`)
+
+| 命令 | 说明 |
+| --- | --- |
+| `tool list --agent <id>` | 列出该 Agent 配置已绑定的工具（custom + system） |
+| `tool create --agent <id> --name <名称> --key <标识> --source-id <flow_id> [--description <描述>] [--source-type <类型>] [--invocation-mode <模式>] [--input-vars <json>]` | 创建绑定工作流（flow）的自定义工具 |
+| `tool update <tool_id> [--name <名称>] [--key <标识>] [--description <描述>] [--source-id <flow_id>] [--invocation-mode <模式>] [--input-vars <json>]` | 更新工具（仅透传实际提供的字段） |
+| `tool delete <tool_id>` | 删除（软删除）指定工具 |
+| `tool workflow list [--keyword <关键词>]` | 搜索可绑定的工作流（flow），取 `source_id` |
+| `tool workflow detail <flow_id>` | 查看工作流入参，辅助填 `--input-vars` |
+| `tool workflow create --name <名称> --code <code\|@file> [--description <描述>] [--input-vars <json\|@file>] [--no-publish] [--code-node-name <名称>] [--version-desc <描述>]` | 创建 START→CODE→END 骨架工作流，CODE 节点承载工具代码（仅 JavaScript），默认自动发布 |
+| `tool workflow update <flow_id> --code <code\|@file> [--no-publish] [--version-desc <描述>]` | 只更新工作流唯一 CODE 节点的代码（其它节点原样保留），默认自动发布 |
+| `tool workflow run <flow_id> [--input <json\|@file>]` | 运行已发布的工作流（HTTP 同步执行），返回 `task_id` / `status` / `run_result` |
+| `tool workflow delete <flow_id> --yes` | 硬删除工作流（不可恢复）；缺 `--yes` 拒绝执行 |
+| `tool workflow describe` | 输出 CODE 节点（JavaScript）使用文档：入口/变量注入/返回值/内置包/SDK，依据官方文档整理 |
+
+`tool` 命令组包装 customer-servhub-api 现有 `/v1/tool` 接口，管理 Agent 的自定义/覆盖工具；CLI 不改变服务端工具表或 sop-engine 的工具执行逻辑。`--invocation-mode` 取值 `must_invoke` / `on_demand`（默认）/ `on_demand_async`，非法值在发请求前本地报错；`tool create --input-vars` 接受 JSON 字符串，形如 `{"order_id":{"description":"订单号","type":"string","required":true}}`，对应工作流入参描述；`workspace_id` 由当前工作空间自动回填。
+
+`tool workflow create/update/run/delete` 直连 BetterYeah 平台（`ai-api`）程序化管理工作流本体：`create` 生成固定 START→CODE→END 三节点骨架并把代码写进 CODE 节点、默认发布，返回 `flow_id` 供 `tool create --source-id` 绑定；`update` 只暴露 CODE 节点代码的修改；`run` 是 HTTP 同步执行（自动经 `GET /v1/workspaces/getKey/{ws}` 用登录态换应用态 Access-Key 再调 `execute_flow`，替代平台画布的 wss 通道），`--input` 的键对应 START `formConfig` 的 `variableName`（默认 `{}`）；`delete` 是硬删除、必须显式 `--yes`。create/update 发布时可用 `--version-desc` 附版本描述（平台版本历史里可见，便于区分 CLI 改动；`--no-publish` 时忽略）。CODE 节点只支持 JavaScript（CommonJS `require`，不支持 ES Module）。`--code` / `--input-vars` 的值以 `@` 开头时按文件路径读取（如 `@./tool.js`）。注意 `tool workflow create --input-vars` 覆盖的是 START 节点的 `formConfig` 入参声明，与 `tool create --input-vars`（工具记录的 `input_var_descriptions`）是不同字段。`tool workflow describe` 输出依据[官方 JavaScript&Python 节点文档](https://ai-docs.betteryeah.com/Flow/节点介绍与配置/JavaScript&Python节点.html)整理的 CODE 节点使用文档（入口 `main()`、变量注入、返回值约定、内置包、BetterYeah SDK），AI 编写工具代码前应先读。
+
 ### 商品管理 (`product`)
 
 | 命令 | 说明 |
@@ -231,6 +254,9 @@ cs-cli workspace points-consumes-daily --start 2026-04-01 --end 2026-04-23
 | `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 supplement list --agent <id> --product-id <商品ID>` | 列出商品补充知识条目（含每条的 question / answer / images / videos） |
+| `product supplement add --agent <id> --product-id <商品ID> --question <Q> --answer <A> [--image <path\|url>...] [--video <path\|url>...] [--dry-run] [--backup <path>]` | 新增一条补充知识（Q/A + 可选图片/视频）；本地媒体自动上传公开 OSS，URL 直写；read-modify-write 保留旧条目 |
+| `product supplement append-media --agent <id> --product-id <商品ID> --index <n> [--image ...] [--video ...] [--dry-run] [--backup <path>]` | 向指定下标条目追加图片/视频，其它条目原样保留、去重合并 |
 
 `product update` 支持更新的字段包括：`卖点`、`补充知识`、`tag`、`参数`、`轮播图识别结果`、`商品详情页识别结果` 等。`--update` 接受 JSON 字符串或 `@文件路径`。
 
@@ -246,6 +272,10 @@ cs-cli workspace points-consumes-daily --start 2026-04-01 --end 2026-04-23
 
 `product related-knowledge` 管理商品详情的“关联知识库”文件级绑定。`--type qa` 对应 FAQ 知识库，`--type common` 对应扩展知识库。`add` / `remove` 会先读取当前绑定，再通过服务端全量替换接口写回；重复添加或移除不存在的文件保持幂等。`--file <文件名>` 会按当前 Agent 的知识库文件列表做精确匹配；文件名不存在或不唯一时，改用 `--file-id` + `--partition-id` 显式模式。
 
+`product supplement` 维护商品「补充知识」的带图/视频问答（结构为 `{ question, answer, images: [URL], videos: [URL] }`），与前端商品详情页的补充知识上传一致。写入采用 **read-modify-write**：先 `product get` 读取并解析当前补充知识，本地合并后再调既有 `/v1/knowledge/product/update`，绝不用新增项覆盖旧条目。`--image` / `--video` 可重复传多个，值可以是**本地文件**（先经 `/v1/upload_sts` 取 STS 凭证上传公开 OSS，key 为 `/ai/knowledge/supplement/${timestamp}_${filename}`）或**已有 http(s) URL**（直写不重复上传）。图片限 `image/*` ≤ 10MB、视频限 `video/*` ≤ 200MB，超限或类型不符在发起上传请求前直接失败。`--dry-run` 只输出将写入的最终 JSON、不落库、不上传；`--backup <path>` 在写前把当前补充知识快照到本地文件。`append-media` 仅向 `--index` 指定的条目追加媒体，去重合并，其它条目原样保留。
+
+单文件上传也可单独用 `media upload`（见下方「媒体上传」小节），拿到公网 URL 后再作为 `--image` / `--video` 的值传入。
+
 ```bash
 # 更新卖点
 cs-cli product update --agent <id> --product-id <商品ID> --update '{"卖点":"新卖点内容"}'
@@ -267,6 +297,39 @@ cs-cli product related-knowledge add --agent <id> --product-id <商品ID> --type
 
 # 显式 ID 模式绑定扩展知识文件
 cs-cli product related-knowledge add --agent <id> --product-id <商品ID> --type common --file-id 622474 --partition-id 12345 --file-name "售后规则.md"
+
+# 查看商品当前补充知识条目
+cs-cli product supplement list --agent <id> --product-id <商品ID>
+
+# 新增一条带图问答（本地图片自动上传，已有 URL 直写）
+cs-cli product supplement add --agent <id> --product-id <商品ID> \
+  --question "尺码怎么选？" --answer "参考尺码表，拍下留言身高体重" \
+  --image ./size-chart.png --image https://xxx.com/a.png
+
+# 先 dry-run 预览最终写入 JSON，不落库
+cs-cli product supplement add --agent <id> --product-id <商品ID> \
+  --question "Q" --answer "A" --video ./demo.mp4 --dry-run
+
+# 向第 0 条补充知识追加媒体，写前备份
+cs-cli product supplement append-media --agent <id> --product-id <商品ID> \
+  --index 0 --image ./extra.png --backup ./supplement-backup.json
+```
+
+
+### 媒体上传 (`media`)
+
+| 命令 | 说明 |
+| --- | --- |
+| `media upload --file <path> [--type <image\|video>] [--path-prefix <prefix>] [--dry-run]` | 上传单个本地图片/视频到公开 OSS，返回可访问 URL |
+
+`media upload` 把单个本地文件上传到公开 OSS（`resource_bucket`），返回公网 URL，供 `product supplement` 的 `--image` / `--video` 复用。凭证走 `GET /v1/upload_sts`（返回 AES-CBC 加密，CLI 内解密），上传 key 为 `<path-prefix>/<timestamp>_<filename>`，`--path-prefix` 默认 `/ai/knowledge/supplement`。`--type` 缺省时按扩展名推断；图片限 `image/*` ≤ 10MB、视频限 `video/*` ≤ 200MB，超限/类型不符在发起上传前直接拒绝。传入的 `--file` 如果本身是 http(s) URL 会被拒绝（无需上传）。`--dry-run` 仅校验并输出将要上传的信息、不实际上传。
+
+```bash
+# 上传本地图片，拿到公网 URL
+cs-cli media upload --file ./banner.png --type image
+
+# 自定义路径前缀 + 预览（不实际上传）
+cs-cli media upload --file ./demo.mp4 --path-prefix /ai/knowledge/supplement --dry-run
 ```