## 预期行为 用户在 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 自己的插件升级机制完全用不上。 - #922 `release v0.1.119` 只含 #731 / #895,不含 native 工作流,短期内 npm 上不会出现。 ## 建议 1. `package.json` 显式枚举 `exports`(#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
jensenojs commentedon Sep 18, 2026
补一条实测证据,比 issue 正文描述的情况更严重:
"plugins": ["billion-context"]不是「装了拿不到插件」,而是会在 opencode 服务进程里把 CLI 入口当插件模块加载并产生副作用。opencode 2.0.3 的入口解析(
packages/plugin/src/host.ts:17-43):即先试
billion-context/server,失败后 subpath""回退到裸包名billion-context→main→dist/index.js。实测(npm i billion-context@0.1.118,node 里 import 裸包名):
require.resolve("billion-context/server")→MODULE_NOT_FOUND(无exports),main=dist/index.js。所以按规范方式配置的后果是三重的:
undefined(无id/setup/server),opencode 得不到插件dist/index.js的副作用当场在宿主进程里启动代理、开 180s 周期的 auto-update 定时器也就是说包目前的形状下,规范安装路径不是「不工作」,而是「以一种有副作用的方式不工作」。
这给 issue 正文的建议加了一条优先级更高的要求:
exports缺失时不该由main兜底承接插件加载。显式枚举exports(至少"./server"指向 native 插件入口)同时解决 1/2/3——子路径存在后 opencode 不再回退到裸包名,CLI 入口也就不会被当插件导入。顺带:
dist/index.js作为main在 import 时就产生监听/定时器副作用,本身对任何把它当库导入的场景都是隐患,可以考虑把副作用收进bin或显式的start()调用之后(这条属于独立话题,若认为值得单独跟踪我另开 issue)。ranxianglei commentedon Sep 18, 2026
[bot] 🏷 全部论断已独立核实——包括在最新发行版 @opencode/cli 2.0.7 上做到二进制级的加载器契约验证。结论与你的优先级判断一致,方案见下,实现已开始。
1. 加载器契约——从 2.0.7 发行二进制里直接提取确认
2.0.7 的 npm 包是 Bun 编译的单体 ELF(bin/opencode.exe + 平台包),所以我把入口解析函数直接从内嵌 JS bundle 里抠了出来,与你引用的 host.ts 逐字一致:
即 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(tip2c5a6f8),其合入 master 的跟踪载体是 PR #706。因此本修复以堆叠 PR 落到 feat/pi-native-plugin(同 #875/#878/#882 折入 #850 的模式),分支2026-09-18_opencode-native-packaging,内容:"exports": { ".": "./dist/index.js", "./server": "./dist/agent/opencode-native.js" }封印裸
billion-context/dist/*子路径导入不影响任何实测到的消费者(opencode-acp 1.18.1 与 billion-context-pi 均不依赖本包)。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,我接手。ranxianglei commentedon Sep 18, 2026
[bot] 🏷 已按「先堆叠」落地:PR #931 → #931 (base
feat/pi-native-plugin,tip81d647c,随 #706 进 master)改动(5 文件,+227/-24):
{ ".": "./dist/index.js", "./server": "./dist/agent/opencode-native.js" }。./server正是 opencode 加载器最先尝试的子路径(2.0.7 二进制里提取的cm()已验证),一旦解析成功,裸包名→main→dist/index.js 的回退链永不触发——你实测的宿主进程监听/定时器/EADDRINUSE 三类副作用从插件加载路径上消失。.保持根解析与今天字节等价;files本就含dist/。isNpmInstallForm(root)(包根在 node_modules 下 ⇒ npm 形态)+applyOpencodePluginEntry()——npm 安装写裸包名billion-context(并删掉遗留 shim 目录、输出迁移提示);checkout/dev 安装保留 shim 目录并在输出里写明「machine-local shim, not portable across machines」。remove/status 两种形态都识别。tests/plugin-install-opencode.test.ts8 例(来源判别表含 pnpm 嵌套/Windows 反斜杠、两形态 fresh/migrate/idempotent/跨形态替换、真实 installer 全链路 install→status→remove 的 hermetic e2e)。验证结果:
npm test1704 pass / 0 fail(2 skip = e2e gate)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 合入并发布后端到端成立。feat: standard npm install path for the opencode native plugin (Refs #…
Merge pull request #931 from ranxianglei/2026-09-18_opencode-native-p…
feat: unify the dsh install lane on dsh's own plugin channel (#966)