Skip to content

opencode 2.x: no-launcher npm-plugin deployment — plugins: ["billion-context"], plugin lazily spawns the proxy #809

Closed
2 of 2 issues completed

Description

@jensenojs

Expected behavior (user side)

// opencode.jsonc — one entry, nothing else changes
"plugins": ["billion-context"],
"compaction": { "auto": false }
  • opencode installs the package through its own plugin machinery (Npm.add); plugin and proxy ship in the same package, so they are always the same version.
  • On startup the plugin probes 127.0.0.1:18787 (manifest GET + proxy: "billion-context" identity check — not bare TCP, so a foreign process on the port can't be mistaken for bili). On miss it spawns node <package root>/dist/index.js detached, loopback-bound; the path is resolved from import.meta.url at runtime. Machine-level singleton: all plugin instances across opencode servers converge on one proxy (spawn races are the norm — plugins instantiate per-location, probe logs show 6 instances in one service — and EADDRINUSE resolves them).
  • Requests are rewritten idempotently to /bili/<url> and stamped with session headers (the existing plugin behavior); the proxy stays the single compression authority.
  • No launcher, no provider config changes, no locally-copied plugin files. Dotfiles-synced configs work across machines; upgrades flow through opencode's host-managed plugin install.
  • When BILLION_CONTEXT_PROXY is set (launcher is managing), the npm-loaded instance stands down — launcher mode keeps working unchanged.

Why this is feasible (verified, not assumed)

  • Loader contract: exports["./server"] is resolved first on both generations — 2.0.3 (tag d44b52c, packages/core/src/plugin/host.ts, entry(["server", ""])) and dev (packages/opencode/src/plugin/shared.ts, resolvePackageEntrypoint).
  • Module shape: 2.0.3 requires default {id, setup|effect}; dev requires {id, server} — the existing triple export {id, setup, server} already covers both, so the local variant just inherits it.
  • Runtime probe on 2.0.3 (file-writing probe against a live service): ctx.options exists (options channel works), ctx.tool.reload() works (transform re-fires — tool registry rebuild is available), plugin file hot-reload + clean dispose work.
  • model.request fires with a mutable baseURL that reaches the wire — a second rewrite channel besides http.request, closer to the launcher's config-level baseURL rewrite.
  • I have a half-done local-mode variant on a fork branch (~27 lines: opencode-local.ts, createOpencodePlugin factory + fixed proxy base + distinct plugin id) ready to extend into a PR.

Questions for you

  1. Carrier: billion-context itself with exports["./server"] (my lean — one package, one version, oc.py-style host updates just work) vs a separate thin opencode-scoped package. Note: adding an exports map seals bare subpath imports (billion-context/dist/*), so it needs a wildcard ("./*": "./*") or explicit enumeration — a repo-level decision. opencode-acp already publishes exports["./server"], so this contract route matches your existing practice.
  2. Entry form: separate dist entry for the npm path (V2-only, statically determinable behavior, distinct id avoids tool double-registration when both launcher and npm plugins load) vs one dual-mode file. I lean separate entry; the fork branch already is one.
  3. Tool registration source: keep embedded V2_BILI_TOOLS, or re-register from the proxy manifest after spawn via ctx.tool.reload (pi's model — single source of truth at runtime; probe confirms reload works on 2.0.3). This also decides whether version-skew between plugin and proxy is benign (manifest) or needs a warning (embedded).
  4. opencode-acp coexistence: its self-disable conditions (env / /bili/ baseURL) don't trigger in plugin-local mode, so both plugins in one config would claim the same history. You maintain both projects — where should the mutual-exclusion semantics live?
  5. Auto-update: the proxy spawned from opencode's npm cache must skip the tarball self-update (it would race the host's npm install on the same directory). Env marker vs CLI flag?

Full design doc attached below (Chinese) — requirement list, verified facts with source locations, failure/degradation matrix, upgrade story, probe results, and open questions. It is a discussion artifact, not a finalized plan; everything in it is negotiable.

附录:bili 本地压缩插件设计文稿 v2(诉求清单 / 已验证事实 / 降级矩阵 / 探针结果 / 开放问题)

bili 本地压缩插件设计文稿

讨论稿,2026-09-15。v2 整合版:部署载体从"插件目录文件拷贝"升级为 npm 插件包,吸收三个新事实域——opencode 2.x 插件加载契约、opencode service 生命周期、双模式共存判别器。设计目标不变:给 opencode 2.x 挂一个本地插件,上下文压缩由 bili 接管。用户不改启动方式、不改 provider 配置。

诉求清单

从整个讨论中收拢的诉求,设计必须逐条给出交代:

  • 不改启动 opencode 的方式(不要 launcher)。
  • 不改 provider 配置(opencode.jsonc 不出现 /bili/ 字样)。
  • 代理逻辑由插件承载。
  • 用户日常零操作:插件自己拉起/维护本机 bili。
  • 部署形态是上游 npm 包:"plugins": ["billion-context"] 一行进 opencode.jsonc,由 opencode 自己的插件机制安装,由 oc.py _refresh_plugins 升级。拒绝本地拷贝文件——多机 yadm 同步难、升级难。
  • 插件与代理同版本:部署单元是"薄插件 + 代理"一体,不引入跨包版本协调缝。
  • 多机部署走 yadm:所有路径运行时从 import.meta.url 解析,不写死机器本地绝对路径。
  • opencode 插件 API 高速迭代下的健壮性:能力探测、静默退化、退化可见。
  • 会话内换 provider(kimi→gpt 之类)压缩行为良好定义。
  • 单压缩 owner:宿主 auto-compaction 和 provider 原生压缩都不与 ACP 共存。
  • 用户可调 per-provider / per-model 的压缩参数和上下文限制。
  • 可观测:压缩发生了用户能知道;插件退化了用户能知道。
  • 全链路可升级可回滚:opencode、bili、acp-kernel、插件自身四个升级通道。
  • 安全:本地绑定、日志落盘边界、会话头防伪。
  • 与 bili opencode launcher 模式共存不互相踩。

背景

billion-context(bili)是上下文压缩代理;acp-kernel 是压缩引擎,npm 精确版本锁在 devDependencies,tsup 构建时内联进 dist,零运行时依赖。bili 已有 opencode 2.x 内置插件(src/agent/opencode.ts,PR #754 合并,2.0.3 端到端验证过),但它依赖 launcher 注入的 BILLION_CONTEXT_PROXY env 或 /bili/ 形态 baseURL——两样用户都不要,所以做 local 变体。

仓库定位(多 client 视角)

billion-context 是服务多个 client 的通用压缩代理——claude code、codex、pi、omp、gemini、hermes、dsh——每个 client 一个薄插件(dist/agent/*.js),代理本体与压缩逻辑不感知具体 client。本设计不改变这个定位:opencode 只是其中一个集成面,npm 插件载体是该集成面新增的一种宿主接入方式(现有各 client 的接入方式是 launcher 或 plugin-install 写机器本地路径配置)。host-managed npm 安装(宿主自己管包的安装与升级)在 repo 是首例——owner 可能想把它当成可泛化模式(其他支持 npm 插件的宿主照抄),也可能保持 opencode 专属,issue 里表态。

opencode 2.x 插件契约(本轮核实,dev 分支源码)

以下是 npm 载体的地基,逐条给源码位置:

  1. 包入口解析(packages/opencode/src/plugin/shared.ts resolvePackageEntrypoint):优先 package.json exports["./server"](TUI 插件读 exports["./tui"]),否则回落 main(仅 server kind)。npm spec 经 parsePluginSpecifier(裸包名 = latest)+ Npm.add 装进 opencode 自己管理的 npm cache(具体目录未核实,验证项)。
  2. 插件调用(packages/opencode/src/plugin/index.ts applyPlugin):server(input, load.options)——jsonc 里 plugins 条目的 options 字段作为第二个参数传进插件函数。旧形态(导出裸函数)同样 (input, options)。
  3. 配置键(packages/core/src/config/plugin/external.ts + plugin.ts):2.x 原生键是 plugins(复数),条目 string | { package, options };支持 file:// 和相对路径 spec(相对 config 文档所在目录解析)。V1 键 plugin(单数)经 packages/core/src/v1/config/migrate.ts 迁移到 plugins——launcher 的 temp 配置注入走的就是这条迁移路。
  4. 插件可改 config——已闭合,版本依赖,2.0.3 上不可达(源码级,2.0.3 tag + dev 双向核实):2.0.3 的 V2 插件 Context 命名空间清单(packages/core/src/plugin/host.ts:options/agent/aisdk/catalog/command/event/experimental/generate/integration/mcp/permission/plugin/reference/skill/shell/tool/vcs/websearch/worktree/session)没有 config 面——config hook 属于 V1 server() 路径的 hooks 对象,而 2.0.3 选 setup 弃 server(bili 注释实测:"setup() is chosen over server()")。dev 上则经 server() 路径 config hook 可达:hook.config?.(cfg) 收到的就是共享引用(Config.get() = InstanceState.use(state, s => s.config),同一对象),compaction 读取惰性(isOverflow 每次 config.get()),时序成立。结论:宿主压缩禁用在 2.0.3 落方案 2(用户 jsonc 一行),dev/未来版本可能自动接管——三不变量第 1 条的典型退化场景。
  5. billion-context 主入口 import-unsafe:src/index.ts 模块级无条件执行 main()。对 npm 载体无碍——exports["./server"] 子路径直接指向 dist/agent/opencode.js,绕开主入口,无需加 main-guard。
  6. service 模式:opencode 2 有 opencode service start/stop/status/...(后台 server 管理)。插件(server kind)跑在 server 进程内,process.env 可读——launcher 模式的现有 V2 插件就靠 BILLION_CONTEXT_PROXY env 工作。
  7. 插件模块契约跨代翻转(2.0.3 tag d44b52c vs dev 源码级核实):2.0.3 的 packages/core/src/plugin/module.ts 用 Schema 强制 default 导出 {id, setup | effect}(多余键忽略);dev 的 readV1Plugin(detect 模式)只认 id/server/tui 键,{id, setup}-only 模块在 dev 上加载失败,走 server() 形状。即:setup 形状只在 2.0.x 活,server 形状在 1.x 和 dev 活。bili 现有导出 {id, setup, server} 三重形状是同时吃两代的生存策略,local 变体必须继承。命名警告:2.0.3 语境的"V2"指 setup 形状,dev 语境的"V1"指 server 形状——同一形状两代叫法相反,读文档必须带版本号。2.0.3 插件系统在 packages/core/src/plugin/,dev 搬到 packages/opencode/src/plugin/(oc.py 注释 404 的原因)。
  8. options 注入路径两代不同:2.0.3 合进 host input(ctx.options,module.ts effect: (host) => plugin.effect({...host, options: operation.options}));dev 是 setup/server 的第二参数。插件读两处(ctx.options ?? arguments[1])。
  9. 入口解析两代一致:2.0.3 Host.resolve 先试 <pkg>/server 子路径再回落 main(entry(["server", ""]));dev resolvePackageEntrypoint 读 exports["./server"] 优先。exports["./server"] 两代通吃。

事实修正

  • 原稿"插件进程读不到宿主 env,配置只能写死源码或走文件"不准确:V2 插件跑在 opencode server 进程内,process.env 可读。真正不可及的是 opencode 启动后才产生的内部状态;config 对象可能经 init 期 mutation seam 可及(见上条第 4 点,验证项)。
  • launcher 注入机制全貌(prepareOpencodeHttpRewrite):深拷贝用户合并配置 → 改写发现的 provider baseURL → temp opencode.json 里 append 插件条目(2.x 用 temp 目录 index.js re-export 真实插件文件,走 V1 plugin 键 + 迁移)→ 注入 compaction.auto: false → OPENCODE_CONFIG 指向 temp 文件(叠加在全局合并之上,PR fix(launcher): read opencode JSONC config (comments + merge) like opencode itself #797 已对齐这个语义)→ 设 BILLION_CONTEXT_PROXY env。
  • PR fix(launcher): read opencode JSONC config (comments + merge) like opencode itself #797(jsonc 三文件深合并 + OPENCODE_CONFIG 叠加):已开,owner 的 ework agent 完成审阅闭环(深合并修复 d50652c),等合并。

已验证的本机事实(opencode 2.0.1 实测):

  • http.request hook 触发、能就地改 URL 和 header,改动真实到达 wire。
  • tool.transform 能注册工具,execute 回调 ctx 里有 sessionID。
  • ctx.catalog.model.list() 能拿 per-model 上下文窗口。
  • ~/.config/opencode/plugins/ 自动加载,放单个 js 即生效,零配置改动;config plugin 数组条目必须目录。
  • 2.0.1 不认 XDG_CONFIG_HOME,项目级 config 会合并。
  • 2.x managed service 跨调用存活且缓存旧配置,实验前 opencode service stop。
  • service 进程的 stdout 指向 /dev/null——插件的 console.log 会被丢弃;探针必须写文件(2.0.3 service start 无 --standalone flag)。

2.0.3 探针实测(2026-09-15,文件写法绕开 /dev/null):

  • setup 单参数:2.0.3 的 V2 setup 只收一个 ctx(第二参数为 null);ctx.options 字段存在(plugins 目录发现时为空对象,数值传递需 config 条目 + e2e)。ctx 命名空间 23 个,无 config——验证项 1 的运行时确认。
  • tool.reload 生效:reload() resolve 后 transform 回调重入(call fix: address all code review findings (condense, routing, session-id, dead code) #2 出现)——注册表重建且 transform 重新应用。manifest 注册源迁移的机制打通。
  • 插件按 location 实例化:单 service 内 50ms 里 setup 跑了 6 次(6 个 location 各一份实例)——spawn 竞态不是尾部场景而是每次冷启动的常态,EADDRINUSE 兜底是主路径;工具注册也按 location 隔离。
  • 插件文件热重载生效:watcher 监听插件文件,改动即重新加载并重跑 setup;删除文件触发 dispose(6 个实例全部干净卸载)。
  • (昨日遗留探针日志,/tmp/bili-probe.log)2.0.3 V2 hook 面远比 bili 当前使用的丰富:prompt / context(含 system+messages+tools 数组)/ title / model.request(baseURL 可变,变更真实到达 wire,失败后有 retry hook)/ http.request / http.response 全部触发。model.request 的可变 baseURL 是 http.request URL 改写之外的第二条改写通道(更像 launcher 的 config baseURL 改写的请求期版本)。

架构

下图是 opencode 集成面的形状;repo 整体形态不变(通用代理 + 每 client 一个薄插件)。

opencode 2.x(照常启动;service 模式或直跑)
└── opencode.jsonc: "plugins": [{ "package": "billion-context",
                                  "options": { "port": 18787, ... } }]   # 一行
    └── opencode 加载器: Npm.add("billion-context") → opencode npm cache
        → import exports["./server"] → dist/agent/opencode.js(单文件双模式)
        ├── env 判别: BILLION_CONTEXT_PROXY 在 → launcher 模式(现状行为,零改动)
        └── 缺失 → local 模式:
            ├── proxyBase = options.port || http://127.0.0.1:18787
            ├── http.request hook
            │   ├── 改写 URL → /bili/<原请求完整URL>(幂等)
            │   └── 盖章 x-bili-plugin / -conversation / -context-window
            ├── tool.transform → compress / decompress / search_context /
            │   acp_status / absorb → POST /__bili/plugin/tool
            └── 启动期:health 探测 → 失败则 spawn
                node <包根>/dist/index.js(detached,显式 loopback 绑定)
                包根从 import.meta.url 运行时解析;spawned 模式禁 bili 自更新

本机 bili(跑在 opencode npm cache 内;oc.py _refresh_plugins 升级)
└── acp-kernel 压缩引擎(内联)+ loop/ 三个 wire adapter
    └── 会话状态 ~/.local/share/billion-context/sessions/(与安装位置无关)

链路:用户消息 → opencode 组装 → http.request hook(改写+盖章)→ bili(会话识别 → adapter → kernel 管线 → 转发真实 upstream)→ 响应回流。模型调 compress → 插件 execute(ctx.sessionID) → POST /__bili/plugin/tool → 结果回 agent 自己的历史(plugin mode)。

端口 18787(8787 被 codex-mixin 占)。实现前确认空闲。

代理生命周期与 opencode service

机器级单例,与 opencode service 生命周期解耦。理由链(经评审纠错修正:bili 本身支持多实例——instance.ts:221 是 per-instance liveness registry(#394/#527),persist.ts 明写多实例共享 BILI_SESSION_DIR,"单例假设"的旧论据不成立;真正支撑单例结论的是下面三条):

  • 升级通道唯一性:oc.py 只刷一份 npm cache,插件与代理同包——若每个 opencode server 各 spawn 一份,多份代理读同一 cache 目录会产生版本混布,收敛语义破碎。
  • 固定端口:所有 server 的插件实例写死(或经 options 统一)同一个 127.0.0.1:18787,天然汇流。
  • 跨进程会话连续:会话生命周期横跨多个 opencode 进程(TUI 重启、service 重启)——代理绑死某个 service,opencode service stop 会腰斩其他 server 正在进行的会话压缩状态。
  • opencode 的 service API 没有第三方进程注册面——service.json 只是连接密码,没法把 bili 注册成 opencode 托管的服务。
  • 多 server 语义因此收敛为:所有 server 的插件实例汇流同一个 127.0.0.1:18787。幂等改写保证共存无害;spawn 竞态是常态而非兜底——探针实证单 service 内插件按 location 实例化(50ms 内 6 个实例),每次冷启动必有 N 个实例同时探测-失败-spawn,后到者由 bili 的 EADDRINUSE 退出收敛;跨实例版本偏斜由握手处理(见升级节)。
  • opencode 1 的问题不存在:V1 没有 http.request/tool.transform seam,local 插件天然 inert;V1 官方路径是 opencode-acp/launcher,互不干涉。
  • 已知不对称(记录,不解决):opencode service stop 不停 bili。detached 进程常驻是设计选择,与 bili"跑几天"的定位一致;杀开关独立存在(见配置面)。

部署载体与命名

三选项,留给 owner 裁决(见上游化路径节):

  • A. billion-context 本体当插件包(倾向):exports["./server"] 指向 dist/agent/opencode.js,插件与代理同包同版本,spawn 路径从包根解析。仓库已有 pi/omp 薄插件内嵌先例。事实补充(评审后):当前 package.json 没有 exports 字段——import-unsafe 是现状(main=dist/index.js 模块级跑 CLI),加 exports 反而是修复面;opencode-acp 已发布 exports["./server"](同 owner 项目),是现成先例,说明这条契约路线与 owner 的既有实践一致。代价有三层:
    • opencode 的插件 cache 里装进完整 CLI 代理;
    • billion-context 这个名字在 opencode 插件列表里语义不显;
    • package.json 加 exports map 会封印子路径导入——一旦 exports 存在,外部对 billion-context/dist/* 的裸导入全部失效。对一个被多种方式消费的通用包(MCP spawn 走命令行不受影响,但外部 import、文档示例、潜在下游都受影响),exports 面是仓库级决策:需要 wildcard("./*": "./*")保住旧导入路径,或显式枚举允许的子路径。这层必须在 issue 里摆给 owner,不能当 opencode 的局部便利提案。
  • B. opencode-acp 转向薄客户端壳:opencode-acp 今天是进程内 V1 引擎(与 bili 零依赖),转向为依赖 billion-context 的壳是产品架构更换。跨包版本缝 + 劫持活产品名,是 owner 的决策,不由 PR 替他做。
  • C. 新发薄包(如 billion-context-opencode):依赖 pin billion-context,manifest 协议天然容忍版本漂移。多一个包要养。

版本漂移三不变量

对"oc1/oc2 复杂度进入插件"的结构性回答。复杂度是搬家不是增殖:兼容矩阵的 owner(同包发布的 bili)没变,变的只是接缝数与运行位置。三条不变量守住,版本差异就只是降级矩阵的一行:

  1. inert 地板:所有 opencode 版本敏感接缝(http.request / config hook / tool.reload / options / session hooks)都有定义好的退化路径,地板是"直连不压缩"。任何无 fallback 的新接缝不得进 delta。
  2. 唯一承重契约:对 opencode 的硬依赖只有包入口解析(exports["./server"])——唯一无 fallback 的一项,也是整条链上最稳的一环(核心加载机制,非实验接缝)。它断裂属生态级事件(所有 npm 插件一起死),检测靠 opencode 的插件列表可见性,插件内无缓解手段。
  3. 插件内禁版本探测:插件一旦出现 if (opencodeMajor >= X) 分支,它就成了跑在宿主进程内的第二个 launcher。版本编排属于 launcher 通道;插件通道只瞄准当前 V2 契约,churn 用退化吸收,不用探测吸收。oc1 兼容(dual-shape 导出)留在 launcher 通道的文件里,npm 入口 V2-only(待决策项 1 独立入口的第三条理由)。

作者已在 2.x 内实测到接缝面差异(agent/opencode.ts:160-165:"reload-based refresh is not available on all observed surfaces"),其对策——全文 optional-chaining + inert-safe——就是本设计继承的既有模式。更强实证(源码级):插件模块契约本身跨代翻转——2.0.3 强制 {id, setup},dev 只认 {id, server}(背景契约第 7 条)——连"导出什么形状"这个最基础的契约都在 2.0.3 与 dev 之间翻转了。作者的生存策略是三重导出 {id, setup, server} 全形状同时在场;local 变体必须继承这个策略。这是三不变量的现实压力测试:宿主 API churn 不是尾部风险,是已经发生过的中位数事件。

版本漂移的真实伤害形态按风险排序:退化不可见(接缝 churn → 静默 inert → 用户以为在压缩实际裸跑;可观测性一节的缺口即此处)> 冒烟矩阵持续税(按接缝数比例增加)> 生态级断裂(无插件内缓解)。

与现有 V2 插件的 delta

local 模式是 src/agent/opencode.ts 的增量变体,不是重写:

  1. proxyBase 解析链改为:BILLION_CONTEXT_PROXY env(launcher 在管时整个插件实例退让)→ local 模式下 options.port → 默认 http://127.0.0.1:18787;启动探测、缺失自启(替代 env/URL 推导)。
  2. 主动 URL 改写为 /bili/<原URL> 形态(现有插件只盖章不改写;这是核心新行为),且必须幂等——请求已是 /bili/ 形态时不得重复加前缀。
  3. kill switch 通道待决策:options.enabled: false(jsonc,yadm 同步,干净)vs 文件制(原稿方案,但���件目录在 npm cache 里会被升级冲掉——若走文件必须放 ~/.config/billion-context/ 等稳定用户目录)。见配置面。
  4. 出站 body 检测到 context_management 时 stderr 告警。
  5. 与 bili 的握手/版本语义待裁决(开放问题 1):握手按 protocolVersion 判(需先补 agent 侧校验);版本差的处理随注册源选择分支——注册源迁移到 manifest 则纯信息性,保持内嵌则告警有真实价值。原稿的"自重启 bili"在两种分支下都不成立(npm cache 场景重启的还是 oc.py 管着的那份码),已否决。见升级与兼容。
  6. 注册源迁移候选(评审新增,见 manifest 契约节):内嵌 V2_BILI_TOOLS 同步注册(现状)→ spawn 后经 ctx.tool.reload 换成 manifest 下发集。探针已确认 tool.reload 生效(transform 重入机制可用)——迁移可行,把 opencode 插件与 pi 共享"单一事实源"模型,漂移防护从构建期纪律升级为运行时机制。

bili 契约与会话身份

插件依赖的 bili HTTP 接口(shared.ts 在用、server 侧已实现):POST /__bili/plugin/tool({conversationId, tool, args} → {ok, result, error});GET /__bili/plugin/status?conversationId=。宽松契约:不匹配就禁用工具注册并警告,不硬撑。

manifest 契约的实际粒度(已读 plugin.ts:372 / agent/shared.ts:88 / agent/opencode.ts 核实,并经独立评审纠错)

GET /__bili/plugin/manifest 返回:protocolVersion: 1、version(proxy 版本串)、proxy: "billion-context"(身份标识)、toolNames、tools.anthropic/openai/responses(每工具完整 input_schema,按 wire 格式分列)、headers(盖章头名)、toolEndpoint/statusEndpoint。修正后的结论:

  • opencode 插件不消费 manifest,工具注册是内嵌的(评审纠错,已复核:agent/opencode.ts:212 V2_BILI_TOOLS 由 ACP_TOOLS_OPENAI + ABSORB_TOOL_OPENAI 构建进 bundle,注释 160-165 行给出理由——同步注册可用、tool.reload 在部分观测面上不可用)。消费 manifest 的是 pi(agent/pi.ts:206)。所以"schema 漂移构造上不可能"只对 pi 成立;opencode 插件与代理的一致性靠构建期纪律(注释明写 parity with src/compress-tool.ts),运行时无校验。
  • protocolVersion 当前无消费者校验:agent 侧无人 fetch 后比对(opencode 插件根本不 fetch)。协议门控是它该承担的职责(见验证项 20)。
  • 版本串(version)纯信息性:fetchProxyVersion 供状态 UI 展示,不参与任何门控。
  • 注册源迁移是 delta 改动项,且接缝在 2.0.3 上已声明存在:Host.resolve 后的 Context tool: { transform, reload, hook }(2.0.3 core/src/plugin/host.ts)——local 变体可选"先内嵌同步注册、spawn 后经 ctx.tool.reload 换成 manifest 下发集"(运行时真实生效待探针,验证项 21;作者注释警告过部分观测面不可用),把 opencode 插件拉进和 pi 相同的"单一事实源"模型。

会话身份(session-id.ts):优先级链 x-bili-plugin-conversation(仅 x-bili-plugin 伴随时认)> x-claude-code-session-id > x-session-affinity > x-acp-session > x-session-id > x-opencode-session > session-id > session_id;无身份请求直接 400(内容指纹兜底因碰撞风险移除)。插件用 e.sessionID 盖章,同一会话换 provider 此 id 不变,bili 会话连续。

跨 provider 切换

kernel 消息身份是内容哈希(raw id),不是 wire 位置。同一段历史走 chat/completions 或 responses,哈希到同一 raw id,mNNNNN 不变,decompress 照常。wire 解析、重渲染、窗口、阈值全部 per-request 按当前模型算。所以"ACP 独占 + 会话头稳定"下,kimi→gpt 中途切换是良好定义的常规场景。

窗口突变同理:换到小窗模型的下一个请求立即按新窗口评估压缩水位,已 fold 的块不动。不良好定义的情况全是会话进过第二个 owner:宿主压缩的切口是整会话永久的;原生 compaction 密文绑死 OpenAI API,切换时只能被丢。

per-provider 上下文限制处理

这是本设计要显式接住的一层,bili 已有大部分机制,插件要做的就是不要破坏它。

窗口有四个来源,实测代码核实(weak-overflow.ts resolvedWindow、plugin.ts:85、compress-settings.ts):

  1. models.dev registry 快照(src/registry-snapshot.json,离线地板)。
  2. 用户配置 ~/.config/billion-context/billion-context.json 的 compress 段,global → provider → model 三级按字段 deepest-wins 合并,嵌套对象(prompts / absorb / reasoning)子字段级合并。这是 per-provider/per-model 压缩参数(阈值、headroom、prompts)的用户可调面。
  3. 插件从 opencode catalog 盖的 x-bili-plugin-context-window 头(注册路由表时消费)。
  4. 从真实 400 学到的 confirmed/learned 上限,与 effective 取 min,带 stale 检测和收回(retractStaleLearnedLimits)。

已知张力:opencode catalog 与 models.dev registry 可能给出不同窗口,谁赢未实测——第四象限(catalog 头 vs registry)的优先级是验证项。压缩触发(nudge 评估)发生在每请求,用当时生效的窗口;side request(title/summarize)共享主会话 key,走 sidePassthrough,有独立 guard(sideRequestGuard)防整历史重放打爆上游。

参数面:对照 opencode-acp

opencode-acp(v1-only 扩展)的配置参考手册约 60 个参数,值得当 checklist 逐项过。归宿分三类:

已由 bili 配置覆盖,插件不需要重复暴露。 触发与阈值族(maxContextLimit、emergencyThresholdPercent、nudgeFrequency、minNudgeContextPercent、nudgeGrowthTokens、minNudgeGrowthRatio/Floor、nudgeForce、summaryBuffer)对应 bili compress 段的阈值/headroom;per-provider/per-model 级联覆盖(compress.providers,模型 > provider > 全局逐字段)对应 bili 的 global→provider→model deepest-wins;experimental.customPrompts 对应 bili prompts 三级合并;protectedTools、maxSummaryLengthHard、minCompressRange、maxVisibleSegments、preserveRecent* 在 bili compress 配置中各有对应字段,但逐项映射未核对(验证项)。

插件层值得暴露的(opencode-facing UX,走 options 通道): enabled(jsonc 一行,替代 disabled 文件);compress.permission(ask/allow/deny——V2 tool editor 的 add() 自带 permission 选项,直接可用);compress.showCompression(聊天 UI 压缩状态指示,正好补可观测性一节标出的 inert 可见性缺口);pruneNotification(内容被剪时通知用户);commands.enabled / commands.protectedTools(/acp 类命令面开关);allowSubAgents(子 agent 会话是否接管压缩);debug / logLevel / port / minBiliVersion。

bili 侧值得吸收的设计(feature gap,不是插件参数): contextLimitFallback(窗口未知时回退绝对值 128k)——bili 目前窗口解析为 0 后的行为未核实,建议 billion-context.json 加同名参数;protectTags(<protect> 块豁免压缩)——kernel 级能力,bili 没有;qualityGate(摘要质量门,ROUGE 召回不达标重生成)——bili 没有;gc.* 代际清理参数族——bili 有 orphan-gc 但可调面不同;messageFilters(OMO 类注入过滤)——opencode 场景特化的 wire 卫生,可做插件侧可选 filter;三层配置文件(全局 → 配置目录 → 项目层)——bili 配置目前单层,项目层对按项目调压缩有用,值得加。

单 owner 规则

一个会话只能有一个压缩 owner,每个机制只认自己的占位符。

  • 宿主 auto-compaction:触发时旧消息被宿主摘要替换,bili 的 tag/acp_summary/ref 从线上消失,kernel 编号悬空。launcher 靠临时 config 写 compaction.auto: false;local 插件没有临时 config,候选方案按优先级重排:
    1. 插件 config hook 直接改——已闭合:2.0.3 不可达(V2 Context 无 config 面,背景契约第 4 条);dev/未来版本经 V1 路径可达且机制成立(共享引用+惰性读取)。留作该面出现时自动启用的增强,不作为 2.0.3 的依赖。注:本插件 V1 路径确实在用 config hook(agent/opencode.ts:91-97 注入 /acp command),但 2.0.3 选 setup 弃 server,V1 路径不执行。
    2. 用户全局 config 加一行 compaction.auto: false(yadm 同步)——2.0.3 的既定答案,launcher 模式注入的同款键。
    3. 维持现状退化兜底:宿主压缩后插件经 session.compaction.ended 上报边界,bili 归档自己的块(现有 V2 插件已有此退化路径;reportCompactionBoundary 已实现)。
  • 第三方压缩插件同装(评审新增,本用户场景真实存在——workspace 里就有 opencode-acp):opencode-acp 的自禁用三条件(自身 enabled 开关 / BILLION_CONTEXT_PROXY env / provider baseURL 含 /bili/)在 local 模式下全部不触发——URL 改写只发生在 http.request hook,config 文档不动。yadm 同步的 jsonc 完全可能同时列出两个插件,两个压缩 owner 会同时抢同一段历史,各自把对方的占位符当作未知内容处理。这是单 owner 规则的第三个对手维度,处置方案未决(见开放问题 7)。候选通道及其自伤面:让 local 插件在进程内写 process.env.BILLION_CONTEXT_PROXY 骗 opencode-acp 自禁——但该 env 同时是本插件自己的 launcher 判别器(见共存节),写它会让共存语义误判。
  • provider 原生 in-band compaction:产物加密块,bili 读不了解不了归档不了。插件绝不配 contextManagement;用户手工配的靠 http.request body 检测告警。body 在 hook 事件里是否可读是验证项。残余缺口:bili 对 OpenAI context_management 请求字段当前零处理——透传不告警是独立上游 issue(见上游化路径)。

失败与降级矩阵

场景 检测 行为 用户可见性
opencode 插件安装失败 Npm.add 报错 插件不存在,直连 provider opencode 启动日志
bili spawn 失败 探测端口不通 插件停用,直连 provider 启动日志一行
bili 运行中死掉 请求 502/拒连 请求失败(响亮) opencode 报错
握手协议不兼容 manifest 协议版本 禁工具注册 + 告警(待裁决,开放问题 1) acp_status / 日志
版本不相等(隔代共事窗口) manifest version 随注册源分支:manifest 注册→纯信息性;内嵌注册→告警(待裁决,开放问题 1) acp_status / 日志
bili 自更新与 oc.py 竞争写 cache update.ts 目标目录 spawned 模式禁自更新(待定机制,见升级节) bili 日志
opencode API churn 接缝缺失 静默退纯代理 见可观测性
e.sessionID 缺失 盖章跳过 bili 400 拒请求 opencode 报错
catalog 不可用 list() 抛错 窗口头不盖,用 registry 无(默认行为)
用户配原生压缩 body 检测 告警,不拦截 stderr
宿主压缩漏禁 compaction.ended 上报边界,归档 bili 日志
第三方压缩插件同装(如 opencode-acp) 启动期配置扫描 处置未决(开放问题 7,双 owner 抢同一段历史) 待定

原稿"bili 未安装"一行在 npm 载体下消解:opencode 装包即装代理,装失败就是第一行。

升级与兼容

acp-kernel 是构建期内联依赖:kernel 升级必须先发 kernel 包、npm 上验证、bili 再升版本发布(仓库 AGENTS.md 已有此跨仓规矩)。kernel 升级永远以 bili 发布为载体,插件不直接感知 kernel。

npm 载体下的升级通道重排:

  • 插件与代理:同一个包,同一次 Npm.add。版本一致性是 repo"一个版本一个事实"哲学(所有 client 插件和代理打进同一个 dist)的免费副产品,不是为 opencode 特设的机制——oc.py 刷的是整个包,其他集成面(claude code 等)用的也是同一份新码。升级唯一入口是 oc.py _refresh_plugins(npm spec 升级)→ 重启 opencode → 新插件 spawn 新代理。自重启 bili 已否决:npm cache 场景重启的还是 oc.py 管着的那份码,版本收敛属于升级流程不属于运行时;握手与版本差的完整语义待裁决(开放问题 1,随注册源选择分支)。
  • bili 自更新(update.ts tarball 覆盖安装目录)在 npm cache 场景下是危险项:每 180s 检查会和 oc.py 的 npm install 竞争写同一目录。plugin-spawned 模式必须禁用——机制待决策(候选:spawn 时设 env 标记如 BILLION_CONTEXT_SPAWNED=1,update.ts 见到即跳过;或 spawn 传 CLI flag)。全局手动 bili 的自更新行为保持不变。
  • 回滚:jsonc 里 plugin spec 从裸包名换成 pin 版本(billion-context@0.1.113)即回滚,oc.py 尊重 spec。原稿的 .bak 文件回滚链随之消解。
  • bili 版本 pin 与 auto-update 对抗(全局安装场景保留):ACP_AUTO_UPDATE=0 + npm install -g billion-context@<exact>;插件 options 允许声明 minBiliVersion。
  • 持久化兼容:会话状态在 ~/.local/share/billion-context/sessions/(kernel StateStore),重启后 reload,消息 id 永不复用是跨版本不变量。持久化格式跨版本兼容/迁移行为未核实,是验证项——旧会话在新版本下首次加载要么正常要么明确报错,不允许静默损坏。
  • opencode 升级:冒烟矩阵(下)。dev 分支与 2.0.3 的插件契约差异(exports 键、plugins 键名)本身是验证项。

安全与隐私

bili 默认绑 loopback,非 loopback 要显式 --host 且带 Origin 校验;插件 spawn 时显式 loopback。会话头防伪已有:conversation 头只在 plugin marker 伴随时认(session-id.ts)。落盘边界用户须知:~/.local/state/billion-context/bili.log tee 日志(URL 有 masking),完整请求体 dump 默认关(ACP_DUMP_BODY),会话持久化目录含完整上下文明文。npm cache 内运行不改变任何落盘位置(全部 XDG 解析,与安装位置无关)。

可观测性

压缩本身在 plugin mode 下可见(工具调用留在历史里)。状态面:acp_status 工具、bili web UI(localhost:18787)、bili.log。待加强的点:插件 inert 时(接缝缺失)用户怎么一眼看到——现有 V2 插件靠 /acp render 报状态,TUI 里要 Tab+Enter,run 模式根本没有 slash 分发。local 版至少保证 stderr 激活日志 + acp_status 注册失败时的降级说明;更好的信号(比如注册一个永远存在的 status 工具)待实现期定。

配置面

  • 插件侧(新通道):jsonc plugins 条目的 options 字段,作为第二参数进插件函数。候选暴露集见参数面节。kill switch = options.enabled: false(jsonc + yadm,最干净)或稳定用户目录文件(~/.config/billion-context/disabled),待决策项 4。
  • bili 侧:~/.config/billion-context/billion-context.json 三级压缩配置(不变)。
  • opencode 侧:2.0.3 上是一行 compaction.auto: false(源码级闭合:插件无 config 面,见背景契约第 4 条);dev/未来版本探测到 config hook 面后可归零——插件降级到"有该面就自动接管"的增强逻辑,不硬依赖。

插件第一版的最小暴露集:enabled + 工具 permission(默认 allow)+ port + stderr 激活日志。showCompression、pruneNotification、allowSubAgents 等第二版按可观测性一节的缺口优先级补;插件不重复实现 bili 已有的阈值族参数,只透传。

与 launcher 模式共存

用户同时跑 bili opencode 时,launcher 注入的插件和 npm 加载的 local 插件会同时加载(跑在同一个 opencode 进程里)。判别器是 env:launcher 启动 opencode 时设了 BILLION_CONTEXT_PROXY,两个插件实例都看得见。规则:

  • env 存在 → launcher 在管。npm 实例停用自己的工具注册和改写(或至少停工具注册——幂等改写保证请求层双写无害,但工具双注册有真冲突风险)。launcher 实例照常工作。
  • env 缺失 → local 模式接管。

这比原稿"从请求 URL 形态反推谁在管"可靠(URL 反推要等第一个请求才知道,工具注册在启动期就要决策)。剩余验证项:launcher 实例和 npm 实例的加载顺序、resolvePluginId 对同 id 插件的去重行为(独立入口变体天然错开 id,见待决策项 1 的分支事实)。另注意 launcher 注入走 V1 plugin 键(经迁移),用户 jsonc 走 2.x plugins 键——两条路并存,不互相覆盖;launcher temp 与用户 plugins 同时列出同包名时的去重语义未验证。

env 撞语义警告(评审发现):BILLION_CONTEXT_PROXY 在本设计里已承担两个职责——launcher 模式判别器、opencode-acp 自禁用信号(launcher 注释明写这个意图)。若 local 插件未来想借它让第三方插件自禁(开放问题 7 通道 a),会反过来污染自己的 launcher 判别器。这个 env 是共享命名空间,新增语义前必须先解耦。

测试策略

  • 单元:URL 改写(query、特殊字符、https upstream)、/bili/ 形态解析与幂等、options 解析(默认值/非法值)、env 判别分支。
  • 集成:capture-server 套件(本次调研探针固化),断言改写、盖章、工具注册。
  • e2e:仿 tests/e2e/e2e-codex.test.ts 模式,真 opencode + 真 bili + 本地 capture upstream:压缩真发生、decompress 拉回、kimi→gpt 切换、重启 bili 状态恢复、原生压缩告警、双插件共存、spawn from package root(临时目录模拟 npm cache 布局)。
  • 冒烟矩阵:每次 opencode 跨 minor 跑接缝面 + 改写 + 工具 + spawn + 切换用例。

实现期待验证清单

  1. config hook 改 compaction.auto: false 源码级闭合:2.0.3 V2 Context 无 config 面(不可达);dev 经 V1 路径可达且共享引用+惰性读取成立。方案落定见单 owner 节。
  2. options 第二参数在 2.0.3 传入 闭合(源码 + 探针):2.0.3 注入 ctx.options(探针实证字段存在),setup 第二参数为 null;dev 用第二参数——插件读两处。
  3. exports["./server"] 在 2.0.3 生效 源码级闭合:2.0.3 Host.resolve 先试 <pkg>/server 子路径再回落 main,与 dev 的 exports["./server"] 优先语义一致。
  4. Npm.add 的 cache 目录位置与生命周期(opencode 跨版本/多实例是否共享同一份 billion-context)。
  5. e.sessionID 在 http.request 事件的稳定性与覆盖面。
  6. hook 事件是否暴露请求 body(原生压缩检测)。
  7. compaction hook 能否拦截宿主压缩 失去必要性(决策项 3 已闭合走方案 2;保留为 dev 接缝面变化时的复检项)。
  8. kimi→gpt 切换后 <acp> 标签在工具历史格式转换中幸存。
  9. /bili/ 改写对 query / https upstream 的正确性。
  10. bili 中途死掉的确切行为与是否加健康检查降级。
  11. catalog 头 vs registry vs learned 窗口冲突时谁赢。
  12. 持久化状态跨 bili 版本 reload(升级后旧会话)。
  13. launcher + npm 双插件共存:加载顺序、工具去重、独立 id 错开。per-directory scope 已实证(探针:单 service 6 个 location 实例);剩余:同包名在 global + project 两份 config 文档同时列出(不同 options)的去重语义。
  14. 未知窗口模型(window=0)的实际行为。
  15. catalog 不可用时窗口头缺失对压缩触发的影响。
  16. opencode-acp compress 参数族与 bili compress 配置的逐项映射(参数面第一类归宿的核对)。
  17. update.ts 禁用机制的最小改动点(env vs CLI flag)。
  18. spawned bili 的 stderr/日志在 opencode 侧可见性(spawn 用什么 stdio 策略)。
  19. opencode 插件加载失败(setup 期 throw)在宿主的可见性——源码级半闭合:2.0.3 LoadError 与 dev logError("failed to load plugin") + Effect.catch(void) 均为日志行+静默继续(dev 有 TODO 接 Session.Event.Error)。fail-loud 的用户面可见性弱,开放问题 6 的前提被削弱;运行时确认日志行的实际位置(stderr/opencode log 文件)并入探针 A。
  20. manifest.protocolVersion 当前无任何消费者校验(opencode 插件根本不 fetch manifest,pi 走 fetchManifest 但只读 tools.*)——协议门控需要补 agent 侧校验,这是插件 PR 内的既定改动项(开放问题 1 的提案依赖它)。
  21. ctx.tool.reload 运行时生效 闭合(探针实证):2.0.3 上 reload() resolve 后 transform 重入,注册表重建机制可用;作者"not available on all observed surfaces"的警告对 2.0.3 主路径不成立。

2.0.3 探针实验设计(运行时确认)

源码级分析已闭合验证项 1/2/3,剩余需要跑真 opencode 的只有三件事。共用一个探针文件、一次启动:

载体:~/.config/opencode/plugins/bili-probe.js(单文件,走 plugins 目录自动发现;yadm 注意——实验后删除)。探针必须 inert:无 URL 改写、不 spawn、不碰 provider,产出全部走 console.log。

探针 A(Options 与 Context 面确认):export default { id: "bili-probe", setup: async (ctx, maybeOptions) => { console.log("[bili-probe] ctx keys:", Object.keys(ctx).join(",")); console.log("[bili-probe] ctx.options:", JSON.stringify(ctx?.options)); console.log("[bili-probe] 2nd arg:", JSON.stringify(maybeOptions)); } }。jsonc 里临时以 { "package": "bili-probe", ... } 不可行(非 npm 包)——探针走 plugins 目录,options 为空是预期;本探针只确认 Context 面清单与 ctx.options 字段存在性,options 数值传递留给 e2e(装真包时)。判读:ctx keys 无 config → 验证项 1 闭合的运行时确认;加载失败日志行的落点顺带观测。

探针 B(tool.reload 运行时生效):setup 内经 ctx.tool.transform 注册占位工具(description="v1"),延迟 2 秒后再注册同名工具 description="v2" 并调 ctx.tool.reload?.()(optional-chaining + log reload 是否为 function);观测通道:TUI 工具面板或 opencode debug 的工具清单看 description 是 v1 还是 v2。判读:v2 可见 → 注册源迁移分支成立(开放问题 1 的 manifest reload 路径打通);v1 或工具消失 → reload 在该面不可用,走"内嵌+版本告警"分支。

安全边界与停止条件:实验前 opencode service stop(service 缓存旧配置的既有警告);探针写盘仅限 console;最多两轮迭代(探针拿不到观测就改观测通道,不改探针逻辑超过两次);结束即删探针文件并重启 service。

预注册判读矩阵(已执行,2026-09-15):

观测 结果
ctx keys 无 config、ctx.options 存在 ✅ 命中——23 命名空间无 config;ctx.options 空对象存在;第二参数 null
reload 生效(v2 可见) ✅ 命中——reload() resolved + transform call #2 重入
加载失败日志行可见性 未测(探针未注入失败;日志行位置已有源码结论)
额外收获 插件按 location 实例化(6 实例);插件文件热重载 + dispose 卸载干净

执行备注(复用此法须知):service stdout 在 /dev/null,探针必须写文件;service start 无 --standalone flag;改插件文件即热重载,无需重启 service;昨日前 agent 的探针遗留日志(/tmp/bili-probe.log)贡献了 hook 面全量数据。探针文件已删除、环境已还原。

开放问题(未决张力)

本轮讨论识别的七处真实张力,均未决;每条给对立面和它阻塞什么。讨论收敛后回填待决策项并逐条消解。

  1. 握手语义混淆:现设计(delta 第 5 条、降级矩阵第 4 行)把"协议不兼容"(manifest 握手失败 → 禁工具+警告,宽松契约)和"版本不相等"(插件 0.1.114 配代理 0.1.113)混为一谈。事实已钉死(见 manifest 契约节):opencode 插件工具注册是内嵌的,不消费 manifest——所以漂移防护当前不存在。条件式的技术前提已判(探针确认 tool.reload 生效):注册源迁移分支可行——若采用,握手按 protocolVersion 判(先补 agent 侧校验,验证项 20)+ 版本差纯信息性;若保持内嵌,则版本差告警有真实价值。最终裁决留 issue(owner 拍板注册源与握手语义),技术两侧都成立。"隔代共事"窗口(oc.py 升级 cache 后 detached 旧 bili 存活、新插件连旧 bili 干活到下次重启)定性为升级流程常态。
  2. bili 死后自愈 vs 响亮失败:矩阵现写"请求失败(响亮)"。备选是失败请求触发 lazy 重探测+respawn、后续请求自愈、用户可能无感。取舍:便利 vs 案发现场保护——panic loop 会被 respawn 循环掩盖,故障暴露距离拉长,与 let-it-crash 原则正面冲突。折中候选:respawn 限速(如一次会话最多一次)+ 死因日志必留。
  3. health 探测的身份验证:裸 TCP 探活分不清"bili 没跑"和"18787 被无关进程占了"。后者会把请求改写给陌生进程,产生不可预测失败。机制已存在(见 manifest 契约节):探测 = GET manifest + 验应答 proxy: "billion-context" 身份字段(fetchProxyVersion 就是这个探针的现成实现,补一个 proxy 字段断言即可)。探测实现直接复用它,固定端口决策的安全性前提成立。剩余讨论点收敛为:探测时机(仅启动期 vs 每次失败请求后重探)。
  4. kill switch 的两个使用场景:options.enabled: false(jsonc/yadm)适合"我不想用了"的持久决定,但要改配置+重启;文件制适合"bili 在发疯,三十秒内给我停"(touch 生效,若插件每请求查文件存在性)。两个场景都真实存在,也许都要——但那是两个状态源,与最小复杂度打架。
  5. 单文件双模式是 repo 结构异类:其他 agent 插件都是"一种宿主接入方式一个文件",opencode.js 若同时服务 launcher 注入(env 在)和 npm 加载(env 不在),行为判据藏在运行时 env 里——排查"为什么 spawn 了/为什么没 spawn"要翻环境变量。独立入口让行为静态可判,代价是 exports 指向与 launcher 注入路径联动改。异类性及其理由要在 issue 里向 owner 摆开。
  6. options 校验的失败哲学:options.port 给了 "18787x" 或负数:启动期 fail-loud(插件加载 throw)还是 fallback 默认值+stderr 告警。fail-loud 符合故障暴露原则,但前提是"插件加载失败在 opencode 宿主里可见"先被验证(见验证项 19)——若加载失败静默退化成直连,fail-loud 反而制造最坏的静默。
  7. 第三方压缩插件同装的处置(评审新增,本用户真实场景):opencode-acp 自禁用条件在 local 模式全不触发,同装即双 owner 抢同一段历史(见单 owner 节)。候选通道:(a) 进程内写 BILLION_CONTEXT_PROXY 骗其自禁——自伤:该 env 是本插件自己的 launcher 判别器,共存节语义会被误判;(b) 检测到其安装时启动告警 + 文档声明互斥;(c) URL 改写发生后再禁它(太晚,它已经上过手)。未见干净通道,issue 里值得问 owner(他同时维护两个项目,互斥语义应由他定)。

待决策项

原稿部分项在 npm 载体下消解,标注如下;新决策按依赖关系排序:

  1. 插件入口形态:仓库内单文件双模式(src/agent/opencode.ts 扩展,env 判别)vs 独立 dist 入口(dist/agent/opencode-local.js,exports 指向它)。注意分支事实(经评审纠错):opencode-plugin-local-mode 分支上已复原的 27 行是独立入口变体(opencode-local.ts + createOpencodePlugin 工厂 + 独立插件 id + 模块旁 disabled 文件——后者正是会被 npm cache 升级冲掉的 kill switch 方案,见开放问题 4),它不是单文件双模式的演示,而是独立入口方向的半成品。倾向后者(独立入口):行为静态可判(开放问题 5)、独立 id 天然错开双插件冲突、分支工作直接延续、V2-only 入口不背 oc1 复杂度(版本漂移三不变量第 3 条)。issue 里让 owner 表态。
  2. 部署载体 A/B/C(见部署载体与命名节)——owner 裁决,A 为倾向。
  3. 宿主 auto-compaction 禁用 已闭合:2.0.3 落方案 2(用户 jsonc 一行 compaction.auto: false,yadm 同步),方案 3 作退化兜底;dev/未来经 config hook 自动接管(探测到该面才启用,不硬依赖)。
  4. kill switch 通道:options.enabled(倾向,yadm 同步)vs 稳定目录文件(无需改 jsonc 即可停)。
  5. 固定端口 18787 + options.port 覆盖(倾向直接定,除非实测冲突)。
  6. update.ts 禁用机制:env 标记 vs CLI flag。
  7. 双模式共存按 env 判别做,还是更简单(直接要求二选一)。
  8. 插件 inert 的可见信号做到什么程度。
  9. bili 侧 feature gap 的移植优先级:contextLimitFallback / protectTags / qualityGate / 项目层配置,先做哪个(contextLimitFallback 建议最先,它堵住的是未知窗口模型的安全网缺口)。
  10. 开放问题节的七条张力(握手语义 / 自愈 / 探测身份 / 杀开关双场景 / 入口形态 / options 校验 / 第三方插件同装)——讨论收敛后逐项消解并回填。

上游化路径

仓库规矩(AGENTS.md):PR 必须先有 issue(Fixes #N)、Agent 永不 merge/publish、分支命名 YYYY-MM-DD_short-title。owner 的 ework agent 会自动审阅、跑全套验证、甚至直接在 fork 上落修复(PR #797 的 d50652c 先例)——响应速度很快,issue 值得当设计讨论场用。

issue 骨架(本 spec 的对外投影):

  1. 形态提案:"plugins": ["billion-context"] + exports["./server"](附 opencode 加载器源码依据)。
  2. 代理生命周期:机器级单例、service 解耦理由、多 server 汇流语义。
  3. 待 owner 验证:插件 config hook 改 compaction.auto(seam 已确认存在,剩 memoization 与读取时机两问,验证项 1)。
  4. 待 owner 裁决:部署载体 A/B/C(含命名);第三方压缩插件(opencode-acp)同装的互斥语义(开放问题 7)。
  5. 落点:src/agent/ 增量(独立入口变体已在 fork 分支有半成品:opencode-local.ts + 工厂 + 独立 id)。

独立 issue(不混进插件 PR):OpenAI context_management 零处理的透传缺口(用户当前配置不触发,残余风险)。

Activity

  1. ranxianglei commented on Sep 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷

    Thanks for the thorough design doc — the verified-facts section is genuinely well-sourced. I read it against the current tree (origin/master v0.1.114, acp-kernel 0.0.72 pinned) before answering, so the citations below are against what's actually merged, not a fork state.

    Verification (grounding)

    Every load-bearing claim in the doc checks out against master:

    • Triple export { id: "billion-context-opencode", setup, server } exists — src/agent/opencode.ts:332.
    • V2_BILI_TOOLS = [...ACP_TOOLS_OPENAI, ABSORB_TOOL_OPENAI] embedded registration — opencode.ts:212. The http.request hook stamps x-bili-plugin* headers only — no URL rewrite, no spawn today (opencode.ts:263-273). So local mode is purely additive on the existing thin protocol-client, exactly as framed.
    • Manifest already returns the identity field the health-probe needs: proxy: "billion-context" + protocolVersion — src/plugin.ts:376-377. Reusing fetchProxyVersion + asserting that field is a ~3-line probe.
    • package.json has no exports map; main: dist/index.js; and src/index.ts:6 runs main() at module top-level (import-unsafe confirmed). The plugin subpath bypasses the main entry, so no main-guard is needed for the plugin path itself.
    • No bare billion-context/dist/* imports anywhere in the repo → an explicit-enum exports map breaks nothing here (cross-repo downstream still needs a check before we seal — see Q1).
    • tsup.config.ts already lists each agent file as its own entry → adding src/agent/opencode-local.ts is a one-line change matching the existing "one host-access-method per file" convention.

    Overall assessment

    This closes a real gap: today opencode integration requires the launcher (bili opencode) injecting BILLION_CONTEXT_PROXY + temp config. Anyone who won't change how they launch (service mode, yadm-synced dotfiles across machines) has no path. The npm-plugin route reuses opencode's own install machinery and keeps plugin+proxy version-locked because they're the same package — the repo's "one version, one fact" philosophy as a free side effect, not a special mechanism. It fits the architecture (proxy stays single compression authority; plugin stays a pure protocol client) and doesn't pollute boundaries (local mode is additive, gated by env absence, degrades to inert). Green light to move toward implementation, with two owner sign-offs below. Since this is a feature/design thread, I'm giving recommendations and stopping short of code until those land.

    Answers to your five questions

    Q1 — Carrier: A (billion-context + exports["./server"]), explicit-enum exports map (not wildcard).
    Same-package version-locking is the whole point; a separate package (C) reintroduces the cross-package version seam this repo works hard to avoid, and B (turning live opencode-acp into a thin shell) is a product-architecture swap + name hijack that's owner-only and not viable now. On the sealing concern: I'd push back on the wildcard "./*": "./*" — it re-exposes the entire dist tree as public API, which is worse than sealing. Enumerate what's actually consumed externally: "." (main) and "./server" (the new plugin entry). Nothing in the repo imports billion-context/dist/* bare, so this is safe internally. Pre-flight before merging: confirm no downstream project (across repos) does a bare billion-context/dist/... import — if one does, add that specific subpath to the map rather than widening to a wildcard.

    Q2 — Separate dist entry (src/agent/opencode-local.ts → dist/agent/opencode-local.js), V2-only shape, distinct id. Agrees with your lean, and it's the natural fit: tsup already builds agent files individually; a distinct file whose behavior isn't keyed off runtime env makes "why did it spawn / not spawn" trivially debuggable (open question 5); a distinct plugin id sidesteps the unverified resolvePluginId same-id dedup when both the launcher-injected and npm-loaded plugins load in one process (verification item 13); and a V2-only entry sheds the oc1/dual-shape complexity (three-invariant #3) while the launcher file keeps the triple export for cross-generation survival.
    One caveat: the two files share most plumbing (header stamping, tool forwarding, window refresh, compaction reporting). Naive copy-paste is a drift hazard. Extract the shared V2 core into a factory parameterized by (proxyBase resolver, options, pluginId) — your fork branch already sketches createOpencodePlugin; extend it so both opencode.ts and opencode-local.ts call it. DRY without coupling the two deployment modes' behavior.

    Q3 — Tool registration source: keep embedded V2_BILI_TOOLS for v1; do NOT make manifest+reload the base. This is where I'd push back on the doc's lean, and it's the highest-leverage decision. Reasoning:

    • Manifest+reload buys "single source of truth," but that benefit only matters for cross-package clients (pi is a separate package). Here the embedded schema and the proxy's served schema come from the same source (compress-tool.ts) built together — drift protection within one package is nil.
    • Manifest+reload adds a startup-ordering dependency (probe → spawn → wait-ready → fetch-manifest → reload) on ctx.tool.reload — a seam your own comments flag as surface-churn-prone (opencode.ts:160-165, dev-build divergence). "Works on 2.0.3" ≠ "works on every observed surface."
    • Embedded registration depends on no such seam and guarantees tools are present on turn 1 regardless of proxy liveness. Even in the "隔代共事" skew window (new plugin → old detached proxy), the loose tool contract (POST /__bili/plugin/tool {conversationId, tool, args}) + stable tool names forward fine; worst case a new tool returns an error string the model sees. Bounded and recoverable.
    • Net: gate the handshake on protocolVersion (add the missing agent-side validation — verification item 20, a small in-PR addition), and treat version difference as informational. That cleanly resolves open question 1's branch without taking on the reload ordering risk.

    Q4 — opencode-acp coexistence: documented mutual exclusion + startup warning as v1; reject env-poisoning; true auto-exclusion is a cross-repo follow-up. They're mutually exclusive by definition (single-owner rule — two compression owners corrupt each other's placeholders), so don't try to make them coexist gracefully. I agree with rejecting channel (a): writing BILLION_CONTEXT_PROXY to trick opencode-acp into self-disable would pollute the shared-namespace env that is also billion-context's own launcher discriminator — the self-harm you flagged. For v1: detect the other's tell-tale at startup (if opencode exposes the loaded-plugin list to a plugin — needs a verification probe), log a prominent warning, and document exclusivity loudly in both READMEs. Since you maintain both projects, the right long-term fix likely lives in opencode-acp (teach it to defer when a bili proxy is authoritative) — that's an opencode-acp change, out of scope for this PR. I'll file it as a separate cross-repo issue tagged with #809 as source.

    Q5 — Auto-update disable: already solvable, no new update.ts mechanism needed. The gate exists in three forms today: --no-auto-update flag (cli.ts:160), ACP_AUTO_UPDATE=0 env / config "autoUpdate": false (config.ts:492), wired through if (opts.autoUpdate) startAutoUpdate(...) (cli.ts:415). The spawned bili just launches with --no-auto-update. Two things worth calling out:

    • It's required, not optional hardening. The existing source-checkout guard (isGitWorkingTree, auto-update overwrites tracked files when run from a git source checkout (findInstallDir resolves to repo root) #580) does not cover opencode's npm cache (npm strips .git), so without the explicit flag the spawned bili would self-update and race oc.py's Npm.add refresh. Confirm the spawn always passes it.
    • Recommend the CLI flag in spawn args (visible in the process cmdline for debugging, no new env-namespace pollution); optionally also set a distinct identity marker env (e.g. BILLION_CONTEXT_SPAWNED_BY=billion-context-opencode-plugin) purely for logging — but the actual auto-update gate is the existing flag. Frozen-spawned-bili is exactly right since oc.py is the upgrade authority for that copy.

    Positions on the open tensions (only where I add beyond the above)

    • T2 self-heal vs loud-fail: loud-fail for v1. Your panic-loop-masking concern is valid and matches let-it-crash. Rate-limited respawn (≤1/session + mandatory death-cause log) is a clean follow-up, not v1 scope.
    • T3 health-probe timing: startup-only for v1 (reuse fetchProxyVersion + assert proxy === "billion-context"). Add lazy re-probe-on-failed-request only if loud-fail proves too harsh in practice — avoid per-request overhead up front.
    • T4 kill switch: options.enabled: false for v1 (jsonc/yadm-synced, static, clean). Note the existing BILLION_CONTEXT_PLUGIN=0 env inert toggle (opencode.ts:210) already covers the emergency case; options.enabled just extends it to jsonc. Defer the file-based 30-second stop — it's a second state source fighting minimal complexity.
    • T6 options-validation philosophy: here I'd override the fail-loud instinct. Verification item 19 shows a setup() throw is log-line + silent-continue (weak user visibility), so fail-loud risks the worst silent outcome (malformed options → plugin silently dead → direct passthrough, user thinks compression is on). Use fallback-to-default + stderr/log warning for malformed values given the host swallows setup throws.

    Staged path forward (for scope approval)

    Phase 1 (first PR, low-risk core):

    1. Extract shared V2 factory from opencode.ts; add src/agent/opencode-local.ts (separate tsup entry, distinct id, V2-only {id, setup} shape).
    2. Local mode: options.port → default http://127.0.0.1:18787; manifest+identity health probe; on miss spawn node <pkgroot>/dist/index.js --port <port> --no-auto-update (detached, loopback-bound default, pkgroot from import.meta.url); idempotent /bili/<url> rewrite in the http.request hook; env stand-down (BILLION_CONTEXT_PROXY set → local instance inert).
    3. package.json exports: explicit enum { ".": "./dist/index.js", "./server": "./dist/agent/opencode-local.js" } (post downstream-import pre-flight).
    4. Add agent-side protocolVersion validation (closes verification item 20).
    5. Unit tests: URL rewrite (query / special chars / https upstream), /bili/ parse + idempotency, options parsing (defaults / malformed → fallback+warn), env-discrimination branches.

    Phase 2 (after e2e validation): options.enabled kill switch, inert-visibility signal, opencode-acp coexistence warning.

    Separate follow-up issues (not in this PR): opencode-acp mutual exclusion (cross-repo, source-tagged #809); OpenAI context_management zero-handling passthrough gap; contextLimitFallback feature gap (your suggested first bili-side port).

    What I need from you (genuine decision points)

    1. Carrier: confirm A (billion-context + exports["./server"]) and approve the explicit-enum exports map — I'll run the cross-repo bare-subpath-import pre-flight before sealing.
    2. opencode-acp exclusion: confirm "document + warn in both, auto-exclusion as a cross-repo follow-up" is acceptable, or direct otherwise.
    3. Scope: approve Phase 1 as the first PR with Phases 2 + follow-ups staged after e2e?

    Once (1)–(3) land I'll open the issue-linked PR (Fixes #809 or Part of #809 depending on how you want the follow-ups tracked).


    中文摘要:设计稿我逐条对着当前 master(v0.1.114)核实过,代码引用都成立。总体认可——它补的是真缺口(现在 opencode 必须走 launcher),插件+代理同包同版本是仓库"一个版本一个事实"哲学的免费副产品,架构契合、耦合低。五个问题我的明确建议:①载体选 A(billion-context 本体 + exports["./server"]),用显式枚举 exports(不用通配符,避免把整个 dist 暴露成公共 API);②独立 dist 入口(opencode-local.ts,V2-only,独立 id),但把共享 V2 逻辑抽成工厂避免双文件漂移;③工具注册保持内嵌(不走 manifest+reload——单一事实源只对跨包客户端有意义,同包内 schema 同源零漂移,而 reload 是会 churn 的接缝且引入启动时序依赖),握手按 protocolVersion 判(顺带补上缺失的 agent 侧校验)、版本差纯信息性;④与 opencode-acp 互斥走"文档声明+启动告警",拒绝写 env 骗自禁(会污染自己的 launcher 判别器),真正的自动互斥归到跨仓 follow-up issue;⑤自更新禁用现有机制就够——spawn 时带 --no-auto-update(git-checkout 守卫不覆盖 npm cache,所以这条是必需不是可选)。需要你拍板三件事:载体 A + 显式 exports、opencode-acp 互斥归属、以及 Phase 1 作为首个 PR 的范围。拍板后我再开带 Fixes #809 的 PR。

  2. jensenojs commented on Sep 15, 2026

    @jensenojs
    ContributorAuthor

    五个问题全部同意,其中两处我明确修正自己的倾向:

    1. 载体 A + 显式枚举 exports:同意,并放弃 wildcard 倾向——"把整个 dist 重新暴露为公共 API 比封印更糟"这个论证我接受。跨仓裸子路径导入的 pre-flight 我顺手跑了:GitHub 全局代码搜索 billion-context/dist 和 "billion-context/ 两个模式零命中(code search 索引有覆盖盲区,非绝对证明,但作为合并前检查的信号足够)。显式枚举 { ".": "./dist/index.js", "./server": "./dist/agent/opencode-local.js" } 可以放心。
    2. 独立入口 + 共享工厂:同意。fork 分支的 createOpencodePlugin 草稿需要扩一个 id 参数——现在写死了 billion-context-opencode,两文件同 id 会在 launcher + npm 双加载时撞工具注册;opencode.ts 和 opencode-local.ts 都改为调工厂,消除双文件漂移。
    3. 注册源保持内嵌——接受反驳,让步干脆:"单一事实源的收益只在跨包客户端成立,同包内 schema 同源、漂移防护为零"是对的;而 manifest+reload 引入的启动时序依赖(probe → spawn → wait → fetch → reload)正好压在你们自己标注过的 churn 接缝上(opencode.ts:160-165)。开放问题 1 就此收敛:握手按 protocolVersion 判 + 版本差纯信息性 + agent 侧校验补进 PR(关掉验证项 20)。
    4. acp 互斥走文档 + 启动告警:同意。env 污染通道我本来就只是列出来示众,弃。
    5. --no-auto-update:同意用 CLI flag(cmdline 可见、零新 env 命名空间)。"git-checkout 守卫不覆盖 npm cache(npm 剥掉 .git)所以这条是必需不是可选"——这个提醒很关键,spawn 参数必带。

    T2/T3/T4/T6 同意:响亮失败 v1、仅启动期探测(复用 fetchProxyVersion + 断言 proxy 字段)、options.enabled、options 校验 fallback+告警(T6 的论证成立——setup throw 在宿主里只有日志行时,fail-loud 制造的是最坏的静默,我收回 fail-loud 倾向)。BILLION_CONTEXT_PLUGIN=0 已覆盖紧急停用场景这条也记下了,options.enabled 只是把它延伸到 jsonc。

    三个拍板项,从我这侧确认:① A + 显式枚举 ✓(pre-flight 结果如上);② acp 互斥文档+告警 ✓;③ Phase 1 范围 ✓——含 protocolVersion 校验,排除 manifest reload,options.enabled 与 inert 可见性放 Phase 2。

    PR 分工:我来开——fork 的 opencode-plugin-local-mode 分支已有工厂草稿 + 幂等 /bili/ 改写的半成品(约 27 行),我把它扩成 Phase 1:spawn(node <pkgroot>/dist/index.js --port <port> --no-auto-update,detached + loopback,pkgroot 从 import.meta.url 解析)、身份探测、env 判别(BILLION_CONTEXT_PROXY 在 → 本实例 inert)、ctx.options ?? 第二参数 的 options 解析、exports 声明、tsup 入口、单元测试(改写幂等/特殊字符/https、options 非法值 fallback+告警、env 分支)。分支名按仓库规矩 2026-09-15_opencode-npm-plugin,Fixes #809。@ranxianglei 对 ①-③ 点头即开工;如果你更想让 ework 直接从我的 fork 分支接力实现,协作方式你定。

  3. ranxianglei commented on Sep 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷

    收到,全部对齐——谢谢干脆的让步(Q3 内嵌注册、T6 fallback+告警都收下)。三个拍板项按你确认的锁定:①A + 显式枚举 exports(你跑了跨仓裸子路径搜索零命中,够了)、②acp 互斥走文档+启动告警、③Phase 1 范围(含 protocolVersion 校验,排除 manifest reload,options.enabled 与 inert 可见性放 Phase 2)。

    分工决定:由我(ework)开这个 PR。 理由:单一干净 PR、不依赖跨 fork 访问、分支名按仓库规矩走。你 fork 上那 ~27 行草稿的思路(createOpencodePlugin 工厂带 id 参数 + 幂等 /bili/ 改写)我会照做,但在我这边对着真实代码库从零重建——这样 provenance 干净、不引入外部分支耦合,也省得两边各推一条竞争分支。所以请你先别另开 PR;如果你更想自己推自己的分支收尾,说一声我就让位。

    几点实现侧说明(都是我们已收敛结论的落地,不是新分歧):

    • 回归护栏我看过了:tests/opencode-v2.test.ts 锁死了 launcher V2 插件的 .id/.setup/.server、工具 schema 精确 parity、/bili/ 与 env 两条惰性激活路径、BILLION_CONTEXT_PLUGIN=0 kill switch、session.compaction.ended 边界上报、cleanup dispose。重构会把这些共享 V2 逻辑抽进 src/agent/opencode-v2.ts 的工厂(带 id 参数),opencode.ts(launcher)和新的 opencode-local.ts 都调它——目标是该测试全绿不动。
    • 一个我要在 PR 里显式标注、但不阻塞开工的验证点:local 模式的核心新行为是在 http.request 里改 e.request.url 到 wire。现有代码注释只实证了 headers 改动能到 wire(opencode.ts:140-141),url 在类型里是可写属性、你的草稿也基于它,但"url 改写真到 wire"这一条 e2e 冒烟要第一个盖住(对应设计稿验证项 9)。若某个 opencode build 不吃 http.request 的 url 变更,fallback 是 model.request 的可变 baseURL 改写——记为后续,不进 v1 以保持范围紧。
    • 会话头防伪、loopback-only spawn、--no-auto-update 必带(git-checkout 守卫不覆盖 npm cache,这条是必需)都按确认的做。

    现在就动手:分支 2026-09-15_opencode-npm-plugin,PR 带 Fixes #809,typecheck + 单测 + build 全绿后回来贴链接。acp 互斥的跨仓 follow-up issue(source-tagged #809)我随后单独提。

  4. jensenojs commented on Sep 15, 2026

    @jensenojs
    ContributorAuthor

    收到——由你开 PR,我不另开分支。27 行草稿的思路(工厂 + id 参数 + 幂等改写)你随意取用,对真实代码库从零重建的确 provenance 更干净。

    url 改写到 wire 这个点你提得准:现有实证只覆盖 headers(opencode.ts:140-141),我的草稿也是基于"url 在类型里可写"的假设——e2e 第一个盖住它是对的顺序。如果真有 build 不吃 http.request 的 url 变更,model.request 的可变 baseURL 是现成 fallback(探针已实证其到 wire)。

    等你的 PR 链接。

  5. ranxianglei commented on Sep 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    按收敛后的方案从 master 开工并开了 PR(我这边开,避免和你 fork 分支撞车;你 fork 上那 ~27 行 WIP 可留作参考,我以「共享工厂」为准重写了一遍)。

    **PR: https://github.com/ranxianglei/billion-context/pull/810**(`Fixes #809,分支 2026-09-15_opencode-npm-plugin`)

    Phase 1 落地:

    • 新增独立入口 src/agent/opencode-local.ts(id billion-context-opencode-local,V2-only {id, setup})。
    • V2 逻辑抽成共享工厂 createOpencodeV2Setup(config)(新文件 src/agent/opencode-v2.ts);launcher(opencode.ts)与 npm 入口都调它——两文件不再漂移,双加载时 id 不同不撞工具注册。
    • local 模式:options.port → 默认 http://127.0.0.1:18787;先探 manifest 并断言 proxy === "billion-context"(占位的外来服务响亮拒绝,不静默采用);连不上才 spawn node <pkgroot>/dist/index.js start --port N --host 127.0.0.1 --no-auto-update(detached + loopback,pkgroot 从 import.meta.url 解析);首请求幂等改写 /bili/<url>。
    • 互斥/停用:BILLION_CONTEXT_PROXY 已在 → inert 不 spawn;BILLION_CONTEXT_PLUGIN=0 kill switch → inert。acp 互斥走文档 + 启动告警(v1)。
    • exports 显式枚举 { ".": "./dist/index.js", "./server": "./dist/agent/opencode-local.js" };tsup 加入口;protocolVersion 校验补进 agent 侧(握手按 protocolVersion 判、版本差纯信息性)。

    Pre-flight(本机跑过): typecheck 干净;node --test 1618 pass / 0 fail / 2 skip(skip 为既有);tsup build 产出 dist/agent/opencode-local.js;built-artifact 冒烟(default.id/setup、resolvePackageRoot() 指向存在的 dist/index.js、spawn 参数)均正确。

    两处留给你的真实 upstream e2e(单测只覆盖纯逻辑,未打活客户端/upstream):

    1. url-mutation 是否真到 wire —— hook 改的是 e.request.url;opencode.ts 的注释只证明了 headers 到 wire,url 这个 typed writable property 到没到 wire 在这边无法验证。若没到,fallback 改 model.request 的 baseURL(延后,不进 v1)。
    2. spawn 收敛 —— EADDRINUSE 双进程竞态靠 loser 无 launch token 干净退出(server.ts)收敛,我是读代码确认的,没做 live 双 spawn。

    建议 smoke:真实 OpenCode 2.x 指到 Responses-compatible upstream(经 options.port),确认首请求改写 + 一次 compress round-trip,再加 kill-switch / BILLION_CONTEXT_PROXY stand-down 各一次。

    Phase 2(本 PR 明确排除): options.enabled toggle、inert 状态可见性、manifest reload。

    麻烦 review;CI 是 manual-dispatch(需 repo secrets),你那边能跑就跑下 e2e。合并由你来(Agents 不能 merge)。

  6. ranxianglei commented on Sep 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    链接来了(我上一条和你这条撞车了,重发一次):

    **https://github.com/ranxianglei/billion-context/pull/810**(`Fixes #809,分支 2026-09-15_opencode-npm-plugin` → master)

    按你说的从 master 从零重建,没碰你 fork 的分支(provenance 更干净)。你草稿的三个点都落进去了:

    • 共享工厂 createOpencodeV2Setup(config)(新文件 src/agent/opencode-v2.ts),launcher 和 npm 入口都调它。
    • id 参数化:两个入口各自带 id(launcher=billion-context-opencode、local=billion-context-opencode-local),双加载不撞工具注册。
    • 幂等 /bili/ 改写:首请求改写、二次 fire 不动。

    url→wire 这点我们判断一致:e2e 第一个盖它。fallback 我也认——若真有 build 不吃 http.request 的 url 变更,改 model.request 的可变 baseURL(你探针已实证 baseURL 到 wire)。这条我留在 PR body 里标成延后项,不进 v1,避免现在为未证实的路径加代码。

    Pre-flight 本机已过:typecheck 干净 · node --test 1618 pass / 0 fail / 2 skip(skip 既有)· tsup build 产出 dist/agent/opencode-local.js。

    麻烦 review;CI manual-dispatch 需 repo secrets,你那边能跑就跑下真实 upstream 的 url-mutation + spawn 收敛两项。合并由你来。

  7. jensenojs commented on Sep 15, 2026

    @jensenojs
    ContributorAuthor

    别急, 我试用了一下搞出 Session failedx
    Attempted to assign to readonly property., 了, 所有的session都用不了了... 我还在看是怎么回事

  8. ranxianglei commented on Sep 15, 2026

    @ranxianglei
    Owner

    link #513

  9. ranxianglei commented on Sep 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    收到,这个严重,我马上查。先给你立即恢复的办法(不用等修复):

    临时解锁(任选其一)→ 重启 opencode:

    1. 把 opencode.json 的 plugin/plugins 数组里的 "billion-context" 删掉;或
    2. 设环境变量 BILLION_CONTEXT_PLUGIN=0(kill switch)

    这样插件不注册任何 hook,session 立刻能回来。

    为精准定位,麻烦给两个信息:

    • 完整 stack trace(readonly 到底抛在哪一行 / 哪个属性)——直接定到点;
    • 你怎么加载的?opencode.json 里 plugins:["billion-context"](npm 入口),还是 bili opencode launcher?opencode 版本号。

    我这边在读你链的 #513,同时在审新入口 request-hook 的属性改写路径——最可疑的是 http.request hook 里对 request 字段的赋值:若 OpenCode 2.x 在运行时冻结了该对象(类型上可写、运行时只读),赋值就会炸,且每次请求都炸 → 所有 session 挂。稍后给根因 + 修复。

  10. jensenojs commented on Sep 15, 2026

    @jensenojs
    ContributorAuthor

    补充一次真实宿主复现结果(macOS,OpenCode v2.0.3,PR #810 的本地构建):

    我在 ~/.config/opencode/plugins/bili-pkg/index.js 启用了 PR #810 的 local plugin。OpenCode 会加载它,但每个请求在 httpRequestHook 里报:

    TypeError: Attempted to assign to readonly property
    Failed to drain Session

    位置是 dist/agent/opencode-local.js 的 e.request.url = next。

    OpenCode 2.0.3 的 http.request 事件传入 WHATWG Request。event.request 这个字段可以被整体替换,但 Request.url 是只读属性。当前 hook 直接写 .url,所以请求在发往上游之前就失败,表现为所有 session 失败。类型里的 url?: unknown 没有反映运行时只读约束。

    另外确认了一个独立问题:真实 /Users/oujinsai/.local/opt/opencode-v2/bin/opencode 是 Mach-O arm64 可执行文件。local plugin 使用 spawn(process.execPath, [dist/index.js, ...]) 时,process.execPath 指向 OpenCode CLI 本身,不是 Node。代理未运行时,这会把 dist/index.js 当作 OpenCode 子命令参数,打印帮助后退出。这个问题与 readonly 报错分开:本次已有 18787 进程,所以先触发的是 URL 写入错误。

    为恢复使用,我把 ~/.config/opencode/plugins/bili-pkg 移到 ~/.config/opencode/plugins-disabled/bili-pkg,没有修改 PR 源码。等待插件 watcher 重载后执行真实请求:

    opencode run --format json --auto "只回复 OK"

    退出码为 0,返回 OK。这证明停用插件即可恢复当前 OpenCode 会话。

    PR body 已把“URL 改写是否真正到 wire”列为待验证项;这次真实 E2E 给出了反例。修复方向应在 hook 边界重新构造可变请求或修改受支持的上游 URL 字段,避免直接写 WHATWG Request.url;spawn 则需要明确调用 Node runtime,而不是 process.execPath。我这次没有改代码。

  11. jensenojs commented on Sep 15, 2026

    @jensenojs
    ContributorAuthor

    补充诊断过程和根因边界(对应本 issue 之前的“request 属性只读”怀疑,以及 PR #810 body 中尚未完成的真实 E2E 验证):

    诊断过程

    1. 先确认故障发生在真实 OpenCode 会话,而不是单测。环境是 macOS,OpenCode v2.0.3,插件通过 ~/.config/opencode/plugins/bili-pkg/index.js 自动加载。会话界面显示 Session failed,日志同时出现 Failed to drain Session。
    2. 沿日志 stack trace 定位到 PR feat: opencode 2.x no-launcher npm-plugin deployment #810 构建产物 dist/agent/opencode-local.js 的 httpRequestHook。失败语句对应源码中的 e.request.url = next。
    3. 对照 OpenCode 2.0.3 的运行时形状:http.request 事件携带的是 WHATWG Request。事件里的 request 引用可以被整体替换;WHATWG Request 实例的 url 属性由对象本身只读提供。当前实现把“类型接口里可访问的 url 字段”当成了“运行时可以写入的 url 属性”,两者约束不一致。
    4. 再单独检查 local 模式的启动前提。真实的 /Users/oujinsai/.local/opt/opencode-v2/bin/opencode 经 file 确认为 Mach-O arm64 原生可执行文件。于是,在代理未运行时,process.execPath 指向 OpenCode 可执行文件;local plugin 的 spawn 参数把 dist/index.js 交给了 OpenCode CLI 解析。这个过程会输出 CLI 帮助并退出,随后插件的启动轮询超时,形成静默 inert。
    5. 最后做停用实验:把 bili-pkg 目录移出 OpenCode 自动发现目录,等待 watcher 重载,再执行真实请求 opencode run --format json --auto "只回复 OK"。命令退出码为 0,返回 OK。这一步把“插件 hook 导致会话失败”与 OpenCode 本身故障区分开。

    根因关系

    当前这次“所有 session 都失败”的直接根因是:

    httpRequestHook 在请求发送前执行 e.request.url = next;运行时对象是 WHATWG Request,Request.url 为只读;赋值立即抛出 TypeError: Attempted to assign to readonly property;OpenCode 随后报告 Failed to drain Session,所以每个经过该 hook 的会话都会失败。

    spawn 问题属于另一条独立故障链:

    代理已在 18787 监听时,请求先走到了 URL 赋值,因此先暴露 readonly 异常。代理没有运行时,才会进入 spawn(process.execPath, ...) 路径,因宿主是 Mach-O 原生 OpenCode CLI 而不是 Node 解释器,子进程无法按预期启动代理,最后表现为轮询超时和插件 inert。它解释了“为什么代理缺失时插件接不上”,不解释本次已经出现的 readonly stack trace。

    证据范围

    这次实测证明了三件事:

    • PR feat: opencode 2.x no-launcher npm-plugin deployment #810 的 local plugin 在真实 OpenCode v2.0.3 中确实能被加载;
    • URL hook 的运行时赋值会在请求阶段抛出 readonly 异常,并把错误传播成 session failure;
    • 移除该插件后,现有 OpenCode 服务可以完成真实请求。

    这次实测没有覆盖其他 OpenCode 版本、其他宿主构建,也没有把“修复后 URL 是否能到达上游”作为已验证事实。这里仅记录故障链和证据边界,不提出根因修复方案。

  12. ranxianglei commented on Sep 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    你的两条诊断完全正确,我这边独立复现也收敛到同一根因,谢谢这么扎实的实测。逐条确认 + 修复方向:

    Bug 1(crash,已复现):Request.prototype.url.set === undefined(只读 getter)。非严格模式下 r.url=x 静默失败(url 不变),但 billion-context 是 ESM=严格模式,赋值直接抛 TypeError: Cannot set property url of #<_Request> which has only a getter——和你看到的 Attempted to assign to readonly property 同一机制。你点出的关键「event.request 引用可整体替换」正是解法:不写 .url,改为 e.request = new Request("<proxy>/bili/<原url>", e.request)——method/headers/body 从原请求带过去,指向代理。这样留在已验证的 http.request seam 内,不需要动 globalThis.fetch。另外我会把整个 hook 包进防御性 try/catch:插件绝不能把宿主 session 打挂——任何异常都降级为直通(不压缩),绝不 reject 出去。

    Bug 2(spawn 用错可执行文件,独立链):确认 process.execPath 在原生 opencode 二进制下不是 Node。修复=解析真实 Node runtime:先查 process.execPath basename 是否 node,否则沿 PATH 找 node/node.exe,再留 BILLION_CONTEXT_NODE 环境变量兜底;找不到就响亮报错 + inert(不再静默轮询超时)。

    为什么单测没抓到:mock 用的是普通对象 {url, headers}(.url 可写),掩盖了 WHATWG Request 的只读约束;类型里 url?: unknown 也没反映运行时约束。我会把 mock 换成真实 Request,让这条回归被测试守住。

    正在改 + 验证(typecheck/test/build),稍后往 #810 推更新。你复测时注意:你的手动拷贝布局(plugins/bili-pkg/index.js)不在 npm 包结构里,resolvePackageRoot 找不到 dist/index.js——标准路径应是 plugins:["billion-context"] 解析到 node_modules/billion-context;若坚持手动布局,需保证 dist/index.js 可达并设 BILLION_CONTEXT_NODE。等你更新后我给具体复测步骤。

  13. added a commit that references this issue on Sep 15, 2026
    af02b2a
  14. ranxianglei commented on Sep 15, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    两个 bug 都修好了,已推到 #810(commit af02b2a,在 cb8c00b 之上)。逐条对应你的诊断:

    Bug 1(readonly crash):不再写 .url。改为整体替换请求引用——e.request = new Request("<proxy>/bili/<原url>", e.request),method/headers/body 从原请求带过去、指向代理。这正是你说的「event.request 引用可整体替换」。另外把整个 httpRequestHook 包进防御性 try/catch:任何异常都降级为直通(不压缩),绝不 reject 出去——插件不可能再把宿主 session 打挂。构造失败(如 body 已被消费)也走同一条降级路径。

    Bug 2(spawn 用错可执行文件):新增 findNodeRuntime():先看 process.execPath basename 是否 node,否则沿 PATH 找 node/node.exe,再留 BILLION_CONTEXT_NODE 环境变量兜底;找不到就响亮报错 + inert(不再静默轮询超时)。

    为什么之前没抓到:单测 mock 用的是普通对象 {url, headers}(.url 可写),掩盖了 WHATWG Request 的只读约束。现在 mock 换成真实 Request,并加了回归测试钉死「必须换引用、不能写 .url」,另加 findNodeRuntime 四个分支测试。

    本机验证:typecheck 干净 · node --test 1623 pass / 0 fail / 2 skip · tsup build 产出 dist/agent/opencode-local.js · 构建产物 smoke:findNodeRuntime()→真实 node、spawn args 指向 dist/index.js、rewrite 幂等成立。

    你复测的步骤(关键在最后两点):

    1. 从更新后的分支重新构建:git checkout 2026-09-15_opencode-npm-plugin && npm ci && npm run build,再按原路径部署。
    2. 部署结构:插件文件须位于 <包根>/dist/agent/opencode-local.js——因为 resolvePackageRoot 从插件文件上溯两级当包根,再去找 dist/index.js。你现在的 plugins/bili-pkg/index.js 是单文件拷贝,上溯两级是 plugins/,找不到 dist/index.js,代理起不来(会响亮报错+inert,不崩)。请部署整个包(标准 plugins:["billion-context"] 解析进 node_modules 即可),别只拷一个 index.js。
    3. PATH 边界:若你的 opencode 是从 Finder/GUI 启动、环境里 PATH 没有 node,设 BILLION_CONTEXT_NODE=/绝对路径/node。
    4. 预期:不再有 readonly 报错;代理在 18787 自动拉起;压缩生效。

    仍待你确认的最后一步:「换引用后的请求是否真的被 opencode 发出去、且代理能从 /bili/ 解出上游」这条完整回路,我这边靠你的实证(引用可替换)+ 单测回归覆盖,但真实宿主端到端还需你这次复测盖章。麻烦跑一下,有问题贴日志给我。

  15. jensenojs commented on Sep 15, 2026

    @jensenojs
    ContributorAuthor

    你确保你这里的坑在 #513 上不会再犯就好了,

  16. 84 remaining items

  17. added a commit that references this issue on Sep 17, 2026
  18. ranxianglei commented on Sep 17, 2026

    @ranxianglei
    Owner

    已经合并了众多opencodev2 等发版本 本issue关闭

  19. added a commit that references this issue on Oct 25, 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