claude-code/BUILD_GUIDE.md

# Claude Code 源码编译指南

> 本文档记录了为 Claude Code 源码快照补充缺失配置文件并成功编译运行的完整过程。

## 概述

Claude Code 的源码快照仅包含 `src/` 目录和 `README.md`，缺少所有构建配置文件。本指南涵盖了从零开始恢复构建环境的全部步骤。

---

## 补充的配置文件

### 1. `package.json`

项目的核心配置文件，定义了：

- **包名**: `@anthropic-ai/claude-code`
- **入口点**: `src/entrypoints/cli.tsx`
- **构建产物**: `dist/cli.js`
- **脚本命令**:
  - `bun run build` — 执行构建脚本
  - `bun run dev` — 直接运行源码（开发模式）
  - `bun run typecheck` — TypeScript 类型检查

**依赖项分为三类：**

| 分类 | 数量 | 示例 |
|------|------|------|
| 公开 npm 包 | ~75 个 | `react`, `chalk`, `zod`, `@anthropic-ai/sdk` |
| Anthropic 内部包（需 stub） | ~10 个 | `@ant/*`, `@anthropic-ai/sandbox-runtime` |
| 开发依赖 | ~13 个 | `typescript`, `@types/react`, `@types/bun` |

### 2. `tsconfig.json`

TypeScript 编译配置，关键设置：

- **模块系统**: ESNext + bundler resolution
- **JSX**: `react-jsx`（React 19 的新 JSX 转换）
- **路径别名**: `src/*` → `./src/*`（项目中大量使用 `import from 'src/...'` 格式的导入）
- **目标**: ESNext（Bun 原生支持）
- **类型**: 同时包含 `bun-types` 和 `node` 类型定义

### 3. `globals.d.ts`

全局类型声明文件，定义了：

- **`MACRO` 常量**：构建时注入的宏定义
  - `MACRO.VERSION` — 版本号
  - `MACRO.BUILD_TIME` — 构建时间戳
  - `MACRO.PACKAGE_URL` — npm 包地址
  - `MACRO.NATIVE_PACKAGE_URL` — 原生包地址
  - `MACRO.FEEDBACK_CHANNEL` — 反馈渠道
  - `MACRO.ISSUES_EXPLAINER` — 问题报告说明
  - `MACRO.VERSION_CHANGELOG` — 版本变更日志

- **`bun:bundle` 模块**：Bun 构建时特性标志（feature flags）模块的类型声明
- **内部包的类型 stub**：为不公开的 Anthropic 内部包提供类型定义

### 4. `scripts/build.ts`

核心构建脚本，使用 Bun 的 `Bun.build()` API，处理以下关键问题：

#### a) `bun:bundle` Feature Flags 处理

原始代码使用 `import { feature } from 'bun:bundle'` 进行编译时死代码消除。构建脚本通过自定义 Bun 插件为 `feature()` 函数提供 polyfill，所有特性标志在外部构建中默认返回 `false`：

```
PROACTIVE, KAIROS, BRIDGE_MODE, DAEMON, VOICE_MODE,
AGENT_TRIGGERS, MONITOR_TOOL, COORDINATOR_MODE,
ABLATION_BASELINE, DUMP_SYSTEM_PROMPT, CHICAGO_MCP
```

#### b) `MACRO.*` 构建时常量注入

通过 `Bun.build()` 的 `define` 选项在编译时替换所有 `MACRO.*` 引用为实际值。

#### c) 内部包 Stub 插件

为不公开的 Anthropic 内部包（`@ant/*`、`@anthropic-ai/sandbox-runtime` 等）提供内联 stub，确保编译时所有命名导出都能正确解析，同时不引入运行时依赖。

#### d) 缺失源文件自动 Stub 插件

源码快照中缺少部分文件（被 `feature()` 特性标志保护或属于内部模块）。构建脚本通过 `missingSourceStubPlugin` 插件**在构建时自动检测并 stub 这些缺失文件**，无需在源码树中手动创建 stub 文件：

- 通过 `onResolve` 钩子拦截所有源文件导入，检测目标文件是否存在于磁盘
- 不存在的文件自动重定向到虚拟 `missing-source` 命名空间
- 对需要特定 named exports 的模块（如 `connectorText`、`protectedNamespace` 等）提供精确 stub
- 其余缺失模块返回通用 `export default {}`
- `.md` 和 `.txt` 文件返回空字符串，`.d.ts` 文件返回 `export {}`
- 构建日志中以 `⚠️ Auto-stubbing missing module:` 标记自动 stub 的模块

#### e) 外部依赖处理

所有公开 npm 包标记为 `external`，不打包进产物，运行时从 `node_modules` 解析。

### 5. 源码修复

`src/main.tsx` 中的 `-d2e` 短标志格式与 Commander.js v13 不兼容（v13 要求短标志为单个字符），已修改为仅使用 `--debug-to-stderr` 长标志。

---

## 编译步骤

### 前提条件

- [Bun](https://bun.sh) ≥ 1.1（推荐 1.3+）
- Windows / macOS / Linux

### 步骤 1：安装依赖

```bash
bun install
```

这将安装约 600+ 个包（含传递依赖），耗时约 1-2 分钟。

### 步骤 2：执行构建

```bash
bun run build
```

构建脚本将：
1. 初始化 `bun:bundle` feature flag polyfill
2. 注入 `MACRO.*` 构建时常量
3. 为内部 Anthropic 包生成内联 stub
4. 自动检测并 stub 源码快照中缺失的源文件
5. 打包 `src/entrypoints/cli.tsx` 入口点
6. 输出到 `dist/cli.js`（约 11.7 MB）和 `dist/cli.js.map`

### 步骤 3：验证运行

```bash
# 检查版本
bun dist/cli.js --version
# 输出: 1.0.0-research (Claude Code)

# 查看帮助
bun dist/cli.js --help

# 启动交互式界面（需要 API Key）
bun dist/cli.js
```

### 自定义版本号

```bash
CLAUDE_CODE_VERSION=2.0.0 bun run build
```

---

## 构建产物

| 文件 | 大小 | 说明 |
|------|------|------|
| `dist/cli.js` | ~11.7 MB | 主程序包（ESM 格式） |
| `dist/cli.js.map` | ~38.6 MB | Source Map |

---

## 技术要点

### 架构概览

```
入口点: src/entrypoints/cli.tsx
    ↓ (动态导入)
主程序: src/main.tsx (Commander.js CLI)
    ↓
终端 UI: src/ink/ (自定义 Ink 实现 + React 19)
    ↓
核心系统:
├── src/tools/      (~40 个工具实现)
├── src/commands/   (~50 个斜杠命令)
├── src/services/   (API、MCP、OAuth、分析)
├── src/hooks/      (权限系统)
└── src/coordinator/ (多智能体协调)
```

### 关键技术栈

| 组件 | 技术 |
|------|------|
| 运行时 | Bun |
| 语言 | TypeScript (strict) |
| 终端 UI | React 19 + 自定义 Ink fork |
| CLI 框架 | Commander.js 13 |
| Schema 验证 | Zod v3 |
| 协议 | MCP SDK, LSP |
| API | Anthropic SDK |
| 遥测 | OpenTelemetry 2.x |
| 布局引擎 | 纯 TypeScript yoga-layout 实现 |

### 注意事项

1. **内部包不可用**：`@ant/*` 系列包和部分 `@anthropic-ai/*` 包不在公共 npm 上发布，相关功能（Chrome 集成、计算机使用、沙箱运行时等）在此构建中不可用。

2. **Feature Flags 全部禁用**：所有 `bun:bundle` 特性标志默认返回 `false`，这意味着实验性功能（语音、守护进程、协调器模式等）的代码路径已被消除。

3. **需要 API Key 才能实际使用**：虽然 CLI 可以编译和启动（完整的终端 UI、主题选择等均正常），但实际使用需要 Anthropic API Key 或 OAuth 登录。

4. **React Reconciler 版本**：项目使用了 `useEffectEvent` Hook，需要 `react-reconciler@0.33.0`（而非 0.31.0），该版本才实现了 `useEffectEvent` 调度器。

5. **内部包 Stub 需完整方法签名**：某些内部包（如 `@anthropic-ai/sandbox-runtime` 的 `SandboxManager`）的 stub 需要包含完整的静态方法（如 `isSupportedPlatform`、`checkDependencies`、`wrapWithSandbox` 等），否则运行时在访问未定义属性时会报错。构建脚本已为所有已知的内部类提供了完整方法签名。

6. **非官方构建**：此构建仅用于教育和安全研究目的，不代表 Anthropic 官方发布。