huggingface / smolagents · 原始碼導讀

這份導讀勾勒出一條有結構的閱讀順序，共四個站點：repository 的定位地標、執行路徑、核心函式庫模組，以及修改的影響範圍。指南裡引用的每一個行號範圍，都指向被分析版本 30bb1161095dbae2271e6bc3cc4c219cc3897a57 的檔案。

程式碼區塊是分析器可依行定位的語意單位，代表 module、function、class 和控制流分支這類結構區域。區塊描述和「為什麼」的註解，是靜態分析產生的推論性解讀，附帶信心評分，而不是執行時的證明。

深入實作細節之前，先從 repository 的地標和檔案層級的區塊開始。定位課程標出了這些 module 容器：

• examples/structured_output_tool.py:1-77：module examples/structured_output_tool.py，為被分析的原始碼檔案提供檔案層級容器（信心值 0.9）。
• src/smolagents/cli.py:1-294：module src/smolagents/cli.py，為被分析的原始碼檔案提供檔案層級容器（信心值 0.76）。
• src/smolagents/vision_web_browser.py:1-247：module src/smolagents/vision_web_browser.py，為被分析的原始碼檔案提供檔案層級容器（信心值 0.9）。
• examples/open_deep_research/app.py:1-11：module examples/open_deep_research/app.py，為被分析的原始碼檔案提供檔案層級容器（信心值 0.76）。
• examples/open_deep_research/run.py:1-125：module examples/open_deep_research/run.py，為被分析的原始碼檔案提供檔案層級容器（信心值 0.76）。
• examples/open_deep_research/run_gaia.py:1-312：module examples/open_deep_research/run_gaia.py，為被分析的原始碼檔案提供檔案層級容器（信心值 0.76）。

接著，追蹤靜態重建出的、圍繞進入點和邊界的執行路徑。從分析器的 90 條有界路徑中，列出了五條樣本追蹤：從 examples/async_agent/main.py 出發的路徑走到 Route 和 Starlette，從 examples/open_deep_research/app.py 出發的路徑則走到 create_agent、GradioUI 和 demo.launch，全都停在未解析的邊界。

• examples/async_agent/main.py:1-49：module examples/async_agent/main.py，為被分析的原始碼檔案提供檔案層級容器（信心值 0.76）。
• examples/open_deep_research/app.py:10-11：main_guard __main__，控制 Python 檔案被直接執行（而不只是被 import）時應該跑的程式碼（信心值 0.99）。
• examples/open_deep_research/app.py:1-11：module examples/open_deep_research/app.py，為被分析的原始碼檔案提供檔案層級容器（信心值 0.76）。

分析器核心程式碼課程的 8 個區塊中，沒有一個位在函式庫程式碼裡，8 個全都在範例檔案中。因此，函式庫閱讀集是 AI Frontier 實驗室依靜態呼叫次數做的確定性挑選，不是分析器的課程。

• 範例的核心程式碼區塊：examples/open_deep_research/app.py:10-11（main_guard __main__）、examples/agent_from_any_llm.py:43-52（function get_weather），以及 examples/multiple_tools.py 裡的函式 16-48（get_weather）、52-84（convert_currency）、88-115（get_news_headlines）、119-144（get_joke）、148-170（get_time_in_timezone）和 174-191（get_random_fact）。
• src/smolagents/local_python_executor.py：service/core 候選，有 195 個呼入和 190 個呼出。
  • src/smolagents/local_python_executor.py:1417-1569：function evaluate_ast，封裝一個具名的操作，連到 103 條下游呼叫或 import 關係（信心值 0.76）。
  • src/smolagents/local_python_executor.py:825-918：function evaluate_call，封裝一個具名的操作，連到 48 條下游呼叫或 import 關係（信心值 0.76）。
• src/smolagents/models.py：service/core 候選，有 60 個呼入和 66 個呼出。
  • src/smolagents/models.py:860-1135：class TransformersModel，把相關的行為歸在同一個類別邊界裡（信心值 0.99）。
  • src/smolagents/models.py:1859-2060：class AmazonBedrockModel，把相關的行為歸在同一個類別邊界裡（信心值 0.99）。
• src/smolagents/agents.py：service/core 候選，有 16 個呼入和 80 個呼出。
  • src/smolagents/agents.py:268-1212：class MultiStepAgent，把相關的行為歸在同一個類別邊界裡（信心值 0.99）。
  • src/smolagents/agents.py:1505-1803：class CodeAgent，把相關的行為歸在同一個類別邊界裡（信心值 0.99）。
• src/smolagents/utils.py：service/core 候選，有 56 個呼入和 8 個呼出。
  • src/smolagents/utils.py:285-373：function instance_to_source，封裝一個操作，連到 42 條下游呼叫或 import 關係（信心值 0.76）。
  • src/smolagents/utils.py:528-606：class Retrying，把相關的行為歸在同一個類別邊界裡（信心值 0.97）。

規劃修改時，請優先考慮這些區塊，因為靜態圖顯示它們周圍的耦合較強，下游的連結也很多：

• src/smolagents/local_python_executor.py:1417-1569：function evaluate_ast，封裝一個操作，連到 103 條下游呼叫或 import 關係（信心值 0.76）。
• src/smolagents/local_python_executor.py:1450-1569：if evaluate_ast，依一個看得到的條件在控制流路徑之間選擇（信心值 0.76）。
• src/smolagents/local_python_executor.py:1444-1447：if evaluate_ast，依一個看得到的條件在控制流路徑之間選擇（信心值 0.76）。
• src/smolagents/local_python_executor.py:1448-1449：straight_line evaluate_ast，把相鄰的循序陳述式歸成一個有界的區域（信心值 0.96）。
• src/smolagents/local_python_executor.py:825-918：function evaluate_call，封裝一個操作，連到 48 條下游呼叫或 import 關係（信心值 0.76）。
• examples/open_deep_research/scripts/text_web_browser.py:263-353：function SimpleTextBrowser._fetch_page，封裝一個操作，連到 47 條下游呼叫或 import 關係（信心值 0.76）。

這份導讀受限於靜態分析的限制和分析器的不確定性：

• 動態行為沒有解析：靜態分析無法解析反射、執行期依賴注入、動態 import、monkey-patching、產生的程式碼、框架在執行期的接線或動態分派。
• 指令沒有驗證：安裝、執行與建置的推論並不完整，安裝指令也沒有驗證。
• 清單檔不完整：依賴記錄只來自 v0.10 解析的 requirements 形式清單檔，不包含 pyproject.toml 的依賴表。
• 逐行擷取的文件陳述：README 的陳述可能抓到程式碼行而不是說明性的陳述，最多只能當作作者自述。
• 分析器的邊界：manifest 的能力項目描述的是 RepoLumen，而不是被分析的 repository。
• 不確定性課程：分析器指出有 6888 條靜態關係仍是未解析的外部目標，不確定性課程裡也沒有獨立的程式碼區塊。

所有的區塊說明和角色分類，都是附帶信心評分的靜態推論，而不是執行時的證明。