@symerian/symi 3.0.21 → 3.0.22

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

@@ -1,380 +0,0 @@
----
-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
-
-Symi 可以在回复流程运行之前**摘要入站媒体**（图片/音频/视频）。它会自动检测本地工具或提供商密钥是否可用，并且可以禁用或自定义。如果理解关闭，模型仍然会像往常一样接收原始文件/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` 但未配置模型，当提供商支持该能力时，Symi 尝试**活动的回复模型**。
-
-### 自动检测媒体理解（默认）
-
-如果 `tools.media.<capability>.enabled` **未**设置为 `false` 且你没有配置模型，Symi 按以下顺序自动检测并**在第一个可用选项处停止**：
-
-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`，该条目仅对这些媒体类型运行。对于共享列表，Symi 可以推断默认值：
-
-- `openai`、`anthropic`、`minimax`：**图片**
-- `google`（Gemini API）：**图片 + 音频 + 视频**
-- `groq`：**音频**
-- `deepgram`：**音频**
-
-对于 CLI 条目，**显式设置 `capabilities`** 以避免意外匹配。如果你省略 `capabilities`，该条目对它出现的列表都符合条件。
-
-## 提供商支持矩阵（Symi 集成）
-
-| 能力 | 提供商集成                                     | 说明                                    |
-| ---- | ---------------------------------------------- | --------------------------------------- |
-| 图片 | 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

@@ -1,97 +0,0 @@
----
-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`
-
-## 配置（`~/.symi/symi.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

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

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

@@ -1,72 +0,0 @@
----
-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
----
-
-# 语音唤醒（全局唤醒词）
-
-Symi 将**唤醒词作为单一全局列表**，由 **Gateway 网关**拥有。
-
-- **没有**每节点的自定义唤醒词。
-- **任何节点/应用 UI 都可以编辑**列表；更改由 Gateway 网关持久化并广播给所有人。
-- 每个设备仍保留自己的**语音唤醒启用/禁用**开关（本地用户体验 + 权限不同）。
-
-## 存储（Gateway 网关主机）
-
-唤醒词存储在 Gateway 网关机器上：
-
-- `~/.symi/settings/voicewake.json`
-
-结构：
-
-```json
-{ "triggers": ["symi", "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

@@ -1,84 +0,0 @@
----
-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
-
-Symi 可以使用 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
-{
-  tools: {
-    web: {
-      search: {
-        provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...",
-          baseUrl: "https://api.perplexity.ai",
-          model: "perplexity/sonar-pro",
-        },
-      },
-    },
-  },
-}
-```
-
-## 从 Brave 切换
-
-```json5
-{
-  tools: {
-    web: {
-      search: {
-        provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...",
-          baseUrl: "https://api.perplexity.ai",
-        },
-      },
-    },
-  },
-}
-```
-
-如果同时设置了 `PERPLEXITY_API_KEY` 和 `OPENROUTER_API_KEY`，请设置 `tools.web.search.perplexity.baseUrl`（或 `tools.web.search.perplexity.apiKey`）以消除歧义。
-
-如果未设置 base URL，Symi 会根据 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 配置详情。