wait4xandGLM-5.3
541710b50a
四节+结语：19 连发压力日引入 / spec 任务包（blog-5f 实引 verify 原文与已证伪路径）/ mesh 交通规则（契约式下达-预约拦刀实录-守卫 铁律）/ 纪律从事故长出来（验收先探实值-口径错配-五段式运维-视觉 双轨-解封后 SEO 100）。全部数字与命令对档核验。 车道：worker-one（1906 字/schema 过/lint 0 违例）；收编补引文精度 （T1 verify 对齐原文四条件） 验证: pnpm astro build 36 页；E2E 34/34；content-lint 0/0/0 Spec: none (内容文章，车道级交付) Co-authored-by: GLM-5.3
78 lines
7.2 KiB
Markdown
78 lines
7.2 KiB
Markdown
---
|
||
title: "单人博客的多智能体工程：spec 任务包与 mesh 协同"
|
||
pubDate: 2026-11-01
|
||
category: tech
|
||
tags: [工程实践, AI 协作]
|
||
---
|
||
|
||
这个博客表面是一个人的产物：一个仓库、一条 push 即自动构建发布的管线。但真正干活的是一个小队——我带着几个跑在独立终端里的 agent。2026-10-25 是压力测试日：main 分支一天 19 连发（a10141d 到 3a59edc），两条 mesh 车道与主线并行，中间还插着视觉复核。人多了手就杂：谁在动哪个文件？怎么证明一件事真的做完了，而不是"看起来好了"？发布链半夜炸了谁来收？这篇复盘我们在实战里沉淀的两套基建：spec 工作流负责"合同"，mesh 负责"交通"。
|
||
|
||
## 一、spec：把任务写成可验收的合同
|
||
|
||
多 agent 协作最先崩的不是代码，是记忆。一个任务跨了好几轮对话，改到一半的方案、已经否决的路、验收口径，散落在聊天记录里就等于丢了。spec 工作流的解法很朴素：开任务包，把一切写进仓库。
|
||
|
||
每个任务包是 `.spec/specs/` 下的一个目录（收尾后归档进 `.spec/specs/archive/`），核心是两个文件：`spec.md` 写范围、假设与取舍，`tasks.md` 写任务清单。每个任务必须带两行：
|
||
|
||
- **boundary**：这个任务能动哪些文件，白纸黑字；
|
||
- **verify**：怎么证明做完了——只读断言，跑通退出码 0 才算勾。
|
||
|
||
以 2026-10-26 收官的 blog-5f 包（SEO 解封 + 美化首批，八个任务）为例，T1 的 verify 长这样：
|
||
|
||
```bash
|
||
test -f public/robots.txt \
|
||
&& grep -q "Sitemap: https://wait4x.online/sitemap-index.xml" public/robots.txt \
|
||
&& grep -q "Disallow: /admin" public/robots.txt \
|
||
&& grep -q "SEO 解封操作单" docs/上线检查单.md
|
||
```
|
||
|
||
不是"robots.txt 已配置"，而是一条能跑出退出码的命令。涉及页面的任务统一指向 E2E：`E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs`，34 项全过才算数。
|
||
|
||
任务还标了归属：`claim: op-gitea`、`claim: op-artalk`（两条 mesh 车道）或 `claim: orchestrator`（主线独占集成权）。共享文件按 boundary 划界——全局样式的 tokens.css 只许主线动，车道需要新变量就提需求，不许自己伸手。
|
||
|
||
spec.md 里我最喜欢的一节叫"已证伪路径"：首屏 banner 化、热力图换绿、标题 27px 收到 22px——被视觉模型否决的方案连否定理由一起入库。下次有人（包括未来的我）想再试一遍，先读档案，少烧一轮预算。
|
||
|
||
门禁收口：`/spec:check` 复核、`/spec:done` 归档提交、`/spec:push` 合并。验收必须有真实证据（脚本输出、测试结果），口头"过了"不算数；被阻塞的任务打 `!` 标记上浮给人，绝不静默跳过。八个任务全部勾完、验收面全绿，包才归档——归档目录本身就是这个项目的工程日志。
|
||
|
||
## 二、mesh：多终端的交通规则
|
||
|
||
spec 解决"写什么"，mesh 解决"谁在线、谁在干什么、别撞车"。
|
||
|
||
每个终端以别名加入本机 mesh 总线的房间，这个项目用 `blog` 房间。派任务不用喊话，而是契约式 `mesh_send`：先 `mesh_reserve` 预约产出文件路径，再给 boundary、verify 与完成动作。你正在读的这篇文章就是这么被派下来的——动笔前我先预约了 `content/posts/spec-workflow-and-mesh.md`，写完还要回复派单方、往团队板留痕。
|
||
|
||
这套机制也有粒度教训：早期一条车道图省事预约了整棵目录树，把隔壁车道的兄弟文件一并挡住；后来收敛成文件粒度，预约范围与 boundary 对齐。需要一群 agent 各自表态时用 `mesh_wait_all` 等群裁：它返回"谁答了、谁没答"的名单，而不是自己盯着屏幕轮询。
|
||
|
||
`mesh_reserve` 是真实救过场的机制。10-25 20:31 发布链中断：build.sh 裸引用了一条车道里尚未收编推送的新脚本，而构建仓 checkout 的是 origin/main，没有这个文件，连续三次全队构建炸掉、staging 冻结。修复窗口里一条车道预约了 build.sh 紧急处置，我提刀赶去补刀，编辑被正确拦下——撞车靠机制防住，不靠谁手快。
|
||
|
||
这次事故还沉淀出一条铁律：被 `infra/deploy/build.sh` 引用的新文件，存在性守卫必须是第一笔改动——
|
||
|
||
```bash
|
||
[ -f scripts/build-perf/content-lint.mjs ] && node scripts/build-perf/content-lint.mjs dist || echo skip
|
||
```
|
||
|
||
文件没到，构建降级跳过，而不是全队陪葬。
|
||
|
||
第三个组件是 board（团队记忆板）：类型化条目——OBSERVED（看到什么）、FACT（验证过什么）、FAIL（证伪了什么路）、CLAIM（认领了什么）、PATCH_SUMMARY（落了什么改动），写入即广播到房间，可全文检索。价值最大的是 FAIL：一条被证伪的路变得可搜索之后，整个房间不必为它烧第二次预算。重试任何方案前先 `board_grep` 一遍，是这个房间的肌肉记忆。
|
||
|
||
## 三、纪律从事故里长出来
|
||
|
||
这套基建里最值钱的不是工具，是事故换来的纪律。
|
||
|
||
**验收先探实值。** E2E 断言出过两次假 FAIL，都是选择器里猜的类名与真实 DOM 对不上；还有过截图"看起来正常"、`document.fonts.check()` 实测字体根本没加载的翻车。之后所有断言动笔前必须先 grep 源码拿真实类名——眼见为实，升级成实测为实。还有口径：验收必须打在与改动相同的产物上——曾对着部署着 origin/main 的 staging 断言工作树里未提交的修复，白绿一场；之后 E2E 一律本地起服务对着自己构建的 dist 跑，口径错了，断言再严谨也是自我安慰。
|
||
|
||
**运维脚本五段式。** SEO 事故是最好的样本：全站自上线起被 `X-Robots-Tag: noindex` 封印，根因是 nginx 共享 snippet（`/etc/nginx/snippets/esa-origin-ssl.conf`）里一行给内部服务设计的头误伤了博客 vhost，叠加 robots.txt 404 和 ESA 边缘 30 天 HTML 缓存，Lighthouse SEO 只有 60-63。最阴的一环在缓存：noindex 响应头固化在边缘缓存对象里，源站修完不 purge，爬虫一个月内照旧看见封印。所以修复脚本 `scripts/ops/seo-unblock.sh` 把仓库侧能自动化的固化成：现状展示 → DRY-RUN 列变更计划 → 人工确认（默认拒绝）→ 执行（先备份）→ `nginx -t` 失败自动回滚 → curl 终验，结尾再打印 ESA 控制台的手动步骤清单。改生产配置从此没有"直接上手"这个选项。
|
||
|
||
**视觉双轨。** 美化方案由文本模型出稿，但"好不好看"交给视觉模型逐图裁定，实现与裁定冲突时以裁定为准。人的直觉在这条流水线里做终审，不做初稿。
|
||
|
||
解封后生产复测：SEO 全页 100/100。
|
||
|
||
## 四、这套东西的普适性
|
||
|
||
回头看，没有一环绑定在"博客"上：
|
||
|
||
- 任务包 = 范围与验收的合同，进 git，跨会话不丢；
|
||
- mesh 房间 = 多终端的交通规则：预约、群裁、留痕；
|
||
- board = 团队记忆，失败可检索，教训不交两次学费；
|
||
- 五段式脚本 = 生产操作的安全带：预览、确认、可回滚。
|
||
|
||
单人开发者的新杠杆就在这：agent 把执行带宽放大了一个量级，而工程化纪律决定这带宽是产出还是事故。19 连发那天最庆幸的不是发了 19 个提交，是每一个都带着可复核的证据落地。
|