@shulex/cxclawctl 0.1.2 → 0.1.3

package/skills/agent-builder/references/multi-agent/migration/small.md

@@ -1,225 +0,0 @@
-# 迁移模式：small legacy MULTI_AGENT -> CHAT_FLOW
-
-输入是旧版 `multiAgentGraph`（扁平 `agents[]` + `agentEdges[]`）时使用本文件。目标不是复述旧
-prompt，也不是按 old agent 数量建同样数量的节点，而是还原并保留入口、客户意图、工具、动作分支、
-模板回复、人工接管、结束和内部流转等**可执行业务语义**。
-
-开始前先读 `../graph-spec.md` 和 `principles.md`。本文件只负责短图的旧图取证、coverage、语义映射
-和用户确认；它不定义目标节点字段、默认边或构图/校验命令。
-
-短图不强制跑 analyzer，但必须产出等价的 topology 摘要：唯一入口、可达节点、显式 edge、
-`SWITCH_AGENT` 控制边、动作分支和终端。如果已有 analyzer 产物，优先使用其中的 `topology` /
-`flow_understanding.seed.json` / `migration_contracts`；图小不是跳过 classifier 闭集、模板资源、用户
-交互和动作顺序对账的理由。
-
-## 触发和分流
-
-符合任一条件即进入迁移模式：
-
-- 文本包含 `multiAgentGraph` / `agentEdges` / `classifierPlugin`；
-- 用户给当前环境旧版 agent_id 并要求迁移 / 转新版 / 一键迁移；
-- 顶层 JSON 形如 `[{"category":"TEXT","meta":{"multiAgentGraph":...}}]`。
-
-否则走 `/skills/agent-builder/references/chatflow/workflow.md`；图片或流程图输入先读
-`/skills/agent-builder/references/chatflow/visual-translation.md`。
-
-符合任一条件时，停止本文件的短图流程并改读 `large.md`：
-
-- `displayPrompt` 远大于 `prompt`，或含大量 HTML 展示内容；
-- 顶层含大量前端画布、审计或非执行字段，需要裁剪；
-- `usedPlugins[].meta.toolAfterExecuteActions` 或工具 `actionStatuses` 是主要流程来源；
-- agent/action/tool 数量较多，需要先生成 Mermaid、chunk 和 batch；
-- prompt 与 action 中的模板、目标 agent 或知识配置存在冲突。
-
-长图先执行：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/multi-agent/legacy_graph_analyzer.py inspect \
-  --input /workspace/state/agent-builder/multi-agent/read_<old_agent_id>_raw.json \
-  --out-dir /workspace/state/agent-builder/multi-agent
-```
-
-## 迁移阶段的产物
-
-| 文件 | 用途 |
-|------|------|
-| `/workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/` | analyzer 索引、topology、coverage 和迁移计划 |
-| `/workspace/state/agent-builder/multi-agent/mapping_rules.json` | 用户确认过、可跨任务复用的模糊映射规则 |
-| `/workspace/outputs/agent-builder/` | 仅在用户明确要求下载/留档时使用 |
-
-目标 source、graph、编译、校验和部署均由 `../../chatflow/workflow.md` 管理；不要在本文件中创建临时
-Python 构图脚本或复制目标图命令。
-
-## Step 1：解析旧图并还原拓扑
-
-短小图可以由模型直接解析；长图必须由脚本解析。无论方式，都必须记录：
-
-- `agents[]` 的 id、名称、prompt、`displayPrompt`、`usedPlugins` 和结构化 meta；
-- `agentEdges[]` 的显式流转；
-- classifier 与工具的 `toolAfterExecuteActions`、`actionStatuses`；
-- 模板、人工接管、结束和知识能力配置；
-- 每个非空 PE 的完整原文和 SHA-256。模型必须结合结构化资源、动作边、上下游职责阅读全文，语义识别其中的
-  模板、转人工、普通工具、固定完整话术、等待点和流程控制；不得按 `template id`、`reason`、
-  `use/call tool`、三引号等固定写法或语言专用正则分类。短图也要按 `principles.md` 生成等价的
-  `prompt_reviews[].discovered_blocks`，不能只保留 prompt 摘要；
-- 可达性、入口和缺失目标的 action。
-
-`agentEdges[]` 只记录“上游模型可以选择调用的相邻职责”，不是确定性流程边。旧图 Mermaid 中应以虚线
-标识这类关系；SOP 映射时由模型根据职责和用户轮次决定保留为模型可选路由、吸收进同一职责，或在独立
-`SWITCH_AGENT` 证据/用户确认后形成确定性流程。不要把它直接抄成目标图的一条连线。
-
-`displayPrompt` 中的 `{{ToolName}}` 必须提取为 `tool_references` 并与 `usedPlugins` / 系统能力 /
-action 对账。仅 display-only 的未绑定 chip、HTML 壳和“use this tool”之类泛化措辞都保留 audit warning；
-只有 prompt 中明确可执行的调用缺少结构化依赖时才进入 `open_questions`。
-
-向用户先展示以下内容，不要一上来写目标图：
-
-```text
-## 旧 Multi 流程理解
-| 阶段 | 输入/用户轮次 | 旧证据 | 分支/出口 | 风险 |
-
-## SOP 拆解
-| SOP 步骤 | 触发条件 | 处理动作 | 用户可见回复/等待 | 下游 |
-```
-
-同时贴一段简版 Mermaid，展示入口、主干、动作分支和终端。存在不可达节点、多个入口或 action 缺少目标时，
-先作为 blocking 问题处理，不能靠补猜测的边继续。先让用户确认 SOP；coverage 留在 plan 中审计，只有
-存在缺口或用户要求明细时才展示表格。
-
-## Step 2：做语义映射和 coverage
-
-按拓扑顺序映射，但先归一化业务职责，不按 `agents[]` 数量建节点。每个映射要同时考虑 old agent、
-结构化 action 和 prompt，避免先丢语义再补。
-
-迁移计划只写业务职责和目标节点类别候选；以下是常见候选，不是字段或出边规则：
-
-| Legacy 语义 | 候选类别 |
-|---|---|
-| 自然语言分类 | `INTENT` |
-| 已绑定的外部 HTTP 调用 | `TOOL` |
-| 工具结果后的确定性判断 | `IF_ELSE` |
-| 收集客户信息 | `QUESTION` |
-| 向客户发送模板或话术 | `REPLY` |
-| 内部总结、改写、抽取或中间文本生成 | `LLM` |
-| 开放式判断、真实工具自主选择或流程内选择 | `AGENT` |
-| 人工接管 | `TRANSFER_TO_HUMAN` |
-| 正常结束 | `FINISH` |
-| 变量抽取、归一化或上下文传递 | `VARIABLE_PROCESS` |
-| 已启用且目录完整的旧知识能力 | 知识回复候选，具体类别在目标图阶段决定 |
-
-`SWITCH_AGENT` 是旧控制流证据，不是外部工具。仅承担跳转的 old agent 标记为 `edge_only`；独立 SOP、
-用户交互、资源调用或分支职责才需要保留为候选节点。每个 old agent、真实 tool、explicit edge 和
-action edge 都必须在 coverage 中标记为 `preserved`、`merged`、`split`、`rewritten`、`edge_only` 或
-`open_question`，并给出证据。
-
-explicit edge 的 `mapped_to` 可以写对应职责块或模型可选路由能力；不得默认写成固定的目标节点连线。
-
-知识能力只按旧语义判断：直接 `directoryIds` 或
-`meta.knowledgeAiReplyConfig.directoryIds` 都是目录证据；后者的 `enable` 优先。明确 `enable=false`
-且目录为空只保留 audit。已启用或启用状态未知且目录为空，才是 blocking 问题：要求用户提供目录或
-明确移除该能力。不要把仅 display 的知识占位符当成缺失依赖。
-
-模板、人工接管和结束动作需要分别记录资源、先后顺序和用户可见语义。不同模板 id、不同人工接管原因、
-不同前置话术或不同结束语义默认不能合并；是否采用等价回复策略必须经用户确认。
-
-每个完整 PE 都要进入 `coverage.prompt_reviews`，回写全文 hash 和 `reviewed_full_prompt=true`；语义识别出的
-每个块按源顺序进入 `discovered_blocks`，带精确 source span/quote。SOP → 节点类别确认后，再为每个块选择
-`target_type`：上下文决定且需留在多轮 AGENT 内的模板/工具/转人工用 `AGENT_LIBRARY_BLOCK`；确定性动作
-分别选择 `REPLY_TEMPLATE` / `TOOL_NODE` / `TRANSFER_NODE`；等待点选择合同允许的多轮或交互节点承载方式。
-固定话术先使用通用 `NODE_PROMPT_FIELD`，不把它写死为 REPLY；进入 CHAT_FLOW source 实现并读完所选节点
-合同后，再用 `render_path` 指向该节点的真实 PE/文本字段。LibraryBlock、plugin 绑定和内容 hash 由与 large
-模式相同的合并/渲染规则根据结构化语义派生，不让模型或人工逐 case 拼字符串。未映射完不得转入 CHAT_FLOW
-source 阶段。
-
-## Step 3：生成 SOP → 节点映射 Mermaid 并确认
-
-保留旧 prompt 中的业务目标、判断标准、客服话术边界和工具结果解释；剥离旧引擎专用的工具指令、
-编辑器占位符和 HTML 壳。清理不能抹掉结构化动作：每一项要么落入 mapping plan 的业务职责，
-要么有 audit 或 open question 记录。
-
-在用户确认 SOP 后，按流程块（不是按 old agent）写 `sop_mapping`。草稿先写候选类别；节点映射得到
-用户确认后，将每个块的确认类别写入 `selected_nodes`：
-
-```json
-{
-  "sop_mapping": {
-    "blocks": [
-      {
-        "id": "collect_order",
-        "responsibility": "Collect the order information",
-        "candidate_nodes": ["QUESTION"],
-        "selected_nodes": ["QUESTION"]
-      },
-      {
-        "id": "lookup_order",
-        "responsibility": "Look up the order and route by result",
-        "candidate_nodes": ["TOOL", "IF_ELSE"],
-        "selected_nodes": ["TOOL", "IF_ELSE"]
-      }
-    ],
-    "relations": [
-      {"from": "collect_order", "to": "lookup_order", "condition": "order information complete"}
-    ]
-  }
-}
-```
-
-生成 Mermaid 并直接贴给用户确认：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/multi-agent/legacy_graph_analyzer.py emit-mapping-mermaid \
-  --plan-file /workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/migration_plan.json \
-  --out-file /workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/sop_mapping.mmd
-```
-
-图中每个流程块必须显示其职责和候选/确认节点类别，边必须显示条件。它取代节点映射表作为用户确认界面；
-coverage 仍在 plan 中，不逐项占用对话。映射未确认时不得写 source。
-
-只对会改变可执行语义的缺口提问：缺失真实工具/模板、启用或未知启用的空知识目录、不可达或断开的
-结构边、无法恢复的关键动作合同。每个问题给出 2–3 个可执行选项、推荐项、影响和是否阻塞；不要把
-audit warning 逐条抛给用户。
-
-## Step 4：交给目标图阶段实现
-
-coverage 完整、SOP → 节点映射 Mermaid 和必要的用户决定确认后，停止使用本文件推断实现细节，依次读取：
-
-1. `../../chatflow/overview.md`
-2. `../../chatflow/workflow.md`
-3. `../../chatflow/graph-spec.md`
-4. `../../chatflow/node-selection.md`
-5. 每个已选类别对应的 `../../chatflow/nodes/*.md`
-
-目标图阶段才决定 source 字段、资源绑定、边、编译、校验和部署。迁移计划是该阶段的语义输入；目标图
-实现或校验发现缺少业务信息时，回到本文件补 evidence / coverage / 用户确认，而不是在目标图中猜测。
-source 完成后、compile 前先运行 `legacy_graph_analyzer.py audit-migration-source --plan-file ...
---index-file ... --source-file ... --out-file ... --pretty`，再运行
-`validate-prompt-block-rendering --plan-file ... --index-file ... --source-file ... --pretty`。前者会阻断损坏
-source 结构、真实不存在的边端点，以及显式 `rendered_to` / `source_nodes` 指向不存在节点；节点类别、
-AGENT/next step 选择和只有 `mapped_to` 的 coverage 去向疑点只给 warning；后者检查可执行 prompt block
-是否真实渲染。若 source key 与流程块 id 不同，先在 coverage 项填写 `rendered_to`。
-同一轮完成 source → compile 不要求 handoff。只有任务需要跨轮恢复、多 worker / agent 交接，或 source
-可能被人工编辑时，才建议运行 `emit-handoff --plan-file ... --index-file ... --source-file ... --out-file ...
---pretty`，并由接手方在 compile 前显式运行 `verify-handoff`。handoff 只记录现有 validation 和 warning，
-不新增阻断；文件未变化即验证通过，发生变化才返回 `STALE_MIGRATION_PLAN`。该合同只属于迁移侧，不改
-通用 Chatflow compile。
-
-## 迁移摘要和自检
-
-向用户报告：
-
-- 旧图入口、主干、分支、用户轮次、人工接管和终端的理解；
-- 已确认的 SOP → 节点映射 Mermaid；
-- 每个 old agent、tool、explicit edge、action edge 的 coverage；
-- 合并、拆分、改写和经用户确认的删减及其影响；
-- 真正阻塞项、已解决项和仍需确认项；
-- 进入目标图阶段后的实现、校验和回放状态（若已执行）。
-
-完成迁移计划前逐项检查：
-
-- 所有结构化工具、动作、模板、知识能力和终端都有证据与 coverage；
-- `displayPrompt` 的噪音没有被误判成可执行依赖；
-- 每个合并都有相同输入、用户轮次、资源、分支和下游语义的证据；
-- 每个 SOP 流程块都在 Mermaid 中显示了确认的节点类别和条件关系；
-- 每个 `open_question` 都是必要且可执行的；
-- 已选节点类别只是候选，尚未在本文件填写目标字段或默认边；
-- 进入目标图阶段前已读取相应的 CHAT_FLOW 文档。

package/skills/agent-builder/references/multi-agent/orchestration.md

@@ -1,11 +0,0 @@
-# Deprecated: orchestration
-
-本文件只保留历史引用兼容，不再承载编排理解或迁移规则。
-
-旧 MULTI_AGENT 的编排语义、证据优先级和迁移保真规则统一读取：
-
-1. `overview.md`
-2. `workflow.md`
-3. `graph-spec.md`
-4. `migration/principles.md`
-5. `migration/small.md` 或 `migration/large.md`

package/skills/agent-builder/references/multi-agent/overview.md

@@ -1,48 +0,0 @@
-# MULTI_AGENT
-
-legacy MULTI_AGENT 只作为存量形态维护。用户没有明确指定旧 multi 形态时，多节点、多分支、工具状态分支或人工节点默认用 CHAT_FLOW。
-
-## 先判定模式
-
-| 输入特征 | 模式 | 先读 |
-|---------|------|------|
-| 用户要求新建 MULTI_AGENT / multi agent / multiAgentGraph | 不支持新建 | `workflow.md` 的“不支持新建” |
-| 用户提供已有 MULTI_AGENT agent_id / 完整旧 JSON，要求查看、解释或审计 | 读取解释 | `workflow.md`、`graph-spec.md` |
-| 用户明确要求更新已有 MULTI_AGENT | 存量更新 | `workflow.md`、`update.md` |
-| 用户要求迁移 / 转新版 / 转 CHAT_FLOW，或输入含 `multiAgentGraph` / `agentEdges` / `classifierPlugin` | 迁移 | `workflow.md`、`graph-spec.md`、`migration/principles.md`，再按大小读 `migration/small.md` 或 `migration/large.md` |
-
-用户只要表达“迁移 / 转新版 / 转 CHAT_FLOW / 从旧 agent 转过来”，本文件就是第一入口。不要先去
-`../chatflow/overview.md` 做节点选择；先按本文件和 `workflow.md` 完成旧结构理解、大小判定和迁移计划。
-目标 CHAT_FLOW source 明确后，才回到 `../chatflow/graph-spec.md`、`../chatflow/node-selection.md` 和对应
-`../chatflow/nodes/*.md` 校验目标节点字段。
-
-## 固定原则
-
-- 不新建 MULTI_AGENT；新建多节点流程推荐 `../chatflow/overview.md`。
-- 已有 MULTI_AGENT 可读取、解释、必要兼容更新、迁移。
-- 旧图证据读取优先级：结构化 action/tool/plugin > `agentEdges` > `prompt` > `displayPrompt`。
-- `displayPrompt` 默认是前端展示噪音和人工审计来源，不作为迁移后的模型输入。
-- 迁移允许 PE 改写、节点合并和拆分；节点数可增可减，但必须由可执行合同决定，并输出 coverage 和 changed_items。
-
-## 文档职责
-
-| 文件 | 职责 |
-|------|------|
-| `overview.md` | 入口分流和边界 |
-| `workflow.md` | 查看、解释、更新、迁移的操作步骤 |
-| `graph-spec.md` | legacy JSON 字段、前端噪音清洗、证据优先级 |
-| `update.md` | 仅更新已有 MULTI_AGENT 的完整对象更新规则 |
-| `migration/principles.md` | 迁移保真、coverage、合并、PE 改写规则 |
-| `migration/small.md` | 短小 legacy 图直接迁移流程 |
-| `migration/large.md` | 长图 analyzer + 并发 batch；只确认合并问题和最终全局图 |
-| `graph-structure.md` / `orchestration.md` / `migrate-to-chatflow.md` | 历史兼容跳转页；不要作为主流程读取 |
-
-## 触发信号
-
-- 用户明确说 MULTI_AGENT、multi agent、agent_graph、旧 agent、legacy graph、迁移到 chatflow。
-- 用户明确说创建新的 multi、创建 MULTI_AGENT、更新 MULTI_AGENT。
-- 输入 JSON 含 `multiAgentGraph`、`agentEdges`、`classifierPlugin`。
-- 用户要求先转 Mermaid、先分解、分步骤迁移旧图。
-- 旧图中有 `usedPlugins[].meta.toolAfterExecuteActions` 或工具 `actionStatuses`。
-
-如果用户只是说“流程图、多节点、条件分支、工具状态分支、人工节点”，但没有明确指定 legacy multi，回到 `../chatflow/overview.md`。

package/skills/agent-builder/references/multi-agent/update.md

@@ -1,128 +0,0 @@
-# MULTI_AGENT Update
-
-仅当用户明确要求更新已有 `MULTI_AGENT` / `multiAgentGraph` 时使用本文件。默认新建多节点流程使用 CHAT_FLOW；MULTI_AGENT 是 legacy 形态，不支持新建，因为不好维护。
-
-## 触发条件
-
-符合任一条件才进入本文件：
-
-- 用户要求更新一个已有 `MULTI_AGENT`，且提供 agent_id 或完整旧 JSON
-
-如果用户只是说“多节点、多分支、流程图、工具状态分支”，但没有明确指定 MULTI_AGENT，回到 `../chatflow/overview.md`。如果用户明确要求新建 legacy MULTI_AGENT / 旧 multi agent / 不要 CHAT_FLOW，不使用本文件，回到 `overview.md` 和 `workflow.md` 说明不支持新建并推荐 CHAT_FLOW。
-
-## 用户需求理解
-
-更新前，先按 `graph-spec.md` 理解旧图证据，再把需求整理成结构化设计，不直接写 payload。
-
-必须确认：
-
-- 业务目标：这个 agent 解决什么问题
-- 入口 agent：用户第一句话进入哪个 agent
-- 子 agent 职责：每个 agent 的名称、角色、prompt 目标
-- 工具：每个 agent 绑定哪些真实 `usedPlugins`，工具 id 是否已存在
-- 工具状态分支：`actionStatuses` 和每个 status 后的 action
-- 显式边：是否需要 `agentEdges`
-- 模板回复：template id / template content 来源
-- 转人工：哪些场景转人工，是否先回复
-- 结束：哪些场景 finish，是否先回复
-- KB：是否启用、目录 id、标签 id；只有已启用或启用状态未知且目录缺失时才提 `open_questions`，明确未启用只保留审计
-- 兜底：未知意图、工具异常、用户信息不足时怎么处理
-
-输出给用户确认时必须包含 Mermaid：
-
-```mermaid
-flowchart TD
-  A["entry old agent: collect_order"]
-  B["old agent: lookup_order<br/>tool: get_order"]
-  C["old agent: reply_shipping"]
-  H["transfer"]
-  A --> B
-  B -->|"found"| C
-  B -->|"not found"| H
-```
-
-用户未确认 Mermaid、agent 清单、工具清单和 action 清单前，不调用 update。
-
-## Tool Action 示例
-
-外部工具分支必须放在工具配置的 `toolAfterExecuteActions`，不要只写进 prompt：
-
-```json
-{
-  "id": 8299,
-  "name": "get_order_info",
-  "type": "EXTERNAL_HTTP_CALL",
-  "meta": {
-    "externalHttpCallConfig": {
-      "requestParam": {"items": []},
-      "responseParam": {"items": []},
-      "actionStatuses": [
-        {"name": "ORDER_FOUND", "condition": {"and": []}},
-        {"name": "ORDER_NOT_FOUND", "condition": {"or": []}}
-      ]
-    },
-    "toolAfterExecuteActions": [
-      {
-        "matchStatus": "ORDER_FOUND",
-        "actions": [{"type": "SWITCH_AGENT", "value": "agent_reply_order"}]
-      },
-      {
-        "matchStatus": "ORDER_NOT_FOUND",
-        "actions": [{"type": "TRANSFER_TO_HUMAN"}]
-      }
-    ]
-  }
-}
-```
-
-## 更新流程
-
-更新已有 MULTI_AGENT 必须先取完整对象，不允许只提交局部 patch：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-agent --id <agent_id> --pretty
-```
-
-将完整对象保存到：
-
-```text
-/workspace/state/agent-builder/multi-agent/update_<agent_id>_payload.json
-```
-
-修改后展示 diff 摘要和 Mermaid，请用户确认。确认后执行：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api update-agent \
-  --data-file /workspace/state/agent-builder/multi-agent/update_<agent_id>_payload.json \
-  --pretty
-```
-
-约束：
-
-- `agentId` 必须等于 `id`
-- `type` 必须保持 `MULTI_AGENT`
-- 不删除未知字段；完整对象更新时保留服务端已有字段
-- 修改 prompt 时同步 `prompt` 和 `displayPrompt`，但不要插入 `{{Template_Reply}}` 这类旧编辑器占位符
-- 工具 id 必须真实存在；先 `get-plugin`
-- action 目标 agent 必须存在于 `multiAgentGraph.agents[]`
-- 新增 template / KB / transfer 行为必须写出 open question 和用户确认
-
-## 更新结果
-
-执行成功后必须告诉用户：
-
-```text
-=== MULTI_AGENT Result ===
-Action: update
-Agent: <id> "<name>"
-Agents: N
-Tools: N
-Explicit agentEdges: N
-Tool action edges: N
-Template replies: N
-Transfer actions: N
-Finish actions: N
-Open questions resolved: N
-```
-
-如果用户后续要迁到 CHAT_FLOW，再切到 `migration/principles.md`，并按大小选择 `migration/small.md` 或 `migration/large.md`。

package/skills/agent-builder/references/multi-agent/workflow.md

@@ -1,87 +0,0 @@
-# MULTI_AGENT Workflow
-
-## 不支持新建
-
-用户要求新建 MULTI_AGENT 时，直接说明：
-
-```text
-MULTI_AGENT 是 legacy 形态，不支持新建，因为路由和工具动作分散在旧 graph/prompt/meta tools 中，不好维护。新建多节点流程请改用 CHAT_FLOW。
-```
-
-然后切到 `../chatflow/overview.md`。
-
-## 查看 / 解释已有 MULTI_AGENT
-
-1. 如果用户只给 agent_id，先取完整对象：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-agent --id <agent_id> --pretty
-```
-
-2. 将完整对象保存到：
-
-```text
-/workspace/state/agent-builder/multi-agent/read_<agent_id>_raw.json
-```
-
-3. 按 `graph-spec.md` 读取旧图字段。如果 graph 很大或 `displayPrompt` 含大量 HTML，必须先跑 analyzer：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/multi-agent/legacy_graph_analyzer.py inspect \
-  --input /workspace/state/agent-builder/multi-agent/read_<agent_id>_raw.json \
-  --out-dir /workspace/state/agent-builder/multi-agent \
-  --pretty
-```
-
-4. 解释结果必须区分：
-
-- old agents / tools / explicit agentEdges / action edges 数量。
-- 入口 agent。
-- 真实外部工具和 actionStatus。
-- template / transfer / finish / KB 结构能力。
-- prompt 中疑似旧工具指令和前端占位符。
-- 风险项：dangling ref、KB 空目录、模板缺失、prompt/action 冲突。
-
-纯查看/解释任务的结果必须直接展示在对话里。可以保留 `overview.mmd`、`index.ai.json` 等 state 文件作为审计
-证据，但不要让用户下载文件才能看到流程。迁移任务的交互门按 small / large 文档执行；large 模式不得把
-每个 batch 的局部图或计划逐轮展示给用户。
-
-## 更新已有 MULTI_AGENT
-
-只有用户明确要求更新已有 MULTI_AGENT 时才进入 `update.md`。更新前必须先解释当前结构，并让用户确认 Mermaid、agent 清单、工具清单和 action 清单。
-
-## 迁移到 CHAT_FLOW
-
-本节只负责分流和执行顺序；迁移保真规则以 `migration/principles.md` 为准，具体步骤以
-`migration/small.md` 或 `migration/large.md` 为准。
-
-1. 先读 `graph-spec.md` 和 `migration/principles.md`，确认旧图证据、coverage 和 PE 改写要求。
-2. 按大小选择：
-   - 短小图：`migration/small.md`
-   - 长图、HTML 噪音多、工具/action 多、用户要求先拆解：`migration/large.md`
-3. 迁移前必须先理解旧结构，不直接把完整 raw JSON 交给模型生成 CHAT_FLOW。
-4. small 模式按 `migration/small.md` 确认；large 模式只集中确认 blocking `open_questions` 和最终合并后的
-   全局 SOP → 节点类别 Mermaid。映射确认后才进入目标 source。
-5. 生成目标 source 时，切到 `../chatflow/graph-spec.md`、`../chatflow/node-selection.md` 和对应 `../chatflow/nodes/*.md`。
-6. compile / validate / deploy 只使用 `../chatflow/workflow.md` 里的 CHAT_FLOW CLI。
-
-迁移过程按 `migration/principles.md` 的“对话展示合同”输出。large 模式的 worker 只写 state，不与用户交互；
-协调器合并并去重问题后才发起确认。state 文件路径只能作为复现依据放在末尾；除非用户明确要求下载或留档，
-不把 Mermaid / plan / report 复制到 outputs。
-
-## 状态文件
-
-| 文件 | 用途 |
-|------|------|
-| `/workspace/state/agent-builder/multi-agent/read_<id>_raw.json` | 读取/解释旧 agent 原始对象 |
-| `/workspace/state/agent-builder/multi-agent/update_<id>_payload.json` | 更新已有 MULTI_AGENT 的完整 payload |
-| `/workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/index.ai.json` | analyzer 裁剪后的 AI 输入 |
-| `/workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/overview.mmd` | 旧图 Mermaid 总览 |
-| `/workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/sop_mapping.mmd` | 经确认的 SOP → 节点映射 Mermaid |
-| `/workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/chunks.json` | 旧图 chunk 清单 |
-| `/workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/progress.json` | batch 检查点和可恢复进度 |
-| `/workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/batches/worker_manifest.json` | 当前并发 wave 的 worker 输入/输出清单 |
-| `/workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/batches/<batch>.context.json` | 单个 worker 的只读有界输入 |
-| `/workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/batches/<batch>.plan.json` | 单个 worker 的隔离输出；不含 Mermaid |
-
-迁移生成 CHAT_FLOW source / graph 后，目标文件放 `/workspace/state/agent-builder/chatflow/`，不放回 `multi-agent/`。

package/skills/agent-builder/references/single-agent/overview.md

@@ -1,48 +0,0 @@
-# SINGLE_AGENT
-
-SINGLE_AGENT 适合目标单一、分支少、一个 prompt 能说清职责的场景。超过 3 个稳定流程分支、需要条件路由或人工审批时，改用 CHAT_FLOW。
-
-## 创建
-
-```bash
-npx --yes @shulex/cxclawctl@latest api create-agent \
-  --data-file /workspace/state/agent-builder/single_agent_payload.json \
-  --pretty
-```
-
-最小结构：
-
-```json
-{
-  "name": "FAQ_Bot",
-  "type": "SINGLE_AGENT",
-  "source": "MANUAL",
-  "prompt": "...",
-  "displayPrompt": "...",
-  "usedPlugins": []
-}
-```
-
-## 更新
-
-更新前先查完整对象：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-agent --id <agent_id> --pretty
-npx --yes @shulex/cxclawctl@latest api update-agent \
-  --data-file /workspace/state/agent-builder/update_agent_<agent_id>.json \
-  --pretty
-```
-
-约束：
-
-- `update-agent` 必须提交完整对象。
-- `agentId` 必须等于 `id`。
-- 改 prompt 时同步改 `prompt` 和 `displayPrompt`。
-- 工具只写真实工具 id；先用 `list-plugins` / `get-plugin` 确认。
-
-## 相关文档
-
-- prompt：`prompt.md`
-- 工具绑定：`tools.md`
-- 语音 Agent：`voice.md`

package/skills/agent-builder/references/single-agent/prompt.md

@@ -1,16 +0,0 @@
-# SINGLE_AGENT Prompt
-
-Prompt 要写职责、边界、工具使用条件和回复要求，不要把路由流程、模板回复、转人工策略全塞进去。流程复杂时改用 CHAT_FLOW。
-
-## 必守规则
-
-- `prompt` 和 `displayPrompt` 保持一致。
-- prompt 提到的外部能力必须有真实工具绑定。
-- 固定话术优先走模板库或 CHAT_FLOW REPLY(TEMPLATE)，不要让 SINGLE_AGENT 硬背长固定文本。
-- 需要变量系统字段时先查 `list-ai-fields`，并确认对应字段会在运行时进入上下文。
-
-## 常见错误
-
-- prompt 写“调用订单工具”，但 `usedPlugins` 没有订单工具 id。
-- prompt 要求多分支跳转，但 Agent 本体没有稳定路由能力。
-- 只改 `displayPrompt`，导致页面展示和实际执行不一致。

package/skills/agent-builder/references/single-agent/tools.md

@@ -1,36 +0,0 @@
-# SINGLE_AGENT Tools
-
-SINGLE_AGENT 通过 `usedPlugins` 绑定可调用工具。对外叫“工具”，底层字段仍叫 `plugin`。
-
-## 查询工具
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-plugins --pretty
-npx --yes @shulex/cxclawctl@latest api get-plugin --id <tool_id> --pretty
-```
-
-`list-plugins` 只看精简列表；确认 requestParam / responseParam / actionStatuses 时使用 `get-plugin` 查看完整定义。
-
-## 绑定格式
-
-SINGLE_AGENT 通常使用工具 id 数组：
-
-```json
-{
-  "usedPlugins": [2019, 2020]
-}
-```
-
-不要写成对象数组，除非已确认该 Agent 类型和接口需要完整工具对象。
-
-## 调试
-
-`run-plugin` 会真实调用目标接口，只在用户明确要求或授权后执行；不能把它当作绑定工具或上线前的默认步骤。目标为写接口时，执行前还要额外确认请求体和影响范围。
-
-`run_tool_config.json` 必须是包含 `externalHttpCallConfig` 和 `externalHttpCallRequestBody` 的 envelope，完整结构见 `../tools/http-tool.md`：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api run-plugin \
-  --data-file /workspace/state/agent-builder/run_tool_config.json \
-  --pretty
-```

package/skills/agent-builder/references/single-agent/voice.md

@@ -1,46 +0,0 @@
-# Voice Agent
-
-Voice Agent 是 `SINGLE_AGENT` 的语音特化：`type` 仍为 `SINGLE_AGENT`，通过 `meta.category = "voice"` 进入语音链路。
-
-## 创建结构
-
-```json
-{
-  "name": "Voice_Support",
-  "type": "SINGLE_AGENT",
-  "source": "MANUAL",
-  "prompt": "Use short, spoken sentences.",
-  "displayPrompt": "Use short, spoken sentences.",
-  "meta": {
-    "category": "voice",
-    "version": "v1",
-    "assistant": {
-      "callType": "INBOUND_PHONE_CALL",
-      "firstMessage": "Hello, how can I help?",
-      "language": "en-US"
-    }
-  }
-}
-```
-
-## 关键字段
-
-| 字段 | 说明 |
-|---|---|
-| `type` | 固定 `SINGLE_AGENT` |
-| `meta.category` | 固定 `voice`，必须在 `meta` 内 |
-| `meta.assistant` | 必填，不能为 null |
-| `meta.assistant.callType` | `INBOUND_PHONE_CALL` / `OUTBOUND_PHONE_CALL` / `WEB_CALL` |
-| `meta.assistant.language` | 语音识别和合成语言 |
-| `meta.assistant.firstMessage` | 接通后第一句话 |
-
-## CLI
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-voice-agents --pretty
-npx --yes @shulex/cxclawctl@latest api create-agent \
-  --data-file /workspace/state/agent-builder/voice_agent_payload.json \
-  --pretty
-```
-
-更新语音 Agent 前仍然先 `get-agent`，再提交完整对象。