@shulex/cxclawctl 0.1.2 → 0.1.3

package/skills/solvea-kit/references/chat.md

@@ -1,244 +0,0 @@
-# 对话测试
-
-> 已过时：POC 测试走 `poc`，交付回归走 `delivery`，原始会话与运营数据走 `agent-analytics`，badcase 上下文排查走 `shulex-support` 的 Agent 会话诊断场景，CHAT_FLOW 测试注意事项走 `agent-builder`。本文件仅保留历史兼容，不作为新任务入口。
-
-## 单轮测试
-
-### API
-
-| 操作 | 方法 | 路径 | 说明 |
-|------|------|------|------|
-| 对话测试 | POST | `/api_v2/gpt/bot/{botId}/chat` | 单轮或多轮（传 chatId） |
-
-### CLI
-
-```bash
-npx --yes @shulex/cxclawctl@latest api chat -m "你好" --pretty
-```
-
----
-
-## 多轮测试（Session）
-
-多轮对话时，每轮请求必须传入上一轮返回的 `chatId`，否则每次开新会话、上下文断开。
-
-### CLI
-
-```bash
-npx --yes @shulex/cxclawctl@latest api chat -m "你好" --pretty
-# 从返回中取 chatId
-npx --yes @shulex/cxclawctl@latest api chat -m "继续问" --chat-id <上轮chatId> --pretty
-```
-
-### Python 示例
-
-```python
-from client import SolveaClient
-client = SolveaClient()
-
-r1 = client.chat("你好")
-chat_id = r1.get("chatId")
-r2 = client.chat("继续问", chat_id=chat_id)
-```
-
-### 对话详情与 Badcase 溯源
-
-| 操作 | 方法 | 路径 | 说明 |
-|------|------|------|------|
-| 收件箱列表 | POST | `/api_v2/gpt/project/{pid}/transcripts/filter` | 返回会话摘要，不含完整内容 |
-| 对话详情（按 chatId） | GET | `/api_v2/gpt/project/{pid}/transcript/{chatId}?isCompare=true` | 获取单条完整对话 |
-| Badcase 溯源（按轮次） | POST | `/api_v2/gpt/bot/{botId}/chat/context/compare` | 返回检索知识、tool call 详情、最终 answer |
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-transcripts --pretty
-```
-
-Badcase 分析标准流程：
-1. `get-transcript --chat-id <chatId>` — 获取完整对话数据，定位问题轮次
-2. `get_chat_context_compare(bot_id, turn_data)` — 传入该轮 context，返回检索知识、tool call 详情、最终 answer
-
----
-
-## CHAT_FLOW Agent 测试注意事项
-
-CHAT_FLOW Agent 不能用 `metadata.specified_agent_id`（或老版 `specified_agent_data`）这类强制 agent 路由直接测试，必须通过策略路由。
-
-完整测试流程：
-1. 创建意图（`create-intent`）
-2. 创建策略（`create-strategy`），将意图路由到目标 CHAT_FLOW Agent
-3. 启用策略（`toggle-strategy --enable`）
-4. 编写测试用例 JSON
-5. 运行当前业务 skill 指定的测试 runner
-6. 根据失败项调整 Agent → 重跑测试直到通过率达标
-
----
-
-## 批量测试
-
-> POC 测试业务流程归属 `poc` skill，交付回归业务流程归属 `delivery` skill。
-> 测试 runner 已归属到对应业务 skill。
-
-### 用法
-
-```bash
-# POC 测试：先读 /skills/poc/interfaces/poc-test.md
-# Delivery 回归：先读 /skills/delivery/interfaces/delivery-test.md
-
-# 校验 chatflow 图结构（chatflow 能力在 agent-builder skill 下）
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/validate_graph.py --data-file graph.json
-```
-
-### 测试用例格式（JSON Schema）
-
-```json
-[
-  {
-    "name": "测试名称",
-    "category": "分类",
-    "messages": ["用户消息1", "用户消息2（多轮）"],
-    "expected": {
-      "intent": "期望意图名（模糊匹配）",
-      "content_contains": ["回复须包含的关键词"],
-      "content_not_contains": ["回复不应包含的关键词"],
-      "handoff": false,
-      "flow_status": "success",
-      "nodes_executed": ["REPLY", "AGENT"]
-    }
-  }
-]
-```
-
-### expected 字段说明
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `intent` | string | 期望意图名，模糊匹配 |
-| `content_contains` | string[] | 回复内容必须包含的关键词列表 |
-| `content_not_contains` | string[] | 回复内容不应包含的关键词列表 |
-| `handoff` | boolean | 是否期望转人工 |
-| `flow_status` | string | 期望流程状态，如 `"success"` |
-| `nodes_executed` | string[] | 期望执行的节点类型列表 |
-
-### 含节点执行检查的测试用例示例
-
-```json
-{
-  "name": "修改地址-完整流程",
-  "messages": ["I want to change my address for order 12345"],
-  "expected": {
-    "intent": "Modify Order",
-    "flow_status": "success",
-    "nodes_executed": ["REPLY", "AGENT"],
-    "content_contains": ["address"]
-  }
-}
-```
-
-### 自动判定为失败的条件
-
-以下情况无论回复内容如何，测试工具自动判定为失败：
-- 回复内容为 `INTERNAL_ERROR`
-- `response.type` 为 `STOPPED` 或 `CONFUSED`
-
-## 自动化测试闭环
-
-用真实对话数据验证 Agent 配置效果，替代人工编写测试用例。
-
-```
-Step 1: 拉取真实对话数据
-  client.export_transcripts() → 轮询 → 下载 xlsx
-  （可选）client.list_intents/list_agents/list_plugins
-
-Step 2: 转化为测试用例
-  从 inbox 提取每条对话的用户消息序列（按提问顺序）
-  单轮对话 → messages: [首条消息]
-  多轮对话 → messages: [消息1, 消息2, ...]（保持原始顺序）
-
-Step 3: 批量测试
-  POC 按 /skills/poc/interfaces/poc-test.md
-  Delivery 按 /skills/delivery/interfaces/delivery-test.md
-  检查：意图识别、节点执行链路、INTERNAL_ERROR、回复质量
-
-Step 4: 分析结果 → 生成优化方案
-  - 意图误识别 → 调整意图 description
-  - 节点执行失败 → 修复 CHAT_FLOW 图
-  - 回复不准确 → 调整 Agent prompt
-  - 策略未命中 → 修复策略条件
-  列出待修改清单，和用户确认后自动执行
-
-Step 5: 自动执行修改
-  用户确认后，调 API 更新意图/策略/Agent
-
-Step 6: 重新测试
-  再次运行 batch test，对比前后通过率
-  循环 Step 4-6 直到达标
-```
-
-### 从线上导出 inbox 数据
-
-```python
-from client import SolveaClient
-import time
-
-client = SolveaClient()
-
-# 1. 提交导出任务（默认近 1 个月）
-result = client.export_transcripts(page_size=1000, time_offset=8)
-task_id = result.get("taskId")
-
-# 2. 轮询任务状态
-while True:
-    tasks = client.get_export_tasks()
-    task = next((t for t in tasks if str(t["id"]) == str(task_id)), None)
-    if task and task["status"] == "SUCCESS":
-        file_url = task["file"]
-        break
-    time.sleep(5)
-
-# 3. 下载 xlsx 并读取
-# curl -o /tmp/inbox_export.xlsx '<file_url>'
-```
-
-| 操作 | 方法 | 路径 | 说明 |
-|------|------|------|------|
-| 提交导出任务 | POST | `/api_v2/gpt/project/{pid}/transcripts/export/async` | |
-| 轮询导出状态 | POST | `/api_v2/gpt/label/project/{pid}/getLabelTask` | status=SUCCESS 时取 file URL |
-
-```bash
-npx --yes @shulex/cxclawctl@latest api export-transcripts --pretty
-npx --yes @shulex/cxclawctl@latest api get-export-tasks --pretty
-```
-
-### 转化真实数据为测试用例
-
-```python
-test_cases = []
-for conversation in inbox_data:
-    user_messages = [msg["content"] for msg in conversation["messages"]
-                     if msg["role"] == "user"]
-    if user_messages:
-        test_cases.append({
-            "name": f"real_{conversation['id']}",
-            "category": "production_data",
-            "messages": user_messages,
-            "expected": {}
-        })
-```
-
-### 优化调整规则
-
-1. 意图误识别率 > 10% → 修改意图 description，扩展或收窄匹配范围
-2. 策略未命中 → 检查条件规则，修复 apiName/relation/values
-3. INTERNAL_ERROR → 检查 CHAT_FLOW 图结构（validate_graph）
-4. 回复不准确 → 调整 prompt，增加业务规则说明
-5. 多轮断开 → 检查 maxRounds 配置
-
----
-
-## 原则
-
-- 多轮对话必须传 chatId，否则每次开新会话、上下文断开
-- 测试驱动配置：配置 Agent 后必须通过批量测试验证，不能只配置不测试
-- 测试用例必须覆盖 CHAT_FLOW 的每一个流程节点和分支，包括负面用例（不应匹配的意图）
-- 仅检查回复内容不够，CHAT_FLOW 测试必须同时检查 `nodes_executed` 和 `flow_status`
-- 每次调整后必须重跑测试，对比通过率变化

package/skills/solvea-kit/references/intent.md

@@ -1,69 +0,0 @@
-# 意图管理
-
-## 能力概览
-
-创建、查询、更新、启用/禁用 Shulex 策略路由使用的系统意图。
-
-意图（Intent）代表用户的问题类型，如"退款"、"查询订单"。策略路由依赖意图 id 将对话分派给正确的 Agent。
-
-CHAT_FLOW 内的 INTENT 节点直接在节点配置里定义意图（填 name + desc），不需要调用系统意图接口创建。策略路由的意图才需要通过 API 创建。
-
-## API
-
-| 操作 | 方法 | 路径 | 说明 |
-|------|------|------|------|
-| 意图列表 | GET | `/api_v2/gpt/project/{pid}/intents` | |
-| 创建意图 | POST | `/api_v2/gpt/project/{pid}/intent` | |
-| 意图详情 | GET | `/api_v2/gpt/project/{pid}/intent/{id}` | |
-| 更新意图 | PUT | `/api_v2/gpt/project/{pid}/intent/{id}` | |
-| 启用/禁用意图 | PUT | `/api_v2/gpt/project/{pid}/intent/{id}/status` | |
-
-## CLI
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-intents --pretty
-
-npx --yes @shulex/cxclawctl@latest api get-intent --id <intent_id> --pretty
-
-npx --yes @shulex/cxclawctl@latest api create-intent \
-  --data '{"name":"退款","description":"用户要求退款","type":"Other","status":"ENABLED","category":"E_COMMERCE"}'
-
-# 更新意图描述（PUT body 字段是 description，name 必传）
-npx --yes @shulex/cxclawctl@latest api update-intent --id <intent_id> \
-  --data-file /workspace/state/solvea-kit/intent_update.json
-
-# 短描述可直接使用 --data；长描述先写入 JSON 文件，再通过 --data-file 提交
-
-npx --yes @shulex/cxclawctl@latest api toggle-intent --id <intent_id> --disable
-npx --yes @shulex/cxclawctl@latest api toggle-intent --id <intent_id> --enable
-```
-
-## update-intent 字段说明（GET / PUT 字段命名不一致，必看）
-
-API 在 GET 和 PUT 之间字段名不对齐，照搬 GET 输出回写会失败：
-
-| GET 返回 | PUT body | 用途 |
-|---------|----------|------|
-| `name` | `name` | 意图名（必传） |
-| **`example`** | **`description`** | 意图描述。GET 返回的 `example` 字段对应 PUT 的 `description`，**不要照搬 GET 字段名** |
-| `enableCollect` | `enableCollect` | 一致 |
-| `collects` | `collects` | 一致 |
-| 其它字段（`callCount` / `createdAt` / `source` 等只读） | 不传 | 服务端维护 |
-
-仅更新描述时，body 最小必填：
-
-```json
-{
-  "name": "Package issues",
-  "description": "...",
-  "enableCollect": false,
-  "collects": []
-}
-```
-
-## 原则
-
-- 创建意图前先查 `list-intents`，避免重复创建同名意图
-- 更新意图：先 `get-intent` 拿当前 `name`（必传），用 `description` 字段（不是 `example`）写新描述
-- CHAT_FLOW 的 INTENT 节点内直接定义意图（`config.intents[]` 的 name + desc），`intents[].intentId` 留空，不要调用 `create-intent` 接口
-- 意图 name 建议纯 ASCII，与 INTENT 节点 name 字段约定一致

package/skills/solvea-kit/references/plugin.md

@@ -1,53 +0,0 @@
-# 工具管理（Legacy 兼容入口）
-
-> 本文件不再维护工具 schema。工具查看、创建、更新、调试、MockData 和 X-Token 配置统一由 `agent-builder` 负责。
-
-权威文档：
-
-- 总入口：`../../agent-builder/references/tools/overview.md`
-- HTTP 参数、状态映射、relation/value 契约：`../../agent-builder/references/tools/http-tool.md`
-- Mock / Excel / CSV：`../../agent-builder/references/tools/mock-tool.md`
-- X-Token：`../../agent-builder/references/tools/x-token.md`
-
-底层兼容命名仍是 `plugin` / `pluginId` / `queryPlugin`，常见工具类型仍是 `EXTERNAL_HTTP_CALL`。旧任务进入本页后，应立即转到上述 agent-builder 文档，不在这里复制或推导另一套 payload。
-
-## 核心命令入口
-
-统一使用 `/workspace/state/agent-builder/` 保存跨轮配置：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-plugins --pretty
-
-npx --yes @shulex/cxclawctl@latest api get-plugin --id <tool_id> --pretty
-
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/tools/validate_tool_config.py \
-  --data-file /workspace/state/agent-builder/tool_<name>.json --pretty
-
-npx --yes @shulex/cxclawctl@latest api create-plugin \
-  --data-file /workspace/state/agent-builder/tool_<name>.json --pretty
-
-npx --yes @shulex/cxclawctl@latest api update-plugin \
-  --data-file /workspace/state/agent-builder/tool_<name>.json --pretty
-
-npx --yes @shulex/cxclawctl@latest api replace-mock-data \
-  --name <mock_type> \
-  --data-file /workspace/state/agent-builder/mock_records.json --pretty
-
-npx --yes @shulex/cxclawctl@latest api query-mock-data \
-  --name <mock_type> --pretty
-
-npx --yes @shulex/cxclawctl@latest api run-plugin \
-  --data-file /workspace/state/agent-builder/run_tool_config.json --pretty
-```
-
-`run_tool_config.json` 必须使用 `externalHttpCallConfig` + `externalHttpCallRequestBody` envelope；具体结构只看 agent-builder 的 `http-tool.md`。
-
-## 兼容与安全边界
-
-- 创建前先查重并运行静态 validator；写入前确认环境和影响范围；创建后使用 `get-plugin` 回查完整定义。
-- Authorization、X-Token 等鉴权 Header 按普通 `headerParams` 配置。
-- `run-plugin` 会真实调用目标接口，只在用户明确要求或授权后执行。目标为写接口时，执行前还要额外确认请求体和影响范围；它不是创建或上线的默认步骤。
-- MockData 的 `replace-mock-data` 是全量替换写操作，执行前必须确认；`--name` 在 MockData 命令中表示 `mock_type`。
-- BOOLEAN 状态规则兼容 JSON boolean `true` / `false` 和前端保存的字符串 `"true"` / `"false"`；手写 JSON 推荐 boolean。完整类型与 relation 约束以 agent-builder 的 `http-tool.md` 为准。
-- `actionStatuses` 默认分支兼容 `"condition": {}` 和 `"condition": {"or": []}`；新建配置推荐 canonical `{}`，但 `or: []` 同样合法。
-- 工具绑定格式和节点边界按具体 Agent 形态的 agent-builder 文档处理，不沿用本 legacy 文件的历史示例。

package/skills/solvea-kit/references/quality-inspection.md

@@ -1,75 +0,0 @@
-# AI 质检管理
-
-本模块管理系统的 AI 质检开关、系统规则、自定义规则和预警。质检结果运营分析仍由 `agent-analytics` 负责；这里仅在用户要调整配置或查看规则命中时使用。
-
-## 查询与总开关
-
-先读取现状。开启或关闭会影响项目后续 Agent 回复的质检行为，必须说明影响并在用户确认后写入：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-quality-status --pretty
-npx --yes @shulex/cxclawctl@latest api list-quality-rules \
-  --begin-ts <epoch_ms> --end-ts <epoch_ms> --pretty
-npx --yes @shulex/cxclawctl@latest api set-quality-status --enable --pretty
-```
-
-关闭时使用 `--disable`。不要修改 GPT 的 Nacos `quality-inspection-gate`；它是平台灰度与消息过滤配置，不是租户可管理的质检开关。
-
-## 系统规则
-
-先读取规则清单与详情，再展示将要修改的范围、识别/拦截动作、启停状态和适用 Agent。系统规则只能更新，不能删除或更改为自定义规则：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-quality-rule \
-  --inspection-key <rule_key> --pretty
-npx --yes @shulex/cxclawctl@latest api update-quality-rule \
-  --data-file /workspace/state/solvea-kit/quality_rule_update.json --pretty
-```
-
-## 自定义规则
-
-自定义规则可包含以下配置：
-
-- `name`：规则名称
-- `customPrompt`：自然语言质检要求
-- `words`：敏感词数组；可与 `customPrompt` 二选一或同时使用
-- `scope`：`0` 客服回复、`1` 客户来信、`2` 全部消息
-- `type`：`1` 仅识别、`2` 拦截；`scope=2` 时只能使用仅识别
-- `checkAllAgent`、`agentIds`、`autoAddAgent`：适用 Agent 范围
-- `filterAmazon`：是否过滤 Amazon 场景
-
-先生成 JSON 并向用户展示，确认后再创建、更新或删除：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api create-custom-quality-rule \
-  --data-file /workspace/state/solvea-kit/custom_quality_rule_create.json --pretty
-npx --yes @shulex/cxclawctl@latest api get-custom-quality-rule \
-  --inspection-key <rule_key> --pretty
-npx --yes @shulex/cxclawctl@latest api update-custom-quality-rule \
-  --data-file /workspace/state/solvea-kit/custom_quality_rule_update.json --pretty
-npx --yes @shulex/cxclawctl@latest api delete-custom-quality-rule \
-  --inspection-key <rule_key> --pretty
-```
-
-不要自行把规则设为拦截；用户没有明确要求时默认建议“仅识别”。删除规则前必须说明该规则将停止对后续消息生效。
-
-## 预警
-
-预警规则关联一个或多个质检规则，并可配置即时或每日汇总、邮箱或机器人 Webhook 通知。Webhook 和邮箱地址属于敏感配置：展示时脱敏，更新前必须确认。
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-quality-alert-rules --pretty
-npx --yes @shulex/cxclawctl@latest api get-quality-alert-rule --id <alert_id> --pretty
-npx --yes @shulex/cxclawctl@latest api create-quality-alert-rule \
-  --data-file /workspace/state/solvea-kit/quality_alert_create.json --pretty
-npx --yes @shulex/cxclawctl@latest api update-quality-alert-rule \
-  --data-file /workspace/state/solvea-kit/quality_alert_update.json --pretty
-npx --yes @shulex/cxclawctl@latest api delete-quality-alert-rule --id <alert_id> --pretty
-npx --yes @shulex/cxclawctl@latest api list-quality-alert-messages \
-  --data-file /workspace/state/solvea-kit/quality_alert_messages_query.json --pretty
-npx --yes @shulex/cxclawctl@latest api get-quality-alert-message --id <message_id> --pretty
-```
-
-## 结果排查边界
-
-规则命中趋势和汇总可通过 `report-inspection` / `report-inspection-history` 查询；要分析具体会话或质检判断原因，转 `agent-analytics`。Agent 回复后的运行质检由 GPT 调 Intelli 执行，字段配置由 Tars 管理，不要跨这两个边界猜测数据来源。

package/skills/solvea-kit/references/strategy.md

@@ -1,62 +0,0 @@
-# 策略管理
-
-Strategy（策略）定义了：当某个条件（意图、触点、实体等）满足时，执行什么动作，例如路由到 Agent、回复模板、AI 回复、转人工或不处理。
-
-## 条件构建（Condition）
-
-先调 `list-entities` 获取可用条件实体（apiName、apiType、source、metadata），然后组装 condition：
-
-```json
-{
-  "and": [
-    {"rules": [{"apiName": "__touch_point", "apiType": "TEXT", "source": "SYSTEM", "relation": "IN", "values": ["LIVE_CHAT"]}]},
-    {"rules": [{"apiName": "__intent_ids", "apiType": "TEXT", "source": "SYSTEM", "relation": "IN", "values": [9750]}]}
-  ]
-}
-```
-
-`__intent_ids` 的 values 字段使用 `int(intent_id)`，不要用字符串。
-
-## 动作类型（Action）
-
-| 类型 | 说明 | 必需字段 |
-|------|------|---------|
-| `AGENT` | 路由到指定 Agent | agentId |
-| `TEMPLATE_REPLY` | 回复固定模板 | templateId |
-| `TEMPLATE_REPLY_AND_TRANSFER_TO_AGENT` | 模板回复后转人工 | templateId |
-| `AI_REPLY` | AI 生成回复 | - |
-| `AI_REPLY_AND_TRANSFER_TO_AGENT` | AI 回复后转人工 | - |
-| `DO_NOTHING` | 不做任何操作 | - |
-
-## API
-
-| 操作 | 方法 | 路径 | 说明 |
-|------|------|------|------|
-| 可用实体列表 | GET | `/api_v2/gpt/project/{pid}/entities` | 获取 apiName、apiType、source |
-| 创建策略 | POST | `/api_v2/gpt/project/{pid}/strategy?v4=true` | 必须带 v4=true |
-| 更新策略 | PUT | `/api_v2/gpt/project/{pid}/strategy/{id}?v4=true` | 必须带 v4=true |
-| 启用/禁用策略 | - | - | 通过 toggle-strategy CLI |
-
-## CLI
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-entities --pretty
-npx --yes @shulex/cxclawctl@latest api list-strategies --pretty
-
-npx --yes @shulex/cxclawctl@latest api create-strategy \
-  --data '{"name":"退款路由","trigger":"MESSAGE","condition":{...},"action":{"type":"AGENT","agentId":2270}}'
-
-npx --yes @shulex/cxclawctl@latest api update-strategy --id <strategy_id> \
-  --data-file /workspace/state/solvea-kit/update_strategy.json
-
-npx --yes @shulex/cxclawctl@latest api toggle-strategy --id <strategy_id> --enable
-npx --yes @shulex/cxclawctl@latest api toggle-strategy --id <strategy_id> --disable
-```
-
-## 原则
-
-- 创建/更新策略接口参数由 SolveaClient 自动处理，无需额外传参。
-- `__intent_ids` 的 values 字段使用 int，不要使用字符串形式。
-- 配置策略后必须执行 `toggle-strategy --enable` 启用，否则不生效。
-- 测试 CHAT_FLOW 时，必须先创建策略将意图路由到 Agent，再通过 chat 接口发送匹配消息测试；不能用 `metadata.specified_agent_id` / `metadata.specified_agent_data` 这类强制 agent 路由直接测试 CHAT_FLOW Agent。
-- Agent 构建、工具配置和 CHAT_FLOW 图不在本文档维护，走 `agent-builder`。