@shulex/cxclawctl 0.1.2 → 0.1.3

package/skills/agent-builder/references/tools/http-tool.md

@@ -1,315 +0,0 @@
-# HTTP 工具
-
-本文描述 `EXTERNAL_HTTP_CALL` 工具的真实保存结构。底层接口和字段仍使用 `plugin` / `pluginId` / `queryPlugin` 命名。
-
-## API 与 CLI
-
-| 操作 | 方法 | 路径 |
-|---|---|---|
-| 列表 | POST | `/api_v2/gpt/ap/queryPlugin` |
-| 详情 | POST | `/api_v2/gpt/ap/queryPlugin`，body 带 `pluginId`、`convertStrategyV5=true` |
-| 创建 | POST | `/api_v2/gpt/ap/createPlugin` |
-| 更新 | POST | `/api_v2/gpt/ap/updatePlugin` |
-| 删除 | POST | `/api_v2/gpt/ap/deletePlugin` |
-| 调试（不保存） | POST | `/api_v2/gpt/ap/runHttpPlugin` |
-| 根据真实响应构建输出 | POST | `/api_v2/gpt/ap/{projectId}/build/plugin` |
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-plugins --pretty
-npx --yes @shulex/cxclawctl@latest api get-plugin --id <tool_id> --pretty
-npx --yes @shulex/cxclawctl@latest api create-plugin \
-  --data-file /workspace/state/agent-builder/tool_<name>.json --pretty
-npx --yes @shulex/cxclawctl@latest api update-plugin \
-  --data-file /workspace/state/agent-builder/tool_<name>.json --pretty
-```
-
-大 JSON 不要内联到 `--data`。创建前必须先查重、静态验证并确认写入；创建后用返回的 ID 执行 `get-plugin` 回查。
-
-`update-plugin` 是完整对象更新，payload 需要带 `pluginId`；可基于 `get-plugin` 返回的完整定义修改目标字段。
-
-## 完整外层结构
-
-```json
-{
-  "name": "lookup_order",
-  "description": "按订单号查询订单是否存在",
-  "type": "EXTERNAL_HTTP_CALL",
-  "source": "MANUAL",
-  "visible": true,
-  "meta": {
-    "category": "MANUAL",
-    "externalHttpCallConfig": {
-      "url": "https://example.com/api/order",
-      "method": "POST",
-      "headerParams": [
-        {
-          "name": "Content-Type",
-          "description": "JSON request",
-          "value": "application/json"
-        }
-      ],
-      "requestParam": {
-        "items": []
-      },
-      "responseParam": {
-        "items": []
-      },
-      "actionStatuses": []
-    }
-  }
-}
-```
-
-- 普通接口使用 `meta.category: "MANUAL"`，并提供非空 `url`。`method` 使用接口真实方法。
-- Header 结构为 `name`、`value`、`description`。Authorization、X-Token 等鉴权值和普通 Header 一样写入 `value`。
-- 工具只能放到 AGENT 节点的 `usedPlugins`，或由 TOOL 节点引用；不要放进 Output 区域。
-
-## 参数 schema
-
-`requestParam.items` 和 `responseParam.items` 的每个元素都是 `HttpParamDTO.Item`：
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `name` | string | 必须非空、不能包含 `.`，同一层级必须唯一 |
-| `description` | string | 参数说明；建议始终提供 |
-| `required` | boolean | 是否必填，主要用于请求参数 |
-| `type` | string | `string` / `integer` / `number` / `date` / `boolean` / `array` / `object` |
-| `effect` | boolean | 是否对模型/返回结果生效，通常为 `true` |
-| `source` | string | 请求值来源，缺省语义为 `LLM` |
-| `ref` | object | 可选字段映射，服务端 Pair 结构通常是 `{"key":"...","value":"..."}` |
-| `value` | any | `source: "CUSTOMIZE"` 时的固定值 |
-| `listSubItem` | Item | `type: "array"` 时必填，描述唯一的元素类型 |
-| `objectItems` | Item[] | `type: "object"` 时必填且非空，描述对象字段 |
-
-`source` 常见取值：`LLM`、`CONVERSATION`、`ORDER`、`LOGISTIC`、`TICKET`、`AGENT_OUTPUT`、`CUSTOMIZE`、`METADATA`。使用非 `LLM` 来源前，应确认对应运行时确实提供该数据。
-
-复杂类型示例：
-
-```json
-{
-  "name": "data",
-  "description": "response body",
-  "type": "object",
-  "effect": true,
-  "objectItems": [
-    {
-      "name": "items",
-      "description": "order lines",
-      "type": "array",
-      "effect": true,
-      "listSubItem": {
-        "name": "item",
-        "description": "one line",
-        "type": "object",
-        "effect": true,
-        "objectItems": [
-          {
-            "name": "quantity",
-            "description": "quantity",
-            "type": "integer",
-            "effect": true
-          }
-        ]
-      }
-    }
-  ]
-}
-```
-
-`array` 的 `listSubItem.name` 是元素描述名，不进入状态映射路径；上例数量字段的精确 `apiName` 是 `data.items.quantity`。
-
-## actionStatuses
-
-`actionStatuses` 用于 TOOL 节点启用 `enableActionStatus=true` 后的分支。每项结构是：
-
-```json
-{
-  "name": "found",
-  "condition": {
-    "or": [
-      {
-        "rules": [
-          {
-            "type": "GENERIC",
-            "apiName": "data.exists",
-            "apiType": "BOOLEAN",
-            "relation": "EQUAL",
-            "values": [true]
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-- `condition.or` 中的组彼此是 OR；同一组的 `rules` 彼此是 AND。
-- 每条规则必须完整提供 `type`、`apiName`、`apiType`、`relation`、`values`。当前普通 HTTP 状态规则使用 `type: "GENERIC"`。
-- `apiName` 必须是 `responseParam.items` 中字段的完整精确路径。对象层级以 `.` 连接；数组元素描述名不计入路径。不能只写叶子名，也不能用参数 `name` 自带点号来伪造路径。
-- `object` 本身不能作为状态条件；应选择其可比较的后代字段。
-- 最后一项必须是默认状态，后端与 UI 兼容两种空条件：`"condition": {}` 或 `"condition": {"or": []}`。新建配置推荐 canonical `"condition": {}`；`{"or": []}` 同样合法，不能判为非法。默认状态只能放最后。
-
-### 参数类型到 apiType
-
-| response `type` | 可用 `apiType` |
-|---|---|
-| `string` | `TEXT` |
-| `integer` / `number` | `NUMBER` |
-| `date` | `DATE_TO_NOW` 或 `NOW_TO_DATE` |
-| `boolean` | `BOOLEAN` |
-| `array` | `ARRAY_SIZE` |
-| `object` | 不支持作为条件 |
-
-### apiType 到 relation
-
-| `apiType` | 可用 `relation` | `values` 规则 |
-|---|---|---|
-| `TEXT` | `CONTAIN`, `NOT_CONTAIN`, `IS_EMPTY`, `NOT_EMPTY`, `EQUAL`, `NOT_EQUAL` | `CONTAIN` / `NOT_CONTAIN` 可有一个或多个字符串；`EQUAL` / `NOT_EQUAL` 一个字符串 |
-| `NUMBER` | `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `LESS_THAN_OR_EQUAL`, `BETWEEN`, `EQUAL`, `NOT_EQUAL`, `IS_EMPTY`, `NOT_EMPTY` | JSON 数值或前端保存的数值字符串；`BETWEEN` 恰好两个，其余比较恰好一个 |
-| `DATE_TO_NOW` / `NOW_TO_DATE` | 同 `NUMBER` | JSON 数值或数值字符串；`BETWEEN` 恰好两个 |
-| `ARRAY_SIZE` | 同 `NUMBER` | JSON 数值或数值字符串；`BETWEEN` 恰好两个 |
-| `BOOLEAN` | `EQUAL`, `NOT_EQUAL`, `IS_EMPTY`, `NOT_EMPTY` | 后端同时接受 JSON boolean `true` / `false` 和前端保存的字符串 `"true"` / `"false"`；手写 JSON 推荐 boolean |
-
-`IS_EMPTY` / `NOT_EMPTY` 的 `values` 必须是空数组 `[]`。虽然底层 `LogicalRelationEnum` 还包含 `IN`、`NOT_IN`、`EXACT_CONTAINS`、`NOT_EXACT_CONTAINS`，当前工具详情页和静态 validator 不接受它们用于上述 HTTP 状态映射；不要在新配置中使用。
-
-## 合法完整示例：`data.exists` boolean
-
-```json
-{
-  "name": "lookup_order",
-  "description": "按订单号查询订单是否存在",
-  "type": "EXTERNAL_HTTP_CALL",
-  "source": "MANUAL",
-  "visible": true,
-  "meta": {
-    "category": "MANUAL",
-    "externalHttpCallConfig": {
-      "url": "https://example.com/api/order",
-      "method": "POST",
-      "headerParams": [
-        {
-          "name": "Content-Type",
-          "description": "JSON request",
-          "value": "application/json"
-        }
-      ],
-      "requestParam": {
-        "items": [
-          {
-            "name": "order_id",
-            "description": "订单号",
-            "required": true,
-            "type": "string",
-            "effect": true,
-            "source": "LLM"
-          }
-        ]
-      },
-      "responseParam": {
-        "items": [
-          {
-            "name": "data",
-            "description": "查询结果",
-            "type": "object",
-            "effect": true,
-            "objectItems": [
-              {
-                "name": "exists",
-                "description": "订单是否存在",
-                "type": "boolean",
-                "effect": true
-              }
-            ]
-          }
-        ]
-      },
-      "actionStatuses": [
-        {
-          "name": "found",
-          "condition": {
-            "or": [
-              {
-                "rules": [
-                  {
-                    "type": "GENERIC",
-                    "apiName": "data.exists",
-                    "apiType": "BOOLEAN",
-                    "relation": "EQUAL",
-                    "values": [true]
-                  }
-                ]
-              }
-            ]
-          }
-        },
-        {
-          "name": "not_found_or_error",
-          "condition": {}
-        }
-      ]
-    }
-  }
-}
-```
-
-旧错误 case 常把它写成 `apiName: "exists"`、`apiType: "TEXT"`、`relation: "eq"`、`values: ["true"]`。真正的错误有三处：路径缺少父级 `data`；boolean 必须映射到 `BOOLEAN`；关系必须是大写枚举 `EQUAL`。`values: ["true"]` 是前端可能保存的兼容格式，后端可接受；手写 JSON 时仍推荐更明确的 `values: [true]`。
-
-## 静态验证与写入
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/tools/validate_tool_config.py \
-  --data-file /workspace/state/agent-builder/tool_lookup_order.json \
-  --pretty
-```
-
-只有输出 `"valid": true` 才继续请求用户确认并创建。该命令取代“只确认 JSON 能解析”的弱校验：它还会拒绝非法类型、同层重名、缺失复杂类型子项、错误字段路径、类型/关系/值不匹配，以及默认状态位置错误。
-
-创建完成后：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-plugin --id <tool_id> --pretty
-```
-
-以回查结果确认名称、URL、方法、参数树和 `actionStatuses` 已按预期保存。
-
-## 调试安全边界
-
-`run-plugin` / `runHttpPlugin` 会真实访问目标 URL，不是纯校验：
-
-`run-plugin --data-file` 接收 envelope，而不是裸 `externalHttpCallConfig`。例如：
-
-```json
-{
-  "externalHttpCallConfig": {
-    "url": "https://example.com/api/order",
-    "method": "POST",
-    "headerParams": [
-      {
-        "name": "Content-Type",
-        "value": "application/json"
-      }
-    ],
-    "requestParam": {
-      "items": []
-    },
-    "responseParam": {
-      "items": []
-    },
-    "actionStatuses": []
-  },
-  "externalHttpCallRequestBody": {
-    "order_id": "ORDER-DEMO-001"
-  }
-}
-```
-
-```bash
-npx --yes @shulex/cxclawctl@latest api run-plugin \
-  --data-file /workspace/state/agent-builder/run_tool_config.json \
-  --pretty
-```
-
-- 仅当用户明确要求或明确授权实际调试时执行。
-- GET 等只读接口也不能因“创建工具”而默认调用。
-- POST / PUT / PATCH / DELETE 等可能写数据的接口，执行前额外确认本次请求体和影响范围。
-- 不得将“上线前必须运行”作为强制步骤；未授权时只做静态验证和保存结果回查。

package/skills/agent-builder/references/tools/mock-tool.md

@@ -1,279 +0,0 @@
-# Mock / Excel / CSV 工具
-
-Mock 工具不是新的 plugin 类型。保存到工具库时仍然是：
-
-```json
-{
-  "type": "EXTERNAL_HTTP_CALL",
-  "source": "MANUAL",
-  "meta": {
-    "category": "EXCEL",
-    "fileName": "logistics.xlsx"
-  }
-}
-```
-
-`EXCEL` 表示构建来源和 UI 展示方式；真正的数据保存在 MockData 表中，工具的 HTTP 配置指向同一环境的 MockData 搜索接口。
-
-## UI 与高级 CLI 的边界
-
-详情页上传 Excel / CSV 时，浏览器只读取第一个 sheet，转换成 JSON 数组，并将日期格式化、其他单元格调用 `toString()`。入参与出参也按首行列名生成顶层 `string` 字段。因此 UI 路径适合偏扁平的字符串记录。
-
-高级 CLI 可以直接向 MockData 写 JSON 数组，不是详情页的上传入口。它可以保留 number、boolean、object、array 等嵌套 JSON 类型；但是详情页的表格编辑器只按首条记录的顶层列展示。以后在 UI 打开、编辑并保存，数据会被 UI 当前表格状态全量重传，嵌套值可能被覆盖、字符串化或降级。需要保留嵌套类型时，后续仍使用 CLI 管理，并避免从 UI 重存数据。
-
-`get-plugin` 只读取保存的工具定义，不会调用工具原来的 URL，也不会查询 MockData 内容。数据回查要单独用 `query-mock-data`。
-
-## 标准创建流程
-
-MockData 的 `mock_type` 必须包含工具 ID，所以创建顺序和普通 HTTP 工具有所不同：
-
-1. `list-plugins --pretty` 查重，向用户说明将进行三类写操作：创建占位、全量替换 MockData、更新工具；取得确认。
-2. 创建最小占位工具，取得服务端返回的 `id`。
-3. 从 `fileName` 去掉最后一个扩展名得到 stem，再生成 `mock_type = <stem>_<id>`。例如 `logistics.mock.xlsx`、ID `321` 对应 `logistics.mock_321`。
-4. 按该 ID 准备最终工具配置，先运行 `validate_tool_config.py` 静态验证。
-5. 执行 `replace-mock-data --name <mock_type>` 全量替换数据。
-6. 在最终 payload 的普通 `headerParams` 中配置 `X-Token`，再执行 `update-plugin --data-file ... --pretty`。配置中 `method=POST`，URL 指向 `/api_v2/gpt/mockdata/searchMockData/<mock_type>`。
-7. 分别运行 `query-mock-data --name <mock_type>` 与 `get-plugin --id <id> --pretty` 回查数据和定义。
-
-占位配置示例：
-
-```json
-{
-  "name": "lookup_logistics_mock",
-  "description": "按物流单号查询测试物流记录",
-  "type": "EXTERNAL_HTTP_CALL",
-  "source": "MANUAL"
-}
-```
-
-```bash
-npx --yes @shulex/cxclawctl@latest api create-plugin \
-  --data-file /workspace/state/agent-builder/mock_placeholder.json \
-  --pretty
-```
-
-创建结果中的 ID 是后续所有步骤的同一个 `<tool_id>`。不要猜 ID，也不要在不同工具之间复用 `mock_type`。
-
-## 数据文件与替换命令
-
-`/workspace/state/agent-builder/logistics_mock_records.json`：
-
-```json
-[
-  {
-    "tracking_number": "TRACK-DEMO-001",
-    "carrier": "DemoCarrier",
-    "delivered": false,
-    "latest_status": {
-      "status": "InTransit",
-      "description": "Package left the sorting center"
-    },
-    "events": [
-      {
-        "time": "2026-07-16T09:30:00+08:00",
-        "location": "Shanghai",
-        "description": "Departed facility"
-      }
-    ],
-    "days_after_last_update": 1
-  },
-  {
-    "tracking_number": "TRACK-DEMO-002",
-    "carrier": "DemoCarrier",
-    "delivered": true,
-    "latest_status": {
-      "status": "Delivered",
-      "description": "Delivered to recipient"
-    },
-    "events": [],
-    "days_after_last_update": 0
-  }
-]
-```
-
-为匹配字段设置稳定的顶层查询键；上例只使用 `tracking_number`。同一 `mock_type` 中，不同记录的查询键值组合不得重复；如果用 `tracking_number` 和 `carrier` 联合查询，则二者的组合必须唯一。组合重复时搜索只返回数据库结果中的第一条，结果不确定。
-
-确认写操作后执行：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api replace-mock-data \
-  --name logistics_mock_<tool_id> \
-  --data-file /workspace/state/agent-builder/logistics_mock_records.json \
-  --pretty
-```
-
-`--name` 在这两个命令中就是 `mock_type`。`replace-mock-data` 会先删除当前租户下相同 `mock_type` 的全部旧记录，再写入新数组；不是追加或局部更新。数组最多 10,000 条，空数组会清空该类型。每次执行都属于写操作，必须在执行前确认本次全量替换的类型、条数和影响环境。
-
-## 最终工具配置
-
-最终配置仍使用 HTTP 工具参数 schema。`X-Token` 与其他 Header 一样配置在 `headerParams` 中。
-
-```json
-{
-  "pluginId": 321,
-  "name": "lookup_logistics_mock",
-  "description": "按物流单号查询测试物流记录",
-  "type": "EXTERNAL_HTTP_CALL",
-  "source": "MANUAL",
-  "visible": true,
-  "meta": {
-    "category": "EXCEL",
-    "fileName": "logistics_mock.json",
-    "externalHttpCallConfig": {
-      "url": "https://<current-host>/api_v2/gpt/mockdata/searchMockData/logistics_mock_321",
-      "method": "POST",
-      "headerParams": [
-        {
-          "name": "X-Token",
-          "description": "MockData API token",
-          "value": "<X_TOKEN>"
-        }
-      ],
-      "requestParam": {
-        "items": [
-          {
-            "name": "tracking_number",
-            "description": "物流单号，MockData 顶层查询键",
-            "required": true,
-            "type": "string",
-            "effect": true,
-            "source": "LLM"
-          }
-        ]
-      },
-      "responseParam": {
-        "items": [
-          {
-            "name": "tracking_number",
-            "description": "物流单号",
-            "type": "string",
-            "effect": true
-          },
-          {
-            "name": "carrier",
-            "description": "物流商",
-            "type": "string",
-            "effect": true
-          },
-          {
-            "name": "delivered",
-            "description": "是否签收",
-            "type": "boolean",
-            "effect": true
-          },
-          {
-            "name": "latest_status",
-            "description": "最新状态",
-            "type": "object",
-            "effect": true,
-            "objectItems": [
-              {
-                "name": "status",
-                "description": "状态码",
-                "type": "string",
-                "effect": true
-              },
-              {
-                "name": "description",
-                "description": "状态描述",
-                "type": "string",
-                "effect": true
-              }
-            ]
-          },
-          {
-            "name": "events",
-            "description": "物流事件",
-            "type": "array",
-            "effect": true,
-            "listSubItem": {
-              "name": "event",
-              "description": "单条事件",
-              "type": "object",
-              "effect": true,
-              "objectItems": [
-                {
-                  "name": "time",
-                  "description": "发生时间",
-                  "type": "string",
-                  "effect": true
-                },
-                {
-                  "name": "location",
-                  "description": "发生地点",
-                  "type": "string",
-                  "effect": true
-                },
-                {
-                  "name": "description",
-                  "description": "事件描述",
-                  "type": "string",
-                  "effect": true
-                }
-              ]
-            }
-          },
-          {
-            "name": "days_after_last_update",
-            "description": "距上次更新天数",
-            "type": "integer",
-            "effect": true
-          }
-        ]
-      },
-      "actionStatuses": []
-    }
-  }
-}
-```
-
-不要从被替代的原工具复制 URL 或 Header。Mock 工具必须使用当前环境 MockData URL 和当前环境凭据；原接口的域名、认证信息和业务 Header 都不应残留。
-
-用实际 `<tool_id>`、host 和安全注入后的本地 state 文件做静态验证，再更新：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/tools/validate_tool_config.py \
-  --data-file /workspace/state/agent-builder/tool_lookup_logistics_mock.json \
-  --pretty
-
-npx --yes @shulex/cxclawctl@latest api update-plugin \
-  --data-file /workspace/state/agent-builder/tool_lookup_logistics_mock.json \
-  --pretty
-```
-
-## 搜索语义
-
-MockData 搜索接口只保留请求 JSON 中的顶层 primitive/wrapper 值和 string；object、array 等复杂值不会进入查询条件。所有保留下来的顶层条件按 AND 精确匹配：
-
-```json
-{
-  "tracking_number": "TRACK-DEMO-001",
-  "carrier": "DemoCarrier",
-  "ignored_nested_filter": {
-    "status": "InTransit"
-  }
-}
-```
-
-实际匹配条件只有 `tracking_number` AND `carrier`。接口返回第一条命中记录；没有命中时返回：
-
-```json
-{"message":"no result"}
-```
-
-因此请求参数应优先只暴露必要的顶层查询键，保证不同记录的查询键值组合不重复；不要设计依赖嵌套字段过滤的 Mock 工具。
-
-## 回查与调试边界
-
-```bash
-npx --yes @shulex/cxclawctl@latest api query-mock-data \
-  --name logistics_mock_<tool_id> --pretty
-
-npx --yes @shulex/cxclawctl@latest api get-plugin --id <tool_id> --pretty
-```
-
-回查时确认：数据条数和嵌套类型正确；工具仍是 `EXTERNAL_HTTP_CALL`；`meta.category=EXCEL`；`fileName`、URL 中的 `mock_type` 与 ID 一致；方法为 POST；Header 为 `X-Token`。
-
-`run-plugin` 会真实调用 MockData 搜索接口。只有用户明确要求或授权时才运行，不能因为它通常是只读查询就自动执行。若今后工具 URL 被改成任何写接口，运行前还必须对具体请求和影响范围做额外确认。
-
-若 Mock 工具配置 `actionStatuses`，默认分支可使用 `"condition": {}` 或 UI 兼容形态 `"condition": {"or": []}`；两者都表示空条件且都合法。新建配置推荐前者。

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

@@ -1,46 +0,0 @@
-# 工具 Overview
-
-工具是 Agent 可调用的外部能力，常见类型是 `EXTERNAL_HTTP_CALL`。底层 API 和字段名仍使用 `plugin` / `pluginId` / `queryPlugin`。
-
-## 常用命令
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-plugins --pretty
-npx --yes @shulex/cxclawctl@latest api get-plugin --id <tool_id> --pretty
-npx --yes @shulex/cxclawctl@latest script skills/agent-builder/scripts/tools/validate_tool_config.py \
-  --data-file /workspace/state/agent-builder/tool_<name>.json --pretty
-npx --yes @shulex/cxclawctl@latest api create-plugin \
-  --data-file /workspace/state/agent-builder/tool_<name>.json --pretty
-npx --yes @shulex/cxclawctl@latest api update-plugin \
-  --data-file /workspace/state/agent-builder/tool_<name>.json --pretty
-npx --yes @shulex/cxclawctl@latest api run-plugin \
-  --data-file /workspace/state/agent-builder/run_tool_config.json --pretty
-npx --yes @shulex/cxclawctl@latest api replace-mock-data \
-  --name <mock_type> --data-file /workspace/state/agent-builder/mock_records.json --pretty
-npx --yes @shulex/cxclawctl@latest api query-mock-data \
-  --name <mock_type> --pretty
-```
-
-`list-plugins` 只返回精简列表。排查或配置入参、出参、`actionStatuses` 时用 `get-plugin` 查看完整定义。Header 与其他工具字段一样通过 `headerParams` 配置。MockData 命令复用 `--name` 表示 `mock_type`，不是工具名。
-
-## 创建流程
-
-普通 HTTP 工具按以下顺序处理：
-
-1. `list-plugins --pretty` 查重。
-2. 将配置写入 `/workspace/state/agent-builder/tool_<name>.json`；跨轮配置不能写 `/workspace/tmp/`。
-3. 运行 `validate_tool_config.py` 做静态验证。它不只检查 JSON 语法，还检查参数树、状态映射的精确字段路径、类型和关系。
-4. 展示和配置摘要，请用户确认。
-5. 执行 `create-plugin --data-file ...`。
-6. 从创建结果取得 ID，再执行 `get-plugin --id <tool_id> --pretty`，确认服务端保存后的完整定义与预期一致。
-
-Mock 工具必须先创建占位工具取得 ID，才能生成唯一的 `mock_type`；其完整顺序、安全确认和回查方式见 `mock-tool.md`。
-
-`run-plugin` 会实际请求工具配置中的目标接口。其 data file 必须使用 `{"externalHttpCallConfig": {...}, "externalHttpCallRequestBody": {...}}` envelope，完整示例见 `http-tool.md`。只有用户明确要求或授权调试时才能运行；若目标是写接口，还要在执行前单独确认。它不是创建工具的默认步骤，也不能表述为“上线前必须运行”。
-
-## 详细文档
-
-- HTTP 工具结构：`http-tool.md`
-- Mock / Excel / CSV 工具：`mock-tool.md`
-- Agent 工具配置：`tool-config.md`
-- X-Token / header patch：`x-token.md`

package/skills/agent-builder/references/tools/tool-config.md

@@ -1,43 +0,0 @@
-# Agent 工具配置
-
-## SINGLE_AGENT
-
-SINGLE_AGENT 通过 `usedPlugins` 绑定工具。优先使用工具 id 数组：
-
-```json
-{
-  "usedPlugins": [2019, 2020]
-}
-```
-
-配置前必须确认：
-
-- 工具 id 存在。
-- requestParam 必填项能由 LLM、metadata、固定值或上下文提供。
-- prompt 里提到的工具都在 `usedPlugins` 中。
-
-## CHAT_FLOW
-
-CHAT_FLOW 有两种用法：
-
-- `TOOL` 节点：直接调用单个工具，适合结构化结果和 actionStatus 分支。
-- `AGENT` 节点 `usedPlugins`：让 LLM 调工具并解释结果，适合非结构化判断。
-
-构图细节读：
-
-- `../chatflow/nodes/tool.md`
-- `../chatflow/nodes/agent.md`
-- `../chatflow/node-selection.md`
-
-## 查看详情
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-plugin --id <tool_id> --pretty
-```
-
-重点看：
-
-- `meta.externalHttpCallConfig.requestParam.items`
-- `meta.externalHttpCallConfig.responseParam.items`
-- `meta.externalHttpCallConfig.actionStatuses`
-- `headerParams`