@bty/customer-service-cli 0.6.7 → 0.6.9

package/CHANGELOG.md

@@ -1,7 +1,10 @@
 # Changelog
 
-## Unreleased
+## 0.6.9 (2026-08-24)
 
+- 新增 `channel-metric` 命令组，查询千牛等渠道店铺客服的每日排行指标（`channel_metric_snapshot`）：
+  - `channel-metric query --workspace-id <ws> --start <date> --end <date> [--agent <id>] [--platform <channel>]`：按 workspace + 日期区间（+ 可选 agent / 渠道）查询指标，按日期×渠道分组输出。
+  - `channel-metric backfill --channel <channel> --start <date> --end <date> [--workspace-id <ws>...]`：手动补数据，采集指定日期区间的渠道指标；`--workspace-id` 可重复传，缺省采集所有已开启配置的 workspace。
 - 新增 `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 字符串 / 多层编码）。
@@ -9,6 +12,10 @@
   - `product supplement append-media --agent <id> --product-id <id> --index <n> [--image ...] [--video ...] [--dry-run] [--backup <path>]`：仅向目标下标条目追加媒体，其它条目原样保留；去重合并，未提供任何媒体时报错。
 - Dashboard 命令使用客服 API 原域名下的 `/observability` 网关前缀，无需新增地址配置。
 
+## 0.6.8 (2026-08-10)
+
+- `conversation transfer-human` 新增 `--only-abnormal`：默认仍返回全部转人工会话；开启后仅保留异常会话，排除正常 SOP 转人工、`专家agent无法回答`、`存在无法处理的消息类型：...` 三类正常情况。
+
 ## 0.6.7 (2026-07-30)
 
 > 版本号说明：registry 实际发布序列 0.6.2 → 0.6.4 → 0.6.5 → 0.6.6（0.6.3 从未发布，0.6.4–0.6.6 由其它分支占用），故本条目落 0.6.7。

package/README.md

@@ -520,7 +520,7 @@ Agent 关联的通用规则知识库（`suffix_type=_common`），与 FAQ / 商
 | `conversation list [--agent <id>] [--equipment-id <设备ID>] [--user <用户名>] [--start <日期>] [--end <日期>]` | 搜索会话     |
 | `conversation records <conversation_id> [--page-size N] [--direction prev|next]` | 获取会话聊天记录 |
 | `conversation context-search --query <文本> [--start <时间>] [--end <时间>]` | 通过上下文内容模糊搜索对话记录（返回匹配消息详情，时间范围最多 3 天） |
-| `conversation transfer-human --agent <customer_agent_config_id> --start <时间> --end <时间>` | 查询转人工会话及对应转人工消息记录（时间范围最多 7 天，自动 cursor 翻页） |
+| `conversation transfer-human --agent <customer_agent_config_id> --start <时间> --end <时间> [--only-abnormal]` | 查询转人工会话及对应转人工消息记录（时间范围最多 7 天，自动 cursor 翻页；`--only-abnormal` 仅保留异常会话） |
 
 
 ### Agent 调试 (`debug`)

package/dist/bin.js

@@ -526,6 +526,7 @@ async function listActivities(opts) {
     page_size: opts.pageSize ?? 20
   };
   if (opts.search) query.search = opts.search;
+  if (opts.state) query.state = opts.state;
   return request(getCustomerServiceUrl(), `${PATH_PREFIX}/list`, {
     method: "GET",
     query
@@ -615,6 +616,11 @@ function parseEnabledFlag(raw) {
   if (raw === "false") return false;
   throw new Error("--enabled \u4EC5\u63A5\u53D7 true | false");
 }
+var VALID_LIST_STATES = ["all", "pending", "ongoing", "ended"];
+function parseStateFlag(raw) {
+  if (VALID_LIST_STATES.includes(raw)) return raw;
+  throw new Error(`--state \u4EC5\u63A5\u53D7 ${VALID_LIST_STATES.join(" | ")}`);
+}
 function parseActivityId(raw) {
   const n = Number(raw);
   if (!Number.isInteger(n) || n <= 0) {
@@ -627,14 +633,18 @@ function registerActivityCommand(program2) {
     "\u6D3B\u52A8 V2 \u7BA1\u7406 \u2014\u2014 \u589E\u5220\u6539\u67E5\u6D3B\u52A8\u3001\u6309\u5546\u54C1\u53CD\u67E5\u3001\u5355\u6761\u542F\u7528 toggle\u3001per-tenant V2 \u603B\u5F00\u5173\u3002\u670D\u52A1\u7AEF\uFF1Acustomer-servhub-api /v1/activity*\uFF1B\u5951\u7EA6\u53C2\u8003 docs/devkit/specs/2026-05-28-activity-v2-api-reference.md"
   );
   activity.command("list").description(
-    "\u5217\u51FA\u6D3B\u52A8\uFF08\u5206\u9875 + \u540D\u79F0\u641C\u7D22\uFF09\u3002\u8FD4\u56DE total / v2_activity_enabled / items[]\uFF0Citems \u542B id\u3001activity_name\u3001effective_type\u3001enabled\u3001product_scope\u3001products \u7B49"
-  ).requiredOption("--agent <id>", "customer_agent_config_id\uFF08agent \u914D\u7F6E ID\uFF0C\u4ECE agent list \u83B7\u53D6\uFF09").option("--page <number>", "\u9875\u7801\uFF08\u22651\uFF09", "1").option("--page-size <number>", "\u6BCF\u9875\u6570\u91CF\uFF081-100\uFF09", "20").option("--search <text>", "\u6309\u6D3B\u52A8\u540D\u6A21\u7CCA\u5339\u914D").action(async (opts) => {
+    "\u5217\u51FA\u6D3B\u52A8\uFF08\u5206\u9875 + \u540D\u79F0\u641C\u7D22 + \u72B6\u6001\u8FC7\u6EE4\uFF09\u3002\u8FD4\u56DE total / v2_activity_enabled / items[]\uFF0Citems \u542B id\u3001activity_name\u3001effective_type\u3001enabled\u3001product_scope\u3001products \u7B49\uFF1Btotal \u4E0E state/search \u8FC7\u6EE4\u540C\u53E3\u5F84"
+  ).requiredOption("--agent <id>", "customer_agent_config_id\uFF08agent \u914D\u7F6E ID\uFF0C\u4ECE agent list \u83B7\u53D6\uFF09").option("--page <number>", "\u9875\u7801\uFF08\u22651\uFF09", "1").option("--page-size <number>", "\u6BCF\u9875\u6570\u91CF\uFF081-100\uFF09", "20").option("--search <text>", "\u6309\u6D3B\u52A8\u540D\u6A21\u7CCA\u5339\u914D").option(
+    "--state <state>",
+    "\u5C55\u793A\u72B6\u6001\u8FC7\u6EE4\uFF1Aall | pending | ongoing | ended\uFF08\u7F3A\u7701=all\uFF0C\u542B\u65F6\u95F4\u5F02\u5E38\u6761\u76EE\uFF1Blong_term \u6052 ongoing\uFF09"
+  ).action(async (opts) => {
     try {
       const data = await listActivities({
         customerAgentConfigId: opts.agent,
         page: Number(opts.page),
         pageSize: Number(opts.pageSize),
-        search: opts.search
+        search: opts.search,
+        state: opts.state === void 0 ? void 0 : parseStateFlag(opts.state)
       });
       formatOutput({ success: true, data }, program2.opts().table);
     } catch (err) {
@@ -1085,6 +1095,115 @@ function registerChangeConsumerCommand(program2) {
   });
 }
 
+// src/commands/channel-metric.ts
+import Table2 from "cli-table3";
+
+// src/client/channel-metric-api.ts
+var CHANNEL_METRIC_PREFIX = "/v1/channel-metric";
+async function backfillChannelMetrics(opts) {
+  const request = createRequest();
+  const body = {
+    channel: opts.channel,
+    start_date: opts.startDate,
+    end_date: opts.endDate
+  };
+  if (opts.workspaceIds && opts.workspaceIds.length > 0) {
+    body.workspace_ids = opts.workspaceIds;
+  }
+  return request(getObservabilityUrl(), `${CHANNEL_METRIC_PREFIX}/backfill`, {
+    method: "POST",
+    body
+  });
+}
+async function queryChannelMetrics(opts) {
+  const request = createRequest();
+  const query = {
+    workspace_id: opts.workspaceId,
+    start_date: opts.startDate,
+    end_date: opts.endDate
+  };
+  if (opts.configId) query.config_id = opts.configId;
+  if (opts.channel) query.channel = opts.channel;
+  return request(getObservabilityUrl(), `${CHANNEL_METRIC_PREFIX}/metrics`, {
+    method: "GET",
+    query
+  });
+}
+
+// src/commands/channel-metric.ts
+function collect(value, previous) {
+  return previous.concat([value]);
+}
+function renderGroupedTable(groups) {
+  let total = 0;
+  for (const group of groups) {
+    process.stdout.write(`
+=== ${group.stat_date} \xB7 ${group.channel}\uFF08${group.items.length} \u4E2A\u8D26\u53F7\uFF09===
+`);
+    const first = group.items[0];
+    const headers = (first?.metrics_json ?? []).map((field) => field.label);
+    const table = new Table2({ head: ["account_id", ...headers] });
+    for (const row of group.items) {
+      table.push([
+        String(row.account_id),
+        ...row.metrics_json.map(
+          (field) => field.value === void 0 || field.value === null ? "-" : String(field.value)
+        )
+      ]);
+    }
+    process.stdout.write(`${table.toString()}
+`);
+    total += group.items.length;
+  }
+  process.stdout.write(`
+\u5171 ${total} \u6761\u8BB0\u5F55
+`);
+}
+function registerChannelMetricCommand(program2) {
+  const channelMetric = program2.command("channel-metric").description("\u6E20\u9053\u76D1\u63A7\u6307\u6807\u67E5\u8BE2 \u2014\u2014 \u67E5\u8BE2\u5343\u725B\u7B49\u6E20\u9053\u5E97\u94FA\u5BA2\u670D\u7684\u6BCF\u65E5\u6392\u884C\u6307\u6807\uFF08channel_metric_snapshot\uFF09");
+  channelMetric.command("query").description(
+    "\u6309 workspace + \u65E5\u671F\u533A\u95F4\uFF08+ \u53EF\u9009 agent / \u6E20\u9053\uFF09\u67E5\u8BE2\u6307\u6807\uFF0C\u6309\u65E5\u671F\xD7\u6E20\u9053\u5206\u7EC4\u8F93\u51FA\u3002\u4E0D\u4F20 --agent \u8F93\u51FA\u8BE5 workspace \u4E0B\u5168\u90E8 agent\uFF0C\u4E0D\u4F20 --platform \u8F93\u51FA\u5168\u90E8\u6E20\u9053"
+  ).requiredOption("--workspace-id <workspace_id>", "\u5DE5\u4F5C\u7A7A\u95F4 ID\uFF08\u5FC5\u4F20\uFF0C\u4E0E\u670D\u52A1\u7AEF\u5F52\u5C5E\u6821\u9A8C\u4E00\u81F4\uFF09").option("--agent <agent_id>", "Agent \u914D\u7F6E ID\uFF1B\u7F3A\u7701\u67E5\u8BE2\u8BE5 workspace \u4E0B\u5168\u90E8 agent").requiredOption("--start <date>", "\u8D77\u59CB\u65E5\u671F\uFF08YYYY-MM-DD\uFF09").requiredOption("--end <date>", "\u7ED3\u675F\u65E5\u671F\uFF08YYYY-MM-DD\uFF09").option("--platform <channel>", "\u6E20\u9053\uFF08platform\uFF09\uFF0C\u5982 qianniu\uFF1B\u7F3A\u7701\u67E5\u8BE2\u5168\u90E8\u6E20\u9053").action(async (opts) => {
+    try {
+      setRuntimeWorkspaceId(opts.workspaceId);
+      const data = await queryChannelMetrics({
+        workspaceId: opts.workspaceId,
+        configId: opts.agent,
+        startDate: opts.start,
+        endDate: opts.end,
+        channel: opts.platform
+      });
+      const groups = data?.groups ?? [];
+      if (groups.length === 0) {
+        process.stdout.write("(empty)\n");
+        return;
+      }
+      renderGroupedTable(groups);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+  channelMetric.command("backfill").description(
+    "\u624B\u52A8\u8865\u6570\u636E\uFF1A\u91C7\u96C6\u6307\u5B9A\u65E5\u671F\u533A\u95F4\u7684\u6E20\u9053\u6307\u6807\u3002\u53EF\u6307\u5B9A workspace\uFF08\u53EF\u91CD\u590D\u4F20\uFF09\uFF1B\u4E0D\u4F20 --workspace-id = \u91C7\u96C6\u6240\u6709\u5DF2\u5F00\u542F\u914D\u7F6E\u7684 workspace"
+  ).requiredOption("--channel <channel>", "\u6E20\u9053\uFF08platform\uFF09\uFF0C\u5982 qianniu").requiredOption("--start <date>", "\u8D77\u59CB\u65E5\u671F\uFF08YYYY-MM-DD\uFF09").requiredOption("--end <date>", "\u7ED3\u675F\u65E5\u671F\uFF08YYYY-MM-DD\uFF09").option("--workspace-id <workspace_id>", "\u5DE5\u4F5C\u7A7A\u95F4 ID\uFF08\u53EF\u91CD\u590D\u4F20\uFF1B\u7F3A\u7701 = \u91C7\u96C6\u6240\u6709\u5DF2\u5F00\u542F\u914D\u7F6E\u7684 ws\uFF09", collect).action(async (opts) => {
+    try {
+      const workspaceIds = opts.workspaceId?.length ? opts.workspaceId : void 0;
+      setRuntimeWorkspaceId(workspaceIds?.[0]);
+      const data = await backfillChannelMetrics({
+        channel: opts.channel,
+        startDate: opts.start,
+        endDate: opts.end,
+        workspaceIds
+      });
+      formatOutput({ success: true, data }, program2.opts().table);
+    } catch (err) {
+      reportCaughtError(err);
+      process.exit(toExitCode(err));
+    }
+  });
+}
+
 // src/client/chat-history-api.ts
 async function listChatHistory(opts) {
   const request = createRequest();
@@ -1228,6 +1347,11 @@ function registerConfigCommand(program2) {
 var MAX_CONTEXT_SEARCH_RANGE_MS = 3 * 24 * 60 * 60 * 1e3;
 var MAX_TRANSFER_HUMAN_RANGE_MS = 7 * 24 * 60 * 60 * 1e3;
 var MAX_TRANSFER_HUMAN_CURSOR_PAGES = 500;
+var NORMAL_TRANSFER_EVENTS = /* @__PURE__ */ new Set([
+  "\u9700\u8981\u4EBA\u5DE5\u63A5\u7BA1, SOP\u5F15\u64CE\u8BF7\u6C42\u8F6C\u4EBA\u5DE5\u5904\u7406",
+  "\u9700\u8981\u4EBA\u5DE5\u63A5\u7BA1, \u4E13\u5BB6agent\u65E0\u6CD5\u56DE\u7B54"
+]);
+var NORMAL_TRANSFER_EVENT_PREFIXES = ["\u9700\u8981\u4EBA\u5DE5\u63A5\u7BA1, \u5B58\u5728\u65E0\u6CD5\u5904\u7406\u7684\u6D88\u606F\u7C7B\u578B\uFF1A"];
 function parseSearchTime(value, fieldName) {
   const parsed = new Date(value);
   if (Number.isNaN(parsed.getTime())) {
@@ -1256,6 +1380,22 @@ function validateTransferHumanRange(startTime, endTime) {
     throw new Error("\u67E5\u8BE2\u65F6\u95F4\u8303\u56F4\u4E0D\u80FD\u8D85\u8FC77\u5929");
   }
 }
+function shouldKeepTransferHumanConversation(item, onlyAbnormal) {
+  if (!onlyAbnormal) return true;
+  if (!item || typeof item !== "object") return true;
+  const takeoverEvents = item.takeover_event_record;
+  if (!Array.isArray(takeoverEvents) || takeoverEvents.length === 0) return true;
+  const eventNames = takeoverEvents.map((event) => {
+    if (!event || typeof event !== "object") return void 0;
+    const eventName = event.event_name;
+    return typeof eventName === "string" ? eventName : void 0;
+  }).filter((eventName) => typeof eventName === "string");
+  if (eventNames.length === 0) return true;
+  return eventNames.some((eventName) => {
+    if (NORMAL_TRANSFER_EVENTS.has(eventName)) return false;
+    return !NORMAL_TRANSFER_EVENT_PREFIXES.some((prefix) => eventName.startsWith(prefix));
+  });
+}
 async function contextSearchRecords(opts) {
   validateContextSearchRange(opts.startTime, opts.endTime);
   const wsId = getWorkspaceId(opts.workspaceId);
@@ -1320,7 +1460,8 @@ async function listTransferHumanConversations(opts) {
         }
       }
     );
-    items.push(...page.items ?? []);
+    const pageItems = page.items ?? [];
+    items.push(...pageItems.filter((item) => shouldKeepTransferHumanConversation(item, opts.onlyAbnormal ?? false)));
     pagination = page.pagination ?? {};
     const hasMore = pagination.has_more === true;
     const nextCursor = typeof pagination.next_cursor === "string" && pagination.next_cursor ? pagination.next_cursor : void 0;
@@ -1385,12 +1526,13 @@ function registerConversationCommand(program2) {
       process.exit(toExitCode(err));
     }
   });
-  conversation.command("transfer-human").description("\u67E5\u8BE2\u8F6C\u4EBA\u5DE5\u4F1A\u8BDD\u53CA\u5BF9\u5E94\u8F6C\u4EBA\u5DE5\u6D88\u606F\u8BB0\u5F55").requiredOption("--agent <config_id>", "Agent \u914D\u7F6E ID\uFF08customer_agent_config_id\uFF09").requiredOption("--start <date>", "\u5F00\u59CB\u65F6\u95F4\uFF08ISO \u683C\u5F0F\uFF0C\u5982 2026-05-20T00:00:00\uFF09").requiredOption("--end <date>", "\u7ED3\u675F\u65F6\u95F4\uFF08ISO \u683C\u5F0F\uFF0C\u5982 2026-05-20T23:59:59\uFF09").action(async (opts) => {
+  conversation.command("transfer-human").description("\u67E5\u8BE2\u8F6C\u4EBA\u5DE5\u4F1A\u8BDD\u53CA\u5BF9\u5E94\u8F6C\u4EBA\u5DE5\u6D88\u606F\u8BB0\u5F55\uFF08\u53EF\u9009\u4EC5\u4FDD\u7559\u5F02\u5E38\u4F1A\u8BDD\uFF09").requiredOption("--agent <config_id>", "Agent \u914D\u7F6E ID\uFF08customer_agent_config_id\uFF09").requiredOption("--start <date>", "\u5F00\u59CB\u65F6\u95F4\uFF08ISO \u683C\u5F0F\uFF0C\u5982 2026-05-20T00:00:00\uFF09").requiredOption("--end <date>", "\u7ED3\u675F\u65F6\u95F4\uFF08ISO \u683C\u5F0F\uFF0C\u5982 2026-05-20T23:59:59\uFF09").option("--only-abnormal", "\u4EC5\u4FDD\u7559\u5F02\u5E38\u4F1A\u8BDD\uFF08\u6392\u9664\u6B63\u5E38 SOP \u8F6C\u4EBA\u5DE5\u3001agent \u65E0\u6CD5\u56DE\u7B54\u3001\u8F93\u5165/\u6D88\u606F\u7C7B\u578B\u5F02\u5E38\uFF09", false).action(async (opts) => {
     try {
       const data = await listTransferHumanConversations({
         customerAgentConfigId: opts.agent,
         startDate: opts.start,
-        endDate: opts.end
+        endDate: opts.end,
+        onlyAbnormal: opts.onlyAbnormal
       });
       formatOutput({ success: true, data }, program2.opts().table);
     } catch (err) {
@@ -1575,7 +1717,7 @@ async function writeBinaryToFile(filePath, buffer) {
 }
 
 // src/commands/dashboard.ts
-function collect(value, previous) {
+function collect2(value, previous) {
   return previous.concat([value]);
 }
 function registerDashboardCommand(program2) {
@@ -1630,7 +1772,7 @@ function registerDashboardCommand(program2) {
   });
   dashboard.command("export").description(
     "\u5BFC\u51FA\u5E97\u94FA\u7EF4\u5EA6\u6BCF\u65E5\u660E\u7EC6\uFF08\u63A5\u5F85\u5BA2\u6237\u6570/AI\u72EC\u7ACB\u627F\u63A5/\u8F6C\u4EBA\u5DE5/AI\u56DE\u590D\u6D88\u606F\u6570\uFF09\u3002\u9ED8\u8BA4\u89E3\u6790\u4E3A JSON \u884C\uFF1B--out \u843D\u76D8\u539F\u59CB CSV\u3002\u53EF\u91CD\u590D --config-id \u9650\u5B9A\u5E97\u94FA"
-  ).requiredOption("--start <date>", "\u5F00\u59CB\u65E5\u671F (YYYY-MM-DD)\uFF0C\u5FC5\u586B").requiredOption("--end <date>", "\u7ED3\u675F\u65E5\u671F (YYYY-MM-DD)\uFF0C\u5FC5\u586B\uFF0C\u4E0D\u80FD\u665A\u4E8E\u6628\u5929").option("--config-id <id>", "\u5E97\u94FA\u914D\u7F6E ID\uFF08\u53EF\u91CD\u590D\u4F20\uFF1B\u4E0D\u4F20=\u5168\u90E8\u5E97\u94FA\uFF09", collect, []).option("--channel <channel>", "\u6E20\u9053\u7B5B\u9009: qianniu | jingdong | pinduoduo | douyin").option("--out <path>", "\u843D\u76D8\u539F\u59CB CSV \u8DEF\u5F84\uFF08\u7236\u76EE\u5F55\u81EA\u52A8 mkdir -p\uFF09").action(async (opts) => {
+  ).requiredOption("--start <date>", "\u5F00\u59CB\u65E5\u671F (YYYY-MM-DD)\uFF0C\u5FC5\u586B").requiredOption("--end <date>", "\u7ED3\u675F\u65E5\u671F (YYYY-MM-DD)\uFF0C\u5FC5\u586B\uFF0C\u4E0D\u80FD\u665A\u4E8E\u6628\u5929").option("--config-id <id>", "\u5E97\u94FA\u914D\u7F6E ID\uFF08\u53EF\u91CD\u590D\u4F20\uFF1B\u4E0D\u4F20=\u5168\u90E8\u5E97\u94FA\uFF09", collect2, []).option("--channel <channel>", "\u6E20\u9053\u7B5B\u9009: qianniu | jingdong | pinduoduo | douyin").option("--out <path>", "\u843D\u76D8\u539F\u59CB CSV \u8DEF\u5F84\uFF08\u7236\u76EE\u5F55\u81EA\u52A8 mkdir -p\uFF09").action(async (opts) => {
     try {
       const result = await exportShopData({
         startDate: opts.start,
@@ -7437,6 +7579,7 @@ registerMediaCommand(program);
 registerKnowledgeCommand(program);
 registerActivityCommand(program);
 registerIssueCommand(program);
+registerChannelMetricCommand(program);
 registerChatHistoryCommand(program);
 registerFaqCommand(program);
 registerConversationCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bty/customer-service-cli",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "AI Customer Service CLI - Agent friendly",
   "type": "module",
   "main": "./dist/bin.js",