@symerian/symi 3.0.21 → 3.0.22

package/docs/zh-CN/install/hetzner.md

@@ -1,336 +0,0 @@
----
-read_when:
-  - 你想让 Symi 在云 VPS 上 24/7 运行（而不是你的笔记本电脑）
-  - 你想在自己的 VPS 上运行生产级、永久在线的 Gateway 网关
-  - 你想完全控制持久化、二进制文件和重启行为
-  - 你在 Hetzner 或类似提供商上用 Docker 运行 Symi
-summary: 在廉价的 Hetzner VPS（Docker）上 24/7 运行 Symi Gateway 网关，带持久状态和内置二进制文件
-title: Hetzner
-x-i18n:
-  generated_at: "2026-02-03T07:52:17Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 84d9f24f1a803aa15faa52a05f25fe557ec3e2c2f48a00c701d49764bd3bc21a
-  source_path: platforms/hetzner.md
-  workflow: 15
----
-
-# 在 Hetzner 上运行 Symi（Docker，生产 VPS 指南）
-
-## 目标
-
-使用 Docker 在 Hetzner VPS 上运行持久的 Symi Gateway 网关，带持久状态、内置二进制文件和安全的重启行为。
-
-如果你想要"约 $5 实现 Symi 24/7"，这是最简单可靠的设置。
-Hetzner 定价会变化；选择最小的 Debian/Ubuntu VPS，如果遇到 OOM 再扩容。
-
-## 我们在做什么（简单说明）？
-
-- 租用一台小型 Linux 服务器（Hetzner VPS）
-- 安装 Docker（隔离的应用运行时）
-- 在 Docker 中启动 Symi Gateway 网关
-- 在主机上持久化 `~/.symi` + `~/.symi/workspace`（重启/重建后保留）
-- 通过 SSH 隧道从你的笔记本电脑访问控制 UI
-
-Gateway 网关可以通过以下方式访问：
-
-- 从你的笔记本电脑进行 SSH 端口转发
-- 如果你自己管理防火墙和令牌，可以直接暴露端口
-
-本指南假设在 Hetzner 上使用 Ubuntu 或 Debian。
-如果你使用其他 Linux VPS，请相应地映射软件包。
-通用 Docker 流程请参见 [Docker](/install/docker)。
-
----
-
-## 快速路径（有经验的运维人员）
-
-1. 配置 Hetzner VPS
-2. 安装 Docker
-3. 克隆 Symi 仓库
-4. 创建持久化主机目录
-5. 配置 `.env` 和 `docker-compose.yml`
-6. 将所需二进制文件烘焙到镜像中
-7. `docker compose up -d`
-8. 验证持久化和 Gateway 网关访问
-
----
-
-## 你需要什么
-
-- 具有 root 访问权限的 Hetzner VPS
-- 从你的笔记本电脑进行 SSH 访问
-- 基本熟悉 SSH + 复制/粘贴
-- 约 20 分钟
-- Docker 和 Docker Compose
-- 模型认证凭证
-- 可选的提供商凭证
-  - WhatsApp 二维码
-  - Telegram 机器人令牌
-  - Gmail OAuth
-
----
-
-## 1) 配置 VPS
-
-在 Hetzner 中创建一个 Ubuntu 或 Debian VPS。
-
-以 root 身份连接：
-
-```bash
-ssh root@YOUR_VPS_IP
-```
-
-本指南假设 VPS 是有状态的。
-不要将其视为一次性基础设施。
-
----
-
-## 2) 安装 Docker（在 VPS 上）
-
-```bash
-apt-get update
-apt-get install -y git curl ca-certificates
-curl -fsSL https://get.docker.com | sh
-```
-
-验证：
-
-```bash
-docker --version
-docker compose version
-```
-
----
-
-## 3) 克隆 Symi 仓库
-
-```bash
-git clone https://github.com/symi/symi.git
-cd symi
-```
-
-本指南假设你将构建自定义镜像以保证二进制文件持久化。
-
----
-
-## 4) 创建持久化主机目录
-
-Docker 容器是临时的。
-所有长期状态必须存储在主机上。
-
-```bash
-mkdir -p /root/.symi
-mkdir -p /root/.symi/workspace
-
-# 将所有权设置为容器用户（uid 1000）：
-chown -R 1000:1000 /root/.symi
-chown -R 1000:1000 /root/.symi/workspace
-```
-
----
-
-## 5) 配置环境变量
-
-在仓库根目录创建 `.env`。
-
-```bash
-SYMI_IMAGE=symi:latest
-SYMI_GATEWAY_TOKEN=change-me-now
-SYMI_GATEWAY_BIND=lan
-SYMI_GATEWAY_PORT=18789
-
-SYMI_CONFIG_DIR=/root/.symi
-SYMI_WORKSPACE_DIR=/root/.symi/workspace
-
-GOG_KEYRING_PASSWORD=change-me-now
-XDG_CONFIG_HOME=/home/node/.symi
-```
-
-生成强密钥：
-
-```bash
-openssl rand -hex 32
-```
-
-**不要提交此文件。**
-
----
-
-## 6) Docker Compose 配置
-
-创建或更新 `docker-compose.yml`。
-
-```yaml
-services:
-  symi-gateway:
-    image: ${SYMI_IMAGE}
-    build: .
-    restart: unless-stopped
-    env_file:
-      - .env
-    environment:
-      - HOME=/home/node
-      - NODE_ENV=production
-      - TERM=xterm-256color
-      - SYMI_GATEWAY_BIND=${SYMI_GATEWAY_BIND}
-      - SYMI_GATEWAY_PORT=${SYMI_GATEWAY_PORT}
-      - SYMI_GATEWAY_TOKEN=${SYMI_GATEWAY_TOKEN}
-      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
-      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
-      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-    volumes:
-      - ${SYMI_CONFIG_DIR}:/home/node/.symi
-      - ${SYMI_WORKSPACE_DIR}:/home/node/.symi/workspace
-    ports:
-      # 推荐：在 VPS 上保持 Gateway 网关仅限 loopback；通过 SSH 隧道访问。
-      # 要公开暴露，移除 `127.0.0.1:` 前缀并相应配置防火墙。
-      - "127.0.0.1:${SYMI_GATEWAY_PORT}:18789"
-
-      # 可选：仅当你对此 VPS 运行 iOS/Android 节点并需要 Canvas 主机时。
-      # 如果你公开暴露此端口，请阅读 /gateway/security 并相应配置防火墙。
-      # - "18793:18793"
-    command:
-      [
-        "node",
-        "dist/index.js",
-        "gateway",
-        "--bind",
-        "${SYMI_GATEWAY_BIND}",
-        "--port",
-        "${SYMI_GATEWAY_PORT}",
-      ]
-```
-
----
-
-## 7) 将所需二进制文件烘焙到镜像中（关键）
-
-在运行中的容器内安装二进制文件是一个陷阱。
-任何在运行时安装的东西都会在重启时丢失。
-
-所有 skills 所需的外部二进制文件必须在镜像构建时安装。
-
-以下示例仅展示三个常见二进制文件：
-
-- `gog` 用于 Gmail 访问
-- `goplaces` 用于 Google Places
-- `wacli` 用于 WhatsApp
-
-这些是示例，不是完整列表。
-你可以使用相同的模式安装任意数量的二进制文件。
-
-如果你以后添加依赖额外二进制文件的新 skills，你必须：
-
-1. 更新 Dockerfile
-2. 重新构建镜像
-3. 重启容器
-
-**示例 Dockerfile**
-
-```dockerfile
-FROM node:22-bookworm
-
-RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
-
-# 示例二进制文件 1：Gmail CLI
-RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
-  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog
-
-# 示例二进制文件 2：Google Places CLI
-RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
-  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces
-
-# 示例二进制文件 3：WhatsApp CLI
-RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
-  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli
-
-# 使用相同模式在下方添加更多二进制文件
-
-WORKDIR /app
-COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
-COPY scripts ./scripts
-
-RUN corepack enable
-RUN pnpm install --frozen-lockfile
-
-COPY . .
-RUN pnpm build
-RUN pnpm ui:install
-RUN pnpm ui:build
-
-ENV NODE_ENV=production
-
-CMD ["node","dist/index.js"]
-```
-
----
-
-## 8) 构建并启动
-
-```bash
-docker compose build
-docker compose up -d symi-gateway
-```
-
-验证二进制文件：
-
-```bash
-docker compose exec symi-gateway which gog
-docker compose exec symi-gateway which goplaces
-docker compose exec symi-gateway which wacli
-```
-
-预期输出：
-
-```
-/usr/local/bin/gog
-/usr/local/bin/goplaces
-/usr/local/bin/wacli
-```
-
----
-
-## 9) 验证 Gateway 网关
-
-```bash
-docker compose logs -f symi-gateway
-```
-
-成功：
-
-```
-[gateway] listening on ws://0.0.0.0:18789
-```
-
-从你的笔记本电脑：
-
-```bash
-ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
-```
-
-打开：
-
-`http://127.0.0.1:18789/`
-
-粘贴你的 Gateway 网关令牌。
-
----
-
-## 持久化位置（事实来源）
-
-Symi 在 Docker 中运行，但 Docker 不是事实来源。
-所有长期状态必须在重启、重建和重启后保留。
-
-| 组件             | 位置                          | 持久化机制    | 说明                        |
-| ---------------- | ----------------------------- | ------------- | --------------------------- |
-| Gateway 网关配置 | `/home/node/.symi/`           | 主机卷挂载    | 包括 `symi.json`、令牌      |
-| 模型认证配置文件 | `/home/node/.symi/`           | 主机卷挂载    | OAuth 令牌、API 密钥        |
-| Skill 配置       | `/home/node/.symi/skills/`    | 主机卷挂载    | Skill 级别状态              |
-| 智能体工作区     | `/home/node/.symi/workspace/` | 主机卷挂载    | 代码和智能体产物            |
-| WhatsApp 会话    | `/home/node/.symi/`           | 主机卷挂载    | 保留二维码登录              |
-| Gmail 密钥环     | `/home/node/.symi/`           | 主机卷 + 密码 | 需要 `GOG_KEYRING_PASSWORD` |
-| 外部二进制文件   | `/usr/local/bin/`             | Docker 镜像   | 必须在构建时烘焙            |
-| Node 运行时      | 容器文件系统                  | Docker 镜像   | 每次镜像构建时重建          |
-| 操作系统包       | 容器文件系统                  | Docker 镜像   | 不要在运行时安装            |
-| Docker 容器      | 临时的                        | 可重启        | 可以安全销毁                |

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

@@ -1,193 +0,0 @@
----
-read_when:
-  - 安装 Symi
-  - 你想从 GitHub 安装
-summary: 安装 Symi（推荐安装器、全局安装或从源代码安装）
-title: 安装
-x-i18n:
-  generated_at: "2026-02-03T10:07:43Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: b26f48c116c26c163ee0090fb4c3e29622951bd427ecaeccba7641d97cfdf17a
-  source_path: install/index.md
-  workflow: 15
----
-
-# 安装
-
-除非有特殊原因，否则请使用安装器。它会设置 CLI 并运行新手引导。
-
-## 快速安装（推荐）
-
-```bash
-curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash
-```
-
-Windows（PowerShell）：
-
-```powershell
-iwr -useb https://jaysteelmind.github.io/getsymi/install.ps1 | iex
-```
-
-下一步（如果你跳过了新手引导）：
-
-```bash
-symi onboard --install-daemon
-```
-
-## 系统要求
-
-- **Node >=22**
-- macOS、Linux 或通过 WSL2 的 Windows
-- `pnpm` 仅在从源代码构建时需要
-
-## 选择安装路径
-
-### 1）安装器脚本（推荐）
-
-通过 npm 全局安装 `symi` 并运行新手引导。
-
-```bash
-curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash
-```
-
-安装器标志：
-
-```bash
-curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash -s -- --help
-```
-
-详情：[安装器内部原理](/install/installer)。
-
-非交互式（跳过新手引导）：
-
-```bash
-curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash -s -- --no-onboard
-```
-
-### 2）全局安装（手动）
-
-如果你已经有 Node：
-
-```bash
-npm install -g @symerian/symi@latest
-```
-
-如果你全局安装了 libvips（macOS 上通过 Homebrew 安装很常见）且 `sharp` 安装失败，请强制使用预构建二进制文件：
-
-```bash
-SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g @symerian/symi@latest
-```
-
-如果你看到 `sharp: Please add node-gyp to your dependencies`，要么安装构建工具（macOS：Xcode CLT + `npm install -g node-gyp`），要么使用上面的 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 变通方法来跳过原生构建。
-
-或使用 pnpm：
-
-```bash
-pnpm add -g symi@latest
-pnpm approve-builds -g                # 批准 symi、node-llama-cpp、sharp 等
-pnpm add -g symi@latest           # 重新运行以执行 postinstall 脚本
-```
-
-pnpm 需要显式批准带有构建脚本的包。在首次安装显示"Ignored build scripts"警告后，运行 `pnpm approve-builds -g` 并选择列出的包，然后重新运行安装以执行 postinstall 脚本。
-
-然后：
-
-```bash
-symi onboard --install-daemon
-```
-
-### 3）从源代码（贡献者/开发）
-
-```bash
-git clone https://github.com/symi/symi.git
-cd symi
-pnpm install
-pnpm ui:build # 首次运行时自动安装 UI 依赖
-pnpm build
-symi onboard --install-daemon
-```
-
-提示：如果你还没有全局安装，请通过 `pnpm symi ...` 运行仓库命令。
-
-### 4）其他安装选项
-
-- Docker：[Docker](/install/docker)
-- Nix：[Nix](/install/nix)
-- Ansible：[Ansible](/install/ansible)
-- Bun（仅 CLI）：[Bun](/install/bun)
-
-## 安装后
-
-- 运行新手引导：`symi onboard --install-daemon`
-- 快速检查：`symi doctor`
-- 检查 Gateway 网关健康状态：`symi status` + `symi health`
-- 打开仪表板：`symi dashboard`
-
-## 安装方式：npm vs git（安装器）
-
-安装器支持两种方式：
-
-- `npm`（默认）：`npm install -g @symerian/symi@latest`
-- `git`：从 GitHub 克隆/构建并从源代码 checkout 运行
-
-### CLI 标志
-
-```bash
-# 显式 npm
-curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash -s -- --install-method npm
-
-# 从 GitHub 安装（源代码 checkout）
-curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash -s -- --install-method git
-```
-
-常用标志：
-
-- `--install-method npm|git`
-- `--git-dir <path>`（默认：`~/symi`）
-- `--no-git-update`（使用现有 checkout 时跳过 `git pull`）
-- `--no-prompt`（禁用提示；CI/自动化中必需）
-- `--dry-run`（打印将要执行的操作；不做任何更改）
-- `--no-onboard`（跳过新手引导）
-
-### 环境变量
-
-等效的环境变量（对自动化有用）：
-
-- `SYMI_INSTALL_METHOD=git|npm`
-- `SYMI_GIT_DIR=...`
-- `SYMI_GIT_UPDATE=0|1`
-- `SYMI_NO_PROMPT=1`
-- `SYMI_DRY_RUN=1`
-- `SYMI_NO_ONBOARD=1`
-- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1`（默认：`1`；避免 `sharp` 针对系统 libvips 构建）
-
-## 故障排除：找不到 `symi`（PATH）
-
-快速诊断：
-
-```bash
-node -v
-npm -v
-npm prefix -g
-echo "$PATH"
-```
-
-如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**不**在 `echo "$PATH"` 的输出中，你的 shell 无法找到全局 npm 二进制文件（包括 `symi`）。
-
-修复：将其添加到你的 shell 启动文件（zsh：`~/.zshrc`，bash：`~/.bashrc`）：
-
-```bash
-# macOS / Linux
-export PATH="$(npm prefix -g)/bin:$PATH"
-```
-
-在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH。
-
-然后打开新终端（或在 zsh 中执行 `rehash` / 在 bash 中执行 `hash -r`）。
-
-## 更新/卸载
-
-- 更新：[更新](/install/updating)
-- 迁移到新机器：[迁移](/install/migrating)
-- 卸载：[卸载](/install/uninstall)

package/docs/zh-CN/install/installer.md

@@ -1,128 +0,0 @@
----
-read_when:
-  - 你想了解 `jaysteelmind.github.io/getsymi/install.sh` 的工作机制
-  - 你想自动化安装（CI / 无头环境）
-  - 你想从 GitHub 检出安装
-summary: 安装器脚本的工作原理（install.sh + install-cli.sh）、参数和自动化
-title: 安装器内部机制
-x-i18n:
-  generated_at: "2026-02-01T21:07:55Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 9e0a19ecb5da0a395030e1ccf0d4bedf16b83946b3432c5399d448fe5d298391
-  source_path: install/installer.md
-  workflow: 14
----
-
-# 安装器内部机制
-
-Symi 提供两个安装器脚本（托管在 `jaysteelmind.github.io/getsymi`）：
-
-- `https://jaysteelmind.github.io/getsymi/install.sh` — "推荐"安装器（默认全局 npm 安装；也可从 GitHub 检出安装）
-- `https://jaysteelmind.github.io/getsymi/install-cli.sh` — 无需 root 权限的 CLI 安装器（安装到带有独立 Node 的前缀目录）
-- `https://jaysteelmind.github.io/getsymi/install.ps1` — Windows PowerShell 安装器（默认 npm；可选 git 安装）
-
-查看当前参数/行为，运行：
-
-```bash
-curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash -s -- --help
-```
-
-Windows (PowerShell) 帮助：
-
-```powershell
-& ([scriptblock]::Create((iwr -useb https://jaysteelmind.github.io/getsymi/install.ps1))) -?
-```
-
-如果安装器完成但在新终端中找不到 `symi`，通常是 Node/npm PATH 问题。参见：[安装](/install#nodejs--npm-path-sanity)。
-
-## install.sh（推荐）
-
-功能概述：
-
-- 检测操作系统（macOS / Linux / WSL）。
-- 确保 Node.js **22+**（macOS 通过 Homebrew；Linux 通过 NodeSource）。
-- 选择安装方式：
-  - `npm`（默认）：`npm install -g @symerian/symi@latest`
-  - `git`：克隆/构建源码检出并安装包装脚本
-- 在 Linux 上：必要时将 npm 前缀切换到 `~/.npm-global`，以避免全局 npm 权限错误。
-- 如果是升级现有安装：运行 `symi doctor --non-interactive`（尽力执行）。
-- 对于 git 安装：安装/更新后运行 `symi doctor --non-interactive`（尽力执行）。
-- 通过默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 来缓解 `sharp` 原生安装问题（避免使用系统 libvips 编译）。
-
-如果你*希望* `sharp` 链接到全局安装的 libvips（或你正在调试），请设置：
-
-```bash
-SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash
-```
-
-### 可发现性 / "git 安装"提示
-
-如果你在**已有的 Symi 源码检出目录中**运行安装器（通过 `package.json` + `pnpm-workspace.yaml` 检测），它会提示：
-
-- 更新并使用此检出（`git`）
-- 或迁移到全局 npm 安装（`npm`）
-
-在非交互式上下文中（无 TTY / `--no-prompt`），你必须传入 `--install-method git|npm`（或设置 `SYMI_INSTALL_METHOD`），否则脚本将以退出码 `2` 退出。
-
-### 为什么需要 Git
-
-`--install-method git` 路径（克隆 / 拉取）需要 Git。
-
-对于 `npm` 安装，Git *通常*不是必需的，但某些环境仍然需要它（例如通过 git URL 获取软件包或依赖时）。安装器目前会确保 Git 存在，以避免在全新发行版上出现 `spawn git ENOENT` 错误。
-
-### 为什么在全新 Linux 上 npm 会报 `EACCES`
-
-在某些 Linux 设置中（尤其是通过系统包管理器或 NodeSource 安装 Node 后），npm 的全局前缀指向 root 拥有的位置。此时 `npm install -g ...` 会报 `EACCES` / `mkdir` 权限错误。
-
-`install.sh` 通过将前缀切换到以下位置来缓解此问题：
-
-- `~/.npm-global`（并在存在时将其添加到 `~/.bashrc` / `~/.zshrc` 的 `PATH` 中）
-
-## install-cli.sh（无需 root 权限的 CLI 安装器）
-
-此脚本将 `symi` 安装到前缀目录（默认：`~/.symi`），同时在该前缀下安装专用的 Node 运行时，因此可以在不想改动系统 Node/npm 的机器上使用。
-
-帮助：
-
-```bash
-curl -fsSL https://jaysteelmind.github.io/getsymi/install-cli.sh | bash -s -- --help
-```
-
-## install.ps1（Windows PowerShell）
-
-功能概述：
-
-- 确保 Node.js **22+**（winget/Chocolatey/Scoop 或手动安装）。
-- 选择安装方式：
-  - `npm`（默认）：`npm install -g @symerian/symi@latest`
-  - `git`：克隆/构建源码检出并安装包装脚本
-- 在升级和 git 安装时运行 `symi doctor --non-interactive`（尽力执行）。
-
-示例：
-
-```powershell
-iwr -useb https://jaysteelmind.github.io/getsymi/install.ps1 | iex
-```
-
-```powershell
-iwr -useb https://jaysteelmind.github.io/getsymi/install.ps1 | iex -InstallMethod git
-```
-
-```powershell
-iwr -useb https://jaysteelmind.github.io/getsymi/install.ps1 | iex -InstallMethod git -GitDir "C:\\symi"
-```
-
-环境变量：
-
-- `SYMI_INSTALL_METHOD=git|npm`
-- `SYMI_GIT_DIR=...`
-
-Git 要求：
-
-如果你选择 `-InstallMethod git` 但未安装 Git，安装器会打印 Git for Windows 的链接（`https://git-scm.com/download/win`）并退出。
-
-常见 Windows 问题：
-
-- **npm error spawn git / ENOENT**：安装 Git for Windows 并重新打开 PowerShell，然后重新运行安装器。
-- **"symi" 不是可识别的命令**：你的 npm 全局 bin 文件夹不在 PATH 中。大多数系统使用 `%AppData%\\npm`。你也可以运行 `npm config get prefix` 并将 `\\bin` 添加到 PATH，然后重新打开 PowerShell。