# 工具系统 (Tool System)
Agent 工具系统是 ReAct 循环中 **Action → Observation** 环节的执行引擎。每个工具遵循 `AgentTool` trait 向 LLM 暴露 JSON Schema 参数定义，并在 `execute` 中调用服务层完成实际业务操作。
---
## 三层架构
```mermaid
graph TB
subgraph Layer1["调度层 — AgentRuntime"]
direction LR
RT["src/agent/runtime/mod.rs
ReAct 循环
调度 LLM tool_calls → 工具执行 → 结果注入上下文"]
end
subgraph Layer2["执行协调层 — Executor"]
direction LR
EX["src/agent/runtime/executor.rs
验证 → PreToolUse hooks → 并行调度 → PostToolUse"]
SX["src/agent/runtime/streaming_executor.rs (流式变体)
流式 tool_use 到达时立即调度 + Sibling Abort
非并发工具独占执行 (executing_non_concurrent 标志)"]
end
subgraph Layer3["业务逻辑层 — AgentTool Trait + 工具实现"]
direction LR
Tools["src/agent/tools/
每个工具独立子模块，实现 AgentTool trait"]
end
Layer1 --> Layer2 --> Layer3
```
---
## AgentTool Trait
```mermaid
classDiagram
class AgentTool {
<>
+name() &str
+description() &str
+parameters() Value
+execute(args, ctx) ToolOutput
+interrupt_behavior() InterruptBehavior
+is_concurrency_safe(args) bool
+check_permissions(args) PermissionRule[]
+causes_sibling_abort() bool
+execute_with_progress(args, ctx, tx) ToolOutput
}
class InterruptBehavior {
<>
Cancel — 可安全中断（只读工具默认）
Block — 忽略中断信号直到完成（写入工具）
}
class PermissionRule {
<>
Deny — 不可覆盖的拒绝
Allow — 显式允许
Ask — 需用户确认
}
class ToolContext {
+Arc~AppState~ app_state
+String session_id
+bool silent
+Arc~Mutex~FileStateCache~~ read_file_state
+Option~UnboundedSender~ sse_tx
+bool enable_thinking
}
class ToolOutput {
+String content — 给 LLM 的截断文本
+bool is_error — 是否为错误
+Value metadata — 给前端的结构化数据
}
class ToolRegistry {
-HashMap~String, Box~AgentTool~~ tools
-Vec~String~ ordered_names
+empty() Self
+new(skill_registry) Self
+new_with_queue(queue, skill_registry) Self
+new_with_team(queue, team_manager, skill_registry) Self
+add_tool(tool)
+replace_tool(tool)
+get(name) Option~&dyn AgentTool~
+definitions() Vec~ToolDefinition~
}
AgentTool --> InterruptBehavior
AgentTool --> PermissionRule
AgentTool --> ToolContext
AgentTool --> ToolOutput
```
### 方法详解
| 方法 | 返回类型 | 默认值 | 说明 |
|:---|:---|:---|:---|
| `name()` | `&str` | **(必须)** | 工具名称，全小写下划线风格，与 LLM function calling `name` 一致 |
| `description()` | `&str` | **(必须)** | 告知 LLM 何时应调用该工具；作为 base description 注入 system prompt |
| `parameters()` | `Value` | **(必须)** | JSON Schema 格式的参数定义，直接序列化为 LLM tool definition |
| `execute(args, ctx)` | `ToolOutput` | **(必须)** | 核心执行逻辑，接收 LLM 传入的参数 + `ToolContext` 全局状态 |
| `interrupt_behavior()` | `InterruptBehavior` | `Cancel` | 控制用户取消时的行为：`Cancel`—响应取消信号立即返回错误；`Block`—忽略取消直到执行完成（保护有副作用的写入操作） |
| `is_concurrency_safe(args)` | `bool` | `false` | 该工具是否可以与其他工具并发执行。**只读工具**（`read_file`、`search_papers`、`rag_search` 等）覆写为 `true`；写入工具保持默认 `false` |
| `check_permissions()` | `Vec` | `[]` | 工具自定义权限规则：`Deny{tool, reason}` / `Allow{tool}` / `Ask{tool, message}`。与 `PermissionChecker` 管道协同工作 |
| `causes_sibling_abort()` | `bool` | `false` | 该工具错误时是否中止兄弟并行执行。用于 `download_paper`、`parse_paper` 等关键工具 |
| `execute_with_progress(args, ctx, tx)` | `ToolOutput` | 委托 `execute()` | 长时间操作可覆写，通过 `progress_tx` 发送进度更新到前端 |
---
## 工具清单（23 个）
### 文件系统工具（6 个）— `filesystem/`
| 工具 | 并发安全 | 中断行为 | 功能 |
|:---|:---|:---|:---|
| `read_file` | ✅ | Cancel | 读取文件，带 `FileStateCache` mtime 去重；相同 offset/limit 且文件未修改时返回 `FILE_UNCHANGED_STUB` 占位符 |
| `grep_files` | ✅ | Cancel | 正则搜索文件内容 |
| `glob_files` | ✅ | Cancel | 通配符匹配文件路径 |
| `run_bash` | ❌ | Cancel | Shell 命令执行，有独立超时和输出截断 |
| `file_write` | ❌ | Block | 创建/覆盖文件 |
| `file_edit` | ❌ | Block | 精确字符串替换（基于 `old_string` 匹配） |
**安全约束** (`filesystem/security.rs`)：
- **路径沙箱**：只允许 `library_dir`、`skills_dir`、项目根目录三个根路径
- **路径穿越防护**：字符串级拒绝含 `..` 或 `~` 的路径
- `canonicalize()` 解析符号链接后再做前缀匹配，防止 symlink 绕过
### 天文科研工具（8 个）— `astro/`
| 工具 | 并发安全 | 功能 |
|:---|:---|:---|
| `search_papers` | ✅ | ADS + arXiv 跨库联合检索，自动合并去重，关联本地馆藏状态与引用关系 |
| `get_paper_metadata` | ✅ | 获取单篇文献完整元数据（作者、期刊、关键词、摘要、引用数、下载/解析状态） |
| `download_paper` | ❌ | PDF 下载，支持 Obscura 反爬绕过和多通道 fallback |
| `parse_paper` | ❌ | PDF/HTML → Markdown 解析（MinerU/ar5iv/IOP/A&A 等多引擎） |
| `get_paper_content` | ✅ | 读取已解析的论文全文 Markdown |
| `rag_search` | ✅ | 向量相似度检索 + LLM 答案生成（基于 `sqlite-vec`） |
| `query_target` | ✅ | CDS Sesame 天体目标查询（IAU 名称解析 + 坐标/类型） |
| `save_note` | ❌ | 高亮批注持久化到数据库 |
### Agent 自管理工具（5 个）
| 工具 | 并发安全 | 中断行为 | 功能 |
|:---|:---|:---|:---|
| `todo_write` | ✅ | Cancel | 任务规划，支持 `pending/in_progress/completed` 状态 + `blockedBy` DAG 依赖；验证只能有一个 in_progress 任务 |
| `compress_context` | ✅ | Cancel | 设置手动压缩标志位，下一轮 LLM 调用前由 Runtime 执行压缩（纯幂等操作） |
| `load_skill` | ✅ | Cancel | 按需加载 SKILL.md 技能文件。支持 **inline** 模式（直接返回内容）和 **fork** 模式（启动子代理按技能指引执行任务） |
| `save_memory` | ❌ | Block | 跨会话记忆持久化。写入时门控：质量检查（过短/模糊/瞬时/代码模式）+ Jaccard 70% 去重 |
| `ask_user` | N/A | Block | 暂停 ReAct 循环向用户提问。oneshot 通道机制：创建问题 → SSE 推送前端 → 阻塞等待 → 5 分钟超时。子代理中不可用（silent 模式） |
### 高级编排工具（4 个）
| 工具 | 并发安全 | 中断行为 | 功能 |
|:---|:---|:---|:---|
| `subagent` | ❌ | Block | 上下文隔离的子代理。子代理拥有完整工具访问权，但仅最终摘要返回父代理。支持自定义 `max_steps`（默认5，最大10） |
| `bg_task_run` | ❌ | Block | 后台异步执行慢速操作（仅支持 `download_paper`、`parse_paper`）。结果通过 `BgNotificationQueue` 在下一轮前注入 |
| `bg_task_check` | ✅ | Cancel | 查询后台任务状态（可指定 task_id 或列出全部） |
| *团队 4 工具* | ❌ | Block | `spawn_teammate` / `send_teammate_message` / `team_broadcast` / `check_team_inbox` — 基于文件收件箱的多 Agent 协作 |
---
## 执行流水线
从 LLM 返回 `tool_calls` 到结果注入 `messages[]` 的完整数据流：
```
LLM stream → tool_calls[]
│
▼
┌─ validate_and_prepare() ─────────────────────────────────────┐
│ 1. 死循环检测 (DuplicateDetector): │
│ 连续相同 (tool_name, args) ≥ threshold → 注入错误消息 │
│ 2. JSON 参数解析: 失败则注入 tool_result 错误 │
│ 3. 修复空 tool_call_id (UUID 前缀) │
└──────────────────────────────────────────────────────────────┘
│
▼ PreparedCall[]
│
├─ 发送 ToolCall SSE 事件 → 前端实时渲染
│
├─ PreToolUse hooks (顺序执行)
│ ├─ 可拦截 (Block) / 修改参数 (MutateInput) / 注入上下文 (AppendContext)
│ └─ mutated_args + additional_contexts 收集
│
▼
┌─ execute_parallel() — ToolPartitioner 批次调度 ──────────────┐
│ │
│ Phase 3a: 构建非拒绝工具的 (原索引, PreparedCall) 映射 │
│ Phase 3b: ToolPartitioner::partition() 分区 │
│ · 连续 concurrency_safe 工具 → 并行批次 │
│ · 非 concurrency_safe 工具 → 独占串行批次 │
│ · 示例: [read, grep, bash, read, write] │
│ → [read∥grep], [bash], [read], [write] │
│ │
│ Phase 3c: 逐批次执行 │
│ · 并行批次 → FuturesUnordered 并发 (tokio::spawn each) │
│ · 串行批次 → 逐个执行 (前一个完成后才启动下一个) │
│ │
│ 中断处理（每工具内）: │
│ tokio::select! { │
│ timeout(tool_timeout_secs) → 执行工具 │
│ cancel_fut (每 250ms 轮询) → 返回错误 │
│ } │
│ InterruptBehavior::Block → 忽略 cancel_fut，等完成 │
│ InterruptBehavior::Cancel → 响应取消，注入错误 │
│ │
│ 辅助函数: │
│ execute_single_tool() — 单工具超时+取消+执行 │
│ process_single_result() — 结果处理+SSE推送+TTL持久化+Hook │
└──────────────────────────────────────────────────────────────┘
│
▼ (每个工具完成后逐个处理)
│
├─ 发送 ToolResult SSE 事件 (tool_call_id 精确匹配)
│
├─ maybe_persist_tool_result()
│ ├─ content ≤ max_chars → 直接传递
│ └─ content > max_chars → 写入 disk + 返回 stub
│ 幂等写入 (create_new)，同 tool_call_id 不重复写
│
├─ PostToolUse hooks → 审计日志 / 指标采集 / 输出修改
│
├─ 持久化到 agent_messages 表 (fire-and-forget)
│
└─ 推入 messages[] → 下一轮 LLM 调用
```
### 并发模型细节
```rust
// executor.rs Phase 3c: 逐批次执行
for batch in &batches {
if batch.is_parallel {
// 并行批次: FuturesUnordered 内并发执行
let mut exec_futs: FuturesUnordered<_> = batch.calls.iter()
.map(|prep| execute_single_tool(...))
.collect();
while let Some(result) = exec_futs.next().await {
process_single_result(...).await;
}
} else {
// 串行批次: 逐个执行（非并发安全工具独占）
for prep in &batch.calls {
let result = execute_single_tool(...).await;
process_single_result(...).await;
}
}
}
```
关键特性：
- `ToolPartitioner::partition()` 将工具调用分为并行批次和串行批次
- 并行批次内使用 `FuturesUnordered` 最大化并发
- 串行批次内逐个执行（如 `run_bash`、`file_write` 独占）
- 连续的并发安全工具自动合并到一个并行批次
- `is_concurrency_safe(args)` 是**输入感知**的：同一工具可能因参数不同而安全属性不同
- `InterruptBehavior::Block` 保护写入操作不被用户取消打断
---
## ToolRegistry 注册流程
```mermaid
sequenceDiagram
participant RT as AgentRuntime::new()
participant TR as ToolRegistry
participant Tools as 工具实例
RT->>TR: new_with_queue(queue, skill_registry)
TR->>TR: add_base_tools()
Note over TR: 注册 19 个基础工具
TR->>Tools: read_file, grep_files, glob_files, run_bash
TR->>Tools: file_write, file_edit
TR->>Tools: search_papers, get_paper_metadata
TR->>Tools: download_paper, parse_paper, get_paper_content
TR->>Tools: rag_search, query_target, save_note
TR->>Tools: todo_write, compress_context, ask_user
TR->>Tools: load_skill(skill_registry)
TR->>Tools: subagent (默认实例)
opt queue.is_some()
TR->>TR: add_background_tools(queue)
TR->>Tools: bg_task_run + bg_task_check
end
RT->>TR: add_tool(SaveMemoryTool)
Note over TR: MemoryManager 需要共享状态，动态注入
RT->>TR: replace_tool(SubAgentTool::new_with_hooks(...))
Note over TR: 替换为带 PermissionChecker + HookRegistry 的增强版
TR->>TR: definitions()
Note over TR: HashMap 值收集 → 按 name 字母序排序
Note over TR: 排序保证跨调用稳定性 → 提升 prompt cache 命中率
```
### 注册表工厂方法
| 方法 | 工具数 | 用途 |
|:---|:---|:---|
| `ToolRegistry::empty()` | 0 | 受限场景（如记忆提取子代理只需只读 + save_memory） |
| `ToolRegistry::new(skill_registry)` | 19 | 标准科研 Agent |
| `ToolRegistry::new_with_queue(queue, skill_registry)` | 21 | 带后台任务支持 |
| `ToolRegistry::new_with_team(queue, team_manager, skill_registry)` | 25 | 带团队协作 |
---
## 安全模型
### 多层权限管道
```
工具调用
│
├─ 1. AgentTool::check_permissions() ← 工具自身声明的权限规则
│
├─ 2. PermissionChecker::check() ← 集中式规则链
│ ├─ Deny rule (最高优先级，不可覆盖)
│ ├─ Allow rule (显式允许)
│ ├─ Ask rule (需用户确认)
│ └─ Default: Allowed
│ └─ 支持通配符 "*" 匹配所有工具
│
└─ 3. PreToolUse hooks ← Hook 可最终拦截 (Block)
```
### 文件系统安全
```rust
// 路径穿越检测
fn has_path_traversal(path_str: &str) -> bool {
path_str.contains("..") || path_str.contains('~')
}
// 路径沙箱
fn is_path_allowed(path: &Path, ctx: &ToolContext) -> bool {
let canonical = path.canonicalize()?; // 解析所有符号链接
// 检查是否在 library_dir / skills_dir / current_dir 下
allowed_roots.iter().any(|root| canonical.starts_with(root))
}
```
### SQL 注入防护
所有数据库操作使用参数化查询，无字符串拼接：
```rust
sqlx::query("INSERT INTO agent_messages (...) VALUES (?, ?, ...)")
.bind(value1)
.bind(value2)
// ...
```
---
## 关键集成点
### Hook 系统
| Hook | 触发时机 | 在工具系统中的用途 |
|:---|:---|:---|
| `PreToolUse` | 工具执行前 | 拦截/修改参数（`MutateInput`）、注入附加上下文（`AppendContext`）、权限确认（`PermissionRequired`） |
| `PostToolUse` | 工具执行后 | 审计日志写入 `agent_audit_log`、指标采集（`MetricsData`）、输出修改（`MutateOutput`） |
### SSE 事件流
```
ToolCall { id, name, arguments, step } ← 工具开始执行
↓
(如有进度) ToolProgress { id, progress } ← execute_with_progress 发送
↓
ToolResult { tool_call_id, name, output, ← 执行完成
is_error, metadata, step }
```
前端通过 `tool_call_id` 精确匹配 ToolCall/ToolResult，实现 Timeline 渲染。
### 上下文压缩
三层压缩与工具系统的交互：
| 层级 | 触发方式 | 实现 |
|:---|:---|:---|
| micro_compact | 自动（token 超限前） | 占位符替换，不涉及工具 |
| auto_compact | 自动（`estimated_tokens > soft_limit`） | Runtime 检测 → `snapshot_compress_restore()` → 文件缓存快照 → LLM 摘要压缩 → 恢复最近文件 |
| manual_compact | `compress_context` 工具 | 设置 `pending_manual_compress` 标志位，下一轮 LLM 调用前执行。不受熔断器限制 |
压缩熔断器 (`CompactionCircuitBreaker`)：连续失败多次后打开，阻止进一步压缩以防止无限循环。
### 工具输出持久化
```
execute() → ToolOutput { content }
│
├─ content.len() ≤ max_output_chars (默认 4000)
│ └─ 直接返回给 LLM
│
└─ content.len() > max_output_chars
└─ maybe_persist_tool_result()
├─ 写入 {library_dir}/tool-results/{tool_call_id}.txt
├─ 使用 create_new 保证幂等
└─ 返回 stub（含 path + preview）
LLM 可通过 read_file 读取完整内容
```
---
## 目录结构
```
src/agent/tools/
├── mod.rs # AgentTool trait + ToolRegistry + ToolContext + ToolOutput + 辅助函数
├── filesystem/ # 文件 I/O (6 工具)
│ ├── mod.rs # re-export
│ ├── read.rs # read_file — 带 FileStateCache mtime 去重
│ ├── grep.rs # grep_files — 正则搜索
│ ├── glob.rs # glob_files — 通配符匹配
│ ├── bash.rs # run_bash — Shell 命令执行（超时+截断）
│ ├── write.rs # file_write — 文件创建/覆盖
│ ├── edit.rs # file_edit — 精确字符串替换
│ └── security.rs # 共享安全验证（路径沙箱 + 穿越检测）
├── astro/ # 天文学工具 (8 工具)
│ ├── mod.rs # re-export
│ ├── search.rs # search_papers + get_paper_metadata
│ ├── paper.rs # download_paper + parse_paper + get_paper_content
│ ├── rag.rs # rag_search — 向量检索 + LLM 问答
│ ├── target.rs # query_target — CDS Sesame 查询
│ └── note.rs # save_note — 高亮批注
├── todo.rs # todo_write — 任务规划（DAG 依赖，持久化到 agent_tasks）
├── compress.rs # compress_context — 手动上下文压缩标志位
├── skill.rs # load_skill — inline/fork 双模式技能加载
├── subagent.rs # subagent — 上下文隔离的子代理委派
├── ask_user.rs # ask_user — oneshot 通道用户交互
├── background.rs # bg_task_run + bg_task_check — 后台异步任务
├── team.rs # spawn/send/broadcast/check_inbox — 多 Agent 协作
├── memory.rs # save_memory — 带质量门控的跨会话记忆
└── persist.rs # maybe_persist_tool_result — 大输出磁盘持久化
```