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

Claw CodeBetter 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 CLIQueryEnginePort命令路由工具路由命令清单工具清单执行层会话存储转录存储2.2 核心设计思路Cleanroom 原则不直接复制原始源码而是通过研究架构模式harness、工具绑定、会话管理重新实现。双轨并行Python 负责快速迭代、原型验证、易用性Rust 负责性能关键路径、内存安全、生产级运行时镜像机制通过reference_data/commands_snapshot.json和tools_snapshot.json记录原始系统的接口清单Python 实现逐个镜像这些能力。2.3 数据流通过拒绝用户 Prompt路由层命令/工具匹配权限检查执行拒绝处理会话更新消息压缩返回结果三、实用教程3.1 环境准备# 克隆仓库gitclone https://github.com/ultraworkers/claw-codecdclaw-code# Python 环境准备python3-mpipinstall-e.# Rust 构建可选cdrustcargobuild--release3.2 快速开始# 查看当前 Python 移植状态摘要python3-msrc.main summary# 打印工作空间清单python3-msrc.main manifest# 列出当前已镜像的模块python3-msrc.main subsystems--limit16# 列出命令清单python3-msrc.main commands--limit10# 列出工具清单python3-msrc.main tools--limit103.3 配置说明参数默认值说明max_turns8单会话最大轮次max_budget_tokens2000最大 token 预算compact_after_turns12触发消息压缩的轮次阈值structured_outputFalse是否启用结构化输出3.4 进阶用法# 路由测试将 prompt 分发到命令/工具python3-msrc.main route帮我写一个排序算法--limit5# Bootstrap 模拟构建运行时风格会话报告python3-msrc.main bootstrap分析这个文件--limit5# Turn 循环运行小型状态轮次循环python3-msrc.main turn-loop实现一个 API--max-turns3# 会话持久化python3-msrc.main flush-transcript会话内容python3-msrc.main load-sessionsession_id# 运行验证python3-munittest discover-stests-v四、核心模块解读4.1 models.py职责定义核心数据模型包括子系统、移植模块、权限拒绝、使用统计等。关键代码dataclass(frozenTrue)classPortingModule:name:strresponsibility:strsource_hint:strstatus:strplanneddataclassclassPortingBack:title:strmodules:list[PortingModule]field(default_factorylist)设计要点使用dataclass(frozenTrue)确保不可变性便于并发场景和缓存优化。4.2 commands.py职责命令清单管理、查找、执行路由。关键代码lru_cache(maxsize1)defload_command_snapshot()-tuple[PortingModule,...]:raw_entriesjson.loads(SNAPSHOT_PATH.read_text())returntuple(PortingModule(nameentry[name],responsibilityentry[responsibility],source_hintentry[source_hint],statusmirrored,)forentryinraw_entries)设计要点使用lru_cache避免重复读取 JSON提升启动速度。4.3 tools.py职责工具清单管理、权限过滤、执行模拟。关键代码deffilter_tools_by_permission_context(tools:tuple[PortingModule,...],permission_context:ToolPermissionContext|NoneNone)-tuple[PortingModule,...]:ifpermission_contextisNone:returntoolsreturntuple(moduleformoduleintoolsifnotpermission_context.blocks(module.name))设计要点权限检查在路由层完成确保执行前已通过安全审计。4.4 query_engine.py职责查询引擎核心处理 prompt 提交、会话管理、token 预算。关键代码defsubmit_message(self,prompt:str,matched_commands:tuple[str,...](),matched_tools:tuple[str,...](),denied_tools:tuple[PermissionDenial,...](),)-TurnResult:iflen(self.mutable_messages)self:config.max_turns:# 返回 max_turns_reachedprojected_usageself.total_usage.add_turn(prompt,output)ifprojected_usage.input_tokensprojected_usage.output_tokensself.config.max_budget_tokens:# 返回 max_budget_reached设计要点严格轮次和预算控制防止无限循环和资源耗尽。4.5 main.py职责CLI 入口解析命令行参数并分发到对应模块。关键代码defbuild_parser()-argparse.ArgumentParser:parserargparse.ArgumentParser(descriptionPython porting workspace for the Claw Code rewrite effort)subparsersparser.add_subparsers(destcommand,requiredTrue)subparsers.add_parser(summary,helprender a Markdown summary)subparsers.add_parser(manifest,helpprint the workspace manifest)# ... 更多子命令设计要点使用argparse构建子命令体系保持与原始系统命令接口一致。五、常见问题与踩坑问题原因解决方案Unknown mirrored tool工具名称未在清单中注册检查tools_snapshot.json或使用--query搜索Max turns reached会话轮次超过配置阈值调整QueryEngineConfig.max_turns或拆分任务Max budget reachedToken 使用超限调整max_budget_tokens或压缩 promptRust 构建失败缺少 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 系统的内部工作机制