开源项目二次开发辅助工具 · AST 解析与扩展点识别

这个项目解决什么问题

接手一个陌生开源项目，最贵的不是写代码，而是搞清楚从哪里下刀：入口在哪、哪些类是留给你继承的、哪些函数一改就崩。市面上工具生成的是"API 手册"，本项目生成的是上手路径——这是视角上的根本区别。

核心亮点

• AST 静态解析，核心零依赖：项目结构、文档覆盖率、圈复杂度全部用 Python 标准库 ast 实现，不依赖重型 LSP/索引服务，任何机器秒开。
• 入口点识别：约定入口 + __main__ 判断双策略，报告第一页就告诉你"程序从这里开始跑"。
• 依赖双向审计：内部模块依赖图（Mermaid 语法，可直接贴进 GitHub Wiki）；同时把代码实际 import 与 requirements.txt 交叉比对，揪出"能跑但换台机器就崩"的隐性依赖。
• 可扩展接口识别：抽象基类、被继承的基类、装饰器注册点——报告直接列出"二次开发的下刀处"，这是全项目最实用的一页。
• 双引擎 AI 摘要：配置 OpenAI API Key 后为每个模块生成通俗解读；没有 Key 自动降级为本地启发式摘要引擎，离线环境全流程可用，课程汇报时这是现成的"工程鲁棒性"论据。
• 双入口交付：CLI 适合集成到脚本，Flask 网页适合现场演示，报告统一落盘 outputs/。

效果预览

命令行一键分析（内置演示项目 sample_repo，离线可复现）：

Web 报告页：概览指标、入口点、扩展接口徽章、依赖图一屏呈现：

预览图为演示项目（5 个文件）的实际输出效果；仓库越大，报告信息量越大。

你将学到

• ast 模块的工程化用法：结构提取、圈复杂度、静态规则匹配
• 依赖关系分析与其可视化表达（Mermaid）
• 外部服务的优雅降级设计（AI → 本地引擎、gitpython → 系统 git）
• 从"分析结果"到"可执行建议"的报告设计思路

适合谁

经常接手陌生代码库的开发者、做"代码理解/大模型+代码"方向毕设的学生。难度 ★★★☆，核心分析模块纯标准库实现，每一行都能读懂。

扩展点识别的规则怎么设计的、依赖图算法细节——源码注释里都有，这里刻意没有展开，留给你自己探索。

交付内容：完整可运行源码、README.md（逐步运行方法与实现说明）、requirements.txt。

许可：个人使用，可用于自己的学习、课程实验与研究报告，请勿转售或公开传播。

环境与步骤

pip install -r requirements.txt

pip install -r requirements.txt

python main.py ./sample_repo                            # 内置演示项目，离线可跑
python main.py https://github.com/pallets/flask        # 分析任意公开仓库
python app.py                                          # Web 界面

注意事项

• AI 摘要为可选增强：不配 OpenAI Key 时自动降级为本地启发式摘要引擎。

Q：没有 OpenAI Key 能用吗？

A：能。AI 摘要是可选增强：检测不到 Key 时自动切到本地启发式摘要引擎，结构解析、入口识别、依赖审计、扩展点识别这些核心内容都不依赖网络。

Q：会把我的代码传到外面吗？

A：解析全在本地用标准库 ast 完成，不依赖重型索引服务；只有你配了 Key 并启用 AI 摘要时，才会把模块文本发给模型。

Q：报告里具体有什么？

A：项目结构与文档覆盖率、程序入口（约定入口 + __main__ 双策略）、内部模块依赖图（Mermaid 语法，可直接贴进 Wiki）、requirements 与实际 import 的交叉比对（揪出“能跑但换台机器就崩”的隐性依赖）、可扩展接口（抽象基类、被继承的基类、装饰器注册点）、圈复杂度热点。

Q：怎么跑？

A：两种入口：python main.py https://github.com/pallets/flask 出 Markdown 报告适合脚本集成；或起 Flask 网页（http://127.0.0.1:5000 ）现场演示，报告统一落盘 outputs/。