OpenCode 中文社区

Appearance

5.13 自定义工具 ​

💡 一句话总结：创建自定义工具，扩展 OpenCode 的能力。

学完你能做什么 ​

  • 能创建自定义工具
  • 能实现工具参数
  • 能处理工具错误
  • 能注册和管理工具

🎒 开始前的准备 ​

确保你已经完成以下事项：

  • [ ] 完成必修课程
  • [ ] 了解 AGENTS.md 基本结构

核心思路 ​

工具类型 ​

类型说明示例
命令行执行 Shell 命令bash
文件操作读写文件read, write
代码分析分析代码结构grep, lsp-*
API 调用外部服务请求curl, http

创建工具 ​

配置文件 ​

yaml
tools:
  my-tool:
    name: "我的工具"
    description: "一个自定义工具"
    category: "development"
    
    parameters:
      - name: "input"
        type: "string"
        required: true
        description: "输入参数"
      
      - name: "option"
        type: "string"
        required: false
        default: "default"
        description: "选项"
    
    handler: |
      // 工具处理逻辑
      const result = process(input, option);
      return result;
    
    examples:
      - input: "test"
        output: "处理结果: test"

JavaScript 实现 ​

typescript
// tools/my-tool.ts
export default {
  name: "my-tool",
  description: "我的自定义工具",
  
  parameters: {
    input: {
      type: "string",
      required: true,
    },
    option: {
      type: "string",
      required: false,
      default: "default",
    },
  },
  
  async handler(args: { input: string; option?: string }): Promise<string> {
    const { input, option = "default" } = args;
    
    // 处理逻辑
    const result = `处理结果: ${input} (选项: ${option})`;
    
    return result;
  },
};

高级工具 ​

带错误处理 ​

yaml
tools:
  safe-tool:
    name: "安全工具"
    description: "带错误处理的工具"
    
    parameters:
      - name: "input"
        type: "string"
        required: true
    
    handler: |
      try {
        const result = riskyOperation(input);
        return { success: true, result };
      } catch (error) {
        return { success: false, error: error.message };
      }
    
    error_handling:
      retry: true
      max_retries: 3
      timeout: 30000

带进度通知 ​

typescript
tools:
  progress-tool:
    name: "进度工具"
    description: "支持进度通知的工具"
    
    handler: |
      const steps = 10;
      for (let i = 1; i <= steps; i++) {
        progress.notify(i / steps, `步骤 ${i}/${steps}`);
        await doStep(i);
      }
      return "完成";

跟我做 ​

实战：创建代码统计工具 ​

yaml
tools:
  code-stats:
    name: "代码统计"
    description: "统计代码文件的行数、字符数等"
    
    parameters:
      - name: "path"
        type: "string"
        required: true
        description: "文件或目录路径"
      
      - name: "extensions"
        type: "array"
        required: false
        default: ["ts", "js", "tsx", "jsx"]
        description: "要统计的文件类型"
    
    handler: |
      const files = findFiles(path, extensions);
      const stats = files.map(file => {
        const content = readFile(file);
        return {
          file,
          lines: content.split('\n').length,
          chars: content.length,
          words: content.split(/\s+/).length
        };
      });
      
      const total = {
        files: stats.length,
        lines: stats.reduce((sum, s) => sum + s.lines, 0),
        chars: stats.reduce((sum, s) => sum + s.chars, 0),
        words: stats.reduce((sum, s) => sum + s.words, 0)
      };
      
      return { files: stats, total };

检查点 ✅ ​

全部通过才能继续

  • [ ] 能创建基础工具
  • [ ] 能配置参数
  • [ ] 能处理错误
  • [ ] 能创建复杂工具

本课小结 ​

你学会了：

  1. 工具类型
  2. 创建工具
  3. 高级功能
  4. 实战案例

下一课预告 ​

下一课我们将学习 GitHub 集成。

📚 更多完整模板：Prompt 模板库

微信群