@shulex/cxclawctl 0.1.2 → 0.1.4

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

@@ -1,60 +0,0 @@
-# HUMAN_REVIEW
-
-## 功能概述
-
-人工审核或人工补充信息节点。适合需要内部人员审批、确认、填充字段的流程。
-
-HUMAN_REVIEW 是流程内的人工任务：审核或填写完成后，流程继续走出边。它不是客服会话转人工；
-需要把当前用户会话交给人工客服时使用 `TRANSFER_TO_HUMAN` 或具备真实转人工能力的节点。
-
-## 创建方式
-
-```json
-{
-  "key": "review_refund",
-  "type": "human_review",
-  "method": "approval",
-  "description": "Review whether refund can be approved."
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| method | `approval` / `fill` |
-| description | 给审核人的说明；支持 `[[var:[...]]]` 上游变量模板 |
-| fields | fill 模式需要填写的字段 |
-| fields[].id | fill 字段 id；下游 selector 第三段使用该值，建议显式写稳定 id |
-| fields[].fieldName | fill 字段名，必填 |
-| fields[].fieldType | `text` / `attachment` / `options` |
-| fields[].options | `options` 类型必填，不能为空且不能重复 |
-| midway_message_strategy | 审核等待期间普通用户消息的处理：`ignore`（默认）/ `handle` |
-
-## Edges
-
-- approval：必须有 `AGREE` + `REJECT`。
-- fill：仅 `SOURCE`。
-
-## Resource Dependencies
-
-fill 模式字段需确认业务字段定义。
-
-## 限制
-
-- approval 双出边必须完整。
-- `description` 必填。
-- `description` 可插入变量模板：`[[var:["CODE","<code_node_id>","summary"]]]`。
-- 变量模板支持上游 `SYSTEM`、`TOOL`、`EXTRACT`、`CODE`、`LLM`、`AGENT`、`HUMAN_REVIEW`；工具状态可用 `["TOOL", node_id, "ACTION_STATUS_NAME"]`。
-- `AGENT` selector 只能引用当前上游路径已连通 nextStep 的 `params[].name`。
-- fill 模式必须有 `SOURCE` 出边。
-- fill 模式字段必须有 `fieldName`；`options` 字段必须配置选项。
-- 下游引用 fill 结果用 `["HUMAN_REVIEW", "<this_node_id>", "<field_id>"]`。
-- 如果后续要引用 fill 结果，`fields[].id` 必须稳定；不要用展示名当 selector。
-- 不用它代替普通用户确认；用户确认用 QUESTION。
-
-## Common Mistakes
-
-- approval 忘记 REJECT 分支。
-- description 变量模板引用非上游节点，或 EXTRACT 使用了 `name` 而不是 `id`。
-- fill 字段没有稳定 `id`，导致下游无法可靠引用人工填写结果。

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

@@ -1,100 +0,0 @@
-# IF_ELSE
-
-## 功能概述
-
-对已有变量、工具输出或系统字段做确定性条件判断。多个 `cases` 按顺序表达 `if / elif`，未命中时的 `FALSE` 表达 `else`；它不理解自然语言，只比较已经存在的结构化值。
-
-它不理解自然语言，而是读取已经存在的结构化值，按 cases 的条件组合输出对应 handle；没有命中时走 FALSE。适合枚举、存在性、数值、日期和布尔判断，也可表达多个条件的 AND/OR 组合。
-
-## Source 选择
-
-IF_ELSE 的第一步是确定判断对象，不是先写 case 名称：
-
-| 要判断的内容 | source JSON 简写 | 完整 graph selector | 说明 |
-|---|---|---|---|
-| 工具 actionStatus | `{"tool_status": "lookup_order"}` | `["TOOL", "<tool_node_id>", "ACTION_STATUS_NAME"]` | 运行时读取最近一次 TOOL 输出的 `tool_result.__status`；不是 `status` 字段 |
-| 工具返回体字段 | `{"tool": "lookup_order", "path": ["order", "shipping_method_no"]}` | `["TOOL", "<tool_node_id>", "order", "shipping_method_no"]` | 运行时从 `tool_result` 开始逐层取值；路径必须来自 `responseParam.items[]` |
-| 变量系统字段 | `{"system": {"category": "Order", "path": [3248, 3249]}}` | `["SYSTEM", "Order", 3248, 3249]` | 完整 selector 只能是 3 段或 4 段；第三/第四段是字段 id |
-| CODE 输出 | `{"code": "normalize_items", "field": "item_count"}` | `["CODE", "<code_node_id>", "item_count"]` | 运行时从 `exec_result[fieldName]` 读取；field 必须是 CODE `outputs[].fieldName` |
-| LLM 输出 | 用完整 selector | `["LLM", "<llm_node_id>", "text"]` 或 `["LLM", "<llm_node_id>", "structured_output", "..."]` | text 固定三段；structured_output 可继续下钻 |
-| AGENT 输出 | 无推荐简写；用完整 selector | `["AGENT", "<agent_node_id>", "param_name"]` | param 必须来自已连通 nextStep 的 `params[].name` |
-
-常见错误是把工具 actionStatus 当作普通字段写 `{"tool":"x","field":"status"}`，或把返回体字段当成 actionStatus。除非 `responseParam` 真实存在 `status` 字段，否则不能写 `status`。
-
-当工具详情里同时出现普通返回字段和 actionStatus 时，先判断业务语义：
-- 旧流程按“工具执行动作状态”走分支，且状态名与 actionStatus 对齐：选 `tool_status` / `ACTION_STATUS_NAME`。
-- 旧流程按订单状态、物流单号、退款金额、商品数组等返回体内容判断：选 TOOL 出参 path。
-- 需要对多个字段组合、数组长度、对象字段归一化后判断：先 `TOOL -> CODE`，再在 IF_ELSE 里选 CODE output。
-- 需要判断变量系统字段，例如订单号、邮箱、国家、附件字段：选 SYSTEM，不要伪造 TOOL `status`。
-
-validator 会检查 selector 引用的节点必须是当前 IF_ELSE 的上游 predecessor；不能引用同级、下游或未连通节点。需要先经过 CODE 转换时，边必须是 `TOOL -> CODE -> IF_ELSE`，再在 IF_ELSE 中引用 CODE 输出。
-
-## 创建方式
-
-```json
-{
-  "key": "check_order_status",
-  "type": "if_else",
-  "cases": [
-    {
-      "id": "SHIPPED",
-      "conditions": [
-        {"variableSelector": {"tool": "lookup_order", "path": ["order", "shipping_method_no"]}, "comparisonOperator": "NOT_EMPTY"}
-      ]
-    }
-  ]
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| cases[].id / name | 出边 handle |
-| cases[].logicalOperator | `AND` / `OR`，默认 `AND` |
-| conditions[].variableSelector | 判断字段 |
-| conditions[].comparisonOperator | 比较操作 |
-| conditions[].value | 比较值 |
-
-## Edges
-
-每个 case 一条边，另加 `FALSE`。运行时按 `cases` 顺序依次评估，命中第一个 case 后用该 `case.id` 作为 `output_handle` 和路由 handle；全部未命中时用 `FALSE` handle，并在输出数据里记录 `matched_case_id: "else"`。
-
-## Resource Dependencies
-
-判断变量系统字段先查 `list-ai-fields`；判断工具结果需确认上游 TOOL 输出字段。
-
-变量系统字段在进入 CHAT_FLOW 前由 `shulex-gpt` chat 链路统一抽取，因此可直接用 IF_ELSE 判断。嵌套字段必须使用 `list-ai-fields` 返回的完整 id 路径，例如 `["SYSTEM", "Order", 3248, 3249]`。
-
-判断工具字段前必须查工具详情的 `responseParam` 或可验证的完整 graph 输出配置；只看到旧 prompt 里的“状态”“成功”“失败”不等于有可引用字段。判断代码输出前必须读取 CODE 节点的 `outputs`，不能引用 `source_code` 中临时变量。
-
-完整 graph 校验会用 plugin metadata 构建 TOOL 可用出参路径：object 子字段可继续下钻，array 字段按叶子处理。若工具没有 metadata 或离线校验，路径错误可能不会被发现；涉及真实工具分支时必须带项目资源执行 compile / validate。
-
-## 限制
-
-- 所有 case 和 `FALSE` 必须连边。
-- 至少有一个 case；每个 case 至少有一个 condition。
-- 每个 condition 必须有 `variableSelector` 和 `comparisonOperator`。
-- 除 `EMPTY` / `NOT_EMPTY` 外，condition 必须有非空 `value`。
-- `varType: boolean` 的 `value` 推荐使用前端保存的字符串 `"true"`、`"false"`；运行时也能把布尔值或 `"1"/"yes"` 转成 true，但不要依赖非前端格式。
-- `varType: array` 只能做空值或长度比较；运行时不支持 `CONTAINS` / `NOT_CONTAINS`，会抛节点执行错误。需要判断数组元素内容时先用 CODE 拆出稳定 output。
-- `variableSelector` 引用上游变量，支持 `SYSTEM`、`TOOL`、`EXTRACT`、`CODE`、`LLM`、`AGENT`、`HUMAN_REVIEW`。
-- 判断工具状态映射用 `["TOOL", "<tool_node_id>", "ACTION_STATUS_NAME"]`。
-- `AGENT` selector 只能引用当前上游路径已连通 nextStep 的 `params[].name`。
-- TOOL 输出 selector 不加 `"output"` 层。
-- TOOL 嵌套输出使用分段 `path`，例如 `{"tool":"lookup_order","path":["order","shipping_method_no"]}`；不要写点号字段。
-- TOOL 数组出参按叶子字段处理，不要直接写 `["items", "0", "sku"]` 或假设 validator 会理解数组元素路径；需要拆数组时先用 CODE 输出稳定标量。
-- EXTRACT selector 第三段是 extract `id`，不是 `name`。
-- SYSTEM selector 不能省略嵌套字段的父级 id。
-- CODE selector 可以是 `["CODE", node_id]` 或 `["CODE", node_id, fieldName]`；IF_ELSE 判断具体字段时必须使用三段式，并且 `fieldName` 存在于 CODE outputs。运行时不支持 `["CODE", node_id, "obj", "field"]` 这种继续下钻。
-
-## Common Mistakes
-
-- 用 IF_ELSE 判断自然语言语义。语义判断应使用 `AGENT(next_steps)` 或 `INTENT`。
-- 忘记 `FALSE` 兜底。
-- 引用不存在的 TOOL 输出路径，例如未确认 `responseParam` 就写 `["status"]`。
-- 需要判断工具 actionStatus 却写成普通 TOOL 字段；应使用 `tool_status` 或完整图的 `ACTION_STATUS_NAME`。
-- 引用 CODE 中没有声明为 output 的临时变量；下游只能读 `outputs[].field_name`。
-- 引用不是当前 IF_ELSE 上游的 TOOL / CODE 节点；需要先补边或重排图。
-- boolean 条件把 `value` 写成 `["true"]`、布尔值或其它文本；前端标准格式是字符串 `"true"`、`"false"`，数组会被运行时整体字符串化并可能造成反向误判。
-- 用 `["EXTRACT", node_id, "order_no"]` 引用提取结果；应使用提取项 id。

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

@@ -1,79 +0,0 @@
-# INTENT
-
-## 功能概述
-
-根据上下文识别用户意图并分流。意图直接定义在节点内，不调用系统意图创建接口。
-
-INTENT 是业务分类路由节点，等价于“把客户表达归入有限客户意图，再进入对应处理流程”。每个 intent
-都应该代表一个可解释的客户意图和后续 SOP 路径，不是技术状态名的包装，也不是把所有分支汇入一个
-泛化 AGENT 的前置分类壳。
-
-## INTENT 全局 prompt 与历史
-
-`prompt` 默认 `null`。只有需求明确需要配置该节点的单独pe时才生成，并在生成后询问用户是否启用；用户拒绝则保留 `prompt: null`。每个 intent 仍须有清晰 `desc` 和独立可解释的下游路径。`history_round_limit` 默认 `null`，仅在用户明确指定历史范围时配置。
-
-## 创建方式
-
-```json
-{
-  "key": "intent_router",
-  "type": "intent",
-  "prompt": "Classify the user's request using the intent boundaries below. Choose the most specific matching intent; use OTHER when unclear or out of scope.",
-  "intents": [
-    {"id": "order_issue", "name": "Order_Issue", "desc": "User asks about an order."},
-    {"id": "refund_request", "name": "Refund_Request", "desc": "User wants a refund."}
-  ]
-}
-```
-
-## 创建参数
-
-| 字段                 | 说明                                                                                                     |
-|----------------------|----------------------------------------------------------------------------------------------------------|
-| intents[].id         | 必填，作为出边 handle                                                                                    |
-| intents[].name       | 意图名，默认英文 ASCII                                                                                   |
-| intents[].desc       | 新定义意图必填，描述识别的规则、边界                                                                     |
-| intents[].intentId   | 可选，复用已有系统意图                                                                                   |
-| intents[].examples   | 可选示例话术                                                                                             |
-| prompt               | 可选的意图节点全局识别提示（PE）。未明确需要时为 `null`；仅在确有跨意图边界、优先级或范围约束时配置      |
-| use_chat_history     | 是否结合历史，默认 true                                                                                  |
-| history_round_limit  | 可选，编译为 `historyRoundLimit`；默认 `None/null`（交由后端默认策略），`-1` 表示全部历史，正数表示最近 N 轮（1-10）。 |
-
-## Edges
-
-每个 intent 一条边，另加 `OTHER`。
-
-`intents` 可写对象数组。edges 的 `on` 可使用 intent `id` 或 `name`，最终按 `id` 生成 handle。复用系统意图时写 `intentId`；新定义意图时必须写清楚 `name` 和 `desc`。
-
-每个客户意图默认必须进入不同的处理路径。多个 intent 共享同一个下游只在以下条件全部满足时允许：
-
-- 客户意图虽然表达不同，但业务处理动作完全一致；
-- 需要收集的字段、调用工具、模板/回复合同、转人工原因和终态完全一致；
-- `mapping_explanations` 写明共享理由。
-
-否则不能把多个 intent 都连到同一个 generic AGENT 或同一个泛化处理节点。遇到多个意图当前看起来
-处理相似时，优先拆出共享的后置子流程：`INTENT -> 不同业务入口 -> 共享工具/回复/转人工节点`，
-而不是直接让所有 intent 指向同一个大 AGENT。
-
-## Resource Dependencies
-
-如要复用已有意图，先查意图：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-intents --pretty
-```
-
-## 限制
-
-- 每条意图必须有 `name + desc` 或 `intentId`。
-- name 不能重复。
-- 每个 intent handle 和 `OTHER` 都必须连边。
-- 每个 intent 的出边目标必须能读出对应客户意图的处理路径；无证据不要全部汇入同一个 AGENT。
-- `useChatHistory` 完整 graph 默认为 true；source 通常不用改。
-
-## Common Mistakes
-
-- 写 `description` 字段。source JSON 使用 `desc`。
-- 只写 name 不写 desc，导致后端校验“意图描述为空”。
-- 把分类结果全部接到同一个处理 AGENT，导致意图节点只剩形式分类，没有实际 SOP 分流。
-- 用技术字段或工具状态当 intent 名称；INTENT 应描述客户意图，结构化字段判断用 IF_ELSE 或 TOOL status。

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

@@ -1,43 +0,0 @@
-# KNOWLEDGE_REPLY
-
-## 功能概述
-
-兼容多轮知识回复节点。仅用于用户明确要求保留，或已有图中原样维护。
-
-## 创建方式
-
-```json
-{
-  "key": "compat_knowledge",
-  "type": "knowledge_reply",
-  "prompt": "Answer based on the knowledge base.",
-  "kb_dirs": [1001]
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| prompt | 知识回答要求 |
-| kb_dirs | knowledgeDirectoryIds |
-| max_rounds | 多轮最大轮数 |
-| disable_prev_node_results | 是否不把前序节点结果注入知识回答上下文，默认 false |
-
-## Edges
-
-必须同时有 `RESOLVED` 和 `UNRESOLVED`。
-
-## Resource Dependencies
-
-先确认知识库目录 id。
-
-## 限制
-
-- 新建默认不要用。
-- 保留时必须补齐双出边。
-
-## Common Mistakes
-
-- 新图误用 KNOWLEDGE_REPLY。
-- 缺少 `UNRESOLVED` 转人工路径。

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

@@ -1,117 +0,0 @@
-# LLM
-
-## 功能概述
-
-纯模型处理节点。用于生成文本、总结、改写、抽取或把上游信息整理成后续节点可用的结果。
-
-LLM 的结果供下游节点使用，不直接作为对客回复发送。它不等待用户、不调用外部工具，也不自己决定多条出边；需要这些能力时选择对应节点。
-
-LLM 和 AGENT 的边界：
-
-- `LLM`：只调模型，不调用外部工具，不使用 `next_steps` 做路由。
-- `AGENT`：需要模型自主调用真实工具，或需要通过 `next_steps` 选择后续节点。
-- `REPLY(PROMPT)`：只负责对用户发送一段回复，不用于生成内部中间结果。
-
-## 创建方式
-
-```json
-{
-  "key": "summarize_case",
-  "type": "llm",
-  "prompt": "Summarize the customer's issue and [[var:{\"system\":{\"category\":\"Order\",\"path\":[2742]}}]] for downstream decision making.",
-  "history_round_limit": 3,
-  "structured_output": {
-    "enabled": true,
-    "schema": {
-      "type": "object",
-      "properties": {
-        "summary": {"type": "string"},
-        "needs_handoff": {"type": "boolean"}
-      },
-      "required": ["summary"]
-    }
-  }
-}
-```
-
-需要按上游图片/附件 URL 调模型时，开启 vision 并给出 URL selector：
-
-```json
-{
-  "key": "inspect_attachment",
-  "type": "llm",
-  "prompt": "Describe the image for downstream processing.",
-  "vision": {
-    "enabled": true,
-    "detail": "high",
-    "media_selectors": [["SYSTEM", "Customer", 2780]]
-  }
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| prompt | 模型处理指令；完整 graph 字段为 `promptTemplate` |
-| history_round_limit | `0` 不带历史（默认）；`-1` 全部历史；正数带最近 N 轮 |
-| use_long_memory | 是否注入长记忆，默认 false |
-| vision.enabled | 是否附加图片输入，默认 false |
-| vision.detail | `auto` / `low` / `high`，默认 `auto` |
-| vision.media_selectors | 图片 URL 或 URL 数组的上游 selector；source 可写 `media_selectors` 或 `mediaSelectors` |
-| structured_output.enabled | 是否要求模型按 JSON Schema 输出对象 |
-| structured_output.schema | 开启时必填；根必须是 `type: object` 且有 `properties` |
-
-## Edges
-
-仅 `SOURCE` 单出边。LLM 不承担多分支路由；需要根据 LLM 结果分支时，后接 `IF_ELSE`、`INTENT` 或 `AGENT(next_steps)`。
-
-## Output Variables
-
-普通文本输出使用：
-
-```json
-{"variableSelector": {"llm": "summarize_case", "field": "text"}}
-```
-
-完整 graph selector：
-
-```json
-["LLM", "<llm_node_id>", "text"]
-```
-
-开启 `structured_output` 后，下游可以选择整个结构化对象或对象字段：
-
-```json
-{"variableSelector": {"llm": "summarize_case", "path": ["structured_output", "summary"]}}
-```
-
-完整 graph selector：
-
-```json
-["LLM", "<llm_node_id>", "structured_output", "summary"]
-```
-
-`structured_output` 未开启时，不得引用该路径。
-
-## Resource Dependencies
-
-变量模板通过标准 selector 读取上游 `SYSTEM`、`TOOL`、`EXTRACT`、`CODE`、`LLM`、`AGENT`、`HUMAN_REVIEW` 或 `NODE` 输出；图片 selector 必须在当前 LLM 的上游路径上，并在运行时解析成 HTTP(S) 图片 URL。
-
-## 限制
-
-- 必须有入边和 `SOURCE` 出边。
-- `prompt` / `promptTemplate` 必须非空。
-- 不绑定 `plugins` / `usedPlugins`；需要工具调用时用 AGENT 或 TOOL。
-- 不配置 `next_steps`；需要模型选择下游时用 AGENT。
-- prompt 会渲染 `[[var:[...]]]`。source 模板可用 selector 简写，例如 `[[var:{"code":"normalize_case","field":"summary"}]]`；编译后会替换为真实 node id。
-- `vision.enabled=true` 时至少配置一个 `media_selectors`；每个 selector 的值必须在运行时解析为 HTTP(S) 图片 URL 或 URL 数组。
-- `structured_output.enabled=true` 时 schema 根必须是 object，`required`（若存在）必须是数组。
-- 旧 `aiFieldIds`、`modelId`、`outputs` / `outputVariables` 不属于当前 LLM 运行时契约；source 顶层使用这些字段会被 builder 拒绝，已有 graph 出现它们时 validator 只会警告其被忽略。
-
-## Common Mistakes
-
-- 用 LLM 调外部 HTTP 工具；应使用 AGENT with plugins 或 TOOL。
-- 用 LLM 做多出口路由；应使用 AGENT(next_steps)、INTENT 或 IF_ELSE。
-- 用 REPLY(PROMPT) 生成内部摘要，导致内容发给用户。
-- 把 `summary` 直接写成 `['LLM', node_id, 'summary']`；当前运行时要么取 `text`，要么取 `structured_output` 路径。

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

@@ -1,38 +0,0 @@
-# NOTE
-
-## 功能概述
-
-画布注释节点，只用于给搭建者留下说明，不参与 CHAT_FLOW 运行。
-
-前端创建 NOTE 时使用 `type: CUSTOM_NOTE`、`data.category: NOTE`、`data.config.noteText`；后端 `GraphJSONLoader` 解析节点时会跳过 `CUSTOM_NOTE`。
-
-## 创建方式
-
-通常不要在 source JSON 中新建 NOTE。只有在增量维护已有图并需要保留画布备注时，才保留已有 NOTE。
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| type | 完整 graph 中为 `CUSTOM_NOTE` |
-| data.category | `NOTE` |
-| data.config.noteText | 注释文本 |
-
-## Edges
-
-无运行边。NOTE 不需要从 START 可达，也不要求入边或出边。
-
-## Resource Dependencies
-
-无。
-
-## 限制
-
-- NOTE 不参与运行、变量、工具、模板、路由或发布后的执行逻辑。
-- 不要连接 NOTE 节点；连线不会表达业务路径。
-- 校验运行图时不要把孤立 NOTE 当作异常。
-
-## Common Mistakes
-
-- 把 NOTE 未连接 START 当作图异常提醒用户。
-- 用 NOTE 表达业务流程中的条件、回复或人工说明。

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

@@ -1,97 +0,0 @@
-# QUESTION
-
-## 功能概述
-
-向用户提问。`USER_REPLY` 用于按用户选择分支；`VARIABLE` 用于收集变量系统字段。
-
-它是画布中明确的“等待用户”节点：发送提问后流程暂停，收到新消息后才通过对应 reply handle 或收集结果继续。适合信息补全、确认、否认和有限选项；不承担外部调用或复杂推理。
-
-## 创建方式
-
-```json
-{
-  "key": "ask_platform",
-  "type": "question",
-  "mode": "USER_REPLY",
-  "question": "Please choose a platform: TikTok, Amazon, or Shopify.",
-  "replies": ["TikTok", "Amazon", "Shopify"],
-  "max_rounds": 3
-}
-```
-
-```json
-{
-  "key": "collect_email",
-  "type": "question",
-  "mode": "VARIABLE",
-  "question": "Please provide your email.",
-  "variables": [2744]
-}
-```
-
-```json
-{
-  "key": "ask_platform_with_template",
-  "type": "question",
-  "mode": "USER_REPLY",
-  "question_type": "TEMPLATE",
-  "question_template_id": 12345,
-  "replies": ["TikTok", "Amazon", "Shopify"]
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| mode | `USER_REPLY` / `VARIABLE` |
-| question_type | `PROMPT` / `TEMPLATE`，默认 `PROMPT` |
-| question | `PROMPT` 提问文案 |
-| question_template_id | `TEMPLATE` 提问模板 id |
-| replies | USER_REPLY 的选项 |
-| variables | VARIABLE 模式收集的变量系统字段 ids |
-| max_rounds | 最大追问轮数，默认 5 |
-| condition | VARIABLE 多字段收集完成条件：`AND` / `OR`，默认 `AND` |
-| use_chat_history | 识别/收集时是否使用会话历史，默认 true |
-
-## Edges
-
-- USER_REPLY：每个 reply 一条边，另加 `OTHER`。
-- VARIABLE：仅 `SOURCE`。
-
-`replies` 可写字符串数组，也可写对象数组：
-
-```json
-[
-  {"id": "TIKTOK", "name": "TikTok"},
-  {"id": "AMAZON", "name": "Amazon"}
-]
-```
-
-对象写法更稳定；edges 的 `on` 可使用 reply `id` 或 `name`，最终按 `id` 生成 handle。字符串写法会用清洗后的名称作为 `id`。
-
-## Resource Dependencies
-
-VARIABLE 模式先查变量系统字段：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-ai-fields --pretty
-```
-
-## 限制
-
-- USER_REPLY 的 `replies[].name` 必须能清洗为 ASCII。
-- USER_REPLY 每个 reply 必须有非空 `id` 和 `name`，`name` 不能重复。
-- USER_REPLY 必须连完全部 reply 和 `OTHER`。
-- `PROMPT` 必须有 `question`；`TEMPLATE` 必须有 `question_template_id`。
-- 必须至少配置 `variables` 或 `replies`。
-- VARIABLE 模式必须配置 `variables`；USER_REPLY 模式必须配置 `replies`。
-- QUESTION 自身负责多轮追问和等待用户输入；不要用图层回环实现追问。
-- “请提供/请上传”只有在 QUESTION 中才构成真实收集；如果需要先解释收集原因，可用 `REPLY → QUESTION`，不能用 REPLY 代替 QUESTION。
-
-## Common Mistakes
-
-- 想要分支却用 REPLY。
-- 忘记 `OTHER` 兜底边。
-- 为多轮追问画环；应使用 `max_rounds`。
-- 模板提问写成 `reply_type=TEMPLATE`。QUESTION 使用 `question_type=TEMPLATE`。

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

@@ -1,68 +0,0 @@
-# RAG_REPLY
-
-## 功能概述
-
-单轮知识库检索并回复。新建知识库问答默认使用该节点。
-
-RAG_REPLY 会先用配置的知识目录检索，再向用户发送答案。它的输出取决于知识是否命中：命中走
-`TRUE`，未命中走 `LACK_KNOWLEDGE`。它不是普通固定话术节点，也不负责调用业务工具或执行开放式流程决策。
-
-## 创建方式
-
-```json
-{
-  "key": "product_knowledge",
-  "type": "rag_reply",
-  "prompt": "Answer based on the selected knowledge base.",
-  "kb_dirs": [1001, 1002],
-  "knowledge_keyword_ids": [11, 13],
-  "knowledge_keyword_selector": ["SYSTEM", "Order", "isolation_keyword"],
-  "customize_query": true,
-  "query_selector": ["EXTRACT", "extract_question", "question_text"]
-}
-```
-
-## 创建参数
-
-| 字段 | 说明 |
-|------|------|
-| prompt | 知识回答要求；普通文本 |
-| kb_dirs | knowledgeDirectoryIds；可选，未配置时节点不会检索知识并通常走 `LACK_KNOWLEDGE` |
-| knowledge_keyword_ids | knowledgeKeywordIds；隔离关键词 ID 数组，限定检索范围/隔离条件 |
-| knowledge_keyword_selector | knowledgeKeywordSelector；变量选择器，运行时值为隔离关键词名称或名称数组；由模型根据关键词来源自动选择 selector 类型 |
-| customize_query | 是否用变量作为检索 query |
-| query_selector | `customize_query=true` 时必填的上游变量选择器 |
-| disable_prev_node_results | 是否不把前序节点结果注入知识回答上下文，默认 false |
-
-## Edges
-
-必须同时有 `TRUE` 和 `LACK_KNOWLEDGE`。运行时 `TRUE` 分支如果有出边，chatflow 后端会注入 `WAIT -> USER_INPUT -> 原 TRUE 下游`，也就是知识回复命中并回复用户后，等待下一轮用户输入再继续后续流程；`LACK_KNOWLEDGE` 直接走缺知识兜底分支。
-
-如果命中知识后不需要继续流程，`TRUE` 可连 `$finish`；如果希望命中后继续处理下一轮用户输入，`TRUE` 连后续节点并接受上述等待语义。
-
-## Resource Dependencies
-
-先确认知识库目录 id。目录为空会导致总走 `LACK_KNOWLEDGE`。
-
-## 限制
-
-- 新建默认用 RAG_REPLY，不用 KNOWLEDGE_REPLY。
-- `kb_dirs` / `knowledgeDirectoryIds` 是可选的；未配置或为空时，节点没有可检索目录，通常会走 `LACK_KNOWLEDGE`。只有用户明确要求空知识路径时才省略它。
-- 使用固定隔离关键词时设置 `knowledgeKeywordIds`，值必须是通过 `kb-builder` 查询到的关键词数字 ID，不要把关键词文本直接填进去。
-- 使用运行时变量决定隔离关键词时设置 `knowledgeKeywordSelector`，变量值必须是关键词名称或名称数组；需要先用 `kb-builder` 搜索/创建关键词，确认名称与知识中心一致。selector 类型按变量实际来源选择：系统字段用 `SYSTEM`，工具输出用 `TOOL`，提取/代码/LLM/AGENT/人工审核输出分别用对应类型。
-- `knowledgeKeywordIds` 与 `knowledgeKeywordSelector` 默认互斥：固定关键词使用 ID，动态关键词使用 selector。后端尚未明确两者同时配置时的合并语义，因此 validator 会拒绝同时配置。
-- `prompt` 不插变量；需要变量作为检索 query 时用 `customize_query=true` + `query_selector`。
-- `query_selector` 支持 `SYSTEM`、`TOOL`、`EXTRACT`、`CODE`、`LLM`、`AGENT`、`HUMAN_REVIEW`。
-- EXTRACT selector 第三段是 extract `id`，不是 `name`。
-- 不使用工具状态 `ACTION_STATUS_NAME` 作为检索 query。
-- `AGENT` selector 只能引用当前上游路径已连通 nextStep 的 `params[].name`。
-
-## Common Mistakes
-
-- 忘记 `LACK_KNOWLEDGE` 兜底。
-- 知识目录为空还以为会命中知识。
-- 把隔离关键词文本填入 `knowledgeKeywordIds`；该字段只接受关键词 ID。
-- 未先查询/创建隔离关键词就配置 ID，导致节点引用不存在的关键词。
-- 用户要求按变量切换隔离关键词，却误用 `querySelector`；前者使用 `knowledgeKeywordSelector`，后者只控制检索 query。
-- `customize_query=true` 但没配置 `query_selector`。
-- 把检索 query 写成 prompt 里的变量模板。