# Claude Code Haha — 项目代码分析

## 概述

本项目是基于 **2026-03-31 泄露的 Anthropic Claude Code 源码** 修复而成的本地可运行版本，命名为 **Claude Code Haha**。它是一个功能完整的 **AI 编程助手 CLI 工具**，支持接入任意 Anthropic 兼容 API（如 MiniMax、OpenRouter 等）。

> [!NOTE]
> 泄露的原始源码无法直接运行。本仓库修复了启动链路中的多个阻塞问题（Enter 键无响应、TUI 不启动、stub 文件缺失等），使完整的 Ink TUI 交互界面可以在本地工作。

---

## 技术栈

| 类别 | 技术 | 说明 |
|------|------|------|
| **运行时** | [Bun](https://bun.sh) | 高性能 JS/TS 运行时，用于替代 Node.js |
| **语言** | TypeScript (ESNext) | 全量 TS，`moduleResolution: bundler` |
| **终端 UI** | React 19 + [Ink 6](https://github.com/vadimdemedes/ink) | 基于 React 渲染终端 TUI 界面 |
| **CLI 解析** | Commander.js (`@commander-js/extra-typings`) | 命令行参数解析和子命令 |
| **AI API** | `@anthropic-ai/sdk` | Anthropic Messages API 通信 |
| **MCP 协议** | `@modelcontextprotocol/sdk` | Model Context Protocol 客户端 |
| **LSP** | `vscode-jsonrpc` / `vscode-languageserver-types` | Language Server Protocol 集成 |
| **可观测性** | OpenTelemetry (logs/metrics/tracing) | 遥测数据采集 |
| **特性开关** | GrowthBook (`@growthbook/growthbook`) | A/B 测试与功能门控 |
| **构建特性** | `bun:bundle` (`feature()`) | 编译时死代码消除 |
| **数据验证** | Zod v4 | 输入 schema 定义与校验 |
| **云认证** | `google-auth-library`, `@aws-sdk/client-bedrock-runtime` | Google/AWS 多云认证 |
| **Markdown** | `marked` + `highlight.js` | Markdown 渲染和代码高亮 |
| **搜索** | `fuse.js` | 模糊搜索（命令/文件搜索） |
| **其他** | `chalk`, `diff`, `chokidar`, `yaml`, `zod`, `ws` | 着色、diff、文件监听、YAML 解析、WebSocket |

---

## 架构概览

### 启动链路

```
bin/claude-haha (Bash)
  └─ bun --env-file=.env src/entrypoints/cli.tsx
       ├─ Fast paths: --version, --daemon, --bridge, ps/logs/attach/kill
       └─ Full CLI: src/main.tsx (Commander.js 解析 → React/Ink TUI)
            └─ src/screens/REPL.tsx (主交互 REPL 循环)
```

- **`preload.ts`** — Bun preload 脚本，注入 `MACRO` 全局变量（版本号等）
- **`cli.tsx`** — Bootstrap 入口，通过 fast-path 优化各子命令的加载速度
- **`main.tsx`** (~800KB) — 核心主逻辑，Commander.js 定义所有命令行选项
- **`REPL.tsx`** (~900KB) — 交互式 REPL 界面，处理用户输入、消息渲染、工具执行

### 核心模块层次

```mermaid
graph TD
    A[CLI Entry - cli.tsx] --> B[Main - main.tsx]
    B --> C[REPL Screen - REPL.tsx]
    C --> D[Query Engine - query.ts]
    D --> E[API Service - services/api]
    D --> F[Tool System - tools/]
    D --> G[Auto Compact - services/compact]
    C --> H[UI Components - components/]
    C --> I[React Hooks - hooks/]
    F --> J[Permission System - utils/permissions]
    C --> K[MCP Clients - services/mcp]
    C --> L[Slash Commands - commands/]
```

---

## 核心系统详解

### 1. Query Engine (`query.ts`, `QueryEngine.ts`)

**核心循环**：`query()` 是一个 `AsyncGenerator`，驱动整个 AI 对话循环：

1. **上下文管理** — 自动压缩（auto compact）、微压缩（microcompact）、snip（历史裁剪）
2. **API 调用** — 流式调用 Anthropic Messages API
3. **工具执行** — 解析模型返回的 `tool_use` 块，执行对应工具
4. **循环继续** — 将工具结果拼接回消息列表，继续下一轮推理

关键特性：
- **Task Budget** — 限制单次 agentic turn 的总 token 消耗
- **Reactive Compact** — 遇到 prompt-too-long 时自动触发压缩
- **Streaming Tool Execution** — 流式接收模型输出的同时并行启动工具执行
- **Fallback Model** — 主模型失败时自动降级到备用模型

### 2. Tool System (`Tool.ts`, `tools.ts`, `tools/`)

采用 **`buildTool()` 工厂模式**，统一工具定义接口。每个工具包含：
- `inputSchema` (Zod) — 输入校验
- `checkPermissions()` — 权限检查
- `call()` — 执行逻辑
- `renderToolUseMessage()` / `renderToolResultMessage()` — UI 渲染
- `prompt()` — 给模型的工具说明

#### 内置工具清单 (40+)

| 分类 | 工具 | 说明 |
|------|------|------|
| **文件操作** | `FileReadTool`, `FileWriteTool`, `FileEditTool`, `NotebookEditTool` | 读/写/编辑文件、Jupyter Notebook |
| **搜索** | `GrepTool`, `GlobTool`, `WebSearchTool`, `ToolSearchTool` | Ripgrep 搜索、Glob 匹配、网页搜索、工具发现 |
| **Shell** | `BashTool`, `PowerShellTool`, `REPLTool` | Bash/PowerShell 命令执行、REPL VM 模式 |
| **任务管理** | `TaskCreateTool`, `TaskGetTool`, `TaskUpdateTool`, `TaskListTool`, `TaskStopTool`, `TaskOutputTool` | 多任务并行管理 |
| **Agent** | `AgentTool`, `TeamCreateTool`, `TeamDeleteTool`, `SendMessageTool` | 子 Agent 派生、团队协作 |
| **计划模式** | `EnterPlanModeTool`, `ExitPlanModeTool`, `EnterWorktreeTool`, `ExitWorktreeTool` | 进入/退出计划模式、Git Worktree 隔离 |
| **网络** | `WebFetchTool`, `WebBrowserTool` | HTTP 抓取、浏览器自动化 |
| **MCP** | `MCPTool`, `ListMcpResourcesTool`, `ReadMcpResourceTool` | MCP 服务器工具代理 |
| **其他** | `TodoWriteTool`, `SkillTool`, `AskUserQuestionTool`, `LSPTool`, `ConfigTool`, `SleepTool`, `BriefTool` | TODO 管理、Skill 调用、用户交互、LSP 诊断 |
| **特殊** | `ScheduleCronTool`, `RemoteTriggerTool`, `WorkflowTool`, `MonitorTool` | 定时任务、远程触发、工作流脚本 |

### 3. 斜杠命令系统 (`commands/`)

项目包含 **87+ 个斜杠命令目录**，覆盖：

| 分类 | 命令示例 |
|------|----------|
| **Git 操作** | `/commit`, `/diff`, `/branch`, `/review`, `/pr_comments` |
| **会话管理** | `/session`, `/resume`, `/compact`, `/clear`, `/export`, `/share` |
| **配置** | `/config`, `/model`, `/theme`, `/keybindings`, `/permissions`, `/vim` |
| **Agent/协作** | `/agents`, `/buddy`, `/tasks`, `/teleport` |
| **开发工具** | `/doctor`, `/stats`, `/debug-tool-call`, `/heapdump`, `/ctx_viz` |
| **集成** | `/mcp`, `/plugin`, `/skills`, `/chrome`, `/ide`, `/desktop` |
| **其他** | `/help`, `/version`, `/upgrade`, `/feedback`, `/voice`, `/login`, `/logout` |

### 4. 服务层 (`services/`)

| 服务 | 说明 |
|------|------|
| `api/` | API 调用封装 (重试、fallback、mock、dump prompts) |
| `mcp/` | MCP 客户端管理 (连接、工具注册、资源读取) |
| `compact/` | 自动压缩 (auto compact, reactive compact, snip) |
| `oauth/` | OAuth 认证流程 |
| `lsp/` | LSP 服务器集成 |
| `analytics/` | 分析追踪 (GrowthBook, 事件上报) |
| `plugins/` | 插件加载与管理 |
| `voice.ts` | 语音输入 (STT) |
| `tips/` | 使用提示推送 |
| `policyLimits/` | 组织策略限制 |

### 5. UI 组件 (`components/`)

基于 React + Ink 构建的终端 UI 组件体系，包含 **113 个组件文件** + **31 个子目录**：

- **核心交互**: `PromptInput/`, `TextInput`, `VimTextInput`, `BaseTextInput`
- **消息渲染**: `Message`, `MessageRow`, `Messages`, `VirtualMessageList`（虚拟滚动）
- **差异展示**: `StructuredDiff/`, `FileEditToolDiff`, `diff/`
- **对话框**: `ModelPicker`, `ThemePicker`, `GlobalSearchDialog`, `HistorySearchDialog`
- **状态显示**: `StatusLine`, `Spinner`, `AgentProgressLine`, `CoordinatorAgentStatus`
- **Markdown**: `Markdown`, `MarkdownTable`, `HighlightedCode/`
- **设计系统**: `design-system/`, `ui/`

### 6. Skill 系统 (`skills/`)

Skill 是可扩展的指令文件系统：
- `bundledSkills.ts` — 内置 skill 注册
- `loadSkillsDir.ts` — 从文件系统加载自定义 skill
- `bundled/` — 内置 skill 目录
- 支持 YAML frontmatter 格式的 `.md` 文件

### 7. 多 Agent 架构 (`coordinator/`)

- **Coordinator Mode** — 协调器模式，中央 Agent 分配任务给 Worker Agent
- **Agent Tool** — 派生子 Agent 执行独立任务
- **Team System** — 创建/删除团队成员
- **Worktree** — Git Worktree 隔离执行

### 8. 权限与安全 (`utils/permissions/`)

多层权限控制体系：
- **PermissionMode**: `default`, `plan`, `auto`, `bypass`
- **规则来源**: project CLAUDE.md、user settings、CLI flags
- **规则类型**: `alwaysAllow`, `alwaysDeny`, `alwaysAsk`
- **Hooks**: `PreToolUse`, `PostToolUse` 钩子

---

## 关键数据流

```
用户输入 → PromptInput → handlePromptSubmit()
  → slash command? → 执行 command handler
  → 否 → query() async generator
    → auto compact / microcompact / snip
    → prependUserContext() + appendSystemContext()
    → deps.callModel() (流式 API 调用)
    → 解析 tool_use 块 → StreamingToolExecutor
    → checkPermissions() → call() → ToolResult
    → 拼接 tool_result → 继续循环
    → stop_reason ≠ tool_use → 结束
```

---

## 项目文件统计

| 目录 | 估计文件数 | 说明 |
|------|-----------|------|
| `src/tools/` | 44 目录 | 内置工具实现 |
| `src/commands/` | 87 目录 + 15 文件 | 斜杠命令 |
| `src/components/` | 113 文件 + 31 目录 | UI 组件 |
| `src/hooks/` | 83 文件 + 2 目录 | React hooks |
| `src/utils/` | 298 文件 + 31 目录 | 工具函数 |
| `src/services/` | 16 文件 + 20 目录 | 服务层 |
| **总计** | ~700+ 文件 | **大型 TypeScript 项目** |

> [!IMPORTANT]
> 核心文件体量巨大：`main.tsx` (~800KB)、`REPL.tsx` (~900KB)、`messages.ts` (~193KB)、`query.ts` (~69KB)。这是一个工业级的 AI 编程助手完整实现。

---

## 本地修复清单

| 问题 | 修复方式 |
|------|----------|
| TUI 不启动 | 恢复 `cli.tsx` 完整入口（原代码错误路由到 recovery CLI） |
| 启动卡死 | 创建 stub `.md` 文件（`verify` skill 导入缺失） |
| `--print` 卡死 | 创建 `filePersistence/types.ts` 和 `ultraplan/prompt.txt` 桩文件 |
| Enter 键无响应 | `modifiers-napi` native 包缺失，加 try-catch 容错 |
| setup 被跳过 | 移除 `preload.ts` 中默认设置的 `LOCAL_RECOVERY=1` |

---

## 总结

这是一个 **功能极其完整的 AI 编程助手** 实现，涵盖：

1. ✅ 完整的终端 TUI 交互界面 (React/Ink)
2. ✅ 40+ 内建工具 (文件操作、搜索、Shell、Agent、MCP)
3. ✅ 87+ 斜杠命令
4. ✅ 多 Agent 并行执行 (Coordinator/Worker 架构)
5. ✅ MCP 协议支持
6. ✅ Skill/Plugin 扩展系统
7. ✅ 自动上下文压缩 (auto compact, reactive compact, snip)
8. ✅ 流式工具执行
9. ✅ 多层权限控制
10. ✅ 语音输入支持
11. ✅ Git Worktree 隔离执行
12. ✅ IDE 集成 (VS Code, JetBrains)
13. ✅ OAuth / API Key 认证
14. ✅ 会话持久化与恢复