DepArchitect

Deterministic Dependency Governance with Optional AI / Multi-Agent Copilot for Python Projects

DepArchitect 是一个面向 Python 项目的依赖架构审查与治理工具。它先通过确定性静态分析回答依赖健康、模块耦合、新增依赖合理性和关键依赖升级风险，再在其上叠加可选 AI / multi-agent copilot 做解释、建议和交互引导。

项目目标不是做一个普通的 dependency updater，也不是把所有判断交给 AI，而是构建一个 Static Analysis First + Optional AI / Agent Copilot Layer 的工程化依赖治理工具。

本项目是一个vibe coding项目，可以当作学习vibe coding的一个实战案例，或者当作一个独立的开源项目来使用。 项目采用的是opencode+omo-slim+openspec的开发流程和规范，具体会在docs文档中展示。

---

核心价值

传统依赖工具通常关注：

• 哪些依赖过期了
• 哪些包存在安全漏洞
• 哪些依赖没有被使用

DepArchitect 更关注架构层面的依赖问题：

• 当前项目的依赖结构是否健康
• 依赖链是否过深、是否引入过多传递依赖
• 是否存在内部循环 import 或模块耦合问题
• 是否有多个依赖在解决同一类问题
• 新增一个依赖是否真的有必要
• 已有依赖是否已经能完成新功能
• 升级关键依赖会影响哪些代码
• 升级前是否需要先补测试

---

主要功能

1. Dependency Health Scan

分析 Python 项目的依赖健康度。

deparch scan .
deparch scan . --format html --output deparch-report.html

检查内容包括：

• 直接依赖数量
• 传递依赖数量
• 最大依赖深度
• 最深依赖链
• 未使用依赖
• 重复能力依赖
• 重型依赖
• 过时依赖
• license 风险
• 依赖健康评分

---

2. Internal Dependency / Circular Import Analysis

分析项目内部 Python 模块之间的 import 关系，发现循环依赖和高耦合模块。

deparch cycles .
deparch cycles . --format html

检查内容包括：

• Python 文件 import 图
• 内部模块依赖图
• 循环 import
• 高 fan-in / fan-out 模块
• 架构层级违规
• HTML 交互报告（import 图可视化 + 循环高亮 + 耦合热力图）

---

3. Dependency Addition Review

在新增依赖前，判断候选依赖是否真的必要，以及是否符合项目现有架构和技术风格。

deparch review-add \
  --feature "export invoice as PDF" \
  --candidate weasyprint

分析维度包括：

• 新功能需要什么能力
• 项目已有依赖是否已经能完成
• 新依赖会引入多少传递依赖
• 是否存在 native dependency
• license 是否合适
• 维护活跃度如何
• 是否和现有依赖能力重复
• 是否符合项目 policy
• 是否存在更轻量替代方案

---

4. Dependency Upgrade Risk Review

判断某个关键依赖升级是否安全、会影响哪些代码，以及升级前是否需要补测试。

deparch review-upgrade pydantic==2.7.0

MVP 优先深做：

• Pydantic v1 → v2

后续扩展：

• FastAPI old → new
• SQLAlchemy 1.4 → 2.x
• Django 3.x → 4.x / 5.x

---

快速开始

安装

# 克隆仓库
git clone https://github.com/buffer121328/DepArchitect.git
cd DepArchitect

# 创建虚拟环境并安装
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

基本使用

# 扫描项目依赖健康度
deparch scan 项目目录

# 检测循环依赖
deparch cycles 项目目录

# 指定输出格式
deparch scan 项目目录 --format json
deparch cycles 项目目录 --format html

# 输出到文件
deparch scan 项目目录 --format html --output report.html
deparch cycles 项目目录 --format html --output cycles-report.html

生成的 HTML 报告默认保存在目标项目的 .deparch/reports/ 目录下：

.deparch/reports/
  index.html          # 报告入口
  _shared/            # 共享资源
    app.css
    app.js
  scan/
    index.html        # 依赖扫描报告
  cycles/
    index.html        # 循环依赖报告

用浏览器打开 index.html 即可查看交互式报告。

---

技术架构

整体采用：

Static Analysis First + Optional AI / Agent Copilot Layer

核心原则：

• 确定性分析由规则、AST、依赖图和静态扫描完成
• AI / agent 不负责基础扫描，只消费结构化 evidence / report
• 所有评分和判断都应尽可能可追溯、可解释
• AI / agent 不能生成 finding、修改 score 或覆盖规则决策

CLI
 ↓
Project Loader
 ↓
Static Analysis Engine
 ├─ Dependency Parser
 ├─ Import Graph Analyzer
 ├─ Cycle Detector
 ├─ Unused Dependency Detector
 ├─ Capability Duplicate Detector
 └─ Upgrade Usage Scanner
 ↓
Dependency Intelligence Engine
 ├─ Capability Registry
 ├─ Compatibility Matrix
 ├─ Breaking Change Rules
 ├─ Policy Engine
 └─ Risk Scoring Engine
 ↓
Deterministic Report / Evidence
 ↓
Optional AI / Agent Copilot Layer
 ├─ Suggest Agents
 ├─ Review Add Specialists
 ├─ Review Upgrade Specialists
 ├─ Critic
 └─ Synthesizer
 ↓
Report Generator

phase1展示如下：

统一 HTML 报告目录：

.deparch/reports/
  index.html
  _shared/
    app.css
    app.js
  scan/
    index.html
  cycles/
    index.html      # phase 2 done
  score/
    index.html      # future
  review-add/
    index.html      # future
  review-upgrade/
    index.html      # future

---

技术栈

基础技术

• Python 3.11+
• Typer / Click：CLI
• Rich：终端美化输出
• Pydantic：数据模型
• tomllib / tomlkit：解析 pyproject
• packaging：版本和 specifier 解析
• pipdeptree：依赖树
• importlib.metadata：包元数据
• ast：解析 Python import
• networkx：依赖图分析
• pytest-cov：测试覆盖率

AI 相关

• 原生 Python + asyncio：轻量 orchestrator
• OpenAI / DeepSeek / Qwen：provider SDK / 模型层
• Pydantic structured output：结构化输出
• Mock provider：无网络测试

可选扩展

• libcst：后续做自动 patch
• GitPython：GitHub repo 分析
• FastAPI：后续做 API 服务
• SQLite：缓存扫描结果

---

当前输出格式

• --format console
• --format json
• --format html

HTML 说明：

• deparch scan PATH --format html 会默认写入项目下的 .deparch/reports/
• scan 页面支持导航切换、依赖搜索、节点详情、线颜色图例、返回上一步和由简入繁的图展开
• JS 只负责交互增强，不参与任何分析或评分计算

后续统一扩展：

• markdown
• pdf（作为 HTML 的派生输出）

---

开发路线与时间安排

当前已完成：

• ✅ Phase 0：项目准备（CLI 框架、基础设施）
• ✅ Phase 1：依赖解析与图构建，HTML 交互报告
• ✅ Phase 2：内部 import 图与循环依赖检测 (deparch cycles)
• 🔄 各阶段测试与优化中

本月（6月）推进计划

Phase	时间	目标	状态
Phase 2	6/1-6/5	循环依赖检测 (deparch cycles)	✅ 已完成
Phase 3	6/5-6/8	未使用依赖检测	📋 规划中
Phase 4	6/8-6/11	重复能力依赖检测	📋 规划中
Phase 5	6/11-6/13	依赖健康评分模型	📋 规划中
Phase 6	6/13-6/16	新增依赖评审 (review-add)	📋 规划中
Phase 7	6/16-6/21	Pydantic 升级风险评审	📋 规划中
Phase 8	6/21-6/24	统一报告系统	📋 规划中
Phase 9	6/24-6/28	Demo 项目与完整 README	📋 规划中
总计	6/1-6/28	4 周内完成 MVP	🎯

关键路径

Phase 0 → Phase 1 ✅ ├→ Phase 2 (循环检测) └→ Phase 3 (未使用) ↓ Phase 4-5 (评分) ↓ Phase 6-7 (评审) ↓ Phase 8 (报告) ↓ Phase 9 (Demo) ← 6月底交付

交付成果

本月底完成：

✅ deparch scan examples/demo-shop-api
✅ deparch cycles examples/demo-shop-api
✅ deparch review-add examples/demo-shop-api --feature "..." --candidate "..."
✅ deparch review-upgrade examples/demo-shop-api pydantic==2.7.0
✅ 完整 HTML / JSON / Markdown 报告
✅ demo 项目 + README 展示

### 交付成果

本月底完成：

```bash
✅ deparch scan examples/demo-shop-api
✅ deparch cycles examples/demo-shop-api
✅ deparch review-add examples/demo-shop-api --feature "..." --candidate "..."
✅ deparch review-upgrade examples/demo-shop-api pydantic==2.7.0
✅ 完整 HTML / JSON / Markdown 报告
✅ demo 项目 + README 展示