用途
sync-opencode 用于在 opencode 上复现 Claude 侧配置的钩子、推荐配置、技能权限、命令与子代理,并验证生成结果的一致性。它是 opencode 相关流水线的唯一入口,按 Config → Sync → Test → Verify 的顺序执行,任一阶段非零退出即失败。
主要能力
- 配置合并:读取 .opencode/opencode.recommended.json,深度合并进项目根目录的 opencode.json。推荐配置的叶子键优先,仅存在于项目中的对象键保留,推荐文件中的数组替换项目数组。
- 钩子桥接:opencode 没有 shell 命令钩子系统,只有 JavaScript 插件回调。因此把 .claude/settings.json 编译成 .opencode/plugins/easy-claude-hooks.js,在 opencode 事件与 Claude 钩子之间双向翻译事件名、工具 ID、参数与退出码语义。
- 技能权限:opencode 忽略 disable-model-invocation,所以通过项目根 opencode.json 的 permission.skill 执行选择策略,并为每个技能生成 .opencode/commands/<name>.md 以保留 /name 手动入口。权限写入由 .opencode/skill-permissions.generated.json 账本记录归属,用户自行设置的键不被接管或放松。
- 子代理镜像:opencode 不自动发现子代理,因此 .claude/agents/.md 被镜像到 .opencode/agent/.md。技能本身被 opencode 自动发现,无需镜像。
- 测试与校验:运行配置、写入器与生成插件的运行时测试;在内存中用真实写入器重新合并/渲染并逐字节对比已跟踪文件。
使用方式
用 node 直接运行包内入口,例如:
node .claude/skills/sync-opencode/scripts/run-opencode-sync.mjs --list-stages
失败时可重跑单个阶段:--only=<stage> --verbose。不要通过宿主项目的 package.json 脚本驱动该框架。
关键规则与限制
- 必须按阶段顺序执行;不得手工编辑生成的 easy-claude-hooks.js。
- 修改框架默认值应编辑 .opencode/opencode.recommended.json 后重跑流水线;该文件不得命名为 opencode.json,以免被 opencode 当作项目配置自动加载。
- 仅编译
node "$CLAUDE_PROJECT_DIR"/...形态的钩子命令,其他形态报告为 unsupported-command-shape。 - opencode 无法复现的 Claude 事件在同步报告中记为 skipped-events,不会静默丢弃。
- opencode 无绝对压缩阈值,按模型注册窗口相对压缩;框架不为三个宿主固定自动压缩预算。
- 旧的手写 .opencode/plugins/notification.js 会被备份至 tmp/opencode-legacy/ 并删除,避免重复通知。
- 复制到新项目时不要复制 skill-permissions.generated.json 与 commands/,二者按项目生成。
外部依赖仅为 node >= 18;生成的插件只导入 node: 内置模块并调用 .claude/hooks/*.cjs 脚本。