副标题:GateLoop —— 流程门控 + 多 skill 协作 + exit code 验证的统一执行引擎
一句话:模型负责干活,引擎负责判断"干完了"这三个字什么时候作数。
一、模型越强,交付越乱
先看三个被反复验证的事实:
| 现象 | 具体表现 | 根因 |
|---|---|---|
| Agent 说"验证通过了" | 其实根本没跑过 tsc,带编译错误的代码被合并进主干 | 步骤是建议,没有强制执行点 |
| 长任务状态漂移 | 对话进行到第 40 轮,模型忘了自己在第几步、上游产出了什么 | 状态存在模型脑子里 |
| 死循环烧 token | 同一个错误修了 20 遍,账单爆炸才被发现 | 没有熔断机制 |
传统解法是在 System Prompt 里写"请务必验证后再提交"。问题在于:这些对 LLM 只是建议,不是约束。它会选择性遵守,也会选择性"装作"遵守。
这个问题的行业坐标已经清楚了。2026 年,verification harness 被公认为无人值守 agent 可靠性的最高杠杆实践;但一篇评审了 21 个 agent harness 的报告给出了更直接的结论:
"它们都解决了跑一个 agent 的问题,没有一个解决了验证一个 agent 的问题。None of them define 'done' as something you can check."
模型在变强,上下文窗口在变大,但执行层没人做:谁来决定流程走到哪一步、阶段之间怎么交接、什么算完成、失败怎么办。这是本文要补的东西——不是又一个 prompt 技巧,而是一个把纪律从"模型自觉"搬进"引擎强制"的运行时:GateLoop。
一个真实的事故
约束放错了位置,提示词再长也没用——这话不能只靠引用别人的翻车,所以我们把它做成了留在仓库里的现场(demo/gateloop-story/,可复现):一份同时埋了 TS 类型错误、ESLint 违规、Prettier 格式违规的样本文件,拆成 lint → ts → format 三个锚点,每个锚点用真实工具的 exit 0 守门。以下是写作本文当天真实跑完的记录(原样截取,未修饰):
$ nut gateloop next anchor.config.json # 只修了格式问题,类型错误还在
📌 阶段: ts (tsc 过检) 🔁 尝试: 1/3
❌ 验证结果: 失败 (1 项检查)
❌ Custom: npx tsc --noEmit --strict broken-sample.ts (5897ms)
broken-sample.ts(4,9): error TS2322: Type 'number' is not assignable to type 'string'.
➡️ ❌ 验证未通过(1 个错误,1/3 次)。修复后重新调用 next。
时间线完整复刻了事故结构:第一道 eslint 门禁拦下格式违规(Replace ',' with ';');格式修完,第二道 tsc 门禁当场抓出类型错误 TS2322——这一步正是事故的要害:如果校验靠模型自评,"我觉得修好了"这句话就通关了;接进 verify.custom 后,它只是引擎重跑命令时 exit 1 的一行输出。 修复方式不是把 SKILL.md 写得更凶,而是把校验命令接进门禁,让引擎重跑判定。
问题出在约束的位置,而不是提示词的长度。 这条经验贯穿本文。
二、GateLoop:给 Agent 装一层执行运行时
GateLoop 是一个运行时约束器(harness)。skill 只声明"要做什么"(What),引擎强制"怎么做才算数"(How)。它和提示词技巧的区别在于强制力:SKILL.md 里的步骤对模型是建议,anchor.config.json 里的 verify 对模型是闸门。
它的能力面是三条线,全部落地在 src/gateloop/ 的真实代码里:
① 流程门控 —— anchor 状态机推进,每阶段过闸才能走下一步(state.ts)
② 协作管道 —— 阶段间 emits/consumes 数据契约,多 skill 跨存档上下文(flow.config)
③ 验证门禁 —— 推进前引擎重跑真实命令,exit 0 才算过(verify.ts)
落地到 CLI 和 API 两种形态(npm 包 ai-rail,已发布 v0.0.0-beta.8,bin 命令 nut):
# CLI:所有流程操作都是一条命令
nut gateloop init <manifest> --task "实现用户列表页"
nut gateloop next <manifest> # 推进(内部强制重验 + 熔断)
nut gateloop status <manifest> # 断线恢复:现在在哪一步
nut gateloop retry / reset / check / gc / subtask-add / subtask-done / emit / mem-write / mem-read
# API:同一套能力,编程调用
import { GateLoop, verify } from 'ai-rail/gateloop'
const loop = new GateLoop(loadManifest('./anchor.config.json'))
await loop.init('实现用户列表页') // → 指令:先做 inventory(客观清单)
await loop.next() // → 引擎重跑验证,exit 0 才推进
一个 skill 的"执行契约"长这样(真实配置节选,frontend-codegen 前端代码生成 skill):
{
"name": "frontend-codegen",
"description": "前端代码生成唯一入口(GateLoop harness)— 单 skill 完成 设计→生成→质检 全流程。v14 合并 frontend-design/css-style-writer/code-quality-guard 为内联规则(rules/*.mdc),消除多 skill 分裂误触发",
"scratchDir": ".specflow/scratch",
"scratchGcHours": 72,
"maxAttempts": 5, // 熔断:每阶段最多试 5 次
"anchors": [
{ "id": "inventory", // 阶段 1:环境与风格客观基线,脚本产出,模型改不了
"name": "环境与风格基线(客观)",
"brief": "脚本产出 inventory.json:枚举 src/ 下所有 .ts/.tsx 文件并标记行数违规(客观基线,模型不参与判断)。固定约定(不可协商,全流程强制):组件形式 = <a-b>/index.tsx + <a-b>/index.scss;圈复杂度 ≤ 15……",
"produces": [".specflow/context/inventory.json"],
"emits": ["inventory"],
"verify": {
"produceScripts": [
"node ${skillDir}/scripts/inventory.mjs --output .specflow/context/inventory.json --root src"
],
"autoEmit": { "inventory": ".specflow/context/inventory.json" }, // 脚本成功后自动产出 artifact,模型零参与
"modelWritable": false, // 清单只能脚本写,verify 时引擎重跑覆盖,防伪造
"producesFresh": true // 产物必须比本轮新,防复用旧文件
}
},
{ "id": "design", // 阶段 2:设计思考四步,必须覆盖 inventory 的全部违规
"name": "设计思考:影响范围→方案→改动→任务列表",
"reads": ["rules/design-rules.mdc"], // 规则由引擎内联,无需 Step 0
"consumes": ["inventory"],
"produces": [".specflow/context/current.json"],
"emits": ["frontendPlan", "architectureReview"],
"verify": {
"schema": { "type": "object",
"required": ["frontendPlan", "architectureReview"],
"properties": {
"frontendPlan": { "required": ["impactScope", "changes", "tasks", "functionOwnership", "stateClassification", "efficiencyAudit", "moduleBoundary", "edgeCases", "errorStates", "coverage"] },
"architectureReview": { "required": ["verdicts"] } // 每条 verdict 必须带 metric/fact/verdict/reason
} },
"producesFresh": true,
"custom": [
"node ${skillDir}/scripts/verify-coverage.mjs --inventory .specflow/context/inventory.json --plan .specflow/context/current.json",
"npx nut gateloop metric design --input .specflow/context/current.json",
"npx nut gateloop metric architecture --input .specflow/context/current.json"
],
"review": { "output": ".specflow/context/design-review.json", "requireEvidence": true,
"checklist": [
{ "id": "impact-scope", "rule": "影响范围完整:改动涉及的模块/文件/依赖链已全部识别,无遗漏的连带改动", "mode": "model" },
{ "id": "changes-convention", "rule": "改动清单符合固定约定:组件路径 <a-b>/index.tsx + <a-b>/index.scss(kebab-case 目录)", "mode": "model" },
{ "id": "tasks-derivation", "rule": "任务列表从 changes 派生:无任务缺文件、无文件缺任务", "mode": "model" },
/* ……共 9 项:布局决策/模块边界/状态分类/函数归属/耦合健康/效率审计,逐条 verdict + 带行号证据 */
] }
}
},
{ "id": "code", // 阶段 3:按任务生成 + 质量验收,exit 0 才放行
"name": "按任务生成 + 质量验收",
"reads": ["RULE.mdc", "rules/style-rules.mdc", "rules/quality-rules.mdc"],
"consumes": ["frontendPlan", "architectureReview"],
"requiresSubtasks": true, // 按 frontendPlan.tasks 逐任务执行,全绿才推进
"maxAttempts": 8,
"produces": ["src/**/*.tsx", "src/**/*.ts", "src/**/*.scss"],
"verify": {
"tsc": true, "build": true, "producesFresh": true,
"custom": [
"npx nut gateloop metric style-crosscheck --dir src/",
"npx nut gateloop metric code --dir src/",
"node ${skillDir}/scripts/verify-completion.mjs --root src --plan .specflow/context/current.json"
],
"review": { "output": ".specflow/context/code-review.json", "requireEvidence": true,
"checklist": [
{ "id": "component-convention", "rule": "组件形式符合固定约定:<a-b>/index.tsx + <a-b>/index.scss(入口 index,固定死)", "mode": "model" },
{ "id": "data-flow", "rule": "数据流清晰:props 单向注入,state 分类符合 frontendPlan.stateClassification", "mode": "model" },
{ "id": "style-state-coverage", "rule": "全状态覆盖:hover/focus/disabled + loading/empty/error 均覆盖", "mode": "model" }
/* ……共 11 项,逐条 verdict + 带行号证据 */
] }
}
}
]
}
几个字段背后的机制:modelWritable: false 意味着清单是脚本说了算——verify 时引擎重跑 produceScripts 覆盖产物,模型伪造无效;producesFresh 意味着产物必须比本轮尝试新,用旧文件蒙混直接失败;autoEmit 让 inventory 这一环模型零参与——纯脚本进、纯 artifact 出;reads 让规则由引擎内联,不再依赖模型主动去读。
三、门控:确定的交给脚本,理解的交给清单
验证层的核心是 5 类分工——把每个质量要求放进它该在的位置,不越界:
A 收敛(能编译/无 any/圈复杂度) → exit code ← 脚本,100% 确定
B 完备(字段齐全) → schema ← 脚本卡"想全没"
C 度量(依赖环/热点) → 脚本粗筛 → 模型精判 → 回灌
D 主观(拆分合不合理) → review 四道门禁 ← 模型评 + 脚本卡形式
E 纯审美 → 不进 verify
这条边界的实际意义:不会把"布局合不合理"塞进 tsc,也不会把"依赖有没有循环"交给模型自评——前者测不出来,后者测不准。C 类是两者的混搭:脚本先跑依赖图找出 12 个可疑环,模型再精判哪些是真环、哪些是类型引用误报,结论回灌成 artifact 供下游消费。
D 类(主观)是这个设计里最容易被忽视也最常翻车的地方。模型自评会放水,所以 review 配了四道门禁:
- 完整性:checklist 每一项都必须有 verdict,漏评即失败
- 防伪:
mode: 'script'的项,引擎自己重跑 command 核对模型写的结论——模型说"相似度 98%",引擎跑一遍相似度脚本,数字对不上直接失败 - 证据:每条的 evidence 必须带真实引用(文件 + 行号),空话过不去
- fail 必改:任何一项 verdict 为 fail 且是 blocking 的,整个阶段不通过
这就是"检测清单两条路径"的落地:用户给的检测清单里,能脚本化的全部 100% exit code 判定;需要理解的,模型一次过一遍、逐条核对留痕。
四、流程:状态机、契约与熔断
引擎推进的心脏是 doNext(),门禁顺序是刻意设计的(state.ts 真实实现):
调用 next()
├─ [门禁1] requiresSubtasks? → 子任务未全绿 → 拒绝推进
├─ 强制重跑 verify(真实命令,exit code 判定)
├─ [门禁2] emits 声明的 artifact 已产出?
├─ [门禁3] writesMemory 声明的决策记忆已回写?
├─ attempts++
├─ 验证未通过?
│ ├─ attempts >= maxAttempts → 熔断(escalated)
│ └─ 否则 → 返回错误,让模型修复后重试
└─ 验证通过? → 推进下一 anchor
三个容易被低估的细节:
状态唯一写入者。 anchor-state.json 只有引擎内部能写,不导出给模型。模型能读状态、能通过 API 请求变更,但改不了文件本身。断线后 nut gateloop status 看到的和真实进度永远一致。状态文件损坏时(进程被强杀),引擎会先把原文件备份成 .corrupt-<时间戳> 再重新初始化——进度不静默丢失。
数据契约。 阶段之间通过 consumes / emits 显式交接:声明了 emits: ["frontendPlan"] 却没产出,验证直接失败。数据流从"隐式约定"变成"显式契约",上一阶段的产出会被引擎自动内联进下一阶段的指令——模型不需要自己去找,也不可能拿错。
熔断与环检测。 每阶段独立 maxAttempts,连续失败超限进入 escalated 停机,不再烧 token。Flow 层还有 maxJumps 环检测:onPass 跳转成环(A→B→A)会被识别并停机,而不是无限空转。
五、协作:多 skill 编排与信息管道
单个 skill 用 anchor 管内部,多个 skill 接力用 flow 管全局(flow.config.json):
{
"name": "full-stack-deliver",
"flow": [
{ "id": "design", "delegateSkill": "web-ui-design",
"writesMemory": ["designDecision"], "readsContext": ["#req"] },
{ "id": "code", "delegateSkill": "frontend-codegen",
"readsContext": ["design"],
"onEscalate": { "jumpTo": "design" } } // 设计不达标 → 回滚到需求阶段重做
]
}
长链路协作最大的敌人是信息衰减:第一个 skill 的结论传到最后只剩一句话。GateLoop 用三条管道对抗它:
- readsContext 上下文存档:上游阶段结束时,引擎自动归档决策和产物,下游 skill 按 key 拉取,不靠模型转述
- writesMemory 决策记忆:关键决策(选型、约定)落盘成确定性事实源,跨任务、跨轮可查
- onEscalate 回滚:下游验证发现上游设计有问题,跳回上游重做,而不是带着错误硬走
在真实仓库里,这个模式已经跑在多个 skill 上:frontend-codegen(inventory → design → code 三锚点)、pvm(detect → install → execute)、code-env(环境检测 → 拉码建分支 → 装运行时 → 装依赖 → 启动验证,五锚点)。领域不同,门禁模式完全一致——这就是"声明即能力":skill 作者只写清单和验证条件,状态机、熔断、隔离、续跑由引擎统一提供。
六、模型凭什么听你的?
一个必须正面回答的问题:这一切都建立在模型愿意调用 nut gateloop next 的前提下。模型要是不调、直接撒谎说"做完了",引擎根本没有运行的机会——谁来保证它一定按流程执行?
先承认:没有 100% 的保证。 模型确实可以拒绝调用、可以撒谎。声称能"保证模型执行"的方案都做不到这一点。
但注意——我们不保证"模型执行",我们保证的是"不真执行 = 零推进"。 这两件事完全不同:
路径 A:真执行 → init → 产出文件 → next(引擎强制重跑 exit code)→ 状态推进
路径 B:撒谎说做完了 → 对话里说得天花乱坠
但 anchor-state.json 一步没走、产物不存在、mtime 没变
没有任何可被第三方检查的客观证据
真正的约束不在"能否撒谎",而在"撒谎能换来什么"——答案是:谎言无法产生推进。 状态文件是引擎唯一写的,产物存在与否是磁盘上的物理事实,下游的内联数据只在真推进后才注入。 "省事"的路径恰好就是"正确执行"的路径,撒谎在机制上就是死路。
四道防线叠加:入口层(skill 铁律要求 init/next)→ 验证层(next 强制重跑真实命令)→ 防伪层(review 的 script 项由引擎重跑核对)→ 审计层(状态文件 + 日志 + 产物时间戳,随时可查)。
一句话:我们不赌模型诚实,我们赌"验证是确定性的"。 银行不保证没人造假钞,但保证假的一定过不去验钞机。引擎就是那台验钞机——不赌人性,赌机器。
七、实验:六个可复现的对比
以下终端输出来自引擎开发过程中的实测记录(fixture 保留在仓库 git 历史中,demos/gateloop/ 目录已在后续整理中移除)。
实验 1:它说验证过了,门禁不认
code 锚点声明 "verify": { "tsc": true }。代码里故意留一个编译错误,模型调 next:
$ nut gateloop next anchor.config.json
📌 阶段: code (编码) 🔁 尝试: 1/5
🔍 验证: tsc --noEmit(由引擎内部执行)
❌ 验证结果: 失败 (2 项检查)
✅ 产物存在性 (6ms)
❌ tsc (2508ms)
src/utils.ts(4,14): error TS2322: Type 'string' is not assignable to type 'number'.
➡️ ❌ 验证未通过(1 个错误,1/5 次)。修复后重新调用 next。
模型可以声称"tsc 通过了"一百次,但引擎会在推进前自己跑一遍。想要过,只能真的把代码改对。
实验 2:死循环被熔断
verify.custom 恒为 node -e "process.exit(1)",maxAttempts: 2:
$ nut gateloop next anchor.config.json
📌 阶段: build (构建) 🔁 尝试: 1/2
❌ 验证结果: 失败 (1 项检查)
❌ Custom: node -e "process.exit(1)" (154ms)
➡️ ❌ 验证未通过(1 个错误,1/2 次)。修复后重新调用 next。
$ nut gateloop next anchor.config.json
📌 阶段: build (构建) 🔁 尝试: 2/2
🛑 已熔断:连续失败超过上限,需人工介入或降级方案。
第 2 次仍失败,状态机把锚点标记为 escalated,自动停机。不再无意义地烧 token。
实验 3:什么都没做就想交差
scan 锚点声明产物 todo-report.json。模型什么都没做就 next:
$ nut gateloop next anchor.config.json
📌 阶段: scan (扫描并汇总 TODO) 🔁 尝试: 1/3
❌ 验证结果: 失败 (1 项检查)
❌ 产物存在性 (7ms)
缺失: todo-report.json
➡️ ❌ 验证未通过(1 个错误,1/3 次)。修复后重新调用 next。
没有 GateLoop,模型一句"我扫了,没有 TODO"就交差了;有 GateLoop,它必须真的跑出产物文件。
实验 4-5:稳定性与完整性(机制验证)
- 同题多次生成:对同一份含错误的代码连续
nut gateloop check3 次,输出除耗时外逐字节一致——确定性来自流水线,不来自模型的"临场发挥"。 - 子任务闭环:
requiresSubtasks: true的阶段,一个子任务没完成,next永远被挡回,直到全部 done。
实验 6:真实文件,真实工具,真实修复
给一个埋了 lint / TS 类型 / 格式化三类问题的 .ts 文件,做两个 skill(完整可复现 demo:demo/gateloop-story/,跑法见 anchor.config.json 三个锚点):
- 裸 skill(只有 SKILL.md,无 manifest):按文档修完宣布"已全部修复",外部再跑
npx eslint当场抓到 1 个漏网错误——它自己永远不会发现,全凭自觉 - GateLoop skill:三类问题拆成三个锚点,每个用真实工具 exit 0 守门:
{ "anchors": [
{ "id": "lint", "verify": { "custom": "npx eslint ../broken-sample.ts" } },
{ "id": "ts", "verify": { "custom": "npx tsc --noEmit --strict ... ../broken-sample.ts" } },
{ "id": "format", "verify": { "custom": "npx prettier --check ../broken-sample.ts" } }
] }
真实跑起来:第一次 next 被 lint 门禁当场拦截(19 个错误,attempt 1/3,没有推进);每修一类再 next,依次输出 ✅ 验证通过,已推进到 ts 阶段 → 已推进到 format 阶段 → ✅ 所有阶段已完成。
差异:裸 skill 把"修好了"定义成模型的一句陈述;GateLoop skill 把它定义成三个工具的 exit 0。少一道门都不算完。
八、边界:什么该自动,什么该人做
最后是边界。GateLoop 的自动闭环只覆盖开发 + 测试,到发布停下:
脚本(确定的)→ exit code 门禁,自动 —— 验证能不能跑通
模型(理解的)→ 写代码、做设计,自动 —— 把需求变成代码
人 (不可逆的)→ 发布上线,手动 —— 只有人知道"对不对"
"生产环境对不对"脚本验证不了,交给人的经验。敢说"管不到",比声称"全自动"可信。
仓库地址
- GitHub:github.com/Lycorxy/gat…
- Gitee:gitee.com/lycorxy/gat…
源码、文档、Issue 都在这里,开源免费,欢迎使用,如果对你有用就点个star支持一下吧。
npm 包
- pnpm:pnpm add -D gateloop
- npm:npm i -D gateloop
附:实现形态
引擎以 npm 包 ai-rail(已发布 v0.0.0-beta.8,bin 命令 nut)提供,纯 CLI + API 两种形态。内部状态与工作区函数不对外导出——全部能力经 GateLoop 类封装,从 API 层面杜绝"绕过引擎直接改状态"。verify 命令类验证器为 tsc / build / test / custom(任意真实命令都能进 custom),加上 schema / producesExist / producesFresh / review / produceScripts 全套门禁。
引擎源码(src/gateloop/)与配套 skill(skill-creator-gateloop)在仓库里可直接阅读与运行。
如果你也在做 AI 编程 Agent,不妨把"纪律"从 prompt 里拿出来,交给引擎。模型负责干活,引擎负责判断"干完了"这三个字什么时候作数。