快速上手：第一条 GSD 命令 - 和平哥的学习笔记

这是「GSD 全景代码解析」专题的第 5 篇。在上一篇（第 04 篇）中，我们深入剖析了 GSD 的目录结构哲学，理解了 dreams/、plans/、sessions/ 三大核心目录如何支撑从目标到执行的全链路管理。本篇将带你从零开始，完成 GSD 的安装并执行第一条实战命令 /gsd-new-project，真正进入 GSD 的工作流。

环境准备和前提条件

在正式安装 GSD 之前，请确保你的开发环境满足以下要求：

项目	最低版本	说明
Node.js	18.x	GSD 基于 Node.js 构建，推荐 20.x LTS
npm	9.x	包管理器，随 Node.js 一同安装
Git	2.30+	项目初始化和版本控制必需
AI IDE	—	Cursor、Windsurf 或 VS Code + Cline 等支持 slash command 的 IDE

你可以通过以下命令快速检查当前环境：

node --version
npm --version
git --version

如果 Node.js 尚未安装，建议通过 nvm 或 fnm 进行版本管理：

# 使用 nvm 安装 Node.js 20
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20

提示：GSD 的 /gsd-new-project 命令设计为在 AI IDE 的上下文感知环境中运行，因此建议使用 Cursor 或 Windsurf 以获得最佳体验。

安装 GSD

GSD 提供两种安装方式：一键安装脚本（推荐）和 npm 全局安装。选择适合你的方式即可。

方式一：通过安装脚本（推荐）

这是最简单、最快捷的方式。打开终端，执行以下命令：

curl -fsSL https://get.gsd.build/install.sh | bash

脚本会自动完成以下操作：

检测操作系统（macOS / Linux / WSL）
下载对应平台的最新版本
安装到 ~/.gsd/bin 目录
将路径写入 ~/.bashrc 或 ~/.zshrc

安装完成后，重新加载 shell 配置或新开一个终端窗口：

source ~/.bashrc   # 或 source ~/.zshrc

方式二：通过 npm 安装

如果你更习惯使用 npm，或者需要集成到现有的 Node.js 工作流中，可以选择全局安装：

npm install -g @gsd/cli

或者使用 pnpm/yarn：

# pnpm
pnpm add -g @gsd/cli

# yarn
yarn global add @gsd/cli

注意：npm 方式安装的包名称为 @gsd/cli，而安装脚本方式使用的二进制名为 gsd，两者功能完全一致。

验证安装

安装完成后，建议执行以下两个命令验证 GSD 是否正确安装：

1. 查看版本

gsd --version

预期输出示例：

gsd version 1.4.2
node: v20.11.0
platform: linux x64

2. 运行诊断命令

gsd doctor

预期输出示例：

✓ Node.js (v20.11.0)
✓ Git (2.43.0)
✓ Configuration file (~/.gsd/config.json)
✓ AI IDE integration (Cursor detected)
✓ Default workspace directory (~/gsd-workspace)

All checks passed! GSD is ready to use.

gsd doctor 会全面检查运行环境，如果发现任何问题（如缺失依赖、配置错误），会给出具体的修复建议。

第一条命令：`/gsd-new-project`

/gsd-new-project 是 GSD 的核心入口命令，它的作用是在当前目录初始化一个带有 .planning/ 工作区的全新项目。整个流程被设计为一次结构化的 Dream Extraction（目标提取）会话。

命令执行流程

flowchart TD
    A[在 AI IDE 中输入 /gsd-new-project] --> B{是否在当前 Git 仓库?}
    B -->|是| C[读取现有项目上下文]
    B -->|否| D[初始化新的 Git 仓库]
    C --> E[进入 Dream Extraction 阶段]
    D --> E
    E --> F[AI 引导输入项目愿景与目标]
    F --> G[生成 REQUIREMENTS.md]
    G --> H[生成 PROJECT.md]
    H --> I[生成 config.json]
    I --> J[生成 ROADMAP.md]
    J --> K[创建 .planning/ 目录]
    K --> L[输出下一步提示]

触发方式

在支持 slash command 的 AI IDE（如 Cursor）中，打开任意项目的根目录或空文件夹，在 AI 聊天框中输入：

/gsd-new-project

GSD 会立即接管会话，开始引导式项目初始化。

Dream Extraction 阶段

这是 /gsd-new-project 最核心的阶段。GSD 会通过多轮对话引导你明确以下信息：

项目愿景（Vision）：你最终想构建什么？解决什么问题？
目标用户（Audience）：谁会使用这个项目？
核心功能（Core Features）：MVP 阶段必须包含哪些功能？
技术偏好（Tech Stack）：语言、框架、部署方式等偏好
约束条件（Constraints）：时间、预算、合规等特殊要求

以下是一个实际的交互示例：

AI: 🎯 让我们开始创建你的项目规划。首先，请用一句话描述你的项目愿景。

You: 我想做一个个人财务管理工具，能自动同步银行流水并生成月度报告。

AI: 明白了！目标用户是你自己还是面向大众？

You: 初期自己用，后期可能开源给技术社区。

AI: 好的。核心功能上，除了同步流水和生成报告，还需要预算提醒吗？

You: 需要，还有多账户支持。

...（经过约 5-8 轮对话）...

设计哲学：Dream Extraction 不是简单的问答，而是 GSD 将人类的模糊意图转化为结构化机器可执行计划的关键桥梁。这个阶段的输出质量直接决定了后续 /gsd-plan-phase 和 /gsd-session 的效率。

项目结构初始化

对话完成后，GSD 会在项目根目录创建 .planning/ 目录，并生成 4 个核心文件：

my-project/
├── .planning/
│   ├── PROJECT.md          # 项目总览与元数据
│   ├── REQUIREMENTS.md     # 需求规格说明书
│   ├── config.json         # GSD 项目级配置
│   └── ROADMAP.md          # 里程碑与路线图
├── .gitignore              # 自动追加 .planning/ 忽略规则
└── ...（已有项目文件）

如果是空目录，GSD 还会自动执行 git init，确保版本控制就绪。

生成的文件解析

下面详细解析 .planning/ 目录中每个文件的用途和内容结构。

PROJECT.md

这是项目的总览文档，相当于项目的 README + 高层架构说明。它由 GSD 根据 Dream Extraction 的对话内容自动生成。

典型结构：

# Project: FinanceTracker

## Vision
构建一个开源的个人财务管理工具，支持多银行流水自动同步、
预算提醒和月度财务报告生成。

## Status
- Created: 2026-04-23
- Phase: planning
- Next: /gsd-plan-phase

## Tech Stack
- Backend: Node.js + Express
- Database: PostgreSQL
- Frontend: React + Tailwind
- Deployment: Docker + VPS

## Key Metrics
- MVP Deadline: 2026-05-30
- Target Users: 个人开发者 / 技术社区

作用：

作为项目的"一句话摘要"，任何新加入的 AI Agent 或开发者首先阅读此文件
记录项目当前所处阶段（planning / in-progress / review / done）
定义技术栈和关键约束，约束后续所有决策

REQUIREMENTS.md

这是需求规格说明书，将 Dream Extraction 中提取的模糊需求转化为结构化的功能列表。

典型结构：

# Requirements

## Functional Requirements

### FR-001: 银行流水同步
- Priority: P0
- Description: 支持通过 Open Banking API 同步多家银行账户流水
- Acceptance: 至少支持 3 家银行，同步延迟 < 5 分钟

### FR-002: 月度报告生成
- Priority: P0
- Description: 自动生成按类别汇总的月度支出报告
- Acceptance: 报告包含图表，可导出 PDF

### FR-003: 预算提醒
- Priority: P1
- Description: 当某类别支出超过预算阈值时发送通知
- Acceptance: 支持邮件和 Web 推送两种通知方式

## Non-Functional Requirements

### NFR-001: 数据安全
- 所有银行凭证必须加密存储（AES-256）
- 支持本地部署，数据不出境

### NFR-002: 性能
- 报告生成时间 < 3 秒（数据量 < 10,000 条）

作用：

每个需求都有唯一 ID（如 FR-001），便于在后续 Session 中追踪实现状态
优先级（P0/P1/P2）指导开发顺序
验收标准（Acceptance）为测试提供依据

config.json

这是 GSD 的项目级配置文件，控制 GSD 在该项目中的行为。

典型内容：

{
  "project": {
    "name": "FinanceTracker",
    "version": "0.1.0",
    "language": "zh-CN"
  },
  "gsd": {
    "workspace": ".planning",
    "autoCommit": true,
    "sessionFormat": "structured",
    "maxSessionDepth": 5
  },
  "ai": {
    "model": "claude-sonnet-4-20250514",
    "contextWindow": 200000,
    "responseStyle": "concise"
  },
  "integrations": {
    "git": {
      "branchPrefix": "gsd/",
      "commitMessagePrefix": "[GSD]"
    },
    "ci": {
      "provider": "github-actions",
      "runTestsOnPR": true
    }
  }
}

关键配置项说明：

配置项	类型	默认值	说明
`gsd.autoCommit`	boolean	`true`	每个 Session 结束后是否自动提交 Git
`gsd.sessionFormat`	string	`"structured"`	Session 日志格式：`structured` 或 `narrative`
`gsd.maxSessionDepth`	number	`5`	单个 Phase 内最大 Session 嵌套深度
`ai.model`	string	`"claude-sonnet"`	默认使用的 AI 模型
`ai.responseStyle`	string	`"concise"`	AI 回复风格：`concise` / `detailed` / `tutorial`
`integrations.git.branchPrefix`	string	`"gsd/"`	GSD 自动创建的分支前缀

ROADMAP.md

这是路线图文档，基于需求优先级和依赖关系自动生成里程碑计划。

典型结构：

# Roadmap

## Phase 1: Foundation (Week 1-2)
- [ ] Setup project scaffolding
- [ ] Design database schema
- [ ] Implement bank API authentication
- **Deliverable**: 可本地运行的基础框架

## Phase 2: Core Features (Week 3-5)
- [ ] Bank transaction sync (FR-001)
- [ ] Monthly report generation (FR-002)
- [ ] Basic budget configuration
- **Deliverable**: MVP 可用版本

## Phase 3: Polish & Release (Week 6-8)
- [ ] Budget alerts (FR-003)
- [ ] PDF export
- [ ] Docker deployment setup
- **Deliverable**: v1.0 开源发布

作用：

将 REQUIREMENTS 映射到时间线上的可交付阶段
每个 Phase 对应后续 /gsd-plan-phase 的一次调用
可随时手动调整，GSD 会在后续会话中读取最新版本

常用配置项介绍

除了 config.json 中的标准配置，GSD 还支持通过环境变量和全局配置文件进行更灵活的定制。

全局配置文件

位于 ~/.gsd/config.json，作用于所有项目：

{
  "defaults": {
    "ai": {
      "model": "claude-opus-4-20250514",
      "temperature": 0.2
    },
    "git": {
      "autoPush": false,
      "defaultRemote": "origin"
    }
  },
  "templates": {
    "project": "~/gsd-templates/standard",
    "session": "~/gsd-templates/session-structured"
  }
}

环境变量

变量名	说明	示例
`GSD_AI_MODEL`	覆盖默认 AI 模型	`export GSD_AI_MODEL=gpt-4o`
`GSD_WORKSPACE`	自定义工作区根目录	`export GSD_WORKSPACE=/data/gsd`
`GSD_DEBUG`	开启调试模式	`export GSD_DEBUG=1`
`GSD_NO_AUTO_COMMIT`	禁用自动提交	`export GSD_NO_AUTO_COMMIT=1`

项目级覆盖规则

配置优先级从高到低：

环境变量 > 项目 config.json > 全局 ~/.gsd/config.json > 内置默认值

这意味着你可以在全局设置一个保守的默认值，然后在具体项目中按需覆盖。

验证第一条命令成果

执行完 /gsd-new-project 后，建议进行以下验证：

# 1. 检查 .planning/ 目录是否存在
ls -la .planning/

# 预期输出：
# PROJECT.md  REQUIREMENTS.md  config.json  ROADMAP.md

# 2. 检查 Git 状态
git status

# 预期输出（如果 autoCommit 为 false）：
# Untracked files:
#   .planning/

# 3. 快速浏览项目总览
cat .planning/PROJECT.md | head -20

# 4. 验证 config.json 语法
node -e "JSON.parse(require('fs').readFileSync('.planning/config.json'))" && echo "Valid JSON"

如果一切正常，你的项目现在已经具备了 GSD 工作流的基础设施。

下一步：`/gsd-plan-phase`

到这里，你已经完成了 GSD 的安装和第一条命令的执行。.planning/ 目录中的 4 个文件构成了项目的"战略层"，但它们还只是计划，尚未进入真正的执行阶段。

接下来，我们将使用 /gsd-plan-phase 命令，将 ROADMAP 中的第一个 Phase 细化为可执行的 Session 序列。这个命令会：

读取当前 ROADMAP 和 REQUIREMENTS
分析 Phase 间的依赖关系
生成具体的 Session 计划（存入 .planning/sessions/）
输出可立即执行的 /gsd-session 命令

下一篇预告： 第 06 篇《命令系统架构》

我们将深入剖析 GSD 的命令解析器、路由机制和插件系统，揭示 /gsd-new-project、/gsd-plan-phase、/gsd-session 等命令背后的统一架构设计。敬请期待。

环境准备和前提条件

安装 GSD

方式一：通过安装脚本（推荐）

方式二：通过 npm 安装

验证安装

1. 查看版本

2. 运行诊断命令

第一条命令：/gsd-new-project

命令执行流程

触发方式

Dream Extraction 阶段

项目结构初始化

生成的文件解析

PROJECT.md

REQUIREMENTS.md

config.json

ROADMAP.md

常用配置项介绍

全局配置文件

环境变量

项目级覆盖规则

验证第一条命令成果

下一步：/gsd-plan-phase

第一条命令：`/gsd-new-project`

下一步：`/gsd-plan-phase`