Refactor tool execution pipeline

2026-06-21 14:30:40 +08:00
parent 3e5f0658b3
commit 99c1e9cd6c
81 changed files with 3587 additions and 5317 deletions
@@ -0,0 +1,115 @@
+# iAs 工具平台化改造 —— 当前状态
+
+> 最后更新：2024-06-18
+
+---
+
+## 一、架构
+
+```
+主进程（单 tokio 进程）
+├── 消息队列 (三消费者: LLM / Tool / Send)
+├── 工具注册器 (扫描 tools/*/specs/*.tool.yaml)
+├── 运行时 (executor::execute_loop: spawn → stdout → http/db/result)
+├── 审批 (ApprovalManager, oneshot 挂起)
+└── LLM (DeepSeek, 原生 tool_call, thinking 模式)
+
+工具层（独立进程，stdin→stdout，无网络依赖）
+├── tools/datetime/specs/    (1 工具, 470 KB)
+├── tools/weather/specs/     (3 工具, 437 KB)
+├── tools/amap/specs/        (6 工具, 441 KB)
+├── tools/memories/specs/    (5 工具, 437 KB)
+├── tools/web_search/specs/  (1 工具, 433 KB)
+└── tools/fetch_page/specs/  (1 工具, 435 KB)
+                         共 17 个工具, 总计 2.7 MB
+```
+
+---
+
+## 二、LLM 调用协议
+
+使用 DeepSeek 原生 `tool_call` (function calling)，非代码块。
+
+**2 个元工具注册给 API：**
+
+```json
+[
+  {"function": {"name": "query_capabilities", "description": "查询所有可用工具"}},
+  {"function": {"name": "call_capability", "description": "调用工具", "parameters": {"name": "工具名", "prompt": "JSON参数"}}}
+]
+```
+
+LLM 先调 `query_capabilities` 获取工具列表，再 `call_capability` 调具体工具。工具结果以 `role=tool` 插入上下文。
+
+---
+
+## 三、主进程↔工具协议
+
+工具为短生命周期进程。每次 spawn 读 stdin 一行 JSON，写 stdout 一行 JSON。
+
+**stdin 信封：**
+
+```json
+{"params": {"location": "北京"}, "approved": true, "user_id": "wxid"}
+```
+
+后继调用追加 `response` 或 `db_response` 字段。
+
+**stdout 消息：**
+
+| type | 含义 | 主进程行为 |
+|------|------|-----------|
+| `{"type":"http","method":"GET","url":"...","desc":"..."}` | HTTP 请求 | 审批→执行→re-spawn |
+| `{"type":"db","operation":"read_memories","params":{...}}` | DB 请求 | 执行 DB→re-spawn |
+| `{"type":"result","content":"..."}` | 最终结果 | 提取 content |
+
+---
+
+## 四、工具规范 (YAML)
+
+每个工具目录下 `specs/*.tool.yaml`，16 个字段：
+
+```yaml
+name: weather_now
+desc: 查询指定城市的实时天气（温度、体感温度、风向风力、湿度、气压、能见度）
+type: http
+tool: weather
+command: now
+path: /target/release/weather
+risk_level: low
+timeout_secs: 10
+env: [QWEATHER_KEY]
+params:
+  - name: location
+    required: true
+    desc: 城市名称，如"北京"、"上海"、"合肥"
+```
+
+---
+
+## 五、日志
+
+3 路文件日志 + 终端运维日志：
+
+| target | 文件 | 内容 |
+|--------|------|------|
+| `ias::msg` | msg.log | [用户] / [LLM] / [tool] |
+| `ias::raw` | raw.log | [llm-request] / [llm-response] |
+| `ias::err` | error.log | [spawn] [http] [timeout] [llm-chat] ... |
+
+---
+
+## 六、已清理
+
+| 删除 | 原因 |
+|------|------|
+| `src/tools/builtins/` (8 文件) | 迁移为独立工具 |
+| `src/tools/api_tool.rs` | 合并到 executor |
+| `src/tools/tool.rs` | Tool trait 不再需要 |
+| `src/tools/builtin.rs` | 兼容层 |
+| `src/tools/shell_tool.rs` | 不需要 |
+| `src/tools/stdio_tool.rs` | 合并到 executor |
+| `capability-lib/` | 工具不再需要底座 |
+| `tools/dist/` `tools/rules/` | 改为 tools/*/specs/ |
+| `cli.rs` ToolCommand 等枚举 | 改为动态 CLI |
+| `conversation.rs` 代码块解析 | 改为原生 tool_call |