chore: docs v1.0

docs/README.md

@@ -0,0 +1,66 @@
+# VersperClaw 文档
+
+> VersperClaw — 基于 Anthropic Claude Code 的增强型 AI CLI 代理，集成 VRM 桌面伴侣、多 Provider、语音对话和自动化模式。
+
+## 目录
+
+### 架构
+| 文档 | 说明 |
+|------|------|
+| [项目架构概览](architecture/overview.md) | 技术栈、入口流程、模块职责、架构亮点 |
+| [核心数据流](architecture/data-flow.md) | 5 大核心数据流：用户输入、语音捕获、远程桥接、Friend 表情、Provider 代理 |
+
+### CLI 与工具
+| 文档 | 说明 |
+|------|------|
+| [CLI 命令系统](cli/overview.md) | 命令注册、Slash 命令大全 (~75+)、Skill/工作流系统 |
+| [AI 工具系统](tools/overview.md) | buildTool 框架、执行流程、权限系统、关键工具详解 |
+| [工具参考大全](tools/tool-reference.md) | 所有 ~60+ AI 工具的完整参考表 |
+
+### Friend VRM 伴侣
+| 文档 | 说明 |
+|------|------|
+| [系统总览](friend/overview.md) | 定位、组件、交互模式、架构图 |
+| [系统架构](friend/architecture.md) | FriendService、SSE、HTTP 服务器、TTS/STT/VAD 详细分析 |
+| [数据流](friend/data-flow.md) | 文字对话/F2 语音/情绪表情/SSE 事件 四种流 |
+| [情绪→3D 表情映射](friend/emotion-map.md) | 13 种情绪的 blend shape 组合、动作映射 |
+| [前端 3D 渲染](friend/frontend-3d.md) | Three.js、EmoteController、MotionController、LipSync、TextBubble |
+| [语音捕获与 VAD](friend/voice-vad.md) | Silero VAD 状态机、STT 提供者链、静音系统 |
+
+### 语音
+| 文档 | 说明 |
+|------|------|
+| [语音系统总览](voice/overview.md) | STT/TTS 提供者、Voice Stream 协议 |
+
+### Ink 终端 UI
+| 文档 | 说明 |
+|------|------|
+| [Ink UI 框架](ink-ui/overview.md) | 自定义 Fork 的渲染管线、组件库、事件系统 |
+
+### 桌面服务器
+| 文档 | 说明 |
+|------|------|
+| [HTTP/WS 服务器](server/overview.md) | Bun.serve()、REST API、WebSocket、服务层 |
+| [Provider 代理](server/proxy-provider.md) | Anthropic ↔ OpenAI 协议转换、多提供商支持 |
+
+### 后端服务
+| 文档 | 说明 |
+|------|------|
+| [服务总览](services/overview.md) | MCP、上下文压缩、Auto Dream、飞书/Telegram |
+
+### 协调与自动化
+| 文档 | 说明 |
+|------|------|
+| [目标与自动模式](coordinator/goals-auto-mode.md) | Goal 系统、Auto Mode、查询循环、Task 系统 |
+| [多代理协调](coordinator/multi-agent.md) | Coordinator 模式、Worker 派发、并行策略 |
+
+### 远程桥接
+| 文档 | 说明 |
+|------|------|
+| [远程桥接总览](remote-bridge/overview.md) | Bridge 模式、传输协议、认证机制 |
+
+### 记忆与上下文
+| 文档 | 说明 |
+|------|------|
+| [自动记忆系统](memory-context/memory.md) | Memdir、4 种记忆类型、生命周期 |
+| [上下文管理](memory-context/context.md) | 系统/用户上下文构建、压缩策略、React Contexts |

docs/architecture/data-flow.md

@@ -0,0 +1,560 @@
+# 核心数据流
+
+本文档详细描述 VersperClaw 的六大核心数据流，包含 ASCII 序列图和关键代码路径。
+
+---
+
+## 1. 用户输入流
+
+用户通过终端输入文本到 AI 响应的完整链路。
+
+```
+User (键盘)
+    │
+    │  键入文本 + Enter
+    ▼
+PromptInput 组件
+(screens/PromptInput.tsx)
+    │
+    │  handlePromptSubmit()
+    ▼
+messageQueueManager.enqueue()
+(utils/messageQueueManager.ts)
+    │
+    │ 命令入队 (priority: 'now' | 'next' | 'later')
+    │ FIFO 按优先级排序
+    ▼
+useCommandQueue hook
+(hooks/useCommandQueue.ts)
+    │
+    │ 出队 → 交给 REPL 主循环
+    ▼
+query() 函数
+(query.ts → QueryEngine.ts)
+    │
+    ├── 组装消息历史
+    ├── 获取系统提示词 (src/context.ts)
+    ├── 合并工具列表 (assembleToolPool)
+    └── 选择 Provider
+         │
+         ├── [1P Anthropic] ── Anthropic SDK ── POST /v1/messages
+         │
+         └── [3P Provider] ── server/proxy/handler.ts
+                                │
+                                ├── anthropicToOpenaiChat.ts  (请求转换)
+                                ├── POST provider API (OpenAI/Groq/DeepSeek...)
+                                └── openaiChatToAnthropic.ts (响应转换)
+                                      │
+                                      ▼
+                              流式响应回到 query()
+                                      │
+                                      ▼
+                              工具调用分发 (Tool Execution)
+                                      │
+                                      ▼
+                              渲染响应到终端 (Ink UI)
+```
+
+### 关键代码路径
+
+| 步骤 | 文件 | 核心函数 |
+|------|------|----------|
+| 输入 | `src/components/PromptInput/PromptInput.tsx` | `handlePromptSubmit()` |
+| 队列 | `src/utils/messageQueueManager.ts` | `enqueue()`, `dequeue()` |
+| 查询 | `src/query.ts` | `query()` |
+| 引擎 | `src/QueryEngine.ts` | `QueryEngine` 类 |
+| 工具 | `src/tools.ts` | `assembleToolPool()`, `getTools()` |
+| 代理 | `src/server/proxy/handler.ts` | `handleProxyRequest()` |
+| 响应渲染 | `src/screens/REPL.tsx` | 消息列表 + 流式渲染 |
+
+### 队列优先级机制
+
+```
+优先级: 'now' > 'next' > 'later'
+同一优先级内 FIFO
+
+┌─────────┐  ┌──────────┐  ┌─────────┐
+│  'now'  │  │  'next'  │  │ 'later' │
+│ (紧急)  │  │ (正常)   │  │ (通知)  │
+├─────────┤  ├──────────┤  ├─────────┤
+│ ═══▶    │  │ ═══▶     │  │ ═══▶    │
+│ 出队优先  │  │          │  │         │
+└─────────┘  └──────────┘  └─────────┘
+```
+
+---
+
+## 2. 语音捕获流
+
+从麦克风到 VRM 前端语音播放的完整管道。
+
+### 语音捕获架构
+
+VersperClaw 使用进程内音频捕获（cpal Rust 库，通过 `native-modules/audio-capture-napi`），而不是传统的 arecord/parecord 子进程。
+
+```
+麦克风 (硬件)
+    │
+    │ 16kHz S16LE PCM
+    ▼
+cpal (Rust 原生模块)
+(native-modules/audio-capture-napi)
+    │
+    │ onData(chunk: Buffer)
+    ▼
+FriendService.startVoiceCapture()
+(friend/FriendService.ts)
+    │
+    ├──▶ Silero VAD (语音活动检测)
+    │    (friend/voice/vad-service.ts)
+    │    │
+    │    │ onnxruntime-web WASM 推理
+    │    │ 512 samples/frame @ 16kHz (32ms)
+    │    │
+    │    ├── 说话开始 → 开始积累音频
+    │    ├── 检测持续语音 (≥10 帧 ≈ 320ms 激活)
+    │    └── 检测静音 (≥20 帧 ≈ 640ms) → onSpeechEnd
+    │         │
+    │         ▼
+    │    音频段 (Float32Array)
+    │         │
+    │         ▼
+    │    STT (语音转文字)
+    │    ├── Doubao ASM (火山引擎)
+    │    │   (doubaoime-asr 包)
+    │    ├── Anthropic STT
+    │    └── Whisper (OpenAI)
+    │         │
+    │         ▼
+    │    转录文本 (transcript)
+    │
+    └──▶ messageQueueManager.enqueue()
+         │
+         │ { value: transcript, mode: 'prompt', origin: { kind: 'channel', server: 'friend' } }
+         ▼
+    AI 处理 (同用户输入流)
+         │
+         │ AI 响应文本
+         ▼
+    TTS (文本转语音)
+    ├── Edge TTS (node-edge-tts, 默认 zh-CN-XiaoxiaoNeural)
+    └── Qwen TTS (DashScope API, qwen3-tts-flash)
+         │
+         │ 生成 MP3 文件
+         ▼
+    broadcastToVrm()
+    (friend/sse.ts)
+         │
+         │ SSE → { text, audioUrl, audioIndex }
+         ▼
+    VRM 前端
+    ├── 播放音频
+    ├── 显示文本气泡
+    └── ��发口型同步
+```
+
+### VAD 状态机
+
+```
+Silero VAD 内部状态:
+
+          [静音] ────────────── 帧概率 < 正阈值 ──────────────▶ [静音]
+            │                                                     ▲
+            │ 帧概率 ≥ positiveSpeechThreshold                   │
+            │ (连续 ≥ preSpeechTriggerFrames)                    │ 帧概率 < 负阈值
+            ▼                                                     │ (连续 ≥ redemptionFrames)
+          [可能说话] ────── 帧概率 < 正阈值 ──────▶ [确认说话] ──┘
+            │                                                     │
+            │ onSpeechStart()                                     │ onSpeechEnd(audio)
+            ▼                                                     ▼
+      [积累音频帧]                                      [发送音频段到 STT]
+```
+
+| 参数 | 默认值 | 含义 |
+|------|--------|------|
+| `positiveSpeechThreshold` | 0.75 | 判定为语音的置信度阈值 |
+| `negativeSpeechThreshold` | 0.50 | 判定为静音的置信度阈值 |
+| `preSpeechTriggerFrames` | 10 | 激活前需要连续语音帧数 |
+| `redemptionFrames` | 20 | 结束前需要连续静音帧数 |
+| `minSpeechFrames` | 6 | 最小有效语音帧数 |
+| `rmsThreshold` | 0.004 | RMS 能量阈值 (-48dBFS)，低于此值跳过推理 |
+
+### 回声消除机制
+
+```
+FriendService 在 TTS 播放时自动静音麦克风:
+
+AI 响应文本
+    │
+    ▼
+TTS 开始生成
+    │
+    ▼
+friend.muted = true
+    │  muteTimer = setTimeout(unmute, estimatedTtsDuration)
+    │
+    ▼
+TTS 播放期间: 麦克风数据 → 丢弃 (不送 VAD/STT)
+    │
+    ▼
+TTS 播放结束 (或估算时间到)
+    │
+    ▼
+friend.muted = false
+    │
+    ▼
+恢复正常捕获
+```
+
+---
+
+## 3. 远程桥接流
+
+Local CLI 到 `claude.ai` 远程会话的 WebSocket 桥接。
+
+```
+Local CLI (你的机器)                  claude.ai 服务器
+─────────────────────            ─────────────────────
+
+  claude --remote start
+       │
+       ▼
+  bridgeMain()
+  (bridge/bridgeMain.ts)
+       │
+       │ 创建本地 HTTP 服务
+       │ 发起 OAuth 登录
+       ▼
+  WebSocket 连接
+  (bridge/replBridgeTransport.ts)
+       │                ◄══════════►  claude.ai 远程会话
+       │  wss://api.claude.ai/...
+       │
+       ▼
+  replBridge.ts
+       │
+       ├── 从远程接收输入 → 入队到本地 messageQueueManager
+       ├── 将本地输出/工具结果 → 发送回远程
+       └── 同步本地命令到远程白名单
+            (BRIDGE_SAFE_COMMANDS)
+```
+
+### 命令过滤
+
+远程模式下只允许安全命令执行：
+
+```
+REMOTE_SAFE_COMMANDS = {
+   session,   // 显示 QR/URL
+   exit,      // 退出
+   clear,     // 清屏
+   help,      // 帮助
+   theme,     // 主题
+   color,     // 颜色
+   vim,       // Vim 模式
+   cost,      // 计费
+   usage,     // 用量
+   copy,      // 复制
+   btw,       // 便签
+   feedback,  // 反馈
+   plan,      // 计划模式
+   keybindings, // 快捷键
+   statusline,  // 状态栏
+   stickers,    // 贴纸
+   mobile,      // 移动端
+}
+```
+
+桥接安全命令（从移动端也可执行）：
+
+```
+BRIDGE_SAFE_COMMANDS = {
+   compact,    // 压缩上下文
+   clear,      // 清屏
+   cost,       // 计费
+   summary,    // 会话总结
+   releaseNotes, // 更新日志
+   files,      // 文件列表
+}
+```
+
+---
+
+## 4. Friend 表情流
+
+LLM 调用 `friend_emotion` 工具到 VRM 前端 3D 角色表情渲染的完整链路。
+
+```
+LLM 推理
+    │
+    │ 思考上下文后调用 FriendEmotionTool
+    ▼
+FriendEmotionTool.call({ emotion, intensity, mood_delta })
+(tools/FriendEmotionTool.ts)
+    │
+    ├── 更新心情指数 moodIndex (0-100, 基准值 60)
+    │   ├── mood_delta > 0: moodIndex += delta (上限 100)
+    │   └── mood_delta < 0: moodIndex -= delta (下限 0)
+    │
+    └── broadcastToVrm({
+    │       emotion: 'happy'|'sad'|'angry'|...,
+    │       emotionIntensity: 0..1,
+    │       moodDelta: n,
+    │       moodIndex: n
+    │   })
+    │
+    ▼
+broadcastToVrm()
+(friend/sse.ts)
+    │
+    │ SSE data: JSON.stringify(payload) + "\n\n"
+    │ 发送给所有已连接的 SSE 客户端
+    ▼
+VRM 前端 (Three.js / React Three Fiber)
+    │
+    ├── SSE 事件解析
+    │
+    ├── VRMScene 组件
+    │   ├── EmoteController — 设置 BlendShape 混合形状
+    │   │   (happy → 嘴角上扬, sad → 眉眼下垂, 等)
+    │   ├── MotionController — 触发生理动画 (呼吸、眨眼)
+    │   └── TextBubble — 显示聊天文本气泡
+    │
+    └── AudioPlayback (如���有 audioUrl)
+        └── 播放 TTS 音频 + 口型同步
+```
+
+### 可用表情列表
+
+| 表情 | 说明 |
+|------|------|
+| `happy` | 开心 |
+| `sad` | 悲伤 |
+| `angry` | 生气 |
+| `surprised` | 惊讶 |
+| `think` | 思考 |
+| `awkward` | 尴尬 |
+| `question` | 疑问 |
+| `curious` | 好奇 |
+| `neutral` | 中性/默认 |
+| `love` | 喜爱 |
+| `flirty` | 调情 |
+| `greeting` | 打招呼 |
+| `relaxed` | 放松 |
+
+### 心情系统
+
+```
+心情指数 (moodIndex) 范围 0-100，基准值 60
+
+  0 ────────────── 60 ────────────── 100
+  [低落]          [中性]            [高涨]
+
+每次 mood_delta: -3 到 +3 (最小绝对值 1)
+通过 prefs 持久化 (friend/prefs.ts)
+
+moodIndex 影响:
+  - 文本气泡颜色/样式
+  - 坐姿姿态 (放松 vs 紧张)
+  - 手臂动作幅度
+```
+
+### SSE 广播事件类型
+
+Friend SSE 通道通过 `broadcastToVrm()` 发送 JSON 事件，所有字段均为可选：
+
+```typescript
+type VrmBroadcastPayload = {
+  text?: string;           // 显示文本
+  emotion?: string;        // 表情名称
+  emotionIntensity?: number; // 表情强度 0-1
+  audioUrl?: string;       // TTS 音频 URL
+  audioIndex?: number;     // 音频序列号
+  clearText?: boolean;     // 清除当前文本
+  imageUrl?: string;       // 显示的图片 URL
+  moodDelta?: number;      // 心情变化量
+  moodIndex?: number;      // 当前心情指数
+  sendFirstTts?: boolean;  // 发送第一个 TTS 段
+  appendText?: boolean;    // 追加到已有文本
+  replyDone?: boolean;     // 响应结束标记
+};
+```
+
+---
+
+## 5. Provider 代理流
+
+CLI 通过统一接口向不同 LLM Provider 发送请求的完整路径。
+
+### 双路由架构
+
+```
+CLI (Anthropic Messages API format)
+    │
+    │ 选择 Provider
+    ▼
+┌────────────────────────────────────────┐
+│          Provider 路由决策              │
+│                                        │
+│  isFirstPartyAnthropicBaseUrl()         │
+│  + isClaudeAISubscriber()               │
+│  + !isUsing3PServices()                 │
+│         │                    │          │
+│       是/                    │ 否       │
+│         │                    │          │
+│         ▼                    ▼          │
+│   ┌──────────┐    ┌──────────────────┐ │
+│   │ Anthropic│    │  Proxy Handler   │ │
+│   │ SDK 直连 │    │  (server/proxy/  │ │
+│   │          │    │   handler.ts)    │ │
+│   │POST /v1/ │    │                  │ │
+│   │messages  │    │ apiFormat?       │ │
+│   └──────────┘    │                  │ │
+│                   │ ┌── 'openai' ──▶ │ │
+│                   │ │ Anthropic →    │ │
+│                   │ │ OpenAI Chat    │ │
+│                   │ │ Completions    │ │
+│                   │ │                │ │
+│                   │ │── 'openai-     │ │
+│                   │ │   responses'   │ │
+│                   │ │ Anthropic →    │ │
+│                   │ │ OpenAI         │ │
+│                   │ │ Responses API  │ │
+│                   │ └────────────────│ │
+│                   └──────────────────┘ │
+└────────────────────────────────────────┘
+```
+
+### 请求/响应转换流程
+
+```
+Anthropic Messages API 请求
+{
+  model: "claude-3-opus",
+  messages: [{role: "user", content: "Hello"}],
+  system: "You are helpful",
+  max_tokens: 1024,
+  stream: true
+}
+    │
+    ▼
+anthropicToOpenaiChat.ts / anthropicToOpenaiResponses.ts
+    │
+    │ 转换逻辑:
+    │ - system → system message (prefix)
+    │ - messages[] → messages[] (role 映射)
+    │ - max_tokens → max_tokens
+    │ - stream → stream
+    │ - tools → tools (格式适配)
+    │
+    ▼
+OpenAI Chat/Responses API 请求
+{
+  model: "gpt-4",
+  messages: [
+    {role: "system", content: "You are helpful"},
+    {role: "user", content: "Hello"}
+  ],
+  max_tokens: 1024,
+  stream: true
+}
+    │
+    │ POST 到上游 Provider URL
+    ▼
+OpenAI 流式响应
+    │
+    ▼
+openaiChatToAnthropic.ts / openaiResponsesToAnthropic.ts (流式)
+    │
+    │ 转换逻辑:
+    │ - delta.content → delta.text
+    │ - tool_calls → content_block / tool_use
+    │ - finish_reason → stop_reason
+    │
+    ▼
+Anthropic 格式流式事件回 CLI
+```
+
+### Provider 配置
+
+通过 ProviderService (`src/server/services/providerService.ts`) 管理：
+
+```typescript
+type ProviderConfig = {
+  id: string;
+  name: string;
+  apiFormat: 'openai' | 'openai-responses' | 'anthropic';
+  baseUrl: string;
+  apiKey: string;
+  models: string[];
+};
+```
+
+支持的内置 Provider（部分）：
+- OpenAI (GPT-4, GPT-4o)
+- Groq (Llama, Mixtral)
+- DeepSeek
+- 自定义 OpenAI 兼容 API
+
+---
+
+## 数据流汇总图
+
+```
+                        ┌─────────────────────────┐
+                        │    用户的输入来源         │
+                        ├─────┬─────┬──────┬──────┤
+                        │键盘 │语音 │远程  │ Bot  │
+                        │     │     │WebSocket  │
+                        └──┬──┴──┬──┴──┬───┴──┬──┘
+                           │     │     │      │
+                           ▼     │     │      │
+                    ┌──────────┐ │     │      │
+                    │  message │◄┘     │      │
+                    │  Queue   │◄──────┘      │
+                    │  Manager │◄─────────────┘
+                    └─────┬────┘
+                          │
+                          ▼
+                    ┌──────────┐
+                    │  query() │
+                    │  AI 引擎 │
+                    └──┬────┬──┘
+                       │    │
+            ┌──────────┘    └──────────┐
+            ▼                          ▼
+    ┌──────────────┐          ┌────────────────┐
+    │  Tool 执行    │          │  LLM 文本响应   │
+    │ (Bash/Read/  │          └───────┬────────┘
+    │  Edit/...   │                  │
+    └──────────────┘          ┌───────┴────────┐
+                              │  分发到消费者    │
+                              ├────┬────┬──────┤
+                              │TUI │TTS │SSE   │
+                              │显示 │播放 │推送  │
+                              └────┴────┴──────┘
+```
+
+---
+
+## 参考文件路径
+
+| 文件 | 说明 |
+|------|------|
+| `src/utils/messageQueueManager.ts` | 统一命令队列 |
+| `src/query.ts` | AI 查询入口 |
+| `src/QueryEngine.ts` | 查询引擎实现 |
+| `src/friend/FriendService.ts` | Friend 语音/文本服务 |
+| `src/friend/voice/vad-service.ts` | Silero VAD 实现 |
+| `src/friend/tts.ts` | Edge TTS / Qwen TTS |
+| `src/friend/sse.ts` | SSE 广播与客户端管理 |
+| `src/friend/server.ts` | Friend HTTP 服务 (Bun.serve) |
+| `src/tools/FriendEmotionTool.ts` | VRM 表情工具 |
+| `src/friend/constants.ts` | 情绪列表常量 |
+| `src/server/proxy/handler.ts` | Provider 代理句柄 |
+| `src/server/proxy/transform/` | 协议转换器 |
+| `src/server/proxy/streaming/` | 流式响应转换 |
+| `src/server/services/providerService.ts` | Provider 配置管理 |
+| `src/bridge/bridgeMain.ts` | 远程桥接主入口 |
+| `src/bridge/replBridgeTransport.ts` | WebSocket 传输层 |
+| `src/bridge/replBridge.ts` | REPL 桥接逻辑 |

docs/architecture/overview.md

@@ -0,0 +1,213 @@
+# 项目架构概览
+
+## 项目定位
+
+VersperClaw 是一个 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 │ │
+                  └─────────────────────────────────────┘
+```

docs/coordinator/goals-auto-mode.md

@@ -0,0 +1,222 @@
+# 目标系统与自动模式
+
+## Goal 系统
+
+Goal（目标）系统允许用户通过 `/goal <objective>` 命令设定一个长期目标，让 Agent 在多个对话轮次中持续追寻该目标，直至完成、受阻或暂停。
+
+### 状态机
+
+Goal 的生命周期由以下状态构成：
+
+```
+pursuing → paused → achieved / blocked
+         → usage-limited / budget-limited
+```
+
+- **pursuing（追寻中）**：初始状态，Agent 正在积极地朝目标推进。
+- **paused（已暂停）**：用户使用 `/goal pause` 暂停自动续跑，可用 `/goal resume` 恢复。
+- **achieved（已完成）**：Agent 认定目标已完全达成。需经过严格的完成审计（Completion Audit）。
+- **blocked（已阻塞）**：Agent 遇到无法继续的障碍，需要用户介入。
+- **usage-limited / budget-limited**：因 token 预算或费用限制而停止。
+
+### 核心文件
+
+| 文件 | 路径 | 用途 |
+|------|------|------|
+| goal.tsx | `src/commands/goal/goal.tsx` | `/goal` 命令的 JSX 实现（React Ink 渲染） |
+| index.ts | `src/commands/goal/index.ts` | 命令注册入口 |
+| goal.ts | `src/utils/goal.ts` | 工具函数：构建续跑提示、状态格式化 |
+| useGoalAutoContinue.ts | `src/hooks/useGoalAutoContinue.ts` | React Hook：在每轮对话结束后自动注入续跑提示 |
+
+### 持续提示
+
+`buildContinuationPrompt()`（定义于 `src/utils/goal.ts`）在每轮自动续跑时注入完整的上下文提示，包含：
+
+- **目标描述**（`<objective>` XML 标签包裹）
+- **续跑行为指导**：保持目标完整性，不允许缩小范围
+- **基于证据的工作原则**：依赖当前工作区状态而非对话记忆
+- **完成审计要求**：必须逐项验证所有需求
+- **阻塞审计规则**：连续 3 轮相同阻塞条件才允许标记 blocked
+
+`useGoalAutoContinue` hook（`src/hooks/useGoalAutoContinue.ts`）监听 `QueryGuard` 状态：
+- 当查询从活跃（running）转为空闲（idle）时触发
+- 仅在 goal 状态为 `pursuing` 且非 plan 模式时注入
+- 自动清理旧目标的排队续跑，防止冲突
+- 每次续跑递增 `continuationCount`
+
+### 完成审计（Completion Audit）
+
+Agent 在决定标记目标为 `achieved` 前，必须执行严格的完成审计：
+
+1. 从目标描述中推导具体的、可验证的需求
+2. 不重新定义成功标准——保留原始范围
+3. 对每个需求，检查当前状态中的权威证据
+4. 确认证据足以证明完成，而非仅未发现未完成的工作
+5. 只有在当前证据能够经受逐项审查时，才标记为已达成
+
+### Blocked 审计
+
+防止 Agent 过早放弃的机制（`src/utils/goal.ts` 中 `BLOCKED_AUDIT_TURNS = 3`）：
+
+- 阻塞条件必须连续出现 **至少 3 轮** 才能标记 blocked
+- 用户恢复已阻塞的目标后，阻塞审计重置
+- 仅在确实无法推进、需要用户输入或外部状态变更时才使用
+- 不因任务困难、缓慢或需要澄清而标记 blocked
+
+### 预算跟踪
+
+`checkTokenBudget()`（定义于 `src/query/tokenBudget.ts`）根据 token 消耗决定是否继续自动续跑：
+
+- 使用 `createBudgetTracker()` 跟踪每次续跑的 token 消耗
+- `COMPLETION_THRESHOLD = 0.9`：token 消耗达到预算的 90% 时停止
+- `DIMINISHING_THRESHOLD = 500`：连续 3 次续跑且每次增量 < 500 token 时视为收益递减
+- 返回 `continue` 或 `stop` 决策
+
+---
+
+## Auto Mode（自动模式）
+
+### 激活方式
+
+- 用户通过 `/goal <objective>` 设置目标后自动进入自动模式
+- Plan 模式下自动模式被禁用（`inPlanMode` 检查）
+
+### 自动续跑机制
+
+每次 Agent 响应完成后，`useGoalAutoContinue` hook 自动向命令队列注入 `[goal] Continue` 提示：
+
+```typescript
+const prompt = buildContinuationPrompt(goal, now)
+enqueue({
+  mode: 'prompt',
+  value: prompt,
+  priority: 'later',
+  isMeta: true,
+})
+```
+
+- 只在 `pursuing` 状态下触发
+- 跳过 plan 模式
+- 用户输入优先于自动续跑（有阻塞性用户输入时不注入）
+- 避免为同一目标重复排队
+
+### update_goal 工具
+
+Agent 可通过 `update_goal` 工具报告进度：
+
+- `status='complete'`：目标达成，停止续跑
+- `status='blocked'`：受阻，需用户介入
+- 调用时必须包含 `goal_id`（与目标 ID 匹配）
+
+### 目标管理命令
+
+| 命令 | 功能 |
+|------|------|
+| `/goal <objective>` | 设置新目标（若已有活跃目标则提示覆盖确认） |
+| `/goal set <objective>` | 同上 |
+| `/goal pause` | 暂停当前目标 |
+| `/goal resume` | 恢复被暂停的目标（重置续跑计数和预算窗口） |
+| `/goal edit <new objective>` | 编辑目标描述 |
+| `/goal clear` | 清除当前目标 |
+| `/goal`（无参数） | 查看当前目标状态 |
+
+---
+
+## 查询循环（query.ts）
+
+### queryLoop() 主循环
+
+`src/query.ts` 中的 `queryLoop()` 是 Agent 的核心执行循环，在 `QueryEngine.ts` 中被调用。每次迭代处理一个完整的模型调用���期：
+
+```
+模型调用 → 流式响应处理 → 工具执行 → stop hooks → 继续决策
+```
+
+1. **模型调用**：`queryModelWithStreaming()` 发送消息到 API
+2. **流处理**：处理 `content_block_start/delta` 事件
+3. **工具执行**：检测 `tool_use` 并执行
+4. **stop hooks**：执行 `handleStopHooks()`（记忆提取、自动 dream、prompt 建议等）
+5. **继续决策**：检查是否需要继续循环（工具调用、max_output_tokens 恢复、goal 续跑）
+
+### max_output_tokens 恢复
+
+当模型响应被 `max_output_tokens` 截断时，queryLoop 提供最多 **3 次** 恢复尝试（`MAX_OUTPUT_TOKENS_RECOVERY_LIMIT`）：
+
+1. 注入恢复提示，指导模型从中断处继续
+2. 若 8K 默认输出限制触发，自动升级到 64K（一次，`tengu_otk_slot_v1` 功能门控）
+3. 恢复尝试耗尽后，将错误信息输出给用户
+
+相关变量（`src/query.ts`）：
+- `maxOutputTokensRecoveryCount`：当前恢复尝试次数
+- `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3`：最大恢复次数
+- `ESCALATED_MAX_TOKENS`：升级后的输出 token 上限
+
+### Reactive Compaction
+
+当上下文超出 API 限制时自动触发压缩：
+
+- `hasAttemptedReactiveCompact`：防止在同一轮迭代中重复压缩
+- 上下文超时（prompt-too-long）触发的压缩流程
+- 压缩后保持 stop hooks 的阻塞错误处理
+- 保留反应式压缩保护（不因 stop hook 错误而重置，防止无限循环）
+
+---
+
+## Task 系统
+
+Task（任务）系统管理 Agent 派发的异步子任务。
+
+### Task 类型
+
+定义于 `src/Task.ts`：
+
+| 类型 | 标识 | 用途 |
+|------|------|------|
+| `local_bash` | `b` | 本地 Shell 命令执行 |
+| `local_agent` | `a` | 本地子 Agent |
+| `remote_agent` | `r` | 远程 Agent |
+| `in_process_teammate` | `t` | 进程内队友 |
+| `local_workflow` | `w` | 本地工作流脚本 |
+| `dream` | `d` | 记忆整理任务 |
+| `monitor_mcp` | `m` | MCP 监控 |
+
+### 状态
+
+```
+pending → running → completed / failed / killed
+```
+
+- `pending`：等待分配
+- `running`：正在执行
+- `completed`：正常完成
+- `failed`：执行失败
+- `killed`：被终止
+
+### 后台/前台任务
+
+任务系统区分前台任务（阻塞用户交互）和后台任务（在后台运行），但 Task 类型本身不区分配置字段；区分体现在调用上下文中。
+
+### 任务 ID 生成
+
+`generateTaskId()`（`src/Task.ts`）生成格式为 `{类型前缀}{8位随机字母数字}` 的 ID：
+- 使用 `randomBytes(8)` 生成安全随机数
+- 36 进制字母表（数字 + 小写字母）
+- 36^8 ≈ 2.8 万亿种组合，抗暴力枚举
+
+### stopTask（优雅终止）
+
+Task 的 `kill()` 方法实现优雅终止，每个 Task 类型提供独立的 `kill` 实现（`src/tasks.ts`）：
+
+```typescript
+export type Task = {
+  name: string
+  type: TaskType
+  kill(taskId: string, setAppState: SetAppState): Promise<void>
+}
+```
+
+### 任务注册
+
+`src/tasks.ts` 中的 `getAllTasks()` 收集所有可用 Task：
+- 始终注册：`LocalShellTask`, `LocalAgentTask`, `RemoteAgentTask`, `DreamTask`
+- 条件注册（通过 feature gate）：`LocalWorkflowTask`, `MonitorMcpTask`

docs/coordinator/multi-agent.md

@@ -0,0 +1,205 @@
+# Coordinator 多代理模式
+
+## 概述
+
+Coordinator 模式是 VersperClaw 的一种高级执行模式，允许一个协调者（Coordinator）LLM 通过 `AgentTool` 派生子代理（Worker）并行执行任务。通过 `CLAUDE_CODE_COORDINATOR_MODE` 环境变量激活。
+
+### 激活方式
+
+```bash
+export CLAUDE_CODE_COORDINATOR_MODE=1
+```
+
+检测逻辑位于 `src/coordinator/coordinatorMode.ts`：
+
+```typescript
+export function isCoordinatorMode(): boolean {
+  if (feature('COORDINATOR_MODE')) {
+    return isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
+  }
+  return false
+}
+```
+
+### 会话模式匹配
+
+`matchSessionMode()` 确保恢复的会话与当前 coordinator 模式一致。如果环境变量与会话存储的模式不匹配（例如在 coordinator 模式下创建会话，然后在 normal 模式下恢复），会自动翻转环境变量并记录事件。
+
+---
+
+## 工作模式
+
+### 核心架构
+
+```
+User → Coordinator LLM → AgentTool → Worker 1
+                                 → Worker 2
+                                 → Worker 3 (并行)
+```
+
+- **Coordinator LLM**：接收用户请求，制定计划，派发任务，综合结果
+- **Worker**：通过 `AgentTool` 派生的子代理，执行具体任务
+- **通信**：Worker 结果通过 `<task-notification>` XML 格式返回
+
+### Worker 通信格式
+
+Worker 完成时，结果以 `user-role` 消息形式送达 Coordinator：
+
+```xml
+<task-notification>
+  <task-id>{agentId}</task-id>
+  <status>completed|failed|killed</status>
+  <summary>{human-readable status summary}</summary>
+  <result>{agent's final text response}</result>
+  <usage>
+    <total_tokens>N</total_tokens>
+    <tool_uses>N</tool_uses>
+    <duration_ms>N</duration_ms>
+  </usage>
+</task-notification>
+```
+
+Coordinator 必须区分工作结果消息和真实用户消息：工作结果包含 `<task-notification>` 标签。
+
+---
+
+## 工作流：四阶段模型
+
+### Phase 1: Research（研究）
+- Coordinator 并行启动多个 Worker 进行独立研究
+- 每个 Worker 负责调查代码库的不同方面
+- 只读任务，可自由并行
+
+### Phase 2: Synthesis（综合）
+- Coordinator **亲自**阅读所有研究发现
+- 理解问题本质，编写具体的实现规格
+- **关键原则**：Coordinator 必须理解研究发现再分配任务，不能将理解工作委托给 Worker
+
+### Phase 3: Implementation（实现）
+- 根据综合后的规格派发实现任务
+- 按文件集串行处理写操作，避免冲突
+
+### Phase 4: Verification（验证）
+- 独立的 Worker 验证实现结果
+- 真正的验证意味着证明代码工作，而非确认代码存在
+- 测试、类型检查和边缘用例
+
+---
+
+## 并行策略
+
+### 只读任务全并行
+研究阶段的所有 Worker 可同时启动，互不影响。
+
+### 写任务按文件集串行
+实现阶段的写操作需谨慎：同一组文件的操作需要串行执行。
+
+### 验证与实现可部分并行
+实现的不同文件区域可同时进行验证。
+
+---
+
+## 工具集
+
+Coordinator 拥有以下专用工具（定义于 `src/tools/AgentTool/AgentTool.tsx`）：
+
+| 工具 | 用途 |
+|------|------|
+| `AgentTool`（`Agent`） | 创建新的 Worker |
+| `SendMessageTool` | 向已存在的 Worker 发送后续指令 |
+| `TaskStopTool` | 停止正在运行的 Worker |
+| `subscribe_pr_activity` | 订阅 GitHub PR 事件 |
+
+### AgentTool 的使用
+
+```typescript
+AgentTool({
+  description: "Investigate auth bug",
+  subagent_type: "worker",
+  prompt: "..."
+})
+```
+
+重要规则：
+- 不要用一个 Worker 去检查另一个 Worker 的状态——Worker 完成时会自动通知
+- 不要为简单的文件读取或命令执行创建 Worker
+- 不要设置 model 参数——Worker 使用默认模型
+- 已完成工作的 Worker 应通过 `SendMessageTool` 继续使用其加载的上下文
+
+---
+
+## Prompt 编写规则
+
+### Worker 看不到 Coordinator 的对话
+
+每个 Worker prompt 必须**自包含**，包含执行任务所需的全部信息。Coordinator 不能假设 Worker 知道对话中发生过什么。
+
+### 好的 Prompt 示例
+
+```typescript
+// 好的 prompt：包含具体路径、行号和精确指令
+AgentTool({
+  prompt: "Fix the null pointer in src/auth/validate.ts:42. " +
+    "The user field can be undefined when the session expires. " +
+    "Add a null check and return early with an appropriate error. " +
+    "Commit and report the hash."
+})
+```
+
+### 坏的 Prompt 示例（反模式）
+
+```typescript
+// 坏的 prompt：模糊、依赖上下文
+AgentTool({ prompt: "Fix the bug we discussed" }) // 错误：Worker 看不到讨论
+AgentTool({ prompt: "Based on your findings, implement the fix" }) // 错误：懒惰的委托
+```
+
+### 目的陈述
+
+为 Prompt 添加目的说明，帮助 Worker 校准深度和重点：
+
+- "This research will inform a PR description — focus on user-facing changes."
+- "I need this to plan an implementation — report file paths, line numbers, and type signatures."
+
+### continue vs spawn 的选择
+
+| 场景 | 策略 | 原因 |
+|------|------|------|
+| 研究恰好覆盖了需编辑的文件 | **Continue**（SendMessageTool） | Worker 已有文件在上下文中 |
+| 研究范围广，实现范围窄 | **Spawn fresh**（AgentTool） | 避免携带探索噪音 |
+| 纠正错误或扩展近期工作 | **Continue** | Worker 有错误上下文 |
+| 验证其他 Worker 的代码 | **Spawn fresh** | 验证者需以新视角查看代码 |
+| 完全不同的任务 | **Spawn fresh** | 无有用上下文可复用 |
+
+---
+
+## 实现细节
+
+### 核心文件
+
+| 文件 | 路径 | 用途 |
+|------|------|------|
+| coordinatorMode.ts | `src/coordinator/coordinatorMode.ts` | Coordinator 模式检测、会话匹配、用户上下文构建 |
+| AgentTool.tsx | `src/tools/AgentTool/AgentTool.tsx` | Agent 工具的实现 |
+| builtInAgents.ts | `src/tools/AgentTool/builtInAgents.ts` | 内置 Agent 定义 |
+
+### Worker 工具白名单
+
+内部 Worker 工具（由 `INTERNAL_WORKER_TOOLS` 定义的集合）对 Worker 不可见：
+
+- `TeamCreateTool`
+- `TeamDeleteTool`
+- `SendMessageTool`
+- `SyntheticOutputTool`
+
+在简单模式（`CLAUDE_CODE_SIMPLE`）下，Worker 仅有权访问：Bash、Read、Edit 工具，外加 MCP 工具。
+
+### Worker 错误处理
+
+当 Worker 报告失败时：
+- 使用 `SendMessageTool` 继续同一 Worker——它保留完整的错误上下文
+- 如果纠正尝试也失败，尝试不同方法或报告用户
+
+### 停止 Worker
+
+使用 `TaskStopTool` 停止方向错误的 Worker。已停止的 Worker 可通过 `SendMessageTool` 继续。

docs/friend/architecture.md

@@ -0,0 +1,419 @@
+# Friend 系统架构
+
+本文档详细描述 Friend VRM 桌面伴侣系统的各个组件架构。
+
+---
+
+## 1. FriendService — 核心编排器
+
+**文件**: `src/friend/FriendService.ts` (~31KB, 897 行)
+
+### 1.1 生命周期管理
+
+```
+start() ──► 状态: 'starting'
+    │
+    ├── 初始化 Silero VAD (非致命失败，失败后语音捕获降级为 F2-only)
+    │       └── 配置: threshold 0.75, preSpeechTriggerFrames 10, redemptionFrames 20
+    │
+    └── 状态: 'running'
+
+stop() ──► 停止语音捕获 → 清理 STT 连接 → 状态: 'stopped'
+```
+
+### 1.2 React external store 接口
+
+FriendService 实现了类似 React `useSyncExternalStore` 的接口：
+
+```typescript
+subscribe(listener: Listener): () => void       // 添加状态监听
+subscribeToInbound(listener): () => void         // 监听用户输入事件
+getStateSnapshot(): FriendServiceState           // 获取当前状态快照
+```
+
+`FriendServiceState` 包含：
+- `status`: `'stopped' | 'starting' | 'running' | 'error'`
+- `lastError`: 可选错误信息
+- `displayClientCount`: SSE 显示器客户端数量
+- `captureStatus`: 语音捕获状态（`capturing` + `interimText`）
+
+### 1.3 文本中继
+
+```typescript
+sendText(text: string): void
+```
+
+流程：
+1. 通知所有 `inboundListeners`（bridge hook 用于 turn tracking）
+2. 动态导入 `messageQueueManager.enqueue()`（避免循环依赖）
+3. 使用 `bridgeOrigin: true` 和 `origin: { kind: 'channel', server: 'friend' }` 标记来源
+
+### 1.4 语音捕获
+
+参见 [语音捕获与 VAD 策略](voice-vad.md) 详细文档。
+
+```
+startVoiceCapture()
+    │
+    ├── 检测 STT provider（自动降级）
+    ├── 创建 STT 连接（8s 超时）
+    ├── 启动 arecord/parecord 子进程（500ms 验证窗口）
+    └── 启动 VAD 检测
+```
+
+### 1.5 静音系统
+
+AI 处理全过程阻止麦克风采音进入 STT/VAD，防止 TTS 播放时的回声。
+
+```
+startAiTurnMute()
+    │ muted = true, VAD pause
+    │ 设置 30s 安全性计时器
+    │
+    ├── AI 处理 → TTS 生成
+    │
+    └── extendMuteForTts(audioId)
+        │ 解析 MP3 精确时长
+        │ 重置计时器为精确播放时长
+        │
+        └── unmute()
+            │ muted = false, VAD resume
+```
+
+### 1.6 STT 自动检测
+
+```typescript
+detectAvailableSttProvider()
+    │
+    ├── 1. Groq Whisper API (最快, REST 调用)
+    ├── 2. Local Whisper (pip install openai-whisper)
+    ├── 3. Anthropic Voice Stream
+    ├── 4. Doubao ASR (检查 ~/.claude/tts/doubao/credentials.json)
+    │
+    └── 全不可用则抛出错误
+```
+
+### 1.7 TTS 生成
+
+```typescript
+generateTts(text: string)
+    │
+    ├── prefs.provider === 'qwen' + prefs.qwenKey 存在
+    │   └── Qwen DashScope TTS (qwen3-tts-flash)
+    │
+    └── else
+        └── Edge TTS (node-edge-tts, 默认 zh-CN-XiaoxiaoNeural)
+```
+
+### 1.8 SSE 广播
+
+```typescript
+broadcastResponse(text: string)
+    │
+    ├── broadcastToVrm({ text })           // 发送文字到前端 TextBubble
+    ├── if TTS enabled:
+    │   ├── generateTts(text)
+    │   ├── broadcastToVrm({ audioUrl, sendFirstTts: true })
+    │   └── extendMuteForTts(audioId)
+    └── broadcastToVrm({ replyDone: true }) // 信号回复完成
+```
+
+### 1.9 MP3 时长解析
+
+`getMp3DurationMs()` 方法使用帧同步头扫描法精确计算 MP3 时长：
+
+1. 跳过 ID3v2 标签头
+2. 查找前两个帧同步字（0xFF + 0xE0）
+3. 计算实际帧间隔（CBR 模式）
+4. 解析帧头获取采样率和每帧采样数
+5. 按步长计数帧数
+6. 计算 `(帧数 * 每帧采样数 / 采样率) * 1000`
+
+---
+
+## 2. SSE 模块
+
+**文件**: `src/friend/sse.ts`
+
+### 2.1 客户端注册表
+
+```typescript
+Set<SseClient>  // 全局 SSE 客户端集合
+```
+
+- `addSseClient(client)`: 注册新客户端
+- `removeSseClient(client)`: 移除客户端
+- `getSseClientCount()`: 获取活跃客户端数
+- `createSseClientId()`: 生成唯一 ID (`sse-{counter}-{timestamp}`)
+
+### 2.2 VrmBroadcastPayload 类型
+
+```typescript
+type VrmBroadcastPayload = {
+  text?: string;           // 回复文字
+  emotion?: string;        // 表情名
+  emotionIntensity?: number; // 表情强度 0-1
+  audioUrl?: string;       // TTS 音频 URL
+  audioIndex?: number;     // 音频索引（多句排序）
+  clearText?: boolean;     // 清空气泡文字
+  imageUrl?: string;       // 显示图片
+  moodDelta?: number;      // 心情变化
+  moodIndex?: number;      // 当前心情指数 0-100
+  sendFirstTts?: boolean;  // 开始 TTS 播放信号
+  appendText?: boolean;    // 追加文字（后续句子）
+  replyDone?: boolean;     // 回复结束信号
+};
+```
+
+### 2.3 广播机制
+
+```typescript
+broadcastToVrm(payload: VrmBroadcastPayload)
+    ├── 序列化为 SSE data 格式: `data: {json}\n\n`
+    ├── 遍历所有客户端，逐个写入
+    └── 写入失败的客户端自动移除
+```
+
+### 2.4 连接建立
+
+`createSseResponse()` 创建 Bun ReadableStream，返回 `text/event-stream` 响应。
+初始发送空行以确认连接建立。客户端断开时自动取消注册。
+
+---
+
+## 3. HTTP 服务器
+
+**文件**: `src/friend/server.ts`
+
+### 3.1 Bun.serve() 配置
+
+- 端口: 3456
+- 主机: 127.0.0.1
+- `idleTimeout`: 60s（容纳慢速 STT 初始化）
+
+### 3.2 端口管理
+
+`freePort()` 方法在启动时尝试释放被占用的端口：
+1. 使用 `ss -tlnp` 查找端口占用进程
+2. 验证进程是否为 `bun`/`VersperClaw`/`claude-*`/`node`
+3. 发送 SIGTERM，等待 3s，失败则 SIGKILL
+
+### 3.3 路由
+
+| 路径 | 方法 | 功能 |
+|------|------|------|
+| `/plugins/friend/events` | GET | SSE 事件流 |
+| `/plugins/friend/*` | ANY | Friend API 路由（见下文） |
+| `/friend/*` | GET | 静态文件 |
+| WebSocket 升级 | ANY | 返回 426（不支持） |
+
+---
+
+## 4. Friend API 路由
+
+**文件**: `src/server/api/friend.ts` (~793 行)
+
+### 4.1 完整路由表
+
+| 端点 | 方法 | 功能 |
+|------|------|------|
+| `/plugins/friend/events` | GET | SSE 事件流 |
+| `/plugins/friend/audio/:id` | GET | 提供 TTS 音频文件 |
+| `/plugins/friend/media/:id` | GET | 提供媒体文件 |
+| `/plugins/friend/chat` | POST | 文字聊天消息 |
+| `/plugins/friend/voice/stt-segment` | POST | 浏览器 VAD 语音片段 |
+| `/plugins/friend/voice/start` | POST | 开始服务器端语音捕获 |
+| `/plugins/friend/voice/stop` | POST | 停止语音捕获 |
+| `/plugins/friend/voice/status` | POST | 获取捕获状态 |
+| `/plugins/friend/touch` | POST | 触摸交互事件 |
+| `/plugins/friend/voice` | GET/POST | 语音设置 |
+| `/plugins/friend/stt/config` | GET | STT 配置 |
+| `/plugins/friend/stt/file` | POST | 文件转录 |
+| `/plugins/friend/preview` | POST | TTS 预览 |
+| `/plugins/friend/settings` | GET/POST | 通用设置 |
+| `/plugins/friend/persona` | GET/POST | 角色设定 |
+| `/plugins/friend/model/list` | GET | 模型列表 |
+| `/plugins/friend/model/serve/:file` | GET | 提供 VRM 模型文件 |
+| `/plugins/friend/model/import` | POST | 导入 VRM 模型 |
+| `/plugins/friend/history` | GET | 对话历史 |
+| `/plugins/friend/context/clear` | POST | 清空上下文 |
+| `/plugins/friend/mood/adjust` | POST | 调整心情 |
+| `/plugins/friend/session/memo` | POST | 记录会话备注 |
+| `/plugins/friend/dance/list` | GET | 舞蹈列表 |
+| `/plugins/friend/dance/import` | POST | 导入舞蹈 VMD/MP3 |
+| `/plugins/friend/dance/delete` | POST | 删除舞蹈 |
+| `/plugins/friend/dance/serve/:file` | GET | 提供舞蹈文件 |
+| `/plugins/friend/persona/screenshot` | POST | 保存 VRM 截图 |
+| `/plugins/friend/persona/generate` | POST | AI 生成角色设定 |
+| `/plugins/friend/screen/observe` | POST | 屏观察触发 |
+| `/friend/api/window-close` | POST | Tauri 窗口关闭事件 |
+
+### 4.2 MIME 类型支持
+
+- 音频: `.mp3`, `.opus`, `.ogg`, `.wav`, `.webm`
+- 图片: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, `.bmp`
+
+---
+
+## 5. TTS 服务
+
+**文件**: `src/friend/tts.ts`
+
+### 5.1 Edge TTS
+
+```typescript
+edgeTts({ text, voice? })
+    ├── 使用 node-edge-tts 库
+    ├── 默认语音: zh-CN-XiaoxiaoNeural
+    ├── 输出: 临时目录中的 MP3 文件
+    └── 返回: { success, audioPath, error }
+```
+
+### 5.2 Qwen DashScope TTS
+
+```typescript
+qwenTts({ text, apiKey, voice?, model?, language? })
+    ├── 端点: dashscope.aliyuncs.com / dashscope-intl.aliyuncs.com
+    ├── 默认模型: qwen3-tts-flash
+    ├── 默认语音: Cherry
+    ├── 超时: 30s
+    └── 返回: { success, audioPath, error }
+```
+
+### 5.3 音频文件注册表
+
+```typescript
+audioFiles = Map<string, string>  // id → 文件路径
+
+registerAudioFile(filePath)       // 注册文件，5 分钟后自动过期
+getAudioFile(id)                  // 获取文件路径
+```
+
+---
+
+## 6. STT 服务
+
+**文件**: `src/friend/stt-service.ts`
+
+提供基于文件的语音转录，用于 REST 端点。流式/进程内捕获由 FriendService 处理。
+
+支持 Provider:
+- `anthropic`: Anthropic Voice Stream
+- `local`: Local Whisper (openai-whisper)
+- `doubao`: Doubao ASR
+- `browser`: 浏览器 VAD (仅前端的占位符)
+
+---
+
+## 7. VAD 服务
+
+**文件**: `src/friend/voice/vad-service.ts`
+
+参见 [语音捕获与 VAD 策略](voice-vad.md) 详细文档。
+
+### 7.1 核心架构
+
+- **模型**: Silero VAD legacy ONNX (来自 `@ericedouard/vad-node-realtime`)
+- **运行时**: onnxruntime-web WASM 后端（Bun 不兼容 onnxruntime-node）
+- **帧大小**: 512 采样 @ 16kHz = 32ms/帧
+- **预处理**: RMS 能量预过滤 (<0.004 跳过推理)
+
+### 7.2 状态机
+
+```
+pre-speech phase (preSpeechCount < preSpeechTriggerFrames)
+    │  ├── 非语音帧 → 重置计数
+    │  └── 连续语音帧达到阈值 → 进入 speaking
+    ▼
+speaking (confirmed speech segment)
+    │  ├── 语音帧 → 重置 redemptionCounter
+    │  └── 静音帧 → redemptionCounter++
+    │       └── redemptionCounter >= redemptionFrames → endSpeech()
+    ▼
+silence redemption (grace period)
+    └── endSpeech() → onSpeechEnd 回调
+```
+
+---
+
+## 8. 偏好设置
+
+**文件**: `src/friend/prefs.ts`
+
+```typescript
+interface FriendPrefs {
+  enabled?: boolean;
+  voice?: string;              // TTS 语音
+  provider?: string;           // TTS provider (edge | qwen)
+  qwenKey?: string;            // Qwen API Key
+  qwenModel?: string;          // Qwen 模型名
+  modelPath?: string;          // VRM 模型路径
+  ttsEnabled?: boolean;        // TTS 开启
+  showText?: boolean;          // 显示文字气泡
+  hideUI?: boolean;            // 隐藏 UI
+  tracking?: 'mouse' | 'camera';  // 眼球追踪模式
+  volume?: number;             // 音量 0-1
+  uiAlign?: 'left' | 'right';  // UI 对齐
+  screenObserve?: boolean;     // 屏幕观察
+  screenObserveInterval?: number; // 观察间隔(秒)
+  language?: 'zh' | 'en';     // 语言
+  currentDance?: string;       // 当前舞蹈
+  hideMood?: boolean;          // 隐藏心情
+  sttProvider?: string;        // STT provider
+  sttLanguage?: string;        // STT 语言
+  groqApiKey?: string;         // Groq API Key
+}
+```
+
+持久化路径: `~/.config/VersperClaw/friend.json`
+
+---
+
+## 9. Tauri Launcher
+
+**文件**: `src/friend/tauri-launcher.ts`
+
+- 查找 Tauri 二进制文件（release → debug）
+- 启动为 detached 子进程
+- 管道 stdout/stderr 到主进程日志
+- 退出时自动清理
+
+启动路径: `src/components/friend/frontend/src-tauri/target/{release|debug}/versperclaw-friend`
+
+---
+
+## 10. 常量
+
+**文件**: `src/friend/constants.ts`
+
+```typescript
+GATEWAY_URL = 'http://127.0.0.1:3456'
+FRIEND_SESSION_KEY = 'agent:main:main'
+CHANNEL_ID = 'friend'
+VALID_EMOTIONS = ['happy', 'sad', 'angry', 'surprised', 'think', 'awkward',
+                  'question', 'curious', 'neutral', 'love', 'flirty',
+                  'greeting', 'relaxed']
+```
+
+---
+
+## 依赖关系图
+
+```
+server.ts ──┬── sse.ts ──────────► FriendService.ts ──┬── tts.ts
+            │                    │                    ├── vad-service.ts
+            │                    │                    ├── prefs.ts
+            │                    │                    └── text-utils.ts
+            │                    │
+            └── api/friend.ts ───┤
+                                ├── sse.ts
+                                ├── prefs.ts
+                                ├── tts.ts
+                                ├── stt-service.ts
+                                └── FriendService.ts
+
+FriendEmotionTool.ts ──► sse.ts, prefs.ts
+FriendScreenObserveTool.ts ──► sse.ts
+
+tauri-launcher.ts (独立启动)
+```

docs/friend/data-flow.md

@@ -0,0 +1,369 @@
+# Friend 数据流
+
+本文档详细描述 Friend 系统中的四种核心数据流，以及 SSE 事件格式规范。
+
+---
+
+## 1. 文字对话流
+
+用户在前端输入框输入文字，按下 Enter 发送。
+
+```
+用户输入文字
+    │
+    ▼
+ChatInput.tsx  ── POST /plugins/friend/chat ──────────────────┐
+    │                              { message: "你好" }         │
+    │                                                          │
+    ▼                                                          │
+handleFriendApi()  ── friendService.start()                    │
+    │                 friendService.sendText(message)           │
+    ▼                                                          │
+FriendService.sendText()                                       │
+    │                                                          │
+    ├── 通知 inboundListeners (bridge hook turn tracking)      │
+    │                                                          │
+    └── messageQueueManager.enqueue()                          │
+        │  { mode: 'prompt', skipSlashCommands: true,          │
+        │    bridgeOrigin: true, origin: { server: 'friend' }} │
+        │                                                      │
+        ▼                                                      │
+    AI Provider (Anthropic/NVIDIA/OpenAI)                      │
+        │                                                      │
+        ├── 处理消息                                           │
+        ├── 可调用 friend_emotion 工具设置表情                  │
+        ├── 可调用 friend_screen_observe 观察屏幕               │
+        │                                                      │
+        ▼                                                      │
+    AI 回复流回 (通过 useFriendBridge / REPL)                   │
+        │                                                      │
+        ▼                                                      │
+    FriendService.broadcastResponse(text)                      │
+        │                                                      │
+        ├── broadcastToVrm({ text })                           │
+        │       │                                              │
+        │       ▼ SSE data                                     │
+        │   TextBubble 收到                                     │
+        │       │                                              │
+        │       ├── 重置气泡，显示文字                          │
+        │       ├── 启动打字机效果 (逐字符显示)                 │
+        │       │   - CJK: 200ms/char (TTS开启) / 80ms (关闭)  │
+        │       │   - English: 60ms/char (TTS开启) / 30ms (关闭)│
+        │       ├── 打字机完成后渲染 Markdown                    │
+        │       └── 1秒后触发 onMessage → VRMScene 表情动作    │
+        │                                                      │
+        ├── if TTS enabled:                                    │
+        │   ├── generateTts(text)                              │
+        │   │   ├── stripForTts() 清洗文本                     │
+        │   │   └── EdgeTTS 或 QwenTTS 生成 MP3                │
+        │   │                                                 │
+        │   ├── broadcastToVrm({ audioUrl, sendFirstTts })     │
+        │   │       │                                           │
+        │   │       ▼ SSE data                                 │
+        │   │   TextBubble 开始音频队列播放                     │
+        │   │       │                                           │
+        │   │       └── LipSync.playAudio(url)                 │
+        │   │           ├── fetch 音频文件                      │
+        │   │           ├── decodeAudioData                     │
+        │   │           ├── 连接到 lipSyncNode (分析) + gainNode (扬声器) │
+        │   │           └── 播放时实时更新 VRM 嘴形             │
+        │   │                                                 │
+        │   └── extendMuteForTts(audioId)                      │
+        │       └── 精确计算 MP3 时长，更新静音定时器           │
+        │                                                      │
+        └── broadcastToVrm({ replyDone: true })                │
+                │                                               │
+                ▼ SSE data                                     │
+            TextBubble 调度气泡隐藏 (2s 延迟)                  │
+                或等待后续 appendText 消息                      │
+```
+
+---
+
+## 2. 语音捕获流 (F2 通话模式)
+
+用户按下 F2 进入连续语音通话模式，再次按下 F2 结束通话。
+
+### 2.1 启动通话
+
+```
+用户按 F2
+    │
+    ▼
+ChatInput.startVoiceCall()
+    │
+    ├── setVoiceCallActive(true)
+    │
+    └── useServerStt.startStreaming()
+        │
+        └── POST /plugins/friend/voice/start
+            │
+            ▼
+        handleFriendApi()
+            │
+            └── friendService.startVoiceCapture()
+                │
+                ├── 检测 STT provider (Groq→Whisper→Anthropic→Doubao)
+                │
+                ├── startSttConnection() (8s 超时)
+                │   ├── Groq: connectGroqStream()
+                │   ├── Local: connectLocalWhisperStream()
+                │   ├── Anthropic: connectVoiceStream()
+                │   └── Doubao: connectDoubaoStream()
+                │
+                ├── loadAudioCapture()
+                │   ├── 尝试 arecord (ALSA)
+                │   │   args: -D default -r 16000 -f S16_LE -c 1 -t raw -q
+                │   ├── 失败则尝试 parecord (PulseAudio)
+                │   │   args: --raw --rate=16000 --format=s16le --channels=1
+                │   └── 500ms 验证窗口: 确认子进程输出音频数据
+                │
+                ├── arecord 数据回调:
+                │   ├── if not muted → 转发到 STT connection.send(chunk)
+                │   └── if not muted → 转发到 VAD processAudio(float32)
+                │
+                └── vadInstance.start()
+```
+
+### 2.2 语音检测与转录
+
+```
+麦克风音频流 (16kHz S16LE)
+    │
+    ├──► STT Connection.send(chunk)  (实时流式转录)
+    │
+    └──► SileroVad.processAudio(float32)
+            │
+            ├── RMS 预过滤 (阈值 0.004)
+            │   ├── < 阈值 → 概率 = 0 (跳过推理)
+            │   └── >= 阈值 → ONNX 推理
+            │
+            ├── 状态机
+            │   ├── pre-speech: 需要连续 10 帧 (~320ms) 确认说话
+            │   ├── speaking: 语音持续中
+            │   └── silence redemption: 连续 20 帧 (~640ms) 静音触发 endSpeech
+            │
+            └── onSpeechEnd callback
+                │
+                ▼
+            FriendService._flushVadSegment()
+                │
+                ├── 创建新的 STT 连接 (旧的连接继续处理)
+                │
+                ├── 等待旧连接 finalize()
+                │   └── 获取转录文本推入 captureTranscripts
+                │
+                ├── if 有转录文本:
+                │   ├── this.sendText(transcript)
+                │   │       │
+                │   │       ▼
+                │   │   messageQueueManager.enqueue() → AI 开始处理
+                │   │
+                │   └── this.startAiTurnMute()
+                │       ├── muted = true
+                │       ├── VAD pause
+                │       └── 30s 超时安全性定时器
+                │
+                └── 循环继续监听下一段语音
+```
+
+### 2.3 AI 回复与静音解除
+
+```
+AI 处理完成
+    │
+    ▼
+FriendService.broadcastResponse(text)
+    │
+    ├── broadcastToVrm({ text })          // 显示文字
+    │
+    ├── if TTS enabled:
+    │   ├── generateTts(text)
+    │   │       │
+    │   │       ▼
+    │   ├── broadcastToVrm({ audioUrl, sendFirstTts: true })
+    │   │
+    │   └── extendMuteForTts(audioId)
+    │       ├── getMp3DurationMs() 精确计算
+    │       ├── 取消 30s 安全性定时器
+    │       └── 设定精确的播放时长定时器
+    │
+    └── broadcastToVrm({ replyDone: true })
+        │
+        ▼
+    播放完成后 → unmute()
+        ├── muted = false
+        └── VAD resume (可继续接收语音)
+```
+
+### 2.4 结束通话
+
+```
+用户按 F2 (再次)
+    │
+    ▼
+ChatInput.endVoiceCall()
+    │
+    └── useServerStt.stopStreaming()
+        │
+        └── POST /plugins/friend/voice/stop
+            │
+            ▼
+        friendService.stopVoiceCapture()
+            │
+            ├── arecord.kill('SIGTERM') → 2s 后 SIGKILL
+            ├── capturing = false
+            ├── clearMute()
+            ├── VAD reset()
+            ├── STT connection.finalize() + close()
+            ├── 发送剩余转录文本
+            └── 返回完整转录
+```
+
+---
+
+## 3. 情绪表情流
+
+LLM 调用 `friend_emotion` 工具触发情绪更新。
+
+```
+LLM 处理完成，调用 friend_emotion 工具
+    │
+    ▼
+FriendEmotionTool.call({ emotion: 'happy', intensity: 0.8, mood_delta: 2 })
+    │
+    ├── broadcastToVrm({ emotion: 'happy', emotionIntensity: 0.8 })
+    │       │
+    │       ▼ SSE data
+    │   App.tsx handleVrmMessage
+    │       │
+    │       ├── emotionActionMap['happy'] = 'happy'
+    │       │
+    │       ├── sceneRef.current.setEmotionWithReset('happy', 5000, 0.8)
+    │       │       │
+    │       │       ▼
+    │       │   VRMScene.setEmotionWithReset (via forwardRef)
+    │       │       │
+    │       │       └── EmoteController.setEmotionWithReset('happy', 5000, 0.8)
+    │       │           ├── setEmotion('happy', 0.8)
+    │       │           │   ├── 获取 happy 的 blend shapes: [{name:'happy', val:0.2}, {name:'aa', val:0.8}]
+    │       │           │   ├── 应用 intensity: aa = 0.8*0.8 = 0.64, happy = 0.2*0.8 = 0.16
+    │       │           │   ├── isTransitioning = true
+    │       │           │   └── 记录目标 blendshape 值
+    │       │           │
+    │       │           └── setTimeout(5000ms → setEmotion('neutral'))
+    │       │
+    │       └── sceneRef.current.playAction('happy')
+    │               │
+    │               ▼
+    │           MotionController.playAction('happy')
+    │               ├── loadClip('happy.fbx')
+    │               ├── crossFadeTo(clip, 0.3s)
+    │               ├── LoopOnce + clampWhenFinished
+    │               └── 完成后 crossFade 回 idle 动画
+    │
+    ├── 处理 mood_delta
+    │   ├── 读取当前 moodIndex = 60
+    │   ├── newMood = clamp(60 + 2, 0, 100) = 62
+    │   ├── 持久化到 prefs
+    │   └── broadcastToVrm({ moodDelta: 2, moodIndex: 62 })
+    │           │
+    │           ▼ SSE data
+    │       MoodIndicator 收到
+    │           ├── 显示心情数值变化气泡 (+2)
+    │           ├── Canvas 动画: displayPercent 从 60 → 62 渐变
+    │           └── 5s 后自动隐藏
+    │
+    └── 返回 tool result
+```
+
+### 每帧更新循环 (VRMScene animate)
+
+```
+requestAnimationFrame 循环 (约 60fps)
+    │
+    ├── 1. MotionController.update(delta)
+    │   └── AnimationMixer.update(delta)
+    │
+    ├── 2. 应用 Relaxed Hand Pose (非舞蹈状态)
+    │   └── 手指自然弯曲 + 微妙颤动
+    │
+    ├── 3. Humanoid.update()
+    │
+    ├── 4. 眼球追踪 (camera 模式)
+    │   └── lookAtTarget = camera.position
+    │
+    ├── 5. LookAt.update(delta)
+    │
+    ├── 6. Eye Saccades Controller.update()
+    │   └── 每隔 400-1200ms 添加随机眼球微动偏移
+    │
+    ├── 7. Blink State Machine.update()
+    │   └── 随机眨眼 (间隔 1-6s, 时长 150ms, sin 曲线)
+    │
+    ├── 8. EmoteController.update(delta)
+    │   └── cubic ease 过渡到目标 blendshape 值
+    │
+    ├── 9. LipSync.update(vrm, delta)
+    │   ├── 读取 wlipsync 音频分析节点的音素权重
+    │   ├── 选择胜者/亚军音素
+    │   ├── Attack/Release 平滑 (50/30)
+    │   └── 设置 VRM 嘴形 blendshapes (aa, ee, ih, oh, ou)
+    │
+    ├── 10. ExpressionManager.update()
+    │
+    └── 11. SpringBoneManager.update(delta)
+        └── 物理头发/衣服/饰品模拟
+```
+
+---
+
+## 4. SSE 事件格式
+
+所有前端 SSE 事件通过 `GET /plugins/friend/events` 接收，格式为标准 SSE (`data: {json}\n\n`)。
+
+### 4.1 VrmBroadcastPayload 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `text` | string | 否 | AI 回复文字，TextBubble 显示并启动打字机效果 |
+| `emotion` | string | 否 | VRM 表情名，触发 EmoteController 切换 blend shapes |
+| `emotionIntensity` | number | 否 | 表情强度 0-1，默认 1 |
+| `audioUrl` | string | 否 | TTS 音频 URL，TextBubble 触发 LipSync 播放 |
+| `audioIndex` | number | 否 | 音频播放顺序索引，用于多句排序 |
+| `clearText` | boolean | 否 | 清空气泡文字和音频队列 |
+| `imageUrl` | string | 否 | 图片 URL，在气泡中显示 |
+| `moodDelta` | number | 否 | 心情变化量，MoodIndicator 显示浮动气泡 |
+| `moodIndex` | number | 否 | 当前心情指数 0-100，MoodIndicator Canvas 更新 |
+| `sendFirstTts` | boolean | 否 | 开始 TTS 播放的信号，重置音频队列 |
+| `appendText` | boolean | 否 | 追加文字模式，后续句子的文字和音频配对 |
+| `replyDone` | boolean | 否 | 回复完成信号，TextBubble 调度气泡隐藏 |
+
+### 4.2 典型回复序列
+
+```
+1. { text: "你好！今天心情不错啊！", replyDone: true }
+    → 显示文字，打字机效果，1s 后触发表情
+
+2. { text: "一起玩吧！" }
+   { audioUrl: "http://127.0.0.1:3456/plugins/friend/audio/123-1", sendFirstTts: true }
+   { replyDone: true }
+    → 显示文字 + 播放 TTS + 语音结束后隐藏气泡
+
+3. { text: "今天天气真好。" }
+   { audioUrl: "...", sendFirstTts: true, emotion: "happy", emotionIntensity: 0.8 }
+   { appendText: true, text: "要不要出去走走？", audioUrl: "...", audioIndex: 1 }
+   { appendText: true, text: "我知道一个好地方。", audioUrl: "...", audioIndex: 2 }
+   { replyDone: true }
+    → 多句子回复，每句独立音频，按索引顺序播放
+    → 第一句发送时触发 happy 表情
+
+4. { emotion: "think", emotionIntensity: 0.7 }
+    → 思考阶段的表情更新（LLM 处理中）
+
+5. { clearText: true }
+    → 清空气泡（新会话）
+
+6. { moodDelta: 3, moodIndex: 63 }
+    → 心情更新，显示 +3 浮动气泡，Canvas 液态填充变化
+```

docs/friend/emotion-map.md

@@ -0,0 +1,195 @@
+# 情绪 → 3D 表情映射
+
+Friend 系统支持 13 种情绪，每种映射到 VRM blend shapes 组合、过渡时间和肢体动作。
+
+---
+
+## 完整映射表
+
+数据来源: `src/components/friend/frontend/emote.ts`
+
+| 情绪 | Blend Shapes 组合 | 过渡时间 | 肢体动作 |
+|------|------------------|---------|---------|
+| `happy` | happy(0.2) + aa(0.8) | 0.4s | `happy` (开心.fbx) |
+| `sad` | sad(0.7) + oh(0.15) | 0.4s | `shy` (害羞.fbx) |
+| `angry` | angry(0.7) + ee(0.3) | 0.3s | `angry` (生气.fbx) |
+| `surprised` | surprised(0.8) + oh(0.4) | 0.15s | `excited` (兴奋.fbx) |
+| `think` | think(0.7) | 0.5s | `scratchHead` (挠头.vrma) |
+| `awkward` | sad(0.3) + ee(0.2) | 0.5s | `playFingers` (搓手.vrma) |
+| `question` | surprised(0.4) + think(0.3) | 0.4s | `point` (指点.fbx) |
+| `curious` | think(0.5) + surprised(0.2) | 0.4s | `scratchHead` (挠头.vrma) |
+| `neutral` | neutral(1.0) | 0.6s | `salute` (敬礼.fbx) |
+| `love` | happy(0.2) + relaxed(0.4) | 0.4s | `shy` (害羞.fbx) |
+| `flirty` | happy(0.2) + relaxed(0.3) + aa(0.15) | 0.4s | `shy` (害羞.fbx) |
+| `greeting` | happy(0.2) + aa(0.3) | 0.3s | `greeting` (招呼.fbx) |
+| `relaxed` | relaxed(0.8) | 0.5s | `salute` (敬礼.fbx) |
+
+### 使用的 VRM Blend Shapes
+
+VRM 标准 blendshape 名称及其对应的面部区域：
+
+| Blend Shape | 面部区域 |
+|-------------|---------|
+| `happy` | 嘴角上扬 (smile) |
+| `sad` | 嘴角下垂 |
+| `angry` | 皱眉 |
+| `surprised` | 眉毛上抬 |
+| `think` | 思考表情 |
+| `neutral` | 自然表情 |
+| `relaxed` | 放松表情 |
+| `aa` | 张嘴 (A 音) |
+| `ee` | 露齿 (E 音) |
+| `oh` | 嘟嘴 (O 音) |
+| `ih` | 微张嘴 (I 音, 主要用于唇同步) |
+| `ou` | 收唇 (U 音, 主要用于唇同步) |
+| `blink` | 闭眼 (由眨眼系统独立控制) |
+
+---
+
+## EmoteController 过渡系统
+
+**文件**: `src/components/friend/frontend/emote.ts`
+
+### 过渡算法
+
+```typescript
+// cubic ease 缓动函数
+setEmotion('happy', intensity = 0.8)
+    │
+    ├── 1. 获取情绪定义
+    │   happy: [{name:'happy', value:0.2}, {name:'aa', value:0.8}]
+    │
+    ├── 2. 乘以 intensity
+    │   happy = 0.2 * 0.8 = 0.16
+    │   aa    = 0.8 * 0.8 = 0.64
+    │
+    ├── 3. 记录当前 blendshape 值 (起始值)
+    │   currentValues = { happy: 0.05, aa: 0, ... }
+    │
+    ├── 4. 设置目标值
+    │   targetValues = { happy: 0.16, aa: 0.64 }
+    │
+    ├── 5. 开始过渡 (isTransitioning = true)
+    │
+    └── 每帧 update(deltaTime):
+        │
+        ├── transitionProgress += deltaTime / blendDuration(0.4s)
+        │
+        ├── if progress >= 1: transition end
+        │
+        ├── cubic ease:
+        │   t < 0.5 → 4 * t³
+        │   t >= 0.5 → 1 - (-2t + 2)³ / 2
+        │
+        └── value = start + (target - start) * ease(t)
+```
+
+### 自动回中系统
+
+```typescript
+setEmotionWithReset('happy', durationMs = 5000, intensity = 0.8)
+    ├── setEmotion('happy', 0.8)         // 立即开始过渡
+    └── setTimeout(5000ms)
+        └── setEmotion('neutral')         // 自动回中到自然表情
+```
+
+### 完整重置
+
+```typescript
+resetAll()
+    ├── 清除 resetTimer
+    ├── isTransitioning = false
+    ├── 将所有 blendshape 值设为 0
+    └── 清空 currentValues / targetValues
+```
+
+---
+
+## 情绪 → 动作映射
+
+**文件**: `src/components/friend/frontend/App.tsx`
+
+App.tsx 中的 `emotionActionMap` 定义了情绪与动作的关联：
+
+```typescript
+const emotionActionMap: Record<string, string> = {
+  think:     'scratchHead',  // 挠头
+  question:  'point',        // 指
+  curious:   'scratchHead',  // 挠头
+  happy:     'happy',        // 开心
+  surprised: 'excited',      // 兴奋
+  angry:     'angry',        // 生气
+  awkward:   'playFingers',  // 搓手指
+  sad:       'shy',          // 害羞
+  love:      'shy',          // 害羞
+  flirty:    'shy',          // 害羞
+  greeting:  'greeting',     // 招呼
+  relaxed:   'salute',       // 敬礼
+  neutral:   'salute',       // 敬礼
+}
+```
+
+动作文件类型：
+- `.vrma`: VRM Animation 格式 (挠头、搓手、伸展、叉腰)
+- `.fbx`: Mixamo FBX 格式 (开心、生气、招呼、兴奋、害羞、指点、敬礼、暴怒)
+
+---
+
+## 心情指数系统
+
+除了即时表情，Friend 还有持续的心情指数系统：
+
+```
+moodIndex: 0-100
+  ├── 0-29:  低 (灰色, rgb(160,168,180))
+  ├── 30-49: 偏低 (蓝色, rgb(78,168,222))
+  ├── 50-69: 中等 (绿色, rgb(72,199,142))
+  ├── 70-89: 良好 (橙色, rgb(255,165,70))
+  └── 90-100: 优秀 (粉色, rgb(255,107,157))
+```
+
+- LLM 通过 `friend_emotion` 工具的 `mood_delta` 参数调整 (-3 到 +3)
+- 前端 MoodIndicator 组件以液态填充柱状图 + 爱心图标可视化
+- Canvas 动画使用贝塞尔波浪动画和颜色渐变
+
+---
+
+## 触摸交互反应系统
+
+**文件**: `src/components/friend/frontend/App.tsx`
+
+6 个触摸区域各自有多个可能的反应：
+
+| 区域 | 可能的反应 (情绪 + 动作) |
+|------|------------------------|
+| head (头) | relaxed+happy, relaxed+shy, angry+angryPump, relaxed+excited |
+| arm (手臂) | surprised+excited, happy+happy, relaxed+greeting, relaxed+akimbo |
+| chest (胸) | angry+angryPump, angry+angry, angry+point |
+| belly (肚子) | angry+angryPump, angry+angry, awkward+playFingers |
+| buttocks (屁股) | angry+angryPump, angry+point, sad+shy |
+| leg (腿) | sad+shy, angry+angry, awkward+playFingers |
+
+触摸交互逻辑：
+1. 双击模型触发区域检测（射线检测 + 最近骨骼匹配）
+2. 随机选择该区域的一个反应组合
+3. 立即播放表情 + 动作
+4. 3s 冷却期写入 session memo（[用户摸了摸你的xx]）
+5. 60s 冷却期 + 50% 概率发送文字回复到 AI（POST /plugins/friend/touch）
+
+---
+
+## 空闲小动作系统
+
+当用户 30 秒无活动时，VRM 角色会自动做一些小动作：
+
+```
+idleMs >= 30,000ms → 每 15s 检查一次
+    │
+    ├── 50% 概率触发
+    ├── 随机选择 13 种情绪之一
+    ├── 随机选择 12 种动作之一
+    ├── 强度: 0.4-0.8 (随机)
+    └── 持续: 3-5s (随机)
+```
+
+此系统防止角色长时间静止不动，增加生动感。

docs/friend/frontend-3d.md

@@ -0,0 +1,573 @@
+# 前端 3D 渲染
+
+本文档描述 Friend VRM 桌面伴侣的前端 3D 渲染系统。
+
+---
+
+## 技术栈
+
+| 技术 | 用途 |
+|------|------|
+| **Three.js** | 3D 渲染引擎 |
+| **@pixiv/three-vrm** | VRM 模型加载与控制 |
+| **@pixiv/three-vrm-animation** | VRM 动画加载与 LookAt |
+| **@pixiv/three-vrm-animation** | VRMA 动画支持 |
+| **Tauri (WebKitGTK)** | 桌面窗口外壳 |
+| **React** | UI 框架 |
+| **Vite** | 前端构建工具 |
+| **Bun** | 构建运行环境 |
+| **CSS-in-JS** (内联 style) | 组件样式 |
+| **Lucide React** | 图标库 |
+| **marked** | Markdown 渲染 |
+| **wlipsync** | WebAudio 唇形同步 |
+| **Intl.Segmenter** | Unicode 字符分割 |
+
+---
+
+## VRMScene.tsx — 核心 3D 场景
+
+**文件**: `src/components/friend/frontend/components/VRMScene.tsx` (~871 行)
+
+### 组件接口
+
+通过 `forwardRef` 暴露的操作句柄：
+
+```typescript
+interface VRMSceneHandle {
+  setEmotion(emotion: string, intensity?: number): void
+  setEmotionWithReset(emotion: string, durationMs: number, intensity?: number): void
+  resetCamera(): void
+  setTrackingMode(mode: 'mouse' | 'camera'): void
+  playAction(name: string, hold?: boolean): void
+  captureScreenshot(): string | null
+  panCamera(dx: number, dy: number): void
+  rotateCamera(dx: number, dy: number): void
+  playDance(nameOrPreset: string | DancePreset): void
+  stopDance(): void
+  isDancing(): boolean
+  setBgmVolume(v: number): void
+  reset(): void
+}
+```
+
+### 场景初始化
+
+```typescript
+// VRMScene 组件创建时
+const renderer = new THREE.WebGLRenderer({
+  canvas,
+  alpha: true,              // 透明背景
+  antialias: true,          // 抗锯齿
+  preserveDrawingBuffer: true,  // 截图支持
+})
+renderer.setClearColor(0x000000, 0)  // 完全透明
+
+// 透视相机
+const FOV = 40
+const camera = new THREE.PerspectiveCamera(FOV, aspect, 0.1, 100)
+// 轨道控制: 围绕 pivot 点的球面坐标
+
+// 光照
+const ambientLight = new THREE.AmbientLight(0xffffff, 0.6)
+const directionalLight = new THREE.DirectionalLight(0xffffff, 1.2)  // 主光
+const fillLight = new THREE.DirectionalLight(0xffffff, 0.4)         // 补光
+```
+
+### 模型加载
+
+```typescript
+loader.load(modelPath, async (gltf) => {
+  // 1. 获取 VRM 数据
+  const loadedVrm = gltf.userData.vrm
+
+  // 2. 优化: 移除冗余顶点 + 合并骨架
+  VRMUtils.removeUnnecessaryVertices(loadedVrm.scene)
+  VRMUtils.combineSkeletons(loadedVrm.scene)
+
+  // 3. 添加 LookAt 四元数代理
+  const lookAtQuatProxy = new VRMLookAtQuaternionProxy(loadedVrm.lookAt)
+  loadedVrm.scene.add(lookAtQuatProxy)
+
+  // 4. 标准化 VRM 0.x → 1.0 姿态
+  VRMUtils.rotateVRM0(loadedVrm)
+
+  // 5. 计算自动相机位置 (根据模型包围盒)
+  const box = new THREE.Box3().setFromObject(loadedVrm.scene)
+  // pivot 在颈部高度
+  // orbitRadius = modelSize.y / 4.2 / tan(FOV/2)
+
+  // 6. 初始化控制器
+  emote = new EmoteController(loadedVrm)
+  motion = new MotionController(loadedVrm)
+  handPoseCache = buildHandPoseCache(loadedVrm)
+
+  // 7. 加载空闲动画
+  motion.loadIdle('/friend/idle_loop.vrma')
+})
+```
+
+### 每帧更新循环 (11 步)
+
+```typescript
+function animate() {
+  // 1. Animation Mixer (MotionController)
+  motion.update(delta)
+
+  // 2. 放松手部姿态 (非舞蹈时)
+  if (handPose && !motion.isDancing)
+    applyRelaxedHandPose(handPose, elapsedTime)
+
+  // 3. Humanoid 骨骼更新
+  vrm.humanoid.update()
+
+  // 4. Camera tracking mode → lookAt
+  if (trackingMode === 'camera')
+    saccades.instantUpdate(vrm, camera.position)
+
+  // 5. LookAt 更新
+  vrm.lookAt.update(delta)
+
+  // 6. 眼球微动 (saccades)
+  saccadesController.update(vrm, lookAtTarget, delta)
+
+  // 7. 眨眼 (blink)
+  updateBlink(vrm, delta, blinkState)
+
+  // 8. 表情过渡 (EmoteController)
+  emote.update(delta)
+
+  // 9. 唇形同步 (LipSync)
+  lipSync.update(vrm, delta)
+
+  // 10. Expression Manager
+  vrm.expressionManager.update()
+
+  // 11. Spring Bone 物理
+  vrm.springBoneManager.update(delta)
+
+  renderer.render(scene, camera)
+}
+```
+
+### 相机控制系统
+
+球面坐标相机控制：
+
+```typescript
+// 参数: pivot(旋转中心), orbitRadius(距离), orbitTheta(水平角), orbitPhi(垂直角)
+camera.position.set(
+  pivot.x + radius * sin(phi) * sin(theta),
+  pivot.y + radius * cos(phi),
+  pivot.z + radius * sin(phi) * cos(theta),
+)
+camera.lookAt(pivot)
+```
+
+- 鼠标滚轮: 缩放 (0.8-5.0)
+- 左键拖拽 VRM 模型: 双击触发射线碰撞检测身体区域
+- 中键拖拽: 推拉 (dolly)
+- 右键拖拽: 旋转视角
+- 菜单栏拖拽按钮: 平移 / 旋转 视角
+
+### 眼球追踪系统
+
+两种模式:
+- `mouse`: 鼠标在屏幕上的位置决定 VRM 视线的交点（通过射线平面求交）
+- `camera`: VRM 始终看向相机位置
+
+眼球微动控制器 (`EyeSaccadeController`):
+- 每 400-1200ms 添加随机偏移 (-0.25 到 0.25 units)
+- 瞬间更新 + 每帧 lerp 平滑
+
+### 眨眼系统
+
+- 随机间��: 1-6s
+- 眨眼时长: 150ms
+- 使用 sin(π * progress) 曲线实现自然闭合
+- 每帧更新 `blink` blendshape
+
+### 放松手部姿态
+
+当 VRM 模型没有手指动画轨道时，手指会保持 T-pose 僵硬状态。
+解决方案：每帧手动设置手指旋转。
+
+```typescript
+// 手指自然弯曲 (从拇指到小指递增)
+const curlMap = {
+  Thumb:  [0.25, 0.15, 0.10],
+  Index:  [0.20, 0.30, 0.20],
+  Middle: [0.25, 0.35, 0.25],
+  Ring:   [0.30, 0.40, 0.30],
+  Little: [0.35, 0.45, 0.30],
+}
+// 手指自然张开
+const spreadMap = { Thumb: 0.15, Index: 0.04, Middle: 0, Ring: -0.04, Little: -0.08 }
+// 微妙颤动: sin(time * freq + seed) * 0.02
+```
+
+### 触摸区域检测
+
+射线检测 + 最近骨骼匹配：
+
+```typescript
+const boneRegionMap: [string, TouchRegion][] = [
+  ['head', 'head'], ['neck', 'head'],
+  ['leftShoulder', 'arm'], /* ...所有手臂骨骼... */
+  ['chest', 'chest'], ['spine', 'belly'],
+  ['hips', 'buttocks'],
+  ['leftUpperLeg', 'leg'], /* ...所有腿部骨骼... */
+]
+// 计算点击点与所有骨骼的世界坐标距离
+// 选择最近的骨骼对应的区域
+```
+
+双击确认（500ms 窗口）+ 5s 冷却。
+
+### 窗口穿透点击检测
+
+```typescript
+// 渲染到 1x1 offscreen render target
+// 读取光标位置的 alpha 通道
+// alpha > 10 → 点击在模型上 → 不穿透
+// alpha <= 10 → 点击在透明背景 → 穿透窗口
+```
+
+---
+
+## EmoteController — Blend Shape 动画系统
+
+**文件**: `src/components/friend/frontend/emote.ts` (~207 行)
+
+详细情绪映射见 [情绪 → 3D 表情映射](emotion-map.md)。
+
+### 核心机制
+
+```
+EmoteController
+  ├── emotionStates: Map<emotionName, { expression[], blendDuration }>
+  │   13 种情绪的 blend shapes 组合定义
+  │
+  ├── setEmotion(name, intensity)
+  │   开始过渡：记录起始值、设置目标值、启动过渡
+  │
+  ├── setEmotionWithReset(name, durationMs, intensity)
+  │   设置表情 + 定时自动回中到 neutral
+  │
+  ├── update(deltaTime)
+  │   每帧计算 cubic ease 过渡
+  │
+  └── resetAll()
+      立即清零所有 blendshape
+```
+
+---
+
+## MotionController — 动画系统
+
+**文件**: `src/components/friend/frontend/motion-controller.ts` (~421 行)
+
+### 支持的文件格式
+
+| 格式 | 描述 | 来源 |
+|------|------|------|
+| VRMA | VRM Animation 格式 | 标准动画文件 |
+| VMD | MikuMikuDance 格式 | 舞蹈动画 (极乐净土/恋爱循环) |
+| FBX | Autodesk FBX 格式 | Mixamo 动画 (开心/生气等) |
+
+### 动作预设
+
+**短动作** (单次触发，完成后回归 idle):
+
+```typescript
+akimbo:      { label: '叉腰',   type: 'vrma' }
+playFingers: { label: '搓手',   type: 'vrma' }
+scratchHead: { label: '挠头',   type: 'vrma' }
+stretch:     { label: '伸展',   type: 'vrma' }
+happy:       { label: '开心',   type: 'fbx'  }
+angry:       { label: '生气',   type: 'fbx'  }
+greeting:    { label: '招呼',   type: 'fbx'  }
+excited:     { label: '兴奋',   type: 'fbx'  }
+shy:         { label: '害羞',   type: 'fbx'  }
+point:       { label: '指点',   type: 'fbx'  }
+salute:      { label: '敬礼',   type: 'fbx'  }
+angryPump:   { label: '暴怒',   type: 'fbx'  }
+```
+
+**舞蹈** (循环播放，支持 BGM):
+
+```typescript
+jile: { label: '极乐净土', type: 'vmd', bgm: '/friend/jile.mp3' }
+love: { label: '恋爱循环', type: 'vmd', bgm: '/friend/love.mp3' }
+```
+
+### 动画过渡系统
+
+使用单个持久的 `AnimationMixer` 配合 `crossFade` 过渡，避免 T-pose 闪烁：
+
+```typescript
+private crossFadeTo(newAction, duration = 0.3s) {
+  newAction.reset().setEffectiveWeight(1).play()
+  const prev = this.currentAction ?? this.idleAction
+  if (prev && prev !== newAction) {
+    prev.crossFadeTo(newAction, duration, false)
+  }
+  this.currentAction = newAction
+}
+```
+
+### 动作生命周期
+
+```
+playAction('happy')
+    │
+    ├── 检查并发锁 (_actionPlaying / _isDancing)
+    │
+    ├── 异步加载动画文件 (带 generation 标记)
+    │   ├── VRMA: GLTFLoader + VRMAnimationLoaderPlugin
+    │   ├── FBX: loadMixamoAnimation
+    │   └── VMD: parseVMDAnimation + bindVMDToVRM + IK
+    │
+    ├── crossFadeTo(action, 0.3s)
+    │
+    ├── LoopOnce + clampWhenFinished
+    │
+    ├── finished 事件 → 回归 idle
+    │   └── hold 模式: 保持 10s 后回归 idle
+    │
+    └── 安全性超时: (duration + 1s) 后强制释放
+```
+
+### VMD 舞蹈系统
+
+特殊处理 VMD 格式：
+
+```typescript
+loadVMDWithIK(url)
+    ├── 1. 解析 VMD 文件 (parseVMDAnimation)
+    │    - 解析 VMD 二进制格式
+    │    - 从 VRM 骨骼映射到关键帧
+    │    - 缓存解析结果 (解析开销大)
+    │
+    ├── 2. 绑定到 VRM (bindVMDToVRM)
+    │    - 生成 Three.js AnimationClip
+    │    - 创建 IK 目标对象
+    │    - 启用 IK 处理器
+    │
+    └── 3. 建立复用的 IK 处理器 (VRMIKHandler)
+         - 使用 FABRIK 算法
+         - 支持手臂 IK
+         - 每帧在 mixer.update 后运行
+```
+
+舞蹈启动时自动切换相机视角到合适位置（臀部高度为中心）。
+
+### BGM 系统
+
+```typescript
+// 舞蹈开始时
+this.bgmAudio = new Audio(preset.bgm)
+this.bgmAudio.loop = true
+this.bgmAudio.volume = this._volume
+this.bgmAudio.play()
+
+// 舞蹈停止时: 淡出 (每隔 50ms 降低 0.1)
+const fadeInterval = setInterval(() => {
+  audio.volume = Math.max(0, audio.volume - 0.1)
+  if (audio.volume <= 0) { clearInterval(fadeInterval); audio.pause() }
+}, 50)
+```
+
+---
+
+## LipSync — 唇形同步
+
+**文件**: `src/components/friend/frontend/lip-sync.ts` (~187 行)
+
+### 技术实现
+
+使用 `wlipsync` 库的 WebAudio 音频分析节点：
+
+```typescript
+// 初始化
+this.lipSyncNode = await createWLipSyncNode(audioContext, profile)
+// lipSyncNode 只分析音频，不连接扬声器
+// gainNode 连接扬声器
+
+// 播放音频时，同时连接到 lipSyncNode 和 gainNode
+source.connect(this.lipSyncNode)  // 分析
+source.connect(this.gainNode)     // 扬声器
+```
+
+### 音素 → VRM Blend Shape 映射
+
+| wlipsync 分析键 | VRM Blend Shape |
+|----------------|----------------|
+| `A` | `aa` (张嘴) |
+| `E` | `ee` (露齿) |
+| `I` | `ih` (微张嘴) |
+| `O` | `oh` (嘟嘴) |
+| `U` | `ou` (收唇) |
+| `S` | 映射到 `I`/`ih` |
+
+双胜者策略：取概率最高的两个音素，胜者 cap 0.7，亚军 cap 0.35。
+
+### 平滑参数
+
+- `ATTACK`: 50 (上升速率)
+- `RELEASE`: 30 (衰减速率)
+- `CAP`: 0.7 (最大权重)
+- `SILENCE_VOL`: 0.04 (静音音量阈值)
+- `SILENCE_GAIN`: 0.05 (静音增益阈值)
+- `IDLE_MS`: 160 (静音判定窗口)
+
+公式: `smoothed = from + (to - from) * (1 - exp(-rate * delta))`
+
+静音时完全跳过 blendshape 设置（让 EmoteController 控制嘴部）。
+
+---
+
+## TextBubble.tsx — 文字气泡
+
+**文件**: `src/components/friend/frontend/components/TextBubble.tsx` (~608 行)
+
+### 核心功能
+
+1. **SSE 驱动**：通过 `EventSource` 实时接收 `VrmBroadcastPayload`
+2. **打字机效果**：逐字符显示，CJK/English 自适应速率
+3. **音频队列**：多句子音频按索引顺序播放，支持 `appendText` 配对
+4. **Markdown 渲染**：打字机完成后使用 `marked` 渲染
+5. **发送首 TTS 队列**：支持排队 `sendFirstTts` 信号
+6. **看门狗**：30s 超时自动隐藏（防止卡死）
+
+### 打字机速率计算
+
+```typescript
+function getCharRate(text: string, ttsEnabled: boolean): number {
+  const ratio = cjkRatio(text)
+  if (ttsEnabled) {
+    return Math.round(200 * ratio + 60 * (1 - ratio))  // CJK: 200ms, EN: 60ms
+  }
+  return Math.round(80 * ratio + 30 * (1 - ratio))     // CJK: 80ms, EN: 30ms
+}
+```
+
+### 消息处理逻辑
+
+```
+handleMessage(msg)
+    │
+    ├── Audio-only: 直接入音频队列
+    │
+    ├── appendText: 配对文字和音频索引，等待播放时揭示文字
+    │
+    ├── Image-only: 显示图片，15s 自动隐藏
+    │
+    ├── Emotion-only: 转发 onMessage 回调 (不改变气泡)
+    │
+    └── Text message:
+        ├── sendFirstTts: 重置音频队列，播放首句 TTS
+        ├── 设置文字 → 启动打字机
+        ├── 打字机完成后隐藏调度 (2s)
+        └── 如果没有 TTS → 打字机完成后直接调度隐藏
+```
+
+### 隐藏调度逻辑
+
+```
+tryScheduleHide()
+    ├── 打字机完成? (typewriterRef === null)
+    ├── 音频播放完毕? (!audioPlaying && queue empty)
+    ├── sendFirstTts 队列为空?
+    ├── replyDone 已收到?
+    │
+    └── 全部满足 → setTimeout(hideBubble, 2000ms)
+```
+
+---
+
+## ChatInput.tsx — 输入栏
+
+**文件**: `src/components/friend/frontend/components/ChatInput.tsx` (~475 行)
+
+### 三种模式
+
+1. **文字输入模式**: 输入框 + 发送按钮 + 回车发送
+2. **PTT 模式**: 按住麦克风按钮录音，松开停止并转录
+3. **语音通话模式** (F2): 连续语音，VAD 自动分段
+
+### 全局快捷键
+
+- `Enter`: 打开输入栏 / 发送消息
+- `Escape`: 关闭输入栏
+- `F2`: 切换语音通话
+- `F4`: 设置面板
+- `F5`: 刷新前端
+- `Tab`: 折叠/展开菜单
+- `Ctrl+D`: 清空输入
+
+### 语音通话 TTS 中断
+
+```typescript
+const scheduleInterrupt = useCallback(() => {
+  // 1s 延迟中断 TTS 播放
+  // 当用户开始说话时，延迟 1s 后中断当前 TTS
+  // 避免用户的"嗯"等短暂声音打断对话
+  setTimeout(() => {
+    ;(window as any).__clawInterruptAudio?.()
+  }, 1000)
+}, [])
+```
+
+---
+
+## MoodIndicator.tsx — 心情指示器
+
+**文件**: `src/components/friend/frontend/components/MoodIndicator.tsx` (~373 行)
+
+### Canvas 动画
+
+- **液态填充柱状图**: 使用二次贝塞尔波浪动画 + Canvas clip
+- **爱心图标**: 同样的波浪填充，经典心形路径
+- **双波浪层**: 不同速度和透明度叠加，产���液态流动效果
+- **颜色分级**: 90+ 粉色 → 70+ 橙色 → 50+ 绿色 → 30+ 蓝色 → 0+ 灰色
+- **浮动气泡**: 心情变化时显示 `❤️+3` 或 `🩶-2` 浮动动画
+
+### 交互
+
+- 正常状态: 半透明 (opacity 0.5)
+- 鼠标悬停: 全透明 (opacity 1.0)
+- 拖拽: 可自由移动到任意位置
+- 自动隐藏: 5s 无交互后恢复半透明
+
+### 波浪参数
+
+```typescript
+WAVE_LENGTH = 8        // 波长
+WAVE_HEIGHT = 2.5      // 波高 (px)
+
+// 双波浪叠加
+drawWave(scrollDir: -1, alpha: 0.55)  // 底层波浪，慢速反向
+drawWave(scrollDir: 1, alpha: 1.0)    // 顶层波浪，快速正向
+```
+
+---
+
+## 其他组件
+
+### ResizeHandles
+窗口大小调整手柄，支持拖拽调整窗口尺寸。
+
+### SettingsPanel
+设置面板 (F4 打开)，包含:
+- VRM 模型选择/导入
+- TTS 开关 + 语音选择
+- 显示设置 (文字气泡、UI、心情)
+- 追踪模式 (鼠标/相机)
+- 音量控制
+- 屏幕观察设置
+- 语言设置
+- STT Provider 选择
+- 舞蹈选择
+
+### HistoryPanel
+对话历史面板，显示最近 100 条消息，支持拖拽移动位置。

docs/friend/overview.md

@@ -0,0 +1,138 @@
+# VRM 桌面伴侣系统
+
+## 定位
+
+Friend 是 VersperClaw 的 VRM 3D 桌面伙伴系统，与 CLI 共享同一进程运行。它通过 SSE + HTTP 与 Tauri 前端通信，无需独立的子进程或外部服务。用户可以与 VRM 角色进行文字聊天、语音对话，角色会通过 3D 表情、肢体动作和语音进行反馈。
+
+核心设计理念：**同进程集成** — FriendService 作为单例运行在 CLI 主进程中，消息通过 `messageQueueManager.enqueue()` 直接注入到对话流程中，AI 回复通过 SSE 实时广播到前端显示。
+
+---
+
+## 核心组件
+
+| 组件 | 文件 | 职责 |
+|------|------|------|
+| **FriendService** | `src/friend/FriendService.ts` (~31KB) | 核心编排器，管理生命周期、语音捕获、STT/TTS、SSE 广播、静音系统 |
+| **SSE 模块** | `src/friend/sse.ts` | 客户端注册表，类型化广播 `VrmBroadcastPayload` |
+| **HTTP 服务器** | `src/friend/server.ts` | Bun.serve() 在 3456 端口，处理静态文件、API 路由、SSE 连接 |
+| **API 路由** | `src/server/api/friend.ts` | `/plugins/friend/*` 的所有 REST 端点 |
+| **TTS 服务** | `src/friend/tts.ts` | Edge TTS + Qwen DashScope TTS，音频文件注册表 |
+| **STT 服务** | `src/friend/stt-service.ts` | 基于文件的语音转录（REST 端点） |
+| **VAD 服务** | `src/friend/voice/vad-service.ts` | Silero VAD ONNX 模型，onnxruntime-web WASM 后端 |
+| **偏好设置** | `src/friend/prefs.ts` | 持久化到 `~/.config/VersperClaw/friend.json` |
+| **Tauri 启动器** | `src/friend/tauri-launcher.ts` | 启动 Tauri 桌面窗口 |
+| **前端应用** | `src/components/friend/frontend/` | React + Three.js + @pixiv/three-vrm |
+
+---
+
+## LLM 集成
+
+Friend 通过三种方式与 LLM 深度集成：
+
+### 1. `friend_emotion` 工具
+- 定义在 `src/tools/FriendEmotionTool.ts`
+- LLM 可在每次回复后调用，设置角色表情和心情
+- 参数：`emotion` (13种情绪之一)、`intensity` (0-1)、`mood_delta` (-3 到 +3)
+- 通过 `broadcastToVrm()` 向 SSE 客户端广播表情切换
+- `mood_delta` 会持久化到 prefs 中的 `_moodIndex`，并广播给前端心情指示器
+
+### 2. `friend_screen_observe` 工具
+- 定义在 `src/tools/FriendScreenObserveTool.ts`
+- 捕获桌面截图，返回图片路径
+- LLM 使用 Read 工具查看截图后，以同伴身份回应
+- 自动广播 `think` 表情到前端
+
+### 3. friendPrompt 技能注入
+- 定义在 `src/skills/bundled/friendPrompt.ts`
+- 自动注入系统提示，告知 LLM 拥有 VRM 虚拟形象
+- 包含情绪列表、心情指数、对话风格指引
+
+---
+
+## 情绪系统
+
+Friend 支持 13 种情绪，映射到 VRM blend shapes 和骨骼动画：
+
+- `happy`, `sad`, `angry`, `surprised`, `think`, `awkward`, `question`, `curious`, `neutral`, `love`, `flirty`, `greeting`, `relaxed`
+
+每种情绪在 `src/components/friend/frontend/emote.ts` 中定义了：
+- VRM blend shapes 组合及权重
+- 过渡时间（cubic ease 缓动）
+- 自动回中到 neutral 的定时器
+
+情绪与肢体动作在 `App.tsx` 的 `emotionActionMap` 中关联。
+
+---
+
+## 交互模式
+
+### 文字聊天
+用户在输入框输入文字，通过 `POST /plugins/friend/chat` 发送到后端，FriendService 调用 `sendText()` 将消息通过 `messageQueueManager.enqueue()` 注入 CLI 对话流程。
+
+### PTT 按键通话
+按住麦克风按钮进行语音录制，松开后语音数据被发送到 STT 服务转录为文字，然后提交到对话流程。
+
+### F2 语音通话
+按下 F2 进入连续语音通话模式。服务器端通过 `arecord`/`parecord` 持续捕获麦克风音频，Silero VAD 自动检测语音段落边界，转录后自动发送给 AI 处理。AI 回复通过 TTS 播放，期间静音系统阻止回声。
+
+---
+
+## 简要架构图
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    VersperClaw 主进程 (Bun)                      │
+│                                                                 │
+│  ┌──────────────┐    ┌──────────────────┐    ┌───────────────┐  │
+│  │   CLI TUI    │    │   LLM Provider   │    │   Bridge API  │  │
+│  │  (React Ink) │◄──►│  (Anthropic/NIM) │◄──►│  (SSE/HTTP)   │  │
+│  └──────┬───────┘    └────────┬─────────┘    └───────────────┘  │
+│         │                     │                                  │
+│  ┌──────▼─────────────────────▼──────────────────────────────┐  │
+│  │                   FriendService (单例)                     │  │
+│  │  ┌────────────┐  ┌───────────┐  ┌───────────┐  ┌───────┐  │  │
+│  │  │ STT 连接器 │  │ TTS 生成器│  │ VAD 检测  │  │静音系统│  │  │
+│  │  │(Groq/等)   │  │(Edge/Qwen)│  │(Silero)   │  │       │  │  │
+│  │  └────────────┘  └───────────┘  └───────────┘  └───────┘  │  │
+│  └───────────────────────┬────────────────────────────────────┘  │
+│                          │                                       │
+│  ┌───────────────────────▼────────────────────────────────────┐  │
+│  │               HTTP 服务器 (Bun.serve :3456)                 │  │
+│  │  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐  │  │
+│  │  │ SSE /events  │  │ REST API     │  │ 静态文件服务     │  │  │
+│  │  │             │  │ /chat /voice │  │ /friend/*        │  │  │
+│  │  └─────────────┘  └──────────────┘  └──────────────────┘  │  │
+│  └───────────────────────┬────────────────────────────────────┘  │
+└──────────────────────────┼────────────────────────────────────────┘
+                           │ SSE + HTTP
+                           ▼
+┌──────────────────────────────────────────────────────────────────┐
+│              Tauri 桌面窗口 (WebKitGTK)                          │
+│                                                                  │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                 App.tsx (React 应用)                       │   │
+│  │  ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────────┐  │   │
+│  │  │ VRMScene │ │TextBubble│ │ChatInput│ │ MoodIndicator│  │   │
+│  │  │ Three.js │ │SSE驱动   │ │PTT/通话│ │ Canvas 动画  │  │   │
+│  │  └──────────┘ └──────────┘ └────────┘ └──────────────┘  │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                                                                  │
+│  核心 3D 子系统:                                                 │
+│  ┌─────────────┐ ┌────────────────┐ ┌──────────┐ ┌──────────┐  │
+│  │EmoteController│ MotionController │  LipSync  │ TextBubble │  │
+│  │blend shapes  │ VRMA/VMD/FBX    │ WebAudio  │ 打字机效果 │  │
+│  │13种情绪映射  │ 舞蹈系统        │ 唇形同步  │ Markdown   │  │
+│  └─────────────┘ └────────────────┘ └──────────┘ └──────────┘  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 文件位置
+
+- 后端: `src/friend/` — FriendService, SSE, TTS, STT, VAD, prefs, server, launcher
+- 前端: `src/components/friend/frontend/` — React app, Three.js 3D 场景
+- API 路由: `src/server/api/friend.ts` — 所有 HTTP 端点
+- LLM 工具: `src/tools/FriendEmotionTool.ts`, `src/tools/FriendScreenObserveTool.ts`
+- 技能注入: `src/skills/bundled/friendPrompt.ts`
+- 配置: `~/.config/VersperClaw/friend.json`

docs/friend/voice-vad.md

@@ -0,0 +1,525 @@
+# 语音捕获与 VAD 策略
+
+本文档详细描述 Friend 系统的音频捕获、语音活动检测 (VAD)、语音转文字 (STT) 和静音管理策略。
+
+---
+
+## 1. 音频捕获
+
+### 1.1 子进程架构
+
+Friend 使用子进程方式进行音频捕获，而非原生 NAPI 绑定。这是因为 cpal 的同步 NAPI 调用在 ALSA 初始化卡顿时会阻塞事件循环，且无法从 JS 侧超时。
+
+**文件**: `src/friend/FriendService.ts` — `loadAudioCapture()` 方法
+
+```typescript
+private async loadAudioCapture(): Promise<AudioCaptureProvider> {
+  // 使用 arecord / parecord 子进程
+  // 尝试顺序: arecord (ALSA) → parecord (PulseAudio)
+}
+```
+
+### 1.2 工具选择与参数
+
+**arecord** (ALSA):
+```
+-D default    # 默认设备
+-r 16000      # 采样率 16kHz
+-f S16_LE     # 16位有符号小端 PCM
+-c 1          # 单声道
+-t raw        # 原始 PCM 格式
+-q            # 静默模式
+```
+
+**parecord** (PulseAudio):
+```
+--raw              # 原始 PCM
+--rate=16000       # 16kHz
+--format=s16le     # 16位有符号小端
+--channels=1       # 单声道
+--latency-msec=20  # 低延迟
+```
+
+### 1.3 验证机制 (500ms 窗口)
+
+子进程启动后有 500ms 验证窗口：
+
+```typescript
+// 启动子进程后等待 500ms
+// 若子进程在此时间内产生了音频数据 → 验证通过
+// 若子进程退出且未产出数据 → 验证失败，尝试下一个工具
+// 若 500ms 无数据 → 验证失败
+```
+
+这防止了 `parecord` 在 PulseAudio 不可用时静默失败的问题（进程启动但立即退出）。
+
+### 1.4 数据回调
+
+```typescript
+const feedAudio = (chunk: Buffer) => {
+  // 1. 静音过滤: muted 时不转发（防止 TTS 回声）
+  if (this.muted) return;
+
+  // 2. 转发到 STT 连接
+  onData(chunk);
+
+  // 3. 转发到 VAD 检测
+  if (this.vadInstance) {
+    const float32 = new Float32Array(chunk.length / 2);
+    for (let i = 0; i < float32.length; i++) {
+      float32[i] = chunk.readInt16LE(i * 2) / 32768;
+    }
+    this.vadInstance.processAudio(float32).catch(() => {});
+  }
+};
+```
+
+### 1.5 停止逻辑
+
+```typescript
+stopRecording: async () => {
+  if (captureProc) {
+    captureProc.kill('SIGTERM');
+    // 2s 后强制 SIGKILL（防止僵进程）
+    setTimeout(() => {
+      try { captureProc?.kill('SIGKILL'); } catch {}
+    }, 2000);
+    captureProc = null;
+  }
+},
+```
+
+---
+
+## 2. STT Provider 检测与降级
+
+### 2.1 自动检测链
+
+**文件**: `src/friend/FriendService.ts` — `detectAvailableSttProvider()` 方法
+
+```typescript
+detectAvailableSttProvider()
+    │
+    ├── 1. Groq Whisper (isGroqAvailable)
+    │   最快 - REST API 调用，无需 Python
+    │   检测: 检查 API key 是否存在
+    │
+    ├── 2. Local Whisper (checkLocalWhisperAvailable)
+    │   本地运行，无需网络
+    │   检测: 导入 connectLocalWhisperStream 检查
+    │
+    ├── 3. Anthropic Voice Stream (isVoiceStreamAvailable)
+    │   通过 Anthropic API 的流式语音识别
+    │   检测: 检查登录状态和 API key
+    │
+    ├── 4. Doubao ASR
+    │   通过豆包 API
+    │   检测: 检查 ~/.claude/tts/doubao/credentials.json
+    │
+    └── 全不可用 → 抛出错误
+        "No STT provider available. Install local Whisper: pip install openai-whisper"
+```
+
+### 2.2 STT Provider 特性对比
+
+| Provider | 延迟 | 依赖 | 是否需要网络 | 支持语言 |
+|----------|------|------|-------------|---------|
+| **Groq Whisper** | 低 | API key | 是 | 多语言 |
+| **Local Whisper** | 中 | Python + pip | 否 | 多语言 |
+| **Anthropic Voice Stream** | 低 | Anthropic 登录 | 是 | 多语言 (keyterms支持) |
+| **Doubao ASR** | 中 | 凭据文件 | 是 | 中文最佳 |
+
+### 2.3 STT 连接超时
+
+所有 provider 连接都有 8 秒超时：
+
+```typescript
+startSttConnectionWithTimeout(provider, language)
+    ├── 超时 8s
+    └── 超时错误提示: "STT provider '{provider}' timed out after 8s."
+        └── provider === 'local' 时附带 pip 安装提示
+```
+
+### 2.4 连接工厂
+
+```typescript
+startSttConnection(provider, language)
+    │
+    ├── anthropic: connectVoiceStream(callbacks, { language, keyterms })
+    │    keyterms: ['code', 'versperclaw'] 提高相关词汇识别率
+    │
+    ├── local: preloadWhisperModel + connectLocalWhisperStream
+    │    需预加载模型（首次加载较慢）
+    │
+    ├── doubao: connectDoubaoStream(callbacks, { language })
+    │
+    └── groq: connectGroqStream(callbacks, { language })
+        最快，纯 REST 流式调用
+```
+
+### 2.5 回调接口
+
+```typescript
+const callbacks = {
+  onTranscript: (text: string, isFinal: boolean) => {
+    if (isFinal) {
+      this.captureTranscripts.push(text);  // 最终文本入队列
+      this.captureInterimText = '';
+    } else {
+      this.captureInterimText = text;       // 临时文本（前端轮询显示）
+    }
+    // 更新状态供前端轮询
+    this.setState({
+      captureStatus: { capturing: true, interimText: this.captureInterimText },
+    });
+  },
+  onError: (_error: string) => {},
+  onClose: () => {},
+  onReady: (_conn: any) => {},
+};
+```
+
+---
+
+## 3. Silero VAD 架构
+
+**文件**: `src/friend/voice/vad-service.ts` (~322 行)
+
+### 3.1 为什么选择 onnxruntime-web WASM
+
+Bun 不支持 onnxruntime-node 原生插件（会触发 segfault），因此使用 onnxruntime-web 的 WASM 后端。WASM 二进制文件来自 `onnxruntime-web/dist`。
+
+### 3.2 模型规格
+
+- **模型**: Silero VAD legacy ONNX (来自 `@ericedouard/vad-node-realtime`)
+- **模型文件**: `silero_vad_legacy.onnx`
+- **输入**: 512 采样帧 @ 16kHz (32ms)
+- **输出**: 语音概率 (0-1)
+- **LSTM 状态**: h=[2,1,64], c=[2,1,64]
+
+### 3.3 配置参数
+
+```typescript
+this.opts = {
+  // 说话判定阈值
+  positiveSpeechThreshold: 0.75,    // 超过此值判定为语音帧
+  negativeSpeechThreshold: 0.50,    // 低于此值判定为静音帧
+
+  // 触发条件
+  preSpeechTriggerFrames: 10,       // 需要连续 10 帧 (320ms) 确认说话
+  minSpeechFrames: 6,               // 最少 6 帧 (192ms) 有效语音
+
+  // 静音消音
+  redemptionFrames: 20,             // 连续 20 帧 (640ms) 静音结束段落
+
+  // 前置填充
+  preSpeechPadFrames: 10,           // 段落开头包含 10 帧前置音频
+
+  // 能量过滤
+  rmsThreshold: 0.004,              // RMS 能量阈值 (-48dBFS 噪声底限)
+
+  // 采样率
+  sampleRate: 16000,                // 16kHz
+};
+```
+
+### 3.4 RMS 能量预过滤
+
+在运行 ONNX 推理之前，先计算帧的 RMS 能量：
+
+```typescript
+let sumSq = 0;
+for (let i = 0; i < frame.length; i++) {
+  sumSq += frame[i] * frame[i];
+}
+const rms = Math.sqrt(sumSq / frame.length);
+
+if (rms < this.opts.rmsThreshold) {
+  prob = 0;  // 低于噪声底限 → 跳过 ONNX 推理
+} else {
+  // 执行 ONNX 推理
+  prob = await this.session.run({ input, sr, h, c });
+}
+```
+
+作用：
+- 节省 CPU 资源（大量帧无语音信号）
+- 过滤机械噪声/麦克风碰撞/环境静音
+- 降低误触发率
+
+### 3.5 状态机详解
+
+```
+              ┌──────────────────────────────────────────────────┐
+              │                  pre-speech phase               │
+              │  preSpeechCount < preSpeechTriggerFrames (10)   │
+              │                                                  │
+              │  语音帧 → preSpeechCount++                      │
+              │  非语音帧 → preSpeechCount = 0                  │
+              │                                                  │
+              │  当 preSpeechCount >= 10:                        │
+              │    → speaking = true                             │
+              │    → speechFrameCount = preSpeechCount           │
+              │    → onSpeechStart()                             │
+              └──────────────────────┬───────────────────────────┘
+                                     │
+                                     ▼
+              ┌──────────────────────────────────────────────────┐
+              │                 speaking phase                   │
+              │                                                  │
+              │  语音帧 → redemptionCounter = 0                 │
+              │  静音帧 → redemptionCounter++                    │
+              │                                                  │
+              │  当 redemptionCounter >= 20 (640ms):             │
+              │    → endSpeech()                                 │
+              │    → onSpeechEnd(audioSegment)                   │
+              └──────────────────────────────────────────────────┘
+```
+
+### 3.6 段落构建
+
+当 onSpeechEnd 触发时，构建包含前置填充的音频段：
+
+```typescript
+private endSpeech(): void {
+  // 1. 检查最小语音帧数 (防止误触发)
+  if (this.speechFrameCount < this.opts.minSpeechFrames) {
+    this.callbacks.onVADMisfire();  // 误触发回调
+    return;
+  }
+
+  // 2. 构建音频段 (含前置填充)
+  const total = this.frameHistory.length;
+  const prePad = Math.min(this.opts.preSpeechPadFrames, total);
+  const segFrames = this.frameHistory.slice(
+    total - prePad - this.speechFrameCount,
+    total
+  );
+  // 合并所有帧为一个 Float32Array
+  const segment = new Float32Array(totalSamples);
+  for (const f of segFrames) { segment.set(f.frame, offset); offset += ... }
+
+  // 3. 回调
+  this.callbacks.onSpeechEnd(segment);
+}
+```
+
+### 3.7 VAD 生命周期
+
+```typescript
+class SileroVad {
+  async init()     // 加载 ONNX 模型 (初始化)
+  start()          // 激活 VAD 处理
+  pause()          // 暂停 + 结束当前语音段
+  processAudio()   // 处理 PCM 音频帧
+  flush()          // 刷新剩余缓冲区 + 结束段
+  reset()          // 重置全部状态 (保留 session)
+  destroy()        // 清理资源
+}
+```
+
+### 3.8 VAD 初始化失败的处理
+
+VAD 初始化失败是非致命的：
+
+```typescript
+vad.init()
+  .then(() => { this.vadInstance = vad; })
+  .catch((e) => {
+    console.warn('[FriendService] VAD init failed (non-fatal, voice capture falls back to F2-only):', e);
+  });
+```
+
+当 VAD 不可用时，F2 语音通话模式降级为手动分段（仍可通过 PTT 模式使用语音）。
+
+---
+
+## 4. 静音系统
+
+### 4.1 为什么需要静音
+
+当 AI 回复通过 TTS 播放时，扬声器声音会被麦克风捕获，如果不做静音处理会产生两种问题：
+1. **TTS 回声**: 自己的语音进入 STT 造成重复识别
+2. **打断 AI 回复**: 用户未说话但环境噪声导致 VAD 误触发
+
+### 4.2 静音策略
+
+```
+startAiTurnMute() ──── 在语音片段提交时立即静音
+    │
+    ├── muted = true
+    ├── vadInstance.pause()
+    └── 30s 超时定时器 (安全性保障)
+    │
+    ▼
+AI 处理 (工具调用、深度思考)
+    │
+    ▼
+broadcastResponse() → generateTts()
+    │
+    ├── TTS 成功:
+    │   └── extendMuteForTts(audioId)
+    │       ├── 取消 30s 定时器
+    │       └── 设置精确的 TTS 播放时长定时器
+    │
+    ├── TTS 失败:
+    │   └── unmute() (立即解除静音)
+    │
+    ▼
+TTS 播放完毕 → unmute()
+    ├── muted = false
+    ├── muteTimer = null
+    └── vadInstance.start()    (恢复 VAD 监听)
+```
+
+### 4.3 定时器精确控制
+
+- **初始静音**: 30s（覆盖几乎所有 AI 响应周期）
+- **精确调整**: TTS 生成后通过 MP3 时长解析精确控制
+- **安全性保障**: 任何情况下都不会永久静音
+
+### 4.4 清除静音 (紧急情况)
+
+```typescript
+stopVoiceCapture() → _stopCapture()
+    ├── 停止音频捕获
+    ├── clearMute()  (立即解除静音)
+    └── VAD reset()
+```
+
+---
+
+## 5. MP3 时长解析
+
+**文件**: `src/friend/FriendService.ts` — `getMp3DurationMs()` 方法
+
+### 5.1 帧同步头扫描法
+
+不使用 bitrate 查找表（容易出错），而是通过实际帧间隔计算：
+
+```typescript
+private getMp3DurationMs(audioId: string): number {
+  // 1. 获取音频文件路径
+  const filePath = getAudioFile(audioId);
+  const buf = readFileSync(filePath);
+
+  // 2. 跳过 ID3v2 标签 (如果存在)
+  if (buf[0..2] === 'ID3') {
+    offset = 10 + syncsafe_int(buf[6..9]);
+  }
+
+  // 3. 找到前两个帧同步字
+  // 帧同步: 0xFF 字节 + 0xE0 掩码
+  for (let i = offset; i < buf.length - 3; i++) {
+    if (isSync(i)) {
+      if (firstSync === -1) firstSync = i;
+      else { secondSync = i; break; }
+    }
+  }
+
+  // 4. 计算帧间隔 (CBR 模式)
+  const frameSize = secondSync - firstSync;
+
+  // 5. 解析帧头获取采样率
+  const h = read32BE(firstSync);
+  const version = (h >> 19) & 0x3;
+  const sampleRateIdx = (h >> 10) & 0x3;
+  // MPEG1 → 1152 samples/frame, MPEG2/2.5 → 576
+
+  // 6. 按步长计数帧数 (帧损坏时扫描到下一个同步字)
+  for (let pos = firstSync; pos + 3 < buf.length; pos += frameSize) {
+    if (!isSync(pos)) {
+      // 损坏帧: 扫描到下一个同步字
+      while (pos < buf.length - 3 && !isSync(pos)) pos++;
+    }
+    frames++;
+  }
+
+  // 7. 计算时长
+  return Math.round((frames * spf) / sampleRate * 1000);
+}
+```
+
+### 5.2 为什么自实现 MP3 解析
+
+- Edge TTS 输出 CBR MP3
+- 不依赖外部库（减少依赖项）
+- 帧同步头扫描法对 CBR 精确且鲁棒
+- 处理文件损坏的帧 (向前扫描下一个同步字)
+
+---
+
+## 6. 前端语音捕获 (useServerStt hook)
+
+**文件**: `src/components/friend/frontend/hooks/useServerStt.ts`
+
+### 6.1 设计原因
+
+Tauri 使用 WebKitGTK，不兼容 `onnxruntime-web` WASM 后端，因此浏览器 VAD (`@ricky0123/vad-web`) 不可用。前端将语音捕获完全委托给后端。
+
+### 6.2 两种模式
+
+**Push-to-Talk (PTT)**:
+```typescript
+startPushToTalk() → POST /voice/start  // 后端开始捕获
+stopPushToTalk()  → POST /voice/stop   // 后端停止并返回转录
+```
+
+**Voice Call (F2 模式)**:
+```typescript
+startStreaming(onTranscript, onError) → POST /voice/start
+    │
+    ├── 后端持续捕获麦克风音频
+    ├── 后端自动分段 (VAD / 定时 5s) 并转录
+    ├── 前端每 1s 轮询 POST /voice/status 获取 interimText
+    └── 显示在输入栏中
+
+stopStreaming() → POST /voice/stop
+    └── 结束后端捕获，返回完整转录
+```
+
+### 6.3 前端语音通���交互
+
+```typescript
+// TTS 中断: 用户说话时延迟 1s 中断当前 TTS
+const scheduleInterrupt = useCallback(() => {
+  setTimeout(() => {
+    ;(window as any).__clawInterruptAudio?.()
+  }, 1000)
+}, [])
+
+// 显示控制: 转录文字显示 3s 后自动清除
+setTimeout(() => {
+  if (voiceCallActiveRef.current) {
+    setText('')
+  }
+}, 3000)
+```
+
+---
+
+## 7. 浏览器 VAD 片段转录
+
+前端浏览器 VAD（非 WebKitGTK 环境）检测到语音段落后，通过 HTTP 发送到后端：
+
+```typescript
+// POST /plugins/friend/voice/stt-segment
+// Body: raw PCM/WAV buffer
+handleFriendApi → friendService.transcribeAudioSegment(audioBuffer)
+    │
+    ├── 检测 STT provider (自动降级)
+    ├── 创建临时 STT 连接
+    ├── 发送音频 → 等待 finalize
+    └── 发送转录文本到 AI 对话
+```
+
+---
+
+## 总结: 语音路径选择
+
+| 使用场景 | VAD | STT Provider | 音频来源 | 静音需求 |
+|---------|-----|------------|---------|---------|
+| Push-to-Talk (PTT) | 否 (人工分段) | 自动检测 | arecord/parecord | 否 |
+| F2 语音通话 | Silero VAD | 自动检测 → 分段 flush | arecord/parecord | 是 |
+| 浏览器 VAD (非 Tauri) | 浏览器 VAD | STT segment API | getUserMedia | 否 |
+| 文字输入 | 不适用 | 不适用 | 键盘 | 不适用 |

docs/ink-ui/overview.md

@@ -0,0 +1,585 @@
+# Ink 终端 UI 框架
+
+## 概述
+
+VersperClaw 的 Ink 是基于 [vadimdemedes/ink](https://github.com/vadimdemedes/ink) v6 的深度定制分叉（fork）。Ink 使用 React 组件模型渲染终端用户界面。它将 React 的虚拟 DOM 映射到终端字符网格，支持 Yoga Flexbox 布局、样式继承、事件处理、文本选择、搜索高亮等丰富的交互能力。
+
+> 与上游相比，VersperClaw 的 Ink 新增/修改了以下核心能力：自定义 DOM 节点树、压缩屏幕缓冲区（Int32Array）、基于 Yoga WASM 的布局引擎、Kitty 键盘协议支持、SGR 鼠标跟踪、文本选择模式、搜索高亮、双向文本处理、scrollable 容器、声明式光标位置等。
+
+---
+
+## 核心架构
+
+Ink 的渲染管线分为以下几个层次：
+
+```
+React 组件树
+    │
+    ▼
+React Reconciler (自定义 Fiber 协调器)
+    │
+    ▼
+DOM 节点树 (ink-root, ink-box, ink-text, ...)
+    │
+    ▼
+Yoga 布局引擎 (WASM Flexbox)
+    │
+    ▼
+Renderer → Output (screen buffer)
+    │
+    ▼
+LogUpdate (差异比较)
+    │
+    ▼
+Patch[] → ANSI 序列 → stdout
+```
+
+### Ink 主类
+
+文件：`src/ink/ink.tsx`
+
+`Ink` 类（约 1723 行）管理整个渲染生命周期：
+
+- **构造函数**：设置 `LogUpdate`、节流渲染调度器（`scheduleRender`，使用 `FRAME_INTERVAL_MS=16ms`）、`FocusManager`、Yoga `onComputeLayout` 回调、React reconciler 容器
+- **`onRender()`**：核心帧循环，每个渲染周期执行以下步骤：
+  1. 调用 `createRenderer` 执行 DOM → Yoga 布局 → 屏幕缓冲区的渲染
+  2. 处理选择滚动追踪
+  3. 应用选择/搜索覆盖层
+  4. 全损坏回退（full-damage backstop）
+  5. 计算差异（diff）
+  6. 缓冲池交换
+  7. 补丁优化与序列化
+  8. 光标定位（原生光标或声明式光标）
+  9. 写入 stdout
+- **选择管理**：`startSelection`, `extendSelection`, `wordSelect`, `lineSelect`, `dragScrollCapture`, `shiftSelection`
+- **stdin 挂起/恢复**：用于外部编辑器集成
+- **控制台/stderr 补丁**：拦截 console.log 等输出重定向
+- **drainStdin**：清理时清空 stdin 缓冲区
+
+### React Reconciler（协调器）
+
+文件：`src/ink/reconciler.ts`
+
+使用 `react-reconciler` 包创建自定义 Fiber 协调器，将 React 组件映射到 Ink 的 DOM 节点。
+
+**关键宿主配置**：
+
+| 钩子 | 说明 |
+|------|------|
+| `createInstance` | 创建 `DOMElement`（`ink-box`, `ink-text` 等），在 `<Text>` 内部嵌套时将 `ink-text` 转换为 `ink-virtual-text` |
+| `createTextInstance` | 创建 `TextNode`，要求必须在 `<Text>` 内使用 |
+| `commitUpdate` | React 19 使用新旧 props 直接比较，调用 `setStyle`, `setAttribute`, `setTextStyles`, `setEventHandler` |
+| `commitTextUpdate` | 更新文本节点 |
+| `appendChild` / `insertBefore` / `removeChild` | DOM 树操作，同步更新 Yoga 节点树 |
+| `resetAfterCommit` | 提交后触发 `onComputeLayout`（Yoga 布局）和 `onRender`（渲染帧） |
+| `hideInstance` / `unhideInstance` | 设置/取消 Yoga `display: none` |
+
+**调试工具**：
+- `getOwnerChain()`：从 React Fiber `_debugOwner` 提取组件名链，用于识别重绘来源
+- `CLAUDE_CODE_DEBUG_REPAINTS` 环境变量：启用后记录组件树归属
+- `CLAUDE_CODE_COMMIT_LOG`：记录提交/渲染性能日志
+
+### DOM 节点树
+
+文件：`src/ink/dom.ts`
+
+自定义 DOM 树，与浏览器 DOM 不同，专为终端渲染优化。
+
+**节点类型**：
+
+| 节点名 | 说明 |
+|--------|------|
+| `ink-root` | 根节点，持有 `FocusManager` |
+| `ink-box` | 容器（类似 `<div>`），有 Yoga 节点 |
+| `ink-text` | 文本容器，有测量函数 |
+| `ink-virtual-text` | `<Text>` 内嵌套的文本，无 Yoga 节点 |
+| `ink-link` | 超链接，无 Yoga 节点 |
+| `ink-progress` | 进度条，无 Yoga 节点 |
+| `ink-raw-ansi` | 预渲染 ANSI 字符串，固定尺寸测量 |
+| `#text` | 文本叶子节点 |
+
+**DOM 操作**：
+- `createNode()` / `createTextNode()` —— 创建节点
+- `appendChildNode()` / `insertBeforeNode()` / `removeChildNode()` —— DOM 树操作，同步更新 Yoga 节点
+- `setStyle()` / `setAttribute()` / `setTextStyles()` —— 属性更新，含脏检测（shallow equal 跳过未变更的渲染）
+- `markDirty()` —— 标记节点及其所有祖先为脏
+- `scheduleRenderFrom()` —— 从指定节点触发渲染（用于非 React 触发的 DOM 变更）
+
+**脏标记（Dirty Flag）**：每个 `DOMElement` 有 `dirty` 属性（boolean），`markDirty()` 从当前节点向上遍历直到根节点。渲染完成后清除。这允许增量重绘 —— 只有脏子树被重新布局和渲染。
+
+### Screen（屏幕缓冲区）
+
+文件：`src/ink/screen.ts`
+
+Screen 是终端渲染的核心数据结构，使用**压缩的 Int32Array** 存储每个单元格，避免为每个单元格分配对象（200x120 屏幕可避免分配 24000 个对象）。
+
+**单元格存储布局**：
+每个单元���占用 2 个 Int32（共 8 字节）：
+- `word0`：字符 ID（索引到 `CharPool`，32 位）
+- `word1`：`styleId[31:17] | hyperlinkId[16:2] | width[1:0]`
+
+**池化系统**：
+
+| 池 | 说明 |
+|----|------|
+| `CharPool` | 字符字符串池，共享跨所有屏幕。ASCII 字符使用 `Int32Array` 快速查找；非 ASCII 使用 `Map`。索引 0 固定为空格，索引 1 为 spacer 空字符串。 |
+| `StylePool` | ANSI 样式池，位 0 标识样式是否在空格上可见（背景色、反色、下划线等）。提供 `transition(fromId, toId)` 方法生成缓存的 ANSI 过渡字符串。`withInverse()`、`withCurrentMatch()`、`withSelectionBg()` 用于选择/搜索覆盖层。 |
+| `HyperlinkPool` | OSC 8 超链接池，索引 0 表示无链接。 |
+
+**单元格宽度枚举（`CellWidth`）**：
+| 值 | 名称 | 说明 |
+|----|------|------|
+| 0 | Narrow | 单宽字符 |
+| 1 | Wide | 宽字符（CJK、emoji），占用两列 |
+| 2 | SpacerTail | 宽字符的第二列占位符 |
+| 3 | SpacerHead | 软换行时在行尾标记宽字符延续 |
+
+**关键函数**：
+- `createScreen()` —— 创建屏幕，8 字节/单元格的 ArrayBuffer
+- `resetScreen()` —— 重用屏幕，使用 `BigInt64Array.fill()` 快速清空
+- `setCellAt()` —— 写入单元格，自动创建宽字符的 SpacerTail
+- `setCellStyleId()` —— 仅更新样式 ID，用于选择/搜索覆盖层
+- `cellAt()` / `cellAtIndex()` —— 读取单元格
+- `diff()` / `diffEach()` —— 比较两个屏幕，使用 `findNextDiff()` 快速跳过相同区域
+- `blitRegion()` —— 批量复制矩形区域（`TypedArray.set()`）
+- `clearRegion()` —— 快速清空矩形区域
+- `shiftRows()` —— 行位移（`copyWithin`），用于 DECSTBM 滚动优化
+- `markNoSelectRegion()` —— 标记选择排除区域
+- `migrateScreenPools()` —— 跨代池重置时重新 intern
+
+### Output（输出缓冲）
+
+文件：`src/ink/output.ts`
+
+收集渲染操作（Operations），在 `get()` 中统一应用到 Screen 缓冲区。
+
+**操作类型**：
+| 类型 | 说明 |
+|------|------|
+| `write` | 写入 ANSI 文本到指定位置 |
+| `blit` | 复制源屏幕的矩形区域 |
+| `clear` | 清空矩形区域 |
+| `clip` / `unclip` | 裁剪区域（嵌套 `overflow:hidden`） |
+| `shift` | 行位移 |
+| `noSelect` | 标记选择排除区域（最后应用） |
+
+**字符缓存**（`charCache`）：
+每行文本经过 tokenize（ANSI 解析）、grapheme 聚类、双向文本重排、样式 ID + 超链接预计算后缓存。大多数行在帧间不变，缓存命中后只需读取属性并调用 `setCellAt()`。
+
+**`writeLineToScreen()`**：
+核心写入函数，处理：
+- C0 控制字符（tab → 空格展开，ESC → CSI/single-char 序列跳过）
+- 零宽字符（组合标记等）静默跳过
+- 宽字符在行尾时放置 SpacerHead
+- 写时损坏区域追踪（`screen.damage`）
+
+### LogUpdate（差异比较与补丁生成）
+
+文件：`src/ink/log-update.ts`
+
+比较前一帧和当前帧的 Screen 缓冲区，生成最小补丁序列（`Diff = Patch[]`）。
+
+**补丁类型**：
+| 类型 | 说明 |
+|------|------|
+| `stdout` | 原始 ANSI 字符串输出 |
+| `clear` | 清空 N 行 |
+| `clearTerminal` | 完全清屏（全损坏，引发闪烁） |
+| `cursorHide` / `cursorShow` | 光标显隐 |
+| `cursorMove` | 光标相对移动 |
+| `cursorTo` | 光标绝对定位到列 |
+| `carriageReturn` | CR |
+| `hyperlink` | OSC 8 超链接 |
+| `styleStr` | 预序列化的 ANSI 样式过渡字符串 |
+
+**DECSTBM 滚动优化**：
+当 ScrollBox 的 `scrollTop` 变化时，使用硬件滚动（CSI `top;bottom r` + CSI `n S/T`）替代重写整个滚动区域，大幅减少输出字节。
+
+**全损坏重置**（`fullResetSequence_CAUSES_FLICKER`）：
+在以下情况触发终端完全清屏：
+- 终端尺寸变化（resize）
+- 内容高度超出视口后又缩小到视口内
+- 需要更新的行在滚动缓冲区中（不可达）
+- 这些重置会引发可见的闪烁
+
+**VirtualScreen**：
+内部辅助类，追踪虚拟光标位置和差异补丁列表，支持事务性操作（`txn()`）批量提交补丁。
+
+### Frame（帧结构）
+
+文件：`src/ink/frame.ts`
+
+```typescript
+type Frame = {
+  screen: Screen          // 屏幕缓冲区
+  viewport: Size           // 视口尺寸
+  cursor: Cursor           // 光标状态
+  scrollHint?: ScrollHint  // DECSTBM 滚动提示
+  scrollDrainPending?: boolean  // 是否需要继续帧
+}
+```
+
+辅助函数：
+- `shouldClearScreen()` —— 判断是否需要清屏（resize 或 offscreen）
+- `emptyFrame()` —— 创建空帧
+
+---
+
+## 布局引擎（Yoga）
+
+文件：`src/ink/layout/` 目录
+
+使用 [Yoga](https://yogalayout.com/) 的 WASM 实现进行 Flexbox 布局计算。
+
+**在渲染管线中的位置**：
+1. React commit 后，`resetAfterCommit` 调用 `rootNode.onComputeLayout()`
+2. `ink.tsx` 中的 `onComputeLayout` 调用 `root.yogaNode.calculateLayout()`
+3. Yoga 执行完整的 Flexbox 布局计��（含 `measureFunc` 回调用于文本测量）
+4. Renderer 读取 `getComputedWidth/Height/Top/Left` 获取布局结果
+
+**布局节点**：文件 `src/ink/layout/node.ts`，定义 `LayoutNode` 接口和所有布局常量（`LayoutEdge`, `LayoutDisplay`, `LayoutFlexDirection`, `LayoutJustify`, `LayoutAlign`, `LayoutOverflow`, `LayoutPositionType`, `LayoutWrap`, `LayoutGutter`）。
+
+**布局引擎**：文件 `src/ink/layout/engine.ts`，创建和管理 Yoga WASM 实例。提供 `createLayoutNode()` 和 `getYogaCounters()` 等函数。
+
+**测量函数**：
+- `ink-text`：`measureTextNode()` —— 处理文本换行、tab 展开、bi-di 重排
+- `ink-raw-ansi`：`measureRawAnsiNode()` —— 使用预设的 rawWidth/rawHeight
+
+---
+
+## 样式系统
+
+文件：`src/ink/styles.ts`
+
+样式类型定义（`Styles`）涵盖所有 CSS Flexbox 属性：
+
+**布局**：`display`, `position`, `overflow`, `flexDirection`, `flexWrap`, `flexGrow`, `flexShrink`, `flexBasis`, `alignItems`, `alignSelf`, `justifyContent`
+
+**尺寸**：`width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`（支持数值和百分比字符串）
+
+**间距**：`margin`, `padding`, `gap`（含 X/Y 方向缩写）
+
+**边框**：`borderStyle`（圆角/单线/双线等）, `borderColor`, `borderTop/Right/Bottom/Left`（控制各边显隐）
+
+**文本**：`textWrap`（8 种模式：`wrap`, `wrap-trim`, `end`, `middle`, `truncate-end`, `truncate`, `truncate-middle`, `truncate-start`）
+
+**其他**：`backgroundColor`, `opaque`, `noSelect`（选择排除）, `borderText`（边框内文本）
+
+`applyStyles()` 函数将 `Styles` 对象映射到 Yoga 节点属性。每个样式类别有独立的函数（`applyPositionStyles`, `applyOverflowStyles`, `applyFlexStyles` 等）。
+
+### TextStyles
+
+文件：`src/ink/styles.ts`
+
+```typescript
+type TextStyles = {
+  color?, backgroundColor?  // 颜色
+  dim?, bold?, italic?       // 字体样式
+  underline?, strikethrough? // 装饰
+  inverse?                   // 反色
+}
+```
+
+`TextStyles` 在 `<Text>` 组件中声明，通过 `ink-text` 节点的 `textStyles` 属性传递。渲染时由 `render-node-to-output.ts` 的 `buildTextStyles()` 转换为 ANSI SGR 序列。
+
+---
+
+## 事件系统
+
+### 键盘事件
+
+**Kitty 键盘协议**：在 raw mode 中启用 CSI u 扩展键编码（`ENABLE_KITTY_KEYBOARD` + `ENABLE_MODIFY_OTHER_KEYS`），使 Ctrl+Shift+字母 与 Ctrl+字母 可区分。终端识别通过在 XTVERSION 查询后设置。
+
+**输入解析**：文件 `src/ink/parse-keypress.ts`，状态机解析 stdin 的原始字节流。支持：
+- 普通字符（UTF-8）
+- CSI 序列（方向键、功能键等）
+- Kitty CSI u 序列（带修饰键编码）
+- SGR 鼠标编码（`<row;col;button M/m`)
+- DEC 私有模式响应（DCS 序列）
+- OSC 序列（操作系统命令）
+- 粘贴模式（`IN_PASTE` 状态）
+
+**`App` 组件中的处理**（文件 `src/ink/components/App.tsx`）：
+- `handleReadable()` —— stdin `readable` 事件回调
+- `processInput()` —— 调用 `parseMultipleKeypresses()` 解析多按键
+- `processKeysInBatch()` —— 在 `reconciler.discreteUpdates` 中批量处理按键，避免"最大更新深度超出"错误
+- 处理 `Ctrl+C`（退出）、`Ctrl+Z`（挂起）、终端焦点事件（DECSET 1004）
+
+### 鼠标事件
+
+通过 DECSET 1003（SGR 鼠标跟踪）启用/禁用。
+
+**`processKeysInBatch` 中的鼠标处理**（`handleMouseEvent()`）：
+- **press**：开始选择、多击检测（双击选中单词、三击选中行）
+- **drag**：扩展选择（字符/单词/行模式）
+- **release**：结束选择
+- **no-button motion**（模式 1003）：悬停事件分发（`onMouseEnter`/`onMouseLeave`）
+- **超链接**：单点击时延迟打开，双击取消
+
+**`handleMouseEvent()` 中的选择逻辑**：
+- `startSelection()` / `finishSelection()` / `hasSelection()`
+- 多击跟踪：`clickCount` 在 500ms 内递增，支持双击单词选择和三击行选择
+- `lastPressHadAlt`：记录 Alt 修饰键，用于终端判定
+
+### 焦点管理
+
+文件：`src/ink/focus.ts`
+
+`FocusManager` 存储在每个根节点，类似于浏览器 `document.activeElement`。
+
+**功能**：
+- `focus(node)` / `blur()` —— 获取/失去焦点
+- `handleNodeRemoved()` —— 节点移除时自动恢复焦点到栈中上一个
+- `handleAutoFocus()` —— 自动聚焦（`autoFocus` prop）
+- `handleClickFocus()` —— 点击聚焦（`tabIndex` prop）
+- `focusNext()` / `focusPrevious()` —— Tab / Shift+Tab 导航
+
+**焦点栈**：最多 32 层，用于节点移除后的焦点恢复。
+
+**事件分发**：事件系统使用 `Dispatcher` 类（`src/ink/events/dispatcher.ts`）处理捕获（Capture）和冒泡（Bubble）阶段。`EVENT_HANDLER_PROPS` 集合定义哪些 props 是事件处理器（`onClick`, `onKeyDown` 等）。
+
+---
+
+## 组件库
+
+文件：`src/ink/components/`
+
+| 组件 | 文件 | 说明 |
+|------|------|------|
+| `App` | `App.tsx` | 根组件，管理 stdin/stdout、raw mode、光标、挂起/恢复、事件分发、多击选择 |
+| `Box` | `Box.tsx` | 布局容器（类似 `<div>`），支持完整 Flexbox 样式和事件处理器（onClick, onKeyDown, onMouseEnter, onMouseLeave, onFocus, onBlur） |
+| `Text` | `Text.tsx` | 文本组件，支持颜色（color, backgroundColor）、加粗（bold）、斜体（italic）、下划线（underline）、删除线（strikethrough）、反色（inverse）、换行模式（wrap） |
+| `Button` | `Button.tsx` | 按钮组件（继承 Box 的点击能力） |
+| `Link` | `Link.tsx` | 超链接（使用 OSC 8 协议），终端不支持时回退到纯文本 |
+| `Spacer` | `Spacer.tsx` | 弹性空间填充（`flexGrow: 1`） |
+| `Newline` | `Newline.tsx` | 插入空白行 |
+| `ScrollBox` | `ScrollBox.tsx` | 滚动容器（`overflow: scroll`），支持 `scrollTo()`, `scrollToElement()` 和粘性滚动 |
+| `AlternateScreen` | `AlternateScreen.tsx` | 替代屏幕（alt-screen）管理 |
+| `RawAnsi` | `RawAnsi.tsx` | 原始 ANSI 字符串渲染（预计算的宽度和高度） |
+| `NoSelect` | `NoSelect.tsx` | 选择排除区域（如行号、diff 标记） |
+| `Ansi` | (在 ink.ts 中 re-export) | ANSI 文本渲染 |
+| `ErrorOverview` | `ErrorOverview.tsx` | 错误概览组件 |
+
+**Context 提供者**：
+
+| Context | 文件 | 提供内容 |
+|---------|------|----------|
+| `AppContext` | `AppContext.ts` | `exit()` 退出函数 |
+| `StdinContext` | `StdinContext.ts` | `stdin`, `setRawMode`, `internal_eventEmitter`, `internal_querier` |
+| `TerminalSizeContext` | `TerminalSizeContext.tsx` | `columns`, `rows` 终端尺寸 |
+| `TerminalFocusContext` | `TerminalFocusContext.tsx` | `isTerminalFocused` 终端焦点状态 |
+| `ClockContext` | `ClockContext.tsx` | 时钟/定时器（根据焦点状态调整间隔） |
+| `CursorDeclarationContext` | `CursorDeclarationContext.ts` | 声明式光标位置 |
+
+---
+
+## Hooks
+
+文件：`src/ink/hooks/`
+
+| Hook | 文件 | 说明 |
+|------|------|------|
+| `useInput` | `use-input.ts` | 处理用户键盘输入（`useLayoutEffect` 同步启用 raw mode），注册 `input` 事件监听器 |
+| `useStdin` | `use-stdin.ts` | 访问 stdin/setRawMode/EventEmitter |
+| `useApp` | `use-app.ts` | 访问 `exit()` 函数 |
+| `useAnimationFrame` | `use-animation-frame.ts` | 动画帧钩子（使用 `FRAME_INTERVAL_MS=16ms` 节流渲染） |
+| `useInterval` | `use-interval.ts` | 定时器（终端失焦时可选减速） |
+| `useSelection` | `use-selection.ts` | 文本选择状态管理（anchor, focus, word/line 模式） |
+| `useSearchHighlight` | `use-search-highlight.ts` | 搜索高亮状态（匹配位置、当前匹配导航） |
+| `useDeclaredCursor` | `use-declared-cursor.ts` | 声明式光标位置（用于 IME 输入和屏幕阅读器） |
+| `useTabStatus` | `use-tab-status.ts` | Tab 状态管理 |
+| `useTerminalFocus` | `use-terminal-focus.ts` | 终端焦点变化监听 |
+| `useTerminalTitle` | `use-terminal-title.ts` | 终端标题设置 |
+| `useTerminalViewport` | `use-terminal-viewport.ts` | 终端视口信息 |
+
+---
+
+## 文本选择
+
+文件：`src/ink/selection.ts`
+
+`SelectionState` 管理全屏模式下的文本选择：
+
+- **anchor**：选择起点（鼠标按下处）
+- **focus**：选择终点（鼠标拖动处）
+- **anchorSpan**：多击（双击/三击）时初始单词/行的范围
+- **scrolledOffAbove/Below**：选择过程中滚动出视口的文本
+- **softWrap 标记**：跟踪软换行位置
+
+**选择操作**：
+- `startSelection()` / `updateSelection()` / `finishSelection()`
+- `extendSelection()` —— 字符/单词/行模式扩展
+- `getSelectedText()` —— 获取选中文本（拼接跨行的选择，含滚动出视口的文本）
+- `applySelectionOverlay()` —— 在屏幕覆盖层中高亮选中区域
+
+---
+
+## 搜索高亮
+
+文件：`src/ink/render-to-screen.ts` 和 `src/ink/components/App.tsx`
+
+搜索高亮系统分为两个层次：
+
+1. **`renderToScreen()`** —— 在独立屏幕缓冲区中渲染单个消息，扫描查询字符串的位置
+2. **`applySearchHighlight()`** / **`applyPositionedHighlight()`** —— 将搜索匹配覆盖层应用到实际屏幕
+
+**匹配视觉风格**：
+- 普通匹配：反色（SGR 7，白色底，从主题继承）
+- 当前匹配（用户导航到的位置）：黄色背景（通过黄色前景 + 反色实现）+ 加粗 + 下划线
+
+---
+
+## 渲染管线完整流程
+
+从 React 组件到终端输出的完整流程：
+
+```
+1. React 更新 (setState / 新 props)
+    │
+2. Reconciler commit (resetAfterCommit)
+    ├── onComputeLayout: Yoga calculateLayout()
+    └── onRender: scheduleRender (节流, 16ms)
+    │
+3. createRenderer → renderNodeToOutput
+    ├── 递归遍历 DOM 树
+    ├── 应用 scrollTop 偏移
+    ├── 写操作 -> Output buffer
+    └── blit 操作 -> Output buffer
+    │
+4. Output.get()
+    ├── 应用所有操作到 Screen
+    ├── 处理裁剪区域
+    ├── 处理 absolute 清除
+    └── 更新 softWrap 标记
+    │
+5. LogUpdate.render()
+    ├── 检查是否要全损坏重置
+    ├── DECSTBM 滚动优化
+    ├── diffEach 比较前后帧
+    ├── 处理增长/收缩
+    └── 生成 Patch[]
+    │
+6. optimize() — 补丁合并与去重
+    │
+7. writeDiffToTerminal() — 补丁序列化为 ANSI → stdout
+    │
+8. 屏幕选择/搜索覆盖层更新
+    │
+9. 光标定位
+    └── 下一帧
+```
+
+---
+
+## 特殊功能
+
+### 双缓冲（Double Buffering）
+
+使用前后帧（`frontFrame` / `backFrame`）实现双缓冲：
+- `backFrame.screen` 是当前渲染目标
+- `frontFrame.screen` 是前一帧的屏幕，用于差异比较和 blit
+- 渲染帧切换后进行缓冲池交换（`swapFrames()`）
+
+### 屏幕伤害追踪（Damage Tracking）
+
+每个 `Screen` 有一个 `damage` 矩形区域，记录自上次重置以来发生写操作的区域。`diffEach()` 只扫描损伤区域，避免遍历整个屏幕。
+
+### 双向文本（BiDi）
+
+文件：`src/ink/bidi.ts`
+
+使用 Unicode Bidirectional Algorithm 对文本行进行重排。在 `writeLineToScreen()` 中，每行文本在 tokenize 和 grapheme 聚类后执行 `reorderBidi()`。
+
+### ANSI 解析与 Grapheme 聚类
+
+使用 `@alcalzone/ansi-tokenize` 解析 ANSI 序列，然后通过 `Intl.Segmenter` 进行 grapheme 聚类（支持家族 emoji 等多码点字符）。结果缓存到 `charCache`，帧间重用。
+
+### 终端查询（Terminal Querier）
+
+文件：`src/ink/terminal-querier.ts`
+
+`TerminalQuerier` 通过 DEC 请求序列（如 DA1、XTVERSION、DECRPM）与终端通信。它维护一个待处理请求的 Promise 队列，在收到终端响应时解析相应的 Promise。
+
+### DEC 私有模式
+
+文件：`src/ink/termio/dec.ts`
+
+管理 DEC 私有模式：
+- 鼠标跟踪：`ENABLE_MOUSE_TRACKING(SGR, 1003)` / `DISABLE_MOUSE_TRACKING`
+- 光标显隐：`HIDE_CURSOR` / `SHOW_CURSOR`
+- 焦点报告：`EFE` / `DFE`（DECSET 1004）
+- 滚轮支持：通过 `DECRPM` 查询终端能力
+
+### Kitty 键盘协议
+
+文件：`src/ink/termio/ansi.ts` 和 `src/ink/termio/csi.ts`
+
+通过 CSI `>1u`（Kitty 协议）和 CSI `>4;2m`（xterm modifyOtherKeys）启用扩展键盘报告，使修饰键组合（Ctrl+Shift+A 等）可区分。
+
+### 替代屏幕（Alt Screen）
+
+`<AlternateScreen>` 组件管理终端的替代屏幕缓冲区。启用时：
+- 内容始终恰好占满终端行数
+- 光标隐藏
+- 启用 DECSET 1000/1002/1003 鼠标跟踪
+- 支持 DECSTBM 滚动优化
+- 退出时恢复主屏幕内容
+
+### 声明式光标（Declared Cursor）
+
+`useDeclaredCursor` 钩子和 `CursorDeclarationContext` 允许组件声明当前光标位置（如输入框），使 Ink 在每一帧后将终端光标放置在该位置，支持 IME 输入和屏幕阅读器。
+
+### 滚动容器（ScrollBox）
+
+`<ScrollBox>` 组件（`overflow: scroll`）实现：
+- `scrollTop`：可编程滚动位置
+- `pendingScrollDelta`：累积的滚动增量（限制 SCROLL_MAX_PER_FRAME 行/帧，防止大幅跳动）
+- `stickyScroll`：粘性滚动（内容增长时自动保持在底部）
+- `scrollTo(y)` / `scrollToElement(el, offset)`：可编程滚动
+- `scrollHeight` / `scrollViewportHeight`：滚动信息查询
+- `scrollClampMin` / `scrollClampMax`：虚拟滚动边界保护
+- 渲染时通过 `output.shift()` 实现 DECSTBM 硬件滚动
+
+### 选择排除（NoSelect）
+
+`<NoSelect>` 组件标记区域为选择排除：
+- `noSelect` 模式：仅排除该盒子的精确区域
+- `from-left-edge` 模式：从第 0 列到盒子右边缘的整行区域
+- `screen.noSelect` 位图每帧重置，`blitRegion` 复制时连带复制
+
+### 调试与性能分析
+
+- `CLAUDE_CODE_DEBUG_REPAINTS`：追踪重绘来源组件
+- `CLAUDE_CODE_COMMIT_LOG`：记录提交/渲染时间日志
+- YOGA 计数器：`getYogaCounters()` 报告每个框架的节点访问、测量、缓存命中
+- `FRAME_INTERVAL_MS = 16`：60fps 帧率
+- Blit/Write 比率日志：高频写入（而非 blit）时发出警告
+
+---
+
+## 文件索引
+
+按功能类别整理的核心文件：
+
+| 类别 | 文件 |
+|------|------|
+| 主入口 | `src/ink.ts`, `src/ink/ink.tsx` |
+| DOM | `src/ink/dom.ts` |
+| Reconciler | `src/ink/reconciler.ts` |
+| Renderer | `src/ink/renderer.ts`, `src/ink/render-node-to-output.ts` |
+| Screen | `src/ink/screen.ts` |
+| Output | `src/ink/output.ts` |
+| LogUpdate | `src/ink/log-update.ts` |
+| Frame | `src/ink/frame.ts` |
+| Styles | `src/ink/styles.ts` |
+| Focus | `src/ink/focus.ts` |
+| Selection | `src/ink/selection.ts` |
+| Layout | `src/ink/layout/engine.ts`, `node.ts` |
+| Event Dispatcher | `src/ink/events/dispatcher.ts` |
+| Event Handlers | `src/ink/events/event-handlers.ts` |
+| Components | `src/ink/components/` (App, Box, Text, Button, Link, Spacer, Newline, ScrollBox, AlternateScreen, RawAnsi, NoSelect, ErrorOverview) |
+| Hooks | `src/ink/hooks/` (use-input, use-stdin, use-app, use-animation-frame, use-interval, use-selection, use-search-highlight, use-declared-cursor, use-tab-status, use-terminal-focus, use-terminal-title, use-terminal-viewport) |
+| Termio | `src/ink/termio/ansi.ts`, `csi.ts`, `dec.ts`, `osc.ts` |
+| Bidi | `src/ink/bidi.ts` |
+| Constants | `src/ink/constants.ts` |
+| Contexts | `src/ink/components/AppContext.ts`, `StdinContext.ts`, `TerminalSizeContext.tsx`, `TerminalFocusContext.tsx`, `ClockContext.tsx`, `CursorDeclarationContext.ts` |

docs/memory-context/context.md

@@ -0,0 +1,194 @@
+# 上下文管理
+
+## 概述
+
+VersperClaw 的上下文管理系统负责构建模型会话的输入上下文，包含系统级信息和用户级信息，并在上下文超过限制时自动压缩。
+
+---
+
+## 系统上下文（getSystemContext）
+
+定义于 `src/context.ts`，通过 `getSystemContext()` 构建，缓存在会话期间不变。
+
+### 包含内容
+
+1. **Git 状态**（`getGitStatus()`）
+   - 当前分支、主分支、Git 用户
+   - 工作区状态（staged/unstaged 修改）
+   - 最近 5 条 commit 记录
+   - 限制在 2000 字符以内，超出时截断并提示用户使用 `git status`
+   - 在 CCR 远程模式或 Git 指令禁用时跳过
+
+2. **缓存破坏标记**（Cache Breaker）
+   - 仅在 `BREAK_CACHE_COMMAND` feature gate 启用时注入
+   - 用于紧急调试状态更新
+
+### 代码结构
+
+```typescript
+export const getSystemContext = memoize(
+  async (): Promise<{ [k: string]: string }> => {
+    const gitStatus = isEnvTruthy(process.env.CLAUDE_CODE_REMOTE)
+      ? null
+      : await getGitStatus()
+    return {
+      ...(gitStatus && { gitStatus }),
+      ...(injection && { cacheBreaker: `[CACHE_BREAKER: ${injection}]` }),
+    }
+  },
+)
+```
+
+---
+
+## 用户上下文（getUserContext）
+
+定义于 `src/context.ts`，通过 `getUserContext()` 构建，同样缓存在会话期间不变。
+
+### 包含内容
+
+1. **CLAUDE.md 文件**
+   - 自动发现项目中的 CLAUDE.md 文件（通过 `getClaudeMds()`）
+   - 支持 `--add-dir` 在 bare 模式下添加额外的 CLAUDE.md 目录
+   - 可通过 `CLAUDE_CODE_DISABLE_CLAUDE_MDS` 环境变量禁用
+   - 记忆文件（memory files）被过滤后注入
+
+2. **当前日期**
+   - 格式：`Today's date is YYYY-MM-DD.`
+   - 使用 `getLocalISODate()` 获取本地日期
+
+### 代码结构
+
+```typescript
+export const getUserContext = memoize(
+  async (): Promise<{ [k: string]: string }> => {
+    const claudeMd = shouldDisableClaudeMd
+      ? null
+      : getClaudeMds(filterInjectedMemoryFiles(await getMemoryFiles()))
+    return {
+      ...(claudeMd && { claudeMd }),
+      currentDate: `Today's date is ${getLocalISODate()}.`,
+    }
+  },
+)
+```
+
+---
+
+## 上下文压缩（Compact）
+
+当对话上下文超过 API 限制或用户手动触发时，自动或手动压缩对话历史。
+
+### 压缩触发
+
+| 触发方式 | 说明 |
+|----------|------|
+| **自动压缩** | 上下文超过阈值时自动触发（`autoCompactThreshold`） |
+| **手动压缩** | 用户执行 `/compact` 命令 |
+| **部分压缩** | 用户选择特定消息前后的历史进行压缩 |
+| **反应式压缩** | API 返回 prompt-too-long 时自动触发 |
+
+### 压缩流程（`src/services/compact/compact.ts`）
+
+`compactConversation()` 主流程：
+
+1. **PreCompact Hook**：执行预压缩钩子
+2. **摘要生成**：将旧消息发送给模型生成摘要
+   - 支持 prompt cache 共享（通过 forked agent 复用主会话的缓存前缀）
+   - 自动重试（最多 3 次 PTL 重试 + 2 次流式重试）
+3. **文件状态恢复**：重建最近读取的文件附件（最多 5 个文件，50K token 预算）
+4. **状态恢复**：plan 文件、技能附件、异步 Agent 状态
+5. **工具和 Agent 清单重新声明**：延迟工具、MCP 指令、Agent 列表
+6. **SessionStart Hook**：执行会话启动钩子
+7. **PostCompact Hook**：执行压缩后钩子
+
+### 压缩边界消息
+
+压缩后在消息流中插入 `SystemCompactBoundaryMessage`，包含：
+- 压缩原因（auto/manual）
+- 压缩前的 token 计数
+- 上一个消息的 UUID（用于链式追踪）
+- 用户反馈（手动压缩时）
+- 压缩的消息数量
+
+### 部分压缩（Partial Compact）
+
+`partialCompactConversation()` 支持两种方向：
+
+| 方向 | 说明 | 缓存影响 |
+|------|------|----------|
+| `from` | 压缩 pivot 索引之后的消息，保留之前的内容 | 保留前缀缓存 |
+| `up_to` | 压缩 pivot 索引之前的消息，保留之后的内容 | 缓存失效 |
+
+### 文件附件恢复
+
+`createPostCompactFileAttachments()` 在压缩后自动恢复最近读取的文件：
+
+- 基于读取时间戳排序，恢复最近的文件
+- 跳过已在保留消息中的文件（避免重复）
+- 跳过 plan 文件和记忆文件
+- 受文件数量（5）和 token 预算（50K）双重限制
+- 跳过 `FILE_UNCHANGED_STUB` 对应的文件（压缩时已处理的重复读取）
+
+### 压缩注意事项
+
+- **Plan 模式保持**：如果在 plan 模式下压缩，自动注入 plan mode 附件
+- **技能保留**：已调用的技能内容会被保留（每个技能 5K token 预算，总 25K）
+- **缓存破坏检测**：压缩后通知缓存破坏检测系统
+- **会话元数据**：重新追加会话元数据（自定义标题、标签）
+- **助手模式转录**：在 KAIROS 模式下，将压缩的对话段写入转录文件
+
+---
+
+## React Contexts（src/context/）
+
+CLI 用户界面使用 React Context 管理多种状态：
+
+### voice.tsx（语音上下文）
+- `VoiceProvider` 提供语音状态管理
+- 状态：`idle` / `recording` / `processing`
+- 包含：录音状态、错误信息、实时转录文本、音频电平、预热状态
+- 基于 React Context + Zustand-style store 模式
+
+### mailbox.tsx（消息邮箱）
+- 管理应用内消息队列
+- 处理消息的发送、接收和状态更新
+
+### stats.tsx（状态统计）
+- 提供性能统计数据的上下文
+- 包括 token 使用量、API 调用次数等
+
+### notifications.tsx（通知系统）
+- 管理应用内通知
+- 支持不同优先级（immediate、later）
+- 支持不同颜色（error、info 等）
+
+### fpsMetrics.tsx（FPS 指标）
+- 跟踪 UI 渲染性能
+- 用于调试和优化
+
+### modalContext.tsx（模态框上下文）
+- 管理模态对话框的显示和隐藏
+- 支持堆叠模式
+
+### promptOverlayContext.tsx（提示覆盖层）
+- 管理提示输入区域的覆盖层
+
+### overlayContext.tsx（覆盖层上下文）
+- 管理通用覆盖层组件
+
+### QueuedMessageContext.tsx（队列消息上下文）
+- 管理消息队列状态
+- 处理消息的排队和调度
+
+---
+
+## 核心文件
+
+| 文件 | 路径 | 用途 |
+|------|------|------|
+| context.ts | `src/context.ts` | 系统和用户上下文构建（getSystemContext / getUserContext） |
+| compact.ts | `src/services/compact/compact.ts` | 对话压缩主逻辑 |
+| compactWarningHook.ts | `src/services/compact/compactWarningHook.ts` | 压缩警告钩子 |
+| compactWarningState.ts | `src/services/compact/compactWarningState.ts` | 压缩警告状态管理 |
+| postCompactCleanup.ts | `src/services/compact/postCompactCleanup.ts` | 压缩后清理 |

docs/memory-context/memory.md

@@ -0,0 +1,210 @@
+# 自动记忆系统
+
+## 概述
+
+VersperClaw 拥有一个基于文件的持久化记忆存储系统（Memdir），允许 Agent 在不同会话间记住用户信息、偏好、项目上下文等。记忆存储在项目对应的 `~/.claude/projects/<slug>/memory/` 目录中。
+
+---
+
+## Memdir 系统
+
+### 目录结构
+
+```
+~/.claude/projects/<project-slug>/memory/
+├── MEMORY.md                  # 入口索引文件
+├── user_role.md               # 用户类型记忆文件
+├── feedback_testing.md        # 反馈类型记忆文件
+├── project_deadlines.md       # 项目类型记忆文件
+└── reference_dashboards.md    # 参考类型记忆文件
+```
+
+### 记忆类型
+
+系统定义了四种记忆类型（`src/memdir/memoryTypes.ts`），限制为无法从项目当前状态推导出的信息：
+
+| 类型 | 用途 | 示例 |
+|------|------|------|
+| **user** | 用户角色、职责、知识背景 | "用户是资深 Go 开发者，首次接触 React" |
+| **feedback** | 用户对工作方式的指导 | "不要 mock 数据库——测试必须用真实数据库" |
+| **project** | 项目上下文、目标、事件 | "2026-03-05 之后冻结所有非关键合并" |
+| **reference** | 外部系统的指针 | "Pipeline bugs 在 Linear 项目 INGEST 中跟踪" |
+
+### 不应该保存的内容
+
+- 代码模式、架构、文件路径——这些可从当前项目状态推导
+- Git 历史、最近的变更——`git log` / `git blame` 是权威来源
+- 调试解决方案——修复在代码中，commit message 包含上下文
+- 已在 CLAUDE.md 中记录的内容
+- 临时任务细节——进行中的工作、临时状态
+
+---
+
+## MEMORY.md 入口索引
+
+### 文件规范
+
+MEMORY.md 是记忆系统的入口索引文件（非记忆本身）：
+
+- 路径：`<memoryDir>/MEMORY.md`
+- 最大行数：**200 行**（`MAX_ENTRYPOINT_LINES`）
+- 最大字节数：**25,000 字节**（`MAX_ENTRYPOINT_BYTES`）
+- 格式：每行一个条目：`- [Title](file.md) — 简短描述`
+- 超过限制时自动截断并追加警告
+
+### 截断策略
+
+定义于 `src/memdir/memdir.ts` 的 `truncateEntrypointContent()`：
+
+1. 首先按行数截断（保留前 200 行）
+2. 然后按字节数截断（在最后一个换行符处切割，避免中断行）
+3. 追加截断警告说明原因
+
+---
+
+## 记忆生命周期
+
+### 保存（Save）
+
+两种保存方式：
+
+1. **显式请求**：用户要求 Agent 记住某事时立即保存
+2. **系统自动提取**：通过 `extractMemories`（`src/services/extractMemories/extractMemories.ts`）在后台自动提取有价值的记忆
+
+保存是两步过程：
+1. 写入记忆文件（如 `user_role.md`），使用 frontmatter 格式
+2. 在 `MEMORY.md` 中添加指向该文件的索引条目
+
+### Frontmatter 格式
+
+```markdown
+---
+name: {{记忆名称}}
+description: {{一行描述——用于判断相关性，越具体越好}}
+type: {{user / feedback / project / reference}}
+---
+
+{{记忆内容 — 对于 feedback/project 类型，结构为：规则/事实，然后 **Why:** 和 **How to apply:** 行}}
+```
+
+### 检索（Recall）
+
+`findRelevantMemories()`（`src/memdir/findRelevantMemories.ts`）使用 Sonnet 模型选择与当前查询相关的记忆：
+
+1. 扫描记忆目录中的所有文件，提取文件名和描述
+2. 将查询和可用记忆清单发送给 Sonnet 模型
+3. 模型返回最相关的记忆文件名列表（最多 5 个）
+4. 返回绝对文件路径和 mtime
+
+```typescript
+export async function findRelevantMemories(
+  query: string,          // 用户查询
+  memoryDir: string,      // 记忆目录路径
+  signal: AbortSignal,    // 取消信号
+  recentTools?: string[], // 最近使用的工具（过滤不相关的 API 文档）
+  alreadySurfaced?: Set<string>, // 已展示的文件（避免重复选择）
+): Promise<RelevantMemory[]>
+```
+
+**选择性过滤**：
+- 排除已在对话中展示的文件（`alreadySurfaced`）
+- 排除最近正在使用的工具的参考文档
+- 仍选择包含警告、陷阱、已知问题的记忆
+
+### 更新（Update）
+
+- 记忆文件的内容可以直接覆盖
+- MEMORY.md 中的索引条目保持最新
+- 语义而非时间顺序组织记忆
+
+### 清除（Delete）
+
+用户要求忘记时，找到并删除相关条目（记忆文件 + MEMORY.md 索引）。
+
+---
+
+## 记忆 Age（新鲜度追踪）
+
+### mtime 追踪
+
+每个记忆文件都有 `mtimeMs`（修改时间戳），在检索时返回：
+
+```typescript
+export type RelevantMemory = {
+  path: string
+  mtimeMs: number
+}
+```
+
+### 新鲜度提示
+
+- `MEMORY_DRIFT_CAVEAT`：记忆会随时间过时。在基于记忆回答前，需验证记忆是否仍准确
+- 如果回忆的记忆与当前信息冲突，信任当前观察，更新或移除过时记忆
+
+### 记忆推荐前的验证
+
+即使回忆到的记忆命名了特定函数、文件或标志，也只是"在写入时存在"的声明。在推荐前：
+
+- 如果记忆提到文件路径：检查文件是否存在
+- 如果记忆提到函数或标志：通过 grep 确认
+- 如果用户即将基于推荐采取行动：先验证
+
+---
+
+## 高级特性
+
+### 团队记忆（Team Memory）
+
+通过 `TEAMMEM` feature gate 启用。使用 `getTeamMemPath()`（`src/memdir/teamMemPaths.ts`）获取团队记忆目录路径。
+
+团队记忆和私有记忆使用不同的作用域标签（`<scope>`），共享相同的四种记忆类型。
+
+### 助手模式每日日志（Assistant Daily Log）
+
+通过 `KAIROS` feature gate 启用。长期运行的助手模式的记忆策略：
+
+- 按日期追加到 `logs/YYYY/MM/YYYY-MM-DD.md`
+- 夜间 `/dream` 技能将日志蒸馏为主题文件 + MEMORY.md
+- 避免在长时间会话中频繁重写 MEMORY.md
+
+### 自动 Dream（Auto Dream）
+
+`src/services/autoDream/autoDream.ts` 在后台自动执行记忆整理，包括：
+- 合并重复记忆
+- 更新过时信息
+- 清除无关条目
+
+### 团队记忆同步（Team Memory Sync）
+
+`src/services/teamMemorySync/` 提供团队记忆的实时同步功能，包括文件监控（watcher）和秘密保护（secret guard）。
+
+---
+
+## 配置文件
+
+### 路径解析
+
+`getAutoMemPath()`（`src/memdir/paths.ts`）的路径解析顺序：
+
+1. `CLAUDE_COWORK_MEMORY_PATH_OVERRIDE` 环境变量（完全路径覆盖）
+2. `autoMemoryDirectory` 设置（来自 settings.json 的可信源）
+3. `<memoryBase>/projects/<sanitized-git-root>/memory/`
+
+### 启用/禁用
+
+禁用链（优先级从高到低）：
+1. `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1/true` 环境变量
+2. `CLAUDE_CODE_SIMPLE`（--bare 模式）
+3. 远程模式但未设置 `CLAUDE_CODE_REMOTE_MEMORY_DIR`
+4. `autoMemoryEnabled: false` 在 settings.json 中
+5. 默认：启用
+
+### 核心文件
+
+| 文件 | 路径 | 用途 |
+|------|------|------|
+| memdir.ts | `src/memdir/memdir.ts` | 记忆提示构建、入口索引管理 |
+| paths.ts | `src/memdir/paths.ts` | 路径解析、启停检查 |
+| findRelevantMemories.ts | `src/memdir/findRelevantMemories.ts` | 基于 Sonnet 的相关记忆检索 |
+| memoryTypes.ts | `src/memdir/memoryTypes.ts` | 记忆类型定义和提示文本 |
+| memoryScan.ts | `src/memdir/memoryScan.ts` | 记忆文件扫描 |

docs/remote-bridge/overview.md

@@ -0,0 +1,199 @@
+# 远程桥接 / Remote Control
+
+## 概述
+
+Bridge（桥接）模式将本地 CLI 连接到 Anthropic 的远程会话基础设施（CCR, Claude Code Remote），使用户可以通过 claude.ai/code 从浏览器控制本地终端。
+
+---
+
+## 两种传输模式
+
+### 1. 基于环境 (env-based)
+
+通过 Environments API 进行 poll/dispatch：
+
+1. CLI 注册为一个 "环境"（environment）到 Anthropic 服务器
+2. 服务器通过 `pollForWork` API 分发工作
+3. 客户端领取（acknowledge）工作、执行、发送心跳、返回结果
+
+**核心 API（`src/bridge/bridgeApi.ts`）**：
+
+| 端点 | 方法 | 用途 |
+|------|------|------|
+| `POST /v1/environments/bridge` | registerBridgeEnvironment | 注册当前终端为可用的执行环境 |
+| `GET .../work/poll` | pollForWork | 轮询待处理的工作 |
+| `POST .../work/{id}/ack` | acknowledgeWork | 确认领取工作 |
+| `POST .../work/{id}/heartbeat` | heartbeatWork | 发送心跳（延长租约） |
+| `POST .../work/{id}/stop` | stopWork | 停止工作 |
+| `DELETE .../environments/bridge/{id}` | deregisterEnvironment | 注销环境 |
+
+**认证**：使用 OAuth token 或 Bridge Access Token。
+
+### 2. 无环境 (env-less)
+
+直接通过 OAuth → Worker JWT 交换来连接远程会话：
+
+1. 通过 OAuth 获取访问令牌
+2. 直接连接到远程会话 WebSocket（`/v1/sessions/ws/{sessionId}/subscribe`）
+3. 使用 SDK 消息格式进行双向通信
+
+**核心组件（`src/remote/`）**：
+
+| 文件 | 路径 | 用途 |
+|------|------|------|
+| SessionsWebSocket.ts | `src/remote/SessionsWebSocket.ts` | WebSocket 客户端 |
+| sdkMessageAdapter.ts | `src/remote/sdkMessageAdapter.ts` | SDK 消息转换适配器 |
+
+---
+
+## 核心组件
+
+### bridgeApi.ts（`src/bridge/bridgeApi.ts`）
+
+HTTP 客户端，封装了所有 Bridge API 调用：
+
+- **OAuth 认证**：自动 401 重试 + token 刷新（通过 `onAuth401` 回调）
+- **BridgeFatalError**：不可重试的错误（认证失败、权限不足、会话过期）
+- **ID 验证**：`validateBridgeId()` 防止路径遍历攻击
+- **错误处理**：对 401/403/404/410/429 状态码分别处理
+
+```typescript
+export class BridgeFatalError extends Error {
+  readonly status: number
+  readonly errorType: string | undefined
+}
+```
+
+### bridgeMain.ts（`src/bridge/bridgeMain.ts`）
+
+主桥接逻辑，约 3000 行。负责：
+
+- 环境注册与生命周期管理
+- 工作（work）的 poll/dispatch 循环
+- 会话（session）的创建、运行、恢复
+- 多会话支持（`--spawn`, `--capacity`, `--create-session-in-dir`）
+- 优雅关闭（SIGTERM → SIGKILL 宽限期）
+- 退避策略（连接退避、通用退避、stopWork 退避）
+
+```typescript
+export type BackoffConfig = {
+  connInitialMs: number      // 连接初始延迟
+  connCapMs: number           // 连接最大延迟 (2min)
+  connGiveUpMs: number        // 连接放弃时间 (10min)
+  generalInitialMs: number    // 通用初始延迟
+  generalCapMs: number        // 通用最大延迟 (30s)
+  generalGiveUpMs: number     // 通用放弃时间 (10min)
+  shutdownGraceMs?: number    // SIGTERM→SIGKILL 宽限期
+}
+```
+
+### replBridge.ts（`src/bridge/replBridge.ts`）
+
+REPL 集成桥接，约 2400 行。在 REPL（交互式终端）模式下将 CLI 连接到远程会话：
+
+- 通过 `HybridTransport` 实现消息转发
+- 支持 CCR v1/v2 协议（`createV1ReplTransport` / `createV2ReplTransport`）
+- 消息入口（ingress）处理
+- 控制请求/响应（`SDKControlRequest` / `SDKControlResponse`）
+- 容量唤醒（capacity wake）信号
+
+```typescript
+export type ReplBridgeHandle = {
+  bridgeSessionId: string
+  environmentId: string
+  sessionIngressUrl: string
+  writeMessages(messages: Message[]): void
+  writeSdkMessages(messages: SDKMessage[]): void
+  sendControlRequest(request: SDKControlRequest): void
+  sendControlResponse(response: SDKControlResponse): void
+  sendControlCancelRequest(requestId: string): void
+  sendResult(): void
+  teardown(): Promise<void>
+}
+```
+
+### SessionsWebSocket.ts（`src/remote/SessionsWebSocket.ts`）
+
+WebSocket 客户端，用于直接连接远程会话：
+
+**协议**：
+1. 连接到 `wss://api.anthropic.com/v1/sessions/ws/{sessionId}/subscribe?organization_uuid=...`
+2. 发送认证消息：`{ type: 'auth', credential: { type: 'oauth', token: '...' } }`
+3. 接收 SDK 消息流
+
+**重连机制**：
+- `RECONNECT_DELAY_MS = 2000`：重连延迟 2 秒
+- `MAX_RECONNECT_ATTEMPTS = 5`：最大重连次数
+- `PING_INTERVAL_MS = 30000`：30 秒心跳间隔
+- `PERMANENT_CLOSE_CODES = new Set([4003])`：4003（未授权）为永久关闭，不重连
+- `MAX_SESSION_NOT_FOUND_RETRIES = 3`：4001（会话未找到）有限重试（压缩期间可能短暂出现）
+
+```typescript
+type SessionsWebSocketCallbacks = {
+  onMessage: (message: SessionsMessage) => void
+  onClose?: () => void
+  onError?: (error: Error) => void
+  onConnected?: () => void
+  onReconnecting?: () => void
+}
+```
+
+### sdkMessageAdapter.ts（`src/remote/sdkMessageAdapter.ts`）
+
+SDK 消息格式转换器。将 CCR 发送的 SDK 格式消息（`SDKMessage`）转换为 CLI 内部的消息类型（`Message`）：
+
+- `convertAssistantMessage()`: `SDKAssistantMessage` → `AssistantMessage`
+- `convertStreamEvent()`: `SDKPartialAssistantMessage` → `StreamEvent`
+- 处理多种消息类型：assistant、system、compact_boundary、status、tool_progress、result 等
+
+### remotePermissionBridge.ts
+
+在远程会话中处理权限请求桥接（位于 `src/hooks/useSSHSession.ts`、`useRemoteSession.ts`、`useDirectConnect.ts`），将远程权限提示通过 WebSocket 转发给用户。
+
+---
+
+## 认证机制
+
+| 机制 | 说明 |
+|------|------|
+| **OAuth Token** | 通过 OAuth 2.0 流程获取的访问令牌 |
+| **Bridge Access Token** | 桥接模式专用的访问令牌，通过 `workSecret.ts` 中的 `decodeWorkSecret()` 解码 |
+| **Trusted Device Token** | `X-Trusted-Device-Token` 头部，用于权限提升 |
+| **Token 刷新** | `handleOAuth401Error` 在 401 时自动刷新 |
+
+---
+
+## WebSocket 协议（CCR v1/v2）
+
+### 认证流程
+
+```
+Client → Server: { type: "auth", credential: { type: "oauth", token: "..." } }
+Server → Client: { type: "auth_ok" }  或  { type: "auth_error" }
+```
+
+### 消息格式
+
+- **CCR v1**：通过 `replBridgeTransport.ts` 的 `createV1ReplTransport` 处理
+- **CCR v2**：通过 `createV2ReplTransport` 处理，使用 `buildCCRv2SdkUrl()` 构建 URL
+
+### 心跳保活
+
+- 标准 WebSocket ping：30 秒间隔
+- 会话活动信号（`sendSessionActivitySignal()`）在压缩等长时间操作期间发送，防止 WebSocket 因 idle 超时被断开
+
+---
+
+## 其他组件
+
+| 文件 | 路径 | 用途 |
+|------|------|------|
+| bridgeConfig.ts | `src/bridge/bridgeConfig.ts` | 桥接配置管理 |
+| bridgeMessaging.ts | `src/bridge/bridgeMessaging.ts` | 桥接消息处理逻辑 |
+| capacityWake.ts | `src/bridge/capacityWake.ts` | 容量唤醒信号 |
+| codeSessionApi.ts | `src/bridge/codeSessionApi.ts` | 代码会话 API |
+| trustedDevice.ts | `src/bridge/trustedDevice.ts` | 受信任设备管理 |
+| workSecret.ts | `src/bridge/workSecret.ts` | Work Secret 编解码 |
+| sessionIdCompat.ts | `src/bridge/sessionIdCompat.ts` | 会话 ID 兼容性转换 |
+| pollConfig.ts | `src/bridge/pollConfig.ts` | 轮询间隔配置 |
+| types.ts | `src/bridge/types.ts` | 桥接模块类型定义 |

docs/server/overview.md

@@ -0,0 +1,185 @@
+# 桌面 HTTP/WebSocket 服务器
+
+## 概述
+
+VersperClaw 桌面服务器是一个同进程 HTTP + WebSocket 服务器，基于 **Bun.serve()** 运行，为 Tauri 桌面应用提供全套 API 接口。服务器与 CLI 子进程通过 SDK WebSocket Bridge 通信，桌面 UI 通过客户端 WebSocket 与服务器交互。
+
+- **入口文件**: `src/server/server.ts`
+- **运行时**: Bun (JavaScript/TypeScript 运行时)
+- **默认端口**: 3456
+- **架构**: 单进程，HTTP + WebSocket 共存
+
+## 路由系统
+
+路由定义在 `src/server/router.ts`。所有 API 请求统一由 `handleApiRequest()` 函数处理，根据 URL 路径第二段（resource）分发到对应的 API handler。
+
+当前支持约 **28 个 API 资源路径**，每个 handler 部署在 `src/server/api/` 目录下独立的文件中。
+
+## API 端点
+
+### 会话管理
+
+| 路径 | 描述 |
+|------|------|
+| `/api/sessions` | 会话 CRUD — 创建、读取、更新、删除会话 |
+| `/api/sessions/:id/chat/*` | 会话内的对话操作（由 conversations handler 处理） |
+
+对应文件: `api/sessions.ts`
+
+### 对话管理
+
+| 路径 | 描述 |
+|------|------|
+| `/api/conversations` | 对话 CRUD — 会话消息的读写管理 |
+
+对应文件: `api/conversations.ts`
+
+### 模型配置
+
+| 路径 | 描述 |
+|------|------|
+| `/api/models` | 获取可用模型列表 |
+| `/api/models/current` | 获取/切换当前选中的模型 |
+| `/api/effort` | 获取/设置 Effort 等级（low / medium / high / max） |
+
+对应文件: `api/models.ts`
+
+### 设置与权限
+
+| 路径 | 描述 |
+|------|------|
+| `/api/settings` | 应用设置读写 |
+| `/api/permissions` | 权限配置（由 settings handler 处理） |
+
+对应文件: `api/settings.ts`
+
+### MCP
+
+| 路径 | 描述 |
+|------|------|
+| `/api/mcp` | MCP 服务器管理 — 连接配置与状态 |
+
+对应文件: `api/mcp.ts`
+
+### 插件与技能
+
+| 路径 | 描述 |
+|------|------|
+| `/api/plugins` | 插件管理 — 安装、卸载、更新、启用/禁用 |
+| `/api/skills` | 技能管理 |
+
+对应文件: `api/plugins.ts`, `api/skills.ts`
+
+### 诊断
+
+| 路径 | 描述 |
+|------|------|
+| `/api/doctor` | 环境诊断 — 检查系统配置是否正常 |
+| `/api/diagnostics` | 诊断事件记录与查询 |
+
+对应文件: `api/doctor.ts`, `api/diagnostics.ts`
+
+### 好友系统
+
+| 路径 | 描述 |
+|------|------|
+| `/api/friend` | VRM 虚拟形象前端路由（由 Tauri 桌面应用调用），包含 TTS/STT、SSE、偏好设置等 |
+
+路由定义在单独模块中（非 router.ts 直接管理），对应文件: `api/friend.ts`
+
+### 文件与工作区
+
+| 路径 | 描述 |
+|------|------|
+| `/api/filesystem` | 文件系统访问操作 |
+| `/api/workspaces` | Git 工作区管理（会话工作区创建、差异查看等） |
+
+对应文件: `api/filesystem.ts`（filesystem 由专用路由函数处理）
+
+### 其他端点
+
+| 路径 | 描述 |
+|------|------|
+| `/api/scheduled-tasks` | 定时任务管理 |
+| `/api/search` | 搜索 |
+| `/api/agents` / `/api/tasks` | Agent 任务管理 |
+| `/api/status` | 服务器状态查询 |
+| `/api/teams` | 团队配置 |
+| `/api/providers` | Provider 提供商配置 |
+| `/api/adapters` | 适配器管理 |
+| `/api/computer-use` | Computer Use 功能控制 |
+| `/api/haha-oauth` | haha 自定义 OAuth 认证 |
+| `/api/haha-openai-oauth` | haha OpenAI OAuth 认证 |
+| `/api/h5-access` | H5 访问策略 |
+| `/api/activity-stats` | 活动统计 |
+| `/api/open-targets` | OpenTarget 管理 |
+| `/api/memory` | 记忆管理 |
+| `/api/desktop-ui` | 桌面 UI 偏好 |
+| `/api/cli-auth` | CLI 认证 |
+| `/api/cli-proxy` | CLI 代理 |
+
+## WebSocket
+
+**文件**: `ws/handler.ts` (约 68KB)
+
+WebSocket 连接处理器管理完整的连接生命周期：
+
+- **会话管理**: 创建、启动、停止、清理会话
+- **消息路由**: 将用户消息通过 CLI 子进程（stream-json 模式）处理
+- **命令处理**: 解析和处理斜杠命令（slash command）
+- **权限控制**: Computer Use 审批、运行时覆盖
+- **自动标题**: 追踪用户消息计数，自动生成对话标题
+- **会话预热**: 预启动空闲会话以加快响应
+- **断线重连**: 客户端断线后保持会话 5 分钟，支持重连
+- **消息转换**: CLI stdout 消息转换为 ServerMessage 并转发到 WebSocket
+
+消息协议定义在 `ws/events.ts`，包含 `ClientMessage` 和 `ServerMessage` 类型。
+
+## 服务层
+
+所有后端服务部署在 `src/server/services/` 目录下：
+
+### conversationService.ts
+CLI 子进程管理器。每个桌面会话拥有一个 CLI 子进程，子进程通过 SDK WebSocket Bridge 与桌面服务器通信。
+
+### sessionService.ts
+会话 CRUD 操作封装。读写 CLI 持久化在 `~/.claude/projects/{path}/{sessionId}.jsonl` 的会话数据，确保桌面应用与 CLI 数据完全互通。使用 SQLite 间接管理会话索引。
+
+### providerService.ts
+多 Provider 配置管理。基于预设（Preset）系��，支持 OpenCode 兼容配置。存储位置: `~/.claude/cc-haha/providers.json`，活跃 Provider 的环境变量写入 `~/.claude/cc-haha/settings.json`（与原始 Claude Code 的 `~/.claude/settings.json` 隔离）。
+
+### workspaceService.ts
+Git 工作区管理。支持差异查看、文件历史快照、会话工作区初始化等功能。
+
+### pluginService.ts
+插件管理系统。支持安装、卸载、更新、启用/禁用插件，管理 MCP 服务器集成与 LSP 服务器集成。
+
+### cronScheduler.ts
+Cron 任务调度引擎。定期检查所有定时任务，在匹配 cron 表达式时通过 CLI 子进程执行任务，执行历史持久化到 `~/.claude/scheduled_tasks_log.json`。
+
+### desktopCliLauncherService.ts
+桌面 CLI 启动器。负责安装和管理 `claude-haha` CLI 命令，维护 PATH 环境变量。
+
+### 其他服务
+
+- `diagnosticsService.ts` / `doctorService.ts`: 系统诊断
+- `searchService.ts`: 搜索服务
+- `titleService.ts`: 对话标题自动生成
+- `taskService.ts`: 任务管理
+- `teamService.ts` / `teamWatcher.ts`: 团队协作
+- `notificationService.ts`: 桌面通知
+- `networkSettings.ts`: 网络代理设置
+- `managedSettingsService.ts`: 托管设置
+- `h5AccessService.ts`: H5 访问策略
+- `computerUseApprovalService.ts`: Computer Use 审批
+- `mcpHostPreflight.ts`: MCP 预检
+- `attributionHeaderPolicy.ts`: 归因头策略
+- `agentService.ts`: Agent 服务
+- `adapterService.ts`: 适配器服务
+- `openaiOfficialProvider.ts`: OpenAI 官方提供商
+- `hahaOAuthService.ts` / `hahaOpenAIOAuthService.ts`: OAuth 认证
+- `repositoryLaunchService.ts`: 仓库启动（Git worktree 集成）
+- `filesystemAccessRoots.ts`: 文件系统访问根目录
+- `recoverableJsonFile.ts`: 可恢复 JSON 文件读写
+- `persistentStorageMigrations.ts`: 持久化存储迁移
+- `providerRuntimeEnv.ts`: Provider 运行时环境

docs/server/proxy-provider.md

@@ -0,0 +1,135 @@
+# Provider 代理与多模型支持
+
+## Proxy 协议转换
+
+**文件**: `src/server/proxy/handler.ts`
+
+Proxy Handler 是一个**协议转换反向代理**，接收 Anthropic Messages API 格式的请求，将其转换为 OpenAI Chat Completions 或 Responses API 格式，转发到上游第三方（3P）Provider，再将响应转换回 Anthropic 格式。
+
+### 转换路线
+
+```
+Anthropic Messages API  ←→  OpenAI Chat Completions API
+Anthropic Messages API  ←→  OpenAI Responses API
+```
+
+### 转换模块
+
+所有转换逻辑位于 `src/server/proxy/transform/` 和 `src/server/proxy/streaming/`：
+
+**请求转换（Anthropic → OpenAI）**:
+- `anthropicToOpenaiChat.ts` — 转换非流式 Chat 请求
+- `anthropicToOpenaiResponses.ts` — 转换非流式 Responses 请求
+
+**响应转换（OpenAI → Anthropic）**:
+- `openaiChatToAnthropic.ts` — Chat 响应转 Anthropic 格式
+- `openaiResponsesToAnthropic.ts` — Responses 响应转 Anthropic 格式
+
+**流式转换（OpenAI SSE stream → Anthropic SSE stream）**:
+- `openaiChatStreamToAnthropic.ts` — Chat 流式响应转换
+- `openaiResponsesStreamToAnthropic.ts` — Responses 流式响应转换
+- `openaiResponsesStreamToAnthropicResponse.ts` — Responses 流聚合
+
+**工具参数**:
+- `toolArguments.ts` — 工具参数的兼容处理
+
+**类型定义**:
+- `types.ts` — `AnthropicRequest` 等共享类型
+
+### 支持的 Provider
+
+Proxy 支持以下第三方提供商（3P Provider）：
+
+- **Groq** — 通过 OpenAI Chat API
+- **OpenRouter** — 通过 OpenAI Chat API
+- **OpenCode** — 通过 OpenAI Chat API，含 DeepSeek 推理兼容适配
+- **本地模型** — 任何兼容 OpenAI API 的本地推理端点
+- **其他 OpenAI 兼容 API** — 只要符合 OpenAI Chat/Responses 格式即可
+
+### DeepSeek 兼容模式
+
+当检测到上游 baseUrl 包含 `deepseek` 或 `opencode.ai` 时，自动启用 DeepSeek 推理兼容模式：
+- 启用手动往返推理内容（`roundTripReasoningContent`）
+- 传递 thinking toggle（`passThinkingToggle`）
+
+## Provider 配置系统
+
+**文件**: `src/server/services/providerService.ts`
+
+ProviderService 实现了一个基于预设（Preset）的 Provider 配置系统。
+
+### 数据存储
+
+- **索引文件**: `~/.claude/cc-haha/providers.json`（轻量级索引）
+- **环境变量**: 活跃 Provider 配置写入 `~/.claude/cc-haha/settings.json`
+- **隔离策略**: 与原始 Claude Code 的 `~/.claude/settings.json` 完全隔离
+
+### Preset 预设系统
+
+**文件**: `src/server/config/providerPresets.ts` + `providerPresets.json`
+
+每个预设包含：
+- `id` / `name`: 唯一标识和显示名
+- `baseUrl`: API 端点地址
+- `apiFormat`: 格式类型（`openai_chat` 或 `openai_responses`）
+- `defaultModels`: 模型映射（main / haiku / sonnet / opus）
+- `needsApiKey`: 是否需要 API Key
+- `authStrategy`: 认证策略
+- `defaultEnv`: 默认环境变量
+- `modelContextWindows`: 模型上下文窗口大小
+
+### OpenCode 兼容
+
+系统支持导入 OpenCode 的 Provider 配置，包括模型映射和 API 端点设置。
+
+### haha 认证
+
+自定义认证机制，支持两种 OAuth 流程：
+- `hahaOAuthService.ts` — 通用 haha OAuth
+- `hahaOpenAIOAuthService.ts` — OpenAI 专用 OAuth
+
+## Two-Tier 访问架构
+
+系统采用双层访问模式：
+
+### Tier 1: 原生 SDK 直连
+
+适用于 **Anthropic 用户**，直接使用官方 SDK：
+
+- **Anthropic API** — 直接使用 `@anthropic-ai/sdk`
+- **AWS Bedrock** — 通过 Bedrock SDK
+- **GCP Vertex AI** — 通过 Vertex AI SDK
+
+无需经过 Proxy 转换，性能最优。
+
+### Tier 2: Proxy 协议转换
+
+适用于 **第三方（3P）用户**，通过 Proxy 转换为 OpenAI 格式：
+
+- 请求路径: `/proxy/v1/messages`（使用活跃 Provider）
+- 请求路径: `/proxy/providers/:providerId/v1/messages`（指定特定 Provider）
+- 支持 OpenAI Chat Completions API
+- 支持 OpenAI Responses API
+- 支持流式（SSE）和非流式响应
+
+### OpenAI 官方提供商
+
+**文件**: `src/server/services/openaiOfficialProvider.ts`
+
+OpenAI 官方提供商作为特殊的内置 Provider，使用 OpenAI Codex API，通过 OAuth 认证获取令牌，支持完整的模型目录（`OPENAI_CODEX_MODEL_CATALOG`）。
+
+### Provider 运行时环境
+
+**文件**: `src/server/services/providerRuntimeEnv.ts`
+
+管理 Provider 的运行时环境变量：
+- 构建 Provider 认证环境
+- 规范化模型映射
+- 获取托管环境变量键
+- 解析预设认证策略
+
+### 归因头策略
+
+**文件**: `src/server/services/attributionHeaderPolicy.ts`
+
+自动为请求添加 Claude Code 归因头，确保第三方 API 调用中的来源标识。

docs/services/overview.md

@@ -0,0 +1,231 @@
+# 后端服务
+
+VersperClaw 提供一系列后台服务，涵盖 MCP 集成、上下文压缩、自主记忆整合、即时通讯集成、OAuth 认证、分析监控及工具执行引擎。
+
+---
+
+## MCP (Model Context Protocol)
+
+**目录**: `src/services/mcp/`
+
+MCP 客户端实现，基于 `@modelcontextprotocol/sdk`，支持多种传输层协议和 OAuth 认证。
+
+### 核心文件
+
+| 文件 | 描述 |
+|------|------|
+| `client.ts` | MCP 客户端 — 支持 Stdio、SSE、Streamable HTTP 三种传输协议；管理工具/资源/命令的发现与调用 |
+| `auth.ts` | MCP OAuth 认证 — 基于 Authorization Server Metadata 发现流程，支持 PKCE、令牌刷新、本地 HTTP 服务器捕获授权码 |
+| `config.ts` | MCP Server 配置解析 |
+| `types.ts` | MCP 相关类型定义 |
+| `InProcessTransport.ts` | 同进程传输层实现 |
+| `SdkControlTransport.ts` | SDK Control 传输层 |
+| `normalization.ts` | MCP 结果规范化 |
+| `envExpansion.ts` | 环境变量展开 |
+| `headersHelper.ts` | HTTP 头部辅助 |
+| `elicitationHandler.ts` | MCP Elicit 请求处理 |
+| `mcpStringUtils.ts` | MCP 字符串工具 |
+| `claudeai.ts` | Claude AI 集成 |
+| `officialRegistry.ts` | 官方 MCP 注册表 |
+| `useManageMCPConnections.ts` | MCP 连接管理 Hook |
+| `vscodeSdkMcp.ts` | VSCode SDK 兼容层 |
+| `channelAllowlist.ts` / `channelPermissions.ts` / `channelNotification.ts` | 频道权限与通知 |
+| `MCPConnectionManager.tsx` | MCP 连接管理器 UI 组件 |
+| `xaa.ts` / `xaaIdpLogin.ts` | XAA 身份提供方登录 |
+| `oauthPort.ts` | OAuth 回调端口管理 |
+
+### 支持的传输协议
+
+1. **StdioClientTransport** — 子进程标准输入/输出
+2. **SSEClientTransport** — Server-Sent Events
+3. **StreamableHTTPClientTransport** — 可流式 HTTP
+
+### 发现能力
+
+工具（Tools）、资源（Resources）、提示（Prompts）的自动发现与调用。
+
+---
+
+## 上下文压缩
+
+**目录**: `src/services/compact/`
+
+上下文压缩引擎，在对话历史超出上下文窗口时自动触发压缩，将冗长的历史会话压缩为精炼的摘要。
+
+### 核心文件
+
+| 文件 | 大小 | 描述 |
+|------|------|------|
+| `compact.ts` | 61 KB | **核心压缩引擎** — 将对话历史压缩为摘要，包含完整的压缩策略与边界消息管理 |
+| `autoCompact.ts` | — | **自动压缩** — 当上下文窗口使用量超过阈值时自动触发压缩，管理 maxTokens、重试逻辑、token 估算 |
+| `microCompact.ts` | — | **微压缩** — 细粒度工具结果压缩，仅压缩特定工具（FileRead、FileEdit、FileWrite、Glob、Grep、WebFetch、WebSearch 等）的输出 |
+| `sessionMemoryCompact.ts` | — | **会话记忆压缩** — 实验性功能，将会话记忆压缩整合到会话恢复流程中 |
+| `cachedMicrocompact.ts` | — | 缓存式微压缩，提升重复压缩效率 |
+| `cachedMCConfig.ts` | — | 缓存微压缩配置 |
+| `snipCompact.ts` / `snipProjection.ts` | — | 截断式压缩与投影 |
+| `grouping.ts` | — | 消息分组策略 |
+| `reactiveCompact.ts` | — | 响应式压缩 |
+| `timeBasedMCConfig.ts` | — | 基于时间的微压缩配置 |
+| `postCompactCleanup.ts` | — | 压缩后清理 |
+| `prompt.ts` | — | 压缩提示词模板 |
+| `apiMicrocompact.ts` | — | API 微压缩接口 |
+| `compactWarningHook.ts` / `compactWarningState.ts` | — | 压缩警告 UI 状态管理 |
+
+### 压缩流程
+
+1. `autoCompact` 监控上下文窗口使用率
+2. 当超过阈值时，调用 `compactConversation()`（在 `compact.ts` 中）
+3. 压缩引擎提取历史消息，调用 AI 生成摘要
+4. 摘要替换原始历史消息，压缩边界消息标记范围
+5. `sessionMemoryCompact` 可选地将会话记忆额外压缩
+6. `microCompact` 对工具结果进行细粒度压缩以进一步节省 token
+7. `postCompactCleanup` 执行压缩后清理
+
+---
+
+## Auto Dream (自主记忆整合)
+
+**目录**: `src/services/autoDream/`
+
+Auto Dream 是一个后台记忆整合系统，在对话间期自动运行，将学习到的信息整理为持久化的记忆文件。
+
+### 核心文件
+
+| 文件 | 描述 |
+|------|------|
+| `autoDream.ts` | 主模块 — 后台记忆中整合，使用 `runForkedAgent` 执行 `/dream` 提示词。使用三道门控（Gate）按成本递增顺序判断是否执行：时间（距上次整合 >= minHours）、会话数（新会话 >= minSessions）、锁（无其他进程正在整合） |
+| `config.ts` | 配置 — 是否启用 Auto Dream |
+| `consolidationLock.ts` | 整合锁 — 基于 PID 和 mtime 的文件锁，防止多个进程同时整合。锁文件位于记忆目录，mtime 作为 `lastConsolidatedAt` 时间戳 |
+| `consolidationPrompt.ts` | 整合提示词 — 构建 `/dream` 的系统提示词，指导 AI 反思记忆文件并整理为持久化知识 |
+
+### 门控顺序
+
+1. **时间门控**: 距上次整合 >= 最小小时数（一个 stat 调用，最便宜）
+2. **会话门控**: 新产生的会话记录数 >= 最小会话数
+3. **锁门控**: 无其他进程正在进行整合（最昂贵）
+
+### 整合内容
+
+- 回顾记忆目录中的 `.md` 文件
+- 分析近期会话记录（transcript）
+- 合成新的记忆，整理现有知识
+- 确保记忆文件对后续会话具有良好可读性
+
+---
+
+## 飞书集成
+
+**目录**: `src/services/feishu/`
+
+飞书机器人集成，基于 `@larksuite/channel` SDK。
+
+### 核心文件
+
+| 文件 | 描述 |
+|------|------|
+| `FeishuService.ts` | 飞书机器人服务 — 创建 LarkChannel、注册应用、处理消息事件、管理聊天模式、引用回复、保活机制 |
+| `feishuConfig.ts` | 配置管理 — 读写 `~/.claude/adapters.json` 中的飞书配置段；管理已配对用户、授权用户白名单、Group 模式设置 |
+| `vendor/` | 自包含的第三方实现模块（核心日志、机器人 pending 队列、保活、引用回复、访问策略） |
+
+### 功能
+
+- 应用注册与事件处理
+- DM 私聊白名单
+- Group 群聊模式
+- 引用上下文回复
+- 管理员权限控制
+- 自动保活（Keepalive）
+
+---
+
+## Telegram 集成
+
+**文件**: `src/services/telegram/TelegramService.ts`
+
+Telegram 机器人服务，基于 Telegram Bot API 实现消息收发、指令处理、行内键盘等功能。
+
+### 功能
+
+- `getMe` — 获取机器人信息
+- `sendMessage` — 发送消息（支持 Markdown / HTML 格式）
+- `editMessageText` — 编辑已发送消息
+- `answerCallbackQuery` — 响应回调查询
+- `sendChatAction` — 发送聊天动作指示器
+- `setMyCommands` — 设置机器人命令列表
+- `getUpdates` — 轮询获取更新
+
+配置管理: `telegramConfig.ts` / `telegramTypes.ts`
+
+---
+
+## OAuth
+
+**目录**: `src/services/oauth/`
+
+通用 OAuth 2.0 认证服务，支持授权码流程（Authorization Code Flow with PKCE）。
+
+### 核心文件
+
+| 文件 | 描述 |
+|------|------|
+| `index.ts` | `OAuthService` — 主类，管理完整 OAuth 流程：生成 code_verifier、启动本地 HTTP 服务器监听回调、令牌交换 |
+| `auth-code-listener.ts` | 授权码监听器 — 启动本地 HTTP 服务器捕获回调中的授权码 |
+| `client.ts` | OAuth 客户端 HTTP 请求封装 |
+| `crypto.ts` | PKCE 加密工具 — code_verifier / code_challenge 生成 |
+| `getOauthProfile.ts` | 获取 OAuth 用户档案 |
+| `types.ts` | OAuth 类型定义（令牌、速率限制、订阅类型等） |
+
+### 流程
+
+1. 生成 PKCE code_verifier 和 code_challenge
+2. 构建授权 URL 并打开浏览器
+3. 本地 HTTP 服务器监听回调 / 用户手动粘贴授权码
+4. 用授权码换取令牌（access_token + refresh_token）
+5. 支持令牌刷新和持久化
+
+---
+
+## 分析 (Analytics)
+
+**目录**: `src/services/analytics/`
+
+### 核心组件
+
+| 文件 | 描述 |
+|------|------|
+| `index.ts` | 分析日志入口 — 标准化事件日志接口 |
+| `growthbook.ts` | GrowthBook 特性标记集成 — 远程配置和 A/B 测试功能开关 |
+| `config.ts` | Analytics 配置 |
+| `metadata.ts` | 分析元数据提取 — 工具名称脱敏、MCP 工具详情、文件扩展名 |
+| `datadog.ts` | Datadog 集成 |
+| `firstPartyEventLogger.ts` / `firstPartyEventLoggingExporter.ts` | 第一方事件日志与导出 |
+| `sink.ts` / `sinkKillswitch.ts` | 事件接收器与终止开关 |
+
+### 功能
+
+- 工具使用统计与耗时追踪
+- 模型调用分析
+- GrowthBook 远程特性配置
+- Datadog APM 集成
+
+---
+
+## 工具执行引擎
+
+**目录**: `src/services/tools/`
+
+### 核心文件
+
+| 文件 | 大小 | 描述 |
+|------|------|------|
+| `toolExecution.ts` | 60 KB | **工具执行引擎** — 核心工具运行逻辑，管理工具调用生命周期、权限检查、进度报告、结果处理 |
+| `toolHooks.ts` | — | **工具钩子系统** — 执行 Pre-Tool 和 Post-Tool 挂钩，支持基于规则和基于审批的权限决策 |
+| `StreamingToolExecutor.ts` | — | **流式工具执行器** — 管理并发工具执行队列，支持工具状态追踪（queued / executing / completed / yielded），支持进度消息即时推流 |
+| `toolOrchestration.ts` | — | **工具编排** — 高级工具调度与编排逻辑 |
+
+### 工具执行流程
+
+1. **Pre-Tool Hooks**: 权限检查、规则匹配、审批流程
+2. **工具调用**: 查找工具定义 -> 执行 -> 收集结果
+3. **Post-Tool Hooks**: 结果处理、日志记录、统计更新
+4. **Streaming**: 支持并发工具执行，进度实时推送

docs/tools/overview.md

@@ -0,0 +1,254 @@
+# AI 工具系统
+
+## Tool 抽象
+
+所有 AI 可调用的工具（Tool）都通过 **`buildTool()`** 框架构建。每个工具定义以下核心属性：
+
+```
+Tool<Input, Output, Progress>
+```
+
+### 核心字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | `string` | 工具名称，用于 API 调用标识 |
+| `aliases` | `string[]` | 可选的别名，用于向后兼容 |
+| `searchHint` | `string` | 3-10 词的关键词提示，辅助 ToolSearch 匹配 |
+| `inputSchema` | `Zod Schema` | 输入参数的 Zod 校验 schema |
+| `inputJSONSchema` | `object` | 可选的 JSON Schema 直接输出（MCP 工具使用） |
+| `outputSchema` | `Zod Schema` | 输出参数的 Zod schema |
+| `call()` | 函数 | 工具的核心执行逻辑 |
+| `description()` | 函数 | 工具的描述字符串 |
+| `prompt()` | 函数 | 返回工具在系统提示词中的内容 |
+| `isEnabled()` | 函数 | 工具是否启用（默认 true） |
+| `isConcurrencySafe()` | 函数 | 是否支持并发执行（默认 false） |
+| `isReadOnly()` | 函数 | 是否为只读操作（默认 false） |
+| `isDestructive()` | 函数 | 是否为破坏性操作（删除、覆盖、发送；默认 false） |
+| `shouldDefer` | `boolean` | 是否延迟加载（配合 ToolSearch 使用） |
+| `alwaysLoad` | `boolean` | 是否始终加载（即使在 ToolSearch 模式下） |
+| `maxResultSizeChars` | `number` | 结果超过此大小时持久化到磁盘 |
+| `strict` | `boolean` | 是否启用工具调用严格模式 |
+| `checkPermissions()` | 函数 | 检查用户权限 |
+| `validateInput()` | 函数 | 输入值校验逻辑 |
+| `renderToolUseMessage()` | 函数 | 渲染工具调用 UI |
+| `renderToolResultMessage()` | 函数 | 渲染工具结果 UI |
+| `renderToolUseProgressMessage()` | 函数 | 渲染执行进度 UI |
+| `userFacingName()` | 函数 | 面向用户显示的名称 |
+| `getActivityDescription()` | 函数 | 进度提示文本 |
+| `mapToolResultToToolResultBlockParam()` | 函数 | 将结果映射为 API 格式 |
+
+### buildTool() 默认值
+
+`buildTool()` 提供以下安全默认值：
+
+| 方法 | 默认值 |
+|------|--------|
+| `isEnabled()` | `true` |
+| `isConcurrencySafe()` | `false`（默认不支持并发） |
+| `isReadOnly()` | `false`（默认可能写入） |
+| `isDestructive()` | `false` |
+| `checkPermissions()` | `{ behavior: 'allow', updatedInput: input }`（放行） |
+| `toAutoClassifierInput()` | `''`（跳过分类器） |
+| `userFacingName()` | `name` |
+
+相关文件：`/home/yuki/Code/Agent/VersperClaw/src/Tool.ts`
+
+---
+
+## 注册机制
+
+### getTools() 流程
+
+`src/tools.ts` 的 **`getTools()`** 函数是工具注册的核心入口：
+
+```
+getTools(permissionContext) → Tool[]
+```
+
+执行流程：
+
+1. **`CLAUDE_CODE_SIMPLE` 模式**：仅返回 BashTool、FileReadTool、FileEditTool（极简模式）
+2. **`getAllBaseTools()`**：收集所有内置工具，按 feature flag 和条件编译
+3. **`filterToolsByDenyRules()`**：检查 deny rules，过滤被禁止的工具
+4. **`REPL 模式过滤`**：当 REPL 启用时，隐藏原始工具（`REPL_ONLY_TOOLS`）
+5. **`isEnabled()` 过滤**：逐个检查工具是否启用
+
+### assembleToolPool()
+
+`assembleToolPool()` 是内置工具与 MCP 工具的汇聚函数：
+
+1. 调用 `getTools()` 获取内置工具
+2. 通过 `filterToolsByDenyRules()` 过滤 MCP 工具
+3. 按名称去重（内置工具优先）
+4. 按名称排序（保持 prompt cache 稳定性）
+
+### getMergedTools()
+
+单纯合并内置工具与 MCP 工具（不去重、不排序），用于工具搜索阈值计算等场景。
+
+相关文件：`/home/yuki/Code/Agent/VersperClaw/src/tools.ts`
+
+---
+
+## 执行引擎
+
+### runToolUse()
+
+`src/services/tools/toolExecution.ts` 的 **`runToolUse()`** 是工具调用的入口点，接收 `ToolUseBlock` 并返回异步生成器。
+
+执行生命周期：
+
+```
+runToolUse(toolUse, assistantMessage, canUseTool, toolUseContext)
+  → AsyncGenerator<MessageUpdateLazy>
+```
+
+### 完整生命周期
+
+```
+LLM 请求工具调用
+    │
+    ├─ 1. 查找工具 ── findToolByName()
+    │      ├─ 找到 → 继续
+    │      └─ 未找到 → 尝试别名匹配 → 返回"工具不存在"错误
+    │
+    ├─ 2. 输入校验 ── inputSchema.safeParse(input)
+    │      ├─ 成功 → 继续
+    │      └─ 失败 → 返回 Zod 校验错误（含 ToolSearch schema 未发送提示）
+    │
+    ├─ 3. 自定义校验 ── validateInput()
+    │      ├─ 通过 → 继续
+    │      └─ 拒绝 → 返回自定义错误消息
+    │
+    ├─ 4. PreToolUse Hooks ── runPreToolUseHooks()
+    │      ├─ 产生消息（进度、附件）
+    │      ├─ 产生 hookPermissionResult（提前决定权限）
+    │      ├─ 产生 hookUpdatedInput（修改输入）
+    │      └─ 产生 stop（钩子要求停止执行）
+    │
+    ├─ 5. 权限检查 ── resolveHookPermissionDecision()
+    │      ├─ permission mode 决定交互方式
+    │      ├─ 权限缓存 / alwaysAllow / alwaysDeny / alwaysAsk
+    │      ├─ 用户交互弹窗（default 模式）
+    │      ├─ 自动分类器（auto 模式）
+    │      └─ 结果: allow / reject / ask
+    │
+    ├─ 6. 工具执行 ── tool.call()
+    │      ├─ 执行核心逻辑
+    │      ├─ 发送进度通知 (onProgress)
+    │      └─ 返回 ToolResult
+    │
+    ├─ 7. 结果处理 ── mapToolResultToToolResultBlockParam()
+    │      ├─ 大结果持久化到磁盘
+    │      └─ 生成预览
+    │
+    ├─ 8. PostToolUse Hooks ── runPostToolUseHooks()
+    │      ├─ MCP 工具: 可修改 toolOutput
+    │      └─ 非 MCP 工具: 添加附件消息
+    │
+    └─ 9. 返回结果 ── 生成 MessageUpdateLazy
+           ├─ 成功: tool_result 消息
+           ├─ 错误: tool_use_error 消息
+           └─ 中断: tool_result_stop 消息
+```
+
+---
+
+## 权限系统
+
+权限系统基于 `permission mode` 决定工具调用是否需要用户确认：
+
+### Permission Mode
+
+| 模式 | 说明 |
+|------|------|
+| `default` | 默认模式，敏感操作需用户确认 |
+| `acceptEdits` | 自动接受文件编辑类操作 |
+| `bypassPermissions` | 绕过所有权限检查 |
+| `plan` | 规划模式，限制工具使用 |
+| `auto` | 自动模式，分类器决定权限 |
+
+### 权限规则覆盖
+
+根据 `ToolPermissionContext`，系统支持：
+
+- **alwaysAllowRules**: 始终允许的规则（按工具名称、文件路径模式、shell 命令前缀）
+- **alwaysDenyRules**: 始终拒绝的规则
+- **alwaysAskRules**: 始终询问的规则
+- **denyRules**: 在工具注册阶段过滤掉的工具
+
+### 权限决定来源（OTel `source` 词汇）
+
+| 来源 | 说明 |
+|------|------|
+| `user_temporary` | 用户会话级临时允许 |
+| `user_permanent` | 用户永久允许（存盘） |
+| `user_reject` | 用户拒绝 |
+| `hook` | 钩子系统决定 |
+| `config` | 配置/预设规则决定 |
+
+---
+
+## 进度通知系统
+
+工具执行过程中通过 `onProgress` 回调发送进度通知，不同类型的工具有不同的进度类型：
+
+| 进度类型 | 说明 | 对应工具 |
+|----------|------|----------|
+| `BashProgress` | Shell 命令执行进度 | BashTool |
+| `AgentProgress` | 子代理执行进度 | AgentTool |
+| `MCPProgress` | MCP 工具调用进度 | MCP 工具 |
+| `SkillToolProgress` | 技能执行进度 | SkillTool |
+| `TaskOutputProgress` | 后台任务输出进度 | TaskOutputTool |
+| `WebSearchProgress` | 网络搜索进度 | WebSearchTool |
+| `REPLToolProgress` | REPL 工具进度 | REPLTool |
+| `HookProgress` | 钩子执行进度 | Hooks |
+
+相关文件：
+- `/home/yuki/Code/Agent/VersperClaw/src/services/tools/toolExecution.ts` — 执行引擎
+- `/home/yuki/Code/Agent/VersperClaw/src/types/tools.ts` — 进度类型定义
+- `/home/yuki/Code/Agent/VersperClaw/src/hooks/toolPermission/` — 权限钩子
+- `/home/yuki/Code/Agent/VersperClaw/src/utils/permissions/` — 权限工具函数
+
+---
+
+## 关键工具详述
+
+### AgentTool
+
+执行子代理任务的核心工具。
+
+- **输入参数**: `description`, `prompt`, `subagent_type`, `model`, `run_in_background`, `name`, `team_name`, `mode`, `isolation`, `cwd`
+- **行为**: 启动一个独立的子代理会话，可指定代理类型、模型、隔离方式
+- **权限**: 可能需要用户确认
+- **进度**: `AgentProgress` 类型
+
+### BashTool
+
+在本地 Shell 中执行命令。
+
+- **输入参数**: `command`, `timeout`, `description`, `run_in_background`, `dangerouslyDisableSandbox`
+- **行为**: 执行任意 shell 命令，支持超时控制、后台运行、沙箱模式
+- **权限**: 按命令前缀匹配权限规则
+- **进度**: 超过 2 秒显示 `BashProgress`
+- **自动分类**: search/read/list 命令会折叠显示
+
+### Read / Edit / Write
+
+三大文件操作工具：
+
+- **FileReadTool**: 读取文件内容，支持 PDF、图片、Jupyter Notebook
+- **FileEditTool**: 精确替换文件中的字符串，支持 diff 显示和 git diff 跟踪
+- **FileWriteTool**: 创建或覆盖写入文件内容，包含文件变更追踪
+
+### WebSearch / WebFetch
+
+- **WebSearchTool**: 使用 Tavily API 或本地 SearXNG 进行网络搜索
+- **WebFetchTool**: 抓取 URL 内容并应用 prompt 处理（提取、总结）
+
+相关文件：
+- `/home/yuki/Code/Agent/VersperClaw/src/Tool.ts` — Tool 类型与 buildTool 框架
+- `/home/yuki/Code/Agent/VersperClaw/src/tools.ts` — 工具注册与过滤
+- `/home/yuki/Code/Agent/VersperClaw/src/services/tools/toolExecution.ts` — 执行引擎
+- `/home/yuki/Code/Agent/VersperClaw/src/services/tools/toolHooks.ts` — 工具钩子

docs/tools/tool-reference.md

@@ -0,0 +1,186 @@
+# 工具参考大全
+
+> 完整收录 VersperClaw 中所有 AI 可调用的工具（约 60+），按功能分类。
+
+---
+
+## 核心文件操作
+
+| 工具名称 | 分类 | 用途描述 | 关键参数 |
+|----------|------|----------|----------|
+| **Read** (FileReadTool) | 核心 | 读取文件内容，支持 PDF、图片、Jupyter Notebook。自动推断文件编码和语言 | `file_path` (必填), `offset`, `limit`, `pages` (PDF), `stop_sequence` |
+| **Edit** (FileEditTool) | 核心 | 对现有文件执行精确字符串替换。支持 diff 显示、git diff 跟踪、行尾风格检测 | `file_path` (必填), `old_string` (必填), `new_string` (必填), `replace_all`, `is_undo` |
+| **Write** (FileWriteTool) | 核心 | 创建新文件或覆盖写文件。不支持替换编辑（用途与 Edit 互补） | `file_path` (必填), `content` (必填) |
+| **Glob** (GlobTool) | 核心 | 使用 glob 模式快速搜索文件名。支持 `.gitignore` 排除规则 | `pattern` (必填), `path` (可选) |
+| **Grep** (GrepTool) | 核心 | 使用正则表达式搜索文件内容。基于 ripgrep，支持多种输出模式 | `pattern` (必填), `path` (可选), `glob`, `output_mode`, `-B`, `-A`, `-C`, `-i`, `type`, `head_limit`, `multiline` |
+| **NotebookEdit** (NotebookEditTool) | 核心 | 编辑 Jupyter Notebook (.ipynb) 文件的单元格。支持 replace / insert / delete 模式 | `notebook_path` (必填), `cell_id`, `new_source`, `cell_type`, `edit_mode` |
+
+---
+
+## 命令执行
+
+| 工具名称 | 分类 | 用途描述 | 关键参数 |
+|----------|------|----------|----------|
+| **Bash** (BashTool) | 核心 | 执行 Shell 命令。支持超时控制、后台执行、沙箱模式。自动检测 search/read 类命令以折叠显示 | `command` (必填), `timeout` (可选), `description` (可选), `run_in_background` (可选), `dangerouslyDisableSandbox` (可选) |
+| **Agent** (AgentTool) | 核心 | 启动独立的子代理执行子任务。支持指定代理类型、模型、隔离方式、团队协作 | `description` (必填), `prompt` (必填), `subagent_type`, `model`, `run_in_background`, `name`, `team_name`, `mode`, `isolation` (worktree/remote), `cwd` |
+| **PowerShell** (PowerShellTool) | 命令 | Windows PowerShell 命令执行。仅在 Windows 平台可用 | `command` (必填), `timeout`, `description`, `run_in_background` |
+| **TaskStop** (TaskStopTool) | 命令 | 停止正在运行的后台任务。继承自废弃的 KillShell 工具 | `task_id` (可选), `shell_id` (废弃) |
+| **TaskOutput** (TaskOutputTool) | 命令 | 获取后台任务的执行输出。支持阻塞等待和超时控制 | `task_id` (必填), `block` (默认 true), `timeout` (默认 30000ms) |
+
+---
+
+## 搜索
+
+| 工具名称 | 分类 | 用途描述 | 关键参数 |
+|----------|------|----------|----------|
+| **WebSearch** (WebSearchTool) | 搜索 | 执行网络搜索。支持 Tavily API 和本地 SearXNG 两种后端（优先本地 SearXNG） | `query` (必填, 最少 2 字符) |
+| **WebFetch** (WebFetchTool) | 搜索 | 抓取指定 URL 的内容，并对内容执行 prompt 处理（提取、总结等） | `url` (必填), `prompt` (必填) |
+| **ToolSearch** (ToolSearchTool) | 搜索 | 搜索延迟加载的工具。当 ToolSearch 启用时，部分工具的 schema 不会随初始提示发送，需通过此工具查询后再调用 | `query` (必填, 支持 "select:name" 精确选择), `max_results` (默认 5) |
+
+---
+
+## MCP (Model Context Protocol)
+
+| 工具名称 | 分类 | 用途描述 | 关键参数 |
+|----------|------|----------|----------|
+| **ListMcpResources** (ListMcpResourcesTool) | MCP | 列出已连接 MCP 服务器提供的可用资源 | `server` (可选, 过滤) |
+| **ReadMcpResource** (ReadMcpResourceTool) | MCP | 读取 MCP 资源内容。支持文本和二进制内容（二进制会保存到磁盘） | `server` (必填), `uri` (必填) |
+| **MCPTool** (动态) | MCP | 由 MCP 服务器动态注册的工具。名称格式 `mcp__server__tool`。数量和功能取决于已连接的 MCP 服务器 | 由 MCP 服务器定义 |
+| **McpAuth** (MCP) | MCP | MCP 服务器授权管理。当工具调用返回 McpAuthError 时触发重授权流程 | 由 MCP 服务器定义 |
+
+---
+
+## 任务管理 (Todo V2)
+
+| 工具名称 | 分类 | 用途描述 | 关键参数 |
+|----------|------|----------|----------|
+| **TaskCreate** (TaskCreateTool) | 任务 | 创建新的任务项。支持设置负责人（owner）、依赖关系、元数据 | `subject` (必填), `description` (必填), `activeForm`, `metadata` |
+| **TaskGet** (TaskGetTool) | 任务 | 通过 ID 获取单个任务的详细信息 | `taskId` (必填) |
+| **TaskUpdate** (TaskUpdateTool) | 任务 | 更新任务的状态、描述、负责人、依赖关系、元数据。支持标记为 "deleted" 删除 | `taskId` (必填), `subject`, `description`, `status`, `addBlocks`, `addBlockedBy`, `owner`, `metadata` |
+| **TaskList** (TaskListTool) | 任务 | 列出所有任务的概览（ID、标题、状态、负责人、阻塞关系） | 无参数 |
+| **TodoWrite** (TodoWriteTool) | 任务 | (遗留) 会话级任务清单管理。V1 版本，当 Todo V2 未启用时生效 | `todos` (必填) |
+
+---
+
+## 团队与多代理
+
+| 工具名称 | 分类 | 用途描述 | 关键参数 |
+|----------|------|----------|----------|
+| **TeamCreate** (TeamCreateTool) | 团队 | 创建新团队并设置团队领导。支持指定代理类型，自动生成团队文件 | `team_name` (必填), `description`, `agent_type` |
+| **TeamDelete** (TeamDeleteTool) | 团队 | 删除已存在的团队 | `team_id` (必填) |
+| **SendMessage** (SendMessageTool) | 团队 | 向指定队友发送消息。支持普通文本和结构化消息（关闭请求/响应、计划审批等） | `to` (必填), `message` (必填), `type`, `request_id` |
+| **ListPeers** (ListPeersTool) | 团队 | 列出本地 UDS 对等节点（统一数据空间连接的对等体） | 无参数 |
+
+---
+
+## 规划与工作树
+
+| 工具名称 | 分类 | 用途描述 | 关键参数 |
+|----------|------|----------|----------|
+| **EnterPlanMode** (EnterPlanModeTool) | 规划 | 进入规划模式。在执行复杂任务前，可用于探索和设计方案 | 无参数 |
+| **ExitPlanMode** (ExitPlanModeV2Tool) | 规划 | 退出规划模式。提交最终计划并恢复为之前的权限模式 | `plan` (必填), `plan_approval`, `output`, `mode` |
+| **EnterWorktree** (EnterWorktreeTool) | 规划 | 创建隔离的 git worktree 并将会话切换到其中。用于安全地进行实验性修改 | `name` (可选) |
+| **ExitWorktree** (ExitWorktreeTool) | 规划 | 退出 git worktree 并返回原工作目录。支持 keep（保留）或 remove（删除） | `action` (必填, keep/remove), `discard_changes` |
+
+---
+
+## 技能
+
+| 工具名称 | 分类 | 用途描述 | 关键参数 |
+|----------|------|----------|----------|
+| **Skill** (SkillTool) | 技能 | 执行 Markdown 定义的技能。技能可以是打包的、用户自定义的、插件提供的或 MCP 提供的 | 参数取决于具体技能 |
+| **DiscoverSkills** (DiscoverSkillsTool) | 技能 | 发现新的可用技能。扫描技能目录并返回当前可用的技能列表 | 无参数 |
+
+---
+
+## 目标系统 (Goal)
+
+| 工具名称 | 分类 | 用途描述 | 关键参数 |
+|----------|------|----------|----------|
+| **GoalCreate** (GoalCreateTool) | 目标 | 创建新的会话目标。当当前无活跃目标时生效 | `objective` (必填) |
+| **GoalGet** (GoalGetTool) | 目标 | 查看当前活跃目标的状态、经过时间、续用次数 | 无参数 |
+| **GoalUpdate** (GoalUpdateTool) | 目标 | 声明目标完成或受阻。需提供原因说明 | `goal_id` (必填), `status` (必填, complete/blocked), `reason` (必填) |
+
+---
+
+## Friend 虚拟宠物
+
+| 工具名称 | 分类 | 用途描述 | 关键参数 |
+|----------|------|----------|----------|
+| **FriendEmotion** (FriendEmotionTool) | Friend | 控制 VRM 虚拟形象的表情和情绪状态。设置情绪类型、强度，调整自身心情指数 | `emotion` (必填, 如 happy/sad/angry), `intensity` (0-1, 默认 1), `mood_delta` (-3 到 +3) |
+| **FriendScreenObserve** (FriendScreenObserveTool) | Friend | 捕获当前桌面屏幕截图，供 LLM "观察" 用户桌面环境。返回图片路径 | 无参数 |
+
+---
+
+## 特殊工具
+
+| 工具名称 | 分类 | 用途描述 | 关键参数 |
+|----------|------|----------|----------|
+| **AskUserQuestion** (AskUserQuestionTool) | 特殊 | 向用户提出需要即时回答的问题 | 取决于实现 |
+| **Config** (ConfigTool) | 特殊 | 读取或修改 Claude Code 配置设置（ant 内部版本） | `setting` (必填), `value` (可选) |
+| **Sleep** (SleepTool) | 特殊 | 让代理休眠一段时间。用于延迟执行或等待条件成熟 | 取决于实现 |
+| **CronCreate** (CronCreateTool) | 特殊 | 创建定时触发任务（cron 调度） | 取决于实现 |
+| **CronDelete** (CronDeleteTool) | 特殊 | 删除已存在的 cron 任务 | 取决于实现 |
+| **CronList** (CronListTool) | 特殊 | 列出所有已注册的 cron 任务 | 取决于实现 |
+| **RemoteTrigger** (RemoteTriggerTool) | 特殊 | 远程触发任务执行 | 取决于实现 |
+| **Monitor** (MonitorTool) | 特殊 | 监控资源或任务状态 | 取决于实现 |
+| **Brief** (BriefTool) | 特殊 | 生成简报输出。在 KAIROS/BRIEF 模式下可用 | 取决于实现 |
+| **Snip** (SnipTool) | 特殊 | 强制截断历史上下文。HISTORY_SNIP feature 控制 | 取决于实现 |
+| **SubscribePR** (SubscribePRTool) | 特殊 | 订阅 GitHub PR 的通知 | 取决于实现 |
+| **PushNotification** (PushNotificationTool) | 特殊 | 发送推送通知 | 取决于实现 |
+| **SendUserFile** (SendUserFileTool) | 特殊 | 向用户发送文件 | 取决于实现 |
+
+---
+
+## Workflow
+
+| 工具名称 | 分类 | 用途描述 | 关键参数 |
+|----------|------|----------|----------|
+| **WorkflowTool** (WorkflowTool) | Workflow | 执行多步骤工作流脚本。工作流由 YAML/JSON 定义，支持顺序执行、条件分支、变量传递 | ��决于工作流定义 |
+
+---
+
+## Ant 内部工具
+
+以下工具仅在 `USER_TYPE=ant` 的内部构建中可用，公开构建中被过滤：
+
+| 工具名称 | 分类 | 用途描述 |
+|----------|------|----------|
+| **REPLTool** | Ant 内部 | REPL 模式的 VM 执行器。在 REPL 模式下包装 Bash/Read/Edit 等工具 |
+| **TungstenTool** | Ant 内部 | Tungsten 内部工具 |
+| **SuggestBackgroundPRTool** | Ant 内部 | 后台 PR 建议工具 |
+| **CtxInspectTool** | Ant 内部 | 上下文折叠检查（CONTEXT_COLLAPSE） |
+| **TerminalCaptureTool** | Ant 内部 | 终端面板捕获（TERMINAL_PANEL） |
+| **OverflowTestTool** | Ant 内部 | 溢出测试工具 |
+| **VerifyPlanExecutionTool** | Ant 内部 | 计划执行验证 |
+| **TestingPermissionTool** | Ant 内部 | 测试权限工具（仅 NODE_ENV=test） |
+| **WebBrowserTool** | Ant 内部 | 网页浏览器工具 |
+
+---
+
+## feature-flag 条件编译对照
+
+以下工具根据 feature flag 条件编译，在公开构建中通过 bun build DCE 消除：
+
+| Feature Flag | 包含的工具 |
+|--------------|-----------|
+| `PROACTIVE` / `KAIROS` | SleepTool |
+| `AGENT_TRIGGERS` | CronCreateTool, CronDeleteTool, CronListTool |
+| `AGENT_TRIGGERS_REMOTE` | RemoteTriggerTool |
+| `MONITOR_TOOL` | MonitorTool |
+| `KAIROS` | SendUserFileTool, PushNotificationTool |
+| `KAIROS_PUSH_NOTIFICATION` | PushNotificationTool |
+| `KAIROS_GITHUB_WEBHOOKS` | SubscribePRTool |
+| `WORKFLOW_SCRIPTS` | WorkflowTool |
+| `COORDINATOR_MODE` | 协调模式相关工具 |
+| `HISTORY_SNIP` | SnipTool |
+| `UDS_INBOX` | ListPeersTool |
+| `ENABLE_LSP_TOOL` | LSPTool |
+| `WEB_BROWSER_TOOL` | WebBrowserTool |
+| `OVERFLOW_TEST_TOOL` | OverflowTestTool |
+| `CONTEXT_COLLAPSE` | CtxInspectTool |
+| `TERMINAL_PANEL` | TerminalCaptureTool |
+
+---
+
+> 注: 本参考基于 `/home/yuki/Code/Agent/VersperClaw/src/tools.ts` 的 `getAllBaseTools()` 函数。MCP 工具的完整列表取决于用户配置的 MCP 服务器，未在此表中逐一列出。

docs/voice/overview.md

@@ -0,0 +1,279 @@
+# 语音系统
+
+## 概述
+
+VersperClaw 的语音系统支持**语音转文字（STT, Speech-to-Text）** 和 **文字转语音（TTS, Text-to-Speech）** 功能。语音录制使用底层音频捕获库（cpal），含有 SoX 和 arecord 回退方案。语音识别支持多个提供商，包括云端 API 和本地模型；语音合成同样支持多个引擎，涵盖 Edge TTS 和 DashScope TTS。
+
+> 注意：部分功能受构建特性门控（feature gate）限制，仅在 ant-internal 构建中可用。
+
+---
+
+## 语音录制（Voice Recording）
+
+核心文件：`src/services/voice.ts`
+
+录音模块使用分层策略：
+
+| 层级 | 方案 | 适用平台 |
+|------|------|----------|
+| 原生 | `audio-capture-napi`（cpal） | macOS, Linux, Windows |
+| 回退 1 | SoX `rec` | Linux (有 SoX) |
+| 回退 2 | `arecord` (ALSA) | Linux (有 ALSA) |
+
+关键特征：
+
+- **懒加载原生模块**：`loadAudioNapi()` 在首次按键时异步加载 `audio-capture-napi`，避免启动时阻塞（dlopen 可能耗时 1-8 秒）。
+- **静音检测**：使用 SoX 或 arecord 时启用静音检测（阈值 3%，持续时间 2 秒），自动结束录音。
+- **录音常量**：采样率 16000 Hz，单声道，16-bit PCM。
+- **依赖检查**：`checkVoiceDependencies()` 探测可用性，显示每个方案的可用状态。
+
+---
+
+## STT 提供商（Speech-to-Text）
+
+### 抽象接口
+
+文件：`src/services/voice/providers.ts`
+
+```typescript
+interface TranscriptionProvider {
+  name: string
+  transcribe(wavPath: string, language?: string): Promise<TranscriptionResult>
+}
+```
+
+所有 STT 提供商实现此接口，`LocalWhisperSTT` 和 `DoubaoSTTProvider` 是内置实现。
+
+---
+
+### 1. Groq Whisper（云端）
+
+文件：`src/services/voice/groqSTT.ts`
+
+通过官方 `groq-sdk` npm 包调用 Groq LPU API，使用 Whisper 模型。
+
+**模型回退**：
+1. 优先使用 `whisper-large-v3`
+2. 遇到 429（限速）或 5xx（服务端错误）时自动回退到 `whisper-large-v3-turbo`
+3. 其他错误（4xx）直接抛出，不重试
+
+**API 密钥解析**（优先级从高到低）：
+1. 显式传入的 `apiKey` 参数
+2. `friend.json` 中的 `groqApiKey` 配置
+3. 环境变量 `GROQ_API_KEY`
+4. `~/.claude/settings.json` 中的 `env.groqApiKey`
+
+**核心流程**：
+- `connectGroqStream()` 返回 `VoiceStreamConnection` 接口
+- 接收 PCM 音频块并缓冲
+- `finalize()` 时将 PCM 转换为 WAV（`pcmToWav()`，16-bit 单声道，16000 Hz）
+- 通过 `File` API 上传 WAV 到 Groq
+
+---
+
+### 2. Local Whisper（本地模型）
+
+文件：`src/services/voice/whisperSTT.ts`
+
+基于 Python `openai-whisper` 的本地部署方案。
+
+**架构**：
+- 启动一个长期运行的 Python 子进程（`whisper_server.py`）
+- 通过 stdin/stdout 的 JSON 行协议通信
+- 支持预加载模型（`preloadWhisperModel()`）
+
+**通信协议**：
+- `{"type":"load","model":"small"}` —— 加载模型
+- `{"type":"transcribe","wav":"/path/to/audio.wav","language":"en"}` —— 转写
+- 服务端以 `{"type":"result","text":"...","language":"..."}` 或 `{"type":"error","message":"..."}` 响应
+
+**进程管理**：
+- 进程崩溃后自动重启
+- 30 秒超时保护
+- 临时文件自动清理
+
+**可用性检查**：使用 Python `importlib.util.find_spec("whisper")` 探测 whisper 模块是否可导入，避免加载 PyTorch 的耗时。
+
+---
+
+### 3. Anthropic Voice Stream（WebSocket）
+
+文件：`src/services/voiceStreamSTT.ts`
+
+通过 Anthropic 的 voice_stream WebSocket 端点传输语音，仅在 ant-internal 构建中可用（由 `feature('VOICE_MODE')` 门控）。
+
+**WebSocket 协议**：
+- 端点：`wss://api.anthropic.com/api/ws/speech_to_text/voice_stream`
+- 认证：OAuth Bearer Token（与 Claude Code 共享凭证）
+- 消息类型：
+  - `KeepAlive` —— 每 8 秒发送保持连接
+  - `CloseStream` —— 结束流
+  - 服务端推送 `TranscriptText`、`TranscriptEndpoint`、`TranscriptError`
+
+**连接生命周期**：
+1. `connectVoiceStream()` 建立 WebSocket 连接
+2. `send(audioChunk)` 发送二进制音频帧
+3. `finalize()` 发送 `CloseStream`，等待服务端返回 `TranscriptEndpoint`
+4. `FinalizeSource` 枚举标识解析路径：`post_closestream_endpoint`、`no_data_timeout`、`safety_timeout`、`ws_close`、`ws_already_closed`
+
+**Deepgram Nova 3 门控**：通过 GrowthBook 特性标记 `deepgram_nova_3_gate` 控制是否使用 Deepgram Nova 3 模型。
+
+**Voice Keyterms**：通过查询参数传递关键词列表，提高领域术语的识别准确率。
+
+---
+
+### 4. Doubao（豆包 STT）
+
+文件：`src/services/voice/doubaoSTT.ts`
+
+此文件是一个自动生成的存根（stub），对应 ant-internal 的 `feature()` 门控模块。外部构建中所有代码路径在 DCE（死代码消除）后不会实际执行。
+
+存根使用 JavaScript `Proxy` 将任何属性访问、函数调用、构造操作映射到无操作（noop）处理器。导出 `connectDoubaoStream`、`normalizeLanguageForSTT` 等函数作为占位符。
+
+`DoubaoSTTProvider`（在 `providers.ts` 中）封装了此存根的调用逻辑，通过动态导入（`import('./doubaoSTT.js')`）在运行时解析。
+
+---
+
+## TTS 提供商（Text-to-Speech）
+
+### 抽象接口
+
+文件：`src/services/voice/providers.ts`
+
+```typescript
+interface TTSProvider {
+  name: string
+  synthesize(text: string): Promise<SynthesisResult>
+}
+```
+
+`EdgeTTSProvider` 和 `CommandTTSProvider` 是内置实现。
+
+---
+
+### 1. Edge TTS（微软神经网络语音）
+
+文件：`src/services/voice/providers.ts`（类 `EdgeTTSProvider`）
+
+**实现路径一（Provider 接口）**：
+- 直接调用 `edge-tts` 命令行工具
+- 使用 Node.js `child_process.spawn` 执行子进程
+- 通过 `--voice`、`--text`、`--write-media` 参数控制输出
+- 默认语音：`en-US-AriaNeural`
+
+**实现路径二（独立函数）**：
+文件：`src/services/voice/edgeTTS.ts`（`speakWithEdgeTTS()`）
+- 调用 `scripts/speak.py` Python 脚本
+- 依赖 `.venv/bin/python` 或系统 Python
+- 返回标准化的 `TTSResult` 接口
+
+**实现路径三（Friend 模块）**：
+文件：`src/friend/tts.ts`（`edgeTts()`）
+- 使用 `node-edge-tts` npm 包（Node.js 原生实现，无需 Python）
+- 默认语音：`zh-CN-XiaoxiaoNeural`（中文语音）
+- 输出为 MP3 文件
+
+**播放功能**（`src/services/voice/edgeTTS.ts` `playAudioFile()`）：
+| 平台 | 播放器 | 说明 |
+|------|--------|------|
+| macOS | `afplay` | 原生 |
+| Linux | `ffplay` | 先 `pkill` 已有进程，再启动新进程 |
+| Windows | `start` | 系统默认播放器 |
+
+---
+
+### 2. Qwen DashScope TTS（通义千问语音合成）
+
+文件：`src/friend/tts.ts`（`qwenTts()`）
+
+调用阿里云 DashScope API 进行语音合成。
+
+**API 信息**：
+- 国内端点：`https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`
+- 国际端点：`https://dashscope-intl.aliyuncs.com/...`
+- 默认模型：`qwen3-tts-flash`
+- 默认语音：`Cherry`
+- 认证：Bearer Token（`apiKey`）
+
+**参数**：
+- `voice`：语音角色（如 Cherry, Polly 等）
+- `model`：模型版本
+- `language`：语言（`zh` 或 `en`），决定端点选择和 `language_type`
+
+**流程**：
+1. POST 请求获取合成音频的 URL
+2. 从 URL 下载音频数据
+3. 保存为 WAV 临时文件
+4. 支持 30 秒超时保护
+
+**音频文件注册**：`registerAudioFile()` 将文件路径注册到内存映射，5 分钟后自动过期，用于跨模块引用。
+
+---
+
+### 3. Command TTS（命令模板回退）
+
+文件：`src/services/voice/providers.ts`（类 `CommandTTSProvider`）
+
+通用 shell 命令 TTS，支持模板占位符：
+- `{input}` / `{input_path}` —— 输入文本文件路径
+- `{output_path}` —— 输出音频文件路径
+
+适用于调用任意外部 TTS 命令行工具。
+
+---
+
+## Voice Stream 协议
+
+文件：`src/services/voiceStreamSTT.ts`
+
+Voice Stream 是 Anthropic 的 WebSocket 协议，用于实时语音识别。
+
+### 消息类型
+
+| 方向 | 类型 | 说明 |
+|------|------|------|
+| 客户端 → 服务端 | `KeepAlive` | 心跳，每 8 秒 |
+| 客户端 → 服务端 | `CloseStream` | 结束音频流 |
+| 客户端 → 服务端 | 二进制帧 | PCM 音频数据 |
+| 服务端 → 客户端 | `TranscriptText` | 转写文本片段 |
+| 服务端 → 客户端 | `TranscriptEndpoint` | 转写结束标记 |
+| 服务端 → 客户端 | `TranscriptError` | 错误信息 |
+
+### FinalizeSource 枚举
+
+`finalize()` 方法的解析路径：
+
+| 值 | 说明 |
+|----|------|
+| `post_closestream_endpoint` | 正常流程：发送 CloseStream 后收到 TranscriptEndpoint |
+| `no_data_timeout` | 发送 CloseStream 后 1.5 秒无响应 |
+| `safety_timeout` | WebSocket 挂起超过 5 秒 |
+| `ws_close` | WebSocket 连接关闭 |
+| `ws_already_closed` | 已关闭的连接被重复调用 |
+
+### Keyterms（关键词）
+
+通过 WebSocket 查询参数 `keyterms` 传递关键词列表，格式为逗号分隔的 URL 编码值。关键词可提高模型对特定术语的识别准确率。
+
+---
+
+## Voice Mode（语音模式）
+
+语音模式是 Push-to-Talk（按住说话）的实现：
+
+1. **开始录音**：用户按下语音快捷键
+2. **音频采集**：底层 cpal 或回退方案开始采集 16kHz 单声道 PCM 音频
+3. **音频传输**：音频块通过 Voice Stream WebSocket 实时发送
+4. **释放停止**：用户松开快捷键，发送 CloseStream
+5. **等待转写**：接收服务端返回的 TranscriptText 和 TranscriptEndpoint
+6. **提交文本**：转写文本进入对话输入流
+
+当使用本地 Whisper 时，流程类似但使用子进程通信而非 WebSocket。
+
+---
+
+## 提供商注册与选择
+
+文件：`src/services/voice/providers.ts`
+
+系统通过 `TranscriptionProvider` 和 `TTSProvider` 接口实现多提供商支持。每个提供商有自己的名称（`name` 属性）和实现逻辑。选择策略在调用方（如 `useVoice` hook）中决定，根据可用性和用户配置选择合适的提供商。