@bty/customer-service-cli 0.4.8 → 0.5.2

package/CHANGELOG.md

@@ -0,0 +1,309 @@
+# Changelog
+
+## 0.5.2 (2026-05-28)
+
+**修复：`repair-record` 命令 404 问题**
+
+- `repair-record-api` 三处请求从 `getCustomerAgentUrl()`（`customer-agent.bantouyan.com`）改为 `getCsAdminUrl()`（`customer-service-admin.betteryeah.com`）。服务端路由部署在 `apps/cs-admin`，之前打错了 host。
+- 鉴权方式从 Cookie（`auth_token`）改为标准 Bearer token，与 cs-admin headless 调用规范一致。
+
+Issue #65
+
+## 0.5.1 (2026-05-28)
+
+**新增：数据看板（`dashboard`）子命令**
+
+- 对接后端 `/v1/dashboard` 看板接口，只产结构化数据，运营报告交由上层（LLM）按场景加工。
+  - `dashboard summary [--config-id]`：全局 / 单店 KPI 汇总 + 环比（接待客户数、转人工率、AI 独立承接率）。
+  - `dashboard trend [--config-id] [--granularity day/week/month]`：接待量 / 转人工趋势。
+  - `dashboard shops`：全部店铺统计列表（默认按转人工客户数降序），横向对比。
+  - `dashboard export --start --end [--config-id ...] [--out <path>]`：店铺维度每日明细。两段式（POST 拿 OSS `download_url` → 拉取 CSV），默认解析为 JSON 行（稳定英文 key + 计数转 number），`--out` 落盘原始 CSV。
+  - `dashboard intent --config-id`：单店各意图消息级转人工统计。
+  - `dashboard intent-conversations --config-id --event-one --event-two`：某意图下会话列表下钻。
+- 复用现有 `request`（`Bearer` + `workspace-id`）/ `getCustomerServiceUrl` / 输出与退出码体系，无额外鉴权逻辑。
+- 口径备注：`接待客户数(customers)` 按客户去重 ≈ 看板"会话/接待量"；`AI回复消息数(ai_reply_messages)` 是真实回复条数；`对话轮次 ≈ ai_reply_messages / customers`。**数据 T+1**（`--end` ≤ 昨天），`--start`/`--end` 闭区间。
+
+## 0.5.0 (2026-05-28)
+
+**Breaking change**
+
+- `issue update-owner` 移除 `--owner-phone` 参数。该参数最初设计为"传手机号、由服务端解析为 user_id"，但后端从未真正接入该字段，CLI 端的传入会被静默忽略（Issue #49）。此次硬删，避免继续误导调用者。
+  - 现在 `--owner <user_id_or_name>` 必填，支持 `user_id`（≤7 位纯数字）或工程师花名（CLI 通过 cs-admin `/api/account-roles` 解析，5min 内存 cache，同名歧义会报错列 candidates）。
+  - 升级路径：直接传花名（`--owner xinghe`）或 `user_id`（`--owner 1862`）。
+  - 受影响脚本：任何使用 `--owner-phone` 的脚本会被 commander 拒收并非 0 退出，需替换为 `--owner`。
+
+**新增：批量改派/更新/创建 issue**
+
+- `issue update-owner` 新增批量模式：`--ids 1,2,3 / --ids-file path` + `--owner <user_id|花名> [--dry-run] [--yes]`。
+  - 单次调用 cs-admin BFF `POST /api/workbench/issues/batch-owner`，原子改派 + 自动 Feishu/DingTalk 通知。
+  - 单批最多 200 条；N≥20 + TTY 二次确认，非 TTY 必须 `--yes`。
+- `issue update` 新增批量模式：`--ids ... / --ids-file ...` + `--data '{"status":"closed"}' [--dry-run] [--concurrency 5] [--yes]`。
+  - 串行 PATCH /v1/issues/{id} 模式（fallback），末尾统一报告 `{success_count, failed_count, skipped_count, success_ids, failed[], skipped[]}`。
+- `issue create` 新增批量模式：`--file <path>` 或 `--stdin` 读 JSON（顶层 `version` + `workspace_id` + `issues[]`）。
+  - 每条 issue 必填 `title` / `priority`（critical|high|medium|low）/ `expected`，且 `conversation_id` 与 `user_name` 二选一。
+  - 仅给 `user_name` 时，CLI 自动调 `GET /v1/chat/conversations?user_name=&workspace_id=` 反查 conversation_id（5min cache）。
+  - CLI 把可选 `description` + 必填 `expected` 拼成 `content`：`{description}\n\n## Expected\n{expected}`。
+  - `--dry-run` 会真跑反查 + content 拼装，但不调 POST /v1/issues。
+- Exit code 协议：0 全成功 / 1 全失败 / 2 部分失败 / 130 SIGINT。
+- 双后端 / 单 token：servhub Bearer JWT 通过 cs-admin BFF 鉴权，CLI 只需一套登录态。
+- Pipe-first：`issue list --json | jq ... | xargs cs-cli issue update-owner --ids ...` 可串。
+
+## 0.4.8 (2026-05-27)
+
+- 补发测试集（TestSet）回归测试全套命令。相关代码随测试集二期 M3 经 `feature/0522-test-dataset-phase-2` 合入 release，但 `0.4.7` 的 npm 发布产物实际**未包含**这套代码（publish 时工作副本尚未合入该分支，只带了 transfer-human），导致 `cs-cli testset` 在线上不可用。本次从含测试集代码的 HEAD 重新构建发布。`cs-cli testset` 主语下提供：
+  - `testset list / show / update / delete / copy`：测试集本体的列表 / 详情 / 更新 / 删除 / 复制。
+  - `testset get-eval-prompt / set-eval-prompt`：读取 / 设置测试集评价提示词（`set-eval-prompt --prompt @file` 支持读纯文本 Markdown，不做 JSON.parse）。
+  - `testset case list / show / create / update / delete`：测试集内用例的增删改查（`--data <json|@file>`）。
+  - `testset batch list / show / status`：执行批次的列表 / 详情 / 实时状态（含 `is_terminal`）。
+  - `testset run --testset <id> --agent <id>`：触发测试集回归执行，默认异步；`--wait` 切同步轮询终态（3s 间隔，`--timeout` 控上限，单位秒，超时仍 exit 0 / ADR-002）。
+  - `testset run-case --batch <id> --case <id>`：单条用例重跑。
+  - `testset export --testset <id> --batch <id> --output <path>`：批次结果导出为 xlsx 落盘（父目录自动 mkdir）。
+  - 对接 customer-servhub-api 的 `/v1/test_sets/*` 系列接口（`/cases`、`/execution_batches`、`/execute`、`/{id}/evaluate-prompt`、`/{id}/duplicate`、`/{id}/export`），走 CLI 标准 Bearer 鉴权与全局 `--table` 输出。
+
+## 0.4.7 (2026-05-26)
+
+- `conversation` 新增 `transfer-human` 子命令：`conversation transfer-human --agent <customer_agent_config_id> --start <ISO> --end <ISO> [--page N]`，对接 `GET /v1/chat/conversations/transfer-human`，用于查询指定 Agent 在给定时间范围内的转人工会话及对应转人工消息记录。
+- 查询口径按 `MANUAL_TAKEOVER_REQUIRED` 事件时间过滤会话，不再按会话 `updated_at` 推断；CLI 在本地校验开始/结束时间格式、结束时间不能早于开始时间、查询窗口最多 7 天。
+- 返回结果同时包含：
+  - `takeover_event_record`：命中的转人工事件列表
+  - `transfer_to_human_records`：同时间范围内 `transfer_to_human=true` 的消息记录，新增 `trace_id` 字段（来源 `reply_message_statistics.flow_trace_id`）
+- `transfer-human` 返回的会话字段收敛为转人工场景所需的最小集合，避免沿用通用会话列表的冗余字段；分页大小由服务端固定为 `100`，CLI 仅暴露 `--page`。
+
+## 0.4.5 (2026-05-25)
+
+- `product` 新增 `add` 子命令：直接传入结构化商品数据（JSON 数组）异步学习。`--agent <id> --data <json|@file> [--source <type>] [--no-identify]`，对接 `POST /v1/knowledge/products/upload` 的 `product_items`（与 `product learn` 的 `product_urls` 是同一接口的两种载荷）。`--data` 接受 JSON 字符串或 `@文件路径`；单个对象自动包成数组，传 JSON 基本类型（数字/字符串等）直接报错；`--source` 默认 `manual`，`--no-identify` 关闭自动识别。
+- `faq` 新增 `content` 子命令：列出指定 FAQ 文件内的答案组（含 `answer_group_id` / 问题 / 答案）。`--agent <id> --file <文件名> [--keyword <词>] [--page-size <n>] [--next-group-id <id>]`，走 `GET /mebsuta/api/v1/dataset/{knowledge_id}/faq_contents`。补齐 `faq update` / `faq delete` 所需 `--group-id` 的可发现性——此前 `faq list` 只列文件、无法查到文件内各答案组的 `answer_group_id`。
+- 修正 `product-sync.test.ts` 一处自 0.4.4 起就遗漏的断言（`sync-taobao` 默认发送 `sync_type=full`）。
+
+## 0.4.4 (2026-05-25)
+
+- `product sync-taobao` 新增 `--sync-type <full|incremental>`，对接 `POST /v1/authorized-shop/sync-taobao-products` 的 `sync_type` 参数；CLI 默认仍发送 `full`。
+- 文档同步更新：`README.md` 与命令描述改为“淘宝店铺商品同步”，补充 `--sync-type` 用法说明。
+
+## 0.4.3 (2026-05-22)
+
+- `product` 新增两个淘宝商品同步命令：
+  - `product sync-taobao --agent <id> [--skip-hash-check]`：对接 `POST /v1/authorized-shop/sync-taobao-products`，按 `customer_agent_config_id` 触发店铺商品全量同步，可选跳过哈希校验强制重跑。
+  - `product sync-taobao-item --agent <id> --product-id <id>`：对接 `POST /v1/authorized-shop/sync-single-product`，按 `customer_agent_config_id + product_id` 触发单个淘宝商品同步。
+- `product sync-taobao` / `product sync-taobao-item` 仅支持已开通“高级工具”的店铺 Agent。
+
+## 0.4.2 (2026-05-21)
+
+- `issue` 新增 `update-owner <issue_id>` 子命令：更新工单负责人。`--owner <user_id>` 与 `--owner-phone <phone>` 二选一（互斥），底层调用 `PATCH /v1/issues/{issue_id}`，body 为 `{ owner }` 或 `{ owner_phone }`，后者由服务端解析为 user_id。CLI 侧仅做参数校验与透传，依赖 customer-servhub-api 后续开放 `owner` / `owner_phone` 字段后方可生效。
+
+## 0.4.1 (2026-05-19)
+
+- 新增 `change-consumer` 命令组：商品变更事件消费链路（pull 模式，默认 `consumer_key=ops_agent_assistant`）。标准工作流 `sub create 创建订阅 → delivery list 轮询 → delivery claim 认领 → 处理 → delivery complete 回写`：
+  - `change-consumer sub create`：创建订阅，最简只需 `--workspace-id` + `--events`（默认 `product.updated,product.deleted`）；`--agent-config` 缺省表示该 workspace 全部商品事件；`--disabled` 创建为停用；`--data <json|@文件>` 高级覆盖。
+  - `change-consumer sub list` / `sub update <subscription_id>`：查询 / 更新订阅（`enabled` / `events` / `filters` / `consumer_name`）。
+  - `change-consumer delivery list`：查询待消费项，支持 `--statuses` 过滤与 `--cursor-created-at` / `--cursor-delivery-id` 增量游标。
+  - `change-consumer delivery claim <delivery_id> --claimed-by <id>`：认领（`--lease-seconds` 默认 300，已被他人认领且未过期会失败）。
+  - `change-consumer delivery complete <delivery_id> --status <completed|ignored|failed>`：回写结果，`--result-action` / `--result-note` / `--last-error`，或 `--data` 高级覆盖。
+- 对接 customer-servhub-api 的 `/v1/change-consumers/*` 接口，走 CLI 标准 Bearer 鉴权与全局 `--table` 输出。
+
+## 0.4.0 (2026-05-17)
+
+> 版本号说明：本次含用户可见破坏性变更（移除 langfuse 直连配置项），沿用既有规律（0.2.0 / 0.3.0 的 Breaking 均走 minor bump）定为 0.4.0。`package.json` 的 `version` 由发布流程（`pnpm run release`）统一 bump，本条目以 0.4.0 记录变更内容。
+
+- `debug trace <trace_id>` 新增 `--env <dev|prod>` 选项（默认 `prod`）：用于指定 langfuse 环境。行为变更——不再由 CLI 直连 langfuse REST API，改为请求 customer-servhub-api 的 `GET /v1/debug/langfuse/trace/{trace_id}?env=<env>` 接口（走 CLI 标准 Bearer 鉴权），由服务端按 env 选择 langfuse 凭据并代理拉取 trace。`--env` 仅接受 `dev` / `prod`，传其它值命令直接报错并以非 0 退出，不发请求。
+- **BREAKING**: 移除 `config set` 的 `--langfuse-host` / `--langfuse-public-key` / `--langfuse-secret-key` 三个选项，及 `CLIConfig` 的 `langfuseHost` / `langfusePublicKey` / `langfuseSecretKey` 字段（随 langfuse 直连一并下线）。迁移：`~/.cs-cli/config.json` 中 `langfuseHost` / `langfusePublicKey` / `langfuseSecretKey` 字段可直接删除；langfuse 连接信息（含 dev/prod 双环境凭据）现由 customer-servhub-api 服务端配置，CLI 侧无需也无法再配置；环境变量 `LANGFUSE_BASE_URL` / `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` 在 CLI 侧不再被读取。
+- 清理 langfuse 直连死代码：`helpers.ts` 的 `getLangfuseConfig` 及 `DEFAULT_LANGFUSE_HOST` / `DEFAULT_LANGFUSE_PUBLIC_KEY` / `DEFAULT_LANGFUSE_SECRET_KEY` 内置默认常量全部移除（不再向 CLI 二进制内嵌 langfuse 凭据）。
+
+## 0.3.3 (2026-04-23)
+
+- `workspace` 新增 `points-consumes-daily` 子命令：按天查询当前工作空间的积分消耗（`POST /v1/workspace/points_consumes/daily_deduction`，body `start_time` / `end_time`）。支持 `--start <YYYY-MM-DD>` / `--end <YYYY-MM-DD>`，两者均可选，默认最近 30 天（end=今天，start=今天-29d）。返回 `consume_date` / `total_consume_points` 列表，沿用全局 `--table` 输出。`workspace-id` 由 `request.ts` 统一从 env lock / `--workspace` / 本地 / 全局配置解析，无需在该命令里显式传入。
+
+## 0.3.2 (2026-04-22)
+
+- **修复 0.3.1 引入的回归**：全局 `--timeout <ms>` 与子命令 `--timeout <seconds>` 同名，commander v14 会把子命令位置上的 `--timeout 60` 上浮给 program，preAction 把 `60` 当毫秒写进 runtime store，所有请求在 ~60ms 就被 abort（症状：`cs-cli debug ask --text ... --timeout 60` 在 ~0.226s 返回 `aborted due to timeout`）。
+- 重命名全局标志 `--timeout <ms>` → `--request-timeout <ms>`，消除命名冲突：
+  - `cs-cli debug ask --timeout 60` 现在 commander 直接把 `60` 分给子命令（轮询窗口，秒），HTTP 超时用 60000ms 硬编码 fallback。
+  - 需要单独抬高 HTTP 单次超时：`cs-cli --request-timeout 120000 debug ask --timeout 60`（HTTP 120s + 轮询 60s 独立可控）。
+- 子命令 `debug ask` / `debug chat` / `debug replay` 各自的 `--timeout <seconds>` 不变。
+
+## 0.3.1 (2026-04-21)
+
+- 修复全局 `--timeout <ms>` 死代码：此前 `bin.ts` 声明后没有代码读取 `program.opts().timeout`，所有请求都落到 `request.ts` 里 20000ms 硬编码 fallback，`AbortSignal.timeout` 在 ~20.24s 稳定 abort，`debug chat` 长耗时 Agent 回复表现为卡死。现在 `--timeout` 通过 `setRuntimeRequestTimeoutMs` 贯穿到所有 `createRequest()` 调用。
+- 默认超时由 20s 提到 60s：`--timeout` 默认值 `20000` → `60000`，`request.ts` 的硬编码底座同步提升。
+- 优先级链：`options.timeout` > `createRequest(globalTimeout)` 参数 > 全局 `--timeout` 写入的 runtime store > 60000。
+- 不改动 `debug chat` / `debug reproduce` 各自的 `--timeout <seconds>`（轮询窗口，语义独立）。
+
+## 0.3.0 (2026-04-17)
+
+- **BREAKING**: 合并 `authApiUrl` 与 `aiApiUrl` 配置字段。`CLIConfig.authApiUrl` 已移除；auth 与 ai 请求都走 `aiApiUrl`（默认仍为 `https://ai-api.betteryeah.com`）。迁移：`~/.cs-cli/config.json` 中 `authApiUrl` 字段可直接删除；若此前 `authApiUrl` 与 `aiApiUrl` 指向不同地址，请手动把目标值写入 `aiApiUrl`。
+- **BREAKING**: 移除 `config set --auth-api <url>` 选项。迁移：`cs-cli config set --ai-api <url>`，或通过环境变量 `CS_AI_API_URL=<url>` 覆盖。
+- 三个 API URL 新增环境变量作为**第一优先级**覆盖源：`CS_CS_API_URL` / `CS_AI_API_URL` / `CS_CUSTOMER_AGENT_URL`。优先级为 `env > config.json > 默认值`。空字符串视为未设置。
+
+## 0.2.1 (2026-04-16)
+
+- `product update-sku` 支持 `--sku-id <id>`，与 `--sku` 至少二选一；两者同时提供时优先使用 `sku_id`。SKU 名称在商品复杂字符场景下易写错，`sku_id` 作为全局唯一 ID 更稳定，推荐优先使用。
+- `updateSku` 客户端函数新增可选 `skuId`，提供时 body 只携带 `sku_id`；两者都缺时 throw。`--sku` 由 `requiredOption` 改为 `option`，向后兼容仅传 `--sku` 的旧调用。
+- 补 3 条单测覆盖 skuId-only / both-prefers-skuId / neither-throws；README 表格与示例同步。
+
+## 0.2.0 (2026-04-15)
+
+- **Breaking**: env lock 环境变量加 `CS_` 前缀，避免与通用命名冲突（HTTP `Authorization` 头、其它工具）。旧名 `AUTHORIZATION` / `WORKSPACE_ID` / `AGENT_ID` 不再识别，sandbox / CI 需改用 `CS_AUTH` / `CS_WORKSPACE_ID` / `CS_AGENT_ID`。行为不变：env 有值则锁定凭据/上下文，任何 `--workspace` / `--agent` / `auth login` 等 override 硬失败。
+- 首次在 README 文档化 env lock 约定（工作空间优先级加 priority 0，新增"环境变量锁定（sandbox / CI）"章节）。
+
+## 0.1.27 (2026-04-14)
+
+- `faq` 新增 `update` / `delete` 子命令：`faq update` 通过 `answer_group_id` 更新已有 FAQ 组（支持 `--questions` / `--answers` / `--delete-chunks` 任选组合），`faq delete` 删除指定 FAQ 组。
+- 新增 `knowledge` 命令组：`knowledge list` 列出扩展知识库（`suffix_type=_common`）；`knowledge content list|add|update|delete` 对段落做 CRUD，统一走 `/mebsuta/api/v1/dataset/{id}/contents/perform-operations`。`content add` / `content update` 的 `--content` 支持 `@file` 前缀从文件读取纯文本。
+- `knowledge content update` 未显式指定 `--enable` / `--disable` 时，自动从段落当前快照读取 enable 状态透传（read-modify-write），避免后端 `enable` 必填校验失败，也不会意外切换启停状态。
+- `product` 新增 `learn` 子命令：提交商品 URL 进入异步学习（`/v1/knowledge/products/upload`），支持 `--url` variadic、`--source`、`--no-identify`。
+
+## 0.1.26 (2026-04-11)
+
+- `debug record` 新增 `--deep` 深度解析选项：额外调用 ai-api `/v1/flow/execute_log/{flow_id}/{task_id}`，再跟随返回的 `log_url` 拉取完整执行日志（`actionOutputs` 节点级输入输出），用于排查 flow 内部行为。默认关闭以保持向后兼容。配套 `--flow-workspace <id>` 覆盖 flow 所在 workspace（默认内置固定值 `531c14d1...`）。
+
+## 0.1.25 (2026-04-08)
+
+- 重构重放消息 content 构建：直接使用原始 `context` 结构，保留所有字段（`url`、`image`、`is_entry_product` 等）
+
+## 0.1.24 (2026-04-08)
+
+- 修复重放消息缺少 `url` 字段：CARD 等类型的 `context.url` 现在会正确带入 `content.url`
+
+## 0.1.23 (2026-04-07)
+
+- 修复重放消息图片字段：`content.image_url` 改为 `content.image`，与服务端接口一致
+
+## 0.1.22 (2026-04-07)
+
+- 修复 `debug reproduce` 重放时图片消息丢失：兼容 `context.image` 字段，正确使用原始 `context_type`（不再硬编码 `TEXT`）
+
+## 0.1.21 (2026-04-07)
+
+- `debug reproduce` 返回结果新增顶层 `trace_id` 字段，复现完成后自动获取 Langfuse Trace ID
+
+## 0.1.20 (2026-04-07)
+
+- 修复 `debug reproduce` 复现旧对话时消息被服务端过滤的问题：将时间戳重置到当前时间，保持消息间相对顺序
+
+## 0.1.19 (2026-04-07)
+
+- `conversation list` 新增 `--equipment-id` 参数，支持按设备 ID 筛选会话
+- `conversation list` 的 `--agent` 参数从必填改为可选
+
+## 0.1.17 (2026-04-03)
+
+- 修复 `ops-record` API 地址：从 `customer-agent.bantouyan.com` 迁移到 `customer-servhub-api.betteryeah.com`
+  - 路径从 `/api/agent_operations_records` 改为 `/v1/agent_operations_records`
+  - 认证方式从 Cookie auth 改为 Bearer token（与其他 customer-servhub-api 端点一致）
+- 修复 `ops-record list/create` 的 `--workspace` 选项与全局 `--workspace` 冲突，改为 `--workspace-id`
+- `config set` 新增 `--langfuse-host`、`--langfuse-public-key`、`--langfuse-secret-key` 选项
+
+## 0.1.16 (2026-04-01)
+
+- 新增 `debug reproduce <record_id>` 命令，根据一条回复记录自动复现 Agent 回复
+  - 通过 recordId 获取关联会话（`/v1/chat/records/{recordId}/relations`）和 Agent 配置
+  - 拉取完整会话记录，截取目标 record 之前的所有上下文
+  - 使用原始 `user_name` 创建新 debug 会话并发送
+  - `--agent <config_id>` 可指定另一个 Agent 复现同一段上下文（A/B 对比）
+  - `--dry-run` 仅输出截断后的上下文 msg_list，不发送
+  - `--timeout` / `--poll-interval` 控制等待时间
+- `pollAgentReply` 新增 `category` 过滤参数，reproduce 场景下只等 `agent_response`，避免历史 report 记录干扰
+- 新增 `getRecordRelations`、`truncateBeforeRecord`、`recordsToMsgList` 函数及测试（6 个用例）
+- 更新 README、SKILL.md、workflows.md 文档
+
+## 0.1.15 (2026-04-01)
+
+- 新增 `debug trace <trace_id>` 命令，根据 Langfuse Trace ID 获取完整 Trace 详情
+  - 直接调用 Langfuse REST API（`GET /api/public/traces/:traceId`），使用 Basic Auth 认证
+  - Trace ID 从 `debug record` 返回的 `trace_id` 字段获取
+- `debug record` 返回值新增 `trace_id` 字段，从 `flow_info` 中自动提取
+- 新增 Langfuse 连接配置，支持环境变量（`LANGFUSE_BASE_URL` / `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY`）和配置文件两种覆盖方式，内置默认连接信息
+- 补充 `getLangfuseTrace` 测试（2 个用例）
+- 更新 README 文档
+
+## 0.1.14 (2026-03-31)
+
+- 新增 `ops-record` 命令（运维操作记录管理），支持 list/get/create/update/delete 五个子命令
+  - 运维工程师可上传和查询对 Agent 的操作记录
+  - 创建时 `operator_id` 和 `operator_name` 自动从当前登录用户获取
+- 新增 `operations-record-api` 测试（8 个用例）
+- `package.json` 新增 `publish` 脚本
+- CLAUDE.md / AGENTS.md 明确禁止使用 `npm publish`
+
+## 0.1.13 (2026-03-28)
+
+- 修复发布问题：改用 pnpm publish 重新发布
+
+## 0.1.12 (2026-03-27)
+
+- 新增 `conversation context-search` 命令，支持按上下文内容模糊搜索对话记录
+  - 返回匹配消息详情，包含 `conversation_id`、`record_id`、`context` 等字段
+  - 自动使用当前工作空间作为查询范围
+- 为 `context-search` 增加本地时间窗口校验
+  - 当 `--start` 与 `--end` 同时传入且跨度超过 3 天时，CLI 直接报错，不再等后端返回 400
+- 补充 `conversation-api` 测试与 README 示例
+  - 覆盖查询参数透传、可选时间参数省略和超范围校验
+  - README 明确标注查询窗口最多 3 天
+
+- `issue create` 新增可选参数：`--conversation-id`、`--record-id`、`--workspace-id`、`--source-type`、`--source-data`
+  - 支持关联会话和消息记录，指定来源类型和来源数据
+  - API 层新增 `CreateIssueParams` 类型定义
+
+## 0.1.10 (2026-03-27)
+
+- 新增自动检查更新功能：命令执行后非阻塞检查 npm registry 最新版本
+  - 缓存机制：4 小时内不重复请求（`~/.cs-cli/update-check.json`）
+  - 提示输出到 stderr，不影响 JSON stdout
+  - 网络异常时静默忽略，不影响正常使用
+  - 设置 `CS_CLI_NO_UPDATE_CHECK=1` 可禁用
+
+## 0.1.9 (2026-03-26)
+
+- 全面优化 CLI help 描述，提升 AI Agent 友好性：
+  - 根命令增加系统概念图谱（workspace → agent → SA/product/FAQ → issue → debug → monitor）
+  - 所有命令组增加业务语义说明（如 SA = Agent 意图匹配和回复逻辑的核心配置）
+  - 补全缺失的枚举值（issue status: open|closed、priority: critical|high|medium|low、product status: available|pending|failed 等）
+  - 所有 ID 参数标注来源（如"从 agent list 获取"）
+  - 关键命令标注返回字段结构（如 debug ask 返回 conversation_id + reply[].record_id）
+  - `--data`/`--update` 选项列出可更新字段
+  - `debug ask --messages` 标清两种 JSON 格式（数组 / { msg_list } 对象）
+  - 区分易混淆概念（chat-history ≠ conversation）
+- 同步更新 SKILL.md：新增架构数据流图、ID 获取链路表、完整修复工作流
+
+## 0.1.8 (2026-03-24)
+
+- 新增 `issue stats` 命令（各工作空间 Issue 统计，支持日期筛选）
+- 抽取 `buildCookieHeaders` 到 helpers.ts 供 customer-agent API 复用
+- 修复 customer-agent API 返回嵌套 `data.data` 问题
+
+## 0.1.7 (2026-03-24)
+
+- `bin.ts` version 改为从 `package.json` 动态读取，不再硬编码
+
+## 0.1.6 (2026-03-24)
+
+- 新增 `repair-record list/create/update` 命令（cookie 认证，对接 customer-agent API）
+- 新增 `monitor` 命令（agents/tickets/snapshots/statistics/workspaces）
+- 新增 `customerAgentApiUrl` 配置项（默认 `https://customer-agent.bantouyan.com`）
+- `repair_result` 支持结构化修复推理（`diagnosis_reasoning` / `fix_reasoning`）
+- 补全所有 API 客户端测试（18 个文件 99 个用例）
+- 创建 CLAUDE.md 和 AGENTS.md
+
+## 0.1.5 (2026-03-22)
+
+- 增强 SA/产品 CLI 命令并重构 API 层
+
+## 0.1.4 (2026-03-21)
+
+- 中文化 CLI、调整超时、内置默认 API 地址、支持消息列表重放
+
+## 0.1.3 (2026-03-20)
+
+- 添加 faq、conversation、debug 命令
+
+## 0.1.2 (2026-03-19)
+
+- 添加 chat-history 命令
+
+## 0.1.1 (2026-03-18)
+
+- 添加 workspace、agent、sa、product、issue 命令
+
+## 0.1.0 (2026-03-17)
+
+- 初始版本：auth、config 基础命令

package/README.md

@@ -262,12 +262,67 @@ cs-cli product update-sku --agent <id> --sku-id 6072595054179 --update '{"补充
 | ------------------------------------------------------------------------------------------ | ------ |
 | `issue list [--agent <id>] [--status <状态>] [--priority <优先级>] [--start <日期>] [--end <日期>]` | 列出工单   |
 | `issue get <issue_id>`                                                                     | 获取工单详情 |
-| `issue create --title <标题> --content <内容> [--priority <优先级>] [--tags <标签>]`                | 创建工单   |
-| `issue update <issue_id> --data <json|@file>`                                              | 更新工单   |
+| `issue create --title <标题> --content <内容> [--priority <优先级>] [--tags <标签>]`                | 单条创建工单 |
+| `issue create --file <path> \| --stdin [--dry-run] [--concurrency <n>] [--yes]`            | **批量**创建工单（JSON 协议见下） |
+| `issue update <issue_id> --data <json|@file>`                                              | 单条更新工单 |
+| `issue update --ids <a,b,c> \| --ids-file <path> --data <json|@file> [--dry-run] [--concurrency <n>] [--yes]` | **批量**更新工单字段（串行 PATCH） |
+| `issue update-owner <issue_id> --owner <user_id\|花名>`                                       | 单条改派负责人（花名自动解析） |
+| `issue update-owner --ids <a,b,c> \| --ids-file <path> --owner <user_id\|花名> [--dry-run] [--yes]` | **批量**改派负责人（走 cs-admin BFF，原子改派 + 自动 Feishu/DingTalk 通知，单批 ≤ 200） |
 | `issue stats [--start <日期>] [--end <日期>]`                                                  | 各工作空间 Issue 统计（open/closed/total） |
 | `issue comment list <issue_id>`                                                            | 列出工单评论 |
 | `issue comment add <issue_id> --content <内容>`                                              | 添加评论   |
 
+#### 批量写约定（`update` / `update-owner` / `create --file`）
+
+- `--ids "a,b,c"` 与 `--ids-file path.txt`（一行一个 id，`#` 注释、空行忽略）互斥；与单条 `<issue_id>` 互斥。
+- `--owner` 同时接受 `user_id`（≤ 7 位纯数字）和工程师花名。花名经 cs-admin `/api/account-roles` 解析（KA + SMB 合并去重，5 分钟内存 cache），同名 / 模糊歧义会报错列 candidates。`--owner` 拒绝 11 位手机号（Issue #49，老 `--owner-phone` 0.5.0 起硬删）。
+- `--dry-run` 在所有批量子命令上都不会调写接口；`create --file --dry-run` 会真跑 `user_name → conversation_id` 反查，以便提前发现 `NOT_FOUND` / `AMBIGUOUS`。
+- N ≥ 20 且 stdout 是 TTY 时弹二次确认（输入 `yes`）；非 TTY 必须显式 `--yes`，否则拒收。
+- 末尾报告统一 schema：`{version:"1", total, success_count, failed_count, skipped_count, aborted, success_ids[], failed[{id,code,msg}], skipped[{id,reason}]}`。退出码：`0` 全成功 / `1` 全失败 / `2` 部分失败 / `130` SIGINT。
+- `update-owner --ids` 走 cs-admin BFF `POST /api/workbench/issues/batch-owner` 单次调用（原子），返回 `{updated, skipped:[{issueId, reason}], notify[]}`，与 `update` 的 runBatch 报告 schema 不同（保留 BFF 原样）。
+- 双后端单 token：servhub Bearer JWT 同时通过 cs-admin BFF 鉴权（实测验证），无需额外登录。
+
+#### `issue create --file` JSON 协议
+
+文件解析交给上游（LLM/Agent/脚本）整理成下面这份结构化 JSON，CLI 只做校验 + 反查 + 拼装 + 批量创建。
+
+```jsonc
+{
+  "version": "1",
+  "workspace_id": "ws_xxx",          // 顶层，对所有 issue 生效；缺省时落到默认 workspace
+  "issues": [
+    {
+      "title": "客户反馈：A 问题答非所问",   // 必填
+      "priority": "high",              // 必填，critical|high|medium|low
+      "expected": "应该回答 X",          // 必填，CLI 把它写进 content 的 ## Expected 段
+      "description": "上下文描述",       // 可选，拼在 expected 前面
+      "conversation_id": "conv_xxx",   // 与 user_name 二选一
+      "user_name": "张三",              // 仅给昵称时，CLI 调 /v1/chat/conversations?user_name= 反查
+      "tags": ["badcase"],             // 可选
+      "source_type": "manual_review",  // 可选
+      "source_data": {"reviewer": "..."} // 可选
+    }
+  ]
+}
+```
+
+CLI 把 `description` + `expected` 拼成 `content`：
+
+```
+{description}（如有）
+
+## Expected
+{expected}
+```
+
+`user_name` 反查规则（5 分钟内存 cache，key = `${workspaceId}|${userName}`）：
+
+- 1 条命中 → 用其 `conversation_id`
+- 0 条 → 该 issue 标记 `NOT_FOUND`，整批拒收（防止半批进创建）
+- 多条 → 该 issue 标记 `AMBIGUOUS`，提示改传显式 `conversation_id`
+
+`priority` 不在枚举内、`title`/`expected` 缺失等 → 客户端直接拒收（不打任何接口）。
+
 
 ### 聊天记录 (`chat-history`)
 
@@ -527,6 +582,26 @@ cs-cli change-consumer delivery complete <delivery_id> --status completed \
 
 **xlsx 二进制输出**：`export --output <path>` 必填路径，stdout 仅承载 JSON 报告 `{success:true, data:{path, bytes}}`，不支持 stdout pipe（避免与 JSON-by-default 冲突）。
 
+### 数据看板 (`dashboard`)
+
+转人工率 / 接待量 / AI 回复量等运营指标。**数据 T+1**（`--end` 不能晚于昨天，否则后端返回 400）；`--start` / `--end` 为**闭区间**。渠道枚举：`qianniu`（千牛/淘宝）/ `jingdong` / `pinduoduo` / `douyin`。CLI 只产结构化数据，运营报告由上层（如 LLM）按场景加工。
+
+| 命令 | 说明 |
+| --- | --- |
+| `dashboard summary [--config-id <id>] [--start <d>] [--end <d>] [--channel <c>]` | 全局或单店 KPI 汇总 + 环比（不传 `--config-id` 为全店铺聚合） |
+| `dashboard trend [--config-id <id>] [--start <d>] [--end <d>] [--granularity day/week/month] [--channel <c>]` | 趋势（每日/周/月接待客户数、转人工数、转人工率），`--granularity` 默认 `day` |
+| `dashboard shops [--start <d>] [--end <d>] [--channel <c>]` | 全部店铺统计列表（默认按转人工客户数降序），用于横向对比 |
+| `dashboard export --start <d> --end <d> [--config-id <id> ...] [--channel <c>] [--out <path>]` | 店铺维度每日明细。默认解析为 JSON 行；`--out` 落盘原始 CSV。`--config-id` 可重复传，不传=全部店铺 |
+| `dashboard intent --config-id <id> [--start <d>] [--end <d>]` | 单店各意图（一级/二级标签）消息级转人工统计，默认按转人工消息数降序 |
+| `dashboard intent-conversations --config-id <id> --event-one <l> --event-two <l> [--start <d>] [--end <d>] [--page <n>] [--page-size <n>]` | 某意图下会话列表下钻 |
+
+**口径要点**：
+
+- `summary` / `trend` / `shops` / `intent` 直接透传后端 JSON（`total_customers` / `transfer_rate` / `avg_*` 等英文 key）。
+- `export` 把 CSV 表头映射为稳定英文 key：`date / shop_name / channel / customers / ai_independent_customers / ai_independent_rate / transfer_customers / transfer_rate / ai_reply_messages`；计数字段转 number，比率字段保留原始字符串（如 `"46.0%"`）。
+- **接待客户数（customers）** 按客户去重，是看板口径的"会话/接待量"；**AI 回复消息数（ai_reply_messages）** 是真实 AI 回复条数；`对话轮次 ≈ ai_reply_messages / customers`。
+- `dashboard export --out <path>` 落盘原始 CSV 时，stdout 仅返回 `{path, bytes, count}`。
+
 ## 输出格式
 
 默认输出 JSON：
@@ -555,9 +630,10 @@ cs-cli change-consumer delivery complete <delivery_id> --status completed \
 | 退出码 | 含义                  |
 | --- | ------------------- |
 | `0` | 成功                  |
-| `1` | 业务错误                |
-| `2` | 认证错误（未登录或 Token 过期） |
+| `1` | 业务错误 / 批量全部失败       |
+| `2` | 认证错误（未登录或 Token 过期） / 批量部分失败 |
 | `3` | 网络/服务器错误            |
+| `130` | 批量执行中收到 SIGINT，等飞行中请求结束后退出 |
 
 
 ## 使用示例
@@ -578,6 +654,29 @@ cs-cli issue stats --start 2026-03-01 --end 2026-03-23
 # 列出工单（按日期筛选）
 cs-cli issue list --agent <id> --start 2026-03-01T00:00:00 --end 2026-03-22T23:59:59
 
+# 批量改派（花名 → user_id 自动解析，走 cs-admin BFF 原子改派 + 飞书通知）
+cs-cli issue update-owner --ids iss-1,iss-2,iss-3 --owner xinghe --yes
+
+# 批量改派 dry-run（不写）：仅解析 owner + 列出 ID
+cs-cli issue update-owner --ids iss-1,iss-2 --owner xinghe --dry-run
+
+# pipe-first：先 list 拿 id，再 xargs 批量改派
+cs-cli issue list --status open --priority high \
+  | jq -r '.data.items[].issue_id' | tr '\n' ',' \
+  | xargs -I{} cs-cli issue update-owner --ids "{}" --owner xinghe --yes
+
+# 批量关闭工单（串行 PATCH，部分失败末尾报告）
+cs-cli issue update --ids iss-1,iss-2,iss-3 --data '{"status":"closed"}' --yes
+
+# 从文件批量创建工单（user_name 反查 + content 拼装在 CLI 完成）
+cs-cli issue create --file ./issues.json --dry-run    # 先预览，发现 NOT_FOUND/AMBIGUOUS
+cs-cli issue create --file ./issues.json --yes        # 确认 → 实际创建
+
+# 上游 LLM 直接 pipe 进 stdin
+cat meeting-notes.md \
+  | <llm-extract-issues> \
+  | cs-cli issue create --stdin --yes
+
 # 搜索场景动作
 cs-cli sa search --agent <id> --keyword "退款"