@symerian/symi 3.0.21 → 3.0.22

package/docs/zh-CN/web/control-ui.md

@@ -1,190 +0,0 @@
----
-read_when:
-  - 你想从浏览器操作 Gateway 网关
-  - 你想要无需 SSH 隧道的 Tailnet 访问
-summary: Gateway 网关的浏览器控制 UI（聊天、节点、配置）
-title: 控制 UI
-x-i18n:
-  generated_at: "2026-02-03T10:13:20Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: bef105a376fc1a1df44e3e4fb625db1cbcafe2f41e718181c36877b8cbc08816
-  source_path: web/control-ui.md
-  workflow: 15
----
-
-# 控制 UI（浏览器）
-
-控制 UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用：
-
-- 默认：`http://<host>:18789/`
-- 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/symi`）
-
-它**直接与同一端口上的 Gateway 网关 WebSocket** 通信。
-
-## 快速打开（本地）
-
-如果 Gateway 网关在同一台计算机上运行，打开：
-
-- http://127.0.0.1:18789/（或 http://localhost:18789/）
-
-如果页面加载失败，请先启动 Gateway 网关：`symi gateway`。
-
-认证在 WebSocket 握手期间通过以下方式提供：
-
-- `connect.params.auth.token`
-- `connect.params.auth.password`
-  仪表板设置面板允许你存储 token；密码不会被持久化。
-  新手引导向导默认生成一个 Gateway 网关 token，所以在首次连接时将其粘贴到这里。
-
-## 设备配对（首次连接）
-
-当你从新浏览器或设备连接到控制 UI 时，Gateway 网关需要**一次性配对批准** — 即使你在同一个 Tailnet 上且 `gateway.auth.allowTailscale: true`。这是防止未授权访问的安全措施。
-
-**你会看到：** "disconnected (1008): pairing required"
-
-**批准设备：**
-
-```bash
-# 列出待处理的请求
-symi devices list
-
-# 按请求 ID 批准
-symi devices approve <requestId>
-```
-
-一旦批准，设备会被记住，除非你使用 `symi devices revoke --device <id> --role <role>` 撤销它，否则不需要重新批准。参见 [Devices CLI](/cli/devices) 了解 token 轮换和撤销。
-
-**注意：**
-
-- 本地连接（`127.0.0.1`）会自动批准。
-- 远程连接（LAN、Tailnet 等）需要显式批准。
-- 每个浏览器配置文件生成唯一的设备 ID，因此切换浏览器或清除浏览器数据将需要重新配对。
-
-## 目前可以做什么
-
-- 通过 Gateway 网关 WS 与模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）
-- 在聊天中流式传输工具调用 + 实时工具输出卡片（智能体事件）
-- 实例：在线列表 + 刷新（`system-presence`）
-- 会话：列表 + 每会话思考/详细覆盖（`sessions.list`、`sessions.patch`）
-- 定时任务：列出/添加/运行/启用/禁用 + 运行历史（`cron.*`）
-- Skills：状态、启用/禁用、安装、API 密钥更新（`skills.*`）
-- 节点：列表 + 能力（`node.list`）
-- 执行批准：编辑 Gateway 网关或节点允许列表 + `exec host=gateway/node` 的询问策略（`exec.approvals.*`）
-- 配置：查看/编辑 `~/.symi/symi.json`（`config.get`、`config.set`）
-- 配置：应用 + 带验证的重启（`config.apply`）并唤醒上次活动的会话
-- 配置写入包含基础哈希保护，以防止覆盖并发编辑
-- 配置 schema + 表单渲染（`config.schema`，包括插件 + 渠道 schema）；原始 JSON 编辑器仍然可用
-- 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）
-- 日志：Gateway 网关文件日志的实时尾部跟踪，带过滤/导出（`logs.tail`）
-- 更新：运行包/git 更新 + 重启（`update.run`）并显示重启报告
-
-## 聊天行为
-
-- `chat.send` 是**非阻塞的**：它立即以 `{ runId, status: "started" }` 确认，响应通过 `chat` 事件流式传输。
-- 使用相同的 `idempotencyKey` 重新发送在运行时返回 `{ status: "in_flight" }`，完成后返回 `{ status: "ok" }`。
-- `chat.inject` 将助手备注附加到会话转录，并为仅 UI 更新广播 `chat` 事件（无智能体运行，无渠道投递）。
-- 停止：
-  - 点击**停止**（调用 `chat.abort`）
-  - 输入 `/stop`（或 `stop|esc|abort|wait|exit|interrupt`）以带外中止
-  - `chat.abort` 支持 `{ sessionKey }`（无 `runId`）以中止该会话的所有活动运行
-
-## Tailnet 访问（推荐）
-
-### 集成 Tailscale Serve（首选）
-
-保持 Gateway 网关在 loopback 上，让 Tailscale Serve 用 HTTPS 代理它：
-
-```bash
-symi gateway --tailscale serve
-```
-
-打开：
-
-- `https://<magicdns>/`（或你配置的 `gateway.controlUi.basePath`）
-
-默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Serve 请求可以通过 Tailscale 身份头（`tailscale-user-login`）进行认证。Symi 通过使用 `tailscale whois` 解析 `x-forwarded-for` 地址并与头匹配来验证身份，并且只在请求通过 Tailscale 的 `x-forwarded-*` 头到达 loopback 时接受这些。如果你想即使对于 Serve 流量也要求 token/密码，请设置 `gateway.auth.allowTailscale: false`（或强制 `gateway.auth.mode: "password"`）。
-
-### 绑定到 tailnet + token
-
-```bash
-symi gateway --bind tailnet --token "$(openssl rand -hex 32)"
-```
-
-然后打开：
-
-- `http://<tailscale-ip>:18789/`（或你配置的 `gateway.controlUi.basePath`）
-
-将 token 粘贴到 UI 设置中（作为 `connect.params.auth.token` 发送）。
-
-## 不安全的 HTTP
-
-如果你通过普通 HTTP 打开仪表板（`http://<lan-ip>` 或 `http://<tailscale-ip>`），浏览器在**非安全上下文**中运行并阻止 WebCrypto。默认情况下，Symi **阻止**没有设备身份的控制 UI 连接。
-
-**推荐修复：** 使用 HTTPS（Tailscale Serve）或在本地打开 UI：
-
-- `https://<magicdns>/`（Serve）
-- `http://127.0.0.1:18789/`（在 Gateway 网关主机上）
-
-**降级示例（仅通过 HTTP 使用 token）：**
-
-```json5
-{
-  gateway: {
-    controlUi: { allowInsecureAuth: true },
-    bind: "tailnet",
-    auth: { mode: "token", token: "replace-me" },
-  },
-}
-```
-
-这会为控制 UI 禁用设备身份 + 配对（即使在 HTTPS 上）。仅在你信任网络时使用。
-
-参见 [Tailscale](/gateway/tailscale) 了解 HTTPS 设置指南。
-
-## 构建 UI
-
-Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构建：
-
-```bash
-pnpm ui:build # 首次运行时自动安装 UI 依赖
-```
-
-可选的绝对基础路径（当你想要固定的资源 URL 时）：
-
-```bash
-SYMI_CONTROL_UI_BASE_PATH=/symi/ pnpm ui:build
-```
-
-用于本地开发（单独的开发服务器）：
-
-```bash
-pnpm ui:dev # 首次运行时自动安装 UI 依赖
-```
-
-然后将 UI 指向你的 Gateway 网关 WS URL（例如 `ws://127.0.0.1:18789`）。
-
-## 调试/测试：开发服务器 + 远程 Gateway 网关
-
-控制 UI 是静态文件；WebSocket 目标是可配置的，可以与 HTTP 源不同。当你想要在本地使用 Vite 开发服务器但 Gateway 网关在其他地方运行时，这很方便。
-
-1. 启动 UI 开发服务器：`pnpm ui:dev`
-2. 打开类似以下的 URL：
-
-```text
-http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789
-```
-
-可选的一次性认证（如需要）：
-
-```text
-http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789&token=<gateway-token>
-```
-
-注意：
-
-- `gatewayUrl` 在加载后存储在 localStorage 中并从 URL 中移除。
-- `token` 存储在 localStorage 中；`password` 仅保留在内存中。
-- 当 Gateway 网关在 TLS 后面时（Tailscale Serve、HTTPS 代理等），使用 `wss://`。
-
-远程访问设置详情：[远程访问](/gateway/remote)。

package/docs/zh-CN/web/dashboard.md

@@ -1,53 +0,0 @@
----
-read_when:
-  - 更改仪表板认证或暴露模式
-summary: Gateway 网关仪表板（控制 UI）访问和认证
-title: 仪表板
-x-i18n:
-  generated_at: "2026-02-03T10:13:14Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: e6876d50e17d3dd741471ed78bef6ac175b2fdbdc1c45dd52d9d2bd013e17f31
-  source_path: web/dashboard.md
-  workflow: 15
----
-
-# 仪表板（控制 UI）
-
-Gateway 网关仪表板是默认在 `/` 提供的浏览器控制 UI
-（通过 `gateway.controlUi.basePath` 覆盖）。
-
-快速打开（本地 Gateway 网关）：
-
-- http://127.0.0.1:18789/（或 http://localhost:18789/）
-
-关键参考：
-
-- [控制 UI](/web/control-ui) 了解使用方法和 UI 功能。
-- [Tailscale](/gateway/tailscale) 了解 Serve/Funnel 自动化。
-- [Web 界面](/web) 了解绑定模式和安全注意事项。
-
-认证通过 `connect.params.auth`（token 或密码）在 WebSocket 握手时强制执行。
-参见 [Gateway 网关配置](/gateway/configuration) 中的 `gateway.auth`。
-
-安全注意事项：控制 UI 是一个**管理界面**（聊天、配置、执行审批）。
-不要公开暴露它。UI 在首次加载后将 token 存储在 `localStorage` 中。
-优先使用 localhost、Tailscale Serve 或 SSH 隧道。
-
-## 快速路径（推荐）
-
-- 新手引导后，CLI 现在会自动打开带有你的 token 的仪表板，并打印相同的带 token 链接。
-- 随时重新打开：`symi dashboard`（复制链接，如果可能则打开浏览器，如果是无头环境则显示 SSH 提示）。
-- token 保持本地（仅查询参数）；UI 在首次加载后移除它并保存到 localStorage。
-
-## Token 基础（本地 vs 远程）
-
-- **Localhost**：打开 `http://127.0.0.1:18789/`。如果你看到"unauthorized"，运行 `symi dashboard` 并使用带 token 的链接（`?token=...`）。
-- **Token 来源**：`gateway.auth.token`（或 `SYMI_GATEWAY_TOKEN`）；UI 在首次加载后存储它。
-- **非 localhost**：使用 Tailscale Serve（如果 `gateway.auth.allowTailscale: true` 则无需 token）、带 token 的 tailnet 绑定，或 SSH 隧道。参见 [Web 界面](/web)。
-
-## 如果你看到"unauthorized" / 1008
-
-- 运行 `symi dashboard` 获取新的带 token 链接。
-- 确保 Gateway 网关可达（本地：`symi status`；远程：SSH 隧道 `ssh -N -L 18789:127.0.0.1:18789 user@host` 然后打开 `http://127.0.0.1:18789/?token=...`）。
-- 在仪表板设置中，粘贴你在 `gateway.auth.token`（或 `SYMI_GATEWAY_TOKEN`）中配置的相同 token。

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

@@ -1,118 +0,0 @@
----
-read_when:
-  - 你想通过 Tailscale 访问 Gateway 网关
-  - 你想使用浏览器 Control UI 和配置编辑
-summary: Gateway 网关 Web 界面：Control UI、绑定模式和安全
-title: Web
-x-i18n:
-  generated_at: "2026-02-03T10:13:29Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 4da8bc9831018c482ac918a759b9739f75ca130f70993f81911818bc60a685d1
-  source_path: web/index.md
-  workflow: 15
----
-
-# Web（Gateway 网关）
-
-Gateway 网关从与 Gateway 网关 WebSocket 相同的端口提供一个小型**浏览器 Control UI**（Vite + Lit）：
-
-- 默认：`http://<host>:18789/`
-- 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/symi`）
-
-功能详见 [Control UI](/web/control-ui)。
-本页重点介绍绑定模式、安全和面向 Web 的界面。
-
-## Webhooks
-
-当 `hooks.enabled=true` 时，Gateway 网关还在同一 HTTP 服务器上公开一个小型 webhook 端点。
-参见 [Gateway 网关配置](/gateway/configuration) → `hooks` 了解认证 + 载荷。
-
-## 配置（默认开启）
-
-当资源存在时（`dist/control-ui`），Control UI **默认启用**。
-你可以通过配置控制它：
-
-```json5
-{
-  gateway: {
-    controlUi: { enabled: true, basePath: "/symi" }, // basePath 可选
-  },
-}
-```
-
-## Tailscale 访问
-
-### 集成 Serve（推荐）
-
-保持 Gateway 网关在本地回环上，让 Tailscale Serve 代理它：
-
-```json5
-{
-  gateway: {
-    bind: "loopback",
-    tailscale: { mode: "serve" },
-  },
-}
-```
-
-然后启动 Gateway 网关：
-
-```bash
-symi gateway
-```
-
-打开：
-
-- `https://<magicdns>/`（或你配置的 `gateway.controlUi.basePath`）
-
-### Tailnet 绑定 + 令牌
-
-```json5
-{
-  gateway: {
-    bind: "tailnet",
-    controlUi: { enabled: true },
-    auth: { mode: "token", token: "your-token" },
-  },
-}
-```
-
-然后启动 Gateway 网关（非本地回环绑定需要令牌）：
-
-```bash
-symi gateway
-```
-
-打开：
-
-- `http://<tailscale-ip>:18789/`（或你配置的 `gateway.controlUi.basePath`）
-
-### 公共互联网（Funnel）
-
-```json5
-{
-  gateway: {
-    bind: "loopback",
-    tailscale: { mode: "funnel" },
-    auth: { mode: "password" }, // 或 SYMI_GATEWAY_PASSWORD
-  },
-}
-```
-
-## 安全注意事项
-
-- Gateway 网关认证默认是必需的（令牌/密码或 Tailscale 身份头）。
-- 非本地回环绑定仍然**需要**共享令牌/密码（`gateway.auth` 或环境变量）。
-- 向导默认生成 Gateway 网关令牌（即使在本地回环上）。
-- UI 发送 `connect.params.auth.token` 或 `connect.params.auth.password`。
-- 使用 Serve 时，当 `gateway.auth.allowTailscale` 为 `true` 时，Tailscale 身份头可以满足认证（无需令牌/密码）。设置 `gateway.auth.allowTailscale: false` 以要求显式凭证。参见 [Tailscale](/gateway/tailscale) 和 [安全](/gateway/security)。
-- `gateway.tailscale.mode: "funnel"` 需要 `gateway.auth.mode: "password"`（共享密码）。
-
-## 构建 UI
-
-Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构建：
-
-```bash
-pnpm ui:build # 首次运行时自动安装 UI 依赖
-```

package/docs/zh-CN/web/tui.md

@@ -1,166 +0,0 @@
----
-read_when:
-  - 你想要 TUI 的新手友好演练
-  - 你需要 TUI 功能、命令和快捷键的完整列表
-summary: 终端 UI（TUI）：从任何机器连接到 Gateway 网关
-title: TUI
-x-i18n:
-  generated_at: "2026-02-03T10:13:10Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 4bf5b0037bbb3a166289f2f0a9399489637d4cf26335ae3577af9ea83eee747e
-  source_path: web/tui.md
-  workflow: 15
----
-
-# TUI（终端 UI）
-
-## 快速开始
-
-1. 启动 Gateway 网关。
-
-```bash
-symi gateway
-```
-
-2. 打开 TUI。
-
-```bash
-symi tui
-```
-
-3. 输入消息并按 Enter。
-
-远程 Gateway 网关：
-
-```bash
-symi tui --url ws://<host>:<port> --token <gateway-token>
-```
-
-如果你的 Gateway 网关使用密码认证，请使用 `--password`。
-
-## 你看到的内容
-
-- 标题栏：连接 URL、当前智能体、当前会话。
-- 聊天日志：用户消息、助手回复、系统通知、工具卡片。
-- 状态行：连接/运行状态（连接中、运行中、流式传输中、空闲、错误）。
-- 页脚：连接状态 + 智能体 + 会话 + 模型 + think/verbose/reasoning + token 计数 + 投递状态。
-- 输入：带自动完成的文本编辑器。
-
-## 心智模型：智能体 + 会话
-
-- 智能体是唯一的标识符（例如 `main`、`research`）。Gateway 网关公开列表。
-- 会话属于当前智能体。
-- 会话键存储为 `agent:<agentId>:<sessionKey>`。
-  - 如果你输入 `/session main`，TUI 会将其扩展为 `agent:<currentAgent>:main`。
-  - 如果你输入 `/session agent:other:main`，你会显式切换到该智能体会话。
-- 会话范围：
-  - `per-sender`（默认）：每个智能体有多个会话。
-  - `global`：TUI 始终使用 `global` 会话（选择器可能为空）。
-- 当前智能体 + 会话始终在页脚中可见。
-
-## 发送 + 投递
-
-- 消息发送到 Gateway 网关；默认情况下不投递到提供商。
-- 开启投递：
-  - `/deliver on`
-  - 或设置面板
-  - 或使用 `symi tui --deliver` 启动
-
-## 选择器 + 覆盖层
-
-- 模型选择器：列出可用模型并设置会话覆盖。
-- 智能体选择器：选择不同的智能体。
-- 会话选择器：仅显示当前智能体的会话。
-- 设置：切换投递、工具输出展开和思考可见性。
-
-## 键盘快捷键
-
-- Enter：发送消息
-- Esc：中止活动运行
-- Ctrl+C：清除输入（按两次退出）
-- Ctrl+D：退出
-- Ctrl+L：模型选择器
-- Ctrl+G：智能体选择器
-- Ctrl+P：会话选择器
-- Ctrl+O：切换工具输出展开
-- Ctrl+T：切换思考可见性（重新加载历史）
-
-## 斜杠命令
-
-核心：
-
-- `/help`
-- `/status`
-- `/agent <id>`（或 `/agents`）
-- `/session <key>`（或 `/sessions`）
-- `/model <provider/model>`（或 `/models`）
-
-会话控制：
-
-- `/think <off|minimal|low|medium|high>`
-- `/verbose <on|full|off>`
-- `/reasoning <on|off|stream>`
-- `/usage <off|tokens|full>`
-- `/elevated <on|off|ask|full>`（别名：`/elev`）
-- `/activation <mention|always>`
-- `/deliver <on|off>`
-
-会话生命周期：
-
-- `/new` 或 `/reset`（重置会话）
-- `/abort`（中止活动运行）
-- `/settings`
-- `/exit`
-
-其他 Gateway 网关斜杠命令（例如 `/context`）会转发到 Gateway 网关并显示为系统输出。参见[斜杠命令](/tools/slash-commands)。
-
-## 本地 shell 命令
-
-- 以 `!` 为前缀的行会在 TUI 主机上运行本地 shell 命令。
-- TUI 每个会话会提示一次以允许本地执行；拒绝会在该会话中禁用 `!`。
-- 命令在 TUI 工作目录中以全新的非交互式 shell 运行（无持久化 `cd`/环境变量）。
-- 单独的 `!` 会作为普通消息发送；前导空格不会触发本地执行。
-
-## 工具输出
-
-- 工具调用显示为带有参数 + 结果的卡片。
-- Ctrl+O 在折叠/展开视图之间切换。
-- 工具运行时，部分更新会流式传输到同一张卡片。
-
-## 历史 + 流式传输
-
-- 连接时，TUI 加载最新历史（默认 200 条消息）。
-- 流式响应原地更新直到完成。
-- TUI 还监听智能体工具事件以获得更丰富的工具卡片。
-
-## 连接详情
-
-- TUI 以 `mode: "tui"` 向 Gateway 网关注册。
-- 重新连接会显示系统消息；事件间隙会在日志中显示。
-
-## 选项
-
-- `--url <url>`：Gateway 网关 WebSocket URL（默认为配置或 `ws://127.0.0.1:<port>`）
-- `--token <token>`：Gateway 网关令牌（如果需要）
-- `--password <password>`：Gateway 网关密码（如果需要）
-- `--session <key>`：会话键（默认：`main`，或范围为全局时为 `global`）
-- `--deliver`：将助手回复投递到提供商（默认关闭）
-- `--thinking <level>`：覆盖发送的思考级别
-- `--timeout-ms <ms>`：智能体超时（毫秒）（默认为 `agents.defaults.timeoutSeconds`）
-
-## 故障排除
-
-发送消息后没有输出：
-
-- 在 TUI 中运行 `/status` 以确认 Gateway 网关已连接且处于空闲/忙碌状态。
-- 检查 Gateway 网关日志：`symi logs --follow`。
-- 确认智能体可以运行：`symi status` 和 `symi models status`。
-- 如果你期望消息出现在聊天渠道中，请启用投递（`/deliver on` 或 `--deliver`）。
-- `--history-limit <n>`：要加载的历史条目数（默认 200）
-
-## 故障排除
-
-- `disconnected`：确保 Gateway 网关正在运行且你的 `--url/--token/--password` 正确。
-- 选择器中没有智能体：检查 `symi agents list` 和你的路由配置。
-- 会话选择器为空：你可能处于全局范围或还没有会话。

package/docs/zh-CN/web/webchat.md

@@ -1,56 +0,0 @@
----
-read_when:
-  - 调试或配置 WebChat 访问
-summary: 用于聊天 UI 的 loopback WebChat 静态主机和 Gateway 网关 WS 使用
-title: WebChat
-x-i18n:
-  generated_at: "2026-02-03T10:13:28Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: b5ee2b462c8c979ac27f80dea0cf12cf62b3c799cf8fd0a7721901e26efeb1a0
-  source_path: web/webchat.md
-  workflow: 15
----
-
-# WebChat（Gateway 网关 WebSocket UI）
-
-状态：macOS/iOS SwiftUI 聊天 UI 直接与 Gateway 网关 WebSocket 通信。
-
-## 它是什么
-
-- Gateway 网关的原生聊天 UI（无嵌入式浏览器，无本地静态服务器）。
-- 使用与其他渠道相同的会话和路由规则。
-- 确定性路由：回复始终返回到 WebChat。
-
-## 快速开始
-
-1. 启动 Gateway 网关。
-2. 打开 WebChat UI（macOS/iOS 应用）或控制 UI 聊天标签页。
-3. 确保已配置 Gateway 网关认证（默认需要，即使在 loopback 上）。
-
-## 工作原理（行为）
-
-- UI 连接到 Gateway 网关 WebSocket 并使用 `chat.history`、`chat.send` 和 `chat.inject`。
-- `chat.inject` 直接将助手注释追加到转录并广播到 UI（无智能体运行）。
-- 历史记录始终从 Gateway 网关获取（无本地文件监听）。
-- 如果 Gateway 网关不可达，WebChat 为只读模式。
-
-## 远程使用
-
-- 远程模式通过 SSH/Tailscale 隧道传输 Gateway 网关 WebSocket。
-- 你不需要运行单独的 WebChat 服务器。
-
-## 配置参考（WebChat）
-
-完整配置：[配置](/gateway/configuration)
-
-渠道选项：
-
-- 没有专用的 `webchat.*` 块。WebChat 使用下面的 Gateway 网关端点 + 认证设置。
-
-相关的全局选项：
-
-- `gateway.port`、`gateway.bind`：WebSocket 主机/端口。
-- `gateway.auth.mode`、`gateway.auth.token`、`gateway.auth.password`：WebSocket 认证。
-- `gateway.remote.url`、`gateway.remote.token`、`gateway.remote.password`：远程 Gateway 网关目标。
-- `session.*`：会话存储和主键默认值。