GSD Pi v1.20.1 中文教程：GSD-2 迁移、运行与验证

旧页面所称 GSD-2 当前已转到 open-gsd/gsd-pi，安装包是 @opengsd/gsd-pi。它把终端编码 Agent、计划、验证证据、本地项目记忆和 worktree 感知的 Git 自动化组合起来。当前正式版 v1.20.1发布于 2026 年 9 月 18 日，要求 Node.js 22.18.0 以上。

路径一：官方引导安装

node --version
npx @opengsd/gsd-pi@latest
command -v gsd
gsd --version
cd /path/to/test-repo
gsd

引导流程会选择模型提供商并写入用户级资源。进入项目后先用 /gsd config 查看配置，/gsd status 查看状态，再用 /gsd quick "为现有函数补一条边界测试" 做小任务。预期产生可审阅的代码差异，并在 .gsd/ 留下需求、计划、运行笔记或验证证据。模型输出“完成”只是信号，必须运行仓库测试并查看 Git diff。

路径二：固定全局包与非交互验证

npm install -g @opengsd/gsd-pi@1.20.1
gsd --version
gsd quick --output-format json "只更新一条可回滚的测试"

固定版本适合团队基线和 CI 前的可重复检查。JSON 输出用于机器读取，但不要只验 JSON 是否可解析；还要检查 exit code、changed files、测试证据和任务是否越界。GSD Pi 可接多种 provider，提示、代码和工具结果是否出机取决于所选提供商。API key 放在宿主支持的凭证位置，不要写进 .gsd/ 或仓库。

从旧 unscoped 包迁移

cp -R .gsd .gsd.backup
npm uninstall -g gsd-pi @opengsd/gsd-pi
rm -f ~/.gsd/.update-check ~/.gsd/agent/managed-resources.json
npx @opengsd/gsd-pi@latest
command -v gsd
gsd --version

删除命令来自官方迁移说明，执行前仍要确认路径。若旧包用 sudo 安装，只对卸载旧包使用相同权限；不要把整个新安装长期放在 root 环境。项目的 .gsd/ 是可版本控制的状态，而 .gsd-backups/ 等 sibling runtime 目录通常被忽略，用于迁移快照。升级后打开旧项目，确认阶段、任务与验证证据能读取，再继续自动模式。

排错、权限和升级

gsd 仍指向旧路径时用 command -v、npm prefix -g 查 PATH；pnpm 全局目录未进 PATH 时先执行 pnpm setup 并重开终端。任务卡住时先检查 provider 登录、模型、Git 工作区和 worktree，再检查 .gsd/ 状态；不要直接删状态掩盖问题。常规升级使用 gsd upgrade，升级前提交代码并备份 .gsd/。v1.20.1 主要修复租约、失败 UAT 证据和孤立 worktree 的恢复逻辑，升级后应用一个失败测试样例验证错误能被保留。

与 OpenAI Codex 的实际区别

Codex CLI 是通用编码 Agent，可在仓库中读写、运行命令和完成任务。GSD Pi 在终端 Agent 之上强调项目级结构：milestone、slice、task、.gsd/ 记忆、验证证据和 worktree 自动化。需要直接处理一个明确编码任务时，Codex 的路径更短；需要把较长项目拆解、保存决策并反复推进时，GSD Pi 提供更多流程状态。两者都不能替代代码审查、测试和合并控制。

常见问题