企业官网建设流程全解析

本篇文章基于 learn-harness-engineering 仓库中 loop-state-template.md 展开。仓库为只读资源，文中所有分析与示例均用于帮助读者理解、查看与运行，不涉及对仓库本身的修改。

导读

在循环工程（Loop Engineering）中，每个 Agent 循环都必须有一个持续跟踪当前进度的状态文件——这就是 Loop State Template（循环状态模板）存在的意义。本篇文章带你逐段拆解这份模板的完整结构，说明它如何在"每轮结束更新、每轮开始读取"的节律中充当循环的外部状态记忆，并结合仓库中配套的 Goal / Maker / Checker 模板，讲清楚如何在真实项目中落地一个带状态、可追溯、可干预的 Maker-Checker 循环。读完本文，你将能够直接复制这套模板到自己的循环工程里，并用累计统计与阻塞列表驱动"是否需要人工介入"的判断。

循环为什么需要状态文件：外部状态原语

在 第13讲：手动提示到自主循环 中，作者将循环工程拆解为六个原语：自动化（Automation）、Worktree 隔离、技能（Skills）、连接器（Connectors）、子代理（Sub-agents）与外部状态（External State）。其中外部状态被单独强调为"循环的骨架"——其他所有原语都依赖它。

原因很简单：模型在每次执行之间会忘记一切。记忆不能存放在上下文窗口里，而必须存放在磁盘上。Loop State Template 正是这一理念的最小落地物——它用一份 Markdown 文件回答循环最核心的三个问题：

1. 循环现在进行到哪了？（Basic Info / Cumulative Stats）
2. 每一轮发生了什么？（Round Log）
3. 下一步该做什么、卡在哪里？（Next round plan / Blocker List）

正如模板开篇注释所写：

Every loop should have a state file tracking current progress. Update at the end of each round; read at the start of the next round. （每个循环都应该有一个状态文件跟踪当前进度。每轮结束时更新它；下一轮开始时读取它。）

这一"轮末写入、轮初读取"的节律，正是循环摆脱单次会话记忆限制、实现跨轮连续性的关键。

模板总览：六个板块构成一份完整状态

Loop State Template 由六个板块组成，各自承担不同的职责。完整模板原文如下（可直接复制使用）：

# Loop State Template > Every loop should have a state file tracking current progress. > Update at the end of each round; read at the start of the next round. ## Basic Info - **Loop name**: <!-- e.g. "Unit test completion loop" --> - **Started**: 2026-07-09 10:00 - **Current round**: Round 1 / N total - **Current status**: In progress <!-- In progress / Completed / Blocked / Failed --> - **Total elapsed**: 0h 0m ## Goal <!-- What this loop is trying to achieve --> ## Round Log ### Round 1 - **Started**: - **What the Maker did**: - **Verification result**: ✅ Pass / ❌ Fail / ⚠️ Partial - **Issues found**: - - **Next round plan**: - **Human intervention needed**: Yes / No ### Round 2 - **Started**: - **What the Maker did**: - **Verification result**: ✅ Pass / ❌ Fail / ⚠️ Partial - **Issues found**: - - **Next round plan**: - **Human intervention needed**: Yes / No <!-- Copy the format above and keep adding --> ## Cumulative Stats | Metric | Value | |--------|-------| | Rounds completed | 0 | | Passed rounds | 0 | | Failed rounds | 0 | | Total issues found | 0 | | Human interventions | 0 | | Files changed | 0 | ## Blocker List <!-- Record recurring issues so the next round is aware --> - ## Final Result <!-- Fill in when loop ends --> - **Final status**: Completed / Failed / Manually stopped - **Finished at**: - **Summary**: - What was done - How it went - What was learned - How to improve next time

下面逐板块讲解其设计意图与使用要点。

Basic Info：循环的元数据与心跳

Basic Info 是循环的"身份证"，回答"我是谁、跑到哪了、还活着吗"：

• Loop name：循环的唯一标识，例如 "Unit test completion loop"（单测补全循环）。建议使用与任务强相关的命名，便于多循环并行时区分。
• Started：启动时间戳。它是计算 Total elapsed 的起点。
• Current round：当前轮次，如Round 1 / N total。N可以是预算上限，也可以先写为占位，循环结束后回填实际总轮数。
• Current status：循环的四态枚举——In progress（进行中）/Completed（已完成）/Blocked（阻塞）/Failed（失败）。这一字段是循环控制逻辑判断"是否继续"的首要依据。
• Total elapsed：累计耗时。长时间运行的循环（数小时甚至数天）尤其需要它，用于判断是否超出时间预算。

这五个字段共同构成了循环的"心跳"，任何外部观察者（人类或另一个代理）只需读取 Basic Info 就能快速判断循环的健康状况。

Goal：把目标固化到磁盘

Goal 板块只有一行注释占位（<!-- What this loop is trying to achieve -->），但它承担着最重要的作用：把循环要达成的最终状态固化下来。

在 goal-template.md 中，仓库给出了更完整的"目标文档"写法，包含四个部分：Goal（一句话目标）、Acceptance Criteria（机器可验证的验收标准）、Scope（Fair game / Hands off 边界）、Stop Conditions（停止条件）。Loop State Template 中的 Goal 板块正是 goal 文档的浓缩版——它不重复全部细节，而是确保每个循环的每一轮都能看到"我们最终要达成什么"。

一个可参考的填写示例：

## Goal 为所有 API 模块补齐单元测试，使模块覆盖率 ≥ 80%，且 lint 零错误、TypeScript 类型检查通过。

目标越具体、越可机器验证，循环质量越高——这与 goal-template.md 开头强调的 "The more specific and verifiable, the higher the loop quality" 一脉相承。

Round Log：逐轮事实记录

Round Log 是模板中最核心、也是篇幅最大的板块。每一轮都是一个### Round N小节，包含六个字段：

• Started：本轮开始时间。
• What the Maker did：Maker（实现代理）本轮实际做了什么——改动了哪些文件、实现了什么逻辑。注意这里的"Maker"指代循环中的实现角色，与 maker-prompt.md 中定义的 Maker Agent 一致。
• Verification result：验证结果三态——✅ Pass（通过）/ ❌ Fail（失败）/ ⚠️ Partial（部分通过）。部分通过通常意味着"主路径通了但存在边缘用例或质量问题"。
• Issues found：本轮发现的问题清单，逐条列出。若验证者是 Checker 角色，这些问题应当来自 checker-prompt.md 中要求的"每个问题必须包含描述、位置、证据与严重级别"的输出。
• Next round plan：下一轮的计划。这是循环"自主决策"的书面化——上一轮结束时把下一步计划写下来，下一轮开始时直接按计划执行，避免每次重新头脑风暴。
• Human intervention needed：是否需要人工介入（Yes / No）。这是状态文件与人类之间的"信号接口"。

Round Log 的设计要点在于只记事实、不写评价。每轮记录"做了什么、验证结果如何、发现什么问题"，让整条时间线完全可追溯。模板通过注释<!-- Copy the format above and keep adding -->提示使用者：按此格式持续追加### Round N小节，直到循环结束。

Cumulative Stats：把散落数据汇成决策指标

Cumulative Stats 是一张六行指标表，把 Round Log 中散落的记录汇总为可决策的累计数据：

这六项指标让循环的运行轨迹一眼可见：如果 Failed rounds 持续增长而 Passed rounds 停滞，说明循环正在原地打转，应该触发人工介入或停止条件；如果 Human interventions 频繁为 Yes，说明任务的自动化边界还没设计好。

在 project-07 项目文档 的"实验3：Maker-Checker 循环"中，作者要求"每个循环的loop-state.md至少记录 5 轮"，且每轮都要记录"轮次编号、Maker 做了什么、Checker 发现了什么问题、通过/失败、你是否介入以及为什么介入"——这正是 Cumulative Stats 与 Round Log 组合使用的规范操作。

Blocker List：跨轮记忆的关键

Blocker List 是模板中最容易被忽略、却最体现"外部状态"价值的板块：

它专门用来记录反复出现的问题，让下一轮开始时对已知障碍心中有数。例如：

## Blocker List - 构建环境缺少 Python 3.11，需人工安装（第 2、4 轮均因此失败） - `src/main.ts` 与 `src/xx/` 存在未声明的隐式依赖，改 `xx/` 会破坏构建

它的意义在于：模型每一轮都会"失忆"，但如果把反复踩到的坑写进 Blocker List，下一轮读到状态文件时就会带着这些记忆开始——这正是"模型会忘记，但仓库不会忘记"的具体体现。

Final Result：循环的收尾与复盘

当循环结束时（无论 Completed / Failed / Manually stopped），在 Final Result 板块填写最终结果：

• Final status：终态枚举——Completed（完成）/ Failed（失败）/ Manually stopped（人工停止）。
• Finished at：结束时间。
• Summary：四段式总结——做了什么（What was done）、进展如何（How it went）、学到了什么（What was learned）、下次如何改进（How to improve next time）。

四段式总结的价值在于把"一次循环的经验"沉淀为"下次循环的输入"。改进点可以回填到下一份 Goal 模板或 Maker / Checker 提示词中，形成组织级的学习闭环。

实战落点：与 Maker / Checker / Goal 模板的配合

Loop State Template 不是孤立存在的。在仓库的 lecture-13 code 目录 中，它与其他三份模板构成了一套完整的循环工具箱：

一个典型循环的运转方式如下：

1. 轮初读取：新一轮开始时，循环控制逻辑（或下一个代理）读取loop-state.md，获取上一轮结果、当前轮次、Next round plan 与 Blocker List；
2. Maker 执行：Maker 按 maker-prompt.md 实现本轮任务，产出"修改文件清单 + 实现摘要 + 基础验证结果 + 不确定区域"；
3. Checker 验证：Checker 按 checker-prompt.md 逐项核对清单并运行验证命令，输出"总体裁决 + 问题清单（含位置、证据、严重级别）+ 验证命令结果"；
4. 轮末写入：根据 Checker 结果更新loop-state.md——追加 Round Log、刷新 Cumulative Stats、必要时更新 Blocker List 与 Current status；
5. 停止判断：对照 goal-template.md 中的停止条件（验收全部通过 / 达到最大轮数 / 连续 3 轮无进展 / 遇到无法独立解决的阻塞）决定继续还是终止。

其中，Checker 的"每个问题必须附带证据"要求，直接保证了写入 Round Log 的 Issues found 是可信的——这正是循环工程中最重要原则"Maker 与 Checker 必须分离"（代码的作者不能为自己的作业打分）在状态层的体现。

落地建议与最佳实践

综合模板本身与 第13讲 的论述，以下是使用 Loop State Template 的几条实战建议：

1. 文件命名统一：将状态文件命名为loop-state.md并放在循环工作目录的固定位置，便于每个代理稳定读取（project-07 实验3 即采用此约定）。
2. 每轮必更新、更新必完整：六项 Basic Info、本轮 Round Log、Cumulative Stats 必须在轮末一次更新到位，切忌拖延——状态文件一旦滞后，循环就失去了记忆。
3. 用三态而非二态判断验证：✅ Pass / ❌ Fail / ⚠️ Partial 比简单的对/错更能反映真实情况，Partial 通常意味着需要 Maker 下一轮聚焦修复已知问题。
4. Blocker List 及时沉淀：只要某个问题出现两次，就写入 Blocker List；下一轮读到即绕开，能显著减少无效重试。
5. 以累计指标驱动人工介入：不要每轮都盯着屏幕，而是设定规则——例如"连续 2 轮 Fail 或 Partial 即触发人工介入""Human interventions 达到预算上限即 Manually stopped"。让状态文件替你决定何时需要你，而不是你替循环决定每一步。
6. 从最小状态开始：如第13讲"主なまとめ"所言，先从一个/goal、一个 cron、一份 Markdown 内存文件开始，看到收益后再向上叠加。

Loop State Template 的哲学可以浓缩为一句话：模型会忘记，但仓库不会忘记。把循环的进度、问题与决策写进磁盘上的状态文件，你的循环才能真正脱离你的键盘、自主运转。