/insight-diagram

name: insight-diagram
description: 为任意项目生成 UML 图、架构图和流程图。分析代码库后让用户选择要生成的图表类型，使用 architecture-diagram skill 渲染为 HTML+SVG，保存到 docs/ 目录。适用于任何软件项目的文档可视化。

Insight Diagram — 项目图表生成技能

分析任意代码库，自动生成 UML 14种图 + 架构图 + 流程图，使用 `/architecture-diagram` 渲染为 HTML+SVG。

图表分类与清单

结构性图形 (Structural Diagrams — 静态)

描述系统的物理组成和静态结构。

| 编号 | 图表类型 | 英文标识 | 关注点 | |------|---------|---------|--------| | 1 | 系统架构图 | architecture | 组件关系、全局视角（非UML，最常用） | | 2 | 类图 | class | 定义类、属性、操作及关系 | | 3 | 对象图 | object | 特定时刻的对象实例及其关系 | | 4 | 组件图 | component | 系统组件及其依赖关系 | | 5 | 部署图 | deployment | 物理硬件、节点及软件部署 | | 6 | 包图 | package | 将模型元素分组组织 | | 7 | 复合结构图 | composite-structure | 类的内部结构 | | 8 | 剖面图 | profile | 扩展UML元模型、自定义构造型 |

行为性图形 (Behavioral Diagrams — 动态)

描述系统与外部参与者或系统内部的交互过程。

| 编号 | 图表类型 | 英文标识 | 关注点 | |------|---------|---------|--------| | 9 | 流程图 | flowchart | 主流程与分支（非UML，最常用） | | 10 | 用例图 | usecase | 从用户角度展示系统功能 | | 11 | 活动图 | activity | 过程的流程或步骤 | | 12 | 状态机图 | state-machine | 对象生命周期的状态变迁 | | 13 | 序列图 | sequence | 按时间顺序展示对象间交互 | | 14 | 通信图 | communication | 侧重于对象间的组织关系 | | 15 | 定时图 | timing | 侧重于状态变化的时间约束 | | 16 | 交互概览图 | interaction-overview | 结合活动图和时序图 | | 17 | 泳道图 | swimlane | 跨组件/角色职责流程（活动图变体） |

示例参考

本技能的 `examples/` 目录包含 13 个已完成的图表 HTML 文件，作为视觉样式和内容结构的参考模板。**生成任何图表前，必须先阅读对应的示例文件**，以确保风格一致、结构规范。

示例文件清单

| 文件 | 图表类型 | 英文标识 | |------|---------|---------| | `examples/architecture.html` | 系统架构图 | architecture | | `examples/class.html` | 类图 | class | | `examples/object.html` | 对象图 | object | | `examples/component.html` | 组件图 | component | | `examples/deployment.html` | 部署图 | deployment | | `examples/flowchart.html` | 流程图 | flowchart | | `examples/usecase.html` | 用例图 | usecase | | `examples/activity.html` | 活动图 | activity | | `examples/sequence.html` | 序列图 | sequence | | `examples/communication.html` | 通信图 | communication | | `examples/dfd.html` | 数据流图 | dfd | | `examples/interaction-overview.html` | 交互概览图 | interaction-overview | | `examples/swimlane.html` | 泳道图 | swimlane |

参考规则

1. **生成前必读**: 调用 `/architecture-diagram` 前，先用 Read 工具阅读对应类型的示例文件，从中提取：

• SVG 布局策略（节点间距、分组方式、箭头走向）
• 节点样式层级（核心节点 accent 高亮、普通节点实线边框、可选节点虚线边框）
• 标注风格（阶段标签、Legend 图例、卡片摘要）
• 信息密度（每个节点显示多少字段/属性）

2. **结构对齐**: 生成的图表应与示例保持相同的结构层次：

• 页面顶部：标题 + 副标题 + 图表类型说明
• 中间主体：SVG 图表区域（带浅色边框容器）
• 底部：信息摘要卡片 + 页脚

3. **内容替换而非照搬**: 示例中的业务数据（NovaShield 风控系统）是虚构的参考案例，生成时需替换为目标项目的真实架构信息。只参考布局和样式，不复制业务内容。

4. **无对应示例的类型**: 对于包图 (package)、复合结构图 (composite-structure)、剖面图 (profile)、状态机图 (state-machine)、定时图 (timing) 这 5 种没有示例文件的图表类型，参考最相近的已有示例（如包图参考组件图，状态机图参考活动图），并沿用相同的视觉语言。

执行流程

步骤 1：分析代码库

读取项目关键文件，提取架构信息：

1. 读取项目根目录的 `CLAUDE.md`（如存在）获取项目概览 2. 读取各子目录的 `CLAUDE.md`（如存在）获取模块细节 3. 用 Glob 扫描源码文件结构（`**/*.go`, `**/*.py`, `**/*.ts` 等） 4. 读取入口文件（`main.go`, `app.py`, `index.ts` 等）识别顶层组件 5. 用 Grep 搜索关键模式：接口定义、函数签名、依赖注入、配置项

从以上信息中提炼出：

• **组件清单**: 服务、模块、外部依赖
• **关系图**: 谁调用谁、谁依赖谁、数据流向
• **核心类型**: 结构体/类、接口、枚举
• **流程**: 主业务流程、异常处理流程
• **部署**: 进程、中间件、外部服务

步骤 2：选择图表

使用 AskUserQuestion 让用户选择要生成的图表（multiSelect: true），分4组展示：

**第1组 — 结构性图形（静态）：**

• 系统架构图 (architecture)
• 类图 (class)
• 对象图 (object)
• 组件图 (component)

**第2组 — 结构性图形续 + 部署：**

• 部署图 (deployment)
• 包图 (package)
• 复合结构图 (composite-structure)
• 剖面图 (profile)

**第3组 — 行为性图形（动态）：**

• 流程图 (flowchart)
• 用例图 (usecase)
• 活动图 (activity)
• 状态机图 (state-machine)

**第4组 — 交互图 + 常用非UML：**

• 序列图 (sequence)
• 通信图 (communication)
• 交互概览图 (interaction-overview)
• 泳道图 (swimlane)
• 全部生成 (all)

默认推荐：architecture + sequence + flowchart

步骤 3：逐个生成

对每个选中的图表类型：

1. **先读示例**: 用 Read 工具阅读 `examples/<标识>.html`（如 `examples/architecture.html`），提取布局模式、节点样式、标注方式 2. 根据步骤 1 提取的架构信息，整理出该图表应展示的元素和关系 3. 调用 `/architecture-diagram` skill，传入图表类型、标题、内容描述、输出路径，**必须指定 light 风格** 4. 输出文件保存到 `docs/<标识>.html`（如 `docs/architecture.html`） 5. **生成后必须 review**: 运行几何校验脚本，按结果修正后再继续下一张（见下方「步骤 3.5」） 6. 简要报告完成状态

**生成规则：**

• **风格**: 必须使用 light Claude 风格（暖白背景 #FAF9F6、terracotta/sage/plum/rose 配色、Inter 字体、白色卡片容器），与 Anthropic Claude 品牌视觉一致
• **防遮盖**: 所有 SVG 元素（节点、箭头、标签）不得互相遮盖。具体做法：
• 计算每个元素的边界框，确保无重叠
• 箭头绘制在节点下方（SVG 中先画箭头再画节点）
• 节点间留足间距（垂直最少 40px，水平最少 30px）
• 文字不超出所在节点边界，超长文字截断或换行
• 连接线的标签放置在线段中点偏移处，避免覆盖线段或节点
• 如果元素过多导致图表拥挤，拆分为多个子图或缩小元素尺寸

批量生成顺序（宏观→微观）： architecture → component → deployment → package → composite-structure → profile → class → object → usecase → flowchart → activity → state-machine → swimlane → sequence → communication → timing → interaction-overview

步骤 3.5：几何 review（每张图生成后必做）

生成的 SVG 常见三类几何缺陷，必须用脚本逐张校验并修正：

python3 skills/insight-diagram/scripts/review_svg.py docs/<标识>.html --min-gap 8
# 批量： python3 skills/insight-diagram/scripts/review_svg.py docs/*.html --min-gap 8

脚本检查（与三条核心要求一一对应）：

1. **箭头落点**：每个带箭头的端点必须恰好落在目标框/椭圆/菱形的**边缘线**上（容差 6px）。

• `ERROR 深入框内`：端点穿入框内部 >8px → 缩短连线，让它止于边缘。
• `WARNING 空接`：端点悬空、距最近框 >8px 且不汇入任何其它连线 → 把端点对齐到框边或汇合点。
• 合法情形：端点落在框边、生命线、或与另一条连线交汇（分支/汇聚）——脚本不会误报。

2. **框重叠**（`ERROR`）：非嵌套的两个框在水平、垂直两个方向都有交叠 → 必须移开其中一个。嵌套（一个完全包住另一个，如分组边界框包子节点）是允许的。 3. **框间距**（`WARNING`）：投影相邻的两框净间距 < `--min-gap`（默认 8px）→ 拉开距离。

处理原则：

• **ERROR 必须修复**后再进入下一张；修完重跑脚本确认归零。
• **WARNING 逐条核对**：序列图生命线底部的消息、泳道边界、紧贴的分组等可能是设计本意，确认无误可保留；其余应调整坐标。
• 修正方式是直接编辑 `docs/<标识>.html` 里对应的 `<rect>/<line>/<path>` 坐标，而非重新生成整张图。
• 退出码：有 ERROR 返回 1，干净返回 0；CI 中可加 `--strict` 让 WARNING 也阻断。

步骤 4：报告

全部完成后输出：

• 生成的文件列表
• 每个图表的简要描述

各图表的内容指南

系统架构图 (architecture) — 非UML，最常用

• 展示系统顶层组件及其连接关系
• 区分内部模块与外部依赖
• 标注核心数据流方向

类图 (class)

• 核心类型为类节点（名称+字段+方法）
• 继承、组合、依赖关系
• 接口与实现分离
• 限制在 10-15 个核心类型

对象图 (object)

• 选取一个典型运行时场景
• 展示对象实例及其属性值
• 对象间的链接关系

组件图 (component)

• 每个组件为一个节点
• 箭头表示依赖/调用方向
• 标注接口名称

部署图 (deployment)

• 物理节点（服务器、容器、Serverless）
• 中间件（消息队列、缓存、数据库）
• 外部服务（第三方 API）
• 标注通信协议

包图 (package)

• 按模块/命名空间分组
• 包间依赖关系
• 体现分层架构

复合结构图 (composite-structure)

• 类/组件的内部结构
• 部件(Part)与连接器(Connector)
• 端口(Port)与接口

剖面图 (profile)

• 自定义构造型(Stereotype)
• 扩展元模型的标签定义(Tagged Values)
• 领域特定建模约束

流程图 (flowchart) — 非UML，最常用

• 主流程 + 关键分支
• 失败/异常路径
• 起止节点清晰

用例图 (u