AI Agent 缺的不是更强的模型,而是一个运行时

0 阅读11分钟

副标题: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 配了四道门禁:

  1. 完整性:checklist 每一项都必须有 verdict,漏评即失败
  2. 防伪:mode: 'script' 的项,引擎自己重跑 command 核对模型写的结论——模型说"相似度 98%",引擎跑一遍相似度脚本,数字对不上直接失败
  3. 证据:每条的 evidence 必须带真实引用(文件 + 行号),空话过不去
  4. 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 check 3 次,输出除耗时外逐字节一致——确定性来自流水线,不来自模型的"临场发挥"。
  • 子任务闭环: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 门禁,自动 —— 验证能不能跑通
模型(理解的)→ 写代码、做设计,自动 —— 把需求变成代码
人  (不可逆的)→ 发布上线,手动      —— 只有人知道"对不对"

"生产环境对不对"脚本验证不了,交给人的经验。敢说"管不到",比声称"全自动"可信。


仓库地址

源码、文档、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 里拿出来,交给引擎。模型负责干活,引擎负责判断"干完了"这三个字什么时候作数。