# Claude Code 源码逆向分析文档

> 基于 `D:\cd\claude-code` 项目逆向梳理，源码来源为 2026-03-31 泄露版本，经社区修复后在 Windows + Bun 环境下可构建运行。

---

## 1. 项目概述

**Claude Code** 是 Anthropic 推出的一款命令行 AI 编程助手（CLI Agent）。本项目是该工具的源码研究构建版本，可在本地 Windows 环境下使用 Bun 运行时编译运行。

### 1.1 核心能力

- **终端内 AI 对话**：基于 Ink/React 的 TUI 界面，支持 Markdown 渲染、语法高亮、Diff 展示
- **多模型支持**：通过 `@anthropic-ai/sdk` 调用 Claude API，通过 cc-switch 可切换到 OpenAI/DeepSeek 等
- **工具调用系统**：内置 50+ 自动化工具（文件读写、Shell 执行、Web 搜索、Git 操作等）
- **Agent 子进程**：支持启动子 Agent 并行处理任务
- **MCP 协议**：完整的 Model Context Protocol 客户端/服务端实现
- **会话管理**：持久化会话存储、恢复、导出
- **远程控制**：Bridge 模式支持远程会话连接
- **Hook 系统**：事件钩子（PreToolUse、PostToolUse 等）可扩展
- **插件系统**：支持加载外部插件
- **内存系统**：持久化用户偏好和项目知识（MEMORY.md）

### 1.2 技术栈

| 层 | 技术选型 |
|---|---|
| 运行时 | **Bun** (JavaScript/TypeScript 运行时) |
| UI 框架 | **React 19** + **Ink 6** (终端 React 渲染器) |
| AI SDK | `@anthropic-ai/sdk` + `@anthropic-ai/claude-agent-sdk` |
| 类型系统 | TypeScript 5.8, Zod 4.x |
| 构建工具 | Bun build (bun build --target=bun) |
| 协议 | MCP (Model Context Protocol), WebSocket, SSE |

### 1.3 目录结构概览

```
claude-code/
├── src/
│   ├── entrypoints/         # 入口：cli.tsx, mcp.ts, sdk 等
│   ├── screens/             # 主界面：REPL.tsx (900KB), Doctor, Resume
│   ├── components/          # React/Ink UI 组件 (120+ 文件)
│   ├── tools/               # 50+ AI 可调用工具
│   ├── commands/            # 60+ 斜杠命令
│   ├── tasks/               # 任务类型：Agent/Shell/Workflow/Dream
│   ├── bridge/              # 远程桥接 (会话同步/远程控制)
│   ├── ink/                 # Ink 终端渲染层增强
│   ├── utils/               # 240+ 工具函数文件
│   ├── services/            # API/MCP/OAuth/语音等服务
│   ├── hooks/               # React Hooks (80+)
│   ├── state/               # 全局状态管理 (AppState)
│   ├── context/             # React Context (通知/模态框/语音)
│   ├── keybindings/         # 键盘快捷键系统
│   ├── vim/                 # Vim 模式（文本对象/操作/运动）
│   ├── memdir/              # 内存系统（持久化记忆）
│   ├── skills/              # 技能系统
│   ├── plugins/             # 插件加载
│   ├── constants/           # 常量（Prompts 55KB, 工具定义等）
│   ├── types/               # 类型定义
│   └── stubs/               # 缺失原生模块的桩实现
├── scripts/                 # 构建/部署脚本
├── package.json
└── tsconfig.json
```

---

## 2. 快速开始

### 2.1 环境要求

- Windows 10+ / macOS / Linux
- **Bun** >= 1.x (`powershell -c "irm bun.sh/install.ps1 | iex"`)
- Anthropic API Key（或通过 cc-switch 使用其他 API）

### 2.2 构建与运行

```powershell
# 安装依赖
bun install

# 构建
bun run build

# 启动开发版
bun run dev
```

### 2.3 运行模式

| 命令 | 说明 |
|---|---|
| `bun run dev` | 启动交互式 REPL |
| `bun dist/main.js` | 运行构建版本 |
| `claude --version` | 输出版本信息 |
| `claude -p "prompt"` | 单次问答（非交互） |
| `claude --mcp-server` | 启动 MCP 服务端 |
| `claude remote-control` | 远程控制模式 |

---

## 3. 文档索引

- [架构分析](./architecture.md) — 系统分层架构、组件树、核心模块
- [模块详解](./modules.md) — 每个源码目录/文件的职责分析
- [工具系统](./tools.md) — 50+ AI 工具的完整清单与机制
- [数据流与生命周期](./dataflow.md) — 启动流程、对话循环、任务调度

---

## 4. 核心修复说明

本项目基于泄露版本做了以下关键修复以支持 Windows 构建运行：

1. **MACRO 注入** (`src/entrypoints/cli.tsx`)：补全全局宏定义（版本号、构建时间等）
2. **ColorDiff Stub** (`src/stubs/ant-packages/color-diff-napi/`)：补全 `render` 方法
3. **isBeingDebugged 修复** (`src/main.tsx`)：修正 Bun 环境下的调试检测逻辑
4. **bun:bundle polyfill** (`src/stubs/bun-bundle-runtime.ts`)：运行时替代编译时模块
5. **postinstall 跨平台** (`scripts/postinstall.ts`)：不再依赖 Bash

---

*本文档基于 2026-06-11 源码状态生成*