# 工具规范模块 (tools)

本模块定义了 AI 代理可以使用的所有内置工具的规范 (Schema)、权限要求以及分发逻辑。

## 概览

`tools` 模块充当了 AI 认知能力与物理操作之间的桥梁，其主要职责包括：
- **工具定义**：使用 JSON Schema 定义每个工具的输入参数结构，以便 AI 正确调用。
- **权限映射**：为每个工具分配安全等级（如只读、工作区写入、完全访问）。
- **工具注册表 (GlobalToolRegistry)**：统一管理内置工具和由插件提供的动态工具。
- **分发执行**：将 AI 生成的 JSON 调用分发到 `runtime` 模块中的具体实现。

## 关键特性

- **内置工具集 (MVP Tools)**：
  - **系统交互**：`bash`, `PowerShell`, `REPL`。
  - **文件操作**：`read_file`, `write_file`, `edit_file`。
  - **搜索与发现**：`glob_search`, `grep_search`, `ToolSearch`。
  - **网络与辅助**：`WebSearch`, `WebFetch`, `Sleep`。
  - **高级调度**：`Agent`（启动子代理）, `Skill`（加载专用技能）, `TodoWrite`（任务管理）。
- **名称归一化**：支持工具别名（例如将 `grep` 映射为 `grep_search`），提高 AI 调用的稳健性。
- **插件集成**：允许 `plugins` 模块注册自定义工具，并确保它们与内置工具不发生命名冲突。

## 实现逻辑

### 核心结构

- **`ToolSpec`**: 核心配置结构，存储工具的元数据（名称、描述、Schema、权限）。
- **`GlobalToolRegistry`**: 负责维护工具列表，并提供 `definitions` 方法生成供 LLM 使用的工具 API 声明。
- **`execute_tool`**: 顶级分发函数，负责将反序列化后的输入传递给底层的执行函数。

### 工作流程

1. 系统初始化时，根据用户配置和加载的插件，构建 `GlobalToolRegistry`。
2. 将工具定义转换为 AI 模型可理解的格式（由 `api` 模块处理）。
3. 当接收到 AI 的工具调用请求时，`runtime::ConversationRuntime` 调用 `ToolExecutor`。
4. `ToolExecutor` 委托给本模块的 `execute_tool` 函数。
5. 本模块验证输入格式，并调用 `runtime` 提供的底层文件或进程操作 API。

## 使用示例 (工具定义)

```rust
use tools::{ToolSpec, mvp_tool_specs};
use serde_json::json;

// 获取所有 MVP 工具的规范
let specs = mvp_tool_specs();
for spec in specs {
    println!("工具: {}, 权限级别: {:?}", spec.name, spec.required_permission);
}
```