@shulex/cxclawctl 0.1.2 → 0.1.4

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

@@ -1,350 +0,0 @@
-# AGENT
-
-## 功能概述
-
-让 LLM 承担一个局部、开放式的问题处理职责：在多轮上下文中综合判断、自主选择已绑定工具、解释
-非结构化结果，并在当前职责确实结束后决定是否把流程交给另一个明确的下游职责。
-
-AGENT 是运行时 LLM 节点，不是通用流程容器，也不是给每个简单任务套一层 prompt 后再用
-`next_steps` 跳转的流程节点。适合 AGENT 的职责通常至少满足一项：
-
-- 需要多轮对话才能诊断、澄清或收敛结果，当前节点会直接回复并继续等待用户；
-- 是否调用某个工具、调用顺序或调用时机必须由模型结合自然语言上下文决定；
-- 工具、知识或用户输入是非结构化的，需要模型解释后继续处理；
-- 当前职责有一个或多个真正不同的后续业务动作，且必须由模型根据不断变化的上下文决定是否以及何时交接。
-
-以下职责已有专用节点，不使用 AGENT：
-
-- 只把自然语言分到有限类别：`INTENT`；
-- 流程必须取得客户字段、附件、选择或确认后才能继续：`QUESTION`；
-- 只发送模板、固定话术或生成一段对客回复：`REPLY`；
-- 调用一个确定工具并按状态/字段分支：`TOOL` 加 actionStatus 出边或 `IF_ELSE`；
-- 对结构化值做条件判断：`IF_ELSE`；生成内部文本：`LLM`；知识检索并回答：`RAG_REPLY`；
-- 确定结束或转人工：`FINISH` / `TRANSFER_TO_HUMAN`。
-
-选择 AGENT 时必须写出“为什么不能由上述专用节点表达”。仅因为旧图中的节点类型是 Agent、旧 PE
-很长、当前步骤需要 LLM，或步骤完成后还有下游，都不能证明应创建 AGENT。
-
-## 创建方式
-
-```json
-{
-  "key": "troubleshoot_device",
-  "type": "agent",
-  "prompt": "Diagnose the device issue over multiple turns, use the bound diagnostic tool when needed, and hand off only after troubleshooting reaches an explicit outcome.",
-  "plugins": [12345],
-  "ai_field_ids": [2744],
-  "enable_knowledge_base": true,
-  "knowledge_directory_ids": [32951],
-  "knowledge_keyword_ids": [11, 13],
-  "knowledge_keyword_selector": ["SYSTEM", "Custom", 301],
-  "next_steps": [
-    {
-      "id": "START_REPLACEMENT",
-      "title": "start_replacement",
-      "prompt": "Use only after troubleshooting is exhausted, replacement is eligible, and the customer has chosen replacement so the downstream flow must collect replacement details."
-    },
-    {
-      "id": "FINISH_RESOLVED",
-      "title": "finish_resolved",
-      "prompt": "Use only after the customer confirms that the issue is resolved and the downstream node only needs to close the flow.",
-      "params": [
-        {"name": "resolution", "type": "string", "describe": "Short description of the confirmed resolution", "required": false}
-      ]
-    }
-  ]
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| prompt | source 阶段唯一需要 AI 编写的提示词；builder 会写入完整 graph 的 `displayPrompt`，并派生运行时 `prompt` |
-| plugins / usedPlugins | 可调用工具 id 数组，例如 `[12345]` |
-| ai_field_ids | prompt 可用的变量系统字段 id 数组；完整 graph 字段为 `aiFieldIds` |
-| enable_kb / kb_dirs | 是否启用知识库和目录 |
-| knowledge_keyword_ids | knowledgeKeywordIds；固定隔离关键词 ID 数组 |
-| knowledge_keyword_selector | knowledgeKeywordSelector；变量选择器，运行时值为隔离关键词名称或名称数组；按变量实际来源选择 `SYSTEM` / `TOOL` / `EXTRACT` / `CODE` / `LLM` / `AGENT` / `HUMAN_REVIEW` |
-| max_rounds | 最大轮数，默认 10 |
-| max_rounds_exceeded_action | `TRANSFER_TO_HUMAN`（默认）或 `FORCE_NEXT_STEP`；后者仅在存在可用的流程内分支工具时有意义 |
-| use_long_memory | 是否把长记忆注入模型上下文，默认 false |
-| disable_prev_node_results | 是否不注入前序节点结果，默认 false |
-| next_steps | 仅在 AGENT 需要由模型决定是否/何时交接给明确下游职责时配置；只生成内部流转工具，不是业务工具或转人工工具；source JSON 必须写对象数组，不使用字符串简写 |
-| next_steps[].id | 必填，出边 handle，edges 的 `on` 使用该值 |
-| next_steps[].title | 必填，分支名；推荐使用小写字母、数字和下划线，例如 `accept_wait` |
-| next_steps[].prompt | 必填，内部流转工具描述，用来告诉 LLM 何时选择该分支 |
-| next_steps[].params | 可选，流转时让 LLM 补充的参数，支持 string / number / boolean |
-| next_steps[].params[].name | 有 params 时必填；同一 AGENT 内必须唯一，格式 `/^(?!\d)[A-Za-z0-9_-]{1,64}$/` |
-| next_steps[].params[].type | 有 params 时必填；string / number / boolean |
-| next_steps[].params[].describe | 有 params 时必填；说明该参数业务含义 |
-| next_steps[].params[].required | 可选，默认 false；控制 LLM 调用内部流转工具时该参数是否必填 |
-
-## Prompt Contract
-
-AGENT 的提示词必须写成可执行指令，不写成普通客服话术。默认使用固定结构：
-
-```text
-# Role
-<当前节点的业务角色，只描述这个节点负责什么>
-
-# Task
-<本节点要完成的判断、工具调用、信息解释或多轮对话任务>
-
-# Constraints
-- <必须遵守的业务边界>
-- <不能做的动作，例如不要直接退款、不要承诺未确认事项>
-
-# Tools And Routing
-- <何时调用哪个真实工具；工具必须已绑定在 plugins 中>
-- <何时调用 transfer_to_<step>_node 进入 next_steps 分支>
-- <何时调用真实转人工工具；不要把转人工写成 next_steps 分支>
-```
-## 变量引用优先级
-
-用户说“引用某变量/某内容”时，先确认它是否其实是上游工具的出参字段：
-
-1. 读取工具定义和实际返回 schema，确认 `TOOL` selector 的完整 path；
-2. 若不是工具出参，再查 `list-ai-fields`，选择已有 `SYSTEM` 变量字段；
-3. 若仍不存在，再用 `VARIABLE_PROCESS` 抽取/赋值到 SYSTEM；
-4. AGENT/REPLY prompt 内部变量引用时需说清楚来源(system、tool、node..)。
-
-如果节点不需要工具或下游选择，省略 `# Tools And Routing`。如果只有固定回复、模板、转人工、
-finish、字段判断或工具 status 路由，不要创建 AGENT；改用 REPLY、TRANSFER_TO_HUMAN、IF_ELSE、
-TOOL、INTENT 或 QUESTION。
-
-### next_steps And Transfer Tools
-
-`next_steps` 只表达 AGENT 可以选择的**流程内职责交接**。运行时会把每个 next step 生成为
-`transfer_to_<step>_node` 内部流转工具；语义是“结束当前 AGENT，并让另一个节点开始执行一个明确的
-后续业务动作”。它不是任务清单、执行顺序或通用的“完成后下一步”，不能因为当前简单任务后面还有节点，
-就为 AGENT 创建 `success`、`done`、`continue`、`next` 一类 next step。
-
-创建每个 `next_steps[]` 前必须同时满足：
-
-1. 当前职责本身符合 AGENT 的准入条件，而不是可由 INTENT、QUESTION、REPLY、TOOL、IF_ELSE 或 LLM 表达；
-2. AGENT 在当前节点内可能经历多轮回复或自主工具调用，交接时机需要由模型判断；
-3. 选择该 step 后确实有另一个节点要执行独立动作，例如开始收集 replacement 信息、进入退款处理子流程或结束已解决会话；
-4. step 的选择条件来自非结构化上下文；若由工具 status、布尔值、枚举或固定顺序唯一决定，应在图上结构化路由。
-
-若 AGENT 合理存在，但完成后永远进入同一个确定下游，使用一个 `SOURCE` 出边，不创建单个 next step。
-若 AGENT 不满足准入条件，先替换成专用节点，再使用该节点自己的出边语义。
-
-常见拆分如下：
-
-| 业务需求 | 正确表达 | 不要这样建 |
-|---|---|---|
-| 判断客户消息属于退款、换货还是其他 | `INTENT -> 各意图下游` | `AGENT + refund/replacement/other next_steps` |
-| 必须取得订单号后继续 | `QUESTION(VARIABLE) -> SOURCE` | `AGENT 询问订单号 + got_order next_step` |
-| 发送政策说明后进入确定下游 | `REPLY -> SOURCE` | `AGENT 发送话术 + continue next_step` |
-| 调工具后按明确状态分支 | `TOOL -> actionStatus` 或 `TOOL -> IF_ELSE` | `AGENT 调工具 + success/fail next_steps` |
-| 多轮排障后，由模型确认应开始 replacement | `AGENT -> start_replacement next_step` | 把排障中的每个小步骤都拆成 next step |
-
-真正的转人工是 AGENT 可调用的 `TRANSFER_TO_HUMAN` 系统动作。需要模型结合上下文决定是否升级时，
-在 `displayPrompt` 中插入 `transferHuman` LibraryBlock；该块会转换成运行时转人工指令，联网 compile
-再从 Chatflow 专用插件目录按 `type=TRANSFER_TO_HUMAN` 找到当前项目的真实 ID 并放入 `usedPlugins`。
-`transferToHumans` 仍保持空数组。模型执行后，AGENT 节点结束并输出 `TRANSFER` / handoff
-状态，不再按 `next_steps` 选择下游节点。达到 `max_rounds` 后仍未完成时，AGENT 也会按超轮兜底转人工
-结束，不会自动选择某个 next step。
-
-因此有三种出口，必须分清：
-
-| 出口 | 配置位置 | 运行语义 |
-|---|---|---|
-| 流程内分支 | `next_steps` + 对应边 | 生成 `transfer_to_<step>_node` 内部工具，进入下游节点 |
-| AGENT 自主转人工 | `displayPrompt` 中的 `transferHuman` LibraryBlock + `usedPlugins` 中真实 `TRANSFER_TO_HUMAN` 插件 ID | AGENT 输出 transfer / handoff，流程结束到人工 |
-| 确定性转人工 | 独立 `TRANSFER_TO_HUMAN` 节点或 `$transfer` | 上游结构化分支直接转人工 |
-
-只有“模型完成当前开放式职责后，需要触发某个明确的后续业务动作，且交接条件必须由模型判断”才放进 `next_steps`。
-如果分支结果是转人工，优先让 AGENT
-调用真实转人工工具；如果转人工条件是确定性的，直接在画布上接 `TRANSFER_TO_HUMAN` 或 `$transfer`。
-判断标准不是名字里有没有 `transfer`：`transfer_to_<step>_node` 是 nextStep 内部跳转工具；
-`TRANSFER_TO_HUMAN` 才是人工接管工具。
-
-AGENT 提示词里不能只写“根据上下文处理问题”“你是客服”这类泛化指令。每个 AGENT 都必须说明：
-输入来源、可调用工具、何时回复用户、何时等待用户、何时选择哪个 `next_steps`。选择 AGENT
-时要说明为什么该职责不能被结构化节点替代。
-
-### Prompt / displayPrompt
-
-source JSON 阶段只维护一个 `prompt` 字段，减少上下文和双写错误。builder 编译完整 graph 时会保留两个字段：
-
-- `agentData.displayPrompt`：等于 source `prompt`，给前端编辑器和客户审阅使用，可包含 `LibraryBlock` chip。
-- `agentData.prompt`：由 `displayPrompt` 转换得到，给 chatflow 运行时模型使用；后端 AGENT 执行只读取这个字段，不把 `displayPrompt` 额外注入模型上下文。
-
-模型基于节点职责决定是否引用某个变量或工具；不要为了“看起来完整”强行插入或绑定。只有模型决定提示词正文
-需要展示该变量或工具引用时，才在 source `prompt` 中使用前端可识别的 `LibraryBlock`；前端会把它渲染成变量块 / 工具块，
-而不是普通文本。变量作为运行时上下文注入但提示词正文不需要出现引用时，
-可以只通过 `ai_field_ids` / `aiFieldIds` 表现为提示词下方的变量绑定区，例如 `Platform ×`。
-
-维护已有 AGENT 的提示词时，优先从 inspect 得到的 `displayPrompt` 确认当前客户可见文本；在用户确认修改前，按
-整体输出规则展示受影响片段的 `diff`，清楚对比原指令与拟更新内容。
-
-### 可执行 LibraryBlock
-
-模型需要结合上下文决定是否执行模板、转人工或普通工具，且该职责需要留在多轮 AGENT 内时，必须在
-source `prompt` 中插入以下块，不能只写“调用 xxx”的普通文字。
-
-变量块：
-
-```text
-{#LibraryBlock id=127609 type=variable name="c_order_number" #}
-```
-
-模板回复块；`id` 是具体模板内容 ID，不是 `TEMPLATE_REPLY` 系统插件 ID：
-
-```text
-{#LibraryBlock id=1769 type=tool name=template_reply tool=template_reply #}
-```
-
-普通业务工具块：
-
-```text
-{#LibraryBlock id=31893 type=tool name=Logistics_Anomaly_Register tool=Logistics_Anomaly_Register #}
-```
-
-转人工块；`name` 必须是业务要求的精确 reason，`tool_id` 是当前块的唯一数字实例 ID，不是插件 ID。
-同一 AGENT 内每个转人工块都必须不同，不要复制示例 ID：
-
-```text
-{#LibraryBlock tool_id=1790057523341 type=transferHuman name="want refund" transferType=INSTRUCTION action=NOT_REPLY templateContent="" templateId= #}
-```
-
-块前后仍要写完整执行过程：触发条件、首次调用、调用后是否等待、客户下一轮接受/坚持时分别做什么，
-不能只把块孤立地贴进 prompt。例如：
-
-```text
-## Refund request
-If the customer requests a refund and no longer wants a replacement, first call:
-
-{#LibraryBlock id=1769 type=tool name=template_reply tool=template_reply #}
-
-After the template is sent, wait for the customer's next reply.
-
-- If the customer accepts continuing with replacement, continue the replacement flow.
-- If the customer still insists on a refund, use:
-
-{#LibraryBlock tool_id=1790057523342 type=transferHuman name="want refund" transferType=INSTRUCTION action=NOT_REPLY templateContent="" templateId= #}
-```
-
-builder 会解析并严格校验这些块：
-
-- 模板块的 `id` 保持具体模板内容 ID；联网 compile 从 `/api_v2/gpt/chatflow/queryPlugin`
-  (`forAgentNode=true`) 按 `type=TEMPLATE_REPLY` 解析真实系统插件 ID，并追加到 `usedPlugins`。
-- 普通工具块自动把块内工具 ID 追加到 `usedPlugins`，保留已有工具并去重。
-- 转人工块的 `tool_id` 只标识 PE 块实例；联网 compile 按 `type=TRANSFER_TO_HUMAN` 解析真实插件 ID
-  并追加到 `usedPlugins`，`transferToHumans` 仍为空数组。
-- 编译后的 `displayPrompt` 保留 LibraryBlock；runtime `prompt` 自动转换成可执行文字，两者必须同步。
-- 转人工 runtime 名称固定为 `Transfer_To_Agent`，大小写与前端 `formatChatflowAgentPrompt` 一致。
-- LibraryBlock 必须保持单行；PE 的 `/\{#LibraryBlock\s+(.+?)\s*#\}/g` 不会解析跨行属性。
-- 普通工具块的 `id` 必须存在于 `usedPlugins` 和当前 Chatflow 插件目录，`name` / `tool` 必须与该
-  plugin 的真实名称一致。模板回复和转人工则按系统 plugin type 双向对账：有块必须有对应
-  `usedPlugins`，绑定了对应系统 plugin 也必须有块，避免 PE chip 与运行时工具能力只保留一边。
-- 联网 compile 新建这些系统动作时必须从 Chatflow 插件目录取得真实类型绑定，目录不可用或缺少类型都会
-  失败；普通 validate / update / publish 的模板或插件元数据查询暂时不可用时只告警并跳过该项远端校验，
-  查询成功后确认资源不存在、模板状态不是 `ENABLED` 或对应系统插件类型未绑定时才校验失败。
-- PE 的 LibraryBlock 属性没有通用转义/解码合同。自动迁移不得把包含 `#}`、双引号、反斜杠、换行/
-  控制字符，或形如 `key=` 的独立属性 token 写进 `name` / reason；这些值无法在 PE 中无损表达，必须改用
-  独立节点或先调整值。普通空格、Unicode 和不构成 `#}` 的单独 `#` 可以保留。
-
-提示词正文渲染和运行时绑定是两层，不要混为一谈：
-
-| 层 | 字段/格式 | 作用 |
-|---|---|---|
-| 提示词正文渲染 | variable / tool / template_reply / transferHuman LibraryBlock | 让前端显示可执行块，并让 builder 派生 runtime prompt |
-| 运行时绑定 | `ai_field_ids` / `plugins`，完整 graph 为 `aiFieldIds` / `usedPlugins` | 让 AGENT 运行时能读取变量、调用工具 |
-
-因此，提示词正文插入变量块后仍应检查对应 `ai_field_ids`；工具和模板的 plugin 绑定由 builder 自动补齐，
-validate 会再次对账。模型决定提示词正文需要显示变量/工具/模板/转人工引用时，不要只写纯文本名称；
-纯文本描述不会变成可执行动作。
-
-只有在提示词正文确实需要引用某个变量或可执行动作时，才用 `{#LibraryBlock ... #}` 表达；如果不需要
-在提示词正文中引用，只做运行时上下文注入，可只保留 `ai_field_ids` 变量绑定。找不到具体模板内容 ID、
-工具 ID 或转人工 reason 时，记录缺口并判断是否补绑定、改写为独立节点或提问；禁止把任何猜测或系统
-插件 ID 写成模板块的 `id`。
-
-用户明确给出必须逐字保留的固定完整话术时，没有模板 ID 也不得概括或删段。节点选择先由整体流程决定；
-如果最终由 AGENT 承载，就把完整话术逐段写入 `prompt`，并明确发送后的等待/继续行为。不要因为发现固定
-话术就在本节点文档中把流程强制改成 REPLY；其他承载节点按各自节点合同写入实际 PE/文本字段。
-
-## Edges
-
-- 无 `next_steps`：仅 `SOURCE`。
-- 有 `next_steps`：每个 step id 一条边；运行时 LLM 调用对应内部流转工具后，按 step id 路由。
-- `next_steps` 的边必须指向流程内节点；不要把人工接管写成某个 next step 再接转人工。
-- `next_steps[].params` 会作为 AGENT 输出参数传给被选中的下游路径；下游用 `["AGENT", "<this_node_id>", "<param_name>"]` 引用。
-- AGENT 没有 `next_steps` 且没有 `SOURCE` 出边时，validator 只给 warning；除非明确设计为终端对话节点，否则应连出 `SOURCE` 或配置 `next_steps`。
-
-模型看到的分支工具名是 `transfer_to_<分支名>_node`。例如：
-
-```text
-next_steps[].title = accept_wait
-模型调用的工具名 = transfer_to_accept_wait_node
-```
-
-### Runtime Workflow
-
-1. 进入 AGENT 后，模型会收到当前会话、选中的 `ai_field_ids`、可用业务工具，以及 `next_steps` 生成的分支工具。未开启 `disable_prev_node_results` 时，还会带上前序节点结果。
-2. 模型调用普通业务工具时，Chatflow 先执行工具，再回到同一个 AGENT。模型会结合工具结果继续调用其他工具、回复用户或选择下一步；普通工具执行成功不代表节点已经完成。
-3. 模型直接回复文本而没有调用工具时，本轮回复发送给用户，流程停在当前 AGENT 等待下一条用户消息。用户继续回复后仍进入当前 AGENT。
-4. 只有模型调用 `transfer_to_<分支名>_node`，当前 AGENT 才结束并进入对应下游节点。系统根据该 `next_steps[].id` 选择出边，不根据提示词文本猜测分支。
-5. 分支工具带有 `params` 时，模型调用工具时填写的参数会随该分支输出，下游节点可通过 AGENT selector 引用。
-6. 模型调用真实转人工工具时，AGENT 直接输出 transfer/handoff 并结束到人工，不走 `next_steps`。
-7. `max_rounds` 统计 AGENT 回复用户并等待下一轮输入的次数，不统计节点内部连续调用普通业务工具的次数。达到上限时，默认按超轮转人工结束；只有配置 `FORCE_NEXT_STEP` 且运行时可用流程内分支工具时，模型才会被要求选择一个 next step。无 next step 时该配置会退回转人工。
-
-只有工具结果是非结构化的、必须由模型解释，而且 AGENT 本身也符合准入条件时，才把查询工具放入
-`plugins`，并按需要配置 `next_steps`。工具已有明确 actionStatus，或结果字段可确定判断时，使用独立
-`TOOL` 加状态边 / `IF_ELSE`；不要为了路由方便把确定性工具调用塞进 AGENT。
-
-## Resource Dependencies
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-plugins --pretty
-npx --yes @shulex/cxclawctl@latest api list-agent-ai-fields --pretty
-```
-
-`ai_field_ids` 只能从 `list-agent-ai-fields` 选择；该命令与前端 Agent 字段范围校验一致。`list-ai-fields` 是 Chatflow 画布的 SYSTEM selector / Prompt 字段接口，不能替代 Agent 范围校验。字段服务偶发不可用时可以先不用 `ai_field_ids`，或复用已有 graph 中已确认的字段 id；不要把字段服务错误当成节点配置错误。启用知识库前需要确认目录 id。
-
-## 限制
-
-- 使用 version 2。
-- `usedPlugins` 必须是工具 id 数组，例如 `[12345]`，不要写成 `[{"id": 12345}]`。
-- `aiFieldIds` 必须是变量系统字段 id 数组，例如 `[2744]`。
-- `enable_kb=true` 时通常配置 `kb_dirs`；未配置目录时没有可检索范围。固定隔离关键词使用 `knowledgeKeywordIds`，动态隔离关键词使用 `knowledgeKeywordSelector`。
-- `knowledgeKeywordIds` 只能填 `kb-builder` 查询到的数字 ID；`knowledgeKeywordSelector` 的运行时值必须是关键词名称或名称数组，不要填关键词 ID。
-- `knowledgeKeywordSelector` 必须引用真实存在且位于 AGENT 上游路径的变量/节点输出；模型根据关键词来源自动选择 selector 类型。
-- `knowledgeKeywordIds` 与 `knowledgeKeywordSelector` 默认互斥；后端合并语义未明确时不要同时配置。
-- 完整 graph 中 `prompt` 和 `displayPrompt` 都必须非空；source 阶段只写一个 `prompt`，由 builder 派生完整 graph 的两个字段。
-- 需要上游节点输出稳定进入 prompt 时，先用 VARIABLE_PROCESS 赋值到 SYSTEM 变量系统字段，再在 `ai_field_ids` 引用该字段。
-- 后端会把 `ai_field_ids` 对应字段作为额外系统上下文注入；上游节点结果也可能作为历史节点结果注入，但不要把它当成稳定 prompt 变量。
-- `transferToHumans` 必须为空数组；不要用它配置 AGENT 节点。需要模型结合上下文决定升级时，在
-  `displayPrompt` 使用标准 `transferHuman` LibraryBlock，并让联网 compiler 按类型把隐藏的
-  `TRANSFER_TO_HUMAN` 系统插件真实 ID 绑定到 `usedPlugins`；不要手写或复用旧 Multi-Agent 插件 ID。
-  确定性转人工仍使用独立 `TRANSFER_TO_HUMAN` 节点或 `$transfer`。
-- 不要把多个业务阶段机械映射成多个 AGENT 后再用边串联；每个 AGENT 都必须有不可结构化替代的理由。
-- 迁移或重建时，来源流程中的一个 Agent 节点、一条节点连接或一句“切换到其他 Agent”指令，都不能直接映射为目标 AGENT 或 `next_steps`；必须按目标职责重新通过准入检查。
-- 如果真实外部工具的执行结果有明确 actionStatus 分支，优先拆成独立 TOOL 节点；只有需要 LLM 自主选择是否调用工具时，才放入 `plugins`。
-- 如果 AGENT 后面只是固定流转、模板回复、finish 或转人工，改用结构化节点；不要把这些动作写进 prompt 让模型执行。
-- AGENT 经准入后若确需模型选择多个流程内下游，必须用 `next_steps`，不能多条 `SOURCE` 出边。
-- `next_steps` 只表示流程内下游；转人工不要作为 `next_steps` 项。
-- 每个 `next_steps[]` 都必须有非空 `id`、`title`、`prompt`，并且必须连出对应边。
-- `next_steps[].title` 推荐使用小写下划线格式，例如 `accept_wait`；提示词引用该分支时写完整工具名 `transfer_to_<title>_node`。历史流程中已有其他命名格式时，只要前端必填项和分支连线校验通过，也可以保留。
-- `next_steps[].prompt` 应描述选择该分支的业务条件，不要只重复 `title`。
-- 有 `params` 时，每个参数都必须写清楚 `name`、`type`、`describe`。
-- `params[].name` 是下游变量 selector 的第三段，必须稳定且唯一。
-
-## Common Mistakes
-
-- prompt 里写“调用某工具”，但 `plugins` 没有真实工具 id。
-- 手写或复用旧 Multi-Agent 的 hidden/system 插件 ID；目标 Chatflow 的 `TEMPLATE_REPLY` /
-  `TRANSFER_TO_HUMAN` ID 必须由联网 compiler 通过插件类型解析后写入 `usedPlugins`。
-- 用 AGENT 承载本可由 TOOL actionStatus、IF_ELSE、QUESTION、REPLY 或 TRANSFER_TO_HUMAN 表达的确定性流程。
-- 为了复刻已有节点数量，把多个业务阶段一对一迁成 AGENT。
-- 给 AGENT 一个简单的一次性任务，再创建 `success` / `done` / `continue` next step 跳到下一节点。
-- 想在 prompt 稳定使用上游输出，却没有先赋值到变量系统字段。
-- `usedPlugins` 写成对象数组，导致前端调用工具显示 `[object Object]`。
-- 把模板回复、转人工、业务工具只写成普通 prompt 文字，没有插入标准 LibraryBlock；或把本可确定执行的动作藏在 AGENT，而不拆成结构化节点。
-- 把转人工配置成 `next_steps` 分支，例如 `need_human` 后再接 `$transfer`。
-- 已确认需要由 AGENT 选择多个职责交接分支，却没有配置 `next_steps`。
-- `next_steps` 用字符串简写，导致没有 `prompt`，前端发布校验会失败。
-- 下游引用了未定义的 `next_steps[].params[].name`。

package/skills/agent-builder/references/chatflow/nodes/business-track.md

@@ -1,43 +0,0 @@
-# BUSINESS_TRACK
-
-## 功能概述
-
-发送一个或多个业务追踪事件，不向客户回复、不等待输入，也不改变业务判断。执行完成后沿唯一 `SOURCE`
-出边继续。适合在已确认的业务里程碑记录分析/归因事件；不要用它代替 TOOL、条件判断或用户可见回复。
-
-## 创建方式
-
-```json
-{
-  "key": "track_order_lookup",
-  "type": "business_track",
-  "trace_events": ["order_lookup_started", "after_sales_flow"]
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| trace_events | 非空业务事件编码数组；每一项必须是非空字符串 |
-
-## Edges
-
-仅 `SOURCE` 单出边。通常把它放在需要记录的业务动作之前或之后，并明确记录事件对应的阶段。
-
-## Resource Dependencies
-
-事件编码应来自已确认的业务埋点口径；不因名称相似臆造新的编码。
-
-## 限制
-
-- 必须有入边和 `SOURCE` 出边。
-- 不发送客户消息，也不等待客户输入。
-- 不携带变量 selector；事件码是静态业务配置。
-- 不用它作为“看起来有动作”的占位节点；没有确认的追踪需求时不新增。
-
-## Common Mistakes
-
-- 把用户回复、工具调用或状态判断塞进追踪节点。
-- 只写空数组或空事件字符串。
-- 将追踪节点作为终点，导致后续业务处理断开。

package/skills/agent-builder/references/chatflow/nodes/code.md

@@ -1,157 +0,0 @@
-# CODE
-
-## 功能概述
-
-执行少量确定性数据转换。不要用它承载业务 prompt、复杂流程或外部接口调用。
-
-## CODE 节点使用方法
-
-适合字段标准化、文本拆分/合并、日期/数字转换、从已存在结构化输入提取稳定字段、或者做字段的类型转换，更换变量名等。
-
-```json
-{
-  "key": "normalize_platform", "type": "code",
-  "inputs": [{"field_name": "raw", "variable_selector": {"tool": "lookup", "path": ["platform"]}}],
-  "source_code": "value = str(inputs.raw).strip().lower()\nreturn {'platform': value}",
-  "outputs": [{"field_name": "platform", "field_type": "String"}]
-}
-```
-
-声明 inputs/outputs；所有路径都 `return`；只做纯计算，不访问网络/文件，不写长循环；异常数据返回空值/false/说明字符串交给下游判断。不要在 CODE 内写整段业务流程。chatflow 会把 `sourceCode` 包装成一个内部函数执行，函数体里已存在局部变量 `inputs`。
-
-CODE 只处理已经存在的上游值。写代码前先确认每个 input 的 selector 和每个 output 的下游用途；缺少 input 来源时先用 `QUESTION(VARIABLE)`、`VARIABLE_PROCESS` 或 TOOL 补齐，不要在代码里编造默认业务值。
-
-## 创建方式
-
-```json
-{
-  "key": "normalize_order",
-  "type": "code",
-  "inputs": [
-    {"field_name": "order_no", "variable_selector": {"system": {"category": "Order", "path": [3248, 3249]}}}
-  ],
-  "source_code": "return {\"normalized\": str(inputs.order_no).strip()}",
-  "outputs": [
-    {"field_name": "normalized", "field_type": "String"}
-  ]
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| inputs[].field_name / fieldName | 输入变量名；编译后完整 graph 使用 `fieldName` |
-| inputs[].variable_selector / variableSelector | 输入来源；编译后完整 graph 使用 `variableSelector` |
-| source_code / sourceCode | Python 函数体代码；编译后完整 graph 使用 `sourceCode`，运行时已有 `inputs` 局部变量 |
-| outputs[].field_name / fieldName | 输出名；编译后完整 graph 使用 `fieldName` |
-| outputs[].field_type / fieldType | `String` / `Number` / `Boolean` / `Object` / `Array`；编译后完整 graph 使用 `fieldType` |
-
-## Input / Output 引用规则
-
-CODE 的 input 是对上游 selector 的命名包装。运行时会先逐个解析 `inputs[].variableSelector`，再把结果组成顶层 `inputs` 字典；`source_code` 内优先通过 `inputs.<field_name>` 访问：
-
-```json
-{
-  "key": "build_refund_payload",
-  "type": "code",
-  "inputs": [
-    {"field_name": "order_id", "variable_selector": {"system": {"category": "Order", "path": [3248, 3249]}}},
-    {"field_name": "tool_status", "variable_selector": {"tool_status": "lookup_order"}},
-    {"field_name": "items", "variable_selector": {"tool": "lookup_order", "path": ["order", "items"]}}
-  ],
-  "source_code": "items = inputs.items if isinstance(inputs.items, list) else []\nreturn {\"item_count\": len(items), \"has_items\": len(items) > 0}",
-  "outputs": [
-    {"field_name": "item_count", "field_type": "Number"},
-    {"field_name": "has_items", "field_type": "Boolean"}
-  ]
-}
-```
-
-下游 IF_ELSE / TOOL 引用 CODE 输出时，只能引用 `outputs[].field_name`。CODE 节点运行成功后写入的节点输出形态是：
-
-```json
-{
-  "exec_result": {"<fieldName>": "<assembled value>"},
-  "stdout": "<print output or null>"
-}
-```
-
-变量选择器的 `CODE` 分支只读取 `exec_result`，不读取 `stdout`。
-
-```json
-{"variableSelector": {"code": "build_refund_payload", "field": "has_items"}}
-```
-
-source 简写会编译为完整 selector：
-
-```json
-["CODE", "<code_node_id>", "has_items"]
-```
-
-运行时只支持完整 selector 写成 `["CODE", "<code_node_id>"]` 或 `["CODE", "<code_node_id>", "fieldName"]`。IF_ELSE / TOOL 入参需要具体字段时应使用三段式。不能引用代码里的临时变量、局部对象路径或未声明字段，也不能写 `["CODE", node_id, "obj", "field"]`。需要输出对象/数组时，将整个对象声明为一个 output；若下游必须判断对象内部字段，优先在 CODE 中拆成稳定的标量 outputs。
-
-CODE input 的 selector 同样必须引用当前 CODE 的上游 predecessor。比如要整理工具返回数组，图上必须先有 `TOOL -> CODE`，然后 CODE input 才能引用该 TOOL 输出；不能跨图引用未连通工具。
-
-## Edges
-
-通常 `SOURCE`；作为终止转换节点时可无出边。
-
-## Resource Dependencies
-
-输入引用变量系统字段或上游节点时，先确认对应 id / key。
-
-## 输出映射规则
-
-`return` 的值会按 `outputs` 组装到 `exec_result`：
-
-- `return dict`：按 `outputs[].fieldName` 取同名 key；缺失 key 输出 `None`；多余 key 会被忽略。
-- `return list/tuple`：按 `outputs` 顺序一一映射，长度必须和 output 数量完全一致。
-- 单 output 时可以直接 `return` 标量，运行时会自动包装成 `{fieldName: value}`。
-- 多 output 时不能返回标量。
-- 没有 output 的 CODE 配置会被校验拒绝；不要写“只 print 不 return”的代码节点。
-- 输出类型按 `fieldType` 校验：`String` 要求字符串但会把数字/布尔转成字符串；`Number` 接受 int/float 或可转数字字符串，但拒绝 bool；`Boolean` 必须是 bool；`Object` 必须是 dict；`Array` 必须是 list。
-- 输出值为 `None` 时允许通过类型校验，交给下游 IF_ELSE 用 `EMPTY` / `NOT_EMPTY` 或兜底逻辑处理。
-
-## 限制
-
-- 必须声明 `source_code` 和至少一个 output。
-- 每个 input 必须有 `field_name` 和 `variable_selector`。
-- `inputs[].variable_selector` 引用上游变量，支持 `SYSTEM`、`TOOL`、`EXTRACT`、`CODE`、`LLM`、`AGENT`、`HUMAN_REVIEW`。
-- 判断工具状态映射时可用 `["TOOL", "<tool_node_id>", "ACTION_STATUS_NAME"]`。
-- TOOL 出参 selector 会按真实 plugin `responseParam` 校验：object 字段可下钻，array 字段按叶子处理；需要遍历数组时，把整个数组作为 CODE input，在 `source_code` 内处理。
-- `AGENT` selector 只能引用当前上游路径已连通 nextStep 的 `params[].name`。
-- EXTRACT selector 第三段是 extract `id`，不是 `name`。
-- 每个 output 必须有 `field_name` 和 `field_type`。
-- input/output 的 `field_name` 必须是合法 Python 标识符，不能重复，不能使用 Python 关键字，不能使用 `inputs`、`__inputs__`、`__chatflow_entry__`、`__builtins__` 或 dunder 形态。
-- `source_code` 必须在所有执行路径上 `return`。
-- 输入通过 `inputs.<field_name>` 访问；不要直接使用裸变量名。
-- 使用 `inputs.<field_name>` 时，`field_name` 必须已经在 `inputs` 中声明；校验器会检查这种直接属性引用。动态下标访问不适合作为迁移默认写法，因为字段缺失更难在编译期暴露。
-- 返回值优先使用 dict，key 必须对应 output 的 `field_name`；单输出可返回标量，多输出必须返回 dict 或等长 list/tuple。
-- 返回 dict 不能包含下游要依赖但未在 `outputs` 声明的业务字段；validator 只允许下游引用 `outputs[].fieldName` 中存在的字段。
-- 需要给 TOOL 组装 object/array 入参时，必须先确认工具 `requestParam` 子字段结构；无法确认 item identity 或数组元素结构时输出 `open_questions`，不要在 CODE 中把多个不相关字段拼成可执行补发/退款参数。
-- 允许 import 只有 `math`、`json`、`datetime`、`re`。
-- 可用内置函数仅限常见纯函数：`len/range/enumerate/zip/min/max/sum/sorted/reversed/any/all/abs/round/map/filter/list/dict/set/tuple/str/int/float/bool/isinstance/print`。
-- 使用 `for` / `while` / `if` / 列表、字典、集合推导等普通控制流，但必须保证所有路径最终 `return`。
-- 禁止 `eval/exec/compile/__import__/open/input/globals/locals/vars/dir/getattr/setattr/delattr/breakpoint/type`。
-- 禁止 async/yield/class、dunder 访问、危险属性访问（如 `.sys/.codecs/.builtins/._os`）。
-- 运行时提供常见异常类（如 `Exception`、`ValueError`、`KeyError`、`IndexError`、`TypeError` 等），但迁移代码不要依赖异常驱动主流程；遇到异常业务数据时优先返回空数组、空对象、`false` 或说明性字符串，由下游节点判断。
-- 不要主动 `raise` 作为业务分支；主动抛错会使 CODE 节点失败，而不是进入某个下游 case。
-- 运行时有超时、代码长度、输入大小、stdout、结果大小、内存限制；不要生成大循环、大对象或大量日志。
-- 不调用外部 HTTP；外部调用用 TOOL 或 AGENT with tools。
-
-## Common Mistakes
-
-- 把 input 字段当成同名 Python 变量使用；输入应从 `inputs` 对象读取。
-- 用 extract `name` 当 selector 字段；应使用 extract `id`。
-- 用 CODE 写业务判断大流程。
-- 忘记声明输出字段。
-- 写 `result = {...}` 但没有 `return`。
-- `return {"status": ...}` 后下游引用 `code.status`，但 outputs 没有声明 `status`。
-- 以为可以引用 `["CODE", node_id, "obj", "field"]`；当前 CODE selector 只校验到 output 字段名，复杂对象内部字段应拆成单独 output。
-- 以为 CODE 可以直接读取全局变量、当前会话或工具完整结果；必须通过 `inputs` 显式传入。
-- 用 CODE 伪造缺失的订单、地址、商品数组、退款商品或工具状态；这些属于业务数据缺口，应询问用户或转人工。
-- 用 `raise Exception(...)` 表示业务分支；这会导致 CODE 执行失败，不会生成可供 IF_ELSE 判断的 output。
-- 依赖 `print` 结果给下游使用；下游 CODE selector 只读 `exec_result`，不读 `stdout`。
-- 用 `os/requests/pandas/open` 读文件或调接口。
-- 通过代码节点做网络请求、文件处理、长文本生成或复杂业务决策。

package/skills/agent-builder/references/chatflow/nodes/collect-order.md

@@ -1,47 +0,0 @@
-# COLLECT_ORDER
-
-## 功能概述
-
-订单号收集专用兼容节点，用于维护已有电商客服订单场景。该节点即将下线，新建 CHAT_FLOW 默认不要使用。
-
-新建订单号相关流程时，先确认变量系统是否已有订单号字段，再按业务合同组合：
-
-- 只需要向用户要订单号：`QUESTION(VARIABLE)`，变量选择订单号字段。
-- 已有订单号后要查订单或物流：订单查询 `TOOL`，工具 actionStatus 完整时直接按状态出边，否则接 `IF_ELSE` 判断结构化字段。
-- 需要模型多轮判断订单问题、解释工具结果或选择下一步：`QUESTION(VARIABLE)` -> `AGENT(next_steps)`，必要时把订单查询工具绑定到 AGENT。
-- 需要把上游结果稳定给 AGENT / REPLY prompt 使用：先用 `VARIABLE_PROCESS.assignments` 写入变量系统字段，再让下游通过 `ai_field_ids` 读取。
-
-## 创建方式
-
-```json
-{"key": "collect_order", "type": "collect_order", "max_rounds": 5}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| max_rounds | 最大追问轮数 |
-| collect_order_exception | 维护已有图时的异常回复数组；也接受 `collectOrderException`。每项含 `key`、`type=REPLY/TEMPLATE`、`reply` 或 `template_id` |
-
-## Edges
-
-通常 `SOURCE` 进入后续订单处理节点。
-
-## Resource Dependencies
-
-依赖项目启用订单相关变量系统字段。需要确认字段时查 `list-ai-fields`。
-
-## 限制
-
-- 仅用于维护已有图、复刻旧行为，或用户明确要求保留 `COLLECT_ORDER` 兼容节点。
-- 新建图默认使用 `QUESTION(VARIABLE)` 收集订单号，不使用本节点。
-- 失败路径通常由节点内部异常配置或后续兜底转人工处理。
-- 维护已有异常配置时，每个异常项如果 `type=TEMPLATE` 必须有 `templateId`；否则必须有非空 `reply`。
-- 和 QUESTION / AGENT 一样，运行时会等待用户输入；不要在图层手动画回环。
-
-## Common Mistakes
-
-- 新建图继续使用本节点，导致依赖即将下线能力。
-- 只因为字段叫订单号就选择本节点；新图应优先走变量系统字段 + QUESTION / TOOL / IF_ELSE / AGENT。
-- 在 source JSON 顶层写 `collectOrderException` 但没有放进 `config`，builder 不会自动识别。

package/skills/agent-builder/references/chatflow/nodes/finish.md

@@ -1,34 +0,0 @@
-# FINISH
-
-## 功能概述
-
-结束流程，不发送回复、不转人工。
-
-## 创建方式
-
-```json
-{"from": "final_reply", "to": "$finish"}
-```
-
-## 创建参数
-
-通常只通过 `$finish` 引用，不需要手写节点字段。
-
-## Edges
-
-- 必须有入边。
-- 无出边。
-
-## Resource Dependencies
-
-无。
-
-## 限制
-
-- 平台不强制 FINISH 唯一。
-- 默认使用单个共享 `$finish`，让终端路径汇聚，减少无意义终端节点。
-
-## Common Mistakes
-
-- 把需要先回复的终止路径直接连 `$finish`，导致用户收不到结束话术。
-- 误以为平台要求只能有一个 FINISH；这是推荐约定，不是硬校验。