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

<blockquote><p>「A picture is worth a thousand words. A diagram is worth ten thousand lines of code.」<br>一图胜千言。一张图胜万行代码。</p></blockquote><p>第 13 章解决了一个问题：AI 写代码容易，读代码难。Understand-Anything 用知识图谱<strong>让 AI 理解现有代码</strong>。</p><p>反过来——代码写完了，作为人类<strong>你怎么理解它</strong>？毕竟，线上出了故障你还等着你背锅呢。</p><p>我前一段看到一句箴言：&quot; , &quot;， 翻译过来就是&quot;你可以外包你的思考(给AI),但是你不能外包你的理解&quot;。 这句话被 Andrej Karpathy 多次引用，以至于大家认为是他说的，其实是kache说的：</p><p><img src="/images/image-20260604094614868.png"></p><p>这句话非常有哲理。Dex Horthy 在 2025 AI Engineer 大会上独立提出了：&quot;Don&#39;t outsource the thinking&quot; &#x2F; &quot;AI cannot replace thinking, it can only amplify the thinking you have done.&quot;，但是今年你看， AI已经外包了我们的思考，你只需说出的你需求，智能体就能帮助你生生成你要的程序，但是 AI 没有办法帮我们理解啊。</p><p>我最近就遇到了这样的困惑：我通过goal workflow很快的实现了一个大模型训推任务智能诊断系统，全是AI帮我生成的，但是在联调的前一个星期，我心虚了。</p><p>因为我知道，联调和上线的时候，必然有一些问题，比如当时的设计有些模糊的地方，设计上有gap, 实现上也难免有bug。如果我对生成的代码不熟悉，联调的时候出故障我都不知道啥原因咋修复，可能当时还得重新捋代码才能慢慢找根因，太影响联调的同学了。未来上线以后出现问题，想快速修复就更不可能了。</p><p>所以我专门花了两天时间，建了几个卡片，就为了学习代码理解代码。</p><p>那我是通过什么方式去理解AI生成的代码的呢？</p><p>答案藏在一个用了二十多年的老工具里：UML。区别只有一点：以前的 UML 是人画给团队的，现在是 AI 画给你的。十四种图，从类结构到部署拓扑，从序列交互到状态变迁。AI 生成代码，AI 再画图解释代码——你读图就够了。</p><p>为此，我专门创建了一个Skill，用来生成UML的十四种代码和架构图、流程图以及泳道图。此skill的介绍：<a href="https://goal.rpcx.io/index_cn.html#step-diagram%EF%BC%8C">https://goal.rpcx.io/index_cn.html#step-diagram，</a> 也集成到了goal workflow套件中了。</p><p>本章分两部分：第一部分过一遍 UML 十四种正式图形，外加三种 UML 规范没有但实际很常用的图。第二部分介绍 insight-diagram——一个在 goal.rpcx.io 上发布的 Skill，给任意代码库自动生成全套 UML 图、架构图和流程图。</p><span id="more"></span><h2 id="14-1-UML-简史：从三剑客到-OMG-标准"><a href="#14-1-UML-简史：从三剑客到-OMG-标准" class="headerlink" title="14.1 UML 简史：从三剑客到 OMG 标准"></a>14.1 UML 简史：从三剑客到 OMG 标准</h2><p>1994 年，Grady Booch 和 Jim Rumbaugh 在 Rational Software 相遇。Booch 有他的 Booch Method，Rumbaugh 有他的 OMT（Object Modeling Technique）。两种方法符号体系不同，画出来的图互不认识。</p><p>1995 年，Ivar Jacobson 加入，带来他的 OOSE（Object-Oriented Software Engineering）方法。三人被称为「三剑客」（Three Amigos），目标：统一面向对象建模的符号体系，让所有软件工程师用同一套语言画图。</p><p>1997 年，OMG（Object Management Group）采纳 UML 1.0。2005 年，UML 2.0 图形种类从 9 种扩展到 13 种。最新版本 UML 2.5.1（2017 年）定义了 14 种图，分为两大类：</p><ul><li><strong>结构性图形（Structure Diagrams）</strong>：描述系统的静态结构——有哪些组件、怎么组织的。</li><li><strong>行为性图形（Behavior Diagrams）</strong>：描述系统的动态行为——怎么运行、怎么交互。</li></ul><p>AI 时代之前，UML 的命运比较尴尬。敏捷宣言之后，很多人觉得「重文档轻代码」不靠谱，UML 跟着被冷落了。但有一个事实没变：代码由 AI 大量生成之后，人类比以往更需要可视化理解工具。UML 重新有了用武之地——角色从「先画图再写代码」的前置仪式，变成了「AI 写代码，你读图」的后置理解工具。</p><h2 id="14-2-结构性图形（Structure-Diagrams）：系统长什么样"><a href="#14-2-结构性图形（Structure-Diagrams）：系统长什么样" class="headerlink" title="14.2 结构性图形（Structure Diagrams）：系统长什么样"></a>14.2 结构性图形（Structure Diagrams）：系统长什么样</h2><p>结构性图形回答「系统由什么组成」——类、对象、组件、包、部署节点。它们是系统的静态 X 光片。</p><h3 id="14-2-1-类图（Class-Diagram）"><a href="#14-2-1-类图（Class-Diagram）" class="headerlink" title="14.2.1 类图（Class Diagram）"></a>14.2.1 类图（Class Diagram）</h3><p>最常用的 UML 图。展示系统中的类、接口、协作以及它们之间的关系。</p><p><strong>画什么：</strong></p><ul><li>类名、属性、方法——每个类一个矩形框，分成三格</li><li>关系类型：泛化（继承，空心三角箭头）、实现（虚线空心三角）、关联（实线）、聚合（空心菱形，整体-部分弱关系）、组合（实心菱形，整体-部分强关系，同生命周期）、依赖（虚线箭头）</li></ul><p><strong>什么时候用：</strong> 看项目的领域模型。agent-wrapper 项目的 <code>Agent</code>、<code>Task</code>、<code>Tool</code>、<code>Message</code> 等核心类型及其继承和组合关系。</p><p><strong>AI 时代的价值：</strong> AI 生成 50 个类之后，类图让你一眼看清谁继承了谁、谁组合了谁——不用在 50 个文件之间反复横跳。</p><h3 id="14-2-2-对象图（Object-Diagram）"><a href="#14-2-2-对象图（Object-Diagram）" class="headerlink" title="14.2.2 对象图（Object Diagram）"></a>14.2.2 对象图（Object Diagram）</h3><p>类图的运行时快照。展示特定时刻的对象实例及其属性值和链接关系。</p><p><strong>画什么：</strong></p><ul><li>对象名:类名（加下划线标注）、属性的具体值、实例间的链接</li><li>比如 <code>agent1: Agent { name=&quot;code-generator&quot;, model=&quot;claude-4&quot; }</code> 连接到 <code>task42: Task { status=&quot;running&quot; }</code></li></ul><p><strong>什么时候用：</strong> 调试时的内存快照。复杂对象图在某个时刻的状态——帮助看清递归结构、循环引用、单例模式的具体实例分布。</p><h3 id="14-2-3-组件图（Component-Diagram）"><a href="#14-2-3-组件图（Component-Diagram）" class="headerlink" title="14.2.3 组件图（Component Diagram）"></a>14.2.3 组件图（Component Diagram）</h3><p>比类图高一层——展示软件架构中可替换的模块化组件及其接口。</p><p><strong>画什么：</strong></p><ul><li>组件（矩形，带 <code>&lt;&lt;component&gt;&gt;</code> 标识）、提供的接口（棒棒糖符号）、需要的接口（插座符号）</li><li>组件间通过接口的依赖关系</li></ul><p><strong>什么时候用：</strong> 理解微服务架构或模块化系统中组件之间的契约关系。agent-wrapper 中 <code>LLM Provider</code> 组件提供 <code>chat()</code> 接口，<code>Agent Runtime</code> 组件消费这个接口。</p><h3 id="14-2-4-部署图（Deployment-Diagram）"><a href="#14-2-4-部署图（Deployment-Diagram）" class="headerlink" title="14.2.4 部署图（Deployment Diagram）"></a>14.2.4 部署图（Deployment Diagram）</h3><p>把软件映射到硬件。展示运行时处理节点及驻留在节点上的构件。</p><p><strong>画什么：</strong></p><ul><li>节点（三维立方体）：服务器、容器、设备</li><li>构件（矩形）：部署在节点上的软件模块</li><li>通信路径：节点间的网络连接，可标注协议（HTTP&#x2F;REST、gRPC、消息队列）</li></ul><p><strong>什么时候用：</strong> 理解生产环境的物理拓扑。agent-wrapper 的部署：User&#39;s Machine 节点运行 CLI，Cloud VM 节点运行 Agent Runtime，外部节点 Anthropic API。</p><h3 id="14-2-5-包图（Package-Diagram）"><a href="#14-2-5-包图（Package-Diagram）" class="headerlink" title="14.2.5 包图（Package Diagram）"></a>14.2.5 包图（Package Diagram）</h3><p>按逻辑分组组织模型元素。包可以嵌套，包之间有依赖和导入关系。</p><p><strong>画什么：</strong></p><ul><li>包（文件夹图标或带标签的矩形框）、包间的依赖箭头、包的嵌套层次</li><li>体现分层架构：<code>domain/</code> → <code>application/</code> → <code>infrastructure/</code> → <code>presentation/</code></li></ul><p><strong>什么时候用：</strong> 大项目的模块组织概览。agent-wrapper 中 <code>core/</code> 包、<code>tools/</code> 包、<code>plugins/</code> 包、<code>cli/</code> 包的依赖方向。</p><h3 id="14-2-6-复合结构图（Composite-Structure-Diagram）"><a href="#14-2-6-复合结构图（Composite-Structure-Diagram）" class="headerlink" title="14.2.6 复合结构图（Composite Structure Diagram）"></a>14.2.6 复合结构图（Composite Structure Diagram）</h3><p>深入一个类的内部。展示类的部件（Part）、端口（Port）、连接器（Connector）以及它们之间的协作。</p><p><strong>画什么：</strong></p><ul><li>部件（类内部的组件实例）、端口（小方块，部件与外界的交互点）、连接器（部件间的连线）</li><li>比类图更微观——类图展示「哪些类」，复合结构图展示「这个类内部由哪些部分构成」</li></ul><p><strong>什么时候用：</strong> 理解复杂模式（如 Observer、Visitor）的运行时内部结构。agent-wrapper 中 <code>AgentLoop</code> 类的内部：<code>Planner</code> 部件 → <code>Executor</code> 部件 → <code>Verifier</code> 部件，通过端口相互连接。</p><h3 id="14-2-7-剖面图（Profile-Diagram）"><a href="#14-2-7-剖面图（Profile-Diagram）" class="headerlink" title="14.2.7 剖面图（Profile Diagram）"></a>14.2.7 剖面图（Profile Diagram）</h3><p>UML 的扩展机制。定义特定领域或平台的方言——自定义构造型（Stereotype）、标签值（Tagged Value）、约束（Constraint）。</p><p><strong>画什么：</strong></p><ul><li><code>&lt;&lt;stereotype&gt;&gt;</code> 定义、用构造型标注的元类扩展</li><li>比如定义一个 <code>&lt;&lt;microservice&gt;&gt;</code> 构造型，标注 <code>language</code>、<code>port</code>、<code>healthCheck</code> 等标签值</li></ul><p><strong>什么时候用：</strong> 当 UML 需要说团队自己的术语时。agent-wrapper 项目可以定义 <code>&lt;&lt;skill&gt;&gt;</code>、<code>&lt;&lt;tool&gt;&gt;</code>、<code>&lt;&lt;hook&gt;&gt;</code> 等自定义构造型。</p><h2 id="14-3-行为性图形（Behavior-Diagrams）：系统怎么运行"><a href="#14-3-行为性图形（Behavior-Diagrams）：系统怎么运行" class="headerlink" title="14.3 行为性图形（Behavior Diagrams）：系统怎么运行"></a>14.3 行为性图形（Behavior Diagrams）：系统怎么运行</h2><p>行为性图形回答「系统怎么工作」——流程、交互、状态变迁。它们是系统的动态录像。</p><h3 id="14-3-1-用例图（Use-Case-Diagram）"><a href="#14-3-1-用例图（Use-Case-Diagram）" class="headerlink" title="14.3.1 用例图（Use Case Diagram）"></a>14.3.1 用例图（Use Case Diagram）</h3><p>从用户视角展示系统能做什么。外行最容易看懂的 UML 图。</p><p><strong>画什么：</strong></p><ul><li>参与者（火柴人图标）：人、外部系统、定时器</li><li>用例（椭圆）：系统提供的功能</li><li>关系：<code>&lt;&lt;include&gt;&gt;</code>（必须包含）、<code>&lt;&lt;extend&gt;&gt;</code>（可选扩展）、泛化（参与者或用例的继承）</li></ul><p><strong>什么时候用：</strong> 和产品经理对齐需求。agent-wrapper 的用例：用户 → 「创建 Agent」、用户 → 「配置 Skill」、用户 → 「启动自主循环」、外部 API → 「响应 Tool Call」。</p><h3 id="14-3-2-活动图（Activity-Diagram）"><a href="#14-3-2-活动图（Activity-Diagram）" class="headerlink" title="14.3.2 活动图（Activity Diagram）"></a>14.3.2 活动图（Activity Diagram）</h3><p>增强版流程图。展示从活动到活动的控制流，支持并发分支和合并。</p><p><strong>画什么：</strong></p><ul><li>活动节点（圆角矩形）、决策节点（菱形）、fork&#x2F;join（粗横线）、泳道（可选）</li><li>开始节点（实心圆）→ 活动序列 → 结束节点（实心圆+外圈）</li></ul><p><strong>什么时候用：</strong> 描述一个流程的多分支执行路径。agent-wrapper 中 Goal 命令的执行流程：解析 Goal → 生成 Plan → fork（并行执行 Sub-goals）→ join（汇总结果）→ 验证 → 输出。</p><h3 id="14-3-3-状态机图（State-Machine-Diagram）"><a href="#14-3-3-状态机图（State-Machine-Diagram）" class="headerlink" title="14.3.3 状态机图（State Machine Diagram）"></a>14.3.3 状态机图（State Machine Diagram）</h3><p>跟踪一个对象从生到死的完整生命周期——中间经历了哪些状态，什么事件触发了状态变迁。</p><p><strong>画什么：</strong></p><ul><li>状态（圆角矩形，可包含 entry&#x2F;do&#x2F;exit 动作）、转移（箭头上标注「事件[守卫]&#x2F;动作」）</li><li>初始伪状态（实心圆）、终止状态（实心圆+外圈）</li></ul><p><strong>什么时候用：</strong> 理解有复杂生命周期的对象。agent-wrapper 中 <code>Task</code> 对象的状态机：pending → queued → running → (completed | failed | cancelled)，每个转移上标注触发事件。</p><h3 id="14-3-4-序列图（Sequence-Diagram）"><a href="#14-3-4-序列图（Sequence-Diagram）" class="headerlink" title="14.3.4 序列图（Sequence Diagram）"></a>14.3.4 序列图（Sequence Diagram）</h3><p>最常用的交互图。按时间顺序展示对象间的消息交换——谁先调谁、传什么参数、返回什么。</p><p><strong>画什么：</strong></p><ul><li>生命线（纵向虚线，代表对象的时间线）、激活条（生命线上的矩形，代表对象正在执行）</li><li>消息（水平箭头）：同步调用（实心箭头）、异步消息（开放箭头）、返回（虚线箭头）</li></ul><p><strong>什么时候用：</strong> 理解一个具体场景的完整调用链。agent-wrapper 中「创建并运行一个 Agent」的完整交互序列：CLI → AgentFactory.create() → Agent.run() → LLMProvider.chat() → ToolRegistry.execute() → 返回结果 → CLI 输出。</p><h3 id="14-3-5-通信图（Communication-Diagram）"><a href="#14-3-5-通信图（Communication-Diagram）" class="headerlink" title="14.3.5 通信图（Communication Diagram）"></a>14.3.5 通信图（Communication Diagram）</h3><p>和序列图共享同一批信息，视角不同。序列图强调时间顺序（从上到下），通信图强调对象间的组织关系（空间布局）。</p><p><strong>画什么：</strong></p><ul><li>对象（矩形节点）、链接（对象间的连线）、消息（连线上标注序号和箭头方向）</li><li>消息编号（1, 2, 3...）表示时间顺序，嵌套用 1.1, 1.2...</li></ul><p><strong>什么时候用：</strong> 关注「在某个时刻，哪些对象在互相通信」时——对象间的链接结构成为重点，时间线退居次要。</p><h3 id="14-3-6-定时图（Timing-Diagram）"><a href="#14-3-6-定时图（Timing-Diagram）" class="headerlink" title="14.3.6 定时图（Timing Diagram）"></a>14.3.6 定时图（Timing Diagram）</h3><p>展示对象状态随时间的变化曲线，含精确的时间约束。</p><p><strong>画什么：</strong></p><ul><li>时间轴（横向，精确刻度）、状态线（折线，展示每个对象的状态变化）、持续时间约束 <code>{duration &lt; 500ms}</code></li><li>适合实时系统、嵌入式系统和性能关键路径</li></ul><p><strong>什么时候用：</strong> 性能分析和实时约束验证。agent-wrapper 中 Tool Call 的超时机制：<code>execute_tool()</code> 必须在 30s 内完成，否则触发重试——定时图展示这四个阶段的时间约束。</p><h3 id="14-3-7-交互概览图（Interaction-Overview-Diagram）"><a href="#14-3-7-交互概览图（Interaction-Overview-Diagram）" class="headerlink" title="14.3.7 交互概览图（Interaction Overview Diagram）"></a>14.3.7 交互概览图（Interaction Overview Diagram）</h3><p>活动图和序列图的混合体。用活动图的控制流框架，每个节点可以嵌入一个交互片段（序列图、通信图、定时图或其他交互概览图）。</p><p><strong>画什么：</strong></p><ul><li>框架是活动图（决策节点、fork&#x2F;join、开始&#x2F;结束）</li><li>节点内部嵌入 <code>sd</code>（序列图）等交互片段</li></ul><p><strong>什么时候用：</strong> 复杂流程的宏观概览——不展示每次函数调用的细节，而是展示「这个流程分几大阶段，每个阶段内部发生了什么交互」。agent-wrapper 完整运行流程：初始化（序列图）→ 规划（序列图）→ 执行循环（交互概览图）→ 完成（序列图）。</p><h2 id="14-4-超越-UML：三种实用的非-UML-图"><a href="#14-4-超越-UML：三种实用的非-UML-图" class="headerlink" title="14.4 超越 UML：三种实用的非 UML 图"></a>14.4 超越 UML：三种实用的非 UML 图</h2><p>上面 14 种是 UML 2.5 标准定义的。真实软件工程中，有三种图不在 UML 规范里，但使用频率比很多 UML 图更高。</p><h3 id="14-4-1-系统架构图（Architecture-Diagram）"><a href="#14-4-1-系统架构图（Architecture-Diagram）" class="headerlink" title="14.4.1 系统架构图（Architecture Diagram）"></a>14.4.1 系统架构图（Architecture Diagram）</h3><p>比组件图更自由。展示系统的顶层组件、外部依赖以及数据流方向。不遵守 UML 严格的符号约束——方块、圆圈、数据库图标、云图标都可以用，含义清晰即可。</p><p><strong>什么时候用：</strong> 任何项目的第一个图。项目经理、新成员、外部评审者——所有人都从架构图开始理解系统。</p><h3 id="14-4-2-流程图（Flowchart）"><a href="#14-4-2-流程图（Flowchart）" class="headerlink" title="14.4.2 流程图（Flowchart）"></a>14.4.2 流程图（Flowchart）</h3><p>比活动图更简单。没有 fork&#x2F;join 的并发语义，没有泳道的组织维度——只有开始、结束、处理步骤、判断分支。它就是画在白板上的那种图。</p><p><strong>什么时候用：</strong> 描述算法逻辑、业务流程或决策树。不追求 UML 的完备语义，追求最大可读性。</p><h3 id="14-4-3-泳道图（Swimlane-Diagram）"><a href="#14-4-3-泳道图（Swimlane-Diagram）" class="headerlink" title="14.4.3 泳道图（Swimlane Diagram）"></a>14.4.3 泳道图（Swimlane Diagram）</h3><p>流程图 + 角色分工。把流程步骤按「谁负责」分配到不同的泳道里，跨泳道的箭头表示交互和交接。</p><p><strong>什么时候用：</strong> 跨团队协作流程。agent-wrapper 中用户、Agent Runtime、LLM Provider、Tool Registry 四个泳道的完整交互流程。</p><h2 id="14-5-UML-在-AI-时代的三个用途"><a href="#14-5-UML-在-AI-时代的三个用途" class="headerlink" title="14.5 UML 在 AI 时代的三个用途"></a>14.5 UML 在 AI 时代的三个用途</h2><p>AI 生成代码之后，UML 的角色从「前置设计工具」变成了「后置理解工具」。三个具体用途：</p><p><strong>用途一：代码理解的可视化层。</strong> 第 13 章的 Understand-Anything 产出知识图谱——文件、函数、类的节点和边。UML 把这些节点组织成有意义的模式——类图把散落的类型组织成领域模型，序列图把函数调用链组织成交互故事。知识图谱是原材料，UML 是成品。</p><p><strong>用途二：AI 生成代码的质量验证。</strong> AI 生成了 2000 行代码。你怎么知道架构没被写烂？生成一张类图——继承链有没有循环引用一目了然。生成一张包图——依赖方向有没有违反 Clean Architecture 的箭头规则。UML 就是 AI 代码的架构 X 光。</p><p><strong>用途三：团队沟通的通用语言。</strong> 不同的人看同一段 AI 代码，脑子里画的图可能完全不一样。UML 给了一套标准化的可视化符号，所有人坐下来看同一张图，对「这段代码长什么样」的理解不会差太远。</p><h2 id="14-6-insight-diagram：一键生成全套-UML-图的-Skill"><a href="#14-6-insight-diagram：一键生成全套-UML-图的-Skill" class="headerlink" title="14.6 insight-diagram：一键生成全套 UML 图的 Skill"></a>14.6 insight-diagram：一键生成全套 UML 图的 Skill</h2><p>前面聊了 17 种图。一个中等规模的项目，手工画完，单位是天。</p><p>insight-diagram 在 <a href="https://goal.rpcx.io/index_cn.html#step-diagram">goal.rpcx.io</a> 上发布，给任意代码库自动生成全套 UML 图、架构图和流程图。不需要你懂 UML——告诉它项目在哪，它分析代码库、让你选图表类型，然后一张张生成。</p><p><img src="/images/image-20260604090531683.png"></p><h3 id="14-6-1-核心理念：代码分析-→-图表选择-→-逐个生成"><a href="#14-6-1-核心理念：代码分析-→-图表选择-→-逐个生成" class="headerlink" title="14.6.1 核心理念：代码分析 → 图表选择 → 逐个生成"></a>14.6.1 核心理念：代码分析 → 图表选择 → 逐个生成</h3><p>四个步骤：</p><p><strong>步骤 1 — 分析代码库。</strong> Skill 读取项目的 <code>CLAUDE.md</code>（项目概览）、各子目录的 <code>CLAUDE.md</code>（模块细节），用 Glob 扫描源码文件结构，用 Grep 搜索关键模式（接口定义、函数签名、依赖注入）。提炼出组件清单、依赖关系图、核心类型、业务流程和部署拓扑。</p><p><strong>步骤 2 — 选择图表。</strong> 多选菜单，17 种图表分四组展示：结构性图形（类图、对象图、组件图、部署图、包图、复合结构图、剖面图）、行为性图形（用例图、活动图、状态机图）、交互图（序列图、通信图、定时图、交互概览图）、实用非 UML（系统架构图、流程图、泳道图）。默认推荐：architecture + sequence + flowchart。</p><p><strong>步骤 3 — 逐个生成。</strong> 每个图表的生成流程：</p><ol><li><strong>先读示例。</strong> Skill 内置 13 个示例 HTML 文件，每种图表类型一个。生成前从示例中提取布局策略（节点间距、分组方式、箭头走向）、节点样式层级（核心节点高亮、普通节点实线边框、可选节点虚线边框）、标注风格（阶段标签、Legend 图例、卡片摘要）和信息密度。</li><li><strong>整理元素和关系。</strong> 根据步骤 1 的分析结果，确定元素和关系。类图：10-15 个核心类型。序列图：2-5 个核心交互场景。每个图有明确关注重点，不追求全量覆盖。</li><li><strong>调用 architecture-diagram skill 渲染。</strong> 使用 Anthropic Claude 视觉风格（暖白背景 <code>#FAF9F6</code>、terracotta&#x2F;sage&#x2F;plum&#x2F;rose 配色、Inter 字体），输出 HTML+SVG。所有元素不得遮盖——箭头在节点下方、间距充足（垂直 ≥40px，水平 ≥30px）、文字不溢出。元素过多则拆分子图或缩小元素。</li><li><strong>保存到 <code>docs/</code> 目录。</strong> 文件命名如 <code>docs/architecture.html</code>、<code>docs/class.html</code>、<code>docs/sequence.html</code>。</li></ol><p><strong>步骤 4 — 报告。</strong> 全部生成完成后输出文件列表和每张图的简要描述。</p><h3 id="14-6-2-图表生成顺序：从宏观到微观"><a href="#14-6-2-图表生成顺序：从宏观到微观" class="headerlink" title="14.6.2 图表生成顺序：从宏观到微观"></a>14.6.2 图表生成顺序：从宏观到微观</h3><p>生成顺序是固定的，不是随机的：</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">architecture → component → deployment → package → composite-structure →</span><br><span class="line">profile → class → object → usecase → flowchart → activity → state-machine →</span><br><span class="line">swimlane → sequence → communication → timing → interaction-overview</span><br></pre></td></tr></table></figure><p>从架构图开始，逐步深入到组件、部署、包结构、类的内部结构，再到行为层面的用例、流程、状态、交互。每一步都踩在上一步提取的信息上——生成类图的时候，架构图和组件图已经把系统的主要模块和边界画出来了。</p><h3 id="14-6-3-关键设计决策"><a href="#14-6-3-关键设计决策" class="headerlink" title="14.6.3 关键设计决策"></a>14.6.3 关键设计决策</h3><p><strong>示例驱动，而非提示词驱动。</strong> Skill 不给 LLM 一段「画类图的提示词」——给示例 HTML 文件。LLM 从示例中提取布局模式、色彩方案、节点样式，用自己的内容替换。LLM 做「模仿已有模板然后替换内容」这件事远比做「根据纯文本描述从零生成视觉设计」靠谱。</p><p><strong>专用渲染 Skill 分离。</strong> insight-diagram 不做渲染——它调用 <code>/architecture-diagram</code>（另一个 Skill）生成 HTML+SVG。职责分离：insight-diagram 负责「分析代码、选择图表、整理元素」，architecture-diagram 负责「把元素渲染为 HTML+SVG」。这是 Skill 系统中的组合模式——一个 Skill 依赖另一个 Skill。</p><p><strong>防遮盖规则。</strong> SVG 元素不得互相遮盖。箭头绘制在节点下方（SVG 中先画箭头再画节点）。节点间最小间距 40px（垂直）、30px（水平）。文字不超出节点边界——超长截断或换行。这些规则在生成时强制检查，确保产出图表可直接用于文档和演示，跳过人工微调步骤。</p><p><strong>语言无关。</strong> 支持 Go、Python、TypeScript、Java、Rust 等主流语言。分析代码库使用 Glob + Grep + Read——不依赖语言特定解析器，对所有语言有基本覆盖。需要精确提取「所有类和它们的方法签名」的类图时，建议与 Understand-Anything（第 13 章）组合使用——Understand-Anything 提供精确的结构数据，insight-diagram 负责可视化。</p><h3 id="14-6-4-与-Understand-Anything-的配合"><a href="#14-6-4-与-Understand-Anything-的配合" class="headerlink" title="14.6.4 与 Understand-Anything 的配合"></a>14.6.4 与 Understand-Anything 的配合</h3><p>第 13 章和本章是互补关系：</p><table><thead><tr><th>维度</th><th>Understand-Anything</th><th>insight-diagram</th></tr></thead><tbody><tr><td>产出</td><td>知识图谱（JSON）</td><td>UML&#x2F;架构&#x2F;流程 图（HTML+SVG）</td></tr><tr><td>精度</td><td>确定性（Tree-sitter 解析）</td><td>LLM 推断（基于代码阅读）</td></tr><tr><td>用途</td><td>Agent 查询、影响分析、导航</td><td>人类阅读、文档、演示</td></tr><tr><td>目标读者</td><td>AI Agent</td><td>人类团队</td></tr><tr><td>更新方式</td><td>增量（commit hook 触发）</td><td>按需（手动触发重新生成）</td></tr></tbody></table><p>最佳实践：Understand-Anything 产出的知识图谱提供精确的组件清单和依赖关系，insight-diagram 把信息可视化为标准 UML 图形。确定性的结构数据 + LLM 的视觉表达——和 Understand-Anything 的 Tree-sitter + LLM 混合架构是同一设计哲学。</p><h3 id="14-6-5-在-agent-wrapper-上实战"><a href="#14-6-5-在-agent-wrapper-上实战" class="headerlink" title="14.6.5 在 agent-wrapper 上实战"></a>14.6.5 在 agent-wrapper 上实战</h3><p>实际上只生成了架构图、流程图和几个UML图就已经可以充分理解AI生成的代码了，这里我生成了所有的图片，主要是为了让你了解生成的各个图形的效果 。我更多会看架构图、流程图、类图、序列图、泳道图等。</p><p>有些生成的图形连线有些错误，图形有些重叠，你可以给智能体指出错误，让它修复，生成完美的图形。下面有些图生成的不是很完美，我也贴出来了，没有进一步优化。</p><p>agent-wrapper（<code>/Users/smallnest/ai/agent-wrapper</code>）是 Go 语言实现的 AI Agent 包装框架，核心功能包括 Agent 生命周期管理、Skill 注册与调度、Tool 调用链、LLM Provider 抽象和多轮对话状态机。项目包含 20+ 个 Go 源文件，分布在 <code>core/</code>、<code>tools/</code>、<code>plugins/</code>、<code>cli/</code> 等包中。</p><p>使用 insight-diagram 生成全套图表的过程：</p><ol><li><strong>调用 Skill。</strong> <code>/insight-diagram</code>，Skill 读取 <code>CLAUDE.md</code>、扫描源码结构、提取组件和接口。</li><li><strong>选择图表。</strong> 默认推荐三张图（architecture + sequence + flowchart），覆盖「系统怎么组织的、关键交互怎么发生、主流程怎么走」。</li><li><strong>逐个生成。</strong> Skill 依次读取对应示例、整理元素、调用 architecture-diagram 渲染、保存到 <code>docs/</code>。</li><li><strong>人工补充。</strong> 生成的图表作为基础版本，微调后补充到项目文档。</li></ol><h4 id="agent-wrapper-系统架构图（Architecture-Diagram）"><a href="#agent-wrapper-系统架构图（Architecture-Diagram）" class="headerlink" title="agent-wrapper 系统架构图（Architecture Diagram）"></a>agent-wrapper 系统架构图（Architecture Diagram）</h4><p><img src="/images/image-20260604091042656.png"></p><p>这张图把 agent-wrapper 的顶层结构摊开了。上边调用方（Go 代码或 CLI），中间是核心——Registry 管理 8 个 Provider、Orchestrator 驱动多轮对话循环、process 包管理子进程生命周期。下边 8 个 Agent CLI 进程（claude、codex、pi、opencode 等），每个独立子进程，通过 stdin&#x2F;stdout 与 wrapper 通信。</p><h4 id="agent-wrapper-类图（Class-Diagram）"><a href="#agent-wrapper-类图（Class-Diagram）" class="headerlink" title="agent-wrapper 类图（Class Diagram）"></a>agent-wrapper 类图（Class Diagram）</h4><p><img src="/images/image-20260604093527716.png"></p><p>五个核心类型。<code>Agent</code> 是顶层接口，只有 <code>Run()</code> — 接收 <code>RunInput</code>，输出 <code>&lt;-chan Event</code>。<code>Orchestrator</code> 持有 <code>Agent</code>，加 <code>ApprovalHandler</code>、<code>BudgetHandler</code>、<code>ContextCompressor</code> 三个钩子。<code>Registry</code> 用 <code>sync.RWMutex</code> 保护 map。<code>RunInput</code> 的 <code>SessionID</code>、<code>MaxTurns</code>、<code>OutputFormat</code> 决定每次调用的行为。<code>Event</code> 五种类型（TextDelta&#x2F;ToolCall&#x2F;ToolResult&#x2F;TurnEnd&#x2F;Error）覆盖 agent CLI 的所有输出。</p><h4 id="agent-wrapper-对象图（Object-Diagram）"><a href="#agent-wrapper-对象图（Object-Diagram）" class="headerlink" title="agent-wrapper 对象图（Object Diagram）"></a>agent-wrapper 对象图（Object Diagram）</h4><p><img src="/images/image-20260604094235636.png"></p><p>「用 Claude Code provider 创建并运行一个 Agent」那一瞬间的内存快照。<code>Registry</code> 里注册了 8 个 provider，<code>Get(&quot;claude-code&quot;)</code> 返回 <code>ClaudeCodeAgent</code> 实例。<code>Orchestrator</code> 持有这个 agent，默认 <code>ChainedCompressor</code>（SlidingWindow + Summary），3 次重试。<code>RunInput</code> 带着 prompt &quot;重构这个文件&quot;、<code>MaxTurns=10</code>、<code>OutputFormat=stream</code>。</p><h4 id="agent-wrapper-组件图（Component-Diagram）"><a href="#agent-wrapper-组件图（Component-Diagram）" class="headerlink" title="agent-wrapper 组件图（Component Diagram）"></a>agent-wrapper 组件图（Component Diagram）</h4><p><img src="/images/image-20260604095935699.png"></p><p>组件之间的契约关系。<code>Registry</code> 对外提供 <code>Register(name, Factory)</code> 和 <code>Get(name) Agent</code> 两个接口（棒棒糖），各 provider 包作为组件注册进来。<code>Orchestrator</code> 消费 <code>Agent</code> 接口，同时插 <code>ApprovalHandler</code> 和 <code>BudgetHandler</code> 两个插座。底层 <code>process.AgentProcess</code> 封装 <code>os/exec.Cmd</code>，提供 stdin&#x2F;stdout&#x2F;stderr 管道和优雅关闭（SIGTERM → 5s → SIGKILL）。</p><h4 id="agent-wrapper-部署图（Deployment-Diagram）"><a href="#agent-wrapper-部署图（Deployment-Diagram）" class="headerlink" title="agent-wrapper 部署图（Deployment Diagram）"></a>agent-wrapper 部署图（Deployment Diagram）</h4><p><img src="/images/image-20260604100230653.png"></p><p>代码到物理节点的映射。用户机器运行 CLI（<code>cmd/agent-wrapper</code> 二进制）， 运行 <code>Orchestrator.Run()</code>，启动 claude&#x2F;codex 等子进程。外部节点三个：Anthropic API（claude 后端）、OpenAI API（codex 后端）、Moonshot API（kimi-code 后端）。CLI → Orchestrator 是本地函数调用，Orchestrator → Agent CLI 是子进程 stdio，Agent CLI → 外部 API 是 HTTPS。</p><h4 id="agent-wrapper-包图（Package-Diagram）"><a href="#agent-wrapper-包图（Package-Diagram）" class="headerlink" title="agent-wrapper 包图（Package Diagram）"></a>agent-wrapper 包图（Package Diagram）</h4><p><img src="/images/image-20260604100303916.png"></p><p>顶层 <code>agentwrapper</code> 包入口，依赖 <code>types</code>、<code>harness</code>、<code>process</code>。<code>types/</code> 在最底层——<code>Agent</code> 接口、<code>Event</code>、<code>Message</code>、<code>RunInput</code>，所有其他包都依赖它。<code>harness/</code> 提供可插拔组件：<code>ApprovalHandler</code>、<code>BudgetHandler</code>、<code>ContextCompressor</code>。<code>process/</code> 封装子进程管理。<code>provider/</code> 是独立子树——八个包各自实现 <code>Agent</code> 接口。箭头方向符合 Clean Architecture：外层依赖内层，内层不依赖外层。</p><h4 id="agent-wrapper-复合结构图（Composite-Structure-Diagram）"><a href="#agent-wrapper-复合结构图（Composite-Structure-Diagram）" class="headerlink" title="agent-wrapper 复合结构图（Composite Structure Diagram）"></a>agent-wrapper 复合结构图（Composite Structure Diagram）</h4><p><img src="/images/image-20260604100505711.png"></p><p><code>Orchestrator</code> 的内部结构。四个 Parts：<code>Agent</code>（子进程驱动）、<code>ApprovalHandler</code>（工具审批）、<code>BudgetHandler</code>（token 预算）、<code>ContextCompressor</code>（上下文压缩重试）。<code>Run()</code> 通过 <code>runAgentWithRetry()</code> 端口调 Agent，Event Channel 经审批和预算检查后从 <code>out</code> 端口输出。关键：<code>agent.Run</code> 失败 → <code>IsContextLengthExceeded(err)</code> → <code>compressor.Compress()</code> → 重试最多 <code>maxRetries</code> 次（默认 3）。</p><h4 id="agent-wrapper-剖面图（Profile-Diagram）"><a href="#agent-wrapper-剖面图（Profile-Diagram）" class="headerlink" title="agent-wrapper 剖面图（Profile Diagram）"></a>agent-wrapper 剖面图（Profile Diagram）</h4><p><img src="/images/image-20260604101714963.png"></p><p>为 agent-wrapper 定义的三个自定义 Stereotype。<code>&lt;&lt;Provider&gt;&gt;</code>——实现 Agent 接口的子进程驱动类，含 <code>binary</code>、<code>protocol</code> 标签值。<code>&lt;&lt;Handler&gt;&gt;</code>——可插拔运行时钩子，含 <code>hook_point</code>、<code>is_async</code> 标签。<code>&lt;&lt;Event&gt;&gt;</code>——统一事件类型，含 <code>direction</code> 标签。在 <code>agent.go</code> 里写 <code>// @stereotype Provider binary=claude protocol=stream-json</code>，生成类图时自动识别特殊样式。</p><h4 id="agent-wrapper-流程图（Flowchart）"><a href="#agent-wrapper-流程图（Flowchart）" class="headerlink" title="agent-wrapper 流程图（Flowchart）"></a>agent-wrapper 流程图（Flowchart）</h4><p><img src="/images/image-20260604102024902.png"></p><p>从输入到输出的完整决策树。<code>Registry.Get(provider)</code> → 查表 → 未找到返回 <code>ErrNotRegistered</code>。找到则创建 Agent → <code>NewOrchestrator</code> 配 Approval&#x2F;Budget&#x2F;Compressor&#x2F;Retries。<code>orch.Run()</code> → 校验 prompt → <code>runAgentWithRetry()</code> 启子进程 → Scanner 解析 NDJSON → 每条事件过审批（allow&#x2F;deny&#x2F;abort）→ 过预算 → 输出。TurnEnd 检查 <code>stop_reason</code>，Context 超限触发压缩重试。</p><h4 id="agent-wrapper-用例图（Use-Case-Diagram）"><a href="#agent-wrapper-用例图（Use-Case-Diagram）" class="headerlink" title="agent-wrapper 用例图（Use Case Diagram）"></a>agent-wrapper 用例图（Use Case Diagram）</h4><p><img src="/images/image-20260604101840972.png"></p><p>这个图画的不清晰。</p><h4 id="agent-wrapper-活动图（Activity-Diagram）"><a href="#agent-wrapper-活动图（Activity-Diagram）" class="headerlink" title="agent-wrapper 活动图（Activity Diagram）"></a>agent-wrapper 活动图（Activity Diagram）</h4><p><img src="/images/image-20260604102238637.png"></p><p><code>Orchestrator.Run()</code> 的并发控制流。起始 → Fork 两条。主循环：eventCh 接收 → 分发审批&#x2F;预算&#x2F;转发 → TextDelta 直接转，ToolCall 走审批，TurnEnd 走预算。子进程监控：goroutine 监听 <code>ctx.Done()</code> → <code>terminate()</code>（SIGTERM → 5s → SIGKILL）。退出时 Join → <code>close(out)</code>。</p><h4 id="agent-wrapper-状态机图（State-Machine-Diagram）"><a href="#agent-wrapper-状态机图（State-Machine-Diagram）" class="headerlink" title="agent-wrapper 状态机图（State Machine Diagram）"></a>agent-wrapper 状态机图（State Machine Diagram）</h4><p><img src="/images/image-20260604102405183.png"></p><p><code>AgentProcess</code> 生命周期。<code>Idle</code> → <code>cmd.Start()</code> → <code>Running</code>。Running + <code>cmd.Wait()</code> → <code>Exited</code>（异常记 ExitCode）。Running + ctx 取消 → <code>Terminating</code> → SIGTERM → 5s 后 SIGKILL → <code>Killed</code>。<code>sync.Once</code> 保证 terminate 只跑一次。</p><h4 id="agent-wrapper-序列图（Sequence-Diagram）"><a href="#agent-wrapper-序列图（Sequence-Diagram）" class="headerlink" title="agent-wrapper 序列图（Sequence Diagram）"></a>agent-wrapper 序列图（Sequence Diagram）</h4><p><img src="/images/image-20260604102512785.png"></p><p><code>Orchestrator.RunSync()</code> 的时间线。<code>CLI</code> → <code>Registry.Get(&quot;claude-code&quot;)</code> → 返回 <code>ClaudeCodeAgent</code> → <code>NewOrchestrator</code> → <code>orch.RunSync()</code> → <code>agent.Run()</code> → <code>StartProcess()</code> 启动子进程 → NDJSON 到 stdout → Scanner 解析 → 首条 event 带 <code>session_id</code> → 逐条回 Orchestrator → TurnEnd → <code>RunResult{Text, Usage, SessionID}</code>。agent-wrapper 最核心调用链。</p><h4 id="agent-wrapper-通信图（Communication-Diagram）"><a href="#agent-wrapper-通信图（Communication-Diagram）" class="headerlink" title="agent-wrapper 通信图（Communication Diagram）"></a>agent-wrapper 通信图（Communication Diagram）</h4><p><img src="/images/image-20260604102722921.png"></p><p>同一批信息，视角换成「谁在跟谁通信」。<code>CLI</code>→<code>Registry</code>（1:Get）→<code>Orchestrator</code>（2:NewOrchestrator, 3:RunSync）→<code>ClaudeCodeAgent</code>（4:Run）→<code>AgentProcess</code>（5:Start）→<code>Anthropic API</code>（6:HTTPS）。反馈路径：API→Process→Scanner→Agent→Orchestrator channel→CLI。强调拓扑，不强调时间线。</p><p>图画的不好。</p><h4 id="agent-wrapper-定时图（Timing-Diagram）"><a href="#agent-wrapper-定时图（Timing-Diagram）" class="headerlink" title="agent-wrapper 定时图（Timing Diagram）"></a>agent-wrapper 定时图（Timing Diagram）</h4><p><img src="/images/image-20260604103316021.png"></p><p><code>Orchestrator.RunSync()</code> 的时间约束（ms）。0ms 开始，2ms Agent.Run，5ms Process running，10ms 流式输出，12ms API 请求，50ms TurnEnd，55ms 返回。约束：tool_call ≤ 30s、SIGTERM→SIGKILL &#x3D; 5s。检查长对话超时边界。</p><h4 id="agent-wrapper-交互概览图（Interaction-Overview-Diagram）"><a href="#agent-wrapper-交互概览图（Interaction-Overview-Diagram）" class="headerlink" title="agent-wrapper 交互概览图（Interaction Overview Diagram）"></a>agent-wrapper 交互概览图（Interaction Overview Diagram）</h4><p><img src="/images/image-20260604103110823.png"></p><p>活动图框架嵌入三个交互场景。判断「output format?」→ 三条分支：<code>stream</code>（sd OutputStream，实时输出）、<code>json</code>（sd OutputJSON，<code>Marshal(RunResult)</code> 单条）、<code>stream-json</code>（sd OutputStreamJSON，NDJSON 逐行）。汇聚到 exit。不展开细节，一眼看清分流逻辑。</p><h4 id="agent-wrapper-泳道图（Swimlane-Diagram）"><a href="#agent-wrapper-泳道图（Swimlane-Diagram）" class="headerlink" title="agent-wrapper 泳道图（Swimlane Diagram）"></a>agent-wrapper 泳道图（Swimlane Diagram）</h4><p><img src="/images/image-20260604102857112.png"></p><p>四泳道：User&#x2F;CLI、Orchestrator、Agent&#x2F;Provider、External LLM API。User：Registry.Get → RunInput → RunSync&#x2F;消费 events。Orchestrator：校验 prompt → runAgentWithRetry → processEvent（审批+预算）→ collect result。Agent：startSubprocess → parseNDJSON → emit events → wait exit。API：receive → generate → return tokens&#x2F;tool_calls。跨泳道标注协议：<code>via interface</code>、<code>via pipe</code>、<code>via HTTPS</code>。</p><h2 id="14-7-本章小结"><a href="#14-7-本章小结" class="headerlink" title="14.7 本章小结"></a>14.7 本章小结</h2><p>UML 十四种图加上三种实用扩展，覆盖软件系统的两个核心维度：结构（系统长什么样）和行为（系统怎么运行）。AI 开始生成代码之后，UML 从「前置设计工具」变成了「后置理解工具」——AI 写代码，图让人看得懂。</p><p>insight-diagram 把画图自动化了。一个 Skill，四步（分析代码 → 选择图表 → 逐图生成 → 报告），17 种图表。示例驱动的生成策略锁住了风格，防遮盖规则保证了产出直接能用。跟 Understand-Anything 配合，就是「确定性结构 + LLM 可视化」的完整链路。</p><p>本章为 agent-wrapper 预留的图表占位区，后续用 insight-diagram 生成全套图表后补充实际图片。</p><p>第 12 到 14 章连续过了三组 AI 编码辅助工具：官方插件、代码知识图谱、UML 可视化。下一章进代码重构——代码写完了，怎么让 AI 帮你把它改好。</p>