「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 种图，分为两大类：

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）

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

画什么：

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

14.2.3 组件图（Component Diagram）

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

画什么：

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

14.2.4 部署图（Deployment Diagram）

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

画什么：

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

14.2.5 包图（Package Diagram）

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

画什么：

什么时候用： 大项目的模块组织概览。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）。

画什么：

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

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

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

14.3.1 用例图（Use Case Diagram）

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

画什么：

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

14.3.2 活动图（Activity Diagram）

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

画什么：

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

14.3.3 状态机图（State Machine Diagram）

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

画什么：

什么时候用： 理解有复杂生命周期的对象。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）

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

画什么：

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

14.3.6 定时图（Timing Diagram）

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

画什么：

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

14.3.7 交互概览图（Interaction Overview Diagram）

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

画什么：

什么时候用： 复杂流程的宏观概览——不展示每次函数调用的细节，而是展示「这个流程分几大阶段，每个阶段内部发生了什么交互」。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-Anythinginsight-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。<>——实现 Agent 接口的子进程驱动类，含 binary、protocol 标签值。<>——可插拔运行时钩子，含 hook_point、is_async 标签。<>——统一事件类型，含 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 帮你把它改好。