账本说「已上线」,生产进程说「我没见过它」

自动化发布最危险的不是失败,而是失败了还很自信地报成功。这篇讲 MaxClaw 怎么不再读账本判断「上线了没有」,改成去问生产进程本身。
1. 症状:一条很体面的谎报⌗
MaxClaw 改自己代码的链路大致是这样:
任务分支 ──► Maintainer 验收 ──► 落地通道(lane)
│ fast-forward 进 main
│ 部署步骤:要不要新 release?
│ 要 → 构建 releases/<tree>,guardian 重启进试用期,度过后 promote
│ 不要 → 记 deploy.state = running(「源码树更新即可」)
▼
Maintainer 对账:deploy.state = running → resolved
「xxxx 上线并度过试用期」→ 告诉发起方
问题出在最后一步。Maintainer 的对账逻辑改动前是这样的:
switch (rec.deploy?.state) {
case 'running':
await this.resolve(current, rec) // 记账说在跑,那就是上线了
return
deploy.state 是部署步骤自己得出的结论,不是生产的状态。于是出现了这样一个组合:
| 来源 | 说了什么 |
|---|---|
落地记录 deploy | running,说明是「无需部署:no main runtime file changed」 |
| Maintainer | 「已上线并度过试用期」 |
| 生产进程 | 几小时前启动,跑的是更早的 release tree |
releases/ | 根本没有这次落地对应的 tree |
| guardian 的 promote 记录 | 最后一次晋升早于这次落地 |
五个来源里前两个互相引用,后三个才是事实,而且三者口径一致:这次改动从来没跑在生产里。
2. 账本为什么会错:skill 热加载的一个盲区⌗
要不要新 release,由 deploymentPlan 决定:拿这次改动的路径,去和「主运行时模块图」比对。模块图是 mainRuntimeFiles 用 Bun.build 的 metafile 算出来的,只分析、不执行代码。改动前它只有一个入口:
entrypoints: [join(root, 'src/start.ts')]
而 skill 走的是另一条加载路径。skill 会从源码树热加载,不用重启;但它 import 的核心模块,取的是正在运行的 release 里的那份。src/hot/skill-layout.ts 的做法是建一个镜像目录:
mirror/
├── skills/ ← 源码树 skills/ 的拷贝(热更新)
├── src ──symlink──► releases/<running tree>/src (冻结在 release 里)
└── ... ──symlink──► releases/<running tree>/...
所以一个只被某个 skill 引用、主入口根本不会走到的核心模块,改了以后:
- 从
src/start.ts出发的模块图里没有它 →deploymentPlan说「no main runtime file changed」; - skill 热加载后 import 到的是 release 里的旧版本 → 改动实际不生效;
- 账本记
running,Maintainer 报上线。
修复第一半很直接:skill 入口文件(tools.ts / matchers.ts / connections.ts,即 SKILL_ENTRY_FILES)也作为 bundler 入口参与分析,再把 skills/ 下的路径从结果里滤掉:
entrypoints: [MAIN_RUNTIME_ENTRY, ...await skillEntryPaths(root)].map((p) => join(root, p)),
// ...
.filter((path) => !path.startsWith('skills/'))
过滤这一步很关键。skill 本身仍然是热的,改 skill 文件不应该触发重启;被 skill 拉进来的 src/ 模块才算主运行时文件。测试把这两边都钉住了:
expect([...runtime.modules].sort()).toEqual(['src/runtime/research.ts', 'src/start.ts'])
expect(deploymentPlan(['src/runtime/research.ts'], runtime).restart).toBe(true)
expect(deploymentPlan(['skills/research/tools.ts', 'skills/research/helper.ts'], runtime).restart).toBe(false)
3. 但只修这个漏洞不够⌗
如果到此为止,这次修复就是「把那个判断改对了」。可是下一次部署步骤的判断还会以别的方式出错:新的加载路径、一个没想到的符号链接、一次中途失败的构建。只要 Maintainer 还在读部署步骤的结论,任何一种判断错误都会原样变成一次谎报,而且是带着「度过试用期」这种很具体的措辞去谎报。
所以第二半修复才是主体:**「已上线」不再从账本推出,而是去问生产。**新增的 src/landing/live-check.ts 读三件事:
| 事实 | 来源 | 回答的问题 |
|---|---|---|
| process | 生产进程自己写的 data/runtime/main-process.json(pid、启动时间、release tree / commit) | 现在跑的到底是哪个 release? |
| release | releases/<tree> 是否已构建 | 这个 tree 真的存在吗? |
| promote | guardian 的 state.json:probation、known-good、history 里的 promote | 它度过试用期了吗? |
三者都是别的组件为了自己的目的写下的记录:进程记录是给重启逻辑用的,release 目录是 guardian 启动时要用的,promote 历史是回滚用的。它们没有一个是「为了回答上线没有」而写,所以不会和部署步骤犯同一个错误。
4. 判定逻辑⌗
liveVerdict(落地记录)
├─ 没有落地 commit → not-live
├─ 读不到进程记录 / 记录里没有 tree、commit → not-live
├─ releases/<运行中的 tree> 不存在 → not-live
├─ 运行中的 commit 包含这次落地(merge-base --is-ancestor)
│ ├─ 这个 tree 正在试用期 → pending(下个 tick 再问)
│ ├─ 不是 known-good,也没有 promote 记录 → not-live
│ └─ 否则 → live
└─ 运行中的 commit 不包含它
├─ 用「运行中 release 自己的」模块图重算 deploymentPlan
│ └─ 确实不需要新 release → live
└─ 需要 → not-live,附四条证据
有两处设计值得多说一句。
**第一,「不需要新 release」要用运行中 release 的模块图重算,而不是落地 commit 的。**问题的本质是「正在运行的东西会不会读到这些文件」,那就应该拿正在运行的东西的依赖图来回答。runtimeOfRelease(tree) 直接分析 releases/<tree> 目录,按 tree 缓存(失败时从缓存删掉,下次重算)。即便将来模块图的算法又出现盲区,这一层的回答至少和生产的实际依赖对齐,而不是和某个 commit 的理想状态对齐。
**第二,所有读不到、对不上的情况一律判 not-live(fail closed)。**进程记录丢了、release 目录被清掉、promote 缺失,都不报上线。唯一的例外是没开 release 布局(MAXCLAW_RELEASES 未设置):那种部署下进程直接跑源码树,没有 release 可对,直接判 live,并且在 detail 里写明原因。
not-live 时给出的证据是逐条写出来的,测试里断言了它们的样子:
生产进程 pid …(… 启动)运行 release <old>(commit <old>),不含 <new>
releases/<new tree>(这次落地的 tree)不存在
state.json 最后一次晋升:<old> @ …,早于这次落地(…)
它需要新 release:src/…: main runtime module graph changed
这四行就是第 1 节表格里后三个来源,外加一条「为什么它本该需要新 release」。拿到它的人不需要再去翻日志重建现场。
5. 对不上时,单子回到人手里⌗
Maintainer 的对账改成:
case 'running': {
const live = await ports.landing.live(rec)
if (live.kind === 'pending') return // 还在试用期:什么都不说
if (live.kind === 'not-live') {
await this.attend(current, 'deploy-not-live', notLiveText(rec, live.evidence))
return // 回到 reviewing,唤醒 Maintainer
}
await this.resolve(current, rec, live.detail) // resolved 记录里带上生产核对的原文
return
}
deploy-not-live是新的唤醒原因,渲染成「记账说已上线,生产没有运行它」。单子回到reviewing,Maintainer 被唤醒,正文列出证据,并给出下一步的选择:重新入队、等下一次部署,或交回派出它的对话。- 发起方在这期间什么都收不到。测试
the ledger says running but production does not run it断言了resultsTo(w, w.origin)长度为 0:宁可晚报,也不错报。 - 真的上线时,
resolved那条历史不再只写「上线并度过试用期」,而是附上「生产核对:…」原文(截断到 600 字)。以后谁怀疑这条记录,可以直接看它当时依据的是哪个进程、哪个 tree。
6. 取舍⌗
| 选择 | 代价 | 为什么接受 |
|---|---|---|
每次对账都读进程记录 + state.json + 一次 git merge-base | 每个 tick 多几次文件读和一次 git 调用 | 只对处在 landing 的那一单做,一次只有一单 |
| 不包含时在运行中 release 上跑一次 bundler 分析 | 首次分析要几秒 | 按 tree 缓存,同一个 release 只算一次 |
| 读不到任何一项就判 not-live | 偶发的记录缺失会让 Maintainer 被多叫醒一次 | 多叫醒一次的代价远小于一次谎报:谎报之后没人会再回来看 |
| pending 不发任何消息 | 试用期内发起方没有中间进度 | 试用期失败会走 deploy-reverted,不会被静默吞掉 |
保留部署步骤的 deploy.state | 两套口径并存 | 账本仍然决定「什么时候去问」,只是不再决定「答案是什么」 |
最后一行是这次设计的核心分工。账本没有被废掉,它依然是很好的触发器:running 表示部署步骤认为自己做完了,这是去核对的好时机。只是它不再是判据。
7. 证据⌗
测试就是规格,三个文件在写作时于主干重跑,53 pass / 0 fail。live-check.test.ts 的 7 个用例覆盖了第 4 节判定树的每一个分支:
| 用例 | 结论 |
|---|---|
| 账本 running,进程跑更早的 release | not-live,证据含进程、release、promote、模块图四条 |
| 进程、release、promote 三者一致 | live |
| 运行中 release 含它但在试用期 | pending |
| 含它但既没晋升也不在试用期 | not-live |
| 进程跑的 release 目录不存在 | not-live |
| 改动只碰文档与 skill 文件 | live(无需新 release) |
| 没有进程记录 | not-live |
runtime-files.test.ts 新增一例,钉住「skill 拉进来的核心模块需要 release、skill 文件本身保持热更新」;maintainer.test.ts 新增两例:not-live 时单子回到 reviewing、发起方收不到结果、唤醒正文带证据;pending 时单子停在 landing、什么都不发。
8. 一点反思⌗
回头看,旧逻辑的错误不在某一行代码,而在一个很自然的假设:写账本的组件知道真相。部署步骤当然认为自己知道,它就是负责部署的。但「我做完了部署」和「生产在跑我部署的东西」是两件事,中间隔着构建、重启、试用期、晋升,以及一个热加载机制和 release 之间的符号链接。
给 agent 系统做自动化发布时,这条尤其要紧。人类工程师报「上线了」之前,多半会顺手刷一下页面;agent 不会,它读到什么就报什么,而且会报得很笃定。所以「上线了没有」这个问题,答案必须来自生产进程本身,而不是来自负责部署的那个组件写下的账本。