Repository navigation
Description
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 spawnsnode <package root>/dist/index.jsdetached, loopback-bound; the path is resolved fromimport.meta.urlat 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_PROXYis 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 (tagd44b52c,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.optionsexists (options channel works),ctx.tool.reload()works (transform re-fires — tool registry rebuild is available), plugin file hot-reload + clean dispose work. model.requestfires with a mutable baseURL that reaches the wire — a second rewrite channel besideshttp.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,createOpencodePluginfactory + fixed proxy base + distinct plugin id) ready to extend into a PR.
Questions for you
- Carrier:
billion-contextitself withexports["./server"](my lean — one package, one version, oc.py-style host updates just work) vs a separate thin opencode-scoped package. Note: adding anexportsmap seals bare subpath imports (billion-context/dist/*), so it needs a wildcard ("./*": "./*") or explicit enumeration — a repo-level decision. opencode-acp already publishesexports["./server"], so this contract route matches your existing practice. - 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.
- Tool registration source: keep embedded
V2_BILI_TOOLS, or re-register from the proxy manifest after spawn viactx.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). - 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? - 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 opencodelauncher 模式共存不互相踩。
背景
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 载体的地基,逐条给源码位置:
- 包入口解析(
packages/opencode/src/plugin/shared.tsresolvePackageEntrypoint):优先package.json exports["./server"](TUI 插件读exports["./tui"]),否则回落main(仅 server kind)。npm spec 经parsePluginSpecifier(裸包名 = latest)+Npm.add装进 opencode 自己管理的 npm cache(具体目录未核实,验证项)。 - 插件调用(
packages/opencode/src/plugin/index.tsapplyPlugin):server(input, load.options)——jsonc 里 plugins 条目的options字段作为第二个参数传进插件函数。旧形态(导出裸函数)同样(input, options)。 - 配置键(
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 配置注入走的就是这条迁移路。 - 插件可改 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 属于 V1server()路径的 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 条的典型退化场景。 - billion-context 主入口 import-unsafe:
src/index.ts模块级无条件执行main()。对 npm 载体无碍——exports["./server"]子路径直接指向dist/agent/opencode.js,绕开主入口,无需加 main-guard。 - service 模式:opencode 2 有
opencode service start/stop/status/...(后台 server 管理)。插件(server kind)跑在 server 进程内,process.env可读——launcher 模式的现有 V2 插件就靠BILLION_CONTEXT_PROXYenv 工作。 - 插件模块契约跨代翻转(2.0.3 tag
d44b52cvs 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 的原因)。 - options 注入路径两代不同:2.0.3 合进 host input(
ctx.options,module.tseffect: (host) => plugin.effect({...host, options: operation.options}));dev 是 setup/server 的第二参数。插件读两处(ctx.options ?? arguments[1])。 - 入口解析两代一致:2.0.3
Host.resolve先试<pkg>/server子路径再回落 main(entry(["server", ""]));devresolvePackageEntrypoint读exports["./server"]优先。exports["./server"]两代通吃。
事实修正
- 原稿"插件进程读不到宿主 env,配置只能写死源码或走文件"不准确:V2 插件跑在 opencode server 进程内,
process.env可读。真正不可及的是 opencode 启动后才产生的内部状态;config 对象可能经 init 期 mutation seam 可及(见上条第 4 点,验证项)。 - launcher 注入机制全貌(
prepareOpencodeHttpRewrite):深拷贝用户合并配置 → 改写发现的 provider baseURL → tempopencode.json里 append 插件条目(2.x 用 temp 目录 index.js re-export 真实插件文件,走 V1plugin键 + 迁移)→ 注入compaction.auto: false→OPENCODE_CONFIG指向 temp 文件(叠加在全局合并之上,PR fix(launcher): read opencode JSONC config (comments + merge) like opencode itself #797 已对齐这个语义)→ 设BILLION_CONTEXT_PROXYenv。 - 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.requesthook 触发、能就地改 URL 和 header,改动真实到达 wire。tool.transform能注册工具,execute 回调 ctx 里有sessionID。ctx.catalog.model.list()能拿 per-model 上下文窗口。~/.config/opencode/plugins/自动加载,放单个 js 即生效,零配置改动;configplugin数组条目必须目录。- 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无--standaloneflag)。
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,失败后有retryhook)/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.transformseam,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 加
exportsmap 会封印子路径导入——一旦 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)没变,变的只是接缝数与运行位置。三条不变量守住,版本差异就只是降级矩阵的一行:
- inert 地板:所有 opencode 版本敏感接缝(http.request / config hook / tool.reload / options / session hooks)都有定义好的退化路径,地板是"直连不压缩"。任何无 fallback 的新接缝不得进 delta。
- 唯一承重契约:对 opencode 的硬依赖只有包入口解析(
exports["./server"])——唯一无 fallback 的一项,也是整条链上最稳的一环(核心加载机制,非实验接缝)。它断裂属生态级事件(所有 npm 插件一起死),检测靠 opencode 的插件列表可见性,插件内无缓解手段。 - 插件内禁版本探测:插件一旦出现
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 的增量变体,不是重写:
- proxyBase 解析链改为:
BILLION_CONTEXT_PROXYenv(launcher 在管时整个插件实例退让)→ local 模式下options.port→ 默认http://127.0.0.1:18787;启动探测、缺失自启(替代 env/URL 推导)。 - 主动 URL 改写为
/bili/<原URL>形态(现有插件只盖章不改写;这是核心新行为),且必须幂等——请求已是/bili/形态时不得重复加前缀。 - kill switch 通道待决策:
options.enabled: false(jsonc,yadm 同步,干净)vs 文件制(原稿方案,但���件目录在 npm cache 里会被升级冲掉——若走文件必须放~/.config/billion-context/等稳定用户目录)。见配置面。 - 出站 body 检测到
context_management时 stderr 告警。 - 与 bili 的握手/版本语义待裁决(开放问题 1):握手按 protocolVersion 判(需先补 agent 侧校验);版本差的处理随注册源选择分支——注册源迁移到 manifest 则纯信息性,保持内嵌则告警有真实价值。原稿的"自重启 bili"在两种分支下都不成立(npm cache 场景重启的还是 oc.py 管着的那份码),已否决。见升级与兼容。
- 注册源迁移候选(评审新增,见 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:212V2_BILI_TOOLS由ACP_TOOLS_OPENAI+ABSORB_TOOL_OPENAI构建进 bundle,注释 160-165 行给出理由——同步注册可用、tool.reload在部分观测面上不可用)。消费 manifest 的是 pi(agent/pi.ts:206)。所以"schema 漂移构造上不可能"只对 pi 成立;opencode 插件与代理的一致性靠构建期纪律(注释明写 parity withsrc/compress-tool.ts),运行时无校验。 protocolVersion当前无消费者校验:agent 侧无人 fetch 后比对(opencode 插件根本不 fetch)。协议门控是它该承担的职责(见验证项 20)。- 版本串(
version)纯信息性:fetchProxyVersion供状态 UI 展示,不参与任何门控。 - 注册源迁移是 delta 改动项,且接缝在 2.0.3 上已声明存在:
Host.resolve后的 Contexttool: { transform, reload, hook }(2.0.3core/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):
- models.dev registry 快照(
src/registry-snapshot.json,离线地板)。 - 用户配置
~/.config/billion-context/billion-context.json的 compress 段,global → provider → model 三级按字段 deepest-wins 合并,嵌套对象(prompts / absorb / reasoning)子字段级合并。这是 per-provider/per-model 压缩参数(阈值、headroom、prompts)的用户可调面。 - 插件从 opencode catalog 盖的
x-bili-plugin-context-window头(注册路由表时消费)。 - 从真实 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,候选方案按优先级重排:- 插件 config hook 直接改——已闭合:2.0.3 不可达(V2 Context 无 config 面,背景契约第 4 条);dev/未来版本经 V1 路径可达且机制成立(共享引用+惰性读取)。留作该面出现时自动启用的增强,不作为 2.0.3 的依赖。注:本插件 V1 路径确实在用 config hook(
agent/opencode.ts:91-97注入/acpcommand),但 2.0.3 选 setup 弃 server,V1 路径不执行。 - 用户全局 config 加一行
compaction.auto: false(yadm 同步)——2.0.3 的既定答案,launcher 模式注入的同款键。 - 维持现状退化兜底:宿主压缩后插件经
session.compaction.ended上报边界,bili 归档自己的块(现有 V2 插件已有此退化路径;reportCompactionBoundary已实现)。
- 插件 config hook 直接改——已闭合:2.0.3 不可达(V2 Context 无 config 面,背景契约第 4 条);dev/未来版本经 V1 路径可达且机制成立(共享引用+惰性读取)。留作该面出现时自动启用的增强,不作为 2.0.3 的依赖。注:本插件 V1 路径确实在用 config hook(
- 第三方压缩插件同装(评审新增,本用户场景真实存在——workspace 里就有 opencode-acp):opencode-acp 的自禁用三条件(自身 enabled 开关 /
BILLION_CONTEXT_PROXYenv / 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 对 OpenAIcontext_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 + 切换用例。
实现期待验证清单
config hook 改源码级闭合:2.0.3 V2 Context 无 config 面(不可达);dev 经 V1 路径可达且共享引用+惰性读取成立。方案落定见单 owner 节。compaction.auto: false闭合(源码 + 探针):2.0.3 注入options第二参数在 2.0.3 传入ctx.options(探针实证字段存在),setup 第二参数为 null;dev 用第二参数——插件读两处。源码级闭合:2.0.3exports["./server"]在 2.0.3 生效Host.resolve先试<pkg>/server子路径再回落 main,与 dev 的exports["./server"]优先语义一致。Npm.add的 cache 目录位置与生命周期(opencode 跨版本/多实例是否共享同一份 billion-context)。e.sessionID在 http.request 事件的稳定性与覆盖面。- hook 事件是否暴露请求 body(原生压缩检测)。
失去必要性(决策项 3 已闭合走方案 2;保留为 dev 接缝面变化时的复检项)。compactionhook 能否拦截宿主压缩- kimi→gpt 切换后
<acp>标签在工具历史格式转换中幸存。 /bili/改写对 query / https upstream 的正确性。- bili 中途死掉的确切行为与是否加健康检查降级。
- catalog 头 vs registry vs learned 窗口冲突时谁赢。
- 持久化状态跨 bili 版本 reload(升级后旧会话)。
- launcher + npm 双插件共存:加载顺序、工具去重、独立 id 错开。
per-directory scope已实证(探针:单 service 6 个 location 实例);剩余:同包名在 global + project 两份 config 文档同时列出(不同 options)的去重语义。 - 未知窗口模型(window=0)的实际行为。
- catalog 不可用时窗口头缺失对压缩触发的影响。
- opencode-acp compress 参数族与 bili compress 配置的逐项映射(参数面第一类归宿的核对)。
- update.ts 禁用机制的最小改动点(env vs CLI flag)。
- spawned bili 的 stderr/日志在 opencode 侧可见性(spawn 用什么 stdio 策略)。
- opencode 插件加载失败(setup 期 throw)在宿主的可见性——源码级半闭合:2.0.3
LoadError与 devlogError("failed to load plugin") + Effect.catch(void)均为日志行+静默继续(dev 有 TODO 接 Session.Event.Error)。fail-loud 的用户面可见性弱,开放问题 6 的前提被削弱;运行时确认日志行的实际位置(stderr/opencode log 文件)并入探针 A。 manifest.protocolVersion当前无任何消费者校验(opencode 插件根本不 fetch manifest,pi 走fetchManifest但只读tools.*)——协议门控需要补 agent 侧校验,这是插件 PR 内的既定改动项(开放问题 1 的提案依赖它)。闭合(探针实证):2.0.3 上ctx.tool.reload运行时生效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 面全量数据。探针文件已删除、环境已还原。
开放问题(未决张力)
本轮讨论识别的七处真实张力,均未决;每条给对立面和它阻塞什么。讨论收敛后回填待决策项并逐条消解。
- 握手语义混淆:现设计(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 干活到下次重启)定性为升级流程常态。 - bili 死后自愈 vs 响亮失败:矩阵现写"请求失败(响亮)"。备选是失败请求触发 lazy 重探测+respawn、后续请求自愈、用户可能无感。取舍:便利 vs 案发现场保护——panic loop 会被 respawn 循环掩盖,故障暴露距离拉长,与 let-it-crash 原则正面冲突。折中候选:respawn 限速(如一次会话最多一次)+ 死因日志必留。
- health 探测的身份验证:裸 TCP 探活分不清"bili 没跑"和"18787 被无关进程占了"。后者会把请求改写给陌生进程,产生不可预测失败。机制已存在(见 manifest 契约节):探测 = GET manifest + 验应答
proxy: "billion-context"身份字段(fetchProxyVersion就是这个探针的现成实现,补一个 proxy 字段断言即可)。探测实现直接复用它,固定端口决策的安全性前提成立。剩余讨论点收敛为:探测时机(仅启动期 vs 每次失败请求后重探)。 - kill switch 的两个使用场景:
options.enabled: false(jsonc/yadm)适合"我不想用了"的持久决定,但要改配置+重启;文件制适合"bili 在发疯,三十秒内给我停"(touch 生效,若插件每请求查文件存在性)。两个场景都真实存在,也许都要——但那是两个状态源,与最小复杂度打架。 - 单文件双模式是 repo 结构异类:其他 agent 插件都是"一种宿主接入方式一个文件",opencode.js 若同时服务 launcher 注入(env 在)和 npm 加载(env 不在),行为判据藏在运行时 env 里——排查"为什么 spawn 了/为什么没 spawn"要翻环境变量。独立入口让行为静态可判,代价是 exports 指向与 launcher 注入路径联动改。异类性及其理由要在 issue 里向 owner 摆开。
- options 校验的失败哲学:
options.port给了"18787x"或负数:启动期 fail-loud(插件加载 throw)还是 fallback 默认值+stderr 告警。fail-loud 符合故障暴露原则,但前提是"插件加载失败在 opencode 宿主里可见"先被验证(见验证项 19)——若加载失败静默退化成直连,fail-loud 反而制造最坏的静默。 - 第三方压缩插件同装的处置(评审新增,本用户真实场景):opencode-acp 自禁用条件在 local 模式全不触发,同装即双 owner 抢同一段历史(见单 owner 节)。候选通道:(a) 进程内写
BILLION_CONTEXT_PROXY骗其自禁——自伤:该 env 是本插件自己的 launcher 判别器,共存节语义会被误判;(b) 检测到其安装时启动告警 + 文档声明互斥;(c) URL 改写发生后再禁它(太晚,它已经上过手)。未见干净通道,issue 里值得问 owner(他同时维护两个项目,互斥语义应由他定)。
待决策项
原稿部分项在 npm 载体下消解,标注如下;新决策按依赖关系排序:
- 插件入口形态:仓库内单文件双模式(
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 表态。 - 部署载体 A/B/C(见部署载体与命名节)——owner 裁决,A 为倾向。
宿主 auto-compaction 禁用已闭合:2.0.3 落方案 2(用户 jsonc 一行compaction.auto: false,yadm 同步),方案 3 作退化兜底;dev/未来经 config hook 自动接管(探测到该面才启用,不硬依赖)。- kill switch 通道:
options.enabled(倾向,yadm 同步)vs 稳定目录文件(无需改 jsonc 即可停)。 - 固定端口 18787 +
options.port覆盖(倾向直接定,除非实测冲突)。 - update.ts 禁用机制:env 标记 vs CLI flag。
- 双模式共存按 env 判别做,还是更简单(直接要求二选一)。
- 插件 inert 的可见信号做到什么程度。
- bili 侧 feature gap 的移植优先级:
contextLimitFallback/protectTags/qualityGate/ 项目层配置,先做哪个(contextLimitFallback建议最先,它堵住的是未知窗口模型的安全网缺口)。 - 开放问题节的七条张力(握手语义 / 自愈 / 探测身份 / 杀开关双场景 / 入口形态 / 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 的对外投影):
- 形态提案:
"plugins": ["billion-context"]+exports["./server"](附 opencode 加载器源码依据)。 - 代理生命周期:机器级单例、service 解耦理由、多 server 汇流语义。
- 待 owner 验证:插件 config hook 改
compaction.auto(seam 已确认存在,剩 memoization 与读取时机两问,验证项 1)。 - 待 owner 裁决:部署载体 A/B/C(含命名);第三方压缩插件(opencode-acp)同装的互斥语义(开放问题 7)。
- 落点:
src/agent/增量(独立入口变体已在 fork 分支有半成品:opencode-local.ts+ 工厂 + 独立 id)。
独立 issue(不混进插件 PR):OpenAI context_management 零处理的透传缺口(用户当前配置不触发,残余风险)。
Activity
ranxianglei commentedon Sep 15, 2026
[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-kernel0.0.72pinned) 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:
{ 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. Thehttp.requesthook stampsx-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.proxy: "billion-context"+protocolVersion—src/plugin.ts:376-377. ReusingfetchProxyVersion+ asserting that field is a ~3-line probe.package.jsonhas noexportsmap;main: dist/index.js; andsrc/index.ts:6runsmain()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.billion-context/dist/*imports anywhere in the repo → an explicit-enumexportsmap breaks nothing here (cross-repo downstream still needs a check before we seal — see Q1).tsup.config.tsalready lists each agent file as its own entry → addingsrc/agent/opencode-local.tsis 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) injectingBILLION_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-acpinto 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 importsbillion-context/dist/*bare, so this is safe internally. Pre-flight before merging: confirm no downstream project (across repos) does a barebillion-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 unverifiedresolvePluginIdsame-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 sketchescreateOpencodePlugin; extend it so bothopencode.tsandopencode-local.tscall it. DRY without coupling the two deployment modes' behavior.Q3 — Tool registration source: keep embedded
V2_BILI_TOOLSfor 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:compress-tool.ts) built together — drift protection within one package is nil.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."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.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_PROXYto 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.tsmechanism needed. The gate exists in three forms today:--no-auto-updateflag (cli.ts:160),ACP_AUTO_UPDATE=0env / config"autoUpdate": false(config.ts:492), wired throughif (opts.autoUpdate) startAutoUpdate(...)(cli.ts:415). The spawned bili just launches with--no-auto-update. Two things worth calling out: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'sNpm.addrefresh. Confirm the spawn always passes it.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)
fetchProxyVersion+ assertproxy === "billion-context"). Add lazy re-probe-on-failed-request only if loud-fail proves too harsh in practice — avoid per-request overhead up front.options.enabled: falsefor v1 (jsonc/yadm-synced, static, clean). Note the existingBILLION_CONTEXT_PLUGIN=0env inert toggle (opencode.ts:210) already covers the emergency case;options.enabledjust extends it to jsonc. Defer the file-based 30-second stop — it's a second state source fighting minimal complexity.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):
opencode.ts; addsrc/agent/opencode-local.ts(separate tsup entry, distinct id, V2-only{id, setup}shape).options.port→ defaulthttp://127.0.0.1:18787; manifest+identity health probe; on miss spawnnode <pkgroot>/dist/index.js --port <port> --no-auto-update(detached, loopback-bound default, pkgroot fromimport.meta.url); idempotent/bili/<url>rewrite in thehttp.requesthook; env stand-down (BILLION_CONTEXT_PROXYset → local instance inert).package.jsonexports: explicit enum{ ".": "./dist/index.js", "./server": "./dist/agent/opencode-local.js" }(post downstream-import pre-flight).protocolVersionvalidation (closes verification item 20)./bili/parse + idempotency, options parsing (defaults / malformed → fallback+warn), env-discrimination branches.Phase 2 (after e2e validation):
options.enabledkill 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_managementzero-handling passthrough gap;contextLimitFallbackfeature gap (your suggested first bili-side port).What I need from you (genuine decision points)
billion-context+exports["./server"]) and approve the explicit-enum exports map — I'll run the cross-repo bare-subpath-import pre-flight before sealing.Once (1)–(3) land I'll open the issue-linked PR (
Fixes #809orPart of #809depending 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。jensenojs commentedon Sep 15, 2026
五个问题全部同意,其中两处我明确修正自己的倾向:
billion-context/dist和"billion-context/两个模式零命中(code search 索引有覆盖盲区,非绝对证明,但作为合并前检查的信号足够)。显式枚举{ ".": "./dist/index.js", "./server": "./dist/agent/opencode-local.js" }可以放心。createOpencodePlugin草稿需要扩一个id参数——现在写死了billion-context-opencode,两文件同 id 会在 launcher + npm 双加载时撞工具注册;opencode.ts和opencode-local.ts都改为调工厂,消除双文件漂移。opencode.ts:160-165)。开放问题 1 就此收敛:握手按 protocolVersion 判 + 版本差纯信息性 + agent 侧校验补进 PR(关掉验证项 20)。--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 分支接力实现,协作方式你定。ranxianglei commentedon Sep 15, 2026
[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=0kill switch、session.compaction.ended边界上报、cleanup dispose。重构会把这些共享 V2 逻辑抽进src/agent/opencode-v2.ts的工厂(带id参数),opencode.ts(launcher)和新的opencode-local.ts都调它——目标是该测试全绿不动。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 以保持范围紧。--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)我随后单独提。jensenojs commentedon Sep 15, 2026
收到——由你开 PR,我不另开分支。27 行草稿的思路(工厂 +
id参数 + 幂等改写)你随意取用,对真实代码库从零重建的确 provenance 更干净。url改写到 wire 这个点你提得准:现有实证只覆盖 headers(opencode.ts:140-141),我的草稿也是基于"url 在类型里可写"的假设——e2e 第一个盖住它是对的顺序。如果真有 build 不吃http.request的 url 变更,model.request的可变 baseURL 是现成 fallback(探针已实证其到 wire)。等你的 PR 链接。
ranxianglei commentedon Sep 15, 2026
按收敛后的方案从 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(idbillion-context-opencode-local,V2-only{id, setup})。createOpencodeV2Setup(config)(新文件src/agent/opencode-v2.ts);launcher(opencode.ts)与 npm 入口都调它——两文件不再漂移,双加载时 id 不同不撞工具注册。options.port→ 默认http://127.0.0.1:18787;先探 manifest 并断言proxy === "billion-context"(占位的外来服务响亮拒绝,不静默采用);连不上才 spawnnode <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=0kill switch → inert。acp 互斥走文档 + 启动告警(v1)。{ ".": "./dist/index.js", "./server": "./dist/agent/opencode-local.js" };tsup 加入口;protocolVersion 校验补进 agent 侧(握手按 protocolVersion 判、版本差纯信息性)。Pre-flight(本机跑过): typecheck 干净;
node --test1618 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):
e.request.url;opencode.ts的注释只证明了 headers 到 wire,url 这个 typed writable property 到没到 wire 在这边无法验证。若没到,fallback 改model.request的baseURL(延后,不进 v1)。server.ts)收敛,我是读代码确认的,没做 live 双 spawn。建议 smoke:真实 OpenCode 2.x 指到 Responses-compatible upstream(经
options.port),确认首请求改写 + 一次 compress round-trip,再加 kill-switch /BILLION_CONTEXT_PROXYstand-down 各一次。Phase 2(本 PR 明确排除):
options.enabledtoggle、inert 状态可见性、manifest reload。麻烦 review;CI 是 manual-dispatch(需 repo secrets),你那边能跑就跑下 e2e。合并由你来(Agents 不能 merge)。
ranxianglei commentedon Sep 15, 2026
链接来了(我上一条和你这条撞车了,重发一次):
**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 入口都调它。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 --test1618 pass / 0 fail / 2 skip(skip 既有)· tsup build 产出dist/agent/opencode-local.js。麻烦 review;CI manual-dispatch 需 repo secrets,你那边能跑就跑下真实 upstream 的 url-mutation + spawn 收敛两项。合并由你来。
jensenojs commentedon Sep 15, 2026
别急, 我试用了一下搞出 Session failedx
Attempted to assign to readonly property., 了, 所有的session都用不了了... 我还在看是怎么回事
ranxianglei commentedon Sep 15, 2026
link #513
ranxianglei commentedon Sep 15, 2026
收到,这个严重,我马上查。先给你立即恢复的办法(不用等修复):
临时解锁(任选其一)→ 重启 opencode:
opencode.json的plugin/plugins数组里的"billion-context"删掉;或BILLION_CONTEXT_PLUGIN=0(kill switch)这样插件不注册任何 hook,session 立刻能回来。
为精准定位,麻烦给两个信息:
opencode.json里plugins:["billion-context"](npm 入口),还是bili opencodelauncher?opencode 版本号。我这边在读你链的 #513,同时在审新入口 request-hook 的属性改写路径——最可疑的是
http.requesthook 里对 request 字段的赋值:若 OpenCode 2.x 在运行时冻结了该对象(类型上可写、运行时只读),赋值就会炸,且每次请求都炸 → 所有 session 挂。稍后给根因 + 修复。jensenojs commentedon Sep 15, 2026
补充一次真实宿主复现结果(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 propertyFailed to drain Session位置是
dist/agent/opencode-local.js的e.request.url = next。OpenCode 2.0.3 的
http.request事件传入 WHATWGRequest。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。我这次没有改代码。jensenojs commentedon Sep 15, 2026
补充诊断过程和根因边界(对应本 issue 之前的“request 属性只读”怀疑,以及 PR #810 body 中尚未完成的真实 E2E 验证):
诊断过程
v2.0.3,插件通过~/.config/opencode/plugins/bili-pkg/index.js自动加载。会话界面显示Session failed,日志同时出现Failed to drain Session。dist/agent/opencode-local.js的httpRequestHook。失败语句对应源码中的e.request.url = next。http.request事件携带的是 WHATWGRequest。事件里的request引用可以被整体替换;WHATWGRequest实例的url属性由对象本身只读提供。当前实现把“类型接口里可访问的 url 字段”当成了“运行时可以写入的 url 属性”,两者约束不一致。/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。bili-pkg目录移出 OpenCode 自动发现目录,等待 watcher 重载,再执行真实请求opencode run --format json --auto "只回复 OK"。命令退出码为 0,返回OK。这一步把“插件 hook 导致会话失败”与 OpenCode 本身故障区分开。根因关系
当前这次“所有 session 都失败”的直接根因是:
httpRequestHook在请求发送前执行e.request.url = next;运行时对象是 WHATWGRequest,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。证据范围
这次实测证明了三件事:
这次实测没有覆盖其他 OpenCode 版本、其他宿主构建,也没有把“修复后 URL 是否能到达上游”作为已验证事实。这里仅记录故障链和证据边界,不提出根因修复方案。
ranxianglei commentedon Sep 15, 2026
你的两条诊断完全正确,我这边独立复现也收敛到同一根因,谢谢这么扎实的实测。逐条确认 + 修复方向:
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.requestseam 内,不需要动globalThis.fetch。另外我会把整个 hook 包进防御性 try/catch:插件绝不能把宿主 session 打挂——任何异常都降级为直通(不压缩),绝不 reject 出去。Bug 2(spawn 用错可执行文件,独立链):确认
process.execPath在原生 opencode 二进制下不是 Node。修复=解析真实 Node runtime:先查process.execPathbasename 是否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。等你更新后我给具体复测步骤。fix(opencode): route via request-reference swap + resolve real Node r…
ranxianglei commentedon Sep 15, 2026
两个 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.execPathbasename 是否node,否则沿PATH找node/node.exe,再留BILLION_CONTEXT_NODE环境变量兜底;找不到就响亮报错 + inert(不再静默轮询超时)。为什么之前没抓到:单测 mock 用的是普通对象
{url, headers}(.url可写),掩盖了 WHATWG Request 的只读约束。现在 mock 换成真实Request,并加了回归测试钉死「必须换引用、不能写.url」,另加findNodeRuntime四个分支测试。本机验证:typecheck 干净 ·
node --test1623 pass / 0 fail / 2 skip · tsup build 产出dist/agent/opencode-local.js· 构建产物 smoke:findNodeRuntime()→真实 node、spawn args 指向dist/index.js、rewrite 幂等成立。你复测的步骤(关键在最后两点):
git checkout 2026-09-15_opencode-npm-plugin && npm ci && npm run build,再按原路径部署。<包根>/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。BILLION_CONTEXT_NODE=/绝对路径/node。仍待你确认的最后一步:「换引用后的请求是否真的被 opencode 发出去、且代理能从
/bili/解出上游」这条完整回路,我这边靠你的实证(引用可替换)+ 单测回归覆盖,但真实宿主端到端还需你这次复测盖章。麻烦跑一下,有问题贴日志给我。jensenojs commentedon Sep 15, 2026
你确保你这里的坑在 #513 上不会再犯就好了,
84 remaining items
Merge pull request #850 from ranxianglei/2026-09-15_opencode-native-p…
ranxianglei commentedon Sep 17, 2026
已经合并了众多opencodev2 等发版本 本issue关闭
fix(plugin-install): guard opencode non-object mcp in install/remove/…
fix: attach mode rewrites model URLs like spawn mode (#941 review)
feat(zcode): route:"all" default with per-entry exemptions (ranxiangl…
feat: opencode 2.x no-launcher npm-plugin deployment
fix(opencode): route via request-reference swap + resolve real Node r…
refactor(agent): promote findNodeRuntime to shared for ranxianglei#513 …
fix(opencode): harden in-host proxy spawn + fail-closed protocol gate
fix(launcher): handle async spawn 'error' in ensureProxyRunning (ranx…
refactor(zcode): reuse the shared #809 loopback predicate in the buil…
fix(fastpath): stamp + learn on the direct-to-proxy self branch - dsh…