入门指南
安装与更新
安装、升级、修复、健康检查与卸载。
系统要求
| 项目 | 要求 |
|---|---|
| 操作系统 | macOS（Apple Silicon 或 Intel）或 Linux（x64） |
| opencode | ≥ 1.17.11 |
| Bun | ≥ 1.3.14（安装脚本会自动处理） |
| 网络 | 需要能访问 spiry.yundy.net |
首次安装
curl -fsSL https://spiry.yundy.net/install/v33 | bash安装脚本会：
- 检测系统环境（架构、已安装版本）
- 提示你输入安装码（从 控制台 获取）
- 下载并安装 Spiry 到系统凭据管理的安全位置
- 自动运行健康检查（doctor）
- 配置 opencode 插件入口
安装成功后，打开或重启 opencode 即可生效。
升级
当 Spiry 发布新版本时，你可以用同一条命令升级：
curl -fsSL https://spiry.yundy.net/install/v33 | bash脚本会自动检测到已安装的版本并执行升级。升级与安装一样需要输入安装码（登录 Spiry 官网，在个人控制台点「生成安装码」获取）——它同时是升级资格校验。
升级后如何确保生效
每个项目目录需要重启两次 opencode 才能生效。第一次重启时，插件会自动将该目录下的治理文件更新到最新版；第二次重启时，更新后的内容才会被加载生效。
如果你升级后遇到异常：
- 退出当前 opencode 会话（
ctrl+c或输入/exit） - 重新启动 opencode——插件加载时会自动把标准区刷新到最新版
自动更新从 0.6.3 起，Spiry 插件加载时会自动刷新 AGENTS.md 标准区和增补件标准区到最新版。你的项目特有内容（项目区）绝不会被覆盖。
健康检查（Doctor）
如果你怀疑安装有问题，可以手动运行健康检查：
spiry-install doctorDoctor 会逐项检查并报告 PASS / FAIL：
- 文件完整性（WAL 恢复、精确校验）
- 托管入口点是否正常
- 系统凭据是否可用
- 服务器授权状态
退出码：0 = 全部通过，4 = 有失败项，5 = 待补偿（可修复）。
修复安装
如果安装损坏或文件缺失，可以修复：
spiry-install repairRepair 会重新下载并安装服务器确认的版本，不需要重新输入安装码。
卸载
spiry-install uninstall卸载默认保留凭据和设备 ID，方便日后重新安装。如果你想完全清除：
spiry-install uninstall --purge卸载后设备槽卸载时，Spiry 会尝试通知服务器释放设备槽。如果服务器不可达，卸载会返回 partial 状态、保留 wrapper 供后续重试。使用
--accept-offline-device 可显式接受离线卸载的风险。故障排查
安装脚本报错「权限不足」
确保你对用户状态目录（~/.local/state/spiry/）有读写权限。若目录权限被改动过，删除该目录后重装即可自愈重建。
opencode 加载后看不到 Spiry 命令
检查 .opencode/commands/ 目录下是否有 spiry-*.md 文件。如果没有，在 opencode 对话中输入 /spiry-init 重新铺设命令文件。
插件加载报错
运行 spiry-install doctor 检查安装完整性。如果 Doctor 报 FAIL，尝试 spiry-install repair。