Skip to content

opencode native 插件无法走规范安装:npm 包未暴露插件入口(exports)、native 入口未随包发布,安装器只能写本机绝对路径 shim #925

Closed

Description

@jensenojs

预期行为

用户在 opencode 配置里写一行 "plugins": ["billion-context"],opencode 用自己的插件机制(Npm.add)装包并负责升级。同一份配置能直接同步到另一台机器,不含任何本机绝对路径。

现状(2026-09-18 实测)

  • npm latest = 0.1.118,tarball 的 dist/agent/ 只有 dsh-acp.js / omp.js / opencode.js / pi.js,没有 opencode-native.js。native 插件只存在于未合并的 feat/pi-native-plugin(tip 2c5a6f8)。
  • package.json:main: dist/index.js,没有 exports(pi-native 分支上 exports 也是 null)。opencode 2.x 解析配置里的裸包名时按 <name>/server 子路径走 Node 解析,没有 exports map 就落不到插件入口。
  • 因此 bili plugin install opencode 只能写 shim 目录:<config dir>/plugins/billion-context/index.js 内容为 export { default } from "<本机 checkout 绝对路径>/dist/agent/opencode-native.js";
  • 后果:配置无法跨机同步(用 yadm/chezmoi 同步 dotfiles 的场景直接坏);升级必须人工 git pull && npm run build;opencode 自己的插件升级机制完全用不上。
  • release v0.1.119 #922 release v0.1.119 只含 fix(#728): proactive nudge for upstreams that never report usage #731 / test(launcher): isolate the host client, proxy and CA env vars #895,不含 native 工作流,短期内 npm 上不会出现。

建议

  1. package.json 显式枚举 exports(opencode 2.x: no-launcher npm-plugin deployment — plugins: ["billion-context"], plugin lazily spawns the proxy #809 里讨论过的形态:不用 wildcard,只暴露稳定子路径),把 opencode 插件入口暴露出来。
  2. native 入口随包发布(确保进 files)。
  3. plugin install opencode 判断自身来源:npm 安装时写裸包名条目,只有本地 git checkout 才写 shim 目录,并在输出里说明这是开发形态、不可跨机。

验收

  • npm pack billion-context@<新版> 的 tarball 含 opencode native 插件入口
  • opencode 配置里只写 "plugins": ["billion-context"](零绝对路径)即可加载插件并自拉起代理
  • 同一份配置拷到另一台机器直接生效

Activity

  1. jensenojs commented on Sep 18, 2026

    @jensenojs
    ContributorAuthor

    补一条实测证据,比 issue 正文描述的情况更严重:"plugins": ["billion-context"] 不是「装了拿不到插件」,而是会在 opencode 服务进程里把 CLI 入口当插件模块加载并产生副作用。

    opencode 2.0.3 的入口解析(packages/plugin/src/host.ts:17-43):

    return { server: entry(["server", ""]), tui: entry(["tui"]), rpc: entry(["rpc"]) }
    // entry: subpath 依次尝试 → 有 name 时 specifier = [name, subpath].filter(Boolean).join("/")

    即先试 billion-context/server,失败后 subpath "" 回退到裸包名 billion-context → main → dist/index.js。

    实测(npm i billion-context@0.1.118,node 里 import 裸包名):

    default type: undefined
    default keys: (none)
    named exports: []
    2026-...Z [info] [persist] enabled
    2026-...Z [info] [log] writing to ~/.local/state/billion-context/bili.log
    2026-...Z [info] [update] auto-update enabled (checking every 180s)
    2026-...Z [error] listen failed: EADDRINUSE listen EADDRINUSE: address already in use 127.0.0.1:8787 ...
    

    require.resolve("billion-context/server") → MODULE_NOT_FOUND(无 exports),main = dist/index.js。

    所以按规范方式配置的后果是三重的:

    1. 插件契约拿到 undefined(无 id/setup/server),opencode 得不到插件
    2. 导入 dist/index.js 的副作用当场在宿主进程里启动代理、开 180s 周期的 auto-update 定时器
    3. 端口已被占用时在宿主进程里抛 EADDRINUSE

    也就是说包目前的形状下,规范安装路径不是「不工作」,而是「以一种有副作用的方式不工作」。

    这给 issue 正文的建议加了一条优先级更高的要求:exports 缺失时不该由 main 兜底承接插件加载。显式枚举 exports(至少 "./server" 指向 native 插件入口)同时解决 1/2/3——子路径存在后 opencode 不再回退到裸包名,CLI 入口也就不会被当插件导入。

    顺带:dist/index.js 作为 main 在 import 时就产生监听/定时器副作用,本身对任何把它当库导入的场景都是隐患,可以考虑把副作用收进 bin 或显式的 start() 调用之后(这条属于独立话题,若认为值得单独跟踪我另开 issue)。

  2. ranxianglei commented on Sep 18, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 全部论断已独立核实——包括在最新发行版 @opencode/cli 2.0.7 上做到二进制级的加载器契约验证。结论与你的优先级判断一致,方案见下,实现已开始。

    1. 加载器契约——从 2.0.7 发行二进制里直接提取确认

    2.0.7 的 npm 包是 Bun 编译的单体 ELF(bin/opencode.exe + 平台包),所以我把入口解析函数直接从内嵌 JS bundle 里抠了出来,与你引用的 host.ts 逐字一致:

    function cm(r){ let n=(t)=>{ for(let o of t){
      let i = r.name ? [r.name,o].filter(Boolean).join("/") : path.resolve(r.directory, o||"index");
      try { return pm(i, r.directory) }        // pm = Bun.resolveSync(完整 Node 解析,认 exports map)
      catch(e){ /* 吞 ENOENT/ENOTDIR/MODULE_NOT_FOUND/ERR_MODULE_NOT_FOUND/ERR_PACKAGE_PATH_NOT_EXPORTED/ERR_UNSUPPORTED_DIR_IMPORT */ }
    }}; return { server: n(["server",""]), tui: n(["tui"]), rpc: n(["rpc"]) } }

    即 named spec 的 server 入口:先试 billion-context/server,失败才回落裸包名 → main → dist/index.js。你实测的「宿主进程里起监听 + 180s auto-update 定时器 + EADDRINUSE」正是这条回退链把 CLI 的模块级 main() 在服务进程里跑了一遍。而今天 require.resolve("billion-context/server") 失败是因为 0.1.118 根本没有 exports 字段(发布 tarball 已验:无 exports,dist/agent/ 只有 dsh-acp/omp/opencode/pi)。

    2. 对修复方案的含义

    你的优先级排序是对的,而且这让修复严格优于现状:一旦 exports["./server"] 解析成功,回退链永不触发,CLI 入口的三类副作用就从插件加载路径上彻底消失。在 native 入口发布前,带 ".": "./dist/index.js" 的 exports map 对所有现有消费者字节等价(main 行为不变)。

    关于附带发现(dist/index.js 作为 main 在 import 时产生监听/定时器副作用):同意值得单独跟踪——任何把根入口当库导入的场景都会继承一个活监听器 + 定时器。平台规则限制我不能在工作会话里开 issue;你开了我就接手(候选形态:根入口去副作用化、CLI 收进显式 start() 或 bin guard)。

    3. 落点与实现范围

    native 入口(dist/agent/opencode-native.js)目前只存在于 feat/pi-native-plugin(tip 2c5a6f8),其合入 master 的跟踪载体是 PR #706。因此本修复以堆叠 PR 落到 feat/pi-native-plugin(同 #875/#878/#882 折入 #850 的模式),分支 2026-09-18_opencode-native-packaging,内容:

    • package.json:显式枚举、不用 wildcard(opencode 2.x: no-launcher npm-plugin deployment — plugins: ["billion-context"], plugin lazily spawns the proxy #809 已拍板的「①A + 显式枚举 exports」,且你跑过跨仓裸子路径搜索零命中):
      "exports": { ".": "./dist/index.js", "./server": "./dist/agent/opencode-native.js" }
      封印裸 billion-context/dist/* 子路径导入不影响任何实测到的消费者(opencode-acp 1.18.1 与 billion-context-pi 均不依赖本包)。
    • files:已含 dist/,无需改动;用构建后分支的 npm pack 实证验收项 1(tarball 含 dist/agent/opencode-native.js)。
    • bili plugin install opencode:按运行中安装的自身来源判别——包根位于 node_modules 下(npm/pnpm/yarn,两种分隔符)→ 写裸包名 billion-context 进 plugin(opencode 自己的 Npm.add 装包+升级,零绝对路径);其余形态(git checkout/dev)→ 保留现有 shim 目录并在输出里明示「开发形态、不可跨机」。remove/status 同时识别两种形态;重复 install 会把旧 shim 条目迁移为裸包名。

    4. 时序依赖(验收项 2/3)

    裸包名端到端可用(加载 + 自拉起代理、配置跨机生效)要等 native 工作流进 master 并由某个 release 发布之后才成立——即 #706(或其继任者)+ 下一个 release。本 PR 保证届时无需任何额外打包改动。若你更希望我等 #706 落地后直接在 master 上做,说一声即可——但先堆叠能让 diff 小而可审,且随 #706 自动带入。


    中文摘要:独立核实了全部论断——从 2.0.7 发行二进制的内嵌 JS 中提取出入口解析函数 cm(),与你引用的 host.ts 完全一致(named spec 先试 <pkg>/server、走完整 Node 解析认 exports map,失败才回落裸包名→main→dist/index.js;你实测的宿主进程副作用正是回退链执行了 CLI 模块级 main()),0.1.118 tarball 确认无 exports、无 native 入口。修复按 #809 已拍板的显式枚举 exports 形态,以堆叠 PR 落到 feat/pi-native-plugin(package.json 加 exports {".","./server"}、安装器按来源写裸包名或 shim 并标注开发形态、remove/status 兼容两形态);验收项 2/3 待 #706 合入并发布后端到端成立,本 PR 保证届时零额外打包工作。dist/index.js 导入副作用问题同意单独跟踪——请开 issue,我接手。

  3. ranxianglei commented on Sep 18, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 已按「先堆叠」落地:PR #931 → #931 (base feat/pi-native-plugin,tip 81d647c,随 #706 进 master)

    改动(5 文件,+227/-24):

    1. package.json 显式 exports(opencode 2.x: no-launcher npm-plugin deployment — plugins: ["billion-context"], plugin lazily spawns the proxy #809 拍板的形态,无 wildcard):{ ".": "./dist/index.js", "./server": "./dist/agent/opencode-native.js" }。./server 正是 opencode 加载器最先尝试的子路径(2.0.7 二进制里提取的 cm() 已验证),一旦解析成功,裸包名→main→dist/index.js 的回退链永不触发——你实测的宿主进程监听/定时器/EADDRINUSE 三类副作用从插件加载路径上消失。. 保持根解析与今天字节等价;files 本就含 dist/。
    2. 安装器来源感知:新增 isNpmInstallForm(root)(包根在 node_modules 下 ⇒ npm 形态)+ applyOpencodePluginEntry()——npm 安装写裸包名 billion-context(并删掉遗留 shim 目录、输出迁移提示);checkout/dev 安装保留 shim 目录并在输出里写明「machine-local shim, not portable across machines」。remove/status 两种形态都识别。
    3. 测试:新增 tests/plugin-install-opencode.test.ts 8 例(来源判别表含 pnpm 嵌套/Windows 反斜杠、两形态 fresh/migrate/idempotent/跨形态替换、真实 installer 全链路 install→status→remove 的 hermetic e2e)。
    4. README EN+ZH 同步两种入口形态。

    验证结果:

    • typecheck 干净;全量 npm test 1704 pass / 0 fail(2 skip = e2e gate)
    • 本分支 build + npm pack:tarball 含 dist/agent/opencode-native.js,包内 package.json 带 exports map —— 验收项 1 达成
    • 对打包产物做了解析模拟(全新项目 npm install billion-context-*.tgz):
      • require.resolve("billion-context/server") → …/dist/agent/opencode-native.js ✓(之前 MODULE_NOT_FOUND)
      • import("billion-context/server") → default 导出 { id, setup, server },导入零副作用(无监听、无定时器)✓
      • 裸包名仍 → dist/index.js(现有消费者不受影响)✓
      • billion-context/dist/* 裸子路径 → ERR_PACKAGE_PATH_NOT_EXPORTED(按设计封印;opencode-acp / billion-context-pi 均不依赖本包,零破坏面)✓

    时序提醒:验收项 2/3(裸包名端到端加载 + 自拉起、配置跨机生效)在 #706 合入并由某次 release 发布后自动成立,届时无需任何额外打包工作。另外 dist/index.js 导入副作用那条独立话题,等你开 issue 我接手。


    中文摘要:PR #931 已开(堆叠到 feat/pi-native-plugin,同你指示)——显式 exports 暴露 ./server 插件入口、安装器按自身来源写裸包名或 shim(开发形态明示不可跨机)、8 个新测试全绿、全量 1704 测试通过、打包产物已实证含 native 入口且 billion-context/server 可解析、导入零副作用;验收项 1 达成,2/3 待 #706 合入并发布后端到端成立。

  4. added 2 commits that reference this issue on Sep 18, 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

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions