快速开始

前置条件

• opencode（1.x·1.17.11 或更高·建议装最新版·不支持 2.x）——AI 编程助手的运行引擎，需要你自己用官方渠道安装，分系统的具体命令见下方 opencode 官方安装指引。已经装着可用 1.x 的不用动——安装 Spiry 的命令会检查版本，仅在缺失或版本不符时暂停，并给出明确的安装指引（安装哪个版本、如何安装、完成后如何继续）。
• Bun（≥ 1.3.14）——Spiry 的运行时（安装脚本会检测，缺失时会给出对应系统的安装指引）。
• 一个 Spiry 账号，并通过接引考试——安装码与令牌在通过考试后才解锁，见 接引考试与认证。
• macOS（Apple Silicon 或 Intel）、Linux（x64） 或 Windows 10/11（x64·PowerShell）。

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

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

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 及以上）即可。

目录用法：一个目录，一个项目

Spiry 的记忆宫殿（.spiry/）建在你打开的工作目录下，只为这一个项目服务。因此目录的组织方式直接决定 Spiry 服务质量：

• 每个项目的源码目录应独立占据自己的一个父目录。打开该父目录工作，Spiry 就只服务这一个项目。
• 要接入另一个项目时，跳出当前父目录，另建一个新的父目录放置该项目的源码，然后在新父目录下打开 opencode。
• 切勿把两个互不相干的项目放在同一个父目录下、直接打开这个父目录工作——两份项目记忆会写进同一座记忆宫殿、互相污染。

治理文件与 git：记忆必须进 git

AGENTS.md 与 .spiry/ 记忆宫殿是项目的记忆载体，必须纳入 git 追踪——跨设备的无缝承接、多人协作的记忆接力、跨会话的 Agent 接续，全靠 git 同步。把它们排除在 git 之外（比如写进 .gitignore），等于让项目记忆只活在单台设备上、随时可能丢失。

理想布局里这不需要任何额外动作：你打开的工作目录（源码的父目录）本身就是 git 仓根，治理文件与源码子目录同处根下，天然全部在 git 追踪之内。

已进行中的项目：git 仓根就是源码根，怎么办？

很多项目的 git 仓根直接就是源码根。半路接入 Spiry 时，治理文件要落在源码的父目录里，就会遇到尴尬：父目录不在 git 仓内，治理文件进不了 git。

正确的解法是把 git 仓根上移一级：源码目录降为仓内子目录，全部 commit 历史完整保留（零历史重写）。目标状态长这样：

your-project/          ← 新 git 仓根（opencode 打开的目录）
├── AGENTS.md          ← 治理文件，进 git
├── .spiry/            ← 记忆宫殿，进 git
└── source/            ← 原源码整体降为子目录（名字自定）
    └── ...            ← 原有文件，commit 历史一个不少

这不需要手动操作——Spiry 提供了一等公民工具，一键完成。

/spiry-root-build

在 opencode 里敲这条命令，或直接跟 Agent 说「把仓根上移」，Agent 会调用 spiry_root_build 工具。工具全自动完成五件事：

1. 七项预检：脏工作区、detached HEAD、多 worktree、重名子目录等不安全条件一律拒搬——宁可不动也不冒险。已部署过 Spiry 治理文件不阻碍上移（治理文件会留在仓根不动）。
2. 自动备份：搬移前在仓外同级目录建完整备份，验证无误后才删除。
3. 原子搬移：源码整体降为子目录（默认名 source，可指定），.git 留在新根。如果仓根已有 Spiry 治理文件（.spiry/ + AGENTS.md），它们会留在仓根不动、不随源码降级。
4. 登记 commit：自动 git add -A && git commit，全程零手动 git 操作。
5. 证据集：产出六项客观验收证据（commit 增量、工作区状态、远端不变、布局正确、未 push 数、备份路径），你只需核对。

全程零历史重写——只多一个「挪动」commit，原有历史一个不少。搬移完成后，工具会根据当前状态牵引下一步：尚未部署治理骨架的，牵引 /spiry-init + /spiry-intake；已经 init 过的，只需 /spiry-intake。

第一步：安装 opencode（官方渠道）

通过官方渠道安装 opencode 1.x（建议最新版）——分系统命令见上方 opencode 官方安装指引。已在正常使用 1.x（≥ 1.17.11）的可跳过这一步：安装 Spiry 的命令不会改动它。

第二步：运行 Spiry 安装命令

打开终端，粘贴对应系统的命令（Linux / macOS 用 bash，Windows 用 PowerShell——开始菜单搜索 "PowerShell" 回车即可打开）。Bun 缺失会自动装好；opencode 若缺失或版本不符，命令会暂停并给出明确的安装指引，完成后重新运行本命令即可继续：

Linux / macOS（bash）：

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

Windows（PowerShell）：

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

命令会自行检测环境、下载 Spiry、完成配置。

第三步：生成并输入安装码

安装过程中会提示输入安装码。建议在提示出现时再生成——安装码10 分钟内有效，若先生成安装码、再安装 opencode 或查阅资料，容易超时失效。

1. 访问 Spiry 控制台，用手机号登录。
2. 先通过接引考试——未通过时签发安装码会被拒绝，详见 接引考试与认证。
3. 找到「安装码」区域，点击「签发安装码」，复制生成的码。
4. 回到终端粘贴、回车，安装继续。

第四步：在项目里启用 Spiry

安装完成后，进入你的项目目录，启动 opencode：

cd your-project
opencode

opencode 启动时会自动加载 Spiry 插件。接下来根据你的项目阶段，选择对应的接入路径：

全新项目接入

从零开始的新项目，只需一步——部署治理骨架：

/spiry-init

Spiry 会为你的项目部署治理骨架（AGENTS.md + .spiry/ 记忆宫殿三屋）。部署是非破坏性的——如果你已有 AGENTS.md，Spiry 会保留你的内容、只补充 Spiry 标准入口。

初始化完成后，直接开始使用即可。

开发中的项目接入

已有代码存量的项目，完整接入分三步：

1. 部署治理骨架：/spiry-init——部署 AGENTS.md + .spiry/ 记忆宫殿。
2. 仓根上移（仅当 git 仓根＝源码根时需要）：/spiry-root-build——把仓根上移一级，治理文件留根、源码降为子目录。详见上文。
3. 考古接入：/spiry-intake——机械采集 git 历史/技术栈/目录/README，加工成记忆宫殿草稿 + 追问清单。多轮迭代直到认知收敛。

拿不准第二步是否需要？判断标准很简单：你打开的目录（opencode 的工作目录），它本身就是 git 仓根、且里面直接就是源码？是，就需要仓根上移；如果你的源码已经在某个子目录里、仓根在更上一层，则跳过第二步。

开始使用

初始化完成后，你就可以像平常一样和 AI 对话了。Spiry 会在后台默默工作：

• 你提出需求 → Spiry 自动帮你梳理成结构化需求文档
• 你要做方案 → Spiry 自动帮你产出四层结构方案
• 你要做测试 → Spiry 自动帮你把要测的需求收敛成测试设计草稿，客观事实问清绝不瞎猜
• 你完成一段工作 → Spiry 提醒你按收尾协议落盘
• 你要收工 → 输入 /spiry-close 一键完成收尾

版本维护

Spiry 的升级全程自动，无需任何手动命令：

• 插件本体：重新运行安装命令即可升级，见 安装与更新。
• 项目内标准件（根 AGENTS.md 与增补件的标准区）：每次启动 opencode、插件加载时自动刷新到框架最新版；项目区与记忆宫殿绝不触碰。

原 /spiry-update 命令已废弃——它的职能已被加载期自动刷新完全覆盖。

下一步

• 了解 Spiry 的文件结构：记忆宫殿
• 看全部可用命令：命令手册
• 了解 Spiry 能做什么：核心能力
• 遇到问题？：安装与更新（含故障排查）