oh-my-openagent 插件在 opencode 中加载失败:oh-my-openagent 插件在 openc

情况说明:oh-my-openagent 插件在 opencode 中加载失败

目的:本文件记录一次 oh-my-openagent 插件在 opencode 中无法加载的完整排查过程与方法,供后续 AI 代理或用户遇到同类问题时参考。

1. 概述

症状:在 opencode opencode.jsonc 中声明 oh-my-openagent@next 插件后,opencode 启动时插件崩溃,自定义 agent(Sisyphus、Hephaestus、Prometheus 等 13 个)全部不出现。

根因:两个独立问题叠加:

配置重复——同一插件在两个配置文件中被声明,触发插件自带的重复检测并自毁
包损坏——@next dist tag 当前解析到的版本(v4.5.12)在 Windows 上文件不完整,插件顶层模块同步 readFile 读取缺失文件时未捕获异常,导致模块加载失败

修复:删除项目级 ~/.opencode/ 配置目录 + 将插件 spec 从 @next 改为 @latest(v4.7.5 文件齐全)。

2. 用户视角的症状

现象	说明
启动慢	TUI 启动卡顿数十秒
启动时弹窗	GitHub 设备流登录弹窗(若同时存在 `/connect` 待处理状态)
13 个自定义 agent 不可见	agent 选择器中只有 opencode 内置的 `build` / `plan`,看不到 Sisyphus / Hephaestus / Prometheus / Atlas / Sisyphus-Junior / oracle / librarian / explore / metis / momus / multimodal-looker
TUI 主题不切换	即使配了主题,也不生效(因为 plugin 的 TUI 部分未加载)

3. 根因分析

3.1 第一个问题:配置重复 → 触发插件内自检后自毁

opencode 会从 多个层级 合并配置,包括:
- 全局 ~/.config/opencode/opencode.json[c]
- 项目级 ~/.opencode/opencode.json(当前工作目录的 .opencode/)
若同一插件在两个文件都被声明,opencode 会去重后保留全部(不去重)
插件入口处有 detectDuplicateOmoPlugin 检查,当发现自己的包名(oh-my-openagent)与列表中其他 spec 出现重叠(例如 oh-my-openagent 与 oh-my-openagent@next)时,直接 return {},仅注册空的 plugin 对象,不注册 config hook,导致后续所有 agent / command / skill 都不生效

判断标志(在 oh-my-opencode.log):

[oh-my-openagent] Duplicate OMO plugin entries detected
{"duplicatePlugins":["oh-my-openagent","oh-my-openagent@next"],
 "allPlugins":["oh-my-openagent","@mohak34/...","oh-my-openagent@next", ...]}

3.2 第二个问题:`@next` 包版本损坏 → 顶层模块同步读文件未捕获

oh-my-openagent@next 当前 npm dist tag 解析到 v4.5.12(发布时漏打了部分 skill 文件)
包内 packages/shared-skills/skills/ 下只有 debugging/ 和 programming/ 两个目录
- debugging/SKILL.md 缺失
- programming/SKILL.md 缺失
- frontend-ui-ux/ 整个目录缺失
插件 dist/index.js(行 89805)用 parseFrontmatter(readFile8(join73(baseDir, ...segments, skillName, "SKILL.md"), "utf8")) 同步读取 SKILL.md,外层无 try/catch
文件不存在时抛 ENOENT,整个模块加载失败,opencode 把 plugin 标记为 failed to load

判断标志(在 opencode 主日志,不是 oh-my-opencode.log):

ERROR service=plugin path=oh-my-openagent@next
error=ENOENT: no such file or directory, open
'...\.cache\opencode\packages\oh-my-openagent@next\node_modules\oh-my-openagent\packages\shared-skills\skills\frontend-ui-ux\SKILL.md'
failed to load plugin

3.3 时间线(可复现)

启动 → opencode 解析 config → 加载 plugins → 加载 oh-my-openagent@next
  ├─ [问题 1] 插件入口 detectDuplicateOmoPlugin 检查
  │    ├─ 若 allPlugins 含 "oh-my-openagent"(无版本) 且 "oh-my-openagent@next"
  │    │   → console.warn + return {} → plugin 注册为空(无 config hook)
  │    └─ 否则继续
  └─ [问题 2] dist/index.js 顶层同步 readFile SKILL.md
       ├─ 若 SKILL.md 存在 → 正常加载 13 agents / 9 commands
       └─ 若 SKILL.md 缺失 → 抛 ENOENT → opencode 标记 plugin 加载失败

关键观察:问题 1 触发时插件仍然会写一行日志(因为 detectDuplicateOmoPlugin 里调用了 console.warn);问题 2 触发时插件根本来不及写任何日志(模块加载阶段就崩了),但 opencode 主日志会有 ERROR 行。

4. 排查步骤(可复用 playbook)

给 AI 的话:按以下顺序依次执行,任何一步的失败标志都直接跳到对应修复段。

4.1 确认时间与基本状态

# 当前时间
Get-Date -Format "yyyy-MM-dd HH:mm:ss zzz"

# 是否有 opencode 进程在跑
Get-Process opencode -ErrorAction SilentlyContinue | Select-Object Id, StartTime

记录:当前时间 与 opencode 启动时间。后续日志中匹配该时间窗口的条目才是本次启动产生的。

4.2 定位关键日志

日志	路径	用途
opencode 主日志	`~/.local/share/opencode/log/<最近日期>T<时间>.log`	插件加载 ERROR / INFO 都在这里
插件私有日志	`%TEMP%\oh-my-opencode.log`(`$env:TEMP\oh-my-opencode.log`)	插件内部 `[oh-my-openagent]` 前缀的日志
npm 缓存	`~/.cache/opencode/packages/oh-my-openagent*`	已下载的插件包

重要:oh-my-opencode.log 中的 oh-my-opencode 来自插件内部二进制 oh-my-opencode.exe,不是 oh-my-openagent。这是正确的日志文件名。

4.3 读取 opencode 主日志开头(从最早一行往后数 ~30 行)

Get-ChildItem -LiteralPath "$env:USERPROFILE\.local\share\opencode\log" -File |
  Sort-Object Name -Descending | Select-Object -First 1 |
  ForEach-Object { Get-Content $_.FullName -TotalCount 30 }

关注:

service=config path=... loading 看到几个配置文件被加载
service=plugin path=oh-my-openagent@next loading plugin 是否出现
紧跟其后是否有 service=plugin ... error=ENOENT ... SKILL.md failed to load plugin

4.4 读取插件私有日志

Get-Content -LiteralPath "$env:TEMP\oh-my-opencode.log" -Tail 50

关注:

Duplicate OMO plugin entries detected → 问题 1(配置重复)
完全没新条目 + 主日志有 ERROR → 问题 2(包损坏)
出现 [config-handler] config handler applied {"agentCount":13,...} → 正常加载

4.5 决策树

主日志有 "failed to load plugin" + ENOENT SKILL.md ?
├─ 是 → 问题 2:@next 包损坏
│      修复:opencode.jsonc 把 "@next" 改成 "@latest"(或具体稳定版本号)
│
└─ 否 → 插件私有日志有 "Duplicate OMO plugin entries detected" ?
       ├─ 是 → 问题 1:配置重复
       │      修复:删除多源配置(详见 §5.2)
       │
       └─ 否 → 检查 ~/.cache/opencode/packages/oh-my-openagent* 各目录的版本和文件完整性

4.6 验证包完整性(排查问题 2 时)

$pkg = "$env:USERPROFILE\.cache\opencode\packages\oh-my-openagent@next"
Get-ChildItem -LiteralPath "$pkg\node_modules\oh-my-openagent\packages\shared-skills\skills" -Force |
  Select-Object Name
Get-Content "$pkg\node_modules\oh-my-openagent\package.json" -TotalCount 5

对比:

@latest 应有 10 个 skill:debugging, frontend-ui-ux, init-deep, lcx-report-bug, programming, refactor, remove-ai-slops, review-work, start-work, ulw-plan
@next 若少于 10 个或缺 frontend-ui-ux/,即可确认问题 2

5. 修复方案

5.1 问题 2 修复:切换到 `@latest`

编辑 ~/.config/opencode/opencode.jsonc:

  "plugin": [
    "@mohak34/opencode-notifier@latest",
-   "oh-my-openagent@next",
+   "oh-my-openagent@latest",
    "@tarquinen/opencode-dcp@latest"
  ]

保存后完全退出 TUI 再重启 opencode(仅关闭终端窗口不会让 opencode 重新读 config)。

5.2 问题 1 修复:消除多源声明

声明位置	应保留?	说明
`~/.config/opencode/opencode.jsonc`	是	全局配置,符合 opencode 官方约定
`~/.opencode/opencode.json`	否(在用户家目录场景)	这是项目级配置,只有 `cd <project>` 时才有意义。在 `C:\Users\<name>\` 下存在 = 噪音
`<任意 project>/.opencode/opencode.json`	看情况	若在真正的项目目录里且团队共享,可以保留

最直接的清理:删除 ~/.opencode/ 整个目录(默认无用户自建内容,opencode 不会自动重建)。如不放心可先:

Get-ChildItem -LiteralPath "$env:USERPROFILE\.opencode" -Force -Depth 0 |
  Select-Object Name, Length, LastWriteTime

确认没有 command/、agent/、skill/ 等用户自建目录后再删。

5.3 清理损坏的 npm 缓存(可选)

# 删损坏的 @next 缓存(确认已不再使用后)
Remove-Item -LiteralPath "$env:USERPROFILE\.cache\opencode\packages\oh-my-openagent@next" -Recurse -Force

# 删空的 tui/ 残留(早期 npm install 失败留下)
Remove-Item -LiteralPath "$env:USERPROFILE\.cache\opencode\packages\oh-my-openagent\tui" -Recurse -Force

5.4 验证修复成功

重启 opencode 后,日志应出现(时间戳对应本次启动):

[oh-my-openagent] Config loaded from ...\oh-my-openagent.json ...
[config-handler] agents loaded {"agentKeys":["Sisyphus - ultraworker","Hephaestus - Deep Agent", ...]}
[config-handler] config handler applied {"agentCount":13,"commandCount":9}

TUI 中按 Tab 切到 agent 选择器,应能看到 13 个自定义 agent。

6. 预防建议

配置来源要单一:全局插件放 ~/.config/opencode/opencode.jsonc,不要在 ~/.opencode/(家目录)重复声明。
优先用 @latest 而非 @next:本案例就是 @next 解析到损坏版本。生产环境慎用预发布 tag,或锁定到具体版本号(如 "oh-my-openagent@4.7.5")。
关注 opencode 主日志的 ERROR service=plugin ... failed to load plugin 行:插件完全没加载的标志,比插件私有日志更早出现。
首次安装 oh-my-openagent 时,删除前次残留的 ~/.opencode/ 与 ~/.cache/opencode/packages/oh-my-openagent* 损坏版本。
若要给插件作者反馈:用英文开 issue 到 https://github.com/code-yeongyu/oh-my-openagent/issues/new,不要到 anomalyco/opencode(那是 opencode 主仓)。反馈时应说明:
- opencode 版本
- 插件版本(@next / @latest / 具体号)
- OS 与架构
- 完整 ENOENT 路径(去用户名)

7. 关键路径速查(脱敏)

# 全局配置
~/.config/opencode/opencode.jsonc
~/.config/opencode/oh-my-openagent.json
~/.config/opencode/tui.json

# 项目级配置(常被误用)
~/.opencode/opencode.json

# 插件 npm 缓存
~/.cache/opencode/packages/oh-my-openagent/
~/.cache/opencode/packages/oh-my-openagent@latest/
~/.cache/opencode/packages/oh-my-openagent@next/   # 损坏版,删除

# opencode 主日志
~/.local/share/opencode/log/<YYYY-MM-DD>T<HHMMSS>.log

# 插件私有日志
%TEMP%\oh-my-opencode.log

8. 附录:本案例的修复动作清单(供其他 AI 复现)

#	动作	命令/路径	状态
1	删除项目级配置目录	`Remove-Item ~/.opencode -Recurse -Force`	✓ 完成
2	修复 TUI 插件配置(去掉 `oh-my-openagent/tui` 引用,该子路径不存在)	编辑 `~/.config/opencode/tui.json` → `{"plugin":[]}`	✓ 完成
3	切换插件 spec 从 `@next` 到 `@latest`	编辑 `~/.config/opencode/opencode.jsonc`	✓ 完成
4	重启 opencode	退出 TUI 后再开	✓ 完成
5	删除损坏的 @next npm 缓存	`Remove-Item ~/.cache/opencode/packages/oh-my-openagent@next -Recurse -Force`	✓ 完成(释放 295.2 MB)
6	清理空的 tui/ 残留	`Remove-Item ~/.cache/opencode/packages/oh-my-openagent/tui -Recurse -Force`	✓ 完成

9. 给 AI 的 prompt 模板(用户报"oh-my-openagent 不工作"时直接套用)

你是 AI 代理。用户报告 oh-my-openagent 插件在 opencode 中不可用。

请按以下顺序排查,并把每一步的发现汇报给用户:

1. 确认当前时间: Get-Date -Format "yyyy-MM-dd HH:mm:ss zzz"
2. 列出 opencode 进程: Get-Process opencode
3. 读取 opencode 主日志(取最近一个日志文件的前 30 行): 
   Get-ChildItem ~/.local/share/opencode/log -File | Sort Name -Desc | Select -First 1 | % { Get-Content $_.FullName -TotalCount 30 }
4. 读取插件私有日志: Get-Content $env:TEMP\oh-my-opencode.log -Tail 50
5. 列出全局配置目录: Get-ChildItem ~/.config/opencode -Force
6. 列出插件 npm 缓存: Get-ChildItem ~/.cache/opencode/packages
7. 列出项目级配置: Get-ChildItem ~/.opencode -Force -Depth 0

根据发现判断属于以下哪种情况:
A) 主日志: "ENOENT ... SKILL.md ... failed to load plugin"
   → 插件包损坏。读 ~/.cache/opencode/packages/oh-my-openagent@next/node_modules/oh-my-openagent/packages/shared-skills/skills/ 看缺什么 skill。
   → 修复: opencode.jsonc 把 @next 改 @latest(或具体稳定版本)。
B) 插件日志: "Duplicate OMO plugin entries detected"
   → 配置重复。看 allPlugins 列表,找出 oh-my-openagent 被声明的多个位置,删多余的(通常是 ~/.opencode/opencode.json)。
C) 都没有
   → 检查 ~/.cache/opencode/packages/oh-my-openagent* 各目录是否完整、版本是否与配置一致。

修复后必做:
- 完全退出 TUI 再重启 opencode
- 验证 %TEMP%\oh-my-opencode.log 末尾有 [config-handler] config handler applied {"agentCount":13,...}

oh-my-openagent 插件在 opencode 中加载失败