# 项目架构概览 ## 项目定位 Codev 是一个 AI CLI 智能代理，基于 Anthropic Claude Code 源代码构建，增强了对以下场景的支持： - **VRM 桌面伴侣**（Friend）：在同一进程中运行 HTTP/SSE 服务，驱动 3D VRM 角色的表情、语音和文本气泡 - **多模型提供者**：通过反向代理层将 Anthropic Messages API 协议翻译为 OpenAI Chat/Responses API 协议，支持数十种第三方模型 - **语音对话**：基于 cpal（Rust 原生音频库）的进程内音频捕获，结合 Silero VAD（ONNX 实时语音活动检测）和多种 STT/TTS 引擎 - **自动化模式**：目标系统（Goals）、后台任务（Background Tasks）、MCP 工具集成、Feishu/Telegram Bot 桥接 ## 技术栈 | 类别 | 技术 | |------|------| | 运行时 | **Bun 1.3+**（JavaScript/TypeScript 运行时与打包器） | | 语言 | **TypeScript**（全仓库使用 strict 模式） | | 终端 UI | **Ink v6**（React 终端渲染框架）+ **React 19** | | 3D 渲染 | **Three.js**（VRM 前端使用，通过 {React} Three Fiber） | | 语音活动检测 | **onnxruntime-web (WASM)** — Silero VAD ONNX 模型（非 onnxruntime-node，避免 Bun 段错误） | | 桌面窗口 | **Tauri**（可选桌面窗口模式） | | 包管理 | **Bun** workspace（monorepo），`packageManager: bun@1.3.11` | | 构建 | Bun 内建打包 `scripts/build.ts`，支持 `feature()` 死代码消除 | ## 入口流程 ``` cli.tsx (bootstrap) │ ▼ main.tsx (Commander CLI 定义) │ ├── 注册 ~180+ 命令（commands.ts → command modules） │ └── 注册 ~60+ AI 工具（tools.ts → tool modules） │ ▼ replLauncher.tsx │ ▼ Ink REPL (screens/REPL.tsx) ├── PromptInput（文本输入组件） ├── messageQueueManager（统一命令队列） ├── query.ts（AI 请求分发） └── useMergedTools（工具池装配） ``` ### 启动阶段详解 1. **`src/entrypoints/cli.tsx`** — 最外层入口。先扫描 `--version`/`-v`、`--dump-system-prompt`、`--bridge`、`--daemon`、`--tmux` 等快速路径标志。若无匹配则动态导入 `main.tsx` 并调用 `cliMain()`。 2. **`src/main.tsx`** — 构建 Commander CLI 定义（约 180+ 命令）。执行配置加载、策略检查、遥测初始化、会话恢复等。最后调用 `launchRepl()` 渲染终端 UI。 3. **`src/replLauncher.tsx`** — 负责动态加载 `` 和 `` 组件并调用 `renderAndRun()`。 4. **`src/screens/REPL.tsx`** — 主 REPL 屏幕，包含消息历史、PromptInput、工具调用渲染等。 ## 架构亮点 ### 1. 同进程架构 Friend VRM 服务与 CLI 运行在**同一 Bun 进程**中： - `friend/server.ts` 通过 `Bun.serve()` 监听 `127.0.0.1:3456` - SSE（Server-Sent Events）用于服务端到 VRM 前端的实时推送（表情、音频、文本气泡） - HTTP POST 用于 VRM 前端向 FriendService 发送消息 - 消除了独立的子进程管理和 CLI SDK 会话的开销 ### 2. 模块化工具系统 60+ AI 可调用工具通过 `buildTool()` 框架注册。核心工具包括： - **文件操作**: `BashTool`, `FileReadTool`, `FileEditTool`, `FileWriteTool`, `GlobTool`, `GrepTool` - **Web/搜索**: `WebFetchTool`, `WebSearchTool` - **任务管理**: `TaskCreateTool`, `TaskGetTool`, `TaskUpdateTool`, `TaskListTool`, `TaskStopTool` - **MCP**: `ListMcpResourcesTool`, `ReadMcpResourceTool` - **Friend 特有**: `FriendEmotionTool`（VRM 表情 + 心情管理）, `FriendScreenObserveTool` - **目标系统**: `GoalCreateTool`, `GoalGetTool`, `GoalUpdateTool` - **工作流**: `WorkflowTool`（通过 WORKFLOW_SCRIPTS feature flag） - **其他**: `AgentTool`, `SkillTool`, `TodoWriteTool`, `ToolSearchTool`, `ConfigTool` 等 工具通过 `assembleToolPool()` 与 MCP 工具合并去重，统一提供给 AI 模型。 ### 3. 多 Provider 代理 `src/server/proxy/handler.ts` 实现协议翻译反向代理： - **输入**: CLI 以 Anthropic Messages API 格式发送请求到 `POST /proxy/v1/messages` 或 `POST /proxy/providers/:id/v1/messages` - **转换**: `anthropicToOpenaiChat.ts` / `anthropicToOpenaiResponses.ts` 将请求体翻译为 OpenAI 格式 - **转发**: 发送到上游第三方提供商的 API - **回传**: `openaiChatToAnthropic.ts` / `openaiResponsesToAnthropic.ts` 将响应翻译回 Anthropic 格式 - **流式**: 支持 SSE 流式响应的双向转换（`openaiChatStreamToAnthropic.ts` / `openaiResponsesStreamToAnthropic.ts`） ### 4. Feature Flag 系统 通过 `bun:bundle` 的 `feature()` 函数实现编译期死代码消除： ```typescript import { feature } from 'bun:bundle' // 以下代码在非 KAIROS 构建中被完全消除 const assistantModule = feature('KAIROS') ? require('./assistant/index.js') : null ``` 已定义的 feature flags（部分）：`VOICE_MODE`, `KAIROS`, `DAEMON`, `BRIDGE_MODE`, `COORDINATOR_MODE`, `PROACTIVE`, `AGENT_TRIGGERS`, `MCP_SKILLS`, `WORKFLOW_SCRIPTS`, `BUDDY`, `FORK_SUBAGENT`, `MONITOR_TOOL`, `WEB_BROWSER_TOOL`, `TERMINAL_PANEL` 等。 ## 核心模块一览 | 目录 | 职责 | |------|------| | `src/entrypoints/` | 程序入口点（cli.tsx bootstrap, init.ts 初始化） | | `src/main.tsx` | Commander CLI 定义、启动流程编排 | | `src/commands/` | 180+ 斜杠命令（`/clear`, `/commit`, `/config`, `/friend` 等） | | `src/commands.ts` | 命令注册中心，从各模块加载并导出命令列表 | | `src/tools/` | 60+ AI 工具实现（Bash, Read, Edit, WebSearch, FriendEmotion 等） | | `src/tools.ts` | 工具注册中心，`getAllBaseTools()` 与 `assembleToolPool()` | | `src/ink/` | Ink 终端渲染引擎（自定义 fork，包含 reconciler、layout、renderer 等） | | `src/screens/` | 主要 UI 屏幕（REPL 主屏幕、设置向导等） | | `src/components/` | React 组件（App, PromptInput, 权限请求等） | | `src/hooks/` | React hooks（useMergedTools, useCommandQueue, useReplBridge 等） | | `src/friend/` | VRM 桌面伴侣服务（FriendService, SSE, TTS, VAD, STT） | | `src/server/` | HTTP/WebSocket 服务器（API 路由、Provider 代理、MCP、H5 访问） | | `src/server/proxy/` | 多 Provider 反向代理（协议翻译：Anthropic ↔ OpenAI） | | `src/bridge/` | 远程桥接（WebSocket ↔ claude.ai 远程会话） | | `src/query/` | AI 请求查询引擎（`query.ts`、`QueryEngine.ts`） | | `src/context/` | 系统上下文构建（`context.ts`，生成系统提示词） | | `src/services/` | 后端服务（API client, Analytics, MCP, PolicyLimits, Compact 等） | | `src/utils/` | 工具函数（配置、认证、消息队列、权限、MCP 插件、设置等） | | `src/state/` | 应用状态管理（AppStateStore） | | `src/types/` | TypeScript 类型定义 | | `src/constants/` | 常量（OAuth、产品名、提示词、工具定义等） | | `src/voice/` | 语音模式入口（`voiceModeEnabled.ts`） | | `src/assistant/` | 助手模式（KAIROS feature flag 守护） | | `src/coordinator/` | 协调器模式（多 agent 协作） | | `src/buddy/` | Buddy 子 agent 系统（BUDDY feature flag） | | `src/daemon/` | 守护进程模式（长期运行的后台服务） | | `src/plugins/` | 插件系统（插件发现、加载、生命周期） | | `src/skills/` | 技能系统（用户自定义 prompt 式命令） | | `src/tasks/` | 任务系统（LocalAgentTask, LocalShellTask, RemoteAgentTask 等） | | `src/cli/` | CLI 工具（bg.ts 后台会话管理、templateJobs 模板任务） | | `src/bootstrap/` | 启动状态（state.ts 导入前状态设置） | | `src/config/` | 配置处理 | | `src/vim/` | Vim 模式支持 | | `src/migrations/` | 数据迁移 | | `src/memdir/` | 记忆目录支持 | | `src/upstreamproxy/` | 上游代理支持 | | `src/remote/` | 远程控制支持 | | `native-modules/` | Rust/C++ 原生模块（cpal 音频捕获等） | ## 数据流总览 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ CLI 进程 (Bun) │ │ │ │ ┌──────────┐ ┌───────────┐ ┌───────────┐ ┌─────────────┐ │ │ │ cli.tsx │───▶│ main.tsx │───▶│ REPL.tsx │───▶│ PromptInput │ │ │ │ (bootstrap) │ (Commander) │ (Ink UI) │ │ (输入框) │ │ │ └──────────┘ └───────────┘ └─────┬─────┘ └──────┬──────┘ │ │ │ │ │ │ │ ┌────────────▼────┐ │ │ │ │ messageQueue │ │ │ │ │ Manager.enqueue │ │ │ │ └────────┬────────┘ │ │ │ │ │ │ │ ┌────────▼────────┐ │ │ │ │ query() │ │ │ │ │ (AI 请求) │ │ │ │ └──┬────┬────────┘ │ │ │ │ │ │ │ ┌────────────────────┼────────┘ │ │ │ │ │ │ │ │ ▼ │ ┌────────▼────────┐ │ │ ┌─────────────────────────┐ │ │ Tool Execution │ │ │ │ Anthropic SDK (1P) │ │ │ (Bash/Read/Edit │ │ │ │ POST /v1/messages │ │ │ ...等 ~60 工具) │ │ │ └─────────────────────────┘ │ └─────────────────┘ │ │ │ │ │ │ ┌──────────▼──────────┐ │ │ │ │ server/proxy/ │ │ │ │ │ handler.ts │ │ │ │ │ (3P Provider 代理) │ │ │ │ └──────────┬──────────┘ │ │ │ │ │ │ │ ▼ │ │ │ ┌──────────────────────────────┐ │ │ │ │ OpenAI Chat/Responses API │ │ │ │ │ (OpenAI/Groq/DeepSeek 等) │ │ │ │ └──────────────────────────────┘ │ │ │ │ │ │ ┌──────────────────────────────────────┼──────────────┐ │ │ │ FriendService (同进程) │ │ │ │ │ ┌─────────┐ ┌──────────┐ ┌───────▼──────┐ │ │ │ │ │ Silero │ │ STT │ │ SSE Server │ │ │ │ │ │ VAD │──│ (Doubao/ │ │ :3456 │ │ │ │ │ │ (ONNX) │ │ Whisper) │ └──────┬───────┘ │ │ │ │ └─────────┘ └──────────┘ │ │ │ │ │ ┌─────────┐ ┌──────────┐ │ │ │ │ │ │ TTS │ │ EdgeTTS/ │ │ │ │ │ │ │ Audio │──│ QwenTTS │ │ │ │ │ │ └─────────┘ └──────────┘ │ │ │ │ └────────────────────────────────────┼──────────────┘ │ └───────────────────────────────────────┼──────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ VRM 前端 (Web/Desktop) │ │ ┌─────────────────────────────────┐ │ │ │ SSE → VRMScene → TextBubble │ │ │ │ → EmoteController │ │ │ │ → MotionController │ │ │ │ → AudioPlayback │ │ │ └─────────────────────────────────┘ │ │ HTTP POST → FriendService.sendText │ │ └─────────────────────────────────────┘ ```