# 工具定义规范

> 从 Claude Code `buildTool<T>()` 模式迁移而来。
> 适用于需要"统一接口"的重复任务。

## 模式

所有工具调用遵循以下骨架：

```
目的 + 输入 + 执行 + 输出 + 错误
```

## 通用工具定义格式

```typescript
// 伪代码思路：工具即定义
Tool = {
  name: string,        // 唯一名称
  description: string, // 一句话说明"为什么"有这个工具
  input: Schema,       // 输入参数定义
  validate(input):     // 前置校验（快速失败）
  run(input, ctx):     // 核心执行
  error(e, ctx):       // 错误处理（分级）
}
```

## 规则

1. **快速失败优先**：参数校验在 run 之前，不执行无效操作
2. **输出确定性**：相同输入 + 相同状态 = 相同输出
3. **错误分级**：可重试 / 不可重试 / 用户取消
4. **执行时间预估**：10s 以内的直接干，以上的先汇报
5. **不重复造轮子**：先看 tools/ 目录是否有已有工具

## 当前已定义工具

见 `tools/` 目录中的工具模板文件。