saurabh-oss/archilens
GitHub: saurabh-oss/archilens
基于 AI 的 Git 仓库分层架构可视化工具，支持从系统上下文到运行时流程的多层级图表生成与架构漂移检测。
Stars: 1 | Forks: 0
# ArchiLens
**基于 AI 的分层架构与流程可视化工具，专为 Git 仓库设计。**
ArchiLens 会分析你的代码库并生成交互式的、层次化的架构图——从系统级上下文到 runtime 的 process flow。把它想象成**代码库的 Google Maps**：从大洲（系统架构）一路放大到城市（class 级别的组件）。
🌐 **网站**：https://saurabh-oss.github.io/archilens/
📦 **仓库**：https://github.com/saurabh-oss/archilens
## ArchiLens 的独特之处
| 功能 | Swark | GitDiagram | CodeBoarding | **ArchiLens** |
|---|---|---|---|---|
| 层次化下钻 (L0→L3) | ✗ | ✗ | 部分 | **✓** |
| Process flow / 时序图 | ✗ | ✗ | ✗ | **✓ (AI)** |
| GitHub 原生 (Action + PR 评论) | ✗ | ✗ | ✓ | **✓** |
| CI 中的架构漂移检测 | ✗ | ✗ | ✗ | **✓** |
| 业务能力映射 | ✗ | ✗ | ✗ | **✓** |
| Git 历史演变视图 | ✗ | ✗ | ✗ | **✓** |
| 多格式输出 (Mermaid/D2/PlantUML) | ✗ | ✗ | ✗ | **✓** |
| 多语言支持 | ✓ (LLM) | ✓ (LLM) | ✓ | **✓ (Tree-sitter)** |
| 交互式 Web 查看器 | ✗ | ✗ | ✗ | **✓** |
| 无需 API 密钥即可使用 | ✗ | ✗ | ✗ | **✓ (仅静态)** |
## 图表级别
```
L0: System Context ← Your system as a black box + external actors
L1: Module Architecture ← Major modules/services + dependencies
L2: Component Detail ← Classes, interfaces inside a module
L3: Process Flows ← Runtime request lifecycles (AI-inferred)
```
## 快速开始
### 前置条件
- Python 3.10+
- Git
- （可选）用于 AI 功能的 Anthropic API 密钥
### 安装
```
# 从 GitHub
pip install git+https://github.com/saurabh-oss/archilens.git
# 从源码（开发）
git clone https://github.com/saurabh-oss/archilens.git
cd archilens
python -m pip install -e ".[dev]"
```
### 在你的仓库中初始化
```
cd /path/to/your/repo
python -m archilens init
```
这会创建一个 `.archilens.yml` 配置文件。编辑它可以：
- 将模块映射到业务能力
- 为 process flow 追踪定义 entry point
- 为 L0 上下文图配置外部系统
- 设置用于 CI 强制执行的架构规则
### 生成图表
```
# 使用 AI 进行全面分析（需要 ANTHROPIC_API_KEY 环境变量）
python -m archilens analyze --repo .
# 仅静态分析（不需要 API key）
python -m archilens analyze --repo . --no-ai
# 仅生成特定级别
python -m archilens analyze --repo . --level 1
# 选择输出格式：mermaid（默认）、d2 或 plantuml
python -m archilens analyze --repo . --format d2
# 输出为 JSON（供程序化使用）
python -m archilens analyze --repo . --json-output > snapshot.json
```
### 交互式 Web 查看器
```
python -m archilens serve --repo . --port 8765
```
在 `http://localhost:8765` 打开一个深色主题的单页应用，具有：
- 跨越所有四个图表级别的侧边栏导航
- **点击 L1 图中的任何模块**，下钻查看其 L2 组件视图
- **缩放控制** (−/+/Fit/1:1)，**鼠标滚轮缩放**，以及**点击拖拽平移**
- 针对大型仓库的搜索/过滤侧边栏
- 无需重启服务器即可实时重新分析
### 架构漂移检测
```
# 将当前分支与 main 分支进行比较
python -m archilens diff --base main --head HEAD
# 将 diff 报告写入文件
python -m archilens diff --base v1.0 --head v2.0 --output drift.md
```
### 演变时间线
```
# 分析所有 semver tag 的架构
python -m archilens history --repo . --tags
# 分析特定 ref
python -m archilens history --repo . --refs "v1.0,v1.5,v2.0,HEAD"
```
生成 Mermaid 时间线图和一份完整的 Markdown 演变报告，展示你 git 历史中的模块添加、移除和 LOC（代码行数）趋势。
## 配置参考
`.archilens.yml` 文件控制所有的分析行为。
### 项目
```
project:
name: "My Application"
description: "What this system does"
type: "microservices" # monolith | microservices | modular-monolith | library
```
### 分析
```
analysis:
languages: ["python", "typescript"] # Auto-detected if omitted
entry_points:
- pattern: "**/*controller*.py"
type: "http_handler"
- pattern: "**/routes/**/*.ts"
type: "http_handler"
exclude:
- "**/node_modules/**"
- "**/__pycache__/**"
- "**/venv/**"
max_depth: 5
```
### 业务能力映射
```
capabilities:
- name: "Order Management"
description: "Order lifecycle from creation to fulfillment"
modules:
- "src/orders/**"
- "services/order-service/**"
- name: "Payment Processing"
modules:
- "src/payments/**"
```
### 外部系统
```
external_systems:
- name: "PostgreSQL"
type: "database"
description: "Primary data store"
- name: "Stripe API"
type: "external_api"
description: "Payment processing"
```
### 图表输出
```
diagrams:
output_dir: ".archilens/diagrams"
format: "mermaid" # mermaid | d2 | plantuml
levels:
- { level: 0, enabled: true }
- { level: 1, enabled: true }
- { level: 2, enabled: true }
- { level: 3, enabled: true }
```
### AI 配置
```
ai:
provider: "anthropic" # anthropic | openai | ollama | litellm
model: "claude-sonnet-4-6"
features:
process_flow_inference: true
node_annotations: true
capability_suggestions: true
pattern_detection: true
module_summaries: true
```
### CI 规则
```
ci:
drift_detection: true
pr_comments: true
rules:
- name: "no-layer-skip"
from: "src/presentation/**"
to: "src/infrastructure/**"
action: "warn"
- name: "max-fan-out"
threshold: 10
action: "fail"
```
## GitHub Actions 集成
将此工作流添加到你的仓库：
```
# .github/workflows/archilens.yml
name: Architecture Analysis
on:
push:
branches: [main]
pull_request:
branches: [main]
permissions:
contents: write
pull-requests: write
jobs:
architecture:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install git+https://github.com/saurabh-oss/archilens.git
- name: Generate Diagrams
if: github.event_name == 'push'
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: python -m archilens analyze --repo . --output .archilens/diagrams
- name: Commit Diagrams
if: github.event_name == 'push'
run: |
git config user.name "ArchiLens Bot"
git config user.email "archilens[bot]@users.noreply.github.com"
git add .archilens/diagrams/
git diff --cached --quiet || git commit -m "docs: update architecture diagrams [skip ci]"
git push
- name: PR Drift Detection
if: github.event_name == 'pull_request'
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: python -m archilens diff --base origin/${{ github.base_ref }} --head HEAD
```
## ArchiLens 自身的架构
```
archilens/
├── archilens/ # Core Python package
│ ├── __init__.py
│ ├── __main__.py # Enables python -m archilens
│ ├── cli.py # Click CLI with Rich output
│ ├── config.py # YAML config loader + defaults
│ ├── engine.py # Main orchestrator pipeline
│ ├── models/
│ │ └── __init__.py # Pydantic models (ArchSnapshot, nodes, edges, flows)
│ ├── analyzers/
│ │ ├── discovery.py # File discovery + language detection
│ │ ├── dependencies.py # Static analysis (imports, classes, call graph)
│ │ ├── treesitter.py # Tree-sitter AST extraction (Python/JS/TS/Java/Go)
│ │ ├── diff.py # Architecture diff engine
│ │ ├── evolution.py # Git history evolution & timeline
│ │ └── git_utils.py # Git ref checkout via blob reading
│ ├── generators/
│ │ ├── base.py # DiagramGenerator ABC + factory
│ │ ├── mermaid.py # Mermaid.js output (L0-L3)
│ │ ├── d2.py # D2 output (L0-L3)
│ │ └── plantuml.py # PlantUML output (L0-L3)
│ ├── viewer/
│ │ ├── __init__.py
│ │ └── app.py # Flask SPA with zoom/pan, drill-down
│ ├── ai/
│ │ └── __init__.py # LLM integration (Anthropic/OpenAI/Ollama)
│ └── utils/
│ └── __init__.py
├── docs/
│ └── index.html # GitHub Pages landing site
├── github_action/
│ └── action.yml # Composite GitHub Action
├── tests/
│ ├── test_core.py # Core analysis tests
│ └── test_new_features.py # Tree-sitter, generators, viewer, diff, evolution
├── .archilens.yml # Example configuration
├── .github/workflows/
│ └── archilens.yml # Example CI workflow
├── pyproject.toml # Project metadata + dependencies
└── README.md
```
### Pipeline 流程
```
.archilens.yml Source Code Git History
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────────────┐ ┌────────────┐
│ Config │ │ Discovery │ │ Git Utils │
│ Loader │ │ (Tree-sitter) │ │ (evolution │
└────┬─────┘ └───────┬──────────┘ │ + diff) │
│ │ └─────┬──────┘
▼ ▼ │
┌─────────────────────────────────────────────────────────┐
│ Analysis Engine │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ Static │ │ AI │ │ Metrics & │ │
│ │ Analysis │ │ Augmentation│ │ Patterns │ │
│ └──────┬──────┘ └──────┬───────┘ └───────┬───────┘ │
│ └────────┬────────┘──────────────────┘ │
└──────────────────┼──────────────────────────────────────┘
▼
┌──────────────┐
│ ArchSnapshot │ (Pydantic: nodes + edges + flows)
└──────┬───────┘
│
┌─────────────┼──────────────┐
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌──────────┐
│Mermaid │ │ D2 │ │ PlantUML │
│ (L0-3) │ │ (L0-3) │ │ (L0-3) │
└────┬────┘ └──────────┘ └──────────┘
│
▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Web │ │ Diff │ │ JSON │
│ Viewer │ │ Report │ │ Export │
└──────────┘ └──────────┘ └──────────┘
```
## 开发环境设置
```
# Clone 仓库
git clone https://github.com/saurabh-oss/archilens.git
cd archilens
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# .venv\Scripts\activate # Windows
# 安装 dev 依赖
python -m pip install -e ".[dev]"
# 运行测试
pytest tests/ -v --cov=archilens
# Lint
ruff check archilens/
mypy archilens/
```
## 路线图
- [x] 核心静态分析引擎（通过 Tree-sitter + regex 回退实现多语言支持）
- [x] L0-L3 Mermaid 图表生成
- [x] D2 和 PlantUML 输出格式
- [x] 基于 AI 的 process flow 推理和模块摘要
- [x] 架构漂移检测（带有 CI 规则的 diff 引擎）
- [x] Git 历史演变时间线（`archilens history`）
- [x] 用于 CI/CD 的 GitHub Action
- [x] 业务能力映射
- [x] 带有 Rich 输出的 CLI（`analyze`、`diff`、`history`、`serve`、`init`）
- [x] 具有缩放/平移和点击下钻功能的交互式 Web 查看器
- [x] GitHub Pages 落地页
- [ ] VS Code 扩展
- [ ] GitHub App（具有更丰富 PR 集成的持久化 bot）
- [ ] Monorepo 支持（多服务跨仓库分析）
- [ ] OpenTelemetry 集成（来自 trace 的 runtime 架构）
- [ ] PyPI 发布
## 许可证
MIT — 查看 [许可证](LICENSE)。
标签：SOC Prime, 人工智能, 代码分析, 代码可视化, 凭证管理, 开发工具, 架构图, 用户模式Hook绕过, 逆向工具