docs/features/programming/code_analysis.md
面对一个陌生的代码项目，快速理解其整体架构和各模块功能是每个开发者都会遇到的挑战。GPT Academic 的源码分析功能正是为此而设计——它能够自动遍历项目中的所有源文件，借助大语言模型逐一分析每个文件的功能，然后综合生成项目的整体架构概述。无论是接手他人的项目、学习开源代码，还是回顾自己许久未碰的旧项目，这个功能都能帮您快速建立对代码的宏观认知。
GPT Academic 为不同编程语言提供了专门优化的分析插件，每种插件会自动识别对应语言的源文件和相关配置文件：
| 插件名称 | 分析的文件类型 |
|---|---|
| 解析整个Python项目 | .py |
| 解析整个Java项目 | .java, .xml, .jar, .sh |
| 解析整个C++项目 | .cpp, .hpp, .c, .h |
| 解析整个前端项目 | .js, .jsx, .ts, .tsx, .vue, .css, .less, .sass, .json |
| 解析整个Go项目 | .go, go.mod, go.sum, go.work |
| 解析整个Rust项目 | .rs, .toml, .lock |
| 解析整个Lua项目 | .lua, .xml, .json, .toml |
| 解析整个CSharp项目 | .cs, .csproj |
| 解析整个Matlab项目 | .m |
如果您的项目使用了多种语言或有特殊的文件类型，可以使用"解析项目源代码（手动指定和筛选源代码文件类型）"插件，通过高级参数自定义要分析的文件后缀。
这是最常用的方式，适合分析不在本地的项目或需要分享给他人查看的场景。
首先，将您的代码项目打包成 ZIP 格式的压缩文件。打包时建议排除 node_modules、__pycache__、.git 等无需分析的目录，这样可以减少处理时间和 Token 消耗。然后将压缩包拖拽到界面右侧的文件上传区域，等待上传完成。
上传完成后，系统会在对话区显示文件接收确认，同时在输入框中自动填入文件路径。接下来，在函数插件区找到与您项目语言对应的分析插件（如"解析整个Python项目"），点击该按钮即可开始分析。
<!-- IMAGE: feat_prog_01_code_analysis.png --> <!-- 描述: 源码分析功能的使用界面 --> <!-- 标注: ① 文件上传区域（显示已上传的 zip 文件）② 函数插件区的"解析整个Python项目"按钮 ③ 对话区显示的分析进度 --> <!-- 尺寸建议: 1000px -->如果项目已经在您的本地机器上（运行 GPT Academic 的同一台机器），可以直接在输入框中填写项目的绝对路径，然后点击对应的分析插件按钮。例如：
/home/user/projects/my_python_app
这种方式更加高效，因为省去了打包和上传的步骤，系统会直接读取本地文件进行分析。
您也可以通过虚空终端用自然语言发起分析请求：
请调用插件解析 /home/user/projects/my_app 这个 Python 项目
或者在上传项目后：
用插件分析我刚才上传的代码项目
虚空终端会自动选择合适的分析插件并执行。
源码分析采用"多线程逐文件分析 + 分组迭代汇总"的两阶段策略，这种设计能够在保证分析深度的同时处理大型项目。
系统首先扫描项目目录，收集所有符合条件的源文件。然后使用多线程并发的方式，将每个文件发送给语言模型进行独立分析。在这个阶段，模型会以"程序架构分析师"的角色，为每个文件生成一份简明的功能概述。
您可以在对话区看到分析进度，格式类似于：
[1/15] 请对下面的程序文件做一个概述: src/main.py
[2/15] 请对下面的程序文件做一个概述: src/utils/helper.py
...
当所有文件的独立分析完成后，系统进入汇总阶段。由于语言模型的上下文长度有限，无法一次性处理所有分析结果，系统会将文件分批（每批约 16 个文件）进行迭代汇总。
每一轮汇总中，模型会：
分析完成后，您将获得以下内容：
功能概述表格：列出项目中每个文件的名称和功能说明，方便快速查阅。
整体架构说明：一段综合性的描述，概括项目的整体功能、主要模块及其关系。
文件结构图：以 Mermaid 图表形式展示的项目结构可视化，直观呈现文件之间的组织关系。
分析报告文件：所有分析内容会被保存为文件，出现在界面右侧的下载区，您可以下载留存或分享。
对于混合语言项目或特殊文件结构的项目，您可以使用"解析项目源代码（手动指定和筛选源代码文件类型）"插件。点击该插件后，在弹出的高级参数输入框中指定要分析的文件模式：
包含特定类型：
*.py, *.yaml, config.toml
排除特定类型（使用 ^ 前缀）：
*.py, ^*.pyc, ^*_test.py
组合使用：
*.py, *.js, ^*.min.js, ^node_modules
!!! tip "模式语法"
- * 是通配符，匹配任意字符
- ^ 前缀表示排除
- 多个模式用逗号分隔
- 压缩包中的文件会在解压后的目录中搜索
源码分析功能对项目规模有一定限制——默认最多处理 512 个源文件。如果您的项目超过这个规模，可以考虑以下策略：
选择合适的模型：模型的理解能力直接影响分析质量。对于复杂项目，建议使用 GPT-4 级别的模型；简单项目用 GPT-3.5 即可获得不错的效果。
项目结构清晰：如果项目本身结构混乱（例如所有文件都放在根目录），分析结果也会较难理解。良好的目录组织能帮助模型更好地理解模块划分。
合理的文件数量：虽然系统支持批量处理数百个文件，但文件越多，Token 消耗越大，耗时越长。对于特别大的项目，建议先聚焦核心模块。
注意代码注释：模型会参考代码中的注释来理解功能。如果代码中有详细的文档字符串和注释，分析结果会更准确。
接手新项目：当您加入一个新团队或接手他人的代码时，源码分析能帮您在几分钟内建立对项目的整体认知，了解主要模块和它们的职责。
学习开源项目：在学习优秀的开源项目时，先用这个功能获得一份"导读"，能让后续的深入阅读更有方向性。
代码审查准备：在进行代码审查前，快速了解项目结构和各文件功能，有助于更高效地发现潜在问题。
项目文档生成：分析输出可以作为项目技术文档的基础素材，稍加整理就能成为项目的架构说明文档。
代码重构参考：在进行大规模重构前，先获得现有架构的清晰视图，有助于规划重构方案。
???+ question "提示'源文件太多（超过512个）'" 这是系统的保护限制。解决方法：
- 使用手动指定模式排除不必要的文件（如测试文件、依赖库）
- 分模块进行分析，每次只分析项目的一部分
- 只指定核心源码目录进行分析
???+ question "分析过程中出现超时错误" 大型项目的分析需要较长时间。可以尝试：
- 减少要分析的文件数量
- 提高 `TIMEOUT_SECONDS` 配置值
- 检查网络连接是否稳定
???+ question "分析结果不够准确" 模型对某些领域或框架可能理解有限。改善方法：
- 切换到更强的模型（如 GPT-4o）
- 确保代码中有足够的注释
- 对特别重要的模块进行单独的深入询问
???+ question "上传的压缩包无法解析" 请确保：
- 使用标准的 ZIP 格式打包
- 压缩包内直接包含源码文件或单层目录
- 文件编码为 UTF-8
???+ question "分析进度一直停在某个文件" 这可能是因为该文件内容过长或包含特殊字符。可以：
- 检查该文件是否有异常（如二进制内容、超长单行等）
- 在手动模式中排除该文件重新分析