以下角色、权限表、可用性数字与消息均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。把"审计"这类职责绑死在某个角色上,是讲解用的简化;真实系统按合规要求分配,但"越权要能被检出"这一条不变。
1.1 把一次运行拆成控制面、执行面、数据面。这一节把三个平面落成四个具体的角色:引擎、服务、Worker、存储。三平面回答"职责属于哪一类",四角色回答"谁具体负责什么"——它们是同一件事的两个抽象层次,本节的职责划分是 1.1 的部署视角。
四角色最常见的失败,不是某一个角色坏了,而是角色越权:引擎偷偷调工具、Worker 自己写审计日志、存储负责发通知。越权通常不会立刻崩,但会让故障半径、权限模型和可追溯性一起失效。这一节讲清楚每个角色该做什么、不该做什么,以及越权为什么必须被自动检出。
四个角色的权限表
四个角色可以部署在一个进程里,也可以分布在服务上。划分的依据是职责与权限,不是进程数。
| 角色 | 职责 | 典型动作 | 触达的外界 |
|---|---|---|---|
| 引擎 | 编排 | decide_next、build_plan、dispatch | 内部状态,无外部副作用 |
| 服务 | 承接 API | validate、authenticate、enqueue、audit | 用户请求与认证 |
| Worker | 执行 | execute_tool、call_model、write_artifact | 工具、模型、文件系统 |
| 存储 | 保存事实 | persist、load、query、delete | 持久化介质 |
引擎没有外部副作用。 引擎负责"下一步做什么":根据状态与结果决定下一个动作,把任务分派出去。引擎触达的是内部状态和调度决策,不直接调用工具、不直接写库、不发通知。这不是纪律问题,而是能力问题:引擎一旦能对外,重放决策就会重复副作用,1.1 建立的"控制面可重放"就破了。
服务是用户与系统之间的门。 服务承接 API 请求,做校验与认证,把合法请求入队,并记录审计。审计日志属于服务,因为"谁在什么权限下请求了什么"是面向用户的合规事实,应该由面对用户的那一层负责。
Worker 是唯一执行副作用的地方。 工具调用、模型调用、写产物,都在 Worker。Worker 对应 1.1 的执行面,是四角色里权限最危险的一个。
存储保存事实,不产生决策。 存储负责持久化、读取、查询、删除。存储不应该知道"这个状态为什么出现",那是引擎的事;也不该决定"这个请求是否合法",那是服务的事。
越权为什么必须被检出
角色越权很难用肉眼发现,因为代码在跑,结果也对。Worker 顺手写了一条审计日志,看起来没坏,但三条不变量同时被破坏:
- 故障半径失真。 Worker 坏了的时候,审计日志也丢了,但没有人知道。诊断时你以为是 Worker 故障,其实审计链路也在同一个故障半径里。
- 权限模型失效。 如果 Worker 能写审计,那"审计只能由授权角色写入"这条安全前提就不成立,合规审查会质疑所有日志的完整性。
- 重放语义被污染。 Worker 若直接对外发通知(本该由引擎编排、由服务记录),重放一次就多通知一次。1.1 里"执行面幂等"的前提是副作用都在 Worker 且被记录。
所以越权不是风格问题,是必须被机制自动检出并拦住的问题。下面的实验就演示这种检出。
最小实验:授权违规、链路可靠性与故障半径
实验把四角色做成权限矩阵,跑三件事:检出越权事件、计算串联链路可用性、对比合规与越权路径的恢复率。
# file: agp_lab/runtime_roles.py | write
# tier: 3
# verify: python3 -m unittest tests.test_runtime_roles
"""引擎、服务、Worker、存储四角色的职责与故障半径。
Agent 运行时把工作拆给四个角色:引擎编排,服务承接 API,
Worker 执行副作用,存储保存事实。职责分离的价值不在好看,
而在故障半径可控:每个角色只该承担自己权限内的动作。
本模块提供三件东西:
1. 授权矩阵:检查某个动作是否超出角色权限(职责违规);
2. 串联可靠性:给定各角色可用性,计算一条链路的整体成功率;
3. 反事实:Worker 绕过服务直接对外时,故障如何扩大。
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any
@dataclass(frozen=True)
class Role:
name: str
permissions: frozenset[str]
ROLES: dict[str, Role] = {
"engine": Role("engine", frozenset({"decide_next", "build_plan", "dispatch"})),
"service": Role(
"service", frozenset({"validate", "authenticate", "enqueue", "audit"})
),
"worker": Role("worker", frozenset({"execute_tool", "call_model", "write_artifact"})),
"store": Role("store", frozenset({"persist", "load", "query", "delete"})),
}
def is_authorized(role_name: str, action: str) -> bool:
return action in ROLES[role_name].permissions
def detect_violations(events: list[tuple[str, str]]) -> list[tuple[str, str]]:
"""events 为 [(角色, 动作)],返回超出角色权限的违规项。"""
return [(role, action) for (role, action) in events if not is_authorized(role, action)]
def chain_availability(availabilities: dict[str, float]) -> float:
"""串联链路:整体成功率 = 各角色可用性乘积。
engine → service → worker 是一条串联依赖,任何一环不可用,
整条链路就不可用。
"""
total = 1.0
for value in availabilities.values():
total *= value
return total
def recovery_rate(direct_failure: float, retries: int, logged: bool) -> float:
"""比较合规与违规路径下的恢复率。
logged=True:结果经 store 记录,可重试 retries 次,
成功率 = 1 - p^(retries+1);
logged=False:worker 直接对外,失败即丢,成功率 = 1 - p。
"""
if logged:
return 1.0 - direct_failure ** (retries + 1)
return 1.0 - direct_failure
def demo() -> dict[str, Any]:
"""打印授权违规、链路可靠性与故障半径对比。"""
events = [
("engine", "decide_next"),
("worker", "execute_tool"),
("worker", "audit"), # 违规:审计是 service 的职责
("engine", "execute_tool"), # 违规:执行是 worker 的职责
]
avail = {"engine": 0.99, "service": 0.98, "worker": 0.95}
return {
"violations": detect_violations(events),
"chain_avail": chain_availability(avail),
"compliant_rate": recovery_rate(0.2, 2, logged=True),
"coupled_rate": recovery_rate(0.2, 2, logged=False),
}
if __name__ == "__main__":
result = demo()
print("violations:", result["violations"])
print(f"chain_availability={result['chain_avail']:.4f}")
print(f"compliant(logged, retry=2) recovery={result['compliant_rate']:.4f}")
print(f"coupled(direct) recovery={result['coupled_rate']:.4f}")
运行:
cd private/labs/agp-lab
python3 -m agp_lab.runtime_roles
输出:
violations: [('worker', 'audit'), ('engine', 'execute_tool')]
chain_availability=0.9217
compliant(logged, retry=2) recovery=0.9920
coupled(direct) recovery=0.8000
三行输出对应三件事:
- violations:四个事件里检出了两项越权——
('worker', 'audit')(审计是服务的职责)和('engine', 'execute_tool')(执行是 Worker 的职责)。这两个都是 1.1 强调的典型越权:一个把合规职责下沉,一个把副作用上移。detect_violations把事件流与权限表逐条比对,越权项原样返回,让自动化门禁可以在构建或发布前拦下它们。 - chain_availability=0.9217:engine(0.99)、service(0.98)、worker(0.95)是一条串联依赖,整体成功率是三者乘积 0.99×0.98×0.95≈0.9217。串联链路的含义是:任何一环不可用,整条链路就不可用;整体可用性永远不高于最弱的一环。
- compliant vs coupled:这是 1.1 故障半径的量化。合规路径(Worker 结果经 store 记录,失败可重试 2 次)的恢复率是
1-0.2^3=0.992;越权路径(Worker 绕过服务直接对外,失败即丢)的恢复率只有1-0.2=0.800。多出来的 0.192 就是"被记录 + 可重试"带来的恢复力,越权直接把这一块扔掉了。
实验的结论可以浓缩成一句:越权不仅违反纪律,还实打实地把恢复率从 0.992 拉到 0.800。 这不是道德问题,是概率问题。
四角色在单进程里怎么落地
很多人看完权限表的第一反应是"那我是不是要拆四个服务"。不是。四角色是逻辑职责,不是部署拓扑。同一个进程里也能把四角色分清楚,关键是入口与数据流分开:
| 入口 | 归属角色 | 为什么 |
|---|---|---|
| 收到 HTTP 请求 | service | 校验、认证、审计都在服务层 |
| 决定下一个动作 | engine | 引擎只决策,无副作用 |
| 执行工具调用 | worker | 副作用只在 Worker |
| 读写持久化 | store | 存储只存取,无决策 |
单进程落地时最容易被打破的边界,是"引擎顺手调了工具"——因为引擎和 Worker 在同一个进程里,import 很方便。这一条要由代码结构与测试守住:引擎模块不 import 工具执行模块,用依赖不变量(见 1.3)自动检查,而不是靠人自律。
四个角色的职责表本身,就是事件流的审计依据。 生产里每个事件都带角色标签(谁发起的),运行时用授权矩阵(本节的 detect_violations)持续比对。这样"谁在什么时候越权做了什么"始终可查,而不是等到事故后翻日志。
什么时候拆进程
四角色默认单进程,但有三类信号出现时值得拆:
| 信号 | 拆谁 | 期望 |
|---|---|---|
| Worker 需要独立扩缩容 | 拆 Worker 成独立部署单元 | 工具并发可以单独调 |
| 存储流量压垮其余角色 | 拆 store | 持久化独立扛量 |
| 审计必须独立于业务故障 | 拆 service 的审计链路 | 业务挂了审计还在 |
拆进程的代价是链路可用性下降:1.2 实验里 engine→service→worker 串联,整体可用性是乘积。每多一个进程,就多一分串联衰减。 所以拆之前先问:当前最弱的瓶颈是什么,拆完能不能解;不能解就不拆。
引擎、服务、Worker、存储四角色的分配,不是"哪个进程多一件事"的问题,而是"每一件事都有明确的角色归属"。评审时最常见的提问是:“这个动作发生在哪个角色?“如果回答要犹豫,职责边界就有问题。
一个有用的自检技巧:把每次状态变化、每次对外动作、每次持久化读写分别标注角色,然后逐条问三句话——它该是这个角色做的吗?它是不是越权到了别的角色?如果删掉这个角色,系统还能工作吗?三句话问下来,边界是否清晰立刻显现。
角色边界在失败时的表现是判断划分是否正确的另一把尺子。 四角色各自崩溃,影响范围应该各不相同:引擎挂了,正在执行的会话中断;服务挂了,能接入新会话但存量会话受影响;Worker 挂了,只是它处理的那批任务失败、可被重调度;存储挂了,所有读写都停摆。如果两个角色崩溃的影响完全一样,它们多半不该是两个角色。
| 崩溃对象 | 影响范围 | 恢复动作 |
|---|---|---|
| 引擎 | 当前会话中断 | 会话重建或转交 |
| 服务 | 新会话接入不了 | 重启服务、流量摘除 |
| Worker | 该批任务失败 | 任务重调度(见 3.3) |
| 存储 | 全局读写停摆 | 存储冗余、故障转移 |
架构判据
四角色的职责划分是否合格,用五条判据检查:
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 引擎零副作用 | 引擎只决策、分派,不触达外部 | 引擎里出现工具调用或写库 |
| 服务承接 API | 校验、认证、审计都在服务层 | Worker 直接对外应答请求 |
| Worker 独享副作用 | 工具/模型/产物只在 Worker | 引擎或服务直接调工具 |
| 存储只存取 | 存储无决策、无校验逻辑 | 存储里写业务判断 |
| 越权可检出 | 事件流可被授权矩阵自动比对 | 越权只能靠 code review 发现 |
判据有一条不是可选项:越权可检出。 前四条是设计时的职责划分,第五条是运行时的机制保证。没有第五条,前四条迟早被悄悄侵蚀。
小结
- 三平面落成四角色:引擎编排、服务承接 API、Worker 执行副作用、存储保存事实。
- 每个角色有权限边界;越权会同时破坏故障半径、权限模型与重放语义。
- 串联链路可用性是各环节可用性的乘积,永远不高于最弱一环。
- 合规路径(结果被记录、可重试)的恢复率远高于越权路径(失败即丢),差异可被量化。
- 越权必须被授权矩阵自动检出,不能只靠人工 review。
阅读导航:上一节:1.1 控制面、执行面、数据面 · 下一节:1.3 依赖方向与架构不变量 。
常见错误与边界
- 把"不越权"当纪律而非机制。 靠人记住"引擎别调工具"注定失效;正确做法是让事件流能被授权矩阵自动比对,违规即拦。
- 审计日志谁都能写。 审计是服务层对用户的合规承诺;放开给 Worker 会让日志失去可信度。
- 把串联当并联。 engine、service、worker 是串联依赖,一处不可用整体不可用;优化时抓最弱一环(worker 的 0.95)收益最大。
- 以为"反正能重试”。 越权路径上 Worker 直接对外,失败即丢,根本没有重试机会;重试的前提是结果被 store 记录。
- 四角色不等于四进程。 职责划分是逻辑边界,可以全部在一个进程里;过早拆成微服务反而引入新的链路衰减。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。