@symerian/symi 3.0.20 → 3.0.22

package/docs/zh-CN/logging.md

@@ -1,329 +0,0 @@
----
-read_when:
-  - 你需要一个适合初学者的日志概述
-  - 你想配置日志级别或格式
-  - 你正在故障排除并需要快速找到日志
-summary: 日志概述：文件日志、控制台输出、CLI 跟踪和控制 UI
-title: 日志
-x-i18n:
-  generated_at: "2026-02-03T07:50:52Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 884fcf4a906adff34d546908e22abd283cb89fe0845076cf925c72384ec3556b
-  source_path: logging.md
-  workflow: 15
----
-
-# 日志
-
-Symi 在两个地方记录日志：
-
-- **文件日志**（JSON 行）由 Gateway 网关写入。
-- **控制台输出**显示在终端和控制 UI 中。
-
-本页说明日志存放位置、如何读取日志以及如何配置日志级别和格式。
-
-## 日志存放位置
-
-默认情况下，Gateway 网关在以下位置写入滚动日志文件：
-
-`/tmp/symi/symi-YYYY-MM-DD.log`
-
-日期使用 Gateway 网关主机的本地时区。
-
-你可以在 `~/.symi/symi.json` 中覆盖此设置：
-
-```json
-{
-  "logging": {
-    "file": "/path/to/symi.log"
-  }
-}
-```
-
-## 如何读取日志
-
-### CLI：实时跟踪（推荐）
-
-使用 CLI 通过 RPC 跟踪 Gateway 网关日志文件：
-
-```bash
-symi logs --follow
-```
-
-输出模式：
-
-- **TTY 会话**：美观、彩色、结构化的日志行。
-- **非 TTY 会话**：纯文本。
-- `--json`：行分隔的 JSON（每行一个日志事件）。
-- `--plain`：在 TTY 会话中强制纯文本。
-- `--no-color`：禁用 ANSI 颜色。
-
-在 JSON 模式下，CLI 输出带 `type` 标签的对象：
-
-- `meta`：流元数据（文件、游标、大小）
-- `log`：解析的日志条目
-- `notice`：截断/轮转提示
-- `raw`：未解析的日志行
-
-如果 Gateway 网关无法访问，CLI 会打印一个简短提示运行：
-
-```bash
-symi doctor
-```
-
-### 控制 UI（Web）
-
-控制 UI 的**日志**标签页使用 `logs.tail` 跟踪相同的文件。
-参见 [/web/control-ui](/web/control-ui) 了解如何打开它。
-
-### 仅渠道日志
-
-要过滤渠道活动（WhatsApp/Telegram 等），使用：
-
-```bash
-symi channels logs --channel whatsapp
-```
-
-## 日志格式
-
-### 文件日志（JSONL）
-
-日志文件中的每一行都是一个 JSON 对象。CLI 和控制 UI 解析这些条目以渲染结构化输出（时间、级别、子系统、消息）。
-
-### 控制台输出
-
-控制台日志**感知 TTY**并格式化以提高可读性：
-
-- 子系统前缀（例如 `gateway/channels/whatsapp`）
-- 级别着色（info/warn/error）
-- 可选的紧凑或 JSON 模式
-
-控制台格式由 `logging.consoleStyle` 控制。
-
-## 配置日志
-
-所有日志配置都在 `~/.symi/symi.json` 的 `logging` 下。
-
-```json
-{
-  "logging": {
-    "level": "info",
-    "file": "/tmp/symi/symi-YYYY-MM-DD.log",
-    "consoleLevel": "info",
-    "consoleStyle": "pretty",
-    "redactSensitive": "tools",
-    "redactPatterns": ["sk-.*"]
-  }
-}
-```
-
-### 日志级别
-
-- `logging.level`：**文件日志**（JSONL）级别。
-- `logging.consoleLevel`：**控制台**详细程度级别。
-
-`--verbose` 仅影响控制台输出；它不改变文件日志级别。
-
-### 控制台样式
-
-`logging.consoleStyle`：
-
-- `pretty`：人类友好、彩色、带时间戳。
-- `compact`：更紧凑的输出（最适合长会话）。
-- `json`：每行 JSON（用于日志处理器）。
-
-### 脱敏
-
-工具摘要可以在敏感令牌输出到控制台之前对其进行脱敏：
-
-- `logging.redactSensitive`：`off` | `tools`（默认：`tools`）
-- `logging.redactPatterns`：用于覆盖默认集的正则表达式字符串列表
-
-脱敏仅影响**控制台输出**，不会改变文件日志。
-
-## 诊断 + OpenTelemetry
-
-诊断是用于模型运行**和**消息流遥测（webhooks、队列、会话状态）的结构化、机器可读事件。它们**不**替代日志；它们存在是为了向指标、追踪和其他导出器提供数据。
-
-诊断事件在进程内发出，但导出器仅在启用诊断 + 导出器插件时才附加。
-
-### OpenTelemetry 与 OTLP
-
-- **OpenTelemetry（OTel）**：追踪、指标和日志的数据模型 + SDK。
-- **OTLP**：用于将 OTel 数据导出到收集器/后端的线路协议。
-- Symi 目前通过 **OTLP/HTTP（protobuf）** 导出。
-
-### 导出的信号
-
-- **指标**：计数器 + 直方图（令牌使用、消息流、队列）。
-- **追踪**：模型使用 + webhook/消息处理的 span。
-- **日志**：启用 `diagnostics.otel.logs` 时通过 OTLP 导出。日志量可能很大；请注意 `logging.level` 和导出器过滤器。
-
-### 诊断事件目录
-
-模型使用：
-
-- `model.usage`：令牌、成本、持续时间、上下文、提供商/模型/渠道、会话 ID。
-
-消息流：
-
-- `webhook.received`：每渠道的 webhook 入口。
-- `webhook.processed`：webhook 已处理 + 持续时间。
-- `webhook.error`：webhook 处理程序错误。
-- `message.queued`：消息入队等待处理。
-- `message.processed`：结果 + 持续时间 + 可选错误。
-
-队列 + 会话：
-
-- `queue.lane.enqueue`：命令队列通道入队 + 深度。
-- `queue.lane.dequeue`：命令队列通道出队 + 等待时间。
-- `session.state`：会话状态转换 + 原因。
-- `session.stuck`：会话卡住警告 + 持续时间。
-- `run.attempt`：运行重试/尝试元数据。
-- `diagnostic.heartbeat`：聚合计数器（webhooks/队列/会话）。
-
-### 启用诊断（无导出器）
-
-如果你希望诊断事件可用于插件或自定义接收器，使用此配置：
-
-```json
-{
-  "diagnostics": {
-    "enabled": true
-  }
-}
-```
-
-### 诊断标志（定向日志）
-
-使用标志在不提高 `logging.level` 的情况下开启额外的定向调试日志。
-标志不区分大小写，支持通配符（例如 `telegram.*` 或 `*`）。
-
-```json
-{
-  "diagnostics": {
-    "flags": ["telegram.http"]
-  }
-}
-```
-
-环境变量覆盖（一次性）：
-
-```
-SYMI_DIAGNOSTICS=telegram.http,telegram.payload
-```
-
-注意：
-
-- 标志日志进入标准日志文件（与 `logging.file` 相同）。
-- 输出仍根据 `logging.redactSensitive` 进行脱敏。
-- 完整指南：[/diagnostics/flags](/diagnostics/flags)。
-
-### 导出到 OpenTelemetry
-
-诊断可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。这适用于任何接受 OTLP/HTTP 的 OpenTelemetry 收集器/后端。
-
-```json
-{
-  "plugins": {
-    "allow": ["diagnostics-otel"],
-    "entries": {
-      "diagnostics-otel": {
-        "enabled": true
-      }
-    }
-  },
-  "diagnostics": {
-    "enabled": true,
-    "otel": {
-      "enabled": true,
-      "endpoint": "http://otel-collector:4318",
-      "protocol": "http/protobuf",
-      "serviceName": "symi-gateway",
-      "traces": true,
-      "metrics": true,
-      "logs": true,
-      "sampleRate": 0.2,
-      "flushIntervalMs": 60000
-    }
-  }
-}
-```
-
-注意：
-
-- 你也可以使用 `symi plugins enable diagnostics-otel` 启用插件。
-- `protocol` 目前仅支持 `http/protobuf`。`grpc` 被忽略。
-- 指标包括令牌使用、成本、上下文大小、运行持续时间和消息流计数器/直方图（webhooks、队列、会话状态、队列深度/等待）。
-- 追踪/指标可以通过 `traces` / `metrics` 切换（默认：开启）。启用时，追踪包括模型使用 span 加上 webhook/消息处理 span。
-- 当你的收集器需要认证时设置 `headers`。
-- 支持的环境变量：`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_PROTOCOL`。
-
-### 导出的指标（名称 + 类型）
-
-模型使用：
-
-- `symi.tokens`（计数器，属性：`symi.token`、`symi.channel`、`symi.provider`、`symi.model`）
-- `symi.cost.usd`（计数器，属性：`symi.channel`、`symi.provider`、`symi.model`）
-- `symi.run.duration_ms`（直方图，属性：`symi.channel`、`symi.provider`、`symi.model`）
-- `symi.context.tokens`（直方图，属性：`symi.context`、`symi.channel`、`symi.provider`、`symi.model`）
-
-消息流：
-
-- `symi.webhook.received`（计数器，属性：`symi.channel`、`symi.webhook`）
-- `symi.webhook.error`（计数器，属性：`symi.channel`、`symi.webhook`）
-- `symi.webhook.duration_ms`（直方图，属性：`symi.channel`、`symi.webhook`）
-- `symi.message.queued`（计数器，属性：`symi.channel`、`symi.source`）
-- `symi.message.processed`（计数器，属性：`symi.channel`、`symi.outcome`）
-- `symi.message.duration_ms`（直方图，属性：`symi.channel`、`symi.outcome`）
-
-队列 + 会话：
-
-- `symi.queue.lane.enqueue`（计数器，属性：`symi.lane`）
-- `symi.queue.lane.dequeue`（计数器，属性：`symi.lane`）
-- `symi.queue.depth`（直方图，属性：`symi.lane` 或 `symi.channel=heartbeat`）
-- `symi.queue.wait_ms`（直方图，属性：`symi.lane`）
-- `symi.session.state`（计数器，属性：`symi.state`、`symi.reason`）
-- `symi.session.stuck`（计数器，属性：`symi.state`）
-- `symi.session.stuck_age_ms`（直方图，属性：`symi.state`）
-- `symi.run.attempt`（计数器，属性：`symi.attempt`）
-
-### 导出的 span（名称 + 关键属性）
-
-- `symi.model.usage`
-  - `symi.channel`、`symi.provider`、`symi.model`
-  - `symi.sessionKey`、`symi.sessionId`
-  - `symi.tokens.*`（input/output/cache_read/cache_write/total）
-- `symi.webhook.processed`
-  - `symi.channel`、`symi.webhook`、`symi.chatId`
-- `symi.webhook.error`
-  - `symi.channel`、`symi.webhook`、`symi.chatId`、`symi.error`
-- `symi.message.processed`
-  - `symi.channel`、`symi.outcome`、`symi.chatId`、`symi.messageId`、`symi.sessionKey`、`symi.sessionId`、`symi.reason`
-- `symi.session.stuck`
-  - `symi.state`、`symi.ageMs`、`symi.queueDepth`、`symi.sessionKey`、`symi.sessionId`
-
-### 采样 + 刷新
-
-- 追踪采样：`diagnostics.otel.sampleRate`（0.0–1.0，仅根 span）。
-- 指标导出间隔：`diagnostics.otel.flushIntervalMs`（最小 1000ms）。
-
-### 协议说明
-
-- OTLP/HTTP 端点可以通过 `diagnostics.otel.endpoint` 或 `OTEL_EXPORTER_OTLP_ENDPOINT` 设置。
-- 如果端点已包含 `/v1/traces` 或 `/v1/metrics`，则按原样使用。
-- 如果端点已包含 `/v1/logs`，则按原样用于日志。
-- `diagnostics.otel.logs` 为主日志器输出启用 OTLP 日志导出。
-
-### 日志导出行为
-
-- OTLP 日志使用与写入 `logging.file` 相同的结构化记录。
-- 遵守 `logging.level`（文件日志级别）。控制台脱敏**不**适用于 OTLP 日志。
-- 高流量安装应优先使用 OTLP 收集器采样/过滤。
-
-## 故障排除提示
-
-- **Gateway 网关无法访问？** 先运行 `symi doctor`。
-- **日志为空？** 检查 Gateway 网关是否正在运行并写入 `logging.file` 中的文件路径。
-- **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace` 并重试。

package/docs/zh-CN/network.md

@@ -1,59 +0,0 @@
----
-read_when:
-  - 你需要了解网络架构和安全概述
-  - 你正在调试本地访问、tailnet 访问或配对问题
-  - 你想要获取网络文档的权威列表
-summary: 网络中心：Gateway 网关接口、配对、设备发现和安全
-title: 网络
-x-i18n:
-  generated_at: "2026-02-03T10:07:45Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 0fe4e7dbc8ddea312c8f3093af9b6bc71d9ae4007df76ae24b85889871933bc8
-  source_path: network.md
-  workflow: 15
----
-
-# 网络中心
-
-本中心汇集了 Symi 如何在 localhost、局域网和 tailnet 之间连接、配对和保护设备的核心文档。
-
-## 核心模型
-
-- [Gateway 网关架构](/concepts/architecture)
-- [Gateway 网关协议](/gateway/protocol)
-- [Gateway 网关运维手册](/gateway)
-- [Web 接口 + 绑定模式](/web)
-
-## 配对 + 身份
-
-- [配对概述（私信 + 节点）](/channels/pairing)
-- [Gateway 网关拥有的节点配对](/gateway/pairing)
-- [Devices CLI（配对 + token 轮换）](/cli/devices)
-- [Pairing CLI（私信审批）](/cli/pairing)
-
-本地信任：
-
-- 本地连接（loopback 或 Gateway 网关主机自身的 tailnet 地址）可以自动批准配对，以保持同主机用户体验的流畅性。
-- 非本地的 tailnet/局域网客户端仍需要显式的配对批准。
-
-## 设备发现 + 传输协议
-
-- [设备发现与传输协议](/gateway/discovery)
-- [Bonjour / mDNS](/gateway/bonjour)
-- [远程访问（SSH）](/gateway/remote)
-- [Tailscale](/gateway/tailscale)
-
-## 节点 + 传输协议
-
-- [节点概述](/nodes)
-- [桥接协议（旧版节点）](/gateway/bridge-protocol)
-- [节点运维手册：iOS](/platforms/ios)
-- [节点运维手册：Android](/platforms/android)
-
-## 安全
-
-- [安全概述](/gateway/security)
-- [Gateway 网关配置参考](/gateway/configuration)
-- [故障排除](/gateway/troubleshooting)
-- [Doctor](/gateway/doctor)

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

@@ -1,120 +0,0 @@
----
-read_when:
-  - 更改音频转录或媒体处理方式
-summary: 入站音频/语音消息如何被下载、转录并注入回复
-title: 音频与语音消息
-x-i18n:
-  generated_at: "2026-02-01T21:17:35Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: b926c47989ab0d1ee1fb8ae6372c51d27515b53d6fefe211a85856d372f14569
-  source_path: nodes/audio.md
-  workflow: 15
----
-
-# 音频 / 语音消息 — 2026-01-17
-
-## 已支持的功能
-
-- **媒体理解（音频）**：如果音频理解已启用（或自动检测），Symi 会：
-  1. 找到第一个音频附件（本地路径或 URL），如有需要则下载。
-  2. 在发送给每个模型条目之前执行 `maxBytes` 限制。
-  3. 按顺序运行第一个符合条件的模型条目（提供商或 CLI）。
-  4. 如果失败或跳过（大小/超时），则尝试下一个条目。
-  5. 成功后，将 `Body` 替换为 `[Audio]` 块并设置 `{{Transcript}}`。
-- **命令解析**：转录成功时，`CommandBody`/`RawBody` 会设置为转录文本，因此斜杠命令仍然有效。
-- **详细日志**：在 `--verbose` 模式下，我们会在转录运行和替换正文时记录日志。
-
-## 自动检测（默认）
-
-如果你**未配置模型**且 `tools.media.audio.enabled` **未**设置为 `false`，Symi 会按以下顺序自动检测，并在找到第一个可用选项时停止：
-
-1. **本地 CLI**（如已安装）
-   - `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR` 包含 encoder/decoder/joiner/tokens）
-   - `whisper-cli`（来自 `whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置的 tiny 模型）
-   - `whisper`（Python CLI；自动下载模型）
-2. **Gemini CLI**（`gemini`）使用 `read_many_files`
-3. **提供商密钥**（OpenAI → Groq → Deepgram → Google）
-
-要禁用自动检测，请设置 `tools.media.audio.enabled: false`。
-要自定义，请设置 `tools.media.audio.models`。
-注意：二进制检测在 macOS/Linux/Windows 上采用尽力而为的方式；请确保 CLI 在 `PATH` 中（我们会展开 `~`），或通过完整命令路径设置显式 CLI 模型。
-
-## 配置示例
-
-### 提供商 + CLI 回退（OpenAI + Whisper CLI）
-
-```json5
-{
-  tools: {
-    media: {
-      audio: {
-        enabled: true,
-        maxBytes: 20971520,
-        models: [
-          { provider: "openai", model: "gpt-4o-mini-transcribe" },
-          {
-            type: "cli",
-            command: "whisper",
-            args: ["--model", "base", "{{MediaPath}}"],
-            timeoutSeconds: 45,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-### 仅提供商 + 作用域控制
-
-```json5
-{
-  tools: {
-    media: {
-      audio: {
-        enabled: true,
-        scope: {
-          default: "allow",
-          rules: [{ action: "deny", match: { chatType: "group" } }],
-        },
-        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
-      },
-    },
-  },
-}
-```
-
-### 仅提供商（Deepgram）
-
-```json5
-{
-  tools: {
-    media: {
-      audio: {
-        enabled: true,
-        models: [{ provider: "deepgram", model: "nova-3" }],
-      },
-    },
-  },
-}
-```
-
-## 注意事项与限制
-
-- 提供商认证遵循标准的模型认证顺序（认证配置文件、环境变量、`models.providers.*.apiKey`）。
-- 当使用 `provider: "deepgram"` 时，Deepgram 会读取 `DEEPGRAM_API_KEY`。
-- Deepgram 设置详情：[Deepgram（音频转录）](/providers/deepgram)。
-- 音频提供商可以通过 `tools.media.audio` 覆盖 `baseUrl`、`headers` 和 `providerOptions`。
-- 默认大小限制为 20MB（`tools.media.audio.maxBytes`）。超大音频会跳过该模型并尝试下一个条目。
-- 音频的默认 `maxChars` **未设置**（完整转录文本）。设置 `tools.media.audio.maxChars` 或每个条目的 `maxChars` 来裁剪输出。
-- OpenAI 自动检测默认使用 `gpt-4o-mini-transcribe`；设置 `model: "gpt-4o-transcribe"` 可获得更高准确度。
-- 使用 `tools.media.audio.attachments` 处理多条语音消息（`mode: "all"` + `maxAttachments`）。
-- 转录文本可在模板中通过 `{{Transcript}}` 使用。
-- CLI 标准输出有上限（5MB）；请保持 CLI 输出简洁。
-
-## 常见陷阱
-
-- 作用域规则采用首次匹配优先。`chatType` 会被规范化为 `direct`、`group` 或 `room`。
-- 确保你的 CLI 以退出码 0 退出并输出纯文本；JSON 格式需要通过 `jq -r .text` 进行转换。
-- 保持合理的超时时间（`timeoutSeconds`，默认 60 秒），以避免阻塞回复队列。

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

@@ -1,162 +0,0 @@
----
-read_when:
-  - 在 iOS 节点或 macOS 上添加或修改相机捕获
-  - 扩展智能体可访问的 MEDIA 临时文件工作流
-summary: 用于智能体的相机捕获（iOS 节点 + macOS 应用）：照片（jpg）和短视频片段（mp4）
-title: 相机捕获
-x-i18n:
-  generated_at: "2026-02-03T07:50:55Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: b4d5f5ecbab6f70597cf1e1f9cc5f7f54681253bd747442db16cc681203b5813
-  source_path: nodes/camera.md
-  workflow: 15
----
-
-# 相机捕获（智能体）
-
-Symi 支持用于智能体工作流的**相机捕获**：
-
-- **iOS 节点**（通过 Gateway 网关配对）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
-- **Android 节点**（通过 Gateway 网关配对）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
-- **macOS 应用**（通过 Gateway 网关的节点）：通过 `node.invoke` 捕获**照片**（`jpg`）或**短视频片段**（`mp4`，可选音频）。
-
-所有相机访问都受**用户控制的设置**限制。
-
-## iOS 节点
-
-### 用户设置（默认开启）
-
-- iOS 设置标签页 → **相机** → **允许相机**（`camera.enabled`）
-  - 默认：**开启**（缺少键时视为启用）。
-  - 关闭时：`camera.*` 命令返回 `CAMERA_DISABLED`。
-
-### 命令（通过 Gateway 网关 `node.invoke`）
-
-- `camera.list`
-  - 响应载荷：
-    - `devices`：`{ id, name, position, deviceType }` 数组
-
-- `camera.snap`
-  - 参数：
-    - `facing`：`front|back`（默认：`front`）
-    - `maxWidth`：数字（可选；iOS 节点默认 `1600`）
-    - `quality`：`0..1`（可选；默认 `0.9`）
-    - `format`：当前为 `jpg`
-    - `delayMs`：数字（可选；默认 `0`）
-    - `deviceId`：字符串（可选；来自 `camera.list`）
-  - 响应载荷：
-    - `format: "jpg"`
-    - `base64: "<...>"`
-    - `width`、`height`
-  - 载荷保护：照片会重新压缩以保持 base64 载荷小于 5 MB。
-
-- `camera.clip`
-  - 参数：
-    - `facing`：`front|back`（默认：`front`）
-    - `durationMs`：数字（默认 `3000`，上限 `60000`）
-    - `includeAudio`：布尔值（默认 `true`）
-    - `format`：当前为 `mp4`
-    - `deviceId`：字符串（可选；来自 `camera.list`）
-  - 响应载荷：
-    - `format: "mp4"`
-    - `base64: "<...>"`
-    - `durationMs`
-    - `hasAudio`
-
-### 前台要求
-
-与 `canvas.*` 类似，iOS 节点仅允许在**前台**执行 `camera.*` 命令。后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`。
-
-### CLI 辅助工具（临时文件 + MEDIA）
-
-获取附件最简单的方法是通过 CLI 辅助工具，它将解码的媒体写入临时文件并打印 `MEDIA:<path>`。
-
-示例：
-
-```bash
-symi nodes camera snap --node <id>               # default: both front + back (2 MEDIA lines)
-symi nodes camera snap --node <id> --facing front
-symi nodes camera clip --node <id> --duration 3000
-symi nodes camera clip --node <id> --no-audio
-```
-
-注意事项：
-
-- `nodes camera snap` 默认拍摄**两个**方向以给智能体提供两个视角。
-- 输出文件是临时的（在操作系统临时目录中），除非你构建自己的包装器。
-
-## Android 节点
-
-### 用户设置（默认开启）
-
-- Android 设置页 → **相机** → **允许相机**（`camera.enabled`）
-  - 默认：**开启**（缺少键时视为启用）。
-  - 关闭时：`camera.*` 命令返回 `CAMERA_DISABLED`。
-
-### 权限
-
-- Android 需要运行时权限：
-  - `CAMERA` 用于 `camera.snap` 和 `camera.clip`。
-  - `RECORD_AUDIO` 用于 `includeAudio=true` 时的 `camera.clip`。
-
-如果缺少权限，应用会在可能时提示；如果被拒绝，`camera.*` 请求会失败并返回 `*_PERMISSION_REQUIRED` 错误。
-
-### 前台要求
-
-与 `canvas.*` 类似，Android 节点仅允许在**前台**执行 `camera.*` 命令。后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`。
-
-### 载荷保护
-
-照片会重新压缩以保持 base64 载荷小于 5 MB。
-
-## macOS 应用
-
-### 用户设置（默认关闭）
-
-macOS 配套应用暴露一个复选框：
-
-- **设置 → 通用 → 允许相机**（`symi.cameraEnabled`）
-  - 默认：**关闭**
-  - 关闭时：相机请求返回"用户已禁用相机"。
-
-### CLI 辅助工具（节点调用）
-
-使用主 `symi` CLI 在 macOS 节点上调用相机命令。
-
-示例：
-
-```bash
-symi nodes camera list --node <id>            # list camera ids
-symi nodes camera snap --node <id>            # prints MEDIA:<path>
-symi nodes camera snap --node <id> --max-width 1280
-symi nodes camera snap --node <id> --delay-ms 2000
-symi nodes camera snap --node <id> --device-id <id>
-symi nodes camera clip --node <id> --duration 10s          # prints MEDIA:<path>
-symi nodes camera clip --node <id> --duration-ms 3000      # prints MEDIA:<path> (legacy flag)
-symi nodes camera clip --node <id> --device-id <id>
-symi nodes camera clip --node <id> --no-audio
-```
-
-注意事项：
-
-- `symi nodes camera snap` 默认 `maxWidth=1600`，除非被覆盖。
-- 在 macOS 上，`camera.snap` 在预热/曝光稳定后等待 `delayMs`（默认 2000ms）再捕获。
-- 照片载荷会重新压缩以保持 base64 小于 5 MB。
-
-## 安全性 + 实际限制
-
-- 相机和麦克风访问会触发通常的操作系统权限提示（并需要 Info.plist 中的使用说明字符串）。
-- 视频片段有上限（当前 `<= 60s`）以避免过大的节点载荷（base64 开销 + 消息限制）。
-
-## macOS 屏幕视频（操作系统级别）
-
-对于*屏幕*视频（非相机），使用 macOS 配套应用：
-
-```bash
-symi nodes screen record --node <id> --duration 10s --fps 15   # prints MEDIA:<path>
-```
-
-注意事项：
-
-- 需要 macOS **屏幕录制**权限（TCC）。