simonw / llm · 原始碼導讀

這份指南是依分析器課程排出的閱讀順序，不是程式碼清單，也不是教學：四個閱讀站點（定位、執行故事、核心程式碼、修改指南），外加最後一節限制說明，每一站都由分析器可依行定位的區塊組成，例如 llm/__main__.py:1-4。下面每一個行號範圍都寫成 path:start-end，就是分析器在被分析版本的檔案中為該區塊記錄的 lines 值；範圍從不另外計算或擴大。區塊是分析器可依行定位的程式碼單位，它的描述是分析器附帶信心分數的推論（那個 module 區塊是 0.97），所以請把區塊文字當作指引，而不是已確定的事實。凡是引用簽名的地方，都是分析器符號記錄裡的單行簽名。分析器把 README.md、pyproject.toml 和 LICENSE 歸為專案層級的重要檔案，並建議早點讀。這裡沒有任何安裝、執行或 shell 步驟，因為安裝指令沒有驗證。repository 的平台 metadata 把它描述為一種從命令列存取大型語言模型的方式；這個描述屬於作者自述。

分析器的摘要推論這是一個有 116 個被分析檔案的 Python 專案，圍繞 docs、llm 和 tests 組織，llm/__main__.py 看起來是主要起點；因此，定位課程的兩個檔案層級 module 區塊 llm/__main__.py:1-4 和 llm/cli.py:1-4407，就是最先要讀的目標：在後面的站點深入特定範圍之前，先讀它們掌握配置。llm/__main__.py 是一個標記為 verified 的進入點，記錄到的直接執行摘錄會呼叫 cli 函式；另一筆標記為 verified 的進入點記錄指向 llm/cli.py，角色表把它標為 entry/orchestration 候選，有 105 個呼入和 245 個靜態呼出。

• llm/__main__.py:1-4：module 區塊，符號 llm/__main__.py：被描述為 llm/__main__.py 裡被分析程式碼的檔案層級容器（信心值 0.97）。
• llm/cli.py:1-4407：module 區塊，符號 llm/cli.py：被描述為 llm/cli.py 裡被分析程式碼的檔案層級容器（信心值 0.76）；角色表把這個檔案標為 entry/orchestration 候選（105 個呼入、245 個呼出）。

接著讀執行故事課程：四個區塊描繪分析器怎麼重建一次執行，外加分析資料列出的有界路徑。分析器重建了 13 條有界執行路徑，分析資料列出其中 5 條：一條從進入點 llm/__main__.py:__main__ 以本地呼叫走到 llm/cli.py 裡的 cli，然後以葉節點結束；另外四條從 llm/cli.py 出發，停在未解析的邊界：warnings.simplefilter，或是經由 load_plugins 到達的 hasattr、pm.load_setuptools_entrypoints 或 LLM_LOAD_PLUGINS.split。這些是靜態的重建，不是執行時的證明：分析器不解析反射、動態 import 或動態分派。

• llm/__main__.py:3-4：main_guard，符號 __main__：控制 Python 檔案被直接執行（而不只是被 import）時應該跑的程式碼（信心值 0.99）。
• llm/cli.py:541-565：function，cli：封裝一個具名的操作，這個區塊不需要任何已解析的下游關係（信心值 0.97）；記錄的簽名是 def cli():。
• llm/cli.py:1-4407：module，llm/cli.py：llm/cli.py 裡被分析程式碼的檔案層級容器（信心值 0.76）。
• llm/plugins.py:23-52：function，load_plugins：封裝一個操作，連到 11 條下游呼叫或 import 關係（信心值 0.76）；記錄的簽名是 def load_plugins():。

核心程式碼課程為主要實作提供了一組八個區塊的精簡讀物；進入點守衛、cli 和 load_plugins 在第 2 站也出現過，這裡新增的有五個區塊。這組讀物超出 llm/ 套件，延伸到 docs/conf.py：那裡的 markdown_admonitions 連到 11 條下游關係，setup 則連到 1 條；只有在那個檔案的行為和你有關時才需要讀。最後幾個 llm/cli.py 區塊涵蓋一個例外類別 FragmentNotFound，以及兩個輔助函式，分析器說它們各自連到 4 條下游關係。

• llm/__main__.py:3-4：main_guard，__main__：控制檔案被直接執行（而不只是被 import）時應該跑的程式碼（信心值 0.99）。
• llm/cli.py:541-565：function，cli：封裝一個具名的操作，這個區塊不需要任何已解析的下游關係（信心值 0.97）。
• llm/plugins.py:23-52：function，load_plugins：封裝一個操作，連到 11 條下游呼叫或 import 關係（信心值 0.76）。
• docs/conf.py:6-21：function，markdown_admonitions：封裝一個操作，連到 11 條下游呼叫或 import 關係（信心值 0.76）。
• docs/conf.py:24-25：function，setup：封裝一個操作，連到 1 條下游呼叫或 import 關係（信心值 0.76）。
• llm/cli.py:99-100：class，FragmentNotFound：把相關的行為歸在同一個類別邊界裡（信心值 0.97）；記錄的簽名是 class FragmentNotFound(Exception):。
• llm/cli.py:103-119：function，display_stream_events：封裝一個操作，連到 4 條下游呼叫或 import 關係（信心值 0.76）。
• llm/cli.py:122-133：function，display_async_stream_events：封裝一個操作，連到 4 條下游呼叫或 import 關係（信心值 0.76）。

規劃修改時，以修改指南課程的六個區塊為中心；分析器列出它們，是為了讓你在規劃修改時排定優先順序。記錄到最多下游關係的兩個是 prompt（119）和 logs_list（116）。get_model 在 llm/__init__.py 裡出現三次（function、straight_line 和 try 區塊），角色表把 llm/__init__.py 標為 service/core 候選，有 754 個呼入，llm/parts.py 也是，有 470 個。

• llm/parts.py:313-360：class，StreamEvent：把相關的行為歸在同一個類別邊界裡（信心值 0.97）；記錄的簽名是 class StreamEvent:。
• llm/cli.py:685-1187：function，prompt：封裝一個操作，連到 119 條下游呼叫或 import 關係（信心值 0.76）。
• llm/__init__.py:345-363：function，get_model：封裝一個操作，連到 6 條下游呼叫或 import 關係（信心值 0.97）；記錄的簽名是 def get_model(name: str | None = None, _skip_async: bool = False) -> Model:。
• llm/cli.py:1878-2379：function，logs_list：封裝一個操作，連到 116 條下游呼叫或 import 關係（信心值 0.76）。
• llm/__init__.py:349-363：try，get_model：把一個帶有明確例外處理控制流的操作歸在一起（信心值 0.97）。
• llm/__init__.py:347-348：straight_line，get_model：把相鄰的循序陳述式歸在一起，讓它們可以當作一個有界的區域來說明（信心值 0.96）。

這次分析只有靜態的部分：反射、執行期依賴注入、動態 import、monkey-patching、產生的程式碼、框架在執行期的接線和動態分派都沒有解析，所以列出的路徑背後的執行時行為無法確定。安裝／執行／建置的推論並不完整，安裝指令也沒有驗證，這就是為什麼這份導讀沒有任何執行步驟。依賴記錄只來自分析器 v0.10 解析的 requirements 形式清單檔；pyproject.toml 的依賴表不會被解析。README 陳述的擷取是逐行進行的，可能抓到程式碼行而不是說明性的陳述，所以來自 README 的文字最多只能當作作者自述。分析器記錄的能力描述的是分析器本身，不是這個 repository，所以不算在 repository 的證據裡。最後，區塊註解仍是分析器附帶信心分數的推論，不是經過驗證的執行時行為描述。