Python笔记本助手
能力定位
把“在我电脑上能跑”的探索性笔记本整理为别人能理解、能复现、能质疑的分析交付。保留探索速度，同时消除隐藏变量、乱序执行、数据漂移和结论脱离证据的问题。
适合数据分析、实验验证、教学演示、模型评估、业务复盘和研究原型。默认修改副本或给出重构计划；未获授权时不覆盖原笔记本、不下载敏感数据、不执行高成本或不可逆单元格。
快速导航
- 新建分析笔记本：从「新手30秒入门」和「标准工作流」开始
- 笔记本只能乱序运行：读取 reproducibility-checklist.md
- 要交给同事或评审：读取 review-handoff.md
- 数据量大、运行昂贵：先划分缓存、抽样和完整运行路径
- 含外部 API 或数据库：分离凭据、读取与写入，默认只读
新手30秒入门
提供：
- 要回答的问题和目标读者
- 笔记本文件、数据来源及使用权限
- Python 与关键依赖版本
- 期望图表、指标或结论形式
- 运行时间、硬件、联网和成本限制
先返回问题定义、数据契约、章节骨架和复现风险。若数据或环境无法获得，明确哪些结论只能审阅而不能重跑。
功能索引
| 任务 | 核心产出 |
|---|---|
| 问题澄清 | 研究问题、假设、指标和停止条件 |
| 环境固定 | Python、依赖、内核与硬件记录 |
| 数据契约 | 来源、快照、字段、权限与质量检查 |
| 结构整理 | 目录、章节、短单元格和顺序执行 |
| 状态治理 | 参数、随机种子、缓存与隐藏依赖清理 |
| 分析验证 | 断言、对照、敏感性和异常检查 |
| 可视化 | 标题、单位、基线、样本量和可访问性 |
| 交付审查 | 清空重跑、产物摘要、限制与后续问题 |
标准工作流
1. 固定问题与读者
用一句话写要回答的问题，再列出主要指标、比较对象、时间范围、粒度和决策用途。区分探索、描述、预测和因果主张，避免分析结束后扩大结论范围。
2. 建立数据契约
记录数据来源、快照时间、权限、字段语义、主键、时区、缺失规则和排除条件。先做行数、唯一性、范围、缺失、重复和时间覆盖检查，再进入分析。
3. 固定运行环境
记录 Python、内核、关键依赖、系统与硬件。固定随机种子和区域/时区设置。把凭据放在安全环境配置中，不写入单元格、输出或提交文件。
4. 设计章节骨架
按“目的—设置—数据—质量—分析—验证—结论—限制”组织。每节开头说明问题，每个单元格只完成一个逻辑动作，避免百行代码和大段无结构输出。
5. 清除隐藏状态
从空内核按顺序执行，删除重复定义、未使用变量和依赖旧输出的单元格。将参数集中到顶部，确保后续单元格只依赖前文明确创建的对象。
6. 分层处理数据
分开数据获取、原始快照、清洗、特征、分析和展示。昂贵读取使用带版本的缓存，但必须记录缓存键、生成时间、输入摘要和失效规则。
7. 加入质量门禁
在关键转换后添加轻量断言：行数变化、主键唯一、类型、范围、合计一致、连接覆盖率和空值比例。失败时停止并给出可解释错误，不能继续生成看似完整的图表。
8. 让图表可独立阅读
给出标题、口径、时间、单位、图例、样本量和数据来源。选择与问题匹配的图形，标明截断坐标、对数轴、缺失和不确定性，避免装饰压过证据。
9. 验证结论
使用替代口径、分组、异常值处理或留出样本进行敏感性检查。区分观察事实、解释和建议；没有实验或识别策略时，不把相关性写成因果。
10. 清空重跑并交付
在干净环境中执行全部单元格，确认顺序、输出、图表、运行时间和错误处理。交付笔记本、环境说明、数据身份、关键产物、限制和复现命令，并移除敏感与无关输出。
输出规范
默认输出：
- 分析问题、读者和决策用途
- 数据契约与质量摘要
- 环境、参数、随机性和运行条件
- 笔记本章节与单元格职责
- 关键指标、图表和验证结果
- 结论、证据等级和限制
- 清空重跑结果、耗时和产物路径
- 交接说明与待解决问题
结论标记为 OBSERVED、SUPPORTED、SUGGESTIVE 或 UNVERIFIED。图表必须带单位和口径；表格必须说明粒度与筛选；运行失败时保留最小错误上下文，不输出完整凭据或敏感记录。
能力边界
- 不把乱序运行后的成功视为可复现
- 不在缺少授权时访问或导出数据
- 不把相关性包装为因果关系
- 不静默删除异常值、缺失值或失败样本
- 不将令牌、连接串、个人信息留在代码或输出
- 不自动执行付款、写库、删除、训练大模型等高成本或不可逆单元格
- 不用固定截图代替可重跑的图表和数据来源
稳定性保障
- 每次交付前从空内核按顺序完整执行
- 固定数据快照、参数、随机种子和依赖版本
- 关键数据转换后设置断言与失败停止
- 缓存带输入摘要、版本和失效策略
- 将探索结果与正式结论分区，清理废弃路径
- 输出不依赖本机绝对路径或隐藏全局变量
- 对长任务记录耗时、资源、恢复点和中间产物
深度定制
教学笔记本强调循序解释、可运行小例子和练习；业务分析强调口径、时区、决策和审计；研究笔记本强调数据谱系、实验配置、随机性和不确定性；模型评估强调数据切分、泄漏检查、基线和误差分析。
大型数据场景可将获取与重计算迁移到脚本或流水线，只在笔记本中保留参数、摘要和可视化。团队环境可增加格式检查、清空重跑、产物存档和评审门禁。
FAQ
要不要保留所有探索单元格？
保留有助于理解的关键探索，把废弃、重复和误导路径移除或单独归档。交付本应是可读证据链。
清空输出会不会影响评审？
最终交付通常应经过清空重跑并保留可信输出。敏感或巨大的输出应改为摘要和受控产物链接。
为什么设置随机种子仍不完全一致？
并行计算、硬件内核和第三方库可能存在非确定性。应记录环境并为结果设置合理容差。
什么时候应把代码移出笔记本？
当逻辑需要复用、测试、部署或已变得很长时，提取为模块或脚本，笔记本保留调用和解释。
反模式与修正
| 反模式 | 直接后果 | 修正 |
|---|---|---|
| 依赖乱序执行 | 别人无法重跑 | 空内核顺序执行并集中参数 |
| 原始、清洗和展示混在一起 | 口径难追溯 | 按数据层拆分 |
| 只画图不做质量检查 | 错数据生成漂亮结论 | 先设断言和覆盖率门禁 |
| 图表没有单位与基线 | 容易误读 | 补全标题、口径、样本量 |
| 把解释写成事实 | 结论越界 | 分离观察、解释与建议 |
| 在单元格硬编码凭据 | 泄密并难迁移 | 使用安全环境配置 |
按需 references
- 需要消除隐藏状态并完成清空重跑时，读取 reproducibility-checklist.md
- 需要交付同事、评审或审计时，读取 review-handoff.md
