@symerian/symi 3.0.20 → 3.0.22

package/docs/zh-CN/gateway/bridge-protocol.md

@@ -1,86 +0,0 @@
----
-read_when:
-  - 构建或调试节点客户端（iOS/Android/macOS 节点模式）
-  - 调查配对或 bridge 认证失败
-  - 审计 Gateway 网关暴露的节点接口
-summary: Bridge 协议（旧版节点）：TCP JSONL、配对、作用域 RPC
-title: Bridge 协议
-x-i18n:
-  generated_at: "2026-02-03T07:47:42Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 789bcf3cbc6841fc293e054b919e63d661b3cc4cd205b2094289f00800127fe2
-  source_path: gateway/bridge-protocol.md
-  workflow: 15
----
-
-# Bridge 协议（旧版节点传输）
-
-Bridge 协议是一个**旧版**节点传输（TCP JSONL）。新的节点客户端应该使用统一的 Gateway 网关 WebSocket 协议。
-
-如果你正在构建操作者或节点客户端，请使用 [Gateway 网关协议](/gateway/protocol)。
-
-**注意：** 当前的 Symi 构建不再包含 TCP bridge 监听器；本文档仅作历史参考保留。
-旧版 `bridge.*` 配置键不再是配置模式的一部分。
-
-## 为什么我们有两种协议
-
-- **安全边界**：bridge 暴露一个小的允许列表，而不是完整的 Gateway 网关 API 接口。
-- **配对 + 节点身份**：节点准入由 Gateway 网关管理，并与每节点令牌绑定。
-- **设备发现用户体验**：节点可以通过局域网上的 Bonjour 发现 Gateway 网关，或通过 tailnet 直接连接。
-- **Loopback WS**：完整的 WS 控制平面保持本地，除非通过 SSH 隧道。
-
-## 传输
-
-- TCP，每行一个 JSON 对象（JSONL）。
-- 可选 TLS（当 `bridge.tls.enabled` 为 true 时）。
-- 旧版默认监听端口为 `18790`（当前构建不启动 TCP bridge）。
-
-当 TLS 启用时，设备发现 TXT 记录包含 `bridgeTls=1` 加上 `bridgeTlsSha256`，以便节点可以固定证书。
-
-## 握手 + 配对
-
-1. 客户端发送带有节点元数据 + 令牌（如果已配对）的 `hello`。
-2. 如果未配对，Gateway 网关回复 `error`（`NOT_PAIRED`/`UNAUTHORIZED`）。
-3. 客户端发送 `pair-request`。
-4. Gateway 网关等待批准，然后发送 `pair-ok` 和 `hello-ok`。
-
-`hello-ok` 返回 `serverName`，可能包含 `canvasHostUrl`。
-
-## 帧
-
-客户端 → Gateway 网关：
-
-- `req` / `res`：作用域 Gateway 网关 RPC（chat、sessions、config、health、voicewake、skills.bins）
-- `event`：节点信号（语音转录、智能体请求、聊天订阅、exec 生命周期）
-
-Gateway 网关 → 客户端：
-
-- `invoke` / `invoke-res`：节点命令（`canvas.*`、`camera.*`、`screen.record`、`location.get`、`sms.send`）
-- `event`：已订阅会话的聊天更新
-- `ping` / `pong`：保活
-
-旧版允许列表强制执行位于 `src/gateway/server-bridge.ts`（已移除）。
-
-## Exec 生命周期事件
-
-节点可以发出 `exec.finished` 或 `exec.denied` 事件来表面化 system.run 活动。
-这些被映射到 Gateway 网关中的系统事件。（旧版节点可能仍会发出 `exec.started`。）
-
-Payload 字段（除非注明，否则都是可选的）：
-
-- `sessionKey`（必需）：接收系统事件的智能体会话。
-- `runId`：用于分组的唯一 exec id。
-- `command`：原始或格式化的命令字符串。
-- `exitCode`、`timedOut`、`success`、`output`：完成详情（仅限 finished）。
-- `reason`：拒绝原因（仅限 denied）。
-
-## Tailnet 使用
-
-- 将 bridge 绑定到 tailnet IP：在 `~/.symi/symi.json` 中设置 `bridge.bind: "tailnet"`。
-- 客户端通过 MagicDNS 名称或 tailnet IP 连接。
-- Bonjour **不**跨网络；需要时使用手动主机/端口或广域 DNS‑SD。
-
-## 版本控制
-
-Bridge 目前是**隐式 v1**（无最小/最大协商）。预期向后兼容；在任何破坏性变更之前添加 bridge 协议版本字段。

package/docs/zh-CN/gateway/cli-backends.md

@@ -1,213 +0,0 @@
----
-read_when:
-  - 你想要一个在 API 提供商失败时的可靠回退
-  - 你正在运行 Claude Code CLI 或其他本地 AI CLI 并想要复用它们
-  - 你需要一个纯文本、无工具的路径，但仍支持会话和图像
-summary: CLI 后端：通过本地 AI CLI 实现纯文本回退
-title: CLI 后端
-x-i18n:
-  generated_at: "2026-02-03T07:47:52Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 56a96e83b16a4f6443cbf4a9da7a660c41a5b178af5e13f35352c9d72e1b08dd
-  source_path: gateway/cli-backends.md
-  workflow: 15
----
-
-# CLI 后端（回退运行时）
-
-当 API 提供商宕机、被限流或暂时异常时，Symi 可以运行**本地 AI CLI** 作为**纯文本回退**。这是有意保守的设计：
-
-- **工具被禁用**（无工具调用）。
-- **文本输入 → 文本输出**（可靠）。
-- **支持会话**（因此后续轮次保持连贯）。
-- 如果 CLI 接受图像路径，**图像可以传递**。
-
-这被设计为**安全网**而非主要路径。当你想要"始终有效"的文本响应而不依赖外部 API 时使用它。
-
-## 新手友好快速开始
-
-你可以**无需任何配置**使用 Claude Code CLI（Symi 自带内置默认值）：
-
-```bash
-symi agent --message "hi" --model claude-cli/opus-4.5
-```
-
-Codex CLI 也可以开箱即用：
-
-```bash
-symi agent --message "hi" --model codex-cli/gpt-5.2-codex
-```
-
-如果你的 Gateway 网关在 launchd/systemd 下运行且 PATH 很精简，只需添加命令路径：
-
-```json5
-{
-  agents: {
-    defaults: {
-      cliBackends: {
-        "claude-cli": {
-          command: "/opt/homebrew/bin/claude",
-        },
-      },
-    },
-  },
-}
-```
-
-就这样。除了 CLI 本身外，不需要密钥，不需要额外的认证配置。
-
-## 作为回退使用
-
-将 CLI 后端添加到你的回退列表中，这样它只在主要模型失败时运行：
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: {
-        primary: "anthropic/claude-opus-4-5",
-        fallbacks: ["claude-cli/opus-4.5"],
-      },
-      models: {
-        "anthropic/claude-opus-4-5": { alias: "Opus" },
-        "claude-cli/opus-4.5": {},
-      },
-    },
-  },
-}
-```
-
-注意事项：
-
-- 如果你使用 `agents.defaults.models`（允许列表），必须包含 `claude-cli/...`。
-- 如果主要提供商失败（认证、限流、超时），Symi 将接着尝试 CLI 后端。
-
-## 配置概览
-
-所有 CLI 后端位于：
-
-```
-agents.defaults.cliBackends
-```
-
-每个条目以**提供商 ID**（例如 `claude-cli`、`my-cli`）为键。提供商 ID 成为你的模型引用的左侧部分：
-
-```
-<provider>/<model>
-```
-
-### 配置示例
-
-```json5
-{
-  agents: {
-    defaults: {
-      cliBackends: {
-        "claude-cli": {
-          command: "/opt/homebrew/bin/claude",
-        },
-        "my-cli": {
-          command: "my-cli",
-          args: ["--json"],
-          output: "json",
-          input: "arg",
-          modelArg: "--model",
-          modelAliases: {
-            "claude-opus-4-5": "opus",
-            "claude-sonnet-4-5": "sonnet",
-          },
-          sessionArg: "--session",
-          sessionMode: "existing",
-          sessionIdFields: ["session_id", "conversation_id"],
-          systemPromptArg: "--system",
-          systemPromptWhen: "first",
-          imageArg: "--image",
-          imageMode: "repeat",
-          serialize: true,
-        },
-      },
-    },
-  },
-}
-```
-
-## 工作原理
-
-1. **选择后端**基于提供商前缀（`claude-cli/...`）。
-2. **构建系统提示**使用相同的 Symi 提示 + 工作区上下文。
-3. **执行 CLI**并带有会话 ID（如果支持），使历史记录保持一致。
-4. **解析输出**（JSON 或纯文本）并返回最终文本。
-5. **持久化会话 ID**按后端，使后续请求复用相同的 CLI 会话。
-
-## 会话
-
-- 如果 CLI 支持会话，设置 `sessionArg`（例如 `--session-id`）或 `sessionArgs`（占位符 `{sessionId}`）当 ID 需要插入到多个标志中时。
-- 如果 CLI 使用带有不同标志的**恢复子命令**，设置 `resumeArgs`（恢复时替换 `args`）以及可选的 `resumeOutput`（用于非 JSON 恢复）。
-- `sessionMode`：
-  - `always`：始终发送会话 ID（如果没有存储则使用新 UUID）。
-  - `existing`：仅在之前存储了会话 ID 时才发送。
-  - `none`：从不发送会话 ID。
-
-## 图像（传递）
-
-如果你的 CLI 接受图像路径，设置 `imageArg`：
-
-```json5
-imageArg: "--image",
-imageMode: "repeat"
-```
-
-Symi 会将 base64 图像写入临时文件。如果设置了 `imageArg`，这些路径作为 CLI 参数传递。如果缺少 `imageArg`，Symi 会将文件路径附加到提示中（路径注入），这对于从纯路径自动加载本地文件的 CLI 来说已经足够（Claude Code CLI 行为）。
-
-## 输入 / 输出
-
-- `output: "json"`（默认）尝试解析 JSON 并提取文本 + 会话 ID。
-- `output: "jsonl"` 解析 JSONL 流（Codex CLI `--json`）并提取最后一条智能体消息以及存在时的 `thread_id`。
-- `output: "text"` 将 stdout 视为最终响应。
-
-输入模式：
-
-- `input: "arg"`（默认）将提示作为最后一个 CLI 参数传递。
-- `input: "stdin"` 通过 stdin 发送提示。
-- 如果提示很长且设置了 `maxPromptArgChars`，则使用 stdin。
-
-## 默认值（内置）
-
-Symi 自带 `claude-cli` 的默认值：
-
-- `command: "claude"`
-- `args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]`
-- `resumeArgs: ["-p", "--output-format", "json", "--dangerously-skip-permissions", "--resume", "{sessionId}"]`
-- `modelArg: "--model"`
-- `systemPromptArg: "--append-system-prompt"`
-- `sessionArg: "--session-id"`
-- `systemPromptWhen: "first"`
-- `sessionMode: "always"`
-
-Symi 也自带 `codex-cli` 的默认值：
-
-- `command: "codex"`
-- `args: ["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
-- `resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
-- `output: "jsonl"`
-- `resumeOutput: "text"`
-- `modelArg: "--model"`
-- `imageArg: "--image"`
-- `sessionMode: "existing"`
-
-仅在需要时覆盖（常见：绝对 `command` 路径）。
-
-## 限制
-
-- **无 Symi 工具**（CLI 后端永远不会收到工具调用）。某些 CLI 可能仍会运行它们自己的智能体工具。
-- **无流式传输**（CLI 输出被收集后返回）。
-- **结构化输出**取决于 CLI 的 JSON 格式。
-- **Codex CLI 会话**通过文本输出恢复（无 JSONL），这比初始的 `--json` 运行结构化程度低。Symi 会话仍然正常工作。
-
-## 故障排除
-
-- **找不到 CLI**：将 `command` 设置为完整路径。
-- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。
-- **无会话连续性**：确保设置了 `sessionArg` 且 `sessionMode` 不是 `none`（Codex CLI 目前无法使用 JSON 输出恢复）。
-- **图像被忽略**：设置 `imageArg`（并验证 CLI 支持文件路径）。