中文 English

Clawd Code 最新代码解析：一个 Python-first 的 Claude Code 重写工作区如何组织命令、工具、会话与审计

发布时间: 2026-03-31
clawd-code claude-code python agent architecture audit porting

我重新看了 margrop/clawd-code 的最新代码之后，得出的第一印象是：这仓库已经不再是“泄露源码镜像”的延续叙事了，而是一个明确的 Python-first porting workspace。它的 tracked tree 里，src/ 是活动实现，tests/ 是验证层，archive/claude_code_ts_snapshot/ 是可选的本地归档，src/reference_data/ 则保存了命令、工具和表面覆盖率的镜像数据。

这意味着项目关注点变了。它不再只问“原始 Claude Code 是怎么写的”，而是问：

  1. 旧系统的结构能不能被重新组织成更清晰的 Python 工程；
  2. 命令、工具、会话、权限和启动顺序能不能被显式建模；
  3. 当前 porting workspace 到底覆盖到了旧体系的哪些边界；
  4. 哪些部分只是镜像，哪些部分还只是骨架，哪些部分已经能跑出可读的 runtime 报告。

从这个角度看，这个仓库更像一套“重建中的工程系统”，而不是“保存原样的源码档案”。这也是我把这篇文章重新更新的原因。上一版文章仍然围绕旧快照本体，这一版必须围绕最新的 Python porting 工作区本身来写。

这次更新，我只想讲清楚一件事：最新代码到底把什么东西变成了数据，把什么东西变成了状态，把什么东西变成了流程。
如果你看懂了这三件事，就看懂了这个仓库现在的工程思想。

一、先看仓库的形态，再谈架构

最新 README 已经把路线说得很明白：tracked repo 的主体是 Python porting work，而不是原始 TypeScript snapshot。当前能看到的关键入口有这些：

  1. python3 -m src.main summary
  2. python3 -m src.main manifest
  3. python3 -m src.main parity-audit
  4. python3 -m src.main setup-report
  5. python3 -m src.main command-graph
  6. python3 -m src.main tool-pool
  7. python3 -m src.main bootstrap-graph
  8. python3 -m src.main subsystems --limit 32
  9. python3 -m src.main commands --limit 20
  10. python3 -m src.main tools --limit 20
  11. python3 -m src.main route "<prompt>"
  12. python3 -m src.main bootstrap "<prompt>"
  13. python3 -m src.main turn-loop "<prompt>"
  14. python3 -m src.main flush-transcript "<prompt>"
  15. python3 -m src.main load-session <session_id>
  16. python3 -m src.main remote-mode <target>
  17. python3 -m src.main ssh-mode <target>
  18. python3 -m src.main teleport-mode <target>
  19. python3 -m src.main direct-connect-mode <target>
  20. python3 -m src.main deep-link-mode <target>
  21. python3 -m src.main show-command <name>
  22. python3 -m src.main show-tool <name>
  23. python3 -m src.main exec-command <name> <prompt>
  24. python3 -m src.main exec-tool <name> <payload>

如果只看命令表，你会觉得这像一个“工具仓库”。但最新代码真正重要的不是工具数量，而是它把整个 porting 工作切成了几层：

  1. 面向仓库形态的 port_manifest；
  2. 面向命令/工具镜像的 commands、tools、command_graph、tool_pool；
  3. 面向运行时会话的 query_engine、runtime、history、transcript、session_store；
  4. 面向启动秩序的 setup、prefetch、deferred_init、bootstrap_graph；
  5. 面向审计的 parity_audit；
  6. 面向远程分支的 remote_runtime、direct_modes。

这套切法很重要，因为它说明最新仓库的目标不是“把旧系统一比一翻译成 Python”，而是把旧系统拆成可观察、可组合、可验证的结构，再一步一步补全。

二、道：先定义方向，再定义实现

如果从道家的角度看，这个仓库现在的“道”不再是旧快照的代码文本，而是 porting 这件事本身的方向。

PortManifest 是这个方向最直接的表达。它不做复杂推理，只负责一件事：把当前 workspace 的形态描述出来。
build_port_manifest() 会扫描 src/ 下的 Python 文件，统计总数，按顶层目录聚合模块，并把这些结果整理成 Markdown。这个动作非常朴素，但它的意义很大：

  1. 它让“当前进度”可见；
  2. 它让“活着的模块”可枚举；
  3. 它让“porting 到底做了多少”可以被持续比较；
  4. 它把工程的注意力从“原始源码长什么样”转成“当前 workspace 长什么样”。

这就是“道”的第一层：不是给模型一段大而全的说明，而是给它一个稳定的方向盘。
最新代码里，QueryEnginePort.render_summary() 的作用也很像“把道写成可读摘要”。它把 PortManifest、命令面、工具面、会话状态、预算信息、转录状态串成一页总结。这个 summary 不负责执行，但它负责告诉你：系统现在到底运行在什么层次。

我很喜欢这类设计，因为它不装神秘。它不说“我已经理解了整个系统”，它只说“当前工作区是什么状态，命令和工具面是什么状态，预算和转录是什么状态”。在一个 porting workspace 里，这种克制比花哨更重要。

三、法：命令图、工具池、权限和启动图，决定系统怎么组织

如果说“道”是方向，那么“法”就是组织纪律。最新代码最显著的改进，就是把原来可能散落在脚本或口头约定里的东西，变成了可读的数据结构。

3.1 commands.py：命令不是 if/else，而是镜像表

commands.py 会从 src/reference_data/commands_snapshot.json 读取命令条目，然后构造成 PortingModule 的 tuple。它提供了几个很实用的动作：

  1. get_command(name)：按名字精确取一个命令；
  2. get_commands(...)：按是否包含 plugin-like / skill-like 条目过滤；
  3. find_commands(query)：按关键字搜索；
  4. execute_command(name, prompt)：返回一个“镜像执行”结果；
  5. render_command_index(...)：把命令条目渲染成 Markdown。

这里最有意思的是 execute_command() 的语义。它不是在真实执行旧 Claude Code 的行为，而是在说：
“如果这个镜像命令存在，它在这个 prompt 下会由哪个镜像条目处理。”

这是一种很聪明的 porting 策略。它把“可执行”先降级成“可解释”，再把“可解释”慢慢往真实执行逼近。对一个还在重建中的系统来说，这样更安全，也更容易验证。

3.2 tools.py：工具池不是列表，而是可过滤的能力面

tools.py 和 commands.py 很像，但它多了一层权限感。
它同样从 src/reference_data/tools_snapshot.json 加载工具条目，同时支持：

  1. simple_mode：只保留最基础的一小撮工具；
  2. include_mcp：控制是否保留 MCP 相关条目；
  3. ToolPermissionContext：按工具名或前缀拒绝工具。

这意味着工具不是“全部展开给模型”，而是可以按策略收缩。
ToolPermissionContext.blocks() 的语义很直接：如果名字在 deny list 里，或者工具名前缀命中拒绝规则，就不让它进入工具池。

这个设计很像道家的“有为”和“无为”之间做节制。不是所有能力都要一次性放出来，能力越多，边界越要清楚。
在一个 agent 工程里，工具越像权力，权力越需要边界。

3.3 command_graph.py 和 tool_pool.py：把镜像变成结构

最新代码并没有满足于“我能列出命令/工具”这一步，而是继续往上做了结构化：

  1. CommandGraph 把命令分成 builtins、plugin_like、skill_like；
  2. ToolPool 则把工具池再按 simple_mode、include_mcp 和权限上下文过滤一遍。

这很重要，因为它说明项目不是只在做数据采集，而是在做“语义归类”。

build_command_graph() 的逻辑其实非常朴素：它根据 source_hint 里的文本，把命令拆成不同的类别。
但这个朴素恰恰是工程价值所在，因为它是透明的、可重放的、可解释的。相比用一层看不见的向量相似度做分类，这种规则更容易调试，也更适合 porting 工作。

3.4 bootstrap_graph.py：启动顺序本身就是规矩

build_bootstrap_graph() 直接把启动阶段写成了一串 stage：

  1. top-level prefetch side effects
  2. warning handler and environment guards
  3. CLI parser and pre-action trust gate
  4. setup() + commands/agents parallel load
  5. deferred init after trust
  6. mode routing: local / remote / ssh / teleport / direct-connect / deep-link
  7. query engine submit loop

这其实非常像一份“运行戒律”。
它告诉你：先预取，再加防线；先解析 CLI，再做信任闸门；先装载基础能力，再决定要不要延迟初始化；最后才进入 mode routing 和 query loop。

这不是炫技，这是秩序。一个 agent 系统如果没有启动秩序，很容易把副作用、权限、路由和上下文混成一坨。最新仓库把这些步骤显式列出来，我认为这是它最成熟的部分之一。

四、体：会话、历史、转录，构成系统的身体

如果说前面讲的是“法”，那么现在讲“体”。

QueryEnginePort 是当前工作区里最像“身体”的对象。它不是单纯的函数对象，而是有状态的：

  1. session_id
  2. mutable_messages
  3. permission_denials
  4. total_usage
  5. transcript_store

这五样东西合在一起，构成了一个会变化、会压缩、会持久化的运行体。

4.1 submit_message()：一次 turn 不是一次输出，而是一轮状态更新

QueryEnginePort.submit_message() 做的事并不花哨，但很完整：

  1. 如果 turn 数超过上限，就提前返回；
  2. 生成摘要行，包括 prompt、命中的命令、命中的工具、权限拒绝数量；
  3. 根据 prompt 和 output 更新 token 预算；
  4. 计算 stop_reason；
  5. 把 prompt 追加到 mutable_messages；
  6. 同时写入 TranscriptStore；
  7. 合并 permission denials；
  8. 必要时压缩消息；
  9. 返回 TurnResult。

这说明这个系统把“回答”当成状态机的一步，而不是一次性的字符串输出。
对 porting workspace 来说，这非常合理，因为它的目标本来就不是“生成多精彩的文本”，而是“把工作流稳稳地跑完”。

4.2 stream_submit_message()：流式事件是为了让状态可观察

stream_submit_message() 会把一次 turn 拆成事件流：

  1. message_start
  2. command_match
  3. tool_match
  4. permission_denial
  5. message_delta
  6. message_stop

这是一种很清楚的建模方式。
它让 runtime 不再只是“有输出/没输出”的二元状态，而是一个可以被前端、日志或测试观察的事件序列。

我特别喜欢这一点，因为它让“调试”变成了“看事件”，而不是“猜内部发生了什么”。
一个好的 agent 运行体，不是把所有复杂度藏起来，而是把复杂度变成可读的阶段。

4.3 HistoryLog、TranscriptStore 和 StoredSession

最新代码把历史和转录拆开了：

  1. HistoryLog 记录的是运行阶段级别的事件；
  2. TranscriptStore 记录的是消息转录；
  3. StoredSession 则是最后真正落盘的会话快照。

TranscriptStore 还有一个很小但很好的设计：flushed 标记。
这让你知道当前转录是不是已经冲刷到持久层，而不是只停留在内存里。它还能 compact()、replay()，这意味着会话既可回放，也可收缩。

换句话说，身体不是临时变量的集合，而是一个可保留记忆、可压缩负担、可恢复现场的东西。

五、术：路由、执行、远程模式，让系统真正开始动

如果前面讲的是组织和状态，那这一节就讲“术”。
PortRuntime 是最新代码里非常关键的对象，因为它把“镜像”变成了“可运行的工作流”。

5.1 route_prompt()：不是 embedding，而是透明的 token scoring

PortRuntime.route_prompt() 的路由方式很有意思。它不是把 prompt 丢给一个黑箱分类器，而是：

  1. 先把 prompt 里的 /、- 等符号替换掉；
  2. 再按 token 分词；
  3. 用 token 和模块名、source_hint、responsibility 做子串匹配；
  4. 计算一个简单分数；
  5. 按分数排序，选择最相关的命令和工具。

这意味着路由是透明的、可预测的、可调的。
它不会像 embedding 检索那样“看起来很聪明，但说不清为什么命中”。
在一个 porting 体系里，这种可解释性特别重要，因为你要知道自己到底是在沿用原系统的语义，还是在自己发明新的语义。

5.2 bootstrap_session()：把上下文、setup、registry、runtime 串成一个会话

bootstrap_session() 基本上就是最新仓库里最完整的一次“起飞”流程。它会：

  1. build_port_context()，统计源码、测试、assets、archive 是否可见；
  2. run_setup(trusted=True)，触发预取和延迟初始化；
  3. 创建 HistoryLog；
  4. 记录 commands 和 tools 的条目数；
  5. route_prompt() 找到相关命令/工具；
  6. build_execution_registry() 把镜像命令和镜像工具做成可执行适配器；
  7. 生成 command/tool execution messages；
  8. 推断 permission denials；
  9. 让 QueryEnginePort 处理一次 turn，并生成 stream events；
  10. persist_session() 保存会话；
  11. 汇总成 RuntimeSession。

这个函数特别像一条“把抽象变成现场”的流水线。
它不是只返回一个字符串，而是返回一整个 session 报告：上下文、设置、系统初始化、路由结果、执行结果、流式事件、turn 输出、转录路径、历史记录。

这就是我说它是“运行体”的原因。它已经不是简单的查询引擎，而是一套小型的会话编排系统。

5.3 run_turn_loop()、remote_runtime.py、direct_modes.py

run_turn_loop() 则把会话变成循环。它会把 prompt 在多轮里重复送进 engine，并根据 stop_reason 决定是否继续。
这让系统可以模拟一个有限的对话/执行循环，而不是一次性走到底。

远程模式这边，remote_runtime.py、direct_modes.py 提供的是当前还偏“占位”的分支：

  1. remote
  2. ssh
  3. teleport
  4. direct-connect
  5. deep-link

它们现在更像运行分支的骨架，而不是完整的执行引擎。
但我认为这并不减分。相反，它告诉我们最新仓库已经把未来路线预留出来了：本地工作区、远程控制、SSH 代理、Teleport 恢复、直接连接、深链接式路由，都被当成了可独立建模的模式。

六、启动：预取、延迟初始化和可信门控，是这版最值得抄的地方

如果要从最新代码里挑一个我最喜欢的设计，那就是启动链。

build_bootstrap_graph() 已经把启动顺序写成了规矩，而 setup.py、prefetch.py、deferred_init.py 则把这个规矩落成了结构。

6.1 run_setup()：先预取，再看门

run_setup() 会先做三件预取：

  1. start_mdm_raw_read()
  2. start_keychain_prefetch()
  3. start_project_scan(root)

注意，这里不是在说“真的执行复杂系统动作”，而是在说“启动阶段的顺序要这么组织”。
这个顺序很重要：先把环境信息拉出来，再决定后面的事情是否可信。

6.2 run_deferred_init(trusted)：信任一开，能力才进入

deferred_init.py 也非常干净。它把 trusted 这个布尔值直接映射成四个开关：

  1. plugin_init
  2. skill_init
  3. mcp_prefetch
  4. session_hooks

如果 trusted=False，这些能力全部收起来；如果 trusted=True，它们才开始工作。

这很像一个明确的门槛设计。它不是“先全开再慢慢限制”，而是“先看信任，再决定范围”。
我个人认为，这种顺序比事后补限制更稳。因为在 agent 系统里，启动时的副作用经常比运行时的输出更危险。

6.3 SetupReport：把启动链变成可审查的 Markdown

SetupReport.as_markdown() 会列出：

  1. Python 版本
  2. 平台
  3. trusted 状态
  4. 当前 CWD
  5. 各个 prefetch 项
  6. deferred init 的各项开关

这和前面的 summary 很一致：它不是帮你“做更多事”，而是帮你“看清楚已经做了什么”。
一个重建中的工程系统，最怕的不是能力不够，而是不知道自己当前到底开启了什么。

七、审计：parity audit 不是装饰，而是项目的自我约束

最新代码里最有分量的模块之一，是 parity_audit.py。
因为它直接告诉你：这个 porting workspace 到底镜像了什么，缺了什么，哪些地方还只是努力中的边界。

它比较的不是一个抽象的“像不像”，而是几个具体维度：

  1. root 文件覆盖；
  2. 目录覆盖；
  3. 当前 Python 文件数量 vs archive 的 TS-like 文件数量；
  4. command snapshot 条目数；
  5. tool snapshot 条目数；
  6. 缺失的 root targets；
  7. 缺失的 directory targets。

更重要的是，它把几个数字说得很直白：

  1. total_ts_like_files = 1902
  2. command_entry_count = 207
  3. tool_entry_count = 184

这三个数字说明了什么？

说明这个仓库已经不是“偶尔写几个 Python 文件试试”，而是在用结构化数据承接一个相当大的旧工程表面。

run_parity_audit() 还有一个很值得注意的设计：如果本地 archive 不可用，它不会假装能审计，而是直接告诉你不能比较。
这是一种非常好的工程态度。因为它不把“缺数据”伪装成“没差异”。
对一个正在重建的系统来说，这种诚实比“看起来很完整”更重要。

八、它和上一版最大的不同：从“读泄露源码”变成“读重写工作区”

这一点必须单独说清楚。

上一版文章的主角还是“泄露的 Claude Code 源码及其重写理解”。
而最新仓库的主角已经变成了：

  1. Python-first 的 porting workspace；
  2. snapshot-driven 的镜像数据；
  3. 可运行的 summary / route / bootstrap / loop / audit 工具；
  4. 明确的 local archive 和 tracked Git history 分离；
  5. 还在演化中的 runtime parity。

换句话说，项目的视角从“复现原系统是什么”转向了“如何把原系统拆成可验证的工程片段”。

这不是小变化。
因为一旦你承认自己在做 porting，而不是在做 archive，你就必须接受以下事实：

  1. 代码可以先是镜像，不必先是完整替身；
  2. 模块可以先是骨架，不必先是全部实现；
  3. 审计可以先衡量覆盖，而不是先假定等价；
  4. runtime 可以先能报告，再慢慢能执行。

这比“我已经完整复刻了”更诚实，也更像真正的工程。

九、如果用道法体术来总结这版仓库

道

道不是旧源码，而是 porting 的方向：

  1. 先让结构可见；
  2. 再让镜像可检；
  3. 最后让运行可解释。

法

法是命令图、工具池、权限上下文、启动图：

  1. command_graph 把命令分层；
  2. tool_pool 把工具收缩成可控能力；
  3. ToolPermissionContext 把拒绝变成规则；
  4. bootstrap_graph 把启动顺序写成纪律。

体

体是会话和历史：

  1. QueryEnginePort 有 session；
  2. HistoryLog 记录阶段；
  3. TranscriptStore 能 compact / replay / flush；
  4. StoredSession 能落盘。

术

术是路由、执行、模式、持久化：

  1. route_prompt() 用透明的 token scoring；
  2. build_execution_registry() 把镜像模块变成适配器；
  3. bootstrap_session() 把一次运行完整串起来；
  4. remote_runtime 和 direct_modes 给未来路由留出口。

十、最后我想说的，是这类重写最值得保留的东西

我不太喜欢把这类项目简单称作“抄”或者“复刻”。
从最新代码看，它更像是一次把旧系统拆开、对照、归档、重组，再逐步推进实现的工程。

这种工程最值得保留的，不是某一段代码，而是三种自觉：

  1. 镜像自觉：知道自己当前只是覆盖面，不是完全替身；
  2. 审计自觉：知道自己缺什么，而不是只展示已有的；
  3. 启动自觉：知道先做什么，再做什么，最后做什么。

这三种自觉合在一起，才会让一个 porting workspace 从“演示项目”变成“可持续演化的工程体系”。

如果你要从这版仓库里拿走一个结论，那我会选这一句：

现在的 Clawd Code 不是在炫耀它看见了什么旧代码，而是在展示它如何把旧系统的结构翻译成可验证、可组织、可审计的 Python 工作区。

这才是最新代码真正值得写进博客的地方。

参考阅读

  1. https://github.com/margrop/clawd-code
  2. https://github.com/XingP14/claude-code
  3. https://github.com/ghuntley/claude-code-source-code-deobfuscation