Skip to content

[Design] Host contract v2: pin behavior with stubs first, then unify lifecycle / capability declaration / degradation re | [Design] 宿主契约 v2:先打桩固定行为,再统一生命周期/能力声明/降级恢复/入口实测(讨论通过后才动工)| [Design] Host contract v2: pin behavior with tests first, then unify lif… #5241

Open

Description

@ranxianglei

(ai: zai/glm-5.3)

这是啥问题(一句话)

代理和十条宿主车道之间没有契约:生命周期没有共享状态机、能力靠猜、降级是一次性闩锁、大小靠估算——同一个缺口在每条车道各自复发一遍,补丁打了一条车道下一条又冒出来。本 issue 统一治理,并且立规矩:先打桩固定行为,再讨论方案,批准后才动工。

流程规矩(所有动工必须遵守)

为了兼容性、避免引入回归,本 issue 管辖的每一项改动都走同一条路:

  1. 先打桩:对要动的模块先写特征化测试(characterization tests),把现在的行为(包括有问题的行为)原样钉住;覆盖不足的先补测试。桩测试红了不算失败,它就是现状的记录。
  2. 方案讨论:动工前在 issue 评论区贴「老方案 vs 新方案」对比——老方案=现状怎么做的+历次补丁为什么修不干净;新方案=具体实现(接口、文件、迁移步骤、风险)。讨论通过、owner 批准后才能写实现代码。
  3. 行为等价优先:纯搬运/收敛类 PR 必须让桩测试全绿(行为不变);要改行为的 PR 必须单独说明改哪条桩、为什么,再经批准。
  4. 每步独立 PR、可回滚、CI 绿;一个 issue 一个 PR,Closes 挂到本 issue 的子任务。

为什么逐点修不动(打地鼠证据链)

四个失败家族在非 dsh 的 9 条车道全部成簇出现(dsh 只占 29%,是最重的报告者,不是病因):

家族 全局出现 同型 bug 跨车道独立复发
F1 生命周期/监督无共享状态机 17 处/9 车道 端口漂移钉死:#926(opencode,已修)→ #4566(omp)→ #5127(claude);verifyAttachAndRecover 四份逐字拷贝(pi-native.ts:178 / omp-native.ts:271 / opencode-native.ts:311 / dsh-native.ts:771,~90 行×4)
F2 能力/身份靠推断 18 处 冷启动工具丢失:#4134(dsh)→ #4998(pi)→ #5001(claude-code)→ #4641(hermes);exposedTools 全库 0 命中——声明机制不存在
F3 降级一次性闩锁无恢复 15 处 #5032 自证:直发守卫存在但逐车道手工武装(dsh #4904 有、pi #5027 有、omp/opencode 裸奔);readonly 静默降级 #4614/#5229/#4816/#5086
F4 大小靠估算不实测 17 处 熔断只量部分字段:#5000(只量 text)= #4819(不测图像)= #4315(CJK 扩展区按 1/4 记);入口 5GiB 整段 parse → OOM 向量 #4021

现状不是零起点:状态机的 7 个发射点已存在(claimStartingMarker=spawned、armWatchdog/ensureSqliteEngine=booting、announceListening=listening、markBootReady=ready[server.ts:615]、runtime-status 四原因源=degraded、三条 adopt 路径=adopted、finishShutdown/watchdog=exited),NativeInterceptState 已是事实上的生命周期接口,CA/SQLite 自举/存储隔离(#4175)的自愈样板都在。缺的是单源聚合和契约化,不是重写。

六条契约(治理目标)

  1. C1 生命周期状态机单源:spawned→booting→listening→ready→degraded(reason)→adopted→exited 一份实现;实例注册表加 lifecycle 字段,/__bili/health 用同一枚举,一句话回答「什么模式、为什么、何时重试」。
  2. C2 能力声明,禁止推断:宿主握手时声明注册的工具与流量归属(Plugin lanes: host declares exposed bili tools per request via x-bili-plugin-exposed-tools (structural fix for #3884/#3600 name-guessing) | 插件车道:宿主按请求声明暴露的 bili 工具(根治 #3884/#3600 认名字脆弱性) #3906 方向重开);内容 hash/env 推断降级为显式声明的兜底。
  3. C3 降级三必须:可告警、可恢复、有 TTL——禁止一次性闩锁。现存违规:shadow.ts:186 stats.disabled 进程内永不重试(→ 改冷却 TTL,照抄 engine-bootstrap 冷却样板)、logger markStderrDead 永久(→ 有界重探)、DIRECT([Bug][dsh] After one upstream 400, takeover latches to DIRECT for the rest of the host process (attribution throw never recovers) #4183)/readonly(SQLite unified storage degraded to legacy-only (bili v0.1.205, node v24.22.1, win32-x64) #4614 族)/429-hold(429 governor hold is keyed by origin+credential with no model dimension — one model's quota exhaustion freezes the whole lane (healthy models get local 429/424) #5199)无恢复路径。唯一结构性豁免:宿主进程内 attribution 失败走 direct(宿主里的代码换不了自己),契约只要求醒目可见+「重启宿主恢复」指引。
  4. C4 measure-then-act:入口/出口实测字节,估算值只准做启发不准判死。入口准入早拒(0.1.197: A single 25 MiB request drives the heap to the 4 GB ceiling → process aborts → ~10 s per crash-restart cycle (D | 0.1.197:单个 25 MiB 请求把堆吃到 4 GB 上限 → 进程 abort → 约 10 秒一轮崩溃重启(DSH 双窗口同时 Connection error) #3386 [Bug] Codex Responses WebSocket blocks long sessions at 100 MiB before ACP compression, including small incremental continuations #4804 The invariant judge has no size cap on oversized bodies: performing a full-body JSON.parse on a 5 GiB request is an OOM | 不变量裁判对超大 body 无上限:5GiB 请求上做整 body JSON.parse,是 OOM/事件循环阻塞向量 #4021)、decompress 预检(decompress lacks preflight size check — oversized restore fails at upstream instead of failing early #5013)、熔断/计数字段补全([Bug][dsh][0.1.208] Kill switch / egress fuse only measures message.text: a session with 26,903 messages and only 1.44 M | [Bug][dsh][0.1.208] 判死/egress fuse 只量 message.text:26,903 条消息、core text 仅 1.44 MiB 的会话绕过 fuse 发出 55.2 MiB 请求体,被上游 413 拒收(ModelArts.… #5000 The context can't be compressed, there are too many images displayed. I'm not sure if it's an issue with my upstream. | 上下文无法压缩,显示图片过多,我不知道是不是我上游的问题 #4120 [Bug] defaultCountTokens undercounts Extended CJK characters; supplementary-plane characters fall into the UTF-16 /4 bra | [Bug] defaultCountTokens 漏计扩展汉字,补充平面落入 UTF-16 /4 分支 #4315)、窗口口径唯一(Effective window silently halved: 25% default output headroom + hardcoded 70% escalation nudge, both non-configurable #5230 preflight and [headroom] disagree on the effective window, and preflight folding silently creates no block #5172)。
  5. C5 流量路由可观测:每条车道能发「流量没经过我」信号(route=miss),不许静默失明([ZCode native] z.ai builtin account (ZAI_BUSINESS_BASE_URL) bypasses the provider store — bili-zcode goes silently blind after the switch | [ZCode native] z.ai 内置账号(ZAI_BUSINESS_BASE_URL)绕过 provider store——切换后 bili-zcode 静默失明 #4692 In oh my pi's native plugin mode, the recap feature does not capture conversation traffic, resulting in conversations re | oh my pi 使用原生插件模式下recap 功能对话流量未被捕获导致对话未被压缩 #4897 Pi + claude-bridge: native sends no model requests to proxy; launcher compress returns 404 #3429)。
  6. C6 新车道上线 checklist:直发守卫已武装、--lane 参数、工具声明、告警接入、背压安全通道——omp/opencode lanes: oversized history egresses uncompressed when the proxy is down — direct-send window guard still unarmed (#5025 family residual) #5032 的教训产品化,新宿主只写 ~150 行 lane 文件。

分阶段(每阶段都走上面的规矩:打桩→方案对比→批准→动工)

目标形态:src/agent/adapter/{contract,lifecycle,headers,registration,acp-command}.ts 共享层 + 每宿主薄 lane(pi/dsh/opencode/omp,未来 hermes/trae 各 ~150 行)。真实宿主差异不收敛:dsh compaction 站队/APIG 重签/UI 双面、pi subagents、opencode 三代共存。

被收编的 issue(代表,~67 条)

验收

  • /__bili/health 能一句话回答「现在什么模式、为什么、何时重试」
  • 桩测试成为永久回归网:四家族相关模块的行为改动必须显式过桩
  • 四家族新增 issue 速率归零趋势(不是存量清零,是复发停止)

完整调研底稿(宿主接线全景 33 文件、全仓失败路径穷举、404 条 open issue 四家族交叉验证)在本地,按需贴出任何一节的证据。

Activity

  1. changed the title [-][Design] 宿主契约 v2:先打桩固定行为,再统一生命周期/能力声明/降级恢复/入口实测(讨论通过后才动工)| [Design] Host contract v2: pin behavior with tests first, then unify lifecycle / capability declaration / latch recovery / size admission (discuss before implement)[/-] [+][Design] Host contract v2: pin behavior with stubs first, then unify lifecycle / capability declaration / degradation re | [Design] 宿主契约 v2:先打桩固定行为,再统一生命周期/能力声明/降级恢复/入口实测(讨论通过后才动工)| [Design] Host contract v2: pin behavior with tests first, then unify lif…[/+] on Oct 30, 2026
  2. ranxianglei commented on Oct 30, 2026

    @ranxianglei
    OwnerAuthor

    (ai: zai/glm-5.3)

    阶段 1 方案讨论:四车道启动生命周期抽取(动工前审批稿)

    按 #5241 规矩,实现之前先对比老/新方案,请 owner 批准后才动工。阶段 0 桩(#5242)已把这四份代码的行为钉死,是本方案的等价性验收网。

    老方案:同一份逻辑手抄四遍

    四车道各有一份几乎相同的 verifyAttachAndRecover(启动时:探测目标代理 → 健康就 attach,死了就 fallback 拉自己的):

    车道 位置 状态
    pi src/agent/pi-native.ts:178 基线版
    omp src/agent/omp-native.ts:271 与 pi 差日志字符串 + publishOrigin 小函数
    opencode src/agent/opencode-native.ts:311 与 pi 近逐字相同
    dsh src/agent/dsh-native.ts:771 最厚:+版本轮换(#3544)+register 记账+flight-gen 守卫(#3616)等约 21 行独有差异

    同型 bug 跨车道独立复发(端口钉死 #926→#4566→#5127、冷启动工具 #4134→#4998→#5001→#4641)就是这份手抄的直接代价:修一处,另外三处照旧带病。

    打桩过程还挖出一个没写进任何文档的隐含契约:四份代码都假设"我是这个进程里唯一的 native 车道"——四条车道抢同一个 process.env.BILLION_CONTEXT_PROXY、同一个全局 fetch 拦截槽。生产里每车道一个宿主进程所以碰巧没事;但把两条车道塞进一个进程(测试已实测)会互相覆盖地址、假 spawn、顶掉拦截。阶段 1 合并共享代码时这个契约必须显式化,否则未来一个进程装两条车道就是生产事故。

    新方案:一个共享适配器 + 每车道一份配置(纯搬运)

    新文件 src/agent/native-attach.ts,导出参数化的单份实现:

    export interface NativeLaneSpec {
        lane: "pi" | "omp" | "opencode" | "dsh";
        waitVersions: string[];                        // 各车道 manifest 兼容窗口(现状差异,照搬)
        bootstrap: () => Promise<string | undefined>;  // ensureProxyRunning 包装
        publish: (origin: string) => void;             // pi/oc 写 env+state;omp 走 publishOrigin;dsh 写 register+解除 preset
        onEvent: (level: "info" | "error", msg: string) => void;  // logHostEvent vs persistClientEvent
        rotateOlderResident?: boolean;                 // 仅 dsh = true(#3544 轮换;S2 分歧原样保留,见下)
    }
    export function verifyAttachAndRecover(spec: NativeLaneSpec, attachOrigin: string): Promise<string | undefined>;

    四条车道的 *-native.ts 变成:构造自己的 spec + 调共享实现。规则:纯搬运,行为一字节不变——包括保留现有的不一致(桩就是干这个的)。另外共享模块加一条显式互斥:同一进程 arm 第二条车道直接报错,把上面那个隐含契约变成代码里看得见的约定(报错信息用大白话,说清"一个进程只能跑一条车道")。

    明确不做的:

    • 不统一语义分歧。S2 分歧(旧版本 target:pi/omp/opencode 照样 attach,dsh 轮换重生)保留在 rotateOlderResident 开关后面,统一成哪种另开专项讨论,不混进搬运 PR;
    • 不改任何环境变量名 / CLI / 用户可见行为;
    • 不动 spawn 测试缝(_setSpawnForTest 等,桩和既有测试依赖);
    • 不动 kernel。

    切片:四个 PR,每个独立可合可回滚

    1. PR-1a:新增 native-attach.ts + 迁移 pi(基线最简单、测试最全:pi-native.test.ts 19 测 + 桩矩阵);其余三车道暂不迁移,新旧并存验证一个周期;
    2. PR-1b:迁移 omp;
    3. PR-1c:迁移 opencode;
    4. PR-1d:迁移 dsh(独有差异全部走 spec 开关/钩子,issue3544 全套 20 测是它的专项验收网)。

    验收标准(每个 PR)

    风险与回滚

    • 每车道独立 PR,回滚 = revert 单个 PR,车道退回自己的旧拷贝;
    • 最坏情况:某车道迁移后发现隐藏耦合,该车道不迁,共享实现只服务已迁车道——不阻塞其他车道;
    • dsh 风险最高(差异最多),所以放最后,且有三层网:桩矩阵 + issue3544 全套 + dsh 自有套件。

    请 owner 裁决

    批 A 我就从 PR-1a 开工。

  3. ranxianglei commented on Oct 30, 2026

    @ranxianglei
    OwnerAuthor

    (ai: zai/glm-5.3)

    阶段 1(生命周期单源化)四刀全部开完,按批准的方案 A(纯搬运)+ 一处诚实修正:

    刀 车道 PR 内容
    PR-1a pi #5244 verifyAttachAndRecover 迁入共享 src/agent/native-attach.ts(NativeLaneSpec 参数化)+ 新增 armNativeLane 车道互斥守卫
    PR-1b omp #5246 同构迁移;omp 的 publishOrigin 测试钉保护经 spec 钩子(clearOrigin)保留
    PR-1c opencode #5247 同构迁移;历史连字符日志前缀经 spec.tag 逐字节保留
    PR-1d dsh #5248 不迁移(诚实修正,PR 说明里有完整论证):厚状态机(#3544 轮换/#3616 世界代数/register 发布面)钩子化会把连贯函数摊成两处;只采用 armNativeLane("dsh") 守卫 + 双向交叉引用注释

    每一刀的等价性验收都靠 #5242 的桩矩阵一行未改全绿背书;交叉车道污染(双车道同进程互相覆盖 BILLION_CONTEXT_PROXY/fetch 拦截槽)从隐含假设变成显式契约,issue3304 的有意双车道共驾测试显式豁免。

    合并顺序:#5242 → #5244 → #5246 → #5247 → #5248(全部叠栈,前者合并后 GitHub 自动 retarget)。

    下一阶段(等这批合完再启动,按规矩先出方案讨论):阶段 2 闩锁治理——shadow 三振闩(storage/shadow.ts,disabled 后进程内永不复位)与 stderr-dead 闩(logger.ts)的「可告警、可恢复、有 TTL」化,现状已被 #5242 桩冻结。

  4. ranxianglei commented on Oct 30, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    查重:不重复——本条是独立的宿主契约治理伞,全仓无同题 issue(按 lifecycle/状态机/车道统一/verifyAttachAndRecover 组合检索,0 命中)。
    标签:scope/wiring + p2(跨车道问题按规则不打客户端标签;这是治理/重构 tracker 而非缺陷报告,不打 bug;p2 = 聚合多条真实功能债务、各有绕行、正在系统性收编,非单点不可用)。

    收到阶段 1 进度报告。背书前我先按规矩核了本地仓库(master @ 5594c1315,Merge #5054),结论:报告里的产物目前一个都不在主树里——

    • src/agent/native-attach.ts(共享模块)不存在;
    • armNativeLane / NativeLaneSpec 符号在 src/+tests/ 0 命中;
    • 四份 verifyAttachAndRecover 仍原样挂在 pi-native.ts:178 / omp-native.ts:271 / opencode-native.ts:311 / dsh-native.ts:771,未迁移;
    • 无对应分支或提交。

    这与「四个未合并的叠栈 PR」自洽(PR 还没进 master),所以我不据此否定报告;但我这边拿不到这些 PR 的 head 与 CI 状态,无法确认它们真实存在且绿,所以在核到之前我不会把「阶段 1 已完成/已合」当既成事实转述。

    有一个必须对齐的硬矛盾:表里写的是 PR-1a | pi | #5244,而 #5244 就是本 issue 本身——GitHub 上 issue 与 PR 共用同一编号空间,不可能同时存在两个 5244。请一并发 #5242(桩矩阵)、#5246 / #5247 / #5248 的准确编号或链接。

    拿到正确链接后我会逐个核对 head diff + CI(重点看 #5242 桩矩阵是否真的一行未改全绿、四处迁移是否纯搬运行为等价),再按八问出 review 结论、确认合并顺序。若其中某个其实还没开,也直接说,我按本 issue 流程从 Phase 0 桩开始接手。

    按流程,阶段 2(闩锁治理)继续 gate 在这批合并完成 + 先出「老 vs 新」方案讨论之后,不抢跑。

  5. ranxianglei commented on Oct 30, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    补充核验(接上一条):我把分支从上游按名字捞出来了——这批工作真实存在。我上一条说「无法确认存在」是因为本地 origin 指向的是滞后的本地镜像、没同步到这些未合并的头,不是工作不存在。上游实有:

    • 2026-10-31_contract-v2-stake-tests(= 报告里的桩矩阵)
    • 2026-10-30_native-attach-{pi,omp,opencode,dsh}(= 四刀)

    diff --stat(vs master)逐条对上了报告描述:

    • 桩矩阵纯测试:仅 4 个 tests/contract-v2-stake-*,517 行新增,零 src/ 生产改动 —— 符合阶段 0「打桩不改代码」。四文件正好覆盖 health(/__bili/health)、latches(shadow disabled + stderr-dead)、verify-attach(四拷贝)、lane-probe(route=miss)。
    • pi/omp/opencode 真迁移到共享 src/agent/native-attach.ts(随栈 141→148→155 行),对应 *-native.ts 各自缩水;
    • dsh 只 +23 行(守卫 + 交叉引用注释)、未迁移 —— 与「dsh 不迁、只加 armNativeLane("dsh") 守卫」一致;
    • 叠栈成立:后一个分支含前一个的全部改动;opencode 起带 issue3304-incremental-direct-send.test.ts(+7)= 双车道共驾显式豁免。

    实质内容我基本认账。唯一硬伤仍是编号列:PR-1a | pi | #5244,可 #5244 就是本 issue,issue 与 PR 共用编号空间不可能撞号。请给这五个 PR 的准确号或链接。

    合入前我还会补齐三步(不跳):① 确认五支都真开成了 PR(分支在 ≠ PR 在);② 逐个 head 拉 CI(走镜像缓存,拿到 PR 号后查);③ 每刀出八问 review —— 重点核迁移行为等价(opencode spec.tag 逐字节日志前缀、omp clearOrigin/publishOrigin 钩子是否真保住原语义)+ 桩矩阵是否一行未改全绿。

    给我正确 PR 号(或授权我按分支名继续),我就把这三步走完再给合并判定。

  6. ranxianglei commented on Oct 30, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

    收工小结(接前两条更新):阶段 1 那批已核实真实存在且结构自洽 —— 上游五支分支:2026-10-31_contract-v2-stake-tests(桩矩阵)+ 2026-10-30_native-attach-{pi,omp,opencode,dsh}(四刀)。diff --stat 逐条对上报告:桩矩阵纯测试、零 src/ 改动;pi/omp/opencode 真迁入共享 native-attach.ts;dsh 按「诚实修正」只加 armNativeLane("dsh") 守卫、不迁移;叠栈与 issue3304 双车道豁免均在。

    我这边已完成:查重(独立治理伞,无同题)、打标签(scope/wiring+p2)、逐支结构核验。

    卡在你这里的一项:五个 PR 的准确号或链接 —— 报告编号列把 pi 那格写成 #5244,而 #5244 就是本 issue(issue 与 PR 共用编号空间,不可能撞号),所以我取不到权威编号。给我正确号(或授权我按分支名推进),我就补齐合入前三步再出合并判定:① 确认五支都开成了 PR;② 逐个 head 拉 CI(走镜像缓存);③ 每刀八问 review,重点核迁移行为等价(opencode spec.tag 日志前缀逐字节、omp clearOrigin/publishOrigin 钩子)+ 桩矩阵一行未改全绿。

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