@bty/customer-service-cli 0.6.4 → 0.6.6

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.6.6 (2026-07-17)
+
+- 新增 `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.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。
+- 新增 `debug data snapshot --agent <id> [--product-id <商品ID...>]`：把当前 Agent 的 SOP / 商品 / 活动等数据导出为 `debug_data_overlay` v1 JSON（写 stdout），配合 `--data-overlay @file` 复跑固定数据集；`--product-id` 可重复传多个只导指定商品，不传则分页导出全量商品。
+
 ## 0.6.4 (2026-07-04)
 
 - `conversation transfer-human` 适配服务端 cursor 分页：移除 CLI 暴露的 `--page` 参数，CLI 自动沿 `next_cursor` 拉取全部结果并合并返回，避免深翻页请求压垮数据库。

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。
@@ -231,6 +234,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 +252,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 +277,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
 ```
 
 

package/dist/bin.js

@@ -318,7 +318,7 @@ function toExitCode(err) {
   return 1;
 }
 function createRequest(globalTimeout) {
-  return async function request(baseUrl, path6, options) {
+  return async function request(baseUrl, path7, options) {
     const headers = {
       "Content-Type": "application/json",
       ...options.headers
@@ -346,7 +346,7 @@ function createRequest(globalTimeout) {
     if (workspaceId) {
       headers["workspace-id"] = workspaceId;
     }
-    let url = `${baseUrl}${path6}`;
+    let url = `${baseUrl}${path7}`;
     if (options.query) {
       const params = new URLSearchParams();
       for (const [key, value] of Object.entries(options.query)) {
@@ -485,6 +485,9 @@ function getCustomerServiceUrl() {
   const config = readConfig();
   return config?.customerServiceApiUrl ?? DEFAULT_CS_API_URL;
 }
+function getObservabilityUrl() {
+  return `${getCustomerServiceUrl().replace(/\/+$/, "")}/observability`;
+}
 function getAiApiUrl() {
   const envUrl = process.env.CS_AI_API_URL;
   if (envUrl) return envUrl;
@@ -1401,22 +1404,22 @@ function registerConversationCommand(program2) {
 var DASHBOARD_PREFIX = "/v1/dashboard";
 async function getDashboardSummary(opts) {
   const request = createRequest();
-  const path6 = opts.configId ? `${DASHBOARD_PREFIX}/${opts.configId}/summary` : `${DASHBOARD_PREFIX}/summary`;
+  const path7 = opts.configId ? `${DASHBOARD_PREFIX}/${opts.configId}/summary` : `${DASHBOARD_PREFIX}/summary`;
   const query = {};
   if (opts.startDate) query.start_date = opts.startDate;
   if (opts.endDate) query.end_date = opts.endDate;
   if (opts.channel) query.channel = opts.channel;
-  return request(getCustomerServiceUrl(), path6, { method: "GET", query });
+  return request(getObservabilityUrl(), path7, { method: "GET", query });
 }
 async function getDashboardTrend(opts) {
   const request = createRequest();
-  const path6 = opts.configId ? `${DASHBOARD_PREFIX}/${opts.configId}/trend` : `${DASHBOARD_PREFIX}/trend`;
+  const path7 = opts.configId ? `${DASHBOARD_PREFIX}/${opts.configId}/trend` : `${DASHBOARD_PREFIX}/trend`;
   const query = {};
   if (opts.startDate) query.start_date = opts.startDate;
   if (opts.endDate) query.end_date = opts.endDate;
   if (opts.granularity) query.granularity = opts.granularity;
   if (opts.channel) query.channel = opts.channel;
-  return request(getCustomerServiceUrl(), path6, { method: "GET", query });
+  return request(getObservabilityUrl(), path7, { method: "GET", query });
 }
 async function listShopStatistics(opts) {
   const request = createRequest();
@@ -1424,7 +1427,7 @@ async function listShopStatistics(opts) {
   if (opts.startDate) query.start_date = opts.startDate;
   if (opts.endDate) query.end_date = opts.endDate;
   if (opts.channel) query.channel = opts.channel;
-  return request(getCustomerServiceUrl(), `${DASHBOARD_PREFIX}/shop-statistics`, {
+  return request(getObservabilityUrl(), `${DASHBOARD_PREFIX}/shop-statistics`, {
     method: "GET",
     query
   });
@@ -1435,7 +1438,7 @@ async function getIntentStatistics(opts) {
   if (opts.startDate) query.start_date = opts.startDate;
   if (opts.endDate) query.end_date = opts.endDate;
   return request(
-    getCustomerServiceUrl(),
+    getObservabilityUrl(),
     `${DASHBOARD_PREFIX}/${opts.configId}/intent-statistics`,
     { method: "GET", query }
   );
@@ -1451,7 +1454,7 @@ async function listIntentConversations(opts) {
   if (opts.page) query.page = opts.page;
   if (opts.pageSize) query.page_size = opts.pageSize;
   return request(
-    getCustomerServiceUrl(),
+    getObservabilityUrl(),
     `${DASHBOARD_PREFIX}/${opts.configId}/intent-conversations`,
     { method: "GET", query }
   );
@@ -1539,7 +1542,7 @@ async function exportShopData(opts) {
   if (opts.configIds && opts.configIds.length > 0) body.config_ids = opts.configIds;
   if (opts.channel) body.channel = opts.channel;
   const data = await request(
-    getCustomerServiceUrl(),
+    getObservabilityUrl(),
     `${DASHBOARD_PREFIX}/export`,
     { method: "POST", body }
   );
@@ -1636,12 +1639,12 @@ function registerDashboardCommand(program2) {
         channel: opts.channel
       });
       if (opts.out) {
-        const { path: path6, bytes } = await writeBinaryToFile(
+        const { path: path7, bytes } = await writeBinaryToFile(
           opts.out,
           Buffer.from(result.csv, "utf-8")
         );
         formatOutput(
-          { success: true, data: { path: path6, bytes, count: result.rows.length } },
+          { success: true, data: { path: path7, bytes, count: result.rows.length } },
           program2.opts().table
         );
       } else {
@@ -4062,6 +4065,252 @@ function registerKnowledgeCommand(program2) {
   registerKnowledgeFileBindProductsCommand(knowledge, program2, "common");
 }
 
+// src/lib/media-upload.ts
+import fs9 from "fs";
+import path5 from "path";
+import OSS from "ali-oss";
+
+// src/client/oss-api.ts
+import CryptoJS2 from "crypto-js";
+var STS_SECRET_KEY = "asdb2l0jskjft1q314f3ffjy71k9shj6";
+var IV_BYTES_LEN = 16;
+function decryptStsPayload(ciphertext) {
+  const ciphertextBytes = CryptoJS2.enc.Base64.parse(
+    ciphertext.replaceAll("-", "+").replaceAll("_", "/")
+  );
+  const iv = ciphertextBytes.clone();
+  iv.sigBytes = IV_BYTES_LEN;
+  iv.clamp();
+  const encryptedContent = ciphertextBytes.clone();
+  encryptedContent.words.splice(0, IV_BYTES_LEN / 4);
+  encryptedContent.sigBytes -= IV_BYTES_LEN;
+  const decrypted = CryptoJS2.AES.decrypt(
+    // biome-ignore lint/suspicious/noExplicitAny: CryptoJS CipherParams 结构，仅需 ciphertext 字段
+    { ciphertext: encryptedContent },
+    CryptoJS2.enc.Utf8.parse(STS_SECRET_KEY),
+    {
+      iv,
+      mode: CryptoJS2.mode.CBC,
+      padding: CryptoJS2.pad.Pkcs7
+    }
+  );
+  return decrypted.toString(CryptoJS2.enc.Utf8);
+}
+async function getUploadStsToken() {
+  const request = createRequest();
+  const encrypted = await request(getAiApiUrl(), "/v1/upload_sts", {
+    method: "GET"
+  });
+  if (typeof encrypted !== "string" || encrypted.length === 0) {
+    throw new Error("\u83B7\u53D6 OSS \u4E0A\u4F20\u51ED\u8BC1\u5931\u8D25\uFF1A\u63A5\u53E3\u672A\u8FD4\u56DE\u52A0\u5BC6\u6570\u636E");
+  }
+  let decoded;
+  try {
+    decoded = decryptStsPayload(encrypted);
+  } catch (err) {
+    throw new Error(`OSS \u4E0A\u4F20\u51ED\u8BC1\u89E3\u5BC6\u5931\u8D25\uFF1A${err.message}`);
+  }
+  let token;
+  try {
+    token = JSON.parse(decoded);
+  } catch {
+    throw new Error("OSS \u4E0A\u4F20\u51ED\u8BC1\u89E3\u6790\u5931\u8D25\uFF1A\u89E3\u5BC6\u7ED3\u679C\u4E0D\u662F\u5408\u6CD5 JSON");
+  }
+  if (!token.access_key_id || !token.access_key_secret) {
+    throw new Error("OSS \u4E0A\u4F20\u51ED\u8BC1\u7F3A\u5C11 access_key_id / access_key_secret");
+  }
+  return token;
+}
+
+// src/lib/media-upload.ts
+var IMAGE_MAX_BYTES = 10 * 1024 * 1024;
+var VIDEO_MAX_BYTES = 200 * 1024 * 1024;
+var DEFAULT_PATH_PREFIX = "/ai/knowledge/supplement";
+var IMAGE_EXTS = /* @__PURE__ */ new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".gif",
+  ".webp",
+  ".bmp",
+  ".svg",
+  ".tiff",
+  ".tif",
+  ".ico",
+  ".heic",
+  ".heif",
+  ".avif"
+]);
+var VIDEO_EXTS = /* @__PURE__ */ new Set([
+  ".mp4",
+  ".mov",
+  ".avi",
+  ".mkv",
+  ".webm",
+  ".flv",
+  ".wmv",
+  ".m4v",
+  ".mpeg",
+  ".mpg",
+  ".3gp"
+]);
+function isRemoteUrl(value) {
+  return /^https?:\/\//i.test(value.trim());
+}
+function inferMediaType(filePath) {
+  const ext = path5.extname(filePath).toLowerCase();
+  if (IMAGE_EXTS.has(ext)) return "image";
+  if (VIDEO_EXTS.has(ext)) return "video";
+  return void 0;
+}
+function extMatchesType(filePath, type) {
+  const ext = path5.extname(filePath).toLowerCase();
+  if (type === "image") return !VIDEO_EXTS.has(ext);
+  return !IMAGE_EXTS.has(ext);
+}
+function validateLocalFile(opts) {
+  const { filePath } = opts;
+  const absPath = path5.resolve(filePath);
+  let stat;
+  try {
+    stat = fs9.statSync(absPath);
+  } catch {
+    throw new Error(`\u6587\u4EF6\u4E0D\u5B58\u5728: ${filePath}`);
+  }
+  if (!stat.isFile()) {
+    throw new Error(`\u8DEF\u5F84\u4E0D\u662F\u6587\u4EF6: ${filePath}`);
+  }
+  const type = opts.type ?? inferMediaType(absPath);
+  if (!type) {
+    throw new Error(`\u65E0\u6CD5\u6839\u636E\u6269\u5C55\u540D\u5224\u65AD\u5A92\u4F53\u7C7B\u578B\uFF0C\u8BF7\u663E\u5F0F\u6307\u5B9A --type image|video: ${filePath}`);
+  }
+  if (type !== "image" && type !== "video") {
+    throw new Error(`\u4E0D\u652F\u6301\u7684\u5A92\u4F53\u7C7B\u578B: ${type}\uFF08\u4EC5\u652F\u6301 image / video\uFF09`);
+  }
+  if (!extMatchesType(absPath, type)) {
+    throw new Error(`\u6587\u4EF6\u6269\u5C55\u540D\u4E0E\u58F0\u660E\u7684\u7C7B\u578B ${type} \u4E0D\u5339\u914D: ${filePath}`);
+  }
+  const limit = type === "image" ? IMAGE_MAX_BYTES : VIDEO_MAX_BYTES;
+  if (stat.size > limit) {
+    const limitMb = Math.round(limit / (1024 * 1024));
+    const sizeMb = (stat.size / (1024 * 1024)).toFixed(2);
+    throw new Error(
+      `${type === "image" ? "\u56FE\u7247" : "\u89C6\u9891"}\u5927\u5C0F ${sizeMb}MB \u8D85\u8FC7\u4E0A\u9650 ${limitMb}MB: ${filePath}`
+    );
+  }
+  return {
+    absPath,
+    filename: path5.basename(absPath),
+    type,
+    sizeBytes: stat.size
+  };
+}
+function buildObjectKey(opts) {
+  const ts = opts.timestamp ?? Date.now();
+  const prefix = opts.pathPrefix.replace(/\/+$/, "").replace(/^\/+/, "");
+  return `${prefix}/${ts}_${opts.filename}`;
+}
+var defaultOssPut = async ({ token, bucket, key, bytes }) => {
+  const client = new OSS({
+    region: token.region || "oss-cn-hangzhou",
+    accessKeyId: token.access_key_id,
+    accessKeySecret: token.access_key_secret,
+    stsToken: token.security_token,
+    bucket,
+    secure: true,
+    ...token.endpoint ? { endpoint: token.endpoint } : {}
+  });
+  const normalizedKey = key.replace(/^\/+/, "");
+  const result = await client.put(normalizedKey, bytes);
+  const rawUrl = result?.url ?? result?.res?.requestUrls?.[0];
+  if (!rawUrl) {
+    throw new Error("\u4E0A\u4F20\u6210\u529F\u4F46\u672A\u80FD\u89E3\u6790\u8FD4\u56DE URL");
+  }
+  return rawUrl.split("?")[0];
+};
+var ossPutImpl = defaultOssPut;
+async function uploadLocalFile(opts) {
+  const token = await getUploadStsToken();
+  const bucket = token.resource_bucket;
+  if (!bucket) {
+    throw new Error("OSS \u4E0A\u4F20\u51ED\u8BC1\u7F3A\u5C11 resource_bucket\uFF08\u516C\u5F00\u6876\uFF09\uFF0C\u65E0\u6CD5\u4E0A\u4F20\u516C\u5F00\u5A92\u4F53");
+  }
+  const key = buildObjectKey({
+    pathPrefix: opts.pathPrefix ?? DEFAULT_PATH_PREFIX,
+    filename: opts.file.filename,
+    timestamp: opts.timestamp
+  });
+  const bytes = fs9.readFileSync(opts.file.absPath);
+  try {
+    return await ossPutImpl({ token, bucket, key, bytes });
+  } catch (err) {
+    throw new Error(`OSS \u4E0A\u4F20\u5931\u8D25: ${err.message}`);
+  }
+}
+async function resolveMediaInput(opts) {
+  const value = opts.value.trim();
+  if (isRemoteUrl(value)) {
+    return value;
+  }
+  const file = validateLocalFile({ filePath: value, type: opts.type });
+  if (opts.dryRun) {
+    return `<dry-run:will-upload:${file.filename}>`;
+  }
+  return uploadLocalFile({ file, pathPrefix: opts.pathPrefix });
+}
+
+// src/commands/media.ts
+function registerMediaCommand(program2) {
+  const media = program2.command("media").description(
+    "\u5A92\u4F53\u4E0A\u4F20 \u2014\u2014 \u5C06\u672C\u5730\u56FE\u7247/\u89C6\u9891\u4E0A\u4F20\u5230\u516C\u5F00 OSS \u5E76\u8FD4\u56DE\u516C\u7F51 URL\u3002\u7528\u4E8E\u7EF4\u62A4\u5546\u54C1\u8865\u5145\u77E5\u8BC6\u4E2D\u7684 images / videos\uFF08\u8DEF\u5F84\u524D\u7F00\u4E0E\u524D\u7AEF\u4E00\u81F4\uFF09"
+  );
+  media.command("upload").description(
+    "\u4E0A\u4F20\u5355\u4E2A\u672C\u5730\u56FE\u7247/\u89C6\u9891\u5230\u516C\u5F00 OSS\uFF0C\u8FD4\u56DE\u53EF\u8BBF\u95EE URL\u3002\u56FE\u7247\u9650 10MB\u3001\u89C6\u9891\u9650 200MB\uFF1B\u8D85\u9650\u76F4\u63A5\u62D2\u7EDD\uFF0C\u4E0D\u53D1\u4E0A\u4F20\u8BF7\u6C42"
+  ).requiredOption("--file <path>", "\u672C\u5730\u6587\u4EF6\u8DEF\u5F84").option("--type <type>", "\u5A92\u4F53\u7C7B\u578B: image | video\uFF08\u7F3A\u7701\u6309\u6269\u5C55\u540D\u63A8\u65AD\uFF09").option(
+    "--path-prefix <prefix>",
+    "OSS \u8DEF\u5F84\u524D\u7F00\uFF0C\u6700\u7EC8 key \u4E3A <prefix>/<timestamp>_<filename>",
+    DEFAULT_PATH_PREFIX
+  ).option("--dry-run", "\u4EC5\u6821\u9A8C\u5E76\u8F93\u51FA\u5C06\u8981\u4E0A\u4F20\u7684\u4FE1\u606F\uFF0C\u4E0D\u5B9E\u9645\u4E0A\u4F20").action(async (opts) => {
+    try {
+      if (isRemoteUrl(opts.file)) {
+        throw new Error("--file \u9700\u4E3A\u672C\u5730\u8DEF\u5F84\uFF1B\u5DF2\u662F URL \u7684\u5A92\u4F53\u65E0\u9700\u4E0A\u4F20");
+      }
+      const type = opts.type;
+      if (type && type !== "image" && type !== "video") {
+        throw new Error(`--type \u4EC5\u652F\u6301 image | video\uFF0C\u6536\u5230: ${type}`);
+      }
+      const file = validateLocalFile({ filePath: opts.file, type });
+      if (opts.dryRun) {
+        formatOutput(
+          {
+            success: true,
+            data: {
+              dryRun: true,
+              file: file.absPath,
+              type: file.type,
+              sizeBytes: file.sizeBytes,
+              pathPrefix: opts.pathPrefix
+            }
+          },
+          program2.opts().table
+        );
+        return;
+      }
+      const url = await uploadLocalFile({ file, pathPrefix: opts.pathPrefix });
+      formatOutput(
+        {
+          success: true,
+          data: { url, type: file.type, sizeBytes: file.sizeBytes }
+        },
+        program2.opts().table
+      );
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+}
+
 // src/client/monitor-api.ts
 var MONITOR_PATH_PREFIX = "/v1/operation";
 async function listAgentLifecycle(opts) {
@@ -4954,44 +5203,6 @@ function registerNodeTemplateCommand(program2) {
   });
 }
 
-// src/client/ops-agent-api.ts
-async function listOpsAgentConversations(opts) {
-  const workspaceId = getWorkspaceId(opts.workspaceId);
-  const request = createRequest();
-  const query = {
-    page: opts.page ?? 1,
-    page_size: opts.pageSize ?? 20
-  };
-  if (opts.customerId) query.customer_id = opts.customerId;
-  if (opts.agentId) query.agent_id = opts.agentId;
-  return request(getCustomerServiceUrl(), "/v1/ops-agent/conversations", {
-    method: "GET",
-    query,
-    headers: { "workspace-id": workspaceId }
-  });
-}
-
-// src/commands/ops-agent.ts
-function registerOpsAgentCommand(program2) {
-  const opsAgent = program2.command("ops-agent").description("Ops Agent\uFF08\u5BA2\u670D\u52A9\u624B\uFF09\u67E5\u8BE2\u547D\u4EE4");
-  opsAgent.command("conversations").description(
-    "\u67E5\u8BE2\u5BA2\u670D\u52A9\u624B\u4F1A\u8BDD\u5217\u8868\u3002\u8FD4\u56DE workspace_id\u3001customer_id\u3001title\u3001agent_id\u3001created_at\u3001updated_at"
-  ).option("--customer-id <id>", "\u6309 customer_id \u7B5B\u9009").option("--agent-id <id>", "\u6309 Ops Agent \u914D\u7F6E ID\uFF08customer_agent_config_id\uFF09\u7B5B\u9009").option("--page <number>", "\u9875\u7801", "1").option("--page-size <number>", "\u6BCF\u9875\u6570\u91CF", "20").action(async (opts) => {
-    try {
-      const data = await listOpsAgentConversations({
-        customerId: opts.customerId,
-        agentId: opts.agentId,
-        page: Number(opts.page),
-        pageSize: Number(opts.pageSize)
-      });
-      formatOutput({ success: true, data }, program2.opts().table);
-    } catch (err) {
-      reportCaughtError(err);
-      process.exit(toExitCode(err));
-    }
-  });
-}
-
 // src/client/operations-record-api.ts
 var PATH_PREFIX3 = "/v1/agent_operations_records";
 async function listOperationsRecords(opts) {
@@ -5106,6 +5317,112 @@ function registerOperationsRecordCommand(program2) {
   });
 }
 
+// src/client/ops-agent-api.ts
+async function listOpsAgentConversations(opts) {
+  const workspaceId = getWorkspaceId(opts.workspaceId);
+  const request = createRequest();
+  const query = {
+    page: opts.page ?? 1,
+    page_size: opts.pageSize ?? 20
+  };
+  if (opts.customerId) query.customer_id = opts.customerId;
+  if (opts.agentId) query.agent_id = opts.agentId;
+  return request(getCustomerServiceUrl(), "/v1/ops-agent/conversations", {
+    method: "GET",
+    query,
+    headers: { "workspace-id": workspaceId }
+  });
+}
+
+// src/commands/ops-agent.ts
+function registerOpsAgentCommand(program2) {
+  const opsAgent = program2.command("ops-agent").description("Ops Agent\uFF08\u5BA2\u670D\u52A9\u624B\uFF09\u67E5\u8BE2\u547D\u4EE4");
+  opsAgent.command("conversations").description(
+    "\u67E5\u8BE2\u5BA2\u670D\u52A9\u624B\u4F1A\u8BDD\u5217\u8868\u3002\u8FD4\u56DE workspace_id\u3001customer_id\u3001title\u3001agent_id\u3001created_at\u3001updated_at"
+  ).option("--customer-id <id>", "\u6309 customer_id \u7B5B\u9009").option("--agent-id <id>", "\u6309 Ops Agent \u914D\u7F6E ID\uFF08customer_agent_config_id\uFF09\u7B5B\u9009").option("--page <number>", "\u9875\u7801", "1").option("--page-size <number>", "\u6BCF\u9875\u6570\u91CF", "20").action(async (opts) => {
+    try {
+      const data = await listOpsAgentConversations({
+        customerId: opts.customerId,
+        agentId: opts.agentId,
+        page: Number(opts.page),
+        pageSize: Number(opts.pageSize)
+      });
+      formatOutput({ success: true, data }, program2.opts().table);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+}
+
+// src/commands/product.ts
+import fs10 from "fs";
+
+// src/lib/supplement.ts
+function parseSupplementField(value) {
+  let current = value;
+  for (let i = 0; i < 3; i++) {
+    if (Array.isArray(current)) {
+      return current.filter((it) => it != null && typeof it === "object");
+    }
+    if (typeof current !== "string") return [];
+    const trimmed = current.trim();
+    if (trimmed === "") return [];
+    try {
+      current = JSON.parse(trimmed);
+    } catch {
+      throw new Error(`\u8865\u5145\u77E5\u8BC6 JSON \u89E3\u6790\u5931\u8D25: ${truncate(trimmed)}`);
+    }
+  }
+  return Array.isArray(current) ? current.filter((it) => it != null && typeof it === "object") : [];
+}
+function truncate(s, max = 120) {
+  return s.length > max ? `${s.slice(0, max)}\u2026` : s;
+}
+function mergeUnique(existing, incoming) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const v of [...existing ?? [], ...incoming]) {
+    const t = (v ?? "").trim();
+    if (t === "" || seen.has(t)) continue;
+    seen.add(t);
+    result.push(t);
+  }
+  return result;
+}
+function addSupplementItem(existing, item) {
+  const next = {
+    question: item.question,
+    answer: item.answer
+  };
+  if (item.images && item.images.length > 0) next.images = mergeUnique([], item.images);
+  if (item.videos && item.videos.length > 0) next.videos = mergeUnique([], item.videos);
+  return [...existing, next];
+}
+function appendMediaToItem(existing, opts) {
+  if (!Number.isInteger(opts.index) || opts.index < 0 || opts.index >= existing.length) {
+    throw new Error(`\u8865\u5145\u77E5\u8BC6\u6761\u76EE\u4E0B\u6807\u8D8A\u754C: index=${opts.index}\uFF08\u5F53\u524D\u5171 ${existing.length} \u6761\uFF09`);
+  }
+  return existing.map((it, i) => {
+    if (i !== opts.index) return it;
+    const updated = { ...it };
+    if (opts.images && opts.images.length > 0) {
+      updated.images = mergeUnique(asStringArray(it.images), opts.images);
+    }
+    if (opts.videos && opts.videos.length > 0) {
+      updated.videos = mergeUnique(asStringArray(it.videos), opts.videos);
+    }
+    return updated;
+  });
+}
+function asStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === "string");
+}
+function serializeSupplement(items) {
+  return JSON.stringify(items);
+}
+
 // src/commands/product.ts
 async function getDbId(agentConfigId) {
   const agent = await getAgent(agentConfigId);
@@ -5130,6 +5447,41 @@ async function findProduct(agentConfigId, productId) {
     }
   }
 }
+async function loadProductSupplement(agentConfigId, productId) {
+  const [dbId, matched] = await Promise.all([
+    getDbId(agentConfigId),
+    findProduct(agentConfigId, productId)
+  ]);
+  const detail = await getProductDetail({
+    agentConfigId,
+    dbId,
+    productId
+  });
+  const items = parseSupplementField(detail.\u8865\u5145\u77E5\u8BC6);
+  return {
+    dbId,
+    dataId: detail.id,
+    knowledgeId: matched.knowledge_id,
+    items,
+    raw: detail.\u8865\u5145\u77E5\u8BC6
+  };
+}
+async function writeProductSupplement(ctx, items) {
+  return updateProduct({
+    dataId: ctx.dataId,
+    knowledgeId: ctx.knowledgeId,
+    dbId: ctx.dbId,
+    updateDict: { \u8865\u5145\u77E5\u8BC6: serializeSupplement(items) }
+  });
+}
+async function resolveMediaList(values, type, dryRun) {
+  if (!values || values.length === 0) return [];
+  const urls = [];
+  for (const value of values) {
+    urls.push(await resolveMediaInput({ value, type, dryRun }));
+  }
+  return urls;
+}
 function registerProductCommand(program2) {
   const product = program2.command("product").description(
     "\u5546\u54C1\u77E5\u8BC6\u5E93\u7BA1\u7406 \u2014\u2014 Agent \u5173\u8054\u7684\u5546\u54C1\u6570\u636E\uFF08\u5356\u70B9\u3001\u8865\u5145\u77E5\u8BC6\u3001SKU\u3001\u53C2\u6570\u3001\u56FE\u7247\u8BC6\u522B\u7ED3\u679C\u7B49\uFF09\u3002Agent \u56DE\u7B54\u5546\u54C1\u76F8\u5173\u95EE\u9898\u65F6\u4F9D\u8D56\u6B64\u6570\u636E\u6E90"
@@ -5315,8 +5667,117 @@ function registerProductCommand(program2) {
       process.exit(toExitCode(err));
     }
   });
+  registerProductSupplementCommand(product, program2);
   registerProductRelatedKnowledgeCommand(product, program2);
 }
+function registerProductSupplementCommand(product, program2) {
+  const supplement = product.command("supplement").description(
+    "\u5546\u54C1\u8865\u5145\u77E5\u8BC6\uFF08\u95EE\u7B54 + \u56FE\u7247/\u89C6\u9891\uFF09\u7EF4\u62A4\u3002\u5199\u5165\u91C7\u7528 read-modify-write\uFF0C\u53EA\u5408\u5E76\u76EE\u6807\u6761\u76EE\uFF0C\u4E0D\u8986\u76D6\u5176\u5B83\u8865\u5145\u77E5\u8BC6"
+  );
+  supplement.command("list").description("\u5217\u51FA\u5546\u54C1\u5F53\u524D\u8865\u5145\u77E5\u8BC6\u6761\u76EE\uFF08\u542B\u6BCF\u6761\u7684 question / answer / images / videos\uFF09").requiredOption("--agent <config_id>", "Agent \u914D\u7F6E ID\uFF08\u4ECE agent list \u83B7\u53D6\uFF09").requiredOption("--product-id <product_id>", "\u5546\u54C1 ID\uFF08\u4ECE product list \u83B7\u53D6\uFF09").action(async (opts) => {
+    try {
+      const ctx = await loadProductSupplement(opts.agent, opts.productId);
+      formatOutput(
+        {
+          success: true,
+          data: {
+            product_id: opts.productId,
+            count: ctx.items.length,
+            \u8865\u5145\u77E5\u8BC6: ctx.items
+          }
+        },
+        program2.opts().table
+      );
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  supplement.command("add").description(
+    "\u65B0\u589E\u4E00\u6761\u8865\u5145\u77E5\u8BC6\uFF08Q/A + \u53EF\u9009\u56FE\u7247/\u89C6\u9891\uFF09\u3002--image / --video \u652F\u6301\u672C\u5730\u6587\u4EF6\uFF08\u81EA\u52A8\u4E0A\u4F20\u516C\u5F00 OSS\uFF09\u6216\u5DF2\u6709 URL\uFF08\u76F4\u5199\uFF09\u3002read-modify-write\uFF1A\u4FDD\u7559\u5168\u90E8\u65E2\u6709\u6761\u76EE\uFF0C\u4EC5\u8FFD\u52A0\u65B0\u6761\u76EE"
+  ).requiredOption("--agent <config_id>", "Agent \u914D\u7F6E ID\uFF08\u4ECE agent list \u83B7\u53D6\uFF09").requiredOption("--product-id <product_id>", "\u5546\u54C1 ID\uFF08\u4ECE product list \u83B7\u53D6\uFF09").requiredOption("--question <text>", "\u5E38\u95EE\u95EE\u9898").requiredOption("--answer <text>", "\u56DE\u7B54\u5185\u5BB9").option("--image <path-or-url...>", "\u56FE\u7247\u672C\u5730\u8DEF\u5F84\u6216 URL\uFF08\u53EF\u591A\u4E2A\uFF09").option("--video <path-or-url...>", "\u89C6\u9891\u672C\u5730\u8DEF\u5F84\u6216 URL\uFF08\u53EF\u591A\u4E2A\uFF09").option("--dry-run", "\u53EA\u8F93\u51FA\u6700\u7EC8\u5C06\u5199\u5165\u7684 JSON\uFF0C\u4E0D\u5B9E\u9645\u4E0A\u4F20/\u66F4\u65B0").option("--backup <path>", "\u5199\u5165\u524D\u5C06\u66F4\u65B0\u524D\u8865\u5145\u77E5\u8BC6\u5FEB\u7167\u4FDD\u5B58\u5230\u6307\u5B9A\u6587\u4EF6").action(async (opts) => {
+    try {
+      const ctx = await loadProductSupplement(opts.agent, opts.productId);
+      maybeWriteBackup(opts.backup, ctx.items);
+      const images = await resolveMediaList(opts.image, "image", Boolean(opts.dryRun));
+      const videos = await resolveMediaList(opts.video, "video", Boolean(opts.dryRun));
+      const nextItems = addSupplementItem(ctx.items, {
+        question: opts.question,
+        answer: opts.answer,
+        images,
+        videos
+      });
+      if (opts.dryRun) {
+        formatOutput(
+          {
+            success: true,
+            data: {
+              dryRun: true,
+              before: ctx.items,
+              after: nextItems,
+              update_dict: { \u8865\u5145\u77E5\u8BC6: serializeSupplement(nextItems) }
+            }
+          },
+          program2.opts().table
+        );
+        return;
+      }
+      const data = await writeProductSupplement(ctx, nextItems);
+      formatOutput(
+        { success: true, data: { updated: true, count: nextItems.length, result: data } },
+        program2.opts().table
+      );
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  supplement.command("append-media").description(
+    "\u5411\u6307\u5B9A\u4E0B\u6807\u7684\u5DF2\u6709\u8865\u5145\u77E5\u8BC6\u6761\u76EE\u8FFD\u52A0\u56FE\u7247/\u89C6\u9891\u3002\u539F\u6709 question / answer / images / videos \u53CA\u5176\u5B83\u6761\u76EE\u5747\u4E0D\u4E22\u5931"
+  ).requiredOption("--agent <config_id>", "Agent \u914D\u7F6E ID\uFF08\u4ECE agent list \u83B7\u53D6\uFF09").requiredOption("--product-id <product_id>", "\u5546\u54C1 ID\uFF08\u4ECE product list \u83B7\u53D6\uFF09").requiredOption("--index <number>", "\u76EE\u6807\u8865\u5145\u77E5\u8BC6\u6761\u76EE\u4E0B\u6807\uFF08\u4ECE 0 \u5F00\u59CB\uFF0C\u89C1 supplement list\uFF09").option("--image <path-or-url...>", "\u56FE\u7247\u672C\u5730\u8DEF\u5F84\u6216 URL\uFF08\u53EF\u591A\u4E2A\uFF09").option("--video <path-or-url...>", "\u89C6\u9891\u672C\u5730\u8DEF\u5F84\u6216 URL\uFF08\u53EF\u591A\u4E2A\uFF09").option("--dry-run", "\u53EA\u8F93\u51FA\u6700\u7EC8\u5C06\u5199\u5165\u7684 JSON\uFF0C\u4E0D\u5B9E\u9645\u4E0A\u4F20/\u66F4\u65B0").option("--backup <path>", "\u5199\u5165\u524D\u5C06\u66F4\u65B0\u524D\u8865\u5145\u77E5\u8BC6\u5FEB\u7167\u4FDD\u5B58\u5230\u6307\u5B9A\u6587\u4EF6").action(async (opts) => {
+    try {
+      const index = Number(opts.index);
+      if (!Number.isInteger(index) || index < 0) {
+        throw new Error(`--index \u5FC5\u987B\u4E3A\u975E\u8D1F\u6574\u6570\uFF0C\u6536\u5230: ${opts.index}`);
+      }
+      if ((!opts.image || opts.image.length === 0) && (!opts.video || opts.video.length === 0)) {
+        throw new Error("\u8BF7\u81F3\u5C11\u63D0\u4F9B\u4E00\u4E2A --image \u6216 --video");
+      }
+      const ctx = await loadProductSupplement(opts.agent, opts.productId);
+      maybeWriteBackup(opts.backup, ctx.items);
+      const images = await resolveMediaList(opts.image, "image", Boolean(opts.dryRun));
+      const videos = await resolveMediaList(opts.video, "video", Boolean(opts.dryRun));
+      const nextItems = appendMediaToItem(ctx.items, { index, images, videos });
+      if (opts.dryRun) {
+        formatOutput(
+          {
+            success: true,
+            data: {
+              dryRun: true,
+              before: ctx.items,
+              after: nextItems,
+              update_dict: { \u8865\u5145\u77E5\u8BC6: serializeSupplement(nextItems) }
+            }
+          },
+          program2.opts().table
+        );
+        return;
+      }
+      const data = await writeProductSupplement(ctx, nextItems);
+      formatOutput(
+        { success: true, data: { updated: true, index, result: data } },
+        program2.opts().table
+      );
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+}
+function maybeWriteBackup(backupPath, items) {
+  if (!backupPath) return;
+  fs10.writeFileSync(backupPath, JSON.stringify(items, null, 2), "utf-8");
+}
 
 // src/client/repair-record-api.ts
 var PATH_PREFIX4 = "/api/repair-records";
@@ -5534,7 +5995,7 @@ function registerSACommand(program2) {
 }
 
 // src/commands/special-project.ts
-import fs9 from "fs";
+import fs11 from "fs";
 
 // src/client/special-project-api.ts
 async function createSpecialProject(input) {
@@ -5577,7 +6038,7 @@ async function upsertSpecialProjects(items, apply) {
 // src/commands/special-project.ts
 function readJsonArg(value) {
   if (value.startsWith("@")) {
-    return fs9.readFileSync(value.slice(1), "utf-8");
+    return fs11.readFileSync(value.slice(1), "utf-8");
   }
   return value;
 }
@@ -5654,11 +6115,11 @@ function registerSpecialProjectCommand(program2) {
 }
 
 // src/commands/testset.ts
-import fs11 from "fs";
+import fs13 from "fs";
 
 // src/client/testset-api.ts
-import fs10 from "fs";
-import path5 from "path";
+import fs12 from "fs";
+import path6 from "path";
 function unwrapPaginated(raw, fallbackPageSize) {
   return {
     items: Array.isArray(raw?.data) ? raw?.data : [],
@@ -5686,14 +6147,14 @@ async function listTestSets(query) {
 }
 async function createTestSetFromFile(input) {
   const request = createRequest();
-  const fileBytes = fs10.readFileSync(input.filePath);
+  const fileBytes = fs12.readFileSync(input.filePath);
   const formData = new FormData();
   formData.append(
     "file",
     new Blob([fileBytes], {
       type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
     }),
-    path5.basename(input.filePath)
+    path6.basename(input.filePath)
   );
   return request(getCustomerServiceUrl(), "/v1/test_sets/file/upload", {
     method: "POST",
@@ -6190,7 +6651,7 @@ function readPromptInput(value) {
     if (!filePath) {
       throw new Error("File path cannot be empty after @");
     }
-    return fs11.readFileSync(filePath, "utf-8");
+    return fs13.readFileSync(filePath, "utf-8");
   }
   return value;
 }
@@ -6225,7 +6686,7 @@ function registerTestsetCommand(program2) {
   });
   testset.command("create").description("\u901A\u8FC7 xlsx \u6587\u4EF6\u521B\u5EFA\u6D4B\u8BD5\u96C6").requiredOption("--customer-agent-config-id <id>", "Agent \u914D\u7F6E ID\uFF08\u5FC5\u586B\uFF0C\u4E0E\u540E\u7AEF\u5951\u7EA6\u5BF9\u9F50\uFF09").requiredOption("--file <path>", "\u6D4B\u8BD5\u96C6 xlsx \u6587\u4EF6\u8DEF\u5F84").option("--name <text>", "\u6D4B\u8BD5\u96C6\u540D\u79F0\uFF1B\u4E0D\u4F20\u5219\u540E\u7AEF\u53D6\u6587\u4EF6\u540D").option("--description <text>", "\u6D4B\u8BD5\u96C6\u63CF\u8FF0").option("--use-type <text>", "\u6587\u4EF6\u7528\u9014\u6807\u8BC6").action(async (opts) => {
     try {
-      if (!fs11.existsSync(opts.file)) {
+      if (!fs13.existsSync(opts.file)) {
         outputError(1, `\u6587\u4EF6\u4E0D\u5B58\u5728: ${opts.file}`);
         process.exit(1);
       }
@@ -6414,6 +6875,7 @@ registerAgentCommand(program);
 registerOpsAgentCommand(program);
 registerSACommand(program);
 registerProductCommand(program);
+registerMediaCommand(program);
 registerKnowledgeCommand(program);
 registerActivityCommand(program);
 registerIssueCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bty/customer-service-cli",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "AI Customer Service CLI - Agent friendly",
   "type": "module",
   "main": "./dist/bin.js",
@@ -12,11 +12,13 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
+    "ali-oss": "^6.22.0",
     "cli-table3": "^0.6.0",
     "commander": "^14.0.0",
     "crypto-js": "^4.1.1"
   },
   "devDependencies": {
+    "@types/ali-oss": "^6.16.11",
     "@types/crypto-js": "^4.1.1",
     "@types/node": "^22.10.0",
     "tsup": "^8.0.0",