@bty/customer-service-cli 0.6.5 → 0.6.7

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);
       }
@@ -6320,6 +6781,563 @@ function registerTestsetCommand(program2) {
   registerExportCommand(program2, testset);
 }
 
+// src/commands/tool.ts
+import fs14 from "fs";
+
+// src/client/flow-api.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/client/flow-skeleton.ts
+import { randomUUID } from "crypto";
+var DEFAULT_FORM_CONFIG = [
+  {
+    type: "json",
+    label: "\u4E0A\u4E0B\u6587",
+    required: true,
+    placeholder: "\u8BF7\u8F93\u5165",
+    variableName: "dialogue",
+    cascadeFields: [],
+    isCascadeField: false
+  }
+];
+function buildEdge(source, target) {
+  return {
+    id: `${source}-${target}`,
+    type: "insert",
+    source,
+    target,
+    interactionWidth: 80,
+    style: {
+      stroke: "#C0C3D1",
+      strokeWidth: 2,
+      strokeLinecap: "round",
+      strokeLinejoin: "round"
+    }
+  };
+}
+function buildFlowSkeleton(opts) {
+  const startId = randomUUID();
+  const codeId = randomUUID();
+  const endId = randomUUID();
+  const codeName = opts.codeNodeName ?? "javascript_1";
+  const startNode = {
+    id: startId,
+    type: "START",
+    actionType: "TRIGGER",
+    name: "start",
+    relation: null,
+    isEnable: true,
+    layout: { width: 420, height: 311, position: { x: 0, y: 0 } },
+    data: {
+      name: "start",
+      type: "form",
+      actionType: "TRIGGER",
+      inputs: {},
+      isEnable: true,
+      relation: null,
+      conditions: [],
+      packageName: "",
+      sortCopyIndex: -1,
+      formConfig: opts.inputVars ?? DEFAULT_FORM_CONFIG
+    }
+  };
+  const codeNode = {
+    id: codeId,
+    type: "CODE",
+    actionType: "CODE",
+    name: codeName,
+    relation: null,
+    isEnable: true,
+    layout: { width: 420, height: 435, position: { x: 544, y: 0 } },
+    data: {
+      name: codeName,
+      type: null,
+      actionType: "CODE",
+      inputs: {
+        code: opts.code,
+        desc: opts.description ?? "",
+        version: 1,
+        language: "javascript"
+      },
+      isEnable: true,
+      relation: null,
+      conditions: [],
+      packageName: "",
+      formConfig: null,
+      sortCopyIndex: 1
+    }
+  };
+  const endNode = {
+    id: endId,
+    type: "END",
+    actionType: "END",
+    name: "output",
+    relation: null,
+    isEnable: true,
+    layout: { width: 420, height: 98, position: { x: 1088, y: 0 } },
+    data: {
+      name: "output",
+      type: null,
+      actionType: "END",
+      inputs: {},
+      isEnable: true,
+      relation: null,
+      conditions: [],
+      packageName: "",
+      formConfig: null,
+      sortCopyIndex: -1
+    }
+  };
+  return {
+    nodes: [startNode, codeNode, endNode],
+    edges: [buildEdge(startId, codeId), buildEdge(codeId, endId)]
+  };
+}
+
+// src/client/flow-api.ts
+var CODE_NODE_GUIDE = `# CODE \u8282\u70B9\u7F16\u5199\u6307\u5357\uFF08JavaScript\uFF09
+
+\u81EA\u5B9A\u4E49\u5DE5\u5177 = \u4E00\u4E2A flow\uFF0C\u6838\u5FC3\u662F\u5176\u4E2D\u7684 CODE \u8282\u70B9\u3002\u672C CLI \u521B\u5EFA/\u66F4\u65B0\u7684 CODE \u8282\u70B9\u53EA\u652F\u6301 JavaScript\u3002
+\u5B98\u65B9\u6587\u6863\uFF1Ahttps://ai-docs.betteryeah.com/Flow/\u8282\u70B9\u4ECB\u7ECD\u4E0E\u914D\u7F6E/JavaScript&Python\u8282\u70B9.html
+
+## 1. \u5165\u53E3\uFF1Aasync function main()
+
+\u5FC5\u987B\u7F16\u5199\u540D\u4E3A main \u7684\u5F02\u6B65\u5165\u53E3\u51FD\u6570\uFF08\u9876\u5C42 async function main()\uFF09\u3002
+main() \u7684\u8FD4\u56DE\u503C\u5373\u5DE5\u5177\u4EA7\u51FA\uFF08\u4E1A\u52A1\u7ED3\u679C\uFF09\uFF0C\u4F1A\u88AB\u5E73\u53F0\u56DE\u586B\u7ED9 Agent \u4F5C\u4E3A\u8BE5\u5DE5\u5177\u7684\u8F93\u51FA\uFF1B
+\u6CA1\u6709 return \u5219\u8F93\u51FA\u4E3A null\u3002
+
+## 2. \u5165\u53C2\u4E0E\u53D8\u91CF\u6CE8\u5165
+
+\u524D\u7F6E\u8282\u70B9\u7684\u53D8\u91CF\u5DF2\u5185\u7F6E\u5728\u4EE3\u7801\u6267\u884C\u73AF\u5883\u4E2D\uFF0C\u76F4\u63A5\u4EE5\u540C\u540D\u5168\u5C40\u53D8\u91CF\u4F7F\u7528\u3001\u65E0\u9700\u58F0\u660E\uFF1A
+- START \u8282\u70B9 formConfig \u58F0\u660E\u7684\u6BCF\u4E2A variableName \u90FD\u4F1A\u6CE8\u5165\u4E3A\u540C\u540D\u5168\u5C40\u53D8\u91CF\u3002
+  \u9ED8\u8BA4\u53EA\u58F0\u660E\u4E00\u4E2A dialogue\uFF08\u4E0A\u4E0B\u6587\uFF0C\u7C7B\u578B json\uFF09\u2014\u2014\u5373\u6574\u6BB5\u5BF9\u8BDD\u4E0A\u4E0B\u6587\uFF0C\u76F4\u63A5\u5F15\u7528 dialogue \u5373\u53EF\u3002
+  \u8981\u52A0\u5165\u53C2\u5C31\u6539 formConfig\uFF08\u521B\u5EFA\u65F6\u7528 --input-vars \u8986\u76D6\uFF09\u3002
+- \u4E0A\u6E38\u5176\u5B83\u8282\u70B9\u7684\u8F93\u51FA\u540C\u6837\u6309\u8282\u70B9\u540D\u6CE8\u5165\uFF08\u5982 llm_1\uFF09\u3002\u672C CLI \u751F\u6210\u7684\u9AA8\u67B6\u53EA\u6709 START\u2192CODE\u2192END\uFF0C
+  \u6240\u4EE5\u901A\u5E38\u53EA\u7528\u5F97\u5230 formConfig \u91CC\u7684\u53D8\u91CF\u3002
+
+## 3. \u8FD4\u56DE\u503C
+
+\u8FD4\u56DE**\u88F8\u7684** object / list \u5373\u53EF\uFF0C**\u4E0D\u8981\u518D\u5957\u4E00\u5C42 {data:{...}} \u6216 {data:{run_result:[...]}} \u4FE1\u5C01**\u3002
+\u5E73\u53F0\u6309\u88F8\u8FD4\u56DE\u503C\u6D88\u8D39\uFF1B\u591A\u5957\u7684\u4FE1\u5C01\u4F1A\u8BA9\u4E0B\u6E38\u5BCC\u5316/\u89E3\u6790\u6309\u5B57\u9762 key \u53D6\u503C\u800C\u9759\u9ED8\u5931\u8D25\uFF08\u5DF2\u53D1\u751F\u8FC7\u7EBF\u4E0A\u4E8B\u6545\uFF09\u3002
+\u8FD4\u56DE\u503C\u5FC5\u987B\u53EF\u5E8F\u5217\u5316\u2014\u2014\u4E0D\u80FD\u662F\u6B63\u5219\u3001\u51FD\u6570\u7B49\u4E0D\u53EF\u5E8F\u5217\u5316\u5BF9\u8C61\u3002
+
+## 4. \u5185\u7F6E\u5305\uFF08CommonJS\uFF09
+
+\u73AF\u5883\u5185\u7F6E\u5E38\u7528\u5305\uFF0C\u7528 require \u5BFC\u5165\uFF08\u4E0D\u652F\u6301 ES Module \u7684 import\uFF09\uFF1A
+
+  const axios = require('axios');    // HTTP \u8BF7\u6C42
+  const dayjs = require('dayjs');    // \u65E5\u671F\u5904\u7406
+  const crypto = require('crypto');  // \u52A0\u5BC6/\u6458\u8981
+
+## 5. BetterYeah SDK
+
+  const Betteryeah = require('betteryeah').default;
+  const betteryeah = new Betteryeah();
+
+\u6838\u5FC3\u6A21\u5757\uFF08\u5168\u90E8 await \u8C03\u7528\uFF09\uFF1A
+- betteryeah.llm.chat({ systemPrompt, model, jsonMode, temperature, messages })\uFF1A\u8C03\u5927\u6A21\u578B
+- betteryeah.knowledge.searchKnowledge / insertKnowledge\uFF1A\u77E5\u8BC6\u5E93\u67E5\u8BE2/\u63D2\u5165
+- betteryeah.database.executeDatabase({ databaseId, executableSql })\uFF1A\u6267\u884C SQL
+- betteryeah.plugin.*\uFF1A\u641C\u7D22\uFF08search.googleSearch/bingSearch/aiSearch\uFF09\u3001\u89E3\u6790\uFF08parsing.web/excel/pdf/...\uFF09\u3001
+  \u8BC6\u56FE\u751F\u56FE\uFF08image.vision/generate/ocr\uFF09\u7B49
+- betteryeah.subFlow.execute(flowId, parameter)\uFF1A\u8C03\u7528\u5176\u5B83\u5DF2\u53D1\u5E03\u5DE5\u4F5C\u6D41
+
+SDK \u7EDF\u4E00\u54CD\u5E94\u5F62\u72B6 { code, success, message, data, usage }\uFF0C\u52A1\u5FC5\u68C0\u67E5 success\uFF1A
+
+  if (!result.success) throw new Error(result.message ?? '\u6267\u884C\u51FA\u9519');
+
+## 6. betterAI \u8FD0\u884C\u65F6\u5BF9\u8C61
+
+- betterAI.store.set(key, value) / betterAI.store.get(key)\uFF1Aflow \u751F\u547D\u5468\u671F\u5185\u5171\u4EAB\u6570\u636E
+- betterAI.session.*\uFF1A\u4F1A\u8BDD\u5143\u4FE1\u606F\u4E0E\u6301\u4E45\u5316\u8BB0\u5FC6\uFF08sessionId / conversationId / metaData / \u804A\u5929\u8BB0\u5F55\uFF09
+- betterAI.agent.chat.*\uFF1A\u5411 Agent \u4F1A\u8BDD\u63A8\u9001\u6D88\u606F/\u901A\u77E5
+
+## 7. \u5B8C\u6574\u793A\u4F8B
+
+  async function main() {
+    const ctx = dialogue;        // \u6765\u81EA START formConfig \u7684\u5168\u5C40\u53D8\u91CF
+    // ...\u4F60\u7684\u4E1A\u52A1\u903B\u8F91...
+    return { ok: true };         // main \u7684\u8FD4\u56DE\u503C\u5373\u5DE5\u5177\u4EA7\u51FA\uFF08\u88F8\u5BF9\u8C61\uFF0C\u52FF\u5957\u4FE1\u5C01\uFF09
+  }
+
+## 8. \u6CE8\u610F\u4E8B\u9879
+
+- \u77E5\u8BC6\u5E93 ID / \u6587\u4EF6 ID / \u6570\u636E\u5E93 ID \u7B49\u5728\u5E73\u53F0\u5DE6\u4FA7\u8D44\u6E90\u6811\u7528\u590D\u5236\u6309\u94AE\u83B7\u53D6\u3002
+- SDK \u5404\u6A21\u5757\u5B8C\u6574\u53C2\u6570\u4E0E\u66F4\u591A\u793A\u4F8B\u4EE5\u4E0A\u65B9\u5B98\u65B9\u6587\u6863\u4E3A\u51C6\u3002
+`;
+async function createFlow(opts) {
+  const { nodes, edges } = buildFlowSkeleton({
+    code: opts.code,
+    description: opts.description,
+    inputVars: opts.inputVars,
+    codeNodeName: opts.codeNodeName
+  });
+  const request = createRequest();
+  const res = await request(
+    getAiApiUrl(),
+    "/v1/applications",
+    {
+      method: "POST",
+      query: { workspaceId: getWorkspaceId() },
+      headers: {
+        accept: "application/json",
+        "application-id": randomUUID2().replace(/-/g, "")
+      },
+      body: {
+        icon: "\u{1F33C}",
+        color: "#ADE9CE",
+        description: opts.description ?? "\u6682\u65E0\u63CF\u8FF0",
+        name: opts.name,
+        applicationType: "AI",
+        config: JSON.stringify({ nodes, edges }),
+        channel_type: "flow"
+      }
+    }
+  );
+  const flowId = res.flowId;
+  const versionId = res.versionId;
+  const publish = opts.publish !== false;
+  if (publish) {
+    await request(getAiApiUrl(), "/v1/flow/publish", {
+      method: "POST",
+      body: {
+        draftVersionId: versionId,
+        ...opts.versionDesc ? { version_desc: opts.versionDesc } : {}
+      }
+    });
+  }
+  return { flow_id: flowId, version_id: versionId, published: publish };
+}
+async function getFlowConfig(opts) {
+  const request = createRequest();
+  return request(getAiApiUrl(), `/v1/applications/${encodeURIComponent(opts.flowId)}`, {
+    method: "GET"
+  });
+}
+async function updateFlowCode(opts) {
+  const data = await getFlowConfig({ flowId: opts.flowId });
+  const config = data.config;
+  if (!config || typeof config !== "object" || !Array.isArray(config.nodes)) {
+    throw new APIError(1, "flow config \u5F62\u72B6\u5F02\u5E38\uFF1A\u7F3A nodes \u6570\u7EC4\uFF0C\u65E0\u6CD5\u5B9A\u4F4D CODE \u8282\u70B9");
+  }
+  const codeNodes = config.nodes.filter(
+    // biome-ignore lint/suspicious/noExplicitAny: 同上
+    (n) => n.type === "CODE"
+  );
+  if (codeNodes.length !== 1) {
+    throw new APIError(1, `\u672A\u627E\u5230\u552F\u4E00 CODE \u8282\u70B9\uFF08\u627E\u5230 ${codeNodes.length} \u4E2A\uFF09`);
+  }
+  codeNodes[0].data.inputs.code = opts.code;
+  const request = createRequest();
+  await request(getAiApiUrl(), "/v1/flow/update", {
+    method: "POST",
+    body: { appId: opts.flowId, config, flowId: opts.flowId }
+  });
+  const publish = opts.publish !== false;
+  if (publish) {
+    const draft = await request(
+      getAiApiUrl(),
+      `/v1/flow/draft/${encodeURIComponent(opts.flowId)}`,
+      { method: "GET" }
+    );
+    await request(getAiApiUrl(), "/v1/flow/publish", {
+      method: "POST",
+      body: {
+        draftVersionId: draft.version_id,
+        ...opts.versionDesc ? { version_desc: opts.versionDesc } : {}
+      }
+    });
+  }
+  return { flow_id: opts.flowId, published: publish };
+}
+async function getWorkspaceAccessKey() {
+  const request = createRequest();
+  const workspaceId = getWorkspaceId();
+  return request(
+    getAiApiUrl(),
+    `/v1/workspaces/getKey/${encodeURIComponent(workspaceId)}`,
+    { method: "GET" }
+  );
+}
+async function runFlow(opts) {
+  const accessKey = await getWorkspaceAccessKey();
+  const request = createRequest();
+  return request(
+    getAiApiUrl(),
+    `/v1/public_api/rest_api/${encodeURIComponent(opts.flowId)}/execute_flow`,
+    {
+      method: "POST",
+      headers: { "Access-Key": accessKey },
+      body: { inputs: opts.inputs ?? {}, async_execute: false }
+    }
+  );
+}
+async function deleteFlow(opts) {
+  const request = createRequest();
+  await request(getAiApiUrl(), `/v1/applications/${encodeURIComponent(opts.flowId)}`, {
+    method: "DELETE"
+  });
+  return { flow_id: opts.flowId };
+}
+
+// src/client/tool-api.ts
+var VALID_INVOCATION_MODES = ["must_invoke", "on_demand", "on_demand_async"];
+function assertInvocationMode(mode) {
+  if (!VALID_INVOCATION_MODES.includes(mode)) {
+    throw new APIError(
+      1,
+      "invocation_mode \u975E\u6CD5\uFF0C\u53EF\u9009\u503C\uFF1Amust_invoke / on_demand / on_demand_async"
+    );
+  }
+}
+async function listToolsByConfig(opts) {
+  const request = createRequest();
+  return request(getCustomerServiceUrl(), "/v1/tool/by-config", {
+    method: "GET",
+    query: { customer_agent_config_id: opts.agentConfigId }
+  });
+}
+async function createCustomTool(opts) {
+  if (opts.invocationMode !== void 0) {
+    assertInvocationMode(opts.invocationMode);
+  }
+  const request = createRequest();
+  return request(getCustomerServiceUrl(), "/v1/tool/custom", {
+    method: "POST",
+    body: {
+      name: opts.name,
+      key: opts.key,
+      workspace_id: getWorkspaceId(),
+      customer_agent_config_id: opts.agentConfigId,
+      source_id: opts.sourceId,
+      source_type: opts.sourceType ?? "flow",
+      description: opts.description ?? "",
+      invocation_mode: opts.invocationMode ?? "on_demand",
+      input_var_descriptions: opts.inputVarDescriptions ?? {}
+    }
+  });
+}
+async function updateTool(opts) {
+  if (opts.invocationMode !== void 0) {
+    assertInvocationMode(opts.invocationMode);
+  }
+  const body = {};
+  if (opts.name !== void 0) body.name = opts.name;
+  if (opts.key !== void 0) body.key = opts.key;
+  if (opts.description !== void 0) body.description = opts.description;
+  if (opts.sourceId !== void 0) body.source_id = opts.sourceId;
+  if (opts.invocationMode !== void 0) body.invocation_mode = opts.invocationMode;
+  if (opts.inputVarDescriptions !== void 0) {
+    body.input_var_descriptions = opts.inputVarDescriptions;
+  }
+  const request = createRequest();
+  return request(getCustomerServiceUrl(), `/v1/tool/${opts.toolId}`, {
+    method: "PUT",
+    body
+  });
+}
+async function deleteTool(opts) {
+  const request = createRequest();
+  return request(getCustomerServiceUrl(), `/v1/tool/${opts.toolId}`, {
+    method: "DELETE"
+  });
+}
+async function listWorkflows(opts) {
+  const request = createRequest();
+  return request(getCustomerServiceUrl(), "/v1/tool/workflow/list", {
+    method: "GET",
+    query: { workspace_id: getWorkspaceId(), keyword: opts.keyword ?? "" }
+  });
+}
+async function getWorkflowDetail(opts) {
+  const request = createRequest();
+  return request(
+    getCustomerServiceUrl(),
+    `/v1/tool/workflow/${encodeURIComponent(opts.flowId)}/detail`,
+    {
+      method: "GET",
+      query: { workspace_id: getWorkspaceId() }
+    }
+  );
+}
+
+// src/commands/tool.ts
+function readArgMaybeFile(value) {
+  if (value.startsWith("@")) {
+    const filePath = value.slice(1);
+    try {
+      return fs14.readFileSync(filePath, "utf8");
+    } catch {
+      throw new APIError(
+        1,
+        `\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25\uFF1A${filePath}\uFF08@ \u524D\u7F00\u8868\u793A\u6587\u4EF6\u8DEF\u5F84\uFF1B\u8981\u4F20\u5B57\u9762\u5185\u5BB9\u8BF7\u53BB\u6389 @\uFF09`
+      );
+    }
+  }
+  return value;
+}
+function registerToolCommand(program2) {
+  const tool = program2.command("tool").description(
+    "\u81EA\u5B9A\u4E49/\u8986\u76D6\u5DE5\u5177\uFF08agent tool\uFF09\u7BA1\u7406 \u2014\u2014 \u5BF9\u67D0\u4E2A Agent \u914D\u7F6E\u7ED1\u5B9A\u7684\u81EA\u5B9A\u4E49\u5DE5\u5177\u505A\u589E\u5220\u6539\u67E5\uFF0C\u5E76\u53D1\u73B0\u53EF\u7ED1\u5B9A\u7684\u5DE5\u4F5C\u6D41\uFF08flow\uFF09\u3002\u5305\u88C5 servhub /v1/tool API"
+  );
+  tool.command("list").description("\u5217\u51FA\u8BE5 Agent \u914D\u7F6E\u5DF2\u7ED1\u5B9A\u7684\u5DE5\u5177\uFF08custom + system\uFF09").requiredOption("--agent <config_id>", "Agent \u914D\u7F6E ID\uFF08\u4ECE agent list \u83B7\u53D6\uFF09").action(async (opts) => {
+    try {
+      const data = await listToolsByConfig({ agentConfigId: opts.agent });
+      formatOutput({ success: true, data }, program2.opts().table);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  tool.command("create").description("\u521B\u5EFA\u81EA\u5B9A\u4E49\u5DE5\u5177\uFF0C\u7ED1\u5B9A\u4E00\u4E2A\u5DE5\u4F5C\u6D41\uFF08flow\uFF09\u4F5C\u4E3A\u5DE5\u5177\u5B9E\u73B0").requiredOption("--agent <config_id>", "Agent \u914D\u7F6E ID\uFF08\u4ECE agent list \u83B7\u53D6\uFF09").requiredOption("--name <name>", "\u5DE5\u5177\u663E\u793A\u540D\u79F0").requiredOption("--key <key>", "\u5DE5\u5177 key\uFF08\u552F\u4E00\u6807\u8BC6\uFF09").requiredOption("--source-id <flow_id>", "\u7ED1\u5B9A\u7684\u5DE5\u4F5C\u6D41 ID\uFF08\u4ECE tool workflow list \u83B7\u53D6\uFF09").option("--description <text>", "\u5DE5\u5177\u63CF\u8FF0").option("--source-type <type>", "\u5DE5\u5177\u6765\u6E90\u7C7B\u578B\uFF08\u9ED8\u8BA4 flow\uFF09").option(
+    "--invocation-mode <mode>",
+    "\u8C03\u7528\u6A21\u5F0F\uFF1Amust_invoke / on_demand / on_demand_async\uFF08\u9ED8\u8BA4 on_demand\uFF09"
+  ).option("--input-vars <json>", "\u5165\u53C2\u63CF\u8FF0\uFF08JSON \u5B57\u7B26\u4E32\uFF09\uFF0C\u89E3\u6790\u4E3A input_var_descriptions").action(async (opts) => {
+    try {
+      const inputVarDescriptions = opts.inputVars !== void 0 ? JSON.parse(opts.inputVars) : void 0;
+      const data = await createCustomTool({
+        agentConfigId: opts.agent,
+        name: opts.name,
+        key: opts.key,
+        sourceId: opts.sourceId,
+        description: opts.description,
+        sourceType: opts.sourceType,
+        invocationMode: opts.invocationMode,
+        inputVarDescriptions
+      });
+      formatOutput({ success: true, data }, program2.opts().table);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  tool.command("update <tool_id>").description("\u66F4\u65B0\u5DE5\u5177\u7684\u4EFB\u610F\u5B50\u96C6\u5B57\u6BB5\uFF08\u4EC5\u900F\u4F20\u5B9E\u9645\u63D0\u4F9B\u7684 flag\uFF09").option("--name <name>", "\u5DE5\u5177\u663E\u793A\u540D\u79F0").option("--key <key>", "\u5DE5\u5177 key\uFF08\u552F\u4E00\u6807\u8BC6\uFF09").option("--description <text>", "\u5DE5\u5177\u63CF\u8FF0").option("--source-id <flow_id>", "\u7ED1\u5B9A\u7684\u5DE5\u4F5C\u6D41 ID").option("--invocation-mode <mode>", "\u8C03\u7528\u6A21\u5F0F\uFF1Amust_invoke / on_demand / on_demand_async").option("--input-vars <json>", "\u5165\u53C2\u63CF\u8FF0\uFF08JSON \u5B57\u7B26\u4E32\uFF09\uFF0C\u89E3\u6790\u4E3A input_var_descriptions").action(async (toolId, opts) => {
+    try {
+      const inputVarDescriptions = opts.inputVars !== void 0 ? JSON.parse(opts.inputVars) : void 0;
+      const data = await updateTool({
+        toolId,
+        name: opts.name,
+        key: opts.key,
+        description: opts.description,
+        sourceId: opts.sourceId,
+        invocationMode: opts.invocationMode,
+        inputVarDescriptions
+      });
+      formatOutput({ success: true, data }, program2.opts().table);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  tool.command("delete <tool_id>").description("\u5220\u9664\uFF08\u8F6F\u5220\u9664\uFF09\u6307\u5B9A\u5DE5\u5177").action(async (toolId) => {
+    try {
+      const data = await deleteTool({ toolId });
+      formatOutput({ success: true, data }, program2.opts().table);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  const workflow = tool.command("workflow").description(
+    "\u5DE5\u4F5C\u6D41\uFF08flow\uFF09\u7BA1\u7406\uFF1Alist / detail\uFF08\u53D1\u73B0\uFF09+ create / update / run / delete / describe\uFF08\u589E\u6539\u8DD1\u5220 + \u8BF4\u660E\uFF09"
+  );
+  workflow.command("list").description("\u5217\u51FA\u5F53\u524D\u5DE5\u4F5C\u7A7A\u95F4\u53EF\u7ED1\u5B9A\u7684\u5DE5\u4F5C\u6D41\uFF08flow\uFF09").option("--keyword <kw>", "\u6309\u5173\u952E\u8BCD\u6A21\u7CCA\u7B5B\u9009").action(async (opts) => {
+    try {
+      const data = await listWorkflows({ keyword: opts.keyword });
+      formatOutput({ success: true, data }, program2.opts().table);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  workflow.command("detail <flow_id>").description("\u67E5\u770B\u6307\u5B9A\u5DE5\u4F5C\u6D41\u7684\u5165\u53C2\u5217\u8868\uFF08\u7528\u4E8E\u6784\u9020 input_var_descriptions\uFF09").action(async (flowId) => {
+    try {
+      const data = await getWorkflowDetail({ flowId });
+      formatOutput({ success: true, data }, program2.opts().table);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  workflow.command("create").description(
+    "\u521B\u5EFA\u5DE5\u4F5C\u6D41\uFF08flow\uFF09\uFF1ASTART \u2192 CODE \u2192 END \u9AA8\u67B6\uFF0CCODE \u8282\u70B9\u627F\u8F7D\u5DE5\u5177\u4EE3\u7801\uFF08\u4EC5\u652F\u6301 JavaScript\uFF09\u3002\u975E\u5E42\u7B49\u2014\u2014\u91CD\u8BD5\u4F1A\u5EFA\u51FA\u91CD\u590D flow\uFF0C\u91CD\u8BD5\u524D\u5148 tool workflow list --keyword <name> \u6838\u5BF9"
+  ).requiredOption("--name <name>", "\u5DE5\u4F5C\u6D41\u540D\u79F0").requiredOption(
+    "--code <code|@file>",
+    "CODE \u8282\u70B9 JavaScript \u4EE3\u7801\uFF1B\u503C\u4EE5 @ \u5F00\u5934\u5219\u8BFB\u53D6\u8BE5\u6587\u4EF6\u8DEF\u5F84\uFF08\u5982 @./tool.js\uFF09\uFF0C\u5426\u5219\u6309\u5B57\u9762\u4EE3\u7801"
+  ).option("--description <text>", "\u5DE5\u4F5C\u6D41\u63CF\u8FF0").option(
+    "--input-vars <json|@file>",
+    "\u8986\u76D6 START formConfig\uFF08@file \u540C --code\uFF09\uFF1B\u5F62\u6001\u662F formConfig \u6570\u7EC4 [{type,label,required,placeholder,variableName,...}]\uFF0C\u9ED8\u8BA4\u4EC5 dialogue\u3002\u6CE8\u610F\uFF1A\u4E0E tool create \u7684 --input-vars\uFF08input_var_descriptions\uFF09\u662F\u4E0D\u540C\u5B57\u6BB5"
+  ).option("--no-publish", "\u53EA\u5EFA\u8349\u7A3F\u4E0D\u53D1\u5E03").option("--code-node-name <name>", "CODE \u8282\u70B9\u540D\uFF08\u9ED8\u8BA4 javascript_1\uFF09").option("--version-desc <text>", "\u53D1\u5E03\u7248\u672C\u63CF\u8FF0\uFF08\u5E73\u53F0\u7248\u672C\u5386\u53F2\u91CC\u53EF\u89C1\uFF1B--no-publish \u65F6\u5FFD\u7565\uFF09").action(async (opts) => {
+    try {
+      const code = readArgMaybeFile(opts.code);
+      const inputVars = opts.inputVars !== void 0 ? JSON.parse(readArgMaybeFile(opts.inputVars)) : void 0;
+      const data = await createFlow({
+        name: opts.name,
+        code,
+        description: opts.description,
+        inputVars,
+        codeNodeName: opts.codeNodeName,
+        publish: opts.publish,
+        versionDesc: opts.versionDesc
+      });
+      formatOutput({ success: true, data }, program2.opts().table);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  workflow.command("update <flow_id>").description("\u66F4\u65B0\u5DE5\u4F5C\u6D41\u552F\u4E00 CODE \u8282\u70B9\u7684\u4EE3\u7801\uFF08\u5176\u5B83\u8282\u70B9\u539F\u6837\u4FDD\u7559\uFF09").requiredOption(
+    "--code <code|@file>",
+    "CODE \u8282\u70B9\u65B0\u4EE3\u7801\uFF08JavaScript\uFF09\uFF1B\u503C\u4EE5 @ \u5F00\u5934\u5219\u8BFB\u53D6\u8BE5\u6587\u4EF6\u8DEF\u5F84\uFF0C\u5426\u5219\u6309\u5B57\u9762\u4EE3\u7801"
+  ).option("--no-publish", "\u53EA\u66F4\u65B0\u8349\u7A3F\u4E0D\u53D1\u5E03").option("--version-desc <text>", "\u53D1\u5E03\u7248\u672C\u63CF\u8FF0\uFF08\u5E73\u53F0\u7248\u672C\u5386\u53F2\u91CC\u53EF\u89C1\uFF1B--no-publish \u65F6\u5FFD\u7565\uFF09").action(async (flowId, opts) => {
+    try {
+      const code = readArgMaybeFile(opts.code);
+      const data = await updateFlowCode({
+        flowId,
+        code,
+        publish: opts.publish,
+        versionDesc: opts.versionDesc
+      });
+      formatOutput({ success: true, data }, program2.opts().table);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  workflow.command("run <flow_id>").description(
+    "\u8FD0\u884C\u5DF2\u53D1\u5E03\u7684\u5DE5\u4F5C\u6D41\uFF08HTTP \u540C\u6B65\u6267\u884C\uFF09\uFF1A\u81EA\u52A8\u53D6\u5F53\u524D\u7A7A\u95F4\u5E94\u7528\u6001 access key\uFF0C\u8FD4\u56DE run_result"
+  ).option(
+    "--input <json|@file>",
+    `flow \u5165\u53C2 JSON \u5BF9\u8C61\uFF08\u9ED8\u8BA4 {}\uFF09\uFF0C\u952E\u5BF9\u5E94 START formConfig \u7684 variableName\uFF0C\u5982 '{"dialogue":...}'\uFF1B@file \u540C --code`
+  ).action(async (flowId, opts) => {
+    try {
+      const inputs = opts.input !== void 0 ? JSON.parse(readArgMaybeFile(opts.input)) : void 0;
+      const data = await runFlow({ flowId, inputs });
+      formatOutput({ success: true, data }, program2.opts().table);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  workflow.command("delete <flow_id>").description("\u786C\u5220\u9664\u5DE5\u4F5C\u6D41\uFF08flow\uFF09\u2014\u2014\u4E0D\u53EF\u6062\u590D\uFF08\u533A\u522B\u4E8E tool delete \u7684\u8F6F\u5220\u9664\uFF09").option("--yes", "\u786E\u8BA4\u5220\u9664\uFF08\u5FC5\u987B\u663E\u5F0F\u52A0\uFF0C\u5426\u5219\u62D2\u7EDD\uFF09").action(async (flowId, opts) => {
+    try {
+      if (!opts.yes) {
+        throw new APIError(1, "\u5220\u9664\u4F1A\u8BA9\u6307\u5411\u6B64 flow \u7684\u81EA\u5B9A\u4E49\u5DE5\u5177\u5931\u6548\uFF0C\u786E\u8BA4\u8BF7\u52A0 --yes");
+      }
+      const data = await deleteFlow({ flowId });
+      formatOutput({ success: true, data }, program2.opts().table);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  workflow.command("describe").description(
+    "\u8F93\u51FA CODE \u8282\u70B9\uFF08JavaScript\uFF09\u4F7F\u7528\u6587\u6863\uFF1A\u5165\u53E3/\u53D8\u91CF\u6CE8\u5165/\u8FD4\u56DE\u503C/\u5185\u7F6E\u5305/SDK\uFF0C\u4F9D\u636E\u5B98\u65B9\u6587\u6863\u6574\u7406"
+  ).action(() => {
+    formatOutput({ success: true, data: { guide: CODE_NODE_GUIDE } }, program2.opts().table);
+  });
+}
+
 // src/commands/workspace.ts
 var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 function toISODate(d) {
@@ -6413,7 +7431,9 @@ registerWorkspaceCommand(program);
 registerAgentCommand(program);
 registerOpsAgentCommand(program);
 registerSACommand(program);
+registerToolCommand(program);
 registerProductCommand(program);
+registerMediaCommand(program);
 registerKnowledgeCommand(program);
 registerActivityCommand(program);
 registerIssueCommand(program);