refactor: hard-fork GSD -> MSD (Make Software Done)

Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.
This commit is contained in:
Jakub Zych
2026-10-06 01:47:40 +02:00
parent fe069b2a56
commit a9a7a328e6
2763 changed files with 78465 additions and 78434 deletions

View File

@@ -1,4 +1,4 @@
# GSD Core 架构
# MSD Core 架构
> 面向贡献者和高级用户的系统架构说明。如需面向用户的文档,请参阅[功能参考](FEATURES.md)或[用户指南](USER-GUIDE.md)。
@@ -21,7 +21,7 @@
## 系统概述
GSD Core 是一个**元提示框架**,位于用户与 AI 编码 Agent(Claude Code、Kimi CLI、OpenCode、Kilo、Codex、Copilot、Antigravity、Trae、Cline、Augment Code)之间。它提供:
MSD Core 是一个**元提示框架**,位于用户与 AI 编码 Agent(Claude Code、Kimi CLI、OpenCode、Kilo、Codex、Copilot、Antigravity、Trae、Cline、Augment Code)之间。它提供:
1. **上下文工程** — 结构化产物,为每个任务向 AI 提供所需的全部信息(参见[上下文工程](explanation/context-engineering.md))
2. **多 Agent 编排** — 轻量级编排器,以全新上下文窗口派生专用 Agent(参见[多 Agent 编排](explanation/multi-agent-orchestration.md))
@@ -31,18 +31,18 @@ GSD Core 是一个**元提示框架**,位于用户与 AI 编码 Agent(Claude
```
┌──────────────────────────────────────────────────────┐
│ USER │
│ /gsd-command [args] │
│ /msd-command [args] │
└─────────────────────┬────────────────────────────────┘
│
┌─────────────────────▼────────────────────────────────┐
│ COMMAND LAYER │
│ commands/gsd/*.md — Prompt-based command files │
│ commands/msd/*.md — Prompt-based command files │
│ (Claude Code custom commands / Codex skills) │
└─────────────────────┬────────────────────────────────┘
│
┌─────────────────────▼────────────────────────────────┐
│ WORKFLOW LAYER │
│ gsd-core/workflows/*.md — Orchestration logic │
│ msd-core/workflows/*.md — Orchestration logic │
│ (Reads references, spawns agents, manages state) │
└──────┬──────────────┬─────────────────┬──────────────┘
│ │ │
@@ -54,7 +54,7 @@ GSD Core 是一个**元提示框架**,位于用户与 AI 编码 Agent(Claude
│ │ │
┌──────▼──────────────▼─────────────────▼──────────────┐
│ CLI TOOLS LAYER │
│ gsd-tools.cjs command families + domain modules │
│ msd-tools.cjs command families + domain modules │
│ command-routing-hub + observability seams │
└──────────────────────┬───────────────────────────────┘
│
@@ -75,9 +75,9 @@ GSD Core 是一个**元提示框架**,位于用户与 AI 编码 Agent(Claude
### 2. 轻量级编排器
工作流文件(`gsd-core/workflows/*.md`)不承担繁重工作。它们:
工作流文件(`msd-core/workflows/*.md`)不承担繁重工作。它们:
- 通过 `gsd-tools.cjs init <workflow>` 加载上下文
- 通过 `msd-tools.cjs init <workflow>` 加载上下文
- 以聚焦的提示词派生专用 Agent
- 收集结果并路由到下一步
- 在步骤之间更新状态
@@ -107,33 +107,33 @@ GSD Core 是一个**元提示框架**,位于用户与 AI 编码 Agent(Claude
## 组件架构
### 命令(`commands/gsd/*.md`)
### 命令(`commands/msd/*.md`)
面向用户的入口点。每个文件包含 YAML 前置元数据(name、description、allowed-tools)以及引导工作流的提示词主体。命令按如下方式安装:
- **Claude Code:** 自定义斜线命令(连字符形式,`/gsd-command-name`)
- **OpenCode / Kilo:** 斜线命令(连字符形式,`/gsd-command-name`)
- **Codex:** 技能(`$gsd-command-name`)
- **Copilot:** 斜线命令(连字符形式,`/gsd-command-name`)
- **Claude Code:** 自定义斜线命令(连字符形式,`/msd-command-name`)
- **OpenCode / Kilo:** 斜线命令(连字符形式,`/msd-command-name`)
- **Codex:** 技能(`$msd-command-name`)
- **Copilot:** 斜线命令(连字符形式,`/msd-command-name`)
- **Antigravity:** 技能
**命令总数:** 请参阅 [`docs/INVENTORY.md`](INVENTORY.md#commands) 获取权威数量及完整列表。
#### 两阶段层级路由(v1.40,[#2792](https://github.com/open-gsd/gsd-core/issues/2792))
为控制急于列举技能的 token 开销,v1.40 引入了六个命名空间**元技能**(`gsd-workflow`、`gsd-project`、`gsd-quality`、`gsd-context`、`gsd-manage`、`gsd-ideate`——源自 `commands/gsd/ns-*.md`,但可调用的 `name:` 为此处显示的简短形式),位于具体子技能之上。模型看到的是 6 个命名空间路由器(约 120 个 token),而非扁平的 86 个技能列表(约 2,150 个 token),选择命名空间后通过嵌入在命名空间路由器主体中的路由表路由到具体子技能。命名空间技能是**可叠加的**——每个具体命令仍可直接调用。
为控制急于列举技能的 token 开销,v1.40 引入了六个命名空间**元技能**(`msd-workflow`、`msd-project`、`msd-quality`、`msd-context`、`msd-manage`、`msd-ideate`——源自 `commands/msd/ns-*.md`,但可调用的 `name:` 为此处显示的简短形式),位于具体子技能之上。模型看到的是 6 个命名空间路由器(约 120 个 token),而非扁平的 86 个技能列表(约 2,150 个 token),选择命名空间后通过嵌入在命名空间路由器主体中的路由表路由到具体子技能。命名空间技能是**可叠加的**——每个具体命令仍可直接调用。
路由器描述使用管道分隔的关键词标签(≤ 60 个字符),符合工具注意力研究的结论:关键词密集的标签在路由效果上优于散文,且 token 开销仅约 40%。
#### MCP token 预算交互
急于列举技能是每轮两种反复出现的 token 开销之一。另一种是 `.claude/settings.json` 中每个已启用 MCP 服务器注入的 MCP 工具 schema。重型 MCP 服务器(browser/playwright、Mac-tools、Windows-tools)每轮各自可消耗 20k+ token——通常远超 `model_profile` 调优所节省的量。该开关位于 Claude Code 框架中(`.claude/settings.json` 中的 `enabledMcpjsonServers` / `disabledMcpjsonServers`),**不属于** GSD 的关注范围。两阶段路由层(#2792)和严格的 MCP 启用管理是每轮最大的成本杠杆。请参阅 [`docs/USER-GUIDE.md`](USER-GUIDE.md) 和 `references/context-budget.md` 了解审计清单。
急于列举技能是每轮两种反复出现的 token 开销之一。另一种是 `.claude/settings.json` 中每个已启用 MCP 服务器注入的 MCP 工具 schema。重型 MCP 服务器(browser/playwright、Mac-tools、Windows-tools)每轮各自可消耗 20k+ token——通常远超 `model_profile` 调优所节省的量。该开关位于 Claude Code 框架中(`.claude/settings.json` 中的 `enabledMcpjsonServers` / `disabledMcpjsonServers`),**不属于** MSD 的关注范围。两阶段路由层(#2792)和严格的 MCP 启用管理是每轮最大的成本杠杆。请参阅 [`docs/USER-GUIDE.md`](USER-GUIDE.md) 和 `references/context-budget.md` 了解审计清单。
### 工作流(`gsd-core/workflows/*.md`)
### 工作流(`msd-core/workflows/*.md`)
命令所引用的编排逻辑,包含逐步流程:
- 通过 `gsd-tools.cjs init` 处理程序加载上下文
- 通过 `msd-tools.cjs init` 处理程序加载上下文
- 带有模型解析的 Agent 派生指令
- 关卡/检查点定义
- 状态更新模式
@@ -143,7 +143,7 @@ GSD Core 是一个**元提示框架**,位于用户与 AI 编码 Agent(Claude
#### 工作流的渐进式披露
工作流文件在每次调用对应的 `/gsd-*` 命令时会被完整加载到 Claude 的上下文中。为控制该成本,`tests/workflow-size-budget.test.cjs` 强制执行的工作流大小预算与 Agent 大小预算惯例保持一致:
工作流文件在每次调用对应的 `/msd-*` 命令时会被完整加载到 Claude 的上下文中。为控制该成本,`tests/workflow-size-budget.test.cjs` 强制执行的工作流大小预算与 Agent 大小预算惯例保持一致:
| 层级 | 每文件行数限制 |
|-----------|--------------------|
@@ -151,7 +151,7 @@ GSD Core 是一个**元提示框架**,位于用户与 AI 编码 Agent(Claude
| `LARGE` | 1500 — 多步骤规划器和大型功能工作流 |
| `DEFAULT` | 1000 — 聚焦于单一目的的工作流(目标层级) |
根据 discuss-phase 字节预算(#717;discuss-phase/modes 分割使其保持在 ≈32000 字节),`workflows/discuss-phase.md` 须严格遵守更严格的上限。当工作流超出其层级时,应将各模式的主体提取到 `workflows/<workflow>/modes/<mode>.md`,将模板提取到 `workflows/<workflow>/templates/`,将共享知识提取到 `gsd-core/references/`。父文件成为轻量级调度器,仅读取当前调用所需的模式和模板文件。
根据 discuss-phase 字节预算(#717;discuss-phase/modes 分割使其保持在 ≈32000 字节),`workflows/discuss-phase.md` 须严格遵守更严格的上限。当工作流超出其层级时,应将各模式的主体提取到 `workflows/<workflow>/modes/<mode>.md`,将模板提取到 `workflows/<workflow>/templates/`,将共享知识提取到 `msd-core/references/`。父文件成为轻量级调度器,仅读取当前调用所需的模式和模板文件。
`workflows/discuss-phase/` 是该模式的典型示例——父文件负责调度,`modes/` 存放各标志的行为(`power.md`、`all.md`、`auto.md`、`chain.md`、`text.md`、`batch.md`、`analyze.md`、`default.md`、`advisor.md`),`templates/` 存放 CONTEXT.md、DISCUSSION-LOG.md 以及仅在写入对应输出文件时才读取的 checkpoint.json schema。
@@ -166,7 +166,7 @@ GSD Core 是一个**元提示框架**,位于用户与 AI 编码 Agent(Claude
**Agent 总数:** 33
### 参考文档(`gsd-core/references/*.md`)
### 参考文档(`msd-core/references/*.md`)
工作流和 Agent 通过 `@-reference` 引用的共享知识文档(请参阅 [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) 获取权威数量及完整列表):
@@ -204,7 +204,7 @@ GSD Core 是一个**元提示框架**,位于用户与 AI 编码 Agent(Claude
**思考模型参考:**
将思考类模型(o3、o4-mini、Gemini 2.5 Pro)集成到 GSD 工作流的参考文档:
将思考类模型(o3、o4-mini、Gemini 2.5 Pro)集成到 MSD 工作流的参考文档:
- `thinking-models-debug.md` — 调试工作流的思考模型模式
- `thinking-models-execution.md` — 执行 Agent 的思考模型模式
@@ -214,15 +214,15 @@ GSD Core 是一个**元提示框架**,位于用户与 AI 编码 Agent(Claude
**模块化规划器分解:**
规划器 Agent(`agents/gsd-planner.md`)已从单一整体文件分解为一个核心 Agent 加参考模块,以遵守部分运行时强加的 50K 字符限制:
规划器 Agent(`agents/msd-planner.md`)已从单一整体文件分解为一个核心 Agent 加参考模块,以遵守部分运行时强加的 50K 字符限制:
- `planner-gap-closure.md` — 缺口修复模式行为(读取 VERIFICATION.md,针对性重规划)
- `planner-reviews.md` — 跨 AI 审查集成(从 `/gsd-review` 读取 REVIEWS.md)
- `planner-reviews.md` — 跨 AI 审查集成(从 `/msd-review` 读取 REVIEWS.md)
- `planner-revision.md` — 用于迭代细化的计划修订模式
### 模板(`gsd-core/templates/`)
### 模板(`msd-core/templates/`)
所有规划产物的 Markdown 模板。由 `gsd-tools.cjs template fill` / `phase.scaffold`(以及顶级 `scaffold`)使用,以创建预结构化文件:
所有规划产物的 Markdown 模板。由 `msd-tools.cjs template fill` / `phase.scaffold`(以及顶级 `scaffold`)使用,以创建预结构化文件:
- `project.md`、`requirements.md`、`roadmap.md`、`state.md` — 核心项目文件
- `phase-prompt.md` — 阶段执行提示词模板
- `summary.md`(及 `summary-minimal.md`、`summary-standard.md`、`summary-complex.md`)— 粒度感知摘要模板
@@ -238,28 +238,28 @@ GSD Core 是一个**元提示框架**,位于用户与 AI 编码 Agent(Claude
| Hook | 事件 | 用途 |
|------|-------|---------|
| `gsd-statusline.js` | `statusLine` | 显示模型、任务、目录及上下文使用量进度条 |
| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | 在剩余上下文为 35%/25% 时向 Agent 注入上下文警告 |
| `gsd-check-update.js` | `SessionStart` | 触发后台更新检查的前台触发器 |
| `gsd-check-update-worker.js` | (辅助程序) | 由 `gsd-check-update.js` 派生的后台工作进程;不直接注册事件 |
| `gsd-prompt-guard.js` | `PreToolUse` | 扫描 `.planning/` 写入内容中的提示词注入模式(建议性) |
| `gsd-read-injection-scanner.js` | `PostToolUse` | 扫描 Read 工具输出中不受信任内容里的注入指令 |
| `gsd-workflow-guard.js` | `PreToolUse` | 检测 GSD 工作流上下文之外的文件编辑(建议性,通过 `hooks.workflow_guard` 选择启用) |
| `gsd-secret-read-guard.js` | `PreToolUse` | 硬性阻止通过 Read / Grep / Bash 读取 `.env`、`.env.<suffix>`(`.env.example` 等模板除外)和 `.secrets`;取代安装程序以前写入的 `Read(.env*)` 拒绝规则(#4221) |
| `gsd-read-guard.js` | `PreToolUse` | 建议性防护,防止对本会话中尚未读取的文件执行 Edit/Write |
| `gsd-session-state.sh` | `SessionStart` | 基于 shell 的运行时的会话状态跟踪 |
| `gsd-validate-commit.sh` | `PreToolUse` | 用于规范提交格式执行的提交验证 |
| `gsd-phase-boundary.sh` | `PostToolUse` | 工作流转换的阶段边界检测 |
| `msd-statusline.js` | `statusLine` | 显示模型、任务、目录及上下文使用量进度条 |
| `msd-context-monitor.js` | `PostToolUse` / `AfterTool` | 在剩余上下文为 35%/25% 时向 Agent 注入上下文警告 |
| `msd-check-update.js` | `SessionStart` | 触发后台更新检查的前台触发器 |
| `msd-check-update-worker.js` | (辅助程序) | 由 `msd-check-update.js` 派生的后台工作进程;不直接注册事件 |
| `msd-prompt-guard.js` | `PreToolUse` | 扫描 `.planning/` 写入内容中的提示词注入模式(建议性) |
| `msd-read-injection-scanner.js` | `PostToolUse` | 扫描 Read 工具输出中不受信任内容里的注入指令 |
| `msd-workflow-guard.js` | `PreToolUse` | 检测 MSD 工作流上下文之外的文件编辑(建议性,通过 `hooks.workflow_guard` 选择启用) |
| `msd-secret-read-guard.js` | `PreToolUse` | 硬性阻止通过 Read / Grep / Bash 读取 `.env`、`.env.<suffix>`(`.env.example` 等模板除外)和 `.secrets`;取代安装程序以前写入的 `Read(.env*)` 拒绝规则(#4221) |
| `msd-read-guard.js` | `PreToolUse` | 建议性防护,防止对本会话中尚未读取的文件执行 Edit/Write |
| `msd-session-state.sh` | `SessionStart` | 基于 shell 的运行时的会话状态跟踪 |
| `msd-validate-commit.sh` | `PreToolUse` | 用于规范提交格式执行的提交验证 |
| `msd-phase-boundary.sh` | `PostToolUse` | 工作流转换的阶段边界检测 |
请参阅 [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped) 获取权威的 11 个 hook 列表。
### 命令路由中枢(`gsd-core/bin/lib/command-routing-hub.cjs`)
### 命令路由中枢(`msd-core/bin/lib/command-routing-hub.cjs`)
CJS 命令族路由器通过 `CommandRoutingHub` 进行调度。中枢拥有不抛出异常的纯结果契约(`hub.dispatch()` 捕获内部异常并返回 `{ ok: false, kind, ...typedPayload }`)以及封闭的运行时错误分类(`UnknownCommand`、`InvalidArgs`、`HandlerRefusal`、`HandlerFailure`)。路由器适配器保持为轻量级 CLI 转换器——它们构建中枢、调用 `dispatch`,然后将结果映射到 `output()`/`error()` 调用。运行时为单路径(无双运行时模式选择)。参见 `docs/adr/0174-retire-gsd-sdk-package-boundary.md`。
CJS 命令族路由器通过 `CommandRoutingHub` 进行调度。中枢拥有不抛出异常的纯结果契约(`hub.dispatch()` 捕获内部异常并返回 `{ ok: false, kind, ...typedPayload }`)以及封闭的运行时错误分类(`UnknownCommand`、`InvalidArgs`、`HandlerRefusal`、`HandlerFailure`)。路由器适配器保持为轻量级 CLI 转换器——它们构建中枢、调用 `dispatch`,然后将结果映射到 `output()`/`error()` 调用。运行时为单路径(无双运行时模式选择)。参见 `docs/adr/0174-retire-msd-sdk-package-boundary.md`。
### CLI 工具(`gsd-core/bin/`)
### CLI 工具(`msd-core/bin/`)
Node.js CLI 工具(`gsd-tools.cjs`),其领域模块分布在 `gsd-core/bin/lib/` 中(请参阅 [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) 获取权威列表):
Node.js CLI 工具(`msd-tools.cjs`),其领域模块分布在 `msd-core/bin/lib/` 中(请参阅 [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) 获取权威列表):
| 模块 | 职责 |
@@ -295,10 +295,10 @@ Node.js CLI 工具(`gsd-tools.cjs`),其领域模块分布在 `gsd-core/bin
```
Orchestrator (workflow .md)
│
├── Load context: gsd-tools.cjs init <workflow> <phase>
├── Load context: msd-tools.cjs init <workflow> <phase>
│ Returns JSON with: project info, config, state, phase details
│
├── Resolve model: gsd-tools.cjs resolve-model <agent-name>
├── Resolve model: msd-tools.cjs resolve-model <agent-name>
│ Returns: opus | sonnet | haiku | inherit
│
├── Spawn Agent (Task/SubAgent call)
@@ -309,28 +309,28 @@ Orchestrator (workflow .md)
│
├── Collect result
│
└── Update state: gsd-tools.cjs state update / state patch / state advance-plan
└── Update state: msd-tools.cjs state update / state patch / state advance-plan
```
### 主要 Agent 派生类别
21 个主要 Agent 的概念派生模式分类。完整的 31 个 Agent 权威列表(包括 10 个高级/专用 Agent,如 `gsd-pattern-mapper`、`gsd-code-reviewer`、`gsd-code-fixer`、`gsd-ai-researcher`、`gsd-domain-researcher`、`gsd-eval-planner`、`gsd-eval-auditor`、`gsd-framework-selector`、`gsd-debug-session-manager`、`gsd-intel-updater`),请参阅 [`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped)。
21 个主要 Agent 的概念派生模式分类。完整的 31 个 Agent 权威列表(包括 10 个高级/专用 Agent,如 `msd-pattern-mapper`、`msd-code-reviewer`、`msd-code-fixer`、`msd-ai-researcher`、`msd-domain-researcher`、`msd-eval-planner`、`msd-eval-auditor`、`msd-framework-selector`、`msd-debug-session-manager`、`msd-intel-updater`),请参阅 [`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped)。
| 类别 | Agent | 并行性 |
| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **研究者** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 路并行(技术栈、功能、架构、陷阱);advisor 在 discuss-phase 期间派生 |
| **综合者** | gsd-research-synthesizer | 串行(研究者完成后) |
| **规划者** | gsd-planner, gsd-roadmapper | 串行 |
| **检查者** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | 串行(验证循环,最多 3 次迭代) |
| **执行者** | gsd-executor | 波次内并行,波次间串行 |
| **验证者** | gsd-verifier | 串行(所有执行者完成后) |
| **映射者** | gsd-codebase-mapper | 4 路并行(技术、架构、质量、关注点) |
| **调试者** | gsd-debugger | 串行(交互式) |
| **审计者** | gsd-ui-auditor, gsd-security-auditor | 串行 |
| **文档写作者** | gsd-doc-writer, gsd-doc-verifier | 串行(写作者后接验证者) |
| **分析者** | gsd-user-profiler | 串行 |
| **假设分析者** | gsd-assumptions-analyzer | 串行(discuss-phase 期间) |
| **研究者** | msd-project-researcher, msd-phase-researcher, msd-ui-researcher, msd-advisor-researcher | 4 路并行(技术栈、功能、架构、陷阱);advisor 在 discuss-phase 期间派生 |
| **综合者** | msd-research-synthesizer | 串行(研究者完成后) |
| **规划者** | msd-planner, msd-roadmapper | 串行 |
| **检查者** | msd-plan-checker, msd-integration-checker, msd-ui-checker, msd-nyquist-auditor | 串行(验证循环,最多 3 次迭代) |
| **执行者** | msd-executor | 波次内并行,波次间串行 |
| **验证者** | msd-verifier | 串行(所有执行者完成后) |
| **映射者** | msd-codebase-mapper | 4 路并行(技术、架构、质量、关注点) |
| **调试者** | msd-debugger | 串行(交互式) |
| **审计者** | msd-ui-auditor, msd-security-auditor | 串行 |
| **文档写作者** | msd-doc-writer, msd-doc-verifier | 串行(写作者后接验证者) |
| **分析者** | msd-user-profiler | 串行 |
| **假设分析者** | msd-assumptions-analyzer | 串行(discuss-phase 期间) |
### 波次执行模型
@@ -360,7 +360,7 @@ Wave Analysis:
- **执行者 Agent** 接收前一波次的 SUMMARY.md 文件和阶段 CONTEXT.md/RESEARCH.md,从而实现阶段内跨计划感知
- **验证者 Agent** 接收所有 PLAN.md、SUMMARY.md、CONTEXT.md 文件及 REQUIREMENTS.md,实现历史感知验证
编排器从配置中读取 `context_window`(`gsd-tools.cjs config-get context_window`),当该值 >= 500,000 时,条件性地包含更丰富的上下文。对于标准 200K 窗口,提示词使用截断版本并以缓存友好的顺序排列,以最大化上下文效率。
编排器从配置中读取 `context_window`(`msd-tools.cjs config-get context_window`),当该值 >= 500,000 时,条件性地包含更丰富的上下文。对于标准 200K 窗口,提示词使用截断版本并以缓存友好的顺序排列,以最大化上下文效率。
#### 并行提交安全性
@@ -464,10 +464,10 @@ UI-SPEC.md (per phase) ───────────────────
```
~/.claude/ # Claude Code (global install)
├── skills/gsd-*/SKILL.md # Global skills (authoritative roster: docs/INVENTORY.md)
├── commands/gsd/*.md # Local Claude installs use slash commands instead of global skills
├── gsd-core/
│ ├── bin/gsd-tools.cjs # CLI utility
├── skills/msd-*/SKILL.md # Global skills (authoritative roster: docs/INVENTORY.md)
├── commands/msd/*.md # Local Claude installs use slash commands instead of global skills
├── msd-core/
│ ├── bin/msd-tools.cjs # CLI utility
│ ├── bin/lib/*.cjs # Domain modules (authoritative roster: docs/INVENTORY.md)
│ ├── workflows/*.md # Workflow definitions (authoritative roster: docs/INVENTORY.md)
│ ├── references/*.md # Shared reference docs (authoritative roster: docs/INVENTORY.md)
@@ -505,14 +505,14 @@ UI-SPEC.md (per phase) ───────────────────
├── STATE.md # Living memory: position, decisions, blockers, metrics
├── config.json # Workflow configuration
├── MILESTONES.md # Completed milestone archive
├── research/ # Domain research from /gsd-new-project
├── research/ # Domain research from /msd-new-project
│ ├── SUMMARY.md
│ ├── STACK.md
│ ├── FEATURES.md
│ ├── ARCHITECTURE.md
│ └── PITFALLS.md
├── codebase/ # Brownfield mapping (from /gsd-map-codebase or /gsd-onboard)
├── onboarding/ # Brownfield onboarding summary (from /gsd-onboard)
├── codebase/ # Brownfield mapping (from /msd-map-codebase or /msd-onboard)
├── onboarding/ # Brownfield onboarding summary (from /msd-onboard)
│ ├── STACK.md # YAML frontmatter carries `last_mapped_commit`
│ ├── ARCHITECTURE.md # for the post-execute drift gate (#2003)
│ ├── CONVENTIONS.md
@@ -538,26 +538,26 @@ UI-SPEC.md (per phase) ───────────────────
├── todos/
│ ├── pending/ # Captured ideas
│ └── completed/ # Completed todos
├── threads/ # Persistent context threads (from /gsd-thread)
├── seeds/ # Forward-looking ideas (from /gsd-capture --seed)
├── threads/ # Persistent context threads (from /msd-thread)
├── seeds/ # Forward-looking ideas (from /msd-capture --seed)
├── debug/ # Active debug sessions
│ ├── *.md # Active sessions
│ ├── resolved/ # Archived sessions
│ └── knowledge-base.md # Persistent debug learnings
├── ui-reviews/ # Screenshots from /gsd-ui-review (gitignored)
├── ui-reviews/ # Screenshots from /msd-ui-review (gitignored)
└── continue-here.md # Context handoff (from pause-work)
```
### 执行后代码库漂移关卡(#2003)
在 `/gsd-execute-phase` 最后一个波次提交后,工作流运行一个非阻塞性的 `codebase_drift_gate` 步骤(位于 `schema_drift_gate` 和 `verify_phase_goal` 之间)。它将 diff `last_mapped_commit..HEAD` 与 `.planning/codebase/STRUCTURE.md` 进行对比,并统计四类结构性元素:
在 `/msd-execute-phase` 最后一个波次提交后,工作流运行一个非阻塞性的 `codebase_drift_gate` 步骤(位于 `schema_drift_gate` 和 `verify_phase_goal` 之间)。它将 diff `last_mapped_commit..HEAD` 与 `.planning/codebase/STRUCTURE.md` 进行对比,并统计四类结构性元素:
1. 映射路径之外的新目录
2. `(packages|apps)/<name>/src/index.*` 处的新桶形导出
3. 新迁移文件
4. `routes/` 或 `api/` 下的新路由模块
若数量达到 `workflow.drift_threshold`(默认为 3),关卡将**警告**(默认)并显示建议的 `/gsd-map-codebase --paths …` 命令,或**自动重新映射**(`workflow.drift_action = auto-remap`),方法是派生 `gsd-codebase-mapper` 并将其范围限定为受影响的路径。检测或重新映射过程中的任何错误都会被记录,阶段继续执行——漂移检测不会导致验证失败。
若数量达到 `workflow.drift_threshold`(默认为 3),关卡将**警告**(默认)并显示建议的 `/msd-map-codebase --paths …` 命令,或**自动重新映射**(`workflow.drift_action = auto-remap`),方法是派生 `msd-codebase-mapper` 并将其范围限定为受影响的路径。检测或重新映射过程中的任何错误都会被记录,阶段继续执行——漂移检测不会导致验证失败。
`last_mapped_commit` 存储在每个 `.planning/codebase/*.md` 文件顶部的 YAML 前置元数据中;`bin/lib/drift.cjs` 提供 `readMappedCommit` 和 `writeMappedCommit` 往返辅助函数。
@@ -581,15 +581,15 @@ UI-SPEC.md (per phase) ───────────────────
- Windsurf:以技能为主,带 Windsurf 规则引用
- Trae:以技能为主安装到 `~/.trae` / `./.trae`,不含 `settings.json` 或 hook 集成
- Qwen Code:以技能为主,带 Qwen 品牌路径和提示词重写
- Hermes Agent:在 `skills/gsd/` 下按类别分组的技能
- Hermes Agent:在 `skills/msd/` 下按类别分组的技能
- CodeBuddy:以技能为主,带 CodeBuddy 路径和提示词重写
- Cline:为基于规则的集成写入 `.clinerules`
- Augment Code:以技能为主,完整技能转换和配置管理
5. **路径规范化** — 将 `~/.claude/` 路径替换为特定运行时路径
6. **设置集成** — 在运行时的 `settings.json` 中注册 hook
7. **补丁备份** — 自 v1.17 起,将本地修改的文件备份到 `gsd-local-patches/`,供 `/gsd-update --reapply` 使用
8. **清单跟踪** — 写入 `gsd-file-manifest.json` 以支持干净卸载
9. **卸载模式** — `--uninstall` 移除所有 GSD 文件、hook 和设置
7. **补丁备份** — 自 v1.17 起,将本地修改的文件备份到 `msd-local-patches/`,供 `/msd-update --reapply` 使用
8. **清单跟踪** — 写入 `msd-file-manifest.json` 以支持干净卸载
9. **卸载模式** — `--uninstall` 移除所有 MSD 文件、hook 和设置
安装时的文件移动、陈旧产物清理、配置重写和用户数据保留由安装程序迁移模块管理。请参阅[安装程序迁移](../installer-migrations.md)和 [ADR 0008](../adr/0008-installer-migration-module.md)。迁移模块还负责对旧版安装进行带关卡的首次基线扫描,在后续迁移移除或重写任何内容之前,对已知的运行时安装界面进行分类。
@@ -610,17 +610,17 @@ UI-SPEC.md (per phase) ───────────────────
```
Runtime Engine (Claude Code / Antigravity CLI)
│
├── statusLine event ──► gsd-statusline.js
├── statusLine event ──► msd-statusline.js
│ Reads: stdin (session JSON)
│ Writes: stdout (formatted status), /tmp/claude-ctx-{session}.json (bridge)
│
├── PostToolUse/AfterTool event ──► gsd-context-monitor.js
├── PostToolUse/AfterTool event ──► msd-context-monitor.js
│ Reads: stdin (tool event JSON), /tmp/claude-ctx-{session}.json (bridge)
│ Writes: stdout (hookSpecificOutput with additionalContext warning)
│
└── SessionStart event ──► gsd-check-update.js
└── SessionStart event ──► msd-check-update.js
Reads: VERSION file
Writes: ~/.claude/cache/gsd-update-check.json (spawns background process)
Writes: ~/.claude/cache/msd-update-check.json (spawns background process)
```
### 上下文监控阈值
@@ -647,15 +647,15 @@ Runtime Engine (Claude Code / Antigravity CLI)
研究者 → 规划者 → 执行者流水线包含一个针对 slopsquatting(AI 幻觉软件包名称被预先注册并附带恶意安装后脚本)的供应链关卡。
**威胁模型:** GSD 将从"研究者命名一个软件包"到"执行者运行 `npm install`"的完整路径自动化。一个通过 `npm view`(仅证明已注册,而非合法性)的幻觉名称此前可能未被检测到而流入。约 20% 的 AI 生成软件包引用是幻觉;其中约 43% 的名称在不同提示词中反复出现,使攻击者的预先注册在经济上可行。
**威胁模型:** MSD 将从"研究者命名一个软件包"到"执行者运行 `npm install`"的完整路径自动化。一个通过 `npm view`(仅证明已注册,而非合法性)的幻觉名称此前可能未被检测到而流入。约 20% 的 AI 生成软件包引用是幻觉;其中约 43% 的名称在不同提示词中反复出现,使攻击者的预先注册在经济上可行。
**关卡层次:**
| 层次 | 组件 | 操作 |
|-------|-----------|--------|
| 研究 | `gsd-phase-researcher` | 运行 `gsd-tools query package-legitimacy check --ecosystem <npm\|pypi\|crates> <pkgs>`;向 RESEARCH.md 写入 `## Package Legitimacy Audit` 表格;在写入 RESEARCH.md 之前剥离 `[SLOP]` 软件包 |
| 规划 | `gsd-planner` | 读取审计表;在任何 `[ASSUMED]` 或 `[SUS]` 安装任务之前插入 `checkpoint:human-verify`;向 `<threat_model>` 添加 `T-{phase}-SC` STRIDE 供应链行 |
| 执行 | `gsd-executor` | 规则 3 将软件包安装排除在自动修复范围之外;失败的安装以检查点形式呈现,而非静默替换 |
| 研究 | `msd-phase-researcher` | 运行 `msd-tools query package-legitimacy check --ecosystem <npm\|pypi\|crates> <pkgs>`;向 RESEARCH.md 写入 `## Package Legitimacy Audit` 表格;在写入 RESEARCH.md 之前剥离 `[SLOP]` 软件包 |
| 规划 | `msd-planner` | 读取审计表;在任何 `[ASSUMED]` 或 `[SUS]` 安装任务之前插入 `checkpoint:human-verify`;向 `<threat_model>` 添加 `T-{phase}-SC` STRIDE 供应链行 |
| 执行 | `msd-executor` | 规则 3 将软件包安装排除在自动修复范围之外;失败的安装以检查点形式呈现,而非静默替换 |
**声明溯源集成:** 通过 WebSearch 发现的软件包名称被标记为 `[ASSUMED]`(而非 `[VERIFIED]`),无论 `npm view` 结果如何。这通过在安装边界将溯源标签强制执行为硬关卡,扩展了现有的 `[ASSUMED]` / `[VERIFIED]` / `[CITED]` 溯源系统——`[ASSUMED]` 始终在 PLAN.md 中生成 `checkpoint:human-verify`。
@@ -671,25 +671,25 @@ Runtime Engine (Claude Code / Antigravity CLI)
有关 hook 和防护层如何融入更广泛安全方法的概念概述,请参阅[安全模型](explanation/security-model.md)。
**提示词防护**(`gsd-prompt-guard.js`):
**提示词防护**(`msd-prompt-guard.js`):
- 触发于对 `.planning/` 文件的 Write/Edit
- 扫描内容中的提示词注入模式(角色覆盖、指令绕过、系统标签注入)
- 仅建议性——记录检测结果,不阻止操作
- 模式已内联(`security.cjs` 的子集),以实现 hook 独立性
**工作流防护**(`gsd-workflow-guard.js`):
**工作流防护**(`msd-workflow-guard.js`):
- 触发于对非 `.planning/` 文件的 Write/Edit
- 检测 GSD 工作流上下文之外的编辑(无活动的 `/gsd-` 命令或任务子 Agent)
- 建议使用 `/gsd-quick` 或 `/gsd-fast` 进行状态跟踪的变更
- 检测 MSD 工作流上下文之外的编辑(无活动的 `/msd-` 命令或任务子 Agent)
- 建议使用 `/msd-quick` 或 `/msd-fast` 进行状态跟踪的变更
- 通过 `hooks.workflow_guard: true` 选择启用(默认:false)
---
## 运行时抽象
GSD 通过统一的命令/工作流架构支持多种 AI 编码运行时:
MSD 通过统一的命令/工作流架构支持多种 AI 编码运行时:
### 运行时安装契约矩阵
@@ -697,20 +697,20 @@ GSD 通过统一的命令/工作流架构支持多种 AI 编码运行时:
| 运行时 | 全局根目录 | 本地根目录 | 调用界面 | Agent 界面 | 配置与 hook |
| --- | --- | --- | --- | --- | --- |
| Claude Code | `~/.claude` | `./.claude` | 全局 `skills/gsd-*/SKILL.md`;本地 `commands/gsd/*.md` | `agents/gsd-*.md` | `settings.json` hook 和 statusLine 条目 |
| OpenCode | `~/.config/opencode` | `./.opencode` | `command/gsd-*.md` | `agents/gsd-*.md` | `opencode.json` 或 `opencode.jsonc`;无 GSD hook |
| Kilo | `~/.config/kilo` | `./.kilo` | `command/gsd-*.md` | `agents/gsd-*.md` | `kilo.json` 或 `kilo.jsonc`;无 GSD hook |
| Codex | `~/.codex` | `./.codex` | `skills/gsd-*/SKILL.md` | `agents/` 源 markdown 加每个 Agent 的 TOML | `config.toml` `[agents.gsd-*]`、`[features].hooks`(规范;遗留别名 `codex_hooks` 在重新安装时被识别并迁移到新版本,#3566)以及 hook 表 |
| GitHub Copilot | `~/.copilot` | `./.github` | `skills/gsd-*/SKILL.md` 和 `copilot-instructions.md` | `.agent.md` 文件 | 无 GSD hook 或 statusline |
| Antigravity | 自动检测:`~/.gemini/antigravity`、`~/.gemini/antigravity-ide` 或 `~/.gemini/antigravity-cli` | `./.agent` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | GSD 安装时的 Gemini 风格 `settings.json` hook 条目 |
| Cursor | `~/.cursor` | `./.cursor` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | `rules/` 下的规则引用;无 GSD hook |
| Windsurf | `~/.codeium/windsurf` | `./.windsurf` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | `rules/` 下的规则引用;无 GSD hook |
| Augment Code | `~/.augment` | `./.augment` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | 无 GSD hook 或 statusline |
| Trae | `~/.trae` | `./.trae` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | `rules/` 下的规则引用;无 GSD hook |
| Qwen Code | `~/.qwen` | `./.qwen` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | 通用 GSD 设置及在支持时的 hook 条目 |
| Hermes Agent | `~/.hermes` | `./.hermes` | `skills/gsd/DESCRIPTION.md` 加 `skills/gsd/gsd-*/SKILL.md` | `agents/gsd-*.md` | 通用 GSD 设置及在支持时的 hook 条目 |
| CodeBuddy | `~/.codebuddy` | `./.codebuddy` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | 通用 GSD 设置及在支持时的 hook 条目 |
| Cline | `~/.cline` | 项目根目录 | `.clinerules` | 仅规则 | 无 GSD hook 或 statusline |
| Claude Code | `~/.claude` | `./.claude` | 全局 `skills/msd-*/SKILL.md`;本地 `commands/msd/*.md` | `agents/msd-*.md` | `settings.json` hook 和 statusLine 条目 |
| OpenCode | `~/.config/opencode` | `./.opencode` | `command/msd-*.md` | `agents/msd-*.md` | `opencode.json` 或 `opencode.jsonc`;无 MSD hook |
| Kilo | `~/.config/kilo` | `./.kilo` | `command/msd-*.md` | `agents/msd-*.md` | `kilo.json` 或 `kilo.jsonc`;无 MSD hook |
| Codex | `~/.codex` | `./.codex` | `skills/msd-*/SKILL.md` | `agents/` 源 markdown 加每个 Agent 的 TOML | `config.toml` `[agents.msd-*]`、`[features].hooks`(规范;遗留别名 `codex_hooks` 在重新安装时被识别并迁移到新版本,#3566)以及 hook 表 |
| GitHub Copilot | `~/.copilot` | `./.github` | `skills/msd-*/SKILL.md` 和 `copilot-instructions.md` | `.agent.md` 文件 | 无 MSD hook 或 statusline |
| Antigravity | 自动检测:`~/.gemini/antigravity`、`~/.gemini/antigravity-ide` 或 `~/.gemini/antigravity-cli` | `./.agent` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | MSD 安装时的 Gemini 风格 `settings.json` hook 条目 |
| Cursor | `~/.cursor` | `./.cursor` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | `rules/` 下的规则引用;无 MSD hook |
| Windsurf | `~/.codeium/windsurf` | `./.windsurf` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | `rules/` 下的规则引用;无 MSD hook |
| Augment Code | `~/.augment` | `./.augment` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | 无 MSD hook 或 statusline |
| Trae | `~/.trae` | `./.trae` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | `rules/` 下的规则引用;无 MSD hook |
| Qwen Code | `~/.qwen` | `./.qwen` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | 通用 MSD 设置及在支持时的 hook 条目 |
| Hermes Agent | `~/.hermes` | `./.hermes` | `skills/msd/DESCRIPTION.md` 加 `skills/msd/msd-*/SKILL.md` | `agents/msd-*.md` | 通用 MSD 设置及在支持时的 hook 条目 |
| CodeBuddy | `~/.codebuddy` | `./.codebuddy` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | 通用 MSD 设置及在支持时的 hook 条目 |
| Cline | `~/.cline` | 项目根目录 | `.clinerules` | 仅规则 | 无 MSD hook 或 statusline |
### 上游契约来源
@@ -729,7 +729,7 @@ GSD 通过统一的命令/工作流架构支持多种 AI 编码运行时:
2. **Hook 事件名称** — Claude 使用 `PostToolUse`,Antigravity 使用 `AfterTool`
3. **Agent 前置元数据** — 每个运行时有其自己的 Agent 定义格式
4. **路径约定** — 每个运行时将配置存储在不同的目录中
5. **模型引用** — `inherit` 配置文件让 GSD 推迟到运行时的模型选择
5. **模型引用** — `inherit` 配置文件让 MSD 推迟到运行时的模型选择
安装程序在安装时处理所有转换。工作流和 Agent 以 Claude Code 的原生格式编写,并在部署期间进行转换。

View File

@@ -1,25 +1,25 @@
# GSD CLI 工具参考
# MSD CLI 工具参考
> `gsd-tools` CLI(`gsd-core/bin/gsd-tools.cjs`)参考文档。斜杠命令与用户流程请参见[命令参考](COMMANDS.md)。返回[文档索引](README.md)。
> `msd-tools` CLI(`msd-core/bin/msd-tools.cjs`)参考文档。斜杠命令与用户流程请参见[命令参考](COMMANDS.md)。返回[文档索引](README.md)。
---
## 概述
`gsd-tools.cjs` 集中处理配置解析、模型解析、阶段查找、Git 提交、摘要验证、状态管理以及模板操作,供 GSD 命令、工作流和代理使用。
`msd-tools.cjs` 集中处理配置解析、模型解析、阶段查找、Git 提交、摘要验证、状态管理以及模板操作,供 MSD 命令、工作流和代理使用。
| | |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **发布路径** | `gsd-core/bin/gsd-tools.cjs` |
| **实现** | `gsd-core/bin/lib/` 下的 20 个领域模块(以该目录为准) |
| **发布路径** | `msd-core/bin/msd-tools.cjs` |
| **实现** | `msd-core/bin/lib/` 下的 20 个领域模块(以该目录为准) |
| **状态** | 编排、工作流和自动化的主要运行时命令接口。 |
**用法(CJS):**
```bash
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
node msd-tools.cjs <command> [args] [--raw] [--cwd <path>]
```
**全局标志(CJS):**
@@ -40,47 +40,47 @@ node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
```bash
# 以 JSON 格式加载完整项目配置和状态
node gsd-tools.cjs state load
node msd-tools.cjs state load
# 以 JSON 格式输出 STATE.md frontmatter
node gsd-tools.cjs state json
node msd-tools.cjs state json
# 更新单个字段
node gsd-tools.cjs state update <field> <value>
node msd-tools.cjs state update <field> <value>
# 获取 STATE.md 内容或特定章节
node gsd-tools.cjs state get [section]
node msd-tools.cjs state get [section]
# 批量更新多个字段
node gsd-tools.cjs state patch --field1 val1 --field2 val2
node msd-tools.cjs state patch --field1 val1 --field2 val2
# 递增计划计数器
node gsd-tools.cjs state advance-plan
node msd-tools.cjs state advance-plan
# 记录执行指标
node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N]
node msd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N]
# 重新计算进度条
node gsd-tools.cjs state update-progress
node msd-tools.cjs state update-progress
# 添加决策
node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
node msd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
# 或从文件读取:
node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path]
node msd-tools.cjs state add-decision --summary-file path [--rationale-file path]
# 添加/解决阻塞项
node gsd-tools.cjs state add-blocker --text "..."
node gsd-tools.cjs state resolve-blocker --text "..."
node msd-tools.cjs state add-blocker --text "..."
node msd-tools.cjs state resolve-blocker --text "..."
# 记录会话连续性
node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
node msd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
# 阶段开始——为新阶段更新 STATE.md 的状态/最后活动
node gsd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT
node msd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT
# 代理可发现的阻塞信号(由 discuss-phase / UI 流程使用)
node gsd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
node gsd-tools.cjs state signal-resume
node msd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
node msd-tools.cjs state signal-resume
```
### 状态快照
@@ -88,7 +88,7 @@ node gsd-tools.cjs state signal-resume
对完整 STATE.md 进行结构化解析:
```bash
node gsd-tools.cjs state-snapshot
node msd-tools.cjs state-snapshot
```
返回 JSON,包含:当前位置、阶段、计划、状态、决策、阻塞项、指标、最后活动。
@@ -101,28 +101,28 @@ node gsd-tools.cjs state-snapshot
```bash
# 按编号查找阶段目录
node gsd-tools.cjs find-phase <phase>
node msd-tools.cjs find-phase <phase>
# 计算插入用的下一个小数阶段编号
node gsd-tools.cjs phase next-decimal <phase>
node msd-tools.cjs phase next-decimal <phase>
# 向路线图追加新阶段并创建目录
node gsd-tools.cjs phase add <description>
node msd-tools.cjs phase add <description>
# 在现有阶段后插入小数阶段
node gsd-tools.cjs phase insert <after> <description>
node msd-tools.cjs phase insert <after> <description>
# 移除阶段,对后续阶段重新编号
node gsd-tools.cjs phase remove <phase> [--force]
node msd-tools.cjs phase remove <phase> [--force]
# 标记阶段完成,更新状态和路线图
node gsd-tools.cjs phase complete <phase>
node msd-tools.cjs phase complete <phase>
# 按波次和状态索引计划
node gsd-tools.cjs phase-plan-index <phase>
node msd-tools.cjs phase-plan-index <phase>
# 列出阶段并过滤
node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
node msd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
```
---
@@ -133,13 +133,13 @@ node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--incl
```bash
# 从 ROADMAP.md 提取阶段章节
node gsd-tools.cjs roadmap get-phase <phase>
node msd-tools.cjs roadmap get-phase <phase>
# 带磁盘状态的完整路线图解析
node gsd-tools.cjs roadmap analyze
node msd-tools.cjs roadmap analyze
# 从磁盘更新进度表行
node gsd-tools.cjs roadmap update-plan-progress <N>
node msd-tools.cjs roadmap update-plan-progress <N>
```
---
@@ -150,16 +150,16 @@ node gsd-tools.cjs roadmap update-plan-progress <N>
```bash
# 以默认值初始化 config.json
node gsd-tools.cjs config-ensure-section
node msd-tools.cjs config-ensure-section
# 设置配置值(点号表示法)
node gsd-tools.cjs config-set <key> <value>
node msd-tools.cjs config-set <key> <value>
# 获取配置值
node gsd-tools.cjs config-get <key>
node msd-tools.cjs config-get <key>
# 设置模型配置文件
node gsd-tools.cjs config-set-model-profile <profile>
node msd-tools.cjs config-set-model-profile <profile>
```
---
@@ -168,13 +168,13 @@ node gsd-tools.cjs config-set-model-profile <profile>
```bash
# 根据当前配置文件获取代理使用的模型
node gsd-tools.cjs resolve-model <agent-name>
node msd-tools.cjs resolve-model <agent-name>
# 原始输出返回所选模型 ID/层级。
# JSON 输出还包括配置文件,以及当活跃运行时支持时的
# reasoning_effort。
```
代理名称:`gsd-planner`、`gsd-executor`、`gsd-phase-researcher`、`gsd-project-researcher`、`gsd-research-synthesizer`、`gsd-verifier`、`gsd-plan-checker`、`gsd-integration-checker`、`gsd-roadmapper`、`gsd-debugger`、`gsd-codebase-mapper`、`gsd-nyquist-auditor`
代理名称:`msd-planner`、`msd-executor`、`msd-phase-researcher`、`msd-project-researcher`、`msd-research-synthesizer`、`msd-verifier`、`msd-plan-checker`、`msd-integration-checker`、`msd-roadmapper`、`msd-debugger`、`msd-codebase-mapper`、`msd-nyquist-auditor`
---
@@ -184,25 +184,25 @@ node gsd-tools.cjs resolve-model <agent-name>
```bash
# 验证 SUMMARY.md 文件
node gsd-tools.cjs verify-summary <path> [--check-count N]
node msd-tools.cjs verify-summary <path> [--check-count N]
# 检查 PLAN.md 结构和任务
node gsd-tools.cjs verify plan-structure <file>
node msd-tools.cjs verify plan-structure <file>
# 检查所有计划是否有摘要
node gsd-tools.cjs verify phase-completeness <phase>
node msd-tools.cjs verify phase-completeness <phase>
# 检查 @-引用和路径是否可解析
node gsd-tools.cjs verify references <file>
node msd-tools.cjs verify references <file>
# 批量验证提交哈希
node gsd-tools.cjs verify commits <hash1> [hash2] ...
node msd-tools.cjs verify commits <hash1> [hash2] ...
# 检查 must_haves.artifacts
node gsd-tools.cjs verify artifacts <plan-file>
node msd-tools.cjs verify artifacts <plan-file>
# 检查 must_haves.key_links
node gsd-tools.cjs verify key-links <plan-file>
node msd-tools.cjs verify key-links <plan-file>
```
---
@@ -213,19 +213,19 @@ node gsd-tools.cjs verify key-links <plan-file>
```bash
# 检查阶段编号、磁盘/路线图同步
node gsd-tools.cjs validate consistency
node msd-tools.cjs validate consistency
# 检查 .planning/ 完整性,可选修复
node gsd-tools.cjs validate health [--repair]
node msd-tools.cjs validate health [--repair]
# 探测上下文窗口利用率(用于状态行/钩子调用方)(v1.40.0)
node gsd-tools.cjs validate context
node msd-tools.cjs validate context
# 以类型化 JSON 接口输出上下文利用率(#455)
node gsd-tools.cjs validate context --json
node msd-tools.cjs validate context --json
```
`validate context` 输出包含 `utilization`、`status`(在 60% / 70% 阈值处分别为 `ok` / `warn` / `critical`)以及 `suggestion` 字符串的结构化信封。相同数据支撑 `/gsd-health --context`。
`validate context` 输出包含 `utilization`、`status`(在 60% / 70% 阈值处分别为 `ok` / `warn` / `critical`)以及 `suggestion` 字符串的结构化信封。相同数据支撑 `/msd-health --context`。
传入 `--json` 可直接接收类型化中间表示(适用于脚本和测试断言)。
---
@@ -236,10 +236,10 @@ node gsd-tools.cjs validate context --json
```bash
# 根据粒度选择摘要模板
node gsd-tools.cjs template select <type>
node msd-tools.cjs template select <type>
# 用变量填充模板
node gsd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']
node msd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']
```
`fill` 的模板类型:`summary`、`plan`、`verification`
@@ -252,16 +252,16 @@ node gsd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--t
```bash
# 以 JSON 格式提取 frontmatter
node gsd-tools.cjs frontmatter get <file> [--field key]
node msd-tools.cjs frontmatter get <file> [--field key]
# 更新单个字段
node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal
node msd-tools.cjs frontmatter set <file> --field key --value jsonVal
# 将 JSON 合并到 frontmatter
node gsd-tools.cjs frontmatter merge <file> --data '{json}'
node msd-tools.cjs frontmatter merge <file> --data '{json}'
# 验证必填字段
node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verification
node msd-tools.cjs frontmatter validate <file> --schema plan|summary|verification
```
---
@@ -272,48 +272,48 @@ node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verificatio
```bash
# 创建 CONTEXT.md 模板
node gsd-tools.cjs scaffold context --phase N
node msd-tools.cjs scaffold context --phase N
# 创建 UAT.md 模板
node gsd-tools.cjs scaffold uat --phase N
node msd-tools.cjs scaffold uat --phase N
# 创建 VERIFICATION.md 模板
node gsd-tools.cjs scaffold verification --phase N
node msd-tools.cjs scaffold verification --phase N
# 创建阶段目录
node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"
node msd-tools.cjs scaffold phase-dir --phase N --name "phase name"
```
---
## Init 命令(复合上下文加载)
通过单次调用加载特定工作流所需的所有上下文。返回包含项目信息、配置、状态和工作流专属数据的 JSON。`init onboard [--fast] [--text]` 会为 `/gsd-onboard` 返回 brownfield 信号、planning 文档候选、代码库映射完整性、fast 映射就绪状态、文本模式路由、部分 planning 状态和 onboarding summary 状态。
通过单次调用加载特定工作流所需的所有上下文。返回包含项目信息、配置、状态和工作流专属数据的 JSON。`init onboard [--fast] [--text]` 会为 `/msd-onboard` 返回 brownfield 信号、planning 文档候选、代码库映射完整性、fast 映射就绪状态、文本模式路由、部分 planning 状态和 onboarding summary 状态。
```bash
node gsd-tools.cjs init execute-phase <phase>
node gsd-tools.cjs init plan-phase <phase>
node gsd-tools.cjs init new-project
node gsd-tools.cjs init new-milestone
node gsd-tools.cjs init onboard [--fast] [--text]
node gsd-tools.cjs init quick <description>
node gsd-tools.cjs init resume
node gsd-tools.cjs init verify-work <phase>
node gsd-tools.cjs init phase-op <phase>
node gsd-tools.cjs init todos [area]
node gsd-tools.cjs init milestone-op
node gsd-tools.cjs init map-codebase
node gsd-tools.cjs init progress
node msd-tools.cjs init execute-phase <phase>
node msd-tools.cjs init plan-phase <phase>
node msd-tools.cjs init new-project
node msd-tools.cjs init new-milestone
node msd-tools.cjs init onboard [--fast] [--text]
node msd-tools.cjs init quick <description>
node msd-tools.cjs init resume
node msd-tools.cjs init verify-work <phase>
node msd-tools.cjs init phase-op <phase>
node msd-tools.cjs init todos [area]
node msd-tools.cjs init milestone-op
node msd-tools.cjs init map-codebase
node msd-tools.cjs init progress
# 工作流范围的 init(`--ws` 标志)
node gsd-tools.cjs init execute-phase <phase> --ws <name>
node gsd-tools.cjs init plan-phase <phase> --ws <name>
node msd-tools.cjs init execute-phase <phase> --ws <name>
node msd-tools.cjs init plan-phase <phase> --ws <name>
```
**大载荷处理:** 当输出超过约 50KB 时,CLI 会将内容写入临时文件并返回 `@file:/tmp/gsd-init-XXXXX.json`。工作流检查 `@file:` 前缀并从磁盘读取:
**大载荷处理:** 当输出超过约 50KB 时,CLI 会将内容写入临时文件并返回 `@file:/tmp/msd-init-XXXXX.json`。工作流检查 `@file:` 前缀并从磁盘读取:
```bash
INIT=$(node gsd-tools.cjs init execute-phase "1")
INIT=$(node msd-tools.cjs init execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```
@@ -323,10 +323,10 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```bash
# 归档里程碑
node gsd-tools.cjs milestone complete <version> (--confirm | --dry-run) [--name <name>] [--no-archive-phases] [--force] [--archive-quick]
node msd-tools.cjs milestone complete <version> (--confirm | --dry-run) [--name <name>] [--no-archive-phases] [--force] [--archive-quick]
# 将需求标记为完成
node gsd-tools.cjs requirements mark-complete <ids>
node msd-tools.cjs requirements mark-complete <ids>
# 接受格式:REQ-01,REQ-02 或 REQ-01 REQ-02 或 [REQ-01, REQ-02]
```
@@ -338,10 +338,10 @@ node gsd-tools.cjs requirements mark-complete <ids>
```bash
# 输出原始 XML 技能块(默认——适合 shell 展开)
node gsd-tools.cjs agent-skills <agent-type>
node msd-tools.cjs agent-skills <agent-type>
# 输出类型化 JSON 接口(#455)——{ agent_type, block, skills_count }
node gsd-tools.cjs agent-skills <agent-type> --json
node msd-tools.cjs agent-skills <agent-type> --json
```
`--json` 标志返回适合结构化消费和测试断言的类型化中间表示对象,而默认(无标志)保留工作流 shell 展开所依赖的原始 XML 输出。
@@ -354,13 +354,13 @@ node gsd-tools.cjs agent-skills <agent-type> --json
```bash
# 生成技能清单(写入 .claude/skill-manifest.json)
node gsd-tools.cjs skill-manifest
node msd-tools.cjs skill-manifest
# 生成并指定自定义输出路径
node gsd-tools.cjs skill-manifest --output <path>
node msd-tools.cjs skill-manifest --output <path>
```
返回所有可用 GSD 技能的 JSON 映射,包含其元数据(名称、描述、文件路径、参数提示)。由安装程序和会话启动钩子使用,以避免重复的文件系统扫描。
返回所有可用 MSD 技能的 JSON 映射,包含其元数据(名称、描述、文件路径、参数提示)。由安装程序和会话启动钩子使用,以避免重复的文件系统扫描。
---
@@ -368,54 +368,54 @@ node gsd-tools.cjs skill-manifest --output <path>
```bash
# 将文本转换为 URL 安全的 slug
node gsd-tools.cjs generate-slug "Some Text Here"
node msd-tools.cjs generate-slug "Some Text Here"
# → some-text-here
# 获取时间戳
node gsd-tools.cjs current-timestamp [full|date|filename]
node msd-tools.cjs current-timestamp [full|date|filename]
# 统计并列出待办事项
node gsd-tools.cjs list-todos [area]
node msd-tools.cjs list-todos [area]
# 检查文件/目录是否存在
node gsd-tools.cjs verify-path-exists <path>
node msd-tools.cjs verify-path-exists <path>
# 聚合所有 SUMMARY.md 数据
node gsd-tools.cjs history-digest
node msd-tools.cjs history-digest
# 从 SUMMARY.md 提取结构化数据
node gsd-tools.cjs summary-extract <path> [--fields field1,field2]
node msd-tools.cjs summary-extract <path> [--fields field1,field2]
# 项目统计
node gsd-tools.cjs stats [json|table]
node msd-tools.cjs stats [json|table]
# 进度渲染(人类可读)
node gsd-tools.cjs progress [json|table|bar]
node msd-tools.cjs progress [json|table|bar]
# 以类型化 JSON 接口输出进度(#455)
node gsd-tools.cjs progress --json
node msd-tools.cjs progress --json
# 完成待办事项
node gsd-tools.cjs todo complete <filename> [--dry-run]
node msd-tools.cjs todo complete <filename> [--dry-run]
# UAT 审计——扫描所有阶段的未解决事项
node gsd-tools.cjs audit-uat
node msd-tools.cjs audit-uat
# 跨制品审计队列——扫描 `.planning/` 中未解决的审计事项
node gsd-tools.cjs audit-open [--json]
node msd-tools.cjs audit-open [--json]
# 将 GSD-2 项目反向迁移到当前结构(支撑 `/gsd-import --from-gsd2`)
node gsd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
# 将 GSD-2 项目反向迁移到当前结构(支撑 `/msd-import --from-gsd2`)
node msd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
# 带配置检查的 Git 提交
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify] [--respect-staged]
node msd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify] [--respect-staged]
```
> `--no-verify`:跳过预提交钩子。由并行执行器代理在基于波次的执行过程中使用,以避免构建锁争用(例如 Rust 项目中的 cargo lock 冲突)。编排器在每个波次完成后运行一次钩子。顺序执行时不要使用 `--no-verify`——让钩子正常运行。
> `--files <paths>` **暂存行为**:默认情况下,`--files` 在提交前对每个命名文件运行 `git add -- <path>`。这会覆盖通过 `git add -p` 设置的任何按块暂存。传入 `--respect-staged` 可跳过 `git add` 步骤,仅提交已在索引中且在请求路径规格内的内容。如果该范围内没有已暂存的内容,命令将返回 `{ committed: false, reason: 'nothing staged' }` 而不报错。两种模式下提交都会附加 `-- <paths>` 路径规格,因此 `--files` 范围之外已暂存的文件永远不会被包含(#3061 不变量)。
# 网页搜索(需要 Brave API 密钥)
node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
node msd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
```
---
@@ -426,22 +426,22 @@ node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
```bash
# 构建或重建知识图谱
node gsd-tools.cjs graphify build
node msd-tools.cjs graphify build
# 在图谱中搜索某个词
node gsd-tools.cjs graphify query <term>
node msd-tools.cjs graphify query <term>
# 显示图谱新鲜度和统计数据
node gsd-tools.cjs graphify status
node msd-tools.cjs graphify status
# 显示自上次构建以来的变更
node gsd-tools.cjs graphify diff
node msd-tools.cjs graphify diff
# 写入当前图谱的命名快照
node gsd-tools.cjs graphify snapshot [name]
node msd-tools.cjs graphify snapshot [name]
```
用户入口:`/gsd-graphify`(参见[命令参考](COMMANDS.md#gsd-graphify))。
用户入口:`/msd-graphify`(参见[命令参考](COMMANDS.md#msd-graphify))。
---
@@ -465,30 +465,30 @@ node gsd-tools.cjs graphify snapshot [name]
| UAT | `lib/uat.cjs` | 跨阶段 UAT/验证审计 |
| 配置文件输出 | `lib/profile-output.cjs` | 开发者配置文件格式化 |
| 配置文件流水线 | `lib/profile-pipeline.cjs` | 会话分析流水线 |
| Graphify | `lib/graphify.cjs` | 知识图谱构建/查询/状态/差异/快照(支撑 `/gsd-graphify`) |
| 学习记录 | `lib/learnings.cjs` | 从阶段/SUMMARY 制品中提取学习记录(支撑 `/gsd-extract-learnings`) |
| Graphify | `lib/graphify.cjs` | 知识图谱构建/查询/状态/差异/快照(支撑 `/msd-graphify`) |
| 学习记录 | `lib/learnings.cjs` | 从阶段/SUMMARY 制品中提取学习记录(支撑 `/msd-extract-learnings`) |
| 审计 | `lib/audit.cjs` | 阶段/里程碑审计队列处理器;`audit-open` 助手 |
| GSD2 导入 | `lib/gsd2-import.cjs` | 从 GSD-2 项目反向迁移导入(支撑 `/gsd-import --from-gsd2`) |
| Intel | `lib/intel.cjs` | 可查询的代码库智能索引(支撑 `/gsd-map-codebase --query`) |
| MSD2 导入 | `lib/gsd2-import.cjs` | 从 GSD-2 项目反向迁移导入(支撑 `/msd-import --from-gsd2`) |
| Intel | `lib/intel.cjs` | 可查询的代码库智能索引(支撑 `/msd-map-codebase --query`) |
---
## 审阅器 CLI 路由
`review.models.<cli>` 将审阅器类型映射到代码审查工作流调用的 shell 命令。通过 [`/gsd-config --integrations`](COMMANDS.md#gsd-config) 或直接设置:
`review.models.<cli>` 将审阅器类型映射到代码审查工作流调用的 shell 命令。通过 [`/msd-config --integrations`](COMMANDS.md#msd-config) 或直接设置:
```bash
node gsd-tools.cjs config-set review.models.codex "codex exec --model gpt-5"
node gsd-tools.cjs config-set review.models.agy "gemini-3.1-pro-preview"
node gsd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
node gsd-tools.cjs config-set review.models.claude "" # 清除——回退到会话模型
node msd-tools.cjs config-set review.models.codex "codex exec --model gpt-5"
node msd-tools.cjs config-set review.models.agy "gemini-3.1-pro-preview"
node msd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
node msd-tools.cjs config-set review.models.claude "" # 清除——回退到会话模型
```
Slug 将针对 `[a-zA-Z0-9_-]+` 进行验证;空或包含路径的 slug 将被拒绝。完整字段参考请参见 [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing)。
## 密钥处理
通过 `/gsd-settings` 配置的 API 密钥(`brave_search`、`firecrawl`、`exa_search`)以明文形式写入 `.planning/config.json`,但在所有 `config-set` / `config-get` 输出、确认表格和交互式提示中均会被遮蔽(`****<last-4>`)。遮蔽实现请参见 `gsd-core/bin/lib/secrets.cjs`。`config.json` 文件本身是安全边界——请通过文件系统权限保护它,并将其排除在 git 之外(`.planning/` 默认已被 gitignore)。
通过 `/msd-settings` 配置的 API 密钥(`brave_search`、`firecrawl`、`exa_search`)以明文形式写入 `.planning/config.json`,但在所有 `config-set` / `config-get` 输出、确认表格和交互式提示中均会被遮蔽(`****<last-4>`)。遮蔽实现请参见 `msd-core/bin/lib/secrets.cjs`。`config.json` 文件本身是安全边界——请通过文件系统权限保护它,并将其排除在 git 之外(`.planning/` 默认已被 gitignore)。
---

File diff suppressed because it is too large Load Diff

View File

@@ -1,4 +1,4 @@
# GSD 配置参考
# MSD 配置参考
`.planning/config.json` 的完整 schema 参考。有关设置向导和任务操作指南,请参阅[文档索引](README.md)。
@@ -8,7 +8,7 @@
## 配置文件
GSD 将项目设置存储在 `.planning/config.json` 中。该文件在 `/gsd-new-project` 时创建,通过 `/gsd-settings` 更新。
MSD 将项目设置存储在 `.planning/config.json` 中。该文件在 `/msd-new-project` 时创建,通过 `/msd-settings` 更新。
### 完整 Schema
@@ -99,8 +99,8 @@ GSD 将项目设置存储在 `.planning/config.json` 中。该文件在 `/gsd-ne
"git": {
"branching_strategy": "none",
"create_tag": true,
"phase_branch_template": "gsd/phase-{phase}-{slug}",
"milestone_branch_template": "gsd/{milestone}-{slug}",
"phase_branch_template": "msd/phase-{phase}-{slug}",
"milestone_branch_template": "msd/{milestone}-{slug}",
"quick_branch_template": null
},
"gates": {
@@ -146,7 +146,7 @@ GSD 将项目设置存储在 `.planning/config.json` 中。该文件在 `/gsd-ne
| `runtime` | string | `claude`, `codex` 或任意字符串 | (无) | [运行时感知配置文件解析](#运行时感知配置文件-2517)的活跃运行时。设置后,配置文件层级(opus/sonnet/haiku)解析为运行时原生模型 ID。目前仅 Codex 安装路径通过此解析器为每个 agent 生成模型 ID;其他运行时(`opencode`、`gemini`、`qwen`、`copilot` 等)在 spawn 时消费该解析器,并在 [#2612](https://github.com/open-gsd/gsd-core/issues/2612) 中获得专用安装路径支持。未设置时(默认),行为与之前版本相同。v1.39 新增 |
| `model_profile_overrides.<runtime>.<tier>` | string \| object | 按运行时的层级覆盖 | (无) | 覆盖特定 `(runtime, tier)` 的运行时感知层级映射。层级为 `opus`、`sonnet`、`haiku` 之一。值为模型 ID 字符串(如 `"gpt-5-pro"`)或 `{ model, reasoning_effort }`。参见[运行时感知配置文件](#运行时感知配置文件-2517)。v1.39 新增 |
| `model_policy.provider` | string | `openai`, `anthropic`, `anthropic-fable`, `google`, `qwen`, `generic` | (无) | 声明模型提供商。已知提供商(`openai`、`anthropic`、`anthropic-fable`、`google`、`qwen`)启用基于目录的预设。`generic` 将所有模型 ID 视为不透明字符串——无前缀推断,无推理努力默认值。`model_policy.runtime_tiers` 在旧版 `model_profile_overrides` 之前解析。参见[模型策略预设](#模型策略预设-model_policy--v142-新增)。v1.42 新增([#49](https://github.com/open-gsd/gsd-core/issues/49)) |
| `model_policy.budget` | enum | `high`, `medium`, `low` | (无) | 使用已知提供商时选择预算层级。GSD 在解析时将匹配的目录预设具体化为显式层级映射。当 `provider` 为 `generic` 或 `custom` 时忽略。v1.42 新增([#49](https://github.com/open-gsd/gsd-core/issues/49)) |
| `model_policy.budget` | enum | `high`, `medium`, `low` | (无) | 使用已知提供商时选择预算层级。MSD 在解析时将匹配的目录预设具体化为显式层级映射。当 `provider` 为 `generic` 或 `custom` 时忽略。v1.42 新增([#49](https://github.com/open-gsd/gsd-core/issues/49)) |
| `model_policy.high` | string | 模型 ID | (无) | `generic`/`custom` 提供商的高成本层级模型 ID。当 `provider: "generic"` 或 `"custom"` 时使用。v1.42 新增([#49](https://github.com/open-gsd/gsd-core/issues/49)) |
| `model_policy.medium` | string | 模型 ID | (无) | `generic`/`custom` 提供商的中等成本层级模型 ID。v1.42 新增([#49](https://github.com/open-gsd/gsd-core/issues/49)) |
| `model_policy.low` | string | 模型 ID | (无) | `generic`/`custom` 提供商的低成本层级模型 ID。v1.42 新增([#49](https://github.com/open-gsd/gsd-core/issues/49)) |
@@ -157,17 +157,17 @@ GSD 将项目设置存储在 `.planning/config.json` 中。该文件在 `/gsd-ne
| `dynamic_routing.escalate_on_failure` | boolean | `true`, `false` | `true` | 为 `false` 时,即使 `enabled: true` 也禁用升级——每次尝试使用默认层级。v1.40 新增 |
| `dynamic_routing.max_escalations` | integer | `0`, `1`, `2`, … | `1` | 每次 agent 调用的硬性重试上限。超过上限后,解析器返回上限层级的模型。v1.40 新增 |
| `project_code` | string | 任意短字符串 | (无) | 阶段目录名称的前缀(如 `"ABC"` 生成 `ABC-01-setup/`)。v1.31 新增 |
| `phase_id_convention` | enum | `"milestone-prefixed"`, `null` | `null` | 阶段 ID 命名规范。`null` = 旧版数字 ID(`Phase 1`、`Phase 2`)。`"milestone-prefixed"` = 编码所属里程碑的全局唯一 ID(`Phase 1-01`、`Phase 1-02`)。运行 `gsd-tools roadmap upgrade --convention milestone-prefixed` 迁移现有 ROADMAP.md。 |
| `phase_id_convention` | enum | `"milestone-prefixed"`, `null` | `null` | 阶段 ID 命名规范。`null` = 旧版数字 ID(`Phase 1`、`Phase 2`)。`"milestone-prefixed"` = 编码所属里程碑的全局唯一 ID(`Phase 1-01`、`Phase 1-02`)。运行 `msd-tools roadmap upgrade --convention milestone-prefixed` 迁移现有 ROADMAP.md。 |
| `response_language` | string | 语言代码 | (无) | agent 响应语言(如 `"pt"`、`"ko"`、`"ja"`)。传播至所有派生 agent,实现跨阶段语言一致性。v1.32 新增 |
| `context_window` | number | 任意整数 | `200000` | 上下文窗口大小(token 数)。对于 1M 上下文模型(如 `claude-fable-5`),设置为 `1000000`。`>= 500000` 的值启用自适应上下文增强(完整读取之前的 SUMMARY.md,更深入的反模式读取)。通过 `/gsd-config --advanced` 配置。 |
| `context_window` | number | 任意整数 | `200000` | 上下文窗口大小(token 数)。对于 1M 上下文模型(如 `claude-fable-5`),设置为 `1000000`。`>= 500000` 的值启用自适应上下文增强(完整读取之前的 SUMMARY.md,更深入的反模式读取)。通过 `/msd-config --advanced` 配置。 |
| `context_profile` | string | `dev`, `research`, `review` | (无) | 执行上下文预设,为当前工作类型应用预配置的模式、模型和工作流设置包。v1.34 新增 |
| `claude_md_path` | string | 任意文件路径 | `./CLAUDE.md` | 生成的 CLAUDE.md 文件的自定义输出路径。适用于需要将 CLAUDE.md 放在非根目录位置的 monorepo 或项目。默认为项目根目录下的 `./CLAUDE.md`。v1.36 新增 |
| `claude_md_assembly.mode` | enum | `embed`, `link` | `embed` | 控制如何将受管理的节写入 CLAUDE.md。`embed`(默认)在 GSD 标记之间内联内容。`link` 改为写入 `@.planning/<source-path>`——Claude Code 在运行时展开引用,在典型项目中将 CLAUDE.md 大小减少约 65%。`link` 仅适用于有真实源文件的节;`workflow` 和回退节始终嵌入。按块覆盖:`claude_md_assembly.blocks.<section>`(如 `claude_md_assembly.blocks.architecture: link`)。v1.38 新增 |
| `claude_md_assembly.mode` | enum | `embed`, `link` | `embed` | 控制如何将受管理的节写入 CLAUDE.md。`embed`(默认)在 MSD 标记之间内联内容。`link` 改为写入 `@.planning/<source-path>`——Claude Code 在运行时展开引用,在典型项目中将 CLAUDE.md 大小减少约 65%。`link` 仅适用于有真实源文件的节;`workflow` 和回退节始终嵌入。按块覆盖:`claude_md_assembly.blocks.<section>`(如 `claude_md_assembly.blocks.architecture: link`)。v1.38 新增 |
| `context` | string | 任意文本 | (无) | 注入到项目所有 agent 提示词中的自定义上下文字符串。用于提供每个 agent 都应了解的持久性项目特定指导(如编码规范、团队实践) |
| `phase_naming` | string | 任意字符串 | (无) | 阶段目录名称的自定义前缀。设置后,覆盖自动生成的阶段 slug(如 `"feature"` 生成 `feature-01-setup/` 而非路线图派生的 slug) |
| `brave_search` | boolean | `true`/`false` | 自动检测 | 覆盖 Brave Search API 可用性的自动检测。未设置时,GSD 检查 `BRAVE_API_KEY` 环境变量或 `~/.gsd/brave_api_key` 文件 |
| `firecrawl` | boolean | `true`/`false` | 自动检测 | 覆盖 Firecrawl API 可用性的自动检测。未设置时,GSD 检查 `FIRECRAWL_API_KEY` 环境变量或 `~/.gsd/firecrawl_api_key` 文件 |
| `exa_search` | boolean | `true`/`false` | 自动检测 | 覆盖 Exa Search API 可用性的自动检测。未设置时,GSD 检查 `EXA_API_KEY` 环境变量或 `~/.gsd/exa_api_key` 文件 |
| `brave_search` | boolean | `true`/`false` | 自动检测 | 覆盖 Brave Search API 可用性的自动检测。未设置时,MSD 检查 `BRAVE_API_KEY` 环境变量或 `~/.msd/brave_api_key` 文件 |
| `firecrawl` | boolean | `true`/`false` | 自动检测 | 覆盖 Firecrawl API 可用性的自动检测。未设置时,MSD 检查 `FIRECRAWL_API_KEY` 环境变量或 `~/.msd/firecrawl_api_key` 文件 |
| `exa_search` | boolean | `true`/`false` | 自动检测 | 覆盖 Exa Search API 可用性的自动检测。未设置时,MSD 检查 `EXA_API_KEY` 环境变量或 `~/.msd/exa_api_key` 文件 |
| `search_gitignored` | boolean | `true`/`false` | `false` | `planning.search_gitignored` 的旧版顶层别名。优先使用命名空间形式;此别名为向后兼容而保留 |
> **注意:** `granularity` 在 v1.22.3 中从 `depth` 重命名而来。现有配置会自动迁移。
@@ -176,11 +176,11 @@ GSD 将项目设置存储在 `.planning/config.json` 中。该文件在 `/gsd-ne
## 集成设置
通过 [`/gsd-config --integrations`](COMMANDS.md#gsd-config) 交互式配置。这些是*连接*设置——API 密钥和跨工具路由——特意与 `/gsd-settings`(工作流开关)分开。
通过 [`/msd-config --integrations`](COMMANDS.md#msd-config) 交互式配置。这些是*连接*设置——API 密钥和跨工具路由——特意与 `/msd-settings`(工作流开关)分开。
### 搜索 API 密钥
API 密钥字段接受字符串值(密钥本身)。也可以设置为哨兵值 `true`/`false`/`null` 来覆盖来自环境变量 / `~/.gsd/*_api_key` 文件的自动检测(旧版行为,参见上方各行)。
API 密钥字段接受字符串值(密钥本身)。也可以设置为哨兵值 `true`/`false`/`null` 来覆盖来自环境变量 / `~/.msd/*_api_key` 文件的自动检测(旧版行为,参见上方各行)。
| 设置 | 类型 | 默认值 | 描述 |
|---------|------|---------|-------------|
@@ -188,7 +188,7 @@ API 密钥字段接受字符串值(密钥本身)。也可以设置为哨兵
| `firecrawl` | string \| boolean \| null | `null` | 用于深度抓取的 Firecrawl API 密钥。显示时已脱敏 |
| `exa_search` | string \| boolean \| null | `null` | 用于语义搜索的 Exa Search API 密钥。显示时已脱敏 |
**脱敏规范(`gsd-core/bin/lib/secrets.cjs`):** 8 个字符及以上的密钥显示为 `****<末4位>`;较短的密钥显示为 `****`;`null`/空值显示为 `(unset)`。明文原样写入 `.planning/config.json`——该文件是安全边界——但 CLI、确认表格、日志和 `AskUserQuestion` 描述中不显示明文。这也适用于 `config-set` 命令本身的输出:`config-set brave_search <key>` 返回带脱敏值的 JSON 负载。
**脱敏规范(`msd-core/bin/lib/secrets.cjs`):** 8 个字符及以上的密钥显示为 `****<末4位>`;较短的密钥显示为 `****`;`null`/空值显示为 `(unset)`。明文原样写入 `.planning/config.json`——该文件是安全边界——但 CLI、确认表格、日志和 `AskUserQuestion` 描述中不显示明文。这也适用于 `config-set` 命令本身的输出:`config-set brave_search <key>` 返回带脱敏值的 JSON 负载。
### 代码审查 CLI 路由
@@ -202,13 +202,13 @@ API 密钥字段接受字符串值(密钥本身)。也可以设置为哨兵
`<cli>` slug 需通过 `[a-zA-Z0-9_-]+` 验证。空值或包含路径的 slug 会被 `config-set` 拒绝。
### `/gsd-review` 的默认审查器
### `/msd-review` 的默认审查器
使用 `review.default_reviewers` 将无标志的 `/gsd-review` 运行限定为已检测审查器的子集。
使用 `review.default_reviewers` 将无标志的 `/msd-review` 运行限定为已检测审查器的子集。
| 设置 | 类型 | 默认值 | 描述 |
|---------|------|---------|-------------|
| `review.default_reviewers` | string[] \| null | `null`(所有已检测审查器) | 无标志 `/gsd-review` 的可选默认子集,如 `["codex","claude"]`。优先级顺序:显式审查器标志 > `--all` > `review.default_reviewers` > 所有已检测。未知 slug 以警告忽略;已知但未检测到的 slug 以信息提示忽略;空数组会被 `config-set` 拒绝。 |
| `review.default_reviewers` | string[] \| null | `null`(所有已检测审查器) | 无标志 `/msd-review` 的可选默认子集,如 `["codex","claude"]`。优先级顺序:显式审查器标志 > `--all` > `review.default_reviewers` > 所有已检测。未知 slug 以警告忽略;已知但未检测到的 slug 以信息提示忽略;空数组会被 `config-set` 拒绝。 |
示例:
@@ -222,7 +222,7 @@ API 密钥字段接受字符串值(密钥本身)。也可以设置为哨兵
### Agent 技能注入(动态)
`agent_skills.<agent-type>` 扩展下方记录的 `agent_skills` 映射。slug 需通过 `[a-zA-Z0-9_-]+` 验证——无路径分隔符、无空格、无 shell 元字符。通过 `/gsd-config --integrations` 交互式配置。
`agent_skills.<agent-type>` 扩展下方记录的 `agent_skills` 映射。slug 需通过 `[a-zA-Z0-9_-]+` 验证——无路径分隔符、无空格、无 shell 元字符。通过 `/msd-config --integrations` 交互式配置。
---
@@ -238,61 +238,61 @@ API 密钥字段接受字符串值(密钥本身)。也可以设置为哨兵
| `workflow.auto_advance` | boolean | `false` | 自动串联 discuss → plan → execute,无需停顿 |
| `workflow.nyquist_validation` | boolean | `true` | 计划阶段研究期间的测试覆盖率映射 |
| `workflow.ui_phase` | boolean | `true` | 为前端阶段生成 UI 设计契约 |
| `workflow.ui_safety_gate` | boolean | `true` | 在计划阶段期间,提示为前端阶段运行 /gsd-ui-phase |
| `workflow.ui_review` | boolean | `true` | 在自主模式下阶段执行后运行视觉质量审计(`/gsd-ui-review`)。为 `false` 时跳过 UI 审计步骤。 |
| `workflow.ui_safety_gate` | boolean | `true` | 在计划阶段期间,提示为前端阶段运行 /msd-ui-phase |
| `workflow.ui_review` | boolean | `true` | 在自主模式下阶段执行后运行视觉质量审计(`/msd-ui-review`)。为 `false` 时跳过 UI 审计步骤。 |
| `workflow.node_repair` | boolean | `true` | 验证失败时自主任务修复 |
| `workflow.node_repair_budget` | number | `2` | 每个失败任务的最大修复尝试次数 |
| `workflow.research_before_questions` | boolean | `false` | 在讨论问题之前而非之后运行研究 |
| `workflow.discuss_mode` | string | `'discuss'` | 控制 `/gsd-discuss-phase` 如何收集上下文。`'discuss'`(默认)逐一提问。`'assumptions'` 先读取代码库,生成带置信度的结构化假设,只要求纠正错误内容。v1.28 新增 |
| `workflow.discuss_mode` | string | `'discuss'` | 控制 `/msd-discuss-phase` 如何收集上下文。`'discuss'`(默认)逐一提问。`'assumptions'` 先读取代码库,生成带置信度的结构化假设,只要求纠正错误内容。v1.28 新增 |
| `workflow.max_discuss_passes` | number | `3` | 工作流停止提问前讨论阶段的最大轮数。在无头/自动模式下防止无限讨论循环。 |
| `workflow.skip_discuss` | boolean | `false` | 为 `true` 时,`/gsd-autonomous` 完全跳过讨论阶段,从 ROADMAP 阶段目标写入最简 CONTEXT.md。适用于开发者偏好已完整写入 PROJECT.md/REQUIREMENTS.md 的项目。v1.28 新增 |
| `workflow.skip_discuss` | boolean | `false` | 为 `true` 时,`/msd-autonomous` 完全跳过讨论阶段,从 ROADMAP 阶段目标写入最简 CONTEXT.md。适用于开发者偏好已完整写入 PROJECT.md/REQUIREMENTS.md 的项目。v1.28 新增 |
| `workflow.text_mode` | boolean | `false` | 将 AskUserQuestion TUI 菜单替换为纯文本编号列表。在 TUI 菜单无法渲染的 Claude Code 远程会话(`/rc` 模式)中必需。也可通过讨论阶段的 `--text` 标志按会话设置。v1.28 新增 |
| `workflow.use_worktrees` | boolean | `true` | 为 `false` 时,禁用并行执行的 git worktree 隔离。偏好顺序执行或环境不支持 worktree 的用户可以禁用此选项。v1.31 新增 |
| `workflow.worktree_skip_hooks` | boolean | `false` | 为 `true` 时,worktree 模式下的执行器 agent 传递 `--no-verify`(跳过提交前钩子),波次后的钩子验证改为针对合并结果运行。适用于钩子无法在 agent worktree 中运行的项目的可选逃生舱口。默认 `false` 对每次提交运行钩子(#2924)。 |
| `workflow.code_review` | boolean | `true` | 启用 `/gsd-code-review` 和 `/gsd-code-review --fix` 命令。为 `false` 时,命令以配置门禁消息退出。v1.34 新增 |
| `workflow.code_review_depth` | string | `standard` | `/gsd-code-review` 的默认审查深度:`quick`(仅模式匹配)、`standard`(按文件分析)或 `deep`(带导入图的跨文件)。可通过 `--depth=` 按次运行覆盖。v1.34 新增 |
| `workflow.code_review_depth_overrides` | array | `[]` | 有序的 `{ paths: string[], depth }` 规则列表,按目录前缀匹配对特定目录提升 `/gsd-code-review` 的审查深度,例如 `[{ "paths": ["src/auth"], "depth": "deep" }]`。每条规则的 `paths` 按整段目录路径前缀与本次审查的变更文件集合匹配(`src/auth` 匹配 `src/auth/token.ts`,但绝不匹配 `src/authfoo/x.ts` 或 `docs/src/auth/x.ts`);匹配区分大小写,与 git 一致。glob 语法(`*`、`?`)是配置错误,而非前缀的简写形式。一个匹配的文件会将整次审查提升到该深度——深度并非逐文件应用。解析顺序:`--depth=` 标志 → 匹配到的最强规则 → `workflow.code_review_depth` → `standard`;即使规则的档位比全局默认值弱,匹配到的规则依然生效。格式错误的规则(`depth` 无效、glob 语法、绝对路径、`..` 段、路径为空、`overrides` 非数组、规则非对象、`paths` 格式错误)是配置错误,审查会中止,而不会静默回退。解析出的深度及匹配的规则会打印在审查输出中。#2554 新增 |
| `workflow.code_review` | boolean | `true` | 启用 `/msd-code-review` 和 `/msd-code-review --fix` 命令。为 `false` 时,命令以配置门禁消息退出。v1.34 新增 |
| `workflow.code_review_depth` | string | `standard` | `/msd-code-review` 的默认审查深度:`quick`(仅模式匹配)、`standard`(按文件分析)或 `deep`(带导入图的跨文件)。可通过 `--depth=` 按次运行覆盖。v1.34 新增 |
| `workflow.code_review_depth_overrides` | array | `[]` | 有序的 `{ paths: string[], depth }` 规则列表,按目录前缀匹配对特定目录提升 `/msd-code-review` 的审查深度,例如 `[{ "paths": ["src/auth"], "depth": "deep" }]`。每条规则的 `paths` 按整段目录路径前缀与本次审查的变更文件集合匹配(`src/auth` 匹配 `src/auth/token.ts`,但绝不匹配 `src/authfoo/x.ts` 或 `docs/src/auth/x.ts`);匹配区分大小写,与 git 一致。glob 语法(`*`、`?`)是配置错误,而非前缀的简写形式。一个匹配的文件会将整次审查提升到该深度——深度并非逐文件应用。解析顺序:`--depth=` 标志 → 匹配到的最强规则 → `workflow.code_review_depth` → `standard`;即使规则的档位比全局默认值弱,匹配到的规则依然生效。格式错误的规则(`depth` 无效、glob 语法、绝对路径、`..` 段、路径为空、`overrides` 非数组、规则非对象、`paths` 格式错误)是配置错误,审查会中止,而不会静默回退。解析出的深度及匹配的规则会打印在审查输出中。#2554 新增 |
| `workflow.plan_bounce` | boolean | `false` | 针对生成的计划运行外部验证脚本。启用后,计划阶段编排器将每个 PLAN.md 通过 `plan_bounce_script` 指定的脚本管道处理,并在非零退出时阻塞。v1.36 新增 |
| `workflow.plan_bounce_script` | string | (无) | 用于计划反弹验证的外部脚本路径。接收 PLAN.md 路径作为第一个参数。当 `plan_bounce` 为 `true` 时必需。v1.36 新增 |
| `workflow.plan_bounce_passes` | number | `2` | 顺序执行的反弹轮数。每轮将上一轮的输出反馈给验证器。较高的值提升严格性,但会增加延迟。v1.36 新增 |
| `workflow.post_planning_gaps` | boolean | `true` | 统一的规划后差距报告(#2493)。所有计划生成并提交后,扫描 REQUIREMENTS.md 和 CONTEXT.md 的 `<decisions>` 与阶段目录中的每个 PLAN.md,然后打印一个 `Source \| Item \| Status` 表格。单词边界匹配(REQ-1 vs REQ-10)和自然排序(REQ-02 在 REQ-10 之前)。非阻塞——仅为信息性报告。设为 `false` 跳过计划阶段的步骤 13e。 |
| `workflow.plan_review_convergence` | boolean | `false` | 启用 `/gsd-plan-review-convergence` 命令。默认禁用——此键为 `false` 时命令以启用说明退出。该命令自动化手动计划→审查→重新规划循环:派生已配置的审查器(Codex、Claude、OpenCode、Ollama、LM Studio、llama.cpp),通过 CYCLE_SUMMARY 契约计算未解决的 HIGH 问题,用 `--reviews` 反馈重新规划,并重复直至收敛或达到最大循环次数。通过 `gsd config-set workflow.plan_review_convergence true` 启用。v1.39 新增 |
| `workflow.plan_chunked` | boolean | `false` | 启用分块规划模式。为 `true`(或向 `/gsd-plan-phase` 传递 `--chunked` 标志)时,编排器将单个长期规划器任务拆分为一个简短的轮廓任务,后跟 N 个简短的按计划任务(每个约 3-5 分钟)。每个计划单独提交以具备崩溃韧性。如果任务挂起且终端被强制终止,使用 `--chunked` 重新运行将从最后完成的计划处恢复。在长期任务可能在 stdio 上挂起的 Windows 上特别有用。v1.38 新增 |
| `workflow.code_review_command` | string | (无) | `/gsd-ship` 中外部代码审查集成的 shell 命令。通过 stdin 接收更改的文件路径。非零退出阻塞发布工作流。v1.36 新增 |
| `workflow.plan_review_convergence` | boolean | `false` | 启用 `/msd-plan-review-convergence` 命令。默认禁用——此键为 `false` 时命令以启用说明退出。该命令自动化手动计划→审查→重新规划循环:派生已配置的审查器(Codex、Claude、OpenCode、Ollama、LM Studio、llama.cpp),通过 CYCLE_SUMMARY 契约计算未解决的 HIGH 问题,用 `--reviews` 反馈重新规划,并重复直至收敛或达到最大循环次数。通过 `msd config-set workflow.plan_review_convergence true` 启用。v1.39 新增 |
| `workflow.plan_chunked` | boolean | `false` | 启用分块规划模式。为 `true`(或向 `/msd-plan-phase` 传递 `--chunked` 标志)时,编排器将单个长期规划器任务拆分为一个简短的轮廓任务,后跟 N 个简短的按计划任务(每个约 3-5 分钟)。每个计划单独提交以具备崩溃韧性。如果任务挂起且终端被强制终止,使用 `--chunked` 重新运行将从最后完成的计划处恢复。在长期任务可能在 stdio 上挂起的 Windows 上特别有用。v1.38 新增 |
| `workflow.code_review_command` | string | (无) | `/msd-ship` 中外部代码审查集成的 shell 命令。通过 stdin 接收更改的文件路径。非零退出阻塞发布工作流。v1.36 新增 |
| `workflow.tdd_mode` | boolean | `false` | 将 TDD 流水线作为一等执行模式启用。为 `true` 时,规划器积极地将 `type: tdd` 应用于符合条件的任务(业务逻辑、API、验证、算法),执行器强制执行 RED/GREEN/REFACTOR 门禁序列。阶段结束时的协作审查检查点验证门禁合规性。v1.36 新增 |
| `workflow.human_verify_mode` | string | `'end-of-phase'` | 控制人工验证检查点。`'end-of-phase'`(自 #3309 起为默认值)抑制 `checkpoint:human-verify` 任务,并将检查嵌入 `<verify><human-check>` 块以供阶段结束审查。`'mid-flight'` 恢复阻塞式检查点任务。`checkpoint:decision` 和 `checkpoint:human-action` 不受影响。参见[检查点参考](../../gsd-core/references/checkpoints.md#checkpoint_types)。 |
| `workflow.human_verify_mode` | string | `'end-of-phase'` | 控制人工验证检查点。`'end-of-phase'`(自 #3309 起为默认值)抑制 `checkpoint:human-verify` 任务,并将检查嵌入 `<verify><human-check>` 块以供阶段结束审查。`'mid-flight'` 恢复阻塞式检查点任务。`checkpoint:decision` 和 `checkpoint:human-action` 不受影响。参见[检查点参考](../../msd-core/references/checkpoints.md#checkpoint_types)。 |
| `workflow.cross_ai_execution` | boolean | `false` | 将阶段执行委托给外部 AI CLI,而非派生本地执行器 agent。适用于利用不同模型在特定阶段的优势。v1.36 新增 |
| `workflow.cross_ai_command` | string | (无) | 跨 AI 执行的 shell 命令模板。通过 stdin 接收阶段提示词。必须生成与 SUMMARY.md 兼容的输出。当 `cross_ai_execution` 为 `true` 时必需。v1.36 新增 |
| `workflow.cross_ai_timeout` | number | `300` | 跨 AI 执行命令的超时秒数。防止失控的外部进程。v1.36 新增 |
| `workflow.ai_integration_phase` | boolean | `true` | 启用 `/gsd-ai-integration-phase` 命令。为 `false` 时,命令以配置门禁消息退出 |
| `workflow.ai_integration_phase` | boolean | `true` | 启用 `/msd-ai-integration-phase` 命令。为 `false` 时,命令以配置门禁消息退出 |
| `workflow.auto_prune_state` | boolean | `false` | 为 `true` 时,在阶段边界自动清理 STATE.md 中的过期条目,而非提示确认 |
| `workflow.pattern_mapper` | boolean | `true` | 在研究和规划之间运行 `gsd-pattern-mapper` agent,将新文件映射到现有代码库类似物 |
| `workflow.pattern_mapper` | boolean | `true` | 在研究和规划之间运行 `msd-pattern-mapper` agent,将新文件映射到现有代码库类似物 |
| `workflow.subagent_timeout` | number | `600` | 单个 subagent 调用的超时秒数。对于长时间运行的研究或执行阶段可适当增加 |
| `executor.stall_detect_interval_minutes` | number | `5` | 执行器 agent 活跃时,执行器停滞检测的间隔分钟数。执行阶段编排器以此频率检查最近的提交,避免无限等待静默的 agent。 |
| `executor.stall_threshold_minutes` | number | `10` | 执行器完成或预期分支提交活动缺失超过此分钟数后,执行阶段为可能停滞的执行器提供恢复选项。 |
| `planner.stall_detection_enabled` | boolean | `true` | 控制标准规划器、分块大纲/逐计划规划器、计划检查器和修订规划器的有界停滞检测。运行 `gsd config-set planner.stall_detection_enabled false` 可跳过 watchdog 轮询,改用运行时原生完成机制等待每个 agent。**警告:** `false` 会放弃运行时丢失完成回传时的有界恢复;届时可能需要中断并使用现有文件系统回退。规划器执行和结果处理不会被跳过。 |
| `planner.stall_detection_enabled` | boolean | `true` | 控制标准规划器、分块大纲/逐计划规划器、计划检查器和修订规划器的有界停滞检测。运行 `msd config-set planner.stall_detection_enabled false` 可跳过 watchdog 轮询,改用运行时原生完成机制等待每个 agent。**警告:** `false` 会放弃运行时丢失完成回传时的有界恢复;届时可能需要中断并使用现有文件系统回退。规划器执行和结果处理不会被跳过。 |
| `planner.stall_detect_interval_minutes` | number | `5` | 规划器或计划检查器活跃时的停滞检查间隔分钟数。规划阶段编排器按此频率检查磁盘上的 `*-PLAN.md` 活动(#2650)。 |
| `planner.stall_threshold_minutes` | number | `10` | 没有完成标记或新的磁盘计划活动超过此分钟数后,规划阶段自动提供接受计划/重试/停止恢复选项(#2650)。 |
| `workflow.inline_plan_threshold` | number | `3` | 阶段中任务数量的最大值,超过此值后规划器生成单独的 PLAN.md 文件而非在提示词中内联任务 |
| `workflow.drift_threshold` | number | `3` | 阶段期间引入的新结构元素(新目录、桶形导出、迁移、路由模块)的最小数量,超过此值后执行后代码库漂移门禁采取行动。参见 [#2003](https://github.com/open-gsd/gsd-core/issues/2003)。v1.39 新增 |
| `workflow.drift_action` | string | `warn` | `/gsd-execute-phase` 后超过 `workflow.drift_threshold` 时的处理方式。`warn` 打印建议运行 `/gsd-map-codebase --paths …` 的消息;`auto-remap` 派生 `gsd-codebase-mapper` 限定于受影响路径。v1.39 新增 |
| `workflow.drift_action` | string | `warn` | `/msd-execute-phase` 后超过 `workflow.drift_threshold` 时的处理方式。`warn` 打印建议运行 `/msd-map-codebase --paths …` 的消息;`auto-remap` 派生 `msd-codebase-mapper` 限定于受影响路径。v1.39 新增 |
| `workflow.build_command` | string | (无) | 在执行阶段步骤 5.6 的步骤 A 中(合并后构建门禁)构建项目的 shell 命令。未设置时,门禁自动检测:Xcode(存在 `.xcodeproj`)→ `xcodebuild build`,带 `build:` 目标的 `Makefile` → `make build`,Justfile → `just build`,`Cargo.toml` → `cargo build`,`go.mod` → `go build ./...`,Python → `python -m py_compile`,带 `build` 脚本的 `package.json` → `npm run build`。5 分钟超时运行;失败时递增 `WAVE_FAILURE_COUNT`。v1.39 新增 |
| `workflow.test_command` | string | (无) | 在执行阶段步骤 5.6 的步骤 B 中(合并后测试门禁)和回归门禁中运行项目测试套件的 shell 命令。未设置时,门禁自动检测:Xcode(存在 `.xcodeproj`)→ `xcodebuild test`,带 `test:` 目标的 `Makefile` → `make test`,Justfile → `just test`,`package.json` → `npm test`,`Cargo.toml` → `cargo test`,`go.mod` → `go test ./...`,Python → `python -m pytest`。5 分钟超时运行;失败时递增 `WAVE_FAILURE_COUNT`。v1.39 新增 |
## 代码质量设置
`code_quality.*` 命名空间控制可选的结构分析工具,作为 `/gsd-code-review` 的补充。各设置为增量式:每个工具独立选择启用,默认关闭。
`code_quality.*` 命名空间控制可选的结构分析工具,作为 `/msd-code-review` 的补充。各设置为增量式:每个工具独立选择启用,默认关闭。
| 设置 | 类型 | 默认值 | 描述 |
|---------|------|---------|-------------|
| `code_quality.fallow.enabled` | boolean | `false` | 为 `/gsd-code-review` 启用 fallow 结构预处理。为 `false` 时,不生成 fallow 二进制探针或 JSON 产物。 |
| `code_quality.fallow.enabled` | boolean | `false` | 为 `/msd-code-review` 启用 fallow 结构预处理。为 `false` 时,不生成 fallow 二进制探针或 JSON 产物。 |
| `code_quality.fallow.scope` | string | `phase` | fallow 分析范围:`phase`(当前审查文件范围)或 `repo`(整个仓库)。 |
| `code_quality.fallow.profile` | string | `standard` | 传递给预处理运行器的 fallow 配置文件选择器(`minimal`、`standard`、`strict`)。 |
| `code_quality.fallow.mcp` | boolean | `false` | **保留——尚未实现。** 为 `true` 时,为支持 MCP 服务器路由的运行时启用基于 MCP 的结构性发现模式。当前将此设为 `true` 是无操作,并会发出运行时警告。 |
## 发布设置
`ship.pr_body_sections` 为 `/gsd-ship` 添加额外的 PR 正文节,用于项目特定的 PRD/PR 正文内容,而无需编辑 `gsd-core/workflows/ship.md`。
`ship.pr_body_sections` 为 `/msd-ship` 添加额外的 PR 正文节,用于项目特定的 PRD/PR 正文内容,而无需编辑 `msd-core/workflows/ship.md`。
有关入门示例和故障排除的用户指南,请参阅[自定义 PR 正文节](../ship-pr-body-sections.md)。
@@ -310,7 +310,7 @@ API 密钥字段接受字符串值(密钥本身)。也可以设置为哨兵
| `template` | string | (无) | 带封闭 token 的字面 Markdown:`{phase_number}`、`{phase_name}`、`{phase_dir}`、`{base_branch}`、`{padded_phase}`。 |
| `fallback` | string | (无) | 当 `source` 不产生内容且未提供 `template` 时使用的字面 Markdown。 |
每个节至少需要 `source`、`template` 或 `fallback` 之一。默认为 `[]`,因此现有项目在入门添加启用条目之前保持当前的 `/gsd-ship` 输出。
每个节至少需要 `source`、`template` 或 `fallback` 之一。默认为 `[]`,因此现有项目在入门添加启用条目之前保持当前的 `/msd-ship` 输出。
示例:
@@ -357,13 +357,13 @@ API 密钥字段接受字符串值(密钥本身)。也可以设置为哨兵
| 设置 | 类型 | 默认值 | 描述 |
|---------|------|---------|-------------|
| `planning.commit_docs` | boolean | `true` | `.planning/` 文件是否提交到 git |
| `planning.pr_strict` | boolean | `false` | `/gsd-pr-branch` 的过滤模式。`false` 会在 PR 分支中保留 STATE.md、ROADMAP.md、MILESTONES.md、PROJECT.md、REQUIREMENTS.md、milestones/ 等结构性规划状态;`true` 会删除所有 `.planning/` 路径 |
| `planning.pr_strict` | boolean | `false` | `/msd-pr-branch` 的过滤模式。`false` 会在 PR 分支中保留 STATE.md、ROADMAP.md、MILESTONES.md、PROJECT.md、REQUIREMENTS.md、milestones/ 等结构性规划状态;`true` 会删除所有 `.planning/` 路径 |
| `planning.search_gitignored` | boolean | `false` | 向大范围搜索添加 `--no-ignore` 以包含 `.planning/` |
| `planning.sub_repos` | string 数组 | `[]` | 相对于项目根目录的嵌套子仓库路径。设置后,GSD 感知工具按子仓库划定阶段查找、路径解析和提交操作的范围,而非将外层仓库视为 monorepo |
| `planning.sub_repos` | string 数组 | `[]` | 相对于项目根目录的嵌套子仓库路径。设置后,MSD 感知工具按子仓库划定阶段查找、路径解析和提交操作的范围,而非将外层仓库视为 monorepo |
### 多仓库工作空间中的项目根目录解析
当设置了 `sub_repos` 且从列出的子仓库内部调用 `gsd-tools.cjs` 或 `gsd-tools query` 时,两个 CLI 都会向上走到拥有 `.planning/` 的父工作空间,然后再分发处理程序。解析顺序(在每个祖先最多向上检查 10 层,不超过 `$HOME`):
当设置了 `sub_repos` 且从列出的子仓库内部调用 `msd-tools.cjs` 或 `msd-tools query` 时,两个 CLI 都会向上走到拥有 `.planning/` 的父工作空间,然后再分发处理程序。解析顺序(在每个祖先最多向上检查 10 层,不超过 `$HOME`):
1. 如果起始目录本身有 `.planning/`,则其为项目根目录(不向上走)。
2. 父目录有 `.planning/config.json`,且其 `sub_repos`(或旧版 `planning.sub_repos` 形式)中列出了起始目录的顶层段。
@@ -383,21 +383,21 @@ API 密钥字段接受字符串值(密钥本身)。也可以设置为哨兵
| 设置 | 类型 | 默认值 | 描述 |
|---------|------|---------|-------------|
| `hooks.context_warnings` | boolean | `true` | 通过上下文监控钩子显示上下文窗口使用警告 |
| `hooks.workflow_guard` | boolean | `false` | 当文件编辑发生在 GSD 工作流上下文之外时发出警告(建议使用 `/gsd-quick` 或 `/gsd-fast`) |
| `hooks.workflow_guard` | boolean | `false` | 当文件编辑发生在 MSD 工作流上下文之外时发出警告(建议使用 `/msd-quick` 或 `/msd-fast`) |
| `statusline.show_last_command` | boolean | `false` | 向状态行追加 `last: /<cmd>` 后缀,显示最近调用的斜杠命令。选择性启用;读取活跃会话记录以提取最新的 `<command-name>` 标签(关闭 #2538) |
| `statusline.context_position` | string | `"end"` | 上下文窗口计量器的位置。`"end"`(默认)在行尾渲染;`"front"` 在模型名称后立即渲染,使计量器在窄终端中保持可见。关闭 #2937 |
提示词注入防护钩子(gsd-prompt-guard.js)始终激活,无法禁用——它是安全特性,而非工作流开关。
提示词注入防护钩子(msd-prompt-guard.js)始终激活,无法禁用——它是安全特性,而非工作流开关。
### 私有规划设置
当 `planning.commit_docs` 为 `false` 且 `.planning/` 在 `.gitignore` 中时,GSD 将规划产物视为仅本地存在。`planning.search_gitignored: true` 确保此配置下大范围搜索仍然包含 `.planning/` 目录。有关设置步骤,请参阅[配置私有规划](how-to/configure-model-profiles.md)。
当 `planning.commit_docs` 为 `false` 且 `.planning/` 在 `.gitignore` 中时,MSD 将规划产物视为仅本地存在。`planning.search_gitignored: true` 确保此配置下大范围搜索仍然包含 `.planning/` 目录。有关设置步骤,请参阅[配置私有规划](how-to/configure-model-profiles.md)。
---
## Agent 技能注入
向 GSD subagent 提示词注入自定义技能文件。技能在 agent spawn 时读取,为其提供 CLAUDE.md 之外的项目特定指令。
向 MSD subagent 提示词注入自定义技能文件。技能在 agent spawn 时读取,为其提供 CLAUDE.md 之外的项目特定指令。
| 设置 | 类型 | 默认值 | 描述 |
|---------|------|---------|-------------|
@@ -410,9 +410,9 @@ API 密钥字段接受字符串值(密钥本身)。也可以设置为哨兵
```json
{
"agent_skills": {
"gsd-executor": ["skills/testing-standards", "skills/api-conventions"],
"gsd-planner": ["skills/architecture-rules"],
"gsd-verifier": ["skills/acceptance-criteria"]
"msd-executor": ["skills/testing-standards", "skills/api-conventions"],
"msd-planner": ["skills/architecture-rules"],
"msd-verifier": ["skills/acceptance-criteria"]
}
}
```
@@ -421,25 +421,25 @@ API 密钥字段接受字符串值(密钥本身)。也可以设置为哨兵
### 支持的 Agent 类型
任何 GSD agent 类型都可以接收技能。常用类型:
任何 MSD agent 类型都可以接收技能。常用类型:
- `gsd-executor` -- 执行实施计划
- `gsd-planner` -- 创建阶段计划
- `gsd-checker` -- 验证计划质量
- `gsd-verifier` -- 执行后验证
- `gsd-researcher` -- 阶段研究
- `gsd-project-researcher` -- 新项目研究
- `gsd-debugger` -- 诊断 agent
- `gsd-codebase-mapper` -- 代码库分析
- `gsd-advisor` -- 讨论阶段顾问
- `gsd-ui-researcher` -- UI 设计契约创建
- `gsd-ui-checker` -- UI 规格验证
- `gsd-roadmapper` -- 路线图创建
- `gsd-synthesizer` -- 研究综合
- `msd-executor` -- 执行实施计划
- `msd-planner` -- 创建阶段计划
- `msd-checker` -- 验证计划质量
- `msd-verifier` -- 执行后验证
- `msd-researcher` -- 阶段研究
- `msd-project-researcher` -- 新项目研究
- `msd-debugger` -- 诊断 agent
- `msd-codebase-mapper` -- 代码库分析
- `msd-advisor` -- 讨论阶段顾问
- `msd-ui-researcher` -- UI 设计契约创建
- `msd-ui-checker` -- UI 规格验证
- `msd-roadmapper` -- 路线图创建
- `msd-synthesizer` -- 研究综合
### 工作原理
在 spawn 时,工作流调用 `gsd-tools query agent-skills <type>`(或旧版 `node gsd-tools.cjs agent-skills <type>`)来加载已配置的技能。如果该 agent 类型存在技能,它们将作为 `<agent_skills>` 块注入到 Task() 提示词中:
在 spawn 时,工作流调用 `msd-tools query agent-skills <type>`(或旧版 `node msd-tools.cjs agent-skills <type>`)来加载已配置的技能。如果该 agent 类型存在技能,它们将作为 `<agent_skills>` 块注入到 Task() 提示词中:
```xml
<agent_skills>
@@ -456,7 +456,7 @@ Read these user-configured skills:
通过 CLI 设置技能:
```bash
gsd-tools query config-set agent_skills.gsd-executor '["skills/my-skill"]'
msd-tools query config-set agent_skills.msd-executor '["skills/my-skill"]'
```
---
@@ -470,7 +470,7 @@ gsd-tools query config-set agent_skills.gsd-executor '["skills/my-skill"]'
| `features.thinking_partner` | boolean | `false` | 在工作流决策点启用思维伙伴分析 |
| `features.global_learnings` | boolean | `false` | 启用跨项目学习流水线(阶段完成时自动复制,注入规划器) |
| `learnings.max_inject` | number | `10` | 注入每个规划器提示词的最大跨项目学习数量。较低值减少提示词大小;较高值提供更广泛的历史上下文 |
| `intel.enabled` | boolean | `false` | 启用可查询的代码库情报系统。为 `true` 时,`/gsd-map-codebase --query` 命令在 `.planning/intel/` 中构建和查询 JSON 索引。v1.34 新增 |
| `intel.enabled` | boolean | `false` | 启用可查询的代码库情报系统。为 `true` 时,`/msd-map-codebase --query` 命令在 `.planning/intel/` 中构建和查询 JSON 索引。v1.34 新增 |
<a id="plan-review-settings"></a>
### 计划审查设置
@@ -479,25 +479,25 @@ gsd-tools query config-set agent_skills.gsd-executor '["skills/my-skill"]'
| 设置 | 类型 | 默认值 | 描述 |
|---------|------|---------|-------------|
| `plan_review.source_grounding` | boolean | `true` | 启用计划漂移防护。为 `true`(默认)时,计划审查将 PLAN.md 中引用的每个符号与实时源代码树对比解析。引用不存在的函数、类、装饰器或 CLI 标志的计划在计划批准前产生 `needs-acknowledgement` 通知。设为 `false` 完全跳过符号验证。可在设置期间(`/gsd-new-project`)或随时通过 `/gsd-settings` 切换。 |
| `plan_review.source_grounding_authority` | enum | `grep` | 选择用于验证符号存在性的解析器适配器。允许值:`grep`(默认——对源文件进行 ripgrep/grep 搜索,任何项目无需额外工具即可使用),`intel`(查询 `/gsd-map-codebase` 构建的 `.planning/intel/api-map.json` 索引;需要 `intel.enabled: true`),`treesitter`(保留用于未来的 tree-sitter 适配器),`lsp`(保留用于未来的 LSP 适配器),`scip`(保留用于未来的 SCIP/LSIF 适配器)。当您已运行 `/gsd-map-codebase` 并希望使用更快的预索引查找时,使用 `intel`。`grep` 和 `intel` 之外的所有值均为保留值,在当前版本中无效。 |
| `plan_review.source_grounding` | boolean | `true` | 启用计划漂移防护。为 `true`(默认)时,计划审查将 PLAN.md 中引用的每个符号与实时源代码树对比解析。引用不存在的函数、类、装饰器或 CLI 标志的计划在计划批准前产生 `needs-acknowledgement` 通知。设为 `false` 完全跳过符号验证。可在设置期间(`/msd-new-project`)或随时通过 `/msd-settings` 切换。 |
| `plan_review.source_grounding_authority` | enum | `grep` | 选择用于验证符号存在性的解析器适配器。允许值:`grep`(默认——对源文件进行 ripgrep/grep 搜索,任何项目无需额外工具即可使用),`intel`(查询 `/msd-map-codebase` 构建的 `.planning/intel/api-map.json` 索引;需要 `intel.enabled: true`),`treesitter`(保留用于未来的 tree-sitter 适配器),`lsp`(保留用于未来的 LSP 适配器),`scip`(保留用于未来的 SCIP/LSIF 适配器)。当您已运行 `/msd-map-codebase` 并希望使用更快的预索引查找时,使用 `intel`。`grep` 和 `intel` 之外的所有值均为保留值,在当前版本中无效。 |
<a id="graphify-settings"></a>
### Graphify 设置
| 设置 | 类型 | 默认值 | 描述 |
|---------|------|---------|-------------|
| `graphify.enabled` | boolean | `false` | 启用项目知识图谱。为 `true` 时,`/gsd-graphify` 在 `.planning/graphs/` 中构建和查询图谱。v1.36 新增 |
| `graphify.build_timeout` | number(秒) | `300` | `/gsd-graphify build` 运行中止前的最大允许秒数。v1.36 新增 |
| `graphify.auto_update` | boolean | `false` | **选择性启用(issue #3347)。** 为 `true`(且 `graphify.enabled` 也为 `true`)时,捆绑的 PostToolUse 钩子 `hooks/gsd-graphify-update.sh` 在默认分支(`git.base_branch` 覆盖,否则为 `main`/`master`/`trunk`)上执行 `git commit/merge/pull/rebase --continue/cherry-pick` 后,在后台分离进程中自动重建项目知识图谱。钩子立即返回;重建更新 `.planning/graphs/{graph.json,graph.html,GRAPH_REPORT.md}` 并写入 `.planning/graphs/.last-build-status.json`(`{ts, status: "running"\|"ok"\|"failed", exit_code, duration_ms, head_at_build}`)。PID 锁定,CI 感知(`$CI` 环境变量抑制),若 `graphify` 不在 `PATH` 中则静默退出。默认 `false`,升级后现有行为不变。 |
| `graphify.enabled` | boolean | `false` | 启用项目知识图谱。为 `true` 时,`/msd-graphify` 在 `.planning/graphs/` 中构建和查询图谱。v1.36 新增 |
| `graphify.build_timeout` | number(秒) | `300` | `/msd-graphify build` 运行中止前的最大允许秒数。v1.36 新增 |
| `graphify.auto_update` | boolean | `false` | **选择性启用(issue #3347)。** 为 `true`(且 `graphify.enabled` 也为 `true`)时,捆绑的 PostToolUse 钩子 `hooks/msd-graphify-update.sh` 在默认分支(`git.base_branch` 覆盖,否则为 `main`/`master`/`trunk`)上执行 `git commit/merge/pull/rebase --continue/cherry-pick` 后,在后台分离进程中自动重建项目知识图谱。钩子立即返回;重建更新 `.planning/graphs/{graph.json,graph.html,GRAPH_REPORT.md}` 并写入 `.planning/graphs/.last-build-status.json`(`{ts, status: "running"\|"ok"\|"failed", exit_code, duration_ms, head_at_build}`)。PID 锁定,CI 感知(`$CI` 环境变量抑制),若 `graphify` 不在 `PATH` 中则静默退出。默认 `false`,升级后现有行为不变。 |
#### 多开发者设置
当多个开发者在同一仓库中重建图谱时,`graphify hook install`(每个克隆运行一次)安装一个 git 合并驱动程序,对并发的 `graph.json` 写入进行联合合并,消除冲突标记。它还注册提交后重建钩子,写入 `.gitattributes`,并将 `graphify merge-driver` 添加到 `.git/config`。单人项目可跳过此步骤。随 graphify v0.7.0 一同引入,以及 `/gsd-graphify status` 显示的 `built_at_commit` 新鲜度信号。
当多个开发者在同一仓库中重建图谱时,`graphify hook install`(每个克隆运行一次)安装一个 git 合并驱动程序,对并发的 `graph.json` 写入进行联合合并,消除冲突标记。它还注册提交后重建钩子,写入 `.gitattributes`,并将 `graphify merge-driver` 添加到 `.git/config`。单人项目可跳过此步骤。随 graphify v0.7.0 一同引入,以及 `/msd-graphify status` 显示的 `built_at_commit` 新鲜度信号。
#### 基于提交的过期性
`/gsd-graphify status` 报告两个正交的过期性信号:
`/msd-graphify status` 报告两个正交的过期性信号:
- **`stale`**(基于 mtime,24 小时窗口)——图谱文件最后写入时间。在 graphify 未自动运行时有用。
- **`commit_stale`**(基于提交,需要 graphify v0.7+)——图谱是否针对当前 `git HEAD` 构建。存在时可信。
@@ -509,10 +509,10 @@ gsd-tools query config-set agent_skills.gsd-executor '["skills/my-skill"]'
```bash
# 启用功能
gsd-tools query config-set features.global_learnings true
msd-tools query config-set features.global_learnings true
# 禁用功能
gsd-tools query config-set features.thinking_partner false
msd-tools query config-set features.thinking_partner false
```
`features.*` 命名空间是动态键模式——无需修改 `VALID_CONFIG_KEYS` 即可添加新的功能标志。任何匹配 `features.<name>` 的键都被配置系统接受。
@@ -537,7 +537,7 @@ gsd-tools query config-set features.thinking_partner false
## STATE.md 前言(阶段生命周期)
`STATE.md` 携带 YAML 前言,状态行钩子在每次渲染时读取。v1.40 添加了四个可选的阶段生命周期字段,由 `parseStateMd()` 读取并由 `formatGsdState()` 渲染:
`STATE.md` 携带 YAML 前言,状态行钩子在每次渲染时读取。v1.40 添加了四个可选的阶段生命周期字段,由 `parseStateMd()` 读取并由 `formatMsdState()` 渲染:
| 字段 | 类型 | 用途 |
|-------|------|---------|
@@ -557,9 +557,9 @@ gsd-tools query config-set features.thinking_partner false
| `git.branching_strategy` | enum | `none` | `none`、`phase` 或 `milestone` |
| `git.base_branch` | string | `main` | 创建阶段/里程碑分支并合并回的集成分支。当仓库使用 `master` 或发布分支时可覆盖 |
| `git.create_tag` | boolean | `true` | 在里程碑完成时创建 git 标签(`v[X.Y]`)。对于有自己发布流程的项目,设为 `false` |
| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | 阶段策略的分支名称模板 |
| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | 里程碑策略的分支名称模板 |
| `git.quick_branch_template` | string 或 null | `null` | `/gsd-quick` 任务的可选分支名称模板 |
| `git.phase_branch_template` | string | `msd/phase-{phase}-{slug}` | 阶段策略的分支名称模板 |
| `git.milestone_branch_template` | string | `msd/{milestone}-{slug}` | 里程碑策略的分支名称模板 |
| `git.quick_branch_template` | string 或 null | `null` | `/msd-quick` 任务的可选分支名称模板 |
### 策略对比
@@ -582,7 +582,7 @@ gsd-tools query config-set features.thinking_partner false
```json
"git": {
"quick_branch_template": "gsd/quick-{num}-{slug}"
"quick_branch_template": "msd/quick-{num}-{slug}"
}
```
@@ -631,7 +631,7 @@ gsd-tools query config-set features.thinking_partner false
| 设置 | 类型 | 默认值 | 描述 |
|---------|------|---------|-------------|
| `workflow.security_enforcement` | boolean | `true` | 通过 `/gsd-secure-phase` 启用威胁模型锚定的安全验证。为 `false` 时完全跳过安全检查 |
| `workflow.security_enforcement` | boolean | `true` | 通过 `/msd-secure-phase` 启用威胁模型锚定的安全验证。为 `false` 时完全跳过安全检查 |
| `workflow.security_asvs_level` | number(1-3) | `1` | OWASP ASVS 验证级别。级别 1 = 机会性,级别 2 = 标准,级别 3 = 全面 |
| `workflow.security_block_on` | string | `"high"` | 阻止阶段推进的最低严重性。选项:`"high"`、`"medium"`、`"low"` |
@@ -671,7 +671,7 @@ gsd-tools query config-set features.thinking_partner false
## 审查设置
为 `/gsd-review` 配置按 CLI 的模型选择。设置后,覆盖该审查器的 CLI 默认模型。
为 `/msd-review` 配置按 CLI 的模型选择。设置后,覆盖该审查器的 CLI 默认模型。
| 设置 | 类型 | 默认值 | 描述 |
|---------|------|---------|-------------|
@@ -680,13 +680,13 @@ gsd-tools query config-set features.thinking_partner false
| `review.models.opencode` | string | (CLI 默认) | 调用 `--opencode` 审查器时使用的模型 |
| `review.models.qwen` | string | (CLI 默认) | 调用 `--qwen` 审查器时使用的模型 |
| `review.models.cursor` | string | (CLI 默认) | 调用 `--cursor` 审查器时使用的模型 |
| `review.models.ollama` | string | (服务器默认) | 调用 `--ollama` 审查器时传递给 Ollama 的模型名称。未设置时使用服务器报告的第一个可用模型(如 `llama3`)。设置为特定标签:`gsd config-set review.models.ollama codellama` |
| `review.models.ollama` | string | (服务器默认) | 调用 `--ollama` 审查器时传递给 Ollama 的模型名称。未设置时使用服务器报告的第一个可用模型(如 `llama3`)。设置为特定标签:`msd config-set review.models.ollama codellama` |
| `review.models.lm_studio` | string | (服务器默认) | 调用 `--lm-studio` 审查器时传递给 LM Studio 的模型名称。未设置时使用服务器报告的第一个可用模型。 |
| `review.models.llama_cpp` | string | (服务器默认) | 调用 `--llama-cpp` 审查器时传递给 llama.cpp 的模型名称。未设置时使用 `/v1/models` 报告的第一个模型。 |
| `review.default_reviewers` | string[] \| null | (所有已检测审查器) | 无标志 `/gsd-review` 的默认审查器子集。示例:`["codex","claude"]`。显式标志和 `--all` 覆盖此设置。 |
| `review.default_reviewers` | string[] \| null | (所有已检测审查器) | 无标志 `/msd-review` 的默认审查器子集。示例:`["codex","claude"]`。显式标志和 `--all` 覆盖此设置。 |
| `review.max_prompt_tokens` | number\|null | null | 组装审查提示词的默认最大预估 token 数。设置后,在发送给每个审查器之前对提示词进行确定性裁剪。按审查器覆盖通过 `review.max_prompt_tokens_per_reviewer` 优先。null = 不裁剪(当前行为)。 |
| `review.max_prompt_tokens_per_reviewer` | object | {} | 按审查器的 token 预算覆盖。键为审查器 slug(ollama、llama_cpp、lm_studio、claude、codex、opencode、qwen、cursor)。值覆盖该审查器的 `review.max_prompt_tokens`。推荐用于本地模型服务器。 |
| `review.ollama_host` | string | `http://localhost:11434` | Ollama 服务器的基础 URL。在非默认端口或远程主机上运行 Ollama 时覆盖:`gsd config-set review.ollama_host http://192.168.1.10:11434` |
| `review.ollama_host` | string | `http://localhost:11434` | Ollama 服务器的基础 URL。在非默认端口或远程主机上运行 Ollama 时覆盖:`msd config-set review.ollama_host http://192.168.1.10:11434` |
| `review.lm_studio_host` | string | `http://localhost:1234` | LM Studio 本地服务器的基础 URL。使用非默认端口时覆盖。 |
| `review.llama_cpp_host` | string | `http://localhost:8080` | llama.cpp 服务器(`llama-server`)的基础 URL。使用非默认端口时覆盖。 |
@@ -713,7 +713,7 @@ gsd-tools query config-set features.thinking_partner false
## 管理器透传标志
配置 `/gsd-manager` 追加到每个分发命令的按步骤标志。这允许在不手动输入标志的情况下自定义管理器运行 discuss、plan 和 execute 步骤的方式。
配置 `/msd-manager` 追加到每个分发命令的按步骤标志。这允许在不手动输入标志的情况下自定义管理器运行 discuss、plan 和 execute 步骤的方式。
| 设置 | 类型 | 默认值 | 描述 |
|---------|------|---------|-------------|
@@ -735,7 +735,7 @@ gsd-tools query config-set features.thinking_partner false
}
```
无效的标志 token 会被净化并记录为警告。只有已识别的 GSD 标志才会透传。
无效的标志 token 会被净化并记录为警告。只有已识别的 MSD 标志才会透传。
---
@@ -745,26 +745,26 @@ gsd-tools query config-set features.thinking_partner false
| Agent | `quality` | `balanced` | `budget` | `adaptive` | `inherit` |
|-------|-----------|------------|----------|------------|-----------|
| gsd-planner | Opus | Opus | Sonnet | Opus | Inherit |
| gsd-roadmapper | Opus | Sonnet | Sonnet | Opus | Inherit |
| gsd-executor | Opus | Sonnet | Sonnet | Sonnet | Inherit |
| gsd-phase-researcher | Opus | Sonnet | Haiku | Sonnet | Inherit |
| gsd-project-researcher | Opus | Sonnet | Haiku | Sonnet | Inherit |
| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-debugger | Opus | Sonnet | Sonnet | Opus | Inherit |
| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Haiku | Inherit |
| gsd-verifier | Sonnet | Sonnet | Haiku | Sonnet | Inherit |
| gsd-plan-checker | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-integration-checker | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-pattern-mapper | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-ui-researcher | Opus | Sonnet | Haiku | Sonnet | Inherit |
| gsd-ui-checker | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-ui-auditor | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-doc-writer | Opus | Sonnet | Haiku | Sonnet | Inherit |
| gsd-doc-verifier | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-planner | Opus | Opus | Sonnet | Opus | Inherit |
| msd-roadmapper | Opus | Sonnet | Sonnet | Opus | Inherit |
| msd-executor | Opus | Sonnet | Sonnet | Sonnet | Inherit |
| msd-phase-researcher | Opus | Sonnet | Haiku | Sonnet | Inherit |
| msd-project-researcher | Opus | Sonnet | Haiku | Sonnet | Inherit |
| msd-research-synthesizer | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-debugger | Opus | Sonnet | Sonnet | Opus | Inherit |
| msd-codebase-mapper | Sonnet | Haiku | Haiku | Haiku | Inherit |
| msd-verifier | Sonnet | Sonnet | Haiku | Sonnet | Inherit |
| msd-plan-checker | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-integration-checker | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-nyquist-auditor | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-pattern-mapper | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-ui-researcher | Opus | Sonnet | Haiku | Sonnet | Inherit |
| msd-ui-checker | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-ui-auditor | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-doc-writer | Opus | Sonnet | Haiku | Sonnet | Inherit |
| msd-doc-verifier | Sonnet | Sonnet | Haiku | Haiku | Inherit |
> **所有 33 个发布 agent 在目录(`gsd-core/bin/shared/model-catalog.json`)中均有显式的按配置文件层级分配。** 上表显示最常用 agent 的代表性子集。对于此处未列出的 agent,`model_overrides` 接受任何已发布的 agent 名称。权威的配置文件数据通过 `src/model-catalog.cts` 从 `gsd-core/bin/shared/model-catalog.json` 导出。
> **所有 33 个发布 agent 在目录(`msd-core/bin/shared/model-catalog.json`)中均有显式的按配置文件层级分配。** 上表显示最常用 agent 的代表性子集。对于此处未列出的 agent,`model_overrides` 接受任何已发布的 agent 名称。权威的配置文件数据通过 `src/model-catalog.cts` 从 `msd-core/bin/shared/model-catalog.json` 导出。
### 按 Agent 覆盖
@@ -774,21 +774,21 @@ gsd-tools query config-set features.thinking_partner false
{
"model_profile": "balanced",
"model_overrides": {
"gsd-executor": "opus",
"gsd-planner": "haiku"
"msd-executor": "opus",
"msd-planner": "haiku"
}
}
```
有效的覆盖值:`opus`、`sonnet`、`haiku`、`inherit`,或任何完全限定的模型 ID(如 `"openai/o3"`、`"google/gemini-2.5-pro"`)。
`model_overrides` 可以设置在 `.planning/config.json`(按项目)或 `~/.gsd/defaults.json`(全局)中。按项目条目在冲突时优先,不冲突的全局条目被保留,因此可以在一个仓库中调整单个 agent 的模型而无需重新设置全局默认值。这在 Claude Code、Codex、OpenCode、Kilo 和其他支持的运行时中统一适用。在 Codex 和 OpenCode 上,解析后的模型在安装时嵌入每个 agent 的静态配置中——`spawn_agent` 和 OpenCode 的 `task` 接口不接受内联 `model` 参数,因此编辑 `model_overrides` 后需要运行 `gsd install <runtime>` 才能使更改生效。参见 issue #2256。
`model_overrides` 可以设置在 `.planning/config.json`(按项目)或 `~/.msd/defaults.json`(全局)中。按项目条目在冲突时优先,不冲突的全局条目被保留,因此可以在一个仓库中调整单个 agent 的模型而无需重新设置全局默认值。这在 Claude Code、Codex、OpenCode、Kilo 和其他支持的运行时中统一适用。在 Codex 和 OpenCode 上,解析后的模型在安装时嵌入每个 agent 的静态配置中——`spawn_agent` 和 OpenCode 的 `task` 接口不接受内联 `model` 参数,因此编辑 `model_overrides` 后需要运行 `msd install <runtime>` 才能使更改生效。参见 issue #2256。
### 按阶段类型的模型(`models`)— v1.41 新增
> 在**阶段**级别(规划、研究、执行、验证)进行调整,无需了解 agent 分类。添加于 [#3023](https://github.com/open-gsd/gsd-core/pull/3030)。
`model_overrides` 是按 **agent** 的(精确但冗长;需要知道 `gsd-codebase-mapper` 属于研究,`gsd-doc-writer` 属于执行)。`models` 块允许用两行表达"规划和执行用 Opus,其余用 Sonnet":
`model_overrides` 是按 **agent** 的(精确但冗长;需要知道 `msd-codebase-mapper` 属于研究,`msd-doc-writer` 属于执行)。`models` 块允许用两行表达"规划和执行用 Opus,其余用 Sonnet":
```json
{
@@ -802,7 +802,7 @@ gsd-tools query config-set features.thinking_partner false
"completion": "sonnet"
},
"model_overrides": {
"gsd-codebase-mapper": "haiku"
"msd-codebase-mapper": "haiku"
}
}
```
@@ -811,11 +811,11 @@ gsd-tools query config-set features.thinking_partner false
| 阶段类型 | Agents |
|---|---|
| `planning` | `gsd-planner`, `gsd-roadmapper`, `gsd-pattern-mapper` |
| `discuss` | `gsd-assumptions-analyzer` |
| `research` | `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-codebase-mapper`, `gsd-ui-researcher` |
| `execution` | `gsd-executor`, `gsd-debugger`, `gsd-doc-writer` |
| `verification` | `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-nyquist-auditor`, `gsd-ui-checker`, `gsd-ui-auditor`, `gsd-doc-verifier`, `gsd-code-reviewer` |
| `planning` | `msd-planner`, `msd-roadmapper`, `msd-pattern-mapper` |
| `discuss` | `msd-assumptions-analyzer` |
| `research` | `msd-phase-researcher`, `msd-project-researcher`, `msd-research-synthesizer`, `msd-codebase-mapper`, `msd-ui-researcher` |
| `execution` | `msd-executor`, `msd-debugger`, `msd-doc-writer` |
| `verification` | `msd-verifier`, `msd-plan-checker`, `msd-integration-checker`, `msd-nyquist-auditor`, `msd-ui-checker`, `msd-ui-auditor`, `msd-doc-verifier`, `msd-code-reviewer` |
| `completion` | (保留——当前无 subagent) |
`discuss` 和 `completion` 被 schema 接受以保持前向兼容性;今天设置它们是无操作,直到某个 subagent 映射到它们为止。
@@ -830,7 +830,7 @@ gsd-tools query config-set features.thinking_partner false
5. 运行时默认值 ← 其他均不适用时
```
五层从上到下组合:`model_profile` 是基础层级,`models[<phase_type>]` 在阶段级别覆盖,`dynamic_routing`(启用时)在软性失败时按尝试次数升级,`model_overrides[<agent>]` 在顶层切出按 agent 的例外,运行时默认值在其他均不适用时生效。在上面的示例中,所有五个研究 agent 解析为 `sonnet`,*除了* `gsd-codebase-mapper`,它被按 agent 覆盖固定为 `haiku`。`dynamic_routing` 默认禁用——关闭时(`enabled: false` 或省略该块),本节的行为与当前相同。
五层从上到下组合:`model_profile` 是基础层级,`models[<phase_type>]` 在阶段级别覆盖,`dynamic_routing`(启用时)在软性失败时按尝试次数升级,`model_overrides[<agent>]` 在顶层切出按 agent 的例外,运行时默认值在其他均不适用时生效。在上面的示例中,所有五个研究 agent 解析为 `sonnet`,*除了* `msd-codebase-mapper`,它被按 agent 覆盖固定为 `haiku`。`dynamic_routing` 默认禁用——关闭时(`enabled: false` 或省略该块),本节的行为与当前相同。
#### 可接受的值
@@ -859,11 +859,11 @@ gsd-tools query config-set features.thinking_partner false
`config-set` 拒绝未知阶段类型:
```bash
$ gsd config-set models.deployment opus
$ msd config-set models.deployment opus
Error: 'models.deployment' is not a valid config key
# 有效:
$ gsd config-set models.research sonnet
$ msd config-set models.research sonnet
```
直接编辑 `.planning/config.json` 较为宽松——解析器简单地忽略无法识别的值并回退到配置文件层级——因此拼写错误不会静默破坏层级解析。
@@ -895,9 +895,9 @@ $ gsd config-set models.research sonnet
| 层级 | Agents | 用途 |
|---|---|---|
| `light` | gsd-codebase-mapper, gsd-doc-classifier, gsd-doc-verifier, gsd-integration-checker, gsd-intel-updater, gsd-nyquist-auditor, gsd-pattern-mapper, gsd-plan-checker, gsd-research-synthesizer, gsd-ui-auditor, gsd-ui-checker | 廉价/快速——纯映射器、扫描器、低风险审计 |
| `standard` | gsd-advisor-researcher, gsd-ai-researcher, gsd-code-fixer, gsd-code-reviewer, gsd-doc-synthesizer, gsd-doc-writer, gsd-domain-researcher, gsd-eval-auditor, gsd-executor, gsd-phase-researcher, gsd-project-researcher, gsd-ui-researcher, gsd-verifier | 默认主力——研究、写作、主要验证 |
| `heavy` | gsd-assumptions-analyzer, gsd-debug-session-manager, gsd-debugger, gsd-eval-planner, gsd-framework-selector, gsd-planner, gsd-roadmapper, gsd-security-auditor, gsd-user-profiler | 深度推理——已处于顶层,无法进一步升级 |
| `light` | msd-codebase-mapper, msd-doc-classifier, msd-doc-verifier, msd-integration-checker, msd-intel-updater, msd-nyquist-auditor, msd-pattern-mapper, msd-plan-checker, msd-research-synthesizer, msd-ui-auditor, msd-ui-checker | 廉价/快速——纯映射器、扫描器、低风险审计 |
| `standard` | msd-advisor-researcher, msd-ai-researcher, msd-code-fixer, msd-code-reviewer, msd-doc-synthesizer, msd-doc-writer, msd-domain-researcher, msd-eval-auditor, msd-executor, msd-phase-researcher, msd-project-researcher, msd-ui-researcher, msd-verifier | 默认主力——研究、写作、主要验证 |
| `heavy` | msd-assumptions-analyzer, msd-debug-session-manager, msd-debugger, msd-eval-planner, msd-framework-selector, msd-planner, msd-roadmapper, msd-security-auditor, msd-user-profiler | 深度推理——已处于顶层,无法进一步升级 |
#### 升级流程
@@ -982,7 +982,7 @@ minimal < low < medium < high < xhigh < max
"heavy": "xhigh"
},
"agent_overrides": {
"gsd-planner": "max"
"msd-planner": "max"
}
}
}
@@ -1045,7 +1045,7 @@ minimal < low < medium < high < xhigh < max
### 执行查询(`resolve-execution`)
使用 `node gsd-tools.cjs resolve-execution <agent-type> [--effort <level>] [--fast-mode <true|false>] [--attempt <n>]` 获取 agent 的完整解析后执行上下文:
使用 `node msd-tools.cjs resolve-execution <agent-type> [--effort <level>] [--fast-mode <true|false>] [--attempt <n>]` 获取 agent 的完整解析后执行上下文:
```json
{
@@ -1068,9 +1068,9 @@ minimal < low < medium < high < xhigh < max
> **Codex CLI 最低支持版本:`0.130.0`**(issue [#3562](https://github.com/open-gsd/gsd-core/issues/3562))。
>
> [Codex CLI 0.130.0](https://github.com/openai/codex/releases/tag/rust-v0.130.0)(2026-05-08 发布)通过 [openai/codex#21485](https://github.com/openai/codex/pull/21485) 移除了通过 extra-skills-roots 发现功能。从此版本起,Codex CLI 仅扫描 `~/.codex/skills/<name>/SKILL.md`、`<project>/.codex/skills/` 和已注册的插件根目录以查找可调用技能。GSD 将 `$gsd-*` 界面安装为 `~/.codex/skills/gsd-<name>/SKILL.md`,因此命令在 Codex 重启后解析。早期 Codex CLI 版本可能显示重复列表(旧版 extra-roots 扫描加上用户根目录副本)——重启 Codex 并升级到 ≥ 0.130.0,或在升级前接受重复项。
> [Codex CLI 0.130.0](https://github.com/openai/codex/releases/tag/rust-v0.130.0)(2026-05-08 发布)通过 [openai/codex#21485](https://github.com/openai/codex/pull/21485) 移除了通过 extra-skills-roots 发现功能。从此版本起,Codex CLI 仅扫描 `~/.codex/skills/<name>/SKILL.md`、`<project>/.codex/skills/` 和已注册的插件根目录以查找可调用技能。MSD 将 `$msd-*` 界面安装为 `~/.codex/skills/msd-<name>/SKILL.md`,因此命令在 Codex 重启后解析。早期 Codex CLI 版本可能显示重复列表(旧版 extra-roots 扫描加上用户根目录副本)——重启 Codex 并升级到 ≥ 0.130.0,或在升级前接受重复项。
当 GSD 为非 Claude 运行时安装时,安装器自动在 `~/.gsd/defaults.json` 中设置 `resolve_model_ids: "omit"`。这使 GSD 为所有 agent 返回空模型参数,因此每个 agent 使用运行时配置的任何模型。默认情况下无需额外设置。
当 MSD 为非 Claude 运行时安装时,安装器自动在 `~/.msd/defaults.json` 中设置 `resolve_model_ids: "omit"`。这使 MSD 为所有 agent 返回空模型参数,因此每个 agent 使用运行时配置的任何模型。默认情况下无需额外设置。
如果您希望不同 agent 使用不同模型,请使用带有运行时可识别的完全限定模型 ID 的 `model_overrides`:
@@ -1078,10 +1078,10 @@ minimal < low < medium < high < xhigh < max
{
"resolve_model_ids": "omit",
"model_overrides": {
"gsd-planner": "o3",
"gsd-executor": "o4-mini",
"gsd-debugger": "o3",
"gsd-codebase-mapper": "o4-mini"
"msd-planner": "o3",
"msd-executor": "o4-mini",
"msd-debugger": "o3",
"msd-codebase-mapper": "o4-mini"
}
}
```
@@ -1133,7 +1133,7 @@ minimal < low < medium < high < xhigh < max
}
```
这将 `gsd-planner` 解析为 `gpt-5.6-sol`(xhigh),`gsd-executor` 解析为 `gpt-5.6-terra`(medium),`gsd-codebase-mapper` 解析为 `gpt-5.6-luna`(medium)。Codex 安装器将 `model = "..."` 和 `model_reasoning_effort = "..."` 嵌入每个生成的 agent TOML。
这将 `msd-planner` 解析为 `gpt-5.6-sol`(xhigh),`msd-executor` 解析为 `gpt-5.6-terra`(medium),`msd-codebase-mapper` 解析为 `gpt-5.6-luna`(medium)。Codex 安装器将 `model = "..."` 和 `model_reasoning_effort = "..."` 嵌入每个生成的 agent TOML。
**Claude 示例** — 显式选择解析到完整 Claude ID(无需 `resolve_model_ids: true`):
@@ -1169,7 +1169,7 @@ minimal < low < medium < high < xhigh < max
**向后兼容性。** 未设置 `runtime` 的配置零行为变化——每个现有配置继续完全相同地工作。自动设置 `resolve_model_ids: "omit"` 的 Codex 安装继续省略模型字段,除非用户通过设置 `runtime: "codex"` 选择启用。
**未知运行时。** 如果 `runtime` 设置为没有内置层级映射且没有 `model_profile_overrides[<runtime>]` 的值,GSD 回退到 Claude 别名安全默认值,而非发出运行时无法接受的模型 ID。要支持新运行时,请在 `model_profile_overrides.<runtime>.{opus,sonnet,haiku}` 中填入有效 ID。
**未知运行时。** 如果 `runtime` 设置为没有内置层级映射且没有 `model_profile_overrides[<runtime>]` 的值,MSD 回退到 Claude 别名安全默认值,而非发出运行时无法接受的模型 ID。要支持新运行时,请在 `model_profile_overrides.<runtime>.{opus,sonnet,haiku}` 中填入有效 ID。
### 配置文件哲学
@@ -1186,11 +1186,11 @@ minimal < low < medium < high < xhigh < max
> **[#49](https://github.com/open-gsd/gsd-core/issues/49)** — 提供商中立的模型策略配置界面。在旧版 `model_profile_overrides` 之前解析。
`model_policy` 提供了一种更简单、提供商中立的方式来跨运行时配置模型层级。对于手动知道正确模型 ID 需要使用 `model_profile_overrides` 的非 Anthropic 运行时,这是首选界面。通过 `/gsd-settings` → 第 8 节(模型策略)配置。
`model_policy` 提供了一种更简单、提供商中立的方式来跨运行时配置模型层级。对于手动知道正确模型 ID 需要使用 `model_profile_overrides` 的非 Anthropic 运行时,这是首选界面。通过 `/msd-settings` → 第 8 节(模型策略)配置。
### 已知提供商预设
通过设置工作流选择提供商和预算级别;GSD 为该提供商/预算组合写入规范模型 ID:
通过设置工作流选择提供商和预算级别;MSD 为该提供商/预算组合写入规范模型 ID:
```json
{
@@ -1227,7 +1227,7 @@ minimal < low < medium < high < xhigh < max
### 通用提供商(逃生舱口)
对于 OpenRouter、LiteLLM、本地网关或任何需要提供精确模型 ID 的运行时,使用 `provider: "generic"`(或 `"custom"`)。GSD 将模型 ID 视为不透明字符串——无前缀推断,无提供商特定默认值:
对于 OpenRouter、LiteLLM、本地网关或任何需要提供精确模型 ID 的运行时,使用 `provider: "generic"`(或 `"custom"`)。MSD 将模型 ID 视为不透明字符串——无前缀推断,无提供商特定默认值:
```json
{
@@ -1266,10 +1266,10 @@ minimal < low < medium < high < xhigh < max
|----------|---------|
| `CLAUDE_CONFIG_DIR` | 覆盖默认配置目录(`~/.claude/`) |
| `GEMINI_API_KEY` | 由上下文监控器检测以切换钩子事件名称 |
| `GSD_AUDIT` | 设置为 `1` 以启用调度审计文件(`.planning/.gsd-trace.jsonl`) |
| `GSD_AUDIT_ARGS` | 设置为 `1` 以在审计/错误事件中包含命令参数(默认省略) |
| `GSD_PROJECT` | 覆盖多项目工作空间支持的项目根目录(v1.32) |
| `GSD_SKIP_SCHEMA_CHECK` | 跳过执行阶段期间的 schema 漂移检测(v1.31) |
| `MSD_AUDIT` | 设置为 `1` 以启用调度审计文件(`.planning/.msd-trace.jsonl`) |
| `MSD_AUDIT_ARGS` | 设置为 `1` 以在审计/错误事件中包含命令参数(默认省略) |
| `MSD_PROJECT` | 覆盖多项目工作空间支持的项目根目录(v1.32) |
| `MSD_SKIP_SCHEMA_CHECK` | 跳过执行阶段期间的 schema 漂移检测(v1.31) |
| `WSL_DISTRO_NAME` | 由安装器检测以处理 WSL 路径 |
---
@@ -1278,9 +1278,9 @@ minimal < low < medium < high < xhigh < max
将设置保存为未来项目的全局默认值:
**位置:** `~/.gsd/defaults.json`
**位置:** `~/.msd/defaults.json`
当 `/gsd-new-project` 创建新的 `config.json` 时,它读取全局默认值并将其作为初始配置合并。按项目设置始终覆盖全局设置。
当 `/msd-new-project` 创建新的 `config.json` 时,它读取全局默认值并将其作为初始配置合并。按项目设置始终覆盖全局设置。
---
@@ -1296,7 +1296,7 @@ minimal < low < medium < high < xhigh < max
{ "kind": "HandlerFailure", "traceId": "...", "command": "plan", "timestamp": "...", "message": "..." }
```
`kind` 字段匹配中心的错误变体之一:`UnknownCommand`、`InvalidArgs`、`HandlerRefusal` 或 `HandlerFailure`。参数默认省略(隐私);参见下方 `GSD_AUDIT_ARGS`。
`kind` 字段匹配中心的错误变体之一:`UnknownCommand`、`InvalidArgs`、`HandlerRefusal` 或 `HandlerFailure`。参数默认省略(隐私);参见下方 `MSD_AUDIT_ARGS`。
### 审计跟踪(选择性启用)
@@ -1304,7 +1304,7 @@ minimal < low < medium < high < xhigh < max
**通过环境变量:**
```bash
GSD_AUDIT=1 gsd plan
MSD_AUDIT=1 msd plan
```
**通过配置(`config.audit.enabled`):**
@@ -1316,7 +1316,7 @@ GSD_AUDIT=1 gsd plan
}
```
**审计文件位置:** `.planning/.gsd-trace.jsonl`(已 gitignore)
**审计文件位置:** `.planning/.msd-trace.jsonl`(已 gitignore)
每行都是一个完整的 `DispatchEvent` JSON 对象,包含 `traceId`(每次调度的唯一 UUID v4)和 `parentTraceId`(当调用者将 `req.parentTraceId` 传入 `Hub.dispatch` 时存在)。未来的初始化编排器(第 2 阶段)将自动连接 `parentTraceId`,使单个顶层调用的所有子调度共享一个公共父级;在此之前,叶子调度发出 `parentTraceId: undefined`。您可以通过在审计文件上过滤 `parentTraceId === <rootTraceId>` 来将子事件关联到父级。文件为仅追加,从不截断;需要时手动轮换或删除。`parentTraceId` 必须是规范的 UUID v4(RFC 4122,格式 `xxxxxxxx-xxxx-4xxx-[89ab]xxx-xxxxxxxxxxxx`);不匹配此格式的值会从发出的事件中静默删除,不会出现在审计输出中。
@@ -1325,10 +1325,10 @@ GSD_AUDIT=1 gsd plan
默认情况下,命令参数从所有发出的事件(stderr 错误和审计文件)中**省略**。要逐字包含参数:
```bash
GSD_AUDIT_ARGS=1 GSD_AUDIT=1 gsd plan --tdd
MSD_AUDIT_ARGS=1 MSD_AUDIT=1 msd plan --tdd
```
`GSD_AUDIT_ARGS` 同时适用于 stderr 错误行和审计文件。
`MSD_AUDIT_ARGS` 同时适用于 stderr 错误行和审计文件。
---

File diff suppressed because it is too large Load Diff

View File

@@ -1,64 +1,64 @@
# GSD 已发布功能清单
# MSD 已发布功能清单
> 所有已发布 GSD 功能面的权威目录:命令、代理、工作流、参考资料、CLI 模块和钩子。当广义文档(AGENTS.md、COMMANDS.md、ARCHITECTURE.md、CLI-TOOLS.md)与文件系统不一致时,以本文件及代码库目录树为准。
> 所有已发布 MSD 功能面的权威目录:命令、代理、工作流、参考资料、CLI 模块和钩子。当广义文档(AGENTS.md、COMMANDS.md、ARCHITECTURE.md、CLI-TOOLS.md)与文件系统不一致时,以本文件及代码库目录树为准。
## 使用说明
- 本文件中的数量基于 v1.36.0 快照,版本之间可能存在偏差。如需实时数量,请在检出目录中运行 `ls commands/gsd/*.md | wc -l`、`ls agents/gsd-*.md | wc -l` 等命令。
- 本文件中的数量基于 v1.36.0 快照,版本之间可能存在偏差。如需实时数量,请在检出目录中运行 `ls commands/msd/*.md | wc -l`、`ls agents/msd-*.md | wc -l` 等命令。
- 本文件列举了所有六大类别(代理、命令、工作流、参考资料、CLI 模块、钩子)中的每个已发布功能面。广义文档可能呈现叙述性内容或精选子集;当其与文件系统不一致时,本文件及目录清单为准。
- v1.36.0 之后新增的功能面应首先在此处记录,再传播到广义文档中。`tests/inventory-manifest-sync.test.cjs` 中的漂移控制测试将清单内容锚定到文件系统。
这是所有已发布 GSD Core 功能面的权威目录。请参阅 [文档索引](README.md) 按主题导航。
这是所有已发布 MSD Core 功能面的权威目录。请参阅 [文档索引](README.md) 按主题导航。
---
## 代理 (33 shipped)
完整清单位于 `agents/gsd-*.md`。"主要文档"列标注了 [`docs/AGENTS.md`](../AGENTS.md) 是否提供完整角色卡(*primary*)、"高级与专项代理"章节中的简短存根(*advanced stub*),或未覆盖(*inventory only*)。
完整清单位于 `agents/msd-*.md`。"主要文档"列标注了 [`docs/AGENTS.md`](../AGENTS.md) 是否提供完整角色卡(*primary*)、"高级与专项代理"章节中的简短存根(*advanced stub*),或未覆盖(*inventory only*)。
| 代理 | 角色(一行描述) | 由谁启动 | 主要文档 |
|------|----------------|----------|----------|
| gsd-project-researcher | 在路线图创建前研究领域生态系统(技术栈、功能、架构、潜在问题)。 | `/gsd-new-project`、`/gsd-new-milestone` | primary |
| gsd-phase-researcher | 在规划前研究特定阶段的实施方案。 | `/gsd-plan-phase` | primary |
| gsd-ui-researcher | 为前端阶段生成 UI 设计契约。 | `/gsd-ui-phase` | primary |
| gsd-assumptions-analyzer | 为 discuss-phase(假设模式)生成有证据支撑的假设。 | `discuss-phase-assumptions` 工作流 | primary |
| gsd-advisor-researcher | 在 discuss-phase 顾问模式下研究单个灰色地带决策。 | `discuss-phase` 工作流(顾问模式) | primary |
| gsd-research-synthesizer | 将并行研究者的输出整合为统一的 SUMMARY.md。 | `/gsd-new-project` | primary |
| gsd-planner | 创建可执行的阶段计划,包含任务分解和目标反向验证。 | `/gsd-plan-phase`、`/gsd-quick` | primary |
| gsd-roadmapper | 创建包含阶段分解和需求映射的项目路线图。 | `/gsd-new-project` | primary |
| gsd-executor | 以原子提交和偏差处理方式执行 GSD 计划。 | `/gsd-execute-phase`、`/gsd-quick` | primary |
| gsd-plan-checker | 验证计划是否能实现阶段目标(8 个验证维度)。 | `/gsd-plan-phase`(验证循环) | primary |
| gsd-integration-checker | 验证跨阶段集成和端到端流程。 | `/gsd-audit-milestone` | primary |
| gsd-ui-checker | 根据质量维度验证 UI-SPEC.md 设计契约。 | `/gsd-ui-phase`(验证循环) | primary |
| gsd-verifier | 通过目标反向分析验证阶段目标的达成情况。 | `/gsd-execute-phase` | primary |
| gsd-nyquist-auditor | 通过生成测试填补奈奎斯特验证空缺。 | `/gsd-validate-phase` | primary |
| gsd-ui-auditor | 对已实现前端代码进行六柱回溯视觉审计。 | `/gsd-ui-review` | primary |
| gsd-codebase-mapper | 探索代码库并撰写结构化分析文档。 | `/gsd-map-codebase` | primary |
| gsd-debugger | 使用科学方法和持久状态调查缺陷。 | `/gsd-debug`、`/gsd-verify-work` | primary |
| gsd-user-profiler | 从 8 个维度评分开发者行为。 | `/gsd-profile-user` | primary |
| gsd-doc-writer | 撰写并更新项目文档。 | `/gsd-docs-update` | primary |
| gsd-doc-verifier | 验证生成文档中的事实声明。 | `/gsd-docs-update` | primary |
| gsd-security-auditor | 验证 PLAN.md 威胁模型中的威胁缓解措施。 | `/gsd-secure-phase` | primary |
| gsd-pattern-mapper | 将新文件映射到最近似的已有类似文件;为规划者撰写 PATTERNS.md。 | `/gsd-plan-phase`(在研究与规划之间) | advanced stub |
| gsd-debug-session-manager | 在隔离上下文中运行完整的 `/gsd-debug` 检查点和续传循环,保持主上下文精简。 | `/gsd-debug` | advanced stub |
| gsd-code-reviewer | 审查源文件中的缺陷、安全问题和代码质量问题;生成 REVIEW.md。 | `/gsd-code-review` | advanced stub |
| gsd-code-fixer | 以每次修复原子提交的方式应用 REVIEW.md 中的修复;生成 REVIEW-FIX.md。 | `/gsd-code-review --fix` | advanced stub |
| gsd-ai-researcher | 将所选 AI 框架的官方文档研究成可实施的指导(AI-SPEC.md §3–§4b)。 | `/gsd-ai-integration-phase` | advanced stub |
| gsd-domain-researcher | 为 AI 系统提供领域专家评估标准和失效模式(AI-SPEC.md §1b)。 | `/gsd-ai-integration-phase` | advanced stub |
| gsd-eval-planner | 为 AI 阶段设计结构化评估策略(AI-SPEC.md §5–§7)。 | `/gsd-ai-integration-phase` | advanced stub |
| gsd-eval-auditor | 对 AI 阶段评估覆盖率进行回溯审计;生成 EVAL-REVIEW.md(COVERED/PARTIAL/MISSING)。 | `/gsd-eval-review` | advanced stub |
| gsd-framework-selector | ≤6 个问题的交互式决策矩阵,为 AI/LLM 框架评分并给出推荐。 | `/gsd-ai-integration-phase` | advanced stub |
| gsd-intel-updater | 撰写结构化 intel 文件(`.planning/intel/*.json`),用作可查询的代码库知识库。 | `/gsd-map-codebase --query` | advanced stub |
| gsd-doc-classifier | 将单个规划文档分类为 ADR、PRD、SPEC、DOC 或 UNKNOWN;并行生成以处理文档语料库。 | `/gsd-ingest-docs` | advanced stub |
| gsd-doc-synthesizer | 将已分类的规划文档综合为一个统一上下文,具有优先级规则、循环检测和三桶冲突报告。 | `/gsd-ingest-docs` | advanced stub |
| msd-project-researcher | 在路线图创建前研究领域生态系统(技术栈、功能、架构、潜在问题)。 | `/msd-new-project`、`/msd-new-milestone` | primary |
| msd-phase-researcher | 在规划前研究特定阶段的实施方案。 | `/msd-plan-phase` | primary |
| msd-ui-researcher | 为前端阶段生成 UI 设计契约。 | `/msd-ui-phase` | primary |
| msd-assumptions-analyzer | 为 discuss-phase(假设模式)生成有证据支撑的假设。 | `discuss-phase-assumptions` 工作流 | primary |
| msd-advisor-researcher | 在 discuss-phase 顾问模式下研究单个灰色地带决策。 | `discuss-phase` 工作流(顾问模式) | primary |
| msd-research-synthesizer | 将并行研究者的输出整合为统一的 SUMMARY.md。 | `/msd-new-project` | primary |
| msd-planner | 创建可执行的阶段计划,包含任务分解和目标反向验证。 | `/msd-plan-phase`、`/msd-quick` | primary |
| msd-roadmapper | 创建包含阶段分解和需求映射的项目路线图。 | `/msd-new-project` | primary |
| msd-executor | 以原子提交和偏差处理方式执行 MSD 计划。 | `/msd-execute-phase`、`/msd-quick` | primary |
| msd-plan-checker | 验证计划是否能实现阶段目标(8 个验证维度)。 | `/msd-plan-phase`(验证循环) | primary |
| msd-integration-checker | 验证跨阶段集成和端到端流程。 | `/msd-audit-milestone` | primary |
| msd-ui-checker | 根据质量维度验证 UI-SPEC.md 设计契约。 | `/msd-ui-phase`(验证循环) | primary |
| msd-verifier | 通过目标反向分析验证阶段目标的达成情况。 | `/msd-execute-phase` | primary |
| msd-nyquist-auditor | 通过生成测试填补奈奎斯特验证空缺。 | `/msd-validate-phase` | primary |
| msd-ui-auditor | 对已实现前端代码进行六柱回溯视觉审计。 | `/msd-ui-review` | primary |
| msd-codebase-mapper | 探索代码库并撰写结构化分析文档。 | `/msd-map-codebase` | primary |
| msd-debugger | 使用科学方法和持久状态调查缺陷。 | `/msd-debug`、`/msd-verify-work` | primary |
| msd-user-profiler | 从 8 个维度评分开发者行为。 | `/msd-profile-user` | primary |
| msd-doc-writer | 撰写并更新项目文档。 | `/msd-docs-update` | primary |
| msd-doc-verifier | 验证生成文档中的事实声明。 | `/msd-docs-update` | primary |
| msd-security-auditor | 验证 PLAN.md 威胁模型中的威胁缓解措施。 | `/msd-secure-phase` | primary |
| msd-pattern-mapper | 将新文件映射到最近似的已有类似文件;为规划者撰写 PATTERNS.md。 | `/msd-plan-phase`(在研究与规划之间) | advanced stub |
| msd-debug-session-manager | 在隔离上下文中运行完整的 `/msd-debug` 检查点和续传循环,保持主上下文精简。 | `/msd-debug` | advanced stub |
| msd-code-reviewer | 审查源文件中的缺陷、安全问题和代码质量问题;生成 REVIEW.md。 | `/msd-code-review` | advanced stub |
| msd-code-fixer | 以每次修复原子提交的方式应用 REVIEW.md 中的修复;生成 REVIEW-FIX.md。 | `/msd-code-review --fix` | advanced stub |
| msd-ai-researcher | 将所选 AI 框架的官方文档研究成可实施的指导(AI-SPEC.md §3–§4b)。 | `/msd-ai-integration-phase` | advanced stub |
| msd-domain-researcher | 为 AI 系统提供领域专家评估标准和失效模式(AI-SPEC.md §1b)。 | `/msd-ai-integration-phase` | advanced stub |
| msd-eval-planner | 为 AI 阶段设计结构化评估策略(AI-SPEC.md §5–§7)。 | `/msd-ai-integration-phase` | advanced stub |
| msd-eval-auditor | 对 AI 阶段评估覆盖率进行回溯审计;生成 EVAL-REVIEW.md(COVERED/PARTIAL/MISSING)。 | `/msd-eval-review` | advanced stub |
| msd-framework-selector | ≤6 个问题的交互式决策矩阵,为 AI/LLM 框架评分并给出推荐。 | `/msd-ai-integration-phase` | advanced stub |
| msd-intel-updater | 撰写结构化 intel 文件(`.planning/intel/*.json`),用作可查询的代码库知识库。 | `/msd-map-codebase --query` | advanced stub |
| msd-doc-classifier | 将单个规划文档分类为 ADR、PRD、SPEC、DOC 或 UNKNOWN;并行生成以处理文档语料库。 | `/msd-ingest-docs` | advanced stub |
| msd-doc-synthesizer | 将已分类的规划文档综合为一个统一上下文,具有优先级规则、循环检测和三桶冲突报告。 | `/msd-ingest-docs` | advanced stub |
**覆盖说明。** `docs/AGENTS.md` 为 21 个主要代理提供了完整角色卡,并为 12 个高级代理提供了简洁存根。该文件中的代理工具权限摘要仅涵盖主要的 21 个代理;高级代理的工具列表记录在 `agents/gsd-*.md` 中各代理的 frontmatter 里。
**覆盖说明。** `docs/AGENTS.md` 为 21 个主要代理提供了完整角色卡,并为 12 个高级代理提供了简洁存根。该文件中的代理工具权限摘要仅涵盖主要的 21 个代理;高级代理的工具列表记录在 `agents/msd-*.md` 中各代理的 frontmatter 里。
---
## 命令 (67 shipped)
完整清单位于 `commands/gsd/*.md`。以下分组与 `docs/COMMANDS.md` 的章节顺序一致;每行包含命令名称、从命令 frontmatter `description:` 派生的一行角色描述,以及源文件链接。`tests/command-count-sync.test.cjs` 将数量锁定到文件系统。
完整清单位于 `commands/msd/*.md`。以下分组与 `docs/COMMANDS.md` 的章节顺序一致;每行包含命令名称、从命令 frontmatter `description:` 派生的一行角色描述,以及源文件链接。`tests/command-count-sync.test.cjs` 将数量锁定到文件系统。
### 命名空间元技能
@@ -66,199 +66,199 @@
| 命令 | 角色 | 源文件 |
|------|------|--------|
| `/gsd-workflow` | 阶段流水线路由器 — 讨论 / 规划 / 执行 / 验证 / 阶段 / 进度。 | [commands/gsd/ns-workflow.md](../../commands/gsd/ns-workflow.md) |
| `/gsd-project` | 项目生命周期路由器 — 里程碑、审计、摘要。 | [commands/gsd/ns-project.md](../../commands/gsd/ns-project.md) |
| `/gsd-quality` | 质量关卡路由器 — 代码审查、调试、审计、安全、评估、UI。 | [commands/gsd/ns-review.md](../../commands/gsd/ns-review.md) |
| `/gsd-context` | 代码库智能路由器 — 映射、图形化、文档、学习。 | [commands/gsd/ns-context.md](../../commands/gsd/ns-context.md) |
| `/gsd-manage` | 管理路由器 — 配置、工作区、工作流、线程、更新、发布、收件箱。 | [commands/gsd/ns-manage.md](../../commands/gsd/ns-manage.md) |
| `/gsd-ideate` | 探索与捕获路由器 — 探索、草图、尖峰、规格、捕获。 | [commands/gsd/ns-ideate.md](../../commands/gsd/ns-ideate.md) |
| `/msd-workflow` | 阶段流水线路由器 — 讨论 / 规划 / 执行 / 验证 / 阶段 / 进度。 | [commands/msd/ns-workflow.md](../../commands/msd/ns-workflow.md) |
| `/msd-project` | 项目生命周期路由器 — 里程碑、审计、摘要。 | [commands/msd/ns-project.md](../../commands/msd/ns-project.md) |
| `/msd-quality` | 质量关卡路由器 — 代码审查、调试、审计、安全、评估、UI。 | [commands/msd/ns-review.md](../../commands/msd/ns-review.md) |
| `/msd-context` | 代码库智能路由器 — 映射、图形化、文档、学习。 | [commands/msd/ns-context.md](../../commands/msd/ns-context.md) |
| `/msd-manage` | 管理路由器 — 配置、工作区、工作流、线程、更新、发布、收件箱。 | [commands/msd/ns-manage.md](../../commands/msd/ns-manage.md) |
| `/msd-ideate` | 探索与捕获路由器 — 探索、草图、尖峰、规格、捕获。 | [commands/msd/ns-ideate.md](../../commands/msd/ns-ideate.md) |
### 核心工作流
| 命令 | 角色 | 源文件 |
|------|------|--------|
| `/gsd-new-project` | 通过深度上下文收集和 PROJECT.md 初始化新项目。 | [commands/gsd/new-project.md](../../commands/gsd/new-project.md) |
| `/gsd-onboard` | 引导现有代码库完成映射、文档摄取、项目设置和 onboarding summary。 | [commands/gsd/onboard.md](../../commands/gsd/onboard.md) |
| `/gsd-workspace` | 管理 GSD 工作区 — 创建(`--new`)、列出(`--list`)或移除(`--remove`)隔离的工作区环境。 | [commands/gsd/workspace.md](../../commands/gsd/workspace.md) |
| `/gsd-discuss-phase` | 在规划前通过自适应提问收集阶段上下文。 | [commands/gsd/discuss-phase.md](../../commands/gsd/discuss-phase.md) |
| `/gsd-mvp-phase` | 将阶段规划为垂直 MVP 切片 — 用户故事、SPIDR 拆分,然后进行阶段规划。 | [commands/gsd/mvp-phase.md](../../commands/gsd/mvp-phase.md) |
| `/gsd-spec-phase` | 苏格拉底式规格细化,生成包含可证伪需求的 SPEC.md。 | [commands/gsd/spec-phase.md](../../commands/gsd/spec-phase.md) |
| `/gsd-ui-phase` | 为前端阶段生成 UI 设计契约(UI-SPEC.md)。 | [commands/gsd/ui-phase.md](../../commands/gsd/ui-phase.md) |
| `/gsd-ai-integration-phase` | 通过框架选择、研究和评估规划生成 AI 设计契约(AI-SPEC.md)。 | [commands/gsd/ai-integration-phase.md](../../commands/gsd/ai-integration-phase.md) |
| `/gsd-plan-phase` | 创建带有验证循环的详细阶段计划(PLAN.md)。 | [commands/gsd/plan-phase.md](../../commands/gsd/plan-phase.md) |
| `/gsd-plan-review-convergence` | 跨 AI 计划收敛循环 — 根据审查反馈重新规划,直到没有 HIGH 级别问题为止(最多 3 个循环)。 | [commands/gsd/plan-review-convergence.md](../../commands/gsd/plan-review-convergence.md) |
| `/gsd-ultraplan-phase` | [BETA] 将计划阶段卸载到 Claude Code 的 ultraplan 云端 — 远程起草,在浏览器中审查,通过 `/gsd-import` 导入回来。仅限 Claude Code。 | [commands/gsd/ultraplan-phase.md](../../commands/gsd/ultraplan-phase.md) |
| `/gsd-spike` | 通过一次性实验快速验证想法;使用 `--wrap-up` 将发现打包为持久技能。 | [commands/gsd/spike.md](../../commands/gsd/spike.md) |
| `/gsd-sketch` | 使用一次性 HTML 原型快速勾画 UI/设计想法;使用 `--wrap-up` 打包发现。 | [commands/gsd/sketch.md](../../commands/gsd/sketch.md) |
| `/gsd-execute-phase` | 使用基于波次的并行化执行阶段中的所有计划。 | [commands/gsd/execute-phase.md](../../commands/gsd/execute-phase.md) |
| `/gsd-verify-work` | 通过自动诊断的对话式 UAT 验证已构建的功能。 | [commands/gsd/verify-work.md](../../commands/gsd/verify-work.md) |
| `/gsd-ship` | 验证后创建 PR、运行审查并准备合并。 | [commands/gsd/ship.md](../../commands/gsd/ship.md) |
| `/gsd-fast` | 内联执行简单任务 — 无子代理、无规划开销。 | [commands/gsd/fast.md](../../commands/gsd/fast.md) |
| `/gsd-quick` | 以 GSD 保证(原子提交、状态跟踪)执行快速任务,但跳过可选代理。 | [commands/gsd/quick.md](../../commands/gsd/quick.md) |
| `/gsd-ui-review` | 对已实现前端代码进行六柱回溯视觉审计。 | [commands/gsd/ui-review.md](../../commands/gsd/ui-review.md) |
| `/gsd-code-review` | 审查阶段中更改的源文件中的缺陷、安全问题和代码质量问题;使用 `--fix` 自动应用发现。 | [commands/gsd/code-review.md](../../commands/gsd/code-review.md) |
| `/gsd-eval-review` | 回溯审计已执行 AI 阶段的评估覆盖率;生成 EVAL-REVIEW.md。 | [commands/gsd/eval-review.md](../../commands/gsd/eval-review.md) |
| `/msd-new-project` | 通过深度上下文收集和 PROJECT.md 初始化新项目。 | [commands/msd/new-project.md](../../commands/msd/new-project.md) |
| `/msd-onboard` | 引导现有代码库完成映射、文档摄取、项目设置和 onboarding summary。 | [commands/msd/onboard.md](../../commands/msd/onboard.md) |
| `/msd-workspace` | 管理 MSD 工作区 — 创建(`--new`)、列出(`--list`)或移除(`--remove`)隔离的工作区环境。 | [commands/msd/workspace.md](../../commands/msd/workspace.md) |
| `/msd-discuss-phase` | 在规划前通过自适应提问收集阶段上下文。 | [commands/msd/discuss-phase.md](../../commands/msd/discuss-phase.md) |
| `/msd-mvp-phase` | 将阶段规划为垂直 MVP 切片 — 用户故事、SPIDR 拆分,然后进行阶段规划。 | [commands/msd/mvp-phase.md](../../commands/msd/mvp-phase.md) |
| `/msd-spec-phase` | 苏格拉底式规格细化,生成包含可证伪需求的 SPEC.md。 | [commands/msd/spec-phase.md](../../commands/msd/spec-phase.md) |
| `/msd-ui-phase` | 为前端阶段生成 UI 设计契约(UI-SPEC.md)。 | [commands/msd/ui-phase.md](../../commands/msd/ui-phase.md) |
| `/msd-ai-integration-phase` | 通过框架选择、研究和评估规划生成 AI 设计契约(AI-SPEC.md)。 | [commands/msd/ai-integration-phase.md](../../commands/msd/ai-integration-phase.md) |
| `/msd-plan-phase` | 创建带有验证循环的详细阶段计划(PLAN.md)。 | [commands/msd/plan-phase.md](../../commands/msd/plan-phase.md) |
| `/msd-plan-review-convergence` | 跨 AI 计划收敛循环 — 根据审查反馈重新规划,直到没有 HIGH 级别问题为止(最多 3 个循环)。 | [commands/msd/plan-review-convergence.md](../../commands/msd/plan-review-convergence.md) |
| `/msd-ultraplan-phase` | [BETA] 将计划阶段卸载到 Claude Code 的 ultraplan 云端 — 远程起草,在浏览器中审查,通过 `/msd-import` 导入回来。仅限 Claude Code。 | [commands/msd/ultraplan-phase.md](../../commands/msd/ultraplan-phase.md) |
| `/msd-spike` | 通过一次性实验快速验证想法;使用 `--wrap-up` 将发现打包为持久技能。 | [commands/msd/spike.md](../../commands/msd/spike.md) |
| `/msd-sketch` | 使用一次性 HTML 原型快速勾画 UI/设计想法;使用 `--wrap-up` 打包发现。 | [commands/msd/sketch.md](../../commands/msd/sketch.md) |
| `/msd-execute-phase` | 使用基于波次的并行化执行阶段中的所有计划。 | [commands/msd/execute-phase.md](../../commands/msd/execute-phase.md) |
| `/msd-verify-work` | 通过自动诊断的对话式 UAT 验证已构建的功能。 | [commands/msd/verify-work.md](../../commands/msd/verify-work.md) |
| `/msd-ship` | 验证后创建 PR、运行审查并准备合并。 | [commands/msd/ship.md](../../commands/msd/ship.md) |
| `/msd-fast` | 内联执行简单任务 — 无子代理、无规划开销。 | [commands/msd/fast.md](../../commands/msd/fast.md) |
| `/msd-quick` | 以 MSD 保证(原子提交、状态跟踪)执行快速任务,但跳过可选代理。 | [commands/msd/quick.md](../../commands/msd/quick.md) |
| `/msd-ui-review` | 对已实现前端代码进行六柱回溯视觉审计。 | [commands/msd/ui-review.md](../../commands/msd/ui-review.md) |
| `/msd-code-review` | 审查阶段中更改的源文件中的缺陷、安全问题和代码质量问题;使用 `--fix` 自动应用发现。 | [commands/msd/code-review.md](../../commands/msd/code-review.md) |
| `/msd-eval-review` | 回溯审计已执行 AI 阶段的评估覆盖率;生成 EVAL-REVIEW.md。 | [commands/msd/eval-review.md](../../commands/msd/eval-review.md) |
### 阶段与里程碑管理
| 命令 | 角色 | 源文件 |
|------|------|--------|
| `/gsd-phase` | 阶段的增删改查 — 在 ROADMAP.md 中添加(默认)、插入(`--insert`)、移除(`--remove`)或编辑(`--edit`)阶段。 | [commands/gsd/phase.md](../../commands/gsd/phase.md) |
| `/gsd-add-tests` | 根据 UAT 标准和实现,为已完成阶段生成测试。 | [commands/gsd/add-tests.md](../../commands/gsd/add-tests.md) |
| `/gsd-validate-phase` | 回溯审计并填补已完成阶段的奈奎斯特验证空缺。 | [commands/gsd/validate-phase.md](../../commands/gsd/validate-phase.md) |
| `/gsd-secure-phase` | 回溯验证已完成阶段的威胁缓解措施。 | [commands/gsd/secure-phase.md](../../commands/gsd/secure-phase.md) |
| `/gsd-audit-milestone` | 在归档前根据原始意图审计里程碑完成情况。 | [commands/gsd/audit-milestone.md](../../commands/gsd/audit-milestone.md) |
| `/gsd-audit-uat` | 跨阶段审计所有待处理的 UAT 和验证项目。 | [commands/gsd/audit-uat.md](../../commands/gsd/audit-uat.md) |
| `/gsd-audit-fix` | 自主审计到修复流水线 — 查找问题、分类、修复、测试、提交。 | [commands/gsd/audit-fix.md](../../commands/gsd/audit-fix.md) |
| `/gsd-complete-milestone` | 归档已完成的里程碑并为下一个版本做准备。 | [commands/gsd/complete-milestone.md](../../commands/gsd/complete-milestone.md) |
| `/gsd-new-milestone` | 启动新的里程碑周期 — 更新 PROJECT.md 并路由到需求。 | [commands/gsd/new-milestone.md](../../commands/gsd/new-milestone.md) |
| `/gsd-milestone-summary` | 从里程碑产物生成全面的项目摘要。 | [commands/gsd/milestone-summary.md](../../commands/gsd/milestone-summary.md) |
| `/gsd-cleanup` | 归档已完成里程碑中积累的阶段目录。 | [commands/gsd/cleanup.md](../../commands/gsd/cleanup.md) |
| `/gsd-manager` | 用于从单个终端管理多个阶段的交互式指挥中心。 | [commands/gsd/manager.md](../../commands/gsd/manager.md) |
| `/gsd-workstreams` | 管理并行工作流 — 列出、创建、切换、状态、进度、完成、恢复。 | [commands/gsd/workstreams.md](../../commands/gsd/workstreams.md) |
| `/gsd-autonomous` | 自主运行所有剩余阶段 — 每个阶段依次讨论 → 规划 → 执行。 | [commands/gsd/autonomous.md](../../commands/gsd/autonomous.md) |
| `/gsd-undo` | 安全的 git 回退 — 使用阶段清单回滚阶段或计划提交。 | [commands/gsd/undo.md](../../commands/gsd/undo.md) |
| `/msd-phase` | 阶段的增删改查 — 在 ROADMAP.md 中添加(默认)、插入(`--insert`)、移除(`--remove`)或编辑(`--edit`)阶段。 | [commands/msd/phase.md](../../commands/msd/phase.md) |
| `/msd-add-tests` | 根据 UAT 标准和实现,为已完成阶段生成测试。 | [commands/msd/add-tests.md](../../commands/msd/add-tests.md) |
| `/msd-validate-phase` | 回溯审计并填补已完成阶段的奈奎斯特验证空缺。 | [commands/msd/validate-phase.md](../../commands/msd/validate-phase.md) |
| `/msd-secure-phase` | 回溯验证已完成阶段的威胁缓解措施。 | [commands/msd/secure-phase.md](../../commands/msd/secure-phase.md) |
| `/msd-audit-milestone` | 在归档前根据原始意图审计里程碑完成情况。 | [commands/msd/audit-milestone.md](../../commands/msd/audit-milestone.md) |
| `/msd-audit-uat` | 跨阶段审计所有待处理的 UAT 和验证项目。 | [commands/msd/audit-uat.md](../../commands/msd/audit-uat.md) |
| `/msd-audit-fix` | 自主审计到修复流水线 — 查找问题、分类、修复、测试、提交。 | [commands/msd/audit-fix.md](../../commands/msd/audit-fix.md) |
| `/msd-complete-milestone` | 归档已完成的里程碑并为下一个版本做准备。 | [commands/msd/complete-milestone.md](../../commands/msd/complete-milestone.md) |
| `/msd-new-milestone` | 启动新的里程碑周期 — 更新 PROJECT.md 并路由到需求。 | [commands/msd/new-milestone.md](../../commands/msd/new-milestone.md) |
| `/msd-milestone-summary` | 从里程碑产物生成全面的项目摘要。 | [commands/msd/milestone-summary.md](../../commands/msd/milestone-summary.md) |
| `/msd-cleanup` | 归档已完成里程碑中积累的阶段目录。 | [commands/msd/cleanup.md](../../commands/msd/cleanup.md) |
| `/msd-manager` | 用于从单个终端管理多个阶段的交互式指挥中心。 | [commands/msd/manager.md](../../commands/msd/manager.md) |
| `/msd-workstreams` | 管理并行工作流 — 列出、创建、切换、状态、进度、完成、恢复。 | [commands/msd/workstreams.md](../../commands/msd/workstreams.md) |
| `/msd-autonomous` | 自主运行所有剩余阶段 — 每个阶段依次讨论 → 规划 → 执行。 | [commands/msd/autonomous.md](../../commands/msd/autonomous.md) |
| `/msd-undo` | 安全的 git 回退 — 使用阶段清单回滚阶段或计划提交。 | [commands/msd/undo.md](../../commands/msd/undo.md) |
### 会话与导航
| 命令 | 角色 | 源文件 |
|------|------|--------|
| `/gsd-progress` | 检查项目进度、显示上下文并路由到下一个操作;使用 `--next` 自动推进或使用 `--do` 运行自由格式任务。 | [commands/gsd/progress.md](../../commands/gsd/progress.md) |
| `/gsd-capture` | 捕获想法、任务、笔记和种子 — todo(默认)、`--note`、`--backlog`、`--seed` 或 `--list` 待处理 todo。 | [commands/gsd/capture.md](../../commands/gsd/capture.md) |
| `/gsd-stats` | 显示项目统计信息 — 阶段、计划、需求、git 指标、时间线。 | [commands/gsd/stats.md](../../commands/gsd/stats.md) |
| `/gsd-pause-work` | 在阶段中途暂停工作时创建上下文交接。 | [commands/gsd/pause-work.md](../../commands/gsd/pause-work.md) |
| `/gsd-resume-work` | 从上一个会话恢复工作并完整还原上下文。 | [commands/gsd/resume-work.md](../../commands/gsd/resume-work.md) |
| `/gsd-explore` | 苏格拉底式构思和想法路由 — 在承诺之前思考想法。 | [commands/gsd/explore.md](../../commands/gsd/explore.md) |
| `/gsd-review-backlog` | 审查并将待办事项提升到活跃里程碑。 | [commands/gsd/review-backlog.md](../../commands/gsd/review-backlog.md) |
| `/gsd-thread` | 管理用于跨会话工作的持久上下文线程。 | [commands/gsd/thread.md](../../commands/gsd/thread.md) |
| `/msd-progress` | 检查项目进度、显示上下文并路由到下一个操作;使用 `--next` 自动推进或使用 `--do` 运行自由格式任务。 | [commands/msd/progress.md](../../commands/msd/progress.md) |
| `/msd-capture` | 捕获想法、任务、笔记和种子 — todo(默认)、`--note`、`--backlog`、`--seed` 或 `--list` 待处理 todo。 | [commands/msd/capture.md](../../commands/msd/capture.md) |
| `/msd-stats` | 显示项目统计信息 — 阶段、计划、需求、git 指标、时间线。 | [commands/msd/stats.md](../../commands/msd/stats.md) |
| `/msd-pause-work` | 在阶段中途暂停工作时创建上下文交接。 | [commands/msd/pause-work.md](../../commands/msd/pause-work.md) |
| `/msd-resume-work` | 从上一个会话恢复工作并完整还原上下文。 | [commands/msd/resume-work.md](../../commands/msd/resume-work.md) |
| `/msd-explore` | 苏格拉底式构思和想法路由 — 在承诺之前思考想法。 | [commands/msd/explore.md](../../commands/msd/explore.md) |
| `/msd-review-backlog` | 审查并将待办事项提升到活跃里程碑。 | [commands/msd/review-backlog.md](../../commands/msd/review-backlog.md) |
| `/msd-thread` | 管理用于跨会话工作的持久上下文线程。 | [commands/msd/thread.md](../../commands/msd/thread.md) |
### 代码库智能
| 命令 | 角色 | 源文件 |
|------|------|--------|
| `/gsd-map-codebase` | 使用并行映射代理分析代码库;使用 `--fast` 进行轻量级扫描或使用 `--query` 进行 intel 查询。 | [commands/gsd/map-codebase.md](../../commands/gsd/map-codebase.md) |
| `/gsd-graphify` | 在 `.planning/graphs/` 中构建、查询和检查项目知识图谱。 | [commands/gsd/graphify.md](../../commands/gsd/graphify.md) |
| `/gsd-extract-learnings` | 从已完成阶段产物中提取决策、经验、模式和意外发现。 | [commands/gsd/extract-learnings.md](../../commands/gsd/extract-learnings.md) |
| `/msd-map-codebase` | 使用并行映射代理分析代码库;使用 `--fast` 进行轻量级扫描或使用 `--query` 进行 intel 查询。 | [commands/msd/map-codebase.md](../../commands/msd/map-codebase.md) |
| `/msd-graphify` | 在 `.planning/graphs/` 中构建、查询和检查项目知识图谱。 | [commands/msd/graphify.md](../../commands/msd/graphify.md) |
| `/msd-extract-learnings` | 从已完成阶段产物中提取决策、经验、模式和意外发现。 | [commands/msd/extract-learnings.md](../../commands/msd/extract-learnings.md) |
### 审查、调试与恢复
| 命令 | 角色 | 源文件 |
|------|------|--------|
| `/gsd-review` | 通过外部 AI CLI 请求跨 AI 同行审查阶段计划。 | [commands/gsd/review.md](../../commands/gsd/review.md) |
| `/gsd-debug` | 在上下文重置时进行跨会话持久状态的系统化调试。 | [commands/gsd/debug.md](../../commands/gsd/debug.md) |
| `/gsd-forensics` | 针对失败 GSD 工作流的事后调查 — 分析 git、产物、状态。 | [commands/gsd/forensics.md](../../commands/gsd/forensics.md) |
| `/gsd-health` | 诊断规划目录健康状态并可选择修复问题。 | [commands/gsd/health.md](../../commands/gsd/health.md) |
| `/gsd-import` | 摄取外部计划,并与项目决策进行冲突检测。 | [commands/gsd/import.md](../../commands/gsd/import.md) |
| `/gsd-inbox` | 根据项目模板分类审查所有未处理的 GitHub 问题和 PR。 | [commands/gsd/inbox.md](../../commands/gsd/inbox.md) |
| `/msd-review` | 通过外部 AI CLI 请求跨 AI 同行审查阶段计划。 | [commands/msd/review.md](../../commands/msd/review.md) |
| `/msd-debug` | 在上下文重置时进行跨会话持久状态的系统化调试。 | [commands/msd/debug.md](../../commands/msd/debug.md) |
| `/msd-forensics` | 针对失败 MSD 工作流的事后调查 — 分析 git、产物、状态。 | [commands/msd/forensics.md](../../commands/msd/forensics.md) |
| `/msd-health` | 诊断规划目录健康状态并可选择修复问题。 | [commands/msd/health.md](../../commands/msd/health.md) |
| `/msd-import` | 摄取外部计划,并与项目决策进行冲突检测。 | [commands/msd/import.md](../../commands/msd/import.md) |
| `/msd-inbox` | 根据项目模板分类审查所有未处理的 GitHub 问题和 PR。 | [commands/msd/inbox.md](../../commands/msd/inbox.md) |
### 文档、用户档案与实用工具
| 命令 | 角色 | 源文件 |
|------|------|--------|
| `/gsd-docs-update` | 生成或更新经代码库验证的项目文档。 | [commands/gsd/docs-update.md](../../commands/gsd/docs-update.md) |
| `/gsd-ingest-docs` | 扫描仓库中混合的 ADR/PRD/SPEC/DOC 文档,通过分类、综合和冲突报告引导或合并到完整的 `.planning/` 设置中。 | [commands/gsd/ingest-docs.md](../../commands/gsd/ingest-docs.md) |
| `/gsd-profile-user` | 生成开发者行为档案和 Claude 可发现的产物。 | [commands/gsd/profile-user.md](../../commands/gsd/profile-user.md) |
| `/gsd-settings` | 配置 GSD 工作流开关和模型档案。 | [commands/gsd/settings.md](../../commands/gsd/settings.md) |
| `/gsd-config` | 配置 GSD 设置 — 工作流开关(默认)、高级旋钮(`--advanced`)、集成(`--integrations`)或模型档案(`--profile`)。 | [commands/gsd/config.md](../../commands/gsd/config.md) |
| `/gsd-pr-branch` | 通过过滤掉 `.planning/` 提交来创建干净的 PR 分支。 | [commands/gsd/pr-branch.md](../../commands/gsd/pr-branch.md) |
| `/gsd-surface` | 切换哪些技能被呈现 — 应用配置文件、列出或禁用集群而无需重新安装。 | [commands/gsd/surface.md](../../commands/gsd/surface.md) |
| `/gsd-update` | 将 GSD 更新到最新版本;使用 `--sync` 跨运行时同步技能或使用 `--reapply` 重新应用本地补丁。 | [commands/gsd/update.md](../../commands/gsd/update.md) |
| `/gsd-help` | 显示可用的 GSD 命令和使用指南。 | [commands/gsd/help.md](../../commands/gsd/help.md) |
| `/msd-docs-update` | 生成或更新经代码库验证的项目文档。 | [commands/msd/docs-update.md](../../commands/msd/docs-update.md) |
| `/msd-ingest-docs` | 扫描仓库中混合的 ADR/PRD/SPEC/DOC 文档,通过分类、综合和冲突报告引导或合并到完整的 `.planning/` 设置中。 | [commands/msd/ingest-docs.md](../../commands/msd/ingest-docs.md) |
| `/msd-profile-user` | 生成开发者行为档案和 Claude 可发现的产物。 | [commands/msd/profile-user.md](../../commands/msd/profile-user.md) |
| `/msd-settings` | 配置 MSD 工作流开关和模型档案。 | [commands/msd/settings.md](../../commands/msd/settings.md) |
| `/msd-config` | 配置 MSD 设置 — 工作流开关(默认)、高级旋钮(`--advanced`)、集成(`--integrations`)或模型档案(`--profile`)。 | [commands/msd/config.md](../../commands/msd/config.md) |
| `/msd-pr-branch` | 通过过滤掉 `.planning/` 提交来创建干净的 PR 分支。 | [commands/msd/pr-branch.md](../../commands/msd/pr-branch.md) |
| `/msd-surface` | 切换哪些技能被呈现 — 应用配置文件、列出或禁用集群而无需重新安装。 | [commands/msd/surface.md](../../commands/msd/surface.md) |
| `/msd-update` | 将 MSD 更新到最新版本;使用 `--sync` 跨运行时同步技能或使用 `--reapply` 重新应用本地补丁。 | [commands/msd/update.md](../../commands/msd/update.md) |
| `/msd-help` | 显示可用的 MSD 命令和使用指南。 | [commands/msd/help.md](../../commands/msd/help.md) |
---
## 工作流 (88 shipped)
完整清单位于 `gsd-core/workflows/*.md`。工作流是命令在内部引用的轻量编排器;大多数不由最终用户直接阅读。以下行将每个工作流文件映射到其角色(来源于 `<purpose>` 块),以及在适用情况下映射到调用它的命令。
完整清单位于 `msd-core/workflows/*.md`。工作流是命令在内部引用的轻量编排器;大多数不由最终用户直接阅读。以下行将每个工作流文件映射到其角色(来源于 `<purpose>` 块),以及在适用情况下映射到调用它的命令。
| 工作流 | 角色 | 调用者 |
|--------|------|--------|
| `add-backlog.md` | 使用 999.x 编号将待办事项添加到 ROADMAP.md。 | `/gsd-capture --backlog` |
| `add-phase.md` | 在路线图中当前里程碑的末尾添加新的整数阶段。 | `/gsd-phase`(默认) |
| `add-tests.md` | 根据已完成阶段的产物生成单元测试和 E2E 测试。 | `/gsd-add-tests` |
| `add-todo.md` | 将会话中出现的想法或任务捕获为结构化 todo。 | `/gsd-capture`(默认) |
| `ai-integration-phase.md` | 将框架选择 → AI 研究 → 领域研究 → 评估规划编排为 AI-SPEC.md。 | `/gsd-ai-integration-phase` |
| `analyze-dependencies.md` | 分析 ROADMAP.md 阶段的文件重叠和语义依赖;建议 `Depends on` 边。 | `/gsd-manager --analyze-deps` |
| `audit-fix.md` | 自主审计到修复流水线 — 运行审计、解析、分类、修复、测试、提交。 | `/gsd-audit-fix` |
| `audit-milestone.md` | 通过聚合阶段验证来验证里程碑是否满足完成定义。 | `/gsd-audit-milestone` |
| `audit-uat.md` | 跨阶段审计 UAT 和验证文件;生成优先排序的待处理事项列表。 | `/gsd-audit-uat` |
| `autonomous.md` | 自主驱动里程碑阶段 — 所有剩余阶段、一个范围或单个阶段。 | `/gsd-autonomous` |
| `check-todos.md` | 列出待处理 todo,允许选择,加载上下文,并路由到适当的操作。 | `/gsd-capture --list` |
| `cleanup.md` | 归档已完成里程碑中积累的阶段目录。 | `/gsd-cleanup` |
| `code-review-fix.md` | 通过 gsd-code-fixer 以每次修复原子提交的方式自动修复 REVIEW.md 中的问题。 | `/gsd-code-review --fix` |
| `code-review.md` | 通过 gsd-code-reviewer 审查阶段源码变更;生成 REVIEW.md。 | `/gsd-code-review` |
| `complete-milestone.md` | 将已发布版本标记为完成 — MILESTONES.md 条目、PROJECT.md 演进、标签。 | `/gsd-complete-milestone` |
| `diagnose-issues.md` | 编排并行调试代理以调查 UAT 差距并找出根本原因。 | `/gsd-verify-work`(自动诊断) |
| `discuss-phase-assumptions.md` | 假设模式讨论 — 通过以代码库为先的分析提取实施决策。 | `/gsd-discuss-phase`(当 `discuss_mode=assumptions` 时) |
| `discuss-phase-power.md` | 高级用户讨论 — 将所有问题预生成到 JSON 状态文件和 HTML UI 中。 | `/gsd-discuss-phase --power` |
| `discuss-phase.md` | 通过迭代灰色地带讨论提取实施决策。 | `/gsd-discuss-phase` |
| `mvp-phase.md` | 将阶段规划为垂直 MVP 切片 — 用户故事、SPIDR 拆分,然后进行阶段规划。 | `/gsd-mvp-phase` |
| `do.md` | 将用户的自由格式文本路由到最匹配的 GSD 命令。 | `/gsd-progress --do` |
| `docs-update.md` | 生成、更新和验证规范的和手写的项目文档。 | `/gsd-docs-update` |
| `edit-phase.md` | 就地编辑 ROADMAP.md 中现有阶段的任何字段,保留编号和位置。 | `/gsd-phase --edit` |
| `eval-review.md` | 对已实现 AI 阶段的评估覆盖率进行回溯审计。 | `/gsd-eval-review` |
| `execute-phase.md` | 使用基于波次的并行执行方式执行阶段中的所有计划。 | `/gsd-execute-phase` |
| `add-backlog.md` | 使用 999.x 编号将待办事项添加到 ROADMAP.md。 | `/msd-capture --backlog` |
| `add-phase.md` | 在路线图中当前里程碑的末尾添加新的整数阶段。 | `/msd-phase`(默认) |
| `add-tests.md` | 根据已完成阶段的产物生成单元测试和 E2E 测试。 | `/msd-add-tests` |
| `add-todo.md` | 将会话中出现的想法或任务捕获为结构化 todo。 | `/msd-capture`(默认) |
| `ai-integration-phase.md` | 将框架选择 → AI 研究 → 领域研究 → 评估规划编排为 AI-SPEC.md。 | `/msd-ai-integration-phase` |
| `analyze-dependencies.md` | 分析 ROADMAP.md 阶段的文件重叠和语义依赖;建议 `Depends on` 边。 | `/msd-manager --analyze-deps` |
| `audit-fix.md` | 自主审计到修复流水线 — 运行审计、解析、分类、修复、测试、提交。 | `/msd-audit-fix` |
| `audit-milestone.md` | 通过聚合阶段验证来验证里程碑是否满足完成定义。 | `/msd-audit-milestone` |
| `audit-uat.md` | 跨阶段审计 UAT 和验证文件;生成优先排序的待处理事项列表。 | `/msd-audit-uat` |
| `autonomous.md` | 自主驱动里程碑阶段 — 所有剩余阶段、一个范围或单个阶段。 | `/msd-autonomous` |
| `check-todos.md` | 列出待处理 todo,允许选择,加载上下文,并路由到适当的操作。 | `/msd-capture --list` |
| `cleanup.md` | 归档已完成里程碑中积累的阶段目录。 | `/msd-cleanup` |
| `code-review-fix.md` | 通过 msd-code-fixer 以每次修复原子提交的方式自动修复 REVIEW.md 中的问题。 | `/msd-code-review --fix` |
| `code-review.md` | 通过 msd-code-reviewer 审查阶段源码变更;生成 REVIEW.md。 | `/msd-code-review` |
| `complete-milestone.md` | 将已发布版本标记为完成 — MILESTONES.md 条目、PROJECT.md 演进、标签。 | `/msd-complete-milestone` |
| `diagnose-issues.md` | 编排并行调试代理以调查 UAT 差距并找出根本原因。 | `/msd-verify-work`(自动诊断) |
| `discuss-phase-assumptions.md` | 假设模式讨论 — 通过以代码库为先的分析提取实施决策。 | `/msd-discuss-phase`(当 `discuss_mode=assumptions` 时) |
| `discuss-phase-power.md` | 高级用户讨论 — 将所有问题预生成到 JSON 状态文件和 HTML UI 中。 | `/msd-discuss-phase --power` |
| `discuss-phase.md` | 通过迭代灰色地带讨论提取实施决策。 | `/msd-discuss-phase` |
| `mvp-phase.md` | 将阶段规划为垂直 MVP 切片 — 用户故事、SPIDR 拆分,然后进行阶段规划。 | `/msd-mvp-phase` |
| `do.md` | 将用户的自由格式文本路由到最匹配的 MSD 命令。 | `/msd-progress --do` |
| `docs-update.md` | 生成、更新和验证规范的和手写的项目文档。 | `/msd-docs-update` |
| `edit-phase.md` | 就地编辑 ROADMAP.md 中现有阶段的任何字段,保留编号和位置。 | `/msd-phase --edit` |
| `eval-review.md` | 对已实现 AI 阶段的评估覆盖率进行回溯审计。 | `/msd-eval-review` |
| `execute-phase.md` | 使用基于波次的并行执行方式执行阶段中的所有计划。 | `/msd-execute-phase` |
| `execute-plan.md` | 执行阶段提示(PLAN.md)并创建结果摘要(SUMMARY.md)。 | `execute-phase.md`(每个计划的子代理) |
| `explore.md` | 苏格拉底式构思 — 通过探究性问题引导开发者。 | `/gsd-explore` |
| `debug.md` | 系统化调试 — 子命令路由、会话创建、委托给 gsd-debug-session-manager。 | `/gsd-debug` |
| `extract-learnings.md` | 从已完成阶段产物中提取决策、经验、模式和意外发现。 | `/gsd-extract-learnings` |
| `fast.md` | 内联执行简单任务,无子代理开销。 | `/gsd-fast` |
| `forensics.md` | 针对失败工作流的取证调查 — git、产物和状态分析。 | `/gsd-forensics` |
| `explore.md` | 苏格拉底式构思 — 通过探究性问题引导开发者。 | `/msd-explore` |
| `debug.md` | 系统化调试 — 子命令路由、会话创建、委托给 msd-debug-session-manager。 | `/msd-debug` |
| `extract-learnings.md` | 从已完成阶段产物中提取决策、经验、模式和意外发现。 | `/msd-extract-learnings` |
| `fast.md` | 内联执行简单任务,无子代理开销。 | `/msd-fast` |
| `forensics.md` | 针对失败工作流的取证调查 — git、产物和状态分析。 | `/msd-forensics` |
| `graduation.md` | 跨阶段聚类 LEARNINGS.md 中的重复项,并显示 HITL 提升候选项。 | `transition.md`(graduation_scan 步骤) |
| `health.md` | 验证 `.planning/` 目录完整性并报告可操作问题。 | `/gsd-health` |
| `help.md` | 显示完整的 GSD Core 命令参考。 | `/gsd-help` |
| `import.md` | 摄取外部计划,并与现有项目决策进行冲突检测。 | `/gsd-import` |
| `inbox.md` | 根据项目贡献模板分类未处理的 GitHub 问题和 PR。 | `/gsd-inbox` |
| `ingest-docs.md` | 扫描仓库中混合的规划文档;分类、综合,并通过冲突报告引导或合并到 `.planning/` 中。 | `/gsd-ingest-docs` |
| `insert-phase.md` | 为里程碑中途发现的紧急工作插入十进制阶段。 | `/gsd-phase --insert` |
| `list-phase-assumptions.md` | 在规划前显示 Claude 对某个阶段的假设。 | `/gsd-discuss-phase --assumptions` |
| `list-workspaces.md` | 列出在 `~/gsd-workspaces/` 中找到的所有 GSD 工作区及其状态。 | `/gsd-workspace --list` |
| `manager.md` | 交互式里程碑指挥中心 — 仪表板、内联讨论、后台规划/执行。 | `/gsd-manager` |
| `map-codebase.md` | 编排并行代码库映射代理以生成 `.planning/codebase/` 文档。 | `/gsd-map-codebase` |
| `milestone-summary.md` | 里程碑摘要综合 — 从里程碑产物生成的入职和审查产物。 | `/gsd-milestone-summary` |
| `new-milestone.md` | 启动新里程碑周期 — 加载项目上下文、收集目标、更新 PROJECT.md/STATE.md。 | `/gsd-new-milestone` |
| `new-project.md` | 统一的新项目流程 — 提问、研究(可选)、需求、路线图。 | `/gsd-new-project` |
| `onboard.md` | Brownfield 接入编排 — 映射代码库、摄取文档、初始化规划并总结下一步。 | `/gsd-onboard` |
| `new-workspace.md` | 创建带有仓库 worktree/克隆和独立 `.planning/` 的隔离工作区。 | `/gsd-workspace --new` |
| `next.md` | 检测当前项目状态并自动推进到下一个逻辑步骤。 | `/gsd-progress --next` |
| `health.md` | 验证 `.planning/` 目录完整性并报告可操作问题。 | `/msd-health` |
| `help.md` | 显示完整的 MSD Core 命令参考。 | `/msd-help` |
| `import.md` | 摄取外部计划,并与现有项目决策进行冲突检测。 | `/msd-import` |
| `inbox.md` | 根据项目贡献模板分类未处理的 GitHub 问题和 PR。 | `/msd-inbox` |
| `ingest-docs.md` | 扫描仓库中混合的规划文档;分类、综合,并通过冲突报告引导或合并到 `.planning/` 中。 | `/msd-ingest-docs` |
| `insert-phase.md` | 为里程碑中途发现的紧急工作插入十进制阶段。 | `/msd-phase --insert` |
| `list-phase-assumptions.md` | 在规划前显示 Claude 对某个阶段的假设。 | `/msd-discuss-phase --assumptions` |
| `list-workspaces.md` | 列出在 `~/msd-workspaces/` 中找到的所有 MSD 工作区及其状态。 | `/msd-workspace --list` |
| `manager.md` | 交互式里程碑指挥中心 — 仪表板、内联讨论、后台规划/执行。 | `/msd-manager` |
| `map-codebase.md` | 编排并行代码库映射代理以生成 `.planning/codebase/` 文档。 | `/msd-map-codebase` |
| `milestone-summary.md` | 里程碑摘要综合 — 从里程碑产物生成的入职和审查产物。 | `/msd-milestone-summary` |
| `new-milestone.md` | 启动新里程碑周期 — 加载项目上下文、收集目标、更新 PROJECT.md/STATE.md。 | `/msd-new-milestone` |
| `new-project.md` | 统一的新项目流程 — 提问、研究(可选)、需求、路线图。 | `/msd-new-project` |
| `onboard.md` | Brownfield 接入编排 — 映射代码库、摄取文档、初始化规划并总结下一步。 | `/msd-onboard` |
| `new-workspace.md` | 创建带有仓库 worktree/克隆和独立 `.planning/` 的隔离工作区。 | `/msd-workspace --new` |
| `next.md` | 检测当前项目状态并自动推进到下一个逻辑步骤。 | `/msd-progress --next` |
| `node-repair.md` | 用于失败任务验证的自主修复算子;由 `execute-plan` 调用。 | `execute-plan.md`(恢复) |
| `note.md` | 零摩擦想法捕获 — 一次 Write 调用,一行确认。 | `/gsd-capture --note` |
| `pause-work.md` | 创建结构化的 `.planning/HANDOFF.json` 和 `.continue-here.md` 交接文件。 | `/gsd-pause-work` |
| `plan-phase.md` | 创建包含集成研究和验证循环的可执行 PLAN.md 文件。 | `/gsd-plan-phase`、`/gsd-quick` |
| `plan-review-convergence.md` | 跨 AI 计划收敛循环 — 根据审查反馈重新规划,直到没有 HIGH 级别问题为止。 | `/gsd-plan-review-convergence` |
| `plant-seed.md` | 将前瞻性想法捕获为带有触发条件的结构化种子文件。 | `/gsd-capture --seed` |
| `pr-branch.md` | 通过过滤 `.planning/` 提交为 PR 创建干净的分支。 | `/gsd-pr-branch` |
| `profile-user.md` | 编排完整的开发者档案流程 — 同意、会话扫描、档案生成。 | `/gsd-profile-user` |
| `progress.md` | 进度渲染 — 项目上下文、位置和下一步操作路由。 | `/gsd-progress` |
| `quick.md` | 以 GSD 保证(原子提交、状态跟踪)快速执行任务。 | `/gsd-quick` |
| `reapply-patches.md` | GSD 更新后重新应用本地修改。 | `/gsd-update --reapply` |
| `remove-phase.md` | 从路线图中移除未来的阶段并重新编号后续阶段。 | `/gsd-phase --remove` |
| `remove-workspace.md` | 移除 GSD 工作区并清理 worktree。 | `/gsd-workspace --remove` |
| `resume-project.md` | 恢复工作 — 从 STATE.md、HANDOFF.json 和产物中完整还原上下文。 | `/gsd-resume-work` |
| `review.md` | 通过外部 CLI 进行跨 AI 计划审查;生成 REVIEWS.md。 | `/gsd-review` |
| `scan.md` | 快速单焦点代码库扫描 — map-codebase 的轻量替代方案。 | `/gsd-map-codebase --fast` |
| `secure-phase.md` | 对已完成阶段进行回溯威胁缓解审计。 | `/gsd-secure-phase` |
| `session-report.md` | 会话报告 — 令牌使用情况、工作摘要、成果。 | `/gsd-pause-work --report` |
| `settings.md` | 配置 GSD 工作流开关和模型档案。 | `/gsd-settings`、`/gsd-config --profile` |
| `settings-advanced.md` | 配置 GSD 高级用户旋钮 — 计划回弹、超时、分支模板、跨 AI 执行、运行时旋钮。 | `/gsd-config --advanced` |
| `settings-integrations.md` | 配置第三方 API 密钥(Brave/Firecrawl/Exa)、`review.models.<cli>` CLI 路由和带掩码(`****<last-4>`)显示的 `agent_skills.<agent-type>` 注入。 | `/gsd-config --integrations` |
| `ship.md` | 验证后创建 PR、运行审查并准备合并。 | `/gsd-ship` |
| `sketch.md` | 通过一次性 HTML 原型(每次草图 2-3 个变体)探索设计方向。 | `/gsd-sketch` |
| `sketch-wrap-up.md` | 整理草图发现并将其打包为持久的 `sketch-findings-[project]` 技能。 | `/gsd-sketch --wrap-up` |
| `spec-phase.md` | 带歧义评分的苏格拉底式规格细化;生成 SPEC.md。 | `/gsd-spec-phase` |
| `spike.md` | 通过聚焦的一次性实验进行快速可行性验证。 | `/gsd-spike` |
| `spike-wrap-up.md` | 整理尖峰发现并将其打包为持久的 `spike-findings-[project]` 技能。 | `/gsd-spike --wrap-up` |
| `stats.md` | 项目统计信息渲染 — 阶段、计划、需求、git 指标。 | `/gsd-stats` |
| `sync-skills.md` | 跨运行时 GSD 技能同步 — 跨运行时根目录差异并应用 `gsd-*` 技能目录。 | `/gsd-update --sync` |
| `transition.md` | 阶段边界过渡工作流 — 工作流检查、状态推进。 | `execute-phase.md`、`/gsd-progress --next` |
| `ui-phase.md` | 通过 gsd-ui-researcher 生成 UI-SPEC.md 设计契约。 | `/gsd-ui-phase` |
| `ui-review.md` | 通过 gsd-ui-auditor 进行六柱回溯视觉审计。 | `/gsd-ui-review` |
| `ultraplan-phase.md` | [BETA] 将规划卸载到 Claude Code 的 ultraplan 云端;远程起草并通过 `/gsd-import` 导入回来。 | `/gsd-ultraplan-phase` |
| `undo.md` | 安全的 git 回退 — 使用阶段清单回滚阶段或计划提交。 | `/gsd-undo` |
| `thread.md` | 为跨会话工作创建、列出、关闭或恢复持久上下文线程。 | `/gsd-thread` |
| `update.md` | 将 GSD 更新到最新版本并显示变更日志。 | `/gsd-update` |
| `validate-phase.md` | 回溯审计并填补已完成阶段的奈奎斯特验证空缺。 | `/gsd-validate-phase` |
| `verify-work.md` | 带自动诊断的对话式 UAT — 生成 UAT.md 和修复计划。 | `/gsd-verify-work` |
| `note.md` | 零摩擦想法捕获 — 一次 Write 调用,一行确认。 | `/msd-capture --note` |
| `pause-work.md` | 创建结构化的 `.planning/HANDOFF.json` 和 `.continue-here.md` 交接文件。 | `/msd-pause-work` |
| `plan-phase.md` | 创建包含集成研究和验证循环的可执行 PLAN.md 文件。 | `/msd-plan-phase`、`/msd-quick` |
| `plan-review-convergence.md` | 跨 AI 计划收敛循环 — 根据审查反馈重新规划,直到没有 HIGH 级别问题为止。 | `/msd-plan-review-convergence` |
| `plant-seed.md` | 将前瞻性想法捕获为带有触发条件的结构化种子文件。 | `/msd-capture --seed` |
| `pr-branch.md` | 通过过滤 `.planning/` 提交为 PR 创建干净的分支。 | `/msd-pr-branch` |
| `profile-user.md` | 编排完整的开发者档案流程 — 同意、会话扫描、档案生成。 | `/msd-profile-user` |
| `progress.md` | 进度渲染 — 项目上下文、位置和下一步操作路由。 | `/msd-progress` |
| `quick.md` | 以 MSD 保证(原子提交、状态跟踪)快速执行任务。 | `/msd-quick` |
| `reapply-patches.md` | MSD 更新后重新应用本地修改。 | `/msd-update --reapply` |
| `remove-phase.md` | 从路线图中移除未来的阶段并重新编号后续阶段。 | `/msd-phase --remove` |
| `remove-workspace.md` | 移除 MSD 工作区并清理 worktree。 | `/msd-workspace --remove` |
| `resume-project.md` | 恢复工作 — 从 STATE.md、HANDOFF.json 和产物中完整还原上下文。 | `/msd-resume-work` |
| `review.md` | 通过外部 CLI 进行跨 AI 计划审查;生成 REVIEWS.md。 | `/msd-review` |
| `scan.md` | 快速单焦点代码库扫描 — map-codebase 的轻量替代方案。 | `/msd-map-codebase --fast` |
| `secure-phase.md` | 对已完成阶段进行回溯威胁缓解审计。 | `/msd-secure-phase` |
| `session-report.md` | 会话报告 — 令牌使用情况、工作摘要、成果。 | `/msd-pause-work --report` |
| `settings.md` | 配置 MSD 工作流开关和模型档案。 | `/msd-settings`、`/msd-config --profile` |
| `settings-advanced.md` | 配置 MSD 高级用户旋钮 — 计划回弹、超时、分支模板、跨 AI 执行、运行时旋钮。 | `/msd-config --advanced` |
| `settings-integrations.md` | 配置第三方 API 密钥(Brave/Firecrawl/Exa)、`review.models.<cli>` CLI 路由和带掩码(`****<last-4>`)显示的 `agent_skills.<agent-type>` 注入。 | `/msd-config --integrations` |
| `ship.md` | 验证后创建 PR、运行审查并准备合并。 | `/msd-ship` |
| `sketch.md` | 通过一次性 HTML 原型(每次草图 2-3 个变体)探索设计方向。 | `/msd-sketch` |
| `sketch-wrap-up.md` | 整理草图发现并将其打包为持久的 `sketch-findings-[project]` 技能。 | `/msd-sketch --wrap-up` |
| `spec-phase.md` | 带歧义评分的苏格拉底式规格细化;生成 SPEC.md。 | `/msd-spec-phase` |
| `spike.md` | 通过聚焦的一次性实验进行快速可行性验证。 | `/msd-spike` |
| `spike-wrap-up.md` | 整理尖峰发现并将其打包为持久的 `spike-findings-[project]` 技能。 | `/msd-spike --wrap-up` |
| `stats.md` | 项目统计信息渲染 — 阶段、计划、需求、git 指标。 | `/msd-stats` |
| `sync-skills.md` | 跨运行时 MSD 技能同步 — 跨运行时根目录差异并应用 `msd-*` 技能目录。 | `/msd-update --sync` |
| `transition.md` | 阶段边界过渡工作流 — 工作流检查、状态推进。 | `execute-phase.md`、`/msd-progress --next` |
| `ui-phase.md` | 通过 msd-ui-researcher 生成 UI-SPEC.md 设计契约。 | `/msd-ui-phase` |
| `ui-review.md` | 通过 msd-ui-auditor 进行六柱回溯视觉审计。 | `/msd-ui-review` |
| `ultraplan-phase.md` | [BETA] 将规划卸载到 Claude Code 的 ultraplan 云端;远程起草并通过 `/msd-import` 导入回来。 | `/msd-ultraplan-phase` |
| `undo.md` | 安全的 git 回退 — 使用阶段清单回滚阶段或计划提交。 | `/msd-undo` |
| `thread.md` | 为跨会话工作创建、列出、关闭或恢复持久上下文线程。 | `/msd-thread` |
| `update.md` | 将 MSD 更新到最新版本并显示变更日志。 | `/msd-update` |
| `validate-phase.md` | 回溯审计并填补已完成阶段的奈奎斯特验证空缺。 | `/msd-validate-phase` |
| `verify-work.md` | 带自动诊断的对话式 UAT — 生成 UAT.md 和修复计划。 | `/msd-verify-work` |
> **注意:** 某些工作流没有直接面向用户的命令(例如 `execute-plan.md`、`transition.md`、`node-repair.md`、`diagnose-issues.md`)— 它们由编排器工作流在内部调用。
@@ -266,7 +266,7 @@
## 参考资料 (62 shipped)
完整清单位于 `gsd-core/references/*.md`。参考资料是工作流和代理 `@-reference` 的共享知识文档。以下分组与 [`docs/ARCHITECTURE.md`](ARCHITECTURE.md#references-gsd-corereferencesmd) 一致 — 核心、工作流、思维模型集群和模块化规划器分解。
完整清单位于 `msd-core/references/*.md`。参考资料是工作流和代理 `@-reference` 的共享知识文档。以下分组与 [`docs/ARCHITECTURE.md`](ARCHITECTURE.md#references-msd-corereferencesmd) 一致 — 核心、工作流、思维模型集群和模块化规划器分解。
### 核心参考资料
@@ -278,7 +278,7 @@
| `model-profile-resolution.md` | 模型解析算法文档。 |
| `verification-patterns.md` | 如何验证不同的产物类型。 |
| `verification-overrides.md` | 每种产物的验证覆盖规则。 |
| `verifier-phase-gates.md` | 由 gsd-verifier 急切加载的验证期门禁(自已退役的 verify-phase 工作流迁移,#1892):决策覆盖校验(#2492)、测试质量审计、基础设施阶段的 human-verification 划定(#2504)。 | |
| `verifier-phase-gates.md` | 由 msd-verifier 急切加载的验证期门禁(自已退役的 verify-phase 工作流迁移,#1892):决策覆盖校验(#2492)、测试质量审计、基础设施阶段的 human-verification 划定(#2504)。 | |
| `planning-config.md` | 完整的配置模式和行为。 |
| `git-integration.md` | Git 提交、分支和历史模式。 |
| `git-planning-commit.md` | 规划目录提交约定。 |
@@ -286,7 +286,7 @@
| `tdd.md` | 测试驱动开发集成模式。 |
| `ui-brand.md` | 视觉输出格式模式。 |
| `common-bug-patterns.md` | 代码审查和验证的常见缺陷模式。 |
| `debugger-philosophy.md` | 由 `gsd-debugger` 加载的长青调试准则。 |
| `debugger-philosophy.md` | 由 `msd-debugger` 加载的长青调试准则。 |
| `mandatory-initial-read.md` | 注入到代理提示中的共享必读样板文本。 |
| `project-skills-discovery.md` | 注入到代理提示中的共享项目技能发现样板文本。 |
@@ -311,9 +311,9 @@
| `thinking-partner.md` | 决策点处的条件性思维伙伴激活。 |
| `autonomous-smart-discuss.md` | 自主模式的智能讨论逻辑。 |
| `ios-scaffold.md` | iOS 应用程序脚手架模式。 |
| `ai-evals.md` | `/gsd-ai-integration-phase` 的 AI 评估设计参考。 |
| `ai-frameworks.md` | `gsd-framework-selector` 的 AI 框架决策矩阵参考。 |
| `executor-examples.md` | gsd-executor 代理的已完成示例。 |
| `ai-evals.md` | `/msd-ai-integration-phase` 的 AI 评估设计参考。 |
| `ai-frameworks.md` | `msd-framework-selector` 的 AI 框架决策矩阵参考。 |
| `executor-examples.md` | msd-executor 代理的已完成示例。 |
| `doc-conflict-engine.md` | 摄取/导入工作流的共享冲突检测契约。 |
| `execute-mvp-tdd.md` | MVP+TDD 模式下 execute-phase 的运行时关卡语义 — 任务前失败测试验证、阶段结束阻塞性审查。 |
| `mvp-concepts.md` | 六个 MVP 相关参考文件的交叉引用索引;将每个文件映射到其目的和加载它的工作流。 |
@@ -321,7 +321,7 @@
### 草图参考资料
`/gsd-sketch` 工作流及其收尾配套使用的参考资料。
`/msd-sketch` 工作流及其收尾配套使用的参考资料。
| 参考资料 | 角色 |
|----------|------|
@@ -332,7 +332,7 @@
### 思维模型参考资料
将思维类模型(o3、o4-mini、Gemini 2.5 Pro)集成到 GSD 工作流中的参考资料。
将思维类模型(o3、o4-mini、Gemini 2.5 Pro)集成到 MSD 工作流中的参考资料。
| 参考资料 | 角色 |
|----------|------|
@@ -344,14 +344,14 @@
### 模块化规划器分解
`gsd-planner` 代理被分解为一个核心代理加上参考模块,以适应运行时字符限制。
`msd-planner` 代理被分解为一个核心代理加上参考模块,以适应运行时字符限制。
| 参考资料 | 角色 |
|----------|------|
| `planner-antipatterns.md` | 规划器反模式和特异性示例。 |
| `planner-chunked.md` | 分块模式返回格式(`## OUTLINE COMPLETE`、`## PLAN COMPLETE`),用于缓解 Windows stdio 挂起问题。 |
| `planner-gap-closure.md` | 间隙闭合模式行为(读取 VERIFICATION.md,有针对性地重新规划)。 |
| `planner-reviews.md` | 跨 AI 审查集成(读取来自 `/gsd-review` 的 REVIEWS.md)。 |
| `planner-reviews.md` | 跨 AI 审查集成(读取来自 `/msd-review` 的 REVIEWS.md)。 |
| `planner-revision.md` | 迭代细化的计划修订模式。 |
| `planner-source-audit.md` | 规划器源代码审计和权限限制规则。 |
| `planner-mvp-mode.md` | MVP 模式的垂直切片规划规则。 |
@@ -362,26 +362,26 @@
| `user-story-template.md` | MVP 规划的用户故事格式 — "作为 / 我想要 / 以便" 结构化字段。 |
| `spidr-splitting.md` | 用于在 MVP 模式下处理大型用户故事的 SPIDR 拆分分解规则。 |
> **子目录:** `gsd-core/references/few-shot-examples/` 包含额外的少样本示例(`plan-checker.md`、`verifier.md`),这些示例从特定代理中引用。它们不计入 62 个顶级参考资料。
> **子目录:** `msd-core/references/few-shot-examples/` 包含额外的少样本示例(`plan-checker.md`、`verifier.md`),这些示例从特定代理中引用。它们不计入 62 个顶级参考资料。
---
## CLI 模块 (81 shipped)
完整清单:`gsd-core/bin/lib/*.cjs`。
完整清单:`msd-core/bin/lib/*.cjs`。
| 模块 | 职责 |
|------|------|
| `active-workstream-store.cjs` | 工作流来源优先级和选择(CLI `--ws` > `GSD_WORKSTREAM` 环境变量 > 存储的指针);名称验证和环境传播 |
| `active-workstream-store.cjs` | 工作流来源优先级和选择(CLI `--ws` > `MSD_WORKSTREAM` 环境变量 > 存储的指针);名称验证和环境传播 |
| `adr-parser.cjs` | 用于 plan-phase 摄取快速路径的 ADR 决策解析器;规范化章节同义词,解析状态/决策/范围围栏,并强制执行状态拒绝关卡 |
| `agent-command-router.cjs` | `gsd-tools agent` 的轻量 CJS 子命令路由适配器 |
| `artifacts.cjs` | 规范产物注册表 — 已知的 `.planning/` 根文件名;被 `gsd-health` W019 lint 使用 |
| `agent-command-router.cjs` | `msd-tools agent` 的轻量 CJS 子命令路由适配器 |
| `artifacts.cjs` | 规范产物注册表 — 已知的 `.planning/` 根文件名;被 `msd-health` W019 lint 使用 |
| `audit.cjs` | 审计分发、审计开放会话、审计存储帮助器 |
| `check-command-router.cjs` | `gsd-tools check` 的轻量 CJS 子命令路由适配器 |
| `check-command-router.cjs` | `msd-tools check` 的轻量 CJS 子命令路由适配器 |
| `cjs-command-router-adapter.cjs` | 清单支持的 CJS 命令族路由器的共享兼容性适配器 |
| `clock.cjs` | 用于确定性锁测试的可注入时钟接缝(now/sleep) |
| `clusters.cjs` | 运行时 surface 模块的技能集群定义(ADR-0011 阶段 2) |
| `code-review-flags.cjs` | `/gsd-code-review` 的类型化标志解析器;导出 `parseCodeReviewFlags(argv)`(→ `{ fix, all, auto, depth, files }`)和 `resolveCodeReviewWorkflow(flags)`(→ `'code-review.md' \| 'code-review-fix.md'`);`--fix`/`--all`/`--auto` 路由的规范分发接缝 |
| `code-review-flags.cjs` | `/msd-code-review` 的类型化标志解析器;导出 `parseCodeReviewFlags(argv)`(→ `{ fix, all, auto, depth, files }`)和 `resolveCodeReviewWorkflow(flags)`(→ `'code-review.md' \| 'code-review-fix.md'`);`--fix`/`--all`/`--auto` 路由的规范分发接缝 |
| `command-aliases.cjs` | 清单支持的族路由器的别名/子命令元数据 |
| `command-arg-projection.cjs` | 跨命令族路由器共享的类型化标志和位置参数投影帮助器 |
| `command-routing-hub.cjs` | 纯结果分发中心,集中了所有命令族路由器的模式决策(SDK vs CJS)、错误分类和无抛出契约(#3788) |
@@ -390,63 +390,63 @@
| `config.cjs` | `config.json` 读写、章节初始化;从 `config-schema.cjs` 导入验证器 |
| `config-types.cjs` | `model_policy` 配置块的 TypeScript 类型定义 — `ModelPolicyConfig`、`TierEntry`、`RuntimeTiers`;在发布时从 `src/config-types.cts` 编译(ADR-457) |
| `configuration.cjs` | 配置模块 — 规范的配置加载、旧版键规范化、默认值合并和显式磁盘迁移;SDK 和 CJS 消费者的真实来源 |
| `context-utilization.cjs` | `gsd-health --context` 的纯分类器 — 根据 60%/70% 断裂点阈值将(tokensUsed, contextWindow)转换为 `{ percent, state }` 分类结果(#2792) |
| `context-utilization.cjs` | `msd-health --context` 的纯分类器 — 根据 60%/70% 断裂点阈值将(tokensUsed, contextWindow)转换为 `{ percent, state }` 分类结果(#2792) |
| `core.cjs` | 错误处理、输出格式化、共享工具、运行时回退;规划工作区帮助器的兼容性重新导出 |
| `decisions.cjs` | 解析 CONTEXT.md `<decisions>` 块;接受数字(D-42)和字母数字(D-INFRA-01)ID;返回 `{id, text, category, tags, trackable}` |
| `docs.cjs` | 文档更新工作流初始化、Markdown 扫描、单体仓库检测 |
| `drift.cjs` | 执行后代码库结构漂移检测器(#2003):将文件更改分类为新目录/桶/迁移/路由类别,并循环处理 `last_mapped_commit` frontmatter |
| `fallow-runner.cjs` | `/gsd-code-review` 的 fallow 审计适配器:二进制解析(`node_modules/.bin` 然后 `PATH`)、可操作的缺少二进制错误和结构性发现规范化 |
| `fallow-runner.cjs` | `/msd-code-review` 的 fallow 审计适配器:二进制解析(`node_modules/.bin` 然后 `PATH`)、可操作的缺少二进制错误和结构性发现规范化 |
| `frontmatter.cjs` | YAML frontmatter 增删改查操作 |
| `gap-checker.cjs` | 规划后间隙分析(#2493):REQUIREMENTS.md + CONTEXT.md 决策 vs PLAN.md 覆盖率报告(`gsd-tools gap-analysis`) |
| `graphify.cjs` | `/gsd-graphify` 的知识图谱构建/查询/状态/差异 |
| `gsd2-import.cjs` | `/gsd-import --from-gsd2` 的外部计划摄取 |
| `init-command-router.cjs` | `gsd-tools init` 的轻量 CJS 子命令路由适配器 |
| `gap-checker.cjs` | 规划后间隙分析(#2493):REQUIREMENTS.md + CONTEXT.md 决策 vs PLAN.md 覆盖率报告(`msd-tools gap-analysis`) |
| `graphify.cjs` | `/msd-graphify` 的知识图谱构建/查询/状态/差异 |
| `gsd2-import.cjs` | `/msd-import --from-gsd2` 的外部计划摄取 |
| `init-command-router.cjs` | `msd-tools init` 的轻量 CJS 子命令路由适配器 |
| `init.cjs` | 每种工作流类型的复合上下文加载 |
| `install-profiles.cjs` | `--minimal` 安装的安装配置文件允许列表和技能暂存(#2762);哪些 `gsd-*` 技能/代理落入运行时配置目录的单一真实来源 |
| `install-profiles.cjs` | `--minimal` 安装的安装配置文件允许列表和技能暂存(#2762);哪些 `msd-*` 技能/代理落入运行时配置目录的单一真实来源 |
| `installer-migration-authoring.cjs` | 记录元数据、显式范围、所有权证据和运行时契约引用的安装程序迁移创作守卫 |
| `installer-migration-report.cjs` | 安装/更新集成的安装程序迁移报告投影和阻止操作守卫 |
| `installer-migrations.cjs` | 安装程序迁移规划、产物分类、安装状态持久化、日志化应用和回滚帮助器 |
| `intel.cjs` | 支持 `/gsd-map-codebase --query` 和 `gsd-intel-updater` 的代码库 intel 存储 |
| `learnings.cjs` | `/gsd-extract-learnings` 的跨阶段学习提取 |
| `intel.cjs` | 支持 `/msd-map-codebase --query` 和 `msd-intel-updater` 的代码库 intel 存储 |
| `learnings.cjs` | `/msd-extract-learnings` 的跨阶段学习提取 |
| `milestone.cjs` | 里程碑归档、需求标记 |
| `model-catalog.cjs` | 共享模型目录 JSON 上的 CJS 适配器;导出所有 CLI 消费者的规范运行时层级默认值、代理配置文件映射、别名映射和路由元数据 |
| `model-profiles.cjs` | 源自 `model-catalog.cjs` 的向后兼容配置文件帮助器;不再拥有自己的模型表 |
| `package-identity.cjs` | GSD 已发布包坐标(npm 名称、bin 名称、仓库 slug、变更日志 URL、手动安装命令)的生成单一来源,源自 package.json;由更新工作进程、`check-latest-version` 和安装程序读取(#498) |
| `phase-command-router.cjs` | `gsd-tools phase` 的轻量 CJS 子命令路由适配器 |
| `package-identity.cjs` | MSD 已发布包坐标(npm 名称、bin 名称、仓库 slug、变更日志 URL、手动安装命令)的生成单一来源,源自 package.json;由更新工作进程、`check-latest-version` 和安装程序读取(#498) |
| `phase-command-router.cjs` | `msd-tools phase` 的轻量 CJS 子命令路由适配器 |
| `phase-lifecycle.cjs` | 从 phase-lifecycle SDK 处理程序中提取的纯计算阶段生命周期帮助器 |
| `phase.cjs` | 阶段目录操作、十进制编号、计划索引 |
| `phases-command-router.cjs` | `gsd-tools phases` 的轻量 CJS 子命令路由适配器 |
| `phases-command-router.cjs` | `msd-tools phases` 的轻量 CJS 子命令路由适配器 |
| `plan-scan.cjs` | 用于检测平面和嵌套布局中计划和摘要文件的规范阶段计划扫描器(k014) |
| `planning-workspace.cjs` | 规划路径/工作流接缝(`planningDir`、`planningPaths`、活跃工作流路由、`.planning/.lock` 编排) |
| `project-root.cjs` | 使用四种启发式方法从起始目录解析项目根目录(自己的 `.planning/` 守卫、`sub_repos` 配置、`multiRepo` 标志、`.git` 启发式) |
| `profile-output.cjs` | 档案渲染、USER-PROFILE.md 和 dev-preferences.md 生成 |
| `profile-pipeline.cjs` | 用户行为档案数据流水线、会话文件扫描 |
| `prompt-budget.cjs` | 审查提示的纯令牌预算核算 — 估算令牌,应用确定性修剪优先级(缩减 PROJECT.md 头部、按比例截断计划、删除上下文/研究/需求、硬失败守卫),返回 `review.max_prompt_tokens` 的结构化元数据(#3081) |
| `review-reviewer-selection.cjs` | `/gsd-review` 默认审查者策略和优先级的审查者选择/规范化帮助器 |
| `roadmap-command-router.cjs` | `gsd-tools roadmap` 的轻量 CJS 子命令路由适配器 |
| `review-reviewer-selection.cjs` | `/msd-review` 默认审查者策略和优先级的审查者选择/规范化帮助器 |
| `roadmap-command-router.cjs` | `msd-tools roadmap` 的轻量 CJS 子命令路由适配器 |
| `roadmap-upgrade.cjs` | 将旧版 `Phase N` 条目转换为里程碑前缀 `Phase M-NN` 约定的迁移工具;`computeMigrationPlan` + `applyMigration`,默认为试运行并具有原子回滚 |
| `roadmap.cjs` | ROADMAP.md 解析、阶段提取、计划进度 |
| `runtime-artifact-layout.cjs` | 运行时产物布局模块 — 解析每个受支持运行时的产物目录形状(命令、代理、技能);每个运行时产物放置的单一真实来源(#3663) |
| `runtime-name-policy.cjs` | 运行时名称规范化策略 — 用于路径构建和显示的运行时标识符的规范令牌清理 |
| `runtime-homes.cjs` | 规范的运行时 → 全局配置/技能目录映射;对所有 15 个运行时的一流支持,包括 Hermes 嵌套布局和 Cline 基于规则的排除(#3126) |
| `runtime-slash.cjs` | 运行时感知的斜杠命令格式化器 — 在面向用户的输出和持久化产物中发出 `/gsd-<cmd>`(基于技能的运行时)和 `$gsd-<cmd>`(codex)的单一真实来源(#3584) |
| `runtime-slash.cjs` | 运行时感知的斜杠命令格式化器 — 在面向用户的输出和持久化产物中发出 `/msd-<cmd>`(基于技能的运行时)和 `$msd-<cmd>`(codex)的单一真实来源(#3584) |
| `schema-detect.cjs` | ORM 模式的模式漂移检测(Prisma、Drizzle、Supabase、TypeORM、Payload);导出 `detectSchemaFiles`、`detectSchemaOrm`、`checkSchemaDrift`、`SCHEMA_PATTERNS`、`ORM_INFO` |
| `secrets.cjs` | 集成密钥的密钥配置掩码约定(`****<last-4>`);导出 `SECRET_CONFIG_KEYS`、`isSecretKey`、`maskSecret`、`maskIfSecret` |
| `semver-compare.cjs` | 共享 semver 比较策略帮助器(`compareSemverCore`、稳定三元组验证、规范化元组解析),由更新检查钩子、statusline 开发安装检测和变更集提取范围逻辑使用(#10) |
| `security.cjs` | 路径遍历防护、提示注入检测、安全 JSON/shell 帮助器 |
| `shell-command-projection.cjs` | 托管钩子序列化的运行时感知 shell 命令投影:根据运行时/平台决定 PowerShell 调用操作符使用,并规范化 Windows 脚本路径令牌 |
| `state-command-router.cjs` | `gsd-tools state` 的轻量 CJS 子命令路由适配器 |
| `state-command-router.cjs` | `msd-tools state` 的轻量 CJS 子命令路由适配器 |
| `state.cjs` | STATE.md 解析、更新、进度推进、指标 |
| `state-document.cjs` | 纯 STATE.md 字段提取、替换、状态规范化和进度计算转换 |
| `surface.cjs` | 运行时 surface 模块 — 独立于安装时配置文件标记管理运行时启用/禁用 surface 状态(ADR-0011 阶段 2) |
| `task-command-router.cjs` | `gsd-tools task` 的轻量 CJS 子命令路由适配器 |
| `task-command-router.cjs` | `msd-tools task` 的轻量 CJS 子命令路由适配器 |
| `template.cjs` | 带变量替换的模板选择和填充 |
| `uat.cjs` | UAT 文件解析、验证债务跟踪、audit-uat 支持 |
| `ui-safety-gate.cjs` | 无 shell 的词边界 UI 令牌检测器(#3706,#3718);从 stdin 读取阶段章节文本,退出 0(找到 UI)或 1(未找到 UI);也部署到 `gsd-core/bin/lib/`,以便 GSD 安装程序将其传送到 `$RUNTIME_DIR`(#448) |
| `update-context.cjs` | `/gsd-update` 的纯安装上下文解析器 — 从 update.md bash 移植的运行时/范围/配置目录/版本检测(LOCAL/GLOBAL/UNKNOWN);支持 `gsd-tools update-context`(#498) |
| `validate-command-router.cjs` | `gsd-tools validate` 的轻量 CJS 子命令路由适配器 |
| `ui-safety-gate.cjs` | 无 shell 的词边界 UI 令牌检测器(#3706,#3718);从 stdin 读取阶段章节文本,退出 0(找到 UI)或 1(未找到 UI);也部署到 `msd-core/bin/lib/`,以便 MSD 安装程序将其传送到 `$RUNTIME_DIR`(#448) |
| `update-context.cjs` | `/msd-update` 的纯安装上下文解析器 — 从 update.md bash 移植的运行时/范围/配置目录/版本检测(LOCAL/GLOBAL/UNKNOWN);支持 `msd-tools update-context`(#498) |
| `validate-command-router.cjs` | `msd-tools validate` 的轻量 CJS 子命令路由适配器 |
| `validate.cjs` | 纯阶段变体规范化帮助器(`phaseVariants`、`buildRoadmapPhaseVariants`、`buildNotStartedPhaseVariants`),被 `verify.cjs` 用于 W006/W007 检查;无 I/O,无异步 |
| `verify-command-router.cjs` | `gsd-tools verify` 的轻量 CJS 子命令路由适配器 |
| `verify-command-router.cjs` | `msd-tools verify` 的轻量 CJS 子命令路由适配器 |
| `verify.cjs` | 计划结构、阶段完整性、参考、提交验证 |
| `workstream-inventory-builder.cjs` | 纯工作流清单投影构建器 |
| `workstream-inventory.cjs` | 共享工作流清单投影:状态字段、阶段/计划/摘要计数、路线图阶段计数和活跃标记 — 将纯投影委托给 `workstream-inventory-builder.cjs` 的轻量编排器 |
@@ -464,23 +464,23 @@
| 钩子 | 事件 | 目的 |
|------|------|------|
| `gsd-statusline.js` | `statusLine` | 显示模型、任务、目录、上下文使用情况 |
| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | 在剩余 35%/25% 时注入面向代理的上下文警告 |
| `gsd-check-update.js` | `SessionStart` | 后台检查新的 GSD 版本 |
| `gsd-check-update-worker.js` | (工作进程) | check-update 的后台工作进程帮助器 |
| `gsd-update-banner.js` | `SessionStart` | 当未使用 GSD statusline 时选择性地显示更新可用横幅(PR #2795) |
| `gsd-prompt-guard.js` | `PreToolUse` | 扫描 `.planning/` 写入中的提示注入模式(建议性) |
| `gsd-workflow-guard.js` | `PreToolUse` | 检测 GSD 工作流上下文之外的文件编辑(建议性,可选启用) |
| `gsd-read-guard.js` | `PreToolUse` | 防止对未读文件执行 Edit/Write 的建议性守卫 |
| `gsd-read-injection-scanner.js` | `PostToolUse` | 扫描工具 Read 结果中的提示注入模式(v1.36+,PR #2201) |
| `gsd-worktree-path-guard.js` | `PreToolUse` | 硬性阻止对 worktree 根目录之外绝对路径执行 Edit/Write/MultiEdit(PR #579,#260) |
| `gsd-agent-isolation-guard.js` | `PreToolUse` | 当项目解析出的调度隔离模式为 `harness-worktree` 时,硬性阻止缺少隔离参数的 executor `Agent()` 调度(#3045) |
| `gsd-write-guard.js` | `PreToolUse` | 硬性阻止将精选的 `.planning/` 工件(ROADMAP.md、里程碑路线图、STATE.md)灾难性缩减的整文件 `Write`;可通过一次性哨兵文件 `.planning/.gsd-allow-shrink`(工作流步骤)或 `GSD_ALLOW_PLANNING_SHRINK=1`(交互式)覆盖(#2255,#973 的修复 3) |
| `gsd-secret-read-guard.js` | `PreToolUse` | 硬性阻止通过 Read / Grep / Bash 读取 `.env`、`.env.<suffix>`(`.env.example` 等模板除外)和 `.secrets`;取代安装程序以前写入的 `Read(.env*)` 拒绝规则(#4221) |
| `gsd-session-state.sh` | `SessionStart` | 基于 shell 运行时的会话状态跟踪 |
| `gsd-validate-commit.sh` | `PreToolUse` | 常规提交强制执行的提交验证 |
| `gsd-phase-boundary.sh` | `PostToolUse` | 工作流过渡的阶段边界检测 |
| `gsd-graphify-update.sh` | `PostToolUse` | 在主 HEAD 推进后自动重建知识图谱(可选启用,默认关闭 — #3347) |
| `msd-statusline.js` | `statusLine` | 显示模型、任务、目录、上下文使用情况 |
| `msd-context-monitor.js` | `PostToolUse` / `AfterTool` | 在剩余 35%/25% 时注入面向代理的上下文警告 |
| `msd-check-update.js` | `SessionStart` | 后台检查新的 MSD 版本 |
| `msd-check-update-worker.js` | (工作进程) | check-update 的后台工作进程帮助器 |
| `msd-update-banner.js` | `SessionStart` | 当未使用 MSD statusline 时选择性地显示更新可用横幅(PR #2795) |
| `msd-prompt-guard.js` | `PreToolUse` | 扫描 `.planning/` 写入中的提示注入模式(建议性) |
| `msd-workflow-guard.js` | `PreToolUse` | 检测 MSD 工作流上下文之外的文件编辑(建议性,可选启用) |
| `msd-read-guard.js` | `PreToolUse` | 防止对未读文件执行 Edit/Write 的建议性守卫 |
| `msd-read-injection-scanner.js` | `PostToolUse` | 扫描工具 Read 结果中的提示注入模式(v1.36+,PR #2201) |
| `msd-worktree-path-guard.js` | `PreToolUse` | 硬性阻止对 worktree 根目录之外绝对路径执行 Edit/Write/MultiEdit(PR #579,#260) |
| `msd-agent-isolation-guard.js` | `PreToolUse` | 当项目解析出的调度隔离模式为 `harness-worktree` 时,硬性阻止缺少隔离参数的 executor `Agent()` 调度(#3045) |
| `msd-write-guard.js` | `PreToolUse` | 硬性阻止将精选的 `.planning/` 工件(ROADMAP.md、里程碑路线图、STATE.md)灾难性缩减的整文件 `Write`;可通过一次性哨兵文件 `.planning/.msd-allow-shrink`(工作流步骤)或 `MSD_ALLOW_PLANNING_SHRINK=1`(交互式)覆盖(#2255,#973 的修复 3) |
| `msd-secret-read-guard.js` | `PreToolUse` | 硬性阻止通过 Read / Grep / Bash 读取 `.env`、`.env.<suffix>`(`.env.example` 等模板除外)和 `.secrets`;取代安装程序以前写入的 `Read(.env*)` 拒绝规则(#4221) |
| `msd-session-state.sh` | `SessionStart` | 基于 shell 运行时的会话状态跟踪 |
| `msd-validate-commit.sh` | `PreToolUse` | 常规提交强制执行的提交验证 |
| `msd-phase-boundary.sh` | `PostToolUse` | 工作流过渡的阶段边界检测 |
| `msd-graphify-update.sh` | `PostToolUse` | 在主 HEAD 推进后自动重建知识图谱(可选启用,默认关闭 — #3347) |
---

View File

@@ -1,4 +1,4 @@
# GSD Core 文档
# MSD Core 文档
文档按四个象限组织:**教程**通过实践帮助你学习,**操作指南**解决具体任务,**参考文档**提供权威信息,**概念说明**探讨设计理念与决策。
@@ -9,7 +9,7 @@
## Tutorials
- [第一个项目](tutorials/your-first-project.md) — 从安装到首个已交付阶段,一条有保障的路径
- [接入现有代码库](tutorials/onboarding-an-existing-codebase.md) — 将 GSD Core 引入已有项目的代码库
- [接入现有代码库](tutorials/onboarding-an-existing-codebase.md) — 将 MSD Core 引入已有项目的代码库
---
@@ -21,17 +21,17 @@
- [执行一个阶段](how-to/execute-a-phase.md) — 使用全新上下文的子代理以并行波次运行计划
- [验证并交付](how-to/verify-and-ship.md) — 审查已完成的工作、诊断失败并创建 PR
- [自主运行阶段](how-to/run-phases-autonomously.md) — 使用自主模式进行无人值守的阶段执行
- [处理快速临时任务](how-to/handle-quick-and-fast-tasks.md) — 使用 `/gsd-quick` 和 `/gsd-fast` 处理阶段循环之外的临时工作
- [处理快速临时任务](how-to/handle-quick-and-fast-tasks.md) — 使用 `/msd-quick` 和 `/msd-fast` 处理阶段循环之外的临时工作
- [配置模型配置文件](how-to/configure-model-profiles.md) — 在高质量、均衡和经济模型层级之间切换
- [设置跨 AI 审查](how-to/set-up-cross-ai-review.md) — 配置第二个 AI 对主代理生成的代码进行审查
- [使用工作流并行工作](how-to/work-in-parallel-with-workstreams.md) — 使用工作流同时运行独立的工作线
- [使用工作空间隔离工作](how-to/isolate-work-with-workspaces.md) — 使用工作空间对实验性或高风险变更进行沙箱隔离
- [调试失败的执行](how-to/debug-a-failed-execution.md) — 诊断并从中断或不完整的阶段执行中恢复
- [探索与草图](how-to/spike-and-sketch.md) — 在提交计划之前,使用 `/gsd-spike` 和 `/gsd-sketch` 进行探索性工作
- [探索与草图](how-to/spike-and-sketch.md) — 在提交计划之前,使用 `/msd-spike` 和 `/msd-sketch` 进行探索性工作
- [设计 UI 阶段](how-to/design-a-ui-phase.md) — 使用 UI 阶段循环处理前端和视觉工作
- [从追踪器 Issue 驱动 GSD](how-to/drive-gsd-from-a-tracker-issue.md) — 从 GitHub、Linear 或 Jira issue 启动一个阶段
- [从 GSD 2 迁移](how-to/migrate-from-gsd-2.md) — 将现有的 GSD 2 项目升级到 GSD Core
- [更新 GSD](how-to/update-gsd.md) — 重新运行安装程序以获取最新版本
- [从追踪器 Issue 驱动 MSD](how-to/drive-msd-from-a-tracker-issue.md) — 从 GitHub、Linear 或 Jira issue 启动一个阶段
- [从 GSD 2 迁移](how-to/migrate-from-gsd-2.md) — 将现有的 GSD 2 项目升级到 MSD Core
- [更新 MSD](how-to/update-msd.md) — 重新运行安装程序以获取最新版本
- [恢复与故障排查](how-to/recover-and-troubleshoot.md) — 修复常见问题、重建上下文并卸载
---
@@ -40,7 +40,7 @@
- [命令](COMMANDS.md) — 每个命令的标志和示例
- [配置](CONFIGURATION.md) — 完整配置模式、模型配置文件、Git 分支策略
- [CLI 工具](CLI-TOOLS.md) — `gsd-tools.cjs` 用于工作流和代理的编程式 API
- [CLI 工具](CLI-TOOLS.md) — `msd-tools.cjs` 用于工作流和代理的编程式 API
- [功能特性](FEATURES.md) — 完整功能索引
- [清单](INVENTORY.md) — 已安装的技能与界面映射
- [STATE.md 模式](reference/state-md.md) — `.planning/STATE.md` 的逐字段参考
@@ -52,14 +52,14 @@
## Explanation
- [上下文工程](explanation/context-engineering.md) — 上下文腐化如何形成,以及 GSD Core 如何防止它
- [上下文工程](explanation/context-engineering.md) — 上下文腐化如何形成,以及 MSD Core 如何防止它
- [阶段循环](explanation/the-phase-loop.md) — 讨论 → 规划 → 执行 → 验证 → 交付循环的设计原理
- [多代理编排](explanation/multi-agent-orchestration.md) — 子代理的生成、范围界定和协调方式
- [安全模型](explanation/security-model.md) — 信任边界、权限和安全自动化
- [架构](ARCHITECTURE.md) — 系统架构、代理模型和数据流
- [讨论模式](workflow-discuss-mode.md) — `/gsd-discuss-phase` 的假设模式与访谈模式
- [讨论模式](workflow-discuss-mode.md) — `/msd-discuss-phase` 的假设模式与访谈模式
- [上下文监控](context-monitor.md) — 上下文窗口监控钩子架构
- [Issue 驱动编排](issue-driven-orchestration.md) — 使用现有原语从追踪器 issue 驱动 GSD 的方案
- [Issue 驱动编排](issue-driven-orchestration.md) — 使用现有原语从追踪器 issue 驱动 MSD 的方案
---

View File

@@ -1,8 +1,8 @@
# GSD 用户指南
# MSD 用户指南
GSD Core 的叙述性辅助指南——从这里开始了解系统全貌,然后按链接进入各专项文档。
MSD Core 的叙述性辅助指南——从这里开始了解系统全貌,然后按链接进入各专项文档。
> **GSD Core 的文档按照 [Diataxis](https://diataxis.fr) 框架组织。**
> **MSD Core 的文档按照 [Diataxis](https://diataxis.fr) 框架组织。**
> 按目标浏览:[教程](README.md#tutorials) · [操作指南](README.md#how-to-guides) · [参考手册](README.md#reference) · [说明](README.md#explanation) · [文档索引](README.md)
---
@@ -10,7 +10,7 @@ GSD Core 的叙述性辅助指南——从这里开始了解系统全貌,然
## 目录
- [斜杠命令形式](#slash-command-forms-hyphen-vs-colon)
- [命名空间路由入门](#namespace-routing-primer-gsdnamespace-v140)
- [命名空间路由入门](#namespace-routing-primer-msdnamespace-v140)
- [项目生命周期概览](#project-lifecycle-overview)
- [工作流程图](#workflow-diagrams)
- [UI 设计契约](#ui-design-contract)
@@ -24,40 +24,40 @@ GSD Core 的叙述性辅助指南——从这里开始了解系统全貌,然
- [项目文件结构](#project-file-structure)
- [相关资源](#related)
如需从 GitHub / Linear / Jira issue 直接驱动 GSD,请参阅
如需从 GitHub / Linear / Jira issue 直接驱动 MSD,请参阅
[issue-driven-orchestration](issue-driven-orchestration.md) 指南——该指南将跟踪器 issue
映射到工作区 → 讨论 → 计划 → 执行 → 验证 → 审查 → 发布的循环,使用现有的 GSD 基础功能实现。
映射到工作区 → 讨论 → 计划 → 执行 → 验证 → 审查 → 发布的循环,使用现有的 MSD 基础功能实现。
---
## 斜杠命令形式 {#slash-command-forms-hyphen-vs-colon}
GSD 向所有支持的运行时提供**同一套技能**,使用连字符形式的斜杠拼写:
MSD 向所有支持的运行时提供**同一套技能**,使用连字符形式的斜杠拼写:
- **连字符形式** — `/gsd-command-name` — 供 Claude Code、Copilot、OpenCode、Kilo、Cursor、Windsurf、Augment、Antigravity 和 Trae 使用。
- **连字符形式** — `/msd-command-name` — 供 Claude Code、Copilot、OpenCode、Kilo、Cursor、Windsurf、Augment、Antigravity 和 Trae 使用。
安装器会将此形式写入您所针对的每个运行时的命令目录。
## 命名空间路由入门(`gsd:<namespace>`,v1.40)
## 命名空间路由入门(`msd:<namespace>`,v1.40)
v1.40 提供了六个**命名空间元技能**,作为分层路由的第一阶段入口——它们将贪婪技能列举的 token 成本保持在较低水平(6 个路由器约 120 个 token,而扁平列举 86 个技能约需 2,150 个 token),同时每个具体子技能仍可直接调用。每个命名空间路由器的正文包含一张路由表,将您的意图映射到正确的具体子技能。
| 命名空间 | 路由器 | 路由目标 |
|-----------|--------|-----------|
| 阶段流水线 | `/gsd-workflow` | discuss / plan / execute / verify / phase / progress |
| 项目生命周期 | `/gsd-project` | milestones, audits, summary |
| 质量关卡 | `/gsd-quality` | code review, debug, audit, security, eval, ui |
| 代码库情报 | `/gsd-context` | map, graphify, docs, learnings |
| 管理 | `/gsd-manage` | config, workspace, workstreams, thread, update, ship, inbox |
| 探索与捕获 | `/gsd-ideate` | explore, sketch, spike, spec, capture |
| 阶段流水线 | `/msd-workflow` | discuss / plan / execute / verify / phase / progress |
| 项目生命周期 | `/msd-project` | milestones, audits, summary |
| 质量关卡 | `/msd-quality` | code review, debug, audit, security, eval, ui |
| 代码库情报 | `/msd-context` | map, graphify, docs, learnings |
| 管理 | `/msd-manage` | config, workspace, workstreams, thread, update, ship, inbox |
| 探索与捕获 | `/msd-ideate` | explore, sketch, spike, spec, capture |
您几乎不需要亲自输入命名空间路由器。它们的价值在于为模型提供发现正确子技能的路由层——其存在使系统提示只需列出 6 条而非 86 条。如果您已经知道具体命令(例如 `/gsd-plan-phase`),可直接调用。
您几乎不需要亲自输入命名空间路由器。它们的价值在于为模型提供发现正确子技能的路由层——其存在使系统提示只需列出 6 条而非 86 条。如果您已经知道具体命令(例如 `/msd-plan-phase`),可直接调用。
---
## 项目生命周期概览
GSD 核心循环为:**discuss → plan → execute → verify → ship**,每个阶段重复一次。包括示例输出、创建哪些文件以及所有生效标志的完整逐步演练,请参阅专项教程。
MSD 核心循环为:**discuss → plan → execute → verify → ship**,每个阶段重复一次。包括示例输出、创建哪些文件以及所有生效标志的完整逐步演练,请参阅专项教程。
参见 [您的第一个项目](tutorials/your-first-project.md)。
@@ -67,12 +67,12 @@ GSD 核心循环为:**discuss → plan → execute → verify → ship**,每
| 标志 | 命令 | 使用场景 |
| ---- | ------- | ----------- |
| `--auto` | `/gsd-new-project` | 跳过交互式问题,从 PRD 文件导入 |
| `--research` | `/gsd-quick` | 为临时任务添加研究 Agent |
| `--validate` | `/gsd-quick` | 添加计划检查和执行后验证 |
| `--chain` | `/gsd-discuss-phase` | 自动链式运行 discuss → plan → execute 而不中断 |
| `--skip-research` | `/gsd-plan-phase` | 在领域已熟悉时跳过研究 Agent |
| `--draft` | `/gsd-ship` | 创建草稿 PR 而非待审查 PR |
| `--auto` | `/msd-new-project` | 跳过交互式问题,从 PRD 文件导入 |
| `--research` | `/msd-quick` | 为临时任务添加研究 Agent |
| `--validate` | `/msd-quick` | 添加计划检查和执行后验证 |
| `--chain` | `/msd-discuss-phase` | 自动链式运行 discuss → plan → execute 而不中断 |
| `--skip-research` | `/msd-plan-phase` | 在领域已熟悉时跳过研究 Agent |
| `--draft` | `/msd-ship` | 创建草稿 PR 而非待审查 PR |
完整命令参考(含所有标志)请参阅 [`docs/COMMANDS.md`](COMMANDS.md)。配置选项(模型配置文件、工作流 Agent、git 分支策略)请参阅 [`docs/CONFIGURATION.md`](CONFIGURATION.md)。
@@ -85,7 +85,7 @@ GSD 核心循环为:**discuss → plan → execute → verify → ship**,每
```text
┌──────────────────────────────────────────────────┐
│ NEW PROJECT │
│ /gsd-new-project │
│ /msd-new-project │
│ Questions -> Research -> Requirements -> Roadmap│
└─────────────────────────┬────────────────────────┘
│
@@ -93,27 +93,27 @@ GSD 核心循环为:**discuss → plan → execute → verify → ship**,每
│ FOR EACH PHASE: │
│ │
│ ┌────────────────────┐ │
│ │ /gsd-discuss-phase │ │ <- Lock in preferences
│ │ /msd-discuss-phase │ │ <- Lock in preferences
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-ui-phase │ │ <- Design contract (frontend)
│ │ /msd-ui-phase │ │ <- Design contract (frontend)
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-plan-phase │ │ <- Research + Plan + Verify
│ │ /msd-plan-phase │ │ <- Research + Plan + Verify
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-execute-phase │ │ <- Parallel execution
│ │ /msd-execute-phase │ │ <- Parallel execution
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-verify-work │ │ <- Manual UAT
│ │ /msd-verify-work │ │ <- Manual UAT
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-ship │ │ <- Create PR (optional)
│ │ /msd-ship │ │ <- Create PR (optional)
│ └──────────┬─────────┘ │
│ │ │
│ Next Phase?────────────┘
@@ -121,8 +121,8 @@ GSD 核心循环为:**discuss → plan → execute → verify → ship**,每
└─────────────┼──────────────┘
│
┌───────────────▼──────────────┐
│ /gsd-audit-milestone │
│ /gsd-complete-milestone │
│ /msd-audit-milestone │
│ /msd-complete-milestone │
└───────────────┬──────────────┘
│
Another milestone?
@@ -130,14 +130,14 @@ GSD 核心循环为:**discuss → plan → execute → verify → ship**,每
Yes No -> Done!
│
┌───────▼──────────────┐
│ /gsd-new-milestone │
│ /msd-new-milestone │
└──────────────────────┘
```
### 计划 Agent 协调
```text
/gsd-plan-phase N
/msd-plan-phase N
│
├── Phase Researcher (x4 parallel)
│ ├── Stack researcher
@@ -170,18 +170,18 @@ GSD 核心循环为:**discuss → plan → execute → verify → ship**,每
### 验证架构(奈奎斯特层)
在计划阶段研究期间,GSD 会在编写任何代码之前将自动化测试覆盖率映射到每个阶段的需求上。研究者会检测您现有的测试基础设施,将每个需求映射到特定的测试命令,并识别在实施开始前必须创建的测试脚手架(Wave 0 任务)。计划检查器将此作为第 8 个验证维度执行:缺少自动化验证命令的任务计划将不会被批准。
在计划阶段研究期间,MSD 会在编写任何代码之前将自动化测试覆盖率映射到每个阶段的需求上。研究者会检测您现有的测试基础设施,将每个需求映射到特定的测试命令,并识别在实施开始前必须创建的测试脚手架(Wave 0 任务)。计划检查器将此作为第 8 个验证维度执行:缺少自动化验证命令的任务计划将不会被批准。
**输出:** `{phase}-VALIDATION.md` — 阶段的反馈契约。
**禁用:** 在 `/gsd-settings` 中将 `workflow.nyquist_validation: false` 设置为 false,适用于测试基础设施不是重点的快速原型阶段。
**禁用:** 在 `/msd-settings` 中将 `workflow.nyquist_validation: false` 设置为 false,适用于测试基础设施不是重点的快速原型阶段。
### 追溯验证(`/gsd-validate-phase`)
### 追溯验证(`/msd-validate-phase`)
对于在奈奎斯特验证出现之前执行的阶段,或仅有传统测试套件的现有代码库,可追溯审计并填补覆盖缺口:
```text
/gsd-validate-phase N
/msd-validate-phase N
|
+-- Detect state (VALIDATION.md exists? SUMMARY.md exists?)
|
@@ -203,9 +203,9 @@ GSD 核心循环为:**discuss → plan → execute → verify → ship**,每
### 假设讨论模式
默认情况下,`/gsd-discuss-phase` 会就您的实现偏好提出开放性问题。假设模式将此倒转:GSD 首先读取您的代码库,提出关于如何构建该阶段的结构化假设,然后仅就修正内容提问。
默认情况下,`/msd-discuss-phase` 会就您的实现偏好提出开放性问题。假设模式将此倒转:MSD 首先读取您的代码库,提出关于如何构建该阶段的结构化假设,然后仅就修正内容提问。
**启用:** 通过 `/gsd-settings` 将 `workflow.discuss_mode` 设置为 `'assumptions'`。
**启用:** 通过 `/msd-settings` 将 `workflow.discuss_mode` 设置为 `'assumptions'`。
完整的讨论模式参考请参阅 [docs/workflow-discuss-mode.md](workflow-discuss-mode.md)。
@@ -213,18 +213,18 @@ GSD 核心循环为:**discuss → plan → execute → verify → ship**,每
讨论阶段将实现决策以编号项(`- **D-01:** …`)的形式捕获到 CONTEXT.md 的 `<decisions>` 块中。两个关卡确保这些决策能延续到计划和交付代码中。
**计划阶段转换关卡(阻塞)。** 计划完成后,GSD 会拒绝将阶段标记为已计划,直到每个可跟踪决策出现在至少一个计划的 `must_haves`、`truths` 或正文中。
**计划阶段转换关卡(阻塞)。** 计划完成后,MSD 会拒绝将阶段标记为已计划,直到每个可跟踪决策出现在至少一个计划的 `must_haves`、`truths` 或正文中。
**验证阶段验证关卡(非阻塞)。** 在验证期间,GSD 会在计划、SUMMARY.md、修改文件和最近提交消息中搜索每个可跟踪决策。遗漏项以警告章节的形式记录到 VERIFICATION.md;验证状态不变。
**验证阶段验证关卡(非阻塞)。** 在验证期间,MSD 会在计划、SUMMARY.md、修改文件和最近提交消息中搜索每个可跟踪决策。遗漏项以警告章节的形式记录到 VERIFICATION.md;验证状态不变。
**将决策排除在外。** 将其移至 `<decisions>` 内的 `### Claude's Discretion` 标题下,或添加标签:`- **D-08 [informational]:** …`、`- **D-09 [folded]:** …`、`- **D-10 [deferred]:** …`。
**禁用关卡。** 在 `.planning/config.json` 中设置 `workflow.context_coverage_gate: false`(或通过 `/gsd-settings`)。默认值为 `true`。
**禁用关卡。** 在 `.planning/config.json` 中设置 `workflow.context_coverage_gate: false`(或通过 `/msd-settings`)。默认值为 `true`。
### 执行波次协调
```text
/gsd-execute-phase N
/msd-execute-phase N
│
├── Analyze plan dependencies
│
@@ -240,14 +240,14 @@ GSD 核心循环为:**discuss → plan → execute → verify → ship**,每
├── Test quality audit (disabled tests, circular patterns, assertion strength)
│
├── PASS -> VERIFICATION.md (success)
└── FAIL -> Issues logged for /gsd-verify-work
└── FAIL -> Issues logged for /msd-verify-work
```
---
## UI 设计契约
AI 生成的前端在视觉上不一致,原因不在于 Claude Code 在 UI 方面能力不足,而在于执行前没有建立设计契约。`/gsd-ui-phase` 在计划前锁定设计契约;`/gsd-ui-review` 在执行后审计结果。
AI 生成的前端在视觉上不一致,原因不在于 Claude Code 在 UI 方面能力不足,而在于执行前没有建立设计契约。`/msd-ui-phase` 在计划前锁定设计契约;`/msd-ui-review` 在执行后审计结果。
完整工作流、配置、shadcn 初始化以及注册表安全关卡,请参阅 [设计 UI 阶段](how-to/design-a-ui-phase.md)。
@@ -255,33 +255,33 @@ AI 生成的前端在视觉上不一致,原因不在于 Claude Code 在 UI 方
| 命令 | 描述 |
| -------------------- | -------------------------------------------------------- |
| `/gsd-ui-phase [N]` | 为前端阶段生成 UI-SPEC.md 设计契约 |
| `/gsd-ui-review [N]` | 对已实现 UI 进行追溯性六维视觉审计 |
| `/msd-ui-phase [N]` | 为前端阶段生成 UI-SPEC.md 设计契约 |
| `/msd-ui-review [N]` | 对已实现 UI 进行追溯性六维视觉审计 |
| 设置 | 默认值 | 描述 |
| ------------------------- | ------- | ----------------------------------------------------------- |
| `workflow.ui_phase` | `true` | 为前端阶段生成 UI 设计契约 |
| `workflow.ui_safety_gate` | `true` | 计划阶段提示为前端阶段运行 /gsd-ui-phase |
| `workflow.ui_safety_gate` | `true` | 计划阶段提示为前端阶段运行 /msd-ui-phase |
---
## 探针与草图
使用 `/gsd-spike` 在计划前验证技术可行性,使用 `/gsd-sketch` 在设计前探索视觉方向。两者均将产物存储在 `.planning/` 中,并通过其配套的收尾工具与项目技能系统集成。
使用 `/msd-spike` 在计划前验证技术可行性,使用 `/msd-sketch` 在设计前探索视觉方向。两者均将产物存储在 `.planning/` 中,并通过其配套的收尾工具与项目技能系统集成。
完整工作流和流程图请参阅 [探针与草图](how-to/spike-and-sketch.md)。
**典型流程:**
```bash
/gsd-spike "SSE vs WebSocket" # Validate the approach
/gsd-spike --wrap-up # Package learnings
/msd-spike "SSE vs WebSocket" # Validate the approach
/msd-spike --wrap-up # Package learnings
/gsd-sketch "real-time feed UI" # Explore the design
/gsd-sketch --wrap-up # Package decisions
/msd-sketch "real-time feed UI" # Explore the design
/msd-sketch --wrap-up # Package decisions
/gsd-discuss-phase N # Lock in preferences (now informed by spike + sketch)
/gsd-plan-phase N # Plan with confidence
/msd-discuss-phase N # Lock in preferences (now informed by spike + sketch)
/msd-plan-phase N # Plan with confidence
```
---
@@ -293,35 +293,35 @@ AI 生成的前端在视觉上不一致,原因不在于 Claude Code 在 UI 方
尚未准备好进入主动计划的想法使用 999.x 编号进入待办事项,保持在活跃阶段序列之外。
```bash
/gsd-capture --backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
/gsd-capture --backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
/msd-capture --backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
/msd-capture --backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
```
待办事项获得完整的阶段目录,因此您可以使用 `/gsd-discuss-phase 999.1` 进一步探索某个想法,或在准备好时使用 `/gsd-plan-phase 999.1`。
待办事项获得完整的阶段目录,因此您可以使用 `/msd-discuss-phase 999.1` 进一步探索某个想法,或在准备好时使用 `/msd-plan-phase 999.1`。
**审查和提升**使用 `/gsd-review-backlog`——它显示所有待办事项,并让您选择提升(移至活跃序列)、保留(留在待办事项中)或移除(删除)。
**审查和提升**使用 `/msd-review-backlog`——它显示所有待办事项,并让您选择提升(移至活跃序列)、保留(留在待办事项中)或移除(删除)。
### 种子
种子是带有触发条件的前瞻性想法。与待办事项不同,种子会在正确的里程碑到来时自动浮现。
```bash
/gsd-capture --seed "Add real-time collab when WebSocket infra is in place"
/msd-capture --seed "Add real-time collab when WebSocket infra is in place"
```
`/gsd-new-milestone` 会扫描所有种子并呈现匹配项。**存储位置:** `.planning/seeds/SEED-NNN-slug.md`
`/msd-new-milestone` 会扫描所有种子并呈现匹配项。**存储位置:** `.planning/seeds/SEED-NNN-slug.md`
### 持久上下文线程
线程是轻量级的跨会话知识存储,用于跨多个会话但不属于任何特定阶段的工作。
```bash
/gsd-thread # List all threads
/gsd-thread fix-deploy-key-auth # Resume existing thread
/gsd-thread "Investigate TCP timeout" # Create new thread
/msd-thread # List all threads
/msd-thread fix-deploy-key-auth # Resume existing thread
/msd-thread "Investigate TCP timeout" # Create new thread
```
线程成熟后可提升为阶段(`/gsd-phase`)或待办事项(`/gsd-capture --backlog`)。**存储位置:** `.planning/threads/{slug}.md`
线程成熟后可提升为阶段(`/msd-phase`)或待办事项(`/msd-capture --backlog`)。**存储位置:** `.planning/threads/{slug}.md`
---
@@ -335,19 +335,19 @@ AI 生成的前端在视觉上不一致,原因不在于 Claude Code 在 UI 方
| 命令 | 用途 |
| ---------------------------------- | ---------------------------------------------------- |
| `/gsd-workstreams create <name>` | 创建具有隔离计划状态的新工作流 |
| `/gsd-workstreams switch <name>` | 将活跃上下文切换到不同的工作流 |
| `/gsd-workstreams list` | 显示所有工作流及当前活跃的工作流 |
| `/gsd-workstreams complete <name>` | 将工作流标记为完成并归档其状态 |
| `/msd-workstreams create <name>` | 创建具有隔离计划状态的新工作流 |
| `/msd-workstreams switch <name>` | 将活跃上下文切换到不同的工作流 |
| `/msd-workstreams list` | 显示所有工作流及当前活跃的工作流 |
| `/msd-workstreams complete <name>` | 将工作流标记为完成并归档其状态 |
```bash
# Workspace example — feature branch isolation
/gsd-workspace --new --name feature-b --repos .
cd ~/gsd-workspaces/feature-b
/gsd-new-project
/msd-workspace --new --name feature-b --repos .
cd ~/msd-workspaces/feature-b
/msd-new-project
/gsd-workspace --list
/gsd-workspace --remove feature-b
/msd-workspace --list
/msd-workspace --remove feature-b
```
---
@@ -356,7 +356,7 @@ cd ~/gsd-workspaces/feature-b
### 纵深防御(v1.27)
GSD 生成的 Markdown 文件会成为 LLM 系统提示。这意味着流入规划产物的任何用户控制文本都是潜在的间接提示注入向量。v1.27 引入了集中式安全加固:
MSD 生成的 Markdown 文件会成为 LLM 系统提示。这意味着流入规划产物的任何用户控制文本都是潜在的间接提示注入向量。v1.27 引入了集中式安全加固:
**路径遍历防护:** 所有用户提供的文件路径(`--text-file`、`--prd`)均经过验证,确保解析在项目目录内。macOS 的 `/var` → `/private/var` 符号链接解析已处理。
@@ -364,8 +364,8 @@ GSD 生成的 Markdown 文件会成为 LLM 系统提示。这意味着流入规
**运行时钩子:**
- `gsd-prompt-guard.js` — 扫描写入 `.planning/` 的 Write/Edit 调用中的注入模式(始终活跃,仅建议)
- `gsd-workflow-guard.js` — 对 GSD 工作流上下文之外的文件编辑发出警告(通过 `hooks.workflow_guard` 选择性启用)
- `msd-prompt-guard.js` — 扫描写入 `.planning/` 的 Write/Edit 调用中的注入模式(始终活跃,仅建议)
- `msd-workflow-guard.js` — 对 MSD 工作流上下文之外的文件编辑发出警告(通过 `hooks.workflow_guard` 选择性启用)
**CI 扫描器:** `prompt-injection-scan.security.test.cjs` 扫描所有 agent、工作流和命令文件中的嵌入式注入向量。
@@ -395,7 +395,7 @@ AI 编码工具会幻觉出包名。攻击者会在 npm、PyPI 和 crates.io 上
**合法性判定:**
| 判定 | 含义 | GSD 操作 |
| 判定 | 含义 | MSD 操作 |
|---------|---------|------------|
| `[OK]` | 通过所有合法性检查 | 继续——不添加检查点 |
| `[SUS]` | 存在可疑信号 | 标记;规划器添加 `checkpoint:human-verify` |
@@ -415,17 +415,17 @@ pip install slopcheck
执行阶段后,在 UAT 前进行结构化代码审查。完整工作流请参阅 [设置跨 AI 审查](how-to/set-up-cross-ai-review.md)。
```bash
/gsd-code-review 3 # Review all changed files in phase 3
/gsd-code-review 3 --depth=deep # Deep cross-file review
/gsd-code-review 3 --fix # Fix Critical + Warning findings atomically
/gsd-code-review 3 --fix --auto # Fix and re-review until clean (max 3 iterations)
/gsd-audit-fix # Audit + classify + fix (medium+ severity, max 5)
/msd-code-review 3 # Review all changed files in phase 3
/msd-code-review 3 --depth=deep # Deep cross-file review
/msd-code-review 3 --fix # Fix Critical + Warning findings atomically
/msd-code-review 3 --fix --auto # Fix and re-review until clean (max 3 iterations)
/msd-audit-fix # Audit + classify + fix (medium+ severity, max 5)
```
审查步骤插入在执行之后、UAT 之前:
```text
/gsd-execute-phase N -> /gsd-code-review N -> /gsd-code-review N --fix -> /gsd-verify-work N
/msd-execute-phase N -> /msd-code-review N -> /msd-code-review N --fix -> /msd-verify-work N
```
---
@@ -444,26 +444,26 @@ pip install slopcheck
```bash
claude --dangerously-skip-permissions
/gsd-new-project # Answer questions, configure, approve roadmap
/msd-new-project # Answer questions, configure, approve roadmap
/clear
/gsd-discuss-phase 1 # Lock in your preferences
/gsd-ui-phase 1 # Design contract (frontend phases)
/gsd-plan-phase 1 # Research + plan + verify
/gsd-execute-phase 1 # Parallel execution
/gsd-verify-work 1 # Manual UAT
/gsd-ship 1 # Create PR from verified work
/gsd-ui-review 1 # Visual audit (frontend phases)
/msd-discuss-phase 1 # Lock in your preferences
/msd-ui-phase 1 # Design contract (frontend phases)
/msd-plan-phase 1 # Research + plan + verify
/msd-execute-phase 1 # Parallel execution
/msd-verify-work 1 # Manual UAT
/msd-ship 1 # Create PR from verified work
/msd-ui-review 1 # Visual audit (frontend phases)
/clear
/gsd-progress --next # Auto-detect and run next step
/msd-progress --next # Auto-detect and run next step
...
/gsd-audit-milestone # Check everything shipped
/gsd-complete-milestone # Archive, tag, done
/gsd-pause-work --report # Generate session summary
/msd-audit-milestone # Check everything shipped
/msd-complete-milestone # Archive, tag, done
/msd-pause-work --report # Generate session summary
```
> [!CAUTION]
> **The permissions flag is optional.** It skips per-file confirmation while
> GSD's sub-agents read and write files. Use it only in low-stakes or
> MSD's sub-agents read and write files. Use it only in low-stakes or
> throwaway contexts. To keep confirmations enabled, start with `claude` instead.
> For real work, read the [security model](../explanation/security-model.md) first.
@@ -471,24 +471,24 @@ claude --dangerously-skip-permissions
### 从现有文档新建项目
```bash
/gsd-new-project --auto @prd.md # Auto-runs research/requirements/roadmap from your doc
/msd-new-project --auto @prd.md # Auto-runs research/requirements/roadmap from your doc
/clear
/gsd-discuss-phase 1 # Normal flow from here
/msd-discuss-phase 1 # Normal flow from here
```
### 现有代码库
```bash
/gsd-onboard # Safely map, ingest docs, and initialize planning
# Follow printed handoff commands, then rerun /gsd-onboard
/msd-onboard # Safely map, ingest docs, and initialize planning
# Follow printed handoff commands, then rerun /msd-onboard
# (normal phase workflow from here)
```
**执行后漂移检测(#2003)。** 每次 `/gsd-execute-phase` 之后,GSD 会检查该阶段是否引入了足够的结构变化,使 `.planning/codebase/STRUCTURE.md` 过时。通过以下方式调整行为:
**执行后漂移检测(#2003)。** 每次 `/msd-execute-phase` 之后,MSD 会检查该阶段是否引入了足够的结构变化,使 `.planning/codebase/STRUCTURE.md` 过时。通过以下方式调整行为:
```bash
/gsd-settings workflow.drift_action auto-remap # remap automatically
/gsd-settings workflow.drift_threshold 5 # tune sensitivity
/msd-settings workflow.drift_action auto-remap # remap automatically
/msd-settings workflow.drift_threshold 5 # tune sensitivity
```
### 计划漂移守卫
@@ -504,40 +504,40 @@ claude --dangerously-skip-permissions
**needs-acknowledgement 行为。** 当守卫发现缺失的符号时,它会在计划审查输出中发出 needs-acknowledgement 通知,而不是硬性阻塞。您可以确认并继续(该符号可能是有意新增的),或请求修改计划。守卫不会自动拒绝计划——它为人工决策提供信号。
**无需 intel 即可工作。** 默认情况下,守卫使用 `grep`/`ripgrep` 搜索源文件——无需预先索引。如果您已使用 `intel.enabled: true` 运行 `/gsd-map-codebase`,请将 `plan_review.source_grounding_authority: intel` 设置为使用更快的预构建 `api-map.json` 索引。
**无需 intel 即可工作。** 默认情况下,守卫使用 `grep`/`ripgrep` 搜索源文件——无需预先索引。如果您已使用 `intel.enabled: true` 运行 `/msd-map-codebase`,请将 `plan_review.source_grounding_authority: intel` 设置为使用更快的预构建 `api-map.json` 索引。
```bash
# Enable/disable (default: on)
/gsd-settings plan_review.source_grounding true
/gsd-settings plan_review.source_grounding false
/msd-settings plan_review.source_grounding true
/msd-settings plan_review.source_grounding false
# Switch resolver authority
/gsd-settings plan_review.source_grounding_authority grep # live grep (default)
/gsd-settings plan_review.source_grounding_authority intel # pre-indexed api-map.json
/msd-settings plan_review.source_grounding_authority grep # live grep (default)
/msd-settings plan_review.source_grounding_authority intel # pre-indexed api-map.json
```
在项目设置时切换(`/gsd-new-project` 在工作流偏好设置期间询问)或随时通过 `/gsd-settings`(计划部分 → 漂移守卫)切换。
在项目设置时切换(`/msd-new-project` 在工作流偏好设置期间询问)或随时通过 `/msd-settings`(计划部分 → 漂移守卫)切换。
### 快速修复 Bug
```bash
/gsd-quick
/msd-quick
> "Fix the login button not responding on mobile Safari"
```
### 休息后恢复工作
```bash
/gsd-progress # See where you left off and what's next
/msd-progress # See where you left off and what's next
# or
/gsd-resume-work # Full context restoration from last session
/msd-resume-work # Full context restoration from last session
```
### 准备发布
```bash
/gsd-audit-milestone # Check requirements coverage, detect stubs
/gsd-complete-milestone # Archive, tag, done
/msd-audit-milestone # Check requirements coverage, detect stubs
/msd-complete-milestone # Archive, tag, done
```
### 速度与质量预设
@@ -548,15 +548,15 @@ claude --dangerously-skip-permissions
| 常规开发 | `interactive` | `standard` | `balanced` | 开启 | 开启 | 开启 |
| 生产环境 | `interactive` | `fine` | `quality` | 开启 | 开启 | 开启 |
**在自主模式下跳过讨论阶段:** 以 `yolo` 模式运行时,通过 `/gsd-settings` 设置 `workflow.skip_discuss: true`。
**在自主模式下跳过讨论阶段:** 以 `yolo` 模式运行时,通过 `/msd-settings` 设置 `workflow.skip_discuss: true`。
### 里程碑中期范围变更
```bash
/gsd-phase # Append a new phase to the roadmap (default mode)
/gsd-phase --insert 3 # Insert urgent work between phases 3 and 4
/gsd-phase --remove 7 # Descope phase 7 and renumber
/gsd-phase --edit 4 # Edit any field of phase 4 in place
/msd-phase # Append a new phase to the roadmap (default mode)
/msd-phase --insert 3 # Insert urgent work between phases 3 and 4
/msd-phase --remove 7 # Descope phase 7 and renumber
/msd-phase --edit 4 # Edit any field of phase 4 in place
```
---
@@ -565,29 +565,29 @@ claude --dangerously-skip-permissions
完整的故障排查指南请参阅 [恢复与故障排查](how-to/recover-and-troubleshoot.md)。以下是最常见问题的摘要。
### 程序化 CLI(`gsd-tools query` 与 `gsd-tools.cjs`)
### 程序化 CLI(`msd-tools query` 与 `msd-tools.cjs`)
对于自动化,优先使用带有已注册子命令的 **`gsd-tools query`**(参见 [CLI-TOOLS.md — SDK 和程序化访问](CLI-TOOLS.md#sdk-and-programmatic-access) 及 QUERY-HANDLERS.md)。旧版 `node $HOME/.claude/gsd-core/bin/gsd-tools.cjs` CLI 仍受支持。
对于自动化,优先使用带有已注册子命令的 **`msd-tools query`**(参见 [CLI-TOOLS.md — SDK 和程序化访问](CLI-TOOLS.md#sdk-and-programmatic-access) 及 QUERY-HANDLERS.md)。旧版 `node $HOME/.claude/msd-core/bin/msd-tools.cjs` CLI 仍受支持。
### STATE.md 不同步
```bash
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state validate # Detect drift
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state sync --verify # Preview changes
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state sync # Reconstruct STATE.md
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state validate # Detect drift
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync --verify # Preview changes
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync # Reconstruct STATE.md
```
### 命令在"Spawning..."后似乎冻结
GSD 子 Agent 在单独的上下文窗口中运行——其工作在进行中对父会话不可见。请勿中断会话。等待结果;研究和计划 Agent 通常需要 1–5 分钟。
MSD 子 Agent 在单独的上下文窗口中运行——其工作在进行中对父会话不可见。请勿中断会话。等待结果;研究和计划 Agent 通常需要 1–5 分钟。
### 长会话期间上下文退化
在主要命令之间清除上下文窗口:在 Claude Code 中使用 `/clear`。GSD 围绕全新上下文设计——每个子 Agent 获得一个干净的 200K 窗口。清除后使用 `/gsd-resume-work` 或 `/gsd-progress` 恢复状态。
在主要命令之间清除上下文窗口:在 Claude Code 中使用 `/clear`。MSD 围绕全新上下文设计——每个子 Agent 获得一个干净的 200K 窗口。清除后使用 `/msd-resume-work` 或 `/msd-progress` 恢复状态。
### 计划似乎不正确或不一致
在计划前运行 `/gsd-discuss-phase [N]`。大多数计划质量问题来源于 Claude 在 `CONTEXT.md` 本可避免的情况下做出假设。
在计划前运行 `/msd-discuss-phase [N]`。大多数计划质量问题来源于 Claude 在 `CONTEXT.md` 本可避免的情况下做出假设。
### 执行失败或产生存根
@@ -595,11 +595,11 @@ GSD 子 Agent 在单独的上下文窗口中运行——其工作在进行中对
### 不知道当前位置
运行 `/gsd-progress`。它读取所有状态文件,精确告诉您当前所在位置和下一步操作。
运行 `/msd-progress`。它读取所有状态文件,精确告诉您当前所在位置和下一步操作。
### 模型成本过高
切换到预算配置文件:`/gsd-config --profile budget`。如果领域已熟悉,通过 `/gsd-settings` 禁用研究和计划检查 Agent。
切换到预算配置文件:`/msd-config --profile budget`。如果领域已熟悉,通过 `/msd-settings` 禁用研究和计划检查 Agent。
### 按阶段调整模型成本(`models`)——v1.40 新增
@@ -625,7 +625,7 @@ GSD 子 Agent 在单独的上下文窗口中运行——其工作在进行中对
{
"models": { "research": "sonnet" },
"model_overrides": {
"gsd-codebase-mapper": "haiku"
"msd-codebase-mapper": "haiku"
}
}
```
@@ -655,7 +655,7 @@ GSD 子 Agent 在单独的上下文窗口中运行——其工作在进行中对
在调整 `model_profile` 或 `models.<phase_type>` 之前,请审计您的运行时启用了哪些 **MCP 服务器**。每个启用的 MCP 服务器都会将其工具模式注入每次交互——重量级服务器每次可能消耗超过 20k 个 token。
这是**运行时设置**,不是 GSD 设置。切换项位于 `.claude/settings.json`:
这是**运行时设置**,不是 MSD 设置。切换项位于 `.claude/settings.json`:
```json
{
@@ -672,13 +672,13 @@ GSD 子 Agent 在单独的上下文窗口中运行——其工作在进行中对
每个被禁用的服务器都会从后续每次交互中移除其模式。精简 MCP **与** `model_profile` 调整形成叠加效果——两个杠杆是累加的,MCP 节省效果立即体现在编排器生成的每个子 Agent 上。
完整审计、运行时参考及与 `model_profile` 的组合说明,请参阅捆绑的 `context-budget.md` 参考中的 [MCP 工具模式成本](../../gsd-core/references/context-budget.md#mcp-tool-schema-cost-harness-concern)。
完整审计、运行时参考及与 `model_profile` 的组合说明,请参阅捆绑的 `context-budget.md` 参考中的 [MCP 工具模式成本](../../msd-core/references/context-budget.md#mcp-tool-schema-cost-harness-concern)。
### 使用非 Claude 运行时(Codex、OpenCode、Antigravity CLI、Kilo)
> **Codex CLI 最低支持版本:`0.130.0`**(issue [#3562](https://github.com/open-gsd/gsd-core/issues/3562))。
如果您为非 Claude 运行时安装了 GSD,安装器已配置好模型解析。无需手动设置——`resolve_model_ids: "omit"` 会自动设置,告知 GSD 跳过 Anthropic 模型 ID 解析,让运行时选择其默认模型。
如果您为非 Claude 运行时安装了 MSD,安装器已配置好模型解析。无需手动设置——`resolve_model_ids: "omit"` 会自动设置,告知 MSD 跳过 Anthropic 模型 ID 解析,让运行时选择其默认模型。
在非 Claude 运行时上分配不同模型:
@@ -686,9 +686,9 @@ GSD 子 Agent 在单独的上下文窗口中运行——其工作在进行中对
{
"resolve_model_ids": "omit",
"model_overrides": {
"gsd-planner": "o3",
"gsd-executor": "o4-mini",
"gsd-debugger": "o3"
"msd-planner": "o3",
"msd-executor": "o4-mini",
"msd-debugger": "o3"
}
}
```
@@ -706,9 +706,9 @@ GSD 子 Agent 在单独的上下文窗口中运行——其工作在进行中对
### 手动安装 / 无 Node.js 设置
如果无法运行 GSD 安装器,则无法直接使用 `agents/` 中的源文件——它们采用 Claude Code 的原生 frontmatter 格式。对于 OpenCode,需要进行两项转换:
如果无法运行 MSD 安装器,则无法直接使用 `agents/` 中的源文件——它们采用 Claude Code 的原生 frontmatter 格式。对于 OpenCode,需要进行两项转换:
| 字段 | GSD 源格式 | OpenCode 有效格式 | 操作 |
| 字段 | MSD 源格式 | OpenCode 有效格式 | 操作 |
|---|---|---|---|
| `tools:` | `Read, Bash, Grep`(逗号字符串) | 不是 frontmatter 字段 | 完全删除 `tools:` 行 |
| `color:` | 纯 CSS 颜色名称 | 十六进制或 OpenCode 语义名称 | 转换为十六进制或删除 |
@@ -716,26 +716,26 @@ GSD 子 Agent 在单独的上下文窗口中运行——其工作在进行中对
**替代方案:** 在任何有 Node.js 的机器上运行安装器:
```bash
npx @opengsd/gsd-core@latest --opencode --global
npx @golem15/msd-core@latest --opencode --global
```
### 为 Cline 安装
```bash
npx @opengsd/gsd-core --cline --global # applies to all projects
npx @opengsd/gsd-core --cline --local # this project only
npx @golem15/msd-core --cline --global # applies to all projects
npx @golem15/msd-core --cline --local # this project only
```
### 为 CodeBuddy 安装
```bash
npx @opengsd/gsd-core --codebuddy --global
npx @golem15/msd-core --codebuddy --global
```
### 为 Qwen Code 安装
```bash
npx @opengsd/gsd-core --qwen --global
npx @golem15/msd-core --qwen --global
```
### 为预发布版本安装
@@ -743,7 +743,7 @@ npx @opengsd/gsd-core --qwen --global
在运行安装器前,将运行时的 `*_CONFIG_DIR` 环境变量设置为预发布目录:
```bash
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @golem15/msd-core@latest --windsurf --global
```
**支持运行时的环境变量参考:**
@@ -766,23 +766,23 @@ WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --wind
### 将 Claude Code 与非 Anthropic 提供商结合使用
切换到 `inherit` 配置文件:`/gsd-config --profile inherit`。这使所有 Agent 使用您当前的会话模型。
切换到 `inherit` 配置文件:`/msd-config --profile inherit`。这使所有 Agent 使用您当前的会话模型。
### 处理敏感/私有项目
在 `/gsd-new-project` 期间或通过 `/gsd-settings` 设置 `commit_docs: false`。将 `.planning/` 添加到您的 `.gitignore`。
在 `/msd-new-project` 期间或通过 `/msd-settings` 设置 `commit_docs: false`。将 `.planning/` 添加到您的 `.gitignore`。
### GSD 更新覆盖了我的本地更改
### MSD 更新覆盖了我的本地更改
自 v1.17 起,安装器会将本地修改的文件备份到 `gsd-local-patches/`。运行 `/gsd-update --reapply` 将您的更改合并回来。
自 v1.17 起,安装器会将本地修改的文件备份到 `msd-local-patches/`。运行 `/msd-update --reapply` 将您的更改合并回来。
### 无法通过 npm 更新
参见 [docs/manual-update.md](../manual-update.md) 中的逐步手动更新程序。
### 工作流诊断(`/gsd-forensics`)
### 工作流诊断(`/msd-forensics`)
当工作流以不明显的方式失败时,运行 `/gsd-forensics` 生成涵盖 git 历史异常、产物完整性和状态不一致的诊断报告。输出写入 `.planning/forensics/`。
当工作流以不明显的方式失败时,运行 `/msd-forensics` 生成涵盖 git 历史异常、产物完整性和状态不一致的诊断报告。输出写入 `.planning/forensics/`。
### 执行器子 Agent 在 Bash 命令上遇到"Permission denied"
@@ -811,14 +811,14 @@ WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --wind
### 并行执行导致构建锁定错误
GSD 自 v1.26 起自动处理此问题。如果您使用的是旧版本,请在项目的 `CLAUDE.md` 中添加:
MSD 自 v1.26 起自动处理此问题。如果您使用的是旧版本,请在项目的 `CLAUDE.md` 中添加:
```markdown
## Git Commit Rules for Agents
All subagent/executor commits MUST use `--no-verify`.
```
完全禁用并行执行:`/gsd-settings` → 将 `parallelization.enabled` 设置为 `false`。
完全禁用并行执行:`/msd-settings` → 将 `parallelization.enabled` 设置为 `false`。
---
@@ -826,19 +826,19 @@ All subagent/executor commits MUST use `--no-verify`.
| 问题 | 解决方案 |
| ------------------------------------ | ------------------------------------------------------------------------ |
| 丢失上下文 / 新会话 | `/gsd-resume-work` 或 `/gsd-progress` |
| 丢失上下文 / 新会话 | `/msd-resume-work` 或 `/msd-progress` |
| 阶段出错 | `git revert` 阶段提交,然后重新计划 |
| 需要更改范围 | `/gsd-phase`(默认)、`/gsd-phase --insert` 或 `/gsd-phase --remove` |
| 出现问题 | `/gsd-debug "description"`(添加 `--diagnose` 进行分析而不修复) |
| 需要更改范围 | `/msd-phase`(默认)、`/msd-phase --insert` 或 `/msd-phase --remove` |
| 出现问题 | `/msd-debug "description"`(添加 `--diagnose` 进行分析而不修复) |
| STATE.md 不同步 | `state validate` 然后 `state sync` |
| 工作流状态似乎损坏 | `/gsd-forensics` |
| 快速定向修复 | `/gsd-quick` |
| 计划与您的愿景不符 | `/gsd-discuss-phase [N]` 然后重新计划 |
| 成本持续上涨 | `/gsd-config --profile budget` 并通过 `/gsd-settings` 关闭 Agent |
| 更新破坏了本地更改 | `/gsd-update --reapply` |
| 需要为利益相关者生成会话摘要 | `/gsd-pause-work --report` |
| 不知道下一步是什么 | `/gsd-progress --next` |
| 并行执行构建错误 | 更新 GSD 或设置 `parallelization.enabled: false` |
| 工作流状态似乎损坏 | `/msd-forensics` |
| 快速定向修复 | `/msd-quick` |
| 计划与您的愿景不符 | `/msd-discuss-phase [N]` 然后重新计划 |
| 成本持续上涨 | `/msd-config --profile budget` 并通过 `/msd-settings` 关闭 Agent |
| 更新破坏了本地更改 | `/msd-update --reapply` |
| 需要为利益相关者生成会话摘要 | `/msd-pause-work --report` |
| 不知道下一步是什么 | `/msd-progress --next` |
| 并行执行构建错误 | 更新 MSD 或设置 `parallelization.enabled: false` |
---
@@ -852,24 +852,24 @@ All subagent/executor commits MUST use `--no-verify`.
STATE.md # Decisions, blockers, session memory
config.json # Workflow configuration
MILESTONES.md # Completed milestone archive
HANDOFF.json # Structured session handoff (from /gsd-pause-work)
research/ # Domain research from /gsd-new-project
reports/ # Session reports (from /gsd-pause-work --report)
HANDOFF.json # Structured session handoff (from /msd-pause-work)
research/ # Domain research from /msd-new-project
reports/ # Session reports (from /msd-pause-work --report)
todos/
pending/ # Captured ideas awaiting work
completed/ # Completed todos
debug/ # Active debug sessions
resolved/ # Archived debug sessions
spikes/ # Feasibility experiments (from /gsd-spike)
spikes/ # Feasibility experiments (from /msd-spike)
NNN-name/ # Experiment code + README with verdict
MANIFEST.md # Index of all spikes
sketches/ # HTML mockups (from /gsd-sketch)
sketches/ # HTML mockups (from /msd-sketch)
NNN-name/ # index.html (2-3 variants) + README
themes/
default.css # Shared CSS variables for all sketches
MANIFEST.md # Index of all sketches with winners
codebase/ # Brownfield codebase mapping (from /gsd-map-codebase or /gsd-onboard)
onboarding/ # Brownfield onboarding summary (from /gsd-onboard)
codebase/ # Brownfield codebase mapping (from /msd-map-codebase or /msd-onboard)
onboarding/ # Brownfield onboarding summary (from /msd-onboard)
phases/
XX-phase-name/
XX-YY-PLAN.md # Atomic execution plans
@@ -877,9 +877,9 @@ All subagent/executor commits MUST use `--no-verify`.
CONTEXT.md # Your implementation preferences
RESEARCH.md # Ecosystem research findings
VERIFICATION.md # Post-execution verification results
XX-UI-SPEC.md # UI design contract (from /gsd-ui-phase)
XX-UI-REVIEW.md # Visual audit scores (from /gsd-ui-review)
ui-reviews/ # Screenshots from /gsd-ui-review (gitignored)
XX-UI-SPEC.md # UI design contract (from /msd-ui-phase)
XX-UI-REVIEW.md # Visual audit scores (from /msd-ui-review)
ui-reviews/ # Screenshots from /msd-ui-review (gitignored)
```
---

View File

@@ -19,7 +19,7 @@
|-------|-----------|----------------|
| 正常 | > 35% | 无警告 |
| 警告 | <= 35% | 完成当前任务收尾,避免开启新的复杂工作 |
| 严重 | <= 25% | 立即停止,保存状态(`/gsd-pause-work`) |
| 严重 | <= 25% | 立即停止,保存状态(`/msd-pause-work`) |
## 防抖机制
@@ -31,13 +31,13 @@
## 架构
```
Statusline Hook (gsd-statusline.js)
Statusline Hook (msd-statusline.js)
| writes
v
/tmp/claude-ctx-{session_id}.json
^ reads
|
Context Monitor (gsd-context-monitor.js, PostToolUse/AfterTool)
Context Monitor (msd-context-monitor.js, PostToolUse/AfterTool)
| injects
v
additionalContext -> Agent sees warning
@@ -54,15 +54,15 @@ additionalContext -> Agent sees warning
}
```
## 与 GSD 的集成
## 与 MSD 的集成
GSD 的 `/gsd-pause-work` 命令用于保存执行状态。WARNING 消息建议使用该命令,CRITICAL 消息则要求立即保存状态。
MSD 的 `/msd-pause-work` 命令用于保存执行状态。WARNING 消息建议使用该命令,CRITICAL 消息则要求立即保存状态。
## 配置
两个钩子均在执行 `npx @opengsd/gsd-core` 安装时自动注册——正常情况下无需手动操作。有关钩子配置详情、阈值覆盖以及手动注册示例,请参阅[配置文档](CONFIGURATION.md)。
两个钩子均在执行 `npx @golem15/msd-core` 安装时自动注册——正常情况下无需手动操作。有关钩子配置详情、阈值覆盖以及手动注册示例,请参阅[配置文档](CONFIGURATION.md)。
简要参考:状态栏钩子在 `settings.json` 中注册为 `statusLine`;上下文监视器(`gsd-context-monitor.js`)注册为 `PostToolUse` 钩子(Antigravity CLI 中为 `AfterTool`)。两项配置均使用运行安装程序时的 Node 可执行文件绝对路径。在 Windows PowerShell 中,需在带引号的可执行文件路径前添加 `&` 前缀。
简要参考:状态栏钩子在 `settings.json` 中注册为 `statusLine`;上下文监视器(`msd-context-monitor.js`)注册为 `PostToolUse` 钩子(Antigravity CLI 中为 `AfterTool`)。两项配置均使用运行安装程序时的 Node 可执行文件绝对路径。在 Windows PowerShell 中,需在带引号的可执行文件路径前添加 `&` 前缀。
## 安全性

View File

@@ -1,6 +1,6 @@
# 上下文工程
> GSD Core 的存在原因及其旨在解决的问题。
> MSD Core 的存在原因及其旨在解决的问题。
---
@@ -23,15 +23,15 @@
---
## GSD Core 的答案:全新上下文的子智能体
## MSD Core 的答案:全新上下文的子智能体
GSD Core 的核心洞见是:编码会话中*大多数*工作根本无需在主上下文中完成。研究、规划、代码编写和验证各自是独立且边界清晰的任务。每项任务都可以交给一个专门的子智能体来处理——该智能体以一个干净、精心限定范围的上下文窗口启动,并将其结果报告给一个保持精简状态的薄层编排器。
MSD Core 的核心洞见是:编码会话中*大多数*工作根本无需在主上下文中完成。研究、规划、代码编写和验证各自是独立且边界清晰的任务。每项任务都可以交给一个专门的子智能体来处理——该智能体以一个干净、精心限定范围的上下文窗口启动,并将其结果报告给一个保持精简状态的薄层编排器。
这不是上下文腐化的变通之法,而是一种结构性解决方案。
编排器——也就是你的主会话——从不接触源文件。它生成智能体、收集其结果、更新共享状态,并路由到下一个步骤。正因为它自身承担的工作很少,其上下文窗口的增长缓慢且可预测。繁重的工作发生在各个智能体中——每个智能体都以全新状态启动,仅接收完成其任务所需的上下文,并在完成后终止。
考虑这在实践中意味着什么。当你运行 `/gsd-plan-phase` 时,编排器会:
考虑这在实践中意味着什么。当你运行 `/msd-plan-phase` 时,编排器会:
1. 加载一个紧凑的 JSON 上下文有效载荷(项目摘要、阶段目标、相关配置)。
2. 生成一个拥有 20 万令牌全新窗口的研究智能体。
@@ -44,11 +44,11 @@ GSD Core 的核心洞见是:编码会话中*大多数*工作根本无需在主
## 规格驱动开发与元提示
仅靠上下文工程还不够。如果一个智能体以全新状态启动,却接收到模糊的指令,它产生的输出也将是模糊的。GSD Core 将全新上下文的子智能体与两项互补的原则相结合:
仅靠上下文工程还不够。如果一个智能体以全新状态启动,却接收到模糊的指令,它产生的输出也将是模糊的。MSD Core 将全新上下文的子智能体与两项互补的原则相结合:
**规格驱动开发**意味着每个阶段在执行开始之前都会生成结构化产物。`CONTEXT.md` 捕获来自讨论步骤的实现决策。`RESEARCH.md` 记录研究智能体的发现。`PLAN.md` 将工作分解为离散的、按依赖关系排序的任务,并附有明确的验收标准。在执行器智能体接触文件之时,它已拥有一份精确的规格说明——而非对一段漫长对话的重新解读。
**元提示**意味着智能体定义本身就是经过精心设计的提示,而非临时指令。`gsd-core/workflows/` 和 `agents/` 中的文件编码了关于如何限定任务范围、需要验证什么,以及何时上报至人工检查点的宝贵经验。用户无需在每次会话中重新解释这些知识;它已内嵌于系统自身的提示中。
**元提示**意味着智能体定义本身就是经过精心设计的提示,而非临时指令。`msd-core/workflows/` 和 `agents/` 中的文件编码了关于如何限定任务范围、需要验证什么,以及何时上报至人工检查点的宝贵经验。用户无需在每次会话中重新解释这些知识;它已内嵌于系统自身的提示中。
这种组合是刻意为之的。全新上下文确保每个智能体清晰推理。规格驱动的产物确保每个智能体针对*正确的*事物进行推理。元提示确保每个智能体知道*如何*将其做好。
@@ -56,7 +56,7 @@ GSD Core 的核心洞见是:编码会话中*大多数*工作根本无需在主
## `.planning/` 的作用
上下文工程要求知识能在上下文重置后得以保留。GSD Core 为此使用文件系统。每一项有意义的输出都以人类可读的 Markdown 或 JSON 格式写入 `.planning/`。这意味着:
上下文工程要求知识能在上下文重置后得以保留。MSD Core 为此使用文件系统。每一项有意义的输出都以人类可读的 Markdown 或 JSON 格式写入 `.planning/`。这意味着:
- 重启会话(或模型崩溃)不会丢失工作成果。
- 任何后续智能体都可以直接读取先前的产物,而无需依赖共享的对话历史。
@@ -70,11 +70,11 @@ GSD Core 的核心洞见是:编码会话中*大多数*工作根本无需在主
这里需要如实说明权衡之处。
**额外开销。** 阶段循环引入了真实的摩擦。将 `/gsd-discuss-phase`、`/gsd-plan-phase` 和 `/gsd-execute-phase` 作为独立步骤运行,比直接在普通会话中输入"实现这个功能"需要更多的耗时。对于小型、已充分理解的改动,这种开销并不值得。
**额外开销。** 阶段循环引入了真实的摩擦。将 `/msd-discuss-phase`、`/msd-plan-phase` 和 `/msd-execute-phase` 作为独立步骤运行,比直接在普通会话中输入"实现这个功能"需要更多的耗时。对于小型、已充分理解的改动,这种开销并不值得。
**延迟。** 生成多个拥有全新上下文的子智能体,比单次上下文内编辑要慢。研究、规划和执行各自都会产生往返成本。
**简单任务的繁文缛节。** 如果你只需要重命名一个变量、修复一个错别字,或添加一个缺失的导入,阶段循环就是杀鸡用牛刀。GSD Core 提供了 `/gsd-quick` 和 `/gsd-fast`,用于处理不需要完整阶段的临时工作。请参阅[处理快速任务](../how-to/handle-quick-and-fast-tasks.md)。
**简单任务的繁文缛节。** 如果你只需要重命名一个变量、修复一个错别字,或添加一个缺失的导入,阶段循环就是杀鸡用牛刀。MSD Core 提供了 `/msd-quick` 和 `/msd-fast`,用于处理不需要完整阶段的临时工作。请参阅[处理快速任务](../how-to/handle-quick-and-fast-tasks.md)。
当工作足够复杂、上下文腐化成为真实风险时,阶段循环才物有所值——例如多文件功能、横切重构、跨越数小时或多个会话的工作。其他情况下,请使用更轻量的原语。

View File

@@ -1,6 +1,6 @@
# GSD Core 中的多智能体编排
# MSD Core 中的多智能体编排
> **说明文档** — 本文档阐述 GSD Core *为何*围绕多智能体编排进行设计,以及*各组件如何协同工作*。这不是操作指南。有关配置,请参阅
> **说明文档** — 本文档阐述 MSD Core *为何*围绕多智能体编排进行设计,以及*各组件如何协同工作*。这不是操作指南。有关配置,请参阅
> [配置模型配置文件](../how-to/configure-model-profiles.md) 和
> [配置参考](../CONFIGURATION.md)。有关完整的智能体清单,
> 请参阅 [清单](../INVENTORY.md)。
@@ -14,7 +14,7 @@ AI 编程智能体会逐渐退化。这并非因为模型变差,而是因为
会被中间步骤的噪音挤出或稀释。当智能体在复杂任务中写到第五个文件时,
它可能已经忘记了第一条消息中说明的约束条件。这种现象有时被称为*上下文腐化*。
GSD Core 的多智能体设计正是对这一问题的直接回应。与其让一个
MSD Core 的多智能体设计正是对这一问题的直接回应。与其让一个
长期运行的智能体承担整个会话,不如让一个轻量编排器派生出
短暂存在的专用智能体,每个智能体都拥有**全新的 200K token 上下文窗口**,
并且*只获取完成其特定工作所需的工件*。编排器自身从不承担繁重工作;
@@ -24,17 +24,17 @@ GSD Core 的多智能体设计正是对这一问题的直接回应。与其让
## 编排器 → 智能体模式
`gsd-core/workflows/` 中的每个工作流都遵循相同的结构:
`msd-core/workflows/` 中的每个工作流都遵循相同的结构:
```text
Orchestrator (workflow .md file)
│
├── Load context
│ gsd-tools.cjs init <workflow> <phase>
│ msd-tools.cjs init <workflow> <phase>
│ → JSON: project info, config, state, phase details
│
├── Resolve model
│ gsd-tools.cjs resolve-model <agent-name>
│ msd-tools.cjs resolve-model <agent-name>
│ → opus | sonnet | haiku | inherit
│
├── Spawn specialised agent (Task/SubAgent call)
@@ -46,7 +46,7 @@ Orchestrator (workflow .md file)
├── Collect result
│
└── Update state
gsd-tools.cjs state update / state patch / state advance-plan
msd-tools.cjs state update / state patch / state advance-plan
```
编排器被刻意设计为轻量级。它不对领域进行推理,
@@ -55,19 +55,19 @@ Orchestrator (workflow .md file)
### 智能体清单
GSD Core 的智能体按功能类别划分,对应
MSD Core 的智能体按功能类别划分,对应
研究 → 规划 → 执行 → 验证的流水线:
| 类别 | 智能体 | 典型并行度 |
|---|---|---|
| 研究员 | `gsd-project-researcher`、`gsd-phase-researcher`、`gsd-ui-researcher`、`gsd-advisor-researcher` | 4 个并行(技术栈、功能、架构、潜在问题) |
| 综合员 | `gsd-research-synthesizer` | 顺序执行,在研究员完成后运行 |
| 规划员 | `gsd-planner`、`gsd-roadmapper` | 顺序执行 |
| 检查员 | `gsd-plan-checker`、`gsd-integration-checker`、`gsd-ui-checker`、`gsd-nyquist-auditor` | 顺序执行,最多 3 次修订迭代 |
| 执行员 | `gsd-executor` | 波次内并行,波次间顺序 |
| 验证员 | `gsd-verifier` | 顺序执行,在所有执行员完成后运行 |
| 映射员 | `gsd-codebase-mapper` | 4 个并行子探针 |
| 审计员 | `gsd-ui-auditor`、`gsd-security-auditor` | 顺序执行 |
| 研究员 | `msd-project-researcher`、`msd-phase-researcher`、`msd-ui-researcher`、`msd-advisor-researcher` | 4 个并行(技术栈、功能、架构、潜在问题) |
| 综合员 | `msd-research-synthesizer` | 顺序执行,在研究员完成后运行 |
| 规划员 | `msd-planner`、`msd-roadmapper` | 顺序执行 |
| 检查员 | `msd-plan-checker`、`msd-integration-checker`、`msd-ui-checker`、`msd-nyquist-auditor` | 顺序执行,最多 3 次修订迭代 |
| 执行员 | `msd-executor` | 波次内并行,波次间顺序 |
| 验证员 | `msd-verifier` | 顺序执行,在所有执行员完成后运行 |
| 映射员 | `msd-codebase-mapper` | 4 个并行子探针 |
| 审计员 | `msd-ui-auditor`、`msd-security-auditor` | 顺序执行 |
每个智能体定义(位于 `agents/*.md`)声明了其允许的工具访问权限、
用途以及终端输出颜色。仅需读取文件并写入单个输出文档的智能体
@@ -80,7 +80,7 @@ GSD Core 的智能体按功能类别划分,对应
## 基于波次的并行执行
多智能体设计最直观的体现是 `/gsd-execute-phase`
多智能体设计最直观的体现是 `/msd-execute-phase`
如何处理一组可能相互依赖的计划。
在派生任何执行员之前,编排器会执行**波次分析**:
@@ -159,7 +159,7 @@ AI 智能体上下文窗口中包含的内容与模型层级或提示质量同
**跨会话的上下文卫生。** 由于所有状态都以人类可读的 Markdown 和 JSON
存储在 `.planning/` 中(而非任何智能体的上下文窗口中),
GSD 工作流能够在上下文重置(`/clear`)、标签页切换和
MSD 工作流能够在上下文重置(`/clear`)、标签页切换和
多日中断后继续运行。下一个智能体始终从持久化的、经过验证的
工件启动,而非从漫长对话的重建记忆中启动。
@@ -172,7 +172,7 @@ GSD 工作流能够在上下文重置(`/clear`)、标签页切换和
**协调开销。** 每次智能体派生都是一次往返:编排器
必须格式化提示、移交上下文、等待子智能体完成
(通常需 1–5 分钟),然后解析结果。对于简单任务,
单个能力强大的智能体在一个上下文中工作会更快完成。GSD 通过
单个能力强大的智能体在一个上下文中工作会更快完成。MSD 通过
将并行化作为默认方式来缓解这一问题(在依赖关系允许的情况下)——
`plan-phase` 中的四个研究员同时运行,而非顺序运行。
@@ -184,7 +184,7 @@ GSD 工作流能够在上下文重置(`/clear`)、标签页切换和
**上下文拼接成本。** 为每个智能体打包正确的工件
需要编排器花费 token 来组装和传输上下文负载。
这是隔离的代价。`gsd-tools.cjs init` 处理器
这是隔离的代价。`msd-tools.cjs init` 处理器
生成一个在完整性与 token 预算之间取得平衡的 JSON 负载,
采用缓存友好的排序,使负载中稳定的部分(项目定义、配置)
在重复调用时命中缓存。

View File

@@ -1,14 +1,14 @@
# GSD Core 安全模型
# MSD Core 安全模型
> **说明** — 本文档描述 GSD Core 为何采用当前的安全立场,以及各防护层如何协同工作。本文不是每个钩子参数的参考手册。有关 `/gsd-secure-phase` 命令及其选项,请参阅[命令文档](../COMMANDS.md)。有关实现层面的钩子架构,请参阅[架构文档 § 钩子系统](../ARCHITECTURE.md#hook-system)。有关组织级安全基线(扫描器控制、事件处理清单、所有权模型),请参阅 [SECURITY.md](../../../SECURITY.md)。
> **说明** — 本文档描述 MSD Core 为何采用当前的安全立场,以及各防护层如何协同工作。本文不是每个钩子参数的参考手册。有关 `/msd-secure-phase` 命令及其选项,请参阅[命令文档](../COMMANDS.md)。有关实现层面的钩子架构,请参阅[架构文档 § 钩子系统](../ARCHITECTURE.md#hook-system)。有关组织级安全基线(扫描器控制、事件处理清单、所有权模型),请参阅 [SECURITY.md](../../../SECURITY.md)。
---
## 为何 AI 驱动的开发需要专项安全立场
传统代码编辑器不会代表用户执行任意软件包。GSD Core 会。其研究 → 计划 → 执行的流水线将从"命名一个软件包"到"运行 `npm install <package>`"、从"编写规划产物"到"将该产物用作 LLM 系统提示"的完整路径全部自动化。每一个自动化步骤都将人从环路中移除——而每次移除都是潜在的攻击面。
传统代码编辑器不会代表用户执行任意软件包。MSD Core 会。其研究 → 计划 → 执行的流水线将从"命名一个软件包"到"运行 `npm install <package>`"、从"编写规划产物"到"将该产物用作 LLM 系统提示"的完整路径全部自动化。每一个自动化步骤都将人从环路中移除——而每次移除都是潜在的攻击面。
GSD Core 的安全模型围绕一个核心原则构建:**纵深防御**。没有任何单一控制措施被认为是完美的。多个相互重叠的层各自降低一类特定风险,共同使攻击面大幅难以利用——尽管并未彻底消除。本文档末尾的诚实总结说明了该系统无法防御的内容。
MSD Core 的安全模型围绕一个核心原则构建:**纵深防御**。没有任何单一控制措施被认为是完美的。多个相互重叠的层各自降低一类特定风险,共同使攻击面大幅难以利用——尽管并未彻底消除。本文档末尾的诚实总结说明了该系统无法防御的内容。
---
@@ -18,17 +18,17 @@ GSD Core 的安全模型围绕一个核心原则构建:**纵深防御**。没
AI 模型会产生幻觉性软件包名称。这并非边缘故障模式:2025 年的研究表明,AI 生成的软件包引用中约有 20% 是幻觉名称,与合法软件包并不对应。这些幻觉名称中有一部分——同一研究中约 43%——在提示词中持续重复出现,这意味着攻击者可以观察 AI 工具常见生成的名称,然后在 npm、PyPI 或 crates.io 上预先注册这些名称,并附带恶意的安装后脚本。这种技术称为 *slopsquatting*。
Slopsquatting 的隐蔽之处在于,通过 `npm view` 验证的幻觉名称*看起来是合法的*。注册表条目仅证明有人注册了该名称——并不能证明该软件包实现了 AI 所描述的功能,也不能证明它有任何合法用户,更不能证明其安装脚本是安全的。若没有门控,幻觉名称将无声地流过 GSD 的研究员 → 规划员 → 执行员流水线,最终在您的机器上作为 `npm install <attacker-package>` 运行。
Slopsquatting 的隐蔽之处在于,通过 `npm view` 验证的幻觉名称*看起来是合法的*。注册表条目仅证明有人注册了该名称——并不能证明该软件包实现了 AI 所描述的功能,也不能证明它有任何合法用户,更不能证明其安装脚本是安全的。若没有门控,幻觉名称将无声地流过 MSD 的研究员 → 规划员 → 执行员流水线,最终在您的机器上作为 `npm install <attacker-package>` 运行。
### 门控机制
门控机制跨三个流水线阶段运行:
**研究阶段。** 当 `gsd-phase-researcher` 推荐外部软件包时,它会对每个软件包运行 `gsd-tools query package-legitimacy check --ecosystem <npm|pypi|crates> <pkgs>`。结果会以 `## Package Legitimacy Audit` 表格的形式写入 `RESEARCH.md`。标记为 `[SLOP]`(高置信度幻觉或攻击者注册)的软件包在保存前会**从 `RESEARCH.md` 中完全删除**,永远不会到达规划员。
**研究阶段。** 当 `msd-phase-researcher` 推荐外部软件包时,它会对每个软件包运行 `msd-tools query package-legitimacy check --ecosystem <npm|pypi|crates> <pkgs>`。结果会以 `## Package Legitimacy Audit` 表格的形式写入 `RESEARCH.md`。标记为 `[SLOP]`(高置信度幻觉或攻击者注册)的软件包在保存前会**从 `RESEARCH.md` 中完全删除**,永远不会到达规划员。
**规划阶段。** `gsd-planner` 读取审计表。对于任何标记为 `[SUS]`(可疑:新注册、下载量低、无源代码仓库,或命名模式接近某热门软件包)或 `[ASSUMED]`(来自 WebSearch 而非直接注册表验证)的软件包,规划员会在安装步骤之前**插入一个 `checkpoint:human-verify` 任务**。该检查点包含指向注册表页面的直接链接,以及需要重点核查的内容:维护者历史、问题跟踪器活动、是否存在可疑的安装脚本。
**规划阶段。** `msd-planner` 读取审计表。对于任何标记为 `[SUS]`(可疑:新注册、下载量低、无源代码仓库,或命名模式接近某热门软件包)或 `[ASSUMED]`(来自 WebSearch 而非直接注册表验证)的软件包,规划员会在安装步骤之前**插入一个 `checkpoint:human-verify` 任务**。该检查点包含指向注册表页面的直接链接,以及需要重点核查的内容:维护者历史、问题跟踪器活动、是否存在可疑的安装脚本。
**执行阶段。** 若安装失败,`gsd-executor` 会**触发检查点并停止**。它不会静默地尝试备用软件包名称——因为备用名称本身可能也是恶意的。这是执行员行为定义中的明确规则(执行员代理定义中的 RULE 3)。
**执行阶段。** 若安装失败,`msd-executor` 会**触发检查点并停止**。它不会静默地尝试备用软件包名称——因为备用名称本身可能也是恶意的。这是执行员行为定义中的明确规则(执行员代理定义中的 RULE 3)。
### 为何 WebSearch 软件包始终标记为 `[ASSUMED]`
@@ -46,7 +46,7 @@ Slopsquatting 的隐蔽之处在于,通过 `npm view` 验证的幻觉名称*
### 优雅降级
若 `slopcheck` 不可用(未安装,或研究阶段 pip 安装失败),GSD 应用最严格的兜底策略:**每个推荐软件包均标记为 `[ASSUMED]`**,规划员对每次安装均设置 `checkpoint:human-verify` 任务。研究和规划照常进行——系统不会因缺少工具依赖而硬性失败。这有意比正常流程更严格:`slopcheck` 不可用意味着每次软件包安装都会有人工检查点。
若 `slopcheck` 不可用(未安装,或研究阶段 pip 安装失败),MSD 应用最严格的兜底策略:**每个推荐软件包均标记为 `[ASSUMED]`**,规划员对每次安装均设置 `checkpoint:human-verify` 任务。研究和规划照常进行——系统不会因缺少工具依赖而硬性失败。这有意比正常流程更严格:`slopcheck` 不可用意味着每次软件包安装都会有人工检查点。
`slopcheck` 工具采用 MIT 协议,可通过 pip 安装。若该工具被废弃,`[ASSUMED]` 门控兜底策略确保人工检查点覆盖无论如何均能维持。
@@ -56,36 +56,36 @@ Slopsquatting 的隐蔽之处在于,通过 `npm view` 验证的幻觉名称*
### 威胁
GSD Core 生成的 Markdown 文件会成为 LLM 系统提示。研究流水线读取外部网页内容;规划流水线接受用户提供的文本(`--text-file`、`--prd`);执行流水线写入规划产物,这些产物稍后会作为代理上下文被重新读取。任何流入这些产物的用户可控文本都是潜在的**间接提示注入**向量——攻击者控制的字符串一旦进入系统提示,就会尝试覆盖代理指令或窃取信息。
MSD Core 生成的 Markdown 文件会成为 LLM 系统提示。研究流水线读取外部网页内容;规划流水线接受用户提供的文本(`--text-file`、`--prd`);执行流水线写入规划产物,这些产物稍后会作为代理上下文被重新读取。任何流入这些产物的用户可控文本都是潜在的**间接提示注入**向量——攻击者控制的字符串一旦进入系统提示,就会尝试覆盖代理指令或窃取信息。
### 防御机制
GSD Core 在三个层面应对提示注入。
MSD Core 在三个层面应对提示注入。
**输入验证(`security.cjs`)。** `gsd-core/bin/lib/security.cjs` 模块是核心安全工具。它提供:
**输入验证(`security.cjs`)。** `msd-core/bin/lib/security.cjs` 模块是核心安全工具。它提供:
- 路径遍历防护:用户提供的文件路径(`--text-file`、`--prd`)经过验证,确保解析在项目目录内,并显式处理 macOS `/var` → `/private/var` 符号链接解析
- 提示注入检测:已知注入模式(角色覆盖、指令绕过、系统标签注入)在用户提供的文本进入任何规划产物之前进行扫描
- 安全 JSON 解析:防止通过精心构造的 JSON 负载发动原型污染攻击的包装器
- Shell 参数验证:传递给子 Shell 命令的参数在使用前经过验证
**运行时钩子:`gsd-prompt-guard.js`。** 该钩子在每次针对 `.planning/` 文件的 Write 或 Edit 调用时触发。它扫描待写入内容中的注入模式,与 `security.cjs` 相同(部分模式直接内联到钩子中以实现独立性——钩子不 `require()` 该模块,因此即使模块路径改变也能运行)。检测结果**仅供参考**:钩子记录发现但不阻止写入。其原因在于,对合法规划写入的误报拦截比二级扫描层漏掉一次注入更具破坏性。
**运行时钩子:`msd-prompt-guard.js`。** 该钩子在每次针对 `.planning/` 文件的 Write 或 Edit 调用时触发。它扫描待写入内容中的注入模式,与 `security.cjs` 相同(部分模式直接内联到钩子中以实现独立性——钩子不 `require()` 该模块,因此即使模块路径改变也能运行)。检测结果**仅供参考**:钩子记录发现但不阻止写入。其原因在于,对合法规划写入的误报拦截比二级扫描层漏掉一次注入更具破坏性。
**运行时钩子:`gsd-read-injection-scanner.js`。** 该钩子在每次 Read 工具调用的输出时触发。它扫描*刚刚读取的内容*中在不可信内容中注入的指令——捕获攻击者在 GSD 即将纳入代理上下文的文件中嵌入指令的情况。
**运行时钩子:`msd-read-injection-scanner.js`。** 该钩子在每次 Read 工具调用的输出时触发。它扫描*刚刚读取的内容*中在不可信内容中注入的指令——捕获攻击者在 MSD 即将纳入代理上下文的文件中嵌入指令的情况。
**CI 扫描器。** `prompt-injection-scan.security.test.cjs` 作为测试套件的一部分,扫描所有代理、工作流和命令文件中嵌入的注入向量。这能捕获 GSD 源代码本身的注入尝试——例如,修改工作流文件以添加角色覆盖指令的供应链攻击。
**CI 扫描器。** `prompt-injection-scan.security.test.cjs` 作为测试套件的一部分,扫描所有代理、工作流和命令文件中嵌入的注入向量。这能捕获 MSD 源代码本身的注入尝试——例如,修改工作流文件以添加角色覆盖指令的供应链攻击。
### 读取注入扫描器与提示守卫的对比
两个钩子覆盖互补的攻击面。`gsd-prompt-guard.js` 监视*对规划产物的写入*——捕获注入的植入。`gsd-read-injection-scanner.js` 监视*任何文件的读取*——捕获来自外部内容的注入摄取(依赖项的 README、第三方配置文件、用户提供的文档)。两者共同覆盖了摄取 → 存储 → 再读取的完整生命周期。
两个钩子覆盖互补的攻击面。`msd-prompt-guard.js` 监视*对规划产物的写入*——捕获注入的植入。`msd-read-injection-scanner.js` 监视*任何文件的读取*——捕获来自外部内容的注入摄取(依赖项的 README、第三方配置文件、用户提供的文档)。两者共同覆盖了摄取 → 存储 → 再读取的完整生命周期。
---
## 第三层 — 仓库与依赖完整性
在 GSD 运行时行为的上游,`open-gsd` 组织在仓库和软件包层面实施控制。这些控制在 [`docs/security/baseline.md`](../../security/baseline.md) 中有完整文档,此处为完整性摘要。
在 MSD 运行时行为的上游,`open-gsd` 组织在仓库和软件包层面实施控制。这些控制在 [`docs/security/baseline.md`](../../security/baseline.md) 中有完整文档,此处为完整性摘要。
**依赖完整性。** 所有第三方依赖通过 `package-lock.json` 锁定,并在安装前与已发布的校验和进行验证。`scripts/check-npm-integrity.cjs` 门控在 CI 阶段检测版本无效、缺失软件包和多余软件包。这能缓解针对 GSD 自身依赖的依赖混淆和拼写抢注攻击。
**依赖完整性。** 所有第三方依赖通过 `package-lock.json` 锁定,并在安装前与已发布的校验和进行验证。`scripts/check-npm-integrity.cjs` 门控在 CI 阶段检测版本无效、缺失软件包和多余软件包。这能缓解针对 MSD 自身依赖的依赖混淆和拼写抢注攻击。
**密钥扫描。** 每次提交和 PR 均扫描硬编码密钥。有意的测试夹具必须使用项目标准排除语法进行标注(标注格式见 `SECURITY.md`)。未标注的抑制项将导致 CI 失败。
@@ -111,7 +111,7 @@ GSD Core 在三个层面应对提示注入。
## 相关文档
- [命令文档](../COMMANDS.md) — 包含 `/gsd-secure-phase` 和 `/gsd-code-review` 及安全相关标志
- [命令文档](../COMMANDS.md) — 包含 `/msd-secure-phase` 和 `/msd-code-review` 及安全相关标志
- [架构文档 § 钩子系统](../ARCHITECTURE.md#hook-system) — 每个钩子的实现细节、事件触发器及安全属性
- [SECURITY.md](../../../SECURITY.md) — 漏洞报告、组织级安全基线、密钥扫描排除治理及依赖完整性验证
- [文档索引](../README.md)

View File

@@ -1,12 +1,12 @@
# 阶段循环
> GSD Core 组织工作的核心思维模型。
> MSD Core 组织工作的核心思维模型。
---
## 循环是什么
GSD Core 将所有开发工作结构化为一个重复周期:
MSD Core 将所有开发工作结构化为一个重复周期:
```text
Discuss → (UI design) → Plan → Execute → Verify → Ship
@@ -30,7 +30,7 @@ Discuss 步骤刻意保持轻量。它是一次对话,而非规格说明练习
### UI design(可选)
对于有视觉组件的阶段,在 Discuss 和 Plan 之间有一个可选的 `/gsd-ui-phase` 步骤。它生成 `UI-SPEC.md`——一份在编写任何代码之前描述布局、交互和视觉行为的设计契约。当 UI 足够复杂,设计中的歧义会导致不同的实现选择时,值得运行此步骤。一份清晰的设计契约比重新实现要便宜得多。
对于有视觉组件的阶段,在 Discuss 和 Plan 之间有一个可选的 `/msd-ui-phase` 步骤。它生成 `UI-SPEC.md`——一份在编写任何代码之前描述布局、交互和视觉行为的设计契约。当 UI 足够复杂,设计中的歧义会导致不同的实现选择时,值得运行此步骤。一份清晰的设计契约比重新实现要便宜得多。
### Plan
@@ -87,7 +87,7 @@ Ship 步骤创建拉取请求并归档阶段产出物。`STATE.md` 更新以标
- 执行可以并行化为少数几个不重叠的计划,而不是几十个。
- 有清晰的、可测试的完成定义,验证器无需阅读整个代码库即可检查。
具体来说:"添加 HMAC-SHA256 签名验证中间件"是一个好的阶段范围。"构建认证系统"通常不是——它几乎总是包含多个独立关注点,作为单独阶段会更好。"修复 README 中的拼写错误"低于循环能增添价值的门槛;请使用 `/gsd-quick` 代替。
具体来说:"添加 HMAC-SHA256 签名验证中间件"是一个好的阶段范围。"构建认证系统"通常不是——它几乎总是包含多个独立关注点,作为单独阶段会更好。"修复 README 中的拼写错误"低于循环能增添价值的门槛;请使用 `/msd-quick` 代替。
有疑问时,拆分。更小的阶段完成得更快,验证更有把握,当设计决策被证明有误时也更容易纠偏。
@@ -113,7 +113,7 @@ Ship 步骤创建拉取请求并归档阶段产出物。`STATE.md` 更新以标
循环运行良好时,感觉像是一种节奏:有节奏的专注、有边界的工作,每个步骤都清晰,因为上一步骤做好了它的工作。开销是真实的,但它是前置支付的——用几分钟规划换取而不是数小时返工。
对于低于循环门槛的工作,GSD Core 提供更轻量的原语。阶段循环是一种工具,而非唯一工具。
对于低于循环门槛的工作,MSD Core 提供更轻量的原语。阶段循环是一种工具,而非唯一工具。
---

View File

@@ -6,7 +6,7 @@
## 四种配置文件(以及 `adaptive` 和 `inherit`)
在 `.planning/config.json` 中设置 `model_profile`,或通过 `/gsd-config --profile <name>` 设置:
在 `.planning/config.json` 中设置 `model_profile`,或通过 `/msd-config --profile <name>` 设置:
| 配置文件 | 规划器 | 执行器 | 研究员 | 验证器 | 适用场景 |
|---------|---------|----------|-------------|----------|----------|
@@ -16,15 +16,15 @@
| `adaptive` | Opus | Sonnet | Sonnet | Sonnet | 与其他层级在运行时感知配置文件下的解析方式相同;在频繁切换运行时环境时使用 |
| `inherit` | (会话模型) | (会话模型) | (会话模型) | (会话模型) | 非 Anthropic 提供商(OpenRouter、本地模型)——所有代理遵循当前会话模型 |
上表展示的是代表性子集。全部 33 个内置代理在 `gsd-core/bin/shared/model-catalog.json` 中均有明确的按配置文件层级分配。完整表格请参阅配置参考中的 [模型配置文件](../CONFIGURATION.md#model-profiles)。
上表展示的是代表性子集。全部 33 个内置代理在 `msd-core/bin/shared/model-catalog.json` 中均有明确的按配置文件层级分配。完整表格请参阅配置参考中的 [模型配置文件](../CONFIGURATION.md#model-profiles)。
**通过命令快速切换:**
```bash
/gsd-config --profile balanced # Normal development
/gsd-config --profile budget # Prototyping or high-cost phases
/gsd-config --profile quality # Production release
/gsd-config --profile inherit # OpenRouter, local models
/msd-config --profile balanced # Normal development
/msd-config --profile budget # Prototyping or high-cost phases
/msd-config --profile quality # Production release
/msd-config --profile inherit # OpenRouter, local models
```
**或直接编辑 `.planning/config.json`:**
@@ -45,20 +45,20 @@
{
"model_profile": "balanced",
"model_overrides": {
"gsd-executor": "opus",
"gsd-codebase-mapper": "haiku"
"msd-executor": "opus",
"msd-codebase-mapper": "haiku"
}
}
```
有效值:`opus`、`sonnet`、`haiku`、`inherit`,或任何完全限定的模型 ID(例如 `"openai/o3"`、`"google/gemini-2.5-pro"`)。
`model_overrides` 可在 `.planning/config.json` 中按项目设置,也可在 `~/.gsd/defaults.json` 中全局设置。项目级条目在冲突时优先;不冲突的全局条目会被保留。
`model_overrides` 可在 `.planning/config.json` 中按项目设置,也可在 `~/.msd/defaults.json` 中全局设置。项目级条目在冲突时优先;不冲突的全局条目会被保留。
**关于 Codex 和 OpenCode 的重要说明:** 这些运行时会在安装时将解析后的模型嵌入每个代理的静态配置中。编辑 `model_overrides` 后,需重新运行安装程序使更改生效:
```bash
npx @opengsd/gsd-core@latest --codex --global # or --opencode, --kilo, etc.
npx @golem15/msd-core@latest --codex --global # or --opencode, --kilo, etc.
```
---
@@ -85,11 +85,11 @@ npx @opengsd/gsd-core@latest --codex --global # or --opencode, --kilo, etc.
| 阶段类型 | 涵盖的代理 |
|---|---|
| `planning` | `gsd-planner`、`gsd-roadmapper`、`gsd-pattern-mapper` |
| `research` | `gsd-phase-researcher`、`gsd-project-researcher`、`gsd-research-synthesizer`、`gsd-codebase-mapper`、`gsd-ui-researcher` |
| `execution` | `gsd-executor`、`gsd-debugger`、`gsd-doc-writer` |
| `verification` | `gsd-verifier`、`gsd-plan-checker`、`gsd-integration-checker`、`gsd-nyquist-auditor`、`gsd-ui-checker`、`gsd-ui-auditor`、`gsd-doc-verifier`、`gsd-code-reviewer` |
| `discuss` | `gsd-assumptions-analyzer` |
| `planning` | `msd-planner`、`msd-roadmapper`、`msd-pattern-mapper` |
| `research` | `msd-phase-researcher`、`msd-project-researcher`、`msd-research-synthesizer`、`msd-codebase-mapper`、`msd-ui-researcher` |
| `execution` | `msd-executor`、`msd-debugger`、`msd-doc-writer` |
| `verification` | `msd-verifier`、`msd-plan-checker`、`msd-integration-checker`、`msd-nyquist-auditor`、`msd-ui-checker`、`msd-ui-auditor`、`msd-doc-verifier`、`msd-code-reviewer` |
| `discuss` | `msd-assumptions-analyzer` |
| `completion` | 保留——目前无子代理;已被模式接受以备向后兼容 |
`models` 块仅接受层级别名(`opus`、`sonnet`、`haiku`、`inherit`)。如需使用完全限定的模型 ID,请改用按代理设置的 `model_overrides`。
@@ -103,12 +103,12 @@ npx @opengsd/gsd-core@latest --codex --global # or --opencode, --kilo, etc.
"research": "sonnet"
},
"model_overrides": {
"gsd-codebase-mapper": "haiku"
"msd-codebase-mapper": "haiku"
}
}
```
全部五个研究代理解析为 `sonnet`,*除* `gsd-codebase-mapper` 被固定为 `haiku` 之外。
全部五个研究代理解析为 `sonnet`,*除* `msd-codebase-mapper` 被固定为 `haiku` 之外。
---
@@ -131,7 +131,7 @@ npx @opengsd/gsd-core@latest --codex --global # or --opencode, --kilo, etc.
}
```
每个代理都有一个默认层级(`light`、`standard` 或 `heavy`)。第一次尝试时,GSD Core 选择 `tier_models[default_tier]`。如果编排器检测到软失败(验证不确定、计划检查被标记等),则将代理提升一级重新启动。`max_escalations` 限制总重试次数。
每个代理都有一个默认层级(`light`、`standard` 或 `heavy`)。第一次尝试时,MSD Core 选择 `tier_models[default_tier]`。如果编排器检测到软失败(验证不确定、计划检查被标记等),则将代理提升一级重新启动。`max_escalations` 限制总重试次数。
已处于 `heavy` 层级的代理无法进一步升级。
@@ -152,9 +152,9 @@ npx @opengsd/gsd-core@latest --codex --global # or --opencode, --kilo, etc.
---
## 在非 Anthropic 运行时上使用 GSD Core
## 在非 Anthropic 运行时上使用 MSD Core
如果您为 Codex、OpenCode、Antigravity CLI 或 Kilo 安装了 GSD Core,安装程序已在您的配置中设置了 `resolve_model_ids: "omit"`。这告知 GSD Core 跳过 Anthropic 模型 ID 解析,让运行时选择其自己的默认模型。基本情况下无需手动设置。
如果您为 Codex、OpenCode、Antigravity CLI 或 Kilo 安装了 MSD Core,安装程序已在您的配置中设置了 `resolve_model_ids: "omit"`。这告知 MSD Core 跳过 Anthropic 模型 ID 解析,让运行时选择其自己的默认模型。基本情况下无需手动设置。
**如果您希望在 Codex 上使用分层模型:**
@@ -165,7 +165,7 @@ npx @opengsd/gsd-core@latest --codex --global # or --opencode, --kilo, etc.
}
```
GSD Core 将每个层级别名解析为运行时层级映射中定义的 Codex 原生模型和推理力度。
MSD Core 将每个层级别名解析为运行时层级映射中定义的 Codex 原生模型和推理力度。
**如果您希望在任意非 Claude 运行时上使用按代理模型 ID:**
@@ -173,9 +173,9 @@ GSD Core 将每个层级别名解析为运行时层级映射中定义的 Codex
{
"resolve_model_ids": "omit",
"model_overrides": {
"gsd-planner": "o3",
"gsd-executor": "o4-mini",
"gsd-debugger": "o3"
"msd-planner": "o3",
"msd-executor": "o4-mini",
"msd-debugger": "o3"
}
}
```

View File

@@ -2,7 +2,7 @@
**目标:** 在某个阶段执行失败、卡住或产生不完整工作时进行恢复,并在不丢失进度或重复已成功工作的情况下干净地继续。
**前提条件:** 您已运行 `/gsd-execute-phase N`,执行在写入 `VERIFICATION.md` 之前停止,或者您看到意外输出、缺少文件,或进度条卡住不动。
**前提条件:** 您已运行 `/msd-execute-phase N`,执行在写入 `VERIFICATION.md` 之前停止,或者您看到意外输出、缺少文件,或进度条卡住不动。
---
@@ -12,15 +12,15 @@
### 如果您看到"Spawning…"后超过 1–5 分钟没有输出
这是正常现象,并非冻结。GSD 子代理在独立的上下文窗口中运行。spawn 行上的存活注释可以确认这一点。请不要中断会话。
这是正常现象,并非冻结。MSD 子代理在独立的上下文窗口中运行。spawn 行上的存活注释可以确认这一点。请不要中断会话。
如果超过 10 分钟仍无结果,请检查 Claude Code 侧边栏。如果代理任务显示已完成但没有输出,结果可能在上下文切换中丢失——请重新运行相同的命令:
```bash
/gsd-execute-phase 1
/msd-execute-phase 1
```
GSD 在分派执行器之前会检查 `SUMMARY.md` 文件。已有该文件的计划将被自动跳过。
MSD 在分派执行器之前会检查 `SUMMARY.md` 文件。已有该文件的计划将被自动跳过。
### 如果执行在某个 wave 中途停止并显示错误信息
@@ -34,7 +34,7 @@ git log --oneline -20
### 如果执行器已提交代码但未写入 SUMMARY.md
GSD 会在下次运行时检测到这一情况,并弹出一个安全恢复确认界面,提供三个选项:
MSD 会在下次运行时检测到这一情况,并弹出一个安全恢复确认界面,提供三个选项:
- **手动收尾** — 自行检查提交内容,写入 `SUMMARY.md`,然后重新运行。
- **从头重新执行** — 在分派新执行器之前,回滚或覆盖部分提交。
@@ -44,12 +44,12 @@ GSD 会在下次运行时检测到这一情况,并弹出一个安全恢复确
## 诊断根本原因
### 运行 `/gsd-debug --diagnose`
### 运行 `/msd-debug --diagnose`
如果执行产生了错误输出、存根代码或验证失败,使用诊断模式进行调查,而不应用任何修复:
```bash
/gsd-debug --diagnose "Phase 2 executor produced stubs instead of real code"
/msd-debug --diagnose "Phase 2 executor produced stubs instead of real code"
```
`--diagnose` 在找到根本原因后停止,不修改您的文件。它会在 `.planning/debug/<slug>.md` 创建一个会话文件,以便您在需要时稍后继续调查。
@@ -57,36 +57,36 @@ GSD 会在下次运行时检测到这一情况,并弹出一个安全恢复确
要启动同时应用修复的完整调试会话:
```bash
/gsd-debug "Login middleware not handling 401 correctly after phase 3"
/msd-debug "Login middleware not handling 401 correctly after phase 3"
```
GSD 收集症状,使用科学方法进行结构化调查,并提出修复方案。如果您的配置中设置了 `tdd_mode: true`,则在应用任何修复之前需要先有一个失败的测试。
MSD 收集症状,使用科学方法进行结构化调查,并提出修复方案。如果您的配置中设置了 `tdd_mode: true`,则在应用任何修复之前需要先有一个失败的测试。
### 查看活动调试会话
```bash
/gsd-debug list
/msd-debug list
```
显示所有打开的会话及其当前假设和下一步操作。要恢复特定会话:
```bash
/gsd-debug continue <slug>
/msd-debug continue <slug>
```
---
## 使用 `/gsd-forensics` 进行事后分析
## 使用 `/msd-forensics` 进行事后分析
如果根本原因从错误输出中无法判断——例如,计划引用了不存在的文件、执行产生了意外结果,或状态似乎已损坏——请运行取证调查:
```bash
/gsd-forensics "Phase 3 execution stalled after wave 1"
/msd-forensics "Phase 3 execution stalled after wave 1"
```
GSD 分析 git 历史记录、`.planning/` 制品完整性、STATE.md 一致性、未提交的工作和孤立的 worktree。它将结构化报告写入 `.planning/forensics/report-<timestamp>.md`,并给出推荐的修复步骤。
MSD 分析 git 历史记录、`.planning/` 制品完整性、STATE.md 一致性、未提交的工作和孤立的 worktree。它将结构化报告写入 `.planning/forensics/report-<timestamp>.md`,并给出推荐的修复步骤。
`/gsd-forensics` 是只读的——它不会修改您的项目文件。
`/msd-forensics` 是只读的——它不会修改您的项目文件。
**可检测的问题:**
@@ -103,46 +103,46 @@ GSD 分析 git 历史记录、`.planning/` 制品完整性、STATE.md 一致性
一旦底层问题解决,重新运行执行命令:
```bash
/gsd-execute-phase 1
/msd-execute-phase 1
```
GSD 会跳过 `SUMMARY.md` 已存在的计划,仅为剩余计划分派执行器。
MSD 会跳过 `SUMMARY.md` 已存在的计划,仅为剩余计划分派执行器。
如果您只需要重新执行特定的 wave:
```bash
/gsd-execute-phase 1 --wave 2
/msd-execute-phase 1 --wave 2
```
---
## 使用 `/gsd-undo` 回滚
## 使用 `/msd-undo` 回滚
如果执行产生了您想完全丢弃的代码,请使用计划清单进行回滚,而不是手动 `git revert`:
### 回滚单个计划
```bash
/gsd-undo --plan 03-02
/msd-undo --plan 03-02
```
回滚阶段 `3` 中计划 `02` 的所有提交。GSD 在写入任何更改之前会显示确认界面。
回滚阶段 `3` 中计划 `02` 的所有提交。MSD 在写入任何更改之前会显示确认界面。
### 回滚整个阶段
```bash
/gsd-undo --phase 03
/msd-undo --phase 03
```
回滚阶段 `3` 的所有提交。GSD 会检查后续阶段是否依赖该阶段,并在继续之前发出警告。
回滚阶段 `3` 的所有提交。MSD 会检查后续阶段是否依赖该阶段,并在继续之前发出警告。
### 从最近的提交中交互式选择
```bash
/gsd-undo --last 5
/msd-undo --last 5
```
显示最近五个 GSD 提交,让您选择要回滚的内容。
显示最近五个 MSD 提交,让您选择要回滚的内容。
---
@@ -151,7 +151,7 @@ GSD 会跳过 `SUMMARY.md` 已存在的计划,仅为剩余计划分派执行
如果您在上下文重置或新会话后返回项目:
```bash
/gsd-resume-work
/msd-resume-work
```
从上次交接中恢复您的完整会话上下文,包括当前阶段、阻塞项以及执行停止的位置。
@@ -159,7 +159,7 @@ GSD 会跳过 `SUMMARY.md` 已存在的计划,仅为剩余计划分派执行
或者,要查看当前进度并自动跳转到下一个正确步骤:
```bash
/gsd-progress --next
/msd-progress --next
```
---

View File

@@ -2,13 +2,13 @@
**目标:** 生成一份已锁定的 UI 设计契约(`UI-SPEC.md`),在规划者编写任务之前,确定间距、颜色、字体和文案的决策,从而防止执行阶段因随意选择样式导致视觉不一致。
**前置条件:** `.planning/ROADMAP.md` 已存在,且该阶段包含前端或 UI 工作。强烈建议先运行 `/gsd-discuss-phase N`——UI 研究员会读取 `CONTEXT.md`,以避免重复询问您已经做出的决策。
**前置条件:** `.planning/ROADMAP.md` 已存在,且该阶段包含前端或 UI 工作。强烈建议先运行 `/msd-discuss-phase N`——UI 研究员会读取 `CONTEXT.md`,以避免重复询问您已经做出的决策。
---
## 判断此阶段是否需要 UI 契约
并非所有阶段都需要 `/gsd-ui-phase`。在以下情况下使用它:
并非所有阶段都需要 `/msd-ui-phase`。在以下情况下使用它:
- 该阶段引入新的 UI 界面(页面、流程、布局)
- 将构建多个组件,且视觉一致性至关重要
@@ -20,22 +20,22 @@
- 该阶段纯粹是后端、基础设施或数据工作,没有面向用户的输出
- 早期阶段已存在 UI-SPEC.md,且此阶段在完全相同的视觉模式上构建,不引入新界面
如果不确定,安全门会提示您:当 `workflow.ui_safety_gate` 启用时(默认启用),`/gsd-plan-phase` 在检测到前端工作但没有 UI-SPEC.md 时会发出警告,并询问是否先运行 `/gsd-ui-phase`。
如果不确定,安全门会提示您:当 `workflow.ui_safety_gate` 启用时(默认启用),`/msd-plan-phase` 在检测到前端工作但没有 UI-SPEC.md 时会发出警告,并询问是否先运行 `/msd-ui-phase`。
---
## 运行 UI 设计契约
```bash
/gsd-ui-phase 2
/msd-ui-phase 2
```
如果未指定阶段编号,GSD Core 会以当前阶段为目标。
如果未指定阶段编号,MSD Core 会以当前阶段为目标。
该命令分两个阶段运行:
1. **`gsd-ui-researcher`** — 读取 `CONTEXT.md`、`RESEARCH.md` 和 `REQUIREMENTS.md` 中的已有决策,检测设计系统状态(shadcn `components.json`、Tailwind 配置、现有 token),并仅针对以下五个领域中尚未回答的设计问题进行提问:间距、颜色、字体、文案和注册表安全。
2. **`gsd-ui-checker`** — 从七个维度验证生成的 `UI-SPEC.md`。如果发现问题,修订循环会重新运行研究员(最多两次迭代),专门针对被标记的项目。
1. **`msd-ui-researcher`** — 读取 `CONTEXT.md`、`RESEARCH.md` 和 `REQUIREMENTS.md` 中的已有决策,检测设计系统状态(shadcn `components.json`、Tailwind 配置、现有 token),并仅针对以下五个领域中尚未回答的设计问题进行提问:间距、颜色、字体、文案和注册表安全。
2. **`msd-ui-checker`** — 从七个维度验证生成的 `UI-SPEC.md`。如果发现问题,修订循环会重新运行研究员(最多两次迭代),专门针对被标记的项目。
**输出:** `.planning/phases/{phase-dir}/` 中的 `{padded_phase}-UI-SPEC.md`。
@@ -69,7 +69,7 @@
npx shadcn init --preset <paste>
```
预设字符串成为 GSD Core 规划产物中的一等公民,可在各阶段和里程碑间复现。
预设字符串成为 MSD Core 规划产物中的一等公民,可在各阶段和里程碑间复现。
---
@@ -82,13 +82,13 @@ npx shadcn view <component> # inspect source before installing
npx shadcn diff <component> # compare against the official registry
```
如果未处理注册表安全问题,检查器会将规格标记为 BLOCKED。若您的项目不使用 shadcn,或您有其他审查流程,可通过 `/gsd-settings` 禁用此门控。
如果未处理注册表安全问题,检查器会将规格标记为 BLOCKED。若您的项目不使用 shadcn,或您有其他审查流程,可通过 `/msd-settings` 禁用此门控。
---
## 使用草图发现结果作为起点
如果您已运行 `/gsd-sketch --wrap-up`,UI 研究员会自动加载 `.claude/skills/sketch-findings-[project]/`。经过预验证的决策(布局、调色板、字体、间距)将被视为已锁定——研究员不会重新询问它们。运行开始时会显示一条提示:
如果您已运行 `/msd-sketch --wrap-up`,UI 研究员会自动加载 `.claude/skills/sketch-findings-[project]/`。经过预验证的决策(布局、调色板、字体、间距)将被视为已锁定——研究员不会重新询问它们。运行开始时会显示一条提示:
```text
⚡ Sketch findings detected: .claude/skills/sketch-findings-[project]/SKILL.md
@@ -96,20 +96,20 @@ npx shadcn diff <component> # compare against the official registry
as locked — not re-asked.
```
这是在 `/gsd-ui-phase` 之前运行 `/gsd-sketch --wrap-up` 的主要原因:它将对话式的设计探索转化为具有约束力的契约输入。
这是在 `/msd-ui-phase` 之前运行 `/msd-sketch --wrap-up` 的主要原因:它将对话式的设计探索转化为具有约束力的契约输入。
---
## 使用 `/gsd-ui-review` 进行事后视觉审计
## 使用 `/msd-ui-review` 进行事后视觉审计
`/gsd-ui-review` 在执行之后运行,而非之前。用它来对照 UI-SPEC 审计已实现的前端(当没有规格时,则对照抽象的六支柱标准进行审计)。
`/msd-ui-review` 在执行之后运行,而非之前。用它来对照 UI-SPEC 审计已实现的前端(当没有规格时,则对照抽象的六支柱标准进行审计)。
```bash
/gsd-ui-review # audit the current phase
/gsd-ui-review 3 # audit phase 3 specifically
/msd-ui-review # audit the current phase
/msd-ui-review 3 # audit phase 3 specifically
```
它适用于任何包含前端代码的项目——不需要 GSD 项目初始化。
它适用于任何包含前端代码的项目——不需要 MSD 项目初始化。
**检查内容(六支柱,每项评分 1–4):**
@@ -120,24 +120,24 @@ npx shadcn diff <component> # compare against the official registry
5. 间距 — 网格对齐、token 一致性
6. 体验设计 — 加载、错误和空状态覆盖
**输出:** `{padded_phase}-UI-REVIEW.md`,包含评分和前三项优先修复事项。当配置了 `gsd-browser` 等浏览器 MCP 服务器时,审计还会捕获截图作为视觉证据。
**输出:** `{padded_phase}-UI-REVIEW.md`,包含评分和前三项优先修复事项。当配置了 `msd-browser` 等浏览器 MCP 服务器时,审计还会捕获截图作为视觉证据。
**截图存储:** 截图保存至 `.planning/ui-reviews/`。系统会自动创建 `.gitignore` 以防止二进制文件提交到 git。截图会在 `/gsd-complete-milestone` 期间清理。
**截图存储:** 截图保存至 `.planning/ui-reviews/`。系统会自动创建 `.gitignore` 以防止二进制文件提交到 git。截图会在 `/msd-complete-milestone` 期间清理。
---
## 在阶段生命周期中的推荐位置
```text
/gsd-discuss-phase N ← lock implementation preferences
/gsd-ui-phase N ← lock design contract (frontend phases)
/gsd-plan-phase N ← research + plan (reads UI-SPEC.md as context)
/gsd-execute-phase N ← parallel execution
/gsd-verify-work N ← manual UAT
/gsd-ui-review N ← retroactive visual audit (optional but recommended)
/msd-discuss-phase N ← lock implementation preferences
/msd-ui-phase N ← lock design contract (frontend phases)
/msd-plan-phase N ← research + plan (reads UI-SPEC.md as context)
/msd-execute-phase N ← parallel execution
/msd-verify-work N ← manual UAT
/msd-ui-review N ← retroactive visual audit (optional but recommended)
```
`/gsd-ui-phase` 位于 discuss 和 plan 之间,因为规划者会将 `UI-SPEC.md` 作为设计上下文读取——`PLAN.md` 中的任务会引用规格锁定的间距 token、颜色变量和文案决策。
`/msd-ui-phase` 位于 discuss 和 plan 之间,因为规划者会将 `UI-SPEC.md` 作为设计上下文读取——`PLAN.md` 中的任务会引用规格锁定的间距 token、颜色变量和文案决策。
---

View File

@@ -2,18 +2,18 @@
**目标:** 在规划开始之前收集某个阶段所需的实施决策,以便研究员和规划员无需再次询问您。
**前提条件:** `.planning/ROADMAP.md` 文件已存在。如果没有,请先运行 `/gsd-new-project`。
**前提条件:** `.planning/ROADMAP.md` 文件已存在。如果没有,请先运行 `/msd-new-project`。
---
## 选择讨论模式
GSD Core 提供两种模式。根据对代码库的熟悉程度进行选择。
MSD Core 提供两种模式。根据对代码库的熟悉程度进行选择。
**如果您想预先表达自己的实施偏好**(访谈模式,默认):
```bash
/gsd-discuss-phase 2
/msd-discuss-phase 2
```
Claude 会识别阶段范围中的模糊地带,让您选择要讨论的内容,然后针对每个领域处理大约四个问题。
@@ -21,8 +21,8 @@ Claude 会识别阶段范围中的模糊地带,让您选择要讨论的内容
**如果代码库已有明确的模式,且大多数问题对您来说显而易见**(假设模式):
```bash
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
/gsd-discuss-phase 2
node msd-tools.cjs config-set workflow.discuss_mode assumptions
/msd-discuss-phase 2
```
Claude 通过子代理读取 5–15 个相关代码库文件,形成带有证据和置信度级别的假设,并呈现给您确认或纠正。通常只需 2–4 次交互,而非 15–20 次。
@@ -30,7 +30,7 @@ Claude 通过子代理读取 5–15 个相关代码库文件,形成带有证
切换回原模式:
```bash
node gsd-tools.cjs config-set workflow.discuss_mode discuss
node msd-tools.cjs config-set workflow.discuss_mode discuss
```
请参阅[讨论模式说明](../workflow-discuss-mode.md)以获取完整对比,包括各模式可能节省时间的场景。
@@ -42,7 +42,7 @@ node gsd-tools.cjs config-set workflow.discuss_mode discuss
默认情况下,Claude 会呈现模糊地带并询问您希望覆盖哪些内容。如果您想跳过该选择提示,直接处理所有内容:
```bash
/gsd-discuss-phase 2 --all
/msd-discuss-phase 2 --all
```
---
@@ -52,7 +52,7 @@ node gsd-tools.cjs config-set workflow.discuss_mode discuss
**如果该阶段已充分理解,您希望 Claude 无需提示即可选择推荐的默认值:**
```bash
/gsd-discuss-phase 3 --auto
/msd-discuss-phase 3 --auto
```
Claude 为每个问题选择推荐答案并记录选择。适用于决策风险较低或已在先前阶段中隐含的阶段。
@@ -60,7 +60,7 @@ Claude 为每个问题选择推荐答案并记录选择。适用于决策风险
**如果您有远程会话限制(无 TUI 菜单):**
```bash
/gsd-discuss-phase 2 --text
/msd-discuss-phase 2 --text
```
所有提示将以纯文本编号列表的形式呈现,而不是交互式选择器。
@@ -72,7 +72,7 @@ Claude 为每个问题选择推荐答案并记录选择。适用于决策风险
如果您希望一次回答多个问题,而不是逐一回答:
```bash
/gsd-discuss-phase 2 --batch
/msd-discuss-phase 2 --batch
```
Claude 每轮分组 2–5 个问题。
@@ -84,7 +84,7 @@ Claude 每轮分组 2–5 个问题。
如果您希望在做出决定之前查看选项对比表:
```bash
/gsd-discuss-phase 2 --analyze
/msd-discuss-phase 2 --analyze
```
---
@@ -94,7 +94,7 @@ Claude 每轮分组 2–5 个问题。
如果您已有准备好的答案文件,并希望一次性提交所有决策:
```bash
/gsd-discuss-phase 1 --power
/msd-discuss-phase 1 --power
```
---
@@ -104,7 +104,7 @@ Claude 每轮分组 2–5 个问题。
**如果您希望在任何交互式会话之前了解 Claude 的假设和计划** — 适用于在投入讨论时间之前验证对齐情况:
```bash
/gsd-discuss-phase 3 --assumptions
/msd-discuss-phase 3 --assumptions
```
Claude 输出其假设(附带代码库证据和置信度级别)后退出。不会写入 CONTEXT.md。查看输出后,如有需要纠正的内容,再运行正常的讨论或假设模式会话。
@@ -132,9 +132,9 @@ Claude 输出其假设(附带代码库证据和置信度级别)后退出。
## 决策如何影响规划
当您接下来运行 `/gsd-plan-phase` 时,规划员会读取 CONTEXT.md 以了解哪些决策已锁定。它不会重新询问此处已回答的问题。研究员会首先读取该文件以了解需要调查的内容。
当您接下来运行 `/msd-plan-phase` 时,规划员会读取 CONTEXT.md 以了解哪些决策已锁定。它不会重新询问此处已回答的问题。研究员会首先读取该文件以了解需要调查的内容。
**如果运行 `/gsd-plan-phase` 时 CONTEXT.md 缺失**,系统将提供两种选择:不使用上下文继续(计划仅使用研究和需求,不包含您的设计偏好),或先运行 `/gsd-discuss-phase`。
**如果运行 `/msd-plan-phase` 时 CONTEXT.md 缺失**,系统将提供两种选择:不使用上下文继续(计划仅使用研究和需求,不包含您的设计偏好),或先运行 `/msd-discuss-phase`。
---
@@ -143,7 +143,7 @@ Claude 输出其假设(附带代码库证据和置信度级别)后退出。
完全跳过 discuss-phase,直接进入规划:
```bash
/gsd-plan-phase 1 --prd path/to/prd.md
/msd-plan-phase 1 --prd path/to/prd.md
```
规划员会从 PRD 综合生成 CONTEXT.md,并将所有需求视为锁定决策。

View File

@@ -1,8 +1,8 @@
# 如何从追踪器议题驱动 GSD Core
# 如何从追踪器议题驱动 MSD Core
**目标:** 将一个范围明确的 GitHub、Linear 或 Jira 议题,通过完整的 GSD 流水线从隔离工作区推进至合并 PR——仅使用 GSD Core 中已有的命令,无需任何自定义脚本或追踪器集成。
**目标:** 将一个范围明确的 GitHub、Linear 或 Jira 议题,通过完整的 MSD 流水线从隔离工作区推进至合并 PR——仅使用 MSD Core 中已有的命令,无需任何自定义脚本或追踪器集成。
**前提条件:** GSD Core 已安装。议题范围有边界、验收标准可观测,且无上游阻塞依赖。
**前提条件:** MSD Core 已安装。议题范围有边界、验收标准可观测,且无上游阻塞依赖。
有关该模式背后的概念与设计理由,请参阅[议题驱动编排详解](../issue-driven-orchestration.md)。
@@ -16,13 +16,13 @@
- **议题是独立的新工作** → 添加一个阶段:
```bash
/gsd-phase "描述与议题标题一致的内容"
/msd-phase "描述与议题标题一致的内容"
```
- **议题紧急,必须插入现有阶段之间** → 插入一个小数阶段:
```bash
/gsd-phase --insert 3 "Fix: 来自议题的描述"
/msd-phase --insert 3 "Fix: 来自议题的描述"
```
复制追踪器议题的 URL。您将在第三步中将其粘贴到 `CONTEXT.md`,以便在上下文压缩后仍保留可追溯性。
@@ -34,13 +34,13 @@
每个议题都有专属工作区——一个带有独立 `.planning/` 目录的 git worktree。未完成的工作、中止的计划和探索性提交均保留在 `main` 之外。
```bash
/gsd-workspace --new --name my-issue-slug --repos . --strategy worktree
/msd-workspace --new --name my-issue-slug --repos . --strategy worktree
```
继续操作前,切换到工作区目录:
```bash
cd ~/gsd-workspaces/my-issue-slug
cd ~/msd-workspaces/my-issue-slug
```
---
@@ -50,15 +50,15 @@ cd ~/gsd-workspaces/my-issue-slug
运行 discuss-phase,在规划开始之前确定实现决策。会话打开后,将追踪器议题 URL 粘贴到讨论中,以便记录到 `CONTEXT.md`。
```bash
/gsd-discuss-phase N
/msd-discuss-phase N
```
GSD 会就议题范围中的模糊点进行提问——错误处理、边界情况、接口契约、技术选型。您的回答将影响后续生成的计划。
MSD 会就议题范围中的模糊点进行提问——错误处理、边界情况、接口契约、技术选型。您的回答将影响后续生成的计划。
如果您已知晓所有答案并希望快速推进:
```bash
/gsd-discuss-phase N --auto
/msd-discuss-phase N --auto
```
---
@@ -66,22 +66,22 @@ GSD 会就议题范围中的模糊点进行提问——错误处理、边界情
## 第四步:规划阶段
```bash
/gsd-plan-phase N
/msd-plan-phase N
```
GSD 会派生研究代理,读取您的 `CONTEXT.md` 决策(包括议题 URL),并生成原子化的 `PLAN.md` 文件。计划检查器会在保存前验证每份计划。
MSD 会派生研究代理,读取您的 `CONTEXT.md` 决策(包括议题 URL),并生成原子化的 `PLAN.md` 文件。计划检查器会在保存前验证每份计划。
如果您希望在执行前由外部 AI CLI 进行同行评审(对于重大变更推荐使用):
```bash
/gsd-review --phase N
/gsd-plan-phase N --reviews
/msd-review --phase N
/msd-plan-phase N --reviews
```
或运行完整的计划-评审-收敛循环,直到不再有 HIGH 级别的问题:
```bash
/gsd-plan-review-convergence N
/msd-plan-review-convergence N
```
---
@@ -91,19 +91,19 @@ GSD 会派生研究代理,读取您的 `CONTEXT.md` 决策(包括议题 URL
交互式逐阶段执行:
```bash
/gsd-execute-phase N
/msd-execute-phase N
```
无人值守地运行所有剩余阶段:
```bash
/gsd-autonomous
/msd-autonomous
```
在可视化仪表盘中监控进度并跨阶段调度工作:
```bash
/gsd-manager
/msd-manager
```
三种方式均会更新 `STATE.md`,原子化提交每项任务,并运行阶段后验证器。
@@ -113,10 +113,10 @@ GSD 会派生研究代理,读取您的 `CONTEXT.md` 决策(包括议题 URL
## 第六步:验证工作
```bash
/gsd-verify-work N
/msd-verify-work N
```
GSD 会逐条引导您核对阶段目标中的验收标准(与追踪器议题对应)。如有失败,GSD 会诊断根本原因并创建修复计划。重复执行和重新验证,直到所有检查通过。
MSD 会逐条引导您核对阶段目标中的验收标准(与追踪器议题对应)。如有失败,MSD 会诊断根本原因并创建修复计划。重复执行和重新验证,直到所有检查通过。
即使代码看起来正确,也应将 `verification_failed` 视为阻塞——失败通常会揭示原始议题中遗漏的验收标准。
@@ -127,17 +127,17 @@ GSD 会逐条引导您核对阶段目标中的验收标准(与追踪器议题
在开启 PR 前先进行代码评审:
```bash
/gsd-code-review N
/gsd-code-review N --fix
/msd-code-review N
/msd-code-review N --fix
```
然后创建 PR:
```bash
/gsd-ship N
/msd-ship N
```
GSD 会从您的规划产物中组装 PR 正文:阶段目标、变更摘要、已满足的需求、验证状态和关键决策。在 PR 正文中加入 `Closes #NNN` 或 `Fixes #NNN`(或通过 `/gsd-config` 设置),以便在 PR 合并时自动关闭追踪器议题。
MSD 会从您的规划产物中组装 PR 正文:阶段目标、变更摘要、已满足的需求、验证状态和关键决策。在 PR 正文中加入 `Closes #NNN` 或 `Fixes #NNN`(或通过 `/msd-config` 设置),以便在 PR 合并时自动关闭追踪器议题。
---
@@ -146,12 +146,12 @@ GSD 会从您的规划产物中组装 PR 正文:阶段目标、变更摘要、
在处理议题的过程中,您常常会发现相关工作。在不丢失上下文的情况下进行记录:
```bash
/gsd-capture "Follow-up: 发现的工作描述" # 作为待办事项添加
/gsd-capture --seed "值得未来阶段考虑的想法" # 为下一个里程碑保留
/gsd-capture --backlog "不紧急但值得跟踪的内容" # 存入待办列表
/msd-capture "Follow-up: 发现的工作描述" # 作为待办事项添加
/msd-capture --seed "值得未来阶段考虑的想法" # 为下一个里程碑保留
/msd-capture --backlog "不紧急但值得跟踪的内容" # 存入待办列表
```
GSD 不会自动向追踪器发布内容。从已记录的后续工作中创建追踪器议题是独立的手动步骤——这保留了人工审核的环节。
MSD 不会自动向追踪器发布内容。从已记录的后续工作中创建追踪器议题是独立的手动步骤——这保留了人工审核的环节。
---
@@ -159,12 +159,12 @@ GSD 不会自动向追踪器发布内容。从已记录的后续工作中创建
| 情境 | 处理方式 |
|-----------|-----------|
| 议题非常小(拼写错误、配置变更) | 跳过工作区 + 讨论 + 规划;改用 `/gsd-quick` |
| 议题包含多个独立子任务 | 使用 `/gsd-manager` 跨计划并行执行 |
| 议题被其他议题阻塞 | 在上游阻塞解除前不要开始;GSD 没有自动依赖轮询 |
| 执行中途发现议题范围比预期大 | 停止,运行 `/gsd-phase --insert N` 添加子阶段,然后继续 |
| 想跳过交互式讨论 | 对 `/gsd-discuss-phase` 使用 `--auto` 标志,或为项目级自动化设置 `workflow.skip_discuss: true` |
| 多个议题构成一个连贯的发布版本 | 运行 `/gsd-new-milestone` 将其分组,并运行 `/gsd-autonomous` 按顺序执行 |
| 议题非常小(拼写错误、配置变更) | 跳过工作区 + 讨论 + 规划;改用 `/msd-quick` |
| 议题包含多个独立子任务 | 使用 `/msd-manager` 跨计划并行执行 |
| 议题被其他议题阻塞 | 在上游阻塞解除前不要开始;MSD 没有自动依赖轮询 |
| 执行中途发现议题范围比预期大 | 停止,运行 `/msd-phase --insert N` 添加子阶段,然后继续 |
| 想跳过交互式讨论 | 对 `/msd-discuss-phase` 使用 `--auto` 标志,或为项目级自动化设置 `workflow.skip_discuss: true` |
| 多个议题构成一个连贯的发布版本 | 运行 `/msd-new-milestone` 将其分组,并运行 `/msd-autonomous` 按顺序执行 |
---

View File

@@ -2,19 +2,19 @@
**目标:** 通过基于波次的并行执行来运行已规划的阶段,并将每个计划作为原子性 git 提交落地。
**前置条件:** 该阶段至少有一个 `PLAN.md` 文件。如果规划尚未完成,请先运行 `/gsd-plan-phase N` —— 参见[规划阶段](plan-a-phase.md)。
**前置条件:** 该阶段至少有一个 `PLAN.md` 文件。如果规划尚未完成,请先运行 `/msd-plan-phase N` —— 参见[规划阶段](plan-a-phase.md)。
---
## 运行完整阶段
```bash
/gsd-execute-phase 1
/msd-execute-phase 1
```
GSD Core 读取阶段的计划文件,将其按依赖关系分组为若干波次,并为每个计划生成独立的执行器代理。每个执行器在下一波次开始前以原子方式提交其工作。
MSD Core 读取阶段的计划文件,将其按依赖关系分组为若干波次,并为每个计划生成独立的执行器代理。每个执行器在下一波次开始前以原子方式提交其工作。
在分发任何代理之前,GSD Core 会打印波次表:
在分发任何代理之前,MSD Core 会打印波次表:
```
## Execution Plan
@@ -38,24 +38,24 @@ Phase 1: Core middleware — 3 plans across 2 wave(s)
如果只想执行一个波次——例如,在进入第 2 波次之前先检查第 1 波次的输出——请使用 `--wave N`:
```bash
/gsd-execute-phase 1 --wave 2
/msd-execute-phase 1 --wave 2
```
GSD Core 仅执行第 2 波次的计划。它会首先检查所有较早波次是否已完成;如果任何第 1 波次计划仍标记为未完成,则会停止并提示你先完成较早波次。
MSD Core 仅执行第 2 波次的计划。它会首先检查所有较早波次是否已完成;如果任何第 1 波次计划仍标记为未完成,则会停止并提示你先完成较早波次。
---
## 恢复停滞的执行
如果执行中途停止——配额错误、网络断开或会话崩溃——波次级别的进度会被保留。GSD Core 会检查每个计划的 `SUMMARY.md` 文件;已有该文件的计划在重新运行时会自动跳过:
如果执行中途停止——配额错误、网络断开或会话崩溃——波次级别的进度会被保留。MSD Core 会检查每个计划的 `SUMMARY.md` 文件;已有该文件的计划在重新运行时会自动跳过:
```bash
/gsd-execute-phase 1
/msd-execute-phase 1
```
GSD Core 会跳过 `SUMMARY.md` 已存在的计划,并从第一个未完成的计划继续。
MSD Core 会跳过 `SUMMARY.md` 已存在的计划,并从第一个未完成的计划继续。
**如果提交存在但 `SUMMARY.md` 缺失**(执行器已提交,但在会话结束前未写入摘要),GSD Core 会弹出一个安全恢复门并提供三个选项:
**如果提交存在但 `SUMMARY.md` 缺失**(执行器已提交,但在会话结束前未写入摘要),MSD Core 会弹出一个安全恢复门并提供三个选项:
- `close out manually` — 检查提交,手动编写 `SUMMARY.md`,然后重新运行。
- `re-execute from scratch` — 在分发新执行器前回滚或替代部分提交。
@@ -88,13 +88,13 @@ Git 历史记录中每个任务会有一个提交(来自各执行器),随
要将执行委托给在 `workflow.cross_ai_command` 中配置的外部 AI CLI(Codex、Antigravity 等):
```bash
/gsd-execute-phase 2 --cross-ai
/msd-execute-phase 2 --cross-ai
```
要在配置中启用跨 AI 时强制本地执行:
```bash
/gsd-execute-phase 2 --no-cross-ai
/msd-execute-phase 2 --no-cross-ai
```
---

View File

@@ -1,6 +1,6 @@
# 如何处理快速轻量级任务
并非每项工作都需要完整的阶段流程。GSD 提供了两个轻量级命令,适用于不需要完整的讨论 → 计划 → 执行 → 验证循环的工作。
并非每项工作都需要完整的阶段流程。MSD 提供了两个轻量级命令,适用于不需要完整的讨论 → 计划 → 执行 → 验证循环的工作。
有关何时值得使用完整阶段流水线的说明,请参阅[上下文工程](../explanation/context-engineering.md)。
@@ -10,30 +10,30 @@
| 场景 | 命令 |
|-----------|---------|
| 修复 Bug、添加小功能,或任何无法概括为单一琐碎编辑的任务 | `/gsd-quick` |
| 修复错别字、更新配置值、添加 `.gitignore` 条目,或任何涉及 ≤ 3 个文件且耗时不到一分钟的更改 | `/gsd-fast` |
| 任务有未知因素、需要调研,或将涉及超过几个文件 | `/gsd-quick` 加 `--research` |
| 修复 Bug、添加小功能,或任何无法概括为单一琐碎编辑的任务 | `/msd-quick` |
| 修复错别字、更新配置值、添加 `.gitignore` 条目,或任何涉及 ≤ 3 个文件且耗时不到一分钟的更改 | `/msd-fast` |
| 任务有未知因素、需要调研,或将涉及超过几个文件 | `/msd-quick` 加 `--research` |
**经验法则:** 如果你哪怕有一刻犹豫该任务是否属于琐碎操作,就使用 `/gsd-quick`。当范围看起来不够简单时,`/gsd-fast` 会自动将你重定向到 `/gsd-quick`。
**经验法则:** 如果你哪怕有一刻犹豫该任务是否属于琐碎操作,就使用 `/msd-quick`。当范围看起来不够简单时,`/msd-fast` 会自动将你重定向到 `/msd-quick`。
---
## `/gsd-quick` — 带有 GSD 保证的临时任务
## `/msd-quick` — 带有 MSD 保证的临时任务
`/gsd-quick` 运行一个规划器和执行器,提供与完整阶段相同的原子提交和 STATE.md 跟踪保证,但无需阶段开销(无 ROADMAP 条目、无讨论阶段、无跨多个计划的波次协调)。
`/msd-quick` 运行一个规划器和执行器,提供与完整阶段相同的原子提交和 STATE.md 跟踪保证,但无需阶段开销(无 ROADMAP 条目、无讨论阶段、无跨多个计划的波次协调)。
### 基本用法
```bash
/gsd-quick
/msd-quick
```
GSD 会提示你输入任务描述,然后进行规划和执行。产出物保存在 `.planning/quick/` 中。
MSD 会提示你输入任务描述,然后进行规划和执行。产出物保存在 `.planning/quick/` 中。
你也可以直接传入描述:
```bash
/gsd-quick "Fix the login button not responding on mobile Safari"
/msd-quick "Fix the login button not responding on mobile Safari"
```
### 标志
@@ -50,9 +50,9 @@ GSD 会提示你输入任务描述,然后进行规划和执行。产出物保
标志可自由组合:
```bash
/gsd-quick --research --validate # research + plan-checking + verification, no discuss
/gsd-quick --discuss # just surface grey areas before planning
/gsd-quick --full # the complete quality pipeline
/msd-quick --research --validate # research + plan-checking + verification, no discuss
/msd-quick --discuss # just surface grey areas before planning
/msd-quick --full # the complete quality pipeline
```
### 何时添加标志
@@ -65,38 +65,38 @@ GSD 会提示你输入任务描述,然后进行规划和执行。产出物保
### 列出和恢复快速任务
```bash
/gsd-quick list # show all quick tasks with status
/gsd-quick status my-task-slug # show status of a specific task
/gsd-quick resume my-task-slug # resume an interrupted task
/msd-quick list # show all quick tasks with status
/msd-quick status my-task-slug # show status of a specific task
/msd-quick resume my-task-slug # resume an interrupted task
```
---
## `/gsd-fast` — 内联琐碎编辑
## `/msd-fast` — 内联琐碎编辑
`/gsd-fast` 直接在当前上下文中完成工作。没有子代理、没有 `PLAN.md`,也没有调研。它仅适用于你自己在一分钟内即可完成的更改。
`/msd-fast` 直接在当前上下文中完成工作。没有子代理、没有 `PLAN.md`,也没有调研。它仅适用于你自己在一分钟内即可完成的更改。
```bash
/gsd-fast "fix typo in README"
/gsd-fast "add .env to .gitignore"
/msd-fast "fix typo in README"
/msd-fast "add .env to .gitignore"
```
如果你省略描述,GSD 会提示你输入。
如果你省略描述,MSD 会提示你输入。
`/gsd-fast` 在继续操作前会检查任务是否确实属于琐碎操作。如果判断范围过大,它会停止并重定向你:
`/msd-fast` 在继续操作前会检查任务是否确实属于琐碎操作。如果判断范围过大,它会停止并重定向你:
```text
This looks like it needs planning. Use /gsd-quick instead:
/gsd-quick "your task description"
This looks like it needs planning. Use /msd-quick instead:
/msd-quick "your task description"
```
完成更改后,`/gsd-fast` 以原子方式提交,并且如果 `.planning/STATE.md` 中存在 `Quick Tasks Completed` 表格,则向其追加一行。
完成更改后,`/msd-fast` 以原子方式提交,并且如果 `.planning/STATE.md` 中存在 `Quick Tasks Completed` 表格,则向其追加一行。
---
## `/gsd-quick` 相比 `/gsd-fast` 多提供的能力
## `/msd-quick` 相比 `/msd-fast` 多提供的能力
| 能力 | `/gsd-fast` | `/gsd-quick` |
| 能力 | `/msd-fast` | `/msd-quick` |
|------------|------------|--------------|
| 子代理规划器 | 否 | 是 |
| 子代理执行器 | 否 | 是 |
@@ -109,7 +109,7 @@ This looks like it needs planning. Use /gsd-quick instead:
| STATE.md 跟踪 | 若表格存在则追加行 | 始终更新 |
| `.planning/quick/` 产出物 | 否 | 是 |
关键区别在于子代理隔离。`/gsd-quick` 在独立的上下文窗口中启动全新的规划器和执行器,这意味着工作会被妥善规划,提交按任务原子化,且编排器可验证结果。`/gsd-fast` 仅使用当前上下文窗口,有意限制于无需上述任何流程的琐碎更改。
关键区别在于子代理隔离。`/msd-quick` 在独立的上下文窗口中启动全新的规划器和执行器,这意味着工作会被妥善规划,提交按任务原子化,且编排器可验证结果。`/msd-fast` 仅使用当前上下文窗口,有意限制于无需上述任何流程的琐碎更改。
---

View File

@@ -1,6 +1,6 @@
# 如何在您的运行时上安装 GSD Core
# 如何在您的运行时上安装 MSD Core
将 GSD Core(`@opengsd/gsd-core`)安装到您日常使用的 AI 编码运行时中。本指南提供各支持运行时的标准安装路径,以及适用于未安装 Node.js 的机器的手动安装路径。
将 MSD Core(`@golem15/msd-core`)安装到您日常使用的 AI 编码运行时中。本指南提供各支持运行时的标准安装路径,以及适用于未安装 Node.js 的机器的手动安装路径。
**所需条件:** Node.js 18+ 及 npm(或 npx)。如果您没有 Node.js,请跳转至[不使用 Node.js 安装](#不使用-nodejs-安装)。
@@ -8,7 +8,7 @@
## 为什么需要安装程序
GSD Core 以 Claude Code 原生 frontmatter 格式分发代理和命令文件。每个支持的运行时需要不同的 schema、目录结构和命令调用语法。安装程序负责执行必要的转换——例如,为 OpenCode 转换工具列表和颜色值、为 Codex 写入 TOML 代理条目。
MSD Core 以 Claude Code 原生 frontmatter 格式分发代理和命令文件。每个支持的运行时需要不同的 schema、目录结构和命令调用语法。安装程序负责执行必要的转换——例如,为 OpenCode 转换工具列表和颜色值、为 Codex 写入 TOML 代理条目。
**请勿直接从 `agents/` 或 `commands/` 复制文件。** 这样做会绕过转换过程,导致 schema 验证错误或命令缺失。
@@ -19,7 +19,7 @@ GSD Core 以 Claude Code 原生 frontmatter 格式分发代理和命令文件。
在任意目录运行安装程序。它会提示您选择运行时,以及是全局安装(所有项目)还是本地安装(仅此项目)。
```bash
npx @opengsd/gsd-core@latest
npx @golem15/msd-core@latest
```
这是全新安装或切换运行时后重新运行安装程序所需的唯一命令。
@@ -31,17 +31,17 @@ npx @opengsd/gsd-core@latest
### Claude Code
```bash
npx @opengsd/gsd-core@latest --claude --global
npx @golem15/msd-core@latest --claude --global
```
技能文件存放于 `~/.claude/`。下次 Claude Code 会话中,命令将以 `/gsd-*` 斜杠命令的形式出现。重启 Claude Code 以加载它们。
技能文件存放于 `~/.claude/`。下次 Claude Code 会话中,命令将以 `/msd-*` 斜杠命令的形式出现。重启 Claude Code 以加载它们。
**同时在 `--global` 和 `--local` 两个作用域安装。** 这是受支持的配置(不同项目有时需要不同的自定义配置),但 Claude Code 自身的触发器解析规则——个人作用域覆盖项目作用域,且技能(skill)覆盖同名命令——都指向同一个方向:全局技能总是在 `/gsd-<name>` 触发器上胜过本地命令。GSD Core 会检测到这一点,并在安装完成后立即打印出哪个作用域胜出(并通过 `/gsd-health` 以诊断代码 `W028` 呈现相同的事实);这只是一条提示,不是失败——安装本身仍然会成功。在**全局**作用域下,胜出技能的工作流规范引用会在运行时优先相对于你的工作目录解析,因此即使 Claude Code 实际调用的是全局技能,拥有自己 `.claude/gsd-core/` 的项目仍然能获取到自己的规范。
**同时在 `--global` 和 `--local` 两个作用域安装。** 这是受支持的配置(不同项目有时需要不同的自定义配置),但 Claude Code 自身的触发器解析规则——个人作用域覆盖项目作用域,且技能(skill)覆盖同名命令——都指向同一个方向:全局技能总是在 `/msd-<name>` 触发器上胜过本地命令。MSD Core 会检测到这一点,并在安装完成后立即打印出哪个作用域胜出(并通过 `/msd-health` 以诊断代码 `W028` 呈现相同的事实);这只是一条提示,不是失败——安装本身仍然会成功。在**全局**作用域下,胜出技能的工作流规范引用会在运行时优先相对于你的工作目录解析,因此即使 Claude Code 实际调用的是全局技能,拥有自己 `.claude/msd-core/` 的项目仍然能获取到自己的规范。
**覆盖安装目录:**
```bash
CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
CLAUDE_CONFIG_DIR=~/.claude-alt npx @golem15/msd-core@latest --claude --global
```
---
@@ -49,7 +49,7 @@ CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
### OpenCode
```bash
npx @opengsd/gsd-core@latest --opencode --global
npx @golem15/msd-core@latest --opencode --global
```
技能文件存放于 `~/.config/opencode/`(XDG)或 `~/.opencode/`。安装程序将代理 frontmatter 转换为 OpenCode 的 schema——移除 `tools:` 字段并将颜色值转换为十六进制格式。如需了解具体变更内容,请参阅[不使用 Node.js 安装 — OpenCode 转换](#opencode--必要转换)。
@@ -57,7 +57,7 @@ npx @opengsd/gsd-core@latest --opencode --global
**覆盖安装目录:**
```bash
OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --opencode --global
OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @golem15/msd-core@latest --opencode --global
```
---
@@ -65,7 +65,7 @@ OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --openco
### Kilo
```bash
npx @opengsd/gsd-core@latest --kilo --global
npx @golem15/msd-core@latest --kilo --global
```
技能文件存放于 `~/.config/kilo/`(XDG)或 `~/.kilo/`。使用与 OpenCode 相同的平铺 Markdown 命令格式。
@@ -73,7 +73,7 @@ npx @opengsd/gsd-core@latest --kilo --global
**覆盖安装目录:**
```bash
KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
KILO_CONFIG_DIR=~/.config/kilo-alt npx @golem15/msd-core@latest --kilo --global
```
---
@@ -81,10 +81,10 @@ KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
### Codex
```bash
npx @opengsd/gsd-core@latest --codex --global
npx @golem15/msd-core@latest --codex --global
```
技能文件存放于 `~/.codex/skills/gsd-*/SKILL.md`。代理以每个代理独立的 TOML 条目写入 `config.toml`。安装后重启 Codex(或运行 `codex --reload`)。
技能文件存放于 `~/.codex/skills/msd-*/SKILL.md`。代理以每个代理独立的 TOML 条目写入 `config.toml`。安装后重启 Codex(或运行 `codex --reload`)。
**最低支持版本:** Codex CLI 0.130.0。更早版本额外扫描技能根目录,可能导致重复列出条目。
@@ -93,15 +93,15 @@ npx @opengsd/gsd-core@latest --codex --global
### GitHub Copilot
```bash
npx @opengsd/gsd-core@latest --copilot --global
npx @golem15/msd-core@latest --copilot --global
```
技能文件存放于 `~/.copilot/`。GSD 以代理 `.md` 文件和仓库指令文件的形式安装。
技能文件存放于 `~/.copilot/`。MSD 以代理 `.md` 文件和仓库指令文件的形式安装。
**覆盖安装目录:**
```bash
COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --global
COPILOT_CONFIG_DIR=~/.copilot-alt npx @golem15/msd-core@latest --copilot --global
```
---
@@ -109,15 +109,15 @@ COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --globa
### Cursor
```bash
npx @opengsd/gsd-core@latest --cursor --global
npx @golem15/msd-core@latest --cursor --global
```
技能文件存放于 `~/.cursor/`。GSD 安装技能、代理和规则引用。
技能文件存放于 `~/.cursor/`。MSD 安装技能、代理和规则引用。
**覆盖安装目录:**
```bash
CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global
CURSOR_CONFIG_DIR=~/.cursor-alt npx @golem15/msd-core@latest --cursor --global
```
---
@@ -125,29 +125,29 @@ CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global
### Windsurf
```bash
npx @opengsd/gsd-core@latest --windsurf --global
npx @golem15/msd-core@latest --windsurf --global
```
技能文件存放于 `~/.codeium/windsurf/`。GSD 安装技能、代理和工作区规则。
技能文件存放于 `~/.codeium/windsurf/`。MSD 安装技能、代理和工作区规则。
**覆盖安装目录:**
```bash
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @opengsd/gsd-core@latest --windsurf --global
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @golem15/msd-core@latest --windsurf --global
```
---
### Cline
Cline 使用基于规则的集成方式——GSD 以 `.clinerules` 形式安装,而非斜杠命令。
Cline 使用基于规则的集成方式——MSD 以 `.clinerules` 形式安装,而非斜杠命令。
```bash
# 全局安装(所有项目)
npx @opengsd/gsd-core@latest --cline --global
npx @golem15/msd-core@latest --cline --global
# 本地安装(仅此项目)
npx @opengsd/gsd-core@latest --cline --local
npx @golem15/msd-core@latest --cline --local
```
全局安装写入 `~/.cline/`。本地安装写入 `./.cline/`。规则由 Cline 自动加载——不注册自定义斜杠命令。
@@ -157,10 +157,10 @@ npx @opengsd/gsd-core@latest --cline --local
### CodeBuddy
```bash
npx @opengsd/gsd-core@latest --codebuddy --global
npx @golem15/msd-core@latest --codebuddy --global
```
技能文件存放于 `~/.codebuddy/skills/gsd-*/SKILL.md`。
技能文件存放于 `~/.codebuddy/skills/msd-*/SKILL.md`。
---
@@ -169,15 +169,15 @@ npx @opengsd/gsd-core@latest --codebuddy --global
Qwen Code 使用与 Claude Code 2.1.88+ 相同的开放技能标准。
```bash
npx @opengsd/gsd-core@latest --qwen --global
npx @golem15/msd-core@latest --qwen --global
```
技能文件存放于 `~/.qwen/skills/gsd-*/SKILL.md`。
技能文件存放于 `~/.qwen/skills/msd-*/SKILL.md`。
**覆盖安装目录:**
```bash
QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
QWEN_CONFIG_DIR=~/.qwen-alt npx @golem15/msd-core@latest --qwen --global
```
---
@@ -185,17 +185,17 @@ QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
### Augment Code
```bash
npx @opengsd/gsd-core@latest --augment --global
npx @golem15/msd-core@latest --augment --global
```
技能文件存放于 `~/.augment/`。GSD 安装技能和代理,不拥有 hook 或状态栏所有权。
技能文件存放于 `~/.augment/`。MSD 安装技能和代理,不拥有 hook 或状态栏所有权。
---
### Antigravity
```bash
npx @opengsd/gsd-core@latest --antigravity --global
npx @golem15/msd-core@latest --antigravity --global
```
安装程序自动检测 Antigravity 配置目录(`~/.gemini/antigravity`、`~/.gemini/antigravity-ide` 或 `~/.gemini/antigravity-cli`)。使用与 Gemini 兼容的设置策略。
@@ -203,7 +203,7 @@ npx @opengsd/gsd-core@latest --antigravity --global
**覆盖安装目录:**
```bash
ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --antigravity --global
ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @golem15/msd-core@latest --antigravity --global
```
---
@@ -211,19 +211,19 @@ ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --
### Trae
```bash
npx @opengsd/gsd-core@latest --trae --global
npx @golem15/msd-core@latest --trae --global
```
技能文件存放于 `~/.trae/`。GSD 安装技能、代理和规则引用。
技能文件存放于 `~/.trae/`。MSD 安装技能、代理和规则引用。
---
## 本地安装与全局安装
上述所有示例均使用 `--global`,即为您的用户账户全局安装 GSD。若要将安装范围限定到单个项目,请将 `--global` 替换为 `--local`:
上述所有示例均使用 `--global`,即为您的用户账户全局安装 MSD。若要将安装范围限定到单个项目,请将 `--global` 替换为 `--local`:
```bash
npx @opengsd/gsd-core@latest --claude --local
npx @golem15/msd-core@latest --claude --local
```
本地安装写入项目根目录下的 `.claude/` 目录。当全局安装和本地安装同时存在时,本地安装的设置优先于全局设置。
@@ -235,10 +235,10 @@ npx @opengsd/gsd-core@latest --claude --local
运行时的预发布版(Windsurf Next、Cursor Nightly、VS Code Insiders、Codex 预览通道等)从同级配置目录读取配置。在运行安装程序前设置对应的 `*_CONFIG_DIR` 环境变量:
```bash
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @golem15/msd-core@latest --windsurf --global
```
在安装程序提示中选择对应的稳定版运行时。GSD 不将预发布版作为独立命名运行时枚举——它们通过此环境变量机制提供尽力支持,不在发布 CI 中单独测试。
在安装程序提示中选择对应的稳定版运行时。MSD 不将预发布版作为独立命名运行时枚举——它们通过此环境变量机制提供尽力支持,不在发布 CI 中单独测试。
---
@@ -249,11 +249,11 @@ WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --wind
**方案 A——使用有 Node.js 的机器。** 任何有 Node.js 的机器均可:WSL、Linux 虚拟机、CI runner 或 Docker 容器。在那台机器上运行安装程序,然后将输出目录复制到目标机器。以 OpenCode 为例:
```bash
npx @opengsd/gsd-core@latest --opencode --global
npx @golem15/msd-core@latest --opencode --global
# 然后将 ~/.config/opencode/agents/ 复制到 Windows 机器
```
**方案 B——手动转换源文件。** 代理源文件位于 GSD Core 仓库的 `agents/` 目录下,格式为 Claude Code 原生 frontmatter 格式。每个运行时期望不同的结构。有关各运行时的具体字段转换说明,请参阅用户指南中的[手动安装 / 无 Node.js 设置](../USER-GUIDE.md#manual-install--no-nodejs-setup),其中详细介绍了 OpenCode 的转换内容,并指向安装程序中其他运行时对应的 `convert*Frontmatter` 函数。
**方案 B——手动转换源文件。** 代理源文件位于 MSD Core 仓库的 `agents/` 目录下,格式为 Claude Code 原生 frontmatter 格式。每个运行时期望不同的结构。有关各运行时的具体字段转换说明,请参阅用户指南中的[手动安装 / 无 Node.js 设置](../USER-GUIDE.md#manual-install--no-nodejs-setup),其中详细介绍了 OpenCode 的转换内容,并指向安装程序中其他运行时对应的 `convert*Frontmatter` 函数。
---
@@ -262,8 +262,8 @@ npx @opengsd/gsd-core@latest --opencode --global
重启您的运行时以加载新命令和代理。然后启动新项目或接入现有仓库:
```bash
/gsd-new-project # 新建项目
/gsd-onboard # 现有代码库
/msd-new-project # 新建项目
/msd-onboard # 现有代码库
```
如果重启后找不到该命令,请确认安装目录与运行时预期的配置路径匹配。上方的预发布版章节介绍了最常见的路径不匹配情况。
@@ -273,6 +273,6 @@ npx @opengsd/gsd-core@latest --opencode --global
## 相关链接
- [您的第一个项目](../tutorials/your-first-project.md)
- [更新 GSD Core](update-gsd.md)
- [更新 MSD Core](update-msd.md)
- [配置](../CONFIGURATION.md)
- [文档索引](../README.md)

View File

@@ -1,6 +1,6 @@
# 如何使用工作区隔离工作
**目标:** 创建一个完全隔离的 GSD 环境——独立的 git worktree、独立的 `.planning/` 根目录,以及可选的多仓库支持——适用于功能分支或多仓库工作场景。
**目标:** 创建一个完全隔离的 MSD 环境——独立的 git worktree、独立的 `.planning/` 根目录,以及可选的多仓库支持——适用于功能分支或多仓库工作场景。
**前提条件:** 已安装 `git` 且仓库支持 worktree。对于多仓库工作区,目标仓库需存在于本地或可通过路径访问。
@@ -14,13 +14,13 @@
- 独立的 `WORKSPACE.md` 清单文件,用于跟踪成员仓库
- git worktree(默认)或指定仓库的完整克隆,在专用分支上检出(默认:`workspace/<name>`)
工作区默认存放在 `~/gsd-workspaces/<name>/` 下。
工作区默认存放在 `~/msd-workspaces/<name>/` 下。
```
~/gsd-workspaces/
~/msd-workspaces/
└── feature-b/
├── WORKSPACE.md ← 清单文件
├── .planning/ ← 完全独立的 GSD 状态
├── .planning/ ← 完全独立的 MSD 状态
│ ├── PROJECT.md
│ ├── ROADMAP.md
│ └── ...
@@ -35,15 +35,15 @@
## 为多个仓库创建工作区
```bash
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
/msd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
```
GSD 会在 `~/gsd-workspaces/feature-b/` 中创建 `hr-ui` 和 `ZeymoAPI` 的 worktree,在每个仓库中检出 `workspace/feature-b` 分支,写入 `WORKSPACE.md`,并创建一个空的 `.planning/` 目录,准备好供 `/gsd-new-project` 使用。
MSD 会在 `~/msd-workspaces/feature-b/` 中创建 `hr-ui` 和 `ZeymoAPI` 的 worktree,在每个仓库中检出 `workspace/feature-b` 分支,写入 `WORKSPACE.md`,并创建一个空的 `.planning/` 目录,准备好供 `/msd-new-project` 使用。
自定义位置:
```bash
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI --path /projects/feature-b
/msd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI --path /projects/feature-b
```
---
@@ -53,7 +53,7 @@ GSD 会在 `~/gsd-workspaces/feature-b/` 中创建 `hr-ui` 和 `ZeymoAPI` 的 wo
当你需要在单个仓库上进行功能分支隔离——独立分支、独立 `.planning/`、不受 main 分支状态影响时:
```bash
/gsd-workspace --new --name payments-rework --repos .
/msd-workspace --new --name payments-rework --repos .
```
`.` 表示为当前仓库创建 worktree,该 worktree 会在 `workspace/payments-rework` 分支上检出。
@@ -61,7 +61,7 @@ GSD 会在 `~/gsd-workspaces/feature-b/` 中创建 `hr-ui` 和 `ZeymoAPI` 的 wo
若要强制使用完整克隆而非 worktree:
```bash
/gsd-workspace --new --name payments-rework --repos . --strategy clone
/msd-workspace --new --name payments-rework --repos . --strategy clone
```
---
@@ -69,7 +69,7 @@ GSD 会在 `~/gsd-workspaces/feature-b/` 中创建 `hr-ui` 和 `ZeymoAPI` 的 wo
## 显式指定分支
```bash
/gsd-workspace --new --name payments-rework --repos . --branch feature/payments-v2
/msd-workspace --new --name payments-rework --repos . --branch feature/payments-v2
```
`--branch` 标志为工作区中所有仓库设置分支名称,默认为 `workspace/<name>`。
@@ -79,43 +79,43 @@ GSD 会在 `~/gsd-workspaces/feature-b/` 中创建 `hr-ui` 和 `ZeymoAPI` 的 wo
## 跳过交互式询问
```bash
/gsd-workspace --new --name payments-rework --repos . --auto
/msd-workspace --new --name payments-rework --repos . --auto
```
GSD 将接受所有默认值,无需提示确认。
MSD 将接受所有默认值,无需提示确认。
---
## 在工作区内初始化 GSD
## 在工作区内初始化 MSD
创建工作区后,进入工作区目录并初始化 GSD 项目:
创建工作区后,进入工作区目录并初始化 MSD 项目:
```bash
cd ~/gsd-workspaces/feature-b
/gsd-new-project
cd ~/msd-workspaces/feature-b
/msd-new-project
```
工作区内的 `.planning/` 目录是从该目录运行所有后续 GSD 命令的根目录。它与源仓库中存在的任何 `.planning/` 完全独立。
工作区内的 `.planning/` 目录是从该目录运行所有后续 MSD 命令的根目录。它与源仓库中存在的任何 `.planning/` 完全独立。
---
## 列出工作区
```bash
/gsd-workspace --list
/msd-workspace --list
```
打印所有活跃的 GSD 工作区及其状态。
打印所有活跃的 MSD 工作区及其状态。
---
## 删除工作区
```bash
/gsd-workspace --remove feature-b
/msd-workspace --remove feature-b
```
GSD 会移除 git worktree 并清理工作区目录。此操作不会从远程仓库删除分支——仅删除本地 worktree 和工作区目录。
MSD 会移除 git worktree 并清理工作区目录。此操作不会从远程仓库删除分支——仅删除本地 worktree 和工作区目录。
---
@@ -123,15 +123,15 @@ GSD 会移除 git worktree 并清理工作区目录。此操作不会从远程
选择工作区的场景:
- 你需要跨**多个仓库**协同工作,且这些仓库需要在同一个 GSD 项目下进行协调(例如,一个 API 仓库和一个 UI 仓库需要一起发布)
- 你需要跨**多个仓库**协同工作,且这些仓库需要在同一个 MSD 项目下进行协调(例如,一个 API 仓库和一个 UI 仓库需要一起发布)
- 你需要每个功能拥有**独立的 git worktree**,带有各自的分支、锁文件和构建产物——以确保一个环境中的构建和依赖安装不会影响另一个环境
- 你希望拥有**完全独立的 `.planning/` 根目录**,而非主仓库 `.planning/` 的子目录
- 你正在采用 Issue 驱动的工作流,将每个跟踪器 Issue 映射到一个工作区(参见[从跟踪器 Issue 驱动 GSD](drive-gsd-from-a-tracker-issue.md))
- 你正在采用 Issue 驱动的工作流,将每个跟踪器 Issue 映射到一个工作区(参见[从跟踪器 Issue 驱动 MSD](drive-msd-from-a-tracker-issue.md))
选择[工作流](work-in-parallel-with-workstreams.md)的场景:
- 所有工作都在**单一仓库**中进行,共享相同的 git 历史
- 你希望在不同关注领域(API、UI、基础设施)上并发运行 `/gsd-plan-phase` 或 `/gsd-discuss-phase`,且各自的 `STATE.md` 文件之间互不干扰
- 你希望在不同关注领域(API、UI、基础设施)上并发运行 `/msd-plan-phase` 或 `/msd-discuss-phase`,且各自的 `STATE.md` 文件之间互不干扰
- 你不需要每个关注领域拥有独立的 worktree;切换规划上下文即可满足需求
---
@@ -139,6 +139,6 @@ GSD 会移除 git worktree 并清理工作区目录。此操作不会从远程
## 相关内容
- [使用工作流并行工作](work-in-parallel-with-workstreams.md)
- [从跟踪器 Issue 驱动 GSD](drive-gsd-from-a-tracker-issue.md)
- [从跟踪器 Issue 驱动 MSD](drive-msd-from-a-tracker-issue.md)
- [命令](../COMMANDS.md)
- [文档索引](../README.md)

View File

@@ -1,22 +1,22 @@
# 如何从 GSD-2 迁移
**目标:** 将较旧的 GSD-2 项目(`.gsd/` 目录布局)升级迁移到 GSD Core(`.planning/` 布局),并可选择将项目仓库中已有的 ADR、PRD 或规范文档纳入新的规划结构。
**目标:** 将较旧的 GSD-2 项目(`.gsd/` 目录布局)升级迁移到 MSD Core(`.planning/` 布局),并可选择将项目仓库中已有的 ADR、PRD 或规范文档纳入新的规划结构。
**前提条件:** GSD Core 已安装。GSD-2 项目目录在磁盘上可访问。
**前提条件:** MSD Core 已安装。GSD-2 项目目录在磁盘上可访问。
---
## 了解迁移内容
GSD-2 使用 `.gsd/` 目录作为规划根目录,GSD Core 使用 `.planning/`。迁移过程读取 `.gsd/` 中的工件,并将其写入所有 GSD Core 命令所期望的标准 `.planning/` 结构中。
GSD-2 使用 `.gsd/` 目录作为规划根目录,MSD Core 使用 `.planning/`。迁移过程读取 `.gsd/` 中的工件,并将其写入所有 MSD Core 命令所期望的标准 `.planning/` 结构中。
| GSD-2 中的现有内容 | `/gsd-import --from-gsd2` 产生的内容 |
| GSD-2 中的现有内容 | `/msd-import --from-gsd2` 产生的内容 |
|----------------------|-----------------------------------------|
| `.gsd/PROJECT.md` | `.planning/PROJECT.md` |
| `.gsd/ROADMAP.md` | `.planning/ROADMAP.md` |
| `.gsd/STATE.md` | `.planning/STATE.md` |
| `.gsd/phases/` 目录 | `.planning/phases/` 目录 |
| 阶段 `PLAN.md` 文件 | GSD Core `{NN}-{MM}-PLAN.md` 文件(强制重命名) |
| 阶段 `PLAN.md` 文件 | MSD Core `{NN}-{MM}-PLAN.md` 文件(强制重命名) |
冲突检测会在写入任何文件之前运行。如果目标目录中已存在 `PROJECT.md` 且导入内容与之矛盾,迁移将在 BLOCKER 门控处停止,并列出需要您解决的冲突。
@@ -27,15 +27,15 @@ GSD-2 使用 `.gsd/` 目录作为规划根目录,GSD Core 使用 `.planning/`
### 迁移当前目录
```bash
/gsd-import --from-gsd2
/msd-import --from-gsd2
```
GSD 读取当前工作目录下的 `.gsd/`,并将迁移后的工件写入 `.planning/`。
MSD 读取当前工作目录下的 `.gsd/`,并将迁移后的工件写入 `.planning/`。
### 从其他路径迁移
```bash
/gsd-import --from-gsd2 --path ~/projects/old-project
/msd-import --from-gsd2 --path ~/projects/old-project
```
当 GSD-2 项目不在当前工作目录时,使用 `--path` 指定路径。
@@ -46,7 +46,7 @@ GSD 读取当前工作目录下的 `.gsd/`,并将迁移后的工件写入 `.pl
如果冲突检测发现阻断项——例如,GSD-2 的技术栈声明与现有的 `.planning/PROJECT.md` 相矛盾——它会打印冲突报告并停止,不写入任何文件。
阅读报告,解决矛盾(编辑源文档或现有规划工件),然后重新运行 `/gsd-import --from-gsd2`。迁移可以安全地重复运行,直至顺利通过。
阅读报告,解决矛盾(编辑源文档或现有规划工件),然后重新运行 `/msd-import --from-gsd2`。迁移可以安全地重复运行,直至顺利通过。
---
@@ -55,30 +55,30 @@ GSD 读取当前工作目录下的 `.gsd/`,并将迁移后的工件写入 `.pl
如果您拥有的是独立的计划文档(团队规划文档、Markdown 规范、导出的任务列表),而非完整的 GSD-2 项目,请使用 `--from` 代替:
```bash
/gsd-import --from /tmp/team-plan.md
/msd-import --from /tmp/team-plan.md
```
GSD 执行相同的冲突检测流程,将内容转换为 GSD Core `PLAN.md` 格式,并使用计划检查器验证结果。验证完成后,您将看到目标文件名和后续步骤。
MSD 执行相同的冲突检测流程,将内容转换为 MSD Core `PLAN.md` 格式,并使用计划检查器验证结果。验证完成后,您将看到目标文件名和后续步骤。
---
## 吸收现有文档
如果您的仓库中已包含 ADR(架构决策记录)、PRD 或规范文档,可在迁移完成后使用 `/gsd-ingest-docs` 将其合并到 `.planning/` 结构中:
如果您的仓库中已包含 ADR(架构决策记录)、PRD 或规范文档,可在迁移完成后使用 `/msd-ingest-docs` 将其合并到 `.planning/` 结构中:
### 扫描整个仓库(自动检测模式)
```bash
/gsd-ingest-docs
/msd-ingest-docs
```
如果 `.planning/` 已经存在(例如,刚完成迁移后),GSD 默认使用合并模式——将导入的文档与已有内容并行合并,而非覆盖。
如果 `.planning/` 已经存在(例如,刚完成迁移后),MSD 默认使用合并模式——将导入的文档与已有内容并行合并,而非覆盖。
### 限定到特定目录
```bash
/gsd-ingest-docs docs/
/gsd-ingest-docs docs/adr/
/msd-ingest-docs docs/
/msd-ingest-docs docs/adr/
```
### 使用显式优先级清单
@@ -86,7 +86,7 @@ GSD 执行相同的冲突检测流程,将内容转换为 GSD Core `PLAN.md`
当文档类型混合,或您希望控制冲突时哪份文档优先:
```bash
/gsd-ingest-docs --manifest ingest.yaml
/msd-ingest-docs --manifest ingest.yaml
```
清单是一个 YAML 文件,每个文档列出 `{path, type, precedence?}`。请参阅 [Commands](../COMMANDS.md) 中 `--manifest` 标志说明,了解其期望的结构。
@@ -94,11 +94,11 @@ GSD 执行相同的冲突检测流程,将内容转换为 GSD Core `PLAN.md`
### 强制指定模式
```bash
/gsd-ingest-docs --mode merge # 合并到现有 .planning/
/gsd-ingest-docs --mode new # 从零开始引导(覆盖)
/msd-ingest-docs --mode merge # 合并到现有 .planning/
/msd-ingest-docs --mode new # 从零开始引导(覆盖)
```
**输出:** `/gsd-ingest-docs` 始终生成一个 `INGEST-CONFLICTS.md`,其中包含三个类别——自动解决、竞争变体和未解决的阻断项。每次导入运行后请审查此文件。仅在 LOCKED 与 LOCKED 的 ADR 矛盾时才会硬停止;其他所有情况均会呈现供您审查,而不会被静默丢弃。
**输出:** `/msd-ingest-docs` 始终生成一个 `INGEST-CONFLICTS.md`,其中包含三个类别——自动解决、竞争变体和未解决的阻断项。每次导入运行后请审查此文件。仅在 LOCKED 与 LOCKED 的 ADR 矛盾时才会硬停止;其他所有情况均会呈现供您审查,而不会被静默丢弃。
---
@@ -107,19 +107,19 @@ GSD 执行相同的冲突检测流程,将内容转换为 GSD Core `PLAN.md`
迁移及文档导入完成后,确认项目状态的一致性:
```bash
/gsd-health
/gsd-health --repair
/msd-health
/msd-health --repair
```
`/gsd-health` 检查 `.planning/` 目录的完整性并报告任何偏差。`--repair` 会自动修复可恢复的问题。
`/msd-health` 检查 `.planning/` 目录的完整性并报告任何偏差。`--repair` 会自动修复可恢复的问题。
然后检查 GSD Core 是否能够读取您的项目状态:
然后检查 MSD Core 是否能够读取您的项目状态:
```bash
/gsd-progress
/msd-progress
```
如果项目迁移顺利,您将看到当前阶段状态和推荐的下一步操作。从此处起,适用标准 GSD Core 工作流程。
如果项目迁移顺利,您将看到当前阶段状态和推荐的下一步操作。从此处起,适用标准 MSD Core 工作流程。
---
@@ -127,13 +127,13 @@ GSD 执行相同的冲突检测流程,将内容转换为 GSD Core `PLAN.md`
| 情形 | 处理方式 |
|-----------|-----------|
| 当前目录中存在 `.gsd/` | 运行 `/gsd-import --from-gsd2`(无需 `--path`) |
| 当前目录中存在 `.gsd/` | 运行 `/msd-import --from-gsd2`(无需 `--path`) |
| `.gsd/` 在其他目录 | 使用 `--path ~/projects/old-project` |
| 您有独立的计划文档,而非完整的 GSD-2 项目 | 使用 `/gsd-import --from /path/to/plan.md` |
| 您在 `docs/adr/` 中有 ADR | 迁移后运行 `/gsd-ingest-docs docs/adr/` |
| 您有 ADR、PRD 和规范的混合文档 | 在仓库根目录运行 `/gsd-ingest-docs`,它会自动分类 |
| 您有独立的计划文档,而非完整的 GSD-2 项目 | 使用 `/msd-import --from /path/to/plan.md` |
| 您在 `docs/adr/` 中有 ADR | 迁移后运行 `/msd-ingest-docs docs/adr/` |
| 您有 ADR、PRD 和规范的混合文档 | 在仓库根目录运行 `/msd-ingest-docs`,它会自动分类 |
| 冲突检测报告阻断项 | 解决列出的矛盾后重新运行;在所有阻断项清除前不会写入任何文件 |
| 您不确定迁移是否成功 | 运行 `/gsd-health` 和 `/gsd-progress` 进行确认 |
| 您不确定迁移是否成功 | 运行 `/msd-health` 和 `/msd-progress` 进行确认 |
| INGEST-CONFLICTS.md 列出未解决的阻断项 | 这些需要手动解决,相关文档才能被纳入规划 |
---

View File

@@ -2,23 +2,23 @@
**目标:** 将阶段决策和研究成果转化为可原子化执行、可验证的任务计划。
**前提条件:** `.planning/ROADMAP.md` 已存在。强烈建议(但非必须)先通过 `/gsd-discuss-phase` 生成 `{phase}-CONTEXT.md`。
**前提条件:** `.planning/ROADMAP.md` 已存在。强烈建议(但非必须)先通过 `/msd-discuss-phase` 生成 `{phase}-CONTEXT.md`。
---
## 运行标准规划流程
```bash
/gsd-plan-phase 2
/msd-plan-phase 2
```
该命令按顺序执行三个阶段:
1. **研究** — `gsd-phase-researcher` 子代理调查相关领域并写入 `{phase}-RESEARCH.md`。
2. **规划** — `gsd-planner` 子代理读取上下文、研究成果和需求,然后写入一个或多个 `{phase}-{N}-PLAN.md` 文件。
3. **验证** — `gsd-plan-checker` 子代理从八个维度验证计划质量,并触发修订循环(最多三次迭代),直至质量门控通过。
1. **研究** — `msd-phase-researcher` 子代理调查相关领域并写入 `{phase}-RESEARCH.md`。
2. **规划** — `msd-planner` 子代理读取上下文、研究成果和需求,然后写入一个或多个 `{phase}-{N}-PLAN.md` 文件。
3. **验证** — `msd-plan-checker` 子代理从八个维度验证计划质量,并触发修订循环(最多三次迭代),直至质量门控通过。
若未指定阶段编号,GSD Core 将自动定位 ROADMAP.md 中下一个未规划的阶段。
若未指定阶段编号,MSD Core 将自动定位 ROADMAP.md 中下一个未规划的阶段。
---
@@ -27,34 +27,34 @@
**如果领域已熟悉且无需新的研究:**
```bash
/gsd-plan-phase 3 --skip-research
/msd-plan-phase 3 --skip-research
```
**如果 RESEARCH.md 已存在但需要强制刷新:**
```bash
/gsd-plan-phase 3 --research
/msd-plan-phase 3 --research
```
**如果只想运行研究** — 写入 RESEARCH.md 后在规划前退出:
```bash
/gsd-plan-phase --research-phase 4
/msd-plan-phase --research-phase 4
```
若 RESEARCH.md 已存在,系统会提示选择更新、查看或跳过。如需强制刷新而不显示提示:
```bash
/gsd-plan-phase --research-phase 4 --research
/msd-plan-phase --research-phase 4 --research
```
将现有 RESEARCH.md 打印到标准输出而不启动研究代理:
```bash
/gsd-plan-phase --research-phase 4 --view
/msd-plan-phase --research-phase 4 --view
```
注意:`--research-phase <N>` 是 `/gsd-plan-phase` 上的标志。不存在独立的研究阶段命令——原来的独立研究命令已被弃用,以此标志取而代之。
注意:`--research-phase <N>` 是 `/msd-plan-phase` 上的标志。不存在独立的研究阶段命令——原来的独立研究命令已被弃用,以此标志取而代之。
---
@@ -63,7 +63,7 @@
**如果希望任务按端到端的薄切片组织**(每个功能从 UI → API → DB),而非按技术层次:
```bash
/gsd-plan-phase 1 --mvp
/msd-plan-phase 1 --mvp
```
在新项目的第一阶段且无先前阶段摘要的情况下,`--mvp` 还会生成 `SKELETON.md`——一份 Walking Skeleton,涵盖项目脚手架、路由、一次真实的数据库读写、一次真实的 UI 交互以及开发部署。
@@ -77,13 +77,13 @@
**如果需要强制 TDD** — 每个新增行为的任务在实现前先编写一个失败测试:
```bash
/gsd-plan-phase 1 --tdd
/msd-plan-phase 1 --tdd
```
可与 `--mvp` 组合使用:
```bash
/gsd-plan-phase 1 --mvp --tdd
/msd-plan-phase 1 --mvp --tdd
```
这将生成垂直切片,其中每个新增行为的任务均遵循 RED → GREEN → REFACTOR 流程。规划器会对符合条件的任务(业务逻辑、API 端点、数据转换)应用 `type: tdd`,并对 UI、配置和胶水代码使用标准的 `type: execute`。
@@ -91,17 +91,17 @@
TDD 模式也可在配置中持久化:
```bash
node gsd-tools.cjs config-set workflow.tdd_mode true
node msd-tools.cjs config-set workflow.tdd_mode true
```
---
## 基于跨 AI 评审反馈重新规划
**如果已运行 `/gsd-review --phase N` 且存在 `REVIEWS.md`:**
**如果已运行 `/msd-review --phase N` 且存在 `REVIEWS.md`:**
```bash
/gsd-plan-phase 3 --reviews
/msd-plan-phase 3 --reviews
```
规划器会读取 `REVIEWS.md` 并修订计划以解决反馈问题。不可与 `--gaps` 组合使用。
@@ -109,7 +109,7 @@ node gsd-tools.cjs config-set workflow.tdd_mode true
**如果需要自动化循环** — 持续重新规划和重新评审,直至不再存在 HIGH 级别关注点:
```bash
/gsd-plan-review-convergence 3
/msd-plan-review-convergence 3
```
收敛循环执行规划 → 评审 → 重新规划 → 再评审的周期(默认最多三次)。使用 `--max-cycles N` 可覆盖上限。
@@ -121,7 +121,7 @@ node gsd-tools.cjs config-set workflow.tdd_mode true
**如果 `VERIFICATION.md` 存在未解决的差距,且只想针对这些差距重新规划:**
```bash
/gsd-plan-phase 3 --gaps
/msd-plan-phase 3 --gaps
```
研究阶段将被跳过;规划器直接读取验证中的差距信息。
@@ -133,13 +133,13 @@ node gsd-tools.cjs config-set workflow.tdd_mode true
**如果已配置 `workflow.plan_bounce_script` 且需要对完成的计划进行外部验证:**
```bash
/gsd-plan-phase 1 --bounce
/msd-plan-phase 1 --bounce
```
即使在配置中已启用弹跳,也可跳过:
```bash
/gsd-plan-phase 1 --skip-bounce
/msd-plan-phase 1 --skip-bounce
```
---
@@ -147,7 +147,7 @@ node gsd-tools.cjs config-set workflow.tdd_mode true
## 禁止交互式确认
```bash
/gsd-plan-phase --auto
/msd-plan-phase --auto
```
跳过所有提示。适用于自动化流水线。若配置中 `research_enabled` 为 false,则跳过研究阶段。
@@ -171,7 +171,7 @@ node gsd-tools.cjs config-set workflow.tdd_mode true
### 计划质量维度
`gsd-plan-checker` 在允许执行前从八个维度验证计划:
`msd-plan-checker` 在允许执行前从八个维度验证计划:
1. 任务原子性——每个任务只关注单一问题
2. 依赖正确性——波次顺序一致
@@ -191,7 +191,7 @@ node gsd-tools.cjs config-set workflow.tdd_mode true
如果某阶段的 `VERIFICATION.md` 中 `status: passed`,则该阶段被视为已关闭。尝试重新规划会以错误终止。如果关闭操作有误,可使用 `--force` 覆盖:
```bash
/gsd-plan-phase 2 --force
/msd-plan-phase 2 --force
```
警告信息将写入转录记录和所有已提交的计划文档中。

View File

@@ -2,7 +2,7 @@
**目标:** 识别并修复常见问题——从上下文丢失、状态损坏,到安装失败和权限错误——采用条件化的处理步骤结构。
**前提条件:** GSD Core 已安装。若遇到安装问题,请参阅 [在您的运行时中安装](install-on-your-runtime.md)。
**前提条件:** MSD Core 已安装。若遇到安装问题,请参阅 [在您的运行时中安装](install-on-your-runtime.md)。
---
@@ -11,7 +11,7 @@
### 如果您不清楚当前所处的位置
```bash
/gsd-progress
/msd-progress
```
读取所有状态文件,并精确告知您当前位置以及下一步操作。
@@ -19,13 +19,13 @@
若要自动跳转到正确的下一步:
```bash
/gsd-progress --next
/msd-progress --next
```
### 如果您正在开始新会话并需要恢复上下文
```bash
/gsd-resume-work
/msd-resume-work
```
从上次交接中恢复完整的会话上下文,包括当前阶段、规划决策以及工作停止的位置。
@@ -41,21 +41,21 @@
然后恢复状态:
```bash
/gsd-resume-work
/msd-resume-work
```
GSD 的设计围绕全新上下文展开。每个子代理已获得干净的 200k 窗口。主会话会随时间退化——清空并恢复才是正确的处理方式,而非继续硬撑。
MSD 的设计围绕全新上下文展开。每个子代理已获得干净的 200k 窗口。主会话会随时间退化——清空并恢复才是正确的处理方式,而非继续硬撑。
### 如果您希望在停止前保存上下文
```bash
/gsd-pause-work
/msd-pause-work
```
将当前位置创建为 `.planning/HANDOFF.json`。添加 `--report` 可同时将会话后摘要写入 `.planning/reports/`:
```bash
/gsd-pause-work --report
/msd-pause-work --report
```
---
@@ -65,7 +65,7 @@ GSD 的设计围绕全新上下文展开。每个子代理已获得干净的 200
### 如果 `.planning/` 完整性不确定
```bash
/gsd-health
/msd-health
```
以错误、警告和信息说明的形式报告状态:
@@ -79,7 +79,7 @@ GSD 的设计围绕全新上下文展开。每个子代理已获得干净的 200
可自动修复的常见问题(错误 E004、E005;警告 W003、W008):
```bash
/gsd-health --repair
/msd-health --repair
```
该命令会重新创建缺失的 `STATE.md`,将损坏的 `config.json` 重置为默认值,并补充所有缺失的配置键。它不会覆盖 `PROJECT.md` 或 `ROADMAP.md`。
@@ -89,40 +89,40 @@ GSD 的设计围绕全新上下文展开。每个子代理已获得干净的 200
这会产生警告 `W002`。使用状态 CLI 进行诊断和修复:
```bash
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state validate
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state validate
```
在不写入的情况下预览同步将更改的内容:
```bash
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state sync --verify
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync --verify
```
应用同步:
```bash
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state sync
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync
```
这些命令从磁盘上的实际项目状态重建 `STATE.md`,取代手动编辑 `STATE.md` 的操作。
### 如果看到"项目已初始化"
`.planning/PROJECT.md` 已存在。`/gsd-new-project` 是一项安全检查。如果您确实想重新开始,请先删除 `.planning/` 目录:
`.planning/PROJECT.md` 已存在。`/msd-new-project` 是一项安全检查。如果您确实想重新开始,请先删除 `.planning/` 目录:
```bash
rm -rf .planning/
```
然后重新运行 `/gsd-new-project`。
然后重新运行 `/msd-new-project`。
### 如果上下文窗口利用率过高
```bash
/gsd-health --context
/msd-health --context
```
探测上下文窗口利用率保护机制。警告阈值为 60%,严重阈值为 70%。如果超过警告阈值,请在开始下一个主要命令前运行 `/clear` 后跟 `/gsd-resume-work`。
探测上下文窗口利用率保护机制。警告阈值为 60%,严重阈值为 70%。如果超过警告阈值,请在开始下一个主要命令前运行 `/clear` 后跟 `/msd-resume-work`。
---
@@ -130,7 +130,7 @@ rm -rf .planning/
### 如果执行器在执行 Bash 命令时遇到"Permission denied"
GSD 的 `gsd-executor` 子代理需要具有写入权限的 Bash 访问。在 `~/.claude/settings.json` 的 `permissions.allow` 下添加所需模式。至少需要:
MSD 的 `msd-executor` 子代理需要具有写入权限的 Bash 访问。在 `~/.claude/settings.json` 的 `permissions.allow` 下添加所需模式。至少需要:
```json
"Bash(git add:*)",
@@ -148,17 +148,17 @@ GSD 的 `gsd-executor` 子代理需要具有写入权限的 Bash 访问。在 `~
检查计划是否过于宏大。计划最多应包含两到三个任务。如果任务太大,则超出单个上下文窗口能可靠产出的范围。请以更小的范围重新规划该阶段:
```bash
/gsd-plan-phase 1
/msd-plan-phase 1
```
若要系统性地诊断出错原因,请参阅 [调试失败的执行](debug-a-failed-execution.md)。
### 如果并行执行导致构建锁定错误或预提交钩子失败
这是由多个代理同时触发构建工具引起的。自 v1.26 起,GSD 自动处理此问题。如果您使用的是旧版本,或仍然出现竞争问题,请禁用并行执行:
这是由多个代理同时触发构建工具引起的。自 v1.26 起,MSD 自动处理此问题。如果您使用的是旧版本,或仍然出现竞争问题,请禁用并行执行:
```bash
/gsd-settings
/msd-settings
```
将 `parallelization.enabled` 设置为 `false`。
@@ -171,7 +171,7 @@ GSD 的 `gsd-executor` 子代理需要具有写入权限的 Bash 访问。在 `~
git log --oneline -10
```
Claude Code 中存在一个已知的分类错误,可能在工作实际成功时报告失败。GSD 的编排器会抽查实际输出,但如果您发现不一致,提交记录才是最终依据。
Claude Code 中存在一个已知的分类错误,可能在工作实际成功时报告失败。MSD 的编排器会抽查实际输出,但如果您发现不一致,提交记录才是最终依据。
---
@@ -179,31 +179,31 @@ Claude Code 中存在一个已知的分类错误,可能在工作实际成功
### 如果计划看起来有误或与您的意图不符
在规划之前运行 `/gsd-discuss-phase N`。大多数计划质量问题来自本可由 `CONTEXT.md` 预防的假设:
在规划之前运行 `/msd-discuss-phase N`。大多数计划质量问题来自本可由 `CONTEXT.md` 预防的假设:
```bash
/gsd-discuss-phase 1
/msd-discuss-phase 1
```
若要查看 GSD 当前做出的假设而无需开始完整会话:
若要查看 MSD 当前做出的假设而无需开始完整会话:
```bash
/gsd-discuss-phase 3 --assumptions
/msd-discuss-phase 3 --assumptions
```
### 如果您需要在执行后更改某些内容
不要重新运行 `/gsd-execute-phase`。请使用 `/gsd-quick` 进行有针对性的修复:
不要重新运行 `/msd-execute-phase`。请使用 `/msd-quick` 进行有针对性的修复:
```bash
/gsd-quick "Fix the login button not responding on mobile Safari"
/msd-quick "Fix the login button not responding on mobile Safari"
```
或使用 `/gsd-verify-work N` 通过 UAT 系统性地识别和修复问题。
或使用 `/msd-verify-work N` 通过 UAT 系统性地识别和修复问题。
### 如果命令在"Spawning…"处似乎卡住了
请等待。GSD 子代理在独立的上下文窗口中运行。其工作在进行中对父会话不可见。生成行上的活跃度提示确认这是预期行为。研究和规划代理通常需要 1–5 分钟;验证代理在大型阶段中可能需要更长时间。
请等待。MSD 子代理在独立的上下文窗口中运行。其工作在进行中对父会话不可见。生成行上的活跃度提示确认这是预期行为。研究和规划代理通常需要 1–5 分钟;验证代理在大型阶段中可能需要更长时间。
不要中断会话。终止它会丢弃进行中的子代理工作。
@@ -216,56 +216,56 @@ Claude Code 中存在一个已知的分类错误,可能在工作实际成功
### 如果工作流似乎已损坏或状态不一致
```bash
/gsd-forensics
/msd-forensics
```
或附带描述:
```bash
/gsd-forensics "Phase 3 execution stalled after wave 1"
/msd-forensics "Phase 3 execution stalled after wave 1"
```
`/gsd-forensics` 执行事后调查:git 历史异常、产物完整性、STATE.md 一致性、未提交的工作以及孤立的工作树。它将报告写入 `.planning/forensics/` 并给出推荐的补救步骤。该命令为只读,不会修改您的项目文件。
`/msd-forensics` 执行事后调查:git 历史异常、产物完整性、STATE.md 一致性、未提交的工作以及孤立的工作树。它将报告写入 `.planning/forensics/` 并给出推荐的补救步骤。该命令为只读,不会修改您的项目文件。
### 如果您需要回滚某个阶段或计划
```bash
/gsd-undo --phase 03 # 回滚阶段 3 的所有提交
/gsd-undo --plan 03-02 # 回滚阶段 3 中计划 02 的提交
/gsd-undo --last 5 # 从最近 5 个 GSD 提交中交互式选择
/msd-undo --phase 03 # 回滚阶段 3 的所有提交
/msd-undo --plan 03-02 # 回滚阶段 3 中计划 02 的提交
/msd-undo --last 5 # 从最近 5 个 MSD 提交中交互式选择
```
`/gsd-undo` 在回滚前检查依赖阶段,并始终显示确认步骤。
`/msd-undo` 在回滚前检查依赖阶段,并始终显示确认步骤。
---
## 安装与更新问题
### 如果安装后 GSD 未被识别
### 如果安装后 MSD 未被识别
重启您的运行时。GSD 将斜杠命令安装到您运行时的命令目录中(例如 `~/.claude/commands/gsd/`)。大多数运行时仅在启动时发现新命令。
重启您的运行时。MSD 将斜杠命令安装到您运行时的命令目录中(例如 `~/.claude/commands/msd/`)。大多数运行时仅在启动时发现新命令。
如果问题仍然存在,请验证安装:
```bash
npx @opengsd/gsd-core@latest --claude --local
npx @golem15/msd-core@latest --claude --local
```
有关特定运行时的安装路径和排查说明,请参阅 [在您的运行时中安装](install-on-your-runtime.md)。
### 如果更新覆盖了您的本地更改
自 v1.17 起,安装程序将本地修改的文件备份到 `gsd-local-patches/`。重新应用您的更改:
自 v1.17 起,安装程序将本地修改的文件备份到 `msd-local-patches/`。重新应用您的更改:
```bash
/gsd-update --reapply
/msd-update --reapply
```
### 如果无法通过 npm 更新
如果 `npx @opengsd/gsd-core` 因 npm 故障或网络限制而失败,请参阅 `docs/manual-update.md` 了解无需 npm 访问即可完成更新的逐步手动更新流程。
如果 `npx @golem15/msd-core` 因 npm 故障或网络限制而失败,请参阅 `docs/manual-update.md` 了解无需 npm 访问即可完成更新的逐步手动更新流程。
有关常规更新,请参阅 [更新 GSD](update-gsd.md)。
有关常规更新,请参阅 [更新 MSD](update-msd.md)。
---
@@ -276,13 +276,13 @@ npx @opengsd/gsd-core@latest --claude --local
切换到预算配置文件:
```bash
/gsd-config --profile budget
/msd-config --profile budget
```
如果对该领域已很熟悉,请通过设置禁用研究和计划检查代理:
```bash
/gsd-settings
/msd-settings
```
另外,请审核已启用的 MCP 服务器。每个已启用的 MCP 服务器都会在每个回合中将其工具架构注入。浏览器和平台特定工具每个可能消耗 20k+ 个令牌。在 `.claude/settings.json` 中禁用当前阶段不需要的服务器:
@@ -299,19 +299,19 @@ npx @opengsd/gsd-core@latest --claude --local
| 问题 | 解决方案 |
|---------|---------|
| 上下文丢失或新会话 | `/gsd-resume-work` 或 `/gsd-progress` |
| 不知道下一步是什么 | `/gsd-progress --next` |
| 阶段出错 | `/gsd-undo --phase NN`,然后重新规划 |
| 某些内容损坏 | `/gsd-debug "description"`(添加 `--diagnose` 可仅分析而不修复) |
| 上下文丢失或新会话 | `/msd-resume-work` 或 `/msd-progress` |
| 不知道下一步是什么 | `/msd-progress --next` |
| 阶段出错 | `/msd-undo --phase NN`,然后重新规划 |
| 某些内容损坏 | `/msd-debug "description"`(添加 `--diagnose` 可仅分析而不修复) |
| STATE.md 不同步 | `state validate` 后 `state sync` |
| `.planning/` 完整性不确定 | `/gsd-health`,然后 `/gsd-health --repair` |
| 工作流状态似乎损坏 | `/gsd-forensics` |
| 快速针对性修复 | `/gsd-quick` |
| 计划与您的愿景不符 | `/gsd-discuss-phase N` 后重新规划 |
| 成本过高 | `/gsd-config --profile budget` 和 `/gsd-settings` 关闭代理 |
| 更新破坏了本地更改 | `/gsd-update --reapply` |
| 需要会话摘要 | `/gsd-pause-work --report` |
| 并行执行构建错误 | 更新 GSD 或设置 `parallelization.enabled: false` |
| `.planning/` 完整性不确定 | `/msd-health`,然后 `/msd-health --repair` |
| 工作流状态似乎损坏 | `/msd-forensics` |
| 快速针对性修复 | `/msd-quick` |
| 计划与您的愿景不符 | `/msd-discuss-phase N` 后重新规划 |
| 成本过高 | `/msd-config --profile budget` 和 `/msd-settings` 关闭代理 |
| 更新破坏了本地更改 | `/msd-update --reapply` |
| 需要会话摘要 | `/msd-pause-work --report` |
| 并行执行构建错误 | 更新 MSD 或设置 `parallelization.enabled: false` |
---

View File

@@ -1,6 +1,6 @@
# 如何自主运行阶段
无需人工干预地运行所有剩余阶段——或指定范围内的阶段——GSD 将自动完成每个阶段的讨论 → 规划 → 执行流程。
无需人工干预地运行所有剩余阶段——或指定范围内的阶段——MSD 将自动完成每个阶段的讨论 → 规划 → 执行流程。
有关自主运行期间阶段循环的工作原理,请参阅[阶段循环](../explanation/the-phase-loop.md)。
@@ -10,17 +10,17 @@
- 已有包含 `.planning/ROADMAP.md` 和 `.planning/STATE.md` 的活跃项目
- 所有要运行的阶段必须处于自主模式可驱动的状态(待处理或进行中;非已完成状态)
- 您关心的所有设计决策应已记录在 `PROJECT.md` 中,或通过之前的 `/gsd-discuss-phase` 捕获——自主模式仅在使用 `--interactive` 时才能交互式地处理灰色地带
- 您关心的所有设计决策应已记录在 `PROJECT.md` 中,或通过之前的 `/msd-discuss-phase` 捕获——自主模式仅在使用 `--interactive` 时才能交互式地处理灰色地带
---
## 运行所有剩余阶段
```bash
/gsd-autonomous
/msd-autonomous
```
GSD 读取 `ROADMAP.md`,按数字顺序发现所有未完成的阶段,并对每个阶段执行讨论 → 规划 → 执行。所有阶段完成后,它会自动运行里程碑生命周期:审计 → 完成 → 清理。
MSD 读取 `ROADMAP.md`,按数字顺序发现所有未完成的阶段,并对每个阶段执行讨论 → 规划 → 执行。所有阶段完成后,它会自动运行里程碑生命周期:审计 → 完成 → 清理。
---
@@ -29,15 +29,15 @@ GSD 读取 `ROADMAP.md`,按数字顺序发现所有未完成的阶段,并对
使用 `--from` 和 `--to` 来限定运行范围。两个标志都接受十进制阶段编号(例如 `3.1`)。
```bash
/gsd-autonomous --from 3 # 阶段 3、4、5 …(跳过已完成的阶段 1 和 2)
/gsd-autonomous --to 5 # 直到并包括阶段 5
/gsd-autonomous --from 3 --to 5 # 恰好是阶段 3、4 和 5
/msd-autonomous --from 3 # 阶段 3、4、5 …(跳过已完成的阶段 1 和 2)
/msd-autonomous --to 5 # 直到并包括阶段 5
/msd-autonomous --from 3 --to 5 # 恰好是阶段 3、4 和 5
```
到达 `--to` 时,生命周期步骤会被跳过,因为并非所有里程碑阶段都已完成。完成横幅会告诉您如何继续:
```text
Resume with: /gsd-autonomous --from 6
Resume with: /msd-autonomous --from 6
```
---
@@ -47,11 +47,11 @@ Resume with: /gsd-autonomous --from 6
默认情况下,自主模式使用智能讨论(批量表格提案)自动回答讨论问题。如果您希望自己回答设计问题,同时将规划和执行保持在主上下文之外:
```bash
/gsd-autonomous --interactive
/msd-autonomous --interactive
```
交互模式下:
- `/gsd-discuss-phase` 内联运行并等待您的回答
- `/msd-discuss-phase` 内联运行并等待您的回答
- 规划和执行作为后台代理分发,以便您在讨论下一阶段时当前阶段仍在构建
- 主上下文保持精简——只有讨论对话会累积
@@ -59,7 +59,7 @@ Resume with: /gsd-autonomous --from 6
## 哪些安全门控仍然适用
自主模式不会绕过 GSD 的质量流水线。每个阶段仍然会:
自主模式不会绕过 MSD 的质量流水线。每个阶段仍然会:
- 在执行前运行计划检查器
- 执行后读取 `VERIFICATION.md` 并根据结果进行路由
@@ -74,15 +74,15 @@ Resume with: /gsd-autonomous --from 6
## 何时不使用自主模式
以下情况请勿使用 `/gsd-autonomous`:
以下情况请勿使用 `/msd-autonomous`:
- **阶段存在未解决的设计决策。** 如果您尚未运行 `/gsd-discuss-phase` 且 `PROJECT.md` 未捕获您的偏好,智能讨论将做出您可能不认同的自主选择。请先交互式地运行讨论,或使用 `--interactive`。
- **阶段存在未解决的设计决策。** 如果您尚未运行 `/msd-discuss-phase` 且 `PROJECT.md` 未捕获您的偏好,智能讨论将做出您可能不认同的自主选择。请先交互式地运行讨论,或使用 `--interactive`。
- **您需要对单个阶段进行精细控制。** 对于单个阶段,`/gsd-execute-phase N` 会提供逐步输出并允许您在继续之前做出反应。自主模式专为批量无人值守运行而设计。
- **您需要对单个阶段进行精细控制。** 对于单个阶段,`/msd-execute-phase N` 会提供逐步输出并允许您在继续之前做出反应。自主模式专为批量无人值守运行而设计。
- **阶段包含新颖或高风险的工作。** 自主模式除非遇到阻碍,否则会跳过暂停。对于预期有意外情况的阶段,请通过手动执行保持在循环中。
- **您正处于已部分执行的阶段中途。** 自主模式可以接管未完成的阶段,但不会恢复部分执行的波次。使用 `/gsd-execute-phase N` 完成已在进行中的阶段。
- **您正处于已部分执行的阶段中途。** 自主模式可以接管未完成的阶段,但不会恢复部分执行的波次。使用 `/msd-execute-phase N` 完成已在进行中的阶段。
如果运行中途停止,请参阅[调试失败的执行](debug-a-failed-execution.md)了解如何诊断问题所在。
@@ -93,13 +93,13 @@ Resume with: /gsd-autonomous --from 6
自主模式在每个阶段前打印进度横幅:
```text
GSD ► AUTONOMOUS ▸ Phase 3/7: Auth Middleware [████░░░░] 28%
MSD ► AUTONOMOUS ▸ Phase 3/7: Auth Middleware [████░░░░] 28%
```
如果您需要在会话中途查看运行进度,请打开另一个终端并运行:
```bash
/gsd-progress
/msd-progress
```
---
@@ -109,10 +109,10 @@ Resume with: /gsd-autonomous --from 6
如果自主模式停止——无论是您从阻碍提示中选择了"停止自主模式",还是会话被中断——请从停止处继续:
```bash
/gsd-autonomous --from 4 # 将 4 替换为第一个未完成的阶段编号
/msd-autonomous --from 4 # 将 4 替换为第一个未完成的阶段编号
```
GSD 会自动跳过已完成的阶段,因此如果您不确定运行在何处停止,从较早的阶段编号重新运行是安全的。
MSD 会自动跳过已完成的阶段,因此如果您不确定运行在何处停止,从较早的阶段编号重新运行是安全的。
---

View File

@@ -8,7 +8,7 @@
## 决定使用哪些评审者
GSD Core 可将评审请求路由至以下任意组合:Claude(独立会话)、Codex CLI、CodeRabbit、OpenCode、Qwen Code、Cursor、Antigravity CLI、Ollama、LM Studio 以及 llama.cpp。
MSD Core 可将评审请求路由至以下任意组合:Claude(独立会话)、Codex CLI、CodeRabbit、OpenCode、Qwen Code、Cursor、Antigravity CLI、Ollama、LM Studio 以及 llama.cpp。
每位评审者会独立地对您的 `PLAN.md` 文件执行相同的结构化提示。由于不同模型存在不同的盲区,多评审者共识能比任何单一评审者发现更多问题。
@@ -26,18 +26,18 @@ npm install -g @openai/codex
## 设置默认评审者(可选)
默认情况下,`/gsd-review` 会运行所有检测到的 CLI。若要将特定子集固定为项目默认值:
默认情况下,`/msd-review` 会运行所有检测到的 CLI。若要将特定子集固定为项目默认值:
```bash
/gsd-config --integrations
/msd-config --integrations
```
集成向导涵盖 API 密钥、代码评审 CLI 路由以及 `review.default_reviewers` 列表。将该列表设置为您希望作为无标志默认值的评审者——例如 `["codex","claude"]`。
或者,也可通过 `gsd-tools` 直接设置:
或者,也可通过 `msd-tools` 直接设置:
```bash
gsd config-set review.default_reviewers '["codex","claude"]'
msd config-set review.default_reviewers '["codex","claude"]'
```
完整的集成设置架构(API 密钥、每个评审者的模型覆盖、本地服务器主机地址)请参阅[配置](../CONFIGURATION.md)。
@@ -49,17 +49,17 @@ gsd config-set review.default_reviewers '["codex","claude"]'
### 标准评审(使用已配置的默认值或所有检测到的 CLI)
```bash
/gsd-review --phase 3
/msd-review --phase 3
```
GSD 会依次调用每位评审者,收集结构化反馈(摘要、优点、HIGH/MEDIUM/LOW 级别问题、建议、风险评估),并将合并后的输出写入 `.planning/phases/03-.../03-REVIEWS.md`。
MSD 会依次调用每位评审者,收集结构化反馈(摘要、优点、HIGH/MEDIUM/LOW 级别问题、建议、风险评估),并将合并后的输出写入 `.planning/phases/03-.../03-REVIEWS.md`。
### 为一次性运行选择单个评审者
```bash
/gsd-review --phase 3 --agy
/gsd-review --phase 3 --codex
/gsd-review --phase 3 --cursor
/msd-review --phase 3 --agy
/msd-review --phase 3 --codex
/msd-review --phase 3 --cursor
```
任何显式标志都会覆盖该次运行的 `--all` 默认值和 `review.default_reviewers`。
@@ -67,7 +67,7 @@ GSD 会依次调用每位评审者,收集结构化反馈(摘要、优点、H
### 并行运行所有可用评审者
```bash
/gsd-review --phase 3 --all
/msd-review --phase 3 --all
```
`--all` 始终覆盖配置,运行完整的检测集合,包括任何已配置的本地模型服务器(Ollama、LM Studio、llama.cpp)。
@@ -77,11 +77,11 @@ GSD 会依次调用每位评审者,收集结构化反馈(摘要、优点、H
如果您在本地运行 Ollama 或 LM Studio,当服务器可达时,使用 `--all` 会自动将其包含在内。您也可以显式指定:
```bash
/gsd-review --phase 3 --ollama
/gsd-review --phase 3 --lm-studio
/msd-review --phase 3 --ollama
/msd-review --phase 3 --lm-studio
```
如果默认值(`localhost:11434` / `localhost:1234`)不适用,请通过 `/gsd-config --integrations` 在 `review.*` 键下配置主机地址和模型选择。
如果默认值(`localhost:11434` / `localhost:1234`)不适用,请通过 `/msd-config --integrations` 在 `review.*` 键下配置主机地址和模型选择。
---
@@ -100,7 +100,7 @@ GSD 会依次调用每位评审者,收集结构化反馈(摘要、优点、H
查看输出后,结合反馈重新规划:
```bash
/gsd-plan-phase 3 --reviews
/msd-plan-phase 3 --reviews
```
规划器会读取 `REVIEWS.md`,并在保存前调整计划以解决相关问题。
@@ -112,7 +112,7 @@ GSD 会依次调用每位评审者,收集结构化反馈(摘要、优点、H
对于希望迭代直至所有 HIGH 级别问题解决的阶段,请使用收敛循环:
```bash
/gsd-plan-review-convergence 3
/msd-plan-review-convergence 3
```
此命令运行 `plan-phase → review → replan → re-review`,最多循环三次(默认)。当 HIGH 级别问题数量降至零时,循环退出。
@@ -120,17 +120,17 @@ GSD 会依次调用每位评审者,收集结构化反馈(摘要、优点、H
### 使用特定评审者进行收敛
```bash
/gsd-plan-review-convergence 3 --codex
/gsd-plan-review-convergence 3 --agy
/msd-plan-review-convergence 3 --codex
/msd-plan-review-convergence 3 --agy
```
### 使用所有评审者并提高循环上限进行收敛
```bash
/gsd-plan-review-convergence 3 --all --max-cycles 5
/msd-plan-review-convergence 3 --all --max-cycles 5
```
**停滞检测:** 如果 HIGH 级别问题数量在各轮次间未减少,GSD 会向您发出警告。当循环上限已达但仍存在未解决的 HIGH 级别问题时,升级门控会询问是否继续或手动审查。
**停滞检测:** 如果 HIGH 级别问题数量在各轮次间未减少,MSD 会向您发出警告。当循环上限已达但仍存在未解决的 HIGH 级别问题时,升级门控会询问是否继续或手动审查。
---
@@ -143,8 +143,8 @@ GSD 会依次调用每位评审者,收集结构化反馈(摘要、优点、H
| 项目以 OpenAI 为主 | 添加 `--codex` 以获取 OpenAI 模型视角 |
| 希望使用 GitHub Copilot 的模型 | 添加 `--opencode` |
| 希望完全避免 API 费用 | 使用本地模型配置 Ollama 并使用 `--ollama` |
| 发布前需要最大覆盖率 | `/gsd-plan-review-convergence N --all` |
| 快速迭代并希望获得快速反馈 | 选择一个 CLI:`/gsd-review --phase N --agy` |
| 发布前需要最大覆盖率 | `/msd-plan-review-convergence N --all` |
| 快速迭代并希望获得快速反馈 | 选择一个 CLI:`/msd-review --phase N --agy` |
---

View File

@@ -2,7 +2,7 @@
**目标:** 在将某个阶段锁定到具体方案之前,通过聚焦的可行性实验(spike)和一次性 HTML 原型(sketch)来降低实现风险。
**前提条件:** 无。`/gsd-spike` 和 `/gsd-sketch` 会自行创建所需的存储目录,不要求已初始化 GSD 项目。
**前提条件:** 无。`/msd-spike` 和 `/msd-sketch` 会自行创建所需的存储目录,不要求已初始化 MSD 项目。
---
@@ -10,8 +10,8 @@
| 你想回答的问题… | 使用 |
|---|---|
| "这个技术方案真的可行吗?" | `/gsd-spike` |
| "这个布局 / 交互 / 视觉处理感觉对吗?" | `/gsd-sketch` |
| "这个技术方案真的可行吗?" | `/msd-spike` |
| "这个布局 / 交互 / 视觉处理感觉对吗?" | `/msd-sketch` |
| "正确的技术方案是什么,它应该长什么样?" | 两者都用,顺序是:先 spike,再 sketch |
Spike 通过可执行代码和 VALIDATED / INVALIDATED / PARTIAL 结论来回答二元可行性问题。Sketch 通过 2–3 个可在浏览器中对比的 HTML 变体来回答视觉问题。两者互为补充——spike 证明方案可构建,sketch 证明设计值得构建。
@@ -23,21 +23,21 @@ Spike 通过可执行代码和 VALIDATED / INVALIDATED / PARTIAL 结论来回答
### 交互式引导(默认)
```bash
/gsd-spike
/msd-spike
```
GSD 会询问技术问题,将其分解为 2–5 个独立实验,以 **Given / When / Then** 假设形式呈现,并在开始构建前请求确认。
MSD 会询问技术问题,将其分解为 2–5 个独立实验,以 **Given / When / Then** 假设形式呈现,并在开始构建前请求确认。
### 直接提供想法
```bash
/gsd-spike "can we stream LLM tokens through SSE"
/msd-spike "can we stream LLM tokens through SSE"
```
### 跳过引导,直接运行
```bash
/gsd-spike --quick "websocket vs SSE latency"
/msd-spike --quick "websocket vs SSE latency"
```
`--quick` 跳过分解对话,直接将参数作为单个 spike 问题处理。当问题已经足够具体、无需进一步细化时使用此选项。
@@ -59,10 +59,10 @@ GSD 会询问技术问题,将其分解为 2–5 个独立实验,以 **Given
当你获得有效信号后,将调查结果封装成项目本地技能,以便后续会话自动加载:
```bash
/gsd-spike --wrap-up
/msd-spike --wrap-up
```
此命令会写入 `.claude/skills/spike-findings-[project]/`。该技能会被自动发现,并在后续的 `/gsd-sketch`、`/gsd-ui-phase` 和 `/gsd-plan-phase` 运行时加载——无需显式引用。
此命令会写入 `.claude/skills/spike-findings-[project]/`。该技能会被自动发现,并在后续的 `/msd-sketch`、`/msd-ui-phase` 和 `/msd-plan-phase` 运行时加载——无需显式引用。
---
@@ -71,21 +71,21 @@ GSD 会询问技术问题,将其分解为 2–5 个独立实验,以 **Given
### 风格引导(默认)
```bash
/gsd-sketch
/msd-sketch
```
GSD 会开启一段简短对话,在编写任何代码之前探索感觉、视觉参考和核心用户操作。它每次只问一个问题,只有在你说"开始"后才动手构建。
MSD 会开启一段简短对话,在编写任何代码之前探索感觉、视觉参考和核心用户操作。它每次只问一个问题,只有在你说"开始"后才动手构建。
### 直接提供设计方向
```bash
/gsd-sketch "dashboard layout"
/msd-sketch "dashboard layout"
```
### 跳过风格引导,直接运行
```bash
/gsd-sketch --quick "sidebar navigation"
/msd-sketch --quick "sidebar navigation"
```
`--quick` 完全跳过引导对话,直接使用参数作为设计方向。
@@ -93,7 +93,7 @@ GSD 会开启一段简短对话,在编写任何代码之前探索感觉、视
### 非 Claude 运行时(Codex、Antigravity CLI 等)
```bash
/gsd-sketch --text "onboarding flow"
/msd-sketch --text "onboarding flow"
```
`--text` 将交互式提示替换为纯文本编号列表。当你的运行时不支持 `AskUserQuestion` 时使用此选项。
@@ -115,10 +115,10 @@ GSD 会开启一段简短对话,在编写任何代码之前探索感觉、视
选定变体后,将视觉决策捕获到项目本地技能中:
```bash
/gsd-sketch --wrap-up
/msd-sketch --wrap-up
```
此命令会写入 `.claude/skills/sketch-findings-[project]/`。该技能由 `/gsd-ui-phase` 自动获取——经过预验证的决策(布局、色彩方案、排版、间距)被视为已锁定,不会再次询问。
此命令会写入 `.claude/skills/sketch-findings-[project]/`。该技能由 `/msd-ui-phase` 自动获取——经过预验证的决策(布局、色彩方案、排版、间距)被视为已锁定,不会再次询问。
---
@@ -127,26 +127,26 @@ GSD 会开启一段简短对话,在编写任何代码之前探索感觉、视
当你对技术可行性和视觉方向都不确定时,推荐使用以下顺序:
```bash
/gsd-spike "SSE vs WebSocket for real-time feed"
/gsd-spike --wrap-up
/msd-spike "SSE vs WebSocket for real-time feed"
/msd-spike --wrap-up
/gsd-sketch "real-time feed UI"
/gsd-sketch --wrap-up
/msd-sketch "real-time feed UI"
/msd-sketch --wrap-up
/gsd-discuss-phase N
/gsd-plan-phase N
/msd-discuss-phase N
/msd-plan-phase N
```
spike 调查结果会为 sketch 提供参考(真实数据结构、真实交互状态、实际约束)。两次 wrap-up 均会持久化决策,规划器和 UI 研究员会自动加载,因此在 `/gsd-discuss-phase` 或 `/gsd-ui-phase` 期间无需重新解释选择。
spike 调查结果会为 sketch 提供参考(真实数据结构、真实交互状态、实际约束)。两次 wrap-up 均会持久化决策,规划器和 UI 研究员会自动加载,因此在 `/msd-discuss-phase` 或 `/msd-ui-phase` 期间无需重新解释选择。
---
## spike 或 sketch 如何流入某个阶段
Spike 和 sketch 的产物不需要手动引用。GSD 会在以下两个时间点自动读取它们:
Spike 和 sketch 的产物不需要手动引用。MSD 会在以下两个时间点自动读取它们:
1. **`/gsd-sketch`** — 在构建原型前加载 `.claude/skills/spike-findings-*/`,使变体反映已验证的约束(流式状态、真实字段名等)
2. **`/gsd-ui-phase N`** — 在生成 UI 设计契约前加载 `.claude/skills/sketch-findings-*/`;经过预验证的设计决策被视为已锁定
1. **`/msd-sketch`** — 在构建原型前加载 `.claude/skills/spike-findings-*/`,使变体反映已验证的约束(流式状态、真实字段名等)
2. **`/msd-ui-phase N`** — 在生成 UI 设计契约前加载 `.claude/skills/sketch-findings-*/`;经过预验证的设计决策被视为已锁定
当存在 `spike-findings-*` 技能时,规划器也会读取 spike 调查结果,从而使已验证的技术选择(采用哪个库、哪种协议、哪种数据格式)直接流入任务计划,无需反复解释。

View File

@@ -1,8 +1,8 @@
# 如何更新 GSD Core
# 如何更新 MSD Core
将现有的 GSD Core 安装更新到最新版本,在确认前预览变更日志,并恢复可能被更新覆盖的本地自定义配置。
将现有的 MSD Core 安装更新到最新版本,在确认前预览变更日志,并恢复可能被更新覆盖的本地自定义配置。
**所需条件:** 与 GSD 安装时相同的运行时环境。更新命令在后台重新运行安装程序,因此需要 Node.js 和 npx(与最初安装时的要求相同)。
**所需条件:** 与 MSD 安装时相同的运行时环境。更新命令在后台重新运行安装程序,因此需要 Node.js 和 npx(与最初安装时的要求相同)。
---
@@ -11,19 +11,19 @@
在 AI 运行时内,执行:
```bash
/gsd-update
/msd-update
```
GSD 将执行以下操作:
MSD 将执行以下操作:
1. 检测已安装的版本和安装范围(全局或本地)。
2. 通过 npm 检查 `@opengsd/gsd-core` 的最新版本。
2. 通过 npm 检查 `@golem15/msd-core` 的最新版本。
3. 获取变更日志,并显示您已安装版本与最新版本之间的变更内容。
4. 在执行任何操作前请求确认。
5. 将 GSD 管理目录中发现的用户添加文件备份至 `gsd-user-files-backup/`。
6. 运行安装程序(`npx @opengsd/gsd-core@latest --<runtime> --<scope>`)。
5. 将 MSD 管理目录中发现的用户添加文件备份至 `msd-user-files-backup/`。
6. 运行安装程序(`npx @golem15/msd-core@latest --<runtime> --<scope>`)。
7. 清除更新检查缓存,使状态栏指示器重置。
8. 报告本地修改的 GSD 文件是否已备份至 `gsd-local-patches/`。
8. 报告本地修改的 MSD 文件是否已备份至 `msd-local-patches/`。
更新完成后请重启运行时,以加载新的命令和代理。
@@ -33,22 +33,22 @@ GSD 将执行以下操作:
| 标志 | 功能说明 |
|------|--------------|
| `--sync` | 更新后,从 GSD 注册表同步技能 |
| `--reapply` | 更新后,将 `gsd-local-patches/` 中本地修改的 GSD 文件合并回来 |
| `--sync` | 更新后,从 MSD 注册表同步技能 |
| `--reapply` | 更新后,将 `msd-local-patches/` 中本地修改的 MSD 文件合并回来 |
```bash
/gsd-update --sync # Update and sync skills
/gsd-update --reapply # Update and reapply local patches
/msd-update --sync # Update and sync skills
/msd-update --reapply # Update and reapply local patches
```
---
## 更新前查看变更日志
`/gsd-update` 在请求确认*之前*,始终会显示您已安装版本与最新版本之间的变更日志差异。您无需另行访问 GitHub。输出内容如下所示:
`/msd-update` 在请求确认*之前*,始终会显示您已安装版本与最新版本之间的变更日志差异。您无需另行访问 GitHub。输出内容如下所示:
```text
## GSD Update Available
## MSD Update Available
Installed: 1.39.0
Latest: 1.41.0
@@ -70,47 +70,47 @@ Proceed with update? [Yes, update now / No, cancel]
## 恢复本地自定义配置
### 您在 GSD 管理目录中添加的文件
### 您在 MSD 管理目录中添加的文件
如果您在 GSD 管理的目录中放置了自定义文件(例如,以 `gsd-` 为前缀的自定义代理,或 `commands/gsd/` 中的额外文件),安装程序会在清除这些目录前检测到它们,并将其复制到 `gsd-user-files-backup/`。更新完成后,请从该备份位置手动恢复这些文件。
如果您在 MSD 管理的目录中放置了自定义文件(例如,以 `msd-` 为前缀的自定义代理,或 `commands/msd/` 中的额外文件),安装程序会在清除这些目录前检测到它们,并将其复制到 `msd-user-files-backup/`。更新完成后,请从该备份位置手动恢复这些文件。
您放置在 GSD 管理目录之外的文件——不以 `gsd-` 为前缀的自定义代理、`commands/gsd/` 之外的自定义命令、您的 `CLAUDE.md` 文件以及自定义钩子——安装程序不会对其进行任何操作。
您放置在 MSD 管理目录之外的文件——不以 `msd-` 为前缀的自定义代理、`commands/msd/` 之外的自定义命令、您的 `CLAUDE.md` 文件以及自定义钩子——安装程序不会对其进行任何操作。
### 您直接修改的 GSD 文件
### 您直接修改的 MSD 文件
如果您编辑了 GSD 安装的某个文件(例如,调整了某个代理的系统提示),安装程序会通过与清单的哈希比对检测到该修改,将文件备份至 `gsd-local-patches/`,然后用新版本替换它。更新完成后,执行:
如果您编辑了 MSD 安装的某个文件(例如,调整了某个代理的系统提示),安装程序会通过与清单的哈希比对检测到该修改,将文件备份至 `msd-local-patches/`,然后用新版本替换它。更新完成后,执行:
```bash
/gsd-update --reapply
/msd-update --reapply
```
此命令会将您在 `gsd-local-patches/` 中的修改合并回新安装的文件中。
此命令会将您在 `msd-local-patches/` 中的修改合并回新安装的文件中。
如果您在之前的更新后跳过了 `--reapply`,现在想应用补丁,执行:
```bash
/gsd-update --reapply
/msd-update --reapply
```
单独运行 `--reapply` 而不触发新下载是安全的——如果您已是最新版本,GSD 会跳过安装步骤,直接执行补丁重新应用。
单独运行 `--reapply` 而不触发新下载是安全的——如果您已是最新版本,MSD 会跳过安装步骤,直接执行补丁重新应用。
---
## 当 npm 不可用时
如果 `npx @opengsd/gsd-core@latest` 因 npm 中断、网络限制,或因您正在使用源代码仓库而失败,请使用 [docs/manual-update.md](../../manual-update.md) 中的手动更新流程。该文档涵盖拉取最新提交、构建钩子分发包以及直接运行 `node bin/install.js` 的步骤。
如果 `npx @golem15/msd-core@latest` 因 npm 中断、网络限制,或因您正在使用源代码仓库而失败,请使用 [docs/manual-update.md](../../manual-update.md) 中的手动更新流程。该文档涵盖拉取最新提交、构建钩子分发包以及直接运行 `node bin/install.js` 的步骤。
---
## 如果您已是最新版本
`/gsd-update` 会提前退出并显示确认消息——无需下载、无需安装、无需重启。
`/msd-update` 会提前退出并显示确认消息——无需下载、无需安装、无需重启。
---
## 安装程序迁移
每个 GSD 版本可能包含安装程序迁移,用于重命名、移动或停用管理文件。迁移层会在写入新包内容之前自动运行。会影响您已修改文件的迁移操作将提示确认,而不是静默执行。有关完整设计和运行时配置合约注册表,请参阅 [docs/installer-migrations.md](../../installer-migrations.md)。
每个 MSD 版本可能包含安装程序迁移,用于重命名、移动或停用管理文件。迁移层会在写入新包内容之前自动运行。会影响您已修改文件的迁移操作将提示确认,而不是静默执行。有关完整设计和运行时配置合约注册表,请参阅 [docs/installer-migrations.md](../../installer-migrations.md)。
---

View File

@@ -9,36 +9,36 @@
## 运行用户验收测试
```bash
/gsd-verify-work 1
/msd-verify-work 1
```
GSD Core 读取该阶段的 `SUMMARY.md` 文件,提取用户可观测的交付物,并逐一引导您完成验证。对于每个检查点,它会展示*应该*发生的情况,并询问实际情况是否与之匹配。
MSD Core 读取该阶段的 `SUMMARY.md` 文件,提取用户可观测的交付物,并逐一引导您完成验证。对于每个检查点,它会展示*应该*发生的情况,并询问实际情况是否与之匹配。
- `yes` / `y` / 直接回车 → 通过,进入下一项测试
- 其他任何输入 → 记录为问题,严重程度根据您的描述推断
您无需手动分类严重程度——GSD Core 会从您的描述中推断("崩溃" → 阻塞级,"无法使用" → 严重级,"看起来不对" → 外观级)。
您无需手动分类严重程度——MSD Core 会从您的描述中推断("崩溃" → 阻塞级,"无法使用" → 严重级,"看起来不对" → 外观级)。
进度将写入 `.planning/phases/01-<name>/01-UAT.md`,在 `/clear` 之后依然保留。若会话中断,重新运行 `/gsd-verify-work 1`,GSD Core 会提示是否从上次检查点恢复。
进度将写入 `.planning/phases/01-<name>/01-UAT.md`,在 `/clear` 之后依然保留。若会话中断,重新运行 `/msd-verify-work 1`,MSD Core 会提示是否从上次检查点恢复。
---
## 发现失败时:自动诊断与修复规划
如果有测试报告问题,GSD Core 会自动执行以下步骤:
如果有测试报告问题,MSD Core 会自动执行以下步骤:
1. **诊断根本原因** — 为每个问题并行启动调试代理,并将根本原因更新至 `UAT.md`。
2. **规划差距弥补** — 在差距弥补模式下启动 `gsd-planner`,读取 `UAT.md`(含诊断结果)并生成新的 `PLAN.md` 文件。
3. **验证修复计划** — 启动 `gsd-plan-checker` 确保计划可执行。若发现问题,规划器与检查器最多迭代三次。
2. **规划差距弥补** — 在差距弥补模式下启动 `msd-planner`,读取 `UAT.md`(含诊断结果)并生成新的 `PLAN.md` 文件。
3. **验证修复计划** — 启动 `msd-plan-checker` 确保计划可执行。若发现问题,规划器与检查器最多迭代三次。
4. **呈现下一步** — 当计划通过检查器时:
```
Plans verified and ready for execution.
`/clear` then `/gsd-execute-phase 1 --gaps-only`
`/clear` then `/msd-execute-phase 1 --gaps-only`
```
运行提示的命令以应用修复,然后重新运行 `/gsd-verify-work 1` 确认一切通过。
运行提示的命令以应用修复,然后重新运行 `/msd-verify-work 1` 确认一切通过。
---
@@ -47,14 +47,14 @@ Plans verified and ready for execution.
一旦所有 UAT 测试通过(或首次运行且未发现问题),该阶段将自动在 `ROADMAP.md` 和 `STATE.md` 中标记为已完成。
```bash
/gsd-ship 1
/msd-ship 1
```
GSD Core 执行预检(验证状态、干净的工作树、分支、远程仓库、`gh` CLI 身份验证),推送分支并创建 PR:
MSD Core 执行预检(验证状态、干净的工作树、分支、远程仓库、`gh` CLI 身份验证),推送分支并创建 PR:
```bash
/gsd-ship 1 # 准备审查的 PR
/gsd-ship 1 --draft # 草稿 PR — 当后续还有更多阶段时很有用
/msd-ship 1 # 准备审查的 PR
/msd-ship 1 --draft # 草稿 PR — 当后续还有更多阶段时很有用
```
PR 正文由规划产物自动组装:
@@ -71,19 +71,19 @@ PR 正文由规划产物自动组装:
## 可选:发布前或发布后的代码审查
`/gsd-ship` 不会自动运行代码审查,但您可以在任意节点插入审查:
`/msd-ship` 不会自动运行代码审查,但您可以在任意节点插入审查:
**验证前**(在 UAT 之前发现问题):
```bash
/gsd-code-review 1 # 标准审查
/gsd-code-review 1 --fix # 审查后自动修复 Critical 和 Warning 发现
/msd-code-review 1 # 标准审查
/msd-code-review 1 --fix # 审查后自动修复 Critical 和 Warning 发现
```
**PR 开启后**(在合并前把关质量):
```bash
/gsd-code-review 1 --depth=deep # 包含导入图的跨文件分析
/msd-code-review 1 --depth=deep # 包含导入图的跨文件分析
```
请参阅[配置跨 AI 审查](set-up-cross-ai-review.md),了解如何在周期早期为计划审查配置 Antigravity、Codex 或其他审查工具。
@@ -95,11 +95,11 @@ PR 正文由规划产物自动组装:
如果您的分支包含不希望审查者看到的 `.planning/` 提交:
```bash
/gsd-pr-branch # 相对于 main 进行过滤
/gsd-pr-branch develop # 相对于 develop 进行过滤
/msd-pr-branch # 相对于 main 进行过滤
/msd-pr-branch develop # 相对于 develop 进行过滤
```
`/gsd-pr-branch` 会创建一个仅包含代码变更的新分支——规划产物提交将被排除。若您的团队审查规范不包含规划噪音,请在 `/gsd-ship` 之前运行此命令。
`/msd-pr-branch` 会创建一个仅包含代码变更的新分支——规划产物提交将被排除。若您的团队审查规范不包含规划噪音,请在 `/msd-ship` 之前运行此命令。
---
@@ -108,11 +108,11 @@ PR 正文由规划产物自动组装:
如果这是里程碑中的最后一个阶段,请运行里程碑审计并将其归档:
```bash
/gsd-audit-milestone # 验证所有需求已发布
/gsd-complete-milestone # 归档,创建 git 标签
/msd-audit-milestone # 验证所有需求已发布
/msd-complete-milestone # 归档,创建 git 标签
```
`/gsd-complete-milestone` 是 PR 合并后的自然下一步。请参阅[阶段循环](../explanation/the-phase-loop.md),了解验证与发布如何融入完整的项目生命周期。
`/msd-complete-milestone` 是 PR 合并后的自然下一步。请参阅[阶段循环](../explanation/the-phase-loop.md),了解验证与发布如何融入完整的项目生命周期。
---

View File

@@ -2,7 +2,7 @@
**目标:** 并发推进不同里程碑领域(后端 API、前端仪表板、基础设施或其他关注点)的工作,同时避免一个领域的规划状态污染另一个领域。
**前提条件:** 已激活的 GSD Core 项目(`.planning/ROADMAP.md` 存在)。若尚未创建,请先运行 `/gsd-new-project`。
**前提条件:** 已激活的 MSD Core 项目(`.planning/ROADMAP.md` 存在)。若尚未创建,请先运行 `/msd-new-project`。
---
@@ -28,24 +28,24 @@
└── phases/
```
当某个工作流处于激活状态时,所有 GSD 命令——`/gsd-progress`、`/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase`——都将从该工作流的目录读取并写入。切换工作流会将所有这些命令重定向到另一个子树,而不会影响源代码树。
当某个工作流处于激活状态时,所有 MSD 命令——`/msd-progress`、`/msd-discuss-phase`、`/msd-plan-phase`、`/msd-execute-phase`——都将从该工作流的目录读取并写入。切换工作流会将所有这些命令重定向到另一个子树,而不会影响源代码树。
---
## 创建工作流
```bash
/gsd-workstreams create backend-api
/msd-workstreams create backend-api
```
GSD 会在 `.planning/workstreams/backend-api/` 下创建工作流目录,并初始化一个框架 `STATE.md` 和 `ROADMAP.md`。工作流不会自动激活——需要显式切换。
MSD 会在 `.planning/workstreams/backend-api/` 下创建工作流目录,并初始化一个框架 `STATE.md` 和 `ROADMAP.md`。工作流不会自动激活——需要显式切换。
---
## 列出工作流
```bash
/gsd-workstreams list
/msd-workstreams list
```
显示所有工作流,以及当前会话中哪个工作流处于激活状态。
@@ -55,26 +55,26 @@ GSD 会在 `.planning/workstreams/backend-api/` 下创建工作流目录,并
## 切换到某个工作流
```bash
/gsd-workstreams switch backend-api
/msd-workstreams switch backend-api
```
从此时起,所有 GSD 工作流命令均在 `backend-api` 上下文中运行。切换是会话范围的:当多个 Claude Code 终端同时打开同一仓库时,每个会话可以持有不同的激活工作流,互不干扰。
从此时起,所有 MSD 工作流命令均在 `backend-api` 上下文中运行。切换是会话范围的:当多个 Claude Code 终端同时打开同一仓库时,每个会话可以持有不同的激活工作流,互不干扰。
切换后,按正常阶段工作流推进:
```bash
/gsd-discuss-phase 1
/gsd-plan-phase 1
/gsd-execute-phase 1
/gsd-verify-work 1
/msd-discuss-phase 1
/msd-plan-phase 1
/msd-execute-phase 1
/msd-verify-work 1
```
如需在另一个领域工作,在第二个终端中切换工作流:
```bash
/gsd-workstreams switch frontend-dash
/gsd-discuss-phase 1
/gsd-plan-phase 1
/msd-workstreams switch frontend-dash
/msd-discuss-phase 1
/msd-plan-phase 1
```
---
@@ -82,7 +82,7 @@ GSD 会在 `.planning/workstreams/backend-api/` 下创建工作流目录,并
## 查看所有工作流的进度
```bash
/gsd-workstreams progress
/msd-workstreams progress
```
打印跨工作流摘要——每个工作流的阶段状态、当前位置和未完成工作——无需在工作流之间来回切换。
@@ -90,7 +90,7 @@ GSD 会在 `.planning/workstreams/backend-api/` 下创建工作流目录,并
查看单个工作流的详细状态:
```bash
/gsd-workstreams status backend-api
/msd-workstreams status backend-api
```
---
@@ -100,10 +100,10 @@ GSD 会在 `.planning/workstreams/backend-api/` 下创建工作流目录,并
在上下文重置或新会话后,恢复您的位置:
```bash
/gsd-workstreams resume backend-api
/msd-workstreams resume backend-api
```
此命令会激活该工作流并恢复上次已知位置,等价于切换后再运行 `/gsd-resume-work`。
此命令会激活该工作流并恢复上次已知位置,等价于切换后再运行 `/msd-resume-work`。
---
@@ -112,10 +112,10 @@ GSD 会在 `.planning/workstreams/backend-api/` 下创建工作流目录,并
当某个工作流的里程碑工作完成时:
```bash
/gsd-workstreams complete backend-api
/msd-workstreams complete backend-api
```
GSD 会将该工作流标记为已归档,并将其从活跃列表中移出。规划产物将保留在 `.planning/workstreams/backend-api/` 下以供审计。
MSD 会将该工作流标记为已归档,并将其从活跃列表中移出。规划产物将保留在 `.planning/workstreams/backend-api/` 下以供审计。
---
@@ -124,8 +124,8 @@ GSD 会将该工作流标记为已归档,并将其从活跃列表中移出。
如需对某个特定工作流运行一条命令,而不更改当前会话的激活上下文,请使用 `--ws` 标志:
```bash
/gsd-progress --ws frontend-dash
/gsd-plan-phase 2 --ws backend-api
/msd-progress --ws frontend-dash
/msd-plan-phase 2 --ws backend-api
```
`--ws` 在解析顺序中具有最高优先级,不会更改会话范围的指针。
@@ -145,7 +145,7 @@ GSD 会将该工作流标记为已归档,并将其从活跃列表中移出。
- 您需要在**多个仓库**之间工作(例如 `hr-ui` 和 `ZeymoAPI`)
- 每个功能需要**独立 git worktree** 或克隆的隔离——完全独立的分支、锁文件和构建产物
- 您希望在每个工作区中独立运行 `/gsd-new-project`,拥有完全独立的 `.planning/` 根目录,而不是主仓库 `.planning/` 的子目录
- 您希望在每个工作区中独立运行 `/msd-new-project`,拥有完全独立的 `.planning/` 根目录,而不是主仓库 `.planning/` 的子目录
---

View File

@@ -1,56 +1,56 @@
# 使用 GSD 进行议题驱动的编排
# 使用 MSD 进行议题驱动的编排
**状态:** 稳定工作流指南
**受众:** 在 GitHub Issues、Linear、Jira 或类似议题跟踪系统中管理工作的开发者,希望通过 GSD 现有原语驱动 AI 辅助实现。
**受众:** 在 GitHub Issues、Linear、Jira 或类似议题跟踪系统中管理工作的开发者,希望通过 MSD 现有原语驱动 AI 辅助实现。
## 本指南的内容
本指南提供一套方案,将 GSD 已有的命令组合成一个"议题跟踪 → 工作区 → 计划/执行 → 验证/审核 → PR"的循环。这仅是文档说明。无新命令、无守护进程、无跟踪系统集成 —— 下文引用的每一条命令在 GSD 中均已存在。
本指南提供一套方案,将 MSD 已有的命令组合成一个"议题跟踪 → 工作区 → 计划/执行 → 验证/审核 → PR"的循环。这仅是文档说明。无新命令、无守护进程、无跟踪系统集成 —— 下文引用的每一条命令在 MSD 中均已存在。
本方案的结构受到 OpenAI 开源 [Symphony 编排参考](https://openai.com/index/open-source-codex-orchestration-symphony/)([代码库](https://github.com/openai/symphony))的启发。GSD 不内嵌或封装 Symphony。Symphony 中的编排*概念*可以清晰地映射到 GSD 已有的原语上;本指南只是将这种映射明确阐述出来,让你无需编写粘合代码或绕过 GSD 的安全门控即可采用该模式。
本方案的结构受到 OpenAI 开源 [Symphony 编排参考](https://openai.com/index/open-source-codex-orchestration-symphony/)([代码库](https://github.com/openai/symphony))的启发。MSD 不内嵌或封装 Symphony。Symphony 中的编排*概念*可以清晰地映射到 MSD 已有的原语上;本指南只是将这种映射明确阐述出来,让你无需编写粘合代码或绕过 MSD 的安全门控即可采用该模式。
## 为何存在本指南
GSD 具备议题驱动 AI 开发的基础构建块 ——
`/gsd-workspace --new`、`/gsd-manager`、`/gsd-autonomous`、`/gsd-verify-work`、
`/gsd-review`、`/gsd-ship`,以及 `STATE.md` 和阶段产物套件
MSD 具备议题驱动 AI 开发的基础构建块 ——
`/msd-workspace --new`、`/msd-manager`、`/msd-autonomous`、`/msd-verify-work`、
`/msd-review`、`/msd-ship`,以及 `STATE.md` 和阶段产物套件
—— 但缺少一份说明如何从单个跟踪议题驱动它们、无需编写自定义编排脚本的指南。没有这份指南,常见的失效模式是:
- 使用不足:开发者手动运行 discuss/plan/execute,即使工作模式完全适合,也从未使用
`/gsd-manager` 或 `/gsd-autonomous`。
`/msd-manager` 或 `/msd-autonomous`。
- 绕过脚本:开发者在跟踪系统与 `claude` 调用之间编写临时 shell 循环,绕过 `STATE.md`、阶段清单和验证门控。
本指南使规范循环变得易于发现。
## 概念映射
每行将 Symphony 风格的编排概念映射到 GSD 中对应的原语。在阅读 Symphony 文档、博客文章或第三方编排资料时,可将此表用作转换参考。
每行将 Symphony 风格的编排概念映射到 MSD 中对应的原语。在阅读 Symphony 文档、博客文章或第三方编排资料时,可将此表用作转换参考。
| Symphony 概念 | GSD 原语 |
| Symphony 概念 | MSD 原语 |
|---|---|
| `WORKFLOW.md`(顶层意图) | `ROADMAP.md`(项目意图)、`STATE.md`(实时状态)、阶段 `CONTEXT.md`(每阶段范围)、阶段 `PLAN.md`(可执行步骤) |
| 每个任务一个独立的代理工作区 | `/gsd-workspace --new --strategy worktree` |
| 代理调度与并发 | `/gsd-manager`(交互式仪表板)、`/gsd-autonomous`(无人值守) |
| 每阶段的计划与讨论步骤 | `/gsd-discuss-phase` → `/gsd-plan-phase` → `/gsd-execute-phase` |
| 工作证明 / 测试证据 | `/gsd-verify-work`(UAT.md 在 `/clear` 后持久保存) |
| 对抗性审核 | `/gsd-review`(由独立 AI CLI 对计划进行交叉对等审核) |
| 人工合并门控 | `/gsd-ship`(创建 PR,可选代码审查,准备合并) |
| 后续工作捕获 | `/gsd-capture`、`/gsd-capture --seed`、`/gsd-new-milestone`,或手动打开的跟踪议题 |
| 每个任务一个独立的代理工作区 | `/msd-workspace --new --strategy worktree` |
| 代理调度与并发 | `/msd-manager`(交互式仪表板)、`/msd-autonomous`(无人值守) |
| 每阶段的计划与讨论步骤 | `/msd-discuss-phase` → `/msd-plan-phase` → `/msd-execute-phase` |
| 工作证明 / 测试证据 | `/msd-verify-work`(UAT.md 在 `/clear` 后持久保存) |
| 对抗性审核 | `/msd-review`(由独立 AI CLI 对计划进行交叉对等审核) |
| 人工合并门控 | `/msd-ship`(创建 PR,可选代码审查,准备合并) |
| 后续工作捕获 | `/msd-capture`、`/msd-capture --seed`、`/msd-new-milestone`,或手动打开的跟踪议题 |
| 并发控制 | Manager / 后台代理语义(无持续轮询器) |
映射是单向的:GSD 持有安全门控(验证、人工审核、后续工作创建的明确确认)。Symphony 的"持续编排"框架被有意地未采用 —— 参见[非目标](#非目标)。
映射是单向的:MSD 持有安全门控(验证、人工审核、后续工作创建的明确确认)。Symphony 的"持续编排"框架被有意地未采用 —— 参见[非目标](#非目标)。
## 端到端流程
规范的"议题 → PR"循环,设计为可从单个跟踪议题端到端运行。运行前请替换括号中的占位符。
1. **选择跟踪议题。** 从你的跟踪系统(GitHub、Linear 等)中选择一个范围足够明确可供自主实现的议题 —— 边界清晰、验收标准可观察、没有阻碍执行的上游依赖。
2. **映射到 GSD 阶段。** 如果该议题对应 `ROADMAP.md` 中已有的阶段,选择它。若无,运行 `/gsd-new-milestone`(用于一批相关议题的新里程碑),或通过 `/gsd-phase` / `/gsd-phase --insert` 打开一个阶段。将跟踪议题 URL 写入该阶段的 `CONTEXT.md`,确保可追溯性在压缩后依然保留。
3. **创建独立工作区。** 运行 `/gsd-workspace --new --strategy worktree <slug>`,以创建一个带有独立 `.planning/` 目录的 git 工作树。工作树是安全边界:任何探索、部分提交或中止的计划都保留在 `main` 之外。
4. **通过 GSD 运行 discuss → plan → execute。** 在工作区内部运行 `/gsd-discuss-phase` 澄清歧义,运行 `/gsd-plan-phase` 生成 `PLAN.md`,再通过 `/gsd-manager`(交互式仪表板)或 `/gsd-execute-phase` / `/gsd-autonomous`(无人值守)来实现。避免从 GSD 外部直接驱动原始 `claude` 调用 —— 这会绕过 `STATE.md` 更新和阶段清单。
5. **要求工作证明。** 运行 `/gsd-verify-work`,引导用户根据阶段的验收标准进行 UAT。测试、截图、日志捕获和配置差异均记录在 `UAT.md` 中,该文件在 `/clear` 后持久保存,并在验证发现遗漏范围时通过 `/gsd-plan-phase --gaps` 补充缺口。
6. **通过审核和发布门控。** 运行 `/gsd-review`,从独立 AI CLI 获取对计划的对抗性对等审核(逐模型发现盲点),然后运行 `/gsd-ship`,从规划产物中组装丰富的 PR 正文并打开 PR。两个门控都需要人工决策,之后才能推送到远端。
7. **明确捕获后续工作。** 使用 `/gsd-capture` 记录内联备注,使用 `/gsd-capture --seed` 记录值得未来阶段处理的想法,或使用 `/gsd-new-milestone` 记录一组有关联的后续工作。从发现的后续工作创建跟踪议题需要明确的用户确认 —— GSD 不会自动向远程跟踪系统发布内容。
2. **映射到 MSD 阶段。** 如果该议题对应 `ROADMAP.md` 中已有的阶段,选择它。若无,运行 `/msd-new-milestone`(用于一批相关议题的新里程碑),或通过 `/msd-phase` / `/msd-phase --insert` 打开一个阶段。将跟踪议题 URL 写入该阶段的 `CONTEXT.md`,确保可追溯性在压缩后依然保留。
3. **创建独立工作区。** 运行 `/msd-workspace --new --strategy worktree <slug>`,以创建一个带有独立 `.planning/` 目录的 git 工作树。工作树是安全边界:任何探索、部分提交或中止的计划都保留在 `main` 之外。
4. **通过 MSD 运行 discuss → plan → execute。** 在工作区内部运行 `/msd-discuss-phase` 澄清歧义,运行 `/msd-plan-phase` 生成 `PLAN.md`,再通过 `/msd-manager`(交互式仪表板)或 `/msd-execute-phase` / `/msd-autonomous`(无人值守)来实现。避免从 MSD 外部直接驱动原始 `claude` 调用 —— 这会绕过 `STATE.md` 更新和阶段清单。
5. **要求工作证明。** 运行 `/msd-verify-work`,引导用户根据阶段的验收标准进行 UAT。测试、截图、日志捕获和配置差异均记录在 `UAT.md` 中,该文件在 `/clear` 后持久保存,并在验证发现遗漏范围时通过 `/msd-plan-phase --gaps` 补充缺口。
6. **通过审核和发布门控。** 运行 `/msd-review`,从独立 AI CLI 获取对计划的对抗性对等审核(逐模型发现盲点),然后运行 `/msd-ship`,从规划产物中组装丰富的 PR 正文并打开 PR。两个门控都需要人工决策,之后才能推送到远端。
7. **明确捕获后续工作。** 使用 `/msd-capture` 记录内联备注,使用 `/msd-capture --seed` 记录值得未来阶段处理的想法,或使用 `/msd-new-milestone` 记录一组有关联的后续工作。从发现的后续工作创建跟踪议题需要明确的用户确认 —— MSD 不会自动向远程跟踪系统发布内容。
PR 合并后,循环关闭。PR 正文中的自动关闭关键词(`Closes #NNN` / `Fixes #NNN`)会在合并时关闭跟踪议题。
@@ -58,30 +58,30 @@ PR 合并后,循环关闭。PR 正文中的自动关闭关键词(`Closes #NN
该循环之所以安全,是因为四项不变量在构建上得到保证:
- **独立工作树。** 每个议题在 `/gsd-workspace --new` 工作树中运行,因此部分工作、中止的计划和探索性提交永远不会触及 `main`。`gsd-local-patches/` 是恢复入口,当工作树的手动编辑需要跨更新带回时可使用。
- **明确的人工审核。** `/gsd-review` 和 `/gsd-ship` 均会停下来等待人工批准。没有自动合并,也没有从执行路径自动创建 PR 的路径。如果你想为特定代码库移除人工门控,那是你的分支保护 / 合并队列策略决定,而非 GSD 代为选择的。
- **不自动公开发布。** GSD 从不在没有明确用户发起命令的情况下打开、评论或关闭跟踪议题。后续工作捕获默认写入本地产物(备注、种子、里程碑);推回跟踪系统是单独的手动步骤。
- **发布前先验证。** `/gsd-verify-work` 的 UAT.md 必须记录证据,才能运行 `/gsd-ship`。推荐的规范是将 `verification_failed` 视为阻塞项,即使实现看起来正确 —— 失败通常意味着遗漏了验收标准,而非测试不稳定。
- **独立工作树。** 每个议题在 `/msd-workspace --new` 工作树中运行,因此部分工作、中止的计划和探索性提交永远不会触及 `main`。`msd-local-patches/` 是恢复入口,当工作树的手动编辑需要跨更新带回时可使用。
- **明确的人工审核。** `/msd-review` 和 `/msd-ship` 均会停下来等待人工批准。没有自动合并,也没有从执行路径自动创建 PR 的路径。如果你想为特定代码库移除人工门控,那是你的分支保护 / 合并队列策略决定,而非 MSD 代为选择的。
- **不自动公开发布。** MSD 从不在没有明确用户发起命令的情况下打开、评论或关闭跟踪议题。后续工作捕获默认写入本地产物(备注、种子、里程碑);推回跟踪系统是单独的手动步骤。
- **发布前先验证。** `/msd-verify-work` 的 UAT.md 必须记录证据,才能运行 `/msd-ship`。推荐的规范是将 `verification_failed` 视为阻塞项,即使实现看起来正确 —— 失败通常意味着遗漏了验收标准,而非测试不稳定。
如果这些不变量中的任何一项被绕过(例如直接对工作树运行 `claude`、跳过 `/gsd-verify-work`,或在没有用户确认的情况下通过跟踪 API 脚本化创建议题),本指南的保证将不再适用。
如果这些不变量中的任何一项被绕过(例如直接对工作树运行 `claude`、跳过 `/msd-verify-work`,或在没有用户确认的情况下通过跟踪 API 脚本化创建议题),本指南的保证将不再适用。
## 非目标
本指南刻意**不**提出以下任何内容。在此列出,以防止未来贡献者在代码审查中重新讨论:
- **不内嵌或复制 Symphony 代码。** GSD 复用自身原语。上述映射是概念性的;本代码库中不包含任何 Symphony 衍生源码。
- **无长期运行的守护进程。** GSD 不轮询 GitHub 或 Linear。Manager 和自主工作流通过后台代理语义处理并发,而非通过守护进程。
- **无强制跟踪系统依赖。** 该循环无需任何跟踪系统集成即可运行。"跟踪议题"步骤是一种*人工输入* —— URL 写入 `CONTEXT.md`。GSD 不关心你使用哪个跟踪系统,或者你是否使用跟踪系统。
- **不绕过验证、审核或人工决策门控。** 即使在运行 `/gsd-autonomous` 时,验证和审核门控依然触发。"autonomous(自主)"标签指的是阶段间的推进,而非跳过人工批准。
- **不内嵌或复制 Symphony 代码。** MSD 复用自身原语。上述映射是概念性的;本代码库中不包含任何 Symphony 衍生源码。
- **无长期运行的守护进程。** MSD 不轮询 GitHub 或 Linear。Manager 和自主工作流通过后台代理语义处理并发,而非通过守护进程。
- **无强制跟踪系统依赖。** 该循环无需任何跟踪系统集成即可运行。"跟踪议题"步骤是一种*人工输入* —— URL 写入 `CONTEXT.md`。MSD 不关心你使用哪个跟踪系统,或者你是否使用跟踪系统。
- **不绕过验证、审核或人工决策门控。** 即使在运行 `/msd-autonomous` 时,验证和审核门控依然触发。"autonomous(自主)"标签指的是阶段间的推进,而非跳过人工批准。
- **不扩展默认技能 / 命令面。** 本指南引用的每一条命令均已存在。本指南是文档面,而非功能面。
## 可能的未来后续
如果维护者在使用该循环的过程中积累了足够的经验,一个独立的 approved-enhancement 可在未来添加*最小化*的跟踪桥接:
- 将一个 GitHub 或 Linear 议题导入 GSD 工作区 / 阶段。
- 将一个 GitHub 或 Linear 议题导入 MSD 工作区 / 阶段。
- 将 `UAT.md` 证据作为评论导出到源议题。
- 从 `/gsd-capture --seed` 输出生成后续跟踪议题。
- 从 `/msd-capture --seed` 输出生成后续跟踪议题。
上述每一项都将是独立的增强提案,因为每项都增加了集成面和持续维护负担。它们超出了本指南的范围。
@@ -89,8 +89,8 @@ PR 合并后,循环关闭。PR 正文中的自动关闭关键词(`Closes #NN
- [阶段循环](explanation/the-phase-loop.md) — 说明 discuss → plan → execute → verify → ship 如何作为重复循环组合在一起。
- [工作区操作指南](how-to/work-in-parallel-with-workstreams.md) — 创建和管理并行工作树的逐步指南。
- [文档索引](README.md) — GSD Core 文档的完整目录。
- [文档索引](README.md) — MSD Core 文档的完整目录。
- [docs/USER-GUIDE.md](./USER-GUIDE.md) — 上述各命令以任务为导向的操作指南。
- [docs/COMMANDS.md](COMMANDS.md) — `/gsd-*` 命令的完整参考。
- [docs/COMMANDS.md](COMMANDS.md) — `/msd-*` 命令的完整参考。
- [docs/FEATURES.md](FEATURES.md) — 功能级能力矩阵(工作区、manager、autonomous、verify、review、ship)。
- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — 阶段产物生命周期与 `STATE.md` 机制。

View File

@@ -1,6 +1,6 @@
# CONTEXT.md 结构参考
每个阶段的 `CONTEXT.md` 是 GSD Core 用于保存 `/gsd-discuss-phase` 阶段所收集的实现决策的载体。它是研究代理和规划代理的主要上游输入。本页面记录其结构。参见[文档索引](../README.md)。
每个阶段的 `CONTEXT.md` 是 MSD Core 用于保存 `/msd-discuss-phase` 阶段所收集的实现决策的载体。它是研究代理和规划代理的主要上游输入。本页面记录其结构。参见[文档索引](../README.md)。
---
@@ -14,7 +14,7 @@
示例:`.planning/phases/03-post-feed/03-CONTEXT.md`。
该文件由 `gsd-core/workflows/discuss-phase.md` 中的 `write_context` 步骤生成(或通过 PRD/ADR 摄入快速路径生成)。在正常操作中,该文件不会被手动编辑——讨论阶段工作流负责写入,下游代理将其作为封闭的可信来源读取。
该文件由 `msd-core/workflows/discuss-phase.md` 中的 `write_context` 步骤生成(或通过 PRD/ADR 摄入快速路径生成)。在正常操作中,该文件不会被手动编辑——讨论阶段工作流负责写入,下游代理将其作为封闭的可信来源读取。
---
@@ -39,12 +39,12 @@
| 块名 | 用途 | 由谁填充 | 由谁消费 |
|---|---|---|---|
| `<domain>` | 声明阶段边界——本阶段交付内容及明确排除在范围之外的内容。在规划和执行过程中为范围护栏提供锚点。 | `discuss-phase`(来自 ROADMAP.md 阶段目标) | `gsd-planner`、`gsd-plan-checker`(范围合规性) |
| `<spec_lock>` | 仅在 `check_spec` 步骤发现 `*-SPEC.md` 时才存在。列出锁定的需求数量和范围边界;代理被指示直接读取 `SPEC.md` 以获取完整需求。 | `discuss-phase`(条件性) | `gsd-planner`(直接读取 SPEC.md,而非在此重读需求) |
| `<decisions>` | 从讨论中收集的实现决策,使用 `D-NN` 标识符标注。分类由实际讨论内容产生,而非固定分类体系。包含 `Claude's Discretion` 子节,用于用户委托代理自行决定的领域。 | `discuss-phase`(交互式讨论) | `gsd-planner`(锁定的决策必须实现)、`gsd-plan-checker`(维度 7 合规性) |
| `<canonical_refs>` | 与本阶段相关的所有规格文档、ADR、功能文档或设计文档的完整相对路径。必填——每份 CONTEXT.md 必须包含此节。代理在规划或实现之前必须读取列出的文件。 | `discuss-phase`(从 ROADMAP.md 引用 + 讨论中的用户引用 + 代码库侦查积累) | `gsd-phase-researcher`、`gsd-planner` |
| `<code_context>` | 在 `scout_codebase` 步骤中发现的可复用资产、已建立的模式和集成点。引导代理使用现有代码,而非重新实现。 | `discuss-phase`(代码库侦查) | `gsd-planner`、`gsd-phase-researcher` |
| `<specifics>` | 讨论期间逐字记录的具体"我希望它像 X 一样"的参考、产品对比或特定示例。 | `discuss-phase`(自由形式用户输入) | `gsd-planner` |
| `<domain>` | 声明阶段边界——本阶段交付内容及明确排除在范围之外的内容。在规划和执行过程中为范围护栏提供锚点。 | `discuss-phase`(来自 ROADMAP.md 阶段目标) | `msd-planner`、`msd-plan-checker`(范围合规性) |
| `<spec_lock>` | 仅在 `check_spec` 步骤发现 `*-SPEC.md` 时才存在。列出锁定的需求数量和范围边界;代理被指示直接读取 `SPEC.md` 以获取完整需求。 | `discuss-phase`(条件性) | `msd-planner`(直接读取 SPEC.md,而非在此重读需求) |
| `<decisions>` | 从讨论中收集的实现决策,使用 `D-NN` 标识符标注。分类由实际讨论内容产生,而非固定分类体系。包含 `Claude's Discretion` 子节,用于用户委托代理自行决定的领域。 | `discuss-phase`(交互式讨论) | `msd-planner`(锁定的决策必须实现)、`msd-plan-checker`(维度 7 合规性) |
| `<canonical_refs>` | 与本阶段相关的所有规格文档、ADR、功能文档或设计文档的完整相对路径。必填——每份 CONTEXT.md 必须包含此节。代理在规划或实现之前必须读取列出的文件。 | `discuss-phase`(从 ROADMAP.md 引用 + 讨论中的用户引用 + 代码库侦查积累) | `msd-phase-researcher`、`msd-planner` |
| `<code_context>` | 在 `scout_codebase` 步骤中发现的可复用资产、已建立的模式和集成点。引导代理使用现有代码,而非重新实现。 | `discuss-phase`(代码库侦查) | `msd-planner`、`msd-phase-researcher` |
| `<specifics>` | 讨论期间逐字记录的具体"我希望它像 X 一样"的参考、产品对比或特定示例。 | `discuss-phase`(自由形式用户输入) | `msd-planner` |
| `<deferred>` | 讨论中出现但属于其他阶段的想法,予以保留以免遗失。当待办事项经过审查但未纳入范围时,包含 `Reviewed Todos` 子节。 | `discuss-phase`(范围蔓延重定向) | 不被自动化代理消费;仅供人工参考 |
---
@@ -107,7 +107,7 @@ No external specs — requirements fully captured in decisions above
## SPEC.md 集成
当 `/gsd-spec-phase` 在讨论阶段之前运行时,`check_spec` 步骤会找到 `*-SPEC.md` 文件并激活 `<spec_lock>`:
当 `/msd-spec-phase` 在讨论阶段之前运行时,`check_spec` 步骤会找到 `*-SPEC.md` 文件并激活 `<spec_lock>`:
```markdown
<spec_lock>

View File

@@ -1,6 +1,6 @@
# PLAN.md 模式参考
每个计划的 `PLAN.md` 是 GSD Core 的可执行工作单元——一份结构化文档,精确告知执行器代理需要构建什么以及如何验证构建是否正确完成。本页记录其结构。参见[文档索引](../README.md)。
每个计划的 `PLAN.md` 是 MSD Core 的可执行工作单元——一份结构化文档,精确告知执行器代理需要构建什么以及如何验证构建是否正确完成。本页记录其结构。参见[文档索引](../README.md)。
---
@@ -14,7 +14,7 @@
例如:`.planning/phases/03-post-feed/03-02-PLAN.md`(第 3 阶段,第 2 计划)。
计划由 `gsd-planner` 代理生成(由 `/gsd-plan-phase` 触发),并由 `execute-phase` 消费。一个阶段通常包含一到四个计划;同一阶段内的计划被分配到执行波次,以便独立工作并行运行。
计划由 `msd-planner` 代理生成(由 `/msd-plan-phase` 触发),并由 `execute-phase` 消费。一个阶段通常包含一到四个计划;同一阶段内的计划被分配到执行波次,以便独立工作并行运行。
---
@@ -66,7 +66,7 @@ must_haves:
| `phase` | 是 | string | 阶段标识符,例如 `03-post-feed`。 |
| `plan` | 是 | string | 阶段内的计划编号,例如 `02`。 |
| `type` | 是 | `execute` 或 `tdd` | 标准计划使用 `execute`;测试驱动计划使用 `tdd`,测试在实现之前编写。 |
| `wave` | 是 | integer | 执行波次。波次 1 中的计划并行运行(无依赖关系)。波次 2 及以上的计划等待上一波次的所有计划完成后才开始。由 `gsd-planner` 在规划时预先计算。 |
| `wave` | 是 | integer | 执行波次。波次 1 中的计划并行运行(无依赖关系)。波次 2 及以上的计划等待上一波次的所有计划完成后才开始。由 `msd-planner` 在规划时预先计算。 |
| `depends_on` | 是 | array of plan IDs | 该计划必须等待的前置计划。空数组表示波次 1。示例:`["03-01"]` 表示该计划在第 3 阶段计划 01 完成后运行。 |
| `files_modified` | 是 | array of paths | 该计划创建或修改的所有文件。被计划检查器用于检测同波次文件冲突,也被 execute-phase 用于合并跟踪。 |
| `autonomous` | 是 | boolean | 当所有任务类型均为 `auto` 时为 `true`。当计划包含任何需要人工交互的 `checkpoint:*` 任务时为 `false`。 |
@@ -78,7 +78,7 @@ must_haves:
## `must_haves` 字段
`must_haves` 描述了阶段目标达成后必须可观测到的真实状态。该字段在规划阶段派生,并在执行后由 `gsd-verifier` 代理验证。
`must_haves` 描述了阶段目标达成后必须可观测到的真实状态。该字段在规划阶段派生,并在执行后由 `msd-verifier` 代理验证。
### 子字段
@@ -122,8 +122,8 @@ Output: PostFeed and PostCard components wired to /api/feed.
```xml
<execution_context>
@~/.claude/gsd-core/workflows/execute-plan.md
@~/.claude/gsd-core/templates/summary.md
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
```
@@ -194,7 +194,7 @@ Output: PostFeed and PostCard components wired to /api/feed.
## 计划质量维度
`gsd-plan-checker` 代理在执行开始前对每个 PLAN.md 进行 12 个维度的审查。任何未通过 BLOCKER 级别检查的计划将被退回给 `gsd-planner` 修订(最多 3 次迭代):
`msd-plan-checker` 代理在执行开始前对每个 PLAN.md 进行 12 个维度的审查。任何未通过 BLOCKER 级别检查的计划将被退回给 `msd-planner` 修订(最多 3 次迭代):
| 维度 | 检查内容 |
|---|---|

View File

@@ -1,6 +1,6 @@
# 规划产物参考
`.planning/` 目录是 GSD Core 项目的共享记忆。所有工作流都会读取和写入该目录,并留下可审计的决策记录。本页列出每个文件、其用途,以及哪些命令负责生成或消费它。参见[文档索引](../README.md)。
`.planning/` 目录是 MSD Core 项目的共享记忆。所有工作流都会读取和写入该目录,并留下可审计的决策记录。本页列出每个文件、其用途,以及哪些命令负责生成或消费它。参见[文档索引](../README.md)。
---
@@ -50,32 +50,32 @@
| | |
|---|---|
| **用途** | 规范的项目标识:项目内容、目标用户、核心价值、需求、约束和关键决策。随项目演进持续更新。 |
| **生成者** | `/gsd-new-project`(初始创建,包含 `/gsd-onboard` 交接);由 `/gsd-complete-milestone` 在决策验证后更新。 |
| **消费者** | 所有规划工作流;`gsd-phase-researcher`、`gsd-planner`(上下文);`discuss-phase`(历史决策);`gsd-plan-checker`(项目约束)。 |
| **生成者** | `/msd-new-project`(初始创建,包含 `/msd-onboard` 交接);由 `/msd-complete-milestone` 在决策验证后更新。 |
| **消费者** | 所有规划工作流;`msd-phase-researcher`、`msd-planner`(上下文);`discuss-phase`(历史决策);`msd-plan-checker`(项目约束)。 |
### `ROADMAP.md`
| | |
|---|---|
| **用途** | 里程碑与阶段列表,含目标、需求 ID、成功标准以及每个阶段的规范参考。是项目构建内容和顺序的唯一可信来源。 |
| **生成者** | `/gsd-new-project`(初始创建,包含 `/gsd-onboard` 交接);由 `/gsd-phase --insert` 和 `/gsd-complete-milestone` 更新。 |
| **消费者** | `/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase`;所有需要阶段信息的编排命令;`gsd-planner`、`gsd-plan-checker`、`gsd-phase-researcher`。 |
| **生成者** | `/msd-new-project`(初始创建,包含 `/msd-onboard` 交接);由 `/msd-phase --insert` 和 `/msd-complete-milestone` 更新。 |
| **消费者** | `/msd-discuss-phase`、`/msd-plan-phase`、`/msd-execute-phase`;所有需要阶段信息的编排命令;`msd-planner`、`msd-plan-checker`、`msd-phase-researcher`。 |
### `REQUIREMENTS.md`
| | |
|---|---|
| **用途** | 编号化、可勾选的项目验收标准。每条需求带有 ID(如 `AUTH-01`),映射到路线图阶段。随着阶段执行,逐步标记需求为已完成。 |
| **生成者** | `/gsd-new-project`(初始创建,包含 `/gsd-onboard` 交接);需求由 `execute-phase` 标记为已完成。 |
| **消费者** | `gsd-planner`(计划必须覆盖所有阶段需求 ID);`gsd-plan-checker` 维度 1(需求覆盖);`discuss-phase`(历史需求)。 |
| **生成者** | `/msd-new-project`(初始创建,包含 `/msd-onboard` 交接);需求由 `execute-phase` 标记为已完成。 |
| **消费者** | `msd-planner`(计划必须覆盖所有阶段需求 ID);`msd-plan-checker` 维度 1(需求覆盖);`discuss-phase`(历史需求)。 |
### `STATE.md`
| | |
|---|---|
| **用途** | 实时进度跟踪器——当前阶段与计划、进度指标、积累的决策、会话连续性说明。每次工作流运行时首先读取,每次重要操作后更新。 |
| **生成者** | `/gsd-new-project`(初始创建,包含 `/gsd-onboard` 交接);由所有阶段工作流、`/gsd-pause-work`、`/gsd-resume-work` 持续更新。 |
| **消费者** | 所有编排工作流;`/gsd-progress`;通过 `/gsd-quick` 执行的临时任务;`gsd-planner` 和 `gsd-phase-researcher`(项目决策)。 |
| **生成者** | `/msd-new-project`(初始创建,包含 `/msd-onboard` 交接);由所有阶段工作流、`/msd-pause-work`、`/msd-resume-work` 持续更新。 |
| **消费者** | 所有编排工作流;`/msd-progress`;通过 `/msd-quick` 执行的临时任务;`msd-planner` 和 `msd-phase-researcher`(项目决策)。 |
完整字段参考请参见 [STATE.md 模式](state-md.md)。
@@ -84,8 +84,8 @@
| | |
|---|---|
| **用途** | 工作流配置:模型配置文件、研究与计划检查器开关、Git 分支策略、Nyquist 验证、并行化设置,以及每个代理的模型覆盖。 |
| **生成者** | `/gsd-new-project`(初始创建);`/gsd-settings`(交互式编辑)。 |
| **消费者** | 每个工作流和子代理——在初始化时通过 `gsd-tools query config-get` 读取。 |
| **生成者** | `/msd-new-project`(初始创建);`/msd-settings`(交互式编辑)。 |
| **消费者** | 每个工作流和子代理——在初始化时通过 `msd-tools query config-get` 读取。 |
完整模式请参见 [CONFIGURATION](../CONFIGURATION.md)。
@@ -93,17 +93,17 @@
| | |
|---|---|
| **用途** | Brownfield onboarding 索引,记录产物状态、代码库映射是否完整,以及初次设置后的下一个推荐 GSD 命令。 |
| **生成者** | `/gsd-onboard`,在 `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md` 和 `STATE.md` 全部存在后生成。 |
| **消费者** | 审查初次设置的人;以后确认现有 onboarding 状态的 `/gsd-onboard` 运行。 |
| **用途** | Brownfield onboarding 索引,记录产物状态、代码库映射是否完整,以及初次设置后的下一个推荐 MSD 命令。 |
| **生成者** | `/msd-onboard`,在 `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md` 和 `STATE.md` 全部存在后生成。 |
| **消费者** | 审查初次设置的人;以后确认现有 onboarding 状态的 `/msd-onboard` 运行。 |
### `MILESTONES.md`(可选)
| | |
|---|---|
| **用途** | 已完成里程碑的历史记录。每个里程碑关闭时填充;提供已交付内容及时间的存档快照。 |
| **生成者** | `/gsd-complete-milestone`。 |
| **消费者** | `/gsd-audit-milestone`;人工审查。 |
| **生成者** | `/msd-complete-milestone`。 |
| **消费者** | `/msd-audit-milestone`;人工审查。 |
### `DECISIONS-INDEX.md`(可选)
@@ -118,8 +118,8 @@
| | |
|---|---|
| **用途** | 工作中断时写入的机器可读暂停状态。包含恢复点、进行中的上下文以及继续说明。恰好消费一次——在恢复时。 |
| **生成者** | `/gsd-pause-work`。 |
| **消费者** | `/gsd-resume-work`。 |
| **生成者** | `/msd-pause-work`。 |
| **消费者** | `/msd-resume-work`。 |
---
@@ -132,8 +132,8 @@
| | |
|---|---|
| **用途** | 规划开始前捕获的实现决策。包含阶段边界(`<domain>`)、带有 `D-NN` 标识符的锁定决策(`<decisions>`)、规范文档参考(`<canonical_refs>`)、现有代码洞察(`<code_context>`)、具体灵感(`<specifics>`)以及推迟的想法(`<deferred>`)。 |
| **生成者** | `/gsd-discuss-phase`(交互式讨论或 PRD/ADR 快速路径)。 |
| **消费者** | `gsd-phase-researcher`(待调查内容);`gsd-planner`(锁定决策);`gsd-plan-checker` 维度 7(上下文合规性)。 |
| **生成者** | `/msd-discuss-phase`(交互式讨论或 PRD/ADR 快速路径)。 |
| **消费者** | `msd-phase-researcher`(待调查内容);`msd-planner`(锁定决策);`msd-plan-checker` 维度 7(上下文合规性)。 |
完整字段参考请参见 [CONTEXT.md 模式](context-md.md)。
@@ -142,7 +142,7 @@
| | |
|---|---|
| **用途** | discuss-phase 会话的人类可读审计记录:讨论的领域、提出的选项、所做的选择、推迟的想法以及留给 Claude 自行决定的事项。不被自动化工作流消费。 |
| **生成者** | `/gsd-discuss-phase`(`git_commit` 步骤)。 |
| **生成者** | `/msd-discuss-phase`(`git_commit` 步骤)。 |
| **消费者** | 人工审查;回顾总结。 |
### `<NN>-RESEARCH.md`
@@ -150,32 +150,32 @@
| | |
|---|---|
| **用途** | 规划前产生的技术研究结果。回答"为了很好地规划此阶段,我需要了解什么?"——涵盖领域分析、模式、风险、架构职责映射以及验证架构部分(由 Nyquist 门控使用)。 |
| **生成者** | `/gsd-plan-phase` 通过 `gsd-phase-researcher` 代理。 |
| **消费者** | `gsd-planner`(规划输入);`gsd-plan-checker` 维度 7c(层级合规性)、维度 8(Nyquist)、维度 11(研究解决);`gsd-pattern-mapper`(文件列表来源)。 |
| **生成者** | `/msd-plan-phase` 通过 `msd-phase-researcher` 代理。 |
| **消费者** | `msd-planner`(规划输入);`msd-plan-checker` 维度 7c(层级合规性)、维度 8(Nyquist)、维度 11(研究解决);`msd-pattern-mapper`(文件列表来源)。 |
### `<NN>-VALIDATION.md`
| | |
|---|---|
| **用途** | 源自 RESEARCH.md 中 `## Validation Architecture` 部分的 Nyquist 启发式验证策略。指定计划必须遵守的自动化测试覆盖要求。 |
| **生成者** | `/gsd-plan-phase`(步骤 5.5,当 `workflow.nyquist_validation` 已启用且 RESEARCH.md 包含验证架构部分时)。 |
| **消费者** | `gsd-plan-checker` 维度 8(检查 8e 门控——Nyquist 检查进行前必须存在);`gsd-verifier`。 |
| **生成者** | `/msd-plan-phase`(步骤 5.5,当 `workflow.nyquist_validation` 已启用且 RESEARCH.md 包含验证架构部分时)。 |
| **消费者** | `msd-plan-checker` 维度 8(检查 8e 门控——Nyquist 检查进行前必须存在);`msd-verifier`。 |
### `<NN>-PATTERNS.md`
| | |
|---|---|
| **用途** | 由 `gsd-pattern-mapper` 生成的代码库类比映射。针对本阶段每个待创建或修改的文件,识别最近似的现有类比,对文件的角色和数据流进行分类,并提取具体代码摘录。引导规划者采用一致的模式。 |
| **生成者** | `/gsd-plan-phase` 通过 `gsd-pattern-mapper` 代理(可选;如果 `workflow.pattern_mapper: false` 则跳过)。 |
| **消费者** | `gsd-planner`(模式指导);`gsd-plan-checker` 维度 12(模式合规性)。 |
| **用途** | 由 `msd-pattern-mapper` 生成的代码库类比映射。针对本阶段每个待创建或修改的文件,识别最近似的现有类比,对文件的角色和数据流进行分类,并提取具体代码摘录。引导规划者采用一致的模式。 |
| **生成者** | `/msd-plan-phase` 通过 `msd-pattern-mapper` 代理(可选;如果 `workflow.pattern_mapper: false` 则跳过)。 |
| **消费者** | `msd-planner`(模式指导);`msd-plan-checker` 维度 12(模式合规性)。 |
### `<NN>-<PP>-PLAN.md`
| | |
|---|---|
| **用途** | 阶段内单个工作单元的可执行计划。包含 YAML 前置内容(wave、dependencies、files、requirements、`must_haves`)、目标、上下文参考、带有 `<read_first>`、`<action>`、`<verify>` 和 `<acceptance_criteria>` 字段的 XML 结构化任务,以及验证标准。 |
| **生成者** | `/gsd-plan-phase` 通过 `gsd-planner` 代理。每个计划一个文件——例如,`03-02-PLAN.md` 是第 3 阶段第 2 个计划。 |
| **消费者** | `/gsd-execute-phase`(执行器代理读取计划并运行任务);`gsd-plan-checker`(执行前质量审查);`gsd-verifier`(读取 `must_haves` 进行执行后验证)。 |
| **生成者** | `/msd-plan-phase` 通过 `msd-planner` 代理。每个计划一个文件——例如,`03-02-PLAN.md` 是第 3 阶段第 2 个计划。 |
| **消费者** | `/msd-execute-phase`(执行器代理读取计划并运行任务);`msd-plan-checker`(执行前质量审查);`msd-verifier`(读取 `must_haves` 进行执行后验证)。 |
完整字段参考请参见 [PLAN.md 模式](plan-md.md)。
@@ -185,30 +185,30 @@
|---|---|
| **用途** | 计划完成后写入的执行记录。记录已构建内容、与计划的偏差、对验收标准的自查,以及阶段的依赖关系图。 |
| **生成者** | `execute-phase` 执行器代理(在每个计划执行结束时写入)。 |
| **消费者** | `/gsd-progress`(阶段状态);`gsd-planner`(当后续计划对先前计划输出存在真实依赖时);`milestone-summary`。 |
| **消费者** | `/msd-progress`(阶段状态);`msd-planner`(当后续计划对先前计划输出存在真实依赖时);`milestone-summary`。 |
### `<NN>-VERIFICATION.md`
| | |
|---|---|
| **用途** | 阶段目标验证报告。在执行完成后,对照实际代码库检查所有计划中的 `must_haves.truths`、`must_haves.artifacts` 和 `must_haves.key_links`。记录 `status: passed | gaps_found | human_needed`。 |
| **生成者** | `/gsd-verify-work`(或 `/gsd-execute-phase` 内的验证步骤)。 |
| **消费者** | `plan-phase` 已关闭阶段门控(`status: passed` 的 VERIFICATION.md 将阶段标记为 `Complete`,并在没有 `--force` 的情况下阻止重新规划);`/gsd-progress`;人工审查。 |
| **生成者** | `/msd-verify-work`(或 `/msd-execute-phase` 内的验证步骤)。 |
| **消费者** | `plan-phase` 已关闭阶段门控(`status: passed` 的 VERIFICATION.md 将阶段标记为 `Complete`,并在没有 `--force` 的情况下阻止重新规划);`/msd-progress`;人工审查。 |
### `<NN>-UAT.md`
| | |
|---|---|
| **用途** | 持久化的 UAT 会话跟踪。在实时 UAT 会话中记录每个测试用例、预期的可观察行为、结果以及开发者响应。带有 YAML 前置内容(`status`、`phase`、`source`、时间戳)。 |
| **生成者** | `/gsd-audit-uat`(交互式 UAT 会话)。 |
| **消费者** | `/gsd-audit-uat`(恢复先前的 UAT 会话)。 |
| **生成者** | `/msd-audit-uat`(交互式 UAT 会话)。 |
| **消费者** | `/msd-audit-uat`(恢复先前的 UAT 会话)。 |
### `.continue-here.md`
| | |
|---|---|
| **用途** | 阶段工作暂停时写入的人类可读恢复说明。包含供恢复代理使用的上下文:关键反模式、阻塞问题、必读内容以及恢复的确切命令。 |
| **生成者** | `/gsd-pause-work`。 |
| **生成者** | `/msd-pause-work`。 |
| **消费者** | 任何在阶段上启动的工作流——`discuss-phase` 和 `plan-phase` 在入口处均检查此文件,并要求代理在继续之前证明其理解了所有 `blocking` 反模式。 |
---

View File

@@ -1,14 +1,14 @@
# STATE.md 架构参考
`STATE.md` 是 GSD Core 的动态项目记忆文件——一个记录项目当前状态、最近发生的事情以及下一步操作的单一 Markdown 文档。本页面记录其结构。参见[文档索引](../README.md)。
`STATE.md` 是 MSD Core 的动态项目记忆文件——一个记录项目当前状态、最近发生的事情以及下一步操作的单一 Markdown 文档。本页面记录其结构。参见[文档索引](../README.md)。
---
## 概述
由 GSD Core 管理的每个项目在 `.planning/STATE.md` 处保存一个 `STATE.md`。该文件在每次工作流开始时被读取,并在每次重要操作后被写入。该文件包含:
由 MSD Core 管理的每个项目在 `.planning/STATE.md` 处保存一个 `STATE.md`。该文件在每次工作流开始时被读取,并在每次重要操作后被写入。该文件包含:
- **YAML 前置数据** — 机器可读字段,由状态行钩子(`parseStateMd`)和 `gsd-tools state` 命令使用。
- **YAML 前置数据** — 机器可读字段,由状态行钩子(`parseStateMd`)和 `msd-tools state` 命令使用。
- **Markdown 正文** — 人类可读的章节,涵盖当前位置、累积的上下文、会话连续性以及性能指标。
该文件有意保持较小(目标:不超过 100 行)。它是项目状态的摘要,而非存档。
@@ -17,13 +17,13 @@
## YAML 前置数据
前置数据出现在文件最开头的 `---` 分隔符之间。除 `gsd_state_version` 和 `status` 外,所有字段均为可选;当相关数据尚不可用时,字段可以缺失。
前置数据出现在文件最开头的 `---` 分隔符之间。除 `msd_state_version` 和 `status` 外,所有字段均为可选;当相关数据尚不可用时,字段可以缺失。
### 注释示例
```yaml
---
gsd_state_version: '1.0'
msd_state_version: '1.0'
milestone: v2.0
milestone_name: Code Quality
status: executing
@@ -56,7 +56,7 @@ paused_at: null
| 字段 | 类型 | 填充时机 | 用途 |
|---|---|---|---|
| `gsd_state_version` | 字符串(`'1.0'`) | 始终 | 架构版本;在第一次 `state.*` 调用时由 `syncStateFrontmatter` 写入。 |
| `msd_state_version` | 字符串(`'1.0'`) | 始终 | 架构版本;在第一次 `state.*` 调用时由 `syncStateFrontmatter` 写入。 |
| `milestone` | 字符串(如 `v2.0`) | 配置了里程碑时 | 当前里程碑版本,从项目配置中读取。 |
| `milestone_name` | 字符串 | 配置了里程碑时 | 里程碑的人类可读标签(如 `Code Quality`)。 |
| `status` | 字符串 | 始终 | 当前生命周期阶段。由 `normalizeStateStatus()` 规范化——参见[状态值](#状态值)。 |
@@ -83,7 +83,7 @@ paused_at: null
| 字段 | 基数 |
|---|---|
| `gsd_state_version` | one |
| `msd_state_version` | one |
| `milestone` | optional |
| `milestone_name` | optional |
| `current_phase` | optional |
@@ -105,7 +105,7 @@ paused_at: null
### 状态值
`gsd-core/bin/lib/state-document.cjs` 中的 `normalizeStateStatus()` 将原始正文文本映射到以下规范值:
`msd-core/bin/lib/state-document.cjs` 中的 `normalizeStateStatus()` 将原始正文文本映射到以下规范值:
| 规范值 | 匹配文本(不区分大小写) |
|---|---|
@@ -121,10 +121,10 @@ paused_at: null
| 命令 | 运行期间的 `status` |
|---|---|
| `/gsd-discuss-phase` | `discussing` |
| `/gsd-plan-phase` | `planning` |
| `/gsd-execute-phase` | `executing` |
| `/gsd-verify-work` | `verifying` |
| `/msd-discuss-phase` | `discussing` |
| `/msd-plan-phase` | `planning` |
| `/msd-execute-phase` | `executing` |
| `/msd-verify-work` | `verifying` |
<!-- STATE-MD-SCHEMA:START:status-lifecycle — generated by scripts/gen-state-md-docs.cjs from src/state-md-schema.cts; do not edit by hand -->
### 状态生命周期 (ADR-2207)
@@ -145,7 +145,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
## 状态行渲染场景
`hooks/gsd-statusline.js` 中的 `formatGsdState()` 读取已解析的前置数据并输出**第一个匹配的场景**。如果没有新的生命周期字段适用,渲染将回退到与 v1.38.x 完全一致的原始格式。
`hooks/msd-statusline.js` 中的 `formatMsdState()` 读取已解析的前置数据并输出**第一个匹配的场景**。如果没有新的生命周期字段适用,渲染将回退到与 v1.38.x 完全一致的原始格式。
| 场景 | 触发条件 | 显示示例 |
|---|---|---|
@@ -154,7 +154,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
| **3. 里程碑完成** | `percent` 为 `100` 或 `completed_phases == total_phases` | `v2.0 [██████████] 100% · milestone complete` |
| **4. 默认回退** | 以上均不匹配 | `v1.9 Code Quality · executing · ph 1/5`(现有格式) |
**场景优先级:** 当 `active_phase` 和 `next_action` 均已填充时,场景 1 优先——编排器正在运行,显示"下一步推荐"会造成误导。此优先级由 `formatGsdState()` 中的检查顺序强制执行,并由 `tests/gsd-statusline.test.cjs` 中的 `"scene priority"` 测试套件覆盖。
**场景优先级:** 当 `active_phase` 和 `next_action` 均已填充时,场景 1 优先——编排器正在运行,显示"下一步推荐"会造成误导。此优先级由 `formatMsdState()` 中的检查顺序强制执行,并由 `tests/msd-statusline.test.cjs` 中的 `"scene priority"` 测试套件覆盖。
进度条(`[██░░░░░░░░] 20%`)仅在前置数据中存在 `progress.percent` 时才追加到里程碑段;缺失则不显示进度条。
@@ -162,7 +162,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
## 前置数据解析约束
状态行钩子使用基于正则表达式的解析(无完整 YAML 库),因此以下约束适用。这些约束在 `tests/gsd-statusline.test.cjs` 中经过测试。
状态行钩子使用基于正则表达式的解析(无完整 YAML 库),因此以下约束适用。这些约束在 `tests/msd-statusline.test.cjs` 中经过测试。
1. **前置数据必须从文件的第一个字符开始。** 任何内容——包括注释——出现在开头 `---` 之前都会使匹配失效。开头的 `---` 行必须恰好如此,不能有尾随空格。
@@ -176,7 +176,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
## Markdown 正文章节
正文(结束 `---` 之后的所有内容)遵循 `gsd-core/templates/state.md` 中的模板。标准章节为:
正文(结束 `---` 之后的所有内容)遵循 `msd-core/templates/state.md` 中的模板。标准章节为:
### 项目参考
@@ -200,7 +200,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
进度*历史*不属于这里。它会累积到下方的 [`### Performance Metrics`](#性能指标) 中,那才是设计用于增长的部分。
当现有值为已知模板默认值时,该章节中的 `Status:` 和 `Last activity:` 字段由 GSD 处理器更新(Knuth 不变式:执行器编写的值被保留)。已知处理器默认值的完整列表位于 `gsd-core/bin/lib/state-document.cjs` 中的 `KNOWN_TEMPLATE_DEFAULTS`。
当现有值为已知模板默认值时,该章节中的 `Status:` 和 `Last activity:` 字段由 MSD 处理器更新(Knuth 不变式:执行器编写的值被保留)。已知处理器默认值的完整列表位于 `msd-core/bin/lib/state-document.cjs` 中的 `KNOWN_TEMPLATE_DEFAULTS`。
### 性能指标
@@ -213,11 +213,11 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
### 累积的上下文
**决策** — 影响当前工作的近期决策摘要(完整日志在 `PROJECT.md` 中)。通过 `gsd-tools state add-decision` 添加。
**决策** — 影响当前工作的近期决策摘要(完整日志在 `PROJECT.md` 中)。通过 `msd-tools state add-decision` 添加。
**待处理的待办事项** — 数量及对 `.planning/todos/pending/` 的引用。通过 `/gsd-capture` 捕获。
**待处理的待办事项** — 数量及对 `.planning/todos/pending/` 的引用。通过 `/msd-capture` 捕获。
**阻碍/关切** — 影响未来工作的问题,以发起阶段为前缀。通过 `gsd-tools state add-blocker` 添加;通过 `gsd-tools state resolve-blocker` 解决。
**阻碍/关切** — 影响未来工作的问题,以发起阶段为前缀。通过 `msd-tools state add-blocker` 添加;通过 `msd-tools state resolve-blocker` 解决。
### 会话连续性
@@ -236,7 +236,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
- 添加任何生命周期字段是可选的——当字段缺失时,渲染器会优雅降级。
- 即使 `progress` 块存在,进度条也是可选的:只有 `progress.percent` 触发进度条;单独的 `total_phases` 和 `completed_phases` 不会触发。
`tests/gsd-statusline.test.cjs` 中的 `formatGsdState #2833 backward compatibility` 测试套件锁定了此保证;任何破坏旧版 `STATE.md` 渲染的变更都将导致该套件失败。
`tests/msd-statusline.test.cjs` 中的 `formatMsdState #2833 backward compatibility` 测试套件锁定了此保证;任何破坏旧版 `STATE.md` 渲染的变更都将导致该套件失败。
---

View File

@@ -319,7 +319,7 @@ npm run dev &
DEV_SERVER_PID=$!
# 等待就绪(最多 30s)
gsd_run run-with-timeout 30 -- bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; done'
msd_run run-with-timeout 30 -- bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; done'
```
**端口冲突:** 终止陈旧进程(`lsof -ti:3000 | xargs kill`)或使用备用端口(`--port 3001`)。

View File

@@ -44,7 +44,7 @@
**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh
`/gsd-execute-phase 2`
`/msd-execute-phase 2`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
@@ -52,7 +52,7 @@
**也可选:**
- 执行前审查计划
- `/gsd-discuss-phase --assumptions 2` — 检查假设
- `/msd-discuss-phase --assumptions 2` — 检查假设
---
```
@@ -69,7 +69,7 @@
**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh
<sub>阶段 2 的最后一个计划</sub>
`/gsd-execute-phase 2`
`/msd-execute-phase 2`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
@@ -91,15 +91,15 @@
**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程
`/gsd-plan-phase 2`
`/msd-plan-phase 2`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
---
**也可选:**
- `/gsd-discuss-phase 2` — 先收集上下文
- `/gsd-plan-phase --research-phase 2` — 调查未知项
- `/msd-discuss-phase 2` — 先收集上下文
- `/msd-plan-phase --research-phase 2` — 调查未知项
- 审查路线图
---
@@ -120,15 +120,15 @@
**阶段 3: 核心功能** — 用户仪表板、设置和数据导出
`/gsd-plan-phase 3`
`/msd-plan-phase 3`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
---
**也可选:**
- `/gsd-discuss-phase 3` — 先收集上下文
- `/gsd-plan-phase --research-phase 3` — 调查未知项
- `/msd-discuss-phase 3` — 先收集上下文
- `/msd-plan-phase --research-phase 3` — 调查未知项
- 回顾阶段 2 构建的内容
---
@@ -145,11 +145,11 @@
**阶段 3: 核心功能** — 用户仪表板、设置和数据导出
**直接规划:** `/gsd-plan-phase 3`
**直接规划:** `/msd-plan-phase 3`
**先讨论上下文:** `/gsd-discuss-phase 3`
**先讨论上下文:** `/msd-discuss-phase 3`
**研究未知项:** `/gsd-plan-phase --research-phase 3`
**研究未知项:** `/msd-plan-phase --research-phase 3`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
@@ -169,7 +169,7 @@
**开始 v1.1** — 提问 → 研究 → 需求 → 路线图
`/gsd-new-milestone`
`/msd-new-milestone`
<sub>`/clear` 优先 → 全新上下文窗口</sub>
@@ -214,7 +214,7 @@
## 继续
运行 `/clear`,然后粘贴:
/gsd-execute-phase 2
/msd-execute-phase 2
```
用户不知道 02-03 是关于什么的。
@@ -222,7 +222,7 @@
### 不要:缺少 /clear 说明
```
`/gsd-plan-phase 3`
`/msd-plan-phase 3`
先运行 /clear。
```
@@ -242,7 +242,7 @@
```
```
/gsd-plan-phase 3
/msd-plan-phase 3
```
```

View File

@@ -2,11 +2,11 @@
为紧急插入计算下一个小数阶段编号。
## 使用 gsd-tools.cjs query
## 使用 msd-tools.cjs query
```bash
# 获取阶段 6 之后的下一个小数阶段
gsd-tools.cjs query phase.next-decimal 6
msd-tools.cjs query phase.next-decimal 6
```
输出:
@@ -32,13 +32,13 @@ gsd-tools.cjs query phase.next-decimal 6
## 提取值
```bash
DECIMAL_PHASE=$(gsd-tools.cjs query phase.next-decimal "${AFTER_PHASE}" --pick next)
BASE_PHASE=$(gsd-tools.cjs query phase.next-decimal "${AFTER_PHASE}" --pick base_phase)
DECIMAL_PHASE=$(msd-tools.cjs query phase.next-decimal "${AFTER_PHASE}" --pick next)
BASE_PHASE=$(msd-tools.cjs query phase.next-decimal "${AFTER_PHASE}" --pick base_phase)
```
或使用 --raw 标志:
```bash
DECIMAL_PHASE=$(gsd-tools.cjs query phase.next-decimal "${AFTER_PHASE}" --raw)
DECIMAL_PHASE=$(msd-tools.cjs query phase.next-decimal "${AFTER_PHASE}" --raw)
# 返回: 06.1
```
@@ -56,7 +56,7 @@ DECIMAL_PHASE=$(gsd-tools.cjs query phase.next-decimal "${AFTER_PHASE}" --raw)
小数阶段目录使用完整的小数编号:
```bash
SLUG=$(gsd-tools.cjs query generate-slug "$DESCRIPTION" --raw)
SLUG=$(msd-tools.cjs query generate-slug "$DESCRIPTION" --raw)
PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
mkdir -p "$PHASE_DIR"
```

View File

@@ -1,5 +1,5 @@
<overview>
GSD 框架的 Git 集成。
MSD 框架的 Git 集成。
</overview>
<core_principle>
@@ -29,7 +29,7 @@ git 日志应该读起来像是发布内容的变更日志,而不是规划活
[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
```
如果 NO_GIT:静默运行 `git init`。GSD 项目总是有自己的仓库。
如果 NO_GIT:静默运行 `git init`。MSD 项目总是有自己的仓库。
</git_check>
<commit_formats>
@@ -51,7 +51,7 @@ Phases:
提交内容:
```bash
gsd-tools.cjs query commit "docs: initialize [project-name] ([N] phases)" --files .planning/
msd-tools.cjs query commit "docs: initialize [project-name] ([N] phases)" --files .planning/
```
</format>
@@ -129,7 +129,7 @@ SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
提交内容:
```bash
gsd-tools.cjs query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
msd-tools.cjs query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
```
**注意:** 代码文件不包含 - 已按任务提交。
@@ -149,7 +149,7 @@ Current: [task name]
提交内容:
```bash
gsd-tools.cjs query commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
msd-tools.cjs query commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
```
</format>

View File

@@ -1,6 +1,6 @@
# Git 规划提交
通过 `gsd-tools.cjs query commit` 提交规划工件,它会自动检查 `commit_docs` 配置和 gitignore 状态(与旧版 `gsd-tools.cjs commit` 行为相同)。
通过 `msd-tools.cjs query commit` 提交规划工件,它会自动检查 `commit_docs` 配置和 gitignore 状态(与旧版 `msd-tools.cjs commit` 行为相同)。
## 通过 CLI 提交
@@ -9,7 +9,7 @@
对 `.planning/` 文件始终使用此方式 —— 它会自动处理 `commit_docs` 与 gitignore 检查:
```bash
gsd-tools.cjs query commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
msd-tools.cjs query commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
```
如果 `commit_docs` 为 `false` 或 `.planning/` 被 gitignore,CLI 会返回 `skipped`(带原因)。无需手动条件检查。
@@ -19,7 +19,7 @@ gsd-tools.cjs query commit "docs({scope}): {description}" --files .planning/STAT
将 `.planning/` 文件变更合并到上次提交:
```bash
gsd-tools.cjs query commit "" --files .planning/codebase/*.md --amend
msd-tools.cjs query commit "" --files .planning/codebase/*.md --amend
```
## 提交消息模式

View File

@@ -12,14 +12,14 @@ MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"
## 查找表
@~/.claude/gsd-core/references/model-profiles.md
@~/.claude/msd-core/references/model-profiles.md
在表中查找已解析配置对应的代理。将 model 参数传递给 Task 调用:
```
Task(
prompt="...",
subagent_type="gsd-planner",
subagent_type="msd-planner",
model="{resolved_model}" # "inherit"、"sonnet" 或 "haiku"
)
```

View File

@@ -1,23 +1,23 @@
# 模型配置
模型配置控制每个 GSD 代理使用哪个 Claude 模型。这允许平衡质量和 token 消耗。
模型配置控制每个 MSD 代理使用哪个 Claude 模型。这允许平衡质量和 token 消耗。
## 配置定义
| 代理 | `quality` | `balanced` | `budget` |
|-------|-----------|------------|----------|
| gsd-planner | opus | opus | sonnet |
| gsd-roadmapper | opus | sonnet | sonnet |
| gsd-executor | opus | sonnet | sonnet |
| gsd-phase-researcher | opus | sonnet | haiku |
| gsd-project-researcher | opus | sonnet | haiku |
| gsd-research-synthesizer | sonnet | sonnet | haiku |
| gsd-debugger | opus | sonnet | sonnet |
| gsd-codebase-mapper | sonnet | haiku | haiku |
| gsd-verifier | sonnet | sonnet | haiku |
| gsd-plan-checker | sonnet | sonnet | haiku |
| gsd-integration-checker | sonnet | sonnet | haiku |
| gsd-nyquist-auditor | sonnet | sonnet | haiku |
| msd-planner | opus | opus | sonnet |
| msd-roadmapper | opus | sonnet | sonnet |
| msd-executor | opus | sonnet | sonnet |
| msd-phase-researcher | opus | sonnet | haiku |
| msd-project-researcher | opus | sonnet | haiku |
| msd-research-synthesizer | sonnet | sonnet | haiku |
| msd-debugger | opus | sonnet | sonnet |
| msd-codebase-mapper | sonnet | haiku | haiku |
| msd-verifier | sonnet | sonnet | haiku |
| msd-plan-checker | sonnet | sonnet | haiku |
| msd-integration-checker | sonnet | sonnet | haiku |
| msd-nyquist-auditor | sonnet | sonnet | haiku |
## 配置理念
@@ -56,8 +56,8 @@
{
"model_profile": "balanced",
"model_overrides": {
"gsd-executor": "opus",
"gsd-planner": "haiku"
"msd-executor": "opus",
"msd-planner": "haiku"
}
}
```
@@ -77,17 +77,17 @@
## 设计理由
**为什么 gsd-planner 使用 Opus?**
**为什么 msd-planner 使用 Opus?**
规划涉及架构决策、目标分解和任务设计。这是模型质量影响最大的地方。
**为什么 gsd-executor 使用 Sonnet?**
**为什么 msd-executor 使用 Sonnet?**
执行者遵循明确的 PLAN.md 指令。计划已包含推理;执行只是实现。
**为什么 balanced 中验证器使用 Sonnet(而非 Haiku)?**
验证需要目标回溯推理 —— 检查代码是否**交付**了阶段承诺的内容,而不仅仅是模式匹配。Sonnet 处理得很好;Haiku 可能会遗漏细微的差距。
**为什么 gsd-codebase-mapper 使用 Haiku?**
**为什么 msd-codebase-mapper 使用 Haiku?**
只读探索和模式提取。不需要推理,只需从文件内容输出结构化结果。
**为什么用 `inherit` 而不是直接传递 `opus`?**
Claude Code 的 `"opus"` 别名映射到特定模型版本。组织可能阻止旧版 opus 而允许新版。GSD 为 opus 级代理返回 `"inherit"`,使其使用用户在会话中配置的任何 opus 版本。这避免了版本冲突和静默回退到 Sonnet。
Claude Code 的 `"opus"` 别名映射到特定模型版本。组织可能阻止旧版 opus 而允许新版。MSD 为 opus 级代理返回 `"inherit"`,使其使用用户在会话中配置的任何 opus 版本。这避免了版本冲突和静默回退到 Sonnet。

View File

@@ -9,12 +9,12 @@
- 提取标志(以 `--` 为前缀)
- 剩余文本为描述(用于 insert/add 命令)
## 使用 gsd-tools
## 使用 msd-tools
`find-phase` 命令一步完成规范化和验证:
```bash
PHASE_INFO=$(node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" find-phase "${PHASE}")
PHASE_INFO=$(node "$HOME/.claude/msd-core/bin/msd-tools.cjs" find-phase "${PHASE}")
```
返回 JSON 包含:
@@ -45,7 +45,7 @@ fi
使用 `roadmap get-phase` 验证阶段存在:
```bash
PHASE_CHECK=$(node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}")
PHASE_CHECK=$(node "$HOME/.claude/msd-core/bin/msd-tools.cjs" roadmap get-phase "${PHASE}")
if [ "$(printf '%s\n' "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then
echo "ERROR: Phase ${PHASE} not found in roadmap"
exit 1
@@ -57,5 +57,5 @@ fi
使用 `find-phase` 进行目录查找:
```bash
PHASE_DIR=$(node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" find-phase "${PHASE}" --raw)
PHASE_DIR=$(node "$HOME/.claude/msd-core/bin/msd-tools.cjs" find-phase "${PHASE}" --raw)
```

View File

@@ -10,8 +10,8 @@
},
"git": {
"branching_strategy": "none",
"phase_branch_template": "gsd/phase-{phase}-{slug}",
"milestone_branch_template": "gsd/{milestone}-{slug}"
"phase_branch_template": "msd/phase-{phase}-{slug}",
"milestone_branch_template": "msd/{milestone}-{slug}"
}
```
@@ -20,13 +20,13 @@
| `commit_docs` | `true` | 是否将规划工件提交到 git |
| `search_gitignored` | `false` | 在广泛 rg 搜索中添加 `--no-ignore` |
| `git.branching_strategy` | `"none"` | Git 分支策略:`"none"`、`"phase"` 或 `"milestone"` |
| `git.phase_branch_template` | `"gsd/phase-{phase}-{slug}"` | 阶段策略的分支模板 |
| `git.milestone_branch_template` | `"gsd/{milestone}-{slug}"` | 里程碑策略的分支模板 |
| `git.phase_branch_template` | `"msd/phase-{phase}-{slug}"` | 阶段策略的分支模板 |
| `git.milestone_branch_template` | `"msd/{milestone}-{slug}"` | 里程碑策略的分支模板 |
</config_schema>
<planner_stall_detection>
`planner.stall_detection_enabled` 默认为 `true`,控制标准规划器、分块规划器、计划检查器和修订规划器的有界停滞检测。运行 `gsd config-set planner.stall_detection_enabled false` 可跳过 watchdog 轮询,并通过运行时原生完成机制等待每个 agent。**警告:** `false` 会放弃运行时丢失完成回传时的有界恢复;可能需要中断并使用现有文件系统回退。
`planner.stall_detection_enabled` 默认为 `true`,控制标准规划器、分块规划器、计划检查器和修订规划器的有界停滞检测。运行 `msd config-set planner.stall_detection_enabled false` 可跳过 watchdog 轮询,并通过运行时原生完成机制等待每个 agent。**警告:** `false` 会放弃运行时丢失完成回传时的有界恢复;可能需要中断并使用现有文件系统回退。
</planner_stall_detection>
@@ -42,19 +42,19 @@
- 用户必须将 `.planning/` 添加到 `.gitignore`
- 适用于:OSS 贡献、客户项目、保持规划私有
**使用 `gsd-tools.cjs query`(推荐):**
**使用 `msd-tools.cjs query`(推荐):**
```bash
# 提交时自动检查 commit_docs + gitignore:
gsd-tools.cjs query commit "docs: update state" --files .planning/STATE.md
msd-tools.cjs query commit "docs: update state" --files .planning/STATE.md
# 通过 state load 加载配置(返回 JSON):
INIT=$(gsd-tools.cjs query state.load)
INIT=$(msd-tools.cjs query state.load)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
# commit_docs 在 JSON 输出中可用
# 或使用包含 commit_docs 的 init 命令:
INIT=$(gsd-tools.cjs query init.execute-phase "1")
INIT=$(msd-tools.cjs query init.execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
# commit_docs 包含在所有 init 命令输出中
```
@@ -64,7 +64,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
**通过 CLI 提交(自动处理检查):**
```bash
gsd-tools.cjs query commit "docs: update state" --files .planning/STATE.md
msd-tools.cjs query commit "docs: update state" --files .planning/STATE.md
```
CLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动条件判断。
@@ -82,7 +82,7 @@ CLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动
- 在应该包含 `.planning/` 的广泛 rg 搜索中添加 `--no-ignore`
- 仅在搜索整个仓库并期望 `.planning/` 匹配时需要
**注意:** 大多数 GSD 操作使用直接文件读取或显式路径,无论 gitignore 状态如何都有效。
**注意:** 大多数 MSD 操作使用直接文件读取或显式路径,无论 gitignore 状态如何都有效。
</search_behavior>
@@ -125,18 +125,18 @@ CLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动
**当 `git.branching_strategy: "none"`(默认):**
- 所有工作提交到当前分支
- 标准 GSD 行为
- 标准 MSD 行为
**当 `git.branching_strategy: "phase"`:**
- `execute-phase` 在执行前创建/切换到分支
- 分支名来自 `phase_branch_template`(如 `gsd/phase-03-authentication`)
- 分支名来自 `phase_branch_template`(如 `msd/phase-03-authentication`)
- 所有计划提交到该分支
- 阶段完成后用户手动合并分支
- `complete-milestone` 提供合并所有阶段分支的选项
**当 `git.branching_strategy: "milestone"`:**
- 里程碑的第一个 `execute-phase` 创建里程碑分支
- 分支名来自 `milestone_branch_template`(如 `gsd/v1.0-mvp`)
- 分支名来自 `milestone_branch_template`(如 `msd/v1.0-mvp`)
- 里程碑中所有阶段提交到同一分支
- `complete-milestone` 提供将里程碑分支合并到 main 的选项
@@ -152,14 +152,14 @@ CLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动
使用 `init execute-phase` 返回所有配置为 JSON:
```bash
INIT=$(gsd-tools.cjs query init.execute-phase "1")
INIT=$(msd-tools.cjs query init.execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
# JSON 输出包含:branching_strategy, phase_branch_template, milestone_branch_template
```
或使用 `state load` 获取配置值:
```bash
INIT=$(gsd-tools.cjs query state.load)
INIT=$(msd-tools.cjs query state.load)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
# 从 JSON 解析 branching_strategy, phase_branch_template, milestone_branch_template
```

View File

@@ -1,6 +1,6 @@
# UI 品牌规范
面向用户的 GSD 输出的视觉模式。编排器通过 @ 引用此文件。
面向用户的 MSD 输出的视觉模式。编排器通过 @ 引用此文件。
## 分隔符与横幅
@@ -38,7 +38,7 @@ Markdown。该方案被否决 —— 它需要在每个运行时描述符及解
用于主要工作流过渡。
```
### GSD ► {阶段名称}
### MSD ► {阶段名称}
```
**阶段名称(大写):**
@@ -142,7 +142,7 @@ Markdown。该方案被否决 —— 它需要在每个运行时描述符及解
---
**也可选:**
- (根据工作流选填可选命令,例如 `/gsd-progress --next`)
- (根据工作流选填可选命令,例如 `/msd-progress --next`)
---
```
@@ -183,7 +183,7 @@ Markdown。该方案被否决 —— 它需要在每个运行时描述符及解
那行吞掉
- 把标题夹在两条横线之间 —— 标题本身就是分隔
- 混合横幅样式(`===`、`***`)
- 横幅中缺少 `GSD ►` 前缀
- 横幅中缺少 `MSD ►` 前缀
- 随机 emoji(`🚀`、`✨`、`💫`)
- 完成后缺少下一步区块

View File

@@ -600,7 +600,7 @@ check_substantive() {
关于自动化优先的检查点模式、服务器生命周期管理、CLI 安装处理和错误恢复协议,请参阅:
**@~/.claude/gsd-core/references/checkpoints.md** → `<automation_reference>` 部分
**@~/.claude/msd-core/references/checkpoints.md** → `<automation_reference>` 部分
关键原则:
- Claude 在呈现检查点**之前**设置验证环境

View File

@@ -1,12 +1,12 @@
# 将现有代码库纳入工作流
在本教程中,您将把 GSD Core 引入一个已有代码的仓库。您将对代码库进行映射,创建一个描述您所*新增*内容的项目,并针对一个小型聚焦变更运行首次讨论与规划循环。完成后,GSD Core 的规划流水线将了解您的技术栈、规范和关注点——并在每次规划时运用这些知识。
在本教程中,您将把 MSD Core 引入一个已有代码的仓库。您将对代码库进行映射,创建一个描述您所*新增*内容的项目,并针对一个小型聚焦变更运行首次讨论与规划循环。完成后,MSD Core 的规划流水线将了解您的技术栈、规范和关注点——并在每次规划时运用这些知识。
---
## 您将构建的内容
我们将向一个现有的 Express 应用程序添加一个 `GET /health` 端点。该变更足够小,不会分散您对真正核心内容的注意力:GSD Core 在规划任何内容之前如何学习您的代码库。
我们将向一个现有的 Express 应用程序添加一个 `GET /health` 端点。该变更足够小,不会分散您对真正核心内容的注意力:MSD Core 在规划任何内容之前如何学习您的代码库。
---
@@ -18,12 +18,12 @@
---
## 第 1 步 — 安装 GSD Core
## 第 1 步 — 安装 MSD Core
在您的仓库根目录执行:
```bash
npx @opengsd/gsd-core@latest
npx @golem15/msd-core@latest
```
在提示时选择 **Claude Code** 和 **local**。您将看到:
@@ -31,7 +31,7 @@ npx @opengsd/gsd-core@latest
```text
✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start
✓ MSD Core ready — run /msd-new-project to start
```
---
@@ -44,7 +44,7 @@ claude --dangerously-skip-permissions
> [!CAUTION]
> **The permissions flag is optional.** It skips per-file confirmation while
> GSD's sub-agents read and write files. Use it only in low-stakes or
> MSD's sub-agents read and write files. Use it only in low-stakes or
> throwaway contexts. To keep confirmations enabled, start with `claude` instead.
> For real work, read the [security model](../explanation/security-model.md) first.
@@ -53,13 +53,13 @@ claude --dangerously-skip-permissions
## 第 3 步 — 开始 brownfield onboarding
在创建项目之前,让 GSD Core 检查仓库状态并告诉您安全的下一个顶层命令。这一步可避免跳过代码库上下文或覆盖现有 planning 文件。
在创建项目之前,让 MSD Core 检查仓库状态并告诉您安全的下一个顶层命令。这一步可避免跳过代码库上下文或覆盖现有 planning 文件。
```text
/gsd-onboard
/msd-onboard
```
如果 onboarding 报告缺少代码库映射,请选择推荐选项并运行打印出的 `/gsd-map-codebase` 交接命令,然后重新运行 `/gsd-onboard`。`/gsd-onboard --fast` 只适合轻量首次通过;在 `/gsd-new-project` 前仍需要完整映射。`/gsd-map-codebase` 会派生四个并行映射子代理(您将看到"Spawning 4 parallel codebase mapper agents…"——这需要 1–5 分钟;请勿中断)。每个代理专注于不同的关注点:
如果 onboarding 报告缺少代码库映射,请选择推荐选项并运行打印出的 `/msd-map-codebase` 交接命令,然后重新运行 `/msd-onboard`。`/msd-onboard --fast` 只适合轻量首次通过;在 `/msd-new-project` 前仍需要完整映射。`/msd-map-codebase` 会派生四个并行映射子代理(您将看到"Spawning 4 parallel codebase mapper agents…"——这需要 1–5 分钟;请勿中断)。每个代理专注于不同的关注点:
| 代理 | 关注点 |
|-------|-------|
@@ -83,9 +83,9 @@ Created .planning/codebase/:
- CONCERNS.md (33 lines) - Technical debt and issues
```
打开 `.planning/codebase/STACK.md`。您将看到 GSD Core 检测到的语言、运行时、框架版本和关键依赖项——这些内容基于实际读取的文件,而非猜测。
打开 `.planning/codebase/STACK.md`。您将看到 MSD Core 检测到的语言、运行时、框架版本和关键依赖项——这些内容基于实际读取的文件,而非猜测。
打开 `.planning/codebase/CONVENTIONS.md`。您将看到它从您的源代码中观察到的命名规范、错误处理模式和代码风格规则。GSD Core 为该仓库生成的每个计划都将自动遵循这些规范。
打开 `.planning/codebase/CONVENTIONS.md`。您将看到它从您的源代码中观察到的命名规范、错误处理模式和代码风格规则。MSD Core 为该仓库生成的每个计划都将自动遵循这些规范。
打开 `.planning/codebase/CONCERNS.md`。在进行任何新功能开发之前,这是最值得阅读的文件——它会展现可能影响您计划的技术债务和脆弱区域。
@@ -99,15 +99,15 @@ Created .planning/codebase/:
/clear
```
现在再次运行 `/gsd-onboard`。如果 GSD Core 检测到 ADR、PRD、spec、RFC 或根级需求文档,请先接受推荐的 `/gsd-ingest-docs` 交接,然后再运行 `/gsd-onboard`。上下文准备好后,onboarding 会打印项目初始化交接命令:
现在再次运行 `/msd-onboard`。如果 MSD Core 检测到 ADR、PRD、spec、RFC 或根级需求文档,请先接受推荐的 `/msd-ingest-docs` 交接,然后再运行 `/msd-onboard`。上下文准备好后,onboarding 会打印项目初始化交接命令:
```text
/gsd-new-project
/msd-new-project
```
由于 GSD Core 在上一步中发现了现有代码,`/gsd-new-project` 知道这是一个棕地项目。问题将聚焦于您所*新增*的内容,而非重新描述已有的内容:
由于 MSD Core 在上一步中发现了现有代码,`/msd-new-project` 知道这是一个棕地项目。问题将聚焦于您所*新增*的内容,而非重新描述已有的内容:
GSD Core 会询问您想构建什么。请用您正在添加的功能来回答,而不是描述整个代码库:
MSD Core 会询问您想构建什么。请用您正在添加的功能来回答,而不是描述整个代码库:
```text
Add a GET /health endpoint to the Express app. It should return
@@ -115,7 +115,7 @@ Add a GET /health endpoint to the Express app. It should return
health checks.
```
GSD Core 会进一步提出少量澄清问题,然后继续创建需求和路线图。由于它已读取 `ARCHITECTURE.md` 和 `STACK.md`,它会自动将现有能力映射到 `PROJECT.md` 的 **Validated** 部分——您无需描述现有的 API 接口。
MSD Core 会进一步提出少量澄清问题,然后继续创建需求和路线图。由于它已读取 `ARCHITECTURE.md` 和 `STACK.md`,它会自动将现有能力映射到 `PROJECT.md` 的 **Validated** 部分——您无需描述现有的 API 接口。
对所有工作流设置选择推荐默认值。
@@ -133,7 +133,7 @@ Proposed Roadmap
批准路线图。
项目设置完成后,再运行一次 `/gsd-onboard`。现在 `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md` 和 `STATE.md` 都已存在,onboarding 会创建或确认 `.planning/onboarding/SUMMARY.md`。
项目设置完成后,再运行一次 `/msd-onboard`。现在 `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md` 和 `STATE.md` 都已存在,onboarding 会创建或确认 `.planning/onboarding/SUMMARY.md`。
**在 `.planning/` 中创建的内容:**
@@ -148,7 +148,7 @@ Proposed Roadmap
codebase/ ← 第 3 步生成的七个映射文件
```
注意 `.planning/codebase/` 已经从第 3 步存在。GSD Core 在编写 `PROJECT.md` 时读取了这些文件,这就是为什么它无需您描述即可填充已验证的需求。
注意 `.planning/codebase/` 已经从第 3 步存在。MSD Core 在编写 `PROJECT.md` 时读取了这些文件,这就是为什么它无需您描述即可填充已验证的需求。
---
@@ -159,10 +159,10 @@ Proposed Roadmap
```
```text
/gsd-discuss-phase 1
/msd-discuss-phase 1
```
由于 GSD Core 已读取您的 `CONVENTIONS.md` 和 `ARCHITECTURE.md`,其问题基于您的实际代码库——而非通用建议。您可能会看到:
由于 MSD Core 已读取您的 `CONVENTIONS.md` 和 `ARCHITECTURE.md`,其问题基于您的实际代码库——而非通用建议。您可能会看到:
```text
> Your routes are registered in src/routes/index.js. Should the health
@@ -177,7 +177,7 @@ Proposed Roadmap
process.uptime() is fine.
```
讨论结束后,GSD Core 将写入:
讨论结束后,MSD Core 将写入:
```text
.planning/phases/01-health-endpoint/CONTEXT.md
@@ -190,7 +190,7 @@ Proposed Roadmap
## 第 6 步 — 规划第 1 阶段
```text
/gsd-plan-phase 1
/msd-plan-phase 1
```
四个研究子代理并行运行(1–5 分钟)。当它们返回后,规划器读取 `CONTEXT.md`、研究结果和您的代码库映射,创建符合您规范的任务计划。
@@ -204,7 +204,7 @@ Proposed Roadmap
01-02-PLAN.md ← Task: register health route in src/routes/index.js
```
打开 `01-01-PLAN.md`。注意 `<files>` 标签引用了 `src/routes/health.js`——正是您在讨论中指定的路径,与 GSD Core 在代码库映射中观察到的路由模式一致。这正是代码库映射发挥作用的体现。
打开 `01-01-PLAN.md`。注意 `<files>` 标签引用了 `src/routes/health.js`——正是您在讨论中指定的路径,与 MSD Core 在代码库映射中观察到的路由模式一致。这正是代码库映射发挥作用的体现。
---
@@ -213,21 +213,21 @@ Proposed Roadmap
您现在拥有一个带有代码库映射、讨论决策记录和经过验证的任务计划的项目——所有内容均基于您的实际代码。从这里开始,工作流与绿地项目完全相同:
```text
/gsd-execute-phase 1
/gsd-verify-work 1
/gsd-ship 1
/msd-execute-phase 1
/msd-verify-work 1
/msd-ship 1
```
对于每个未来的功能,当结构发生重大变化时,再次运行 `/gsd-map-codebase`,以保持代码库映射的时效性。
对于每个未来的功能,当结构发生重大变化时,再次运行 `/msd-map-codebase`,以保持代码库映射的时效性。
---
## 您学到了什么
- `/gsd-onboard` 如何安全编排 brownfield 设置,不嵌套交互式命令,也不覆盖现有 planning 文件。
- `/gsd-map-codebase` 如何运行四个并行代理,在 `.planning/codebase/` 中生成 `STACK.md`、`ARCHITECTURE.md`、`CONVENTIONS.md`、`CONCERNS.md`、`STRUCTURE.md`、`TESTING.md` 和 `INTEGRATIONS.md`。
- 在棕地仓库中运行 `/gsd-new-project` 如何将问题聚焦于您所*新增*的内容,并从现有代码中填充已验证的需求。
- 代码库映射如何塑造 `/gsd-discuss-phase` 中的每个问题——文件路径、模式和规范均来自您的实际代码。
- `/msd-onboard` 如何安全编排 brownfield 设置,不嵌套交互式命令,也不覆盖现有 planning 文件。
- `/msd-map-codebase` 如何运行四个并行代理,在 `.planning/codebase/` 中生成 `STACK.md`、`ARCHITECTURE.md`、`CONVENTIONS.md`、`CONCERNS.md`、`STRUCTURE.md`、`TESTING.md` 和 `INTEGRATIONS.md`。
- 在棕地仓库中运行 `/msd-new-project` 如何将问题聚焦于您所*新增*的内容,并从现有代码中填充已验证的需求。
- 代码库映射如何塑造 `/msd-discuss-phase` 中的每个问题——文件路径、模式和规范均来自您的实际代码。
- 规划器如何读取 `CONTEXT.md` 和 `CONVENTIONS.md` 来生成符合您仓库风格的计划。
---
@@ -235,5 +235,5 @@ Proposed Roadmap
## 相关内容
- [您的第一个项目](your-first-project.md) — 从安装到 PR 的完整绿地循环
- [通过命令使用映射代码库](../COMMANDS.md) — 所有 `/gsd-map-codebase` 标志和子命令
- [通过命令使用映射代码库](../COMMANDS.md) — 所有 `/msd-map-codebase` 标志和子命令
- [文档索引](../README.md)

View File

@@ -1,6 +1,6 @@
# 你的第一个项目
在本教程中,你将安装 GSD Core 并从头构建一个小型命令行待办事项应用——一个阶段、一个 PR、完整的流程循环。完成后,你将至少运行过核心阶段循环中的每一条命令一次,并看到每条命令所生成的规划产物。
在本教程中,你将安装 MSD Core 并从头构建一个小型命令行待办事项应用——一个阶段、一个 PR、完整的流程循环。完成后,你将至少运行过核心阶段循环中的每一条命令一次,并看到每条命令所生成的规划产物。
---
@@ -16,16 +16,16 @@
- **Claude Code** — 在你想使用的项目目录中打开。
- 初次安装需要网络连接。
不需要其他工具。GSD Core 本身将在下一步安装。
不需要其他工具。MSD Core 本身将在下一步安装。
---
## 第 1 步 — 安装 GSD Core
## 第 1 步 — 安装 MSD Core
在项目目录中打开终端并运行:
```bash
npx @opengsd/gsd-core@latest
npx @golem15/msd-core@latest
```
安装程序会询问你使用的 AI 编程运行时,以及是全局安装还是安装到当前项目。现在选择 **Claude Code** 和**本地安装**(仅此项目)。
@@ -35,10 +35,10 @@ npx @opengsd/gsd-core@latest
```text
✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start
✓ MSD Core ready — run /msd-new-project to start
```
注意项目中现在存在一个 `.claude/` 目录。这是 GSD Core 的命令和代理所在的位置。
注意项目中现在存在一个 `.claude/` 目录。这是 MSD Core 的命令和代理所在的位置。
> 为什么选本地而不是全局?本地安装可将技能版本固定到该项目。如需全局安装,请参阅 [在你的运行时上安装](../how-to/install-on-your-runtime.md)。
@@ -46,7 +46,7 @@ npx @opengsd/gsd-core@latest
## 第 2 步 — 以权限模式启动 Claude Code
GSD Core 会生成读写文件的子代理。以权限标志启动 Claude Code,这样它就不会在每次文件操作时暂停询问:
MSD Core 会生成读写文件的子代理。以权限标志启动 Claude Code,这样它就不会在每次文件操作时暂停询问:
```bash
claude --dangerously-skip-permissions
@@ -61,10 +61,10 @@ claude --dangerously-skip-permissions
在 Claude Code 提示符处输入以下斜杠命令:
```text
/gsd-new-project
/msd-new-project
```
GSD Core 将开启一段对话。它首先提问:
MSD Core 将开启一段对话。它首先提问:
```text
What do you want to build?
@@ -78,13 +78,13 @@ A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`,
No external dependencies — Node built-ins only.
```
GSD Core 会继续提出几个澄清性问题。自然地回答即可。它在撰写任何计划之前,正在了解你的关注点。
MSD Core 会继续提出几个澄清性问题。自然地回答即可。它在撰写任何计划之前,正在了解你的关注点。
问题结束后,它会提议进行领域调研。对于如此小的项目,你可以跳过调研——在提示时选择**跳过调研**。
GSD Core 随后会要求你选择工作流设置(模式、粒度、调研代理)。每项均选择推荐的默认值。这些设置将写入 `.planning/config.json`。
MSD Core 随后会要求你选择工作流设置(模式、粒度、调研代理)。每项均选择推荐的默认值。这些设置将写入 `.planning/config.json`。
最后,一个路线图子代理开始运行(你会看到"Spawning roadmapper…"的提示——这是正常的,大约需要一分钟)。返回后,GSD Core 会展示一份路线图提案。对于单阶段项目,它看起来类似:
最后,一个路线图子代理开始运行(你会看到"Spawning roadmapper…"的提示——这是正常的,大约需要一分钟)。返回后,MSD Core 会展示一份路线图提案。对于单阶段项目,它看起来类似:
```text
Proposed Roadmap
@@ -115,7 +115,7 @@ Proposed Roadmap
## 第 4 步 — 清除上下文并讨论第 1 阶段
GSD Core 的设计围绕全新的上下文。在每个阶段之前清除主会话窗口:
MSD Core 的设计围绕全新的上下文。在每个阶段之前清除主会话窗口:
```text
/clear
@@ -124,10 +124,10 @@ GSD Core 的设计围绕全新的上下文。在每个阶段之前清除主会
然后开始第 1 阶段的讨论:
```text
/gsd-discuss-phase 1
/msd-discuss-phase 1
```
GSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响*如何*构建,而不仅仅是*构建什么*。示例交流:
MSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响*如何*构建,而不仅仅是*构建什么*。示例交流:
```text
> How should done items be stored — mark them in place or move them?
@@ -140,7 +140,7 @@ GSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响*
Create it silently on first add.
```
讨论结束后,GSD Core 会写入:
讨论结束后,MSD Core 会写入:
```text
.planning/phases/01-core-cli/CONTEXT.md
@@ -153,7 +153,7 @@ GSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响*
## 第 5 步 — 规划第 1 阶段
```text
/gsd-plan-phase 1
/msd-plan-phase 1
```
四个调研子代理并行展开工作(你会看到"Spawning 4 researchers…"的提示)。这需要 1–5 分钟,请勿中断。
@@ -169,17 +169,17 @@ GSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响*
01-02-PLAN.md ← 任务:实现 add / list / done 命令
```
打开 `01-01-PLAN.md`。你会看到一个 `<task>` 块,包含名称、涉及的文件、操作步骤、验证命令和完成条件。注意 `<verify>` 标签——GSD Core 的执行器将在写入代码后运行该命令。
打开 `01-01-PLAN.md`。你会看到一个 `<task>` 块,包含名称、涉及的文件、操作步骤、验证命令和完成条件。注意 `<verify>` 标签——MSD Core 的执行器将在写入代码后运行该命令。
---
## 第 6 步 — 执行第 1 阶段
```text
/gsd-execute-phase 1
/msd-execute-phase 1
```
GSD Core 将计划分组为波次(独立计划并行运行),为每个计划生成一个全新的 200k 上下文执行器,并原子性地提交每个任务。
MSD Core 将计划分组为波次(独立计划并行运行),为每个计划生成一个全新的 200k 上下文执行器,并原子性地提交每个任务。
你将看到类似如下内容:
@@ -215,17 +215,17 @@ node todo.js done 1
node todo.js list
```
你应该看到条目出现,并且在标记完成后,条目 1 从默认列表中消失。这是 GSD Core 交付的你的第一个可见结果。
你应该看到条目出现,并且在标记完成后,条目 1 从默认列表中消失。这是 MSD Core 交付的你的第一个可见结果。
---
## 第 7 步 — 验证工作
```text
/gsd-verify-work 1
/msd-verify-work 1
```
GSD Core 提取阶段的成功标准并逐一引导你完成:
MSD Core 提取阶段的成功标准并逐一引导你完成:
```text
[1/3] Can you run `node todo.js add "buy milk"` without errors?
@@ -240,7 +240,7 @@ GSD Core 提取阶段的成功标准并逐一引导你完成:
All 3 checks passed. Phase 1 verified.
```
如果任何检查失败,GSD Core 会诊断根本原因并创建修复计划。再次运行 `/gsd-execute-phase 1` 应用修复,然后重新运行 `/gsd-verify-work 1`。
如果任何检查失败,MSD Core 会诊断根本原因并创建修复计划。再次运行 `/msd-execute-phase 1` 应用修复,然后重新运行 `/msd-verify-work 1`。
**创建的内容:**
@@ -253,10 +253,10 @@ All 3 checks passed. Phase 1 verified.
## 第 8 步 — 发布
```text
/gsd-ship 1
/msd-ship 1
```
GSD Core 使用自动生成的正文创建拉取请求。PR 正文始终包含:摘要、变更内容、已解决的需求、验证情况和关键决策。
MSD Core 使用自动生成的正文创建拉取请求。PR 正文始终包含:摘要、变更内容、已解决的需求、验证情况和关键决策。
你将看到:
@@ -272,15 +272,15 @@ Title: feat(phase-1): core CLI — add / list / done commands
## 你学到了什么
- 如何使用 `npx @opengsd/gsd-core@latest` 安装 GSD Core。
- `/gsd-new-project` 如何将一段对话转化为由 `.planning/` 产物支撑的路线图。
- `/gsd-discuss-phase` 如何在任何规划开始之前捕获实现决策。
- `/gsd-plan-phase` 如何生成并行调研器并产出原子任务计划。
- `/gsd-execute-phase` 如何以并行波次运行这些计划并提交每个任务。
- `/gsd-verify-work` 如何引导完成成功标准并在需要时生成修复计划。
- `/gsd-ship` 如何将已验证的阶段转化为拉取请求。
- 如何使用 `npx @golem15/msd-core@latest` 安装 MSD Core。
- `/msd-new-project` 如何将一段对话转化为由 `.planning/` 产物支撑的路线图。
- `/msd-discuss-phase` 如何在任何规划开始之前捕获实现决策。
- `/msd-plan-phase` 如何生成并行调研器并产出原子任务计划。
- `/msd-execute-phase` 如何以并行波次运行这些计划并提交每个任务。
- `/msd-verify-work` 如何引导完成成功标准并在需要时生成修复计划。
- `/msd-ship` 如何将已验证的阶段转化为拉取请求。
对于多阶段项目,对每个阶段重复第 4–8 步,然后运行 `/gsd-progress --next`,让 GSD Core 自动检测下一步。
对于多阶段项目,对每个阶段重复第 4–8 步,然后运行 `/msd-progress --next`,让 MSD Core 自动检测下一步。
---
@@ -288,4 +288,4 @@ Title: feat(phase-1): core CLI — add / list / done commands
- [阶段循环](../explanation/the-phase-loop.md) — 循环为何如此设计
- [操作指南](../README.md#how-to-guides) — 针对特定情况的任务型操作说明
- [接入现有代码库](onboarding-an-existing-codebase.md) — 将 GSD Core 引入棕地仓库
- [接入现有代码库](onboarding-an-existing-codebase.md) — 将 MSD Core 引入棕地仓库

View File

@@ -1,6 +1,6 @@
# 讨论模式:假设模式与访谈模式
GSD Core 的讨论阶段提供两种模式,用于在规划开始前收集实现上下文。了解何时使用哪种模式,有助于减少来回沟通,更快地生成确认后的 `CONTEXT.md`。
MSD Core 的讨论阶段提供两种模式,用于在规划开始前收集实现上下文。了解何时使用哪种模式,有助于减少来回沟通,更快地生成确认后的 `CONTEXT.md`。
有关运行任一模式的分步说明,请参阅[讨论阶段使用指南](how-to/discuss-a-phase.md)。
@@ -26,10 +26,10 @@ GSD Core 的讨论阶段提供两种模式,用于在规划开始前收集实
```bash
# 启用假设模式
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
node msd-tools.cjs config-set workflow.discuss_mode assumptions
# 切换回访谈模式
node gsd-tools.cjs config-set workflow.discuss_mode discuss
node msd-tools.cjs config-set workflow.discuss_mode discuss
```
该设置为每个项目独立存储(保存于 `.planning/config.json`)。有关两种模式所生成文件的完整结构,请参阅 [CONTEXT.md 结构说明](reference/context-md.md)。
@@ -69,7 +69,7 @@ node gsd-tools.cjs config-set workflow.discuss_mode discuss
## 相关资源
- [讨论阶段](how-to/discuss-a-phase.md) — 运行 `/gsd-discuss-phase` 的分步指南(支持两种模式)。
- [讨论阶段](how-to/discuss-a-phase.md) — 运行 `/msd-discuss-phase` 的分步指南(支持两种模式)。
- [CONTEXT.md 结构说明](reference/context-md.md) — 两种模式所生成文件的完整字段参考。
- [阶段循环](explanation/the-phase-loop.md) — 讨论如何融入更广泛的 讨论 → 规划 → 执行 → 验证 → 发布 循环。
- [文档索引](README.md) — GSD Core 文档的完整目录。
- [文档索引](README.md) — MSD Core 文档的完整目录。