Skip to content

Commit 04312fd

Browse files
JL-RogerJL-Roger
committed
docs: add comprehensive build and run guide (BUILD.md)
1 parent 9cef6af commit 04312fd

1 file changed

Lines changed: 345 additions & 0 deletions

File tree

‎BUILD.md‎

Lines changed: 345 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,345 @@
1+
# Claude Code 编译与运行指南
2+
3+
> 基于 2026-03-31 泄露的 Claude Code CLI 源码
4+
> 最后更新：2026-04-01
5+
6+
---
7+
8+
## 1. 前置条件
9+
10+
### 1.1 必须安装
11+
12+
| 工具 | 版本 | 安装命令 |
13+
|------|------|----------|
14+
| **Bun** | 1.3+ | `curl -fsSL https://bun.sh/install \| bash` |
15+
| **Node.js** | 18+ | 已有则跳过（Bun 自带 npm） |
16+
17+
### 1.2 验证安装
18+
19+
```bash
20+
bun --version # 应输出 1.x.x
21+
node --version # 应输出 v18+ 或 v22+
22+
```
23+
24+
### 1.3 工作目录
25+
26+
所有命令在以下目录执行：
27+
28+
```bash
29+
cd ~/.openclaw/workspace/claude-code
30+
```
31+
32+
---
33+
34+
## 2. 项目结构概览
35+
36+
```
37+
claude-code/
38+
├── src/ # 源码（1,886 个 TypeScript 文件）
39+
│ ├── main.tsx # CLI 入口（4,683 行）
40+
│ ├── QueryEngine.ts # LLM 查询引擎（1,295 行）
41+
│ ├── Tool.ts # 工具接口定义（792 行）
42+
│ ├── commands.ts # 命令注册（754 行）
43+
│ ├── tools.ts # 工具注册（389 行）
44+
│ ├── screens/ # 全屏 UI（REPL.tsx 5,005 行）
45+
│ ├── components/ # React 组件（346 个）
46+
│ ├── tools/ # 工具实现（42 个目录）
47+
│ ├── services/ # 服务层（21 个子目录）
48+
│ ├── commands/ # 斜杠命令（80+ 个）
49+
│ ├── utils/ # 工具函数（290+ 文件, 88K 行）
50+
│ ├── hooks/ # React hooks（104 个）
51+
│ ├── bridge/ # IDE 桥接（31 文件）
52+
│ └── ink/ # 自定义 Ink 渲染器（96 文件）
53+
├── shims/ # 编译 shim
54+
│ ├── bun-bundle.ts # bun:bundle feature() 替代
55+
│ └── macro.ts # MACRO 全局变量注入
56+
├── dist/ # 编译输出
57+
├── ARCHITECTURE*.md # 架构文档（7 份）
58+
└── package.json # 依赖声明
59+
```
60+
61+
---
62+
63+
## 3. 缺失文件与修复
64+
65+
泄露的源码不完整。以下是编译前必须补充的内容：
66+
67+
### 3.1 缺失的源文件（22 个 stub）
68+
69+
这些文件在 `src/` 下，是内部工具引用但泄露包中不存在的：
70+
71+
| 文件 | 用途 |
72+
|------|------|
73+
| `src/global.d.ts` | TypeScript 全局类型声明 |
74+
| `src/utils/protectedNamespace.ts` | 命名空间保护检查 |
75+
| `src/utils/useEffectEvent.ts` | React useEffectEvent shim |
76+
| `src/entrypoints/sdk/coreTypes.generated.ts` | SDK 生成类型 |
77+
| `src/entrypoints/sdk/runtimeTypes.ts` | SDK 运行时类型 |
78+
| `src/entrypoints/sdk/toolTypes.ts` | SDK 工具类型 |
79+
| `src/tools/REPLTool/REPLTool.ts` | REPL 工具 stub |
80+
| `src/tools/SuggestBackgroundPRTool/` | PR 建议工具 stub |
81+
| `src/tools/VerifyPlanExecutionTool/` | 计划验证工具 stub |
82+
| `src/tools/WorkflowTool/` | 工作流工具 stub |
83+
| `src/tools/TungstenTool/TungstenLiveMonitor.tsx` | Tungsten 监控 stub |
84+
| `src/commands/agents-platform/` | Agent 平台命令 stub |
85+
| `src/commands/assistant/` | 助手命令 stub |
86+
| `src/components/agents/SnapshotUpdateDialog.tsx` | 快照对话框 stub |
87+
| `src/assistant/AssistantSessionChooser.tsx` | 会话选择器 stub |
88+
| `src/services/compact/snipCompact.ts` | 剪裁压缩 stub |
89+
| `src/services/compact/cachedMicrocompact.ts` | 微压缩 stub |
90+
| `src/services/contextCollapse/` | 上下文折叠 stub |
91+
| `src/ink/devtools.ts` | 开发工具 stub |
92+
| `src/skills/bundled/verify/` | 验证 skill stub |
93+
| `src/utils/filePersistence/types.ts` | 文件持久化类型 stub |
94+
95+
这些 stub 已经在仓库中，编译时会自动包含。
96+
97+
### 3.2 缺失的 npm 包
98+
99+
泄露的 `package.json` 缺少 28 个依赖。运行以下命令安装：
100+
101+
```bash
102+
bun install
103+
```
104+
105+
这会安装 `package.json` 中声明的所有依赖（已补充完整）。
106+
107+
### 3.3 内部 Anthropic 包（stub）
108+
109+
以下两个包是 Anthropic 内部包，无法从 npm 安装：
110+
111+
- `@ant/claude-for-chrome-mcp` — Chrome 集成 MCP
112+
- `@anthropic-ai/sandbox-runtime` — 沙箱运行时
113+
114+
它们在 `node_modules/` 中以 stub 形式存在（已创建）。
115+
116+
---
117+
118+
## 4. 需要修改的源码
119+
120+
### 4.1 Commander.js 短标志
121+
122+
原代码使用 `-d2e` 这种多字符短标志，Commander.js 不支持。
123+
124+
**修改文件**：`node_modules/commander/lib/option.js`
125+
126+
```javascript
127+
// 原代码
128+
const shortFlagExp = /^-[^-]$/;
129+
130+
// 修改为（允许任意长度短标志）
131+
const shortFlagExp = /^-[^-]+$/;
132+
```
133+
134+
> ⚠️ 修改的是 `node_modules/` 中的文件。每次 `bun install` 后需要重新修改。建议创建 postinstall 脚本自动 patch。
135+
136+
### 4.2 MACRO 全局变量
137+
138+
原代码使用 `MACRO.VERSION` 等全局变量，Bun 编译时会自动注入。开源版本没有这个机制。
139+
140+
**创建文件**：`shims/macro.ts`
141+
142+
```typescript
143+
globalThis.MACRO = {
144+
VERSION: "1.0.0",
145+
BUILD_TIME: undefined,
146+
ISSUES_EXPLAINER: "https://github.com/anthropics/claude-code/issues",
147+
FEEDBACK_CHANNEL: "#claude-code-feedback",
148+
NATIVE_PACKAGE_URL: "https://claude.ai/download",
149+
PACKAGE_URL: "https://www.npmjs.com/package/@anthropic-ai/claude-code",
150+
VERSION_CHANGELOG: "https://github.com/anthropics/claude-code/releases",
151+
};
152+
```
153+
154+
编译时作为额外入口点注入。
155+
156+
### 4.3 bun:bundle feature()
157+
158+
原代码使用 `import { feature } from 'bun:bundle'` 实现编译时死码消除。开源 Bun 没有这个功能。
159+
160+
**创建文件**：`shims/bun-bundle.ts`
161+
162+
```typescript
163+
export function feature(name: string): boolean {
164+
const flags: Record<string, boolean> = {
165+
WORKFLOW_SCRIPTS: false,
166+
AGENT_TRIGGERS: false,
167+
// ... 其他 flag 默认 false
168+
};
169+
return flags[name] ?? false;
170+
}
171+
```
172+
173+
Bun 的 `bunfig.toml` 配置了 `.js` → `.ts` 的 loader 映射，会自动解析这个 shim。
174+
175+
### 4.4 useEffectEvent 兼容
176+
177+
代码使用了 React 19 实验性 Hook `useEffectEvent`，但 `react-reconciler@0.31` 不支持。
178+
179+
**创建文件**：`src/utils/useEffectEvent.ts`
180+
181+
```typescript
182+
import { useCallback, useRef } from 'react';
183+
184+
export function useEffectEvent<T extends (...args: any[]) => any>(callback: T): T {
185+
const ref = useRef(callback);
186+
ref.current = callback;
187+
return useCallback(((...args: any[]) => ref.current(...args)) as T, []);
188+
}
189+
```
190+
191+
**修改**：`src/components/tasks/BackgroundTasksDialog.tsx` 和 `src/state/AppState.tsx` 中将 `import { ... useEffectEvent ... } from 'react'` 改为从 `../../utils/useEffectEvent.js` 导入。
192+
193+
### 4.5 版本检查跳过
194+
195+
原代码调用 `assertMinVersion()` 检查远程最低版本配置，会访问 Anthropic 服务器。
196+
197+
**修改文件**：`src/utils/autoUpdater.ts`
198+
199+
```typescript
200+
export async function assertMinVersion(): Promise<void> {
201+
return; // 直接返回，跳过检查
202+
// ... 原有代码
203+
}
204+
```
205+
206+
### 4.6 组织验证跳过
207+
208+
原代码调用 `validateForceLoginOrg()` 检查组织限制。
209+
210+
**修改文件**：`src/main.tsx`
211+
212+
注释掉两处 `validateForceLoginOrg` 调用（约第 2302 行和第 2614 行）：
213+
214+
```typescript
215+
// const orgValidation = await validateForceLoginOrg();
216+
// if (!orgValidation.valid) {
217+
// process.exit(1);
218+
// }
219+
```
220+
221+
---
222+
223+
## 5. 编译步骤
224+
225+
### 5.1 完整编译命令
226+
227+
```bash
228+
cd ~/.openclaw/workspace/claude-code
229+
230+
# 1. 安装依赖
231+
bun install
232+
233+
# 2. 编译 TypeScript → JavaScript bundle
234+
bun build shims/macro.ts src/main.tsx --target=bun --outdir=./dist
235+
236+
# 3. 合并为单文件（macro shim + main bundle + auto-execute）
237+
cat dist/shims/macro.js dist/src/main.js > dist/bundle.js
238+
echo 'if (typeof main === "function") main().catch(e => { console.error(e); process.exit(1); });' >> dist/bundle.js
239+
```
240+
241+
### 5.2 编译结果
242+
243+
```
244+
Bundled 5745 modules in ~300ms
245+
dist/bundle.js ~23 MB (单文件可执行)
246+
```
247+
248+
- **模块数**：5,745（含源码 + 依赖）
249+
- **文件大小**：~23 MB
250+
- **编译时间**：~300ms
251+
- **输出**：`dist/bundle.js`（单文件）
252+
253+
### 5.3 一键编译脚本
254+
255+
```bash
256+
#!/bin/bash
257+
set -e
258+
cd ~/.openclaw/workspace/claude-code
259+
260+
echo "Building..."
261+
bun build shims/macro.ts src/main.tsx --target=bun --outdir=./dist 2>&1
262+
263+
echo "Bundling..."
264+
cat dist/shims/macro.js dist/src/main.js > dist/bundle.js
265+
echo 'if (typeof main === "function") main().catch(e => { console.error(e); process.exit(1); });' >> dist/bundle.js
266+
267+
echo "Done: $(ls -lh dist/bundle.js | awk '{print $5}')"
268+
```
269+
270+
---
271+
272+
## 6. 运行
273+
274+
### 6.1 基本用法
275+
276+
```bash
277+
# 查看帮助（不需要 API key）
278+
bun dist/bundle.js --help
279+
280+
# 查看 MCP 子命令帮助
281+
bun dist/bundle.js mcp --help
282+
283+
# 查看版本
284+
bun dist/bundle.js --version
285+
```
286+
287+
### 6.2 交互模式（需要真实终端）
288+
289+
```bash
290+
# 进入 REPL 交互界面
291+
bun dist/bundle.js
292+
```
293+
294+
会显示：
295+
1. **信任对话框** — 确认信任当前目录
296+
2. **欢迎界面** — Logo + 版本信息
297+
3. **REPL 输入框** — 等待输入
298+
299+
### 6.3 非交互模式（-p）
300+
301+
```bash
302+
# 需要 API key
303+
export ANTHROPIC_API_KEY=你的密钥
304+
bun dist/bundle.js -p "say hello"
305+
```
306+
307+
### 6.4 配置管理
308+
309+
```bash
310+
# 添加 MCP 服务器
311+
bun dist/bundle.js mcp add myserver http://localhost:3000
312+
313+
# 查看配置
314+
bun dist/bundle.js config
315+
316+
# 查看已添加的 MCP 服务器
317+
bun dist/bundle.js mcp list
318+
```
319+
320+
---
321+
322+
## 7. 架构文档
323+
324+
项目包含 7 份架构分析文档：
325+
326+
| 文档 | 大小 | 内容 |
327+
|------|------|------|
328+
| `ARCHITECTURE.md` | 20KB | 全景架构总览 |
329+
| `ARCHITECTURE-TOOLS.md` | 24KB | 43 个工具详细分析 |
330+
| `ARCHITECTURE-SERVICES.md` | 28KB | 21 个服务详细分析 |
331+
| `ARCHITECTURE-COMPONENTS.md` | 28KB | 389 个组件分析 |
332+
| `ARCHITECTURE-COMMANDS.md` | 24KB | 60+ 命令/Skill/Plugin |
333+
| `ARCHITECTURE-UTILS.md` | 12KB | 290+ 工具文件 |
334+
| `ARCHITECTURE-BRIDGE-REMOTE.md` | 12KB | Bridge/Remote/Coordinator |
335+
| `REFACTORING-ASSESSMENT.md` | 12KB | 重构可行性评估 |
336+
337+
---
338+
339+
## 8. 已知问题
340+
341+
1. **TUI 需要真实终端** — SSH 管道或非 TTY 环境下会静默退出
342+
2. **API 调用需要密钥** — 没有 `ANTHROPIC_API_KEY` 时发送消息会失败
343+
3. **部分功能为 stub** — REPLTool、WorkflowTool 等是空实现
344+
4. **macOS Keychain** — 安全存储在 Linux 上回退到明文文件
345+
5. **Windows 支持** — PowerShell 工具需要 Windows 环境测试

0 commit comments

Comments
 (0)