Agent Architecture Lens 是一个用于审查智能体架构的技能，关注控制流、持久状态、重试与恢复。它的出发点是 ReAct 循环——推理、行动、观察、重复——这是每个智能体的原子，本身是正确的，但也是不完整的：随着运行时间变长、过程变乱，它不会以一次戏剧性的失败告终，而是悄悄变得不够用。
核心原则
该技能主张：架构跟随任务的形状与时长，而不是图表的优雅。一个循环就是只有一个节点、一条指向自身的边的图。两条主线贯穿每次审查：第一，图不是升级——结构是对你实际遇到的需求的回应，因此没有此类需求的任务应保持循环，审查也应如实说明；第二，账本而非记录——必须经受任何情况而存活的进度存放在持久工件中，而不是模型希望记住的消息历史里。审查时要明确说出这两点。
第一遍：六个信号
在推荐任何结构之前，先说明六个信号中哪些触发，并编号：
- 状态超出单个上下文窗口。运行跟踪的内容超过模型工作记忆的容量。
- 运行必须抗崩溃。执行中途丢失不可接受——数分钟的工作、真实的 API 花费、等待中的用户。
- 运行中需要人工审批。在智能体继续之前必须有人审查，而他们可能需要数小时。
- 工作流有并行分支。真正独立的子任务不应被串行化。
- 多个模型或智能体必须协调。不同步骤需要不同的模型、工具或权限。
- 执行必须可重放且可审计。事后有人会问“这次运行到底发生了什么？”
零信号触发 → 建议保持循环并停止。直说：“没有信号触发；这保持为循环——图不是升级。”在此处添加结构只会带来延迟和测试面，回报为零。
一个或多个触发 → 每个信号都指明设计所欠的具体机制，下面的检查只验证这些。不要引入其余部分。
升级阶梯
结构按以下顺序添加，因为每一级都比前一级成本更高。每一级都必须由实际触发的信号来证明其合理性。
- 外部化状态。把运行必须记住的内容从消息列表中抽出，放入带命名字段和声明默认值的类型化结构。回报最高、成本最低——模型不再需要翻找自己之前的推理来找到六步前产生的值。
- 添加检查点。每步之后写入状态，使崩溃后能恢复而非重新开始。这是真正的循环到图的转变。
- 按职责拆分为命名步骤。当步骤需要不同的模型、工具、权限或错误处理时拆分。一步一职。
- 分支与并行。最后，且仅用于真正独立的工作或真正分岔的路线。
信号 1 和 6 通常在第 1 级满足。信号 2 和 3 需要第 2 级。信号 5 需要第 3 级。只有信号 4 需要第 4 级。
实现视角
按顺序检查以下五个方面。跳过任何信号未触发的方面。
状态
检查运行记住什么、存放在哪里、谁写入、增长成本如何。
要问：
- 哪些值必须比当前上下文窗口活得更久，哪些是真正的临时值？
- 每个持久化字段是否都有类型、默认值，以及两个步骤同时写入时的处理规则？
- 如果状态丢失，能否从持久输入重建，还是它是唯一副本？
- 大负载是内联在状态中，还是放在外部存储 id 之后？
- 什么限制了消息历史的增长——在 token 阈值处进行摘要步骤，还是什么都没有？
重试
模型永远不决定重试。存在于模型推理中的重试计数会产生两种失败模式：对已死端点尝试十五次，以及只尝试一次后编造结果。
要问：
- 尝试次数是否写在下次执行会读取的地方，还是每次从记忆中重新推导？
- 计数器是否在尝试之前递增？尝试中途崩溃仍必须计为一次尝试。
- 计数达到上限时的回退路线是什么——命名的升级，还是未处理的死胡同？
- 重试的步骤是否区分暂时性失败与永久性失败，还是对两者同样重试？
- 是否存在失败工具可以在没有外部计数限制的情况下被再次调用的路径？
终止
每次运行需要三个出口：成功、重试耗尽、硬上限——最大步数、最大 token、花费上限或截止时间。三个中有两个，就是一个戴着停止条件的无界运行。
要问：
- 哪个条件成功结束本次运行，它是状态值还是模型自认为完成？
- 当工作无法完成时会发生什么——有命名的失败出口，还是循环？
- 硬上限是什么，以无需模型配合即可计数的单位表示？
- 谁观察到上限被触及，他们看到什么？
- 对于任何长时间运行或付费的操作：是否有花费上限，用户是否被告知？
副作用
将决策（“这封邮件应该发送，内容如下”）与执行（“发送它”）分开。决策步骤可安全重放；执行步骤必须幂等，因为副作用与检查点之间的崩溃会在恢复时重放该步骤。
要问：
- 哪些步骤在运行之外写入——消息、提交、PR、工单、支付、部署？
- 每个是否携带在效果之前写入状态的稳定键，并在重新执行时在顶部检查？
- 行动决策是否与行动本身分开记录，以便重放只重新执行后者？
- 两个并行步骤能否写入同一状态字段或命中同一限流 API？
- 工具是否按步骤限定范围，使只应读取的步骤无法写入？
恢复与门控
要问：
- 人工门控在哪里暂停运行，审批能否在进程重启后存活——还是只是一个会消失的对话轮次？
- 恢复时，什么标识该运行，它如何找到要恢复的步骤？
- 是否有崩溃恢复测试——运行中途杀死、重启、断言它在正确的步骤以正确的计数器恢复？这是必需的集成测试，不是可选的。
- 执行轨迹能否回答“运行了什么、以什么顺序、输入输出是什么”？
- 什么清除旧检查点，审计窗口是多久？
图的成本
推荐结构时要说出成本——这正是该视角能让普通循环返回 proceed 的原因。
成本与表现：
- 延迟：每个检查点是一次写入，每个边界是一次序列化周期——真实但通常不可见；对亚秒级交互工作有影响。
- 协调：并行分支需要汇合点，每个分支独立失败——比循环版本需要更多错误处理代码。
- 路径爆炸：三个条件路线最多产生八条执行路径，每条路径都需要测试。
- 模式设计：每个状态字段需要类型、默认值和写入规则；弄错了错误会在每一步浮现。
- 维护：重试逻辑、回退路线、错误处理器和上限都是循环所没有的新代码。
图更可靠，正是因为它不把编排托付给模型。这种可靠性是用工程小时换来的。
输出契约
返回：
- verdict：proceed 或 revise。
- signals_fired：六个信号中哪些适用，按编号，每条一行证据。空列表是有效且常见的结果。
- blocking_findings：需要修改计划的关键发现（proceed 时为空）。
- advisory_findings：值得带入实现的非阻塞观察。
- required_changes：编号的计划修正（仅在 revise 时）。
当该视角改变了工作时，用一行说明：
Agent architecture lens: signals [n] fire, so [mechanism owed]; [main risk], bounded by [ceiling].
注意事项
- 不要因为设计看起来更严肃就推荐图。零信号意味着循环就是答案。
- 不要把并行当作 sophistication——它成倍增加测试面，是最后一级，不是第一级。
- 不要接受“智能体完成后会停止”作为终止条件。它需要三个出口。
- 不要接受仅以文字陈述的重试上限。如果模型之外没有任何东西计数尝试，就没有上限。
- 不要让检查点永远累积——无界状态增长是一场缓慢的停机。
参考资料
按需加载，不要预先加载：
- references/failure-modes.md — 症状 → 结构补救，并校准无界运行实际能走多远。
- references/state-and-checkpoints.md — 类型化状态模式设计、检查点节奏、TTL 与清除。
- references/topologies.md — 循环、路由器、编排者-工作者、评估者-优化者、带汇合的并行扇出。