claw-code 源码分析：Python 快迭代 + Rust 硬化——双轨策略的成本、收益与边界在哪里？

涉及仓库证据 ：README 的"Python-first porting workspace"与 Rust "definitive version/primary product surface"叙事、Python src/ 的快照/报告/审计切片、Rust workspace 的版本/安全姿态与 crate 边界。

---

1. 双轨策略在本仓库里的"官方含义"

claw-code 同时维护两套实现面：

• Python 轨（src/）：README 明确称其为"Python-first porting workspace"，并强调已从外泄快照切换到可公开协作的移植工作区：

## Porting Status

The main source tree is now Python-first.

- `src/` contains the active Python porting workspace
- `tests/` verifies the current Python workspace
- the exposed snapshot is no longer part of the tracked repository state

The current Python workspace is not yet a complete one-to-one replacement for the original system, but the primary implementation surface is now Python.

• Rust 轨（rust/） ：README 早段强调 Rust aims to be "definitive version"，而 rust/README.md 则进一步说 Rust workspace 是"current main product surface"：

Claw Code is a local coding-agent CLI implemented in safe Rust. ...

The Rust workspace is the current main product surface. The `claw` binary provides interactive sessions, one-shot prompts, workspace-aware tools, local agent workflows, and plugin-capable operation from a single workspace.

这说明双轨不是"同一功能写两遍"的炫技，而是两条不同工程目标：

• Python：理解与对照、快速切片、可重复报告
• Rust：可发布产品面、性能/安全、长期接口稳定

---

2. Python 轨的收益：快、可解释、可对照（适合移植期）

从现有代码形态看，Python 侧的核心价值是把复杂 Harness 拆成"可枚举 + 可报告"的块：

2.1 用快照清单把目标表面"数据化"

commands_snapshot.json / tools_snapshot.json → PORTED_COMMANDS / PORTED_TOOLS，驱动 route/shim/summary（见 result/08.md）。这让移植讨论从"我觉得像"变成"清单条目与路由输出可复现"。

2.2 用 Parity Audit 把"像不像"量化

parity_audit.py 把根文件、目录、文件数比、清单条目比写成结构化结果，属于典型"移植期仪表盘"（见 result/10.md）。其映射表把顶层对齐目标写死：

ARCHIVE_ROOT_FILES = {
    'QueryEngine.ts': 'QueryEngine.py',
    ...
    'tools.ts': 'tools.py',
}

2.3 用 shim + Markdown 报告把运行时切片可观测化

bootstrap 输出一轮 "Runtime Session" 报告：Context、Setup、System Init、Routed Matches、Tool/Command Execution（shim）、Stream Events、Turn Result、落盘路径。 \n这种"先把故事讲清楚"的方式，能在没有外部模型/网络依赖时先把状态机与审计位摆对（见 result/03.md、result/09.md）。

2.4 适合用来"验证架构选择"，不适合承担最终性能与分发

Python 的 QueryEnginePort 当前甚至不调用真实 LLM，仅格式化摘要/JSON；这非常适合做接口/审计/停止条件的推演，但不承担"真实代理 runtime"的性能目标。

---

3. Rust 轨的收益：硬化、产品化、长期可维护（适合主线）

Rust README 把"可用的本地 CLI 产品面"写得很具体：会话、工具、slash commands、插件、skill discovery、OAuth 等（见 rust/README.md）。从工程角度，它更像"要跑在用户机器上的东西"，优势在于：

3.1 类型与模块边界更强：长期维护成本更低

Rust workspace 用 crate 切分 runtime/tools/commands/plugins 等，天然形成"接口面"。这一层一旦稳定，生态扩展（插件、技能）与兼容层才更可控（见 result/17.md）。

3.2 安全姿态更强：例如 workspace 禁止 unsafe

[workspace.lints.rust]
unsafe_code = "forbid"

在 Harness 这种会跑 shell/文件/网络的系统里，安全姿态是产品化门槛之一；Rust 的默认约束更容易形成"硬化基线"。

3.3 分发与体验目标更明确

rust/README.md 提到 claw 二进制提供交互与 one-shot、工具与插件能力，并给出安装/运行方式。这是 Python 轨当前不强调的目标（Python 更像研究/移植工作区 CLI）。

---

4. 双轨策略的成本：真正贵的不是"写两遍"，而是"对齐两遍"

双轨最常见的隐藏成本：\n\n### 4.1 语义漂移（Semantic drift）

Python 的"inventory/route/shim/turn-loop"与 Rust 的"真实 runtime loop"会自然演进出不同语义：\n\n- Python 可能把某开关当作"报告参数"；Rust 需要把它当作"产品配置"。\n- Python 的 MCP 开关是字符串启发式过滤；Rust 可能是协议级 registry。\n- Python 的 usage 是 split 词数近似；Rust 可能来自 provider 的真实 token usage。\n\n漂移不可怕，可怕的是没人知道漂移发生了。解决方式是：把关键契约写成可重复报告/测试（Python 已在做），并把"以哪一轨为准"写清。

4.2 贡献者注意力被分裂

同一个 feature（例如 compaction、plugins、sessions）在两套树里都有影子，贡献者需要知道"在哪改才算改对"。仓库需要明确：\n\n- Python：对照/验证/研究面\n- Rust：产品面（主线）\n\nrust/README.md 已明确"current main product surface"，这是降低分裂成本的关键信号。

4.3 接口复用困难

如果两边都各自定义事件形状/权限模型/日志字段，将来想做兼容层（例如 IDE 集成）会更难。需要在"横向地基"上对齐：\n\n- 工具权限分级（read-only/workspace-write/danger）\n- hook 事件 payload\n- session 持久化 schema（至少字段名/版本策略）

---

5. 边界在哪里：哪些东西应当"只在一条轨上做"

为了避免"永远双写"，建议把工作边界划清楚：

5.1 更适合留在 Python 轨的工作

• 对照底稿治理 ：reference_data 的抽取、差异解释、parity 报告门禁。
• 架构切片实验：路由策略、报告形态、停止条件、审计字段设计。
• 教学与可解释性工具 ：bootstrap Markdown 报告、可重复的 CLI 验证链。

5.2 更适合落到 Rust 轨的工作

• 真实工具执行与 sandbox/权限硬化（文件/进程/网络都在这层落地）。
• 长期稳定的插件/技能生态接口（manifest、registry、hook runner 等）。
• 性能敏感与并发敏感的 runtime（会话压缩、流式、后台任务）。
• 面向用户的分发与兼容层（CLI 体验、LSP、server/compat-harness）。

5.3 两边都该对齐的最小集合（否则会永远分裂）

• 核心术语与事件名 ：例如 compaction、permission、session。 \n- 审计字段的最小集 ：session_id、tool_name、denial reason/code、usage。 \n- 配置开关的语义 ：include_mcp 这类开关在两边都应有一致的含义，即便实现不同。

---

6. 实操建议：如何让双轨"互补而不互耗"

1. 以 Rust 为"行为主线"，Python 为"对照与诊断线" ：遇到语义冲突时，先决定哪边是权威。 \n2. 让 Python 报告为 Rust 提供验收用例 ：例如把 Python 的 bootstrap 报告结构当作"验收模板"，Rust 侧可输出同样章节（哪怕内容不同）。 \n3. 对齐最小契约 ：从权限分级、hook 事件、session schema 开始，逐步统一字段名与错误码。 \n4. 避免双实现同一 I/O：Python 尽量停在 shim/模拟/报告；真实 I/O 与 provider 集成集中在 Rust，减少安全与兼容风险。

---

7. 小结

• 收益：Python 让移植"快且可解释"，Rust 让产品"硬且可维护"。
• 成本：最大成本是语义漂移与注意力分裂，需要用"对照底稿 + 报告/测试门禁 + 明确权威轨"控制。
• 边界：Python 做对照/实验/诊断，Rust 做真实 runtime/工具执行/生态接口；两边只对齐最小契约集合，才能让双轨长期互补。

---