Claw Code：Better Harness Tools，让 AI 真正干实事

从 TypeScript 源码泄露到 Python/Rust 双轨重构，一个关于 harness 工程的 cleanroom 实现

一、项目描述

1.1 项目背景

2026 年 3 月 31 日凌晨 4 点，Claw Code 源码意外泄露，整个开发者社区沸腾了。面对这个备受争议的 AI harness 系统，作者没有选择简单存档，而是做了一件工程师会做的事------从头用 Python 重写核心特性，并在天亮前推送了第一个可用版本。

这不是"存档泄露代码"，而是一个cleanroom 实现：通过研究原始架构模式，用不同语言重新构建等价的 harness 能力，同时避开法律和伦理风险。

1.2 核心特性

特性	说明
Python-first 源码树	主实现迁移到 Python，更易理解和扩展
Rust 性能优化	内存安全的系统语言端口，提供更快的运行时
命令/工具镜像	完整复刻原始系统的命令和工具接口
查询引擎	模拟 prompt 路由、工具匹配、权限检查
会话持久化	支持会话保存、加载和回放
MCP 协议支持	Model Context Protocol 集成

1.3 技术栈

层级	技术
主语言	Python 3.10+
性能层	Rust (claw-cli)
构建工具	cargo, pip
工作流编排	oh-my-codex (OmX), oh-my-opencode (OmO)
测试框架	unittest

二、算法/架构框架

2.1 整体架构

用户输入
Python CLI / Rust CLI
QueryEnginePort
命令路由
工具路由
命令清单
工具清单
执行层
会话存储
转录存储

2.2 核心设计思路

Cleanroom 原则：不直接复制原始源码，而是通过研究架构模式（harness、工具绑定、会话管理）重新实现。

双轨并行：

Python 负责快速迭代、原型验证、易用性
Rust 负责性能关键路径、内存安全、生产级运行时

镜像机制 ：通过 reference_data/commands_snapshot.json 和 tools_snapshot.json 记录原始系统的接口清单，Python 实现逐个"镜像"这些能力。

2.3 数据流

通过
拒绝
用户 Prompt
路由层
命令/工具匹配
权限检查
执行
拒绝处理
会话更新
消息压缩
返回结果

三、实用教程

3.1 环境准备

bash 复制代码

# 克隆仓库
git clone https://github.com/ultraworkers/claw-code
cd claw-code

# Python 环境准备
python3 -m pip install -e .

# Rust 构建（可选）
cd rust
cargo build --release

3.2 快速开始

bash 复制代码

# 查看当前 Python 移植状态摘要
python3 -m src.main summary

# 打印工作空间清单
python3 -m src.main manifest

# 列出当前已镜像的模块
python3 -m src.main subsystems --limit 16

# 列出命令清单
python3 -m src.main commands --limit 10

# 列出工具清单
python3 -m src.main tools --limit 10

3.3 配置说明

参数	默认值	说明
`max_turns`	8	单会话最大轮次
`max_budget_tokens`	2000	最大 token 预算
`compact_after_turns`	12	触发消息压缩的轮次阈值
`structured_output`	False	是否启用结构化输出

3.4 进阶用法

bash 复制代码

# 路由测试：将 prompt 分发到命令/工具
python3 -m src.main route "帮我写一个排序算法" --limit 5

# Bootstrap 模拟：构建运行时风格会话报告
python3 -m src.main bootstrap "分析这个文件" --limit 5

# Turn 循环：运行小型状态轮次循环
python3 -m src.main turn-loop "实现一个 API" --max-turns 3

# 会话持久化
python3 -m src.main flush-transcript "会话内容"
python3 -m src.main load-session <session_id>

# 运行验证
python3 -m unittest discover -s tests -v

四、核心模块解读

4.1 models.py

职责： 定义核心数据模型，包括子系统、移植模块、权限拒绝、使用统计等。

关键代码：

python 复制代码

@dataclass(frozen=True)
class PortingModule:
    name: str
    responsibility: str
    source_hint: str
    status: str = 'planned'

@dataclass
class PortingBack:
    title: str
    modules: list[PortingModule] = field(default_factory=list)

设计要点： 使用 @dataclass(frozen=True) 确保不可变性，便于并发场景和缓存优化。

4.2 commands.py

职责： 命令清单管理、查找、执行路由。

关键代码：

python 复制代码

@lru_cache(maxsize=1)
def load_command_snapshot() -> tuple[PortingModule, ...]:
    raw_entries = json.loads(SNAPSHOT_PATH.read_text())
    return tuple(
        PortingModule(
            name=entry['name'],
            responsibility=entry['responsibility'],
            source_hint=entry['source_hint'],
            status='mirrored',
        )
        for entry in raw_entries
    )

设计要点： 使用 @lru_cache 避免重复读取 JSON，提升启动速度。

4.3 tools.py

职责： 工具清单管理、权限过滤、执行模拟。

关键代码：

python 复制代码

def filter_tools_by_permission_context(
    tools: tuple[PortingModule, ...],
    permission_context: ToolPermissionContext | None = None
) -> tuple[PortingModule, ...]:
    if permission_context is None:
        return tools
    return tuple(module for module in tools if not permission_context.blocks(module.name))

设计要点： 权限检查在路由层完成，确保执行前已通过安全审计。

4.4 query_engine.py

职责： 查询引擎核心，处理 prompt 提交、会话管理、token 预算。

关键代码：

python 复制代码

def submit_message(
    self,
    prompt: str,
    matched_commands: tuple[str, ...] = (),
    matched_tools: tuple[str, ...] = (),
    denied_tools: tuple[PermissionDenial, ...] = (),
) -> TurnResult:
    if len(self.mutable_messages) >= self:config.max_turns:
        # 返回 max_turns_reached
    projected_usage = self.total_usage.add_turn(prompt, output)
    if projected_usage.input_tokens + projected_usage.output_tokens > self.config.max_budget_tokens:
        # 返回 max_budget_reached

设计要点： 严格轮次和预算控制，防止无限循环和资源耗尽。

4.5 main.py

职责： CLI 入口，解析命令行参数并分发到对应模块。

关键代码：

python 复制代码

def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description='Python porting workspace for the Claw Code rewrite effort'
    )
    subparsers = parser.add_subparsers(dest='command', required=True)
    subparsers.add_parser('summary', help='render a Markdown summary')
    subparsers.add_parser('manifest', help='print the workspace manifest')
    # ... 更多子命令

设计要点： 使用 argparse 构建子命令体系，保持与原始系统命令接口一致。

五、常见问题与踩坑

问题	原因	解决方案
`Unknown mirrored tool`	工具名称未在清单中注册	检查 `tools_snapshot.json` 或使用 `--query` 搜索
`Max turns reached`	会话轮次超过配置阈值	调整 `QueryEngineConfig.max_turns` 或拆分任务
`Max budget reached`	Token 使用超限	调整 `max_budget_tokens` 或压缩 prompt
Rust 构建失败	缺少 cargo 或 Rust 工具链	安装 Rustup: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs
权限拒绝	工具被 `ToolPermissionContext` 拦截	检查权限配置或使用允许的工具

六、总结与展望

亮点回顾

✅ Cleanroom 实现：避开法律风险，重新构建等价能力
✅ 双轨并行：Python 易用性 + Rust 性能，兼顾开发效率和运行性能
✅ 完整镜像：命令/工具接口逐个复刻，保持兼容性
✅ AI 辅助开发工作流：使用 oh-my-codex 和 oh-my-opencode 协作完成移植

待改进

🔧 Python 实现尚未完全达到原始系统的运行时等价
🔧 Rust 端仍在开发中，部分 crate 未完成
🔧 缺少完整的 E2E 测试覆盖

适用场景

研究 harness 工程模式：学习如何设计工具绑定、会话管理、权限系统
构建自己的 AI agent 运行时：参考架构模式，定制化实现
性能敏感场景：使用 Rust 端获得更快的执行速度
教育目的：理解大型 AI 系统的内部工作机制

Claw Code：Better Harness Tools，让 AI 真正干实事