chore: rename VersperClaw to Codev, update org to chenbhao

96f34e3 25 days ago

14.7 kB

	# 项目架构概览

	## 项目定位

	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` — 负责动态加载 `<App>` 和 `<REPL>` 组件并调用 `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 │ │
	└─────────────────────────────────────┘
	```