@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/nodes/media-understanding.md

@@ -0,0 +1,380 @@
+---
+read_when:
+  - 设计或重构媒体理解
+  - 调优入站音频/视频/图片预处理
+summary: 入站图片/音频/视频理解（可选），带提供商 + CLI 回退
+title: 媒体理解
+x-i18n:
+  generated_at: "2026-02-03T07:51:40Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f6c575662b7fcbf0b62c46e3fdfa4cdb7cfd455513097e4a2cdec8a34cbdbd48
+  source_path: nodes/media-understanding.md
+  workflow: 15
+---
+
+# 媒体理解（入站）— 2026-01-17
+
+QuantumClaw 可以在回复流程运行之前**摘要入站媒体**（图片/音频/视频）。它会自动检测本地工具或提供商密钥是否可用，并且可以禁用或自定义。如果理解关闭，模型仍然会像往常一样接收原始文件/URL。
+
+## 目标
+
+- 可选：将入站媒体预先消化为短文本，以便更快路由 + 更好的命令解析。
+- 保留原始媒体传递给模型（始终）。
+- 支持**提供商 API** 和 **CLI 回退**。
+- 允许多个模型并按顺序回退（错误/大小/超时）。
+
+## 高层行为
+
+1. 收集入站附件（`MediaPaths`、`MediaUrls`、`MediaTypes`）。
+2. 对于每个启用的能力（图片/音频/视频），根据策略选择附件（默认：**第一个**）。
+3. 选择第一个符合条件的模型条目（大小 + 能力 + 认证）。
+4. 如果模型失败或媒体太大，**回退到下一个条目**。
+5. 成功时：
+   - `Body` 变为 `[Image]`、`[Audio]` 或 `[Video]` 块。
+   - 音频设置 `{{Transcript}}`；命令解析在有标题文本时使用标题文本，否则使用转录。
+   - 标题作为 `User text:` 保留在块内。
+
+如果理解失败或被禁用，**回复流程继续**使用原始正文 + 附件。
+
+## 配置概述
+
+`tools.media` 支持**共享模型**加上每能力覆盖：
+
+- `tools.media.models`：共享模型列表（使用 `capabilities` 来限定）。
+- `tools.media.image` / `tools.media.audio` / `tools.media.video`：
+  - 默认值（`prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`）
+  - 提供商覆盖（`baseUrl`、`headers`、`providerOptions`）
+  - 通过 `tools.media.audio.providerOptions.deepgram` 配置 Deepgram 音频选项
+  - 可选的**每能力 `models` 列表**（优先于共享模型）
+  - `attachments` 策略（`mode`、`maxAttachments`、`prefer`）
+  - `scope`（可选的按渠道/聊天类型/会话键限定）
+- `tools.media.concurrency`：最大并发能力运行数（默认 **2**）。
+
+```json5
+{
+  tools: {
+    media: {
+      models: [
+        /* 共享列表 */
+      ],
+      image: {
+        /* 可选覆盖 */
+      },
+      audio: {
+        /* 可选覆盖 */
+      },
+      video: {
+        /* 可选覆盖 */
+      },
+    },
+  },
+}
+```
+
+### 模型条目
+
+每个 `models[]` 条目可以是**提供商**或 **CLI**：
+
+```json5
+{
+  type: "provider", // 省略时默认
+  provider: "openai",
+  model: "gpt-5.2",
+  prompt: "Describe the image in <= 500 chars.",
+  maxChars: 500,
+  maxBytes: 10485760,
+  timeoutSeconds: 60,
+  capabilities: ["image"], // 可选，用于多模态条目
+  profile: "vision-profile",
+  preferredProfile: "vision-fallback",
+}
+```
+
+```json5
+{
+  type: "cli",
+  command: "gemini",
+  args: [
+    "-m",
+    "gemini-3-flash",
+    "--allowed-tools",
+    "read_file",
+    "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
+  ],
+  maxChars: 500,
+  maxBytes: 52428800,
+  timeoutSeconds: 120,
+  capabilities: ["video", "image"],
+}
+```
+
+CLI 模板还可以使用：
+
+- `{{MediaDir}}`（包含媒体文件的目录）
+- `{{OutputDir}}`（为本次运行创建的临时目录）
+- `{{OutputBase}}`（临时文件基础路径，无扩展名）
+
+## 默认值和限制
+
+推荐默认值：
+
+- `maxChars`：图片/视频为 **500**（简短，适合命令）
+- `maxChars`：音频**不设置**（完整转录，除非你设置限制）
+- `maxBytes`：
+  - 图片：**10MB**
+  - 音频：**20MB**
+  - 视频：**50MB**
+
+规则：
+
+- 如果媒体超过 `maxBytes`，该模型被跳过，**尝试下一个模型**。
+- 如果模型返回超过 `maxChars`，输出被截断。
+- `prompt` 默认为简单的"Describe the {media}."加上 `maxChars` 指导（仅图片/视频）。
+- 如果 `<capability>.enabled: true` 但未配置模型，当提供商支持该能力时，QuantumClaw 尝试**活动的回复模型**。
+
+### 自动检测媒体理解（默认）
+
+如果 `tools.media.<capability>.enabled` **未**设置为 `false` 且你没有配置模型，QuantumClaw 按以下顺序自动检测并**在第一个可用选项处停止**：
+
+1. **本地 CLI**（仅音频；如果已安装）
+   - `sherpa-onnx-offline`（需要带有 encoder/decoder/joiner/tokens 的 `SHERPA_ONNX_MODEL_DIR`）
+   - `whisper-cli`（`whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或捆绑的 tiny 模型）
+   - `whisper`（Python CLI；自动下载模型）
+2. **Gemini CLI**（`gemini`）使用 `read_many_files`
+3. **提供商密钥**
+   - 音频：OpenAI → Groq → Deepgram → Google
+   - 图片：OpenAI → Anthropic → Google → MiniMax
+   - 视频：Google
+
+要禁用自动检测，设置：
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: false,
+      },
+    },
+  },
+}
+```
+
+注意：二进制文件检测在 macOS/Linux/Windows 上是尽力而为的；确保 CLI 在 `PATH` 上（我们会展开 `~`），或设置带有完整命令路径的显式 CLI 模型。
+
+## 能力（可选）
+
+如果你设置了 `capabilities`，该条目仅对这些媒体类型运行。对于共享列表，QuantumClaw 可以推断默认值：
+
+- `openai`、`anthropic`、`minimax`：**图片**
+- `google`（Gemini API）：**图片 + 音频 + 视频**
+- `groq`：**音频**
+- `deepgram`：**音频**
+
+对于 CLI 条目，**显式设置 `capabilities`** 以避免意外匹配。如果你省略 `capabilities`，该条目对它出现的列表都符合条件。
+
+## 提供商支持矩阵（QuantumClaw 集成）
+
+| 能力 | 提供商集成                                     | 说明                                    |
+| ---- | ---------------------------------------------- | --------------------------------------- |
+| 图片 | OpenAI / Anthropic / Google / 其他通过 `pi-ai` | 注册表中任何支持图片的模型都可用。      |
+| 音频 | OpenAI、Groq、Deepgram、Google                 | 提供商转录（Whisper/Deepgram/Gemini）。 |
+| 视频 | Google（Gemini API）                           | 提供商视频理解。                        |
+
+## 推荐提供商
+
+**图片**
+
+- 如果支持图片，优先使用你的活动模型。
+- 良好的默认值：`openai/gpt-5.2`、`anthropic/claude-opus-4-5`、`google/gemini-3-pro-preview`。
+
+**音频**
+
+- `openai/gpt-4o-mini-transcribe`、`groq/whisper-large-v3-turbo` 或 `deepgram/nova-3`。
+- CLI 回退：`whisper-cli`（whisper-cpp）或 `whisper`。
+- Deepgram 设置：[Deepgram（音频转录）](/providers/deepgram)。
+
+**视频**
+
+- `google/gemini-3-flash-preview`（快速）、`google/gemini-3-pro-preview`（更丰富）。
+- CLI 回退：`gemini` CLI（支持对视频/音频使用 `read_file`）。
+
+## 附件策略
+
+每能力的 `attachments` 控制处理哪些附件：
+
+- `mode`：`first`（默认）或 `all`
+- `maxAttachments`：限制处理数量（默认 **1**）
+- `prefer`：`first`、`last`、`path`、`url`
+
+当 `mode: "all"` 时，输出标记为 `[Image 1/2]`、`[Audio 2/2]` 等。
+
+## 配置示例
+
+### 1) 共享模型列表 + 覆盖
+
+```json5
+{
+  tools: {
+    media: {
+      models: [
+        { provider: "openai", model: "gpt-5.2", capabilities: ["image"] },
+        {
+          provider: "google",
+          model: "gemini-3-flash-preview",
+          capabilities: ["image", "audio", "video"],
+        },
+        {
+          type: "cli",
+          command: "gemini",
+          args: [
+            "-m",
+            "gemini-3-flash",
+            "--allowed-tools",
+            "read_file",
+            "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
+          ],
+          capabilities: ["image", "video"],
+        },
+      ],
+      audio: {
+        attachments: { mode: "all", maxAttachments: 2 },
+      },
+      video: {
+        maxChars: 500,
+      },
+    },
+  },
+}
+```
+
+### 2) 仅音频 + 视频（图片关闭）
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        models: [
+          { provider: "openai", model: "gpt-4o-mini-transcribe" },
+          {
+            type: "cli",
+            command: "whisper",
+            args: ["--model", "base", "{{MediaPath}}"],
+          },
+        ],
+      },
+      video: {
+        enabled: true,
+        maxChars: 500,
+        models: [
+          { provider: "google", model: "gemini-3-flash-preview" },
+          {
+            type: "cli",
+            command: "gemini",
+            args: [
+              "-m",
+              "gemini-3-flash",
+              "--allowed-tools",
+              "read_file",
+              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
+            ],
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+### 3) 可选图片理解
+
+```json5
+{
+  tools: {
+    media: {
+      image: {
+        enabled: true,
+        maxBytes: 10485760,
+        maxChars: 500,
+        models: [
+          { provider: "openai", model: "gpt-5.2" },
+          { provider: "anthropic", model: "claude-opus-4-5" },
+          {
+            type: "cli",
+            command: "gemini",
+            args: [
+              "-m",
+              "gemini-3-flash",
+              "--allowed-tools",
+              "read_file",
+              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
+            ],
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+### 4) 多模态单条目（显式能力）
+
+```json5
+{
+  tools: {
+    media: {
+      image: {
+        models: [
+          {
+            provider: "google",
+            model: "gemini-3-pro-preview",
+            capabilities: ["image", "video", "audio"],
+          },
+        ],
+      },
+      audio: {
+        models: [
+          {
+            provider: "google",
+            model: "gemini-3-pro-preview",
+            capabilities: ["image", "video", "audio"],
+          },
+        ],
+      },
+      video: {
+        models: [
+          {
+            provider: "google",
+            model: "gemini-3-pro-preview",
+            capabilities: ["image", "video", "audio"],
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+## 状态输出
+
+当媒体理解运行时，`/status` 包含一行简短摘要：
+
+```
+📎 Media: image ok (openai/gpt-5.2) · audio skipped (maxBytes)
+```
+
+这显示每能力的结果以及适用时选择的提供商/模型。
+
+## 注意事项
+
+- 理解是**尽力而为**的。错误不会阻止回复。
+- 即使理解被禁用，附件仍然传递给模型。
+- 使用 `scope` 限制理解运行的位置（例如仅私信）。
+
+## 相关文档
+
+- [配置](/gateway/configuration)
+- [图片和媒体支持](/nodes/images)

package/docs/zh-CN/nodes/talk.md

@@ -0,0 +1,97 @@
+---
+read_when:
+  - 在 macOS/iOS/Android 上实现 Talk 模式
+  - 更改语音/TTS/中断行为
+summary: Talk 模式：使用 ElevenLabs TTS 进行连续语音对话
+title: Talk 模式
+x-i18n:
+  generated_at: "2026-02-03T10:07:59Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: ecbc3701c9e9502970cf13227fedbc9714d13668d8f4f3988fef2a4d68116a42
+  source_path: nodes/talk.md
+  workflow: 15
+---
+
+# Talk 模式
+
+Talk 模式是一个连续的语音对话循环：
+
+1. 监听语音
+2. 将转录文本发送到模型（main 会话，chat.send）
+3. 等待响应
+4. 通过 ElevenLabs 朗读（流式播放）
+
+## 行为（macOS）
+
+- Talk 模式启用时显示**常驻悬浮窗**。
+- **监听 → 思考 → 朗读**阶段转换。
+- **短暂停顿**（静音窗口）后，当前转录文本被发送。
+- 回复被**写入 WebChat**（与打字相同）。
+- **语音中断**（默认开启）：如果用户在助手朗读时开始说话，我们会停止播放并记录中断时间戳供下一个提示使用。
+
+## 回复中的语音指令
+
+助手可以在回复前添加**单行 JSON** 来控制语音：
+
+```json
+{ "voice": "<voice-id>", "once": true }
+```
+
+规则：
+
+- 仅适用于第一个非空行。
+- 未知键会被忽略。
+- `once: true` 仅适用于当前回复。
+- 没有 `once` 时，该语音成为 Talk 模式的新默认值。
+- JSON 行在 TTS 播放前会被移除。
+
+支持的键：
+
+- `voice` / `voice_id` / `voiceId`
+- `model` / `model_id` / `modelId`
+- `speed`、`rate`（WPM）、`stability`、`similarity`、`style`、`speakerBoost`
+- `seed`、`normalize`、`lang`、`output_format`、`latency_tier`
+- `once`
+
+## 配置（`~/.quantumclaw/quantumclaw.json`）
+
+```json5
+{
+  talk: {
+    voiceId: "elevenlabs_voice_id",
+    modelId: "eleven_v3",
+    outputFormat: "mp3_44100_128",
+    apiKey: "elevenlabs_api_key",
+    interruptOnSpeech: true,
+  },
+}
+```
+
+默认值：
+
+- `interruptOnSpeech`：true
+- `voiceId`：回退到 `ELEVENLABS_VOICE_ID` / `SAG_VOICE_ID`（或当 API 密钥可用时使用第一个 ElevenLabs 语音）
+- `modelId`：未设置时默认为 `eleven_v3`
+- `apiKey`：回退到 `ELEVENLABS_API_KEY`（或 Gateway 网关 shell profile（如果可用））
+- `outputFormat`：macOS/iOS 上默认为 `pcm_44100`，Android 上默认为 `pcm_24000`（设置 `mp3_*` 以强制 MP3 流式传输）
+
+## macOS UI
+
+- 菜单栏切换：**Talk**
+- 配置标签页：**Talk Mode** 组（voice id + 中断开关）
+- 悬浮窗：
+  - **监听**：云朵随麦克风电平脉动
+  - **思考**：下沉动画
+  - **朗读**：辐射圆环
+  - 点击云朵：停止朗读
+  - 点击 X：退出 Talk 模式
+
+## 注意事项
+
+- 需要语音 + 麦克风权限。
+- 使用 `chat.send` 针对会话键 `main`。
+- TTS 使用带有 `ELEVENLABS_API_KEY` 的 ElevenLabs 流式 API，并在 macOS/iOS/Android 上进行增量播放以降低延迟。
+- `eleven_v3` 的 `stability` 验证为 `0.0`、`0.5` 或 `1.0`；其他模型接受 `0..1`。
+- 设置时 `latency_tier` 验证为 `0..4`。
+- Android 支持 `pcm_16000`、`pcm_22050`、`pcm_24000` 和 `pcm_44100` 输出格式，用于低延迟 AudioTrack 流式传输。

package/docs/zh-CN/nodes/troubleshooting.md

@@ -0,0 +1,8 @@
+---
+summary: 节点故障排查：排查配对、前台限制、权限与工具调用失败
+title: 节点故障排查
+---
+
+# 节点故障排查
+
+该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Node Troubleshooting](/nodes/troubleshooting)。

package/docs/zh-CN/nodes/voicewake.md

@@ -0,0 +1,72 @@
+---
+read_when:
+  - 更改语音唤醒词行为或默认值
+  - 添加需要唤醒词同步的新节点平台
+summary: 全局语音唤醒词（Gateway 网关拥有）及其如何跨节点同步
+title: 语音唤醒
+x-i18n:
+  generated_at: "2026-02-03T07:51:10Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: eb34f52dfcdc3fc1ae088ae1f621f245546d3cf388299fbeea62face61788c37
+  source_path: nodes/voicewake.md
+  workflow: 15
+---
+
+# 语音唤醒（全局唤醒词）
+
+QuantumClaw 将**唤醒词作为单一全局列表**，由 **Gateway 网关**拥有。
+
+- **没有**每节点的自定义唤醒词。
+- **任何节点/应用 UI 都可以编辑**列表；更改由 Gateway 网关持久化并广播给所有人。
+- 每个设备仍保留自己的**语音唤醒启用/禁用**开关（本地用户体验 + 权限不同）。
+
+## 存储（Gateway 网关主机）
+
+唤醒词存储在 Gateway 网关机器上：
+
+- `~/.quantumclaw/settings/voicewake.json`
+
+结构：
+
+```json
+{ "triggers": ["quantumclaw", "claude", "computer"], "updatedAtMs": 1730000000000 }
+```
+
+## 协议
+
+### 方法
+
+- `voicewake.get` → `{ triggers: string[] }`
+- `voicewake.set`，参数 `{ triggers: string[] }` → `{ triggers: string[] }`
+
+注意事项：
+
+- 触发词会被规范化（修剪空格、删除空值）。空列表回退到默认值。
+- 为安全起见会强制执行限制（数量/长度上限）。
+
+### 事件
+
+- `voicewake.changed` 载荷 `{ triggers: string[] }`
+
+接收者：
+
+- 所有 WebSocket 客户端（macOS 应用、WebChat 等）
+- 所有已连接的节点（iOS/Android），以及节点连接时作为初始"当前状态"推送。
+
+## 客户端行为
+
+### macOS 应用
+
+- 使用全局列表来控制 `VoiceWakeRuntime` 触发器。
+- 在语音唤醒设置中编辑"触发词"会调用 `voicewake.set`，然后依赖广播保持其他客户端同步。
+
+### iOS 节点
+
+- 使用全局列表进行 `VoiceWakeManager` 触发检测。
+- 在设置中编辑唤醒词会调用 `voicewake.set`（通过 Gateway 网关 WS），同时保持本地唤醒词检测的响应性。
+
+### Android 节点
+
+- 在设置中暴露唤醒词编辑器。
+- 通过 Gateway 网关 WS 调用 `voicewake.set`，使编辑在所有地方同步。

package/docs/zh-CN/perplexity.md

@@ -0,0 +1,102 @@
+---
+read_when:
+  - 你想使用 Perplexity Sonar 进行网络搜索
+  - 你需要设置 PERPLEXITY_API_KEY 或 OpenRouter
+summary: Perplexity Sonar 的 web_search 设置
+title: Perplexity Sonar
+x-i18n:
+  generated_at: "2026-02-01T21:19:10Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 264d08e62e3bec854e378dad345ca209d139cd19b0469f3b25f88bb63b73ba00
+  source_path: perplexity.md
+  workflow: 15
+---
+
+# Perplexity Sonar
+
+QuantumClaw 可以使用 Perplexity Sonar 作为 `web_search` 工具。你可以通过 Perplexity 的直连 API 或通过 OpenRouter 连接。
+
+## API 选项
+
+### Perplexity（直连）
+
+- Base URL：https://api.perplexity.ai
+- 环境变量：`PERPLEXITY_API_KEY`
+
+### OpenRouter（替代方案）
+
+- Base URL：https://openrouter.ai/api/v1
+- 环境变量：`OPENROUTER_API_KEY`
+- 支持预付费/加密货币积分。
+
+## 配置示例
+
+```json5
+{
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "pplx-...",
+            baseUrl: "https://api.perplexity.ai",
+            model: "perplexity/sonar-pro",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+      },
+    },
+  },
+}
+```
+
+## 从 Brave 切换
+
+```json5
+{
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "pplx-...",
+            baseUrl: "https://api.perplexity.ai",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+      },
+    },
+  },
+}
+```
+
+如果同时设置了 `PERPLEXITY_API_KEY` 和 `OPENROUTER_API_KEY`，请设置 `plugins.entries.perplexity.config.webSearch.baseUrl`（或 `plugins.entries.perplexity.config.webSearch.apiKey`）以消除歧义。
+
+提供商专属配置现在统一放在 `plugins.entries.<plugin>.config.webSearch.*`。旧的 `tools.web.search.*` 路径仅通过兼容层继续生效，不再推荐用于新配置。
+
+如果未设置 base URL，QuantumClaw 会根据 API 密钥来源选择默认值：
+
+- `PERPLEXITY_API_KEY` 或 `pplx-...` → 直连 Perplexity（`https://api.perplexity.ai`）
+- `OPENROUTER_API_KEY` 或 `sk-or-...` → OpenRouter（`https://openrouter.ai/api/v1`）
+- 未知密钥格式 → OpenRouter（安全回退）
+
+## 模型
+
+- `perplexity/sonar` — 带网络搜索的快速问答
+- `perplexity/sonar-pro`（默认） — 多步推理 + 网络搜索
+- `perplexity/sonar-reasoning-pro` — 深度研究
+
+请参阅 [Web 工具](/tools/web) 了解 web_search 配置详情。