NullLabTests/archiscape

# Archiscape **借助 AI 驱动的分层分类、社区发现和耦合分析，将任何 Python 代码库逆向工程为交互式架构知识图谱。** Archiscape 是一个用于**实证软件工程研究**的静态分析框架。它在 AST 级别读取 Python 源代码，并重建其隐式架构——模块、类、函数及其依赖关系和语义角色——然后将其渲染为可探索的产出物：交互式 D3.js 力导向图、结构化的 Markdown 文档以及机器可读的 JSON。 传统的文档工具需要人工维护，而 UML 逆向工程器只能生成静态图表。与此不同，Archiscape 将架构视为一个**一阶分析对象**：可度量、可跨版本比较，并且适用于统计和图论分析。 ## 研究应用 Archiscape 旨在支持以下几个研究方向： - **架构演进追踪** — 跨 git 历史快照运行 Archiscape，以量化耦合、模块化和层次结构随时间的变化。 - **实证代码库比较** — 跨项目、团队或组织比较架构指标（密度、枢纽分布、社区结构、层级比例）。 - **设计模式挖掘** — 使用增强图（装饰器、继承、命名规范）来检测并对重复出现的架构模式进行分类。 - **技术债量化** — 将具有高扇入（传入耦合）和低文档覆盖率的枢纽组件识别为结构性技术债候选者。 - **新手入门与认知** — 为程序理解研究生成分层架构图；衡量自动检测到的层次与开发人员心智模型的匹配程度。 - **LLM 作为评判者的架构分类** — 本仓库包含一个可选的基于 LLM 的层次分类器，它使用 GPT-4o-mini 对组件进行语义标记，为研究 LLM 能在多大程度上从代码中恢复架构意图提供了一种可复现的方法。 ## 功能 | 功能 | 实现 | |---|---| | **AST 提取** | 完整的 Python AST 遍历 — 模块、类、函数、async def、装饰器、类属性、import 语句（标准库 vs 第三方） | | **依赖图** | 带有类型化边（`imports`，`contains`）的 NetworkX `DiGraph` | | **层次检测（启发式）** | 基于组件名称 + 文件路径关键字评分的 8 层本体 | | **层次检测 (LLM)** | 通过兼容 OpenAI 的 API 使用可选的 GPT-4o-mini 分类器；设置 `ARCHISCAPE_LLM_KEY` 或传递 `--llm-key` | | **社区发现** | 在无向投影图上进行贪婪模块度优化 | | **耦合指标** | 每个组件的扇入、扇出、度中心性；整体图密度 | | **枢纽识别** | 按总连接度排名的 Top-N 组件 | | **交互式可视化** | 独立的 HTML（D3.js 力导向图、侧边栏详情面板、实时搜索、缩放/平移/拖拽） | | **动态文档** | 包含层次表、耦合矩阵、枢纽列表和组件树的 `ARCHITECTURE.md` | | **机器可读导出** | JSON 导出，用于在 notebook 或自动化 pipeline 中进行下游分析 | ## 快速入门 ``` pip install -e /path/to/archiscape # 快速摘要 archiscape summary /path/to/project # 完整报告（Markdown + 交互式 HTML） archiscape doc /path/to/project # 使用基于 LLM 的层分类 ARCHISCAPE_LLM_KEY="sk-..." archiscape doc /path/to/project --llm-model gpt-4o-mini # 原始数据导出 archiscape scan /path/to/project -o architecture.json ``` ### 解读输出结果 - **`ARCHITECTURE.md`** — 层次分布显示了每个架构层级中组件的比例。枢纽表标识了耦合度最高的模块（高维护风险）。耦合指标（扇入/扇出）在项目级别量化了传入与传出耦合。 - **`architecture.html`** — 按层次进行颜色编码。较大的节点代表模块。点击任意节点查看详情。搜索可过滤图表。侧边栏显示社区计数和枢纽排名。 - **`architecture.json`** — 包含每个节点的 import、装饰器、属性和层次分配的完整实体树。 ## 示例：自我分析 在其自身的代码库上运行 `archiscape doc`： ``` ╭──────────────────────────────────────────────────────────────────────────────╮ │ Archiscape v0.1.0 — Architecture Report │ │ /home/user/archiscape │ │ │ │ Components: 34 Dependencies: 28 Density: 0.025 Communities: 3 │ ╰──────────────────────────────────────────────────────────────────────────────╯ Architectural Layers Layer Components Proportion ─────────────────────────────────────── Analysis 21 62% Rendering 6 18% Presentation 6 18% Other 1 3% Most Connected Components (Hubs) archiscape.analyzer 13 edges fan-in:3 fan-out:10 analysis archiscape.cli 10 edges fan-in:0 fan-out:10 presentation archiscape.graph 5 edges fan-in:2 fan-out:3 analysis ``` ## 工作原理 ``` Source code (*.py) │ ▼ ┌─────────────────────┐ │ AST Walker │ Python ast module → CodeEntity tree │ (analyzer.py) │ (modules, classes, functions, imports, └─────────┬───────────┘ decorators, attributes, docstrings) │ ▼ ┌─────────────────────┐ │ Graph Constructor │ NetworkX DiGraph │ (graph.py) │ • typed edges (imports / contains) └─────────┬───────────┘ • layer detection (heuristic + optional LLM) │ • community detection (greedy modularity) │ • coupling metrics (fan-in/out, density, hubs) │ ▼ ┌─────────────────────┐ │ Renderers │ │ • markdown.py │ → ARCHITECTURE.md │ • html.py │ → architecture.html (D3.js) │ • CLI (json dump) │ → architecture.json └─────────────────────┘ ``` ### 层次本体（启发式） | 层级 | 关键字 | |---|---| | 表现层 (Presentation) | cli, ui, view, controller, handler, routes, web, app | | 应用层 (Application) | service, use_case, orchestrator, manager, pipeline, workflow | | 领域层 (Domain) | model, entity, domain, core, engine, schema | | 基础设施层 (Infrastructure) | db, repository, storage, cache, queue, io, network | | 分析层 (Analysis) | parser, analyzer, scanner, extractor, graph, visitor | | 渲染层 (Rendering) | renderer, template, html, markdown, format, serialize | | 配置层 (Config) | config, settings, constants, env, flags | | 工具层 (Utility) | util, helper, tool, common, base, mixin | 当提供 `--llm-key` 时，只要 LLM 返回标签，启发式分类就会被 GPT-4o-mini 的判断所取代，从而将关键字匹配的速度与语言模型的语义灵活性结合起来。 ## 项目结构 ``` archiscape/ ├── archiscape/ │ ├── __init__.py │ ├── __main__.py │ ├── analyzer.py # AST walker → CodeEntity tree │ ├── graph.py # graph construction, metrics, LLM classifier │ ├── cli.py # typer CLI (scan / doc / summary) │ └── renderers/ │ ├── __init__.py │ ├── templates/ │ │ └── architecture.html.j2 # Jinja2 template │ ├── html.py # D3.js visualization generator │ └── markdown.py # Markdown doc generator ├── examples/ # sample output from real codebases ├── pyproject.toml ├── CITATION.cff ├── LICENSE └── README.md ``` ## 与相关工具的比较 | 工具 | 侧重点 | 代码库依赖 | 图表可视化 | 层次检测 | 社区发现 | 耦合指标 | LLM 增强 | |---|---|---|---|---|---|---|---| | **Archiscape** | 架构智能 | 静态 (AST) | 交互式 D3.js | 启发式 + 可选 LLM | 是 | 扇入/出、密度、枢纽 | 是 | | pydeps | 依赖可视化 | 静态 (import) | 静态 dot 图 | 否 | 否 | 否 | 否 | | pyreverse (pylint) | UML 类图 | 静态 | 静态 dot/plantuml | 否 | 否 | 否 | 否 | | code2flow | 调用图 | 静态/动态 | 静态图 | 否 | 否 | 否 | 否 | | deply | 架构验证 | 静态 | 基于规则 | 手动标记 | 否 | 否 | 否 | | Structure101 | 架构分析 | 静态 | 分层 | 手动 | 否 | 是 | 否 | Archiscape 的独特之处在于，它在一个专为开发工作流和软件工程研究设计的开源工具中，结合了 **AST 级别的提取**、**可选的基于 LLM 的语义分类**、**图论指标**以及**交互式可视化**。 ## 环境要求 - Python ≥ 3.10 - typer, rich, networkx, jinja2（可通过 pip 安装） ## 引用 如果您在研究中使用 Archiscape，请引用： ``` @software{archiscape2026, author = {NullLabTests}, title = {Archiscape: AI-Powered Codebase Architecture Intelligence}, year = {2026}, url = {https://github.com/NullLabTests/archiscape} } ``` 仓库中包含一个 `CITATION.cff` 文件。 ## 局限性与未来工作 - **仅支持 Python** — 当前的 AST 解析主要针对 Python 3.10+。要支持多语言，需要为每个目标语言提供解析器后端。 - **仅支持静态分析** — 没有运行时追踪数据。动态调用信息可以通过执行频率加权的边来丰富该图谱。 - **import 解析** — 目前能解析项目内部的 import；标记了第三方和标准库的边，但未对其进行遍历。计划在未来实现完整的依赖解析（包括传递性依赖）。 - **层次本体** — 启发式关键字集以英语为中心，且偏向于 Python。欢迎社区为其他语言生态系统做出贡献。 - **LLM 分类器** — 目前使用单次 API 调用，且仅包含名称上下文。未来版本将纳入完整的 docstring 和周围的代码上下文，以实现更准确的分类。 ## 许可证 MIT — 查看 [LICENSE](LICENSE) *Architecture + landscape — 一个让您看清软件全貌的工具。*

标签：AST解析, D3.js可视化, Petitpotam, 数据管道, 架构逆向工程, 特权检测, 软件工程, 逆向工具, 错误基检测, 静态代码分析