# 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 + 交付对账

Roll 采用不同的协调方式。没有中心规划器，没有共享执行图，而是职责单一的**独立 Loop**，再加一个按机会推进已发布交付的事件型 Delivery Reconciler：

```
         BACKLOG  ←──────── 共享状态 ────────→  git / PR / alert
            │
    ┌───────┼──────────────┬──────────┐
    ▼       ▼              ▼          ▼
主 loop  交付对账器       dream      brief
 cycle   边界/读路径       daily      daily
 交付    合并+main 记账    扫描       摘要
 story
```

每个 Loop 在会话驱动期间：
1. **轮询**特定 artifact（BACKLOG、open PR、alert 文件）
2. **行动**（写代码、heal CI、合 PR）
3. **写回**共享 artifact（提交、PR 评论、BACKLOG 更新）
4. **休眠**直到下一个周期

Loop 之间从不直接调用对方，完全通过 artifact 协调。交付对账器不是 daemon：cycle 边界、读路径和 `roll loop reconcile` 都运行同一个幂等真相引擎。

---

## 这是编舞（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

发布边界触发 reconcile tick：
  → 发现 PR 是 open，CI 还在跑 → 保持 awaiting_merge

下个 cycle / 读路径 / 显式 reconcile tick：
  → CI 绿，可合并 → 合 PR → 完成
```

没有编排器，没有依赖图。每个 Loop 在合适的时机做自己的事。

---

## 为什么 Loop 更适合持续交付

软件交付不是一次性任务，而是持续进行的过程：

- BACKLOG 里不断有新 story
- 生产环境暴露 bug
- 依赖包过期
- CI 变慢
- PR 积压

DAG 被设计为执行一次后终止。Loop 被设计为只要有人驱动就一轮接一轮地跑，在条件合适时领下一件有价值的工作。持续交付需要 Loop —— 由会话驱动，而不是由定时器。

**韧性**：Loop 相互隔离。一轮 cycle 失败不会拖垮其他项目；后续任意 Roll 调用都能从事件账本与 main 继续对账。

**可观测性**：Loop 的每一个动作都会产生一个 git commit、一条 PR 评论或一次 BACKLOG 更新。系统的历史就是 git log——人类可读、可 diff、可回滚。

**人类控制**：想暂停交付？在 BACKLOG 里设个标志。想优先处理某个 story？编辑优先级。想停掉交付？结束会话，或者 `roll loop pause`。不需要打断一个运行中的编排器或取消正在飞行中的 Agent 链。

**增量正确性**：TCR（Test-Commit-Revert）确保每个微步骤要么将代码库推进到绿色状态，要么干净地回滚。Loop 在两次 cycle 之间绝不留下损坏的仓库状态。

---

## 专职 Loop 架构

随着系统成熟，Loop 越来越专职化：

| Loop | 节奏 | 职责 |
|------|------|------|
| **主 loop** | 30 分钟 | 读 BACKLOG → 写代码 → 开 PR |
| **交付对账器** | cycle 边界、读路径、显式命令 | 合并符合条件的绿色 PR，并从 main 证据记账 |
| **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** | 按需（`roll dream run-once`） | 反思近期工作，优化 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。