Quick Ref — 最短命令链

# 一句话安装并启动
npm install -g gsd-pi && gsd

# 登录
gsd → /login

# 自主任意执行
gsd → /gsd auto

# 单步执行（学习阶段）
gsd → /gsd

# 查看状态
gsd → /gsd status

# 暂停/恢复
Escape → /gsd auto

# Headless CI
gsd headless --timeout 600000 auto

# 即时状态查询
gsd headless query | jq '.state.phase'

🧭 一眼入口

这是什么

技术栈

• 运行时： Node.js ≥ 22.0.0（24 LTS 推荐）
• Agent 框架： Pi SDK
• 语言： TypeScript
• 状态存储： SQLite + Markdown 文件
• 扩展系统： 24 个内置扩展 + MCP 服务器

最短路径

安装 → 登录 Provider → /gsd auto → 等结果

🚀 Cookbook — 核心工作流

快速启动

npm install -g gsd-pi@latest

gsd
/login

/model

工作层级

Milestone  →  可发布的版本（4-10 个 Slice）
  Slice    →  可演示的垂直能力（1-7 个 Task）
    Task   →  一次上下文窗口大小的单元

Auto Mode — 主工作流

gsd
/gsd auto

Plan → Execute → Complete → Reassess Roadmap → Next Slice
                                            ↓ (全部完成)
                              Validate Milestone → Complete Milestone

Step Mode — 逐步执行

/gsd       # 等同于 /gsd next，显式单步模式
/gsd next

双终端工作流

gsd
/gsd auto

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

最小配置

---
version: 1
models:
  research: claude-sonnet-4-6
  planning: claude-opus-4-6
  execution: claude-sonnet-4-6
  completion: claude-sonnet-4-6
skill_discovery: suggest
auto_supervisor:
  soft_timeout_minutes: 20
  idle_timeout_minutes: 10
  hard_timeout_minutes: 30
budget_ceiling: 50.00
token_profile: balanced
---

高频 Recipes

token_profile: budget        # 节省 40-60% token
dynamic_routing:
  enabled: true              # 自动降级简单任务到便宜模型
budget_ceiling: 20.00

parallel:
  enabled: true
  max_workers: 2
  budget_ceiling: 100.00

/gsd parallel start    # 分析 eligibility 并启动
/gsd parallel status   # 查看所有 worker 状态
/gsd parallel stop     # 停止全部

mode: team                           # 唯一里程碑 ID、关闭 auto_push
unique_milestone_ids: true
git:
  auto_push: false
  push_branches: true
  pre_merge_check: true

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

git:
  isolation: worktree    # 默认：每个 Milestone 独立工作树
  # isolation: branch    # 分支模式
  # isolation: none       # 无隔离，直接在当前分支

verification_commands:
  - npm run lint
  - npm run test
verification_auto_fix: true
verification_max_retries: 2

📋 Artifact 速查

🎛️ Cheatsheet — 命令速查

会话命令

配置与诊断

Milestone 管理

并行编排

工作流模板 (v2.42+)

扩展

cmux 集成

GitHub Sync

Git 命令

会话管理

键盘快捷键

CLI 参数

Headless 模式

# 运行 auto mode
gsd headless

# 单个单元
gsd headless next

# 即时 JSON 快照（无 LLM，~50ms）
gsd headless query

# 带超时
gsd headless --timeout 600000 auto

# 创建里程碑并自动执行
gsd headless new-milestone --context brief.md --auto

⚙️ Cheatsheet — 配置速查

Token Profile

token_profile: budget      # 节省 40-60%
# token_profile: balanced  # 默认，节省 10-20%
# token_profile: quality    # 无压缩

模型选择

models:
  research: claude-sonnet-4-6
  planning:
    model: claude-opus-4-6
    fallbacks:
      - openrouter/z-ai/glm-5
      - openrouter/minimax/minimax-m2.5
  execution: claude-sonnet-4-6
  completion: claude-sonnet-4-6

动态路由

dynamic_routing:
  enabled: true
  tier_models:
    light: claude-haiku-4-5
    standard: claude-sonnet-4-6
    heavy: claude-opus-4-6
  escalate_on_failure: true
  budget_pressure: true
  cross_provider: true
  capability_routing: true

Git 隔离

git:
  isolation: worktree    # 默认
  # isolation: branch
  # isolation: none
  auto_push: false
  push_branches: false
  remote: origin
  snapshots: false
  pre_merge_check: false
  main_branch: main
  commit_docs: true
  auto_pr: false
  pr_target_branch: develop

超时配置

auto_supervisor:
  soft_timeout_minutes: 20
  idle_timeout_minutes: 10
  hard_timeout_minutes: 30

验证配置

verification_commands:
  - npm run lint
  - npm run test
verification_auto_fix: true
verification_max_retries: 2

技能配置

always_use_skills:
  - debug-like-expert
prefer_skills:
  - frontend-design
avoid_skills:
  - security-docker
skill_rules:
  - when: task involves Clerk authentication
    use: [clerk]
skill_staleness_days: 60
skill_discovery: suggest  # auto / suggest / off

工作流模式

mode: solo    # 个人项目
# mode: team  # 团队协作

并行配置

parallel:
  enabled: true
  max_workers: 2          # 1-4
  budget_ceiling: 50.00
  merge_strategy: per-milestone  # per-slice / per-milestone
  auto_merge: confirm     # auto / confirm / manual

预算

budget_ceiling: 50.00
budget_enforcement: pause    # warn / pause / halt

🔧 Cheatsheet — 内置扩展

📊 Cheatsheet — Dashboard 与报告

Dashboard (Ctrl+Alt+G)

• 当前 Milestone、Slice、Task 进度
• Auto Mode 运行时间和阶段
• 按阶段/Slice/模型的成本和 token 分解
• 成本预测
• 待处理 Capture 数量
• 并行 Worker 状态

报告生成

/gsd export --html           # 当前里程碑
/gsd export --html --all     # 所有里程碑

• 项目摘要
• 进度树
• Slice 依赖图（SVG DAG）
• 成本/token 指标柱状图
• 执行时间线
• Changelog
• 知识库章节

🐛 Cheatsheet — 排障速记

/gsd doctor 检查项

• 文件结构和命名规范
• Roadmap ↔ Slice ↔ Task 引用完整性
• 完成状态一致性
• Git 工作树健康（仅 worktree/branch 模式）
• 过期锁文件和孤立运行时记录

🔌 Cheatsheet — MCP 服务器

配置

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
    }
  }
}

OAuth MCP 服务器 (v2.64+)

{
  "mcpServers": {
    "my-server": {
      "transport": "http",
      "url": "https://your-server.com/mcp",
      "auth": {
        "type": "oauth",
        "clientId": "...",
        "clientSecret": "..."
      }
    }
  }
}

命令

/gsd mcp              # MCP 服务器状态
/gsd prefs            # MCP 服务器配置

🔐 Cheatsheet — API Key 管理

支持的 Provider

Key 管理命令

Credential 工具支持

📦 Cheatsheet — Skills

安装 Skills

npx skills add dpearson2699/swift-ios-skills
npx skills add dpearson2699/swift-ios-skills --skill swift-concurrency --skill swiftui-patterns -y
npx skills update

Skill 存放位置

技能健康

/gsd skill-health              # 概览
/gsd skill-health <name>       # 详细视图
/gsd skill-health --stale 30  # 30+ 天未用
/gsd skill-health --declining  # 成功率下降

🏗️ Cheatsheet — 架构速记

目录结构

gsd (CLI binary)
  └─ loader.ts          设置 PI_PACKAGE_DIR, GSD env vars
      └─ cli.ts         装配 SDK managers, 加载扩展
          ├─ headless.ts     Headless 编排
          ├─ onboarding.ts   首次运行向导
          ├─ wizard.ts       Env 注入
          ├─ app-paths.ts    ~/.gsd/ 路径
          └─ src/resources/
              ├─ extensions/gsd/    核心 GSD 扩展
              ├─ extensions/...     23 个支撑扩展
              ├─ agents/           scout, researcher, worker
              └─ AGENTS.md         Agent 路由指令

关键设计

• src/：避免 Pi 主题解析与项目 冲突
• loader.ts cli.ts：设置环境变量， 动态导入
• ./gsd/：是事实来源，Auto Mode 读写磁盘
• Native Git：v2.16+ 使用 libgit2 减少 ~70 个进程/调度

🌐 Cheatsheet — Web 与 VS Code

Web 界面

gsd --web [path]    # 启动浏览器界面

• 浏览器仪表板
• 实时进度
• 多项目支持
• 端口 3000

VS Code 扩展

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

不要混淆：GSD v1 vs v2