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

涉及仓库证据README 的“Python-first porting workspace”与 Rust “definitive version/primary product surface”叙事、Pythonsrc/的快照/报告/审计切片、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 Executionshim、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 driftPython 的“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 报告门禁。架构切片实验路由策略、报告形态、停止条件、审计字段设计。教学与可解释性工具bootstrapMarkdown 报告、可重复的 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. 实操建议如何让双轨“互补而不互耗”以 Rust 为“行为主线”Python 为“对照与诊断线”遇到语义冲突时先决定哪边是权威。 \n2.让 Python 报告为 Rust 提供验收用例例如把 Python 的bootstrap报告结构当作“验收模板”Rust 侧可输出同样章节哪怕内容不同。 \n3.对齐最小契约从权限分级、hook 事件、session schema 开始逐步统一字段名与错误码。 \n4.避免双实现同一 I/OPython 尽量停在 shim/模拟/报告真实 I/O 与 provider 集成集中在 Rust减少安全与兼容风险。7. 小结收益Python 让移植“快且可解释”Rust 让产品“硬且可维护”。成本最大成本是语义漂移与注意力分裂需要用“对照底稿 报告/测试门禁 明确权威轨”控制。边界Python 做对照/实验/诊断Rust 做真实 runtime/工具执行/生态接口两边只对齐最小契约集合才能让双轨长期互补。