5.12a 插件基础

💡 一句话总结：了解 OpenCode 插件系统，创建你的第一个插件。

---

学完你能做什么

• 理解插件架构
• 能创建基础插件
• 能实现插件功能
• 能测试和调试插件

---

🎒 开始前的准备

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

• [ ] 了解 JavaScript/TypeScript
• [ ] 完成必修课程

---

核心思路

插件架构

OpenCode 核心
    ↓
插件接口 (Plugin API)
    ↓
插件 (Plugin)

插件类型

类型	说明	示例
工具插件	添加新工具	自定义命令
UI 插件	扩展界面	新的面板
集成插件	连接外部服务	GitHub 集成
主题插件	提供主题	暗色主题

---

创建插件

项目结构

my-plugin/
├── src/
│   └── index.ts
├── package.json
├── tsconfig.json
└── opencode.config.json

package.json

{
  "name": "my-opencode-plugin",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "opencode": {
    "name": "我的插件",
    "version": "1.0.0",
    "author": "你的名字",
    "description": "一个实用的插件"
  }
}

插件入口

import { Plugin, OpenCodeAPI } from "@opencode/plugin-api";

export default class MyPlugin implements Plugin {
  name = "my-plugin";
  version = "1.0.0";

  async initialize(api: OpenCodeAPI): Promise<void> {
    console.log("插件已启动");
    
    // 注册工具
    api.tools.register({
      name: "my-tool",
      description: "我的自定义工具",
      handler: this.myToolHandler.bind(this),
    });
    
    // 注册快捷键
    api.keybindings.register({
      command: "myPlugin.customCommand",
      key: "ctrl+shift+m",
      handler: this.handleCommand.bind(this),
    });
  }

  async myToolHandler(input: string): Promise<string> {
    // 处理工具调用
    return `处理结果: ${input}`;
  }

  async handleCommand(): Promise<void> {
    // 处理快捷键
    console.log("快捷键触发");
  }

  async dispose(): Promise<void> {
    // 清理资源
    console.log("插件已卸载");
  }
}

---

插件 API

工具 API

api.tools.register({
  name: "custom-tool",
  description: "自定义工具",
  parameters: {
    input: {
      type: "string",
      required: true,
    },
  },
  handler: async (args) => {
    return "结果";
  },
});

菜单 API

api.menus.register({
  id: "my-menu",
  title: "我的菜单",
  items: [
    {
      command: "myPlugin.command1",
      title: "命令1",
    },
    {
      command: "myPlugin.command2",
      title: "命令2",
    },
  ],
});

事件 API

// 监听事件
api.events.on("chat.message", (message) => {
  console.log("收到消息:", message);
});

// 发送事件
api.events.emit("myPlugin.customEvent", { data: "test" });

---

跟我做

实战：创建欢迎插件

import { Plugin, OpenCodeAPI } from "@opencode/plugin-api";

export default class WelcomePlugin implements Plugin {
  name = "welcome-plugin";
  version = "1.0.0";

  async initialize(api: OpenCodeAPI): Promise<void> {
    // 添加欢迎命令
    api.commands.register("welcome.show", async () => {
      api.ui.showNotification({
        type: "info",
        message: "👋 欢迎使用 OpenCode!",
        duration: 5000,
      });
    });
    
    // 添加快捷键
    api.keybindings.register({
      command: "welcome.show",
      key: "ctrl+shift+w",
    });
    
    console.log("欢迎插件已加载");
  }

  async dispose(): Promise<void> {
    console.log("欢迎插件已卸载");
  }
}

---

检查点 ✅

全部通过才能继续

• [ ] 理解插件架构
• [ ] 能创建插件
• [ ] 能使用插件 API
• [ ] 能测试插件

---

本课小结

你学会了：

1. 插件架构
2. 创建插件
3. 插件 API
4. 实战案例

---

下一课预告

下一课我们将学习插件进阶。

---

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