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 | | AI API | https://ai-api.betteryeah.com | | Customer Agent | https://customer-agent.bantouyan.com | | Langfuse | http://192.168.40.10:3000 |

AI API 同时服务于登录认证（auth login / auth whoami），不再区分独立的 "认证 API" 字段。

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

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

API 地址优先级

每个 API 地址的读取顺序为 环境变量 > config.json > 内置默认值。环境变量为 undefined 或空字符串 "" 都视为未设置，继续向下 fallback。

| 环境变量 | 覆盖字段 | 默认值 | | ----------------------- | ------------------- | --------------------------------------------- | | CS_CS_API_URL | customerServiceApiUrl | https://customer-servhub-api.betteryeah.com | | CS_AI_API_URL | aiApiUrl（同时服务 auth 调用） | https://ai-api.betteryeah.com | | CS_CUSTOMER_AGENT_URL | customerAgentApiUrl | https://customer-agent.bantouyan.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 文件，为不同项目配置不同的工作空间。

工作空间优先级

| 优先级 | 来源 | 说明 | | --- | ----------------------- | ---------------------------- | | 0 | CS_WORKSPACE_ID 环境变量 | env lock，最高优先级，override 硬失败（见下方"环境变量锁定"） | | 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 → 强制写入全局配置

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

环境变量锁定（sandbox / CI）

当 sandbox、CI 等非交互环境预先注入以下环境变量时，cs-cli 会透明地把 env 作为凭据与上下文来源，并拒绝任何运行时 override（--workspace / --agent / auth login 等），避免下游脚本在上下文被静默切换时产生未定义行为。

| 环境变量 | 作用 | | ----------------- | ------------------------- | | CS_AUTH | 登录凭据（等同 access token）。存在即视为"已锁定" | | CS_WORKSPACE_ID | 锁定工作空间 ID | | CS_AGENT_ID | 锁定默认 agent ID |

处理逻辑：

1. env 优先：只要环境变量有值，cs-cli 就从 env 读取，忽略本地 credentials.json / .cs-cli.json / 全局配置。
2. override 硬失败：锁定后如果再通过 --workspace / --agent / auth login / auth logout / config set-workspace 传入不一致的值，cs-cli 立刻报错退出，不会静默覆盖。
3. 幂等传值：override 与 env 值完全一致时允许通过（便于脚本显式断言）。

使用示例：

export CS_AUTH="<your-access-token>"
export CS_WORKSPACE_ID="ws-abc123"
export CS_AGENT_ID="agent-xyz"

cs-cli agent list     # 直接运行，无需 auth login
cs-cli --workspace ws-other agent list   # ❌ 报错：CS_WORKSPACE_ID 已被锁定

要解除锁定，清空对应环境变量即可（unset CS_AUTH CS_WORKSPACE_ID CS_AGENT_ID）。

命令速查表

认证 (auth)

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

配置 (config)

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

工作空间 (workspace)

| 命令 | 说明 | | --- | --- | | workspace list | 列出所有工作空间 | | workspace points-consumes-daily [--start <YYYY-MM-DD>] [--end <YYYY-MM-DD>] | 按天查询工作空间积分消耗（默认最近 30 天） |

workspace points-consumes-daily 需要可用的工作空间上下文（--workspace、本地 .cs-cli.json 或全局 defaultWorkspaceId）。

# 查询最近 30 天（默认）
cs-cli workspace points-consumes-daily

# 指定日期范围（含 start/end）
cs-cli workspace points-consumes-daily --start 2026-04-01 --end 2026-04-23

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名称> \| --sku-id <id>) --update <json\|@file> | 更新 SKU 信息（--sku-id 优先于 --sku） | | product learn --agent <id> --url <URL...> [--source <type>] [--no-identify] | 通过商品 URL 异步学习（manual / identify 默认开启） |

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

product learn 提交商品详情页 URL 进入异步学习队列（/v1/knowledge/products/upload），返回 flow_id 和 knowledge_ids。--url 可多值，用空格分隔；--source 默认 manual；传 --no-identify 可关闭自动识别。

# 更新卖点
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 补充知识（按 SKU 名称定位）
cs-cli product update-sku --agent <id> --sku "颜色分类:粉红" --update '{"补充知识":"说明内容"}'

# 更新 SKU 补充知识（按 sku_id 定位，推荐）
cs-cli product update-sku --agent <id> --sku-id 6072595054179 --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 内容 | | faq update --agent <id> --file <文件名> --group-id <id> [--questions <...>] [--answers <...>] [--delete-chunks <id1,id2>] | 更新已有 FAQ 答案组（--questions / --answers / --delete-chunks 至少一个） | | faq delete --agent <id> --file <文件名> --group-id <id> | 删除 FAQ 答案组 |

faq update 按 answer_group_id 定位目标组，POST 同一个 faq_contents/save 接口完成字段替换、问题替换与 chunk 级删除。faq delete 走 DELETE /faq_contents/{group_id} 整组删除。

扩展知识库 (knowledge)

Agent 关联的通用规则知识库（suffix_type=_common），与 FAQ / 商品知识并列的第三类知识源，支持段落（chunk）级 CRUD，统一走 /mebsuta/api/v1/dataset/{id}/contents/perform-operations。

| 命令 | 说明 | | --- | --- | | knowledge list --agent <id> [--page N] [--page-size N] | 列出 Agent 关联的扩展知识库文件 | | knowledge content list --knowledge-id <id> [--page-size N] [--direction up\|down] | 列出段落（chunk） | | knowledge content add --knowledge-id <id> --content <text\|@file> [--keyword <k...>] [--after <chunk_id>] | 新增段落 | | knowledge content update --knowledge-id <id> --chunk-id <id> [--content <text\|@file>] [--keyword <k...>] [--enable \| --disable] | 更新段落（四个变更字段至少一个；未指定 --enable / --disable 时自动保留当前启停状态，避免后端 enable 必填校验失败） | | knowledge content delete --knowledge-id <id> --chunk-id <id> | 删除段落 |

knowledge content add / update 的 --content 支持 @路径 前缀从文件读取纯文本（不是 JSON）。--keyword 为 variadic 选项，空格分隔多个关键词。

会话管理 (conversation)

| 命令 | 说明 | | -------------------------------------------------------------------------------- | -------- | | 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 天） |

Agent 调试 (debug)

| 命令 | 说明 | | ----------------------------------------------------------------------------------------------------------- | -------------------- | | debug ask --agent <id> --text <消息> [--user <用户名>] [--url <图片URL>] [--conversation <会话ID>] [--timeout <秒>] | 向 Agent 发送消息并等待回复 | | debug reproduce <record_id> [--agent <id>] [--timeout <秒>] [--dry-run] | 根据 record_id 复现 Agent 回复（自动获取上下文） | | debug record <record_id> | 获取记录的调试信息（flow_info），返回中包含 trace_id | | debug trace <trace_id> | 根据 Langfuse Trace ID 获取完整 Trace 详情 |

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

debug reproduce 根据一条回复记录自动复现 Agent 回复：通过 recordId 获取关联会话和 Agent 配置，拉取完整会话记录并截取目标 record 之前的上下文，使用原始用户名创建新 debug 会话并发送。--agent 可指定另一个 Agent 复现同一段上下文（A/B 对比），--dry-run 仅输出上下文不发送。

debug trace 直接调用 Langfuse REST API（GET /api/public/traces/:traceId），使用 Basic Auth 认证。Trace ID 从 debug record 返回的 trace_id 字段获取。

Langfuse 配置

Langfuse 已内置默认连接信息，通常无需配置。如需覆盖，支持环境变量和配置文件两种方式：

环境变量（优先级最高）：

export LANGFUSE_BASE_URL="http://192.168.40.10:3000"
export LANGFUSE_PUBLIC_KEY="pk-lf-xxx"
export LANGFUSE_SECRET_KEY="sk-lf-xxx"

配置文件（~/.cs-cli/config.json）：

cs-cli config set --langfuse-host <url> --langfuse-public-key <key> --langfuse-secret-key <key>

修复记录 (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 自我进化价值最大的：没有它们只能做模式匹配，有了它们才能做推理。

运维操作记录 (ops-record)

| 命令 | 说明 | | --- | --- | | ops-record list [--workspace <工作空间ID>] [--agent <AgentID>] [--page N] [--page-size N] | 列出运维操作记录 | | ops-record get <record_id> | 获取运维操作记录详情 | | ops-record create --workspace <工作空间ID> --agent <AgentID> [--workspace-name <名称>] [--agent-name <名称>] [--path <文件路径>] [--remark <备注>] | 创建运维操作记录 | | ops-record update <record_id> --data <json\|@file> | 更新运维操作记录 | | ops-record delete <record_id> | 删除运维操作记录（软删除） |

ops-record update 的 --data 支持的字段：workspace_name、agent_name、path、remark。

创建记录时 operator_id 和 operator_name 自动从当前登录用户获取，无需手动指定。

运营监控 (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 "你好"

# 获取调试信息（返回 flow_info 和 trace_id）
cs-cli debug record <record_id>

# 根据 trace_id 查询 Langfuse Trace 详情
cs-cli debug trace <trace_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 补充知识（按 sku_id 定位，推荐）
cs-cli product update-sku --agent <id> --sku-id 6072595054179 --update '{"补充知识":"粉红色为浅粉调"}'

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

# 更新已有 FAQ 组答案
cs-cli faq update --agent <id> --file "常见问题" --group-id 2 --answers "答案=请通过订单页面申请退款"

# 更新 FAQ 组问题 + 删除旧 chunk
cs-cli faq update --agent <id> --file "常见问题" --group-id 2 --questions "如何退款,怎么申请退款" --delete-chunks 3,5

# 删除整个 FAQ 答案组
cs-cli faq delete --agent <id> --file "常见问题" --group-id 2

# 列出 Agent 的扩展知识库
cs-cli knowledge list --agent <id>

# 列出某扩展知识库的段落
cs-cli knowledge content list --knowledge-id 622474

# 新增段落（插入到末尾）
cs-cli knowledge content add --knowledge-id 622474 --content "退换货需保留商品吊牌" --keyword 退换货 吊牌

# 用文件内容作为段落
cs-cli knowledge content add --knowledge-id 622474 --content @./rules.txt

# 修改段落内容并重设关键词
cs-cli knowledge content update --knowledge-id 622474 --chunk-id 2 --content "新的规则说明" --keyword 规则 说明

# 停用某段落
cs-cli knowledge content update --knowledge-id 622474 --chunk-id 2 --disable

# 删除段落
cs-cli knowledge content delete --knowledge-id 622474 --chunk-id 2

# 商品 URL 异步学习
cs-cli product learn --agent <id> --url https://detail.tmall.com/item.htm?id=997678657962

# 多个 URL 一次提交，且跳过自动识别
cs-cli product learn --agent <id> --url https://a.example/1 https://a.example/2 --no-identify

# 通过上下文内容模糊搜索对话记录（自动使用当前工作空间，查询窗口最多 3 天）
cs-cli conversation context-search --query "退款问题" --start 2026-03-22T00:00:00 --end 2026-03-22T23:59:59

# 复现某条回复（自动获取上下文、原始用户名、Agent 配置）
cs-cli debug reproduce <record_id>

# 用另一个 Agent 复现同一段上下文（A/B 对比）
cs-cli debug reproduce <record_id> --agent <other_config_id>

# 仅查看截断后的上下文，不实际发送
cs-cli debug reproduce <record_id> --dry-run

# 重放对话测试 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}'

# 列出运维操作记录
cs-cli ops-record list --workspace <workspace_id> --agent <agent_id>

# 创建运维操作记录
cs-cli ops-record create --workspace <workspace_id> --agent <agent_id> --remark "更新配置文件"

# 更新运维操作记录
cs-cli ops-record update <record_id> --data '{"remark":"已完成配置更新","path":"/data/config"}'

# 删除运维操作记录
cs-cli ops-record delete <record_id>