slug: python-type-check-cn name: python-type-check-cn displayName: Python 型別排錯助手 summary: 解釋 Python 靜態型別錯誤的真實契約，區分程式碼缺陷、型別宣告和檢查配置，並漸進修正。 description: 用於 Python 靜態型別檢查報錯、型別註解補全、嚴格模式遷移、第三方型別宣告缺失、泛型或協議不匹配、聯合型別收窄失敗、過載衝突、非同步型別錯誤和本地/CI 診斷不一致。先固定直譯器、檢查器、配置和依賴宣告，再把診斷對映到執行時契約與資料流，區分真實缺陷、註解過窄、推斷缺口、宣告質量和配置差異，實施最小修正並用執行測試與型別迴歸共同驗證。預設不以 Any、全域性忽略或關閉規則掩蓋問題。 version: 1.0.0 license: MIT homepage: https://skillhub.cn tags: [Python, 型別檢查, 型別註解, 程式碼質量]

Python 型別排錯助手

能力定位

把一串靜態診斷還原成“程式碼承諾了什麼、執行時可能發生什麼、檢查器缺少什麼資訊”。目標不是讓紅線消失，而是在不破壞公共介面與執行行為的前提下，讓型別契約更準確。

同一錯誤可能來自實現缺陷、註解錯誤、第三方宣告、版本差異或檢查範圍變化，必須先分類再修改。

快速導航

• 引數或返回值不相容：核對呼叫方、實現和公共契約
• 可空值、聯合型別無法收窄：追蹤分支與變異點
• 泛型、協議、協變/逆變報錯：讀取 diagnostic-triage.md
• 第三方庫沒有型別或宣告錯誤：隔離外部宣告與本專案程式碼
• 本地通過、CI 失敗：比較版本、配置發現路徑和檢查檔案集合
• 想逐步開啟嚴格檢查：讀取 migration-gates.md

新手30秒入門

提供完整診斷、相關函式或類、期望執行行為、Python 與檢查器版本、配置檔案、依賴版本，以及本地和 CI 的執行命令。先解釋每條診斷對應的型別關係，再給最小修正候選。

不要先加全域性忽略。忽略會抹掉資訊，也可能讓真正的空值、錯誤分支或介面漂移進入執行時。

功能索引

標準工作流

1. 固定診斷環境

記錄 Python、檢查器、編輯器外掛、依賴與型別宣告版本，讀取實際生效配置、專案根目錄、虛擬環境、包含/排除範圍和 CI 命令。不能只憑編輯器截圖判斷。

2. 建立最小診斷切片

保留報錯行、相關宣告、賦值來源、控制流和呼叫點，刪去無關業務內容但不改變型別關係。確認最小切片與原專案產生相同診斷。

3. 分類診斷來源

標記為真實執行風險、註解與實現不一致、推斷資訊不足、第三方宣告問題、配置/版本差異或檢查器限制。多條錯誤先找共同上游，避免逐條打補丁。

4. 還原執行時契約

回答值在執行時可能是什麼、誰建立、誰消費、是否可變、失敗如何表達。若註解與真實行為衝突，先決定應該改實現還是改契約，不能預設放寬型別。

5. 追蹤型別資料流

沿初始化、分支、守衛、迴圈、閉包、非同步邊界和容器變異追蹤型別變化。對可空值和聯合型別，檢查收窄後是否再次賦值或跨越不可證明的呼叫邊界。

6. 評估介面影響

公開函式、基類、協議、回撥和序列化模型的註解會影響呼叫者。列出向後相容、子型別替換、過載順序和執行時反射影響，再選擇修正位置。

7. 設計最小修正

優先補充真實守衛、修正錯誤返回、提取穩定變數、精確宣告容器、拆分過寬聯合或完善協議。斷言、型別轉換和區域性忽略必須附帶執行時不變數或外部宣告缺陷證據。

8. 雙軌驗證

執行聚焦型別檢查與相關執行測試，覆蓋正常、空值、異常和邊界輸入。檢查診斷數量下降的同時，確認沒有新增更寬的 Any、不可達分支或公共介面破壞。

9. 防止迴歸

儲存最小復現或型別測試，固定檢查器與宣告版本，統一本地/CI 命令。嚴格度提升按模組和錯誤族推進，不一次性製造無法審查的海量噪聲。

輸出規範

預設輸出：環境與配置、診斷清單、共同根因、執行時契約、型別資料流、候選修正對比、介面影響、推薦最小改動、型別檢查結果、執行測試結果、殘餘風險和遷移建議。

每條診斷使用 RUNTIME_DEFECT、ANNOTATION_MISMATCH、INFERENCE_GAP、EXTERNAL_STUB、CONFIG_DRIFT、CHECKER_LIMIT 或 UNKNOWN。型別通過不等於執行正確，必須分開報告。

能力邊界

• 不用全域性 Any、全域性關閉規則或整庫忽略清空診斷
• 不把型別轉換當執行時驗證

  7w4.net收錄了海量優質技能外掛。

• 不為滿足檢查器擅自改變業務返回值或異常語義
• 不假設第三方宣告永遠等於執行行為
• 不把一種檢查器的擴充套件語義說成語言標準
• 不在未評估呼叫方時收窄公共介面
• 不替代執行測試、屬性測試和生產監控

穩定性保障

• 固定檢查器、直譯器、依賴與宣告版本
• 讀取實際生效配置和檢查檔案集合
• 從共同上游錯誤開始修復
• 保留診斷前後數量與類別差異
• 對 cast、斷言和忽略記錄證據
• 型別檢查與執行測試雙軌驗收
• 公共介面改動單獨審查
• 嚴格度按模組漸進推進並設錯誤預算

深度定製

庫專案增加公共 API、相容版本和聲明發布；Web 服務增加請求模型、可空欄位、依賴注入和非同步邊界；資料專案增加表格物件、缺失值、陣列形狀和動態欄位；外掛體系增加協議、登錄檔與動態匯入；遺留專案增加基線快照、模組分層和忽略到期日。

若框架大量依賴執行時魔法，先尋找官方宣告或外掛機制；不要用更寬註解模擬未知行為。

FAQ

型別檢查通過，程式碼就不會報錯嗎？

不會。靜態檢查只覆蓋其模型能表達和看到的契約；網路、資料、併發、反射和執行時版本仍需測試。

可以用型別轉換快速消除錯誤嗎？

只有當你能證明執行時不變數且檢查器無法推斷時。型別轉換不檢查值，錯誤證明會把風險推遲到執行時。

第三方庫沒有型別宣告怎麼辦？

先確認是否有隨包宣告或獨立宣告包，再把動態邊界封裝在小範圍適配層，配合執行驗證；不要讓未知型別擴散全專案。

是否應該一次開啟最嚴格模式？

新專案可以評估；遺留專案更適合按模組和高風險錯誤族推進，保持每批可審查、可回退。

反模式與修正

按需 references

• 遇到聯合、泛型、協議、過載和第三方宣告問題時，讀取 diagnostic-triage.md
• 需要建立嚴格模式遷移和質量門禁時，讀取 migration-gates.md

這個助手能幫助你理解和修復 Python 型別檢查的錯誤，文件結構清晰、內容組織有序。優點是提供了系統的工作流程，能區分錯誤的不同來源，避免常見的修復陷阱。不足是缺少實際使用示例，參考文件內容較為簡略，建議配合官方文件補充學習。整體質量良好，適合有 Python 開發經驗的使用者使用。