BlackBean/pigo/internal/builtinskills/skills/insight-diagram/SKILL.md

name, description

name	description
insight-diagram	为任意项目生成 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，最常用

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

用例图 (usecase)

• 参与者（人/外部系统）
• 用例椭圆
• include/extend 关系

活动图 (activity)

• 阶段/步骤为活动节点
• 并行分支用 fork/join
• 决策点用菱形

状态机图 (state-machine)

• 对象的关键状态
• 触发状态变迁的事件
• 动作/守卫条件
• 初始态和终态

序列图 (sequence)

• 参与者为纵向生命线
• 水平箭头为消息调用
• 标注关键返回值
• 关注 2-5 个核心交互场景

通信图 (communication)

• 组件为节点，消息为连线
• 标注消息序号
• 强调协作关系而非时序

定时图 (timing)

• 时间轴横向展开
• 状态变化的时间约束
• 持续时间标注

交互概览图 (interaction-overview)

• 控制流节点内嵌交互片段
• 展示条件分支和循环
• 宏观概览各交互场景

泳道图 (swimlane) — 活动图变体

• 按组件/角色分泳道
• 流程步骤在对应泳道内
• 跨泳道箭头表示交互