tool interface

Claude Code 的工具系统基于统一的接口设计，确保类型安全和可扩展性。

Tool 接口

核心接口定义

// src/Tool.ts
interface Tool<TInput = any, TOutput = any> {
  // 基本信息
  name: string;
  description: string;
  
  // 输入验证
  inputSchema: ZodSchema<TInput>;
  
  // 执行方法
  execute(
    input: TInput,
    context: ToolContext
  ): Promise<ToolResult<TOutput>>;
  
  // 可选：转换为 Anthropic 工具格式
  toAnthropicTool?(): AnthropicTool;
}

ToolContext

interface ToolContext {
  // 工作目录
  cwd: string;
  
  // 状态访问
  state: DeepImmutable<AppState>;
  
  // 权限检查
  checkPermission(action: string): Promise<boolean>;
  
  // 其他工具访问
  tools: Map<string, Tool>;
  
  // 中断信号
  signal: AbortSignal;
}

ToolResult

type ToolResult<T = any> =
  | { success: true; output: T }
  | { success: false; error: string };

实现示例

简单工具

class EchoTool implements Tool<{ message: string }, string> {
  name = 'echo';
  description = 'Echo back the input message';
  
  inputSchema = z.object({
    message: z.string(),
  });
  
  async execute(input, context) {
    return {
      success: true,
      output: input.message,
    };
  }
}

复杂工具

class FileEditTool implements Tool {
  name = 'strReplace';
  description = 'Replace text in a file';
  
  inputSchema = z.object({
    path: z.string(),
    oldStr: z.string(),
    newStr: z.string(),
  });
  
  async execute(input, context) {
    try {
      // 1. 权限检查
      const allowed = await context.checkPermission('file:write');
      if (!allowed) {
        return { success: false, error: 'Permission denied' };
      }
      
      // 2. 读取文件
      const content = await fs.readFile(input.path, 'utf-8');
      
      // 3. 查找并替换
      const occurrences = countOccurrences(content, input.oldStr);
      if (occurrences === 0) {
        return { success: false, error: 'String not found' };
      }
      if (occurrences > 1) {
        return { success: false, error: 'Multiple matches found' };
      }
      
      const newContent = content.replace(input.oldStr, input.newStr);
      
      // 4. 写入文件
      await fs.writeFile(input.path, newContent);
      
      // 5. 通知 LSP
      await notifyLSP(input.path);
      
      return {
        success: true,
        output: `Successfully replaced text in ${input.path}`,
      };
    } catch (error) {
      return {
        success: false,
        error: error.message,
      };
    }
  }
}

类型安全

Zod Schema

// 定义输入 Schema
const FileEditInputSchema = z.object({
  path: z.string().min(1),
  oldStr: z.string(),
  newStr: z.string(),
}).refine(
  data => data.oldStr !== data.newStr,
  { message: 'oldStr and newStr must be different' }
);

// 类型推导
type FileEditInput = z.infer<typeof FileEditInputSchema>;

运行时验证

async execute(rawInput: unknown, context: ToolContext) {
  // 自动验证和类型转换
  const input = this.inputSchema.parse(rawInput);
  
  // input 现在是类型安全的
  const content = await fs.readFile(input.path, 'utf-8');
}

工具注册

静态注册

// src/tools.ts
export const BUILTIN_TOOLS: Tool[] = [
  new FileEditTool(),
  new BashTool(),
  new ReadCodeTool(),
  // ...
];

动态注册

// Plugin 动态添加工具
export function registerTool(tool: Tool): void {
  BUILTIN_TOOLS.push(tool);
}

MCP 工具

// MCP 服务器的工具自动注册
const mcpTools = await mcpClient.listTools();
mcpTools.forEach(tool => {
  registerTool(new MCPToolAdapter(tool));
});

工具组合

Composite Tool

class AnalyzeAndFixTool implements Tool {
  constructor(
    private readCode: ReadCodeTool,
    private getDiagnostics: GetDiagnosticsTool,
    private fileEdit: FileEditTool
  ) {}
  
  async execute(input, context) {
    // 1. 读取代码
    const code = await this.readCode.execute(
      { path: input.path },
      context
    );
    
    // 2. 获取诊断
    const diagnostics = await this.getDiagnostics.execute(
      { paths: [input.path] },
      context
    );
    
    // 3. 修复问题
    for (const issue of diagnostics.output) {
      await this.fileEdit.execute(
        { path: input.path, /* fix */ },
        context
      );
    }
    
    return { success: true, output: 'Fixed all issues' };
  }
}

下一步

• 深入 FileEditTool 的实现

• 了解 BashTool 的权限检查

• 探索 AgentTool 的协作机制