UML 新用途：让 AI 理解你生成的代码

目录 [−]

1. 14.1 UML 简史：从三剑客到 OMG 标准
2. 14.2 结构性图形（Structure Diagrams）：系统长什么样
   1. 14.2.1 类图（Class Diagram）
   2. 14.2.2 对象图（Object Diagram）
   3. 14.2.3 组件图（Component Diagram）
   4. 14.2.4 部署图（Deployment Diagram）
   5. 14.2.5 包图（Package Diagram）
   6. 14.2.6 复合结构图（Composite Structure Diagram）
   7. 14.2.7 剖面图（Profile Diagram）
3. 14.3 行为性图形（Behavior Diagrams）：系统怎么运行
   1. 14.3.1 用例图（Use Case Diagram）
   2. 14.3.2 活动图（Activity Diagram）
   3. 14.3.3 状态机图（State Machine Diagram）
   4. 14.3.4 序列图（Sequence Diagram）
   5. 14.3.5 通信图（Communication Diagram）
   6. 14.3.6 定时图（Timing Diagram）
   7. 14.3.7 交互概览图（Interaction Overview Diagram）
4. 14.4 超越 UML：三种实用的非 UML 图
   1. 14.4.1 系统架构图（Architecture Diagram）
   2. 14.4.2 流程图（Flowchart）
   3. 14.4.3 泳道图（Swimlane Diagram）
5. 14.5 UML 在 AI 时代的三个用途
6. 14.6 insight-diagram：一键生成全套 UML 图的 Skill
   1. 14.6.1 核心理念：代码分析 → 图表选择 → 逐个生成
   2. 14.6.2 图表生成顺序：从宏观到微观
   3. 14.6.3 关键设计决策
   4. 14.6.4 与 Understand-Anything 的配合
   5. 14.6.5 在 agent-wrapper 上实战
      1. agent-wrapper 系统架构图（Architecture Diagram）
      2. agent-wrapper 类图（Class Diagram）
      3. agent-wrapper 对象图（Object Diagram）
      4. agent-wrapper 组件图（Component Diagram）
      5. agent-wrapper 部署图（Deployment Diagram）
      6. agent-wrapper 包图（Package Diagram）
      7. agent-wrapper 复合结构图（Composite Structure Diagram）
      8. agent-wrapper 剖面图（Profile Diagram）
      9. agent-wrapper 流程图（Flowchart）
      10. agent-wrapper 用例图（Use Case Diagram）
      11. agent-wrapper 活动图（Activity Diagram）
      12. agent-wrapper 状态机图（State Machine Diagram）
      13. agent-wrapper 序列图（Sequence Diagram）
      14. agent-wrapper 通信图（Communication Diagram）
      15. agent-wrapper 定时图（Timing Diagram）
      16. agent-wrapper 交互概览图（Interaction Overview Diagram）
      17. agent-wrapper 泳道图（Swimlane Diagram）
7. 14.7 本章小结

「A picture is worth a thousand words. A diagram is worth ten thousand lines of code.」
一图胜千言。一张图胜万行代码。

第 13 章解决了一个问题：AI 写代码容易，读代码难。Understand-Anything 用知识图谱让 AI 理解现有代码。

反过来——代码写完了，作为人类你怎么理解它？毕竟，线上出了故障你还等着你背锅呢。

我前一段看到一句箴言："𝐲𝐨𝐮 𝐜𝐚𝐧 𝐨𝐮𝐭𝐬𝐨𝐮𝐫𝐜𝐞 𝐲𝐨𝐮𝐫 𝐭𝐡𝐢𝐧𝐤𝐢𝐧𝐠, 𝐛𝐮𝐭 𝐲𝐨𝐮 𝐜𝐚𝐧𝐧𝐨𝐭 𝐨𝐮𝐭𝐬𝐨𝐮𝐫𝐜𝐞 𝐲𝐨𝐮𝐫 𝐮𝐧𝐝𝐞𝐫𝐬𝐭𝐚𝐧𝐝𝐢𝐧𝐠"， 翻译过来就是"你可以外包你的思考(给AI),但是你不能外包你的理解"。 这句话被 Andrej Karpathy 多次引用，以至于大家认为是他说的，其实是kache说的：

这句话非常有哲理。Dex Horthy 在 2025 AI Engineer 大会上独立提出了："Don't outsource the thinking" / "AI cannot replace thinking, it can only amplify the thinking you have done."，但是今年你看， AI已经外包了我们的思考，你只需说出的你需求，智能体就能帮助你生生成你要的程序，但是 AI 没有办法帮我们理解啊。

我最近就遇到了这样的困惑：我通过goal workflow很快的实现了一个大模型训推任务智能诊断系统，全是AI帮我生成的，但是在联调的前一个星期，我心虚了。

因为我知道，联调和上线的时候，必然有一些问题，比如当时的设计有些模糊的地方，设计上有gap, 实现上也难免有bug。如果我对生成的代码不熟悉，联调的时候出故障我都不知道啥原因咋修复，可能当时还得重新捋代码才能慢慢找根因，太影响联调的同学了。未来上线以后出现问题，想快速修复就更不可能了。

所以我专门花了两天时间，建了几个卡片，就为了学习代码理解代码。

那我是通过什么方式去理解AI生成的代码的呢？

答案藏在一个用了二十多年的老工具里：UML。区别只有一点：以前的 UML 是人画给团队的，现在是 AI 画给你的。十四种图，从类结构到部署拓扑，从序列交互到状态变迁。AI 生成代码，AI 再画图解释代码——你读图就够了。

为此，我专门创建了一个Skill，用来生成UML的十四种代码和架构图、流程图以及泳道图。此skill的介绍：https://goal.rpcx.io/index_cn.html#step-diagram， 也集成到了goal workflow套件中了。

本章分两部分：第一部分过一遍 UML 十四种正式图形，外加三种 UML 规范没有但实际很常用的图。第二部分介绍 insight-diagram——一个在 goal.rpcx.io 上发布的 Skill，给任意代码库自动生成全套 UML 图、架构图和流程图。

14.1 UML 简史：从三剑客到 OMG 标准

1994 年，Grady Booch 和 Jim Rumbaugh 在 Rational Software 相遇。Booch 有他的 Booch Method，Rumbaugh 有他的 OMT（Object Modeling Technique）。两种方法符号体系不同，画出来的图互不认识。

1995 年，Ivar Jacobson 加入，带来他的 OOSE（Object-Oriented Software Engineering）方法。三人被称为「三剑客」（Three Amigos），目标：统一面向对象建模的符号体系，让所有软件工程师用同一套语言画图。

1997 年，OMG（Object Management Group）采纳 UML 1.0。2005 年，UML 2.0 图形种类从 9 种扩展到 13 种。最新版本 UML 2.5.1（2017 年）定义了 14 种图，分为两大类：

• 结构性图形（Structure Diagrams）：描述系统的静态结构——有哪些组件、怎么组织的。
• 行为性图形（Behavior Diagrams）：描述系统的动态行为——怎么运行、怎么交互。

AI 时代之前，UML 的命运比较尴尬。敏捷宣言之后，很多人觉得「重文档轻代码」不靠谱，UML 跟着被冷落了。但有一个事实没变：代码由 AI 大量生成之后，人类比以往更需要可视化理解工具。UML 重新有了用武之地——角色从「先画图再写代码」的前置仪式，变成了「AI 写代码，你读图」的后置理解工具。

14.2 结构性图形（Structure Diagrams）：系统长什么样

结构性图形回答「系统由什么组成」——类、对象、组件、包、部署节点。它们是系统的静态 X 光片。

14.2.1 类图（Class Diagram）

最常用的 UML 图。展示系统中的类、接口、协作以及它们之间的关系。

画什么：

• 类名、属性、方法——每个类一个矩形框，分成三格
• 关系类型：泛化（继承，空心三角箭头）、实现（虚线空心三角）、关联（实线）、聚合（空心菱形，整体-部分弱关系）、组合（实心菱形，整体-部分强关系，同生命周期）、依赖（虚线箭头）

什么时候用： 看项目的领域模型。agent-wrapper 项目的 Agent、Task、Tool、Message 等核心类型及其继承和组合关系。

AI 时代的价值： AI 生成 50 个类之后，类图让你一眼看清谁继承了谁、谁组合了谁——不用在 50 个文件之间反复横跳。

14.2.2 对象图（Object Diagram）

类图的运行时快照。展示特定时刻的对象实例及其属性值和链接关系。

画什么：

• 对象名:类名（加下划线标注）、属性的具体值、实例间的链接
• 比如 agent1: Agent { name="code-generator", model="claude-4" } 连接到 task42: Task { status="running" }

什么时候用： 调试时的内存快照。复杂对象图在某个时刻的状态——帮助看清递归结构、循环引用、单例模式的具体实例分布。

14.2.3 组件图（Component Diagram）

比类图高一层——展示软件架构中可替换的模块化组件及其接口。

画什么：

• 组件（矩形，带 <<component>> 标识）、提供的接口（棒棒糖符号）、需要的接口（插座符号）
• 组件间通过接口的依赖关系

什么时候用： 理解微服务架构或模块化系统中组件之间的契约关系。agent-wrapper 中 LLM Provider 组件提供 chat() 接口，Agent Runtime 组件消费这个接口。

14.2.4 部署图（Deployment Diagram）

把软件映射到硬件。展示运行时处理节点及驻留在节点上的构件。

画什么：

• 节点（三维立方体）：服务器、容器、设备
• 构件（矩形）：部署在节点上的软件模块
• 通信路径：节点间的网络连接，可标注协议（HTTP/REST、gRPC、消息队列）

什么时候用： 理解生产环境的物理拓扑。agent-wrapper 的部署：User's Machine 节点运行 CLI，Cloud VM 节点运行 Agent Runtime，外部节点 Anthropic API。

14.2.5 包图（Package Diagram）

按逻辑分组组织模型元素。包可以嵌套，包之间有依赖和导入关系。

画什么：

• 包（文件夹图标或带标签的矩形框）、包间的依赖箭头、包的嵌套层次
• 体现分层架构：domain/ → application/ → infrastructure/ → presentation/

什么时候用： 大项目的模块组织概览。agent-wrapper 中 core/ 包、tools/ 包、plugins/ 包、cli/ 包的依赖方向。

14.2.6 复合结构图（Composite Structure Diagram）

深入一个类的内部。展示类的部件（Part）、端口（Port）、连接器（Connector）以及它们之间的协作。

画什么：

• 部件（类内部的组件实例）、端口（小方块，部件与外界的交互点）、连接器（部件间的连线）
• 比类图更微观——类图展示「哪些类」，复合结构图展示「这个类内部由哪些部分构成」

什么时候用： 理解复杂模式（如 Observer、Visitor）的运行时内部结构。agent-wrapper 中 AgentLoop 类的内部：Planner 部件 → Executor 部件 → Verifier 部件，通过端口相互连接。

14.2.7 剖面图（Profile Diagram）

UML 的扩展机制。定义特定领域或平台的方言——自定义构造型（Stereotype）、标签值（Tagged Value）、约束（Constraint）。

画什么：

• <<stereotype>> 定义、用构造型标注的元类扩展
• 比如定义一个 <<microservice>> 构造型，标注 language、port、healthCheck 等标签值

什么时候用： 当 UML 需要说团队自己的术语时。agent-wrapper 项目可以定义 <<skill>>、<<tool>>、<<hook>> 等自定义构造型。

14.3 行为性图形（Behavior Diagrams）：系统怎么运行

行为性图形回答「系统怎么工作」——流程、交互、状态变迁。它们是系统的动态录像。

14.3.1 用例图（Use Case Diagram）

从用户视角展示系统能做什么。外行最容易看懂的 UML 图。

画什么：

• 参与者（火柴人图标）：人、外部系统、定时器
• 用例（椭圆）：系统提供的功能
• 关系：<<include>>（必须包含）、<<extend>>（可选扩展）、泛化（参与者或用例的继承）

什么时候用： 和产品经理对齐需求。agent-wrapper 的用例：用户 → 「创建 Agent」、用户 → 「配置 Skill」、用户 → 「启动自主循环」、外部 API → 「响应 Tool Call」。

14.3.2 活动图（Activity Diagram）

增强版流程图。展示从活动到活动的控制流，支持并发分支和合并。

画什么：

• 活动节点（圆角矩形）、决策节点（菱形）、fork/join（粗横线）、泳道（可选）
• 开始节点（实心圆）→ 活动序列 → 结束节点（实心圆+外圈）

什么时候用： 描述一个流程的多分支执行路径。agent-wrapper 中 Goal 命令的执行流程：解析 Goal → 生成 Plan → fork（并行执行 Sub-goals）→ join（汇总结果）→ 验证 → 输出。

14.3.3 状态机图（State Machine Diagram）

跟踪一个对象从生到死的完整生命周期——中间经历了哪些状态，什么事件触发了状态变迁。

画什么：

• 状态（圆角矩形，可包含 entry/do/exit 动作）、转移（箭头上标注「事件[守卫]/动作」）
• 初始伪状态（实心圆）、终止状态（实心圆+外圈）

什么时候用： 理解有复杂生命周期的对象。agent-wrapper 中 Task 对象的状态机：pending → queued → running → (completed | failed | cancelled)，每个转移上标注触发事件。

14.3.4 序列图（Sequence Diagram）

最常用的交互图。按时间顺序展示对象间的消息交换——谁先调谁、传什么参数、返回什么。

画什么：

• 生命线（纵向虚线，代表对象的时间线）、激活条（生命线上的矩形，代表对象正在执行）
• 消息（水平箭头）：同步调用（实心箭头）、异步消息（开放箭头）、返回（虚线箭头）

什么时候用： 理解一个具体场景的完整调用链。agent-wrapper 中「创建并运行一个 Agent」的完整交互序列：CLI → AgentFactory.create() → Agent.run() → LLMProvider.chat() → ToolRegistry.execute() → 返回结果 → CLI 输出。

14.3.5 通信图（Communication Diagram）

和序列图共享同一批信息，视角不同。序列图强调时间顺序（从上到下），通信图强调对象间的组织关系（空间布局）。

画什么：

• 对象（矩形节点）、链接（对象间的连线）、消息（连线上标注序号和箭头方向）
• 消息编号（1, 2, 3...）表示时间顺序，嵌套用 1.1, 1.2...

什么时候用： 关注「在某个时刻，哪些对象在互相通信」时——对象间的链接结构成为重点，时间线退居次要。

14.3.6 定时图（Timing Diagram）

展示对象状态随时间的变化曲线，含精确的时间约束。

画什么：

• 时间轴（横向，精确刻度）、状态线（折线，展示每个对象的状态变化）、持续时间约束 {duration < 500ms}
• 适合实时系统、嵌入式系统和性能关键路径

什么时候用： 性能分析和实时约束验证。agent-wrapper 中 Tool Call 的超时机制：execute_tool() 必须在 30s 内完成，否则触发重试——定时图展示这四个阶段的时间约束。

14.3.7 交互概览图（Interaction Overview Diagram）

活动图和序列图的混合体。用活动图的控制流框架，每个节点可以嵌入一个交互片段（序列图、通信图、定时图或其他交互概览图）。

画什么：

• 框架是活动图（决策节点、fork/join、开始/结束）
• 节点内部嵌入 sd（序列图）等交互片段

什么时候用： 复杂流程的宏观概览——不展示每次函数调用的细节，而是展示「这个流程分几大阶段，每个阶段内部发生了什么交互」。agent-wrapper 完整运行流程：初始化（序列图）→ 规划（序列图）→ 执行循环（交互概览图）→ 完成（序列图）。

14.4 超越 UML：三种实用的非 UML 图

上面 14 种是 UML 2.5 标准定义的。真实软件工程中，有三种图不在 UML 规范里，但使用频率比很多 UML 图更高。

14.4.1 系统架构图（Architecture Diagram）

比组件图更自由。展示系统的顶层组件、外部依赖以及数据流方向。不遵守 UML 严格的符号约束——方块、圆圈、数据库图标、云图标都可以用，含义清晰即可。

什么时候用： 任何项目的第一个图。项目经理、新成员、外部评审者——所有人都从架构图开始理解系统。

14.4.2 流程图（Flowchart）

比活动图更简单。没有 fork/join 的并发语义，没有泳道的组织维度——只有开始、结束、处理步骤、判断分支。它就是画在白板上的那种图。

什么时候用： 描述算法逻辑、业务流程或决策树。不追求 UML 的完备语义，追求最大可读性。

14.4.3 泳道图（Swimlane Diagram）

流程图 + 角色分工。把流程步骤按「谁负责」分配到不同的泳道里，跨泳道的箭头表示交互和交接。

什么时候用： 跨团队协作流程。agent-wrapper 中用户、Agent Runtime、LLM Provider、Tool Registry 四个泳道的完整交互流程。

14.5 UML 在 AI 时代的三个用途

AI 生成代码之后，UML 的角色从「前置设计工具」变成了「后置理解工具」。三个具体用途：

用途一：代码理解的可视化层。 第 13 章的 Understand-Anything 产出知识图谱——文件、函数、类的节点和边。UML 把这些节点组织成有意义的模式——类图把散落的类型组织成领域模型，序列图把函数调用链组织成交互故事。知识图谱是原材料，UML 是成品。

用途二：AI 生成代码的质量验证。 AI 生成了 2000 行代码。你怎么知道架构没被写烂？生成一张类图——继承链有没有循环引用一目了然。生成一张包图——依赖方向有没有违反 Clean Architecture 的箭头规则。UML 就是 AI 代码的架构 X 光。

用途三：团队沟通的通用语言。 不同的人看同一段 AI 代码，脑子里画的图可能完全不一样。UML 给了一套标准化的可视化符号，所有人坐下来看同一张图，对「这段代码长什么样」的理解不会差太远。

14.6 insight-diagram：一键生成全套 UML 图的 Skill

前面聊了 17 种图。一个中等规模的项目，手工画完，单位是天。

insight-diagram 在 goal.rpcx.io 上发布，给任意代码库自动生成全套 UML 图、架构图和流程图。不需要你懂 UML——告诉它项目在哪，它分析代码库、让你选图表类型，然后一张张生成。

14.6.1 核心理念：代码分析 → 图表选择 → 逐个生成

四个步骤：

步骤 1 — 分析代码库。 Skill 读取项目的 CLAUDE.md（项目概览）、各子目录的 CLAUDE.md（模块细节），用 Glob 扫描源码文件结构，用 Grep 搜索关键模式（接口定义、函数签名、依赖注入）。提炼出组件清单、依赖关系图、核心类型、业务流程和部署拓扑。

步骤 2 — 选择图表。 多选菜单，17 种图表分四组展示：结构性图形（类图、对象图、组件图、部署图、包图、复合结构图、剖面图）、行为性图形（用例图、活动图、状态机图）、交互图（序列图、通信图、定时图、交互概览图）、实用非 UML（系统架构图、流程图、泳道图）。默认推荐：architecture + sequence + flowchart。

步骤 3 — 逐个生成。 每个图表的生成流程：

1. 先读示例。 Skill 内置 13 个示例 HTML 文件，每种图表类型一个。生成前从示例中提取布局策略（节点间距、分组方式、箭头走向）、节点样式层级（核心节点高亮、普通节点实线边框、可选节点虚线边框）、标注风格（阶段标签、Legend 图例、卡片摘要）和信息密度。
2. 整理元素和关系。 根据步骤 1 的分析结果，确定元素和关系。类图：10-15 个核心类型。序列图：2-5 个核心交互场景。每个图有明确关注重点，不追求全量覆盖。
3. 调用 architecture-diagram skill 渲染。 使用 Anthropic Claude 视觉风格（暖白背景 #FAF9F6、terracotta/sage/plum/rose 配色、Inter 字体），输出 HTML+SVG。所有元素不得遮盖——箭头在节点下方、间距充足（垂直 ≥40px，水平 ≥30px）、文字不溢出。元素过多则拆分子图或缩小元素。
4. 保存到 docs/ 目录。 文件命名如 docs/architecture.html、docs/class.html、docs/sequence.html。

步骤 4 — 报告。 全部生成完成后输出文件列表和每张图的简要描述。

14.6.2 图表生成顺序：从宏观到微观

生成顺序是固定的，不是随机的：

architecture → component → deployment → package → composite-structure →
profile → class → object → usecase → flowchart → activity → state-machine →
swimlane → sequence → communication → timing → interaction-overview

从架构图开始，逐步深入到组件、部署、包结构、类的内部结构，再到行为层面的用例、流程、状态、交互。每一步都踩在上一步提取的信息上——生成类图的时候，架构图和组件图已经把系统的主要模块和边界画出来了。

14.6.3 关键设计决策

示例驱动，而非提示词驱动。 Skill 不给 LLM 一段「画类图的提示词」——给示例 HTML 文件。LLM 从示例中提取布局模式、色彩方案、节点样式，用自己的内容替换。LLM 做「模仿已有模板然后替换内容」这件事远比做「根据纯文本描述从零生成视觉设计」靠谱。

专用渲染 Skill 分离。 insight-diagram 不做渲染——它调用 /architecture-diagram（另一个 Skill）生成 HTML+SVG。职责分离：insight-diagram 负责「分析代码、选择图表、整理元素」，architecture-diagram 负责「把元素渲染为 HTML+SVG」。这是 Skill 系统中的组合模式——一个 Skill 依赖另一个 Skill。

防遮盖规则。 SVG 元素不得互相遮盖。箭头绘制在节点下方（SVG 中先画箭头再画节点）。节点间最小间距 40px（垂直）、30px（水平）。文字不超出节点边界——超长截断或换行。这些规则在生成时强制检查，确保产出图表可直接用于文档和演示，跳过人工微调步骤。

语言无关。 支持 Go、Python、TypeScript、Java、Rust 等主流语言。分析代码库使用 Glob + Grep + Read——不依赖语言特定解析器，对所有语言有基本覆盖。需要精确提取「所有类和它们的方法签名」的类图时，建议与 Understand-Anything（第 13 章）组合使用——Understand-Anything 提供精确的结构数据，insight-diagram 负责可视化。

14.6.4 与 Understand-Anything 的配合

第 13 章和本章是互补关系：

维度	Understand-Anything	insight-diagram
产出	知识图谱（JSON）	UML/架构/流程 图（HTML+SVG）
精度	确定性（Tree-sitter 解析）	LLM 推断（基于代码阅读）
用途	Agent 查询、影响分析、导航	人类阅读、文档、演示
目标读者	AI Agent	人类团队
更新方式	增量（commit hook 触发）	按需（手动触发重新生成）

最佳实践：Understand-Anything 产出的知识图谱提供精确的组件清单和依赖关系，insight-diagram 把信息可视化为标准 UML 图形。确定性的结构数据 + LLM 的视觉表达——和 Understand-Anything 的 Tree-sitter + LLM 混合架构是同一设计哲学。

14.6.5 在 agent-wrapper 上实战

实际上只生成了架构图、流程图和几个UML图就已经可以充分理解AI生成的代码了，这里我生成了所有的图片，主要是为了让你了解生成的各个图形的效果 。我更多会看架构图、流程图、类图、序列图、泳道图等。

有些生成的图形连线有些错误，图形有些重叠，你可以给智能体指出错误，让它修复，生成完美的图形。下面有些图生成的不是很完美，我也贴出来了，没有进一步优化。

agent-wrapper（/Users/smallnest/ai/agent-wrapper）是 Go 语言实现的 AI Agent 包装框架，核心功能包括 Agent 生命周期管理、Skill 注册与调度、Tool 调用链、LLM Provider 抽象和多轮对话状态机。项目包含 20+ 个 Go 源文件，分布在 core/、tools/、plugins/、cli/ 等包中。

使用 insight-diagram 生成全套图表的过程：

1. 调用 Skill。 /insight-diagram，Skill 读取 CLAUDE.md、扫描源码结构、提取组件和接口。
2. 选择图表。 默认推荐三张图（architecture + sequence + flowchart），覆盖「系统怎么组织的、关键交互怎么发生、主流程怎么走」。
3. 逐个生成。 Skill 依次读取对应示例、整理元素、调用 architecture-diagram 渲染、保存到 docs/。
4. 人工补充。 生成的图表作为基础版本，微调后补充到项目文档。

agent-wrapper 系统架构图（Architecture Diagram）

这张图把 agent-wrapper 的顶层结构摊开了。上边调用方（Go 代码或 CLI），中间是核心——Registry 管理 8 个 Provider、Orchestrator 驱动多轮对话循环、process 包管理子进程生命周期。下边 8 个 Agent CLI 进程（claude、codex、pi、opencode 等），每个独立子进程，通过 stdin/stdout 与 wrapper 通信。

agent-wrapper 类图（Class Diagram）

五个核心类型。Agent 是顶层接口，只有 Run() — 接收 RunInput，输出 <-chan Event。Orchestrator 持有 Agent，加 ApprovalHandler、BudgetHandler、ContextCompressor 三个钩子。Registry 用 sync.RWMutex 保护 map。RunInput 的 SessionID、MaxTurns、OutputFormat 决定每次调用的行为。Event 五种类型（TextDelta/ToolCall/ToolResult/TurnEnd/Error）覆盖 agent CLI 的所有输出。

agent-wrapper 对象图（Object Diagram）

「用 Claude Code provider 创建并运行一个 Agent」那一瞬间的内存快照。Registry 里注册了 8 个 provider，Get("claude-code") 返回 ClaudeCodeAgent 实例。Orchestrator 持有这个 agent，默认 ChainedCompressor（SlidingWindow + Summary），3 次重试。RunInput 带着 prompt "重构这个文件"、MaxTurns=10、OutputFormat=stream。

agent-wrapper 组件图（Component Diagram）

组件之间的契约关系。Registry 对外提供 Register(name, Factory) 和 Get(name) Agent 两个接口（棒棒糖），各 provider 包作为组件注册进来。Orchestrator 消费 Agent 接口，同时插 ApprovalHandler 和 BudgetHandler 两个插座。底层 process.AgentProcess 封装 os/exec.Cmd，提供 stdin/stdout/stderr 管道和优雅关闭（SIGTERM → 5s → SIGKILL）。

agent-wrapper 部署图（Deployment Diagram）

代码到物理节点的映射。用户机器运行 CLI（cmd/agent-wrapper 二进制）， 运行 Orchestrator.Run()，启动 claude/codex 等子进程。外部节点三个：Anthropic API（claude 后端）、OpenAI API（codex 后端）、Moonshot API（kimi-code 后端）。CLI → Orchestrator 是本地函数调用，Orchestrator → Agent CLI 是子进程 stdio，Agent CLI → 外部 API 是 HTTPS。

agent-wrapper 包图（Package Diagram）

顶层 agentwrapper 包入口，依赖 types、harness、process。types/ 在最底层——Agent 接口、Event、Message、RunInput，所有其他包都依赖它。harness/ 提供可插拔组件：ApprovalHandler、BudgetHandler、ContextCompressor。process/ 封装子进程管理。provider/ 是独立子树——八个包各自实现 Agent 接口。箭头方向符合 Clean Architecture：外层依赖内层，内层不依赖外层。

agent-wrapper 复合结构图（Composite Structure Diagram）

Orchestrator 的内部结构。四个 Parts：Agent（子进程驱动）、ApprovalHandler（工具审批）、BudgetHandler（token 预算）、ContextCompressor（上下文压缩重试）。Run() 通过 runAgentWithRetry() 端口调 Agent，Event Channel 经审批和预算检查后从 out 端口输出。关键：agent.Run 失败 → IsContextLengthExceeded(err) → compressor.Compress() → 重试最多 maxRetries 次（默认 3）。

agent-wrapper 剖面图（Profile Diagram）

为 agent-wrapper 定义的三个自定义 Stereotype。<<Provider>>——实现 Agent 接口的子进程驱动类，含 binary、protocol 标签值。<<Handler>>——可插拔运行时钩子，含 hook_point、is_async 标签。<<Event>>——统一事件类型，含 direction 标签。在 agent.go 里写 // @stereotype Provider binary=claude protocol=stream-json，生成类图时自动识别特殊样式。

agent-wrapper 流程图（Flowchart）

从输入到输出的完整决策树。Registry.Get(provider) → 查表 → 未找到返回 ErrNotRegistered。找到则创建 Agent → NewOrchestrator 配 Approval/Budget/Compressor/Retries。orch.Run() → 校验 prompt → runAgentWithRetry() 启子进程 → Scanner 解析 NDJSON → 每条事件过审批（allow/deny/abort）→ 过预算 → 输出。TurnEnd 检查 stop_reason，Context 超限触发压缩重试。

agent-wrapper 用例图（Use Case Diagram）

这个图画的不清晰。

agent-wrapper 活动图（Activity Diagram）

Orchestrator.Run() 的并发控制流。起始 → Fork 两条。主循环：eventCh 接收 → 分发审批/预算/转发 → TextDelta 直接转，ToolCall 走审批，TurnEnd 走预算。子进程监控：goroutine 监听 ctx.Done() → terminate()（SIGTERM → 5s → SIGKILL）。退出时 Join → close(out)。

agent-wrapper 状态机图（State Machine Diagram）

AgentProcess 生命周期。Idle → cmd.Start() → Running。Running + cmd.Wait() → Exited（异常记 ExitCode）。Running + ctx 取消 → Terminating → SIGTERM → 5s 后 SIGKILL → Killed。sync.Once 保证 terminate 只跑一次。

agent-wrapper 序列图（Sequence Diagram）

Orchestrator.RunSync() 的时间线。CLI → Registry.Get("claude-code") → 返回 ClaudeCodeAgent → NewOrchestrator → orch.RunSync() → agent.Run() → StartProcess() 启动子进程 → NDJSON 到 stdout → Scanner 解析 → 首条 event 带 session_id → 逐条回 Orchestrator → TurnEnd → RunResult{Text, Usage, SessionID}。agent-wrapper 最核心调用链。

agent-wrapper 通信图（Communication Diagram）

同一批信息，视角换成「谁在跟谁通信」。CLI→Registry（1:Get）→Orchestrator（2:NewOrchestrator, 3:RunSync）→ClaudeCodeAgent（4:Run）→AgentProcess（5:Start）→Anthropic API（6:HTTPS）。反馈路径：API→Process→Scanner→Agent→Orchestrator channel→CLI。强调拓扑，不强调时间线。

图画的不好。

agent-wrapper 定时图（Timing Diagram）

Orchestrator.RunSync() 的时间约束（ms）。0ms 开始，2ms Agent.Run，5ms Process running，10ms 流式输出，12ms API 请求，50ms TurnEnd，55ms 返回。约束：tool_call ≤ 30s、SIGTERM→SIGKILL = 5s。检查长对话超时边界。

agent-wrapper 交互概览图（Interaction Overview Diagram）

活动图框架嵌入三个交互场景。判断「output format?」→ 三条分支：stream（sd OutputStream，实时输出）、json（sd OutputJSON，Marshal(RunResult) 单条）、stream-json（sd OutputStreamJSON，NDJSON 逐行）。汇聚到 exit。不展开细节，一眼看清分流逻辑。

agent-wrapper 泳道图（Swimlane Diagram）

四泳道：User/CLI、Orchestrator、Agent/Provider、External LLM API。User：Registry.Get → RunInput → RunSync/消费 events。Orchestrator：校验 prompt → runAgentWithRetry → processEvent（审批+预算）→ collect result。Agent：startSubprocess → parseNDJSON → emit events → wait exit。API：receive → generate → return tokens/tool_calls。跨泳道标注协议：via interface、via pipe、via HTTPS。

14.7 本章小结

UML 十四种图加上三种实用扩展，覆盖软件系统的两个核心维度：结构（系统长什么样）和行为（系统怎么运行）。AI 开始生成代码之后，UML 从「前置设计工具」变成了「后置理解工具」——AI 写代码，图让人看得懂。

insight-diagram 把画图自动化了。一个 Skill，四步（分析代码 → 选择图表 → 逐图生成 → 报告），17 种图表。示例驱动的生成策略锁住了风格，防遮盖规则保证了产出直接能用。跟 Understand-Anything 配合，就是「确定性结构 + LLM 可视化」的完整链路。

本章为 agent-wrapper 预留的图表占位区，后续用 insight-diagram 生成全套图表后补充实际图片。

第 12 到 14 章连续过了三组 AI 编码辅助工具：官方插件、代码知识图谱、UML 可视化。下一章进代码重构——代码写完了，怎么让 AI 帮你把它改好。