From 0d607ad4ed3ae584d5373e4386312b5043902071 Mon Sep 17 00:00:00 2001 From: Blizzard Date: Tue, 28 Apr 2026 10:40:28 +0800 Subject: [PATCH] =?UTF-8?q?init:=20cc=E6=B3=84=E9=9C=B2=E6=BA=90=E7=A0=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .idea/.gitignore | 3 + .idea/claude-code.iml | 8 ++ .idea/modules.xml | 8 ++ .idea/vcs.xml | 6 ++ codebase_analysis.md | 240 ++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 265 insertions(+) create mode 100644 .idea/.gitignore create mode 100644 .idea/claude-code.iml create mode 100644 .idea/modules.xml create mode 100644 .idea/vcs.xml create mode 100644 codebase_analysis.md diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 0000000..26d3352 --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,3 @@ +# Default ignored files +/shelf/ +/workspace.xml diff --git a/.idea/claude-code.iml b/.idea/claude-code.iml new file mode 100644 index 0000000..c956989 --- /dev/null +++ b/.idea/claude-code.iml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 0000000..f9561ec --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 0000000..35eb1dd --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/codebase_analysis.md b/codebase_analysis.md new file mode 100644 index 0000000..67a274a --- /dev/null +++ b/codebase_analysis.md @@ -0,0 +1,240 @@ +# 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. ✅ 会话持久化与恢复