OpenCode 插件架构与生命周期

OpenCode 插件架构与生命周期

学习目标

• 理解 OpenCode Plugin SDK 的插件入口规范
• 掌握配置加载的 6 阶段管道
• 识别 4 大管理器的职责和创建时机

前置知识

本章涉及插件系统的通用原理，建议先阅读：

• 插件系统

下文假设你已理解插件系统概念，直接聚焦 Oh-My-OpenAgent 的具体实现。

项目实践

插件入口

Oh-My-OpenAgent 作为 OpenCode 插件的入口点（src/index.ts）：

• 导出符合 @opencode-ai/plugin SDK 规范的插件定义
• 定义插件名称 oh-my-openagent（兼容旧名 oh-my-opencode）
• 注册生命周期回调（startup、shutdown）

配置加载的 6 阶段管道

插件启动时按顺序执行 6 阶段配置管道：

1. provider     → 加载和验证模型提供商配置
2. plugin-components → 加载插件组件（agents、tools、MCPs、commands）
3. agents       → 构建 Agent 定义和系统提示
4. tools        → 注册工具到工具集
5. MCPs         → 连接 MCP 服务器
6. commands     → 注册 slash 命令

每个阶段的输出作为下一阶段的输入，确保依赖关系正确。

配置文件层级查找

项目级 .opencode/oh-my-openagent.json[c]  (最近)
         ↑
用户级 ~/.config/opencode/oh-my-openagent.json[c]
         ↑
环境变量覆盖

• 层级查找：从项目目录向上遍历到 $HOME，加载所有匹配的配置文件
• 最近者胜出：同名配置项由最近的配置文件决定
• 深合并：不同层级的配置深度合并（deepMerge）
• JSONC 支持：配置文件支持注释和尾随逗号

4 大管理器

插件启动时创建 4 个管理器：

管理器	职责
TmuxSessionManager	管理 tmux 会话布局、Agent pane 分配、清理
BackgroundManager	管理后台 Agent 的生命周期、通知、结果消费
SkillMcpManager	管理 Skill-Embedded MCP 的启动、注入、关闭
ConfigHandler	处理配置变更、热重载、doctor 诊断

为什么选插件而非独立应用

• 复用 OpenCode 基础设施：session 管理、TUI、模型连接、工具调用框架
• 无缝升级：OpenCode 更新时自动获得新能力
• 用户心智负担低：只需安装一个插件，无需学习新工具

问题与规避

配置文件加载顺序混淆

问题：多层级配置文件合并时，用户不清楚哪个配置生效。

规避：doctor 命令内置诊断，显示每个配置项的来源。日志中标注配置加载路径。

插件与 OpenCode 版本不兼容

问题：Oh-My-OpenAgent 依赖特定版本的 OpenCode SDK，版本不匹配时功能异常。

规避：

• peerDependencies 声明 SDK 版本范围
• doctor 命令检查 OpenCode 版本兼容性
• 在启动时检测并报告版本不匹配

设计取舍

插件 vs 独立应用

方案	优势	代价
插件	复用宿主基础设施、无缝升级	受限于宿主 SDK 的能力边界
独立应用	完全控制、不受宿主限制	需要自实现 session/TUI/模型连接

Oh-My-OpenAgent 的选择：插件模式，因为 OpenCode 已经提供了完善的 Agent 运行时，重复造轮子的成本远高于收益。

参考来源

• OpenCode Plugin SDK
• Oh-My-OpenAgent 配置文档