chore: docs v1.2 — add debug system, feishu integration; update swarm, tavily, provider auth

New docs:
- docs/cli/debug-system.md — /debug v2.0 DEBUG PROBE workflow, session debug logging
- docs/services/feishu.md — Feishu/Lark bot architecture, access control, TTS

Updated docs:
- docs/coordinator/multi-agent.md — Agent Teams (Swarm topology), Fork Subagent
- docs/tools/overview.md — WebSearch dual-backend (Tavily vs SearXNG)
- docs/architecture/provider-auth.md — OpenCode Zen free models, NVIDIA sidecar
- docs/friend/voice-vad.md — noise suppression, FriendService stricter threshold
- docs/services/overview.md — condensed feishu section to point to new doc
- docs/README.md — index updated with all new entries

Co-Authored-By: Claude Big Pickle <noreply@anthropic.com>

docs/README.md

@@ -20,7 +20,8 @@
 |------|------|
 | [CLI 命令系统](cli/overview.md) | 命令注册、Slash 命令大全 (~75+)、Skill/工作流系统 |
 | [构建系统与功能标记](cli/build-system.md) | 676 行 | Bun 构建管道、48 个 feature flag、死代码消除、命令可用性门控 |
-| [AI 工具系统](tools/overview.md) | buildTool 框架、执行流程、权限系统、关键工具详解 |
+| [调试系统](cli/debug-system.md) | `/debug` v2.0 DEBUG PROBE 工作流、会话调试日志 |
+| [AI 工具系统](tools/overview.md) | buildTool 框架、执行流程、权限系统、关键工具详解（含 Tavily/SearXNG） |
 | [工具参考大全](tools/tool-reference.md) | 所有 ~60+ AI 工具的完整参考表 |
 
 ### Friend VRM 伴侣
@@ -53,13 +54,14 @@
 | 文档 | 说明 |
 |------|------|
 | [服务总览](services/overview.md) | MCP、上下文压缩、Auto Dream、飞书/Telegram |
+| [飞书集成](services/feishu.md) | 飞书/Lark 机器人架构、访问控制、语音回复、配置 |
 | [上下文压缩深度解析](services/compact-deep-dive.md) | 906 行 | 5 层压缩管线、Budget Reduction、Snip、Microcompact、Context Collapse、Auto-compact |
 
 ### 协调与自动化
 | 文档 | 说明 |
 |------|------|
 | [目标与自动模式](coordinator/goals-auto-mode.md) | Goal 系统、Auto Mode、查询循环、Task 系统 |
-| [多代理协调](coordinator/multi-agent.md) | Coordinator 模式、Worker 派发、并行策略 |
+| [多代理协调](coordinator/multi-agent.md) | Coordinator 模式、Worker 派发、Agent Teams Swarm、Fork Subagent |
 
 ### 远程桥接
 | 文档 | 说明 |

docs/architecture/provider-auth.md

@@ -313,20 +313,23 @@ function shouldUseDeepSeekReasoningCompat(baseUrl: string): boolean {
 - **端点**: `{baseUrl}/v1/chat/completions` (默认 `https://integrate.api.nvidia.com/v1`)
 - **Model 列表**: 从 `/v1/models` 动态拉取，缓存于 `cachedNvidiaModels` 模块变量
 - **默认 Model**: `nvidia/llama-3.1-nemotron-70b-instruct` (可通过 `NVIDIA_MODEL` 环境变量覆盖)
+- **网络架构**: 通过 Sidecar 代理转发（`/api/proxy/nvidia`），适用于需要特殊头或 CORS 处理的 Provider。与之对比，OpenCode/OpenRouter 使用直接 Fetch Override 模式。
 
 ### 4.2 OpenCode Zen
 
 **文件**: `src/services/api/opencodeClient.ts`
 
 - **认证**: 支持 API Key 和匿名免费使用
-- **免费模式**: 当 `apiKey` 为 `undefined` 或 `'public'` 时，注入 billing 特征码 (x-anthropic-billing-header)
+- **免费模式**: 当 `apiKey` 为 `undefined` 或 `'public'` 时，注入 billing 特征码 (`x-anthropic-billing-header: cc_version=2.1.0-dev...`)，标记请求来源用于服务端路由
 - **端点**: `https://opencode.ai/zen/v1/chat/completions`
 - **Model 发现**: 
-  - 从 `https://models.dev/api.json` 动态获取模型元数据 (云端成本策略)
+  - 从 `https://models.dev/api.json` 动态获取模型元数据（云端成本策略）
   - 从 `https://api.github.com/repos/anomalyco/opencode/releases/latest` 获取版本信息
   - 缓存于 `cachedModels` 模块变量
+  - 支持免费模型列表过滤（life-free models）
 - **动态 UA**: 根据版本和运行时自动构建 `User-Agent`
 - **推理内容**: 支持 `reasoning_content` 到 `thinking` block 的转换
+- **网络架构**: 直连模式（Direct Fetch Override），无需 Sidecar 代理
 
 ### 4.3 OpenAI / Codex Official
 

docs/cli/debug-system.md

@@ -0,0 +1,142 @@
+# 调试系统
+
+## 概述
+
+VersperClaw 提供两层调试能力：
+
+1. **会话级调试日志** — 基于 `logForDebugging()` 的持久化日志系统，用于内部诊断
+2. **`/debug` 交互式调试** — 基于 DEBUG PROBE 的主动式调试工作流（v2.0）
+
+---
+
+## 1. 会话调试日志
+
+### 基础用法
+
+通过 CLI 标志启用：
+
+```bash
+claude --debug              # 启用调试日志
+claude --debug=api,hooks    # 按分类过滤
+claude -d                   # 简写
+claude --debug-file=/tmp/debug.log  # 自定义日志路径
+claude --debug-to-stderr    # 输出到 stderr
+```
+
+环境变量：
+
+| 变量 | 说明 |
+|------|------|
+| `DEBUG` / `DEBUG_SDK` | 启用调试模式 |
+| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 最低级别：`verbose`, `debug`, `info`, `warn`, `error` |
+| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 自定义日志目录 |
+
+### 日志位置
+
+默认路径：`~/.claude/debug/<sessionId>.txt`
+
+`latest` 符号链接总是指向最新会话的日志文件。
+
+### 核心文件
+
+| 文件 | 职责 |
+|------|------|
+| `src/utils/debug.ts` | `logForDebugging()`, `isDebugMode()`, `enableDebugLogging()`, `getDebugLogPath()` |
+| `src/utils/debugFilter.ts` | 分类过滤：`parseDebugFilter()`, `shouldShowDebugMessage()` |
+| `src/utils/bufferedWriter.ts` | 缓冲写入器，批量写入日志 |
+
+`logForDebugging()` 在代码库中 250+ 个文件中使用。
+
+---
+
+## 2. `/debug` 交互式调试（v2.0）
+
+### 架构
+
+```
+用户输入 /debug <bug描述>
+        │
+        ▼
+debug.ts (bundled skill)
+        │
+        ▼
+8 步 CHECKPOINT 工作流注入模型上下文
+        │
+        ▼
+模型自动执行：分析 → 插探针 → 复现 → 分析日志 → 修复 → 验证 → 清理
+        │
+        ▼
+DebugSessionTool — 管理 .versperclaw-debug/ 目录
+```
+
+### 与 v1 的区别
+
+| 方面 | v1（旧） | v2.0（当前） |
+|------|---------|-------------|
+| 方式 | 被动读取调试日志 | 主动插入探针 |
+| 数据源 | `~/.claude/debug/*.txt` | `.versperclaw-debug/debug.log` |
+| 模型角色 | 分析已有日志 | 插桩 → 复现 → 分析 → 修复 |
+| 工作流 | 无结构化步骤 | 8 步 CHECKPOINT |
+
+### 8 步 CHECKPOINT 工作流
+
+| 步骤 | 操作 |
+|------|------|
+| **Step 0: Triage** | 确认 bug 报告完整（预期/实际/复现步骤/一致性/错误） |
+| **Step 1: Plan Probes** | 阅读代码，形成 2-3 个假设，输出探针插入计划表 |
+| **Step 2: Init Session** | 调用 `DebugSession({ action: "init" })` 创建 `.versperclaw-debug/` |
+| **Step 3: Insert Probes** | 用 Edit 插入 `DEBUG PROBE [N]` / `DEBUG PROBE END [N]` 代码块 |
+| **Step 4: Reproduce & Log** | 调用 `DebugSession begin_run`，运行复现命令，通过 `read_log` 收集 |
+| **Step 5: Analyze** | 引用日志行，定位根因 |
+| **Step 6: Fix & Verify** | 修复后调用 `begin_verify`，重跑，对比日志 |
+| **Step 7: Cleanup** | 删除所有探针，Grep 确认清理，调用 `DebugSession cleanup` |
+| **Final** | 总结根因、证据、修复、验证、清理 |
+
+### DEBUG PROBE 格式
+
+```typescript
+// DEBUG PROBE [1] <label>
+try {
+  require('fs').appendFileSync('.versperclaw-debug/debug.log',
+    `[${new Date().toISOString()}] [js] file.ts:42 | label | value=${JSON.stringify(value)}\n`)
+} catch {}
+// DEBUG PROBE END [1]
+```
+
+规则：
+- 探针必须是**只观察不修改**的
+- 每个探针有唯一编号 `[N]` 和匹配的 START/END 标记
+- 每种语言的探针模板不同（JS/TS、Python、Go、Rust）
+- 最多 3 轮探针迭代
+- 必须在最终回复前完全清理
+
+### DebugSession 工具
+
+工具名：`DebugSession`
+
+可用动作：
+
+| 动作 | 说明 |
+|------|------|
+| `init` | 创建 `.versperclaw-debug/` 目录、`debug.log`、`state` 文件 |
+| `begin_run` | 追加 `RUN #N` 分隔符，递增运行计数器 |
+| `begin_verify` | 追加 `VERIFY` 分隔符 |
+| `read_log` | 读取 `debug.log` 尾部内容 |
+| `cleanup` | 删除 `.versperclaw-debug/` 目录 |
+
+### 目录结构
+
+```
+.versperclaw-debug/
+  debug.log       -- 探针写入 + RUN/VERIFY 分隔符
+  state           -- JSON: { "runCount": 3 }
+```
+
+### 核心文件
+
+| 文件 | 职责 |
+|------|------|
+| `src/skills/bundled/debug.ts` | `/debug` skill 定义，8 步工作流提示词，探针模板 |
+| `src/tools/DebugSessionTool.ts` | DebugSession 工具实现 |
+| `src/utils/debug.ts` | 通用调试日志基础设施 |
+| `src/commands/debug-tool-call/index.js` | 遗留桩命令（`isEnabled: false`） |

docs/coordinator/multi-agent.md

@@ -203,3 +203,141 @@ AgentTool({ prompt: "Based on your findings, implement the fix" }) // 错误：
 ### 停止 Worker
 
 使用 `TaskStopTool` 停止方向错误的 Worker。已停止的 Worker 可通过 `SendMessageTool` 继续。
+
+---
+
+## Agent Teams（Swarm 拓扑）
+
+### 概述
+
+Agent Teams（Swarm 模式）是 VersperClaw 的多 Agent 拓扑模型，通过 `feature('AGENT_SWARMS')` 编译期标记门控。与 Coordinator/Worker 模式不同，Teams 采用**文件系统邮箱通信**，每个 Agent 在独立进程中运行（tmux split-pane / in-process）。
+
+### 激活方式
+
+```bash
+export CLAUDE_CODE_AGENT_SWARMS=1
+```
+
+### 核心架构
+
+```
+Team Lead (AgentTool team_name="my-team" name="lead")
+    │
+    ├── AgentTool(name="researcher", team_name="my-team") → tmux pane / in-process
+    │     └── 邮箱: ~/.claude/teams/my-team/mailbox/researcher/
+    │
+    ├── AgentTool(name="coder", team_name="my-team") → tmux pane / in-process
+    │     └── 邮箱: ~/.claude/teams/my-team/mailbox/coder/
+    │
+    └── AgentTool(name="reviewer", team_name="my-team") → tmux pane / in-process
+          └── 邮箱: ~/.claude/teams/my-team/mailbox/reviewer/
+```
+
+### 与 Coordinator/Worker 的区别
+
+| 维度 | Coordinator/Worker | Agent Teams (Swarm) |
+|------|-------------------|---------------------|
+| 通信 | `<task-notification>` XML 消息 | 文件系统邮箱（mailbox） |
+| 进程 | 同进程 | 独立 OS 进程（tmux / in-process） |
+| 生命周期 | 单次任务 | 持久化团队 |
+| 隔离度 | 共享上下文 | AsyncLocalStorage（in-process）或完全隔离 |
+| 工具白名单 | 统一限制 | 可配置 agent_type → 自定义工具集 |
+| 嵌套 | Coordinator 可 spawn worker | **禁止**团队成员 spawn 子代（仅 team lead 可） |
+
+### 团队创建流程
+
+1. **创建团队**: `TeamCreateTool({ name: "my-team" })` → 生成 `~/.claude/teams/my-team/config.json`
+2. **设置 Leader**: 当前会话自动成为 team-lead
+3. **派发成员**: `AgentTool({ name: "researcher", team_name: "my-team", prompt: "..." })`
+4. **后台抉择**:
+   - In-process（启用时）→ 同一进程 AsyncLocalStorage 隔离
+   - tmux split-pane（默认）→ 新 tmux 窗格
+   - tmux separate-window → 新 tmux 窗口
+   - iTerm2 native → macOS 原生分屏
+5. **通信**: 成员写入 `mailbox/{agent-name}/`，lead 轮询读取
+
+### 邮箱通信格式
+
+```json
+{
+  "from": "researcher",
+  "text": "研究发现...",
+  "timestamp": 1712345678000
+}
+```
+
+### 团队成员配置
+
+自定义 Agent 定义（`~/.claude/agents/`）：
+
+```json
+{
+  "name": "researcher",
+  "tools": ["BashTool", "ReadTool", "GrepTool", "GlobTool"],
+  "model": "claude-sonnet-4-20250514"
+}
+```
+
+### 关键文件
+
+| 文件 | 职责 |
+|------|------|
+| `src/tools/AgentTool/AgentTool.tsx` | 统一调度入口（Line 262-316 为团队路径） |
+| `src/tools/shared/spawnMultiAgent.ts` | 三种 spawn 后端实现（1105 行） |
+| `src/tools/TeamCreateTool/TeamCreateTool.ts` | 团队创建 + 任务列表重置 |
+| `src/tools/TeamDeleteTool/TeamDeleteTool.ts` | 团队清理 + 活跃成员验证 |
+| `src/utils/swarm/teamHelpers.ts` | TeamFile 类型、文件锁、清理 |
+| `src/utils/swarm/inProcessRunner.ts` | 同进程 teammate 生命周期（1553 行） |
+| `src/utils/swarm/teammateInit.ts` | Stop hook、路径白名单 |
+| `src/utils/swarm/constants.ts` | `TEAM_LEAD_NAME`, `SWARM_SESSION_NAME` |
+
+### Spawn 后端对比
+
+| 后端 | 隔离 | 优点 | 缺点 |
+|------|------|------|------|
+| tmux split-pane | 完整进程隔离 | 可视化管理，可独立 kill | 需要 tmux |
+| tmux separate-window | 完整进程隔离 | 传统方式 | UI 不够紧凑 |
+| iTerm2 native | 完整进程隔离 | macOS 原生集成 | 仅 macOS |
+| In-process | AsyncLocalStorage | 无需终端，快速 | 共享进程，有限隔离 |
+
+### 清理机制
+
+- `cleanupSessionTeams()` 在 SIGINT/SIGTERM 时自动执行
+- 终止所有团队成员窗格
+- 清理团队目录和任务目录
+- 文件锁防止并发竞争
+
+### Forbidden 规则
+
+Agent 工具过滤（`filterToolsForAgent()`）：
+
+1. MCP 工具（`mcp__*`）始终保留
+2. `ALL_AGENT_DISALLOWED_TOOLS` 从所有 Agent 移除
+3. `CUSTOM_AGENT_DISALLOWED_TOOLS` 额外从非内置 Agent 移除
+4. `ASYNC_AGENT_ALLOWED_TOOLS` 异步 Agent 仅允许白名单工具
+
+---
+
+## Fork Subagent（实验性）
+
+### 概述
+
+通过 `feature('FORK_SUBAGENT')` 门控，提供另一种 Agent 拓扑：子 Agent **继承父会话的全部上下文**。
+
+### 关键特性
+
+- **上下文继承**: 子 Agent 从父会话的完整历史开始
+- **字节级缓存优化**: 所有 fork 共享相同 API 前缀（字节一致），提高 prompt 缓存命中
+- **权限冒泡**: `permissionMode: 'bubble'` — 权限提示冒泡到父终端
+- **强制异步**: 所有 fork spawn 必须异步执行
+
+### 适用场景
+
+- 需要子 Agent 拥有完整对话上下文时
+- 希望复用父会话的 prompt 缓存
+
+### 核心文件
+
+| 文件 | 职责 |
+|------|------|
+| `src/tools/AgentTool/forkSubagent.ts` | `buildForkedMessages()` 构建字节相同前缀 |

docs/friend/voice-vad.md

@@ -223,9 +223,9 @@ this.opts = {
 };
 ```
 
-### 3.4 RMS 能量预过滤
+### 3.4 RMS 能量预过滤（噪声抑制）
 
-在运行 ONNX 推理之前，先计算帧的 RMS 能量：
+RMS 预过滤是 VAD 的**第一道噪声防线**。在运行 ONNX 推理之前，先计算帧的 RMS 能量：
 
 ```typescript
 let sumSq = 0;
@@ -244,9 +244,11 @@ if (rms < this.opts.rmsThreshold) {
 
 作用：
 - 节省 CPU 资源（大量帧无语音信号）
-- 过滤机械噪声/麦克风碰撞/环境静音
+- 过滤机械噪声/麦克风碰撞/环境静音（噪声抑制）
 - 降低误触发率
 
+注：FriendService 中使用更严格的阈值 `0.01`（-40dBFS）而非 SileroVAD 的默认 `0.004`，以减少非语音噪音造成的误触发。
+
 ### 3.5 状态机详解
 
 ```

docs/services/feishu.md

@@ -0,0 +1,243 @@
+# 飞书（Feishu/Lark）机器人集成
+
+## 概述
+
+VersperClaw 内置飞书（国内版）和 Lark（国际版）机器人集成，允许用户在即时通讯中与 AI CLI 进行对话。机器人通过 `@larksuite/channel` SDK 建立长连接 WebSocket，支持私聊、群聊、语音回复、引用回复等功能。
+
+---
+
+## 架构
+
+```
+Feishu WebSocket (LarkChannel)
+        │
+        ▼
+FeishuService (singleton)
+  ├── PendingQueue (600ms 去抖)
+  ├── Access Control (DM/Group 策略)
+  ├── Slash Command Router (/stop, /reset, /status, /help)
+  ├── Quoted Context Fetcher
+  └── TTS Engine (Edge TTS / VoxCPM)
+        │
+        ▼
+messageQueueManager.enqueue()
+  └── origin: { kind: 'channel', server: 'feishu' }
+        │
+        ▼
+useFeishuBridge (React hook)
+  ├── 收集 AI 回复
+  └── sendMarkdown() / sendVoice() 返回飞书
+```
+
+---
+
+## 连接方式
+
+采用 **WebSocket 长连接**（非 Webhook），基于 `@larksuite/channel` 包：
+
+- **国内版**: `https://open.feishu.cn`
+- **国际版 (Lark)**: `https://open.larksuite.com`
+- 通过配置中的 `tenant` 字段选择端点（`'lark'` 使用国际版）
+
+### Channel 配置
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `respectProxyEnv` | `true` | 遵循 `HTTP_PROXY`/`HTTPS_PROXY` |
+| `pingTimeout` | `3` | SDK ping 看门狗 |
+| `handshakeTimeoutMs` | `8000` | 连接握手超时 |
+| `httpTimeoutMs` | `30000` | API 调用超时 |
+| `policy.dmMode` | `'open'` | SDK 级 DM 策略（上层另有自定义） |
+| `safety.chatQueue.enabled` | `false` | 禁用 SDK 内部队列，使用自定义 PendingQueue |
+
+### 生命周期事件
+
+- `message` — 收到消息
+- `error` — 连接错误
+- `reconnecting` — 重连中
+- `reconnected` — 重连成功
+
+---
+
+## 消息处理流水线
+
+```
+Feishu WS → NormalizedMessage → PendingQueue → Access Control → Slash Router → Inbound Listeners → enqueue()
+```
+
+### PendingQueue（去抖队列）
+
+文件：`vendor/bot/pending-queue.ts`
+
+- 每个 `chatId` 独立队列
+- 消息静默 600ms 后批量提交
+- 支持 `block(scope)` / `unblock(scope)` — AI 回复期间阻塞新消息
+- 以 `/` 开头的命令跳过队列立即处理
+
+### Access Control（访问控制）
+
+文件：`FeishuService.ts`
+
+**DM 权限**（`canUseDm`）：
+- 机器人拥有者（Owner）— 始终允许
+- 管理员（`admins[]`）— 始终允许
+- `allowedUsers[]` 为空（默认）— 所有人可 DM
+- `allowedUsers[]` 有值 — 仅白名单用户可 DM
+
+**群聊权限**（`canUseGroup`）：
+- 拥有者和管理员始终允许
+- 仅 `allowedChats[]` 中的群被允许
+
+**@ 提及策略**：
+- `requireMentionInGroup` 默认为 `true` — 群聊需要 @bot
+- 可配置为 `false` 响应所有群消息
+
+### 内置命令
+
+| 命令 | 说明 |
+|------|------|
+| `/stop` | 停止当前处理 |
+| `/reset` | 重置会话 |
+| `/status` | 显示机器人状态、App ID、Owner、策略 |
+| `/help` | 显示帮助信息 |
+
+未知命令自动传递给 AI 处理。
+
+---
+
+## 引用回复
+
+当用户回复某条历史消息时，`fetchQuotedContext()`（`vendor/bot/quote.ts`）会通过 `channel.fetchRawMessage()` 获取原文，包装为 XML 注入 AI 上下文：
+
+```xml
+<quoted_message id="..." sender_id="..." sender_name="..." type="text">
+  Original message content here
+</quoted_message>
+```
+
+支持类型：纯文本、合并转发、交互式卡片（CardKit v1 和 v2）。
+
+---
+
+## 消息格式输出
+
+### 文本
+
+`sendText(chatId, text)` — 发送纯文本。
+
+### Markdown（主要方式）
+
+`sendMarkdown(chatId, markdown)` — 发送前通过 `feishuMarkdown.ts` 优化：
+
+- **标题降级**: H1→H4, H2-H6→H5（飞书卡片 H1-H3 渲染有 bug）
+- **Schema 2.0 间距**: 在连续标题、表格前后、代码块周围插入 `<br>`
+- **图片过滤**: 非 `img_*` 图片移除（防 CardKit 200570 错误）
+- **表格限制**: 超过 3 个表格降级为代码块（防 230099/11310 错误）
+
+### 语音
+
+`sendVoice(chatId, text)` — 启用 TTS 时自动调用。
+
+---
+
+## 语音（TTS）系统
+
+飞书语音为**单向输出**（AI 回复 → 语音），用户始终通过文字输入。
+
+### Edge TTS（默认）
+
+- 使用 `edge-tts` CLI 工具
+- 默认语音：`zh-CN-XiaoxiaoNeural`
+- 输出转码为 OGG (Opus) 后发送
+
+### VoxCPM（自定义语音克隆）
+
+- 使用 `.venv/bin/voxcpm` CLI
+- 需要 `ttsReferenceAudio`（WAV/MP3 参考音频）
+- 长文本按 ~150 字在句边界分块
+- 每块独立合成，WAV→OGG 转码，ffmpeg concat 合并
+
+### TTS 配置
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `ttsEnabled` | boolean | 主开关 |
+| `ttsProvider` | `'edge' \| 'voxcpm'` | 引擎选择 |
+| `ttsVoice` | string | Edge TTS 语音名称 |
+| `ttsReferenceAudio` | string | VoxCPM 参考音频路径 |
+
+---
+
+## QR 码注册向导
+
+支持一键创建飞书应用，无需手动在开发者��台操作：
+
+1. 调用 `@larksuite/channel` 的 `registerApp({ source: 'versperclaw' })`
+2. 返回 QR 码 URL，终端用 ASCII 渲染
+3. 用户使用飞书手机端扫码授权
+4. `client_id` 和 `client_secret` 自动保存到配置
+5. 机器人立即启动
+
+---
+
+## 配置
+
+文件路径: `~/.claude/adapters.json`（`feishu` 键下）
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `appId` | string | ✅ | 飞书开放平台 App ID |
+| `appSecret` | string | ✅ | 飞书开放平台 App Secret |
+| `tenant` | `'feishu' \| 'lark'` | ❌ | API 端点选择 |
+| `encryptKey` | string | ❌ | 事件加密 |
+| `verificationToken` | string | ❌ | 事件 URL 验证 |
+| `allowedUsers` | string[] | ❌ | DM 白名单（空=开放） |
+| `admins` | string[] | ❌ | 管理员 open_id |
+| `allowedChats` | string[] | ❌ | 群聊白名单 |
+| `requireMentionInGroup` | boolean | ❌ | 默认 true |
+| `ttsEnabled` | boolean | ❌ | 语音回复开关 |
+| `ttsProvider` | `'edge' \| 'voxcpm'` | ❌ | TTS 引擎 |
+| `ttsVoice` | string | ❌ | Edge TTS 语音 |
+| `ttsReferenceAudio` | string | ❌ | VoxCPM 参考音频 |
+
+---
+
+## Keepalive（保活机制）
+
+文件：`vendor/bot/keepalive.ts`
+
+独立于 SDK 内部 ping 的防御性看门狗：
+
+- **间隔**: 每 15 秒
+- **防风暴**: 5 秒内跳过重复 tick
+- **睡眠检测**: 距上次 tick 超过 30 秒重置计数器
+- **HTTP 探针**: 重连前 HEAD 请求检测网络可达性
+- **死连接阈值**: 连续 3 个 tick 确认 WS 断开才强制重连
+
+---
+
+## 桥接 Hook
+
+`useFeishuBridge`（`src/hooks/useFeishuBridge.ts`）
+
+React hook，负责：
+
+1. 订阅 FeishuService 的入站事件
+2. 监听 `messages` 数组，识别飞书来源的消息（`origin.kind === 'channel' && origin.server === 'feishu'`）
+3. 收集后续 AI 回复
+4. 在 `isLoading` 从 true→false 时:
+   - 主: `sendMarkdown()` 发送完整回复
+   - 次: `sendVoice()` 发送 TTS 语音
+
+---
+
+## 与 FriendService 的对比
+
+| 方面 | FeishuService | FriendService |
+|------|--------------|---------------|
+| 通信方式 | WebSocket (`@larksuite/channel`) | 同进程 HTTP + SSE |
+| 消息输入 | 文字（飞书 IM） | 文字 / 语音（VAD + STT） |
+| 语音方向 | 仅输出（TTS） | 双向（VAD → STT → AI → TTS） |
+| TTS 引擎 | Edge TTS, VoxCPM | Edge TTS, Qwen TTS |
+| 配置存储 | `~/.claude/adapters.json` | `getPrefs()` |
+| 服务位置 | `src/services/feishu/` | `src/friend/` |

docs/services/overview.md

@@ -117,24 +117,19 @@ Auto Dream 是一个后台记忆整合系统，在对话间期自动运行，将
 
 **目录**: `src/services/feishu/`
 
-飞书机器人集成，基于 `@larksuite/channel` SDK。
+飞书（Feishu/Lark）机器人集成，基于 `@larksuite/channel` SDK 的 WebSocket 长连接机器人。
 
-### 核心文件
+详见 [飞书集成文档](feishu.md)。
 
-| 文件 | 描述 |
-|------|------|
-| `FeishuService.ts` | 飞书机器人服务 — 创建 LarkChannel、注册应用、处理消息事件、管理聊天模式、引用回复、保活机制 |
-| `feishuConfig.ts` | 配置管理 — 读写 `~/.claude/adapters.json` 中的飞书配置段；管理已配对用户、授权用户白名单、Group 模式设置 |
-| `vendor/` | 自包含的第三方实现模块（核心日志、机器人 pending 队列、保活、引用回复、访问策略） |
-
-### 功能
+### 功能速览
 
-- 应用注册与事件处理
-- DM 私聊白名单
-- Group 群聊模式
+- 应用注册（支持 QR 码一键创建）
+- DM 私聊 / Group 群聊模式
+- 访问控制（白名单 / 管理员 / 拥有者）
 - 引用上下文回复
-- 管理员权限控制
-- 自动保活（Keepalive）
+- Markdown 格式化输出
+- 语音回复（Edge TTS / VoxCPM 语音克隆）
+- Keepalive 自动保活
 
 ---
 

docs/tools/overview.md

@@ -244,8 +244,23 @@ LLM 请求工具调用
 
 ### WebSearch / WebFetch
 
-- **WebSearchTool**: 使用 Tavily API 或本地 SearXNG 进行网络搜索
-- **WebFetchTool**: 抓取 URL 内容并应用 prompt 处理（提取、总结）
+#### 双后端架构
+
+WebSearchTool 支持两个搜索后端：
+
+| 后端 | 类型 | 配置 | 特点 |
+|------|------|------|------|
+| **Tavily** | 云 API | `TAVILY_API_KEY` 环境变量 | 稳定、无需自托管 |
+| **SearXNG** | 自托管 | Docker 运行 `verspersearch` | 完全隐私、无 API 成本 |
+
+后端自动选择：若配置了 `TAVILY_API_KEY` 则使用 Tavily，否则回退到本地 SearXNG。
+
+#### WebFetch
+
+抓取 URL 内容并应用 prompt 处理（提取、总结）。支持将结果渲染为 Markdown 格式，包含图片链接。
+
+配置项：
+- `JINA_API_KEY` — 可选的 Jina AI API 密钥，用于增强型内容提取
 
 相关文件：
 - `/home/yuki/Code/Agent/VersperClaw/src/Tool.ts` — Tool 类型与 buildTool 框架