# LHY Code 运行教程

> 本教程详细介绍如何在 Windows 环境下运行 LHY Code。

## 目录

1. [前置要求](#1-前置要求)
2. [安装 Bun 运行时](#2-安装-bun-运行时)
3. [克隆与依赖安装](#3-克隆与依赖安装)
4. [环境配置](#4-环境配置)
5. [运行方式](#5-运行方式)
6. [高级配置](#6-高级配置)
7. [常见问题](#7-常见问题)

---

## 1. 前置要求

### 系统要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Windows 10/11 (推荐) |
| 终端 | PowerShell 5.1+ 或 Windows Terminal |
| Git | Git for Windows (用于 Shell 命令执行) |
| 网络 | 能够访问你的 API 端点 |

### 必备软件

1. **Git for Windows**
   - 下载地址：https://git-scm.com/download/win
   - 安装时选择 "Use Git from Bash"

2. **PowerShell 7+**（可选但推荐）
   - 下载地址：https://github.com/PowerShell/PowerShell/releases
   - 项目已配置 PowerShell 7.5.4 地址：D:\PowerShell\PowerShell-7.5.4

---

## 2. 安装 Bun 运行时

### 方法一：官方脚本（推荐）

在 PowerShell 中执行：

```powershell
powershell -c "irm bun.sh/install.ps1 | iex"
```

### 方法二：Scoop 安装

```powershell
scoop install bun
```

### 验证安装

```powershell
bun --version
```

应显示类似 `Bun v1.x.x` 的版本信息。

---

## 3. 克隆与依赖安装

### 克隆项目

```powershell
git clone <仓库地址> lhy-code
cd lhy-code
```

### 安装依赖

```powershell
bun install
```

---

## 4. 环境配置

### 4.1 复制环境变量模板

```powershell
cp .env.example .env
```

### 4.2 编辑 .env 文件

使用文本编辑器打开 `.env` 文件，配置以下内容：

```env
# ====================
# API 认证配置（必填）
# ====================

# 方式一：使用 API Key（通过 x-api-key 头发送）
ANTHROPIC_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

# 方式二：使用 Auth Token（通过 Authorization: Bearer 头发送）
# ANTHROPIC_AUTH_TOKEN=sk-xxxxxxxxxxxxxxxxxxxxxxxx

# ====================
# API 端点配置（必填）
# ====================

# Anthropic 官方端点
# ANTHROPIC_BASE_URL=https://api.anthropic.com

# MiniMax 端点（示例）
ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic

# OpenRouter 端点（示例）
# ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1

# ====================
# 模型配置
# ====================

# 默认模型
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 请求超时（毫秒），默认 10 分钟
API_TIMEOUT_MS=3000000

# 禁用遥测（推荐设为 1）
DISABLE_TELEMETRY=1

# 禁用非必要网络请求（推荐设为 1）
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
```

### 4.3 配置说明

#### API 端点兼容性

LHY Code 支持任何 Anthropic 兼容 API，以下是常用配置：

| 服务 | BASE_URL | 模型示例 |
|------|----------|----------|
| Anthropic 官方 | `https://api.anthropic.com` | claude-sonnet-4-5 |
| MiniMax | `https://api.minimaxi.com/anthropic` | MiniMax-M2.7-highspeed |
| OpenRouter | `https://openrouter.ai/api/v1` | anthropic/claude-3.5-sonnet |
| Groq | `https://api.groq.com/openai/v1` | llama-3.1-70b-versatile |
| AWS Bedrock | （使用 AWS SDK） | Claude 3 系列 |

#### 认证方式

| 方式 | 环境变量 | 说明 |
|------|----------|------|
| API Key | `ANTHROPIC_API_KEY` | 标准方式，通过 `x-api-key` 头发送 |
| Bearer Token | `ANTHROPIC_AUTH_TOKEN` | 通过 `Authorization: Bearer` 头发送 |

---

## 5. 运行方式

### 5.1 方式一：PowerShell 直接运行（推荐）

#### 交互模式（完整 TUI）

```powershell
bun --env-file=.env ./src/entrypoints/cli.tsx
```

#### 无头模式（单次问答）

```powershell
bun --env-file=.env ./src/entrypoints/cli.tsx -p "解释这段代码的作用"
```

#### 管道输入模式

```powershell
echo "帮我写一个 Hello World" | bun --env-file=.env ./src/entrypoints/cli.tsx -p
```

#### 查看帮助

```powershell
bun --env-file=.env ./src/entrypoints/cli.tsx --help
```

### 5.2 方式二：使用启动脚本（需 Git Bash）

如果你使用 Git Bash 或 MSYS2 终端：

```bash
# 交互模式
./bin/lhy-code

# 无头模式
./bin/lhy-code -p "your prompt here"
```

> ⚠️ 注意：Windows 原生终端（cmd/PowerShell）无法直接运行 bash 脚本。

### 5.3 方式三：降级 Recovery CLI 模式

如果完整 TUI 出现问题，可以使用简化版：

```powershell
bun --env-file=.env ./src/localRecoveryCli.ts
```

或设置环境变量：

```powershell
$env:CLAUDE_CODE_FORCE_RECOVERY_CLI="1"
bun --env-file=.env ./src/entrypoints/cli.tsx
```

---

## 6. 高级配置

### 6.1 使用 Windows 原生路径

如果你希望在 Windows 路径下工作：

```powershell
# 设置工作目录
cd D:\Projects\my-project

# 运行 LHY Code
bun --env-file=.env ./src/entrypoints/cli.tsx
```

### 6.2 多会话支持

LHY Code 支持多会话管理：

```powershell
# 查看当前会话
./bin/lhy-code session list

# 切换会话
./bin/lhy-code session switch <session-id>

# 新建会话
./bin/lhy-code session new
```

### 6.3 MCP 服务器配置

LHY Code 支持 MCP (Model Context Protocol) 服务器：

```powershell
# 查看 MCP 配置
./bin/lhy-code mcp list

# 添加 MCP 服务器
./bin/lhy-code mcp add <server-name> <command> [args...]
```

### 6.4 自定义快捷键

编辑 `~/.claude/settings.json`（用户配置目录）：

```json
{
  "keybindings": {
    "abort": "Ctrl+C",
    "scrollUp": "PageUp",
    "scrollDown": "PageDown"
  }
}
```

### 6.5 代理配置

如果需要通过代理访问 API：

```env
# HTTP 代理
HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080

# 或者在 .env 中设置
ANTHROPIC_BASE_URL=http://your-proxy/anthropic/v1
```

### 6.6 日志与调试

```powershell
# 启用调试日志
$env:CLAUDE_CODE_DEBUG="1"

# 查看详细错误
bun --env-file=.env ./src/entrypoints/cli.tsx 2>&1 | tee debug.log
```

---

## 7. 常见问题

### Q1: 启动后界面卡住不动

**解决方法：**

1. 检查 API Key 是否正确配置
2. 检查网络连接是否正常
3. 尝试使用降级模式：

```powershell
$env:CLAUDE_CODE_FORCE_RECOVERY_CLI="1"
bun --env-file=.env ./src/entrypoints/cli.tsx
```

### Q2: Enter 键无响应

**原因：** `modifiers-napi` 原生模块缺失

**解决方法：**
```powershell
# 确保使用较新版本的 Bun
bun upgrade
```

### Q3: API 请求超时

**解决方法：** 增加超时时间

```env
API_TIMEOUT_MS=600000  # 10 分钟
```

### Q4: 中文显示乱码

**解决方法：** 确保终端编码为 UTF-8

```powershell
# PowerShell 设置
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

# 或使用 Windows Terminal（推荐）
```

### Q5: 权限被拒绝（Windows）

**解决方法：** 以管理员身份运行终端，或修改项目目录权限

```powershell
icacls . /grant Everyone:F /t
```

### Q6: 无法找到 Bun

**解决方法：** 确保 Bun 已正确安装并添加到 PATH

```powershell
# 检查 Bun 路径
where bun

# 如果找不到，重新安装
powershell -c "irm bun.sh/install.ps1 | iex"
```

### Q7: 工具执行被拒绝

LHY Code 默认会询问权限来执行危险操作（如删除文件、执行命令）。

**解决方法：**
- 在提示时输入 `y` 确认
- 或设置自动批准规则（谨慎使用）：

```env
CLAUDE_CODE_ALLOW_DANGEROUS_OPERATIONS=1
```

---

## 快速参考

### 常用命令

| 命令 | 说明 |
|------|------|
| `bun --env-file=.env ./src/entrypoints/cli.tsx` | 交互模式 |
| `bun --env-file=.env ./src/entrypoints/cli.tsx -p "prompt"` | 无头模式 |
| `bun --env-file=.env ./src/entrypoints/cli.tsx --version` | 查看版本 |
| `bun --env-file=.env ./src/entrypoints/cli.tsx --help` | 查看帮助 |

### 环境变量速查

| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `ANTHROPIC_API_KEY` | 是* | - | API Key |
| `ANTHROPIC_AUTH_TOKEN` | 是* | - | Auth Token（二选一） |
| `ANTHROPIC_BASE_URL` | 是 | api.anthropic.com | API 端点 |
| `ANTHROPIC_MODEL` | 否 | claude-sonnet-4-20250514 | 默认模型 |
| `DISABLE_TELEMETRY` | 否 | 0 | 设为 1 禁用遥测 |

---

*文档版本：1.0.0*
*最后更新：2026-04-02*