Claw Code 架構：雙層代理架構設計

架構概覽

Claw Code 架構遵循雙層設計: ：一個管理代理工作階段、命令路由和 LLM 互動的 Python 協作層，搭配處理 API 通訊、工具執行、終端渲染和安全的 Rust 效能層。這種分離使高階代理邏輯保持表達力且易於修改，同時將延遲敏感的操作推入編譯的、記憶體安全的程式碼中。

在最高層次上，每個使用者互動流經三個階段： 啟動（環境探索、配置載入、模式路由）、查詢引擎執行（帶工具呼叫和訊息壓縮的回合迴圈）和回應渲染（在終端中串流帶語法高亮的 markdown）。每個階段都由兩層中定義明確的模組支撐。

 User Terminal (REPL / stdin)
       |
       v
 +------------------------------------------+
 |          Rust CLI Binary                  |
 |  rusty-claude-cli  (crossterm, syntect,   |
 |  pulldown_cmark, braille spinner)         |
 +------------------------------------------+
       |
       v
 +------------------------------------------+
 |         Python Orchestration Layer        |
 |  bootstrap_graph.py  (7 stages)          |
 |  runtime.py  (route_prompt, run_turn)    |
 |  query_engine.py  (max_turns=8, stream)  |
 |  commands.py  |  tools.py  |  models.py  |
 |  context.py   |  session_store.py        |
 |  transcript.py | execution_registry.py   |
 |  tool_pool.py  | parity_audit.py         |
 |  + 50 more modules                       |
 +------------------------------------------+
       |              |              |
       v              v              v
 +-----------+  +-----------+  +-----------+
 | Rust api  |  | Rust      |  | Rust      |
 | crate     |  | runtime   |  | tools     |
 | Anthropic |  | 16 modules|  | 19 specs  |
 | client,   |  | bash,file |  | JSON      |
 | SSE,OAuth |  | ops,mcp,  |  | schemas   |
 | retry     |  | oauth,    |  |           |
 |           |  | session,  |  |           |
 |           |  | prompt,   |  |           |
 |           |  | usage     |  |           |
 +-----------+  +-----------+  +-----------+
       |              |
       v              v
 +-----------+  +---------------+
 | Rust      |  | Rust          |
 | commands  |  | compat-       |
 | 15 slash  |  | harness       |
 | commands  |  | (bridge       |
 |           |  |  layer)       |
 +-----------+  +---------------+
       |
       v
   Anthropic API  (api.anthropic.com)

Python 協作層 (src/)

Python 工作區包含 60+ 模組，組織成範圍緊密的子系統。每個模組擁有單一職責，使程式碼庫易於導覽和獨立測試。以下是每個主要子系統的詳細分解。

啟動圖 — bootstrap_graph.py

啟動序列是每個 claw-code 工作階段的入口點。它運行 7 個順序階段，每個階段依賴前一階段的成功完成：

1. 預取 — 在其他任何內容運行之前預載參考資料並預熱快取。
2. 警告處理程式 — 附加全域警告篩選器，使第三方程式庫的噪音棄用訊息不會洩漏到使用者終端。
3. CLI 解析器 — 解析命令列引數和旗標，提前建立執行模式。
4. 設定 + 命令平行載入 — 同時運行環境設定和命令快照載入，以加快啟動速度。
5. 延遲初始化 — 初始化依賴已解析 CLI 狀態和已載入配置的元件。
6. 模式路由 — 將執行路由到六種模式之一： local, remote, ssh, teleport, direct-connect, or deep-link.
7. 查詢引擎提交迴圈 — 將控制權交給查詢引擎以進行互動式回合迴圈。

查詢引擎 — query_engine.py

查詢引擎是核心協作中心。它管理使用者、LLM 和工具系統之間的對話迴圈。關鍵配置值定義在 QueryEngineConfig dataclass:

• max_turns = 8 — 每個使用者查詢在引擎停止前的最大 LLM 往返次數。
• max_budget_tokens = 2000 — 單個查詢工作階段的 token 預算上限。
• compact_after_turns = 12 — 累積到這麼多回合後，對話記錄會被壓縮以釋放上下文視窗空間。

每個回合產生一個 TurnResult, and the QueryEnginePort class exposes session management, message compaction, and streaming. The streaming interface yields six distinct event types: message_start, command_match, tool_match, permission_denial, message_delta, and message_stop. 這種事件驅動設計允許終端渲染器在 token 到達時逐步繪製輸出。

執行環境 — runtime.py

執行環境模組橋接原始使用者輸入和查詢引擎。 它提供 PortRuntime, ，暴露兩個關鍵方法：

• route_prompt — 對使用者輸入進行分詞並根據可用命令和工具評分， producing RoutedMatch objects (each with a kind, name, source_hint, and score).
• bootstrap_session / run_turn_loop — 初始化新的代理工作階段並進入主執行迴圈。

命令 — commands.py

命令清單從 reference_data/commands_snapshot.json 載入。它暴露 CommandExecution dataclass with five fields: name, source_hint, prompt, handled, and message. 四個公開函式提供命令 API：

• load_command_snapshot() — 讀取並解析 JSON 快照檔案。
• get_command(name) — 按名稱傳回單個命令定義。
• find_commands(query) — 模糊搜尋與查詢字串匹配的命令。
• execute_command(cmd) — 派發命令以供執行。

工具 — tools.py

工具清單鏡像了命令系統，但用於工具呼叫。 It loads from reference_data/tools_snapshot.json and defines a ToolExecution dataclass. Key functions include:

• load_tool_snapshot() — Cached with lru_cache for zero-cost repeated access.
• build_tool_backlog() — Constructs the list of pending tool operations.
• get_tools(simple_mode) — When simple_mode is enabled, restricts the available tools to only BashTool, FileReadTool, and FileEditTool.
• filter_tools_by_permission_context() — Applies permission filtering based on the current session context.

核心資料模型 — models.py

The models.py 模組定義了在系統每一層中流動的共享資料類型：

支援 Python 模組

除核心子系統外，Python 層還包含數十個專注的模組：

• context.py — 透過以下方式進行工作區探索 PortContext, which locates source_root, tests_root, assets_root, archive_root, and counts Python files.
• session_store.py — 基於 JSON 的工作階段持久化，儲存在 .port_sessions/ directory.
• transcript.py — 記憶體中的對話記錄，壓縮策略保留最後 10 條訊息 (keep_last=10).
• execution_registry.py — 統一的註冊表，暴露 MirroredCommand and MirroredTool types that bridge the Python and Rust execution models.
• tool_pool.py — 透過以下方式進行篩選工具組裝 ToolPool class, ，將可見工具上限設為 15 個，以避免壓倒 LLM 上下文。
• parity_audit.py — 比較 Python 和 TypeScript 實現： 18 root file mappings and 31 directory mappings to track porting completeness.
• cost_tracker.py — 跨回合累計 token 使用量和美元費用。
• history.py — 工作階段歷史儲存和檢索。
• ink.py — Markdown 面板渲染，用於豐富的終端輸出。
• permissions.py — 權限檢查和策略強制執行。
• prefetch.py — 資料預取以加快啟動速度。
• remote_runtime.py — 處理遠端執行模式。
• direct_modes.py — 直接連線和深層連結模式處理。
• command_graph.py — 命令依賴圖解析。
• query.py — 較低層次的查詢建構輔助工具。
• deferred_init.py — 重量級元件的延遲初始化。

Rust 效能層 (rust/)

Rust 工作區組織為 6 個 crate 的 Cargo 工作區。每個 crate 獨立編譯，支援增量建置和清晰的依賴邊界。它們共同提供 Python 層呼叫的高效能基礎。

api Crate — Anthropic API 用戶端

The api crate 封裝了與 Anthropic API 的所有通訊。 Its AnthropicClient handles authentication, retries, and streaming:

• 重試邏輯 — 自動重試以下 HTTP 狀態碼 408, 409, 429, 500, 502, 503, and 504.
• 驗證 — AuthSource enum supports four modes: None, ApiKey, BearerToken, and ApiKeyAndBearer.
• 串流 — 透過以下方式的伺服器推送事件 MessageStream and SseParser for real-time token delivery.
• OAuth — 用於企業驗證的完整 token 交換流程。

runtime Crate — 16 個模組

The runtime crate 是 Rust 工作區中最大的，包含 16 個模組，涵蓋從 bash 執行到 OAuth 流程的所有內容：

額外的執行環境模組包括：

• bash — 沙箱化的 Shell 命令執行。
• json — 零依賴 JSON 解析器，開銷最小。
• oauth — 完整的 PKCE 授權碼流程，將憑證儲存在 ~/.claude/credentials.json.
• remote — 上游代理配置，使用 DEFAULT_REMOTE_BASE_URL 以及 16 個免代理主機的清單。
• session — MessageRole enum (System, User, Assistant, Tool) and ContentBlock variants (Text, ToolUse, ToolResult).
• sse — Incremental SSE parser for streaming API responses.
• usage — ModelPricing with per-model rates: Sonnet at $15/$75 per million tokens, Haiku at $1/$5, Opus at $15/$75. Includes format_usd for display.

tools Crate — 19 個工具規格

The tools crate 定義了 19 個工具規格，每個都有完整的 JSON Schema 用於參數驗證。這些 schema 是 LLM 決定呼叫哪個工具時所看到的：

commands Crate — 15 個斜線命令

The commands crate 實現了包含 15 個內建命令的斜線命令系統。 Each command is classified by a CommandSource enum: Builtin, InternalOnly, or FeatureGated.

rusty-claude-cli — CLI 執行檔

The rusty-claude-cli crate 是面向使用者的執行檔。它預設使用 claude-sonnet-4-20250514 作為模型，並提供豐富的終端體驗：

• REPL — 互動式讀取-求值-輸出迴圈，帶有布萊葉旋轉動畫（10 幀）用於載入狀態。
• 語法高亮 — 由 syntect with the base16-ocean.dark theme.
• Markdown 渲染 — 使用 pulldown_cmark 直接在終端中解析和渲染 markdown。
• 原始模式行編輯器 — 基於 crossterm 進行跨平台終端輸入處理。

compat-harness Crate

The compat-harness crate 作為 Python 協作層和 Rust 效能層之間的相容性橋樑。它確保資料結構、函式簽名和呼叫慣例在語言邊界之間保持穩定。

資料流：從提示到回應

理解 Claw Code 架構意味著追蹤單個使用者提示如何在整個系統中流動：

1. 使用者在 rusty-claude-cli REPL 中輸入提示。
2. The CLI passes input to the Python layer, where runtime.py 進行分詞並呼叫 route_prompt 以確定它是否匹配斜線命令或應發送到 LLM。
3. 如果是斜線命令， commands crate 直接處理它。否則， query engine 接管。
4. 查詢引擎建構 API 請求 — 包括系統提示 (built by the Rust prompt module from discovered CLAUDE.md files), 對話歷史 (managed by transcript.py), 和可用工具 (filtered by tool_pool.py, max 15).
5. The Rust api crate 向 Anthropic 的 API 傳送啟用串流的請求，透過 Python 層傳回 SSE 事件。
6. 如果 LLM 回應包含工具呼叫，Rust runtime crate 執行它（bash 命令、檔案操作等），透過 PermissionPolicy.
7. 工具結果回饋到下一個回合。此迴圈最多持續 8 turns (Python query engine) or 16 iterations (Rust conversation runtime).
8. 當對話累積超過 12 個回合時，對話記錄會被 壓縮 — Rust 壓縮模組保留最近的 4 條訊息並將估計 token 限制為 10,000。

工作階段與對話記錄管理

Claw-code 透過兩個互補機制維護工作階段狀態：

• session_store.py 將完整的工作階段資料以 JSON 格式持久化到 .port_sessions/ 目錄中，使 /resume 命令能夠恢復先前的對話。
• transcript.py 保持記憶體中的滾動對話記錄。其壓縮演算法保留最後 10 條訊息 (keep_last=10), 丟棄較舊的內容以防止上下文視窗溢出。

在 Rust 端， session module 定義訊息 schema，使用 MessageRole (System, User, Assistant, Tool) and ContentBlock (Text, ToolUse, ToolResult). This shared schema ensures both layers interpret 對話歷史 identically.

Python-TypeScript 一致性審計

由於 claw-code 是 Claude Code 架構的淨室重寫， parity_audit.py 模組持續追蹤實現完整性。它維護 18 個根檔案對映和 31 個目錄對映，將 Python 模組對映到其 TypeScript 對應項，使識別差距和排定移植工作的優先順序變得簡單明瞭。