Python 笔记本助手

要解决的问题

数据分析笔记本最常见的失败模式不是代码报错，而是“在我电脑上能跑，在你那里不可复现”：隐藏的全局变量、乱序执行的单元格、缓存里过期的数据快照、硬编码的凭据，以及图表看起来漂亮但口径无法追溯的结论。探索阶段这些代价尚可容忍，一旦交付给同事、评审或审计，问题会集中爆发。

这个技能把笔记本从“私人实验记录”整理为“可独立阅读的证据链”，目标是保留探索速度的同时，消除隐藏状态和结论脱离证据的风险。

技能如何工作

它按一条清晰的链路推进，核心包括：

• 数据契约：先记录来源、快照时间、字段语义、主键、时区、缺失规则和权限，再做行数、唯一性、范围、重复和时间覆盖检查，之后才进入分析。
• 环境固定：固定 Python、内核、关键依赖、硬件、随机种子和区域设置；凭据只放在安全环境配置中，不写入单元格或输出。
• 章节骨架：按 目的—设置—数据—质量—分析—验证—结论—限制 组织，每个单元格只完成一个逻辑动作，避免百行代码块和大段无结构输出。
• 清除隐藏状态：从空内核按顺序执行，参数集中到顶部，删除重复定义、未使用变量和依赖旧输出的单元格。
• 质量门禁：在关键转换后加轻量断言——行数变化、主键唯一、类型、范围、合计一致、连接覆盖率。断言失败就停止，而不是继续生成看似完整的图表。
• 结论分级：结论标记为 OBSERVED、SUPPORTED、SUGGESTIVE 或 UNVERIFIED；图表必须带单位、口径、样本量和数据来源；没有实验或识别策略时，不把相关性写成因果。

标准流程分十步，从固定问题与读者、建立数据契约、固定环境，一路走到清空重跑、交付产物摘要与复现命令。交付前会在干净环境中完整执行全部单元格，确认顺序、耗时和错误处理。

适用边界

• 默认修改副本或给出重构计划；未获授权时不覆盖原笔记本，不访问或导出敏感数据，不执行付款、写库、删除、训练大模型等高成本或不可逆单元格。
• 乱序运行后的成功不视为可复现，必须从空内核按顺序重跑。
• 即使设置随机种子，并行计算、硬件内核和第三方库仍可能引入非确定性，需记录环境并设置合理容差。
• 不静默删除异常值、缺失值或失败样本；保留关键探索单元格，废弃路径应归档而非悄悄丢弃。
• 当逻辑需要复用、测试或部署时，代码应提取为模块或脚本，笔记本只保留调用与解释。