AI 客服 CLI

供 Agent 调用的 AI 客服命令行工具。所有输出默认为 JSON 格式，便于程序解析。

安装

通过 npm 全局安装（推荐）

npm install -g @bty/customer-service-cli

安装后即可直接使用 cs-cli 命令。

从源码构建

pnpm install
pnpm build

构建产物位于 dist/bin.js，可通过 cs-cli 命令调用。

默认 API 地址

安装后即可使用，无需额外配置 API 地址。内置默认地址：

| 服务 | 默认地址 | | ------ | --------------------------------------------- | | 客服 API | https://customer-servhub-api.betteryeah.com | | 认证 API | https://ai-api.betteryeah.com | | AI API | https://ai-api.betteryeah.com |

如需覆盖，可通过 cs-cli config set 修改：

cs-cli config set --cs-api https://your-api.example.com

快速开始

# 登录
cs-cli auth login --phone 13800000000 --password yourpassword

# 查看当前用户
cs-cli auth whoami

# 设置默认工作空间
cs-cli config set-workspace <workspace_id>

# 列出 Agent
cs-cli agent list

全局选项

| 选项 | 说明 | 默认值 | | ------------------ | ---------------- | ------- | | --table | 以表格形式输出（默认 JSON） | false | | --workspace <id> | 覆盖默认工作空间 ID | 配置文件中的值 | | --timeout <ms> | 请求超时时间（毫秒） | 20000 |

本地配置 (.cs-cli.json)

支持在项目目录下放置 .cs-cli.json 文件，为不同项目配置不同的工作空间。

工作空间优先级

| 优先级 | 来源 | 说明 | | --- | ----------------------- | ---------- | | 1 | --workspace <id> 参数 | 命令行临时覆盖 | | 2 | .cs-cli.json (本地配置) | 当前目录或祖先目录 | | 3 | ~/.cs-cli/config.json | 全局默认配置 |

使用方式

# 在项目目录下初始化本地配置
cs-cli config init

# 设置工作空间（自动写入本地 .cs-cli.json）
cs-cli config set-workspace <workspace_id>

# 强制写入全局配置
cs-cli config set-workspace <workspace_id> --global

CLI 从当前目录向上查找 .cs-cli.json，找到第一个即使用其中的 workspaceId。

.cs-cli.json 格式：

{
  "workspaceId": "ws-abc123",
  "workspaceName": "某客户项目"
}

set-workspace 写入规则

• 当前目录或祖先目录存在 .cs-cli.json → 写入本地配置
• 不存在 .cs-cli.json → 写入全局配置
• 使用 --global → 强制写入全局配置

每次写入后会提示写入的目标路径。

命令速查表

认证 (auth)

| 命令 | 说明 | | ------------------------------------------ | -------- | | auth login --phone <手机号> --password <密码> | 登录 | | auth logout | 退出登录 | | auth whoami | 查看当前登录用户 |

配置 (config)

| 命令 | 说明 | | ----------------------------------------------------------- | ---------------------------- | | config set --cs-api <url> --auth-api <url> --ai-api <url> | 设置 API 地址 | | config get | 查看当前配置（含全局和本地） | | config init | 在当前目录初始化本地配置 (.cs-cli.json) | | config set-workspace <workspace_id> [--global] | 设置默认工作空间 |

工作空间 (workspace)

| 命令 | 说明 | | ---------------- | -------- | | workspace list | 列出所有工作空间 |

Agent 管理 (agent)

| 命令 | 说明 | | ---------------------------------------------- | ----------- | | agent list [--page N] [--page-size N] | 列出 Agent 列表 | | agent get <config_id> | 获取 Agent 详情 | | agent update <config_id> --data <json|@file> | 更新 Agent 配置 |

场景动作 (sa)

| 命令 | 说明 | | --- | --- | | sa list --agent <id> [--intent <意图>] [--first-label <标签>] [--second-label <标签>] | 列出场景动作 | | sa search --agent <id> --keyword <关键词> | 搜索场景动作 | | sa create --agent <id> --first-label <一级标签> --second-label <二级标签> --situation <场景> --action <动作> [--transfer] [--intent <意图>] | 创建场景动作 | | sa update --agent <id> --id <SA_ID> --first-label <一级标签> --second-label <二级标签> --situation <场景> --action <动作> [--transfer] | 更新场景动作 | | sa delete --agent <id> --id <SA_ID> --first-label <一级标签> --second-label <二级标签> | 删除场景动作 | | sa versions --agent <id> --id <SA_ID> | 查看修改记录 |

商品管理 (product)

| 命令 | 说明 | | --- | --- | | product list --agent <id> [--keyword <关键词>] [--status <状态>] [--tag <标签>] | 列出商品 | | product get --agent <id> --product-id <商品ID> | 获取商品详情（自动获取 db_id） | | product update --agent <id> --product-id <商品ID> --update <json\|@file> | 更新商品信息 | | product update-sku --agent <id> --sku <SKU名称> --update <json\|@file> | 更新 SKU 信息 |

product update 支持更新的字段包括：卖点、补充知识、tag、参数、轮播图识别结果、商品详情页识别结果 等。--update 接受 JSON 字符串或 @文件路径。

# 更新卖点
cs-cli product update --agent <id> --product-id <商品ID> --update '{"卖点":"新卖点内容"}'

# 更新标签
cs-cli product update --agent <id> --product-id <商品ID> --update '{"tag":"[\"春季新品\",\"热卖\"]"}'

# 添加商品补充知识
cs-cli product update --agent <id> --product-id <商品ID> --update '{"补充知识":"[{\"question\":\"问题\",\"answer\":\"回答\"}]"}'

# 更新 SKU 补充知识
cs-cli product update-sku --agent <id> --sku "颜色分类:粉红" --update '{"补充知识":"说明内容"}'

工单管理 (issue)

| 命令 | 说明 | | ------------------------------------------------------------------------------------------ | ------ | | 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 stats [--start <日期>] [--end <日期>] | 各工作空间 Issue 统计（open/closed/total） | | issue comment list <issue_id> | 列出工单评论 | | issue comment add <issue_id> --content <内容> | 添加评论 |

聊天记录 (chat-history)

查询客户导入的聊天记录，用于 SA（场景动作）清洗，非 Agent 自身的对话记录。

| 命令 | 说明 | | ------------------------------------------------------ | --------------- | | chat-history --agent <id> [--page N] [--page-size N] | 查询客户导入的聊天记录 |

FAQ 知识库 (faq)

| 命令 | 说明 | | ---------------------------------------------------------------------------- | --------- | | faq list --agent <id> | 列出 FAQ 文件 | | faq add --agent <id> --file <文件名> --questions <问题1,问题2> --answers <答案=xxx> | 添加 FAQ 内容 |

会话管理 (conversation)

| 命令 | 说明 | | -------------------------------------------------------------------------------- | -------- | | conversation list --agent <id> [--user <用户名>] [--start <日期>] [--end <日期>] | 搜索会话 | | conversation records <conversation_id> [--page-size N] [--direction prev|next] | 获取会话聊天记录 |

Agent 调试 (debug)

| 命令 | 说明 | | ----------------------------------------------------------------------------------------------------------- | -------------------- | | debug ask --agent <id> --text <消息> [--user <用户名>] [--url <图片URL>] [--conversation <会话ID>] [--timeout <秒>] | 向 Agent 发送消息并等待回复 | | debug record <record_id> | 获取记录的调试信息（flow_info） |

debug ask 会自动创建调试会话、发送消息、轮询等待 Agent 回复，默认最大等待 30 秒。支持 --messages 传入完整消息列表（JSON 或 @文件）重放 issue 对话。

修复记录 (repair-record)

| 命令 | 说明 | | --- | --- | | repair-record list [--issue <工单ID>] [--agent <AgentID>] [--workspace <工作空间ID>] [--page N] [--page-size N] | 列出修复记录 | | repair-record create --issue <工单ID> --agent <AgentID> --action <修复动作> [--agent-name <名称>] [--type <类型>] [--status <状态>] [--duration <毫秒>] [--result <JSON>] [--workspace <工作空间ID>] | 创建修复记录 | | repair-record update <record_id> --data <json\|@file> | 更新修复记录 |

--status 可选值：pending、success、failed、partial。

repair-record update 的 --data 支持的字段：repair_action、repair_result（JSON 对象）、repair_type、repair_status、duration_ms。

repair_result 结构

--result 或 --data 中的 repair_result 字段应为结构化 JSON，用于记录 AI 修复的完整推理过程，支持未来 AI 自我进化。

| 字段 | 类型 | 说明 | | --- | --- | --- | | failure_type | string | 问题分类: wrong_answer / missing_answer / hallucination / wrong_routing / slow_response / other | | root_component | string | 归因组件: sa_policy / faq / product_knowledge / customer_config / prompt / multiple / unknown | | input | string | 触发问题的用户输入 | | expected | string | 期望的正确回复 | | actual | string | 实际的错误回复 | | diagnosis_reasoning | string | AI 的诊断推理过程：排查了什么、怎么定位根因、排除了哪些可能性（最高价值字段） | | diagnosis_confidence | string | 诊断置信度: high / medium / low | | hypotheses_considered | array | 考虑过的假设列表，每项含 hypothesis、evidence_for、evidence_against、verdict | | fix_strategy | string | 修复策略: create_sa / update_sa / delete_sa / update_faq / add_faq / update_product / update_config / multi_step | | fix_reasoning | string | AI 的修复决策推理：为什么选这个方案、为什么不选其他方案、预期风险和收益 | | alternatives_rejected | array | 被否决的方案列表，每项含 approach、reason | | changes | array | 变更快照，每项含 component、action、target_id、before、after | | target_fixed | boolean | 目标问题是否修复 | | regression_summary | string | 回归验证结果摘要 | | retry_history | array | 重试记录，每项含 round、what_failed、lesson、adjustment | | duration_ms | number | 修复总耗时（毫秒） | | repair_status | string | 最终状态: success / failed / partial | | resolved_date | string | 修复完成时间（ISO 格式） |

加粗的两个字段（diagnosis_reasoning 和 fix_reasoning）是对 AI 自我进化价值最大的：没有它们只能做模式匹配，有了它们才能做推理。

运营监控 (monitor)

直接调用 /v1/operation 底层接口，返回原始数据，由调用方决定如何聚合统计。

Agent 生命周期

| 命令 | 说明 | | --- | --- | | monitor agents [--page N] [--page-size N] | Agent 生命周期列表（含构建进度、会话统计等原始数据） |

监控工单

| 命令 | 说明 | | --- | --- | | monitor tickets list [--agent <id>] [--status <状态>] [--severity <级别>] | 列出监控工单 | | monitor tickets delete <ticket_id> | 删除监控工单 |

监控快照

| 命令 | 说明 | | --- | --- | | monitor snapshots hourly --agent <id> --start <ISO> --end <ISO> | 查询小时快照 | | monitor snapshots daily --agent <id> --start <日期> --end <日期> | 查询日快照 | | monitor snapshots daily-range --agent <id> --start <日期> --end <日期> | 查询日快照范围（含趋势） |

Agent 运营统计

| 命令 | 说明 | | --- | --- | | monitor statistics [--start <ISO> --end <ISO>] [--page N] [--page-size N] | Agent 运营统计（会话量、转人工率、响应时间等） |

运营工作空间

| 命令 | 说明 | | --- | --- | | monitor workspaces [--has-agent] [--page N] [--page-size N] | 运营工作空间列表（含合同、客户信息） |

输出格式

默认输出 JSON：

{
  "success": true,
  "data": { ... }
}

错误时：

{
  "success": false,
  "error": { "code": 1, "message": "错误信息" }
}

使用 --table 选项可以表格形式输出。

退出码

| 退出码 | 含义 | | --- | ------------------- | | 0 | 成功 | | 1 | 业务错误 | | 2 | 认证错误（未登录或 Token 过期） | | 3 | 网络/服务器错误 |

使用示例

# 测试 Agent 回复
cs-cli debug ask --agent a0901fe383064c2abefb0bf1cd52988e --text "你好"

# 获取调试信息
cs-cli debug record <record_id>

# 各工作空间 Issue 统计
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

# 搜索场景动作
cs-cli sa search --agent <id> --keyword "退款"

# 创建场景动作
cs-cli sa create --agent <id> --first-label "售后咨询" --second-label "退款" --situation "用户要求退款" --action "引导用户提交退款申请"

# 查看场景动作修改记录
cs-cli sa versions --agent <id> --id 3

# 使用 JSON 文件更新 Agent
cs-cli agent update <config_id> --data @config.json

# 更新商品卖点
cs-cli product update --agent <id> --product-id 977691714398 --update '{"卖点":"新卖点"}'

# 更新商品标签
cs-cli product update --agent <id> --product-id 977691714398 --update '{"tag":"春季新品,热卖"}'

# 更新 SKU 补充知识
cs-cli product update-sku --agent <id> --sku "颜色分类:粉红" --update '{"补充知识":"粉红色为浅粉调"}'

# 添加 FAQ
cs-cli faq add --agent <id> --file "常见问题" --questions "怎么退款,如何退款" --answers "答案=请联系客服处理退款"

# 重放对话测试 Agent
cs-cli debug ask --agent <id> --messages @conversation.json

# 列出某工单的修复记录
cs-cli repair-record list --issue <issue_id>

# 创建修复记录
cs-cli repair-record create --issue <issue_id> --agent <agent_id> --action "更新 SA 策略"

# 更新修复记录状态
cs-cli repair-record update <record_id> --data '{"repair_status":"success","duration_ms":1200}'