命令系统架构 - 和平哥的学习笔记

这是「GSD 全景代码解析」专题的第 6 篇。上一篇（第 05 篇）我们梳理了 Agent 的注册与路由机制，了解了 Agent 如何被调度和编排；本篇将聚焦于用户与 GSD 交互的第一入口——命令系统。我们将深入解析命令文件的 YAML frontmatter 规范、命令分类体系，以及命令如何作为触发器，串联起整个工作流和 Agent 调用链。

命令系统的定位：用户与 GSD 的第一接触点

在 GSD 的体系架构中，**命令系统（Command System）**是用户与系统交互的唯一显性入口。无论是初始化新项目、规划开发阶段、执行编码任务，还是审查代码质量，用户都通过输入 /gsd:command-name 这样的命令来触发对应的功能。

从架构视角看，命令系统位于 GSD 的最顶层，它承担着三个核心职责：

语义路由：将用户的自然语言意图，映射为具体的、可执行的工作流文件。
权限管控：通过 allowed-tools 字段，精确控制每个命令在执行期间可以调用的工具集，实现最小权限原则。
上下文封装：命令文件本身就是一份"封装好的 Prompt"，它定义了本次交互的目标、输入参数、执行流程和预期产出。

flowchart TD
    A[用户输入 /gsd:new-project] --> B[命令解析器]
    B --> C{命令文件匹配}
    C -->|匹配成功| D[读取命令 Markdown 文件]
    D --> E[解析 YAML frontmatter]
    E --> F[加载 Prompt 主体]
    F --> G[构建完整上下文]
    G --> H[路由到对应工作流]
    H --> I[调度 Agent 执行]
    I --> J[输出结果]

上图展示了命令的完整调用链：命令 → 工作流 → Agent。用户发出的每一个命令，最终都会被解析为一个 Markdown 文件，该文件指导 Agent 如何完成任务。

命令文件格式：Markdown 作为可执行契约

GSD 的一个精妙设计是：每个命令本质上就是一个 Markdown 文件。这种设计使得命令同时具备人类可读性和机器可执行性。

文件路径与命名约定

命令文件统一存放在 commands/gsd/ 目录下，文件名即命令名，采用小写、连字符连接的风格：

commands/gsd/
├── new-project.md
├── plan-phase.md
├── execute-phase.md
├── verify-work.md
├── debug.md
├── stats.md
└── ...（80+ 个命令文件）

用户输入 /gsd:new-project 时，系统会查找并加载 commands/gsd/new-project.md 文件。

文件结构解析

一个典型的命令文件包含两大部分：

1. YAML Frontmatter

位于文件顶部的 --- 围栏内，定义命令的元数据：

---
name: gsd:new-project
description: Initialize a new project with deep context gathering and PROJECT.md
argument-hint: "[--auto]"
allowed-tools:
  - Read
  - Bash
  - Write
  - Task
  - AskUserQuestion
---

各字段含义如下：

字段	类型	说明
`name`	string	命令的完整标识符，格式为 `gsd:command-name`
`description`	string	命令的简短描述，用于帮助文档和 IDE 提示
`argument-hint`	string	参数提示模板，如 `[--auto]` 或 `[phase-number]`
`allowed-tools`	list	该命令执行期间被允许调用的工具白名单

2. Prompt 主体

YAML frontmatter 之后是 Markdown 正文，这部分是真正的执行逻辑。它通常包含以下几个标准区块：

<runtime_note>
**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
</runtime_note>

<context>
**Flags:**
- `--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction.
</context>

<objective>
Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.

**Creates:**
- `.planning/PROJECT.md` — project context
- `.planning/config.json` — workflow preferences
- `.planning/research/` — domain research (optional)
- `.planning/REQUIREMENTS.md` — scoped requirements
- `.planning/ROADMAP.md` — phase structure
- `.planning/STATE.md` — project memory

**After this command:** Run `/gsd:plan-phase 1` to start execution.
</objective>

<execution_context>
@~/.claude/get-shit-done/workflows/new-project.md
@~/.claude/get-shit-done/references/questioning.md
@~/.claude/get-shit-done/references/ui-brand.md
@~/.claude/get-shit-done/templates/project.md
@~/.claude/get-shit-done/templates/requirements.md
</execution_context>

<process>
Execute the new-project workflow from @~/.claude/get-shit-done/workflows/new-project.md end-to-end.
Preserve all workflow gates (validation, approvals, commits, routing).
</process>

各区块的职责：

区块	职责
`<runtime_note>`	提供运行时适配说明，如不同 IDE 下的工具等价映射
`<context>`	定义命令可用的 flags、参数及其语义
`<objective>`	明确命令的目标、产出物，以及后续操作建议
`<execution_context>`	列出该命令依赖的工作流文件、参考文档和模板（`@` 语法引用）
`<process>`	描述执行步骤，包括需要遵循的验证关卡和决策门

命令分类体系：80+ 命令的六维划分

GSD 的命令系统规模庞大，超过 80 个命令覆盖了软件项目从诞生到交付的全生命周期。为了便于理解和使用，我们可以将所有命令划分为六大类别。

flowchart LR
    subgraph 命令分类体系
        A[项目生命周期] --- B[规划类]
        B --- C[执行类]
        C --- D[验证类]
        D --- E[讨论类]
        E --- F[管理类]
        F --- G[调试类]
    end

1. 项目生命周期（Lifecycle）

负责项目的创建、导入和整体管理，是项目的起点和终点。

命令	功能
`new-project`	初始化新项目，收集上下文，生成 PROJECT.md、ROADMAP.md 等
`import`	将现有代码库导入 GSD 管理体系
`map-codebase`	扫描代码库结构，生成代码地图
`cleanup`	清理项目中的临时文件和过时状态

new-project 是入口命令：它创建 .planning/ 目录骨架，填充初始文档，并设置后续阶段的工作基础。

2. 规划类（Planning）

在编码之前进行研究和设计，确保"做正确的事"。

命令	功能
`plan-phase`	为指定阶段制定详细计划，包含研究、规划和验证
`research-phase`	对指定阶段进行领域研究
`spec-phase`	生成技术规格说明
`spike`	进行技术预研和可行性验证
`discuss-phase`	在实施前讨论灰区决策，捕获实现决策

3. 执行类（Execution）

真正编写代码、实现功能的命令，是 GSD 的核心生产力工具。

命令	功能
`execute-phase`	执行完整阶段的所有任务
`do`	执行单个具体任务
`quick`	快速执行模式，跳过部分验证关卡
`fast`	极速模式，最小交互完成原子操作

4. 验证类（Verification）

确保代码质量和工作正确性的命令。

命令	功能
`verify-work`	验证当前工作成果是否符合预期
`code-review`	执行代码审查
`audit`	审计项目状态和合规性

5. 讨论类（Discussion）

在编码前或编码中捕获设计决策，形成可追溯的上下文。

命令	功能
`discuss-phase`	对指定阶段进行讨论，产出 CONTEXT.md 和 DISCUSSION-LOG.md
`ui-phase`	为前端阶段生成 UI 设计契约（UI-SPEC.md）

6. 管理与调试（Management & Debug）

系统维护、状态查看和故障排查。

类别	命令	功能
管理类	`settings`	配置 GSD 工作流偏好
	`stats`	查看项目统计信息
	`help`	获取命令帮助
	`manager`	项目管理面板
调试类	`debug`	诊断和修复执行问题

命令与工作流的关系：触发器模式

命令系统与工作流系统的边界非常清晰：命令是触发器，工作流是剧本。

sequenceDiagram
    participant U as 用户
    participant C as 命令文件
(new-project.md)
    participant W as 工作流引擎
    participant A as Agent 调度器
    participant T as 工具层

    U->>C: 输入 /gsd:new-project --auto
    C->>C: 解析 YAML frontmatter
提取 allowed-tools
    C->>C: 加载 Prompt 主体
解析 
    C->>W: 引用并加载
workflows/new-project.md
    W->>W: 执行工作流步骤
    W->>A: 请求 Agent 执行子任务
    A->>T: 根据 allowed-tools 白名单
调用 Read/Bash/Write 等工具
    T-->>A: 工具执行结果
    A-->>W: 子任务完成
    W-->>C: 工作流执行完毕
    C-->>U: 返回结果：PROJECT.md 等已生成

这个调用链体现了 GSD 架构的分层解耦思想：

命令层只负责"翻译"用户意图，它不直接执行任何操作。
工作流层定义了执行步骤和决策门，是业务逻辑的真正载体。
Agent 层负责任务的自动化执行，它调用工具层完成具体的读写、搜索、代码编辑等操作。
工具层提供原子能力，但受 allowed-tools 白名单约束。

allowed-tools：最小权限原则的实践

allowed-tools 是 GSD 命令系统中一个重要的安全与隔离机制。它明确列出了每个命令在执行期间可以调用的工具，未列入白名单的工具即使被 Agent 请求，也会被系统拒绝。

以 new-project 命令为例：

allowed-tools:
  - Read      # 读取文件
  - Bash      # 执行 shell 命令
  - Write     # 写入文件
  - Task      # 创建子任务
  - AskUserQuestion  # 向用户提问

GSD 中常见的工具类型及其权限含义：

工具	权限级别	典型使用场景
`Read`	只读	读取项目文件、模板、配置
`Bash`	中风险	执行 git 操作、安装依赖、运行脚本
`Write`	高风险	创建/修改项目文件、生成文档
`Task`	中风险	创建并行子任务、调用其他工作流
`AskUserQuestion`	安全	与用户进行交互式确认
`WebSearch`	低风险	联网搜索信息、查找文档
`Edit`	高风险	修改现有代码文件

为什么需要 allowed-tools？

安全隔离：防止命令越权操作。例如，stats 命令只需要 Read 权限，不需要 Write。
可预测性：用户可以通过 allowed-tools 预判命令的副作用范围。
调试友好：当命令行为异常时，可以快速定位是否为工具权限配置问题。

命令文件结构模板解析

下面我们以 new-project.md 为例，完整解析一个命令文件的结构：

---
name: gsd:new-project
description: Initialize a new project with deep context gathering and PROJECT.md
argument-hint: "[--auto]"
allowed-tools:
  - Read
  - Bash
  - Write
  - Task
  - AskUserQuestion
---

<runtime_note>
**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
</runtime_note>

<context>
**Flags:**
- `--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction.
</context>

<objective>
Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.

**Creates:**
- `.planning/PROJECT.md` — project context
- `.planning/config.json` — workflow preferences
- `.planning/RESEARCH.md` — domain research (optional)
- `.planning/REQUIREMENTS.md` — scoped requirements
- `.planning/ROADMAP.md` — phase structure
- `.planning/STATE.md` — project memory

**After this command:** Run `/gsd:plan-phase 1` to start execution.
</objective>

<execution_context>
@~/.claude/get-shit-done/workflows/new-project.md
@~/.claude/get-shit-done/references/questioning.md
@~/.claude/get-shit-done/references/ui-brand.md
@~/.claude/get-shit-done/templates/project.md
@~/.claude/get-shit-done/templates/requirements.md
</execution_context>

<process>
Execute the new-project workflow from @~/.claude/get-shit-done/workflows/new-project.md end-to-end.
Preserve all workflow gates (validation, approvals, commits, routing).
</process>

关键设计洞察：

命令是轻量的：真正的业务逻辑在工作流文件（workflows/new-project.md）中，命令文件只负责"激活"工作流。
@ 引用语法：<execution_context> 中的 @path 语法用于声明依赖，系统会在执行前预加载这些文件。
后续操作建议：<objective> 中明确告知用户"接下来该做什么"，形成连贯的交互体验。

小结

命令系统是 GSD 的用户门面和架构入口。它的核心设计哲学可以概括为三点：

Markdown 即契约：每个命令文件既是人类可读的文档，又是机器可执行的指令，实现了文档与代码的统一。
触发器模式：命令不直接执行业务逻辑，而是引用和触发工作流，实现了关注点分离。
最小权限：allowed-tools 白名单机制确保每个命令只能使用必要的工具，提升了系统的安全性和可预测性。

理解命令系统后，我们实际上已经掌握了 GSD 的用户交互全貌。下一篇将深入到命令所引用的工作流系统，从 `new-project` 开始，拆解项目生命周期命令的具体实现。

下一篇预告： 第 07 篇《项目生命周期命令（上）》

我们将深入解析 new-project、import、map-codebase 等生命周期命令的内部工作流，揭示 GSD 如何从零开始为一个项目建立完整的规划体系。敬请期待。