Merge pull request #3 from NanmiCoder/docs/bilingual-readme-bun-install

docs: add bilingual README and Bun install guide
2026-04-01 12:09:17 +08:00
parent edae0e612d 919dd34a7a
commit d166eb89b6
2 changed files with 250 additions and 5 deletions
@@ -0,0 +1,213 @@
+# Claude Code Haha
+
+<p align="right"><a href="./README.md">中文</a> | <strong>English</strong></p>
+
+A **locally runnable version** repaired from the leaked Claude Code source, with support for any Anthropic-compatible API endpoint such as MiniMax and OpenRouter.
+
+> The original leaked source does not run as-is. This repository fixes multiple blocking issues in the startup path so the full Ink TUI can work locally.
+
+<p align="center">
+  <img src="docs/00runtime.png" alt="Runtime screenshot" width="800">
+</p>
+
+## Features
+
+- Full Ink TUI experience (matching the official Claude Code interface)
+- `--print` headless mode for scripts and CI
+- MCP server, plugin, and Skills support
+- Custom API endpoint and model support
+- Fallback Recovery CLI mode
+
+---
+
+## Architecture Overview
+
+<table>
+  <tr>
+    <td align="center" width="25%"><img src="docs/01-overall-architecture.png" alt="Overall architecture"><br><b>Overall architecture</b></td>
+    <td align="center" width="25%"><img src="docs/02-request-lifecycle.png" alt="Request lifecycle"><br><b>Request lifecycle</b></td>
+    <td align="center" width="25%"><img src="docs/03-tool-system.png" alt="Tool system"><br><b>Tool system</b></td>
+    <td align="center" width="25%"><img src="docs/04-multi-agent.png" alt="Multi-agent architecture"><br><b>Multi-agent architecture</b></td>
+  </tr>
+  <tr>
+    <td align="center" width="25%"><img src="docs/05-terminal-ui.png" alt="Terminal UI"><br><b>Terminal UI</b></td>
+    <td align="center" width="25%"><img src="docs/06-permission-security.png" alt="Permissions and security"><br><b>Permissions and security</b></td>
+    <td align="center" width="25%"><img src="docs/07-services-layer.png" alt="Services layer"><br><b>Services layer</b></td>
+    <td align="center" width="25%"><img src="docs/08-state-data-flow.png" alt="State and data flow"><br><b>State and data flow</b></td>
+  </tr>
+</table>
+
+---
+
+## Quick Start
+
+### 1. Install Bun
+
+This project requires [Bun](https://bun.sh). If Bun is not installed on the target machine yet, use one of the following methods first:
+
+```bash
+# macOS / Linux (official install script)
+curl -fsSL https://bun.sh/install | bash
+```
+
+If a minimal Linux image reports `unzip is required to install bun`, install `unzip` first:
+
+```bash
+# Ubuntu / Debian
+apt update && apt install -y unzip
+```
+
+```bash
+# macOS (Homebrew)
+brew install bun
+```
+
+```powershell
+# Windows (PowerShell)
+powershell -c "irm bun.sh/install.ps1 | iex"
+```
+
+After installation, reopen the terminal and verify:
+
+```bash
+bun --version
+```
+
+### 2. Install project dependencies
+
+```bash
+bun install
+```
+
+### 3. Configure environment variables
+
+Copy the example file and fill in your API key:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+# API authentication (choose one)
+ANTHROPIC_API_KEY=sk-xxx          # Standard API key via x-api-key header
+ANTHROPIC_AUTH_TOKEN=sk-xxx       # Bearer token via Authorization header
+
+# API endpoint (optional, defaults to Anthropic)
+ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
+
+# Model configuration
+ANTHROPIC_MODEL=MiniMax-M2.7-highspeed
+ANTHROPIC_DEFAULT_SONNET_MODEL=MiniMax-M2.7-highspeed
+ANTHROPIC_DEFAULT_HAIKU_MODEL=MiniMax-M2.7-highspeed
+ANTHROPIC_DEFAULT_OPUS_MODEL=MiniMax-M2.7-highspeed
+
+# Timeout in milliseconds
+API_TIMEOUT_MS=3000000
+
+# Disable telemetry and non-essential network traffic
+DISABLE_TELEMETRY=1
+CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
+```
+
+### 4. Start
+
+```bash
+# Interactive TUI mode (full interface)
+./bin/claude-haha
+
+# Headless mode (single prompt)
+./bin/claude-haha -p "your prompt here"
+
+# Pipe input
+echo "explain this code" | ./bin/claude-haha -p
+
+# Show all options
+./bin/claude-haha --help
+```
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|------|------|------|
+| `ANTHROPIC_API_KEY` | One of two | API key sent via the `x-api-key` header |
+| `ANTHROPIC_AUTH_TOKEN` | One of two | Auth token sent via the `Authorization: Bearer` header |
+| `ANTHROPIC_BASE_URL` | No | Custom API endpoint, defaults to Anthropic |
+| `ANTHROPIC_MODEL` | No | Default model |
+| `ANTHROPIC_DEFAULT_SONNET_MODEL` | No | Sonnet-tier model mapping |
+| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | No | Haiku-tier model mapping |
+| `ANTHROPIC_DEFAULT_OPUS_MODEL` | No | Opus-tier model mapping |
+| `API_TIMEOUT_MS` | No | API request timeout, default `600000` (10min) |
+| `DISABLE_TELEMETRY` | No | Set to `1` to disable telemetry |
+| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | No | Set to `1` to disable non-essential network traffic |
+
+---
+
+## Fallback Mode
+
+If the full TUI has issues, use the simplified readline-based interaction mode:
+
+```bash
+CLAUDE_CODE_FORCE_RECOVERY_CLI=1 ./bin/claude-haha
+```
+
+---
+
+## Fixes Compared with the Original Leaked Source
+
+The leaked source could not run directly. This repository mainly fixes the following issues:
+
+| Issue | Root cause | Fix |
+|------|------|------|
+| TUI does not start | The entry script routed no-argument startup to the recovery CLI | Restored the full `cli.tsx` entry |
+| Startup hangs | The `verify` skill imports a missing `.md` file, causing Bun's text loader to hang indefinitely | Added stub `.md` files |
+| `--print` hangs | `filePersistence/types.ts` was missing | Added type stub files |
+| `--print` hangs | `ultraplan/prompt.txt` was missing | Added resource stub files |
+| **Enter key does nothing** | The `modifiers-napi` native package was missing, `isModifierPressed()` threw, `handleEnter` was interrupted, and `onSubmit` never ran | Added try/catch fault tolerance |
+| Setup was skipped | `preload.ts` automatically set `LOCAL_RECOVERY=1`, skipping all initialization | Removed the default setting |
+
+---
+
+## Project Structure
+
+```text
+bin/claude-haha          # Entry script
+preload.ts               # Bun preload (sets MACRO globals)
+.env.example             # Environment variable template
+src/
+├── entrypoints/cli.tsx  # Main CLI entry
+├── main.tsx             # Main TUI logic (Commander.js + React/Ink)
+├── localRecoveryCli.ts  # Fallback Recovery CLI
+├── setup.ts             # Startup initialization
+├── screens/REPL.tsx     # Interactive REPL screen
+├── ink/                 # Ink terminal rendering engine
+├── components/          # UI components
+├── tools/               # Agent tools (Bash, Edit, Grep, etc.)
+├── commands/            # Slash commands (/commit, /review, etc.)
+├── skills/              # Skill system
+├── services/            # Service layer (API, MCP, OAuth, etc.)
+├── hooks/               # React hooks
+└── utils/               # Utility functions
+```
+
+---
+
+## Tech Stack
+
+| Category | Technology |
+|------|------|
+| Runtime | [Bun](https://bun.sh) |
+| Language | TypeScript |
+| Terminal UI | React + [Ink](https://github.com/vadimdemedes/ink) |
+| CLI parsing | Commander.js |
+| API | Anthropic SDK |
+| Protocols | MCP, LSP |
+
+---
+
+## Disclaimer
+
+This repository is based on the Claude Code source leaked from the Anthropic npm registry on 2026-03-31. All original source code copyrights belong to [Anthropic](https://www.anthropic.com). It is provided for learning and research purposes only.
@@ -1,5 +1,7 @@
 # Claude Code Haha

+<p align="right"><strong>中文</strong> | <a href="./README.en.md">English</a></p>
+
 基于 Claude Code 泄露源码修复的**本地可运行版本**，支持接入任意 Anthropic 兼容 API（如 MiniMax、OpenRouter 等）。

 > 原始泄露源码无法直接运行。本仓库修复了启动链路中的多个阻塞问题，使完整的 Ink TUI 交互界面可以在本地工作。
@@ -39,15 +41,45 @@

 ## 快速开始

-### 1. 安装依赖
+### 1. 安装 Bun

-需要 [Bun](https://bun.sh) >= 1.1 和 Node.js >= 18。
+本项目运行依赖 [Bun](https://bun.sh)。如果你的电脑还没有安装 Bun，可以先执行下面任一方式：

 ```bash
-npm install
+# macOS / Linux（官方安装脚本）
+curl -fsSL https://bun.sh/install | bash
 ```

-### 2. 配置环境变量
+如果在精简版 Linux 环境里提示 `unzip is required to install bun`，先安装 `unzip`：
+
+```bash
+# Ubuntu / Debian
+apt update && apt install -y unzip
+```
+
+```bash
+# macOS（Homebrew）
+brew install bun
+```
+
+```powershell
+# Windows（PowerShell）
+powershell -c "irm bun.sh/install.ps1 | iex"
+```
+
+安装完成后，重新打开终端并确认：
+
+```bash
+bun --version
+```
+
+### 2. 安装项目依赖
+
+```bash
+bun install
+```
+
+### 3. 配置环境变量

 复制示例文件并填入你的 API Key：

@@ -79,7 +111,7 @@ DISABLE_TELEMETRY=1
 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
 ```

-### 3. 启动
+### 4. 启动

 ```bash
 # 交互 TUI 模式（完整界面）