Skip to content

feat(#1958): expose conflicting pre-routed /bili/ opencode configs at install and runtime - #1972

Closed
ranxianglei wants to merge 3 commits into
2026-10-03_opencode-v2-routed-proxybasefrom
2026-10-03_opencode-v2-conflict-detection
Closed

ranxianglei wants to merge 3 commits into
2026-10-03_opencode-v2-routed-proxybasefrom
2026-10-03_opencode-v2-conflict-detection

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Stacked on #1959 (head 2026-10-03_opencode-v2-routed-proxybase). Closes #1958 once both land — #1959 fixes the missing-stamp defect; this PR implements the maintainer-directed conflict exposure for the same root configuration.

What

"Native plugin + hand-written /bili/ provider baseURL" is a conflicting configuration: two mutually exclusive access paths claim routing ownership of the same requests. It used to be silently absorbed (#1958: missing plugin identity headers → proxy-mode degradation). Now it is exposed loudly:

  1. Install — bili plugin install opencode scans the real effective config surface (global candidates in opencode's own merge order + OPENCODE_CONFIG + cwd project layer) and refuses with exit code 1 when any provider baseURL carries a /bili/ prefix, listing every hit as file/provider/baseURL plus the two-way fix-it guide. Nothing is written before the check.
  2. Runtime — the V2 native route warns (console.error) once per (session, origin) on a pre-routed model URL with the same guide. An explicit pin of the SAME origin (BILLION_CONTEXT_PROXY pointing at the proxy the URLs already ride) is the supported attach posture (bug: dsh-native — attach 目标瞬时不可达 → 回退 spawn 第二实例:routed baseURL 下工具/模型通道必然脑裂(工具 404 → preflight 502 → 会话不可自愈) #1365/fix: never spawn over a pinned model channel when the attach target is down (#1365) #1370 pinned-channel semantics preserved) and stays silent.
  3. Docs — CLIENTS.md / CONFIGURATION.md (en+zh) now state the three mutually exclusive OpenCode paths and the conflict behavior.

Behavior changes (old → new)

Notes

ework-agent added 2 commits October 3, 2026 15:42
… install and runtime

"Native plugin + hand-written /bili/ provider baseURL" is a conflicting
configuration: two mutually exclusive access paths claiming routing
ownership of the same requests. It used to be silently absorbed (missing
plugin identity, proxy-mode degradation, #1958/#1959). Now it is exposed:

- install: bili plugin install opencode scans the real effective config
  surface (global candidates in opencode's own merge order + OPENCODE_CONFIG
  + cwd project layer) and refuses with exit code 1 when any provider
  baseURL carries a /bili/ prefix — listing file/provider/baseURL per hit
  plus the two-way fix-it guide. Effective-surface semantics mean an
  overridden stale entry never false-positives. Nothing is written before
  the check, so the failure is clean.
- runtime: the V2 native route warns (console.error) once per
  (session, origin) on a pre-routed model URL with the same guide. An
  explicit pin of the SAME origin (BILLION_CONTEXT_PROXY pointing at the
  proxy the URLs already ride) is the supported attach posture and stays
  silent — compared against the env (URL.origin-normalized), not
  state.origin, because attach arming does not freeze state.origin
  synchronously. Stamping still binds to the baked origin (#1959 fallback);
  pinned-channel semantics (#1365/#1370) are untouched.
The launcher / native-plugin / pure-proxy paths each own routing of the
same requests; exactly one may be active per host instance. A hand-written
/bili/ provider baseURL is the pure-proxy path's marker — writing it while
the native plugin is installed is a conflicting configuration that is now
exposed: install refuses (exit 1, listing file/provider/baseURL), and the
runtime warns once per session with the same fix-it guide. The supported
exception is an explicit pin of the same origin (BILLION_CONTEXT_PROXY
pointing at the proxy the URLs already ride), which stays silent.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到,按 [PR] 流程处理(不重做工作):拉分支核对代码 + CI 状态 + 回归审查。

已核实:

审查中发现一个本 PR 引入的测试确定性问题,正在 PR 分支上直接修:findBiliPrefixedOpencodeBaseURLs(process.env, …) 让 pluginInstall("opencode") 开始依赖机器真实配置面——tests/plugin-agent.test.ts 里 4 处 opencode 安装测试只隔离了 OPENCODE_CONFIG 没隔离 XDG_CONFIG_HOME,在真实 opencode 配置带预烤 /bili/ baseURL 的机器上(恰是本 PR 目标用户群)这些测试会因环境失败(§7.2 禁止环境运气)。补一行级隔离后重跑验证,随后给七问结论。

…s exposed by the #1972 scan

The new install-time /bili/ scan reads the real effective config surface
(process.env + cwd), so pluginInstall("opencode") now depends on the
ambient global opencode config. Four test sites in this file isolated
OPENCODE_CONFIG but not XDG_CONFIG_HOME, so on any machine whose real
~/.config/opencode carries pre-routed /bili/ provider baseURLs (exactly
the user group #1958 targets) the suites fail for environmental reasons
(§7.2: tests must be deterministic). Pin XDG_CONFIG_HOME into the fake
home at all four sites.

Verified: with a poisoned ambient XDG (pre-routed baseURL present) the
suite went from 6 failures to 62/62 green; clean environments stay green.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 完成 — 分支已核对、代码逐行审过、定向验证全绿、CI 状态已确认。审查中发现并已在 PR 分支直接修复一个测试确定性问题(commit f9fdf2d1,见下)。

① 原 issue 方向关(最高优先)

维护者指令(#1958 floor 4)要求:安装时检测+评估拒绝、运行时去重警告、良性钉住不误报、module-eval seam 评估、文档写明三路径互斥、给出 (a)/(b) 分析。PR 逐条落实且方向正确:安装时选了拒绝(比警告更强,理由成立——检查点在一切写入之前,失败零副作用);module-eval 评估结论有据(V2PluginContext 只暴露模型清单,无 provider-baseURL seam,#1569);(a)/(b) 按我此前推荐的 (a) 实现并在 PR 正文注明 (b) 的 delta。#1959 遵嘱未合并,等你定夺。方向无问题。

② 回归审查(既有行为清点)

逐项审过 diff 触碰路径的既有行为:

既有行为 结论
routed URL 不二次改写、不触发 resolveLive/respawn(#1365/#1370 pinned-channel) 保持 — 新分支在 noteRoutedOrigin 后仍直接 return;#1959 测试 case 2 的零 respawn 断言在位
launcher lane(bili opencode 自烤 URL) 不受影响 — src/agent/opencode.ts:139-162 是独立的 route 回调(自己 re-bake),根本不进 createNativeRoute;即便进入,launcher 设置的 BILLION_CONTEXT_PROXY 与 baked origin 相同 → 静默
V1 lane 对预烤 URL 的处理 不在范围,正确 — V1 config hook 会 unwrap/re-wrap 陈旧前缀(opencode-native.ts:443-466)+ fetch patch 自行盖章,矛盾姿态被自愈,无需暴露层
非模型 /bili/… 与控制请求(/v1/models、/__bili/health) 保持不打标不绑定 — 警告与绑定同门(routedBiliModelUrl 只匹配 model-API 形状),#1959 测试 case 4 钉住
opencode 安装(干净配置) 不变 — 检查仅在命中时 throw;89 例既有安装测试本地全绿
master 漂移(分支 base 之后 7 个 merge) 无交互 — 唯一交集文件 native-intercept.ts 是 #1957 的 createLiveOriginResolver 健康代际改动,routed 分支在其调用之前 return,语义不相交;GitHub 报 clean

有意行为变更(old → new,PR 已披露,我复核成立):

  • bili plugin install opencode 遇预烤 /bili/ 配置:成功并存 → exit 1 拒绝、零写入。连带后果:已处于该矛盾姿态的用户重跑 install(含升级意图)也会被拒,需先修配置或 remove 插件——这是"拒绝"设计的必然结果,可接受(重跑安装等于再次确认错误姿态)。
  • V2 native route 见预烤模型 URL:静默 → 每 (session, origin) 一次 console.error + 二选一指引;良性同 origin 显式钉住保持静默。wire 字节不变(URL 原样、body/Authorization 不动),仅多请求头(fix(#1958): bind V2 hook proxyBase to the baked origin on already-routed model requests #1959 范畴)。

③ 代码审查(主关)

  • 良性豁免比对对象选对了:比 env 而非 state.origin——attach arming 不同步冻结 state.origin(opencode-native.ts:272-275 注释明确),用 state 比会对良性钉住误报;env 在 attach arm 时同步写入并在所有恢复路径锁步更新。两侧都过 new URL().origin,尾斜杠/默认端口天然折叠(测试 case 覆盖 :80 折叠)。
  • 扫描器合并语义与 readOpencodeConfigRoot(client-config.ts:1282)逐项一致:同文件序(config.json→opencode.json→opencode.jsonc)、同 JSONC 回退解析、OPENCODE_CONFIG 叠加而非替换、项目层按 provider id 优先。"last declarer wins" 近似对深合并是忠实的(后续文件未声明 baseURL 时保留前值);唯一偏差是后续文件显式写 "baseURL": "" 清空的情形不被建模——方向安全(只会 false-refusal 且消息带 file/provider/baseURL 可自行核实),属刻意近似,记录为设计边界,不拦。
  • 去重键 ${sessionID ?? "_"}\u0000${baked} 分隔符防碰撞、Set 仅进程内存、量级可忽略;console.error 用于宿主进程内插件代码与全部 src/agent/* 惯例一致(logger 规则只约束 server-side)。
  • 拒绝消息可行动:逐条 file/provider/baseURL + 二选一指引 + "Nothing was written";错误经 cli.ts:479-481 到 stderr + exit 1,已验证。

④ 测试有效性

8 例新测试都是真测试:驱动真实 createNativeRoute/pluginInstall/扫描器(非 mock),精确计数断言(3 个不同 (session,origin) 恰好 3 次警告、良性钉住恰好 0 次)、配置文件字节级前后对比钉死"零写入"、hermetic(temp XDG + git-root cwd + BILI_CLIENT_BIN pin)。bug 回归时抓得住:重复刷屏、良性误报、绑定丢失、扫描器漏报/误报各有对应用例。非阻塞小缺口:sessionID === undefined 的 "_" 回退键无用例(影响极小,不提立项)。

⑤ diff 整洁度

10 文件 +512/-6,每行都与本 PR 目的相关;无空白重排、无 lockfile/生成物变动;3 个线性提交 stack 正确。干净。

审查中直接修掉的问题(commit f9fdf2d,已在 PR 分支)

新扫描让 pluginInstall("opencode") 开始读取机器真实配置面(process.env + cwd),但 tests/plugin-agent.test.ts 里 4 处 opencode 安装测试只隔离了 OPENCODE_CONFIG 没隔离 XDG_CONFIG_HOME——在真实 opencode 配置带预烤 /bili/ baseURL 的机器上(恰是本 PR 目标用户群,包括你本机)这些测试会因环境失败,违反 §7.2 确定性纪律。A/B 证据:注入毒化 XDG(含 /bili/ baseURL)后,修复前该套件 6 例失败,修复后 62/62 全绿;干净环境保持 62/62。修法:4 处 env 块各补一行 XDG_CONFIG_HOME 指向 fake home(已核实 client-config.ts 中仅 goose/opencode 读 XDG,不影响其他 agent 的安装测试)。

CI 状态与门禁说明

结构化七问

  1. 是什么问题:「原生插件 + 手写 /bili/ baseURL」是两条互斥接入路径同时认领同一批请求路由权的矛盾配置,旧系统静默消化(缺身份头 → proxy 模式退化,[Bug][OpenCode V2] 已带 /bili/ 前缀的模型请求跳过 proxyBase 初始化,缺失插件会话标记 #1958 缺陷类),矛盾本身从不被看见。
  2. 什么原因导致的:routed 分支把"URL 已带 /bili/"一律当作"别人已路由"处理,没有区分 bili 自烤(launcher)与用户手写(矛盾);安装路径从不做姿态一致性校验——缺的是暴露层,不是某条路径的 bug。
  3. 怎么修复的:分层暴露——安装时拒绝(预防,零写入检查点)+ 运行时每 (session,origin) 一次带二选一指引的警告(兜住存量/环境替换)+ 文档声明三路径互斥;盖章兜底按 (a) 保留,任何配置下行为仍然正确。(a)/(b) 待你定夺,(b) 的 delta 很小且已注明。
  4. 是否有回归问题:无意外回归。两处有意变更已披露(安装成功→拒绝;静默→一次警告),pinned-channel/launcher/V1/非模型路径逐项核实保持;master 漂移无交互;发现并修掉一处本 PR 引入的测试环境依赖(XDG 隔离,A/B 验证)。
  5. 是否破坏缓存:不涉及——缓存/重试/游标/去重键均未触碰;警告去重为进程内 Set。
  6. 是否改了设计方向:无架构转向;机制从"静默兼容"转为"暴露矛盾+引导修复",即本次 owner 定向本身;检测层纯增量。
  7. 是否引入了新的配置:没有——无新 env/config 字段/CLI flag;BILLION_CONTEXT_PROXY 为既有变量,此处只读比较。

判定

可合(人工执行):#1972 代码/测试/文档均达标,CI 在 PR 层面能跑的全绿,全矩阵随合入 master 的 push 把关;合并前先给 (a)/(b) 定夺(当前实现 = a)。合并顺序:先 #1959 再 #1972,或直接合 #1972(带入两 PR 全部提交)皆可。

@ranxianglei

Copy link
Copy Markdown
Owner Author

关闭:两处调整——(1) 安装时 exit 1 拒绝改为不做安装闸门:扫描器误判会让用户永远装不上,而安装闸门只拦"先有前缀后装插件"一种顺序,先装后改配置本来只能靠运行时兜底,锁死风险不对称;(2) 盖章兜底也不保留(owner: 不偷偷兼容)。运行时警告(去重/良性钉住豁免/env 比对)由 #2020 原样继承,扫描器与安装拒绝不再要。感谢完整实现,警告逻辑与测试模式被 #2020 复用。

@ranxianglei ranxianglei closed this Oct 4, 2026
yingzhongshuoqi pushed a commit to yingzhongshuoqi/billion-context that referenced this pull request Oct 4, 2026
…e config — expose, don't absorb, don't gate install

Maintainer direction change on ranxianglei#1958: the 'native plugin + hand-written
/bili/ provider baseURL' combo is a conflicting configuration (two access
paths claiming routing ownership of the same requests). The correction is
a loud runtime warning — not silent compat (no stamping/rewrite, the
request stays on the plain-proxy path it encodes) and not an install-time
refusal (a scanner false positive would permanently block installs).

- src/agent/opencode-native.ts (createNativeRoute): on a pre-routed model
  URL, warn once per (session, origin) unless BILLION_CONTEXT_PROXY pins
  the SAME origin (supported attach posture — compared via URL.origin so
  trailing-slash/default-port spellings fold; env, not state.origin,
  because attach arming does not freeze state.origin synchronously).
  No behavior change to the request itself: ranxianglei#1365 pinned-channel
  recording (noteRoutedOrigin) and the isModelApiUrl fall-through are
  untouched; s.proxyBase stays unset for pre-routed URLs.
- tests/issue1958-routed-warn.test.ts: 4 cases — dedup per (session,
  origin) + no stamping; benign pin silent incl. port folding; mismatched
  pin warns; non-model /bili/ paths and /__bili/health never warn.
- CLIENTS(.zh-CN).md / CONFIGURATION(.zh-CN).md: the three OpenCode access
  paths are mutually exclusive; runtime warning + fix-it guide documented.

Supersedes ranxianglei#1959 (silent stamping) and ranxianglei#1972 (install refusal + stamping).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant