@symerian/symi 3.0.20 → 3.0.22

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

@@ -1,317 +0,0 @@
----
-read_when:
-  - 集成使用 OpenResponses API 的客户端
-  - 你需要基于 item 的输入、客户端工具调用或 SSE 事件
-summary: 从 Gateway 网关暴露兼容 OpenResponses 的 /v1/responses HTTP 端点
-title: OpenResponses API
-x-i18n:
-  generated_at: "2026-02-03T07:48:43Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 0597714837f8b210c38eeef53561894220c1473e54c56a5c69984847685d518c
-  source_path: gateway/openresponses-http-api.md
-  workflow: 15
----
-
-# OpenResponses API（HTTP）
-
-Symi 的 Gateway 网关可以提供兼容 OpenResponses 的 `POST /v1/responses` 端点。
-
-此端点**默认禁用**。请先在配置中启用。
-
-- `POST /v1/responses`
-- 与 Gateway 网关相同的端口（WS + HTTP 多路复用）：`http://<gateway-host>:<port>/v1/responses`
-
-底层实现中，请求作为正常的 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`）。
-
-## 选择智能体
-
-无需自定义头：在 OpenResponses `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.responses.enabled` 设置为 `true`：
-
-```json5
-{
-  gateway: {
-    http: {
-      endpoints: {
-        responses: { enabled: true },
-      },
-    },
-  },
-}
-```
-
-## 禁用端点
-
-将 `gateway.http.endpoints.responses.enabled` 设置为 `false`：
-
-```json5
-{
-  gateway: {
-    http: {
-      endpoints: {
-        responses: { enabled: false },
-      },
-    },
-  },
-}
-```
-
-## 会话行为
-
-默认情况下，端点**每个请求都是无状态的**（每次调用生成新的会话键）。
-
-如果请求包含 OpenResponses `user` 字符串，Gateway 网关会从中派生稳定的会话键，这样重复调用可以共享智能体会话。
-
-## 请求结构（支持的）
-
-请求遵循 OpenResponses API，使用基于 item 的输入。当前支持：
-
-- `input`：字符串或 item 对象数组。
-- `instructions`：合并到系统提示中。
-- `tools`：客户端工具定义（函数工具）。
-- `tool_choice`：过滤或要求客户端工具。
-- `stream`：启用 SSE 流式传输。
-- `max_output_tokens`：尽力而为的输出限制（取决于提供商）。
-- `user`：稳定的会话路由。
-
-接受但**当前忽略**：
-
-- `max_tool_calls`
-- `reasoning`
-- `metadata`
-- `store`
-- `previous_response_id`
-- `truncation`
-
-## Item（输入）
-
-### `message`
-
-角色：`system`、`developer`、`user`、`assistant`。
-
-- `system` 和 `developer` 追加到系统提示。
-- 最近的 `user` 或 `function_call_output` item 成为"当前消息"。
-- 较早的 user/assistant 消息作为上下文历史包含。
-
-### `function_call_output`（基于回合的工具）
-
-将工具结果发送回模型：
-
-```json
-{
-  "type": "function_call_output",
-  "call_id": "call_123",
-  "output": "{\"temperature\": \"72F\"}"
-}
-```
-
-### `reasoning` 和 `item_reference`
-
-为了 schema 兼容性而接受，但在构建提示时忽略。
-
-## 工具（客户端函数工具）
-
-使用 `tools: [{ type: "function", function: { name, description?, parameters? } }]` 提供工具。
-
-如果智能体决定调用工具，响应返回一个 `function_call` 输出 item。然后你发送带有 `function_call_output` 的后续请求以继续回合。
-
-## 图像（`input_image`）
-
-支持 base64 或 URL 来源：
-
-```json
-{
-  "type": "input_image",
-  "source": { "type": "url", "url": "https://example.com/image.png" }
-}
-```
-
-允许的 MIME 类型（当前）：`image/jpeg`、`image/png`、`image/gif`、`image/webp`。
-最大大小（当前）：10MB。
-
-## 文件（`input_file`）
-
-支持 base64 或 URL 来源：
-
-```json
-{
-  "type": "input_file",
-  "source": {
-    "type": "base64",
-    "media_type": "text/plain",
-    "data": "SGVsbG8gV29ybGQh",
-    "filename": "hello.txt"
-  }
-}
-```
-
-允许的 MIME 类型（当前）：`text/plain`、`text/markdown`、`text/html`、`text/csv`、`application/json`、`application/pdf`。
-
-最大大小（当前）：5MB。
-
-当前行为：
-
-- 文件内容被解码并添加到**系统提示**，而不是用户消息，所以它保持临时性（不持久化在会话历史中）。
-- PDF 被解析提取文本。如果发现的文本很少，前几页会被栅格化为图像并传递给模型。
-
-PDF 解析使用 Node 友好的 `pdfjs-dist` legacy 构建（无 worker）。现代 PDF.js 构建期望浏览器 worker/DOM 全局变量，因此不在 Gateway 网关中使用。
-
-URL 获取默认值：
-
-- `files.allowUrl`：`true`
-- `images.allowUrl`：`true`
-- 请求受到保护（DNS 解析、私有 IP 阻止、重定向限制、超时）。
-
-## 文件 + 图像限制（配置）
-
-默认值可在 `gateway.http.endpoints.responses` 下调整：
-
-```json5
-{
-  gateway: {
-    http: {
-      endpoints: {
-        responses: {
-          enabled: true,
-          maxBodyBytes: 20000000,
-          files: {
-            allowUrl: true,
-            allowedMimes: [
-              "text/plain",
-              "text/markdown",
-              "text/html",
-              "text/csv",
-              "application/json",
-              "application/pdf",
-            ],
-            maxBytes: 5242880,
-            maxChars: 200000,
-            maxRedirects: 3,
-            timeoutMs: 10000,
-            pdf: {
-              maxPages: 4,
-              maxPixels: 4000000,
-              minTextChars: 200,
-            },
-          },
-          images: {
-            allowUrl: true,
-            allowedMimes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
-            maxBytes: 10485760,
-            maxRedirects: 3,
-            timeoutMs: 10000,
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-省略时的默认值：
-
-- `maxBodyBytes`：20MB
-- `files.maxBytes`：5MB
-- `files.maxChars`：200k
-- `files.maxRedirects`：3
-- `files.timeoutMs`：10s
-- `files.pdf.maxPages`：4
-- `files.pdf.maxPixels`：4,000,000
-- `files.pdf.minTextChars`：200
-- `images.maxBytes`：10MB
-- `images.maxRedirects`：3
-- `images.timeoutMs`：10s
-
-## 流式传输（SSE）
-
-设置 `stream: true` 接收 Server-Sent Events（SSE）：
-
-- `Content-Type: text/event-stream`
-- 每个事件行是 `event: <type>` 和 `data: <json>`
-- 流以 `data: [DONE]` 结束
-
-当前发出的事件类型：
-
-- `response.created`
-- `response.in_progress`
-- `response.output_item.added`
-- `response.content_part.added`
-- `response.output_text.delta`
-- `response.output_text.done`
-- `response.content_part.done`
-- `response.output_item.done`
-- `response.completed`
-- `response.failed`（出错时）
-
-## 用量
-
-当底层提供商报告令牌计数时，`usage` 会被填充。
-
-## 错误
-
-错误使用如下 JSON 对象：
-
-```json
-{ "error": { "message": "...", "type": "invalid_request_error" } }
-```
-
-常见情况：
-
-- `401` 缺少/无效认证
-- `400` 无效请求体
-- `405` 错误的方法
-
-## 示例
-
-非流式：
-
-```bash
-curl -sS http://127.0.0.1:18789/v1/responses \
-  -H 'Authorization: Bearer YOUR_TOKEN' \
-  -H 'Content-Type: application/json' \
-  -H 'x-symi-agent-id: main' \
-  -d '{
-    "model": "symi",
-    "input": "hi"
-  }'
-```
-
-流式：
-
-```bash
-curl -N http://127.0.0.1:18789/v1/responses \
-  -H 'Authorization: Bearer YOUR_TOKEN' \
-  -H 'Content-Type: application/json' \
-  -H 'x-symi-agent-id: main' \
-  -d '{
-    "model": "symi",
-    "stream": true,
-    "input": "hi"
-  }'
-```

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

@@ -1,99 +0,0 @@
----
-read_when:
-  - 在没有 macOS UI 的情况下实现节点配对审批
-  - 添加用于审批远程节点的 CLI 流程
-  - 扩展 Gateway 网关协议以支持节点管理
-summary: Gateway 网关拥有的节点配对（选项 B），用于 iOS 和其他远程节点
-title: Gateway 网关拥有的配对
-x-i18n:
-  generated_at: "2026-02-03T07:48:32Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 1f5154292a75ea2c1470324babc99c6c46a5e4e16afb394ed323d28f6168f459
-  source_path: gateway/pairing.md
-  workflow: 15
----
-
-# Gateway 网关拥有的配对（选项 B）
-
-在 Gateway 网关拥有的配对中，**Gateway 网关**是允许哪些节点加入的唯一信息源。UI（macOS 应用、未来的客户端）只是审批或拒绝待处理请求的前端。
-
-**重要：**WS 节点在 `connect` 期间使用**设备配对**（角色 `node`）。`node.pair.*` 是一个独立的配对存储，**不会**限制 WS 握手。只有显式调用 `node.pair.*` 的客户端使用此流程。
-
-## 概念
-
-- **待处理请求**：一个节点请求加入；需要审批。
-- **已配对节点**：已批准的节点，带有已颁发的认证令牌。
-- **传输层**：Gateway 网关 WS 端点转发请求但不决定成员资格。（旧版 TCP 桥接支持已弃用/移除。）
-
-## 配对工作原理
-
-1. 节点连接到 Gateway 网关 WS 并请求配对。
-2. Gateway 网关存储一个**待处理请求**并发出 `node.pair.requested`。
-3. 你审批或拒绝该请求（CLI 或 UI）。
-4. 审批后，Gateway 网关颁发一个**新令牌**（重新配对时令牌会轮换）。
-5. 节点使用该令牌重新连接，现在是"已配对"状态。
-
-待处理请求在 **5 分钟**后自动过期。
-
-## CLI 工作流程（支持无头模式）
-
-```bash
-symi nodes pending
-symi nodes approve <requestId>
-symi nodes reject <requestId>
-symi nodes status
-symi nodes rename --node <id|name|ip> --name "Living Room iPad"
-```
-
-`nodes status` 显示已配对/已连接的节点及其功能。
-
-## API 接口（Gateway 网关协议）
-
-事件：
-
-- `node.pair.requested` — 创建新的待处理请求时发出。
-- `node.pair.resolved` — 请求被批准/拒绝/过期时发出。
-
-方法：
-
-- `node.pair.request` — 创建或复用待处理请求。
-- `node.pair.list` — 列出待处理 + 已配对的节点。
-- `node.pair.approve` — 批准待处理请求（颁发令牌）。
-- `node.pair.reject` — 拒绝待处理请求。
-- `node.pair.verify` — 验证 `{ nodeId, token }`。
-
-注意事项：
-
-- `node.pair.request` 对每个节点是幂等的：重复调用返回相同的待处理请求。
-- 审批**总是**生成新的令牌；`node.pair.request` 永远不会返回令牌。
-- 请求可以包含 `silent: true` 作为自动审批流程的提示。
-
-## 自动审批（macOS 应用）
-
-当满足以下条件时，macOS 应用可以选择尝试**静默审批**：
-
-- 请求标记为 `silent`，且
-- 应用可以使用相同用户验证到 Gateway 网关主机的 SSH 连接。
-
-如果静默审批失败，则回退到正常的"批准/拒绝"提示。
-
-## 存储（本地，私有）
-
-配对状态存储在 Gateway 网关状态目录下（默认 `~/.symi`）：
-
-- `~/.symi/nodes/paired.json`
-- `~/.symi/nodes/pending.json`
-
-如果你覆盖了 `SYMI_STATE_DIR`，`nodes/` 文件夹会随之移动。
-
-安全注意事项：
-
-- 令牌是机密信息；将 `paired.json` 视为敏感文件。
-- 轮换令牌需要重新审批（或删除节点条目）。
-
-## 传输层行为
-
-- 传输层是**无状态的**；它不存储成员资格。
-- 如果 Gateway 网关离线或配对被禁用，节点无法配对。
-- 如果 Gateway 网关处于远程模式，配对仍然针对远程 Gateway 网关的存储进行。

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

@@ -1,220 +0,0 @@
----
-read_when:
-  - 实现或更新 Gateway 网关 WS 客户端
-  - 调试协议不匹配或连接失败
-  - 重新生成协议模式/模型
-summary: Gateway 网关 WebSocket 协议：握手、帧、版本控制
-title: Gateway 网关协议
-x-i18n:
-  generated_at: "2026-02-03T07:48:42Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: bdafac40d53565901b2df450617287664d77fe4ff52681fa00cab9046b2fd850
-  source_path: gateway/protocol.md
-  workflow: 15
----
-
-# Gateway 网关协议（WebSocket）
-
-Gateway 网关 WS 协议是 Symi 的**单一控制平面 + 节点传输**。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明其**角色** + **作用域**。
-
-## 传输
-
-- WebSocket，带有 JSON 负载的文本帧。
-- 第一帧**必须**是 `connect` 请求。
-
-## 握手（connect）
-
-Gateway 网关 → 客户端（连接前质询）：
-
-```json
-{
-  "type": "event",
-  "event": "connect.challenge",
-  "payload": { "nonce": "…", "ts": 1737264000000 }
-}
-```
-
-客户端 → Gateway 网关：
-
-```json
-{
-  "type": "req",
-  "id": "…",
-  "method": "connect",
-  "params": {
-    "minProtocol": 3,
-    "maxProtocol": 3,
-    "client": {
-      "id": "cli",
-      "version": "1.2.3",
-      "platform": "macos",
-      "mode": "operator"
-    },
-    "role": "operator",
-    "scopes": ["operator.read", "operator.write"],
-    "caps": [],
-    "commands": [],
-    "permissions": {},
-    "auth": { "token": "…" },
-    "locale": "en-US",
-    "userAgent": "symi-cli/1.2.3",
-    "device": {
-      "id": "device_fingerprint",
-      "publicKey": "…",
-      "signature": "…",
-      "signedAt": 1737264000000,
-      "nonce": "…"
-    }
-  }
-}
-```
-
-Gateway 网关 → 客户端：
-
-```json
-{
-  "type": "res",
-  "id": "…",
-  "ok": true,
-  "payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } }
-}
-```
-
-当颁发设备令牌时，`hello-ok` 还包含：
-
-```json
-{
-  "auth": {
-    "deviceToken": "…",
-    "role": "operator",
-    "scopes": ["operator.read", "operator.write"]
-  }
-}
-```
-
-### 节点示例
-
-```json
-{
-  "type": "req",
-  "id": "…",
-  "method": "connect",
-  "params": {
-    "minProtocol": 3,
-    "maxProtocol": 3,
-    "client": {
-      "id": "ios-node",
-      "version": "1.2.3",
-      "platform": "ios",
-      "mode": "node"
-    },
-    "role": "node",
-    "scopes": [],
-    "caps": ["camera", "canvas", "screen", "location", "voice"],
-    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
-    "permissions": { "camera.capture": true, "screen.record": false },
-    "auth": { "token": "…" },
-    "locale": "en-US",
-    "userAgent": "symi-ios/1.2.3",
-    "device": {
-      "id": "device_fingerprint",
-      "publicKey": "…",
-      "signature": "…",
-      "signedAt": 1737264000000,
-      "nonce": "…"
-    }
-  }
-}
-```
-
-## 帧格式
-
-- **Request**：`{type:"req", id, method, params}`
-- **Response**：`{type:"res", id, ok, payload|error}`
-- **Event**：`{type:"event", event, payload, seq?, stateVersion?}`
-
-有副作用的方法需要**幂等键**（见模式）。
-
-## 角色 + 作用域
-
-### 角色
-
-- `operator` = 控制平面客户端（CLI/UI/自动化）。
-- `node` = 能力宿主（camera/screen/canvas/system.run）。
-
-### 作用域（operator）
-
-常用作用域：
-
-- `operator.read`
-- `operator.write`
-- `operator.admin`
-- `operator.approvals`
-- `operator.pairing`
-
-### 能力/命令/权限（node）
-
-节点在连接时声明能力声明：
-
-- `caps`：高级能力类别。
-- `commands`：invoke 的命令允许列表。
-- `permissions`：细粒度开关（例如 `screen.record`、`camera.capture`）。
-
-Gateway 网关将这些视为**声明**并强制执行服务器端允许列表。
-
-## 在线状态
-
-- `system-presence` 返回以设备身份为键的条目。
-- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，以便 UI 可以为每个设备显示单行，
-  即使它同时以 **operator** 和 **node** 身份连接。
-
-### 节点辅助方法
-
-- 节点可以调用 `skills.bins` 来获取当前的 skill 可执行文件列表，
-  用于自动允许检查。
-
-## Exec 审批
-
-- 当 exec 请求需要审批时，Gateway 网关广播 `exec.approval.requested`。
-- 操作者客户端通过调用 `exec.approval.resolve` 来解决（需要 `operator.approvals` 作用域）。
-
-## 版本控制
-
-- `PROTOCOL_VERSION` 在 `src/gateway/protocol/schema.ts` 中。
-- 客户端发送 `minProtocol` + `maxProtocol`；服务器拒绝不匹配的。
-- 模式 + 模型从 TypeBox 定义生成：
-  - `pnpm protocol:gen`
-  - `pnpm protocol:gen:swift`
-  - `pnpm protocol:check`
-
-## 认证
-
-- 如果设置了 `SYMI_GATEWAY_TOKEN`（或 `--token`），`connect.params.auth.token`
-  必须匹配，否则套接字将被关闭。
-- 配对后，Gateway 网关会颁发一个作用于连接角色 + 作用域的**设备令牌**。它在 `hello-ok.auth.deviceToken` 中返回，
-  客户端应将其持久化以供将来连接使用。
-- 设备令牌可以通过 `device.token.rotate` 和 `device.token.revoke` 轮换/撤销（需要 `operator.pairing` 作用域）。
-
-## 设备身份 + 配对
-
-- 节点应包含从密钥对指纹派生的稳定设备身份（`device.id`）。
-- Gateway 网关为每个设备 + 角色颁发令牌。
-- 新设备 ID 需要配对批准，除非启用了本地自动批准。
-- **本地**连接包括 loopback 和 Gateway 网关主机自身的 tailnet 地址
-  （因此同主机 tailnet 绑定仍可自动批准）。
-- 所有 WS 客户端在 `connect` 期间必须包含 `device` 身份（operator + node）。
-  控制 UI **仅**在启用 `gateway.controlUi.allowInsecureAuth` 时可以省略它
-  （或使用 `gateway.controlUi.dangerouslyDisableDeviceAuth` 用于紧急情况）。
-- 非本地连接必须签署服务器提供的 `connect.challenge` nonce。
-
-## TLS + 固定
-
-- WS 连接支持 TLS。
-- 客户端可以选择性地固定 Gateway 网关证书指纹（见 `gateway.tls`
-  配置加上 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。
-
-## 范围
-
-此协议暴露**完整的 Gateway 网关 API**（status、channels、models、chat、
-agent、sessions、nodes、approvals 等）。确切的接口由 `src/gateway/protocol/schema.ts` 中的 TypeBox 模式定义。