docs/features/programming/jupyter_analysis.md
Jupyter Notebook 是数据科学和机器学习领域最流行的交互式开发环境之一，其独特的 Cell 式结构让代码、文档和可视化输出完美融合。然而，这种混合格式也给代码理解带来了挑战——当您接手他人的 Notebook 或回顾自己几个月前的实验代码时，理清各个 Cell 之间的逻辑关系往往需要耗费大量时间。GPT Academic 的 Jupyter Notebook 分析功能专门为此而设计：它能够解析 .ipynb 文件的结构，智能识别代码块和 Markdown 说明，然后借助大语言模型逐块分析每个 Cell 的功能，帮助您快速建立对整个 Notebook 的理解。
Jupyter Notebook 分析功能采用了针对 .ipynb 格式优化的解析策略。系统首先读取 Notebook 的 JSON 结构，提取其中的代码单元格（code cells）和 Markdown 单元格，然后按顺序组织成连贯的文本，最后交由大语言模型进行逐块解读。
与普通的源码分析不同，Notebook 分析会保留单元格的执行顺序信息，让您清楚地了解数据处理流程中每一步的作用。同时，系统还支持选择性地包含或排除 Markdown 单元格——如果 Notebook 中已有详细的文字说明，您可以选择只分析代码部分以节省处理时间和 Token 消耗。
您可以通过两种方式向系统提供待分析的 Jupyter Notebook。
上传单个 Notebook 文件：将 .ipynb 文件直接拖拽到界面右侧的文件上传区域。这是最简单直接的方式，适合分析单个实验笔记或教程文档。
上传包含多个 Notebook 的目录：如果您有一个项目包含多个相关的 Notebook（例如按步骤拆分的数据分析流程），可以将整个目录打包成 ZIP 文件上传。系统会自动扫描目录中所有的 .ipynb 文件并依次处理。
指定本地路径：对于已在本地的文件或目录，您也可以直接在输入框中输入路径，支持以下格式：
# 单个文件
/home/user/notebooks/experiment.ipynb
# 整个目录（将处理其中所有 .ipynb 文件）
/home/user/projects/ml_pipeline
在函数插件区找到 编程 分类下的 解析ipynb文件 插件，点击即可开始分析。插件启动后，您会看到高级参数输入框，这里可以控制 Markdown 单元格的处理方式。
包含 Markdown 单元格（默认）：保留输入框为空或输入 1，系统将同时分析代码单元格和 Markdown 单元格。Markdown 内容会以 Markdown: 前缀标识，帮助您理解代码的上下文说明。
仅分析代码单元格：在高级参数输入框中输入 0，系统将跳过所有 Markdown 单元格，只关注代码部分。这适用于 Markdown 说明已经足够清晰、或者您只想快速了解代码逻辑的场景。
点击插件后，系统会启动自动化的分析流程。
系统首先读取 .ipynb 文件的 JSON 内容，按照 Cell 的类型和顺序提取信息。每个代码 Cell 会保持原有的代码内容，而 Markdown Cell（如果启用）则会添加 Markdown: 前缀以区分。提取过程中会自动过滤空白行，保持内容的紧凑性。
由于大语言模型存在上下文长度限制，系统会根据 Token 数量对内容进行智能分段。默认的分段阈值为 1024 个 Token，这个设置能够确保每个片段既包含足够的上下文，又不会超出模型的处理能力。如果单个 Notebook 内容较长，系统会自动拆分成多个部分进行处理，最后汇总结果。
分段完成后，系统使用多线程并发的方式将各片段发送给大语言模型。模型会以专业程序员的视角，用中文解读每个代码块的功能，包括数据处理步骤、算法实现、可视化逻辑等。您可以在对话区实时看到分析进度：
experiment.ipynb 的分析如下
第 1 个代码块：导入 pandas、numpy 等数据处理库，设置绘图参数...
第 2 个代码块：读取 CSV 数据文件，进行初步的数据清洗...
...
所有片段分析完成后，系统会将结果整合并显示在对话区。同时，完整的分析报告会被保存为文件，出现在界面右侧的下载区供您下载留存。
一个典型的 Notebook 分析结果会按照 Cell 的执行顺序呈现，让您清晰地看到数据处理的完整流程：
第 1 个代码块：导入必要的库，包括 pandas 用于数据处理、matplotlib 和 seaborn 用于可视化、sklearn 用于机器学习模型。
Markdown：实验说明部分，描述了本次分析的目标是预测房价，数据来源为 Kaggle 公开数据集。
第 2 个代码块：使用 pandas 读取 CSV 文件，显示数据集的基本信息包括行数、列数、数据类型。
第 3 个代码块：数据预处理步骤，处理缺失值（使用均值填充）、删除异常值、进行特征标准化。
第 4 个代码块：绘制特征相关性热力图，分析各特征与目标变量的相关程度。
第 5 个代码块：划分训练集和测试集，构建线性回归模型并进行训练。
第 6 个代码块：使用测试集评估模型性能，计算 RMSE 和 R² 指标，绘制预测值与实际值的散点图。
这种逐块解读的方式特别适合理解数据科学项目的工作流，让您无需逐行阅读代码就能把握 Notebook 的整体脉络。
接手数据科学项目：当您加入新团队或接手他人的分析项目时，Notebook 分析能帮您快速了解已有的数据处理流程和建模思路，省去逐个 Cell 研读的时间。
回顾历史实验：几个月前写的实验代码，即使有部分注释，回忆起来也往往需要花费不少时间。让 AI 帮您做一份"执行纪要"，快速唤起记忆。
学习教程 Notebook：在学习在线课程或开源教程时，先用分析功能获得一份中文版的步骤解读，能让后续的深入学习更有针对性。
代码审查准备：在审查团队成员提交的 Notebook 前，快速了解其整体思路和关键步骤，有助于更高效地发现潜在问题。
选择合适的模型：Notebook 分析需要模型具备一定的代码理解和领域知识。对于涉及复杂算法或专业领域的 Notebook（如深度学习、生物信息学），建议使用 GPT-4 级别的模型以获得更准确的解读。
合理设置 Markdown 选项：如果 Notebook 中的 Markdown 说明已经很详细，可以选择仅分析代码部分（参数设为 0），这样能节省 Token 并聚焦于代码逻辑。反之，如果 Markdown 中包含重要的实验设计说明，则应保留以获得完整的上下文。
拆分超长 Notebook：虽然系统会自动处理长文件的分段，但对于包含数百个 Cell 的超长 Notebook，建议先在本地按功能模块拆分成多个较小的 Notebook，这样分析结果会更聚焦、更易理解。
保持代码整洁：Notebook 中如果有大量的调试输出、重复运行的单元格或注释掉的代码，会增加分析的噪音。在提交分析前做一些清理（或使用 nbstripout 等工具）能获得更清晰的结果。
???+ question "提示'找不到任何.ipynb文件'" 请检查：
- 输入的路径是否正确
- 如果上传的是压缩包，确保使用 ZIP 格式
- 确认文件确实以 `.ipynb` 为后缀
???+ question "分析结果中某些 Cell 缺失" 可能的原因：
- 该 Cell 内容为空或仅包含空白行
- 该 Cell 是原始文本（raw cell），系统默认不处理
- 长 Notebook 分段时某些边界处理导致
???+ question "分析结果不够准确" 改善方法：
- 切换到更强的模型（如 GPT-4o 或 qwen-max）
- 确保 Notebook 中的变量名和函数名具有描述性
- 对于专业领域的代码，可在分析后进行人工校正
???+ question "处理多个 Notebook 时顺序混乱" 系统会按照文件系统的顺序处理，如果需要特定顺序，建议：
- 使用数字前缀命名文件（如 `01_data_load.ipynb`, `02_preprocess.ipynb`）
- 或者一次只处理一个 Notebook