Claw Code 架构：双层代理框架设计

架构概述

claw code 架构采用双层设计：Python 编排层负责管理代理会话、命令路由和 LLM 交互，Rust 性能层负责处理 API 通信、工具执行、终端渲染和安全性。这种分离使高层代理逻辑保持表达力且易于修改，同时将延迟敏感的操作推入编译型、内存安全的代码中。

在最高层面，每次用户交互都经过三个阶段：引导启动（环境发现、配置加载、模式路由）、查询引擎执行（带工具调用和消息压缩的轮次循环）和响应渲染（终端中带语法高亮的流式 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 — 单次查询会话的令牌预算上限。
• compact_after_turns = 12 — 累积到这么多轮次后，转录记录将被压缩以释放上下文窗口空间。

每个轮次产生一个 TurnResult，QueryEnginePort 类暴露会话管理、消息压缩和流式接口。流式接口产生六种不同的事件类型：message_start、command_match、tool_match、permission_denial、message_delta 和 message_stop。这种事件驱动设计允许终端渲染器在令牌到达时增量绘制输出。

运行时 — 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() — 读取并解析 JSON 快照文件。
• get_command(name) — 按名称返回单个命令定义。
• find_commands(query) — 模糊搜索匹配查询字符串的命令。
• execute_command(cmd) — 分发命令进行执行。

工具 — tools.py

工具清单镜像命令系统，但用于工具调用。它从 reference_data/tools_snapshot.json 加载并定义 ToolExecution 数据类。关键函数包括：

• load_tool_snapshot() — 使用 lru_cache 缓存，实现零成本重复访问。
• build_tool_backlog() — 构建待处理工具操作列表。
• get_tools(simple_mode) — 启用 simple_mode 时，将可用工具限制为仅 BashTool、FileReadTool 和 FileEditTool。
• filter_tools_by_permission_context() — 根据当前会话上下文应用权限过滤。

核心数据模型 — models.py

models.py 模块定义了在系统各层流转的共享数据类型：

辅助 Python 模块

除核心子系统外，Python 层还包含数十个专注模块：

• context.py — 通过 PortContext 进行工作区发现，定位 source_root、tests_root、assets_root、archive_root，并统计 Python 文件数量。
• session_store.py — 基于 JSON 的会话持久化，存储在 .port_sessions/ 目录中。
• transcript.py — 内存中的对话转录记录，采用保留最近 10 条消息（keep_last=10）的压缩策略。
• execution_registry.py — 统一注册表，暴露 MirroredCommand 和 MirroredTool 类型，桥接 Python 和 Rust 执行模型。
• tool_pool.py — 通过 ToolPool 类进行过滤工具组装，将可见工具上限设为 15 个，以避免 LLM 上下文过载。
• parity_audit.py — 比较 Python 和 TypeScript 实现：18 个根文件映射和 31 个目录映射，用于跟踪移植完整性。
• cost_tracker.py — 跨轮次累积令牌使用量和美元成本。
• 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 客户端

api crate 封装了与 Anthropic API 的所有通信。其 AnthropicClient 处理认证、重试和流式传输：

• 重试逻辑 — 在 HTTP 状态码 408、409、429、500、502、503 和 504 时自动重试。
• 认证 — AuthSource 枚举支持四种模式：None、ApiKey、BearerToken 和 ApiKeyAndBearer。
• 流式传输 — 通过 MessageStream 和 SseParser 实现 Server-Sent Events，用于实时令牌传输。
• OAuth — 完整的令牌交换流程，用于企业认证。

runtime Crate — 16 个模块

runtime crate 是 Rust 工作区中最大的，包含 16 个模块，涵盖从 bash 执行到 OAuth 流程的所有内容：

其他运行时模块包括：

• bash — 沙盒化 shell 命令执行。
• json — 零依赖 JSON 解析器，开销最小。
• oauth — 完整的 PKCE 授权码流程，凭据存储在 ~/.claude/credentials.json。
• remote — 上游代理配置，包含 DEFAULT_REMOTE_BASE_URL 和 16 个无代理主机列表。
• session — MessageRole 枚举（System、User、Assistant、Tool）和 ContentBlock 变体（Text、ToolUse、ToolResult）。
• sse — 用于流式 API 响应的增量 SSE 解析器。
• usage — ModelPricing，包含每个模型的费率：Sonnet 每百万令牌 $15/$75，Haiku $1/$5，Opus $15/$75。包括用于显示的 format_usd。

tools Crate — 19 个工具规范

tools crate 定义了 19 个工具规范，每个都有完整的 JSON Schema 用于参数验证。这些 schema 就是 LLM 在决定调用哪个工具时看到的：

commands Crate — 15 个斜杠命令

commands crate 实现了包含 15 个内置命令的斜杠命令系统。每个命令通过 CommandSource 枚举分类：Builtin、InternalOnly 或 FeatureGated。

rusty-claude-cli — CLI 二进制文件

rusty-claude-cli crate 是面向用户的二进制文件。默认使用 claude-sonnet-4-20250514 作为模型，并提供丰富的终端体验：

• REPL — 交互式读取-求值-打印循环，带有盲文点阵加载动画（10 帧）。
• 语法高亮 — 由 syntect 驱动，使用 base16-ocean.dark 主题。
• Markdown 渲染 — 使用 pulldown_cmark 在终端中直接解析和渲染 markdown。
• 原始模式行编辑器 — 基于 crossterm 构建，支持跨平台终端输入处理。

compat-harness Crate

compat-harness crate 作为 Python 编排层和 Rust 性能层之间的兼容性桥梁。它确保数据结构、函数签名和调用约定在语言边界间保持稳定。

数据流：从提示到响应

理解 claw code 架构意味着追踪单个用户提示如何流经整个系统：

1. 用户在 rusty-claude-cli REPL 中输入提示。
2. CLI 将输入传递到 Python 层，runtime.py 对其进行分词并调用 route_prompt 来确定它是否匹配斜杠命令或应发送到 LLM。
3. 如果是斜杠命令，commands crate 直接处理。否则，查询引擎接管。
4. 查询引擎构建 API 请求——包括系统提示词（由 Rust prompt 模块从发现的 CLAUDE.md 文件构建）、对话历史（由 transcript.py 管理）和可用工具（由 tool_pool.py 过滤，最多 15 个）。
5. Rust api crate 以启用流式传输的方式将请求发送到 Anthropic 的 API，通过 Python 层返回 SSE 事件。
6. 如果 LLM 响应包含工具调用，Rust runtime crate 执行它（bash 命令、文件操作等），通过 PermissionPolicy 检查权限。
7. 工具结果反馈到下一轮。此循环最多持续 8 轮（Python 查询引擎）或 16 次迭代（Rust 对话运行时）。
8. 当对话累积超过 12 轮时，转录记录将被压缩——Rust 压缩模块保留最近 4 条消息并将预估令牌限制为 10,000。

会话与转录记录管理

Claw-code 通过两个互补机制维护会话状态：

• session_store.py 将完整会话数据以 JSON 格式持久化到 .port_sessions/ 目录，使 /resume 命令能够恢复之前的对话。
• transcript.py 在内存中维护滚动转录记录。其压缩算法保留最近 10 条消息（keep_last=10），丢弃旧内容以防止上下文窗口溢出。

在 Rust 端，session 模块使用 MessageRole（System、User、Assistant、Tool）和 ContentBlock（Text、ToolUse、ToolResult）定义消息 schema。这种共享 schema 确保两个层以相同方式解释对话历史。

Python-TypeScript 一致性审计

由于 claw-code 是 Claude Code 架构的洁净室重写，parity_audit.py 模块持续跟踪实现完整性。它维护 18 个根文件映射和 31 个目录映射，将 Python 模块映射到其 TypeScript 对应项，便于识别差距和确定移植工作优先级。