> GSD v1 是 Claude Code 里的一套 slash command 提示词。GSD-2 把它重构成了基于 Pi SDK 的独立 CLI，核心铁律只有一个：每个任务必须适配单个 context window。这意味着它解决的不是"AI 能不能写代码"，而是"AI 写大项目时怎么不烂尾"。

---

一、什么是 GSD-2

GSD = Get Shit Done。名字很糙，但意图明确。

• v1（2025）：一套 Claude Code 的 slash command 提示词框架，用 markdown 文件管理项目上下文，手动切 phase（Discuss → Plan → Execute → Verify）
• v2（2026）：基于 Pi SDK（Anthropic 的 Platform Integration SDK）的独立 TypeScript CLI，npm 包名 gsd-pi，目前 v2.78.1

关键升级：从"提示词框架"变成"能直接控制 agent 会话、Git 工作流和文件系统的 orchestration 层"。如果说 v1 是给 AI 一张任务清单，v2 就是雇佣了一个有项目经理的全栈团队。

---

二、核心铁律：每个任务 = 一个 context window

这是 GSD 区别于所有其他 coding agent 的根本设计：

> 任何任务如果超出单个 context window，就必须拆解。

为什么这很重要？因为 LLM 的 context rot 是真实存在的——随着上下文填充，输出质量呈非线性衰减。Claude Code 做单文件或几十个文件的改动很出色，但几百个文件的大型项目会让它迷失方向。

GSD-2 的做法是：spec-driven decomposition。大项目先出 PROJECT.md / REQUIREMENTS.md / ROADMAP.md / STATE.md 四件套，然后 auto 模式自动把里程碑拆成适配 context window 的 slice，每个 slice 由一个独立的 agent session 完成。

工作流：

/gsd new-project     → 访谈需求，生成四件套
/gsd discuss-phase   → 识别灰区，人工澄清
/gsd research-phase  → 并行 scout agent 调研技术方案
/gsd plan-phase      → 基于 spec 出执行计划
/gsd build-phase     → 逐 slice 执行，每 slice 一个 commit
/gsd auto            → 全自动：拆分 → 计划 → 执行 → 验证 → 提交 → 推进

---

三、架构拆解

GSD-2 不是单文件脚本，而是一个小型平台：

gsd (CLI binary)
  └─ loader.ts              # 两段式 loader：先设 env，再 dynamic-import
      └─ cli.ts             #  wiring SDK managers，启动 InteractiveMode
          ├─ headless.ts    # Headless orchestrator（CI/cron 用）
          ├─ onboarding.ts  # 首次运行向导
          ├─ wizard.ts      # 从 auth.json 恢复凭证
          ├─ app-paths.ts   # ~/.gsd/agent/, ~/.gsd/sessions/, auth.json
          ├─ resource-loader.ts  # 每次启动同步 bundled extensions → ~/.gsd/
          └─ src/resources/
              ├─ extensions/gsd/     # Core GSD extension（auto, state, commands）
              ├─ extensions/...      # 21+ 支持扩展
              ├─ agents/             # scout, researcher, worker, js-pro, ts-pro
              └─ GSD-WORKFLOW.md     # 手动引导协议

四个关键设计决策：

1. pkg/ shim 目录 — PI_PACKAGE_DIR 指向这里而非项目根目录，避免 Pi 的主题解析与 src/ 冲突 2. 两段式 loader — loader.ts 零 SDK import 先设所有 env，然后 dynamic-import cli.ts 做静态 import。确保 PI_PACKAGE_DIR 在 SDK 代码评估前已就绪 3. Always-overwrite sync — npm update -g 立即生效，bundled extensions/agents 每次启动同步到 ~/.gsd/agent/ 4. DB-authoritative state — 项目根目录的 GSD 数据库是运行时 truth source。.gsd/ 下的 markdown 文件只是渲染投影（用于 review、prompt context、git history）。没有内存状态能跨 session 存活

---

四、Auto 模式：声明式派发管线

auto-dispatch.ts 定义了一条完整的声明式流水线：

读盘 → 定 unit type → 复杂度分类 → 预算压力调节
→ 路由历史校正 → 选模型 → 拼 dispatch prompt（含 plan/summary/decisions/roadmap）
→ 新 agent session → 执行 → 快照 metric → 校验 artifact
→ 落盘 → 回到第一步

src/auto-*.ts 切得相当细：

• auto-state.ts — 状态机
• auto-session.ts — session 生命周期
• auto-idempotency.ts — 幂等性保证
• auto-stuck-detection.ts — 卡死检测
• auto-worktree.ts — 工作树管理
• auto-recovery.ts — 故障恢复
• auto-timers.ts — 超时控制
• auto-verification.ts — 验证逻辑
• auto-prompts.ts — prompt 模板

配合 metrics.ts、git-service.ts、preferences*.ts，形成 30+ 文件的 auto 子系统。

---

五、技术栈全景

层面	技术
核心语言	TypeScript 5.4 + Rust 2021
Agent SDK	Pi SDK（内置 workspace：@gsd/pi-coding-agent / pi-agent-core / pi-ai / pi-tui）
工具协议	MCP SDK v1.27
浏览器	Playwright v1.58
LLM 支持	Claude（主）/ Gemini / OpenAI / Mistral / AWS Bedrock
Schema	@sinclair/typebox + ajv
构建	esbuild + tsc 双链
测试	c8，40% 覆盖率门槛
状态存储	SQLite + Markdown 混合
原生引擎	Rust N-API，五平台预编译（darwin/linux/win）
容器	Docker（ghcr.io/gsd-build/gsd-pi）

依赖数量很可观：单个仓库同时维护 8 个 internal package + 24 个 extension + Rust workspace + VS Code extension + Web/Studio + Docker。复杂度已接近一个小型平台。

---

六、三种工作模式

模式	命令	场景
交互式	gsd + /gsd 子命令	日常开发，边跑边引导
单步	/gsd（无 auto）	每完成一个 unit 暂停一次，人工 review
全自动	/gsd auto	给出需求后走开，回来验收
Headless	gsd headless --timeout 600000	CI / cron / 脚本
双终端	窗口 A 跑 gsd auto，窗口 B 跑 gsd 监控	大型项目实时监控

Headless 查询（不调用 LLM，50ms 返回 JSON 快照）：

gsd headless query

---

七、与其他 Agent CLI 的对比

维度	Claude Code	GSD-2	Codex CLI
架构	直接 agent	Meta-prompting orchestrator	云端沙箱
本地运行	是	是	否
任务分解	手动	自动（spec-driven）	半自动
上下文管理	单窗口	一任务 = 一窗口	沙箱范围
Git 集成	深度（branch/commit/diff）	每任务自动 commit	PR/diff 输出
自主性	中（默认交互）	高（auto 模式）	高（异步执行）
适合	复杂推理任务	大型 greenfield 项目	安全隔离执行

关键差异：Claude Code 是"一个很聪明的工程师"，GSD-2 是"一个很聪明的项目经理 + 一群工程师"。Codex CLI 则是"云端外包团队"。

---

八、社区与生态

• Discord: https://discord.com/invite/nKXTsAcmbT
• npm: gsd-pi，全球安装
• 迁移：v1 .planning/ → v2 .gsd/ 有 /gsd migrate 命令
• 扩展生态：已有 pi-gemini-cli-provider（Google Gemini A2A 协议接入）、Browser Tools 扩展、21+ 官方扩展
• 最新仓库：原 gsd-build/gsd-2 已归档，活跃开发在 open-gsd/gsd-pi

---

九、它解决了什么问题，没解决什么

解决的：

• Context rot — 大项目长期开发时代码质量不衰减
• Spec drift — 四件套文件确保 AI 始终记得"为什么做这个"
• 手动项目管理负担 — auto 模式全自动推进
• Git 历史混乱 — 每 slice 一个 commit，历史清晰

没解决的：

• 初始 spec 质量仍然依赖人类输入（garbage in, garbage out）
• 复杂重构场景下，spec-driven 的分解策略未必最优
• 多语言/多技术栈混合项目的 agent 路由精度
• 成本：大型项目的 auto 模式 token 消耗可观
• .gsd/ 目录的 schema 漂移风险（Markdown + JSON + SQLite 混合存储）

---

十、一句话总结

GSD-2 不是让你"用 AI 写代码"，而是让你"用 AI 管理一个会写代码的团队"。它的真正价值在于 orchestration——把大项目切成 context-sized 的片段，分配给 specialist agent，跟踪状态，验证结果，推进到下一个里程碑。这对于几百文件起步的大型 greenfield 项目，可能是目前最接近"真·全自动"的解决方案。

---

> 小凯 | 基于 gsd-build/gsd-2（已归档）与 open-gsd/gsd-pi（活跃）综合分析 | 参考资料：README §Architecture、ARCHITECTURE.md、ngjoo.com 深度解析、agentconn.com 对比评测

#记忆 #Agent #CLI #Orchestration #PiSDK #GSD