揭秘 Claude Code：一次深入的逆向工程与开源实现

Anthropic 公司推出的 AI 编程助手 Claude Code 以其强大的代码生成和交互能力，在开发者社区中获得了广泛关注。然而，作为一个闭源产品，其内部工作机制对外界始终是一个“黑盒”，这不仅让开发者难以完全理解其决策逻辑，也限制了在特定技术栈中的深度定制和优化。

本文将详细拆解一次针对 Claude Code 的逆向工程实践。通过拦截并分析其与模型的 API 通信，研究人员成功揭示了其复杂的 Agent 运行机制，并最终将其核心能力迁移至开源 Python 框架 Pywen 中，为社区提供了一个透明且可定制的替代方案。

动机：为何要解构一个闭源 AI 助手？

尽管 Claude Code 功能强大，但其闭源特性带来了几个核心挑战：

• 决策逻辑不透明：开发者无法探知其内部的提示词设计、工具调用策略以及上下文管理机制，导致在出现问题时难以调试和优化。
• 技术栈集成障碍：其原生环境基于 TypeScript，对于广大的 Python 开发者而言，存在一定的集成和使用壁垒。
• 定制化能力受限：无法根据特定的业务需求或个人偏好来调整其行为模式和响应风格。
• 成本控制未知：由于无法干预其 API 调用策略，用户难以通过优化模型选择或上下文长度来有效控制使用成本。

因此，本次逆向工程的目标非常明确：完整解构 Claude Code 的工作原理，提取其核心提示词和工具定义，并将其能力原生化地复刻到 Pywen 框架中。

逆向工程：通过“猴子补丁”揭开黑盒

由于无法直接访问 Claude Code 的源代码，逆向工程选择了一个巧妙的切入点：拦截其与 Claude 模型之间的所有 API 通信。其所有智能行为，无论是代码生成还是工具调用，都必须通过 API 请求来完成。

核心技术采用了“猴子补丁”（Monkey Patching），这是一种在程序运行时动态修改或替换代码的技术。通过 claude-code-reverse 项目提供的方案，研究人员得以在 Claude Code 的网络请求模块注入自定义逻辑，从而捕获每一次 API 调用的完整请求和响应数据。

运行经过修改的 Claude Code 并进行交互，会生成详细的 API 通信日志。通过分析这些日志，一个原本不透明的“思维过程”被完整地还原了出来。

逆向发现：Claude Code 的八大核心机制

通过对海量 API 日志的深入分析，Claude Code 的完整工作流程被逐步解密，其核心机制主要包含以下八个部分：

1. 配额检查 (Quota Query)

程序每次启动时，会首先向 Claude 模型发送一次轻量级的对话请求，以验证用户的 API 配额是否充足。

• 输入: "quota"
• 模型: Haiku 3.5
• 目的: 选用 Haiku 模型可以在保证功能的同时，实现快速、低成本的 API 配额验证。

2. 主题检测 (Topic Detection)

在接收到用户的每一次输入后，系统会使用一个名为 check-new-topic 的特定提示词来判断当前输入是否开启了一个新的话题。值得注意的是，此检测不包含历史对话上下文，其主要目的是为了更新终端界面的会话标题。

例如，在同一个会话中，当讨论内容切换时，模型会返回如下 JSON 对象：

{ "isNewTopic": true, "title": "Python文件创建" }

3. 核心 Agent 流程

这是 Claude Code 的主要工作循环，由一个主 Agent 驱动。该流程使用了能力更强的 Sonnet 4 模型，并由五个核心提示词组件构成，共同构建了模型的系统级指令（System Prompt）。

• system-identity.prompt.md: 定义 Agent 的身份和角色。
• system-workflow.prompt.md: 描述核心工作流程、行为准则和响应风格。
• system-reminder-start.prompt.md: 注入动态生成的环境信息，如当前工作目录、IDE 状态等。
• 用户实际输入: 用户的原始请求。
• system-reminder-end.prompt.md: 注入任务状态，如当前的 Todo 列表。

4. 上下文压缩 (Compact)

当对话历史的 Token 数量接近模型上下文窗口上限时，Claude Code 会自动或在用户手动触发下启动上下文压缩机制。

• 模型: Sonnet 4
• 机制: 使用一个专门的压缩提示词，将整个对话历史提炼成一份摘要。
• 目的: 这份摘要将作为下一次对话的初始上下文，从而在保留关键信息的同时，为新的对话内容释放空间。

5. IDE 集成

Claude Code 通过 MCP（一种通信协议）与 IDE（如 VS Code）紧密集成，能够读取当前打开的文件信息，并注册专用的工具来与 IDE 交互，例如：

• getDiagnostics: 获取代码中的诊断信息，如错误和警告。
• executeCode: 在 IDE 环境中执行代码片段。
• 此外，它还能利用这些工具自动修复 linting 错误。

6. Todo 短时记忆管理

Claude Code 实现了一套基于本地文件系统的短时记忆系统，用于管理任务列表。

• 存储: 任务状态以 JSON 格式存储在 ~/.claude/todos/ 目录下。
• 结构:

  {
  "todos": [
  {
  "content": "Run tests",
  "status": "in_progress",
  "activeForm": "Running tests"
  }
  ]
  }
  

• 机制: 系统会实时加载和更新这个 JSON 文件，确保 Agent 在多次交互之间能够记住并延续当前的任务。

7. Sub Agent 系统

为了处理复杂任务并避免主 Agent 的上下文被污染，Claude Code 引入了 Sub Agent（子代理）机制，通过一个 Task 工具实现多 Agent 协作。

• 流程: Main Agent（主代理）可以将一个复杂的子任务分派出去。
• 隔离: Sub Agent 在一个完全隔离的上下文中执行该任务。
• 返回: 任务完成后，Sub Agent 将最终结果返回给 Main Agent，这种机制有效避免了中间步骤的冗余信息干扰主对话流程，即所谓的“脏上下文”问题。

8. 对话历史总结

在会话结束时，系统会使用轻量级的 Haiku 3.5 模型为本次对话生成一个简洁的标题，方便用户进行历史会话的管理和回顾。

测试用例：一个完整交互流程的拆解

以下是一个“创建并修改文件”的简单任务，通过它我们可以清晰地看到上述机制是如何协同工作的。

用户输入 1: > 当前目录创建test_py文件夹，写一个hello world Python文件

1. Quota 查询: （启动时已完成）
2. Topic 检测:
   
   • System Prompt:

     Analyze if this message indicates a new conversation topic. If it does, extract a 2-3 word title that captures the new topic. Format your response as a JSON object with two fields: 'isNewTopic' (boolean) and 'title' (string, or null if isNewTopic is false). Only include these fields, no other text.
     

   • 模型输出:

     { "isNewTopic": true, "title": "Python文件创建" }
     

3. 核心 Agent 决策与工具调用 (Reminder & Tool Call):
   
   • System Prompt: 拼接 System-Identity、System-Workflow 等多个提示词组件。
   • Message: 注入动态提醒，例如用户在 IDE 中选中的代码。

     <system-reminder> The user selected the lines 16 to 16 from /home/capios/.nvm/versions/node/v18.20.8/lib/node_modules/@anthropic-ai/claude-code/cli.js: USERPROFILE
     This may or may not be related to the current task. </system-reminder>
     

   • Tools: 传入所有可用工具的详细描述。
   • 模型输出 (Assistant): 首先输出思考过程 "I'll create a test_py folder and write a hello world Python file in it."，然后调用 Bash 工具。

     {
     "command": "mkdir test_py",
     "description": "Create test_py directory"
     }
     

     注：Bash 工具的描述文档非常详尽，包含了安全提示、git 操作规范、PR 创建流程等超过400行的内容，这里不作全文展示。

4. Bash 工具执行策略:
   
   • 在执行具体的 bash 命令前，Claude Code 会调用另一个模型来分析命令的安全性，提取命令前缀，防止命令注入攻击。
   • System Prompt:

     Your task is to process Bash commands that an AI coding agent wants to run. This policy spec defines how to determine the prefix of a Bash command...
     

   • Message:

     ... Command: mkdir test_py
     

   • 模型输出:

     mkdir
     

5. Bash 工具执行后处理:
   
   • 执行完毕后，系统会再次调用模型判断该命令是否显示了文件内容，以决定是否在 CLI 界面上展示输出。mkdir 命令不显示文件内容，因此模型返回 false。
6. 调用 Write 工具:
   
   • 在创建目录后，Agent 继续执行任务的下一步，调用 Write 工具创建文件。
   • 模型输出 (Tool Call):

     {
     "name": "Write",
     "input": {
     "file_path": "/home/capios/test_py/hello_world.py",
     "content": "print(\"Hello, World!\")"
     }
     }
     

7. Write 工具执行结束:
   
   • 模型输出 (Assistant):

     Done! Created test_py/hello_world.py with a simple Hello World program.
     

用户输入 2: > 修改为hello Hangzhou

8. 新 Topic 检测:
   
   • 同样的过程，模型判断这是一个新主题。
   • 模型输出:

     { "isNewTopic": true, "title": "Hangzhou Greeting" }
     

9. 调用 Edit 工具:
   
   • Agent 理解用户意图是修改文件，因此选择调用 Edit 工具。
   • 模型输出 (Tool Call):

     {
     "name": "Edit",
     "input": {
     "file_path": "/home/capios/test_py/hello_world.py",
     "old_string": "print(\"Hello, World!\")",
     "new_string": "print(\"Hello, Hangzhou!\")"
     }
     }
     

10. Edit 工具执行完毕:
    
    • 模型输出 (Assistant):

      Modified to "Hello, Hangzhou!"
      

迁移到 Pywen：从 TypeScript 到 Python 的开源移植

在完整理解 Claude Code 的核心机制之后，下一步便是将其系统地迁移到 Pywen 框架中。这一过程不仅是代码的翻译，更是设计思想的复现。

核心迁移策略

通过逆向工程提取的所有核心组件，被逐一在 Pywen 框架内进行了模块化实现：

1. 提示词体系完整迁移:
   • 位置: pywen/agents/claudecode/prompts.py
   • 实现: 所有从日志中提取的提示词，包括身份定义、工作流程、动态提醒、主题检测和上下文压缩策略，都被整合到了 prompts.py 文件中。这些提示词包含了大量细节指令，是 Claude Code 行为模式的基石。
2. 工具定义精确复刻:
   • 位置: pywen/agents/claudecode/tools/tool_adapter.py
   • 实现: 利用设计模式中的适配器模式（Adapter Pattern），为 Pywen 的原生工具动态替换上 Claude Code 版本的描述。这意味着底层的工具功能保持不变，但提供给大语言模型的工具描述（即 LLM 看到的 Tool Schema）与 Claude Code 完全一致，从而精确复刻其工具调用行为。
3. 系统提醒机制重现:
   • 位置: pywen/agents/claudecode/system_reminder.py
   • 实现: Claude Code 的系统提醒是基于上下文状态智能注入的。Pywen 中通过一个 SystemReminder 模块来复现这一机制，例如在 Todo 列表为空时提醒任务管理，或在多文件编辑后建议运行测试。
4. Todo 短时记忆管理:
   • 位置: pywen/agents/claudecode/tools/todo_tool.py
   • 实现: 基于文件系统的任务状态持久化被封装成一个 TodoTool，实现了任务的增、删、改、查，并通过三种状态（pending/in_progress/completed）进行管理。

Pywen 框架的架构优势

Pywen 灵活且完备的架构设计，使得这次复杂的迁移过程变得高效而顺畅：

• 基础设施完备: 框架提供了 BaseAgent 基类、工具注册系统、会话管理、轨迹记录等核心组件，开发者无需从零构建。
• 灵活的 Agent 体系: 支持多种 Agent 并存，用户可以通过 /agent 命令在不同 Agent（如 claude 模式和默认模式）之间随时切换，各 Agent 拥有独立的配置，互不干扰。
• 丰富的生态系统: 框架内置了文件操作、代码编辑、Web 搜索等多种基础工具，可以按需组合使用，为复刻 Claude Code 的复杂工具集提供了基础。

成果：Pywen 中的 Claude Code

迁移完成后，用户现在可以在 Pywen 框架中无缝地体验到与原生 Claude Code 高度一致的强大能力。

• GitHub 链接: https://github.com/PAMPAS-Lab/Pywen

# 启动 Pywen
$ pywen
# 切换到 Claude Code Agent 模式
> /agent claude
# 现在可以开始使用完整的 Claude Code 能力
> Help me refactor this code and add tests
# Todo 工具将自动激活并进行任务管理
Creating todo list:
1. Analyzing code structure
2. Refactoring implementation
3. Adding test cases

这次成功的逆向工程与开源实现，不仅揭示了一个顶尖闭源 AI 产品的内部设计，更重要的是，它将这些先进的 Agent 架构思想带给了开源社区，推动了技术的透明化与共同进步。

本文所有分析均基于公开可获取的 API 日志，旨在技术学习与交流。