一个对泄露的 Claude Code 进行“从头重写”的项目，已成为 GitHub 上增长最快的仓库。

一、项目是什么

claw-code（仓库全名写作 Rewriting Project Claw Code）是一个围绕「智能体 Harness（ harness：把模型、工具、会话与编排层接在一起的运行时骨架）」展开的开源重写与工程化工作。它并非简单「备份某次外泄的源码树」，而是把对原系统架构模式的理解，落到可维护的 Python 优先实现与并行的 Rust 系统语言移植上，并配套清单化命令/工具镜像、一致性审计、会话与转写管线等工程能力。

项目在公开叙事上强调三点：更好的 Harness 工具链、洁净室（clean-room）式的再实现伦理、以及持续可验证的移植进度。官方 README 亦明确声明：本仓库不主张对原始 Claw Code 源码材料的所有权，且与原作者无隶属、背书或维护关系——读者在引用、二次分发或对接商业场景时，应自行评估合规与授权边界。

---

二、背景故事：从事件到工程选择

据维护者在 README 中的叙述，2026 年 3 月 31 日凌晨，Claw Code 相关源码在社群中高度曝光，引发极大关注。面对技术兴奋与潜在法律/伦理压力并存的环境，维护者选择了一条典型工程师路径：不依赖外泄快照作为长期主分支，而是在极短时间内基于对 Harness 结构的理解，从零用 Python 重写核心能力面，并在日出前完成推送。

这一过程大量依赖 oh-my-codex（OmX） 等工作流层：通过类似 $team 的并行评审与 $ralph 的持续执行/验收循环，把「读结构—定边界—写测试—收敛树形」串成可重复的自动化协作节奏。后续 Rust 移植阶段又引入 oh-my-opencode（OmO） 等工具，用于加速实现与验证支持。换言之，该项目既是「Harness 工程」样本，也是「AI 辅助大型移植」的方法论展示场。

项目在社群传播层面曾创下极快的 Star 增长记录（README 宣称数小时内突破五万星标量级），反映出全球开发者对 Agent 运行时、工具编排与可分享代码生成议题的高度关注。与此同时，维护者亦引用《华尔街日报》等报道，将个人长期使用相关系统的经历与对多模型生态的务实态度一并放入公共叙事——核心仍落回开源 Harness 研究与可延续的工程交付，而非单一产品站队。

---

三、为什么要做「重写」而不是「存档」

README 用相当克制的措辞解释了转向：最初研究外泄代码是为了理解 Harness、工具接线与智能体工作流；在更多思考法律与伦理，并阅读仓库内所附长文（关于 AI 再实现、合法性与 copyleft 侵蚀等议题）之后，维护者不希望外泄快照本身继续成为被跟踪的主源码树。

因此，仓库的「主叙事」从「保留镜像」迁移为：

1. 以 Python 工作区为当前主实现面，持续扩展可执行切片与模块边界。
2. 用清单、审计与测试把「移植到了哪一步」说清楚，避免口号式宣称。
3. 并行推进 Rust，追求更高性能、内存安全与更贴近「 definitive runtime」目标的 CLI/服务端组合。

这种立场对开源参与者意味着：你克隆到的是一条正在生长的替代实现路线，而不是某个封闭产品的内部树副本；贡献应围绕可测试的模块、清晰的子系统边界与文档化的缺口展开。

---

四、仓库布局与双轨实现

4.1 顶层结构（概念层）

当前文档描述的典型布局包括：

• src/：Python 移植工作区（活跃开发主战场）。
• tests/：针对 Python 工作区的单元/发现式测试。
• rust/：Rust workspace，承载 CLI、API 客户端、runtime、插件、命令、工具定义、兼容层、HTTP/SSE 服务、LSP 等 crate。
• assets/：配图、OmX 工作流截图等品牌/说明资源。
• 论述型 Markdown：例如关于再实现合法性的长文，为项目伦理与动机提供文本上下文。

历史上曾出现的「外泄快照」在说明中被表述为不再作为被跟踪的仓库状态的一部分；本地若仍存在被忽略的归档，仅用于可选的一致性审计，而非日常协作基线。

4.2 Python 工作区：模块宇宙

Python 侧已远超早期「几个元数据文件」的规模：src/ 下形成了大量子系统包（以顶层目录为界），用于映射原 TypeScript 时代的子系统划分与运行期关切。README 早期列出的核心文件（如 port_manifest.py、models.py、commands.py、tools.py、query_engine.py、main.py）仍在叙事上代表「清单与入口」，但实际树中还包括 runtime、session、permissions、hooks、plugins、server、voice、skills、bridge、coordinator 等方向的占位或渐进实现。

port_manifest.py 会扫描 src/ 下 Python 文件，按顶层模块聚合计数，生成 PortManifest：包含根路径、Python 文件总数、各子系统文件规模与简短说明，并可输出为 Markdown。这使得「当前工作区有多胖、哪里在长高」可以用一条命令客观打印出来，而不是依赖记忆。

---

五、Python CLI：从「看清单」到「跑一小段运行时」

src/main.py 使用 argparse 暴露丰富的子命令，整体定位是 Python 移植工作区的 CLI 入口。除 summary / manifest / subsystems 这类自省命令外，还包括：

• parity-audit：在本地存在被忽略的 TypeScript 归档时，对比 Python 工作区与归档表面的一致性（README 强调：即便镜像度提升，也尚未构成与原 TypeScript 系统完全 runtime 等价的替代品）。
• setup-report、command-graph、tool-pool、bootstrap-graph：从「启动预取」「命令图分段」「默认设置下组装的工具池」「镜像的引导/运行时阶段图」等角度输出 Markdown 报告，便于审阅架构切割是否合理。
• commands / tools：基于归档快照镜像出的命令/工具清单，支持限额、查询、过滤插件命令或技能命令、MCP、简单模式等。
• route、bootstrap、turn-loop：在镜像清单上模拟「路由提示词」「构建类会话报告」「带状态的多轮小循环」等 harness 行为切片；turn-loop 还可选择结构化输出。
• flush-transcript、load-session：与会话持久化/回放相关的实验路径。
• remote-mode、ssh-mode、teleport-mode、direct-connect-mode、deep-link-mode：对远程控制、SSH、传送、直连、深链等运行时分支的模拟，用于覆盖条件组合而非立刻对接真实网络栈。
• show-command / show-tool、exec-command / exec-tool：按精确名称查看或执行「镜像命令/工具 shim」，便于把元数据与最小可执行替身连起来测。

上述命令共同体现了一种工程哲学：先把 harness 的「inventory（清单）」与「图结构」钉死，再逐步把每条边变成真实 I/O。对新人而言，建议从 python3 -m src.main summary 与 manifest 入手，再跑 python3 -m unittest discover -s tests -v 建立对当前质量基线的体感。

---

六、Query Engine 与会话语义（Python 侧）

query_engine.py 中的 QueryEnginePort 把 PortManifest 与一组 QueryEngineConfig（最大轮次、预算 token、压缩触发轮次、结构化输出与重试等）绑在一起，并维护 session_id、可变消息列表、权限拒绝记录、用量累计、TranscriptStore 等状态。它提供 from_workspace() 与 from_saved_session() 工厂方法，分别对应「冷启动」与「自持久化会话hydrate」。

submit_message 在接近配置上限时会返回明确的停止原因（例如达到最大轮次），并把匹配到的命令/工具名、权限拒绝、用量摘要一并封装进 TurnResult。这种设计让 Python 侧可以在不依赖外部大模型 API的情况下，先把 会话状态机、权限与审计钩子、转写与压缩策略的插槽摆放到位；待后续接入真实模型与真实工具执行器时，替换的是「边」的实现，而不是整体骨架。

从研究视角看，这是典型的 Port（移植层）命名：它不是「又一个聊天封装」，而是刻意与最终 runtime 对齐的薄编排层，用来在移植早中期保持行为可推演、可测试。

---

七、Rust 工作区：走向「 definitive runtime」

README 声明 Rust 实现目标是 更快、内存安全的 harness runtime，并列出 workspace 中各 crate 的职责（不同版本 README 段落略有出入，以仓库内实际 rust/crates 为准）。常见划分包括：

• API 客户端：抽象多家提供商、OAuth、流式响应等。
• runtime：会话状态、压缩（compaction）、MCP 编排、提示构造等 harness 心脏部位。
• tools：工具清单定义与执行框架。
• commands：斜杠命令、技能发现、配置检视等交互面。
• plugins：插件模型、钩子流水线与捆绑示例插件。
• compat-harness：与上游编辑器/IDE 集成路径的兼容层。
• claw-cli：交互式 REPL、Markdown 渲染、工程引导/初始化流程等。
• server / lsp（以实际 crate 为准）：HTTP/SSE 或语言服务方向的系统扩展。

构建方式通常为进入 rust 目录执行 cargo build --release。对系统编程背景的贡献者而言，Rust 轨可以把 Python 上验证过的清单与图逐步硬化为 低延迟、强类型、可并发的实现，同时通过 compat-harness 等模块缓解生态对接成本。

---

八、一致性与「镜像清单」的数据源

Python 树中的 src/reference_data/ 存放 archive_surface_snapshot.json、commands_snapshot.json、tools_snapshot.json 以及 subsystems/ 下一系列子系统 JSON。它们扮演「对照底稿」：让命令/工具/子系统枚举在移植过程中有物可查、有 diff 可算，而不是口头对齐。

parity_audit 等路径依赖「本地被忽略的归档」这一前提——这再次强调：权威协作基线是正在提交的 Python/Rust 源码与 JSON 参考数据，而不是任何外部泄露包。新同事 onboarding 时，应先理解这层数据治理策略，避免在文档或脚本中无意引入不可分发材料。

---

九、方法论：OmX / OmO 与「洁净室」节奏

项目公开强调三类工作模式：

1. $team 模式：并行 code review 与架构反馈，适合 README、对外声明、crate 边界等「高扇出」改动。
2. $ralph 模式：长时程执行与验收循环，适合把测试红绿、parity 提升、CLI 子命令补齐等拆成可追踪的里程碑。
3. 洁净室 pass：命名/品牌清理、QA、发布前校验；Rust workspace 亦经历此类流程。

这些模式的价值不在于「工具名本身」，而在于把 大规模移植从个人英雄式熬夜，转成可重复、可审计、可并行的流水线。对中国开发者社区而言，这也是观察「如何把 AI 编程助手纳入合规工程实践」的样例文本。

---

十、适用人群与学习路径

• 想研究 Agent Harness 的工程师：可从 CLI 子命令与 QueryEnginePort 的状态设计入手，理解「清单—路由—会话—权限—转写」如何拼装。
• 想做语言运行时移植的贡献者：Python 提供快速迭代面，Rust 提供性能与部署面；先修 JSON 镜像与审计，再动真 I/O，通常是风险更低的路径。
• 关注 AI 合规与再实现伦理的研究者：仓库内长文与 README 免责声明构成互文，可对照阅读。
• 希望改进工具链的社区成员：插件、hooks、skills 等子系统目录为未来扩展预留接口面。

推荐学习顺序：

1. 阅读本仓库 README 与所有权声明。
2. 运行 summary、manifest、subsystems。
3. 跑测试，阅读 tests/ 中如何断言移植工作区。
4. 挑选一个与你背景相关的子系统目录，做「读懂数据流 + 最小修复/文档」式首 PR。
5. 若熟悉 Rust，再进入 rust/ 阅读 workspace Cargo.toml 与各 crate 的 lib 边界。

---

十一、社区与支持

项目与 instruct.kr 社群（Discord 等）相关联，定位为韩语与全球开发者讨论 大语言模型、Harness 工程、智能体工作流的交汇点。README 亦提供 GitHub Sponsors 链接，用于支持持续的 harness 工程研究。Star 历史图等指标更多是社群注意力的刻画，真正决定项目寿命的仍是：测试是否绿、parity 是否诚实、Rust/Python 双轨是否可持续收敛。

---

十二、Harness 工程在解决什么问题

若把大模型比作「会推理与生成文本的大脑」，Harness 就是把大脑放进可重复实验与可部署环境里的那一整套外骨骼。它通常要同时回答以下几类问题，而 claw-code 的 Python/Rust 分层正是在这些方向上逐块落子。

第一，上下文如何组织与压缩。 真实对话与工具调用会迅速撑爆上下文窗口；Harness 需要决定何时摘要、如何保留关键决策痕迹、怎样在「人类可读」与「机器可解析」之间折中。QueryEnginePort 中的 compact_after_turns 等配置，就是在移植阶段为这类策略预留旋钮——即便当前实现仍是占位或轻量模拟，接口先行能避免后期全局重构。

第二，工具如何被发现、校验与执行。 从文件系统、终端命令到浏览器与专有 API，工具表面各异，但 Harness 需要统一的清单（manifest）、权限模型与失败语义（超时、部分成功、需用户确认）。Python 侧的 ToolPermissionContext、assemble_tool_pool 与 commands/tools 子命令，本质上是在把「工具宇宙」从散文描述拉成可枚举、可过滤、可拒绝的数据结构。

第三，会话与审计。 企业场景与个人极客场景都会追问：这一轮谁说了什么、模型调了哪些工具、哪些被拒绝、成本如何累计。TranscriptStore、会话持久化相关命令，以及 UsageSummary 一类模型字段，指向的是可回放、可对账的运行史，而不是一次性打印到终端的日志。

第四，运行时分支与环境。 远程开发、SSH、深链唤起、Teleport 式跳转等，本质都是「用户从哪进来、工作目录与凭证如何注入」的组合爆炸。main 里大量 *-mode 子命令以模拟分支的方式先把状态机画全，再决定是否接入真实网络与进程——这是降低早期集成风险的标准手法。

第五，扩展与插件。 Hooks、plugins、skills 等子系统在商业产品与开源生态里往往决定「能否让社区长出来」。claw-code 在目录层面预留这些包，意味着长期目标不是单一二进制，而是可插拔流水线：同一 runtime 核，多种捆绑与第三方扩展并存。

把以上问题拆开来看，就能理解为何 README 反复强调 parity（一致性） 与 checkpoint（检查点）：Harness 的难点不在于写出第一个能跑的 demo，而在于在复杂度上升时仍能保持行为可解释、可测试、可渐进替换。

---

十三、主要子系统目录导读（Python 树）

下列名称以 src/ 顶层包为主，侧重「这一坨在架构叙事里通常干什么」，具体完成度需结合源码与测试阅读。

• assistant：通常承载与「助手」交互面相关的协调逻辑，例如把用户意图导向命令、工具或内部服务；在完整系统中常是 UI/协议层与 runtime 的粘合处。
• bridge：桥接层，多用于对接外部编辑器、协议或另一进程的 IPC；Harness 往往通过 bridge 把「宿主环境」与「代理运行时」隔离。
• bootstrap 与 bootstrap_graph：启动与初始化阶段：配置发现、预取、依赖图或阶段化启动；对应 CLI 的 bootstrap-graph 报告。
• cli / entrypoints：命令行或多种入口形态的统一出口，便于把同一核心逻辑暴露给脚本、IDE 与服务器。
• coordinator：多任务或多通道协调：并行请求、合并结果、冲突解决等；在复杂 harness 里常见。
• hooks / plugins / skills：扩展三角：生命周期钩子、插件包模型、可发现技能；决定生态是否可第三方化。
• server：若走向常驻服务（HTTP/SSE 等），服务端骨架常落于此；与 Rust 侧的 server crate 可能形成「原型—硬化」关系。
• session_store / context / history：会话存储、上下文拼装、历史检索；与 Query Engine 的状态字段相互呼应。
• permissions / cost_tracker / costHook：权限拒绝路径与成本计量；对企业落地与自我约束都关键。
• remote / upstreamproxy / remote_runtime：远程与上游代理相关分支，对应多种 *-mode 模拟入口。
• voice / screens / vim / keybindings / outputStyles：交互形态与展示层：语音、终端界面、编辑器适配、快捷键与输出风格。
• schemas / types / reference_data：类型与 JSON schema、以及镜像快照数据；是 parity 与代码生成的共同地基。
• native_ts / migrations：与历史 TypeScript 资产或迁移脚本相关的过渡层，提醒读者「双栈并存期」如何管理。
• memdir / moreright / buddy 等：多为产品语义命名的子域，在原始系统中往往对应具体功能岛；移植时保留目录名有助于对照审计。

这一节的目的，是帮助新读者在打开 src/ 时不被几十个文件夹吓退：先按「会话—工具—扩展—入口—桥接」五条轴去归类，再深入单包阅读，效率会高得多。

---

十四、测试、审计与「诚实的未完成」

README 中的 Current Parity Checkpoint 写得非常直白：Python 工作区在根入口文件表面、顶层子系统命名、命令/工具清单等维度上已经更贴近归档镜像，但仍不是与原 TypeScript 系统 runtime 等价的一比一替代品；可执行运行时切片数量仍少于完整归档所暗示的规模。

这种表述是成熟开源项目的标志：把营销让位于事实。对贡献者而言，这意味着：

1. 测试是门禁：python3 -m unittest discover -s tests -v 应成为每次改动的默认动作；若测试覆盖不足，优先补测再扩功能。
2. parity-audit 是镜子：有归档时跑审计，没有归档时依赖 reference_data 与代码审查；不要假设「目录长得像就等于行为像」。
3. CLI 子命令分两类：一类是「纯报告/纯模拟」，一类是「未来会接真 I/O」；改之前先读 help 字符串与 main 分支，避免把模拟层误当生产路径。

Rust 侧同理：cargo test 与 CI 工作流（若启用）是合并前的底线；内存安全与并发带来的新 bug 形态，要求更严格的代码审阅与模糊测试规划——这些都可以在未来社区治理里逐步制度化。

---

十五、如何理性看待热度、Star 与长期维护

短时间内极高的 Star 曲线，既说明话题踩在时代情绪上，也会带来错配期望：有人以为克隆即可得到与商业产品逐像素一致的体验，有人则期待立刻出现稳定的 LTS 发行版。对 claw-code 而言，更健康的期待模型是：

• 它是一个研究型与工程型混合的仓库，首要产出是可读的架构切片与可跑的 harness 试验床，而不是承诺 SLA 的云服务。
• 双语言轨意味着维护成本上升，但也提供了「快速迭代（Python）+ 性能与分发（Rust）」的经典分工；社区可以按自己的技能栈选战场。
• 赞助与 Discord 能把散落的讨论聚合成知识库，但真正沉淀仍是 issue、PR、测试与文档；热度若不转化为贡献者留存，曲线终会回落——这对所有爆款开源项目都成立。

若你只想「用」而不「造」，建议同时关注上游生态里更成熟的分发渠道；若你愿意「造」，这里提供了难得的透明移植过程：你能看到清单如何生成、审计如何写、会话状态如何建模，而不是只看到黑盒二进制。

---

十六、合规提醒与协作礼仪（贡献前必读）

再次归纳免责声明：仓库不声称拥有原始材料版权，也不代表官方产品。参与讨论与 PR 时，请避免：

• 在 issue 中粘贴或请求他人提供未授权的完整外泄源码或二进制；
• 将本仓库称为「官方续作」或误导性品牌关联；
• 把 parity 工具输出当作法律意义上的「未侵权证明」——它只是工程对比辅助。

正向做法包括：引用公开文档与接口约定、用洁净室描述问题、用测试用例复现 bug、在 PR 描述里写清行为变更与风险，尊重维护者设定的边界。如此，项目才能在舆论与法律双重压力下仍保持可延续的协作。

---

附录 A：常用命令速查（本地实践）

下列命令均在仓库根目录、已配置好 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
python3 -m unittest discover -s tests -v

若你本地存在维护者文档所述的、已被版本控制忽略的 TypeScript 归档，还可尝试 parity-audit 获得对照报告；无归档时不必强求，先把 reference_data 与当前 src/ 读通同样有价值。Rust 侧则在 rust 目录执行 cargo build --release，并用各 crate 的 README 或 lib 文档（若有）理解依赖方向。

---

附录 B：术语对照与阅读提示

• Harness：本文译为「运行时骨架」或保留英文；指围绕模型构建的工具、会话、权限与编排总体。
• Port / Porting：移植；此处强调结构对齐与行为渐进一致，而非一次到位的逐行翻译。
• Shim：薄封装或替身实现；exec-command 等路径常在早期用 shim 验证元数据与调用约定。
• Parity：一致性；在工程上多指可度量的表面对齐（文件、子系统、清单），不等同于版权或法律结论。
• Compaction：上下文压缩；长会话场景下将历史折叠为更短表示，以腾出 token 给新推理。
• MCP：Model Context Protocol 一类工具编排协议的业界简称出现场景较多；具体以你对接的实现为准。

阅读英文 README 时，可把 「not yet runtime-equivalent」 当作整个仓库的基调句：它邀请你参与把「尚未」变成「更接近」，而不是掩饰缺口。

---

附录 C：面向中文读者的延伸思考

智能体系统正在从「对话框里的奇迹」过渡到「与真实世界打交道的软件」，Harness 层的工程化程度将直接决定可靠性、成本与合规三条底线能否同时守住。claw-code 以公开方式展示清单驱动、审计驱动、测试驱动的移植节奏，对中文技术社区至少有三点启发：其一，再实现可以成为学习与创新的路径，但必须以尊重权利与透明边界为前提；其二，AI 辅助开发若要进入严肃场景，需要像 OmX/OmO 那样把「人机协作」模板化，而不是停留在偶尔成功的提示词；其三，双语言栈不是炫技，而是让探索期与硬化期各得其所——Python 负责把问题空间跑通，Rust 负责把性能与安全压进产品形态。

若你从事企业内平台搭建，可把本仓库当作需求清单生成器：哪些子系统必须存在、哪些 CLI 报告能帮助架构评审、哪些权限与审计字段不可省略，都能从目录与数据文件反推。若你从事教学，可把 turn-loop 与 QueryEnginePort 当成课堂上的迷你案例：在不调用外部模型的情况下，仍能演示状态、停止条件与结构化输出开关如何改变用户体验。这样的读法，能把一个热点仓库从「围观对象」还原为可持续钻研的教材。

最后提醒：技术叙事会随时间更新，分支合并与 Rust main 线推进可能改变部分命令或 crate 名称；当你发现本文与本地代码不一致时，以当前检出为准，并欢迎你在社区中反馈文档滞后之处——这也是开源协作的日常一部分。

---

十七、小结

claw-code 把一次轰动性的事件，转译为一条清晰的工程路线：用可验证的 Python 移植承载架构理解，用 Rust 追求运行时终局形态，用 JSON 镜像与审计把「像不像」从争论变成数据，用 OmX/OmO 等工作流把协作从偶然变成方法。 它既是对特定智能体编辑/编码系统 Harness 的再实现尝试，也是开源社群在 合规、伦理与性能 三角张力下如何做选择的公开实验场。