mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-15 12:53:31 +08:00
docs: restructure README and organize docs into subdirectories
- Slim down README from ~400 lines to ~140 lines, keeping only essential content - Reorganize docs/ into guide/, features/, reference/, images/ subdirectories - Add GitHub badges (stars, forks, issues, PRs, license, language switch) - Extract env vars, FAQ, fixes, project structure, global usage into separate docs - Add LICENSE file (educational and research use only) - Update all cross-references and issue template links
This commit is contained in:
程序员阿江(Relakkes)
parent
28f3a22ef9
commit
8bb3c0e116
2
.github/ISSUE_TEMPLATE/question.md
vendored
2
.github/ISSUE_TEMPLATE/question.md
vendored
@ -9,7 +9,7 @@ assignees: ''
|
||||
## ⚠️ 提交前确认
|
||||
<!-- 请确认以下事项 -->
|
||||
- [ ] 我已经仔细阅读了 [README 常见问题](https://github.com/NanmiCoder/cc-haha#常见问题) 部分
|
||||
- [ ] 我已经阅读了[第三方模型使用指南](https://github.com/NanmiCoder/cc-haha/blob/main/docs/third-party-models.md)
|
||||
- [ ] 我已经阅读了[第三方模型使用指南](https://github.com/NanmiCoder/cc-haha/blob/main/docs/guide/third-party-models.md)
|
||||
- [ ] 我已经搜索并查看了[已关闭的 issues](https://github.com/NanmiCoder/cc-haha/issues?q=is%3Aissue+is%3Aclosed)
|
||||
|
||||
## ❓ 问题描述
|
||||
|
||||
38
LICENSE
Normal file
38
LICENSE
Normal file
@ -0,0 +1,38 @@
|
||||
DISCLAIMER AND LICENSE
|
||||
|
||||
Copyright (c) 2026 Anthropic, PBC. All rights reserved for the original source code.
|
||||
|
||||
This repository is based on the Claude Code source code leaked from the Anthropic
|
||||
npm registry on 2026-03-31. All original source code copyrights belong to Anthropic.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED FOR EDUCATIONAL AND RESEARCH PURPOSES ONLY.
|
||||
|
||||
The purpose of this repository is to facilitate the study and research of AI Agent
|
||||
engineering, including but not limited to:
|
||||
- Agent architecture and design patterns
|
||||
- Tool use and function calling mechanisms
|
||||
- Multi-agent orchestration
|
||||
- Terminal UI (TUI) implementation for AI applications
|
||||
- MCP (Model Context Protocol) integration
|
||||
|
||||
RESTRICTIONS:
|
||||
|
||||
1. This software SHALL NOT be used for any commercial purposes.
|
||||
2. This software SHALL NOT be used to compete with or replicate Anthropic's
|
||||
commercial products or services.
|
||||
3. This software SHALL NOT be redistributed, sublicensed, or sold in any form.
|
||||
4. Users SHALL comply with all applicable laws and regulations in their jurisdiction.
|
||||
|
||||
NO WARRANTY:
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
|
||||
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
|
||||
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
|
||||
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
||||
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||||
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
By using this software, you acknowledge that:
|
||||
- You understand this is leaked source code and all original rights belong to Anthropic.
|
||||
- You will use it solely for learning and research of Agent engineering.
|
||||
- You assume all legal risks and responsibilities arising from the use of this software.
|
||||
310
README.en.md
310
README.en.md
@ -1,28 +1,28 @@
|
||||
# Claude Code Haha
|
||||
|
||||
<p align="right"><a href="./README.md">中文</a> | <strong>English</strong></p>
|
||||
<div align="center">
|
||||
|
||||
[](https://github.com/NanmiCoder/cc-haha/stargazers)
|
||||
[](https://github.com/NanmiCoder/cc-haha/network/members)
|
||||
[](https://github.com/NanmiCoder/cc-haha/issues)
|
||||
[](https://github.com/NanmiCoder/cc-haha/pulls)
|
||||
[](https://github.com/NanmiCoder/cc-haha/blob/main/LICENSE)
|
||||
[](README.md)
|
||||
[](README.en.md)
|
||||
|
||||
</div>
|
||||
|
||||
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">
|
||||
<img src="docs/images/00runtime.png" alt="Runtime screenshot" width="800">
|
||||
</p>
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Features](#features)
|
||||
- [Architecture Overview](#architecture-overview)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Environment Variables](#environment-variables)
|
||||
- [Fallback Mode](#fallback-mode)
|
||||
- [Computer Use Desktop Control](#computer-use-desktop-control)
|
||||
- [Memory System](#memory-system)
|
||||
- [FAQ](#faq)
|
||||
- [Fixes Compared with the Original Leaked Source](#fixes-compared-with-the-original-leaked-source)
|
||||
- [Project Structure](#project-structure)
|
||||
- [Tech Stack](#tech-stack)
|
||||
<p align="center">
|
||||
<a href="#features">Features</a> · <a href="#architecture-overview">Architecture</a> · <a href="#quick-start">Quick Start</a> · <a href="docs/guide/env-vars.en.md">Env Vars</a> · <a href="docs/guide/faq.en.md">FAQ</a> · <a href="docs/guide/global-usage.en.md">Global Usage</a> · <a href="#more-documentation">More Docs</a>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
@ -31,12 +31,10 @@ A **locally runnable version** repaired from the leaked Claude Code source, with
|
||||
- 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 ([Third-Party Models Guide](docs/third-party-models.en.md))
|
||||
- **Computer Use desktop control** (screenshots, mouse, keyboard, app management) — [Guide](docs/computer-use.en.md)
|
||||
- **Memory System** (cross-session persistent memory with auto-extraction and smart retrieval) — [Usage Guide](docs/memory/01-usage-guide.md) | [Implementation](docs/memory/02-implementation.md)
|
||||
- Fallback Recovery CLI mode
|
||||
|
||||
> **Computer Use Note**: This project includes a **modified version of Computer Use**. The official implementation relies on Anthropic's private native modules. We replaced the entire underlying operation layer with a Python bridge (`pyautogui` + `mss` + `pyobjc`), enabling anyone to use Computer Use on macOS. See the [Computer Use Guide](docs/computer-use.en.md) for details.
|
||||
- Custom API endpoint and model support ([Third-Party Models Guide](docs/guide/third-party-models.en.md))
|
||||
- **Computer Use desktop control** — [Guide](docs/features/computer-use.en.md)
|
||||
- **Memory System** (cross-session persistent memory) — [Usage Guide](docs/memory/01-usage-guide.md)
|
||||
- Fallback Recovery CLI mode (`CLAUDE_CODE_FORCE_RECOVERY_CLI=1 ./bin/claude-haha`)
|
||||
|
||||
---
|
||||
|
||||
@ -44,16 +42,16 @@ A **locally runnable version** repaired from the leaked Claude Code source, with
|
||||
|
||||
<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>
|
||||
<td align="center" width="25%"><img src="docs/images/01-overall-architecture.png" alt="Overall architecture"><br><b>Overall architecture</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/02-request-lifecycle.png" alt="Request lifecycle"><br><b>Request lifecycle</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/03-tool-system.png" alt="Tool system"><br><b>Tool system</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/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>
|
||||
<td align="center" width="25%"><img src="docs/images/05-terminal-ui.png" alt="Terminal UI"><br><b>Terminal UI</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/06-permission-security.png" alt="Permissions and security"><br><b>Permissions and security</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/07-services-layer.png" alt="Services layer"><br><b>Services layer</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/08-state-data-flow.png" alt="State and data flow"><br><b>State and data flow</b></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
@ -63,238 +61,55 @@ A **locally runnable version** repaired from the leaked Claude Code source, with
|
||||
|
||||
### 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)
|
||||
# macOS / Linux
|
||||
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:
|
||||
> On minimal Linux images, if you see `unzip is required`, run `apt update && apt install -y unzip` first.
|
||||
|
||||
```bash
|
||||
bun --version
|
||||
```
|
||||
|
||||
### 2. Install project dependencies
|
||||
### 2. Install Dependencies and Configure
|
||||
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
### 3. Configure environment variables
|
||||
|
||||
Copy the example file and fill in your API key:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your API key — see docs/guide/env-vars.en.md for details
|
||||
```
|
||||
|
||||
Edit `.env` (the example below uses [MiniMax](https://platform.minimaxi.com/subscribe/token-plan?code=1TG2Cseab2&source=link) as the API provider — you can replace it with any compatible service):
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
> **Tip**: You can also configure environment variables via the `env` field in `~/.claude/settings.json`. This is consistent with the official Claude Code configuration:
|
||||
>
|
||||
> ```json
|
||||
> {
|
||||
> "env": {
|
||||
> "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
|
||||
> "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
|
||||
> "ANTHROPIC_MODEL": "MiniMax-M2.7-highspeed"
|
||||
> }
|
||||
> }
|
||||
> ```
|
||||
>
|
||||
> Priority: Environment variables > `.env` file > `~/.claude/settings.json`
|
||||
|
||||
### 4. Start
|
||||
### 3. Start
|
||||
|
||||
#### macOS / Linux
|
||||
|
||||
```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
|
||||
./bin/claude-haha # Interactive TUI mode
|
||||
./bin/claude-haha -p "your prompt here" # Headless mode
|
||||
./bin/claude-haha --help # Show all options
|
||||
```
|
||||
|
||||
#### Windows
|
||||
|
||||
> **Prerequisite**: [Git for Windows](https://git-scm.com/download/win) must be installed (provides Git Bash, which the project's internal shell execution depends on).
|
||||
|
||||
The startup script `bin/claude-haha` is a bash script and cannot run directly in cmd or PowerShell. Use one of the following methods:
|
||||
|
||||
**Option 1: PowerShell / cmd — call Bun directly (recommended)**
|
||||
> **Prerequisite**: [Git for Windows](https://git-scm.com/download/win) must be installed.
|
||||
|
||||
```powershell
|
||||
# Interactive TUI mode
|
||||
# PowerShell / cmd — call Bun directly
|
||||
bun --env-file=.env ./src/entrypoints/cli.tsx
|
||||
|
||||
# Headless mode
|
||||
bun --env-file=.env ./src/entrypoints/cli.tsx -p "your prompt here"
|
||||
|
||||
# Fallback Recovery CLI
|
||||
bun --env-file=.env ./src/localRecoveryCli.ts
|
||||
```
|
||||
|
||||
**Option 2: Run inside Git Bash**
|
||||
|
||||
```bash
|
||||
# Same usage as macOS / Linux
|
||||
# Or run inside Git Bash
|
||||
./bin/claude-haha
|
||||
```
|
||||
|
||||
> **Note**: Some features (voice input, Computer Use, sandbox isolation, etc.) are not available on Windows. This does not affect the core TUI interaction.
|
||||
### 4. Global Usage (Optional)
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
Add `bin/` to your PATH to run from any directory. See [Global Usage Guide](docs/guide/global-usage.en.md):
|
||||
|
||||
```bash
|
||||
CLAUDE_CODE_FORCE_RECOVERY_CLI=1 ./bin/claude-haha
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Computer Use Desktop Control
|
||||
|
||||
This project enables and modifies Claude Code's Computer Use feature (internal codename "Chicago"), allowing AI models to directly control your macOS desktop — screenshots, mouse clicks, keyboard input, app management.
|
||||
|
||||
**Underlying modification**: The official implementation depends on Anthropic's private native modules (`@ant/computer-use-swift`, `@ant/computer-use-input`). This project replaces them entirely with a Python bridge using `pyautogui` (mouse/keyboard), `mss` (screenshots), and `pyobjc` (macOS APIs) — no closed-source binaries required.
|
||||
|
||||
```bash
|
||||
# Ensure Python 3 and macOS Accessibility/Screen Recording permissions, then:
|
||||
./bin/claude-haha
|
||||
> Take a screenshot
|
||||
> Open Safari and search for something
|
||||
```
|
||||
|
||||
For supported platforms, technical architecture, and approaches we tried, see: **[Computer Use Guide](docs/computer-use.en.md)**
|
||||
|
||||
---
|
||||
|
||||
## Memory System
|
||||
|
||||
Claude Code includes a **file-based persistent memory system** that accumulates understanding of users and projects across sessions. Core principle: only remember what cannot be inferred from the code.
|
||||
|
||||
**Four memory types**:
|
||||
|
||||
| Type | Purpose | Example |
|
||||
|------|---------|---------|
|
||||
| **User** | Role, skills, preferences | "Deep Go expertise, new to React" |
|
||||
| **Feedback** | Corrections or confirmations of Claude's approach | "Don't mock the database in tests" |
|
||||
| **Project** | Project context not derivable from code | "Merge freeze starts Thursday" |
|
||||
| **Reference** | Pointers to external systems | "Pipeline bugs tracked in Linear INGEST" |
|
||||
|
||||
**Core capabilities**:
|
||||
|
||||
- **Auto-extraction**: After each conversation, a background forked agent automatically analyzes and saves noteworthy information
|
||||
- **Smart retrieval**: When the user asks a question, a Sonnet model selects the most relevant memories (up to 5) to inject into context
|
||||
- **Freshness management**: Memories older than 1 day carry staleness warnings and are verified before citation
|
||||
|
||||
Documentation: **[Usage Guide](docs/memory/01-usage-guide.md)** | **[Implementation Details](docs/memory/02-implementation.md)**
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
export PATH="$HOME/path/to/claude-code-haha/bin:$PATH"
|
||||
```
|
||||
|
||||
---
|
||||
@ -312,39 +127,18 @@ src/
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
## More Documentation
|
||||
|
||||
### Q: `undefined is not an object (evaluating 'usage.input_tokens')`
|
||||
|
||||
**Cause**: `ANTHROPIC_BASE_URL` is misconfigured. The API endpoint is returning HTML or another non-JSON format instead of a valid Anthropic protocol response.
|
||||
|
||||
This project uses the **Anthropic Messages API protocol**. `ANTHROPIC_BASE_URL` must point to an endpoint compatible with Anthropic's `/v1/messages` interface. The Anthropic SDK automatically appends `/v1/messages` to the base URL, so:
|
||||
|
||||
- MiniMax: `ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic` ✅
|
||||
- OpenRouter: `ANTHROPIC_BASE_URL=https://openrouter.ai/api` ✅
|
||||
- OpenRouter (wrong): `ANTHROPIC_BASE_URL=https://openrouter.ai/anthropic` ❌ (returns HTML)
|
||||
|
||||
If your model provider only supports the OpenAI protocol, you need a proxy like LiteLLM for protocol translation. See the [Third-Party Models Guide](docs/third-party-models.en.md).
|
||||
|
||||
### Q: `Cannot find package 'bundle'`
|
||||
|
||||
```
|
||||
error: Cannot find package 'bundle' from '.../claude-code-haha/src/entrypoints/cli.tsx'
|
||||
```
|
||||
|
||||
**Cause**: Your Bun version is too old and doesn't support the required `bun:bundle` built-in module.
|
||||
|
||||
**Fix**: Upgrade Bun to the latest version:
|
||||
|
||||
```bash
|
||||
bun upgrade
|
||||
```
|
||||
|
||||
### Q: How to use OpenAI / DeepSeek / Ollama or other non-Anthropic models?
|
||||
|
||||
This project only supports the Anthropic protocol. If your model provider doesn't natively support the Anthropic protocol, you need a proxy like [LiteLLM](https://github.com/BerriAI/litellm) for protocol translation (OpenAI → Anthropic).
|
||||
|
||||
See the [Third-Party Models Guide](docs/third-party-models.en.md) for detailed setup instructions.
|
||||
| Document | Description |
|
||||
|------|------|
|
||||
| [Environment Variables](docs/guide/env-vars.en.md) | Full env var reference and configuration methods |
|
||||
| [Third-Party Models](docs/guide/third-party-models.en.md) | Using OpenAI / DeepSeek / Ollama and other non-Anthropic models |
|
||||
| [Computer Use](docs/features/computer-use.en.md) | Desktop control (screenshots, mouse, keyboard) |
|
||||
| [Memory System](docs/memory/01-usage-guide.md) | Cross-session persistent memory usage and implementation |
|
||||
| [Global Usage](docs/guide/global-usage.en.md) | Run claude-haha from any directory |
|
||||
| [FAQ](docs/guide/faq.en.md) | Common error troubleshooting |
|
||||
| [Source Fixes](docs/reference/fixes.en.md) | Fixes compared with the original leaked source |
|
||||
| [Project Structure](docs/reference/project-structure.en.md) | Code directory structure |
|
||||
|
||||
---
|
||||
|
||||
|
||||
314
README.md
314
README.md
@ -1,28 +1,28 @@
|
||||
# Claude Code Haha
|
||||
|
||||
<p align="right"><strong>中文</strong> | <a href="./README.en.md">English</a></p>
|
||||
<div align="center">
|
||||
|
||||
[](https://github.com/NanmiCoder/cc-haha/stargazers)
|
||||
[](https://github.com/NanmiCoder/cc-haha/network/members)
|
||||
[](https://github.com/NanmiCoder/cc-haha/issues)
|
||||
[](https://github.com/NanmiCoder/cc-haha/pulls)
|
||||
[](https://github.com/NanmiCoder/cc-haha/blob/main/LICENSE)
|
||||
[](README.md)
|
||||
[](README.en.md)
|
||||
|
||||
</div>
|
||||
|
||||
基于 Claude Code 泄露源码修复的**本地可运行版本**，支持接入任意 Anthropic 兼容 API（如 MiniMax、OpenRouter 等）。
|
||||
|
||||
> 原始泄露源码无法直接运行。本仓库修复了启动链路中的多个阻塞问题，使完整的 Ink TUI 交互界面可以在本地工作。
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/00runtime.png" alt="运行截图" width="800">
|
||||
<img src="docs/images/00runtime.png" alt="运行截图" width="800">
|
||||
</p>
|
||||
|
||||
## 目录
|
||||
|
||||
- [功能](#功能)
|
||||
- [架构概览](#架构概览)
|
||||
- [快速开始](#快速开始)
|
||||
- [环境变量说明](#环境变量说明)
|
||||
- [降级模式](#降级模式)
|
||||
- [Computer Use 桌面控制](#computer-use-桌面控制)
|
||||
- [记忆系统](#记忆系统)
|
||||
- [常见问题](#常见问题)
|
||||
- [相对于原始泄露源码的修复](#相对于原始泄露源码的修复)
|
||||
- [项目结构](#项目结构)
|
||||
- [技术栈](#技术栈)
|
||||
<p align="center">
|
||||
<a href="#功能">功能</a> · <a href="#架构概览">架构概览</a> · <a href="#快速开始">快速开始</a> · <a href="docs/guide/env-vars.md">环境变量</a> · <a href="docs/guide/faq.md">FAQ</a> · <a href="docs/guide/global-usage.md">全局使用</a> · <a href="#更多文档">更多文档</a>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
@ -31,12 +31,10 @@
|
||||
- 完整的 Ink TUI 交互界面（与官方 Claude Code 一致）
|
||||
- `--print` 无头模式（脚本/CI 场景）
|
||||
- 支持 MCP 服务器、插件、Skills
|
||||
- 支持自定义 API 端点和模型（[第三方模型使用指南](docs/third-party-models.md)）
|
||||
- **Computer Use 桌面控制**（截屏、鼠标、键盘、应用管理）— [使用指南](docs/computer-use.md)
|
||||
- **记忆系统**（跨会话持久化记忆，自动提取 + 智能检索）— [使用指南](docs/memory/01-usage-guide.md) | [实现原理](docs/memory/02-implementation.md)
|
||||
- 降级 Recovery CLI 模式
|
||||
|
||||
> **Computer Use 说明**：本项目包含**魔改版的 Computer Use** 功能。官方实现依赖 Anthropic 私有原生模块，我们替换了整个底层操作层，使用 Python bridge（`pyautogui` + `mss` + `pyobjc`）实现，使得任何人都可以在 macOS 上使用。详见 [Computer Use 功能指南](docs/computer-use.md)。
|
||||
- 支持自定义 API 端点和模型（[第三方模型使用指南](docs/guide/third-party-models.md)）
|
||||
- **Computer Use 桌面控制** — [使用指南](docs/features/computer-use.md)
|
||||
- **记忆系统**（跨会话持久化记忆）— [使用指南](docs/memory/01-usage-guide.md)
|
||||
- 降级 Recovery CLI 模式（`CLAUDE_CODE_FORCE_RECOVERY_CLI=1 ./bin/claude-haha`）
|
||||
|
||||
---
|
||||
|
||||
@ -44,16 +42,16 @@
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="25%"><img src="docs/01-overall-architecture.png" alt="整体架构"><br><b>整体架构</b></td>
|
||||
<td align="center" width="25%"><img src="docs/02-request-lifecycle.png" alt="请求生命周期"><br><b>请求生命周期</b></td>
|
||||
<td align="center" width="25%"><img src="docs/03-tool-system.png" alt="工具系统"><br><b>工具系统</b></td>
|
||||
<td align="center" width="25%"><img src="docs/04-multi-agent.png" alt="多 Agent 架构"><br><b>多 Agent 架构</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/01-overall-architecture.png" alt="整体架构"><br><b>整体架构</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/02-request-lifecycle.png" alt="请求生命周期"><br><b>请求生命周期</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/03-tool-system.png" alt="工具系统"><br><b>工具系统</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/04-multi-agent.png" alt="多 Agent 架构"><br><b>多 Agent 架构</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="25%"><img src="docs/05-terminal-ui.png" alt="终端 UI"><br><b>终端 UI</b></td>
|
||||
<td align="center" width="25%"><img src="docs/06-permission-security.png" alt="权限与安全"><br><b>权限与安全</b></td>
|
||||
<td align="center" width="25%"><img src="docs/07-services-layer.png" alt="服务层"><br><b>服务层</b></td>
|
||||
<td align="center" width="25%"><img src="docs/08-state-data-flow.png" alt="状态与数据流"><br><b>状态与数据流</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/05-terminal-ui.png" alt="终端 UI"><br><b>终端 UI</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/06-permission-security.png" alt="权限与安全"><br><b>权限与安全</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/07-services-layer.png" alt="服务层"><br><b>服务层</b></td>
|
||||
<td align="center" width="25%"><img src="docs/images/08-state-data-flow.png" alt="状态与数据流"><br><b>状态与数据流</b></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
@ -63,238 +61,55 @@
|
||||
|
||||
### 1. 安装 Bun
|
||||
|
||||
本项目运行依赖 [Bun](https://bun.sh)。如果你的电脑还没有安装 Bun，可以先执行下面任一方式：
|
||||
|
||||
```bash
|
||||
# macOS / Linux（官方安装脚本）
|
||||
# macOS / Linux
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
```
|
||||
|
||||
如果在精简版 Linux 环境里提示 `unzip is required to install bun`，先安装 `unzip`：
|
||||
|
||||
```bash
|
||||
# Ubuntu / Debian
|
||||
apt update && apt install -y unzip
|
||||
```
|
||||
|
||||
```bash
|
||||
# macOS（Homebrew）
|
||||
# macOS (Homebrew)
|
||||
brew install bun
|
||||
```
|
||||
|
||||
```powershell
|
||||
# Windows（PowerShell）
|
||||
# Windows (PowerShell)
|
||||
powershell -c "irm bun.sh/install.ps1 | iex"
|
||||
```
|
||||
|
||||
安装完成后，重新打开终端并确认：
|
||||
> 精简版 Linux 如提示 `unzip is required`，先运行 `apt update && apt install -y unzip`
|
||||
|
||||
```bash
|
||||
bun --version
|
||||
```
|
||||
|
||||
### 2. 安装项目依赖
|
||||
### 2. 安装依赖并配置
|
||||
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
### 3. 配置环境变量
|
||||
|
||||
复制示例文件并填入你的 API Key：
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# 编辑 .env 填入你的 API Key，详见 docs/guide/env-vars.md
|
||||
```
|
||||
|
||||
编辑 `.env`（以下示例使用 [MiniMax](https://platform.minimaxi.com/subscribe/token-plan?code=1TG2Cseab2&source=link) 作为 API 提供商，也可替换为其他兼容服务）：
|
||||
|
||||
```env
|
||||
# API 认证（二选一）
|
||||
ANTHROPIC_API_KEY=sk-xxx # 标准 API Key（x-api-key 头）
|
||||
ANTHROPIC_AUTH_TOKEN=sk-xxx # Bearer Token（Authorization 头）
|
||||
|
||||
# API 端点（可选，默认 Anthropic 官方）
|
||||
ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
|
||||
|
||||
# 模型配置
|
||||
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
|
||||
|
||||
# 超时（毫秒）
|
||||
API_TIMEOUT_MS=3000000
|
||||
|
||||
# 禁用遥测和非必要网络请求
|
||||
DISABLE_TELEMETRY=1
|
||||
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
|
||||
```
|
||||
|
||||
> **提示**：除了 `.env` 文件，你也可以通过 `~/.claude/settings.json` 的 `env` 字段配置环境变量。这与官方 Claude Code 的配置方式一致：
|
||||
>
|
||||
> ```json
|
||||
> {
|
||||
> "env": {
|
||||
> "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
|
||||
> "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
|
||||
> "ANTHROPIC_MODEL": "MiniMax-M2.7-highspeed"
|
||||
> }
|
||||
> }
|
||||
> ```
|
||||
>
|
||||
> 配置优先级：环境变量 > `.env` 文件 > `~/.claude/settings.json`
|
||||
|
||||
### 4. 启动
|
||||
### 3. 启动
|
||||
|
||||
#### macOS / Linux
|
||||
|
||||
```bash
|
||||
# 交互 TUI 模式（完整界面）
|
||||
./bin/claude-haha
|
||||
|
||||
# 无头模式（单次问答）
|
||||
./bin/claude-haha -p "your prompt here"
|
||||
|
||||
# 管道输入
|
||||
echo "explain this code" | ./bin/claude-haha -p
|
||||
|
||||
# 查看所有选项
|
||||
./bin/claude-haha --help
|
||||
./bin/claude-haha # 交互 TUI 模式
|
||||
./bin/claude-haha -p "your prompt here" # 无头模式
|
||||
./bin/claude-haha --help # 查看所有选项
|
||||
```
|
||||
|
||||
#### Windows
|
||||
|
||||
> **前置要求**：必须安装 [Git for Windows](https://git-scm.com/download/win)（提供 Git Bash，项目内部 Shell 执行依赖它）。
|
||||
|
||||
Windows 下启动脚本 `bin/claude-haha` 是 bash 脚本，无法在 cmd / PowerShell 中直接运行。请使用以下方式：
|
||||
|
||||
**方式一：PowerShell / cmd 直接调用 Bun（推荐）**
|
||||
> **前置要求**：必须安装 [Git for Windows](https://git-scm.com/download/win)
|
||||
|
||||
```powershell
|
||||
# 交互 TUI 模式
|
||||
# PowerShell / cmd 直接调用 Bun
|
||||
bun --env-file=.env ./src/entrypoints/cli.tsx
|
||||
|
||||
# 无头模式
|
||||
bun --env-file=.env ./src/entrypoints/cli.tsx -p "your prompt here"
|
||||
|
||||
# 降级 Recovery CLI
|
||||
bun --env-file=.env ./src/localRecoveryCli.ts
|
||||
```
|
||||
|
||||
**方式二：Git Bash 中运行**
|
||||
|
||||
```bash
|
||||
# 在 Git Bash 终端中，与 macOS/Linux 用法一致
|
||||
# 或在 Git Bash 中运行
|
||||
./bin/claude-haha
|
||||
```
|
||||
|
||||
> **注意**：部分功能（语音输入、Computer Use、Sandbox 隔离等）在 Windows 上不可用，不影响核心 TUI 交互。
|
||||
### 4. 全局使用（可选）
|
||||
|
||||
---
|
||||
|
||||
## 环境变量说明
|
||||
|
||||
| 变量 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `ANTHROPIC_API_KEY` | 二选一 | API Key，通过 `x-api-key` 头发送 |
|
||||
| `ANTHROPIC_AUTH_TOKEN` | 二选一 | Auth Token，通过 `Authorization: Bearer` 头发送 |
|
||||
| `ANTHROPIC_BASE_URL` | 否 | 自定义 API 端点，默认 Anthropic 官方 |
|
||||
| `ANTHROPIC_MODEL` | 否 | 默认模型 |
|
||||
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 否 | Sonnet 级别模型映射 |
|
||||
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 否 | Haiku 级别模型映射 |
|
||||
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | 否 | Opus 级别模型映射 |
|
||||
| `API_TIMEOUT_MS` | 否 | API 请求超时，默认 600000 (10min) |
|
||||
| `DISABLE_TELEMETRY` | 否 | 设为 `1` 禁用遥测 |
|
||||
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 否 | 设为 `1` 禁用非必要网络请求 |
|
||||
|
||||
---
|
||||
|
||||
## 降级模式
|
||||
|
||||
如果完整 TUI 出现问题，可以使用简化版 readline 交互模式：
|
||||
将 `bin/` 加入 PATH 后可在任意目录启动，详见 [全局使用指南](docs/guide/global-usage.md)：
|
||||
|
||||
```bash
|
||||
CLAUDE_CODE_FORCE_RECOVERY_CLI=1 ./bin/claude-haha
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Computer Use 桌面控制
|
||||
|
||||
本项目启用并改造了 Claude Code 的 Computer Use 功能（内部代号 "Chicago"），让 AI 模型可以直接控制你的 macOS 桌面——截屏、鼠标点击、键盘输入、应用管理。
|
||||
|
||||
**底层改造**：官方实现依赖 Anthropic 私有原生模块（`@ant/computer-use-swift`、`@ant/computer-use-input`），本项目用 Python bridge 完全替代，使用 `pyautogui`（鼠标键盘）、`mss`（截图）、`pyobjc`（macOS API），无需任何闭源二进制。
|
||||
|
||||
```bash
|
||||
# 确保有 Python 3 和 macOS 辅助功能/屏幕录制权限，然后直接使用：
|
||||
./bin/claude-haha
|
||||
> 帮我截个屏
|
||||
> 打开网易云音乐搜索一首歌
|
||||
```
|
||||
|
||||
详细说明、支持的设备列表、技术架构和尝试过的方案请参考：**[Computer Use 功能指南](docs/computer-use.md)**
|
||||
|
||||
---
|
||||
|
||||
## 记忆系统
|
||||
|
||||
Claude Code 内置了一套**基于文件的持久化记忆系统**，能够跨会话积累对用户和项目的理解。核心理念：只记住无法从代码中推断出来的东西。
|
||||
|
||||
**四种记忆类型**：
|
||||
|
||||
| 类型 | 用途 | 示例 |
|
||||
|------|------|------|
|
||||
| **User** | 用户角色、技能、偏好 | "深厚 Go 经验，React 新手" |
|
||||
| **Feedback** | 对 Claude 工作方式的纠正或肯定 | "不要 mock 数据库" |
|
||||
| **Project** | 无法从代码推导的项目上下文 | "周四后冻结非关键合并" |
|
||||
| **Reference** | 外部系统的指针 | "Bug 追踪在 Linear INGEST 项目" |
|
||||
|
||||
**核心能力**：
|
||||
|
||||
- **自动提取**：每次对话结束后，后台分叉代理自动分析并保存值得记住的信息
|
||||
- **智能检索**：用户提问时，Sonnet 模型从所有记忆中选择最相关的（最多 5 个）注入上下文
|
||||
- **新鲜度管理**：超过 1 天的记忆附带陈旧警告，引用前自动验证
|
||||
|
||||
详细文档：**[使用指南](docs/memory/01-usage-guide.md)** | **[实现原理](docs/memory/02-implementation.md)**
|
||||
|
||||
---
|
||||
|
||||
## 相对于原始泄露源码的修复
|
||||
|
||||
泄露的源码无法直接运行，主要修复了以下问题：
|
||||
|
||||
| 问题 | 根因 | 修复 |
|
||||
|------|------|------|
|
||||
| TUI 不启动 | 入口脚本把无参数启动路由到了 recovery CLI | 恢复走 `cli.tsx` 完整入口 |
|
||||
| 启动卡死 | `verify` skill 导入缺失的 `.md` 文件，Bun text loader 无限挂起 | 创建 stub `.md` 文件 |
|
||||
| `--print` 卡死 | `filePersistence/types.ts` 缺失 | 创建类型桩文件 |
|
||||
| `--print` 卡死 | `ultraplan/prompt.txt` 缺失 | 创建资源桩文件 |
|
||||
| **Enter 键无响应** | `modifiers-napi` native 包缺失，`isModifierPressed()` 抛异常导致 `handleEnter` 中断，`onSubmit` 永远不执行 | 加 try-catch 容错 |
|
||||
| setup 被跳过 | `preload.ts` 自动设置 `LOCAL_RECOVERY=1` 跳过全部初始化 | 移除默认设置 |
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
bin/claude-haha # 入口脚本
|
||||
preload.ts # Bun preload（设置 MACRO 全局变量）
|
||||
.env.example # 环境变量模板
|
||||
src/
|
||||
├── entrypoints/cli.tsx # CLI 主入口
|
||||
├── main.tsx # TUI 主逻辑（Commander.js + React/Ink）
|
||||
├── localRecoveryCli.ts # 降级 Recovery CLI
|
||||
├── setup.ts # 启动初始化
|
||||
├── screens/REPL.tsx # 交互 REPL 界面
|
||||
├── ink/ # Ink 终端渲染引擎
|
||||
├── components/ # UI 组件
|
||||
├── tools/ # Agent 工具（Bash, Edit, Grep 等）
|
||||
├── commands/ # 斜杠命令（/commit, /review 等）
|
||||
├── skills/ # Skill 系统
|
||||
├── services/ # 服务层（API, MCP, OAuth 等）
|
||||
├── hooks/ # React hooks
|
||||
└── utils/ # 工具函数
|
||||
export PATH="$HOME/path/to/claude-code-haha/bin:$PATH"
|
||||
```
|
||||
|
||||
---
|
||||
@ -312,39 +127,18 @@ src/
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
## 更多文档
|
||||
|
||||
### Q: `undefined is not an object (evaluating 'usage.input_tokens')`
|
||||
|
||||
**原因**：`ANTHROPIC_BASE_URL` 配置不正确，API 端点返回的不是 Anthropic 协议格式的 JSON，而是 HTML 页面或其他格式。
|
||||
|
||||
本项目使用 **Anthropic Messages API 协议**，`ANTHROPIC_BASE_URL` 必须指向一个兼容 Anthropic `/v1/messages` 接口的端点。Anthropic SDK 会自动在 base URL 后面拼接 `/v1/messages`，所以：
|
||||
|
||||
- MiniMax：`ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic` ✅
|
||||
- OpenRouter：`ANTHROPIC_BASE_URL=https://openrouter.ai/api` ✅
|
||||
- OpenRouter 错误写法：`ANTHROPIC_BASE_URL=https://openrouter.ai/anthropic` ❌（返回 HTML）
|
||||
|
||||
如果你的模型供应商只支持 OpenAI 协议，需要通过 LiteLLM 等代理做协议转换，详见 [第三方模型使用指南](docs/third-party-models.md)。
|
||||
|
||||
### Q: `Cannot find package 'bundle'`
|
||||
|
||||
```
|
||||
error: Cannot find package 'bundle' from '.../claude-code-haha/src/entrypoints/cli.tsx'
|
||||
```
|
||||
|
||||
**原因**：Bun 版本过低，不支持项目所需的 `bun:bundle` 等内置模块。
|
||||
|
||||
**解决**：升级 Bun 到最新版本：
|
||||
|
||||
```bash
|
||||
bun upgrade
|
||||
```
|
||||
|
||||
### Q: 怎么接入 OpenAI / DeepSeek / Ollama 等非 Anthropic 模型？
|
||||
|
||||
本项目只支持 Anthropic 协议。如果模型供应商不直接支持 Anthropic 协议，需要用 [LiteLLM](https://github.com/BerriAI/litellm) 等代理做协议转换（OpenAI → Anthropic）。
|
||||
|
||||
详细配置步骤请参考：[第三方模型使用指南](docs/third-party-models.md)
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [环境变量](docs/guide/env-vars.md) | 完整环境变量参考和配置方式 |
|
||||
| [第三方模型](docs/guide/third-party-models.md) | 接入 OpenAI / DeepSeek / Ollama 等非 Anthropic 模型 |
|
||||
| [Computer Use](docs/features/computer-use.md) | 桌面控制功能（截屏、鼠标、键盘） |
|
||||
| [记忆系统](docs/memory/01-usage-guide.md) | 跨会话持久化记忆的使用与实现 |
|
||||
| [全局使用](docs/guide/global-usage.md) | 在任意目录启动 claude-haha |
|
||||
| [常见问题](docs/guide/faq.md) | 常见错误排查 |
|
||||
| [源码修复记录](docs/reference/fixes.md) | 相对于原始泄露源码的修复内容 |
|
||||
| [项目结构](docs/reference/project-structure.md) | 代码目录结构说明 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
62
docs/guide/env-vars.en.md
Normal file
62
docs/guide/env-vars.en.md
Normal file
@ -0,0 +1,62 @@
|
||||
# Environment Variables
|
||||
|
||||
<p align="right"><a href="./env-vars.md">中文</a> | <a href="../../README.en.md">Back to README</a></p>
|
||||
|
||||
| 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 |
|
||||
|
||||
## Configuration Methods
|
||||
|
||||
### Option 1: `.env` File
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit `.env` (the example below uses [MiniMax](https://platform.minimaxi.com/subscribe/token-plan?code=1TG2Cseab2&source=link) as the API provider — you can replace it with any compatible service):
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### Option 2: `~/.claude/settings.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_AUTH_TOKEN": "sk-xxx",
|
||||
"ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
|
||||
"ANTHROPIC_MODEL": "MiniMax-M2.7-highspeed"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> Priority: Environment variables > `.env` file > `~/.claude/settings.json`
|
||||
62
docs/guide/env-vars.md
Normal file
62
docs/guide/env-vars.md
Normal file
@ -0,0 +1,62 @@
|
||||
# 环境变量说明
|
||||
|
||||
<p align="right"><a href="./env-vars.en.md">English</a> | <a href="../../README.md">返回 README</a></p>
|
||||
|
||||
| 变量 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `ANTHROPIC_API_KEY` | 二选一 | API Key，通过 `x-api-key` 头发送 |
|
||||
| `ANTHROPIC_AUTH_TOKEN` | 二选一 | Auth Token，通过 `Authorization: Bearer` 头发送 |
|
||||
| `ANTHROPIC_BASE_URL` | 否 | 自定义 API 端点，默认 Anthropic 官方 |
|
||||
| `ANTHROPIC_MODEL` | 否 | 默认模型 |
|
||||
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 否 | Sonnet 级别模型映射 |
|
||||
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 否 | Haiku 级别模型映射 |
|
||||
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | 否 | Opus 级别模型映射 |
|
||||
| `API_TIMEOUT_MS` | 否 | API 请求超时，默认 600000 (10min) |
|
||||
| `DISABLE_TELEMETRY` | 否 | 设为 `1` 禁用遥测 |
|
||||
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 否 | 设为 `1` 禁用非必要网络请求 |
|
||||
|
||||
## 配置方式
|
||||
|
||||
### 方式一：`.env` 文件
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
编辑 `.env`（以下示例使用 [MiniMax](https://platform.minimaxi.com/subscribe/token-plan?code=1TG2Cseab2&source=link) 作为 API 提供商，也可替换为其他兼容服务）：
|
||||
|
||||
```env
|
||||
# API 认证（二选一）
|
||||
ANTHROPIC_API_KEY=sk-xxx # 标准 API Key（x-api-key 头）
|
||||
ANTHROPIC_AUTH_TOKEN=sk-xxx # Bearer Token（Authorization 头）
|
||||
|
||||
# API 端点（可选，默认 Anthropic 官方）
|
||||
ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
|
||||
|
||||
# 模型配置
|
||||
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
|
||||
|
||||
# 超时（毫秒）
|
||||
API_TIMEOUT_MS=3000000
|
||||
|
||||
# 禁用遥测和非必要网络请求
|
||||
DISABLE_TELEMETRY=1
|
||||
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
|
||||
```
|
||||
|
||||
### 方式二：`~/.claude/settings.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_AUTH_TOKEN": "sk-xxx",
|
||||
"ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
|
||||
"ANTHROPIC_MODEL": "MiniMax-M2.7-highspeed"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 配置优先级：环境变量 > `.env` 文件 > `~/.claude/settings.json`
|
||||
35
docs/guide/faq.en.md
Normal file
35
docs/guide/faq.en.md
Normal file
@ -0,0 +1,35 @@
|
||||
# FAQ
|
||||
|
||||
<p align="right"><a href="./faq.md">中文</a> | <a href="../../README.en.md">Back to README</a></p>
|
||||
|
||||
## Q: `undefined is not an object (evaluating 'usage.input_tokens')`
|
||||
|
||||
**Cause**: `ANTHROPIC_BASE_URL` is misconfigured. The API endpoint is returning HTML or another non-JSON format instead of a valid Anthropic protocol response.
|
||||
|
||||
This project uses the **Anthropic Messages API protocol**. `ANTHROPIC_BASE_URL` must point to an endpoint compatible with Anthropic's `/v1/messages` interface. The Anthropic SDK automatically appends `/v1/messages` to the base URL, so:
|
||||
|
||||
- MiniMax: `ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic` ✅
|
||||
- OpenRouter: `ANTHROPIC_BASE_URL=https://openrouter.ai/api` ✅
|
||||
- OpenRouter (wrong): `ANTHROPIC_BASE_URL=https://openrouter.ai/anthropic` ❌ (returns HTML)
|
||||
|
||||
If your model provider only supports the OpenAI protocol, you need a proxy like LiteLLM for protocol translation. See the [Third-Party Models Guide](./third-party-models.en.md).
|
||||
|
||||
## Q: `Cannot find package 'bundle'`
|
||||
|
||||
```
|
||||
error: Cannot find package 'bundle' from '.../claude-code-haha/src/entrypoints/cli.tsx'
|
||||
```
|
||||
|
||||
**Cause**: Your Bun version is too old and doesn't support the required `bun:bundle` built-in module.
|
||||
|
||||
**Fix**: Upgrade Bun to the latest version:
|
||||
|
||||
```bash
|
||||
bun upgrade
|
||||
```
|
||||
|
||||
## Q: How to use OpenAI / DeepSeek / Ollama or other non-Anthropic models?
|
||||
|
||||
This project only supports the Anthropic protocol. If your model provider doesn't natively support the Anthropic protocol, you need a proxy like [LiteLLM](https://github.com/BerriAI/litellm) for protocol translation (OpenAI → Anthropic).
|
||||
|
||||
See the [Third-Party Models Guide](./third-party-models.en.md) for detailed setup instructions.
|
||||
35
docs/guide/faq.md
Normal file
35
docs/guide/faq.md
Normal file
@ -0,0 +1,35 @@
|
||||
# 常见问题
|
||||
|
||||
<p align="right"><a href="./faq.en.md">English</a> | <a href="../../README.md">返回 README</a></p>
|
||||
|
||||
## Q: `undefined is not an object (evaluating 'usage.input_tokens')`
|
||||
|
||||
**原因**：`ANTHROPIC_BASE_URL` 配置不正确，API 端点返回的不是 Anthropic 协议格式的 JSON，而是 HTML 页面或其他格式。
|
||||
|
||||
本项目使用 **Anthropic Messages API 协议**，`ANTHROPIC_BASE_URL` 必须指向一个兼容 Anthropic `/v1/messages` 接口的端点。Anthropic SDK 会自动在 base URL 后面拼接 `/v1/messages`，所以：
|
||||
|
||||
- MiniMax：`ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic` ✅
|
||||
- OpenRouter：`ANTHROPIC_BASE_URL=https://openrouter.ai/api` ✅
|
||||
- OpenRouter 错误写法：`ANTHROPIC_BASE_URL=https://openrouter.ai/anthropic` ❌（返回 HTML）
|
||||
|
||||
如果你的模型供应商只支持 OpenAI 协议，需要通过 LiteLLM 等代理做协议转换，详见 [第三方模型使用指南](./third-party-models.md)。
|
||||
|
||||
## Q: `Cannot find package 'bundle'`
|
||||
|
||||
```
|
||||
error: Cannot find package 'bundle' from '.../claude-code-haha/src/entrypoints/cli.tsx'
|
||||
```
|
||||
|
||||
**原因**：Bun 版本过低，不支持项目所需的 `bun:bundle` 等内置模块。
|
||||
|
||||
**解决**：升级 Bun 到最新版本：
|
||||
|
||||
```bash
|
||||
bun upgrade
|
||||
```
|
||||
|
||||
## Q: 怎么接入 OpenAI / DeepSeek / Ollama 等非 Anthropic 模型？
|
||||
|
||||
本项目只支持 Anthropic 协议。如果模型供应商不直接支持 Anthropic 协议，需要用 [LiteLLM](https://github.com/BerriAI/litellm) 等代理做协议转换（OpenAI → Anthropic）。
|
||||
|
||||
详细配置步骤请参考：[第三方模型使用指南](./third-party-models.md)
|
||||
41
docs/guide/global-usage.en.md
Normal file
41
docs/guide/global-usage.en.md
Normal file
@ -0,0 +1,41 @@
|
||||
# Global Usage (Run from Any Directory)
|
||||
|
||||
<p align="right"><a href="./global-usage.md">中文</a> | <a href="../../README.en.md">Back to README</a></p>
|
||||
|
||||
If you want to run `claude-haha` directly from any project directory, set up one of the following. Once configured, `claude-haha` will automatically recognize your current working directory.
|
||||
|
||||
## macOS / Linux
|
||||
|
||||
Add to `~/.bashrc` or `~/.zshrc`:
|
||||
|
||||
```bash
|
||||
# Option 1: Add to PATH (recommended)
|
||||
export PATH="$HOME/path/to/claude-code-haha/bin:$PATH"
|
||||
|
||||
# Option 2: Alias
|
||||
alias claude-haha="$HOME/path/to/claude-code-haha/bin/claude-haha"
|
||||
```
|
||||
|
||||
Then reload the config:
|
||||
|
||||
```bash
|
||||
source ~/.bashrc # or source ~/.zshrc
|
||||
```
|
||||
|
||||
## Windows (Git Bash)
|
||||
|
||||
Add to `~/.bashrc`:
|
||||
|
||||
```bash
|
||||
export PATH="$HOME/path/to/claude-code-haha/bin:$PATH"
|
||||
```
|
||||
|
||||
## Verify
|
||||
|
||||
After setup, navigate to any project directory and test:
|
||||
|
||||
```bash
|
||||
cd ~/your-other-project
|
||||
claude-haha
|
||||
# Ask "What is the current directory?" — it should show ~/your-other-project
|
||||
```
|
||||
41
docs/guide/global-usage.md
Normal file
41
docs/guide/global-usage.md
Normal file
@ -0,0 +1,41 @@
|
||||
# 全局使用（任意目录启动）
|
||||
|
||||
<p align="right"><a href="./global-usage.en.md">English</a> | <a href="../../README.md">返回 README</a></p>
|
||||
|
||||
如果你希望在任意项目目录直接运行 `claude-haha`，可以通过以下方式配置。配置完成后，`claude-haha` 会自动识别你当前所在的工作目录。
|
||||
|
||||
## macOS / Linux
|
||||
|
||||
在 `~/.bashrc` 或 `~/.zshrc` 中添加：
|
||||
|
||||
```bash
|
||||
# 方式一：添加 PATH（推荐）
|
||||
export PATH="$HOME/path/to/claude-code-haha/bin:$PATH"
|
||||
|
||||
# 方式二：alias
|
||||
alias claude-haha="$HOME/path/to/claude-code-haha/bin/claude-haha"
|
||||
```
|
||||
|
||||
然后重新加载配置：
|
||||
|
||||
```bash
|
||||
source ~/.bashrc # 或 source ~/.zshrc
|
||||
```
|
||||
|
||||
## Windows (Git Bash)
|
||||
|
||||
在 `~/.bashrc` 中添加：
|
||||
|
||||
```bash
|
||||
export PATH="$HOME/path/to/claude-code-haha/bin:$PATH"
|
||||
```
|
||||
|
||||
## 验证
|
||||
|
||||
配置完成后，进入任意项目目录测试：
|
||||
|
||||
```bash
|
||||
cd ~/your-other-project
|
||||
claude-haha
|
||||
# 启动后询问「当前目录是什么？」，应显示 ~/your-other-project
|
||||
```
|
||||
|
Before Width: | Height: | Size: 959 KiB After Width: | Height: | Size: 959 KiB |
|
Before Width: | Height: | Size: 889 KiB After Width: | Height: | Size: 889 KiB |
|
Before Width: | Height: | Size: 626 KiB After Width: | Height: | Size: 626 KiB |
|
Before Width: | Height: | Size: 923 KiB After Width: | Height: | Size: 923 KiB |
|
Before Width: | Height: | Size: 1.3 MiB After Width: | Height: | Size: 1.3 MiB |
|
Before Width: | Height: | Size: 1.0 MiB After Width: | Height: | Size: 1.0 MiB |
|
Before Width: | Height: | Size: 1.1 MiB After Width: | Height: | Size: 1.1 MiB |
|
Before Width: | Height: | Size: 698 KiB After Width: | Height: | Size: 698 KiB |
|
Before Width: | Height: | Size: 860 KiB After Width: | Height: | Size: 860 KiB |
14
docs/reference/fixes.en.md
Normal file
14
docs/reference/fixes.en.md
Normal file
@ -0,0 +1,14 @@
|
||||
# Fixes Compared with the Original Leaked Source
|
||||
|
||||
<p align="right"><a href="./fixes.md">中文</a> | <a href="../../README.en.md">Back to README</a></p>
|
||||
|
||||
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 |
|
||||
14
docs/reference/fixes.md
Normal file
14
docs/reference/fixes.md
Normal file
@ -0,0 +1,14 @@
|
||||
# 相对于原始泄露源码的修复
|
||||
|
||||
<p align="right"><a href="./fixes.en.md">English</a> | <a href="../../README.md">返回 README</a></p>
|
||||
|
||||
泄露的源码无法直接运行，主要修复了以下问题：
|
||||
|
||||
| 问题 | 根因 | 修复 |
|
||||
|------|------|------|
|
||||
| TUI 不启动 | 入口脚本把无参数启动路由到了 recovery CLI | 恢复走 `cli.tsx` 完整入口 |
|
||||
| 启动卡死 | `verify` skill 导入缺失的 `.md` 文件，Bun text loader 无限挂起 | 创建 stub `.md` 文件 |
|
||||
| `--print` 卡死 | `filePersistence/types.ts` 缺失 | 创建类型桩文件 |
|
||||
| `--print` 卡死 | `ultraplan/prompt.txt` 缺失 | 创建资源桩文件 |
|
||||
| **Enter 键无响应** | `modifiers-napi` native 包缺失，`isModifierPressed()` 抛异常导致 `handleEnter` 中断，`onSubmit` 永远不执行 | 加 try-catch 容错 |
|
||||
| setup 被跳过 | `preload.ts` 自动设置 `LOCAL_RECOVERY=1` 跳过全部初始化 | 移除默认设置 |
|
||||
23
docs/reference/project-structure.en.md
Normal file
23
docs/reference/project-structure.en.md
Normal file
@ -0,0 +1,23 @@
|
||||
# Project Structure
|
||||
|
||||
<p align="right"><a href="./project-structure.md">中文</a> | <a href="../../README.en.md">Back to README</a></p>
|
||||
|
||||
```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
|
||||
```
|
||||
23
docs/reference/project-structure.md
Normal file
23
docs/reference/project-structure.md
Normal file
@ -0,0 +1,23 @@
|
||||
# 项目结构
|
||||
|
||||
<p align="right"><a href="./project-structure.en.md">English</a> | <a href="../../README.md">返回 README</a></p>
|
||||
|
||||
```
|
||||
bin/claude-haha # 入口脚本
|
||||
preload.ts # Bun preload（设置 MACRO 全局变量）
|
||||
.env.example # 环境变量模板
|
||||
src/
|
||||
├── entrypoints/cli.tsx # CLI 主入口
|
||||
├── main.tsx # TUI 主逻辑（Commander.js + React/Ink）
|
||||
├── localRecoveryCli.ts # 降级 Recovery CLI
|
||||
├── setup.ts # 启动初始化
|
||||
├── screens/REPL.tsx # 交互 REPL 界面
|
||||
├── ink/ # Ink 终端渲染引擎
|
||||
├── components/ # UI 组件
|
||||
├── tools/ # Agent 工具（Bash, Edit, Grep 等）
|
||||
├── commands/ # 斜杠命令（/commit, /review 等）
|
||||
├── skills/ # Skill 系统
|
||||
├── services/ # 服务层（API, MCP, OAuth 等）
|
||||
├── hooks/ # React hooks
|
||||
└── utils/ # 工具函数
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user