docs/features/programming/custom_code_analysis.md
实际开发中，项目的技术栈往往并不局限于单一语言。一个典型的全栈项目可能同时包含 Python 后端、TypeScript 前端、配置文件、Shell 脚本等多种类型的文件。标准的语言特定分析插件（如"解析整个Python项目"）在面对这类混合项目时显得力不从心。GPT Academic 的自定义源码分析功能正是为解决这一问题而设计——它允许您通过简洁的模式语法，精确指定要分析的文件类型，同时排除不需要的文件，从而实现对任意项目结构的灵活分析。
自定义源码分析基于与标准源码分析相同的核心引擎，采用"多线程逐文件分析 + 分组迭代汇总"的两阶段策略。其独特之处在于引入了强大的文件筛选机制：通过高级参数输入框，您可以使用通配符模式指定要包含的文件类型，同时使用排除前缀过滤掉不需要分析的文件。
这种设计带来了极大的灵活性。无论是分析同时包含 .py 和 .yaml 的机器学习项目，还是处理混合了前后端代码的 monorepo，或是只想聚焦于某些特定配置文件，都能通过简单的模式表达式轻松实现。
自定义源码分析的核心是文件匹配模式语法，理解这些规则是有效使用此功能的关键。
* 是最基本的通配符，它可以匹配文件名中的任意字符序列。以下是常见的使用方式：
| 模式 | 匹配示例 | 说明 |
|---|---|---|
*.py | main.py, utils.py | 所有 Python 文件 |
*.config.js | webpack.config.js | 以 .config.js 结尾的文件 |
config.* | config.json, config.yaml | 名为 config 的所有类型文件 |
Dockerfile | Dockerfile | 精确匹配特定文件名 |
使用 ^ 前缀可以排除特定类型的文件。这在需要过滤掉测试文件、编译产物或其他无关文件时特别有用：
| 模式 | 效果 |
|---|---|
^*.pyc | 排除所有编译后的 Python 字节码文件 |
^*_test.py | 排除所有测试文件 |
^*.min.js | 排除压缩后的 JavaScript 文件 |
^README.md | 排除 README 文件 |
^node_modules | 排除整个 node_modules 目录 |
多个模式之间使用逗号分隔，包含模式和排除模式可以混合使用。系统会先应用包含规则收集文件，然后应用排除规则进行过滤：
*.py, *.yaml, ^*.pyc, ^*_test.py
这个表达式的含义是：分析所有 Python 源文件和 YAML 配置文件，但排除字节码文件和测试文件。
!!! tip "逗号和空格" 模式之间既可以用逗号分隔，也可以用空格分隔，系统都能正确解析。为了清晰起见，建议统一使用逗号加空格的格式。
如果不输入任何模式（留空高级参数框），系统将尝试匹配所有文件。但请注意，系统内置了一些默认排除规则，压缩文件格式（.zip、.rar、.7z、.tar、.gz）始终会被自动排除，避免误处理压缩包文件。
与标准源码分析相同，您可以通过上传压缩包或指定本地路径两种方式提供项目文件。
上传压缩包：将项目打包成 ZIP 格式上传。上传后系统会自动解压到临时目录，后续的文件匹配将在解压目录中进行。
指定本地路径：在输入框中输入项目的绝对路径，系统将直接在该目录下进行文件搜索。
在函数插件下拉菜单中找到 解析项目源代码（手动指定和筛选源代码文件类型） 插件并选择它。这是一个需要高级参数的插件，选择后会弹出参数输入界面。
在高级参数输入框中，按照前面介绍的语法输入您的文件匹配模式。输入框下方会显示提示信息，帮助您回忆语法规则。确认模式无误后，点击提交按钮开始分析。
<!-- IMAGE: feat_prog_04_custom_analysis.png --> <!-- 描述: 自定义源码分析功能的高级参数界面 --> <!-- 标注: ① 下拉菜单中选中的"解析项目源代码（手动指定和筛选源代码文件类型）"选项 ② 高级参数输入框，内容示例为 "*.py, *.yaml, ^*_test.py" ③ 输入框下方的语法提示 --> <!-- 尺寸建议: 1000px -->以下是几个典型场景的模式配置示例，供您参考和借鉴。
一个包含 Python 后端和 React 前端的项目：
*.py, *.ts, *.tsx, *.json, ^node_modules, ^*.pyc, ^__pycache__
这个配置会分析所有 Python 和 TypeScript/React 源文件以及 JSON 配置，同时排除依赖目录和编译产物。
分析模型代码和配置文件，排除数据和检查点：
*.py, *.yaml, *.yml, config.toml, ^*.csv, ^*.pt, ^*.pth, ^checkpoint
快速了解项目的配置结构：
*.yaml, *.yml, *.toml, *.json, *.ini, *.env, Dockerfile, docker-compose*
*.go, *.proto, go.mod, go.sum, Makefile
分析 Latex 源文件和参考文献：
*.tex, *.bib, *.cls, *.sty
*.py, ^*_test.py, ^test_*.py, ^*_example.py, ^examples
点击提交后，系统的处理流程与标准源码分析一致。
文件收集阶段：系统首先在项目目录（或解压目录）中递归搜索所有匹配包含模式的文件，然后应用排除规则过滤。您可以在对话区看到最终匹配的文件数量。
逐文件分析阶段：使用多线程并发方式分析每个文件，进度信息会实时显示在对话区：
[1/23] 请对下面的程序文件做一个概述: src/main.py
[2/23] 请对下面的程序文件做一个概述: src/utils/helper.py
[3/23] 请对下面的程序文件做一个概述: config/settings.yaml
...
汇总阶段：所有文件分析完成后，系统会分批迭代生成项目的整体概述、功能表格和结构图，与标准源码分析的输出格式相同。
从宽泛到精确：如果不确定需要哪些文件，可以先用较宽泛的模式（如 *.py, *.js）运行一次，根据结果调整后再精确分析。
排除优先：对于大型项目，明确排除无关文件（如 node_modules、dist、.git）能显著减少处理时间和 Token 消耗。
配置文件单独处理：如果只想了解项目的配置结构，可以单独配置一个只匹配配置文件的模式，这样能获得更聚焦的分析结果。
自定义分析同样受到 512 文件的数量限制。面对大型 monorepo，建议：
如果不确定模式是否正确匹配了预期文件，可以先在本地使用类似的 shell 命令测试：
# 模拟 *.py, ^*_test.py 的效果
find . -name "*.py" | grep -v "_test.py"
确认结果符合预期后再提交给系统处理。
???+ question "提示'找不到任何文件'" 可能的原因：
- 模式表达式语法错误，导致没有文件被匹配
- 包含模式与项目实际文件类型不符
- 排除规则过于宽泛，将所有文件都过滤掉了
建议检查模式语法，或尝试更宽泛的包含规则（如 `*`）看是否能匹配到文件。
???+ question "匹配到了不想分析的文件" 添加更精确的排除规则。例如：
- 排除特定目录：`^dirname`
- 排除特定后缀：`^*.min.js`
- 排除特定命名模式：`^test_*`
???+ question "压缩包中的文件无法匹配" 请确保：
- 压缩包使用标准 ZIP 格式
- 系统已正确解压（会创建 `.extract` 后缀的目录）
- 模式中没有硬编码路径（应使用 `*.py` 而非 `src/*.py`）
???+ question "分析结果中文件顺序混乱" 系统按文件系统的默认顺序处理。如果需要特定顺序：
- 使用数字前缀命名关键文件
- 或者分多次按顺序分析不同模块
???+ question "某些特殊格式文件内容显示异常" 系统使用 UTF-8 编码读取所有文件。如果文件使用其他编码（如 GBK），可能出现乱码。建议在分析前将文件转换为 UTF-8 编码。
| 特性 | 语言特定插件 | 自定义分析插件 |
|---|---|---|
| 文件类型 | 预设固定 | 自由指定 |
| 排除规则 | 无 | 支持 |
| 适用场景 | 单语言项目 | 混合项目、特殊需求 |
| 操作复杂度 | 一键使用 | 需要编写模式 |
| 灵活性 | 低 | 高 |
对于单一语言的标准项目，使用对应的语言特定插件更加方便。而当项目结构复杂或有特殊需求时，自定义分析插件能提供更大的灵活性和控制力。
.ipynb 格式文件