前端改动换的是磁盘上的一堆静态文件,部署它的最小单位应该是一根指针,而不是一个进程。

1. 问题:一次改色,一整套重启仪式⌗

MaxClaw 会改自己的代码。一个任务在自己的分支上写完改动,交给落地通道:合并、验证、推上 main,然后部署。部署的完整通道是为后端设计的:

整跑测试 → 新建不可变 release → 预演(rehearsal)→ 重启主进程 → 5 分钟试用期(probation)

这套流程对后端是对的:主进程的模块图变了,就只能换进程;换进程有风险,所以要预演和试用。

但设计文档里写着一个不太体面的数字:每批纯 UI 改动,从交出到上线要 20–30 分钟。改了一个 CSS 变量,主进程也要重启一次,正在跑的后台任务还要先等、再挂起。

而前端静态文件本来就是主进程按请求从磁盘读的。旧的部署计划把 UI 改动标成必须重启,理由写在代码里:

return { restart: true, reason: 'WebUI 静态文件来自运行中的只读 release/ui/dist,构建验证不替换正在提供的产物' }

这句话说的是现状,不是必然:之所以要重启,只是因为没有别的办法把新文件交给正在运行的进程。这次改动补上的就是这个办法,叫「UI 快车道」。

2. 谁说了算:diff,不是任何人的自述⌗

先回答哪些改动能走快车道。最省事的做法是让任务自己声明「我只改了前端」,或者让负责落地的 Maintainer 判断。这次的设计把这两者都排除了,classify.ts 开头就写:

The machine decides from the diff against main; what the task or the Maintainer says about its own change is no input.

原因很简单:一个系统改自己的代码时,声明者就是被审查者。让它自己说走哪条通道,这道门就形同虚设。

判定规则分两层:

层条件结果
路径改动全部在 ui/**、docs/** 下继续往下判
路径碰了 src/(含迁移)、skills/、prompts/、scripts/、watchdog/、package.json/bun.lock,或任何其他路径(含根目录文件)完整通道,理由写出命中的路径和规则
路由前端新增行里调用了服务端没有登记的 /ui/api/*、/api/*、/ws/*完整通道,理由写出路由
路由新增了目标无法静态判定的 fetch( / WebSocket( / EventSource( / sendBeacon(完整通道(从严)

第二层是关键。只看路径不够:一个纯前端改动完全可能去调一个后端还没有的接口。它在合并树里能过 tsc,能过构建,热替换上去以后才 404。所以判定器要从 diff 的 + 行里按字面量抠出 API 路径,再拿去和服务端代码里的路由字面量对照:

const API_LITERAL = /(['"`])(\/(?:ui\/api|api|ws)(?:\/[^'"`]*)?)/g
const CALL_SITE = /\b(fetch|WebSocket|EventSource|sendBeacon)\s*\(\s*(?!['"`]\/(?:ui\/api|api|ws)\b)([^\n]{0,60})/g

对照时,:param、{param}、${expr} 都算一段,字面 * 匹配剩下的任意段,以 / 结尾的前端字面量按前缀算。测试里有几条边界值得一看:

输入判定
fetch('/ui/api/threads?limit=5')路径 /ui/api/threads,查询串丢掉
fetch(`/ui/api/web-sessions/${name}/fork`) 对 /ui/api/web-sessions/:name/fork已登记
/ui/api/threads/extra,服务端只有 /ui/api/threads未登记:前缀相同不算
new WebSocket(`${proto}//${host}/ws/chat`)第一个参数不是字面 API 路径,无法判定 → 完整通道
fetch(url, { cache: 'no-store' })同上
uix/a.ts、docsy/a.md不是 ui/、docs/,完整通道

这是一个故意做得很笨的静态扫描。它不做数据流分析,抠不出确定的字面量就判「我不知道」,而「不知道」在这里的意思就是走完整通道。它会误判,但只会往慢的方向误判。

还有一个容易漏的细节:判定做两次,对照的服务端不同。

落地验证时:diff = 分支 vs main,服务端 = 合并后的树
部署时    :diff = 这一批 vs 上一个部署点,服务端 = 正在运行的 release 目录

第二次复核的理由是:热替换上去的前端,是跑在现在这个进程上的,不是跑在 main 上的。main 上也许已经有了新路由,但它要等下一次重启才会进入运行中的 release。拿 main 对照会得出「路由存在」这个对的结论,但对错了对象。复核不过,这一批就改走重启。

3. 验收没有变松,反而加了一道⌗

很多「快速通道」的做法,是用少测换快。这里不是。看 verificationPlan 的变化:

情况以前现在
纯 UI 改动(无分类器)level 2level 2(测试 without a classifier nothing changes 锁住)
纯 UI,判为快车道—level 3:受影响单测 + tsc(根与 ui/)+ UI 构建 + 页面冒烟
纯 UI,判为完整通道(如新路由)—level 3:单测 + tsc,无冒烟

快车道的验证比原先纯 UI 的等级还高,测试也在和完整通道同一台测试机上、按同一套重跑和归因规则跑。省掉的时间来自部署那一端:不建新 release、不预演、不重启、不试用。验证这一端一步也没少。

新增的那道是页面冒烟,由三件东西组成:

            ┌───────────────── 临时静态服务(随机端口)─────────────────┐
无头浏览器 ──►  /ui/**         → 刚构建的 dist(或上线后:生产自己)      │
            │  /ui/api /api /media → 代理到生产,只放行 GET/HEAD,其余 405 │
            │  /ws/**        → 代理到生产,页面发出的帧只转 {"type":"ping"} │
            └──────────────────────────────────────────────────────────────┘

只读代理是整套冒烟里最值钱的一行设计。冒烟要用生产数据渲染页面,比如打开一个真实存在的对话,否则「页面渲染出内容」这个判据就没有意义。可是被测的是一个还没有验证过的前端。它在页面加载时发一个 POST,或者在 socket 上发一条「标记已读」,都会改动生产状态。于是代理只放行 GET/HEAD,其他方法一律 405 并记录;socket 上页面发出的帧只转发心跳,其余丢弃并计数。server.test.ts 专门有一条测:「of the page’s frames only the keep-alive ping reaches production」。

被测页面可以看生产,但改不了生产。

页面清单(pages.ts):欢迎页(点「新建 side chat」)、一个现有对话、主对话、对话设置面板(点开)、控制台 12 个 tab。共 16 页,每页在 light、dark、glass 三个主题下各跑一次,计划 48 次访问。

判定(judge.ts)是一个纯函数,只看四件事:

if (obs.rootChildren === 0) failures.push('根节点没有渲染出内容')
for (const error of obs.pageErrors) failures.push(`未捕获异常:${error}`)
for (const text of obs.consoleErrors.filter((t) => !isKnownNoise(t))) failures.push(`console.error:${text}`)
for (const selector of obs.missing) failures.push(`缺少关键元素:${selector}`)

console.error 的白名单只有一条,而且条目自带理由:聊天页会给每个对话探一次某个可选绑定,没有绑定时服务端按设计回 404。除此之外的任何 console.error 都算失败。我觉得这个白名单的写法值得抄:每条放行都必须写清楚为什么放行,没写的一律不放。

还有两条和失败语义有关的规则:

  • 第一个失败的页即停。 改动已经被否决,再跑 47 页只是花时间。
  • 浏览器起不来、生产不应答,算「没有结论」(SmokeInfraError),不算改动失败。落地留在队首等环境恢复,不会因为测试机出了问题就把改动退回。这个区分在整个落地通道里反复出现:基础设施的失败不能记到被测改动头上。

每页一张截图,存在 acceptance/<落地 id>/smoke/<主题>/<页>.png,目录和摘要写进落地记录。之后有人问「这一版上线前长什么样」,有据可查。

4. 上线:一根绑定 release 的指针⌗

4.1 机制⌗

新构建放进 data/ui-live/versions/<id>/(先建到 <id>.building,完成后 rename),然后原子地改写 state.json(写临时文件再 rename):

interface UiLiveState {
  v: 1
  base: string | null            // 这根指针是为哪个 release 做的
  active: UiVersion | null       // null = release 自带的 ui/dist
  previous: UiVersion | null     // 回滚回到哪
  switchedAt: number
  reason: string
}

主进程这边,原来的模块级常量 UI_DIST_DIR 改成了函数 uiDistDir(),每个静态请求解析一次:

export function resolveLiveUi(opts: { root: string; releaseDist: string; base: string | null }): LiveUi {
  const state = cachedState(opts.root)
  if (!state?.active || state.base !== opts.base) return { dir: opts.releaseDist, version: null }
  const dir = versionDir(opts.root, state.active.id)
  if (!existsSync(join(dir, 'index.html'))) return { dir: opts.releaseDist, version: null }
  return { dir, version: state.active }
}

每次请求 stat 一次 state.json,按 mtime + size 缓存解析结果。代价是每个静态请求多一次 stat。换来的是:主进程不订阅任何事件,不开第二个监听端口,不需要「通知进程换目录」这条通道。

4.2 为什么不用符号链接、不用事件⌗

设计文档对此有一段明确的取舍,整理成表:

方案问题
符号链接 ui/dist → versions/x原子性没问题,但链接里放不下 base,没法表达「只对某个 release 有效」
主进程订阅切换事件多一条进程间通道,多一个失败模式(事件丢了怎么办、进程刚重启错过了怎么办)
指针文件 + 每次请求解析多一次 stat;切换对在飞请求是原子的:旧请求读旧目录,新请求读新目录,两边文件都在

构建目录不可变,所以回滚就是再换一次指针,不需要重建,也不需要「恢复」。

4.3 base:这根指针最重要的字段⌗

如果没有 base,会出现一个很隐蔽的回退问题:

t0  release R1 运行,快车道把 UI 换成 v7
t1  一个后端改动走完整通道,重启到 R2
    R2 自带的 ui/dist 是当时 main 的最新,已经包含 v7 的改动,还可能更新
t2  如果指针仍然生效 → R2 被指回 v7 目录 → 前端被悄悄换回旧版

base 把指针钉在它所属的 release 上:

场景结果
重启到新 releasebase 不符,指针被忽略,服务 release 自带的构建(即 main 最新)
同一 release 重启(自愈、同 release 重启)指针继续有效
回滚到更旧的 releasebase 不符,指针被忽略
没有 release 标记的代码树(开发、测试实例)base = null,只和同样为 null 的指针配对
指针指向的目录被删了回落到 release 自带构建

ui-live.test.ts 里有一条用例的名字就是这个结论:「a restart onto another release serves that release’s own build, never the older fast-lane directory」。

换句话说,快车道上线的东西都是临时的。下一次完整发布会把它们并进新 release,指针自然作废。快车道没有另起一条与 release 平行、需要单独维护的版本线,它只是在两次 release 之间临时挂上去的一层。

5. 切换之后再冒烟一次,失败就换回指针⌗

hotSwapUi 的步骤:

probe   GET /ui/api/ui-live → 运行中的进程报出自己的 base 和正在服务的版本
        不应答 / 没这个接口(旧 release)→ unsupported → 这一批改走重启
build   在部署目标 commit 的 worktree 里构建到 versions/<id>.building → rename
switch  原子改写 state.json
verify  再问一次进程:你现在服务的是不是 <id>?不是 → 指针退回,infra
smoke   对生产自己再跑一遍全部页面(dist: null,页面和文件都从生产取,仍只读)

结局有四种,每种的处理都不同:

结局指针落地部署
switched新版running完成
unsupported不动—这一批改走重启
smoke-failed退回上一版走已有的失败路径:main 上 revert,Maintainer 被叫醒,改动退回任务继续处理下一批
infra(构建失败、切换后没生效、冒烟没结论)退回上一版stuckpaused,land.ts deploy --resume 重试

几个细节说明这里考虑过失败路径:

  • 验收时已经冒过一次烟,上线后为什么还要再跑一次? 验收冒烟的静态文件来自临时服务,上线冒烟的文件来自生产进程自己的路由,经过的是真实的 uiDistDir()、真实的回落逻辑和真实的 build-info.js。前一次证明这份构建没坏,后一次证明它上线以后也没坏。
  • 回滚回到上一个快车道版本,而不是 release 自带的版本(hot-swap.test.ts:「rolls back to the build that was live before, not to the release’s」)。如果连续两次快车道、第二次失败,用户看到的应该是第一次的结果,不该连第一次也一起丢掉。
  • 构建失败不留半成品:.building 目录被删掉,指针不动。
  • 通知发不出去,不会把回滚变成错误:通知失败只写日志。回滚已经完成,不能因为通知没送达就报告「回滚失败」。

端到端测试 fast-lane.browser.test.ts 在一次性的主进程上(随机端口、临时 home、一次性数据库)走了两遍完整流程:

  1. 往 styles.css 追加一个带标记的 CSS 变量 → 判为快车道 → 构建 → 冒烟 → 热替换 → 运行中的进程提供的 CSS 含标记、href 变了 → 回滚 → CSS、chat.html、build-info.js 都逐字节回到原样;全程断言 instance.exitCode() 为 null,进程没退出过。
  2. 在聊天页入口顶部插入 throw new Error(...) → 仍然判为快车道(路径和路由都合规)→ 热替换 → 上线后冒烟失败 → 指针自动退回、通知恰好发出一条且正文带着那条异常 → CSS 原样。

第二个用例很能说明问题:判定只管「这个改动有没有资格走快车道」,管不了「这个改动对不对」。改动对不对,由冒烟和回滚兜底。

6. 批次:快车道不和完整通道混跑⌗

落地通道本来就会把多个落地合成一批来验证和部署。快车道加了一条规则:快车道落地不和完整通道落地合批。

if (records.length && (r.solo || needsTests !== tests || batchFast !== fast)) break

道理在部署那一端:一批里只要有一个后端改动,这一批 diff 的并集就超出了 ui/、docs/,整批都要重启。这时候前端改动随新 release 上线,本身没问题,但它会被后端改动的预演和试用拖慢,后端改动一失败还会连带被回滚。分开排队,两边就不会互相拖累。

7. 不解决的事⌗

这个设计也有它不管、或者管得不完美的地方,代码和文档都写明了:

局限现状
已经打开的页面不会被换掉旧 index.html 引用的哈希 chunk 在新 dist 里没有时,拿到的是 SPA 兜底;硬刷新即可,PWA 的 service worker 会自己更新。这一点和完整通道重启时一样
回滚只有一步深rollbackUiLive 之后 previous 置空;再回滚一次就回到 release 自带构建,不是更早的快车道版本
路由对照只看字面量存在服务端代码里出现了这个路径字面量,就算「已登记」;它不核对 HTTP 方法,也不证明这个字面量真的是一条注册的路由
磁盘上的版本保留激活的、上一版和最近 5 个,其余在切换时清掉
实际耗时本文没有实测数字。下限可以从常量估:每页截图前固定等 1.2 s,满跑 48 次访问仅等待就约 1 分钟,冒烟在验收和上线各跑一次;加上测试、tsc 和两次构建。「分钟级」是按这些组成推出来的,不是测出来的

路由对照那一条是有意为之。精确地判定一个前端调用能否被服务端应答,需要类型级的契约或者运行时探测,两者都比一个正则贵得多。这里选了便宜、能被测试锁住、出错只会往保守方向偏的方案,真正的兜底仍然是上线后的冒烟。

8. 小结⌗

把这个改动拆开看,其实是三件互相独立的事:

  1. 通道由 diff 决定,不由改动者的自述决定。对一个自己改自己的系统来说,这是门禁能成立的前提。
  2. 快和松是两回事。 快车道省掉的是部署环节的仪式(新 release、预演、重启、试用期),验证环节反而加严了。安全靠的是只读冒烟和能立刻撤回的切换,不是「这只是前端,问题不大」。
  3. 部署的最小单位应当和改动的最小单位对齐。 前端改动换的是一个静态目录,那就只换目录。指针上带 base,保证这次替换的效力不会延续到下一个 release。

旧代码里那句「构建验证不替换正在提供的产物」,说的其实是当时还没有替换手段。补上一根指针文件之后,这个限制就不存在了。