@shulex/cxclawctl 0.1.2 → 0.1.3

package/skills/agent-analytics/SKILL.md

@@ -1,74 +0,0 @@
----
-name: agent-analytics
-description: Shulex 客服智能体（AI Agent）运营数据分析。用于统计指标、趋势、排行、报表和运营下钻；badcase 或单次会话根因排查由 shulex-support 主责，本 skill 可按需提供统计和样本辅助证据。
-requires:
-  libs: [solvea-api]
----
-
-# Agent Analytics
-
-本 skill 用于查询和分析 Agent 运营数据。
-
-**边界规则：** 如果用户要求解释某次会话为什么异常，或提到 badcase、异常回复、失败节点、报错、卡住、答非所问，由 `shulex-support` 负责主诊断；本 skill 仍可在需要时提供整体指标、趋势或样本下钻，不单独替代根因诊断流程。
-
-在本 skill 中，数据分析页面中的**工单即 Agent 会话记录**，也是收件箱数据。统计指标默认通过系统正式的 Agent 看板（`/chatReport` 对应的 `chat-report/*` 接口）获取，工单明细和完整对话通过 Agent 会话记录接口获取。历史过渡的 `/dashboard` 页面已下线，禁止对其对接。
-
-## 场景分流
-
-- 查询统计指标、趋势、字段口径或页面对应接口：默认读取 `references/chat-report-fields.md`。
-- 只有用户明确要求“旧版报表”“/report”“statement”或“返回旧版”时，才读取标记为旧版的 `references/report-fields.md` 并调用 `report-*`。
-- 查询工单明细、筛选样本、分页或单条完整对话：读取 `references/transcript.md`。
-- 同一个问题同时需要统计和样本时，先读取 `chat-report-fields.md` 获取整体指标，再读取 `transcript.md` 下钻解释；若用户指定旧版，则把前者替换为标记为旧版的 `report-fields.md`。
-
-## 固定执行顺序
-
-1. **确认分析目标**：明确用户要看的指标、比较维度和期望结论。
-2. **确认时间范围**：缺少时间范围时必须询问用户，不默认查询本月、最近 30 天或前端默认窗口。
-3. **应用时区和过滤条件**：Agent 看板使用 `startDate` / `endDate`（`YYYY-MM-DD`），可选 `botId`、`channel`（或 `touchPoint`）、`intentId`、`agentId`；前端未选择渠道表示全部渠道，不要自动补 `LIVE_CHAT`。标记为旧版的 `report-*` 才使用毫秒时间戳和 `timeOffset=8`。
-4. **分别调用接口**：每个统计或 Agent 会话记录请求独立执行。不要使用 `&&` 把整批命令串起来，避免一个接口失败后跳过全部后续数据。
-5. **阶段性输出进展**：每完成一类指标，简要说明已拿到什么、缺少什么、下一步查什么。
-6. **按需下钻 Agent 会话记录**：复用当前查询的日期范围和适用过滤条件；`chat-report-inbox-scripts` 或 chat ID 可作为下钻入口。分页直到 `hasNext=false` 才能声称明细完整。
-7. **形成结论**：说明时间范围、时区、过滤条件、数据完整性、不可用指标和异常变化。
-
-## 数据边界
-
-- 某个接口失败时，把对应指标标记为**不可用**，继续请求其他独立指标。
-- 权限问题造成的静默零值、真实业务零值和后端异常必须区分，不能统一解释成“没有工单”。
-- 抽样 Agent 会话记录只能解释具体案例或提供定性线索，不能替代整体统计，也不能用少量样本推导总体比例。
-- 多段时间数据合并时，计数可以求和；比例必须根据合并后的分子和分母重新计算，不能直接平均各段比例。
-- AI 回复与预期或历史水平出现明显变化时，必须指出变化幅度、发生时间和受影响维度；证据不足时明确写成待验证假设。
-
-## CLI 入口
-
-所有数据通过以下入口获取：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api <command> ... --pretty
-```
-
-常用命令：
-
-| 场景 | 命令 |
-|---|---|
-| 服务能力（工单量、进线解决率、转人工率） | `chat-report-tickets` |
-| 服务能力（消息量、AI 回复率） | `chat-report-messages` |
-| 服务质量（CSAT 满意度、点赞点踩数、满意率） | `chat-report-satisfaction` |
-| 服务质量（首响时效、AI/人工平均首次响应耗时） | `chat-report-first-response` |
-| 服务收益（AI 售后挽回率） | `chat-report-return-retention` |
-| 风险与质检（规则命中与预警） | `chat-report-inspection-results` |
-| 意图工单分布与趋势 | `chat-report-intents` |
-| 智能体工单分布与趋势 | `chat-report-agents` |
-| 会话下钻查询脚本 | `chat-report-inbox-scripts` |
-| 旧版报表（仅用户明确指定） | `report-*` |
-| 旧版知识、LiveChat、质检、自学习等 | 对应 `report-*`（仅用户明确指定旧版） |
-| 收件箱 Agent 会话记录明细 | `list-transcripts` |
-| 单条完整 Agent 会话记录 | `get-transcript` |
-
-CLI 命令、参数和字段口径以本 skill 的 references 为准。遇到未知命令或字段时先回读对应 reference，不要猜测接口。
-
-## 回复要求
-
-- 先给核心结论，再给可核对的数据表和指标口径。
-- 趋势图使用 `render_chart`；比例轴在标题或轴名称中注明 `%`，不要使用不受支持的 formatter。
-- 明确列出失败接口、缺失指标、分页是否完成和结论置信度。
-- 用户需要文件时只生成 HTML 或 Markdown；未要求文件时直接在回复中说明结果。

package/skills/agent-analytics/references/chat-report-fields.md

@@ -1,36 +0,0 @@
-# ChatReport (Agent 看板) 字段与接口
-
-本文描述系统当前正式的 `/chatReport`（数据分析 - Agent 看板）页面使用的 `chat-report/*` 接口。默认所有 Agent Analytics 统计查询都使用这些接口；只有用户明确要求旧版 `/report`、`statement` 或“返回旧版”时才使用标记为旧版的 `report-fields.md`。原实验性 `/dashboard` 页面已下线，不得再对接到其接口。
-
-## 公共参数
-
-所有主指标接口都是 `POST /api_v2/as_bot/chat-report/{metric}`，请求 Body JSON 参数为：
-
-- `startDate`、`endDate`：必填，`YYYY-MM-DD`。
-- `botId`：可选，Bot ID。
-- `touchPoint`（或 CLI `--channel`）：可选，渠道名。
-- `intentId`：可选，意图 ID。
-- `agentId`：可选，Agent ID。
-
-## 指标命令与字段对照
-
-| CLI 命令 | 接口路径 | 对应前台板块 | 主要返回字段 |
-|---|---|---|---|
-| `chat-report-tickets` | `/tickets` | 服务能力（解决率/转人工率） | `totalTicketCount`、`aiIncomingTicketCount`、`handoffTicketCount`、`aiIncomingHandoffTicketCount`、`aiIncomingResolvedTicketCount` 等 |
-| `chat-report-messages` | `/messages` | 服务能力（AI 回复率） | `totalMessageCount`、`aiIncomingMessageCount`、`aiReplyMessageCount`、`aiIncomingReplyMessageCount` |
-| `chat-report-satisfaction` | `/satisfaction` | 服务质量（CSAT 满意度与点赞点踩） | `totalTicketCount`、`satisfactionTicketCount`、`satisfactionRecoveryRate`、`sessionAiSatisfiedCount`、`sessionAiUnsatisfiedCount`、`sessionHumanSatisfiedCount`、`sessionHumanUnsatisfiedCount`、`messageAiSatisfiedCount` (AI 点赞数)、`messageAiUnsatisfiedCount` (AI 点踩数)、`messageHumanSatisfiedCount`、`messageHumanUnsatisfiedCount`、`sessionAiSatisfactionRate`、`messageAiSatisfactionRate`、`overallSatisfactionRate` |
-| `chat-report-first-response` | `/first-response` | 服务质量（首次响应时效） | `aiFirstResponseTicketCount`、`humanFirstResponseTicketCount`、`aiFirstResponseDurationTotal`、`humanFirstResponseDurationTotal`、`aiAverageFirstResponseDuration`、`humanAverageFirstResponseDuration`、`overallAverageFirstResponseDuration` |
-| `chat-report-return-retention` | `/return-retention` | 服务收益（RMA 挽回率） | `totalTicketCount`、`retentionTriggeredTicketCount`、`retentionSuccessTicketCount` |
-| `chat-report-inspection-results` | `/inspection-results` | 风险与质检 | `inspectionResultCount` (平台规则与风险预警数) |
-| `chat-report-intents` | `/intents` | 深度分析（意图工单分布与趋势） | 意图列表及各意图的工单数、进线解决数、转人工数等 |
-| `chat-report-agents` | `/agents` | 深度分析（智能体工单分布与趋势） | 智能体列表及各智能体的工单数、进线解决数、转人工数等 |
-| `chat-report-inbox-scripts` | `/inbox-scripts` | 会话下钻筛选脚本 | 获取按各指标下钻收件箱会话时的 ES 查询脚本 |
-
-### 核心公式
-
-- **AI 进线回复率**：`aiIncomingReplyMessageCount / aiIncomingMessageCount * 100%`
-- **AI 进线解决率**：`aiIncomingResolvedTicketCount / aiIncomingTicketCount * 100%`
-- **AI 转人工率**：`aiIncomingHandoffTicketCount / aiIncomingTicketCount * 100%`
-- **AI 满意度 (CSAT)**：`messageAiSatisfiedCount / (messageAiSatisfiedCount + messageAiUnsatisfiedCount) * 100%`
-- **人工满意度 (CSAT)**：`messageHumanSatisfiedCount / (messageHumanSatisfiedCount + messageHumanUnsatisfiedCount) * 100%`
-- **AI RMA 挽回率**：`retentionSuccessTicketCount / retentionTriggeredTicketCount * 100%`

package/skills/agent-analytics/references/report-fields.md

@@ -1,130 +0,0 @@
-# `/report` 统计接口与字段契约
-
-本文描述 `/report` 页面使用的统计接口与字段。前端主要通过 `/api_v2/as_bot/statement/*` 请求 analysis-service 的统计数据。
-
-## 页面能力与命令
-
-| `/report` 场景 | 前端接口 | CLI 命令 |
-|---|---|---|
-| 工单量、解决、转人工 | `POST /api_v2/as_bot/statement/transcript` | `report-transcript` |
-| 消息量、AI 消息回复 | `POST /api_v2/as_bot/statement/message` | `report-message` |
-| Agent 绩效 | `POST /api_v2/as_bot/statement/agent` | `report-agent` |
-| 意图分布与下钻 | `POST /api_v2/as_bot/statement/transcript/intent` | `report-intent` |
-| 满意度汇总 | `POST /api_v2/as_bot/statement/satisfaction/feedback` | `report-satisfaction` |
-| 满意度明细 | `POST /api_v2/as_bot/statement/satisfaction/message` | `report-satisfaction-list` |
-| 评分分布 | `POST /api_v2/as_bot/statement/feedback` | `report-feedback` |
-| 知识使用 | `POST /api_v2/as_bot/statement/knowledge` | `report-knowledge` |
-| 转人工原因 | `POST /api_v2/as_bot/statement/transcript/reason2` | `report-escalation` |
-| 三级原因下钻 | `POST /api_v2/as_bot/statement/transcript/reason/three/level` | `report-escalation-drilldown` |
-| Agent 周趋势图 | `POST /api_v2/as_bot/statement/graph/agent` | `report-agent-weekly-graph` |
-| 自学习 | `POST /api_v2/as_bot/statement/self-learning` | `report-self-learning` |
-| LiveChat 漏斗 | `POST /api_v2/as_bot/livechat/report/summary` | `report-livechat` |
-| LiveChat 明细 | `POST /api_v2/as_bot/livechat/report/table` | `report-livechat-table` |
-| AI 质检概览 | 质检 count 接口 | `report-inspection` |
-| AI 质检趋势 | 质检 history 接口 | `report-inspection-history` |
-
-## 请求参数
-
-Report 通用请求与 analysis-service `FilterRequest` 对齐：
-
-| 字段 | 规则 |
-|---|---|
-| `beginTimestamp` | 必填，目标时区开始日期的 `00:00:00.000`，毫秒 |
-| `endTimestamp` | 必填，目标时区结束日期的 `23:59:59.999`，毫秒 |
-| `projectId` | CLI 根据当前项目自动发送 |
-| `timeOffset` | 前端浏览器 UTC 小时偏移；例如北京时间为 `8` |
-| `botId` | 可选；未选择 Bot 时不发送 |
-| `touchPoint` | 可选；前端未选择渠道时不发送，表示全部渠道 |
-| `agentId` | Agent 明细或 Agent 下钻时发送 |
-| `firstIntentId` | 意图下钻时发送；CLI 使用 `--intent-id` |
-| `dateUnit` | 按接口需要发送 `DAY`、`WEEK` 或 `TOTAL` |
-
-缺少时间范围时必须询问用户。时区默认使用中国时区（`Asia/Shanghai`，`UTC+8`），请求固定发送 `timeOffset=8`；仅当用户明确指定其他时区时，才按用户时区计算日期边界并覆盖 `timeOffset`。
-
-### 与前端日期选择器对齐
-
-- `/report` 公共日期选择器不允许选择今天之后的数据，页面最大日期为昨天。
-- 两个日期相差不能超过 30 天。用户要求更长范围时，按前端可选择的窗口拆段请求。
-- 拆段后计数求和；比例按合并后的分子和分母重新计算，禁止平均分段百分比。
-- Report 和后续 Agent 会话记录下钻必须复用完全相同的毫秒边界、时区与适用过滤条件。
-
-## 时间粒度
-
-- `DAY`：日趋势。`timestampStr` 通常是 `年-年内第几天`，例如 `2026-92`，要转换为实际日期后展示。
-- `WEEK`：周趋势。`timestampStr` 通常是 `年-第几周`，不要当成自然日期。
-- `TOTAL`：整个请求时间段的汇总，用于总览和分段汇总。
-- analysis-service 的 `DateUnit` 还包含 `MONTH`，但 `/report` 前端当前不把它作为页面能力使用。需要自然月数据时，按月分别请求 `TOTAL` 最稳妥。
-
-## 核心指标结构
-
-### Agent 会话记录与消息
-
-`report-transcript` 和 `report-message` 都可能返回以下 bucket key，但两者数据层级不同：前者是工单级，后者是消息回复分析。不要混用两个接口的总量。
-
-| key | 页面含义 | 使用规则 |
-|---|---|---|
-| `total` | 当前口径总量 | rate 类指标的分母 |
-| `resolution` | 已解决或 AI 有效回复数量 | 以响应中的 `script` 为权威筛选口径 |
-| `resolution_rate` | 解决率或页面展示的 AI 消息回复率 | 已是百分比值，不要再次乘 100 |
-| `ai_answer` | AI 参与应答数量 | 与 `resolution` 不是同义字段 |
-| `ai_answer_rate` | AI 应答占比 | 已是百分比值 |
-| `escalation` | 转人工/升级数量 | 以响应中的 `script` 为权威 |
-| `escalation_rate` | 转人工率 | 已是百分比值 |
-
-`/report` 的“AI 消息回复率”页面读取 `report-message` 的 `resolution_rate`。分析时同时保留 `resolution` 和 `total`，跨时间段合并后重新计算。
-
-### Agent
-
-`report-agent` 的 `TOTAL[0].buckets[]` 通常按 Agent 分组：
-
-- `key`：Agent ID。
-- `name`：Agent 名称。
-- `valueMap.total`：该 Agent 总量。
-- `valueMap.ai_answer` / `ai_answer_rate`：AI 应答数量与比例。
-- `valueMap.resolution` / `resolution_rate`：解决数量与比例。
-- `valueMap.escalation` / `escalation_rate`：转人工数量与比例。
-- `scriptMap`：下钻收件箱 Agent 会话记录时使用的查询脚本。
-
-汇总多个 Agent 时先分别求和 `total`、`ai_answer`、`resolution`、`escalation`，再计算比例。
-
-### Intent
-
-`report-intent` 的 `TOTAL[0].buckets[]` 按意图分组，常见字段为 `key`、`name`、`valueMap`、`scriptMap`。意图趋势和详情页还会联合 `report-message` 获取消息级指标；不要把意图工单数当成消息数。
-
-### 满意度
-
-- `report-satisfaction` 返回 AI 与人工满意度汇总。
-- `report-satisfaction-list` 是分页明细，列表 key 为 `satisfactions`，不是 `records`。
-- `report-feedback` 返回评分分布，并按 `handoff` / `no_handoff` 区分人工与 AI。
-
-### 知识、自学习与 LiveChat
-
-- `report-knowledge` 是分页接口，返回知识使用、转人工数/率等字段；翻页时保留相同时间与过滤条件。
-- `report-self-learning` 返回自学习主题统计与趋势。
-- `report-livechat` / `report-livechat-table` 是 LiveChat 售前漏斗，不应代替通用 Agent 会话记录/消息指标。
-- AI 质检使用 `YYYY-MM-DD` 参数，不使用 Report 毫秒参数；时间范围仍需与用户确认的一致。
-
-## 失败与异常数据
-
-- 每个接口单独执行，不要用 `&&` 串联整批请求。
-- `report-escalation` 对应的 `reason2` 曾出现 `errno=-1`，根因可能是 analysis-service 在空聚合转换时异常。此时只能标记“转人工原因指标不可用”，不能自行补原因分布。
-- `statement/transcript` 在错误账号权限下可能静默返回零值。零值与其他接口、收件箱 Agent 会话记录明细明显冲突时，优先检查权限，不要直接判断业务为零。
-- 返回缺少目标 bucket、分页未完成或接口失败时，必须在最终结论中披露。
-- 抽样会话只能帮助解释已有指标，不能代替缺失的整体指标。
-
-## 示例
-
-```bash
-npx --yes @shulex/cxclawctl@latest api report-message \
-  --begin-ts "$BEGIN_MS" \
-  --end-ts "$END_MS" \
-  --time-offset 8 \
-  --date-unit DAY \
-  --pretty
-```
-
-指定渠道时才追加：
-
-```bash
---touch-point LIVE_CHAT
-```

package/skills/agent-analytics/references/transcript.md

@@ -1,110 +0,0 @@
-# Agent 会话记录与收件箱明细
-
-`get-transcript` 获取单条 Agent 会话记录详情。后端对象名为 `Transcript`，业务说明统一称“Agent 会话记录”。
-
-在 `agent-analytics` 中，数据分析页面中的工单指 Agent 会话记录，也是收件箱数据。
-
-统计指标先读取 `report-fields.md` 并调用 Report；只有需要核对明细、寻找样本或查看完整对话时才使用本文命令。
-
-## 命令与接口
-
-| CLI 命令 | 接口 | 用途 |
-|---|---|---|
-| `list-transcripts` | `POST /api_v2/gpt/project/{projectId}/transcripts/filter` | 收件箱 Agent 会话记录摘要列表 |
-| `get-transcript` | `GET /api_v2/gpt/project/{projectId}/transcript/{chatId}?isCompare=true` | 单条完整会话 |
-| `export-transcripts` | `POST /api_v2/gpt/project/{projectId}/transcripts/export/async` | 提交异步导出 |
-| `get-export-tasks` | `POST /api_v2/gpt/label/project/{projectId}/getLabelTask` | 查询导出状态 |
-
-## 与 Report 对齐的过滤条件
-
-`list-transcripts` 支持：
-
-- `--begin-ts` / `--end-ts`
-- `--touch-point`
-- `--bot-id`
-- `--agent-id`
-- `--intent-id`
-- `--handoff true|false`
-- `--debug`
-- `--page` / `--page-size`
-
-下钻时必须复用 Report 的时间范围、时区对应的毫秒边界，以及适用的 Bot、渠道、Agent、意图条件。前端未选择渠道时不要追加 `--touch-point`，表示全部渠道。
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-transcripts \
-  --begin-ts "$BEGIN_MS" \
-  --end-ts "$END_MS" \
-  --page 1 \
-  --page-size 50 \
-  --pretty
-```
-
-筛选 LiveChat 已转人工 Agent 会话记录：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-transcripts \
-  --begin-ts "$BEGIN_MS" \
-  --end-ts "$END_MS" \
-  --touch-point LIVE_CHAT \
-  --handoff true \
-  --page 1 \
-  --page-size 50 \
-  --pretty
-```
-
-## 分页完整性
-
-收件箱接口返回：
-
-- `pageIndex`
-- `pageSize`
-- `hasNext`
-- `list`
-
-`totalCount` 已废弃，通常不能作为可靠总量。**当前页长度不是总量**，CLI 也不会再用当前页长度伪造 `total`。
-
-完整拉取流程：
-
-1. 从 `--page 1` 开始。
-2. 记录当前页 `list` 数量并保存 `chatId` 去重。
-3. 当 `hasNext=true` 时将页码加一，保持其他参数完全不变。
-4. 直到 `hasNext=false` 才算分页完成。
-5. 最终说明实际获取数量；接口总量不可用时明确写“总量不可用”。
-
-未读取到 `hasNext=false` 时，禁止将已获取数据描述为全部 Agent 会话记录。
-
-## 单条完整对话
-
-`list-transcripts` 只返回摘要。需要查看消息内容、AgentAction、转人工上下文或具体异常时，再调用：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-transcript \
-  --chat-id <chatId> \
-  --pretty
-```
-
-不要对列表中的所有 Agent 会话记录无差别获取完整详情。优先根据 Report 指标、时间点、Agent、意图或转人工条件选择有解释价值的样本。
-
-## 抽样结论边界
-
-- 抽样用于解释具体异常、寻找共同模式或展示典型对话。
-- 样本数量、筛选方式和是否随机必须在结论中说明。
-- 样本不能替代 Report 的总体计数和比例。
-- Report 指标不可用时，只能输出“样本中观察到”，不能升级成整体原因或总体占比。
-- AI 回复与原 badcase、历史表现或预期明显不同时，要指出变化发生在哪一轮、哪个 AgentAction 或哪个业务节点。
-
-## 异步导出
-
-只有确实需要大量明细文件时才使用：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api export-transcripts \
-  --begin-ts "$BEGIN_MS" \
-  --end-ts "$END_MS" \
-  --time-offset 8 \
-  --pretty
-
-npx --yes @shulex/cxclawctl@latest api get-export-tasks --pretty
-```
-
-轮询到任务 `status=SUCCESS` 后再使用返回的文件地址。

package/skills/agent-builder/SKILL.md

@@ -1,42 +0,0 @@
----
-name: agent-builder
-description: 构建和维护 Shulex Agent 本体及工具配置。用户要创建、复制、修改 Agent，处理流程图、多节点、条件分支、工具调用、人工节点、SINGLE_AGENT、语音 Agent、MULTI_AGENT legacy、CHAT_FLOW，或创建/调试/绑定外部 HTTP 工具时使用。意图、策略、entity condition 路由不走本 skill。
-requires:
-  libs: [solvea-api]
----
-
-# Agent Builder
-
-## 任务分流
-
-用户没有明确指定 Agent 形态时，默认按 CHAT_FLOW 需求处理。只有用户明确指定 SINGLE_AGENT、语音 Agent，或明确要查看、维护、解释、迁移已有 MULTI_AGENT 时，才进入对应分支。MULTI_AGENT 是 legacy 形态，不支持新建；用户要求新建 multi 时，明确说明不支持新建并推荐改用 CHAT_FLOW。
-用户表达“迁移 / 转新版 / 转 CHAT_FLOW / 从旧 agent 转过来”时，第一站只读 `references/multi-agent/overview.md`；由 multi 文档继续决定读取 `workflow.md`、`graph-spec.md`、`migration/principles.md` 和 small / large 迁移文档。目标图的整体流程和节点类别确认后，才回到 `references/chatflow/graph-spec.md` 和对应 `nodes/*.md` 实现 source。
-
-迁移的旧图解析、分批、coverage、确认门和迁移报告只按 `references/multi-agent/` 执行；不要把这些
-legacy 流程或中间字段写进通用 CHAT_FLOW 文档或 source schema。完成并确认 migration plan 后，才切换到
-CHAT_FLOW 文档实现节点、compile、validate 和 replay；旧图合同未解析前不得 update、deploy 或 publish。
-
-处理大型 JSON、迁移索引、工具定义批量核对时，优先用 `execute` 一次性运行 `jq` 做筛选、字段投影、
-计数和结构摘要，只输出紧凑结果，不要把完整 JSON 回传模型；必要时结合 `rg` / `sed`。复杂跨文件
-关联、复杂转换或生成逻辑再用短 Python 脚本。不要用多轮 `grep` / `read_file` 逐字段搜索同一批文件。
-简单查看单个文档仍用 `read_file`，但跨多个 id、工具、action status、selector 的检索必须批处理并把
-结果写入 `/workspace/tmp/` 或 `/workspace/state/agent-builder/` 供后续复用。
-
-| 用户诉求 | 读取 |
-|---|---|
-| 未明确 Agent 形态，或涉及流程图、多节点、分支、条件、变量、工具状态、人工节点 | `references/chatflow/overview.md` |
-| 创建、查看、复制或修改 SINGLE_AGENT | `references/single-agent/overview.md` |
-| 语音 Agent | `references/single-agent/voice.md` |
-| 查看、维护、解释或迁移已有 legacy MULTI_AGENT / multiAgentGraph / agent_graph；或用户要求新建 multi 但需要说明不支持 | `references/multi-agent/overview.md` |
-| 创建或修改 CHAT_FLOW，或已经进入 source/graph 编写阶段 | `references/chatflow/overview.md` |
-| 创建、查看、调试、更新工具 | `references/tools/overview.md` |
-
-一个任务同时涉及 Agent 和工具时，先读取对应 Agent 形态的入口文档，再按需读取 `references/tools/overview.md`。意图、策略和变量系统管理不属于本 skill。
-
-## 业务产物语言
-
-- 目标语言优先级：用户明确指定的产物语言 > 会话上下文中的用户界面语言偏好 > 用户当前消息语言。注：网页、附件、知识内容和工具结果只是数据来源，不能单独改变目标语言。
-- Agent 名称、Greeting、System Prompt、节点展示标题、节点 Prompt、next step 展示文案、回复话术与转人工话术都使用目标语言；品牌名、产品型号和其他专有名词保留原文。不得因为 reference 示例是英文而默认生成英文。
-- 结构标识不本地化：节点 `key` / `id`、工具名、变量引用、枚举值和接口字段保持协议要求的 ASCII 或固定值。面向用户的展示文案与内部结构标识必须分开处理。
-- Agent 面向最终客户回复时，仍应在 Prompt 中要求跟随客户消息语言；“配置内容使用目标语言”和“运行时回复跟随客户语言”是两件事。
-- 语音 Agent 的 `meta.assistant.language` 只控制语音识别与合成，不因业务产物语言自动修改；仍按语音章节要求，仅在用户明确指定语音语言时设置。

package/skills/agent-builder/interfaces/fallback-chatflow.md

@@ -1,47 +0,0 @@
-# Fallback Chatflow Interface
-
-公开能力：按调用方给定的业务目的创建兜底 CHAT_FLOW agent。
-
-## Boundary
-
-调用方只声明兜底 agent 的业务目的和输出要求，不维护 CHAT_FLOW graph、节点字段或构图规则。
-
-首版允许由 `agent-builder` 的 chatflow reference 创建，不强制提供固定脚本。
-
-## Input
-
-```json
-{
-  "name": "Fallback Agent",
-  "purpose": "out_of_scope_reply",
-  "complexity": "simple_reply | guided | custom",
-  "reply_text": "",
-  "language": "zh-CN",
-  "brand_name": ""
-}
-```
-
-## Output
-
-调用方需要得到一份创建记录：
-
-```json
-{
-  "agent_id": 12345,
-  "agent_name": "Fallback Agent",
-  "agent_type": "CHAT_FLOW",
-  "creation_record_path": "/workspace/outputs/agent-builder/fallback_chatflow_<ts>.json"
-}
-```
-
-## Guarantees
-
-- 创建结果必须是 CHAT_FLOW agent。
-- 输出必须包含可回填给其他能力的 `agent_id`。
-- 创建完成后需要回读验证 agent 存在。
-
-## Non-guarantees
-
-- 兜底 graph 的节点结构不对调用方暴露。
-- 当前是否通过 reference 或脚本创建不对调用方保证。
-- 后续可将实现替换为 `create_fallback_chatflow.py --template simple_reply|guided`，调用方 interface 不变。