自动化发布最危险的不是失败,而是失败了还很自信地报成功。这篇讲 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 是部署步骤自己得出的结论,不是生产的状态。于是出现了这样一个组合:

来源说了什么
落地记录 deployrunning,说明是「无需部署: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?
releasereleases/<tree> 是否已构建这个 tree 真的存在吗?
promoteguardian 的 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,进程跑更早的 releasenot-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 不会,它读到什么就报什么,而且会报得很笃定。所以「上线了没有」这个问题,答案必须来自生产进程本身,而不是来自负责部署的那个组件写下的账本。