Loop Engineering 核心概念全解:从概念词汇表到可落地的 Agent 循环系统设计

原创2026-09-22 20:35:061,842 阅读
文章标签:人工智能AI 技能AI 插件Agent 工作流开发工具CLI代码质量

Loop Engineering 核心概念全解:从概念词汇表到可落地的 Agent 循环系统设计

本文是 loop-engineering 仓库中 docs/concepts.md 的深度展开版。它系统梳理 "loop engineering"(循环工程)这一范式的核心概念词汇、六大基础构件(Six Primitives)与概念关系图,并补齐与仓库内 docs/primitives.md、docs/primitives-matrix.md、docs/loop-design-checklist.md、docs/failure-modes.md、docs/safety.md 及 tools/ 下 CLI 实现之间的对应关系。读完你能够:用一套工具无关的心智模型设计自己的 loop,准确说出各概念的边界(harness 与 loop、intent debt 与 comprehension debt 等),并为后续的落地(调度、worktree、skills、验证拆分、状态管理)建立统一术语基础。

什么是 Loop Engineering

Loop engineering 的核心定义可以浓缩为一句话:"Replacing yourself as the prompter"——把自己从"每次都手动输入下一条提示词"的角色中替换出来。你不再逐条敲 prompt,而是设计一个系统,让它自己去:

  • 发现工作(discover work):从 issue、PR、CI 失败、依赖更新等源头找到该做的事;
  • 分配任务(assign it):把任务交给合适的子代理;
  • 验证结果(verify results):由独立角色检查产物是否达标;
  • 持久化状态(persist state):把"做了什么、进行到哪、下一步是什么"写入可跨会话读取的存储。

一个 loop 本质上是一个递归目标(recursive goal):先定义目的(purpose),然后让 Agent 借助子代理(sub-agents)与外部记忆(external memory)不断迭代,直到完成目标,或直到 loop 将问题升级(escalate)给人类。

这与"一次性的 Agent 运行"有本质区别:后者是单次会话,前者是带调度、状态与验证链的持续系统。仓库根目录 README.md 用一句 slogan 概括了这一范式转换:"Stop prompting. Design the loop. Get a score."

相关概念:站在前人的肩膀上

concepts.md 指出,loop engineering 属于一整个"Agent 化软件开发"概念家族,其中大量概念源自 Addy Osmani 的 Loop Engineering 论述。理解这些相关概念,能让你在设计 loop 时拥有正确的心理模型。

Agent Harness Engineering(Agent 运行环境工程)

Harness 是单个 Agent 运行的环境:工具(tools)、上下文(context)、权限(permissions)、规则(rules)。harness 是"沙箱",而 loop 是负责在时间轴上调度与编排 harness 运行的东西。concepts.md 用一句话区分两者:

Harness = single session setup
Loop    = harness + schedule + state + verification chain

也就是说:harness 解决"一次会话怎么搭",loop 解决"很多次会话怎么被组织成一个持续运转的系统"。

The Factory Model(工厂模型)

工厂模型指构建软件的系统本身:流水线(pipelines)、Agent、检查(checks)与交接(handoffs)。loop engineering 是"如何在工厂车间里运营",而不是"手工组装每一个单元"。

Intent Debt(意图债)

每次会话 Agent 都是"冷启动"的:它不知道你上次说过什么、为什么这样做。缺失的意图(intent)会被 Agent 用"自信的猜测"填补——这就是意图债的来源。

Skills 就是偿还意图债的方式:把约定(conventions)、构建步骤、"我们因为 X 事故不这么做"这类知识"写一次,每次运行都读"。这正是仓库中 docs/primitives.md 把 Skills 定义为"intent 的持久记忆"的原因——没有 skills,loop 每次运行都要从头重新推导一切。

Comprehension Debt(理解债)

理解债 = "仓库里实际存在的东西"与"你真正理解的东西"之间的差距。loop 跑得越快,你看到的"不是自己写的代码"就越多——除非你坚持阅读 loop 产出的东西,否则理解债只会不断增长。这是仓库在 README.md 里反复强调"Read what the loop ships"(读 loop 交付的代码)的理论根基。

Cognitive Surrender(认知投降)

这是"让 loop 跑着,自己停止发表意见"的陷阱。concepts.md 给出了一对方向相反但动作相同的对比:

Designing loops with judgment is the cure; using loops to avoid thinking is the accelerant. Same action, opposite outcome.

——带着判断力设计 loop 是解药;用 loop 逃避思考是助燃剂。同样的动作,相反的结局。仓库 docs/failure-modes.md 把这一现象列为独立的失败模式(S2 级、文化层面的问题):当"loop 的成功指标 = 数量而非质量"、中等风险工作没有人类门控(human gates)时,认知投降就会发生。

Orchestration Tax(编排税)

编排税指协调多个并行 Agent 的人力成本:review 带宽、合并冲突、上下文切换。Worktrees(工作树)能消除机械层面的冲突,但"你能吸收多少个并行 loop"的最终上限仍然是你自己——人是天花板。

仓库提供了把这一概念机械化的工具:tools/loop-worktree/README.md 中的 loop-worktree CLI 支持"一个修复尝试一个 worktree",通过 manifest 跟踪状态,并在 reject 或 escalate 时清扫;lock/unlock 子命令则给 docs/multi-loop.md 的 acting_on 约定提供了机械形式,防止多个独立调度的 loop 竞争同一批文件(真实事故见 stories/multi-loop-collision.md)。

Code Agent Orchestra / Adversarial Code Review(代码 Agent 乐团 / 对抗式代码审查)

这是结构化模式:不同角色(explore 探索、implement 实现、verify 验证)由不同 Agent 承担。其铁律是:实现者绝不能给自己的作业打分(the implementer must never grade its own homework)。这一点对于无人值守(unattended)的 loop 至关重要——它直接引出下文第 5 个构件(maker/checker 拆分)。

六大基础构件(Six Primitives + Memory)

concepts.md 给出了 loop 的全部构件清单,docs/primitives.md 对每一项做了完整展开,docs/primitives-matrix.md 则把它们映射到 Grok、Claude Code、Codex、OpenClaw、Opencode、Cursor、Windsurf、Hermes 八种 Agent 环境。

Loop Engineering 六大基础构件关系图:Automations、Worktrees、Skills、Plugins & Connectors(MCP)、Sub-agents 均以 Memory/State 为中心枢纽协同工作

1. Automations / Scheduling(自动化 / 调度)

心跳(heartbeat)。没有调度,你只有一个一次性的 Agent 运行。常见实现形式:

  • /loop(Grok);
  • Claude Code 中的 scheduled tasks / cron;
  • GitHub Actions + repository dispatch;
  • /goal(run until a verifiable condition is true,运行直到可验证条件成立);
  • 自定义 harness 调度器。

关键属性:interval(间隔)、fire-immediately(是否立即触发首次)、recurring vs one-shot(循环还是单次)、durable(重启后是否存活)。docs/primitives-matrix.md 的 "Scheduling Quick Reference" 给出了"每 5 分钟 / 每日早晨 / 直到测试通过 / 重启后存活 / 事件驱动(CI 失败)"五种典型场景在八个工具里的具体命令写法,例如 Hermes 用 hermes cron create "*/5 * * * *" --deliver local --skill loop-triage "...",OpenClaw 用 openclaw cron create 配 --session isolated。

2. Worktrees(工作树)

无混沌的并行。两个 Agent 同时编辑同一批文件 = merge 地狱;git worktree(或等价的隔离 checkout)让每个 Agent 拥有"共享历史但不共享工作区"的独立目录。

  • Grok 中:生成子代理时传 isolation: "worktree",或用 --worktree / 专用会话;
  • 清理同样重要——loop 应在任务完成或交接后删除 worktree。

仓库用 tools/loop-worktree/ 把这个约定变成机械操作:loop-worktree create --run-id <id> --pattern <p> [--base main] 创建并记录 manifest,loop-worktree mark --run-id <id> --status rejected 打标记(只更新 manifest,不删目录),loop-worktree cleanup [--status rejected,escalated] [--older-than 24h] 清扫,loop-worktree gc 对账孤儿条目。manifest 位于 .loop-worktrees/manifest.json,条目状态为 active / rejected / escalated / merged / stale。

3. Skills(技能)

intent 的持久记忆。一个 skill(通常是 SKILL.md 加可选 scripts/references)编码的内容包括:

  • 项目约定(conventions);
  • "我们因为 X 事故不这么做";
  • build / test / lint 命令;
  • review 标准;
  • 领域知识。

没有 skills,loop 每次运行都从零重新推导(intent debt)。Skills 同时也是复用单元——可打包成插件跨仓库、跨团队共享。仓库内置 skill 见 skills/ 目录(loop-triage、loop-verifier、minimal-fix、loop-budget、loop-constraints、budget-negotiator 等),并提供了可直接使用的 SKILL.md 模板(如 templates/SKILL.md.loop-triage、templates/SKILL.md.verifier)。docs/primitives-matrix.md 的 "Skill Packaging" 一节对比了八个工具的作者格式、分发方式与调用方式。

4. Plugins & Connectors(MCP)

一个只能读文件系统的 loop 是受限的。连接器让 loop 可以:

  • 读取/更新 Linear / Jira 工单;
  • 发布到 Slack / Discord;
  • 查询数据库或内部 API;
  • 在 GitHub 上创建分支和 PR;
  • 触发部署或 runbook。

MCP(Model Context Protocol)已成为通用基板——为一个工具写的连接器往往能用于另一个工具。本仓库自带了可运行时查询的参考 MCP 服务:tools/mcp-server/ 把 patterns、skills、state、budget 和 safety 文档暴露为 MCP 资源(减少 prompt 塞填),配置示例见 examples/mcp/loop-engineering.mcp.json。安全要求见 docs/safety.md 的 "MCP Connector Least Privilege":GitHub 默认只读 issues/PRs/checks、可 comment/label 但默认不 merge;Slack 只允许发布到 #loop-escalations;数据库禁止从 loop 写入生产。

5. Sub-agents(Maker / Checker 拆分)

可靠 loop 最重要的结构性模式。"写代码的那个 Agent 是评价自己工作的最差裁判"——由第二个 Agent(有时用更强的模型,但一定用不同的指令)执行验证。

常见拆分方式:

  • Explorer → Implementer → Verifier(探索 → 实现 → 验证);
  • Implementer → Security reviewer(实现 → 安全审查);
  • Implementer → Test writer + runner(实现 → 测试编写与运行)。

在无人值守 loop 中,verifier 是让你(人类)能放心离开的那块压舱石。多个工具里的 /goal 会用"全新的模型"来判断停止条件是否达成,这正是 maker/checker 思想的另一个应用。docs/primitives-matrix.md 的 "Sub-agent Patterns" 表给出了每种拆分在八个工具里的落地方式(例如 Opencode 用 opencode run "..." --agent implementer 后接 opencode run "Verify diff" --agent verifier --file diff.patch)。

+ Memory / State(记忆 / 状态)

模型在跨 turn、跨 session 时没有长期记忆。loop 必须读写某种持久存储:

  • 仓库内的 STATE.md 或 LOOP-STATE.json;
  • Linear board / GitHub Project 的专用区块;
  • 一行数据库记录。

好的状态必须能回答三个问题:

  • 我们当前在做什么?
  • 上次尝试了什么、结果如何?
  • 什么在等人类处理?

concepts.md 特别强调:状态文件往往是 loop 产生的最重要的单一产物(the single most important artifact)。docs/primitives-matrix.md 的 "State Conventions" 推荐了一套文件命名脊柱:STATE.md(通用)、issue-triage-state.md、pr-babysitter-state.md、ci-sweeper-state.md、post-merge-state.md——每个项目选一条脊柱即可,且 loop 每次运行都必须读写同一个存储。可复制的骨架见 starters/minimal-loop/STATE.md.example。

各构件如何拼成一个 loop

docs/primitives.md 给出了明确的装配顺序——最小可行 loop 通常从三样东西起步:

Scheduling(调度) + 一个 skill(triage)+ state file(状态文件)

然后按需逐级加码:

  • 开始改代码时 → 加 worktree 隔离;
  • loop 开始自主行动时 → 加子代理验证;
  • 想让 loop 驱动工单和 PR(而不只是建议)时 → 加连接器。

最佳 loop 的共性:每个新构件都只在上一版证明了自己的价值(以及自己的失败模式)之后才被引入。这个"先证明、再加码"的思路,正好呼应 docs/loop-design-checklist.md 的 Readiness Levels:L0 Draft(仅意图)→ L1 Report(triage 到 state,无自动动作)→ L2 Assisted(带 verifier 的小型自动修复)→ L3 Unattended(无人值守)。

概念图:一个完整 loop 的运转

concepts.md 附带的 Mermaid 概念图把人类(最高杠杆点)与 loop 系统(调度、triage、状态、子代理、MCP)串成一个闭环,完整复刻如下:

flowchart TB
  subgraph human [Human — highest leverage]
    Design[Design loop]
    Judgment[Encode judgment in skills + verifiers]
    Gate[Human gates for high-risk work]
  end

  subgraph loop [Loop system]
    Schedule[Scheduler /loop cron Action]
    Triage[Triage skill]
    State[(STATE.md / Linear)]
    Impl[Implementer sub-agent]
    Verify[Verifier sub-agent]
    MCP[MCP connectors]
  end

  Design --> Schedule
  Schedule --> Triage
  Triage --> State
  State --> Impl
  Impl --> Verify
  Verify --> MCP
  MCP --> State
  Verify --> Gate
  Judgment --> Triage
  Judgment --> Verify

这张图的信息流可以这样读:人类设计 loop(Design) → 调度器按节奏触发(Schedule)→ triage skill 读取状态并判定优先级(Triage ↔ State)→ 实现者子代理在状态指引下干活(Impl)→ 验证者子代理独立检查(Verify)→ 结果通过 MCP 写回外部系统并更新状态(MCP ↔ State)→ 高风险工作抵达人类门控(Gate)。人类的两条输出——把判断编码进 skills 与 verifiers(Judgment)——同时约束 triage 和 verify 两个环节。

更细粒度的运行视角可参考 docs/architecture-diagrams.md,其中包含:单次运行内的参与者时序图(含"验证通过且预算充足 → 安全自动路径"与"验证失败/预算超限 → 仅报告"的分叉)、运行生命周期状态机(Scheduled → LoadingContext → WorkingInWorktree → Verifying → AwaitingHumanGate / Failed → Logged),以及 L1→L2→L3 自主等级迁移(带降级:incident 或 cost spike 回落 L2,kill switch 直接回到 L1)。

从概念到检查单:设计 loop 前要回答的问题

concepts.md 的 "Where to Go Next" 指出的四条路线,正是把上述概念落地的四份关键文档。这里把它们的要点浓缩成一张与概念一一对应的检查思路:

概念来源 落地的检查项(来自 docs/loop-design-checklist.md)
递归目标 单一清晰目标(一句话);明确 non-goals;有歧义的输入要澄清或升级,而不是猜测
调度(Automations) cadence 与紧迫度匹配;首次是否 fire immediately;是否 durable;夜间降频;watchlist 空时自清理
Skills triage skill 输出格式严格;action skill 匹配项目约定;skill 描述"无聊且具体"(利于自动触发)
Maker/Checker 实现者与验证者分离;实现者不能给自己的活标记"done";验证者在隔离 worktree 里跑测试;/goal 用新模型判断停止条件
Memory/State 状态 schema 文档化;每次运行先读旧状态、后写新状态;每次运行清理已解决项;人类覆盖记录进状态
人类交接 升级触发条件显式化(最大尝试次数、风险路径、歧义);denylist 路径(见下);只在需要行动时才通知人
连接器 最小权限;能开/更新 PR 或工单而非只建议;PR 评论里 bot 身份清晰
成本与安全 token 预算(npx @cobusgreyling/loop-cost);loop-budget.md 日上限与 kill switch;loop-run-log.md 追加式运行历史;最大迭代次数与每日最大自动 PR 数

同时,docs/failure-modes.md 提供了反向检查素材——所有失败模式(Infinite Fix Loop、State Rot、Verifier Theater、Notification Fatigue、Token Burn、Over-Reach、Comprehension Debt Spiral、Cognitive Surrender、Parallel Collision、Escalation Failure)都能追溯到上面某一项检查被跳过。例如 "Verifier Theater"(验证者批准了但 CI 失败)对应"验证者没跑测试、与实现者同模型同上下文";"Parallel Collision"对应"没有 worktree 隔离、两个 loop 无协调地作用于同一 PR"。

安全底线:生产 loop 的护栏

任何要碰代码或外部系统的生产 loop,都必须满足 docs/safety.md 的最低护栏。其中与概念层最相关的是:

  • Path Denylist:**/.env、**/secrets/**、**/credentials/**、**/.terraform/**、**/migrations/**、**/auth/**、**/payments/**、**/billing/** 等路径未经人类批准禁止自动编辑。tools/loop-gate 从 gate.yaml 机械执行该 denylist(以及自动合并 allowlist):loop-gate check --action <type> --paths <changed files> 以退出码 2 表示升级、0 表示放行。gate.yaml 还设置 maxFiles: 10——触碰超过 10 个文件的改动无论触碰哪些路径一律升级。
  • Auto-Merge 默认关闭;即使对琐碎 loop 开启,也只允许"注释/文档里的错别字""仅测试文件里的 lint 自动修复"这类无行为变更项。
  • Human Gates 必选:安全/认证/授权、支付/计费/PII、基础设施/Terraform/K8s 生产、依赖升级、触碰文件数超过 N(建议 10)、同一项第三次失败。
  • 预算协商:L3 loop 接近日上限时可经 skills/budget-negotiator/SKILL.md 请求追加预算,但 Agent 不能自行提高 loop-budget.md 中的上限——必须由人类显式批准并编辑。

下一步阅读

登录后查看全文
loop-engineering