# 项目文件统计分析

## 代码规模

| 目录 | 文件数（估算） | 说明 |
|------|---------------|------|
| `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 隔离