wait4xandGLM-5.3
8571acdc8b
用户直派车道交付：①Spec Harness 详解（任务包解剖+流水线图， boundary/verify 实例+12 命令+门禁）②pi-mesh 四件套（stack 图+ 合奏循环图+上手安装）③Agensh 论文笔记（三支柱/协作环/规模收 益图，DeLM 血统+issue#13→pi-board 诞生线）。七张自绘 SVG、双 语（en 手写直译 locked:true，禁 TMT 覆盖）。与既有 spec- workflow-and-mesh（实战复盘向）互补并存。 车道：worker-one（build/lint/外链 curl/视觉两轮 7/7 全绿）；收 编复验 E2E 34/34+lint 43 页 0/0/0 验证: pnpm astro build 39 文；E2E 34/34；content-lint 0/0/0 Spec: none (内容三篇，直派车道收编) Co-authored-by: GLM-5.3
62 lines
6.9 KiB
Markdown
62 lines
6.9 KiB
Markdown
---
|
||
title: "Spec Harness 详解：把长程开发装进可验收的任务包"
|
||
pubDate: 2026-11-01
|
||
category: tech
|
||
tags: [工程实践, AI 协作]
|
||
---
|
||
|
||
AI 编程智能体最不缺的是写代码的带宽，最缺的是记忆。一个跨了好几轮会话的任务，改到一半的方案、已经否决的路线、验收口径，散落在聊天记录里就等于丢了——换一个会话、重启一次终端，上下文归零。[Spec Harness](https://github.com/MicTx/spec-harness) 解决的就是这个问题：它是一个面向 AI 编程智能体的任务包工作流工具，把长程改动保存为**可恢复、可验证的 Development Record**，用范围、证据和 Git 门禁管住全程。它不提供模型，也不替你做产品决策。
|
||
|
||
一句话概括它的世界观：**当一个编码任务的寿命超过一段对话，缺的不是更聪明的模型，而是一份大家（包括未来的你）都能读的合同。**
|
||
|
||
## 一、核心抽象：任务包
|
||
|
||
所有工作装进 `.spec/specs/YYYY-MM-DD_slug/` 目录，核心是两个文件：`spec.md` 写范围、假设与取舍（还有一节很特别的"已证伪路径"，后面细说），`tasks.md` 写任务清单。收尾后整包归档到 `.spec/specs/archive/`，归档目录本身就是项目的工程日志。
|
||
|
||
每个任务必须带两行合同——**boundary**（这个任务能动哪些文件）和 **verify**（怎么证明做完了）。verify 是只读断言，跑出退出码 0 才许勾选。拿这个博客真实归档的 `2026-10-26_blog-5f` 包里 T3 任务举例：
|
||
|
||
|
||
|
||
boundary 划定"能动什么"，verify 划定"怎么证明做完"——两行齐备，缺一不勾。这不是形式主义：多 agent 并行时，boundary 就是车道之间的护栏（我们的实践里，全局样式文件只许主线动，车道要新变量走申请）；verify 则把"看起来好了"和"证明做完了"区分开，口头"过了"永远不算数。
|
||
|
||
`spec.md` 里最有味道的一节是**已证伪路径**：被否决的方案连否定理由一起入库。我们的 blog-5f 包里记着三条——首屏 banner 化（视觉裁定否决）、热力图换绿（破坏灰阶骨架）、标题 27px 收到 22px（层级锚点，要轻减字重不减号）。下次谁想再试一遍，先读档案，少烧一轮预算。
|
||
|
||
## 二、阶段流水线：五个核心命令与它们把守的门
|
||
|
||
|
||
|
||
五个核心命令串起一条可验证链：**目标 → 范围 → 任务 → 验证 → 归档 → 提交 → 推送**。每个阶段之间都有门把守：`spec.md` 有模板占位符就拒绝进入 run；`done` 要求每个任务 boundary/verify 齐备、验收面全绿且至少有一条非占位证据（脚本输出、测试结果）；`push` 只合并 `spec/` 前缀的集成分支，文件改动与提交永远分开做，禁用 `--no-verify`。
|
||
|
||
被阻塞的任务会打 `!` 标记上浮给用户，绝不静默跳过；复核轮（check）发现的可执行问题必须当轮写回任务包并修复，不允许把"待办"当交付物甩给用户。
|
||
|
||
**中断恢复是常态设计**——这是它对“任务寿命超过对话”最直接的回答：任意时刻重跑 `/spec:run`，从 `tasks.md` 的勾选状态续跑，不依赖任何对话记忆。更进一步，`/spec:autoplan` 做交互式规划（澄清目标后过框架、细节、复核三轮，规划就绪即停，不自动开工），`/spec:autorun` 按规划逐包执行，默认最多 5 轮自动链（`--max-rounds` 可调），暂停后从同一步恢复；一键式入口 `/spec:goal` 则把规划、执行、复核、归档、提交一次跑完。
|
||
|
||
命令面共 12 个阶段命令：core 档装五个核心命令，full 档补齐 goal / autoplan / autorun / update / status / doctor / organize 七个扩展件——`doctor` 做环境自检与修复，`organize` 做结构审计。还有一个容易被忽略的细节：安装只是放文件，不会主动逐任务评估；想让它在你动手前主动问一句“这事要不要开包”，需要显式接线一次 `install_activation_hooks.py --mode on`。判据看交付形状——独立验收面、实际实施者、可恢复的在途任务；小修、只读调查、一次性实验都直接做。它防的是“忘了评估”，不防刻意瞒报——文档里对此毫不讳言。
|
||
|
||
## 三、多 agent 编排：一个编排者，有边界的帮工
|
||
|
||
Spec Harness 对多 agent 的态度很克制：**主会话是唯一的编排者**，路由、集成、验收和 `done`/`push` 门禁永远不出主线。旁支工作（探索、构建、审查这类上下文无关的活）可以委托，但要先过机器路由决策（`scripts/route_decision.py`）并写下任务合同：目标、范围、排除区、产出、验证方式五项齐备才许派。它甚至为"跨会话交接"准备了可选的 `handoff.md`——生成式快照头加 append-only 条目日志，单人、多人、agent、集群四种协作模式各有一套必填小节。
|
||
|
||
扩展位（slots）机制则把"别的团队流程"插进来：`team-loop` 管团队循环、`workflow-runner` 管工作流扇出，各自带 README 协议和测试。源码库里还附了 orchestrator/planner/reviewer/confirmer 四个编排代理定义。
|
||
|
||
## 四、安装：一个安装器，十余个宿主
|
||
|
||
Spec Harness 是 Python 3.9+ 的标准库实现（PolyForm Noncommercial 许可），安装就三步：
|
||
|
||
```bash
|
||
git clone https://github.com/MicTx/spec-harness.git /tmp/spec-harness
|
||
cd /tmp/spec-harness
|
||
git checkout v0.22.2
|
||
bash install.sh
|
||
```
|
||
|
||
安装器支持十余个宿主：Claude Code、Codex、Gemini CLI、Grok、OpenCode、OpenClaw、Hermes、Pi、ZCode、DeepSeek Harness、Devin、Cursor……不指定时自动探测已装的宿主。安装档位分 core / full：core 只装五个核心阶段命令加 Git 钩子；full 补齐全部 12 个阶段命令和 slots、agents 扩展组件。我们在 Pi 上用 `INSTALL_HOSTS=pi bash install.sh`，装完 `/spec` 系列命令直接可用。
|
||
|
||
## 五、跑在一个真实博客上
|
||
|
||
这个博客就是它的用户。归档目录里躺着从裸 clone 构建改造、移动端布局修复到 SEO 解封的一串任务包：blog-5f 一个包八个任务、三条车道（两条 mesh 终端加主线）并行，每个任务的 verify 都是能在命令行跑出退出码的断言，页面类任务统一挂 E2E——`E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs`，34 项全过才算数。包与包接力，一天 19 个提交全绿落地。
|
||
|
||
门禁也真的拦过烂账：一次一个全 manual、从未执行的任务包混进了 `.spec/specs/`，check 门禁直接判 blocked，连带拦下所有携带归档路径的提交——直到把它移出。门禁防的不只是烂尾，还有“看起来有规划”的空包。
|
||
|
||
工具会迭代，但这套思路不会过期：**把"要干什么"写成合同，把"做完了"写成证据，把过程归档成日志。** 无论协作方是人还是 agent，这三件事都是长程工程的地基。
|