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 |
@@ -0,0 +1,96 @@
+# 实现细节
+
+> 2024-06-18 当前状态
+
+---
+
+## 关键文件清单
+
+```
+src/
+├── daemon.rs          → 主控 (LLM/Tool/Send Consumer, Registry, execute_builtin)
+├── main.rs            → CLI (cmd_tool_dynamic, cmd_tools)
+├── cli.rs             → clap 命令定义
+├── logger.rs          → 三路日志初始化
+├── tools/
+│   ├── mod.rs         → 模块声明 (6 个)
+│   ├── spec.rs        → ToolSpec + ParamSpec
+│   ├── parser.rs      → parse_dir() YAML 解析 (4 tests)
+│   ├── registry.rs    → Registry (load/list/dispatch)
+│   ├── executor.rs    → execute_loop (spawn→stdout→http/db/result)
+│   └── approval.rs    → ApprovalManager (6位确认码)
+├── llm/
+│   ├── types.rs       → Message, ToolCall, StreamChunk, ConversationConfig
+│   ├── conversation.rs → Conversation (run_tool_loop, summarize)
+│   ├── deepseek.rs    → DeepSeek provider (tool_call 流式解析)
+│   └── provider.rs    → LlmProvider trait
+└── context/
+    ├── types.rs       → ChatSession, add_tool_result
+    └── builder.rs     → build_context (system prompt + 摘要 + 消息)
+```
+
+---
+
+## 工具调用全链路
+
+```
+用户消息
+  → LLM Consumer: 创建 Conversation, 注册 2 元工具
+  → LLM: 调 query_capabilities (tool_call)
+  → ToolExecutor → PipelineMessage::ToolCall → 消息队列
+  → ToolConsumer → execute_builtin → query_capabilities → 返回工具列表
+  → ToolResult → LLM Consumer → resume
+
+  → LLM: 调 call_capability(name="weather_now", prompt='{"location":"北京"}')
+  → ToolConsumer → execute_builtin → call_capability 解包
+    → registry.dispatch("weather_now", {"location":"北京"})
+    → executor::execute_loop
+      → spawn weather --command now
+      → stdout: {"type":"http","url":"...","desc":"..."}
+      → 审批(如需要) → reqwest::get → response
+      → spawn weather --command now (带 response)
+      → stdout: {"type":"result","content":"北京晴，25°C"}
+    → ToolResult
+  → LLM Consumer → resume → 生成回复
+  → Send Consumer → 微信
+```
+
+---
+
+## executor::execute_loop 状态机
+
+```
+spawn tool
+  → stdout JSON parse
+    ├─ {"type":"result","content":"..."} → 返回 content
+    ├─ {"type":"http","method":"GET","url":"..."}
+    │   → 审批(high risk) → HTTP → 存入 response
+    │   → re-spawn (带 response 字段)
+    └─ {"type":"db","operation":"read_memories",...}
+        → 审批 → MemoryStore 操作 → 存入 db_response
+        → re-spawn (带 db_response 字段)
+```
+
+---
+
+## 消息队列路由
+
+```rust
+MessageKind::UserMessage | ToolResult | ScheduledTask → LLM Consumer
+MessageKind::ToolCall | ApprovalRequest             → Tool Consumer
+MessageKind::LLMReply                              → Send Consumer
+```
+
+---
+
+## System Prompt
+
+```
+你是 iAs 智能助手，通过微信与用户交流。回复简洁自然。
+
+你可以通过 function calling 调用两个元工具：
+1. query_capabilities — 查询所有可用能力工具
+2. call_capability — 调用能力工具，参数 {"name":"工具名","prompt":"{\"参数\":\"值\"}"}
+
+流程：收到消息 → query_capabilities → call_capability → 回复
+```