用途
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 格式输出分析结果
工作原理
- 扫描:递归遍历目录,跳过 node_modules、.git、pycache 等。
- 解析:Python 文件使用 ast 模块解析 import 与 from ... import;JS/TS 文件用正则匹配 import、require、export from;Go 与 Java 文件用正则匹配 import 语句。
- 解析内部依赖:将导入路径映射到项目内的实际文件。
- 生成图表:把依赖关系转换为 Mermaid 图语法。
- 渲染(可选):调用 mmdc(Mermaid CLI)把 .mmd 渲染为 SVG。
适用场景
- 快速理解陌生项目的模块结构
- 代码评审时可视化依赖关系
- 为技术文档制作架构图
- 检测循环依赖或过度耦合
- 重构前分析项目结构
依赖与限制
- 依赖 Python 3.7+(仅标准库,无需额外安装包)。
- SVG 输出需要 @mermaid-js/mermaid-cli(可选)。
- 只分析静态 import 关系,不追踪动态导入。
- 大型项目建议用 --max-files 限制扫描范围。
- 节点过多的 Mermaid 图可能难以渲染,可用 --type 分别生成。