第1章：项目概览

本章介绍 Claude Code 项目的整体情况，包括项目定位、技术栈、目录结构和源码泄露背景。

1.1 项目定位

Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手工具，为开发者提供在终端中直接与 Claude AI 交互的能力。

功能特性

Note

Claude Code 定位为「Agentic CLI Tool」，与传统的代码补全工具（如 GitHub Copilot）不同，它能够理解复杂任务并自主执行多步骤操作。

核心功能包括：

功能类别	具体特性
代码操作	Read、Edit、Write、Grep、Glob 文件操作
命令执行	Bash 命令运行，支持后台任务
网络能力	WebFetch、WebSearch 网络信息获取
多 Agent	AgentTool 支持子 Agent 派发
技能系统	Skill 机制扩展能力边界
MCP 协议	支持外部 MCP Server 集成
权限管理	多级权限控制和安全检查

在 AI 编码工具栈中的位置

graph TD
    subgraph "Layer 1: 代码补全"
        C1[GitHub Copilot]
        C2[Cursor Inline]
    end
    
    subgraph "Layer 2: 对话式编码"
        CC[Claude Code]
        CD[Codex CLI]
        CX[Cursor Chat]
    end
    
    subgraph "Layer 3: 任务编排"
        OM[OpenMatrix]
        AA[AutoGPT]
    end
    
    C1 --> CC
    C2 --> CC
    CC --> OM
    
    L1["解决「写代码」"] -.-> C1
    L2["解决「复杂任务」"] -.-> CC  
    L3["解决「可信交付」"] -.-> OM

Claude Code 位于 Layer 2，介于代码补全工具和任务编排系统之间：

向下承接：能够理解代码上下文，执行代码生成、修改、调试等操作
向上支撑：为 OpenMatrix 等编排系统提供原子级执行能力

1.2 技术栈概览

graph TD
    A[Bun Runtime] --> B[TypeScript]
    B --> C[React + Ink TUI]
    B --> D[Anthropic SDK]
    B --> E[MCP SDK]
    D --> F[Messages API]
    D --> G[Tool Use]
    D --> H[Streaming]

核心技术栈

类别	技术	版本	说明
运行时	Bun	-	高性能 JS 运行时，替代 Node.js
语言	TypeScript	-	类型安全的开发体验
终端 UI	React + Ink	^6.8.0	React 风格的终端组件库
CLI 框架	Commander.js	^14.0.0	命令行参数解析
AI SDK	@anthropic-ai/sdk	^0.80.0	Anthropic Messages API
协议	@modelcontextprotocol/sdk	^1.29.0	MCP 协议实现

关键依赖

{
  "dependencies": {
    "@anthropic-ai/sdk": "^0.80.0",      // Claude API 客户端
    "@modelcontextprotocol/sdk": "^1.29.0", // MCP 协议支持
    "ink": "^6.8.0",                     // 终端 React 渲染
    "react": "^19.2.4",                  // React 核心（内部预发布版）
    "chalk": "^5.6.2",                   // 终端颜色输出
    "execa": "^9.6.1",                   // 进程执行
    "chokidar": "^5.0.0",                // 文件监听
    "ws": "^8.20.0",                     // WebSocket 通信
    "zod": "^4.3.6"                      // Schema 验证（内部版）
  }
}

Warning

部分依赖版本号来自泄露源码，可能是 Anthropic 内部预发布版本，与 npm 公开版本不一致。公开版本参考：React 18.3.1、Zod 3.24.x。

Tip

Bun 作为运行时的优势：内置 TypeScript 支持、更快的包管理、原生 ESM 模块加载，无需预编译即可运行 .ts 文件。

1.3 项目结构一览

graph TD
    E[bin/claude-haha<br/>入口脚本] --> C[cli.tsx<br/>CLI入口]
    C --> M[main.tsx<br/>TUI主逻辑 804KB]
    M --> Q[QueryEngine.ts<br/>查询引擎]
    M --> T[Tool.ts<br/>工具基类]
    T --> TOOLS[tools/<br/>46个工具]
    M --> SKILLS[skills/<br/>Skill系统]
    M --> CMDS[commands/<br/>斜杠命令]
    M --> SERV[services/<br/>服务层]
    M --> UI[ink/components/<br/>终端UI]

目录树结构（精简）

claude-code-haha-main/
├── bin/claude-haha              # 入口脚本
├── preload.ts                   # Bun preload（全局变量设置）
├── src/
│   ├── entrypoints/cli.tsx      # CLI 主入口
│   ├── main.tsx                 # 🔴 TUI 主逻辑（804KB）
│   ├── QueryEngine.ts           # 🔴 查询引擎（46KB）
│   ├── Tool.ts                  # 🔴 工具基类（29KB）
│   ├── tools.ts                 # 工具注册表（17KB）
│   ├── commands.ts              # 斜杠命令注册表（25KB）
│   │
│   ├── tools/                   # 🔴 46个工具子目录
│   │   ├── BashTool/            # - Bash 命令执行
│   │   ├── FileEditTool/        # - 文件编辑
│   │   ├── AgentTool/           # - 子 Agent 派发
│   │   ├── SkillTool/           # - Skill 调用
│   │   ├── MCPTool/             # - MCP 协议
│   │   └── ...                  # 其他 41 个工具
│   │
│   ├── skills/                  # 🔴 Skill 系统
│   │   ├── bundled/             # 内置 Skills 目录
│   │   └── bundledSkills.ts     # Skill 注册机制
│   │
│   ├── commands/                # 🔴 斜杠命令
│   │   ├── init.ts              # /init 命令
│   │   ├── review.ts            # /review 命令
│   │   ├── mcp/                 # /mcp 子命令组
│   │   └── ...
│   │
│   ├── services/                # 服务层（MCP/API/OAuth/LSP）
│   ├── ink/                     # Ink 终端渲染引擎
│   ├── components/              # UI 组件库
│   ├── hooks/                   # React hooks
│   ├── utils/                   # 工具函数
│   └── types/                   # TypeScript 类型定义
└── .env.example                 # 环境变量模板

🔴 标记为核心分析目标，将在后续章节深入解析。

核心文件说明

文件	大小	说明
`main.tsx`	804KB	TUI 主逻辑，包含 Commander 命令解析、React/Ink 渲染、消息处理循环
`QueryEngine.ts`	46KB	查询引擎，处理 API 请求和响应流
`Tool.ts`	29KB	工具基类定义，包含类型和执行框架
`tools.ts`	17KB	工具注册表，汇总所有可用工具
`commands.ts`	25KB	斜杠命令注册表

Warning

main.tsx 文件体积达 804KB，推测是编译打包产物而非源码形式，后续章节将详细分析其结构。

1.4 泄露源码背景与修复说明

免责声明

本源码基于 2025-03-31 从 Anthropic npm registry 泄露的 Claude Code 源码。所有原始源码版权归 Anthropic 所有。仅供学习和研究用途，请勿用于商业或生产环境。

泄露背景

2025年3月31日，Anthropic 的内部 npm registry 发生配置错误，导致 Claude Code 的完整源码被意外公开。泄露的源码无法直接运行，需要修复多个阻塞问题才能启动。

修复记录

问题	根因分析	修复方案
TUI 不启动	入口脚本把无参数启动路由到了 recovery CLI	恢复走 `cli.tsx` 完整入口
启动卡死	`verify` skill 导入缺失的 `.md` 文件，Bun text loader 无限挂起	创建 stub `.md` 文件
`--print` 卡死	`filePersistence/types.ts` 缺失	创建类型桩文件
`--print` 卡死	`ultraplan/prompts.txt` 缺失	创建资源桩文件
Enter 键无响应	`modifiers-napi` native 包缺失，`isModifierPressed()` 抛异常	加 try-catch 容错
setup 被跳过	`preload.ts` 自动设置 `LOCAL_RECOVERY=1` 跳过初始化	移除默认设置

flowchart LR
    O1[TUI 不启动] --> F1[修复入口路由] --> R1[完整 TUI]
    O2[启动卡死] --> F2[创建 stub 文件] --> R2[正常交互]
    O3[Enter 无响应] --> F3[添加容错] --> R3[API 连通]

本仓库定位

本仓库 (claude-code-haha-main) 是修复后的版本，主要改动：

入口修复：恢复正确的 CLI 启动路径
依赖补全：创建缺失的 stub 文件
容错增强：对 native 模块缺失添加 fallback
API 兼容：支持自定义 API 端点（如 MiniMax、OpenRouter）

Tip

修复后可以完整运行 Ink TUI 交互界面，与官方 Claude Code 体验一致。支持 --print 无头模式和 MCP 服务器接入。

下一章将深入探讨 Claude Code 的核心概念，包括 Agent、Tool、Skill、MCP 协议等。

Keyboard shortcuts

Claude Code 源码解析