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 或 deep-link。
7. 查詢引擎提交迴圈 — 將控制權交給查詢引擎以進行互動式回合迴圈。

查詢引擎 — query_engine.py

查詢引擎是中央協調樞紐。它管理使用者、LLM 和工具系統之間的對話迴圈。關鍵設定值定義在 QueryEngineConfig 資料類別中：

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

Each turn produces a 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. This event-driven design allows the terminal renderer to paint output incrementally as tokens arrive.

執行環境 — runtime.py

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

• route_prompt — 將使用者輸入標記化並對可用命令和工具評分，產生 RoutedMatch 物件（每個包含 kind、name、source_hint 和 score）。
• bootstrap_session / run_turn_loop — 初始化新的代理工作階段並進入主要執行迴圈。

命令 — commands.py

命令清單在啟動時從 reference_data/commands_snapshot.json 載入。它暴露包含五個欄位的 CommandExecution 資料類別：name、source_hint、prompt、handled 和 message。四個公開函式提供命令 API：

• load_command_snapshot() — Reads and parses the JSON snapshot file.
• get_command(name) — Returns a single command definition by name.
• find_commands(query) — Fuzzy-searches commands matching a query string.
• execute_command(cmd) — Dispatches a command for execution.

工具 — tools.py

工具清單反映命令系統但用於工具呼叫。它從 reference_data/tools_snapshot.json 載入並定義 ToolExecution 資料類別。關鍵函式包括：

• 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

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

支援 Python 模組

除了核心子系統外，Python 層還包括數十個聚焦的模組：

• context.py — Workspace discovery via PortContext, which locates source_root, tests_root, assets_root, archive_root, and counts Python files.
• session_store.py — JSON-based session persistence stored in the .port_sessions/ directory.
• transcript.py — In-memory conversation transcript with a compaction strategy that keeps the last 10 messages (keep_last=10).
• execution_registry.py — Unified registry exposing MirroredCommand and MirroredTool types that bridge the Python and Rust execution models.
• tool_pool.py — Filtered tool assembly via the ToolPool class, which caps visible tools at 15 to avoid overwhelming the LLM context.
• parity_audit.py — Compares the Python and TypeScript implementations: 18 root file mappings and 31 directory mappings to track porting completeness.
• cost_tracker.py — Accumulates token usage and dollar costs across turns.
• history.py — Session history storage and retrieval.
• ink.py — Markdown panel rendering for rich terminal output.
• permissions.py — Permission checks and policy enforcement.
• prefetch.py — Data prefetching for faster bootstrap.
• remote_runtime.py — Handles remote execution modes.
• direct_modes.py — Direct-connect and deep-link mode handling.
• command_graph.py — Command dependency graph resolution.
• query.py — Lower-level query construction helpers.
• deferred_init.py — Lazy initialization for heavy components.

Rust 效能層 (rust/)

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

api Crate — Anthropic API 客戶端

The api crate encapsulates all communication with the Anthropic API. Its AnthropicClient handles authentication, retries, and streaming:

• Retry logic — Automatically retries on HTTP status codes 408, 409, 429, 500, 502, 503, and 504.
• Authentication — The AuthSource enum supports four modes: None, ApiKey, BearerToken, and ApiKeyAndBearer.
• Streaming — Server-Sent Events via MessageStream and SseParser for real-time token delivery.
• OAuth — Full token exchange flow for enterprise authentication.

runtime Crate — 16 個模組

The runtime crate is the largest in the Rust workspace with 16 modules covering everything from bash execution to OAuth flows:

其他執行環境模組包括：

• bash — Sandboxed shell command execution.
• json — Zero-dependency JSON parser for minimal overhead.
• oauth — Full PKCE authorization code flow, storing credentials at ~/.claude/credentials.json.
• remote — Upstream proxy configuration with DEFAULT_REMOTE_BASE_URL and a list of 16 no-proxy hosts.
• 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 defines 19 tool specifications, each with a full JSON Schema for parameter validation. These schemas are what the LLM sees when deciding which tool to call:

commands Crate — 15 個斜線命令

The commands crate implements the slash command system with 15 built-in commands. Each command is classified by a CommandSource enum: Builtin, InternalOnly, or FeatureGated.

rusty-claude-cli — CLI 執行檔

The rusty-claude-cli crate is the user-facing binary. It defaults to claude-sonnet-4-20250514 as the model and provides a rich terminal experience:

• REPL — Interactive read-eval-print loop with a braille spinner animation (10 frames) for loading states.
• Syntax highlighting — Powered by syntect with the base16-ocean.dark theme.
• Markdown rendering — Uses pulldown_cmark to parse and render markdown directly in the terminal.
• Raw mode line editor — Built on crossterm for cross-platform terminal input handling.

compat-harness Crate

The compat-harness crate serves as the compatibility bridge between the Python orchestration layer and the Rust performance layer. It ensures that data structures, function signatures, and calling conventions remain stable across the language boundary.

資料流程：從提示到回應

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

1. The user types a prompt in the rusty-claude-cli REPL.
2. The CLI passes input to the Python layer, where runtime.py tokenizes it and calls route_prompt to determine if it matches a slash command or should go to the LLM.
3. If it is a slash command, the commands crate handles it directly. Otherwise, the query engine takes over.
4. The query engine constructs the API request — including system prompt (built by the Rust prompt module from discovered CLAUDE.md files), conversation history (managed by transcript.py), and available tools (filtered by tool_pool.py, max 15).
5. The Rust api crate sends the request to Anthropic's API with streaming enabled, yielding SSE events back through the Python layer.
6. If the LLM response includes a tool call, the Rust runtime crate executes it (bash commands, file operations, etc.), checking permissions via the PermissionPolicy.
7. Tool results feed back into the next turn. This loop continues for up to 8 turns (Python query engine) or 16 iterations (Rust conversation runtime).
8. When the conversation accumulates more than 12 turns, the transcript is compacted — the Rust compaction module preserves the 4 most recent messages and limits estimated tokens to 10,000.

工作階段與對話記錄管理

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

• session_store.py persists full session data as JSON in the .port_sessions/ directory, enabling the /resume command to restore previous conversations.
• transcript.py keeps an in-memory rolling transcript. Its compaction algorithm retains the last 10 messages (keep_last=10), discarding older content to prevent context window overflow.

On the Rust side, the session module defines the message schema with MessageRole (System, User, Assistant, Tool) and ContentBlock (Text, ToolUse, ToolResult). This shared schema ensures both layers interpret conversation history identically.

Python-TypeScript 一致性稽核

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