SuperAPI AI 工具集

code-to-diagram

编程与开发

查看项目

更新于 11-06 16:19

技能介绍

用途

code-to-diagram 从代码库中提取 import 与依赖关系,自动生成三类图示:

  • 架构图(Architecture Diagram):模块/目录级别的依赖关系
  • 流程图(Flowchart):文件级别的 import 调用链
  • 组织架构图(Org Chart):目录/文件层级结构

支持语言:Python、JavaScript、TypeScript、Go、Java。 输出格式:Mermaid 文本(.mmd)或 SVG 图片(需要系统安装 mmdc)。

主要能力

  • 递归扫描目录并解析源码中的导入语句,建立内部依赖映射。
  • 将依赖关系转换为 Mermaid 图语法,可选调用 Mermaid CLI 渲染为 SVG。
  • 支持只生成某一类图、指定输出目录、输出 JSON 分析结果。
  • 可通过参数限制扫描文件数与组织架构图深度,适配大型项目。

使用方式

分析整个项目:

python3 scripts/analyze_codebase.py /path/to/project

该命令把三张 Mermaid 图输出到标准输出,并将 .mmd 文件写入当前目录。

指定图表类型:

仅架构图

python3 scripts/analyze_codebase.py /path/to/project --type architecture

仅流程图

python3 scripts/analyze_codebase.py /path/to/project --type flowchart

仅组织架构图

python3 scripts/analyze_codebase.py /path/to/project --type org

指定输出目录与格式:

输出到指定目录

python3 scripts/analyze_codebase.py /path/to/project --output /tmp/diagrams

输出 SVG(需要 mmdc)

python3 scripts/analyze_codebase.py /path/to/project --format svg

同时输出 Mermaid 与 SVG

python3 scripts/analyze_codebase.py /path/to/project --format both

输出 JSON 分析结果:

python3 scripts/analyze_codebase.py /path/to/project --json

参数说明:

  • directory:要分析的代码目录(必填)
  • --type, -t:图表类型,architecture、flowchart、org、all(默认 all)
  • --output, -o:输出目录(默认当前目录)
  • --format, -f:输出格式,mermaid、svg、both(默认 mermaid)
  • --max-files:最大扫描文件数(默认 500)
  • --max-depth:组织架构图最大深度(默认 4)
  • --json:以 JSON 格式输出分析结果

工作原理

  1. 扫描:递归遍历目录,跳过 node_modules、.git、pycache 等。
  2. 解析:Python 文件使用 ast 模块解析 import 与 from ... import;JS/TS 文件用正则匹配 import、require、export from;Go 与 Java 文件用正则匹配 import 语句。
  3. 解析内部依赖:将导入路径映射到项目内的实际文件。
  4. 生成图表:把依赖关系转换为 Mermaid 图语法。
  5. 渲染(可选):调用 mmdc(Mermaid CLI)把 .mmd 渲染为 SVG。

适用场景

  • 快速理解陌生项目的模块结构
  • 代码评审时可视化依赖关系
  • 为技术文档制作架构图
  • 检测循环依赖或过度耦合
  • 重构前分析项目结构

依赖与限制

  • 依赖 Python 3.7+(仅标准库,无需额外安装包)。
  • SVG 输出需要 @mermaid-js/mermaid-cli(可选)。
  • 只分析静态 import 关系,不追踪动态导入。
  • 大型项目建议用 --max-files 限制扫描范围。
  • 节点过多的 Mermaid 图可能难以渲染,可用 --type 分别生成。