@seanyao/roll 4.630.2 → 4.702.2

package/guide/zh/loop-driven-architecture.md

@@ -0,0 +1,186 @@
+# Loop 驱动的 Agent 架构
+
+> 为什么 Roll 用独立 Loop 而不是 DAG 多 Agent 编排——以及这对构建可靠的 AI 软件交付系统意味着什么。
+
+---
+
+## 主流方案：DAG + 编排（Orchestration）
+
+当前大多数 AI Agent 框架遵循相似的模式：规划器将目标拆解为有向无环图（DAG），将每个节点分配给专职 Agent，由编排器按依赖顺序驱动执行：
+
+```
+目标："实现功能 X"
+         │
+       规划器
+         │
+    ┌────┴────┐
+  Agent A   Agent B    ← 并行执行
+    │         │
+    └────┬────┘
+       Agent C         ← 依赖 A + B
+         │
+       输出
+```
+
+这个模型符合人类对项目管理的直觉，易于可视化和解释，在演示中表现良好。LangGraph、AutoGen、CrewAI 等框架都在推广这种模式。
+
+**问题所在：**
+
+- **脆弱性**：Agent B 中途失败，整个图就卡住了。恢复逻辑难写，更难测试。
+- **全知假设**：构建 DAG 要求在执行前就知道所有依赖关系。真实软件开发不是这样的——约束是在过程中才发现的。
+- **同步耦合**：所有 Agent 必须同时在线。一个慢的 Agent 会阻塞整条流水线。
+- **状态不透明**：执行状态存在编排器内部。出问题时，trace 是一张抽象的图——不是人类能直接审查和推理的东西。
+
+这些问题对于一次性任务（"总结这份文档"、"生成这份报告"）影响不大。但对于**持续软件交付**来说影响很大——工作是持续的，需求在演变，人类需要始终在回路中。
+
+---
+
+## Roll 的方案：独立 Loop 作为 Daemon
+
+Roll 采用不同的协调方式。没有中心规划器，没有共享执行图，而是**独立 Loop**——每个 Loop 是一个职责单一的 daemon，按自己的节奏运行，从共享 artifact 中读取并写回：
+
+```
+         BACKLOG  ←──────── 共享状态 ────────→  git / PR / alert
+            │
+    ┌───────┼────────┬──────────┐
+    ▼       ▼        ▼          ▼
+主 loop  PR loop  dream     brief
+  30min    5min     daily     daily
+  交付     heal +   扫描     摘要
+  story    rebase + 代码
+           merge
+```
+
+每个 Loop：
+1. **轮询**特定 artifact（BACKLOG、open PR、alert 文件）
+2. **行动**（写代码、heal CI、合 PR）
+3. **写回**共享 artifact（提交、PR 评论、BACKLOG 更新）
+4. **休眠**直到下一个周期
+
+Loop 之间从不直接调用对方。完全通过 artifact 协调。
+
+---
+
+## 这是编舞（Choreography），不是编排（Orchestration）
+
+这个区别很关键。**编排**中，中央权威告诉每个参与者做什么、什么时候做。**编舞**中，每个参与者知道自己的职责，并对共享环境中的事件做出反应。
+
+| | 编排（DAG） | 编舞（Loop） |
+|--|--|--|
+| 协调方式 | 中心规划器 | 共享 artifact |
+| 故障域 | 整张图 | 单个 Loop |
+| 状态位置 | 编排器内存 | git + BACKLOG + PR |
+| 人类可见性 | 抽象任务图 | `git log`、PR 列表 |
+| 人类干预 | 难——必须打断规划器 | 容易——编辑 BACKLOG |
+| Agent 可用性 | 必须同时在线 | 各自独立运行 |
+
+编舞是 Unix pipeline、微服务事件总线和分布式数据库背后的模式。Roll 将它应用到 AI 软件交付领域。
+
+---
+
+## 实际效果对比
+
+**DAG 方案**——"新增 Agent"：
+
+```
+规划器拆解：
+  → Agent 1：修改 CLI dispatch
+  → Agent 2：更新英文文档
+  → Agent 3：更新中文文档    ← 依赖 Agent 2
+  → Agent 4：写测试
+  → Agent 5：验证 CI         ← 依赖 1–4
+  → 编排器：开 PR
+```
+
+如果 Agent 3 超时，Agent 4 和 5 就等着。编排器必须决定：重试？跳过？失败？
+
+**Loop 方案**——同一个任务：
+
+```
+主 loop 触发：
+  → 读 BACKLOG → 选 "US-AI-004: 新增 agent"
+  → TCR 微步骤写代码（每步：测试 → 提交 或 回滚）
+  → 开 PR
+
+PR loop 触发（5 分钟后）：
+  → 发现 PR 是 open，CI 还在跑 → 跳过
+
+PR loop 再次触发（5 分钟后）：
+  → CI 绿，可合并 → 合 PR → 完成
+```
+
+没有编排器，没有依赖图。每个 Loop 在合适的时机做自己的事。
+
+---
+
+## 为什么 Loop 更适合持续交付
+
+软件交付不是一次性任务，而是持续进行的过程：
+
+- BACKLOG 里不断有新 story
+- 生产环境暴露 bug
+- 依赖包过期
+- CI 变慢
+- PR 积压
+
+DAG 被设计为执行一次后终止。Loop 被设计为永远运行，在条件合适时做有价值的工作。持续交付需要 Loop。
+
+**韧性**：Loop 相互隔离。CI loop 崩了，PR 仍然能被 review。主交付 loop 卡在冲突上，PR loop 仍然能合其他已就绪的 PR。
+
+**可观测性**：Loop 的每一个动作都会产生一个 git commit、一条 PR 评论或一次 BACKLOG 更新。系统的历史就是 git log——人类可读、可 diff、可回滚。
+
+**人类控制**：想暂停交付？在 BACKLOG 里设个标志。想优先处理某个 story？编辑优先级。想停掉某个 Loop？删掉对应的 launchd plist。不需要打断一个运行中的编排器或取消正在飞行中的 Agent 链。
+
+**增量正确性**：TCR（Test-Commit-Revert）确保每个微步骤要么将代码库推进到绿色状态，要么干净地回滚。Loop 在两次 cycle 之间绝不留下损坏的仓库状态。
+
+---
+
+## 专职 Loop 架构
+
+随着系统成熟，Loop 越来越专职化：
+
+| Loop | 节奏 | 职责 |
+|------|------|------|
+| **主 loop** | 30 分钟 | 读 BACKLOG → 写代码 → 开 PR |
+| **PR loop** | 5 分钟 | 合绿色 PR，关陈旧 PR，rebase 落后 PR |
+| **CI loop** | 5 分钟 | 检测 flaky 测试，收集耗时数据，重跑失败 |
+| **alert loop** | 1 分钟 | 聚合 `_LOOP_ALERT`，发送通知 |
+| **bug loop** | 1 小时 | 扫描日志和错误模式，开 FIX story |
+| **dep loop** | 1 天 | 检查过期依赖和 CVE，开升级 story |
+| **doc loop** | 1 天 | 检测代码/文档偏差，开文档 PR |
+| **dream loop** | 每晚 | 反思近期工作，优化 BACKLOG 优先级 |
+
+每个 Loop 只读写自己的 domain。它们之间的协调完全是涌现的——没有任何一个 Loop 知道其他 Loop 的存在。
+
+---
+
+## 取舍：什么时候用哪种方案
+
+Roll 的架构并非放之四海而皆准。根据问题选择方案：
+
+**用 DAG/编排，当：**
+- 任务有明确的、有限的范围（"从头构建这个服务"）
+- 所有依赖关系在执行前都可以确定
+- 需要严格的顺序控制（步骤 N 的输出是步骤 N+1 的精确输入）
+- 任务执行一次后终止
+
+**用 Loop/编舞，当：**
+- 工作是持续和持久的（软件交付、监控、维护）
+- 依赖关系在运行时才被发现
+- 韧性比紧耦合更重要
+- 人类需要观察和干预
+- 系统应该在某些组件失败时继续运行
+
+大多数真实的软件交付系统属于第二种。这就是为什么 Roll 基于 Loop 构建。
+
+---
+
+## 更深的洞察
+
+DAG 模型假设智能集中在规划器中——那个负责拆解目标的 Agent。Loop 模型假设智能是分布式的——每个 Loop 深度了解自己的 domain，并自主行动。
+
+实际上，"提前规划好一切"在现实偏离计划的那一刻就开始失效。Loop 没有可以偏离的计划。它们观察世界的当前状态（BACKLOG、open PR、CI 状态），并据此行动。如果 PR 有冲突，Loop 就 rebase。如果 CI 是红的，Loop 就重跑。如果 story 被 block，Loop 就跳过去做下一个。
+
+这更接近有经验的工程师实际工作的方式：不是执行一个预先承诺的计划，而是持续扫描环境，做当前最有价值的可行动作，并让一切保持干净的状态。
+
+Roll 将这种行为编码为 Loop。