Skip to content

fix: zcode — explain the zero-routable-provider case instead of a bare Connection closed (#1892) - #1896

Merged
ranxianglei merged 7 commits into
masterfrom
2026-10-02_zcode-empty-store-diagnostic
Oct 2, 2026
Merged

ranxianglei merged 7 commits into
masterfrom
2026-10-02_zcode-empty-store-diagnostic

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Part of #1892. Related constraints: #1621 (coding-plan client signing), #1622 (routing scope).

What this changes

routeZcodeConfig's zero-wrapped path previously logged only no routable provider entry found, which surfaced to the ZCode client as an opaque MCP Connection closed with no next step. This adds a read-only classifier (logNoRouteNextSteps) that names the actual shape, based on the ZCode source evidence linked in #1892:

Diagnosis-only boundary (important)

This improves diagnostics only. It does not fix the pre-init MCP exit or activate compression:

Behavior change disclosure

Log wording in the zero-wrapped case changed (log-only; no routing/wire/default/threshold change):

  • every provider entry … → every provider rule … (+ cert-MITM confirmation note)
  • the provider store has no provider entries to route. → built-in/account-layer explanation (+ optional legacy-leftover note)

No new config surface (no env vars / config fields added). Pure observability — never writes; #1621 signing protection and #1622 direct/loopback exemptions unchanged.

Verification

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-02_zcode-empty-store-diagnostic (cada81a)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1927-pr.1896.2730557

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1896.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Acknowledged — this is the [PR] tracking issue for PR #1896 (2026-10-02_zcode-empty-store-diagnostic, head bd9c5de4). Not re-doing the work; reviewing per protocol: pulling the branch, auditing the diff against master, re-running typecheck + targeted zcode suite locally, and watching CI (currently: build-artifact / version-guard / real-lane e2es green; test matrix still running). Structured conclusion follows shortly.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 完成(审核 + 定向验证,未重做)。结论先行:方向正确、代码正确;但审查中发现一个让本 PR 核心价值失效的缺陷,已在 PR 分支补一个独立标注 commit 修掉并验证。另发现 PR 描述里有一处披露失实,见下。

结构化七问

  1. 是什么问题:zcode「零可路由 provider」场景此前只留一行泛化日志,客户端表现为不透明的 MCP Connection closed,无可操作下一步。本 PR 增加只读分类器 logNoRouteNextSteps(内置/账户层说明、[Bug] zcode 原生模式:coding-plan 账号模型创建失败 "Client signing handshake requires HTTPS."(zcode 3.14 客户端签名与 http 改写不兼容) #1621 签名墙→cert-MITM 指引、混合跳过回落到逐条 skip 列表),纯可观测性、从不写配置。
  2. 什么原因导致的(我发现的缺陷):诊断行经 logger 异步 WriteStream 落盘(src/logger.ts 的 s.write),而 src/zcode/mcp-entry.ts main() 的四条早退路径直接 process.exit()、未等 closeLogger()——process.exit 丢弃 libuv 缓冲中未刷出的写入;且 mcp-entry 头部注释明确 zcode 不捕获该 MCP 子进程的 stderr,所以该行两边都没有:bili.log 丢了、stderr 没人读。实证(attach 模式 + 空 personal store + 健康 fake proxy 的最小复现,真实跑 node --import tsx src/zcode/mcp-entry.ts):修复前 8/8 次新诊断行不在 bili.log(仅第一行幸存——libuv 线程池恰在退出前发出了首个 write(2));修复后 8/8 次在文件中。即:按现状合入,用户实际仍什么都看不到。
  3. 怎么修复的:独立 commit bf1e0be6(fix(zcode): flush the log tee before mcp-entry early exits (#1892),+9/-2,仅 mcp-entry.ts):四条早退路径(mode off/!bootstrap、!applied、manifest 不可用、fatal catch)前统一 await closeLogger()——该 API 本就是为此导出的(注释明言"resolves once every buffered line has drained to disk")。同机制面排查后确认范围就到此为止:src/server.ts 的退出路径前都有真实 async 工作(flushAllSessions().finally / shutdown 排空)= 天然 drain 窗口,实际安全;kimi/native-mcp.ts、zcode/bootstrap-hook.ts 走 stderr-only 日志、不落文件,无丢失面——故无需另立项。
  4. 是否有回归问题:无。逐项审过:zero-wrapped 路由语义不变(config untouched、routed:undefined、mode:"active"/attached:true 均被既有+新增测试钉住);[Bug] zcode 原生模式:coding-plan 账号模型创建失败 "Client signing handshake requires HTTPS."(zcode 3.14 客户端签名与 http 改写不兼容) #1621 签名墙、[Bug] zcode 原生模式路由白名单与主流用法错配:多模型/子代理场景需要全量压缩,仅 plan 账号反而是少数 #1622 direct/loopback 豁免、legacy 文件处理全部不动(分类器只读,测试含字节相等断言证明 never-writes);我的 flush 修复只改进程退出时的日志持久性,不触碰请求路径/时序/默认值/阈值。需披露的行为变化一条:日志持久性——四条早退路径的最后几行日志旧值「可能静默丢失(zero-route 路径实测必丢)」→ 新值「退出前保证落盘 bili.log」;原因即第 2 点,否则本 PR 诊断价值为零。
  5. 是否破坏缓存:不涉及(无缓存/重试/游标/去重键)。
  6. 是否改了设计方向:否。诊断边界声明成立:不改 pre-init MCP exit、不激活压缩,coding-plan 流量入压缩仍归 [Bug] zcode 原生模式:coding-plan 账号模型创建失败 "Client signing handshake requires HTTPS."(zcode 3.14 客户端签名与 http 改写不兼容) #1621 的 cert-MITM/native 路线,plan B(改写 legacy 文件)按 [Bug] ZCode 3.14.4 原生插件:新版 providerRules 为空时 MCP 在初始化前退出,客户端报 Connection closed #1892 讨论刻意不做——与代码一致(legacy 仅作只读计数提示)。
  7. 是否引入新的配置:无(env/config/CLI 均未动)。

需你处理的一处:PR 描述披露失实

"Behavior change disclosure" 引用的两条旧字符串——every provider entry … 与 the provider store has no provider entries to route.——在 master 全树 grep 不存在(唯一相近物是 json-edit.ts:325 的一句注释和 CONFIGURATION.md 文档行)。实际改动是纯增量:原泛化行 no routable provider entry found — leaving the config untouched 照旧输出,其后追加分类行。建议把披露段改为:「zero-wrapped 路径新增分类日志行(增量,不替换既有行);措辞变化为『新增』而非『替换』」,以免合并记录留下与 diff 不符的行为基线。

验证与 CI

  • 本地定向(全量回归留给 CI):npm run typecheck clean;zcode 套件 tests/zcode-native.test.ts + tests/zcode-json-edit.test.ts 48/48;上述 A/B 复现 8/8 LOST → 8/8 IN-FILE。
  • 陈旧 base 核查:base 012a86a 落后 master 82 commits,但该区间内零提交触碰 src/zcode|tests/zcode* → 无语义冲突,mergeable=True(BEHIND 不构成阻塞)。
  • 新 head bf1e0be6 CI:build-artifact / version-guard / hermetic registry e2e(ubuntu+windows)/ 全部 real-lane e2e(pi、codex、opencode、dsh)已绿;test matrix(ubuntu+windows × node 22/24)运行中。

判定

可合并(待 test matrix 转绿;合并操作按规约由人执行)。若你希望我把披露段文案直接改掉或再调整措辞,说一声即可。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 补一条 CI 状态更新:上轮回复后 test (ubuntu-latest, 24) 红过一次,已排查并处理,现在整条 run 全绿。

红的是什么:tests/claude-native.test.ts 的 hook e2e: manual bili start on the pinned port is attached, not refused (#1322/#1335/#1660)——claude 原生 hook 的 e2e,断言 hook 应 attach 到测试先起的 squatter daemon;实际 hook 走了 spawn 分支且子进程 exit 1(proxy child exited before becoming healthy,典型 attach-vs-spawn 竞态:squatter 端口 TCP 已通但 health 探针未就绪,hook 误判后在已被占用的端口再 spawn)。

与本 PR 无关的证据:

  1. 我的 commit bf1e0be6 只改 src/zcode/mcp-entry.ts;失败路径跑的是 dist/claude-native-bootstrap.js,其 import 链(launcher/config/instance/plugin-install/agent/native-bootstrap)对 zcode 零引用(已 grep 核实);
  2. 同一 head 的其余三个 matrix cell(ubuntu-22、windows-22、windows-24)全过,原 head bd9c5de4 的 ubuntu-24 也全过;
  3. 决定性证据:同 head 重跑该 job → success,代码零变化。

当前状态:head bf1e0be6,CI 全部 job success(含 ubuntu-24 重跑),PR mergeable: true。结论不变:可合并,合并操作按规约由你执行。

@ranxianglei

Copy link
Copy Markdown
Owner Author

零可路由 provider 是啥?
看不懂你这个.
你这个是修复了零可路由 provider问题吗

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 解释一下,直接回答你两个问题:

「零可路由 provider」是啥

bili 的 zcode native 模式启动时,会读 ZCode 的 provider 配置,逐条尝试把它的 base URL 改写到 bili 代理——这个改写就叫「路由」,改上了这条流量才进压缩。如果检查完所有条目,一条都没能改写(要么根本没有条目,要么每条都有跳过理由:#1621 客户端签名墙、loopback、direct 豁免、没有可用 base URL),就是「零可路由」:routable 数量 = 0。

这个状态下 bili 不启动 MCP 服务,ZCode 端看到的就是那个莫名其妙的 Connection closed——#1892 报的原始症状。

这个 PR 修复了这个问题吗

没有。 它不改任何路由行为:之前路由不上,现在还是路由不上,客户端还是看到 Connection closed。它只改了「发生这种情况时日志写什么」:

真正让这类流量进压缩的路径(都不在这个 PR 里):① 原生路由实际生效的 provider——被 #1621 客户端签名挡着;② cert-MITM 路径——#1621 下的独立工作。「改写旧文件兜底」的方案(plan B)在 #1892 里已明确不做:有效 personal store 存在后,旧文件就不是运行时 provider 来源。

另外我 review 时顺手修了一个会让这个诊断本身失效的问题(bf1e0be):mcp-entry 之前直接 process.exit() 不等日志刷盘,零可路由场景下新加的这行说明必然丢失(实测 8/8 全丢,且 ZCode 不捕获子进程 stderr,等于用户哪儿都看不到)。现在先保证写入 bili.log 再退出。

@ranxianglei
ranxianglei force-pushed the 2026-10-02_zcode-empty-store-diagnostic branch from bf1e0be to 92cfe40 Compare October 2, 2026 12:17
@ranxianglei

Copy link
Copy Markdown
Owner Author

Review + 实机复现矩阵(独立验证,approve)

代码审阅

改动面小而干净:+132/−2,3 文件。logNoRouteNextSteps 纯只读(readFileSync + applyZcodeRouting 干跑,从不写)——实测两份 store 文件前后字节不变;skipped.every(reason includes "#1621") 的判定与真实 skip 文案(client-signing account (#1621) — stays direct…)匹配;mcp-entry 各早退路径 await closeLogger() 在 process.exit 之前,顺序正确。

实机测试(真实 dist + 真实 stdio MCP 客户端行为,非单测)

用 node dist/zcode/mcp-entry.js 直跑(隔离 XDG/ZCODE_DATA_BASE_DIR + 假健康端点,向 stdin 发 MCP initialize 模拟 ZCode):

场景 结果
空个人 store(#1892 本体) exit 0 @91ms,initialize 无响应(= 客户端看到 Connection closed,与 issue 一致);日志两行:旧行 + 新分类行「no explicit provider rule … built-in/account layer … #1621 … cert-MITM」;store 未动
空 store + 旧 config.json 有 2 个 provider 新增「legacy file … still holds N provider record(s) … not routing candidates」注记;旧文件未被触碰/未被当路由目标
全部规则撞 #1621 签名墙 逐条 skip 列表 + 「every provider rule … cert-MITM path (Settings → Network)」分类行
对照:普通自定义 provider(正控) 正常路由(routed custom:my-vendor via … → https://…),manifest 不可用→干净降级 unroute + exit,三行日志全落盘
对照:master 构建 空规则场景只有旧行、无任何分类行 —— 差量就是本 PR 的全部价值

两点如实披露(不阻塞)

  1. closeLogger 的 flush 修复在本机快退路径上观察不到差量:master 构建同样把最后一行落了盘(Linux/tmpfs 快)。修复方向正确(时序依赖,慢盘/Windows 更可能丢),但"最后一行无处存在"的表述在最坏路径上成立、在我的环境未复现。
  2. 签名墙消息里的「Settings → Network: HTTP proxy + root CA path」是 ZCode 设置 UI 的命名假设,不同版本 UI 措辞若有出入会轻微误导——非阻塞。

边界确认(与 PR 声明一致)

本 PR 只改诊断,不改行为:routed undefined 时仍在 MCP 初始化前退出(实测 initialize 无响应),客户端侧 Connection closed 依旧——修复它属于 #1621(native routing of signing accounts / cert-MITM),不在本 PR。

本地:typecheck ✓;zcode 套件 48/48。CI 13/13 绿(实查 head bf1e0be)。可合。

@ranxianglei

Copy link
Copy Markdown
Owner Author

#1892 行为修复(第三 commit 92cfe40):不再 Connection closed,降级服务

#1896 前两个 commit 只补诊断日志。这个 commit 把行为本身修掉:mcp-entry 任何情况下都不再在 MCP 握手前退出。

机制

实测(真机,本仓库 dist + 真 ~/.zcode,空个人 provider store = #1892 报告者的世界)

场景 master(bf1e0be) 本修复(92cfe40)
空个人 store + 无健康代理 exit 0 @91ms,initialize 无应答(=Connection closed) 握手完成 serverInfo=bili,tools=[],alive 直到 stdin 关闭,exit 0
空个人 store + 现役代理(cert-MITM 机器) 同上,死 握手完成,服务真工具 compress/decompress/search_context/acp_status/acp_cache

本地 3.7.6 桌面版 zcode 无 3.14.4 公开下载渠道,用等价 stdio 契约复现 + 验证(空 store 语义与 3.14.4 报告一致)。

测试

ranxianglei pushed a commit that referenced this pull request Oct 2, 2026
The acp_status/panel tests render through the real process VERSION, so
their hardcoded 0.1.179-running spans broke on the first release after
#1873 landed (0.1.180): pull_request CI runs the merge tree, and PR #1896
inherited the red lanes. Derive the UI fixtures with patchBump(VERSION, ±n)
instead; pure-function tests keep the static ENTRIES (running is explicit
there). Adds a teeth assertion: at-or-below-running entries stay out of
the span.
@ranxianglei
ranxianglei force-pushed the 2026-10-02_zcode-empty-store-diagnostic branch from 92cfe40 to 27073b2 Compare October 2, 2026 12:33
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 两条评论都处理完了。分支期间 rebase 到最新 master(f7cc681,含 #1873)并新增一个测试修复 commit,最终 head 27073b2,CI 全绿。先答你的两点披露,再给行为修复 commit 的结构化结论。

对你两条披露的回应

① flush 修复在你环境观察不到差量 —— 两个观察都对,是时序问题:我的复现环境 8/8 丢(零路由路径每次必丢最后一行),你的快 tmpfs 机器上 libuv worker 恰好赶在 teardown 前完成了 write。补充一点:行为修复之后,零路由路径不再 process.exit(degraded 模式让进程活着服务握手),日志丢失的暴露面进一步缩小到剩余早退路径(off/degraded/fatal),那些路径上 closeLogger() 仍然守着。方向不变:保留。

② 「Settings → Network」UI 命名假设 —— 同意,非阻塞。可选软化措辞(不坚持):「在 ZCode 的网络设置里配置 HTTP proxy + root CA」,不断言具体菜单名。你拍板。

行为修复 commit(d6f821c,内容 ≡ 我此前审的 92cfe40,rebase 后逐字节一致,diff 验证过)

1. 是什么问题:零可路由时 mcp-entry 在 MCP initialize 之前就退出,ZCode 看到裸 Connection closed——不是「没压缩」,是没有任何服务。

2. 什么原因导致的:入口把「没有可路由对象」当成致命错误——路由可行性判定和进程存活耦合在一起,判定为不可路由就直接死亡,而不是降级服务。

3. 怎么修复的:解耦。planZcodeRouting() 纯只读干跑在任何 proxy bring-up 之前回答「有没有东西可包」;不可路由的会话不再 spawn 注定失败的代理;入口永远完成握手——找到现役代理(cert-MITM 机器)就通过它提供真 ACP 工具,找不到就以空闲 MCP 服务器活着(tools/list 空列表、tools/call 响亮 isError)。修在决策点(根因),不是在出口掩盖症状。

4. 是否回归:逐项审过,默认路径字节不变(无参调用方 cli/kimi 不受影响,kimi 有独立的 BootstrapMode,grep 核实);happy path 逐字节相同(watchdog/handoff 只在 happy path 安装);干跑纯度核实(applyZcodeRouting→applyNew/applyLegacy 纯字符串变换,无 fs 写,测试用 doesNotMatch(/\/bili\//) 钉死);logger closeLogger() 语义安全(懒重开,不会崩)。行为变更披露(旧→新):

  • (a) 五条早退路径:握手前 exit(0)(客户端见 Connection closed)→ 握手必完成(空闲或经代理);
  • (b) kill-switch off:unroute+exit → unroute+serveDegraded——被杀掉的会话可能通过发现的现役代理拿到真工具(跨 lane:别的 agent 的 8787 代理)。无会话绑定时 tools/call 响亮报错,无数据损坏;旧行为对逃生门用户同样给裸 Connection closed,所以这是改善而非风险;
  • (c) bootstrap 抛错路径不再先 unroute(低风险:bootstrap 顺序 plan→ensureProxy→route,抛错发生在写入前时无 wrapper 可撤;与「永不死亡」哲学一致);
  • (d) 签名墙契约 off→degraded(signing),唯一消费方是 mcp-entry(grep 核实),无外部破坏;
  • (e) 不可路由会话不再 spawn 空转代理(省实例,你声明的意图)。

5. 是否破坏缓存:不涉及——未触碰任何缓存/重试/游标/去重键,persist 未动。

6. 是否改设计方向:是,有意为之——zcode mcp-entry 从 fail-fast-exit 转为 always-serve-degraded。理由:MCP 子进程的存活是客户端契约,路由可行性与之正交。边界清晰:发现逻辑按序探活(BILI_MCP_PROXY→instance file→8787),空闲模式惰性(不打死 origin)。

7. 是否引入新配置:无——BILI_MCP_PROXY 是既有变量(mcp.ts/launcher/plugin-install/cli 都在用),8787 是规范默认端口(config.ts:952)。

测试有效性:强。e2e 钉住精确回归点(空 store 场景断言 initialize 应答存在且 stdin 关闭前 exitCode === null——master 会在 initialize 前就 exit 0);发现路径用假 manifest 服务器验证返回真工具;四分类矩阵钉死分类+不落盘;翻转后的 bootstrap 契约用「ensureProxy 被碰即抛」断言不触发 bring-up。

rebase 与第四个 commit(27073b2)

  • 四个 zcode 文件与新 head 逐字节一致(diff 验证),我的审查全部有效;src/mcp.ts 验证 = master + 仅 zcode degraded hunk(+19/−1),rebase 未丢 feat: tiered release-notes visibility (#1870) #1873 任何东西。
  • 27073b2 纯测试改动(tests/update-notes.test.ts +36/−10):把 feat: tiered release-notes visibility (#1870) #1873 UI 测试的硬编码版本跨度(0.1.179/180/181)改为从真实 VERSION 派生(patchBump(VERSION, ±n)),修的是 master 既有破损(feat: tiered release-notes visibility (#1870) #1873 落地的硬编码 fixture 在 0.1.180 发布后失效,本 PR 的 merge-tree CI 继承了红 lane)。干净、独立标注、仅测试;合并后 master 转绿。顺手加了一颗牙(≤running 的条目不进 span)。非阻塞微疵:patchBump 遇到 prerelease 形态版本号会响亮 assert 失败(fail-fast,可接受)。

验证汇总

本地:typecheck ✓;定向 52/52(zcode-native + zcode-json-edit + zcode-mcp-degraded,含两个新 e2e)。CI(最终 head 27073b2):主 CI run 37007385372 completed success + e2e(fake-codex/native-pi/native-dsh)+ build artifact 全绿。与你本地全量 3660/3641 pass / 0 fail / 19 skipped 一致。

合并前一件事

PR 正文的「Behavior change disclosure」段还写着诊断边界原话(does not fix the pre-init MCP exit),commit 3 之后已过时——建议更新正文以反映新范围(commit message 本身披露得很完整,正文对齐即可)。

判定:可合并。 合并操作按规约由你执行。

@ranxianglei

Copy link
Copy Markdown
Owner Author

新增:真实 zcode 客户端 canary CI lane(#1892 加固)

ci-zcode-real.yml + tests/zcode-real-cli.test.ts(gated by ACP_TEST_ZCODE_CLI)。下载官方固定版本 AppImage(3.14.4,sha256 钉死,actions/cache 按 checksum 缓存),提取真实 CLI bundle(resources/glm/zcode.cjs + 内置 provider registry),跑三件事:

  1. 真实 CLI 能启动(--version 语义合法);
  2. schema/路径 canary:bili 依赖的假设(.zcode/cli、provider_config.json、mcp.servers、providerRules)在真实二进制里仍然成立 —— zcode 上游改名会在这里响亮地红,而不是线上静默 "no route";
  3. spawn 契约:真实客户端从 cli/config.json 的 mcp.servers 发现并拉起我们的 mcp-entry([Bug] ZCode 3.14.4 原生插件:新版 providerRules 为空时 MCP 在初始化前退出,客户端报 Connection closed #1892 现场:空 store)。

实测发现(3.14.4 实机)

  • CLI 与桌面 host 的 personal-store schema 是两套:桌面 host 要求嵌套形 config.providerConfigRules.providerRules + config.modelConfigRules(缺一即 ZodError 降级为空配置);CLI 读扁平形 config.providerRules。bili 的 json-edit.ts 处理的是桌面嵌套形(即 issue 里用户文件的样子)✓。
  • 无 OAuth 登录时真实 turn 无法完成(Model creation failed),客户端在 turn 失败时立刻 SIGKILL 整个 MCP 栈 —— 所以握手级证明留在常规 matrix(zcode-mcp-degraded,官方 SDK 语义、真进程)里,这条 lane 验证到"真实二进制发现并拉起 entry"这一层(headless 的诚实上限)。
  • 新 workflow 文件在 pull_request 事件里用 base 分支的版本,不会在自己的引入 PR 上触发 —— 已加 master push(paths 过滤)触发器,合并后即自验。

触发条件

  • PR 改动 src/zcode/**、tests/zcode-*.test.ts、src/mcp.ts、workflow 自身;
  • master 过滤 push;
  • 手动 dispatch(可指定 zcode 版本,升版时同步改 ZCODE_SHA256 并复查 json-edit.ts 假设 —— canary 测试会提醒)。

ework-agent and others added 5 commits October 2, 2026 21:46
…e Connection closed (#1892)

routeZcodeConfig's zero-wrapped path logged only 'no routable provider entry
found', which surfaced to the client as an opaque MCP 'Connection closed'.
Add a read-only classifier (logNoRouteNextSteps) that names the real shape,
per ZCode source (#1892): an empty personal store is NOT 'no provider' — this
build sources active providers from the built-in/account layer, not the legacy
file — so legacy records are noted as migration leftovers, never as routing
targets. A personal store whose every rule is skipped by the v3.14+ client-
signing wall (#1621) names cert-MITM; mixed/other skips rely on the existing
per-entry skip list. Pure observability: never writes; routing behavior, #1621
signing protection, and #1622 direct/loopback exemptions are unchanged.

Diagnosis-only boundary: this does NOT fix the pre-init MCP exit or activate
compression. With routed===undefined mcp-entry still exits before runMcpStdio;
coding-plan accounts need native routing of the actually-active provider
(blocked by #1621) or the cert-MITM path (separate, to be verified on 3.14.4).

Tests: four #1892 scenarios pinning both the log classification and the
bootstrap outcome (active + routed undefined). zcode suite 48/48.
process.exit drops the logger's async file-stream buffer, and zcode captures none of this MCP child's stderr — so the final diagnostic lines of the zero-route path (incl. the #1892 next-steps classifier) were lost from bili.log in 8/8 empirical runs (attach mode, empty personal store; only the first logged line survived). Await closeLogger() — already exported for exactly this purpose — before all four early-exit paths in main(). Log durability only: no routing/wire/default/threshold change. Verified: typecheck clean, zcode suite 48/48, repro now shows the diagnostic in bili.log 8/8.
…1892)

Native routing that finds nothing to wrap (empty personal store, #1621
signing wall, missing store) no longer spawns a doomed proxy and exits
before the MCP handshake — the zcode client saw a bare 'Connection
closed'. planZcodeRouting() settles viability with a pure dry-run BEFORE
bring-up; the entry serves degraded: through any live proxy it can find
(cert-MITM boxes get the real ACP tools), else as an idle MCP server
(empty tools/list, loud isError on tools/call) whose handshake always
completes.
…spawn contract (#1892)

- ci-zcode-real.yml: download the pinned ZCode AppImage (3.14.4,
  sha256-pinned, cached), extract the real CLI bundle + bundled provider
  registry, run the canary on PRs touching src/zcode/** and on dispatch.
- tests/zcode-real-cli.test.ts (ACP_TEST_ZCODE_CLI): (1) real CLI boots,
  (2) config-path/store-schema assumptions bili's json-edit depends on
  still hold in the binary (.zcode/cli, provider_config.json,
  mcp.servers, providerRules) — upstream renames fail loudly here,
  (3) the real client discovers + spawns our mcp-entry from
  cli/config.json; a real turn needs OAuth so the handshake-level proof
  stays in the matrix suite (zcode-mcp-degraded).
pull_request events use the workflow file from the base branch, so a
newly added workflow never triggers on its own introducing PR — the
master push trigger makes it self-validate right after merge.
@ranxianglei
ranxianglei force-pushed the 2026-10-02_zcode-empty-store-diagnostic branch from 4053ebc to 6dc290c Compare October 2, 2026 13:47
actions/cache@v4 restores at the start of its OWN step. With the Cache step after Download, "if [ -f ZCode.AppImage ]" never matched on a fresh runner, so every run re-downloaded the full AppImage and the checksum-keyed cache was only ever saved, never used. Move the Cache step above Download; the post-download sha256 check still guards restored artifacts.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 canary lane 两个 commit(b7d681b8 + 6dc290c8)审完。发现一个真缺陷已直接修掉(commit 385cf15),最终 head 上 14/14 check-runs 全绿,含 zcode-real lane 本体(真 3.14.4 二进制实跑通过)。

结构化七问(本轮范围:canary lane)

1. 是什么问题:加固需求——bili 对 zcode 内部结构的假设(路径 .zcode/cli、store 文件名、mcp.servers、providerRules)此前只靠 issue 报告者的文件验证过,上游改名会线上静默退化成 "no route"→Connection closed,没有任何早期警报;也没有任何自动化证据证明真实客户端二进制仍能发现并拉起我们的 entry。

2. 什么原因导致的:假设与真实二进制之间没有绑定——没有固定版本的真实制品参与回归,假设腐化只能靠生产事故暴露。

3. 怎么修复的:钉死版本+校验和的官方 AppImage(3.14.4,sha256 硬编码,cache key 含 version+sha256,升版必须同步改 hash 否则响亮失败),三个测试:--version 启动语义;schema canary(四个 needle 在真实 bundle 里存在,失败信息直接指回「re-audit json-edit.ts」);spawn 契约(真实 CLI 从 ~/.zcode/cli/config.json 的 mcp.servers 发现并拉起 wrapper→我们的 entry,空 store = #1892 触发条件;stderr 若赶上 flush 则断言 degraded idle 行)。headless 上限如实标注(无 OAuth 模型→turn 必失败→客户端 SIGKILL MCP 栈,握手级证明留在 zcode-mcp-degraded 常规矩阵)——分层诚实,没有过度声称。

4. 是否回归:纯增量——compare 核实仅两个新文件,零存量改动;npm test 不受影响(ACP_TEST_ZCODE_CLI 门控默认 skip,与 ACP_TEST_E2E/REGISTRY 同惯例);安全面干净(permissions 仅 contents:read,无 secrets,下载后 sha256 强校验)。最终 head 上既有 lane 全绿(codex/pi/dsh/opencode overlay、hermetic registry ×2、test matrix ×4)。

5. 是否破坏缓存:不涉及运行时缓存/游标/去重键。(CI 侧的 AppImage cache 见下条我的修复。)

6. 是否改设计方向:不涉及——纯 CI 加固,产品行为零变化。

7. 是否引入新配置:无用户侧配置。ACP_TEST_ZCODE_CLI 是测试专用 env(沿用既有 ACP_TEST_* 惯例);workflow 的 zcode_version dispatch 输入单独指定版本时会撞死 sha256 校验而响亮失败——这是设计如此(升版必须同时改 hash,文件头有注释),安全方向正确。

我修掉的缺陷(385cf15,ci-zcode-real.yml)

actions/cache@v4 在自身步骤开始时才 restore——原顺序把 Cache 步骤放在 Download 之后,意味着新 runner 上 Download 步骤里的 if [ -f ZCode.AppImage ] 永远不成立,每次运行都完整重下 AppImage,按 checksum 键控的 cache 只存不读,注释里声称的 "unless cached" 从未生效。修复:Cache 步骤移到 Download 之前(+一行注释钉住这个顺序依赖,防止后人"整理"回去);restore 出来的产物仍走 sha256 复验(顺带防缓存投毒)。YAML 语法已验证(8 步骤,顺序 checkout→setup-node→cache→download→extract→install→build→canary)。注:你在我推送前刚好 rebase 过,该 commit 是基于 blob sha 落在 rebase 后的链顶(6dc290c8 之上),无冲突。

对你 rebase 的观察(确认无误)

我审到一半时分支已从 dirty(与 master 冲突)变为可合并:你把分支 rebase 到 e60d6cd 并丢掉了 27073b2(update-notes fixture 修复)——正确处置:master 的 #1922 已经落了等价修复(RUNNING/SURFACE_ENTRIES 方案,实现不同但意图相同),两边都留必然文本冲突。被丢 commit 里多出的那颗牙("≤running 条目不进 span")在 master 上有纯函数级覆盖(spanNotes 排除 running 本身),无丢失。

实测发现核对

你列的三条(桌面嵌套形 vs CLI 扁平形两套 schema、无 OAuth 时 SIGKILL 整个 MCP 栈、pull_request 用 base 分支 workflow 故加 master push 触发器)与代码/测试所编码的内容逐条一致,判断准确。

非阻塞微疵(记录不修):下载 curl 无 --max-time(有 job 级 timeout-minutes:15 兜底,可接受)。

验证汇总:本地 YAML 校验 ✓;CI @385cf155 = 14/14 success(build-artifact、version-guard、test matrix ubuntu/windows×22/24、hermetic registry e2e×2、codex/pi/dsh/opencode/codex-overlay 全 lane、zcode-real)。

判定:可合并。 合并后 master push 触发器会让这条 lane 在未来每个触碰 zcode 路径的合并上自验;升版时按文件头纪律同步 ZCODE_SHA256 即可。合并操作按规约由你执行。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant