6.7 KiB
6.7 KiB
CLAUDE.md
项目概述
LHY Code — 基于 Claude Code 泄露源码修复的本地可运行版本，支持接入任意 Anthropic 兼容 API（MiniMax、OpenRouter 等）。
技术栈
- 运行时: Bun（唯一运行时，不可用 Node.js）
- 语言: TypeScript
- 终端 UI: React 19 + Ink 6
- CLI 解析: Commander.js
- API: Anthropic SDK (
@anthropic-ai/sdk) - 协议: MCP、LSP
- 构建: Bun bundler（通过
bun:bundle的feature()做 DCE） - 包管理: bun install（锁文件
bun.lock）
启动与运行
# 安装依赖
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全局 storeuseAppState(selector)订阅特定切片- 避免不必要的重渲染
开发约定
语言
- 代码注释用中文
- 提交消息用中文（约定式提交格式：
feat:、fix:、refactor:等）
文件组织
- 函数 < 50 行，文件 < 800 行
- 高内聚低耦合，按功能而非类型组织
- 嵌套层级不超过 4 层
代码风格
- 不可变性优先（创建新对象，不修改现有对象）
- 显式处理错误，禁止静默吞掉异常
- 禁止硬编码密钥/凭据
- 系统边界处验证所有输入
安全
.env文件已 gitignore，禁止提交- 不要在前端代码中暴露 API Key
- 工具执行前必须经过权限检查
关键入口文件
| 文件 | 说明 |
|---|---|
| bin/lhy-code | Bash 启动脚本 |
| src/entrypoints/cli.tsx | CLI 入口（快速路径分流） |
| src/main.tsx | TUI 主程序 |
| src/screens/REPL.tsx | REPL 交互界面 |
| src/localRecoveryCli.ts | 降级 CLI |
| preload.ts | Bun preload |