usamaijazmughal/code-diagram
GitHub: usamaijazmughal/code-diagram
一款基于源码解析自动生成 Mermaid 架构图的 AI 辅助工具，用于可视化代码结构与依赖。
Stars: 0 | Forks: 0
# code-diagram
**v1.2.0** | [更新日志](#changelog)
支持 **Claude Code** | **Cursor** | **Gemini CLI** | ChatGPT（实验性）
## 快速开始
安装后重启工具。对于 Claude Code，输入 `/code-diagram` 并会自动补全。
## 输入模式与标志
```
/code-diagram lib/features/payments # directory
/code-diagram lib/auth/bloc.dart # single file
/code-diagram @auth_bloc.dart # @ reference
/code-diagram lib/auth/bloc.dart:10-50 class # line range
/code-diagram [lib/auth, lib/payments] sequence # multiple targets
/code-diagram lib/app sequence rich # show endpoints + operations
/code-diagram lib/app sequence max # shorthand
/code-diagram lib/app sequence effort=max # explicit (self-documenting)
/code-diagram lib/app sequence effort=max rich # exhaustive + endpoints
/code-diagram [lib/auth, lib/payments] effort=max # unlimited per target
```
| 输入模式 | 使用场景 |
|---|---|
| **目录** | 分析完整功能或模块 |
| **单个文件** | 聚焦单个文件的内部结构 |
| **行范围** `path:10-50` | 绘制特定方法或类块 |
| **多路径** `[a, b, c]` | 比较或连接多个功能 |
| **粘贴代码** | 从剪贴板代码快速生成示意图 |
| 标志 | 作用 | 默认值 |
|---|---|---|
| `rich` | 在示意图标签中显示端点、数据库实体和操作 | 关闭（仅方法名，安全） |
| `low` | 快速模式 — 10 次读取，5 跳追踪 | — |
| `medium` | 默认模式 — 20 次读取，12 跳追踪 | 默认 |
| `max` | 详尽模式 — 无读取上限，无限追踪，不自动分解拆分 | — |
抽象解析和混入跟踪**始终在所有努力级别激活** — 它们是正确性步骤，而非深度选项。
## 示意图类型
| 类型 | 命令 | 显示内容 |
|---|---|---|
| **类图** | `class` | 类、接口、继承、组合、依赖 |
| **序列图** | `sequence` | 执行流程：从入口点到外部 API 的各层 |
| **组件图** | `component` | 外部依赖：HTTP 端点、包、服务 |
| **架构图** | `arch` | 层边界与跨层关系 |
| **全部** | `all`（默认） | 以上四种示意图全部生成 |
每种示意图会根据检测到的范式自动适配：
| 范式 | `class` 变为 | `sequence` 变为 |
|---|---|---|
| 面向对象（OOP） | 类图 | 方法调用链 |
| 组件（React/Vue） | 组件树 | 数据流 |
| 函数式（Go/Express） | 模块映射 | 调用图 |
## 流模式
| 模式 | 行为 | 适用场景 |
|---|---|---|
| `full`（默认） | 每种类型生成一张统一示意图 | 文档说明、新人 onboarding |
| `split` | 多张聚焦示意图 | 大型功能、演示展示 |
```
/code-diagram lib/app class split # one diagram per layer
/code-diagram lib/app sequence split # one diagram per flow
```
## 支持的语言
| 语言 | 状态 | 范式 |
|---|---|---|
| Dart / Flutter | 已验证 | OOP |
| TypeScript / JavaScript | 已验证 | OOP、组件、函数式 |
| Java / Kotlin | 已验证 | OOP |
| Python | 已覆盖 | OOP、函数式 |
| Go | 已覆盖 | 函数式、结构化 |
| Swift | 已覆盖 | OOP |
| Rust | 已覆盖 | 结构化、特征基 |
| Vue / Angular / Svelte | 已覆盖 | 组件、混合 |
**已验证** = 在生产代码库中验证通过。**已覆盖** = 实现了对应模式，社区验证欢迎。
## 规模处理策略
| 规模 | 策略 |
|---|---|
| **1 个文件** | 直接读取，生成聚焦示意图 |
| **2–49 个文件** | 完整分析，最多 20 次读取（中等努力） |
| **50–99 个文件** | 先使用 grep 筛选，仅追踪快乐路径序列 |
| **100+ 个文件** | 按子目录自动分解，并生成整合示意图 |
| **多路径** | 每个项目按努力级别分配预算，交叉路径关系检测 |
使用努力级别控制深度。默认为 `medium`（经济实惠且适用于大多数场景）：
```
/code-diagram lib/features/payments max # unlimited reads, no auto-decompose split
/code-diagram lib/features/payments effort=max rich # exhaustive + show endpoints
/code-diagram [lib/auth, lib/payments] effort=max # exhaustive per target
```
## 工作原理
```
Discovery -> Paradigm -> Grep Scan -> Scoring -> Reading -> Diagrams -> Insights
(Glob) (3 probes) (2 passes) (Tier 1/2/3) (effort) (dark theme) (hotspots)
```
1. **Glob** 所有源文件，排除噪声（测试、生成、i18n）
2. **3 次 grep 探测** 分类范式：OOP / 组件 / 函数式 / 混合
3. **2 次批处理 grep 扫描** 按语言提取类、关系、HTTP 调用、导入、依赖注入
4. **层级评分** 使用结构信号识别基础文件（不依赖命名）
5. **选择性读取** — 仅读取 grep 无法解析的文件（低/中等努力最多 10–20 次，`max` 无限制）。组件与架构示意图**零次读取**
6. **Mermaid 输出** 启用深色主题，30 节点上限，`rect` 流程分隔
7. **洞察信息** — 热区、违规项、外部依赖、预算使用情况
## 成本基准测试
该工具旨在最小化 Token 使用。你可自行验证。
### 测试矩阵
在同一目录上运行，从最经济到最昂贵：
```
/code-diagram lib/features/payments component # zero reads (grep only)
/code-diagram lib/features/payments arch # zero reads (grep only)
/code-diagram lib/features/payments class # 3-8 reads
/code-diagram lib/features/payments sequence # 5-12 reads
/code-diagram lib/features/payments all # 8-18 reads
/code-diagram lib/features/payments all rich # same reads, richer labels
/code-diagram lib/features/payments all effort=max # exhaustive
/code-diagram lib/features/payments all max rich # exhaustive + endpoints
```
### 预期读取次数
| 示意图类型 | 预期读取次数 | 若更高则需调查 |
|---|---|---|
| `component` | **0** | 任何读取均为浪费 |
| `arch` | **0** | 任何读取均为浪费 |
| `class` | 3–8 | 超过 10 次为过读 |
| `sequence` | 5–12 | 超过 15 次为横向读取 |
| `all`（中等） | 10–18 | 超过 20 次为预算压力（中等努力） |
### 成本数据来源
每次运行会在末尾的**洞察信息**部分报告读取预算使用情况：
```
Read budget usage: 14 of 20 reads used (medium effort)
```
### 警告标志
- `component` 或 `arch` 触发文件读取（应为零）
- 序列链读取了调用链之外的兄弟文件
- 在 30 个文件以内达到预算上限（20 次中等努力）
- `rich` 标志增加读取次数（实际上它只改变标签，不增加读取）
- `medium` 努力使用超过 20 次读取
- 抽象类未解析为具体实现（应检查各层的 DI 绑定）
## 更新日志
### Claude Code（市场版）
```
/plugin update code-diagram
```
### Claude Code（手动安装）
```
curl -o ~/.claude/skills/code-diagram/SKILL.md \
https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/skills/code-diagram/SKILL.md
```
更新 Claude Code 后请重启。
### Cursor
```
curl -o .cursorrules \
https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/cursor/.cursorrules
```
### Gemini CLI
```
curl -o .gemini/commands/code-diagram.md \
https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/gemini/.gemini/commands/code-diagram.md
```
### 检查版本
版本信息位于插件元数据中：
- **Claude Code：**检查 `plugins/code-diagram/.claude-plugin/plugin.json` 或 `.claude-plugin/marketplace.json`
- **所有工具：**与 [GitHub 最新版本](https://github.com/usamaijazmughal/code-diagram/blob/main/plugins/code-diagram/.claude-plugin/plugin.json) 对比
当前版本：**1.2.0**
## 渲染位置
| 渲染器 | 方法 |
|---|---|
| [mermaid.live](https://mermaid.live) | 粘贴后即时渲染 |
| **GitHub** | 粘贴到任意 `.md` 文件、PR 或问题中 |
| **GitLab** | Markdown 中的原生 Mermaid |
| **Notion** | 使用 `mermaid` 语言的代码块 |
| **VS Code** | 安装 Mermaid 预览扩展 |
## 常见问题
## 仓库结构
```
code-diagram/
skills/code-diagram/SKILL.md # Claude Code (manual install)
plugins/code-diagram/ # Claude Code (marketplace install)
.claude-plugin/plugin.json
skills/code-diagram/SKILL.md
cursor/.cursorrules # Cursor
gemini/.gemini/commands/code-diagram.md # Gemini CLI
chatgpt/SYSTEM_PROMPT.md # ChatGPT (experimental)
.claude-plugin/marketplace.json # Marketplace registry
```
## 更新日志
### v1.2.0
- **简化努力级别：** `low`（10 次读取）、`medium`（20 次读取，默认）、`max`（无限制）。移除 `high`。
- **抽象解析 + 混入跟踪现在无条件激活** — 在**所有**努力级别（包括默认的 `medium`）中均生效。不再是 `high`/`max` 的专属功能。
- **无条件 5 步链追踪：** 读取 → 跟进 → 解析抽象 → 解析混入 → 重复。无条件、无 `if effort=high` 分支。LLM 可稳定跟随。
- 努力级别仅控制预算与跳数，**质量始终为最高**。
- `high` 与 `deep` 作为 `max` 的别名保留（向后兼容）。
- 通过更简洁的逻辑将代码量从约 994 行减少至约 920 行。
### v1.1.0
- **努力级别：** `low`、`medium`（默认）、`high`、`max` — 替代 `deep` 标志
- `high`/`max`：依赖注入注册表解析（GetIt、Hilt、Spring、NestJS）以跟踪抽象→具体
- `high`/`max`：继承搜索后备（在未找到 DI 绑定时 grep `extends AbstractClass`）
- `high`/`max`：混入/组合跟踪（Dart 的 `with`、Kotlin 的 `by`、Python 的多重继承）
- `max`：无读取上限，无限链追踪，不自动分解拆分，完整依赖图遍历
- 对无法解析的边界在示意图中明确标注
- 所有语言通用（Dart、Java、Kotlin、TypeScript、Python、Go、Swift、Rust）
- `deep` 作为 `high` 的别名保留（向后兼容）
### v1.0.2
- 详细级别提示：方法名（推荐、安全）vs 丰富细节（可选）
- 9 个外部操作类别：数据库、缓存、存储、队列、WebSocket、推送、认证、分析、gRPC
- 丰富模式：完整端点路径、`READ/WRITE entity` 表示数据库、紧凑操作表示其他所有
- 适用于所有示意图类型：序列图、类图、组件图、架构图
- 数据库安全：永不显示查询文本、列或模式
- 序列图参考表（15 步以上，仅丰富模式）
- 3 次批处理复合 grep（而非 9 次独立 grep）以提高成本效益
### v1.0.1
- 新增 5 种输入模式：行范围、多路径、粘贴代码、文件验证、@ 引用文档
- 多路径支持混合类型：`[directory, file, @ref, path:10-50]`
- 平衡/深度预算提示（用于自动分解和多路径）
- 跨路径关系检测（多路径模式）
- 所有输入模式的适用性矩阵
- 8 项关键/高级修复（预算冲突、正则表达式、解析、平台同步）
- 所有平台同步：Cursor、Gemini CLI、ChatGPT
### v1.0.0
- 初始发布：5 阶段流水线、4 种示意图类型、8 种语言、3 种范式
- 黑暗主题、grep 优先策略、结构评分、自动分解
- 移植到 Claude Code、Cursor、Gemini CLI、ChatGPT
## 许可证
MIT
由 [Muhammad Usama Ijaz](https://github.com/usamaijazmughal) 构建
| Claude Code | ``` /plugin marketplace add usamaijazmughal/code-diagram /plugin install code-diagram ``` 然后运行：`/code-diagram lib/features/payments` |
| Cursor | ``` curl -o .cursorrules https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/cursor/.cursorrules ``` 然后询问：*“Analyze lib/features/payments and generate diagrams”* |
| Gemini CLI | ``` mkdir -p .gemini/commands && curl -o .gemini/commands/code-diagram.md https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/gemini/.gemini/commands/code-diagram.md ``` 然后运行：`/code-diagram lib/features/payments` |
它会读取每个文件吗？
不会。它先对所有文件进行 grep（速度快），仅读取最重要的文件。默认（中等）最多读取 20 次。`max` 模式下无读取上限但仅追踪调用链。组件和架构示意图零次读取。如果基类不叫 "Base" 怎么办？
该工具使用结构信号而非命名约定。名为 `Payments` 且被 12 个文件扩展的类，优先级高于未被任何类扩展的 `BaseHelper`。能在单体仓库中使用吗？
可以，但请指向特定功能目录。或者使用多路径：`[packages/auth, packages/billing]`支持哪个 Mermaid 版本？
标准语法。`rect` 块需要 Mermaid 9.3+。深色主题需要 9+。避免使用 `namespace`（仅 Mermaid 10.3+ 支持）。输出示意图错误？
请提供：语言、范式、功能规模、问题描述，并提交 issue。标签：AI 工具, ChatGPT, Claude Code, Cursor, Gemini CLI, IPv6支持, JS文件枚举, Mermaid 图表, Promptflow, SEO: AI code diagram, SEO: AI powered UML, SEO: code to diagram, SEO: Mermaid generator, SEO: source code visualization, 代码分析, 代码可视化, 代码审查, 代码生成, 依赖图, 凭证管理, 可视化界面, 序列图, 开发效率, 技术文档, 插件, 数据可视化, 日志审计, 架构图, 流程图, 渗透测试工具, 网络可观测性, 自动化文档, 自文档化, 逆向工具