仓库结构全景图 - 和平哥的学习笔记

这是「GSD 全景代码解析」专题的第 2 篇。在本系列中，我们将逐层拆解 Get Shit Done (GSD) 这一 56K+ stars 的 Meta-Prompting 框架，从仓库目录到每一行 Prompt 设计哲学，带你看懂一个工业级 AI 编程框架是如何用纯文本构建起来的。

上一篇我们回答了「GSD 是什么」，本篇我们把镜头拉近，进入它的物理世界——仓库目录。GSD 的仓库结构并非随意堆砌，而是一个精心设计的五层架构，每一层都有明确的职责边界和通信契约。

一、仓库整体规模

在打开任何文件之前，先看一组数字，建立宏观体感：

维度	数量	说明
仓库总大小	~12 MB	纯文本 + 少量 JS/CJS 工具
Commands	85 个	`commands/gsd/*.md`，用户入口命令
Workflows	83 个	`get-shit-done/workflows/*.md`，编排逻辑
Agents	33 个	`agents/*.md`，专业 Agent 定义
References	51 个	`get-shit-done/references/*.md`，共享知识文档
CLI Modules	30 个	`get-shit-done/bin/lib/*.cjs`，Node.js 工具模块
Hooks	11 个	`hooks/*`，运行时钩子
Tests	300+	`tests/*.test.cjs`，计数同步与功能测试

💡 这些数字来自官方 docs/INVENTORY.md（v1.36.0），并受 tests/inventory-counts.test.cjs 等漂移控制测试锁定。新增文件必须同步更新 INVENTORY，否则 CI 会失败。

二、五层架构总览

GSD 的核心架构可以用一张图概括——从用户输入到文件系统，数据流自上而下穿透五层：

flowchart TB
    subgraph L1["⬆️ Command Layer (commands/gsd/*.md)"]
        C1["/gsd-new-project"]
        C2["/gsd-plan-phase"]
        C3["/gsd-execute-phase"]
        C4["... 85 个命令"]
    end

    subgraph L2["Workflow Layer (get-shit-done/workflows/*.md)"]
        W1["new-project.md"]
        W2["plan-phase.md"]
        W3["execute-phase.md"]
        W4["... 83 个工作流"]
    end

    subgraph L3["Agent Layer (agents/*.md)"]
        A1["gsd-planner"]
        A2["gsd-executor"]
        A3["gsd-verifier"]
        A4["... 33 个 Agent"]
    end

    subgraph L4["CLI Tools Layer (sdk/src/ + bin/lib/)"]
        T1["gsd-sdk query"]
        T2["gsd-tools.cjs"]
        T3["bin/lib/*.cjs"]
    end

    subgraph L5["⬇️ File System (.planning/)"]
        F1["PROJECT.md"]
        F2["ROADMAP.md"]
        F3["STATE.md"]
        F4["phases/"]
    end

    L1 --> L2
    L2 --> L3
    L3 --> L4
    L4 --> L5
    L5 -.->|状态回读| L2

设计哲学：每一层都是薄层（Thin Layer）。Workflow 不干活，只加载上下文、Spawn Agent、收集结果、更新状态。真正的重逻辑被下推到 Agent 定义和 CLI 工具中。

三、逐层拆解

Layer 1：Command Layer — 用户入口

路径：commands/gsd/*.md

这是用户每天打交道的层。85 个 Markdown 文件，每个文件就是一条 /gsd-xxx 命令。例如 /gsd-new-project 对应 commands/gsd/new-project.md。

每个命令文件的格式高度统一：

---
name: new-project
description: Initialize a new project with deep context gathering and PROJECT.md.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
---

## Context

Load context via `gsd-sdk query init.new-project`...

## Steps

1. Ask user for project idea
2. Spawn gsd-project-researcher (4 parallel)
3. ...

命令分组概览：

分组	数量	典型命令
Core Workflow	24	`/gsd-new-project`, `/gsd-plan-phase`, `/gsd-execute-phase`
Phase & Milestone	20	`/gsd-add-phase`, `/gsd-validate-phase`, `/gsd-complete-milestone`
Session & Navigation	14	`/gsd-progress`, `/gsd-pause-work`, `/gsd-resume-work`
Codebase Intelligence	4	`/gsd-map-codebase`, `/gsd-scan`, `/gsd-intel`
Review, Debug & Recovery	6	`/gsd-debug`, `/gsd-forensics`, `/gsd-health`
Docs, Profile & Utilities	17	`/gsd-docs-update`, `/gsd-profile-user`, `/gsd-settings`

这些命令被安装为不同 AI 编程助手的自定义指令：Claude Code 用 Slash Command (/gsd-xxx)，Codex 用 Skill ($gsd-xxx)，Copilot 也是 Slash Command。

Layer 2：Workflow Layer — 编排中枢

路径：get-shit-done/workflows/*.md

83 个工作流文件是 GSD 的编排中枢。它们被命令引用，但大部分不直接暴露给用户。核心职责：

加载上下文：通过 gsd-sdk query init.<workflow> 获取项目信息、配置、状态
解析模型：通过 gsd-sdk query resolve-model <agent> 决定用哪个模型
Spawn Agent：调用 AI 的 Task/SubAgent 能力，传入 Agent 定义 + 上下文 Payload
收集结果：等待 Agent 返回，路由到下一步
更新状态：写回 .planning/STATE.md 和 config.json

三大巨无霸工作流（体积上的三巨头）：

工作流	大小	行数限制	职责
`execute-phase.md`	~69 KB	1700 (XL tier)	波浪并行执行计划
`plan-phase.md`	~66 KB	1700 (XL tier)	研究 → 规划 → 验证循环
`new-project.md`	~44 KB	1700 (XL tier)	新项目初始化全流程

Workflow 尺寸预算：tests/workflow-size-budget.test.cjs 强制执行三级预算，防止上下文膨胀：

Tier	每文件行数上限	适用对象
XL	1700	顶级编排器（execute-phase、plan-phase、new-project）
LARGE	1500	多步骤规划器和大型特性工作流
DEFAULT	1000	聚焦型单用途工作流（目标层级）

当一个工作流超限时，GSD 采用渐进披露策略：把 per-mode 逻辑拆到 workflows/<workflow>/modes/<mode>.md，模板拆到 templates/，共享知识下沉到 references/。最典型的例子是 discuss-phase.md（<500 行），它把 9 种模式（power、all、auto、chain、text、batch、analyze、default、advisor）全部外置到子目录。

Layer 3：Agent Layer — 专业智能体

路径：agents/*.md

33 个 Agent 定义文件，每个文件描述一个专业角色。Agent 文件同样使用 YAML frontmatter：

---
name: gsd-executor
description: Executes GSD plans with atomic commits and deviation handling.
tools: Read, Write, Edit, Bash, Grep, Glob
---

Agent 分类（按 spawn 模式）：

类别	Agent	并行策略
Researchers	`gsd-project-researcher`, `gsd-phase-researcher`, `gsd-ui-researcher`, `gsd-advisor-researcher`	4 并行
Synthesizers	`gsd-research-synthesizer`	串行
Planners	`gsd-planner`, `gsd-roadmapper`	串行
Checkers	`gsd-plan-checker`, `gsd-integration-checker`, `gsd-ui-checker`, `gsd-nyquist-auditor`	验证循环（最多 3 轮）
Executors	`gsd-executor`	波浪内并行
Verifiers	`gsd-verifier`	串行
Mappers	`gsd-codebase-mapper`	4 并行
Debuggers	`gsd-debugger`	交互式串行
Auditors	`gsd-ui-auditor`, `gsd-security-auditor`	串行
Doc Writers	`gsd-doc-writer`, `gsd-doc-verifier`	串行（先写后审）
Advanced	`gsd-pattern-mapper`, `gsd-code-reviewer`, `gsd-code-fixer`, `gsd-ai-researcher` 等 12 个	按需

关键设计：每个 Agent 获得全新的上下文窗口（最高 200K，1M 级模型下可达 500K+）。这是 GSD 最核心的设计原则之一——Fresh Context Per Agent，彻底消除上下文腐烂（Context Rot）。

Layer 4：CLI Tools Layer — 类型化工具箱

路径：get-shit-done/bin/lib/*.cjs、sdk/src/

CLI 工具层是连接编排逻辑与文件系统的桥梁。它分为两部分：

4.1 传统工具：`gsd-tools.cjs` + `bin/lib/*.cjs`

get-shit-done/bin/gsd-tools.cjs 是主入口，30 个 CJS 模块按领域拆分：

模块	大小	职责
`core.cjs`	-	错误处理、输出格式化、共享工具
`state.cjs`	-	STATE.md 解析、更新、进度追踪
`phase.cjs`	-	阶段目录操作、小数编号、计划索引
`roadmap.cjs`	-	ROADMAP.md 解析、阶段提取
`config.cjs`	-	config.json 读写、配置校验
`verify.cjs`	-	计划结构、阶段完整性验证
`template.cjs`	-	模板选择与变量替换
`security.cjs`	-	路径遍历防护、Prompt 注入检测
`model-profiles.cjs`	-	模型层级解析表
`workstream.cjs`	-	工作流 CRUD、活跃指针
`drift.cjs`	-	代码库结构漂移检测（#2003）
`gap-checker.cjs`	-	需求/决策覆盖缺口分析（#2493）
`graphify.cjs`	-	知识图谱构建与查询
`intel.cjs`	-	代码库智能存储
`learnings.cjs`	-	跨阶段经验提取

4.2 新世代 SDK：`sdk/src/`

GSD 正在向 TypeScript SDK 迁移，核心文件规模：

文件	大小	职责
`phase-runner.ts`	~39 KB	阶段执行引擎，波浪调度核心
`gsd-tools.ts`	~20 KB	工具函数封装，兼容层

gsd-sdk query 是新的统一 CLI 接口，逐步替代 gsd-tools.cjs。两者目前并存，确保向后兼容。

Layer 5：File System — 基于文件的持久化状态

路径：.planning/

GSD 没有数据库、没有服务器、没有外部依赖。所有状态都是人类可读的 Markdown + JSON，存于项目根目录的 .planning/ 中。

graph LR
    subgraph planning[".planning/ 目录结构"]
        P1["PROJECT.md
项目愿景与决策"]
        P2["REQUIREMENTS.md
需求范围"]
        P3["ROADMAP.md
阶段路线图"]
        P4["STATE.md
实时状态"]
        P5["config.json
工作流配置"]
        P6["MILESTONES.md
里程碑归档"]

        subgraph phases["phases/"]
            PH1["01-phase-name/"]
            PH2["02-phase-name/"]
        end

        subgraph phase_files["单个阶段目录"]
            F_CTX["01-CONTEXT.md"]
            F_RES["01-RESEARCH.md"]
            F_PLAN["01-01-PLAN.md"]
            F_SUM["01-01-SUMMARY.md"]
            F_VER["01-VERIFICATION.md"]
            F_UI["01-UI-SPEC.md"]
            F_UAT["01-UAT.md"]
        end

        subgraph others["其他"]
            O1["research/"]
            O2["codebase/"]
            O3["debug/"]
            O4["todos/"]
            O5["seeds/"]
            O6["threads/"]
        end
    end

    phases --> phase_files
    planning --> phases
    planning --> others

关键设计原则：

Absent = Enabled：配置中缺失的键默认启用为 true，用户只需显式关闭不需要的功能
状态可提交：.planning/ 可以 git commit，团队成员可见项目全貌
上下文可恢复：/clear 或换会话后，AI 只需读取 .planning/ 即可恢复全部上下文

四、关键文件规模统计

以下是仓库中体积最大的文件，它们往往也是逻辑最复杂的核心文件：

排名	文件	大小	说明
1	`bin/install.js`	~275 KB (~3,000 行)	跨运行时安装器，支持 12+ AI 助手
2	`workflows/execute-phase.md`	~69 KB	波浪并行执行引擎
3	`workflows/plan-phase.md`	~66 KB	研究-规划-验证闭环
4	`workflows/new-project.md`	~44 KB	新项目初始化编排
5	`sdk/src/phase-runner.ts`	~39 KB	TypeScript 阶段运行器
6	`sdk/src/gsd-tools.ts`	~20 KB	SDK 工具封装

安装器 bin/install.js 是单体巨无霸，负责：

运行时检测：Claude Code、OpenCode、Kilo、Gemini CLI、Codex、Copilot、Antigravity、Trae、Cline、Augment Code 等
路径适配：每个运行时有不同的配置目录（~/.claude/、~/.codex/、~/.github/ 等）
格式转换：同一套命令文件，安装时按需转换（Codex 转 TOML + Skill，Copilot 转工具名映射）
本地补丁备份：v1.17+ 自动备份用户本地修改到 gsd-local-patches/

五、支持设施

References：51 个共享知识文档

路径：get-shit-done/references/*.md

Workflow 和 Agent 通过 @-reference 引用这些文档，实现知识的单点维护、多点复用。

类别	数量	典型文档
Core	16	`checkpoints.md`, `gates.md`, `model-profiles.md`, `planning-config.md`, `git-integration.md`
Workflow	21	`agent-contracts.md`, `context-budget.md`, `revision-loop.md`, `universal-anti-patterns.md`
Thinking-Model	5	`thinking-models-planning.md`, `thinking-models-execution.md` 等
Sketch	4	`sketch-interactivity.md`, `sketch-theme-system.md` 等
Planner	6	`planner-gap-closure.md`, `planner-revision.md` 等（分解后的规划器模块）

Hooks：11 个运行时钩子

路径：hooks/

钩子	触发事件	职责
`gsd-statusline.js`	`statusLine`	状态栏：模型、任务、目录、上下文用量
`gsd-context-monitor.js`	`PostToolUse`	上下文警告（剩余 ≤35% 警告，≤25% 严重）
`gsd-prompt-guard.js`	`PreToolUse`	扫描 `.planning/` 写入的 Prompt 注入模式
`gsd-read-injection-scanner.js`	`PostToolUse`	扫描 Read 工具输出中的注入指令
`gsd-check-update.js`	`SessionStart`	后台版本更新检查
`gsd-validate-commit.sh`	`PostToolUse`	提交信息规范校验
`gsd-phase-boundary.sh`	`PostToolUse`	阶段边界检测

所有钩子都包裹在 try/catch 中，出错时静默失败，绝不阻塞主流程。

Templates：规划产物模板

路径：get-shit-done/templates/

为所有 .planning/ 产物提供预结构化模板：project.md、requirements.md、roadmap.md、state.md、phase-prompt.md、summary.md（含 minimal/standard/complex 三档粒度）、DEBUG.md、UI-SPEC.md、UAT.md、VALIDATION.md 等。

六、阅读路线图

面对如此庞大的代码库，建议按以下顺序深入：

flowchart LR
    S1["1. 看懂 INVENTORY.md"]
    S2["2. 读 ARCHITECTURE.md"]
    S3["3. 挑一个命令走通全流程"]
    S4["4. 深入对应 Workflow"]
    S5["5. 分析 Agent 定义"]
    S6["6. 追踪 CLI 工具调用链"]
    S7["7. 研究 .planning/ 产物格式"]

    S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7

步骤	目标	推荐起点
1	建立全局目录索引	`docs/INVENTORY.md`
2	理解架构设计理念	`docs/ARCHITECTURE.md`
3	体验端到端流程	`/gsd-new-project` → 读 `commands/gsd/new-project.md`
4	理解编排逻辑	`get-shit-done/workflows/new-project.md`
5	理解 Agent 角色	`agents/gsd-planner.md`, `agents/gsd-executor.md`
6	理解工具层	`get-shit-done/bin/lib/state.cjs`, `get-shit-done/bin/lib/phase.cjs`
7	理解数据契约	`.planning/` 中生成的 PROJECT.md、ROADMAP.md、STATE.md

七、小结

GSD 的仓库结构揭示了一个深刻的工程选择：用纯文本解决复杂系统的所有问题。

命令是 Markdown，工作流是 Markdown，Agent 定义是 Markdown
状态持久化是 Markdown + JSON，没有数据库
配置是 JSON，遵循 "Absent = Enabled" 的极简哲学
安装器用 ~3,000 行 JS 适配 12+ 不同的 AI 编程助手

这种设计让 GSD 具备了极致的可移植性和可审计性——你可以用 cat 读懂任何一个文件，用 git diff 追踪任何一次变更，用 grep 搜索任何一段逻辑。

📌 关键洞察：GSD 不是一个程序，它是一个用 Markdown 编写的操作系统——运行在 AI 编程助手的上下文窗口里，以文件系统为持久化层，以 Prompt 为指令集。

下一篇预告： 第 03 篇《Command 层设计哲学 —— 一条 /gsd 命令的诞生》

我们将深入 commands/gsd/*.md，拆解一条命令文件的完整结构：YAML frontmatter 的设计意图、块的自描述约定、allowed-tools 的权限模型，以及 GSD 如何用纯文本实现「命令即配置、配置即代码」。敬请期待。