3步打造专属AI编程助手：OpenCode插件实战完整指南

3步打造专属AI编程助手OpenCode插件实战完整指南【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode想让AI改完代码后自动跑一遍测试套件OpenCode是开源的AI编程助手它的插件系统让你把自己的工具和逻辑挂进AI工作流的任意节点。本文按最短路径带你走一遍OpenCode插件开发从5分钟跑通第一个自定义工具到完整的自动测试场景。5分钟跑通第一个插件OpenCode会自动加载插件把.ts文件丢进项目的.opencode/plugins/目录即可全局生效则放~/.config/opencode/plugins/不用配置也不用构建。下面这个插件定义了一个名为hello的自定义工具存成文件就完事了// .opencode/plugins/hello.ts import { type Plugin, tool } from opencode-ai/plugin export const HelloPlugin: Plugin async () { return { tool: { hello: tool({ description: 返回问候语用于验证插件是否生效, args: { name: tool.schema.string().describe(名字), }, async execute(args) { return Hello ${args.name}! 插件已生效 }, }), }, } }重启 opencode在会话里说用 hello 工具问候我看到 Hello OpenCode! 插件已生效 就成了。如果插件发在 npm 上只需把包名写进opencode.json的plugin数组启动时会自动安装不用手动 install。它到底是怎么工作的插件就是一个函数接收上下文返回 Hooks 对象。export type Plugin (input: PluginInput) PromiseHooks启动时 OpenCode 按固定顺序加载插件全局配置、项目配置、全局插件目录、项目插件目录。所有钩子按加载顺序依次执行所以多个插件挂同一个事件时行为是确定、可预期的。上下文对象ctx带来一组现成能力client是 SDK 客户端可以查会话、写日志directory和worktree是项目路径$是 Bun 的 shell能直接跑命令。插件跑在 OpenCode 进程内部既能读状态也能改行为。钩子就是事件流上的拦截点chat.params在请求发往 LLM 前改参数tool.execute.before/after包住每次工具调用event接收session.idle、file.edited这类全局事件。tool()只是个包装函数——它拿 Zod schema 加一个 execute 函数把工具变成 AI 眼里和内置工具没有区别的自定义工具。一个完整场景走一遍hello 工具验证了链路现在解决真问题AI 改完代码立刻知道测试挂没挂。第一步注册新建.opencode/plugins/auto-test.ts。第二步挂钩子用tool.execute.after拦截文件编辑类工具顺手把测试跑掉。这个插件的核心就是一个钩子——文件编辑工具执行后跑一遍bun test把结果写进展示元数据// .opencode/plugins/auto-test.ts import { type Plugin } from opencode-ai/plugin export const AutoTestPlugin: Plugin async (ctx) { return { tool.execute.after: async (input, output) { if (input.tool ! edit input.tool ! write) return // 跳过只读工具 const result await ctx.$bun test --silent.nothrow() // nothrow 防止失败抛异常 output.title Tests ${result.exitCode 0 ? passed : failed} // TUI 直接可见 output.metadata.testPassed result.exitCode 0 }, } }第三步验证重启 opencode让 AI 改某个函数。 TUI 里 edit 工具调用下方的标题会变成 Tests passed 或 Tests failed不用切回终端。想拦截更危险的操作也一样简单在tool.execute.before里对.env路径直接throw new Error(...)before 钩子里抛异常就是合法的阻断手段。踩过的坑 提效技巧参数校验从严args里用 Zod 加.positive()、.enum()这类约束AI 传入脏数据时在入口就被拒掉而不是在运行时炸出莫名其妙的错。错误当文本处理execute里套 try/catch 并返回人能看懂的说明直接抛异常会让 AI 无法判断失败原因、只能盲目重试。⚠️别阻塞关键路径tool.execute.before在每次工具调用必经的路径上别在里面同步跑慢命令重逻辑放 after 钩子或event。资源要清理起了定时器或文件监听的插件实现dispose钩子释放长会话跑一天下来会漏。名字别撞车插件工具与内置工具同名时插件优先起名edit、read等于静默覆盖内置行为建议加业务前缀。继续往下挖官方插件文档 packages/web/src/content/docs/plugins.mdx全部钩子列表、事件类型表和 npm 插件安装方式写新钩子前先翻它。最小参考实现 packages/plugin/src/example.ts仓库里自带的十几行示例插件动手前值得过一遍。工具定义源码 packages/plugin/src/tool.ts看ToolContext里sessionID、abort、metadata()这些字段写复杂工具时会用到。把第二节的 hello.ts 拷进你项目的.opencode/plugins/目录重启一次你就有了第一个能跑的 OpenCode 插件。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考