docs: 添加 CLAUDE.md 项目文档
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,183 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user