乐于分享
好东西不私藏

Claude Code源码泄露深度分析:Agent Harness架构全解密

本文最后更新于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(净室重写)是一种法律上安全的逆向工程方法:通过理解原有系统的架构和行为,用完全独立实现的代码重新构建相同功能。 
关键原则: • 不复制任何专有代码 • 只实现相同的功能和行为 • 从零开始编写,保持架构相似但代码独立 
二、源码架构深度解析
2.1 整体目录结构
 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入口 
三、核心模块技术剖析
3.1 Runtime运行时核心
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], ...]
3.2 Prompt路由机制
 这是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. 剩余空间按得分排序填充 
3.3 Query Engine查询引擎
query_engine.py负责对话管理和上下文维护: 
@dataclassclassQueryEngineConfig:     max_turns: int = 8max_budget_tokens: int = 2000compact_after_turns: int = 12structured_output: bool = Falsestructured_retry_limit: int = 2
3.4 流式事件系统
 Query Engine支持流式输出,事件类型包括: 
 • message_start:消息开始 • command_match:命令匹配 • tool_match:工具匹配 • permission_denial:权限拒绝 • message_delta:消息增量 • message_stop:消息结束 
四、命令与工具系统
4.1 命令系统架构
 Claude Code的命令系统采用模块化设计,每个命令包含: 
命令元数据结构: • name:命令名称 • source_hint:来源提示 • responsibility:职责描述 
@dataclass(frozen=Trueclass RoutedMatch:kind: str# 'command' or 'tool'name: str# 模块名称source_hint: str# 来源提示score: int# 匹配得分
4.2 工具权限系统
 Tool权限管理是安全运行的关键: 
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
五、会话与上下文管理
5.1 Context上下文构建
 上下文(Context)是Agent理解项目的基础: 
@dataclass(frozen=TrueclassPortContext:  source_root: Path# 源码根目录tests_root: Path# 测试目录assets_root: Path# 资源目录
5.2 会话持久化
 会话管理支持完整的持久化: 
 • Session ID:唯一会话标识符 • Transcript:对话历史记录 • Usage统计:输入/输出Token统计 • 消息压缩:超过12轮自动压缩 
六、CLI入口与子命令
 Python重写版提供了丰富的CLI子命令: 
# 基础命令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 # 启动报告
七、远程运行时与多模式
7.1 远程运行时模式
 Claude Code支持多种远程执行模式: 
 • remote-mode:远程控制运行时分支 • ssh-mode:SSH远程执行 • teleport-mode:即时远程跳转 • direct-connect-mode:直连模式 • deep-link-mode:深度链接模式 
7.2 Direct Modes直接模式
 这些是Claude Code的高级特性,允许用户: 
直接连接模式:绕过中间层直接与LLM通信深度链接:从外部应用直接唤起Claude Code会话SSH模式:通过SSH在远程机器上运行Agent 
八、架构启示与总结
8.1 Harness架构的核心设计
 • 模块化设计:每个子系统独立、可替换 • Prompt路由:智能匹配用户意图到具体命令/工具 • 权限隔离:敏感操作需要明确授权 • 会话管理:支持持久化和上下文压缩 
8.2 对Agent开发者的启示
关键学习点: 1. Harness与Model解耦:Agent逻辑与LLM选择分离 2. 工具注册机制:统一的工具注册和发现系统 3. 安全第一:敏感操作的权限检查是标配 4. 流式响应:支持实时反馈和进度展示 
🔗 参考资料
 • instructkr/clawd-code:github.com/instructkr/clawd-code
 Claude Code的泄露为我们提供了一个难得的窗口,得以窥探顶级AI Lab的Agent工程实践 
 程序九源