Skip to content

[Bug] Plugin fails to load under OpenCode 2.1.0: bare package name entry dist/index.js lacks a default export (Plugin mu | [Bug] OpenCode 2.1.0 下插件加载失败:裸包名入口 dist/index.js 没有默认导出(Plugin must export a default definition) #3976

Closed

Description

@lidesjiang

环境

  • OpenCode:2.1.0(当前最新)
  • billion-context:0.1.202(npm 上当前最新,已全局安装:npm install -g billion-context)
  • 操作系统:Windows
  • 配置方式:按 README「手动安装」一节,在 OpenCode 配置中写入
{
  "plugin": ["billion-context"],
  "compaction": { "auto": false }
}

现象

OpenCode 启动后,服务器端日志反复出现下面的警告(同一动作重试三次,产生三个错误编号):

level=WARN role=server message="failed to load plugin"
target=billion-context
cause=PluginModule.LoadError: Plugin must export a default definition with an id and an
      effect or setup function. (cause: SchemaError(Missing key at ["default"]))

紧随其后还有一条:

message="failed to check plugin update" target=billion-context
cause=NpmInstallFailedError: Package is not installed: billion-context

结果是 OpenCode 本身正常运行,但 billion-context 的压缩代理没有启动,压缩功能不生效。

复现步骤

  1. npm install -g billion-context
  2. 按 README「手动安装」一节,在 OpenCode 配置里写入上面那两段配置
  3. 启动 OpenCode,查看 ~/.local/share/opencode/log/opencode.log(或本机对应的数据目录)
  4. 可以看到第 2 节引用的警告,插件加载失败

原因分析

1. OpenCode 实际加载了哪个文件

服务器日志明确记录了加载的入口点:

msg="loading plugin" id=billion-context
entrypoint=file:///<npm 全局目录>/node_modules/billion-context/dist/index.js

也就是包 main 字段指向的 dist/index.js。

2. 这个文件是否满足插件规范

OpenCode 2.x 要求被加载的插件文件用默认导出提供一个对象,对象里要有 id,以及 setup 或 effect 函数。用 Node 直接导入包内四个相关文件逐一检查:

文件 检查结果 结论
dist/index.js(main 指向,即日志中的入口点) 导入成功,模块没有任何导出 没有默认导出,失败属实
dist/agent/dsh-native.js(根导出 . 指向) 只有一批内部测试用的具名导出 同样没有默认导出
dist/agent/opencode-native.js(./server 导出指向) 有完整的默认导出 这才是 OpenCode 插件本体
dist/agent/opencode.js(启动器生成配置时使用的文件) 有完整的默认导出 同样可用

3. 结论

README 建议写裸包名 "billion-context",并说明 OpenCode 会通过自己的 Npm.add 机制读取包的 exports["./server"],也就是 dist/agent/opencode-native.js。在 OpenCode 2.1.0 上实测这个说法不成立:以裸包名加载时,OpenCode 用的是 main 字段(或根导出),而 main 指向的 dist/index.js 是 bili 命令行工具的主程序,只有参数解析和服务器启动逻辑,不含插件定义,也没有默认导出。校验失败后插件被放弃。

后面的 Package is not installed: billion-context 说明插件也不是通过 OpenCode 自己的安装机制装进来的,版本检查同样失败。

4. 附带发现:配置键是旧版写法

文档和安装程序写入的键是 "plugin",而 OpenCode 2.x 的配置键是 "plugins"(复数;"plugin" 是旧版遗留写法,当前版本仍然接受)。

当前可行的写法

「目录 + 重导出」,已在 OpenCode 2.1.0 上实测可用:

  1. 新建一个目录,里面放一个 index.js,内容一行:

    export { default } from "file:///<npm 全局目录>/node_modules/billion-context/dist/agent/opencode-native.js";
  2. 在 OpenCode 配置中以目录形式引用该目录:

    {
      "plugins": [
        "<该目录的路径>"
      ],
      "compaction": { "auto": false }
    }

说明:OpenCode 2.1.0 对条目有两条硬性规则,写成单个文件的路径会被拒绝(configured plugin path must be a directory);写成 "billion-context/server" 会被当成需要 npm 或 git 安装的目标而失败。因此读取目录内的 index.js 是目前唯一能直接用到 opencode-native.js 的方式。

建议的修复方向

  1. 让裸包名 "billion-context" 可以直接工作,例如调整包的入口结构,使 OpenCode 以包名加载时读到的就是 OpenCode 插件定义;或者修改 README,改成实测可行的写法(见上一节)。
  2. 同步更新 README 中 OpenCode 2.x 的安装说明,并让安装器(bili plugin install opencode)和启动器生成的临时配置都采用「plugins 键 + 目录形式」。

Activity

  1. changed the title [-][Bug] OpenCode 2.1.0 下插件加载失败:裸包名入口 dist/index.js 没有默认导出(Plugin must export a default definition)[/-] [+][Bug] Plugin fails to load under OpenCode 2.1.0: bare package name entry dist/index.js lacks a default export (Plugin mu | [Bug] OpenCode 2.1.0 下插件加载失败:裸包名入口 dist/index.js 没有默认导出(Plugin must export a default definition)[/+] on Oct 20, 2026
  2. ranxianglei commented on Oct 20, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    查重:不重复。 搜过 open/closed 的 issue 与 PR(按症状与机制检索,不只标题),没有同症状同机制的条目;最接近的 #2656 是 opencode V2 通道 acp_retrieve 工具注册问题,机制不同且已关闭。

    标签:bug / opencode / scope/wiring / p1 —— README 手动安装与 bili plugin install opencode(npm 形态)两条文档化路径在最新 OpenCode 2.1.0 上插件都加载不了、压缩完全失效,属核心承诺失灵,判 p1。

    初步核对(master 即你装的 0.1.202):

    • 仓库状态与你列的四文件导出形状一致:main → dist/index.js(CLI 主程序,无默认导出);exports["./server"] → dist/agent/opencode-native.js(真正的插件本体)。
    • 「裸包名经 Npm.add 读 exports["./server"]」的说法当时是在 2.0.3 上验证的;2.1.0 实测加载的是 main 指向的文件,说明 OpenCode 在这两个版本之间改了插件解析行为——这是根因所在,不是我们入口结构写错。

    接下来我会:把 @opencode/cli 2.1.0 装到本地读它的插件加载源码,钉死它解析裸包名时到底看哪个字段、认哪个配置键(plugin/plugins)、目录约束从哪来;然后三线修复——① bili plugin install opencode 写入的条目形式;② bili opencode 启动器生成的临时配置;③ README / CLIENTS.md(en+zh)的手动安装说明。有结论即回报。

  3. rwjxrj commented on Nov 9, 2026

    @rwjxrj

    2.2.5 上复现,本地 ESM shim 同样有效(补充确认修复方向)

    复现环境:

    • OpenCode:@opencode/cli 2.2.5(npm 全局)
    • billion-context:0.1.213(npm 全局,npm install -g billion-context)
    • OS:Windows 11
    • 安装方式:bili plugin install opencode(0.1.213 安装器写入裸包名)

    现象与本 issue 一致

    裸包名入口加载失败,且在 2.2.5 上症状更严重——不是仅告警,而是 /reload 直接抛 TypeError(TUI 弹窗):

    TypeError: o is not a function. (In 'o()', 'o' is an instance of Object)
        at <anonymous> (chunk-pa4tadds.js:...)
        at ServerProcess.start (chunk-vjacg5s7.js:...)
    

    opencode plugin update 同步报:

    Failed to check Server plugin "billion-context": Plugin must export a default
    definition with an id and an effect or setup function.
    

    对本 issue 第 3 节结论的补充

    在 2.2.5 上,opencode 加载 dist/index.js(CJS,无导出)后拿到的不是"没有定义",而是一个 Object 形状的东西被当函数调用——与 issue 里 2.1.0 的 SchemaError(Missing key at ["default"]) 文案不同,但根因相同:裸包名解析不到 exports["./server"],README 的 Npm.add 说法在 2.2.5 依旧不成立。

    修复验证:两种 shim 形态均可用

    按本 issue 的「目录 + 重导出」方案实测通过。我还验证了一个等价变体——单个 .js 文件放进 ~/.config/opencode/plugins/(靠 opencode 的 plugins 目录自动发现,不需要配置条目、不需要目录形式):

    // ~/.config/opencode/plugins/billion-context-esm-shim.js
    import * as ns from "file:///D:/nodejs/node_global/node_modules/billion-context/dist/agent/opencode-native.js"
    const raw = ns?.default?.setup ? ns.default : ns?.default?.default ?? ns.default
    export default { id: raw?.id ?? "billion-context-opencode-native", setup: raw.setup, server: raw.server }

    (raw 解包是防御性的:file: 导入 CJS 时部分运行时给的是整个 namespace 而非 module.exports.default。)

    端到端验证结果(2.2.5 + 0.1.213):

    • opencode plugin list 正常列出 billion-context-opencode-native (local)
    • opencode plugin update 不再报 definition 错误
    • 插件自起代理成功,bili.log 出现 [plugin] [acp-usage] input=…,模型请求确实走压缩链路
    • /reload 不再抛 TypeError

    给维护者的两点建议(与本 issue 第 4 节建议合并)

    1. 裸包名入口:main / 根导出 . 目前指向 dist/index.js(CLI)和 dsh-native.js。若 opencode 侧无法推动其按 exports["./server"] 解析裸包名,可考虑把包拆成 billion-context(CLI)+ 子包或双入口,让根入口本身就是 OpenCode 插件定义。
    2. 安装器:bili plugin install opencode 在 2.x 上目前写入的裸包名 + 旧键 "plugin" 双双失效,建议安装器检测 opencode ≥ 2.0 时直接采用本 issue 的目录 shim 写法(并把键改为 "plugins"),把 workaround 内化到安装器里。

    如需我补充 2.2.5 上的完整日志(opencode.log / bili.log 片段),告诉我即可。

  4. ranxianglei commented on Nov 9, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    @rwjxrj 的 2.2.5 数据非常关键——/reload 直接抛 TypeError 说明问题比 2.1.0 更严重,两种 shim 形态的验证也帮我们钉死了修复方向。已按本 issue 的方案修完,PR:#6002。

    根因:OpenCode 2.x 用包的 main 字段解析裸包名(dist/index.js = CLI,无默认导出),而不是 README 说的 exports["./server"];安装器和文档在 2.x 宿主上写的正是裸包名,所以必挂。Linux 2.1.0 上裸包名碰巧能加载(Arborist 缓存路径),所以旧写法过了评审、只在 Windows 上暴露——两位报告者都是 Windows。

    修法(把实测可用的 workaround 内化到安装器):

    • bili plugin install opencode 在 2.x 宿主(以及 git checkout/开发构建)上改写 shim 目录条目:<configDir>/plugins/billion-context/index.js → 重导出本次安装的 dist/agent/opencode-native.js,就是两位实测可用的形态;
    • 1.x npm 安装保持裸包名不变(那里仍然可用);
    • 2.x 配置里的遗留裸包名条目重跑 install 时自动迁移为 shim;shim 指向旧安装路径时重装会自动重新生成指向当前根;
    • README(中英)与 clients 文档(中英)的手动安装说明按宿主代次拆分:1.x 裸包名 / 2.x「目录 + 一行重导出」;
    • doctor/update 文案改为读 shim 目标,区分 npm 根安装(随 bili 自身自更新)与 checkout。

    行为变更披露(旧→新):

    • 2.x 宿主的安装器写入:"plugins": ["billion-context"] → "plugins": ["<configDir>/plugins/billion-context"](shim 目录)。原因:裸包名在 2.x(至少 Windows)永远加载不出来;shim 形态在 Linux/Windows × 2.1.0/2.2.5 四组合均有实测可用。
    • 连带:2.x npm 安装不再产生 opencode 侧的 Arborist 缓存副本,更新改由 bili 自身自更新承担(全局路径稳定);opencode plugin update 对它原先的检查从此不适用。
    • 1.x 行为逐字节不变(版本探测失败仍保守按 1.x 处理)。

    验证:真实 @opencode/cli 2.1.0 二进制在隔离环境跑了完整矩阵(复数/单数键 × 裸包名/shim 目录),shim 两组零加载失败、模块图完整解析、代理正常拉起;再叠加两位在 Windows 2.1.0/2.2.5 的端到端实测。代码侧新增单元测试(2.x 写 shim、遗留裸包名迁移、幂等、陈旧 shim 自愈)+ 一条假 2.x 版本探测的接线 e2e;定向测试 32/32、plugin-agent 76/76,typecheck 干净,全量回归交给 CI。

    遗留提示:已在 2.x 上用旧版 bili 装过的人,升级后重跑一次 bili plugin install opencode 即自动迁移;rwjxrj 的单文件 ~/.config/opencode/plugins/*.js 自动发现变体同样有效,但安装器统一采用配置目录下、可被 status/remove 管理的 shim 目录形态。

    标签:bug / opencode / scope-wiring / p1 —— 文档化安装路径在当前 OpenCode 下压缩整体失效(核心承诺失灵),定 p1。

    八问:

    1. 是什么问题:OpenCode 2.x 宿主上按文档/安装器写入的裸包名插件入口加载失败,压缩代理不启动;2.2.5 上连 /reload 都会抛 TypeError。
    2. 什么原因导致的:2.x 按包 main 字段解析裸包名(dist/index.js 是 CLI、无默认导出),而安装器/README 假设它走 exports["./server"];该假设在 Linux 上碰巧成立、Windows 上不成立,评审时被掩盖。
    3. 影响范围与严重程度:OpenCode ≥2.0 + Windows 的全部原生安装用户压缩功能整体不可用(核心能力失效)= p1;Linux 用户当前侥幸可用但不作保证。
    4. 怎么修复的:安装器对 2.x 宿主改写本机 shim 目录条目(重导出真实插件文件),把用户实测可用的 workaround 内化;文档按宿主代次拆分;遗留裸包名条目自动迁移。
    5. 是否有回归问题:1.x 路径逐字节不变;dev/checkout 形态本来就是 shim,仅 2.x-npm 分支改变;map 形态配置的外来条目保留逻辑由既有测试钉住;status/remove/doctor 对两种形态 × 两种键的组合均已覆盖并有测试。
    6. 是否破坏缓存:不涉及模型/前缀缓存;唯一相关的是 opencode 侧 Arborist 缓存副本不再产生(见行为变更),bili 自身会话存储不受影响。
    7. 是否改了设计方向:没有——仍是「安装器写宿主配置」,只是 2.x 车道的条目形态从裸包名换成本机 shim 目录(与 dev 形态、launcher 临时包装目录同一机制家族)。
    8. 是否引入了新的配置:没有新 env/config 键;变化的只有安装器写入宿主 opencode 配置的条目值。

    收工判定:PR #6002 已开(Closes #3976),定向验证全绿,等 CI 全量结果;合并并发版后,2.x Windows 用户重跑 bili plugin install opencode 即可一步到位。

  5. ranxianglei commented on Nov 9, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    CI 状态更新:PR #6002 首跑 11 个 test 分片全红,经核对为继承性 master 红(LIVE_FILES tripwire,与 #4599 总控在途的同一签名,与本 PR 改动无关);已按协调协议把 ci-fixes(831b645)合入分支重推,新 head 311a34f7e6,CI 重跑中。本 PR 自身的静态门禁(gate/unused-exports/architecture-docs/mysql-contract/static-gates)在首跑已全部转绿。其余结论以上一条回复为准(根因、修法、行为变更披露、八问)。

  6. added a commit that references this issue on Nov 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions