simonw / llm · 架構

分析器的摘要描述這是一個有 116 個被分析檔案的 Python 專案，圍繞三個目錄子系統組織：docs、llm 和 tests。檔案清單算到根目錄 11 個檔案、.github 6 個、docs 35 個、llm 20 個、tests 44 個，整體共記錄到 44 個類測試檔案。

llm 套件裡放著角色記錄點名為活躍程式碼的路徑：cli.py、plugins.py、models.py、logs.py、migrations.py、utils.py、parts.py 和 default_plugins/openai_models.py。在根目錄，README.md、pyproject.toml 和 LICENSE 被標為專案層級的重要檔案，llm/__main__.py 和 llm/cli.py 則被標為可能的進入點。唯一解析出的依賴記錄來自 docs/requirements.txt（sphinx 及相關工具），所以 docs 負責的是文件的建置。

偵測到兩個進入點：llm/__main__.py，它的 __main__ 守衛呼叫 cli()；以及依檔名啟發式規則被標為可能可執行的 llm/cli.py。從 llm/__main__.py 出發的有界路徑，只以一步本地呼叫走到 llm/cli.py:cli，然後以葉節點結束，沒有循環也沒有截斷。

從 llm/cli.py 出發，有一條路徑馬上停在 warnings.simplefilter。另有八條路徑深入 llm/plugins.py [load_plugins]，停在外部或未解析的目標：hasattr、pm.load_setuptools_entrypoints、LLM_LOAD_PLUGINS.split、name.strip、metadata.distribution、entry_point.load、pm.register 和 pm._plugin_distinfo.append。重建結果回報了 13 條有界執行路徑、2 個進入點和 2059 條已解析的呼叫關係；這份分析資料收錄了其中十條路徑。從靜態的角度讀，llm/cli.py 是第一個到達的模組，而從 llm/cli.py 追出的九條路徑中，有八條是在 load_plugins 離開已解析的呼叫圖；第九條停在 warnings.simplefilter，沒有經過 load_plugins。

這些角色標籤是分析器依已解析的靜態呼叫次數和是否屬於進入點推論出來的；它們描述的是在呼叫圖中的位置，不是設計意圖。llm/__init__.py 是連結最多的模組（754 個呼入、48 個呼出），其次是 llm/parts.py（470 個呼入、22 個呼出）；兩者都被標為 service/core 候選。llm/cli.py 帶有 entry/orchestration 標籤（105 入、245 出），和它的進入點身分一致。在函式庫模組中，llm/models.py（130 入／96 出）、llm/logs.py（123 入／64 出）、llm/utils.py（102 入／12 出）和 llm/default_plugins/openai_models.py（89 入／130 出）都被標為 service/core 候選。llm/plugins.py 位在邊緣（41 入、0 出，標為 leaf/data-boundary），附近還有 llm/migrations.py（38 入、1 出）。這些標籤反映的是呼叫量：tests/test_parts.py 因為有 422 個呼出而拿到 orchestration 標籤，tests/test_logs_store.py 則被標為 service/core。

外掛載入是最主要的邊界：從 load_plugins 出發，追蹤到的路徑到達 pm.load_setuptools_entrypoints、entry_point.load、pm.register 和 metadata.distribution，全都是外部或未解析；分析器的邊界清單還點名了 importlib.import_module，不過沒有任何執行路徑停在那裡。一般程式碼的停止點也有：llm/cli.py 停在 warnings.simplefilter，load_plugins 則碰到 hasattr、LLM_LOAD_PLUGINS.split 和 name.strip；邊界清單另外點名了 sys.stderr.write，但沒有對應的執行記錄。規模很大：9,698 條關係中有 7,374 條是 external_or_unresolved，本地的只有 2,324 條，而分析器保留的是文字形式的目標，不會捏造本地目的地。實際上，外掛載入背後的一切（安裝好的 entry point、hook 的註冊）都在這次重建之外，因為進入 load_plugins 的八條追蹤路徑全都停在 unresolved_boundary；分析器也另外記錄了動態 import 沒有被解析。

依靜態呼叫次數，llm/__init__.py 是這個套件的匯集點（754 個呼入），llm/cli.py 則是依賴這個樞紐的大量使用者（105 入、245 出）。llm/parts.py 和 llm/models.py 承擔了其餘大部分的本地呼叫量，llm/plugins.py 則是葉節點（41 個呼入、0 個呼出）。解析出的七筆依賴記錄都標為 scope 'runtime'，但來源是 docs/requirements.txt（sphinx 和文件工具），所以它們描述的是文件建置的工具鏈。因為 pyproject.toml 的依賴表沒有被解析，這次分析無法確定這個套件本身的執行期依賴。未解析的邊在圖中占多數：7,374 條 external_or_unresolved，對上 2,324 條本地，而且動態 import 明確沒有被解析。

這是一幅靜態的圖像：反射、執行期依賴注入、動態 import、monkey-patching、產生的程式碼、框架在執行期的接線和動態分派，分析器都沒有解析。外掛載入、模型解析和 logging 在執行時怎麼互動，這份分析資料無法確定。安裝／執行／建置的推論並不完整，安裝指令也沒有驗證，所以這裡沒有任何可以照做的步驟。測試以 44 個類測試檔案和呼叫圖節點的形式出現，但分析資料無法顯示它們是否通過，也無法顯示程式碼執行時的行為。在這條流程裡，來自 README 的陳述是逐行擷取的，可能抓到程式碼行，所以最多只能算作者的說法。

先讀 README.md 和 pyproject.toml 掌握整體框架，再順著執行走：llm/__main__.py、llm/cli.py:cli，然後是 llm/plugins.py [load_plugins]。分析器的教學記錄建議同樣的順序：先看清單檔和重要符號，再看有界路徑，然後是未解析的邊界。核心部分，先把 llm/__init__.py 當作樞紐來讀，再讀 llm/parts.py 和 llm/models.py。在改任何程式碼之前，最後看 tests/test_parts.py：它有 422 個呼出，因此被標為 orchestration 候選。