Docs SpiryCode 登录

入门指南

快速开始

五分钟从安装到第一次使用。

前置条件

  • opencode（≥ 1.17.11）——AI 编程助手的运行引擎。如果你还没安装，请先参考 opencode 官方文档。
  • 一个 Spiry 账号，并通过接引考试——安装码与令牌在通过考试后才解锁，见 接引考试与认证。
  • macOS（Apple Silicon 或 Intel） 或 Linux（x64）。

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

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。

红线脏工作区（有未提交改动）不要动手；绝不 rm -rf .git 重新 init——历史会全部丢失；除非你明确知道自己在做什么，不要用 filter-repo 之类的历史重写工具——挪动 commit 就是标准做法，历史一个不少。

第一步：获取安装码

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

第二步：安装 Spiry

打开终端，粘贴以下命令一键安装：

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

安装过程中会提示你输入安装码，将上一步获取的安装码粘贴进去即可。安装脚本会自动检测系统环境、下载 Spiry、完成配置。

安装码 vs 令牌安装码用于首次安装（把 Spiry 装到设备上）；令牌是设备的长期身份凭证（安装后自动写入系统凭据，日常使用不需要手动管理）。详见 令牌体系。

第三步：在项目里启用 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 仓根、且里面直接就是源码？是，就需要仓根上移；如果你的源码已经在某个子目录里、仓根在更上一层，则跳过第二步。

考古接入是一次性动作intake 是项目接手时做一次的动作——让 AI 从零建立对你的项目的理解。完成之后，日常的认知更新靠每次收尾时自动写入记忆宫殿，不需要重复 intake。与 /spiry-review 不同——review 是日常常用的质量审查，intake 是一次性的认知建立。

开始使用

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

  • 你提出需求 → Spiry 自动帮你梳理成结构化需求文档
  • 你要做方案 → Spiry 自动帮你产出四层结构方案
  • 你要做测试 → Spiry 自动帮你把要测的需求收敛成测试设计草稿，客观事实问清绝不瞎猜
  • 你完成一段工作 → Spiry 提醒你按收尾协议落盘
  • 你要收工 → 输入 /spiry-close 一键完成收尾
第一次不用紧张Spiry 的设计是渐进增强的——你不主动调命令，它也不会干扰你的正常工作流。随着使用深入，你会发现越来越多 Spiry 在后台帮你的场景。

版本维护

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

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

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

下一步

下一篇 →安装与更新