本文最后更新于
2026-03-31,某些文章具有时效性,若有错误或已失效,请在下方
留言或联系
老夜。
Claude Code源码泄露深度分析:Agent Harness架构全解密
从TypeScript到Python的架构逆向工程 · 揭示AI Agent核心运行机制
2026年3月31日凌晨,Claude Code源码意外泄露。开发者社区迅速响应,其中@instructkr在12小时内完成从TypeScript到Python的干净重写(Clean Room Rewrite)。本文基于Python重写项目,深入分析Claude Code的Harness架构设计。
2026年3月31日凌晨4点,Claude Code的源码被意外暴露。整个开发者社区陷入疯狂,Reddit、Twitter、Hacker News上到处都在讨论这个”史诗级泄露”。
开发者@Nstructkr的反应: 在女朋友担心法律风险时,他选择了最工程师的方式应对——连夜将核心功能从TypeScript移植到Python。 整个过程使用oh-my-codex (OmX)工作流驱动: • $team模式:并行代码审查 • $ralph模式:持久执行循环 + 架构级验证
1.1 什么是Clean Room Rewrite
Clean Room Rewrite(净室重写)是一种法律上安全的逆向工程方法:通过理解原有系统的架构和行为,用完全独立实现的代码重新构建相同功能。
关键原则: • 不复制任何专有代码 • 只实现相同的功能和行为 • 从零开始编写,保持架构相似但代码独立
Python重写项目完整保留了原Claude Code的模块组织结构:
src/ ├── assistant/ # Assistant核心模块 ├── bootstrap/ # 启动引导 ├── bridge/ # 跨模块桥接 ├── buddy/ # Buddy协同模块 ├── cli/ # 命令行接口 ├── components/ # UI组件 ├── coordinator/ # 任务协调器 ├── entrypoints/ # 入口点 ├── hooks/ # 生命周期钩子 ├── keybindings/ # 快捷键绑定 ├── memdir/ # 记忆目录 ├── migrations/ # 数据迁移 ├── moreright/ # 权限管理 ├── native_ts/ # TypeScript原生桥接 ├── plugins/ # 插件系统 ├── reference_data/ # 参考数据 ├── remote/ # 远程运行时 ├── schemas/ # 数据Schema ├── screens/ # 屏幕管理 ├── server/ # 服务端 ├── services/ # 业务服务 ├── skills/ # 技能系统 ├── state/ # 状态管理 ├── constants/ # 常量定义 ├── outputStyles/ # 输出样式 └── runtime.py # 运行时核心query_engine.py # 查询引擎main.py # CLI入口
runtime.py是整个Agent Harness的心脏,负责:
• Prompt路由:智能匹配用户输入到命令/工具 • Session管理:管理运行时会话状态 • 权限推断:自动推断敏感操作的权限状态
@dataclassclass RuntimeSession: prompt: str context: PortContext setup: WorkspaceSetup history: HistoryLog routed_matches: list[RoutedMatch] turn_result: TurnResult command_execution_messages: tuple[str, ...] tool_execution_messages: tuple[str, ...] stream_events: tuple[dict[str, object], ...]
这是Claude Code最核心的创新之一——智能Prompt路由:
defroute_prompt(prompt: str,limit: int = 5): # Token化处理tokens = {token.lower() for token in prompt.replace('/', ' ').replace('-', ' ').split() if token}# 分类收集匹配by_kind = {'command': self._collect_matches(tokens, PORTED_COMMANDS, 'command'),'tool': self._collect_matches(tokens, PORTED_TOOLS, 'tool'),}
路由算法核心逻辑: 1. 将用户Prompt按空格和特殊字符(/, -)分词 2. 对每个token计算与命令/工具的匹配得分 3. 优先保留command和tool各一个最佳匹配 4. 剩余空间按得分排序填充
query_engine.py负责对话管理和上下文维护:
@dataclassclassQueryEngineConfig: max_turns: int = 8max_budget_tokens: int = 2000compact_after_turns: int = 12structured_output: bool = Falsestructured_retry_limit: int = 2
Query Engine支持流式输出,事件类型包括:
• message_start:消息开始 • command_match:命令匹配 • tool_match:工具匹配 • permission_denial:权限拒绝 • message_delta:消息增量 • message_stop:消息结束
Claude Code的命令系统采用模块化设计,每个命令包含:
命令元数据结构: • name:命令名称 • source_hint:来源提示 • responsibility:职责描述
@dataclass(frozen=True) class RoutedMatch:kind: str# 'command' or 'tool'name: str# 模块名称source_hint: str# 来源提示score: int# 匹配得分
def_infer_permission_denials(matches): denials: list[PermissionDenial] = []for match in matches:if match.kind == 'tool' and 'bash' in match.name.lower():denials.append(PermissionDenial(tool_name=match.name,reason='destructive shell 'execution remains gated'))return denials
上下文(Context)是Agent理解项目的基础:
@dataclass(frozen=True) classPortContext: source_root: Path# 源码根目录tests_root: Path# 测试目录assets_root: Path# 资源目录
• Session ID:唯一会话标识符 • Transcript:对话历史记录 • Usage统计:输入/输出Token统计 • 消息压缩:超过12轮自动压缩
# 基础命令python -m src.main summary # 渲染摘要python -m src.main manifest # 工作区清单python -m src.main subsystems # 列出子系统# 运行时命令python -m src.main route PROMPT # 路由Promptpython -m src.main bootstrap # 引导会话python -m src.main turn-loop # 循环执行# 审计命令python -m src.main parity-audit # 等效性审计python -m src.main setup-report # 启动报告
• remote-mode:远程控制运行时分支 • ssh-mode:SSH远程执行 • teleport-mode:即时远程跳转 • direct-connect-mode:直连模式 • deep-link-mode:深度链接模式
这些是Claude Code的高级特性,允许用户:
直接连接模式:绕过中间层直接与LLM通信深度链接:从外部应用直接唤起Claude Code会话SSH模式:通过SSH在远程机器上运行Agent
• 模块化设计:每个子系统独立、可替换 • Prompt路由:智能匹配用户意图到具体命令/工具 • 权限隔离:敏感操作需要明确授权 • 会话管理:支持持久化和上下文压缩
关键学习点: 1. Harness与Model解耦:Agent逻辑与LLM选择分离 2. 工具注册机制:统一的工具注册和发现系统 3. 安全第一:敏感操作的权限检查是标配 4. 流式响应:支持实时反馈和进度展示
• instructkr/clawd-code:github.com/instructkr/clawd-code
Claude Code的泄露为我们提供了一个难得的窗口,得以窥探顶级AI Lab的Agent工程实践