# 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 |