一、项目简介Archify 是一个开源的架构文档自动生成工具能够从代码库中自动提取项目结构、模块依赖关系并生成清晰的可视化架构图。它解决了开发团队在项目迭代过程中文档滞后、架构图手工绘制耗时且容易过时的问题。通过 Archify开发者可以将代码仓库直接转化为易于阅读的架构文档让新成员快速上手、让团队对系统全貌保持一致的认知。项目地址GitHub - tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence,>pip install archify方式二从源码安装git clone https://github.com/tt-a1i/archify.git cd archify pip install -e .安装完成后验证是否安装成功archify --version如果输出版本号说明安装成功。四、快速上手4.1 基本用法进入你的项目根目录执行以下命令即可生成架构图cd /path/to/your/project archify scan --output architecture.md执行后会在当前目录生成architecture.md文件其中包含 Mermaid 格式的架构图可以直接在 GitHub、GitLab 或支持 Mermaid 的编辑器中渲染查看。4.2 指定输出格式Archify 支持多种输出格式通过--format参数指定# 导出为 Mermaid 格式默认 archify scan --format mermaid --output arch.md 导出为 Graphviz DOT 格式 archify scan --format dot --output arch.dot 导出为 PNG 图片需要安装 Graphviz archify scan --format png --output arch.png4.3 自定义扫描范围通过--include和--exclude参数控制扫描范围# 只扫描 src 和 lib 目录排除测试和文档目录 archify scan --include src,lib --exclude tests,docs,node_modules五、配置文件详解在项目根目录创建archify.yaml配置文件可以实现更精细的控制# archify.yaml project: name: MyProject language: python # 可选python, javascript, java, go 等 scan: include: - src/ - lib/ exclude: - tests/ - node_modules/ - vendor/ - *.pyc output: format: mermaid # mermaid, dot, plantuml, png, svg path: ./docs/architecture.md max_depth: 5 # 依赖图最大深度 rules: max_cycle_depth: 3 # 循环依赖检测阈值 highlight_utils: true # 是否高亮工具类/通用模块使用配置文件执行扫描archify scan --config archify.yaml六、编程式 API 使用除了命令行Archify 也提供了 Python API方便集成到自动化脚本或 CI/CD 流水线中from archify import Scanner, Exporter 初始化扫描器 scanner Scanner( project_path./my-project, include[src/, lib/], exclude[tests/, node_modules/] ) 执行扫描获取架构数据 architecture scanner.scan() 打印模块依赖关系 print(f发现 {len(architecture.modules)} 个模块) print(f发现 {len(architecture.dependencies)} 条依赖关系) 导出为 Mermaid 格式 exporter Exporter(architecture) mermaid_code exporter.to_mermaid() with open(architecture.md, w) as f: f.write(mermaid\n) f.write(mermaid_code) f.write(\n) 导出为 PNG 图片 exporter.to_png(architecture.png)七、实战案例一个典型 Web 项目的架构分析7.1 项目背景假设我们有一个基于 Flask 的电子商务后端项目目录结构如下ecommerce/ ├── app/ │ ├── __init__.py │ ├── models/ │ │ ├── user.py │ │ ├── product.py │ │ └── order.py │ ├── services/ │ │ ├── user_service.py │ │ ├── product_service.py │ │ └── order_service.py │ ├── api/ │ │ ├── user_api.py │ │ ├── product_api.py │ │ └── order_api.py │ └── utils/ │ ├── validators.py │ └── helpers.py ├── config/ │ └── settings.py ├── tests/ │ └── test_services.py └── requirements.txt7.2 生成架构图在项目根目录执行archify scan --include app --exclude tests --format mermaid --output docs/architecture.md7.3 生成的架构图示例Archify 会自动分析各模块之间的 import 关系生成如下 Mermaid 架构图graph TD api_user[api/user_api.py] -- srv_user[services/user_service.py] api_user -- utils_val[utils/validators.py] api_product[api/product_api.py] -- srv_product[services/product_service.py] api_order[api/order_api.py] -- srv_order[services/order_service.py] srv_user -- model_user[models/user.py] srv_product -- model_product[models/product.py] srv_order -- model_order[models/order.py] srv_order -- model_user srv_order -- model_product srv_user -- utils_val srv_product -- utils_val srv_order -- utils_val model_user -- utils_help[utils/helpers.py] model_product -- utils_help model_order -- utils_help7.4 架构分析结果从生成的架构图中我们可以清晰看到分层清晰API 层 → 服务层 → 模型层依赖方向符合分层架构原则。工具类复用良好validators和helpers被多个模块引用适合作为通用工具库。order 模块耦合度较高order_service同时依赖了user和product两个模型这在业务上是合理的但需要关注后续是否会产生循环依赖。八、集成到 CI/CD 流水线8.1 GitHub Actions 集成示例将 Archify 集成到 CI 流程中在每次 Pull Request 时自动生成架构图确保架构变更可追溯# .github/workflows/archify.yml name: Generate Architecture Diagram on: pull_request: branches: [main] jobs: archify: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: 3.10 - name: Install Archify run: pip install archify - name: Generate Architecture Diagram run: archify scan --format png --output docs/architecture.png - name: Upload Architecture Diagram uses: actions/upload-artifactv3 with: name: architecture-diagram path: docs/architecture.png8.2 GitLab CI 集成示例# .gitlab-ci.yml archify: stage: build image: python:3.10 before_script: - apt-get update apt-get install -y graphviz - pip install archify script: - archify scan --format png --output docs/architecture.png artifacts: paths: - docs/architecture.png九、常见问题与排错9.1 扫描不到任何模块确认--include参数指向的目录存在且包含源代码文件。如果使用了配置文件检查scan.include路径是否正确。9.2 PNG 导出失败PNG 导出依赖 Graphviz请确保系统已安装# macOS brew install graphviz Ubuntu/Debian sudo apt-get install graphviz Windows 下载安装包https://graphviz.org/download/9.3 生成架构图过于复杂可以通过--max-depth参数限制依赖图深度或通过--exclude排除工具类、第三方库等非核心模块使架构图更加聚焦。9.4 循环依赖误报有时候__init__.py中的导入会被误判为循环依赖。可以在配置文件中调整rules.max_cycle_depth阈值或在exclude中排除__init__.py文件。十、总结与展望Archify 是一个轻量但实用的架构文档自动化工具能够有效降低团队维护架构文档的成本。它支持多种输出格式既可以作为命令行工具手动使用也可以无缝集成到 CI/CD 流水线中实现自动化。对于追求代码质量和文档规范的中大型项目来说Archify 是一个值得尝试的开源方案。未来Archify 社区计划支持更多语言如 Rust、Kotlin、更智能的模块分类算法以及更丰富的可视化样式定制。如果你对该项目感兴趣欢迎前往 GitHub 仓库点个 Star参与贡献或提出你的需求。项目地址GitHub - tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained HTML with motion and crisp export. · GitHub
一、项目简介Archify 是一个开源的架构文档自动生成工具能够从代码库中自动提取项目结构、模块依赖关系并生成清晰的可视化架构图。它解决了开发团队在项目迭代过程中文档滞后、架构图手工绘制耗时且容易过时的问题。通过 Archify开发者可以将代码仓库直接转化为易于阅读的架构文档让新成员快速上手、让团队对系统全貌保持一致的认知。项目地址GitHub - tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence,>pip install archify方式二从源码安装git clone https://github.com/tt-a1i/archify.git cd archify pip install -e .安装完成后验证是否安装成功archify --version如果输出版本号说明安装成功。四、快速上手4.1 基本用法进入你的项目根目录执行以下命令即可生成架构图cd /path/to/your/project archify scan --output architecture.md执行后会在当前目录生成architecture.md文件其中包含 Mermaid 格式的架构图可以直接在 GitHub、GitLab 或支持 Mermaid 的编辑器中渲染查看。4.2 指定输出格式Archify 支持多种输出格式通过--format参数指定# 导出为 Mermaid 格式默认 archify scan --format mermaid --output arch.md 导出为 Graphviz DOT 格式 archify scan --format dot --output arch.dot 导出为 PNG 图片需要安装 Graphviz archify scan --format png --output arch.png4.3 自定义扫描范围通过--include和--exclude参数控制扫描范围# 只扫描 src 和 lib 目录排除测试和文档目录 archify scan --include src,lib --exclude tests,docs,node_modules五、配置文件详解在项目根目录创建archify.yaml配置文件可以实现更精细的控制# archify.yaml project: name: MyProject language: python # 可选python, javascript, java, go 等 scan: include: - src/ - lib/ exclude: - tests/ - node_modules/ - vendor/ - *.pyc output: format: mermaid # mermaid, dot, plantuml, png, svg path: ./docs/architecture.md max_depth: 5 # 依赖图最大深度 rules: max_cycle_depth: 3 # 循环依赖检测阈值 highlight_utils: true # 是否高亮工具类/通用模块使用配置文件执行扫描archify scan --config archify.yaml六、编程式 API 使用除了命令行Archify 也提供了 Python API方便集成到自动化脚本或 CI/CD 流水线中from archify import Scanner, Exporter 初始化扫描器 scanner Scanner( project_path./my-project, include[src/, lib/], exclude[tests/, node_modules/] ) 执行扫描获取架构数据 architecture scanner.scan() 打印模块依赖关系 print(f发现 {len(architecture.modules)} 个模块) print(f发现 {len(architecture.dependencies)} 条依赖关系) 导出为 Mermaid 格式 exporter Exporter(architecture) mermaid_code exporter.to_mermaid() with open(architecture.md, w) as f: f.write(mermaid\n) f.write(mermaid_code) f.write(\n) 导出为 PNG 图片 exporter.to_png(architecture.png)七、实战案例一个典型 Web 项目的架构分析7.1 项目背景假设我们有一个基于 Flask 的电子商务后端项目目录结构如下ecommerce/ ├── app/ │ ├── __init__.py │ ├── models/ │ │ ├── user.py │ │ ├── product.py │ │ └── order.py │ ├── services/ │ │ ├── user_service.py │ │ ├── product_service.py │ │ └── order_service.py │ ├── api/ │ │ ├── user_api.py │ │ ├── product_api.py │ │ └── order_api.py │ └── utils/ │ ├── validators.py │ └── helpers.py ├── config/ │ └── settings.py ├── tests/ │ └── test_services.py └── requirements.txt7.2 生成架构图在项目根目录执行archify scan --include app --exclude tests --format mermaid --output docs/architecture.md7.3 生成的架构图示例Archify 会自动分析各模块之间的 import 关系生成如下 Mermaid 架构图graph TD api_user[api/user_api.py] -- srv_user[services/user_service.py] api_user -- utils_val[utils/validators.py] api_product[api/product_api.py] -- srv_product[services/product_service.py] api_order[api/order_api.py] -- srv_order[services/order_service.py] srv_user -- model_user[models/user.py] srv_product -- model_product[models/product.py] srv_order -- model_order[models/order.py] srv_order -- model_user srv_order -- model_product srv_user -- utils_val srv_product -- utils_val srv_order -- utils_val model_user -- utils_help[utils/helpers.py] model_product -- utils_help model_order -- utils_help7.4 架构分析结果从生成的架构图中我们可以清晰看到分层清晰API 层 → 服务层 → 模型层依赖方向符合分层架构原则。工具类复用良好validators和helpers被多个模块引用适合作为通用工具库。order 模块耦合度较高order_service同时依赖了user和product两个模型这在业务上是合理的但需要关注后续是否会产生循环依赖。八、集成到 CI/CD 流水线8.1 GitHub Actions 集成示例将 Archify 集成到 CI 流程中在每次 Pull Request 时自动生成架构图确保架构变更可追溯# .github/workflows/archify.yml name: Generate Architecture Diagram on: pull_request: branches: [main] jobs: archify: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: 3.10 - name: Install Archify run: pip install archify - name: Generate Architecture Diagram run: archify scan --format png --output docs/architecture.png - name: Upload Architecture Diagram uses: actions/upload-artifactv3 with: name: architecture-diagram path: docs/architecture.png8.2 GitLab CI 集成示例# .gitlab-ci.yml archify: stage: build image: python:3.10 before_script: - apt-get update apt-get install -y graphviz - pip install archify script: - archify scan --format png --output docs/architecture.png artifacts: paths: - docs/architecture.png九、常见问题与排错9.1 扫描不到任何模块确认--include参数指向的目录存在且包含源代码文件。如果使用了配置文件检查scan.include路径是否正确。9.2 PNG 导出失败PNG 导出依赖 Graphviz请确保系统已安装# macOS brew install graphviz Ubuntu/Debian sudo apt-get install graphviz Windows 下载安装包https://graphviz.org/download/9.3 生成架构图过于复杂可以通过--max-depth参数限制依赖图深度或通过--exclude排除工具类、第三方库等非核心模块使架构图更加聚焦。9.4 循环依赖误报有时候__init__.py中的导入会被误判为循环依赖。可以在配置文件中调整rules.max_cycle_depth阈值或在exclude中排除__init__.py文件。十、总结与展望Archify 是一个轻量但实用的架构文档自动化工具能够有效降低团队维护架构文档的成本。它支持多种输出格式既可以作为命令行工具手动使用也可以无缝集成到 CI/CD 流水线中实现自动化。对于追求代码质量和文档规范的中大型项目来说Archify 是一个值得尝试的开源方案。未来Archify 社区计划支持更多语言如 Rust、Kotlin、更智能的模块分类算法以及更丰富的可视化样式定制。如果你对该项目感兴趣欢迎前往 GitHub 仓库点个 Star参与贡献或提出你的需求。项目地址GitHub - tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained HTML with motion and crisp export. · GitHub
