运行循环一个月后，我学到了什么？

上周我写了关于循环工程的文章：从提示智能体完成任务，转向设计系统让智能体自主决定做什么、执行、验证并随时间改进。但很多人表示：好吧，我被说服了，但我到底该怎么构建一个？更重要的是，如何构建一个真正能工作的？ 因为任何人都可以把智能体包在一个无限循环里，然后称之为循环。那只是简单的5%。真正的工作在于让你能放心离开的护栏。过去一个月，我们一直在通过设置大量循环来运行@SuperDesignDev进行实验，这里想分享一些实际的经验教训。

一个好循环的构成

我们运行的每个循环都有相同的四个部分。

1. 循环契约

一个Markdown文件，每次运行时注入给智能体。这是循环的宪法。它包含四样东西：

• 目标（赢是什么样子，是否有终点线）
• 边界（可以自由做什么、绝不能做什么、自主交付与需要人类介入的界限）
• SOP（每次运行遵循的步骤）

人们往往在边界部分投入不足，而正是它决定了你是否能放心离开。以我们的一个循环 Error Sweep 为例：每天早晨它读取生产环境错误追踪器，挑选最严重的新错误，并交付修复。以下是其契约中真实的边界片段：

• 仅在根因明确且修复风险低时修复。任何风险高或体量大的：打开PR并标记给人类。不要自行合并。
• 做最小且有效的修复。每次修复一个PR。
• 如果前一个Error Sweep的PR尚未合并，绝不打开新PR。
• 绝不将凭据、令牌或用户数据复制到报告或PR中。

这些都不是关于如何修复错误。它们是四条划定围栏的句子。围栏内智能体自主交付，围栏外由人类决定。你需要为智能体清晰描绘：何时可以自主交付 + 何时应停下询问。

我们通常将契约、状态、日志放在一个md文件中，就像下面的Markdown：

# — 契约

## 目标
赢是什么样子。是否有终点线，还是作为监控器永远运行？

## 边界
- 可自由做：...
- 绝不做：...
- 自主交付 vs 询问人类：

## SOP（每次运行）
1. 读取状态+日志。
2. 收集变更。挑选最重要的一件待办事项。
3. 执行（或交给执行器）。
4. 验证。记录发生了什么。报告。

## 当前理解
...循环运行的当前状态

## 日志
...过去运行的日志

2. 状态 + 日志

忘记每次运行间信息的循环只是加了步骤的cron作业。它需要记忆，分为两部分：

• 状态（State） 是持久的画面：积压任务、当前假设、已交付的需要跟进的实验。每次运行开始时读取，故意保持精简。
• 日志（Logs） 是仅追加的记录，记录每次运行发生了什么。

最清晰的例子是我们Error Sweep循环维护的状态，这样它就不会浪费一次运行去重新调查已经理解的问题：

## 跳过这些指纹（已知噪音或上游问题，非我方）
- ResizeObserver循环限制超出
- Stripe.js在/checkout的网络波动

## 已修复，仍在监控
- null-team-on-login (019edc8a) — 已在#1027修复，确认在生产环境不再触发

没有这个区块，每天早晨循环都会重新发现同一个噪音错误，浪费一次运行去追查，并惹恼你。有了它，循环跳过已经判断过的问题，将注意力集中在新的东西上。状态是循环停止重复自身的地方。

状态还保存循环通过运行学到的知识：关于用户转化的有效假设，以及从错误中吸取的习惯。我们的CRM循环包含如下内容：

• 第一周遇到信用墙的用户回复率约是其他人的3倍。优先起草这些。
• 起草前检查用户实际构建了什么，而不是他们个人资料上的标签。一个标记为“SaaS仪表盘”的账户实际上是一份印刷宣传册。

这些都不是来自原始契约。循环一次运行地获取它们，现在每次运行都从一个更聪明的起点开始。这就是为什么一个好的循环在第三个月比第一周更有价值：它的状态已经吸收了它看到的一切。

我们用于管理循环的内部工具，在此开源（Loopany）：https://github.com/superdesigndev/loopany-platform

3. /验证（/verify）

这是任何交付高重要性工作（例如，真正的生产代码变更、给真实客户发消息）的循环的前提条件。基本上，你需要确保验证过程简单 + 产生人类容易审查的证据。

通常这意味着：

• 设置环境，使验证令牌高效且可靠
• 包含验证证据的方式

对于工程任务，这意味着：

• dev-local.sh脚本，轻松启动本地开发 + 远程沙箱环境进行测试（如crabox）
• 允许智能体像真实用户一样自驱动应用的工具（如Playwright-CLI）
• /verify技能，包含测试的SOP
• 上传截图和视频证据的位置，附加到PR中（我们上传到GitHub release assets）

而对于非工程工作，可能更棘手，但并非不可能。例如，对于CRM循环，我们有一个验证智能体，根据特定的反垃圾规则审查起草的消息；我们将工程任务的设置开源为一个验证器设置技能（https://github.com/AI-Builder-Club/skills）。

结果是，来自循环的PR不会以“相信我，它有效”的形式出现。它带着一个显示其工作的视频到达。我可以在几秒钟内批准，因为我看到的是行为，而不是阅读diff并祈祷。这也是验证器成为决定一个循环是否好主意的关键因素。

4. 触发器（Trigger）

是什么唤醒了循环。有三种形式，选择合适的是一半的成本模型：

• 连续for循环。 这是ralph-loop或/goal类型的触发器。智能体在for循环中运行，直到满足条件。这是自主研究智能体背后的形态。适用于有明确边界的推进（“继续直到测试套件变绿”），作为永久固定装置则浪费。这主要在有即时反馈循环和清晰规范时有用（如大多数修复错误的工程工作）。
• 基于时间。 按计划触发循环：每小时、每天早上6点。我们的Error Sweep、React Doctor、文档维护和CRM循环都使用cron运行。
• 工作流/事件驱动。 新邮件到达、事件开启、PR落地。循环只在有事可做时运行。它甚至可以与基于时间结合——例如，一个基于时间的tick每小时运行一个脚本检查是否有新的支持工单，如果有，触发智能体；否则，记录并静默。这是管理循环成本的好方法；你会在Evolve部分看到其机制。

编排器（Orchestrator）+ 执行器（Executor）+ 验证器（Verifier）

一旦循环处理任何非平凡的事情，我们开始将其拆分为三个角色：

编排器发现工作。执行器在隔离的盒子中完成工作。验证器证明工作并附上证据。

• 编排器/优先级排序器。 按计划唤醒的智能体。它的工作不是完成任务，而是找到任务：收集信号、查看变更、挑选本次运行最有价值的一件事，并交接。
• 执行器。 在隔离空间中完成实际工作（对于代码，从主分支创建一个新的git工作树，永不污染你的工作目录或其他循环的运行）。
• 验证器。 独立确认执行器的工作，并产生人类可以快速浏览的证据。

但并非所有循环都需要这三个角色。三层结构是复杂的、交付代码的循环的发展形态。很多好的循环只是编排器自己完成所有工作。让我展示两种极端。

进化循环（Evolve Loop）——构建反脆弱循环

在纳西姆·塔勒布的《反脆弱》中，他将系统分为三种：脆弱系统害怕波动，一次事故意味着巨大损失；稳健系统在波动中存活并恢复到原状；反脆弱系统从中获益，每次冲击都让它变得更强大。玻璃是脆弱的，石头是稳健的，你的免疫系统是反脆弱的：每次轻微感染都会训练它。

将其指向循环，问题变得具体：当一次运行失败时，教训去哪里了？

在实践中，教训有三个去向，按抽象程度递增：

人人都有日志，而且它们只会越来越长。将经验提炼成规则是使循环反脆弱的关键。问题是：谁来提炼？

所以在Loopany（我们为这些循环构建的内部应用）中，这成为一个独立的运行角色：进化（evolve）。一个智能体会话读取循环最近十几次运行的日志、结果和成本，并问：我们在哪里重复犯错误？哪些运行被浪费了？哪个边界太松，哪个太紧？它的输出不是产品代码，而是对循环本身的更改：

• 循环契约、状态约定
• 触发机制
• 用于重复化、确定性的智能体步骤的脚本
• 技能
• 人类查看的仪表板

这是一个改进循环自身的循环。

Superdesign实际运行的循环

我们一直在运行循环来自动化Superdesign的大部分工作，有些成功了，有些没有（经验教训会在另一篇博客中分享）。以下是几个我们日常运行的、相对容易复制和设置的实例。

文档维护循环

这是最简单、最有用的循环之一。每周一次，它保持项目文档的准确性；这个循环只有一层。编排器读取diff，检查文档，如果发现偏差则打开PR，然后就完成了。没有单独的执行器，没有单独的验证器，因为任务简单、影响范围小，一个智能体就能处理。你可以添加层——一个验证器来事实核查每个文档声明，一个通道来标记发现的技术债务。但你不应该，至少在简单版本让你吃苦头之前不要。先构建1层版本，感受具体痛点，然后只添加解决该痛点的层。

这是我会推荐你先构建的循环，这里是一个模板：

# doc-maintainer — 契约

## 目标
README、设置指南和示例始终与代码实际交付的内容匹配。零偏差发现 = 成功运行，而不是浪费。

## 边界
- 自主交付：打开一个包含修复的PR。仅此而已。
- 绝不做：重写准确的文档以显得忙碌，接触文档以外的任何内容，在上周的PR未关闭时堆第二个PR。

## SOP（每次运行）
1. 读取diff：自上次扫描以来的每个提交和PR（游标在状态中）。
2. 将README、设置指南、示例、运行手册与代码当前交付的内容进行比较。
3. 真正验证：运行命令、检查链接、尝试示例。绝不依赖记忆。
4. 发现偏差→进行最小修复，新建工作树，打开一个PR解释什么偏差了以及原因。没有过时内容→干净停止。
5. 移动游标，记录运行。

## 状态
- 上次扫描游标（提交哈希）
- 打开的PR（如有）

## 日志
- 每次运行一行：偏差数量 + PR链接，包括零偏差的情况

Bug猎人循环

有些循环向真实客户交付真实代码，错误代价高昂。这时三个层都发挥作用。我们的 Error Sweep 循环每天早上运行：

• （编排器） 它从错误追踪器拉取过去24小时的生产错误（我们编写了一个特殊脚本从Posthog/LLM日志/服务器日志收集数据），按出现次数x用户数排序，跳过状态中的已知噪音指纹，挑选最具影响力的新异常。它提取去minified的堆栈跟踪并找到根因。
• （执行器） 如果根因明确且风险低，在全新工作树中修复并交付PR。如果风险高或体量大，停止并标记给人类。边界中的那个分支每次运行都在做实际工作。
• （验证器） 修复在计入之前被验证，循环在后续运行中持续观察该指纹，确认错误确实停止触发。不能降低实际指标的修复不是修复。

React Doctor 是同样的结构，但针对代码健康而非运行时错误：每天早上它用npx react-doctor扫描应用，挑选最严重的一个问题，在隔离工作树中修复、验证并打开一个PR。它报告健康分数作为每日指标，让你可以观察趋势线。它有一个小的护栏，使其保持可用：

如果之前的React Doctor PR仍然打开未合并，今天不要打开另一个。刷新打开PR的状态，仍然报告分数。

这条规则区分了有帮助的循环和会把你埋在30个永远不会审查的PR中的循环。一个循环必须尊重你的审查带宽，而不仅仅是它自己的吞吐量。

支持工单分类循环

每小时针对Intercom收件箱运行一次。其指导原则：每个支持工单都是一个免费的窗口，窥见产品缺口。 写消息的用户免费提供给你一个错误报告、转化障碍或困惑信号。大多数支持系统回复消息并扔掉窗口。这个循环保留两者。

每次运行执行四个步骤：

• 拉取窗口。 自上次运行以来的所有消息，加上今天到期的任何跟进。窗口在静默时间自动扩大，这样遗漏的触发永远不会丢失工单。按最后发言者分类：客户=需要回复，机器人=审查，队友=已处理。
• 在回复之前调查。 这是差异化之处。对于每个工单，先根据真实数据进行根因分析：检查用户的账户、实际会话、错误日志、账单记录。绝不盲目回答。一半情况下用户描述的问题不是真正的问题。
• 分发给三个输出。 每个工单最多产生三件事：一个回复，立即在消息线程中解决用户问题；一个信号，归档到知识库：工单背后的产品缺口，一次性记录下来，以便增长和工程循环以后可以处理该模式；当根因是一个真正的bug时，它生成一个修复智能体，在全新工作树中，带有验证器和证据，与bug猎人循环相同的机制。
• 回复并休眠。 设置跟进日期，记录运行，等待下一个tick。

使其安全处理真实客户的边界条件：回复分等级。常规、事实性的答案自主交付。任何敏感的、退款、愤怒用户、非英语且我无法审阅语气的，只在人类批准后发送。

设置它 与其他循环相同：一个契约文件加一个每小时的cron。以下是支持契约，简化为一个你可以抄的模板：

# support-triage — 契约

## 目标
每个入站工单在一小时内得到正确、经过调查的回复，并且工单背后的每个产品缺口成为团队可以处理的信号。没有终点线：这是一个监控器。

## 边界
- 自主交付：回复常规、事实性问题（如何使用、账单查询、已知问题并有文档修复）。
- 先问人类：退款、愤怒或有流失风险的用户、任何法律问题、任何团队无法审阅语言的回复。
- 绝不做：承诺功能或时间表、共享其他用户数据、在没有记录根因的情况下关闭工单。

## SOP（每次运行）
1. 拉取自上次运行时间戳以来的对话 + 今天到期的跟进。按最后发言者分类（客户/机器人/队友）。
2. 每个工单：在起草任何内容之前，针对产品数据库、错误日志和账单调查根因。绝不盲目回答。
3. 根据边界层级回复。需要批准的地方只起草。
4. 如果根因是bug：在全新工作树中生成修复智能体，要求验证证据，打开一个标记给团队的PR。
5. 为任何重复或与转化相关的缺口记录信号（先与现有信号去重）。
6. 设置跟进日期。记录运行。

## 状态
- 未完成的跟进（工单id -> 到期日）
- 重复主题统计（用于创建信号）
- 持续教训（例如“重复计费”的常见模式）

## 日志
- 每次运行一行：处理的工单数量、回复数量、打开的PR数量、记录信号数量