Skip to content

wzf1997/claude-code-source

BranchesTags

Repository files navigation

Claude Code 源码开发文档

@anthropic-ai/claude-code v2.1.88 — 通过 sourceMap 还原的 TypeScript 源码，搭建可直接运行的开发环境。

目录

项目结构

package/
├── cli.js                    # 官方编译产物（13MB，可直接 node cli.js 运行）
├── cli.js.map                # sourceMap（60MB，源码还原的来源）
├── package.json              # 官方包信息
├── start.sh                  # 便捷启动脚本（运行 cli.js）
├── vendor/
│   ├── ripgrep/              # ripgrep 二进制（供 Grep 工具使用）
│   └── audio-capture/        # 原生音频捕获模块
└── source/                   # ← 开发环境根目录
    ├── package.json          # 开发环境依赖声明
    ├── bunfig.toml           # Bun 运行时配置（alias、registry）
    ├── tsconfig.json         # TypeScript 配置
    ├── .npmrc                # 强制使用公开 npm registry
    ├── bun-bundle-shim.ts    # feature flag 运行时模拟
    ├── macros-preload.ts     # 构建时宏常量注入
    ├── dev-patch.ts          # 生成 src-dev/ 的预处理脚本
    ├── src/                  # 原始还原的 TypeScript 源码（+ 手动 stub）
    └── src-dev/              # 预处理后可运行的副本（由 dev-patch.ts 生成）

环境要求

工具 版本要求 说明
Bun ≥ 1.2.0 运行时 + 包管理器
macOS 推荐 部分原生模块仅支持 macOS

安装 Bun：

curl -fsSL https://bun.sh/install | bash

快速上手

# 进入开发环境目录
cd /path/to/package/source

# 安装依赖（首次或 package.json 变更后）
bun install

# 生成可运行副本（首次必须，修改 src/ 后需重新运行）
bun run dev-patch.ts

# 验证环境
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx --version
# 预期输出：2.1.88 (Claude Code)

# 查看帮助
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx --help

# 启动交互式会话（需要配置 ANTHROPIC_API_KEY）
export ANTHROPIC_API_KEY=sk-ant-...
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx

开发工作流

修改源码

修改 src/ 中的 .ts/.tsx 文件
          ↓
bun run dev-patch.ts   ← 重新生成 src-dev/
          ↓
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx [参数]

注意： src-dev/ 由 dev-patch.ts 完整重建，不要直接修改 src-dev/ 中的文件。

添加新的 npm 依赖

# 不要用 bun add！会触发父包的 prepare 脚本报错
# 正确做法：手动编辑 package.json，然后 bun install
vim package.json   # 在 dependencies 中添加
bun install

调试

# 开启调试模式
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx --debug

# 按类别过滤调试信息
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx --debug "api,hooks"

# 写入调试日志文件
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx --debug-file /tmp/claude-debug.log

非交互模式（测试用）

# 发送单条消息后退出
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx \
  -p "列出当前目录的文件"

# JSON 格式输出
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx \
  -p --output-format json "当前时间是几点"

核心文件说明

dev-patch.ts — 预处理脚本

将 src/ 复制到 src-dev/，并进行以下转换：

转换 原因
from 'bun:bundle' → 绝对路径到 bun-bundle-shim.ts bun:bundle 是编译时虚拟模块，运行时不存在
from 'src/xxx' → 相对路径 ./xxx Bun alias 不能重定向目录名，需手动转换
import xx from '*.md' → const xx = '' Bun text loader 仅在构建时可用
import xx from '*.txt' → const xx = '' 同上
import '*.d.ts' → 删除 类型声明文件无需运行时加载
'-d2e, --debug-to-stderr' → '--debug-to-stderr' Commander v13 不支持多字符短选项

bun-bundle-shim.ts — Feature Flag 模拟

原始构建使用 feature('FLAG') 在编译期做死代码消除（DCE）。此文件模拟运行时行为：

import { feature } from "./bun-bundle-shim.ts";

if (feature("ULTRATHINK")) {
  // 此代码块在 ENABLED_FLAGS 包含 'ULTRATHINK' 时执行
}

修改 ENABLED_FLAGS 来启用/禁用特定功能模块。

当前已禁用的 flag（实现文件缺失）：

  • WEB_BROWSER_TOOL — WebBrowserTool 实现未包含在 sourceMap
  • MONITOR_TOOL — MonitorTool 实现未包含在 sourceMap
  • WORKFLOW_SCRIPTS — WorkflowTool 实现未包含在 sourceMap
  • PROACTIVE — SleepTool/SuggestBackgroundPRTool 等依赖缺失

macros-preload.ts — 宏常量注入

原始构建通过 bun build --define 将以下常量内联到代码中，运行时需手动注入：

globalThis.MACRO = {
  VERSION: "2.1.88",
  BUILD_TIME: "...",
  VERSION_CHANGELOG: "",
  ISSUES_EXPLAINER: "...",
  // ...
};

通过 bun --preload ./macros-preload.ts 在入口文件执行前注入。

架构概览

执行流程

entrypoints/cli.tsx          # CLI 入口，处理 --version/--daemon 等快速路径
    ↓
main.tsx                     # 主初始化：auth、settings、MCP、插件加载
    ↓
query.ts: query()            # 核心循环（AsyncGenerator）
    ├─ normalizeMessagesForAPI()
    ├─ context.ts            # 注入系统提示（gitStatus、CLAUDE.md 等）
    ├─ Claude Streaming API  # 调用 Anthropic API
    ├─ 检测 stop_reason === 'tool_use'
    ├─ runTools()            # 并行或串行执行工具
    └─ 追加 tool_result，继续循环

关键模块

文件/目录 职责
src/query.ts 核心 AI↔Tool 交互循环（~1700 行）
src/QueryEngine.ts 查询引擎封装
src/Tool.ts Tool 接口定义（所有工具的契约）
src/tools.ts 工具注册表（getAllBaseTools）
src/tools/ 70+ 内置工具实现
src/commands.ts 斜杠命令注册
src/commands/ 斜杠命令实现
src/state/AppStateStore.ts 全局 Zustand store
src/bootstrap/state.ts 应用初始化状态
src/services/mcp/ MCP 连接与工具集成
src/services/api/ Anthropic API 调用封装
src/services/compact/ 上下文压缩逻辑
src/coordinator/ 多 Worker 协调器模式
src/skills/ 技能系统（/skill-name 命令）
src/permissions/ 权限判断逻辑
src/components/ React/Ink UI 组件
src/hooks/ React Hooks

Tool 接口

每个工具实现 Tool<Input, Output> 接口（src/Tool.ts）：

buildTool({
  name: 'ToolName',
  description(): string,
  inputSchema: z.ZodObject,        // Zod schema 验证输入
  isEnabled(): Promise<boolean>,   // 是否启用
  checkPermissions(input): PermissionResult,
  call(input, context): Promise<ToolResult>,
  renderToolUseMessage(): ReactNode,
  renderToolResultMessage(): ReactNode,
  isConcurrencySafe(): boolean,    // 是否可并行执行
  isReadOnly(): boolean,
})

权限系统

权限模式（--permission-mode）：

模式 行为
default 危险操作提示用户确认
acceptEdits 自动接受文件编辑
bypassPermissions 跳过所有权限检查
plan 只读计划模式，不执行操作
dontAsk 静默允许所有操作

Feature Flag 系统

src/ 中大量使用 feature('FLAG_NAME') 做条件编译，原始构建通过 DCE 移除未启用的代码分支。开发环境通过 bun-bundle-shim.ts 模拟：

// 查看所有使用到的 flag
grep -r "feature('" src/ | grep -oP "feature\('([^']+)'\)" | sort -u

// 在 bun-bundle-shim.ts 中启用/禁用
const ENABLED_FLAGS = new Set([
  'BG_SESSIONS',       // 后台会话
  'DAEMON',            // 守护进程模式
  'ULTRATHINK',        // 深度思考模式
  // ... 其他 flag
])

修改 flag 后无需重新运行 dev-patch.ts（shim 文件不经过预处理，直接引用）。

Stub 文件说明

sourceMap 还原时只包含 .ts/.tsx 文件，以下文件在原始仓库中存在但未包含，需要 stub：

npm 包 Stub（source/node_modules/ 下）

包名 说明
@anthropic-ai/sandbox-runtime 沙箱隔离运行时（Anthropic 内部包）
@ant/claude-for-chrome-mcp Chrome 集成 MCP（Ant-only）
@ant/computer-use-mcp Computer Use MCP（Ant-only）
@ant/computer-use-input Computer Use 输入控制（Ant-only）
@ant/computer-use-swift macOS Swift Computer Use（Ant-only）
color-diff-napi 语法高亮颜色差异（Anthropic 内部 native addon）

React 补丁（直接修改 node_modules/react/）

补丁 原因
react/compiler-runtime.js React Compiler 运行时，需转发到 react-compiler-runtime
react.development.js 追加 use() React 19 API，React 18.3.1 未包含
react.development.js 追加 useEffectEvent() React 19 API，React 18.3.1 未包含
react-reconciler constants 追加 NoEventPriority Ink 内部依赖，版本不匹配

源码 Stub（src/ 中添加，由 dev-patch.ts 同步到 src-dev/）

新版本 v2.1.88 新增了以下模块，但未在 sourceMap 中（可能是新功能或 Ant-only）：

路径 说明
src/types/connectorText.ts Connector Text 消息块类型
src/services/contextCollapse/ 上下文折叠服务
src/services/skillSearch/ 技能搜索服务
src/services/compact/reactiveCompact.ts 响应式压缩
src/services/compact/snipCompact.ts Snip 压缩
src/assistant/ Assistant 模式
src/proactive/ 主动模式
src/jobs/classifier.ts 任务分类器
src/tools/WorkflowTool/ 工作流工具
src/tools/CtxInspectTool/ 上下文检查工具
src/commands/agents-platform/ Agents 平台命令
src/commands/workflows/ 工作流命令
src/commands/fork/ Fork 命令

依赖说明

主要依赖及其用途：

依赖 用途
@anthropic-ai/sdk Anthropic API 客户端
ink 终端 UI 框架（React-based）
react + react-compiler-runtime UI 渲染，React Compiler 优化
@modelcontextprotocol/sdk MCP 协议实现
commander CLI 参数解析
zod 运行时类型验证
@opentelemetry/* 遥测与可观测性
@anthropic-ai/sandbox-runtime 沙箱隔离（stub）
chokidar 文件系统监听
execa 子进程管理
lodash-es 工具函数库
yaml YAML 解析
sharp 图片处理
ws WebSocket

常见问题

bun install 报错 prepare script failed

error: prepare script from "@anthropic-ai/claude-code" exited with 1

原因： 在 source/ 目录下执行 bun add xxx 时，Bun 向上查找到了父级 package/package.json 并触发了其 prepare 脚本（内有授权检查）。

解决： 手动编辑 source/package.json 添加依赖，然后运行 bun install（不是 bun add）。

Cannot find module 'bun:bundle'

原因： bun:bundle 是 Bun 编译时虚拟模块，在 src/ 原始文件中存在。

解决： 运行 bun run dev-patch.ts 重新生成 src-dev/，确保所有 bun:bundle 导入已被替换。

MACRO is not defined

原因： 忘记使用 --preload 参数。

解决： 始终使用完整命令：

bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx [参数]

修改了 src/ 中的文件但没有生效

原因： 实际运行的是 src-dev/，需要重新生成。

解决：

bun run dev-patch.ts

修改了 bun-bundle-shim.ts 中的 feature flag 没有生效

bun-bundle-shim.ts 是直接被 src-dev/ 中的文件 import 的（绝对路径引用），无需重新运行 dev-patch.ts，改完直接重新运行 CLI 即可。

启动失败：Cannot find module './tools/XxxTool/XxxTool.js'

某个功能模块的实现文件不在 sourceMap 中，但对应的 feature flag 已启用。

解决：

  1. 在 bun-bundle-shim.ts 中注释掉对应的 flag（禁用该功能）
  2. 或在 src/tools/XxxTool/XxxTool.ts 中创建 stub 文件（使用 buildTool 返回禁用状态）

接入自定义模型（DeepSeek 等）

Claude Code 默认只支持 Anthropic API 格式，proxy.ts 是一个轻量 Bun 代理（零新增依赖），将 Anthropic 格式请求转换为 OpenAI 兼容格式，支持 DeepSeek、Qwen、Ollama、OpenAI 等任意 OpenAI 兼容接口。

快速启动

# 设置目标模型的 API Key
export OPENAI_API_KEY=sk-你的key

# 运行（自动启动代理 + Claude Code）
./run.sh deepseek-chat          # DeepSeek Chat（默认）
./run.sh deepseek-r1            # DeepSeek R1 推理模型
./run.sh deepseek-chat -p "问题" # 单次提问模式

run.sh 会自动完成：

  1. 检测代理是否已运行，未运行则启动 proxy.ts（端口 4000）
  2. 设置 ANTHROPIC_BASE_URL=http://localhost:4000 和 ANTHROPIC_API_KEY=placeholder
  3. 启动 Claude Code CLI

切换到其他模型

# Qwen（阿里云百炼）
export OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export OPENAI_API_KEY=sk-xxx
./run.sh qwen-plus

# 本地 Ollama（免费，无需 Key）
export OPENAI_BASE_URL=http://localhost:11434
export OPENAI_API_KEY=ollama
./run.sh llama3

# OpenAI
export OPENAI_BASE_URL=https://api.openai.com
export OPENAI_API_KEY=sk-xxx
./run.sh gpt-4o

模型名映射（可选）

Claude Code 发送请求时会带上 --model 指定的模型名。如需映射到不同的目标模型名：

export MODEL_MAP='{"my-alias":"deepseek-chat","my-r1":"deepseek-reasoner"}'
./run.sh my-alias

单独运行代理

export OPENAI_API_KEY=sk-xxx
export OPENAI_BASE_URL=https://api.deepseek.com   # 默认值，可省略
bun proxy.ts                    # 监听 4000 端口
bun proxy.ts --port 4001        # 自定义端口

# 代理运行后，手动设置环境变量连接 Claude Code
export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_API_KEY=placeholder
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx --model deepseek-chat

相关文件

文件 说明
proxy.ts Anthropic→OpenAI 格式代理，支持流式与非流式、Tool Use
run.sh 一键启动脚本，自动管理代理生命周期

附录：完整开发命令速查

# 安装依赖
bun install

# 生成 src-dev/
bun run dev-patch.ts

# 运行（替换 [args] 为实际参数）
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx [args]

# 常用运行示例
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx --version
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx --help
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx -p "你好"
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx --debug

About

claude-code v2.1.88 decompiled TypeScript source

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages