Skip to content

fix(plugin): 拆分 server/tui 入口兼容 OpenCode v1 插件规范#15

Merged
Hotakus merged 1 commit into
masterfrom
fix/rename-tui-to-server
Jun 29, 2026
Merged

fix(plugin): 拆分 server/tui 入口兼容 OpenCode v1 插件规范#15
Hotakus merged 1 commit into
masterfrom
fix/rename-tui-to-server

Conversation

@Hotakus

@Hotakus Hotakus commented Jun 29, 2026

Copy link
Copy Markdown
Owner

问题

Ctrl+P → install plugin 安装本插件后,部分用户遇到 OpenCode 启动报错并退出:

Plugin opencode-visual-cache must default export an object with server()

根因

Ctrl+P → install plugin 会根据 package.jsonexportsmain 字段判定插件具备哪些 target(install.tspackageTargets):

  • exports["./server"] 不存在,但 main 存在 → 推入 { kind: "server" }
  • exports["./tui"] 存在 → 推入 { kind: "tui" }

因此插件被同时写入 opencode.json(server 通道)和 tui.json(TUI 通道)。

本插件是纯 TUI 插件,dist/index.jsmain 指向的文件)只导出 { id, tui },没有 server 键。OpenCode v1 加载器 readV1Pluginkind=server 解析该模块时,因 server 键为 undefined 而抛错。

TUI 通道从 exports["./tui"] 加载 dist/tui.js,始终正常——所以 TUI 功能能显示,server 通道的报错在某些 OpenCode 版本下被吞为日志,在另一些版本下直接导致退出。

修复方式

按 OpenCode v1 规范,./server./tui 应为分离的 target-only 模块,互斥导出(PluginModule.tuinever)。

  • 删除 main 字段,移除 exports["."] 通用入口——切断 server 通道对 TUI 模块的 fallback 解析路径。
  • 新增 exports["./server"] 指向 dist/server.js,导出空 server({ id, server: async () => ({}) })——server 通道加载到合法的 PluginModule,不注册任何 hook,完全静默。
  • 新增 src/server.ts 作为空 server 入口源文件。
  • TUI 功能仍由 ./tui 入口承载,不受影响。

生效机制

opencode.json (server 通道) → exports[./server] → dist/server.js → { id, server } → 校验通过,空 server 静默运行
tui.json    (TUI 通道)    → exports[./tui]    → dist/tui.js    → { id, tui }    → 侧边栏正常

两个通道各取各的入口,互不干扰。Ctrl+P → install plugin 同时写两个文件都不出问题。

OpenCode v1 插件加载器按 package.json exports 的 ./server 和 ./tui
分别解析 server 与 TUI 插件,且要求两者互斥(PluginModule.tui 为
never)。本插件为纯 TUI 插件,但 package.json 暴露了 main 指向
dist/index.js(仅导出 { id, tui }),当用户经 Ctrl+P install plugin
将包写入 opencode.json 的 server 通道时,加载器以 kind=server 解析
该模块并抛出 must default export an object with server()。

修复方式:
- 删除 main 字段,移除 exports[.] 通用入口,切断 server 通道对
  TUI 模块的 fallback 解析路径。
- 新增 exports[./server] 指向 dist/server.js,导出空 server
  ({ id, server: async () => ({}) }),使 server 通道加载到合法
  的 PluginModule 而非报错,TUI 功能仍由 ./tui 入口承载。
- 新增 src/server.ts 作为空 server 入口源文件。

同 opencode-subagent-magazine issue #8 的根因与修复方式。
@Hotakus Hotakus self-assigned this Jun 29, 2026
@Hotakus Hotakus added bug Something isn't working enhancement New feature or request labels Jun 29, 2026
@Hotakus Hotakus merged commit b1d6db6 into master Jun 29, 2026
2 checks passed
@Hotakus Hotakus linked an issue Jun 29, 2026 that may be closed by this pull request
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

cannot work

1 participant