16gagent/rules/tool-definition.md

工具定义规范

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

模式

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

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

通用工具定义格式

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

规则

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

当前已定义工具

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