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，就没有条目覆盖率这种工程指标。

json 复制代码

// commands_snapshot.json 示例
{
  "PORTED_BASH": ["read", "write", "execute"],
  "PORTED_FILE": ["glob", "read", "edit"],
  "route_prompt": "在固定模块集合上打分"
}

关键Insight ：系统必须先建立稳定、可枚举、可过滤的清单，再开放I/O。

2. QueryEnginePort

负责会话状态机：

python 复制代码

# 核心逻辑
class QueryEnginePort:
    def submit_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

量化移植进度：

python 复制代码

# 追踪维度
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工程的核心挑战是什么？评论区聊聊