《AI Agent 技术原理与架构·运行时、协议与系统架构》1.3 依赖方向与架构不变量

上一节的四角色不是平等的,它们之间有依赖方向:接入层依赖领域层,领域层依赖基础设施层。反向依赖让故障与变更沿错误方向传播,循环依赖则让先构建谁都无法回答。实验用依赖图检查器同时检反向边与环,演示一条反向边如何直接制造出闭环,并给出依赖不变量应该怎么检查。

以下组件分层、依赖图与边均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。分层号 0/1/2 是讲解用的一种分层法,真实系统有自己的分层语义;但"反向依赖会被检出、循环依赖会被检出"这一条不变。

1.2 给了四个角色,但四个角色不是平等协作的:它们之间有明确的依赖方向。方向是架构里最容易被忽视的不变量。功能可以慢慢加,依赖方向一旦错了,后续每一个变更都在错误的地基上叠加。

这一节把依赖方向讲成三条规则:分层禁止反向依赖、禁止循环、可自动检查。实验用一个依赖图检查器,在三个"运行时系统"依赖图上演示违规边与环的检出,并回答一个反直觉的问题:为什么一条小小的反向边,往往直接就制造出一个环。

分层、反向依赖与循环

先定分层。一个 Agent 运行时大致分三层:

层号层组件
0接入层api
1领域层orchestrator、worker
2基础设施层store、model_gateway

不变量一:组件只能依赖同层或更低层。 api(层 0)可以依赖 orchestrator(层 1);orchestrator(层 1)可以依赖 store(层 2);worker(层 1)可以依赖 model_gateway(层 2)。反之不行:store(层 2)去依赖 api(层 0)就是反向边。

不变量二:依赖图无环。 有环意味着"先构建谁"无法回答,故障会绕回来传播,测试和发布顺序都变得不可推导。

这两条不变量为什么要自动检查?因为代码评审里它们最容易被忽略。反向边往往藏在一句"顺手 import"里,环往往藏在三次间接引用之后。人工 review 抓不全,必须让构建或 CI 在每次变更后自动跑检查器。

为什么反向依赖往往直接成环

这里有一个值得展开的观察。反向边不是"可能造成环",而是往往直接就成环。看这个例子:

api → orchestrator → store 是一条合法链(接入层依赖领域层,领域层依赖基础设施层)。现在加一条反向边 store → api。从 store 出发,可以走 store → api → orchestrator → store,绕一圈回到自己——一个环,包含 api、orchestrator、store 三个节点。

也就是说,在一条贯通低层的依赖链上,任何一条反向边都会与既有链路闭合。这不是巧合,而是方向律:合法方向从高层指向低层,反向边从低层指回高层,而链路上本来就有一条高层到低层的路径,两条拼在一起自然形成回路。

这个观察的工程含义是:不要以为"只加一条反向边没关系,没有环"。在结构上,加了反向边,环往往就跟着来了。下面的实验会证明这一点。

最小实验:依赖图检查器

实验提供一个依赖图检查器:backward_edges 检反向边,find_cycles 用强连通分量(Tarjan)找环,然后在三个图上跑。

# file: agp_lab/dependency_invariants.py | write
# tier: 3
# verify: python3 -m unittest tests.test_dependency_invariants
"""依赖方向与架构不变量:分层、反向依赖与循环。

依赖方向是一条架构不变量:组件只能依赖同层或更低层。
反向依赖(低层依赖高层)会让故障与变更沿错误方向传播,
循环依赖则让"先构建谁"无法回答。

本模块提供一个依赖图检查器:检测反向边与循环,并用一个
"运行时系统"依赖图演示违规修复前后的差别。
"""
from __future__ import annotations

from collections import defaultdict
from dataclasses import dataclass
from typing import Any


@dataclass(frozen=True)
class Component:
    name: str
    layer: int  # 0=接入层, 1=领域层, 2=基础设施层


COMPONENTS: dict[str, Component] = {
    "api": Component("api", 0),
    "orchestrator": Component("orchestrator", 1),
    "worker": Component("worker", 1),
    "store": Component("store", 2),
    "model_gateway": Component("model_gateway", 2),
}


def backward_edges(
    edges: list[tuple[str, str]], components: dict[str, Component] | None = None
) -> list[tuple[str, str]]:
    """返回依赖高层的反向边。src 依赖 dst,若 src 层号 > dst 层号则违规。"""
    comps = components or COMPONENTS
    return [
        (src, dst)
        for (src, dst) in edges
        if comps[src].layer > comps[dst].layer
    ]


def find_cycles(edges: list[tuple[str, str]]) -> set[str]:
    """返回处于至少一个环中的节点(基于强连通分量,SCC 大小>1 或自环)。

    Kahn 拓扑排序会把环上游的悬挂链一并留下,不够精确;这里用
    Tarjan 求 SCC,只有真正闭合的强连通分量才算环。
    """
    adjacency: dict[str, list[str]] = defaultdict(list)
    nodes: set[str] = set()
    for src, dst in edges:
        adjacency[src].append(dst)
        nodes.add(src)
        nodes.add(dst)

    index: dict[str, int] = {}
    lowlink: dict[str, int] = {}
    on_stack: set[str] = set()
    stack: list[str] = []
    counter = 0
    cyclic: set[str] = set()

    def strongconnect(node: str) -> None:
        nonlocal counter
        index[node] = lowlink[node] = counter
        counter += 1
        stack.append(node)
        on_stack.add(node)
        for neighbor in adjacency[node]:
            if neighbor not in index:
                strongconnect(neighbor)
                lowlink[node] = min(lowlink[node], lowlink[neighbor])
            elif neighbor in on_stack:
                lowlink[node] = min(lowlink[node], index[neighbor])
        if lowlink[node] == index[node]:
            scc: list[str] = []
            while True:
                member = stack.pop()
                on_stack.discard(member)
                scc.append(member)
                if member == node:
                    break
            if len(scc) > 1 or node in adjacency[node]:
                cyclic.update(scc)

    for node in nodes:
        if node not in index:
            strongconnect(node)
    return cyclic


CLEAN: list[tuple[str, str]] = [
    ("api", "orchestrator"),
    ("orchestrator", "worker"),
    ("orchestrator", "store"),
    ("worker", "model_gateway"),
]
# 反向依赖往往直接成环:store→api 与 api→orchestrator→store 闭合。
VIOLATING: list[tuple[str, str]] = CLEAN + [
    ("store", "api"),  # 反向:基础设施依赖接入层,随即制造环
]
CYCLIC: list[tuple[str, str]] = CLEAN + [
    ("worker", "orchestrator"),  # 与 orchestrator → worker 构成环
]


def demo() -> dict[str, Any]:
    """打印三种依赖图的违规边与环。"""
    return {
        "clean_backward": backward_edges(CLEAN),
        "clean_cycles": sorted(find_cycles(CLEAN)),
        "violating_backward": backward_edges(VIOLATING),
        "violating_cycles": sorted(find_cycles(VIOLATING)),
        "cyclic_cycles": sorted(find_cycles(CYCLIC)),
    }


if __name__ == "__main__":
    for name, result in demo().items():
        print(f"{name}: {result}")

运行:

cd private/labs/agp-lab
python3 -m agp_lab.dependency_invariants

输出:

clean_backward: []
clean_cycles: []
violating_backward: [('store', 'api')]
violating_cycles: ['api', 'orchestrator', 'store']
cyclic_cycles: ['orchestrator', 'worker']

三行输出对应三个图:

  1. clean:合法依赖图 api→orchestrator→worker/store→model_gateway,反向边为空,环为空。这是目标状态。
  2. violating:在 clean 基础上只加一条 store → api 反向边。backward_edges 立刻检出它;同时 find_cycles 检出 ['api', 'orchestrator', 'store']——正如上一节预言,一条反向边与既有链路直接闭合成了一个环。
  3. cyclic:另一处违规 worker → orchestrator,与 orchestrator → worker 构成 ['orchestrator', 'worker'] 这个环。它不涉及接入层,但同样是循环依赖,同样要被拦下。

两个值得注意的实现细节,也是教学点:

  • find_cycles 不用 Kahn 拓扑排序,而用 Tarjan 求强连通分量。Kahn 会把环上游的悬挂链(比如 worker 挂着却因为别的边进出不平衡而没被删掉)一并留下,不够精确;强连通分量只返回真正闭合的节点集合。教学上这一点解释了"环的检测要用对算法"。
  • violating_cycles 恰好等于 ['api', 'orchestrator', 'store'],也就是 store→api 反向边参与的整个闭合链。环不是"某些坏边",而是"一组节点彼此可达"。

依赖不变量不是一次建好就永久有效。代码每变化一次,依赖图就可能漂移一次:新组件加了反向 import,重构改了分层,工具函数提升到了不该在的层。不变量要随每次变更重新验证,这正是为什么检查器要挂在 CI 而不是挂在手册里。

把检查器作为门禁也有成本:误报会消耗团队耐心,全量重算会拖慢提交。务实的做法是分层检查——变更涉及的子图先查,发布前再做全量;分层检查保速度,全量检查保完整,两件事分开跑。

依赖不变量还有一个部署层面的用法:分层部署的边界就是依赖的边界。 控制平面能独立发布,是因为它不依赖执行平面的内部实现;执行平面能弹性扩容,是因为它不反向依赖控制平面的进程。反过来,如果哪一层被迫联动发布,说明它悄悄建立了不该有的依赖——不变量检查要把"能不能独立部署"也算作约束。

架构判据

依赖不变量是否守住,用五条判据检查:

判据合格的样子不合格的样子
分层一致组件分层号稳定,不随功能漂移同一组件横跨多层语义
无反向边底层不 import 高层基础设施层里出现接入层引用
无环依赖图强连通分量全为单点检出任何长度 >1 的环
自动检查每次变更后自动跑检查器依赖问题靠人工评审把关
修复闭环检出即修,不留豁免违规长期挂着,检查器名存实亡

判据不是一次性达标。第一轮只要能"检出"就已经比人工强;但要警惕第五条:检查器一旦允许豁免,就退化成形式主义。 违规要么修,要么给出有理由的豁免并写进文档,不能静默吞掉。

小结

  • 依赖方向是架构不变量:组件只能依赖同层或更低层,且依赖图无环。
  • 在贯通低层的依赖链上,一条反向边往往直接与既有链路闭合成一个环。
  • 环要用强连通分量(Tarjan)而不是 Kahn 拓扑排序检测,后者会留下环上游的悬挂链。
  • 依赖检查必须自动化,不能靠人工 review;检出后要么修要么显式豁免。

阅读导航:上一节:1.2 引擎、服务、Worker、存储的职责 · 下一节:2.1 状态机:状态、转移、守卫 。

常见错误与边界

  1. 以为"一条反向边没关系"。 在既有链路上加反向边,环往往跟着就来;violating 图就是现成证据。
  2. 把"能编译"当"无环"。 Python 的 import 天然允许环,能编译不代表依赖健康;必须显式跑检查器。
  3. 用拓扑排序找环。 Kahn 会把环上游悬挂链一并留下,误报和漏报都有;强连通分量才是精确口径。
  4. 给检查器开豁免却不记账。 豁免必须显式、有理由、可追溯;静默豁免等于没有检查器。
  5. 把分层号当真理。 0/1/2 只是讲解用的一种分层;真实系统按自己的语义分层,但"反向依赖要被检出"不变。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图