@symerian/symi 3.0.21 → 3.0.22

package/docs/zh-CN/platforms/raspberry-pi.md

@@ -1,365 +0,0 @@
----
-read_when:
-  - 在 Raspberry Pi 上设置 Symi 时
-  - 在 ARM 设备上运行 Symi 时
-  - 构建低成本常驻个人 AI 时
-summary: 在 Raspberry Pi 上运行 Symi（低成本自托管设置）
-title: Raspberry Pi
-x-i18n:
-  generated_at: "2026-02-03T07:53:30Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 6741eaf0115a4fa0efd6599a99e0526a20ceb30eda1d9b04cba9dd5dec84bee2
-  source_path: platforms/raspberry-pi.md
-  workflow: 15
----
-
-# 在 Raspberry Pi 上运行 Symi
-
-## 目标
-
-在 Raspberry Pi 上运行持久、常驻的 Symi Gateway 网关，**一次性成本约 $35-80**（无月费）。
-
-适用于：
-
-- 24/7 个人 AI 助手
-- 家庭自动化中心
-- 低功耗、随时可用的 Telegram/WhatsApp 机器人
-
-## 硬件要求
-
-| Pi 型号         | 内存    | 是否可用？ | 说明                       |
-| --------------- | ------- | ---------- | -------------------------- |
-| **Pi 5**        | 4GB/8GB | ✅ 最佳    | 最快，推荐                 |
-| **Pi 4**        | 4GB     | ✅ 良好    | 大多数用户的最佳选择       |
-| **Pi 4**        | 2GB     | ✅ 可以    | 可用，添加交换空间         |
-| **Pi 4**        | 1GB     | ⚠️ 紧张    | 使用交换空间可行，最小配置 |
-| **Pi 3B+**      | 1GB     | ⚠️ 慢      | 可用但较慢                 |
-| **Pi Zero 2 W** | 512MB   | ❌         | 不推荐                     |
-
-**最低配置：** 1GB 内存，1 核，500MB 磁盘  
-**推荐：** 2GB+ 内存，64 位系统，16GB+ SD 卡（或 USB SSD）
-
-## 你需要准备
-
-- Raspberry Pi 4 或 5（推荐 2GB+）
-- MicroSD 卡（16GB+）或 USB SSD（性能更好）
-- 电源（推荐官方 Pi 电源）
-- 网络连接（以太网或 WiFi）
-- 约 30 分钟
-
-## 1) 刷写系统
-
-使用 **Raspberry Pi OS Lite (64-bit)** — 无头服务器不需要桌面。
-
-1. 下载 [Raspberry Pi Imager](https://www.raspberrypi.com/software/)
-2. 选择系统：**Raspberry Pi OS Lite (64-bit)**
-3. 点击齿轮图标（⚙️）预配置：
-   - 设置主机名：`gateway-host`
-   - 启用 SSH
-   - 设置用户名/密码
-   - 配置 WiFi（如果不使用以太网）
-4. 刷写到你的 SD 卡 / USB 驱动器
-5. 插入并启动 Pi
-
-## 2) 通过 SSH 连接
-
-```bash
-ssh user@gateway-host
-# 或使用 IP 地址
-ssh user@192.168.x.x
-```
-
-## 3) 系统设置
-
-```bash
-# 更新系统
-sudo apt update && sudo apt upgrade -y
-
-# 安装必要软件包
-sudo apt install -y git curl build-essential
-
-# 设置时区（对 cron/提醒很重要）
-sudo timedatectl set-timezone America/Chicago  # 改成你的时区
-```
-
-## 4) 安装 Node.js 22（ARM64）
-
-```bash
-# 通过 NodeSource 安装 Node.js
-curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
-sudo apt install -y nodejs
-
-# 验证
-node --version  # 应显示 v22.x.x
-npm --version
-```
-
-## 5) 添加交换空间（2GB 或更少内存时很重要）
-
-交换空间可防止内存不足崩溃：
-
-```bash
-# 创建 2GB 交换文件
-sudo fallocate -l 2G /swapfile
-sudo chmod 600 /swapfile
-sudo mkswap /swapfile
-sudo swapon /swapfile
-
-# 永久生效
-echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
-
-# 优化低内存（降低 swappiness）
-echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
-sudo sysctl -p
-```
-
-## 6) 安装 Symi
-
-### 选项 A：标准安装（推荐）
-
-```bash
-curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash
-```
-
-### 选项 B：可修改安装（用于调试）
-
-```bash
-git clone https://github.com/symi/symi.git
-cd symi
-npm install
-npm run build
-npm link
-```
-
-可修改安装让你可以直接访问日志和代码 — 对调试 ARM 特定问题很有用。
-
-## 7) 运行新手引导
-
-```bash
-symi onboard --install-daemon
-```
-
-按照向导操作：
-
-1. **Gateway 网关模式：** Local
-2. **认证：** 推荐 API 密钥（OAuth 在无头 Pi 上可能不稳定）
-3. **渠道：** Telegram 最容易上手
-4. **守护进程：** 是（systemd）
-
-## 8) 验证安装
-
-```bash
-# 检查状态
-symi status
-
-# 检查服务
-sudo systemctl status symi
-
-# 查看日志
-journalctl -u symi -f
-```
-
-## 9) 访问仪表板
-
-由于 Pi 是无头的，使用 SSH 隧道：
-
-```bash
-# 从你的笔记本电脑/台式机
-ssh -L 18789:localhost:18789 user@gateway-host
-
-# 然后在浏览器中打开
-open http://localhost:18789
-```
-
-或使用 Tailscale 实现常驻访问：
-
-```bash
-# 在 Pi 上
-curl -fsSL https://tailscale.com/install.sh | sh
-sudo tailscale up
-
-# 更新配置
-symi config set gateway.bind tailnet
-sudo systemctl restart symi
-```
-
----
-
-## 性能优化
-
-### 使用 USB SSD（巨大改进）
-
-SD 卡速度慢且会磨损。USB SSD 可大幅提升性能：
-
-```bash
-# 检查是否从 USB 启动
-lsblk
-```
-
-设置请参见 [Pi USB 启动指南](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot)。
-
-### 减少内存使用
-
-```bash
-# 禁用 GPU 内存分配（无头模式）
-echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
-
-# 如不需要则禁用蓝牙
-sudo systemctl disable bluetooth
-```
-
-### 监控资源
-
-```bash
-# 检查内存
-free -h
-
-# 检查 CPU 温度
-vcgencmd measure_temp
-
-# 实时监控
-htop
-```
-
----
-
-## ARM 特定说明
-
-### 二进制兼容性
-
-大多数 Symi 功能在 ARM64 上可用，但某些外部二进制文件可能需要 ARM 构建：
-
-| 工具               | ARM64 状态 | 说明                                |
-| ------------------ | ---------- | ----------------------------------- |
-| Node.js            | ✅         | 运行良好                            |
-| WhatsApp (Baileys) | ✅         | 纯 JS，无问题                       |
-| Telegram           | ✅         | 纯 JS，无问题                       |
-| gog (Gmail CLI)    | ⚠️         | 检查是否有 ARM 版本                 |
-| Chromium (browser) | ✅         | `sudo apt install chromium-browser` |
-
-如果某个 skill 失败，检查其二进制文件是否有 ARM 构建。许多 Go/Rust 工具有；有些没有。
-
-### 32 位 vs 64 位
-
-**始终使用 64 位系统。** Node.js 和许多现代工具需要它。使用以下命令检查：
-
-```bash
-uname -m
-# 应显示：aarch64（64 位）而不是 armv7l（32 位）
-```
-
----
-
-## 推荐的模型设置
-
-由于 Pi 只是 Gateway 网关（模型在云端运行），使用基于 API 的模型：
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "model": {
-        "primary": "anthropic/claude-sonnet-4-20250514",
-        "fallbacks": ["openai/gpt-4o-mini"]
-      }
-    }
-  }
-}
-```
-
-**不要尝试在 Pi 上运行本地 LLM** — 即使是小模型也太慢了。让 Claude/GPT 来做繁重的工作。
-
----
-
-## 开机自启
-
-新手引导向导会设置这个，但要验证：
-
-```bash
-# 检查服务是否已启用
-sudo systemctl is-enabled symi
-
-# 如果没有则启用
-sudo systemctl enable symi
-
-# 开机启动
-sudo systemctl start symi
-```
-
----
-
-## 故障排除
-
-### 内存不足（OOM）
-
-```bash
-# 检查内存
-free -h
-
-# 添加更多交换空间（见步骤 5）
-# 或减少 Pi 上运行的服务
-```
-
-### 性能慢
-
-- 使用 USB SSD 代替 SD 卡
-- 禁用未使用的服务：`sudo systemctl disable cups bluetooth avahi-daemon`
-- 检查 CPU 降频：`vcgencmd get_throttled`（应返回 `0x0`）
-
-### 服务无法启动
-
-```bash
-# 检查日志
-journalctl -u symi --no-pager -n 100
-
-# 常见修复：重新构建
-cd ~/symi  # 如果使用可修改安装
-npm run build
-sudo systemctl restart symi
-```
-
-### ARM 二进制问题
-
-如果某个 skill 失败并显示"exec format error"：
-
-1. 检查该二进制文件是否有 ARM64 构建
-2. 尝试从源代码构建
-3. 或使用支持 ARM 的 Docker 容器
-
-### WiFi 断开
-
-对于使用 WiFi 的无头 Pi：
-
-```bash
-# 禁用 WiFi 电源管理
-sudo iwconfig wlan0 power off
-
-# 永久生效
-echo 'wireless-power off' | sudo tee -a /etc/network/interfaces
-```
-
----
-
-## 成本对比
-
-| 设置           | 一次性成本 | 月费     | 说明               |
-| -------------- | ---------- | -------- | ------------------ |
-| **Pi 4 (2GB)** | ~$45       | $0       | + 电费（约 $5/年） |
-| **Pi 4 (4GB)** | ~$55       | $0       | 推荐               |
-| **Pi 5 (4GB)** | ~$60       | $0       | 最佳性能           |
-| **Pi 5 (8GB)** | ~$80       | $0       | 过剩但面向未来     |
-| DigitalOcean   | $0         | $6/月    | $72/年             |
-| Hetzner        | $0         | €3.79/月 | 约 $50/年          |
-
-**回本期：** 与云 VPS 相比，Pi 约 6-12 个月内回本。
-
----
-
-## 另请参阅
-
-- [Linux 指南](/platforms/linux) — 通用 Linux 设置
-- [DigitalOcean 指南](/platforms/digitalocean) — 云替代方案
-- [Hetzner 指南](/install/hetzner) — Docker 设置
-- [Tailscale](/gateway/tailscale) — 远程访问
-- [节点](/nodes) — 将你的笔记本电脑/手机与 Pi Gateway 网关配对

package/docs/zh-CN/platforms/windows.md

@@ -1,156 +0,0 @@
----
-read_when:
-  - 在 Windows 上安装 Symi
-  - 查找 Windows 配套应用状态
-summary: Windows（WSL2）支持 + 配套应用状态
-title: Windows (WSL2)
-x-i18n:
-  generated_at: "2026-02-03T07:53:19Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: c93d2263b4e5b60cb6fbe9adcb1a0ca95b70cd6feb6e63cfc4459cb18b229da0
-  source_path: platforms/windows.md
-  workflow: 15
----
-
-# Windows (WSL2)
-
-Windows 上的 Symi 推荐**通过 WSL2**（推荐 Ubuntu）。CLI + Gateway 网关在 Linux 内运行，这保持了运行时的一致性并使工具兼容性大大提高（Node/Bun/pnpm、Linux 二进制文件、Skills）。原生 Windows 可能更棘手。WSL2 给你完整的 Linux 体验——一条命令安装：`wsl --install`。
-
-原生 Windows 配套应用已在计划中。
-
-## 安装（WSL2）
-
-- [入门指南](/start/getting-started)（在 WSL 内使用）
-- [安装和更新](/install/updating)
-- 官方 WSL2 指南（Microsoft）：https://learn.microsoft.com/windows/wsl/install
-
-## Gateway 网关
-
-- [Gateway 网关操作手册](/gateway)
-- [配置](/gateway/configuration)
-
-## Gateway 网关服务安装（CLI）
-
-在 WSL2 内：
-
-```
-symi onboard --install-daemon
-```
-
-或：
-
-```
-symi gateway install
-```
-
-或：
-
-```
-symi configure
-```
-
-出现提示时选择 **Gateway service**。
-
-修复/迁移：
-
-```
-symi doctor
-```
-
-## 高级：通过 LAN 暴露 WSL 服务（portproxy）
-
-WSL 有自己的虚拟网络。如果另一台机器需要访问**在 WSL 内**运行的服务（SSH、本地 TTS 服务器或 Gateway 网关），你必须将 Windows 端口转发到当前的 WSL IP。WSL IP 在重启后会改变，因此你可能需要刷新转发规则。
-
-示例（以**管理员身份**运行 PowerShell）：
-
-```powershell
-$Distro = "Ubuntu-24.04"
-$ListenPort = 2222
-$TargetPort = 22
-
-$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
-if (-not $WslIp) { throw "WSL IP not found." }
-
-netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
-  connectaddress=$WslIp connectport=$TargetPort
-```
-
-允许端口通过 Windows 防火墙（一次性）：
-
-```powershell
-New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
-  -Protocol TCP -LocalPort $ListenPort -Action Allow
-```
-
-在 WSL 重启后刷新 portproxy：
-
-```powershell
-netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
-netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
-  connectaddress=$WslIp connectport=$TargetPort | Out-Null
-```
-
-注意事项：
-
-- 从另一台机器 SSH 目标是 **Windows 主机 IP**（示例：`ssh user@windows-host -p 2222`）。
-- 远程节点必须指向**可访问的** Gateway 网关 URL（不是 `127.0.0.1`）；使用 `symi status --all` 确认。
-- 使用 `listenaddress=0.0.0.0` 进行 LAN 访问；`127.0.0.1` 仅保持本地访问。
-- 如果你想自动化，注册一个计划任务在登录时运行刷新步骤。
-
-## WSL2 分步安装
-
-### 1）安装 WSL2 + Ubuntu
-
-打开 PowerShell（管理员）：
-
-```powershell
-wsl --install
-# Or pick a distro explicitly:
-wsl --list --online
-wsl --install -d Ubuntu-24.04
-```
-
-如果 Windows 要求则重启。
-
-### 2）启用 systemd（Gateway 网关安装所需）
-
-在你的 WSL 终端中：
-
-```bash
-sudo tee /etc/wsl.conf >/dev/null <<'EOF'
-[boot]
-systemd=true
-EOF
-```
-
-然后从 PowerShell：
-
-```powershell
-wsl --shutdown
-```
-
-重新打开 Ubuntu，然后验证：
-
-```bash
-systemctl --user status
-```
-
-### 3）安装 Symi（在 WSL 内）
-
-在 WSL 内按照 Linux 入门指南流程：
-
-```bash
-git clone https://github.com/symi/symi.git
-cd symi
-pnpm install
-pnpm ui:build # auto-installs UI deps on first run
-pnpm build
-symi onboard
-```
-
-完整指南：[入门指南](/start/getting-started)
-
-## Windows 配套应用
-
-我们还没有 Windows 配套应用。如果你想让它实现，欢迎贡献。

package/docs/zh-CN/plugins/agent-tools.md

@@ -1,99 +0,0 @@
----
-read_when:
-  - 你想在插件中添加新的智能体工具
-  - 你需要通过允许列表使工具可选启用
-summary: 在插件中编写智能体工具（模式、可选工具、允许列表）
-title: 插件智能体工具
-x-i18n:
-  generated_at: "2026-02-03T07:53:22Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 4479462e9d8b17b664bf6b5f424f2efc8e7bedeaabfdb6a93126e051e635c659
-  source_path: plugins/agent-tools.md
-  workflow: 15
----
-
-# 插件智能体工具
-
-Symi 插件可以注册**智能体工具**（JSON 模式函数），这些工具在智能体运行期间暴露给 LLM。工具可以是**必需的**（始终可用）或**可选的**（选择启用）。
-
-智能体工具在主配置的 `tools` 下配置，或在每个智能体的 `agents.list[].tools` 下配置。允许列表/拒绝列表策略控制智能体可以调用哪些工具。
-
-## 基本工具
-
-```ts
-import { Type } from "@sinclair/typebox";
-
-export default function (api) {
-  api.registerTool({
-    name: "my_tool",
-    description: "Do a thing",
-    parameters: Type.Object({
-      input: Type.String(),
-    }),
-    async execute(_id, params) {
-      return { content: [{ type: "text", text: params.input }] };
-    },
-  });
-}
-```
-
-## 可选工具（选择启用）
-
-可选工具**永远不会**自动启用。用户必须将它们添加到智能体允许列表中。
-
-```ts
-export default function (api) {
-  api.registerTool(
-    {
-      name: "workflow_tool",
-      description: "Run a local workflow",
-      parameters: {
-        type: "object",
-        properties: {
-          pipeline: { type: "string" },
-        },
-        required: ["pipeline"],
-      },
-      async execute(_id, params) {
-        return { content: [{ type: "text", text: params.pipeline }] };
-      },
-    },
-    { optional: true },
-  );
-}
-```
-
-在 `agents.list[].tools.allow`（或全局 `tools.allow`）中启用可选工具：
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "main",
-        tools: {
-          allow: [
-            "workflow_tool", // 特定工具名称
-            "workflow", // 插件 id（启用该插件的所有工具）
-            "group:plugins", // 所有插件工具
-          ],
-        },
-      },
-    ],
-  },
-}
-```
-
-其他影响工具可用性的配置选项：
-
-- 仅包含插件工具名称的允许列表被视为插件选择启用；核心工具保持启用，除非你在允许列表中也包含核心工具或组。
-- `tools.profile` / `agents.list[].tools.profile`（基础允许列表）
-- `tools.byProvider` / `agents.list[].tools.byProvider`（特定提供商的允许/拒绝）
-- `tools.sandbox.tools.*`（沙箱隔离时的沙箱工具策略）
-
-## 规则 + 提示
-
-- 工具名称**不能**与核心工具名称冲突；冲突的工具会被跳过。
-- 允许列表中使用的插件 id 不能与核心工具名称冲突。
-- 对于触发副作用或需要额外二进制文件/凭证的工具，优先使用 `optional: true`。

package/docs/zh-CN/plugins/manifest.md

@@ -1,68 +0,0 @@
----
-read_when:
-  - 你正在构建一个 Symi 插件
-  - 你需要提供插件配置 Schema 或调试插件验证错误
-summary: 插件清单及 JSON Schema 要求（严格配置验证）
-title: 插件清单
-x-i18n:
-  generated_at: "2026-02-01T21:34:21Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 47b3e33c915f47bdd172ae0316af7ef16ca831c317e3f1a7fdfcd67e3bd43f56
-  source_path: plugins/manifest.md
-  workflow: 15
----
-
-# 插件清单（symi.plugin.json）
-
-每个插件都**必须**在**插件根目录**下提供一个 `symi.plugin.json` 文件。Symi 使用此清单来**在不执行插件代码的情况下**验证配置。缺失或无效的清单将被视为插件错误，并阻止配置验证。
-
-参阅完整的插件系统指南：[插件](/tools/plugin)。
-
-## 必填字段
-
-```json
-{
-  "id": "voice-call",
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": false,
-    "properties": {}
-  }
-}
-```
-
-必填键：
-
-- `id`（字符串）：插件的规范 id。
-- `configSchema`（对象）：插件配置的 JSON Schema（内联形式）。
-
-可选键：
-
-- `kind`（字符串）：插件类型（例如：`"memory"`）。
-- `channels`（数组）：此插件注册的渠道 id（例如：`["matrix"]`）。
-- `providers`（数组）：此插件注册的提供商 id。
-- `skills`（数组）：要加载的 Skills 目录（相对于插件根目录）。
-- `name`（字符串）：插件的显示名称。
-- `description`（字符串）：插件简短描述。
-- `uiHints`（对象）：用于 UI 渲染的配置字段标签/占位符/敏感标志。
-- `version`（字符串）：插件版本（仅供参考）。
-
-## JSON Schema 要求
-
-- **每个插件都必须提供 JSON Schema**，即使不接受任何配置也是如此。
-- 空 Schema 是可以接受的（例如 `{ "type": "object", "additionalProperties": false }`）。
-- Schema 在配置读取/写入时进行验证，而非在运行时。
-
-## 验证行为
-
-- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 已在插件清单中声明。
-- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 会被视为**错误**。
-- 如果插件已安装但清单或 Schema 损坏或缺失，验证将失败，Doctor 会报告插件错误。
-- 如果插件配置存在但插件已**禁用**，配置会被保留，并在 Doctor 和日志中显示**警告**。
-
-## 注意事项
-
-- 清单对**所有插件**都是必需的，包括从本地文件系统加载的插件。
-- 运行时仍然会单独加载插件模块；清单仅用于发现和验证。
-- 如果你的插件依赖原生模块，请记录构建步骤以及所有包管理器允许列表要求（例如 pnpm 的 `allow-build-scripts` - `pnpm rebuild <package>`）。