入门指南

安装与更新

安装、升级、修复、健康检查与卸载。

系统要求

项目	要求
操作系统	macOS（Apple Silicon 或 Intel）、Linux（x64）或 Windows 10/11（x64·PowerShell）
opencode	1.x ≥ 1.17.11（建议装 1.x 最新版·Spiry 在最新 1.x 上认证·不支持 2.x）——需自行安装；已有的正常 1.x 不会被改动
Bun	≥ 1.3.14（安装脚本会自动处理）
网络	需要能访问 `spiry.yundy.net`

首次安装

三平台通用。Bun 缺失会自动装好；opencode 需要你先自行装好（1.x ≥ 1.17.11·建议最新版）——分系统的官方安装方式见下：

opencode 官方安装指引（分系统）

opencode 是 Spiry 的宿主，请用官方渠道自行安装 1.x 系列（建议最新版）。官方文档：opencode.ai/docs。

系统	官方安装方式
macOS / Linux	官方安装脚本——不带版本号即自动装 1.x 最新版（脚本自身会拒绝 2.x）
Windows · 原生 PowerShell	npm 方式（需先装 Node.js LTS）；`@1` 表示 1.x 系列最新版，天然排除 2.x。此路径我们已在真机验证
Windows · WSL（官方推荐）	官方建议 Windows 用户在 WSL 里运行：先按微软指南装 WSL，再在 WSL 终端执行下面的官方脚本；项目通过 `/mnt/c/…` 访问

macOS / Linux（以及 Windows 的 WSL 终端）：

curl -fsSL https://opencode.ai/install | bash

Windows（PowerShell）：

npm install -g opencode-ai@1 --registry https://registry.npmjs.org

装完自查：opencode --version → 显示 1.x（1.17.11 及以上）即可。

关于 2.x 系列opencode 官网首页当前主推 v2，安装时请注意选择 1.x。2.x 是独立的包（@opencode/cli），Spiry 暂不支持；opencode 2 将由我们的后续产品 SpiryCode 原生支持。上述两条命令只会装到 1.x，无需你指定版本号：官方安装脚本本身就只服务 1.x（它取 opencode-ai 包的最新版本，而该包只发布 1.x；脚本还会校验版本号形如 1.x.y，并刻意避开 GitHub 的 latest release——因为那可能是 2.x）；npm 那条的 @1 是版本范围写法，含义是「1.x 系列里的最新版」，按定义排除 2.x。

Linux / macOS（bash）：

curl -fsSL https://spiry.yundy.net/install/v61 | bash

Windows（PowerShell）：

irm https://spiry.yundy.net/install/v61.ps1 | iex

安装脚本会：

检测系统环境（架构、已安装版本）
自动安装 Bun（缺失时经 Spiry 镜像安装）；检查 opencode 版本——缺失或版本不符时暂停，并给出明确的安装指引（安装哪个版本、如何安装、完成后重新运行本命令）
提示你输入安装码——建议等到提示出现时再去控制台生成（安装码 10 分钟内有效，提前生成容易过期）
下载并安装 Spiry 到系统凭据管理的安全位置
自动运行健康检查（doctor）
配置 opencode 插件入口

安装成功后，打开或重启 opencode 即可生效。

升级

当 Spiry 发布新版本时，你可以用同一条命令升级：

curl -fsSL https://spiry.yundy.net/install/v61 | bash

脚本会自动检测到已安装的版本并执行升级。升级与安装一样需要输入安装码（登录 Spiry 官网，在个人控制台点「获取 Spiry 安装码」，再点「生成 Spiry 安装码」）——它同时是升级资格校验。

升级后如何确保生效

每个项目目录需要重启两次 opencode 才能生效。第一次重启时，插件会自动将该目录下的治理文件更新到最新版；第二次重启时，更新后的内容才会被加载生效。

如果你升级后遇到异常：

退出当前 opencode 会话（ctrl+c 或输入 /exit）
重新启动 opencode——插件加载时会自动把标准区刷新到最新版

自动更新从 0.6.3 起，Spiry 插件加载时会自动刷新 AGENTS.md 标准区和增补件标准区到最新版。你的项目特有内容（项目区）绝不会被覆盖。

健康检查（Doctor）

如果你怀疑安装有问题，可以手动运行健康检查：

spiry-install doctor

Doctor 会逐项检查并报告 PASS / FAIL：

文件完整性（WAL 恢复、精确校验）
托管入口点是否正常
系统凭据是否可用
服务器授权状态

退出码：0 = 全部通过，4 = 有失败项，5 = 待补偿（可修复）。

修复安装

如果安装损坏或文件缺失，可以修复：

spiry-install repair

Repair 会重新下载并安装服务器确认的版本，不需要重新输入安装码。

卸载

spiry-install uninstall

卸载默认保留凭据和设备 ID，方便日后重新安装。如果你想完全清除：

spiry-install uninstall --purge

卸载后设备槽卸载时，Spiry 会尝试通知服务器释放设备槽。如果服务器不可达，卸载会返回 partial 状态、保留 wrapper 供后续重试。使用 --accept-offline-device 可显式接受离线卸载的风险。

卸载 opencode 本体（可选）

opencode 与 Spiry 是宿主与插件的关系——上面的命令只卸载 Spiry，不影响 opencode（你可以继续用 opencode 干活）。如果连 opencode 本体也想移除：它经一键命令安装后就是一个单文件——

macOS / Linux：

rm ~/.opencode/bin/opencode

Windows（PowerShell·直接复制执行）：

Remove-Item "$env:USERPROFILE.opencodeinopencode.exe" -Force

macOS / Linux 再顺手删掉 shell 配置文件（~/.zshrc·macOS bash 用户在 ~/.bash_profile·Linux bash 用户在 ~/.bashrc）里 SPIRY-OPENCODE-PATH 开头的两行受管块即可；Windows 无需此步（PATH 由安装器写入注册表·指向已删目录的残留条目无害，介意可在「编辑账户环境变量」中移除 %USERPROFILE%.opencodein）。opencode 自己的配置与数据在 ~/.config/opencode 与 ~/.local/share/opencode（含 provider 凭据 auth.json·Windows 在 %USERPROFILE%.configopencode 与 %LOCALAPPDATA%opencode），想彻底清除可一并删除。

故障排查

安装脚本报错「权限不足」

确保你对用户状态目录（~/.local/state/spiry/）有读写权限。若目录权限被改动过，删除该目录后重装即可自愈重建。

opencode 加载后看不到 Spiry 命令

检查 .opencode/commands/ 目录下是否有 spiry-*.md 文件。如果没有，在 opencode 对话中输入 /spiry-init 重新铺设命令文件。

首次启动后插件无响应（面板出现感叹号 / 黑箱无法启动）

opencode 在启动瞬间对插件与标准件做快照——首次打开时可能提示「插件已更新」、看不到 /spiry-* 命令、或 SPIRY 面板的开关操作带感叹号。这多数是正常时序而非故障：完全退出 opencode（ctrl+c 或 /exit）再打开一次即可。若重启后仍不正常：重跑同一条安装命令——已装好的部分（opencode、Bun）会自动跳过，只会重新安装并修复 Spiry 本身，输入安装码即完成。

插件加载报错

运行 spiry-install doctor 检查安装完整性。如果 Doctor 报 FAIL，尝试 spiry-install repair。