pydantic / pydantic-ai · 架構

分析器的摘要統計了 4,082 個分析過的檔案，GitHub metadata 記錄的主要語言是 Python。記錄到的頂層目錄大小：tests 2,501、src 498、pydantic_ai_slim 426、docs 351、.github 136、examples 63、pydantic_evals 33、pydantic_graph 18、scripts 10、clai 6、agent_docs 6、.agents 7、.claude 12。分析器把 docs、src 和 tests 當作子系統候選；它的成熟度訊號也統計出 2,514 個類測試檔案，所以測試程式碼佔了清單的大部分。依賴記錄引用了根目錄以及 pydantic_evals 和 pydantic_graph 裡的 pyproject.toml，所以至少這幾個套件各自宣告了依賴。README.md、pyproject.toml 和 LICENSE 被標為專案層級的重要檔案。GitHub 的描述提到 agent、即時語音、影像生成和 embedding，並強調從頭到尾的型別；分析資料把這段標為作者的說法，它只用來幫助定位，不是分析器的證據。

重建結果回報 65 個進入點和 580 條有界執行路徑。經驗證的 __main__ 守衛分布很廣：CI 與維護腳本（.github/scripts/agent_provider_health.py、.github/scripts/agent_spend_report.py、scripts/check_cassettes.py）、套件的 __main__ 模組（呼叫 cli_exit() 的 pydantic_ai_slim/pydantic_ai/__main__.py、呼叫 _cli.cli_exit('clai') 的 clai/clai/__main__.py、src/pydantic_clai2/pydantic_clai2/__main__.py），以及一個範例執行入口（呼叫 cli() 的 examples/pydantic_ai_examples/__main__.py）。另外三個進入點——.github/scripts/pydantic_ai_gh_aw_shim/cli.py、examples/pydantic_ai_examples/slack_lead_qualifier/app.py 和 pydantic_ai_slim/pydantic_ai/ui/_web/app.py——只依檔名推測。分析器的摘要把 .claude/skills/testing-skill/parse_cassette.py 稱為主要起點；這是綁在這個技能腳本上的推論，不是函式庫套件從那裡啟動的證據。在 580 條路徑中，逐條列出的十條都從那個腳本的 __main__ 守衛開始：模組層級呼叫 main，main 建立 argparse 的 parser、檢查 args.cassette.exists 並呼叫 parse_cassette，再到達 Cassette 和 cassette.load。這十條每一條都止於一個未解析的外部目標（argparse 呼叫、print、sys.exit、Cassette、cassette.load），終止原因是 'unresolved_boundary'；沒有一條被截斷，也沒有一條出現循環。

每筆角色記錄都寫明它的證據基礎是靜態解析的跨模組呼叫次數和進入點成員資格；這些角色是從呼叫次數推論出來的，不是執行時的觀察。呼入次數最高的：tests/clai2/menu_script.py（569 個呼入、0 個呼出；leaf/data-boundary 候選）、pydantic_ai/exceptions.py（421 入、0 出；leaf 候選）和 pydantic_ai/messages.py（403 入、70 出；service/core 候選）；tests/_inline_snapshot.py（357 入）和 pydantic_ai/_utils.py（253 入、6 出）也常被呼叫。pydantic_ai/agent/__init__.py 正好相反：4 個呼入、203 個呼出，是一個向外呼叫的樞紐；附近還有 models/openai.py（8 入、151 出）、models/google.py（8 入、78 出）、models/__init__.py（113 入、52 出）和 _agent_graph.py（24 入、100 出）。有七筆呼入為 0、呼出很多的記錄被標為 orchestration 候選：tests/durable_exec/test_dbos.py（148 出）、tests/durable_exec/test_prefect.py（88）、pydantic_ai/realtime/_session.py（128 出）、pydantic_ai/models/anthropic.py（105 出）、pydantic_ai/durable_exec/_base.py（92 出）、pydantic_ai/ui/vercel_ai/_adapter.py（92 出）和 pydantic_ai/realtime/openai_live.py（75 出）。

靜態的控制流止於分析器的解析極限，分析資料把它量化了：記錄的 150,000 條關係中，125,702 條是 external_or_unresolved，24,298 條是本地的（124,623 條呼叫、25,377 條 import）。逐條列出的十條路徑呈現出同樣的模式：每一條都以 'unresolved_boundary' 為終止原因，止於一個非本地目標，包括 argparse 的建立與解析、args.cassette.exists、print、sys.exit、Cassette、cassette.load。分析器寫明，反射、執行期依賴注入、動態 import、monkey-patching、產生的程式碼、框架的執行期接線和動態分派都沒有解析，所以外掛式或經由分派的呼叫會以未解析的目標出現，而不是本地的邊。因此，沒有本地的邊連到這類程式碼，並不代表這類程式碼不存在。

這份分析資料裡跨部分的事實來自清單記錄。pydantic_graph 的 pyproject.toml 記錄了對 anyio、logfire-api、pydantic 和 typing-inspection 的 runtime 依賴；pydantic_evals 的清單把 logfire 記錄為 optional。根目錄 pyproject.toml 的 dev 記錄涵蓋一整套工具鏈（pytest、pytest-mock、pytest-xdist、coverage、mypy、pyright 和 ruff），另外還有 redis、azure-identity、boto3-stubs、fastmcp 和 mcp-types 等套件。分析資料裡的 45 筆依賴記錄全都來自 pyproject.toml 清單，版本限制照原樣記錄；setup.py、setup.cfg、Pipfile 和 lock 檔都不會被解析。在已解析的程式碼關係上，分析資料只支持一個有界的說法：外部／未解析的邊有 125,702 條、本地的邊只有 24,298 條，而且動態接線不在範圍內，所以並沒有確立一張哪些部分依賴哪些部分的完整地圖。分析資料在本地層面確實呈現的，是上面整理的呼叫次數結構。

分析器寫明了它看不到的東西。靜態分析不解析反射、執行期依賴注入、動態 import、monkey-patching、產生的程式碼、框架的執行期接線或動態分派，所以套件之間的執行期接線看不到。安裝／執行／建置的推論並不完整，安裝指令也沒有驗證，所以這份資產不提供執行說明。有界分析會把超過 400 kB 的檔案、minified bundle 和 vendored 目錄列入清單但不解析，並把關係抽取限制在每個檔案 2,500 條、每個 repository 150,000 條；這次達到了 repository 的上限（每個檔案的截斷為 0 次），並有五個檔案被列入清單但沒有被解析。來自 README 的文字頂多只是作者的說法（author_claimed），因為抽取是逐行進行的。有三條進入點路徑沒有靜態偵測到的呼叫步驟。

從分析資料可以整理出一個可行的順序：首先看 README.md、pyproject.toml 和 LICENSE，它們都被標為專案層級的重要檔案；分析器的學習路徑陳述也建議先從清單檔和重要符號開始，再追蹤有界執行路徑、檢查未解析的邊界。第二步，逐一走過各個套件樹，包括 pydantic_ai_slim（426 個檔案）、pydantic_evals（33）、pydantic_graph（18）和 src（498），並在主套件裡從呼叫次數的熱點開始：agent/__init__.py、messages.py 和 models/__init__.py。第三步，透過 examples/pydantic_ai_examples/__main__.py 看範例怎麼啟動。最後，在修改程式碼之前，完整跟過一條記錄下來的路徑，並記下每個未解析的邊界。