@symerian/symi 3.0.21 → 3.0.22

package/docs/zh-CN/gateway/local-models.md

@@ -1,157 +0,0 @@
----
-read_when:
-  - 你想从自己的 GPU 机器提供模型服务
-  - 你正在配置 LM Studio 或 OpenAI 兼容代理
-  - 你需要最安全的本地模型指南
-summary: 在本地 LLM 上运行 Symi（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点）
-title: 本地模型
-x-i18n:
-  generated_at: "2026-02-03T07:48:15Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: f72b424c3d8986319868dc4c552596bcd599cc79fab5a57c14bf4f0695c39690
-  source_path: gateway/local-models.md
-  workflow: 15
----
-
-# 本地模型
-
-本地运行是可行的，但 Symi 期望大上下文 + 强大的提示注入防御。小显存会截断上下文并泄露安全性。目标要高：**≥2 台满配 Mac Studio 或同等 GPU 配置（约 $30k+）**。单张 **24 GB** GPU 仅适用于较轻的提示，且延迟更高。使用**你能运行的最大/完整尺寸模型变体**；激进量化或"小型"检查点会增加提示注入风险（参见[安全](/gateway/security)）。
-
-## 推荐：LM Studio + MiniMax M2.1（Responses API，完整尺寸）
-
-当前最佳本地堆栈。在 LM Studio 中加载 MiniMax M2.1，启用本地服务器（默认 `http://127.0.0.1:1234`），并使用 Responses API 将推理与最终文本分开。
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "lmstudio/minimax-m2.1-gs32" },
-      models: {
-        "anthropic/claude-opus-4-5": { alias: "Opus" },
-        "lmstudio/minimax-m2.1-gs32": { alias: "Minimax" },
-      },
-    },
-  },
-  models: {
-    mode: "merge",
-    providers: {
-      lmstudio: {
-        baseUrl: "http://127.0.0.1:1234/v1",
-        apiKey: "lmstudio",
-        api: "openai-responses",
-        models: [
-          {
-            id: "minimax-m2.1-gs32",
-            name: "MiniMax M2.1 GS32",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 196608,
-            maxTokens: 8192,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-**设置清单**
-
-- 安装 LM Studio：https://lmstudio.ai
-- 在 LM Studio 中，下载**可用的最大 MiniMax M2.1 构建**（避免"小型"/重度量化变体），启动服务器，确认 `http://127.0.0.1:1234/v1/models` 列出了它。
-- 保持模型加载；冷加载会增加启动延迟。
-- 如果你的 LM Studio 构建不同，调整 `contextWindow`/`maxTokens`。
-- 对于 WhatsApp，坚持使用 Responses API，这样只发送最终文本。
-
-即使运行本地模型也要保持托管模型的配置；使用 `models.mode: "merge"` 以便备用方案保持可用。
-
-### 混合配置：托管为主，本地备用
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: {
-        primary: "anthropic/claude-sonnet-4-5",
-        fallbacks: ["lmstudio/minimax-m2.1-gs32", "anthropic/claude-opus-4-5"],
-      },
-      models: {
-        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
-        "lmstudio/minimax-m2.1-gs32": { alias: "MiniMax Local" },
-        "anthropic/claude-opus-4-5": { alias: "Opus" },
-      },
-    },
-  },
-  models: {
-    mode: "merge",
-    providers: {
-      lmstudio: {
-        baseUrl: "http://127.0.0.1:1234/v1",
-        apiKey: "lmstudio",
-        api: "openai-responses",
-        models: [
-          {
-            id: "minimax-m2.1-gs32",
-            name: "MiniMax M2.1 GS32",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 196608,
-            maxTokens: 8192,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-### 本地优先，托管作为安全网
-
-交换主要和备用的顺序；保持相同的 providers 块和 `models.mode: "merge"`，这样当本地机器宕机时可以回退到 Sonnet 或 Opus。
-
-### 区域托管/数据路由
-
-- 托管的 MiniMax/Kimi/GLM 变体也存在于 OpenRouter 上，带有区域固定端点（例如，美国托管）。在那里选择区域变体以将流量保持在你选择的管辖区内，同时仍使用 `models.mode: "merge"` 作为 Anthropic/OpenAI 备用。
-- 纯本地仍然是最强的隐私路径；当你需要提供商功能但又想控制数据流时，托管区域路由是折中方案。
-
-## 其他 OpenAI 兼容本地代理
-
-vLLM、LiteLLM、OAI-proxy 或自定义网关都可以工作，只要它们暴露 OpenAI 风格的 `/v1` 端点。用你的端点和模型 ID 替换上面的 provider 块：
-
-```json5
-{
-  models: {
-    mode: "merge",
-    providers: {
-      local: {
-        baseUrl: "http://127.0.0.1:8000/v1",
-        apiKey: "sk-local",
-        api: "openai-responses",
-        models: [
-          {
-            id: "my-local-model",
-            name: "Local Model",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 120000,
-            maxTokens: 8192,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-保持 `models.mode: "merge"` 以便托管模型作为备用保持可用。
-
-## 故障排除
-
-- Gateway 网关能访问代理吗？`curl http://127.0.0.1:1234/v1/models`。
-- LM Studio 模型卸载了？重新加载；冷启动是常见的"卡住"原因。
-- 上下文错误？降低 `contextWindow` 或提高服务器限制。
-- 安全：本地模型跳过提供商端过滤器；保持智能体范围窄并开启压缩以限制提示注入的影响范围。

package/docs/zh-CN/gateway/logging.md

@@ -1,114 +0,0 @@
----
-read_when:
-  - 更改日志输出或格式
-  - 调试 CLI 或 Gateway 网关输出
-summary: 日志输出界面、文件日志、WS 日志样式和控制台格式化
-title: 日志
-x-i18n:
-  generated_at: "2026-02-03T07:48:14Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: efb8eda5e77e3809369a8ff569fac110323a86b3945797093f20e9bc98f39b2e
-  source_path: gateway/logging.md
-  workflow: 15
----
-
-# 日志
-
-面向用户的概览（CLI + Control UI + 配置），请参阅 [/logging](/logging)。
-
-Symi 有两个日志"界面"：
-
-- **控制台输出**（你在终端 / Debug UI 中看到的内容）。
-- **文件日志**（JSON 行）由 Gateway 网关日志记录器写入。
-
-## 基于文件的日志记录器
-
-- 默认滚动日志文件位于 `/tmp/symi/` 下（每天一个文件）：`symi-YYYY-MM-DD.log`
-  - 日期使用 Gateway 网关主机的本地时区。
-- 日志文件路径和级别可以通过 `~/.symi/symi.json` 配置：
-  - `logging.file`
-  - `logging.level`
-
-文件格式是每行一个 JSON 对象。
-
-Control UI 的 Logs 标签页通过 Gateway 网关（`logs.tail`）尾随此文件。CLI 也可以这样做：
-
-```bash
-symi logs --follow
-```
-
-**Verbose 与日志级别**
-
-- **文件日志**完全由 `logging.level` 控制。
-- `--verbose` 仅影响**控制台详细程度**（和 WS 日志样式）；它**不会**提高文件日志级别。
-- 要在文件日志中捕获仅 verbose 的详细信息，请将 `logging.level` 设置为 `debug` 或 `trace`。
-
-## 控制台捕获
-
-CLI 捕获 `console.log/info/warn/error/debug/trace` 并将它们写入文件日志，同时仍打印到 stdout/stderr。
-
-你可以独立调整控制台详细程度：
-
-- `logging.consoleLevel`（默认 `info`）
-- `logging.consoleStyle`（`pretty` | `compact` | `json`）
-
-## 工具摘要脱敏
-
-详细工具摘要（例如 `🛠️ Exec: ...`）可以在进入控制台流之前屏蔽敏感令牌。这**仅限工具**，不会更改文件日志。
-
-- `logging.redactSensitive`：`off` | `tools`（默认：`tools`）
-- `logging.redactPatterns`：正则表达式字符串数组（覆盖默认值）
-  - 使用原始正则字符串（自动 `gi`），或如果你需要自定义标志则使用 `/pattern/flags`。
-  - 匹配项通过保留前 6 个 + 后 4 个字符（长度 >= 18）来屏蔽，否则为 `***`。
-  - 默认值涵盖常见的键赋值、CLI 标志、JSON 字段、bearer 头、PEM 块和流行的令牌前缀。
-
-## Gateway 网关 WebSocket 日志
-
-Gateway 网关以两种模式打印 WebSocket 协议日志：
-
-- **普通模式（无 `--verbose`）**：仅打印"有趣的"RPC 结果：
-  - 错误（`ok=false`）
-  - 慢调用（默认阈值：`>= 50ms`）
-  - 解析错误
-- **详细模式（`--verbose`）**：打印所有 WS 请求/响应流量。
-
-### WS 日志样式
-
-`symi gateway` 支持每个 Gateway 网关的样式切换：
-
-- `--ws-log auto`（默认）：普通模式已优化；详细模式使用紧凑输出
-- `--ws-log compact`：详细时使用紧凑输出（配对的请求/响应）
-- `--ws-log full`：详细时使用完整的每帧输出
-- `--compact`：`--ws-log compact` 的别名
-
-示例：
-
-```bash
-# 优化的（仅错误/慢调用）
-symi gateway
-
-# 显示所有 WS 流量（配对）
-symi gateway --verbose --ws-log compact
-
-# 显示所有 WS 流量（完整元数据）
-symi gateway --verbose --ws-log full
-```
-
-## 控制台格式化（子系统日志）
-
-控制台格式化器是 **TTY 感知的**，打印一致的带前缀行。子系统日志记录器保持输出分组且易于扫描。
-
-行为：
-
-- 每行都有**子系统前缀**（例如 `[gateway]`、`[canvas]`、`[tailscale]`）
-- **子系统颜色**（每个子系统稳定）加上级别着色
-- **当输出是 TTY 或环境看起来像富终端时着色**（`TERM`/`COLORTERM`/`TERM_PROGRAM`），遵守 `NO_COLOR`
-- **缩短的子系统前缀**：删除前导 `gateway/` + `channels/`，保留最后 2 个段（例如 `whatsapp/outbound`）
-- **按子系统的子日志记录器**（自动前缀 + 结构化字段 `{ subsystem }`）
-- **`logRaw()`** 用于 QR/UX 输出（无前缀，无格式化）
-- **控制台样式**（例如 `pretty | compact | json`）
-- **控制台日志级别**与文件日志级别分开（当 `logging.level` 设置为 `debug`/`trace` 时，文件保留完整详情）
-- **WhatsApp 消息正文**以 `debug` 级别记录（使用 `--verbose` 查看它们）
-
-这保持现有文件日志稳定，同时使交互式输出易于扫描。

package/docs/zh-CN/gateway/multiple-gateways.md

@@ -1,119 +0,0 @@
----
-read_when:
-  - 在同一台机器上运行多个 Gateway 网关
-  - 你需要每个 Gateway 网关有隔离的配置/状态/端口
-summary: 在同一主机上运行多个 Symi Gateway 网关（隔离、端口和配置文件）
-title: 多 Gateway 网关
-x-i18n:
-  generated_at: "2026-02-03T07:48:13Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 09b5035d4e5fb97c8d4596f7e23dea67224dad3b6d9e2c37ecb99840f28bd77d
-  source_path: gateway/multiple-gateways.md
-  workflow: 15
----
-
-# 多 Gateway 网关（同一主机）
-
-大多数设置应该使用单个 Gateway 网关，因为一个 Gateway 网关可以处理多个消息连接和智能体。如果你需要更强的隔离或冗余（例如，救援机器人），请使用隔离的配置文件/端口运行多个 Gateway 网关。
-
-## 隔离检查清单（必需）
-
-- `SYMI_CONFIG_PATH` — 每个实例的配置文件
-- `SYMI_STATE_DIR` — 每个实例的会话、凭证、缓存
-- `agents.defaults.workspace` — 每个实例的工作区根目录
-- `gateway.port`（或 `--port`）— 每个实例唯一
-- 派生端口（浏览器/画布）不得重叠
-
-如果这些是共享的，你将遇到配置竞争和端口冲突。
-
-## 推荐：配置文件（`--profile`）
-
-配置文件自动限定 `SYMI_STATE_DIR` + `SYMI_CONFIG_PATH` 范围并为服务名称添加后缀。
-
-```bash
-# main
-symi --profile main setup
-symi --profile main gateway --port 18789
-
-# rescue
-symi --profile rescue setup
-symi --profile rescue gateway --port 19001
-```
-
-按配置文件的服务：
-
-```bash
-symi --profile main gateway install
-symi --profile rescue gateway install
-```
-
-## 救援机器人指南
-
-在同一主机上运行第二个 Gateway 网关，使用独立的：
-
-- 配置文件/配置
-- 状态目录
-- 工作区
-- 基础端口（加上派生端口）
-
-这使救援机器人与主机器人隔离，以便在主机器人宕机时可以调试或应用配置更改。
-
-端口间距：在基础端口之间至少留出 20 个端口，这样派生的浏览器/画布/CDP 端口永远不会冲突。
-
-### 如何安装（救援机器人）
-
-```bash
-# 主机器人（现有或新建，不带 --profile 参数）
-# 运行在端口 18789 + Chrome CDC/Canvas/... 端口
-symi onboard
-symi gateway install
-
-# 救援机器人（隔离的配置文件 + 端口）
-symi --profile rescue onboard
-# 注意：
-# - 工作区名称默认会添加 -rescue 后缀
-# - 端口应至少为 18789 + 20 个端口，
-#   最好选择完全不同的基础端口，如 19789，
-# - 其余的新手引导与正常相同
-
-# 安装服务（如果在新手引导期间没有自动完成）
-symi --profile rescue gateway install
-```
-
-## 端口映射（派生）
-
-基础端口 = `gateway.port`（或 `SYMI_GATEWAY_PORT` / `--port`）。
-
-- 浏览器控制服务端口 = 基础 + 2（仅 loopback）
-- `canvasHost.port = 基础 + 4`
-- 浏览器配置文件 CDP 端口从 `browser.controlPort + 9 .. + 108` 自动分配
-
-如果你在配置或环境变量中覆盖了这些，必须确保每个实例都唯一。
-
-## 浏览器/CDP 注意事项（常见陷阱）
-
-- **不要**在多个实例上将 `browser.cdpUrl` 固定为相同的值。
-- 每个实例需要自己的浏览器控制端口和 CDP 范围（从其 Gateway 网关端口派生）。
-- 如果你需要显式的 CDP 端口，请为每个实例设置 `browser.profiles.<name>.cdpPort`。
-- 远程 Chrome：使用 `browser.profiles.<name>.cdpUrl`（每个配置文件，每个实例）。
-
-## 手动环境变量示例
-
-```bash
-SYMI_CONFIG_PATH=~/.symi/main.json \
-SYMI_STATE_DIR=~/.symi-main \
-symi gateway --port 18789
-
-SYMI_CONFIG_PATH=~/.symi/rescue.json \
-SYMI_STATE_DIR=~/.symi-rescue \
-symi gateway --port 19001
-```
-
-## 快速检查
-
-```bash
-symi --profile main status
-symi --profile rescue status
-symi --profile rescue browser status
-```

package/docs/zh-CN/gateway/network-model.md

@@ -1,23 +0,0 @@
----
-read_when:
-  - 你想要简要了解 Gateway 网关的网络模型
-summary: Gateway 网关、节点和 canvas 主机如何连接。
-title: 网络模型
-x-i18n:
-  generated_at: "2026-02-04T17:53:21Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: e3508b884757ef19f425c82e891e2b07e7fd7d985413d569e55ae9b175c91f0f
-  source_path: gateway/network-model.md
-  workflow: 15
----
-
-大多数操作通过 Gateway 网关（`symi gateway`）进行，它是一个长期运行的单一进程，负责管理渠道连接和 WebSocket 控制平面。
-
-## 核心规则
-
-- 建议每台主机运行一个 Gateway 网关。它是唯一允许拥有 WhatsApp Web 会话的进程。对于救援机器人或严格隔离的场景，可以使用隔离的配置文件和端口运行多个 Gateway 网关。参见[多 Gateway 网关](/gateway/multiple-gateways)。
-- 优先使用回环地址：Gateway 网关的 WS 默认为 `ws://127.0.0.1:18789`。即使是回环连接，向导也会默认生成 gateway token。若需通过 tailnet 访问，请运行 `symi gateway --bind tailnet --token ...`，因为非回环绑定必须使用 token。
-- 节点根据需要通过局域网、tailnet 或 SSH 连接到 Gateway 网关的 WS。旧版 TCP 桥接已弃用。
-- Canvas 主机是一个 HTTP 文件服务器，运行在 `canvasHost.port`（默认 `18793`）上，提供 `/__symi__/canvas/` 路径供节点 WebView 使用。参见 [Gateway 网关配置](/gateway/configuration)（`canvasHost`）。
-- 远程使用通常通过 SSH 隧道或 Tailscale VPN。参见[远程访问](/gateway/remote)和[设备发现](/gateway/discovery)。

package/docs/zh-CN/gateway/openai-http-api.md

@@ -1,125 +0,0 @@
----
-read_when:
-  - 集成需要 OpenAI Chat Completions 的工具
-summary: 从 Gateway 网关暴露 OpenAI 兼容的 /v1/chat/completions HTTP 端点
-title: OpenAI Chat Completions
-x-i18n:
-  generated_at: "2026-02-03T07:48:15Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 6f935777f489bff925a3bf18b1e4b7493f83ae7b1e581890092e5779af59b732
-  source_path: gateway/openai-http-api.md
-  workflow: 15
----
-
-# OpenAI Chat Completions（HTTP）
-
-Symi 的 Gateway 网关可以提供一个小型的 OpenAI 兼容 Chat Completions 端点。
-
-此端点**默认禁用**。请先在配置中启用它。
-
-- `POST /v1/chat/completions`
-- 与 Gateway 网关相同的端口（WS + HTTP 多路复用）：`http://<gateway-host>:<port>/v1/chat/completions`
-
-底层实现中，请求作为普通的 Gateway 网关智能体运行执行（与 `symi agent` 相同的代码路径），因此路由/权限/配置与你的 Gateway 网关一致。
-
-## 认证
-
-使用 Gateway 网关认证配置。发送 bearer 令牌：
-
-- `Authorization: Bearer <token>`
-
-注意事项：
-
-- 当 `gateway.auth.mode="token"` 时，使用 `gateway.auth.token`（或 `SYMI_GATEWAY_TOKEN`）。
-- 当 `gateway.auth.mode="password"` 时，使用 `gateway.auth.password`（或 `SYMI_GATEWAY_PASSWORD`）。
-
-## 选择智能体
-
-无需自定义头：在 OpenAI `model` 字段中编码智能体 ID：
-
-- `model: "symi:<agentId>"`（例如：`"symi:main"`、`"symi:beta"`）
-- `model: "agent:<agentId>"`（别名）
-
-或通过头指定特定的 Symi 智能体：
-
-- `x-symi-agent-id: <agentId>`（默认：`main`）
-
-高级选项：
-
-- `x-symi-session-key: <sessionKey>` 完全控制会话路由。
-
-## 启用端点
-
-将 `gateway.http.endpoints.chatCompletions.enabled` 设置为 `true`：
-
-```json5
-{
-  gateway: {
-    http: {
-      endpoints: {
-        chatCompletions: { enabled: true },
-      },
-    },
-  },
-}
-```
-
-## 禁用端点
-
-将 `gateway.http.endpoints.chatCompletions.enabled` 设置为 `false`：
-
-```json5
-{
-  gateway: {
-    http: {
-      endpoints: {
-        chatCompletions: { enabled: false },
-      },
-    },
-  },
-}
-```
-
-## 会话行为
-
-默认情况下，端点是**每请求无状态**的（每次调用生成新的会话键）。
-
-如果请求包含 OpenAI `user` 字符串，Gateway 网关会从中派生一个稳定的会话键，因此重复调用可以共享智能体会话。
-
-## 流式传输（SSE）
-
-设置 `stream: true` 以接收 Server-Sent Events（SSE）：
-
-- `Content-Type: text/event-stream`
-- 每个事件行是 `data: <json>`
-- 流以 `data: [DONE]` 结束
-
-## 示例
-
-非流式：
-
-```bash
-curl -sS http://127.0.0.1:18789/v1/chat/completions \
-  -H 'Authorization: Bearer YOUR_TOKEN' \
-  -H 'Content-Type: application/json' \
-  -H 'x-symi-agent-id: main' \
-  -d '{
-    "model": "symi",
-    "messages": [{"role":"user","content":"hi"}]
-  }'
-```
-
-流式：
-
-```bash
-curl -N http://127.0.0.1:18789/v1/chat/completions \
-  -H 'Authorization: Bearer YOUR_TOKEN' \
-  -H 'Content-Type: application/json' \
-  -H 'x-symi-agent-id: main' \
-  -d '{
-    "model": "symi",
-    "stream": true,
-    "messages": [{"role":"user","content":"hi"}]
-  }'
-```