@symerian/symi 3.0.20 → 3.0.22

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

@@ -1,79 +0,0 @@
----
-read_when:
-  - 修改媒体管道或附件
-summary: 发送、Gateway 网关和智能体回复的图像和媒体处理规则
-title: 图像和媒体支持
-x-i18n:
-  generated_at: "2026-02-03T07:50:42Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 971aed398ea01078efbad7a8a4bca17f2a975222a2c4db557565e4334c9450e0
-  source_path: nodes/images.md
-  workflow: 15
----
-
-# 图像与媒体支持 — 2025-12-05
-
-WhatsApp 渠道通过 **Baileys Web** 运行。本文档记录了发送、Gateway 网关和智能体回复的当前媒体处理规则。
-
-## 目标
-
-- 通过 `symi message send --media` 发送带可选标题的媒体。
-- 允许来自网页收件箱的自动回复在文本旁边包含媒体。
-- 保持每种类型的限制合理且可预测。
-
-## CLI 接口
-
-- `symi message send --media <path-or-url> [--message <caption>]`
-  - `--media` 可选；标题可以为空以进行纯媒体发送。
-  - `--dry-run` 打印解析后的负载；`--json` 输出 `{ channel, to, messageId, mediaUrl, caption }`。
-
-## WhatsApp Web 渠道行为
-
-- 输入：本地文件路径**或** HTTP(S) URL。
-- 流程：加载到 Buffer，检测媒体类型，并构建正确的负载：
-  - **图像：** 调整大小并重新压缩为 JPEG（最大边 2048px），目标为 `agents.defaults.mediaMaxMb`（默认 5 MB），上限 6 MB。
-  - **音频/语音/视频：** 直通最大 16 MB；音频作为语音消息发送（`ptt: true`）。
-  - **文档：** 其他任何内容，最大 100 MB，可用时保留文件名。
-- WhatsApp GIF 风格播放：发送带 `gifPlayback: true` 的 MP4（CLI：`--gif-playback`），使移动客户端内联循环播放。
-- MIME 检测优先使用魔数字节，然后是头信息，最后是文件扩展名。
-- 标题来自 `--message` 或 `reply.text`；允许空标题。
-- 日志：非详细模式显示 `↩️`/`✅`；详细模式包含大小和源路径/URL。
-
-## 自动回复管道
-
-- `getReplyFromConfig` 返回 `{ text?, mediaUrl?, mediaUrls? }`。
-- 当存在媒体时，网页发送器使用与 `symi message send` 相同的管道解析本地路径或 URL。
-- 如果提供多个媒体条目，则按顺序发送。
-
-## 入站媒体到命令（Pi）
-
-- 当入站网页消息包含媒体时，Symi 下载到临时文件并暴露模板变量：
-  - `{{MediaUrl}}` 入站媒体的伪 URL。
-  - `{{MediaPath}}` 运行命令前写入的本地临时路径。
-- 当启用每会话 Docker 沙箱时，入站媒体被复制到沙箱工作区，`MediaPath`/`MediaUrl` 被重写为相对路径如 `media/inbound/<filename>`。
-- 媒体理解（如果通过 `tools.media.*` 或共享的 `tools.media.models` 配置）在模板化之前运行，可以将 `[Image]`、`[Audio]` 和 `[Video]` 块插入 `Body`。
-  - 音频设置 `{{Transcript}}` 并使用转录进行命令解析，因此斜杠命令仍然有效。
-  - 视频和图像描述保留任何标题文本用于命令解析。
-- 默认情况下只处理第一个匹配的图像/音频/视频附件；设置 `tools.media.<cap>.attachments` 以处理多个附件。
-
-## 限制与错误
-
-**出站发送上限（WhatsApp 网页发送）**
-
-- 图像：重新压缩后约 6 MB 上限。
-- 音频/语音/视频：16 MB 上限；文档：100 MB 上限。
-- 超大或无法读取的媒体 → 日志中有明确错误，回复被跳过。
-
-**媒体理解上限（转录/描述）**
-
-- 图像默认：10 MB（`tools.media.image.maxBytes`）。
-- 音频默认：20 MB（`tools.media.audio.maxBytes`）。
-- 视频默认：50 MB（`tools.media.video.maxBytes`）。
-- 超大媒体跳过理解，但回复仍然使用原始正文通过。
-
-## 测试说明
-
-- 覆盖图像/音频/文档情况的发送 + 回复流程。
-- 验证图像的重新压缩（大小限制）和音频的语音消息标志。
-- 确保多媒体回复作为顺序发送扇出。

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

@@ -1,348 +0,0 @@
----
-read_when:
-  - 将 iOS/Android 节点配对到 Gateway 网关时
-  - 使用节点 canvas/camera 为智能体提供上下文时
-  - 添加新的节点命令或 CLI 辅助工具时
-summary: 节点：配对、能力、权限以及 canvas/camera/screen/system 的 CLI 辅助工具
-title: 节点
-x-i18n:
-  generated_at: "2026-02-03T07:51:55Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 74e9420f61c653e4ceeb00f5a27e4266bd1c7715c1000edd969c3ee185e74de9
-  source_path: nodes/index.md
-  workflow: 15
----
-
-# 节点
-
-**节点**是一个配套设备（macOS/iOS/Android/无头），它以 `role: "node"` 连接到 Gateway 网关 **WebSocket**（与操作员相同的端口），并通过 `node.invoke` 暴露命令接口（例如 `canvas.*`、`camera.*`、`system.*`）。协议详情：[Gateway 网关协议](/gateway/protocol)。
-
-旧版传输：[Bridge 协议](/gateway/bridge-protocol)（TCP JSONL；当前节点已弃用/移除）。
-
-macOS 也可以在**节点模式**下运行：菜单栏应用连接到 Gateway 网关的 WS 服务器，并将其本地 canvas/camera 命令作为节点暴露（因此 `symi nodes …` 可以针对这台 Mac 工作）。
-
-注意事项：
-
-- 节点是**外围设备**，不是 Gateway 网关。它们不运行 Gateway 网关服务。
-- Telegram/WhatsApp 等消息落在 **Gateway 网关**上，而不是节点上。
-
-## 配对 + 状态
-
-**WS 节点使用设备配对。** 节点在 `connect` 期间呈现设备身份；Gateway 网关
-为 `role: node` 创建设备配对请求。通过设备 CLI（或 UI）批准。
-
-快速 CLI：
-
-```bash
-symi devices list
-symi devices approve <requestId>
-symi devices reject <requestId>
-symi nodes status
-symi nodes describe --node <idOrNameOrIp>
-```
-
-注意事项：
-
-- 当节点的设备配对角色包含 `node` 时，`nodes status` 将节点标记为**已配对**。
-- `node.pair.*`（CLI：`symi nodes pending/approve/reject`）是一个单独的 Gateway 网关拥有的
-  节点配对存储；它**不会**限制 WS `connect` 握手。
-
-## 远程节点主机（system.run）
-
-当你的 Gateway 网关在一台机器上运行而你希望命令
-在另一台机器上执行时，使用**节点主机**。模型仍然与 **Gateway 网关**通信；当选择 `host=node` 时，Gateway 网关
-将 `exec` 调用转发到**节点主机**。
-
-### 什么在哪里运行
-
-- **Gateway 网关主机**：接收消息，运行模型，路由工具调用。
-- **节点主机**：在节点机器上执行 `system.run`/`system.which`。
-- **批准**：通过 `~/.symi/exec-approvals.json` 在节点主机上执行。
-
-### 启动节点主机（前台）
-
-在节点机器上：
-
-```bash
-symi node run --host <gateway-host> --port 18789 --display-name "Build Node"
-```
-
-### 通过 SSH 隧道访问远程 Gateway 网关（loopback 绑定）
-
-如果 Gateway 网关绑定到 loopback（`gateway.bind=loopback`，本地模式下的默认值），
-远程节点主机无法直接连接。创建 SSH 隧道并将
-节点主机指向隧道的本地端。
-
-示例（节点主机 -> Gateway 网关主机）：
-
-```bash
-# 终端 A（保持运行）：转发本地 18790 -> Gateway 网关 127.0.0.1:18789
-ssh -N -L 18790:127.0.0.1:18789 user@gateway-host
-
-# 终端 B：导出 Gateway 网关令牌并通过隧道连接
-export SYMI_GATEWAY_TOKEN="<gateway-token>"
-symi node run --host 127.0.0.1 --port 18790 --display-name "Build Node"
-```
-
-注意事项：
-
-- 令牌是 Gateway 网关配置中的 `gateway.auth.token`（Gateway 网关主机上的 `~/.symi/symi.json`）。
-- `symi node run` 读取 `SYMI_GATEWAY_TOKEN` 进行认证。
-
-### 启动节点主机（服务）
-
-```bash
-symi node install --host <gateway-host> --port 18789 --display-name "Build Node"
-symi node restart
-```
-
-### 配对 + 命名
-
-在 Gateway 网关主机上：
-
-```bash
-symi nodes pending
-symi nodes approve <requestId>
-symi nodes list
-```
-
-命名选项：
-
-- 在 `symi node run` / `symi node install` 上使用 `--display-name`（持久化在节点上的 `~/.symi/node.json` 中）。
-- `symi nodes rename --node <id|name|ip> --name "Build Node"`（Gateway 网关覆盖）。
-
-### 将命令加入允许列表
-
-Exec 批准是**每个节点主机**的。从 Gateway 网关添加允许列表条目：
-
-```bash
-symi approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
-symi approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"
-```
-
-批准存储在节点主机的 `~/.symi/exec-approvals.json` 中。
-
-### 将 exec 指向节点
-
-配置默认值（Gateway 网关配置）：
-
-```bash
-symi config set tools.exec.host node
-symi config set tools.exec.security allowlist
-symi config set tools.exec.node "<id-or-name>"
-```
-
-或按会话：
-
-```
-/exec host=node security=allowlist node=<id-or-name>
-```
-
-设置后，任何带有 `host=node` 的 `exec` 调用都会在节点主机上运行（受
-节点允许列表/批准约束）。
-
-相关：
-
-- [节点主机 CLI](/cli/node)
-- [Exec 工具](/tools/exec)
-- [Exec 批准](/tools/exec-approvals)
-
-## 调用命令
-
-低级（原始 RPC）：
-
-```bash
-symi nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'
-```
-
-对于常见的"给智能体一个 MEDIA 附件"工作流，存在更高级的辅助工具。
-
-## 截图（canvas 快照）
-
-如果节点正在显示 Canvas（WebView），`canvas.snapshot` 返回 `{ format, base64 }`。
-
-CLI 辅助工具（写入临时文件并打印 `MEDIA:<path>`）：
-
-```bash
-symi nodes canvas snapshot --node <idOrNameOrIp> --format png
-symi nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9
-```
-
-### Canvas 控制
-
-```bash
-symi nodes canvas present --node <idOrNameOrIp> --target https://example.com
-symi nodes canvas hide --node <idOrNameOrIp>
-symi nodes canvas navigate https://example.com --node <idOrNameOrIp>
-symi nodes canvas eval --node <idOrNameOrIp> --js "document.title"
-```
-
-注意事项：
-
-- `canvas present` 接受 URL 或本地文件路径（`--target`），以及可选的 `--x/--y/--width/--height` 用于定位。
-- `canvas eval` 接受内联 JS（`--js`）或位置参数。
-
-### A2UI（Canvas）
-
-```bash
-symi nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
-symi nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
-symi nodes canvas a2ui reset --node <idOrNameOrIp>
-```
-
-注意事项：
-
-- 仅支持 A2UI v0.8 JSONL（v0.9/createSurface 被拒绝）。
-
-## 照片 + 视频（节点相机）
-
-照片（`jpg`）：
-
-```bash
-symi nodes camera list --node <idOrNameOrIp>
-symi nodes camera snap --node <idOrNameOrIp>            # 默认：两个朝向（2 个 MEDIA 行）
-symi nodes camera snap --node <idOrNameOrIp> --facing front
-```
-
-视频片段（`mp4`）：
-
-```bash
-symi nodes camera clip --node <idOrNameOrIp> --duration 10s
-symi nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio
-```
-
-注意事项：
-
-- 节点必须处于**前台**才能使用 `canvas.*` 和 `camera.*`（后台调用返回 `NODE_BACKGROUND_UNAVAILABLE`）。
-- 片段时长被限制（当前 `<= 60s`）以避免过大的 base64 负载。
-- Android 会在可能时提示 `CAMERA`/`RECORD_AUDIO` 权限；权限被拒绝会以 `*_PERMISSION_REQUIRED` 失败。
-
-## 屏幕录制（节点）
-
-节点暴露 `screen.record`（mp4）。示例：
-
-```bash
-symi nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
-symi nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio
-```
-
-注意事项：
-
-- `screen.record` 需要节点应用处于前台。
-- Android 会在录制前显示系统屏幕捕获提示。
-- 屏幕录制被限制为 `<= 60s`。
-- `--no-audio` 禁用麦克风捕获（iOS/Android 支持；macOS 使用系统捕获音频）。
-- 当有多个屏幕可用时，使用 `--screen <index>` 选择显示器。
-
-## 位置（节点）
-
-当在设置中启用位置时，节点暴露 `location.get`。
-
-CLI 辅助工具：
-
-```bash
-symi nodes location get --node <idOrNameOrIp>
-symi nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000
-```
-
-注意事项：
-
-- 位置**默认关闭**。
-- "始终"需要系统权限；后台获取是尽力而为的。
-- 响应包括纬度/经度、精度（米）和时间戳。
-
-## 短信（Android 节点）
-
-当用户授予 **SMS** 权限且设备支持电话功能时，Android 节点可以暴露 `sms.send`。
-
-低级调用：
-
-```bash
-symi nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from Symi"}'
-```
-
-注意事项：
-
-- 在能力被广播之前，必须在 Android 设备上接受权限提示。
-- 没有电话功能的纯 Wi-Fi 设备不会广播 `sms.send`。
-
-## 系统命令（节点主机 / mac 节点）
-
-macOS 节点暴露 `system.run`、`system.notify` 和 `system.execApprovals.get/set`。
-无头节点主机暴露 `system.run`、`system.which` 和 `system.execApprovals.get/set`。
-
-示例：
-
-```bash
-symi nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
-symi nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
-```
-
-注意事项：
-
-- `system.run` 在负载中返回 stdout/stderr/退出码。
-- `system.notify` 遵守 macOS 应用上的通知权限状态。
-- `system.run` 支持 `--cwd`、`--env KEY=VAL`、`--command-timeout` 和 `--needs-screen-recording`。
-- `system.notify` 支持 `--priority <passive|active|timeSensitive>` 和 `--delivery <system|overlay|auto>`。
-- macOS 节点会丢弃 `PATH` 覆盖；无头节点主机仅在 `PATH` 前置到节点主机 PATH 时才接受它。
-- 在 macOS 节点模式下，`system.run` 受 macOS 应用中的 exec 批准限制（设置 → Exec 批准）。
-  Ask/allowlist/full 的行为与无头节点主机相同；被拒绝的提示返回 `SYSTEM_RUN_DENIED`。
-- 在无头节点主机上，`system.run` 受 exec 批准限制（`~/.symi/exec-approvals.json`）。
-
-## Exec 节点绑定
-
-当有多个节点可用时，你可以将 exec 绑定到特定节点。
-这设置了 `exec host=node` 的默认节点（可以按智能体覆盖）。
-
-全局默认：
-
-```bash
-symi config set tools.exec.node "node-id-or-name"
-```
-
-按智能体覆盖：
-
-```bash
-symi config get agents.list
-symi config set agents.list[0].tools.exec.node "node-id-or-name"
-```
-
-取消设置以允许任何节点：
-
-```bash
-symi config unset tools.exec.node
-symi config unset agents.list[0].tools.exec.node
-```
-
-## 权限映射
-
-节点可能在 `node.list` / `node.describe` 中包含 `permissions` 映射，按权限名称（例如 `screenRecording`、`accessibility`）键入，值为布尔值（`true` = 已授予）。
-
-## 无头节点主机（跨平台）
-
-Symi 可以运行**无头节点主机**（无 UI），它连接到 Gateway 网关
-WebSocket 并暴露 `system.run` / `system.which`。这在 Linux/Windows
-上或在服务器旁运行最小节点时很有用。
-
-启动它：
-
-```bash
-symi node run --host <gateway-host> --port 18789
-```
-
-注意事项：
-
-- 仍然需要配对（Gateway 网关会显示节点批准提示）。
-- 节点主机将其节点 id、令牌、显示名称和 Gateway 网关连接信息存储在 `~/.symi/node.json` 中。
-- Exec 批准通过 `~/.symi/exec-approvals.json` 在本地执行
-  （参见 [Exec 批准](/tools/exec-approvals)）。
-- 在 macOS 上，当配套应用 exec 主机可达时，无头节点主机优先使用它，
-  如果应用不可用则回退到本地执行。设置 `SYMI_NODE_EXEC_HOST=app` 要求
-  使用应用，或设置 `SYMI_NODE_EXEC_FALLBACK=0` 禁用回退。
-- 当 Gateway 网关 WS 使用 TLS 时，添加 `--tls` / `--tls-fingerprint`。
-
-## Mac 节点模式
-
-- macOS 菜单栏应用作为节点连接到 Gateway 网关 WS 服务器（因此 `symi nodes …` 可以针对这台 Mac 工作）。
-- 在远程模式下，应用为 Gateway 网关端口打开 SSH 隧道并连接到 `localhost`。

package/docs/zh-CN/nodes/location-command.md

@@ -1,120 +0,0 @@
----
-read_when:
-  - 添加位置节点支持或权限 UI
-  - 设计后台位置 + 推送流程
-summary: 节点的位置命令（location.get）、权限模式和后台行为
-title: 位置命令
-x-i18n:
-  generated_at: "2026-02-03T07:50:59Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 23124096256384d2b28157352b072309c61c970a20e009aac5ce4a8250dc3764
-  source_path: nodes/location-command.md
-  workflow: 15
----
-
-# 位置命令（节点）
-
-## 简要概述
-
-- `location.get` 是一个节点命令（通过 `node.invoke`）。
-- 默认关闭。
-- 设置使用选择器：关闭 / 使用时 / 始终。
-- 单独的开关：精确位置。
-
-## 为什么用选择器（而不只是开关）
-
-操作系统权限是多级的。我们可以在应用内暴露选择器，但操作系统仍然决定实际授权。
-
-- iOS/macOS：用户可以在系统提示/设置中选择**使用时**或**始终**。应用可以请求升级，但操作系统可能要求进入设置。
-- Android：后台位置是单独的权限；在 Android 10+ 上通常需要进入设置流程。
-- 精确位置是单独的授权（iOS 14+ "精确"，Android "精细" vs "粗略"）。
-
-UI 中的选择器驱动我们请求的模式；实际授权存在于操作系统设置中。
-
-## 设置模型
-
-每个节点设备：
-
-- `location.enabledMode`：`off | whileUsing | always`
-- `location.preciseEnabled`：bool
-
-UI 行为：
-
-- 选择 `whileUsing` 请求前台权限。
-- 选择 `always` 首先确保 `whileUsing`，然后请求后台（或在需要时将用户引导到设置）。
-- 如果操作系统拒绝请求的级别，回退到已授予的最高级别并显示状态。
-
-## 权限映射（node.permissions）
-
-可选。macOS 节点通过权限映射报告 `location`；iOS/Android 可能省略它。
-
-## 命令：`location.get`
-
-通过 `node.invoke` 调用。
-
-参数（建议）：
-
-```json
-{
-  "timeoutMs": 10000,
-  "maxAgeMs": 15000,
-  "desiredAccuracy": "coarse|balanced|precise"
-}
-```
-
-响应负载：
-
-```json
-{
-  "lat": 48.20849,
-  "lon": 16.37208,
-  "accuracyMeters": 12.5,
-  "altitudeMeters": 182.0,
-  "speedMps": 0.0,
-  "headingDeg": 270.0,
-  "timestamp": "2026-01-03T12:34:56.000Z",
-  "isPrecise": true,
-  "source": "gps|wifi|cell|unknown"
-}
-```
-
-错误（稳定代码）：
-
-- `LOCATION_DISABLED`：选择器已关闭。
-- `LOCATION_PERMISSION_REQUIRED`：缺少请求模式的权限。
-- `LOCATION_BACKGROUND_UNAVAILABLE`：应用在后台但只允许使用时。
-- `LOCATION_TIMEOUT`：在时间内没有定位。
-- `LOCATION_UNAVAILABLE`：系统故障/没有提供商。
-
-## 后台行为（未来）
-
-目标：模型可以在节点处于后台时请求位置，但仅当：
-
-- 用户选择了**始终**。
-- 操作系统授予后台位置权限。
-- 应用被允许在后台运行以获取位置（iOS 后台模式/Android 前台服务或特殊许可）。
-
-推送触发流程（未来）：
-
-1. Gateway 网关向节点发送推送（静默推送或 FCM 数据）。
-2. 节点短暂唤醒并从设备请求位置。
-3. 节点将负载转发给 Gateway 网关。
-
-说明：
-
-- iOS：需要始终权限 + 后台位置模式。静默推送可能被限流；预期会有间歇性失败。
-- Android：后台位置可能需要前台服务；否则预期会被拒绝。
-
-## 模型/工具集成
-
-- 工具接口：`nodes` 工具添加 `location_get` 操作（需要节点）。
-- CLI：`symi nodes location get --node <id>`。
-- 智能体指南：仅在用户启用位置并理解范围时调用。
-
-## UX 文案（建议）
-
-- 关闭："位置共享已禁用。"
-- 使用时："仅当 Symi 打开时。"
-- 始终："允许后台位置。需要系统权限。"
-- 精确："使用精确 GPS 位置。关闭以共享大致位置。"