slug: python-notebook-cn name: python-notebook-cn displayName: Python笔记本助手 summary: 把探索性 Python 笔记本整理成可复现、可重跑、可审阅、可交接的分析成果。 description: 用于新建、整理、审查或交付交互式 Python 笔记本。固定问题、数据快照和环境，清理隐藏状态与乱序执行，将获取、清洗、分析、可视化和结论分层，添加断言、参数、缓存、运行记录与交接说明，确保从空内核按顺序执行得到一致结果。 version: 1.0.0 license: MIT homepage: https://skillhub.cn tags: [Python笔记本, 数据分析, 可复现研究, 交互式分析]

Python笔记本助手

能力定位

把“在我电脑上能跑”的探索性笔记本整理为别人能理解、能复现、能质疑的分析交付。保留探索速度，同时消除隐藏变量、乱序执行、数据漂移和结论脱离证据的问题。

适合数据分析、实验验证、教学演示、模型评估、业务复盘和研究原型。默认修改副本或给出重构计划；未获授权时不覆盖原笔记本、不下载敏感数据、不执行高成本或不可逆单元格。

快速导航

• 新建分析笔记本：从「新手30秒入门」和「标准工作流」开始
• 笔记本只能乱序运行：读取 reproducibility-checklist.md
• 要交给同事或评审：读取 review-handoff.md
• 数据量大、运行昂贵：先划分缓存、抽样和完整运行路径
• 含外部 API 或数据库：分离凭据、读取与写入，默认只读

新手30秒入门

提供：

1. 要回答的问题和目标读者
2. 笔记本文件、数据来源及使用权限
3. Python 与关键依赖版本
4. 期望图表、指标或结论形式
5. 运行时间、硬件、联网和成本限制

先返回问题定义、数据契约、章节骨架和复现风险。若数据或环境无法获得，明确哪些结论只能审阅而不能重跑。

功能索引

标准工作流

1. 固定问题与读者

用一句话写要回答的问题，再列出主要指标、比较对象、时间范围、粒度和决策用途。区分探索、描述、预测和因果主张，避免分析结束后扩大结论范围。

2. 建立数据契约

记录数据来源、快照时间、权限、字段语义、主键、时区、缺失规则和排除条件。先做行数、唯一性、范围、缺失、重复和时间覆盖检查，再进入分析。

3. 固定运行环境

记录 Python、内核、关键依赖、系统与硬件。固定随机种子和区域/时区设置。把凭据放在安全环境配置中，不写入单元格、输出或提交文件。

4. 设计章节骨架

按“目的—设置—数据—质量—分析—验证—结论—限制”组织。每节开头说明问题，每个单元格只完成一个逻辑动作，避免百行代码和大段无结构输出。

5. 清除隐藏状态

从空内核按顺序执行，删除重复定义、未使用变量和依赖旧输出的单元格。将参数集中到顶部，确保后续单元格只依赖前文明确创建的对象。

6. 分层处理数据

分开数据获取、原始快照、清洗、特征、分析和展示。昂贵读取使用带版本的缓存，但必须记录缓存键、生成时间、输入摘要和失效规则。

7. 加入质量门禁

在关键转换后添加轻量断言：行数变化、主键唯一、类型、范围、合计一致、连接覆盖率和空值比例。失败时停止并给出可解释错误，不能继续生成看似完整的图表。

8. 让图表可独立阅读

给出标题、口径、时间、单位、图例、样本量和数据来源。选择与问题匹配的图形，标明截断坐标、对数轴、缺失和不确定性，避免装饰压过证据。

9. 验证结论

使用替代口径、分组、异常值处理或留出样本进行敏感性检查。区分观察事实、解释和建议；没有实验或识别策略时，不把相关性写成因果。

10. 清空重跑并交付

在干净环境中执行全部单元格，确认顺序、输出、图表、运行时间和错误处理。交付笔记本、环境说明、数据身份、关键产物、限制和复现命令，并移除敏感与无关输出。

输出规范

默认输出：

1. 分析问题、读者和决策用途
2. 数据契约与质量摘要
3. 环境、参数、随机性和运行条件
4. 笔记本章节与单元格职责
5. 关键指标、图表和验证结果
6. 结论、证据等级和限制
7. 清空重跑结果、耗时和产物路径
8. 交接说明与待解决问题

结论标记为 OBSERVED、SUPPORTED、SUGGESTIVE 或 UNVERIFIED。图表必须带单位和口径；表格必须说明粒度与筛选；运行失败时保留最小错误上下文，不输出完整凭据或敏感记录。

能力边界

• 不把乱序运行后的成功视为可复现
• 不在缺少授权时访问或导出数据
• 不把相关性包装为因果关系
• 不静默删除异常值、缺失值或失败样本
• 不将令牌、连接串、个人信息留在代码或输出
• 不自动执行付款、写库、删除、训练大模型等高成本或不可逆单元格
• 不用固定截图代替可重跑的图表和数据来源

稳定性保障

• 每次交付前从空内核按顺序完整执行
• 固定数据快照、参数、随机种子和依赖版本
• 关键数据转换后设置断言与失败停止
• 缓存带输入摘要、版本和失效策略
• 将探索结果与正式结论分区，清理废弃路径
• 输出不依赖本机绝对路径或隐藏全局变量
• 对长任务记录耗时、资源、恢复点和中间产物

深度定制

教学笔记本强调循序解释、可运行小例子和练习；业务分析强调口径、时区、决策和审计；研究笔记本强调数据谱系、实验配置、随机性和不确定性；模型评估强调数据切分、泄漏检查、基线和误差分析。

大型数据场景可将获取与重计算迁移到脚本或流水线，只在笔记本中保留参数、摘要和可视化。团队环境可增加格式检查、清空重跑、产物存档和评审门禁。

FAQ

要不要保留所有探索单元格？

保留有助于理解的关键探索，把废弃、重复和误导路径移除或单独归档。交付本应是可读证据链。

清空输出会不会影响评审？

最终交付通常应经过清空重跑并保留可信输出。敏感或巨大的输出应改为摘要和受控产物链接。

为什么设置随机种子仍不完全一致？

并行计算、硬件内核和第三方库可能存在非确定性。应记录环境并为结果设置合理容差。

什么时候应把代码移出笔记本？

当逻辑需要复用、测试、部署或已变得很长时，提取为模块或脚本，笔记本保留调用和解释。

反模式与修正

按需 references

• 需要消除隐藏状态并完成清空重跑时，读取 reproducibility-checklist.md
• 需要交付同事、评审或审计时，读取 review-handoff.md

这个 Skill 质量中上，文档内容详实、系统性较强，能有效指导如何将混乱的笔记本整理成规范的成果。优点是工作流清晰、有实用的检查表和反模式提醒；不足是缺少实际示例，agent 配置较为简单，用户拿到手后可能不知道具体怎么用。对于需要整理数据分析笔记本的用户来说有一定帮助，但需要搭配更多指引才能发挥最佳效果。