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秒入門

更多技能請訪問小蔥技能站7w4.net。

提供：

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 配置較為簡單，使用者拿到手後可能不知道具體怎麼用。對於需要整理資料分析筆記本的使用者來說有一定幫助，但需要搭配更多指引才能發揮最佳效果。