@symerian/symi 3.0.20 → 3.0.22

package/docs/zh-CN/install/macos-vm.md

@@ -1,288 +0,0 @@
----
-read_when:
-  - 你想让 Symi 与你的主 macOS 环境隔离
-  - 你想在沙箱中集成 iMessage（BlueBubbles）
-  - 你想要一个可重置、可克隆的 macOS 环境
-  - 你想比较本地与托管 macOS VM 选项
-summary: 在沙箱隔离的 macOS VM（本地或托管）中运行 Symi，当你需要隔离或 iMessage 时
-title: macOS 虚拟机
-x-i18n:
-  generated_at: "2026-02-03T07:53:09Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 4d1c85a5e4945f9f0796038cd5960edecb71ec4dffb6f9686be50adb75180716
-  source_path: platforms/macos-vm.md
-  workflow: 15
----
-
-# 在 macOS 虚拟机上运行 Symi（沙箱隔离）
-
-## 推荐默认方案（大多数用户）
-
-- **小型 Linux VPS** 用于永久在线的 Gateway 网关，成本低。参见 [VPS 托管](/vps)。
-- **专用硬件**（Mac mini 或 Linux 机器）如果你想要完全控制和**住宅 IP** 用于浏览器自动化。许多网站会屏蔽数据中心 IP，所以本地浏览通常效果更好。
-- **混合方案：** 将 Gateway 网关保持在廉价 VPS 上，当你需要浏览器/UI 自动化时，将你的 Mac 作为**节点**连接。参见[节点](/nodes)和 [Gateway 网关远程](/gateway/remote)。
-
-当你特别需要 macOS 独有功能（iMessage/BlueBubbles）或想要与日常 Mac 严格隔离时，使用 macOS VM。
-
-## macOS VM 选项
-
-### 在你的 Apple Silicon Mac 上运行本地 VM（Lume）
-
-使用 [Lume](https://cua.ai/docs/lume) 在你现有的 Apple Silicon Mac 上的沙箱 macOS VM 中运行 Symi。
-
-这为你提供：
-
-- 隔离的完整 macOS 环境（你的主机保持干净）
-- 通过 BlueBubbles 支持 iMessage（在 Linux/Windows 上不可能）
-- 通过克隆 VM 即时重置
-- 无需额外硬件或云成本
-
-### 托管 Mac 提供商（云）
-
-如果你想要云端的 macOS，托管 Mac 提供商也可以：
-
-- [MacStadium](https://www.macstadium.com/)（托管 Mac）
-- 其他托管 Mac 供应商也可以；按照他们的 VM + SSH 文档操作
-
-一旦你有了 macOS VM 的 SSH 访问权限，继续下面的步骤 6。
-
----
-
-## 快速路径（Lume，有经验的用户）
-
-1. 安装 Lume
-2. `lume create symi --os macos --ipsw latest`
-3. 完成设置助手，启用远程登录（SSH）
-4. `lume run symi --no-display`
-5. SSH 进入，安装 Symi，配置渠道
-6. 完成
-
----
-
-## 你需要什么（Lume）
-
-- Apple Silicon Mac（M1/M2/M3/M4）
-- 主机上安装 macOS Sequoia 或更高版本
-- 每个 VM 约 60 GB 可用磁盘空间
-- 约 20 分钟
-
----
-
-## 1) 安装 Lume
-
-```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
-```
-
-如果 `~/.local/bin` 不在你的 PATH 中：
-
-```bash
-echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc
-```
-
-验证：
-
-```bash
-lume --version
-```
-
-文档：[Lume 安装](https://cua.ai/docs/lume/guide/getting-started/installation)
-
----
-
-## 2) 创建 macOS VM
-
-```bash
-lume create symi --os macos --ipsw latest
-```
-
-这会下载 macOS 并创建 VM。VNC 窗口会自动打开。
-
-注意：下载可能需要一段时间，取决于你的网络连接。
-
----
-
-## 3) 完成设置助手
-
-在 VNC 窗口中：
-
-1. 选择语言和地区
-2. 跳过 Apple ID（或者如果你以后想要 iMessage 就登录）
-3. 创建用户账户（记住用户名和密码）
-4. 跳过所有可选功能
-
-设置完成后，启用 SSH：
-
-1. 打开系统设置 → 通用 → 共享
-2. 启用"远程登录"
-
----
-
-## 4) 获取 VM 的 IP 地址
-
-```bash
-lume get symi
-```
-
-查找 IP 地址（通常是 `192.168.64.x`）。
-
----
-
-## 5) SSH 进入 VM
-
-```bash
-ssh youruser@192.168.64.X
-```
-
-将 `youruser` 替换为你创建的账户，IP 替换为你 VM 的 IP。
-
----
-
-## 6) 安装 Symi
-
-在 VM 内：
-
-```bash
-npm install -g @symerian/symi@latest
-symi onboard --install-daemon
-```
-
-按照新手引导提示设置你的模型提供商（Anthropic、OpenAI 等）。
-
----
-
-## 7) 配置渠道
-
-编辑配置文件：
-
-```bash
-nano ~/.symi/symi.json
-```
-
-添加你的渠道：
-
-```json
-{
-  "channels": {
-    "whatsapp": {
-      "dmPolicy": "allowlist",
-      "allowFrom": ["+15551234567"]
-    },
-    "telegram": {
-      "botToken": "YOUR_BOT_TOKEN"
-    }
-  }
-}
-```
-
-然后登录 WhatsApp（扫描二维码）：
-
-```bash
-symi channels login
-```
-
----
-
-## 8) 无头运行 VM
-
-停止 VM 并在无显示器模式下重启：
-
-```bash
-lume stop symi
-lume run symi --no-display
-```
-
-VM 在后台运行。Symi 的守护进程保持 Gateway 网关运行。
-
-检查状态：
-
-```bash
-ssh youruser@192.168.64.X "symi status"
-```
-
----
-
-## 额外：iMessage 集成
-
-这是在 macOS 上运行的杀手级功能。使用 [BlueBubbles](https://bluebubbles.app) 将 iMessage 添加到 Symi。
-
-在 VM 内：
-
-1. 从 bluebubbles.app 下载 BlueBubbles
-2. 用你的 Apple ID 登录
-3. 启用 Web API 并设置密码
-4. 将 BlueBubbles webhooks 指向你的 Gateway 网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）
-
-添加到你的 Symi 配置：
-
-```json
-{
-  "channels": {
-    "bluebubbles": {
-      "serverUrl": "http://localhost:1234",
-      "password": "your-api-password",
-      "webhookPath": "/bluebubbles-webhook"
-    }
-  }
-}
-```
-
-重启 Gateway 网关。现在你的智能体可以发送和接收 iMessage 了。
-
-完整设置详情：[BlueBubbles 渠道](/channels/bluebubbles)
-
----
-
-## 保存黄金镜像
-
-在进一步自定义之前，快照你的干净状态：
-
-```bash
-lume stop symi
-lume clone symi symi-golden
-```
-
-随时重置：
-
-```bash
-lume stop symi && lume delete symi
-lume clone symi-golden symi
-lume run symi --no-display
-```
-
----
-
-## 24/7 运行
-
-通过以下方式保持 VM 运行：
-
-- 保持你的 Mac 插电
-- 在系统设置 → 节能中禁用睡眠
-- 如需要使用 `caffeinate`
-
-对于真正的永久在线，考虑专用 Mac mini 或小型 VPS。参见 [VPS 托管](/vps)。
-
----
-
-## 故障排除
-
-| 问题                    | 解决方案                                                     |
-| ----------------------- | ------------------------------------------------------------ |
-| 无法 SSH 进入 VM        | 检查 VM 的系统设置中是否启用了"远程登录"                     |
-| VM IP 未显示            | 等待 VM 完全启动，再次运行 `lume get symi`                   |
-| 找不到 Lume 命令        | 将 `~/.local/bin` 添加到你的 PATH                            |
-| WhatsApp 二维码扫描失败 | 确保运行 `symi channels login` 时你是登录到 VM（而不是主机） |
-
----
-
-## 相关文档
-
-- [VPS 托管](/vps)
-- [节点](/nodes)
-- [Gateway 网关远程](/gateway/remote)
-- [BlueBubbles 渠道](/channels/bluebubbles)
-- [Lume 快速入门](https://cua.ai/docs/lume/guide/getting-started/quickstart)
-- [Lume CLI 参考](https://cua.ai/docs/lume/reference/cli-reference)
-- [无人值守 VM 设置](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup)（高级）
-- [Docker 沙箱隔离](/install/docker)（替代隔离方案）

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

@@ -1,199 +0,0 @@
----
-read_when:
-  - 你正在将 Symi 迁移到新的笔记本电脑/服务器
-  - 你想保留会话、认证和渠道登录（WhatsApp 等）
-summary: 将 Symi 安装从一台机器迁移到另一台
-title: 迁移指南
-x-i18n:
-  generated_at: "2026-02-03T07:49:55Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 604d862c4bf86e7924d09028db8cc2514ca6f1d64ebe8bb7d1e2dde57ef70caa
-  source_path: install/migrating.md
-  workflow: 15
----
-
-# 将 Symi 迁移到新机器
-
-本指南将 Symi Gateway 网关从一台机器迁移到另一台，**无需重新进行新手引导**。
-
-迁移在概念上很简单：
-
-- 复制**状态目录**（`$SYMI_STATE_DIR`，默认：`~/.symi/`）— 这包括配置、认证、会话和渠道状态。
-- 复制你的**工作区**（默认 `~/.symi/workspace/`）— 这包括你的智能体文件（记忆、提示等）。
-
-但在**配置文件**、**权限**和**部分复制**方面有常见的陷阱。
-
-## 开始之前（你要迁移什么）
-
-### 1）确定你的状态目录
-
-大多数安装使用默认值：
-
-- **状态目录：** `~/.symi/`
-
-但如果你使用以下方式，可能会不同：
-
-- `--profile <name>`（通常变成 `~/.symi-<profile>/`）
-- `SYMI_STATE_DIR=/some/path`
-
-如果你不确定，在**旧**机器上运行：
-
-```bash
-symi status
-```
-
-在输出中查找 `SYMI_STATE_DIR` / profile 的提及。如果你运行多个 Gateway 网关，对每个配置文件重复此操作。
-
-### 2）确定你的工作区
-
-常见默认值：
-
-- `~/.symi/workspace/`（推荐的工作区）
-- 你创建的自定义文件夹
-
-你的工作区是 `MEMORY.md`、`USER.md` 和 `memory/*.md` 等文件所在的位置。
-
-### 3）了解你将保留什么
-
-如果你复制**两者**——状态目录和工作区，你将保留：
-
-- Gateway 网关配置（`symi.json`）
-- 认证配置文件 / API 密钥 / OAuth 令牌
-- 会话历史 + 智能体状态
-- 渠道状态（例如 WhatsApp 登录/会话）
-- 你的工作区文件（记忆、Skills 笔记等）
-
-如果你**只**复制工作区（例如通过 Git），你**不会**保留：
-
-- 会话
-- 凭证
-- 渠道登录
-
-这些存储在 `$SYMI_STATE_DIR` 下。
-
-## 迁移步骤（推荐）
-
-### 步骤 0 — 备份（旧机器）
-
-在**旧**机器上，首先停止 Gateway 网关，这样文件不会在复制过程中发生变化：
-
-```bash
-symi gateway stop
-```
-
-（可选但推荐）归档状态目录和工作区：
-
-```bash
-# 如果你使用配置文件或自定义位置，请调整路径
-cd ~
-tar -czf symi-state.tgz .symi
-
-tar -czf symi-workspace.tgz .symi/workspace
-```
-
-如果你有多个配置文件/状态目录（例如 `~/.symi-main`、`~/.symi-work`），分别归档每个。
-
-### 步骤 1 — 在新机器上安装 Symi
-
-在**新**机器上，安装 CLI（如果需要还有 Node）：
-
-- 参见：[安装](/install)
-
-在这个阶段，如果新手引导创建了一个新的 `~/.symi/` 也没关系 — 你将在下一步覆盖它。
-
-### 步骤 2 — 将状态目录 + 工作区复制到新机器
-
-复制**两者**：
-
-- `$SYMI_STATE_DIR`（默认 `~/.symi/`）
-- 你的工作区（默认 `~/.symi/workspace/`）
-
-常见方法：
-
-- `scp` 压缩包并解压
-- 通过 SSH 使用 `rsync -a`
-- 外部驱动器
-
-复制后，确保：
-
-- 包含了隐藏目录（例如 `.symi/`）
-- 文件所有权对于运行 Gateway 网关的用户是正确的
-
-### 步骤 3 — 运行 Doctor（迁移 + 服务修复）
-
-在**新**机器上：
-
-```bash
-symi doctor
-```
-
-Doctor 是"安全可靠"的命令。它修复服务、应用配置迁移，并警告不匹配问题。
-
-然后：
-
-```bash
-symi gateway restart
-symi status
-```
-
-## 常见陷阱（以及如何避免）
-
-### 陷阱：配置文件/状态目录不匹配
-
-如果你在旧 Gateway 网关上使用了配置文件（或 `SYMI_STATE_DIR`），而新 Gateway 网关使用了不同的配置，你会看到如下症状：
-
-- 配置更改不生效
-- 渠道丢失/已登出
-- 会话历史为空
-
-修复：使用你迁移的**相同**配置文件/状态目录运行 Gateway 网关/服务，然后重新运行：
-
-```bash
-symi doctor
-```
-
-### 陷阱：只复制 `symi.json`
-
-`symi.json` 是不够的。许多提供商在以下位置存储状态：
-
-- `$SYMI_STATE_DIR/credentials/`
-- `$SYMI_STATE_DIR/agents/<agentId>/...`
-
-始终迁移整个 `$SYMI_STATE_DIR` 文件夹。
-
-### 陷阱：权限/所有权
-
-如果你以 root 身份复制或更改了用户，Gateway 网关可能无法读取凭证/会话。
-
-修复：确保状态目录 + 工作区由运行 Gateway 网关的用户拥有。
-
-### 陷阱：在远程/本地模式之间迁移
-
-- 如果你的 UI（WebUI/TUI）指向**远程** Gateway 网关，远程主机拥有会话存储 + 工作区。
-- 迁移你的笔记本电脑不会移动远程 Gateway 网关的状态。
-
-如果你处于远程模式，请迁移 **Gateway 网关主机**。
-
-### 陷阱：备份中的密钥
-
-`$SYMI_STATE_DIR` 包含密钥（API 密钥、OAuth 令牌、WhatsApp 凭证）。将备份视为生产密钥：
-
-- 加密存储
-- 避免通过不安全的渠道共享
-- 如果怀疑泄露，轮换密钥
-
-## 验证检查清单
-
-在新机器上，确认：
-
-- `symi status` 显示 Gateway 网关正在运行
-- 你的渠道仍然连接（例如 WhatsApp 不需要重新配对）
-- 仪表板打开并显示现有会话
-- 你的工作区文件（记忆、配置）存在
-
-## 相关内容
-
-- [Doctor](/gateway/doctor)
-- [Gateway 网关故障排除](/gateway/troubleshooting)
-- [Symi 在哪里存储数据？](/help/faq#where-does-symi-store-its-data)

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

@@ -1,99 +0,0 @@
----
-read_when:
-  - 你想要可复现、可回滚的安装
-  - 你已经在使用 Nix/NixOS/Home Manager
-  - 你想要所有内容都固定并以声明式管理
-summary: 使用 Nix 声明式安装 Symi
-title: Nix
-x-i18n:
-  generated_at: "2026-02-03T07:49:51Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: f1452194cfdd74613b5b3ab90b0d506eaea2d16b147497987710d6ad658312ba
-  source_path: install/nix.md
-  workflow: 15
----
-
-# Nix 安装
-
-使用 Nix 运行 Symi 的推荐方式是通过 **[nix-symi](https://github.com/symi/nix-symi)** — 一个开箱即用的 Home Manager 模块。
-
-## 快速开始
-
-将此粘贴给你的 AI 智能体（Claude、Cursor 等）：
-
-```text
-I want to set up nix-symi on my Mac.
-Repository: github:symi/nix-symi
-
-What I need you to do:
-1. Check if Determinate Nix is installed (if not, install it)
-2. Create a local flake at ~/code/symi-local using templates/agent-first/flake.nix
-3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
-4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
-5. Fill in the template placeholders and run home-manager switch
-6. Verify: launchd running, bot responds to messages
-
-Reference the nix-symi README for module options.
-```
-
-> **📦 完整指南：[github.com/symi/nix-symi](https://github.com/symi/nix-symi)**
->
-> nix-symi 仓库是 Nix 安装的权威来源。本页只是一个快速概述。
-
-## 你将获得
-
-- Gateway 网关 + macOS 应用 + 工具（whisper、spotify、cameras）— 全部固定版本
-- 重启后仍能运行的 Launchd 服务
-- 带有声明式配置的插件系统
-- 即时回滚：`home-manager switch --rollback`
-
----
-
-## Nix 模式运行时行为
-
-当设置 `SYMI_NIX_MODE=1` 时（nix-symi 会自动设置）：
-
-Symi 支持 **Nix 模式**，使配置确定性并禁用自动安装流程。
-通过导出以下环境变量启用：
-
-```bash
-SYMI_NIX_MODE=1
-```
-
-在 macOS 上，GUI 应用不会自动继承 shell 环境变量。你也可以通过 defaults 启用 Nix 模式：
-
-```bash
-defaults write bot.molt.mac symi.nixMode -bool true
-```
-
-### 配置 + 状态路径
-
-Symi 从 `SYMI_CONFIG_PATH` 读取 JSON5 配置，并将可变数据存储在 `SYMI_STATE_DIR` 中。
-
-- `SYMI_STATE_DIR`（默认：`~/.symi`）
-- `SYMI_CONFIG_PATH`（默认：`$SYMI_STATE_DIR/symi.json`）
-
-在 Nix 下运行时，将这些显式设置为 Nix 管理的位置，以便运行时状态和配置不会进入不可变存储。
-
-### Nix 模式下的运行时行为
-
-- 自动安装和自我修改流程被禁用
-- 缺失的依赖会显示 Nix 特定的修复消息
-- 存在时 UI 会显示只读 Nix 模式横幅
-
-## 打包注意事项（macOS）
-
-macOS 打包流程期望在以下位置有一个稳定的 Info.plist 模板：
-
-```
-apps/macos/Sources/Symi/Resources/Info.plist
-```
-
-[`scripts/package-mac-app.sh`](https://github.com/symi/symi/blob/main/scripts/package-mac-app.sh) 将此模板复制到应用包中并修补动态字段（bundle ID、版本/构建号、Git SHA、Sparkle 密钥）。这使 plist 对于 SwiftPM 打包和 Nix 构建保持确定性（它们不依赖完整的 Xcode 工具链）。
-
-## 相关内容
-
-- [nix-symi](https://github.com/symi/nix-symi) — 完整设置指南
-- [向导](/start/wizard) — 非 Nix CLI 设置
-- [Docker](/install/docker) — 容器化设置

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

@@ -1,8 +0,0 @@
----
-summary: Node.js 安装与配置（Symi 版本要求、安装方式与 PATH 排错）
-title: Node.js
----
-
-# Node.js
-
-该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Node.js](/install/node)。

package/docs/zh-CN/install/northflank.mdx

@@ -1,56 +0,0 @@
----
-title: 在 Northflank 上部署
-x-i18n:
-  generated_at: "2026-02-01T21:19:03Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: ad0be8dda41c51d0b6424259316db1b22be5216434f5879f21a5e8c60e0a2ee0
-  source_path: northflank.mdx
-  workflow: 15
----
-
-通过一键模板在 Northflank 上部署 Symi，然后在浏览器中完成设置。
-这是最简单的"无需在服务器上使用终端"的方式：Northflank 为你运行 Gateway网关，
-你通过 `/setup` 网页向导配置一切。
-
-## 如何开始
-
-1. 点击 [Deploy Symi](https://northflank.com/stacks/deploy-symi) 打开模板。
-2. 如果你还没有账户，请创建一个 [Northflank 账户](https://app.northflank.com/signup)。
-3. 点击 **Deploy Symi now**。
-4. 设置必需的环境变量：`SETUP_PASSWORD`。
-5. 点击 **Deploy stack** 构建并运行 Symi 模板。
-6. 等待部署完成，然后点击 **View resources**。
-7. 打开 Symi 服务。
-8. 打开公开的 Symi URL，在 `/setup` 完成设置。
-9. 在 `/symi` 打开控制面板 UI。
-
-## 你将获得
-
-- 托管的 Symi Gateway网关 + 控制面板 UI
-- `/setup` 处的网页设置向导（无需终端命令）
-- 通过 Northflank Volume（`/data`）实现持久化存储，配置/凭据/工作区在重新部署后不会丢失
-
-## 设置流程
-
-1. 访问 `https://<your-northflank-domain>/setup` 并输入你的 `SETUP_PASSWORD`。
-2. 选择模型/认证提供商并粘贴你的密钥。
-3. 点击 **Run setup**。
-4. 在 `https://<your-northflank-domain>/symi` 打开控制面板 UI。
-
-如果 Telegram 私信设置为配对模式，设置向导可以审批配对码。
-
-## 获取聊天令牌
-
-### Telegram 机器人令牌
-
-1. 在 Telegram 中给 `@BotFather` 发消息
-2. 运行 `/newbot`
-3. 复制令牌（格式如 `123456789:AA...`）
-4. 将其粘贴到 `/setup` 中
-
-5. **New Application** → 选择一个名称
-6. **Bot** → **Add Bot**
-7. 在 Bot → Privileged Gateway Intents 下**启用 MESSAGE CONTENT INTENT**（必需，否则机器人启动时会崩溃）
-8. 复制 **Bot Token** 并粘贴到 `/setup` 中
-9. 邀请机器人加入你的服务器（OAuth2 URL Generator；权限范围：`bot`、`applications.commands`）