以下运行 ID、计划、故障点与数字均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。W3 的"重启服务"是用于展示三平面职责的最小例子,真实系统还需要审批、变更窗口与审计。
一个 Agent 跑一次任务,看起来是一段顺序代码。但在生产里,这次运行横跨了三套不同的职责:谁决定下一步做什么,谁真正去执行副作用,谁记录已经发生的事实。把三者混在一起,是运行时架构最常见的起点错误——因为它们的故障行为完全不同,可恢复性也完全不同。
这一节回答三件事:控制面、执行面、数据面各自是什么;为什么必须拆开;以及故障落在不同平面时,恢复策略分别是什么。最后用一个可运行的最小实验,把四类故障注入到同一份计划上,量化副作用次数。
三个平面:职责、故障与可恢复性
三个平面是一组职责划分,不是三个进程。它们可以部署在同一个进程里,也可以分布在不同的服务上;关键是职责边界清晰。
| 平面 | 回答的问题 | 典型动作 | 是否有副作用 | 故障时的可恢复性 |
|---|---|---|---|---|
| 控制面 | 下一步做什么 | 选动作、调度、重试策略、终止判断 | 否 | 高:决策可以重放 |
| 执行面 | 真正执行动作 | 调用工具、调用模型、写数据库 | 是 | 中:取决于副作用是否幂等 |
| 数据面 | 发生过什么 | 记录状态、记录动作结果、保存日志 | 追加写 | 依赖:事实丢失则无法恢复 |
控制面没有副作用,这是它最大的优点。 控制面做的决定(选哪个动作、要不要重试、是否终止)本身不改变外部世界。如果控制面崩溃了,只要数据面还记录着事实,它可以从头重放决策而不产生新的副作用。这正是"持久化执行"能成立的根源:工作流代码可重放,是因为它不碰副作用。
执行面是唯一产生副作用的地方。 工具调用、模型调用、数据库写入,都在这里发生。执行面的故障分两种:副作用没发生,和副作用已发生但结果没记录。前者重试安全,后者重试会制造第二次副作用——这是整个运行时架构里最难处理的故障类型。
数据面记录事实,是另外两个平面的锚点。 没有数据面,控制面不知道走到哪了,执行面不知道什么已经做过。数据面本身也会丢,但那是另一种故障:事实丢失意味着已经发生的副作用无法被追溯,只能对账或人工核对。
为什么必须拆开:故障半径
把三个平面拆开,不是为了整洁,而是为了控制故障半径。
假设控制面和执行面不分家:决定和执行写在同一个函数里。那么"决定错了"和"执行坏了"就会混在一起,重试时你不知道重试的是决策还是副作用。更糟的是,一旦决定本身依赖执行结果(先查再改),两个平面互相纠缠,你既无法重放决策,也无法安全重试执行。
一个反例最能说明问题。早期 Agent 实现里,“调用工具并记录结果"常常写成一个函数:先调用,再写日志,最后返回。如果日志写在调用之后,崩溃恰好发生在两者之间,你就得到"工具已经执行、日志没有记录"的状态。这个状态让所有下游决策都失效,因为控制面无法区分"没执行过"和"执行过但没记录”。三平面分离的实质,就是把"记录事实"提升为一等职责,而不是调用代码里的附带动作。
分拆后的收益可以概括成一句话:控制面可以重放,执行面必须幂等,数据面必须可靠。 三者各自有一套独立的加固手段,而不是一个笼统的"加重试"。
恢复策略取决于故障落在哪个平面
给定同一份计划(动作 A、B、C),故障发生在不同平面时,正确的恢复动作完全不同:
| 故障位置 | 发生了什么 | 恢复动作 | 副作用变化 |
|---|---|---|---|
| 控制面 | 决策游标丢失,事实完好 | 从头重放计划,数据面兜底 | 不增加 |
| 执行面(副作用前) | 动作没执行 | 重试该动作 | 增加一次 |
| 执行面(副作用后、记录前) | 副作用已发生,结果没记录 | 重试需外部幂等键去重 | 可能重复 |
| 数据面 | 事实全部丢失 | 无法追溯,只能对账 | 不可控 |
这份表是运行时架构评审的起点:先问"故障可能落在哪个平面",再决定用哪套机制。把"加重试"挂在嘴边,但说不清要防的是哪个平面的故障,等于没有策略。
最小实验:四类故障注入
下面的实验把三个平面写成可运行的类,用同一份计划 A→B→C 跑四类场景。它不依赖数据库、消息队列或工作流引擎,全部状态在内存里;生产系统把数据面换成持久化实现,但语义不变。
# file: agp_lab/control_planes.py | write
# tier: 3
# verify: python3 -m unittest tests.test_control_planes
"""控制面、执行面、数据面:职责分离与故障注入。
Agent 的一次运行可以看作三个平面的协作:
- 控制面:从计划里选出下一个动作(决策,本身无副作用);
- 执行面:真正执行工具调用(副作用在这里发生);
- 数据面:保存已发生的事实(动作结果)。
可恢复性与故障落在哪个平面强相关。本模块用同一份计划
跑四类场景(无故障 / 控制面故障 / 执行面"副作用已发生
未记录" / 数据面丢失),统计副作用次数,说明:
控制面故障可以靠数据面幂等兜底,执行面崩溃需要幂等键,
数据面丢失则无法自动恢复。
"""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any
@dataclass(frozen=True)
class Action:
name: str
@dataclass
class DataPlane:
"""数据面:只追加地记录已发生的事实(动作结果)。"""
results: dict[str, str] = field(default_factory=dict)
def record(self, name: str, result: str) -> None:
self.results[name] = result
def has(self, name: str) -> bool:
return name in self.results
def get(self, name: str) -> str:
return self.results[name]
def wipe(self) -> None:
self.results.clear()
class ControlPlane:
"""控制面:从计划中依次选出动作;游标丢失可从头重放。"""
def __init__(self, plan: list[str]) -> None:
self.plan = list(plan)
self.index = 0
def next_action(self) -> Action | None:
if self.index >= len(self.plan):
return None
action = Action(self.plan[self.index])
self.index += 1
return action
def reset(self) -> None:
"""模拟控制面故障:游标丢失,计划可从头重放。"""
self.index = 0
class ExecutionPlane:
"""执行面:真正产生副作用;幂等去重由数据面兜底。"""
def __init__(self, data: DataPlane) -> None:
self.data = data
self.side_effects = 0
def execute(self, action: Action, crash_after_side_effect: bool = False) -> str | None:
if self.data.has(action.name):
return self.data.get(action.name)
# 真正的副作用:只在这里 +1。
self.side_effects += 1
result = f"done:{action.name}"
if crash_after_side_effect:
# 模拟崩溃:副作用已经发生,但结果还没写进数据面。
return None
self.data.record(action.name, result)
return result
PLAN = ["A", "B", "C"]
def simulate(fault: str) -> dict[str, Any]:
"""按故障类型运行 PLAN,返回副作用次数与已记录事实。
fault 取值:
- "none" :正常运行;
- "control" :第一次完成后控制面游标丢失,重放由数据面兜底;
- "exec-side" :B 的副作用已发生但结果未记录,恢复时无幂等键;
- "data" :崩溃后数据面事实全部丢失。
"""
data = DataPlane()
exec_plane = ExecutionPlane(data)
def replay(names: list[str]) -> None:
for name in names:
exec_plane.execute(Action(name))
if fault == "none":
replay(PLAN)
return {"side_effects": exec_plane.side_effects, "recorded": sorted(data.results)}
if fault == "control":
replay(PLAN)
# 控制面故障:游标归零,重放计划;结果全部命中数据面缓存。
replay(PLAN)
return {
"side_effects": exec_plane.side_effects,
"recorded": sorted(data.results),
"note": "重放命中缓存,副作用不增加",
}
if fault == "exec-side":
# 崩溃点:A 已确认,B 副作用已发生但结果未记录,C 未执行。
exec_plane.execute(Action("A"))
exec_plane.execute(Action("B"), crash_after_side_effect=True)
# 恢复:重放 B、C。无外部幂等键时,B 的副作用会重复。
replay(["B", "C"])
return {
"side_effects": exec_plane.side_effects,
"recorded": sorted(data.results),
"note": "B 副作用重复,需要外部幂等键",
}
if fault == "data":
replay(PLAN)
data.wipe()
replay(PLAN)
return {
"side_effects": exec_plane.side_effects,
"recorded": sorted(data.results),
"note": "事实全部丢失,副作用全部重复",
}
raise ValueError(f"未知故障类型: {fault}")
def demo() -> dict[str, Any]:
"""打印四类故障下的副作用次数对比。"""
rows = {}
for fault in ["none", "control", "exec-side", "data"]:
rows[fault] = simulate(fault)
return rows
if __name__ == "__main__":
print(f"{'fault':<12}{'side_effects':<14}{'recorded':<20}note")
for fault, result in demo().items():
print(
f"{fault:<12}{result['side_effects']:<14}"
f"{','.join(result['recorded']):<20}{result.get('note', '-')}"
)
运行:
cd private/labs/agp-lab
python3 -m agp_lab.control_planes
输出:
fault side_effects recorded note
none 3 A,B,C -
control 3 A,B,C 重放命中缓存,副作用不增加
exec-side 4 A,B,C B 副作用重复,需要外部幂等键
data 6 A,B,C 事实全部丢失,副作用全部重复
四行输出对应四个场景:
- none:A、B、C 各执行一次,副作用 3 次。
- control:控制面游标丢失,从头重放计划。因为数据面记录着全部结果,重放全部命中缓存,副作用仍是 3 次。这就是"控制面可重放"的含义:重放决策不重复副作用。
- exec-side:B 的副作用已经发生,但结果没有写入数据面。恢复时重放 B、C,B 的副作用执行了第二次——因为这里没有外部幂等键。副作用从 3 变 4。
- data:数据面事实全部丢失。恢复时所有动作重新执行,副作用从 3 变 6。
实验刻意把"没有外部幂等键"和"数据面丢失"单独列出来,因为它们正是最容易在生产里被忽略的两种情况。exec-side 场景尤其值得记住:副作用已发生但结果未记录,是这个模型里唯一让重试失效的故障。 它的解法不在本节的实验里,而在执行面的幂等键设计(见 2.2 与 5.2)。
架构判据
三平面分离是否合格,用六条判据检查:
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 职责边界 | 决策、执行、记录各自有明确的入口 | 一个函数里既调用又写日志 |
| 副作用位置 | 只有执行面产生副作用 | 控制面代码里直接调用工具 |
| 事实记录 | 动作结果先落数据面再确认 | 先返回成功,再异步写日志 |
| 决策可重放 | 控制面崩溃后可从头重放 | 决策依赖未记录的执行结果 |
| 幂等键 | 执行面对副作用去重 | 重试就重复副作用 |
| 数据面可靠 | 事实持久化,可追溯 | 事实在内存里,重启即丢 |
判据不需要一次全做到。W1 的只读检索可以只要职责边界与事实记录;W3 的不可逆操作至少要有副作用位置、事实记录与幂等键。判据的作用是把"运行时做到什么程度"变成有依据的决定。
小结
- 控制面决定做什么,没有副作用,故障可重放;执行面产生副作用,故障需要幂等;数据面记录事实,故障不可自动恢复。
- 三平面分离的本质是让"记录事实"成为一等职责,而不是调用代码里的附带动作。
- 恢复策略取决于故障落在哪个平面:控制面重放、执行面幂等、数据面对账。
- 最难处理的故障是"副作用已发生但结果未记录",重试会制造第二次副作用。
阅读导航:上一节:目录与学习路径 · 下一节:1.2 引擎、服务、Worker、存储的职责 。
常见错误与边界
- 把三平面当三个进程。 三平面是职责划分,不是部署要求。单进程里也可以职责清晰,微服务里也可以混成一团。
- 在执行面之外产生副作用。 控制面里直接调用工具,会让决策不再可重放,这是最隐蔽的架构违规。
- 先确认成功,再记录结果。 崩溃会留下"外部已成功、内部不知道"的状态;正确顺序是结果先落数据面再确认。
- 把重试当恢复。 重试只能处理"副作用没发生"的故障;副作用已发生未记录时,重试会重复,需要幂等键。
- 数据面不是日志。 日志是给人看的,数据面是给控制面和执行面读的;两者都可能丢,但丢了之后的恢复策略完全不同。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。