# CLAUDE.md

## 项目概述

LHY Code — 基于 Claude Code 泄露源码修复的**本地可运行版本**，支持接入任意 Anthropic 兼容 API（MiniMax、OpenRouter 等）。

## 技术栈

- **运行时**: [Bun](https://bun.sh)（唯一运行时，不可用 Node.js）
- **语言**: TypeScript
- **终端 UI**: React 19 + [Ink 6](https://github.com/vadimdemedes/ink)
- **CLI 解析**: Commander.js
- **API**: Anthropic SDK (`@anthropic-ai/sdk`)
- **协议**: MCP、LSP
- **构建**: Bun bundler（通过 `bun:bundle` 的 `feature()` 做 DCE）
- **包管理**: bun install（锁文件 `bun.lock`）

## 启动与运行

```bash
# 安装依赖
bun install

# 交互 TUI 模式
./bin/lhy-code

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

# 管道输入
echo "explain this code" | ./bin/lhy-code -p

# Windows 直接调用
bun --env-file=.env ./src/entrypoints/cli.tsx

# 降级 Recovery CLI
CLAUDE_CODE_FORCE_RECOVERY_CLI=1 ./bin/lhy-code
```

## 环境变量

| 变量 | 说明 |
|------|------|
| `ANTHROPIC_AUTH_TOKEN` | Bearer Token 认证（`Authorization` 头） |
| `ANTHROPIC_API_KEY` | API Key 认证（`x-api-key` 头） |
| `ANTHROPIC_BASE_URL` | 自定义 API 端点 |
| `ANTHROPIC_MODEL` | 默认模型 |
| `ANTHROPIC_DEFAULT_SONNET/HAIKU/OPUS_MODEL` | 各 tier 模型映射 |
| `API_TIMEOUT_MS` | API 超时（默认 600000） |
| `DISABLE_TELEMETRY` | 设为 `1` 禁用遥测 |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 设为 `1` 禁用非必要网络请求 |

## 项目结构

```
bin/lhy-code              # Bash 入口脚本
preload.ts                # Bun preload（设置 MACRO 全局变量）
.env                      # 环境变量（gitignore）
src/
├── entrypoints/cli.tsx   # CLI 主入口（快速路径分流、动态导入）
├── main.tsx              # TUI 主逻辑（Commander.js + React/Ink 渲染）
├── localRecoveryCli.ts   # 降级 Recovery CLI（readline 模式）
├── setup.ts              # 启动初始化（配置、OAuth、遥测等）
├── screens/REPL.tsx      # 交互 REPL 主界面
├── ink/                  # Ink 终端渲染引擎（定制版）
│   ├── components/       # Box、Text 等基础组件
│   ├── reconciler.ts     # React Reconciler
│   ├── renderer.ts       # 渲染器
│   ├── layout/           # Yoga 布局引擎
│   └── termio/           # ANSI/CSI/SGR 终端协议解析
├── components/           # UI 组件（Message、PromptInput、权限对话框等）
├── tools/                # Agent 工具系统（Bash、Edit、Grep、WebFetch、MCP 等）
├── commands/             # 斜杠命令（/commit、/review、/help 等）
├── skills/               # Skill 系统（内置 + 可扩展）
│   └── bundled/          # 内置 Skills（verify、loop、debug 等）
├── services/             # 服务层
│   ├── api/              # Anthropic API 客户端（流式、重试）
│   ├── mcp/              # MCP 协议实现
│   ├── oauth/            # OAuth 认证
│   ├── lsp/              # LSP 语言服务器
│   ├── analytics/        # 遥测/分析
│   └── plugins/          # 插件系统
├── bridge/               # 远程控制桥接（Bridge 模式）
├── hooks/                # React Hooks
├── state/                # 全局状态管理（useSyncExternalStore）
├── utils/                # 工具函数
│   ├── git/              # Git 操作
│   ├── github/           # GitHub 集成
│   ├── permissions/      # 权限系统
│   ├── model/            # 模型选择与路由
│   ├── bash/             # Shell 执行
│   ├── sandbox/          # 沙箱隔离
│   ├── settings/         # 配置管理
│   └── memory/           # 记忆系统
├── constants/            # 常量与系统提示词
├── types/                # TypeScript 类型定义
│   └── generated/        # Protobuf 生成类型
├── plugins/              # 插件接口与内置插件
├── coordinator/          # 多 Agent 协调
├── keybindings/          # 键盘快捷键
├── vim/                  # Vim 模式
└── voice/                # 语音输入
```

## 核心架构

### 启动流程

```
bin/lhy-code → entrypoints/cli.tsx → 快速路径分流 → main.tsx → screens/REPL.tsx
```

`cli.tsx` 使用动态导入 + 快速路径模式，对 `--version`、`--daemon-worker`、`remote-control` 等特殊参数先行处理，避免加载完整模块。

### Feature Flags（构建时 DCE）

通过 `feature('FLAG_NAME')` 实现 Dead Code Elimination：
- `BRIDGE_MODE`：远程控制桥接
- `DAEMON`：守护进程
- `BG_SESSIONS`：后台会话管理
- `VOICE_MODE`：语音输入
- `COORDINATOR_MODE`：多 Agent 协调
- `WORKFLOW_SCRIPTS`：工作流脚本

### 工具系统

所有工具继承 `Tool` 基类，核心工具：
- **BashTool** — Shell 命令执行
- **FileReadTool / FileEditTool / FileWriteTool** — 文件操作
- **GlobTool / GrepTool** — 文件/内容搜索
- **WebFetchTool / WebSearchTool** — 网络访问
- **AgentTool** — 子 Agent 生成
- **MCPTool / LSPTool** — 协议工具
- **SkillTool** — Skill 调用
- **TaskCreateTool / TaskStopTool 等** — 任务管理

### 权限模型

工具调用需要权限确认，支持：
- `denyRules`：禁止特定工具/参数
- `allowRules`：允许特定工具/参数
- `bypassMode`：绕过权限检查
- 权限持久化到 `~/.claude/settings.json`

### 状态管理

使用 React `useSyncExternalStore` + 选择器模式：
- `AppStateStore` 全局 store
- `useAppState(selector)` 订阅特定切片
- 避免不必要的重渲染

## 开发约定

### 语言
- 代码注释用中文
- 提交消息用中文（约定式提交格式：`feat:`、`fix:`、`refactor:` 等）

### 文件组织
- 函数 < 50 行，文件 < 800 行
- 高内聚低耦合，按功能而非类型组织
- 嵌套层级不超过 4 层

### 代码风格
- 不可变性优先（创建新对象，不修改现有对象）
- 显式处理错误，禁止静默吞掉异常
- 禁止硬编码密钥/凭据
- 系统边界处验证所有输入

### 安全
- `.env` 文件已 gitignore，禁止提交
- 不要在前端代码中暴露 API Key
- 工具执行前必须经过权限检查

## 关键入口文件

| 文件 | 说明 |
|------|------|
| [bin/lhy-code](bin/lhy-code) | Bash 启动脚本 |
| [src/entrypoints/cli.tsx](src/entrypoints/cli.tsx) | CLI 入口（快速路径分流） |
| [src/main.tsx](src/main.tsx) | TUI 主程序 |
| [src/screens/REPL.tsx](src/screens/REPL.tsx) | REPL 交互界面 |
| [src/localRecoveryCli.ts](src/localRecoveryCli.ts) | 降级 CLI |
| [preload.ts](preload.ts) | Bun preload |