Add project documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-05 09:33:11 +08:00
parent 4b9d30f795
commit 9074aabe1c
9 changed files with 1987 additions and 0 deletions
@@ -0,0 +1,150 @@
+# 项目文件统计分析
+
+## 代码规模
+
+| 目录 | 文件数（估算） | 说明 |
+|------|---------------|------|
+| `commands/` | 189 | 命令实现，约 82 个命令目录 |
+| `components/` | 180+ | UI 组件 |
+| `hooks/` | 70+ | React Hooks |
+| `tools/` | 80+ | 工具实现，约 40 个工具 |
+| `services/` | 50+ | 服务层 |
+| `bridge/` | 30+ | IDE 桥接 |
+| `utils/` | 50+ | 工具函数 |
+| `types/` | 10+ | 类型定义 |
+| 其他 | 50+ | 状态、Schema、Vim 等 |
+| **总计** | **~1,900** | **512,000+ 行代码** |
+
+## 核心文件规模
+
+| 文件 | 行数 | 说明 |
+|------|------|------|
+| `main.tsx` | ~804K (含内联) | CLI 入口（可能包含内联数据） |
+| `QueryEngine.ts` | ~46K | 查询引擎 |
+| `query.ts` | ~68K | 查询管道 |
+| `commands.ts` | ~25K | 命令注册 |
+| `Tool.ts` | ~29K | 工具类型定义 |
+| `tools.ts` | ~17K | 工具注册 |
+| `interactiveHelpers.tsx` | ~57K | 交互辅助 |
+| `history.ts` | ~23K | 历史记录 |
+| `setup.ts` | ~20K | 初始化设置 |
+| `context.ts` | ~6K | 上下文管理 |
+
+## 技术栈依赖
+
+### 运行时和语言
+- **Bun** — JavaScript/TypeScript 运行时，提供 `bun:bundle` 编译时特性开关
+- **TypeScript (strict)** — 类型安全
+
+### 终端 UI
+- **React** — 组件化 UI 框架
+- **Ink** — React 终端渲染器
+
+### CLI 和工具
+- **Commander.js** — CLI 参数解析
+- **ripgrep** — 代码搜索（通过子进程调用）
+- **Zod v4** — Schema 验证
+
+### 协议和 API
+- **Anthropic SDK** — Claude API 客户端
+- **MCP SDK** — Model Context Protocol
+- **LSP** — Language Server Protocol
+
+### 遥测和分析
+- **OpenTelemetry** — 遥测数据收集
+- **gRPC** — 远程过程调用
+- **GrowthBook** — 特性开关和 A/B 测试
+
+### 认证和安全
+- **OAuth 2.0** — 用户认证
+- **JWT** — Token 认证
+- **macOS Keychain** — 凭据安全存储
+
+## 模块依赖关系
+
+```mermaid
+graph LR
+    subgraph 入口
+        MAIN[main.tsx]
+    end
+
+    subgraph 核心
+        QE[QueryEngine]
+        QUERY[query.ts]
+        CTX[context.ts]
+    end
+
+    subgraph 能力层
+        TOOLS[tools.ts]
+        CMDS[commands.ts]
+    end
+
+    subgraph 实现层
+        TOOL_IMPL[tools/]
+        CMD_IMPL[commands/]
+    end
+
+    subgraph 基础设施
+        SERVICES[services/]
+        BRIDGE[bridge/]
+        HOOKS[hooks/]
+    end
+
+    subgraph UI
+        COMPONENTS[components/]
+        SCREENS[screens/]
+    end
+
+    MAIN --> QE
+    MAIN --> CMDS
+    MAIN --> COMPONENTS
+
+    QE --> QUERY
+    QE --> CTX
+    QE --> TOOLS
+
+    TOOLS --> TOOL_IMPL
+    CMDS --> CMD_IMPL
+
+    TOOL_IMPL --> SERVICES
+    TOOL_IMPL --> HOOKS
+    TOOL_IMPL --> BRIDGE
+
+    COMPONENTS --> HOOKS
+
+    QE --> SERVICES
+```
+
+## 关键设计决策
+
+### 1. Bun 运行时
+选择 Bun 而非 Node.js，获得：
+- 更快的启动时间
+- 原生 TypeScript 支持
+- `bun:bundle` 编译时特性开关（死代码消除）
+- 内置的文件系统 API
+
+### 2. React + Ink 终端 UI
+使用 React 组件模型构建 Terminal UI，获得：
+- 声明式 UI 编程
+- 状态管理一致性
+- 丰富的组件复用
+
+### 3. 工具/命令分离
+- **工具 (Tools)** — Agent 可调用的能力，通过 API 对话使用
+- **命令 (Commands)** — 用户直接调用的交互功能，通过 `/` 前缀使用
+- 两者解耦，但命令可以调用工具
+
+### 4. MCP 协议
+通过 Model Context Protocol 支持外部工具扩展：
+- 标准化的工具注册和调用
+- 支持多种传输方式（stdio、SSE、SDK）
+- 动态工具发现
+
+### 5. 代理集群架构
+支持多代理并行工作：
+- `AgentTool` 生成子代理
+- `coordinator/` 编排多代理
+- `TeamCreateTool`/`TeamDeleteTool` 管理代理团队
+- `SendMessageTool` 代理间通信
+- Git Worktree 隔离