@shulex/cxclawctl 0.1.2 → 0.1.4

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

@@ -1,97 +0,0 @@
-# REPLY
-
-## 功能概述
-
-发送一段话给用户，然后沿唯一 `SOURCE` 出边继续后续流程。`PROMPT` 由 LLM 按提示词生成回复；
-`TEMPLATE` 使用固定模板；`DYNAMIC_TEMPLATE` 先渲染上游变量，再把结果按会话语言翻译后发送。
-
-REPLY 不是只能做终端。凡是业务语义是“先对用户说一段固定/可生成的话，再继续进入同一个后续路径”，
-都可以用 REPLY 表达。它不负责判断分支，也不调用工具；分支判断应放在上游或下游的 INTENT /
-IF_ELSE / QUESTION / AGENT 中。
-
-REPLY 发送的是用户可见内容。需要知识检索回答时用 `RAG_REPLY`；需要内部摘要、改写或抽取时用
-`LLM`；需要发送后立即人工接管时用 `TRANSFER_TO_HUMAN` 的回复配置。
-
-## 创建方式
-
-```json
-{"key": "confirm_platform", "type": "reply", "reply_type": "TEMPLATE", "template_id": 12345}
-```
-
-```json
-{"key": "explain_policy", "type": "reply", "prompt": "Explain the return policy politely and concisely."}
-```
-
-```json
-{"key": "reply_with_order", "type": "reply", "prompt": "Answer using the OrderNumber field if present.", "ai_field_ids": [2742]}
-```
-
-```json
-{
-  "key": "reply_with_summary",
-  "type": "reply",
-  "reply_type": "DYNAMIC_TEMPLATE",
-  "template_content": "Order summary: [[var:{\"code\":\"summarize_case\",\"field\":\"summary\"}]]"
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| prompt | `reply_type` 缺省或为 `PROMPT` 时使用 |
-| reply_type | `PROMPT` / `TEMPLATE` / `DYNAMIC_TEMPLATE`，默认 `PROMPT` |
-| template_id | `TEMPLATE` 必填 |
-| template_content | `DYNAMIC_TEMPLATE` 必填；完整 graph 中可嵌入 `[[var:[...]]]` selector 模板，source 可使用 selector 简写 |
-| ai_field_ids | PROMPT 可用的变量系统字段 id 数组；完整 graph 字段为 `aiFieldIds` |
-| use_long_memory | PROMPT 是否注入长记忆，默认 false |
-| disable_prev_node_results | PROMPT 是否不注入前序节点结果，默认 false |
-
-## Edges
-
-仅 `SOURCE` 单出边。运行时如果 REPLY 有出边，chatflow 后端会注入 `WAIT -> USER_INPUT -> 原下游`，也就是先把回复发给用户并等待下一轮用户输入，再继续进入原下游节点。
-
-如果只是发送最终话术后结束，连 `$finish`；如果发送话术后转人工，连 `$transfer` 或显式 `TRANSFER_TO_HUMAN`。不要让 REPLY 承担分支判断。
-
-如果语义是“发送模板/话术后继续路由到同一个确定目标”，REPLY 表达这段发送动作：
-
-```text
-上游分支 -> REPLY(TEMPLATE 或 PROMPT) -> 后续处理节点
-```
-
-如果发送后要按用户回答分支，不要让 REPLY 直接多出边；改用 `REPLY -> QUESTION`，由 QUESTION
-收集用户回复并分流。
-
-## Resource Dependencies
-
-使用模板前先查模板库：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-templates --keyword "platform" --pretty
-```
-
-模板查询底层走 `/project/{projectId}/templates/filter`。
-
-## 限制
-
-- `TEMPLATE` 必须有 `template_id`。
-- `DYNAMIC_TEMPLATE` 必须有非空 `template_content`，不使用 `template_id` 或 `ai_field_ids`。
-- 动态模板的完整 selector 例如 `[[var:["CODE","<code_node_id>","summary"]]]`；只能引用当前 REPLY 的上游输出。可用 `SYSTEM`、`TOOL`、`EXTRACT`、`CODE`、`LLM`、`AGENT`、`HUMAN_REVIEW` 或 `NODE` selector，工具状态可用 `ACTION_STATUS_NAME`。
-- `DYNAMIC_TEMPLATE` 是确定性的变量渲染与翻译，不是让 LLM 重写模板内容。需要模型措辞时用 `PROMPT`。
-- `PROMPT` 必须写生成要求，可以控制回复内容、语气、必须包含/避免的信息；不要只写用户可见的一句话。
-- `aiFieldIds` 必须是变量系统字段 id 数组，例如 `[2742]`。
-- 字段服务不可用时不要新增未知 `aiFieldIds`；先用固定话术、模板，或复用已有 graph 中已确认字段 id。
-- 需要上游节点输出稳定进入 prompt 时，先用 VARIABLE_PROCESS 赋值到 SYSTEM 变量系统字段，再在 `ai_field_ids` 引用该字段。
-- 后端会把 `ai_field_ids` 对应字段作为额外系统上下文注入；上游节点结果也可能作为历史节点结果注入，但不要把它当成稳定 prompt 变量。
-- REPLY 不承担路由、工具调用、条件判断。
-- REPLY 只有一个下游；需要多个下游时，必须由相邻路由节点承担分支。
-- REPLY 中写“请提供/请上传/请确认”只是发送提示，不表示已收集或已确认；必须连接 QUESTION 才会等待用户输入。
-- `PROMPT` / `TEMPLATE` / `DYNAMIC_TEMPLATE` 各自只使用对应字段；不要在普通 PROMPT 中写 `[[var:...]]`。
-
-## Common Mistakes
-
-- 把固定话术写进 `PROMPT`。固定话术优先用模板；需要模型生成时才用 PROMPT。
-- 用 REPLY 问用户选项并期待分支。需要分支时用 `QUESTION(USER_REPLY)`。
-- 因为 REPLY 后还要继续流程，就误以为不能用 REPLY；REPLY 可以发送后接一个确定下游。
-- 想在 prompt 稳定使用上游输出，却没有先赋值到变量系统字段。
-- 动态模板把 selector 写成普通文本，或在 `template_content` 中引用下游/未连通节点。

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

@@ -1,35 +0,0 @@
-# START
-
-## 功能概述
-
-CHAT_FLOW 唯一入口节点。source JSON 通常不显式创建 START，由顶层 `entry` 自动生成。
-
-## 创建方式
-
-```json
-{"entry": "first_business_node"}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| entry | 首个业务节点 key |
-
-## Edges
-
-START 自动连到 `entry`，handle 为 `SOURCE`。
-
-## Resource Dependencies
-
-无。
-
-## 限制
-
-- 平台要求 START 必须且只能有一个。
-- START 必须有出边。
-
-## Common Mistakes
-
-- 手写多个 START。
-- 已写 `entry` 又额外手写一个重复 START。

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

@@ -1,48 +0,0 @@
-# SUB_GRAPH
-
-## 功能概述
-
-调用另一个 CHAT_FLOW。当前后端 parser 禁止 SUB_GRAPH 有出边，因此它是终止型子流程调用节点。
-
-## 创建方式
-
-```json
-{
-  "key": "run_return_flow",
-  "type": "sub_graph",
-  "target_agent_id": 2496,
-  "context_turn_limit": 5
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| target_agent_id | 被调用的 CHAT_FLOW agent id |
-| agent_id / agentId / targetAgentId | source JSON 可用别名，最终写成 `targetAgentId` |
-| context_turn_limit | 1-10，默认 5 |
-
-## Edges
-
-禁止出边。
-
-## Resource Dependencies
-
-先查可用 agent：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-agents --pretty
-```
-
-## 限制
-
-- 无出边。
-- 必须有入边。
-- `target_agent_id` 必填，且必须是可转成整数的 CHAT_FLOW agent id。
-- `context_turn_limit` 必须在 1-10 之间。
-- 如果子流程后还要回主流程，不适合 SUB_GRAPH；改用 AGENT next_steps 或拆回主流程。
-
-## Common Mistakes
-
-- 给 SUB_GRAPH 连出边，后端 parser 会失败。

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

@@ -1,138 +0,0 @@
-# TOOL
-
-## 功能概述
-
-调用单个外部 HTTP 工具拿结构化数据。下游可接 IF_ELSE；工具定义的 actionStatus 与当前业务分支完全一致时，也可直接按 actionStatus 出边。
-
-它把调用、入参、结果和状态暴露在画布上。action status 是工具声明的离散结果；当判断依赖多个返回字段、系统字段或布尔组合时，可将 TOOL 输出交给 IF_ELSE。TOOL 本身不生成对客回复，也不等待用户。
-
-## 创建前审计
-
-写 TOOL 节点前必须从真实工具定义建立审计表，不只看工具名或旧 prompt：
-
-| 审计项 | 来源 | 用途 |
-|---|---|---|
-| `requestParam.items[]` | 工具详情 | 决定 `input_params`，包括必填、类型、object/array 子字段 |
-| `responseParam.items[]` | 工具详情 | 决定下游 IF_ELSE / CODE / HUMAN_REVIEW 可引用的字段路径 |
-| `actionStatuses[]` | 工具详情 | 决定是否可以 `enable_action_status=true` 以及每个状态下游 |
-
-只有 actionStatus 名称、工具合同和目标业务分支三者能对齐时，才用工具状态出边。若流程按返回体字段、系统变量、多个字段组合或代码计算结果判断，应该 `TOOL -> IF_ELSE` 或 `TOOL -> CODE -> IF_ELSE`。
-
-chatflow 运行时的 TOOL 节点只读取画布上的 `inputParams`、`tool.id/type/enableActionStatus` 后调用工具；节点实现本身不会根据工具详情自动补齐必填参数，也不会猜测缺失参数该绑定哪个变量。工具入参是否完整、TOOL 出参 path 是否存在，必须用真实工具详情和 compile / validate 审计完成。不要只离线编译后就认定工具绑定正确。
-
-## 创建方式
-
-```json
-{
-  "key": "lookup_order",
-  "type": "tool",
-  "tool_id": 12345,
-  "input_params": [
-    {"name": "orderId", "variableSelector": {"system": {"category": "Order", "path": [3248, 3249]}}, "varType": "string"}
-  ]
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| tool_id | 必填，项目已有工具 id |
-| tool_type | 工具插件类型，默认 `EXTERNAL_HTTP_CALL`；维护已有非 HTTP 工具时保留实际类型 |
-| input_params[].name | 参数名，与工具定义一致 |
-| input_params[].text | 固定值 |
-| input_params[].variableSelector | 参数来源 |
-| input_params[].children | object 参数的子字段绑定 |
-| input_params[].varType | 类型 |
-| enable_action_status | 是否按工具 action status 出边 |
-
-## Edges
-
-- 默认 `SOURCE`。
-- `enable_action_status=true` 时，TOOL 直接从工具原始结果 `raw_result["__status"]` 取状态名作为 `output_handle`；缺失时运行时抛 `ToolInvokeError("Tool result missing action status")`。
-- 状态名使用工具定义中的原始名称。
-- 只有工具定义的 actionStatus 完整、互斥且覆盖当前业务分支时才直接出边；否则用 `SOURCE -> IF_ELSE` 或 `SOURCE -> AGENT` 解读工具结果。
-- 多个 actionStatus 不能因为都“失败”就合并到同一个转人工节点；只有责任、用户轮次、回复合同、模板/NO_REPLY 和转人工原因一致时才共享下游。
-
-## Output Variables
-
-TOOL 成功后写入的节点输出形态是：
-
-```json
-{
-  "name": "<tool node title>",
-  "tool_result": "<parsed_result>"
-}
-```
-
-下游引用工具出参时读取的是 `tool_result`，按返回结构逐层写路径：`{"tool":"lookup_order","path":["order","shipping_method_no"]}`。嵌套字段不能写成单段 `field: "order.shipping_method_no"`。
-
-工具状态不是普通出参。判断状态名用：
-
-```json
-{"variableSelector": {"tool_status": "lookup_order"}}
-```
-
-完整 selector 是 `["TOOL", "<tool_node_id>", "ACTION_STATUS_NAME"]`，运行时会读取最近一次该 TOOL 结果中的 `tool_result.__status`。如果工具直接出边和下游 IF_ELSE 都依赖状态，必须确认工具解析后的 `parsed_result` 也保留 `__status`，否则直接出边可用但 IF_ELSE 读不到状态。
-
-判断返回体字段才用：
-
-```json
-{"variableSelector": {"tool": "lookup_order", "path": ["order", "shipping_method_no"]}}
-```
-
-不要在未确认 `responseParam` 的情况下凭经验写 `status`、`data.status`、`result.status`。如果只有 actionStatus 可用，就按 actionStatus 出边或在 IF_ELSE 中引用 `tool_status`。
-
-## Resource Dependencies
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-plugins --pretty
-npx --yes @shulex/cxclawctl@latest api list-ai-fields --pretty
-```
-
-`--bind-tool-params` 只是辅助，不是业务决策来源：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/chatflow/chatflow_builder.py compile ... --bind-tool-params
-```
-
-实际行为：
-- 仅在 `queryAiFields` 可用时生效；字段服务不可用时会被跳过并产生 warning。
-- 只尝试自动绑定工具定义中 `required=true` 且 `source=LLM` 的参数。
-- 只按内置常见字段名映射或变量系统字段直接同名匹配生成 `SYSTEM` selector。
-- 找不到匹配字段时只打印 warning，不会生成 `open_questions`，也不会替你判断是否该新建变量或改成 QUESTION。
-- 已经写在 `input_params` 里的参数不会被覆盖。
-
-因此不能依赖 `--bind-tool-params` 自动解决业务字段绑定；它只能作为最后的辅助补齐和校验。
-
-## 限制
-
-- 必填参数必须绑定变量系统字段或固定值。
-- 找不到明确来源的必填参数时，不得按名称相似自动绑定现有变量；必须输出 `open_questions`，让用户选择新建变量、使用哪个现有变量、改为 `QUESTION(VARIABLE)` 收集、转人工或不迁该自动化。
-- chatflow 运行时解析 `inputParams` 时，如果顶层参数解析结果是 `None`，会直接从 `tool_args` 中省略该参数；这不是“已绑定空值”。必填参数不能依赖运行时发现，必须在创建审计和 validate 阶段拦住。
-- 固定 `text` 绑定到 `varType=object/array` 时，运行时会 `json.loads(text)`；必须写合法 JSON，不能写 Python 字面量或自然语言描述。
-- `variableSelector` 绑定到 `varType=array` 时，如果取到的是非 list，运行时会包装成单元素数组；这只是兼容机制，不代表可把单个商品字段当成完整商品数组使用。
-- array/object 参数（如 `itemVos`、`refundProducts`、`productList`）必须确认数组元素结构和同一商品记录的一致性；无法保证时不要把单个商品字段拼成数组执行补发/退款，优先询问或转人工。
-- validator 会按真实 `requestParam.items[]` 检查所有 required 参数；object 参数会递归检查 `objectItems`，完整缺失路径会类似 `address.line1`。
-- array 参数在 validator 中按叶子处理；它只校验该数组参数本身是否配置，不理解数组元素是否来自同一商品记录。涉及补发/退款商品数组时必须人工审计来源一致性。
-- 工具定义里 `source=CUSTOMIZE` 或非 LLM 的必填参数不会被 `--bind-tool-params` 自动补齐；需要根据工具定义和业务语义手写 `text` 或明确 selector，并通过真实 validate 校验。
-- object 参数的必填子字段必须逐层写入 `children`，字段名与工具定义 `objectItems[].name` 一致。运行时会把 object 的 `children` 解析成 `{child.name: child_value}`。
-- array 参数的 `children` 在运行时会被解析成列表元素；数组元素是对象时，子项也必须按 object 结构显式表达，不能只把多个平铺字段塞进同一个 array。
-- `input_params[].name` 必须和工具定义 `requestParam.items[].name` 一致；object 子字段同理。
-- `input_params[].variableSelector` 引用上游变量，支持 `SYSTEM`、`TOOL`、`EXTRACT`、`CODE`、`LLM`、`AGENT`、`HUMAN_REVIEW`。
-- `input_params[].variableSelector` 不使用工具状态 `ACTION_STATUS_NAME`；需要按工具状态分支时用 TOOL 自身的 actionStatus 出边或下游 IF_ELSE。
-- `input_params[].variableSelector` 只能引用当前 TOOL 的上游节点输出；validator 会拒绝引用同级、下游或未连通节点。
-- `AGENT` selector 只能引用当前上游路径已连通 nextStep 的 `params[].name`。
-- EXTRACT selector 第三段是 extract `id`，不是 `name`。
-- TOOL 只负责调用，不负责解释复杂结果。
-- 使用 actionStatus 前必须确认状态定义完整、互斥，且能准确覆盖当前业务分支；否则使用工具结构化输出接 IF_ELSE。
-
-## Common Checks
-
-- 多个下游业务节点需要由 IF_ELSE 或 actionStatus 明确承接。
-- 参数名与工具定义一致。
-- 引用变量时确认被引用节点在当前 TOOL 上游。
-- object 参数的必填子字段都已绑定，不只绑定父级 object。
-- compile 前确认每个必填参数都有来源说明：`SYSTEM` 字段、上游 TOOL/CODE/QUESTION 输出、固定值，或已记录为阻塞 open question。QUESTION(VARIABLE) 的结果通常先进入变量系统字段，再用 `SYSTEM` selector 绑定工具入参。
-- compile 报缺必填参数时，先回到参数审计表补来源，不要临时绑定同名/近似变量来压过校验。
-- validate 报 `references invalid TOOL output path` 时，先核对真实 `responseParam.items[]`；数组字段不能继续向内写子路径，object 字段才可逐层引用。

package/skills/agent-builder/references/chatflow/nodes/transfer-to-human.md

@@ -1,63 +0,0 @@
-# TRANSFER_TO_HUMAN
-
-## 功能概述
-
-终止当前流程并转人工。支持直接无回复转人工、节点内模型生成话术后转人工、节点内固定模板后转人工。
-
-TRANSFER_TO_HUMAN 表达的是客服会话接管。一旦执行，当前 chatflow 不再继续走后续节点。它不同于 `HUMAN_REVIEW` 的流程内审核，也不同于 `AGENT.next_steps` 的流程内跳转。
-
-## 创建方式
-
-```json
-{"key": "handoff", "type": "transfer"}
-```
-
-```json
-{"key": "handoff_with_template", "type": "transfer", "transfer_type": "TEMPLATE", "template_id": 12345}
-```
-
-## 创建参数
-
-| 字段 | 说明                                                    |
-|------|---------------------------------------------------------|
-| transfer_type | `NO_REPLY` / `PROMPT` / `TEMPLATE`，默认 `NO_REPLY`     |
-| prompt | PROMPT 类型时使用的模型生成提示词                         |
-| template_id | TEMPLATE 时必填                                         |
-| ai_field_ids | PROMPT 可注入的变量系统字段 id 数组                    |
-| disable_prev_node_results | PROMPT 是否不注入前序节点结果，默认 false             |
-| explain | 写入人工接管结果的说明；缺省时使用节点标题             |
-
-## Edges
-
-无出边。普通默认无回复转人工可直接用 `$transfer`。
-
-## Resource Dependencies
-
-TEMPLATE 转人工先查模板：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-templates --keyword "handoff" --pretty
-```
-
-## 限制
-
-- 不要使用 AGENT `transferToHumans` 字段。
-- 确定性转人工路径应显式节点化为 `TRANSFER_TO_HUMAN` 或 `$transfer`。
-- 如果转人工由 AGENT 在多轮判断中自主决定，按 `agent.md` 在 prompt 中插入标准 `transferHuman`
-  LibraryBlock；联网 compile 会把真实 `TRANSFER_TO_HUMAN` 系统插件 ID 加入该 AGENT 的 `usedPlugins`，
-  但独立 `TRANSFER_TO_HUMAN` 节点本身不写插件，也不要把转人工伪装成 AGENT `next_steps`。
-- `NO_REPLY` 不需要 `prompt` 或模板。
-- `PROMPT` 必须有 `prompt`。
-- `PROMPT` 可用 `ai_field_ids` 注入变量系统字段；普通 `[[var:...]]` 模板不在此节点渲染。需要上游节点输出时，先桥接到 SYSTEM 字段，不能默认增加普通 REPLY 节点改变终止语义。
-- `TEMPLATE` 必须有 `template_id`。
-- 有不同回复内容的转人工路径不要合并成同一个 transfer 节点。
-- 不同业务职责、不同 action status 或不同 transfer reason 不要全部连到同一个 `$transfer`。
-- 如果确实要共享一个 transfer，必须在设计说明中写明相同职责、相同用户轮次、相同回复合同和合并证据。
-- `PROMPT` 表示该转人工节点自身先由模型生成一段对客话术，然后执行转人工；它不是前置分类节点。
-- `TEMPLATE` 表示该转人工节点自身先发送固定模板，然后执行转人工。
-- 转人工节点的 PE 是面向模型的pe，作用是用来让模型生成面向客户的回复。
-
-## Common Mistakes
-
-- 把“先回复再转人工”直接连 `$transfer`，导致回复丢失。
-- 多个不同模板共用一个 transfer 节点。

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

@@ -1,52 +0,0 @@
-# VARIABLE_ASSIGNMENT
-
-## 功能概述
-
-变量赋值兼容节点。仅用于兼容已有图；新建优先使用 `VARIABLE_PROCESS`。
-
-## 创建方式
-
-```json
-{
-  "key": "set_variables",
-  "type": "variable_assignment",
-  "assignments": [
-    {"id": "assign-001", "operation": "OVER_WRITE", "source": ["TOOL", "lookup_order", "status"], "target": [["SYSTEM", "Custom", 2742]]}
-  ]
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| assignments[].id | 赋值项 id |
-| assignments[].operation | `OVER_WRITE` / `CLEAR` / `CONSTANT` |
-| assignments[].source | variableSelector 或常量 |
-| assignments[].target | 目标 variableSelector 二维数组 |
-| assignments[].forceOverride | 是否强制覆盖 |
-
-## Edges
-
-仅 `SOURCE`。
-
-## Resource Dependencies
-
-目标变量系统字段先查 `list-ai-fields`。
-
-## 限制
-
-- 新建默认不用。
-- 每个 assignment 必须有 `id/operation/target`。
-- `CONSTANT` 操作必须有非空 `source`。
-- `OVER_WRITE` 的 `source` 引用上游变量，支持 `SYSTEM`、`TOOL`、`EXTRACT`、`CODE`、`LLM`、`AGENT`、`HUMAN_REVIEW`。
-- `OVER_WRITE` 的 `source` 不使用工具状态 `ACTION_STATUS_NAME`；需要状态判断时用 IF_ELSE 或 TOOL actionStatus 出边。
-- `AGENT` selector 只能引用当前上游路径已连通 nextStep 的 `params[].name`。
-- `target` 只能是 `SYSTEM` 变量二维数组，如 `[["SYSTEM", "Custom", 2742]]`。
-- EXTRACT selector 第三段是 extract `id`，不是 `name`。
-- 能迁成 `VARIABLE_PROCESS` 时优先迁移。
-
-## Common Mistakes
-
-- 新建图继续使用旧节点。
-- 把 `source` 写成 extract `name`；应引用 extract `id`。

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

@@ -1,50 +0,0 @@
-# VARIABLE_EXTRACT
-
-## 功能概述
-
-变量提取兼容节点。仅用于兼容已有图；新建优先使用 `VARIABLE_PROCESS`。向用户收集信息优先使用 `QUESTION(VARIABLE)`。
-
-## 创建方式
-
-```json
-{
-  "key": "extract_params",
-  "type": "variable_extract",
-  "variables": [
-    {"alias": "order_no_value", "name": "order_no", "describe": "Order number", "type": "string"}
-  ],
-  "additional_data": [{"node": "previous_node"}]
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| variables / extracts | 提取项，source 写 name/type/describe；需要后续引用时加 alias，compile 后 alias 会变成完整 graph 的 UUID `id` |
-| additional_data | 提取时额外拼接的上游变量选择器数组；source 可写 selector 简写，完整 graph 为 `additionalData: [["SYSTEM",...], ["TOOL",...], ["NODE",...]]` |
-| use_chat_history | 是否使用历史 |
-
-## Edges
-
-仅 `SOURCE`。
-
-## Resource Dependencies
-
-引用上游节点输出或变量系统字段前，先确认对应 id。
-
-## 限制
-
-- 新建默认不用。
-- 至少有一个提取项。
-- source 每个提取项必须有 `name/describe/type`，需要后续引用时必须有 `alias`；已有完整 graph 必须有 `id/name/describe/type`，其中 `id` 通常是前端或 builder 生成的 UUID。
-- `name` 格式 `/^(?!\d)[A-Za-z0-9_-]{1,64}$/`。
-- `additional_data` 只能引用上游 `SYSTEM` / `TOOL` / `CODE` / `AGENT` / `HUMAN_REVIEW` / `NODE`，用于补充提取上下文。
-- `additional_data` 不使用工具状态 `ACTION_STATUS_NAME`；`AGENT` selector 只能引用当前上游路径已连通 nextStep 的 `params[].name`。
-- 下游引用本节点提取结果时用 `["EXTRACT", "<this_node_id>", "<extract_id>"]`；第三段是 extract `id`，不是 `name`。
-- 只想收集用户输入时，用 `QUESTION(VARIABLE)`。
-
-## Common Mistakes
-
-- 把用户提问收集误建成变量提取。
-- 用 `NODE_OUTPUT` 或 extract `name` 写 selector；source 用 `alias`，完整 graph 用 UUID `id`。

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

@@ -1,70 +0,0 @@
-# VARIABLE_PROCESS
-
-## 功能概述
-
-提取上下文变量、给变量系统字段赋值，或先提取再赋值。也是把上游节点输出转换成 AGENT / REPLY prompt 可读变量系统字段的桥接节点。
-
-`shulex-gpt` 会在进入 CHAT_FLOW 前抽取已配置的变量系统字段。这些字段进入图后已可读取；如果需要从 `AttachmentSummary` 等字段中继续提取新参数，仍可使用本节点。
-
-VARIABLE_PROCESS 不向用户发送消息，也不等待用户输入；它处理的是当前上下文里已经存在的文本、变量或上游节点结果。需要向用户补收字段时用 `QUESTION`。
-
-## 创建方式
-
-```json
-{
-  "key": "process_variables",
-  "type": "variable_process",
-  "additional_data": [{"node": "previous_reply"}],
-  "variables": [
-    {"alias": "order_no_value", "name": "order_no", "describe": "Order number", "type": "string"}
-  ],
-  "assignments": [
-    {"id": "assign_order", "operation": "OVER_WRITE", "source": ["SELF", "order_no_value"], "target": [["SYSTEM", "Custom", 2742]]}
-  ]
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| variables / extracts | 提取项，source 写 name/describe/type；需要后续引用时加 alias，compile 后 alias 会变成完整 graph 的 UUID `id` |
-| assignments | 赋值项，必填 id/operation/target |
-| additional_data | 提取时额外拼接的上游变量选择器数组；source 可写 selector 简写，完整 graph 为 `additionalData: [["SYSTEM",...], ["TOOL",...], ["NODE",...]]` |
-| use_chat_history | 是否使用历史 |
-
-## Edges
-
-仅 `SOURCE`。
-
-## Resource Dependencies
-
-赋值到变量系统字段前查：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-ai-fields --pretty
-```
-
-## 限制
-
-- 至少有 extract 或 assignment。
-- source extract 必须有 `name/describe/type`，需要后续引用时必须有 `alias`；已有完整 graph 必须有 `id/name/describe/type`，其中 `id` 通常是前端或 builder 生成的 UUID。
-- extract `name` 格式 `/^(?!\d)[A-Za-z0-9_-]{1,64}$/`。
-- assignment 必须有 `id/operation/target`。
-- `CONSTANT` 操作必须有非空 `source`。
-- `additional_data` 只能引用上游 `SYSTEM` / `TOOL` / `CODE` / `AGENT` / `HUMAN_REVIEW` / `NODE`，用于补充提取上下文；不引用 `SELF`。
-- `additional_data` 不使用工具状态 `ACTION_STATUS_NAME`；`AGENT` selector 只能引用当前上游路径已连通 nextStep 的 `params[].name`。
-- `assignments[].source` 在 `OVER_WRITE` 时可引用上游变量，或用 `["SELF", "<extract_alias>"]` 引用本节点刚提取的值；compile 后会替换成 extract UUID `id`。
-- `assignments[].source` 不使用工具状态 `ACTION_STATUS_NAME`。
-- `assignments[].target` 只能是 `SYSTEM` 变量二维数组，如 `[["SYSTEM", "Custom", 2742]]`。
-- AGENT / REPLY prompt 需要稳定使用上游输出时，先在这里把 `TOOL` / `EXTRACT` / `CODE` / `AGENT` selector 赋值到 `SYSTEM` 变量系统字段，再让下游节点通过 `ai_field_ids` 读取。
-- 下游引用本节点提取结果时用 `["EXTRACT", "<this_node_id>", "<extract_id>"]`；第三段是 extract `id`，不是 `name`。
-- 收集用户输入优先用 `QUESTION(VARIABLE)`。
-- 已有变量系统字段可直接用 `SYSTEM` selector 读取；需要二次提取、转换或赋值时再使用本节点。
-
-## Common Mistakes
-
-- 新建图继续使用即将下线的 `VARIABLE_EXTRACT` / `VARIABLE_ASSIGNMENT`。
-- 只想问用户信息却用变量处理节点。
-- 用 extract `name` 引用输出，例如 `["EXTRACT", node_id, "order_no"]`；source 用 `alias`，完整 graph 用 UUID `id`。
-- 需要给 AGENT / REPLY prompt 使用的上游输出，没有先赋值到 SYSTEM 变量系统字段。

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

@@ -1,53 +0,0 @@
-# CHAT_FLOW
-
-把流程描述、流程图或已有 CHAT_FLOW 修改需求，整理成可校验、可部署的 `chatFlowGraph`。
-
-## 先判定模式
-
-| 输入特征 | 模式 | 先读 |
-|---------|------|------|
-| 文字描述 / 流程图截图 / PDF | 新建 | `workflow.md`、`node-selection.md`；图片输入再读 `visual-translation.md` |
-| 已有 CHAT_FLOW agent_id / graph + 修改要求 | 增量 | `workflow.md`、`graph-spec.md` |
-
-新建 / 增量模式确定后：
-
-1. 先用 `node-selection.md` 选节点类型，不要凭节点名猜。
-2. 对每个最终会使用的候选节点读取对应 `nodes/<node>.md`；字段、出边和 runtime 行为按节点文档确认。节点文档是功能合同，不是 PE/Role 提示词。
-3. 新建图或用户明确提供 source 时，写 source JSON 前读 `graph-spec.md`；已有 CHAT_FLOW 的增量修改先按 `workflow.md` 执行 `inspect`，完整 graph 就是后续修改、校验和保存草稿的输入。
-4. 只读将要使用的 `nodes/<node>.md`，按节点说明填写字段。
-5. 编译、校验、写回、发布流程按 `workflow.md` 执行。
-
-任何节点只要出现必填配置、输入字段、输出字段、变量 selector、资源 id、模板、知识库目录、工具参数、状态分支或等待语义无法从现有上下文唯一确定，都必须提出 `open_questions`，列出“新建资源/变量、使用哪个现有项、转人工或不迁该自动化”等可执行选项和影响；用户确认前不得凭名称相似自动绑定，不得伪造输出字段、资源 id、TOOL 出参路径、CODE 输出字段或下游分支。
-
-新建图禁止使用即将下线节点。订单号/订单信息场景禁止选择 `COLLECT_ORDER`；除非是在维护已有图并必须保留
-已存在行为，否则应使用变量系统订单字段、`QUESTION(VARIABLE)`、`TOOL`、`IF_ELSE` / 工具状态分支和必要的
-`AGENT` 组合表达。
-
-新建图的变量节点只选择 `VARIABLE_PROCESS`；`VARIABLE_EXTRACT` / `VARIABLE_ASSIGNMENT` 只维护已有图。INTENT 节点的 `prompt` 是可选的全局识别 PE，默认使用 `None`；`history_round_limit` 默认使用 `None`，交由后端默认策略。只有当用户需求明确包含跨意图的统一识别规则、边界或优先级时才生成 prompt；生成后先向用户确认是否启用，用户不需要时保留 `prompt: null`。
-
-只要候选里出现 AGENT，必须读 `nodes/agent.md` 的 `next_steps And Transfer Tools`：`next_steps` 只生成流程内跳转工具，AGENT 自主转人工使用标准 `transferHuman` LibraryBlock，不能把转人工配置成 nextStep。不要把 AGENT 当作任意业务步骤的默认容器。
-
-## 工作文件
-
-- source：`/workspace/state/agent-builder/chatflow/*_source.json`（新建或整图重建时）
-- 大图 fragment / integration：`/workspace/state/agent-builder/chatflow/<task>/blocks/`
-- graph：`/workspace/state/agent-builder/chatflow/*_graph.json`（已有图 inspect 后的 patch 也属于此类）
-- state：`/workspace/state/agent-builder/chatflow/`，跨轮复用，文件名稳定
-- outputs：`/workspace/outputs/agent-builder/chatflow/`，只放用户明确需要下载或留档的文件
-- 需要用户确认后继续执行的配置、source、graph 必须写 state，不写 tmp
-
-继续已有 CHAT_FLOW 时，先 `inspect` 拉当前完整 graph，并将它作为本次维护的工作文件。
-
-## 固定原则
-
-- 新建图使用 source JSON；整体重建可使用 source -> compile；已有 CHAT_FLOW 的增量修改使用 inspect 得到的完整 `chatFlowGraph`，包括新增/删除节点、修改边和调整条件分支。
-- 大图先按已确认的流程块完成 keyed source fragment，再合并为唯一 source 并只编译一次；不合并已编译 graph。
-- 固定动作使用 `chatflow_builder.py` CLI，不写临时 Python 脚本，不 import builder 函数。
-- `compile` / `validate` 有 error 必须先修同一个 source 或 graph 文件，再重新执行。
-- 新建、发布前必须让用户确认；增量修改默认保存草稿，不发布。
-- 工具状态确定后必然发送的固定回复优先查模板并使用 `REPLY(TEMPLATE)`；若固定话术是某个上下文判断节点
-  的 PE/输出约束，则逐字保留在该节点实际使用的文本字段，不能仅因它是固定话术就强制改成 REPLY。
-  需要用户选择并分支时用 `QUESTION(USER_REPLY)`。
-- CHAT_FLOW 不感知 `metadata` 路径；禁止在任何节点 prompt、selector、条件、工具入参或代码输入里写 `metadata.xxx`。变量系统字段通过 ai-fields 暴露，使用 `SYSTEM` selector 或相应节点的 ai-field 绑定；支持变量模板的节点可直接引用已连通上游 selector。
-- AGENT / `REPLY(PROMPT)` 通过 `ai_field_ids` 读取变量系统字段；需要稳定使用上游输出时，先用 `VARIABLE_PROCESS` 赋值到 SYSTEM 字段。`REPLY(DYNAMIC_TEMPLATE)` 与 LLM 模板按各自节点文档使用 `[[var:...]]`。
-- 图中不能有环；多轮追问交给节点 `maxRounds`，不要在图层回连上游节点。