@marscore-archi/opencode-omo-slim-sync

OpenCode 插件：启动时按一级 key 将远程 oh-my-opencode-slim 配置合并回写本地 ~/.config/opencode/oh-my-opencode-slim.json[c] 文件，让本地始终跟随远程推荐，同时保留本地独有的自定义项。

安装

1. 安装插件

cd .opencode && npm install @marscore-archi/opencode-omo-slim-sync

2. 声明插件

opencode v1（≥1.18.29）在 opencode.json 中添加：

{
  "plugin": ["@marscore-archi/opencode-omo-slim-sync"]
}

opencode v2 在 opencode.jsonc 中添加：

{
  "plugins": ["@marscore-archi/opencode-omo-slim-sync"]
}

加载顺序：v2 按 plugins 数组顺序加载插件。若同时使用 oh-my-opencode-slim，请将本插件排在它之前，确保合并回写先于 slim 读取本地文件。

3. 启动 OpenCode

opencode

启动时插件会自动拉取远程 slim 配置并合并回写本地文件。本次启动的内存配置不会被修改，下次启动由 oh-my-opencode-slim 自行从合并后的文件加载生效。

工作原理

每次启动
  |
  +-- fetch https://archi.marscore.net/guide/oh-my-opencode-slim.json
  |     * AbortSignal.timeout(3000)
  |
  +-- 3s 内成功? ---- 否 ----> console.warn 并跳过本次更新
  |
  v 是
  +-- 选择本地文件:
  |     * ~/.config/opencode/oh-my-opencode-slim.jsonc  (优先)
  |     * ~/.config/opencode/oh-my-opencode-slim.json   (其次)
  |     * 都不存在 ----> 跳过回写, 不创建新文件
  |
  +-- 读取本地 (.jsonc 剥 // 与 /* */ 注释, 容错尾逗号)
  |
  +-- 一级 key 浅合并: merged = { ...local, ...remote }
  |     * 远程存在的一级 key 整体覆盖本地同名 key
  |     * 本地独有的一级 key 原样保留
  |
  +-- 合并结果与原文件 (规范序列化后) 一致? ---- 是 ----> 跳过写
  |
  v 否
  +-- 原子回写:
        * 写同目录 .<basename>.tmp.<pid>
        * fs.renameSync 覆盖目标
        * 保留 .json / .jsonc 扩展名

合并语义

合并为一级 key 浅合并，不做深层递归：

• 远程存在的一级 key 整体覆盖本地同名 key 的值（本地对该 key 内部的私改会丢失）。
• 本地独有的一级 key 原样保留。
• 远程独有的一级 key 新增进本地。

示例（merged = { ...local, ...remote }）：

local  = { a: 1, b: { x: 1 } }
remote = { b: { y: 2 }, c: 3 }
merged = { a: 1, b: { y: 2 }, c: 3 }

b 被整体替换为远程的值，a 保留，c 新增。

3 秒超时与失败跳过

• 远程拉取通过 AbortSignal.timeout(3000) 施加 3 秒超时上限。
• 超时、网络错误、非 2xx 状态码、JSON 解析失败均 console.warn 并跳过本次更新，不抛错、不阻塞 opencode 启动。
• 不做缓存兜底：远程不可达即跳过，不读取也不写入任何缓存文件。

.jsonc 注释会丢失（已知 trade-off）

.jsonc 文件解析时会剥除 // 行注释与 /* */ 块注释以获得语义对象，但合并回写时是整体重写文件，使用 JSON.stringify 规范序列化，无法还原原始注释。这意味着：

• 你在 .jsonc 中写的注释会在某次合并（合并结果与原文件不同）触发回写时丢失。
• 若合并结果与原文件一致，则不会触发写入，注释得以保留。

建议：若重视注释，可把注释集中放在一份不受远程影响的本地副本中；或接受周期性丢失。未来 v2 可能引入 JSONC AST 合并以保留注释。

自定义配置建议

由于一级 key 浅合并会用远程值整体覆盖同名 key，若你想保留自定义内容，建议把它放在远程不会发布的一级 key 下。例如远程发布 $schema、agents、preset、presets，你可自建 myCustom 等一级 key 存放私改——它不会被远程触及。

注意：即便如此，本插件是整体重写文件，本地独有 key 的值会被保留，但若该 key 内部嵌套了远程也发布的子结构，浅合并仍只看一级 key，不会深层混合。请按一级 key 规划你的自定义项。

与 opencode-provider 共存

本插件与 @marscore-archi/opencode-provider 职责不同、互不依赖，可同时声明：

opencode v1：

{
  "plugin": [
    "@marscore-archi/opencode-provider",
    "@marscore-archi/opencode-omo-slim-sync"
  ]
}

opencode v2：

{
  "plugins": [
    "@marscore-archi/opencode-omo-slim-sync",
    "@marscore-archi/opencode-provider"
  ]
}

• opencode-provider 同步 provider 配置（v1 合并进 config.provider、v2 通过 ctx.provider.transform 注入，带缓存兜底与 {env:XXX} 占位符解析）。
• 本插件同步 slim 配置到磁盘文件（无缓存、无占位符解析，仅落盘）。

许可证

UNLICENSED - 内部使用

兼容性

该插件同时兼容 opencode v1 与 v2，同一发布包无需按版本选择：

• opencode v1（≥1.18.29）：使用 "plugin" 配置字段，插件通过 server() 入口加载。
• opencode v2：使用 "plugins" 配置字段，插件通过 setup() 入口加载（直接执行回写流程，不注册任何 transform/hook）。
• 插件 package.json 不声明任何 peerDependency——v1/v2 路径均不引用 opencode 插件包，因此任一版本的宿主环境均可安装而不报缺失。
• v2 下若同步过程出错，插件会向 console 输出 [omo-slim-sync] 前缀的警告并跳过本次更新，不阻塞 opencode 启动。