ClaudeCode 到 OpenCode 适配通用指南
本文提炼 ClaudeCode 生态能力迁移到 OpenCode 时的通用设计关注点。适配的重点不是逐文件复制
.claude 目录，也不是把一个宿主的术语机械映射到另一个宿主，而是先识别产品能力、宿主加载机制、
运行边界、交付形态和验证方式，再用 OpenCode 原生模型重新落地。
一、先判断迁移对象
适配前应先回答“要迁移的到底是什么”。ClaudeCode 项目里常见的目录、命令、skill、hook、agent、脚本和文档并不一定都是产品能力，有些只是 ClaudeCode 宿主下的加载形式。 通用做法是先抽象能力，再选择 OpenCode 中对应的承载方式。
产品能力
用户真正需要的命令、流程、自动化判断、代码生成、审计、测试、发布等能力。迁移时应保持这些能力，而不是保持旧目录结构。
宿主加载形式
ClaudeCode 的 command、skill、hook、settings 和 subagent 需要重新评估，分别落到 OpenCode 的 command、agent、plugin、config 或外部 runtime。
运行控制面
复杂流程不宜全部写进提示词或插件。稳定逻辑应进入脚本/runtime，宿主命令只做入口、参数转交和结果展示。
交付对象
要区分“适配包自身如何被 OpenCode 加载”和“适配包生成或修改的目标项目资产如何被 OpenCode 加载”。这两类契约不能混在同一个 schema 中。
二、ClaudeCode 到 OpenCode 的常见映射
| ClaudeCode 侧概念 | OpenCode 侧候选承载 | 适配判断 |
|---|---|---|
| Slash command / prompt command | .opencode/commands/*.md |
适合保留为用户可见入口，但命令体应尽量薄，只调用确定性 runtime 或明确的 agent 流程。 |
| Skill | OpenCode agent、command 文档、项目规则或 runtime 模块 | 不要默认迁移成同名 skill。先判断它是角色能力、操作步骤、知识库，还是可执行工具。 |
| Hook | .opencode/plugins/*.ts |
适合做事件监听、命令桥接、工具前后处理。不要把完整业务编排塞进 plugin hook。 |
| Subagent / 单个 reviewer role | .opencode/agents/*.md |
这里指 OpenCode 可加载、可被调用的单个执行角色。它是执行机制，不负责表达完整团队结构。 |
| Agent team / 多角色协作流程 | runtime team plan、orchestrator 配置或运行证据 | 这里指团队结构和阶段职责，例如谁负责设计、谁负责验证、如何 fan-out/fan-in。它不是 OpenCode 独立加载的 agent 文件。 |
| Settings / permissions | opencode.json + 项目安装 manifest |
权限要最小化；全局设置只放通用 bootstrap 或用户明确接受的配置，项目行为应本地可复现。 |
| 工具脚本和 validator | 项目内 runtime、包内 runtime 或外部 CLI | 稳定逻辑应自包含交付，避免运行时偷偷依赖开发仓库路径。 |
三、核心设计关注点
加载边界
明确哪些资产由 OpenCode 自动发现，哪些资产只是 runtime 内部实现。不要把内部实现字段写进用户项目的工作流 schema。
命名空间
为产品命令、生成命令、插件 ID、agent 名称预留不同命名空间。冲突不是小问题，会直接导致用户运行错入口。
安装半径
全局安装方便但污染范围大；项目本地安装隔离好但首次使用麻烦。常见折中是全局轻量 bootstrap + 项目本地物化。
依赖封装
如果 runtime 依赖 Python、Node、第三方包或外部 CLI，应提供版本、锁定依赖、环境诊断和失败降级路径。
写入安全
对目标项目的写入应先生成候选产物，再做 diff、冲突检测、确认、apply 和 rollback，而不是让 agent 直接改目标文件。
可观测验证
区分静态文件存在、runtime 可执行、OpenCode 宿主可见、真实模型执行成功。不同层级的测试不能互相替代。
四、主要难点与解决方案
| 难点 | 风险 | 解决方案 |
|---|---|---|
| 两个宿主的概念不是一一映射 | 把旧宿主的加载模型复制到新宿主，导致交付形态混乱 | 采用 capability-first 迁移：先列产品能力，再选择 OpenCode 原生 command、agent、plugin、config 或 runtime 承载。 |
| 产品包自身和目标项目都可能包含 OpenCode 资产 | 产品命令、生成命令、package plugin、target plugin 互相覆盖 | 定义清晰根路径和命名空间。例如产品包根、目标项目根、运行证据根分别管理，生成资产不得占用产品命名空间。 |
| 宿主会读取全局配置和第三方资产 | 用户以为运行的是当前项目能力，实际入口来自全局目录或其它工具包 | 提供 doctor/source inventory：列出 project、global、旧宿主目录、第三方包来源，并报告 shadowing 风险。 |
| 全局安装和项目安装的取舍困难 | 全局安装污染强，项目安装体验弱 | 将“部署器”全局化，将“完整能力”项目本地化。全局只提供 install/status/upgrade/uninstall 这类 bootstrap 入口。 |
| runtime 依赖在用户环境中不可控 | 命令在开发机可用，在用户项目或 CI 中失败 | 声明依赖、锁定版本、提供专用 venv 或 bundle 策略，并在 doctor 中显式诊断解释器、依赖和路径问题。 |
| 真实 OpenCode 执行依赖 provider/API 和宿主状态 | 测试假阳性或把环境问题误判为设计失败 | 测试结果分为 PASS、FAIL、ENVIRONMENT-SKIP；无 API 时不声称真实宿主执行成功。 |
五、推荐架构取舍
通用建议是：全局只放低风险引导器，项目本地承载完整能力，runtime 负责确定性逻辑，OpenCode 原生命令和插件负责宿主接入。 这样可以同时控制用户体验、隔离性、可复现性和可验证性。
| 方案 | 结论 | 原因 |
|---|---|---|
| 完整全局安装 | 谨慎采用 | 只适合极小、无项目状态、无写入目标文件的工具；复杂工作流容易造成命令污染和版本串扰。 |
| 纯项目本地安装 | 适合作为基础能力 | 隔离性和可复现性最好，但新项目首次使用不够友好。 |
| 全局轻量 bootstrap | 推荐 | 用户只需全局安装一次部署器；每个项目仍获得完整、可诊断、可回滚的本地安装。 |
| 外部 runtime 编排 | 推荐用于复杂流程 | 把确定性逻辑、状态机、validator、rollback、报告生成放到可测试 runtime 中，降低提示词漂移风险。 |
六、黑盒验收口径
- 安装后，用户能在 OpenCode 中看到预期命令、agent 或插件行为。
- 新项目使用路径清晰：全局 bootstrap、项目本地安装、状态检查、升级、卸载都可独立执行。
- 同名命令、agent、skill、plugin 冲突能被诊断，并报告来源路径。
- 无网络、无 provider/API、缺少依赖、路径跨 WSL/Windows 时，系统能区分环境问题和实现问题。
- 写入型能力有候选产物、diff、冲突说明、apply 结果和 rollback 证据。
- 测试报告明确区分静态契约、runtime 执行、宿主加载、真实模型执行四个层级。
七、WorkflowProgram 案例
WorkflowProgram 的 OpenCode 适配采用了上述通用原则。它没有复制 ClaudeCode 版的目录结构，而是把产品入口落到
.opencode/commands/wp-*.md，把角色能力落到 .opencode/agents/*.md，把 hook bridge 落到
.opencode/plugins/workflowprogram.ts，把确定性编排和 validator 放到 Python runtime。
安装模型上，WorkflowProgram 没有把完整能力全局安装，而是新增全局轻量 bootstrap：
/wp-install、/wp-status、/wp-upgrade、/wp-uninstall。
完整 /wp-develop、/wp-validate、agent pack、plugin 和 runtime 仍物化到每个目标项目中。
这个案例的特殊命名如 WP_PACKAGE_ROOT、TARGET_ROOT、RUN_ROOT、/wp-* 不是通用规定，
但背后的通用原则是：产品包根、目标项目根、运行证据根必须分离；产品命名空间和生成命名空间必须分离；全局便利性不能破坏项目隔离性。