diff --git a/CLIENTS.md b/CLIENTS.md index 366f511ca4..4ad3a7fe14 100644 --- a/CLIENTS.md +++ b/CLIENTS.md @@ -418,6 +418,8 @@ on `@opencode/cli` 2.0.3 (V1 lane: 1.14.46 and 1.18.31). | Native (no launcher) | `bili plugin install opencode` | self-spawning plugin in your real config; start `opencode` as usual | | Pure proxy (fallback) | baseURL `/bili/` prefix | no plugin — wire-level tool injection | +These paths are **mutually exclusive** — each one owns routing of the same requests, so 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** (#1958): the runtime warns once per session (deduplicated per origin) with a fix-it guide — remove the prefix or remove the plugin — and the requests stay on the plain-proxy path they encode (no plugin session markers). 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. + ### Launcher — `bili opencode` HTTPS rides cert-MITM, HTTP a temp `opencode.json` clone with `/bili/` @@ -519,6 +521,9 @@ Point the provider baseURL at the proxy like any other client: Note: 2.0 AI-SDK providers require an `apiKey` field even for local endpoints that never check it — set any non-empty value. +This path means **no plugin**: if the native plugin is also installed, the +runtime warns once per session — pick one path per provider (#1958). + ### Status: `/acp` and `acp_status` The `/acp` panel is session-bound in all modes, and the `acp_status` tool is diff --git a/CLIENTS.zh-CN.md b/CLIENTS.zh-CN.md index 344eeaea75..45f78cdfa4 100644 --- a/CLIENTS.zh-CN.md +++ b/CLIENTS.zh-CN.md @@ -125,6 +125,8 @@ bili 只压缩路径匹配已知 wire 协议(`/chat/completions`、`/llm_raw_cha | 原生(免启动器) | `bili plugin install opencode` | 自拉起插件写进真实配置;照常启动 `opencode` | | 纯代理(兜底) | baseURL 加 `/bili/` 前缀 | 无插件 —— wire 级工具注入 | +这三条路径**互斥**——每条都拥有同一批请求的路由权,每个宿主实例只能激活其中一条。手写的 `/bili/` provider baseURL 是纯代理路径的标记;在原生插件已装的情况下写它就是**矛盾配置**(#1958):运行时会每会话警告一次(按 origin 去重)并附修复指引——去掉前缀或卸掉插件——请求则留在其编码的纯代理路径上(无插件会话标记)。受支持的例外是对**同一** origin 的显式钉住——`BILLION_CONTEXT_PROXY` 指向 URL 已经在走的那个代理——保持静默。 + ### 启动器 —— `bili opencode` HTTPS 走证书 MITM,HTTP 走临时 `opencode.json` 副本(`/bili/` 改写;JSONC 注释照单接受,合并方式与 opencode 自身一致;相对本地插件路径在副本里重新锚定为绝对路径 —— opencode 按声明所在配置文件目录解析,#826)。宿主代次用 `--version` 探测(探测失败默认按 1.x):**2.x** 宿主注入内置 V2 插件(`dist/agent/opencode.js`),以临时包装目录形式给出(目录入口 `index.js` 再 re-export 插件文件 —— 2.x 拒绝配置 `plugin` 数组里的裸文件路径);**1.x** 宿主直接给裸文件路径。 @@ -176,6 +178,8 @@ OpenAI/ChatGPT 凭据。 注意:2.0 AI-SDK provider 即使本地端点从不校验也要求 `apiKey` 字段 —— 随便填个非空值。 +这条路径意味着**无插件**:若同时装了原生插件,运行时每会话警告一次——每个 provider 只选一条路径(#1958)。 + ### 状态:`/acp` 与 `acp_status` `/acp` 面板在所有模式下都绑定当前会话,`acp_status` 工具是其宿主内等价手段。在命令编辑器支持新增条目的宿主(2.0.x 稳定版,`editor.add`)上,V2 插件额外注册 `/acp` 斜杠命令 —— 以合成非模型消息渲染,面板优先(与 `acp_status` 工具一致);旧形状上该注册保持惰性。注意 `opencode run` 模式完全不派发斜杠命令(它们会透传给模型)—— 请用 TUI。 diff --git a/CONFIGURATION.md b/CONFIGURATION.md index f73bced02d..78ade6746c 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -960,6 +960,8 @@ Clients you configure with an **API key** (not a login) let you change the upstr "baseURL": "http://localhost:8787/bili/https://open.bigmodel.cn/api/coding/paas/v4" ``` +**OpenCode note.** This is the **no-plugin** path for OpenCode. If the native plugin is also installed over such a config, the runtime warns once per session with a fix-it guide (remove the prefix or remove the plugin); the requests themselves keep riding the plain-proxy path. The three mutually exclusive OpenCode access paths are documented in [CLIENTS.md](CLIENTS.md#opencode). + **Codex (API key)** — edit `~/.codex/config.toml`, change the provider's `base_url`: ```toml diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index 1390d1673e..744dd20989 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -935,6 +935,8 @@ launcher 命令里 `--` 之后的参数原样透传给客户端(`bili pi -- pr "baseURL": "http://localhost:8787/bili/https://open.bigmodel.cn/api/coding/paas/v4" ``` +**OpenCode 注意。**这是 OpenCode 的**无插件**路径。若在此类配置之上还装了原生插件,运行时每会话警告一次并附修复指引(去前缀或卸插件);请求本身继续走纯代理路径。三条互斥的 OpenCode 接入路径见 [CLIENTS.zh-CN.md](CLIENTS.zh-CN.md#opencode)。 + **Codex(API key 模式)** —— 编辑 `~/.codex/config.toml`,改 provider 的 `base_url`: ```toml diff --git a/src/agent/opencode-native.ts b/src/agent/opencode-native.ts index de6c71dd32..97663963d2 100644 --- a/src/agent/opencode-native.ts +++ b/src/agent/opencode-native.ts @@ -108,12 +108,43 @@ export type OpencodeNativeRouteDeps = LiveOriginResolverDeps; export function createNativeRoute(state: NativeInterceptState, deps: OpencodeNativeRouteDeps = {}): (e: V2HttpRequestEvent, s: V2State) => Promise { const resolveLive = createLiveOriginResolver(state, deps); let warned = false; + // #1958: conflicting pre-routed config is exposed once per (session, origin). + const conflictWarned = new Set(); return async (e, s) => { const url = typeof e.request?.url === "string" ? e.request.url : undefined; if (url === undefined) return; // #1365: routed URLs are skipped by isModelApiUrl by design — record // the pinned model channel before that gate so attach recovery can see it. - if (routedBiliModelUrl(url) !== undefined) noteRoutedOrigin(state, url); + if (routedBiliModelUrl(url) !== undefined) { + noteRoutedOrigin(state, url); + // #1958: a hand-written /bili/ prefix while the native plugin is + // active means two access paths claiming routing ownership of the + // same request — a conflicting configuration, not something the + // plugin should silently absorb. Expose it loudly, once per + // session+origin, with a fix-it guide, and leave the request on + // the plain-proxy path it already encodes: no rewrite, no plugin + // stamping. An explicit pin of THIS origin (BILLION_CONTEXT_PROXY + // pointing at the proxy the URLs already ride) is the supported + // attach posture — silent. Compared against the env, NOT + // state.origin: attach arming does not freeze state.origin + // synchronously, so early requests would false-warn against a + // benign pin. + const baked = new URL(url).origin; + const declaredRaw = process.env.BILLION_CONTEXT_PROXY; + let declared: string | undefined; + try { + declared = declaredRaw !== undefined && declaredRaw !== "" ? new URL(declaredRaw).origin : undefined; + } catch { + declared = undefined; + } + if (declared !== baked) { + const key = `${String(e.sessionID ?? "_")}\u0000${baked}`; + if (!conflictWarned.has(key)) { + conflictWarned.add(key); + console.error(`bili-native-opencode: conflicting configuration — model requests already carry a /bili/ prefix (origin ${baked}) while the native plugin is active. The plugin routes model requests itself; hand-written /bili/ prefixes belong to the no-plugin plain-proxy path. Pick ONE: (1) remove the /bili/ prefix from your opencode provider baseURL(s) so the plugin routes them, or (2) run \`bili plugin remove opencode\` and keep the pre-routed URLs. Until resolved, these requests continue to ${baked} in plain proxy mode WITHOUT the plugin session markers.`); + } + } + } if (!isModelApiUrl(url)) return; const target = await resolveLive(); diff --git a/tests/issue1958-routed-warn.test.ts b/tests/issue1958-routed-warn.test.ts new file mode 100644 index 0000000000..4325289173 --- /dev/null +++ b/tests/issue1958-routed-warn.test.ts @@ -0,0 +1,136 @@ +// #1958 (direction change): "native plugin + hand-written /bili/ provider +// baseURL" is a CONFLICTING configuration — two mutually exclusive access +// paths claiming routing ownership of the same requests. Per maintainer +// decision it must be EXPOSED, not silently absorbed, and NOT auto-repaired: +// - runtime: the V2 native route warns once per (session, origin) with a +// fix-it guide; an explicit pin of the SAME origin +// (BILLION_CONTEXT_PROXY pointing at the proxy the URLs already ride) +// stays silent; +// - the request itself is left on the plain-proxy path it already encodes: +// no rewrite, no plugin stamping (s.proxyBase stays unset); +// - install: intentionally NOT gated — warning is the correction, and a +// refusal could permanently block installs on scanner false positives. +import test from "node:test"; +import assert from "node:assert/strict"; + +// Module-level guards read env while opencode-native EVALUATES; static imports +// hoist above any assignment, so set the marker first and import dynamically. +process.env.NODE_TEST_CONTEXT = "1"; + +import type { NativeInterceptState } from "../src/agent/native-intercept.ts"; +import type { V2HttpRequestEvent, V2State } from "../src/agent/opencode-v2.ts"; + +const { createNativeRoute } = await import("../src/agent/opencode-native.ts"); + +const BAKED = "http://127.0.0.1:9999"; +const ROUTED_URL = `${BAKED}/bili/http://example.invalid/v1/chat/completions`; + +function routedEvent(sessionID: string | undefined, url = ROUTED_URL): V2HttpRequestEvent { + const e: V2HttpRequestEvent = { request: new Request(url, { method: "POST" }) }; + if (sessionID !== undefined) e.sessionID = sessionID; + return e; +} + +async function capturedErrors(fn: () => Promise): Promise { + const lines: string[] = []; + const orig = console.error; + console.error = (...args: unknown[]) => { lines.push(args.map(String).join(" ")); }; + try { + await fn(); + } finally { + console.error = orig; + } + return lines.filter((l) => l.includes("conflicting configuration")); +} + +function spawnState(): NativeInterceptState { + return { origin: "http://127.0.0.1:7777", ready: Promise.resolve("http://127.0.0.1:7777") }; +} + +test("#1958: conflicting pre-routed URL warns once per (session, origin), request untouched", async () => { + const prev = process.env.BILLION_CONTEXT_PROXY; + delete process.env.BILLION_CONTEXT_PROXY; + try { + const route = createNativeRoute(spawnState()); + const s: V2State = {}; + const otherUrl = `${BAKED.replace(":9999", ":9998")}/bili/http://other.invalid/v1/chat/completions`; + const run = async (): Promise => { + await route(routedEvent("ses_a"), s); + assert.equal(s.proxyBase, undefined, "no silent compat: the pre-routed path is NOT stamped"); + await route(routedEvent("ses_a"), s); + await route(routedEvent("ses_b"), s); + await route(routedEvent("ses_a", otherUrl), s); + }; + const lines = await capturedErrors(run); + assert.equal(lines.length, 3, "one per distinct (session, origin) pair"); + assert.match(lines[0], new RegExp(BAKED)); + assert.match(lines[0], /pick one/i); + assert.equal(s.proxyBase, undefined, "the plugin never claims routing of pre-routed URLs"); + } finally { + if (prev === undefined) delete process.env.BILLION_CONTEXT_PROXY; + else process.env.BILLION_CONTEXT_PROXY = prev; + } +}); + +test("#1958: an explicit pin of the SAME origin is the supported attach posture — silent", async () => { + const prev = process.env.BILLION_CONTEXT_PROXY; + process.env.BILLION_CONTEXT_PROXY = BAKED; + try { + const state: NativeInterceptState = { origin: BAKED, ready: Promise.resolve(BAKED), attach: true }; + const s: V2State = {}; + const lines = await capturedErrors(async () => { + await createNativeRoute(state)(routedEvent("ses_pin"), s); + await createNativeRoute(state)(routedEvent("ses_pin"), s); + }); + assert.equal(lines.length, 0, "benign explicit pin must not warn"); + // Trailing slash / default-port spelling differences normalize away. + process.env.BILLION_CONTEXT_PROXY = `${BAKED}/`; + const s2: V2State = {}; + const lines2 = await capturedErrors(async () => { + await createNativeRoute(state)(routedEvent("ses_pin"), s2); + }); + assert.equal(lines2.length, 0); + process.env.BILLION_CONTEXT_PROXY = "http://127.0.0.1:80"; + const s3: V2State = {}; + const lines3 = await capturedErrors(async () => { + await createNativeRoute({ origin: "http://127.0.0.1", ready: Promise.resolve("http://127.0.0.1") })(routedEvent("ses_pin", "http://127.0.0.1:80/bili/http://example.invalid/v1/chat/completions"), s3); + }); + assert.equal(lines3.length, 0, "default ports fold in URL.origin comparison"); + } finally { + if (prev === undefined) delete process.env.BILLION_CONTEXT_PROXY; + else process.env.BILLION_CONTEXT_PROXY = prev; + } +}); + +test("#1958: attach to a DIFFERENT origin than the baked URL warns (real conflict)", async () => { + const prev = process.env.BILLION_CONTEXT_PROXY; + process.env.BILLION_CONTEXT_PROXY = "http://127.0.0.1:7777"; + try { + const state: NativeInterceptState = { origin: "http://127.0.0.1:7777", ready: Promise.resolve("http://127.0.0.1:7777"), attach: true }; + const s: V2State = {}; + const lines = await capturedErrors(async () => { + await createNativeRoute(state)(routedEvent("ses_mismatch"), s); + }); + assert.equal(lines.length, 1); + assert.equal(s.proxyBase, undefined, "the pinned channel is left on its own path — no stamping, no rewrite"); + } finally { + if (prev === undefined) delete process.env.BILLION_CONTEXT_PROXY; + else process.env.BILLION_CONTEXT_PROXY = prev; + } +}); + +test("#1958: non-model /bili/ traffic and /__bili/health never warn", async () => { + const prev = process.env.BILLION_CONTEXT_PROXY; + delete process.env.BILLION_CONTEXT_PROXY; + try { + const s: V2State = {}; + const lines = await capturedErrors(async () => { + await createNativeRoute(spawnState())(routedEvent("ses_nm", `${BAKED}/bili/http://example.invalid/some/other/path`), s); + await createNativeRoute(spawnState())(routedEvent("ses_nm", `${BAKED}/__bili/health`), s); + }); + assert.equal(lines.length, 0, "only model API URLs carry the routing claim"); + } finally { + if (prev === undefined) delete process.env.BILLION_CONTEXT_PROXY; + else process.env.BILLION_CONTEXT_PROXY = prev; + } +});