@shulex/cxclawctl 0.1.2 → 0.1.3

package/skills/agent-builder/references/chatflow/visual-translation.md

@@ -1,64 +0,0 @@
-# 流程图读取规范
-
-从流程图、白板草图、决策树或 SOP 大图生成 CHAT_FLOW 时，先把图片理解成结构化摘要，再按 `node-selection.md` 选节点、按 `graph-spec.md` 写 source JSON。
-
-## 大图读取
-
-先由主 agent 对用户上传图片调用一次 `read_file`，拿 overview 和 tile manifest。主 agent 负责全局调度：先从 overview 识别入口、主分支、终点、布局方向和明显缺口，再决定是否需要读取局部 tile。普通小图或 overview 已足够清楚时，不需要 subagent。
-
-如果图片过大并返回 tile manifest（`/store/read_file_images/.../tile_r{row}_c{col}.jpg`），创建 chatflow 前必须先完成全图覆盖式理解：不能只根据 overview 或少量 tile 开始构图，也不要一次性读取全部 tile。
-
-按迭代方式读图：
-
-1. 主 agent 先读 overview 和 manifest，确认行列范围、流程方向、主要区域、入口/终点候选和明显缺口。
-2. 主 agent 写出当前理解：`已识别区域`、`待确认区域`、`需要读取的 tile 范围`。
-3. 每次只派 subagent 读取一个局部连续区域，例如入口区、某条主流程、某个下方分支或某组看不清的节点。
-4. subagent 只读取主 agent 指定的少量 tile，输出局部摘要：`区域位置`、`入口/出口`、`节点文字`、`边/流转`、`条件分支`、`跨 tile 连接点`、`转人工/结束点`、`看不清的问题`。
-5. 主 agent 合并局部摘要后更新全局结构和缺口列表；如果入口、主要分支、跨 tile 连接、结束节点或关键话术仍未覆盖，再派下一次 subagent 读必要 tile。
-6. 只有主要流程、关键分支、跨 tile 连接点和结束节点均已覆盖后，才能开始落 chatflow。
-7. 如果仍有看不清的区域，必须在摘要里显式标注不确定点；不能臆造节点、边或话术。
-
-给 subagent 的 prompt 写清：
-
-- 原图虚拟路径、tile manifest、待读 tile 列表和本次局部目标；subagent 不会自动看到主 agent 已读过的内容。
-- 只读指定 tile；除非指定 tile 明显不够且会影响本次目标，才最多补读相邻 tile，并在摘要里说明原因。
-- 只输出结构化摘要，不生成 chatflow JSON，不调用 CLI，不写文件，不探索 `/skills/`、`/skill-lib/` 或凭证文件。
-- 每个 subagent 只负责一个局部区域，并输出压缩后的结构化摘要。
-
-## 结构化摘要
-
-读图完成后先写摘要，再建 source：
-
-```text
-Direction: top-to-bottom / left-to-right / mixed
-Entry: <入口节点文字>
-Terminal nodes: <结束/转人工/子流程>
-
-Nodes:
-- <编号> <原图文字> | role=<业务作用> | outgoing=<出口>
-
-Edges:
-- <from> --<条件/按钮/状态>--> <to>
-
-Unclear:
-- <看不清或需要用户确认的点>
-```
-
-## 落图顺序
-
-1. 识别入口、终点、转人工点。
-2. 用 `node-selection.md` 为每个业务节点选择 CHAT_FLOW 节点类型。
-3. 用 `graph-spec.md` 写 source JSON 和 edges。
-4. 只读取实际用到的 `nodes/*.md` 补字段和资源依赖。
-
-## 视觉到节点的快速提示
-
-- 矩形且由确定状态必然发送的固定回复：通常是 `REPLY(TEMPLATE)`，先查模板库。若图中表达的是某个
-  模型节点必须遵循的 PE/输出话术约束，则保留在该节点的实际文本字段，不因“固定话术”标签强制改成 REPLY。
-- 菱形简单条件：通常是 `IF_ELSE`。
-- 用户选项/按钮：通常是 `QUESTION(USER_REPLY)`。
-- 流程图中的 Y/N、True/False、满足/不满足：默认是条件分支，不是用户按钮；Y 表示条件满足，N 表示条件不满足，通常映射为 `IF_ELSE` 的 case/FALSE 或工具 `actionStatus`。只有明确写着“请用户选择是/否”时才映射为 `QUESTION(USER_REPLY)`。
-- 查询接口/调用系统：`TOOL -> IF_ELSE` 或 `AGENT(with tools, next_steps)`。
-- 知识库回答：默认 `RAG_REPLY`。
-- 红色转人工：`TRANSFER_TO_HUMAN`。
-- 结束：默认连共享 `$finish`。

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

@@ -1,134 +0,0 @@
-# Chatflow 工作流
-
-## 大图的流程块实现
-
-整体流程图已经确认且单次上下文不适合实现整张大图时，按确认图中的稳定流程块分别实现 source fragment，
-不要把整份大图重新塞回一次模型上下文。流程块来自当前任务已经确认的设计，不依赖任何特定上游图格式或
-迁移字段。每个 fragment 只包含该流程块的 `nodes` 和块内 `edges`，节点 `key` 必须全局唯一；fragment
-不写 `entry`，也不能写到另一流程块的边。
-
-最终 integration 文件只拥有全图 `entry` 和流程块之间的边，不定义节点。例如：
-
-```json
-{
-  "entry": "collect_order",
-  "edges": [
-    {"from": "collect_order", "to": "lookup_order"}
-  ]
-}
-```
-
-所有 fragment 完成后，先合并 source，再只编译一次最终 source：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py merge-source \
-  --fragment-file /workspace/state/agent-builder/chatflow/<task>/blocks/collect_order.json \
-  --fragment-file /workspace/state/agent-builder/chatflow/<task>/blocks/lookup_order.json \
-  --integration-file /workspace/state/agent-builder/chatflow/<task>/blocks/integration.json \
-  --out-file /workspace/state/agent-builder/chatflow/<task>_source.json \
-  --pretty
-```
-
-随后对这份唯一 source 执行 `compile` 和 `validate`。不要分别编译流程块，也不要合并已编译的 graph JSON；
-后者会重复生成入口、节点 id、布局和共享终端。
-
-## 新建
-
-1. 如果输入是截图或 PDF，先读 `visual-translation.md` 得到结构化摘要。
-2. 读 `node-selection.md` 形成候选节点组合。
-3. 在写 source 前，必须先向用户展示拟构建 Mermaid、节点职责、边条件（默认将 Y 解释为“条件满足”、N 解释为“条件不满足”，并说明是否存在用户确认语义）、等待/收集点和不确定点；结构性流程未经用户确认不得 compile 或 deploy。若当前任务已经有确认过的整体流程图，直接复用该确认，不重复增加确认轮次。
-4. 在最终选择节点前，必须读取每个候选节点对应的 `nodes/*.md` 定义，确认 role、edges、
-   prompt/字段约束和常见误用；不要只凭节点名理解用途。
-5. 普通小图按 `graph-spec.md` 写 source JSON 到 `/workspace/state/agent-builder/chatflow/<task>_source.json`；
-   大图按上一节写流程块 fragment，再合并为这份 source。
-6. 再次按已选节点的 `nodes/*.md` 补齐字段和资源 id。
-   AGENT 内需要模型自主决定是否执行的模板、普通工具和转人工动作使用 `nodes/agent.md` 定义的标准
-   LibraryBlock；确定性动作仍使用对应独立节点，不能只写普通文字描述。
-7. 检查变量来源：CHAT_FLOW 不感知 `metadata` 路径，所有节点都禁止写 `metadata.xxx`。AGENT / `REPLY(PROMPT)` 如需稳定使用上游输出，先用 `VARIABLE_PROCESS` 桥接到变量系统字段；`REPLY(DYNAMIC_TEMPLATE)`、LLM 和 HUMAN_REVIEW 的模板可直接使用其支持的上游 selector。
-8. 编译同一份 source：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py compile \
-  --source-file /workspace/state/agent-builder/chatflow/<task>_source.json \
-  --graph-file /workspace/state/agent-builder/chatflow/<task>_graph.json \
-  --pretty
-```
-
-9. 校验同一份 graph：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py validate \
-  --graph-file /workspace/state/agent-builder/chatflow/<task>_graph.json \
-  --pretty
-```
-
-10. 失败就改同一个 source 后重新 compile + validate。若只出现 `queryAiFields` / `field/internal/list` / `tars: Name does not resolve` 相关 warning，说明变量字段服务不可用；没有字段 id 依赖的图可继续后续确认，不要改图结构绕开。
-    含 LibraryBlock 的 AGENT 还要核对：模板块使用具体模板内容 ID、模板状态为 `ENABLED`、`usedPlugins`
-    已包含普通工具 ID，并从 Chatflow 专用插件目录按类型绑定当前项目真实的 `TEMPLATE_REPLY` /
-    `TRANSFER_TO_HUMAN` 系统插件 ID；同时确认 `transferToHumans=[]`、runtime `prompt` 与 `displayPrompt`
-    同步、nextStep 没有被误当成人工接管。
-11. 校验通过后确认是否写入当前环境和 agent 名称；若当前任务先前的整体确认已经明确包含目标环境、名称和
-    保存草稿授权，直接复用，不重复询问。
-12. 用户确认后 deploy 同一份 graph。一次创建多个 CHAT_FLOW agent 时，顺序执行每个 `deploy`；不要用 shell `&` 并发部署多个 agent。
-13. deploy 或现有图 update 后执行一次 `inspect` 回读；逐个检查 LibraryBlock 仍为标准格式。默认只保存草稿，
-    除非用户明确要求发布，不执行 `publish`。
-
-本地无网络或尚未准备登录态时，可在 compile 和 validate 后加 `--offline` 做结构预检。离线模式跳过远端 AI 字段、插件存在性和插件参数合同检查；上传前必须联网复核。
-
-## 增量修改
-
-1. 先 inspect 拉当前图，并写入本次 patch graph：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py inspect \
-  --agent-id <agent_id> \
-  --out /workspace/state/agent-builder/chatflow/patch_<agent_id>_graph.json \
-  --pretty
-```
-
-2. inspect 得到的完整 graph 是已有流程的编辑基线。已有 ChatFlow 的维护沿用 inspect 得到的 patch graph，可在这份 patch graph 上修改节点字段、增删节点、修改边、拆分条件分支或调整路由等，保持未涉及节点及其原始配置不变。
-3. validate patch graph 通过后默认 update 保存草稿，不发布：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py update \
-  --agent-id <agent_id> \
-  --graph-file /workspace/state/agent-builder/chatflow/patch_<agent_id>_graph.json \
-  --pretty
-```
-
-4. 用户明确确认发布后，对同一份 graph 执行 publish：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py publish \
-  --agent-id <agent_id> \
-  --graph-file /workspace/state/agent-builder/chatflow/patch_<agent_id>_graph.json \
-  --pretty
-```
-
-## 变更方案说明
-
-- 新建图方案，或增量任务涉及新增 / 删除节点、修改边、调整条件分支、改变入口出口或路由关系等结构性修改时，面向用户的说明里应附一段 Mermaid，概括修改后的流程结构，帮助用户确认理解是否一致。
-- 大图不要完整铺开，优先展示受影响子图，并保留这段子图与上游入口、下游出口的连接关系；必要时再补一句未展示区域保持不变。
-- Mermaid 必须根据 inspect 得到的现有图、待写入的 source / graph 以及 validate 结果生成。条件边使用真实出边语义或 handle；代码节点必须明确标成代码节点，并展示它实际连接的上下游，不能因为代码内容复杂就从图中省略。
-- 只修改 prompt、话术、模型参数、工具入参映射或单个节点内部字段，且不改变节点和边时，不强制输出 Mermaid。
-- 对已有图、节点配置或提示词提出修改方案时，用户确认前按整体输出规则用 `diff` 展示受影响片段的前后差异；结构性修改可同时提供 Mermaid 和 diff，分别说明流程关系与具体配置变化。
-- 用户确认前展示的是“拟修改结构”；update / deploy 后展示的是实际校验通过的结构。不要把尚未写入的方案描述成已经生效。
-- Mermaid 只用于解释，不能替代 source JSON、graph JSON 或 validate。图示与实际 graph 不一致时，以校验通过的 graph 为准，并立即修正图示。
-
-## 状态和留档
-
-- 工作中的 source / graph 放 `/workspace/state/agent-builder/chatflow/`。
-- 大图的 fragment 与 integration 放 `/workspace/state/agent-builder/chatflow/<task>/blocks/`；合并后的唯一 source
-  仍放 `/workspace/state/agent-builder/chatflow/<task>_source.json`。
-- 文件名稳定，跨轮覆盖，便于继续。
-- 等用户确认后继续执行的配置文件也放 `/workspace/state/agent-builder/chatflow/`，不要放 `/workspace/tmp/`。
-- 只有用户明确要求下载或留档，才复制到 `/workspace/outputs/agent-builder/chatflow/`。
-
-## 禁止
-
-- 不写临时 Python 脚本承载构图、校验、部署。
-- 不 import `chatflow_builder.py`。
-- 不用 `update-agent --id ... --data-file graph.json` 写回纯 graph。
-- 不在用户确认前新建或发布。
-- 不在任何节点 prompt、selector、条件、工具入参或代码输入里写 `metadata.xxx`；变量系统字段通过 ai-fields
-  暴露，需要变量时按节点契约使用 `SYSTEM` selector、`ai_field_ids` 或支持的上游变量模板。

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

@@ -1,185 +0,0 @@
-# MULTI_AGENT Create / Update
-
-Deprecated：本文件是旧版 create/update 说明，保留用于历史引用。当前规则以 `overview.md` 和
-`workflow.md` 为准：不支持新建 `MULTI_AGENT`；用户要求新建多节点流程时切到 `../chatflow/overview.md`。
-只有用户明确要求维护已有 `MULTI_AGENT` 时，读取 `workflow.md`、`graph-spec.md` 和 `update.md`。
-
-## 触发条件
-
-符合任一条件才进入本文件：
-
-- 用户要求更新一个已有 `MULTI_AGENT`，且提供 agent_id 或完整旧 JSON
-- 用户明确不要 CHAT_FLOW，而要旧 multi-agent 形态
-
-如果用户只是说“多节点、多分支、流程图、工具状态分支”，但没有明确指定 MULTI_AGENT，回到 `../chatflow/overview.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 清单前，不调用 create / update。
-
-## 存量更新流程
-
-1. 读 `overview.md`、`workflow.md`、`graph-spec.md` 和 `update.md`。
-2. 若涉及工具，按 `../tools/overview.md` 查工具 id 和完整配置。
-3. 写 payload 到：
-
-```text
-/workspace/state/agent-builder/multi-agent/create_<name>_payload.json
-```
-
-4. 向用户展示摘要和 Mermaid，请用户确认。
-5. 用户确认后执行：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api create-agent \
-  --data-file /workspace/state/agent-builder/multi-agent/create_<name>_payload.json \
-  --pretty
-```
-
-## 最小 Payload
-
-```json
-{
-  "name": "Shipping_Inquiry_Multi",
-  "type": "MULTI_AGENT",
-  "category": "TEXT",
-  "source": "MANUAL",
-  "prompt": "",
-  "displayPrompt": "",
-  "usedPlugins": [],
-  "meta": {
-    "multiAgentGraph": {
-      "entryAgentId": "agent_collect_order",
-      "agents": [
-        {
-          "id": "agent_collect_order",
-          "name": "collect_order",
-          "type": "AGENT",
-          "prompt": "Collect the order number from the customer.",
-          "displayPrompt": "Collect the order number from the customer.",
-          "usedPlugins": [],
-          "meta": {}
-        }
-      ],
-      "agentEdges": [],
-      "displayData": {}
-    }
-  }
-}
-```
-
-实际创建时必须用服务端接受的 id 格式。若没有可复用旧 id，先用稳定字符串 id 生成草稿并请用户确认；如果环境要求数字 id，则在 create 前改为符合旧引擎约束的 id。
-
-## 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: create/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，再切到 `workflow.md` 的“迁移到 CHAT_FLOW”，并按 `migration/principles.md`
-与 `migration/large.md` / `migration/small.md` 执行。

package/skills/agent-builder/references/multi-agent/graph-spec.md

@@ -1,246 +0,0 @@
-# MULTI_AGENT Graph Spec
-
-本文件只解释 legacy MULTI_AGENT 的旧 JSON 结构、证据优先级和清洗规则，不包含目标图映射。
-
-## 输入形态
-
-analyzer 和人工阅读都应支持三种输入：
-
-```json
-{"id": 123, "type": "MULTI_AGENT", "meta": {"multiAgentGraph": {"agents": [], "agentEdges": []}}}
-```
-
-```json
-[{"category": "TEXT", "meta": {"multiAgentGraph": {"agents": [], "agentEdges": []}}}]
-```
-
-```json
-{"entryAgentId": "agent_a", "agents": [], "agentEdges": []}
-```
-
-## 核心字段
-
-| 字段 | 说明 |
-|------|------|
-| `entryAgentId` | 旧图入口 agent id；没有时用入边推断 |
-| `agents[]` | 子 agent 列表 |
-| `agents[].id/name/type` | 子 agent 标识、名称、类型 |
-| `agents[].prompt` | 旧 PE，保留业务语义，但不能覆盖结构化 action/tool 证据 |
-| `agents[].displayPrompt` | 前端展示内容，常含 HTML 和占位符；默认不作为模型输入 |
-| `agents[].usedPlugins[]` | 真实绑定工具 |
-| `agentEdges[]` | 显式 old agent 跳转 |
-| `meta.classifierPlugin` | 旧分类器及其 action |
-| `meta.templateReplyPlugin` | 模板回复结构能力 |
-| `meta.transferToHumanPlugin` / `transferToHumans[]` | 转人工结构能力 |
-| `meta.finishAgentPlugin` | 结束结构能力 |
-| `meta.knowledgeAiReplyPlugin` | 旧知识回复配置 |
-
-## 工具字段
-
-| 字段 | 说明 |
-|------|------|
-| `usedPlugins[].id/name/type` | 工具 id、名称、类型 |
-| `usedPlugins[].meta.externalHttpCallConfig.requestParam` | 外部工具入参 |
-| `usedPlugins[].meta.externalHttpCallConfig.responseParam` | 外部工具出参 |
-| `usedPlugins[].meta.externalHttpCallConfig.actionStatuses[]` | 工具状态分支 |
-| `usedPlugins[].meta.toolAfterExecuteActions[]` | 工具执行后的结构化 action |
-
-`toolAfterExecuteActions[].actions[]` 常见 action：
-
-| type | 旧图控制语义 |
-|------|----------|
-| `SWITCH_AGENT` | 跳到另一个 old agent |
-| `TEMPLATE_REPLY` | 执行模板回复动作 |
-| `TRANSFER_TO_HUMAN` | 发起人工接管动作 |
-| `FINISH_AGENT` | 结束当前处理 |
-
-### 运行时控制语义
-
-Java `MultiAgentService.getLangGraphStructure` 会把 legacy multi 转成 agent_graph 结构：
-
-- `entryAgentId` 作为唯一入口。
-- `agentEdges[]` 会转成 `agent_edges[fromAgentId] = [toAgentId...]`。
-- 每个 agent 的内置 meta plugin 和 `usedPlugins[]` 都会变成 agent 可调用工具。
-- 每个工具保留自己的 `toolAfterExecuteActions`；外部工具的 action 配置保存在 multi graph 里，刷新工具定义时会补回。
-
-Python agent_graph 运行时会把 `agentEdges[]` 变成 `transfer_to_<agent_name>` 的 `SWITCH_AGENT`
-工具，只暴露给对应上游 agent；工具 action 中的 `SWITCH_AGENT.value` 是目标 agent id，运行时再
-查成目标 agent name 并跳转。读取旧图时应按以下方式理解：
-
-- `SWITCH_AGENT` 是控制流，不是外部 HTTP 工具。
-- `agentEdges[]` 表示模型可主动选择的相邻 agent；`toolAfterExecuteActions[].actions[].type=SWITCH_AGENT`
-  表示某个工具状态或分类结果命中后自动进入目标 agent。
-- 目标 agent 是否承载独立 SOP 职责、工具、用户轮次、回复或判断，应作为后续迁移的语义证据；纯跳转壳必须被明确标记，不能与独立职责混淆。
-
-`toolAfterExecuteActions` 的匹配规则：
-
-- 外部 HTTP / 订单 / 物流工具按返回的 `__status` 匹配 `matchStatus`。
-- classifier 按分类返回的 `category` 匹配 `matchStatus`。
-- `matchStatus == null` 是兜底 action，运行时按列表顺序取第一条匹配项。
-- 同一个匹配项里的 `actions[]` 是动作序列；可能先有 `TEMPLATE_REPLY` 或
-  `user_input_template_*`，再 `SWITCH_AGENT` / `TRANSFER_TO_HUMAN` / `FINISH_AGENT`。
-  因此迁移时不能只看最终动作，必须保留“先回复/模板，再跳转/转人工/结束”的组合语义。
-
-## 证据优先级
-
-1. `entryAgentId` 定入口。
-2. `usedPlugins[]` 定真实工具。
-3. `externalHttpCallConfig.actionStatuses[]` 定工具状态分支。
-4. `toolAfterExecuteActions[]` 和 `classifierPlugin.meta.toolAfterExecuteActions[]` 定隐式动作边。
-5. `agentEdges[]` 定显式 old agent 跳转。
-6. template / transfer / finish / KB meta tools 定结构能力。
-7. `prompt` 只补业务语义和话术边界。
-8. `displayPrompt` 只做前端噪音检测、占位符审计和人工核对。
-
-证据冲突时，以 action/tool/plugin 结构优先；prompt 冲突进入 `open_questions`。
-
-## 前端噪音清洗
-
-### 工具渲染壳与真实工具语义必须分开
-
-旧 multi 的 `displayPrompt` 不是纯展示文本。编辑器会把工具插入渲染成类似：
-
-```html
-<span style="color: #00CDAC">{{Obtain_Package_OrderDetails}}</span>
-```
-
-这里的 `<span>`、`style` 和嵌套标签是展示壳；`Obtain_Package_OrderDetails` 是工具引用，
-不能因为清洗 HTML 而丢失。解析时必须同时保留三类证据：
-
-| 证据 | 作用 | 处理方式 |
-|------|------|----------|
-| `displayPrompt` 中的 `{{ToolName}}` | 编辑器插入的工具 chip | 去掉标签和样式，提取为 `tool_references` |
-| `agents[].usedPlugins[]` | 当前 old agent 真正绑定的外部工具 | 保留 id/name/type、请求/响应参数和状态 |
-| `meta.*Plugin` / `classifierPlugin` | 系统工具、分类器和模板/转人工能力 | 保留工具类型、配置和 action |
-
-`tool_references` 必须与结构化工具证据做对账：
-
-- 引用与 `usedPlugins` 或系统 plugin 匹配：视为已绑定可执行资源，保留其 id/type/action 证据；
-  后续映射由迁移文档决定。
-- 引用只出现在 `displayPrompt`，但结构化 plugin 存在：保留 plugin 证据，记录为渲染引用。
-- 引用只出现在 `displayPrompt`，找不到结构化 plugin：不得静默删除，但只写入 audit warning，
-  不生成用户问题。PE 中是否存在可执行引用，由 batch worker 结合完整 PE、结构化资源和流程上下文做
-  语义判断；analyzer 不用 `call/use <name> tool` 等短语正则生成 blocking 结论。worker 确认存在动作但仍
-  无法确定绑定时，才写入 `open_questions`。
-- `Template_Reply`、`Transfer_To_Agent`、`Finish_Agent` 不是普通文案，分别按旧系统动作/终端
-  语义记录；其中 template id、transfer reason 和 action status 优先从结构化字段取值。
-
-系统知识占位符 `{{KB_Reply}}` 可按 `name=KB_Reply`、`source=SYSTEM`、
-`type=KNOWLEDGE_AI_REPLY` 识别。知识配置既可能直接位于 `knowledgeAiReplyPlugin.directoryIds`，也可能
-位于 `knowledgeAiReplyPlugin.meta.knowledgeAiReplyConfig.directoryIds`；后者的启用状态优先。明确
-`enable=false` 的 KB 只保留 audit。已启用或启用状态未知的 KB 目录为空才是
-blocking 风险：提供可用 directory id 或明确移除该能力。没有插件的 display-only `KB_Reply` 同样只是
-audit；只有结构化 SYSTEM 能力或明确可执行 prompt 调用缺失时才进入 blocking open question。
-
-必须清掉或降权：
-
-- `createdAt`、`updatedAt`、`createdBy`、`updatedBy`、`createAtLong`、`updateAtLong`
-- `displayData`、`positions`、`viewport`、前端画布样式
-- 完整 `displayPrompt` HTML 文本
-- `<span style=...>`、嵌套标签和孤立 `style="...">` 这类展示壳
-- 已经提取为 `tool_references` 的原始占位符文本
-
-清洗后保留：
-
-- `prompt` 的业务语义片段。
-- `prompt_review.prompt` 中经可恢复编码修复后的完整 PE、SHA-256 和字符数；它不受 evidence 预算截断。
-- `prompt_review.protected_refs` 中已经由 PE runtime 语法明确表达的模板、转人工和已绑定业务工具引用；
-  每项保留稳定 ID、精确 span/quote 和原始绑定，供合并校验防漏防篡改。自然语言中的固定话术、等待点和
-  其他动作不由该字段推断，仍交给全文语义审阅。
-- `displayPrompt` 的纯文本摘要、长度、占位符名、是否含 HTML。
-- 从渲染 chip 提取的 `tool_references` 及其结构化绑定状态。
-- 结构化 action/tool/template/transfer/finish/KB 证据。
-
-## 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
-```
-
-输出目录：
-
-```text
-/workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/
-  index.full.json
-  index.ai.json
-  overview.mmd
-  chunks.json
-  progress.json
-  batches/worker_manifest.json
-  batches/<batch>.context.json
-  batches/<batch>.plan.json
-```
-
-| 文件 | 用途 |
-|------|------|
-| `index.full.json` | 完整语义索引，供人工审计 |
-| `index.ai.json` | 已裁剪、可给模型读取的语义输入 |
-| `overview.mmd` | 旧图 Mermaid 总览 |
-| `chunks.json` | chunk 清单 |
-| `progress.json` | batch 可恢复进度；并发状态以 `active_batch_ids[]` 为准，`current_batch_id` 只兼容单 worker 旧目录 |
-| `batches/worker_manifest.json` | 一个并发 wave 的隔离输入/输出路径和 worker 合同 |
-| `batches/<batch>.context.json` | worker 只读的有界输入 |
-| `batches/<batch>.plan.json` | worker 独立写入的语义计划；不写共享 progress 或局部 Mermaid |
-
-`index.full.json` / `index.ai.json` 还包含统一 `resources[]`：外部 plugin、SYSTEM chip、知识能力和
-未识别引用都必须在其中有 `resource_kind`、证据来源和目标映射。迁移 coverage 应引用这份清单，
-不要分别从 prompt、usedPlugins 和 meta 再次猜测同一资源。
-
-图结构事实位于 `topology`：`control_edges` 只包含结构化 `SWITCH_AGENT` 的确定性控制流；
-`model_selectable_edges` 单列 `agentEdges[]` 的模型可选跳转。`reachable_agent_ids` 表示旧运行时可达性，
-`deterministically_reachable_agent_ids` 只按确定性控制流计算。AI 建立 SOP 时必须区分二者，不能把
-`model_selectable_edges` 自动变成目标图边；`overview.mmd` 用虚线展示它们。`unreachable_agent_ids` 非空时
-仍是阻塞风险，不能静默补边或丢弃。
-
-`index.ai.json` 中每个 agent 都带精简 `action_edges`，保留来源、工具、`match_status`、动作类型、
-目标和模板状态，但不带前端 raw 字段。这样 AI 可以按 agent 读取完整分支合同，又不会把整份 legacy
-JSON 或 HTML 噪音重复塞入上下文。
-
-PE 还带 `prompt_review`、`prompt_quality` / `prompt_evidence.encoding_quality`：
-
-- `clean`：未发现明显编码异常；
-- `mojibake_suspected`：疑似 UTF-8/Latin-1 错解码；
-- `replacement_character`：出现 Unicode replacement character `�`。
-
-分析器会把经可恢复编码修复后的完整 PE 写入 `prompt_review.prompt`，并记录 `prompt_sha256` /
-`prompt_char_count`；这是 worker 的强制全文审阅合同。另将 HTML 噪音和 legacy 工具指令清洗到
-`agent.prompt` / `prompt_evidence.evidence`，仅用于紧凑的流程摘要。`prompt_evidence.encoding_quality`
-记录清洗前质量，`prompt_evidence.cleaned_encoding_quality` 记录清洗后质量；编码问题本身不是迁移阻塞项。
-
-`coverage_required.prompt_reviews` 会把完整 PE 原样带进对应 batch，即使 `prompt_evidence` 因预算被截断也不
-截断。worker 输出 `discovered_blocks` 和 `control_semantics`；`merge-batch-plans` 再根据结构化 kind、具体
-模板/工具 id、精确转人工 reason 和完整固定话术派生 LibraryBlock、plugin 绑定与内容 hash。自然语言识别和
-协议渲染因此分层：前者由模型理解流程，后者由脚本确定性生成。固定话术使用通用
-`NODE_PROMPT_FIELD`，最终按已选节点合同填写 `render_path`；analyzer 不把它预设成 REPLY。
-
-索引还包含 `coverage_manifest`，为 agents、tools、resources、explicit edges、action edges 和
-`prompt_reviews` 提供稳定 ID。最终 migration plan 必须按 ID 对账；只按节点数量相等不能证明迁移完整。
-
-并发生成/恢复 batch context（每批默认 4 个 chunk、12 条 action edge、20000 evidence 字符）：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/multi-agent/legacy_graph_analyzer.py prepare-batches \
-  --index-file /workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/index.ai.json \
-  --chunks-file /workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/chunks.json \
-  --progress-file /workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/progress.json \
-  --out-dir /workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/batches \
-  --parallelism 4 \
-  --pretty
-```
-
-协调器读取 manifest 后并发运行 worker；每个 worker 只读取自己的 context、写自己的 plan，不向用户提问、
-不生成 Mermaid，也不修改 `progress.json`。worker 全部结束后由 `merge-batch-plans` 串行合并和更新共享进度。
-
-生成 migration plan 后，先用脚本检查流程骨架、节点决策和 coverage：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/multi-agent/legacy_graph_analyzer.py validate-migration-plan \
-  --plan-file /workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/migration_plan.json \
-  --index-file /workspace/state/agent-builder/multi-agent/migrate_<id>_<name>/index.full.json \
-  --pretty
-```
-
-该检查未通过时只能继续补迁移 plan，不能进入完整的迁移产物生成阶段。

package/skills/agent-builder/references/multi-agent/graph-structure.md

@@ -1,12 +0,0 @@
-# Deprecated: graph-structure
-
-本文件只保留历史引用兼容，不再承载旧图读取规则。
-
-读取、解释或迁移 MULTI_AGENT 时，必须改读：
-
-1. `overview.md`
-2. `workflow.md`
-3. `graph-spec.md`
-
-迁移到 CHAT_FLOW 时继续读取 `migration/principles.md`，再按大小读取 `migration/small.md` 或
-`migration/large.md`。

package/skills/agent-builder/references/multi-agent/migrate-to-chatflow.md

@@ -1,13 +0,0 @@
-# Deprecated: migrate-to-chatflow
-
-本文件只保留历史引用兼容，不再承载迁移规则。
-
-旧 MULTI_AGENT 迁移到 CHAT_FLOW 时，必须按以下顺序读取：
-
-1. `overview.md`
-2. `workflow.md`
-3. `graph-spec.md`
-4. `migration/principles.md`
-5. `migration/small.md` 或 `migration/large.md`
-
-不要继续按旧版 `migrate-to-chatflow.md` 生成迁移计划。