feat: pi native 模式——fetch 拦截层 + 插件胶水（native 模式 B）

[ranxianglei]

来源: #513 分析 native 模式时拆出的子任务（owner 已确认方案）。

目标：装好插件后直接跑裸 pi，无需 bili pi launcher，用户无感。

设计（#513 讨论定稿）:

• fetch 拦截层（新模块，核心机制）：在宿主 Node 进程内包一层 globalThis.fetch。仅当请求目标 origin 精确等于"当前模型的上游 origin"（取自 ctx.model.baseUrl）时，改写成 http://127.0.0.1:<会话端口>/bili/<原URL>；其余一切流量原样放行。永不改写已带 /bili/ 前缀的 URL；非 http(s) 协议放行；提供卸载函数与防双重包装标记
• 插件胶水：session_start 时从插件文件自身路径解析包根（<root>/dist/agent/pi.js → 上两级），用 process.execPath spawn node <root>/dist/index.js daemon --fresh --json --parent-pid <pid> → 解析 JSON 得 origin → 安装拦截器 → 现有工具注册/header 盖章逻辑复用（proxyBase 改由 daemon 输出提供而非 detectProxyBase）
• marker 门控：bili plugin install pi --native（或等价开关）写 marker 文件；无 marker 时行为与现状完全一致
• e2e 可行性验证先行：真实 pi 实测——patch globalThis.fetch 能否拦到 provider 请求、SSE 流式响应是否正常回传。这是全设计唯一未验证的承重假设；若不成立，回 探索如何发布为native模式 #513 报告并带替代方案，不硬推
• 单测：拦截器 URL 匹配/改写纯逻辑（string/URL/Request 输入、非 http 协议、防双包、排除规则）

[ranxianglei]

🤖 ework agent · qwen3.8-27b

[bot] 🏷 已完成：PR #524 — feat(pi): native mode（base 是 #523 的分支 2026-09-04_bili-daemon-subcommand，需先合 #523）。

内容：src/agent/intercept.ts（fetch 拦截层）+ pi 扩展内 marker 门控的自启动 daemon 路径 + bili plugin install pi --native / remove / list (native) 标记 + README "Native mode" 章节。测试：intercept 单测矩阵 + native-pi 门控测试；真实 pi e2e 已验证（round-1 直连、重试经代理、SSE 回流、daemon 随 pi 退出自动回收）。详见 PR body。

[ranxianglei]

e2e 验证结果:fetch 拦截层承重假设全部成立 ✅

在 pi 0.83.6 / Node 25 上做了两组实验,源码挖掘 + 实测双重确认:

源码结论

pi → pi-stable-ai → Anthropic/OpenAI 官方 SDK,两家 SDK 的默认 fetch 解析完全相同(Stainless 同款生成代码):

// @anthropic-ai/sdk/internal/shims.js(openai/sdk 同款)
function getDefaultFetch() {
    if (typeof fetch !== 'undefined') return fetch;   // 全局 fetch
}
// client.js —— 构造时一次性捕获:
this.fetch = options.fetch ?? getDefaultFetch();

pi 侧传 options?.fetch(不传)→ 走全局 globalThis.fetch,且客户端在首次请求时才构造。

实验 1:补丁时序(openai wire)

02:43:35.517  橡模块加载 + globalThis.fetch patch 生效
02:43:35.870  POST http://127.0.0.1:8199/v1/chat/completions  ← 被拦截,透传正常

回复正常("OK")。模块加载补丁永远先于客户端构造(353ms 领先)。

实验 2:完整微型架构(anthropic wire)

扩展内 spawn 子代理(动态端口 0)→ stdout 握手拿端口 → patch 改写 origin → 代理收到完整载荷并回传:

REWRITE http://127.0.0.1:8199/v1/messages -> http://127.0.0.1:36271/v1/messages
代理日志: REQ POST /v1/messages bytes=39741   ← 39KB anthropic 载荷完整
pi 正常输出 "OK2";pi 退出 → 子代理被 exit 钩子回收,无残留进程

已知竞态(无害):factory 调用时子代理端口可能未就绪(port=null),但首请求要数百 ms 后才发,届时端口已就绪。正式实现加"端口就绪门闩"即可。

判定表

假设	结果
globalThis.fetch 可拦截模型流量(openai + anthropic 双 wire)	✅
加载时补丁早于 SDK 客户端构造	✅(构造是惰性的)
扩展内 spawn 子进程代理 + 动态端口 + stdout 握手	✅
origin 改写不影响请求/响应	✅(39KB 双向透传)
误伤范围	整回合进程内 fetch 仅模型调用 1 次,按 origin 白名单改写可控

落地方案(与 #513 方案 D 对齐)

npm 安装 billion-context → 用户在 pi 扩展列表加 billion-context/pi → 模块加载时:

1. spawn 本包代理(动态端口、父 pid 看门狗,Windows 上 launcher 子代理从无优雅退出:stopProxy 直接 TerminateProcess,SIGBREAK-flush 全史 0 次触发,防抖窗状态+进行中轮被拦腰 #414 逻辑搬入)
2. patch globalThis.fetch,仅改写命中上游配置的模型请求 origin
3. 打 before_provider_headers 插件标记(复用现有 agent/pi.js 逻辑)

launcher 对 pi 退役(omp/dsh/wire 兜底保留)。开始实施,分支见后续 PR。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

收到,验证结论全部采纳。已按落地方案实施完毕:PR #712(单 PR 合并交付,旧的 #523/#524 已作为被取代项关闭并留了说明评论)。

实现要点(相对你验证时的微型架构)

1. 原生模式对 pi 默认开启——marker 门控(--native / native.json)整个移除:扩展加载即视为 bili 托管。保留 BILLION_CONTEXT_PLUGIN=0 总开关;daemon 启动失败时降级为"告警 + 流量直连 + 退避重试",不会 brick。
2. 端口就绪门闩(你指出的竞态):拦截器在 daemon 握手完成之前就装好,首个请求挂起等待端口就绪再改写;latch 超时则该请求直连放行、后续请求照常走代理。round-1 直连泄漏消除。
3. pi 启动器退役:bili pi / bili pi-test / bili test pi 全部移除,CLI 给出友好退役提示;omp/dsh 及其余客户端、/bili/ wire 兜底完全不动。
4. 顺手修了两个原生模式缺口:
   • 注入零文件化:废除 overlay/临时目录机制(#531 设计返工) #535 的 compaction-cancel 改为按事件动态判定(env / nativeBase / attach-base 任一命中才取消)——裸 pi + 扩展现在就是 bili 托管,必须取消宿主原生压缩;而 daemon 启动失败的运行保持全原生,不丢压缩能力;
   • session_compact 通知补了 nativeBase 回退(之前原生模式下收不到 compact 通知)。

我的真实 pi 端到端验证(pi 0.83.6,隔离 HOME + mock upstream)

• pi -p "Say OK" 正常输出,退出码 0;
• mock upstream 只收到恰好 1 次请求(16KB anthropic/openai 载荷双向完整透传),且代理日志证实该请求先经代理——门闩生效,首请求未直连;
• 动态端口、父 pid 看门狗回收均正常:pi 退出后无残留代理进程;
• 源码 checkout 下 auto-update 自动跳过,无副作用。

残余竞态(已接受并写入 README):若首个请求落在进程启动后 <1s 内(非交互 -p 场景),tools 注册略晚于门闩就绪,该请求会以 wire 模式进入一个匿名会话,turn 2 起带 x-bili-plugin 头正常收敛为插件模式会话。交互用户输入必然晚于 1s,不受影响;且严格优于改动前(旧行为是 round-1 完全直连、零压缩)。

预检

typecheck 干净 · npm test 1391 tests / 1388 pass / 0 fail / 3 skip · build 正常(dist/index.js 2.75MB,dist/agent/pi.js 25.57KB)。版本号未动(仍 0.1.105,发布走 release 流程)。

另注:仓库里还有一个 #706(作者 bot[bot],分支 feat/pi-native-plugin)在做同一件事,是并行开出来的重复评审面,我没有擅自关闭,留你决定取舍。

一句话中文摘要:pi 原生模式已按你的验证结论落地——扩展加载即自启每会话代理并拦截 globalThis.fetch(带端口就绪门闩,首请求不再直连),marker 门控与 bili pi 启动器整体退役(omp/dsh/wire 兜底保留),真实 pi 端到端验证通过,见 PR #712。