系统边界图用上下文图帮助团队对齐微服务和 Agent 的职责边界一、深度引言与场景痛点微服务团队和 Agent 团队经常在一个问题上反复拉扯订单状态的变更通知是订单服务发还是消息 Agent 发用户意图识别错了是网关的问题还是 Agent 的问题配置项被 Agent 改错了是 Agent 不对还是配置服务少做了校验这类争论不是技术问题是职责边界问题。当系统里既有传统微服务又有 AI Agent 时职责边界如果不画清楚出 bug 时没人认领、改功能时互相踩脚、新人看不懂谁能调谁。传统的 API 文档描述了接口的输入输出但没说清楚这件事归谁管。上下文图Context Diagram就是为解决这个问题而生的。它不画代码逻辑不画数据库表结构只画系统的边界线哪些东西是你的系统、哪些是外部的、你的系统对外提供了什么能力、依赖了外部什么服务。一张图能让全团队对齐这片地归谁种。二、底层机制与原理深度剖析三层边界的划分有明确的规则。最外层是不归你管但你需要用的系统——外部 API、用户客户端、第三方数据源。你和它们的关系是单向依赖它们改接口你要跟着改。中间层是你的系统边界又分为两层微服务层和 Agent 编排层。微服务层负责确定性逻辑增删改查、状态机、业务规则Agent 层负责不确定性逻辑意图理解、自然语言生成、多步推理。核心规则是Agent 不做最终的业务写入微服务不做自然语言理解。内层是数据层包含关系数据库、缓存、向量数据库。Agent 和微服务都可以读数据层但写入权限有区别微服务可以写关系数据库和缓存Agent 只能写缓存和向量数据库。关系数据库的写入是账本操作需要有事务保障的业务逻辑来驱动Agent 不具备这个能力。三、生产级代码实现from __future__ import annotations from dataclasses import dataclass, field from enum import Enum class NodeType(Enum): EXTERNAL external GATEWAY gateway MICROSERVICE microservice AGENT agent DATA_STORE data_store dataclass class ContextNode: name: str node_type: NodeType description: str owner: str # 负责团队 sla: str # 可用性承诺 can_write: bool False # Agent 节点是否可以写入 dataclass class ContextEdge: from_node: str to_node: str protocol: str # HTTP/gRPC/Message Queue purpose: str # 调用目的 is_critical: bool False # 是否关键链路 class ContextDiagram: 以代码形式维护系统上下文图 def __init__(self, system_name: str My System): self._system_name system_name self._nodes: list[ContextNode] [] self._edges: list[ContextEdge] [] def add_node(self, node: ContextNode) - None: self._nodes.append(node) def add_edge(self, edge: ContextEdge) - None: self._edges.append(edge) def to_mermaid(self) - str: lines [flowchart TD] external_nodes [] system_nodes [] for node in self._nodes: safe_name node.name.replace( , _) style { NodeType.EXTERNAL: f{safe_name}[外部: {node.name}], NodeType.GATEWAY: f{safe_name}{{网关: {node.name}}}, NodeType.MICROSERVICE: f{safe_name}[服务: {node.name}], NodeType.AGENT: f{safe_name}((Agent: {node.name})), NodeType.DATA_STORE: f{safe_name}[(数据: {node.name})], }.get(node.node_type, f{safe_name}[{node.name}]) if node.node_type NodeType.EXTERNAL: external_nodes.append(style) else: system_nodes.append(style) lines.extend(system_nodes) lines.extend(external_nodes) for edge in self._edges: from_safe edge.from_node.replace( , _) to_safe edge.to_node.replace( , _) label f|{edge.protocol}: {edge.purpose}| color red if edge.is_critical else lines.append(f {from_safe} --{label if edge.purpose else }{to_safe}) return \n.join(lines) def check_agent_boundaries(self) - list[str]: 检查 Agent 是否越界访问了不该写的数据存储 violations [] agent_nodes {n.name for n in self._nodes if n.node_type NodeType.AGENT} data_writes { n.name for n in self._nodes if n.node_type NodeType.DATA_STORE and n.can_write } for edge in self._edges: if edge.from_node in agent_nodes and edge.to_node in data_writes: violations.append( fAgent {edge.from_node} 直接写入数据存储 {edge.to_node}。 f建议: Agent 应通过微服务完成写入操作。 ) return violations def export(self, filepath: str) - None: with open(filepath, w, encodingutf-8) as f: f.write(self.to_mermaid())ContextDiagram.to_mermaid生成的 Mermaid 图可以直接嵌入 README 或设计文档。不同类型的节点用不同的形状区分外部系统用矩形、微服务用方框、Agent 用圆角菱形、数据层用圆桶形。视觉区分让团队一眼就能看懂这是外部依赖还是这是我们的系统组件。check_agent_boundaries是一个强制规则检查器。它自动扫描所有边如果发现 Agent 直接写入了关系数据库就报警。这个检查可以集成到 CI 里每次提交系统上下文图时自动执行。如果有人把无效的边加了进去CI 直接报错。这种以代码维护架构图的方式比 Visio 或 Draw.io 优越的地方在于图可以版本控制可以自动检查可以生成报告。改了一个服务的依赖图自动更新不会存在文档和图对不上的问题。四、边界分析与架构权衡上下文图描述了谁依赖谁但它不描述为什么这样设计、有哪些替代方案被放弃、什么情况下可以打破规则。这些内容还需要用文字补充。上下文图是一个索引不是为了替代设计文档而是给设计文档提供一个可视化的入口。另外上下文图适合团队对齐但不适合运维排障。运维排障需要的是部署拓扑图和调用链追踪而上下文图不包含 IP、端口、实例数量这些运行时信息。不要把上下文图当运维图用。还有一个常见误区画图时把所有的调用关系都画出来。一个系统有 50 个服务两两之间有调用关系全画出来就是一团蜘蛛网。上下文图应该只画关键路径——高频调用的、有 SLA 要求的、跨团队调用的。低频日志同步、后台批处理这种可以省略留给后续的细粒度流程图处理。五、总结系统上下文图的核心价值是帮团队对齐职责边界什么归微服务管、什么归 Agent 管、什么归外部系统管。实现方式是用代码描述节点和边自动生成 Mermaid 图CI 里做边界规则检查。落地建议从 5 个最核心的服务和 Agent 开始画不要贪大求全用check_agent_boundaries做自动规则检查把生成的 Mermaid 图嵌入 README让它成为每个新成员的入门第一份文档。