@shulex/cxclawctl 0.1.2 → 0.1.4

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

@@ -1,259 +0,0 @@
-# CHAT_FLOW 图规范
-
-本文件描述 source JSON、边、全局校验和写回命令。节点字段细节看 `references/nodes/*.md`，节点选型看 `references/node-selection.md`。
-
-## Source JSON
-
-Agent 编写 source JSON，再用 CLI 编译成完整平台 `chatFlowGraph`。source 只放业务必要字段，节点 id、position、handle、默认 config、共享 `$finish` / `$transfer` 由 builder 补齐。
-
-```json
-{
-  "entry": "ask_platform",
-  "nodes": [
-    {
-      "key": "ask_platform",
-      "type": "question",
-      "mode": "USER_REPLY",
-      "question": "Please choose a platform.",
-      "replies": ["TikTok", "Amazon", "Shopify"]
-    },
-    {"key": "tiktok_reply", "type": "reply", "reply_type": "TEMPLATE", "template_id": 12345}
-  ],
-  "edges": [
-    {"from": "ask_platform", "on": "TikTok", "to": "tiktok_reply"},
-    {"from": "ask_platform", "on": "OTHER", "to": "$transfer"},
-    {"from": "tiktok_reply", "to": "$finish"}
-  ]
-}
-```
-
-## Node Keys And Titles
-
-- 每个节点必须有稳定 `key`，供 edges 引用。
-- `title` 可选，默认用 `key`；builder 会把空格、中文、`/` 等清洗成 ASCII。
-- `position` 可选；有明确坐标时保留，没有时自动布局。
-- source 里通常不写 `$start`、`$finish`、`$transfer` 节点本体，边里引用特殊 key 即可。
-
-## Node Types
-
-| type | 节点说明 |
-|------|----------|
-| `start` | `nodes/start.md`，通常省略，用顶层 `entry` 自动生成 |
-| `finish` / `$finish` | `nodes/finish.md` |
-| `reply` | `nodes/reply.md` |
-| `llm` | `nodes/llm.md` |
-| `question` | `nodes/question.md` |
-| `agent` | `nodes/agent.md` |
-| `intent` | `nodes/intent.md` |
-| `if_else` | `nodes/if-else.md` |
-| `tool` | `nodes/tool.md` |
-| `rag_reply` / `knowledge` | `nodes/rag-reply.md` |
-| `knowledge_reply` | `nodes/knowledge-reply.md`，仅已有图兼容 |
-| `transfer` / `$transfer` | `nodes/transfer-to-human.md` |
-| `collect_order` | `nodes/collect-order.md`，即将下线，仅存量兼容 |
-| `variable_process` | `nodes/variable-process.md` |
-| `code` | `nodes/code.md` |
-| `human_review` | `nodes/human-review.md` |
-| `sub_graph` | `nodes/sub-graph.md` |
-| `business_track` | `nodes/business-track.md` |
-| `variable_extract` | `nodes/variable-extract.md`，仅已有图兼容 |
-| `variable_assignment` | `nodes/variable-assignment.md`，仅已有图兼容 |
-
-## Edges
-
-边只写业务语义，不直接写底层 `sourceHandle`：
-
-```json
-{"from": "ask_platform", "on": "TikTok", "to": "tiktok_reply"}
-{"from": "intent", "on": "OTHER", "to": "$transfer"}
-{"from": "rag", "on": "LACK_KNOWLEDGE", "to": "$transfer"}
-{"from": "reply", "to": "$finish"}
-```
-
-`on` 会自动解析为 QUESTION reply id、INTENT id、IF_ELSE case id、AGENT nextStep id，或固定 handle：`SOURCE`、`OTHER`、`FALSE`、`TRUE`、`LACK_KNOWLEDGE`、`RESOLVED`、`UNRESOLVED`、`AGREE`、`REJECT`。
-
-必须显式连出的兜底边：
-
-- QUESTION(USER_REPLY)：所有 reply + `OTHER`
-- INTENT：所有 intent + `OTHER`
-- 流程图中的 `Y/N` 默认表示条件结果（Y=条件满足，N=条件不满足）.
-- IF_ELSE：所有 case + `FALSE`
-- RAG_REPLY：`TRUE` + `LACK_KNOWLEDGE`
-- KNOWLEDGE_REPLY：`RESOLVED` + `UNRESOLVED`
-- HUMAN_REVIEW approval：`AGREE` + `REJECT`
-
-## Variable Selector
-
-变量选择器是跨节点传递数据的数组协议。引用上游提取结果时，第三段必须是完整 graph 里的 extract `id`，不是 `name`。前端新建 extract 时用 `getUuid()` 生成该 `id`；source JSON 用 `alias` 给 builder 引用，compile 后会替换成 UUID。
-
-完整 graph 使用数组。SYSTEM selector 必须保留前端级联菜单的完整字段路径：
-
-```json
-["SYSTEM", "Custom", 123]
-["SYSTEM", "Order", 3248, 3249]
-["TOOL", "<tool_node_id>", "field", "subField"]
-["TOOL", "<tool_node_id>", "ACTION_STATUS_NAME"]
-["EXTRACT", "<extract_node_id>", "9f0a4b17-2a2c-48f3-8e8b-8a7a9b2d0f52"]
-["CODE", "<code_node_id>", "normalized_order_no"]
-["LLM", "<llm_node_id>", "text"]
-["LLM", "<llm_node_id>", "structured_output", "summary"]
-["AGENT", "<agent_node_id>", "reason"]
-["HUMAN_REVIEW", "<review_node_id>", "field_id"]
-["NODE", "<node_id>"]
-["SELF", "9f0a4b17-2a2c-48f3-8e8b-8a7a9b2d0f52"]
-```
-
-约束：
-
-- `SYSTEM` 第一段后依次是 `bizType` 和完整字段 id 路径。`OrderNumber(3249)` 位于 `OrderInformation(3248)` 下时，必须写 `["SYSTEM", "Order", 3248, 3249]`，不能省略父字段 id。
-- `EXTRACT` 用于 `VARIABLE_EXTRACT` / `VARIABLE_PROCESS` 的提取结果；第三段是提取项 `id`，通常是 UUID。
-- `CODE` 第三段是 code output `fieldName`。
-- `LLM` 只能引用 `text`（固定三段）或 `structured_output`。结构化结果的 selector 形如 `['LLM', node_id, 'structured_output', '<schema property>', ...]`，且上游 LLM 必须启用 `structuredOutput`。
-- `AGENT` 第三段是 `next_steps[].params[].name`，只在对应 nextStep 路由到当前下游路径后有值。
-- `HUMAN_REVIEW` 第三段是 fill 字段 `id`。
-- `NODE` 只用于 `VARIABLE_EXTRACT` / `VARIABLE_PROCESS` 的 `additional_data`，表示把上游节点完整输出补充给提取上下文；不要用于 TOOL 入参、IF_ELSE、CODE 输入。
-- `SELF` 只用于 `VARIABLE_PROCESS.assignments[].source`，引用本节点刚提取出的 extract `id`。
-- `TOOL` 的 `ACTION_STATUS_NAME` 只用于允许状态映射的字段：IF_ELSE、CODE 输入、HUMAN_REVIEW 变量模板。
-- 变量只能引用当前节点的上游节点输出，不要引用同级、下游或未连通节点。
-
-source JSON 可用简写，builder 会替换成真实节点 id：
-
-```json
-{"variableSelector": {"tool": "lookup_order", "field": "status"}}
-{"variableSelector": {"tool": "lookup_order", "path": ["order", "shipping_method_no"]}}
-{"variableSelector": {"tool_status": "lookup_order"}}
-{"variableSelector": {"code": "normalize_items", "field": "has_items"}}
-{"variableSelector": {"llm": "summarize_case", "field": "summary"}}
-{"variableSelector": {"node": "ask_order"}}
-{"variableSelector": {"extract": "extract_info", "alias": "order_no_value"}}
-{"variableSelector": {"system": {"category": "Custom", "path": [123]}}}
-{"variableSelector": {"system": {"category": "Order", "path": [3248, 3249]}}}
-```
-
-`list-ai-fields` 返回 Chatflow 画布可用的树形字段，用于 SYSTEM selector。source 的 `path` 必须从顶层字段开始逐级写到目标字段；不要只复制叶子字段的 `id`。
-
-AGENT 的 `ai_field_ids` 还要通过前端 Agent 范围校验，必须从 `list-agent-ai-fields` 选择。两个命令对应生产前端的两套字段数据源，不要混用。
-
-`queryAiFields` 背后依赖字段服务 `field/internal/list`，部分环境会短暂不可用并返回类似 `tars: Name does not resolve`。遇到这种错误时，不要把它判断为 graph schema 错误：
-
-- 不需要变量系统字段的新建 / 修改，可以继续 compile / validate；builder 会跳过字段存在性校验并输出 warning。
-- 需要精确绑定 `SYSTEM` selector 或 `ai_field_ids` 时，先使用已知字段 id、已有 graph 中的字段 id，或等字段服务恢复后重试。
-- 不要因为 `queryAiFields` 不可用就把变量写进 prompt。
-
-TOOL 单层出参可用 `field`；嵌套出参必须用从顶层开始的 `path` 数组，编译结果为 `["TOOL", node_id, "order", "shipping_method_no"]`。不要写点号字段 `"order.shipping_method_no"`，也不要加 `"output"` 中间层。
-
-提示词变量机制：
-
-- CHAT_FLOW 不感知 `metadata` 路径；所有节点都禁止写 `metadata.xxx`、`metadata.ai_fields.xxx` 或类似点号路径。变量系统字段在进入图后只通过 ai-fields 暴露，并由 `SYSTEM` selector 或 `ai_field_ids` 读取。
-- 如果还需要从 `AttachmentSummary` 等已有系统字段中二次提取，或对 TOOL / CODE / AGENT 输出做转换、赋值，使用 `VARIABLE_PROCESS`。
-- AGENT 和 `REPLY(PROMPT)` 的变量入口是变量系统字段：source 写 `ai_field_ids`，完整 graph 写 `agentData.aiFieldIds` 或 `replyContent.aiFieldIds`。AGENT 的 source `prompt` 可使用 `{#LibraryBlock id=<字段id> type=variable name="<字段名>" #}` 表达变量 chip；模板、普通工具和转人工动作按 `nodes/agent.md` 使用各自 LibraryBlock。builder 编译时写入完整 graph 的 `displayPrompt`、派生运行时 `prompt`，并自动补齐普通工具 ID 以及模板/转人工真实系统插件 ID 到 `usedPlugins`。
-- AGENT / `REPLY(PROMPT)` 不渲染 `[[var:...]]`。如果它们必须稳定使用上游节点输出，先用 `VARIABLE_PROCESS.assignments` 写入 `SYSTEM` 字段，再通过 `ai_field_ids` 引用。
-- `REPLY(DYNAMIC_TEMPLATE)`、LLM `prompt` 和 HUMAN_REVIEW `description` 会渲染 `[[var:<selector>]]`。完整 graph 使用 selector 数组，例如 `[[var:["CODE","<code_node_id>","summary"]]]`。source JSON 可在模板中写 selector 简写，例如 `[[var:{"code":"summarize_case","field":"summary"}]]`，builder 会替换为真实节点 id。
-- RAG_REPLY 用 `query_selector` 指定检索 query，不在 prompt 里插变量。
-
-## Compiled Graph Shape
-
-`compile` 生成的完整 `meta.chatFlowGraph` 包含：
-
-- `nodes`：`id` 唯一，`type` 通常为 `CUSTOM`，`position` 为 `{x, y}`，`data.category` 为节点类型。
-- `edges`：每条边必须包含非空的 `id`、`source`、`sourceHandle`、`target`、`targetHandle`、`type`；`id` 全图唯一，`source`、`target` 必须引用现有节点，当前只允许 `type: default`。
-- `viewport`：`{x, y, zoom}`。
-
-已有完整 graph 可包含 `type: CUSTOM_NOTE`、`data.category: NOTE` 的画布注释节点；详见 `nodes/note.md`。NOTE 不参与运行，不需要连线。
-
-不要生成或保留前端测量字段，例如 `measured`。
-
-## Runtime Handles
-
-source JSON 不写 `WAIT` 节点，也不要手动创建 `USER_INPUT` / `AGENT_TOOL` 节点。
-
-后端解析 graph 时会注入内部节点：
-
-- `USER_INPUT`：为 `AGENT`、`QUESTION`、`COLLECT_ORDER`、`KNOWLEDGE_REPLY` 注入等待用户输入的回环；`REPLY` 如果有出边，也会先 `WAIT -> USER_INPUT -> 原下游`；`RAG_REPLY` 的 `TRUE` 分支如果有出边，也会先等待用户下一轮输入再进入原 `TRUE` 下游。
-- `AGENT_TOOL`：为每个 `AGENT` 注入内部工具执行节点；AGENT 调外部 plugin 或知识工具时会走 `AGENT -> AGENT_TOOL -> AGENT`，不作为业务节点手写。
-
-排查日志或 transcript 时，`output_handle=WAIT` 通常表示当前节点已回复用户并等待下一轮输入；真正出现在执行路径里的内部节点是 `USER_INPUT`。
-
-## Resource Queries
-
-节点依赖外部资源时，先查询再写 id：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-templates --keyword "platform" --pretty
-npx --yes @shulex/cxclawctl@latest api list-plugins --pretty
-npx --yes @shulex/cxclawctl@latest api list-ai-fields --pretty
-npx --yes @shulex/cxclawctl@latest api list-agents --pretty
-```
-
-资源查询口径：
-
-- 模板查询走 `POST /api_v2/gpt/project/{projectId}/templates/filter`，用于按 keyword/status/scenes 查可用模板。图搭建页面的 `GET /templates` 适合前端全量渲染，不适合作为 agent 搜索模板的主要入口。
-- 联网 `compile` / `validate` / `deploy` / `update` / `publish` 会回查图中 REPLY、QUESTION、TRANSFER、COLLECT_ORDER 及 AGENT LibraryBlock 引用的模板；模板缺失或状态不是 `ENABLED` 时校验失败。离线模式只能做结构预检，不能声称模板状态已通过。
-- 工具查询使用 `list-plugins`，重点看工具 id、入参、出参和 actionStatus 配置。
-- 变量系统字段查询使用 `list-ai-fields`。该服务不可用时，先跳过字段存在性校验，不要阻断无字段依赖的图创建。
-- AGENT `ai_field_ids` 可用范围查询使用 `list-agent-ai-fields`。
-
-## Global Constraints
-
-- START 必须且只能有一个。
-- FINISH 不强制唯一；默认使用单个共享 `$finish`，减少无意义终端节点。
-- FINISH、TRANSFER_TO_HUMAN、SUB_GRAPH 无出边；SUB_GRAPH 后端 parser 强制禁止出边。
-- 图中不能有环；不要用回连表达多轮。
-- 所有运行节点必须从 START 可达；NOTE / CUSTOM_NOTE 是画布注释，不参与运行，不要求连接。
-- 除 START / NOTE 外，节点 title 不能为空、纯空格或重复。
-- AGENT 完整 graph 的 `prompt` 和 `displayPrompt` 必须非空；source 阶段只写一个 `prompt`，由 builder 派生两个完整 graph 字段；LibraryBlock 的 display/runtime 文本和绑定必须通过对账；`transferToHumans` 必须为空数组。
-- LLM `promptTemplate` 必须非空；LLM 不绑定工具、不配置 next_steps。
-- INTENT 节点可选配置全局识别 PE：source 使用 `prompt`，未配置时编译为 `config.prompt: null`；`history_round_limit` 编译为 `config.historyRoundLimit`，默认 `null`（交由后端默认策略）；每条意图仍需要 `name + desc` 或 `intentId`。
-- 即将下线节点默认不新建：`COLLECT_ORDER`、`KNOWLEDGE_REPLY`、`VARIABLE_ASSIGNMENT`、`VARIABLE_EXTRACT`、`AGENT version=1`。
-
-## CLI
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py --help --pretty
-
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py compile \
-  --source-file /workspace/state/agent-builder/chatflow/chatflow_source.json \
-  --graph-file /workspace/state/agent-builder/chatflow/chatflow_graph.json \
-  --pretty
-
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py validate \
-  --graph-file /workspace/state/agent-builder/chatflow/chatflow_graph.json \
-  --pretty
-
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py inspect \
-  --agent-name Example_Chatflow \
-  --pretty
-
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py deploy \
-  --agent-name Example_Chatflow \
-  --graph-file /workspace/state/agent-builder/chatflow/chatflow_graph.json \
-  --pretty
-
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py update \
-  --agent-id 2496 \
-  --graph-file /workspace/state/agent-builder/chatflow/patch_2496_graph.json \
-  --pretty
-
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py publish \
-  --agent-id 2496 \
-  --graph-file /workspace/state/agent-builder/chatflow/patch_2496_graph.json \
-  --pretty
-```
-
-## Write Discipline
-
-- 新建 agent：校验通过后询问用户是否写入当前环境和 agent 名称；确认后 `deploy`。
-- 多个新建 agent 必须逐个 `deploy`，不要在同一条 shell 命令里用 `&` 并发部署。平台
-  `createAgent` 在同租户/项目并发创建时可能返回泛化 `System Error`；builder CLI 有 deploy lock
-  和一次短重试，但操作层仍应顺序创建，避免部分创建成功、部分失败后路由状态不完整。
-- 增量修改：默认 `update` 保存草稿，不发布。
-- 发布：只有用户明确确认后，对同一份 graph 文件执行 `publish`。
-- 部署失败不要回滚；输出错误、agent_id、graph 文件路径。
-
-## Common Failures
-
-- `Invalid 'tools[N].function.name'`：节点 title 含空格、中文或 `/`，让 builder 清洗或手动改英文 key。
-- `GraphDefParseError`：优先检查 AGENT `transferToHumans` 是否非空、SUB_GRAPH 是否有出边。
-- TOOL `inputParams` 缺必填参数：source 写 `input_params`，或 compile 加 `--bind-tool-params`。
-- IF_ELSE 总走 FALSE：检查 variableSelector 是否多了 `"output"`。
-- RAG_REPLY 没有可检索目录时永远 LACK_KNOWLEDGE：`knowledgeDirectoryIds` 未配置或为空。

package/skills/agent-builder/references/chatflow/node-selection.md

@@ -1,89 +0,0 @@
-# Chatflow 节点选择指南
-
-本指南先确定节点职责，再确定节点组合。每个节点应有单一、可验证的输入/输出合同；不要用一个 AGENT 或一段 prompt 包揽分类、收集、调用、回复和转人工。
-
-## 决策顺序
-
-按以下顺序判断，命中确定性条件后停止继续泛化：
-
-1. 固定入口/终点/人工动作：`START`、`FINISH`、`TRANSFER_TO_HUMAN`。
-2. 流程必须取得客户输入后才能继续：`QUESTION`。只有流程明确要求客户作出选项选择时才用 `USER_REPLY`；收集字段/附件用 `VARIABLE`。
-3. 已有结构化值或工具状态需要判断：优先 `IF_ELSE` 或 `TOOL` 的 `actionStatus` 出边。流程图中的 Y/N 默认是条件结果：Y = 条件满足，N = 条件不满足，不是用户选项。
-4. 必须调用外部系统：`TOOL`；工具返回结构复杂时接 `IF_ELSE`，不要让 AGENT 代替确定性状态映射。
-5. 只需根据自然语言判断并分配到有限类别：`INTENT`；全局分类规则只在确有跨意图边界/优先级时配置 `prompt`。
-6. 知识检索并对客回答：`RAG_REPLY`。
-7. 只发送模板、固定话术或生成一段对客回复：`REPLY`；发送后有确定下游时只允许一个 `SOURCE` 出边。
-8. 内部抽取/整理/转换：优先 `CODE`（确定性）或 `VARIABLE_PROCESS`（字段抽取/赋值）；需要模型生成内部文本才用 `LLM`。
-9. 前述节点都无法表达，且确实需要开放式多轮处理、工具自主选择或由模型决定职责交接时：才使用 `AGENT`。
-10. 已确认需要记录业务埋点、且不改变对话或流程语义：使用 `BUSINESS_TRACK`。
-
-如果输入字段、输出分支或等待语义尚未明确，先询问客户是否有节点偏好；若图形无法直接映射，列出候选节点整理方式并询问客户想如何拆分，输出 `open_questions`，不要退化成万能 AGENT。节点参数、资源和运行时 selector 的细节只读最终选中节点的 `nodes/*.md`，不要在本文件重复展开。
-
-## 节点能力、优势与边界
-
-| 节点 | 独立职责/输入                                                                    | 优势                         | 不适用与替代                                            |
-|---|----------------------------------------------------------------------------------|------------------------------|---------------------------------------------------------|
-| `START` | 启动流程                                                                         | 结构清晰                     | 不放业务逻辑                                            |
-| `FINISH` | 正常结束                                                                         | 明确终态                     | 需要人工接管用 TRANSFER                                 |
-| `QUESTION` | 流程必须取得客户选择、确认、字段或附件后才能继续；USER_REPLY 产出选项，VARIABLE 产出字段 | 真正暂停、支持 max_rounds    | 不调用工具、不回答知识；只需发送说明用 REPLY |
-| `REPLY` | 发送模板、固定话术或生成一段对客回复；存在下游时发送后等待一轮用户消息 | 话术与动作分离 | 不做判断或结构化收集；必须使用客户回复才能继续时改用 QUESTION |
-| `TRANSFER_TO_HUMAN` | 可选直接转人工、模型生成话术转人工、模版发送话术转人工，发送后立马执行转人工动作 | 终止语义明确                 |                                                         |
-| `INTENT` | 根据自然语言在有限意图和 OTHER 中做一次分类分配，可选配置全局分类 PE | 适合纯语义判断和路由 | 不处理结构化状态、不负责多轮任务；每个意图必须有可解释下游 |
-| `IF_ELSE` | 对变量、工具出参或代码结果执行 if/elif/else 路由（多个 cases=if/elif，FALSE=else） | 确定性、可测试 |
-| `TOOL` | 调用一个外部工具并暴露结果/status                                                | 外部的http工具 | 不生成解释；工具若有配置状态映射，优先用 actionStatus   |
-| `RAG_REPLY` | 检索知识并回答，TRUE/LACK_KNOWLEDGE                                              | 知识问答稳定                 | 不代替确认/工具调用；目录必须真实存在                   |
-| `CODE` | 纯确定性字段提取、清洗、归一化、拆分、组装                                           | 可重复、稳定、低成本；适合整理出 IF_ELSE 可判断的值 | 不做模型判断、HTTP、长文本；复杂路由用 IF_ELSE          |
-| `VARIABLE_PROCESS` | 从上下文抽取字段和/或写入 SYSTEM                                                 | 变量桥接、字段合同清晰       | 不等待客户；客户补字段用 QUESTION(VARIABLE)             |
-| `LLM` | 生成内部摘要/改写/结构化结果                                                     | 适合非确定文本整理           | 不直接回复、不调用工具、不多出口                        |
-| `AGENT` | 持续承担局部开放式问题处理：多轮推理、工具自主选择、解释非结构化结果，并在职责结束后按需交接 | 灵活处理无法预先结构化的任务 | 不用于纯分类、必填收集、单次回复或确定流程；next_steps 不是普通执行顺序 |
-| `HUMAN_REVIEW` | 内部审批/填写后继续流程                                                          | 审批合同明确                 | 不是客户会话转人工                                      |
-| `SUB_GRAPH` | 调用独立 CHAT_FLOW                                                               | 复用子流程                   | 当前后端禁止出边                                        |
-| `BUSINESS_TRACK` | 记录确认的业务追踪事件后继续                                                    | 不干扰业务执行               | 不替代工具、回复、判断或用户交互                        |
-
-## AGENT 与 next_steps：准入门禁
-
-AGENT 必须承担一个需要模型持续处理的局部职责，而不是“执行一个简单步骤，然后跳到下一节点”。只有同时满足
-以下条件，才为 AGENT 配置 `next_steps`：
-
-1. 当前职责不能由 `INTENT`、`QUESTION`、`REPLY`、`TOOL`、`IF_ELSE`、`LLM` 或其他专用节点直接表达；
-2. AGENT 可能在当前节点内多轮回复或自主调用工具；
-3. 当前职责结束后确实存在独立的后续业务动作；
-4. 由模型根据非结构化上下文决定是否以及何时交接，而不是由固定顺序、工具 status 或结构化字段决定。
-
-只有一个确定下游时使用 AGENT 的 `SOURCE` 出边，不创建单个 `next_steps`。纯判断分配使用 `INTENT`；
-必须取得客户信息使用 `QUESTION`；只发送回复使用 `REPLY`；确定工具调用与结果路由使用 `TOOL` / `IF_ELSE`。
-不得创建仅表示步骤完成的 `success`、`done`、`continue`、`next` 分支。
-
-迁移或重建现有流程时，来源流程中的 Agent 数量、节点连接和切换指令只是待解释证据，不能直接变成
-目标 AGENT 或 `next_steps`。必须先按业务职责重新选型；只有确认保留为模型可选的职责交接，才生成
-next step。详细运行语义和配置规则见 `nodes/agent.md`。
-
-## QUESTION 与 REPLY：严格区分
-
-```text
-只需向客户发送说明、模板或提醒，不要求把客户下一条回复作为流程输入 → REPLY
-流程必须取得客户提供/选择/确认的信息后才能继续 → QUESTION（真正收集并等待） → 后续节点
-```
-
-- 先判断需求是“发送一段话”，还是“流程必须得到客户输入”；文案写成问句不代表已经完成收集。
-- `QUESTION(USER_REPLY)` 支持多个下游：每个 reply 一条边，并补 `OTHER` 兜底边。
-- `QUESTION(VARIABLE)` 只有一个 `SOURCE` 下游；收集完成后再进入后续节点。
-- `REPLY` 只有一个确定下游；存在下游时运行时才会等待一轮用户消息，需要按客户回答分支时必须接 QUESTION。
-
-## 状态映射与 AGENT 边界
-
-- 工具 actionStatus 完整、互斥、覆盖分支时：`TOOL → status edges`。
-- 读取工具返回字段、变量字段或代码输出时：`TOOL/VARIABLE/CODE → IF_ELSE`；多个 cases 按顺序表达 if/elif，`FALSE` 表达 else；每个 case 和 `FALSE` 都要连边。它只做确定性比较，不做自然语言理解。
-- actionStatus 是工具执行后的离散状态，不等于工具普通出参字段。判断状态名用 `tool_status` / `ACTION_STATUS_NAME`；判断返回体字段用 TOOL 出参 path；两者不要混写。
-- 自然语言意图才用 `INTENT`；不要用 AGENT 读取布尔/枚举状态再手工选路由。
-- 纯自然语言判断并分配到有限类别也使用 `INTENT`，不要仅因为分类需要 LLM 就创建 AGENT。
-- 只有需要模型持续综合非结构化信息、自主决定工具调用，或在当前职责完成后决定是否交接到一个或多个明确下游时才用 AGENT。
-
-
-## 流程图编排前置确认
-
-截图/PDF/白板转 CHAT_FLOW 时，先输出结构化摘要和拟构建 Mermaid，标注入口、节点职责、真实边条件（明确写出 Y=条件满足、N=条件不满足，除非证据表明是用户选择）、等待/收集点、转人工点和不确定区域；用户确认后再写 source、compile、validate。Mermaid 与 graph 不一致时以 graph 为准并立即修正。
-
-## 选择记录与验证
-
-对每个节点记录：`触发输入 → 选择节点 → 输出/等待合同 → 下游边 → 被拒绝的替代节点 → 资源证据`。若存在多个合理节点组合，先询问客户偏好；无法映射的图形节点先列出候选整理方式和 `open_questions`。最终执行 source/资源/edge 对账、compile、validate，并在必要时 replay。