claw-code 源码分析：Harness工程的核心设计
claw-code 源码分析：Harness工程的核心设计
2026年3月，一个名为"Rewriting Project Claw Code"的开源项目在GitHub横空出世——24小时内斩获7万+Stars，成为史上增长最快的仓库。它不是简单的代码备份，而是对AI Agent Harness工程的一次彻底重构。
一、背景：一场意外的"泄露"与回应
🎯 发生了什么
2026年3月31日凌晨4点，Claude Code相关源码在社群中曝光。面对这一突发情况，项目维护者@instructkr做了一个工程师该做的决定：
不依赖泄露快照作为长期分支，而是在极短时间内从零用Python重写核心能力。
这催生了claw-code（全称：Rewriting Project Claw Code）。
🏆 成就
| 指标 | 数据 |
|---|---|
| 发布时间 | 2026年3月31日 |
| 2小时内Stars | 50K+ |
| 当前Stars | 179K+ |
| 主要语言 | Python (3.4%) + Rust (96.1%) |
二、核心架构：双层设计
claw-code采用经典的双层架构，这是它与其他AI编程工具最大的不同。
🏗️ 架构图
用户（终端） │ ▼ ┌──────────────────────────────────┐ │ Python 编排层 (src/) │ ← 60+模块，组织紧密 │ ├── commands.py │ │ ├── tools.py │ │ ├── runtime.py │ │ └── parity_audit.py │ └──────────────────────────────────┘ │ ▼ (compat-harness桥接) ┌──────────────────────────────────┐ │ Rust 执行层 (rust/crates/) │ ← 追求性能与内存安全 │ ├── api-client │ │ ├── runtime │ │ ├── tools │ │ ├── commands │ │ └── claw-cli │ └──────────────────────────────────┘💡 设计哲学
- Python优先：快速迭代、表达力强、可测试
- Rust终局：高性能、内存安全、低延迟
- compat-harness桥接：确保数据结构在语言边界保持稳定
三、核心模块解析
1. Inventory清单系统
这是Harness工程的第一原则：
没有Inventory，就没有条目覆盖率这种工程指标。
// commands_snapshot.json 示例{"PORTED_BASH":["read","write","execute"],"PORTED_FILE":["glob","read","edit"],"route_prompt":"在固定模块集合上打分"}关键Insight：系统必须先建立稳定、可枚举、可过滤的清单，再开放I/O。
2. QueryEnginePort
负责会话状态机：
# 核心逻辑classQueryEnginePort:defsubmit_message(self,message):# 1. 状态机：max_turns, max_budget_tokens# 2. 停止条件：stop_reason统一输出# 3. 审计位：matched_tools, denied_tools特点：不发起外部LLM HTTP请求，纯本地完成状态管理。
3. compat-harness
兼容性桥梁层，对接编辑器生态：
| 功能 | 说明 |
|---|---|
| 数据结构桥接 | Python ↔ Rust类型对齐 |
| 函数签名稳定 | 跨语言调用约定一致 |
| 调用 Conventions | 确保运行时行为一致 |
4. parity_audit
量化移植进度：
# 追踪维度root_file_mappings=18# 根文件映射directory_mappings=31# 目录映射这让"像不像"从主观争论变成可验证的数据。
四、与其他项目的对比
| 项目 | 架构 | 特点 |
|---|---|---|
| claw-code | Python + Rust双层 | 清单驱动、可验证移植 |
| OpenClaw | 单层 | 简单易用、Skills生态 |
| Claude Code | 闭源 | 官方实现 |
五、工程启示
🎯 学习点
- 先清单，后I/O：把"系统承认什么"钉死，再谈"能对世界做什么"
- 用数据说话：parity_audit把移植进度从感受变成指标
- 清洁室重写：不copy代码，只capture架构模式
- 双层分离：编排层追求灵活，执行层追求性能
🔧 实践建议
想学习Harness设计？
src/commands.py+src/tools.py→ 理解清单src/runtime.py+src/query_engine.py→ 理解会话rust/crates/compat-harness/→ 理解桥接
六、总结
claw-code给我们的最大启示是：Harness工程不是堆代码，而是建系统。
当AI Agent从"对话框里的奇迹"变成"与真实世界打交道的软件"时，可靠性、成本、合规这三条底线能否守住，取决于Harness层的工程化程度。
而claw-code用公开的方式展示了：清单驱动、审计驱动、测试驱动的移植节奏。
💬 互动
你认为Harness工程的核心挑战是什么？评论区聊聊