GSD 快速开始指南：macOS / Windows / Linux 安装、配置与首个会话实战

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

GSD 是一个以规划、执行、验证和交付为核心职责的 AI 编程代理，本指南带你完成它在 macOS、Windows、Linux 及 Docker 沙箱中的安装与配置，并启动你的第一个会话。读完本文，你将掌握 Node.js 与 Git 的前置环境搭建、LLM Provider 的接入方式、步骤模式与自动模式两种工作方式，以及会话恢复、更新升级和常见故障的排查方法。

前置条件

在安装 GSD 之前，请先确认你的机器满足以下最低要求。GSD 本身是 Node.js 应用，package.json 中的engines字段明确要求Node.js >= 22.0.0，因此版本检查是启动是否正常的关键一步。

如果你还没有安装 Node.js 或 Git，请按下面对应操作系统的步骤进行。

说明：从源码看，GSD 还依赖若干平台原生二进制（见 package.json 中的 optionalDependencies，如@gsd-build/engine-darwin-arm64、@gsd-build/engine-linux-x64-gnu、@gsd-build/engine-win32-x64-msvc等），安装时会按平台自动选择，无需手工处理。

按操作系统安装

macOS

下载链接：Node.js | Git | Homebrew

第 1 步：安装 Homebrew（如果已安装可跳过）：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

第 2 步：安装 Node.js 和 Git：

brew install node git

第 3 步：验证依赖已安装：

node --version # 应输出 v22.x 或更高 git --version # 应输出 2.20+

第 4 步：安装 GSD：

npm install -g gsd-pi

第 5 步：设置你的 LLM provider：

# 选项 A：设置环境变量（推荐 Anthropic） export ANTHROPIC_API_KEY="sk-ant-..." # 选项 B：使用内置配置向导 gsd config

如果想永久保存这个 key，把 export 语句写入~/.zshrc：

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc source ~/.zshrc

所有 20+ provider 的完整配置方式请见 提供商设置指南。

第 6 步：启动 GSD：

cd ~/my-project # 进入任意项目目录 gsd # 启动一个会话

第 7 步：确认一切正常：

gsd --version # 输出已安装版本

进入会话后，输入/model以确认你的 LLM 已成功连接。

Apple Silicon PATH 修复：如果安装后找不到gsd，可能是 npm 的全局 bin 目录没有加入 PATH：

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc source ~/.zshrc

oh-my-zsh 冲突：oh-my-zsh 的 git 插件定义了alias gsd='git svn dcommit'。可在~/.zshrc中加入unalias gsd 2>/dev/null，或者改用gsd-cli（GSD 在 package.json 的 bin 字段中同时注册了gsd与gsd-cli两个命令，后者可绕开 shell alias 冲突）。

Windows

下载链接：Node.js | Git for Windows | Windows Terminal

选项 A：使用 winget（推荐 Windows 10/11）

第 1 步：安装 Node.js 和 Git：

winget install OpenJS.NodeJS.LTS winget install Git.Git

第 2 步：重启终端（关闭并重新打开 PowerShell 或 Windows Terminal）。

第 3 步：验证依赖已安装：

node --version # 应输出 v22.x 或更高 git --version # 应输出 2.20+

第 4 步：安装 GSD：

npm install -g gsd-pi

第 5 步：设置你的 LLM provider：

# 选项 A：设置环境变量（仅当前会话） $env:ANTHROPIC_API_KEY = "sk-ant-..." # 选项 B：使用内置配置向导 gsd config

如果要永久保存该 key，可在系统设置的环境变量中添加，或者执行：

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-...", "User")

第 6 步：启动 GSD：

cd C:\Users\you\my-project # 进入任意项目目录 gsd # 启动一个会话

第 7 步：确认一切正常：

gsd --version # 输出已安装版本

进入会话后，输入/model以确认你的 LLM 已成功连接。

选项 B：手动安装

1. 下载并安装 Node.js LTS，安装时勾选"Add to PATH"
2. 下载并安装 Git for Windows，使用默认选项
3. 打开一个新的终端，然后继续执行上面的第 3-7 步

Windows 提示：

• 建议使用Windows Terminal或PowerShell，体验最佳。Command Prompt 也能用，但颜色支持较弱。
• 如果gsd无法识别，先重启终端。Windows 需要新开终端才能读取更新后的 PATH。
• WSL2也可用，安装 WSL 后，在发行版内部按 Linux 说明继续。

Linux

下载链接：Node.js | Git | nvm

先确认你的发行版，然后按对应步骤安装。

Ubuntu / Debian

第 1 步：安装 Node.js 和 Git：

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - sudo apt-get install -y nodejs git

Fedora / RHEL / CentOS

第 1 步：安装 Node.js 和 Git：

curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash - sudo dnf install -y nodejs git

Arch Linux

第 1 步：安装 Node.js 和 Git：

sudo pacman -S nodejs npm git

使用 nvm（任意发行版）

第 1 步：先安装 nvm，再安装 Node.js：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash source ~/.bashrc # 或 ~/.zshrc nvm install 24 nvm use 24

所有发行版：第 2-7 步

第 2 步：验证依赖已安装：

node --version # 应输出 v22.x 或更高 git --version # 应输出 2.20+

第 3 步：安装 GSD：

npm install -g gsd-pi

第 4 步：设置你的 LLM provider：

# 选项 A：设置环境变量（推荐 Anthropic） export ANTHROPIC_API_KEY="sk-ant-..." # 选项 B：使用内置配置向导 gsd config

如果想永久保存这个 key，把 export 语句写到~/.bashrc（或~/.zshrc）中：

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc source ~/.bashrc

所有 20+ provider 的完整配置方式请见 提供商设置指南。

第 5 步：启动 GSD：

cd ~/my-project # 进入任意项目目录 gsd # 启动一个会话

第 6 步：确认一切正常：

gsd --version # 输出已安装版本

进入会话后，输入/model以确认你的 LLM 已成功连接。

npm install -g遇到权限错误？不要用sudo npm。应改为修复 npm 的全局目录：

mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc source ~/.bashrc npm install -g gsd-pi

Docker（任意操作系统）

下载链接：Docker Desktop

如果你不想在宿主机安装 Node.js，可以在隔离沙箱中运行 GSD。仓库提供了完整的 Docker 沙箱模板与 compose 文件，详见 docker 目录下的 Docker Sandbox 文档。

第 1 步：安装 Docker Desktop（要求 4.58+）。

第 2 步：克隆 GSD 仓库：

git clone https://github.com/gsd-build/gsd-2.git cd gsd-2/docker

第 3 步：创建并进入沙箱：

docker sandbox create --template . --name gsd-sandbox docker sandbox exec -it gsd-sandbox bash

第 4 步：设置 API key 并运行 GSD：

export ANTHROPIC_API_KEY="sk-ant-..." gsd auto "implement the feature described in issue #42"

沙箱模式下 GSD 无法接触宿主机文件系统、SSH key 或其他项目，适合把自动模式"扔进去跑"的场景。完整的配置、资源限制和 compose 文件请见 Docker Sandbox 文档。在没有 Docker Sandbox 支持的环境中，也可以改用 docker-compose.yaml 做容器级隔离。

安装之后

选择模型

完成 provider 设置后，GSD 会自动选择一个默认模型。你可以在会话中随时切换：

/model

也可以在偏好设置中按阶段配置模型，详见 配置文档。关于各 Provider 的认证方式与环境变量对照，可参考 提供商设置指南 中的快速参考表：Anthropic 用ANTHROPIC_API_KEY、OpenAI 用OPENAI_API_KEY、Gemini 用GEMINI_API_KEY、OpenRouter 用OPENROUTER_API_KEY，本地 providers（Ollama、LM Studio、vLLM、SGLang）则需要在~/.gsd/agent/models.json中声明 endpoint 与 models。

实现细节：gsd config对应源码 src/cli.ts 中的 setup wizard 分支，它会通过 onboarding 流程把凭据写入~/.gsd/agent/auth.json并持久化，因此你可以在任意新终端直接启动gsd，而不必重复 export 环境变量。

两种工作方式

步骤模式 —/gsd

在会话内输入/gsd。GSD 会一次执行一个工作单元，并在每一步之间暂停，通过向导展示刚完成了什么、下一步是什么。

• 没有.gsd/目录：启动讨论流程，先收集你的项目愿景
• 已有 milestone，但没有 roadmap：讨论或研究该 milestone
• roadmap 已存在，仍有待完成的 slices：规划下一个 slice 或执行一个 task
• 进行到一半的 task：从上次停下的地方继续

步骤模式会让你始终留在回路中，在每一步之间查看和确认输出。

自动模式 —/gsd auto

输入/gsd auto后就可以离开。GSD 会自主完成 research、planning、execution、verification、commit，并持续推进每个 slice，直到 milestone 完成。

/gsd auto

自动模式本质是一个由磁盘文件驱动的状态机：它读取.gsd/STATE.md确定下一个工作单元，创建全新会话执行，完成后再次读取磁盘状态并派发下一个单元。完整的执行循环、崩溃恢复、超时监管与成本跟踪等细节，请见 自动模式文档。

推荐工作流：两个终端

一个终端跑自动模式，另一个终端负责引导和干预。

终端 1：让它构建

gsd /gsd auto

终端 2：在它工作时进行引导

gsd /gsd discuss # 讨论架构决策 /gsd status # 查看进度 /gsd queue # 排队下一个 milestone

两个终端都会读写同一套.gsd/文件。你在终端 2 里做出的决策，会在下一个阶段边界被自动拾取。从源码看，GSD 的会话按当前工作目录隔离存储（见 src/cli.ts 中的 per-directory session 逻辑），因此两个终端在同一个项目目录下运行gsd时，会共享同一份项目状态。

GSD 如何组织工作

GSD 用三层结构组织一次交付，核心思想是把大目标拆成可独立验证的小单元：

Milestone → 一个可交付版本（4-10 个 slice） Slice → 一个可演示的垂直能力（1-7 个 task） Task → 一个适合单个上下文窗口的工作单元

铁律是：一个 task 必须能装进一个上下文窗口。装不下，就说明它应该拆成两个 task。

所有状态都保存在.gsd/中（GSD 通过 SQLite 数据库保存权威运行时状态，并将 Markdown 投影渲染到.gsd/供审阅、提示词与 git 历史使用）：

.gsd/ PROJECT.md — 项目当前是什么 REQUIREMENTS.md — 需求契约 DECISIONS.md — 追加式架构决策记录 KNOWLEDGE.md — 手写 Rules，加上 memory 支撑的 Patterns/Lessons STATE.md — 一眼可见的状态摘要 milestones/ M001/ M001-ROADMAP.md — 带依赖关系的 slice 计划 slices/ S01/ S01-PLAN.md — task 拆解 S01-SUMMARY.md — 实际发生了什么

这一分层结构与自动模式的 "Plan → Execute → Complete → Reassess Roadmap → Validate Milestone" 执行循环一一对应，详见 自动模式文档。

VS Code 扩展

GSD 也提供 VS Code 扩展。你可以从扩展市场安装（publisher: FluxLabs），或者在 VS Code 扩展面板中直接搜索 "GSD"：

• @gsd聊天参与者：在 VS Code Chat 中直接与 agent 对话
• 侧边栏仪表板：显示连接状态、模型信息、Token 使用量
• 完整命令面板：启动 / 停止 agent、切换模型、导出会话

CLI（gsd-pi）需要先安装好，扩展会通过 RPC 与其连接。仓库中的 vscode-extension 目录包含完整的扩展源码实现。

Web 界面

GSD 也提供一个基于浏览器的可视化项目管理界面：

gsd --web

--web对应源码 src/cli.ts 中的 web 模式分支，它启动一个浏览器专用的 Web 模式，不依赖终端 TUI。详见 Web 界面文档。

恢复会话

gsd --continue # 或 gsd -c

会恢复当前目录最近一次会话。源码中的实现路径是 src/cli.ts 的SessionManager.continueRecent，它会按当前工作目录定位最近的会话并恢复。

浏览所有保存过的会话：

gsd sessions

该命令会列出当前目录下所有历史会话并支持选择恢复（见 src/cli.ts 中的 sessions 列表逻辑）。如果某个目录还没有会话，会给出 "No sessions found for this directory." 的提示。

更新 GSD

GSD 每 24 小时检查一次更新，并在启动时提示。你也可以手动更新：

npm update -g gsd-pi

或者在会话中执行：

/gsd update

gsd update在源码中会绕过 TTY 门禁直接执行更新流程（见 src/cli.ts 中的 update 分支），确保用户在任何状态下都能升级。另外，当检测到资源版本与当前二进制版本不一致时，CLI 会提示运行npm install -g gsd-pi@latest或gsd update后再继续（见 src/cli.ts 的版本检查）。

快速排障

需要注意的排障要点：

• 环境变量未生效：key 虽然设在 shell 中，但 GSD 看不到。确认你是在同一个终端里 export 后运行gsd，或者直接用gsd config把 key 保存进~/.gsd/agent/auth.json实现跨会话持久化。
• 模型没出现在/model列表：对于 OpenRouter 这类按 key 聚合的 provider，未设置对应环境变量时 GSD 会隐藏其 models；设置 key 并重启gsd即可。
• 本地模型报developerrole 错误：大多数本地推理 server 不支持 OpenAI 的developermessage role，需要在 provider 配置中设置compat.supportsDeveloperRole: false，GSD 会自动改用systemmessage。

更多问题见 故障排查文档。

下一步

• 自动模式：深入理解自主执行
• 配置：模型选择、超时和预算
• 命令参考：所有命令和快捷键
• 提供商设置：每个 provider 的详细配置
• 团队协作：多开发者工作流

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用