你是不是也遇到過這種情況AI 編程助手幫你寫好了整整一個模塊代碼結構完整、注釋規范、命名講究你幾乎準備直接提交了。結果仔細一查發現它調用了一個你從沒聽過的 API再順著文檔去找這個 API 三年前就被移除了。或者更隱蔽一點它在 requirements 里“認真”地加了一個依賴PyPI 上確實能看到這個名字但包作者是一周前注冊的用戶。AI Agent 編程工具比如 Claude Code、Cursor已經進入日常開發流程。于是AI 在代碼里的“編造”也從聊天機器人的無害胡說升級成一種直接影響代碼庫質量、依賴安全甚至線上穩定性的工程風險。Ledgerful 正是沖著這個問題來的一個運行在本地、專門捕捉“AI 在代碼里發明東西”的工具。這篇文章要做三件事第一拆解 AI 代碼幻覺到底長什么樣為什么常規的語法檢查、code review 和單元測試都很難攔住它第二講解 Ledgerful 這類工具的核心設計——為什么它把“生成”和“證明”分開以及賬本機制在驗證流程中的作用第三給出一個可以獨立跑起來的最小本地檢測器實現包括依賴核驗、API 存在性檢查和語法檢查并把它接進 pre-commit 和 CI。如果你正在用 AI 編程助手或者正準備在團隊里引入 AI Agent 開發流程這篇文章值得讀完。讀完之后你會對“AI 生成的代碼能否被信任”有一個更實際的判斷標準也能在自己項目里快速搭出一個初級版本的“幻覺攔截器”。1. AI 代碼幻覺為什么這么快就變成了工程問題1.1 從“內容胡說”到“代碼事故”前兩年我們談 AI 幻覺主要談的是文本生成——AI 寫一篇技術文章可能把不存在的論文引用編得煞有介事。那最多算“內容風險”你只要不拿去投稿損失有限。但代碼生成把這個問題完全放大了。代碼幻覺一旦進入倉庫它會變成真實的進程、真實的網絡請求、真實的依賴樹和真實的線上事故。AI Agent 編程的典型流程是你給它一個需求它生成一段或多段代碼然后你 review、測試、合入。問題在于Agent 生成代碼的“置信度”很高它不會在代碼旁邊標注“這段我不確定”。一個沒見過AutoTuner類的模型依然會把它寫得像真的一樣參數合理、調用鏈完整、返回類型對得上。從文本上看它和正確的代碼幾乎無法區分。這里的核心矛盾是AI 生成的代碼外在形態越來越像人寫的代碼但它的“事實依據”并沒有被任何東西保證。人類程序員寫錯代碼通常是因為疏忽或理解偏差AI 幻覺則是一種“自信的編造”——它不是在犯錯而是在生成一個語法正確、結構完整、但外部事實可能完全不存在的東西。這個區別非常重要因為它決定了我們不能沿用傳統的方式去審查 AI 代碼。1.2 為什么常規檢查兜不住有人會說項目里有 linter、有編譯、有單元測試、有 code review這些機制加起來難道還攔不住幻覺先說編譯和語法檢查。語法檢查只能保證代碼“能被解釋器讀出來”但幻覺代碼往往是語法完全正確的。你調用一個不存在的 APIPython 解釋器只有在那行代碼執行到的時候才會拋AttributeError如果這個分支在測試里沒覆蓋到它就會安靜地在生產環境里炸開。再說 code review。它的核心弱點是“自動化偏見”當一段代碼結構完整、命名規范、注釋說明清晰時reviewer 的警惕性會明顯下降。更麻煩的是很多幻覺代碼表面上的正確性本來就比人類錯誤更難識別——至少人類同事寫錯時會猶猶豫豫AI 生成時卻永遠理直氣壯。你很難對一個“看起來合理的東西”保持足夠的懷疑。最后是單元測試。測試能驗證“這個函數對給定輸入是否返回預期輸出”但很難驗證“這個函數所依賴的外部世界是否真實存在”。import some_made_up_package之后如果代碼路徑根本沒執行到測試全部綠了也不會發現依賴是假的等到部署時包管理器才報錯才是最典型的“幻覺漏網現場”。所以我們需要一個獨立于現有檢查體系的驗證層機制上不假設 AI 生成的內容是真的而是用賬本、證據鏈和自動核驗去確認它的真實性。這正是 Ledgerful 想做的事。2. 先弄清楚AI 在代碼里的“編造”到底長什么樣2.1 五種常見幻覺類型要把幻覺檢測做好先得知道幻覺有哪些形態。結合我在項目里見過的案例AI 代碼幻覺大致可以分成五類幻覺類型典型表現為什么難以發現檢測思路虛構 API調用不存在的函數、類、方法語法正確運行到對應代碼行才報錯文檔索引、類型系統、運行時反射核驗虛假依賴添加不存在的包或真實但可疑的包代碼不執行到對應 import 就不會暴露查詢 PyPI 或內部包源核對包名與版本過期用法使用已刪除或廢棄的接口舊文檔在網上大量存在模型容易“學習”到對照版本化文檔和發布說明虛假配置寫入不存在的配置項或權限策略很多服務會靜默忽略未知配置不報錯用配置 schema 做白名單校驗自洽但錯誤的業務邏輯邏輯完整、方向錯誤測試按錯誤的業務規則寫結果全部通過領域規則校驗人工復核五類幻覺有一個共同特征它們都不是“明顯的語法錯誤”而是“語法正確但事實不成立”。這也解釋了為什么傳統工具鏈對它們基本失靈。2.2 一個看起來非常真實的錯誤示例我們用一個假想的例子來感受一下。假設 AI 生成了一段“自動調參”代碼from future_ml import AutoTuner tuner AutoTuner(modebayesian) result tuner.optimize( datasetiris, target_metricaccuracy, max_trials50, ) print(result.best_params)這段代碼的問題在于future_ml這個包不一定存在AutoTuner類也不一定存在于任何真實包里optimize方法的簽名、best_params屬性都可能是模型“順理成章”編出來的。但從閱讀體驗看它變量命名合理、參數結構完整、函數調用鏈自洽——如果 AI 把它作為“參考實現”給你你可能只會疑惑“我怎么沒用過這個庫”。這才是 AI 代碼幻覺最麻煩的地方它編造的不是一個明顯錯誤的fake_function()而是一整套相互自洽的假象。檢測工具要做的是去驗證這些“合理”背后的“事實”是否真實存在。3. Ledgerful 的核心設計把“生成”和“證明”分開3.1 賬本到底記什么Ledgerful 這個名字很有意思。Ledger 是“賬本”的意思。它把 AI 生成代碼的過程看成一筆一筆“待記賬的交易”模型生成了什么、來自哪個會話、做了哪些檢查、檢查結果如何、有沒有人復核過——這些信息按條目記錄形成一條可追蹤的驗證鏈。這與傳統 linter 有本質區別。linter 是“發現問題就報錯”Ledgerful 是“把問題留在證據鏈里”。它不追求一次檢查就把所有問題改正而是追求每一段 AI 生成代碼都有據可查后續任何人都能回溯這段代碼為什么被信任、依據是什么。一個賬本條目至少應該包含這些字段來源信息哪個 AI 工具、哪次會話、哪個 prompt 生成。驗證項語法、依賴、API、配置、運行行為。驗證證據檢查器返回的原始輸出比如 PyPI 的 404、AST 解析失敗的行號。狀態通過、警告、失敗、待人工復核。人工復核記錄誰看過、結果如何、是否合入。3.2 分層驗證策略從工程實踐的角度看幻覺驗證可以分成四個層次L1 靜態檢查語法解析、格式檢查、AST 結構分析。最快、最便宜但只能抓最表面問題。L2 事實核驗去包索引確認依賴是否存在、去文檔或運行時確認 API 是否存在、用 schema 校驗配置項。這是幻覺檢測的關鍵層。L3 行為驗證在隔離環境里運行代碼或測試觀察是否有異常網絡請求、異常文件寫入等行為。L4 人工復核模型無法自己證明的領域規則標記后交給人類工程師確認。Ledgerful 這類本地工具的重點一般放在 L1 和 L2因為它們在本地就能完成大部分自動化不需要頻繁觸發昂貴的外部模型評測也不需要把代碼交給第三方服務。3.3 本地優先原則“本地工具”是這個項目定位的關鍵詞。代碼審查本來就應當發生在本地倉庫和 CI 環境里而不是把整個代碼庫發給第三方服務去“審查”。本地優先意味著三件事代碼不出倉庫在線核驗只發送必要信息比如包名所有結論沉淀為本地可審計的記錄。對于看重代碼安全和企業合規的團隊這一點尤其重要。4. 構建最小可用版本環境準備與模塊拆解4.1 環境準備本文的示例使用 Python 3.10 以上版本因為要用標準庫的ast解析和importlib.metadata。你需要準備一個 git 倉庫最好已經初始化。Python 3.10 環境。pre-commit可選用于本地 Git 鉤子集成。能夠訪問 PyPI 的網絡環境用于包核驗或者配置內部代理源。為了最大程度降低復現成本最小版本不引入任何第三方依賴全部使用 Python 標準庫。這也符合工具定位它只是一個本地校驗器不承擔重型分析任務。4.2 項目結構一個最小可用版本可以這樣組織ledgerful-demo/ ├── ledgerful/ │ ├── __init__.py │ ├── cli.py # 命令行入口接收文件并調用驗證器 │ ├── collector.py # 獲取 git 暫存區或指定目錄的 Python 文件 │ ├── verifiers/ │ │ ├── __init__.py │ │ ├── syntax_check.py # L1 靜態檢查AST 語法解析 │ │ ├── deps_check.py # L2 事實核驗依賴包與 import 核驗 │ │ └── api_check.py # L2 事實核驗API 存在性檢查 │ ├── ledger.py # 生成/更新賬本記錄 │ └── reporters.py # 匯總輸出格式化打印 ├── .pre-commit-hooks.yaml └── pyproject.tomlcollector.py負責收集“要檢查的文件”verifiers目錄放各層檢查器ledger.py負責把結果寫入賬本reporters.py負責任務結束后的匯總打印。這個結構的好處是每個驗證器都可以獨立添加和測試后續要支持 JS、Go 或者其他語言時只需要新增對應驗證器。5. 核心代碼實現一個本地“代碼幻覺檢測器”5.1 命令行入口與 Git 暫存區采集先寫命令行入口。為了讓它能在 pre-commit 里工作我們支持兩種模式指定文件路徑或者使用--staged參數讀取 git 暫存區中的 Python 文件。# ledgerful/cli.py import argparse import pathlib import subprocess import sys from ledgerful.verifiers.syntax_check import syntax_check from ledgerful.verifiers.deps_check import deps_check from ledgerful.verifiers.api_check import api_check from ledgerful.ledger import append_entry from ledgerful.reporters import print_report def get_staged_python_files() - list[str]: 獲取 git 暫存區中新增、修改、復制、重命名的 Python 文件。 result subprocess.run( [git, diff, --cached, --name-only, --diff-filterACM], capture_outputTrue, textTrue, checkTrue, ) files [] for line in result.stdout.splitlines(): if line.endswith(.py) and pathlib.Path(line).exists(): files.append(line) return files def run_checks(file_path: str) - dict: 依次運行所有驗證器返回該文件的檢查結果。 results { file: file_path, checks: [], status: pass, } syntax_result syntax_check(file_path) deps_result deps_check(file_path) api_result api_check(file_path) results[checks] [ {name: syntax, **syntax_result}, {name: deps, **deps_result}, {name: api, **api_result}, ] if any(item[status] fail for item in results[checks]): results[status] fail elif any(item[status] warn for item in results[checks]): results[status] warn return results def main() - int: parser argparse.ArgumentParser( descriptionLedgerful - local AI hallucination checker ) parser.add_argument(targets, nargs*, help要檢查的文件或目錄) parser.add_argument(--staged, actionstore_true, help只檢查 git 暫存區) args parser.parse_args() targets args.targets if args.staged: targets get_staged_python_files() if not targets: print(No Python files to check.) return 0 all_results [] exit_code 0 for file_path in targets: result run_checks(file_path) all_results.append(result) append_entry(result) if result[status] fail: exit_code 1 print_report(all_results) return exit_code if __name__ __main__: sys.exit(main())這段代碼的邏輯很直接get_staged_python_files調用 git 命令拿到暫存區文件run_checks依次執行三個驗證器append_entry把結果寫入賬本最后統一打印。真正容易踩坑的地方是如果你的 repo 里有很多 Python 文件都在暫存區每個文件都去跑一遍 PyPI 網絡查詢會非常慢。實際使用中建議把“在線核驗”放到 CI 階段本地只跑語法和靜態檢查或者為常見的包名做一層緩存。5.2 語法檢查器用 AST 抓最表層的錯誤接下來是語法檢查器。使用ast.parse而非compile是因為ast.parse可以直接定位出錯的行號和列號便于在賬本里保存結構化證據。# ledgerful/verifiers/syntax_check.py import ast from pathlib import Path def syntax_check(path: str) - dict: 檢查 Python 文件語法是否合法。 try: source Path(path).read_text(encodingutf-8) ast.parse(source, filenamestr(path)) return {status: pass, detail: syntax ok} except SyntaxError as e: return { status: fail, detail: fSyntaxError at line {e.lineno}: { AI代碼幻覺檢測：用Ledgerful構建本地驗證管道
你是不是也遇到過這種情況AI 編程助手幫你寫好了整整一個模塊代碼結構完整、注釋規范、命名講究你幾乎準備直接提交了。結果仔細一查發現它調用了一個你從沒聽過的 API再順著文檔去找這個 API 三年前就被移除了。或者更隱蔽一點它在 requirements 里“認真”地加了一個依賴PyPI 上確實能看到這個名字但包作者是一周前注冊的用戶。AI Agent 編程工具比如 Claude Code、Cursor已經進入日常開發流程。于是AI 在代碼里的“編造”也從聊天機器人的無害胡說升級成一種直接影響代碼庫質量、依賴安全甚至線上穩定性的工程風險。Ledgerful 正是沖著這個問題來的一個運行在本地、專門捕捉“AI 在代碼里發明東西”的工具。這篇文章要做三件事第一拆解 AI 代碼幻覺到底長什么樣為什么常規的語法檢查、code review 和單元測試都很難攔住它第二講解 Ledgerful 這類工具的核心設計——為什么它把“生成”和“證明”分開以及賬本機制在驗證流程中的作用第三給出一個可以獨立跑起來的最小本地檢測器實現包括依賴核驗、API 存在性檢查和語法檢查并把它接進 pre-commit 和 CI。如果你正在用 AI 編程助手或者正準備在團隊里引入 AI Agent 開發流程這篇文章值得讀完。讀完之后你會對“AI 生成的代碼能否被信任”有一個更實際的判斷標準也能在自己項目里快速搭出一個初級版本的“幻覺攔截器”。1. AI 代碼幻覺為什么這么快就變成了工程問題1.1 從“內容胡說”到“代碼事故”前兩年我們談 AI 幻覺主要談的是文本生成——AI 寫一篇技術文章可能把不存在的論文引用編得煞有介事。那最多算“內容風險”你只要不拿去投稿損失有限。但代碼生成把這個問題完全放大了。代碼幻覺一旦進入倉庫它會變成真實的進程、真實的網絡請求、真實的依賴樹和真實的線上事故。AI Agent 編程的典型流程是你給它一個需求它生成一段或多段代碼然后你 review、測試、合入。問題在于Agent 生成代碼的“置信度”很高它不會在代碼旁邊標注“這段我不確定”。一個沒見過AutoTuner類的模型依然會把它寫得像真的一樣參數合理、調用鏈完整、返回類型對得上。從文本上看它和正確的代碼幾乎無法區分。這里的核心矛盾是AI 生成的代碼外在形態越來越像人寫的代碼但它的“事實依據”并沒有被任何東西保證。人類程序員寫錯代碼通常是因為疏忽或理解偏差AI 幻覺則是一種“自信的編造”——它不是在犯錯而是在生成一個語法正確、結構完整、但外部事實可能完全不存在的東西。這個區別非常重要因為它決定了我們不能沿用傳統的方式去審查 AI 代碼。1.2 為什么常規檢查兜不住有人會說項目里有 linter、有編譯、有單元測試、有 code review這些機制加起來難道還攔不住幻覺先說編譯和語法檢查。語法檢查只能保證代碼“能被解釋器讀出來”但幻覺代碼往往是語法完全正確的。你調用一個不存在的 APIPython 解釋器只有在那行代碼執行到的時候才會拋AttributeError如果這個分支在測試里沒覆蓋到它就會安靜地在生產環境里炸開。再說 code review。它的核心弱點是“自動化偏見”當一段代碼結構完整、命名規范、注釋說明清晰時reviewer 的警惕性會明顯下降。更麻煩的是很多幻覺代碼表面上的正確性本來就比人類錯誤更難識別——至少人類同事寫錯時會猶猶豫豫AI 生成時卻永遠理直氣壯。你很難對一個“看起來合理的東西”保持足夠的懷疑。最后是單元測試。測試能驗證“這個函數對給定輸入是否返回預期輸出”但很難驗證“這個函數所依賴的外部世界是否真實存在”。import some_made_up_package之后如果代碼路徑根本沒執行到測試全部綠了也不會發現依賴是假的等到部署時包管理器才報錯才是最典型的“幻覺漏網現場”。所以我們需要一個獨立于現有檢查體系的驗證層機制上不假設 AI 生成的內容是真的而是用賬本、證據鏈和自動核驗去確認它的真實性。這正是 Ledgerful 想做的事。2. 先弄清楚AI 在代碼里的“編造”到底長什么樣2.1 五種常見幻覺類型要把幻覺檢測做好先得知道幻覺有哪些形態。結合我在項目里見過的案例AI 代碼幻覺大致可以分成五類幻覺類型典型表現為什么難以發現檢測思路虛構 API調用不存在的函數、類、方法語法正確運行到對應代碼行才報錯文檔索引、類型系統、運行時反射核驗虛假依賴添加不存在的包或真實但可疑的包代碼不執行到對應 import 就不會暴露查詢 PyPI 或內部包源核對包名與版本過期用法使用已刪除或廢棄的接口舊文檔在網上大量存在模型容易“學習”到對照版本化文檔和發布說明虛假配置寫入不存在的配置項或權限策略很多服務會靜默忽略未知配置不報錯用配置 schema 做白名單校驗自洽但錯誤的業務邏輯邏輯完整、方向錯誤測試按錯誤的業務規則寫結果全部通過領域規則校驗人工復核五類幻覺有一個共同特征它們都不是“明顯的語法錯誤”而是“語法正確但事實不成立”。這也解釋了為什么傳統工具鏈對它們基本失靈。2.2 一個看起來非常真實的錯誤示例我們用一個假想的例子來感受一下。假設 AI 生成了一段“自動調參”代碼from future_ml import AutoTuner tuner AutoTuner(modebayesian) result tuner.optimize( datasetiris, target_metricaccuracy, max_trials50, ) print(result.best_params)這段代碼的問題在于future_ml這個包不一定存在AutoTuner類也不一定存在于任何真實包里optimize方法的簽名、best_params屬性都可能是模型“順理成章”編出來的。但從閱讀體驗看它變量命名合理、參數結構完整、函數調用鏈自洽——如果 AI 把它作為“參考實現”給你你可能只會疑惑“我怎么沒用過這個庫”。這才是 AI 代碼幻覺最麻煩的地方它編造的不是一個明顯錯誤的fake_function()而是一整套相互自洽的假象。檢測工具要做的是去驗證這些“合理”背后的“事實”是否真實存在。3. Ledgerful 的核心設計把“生成”和“證明”分開3.1 賬本到底記什么Ledgerful 這個名字很有意思。Ledger 是“賬本”的意思。它把 AI 生成代碼的過程看成一筆一筆“待記賬的交易”模型生成了什么、來自哪個會話、做了哪些檢查、檢查結果如何、有沒有人復核過——這些信息按條目記錄形成一條可追蹤的驗證鏈。這與傳統 linter 有本質區別。linter 是“發現問題就報錯”Ledgerful 是“把問題留在證據鏈里”。它不追求一次檢查就把所有問題改正而是追求每一段 AI 生成代碼都有據可查后續任何人都能回溯這段代碼為什么被信任、依據是什么。一個賬本條目至少應該包含這些字段來源信息哪個 AI 工具、哪次會話、哪個 prompt 生成。驗證項語法、依賴、API、配置、運行行為。驗證證據檢查器返回的原始輸出比如 PyPI 的 404、AST 解析失敗的行號。狀態通過、警告、失敗、待人工復核。人工復核記錄誰看過、結果如何、是否合入。3.2 分層驗證策略從工程實踐的角度看幻覺驗證可以分成四個層次L1 靜態檢查語法解析、格式檢查、AST 結構分析。最快、最便宜但只能抓最表面問題。L2 事實核驗去包索引確認依賴是否存在、去文檔或運行時確認 API 是否存在、用 schema 校驗配置項。這是幻覺檢測的關鍵層。L3 行為驗證在隔離環境里運行代碼或測試觀察是否有異常網絡請求、異常文件寫入等行為。L4 人工復核模型無法自己證明的領域規則標記后交給人類工程師確認。Ledgerful 這類本地工具的重點一般放在 L1 和 L2因為它們在本地就能完成大部分自動化不需要頻繁觸發昂貴的外部模型評測也不需要把代碼交給第三方服務。3.3 本地優先原則“本地工具”是這個項目定位的關鍵詞。代碼審查本來就應當發生在本地倉庫和 CI 環境里而不是把整個代碼庫發給第三方服務去“審查”。本地優先意味著三件事代碼不出倉庫在線核驗只發送必要信息比如包名所有結論沉淀為本地可審計的記錄。對于看重代碼安全和企業合規的團隊這一點尤其重要。4. 構建最小可用版本環境準備與模塊拆解4.1 環境準備本文的示例使用 Python 3.10 以上版本因為要用標準庫的ast解析和importlib.metadata。你需要準備一個 git 倉庫最好已經初始化。Python 3.10 環境。pre-commit可選用于本地 Git 鉤子集成。能夠訪問 PyPI 的網絡環境用于包核驗或者配置內部代理源。為了最大程度降低復現成本最小版本不引入任何第三方依賴全部使用 Python 標準庫。這也符合工具定位它只是一個本地校驗器不承擔重型分析任務。4.2 項目結構一個最小可用版本可以這樣組織ledgerful-demo/ ├── ledgerful/ │ ├── __init__.py │ ├── cli.py # 命令行入口接收文件并調用驗證器 │ ├── collector.py # 獲取 git 暫存區或指定目錄的 Python 文件 │ ├── verifiers/ │ │ ├── __init__.py │ │ ├── syntax_check.py # L1 靜態檢查AST 語法解析 │ │ ├── deps_check.py # L2 事實核驗依賴包與 import 核驗 │ │ └── api_check.py # L2 事實核驗API 存在性檢查 │ ├── ledger.py # 生成/更新賬本記錄 │ └── reporters.py # 匯總輸出格式化打印 ├── .pre-commit-hooks.yaml └── pyproject.tomlcollector.py負責收集“要檢查的文件”verifiers目錄放各層檢查器ledger.py負責把結果寫入賬本reporters.py負責任務結束后的匯總打印。這個結構的好處是每個驗證器都可以獨立添加和測試后續要支持 JS、Go 或者其他語言時只需要新增對應驗證器。5. 核心代碼實現一個本地“代碼幻覺檢測器”5.1 命令行入口與 Git 暫存區采集先寫命令行入口。為了讓它能在 pre-commit 里工作我們支持兩種模式指定文件路徑或者使用--staged參數讀取 git 暫存區中的 Python 文件。# ledgerful/cli.py import argparse import pathlib import subprocess import sys from ledgerful.verifiers.syntax_check import syntax_check from ledgerful.verifiers.deps_check import deps_check from ledgerful.verifiers.api_check import api_check from ledgerful.ledger import append_entry from ledgerful.reporters import print_report def get_staged_python_files() - list[str]: 獲取 git 暫存區中新增、修改、復制、重命名的 Python 文件。 result subprocess.run( [git, diff, --cached, --name-only, --diff-filterACM], capture_outputTrue, textTrue, checkTrue, ) files [] for line in result.stdout.splitlines(): if line.endswith(.py) and pathlib.Path(line).exists(): files.append(line) return files def run_checks(file_path: str) - dict: 依次運行所有驗證器返回該文件的檢查結果。 results { file: file_path, checks: [], status: pass, } syntax_result syntax_check(file_path) deps_result deps_check(file_path) api_result api_check(file_path) results[checks] [ {name: syntax, **syntax_result}, {name: deps, **deps_result}, {name: api, **api_result}, ] if any(item[status] fail for item in results[checks]): results[status] fail elif any(item[status] warn for item in results[checks]): results[status] warn return results def main() - int: parser argparse.ArgumentParser( descriptionLedgerful - local AI hallucination checker ) parser.add_argument(targets, nargs*, help要檢查的文件或目錄) parser.add_argument(--staged, actionstore_true, help只檢查 git 暫存區) args parser.parse_args() targets args.targets if args.staged: targets get_staged_python_files() if not targets: print(No Python files to check.) return 0 all_results [] exit_code 0 for file_path in targets: result run_checks(file_path) all_results.append(result) append_entry(result) if result[status] fail: exit_code 1 print_report(all_results) return exit_code if __name__ __main__: sys.exit(main())這段代碼的邏輯很直接get_staged_python_files調用 git 命令拿到暫存區文件run_checks依次執行三個驗證器append_entry把結果寫入賬本最后統一打印。真正容易踩坑的地方是如果你的 repo 里有很多 Python 文件都在暫存區每個文件都去跑一遍 PyPI 網絡查詢會非常慢。實際使用中建議把“在線核驗”放到 CI 階段本地只跑語法和靜態檢查或者為常見的包名做一層緩存。5.2 語法檢查器用 AST 抓最表層的錯誤接下來是語法檢查器。使用ast.parse而非compile是因為ast.parse可以直接定位出錯的行號和列號便于在賬本里保存結構化證據。# ledgerful/verifiers/syntax_check.py import ast from pathlib import Path def syntax_check(path: str) - dict: 檢查 Python 文件語法是否合法。 try: source Path(path).read_text(encodingutf-8) ast.parse(source, filenamestr(path)) return {status: pass, detail: syntax ok} except SyntaxError as e: return { status: fail, detail: fSyntaxError at line {e.lineno}: {