docs: rebrand to GSD Core and restructure docs with Diataxis (#605)
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
745
docs/zh-CN/ARCHITECTURE.md
Normal file
745
docs/zh-CN/ARCHITECTURE.md
Normal file
@@ -0,0 +1,745 @@
|
||||
# GSD Core 架构
|
||||
|
||||
> 面向贡献者和高级用户的系统架构说明。如需面向用户的文档，请参阅[功能参考](FEATURES.md)或[用户指南](USER-GUIDE.md)。
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
- [系统概述](#系统概述)
|
||||
- [设计原则](#设计原则)
|
||||
- [组件架构](#组件架构)
|
||||
- [Agent 模型](#agent-模型)
|
||||
- [数据流](#数据流)
|
||||
- [文件系统布局](#文件系统布局)
|
||||
- [安装程序架构](#安装程序架构)
|
||||
- [Hook 系统](#hook-系统)
|
||||
- [CLI 工具层](#cli-工具层)
|
||||
- [运行时抽象](#运行时抽象)
|
||||
|
||||
---
|
||||
|
||||
## 系统概述
|
||||
|
||||
GSD Core 是一个**元提示框架**，位于用户与 AI 编码 Agent（Claude Code、Gemini 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)）
|
||||
3. **规范驱动开发** — 需求 → 研究 → 计划 → 执行 → 验证的完整流水线
|
||||
4. **状态管理** — 跨会话和上下文重置的持久化项目记忆
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ USER │
|
||||
│ /gsd-command [args] │
|
||||
└─────────────────────┬────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────▼────────────────────────────────┐
|
||||
│ COMMAND LAYER │
|
||||
│ commands/gsd/*.md — Prompt-based command files │
|
||||
│ (Claude Code custom commands / Codex skills) │
|
||||
└─────────────────────┬────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────▼────────────────────────────────┐
|
||||
│ WORKFLOW LAYER │
|
||||
│ get-shit-done/workflows/*.md — Orchestration logic │
|
||||
│ (Reads references, spawns agents, manages state) │
|
||||
└──────┬──────────────┬─────────────────┬──────────────┘
|
||||
│ │ │
|
||||
┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐
|
||||
│ AGENT │ │ AGENT │ │ AGENT │
|
||||
│ (fresh │ │ (fresh │ │ (fresh │
|
||||
│ context) │ │ context)│ │ context) │
|
||||
└──────┬──────┘ └─────┬─────┘ └────────┬───────┘
|
||||
│ │ │
|
||||
┌──────▼──────────────▼─────────────────▼──────────────┐
|
||||
│ CLI TOOLS LAYER │
|
||||
│ gsd-tools.cjs command families + domain modules │
|
||||
│ command-routing-hub + observability seams │
|
||||
└──────────────────────┬───────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────▼───────────────────────────────┐
|
||||
│ FILE SYSTEM (.planning/) │
|
||||
│ PROJECT.md | REQUIREMENTS.md | ROADMAP.md │
|
||||
│ STATE.md | config.json | phases/ | research/ │
|
||||
└──────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 设计原则
|
||||
|
||||
### 1. 每个 Agent 拥有全新上下文
|
||||
|
||||
编排器派生的每个 Agent 都有一个干净的上下文窗口（最多 200K token）。这消除了上下文腐化——即 AI 在其上下文窗口中积累大量对话后导致的质量下降问题。
|
||||
|
||||
### 2. 轻量级编排器
|
||||
|
||||
工作流文件（`get-shit-done/workflows/*.md`）不承担繁重工作。它们：
|
||||
|
||||
- 通过 `gsd-tools.cjs init <workflow>` 加载上下文
|
||||
- 以聚焦的提示词派生专用 Agent
|
||||
- 收集结果并路由到下一步
|
||||
- 在步骤之间更新状态
|
||||
|
||||
### 3. 基于文件的状态
|
||||
|
||||
所有状态以人类可读的 Markdown 和 JSON 格式存储在 `.planning/` 中。无需数据库、服务器或外部依赖。这意味着：
|
||||
|
||||
- 状态在上下文重置（`/clear`）后仍然保留
|
||||
- 状态可由人类和 Agent 共同检查
|
||||
- 状态可提交到 git 以供团队查看
|
||||
|
||||
### 4. 缺省即启用
|
||||
|
||||
工作流功能标志遵循**缺省即启用**模式。若 `config.json` 中缺少某个键，则默认为 `true`。用户需显式禁用功能；无需手动启用默认值。
|
||||
|
||||
### 5. 深度防御
|
||||
|
||||
多层保护防止常见故障模式：
|
||||
|
||||
- 计划在执行前经过验证（plan-checker agent）
|
||||
- 执行为每个任务生成原子提交
|
||||
- 执行后验证会检查是否符合阶段目标
|
||||
- UAT 提供人工验证作为最终关卡
|
||||
|
||||
---
|
||||
|
||||
## 组件架构
|
||||
|
||||
### 命令（`commands/gsd/*.md`）
|
||||
|
||||
面向用户的入口点。每个文件包含 YAML 前置元数据（name、description、allowed-tools）以及引导工作流的提示词主体。命令按如下方式安装：
|
||||
|
||||
- **Claude Code：** 自定义斜线命令（连字符形式，`/gsd-command-name`）
|
||||
- **OpenCode / Kilo：** 斜线命令（连字符形式，`/gsd-command-name`）
|
||||
- **Codex：** 技能（`$gsd-command-name`）
|
||||
- **Copilot：** 斜线命令（连字符形式，`/gsd-command-name`）
|
||||
- **Gemini CLI：** 在 `gsd:` 命名空间下的斜线命令（冒号形式，`/gsd:command-name`）——Gemini 将所有自定义命令置于其插件 id 的命名空间下，因此安装路径会将正文中的每个引用改写为冒号形式
|
||||
- **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），选择命名空间后通过嵌入在命名空间路由器主体中的路由表路由到具体子技能。命名空间技能是**可叠加的**——每个具体命令仍可直接调用。
|
||||
|
||||
路由器描述使用管道分隔的关键词标签（≤ 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` 了解审计清单。
|
||||
|
||||
### 工作流（`get-shit-done/workflows/*.md`）
|
||||
|
||||
命令所引用的编排逻辑，包含逐步流程：
|
||||
|
||||
- 通过 `gsd-tools.cjs init` 处理程序加载上下文
|
||||
- 带有模型解析的 Agent 派生指令
|
||||
- 关卡/检查点定义
|
||||
- 状态更新模式
|
||||
- 错误处理与恢复
|
||||
|
||||
**工作流总数：** 请参阅 [`docs/INVENTORY.md`](INVENTORY.md#workflows) 获取权威数量及完整列表。
|
||||
|
||||
#### 工作流的渐进式披露
|
||||
|
||||
工作流文件在每次调用对应的 `/gsd-*` 命令时会被完整加载到 Claude 的上下文中。为控制该成本，`tests/workflow-size-budget.test.cjs` 强制执行的工作流大小预算与 #2361 中的 Agent 预算保持一致：
|
||||
|
||||
| 层级 | 每文件行数限制 |
|
||||
|-----------|--------------------|
|
||||
| `XL` | 1700 — 顶级编排器（`execute-phase`、`plan-phase`、`new-project`） |
|
||||
| `LARGE` | 1500 — 多步骤规划器和大型功能工作流 |
|
||||
| `DEFAULT` | 1000 — 聚焦于单一目的的工作流（目标层级） |
|
||||
|
||||
根据 issue #2551，`workflows/discuss-phase.md` 须严格遵守 <500 行上限。当工作流超出其层级时，应将各模式的主体提取到 `workflows/<workflow>/modes/<mode>.md`，将模板提取到 `workflows/<workflow>/templates/`，将共享知识提取到 `get-shit-done/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。
|
||||
|
||||
### Agent（`agents/*.md`）
|
||||
|
||||
带有前置元数据的专用 Agent 定义，指定：
|
||||
|
||||
- `name` — Agent 标识符
|
||||
- `description` — 角色与用途
|
||||
- `tools` — 允许的工具访问（Read、Write、Edit、Bash、Grep、Glob、WebSearch 等）
|
||||
- `color` — 用于视觉区分的终端输出颜色
|
||||
|
||||
**Agent 总数：** 33
|
||||
|
||||
### 参考文档（`get-shit-done/references/*.md`）
|
||||
|
||||
工作流和 Agent 通过 `@-reference` 引用的共享知识文档（请参阅 [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) 获取权威数量及完整列表）：
|
||||
|
||||
**核心参考：**
|
||||
|
||||
- `checkpoints.md` — 检查点类型定义和交互模式
|
||||
- `gates.md` — 4 种规范关卡类型（确认、质量、安全、转换），与 plan-checker 和 verifier 连接
|
||||
- `model-profiles.md` — 各 Agent 的模型层级分配
|
||||
- `model-profile-resolution.md` — 模型解析算法文档
|
||||
- `verification-patterns.md` — 不同产物类型的验证方式
|
||||
- `verification-overrides.md` — 每种产物的验证覆盖规则
|
||||
- `planning-config.md` — 完整配置 schema 和行为说明
|
||||
- `git-integration.md` — Git 提交、分支及历史记录模式
|
||||
- `git-planning-commit.md` — 规划目录提交约定
|
||||
- `questioning.md` — 项目初始化的梦想提取理念
|
||||
- `tdd.md` — 测试驱动开发集成模式
|
||||
- `ui-brand.md` — 视觉输出格式化模式
|
||||
- `common-bug-patterns.md` — 代码审查和验证的常见错误模式
|
||||
|
||||
**工作流参考：**
|
||||
|
||||
- `agent-contracts.md` — 编排器与 Agent 之间的正式接口
|
||||
- `context-budget.md` — 上下文窗口预算分配规则
|
||||
- `continuation-format.md` — 会话续接/恢复格式
|
||||
- `domain-probes.md` — discuss-phase 的领域特定探测问题
|
||||
- `gate-prompts.md` — 关卡/检查点提示词模板
|
||||
- `revision-loop.md` — 计划修订迭代模式
|
||||
- `universal-anti-patterns.md` — 需检测和避免的常见反模式
|
||||
- `artifact-types.md` — 规划产物类型定义
|
||||
- `phase-argument-parsing.md` — 阶段参数解析约定
|
||||
- `decimal-phase-calculation.md` — 十进制子阶段编号规则
|
||||
- `workstream-flag.md` — 工作流活动指针约定
|
||||
- `user-profiling.md` — 用户行为分析方法
|
||||
- `thinking-partner.md` — 在决策点条件性激活思考伙伴
|
||||
|
||||
**思考模型参考：**
|
||||
|
||||
将思考类模型（o3、o4-mini、Gemini 2.5 Pro）集成到 GSD 工作流的参考文档：
|
||||
|
||||
- `thinking-models-debug.md` — 调试工作流的思考模型模式
|
||||
- `thinking-models-execution.md` — 执行 Agent 的思考模型模式
|
||||
- `thinking-models-planning.md` — 规划 Agent 的思考模型模式
|
||||
- `thinking-models-research.md` — 研究 Agent 的思考模型模式
|
||||
- `thinking-models-verification.md` — 验证 Agent 的思考模型模式
|
||||
|
||||
**模块化规划器分解：**
|
||||
|
||||
规划器 Agent（`agents/gsd-planner.md`）已从单一整体文件分解为一个核心 Agent 加参考模块，以遵守部分运行时强加的 50K 字符限制：
|
||||
|
||||
- `planner-gap-closure.md` — 缺口修复模式行为（读取 VERIFICATION.md，针对性重规划）
|
||||
- `planner-reviews.md` — 跨 AI 审查集成（从 `/gsd-review` 读取 REVIEWS.md）
|
||||
- `planner-revision.md` — 用于迭代细化的计划修订模式
|
||||
|
||||
### 模板（`get-shit-done/templates/`）
|
||||
|
||||
所有规划产物的 Markdown 模板。由 `gsd-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`）— 粒度感知摘要模板
|
||||
- `DEBUG.md` — 调试会话跟踪模板
|
||||
- `UI-SPEC.md`、`UAT.md`、`VALIDATION.md` — 专用验证模板
|
||||
- `discussion-log.md` — 讨论审计追踪模板
|
||||
- `codebase/` — 棕地映射模板（技术栈、架构、约定、关注点、结构、测试、集成）
|
||||
- `research-project/` — 研究输出模板（SUMMARY、STACK、FEATURES、ARCHITECTURE、PITFALLS）
|
||||
|
||||
### Hook（`hooks/`）
|
||||
|
||||
与宿主 AI Agent 集成的运行时 hook：
|
||||
|
||||
| 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-read-guard.js` | `PreToolUse` | 建议性防护，防止对本会话中尚未读取的文件执行 Edit/Write |
|
||||
| `gsd-session-state.sh` | `PostToolUse` | 基于 shell 的运行时的会话状态跟踪 |
|
||||
| `gsd-validate-commit.sh` | `PostToolUse` | 用于规范提交格式执行的提交验证 |
|
||||
| `gsd-phase-boundary.sh` | `PostToolUse` | 工作流转换的阶段边界检测 |
|
||||
|
||||
请参阅 [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped) 获取权威的 11 个 hook 列表。
|
||||
|
||||
### 命令路由中枢（`get-shit-done/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`。
|
||||
|
||||
### CLI 工具（`get-shit-done/bin/`）
|
||||
|
||||
Node.js CLI 工具（`gsd-tools.cjs`），其领域模块分布在 `get-shit-done/bin/lib/` 中（请参阅 [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) 获取权威列表）：
|
||||
|
||||
|
||||
| 模块 | 职责 |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `core.cjs` | 错误处理、输出格式化、共享工具；规划辅助程序的兼容性重导出 |
|
||||
| `planning-workspace.cjs` | 规划接缝（`planningDir`、`planningPaths`、活动工作流路由、`.planning/.lock`） |
|
||||
| `state.cjs` | STATE.md 解析、更新、进度跟踪、指标 |
|
||||
| `phase.cjs` | 阶段目录操作、十进制编号、计划索引 |
|
||||
| `roadmap.cjs` | ROADMAP.md 解析、阶段提取、计划进度 |
|
||||
| `config.cjs` | config.json 读写、节初始化 |
|
||||
| `verify.cjs` | 计划结构、阶段完整性、引用、提交验证 |
|
||||
| `template.cjs` | 带变量替换的模板选择与填充 |
|
||||
| `frontmatter.cjs` | YAML 前置元数据 CRUD 操作 |
|
||||
| `init.cjs` | 各工作流类型的复合上下文加载 |
|
||||
| `milestone.cjs` | 里程碑归档、需求标记 |
|
||||
| `commands.cjs` | 杂项命令（slug、时间戳、待办事项、脚手架、统计） |
|
||||
| `model-profiles.cjs` | 模型配置文件解析表 |
|
||||
| `security.cjs` | 路径遍历防护、提示词注入检测、安全 JSON 解析、shell 参数验证 |
|
||||
| `uat.cjs` | UAT 文件解析、验证债务跟踪、审计 UAT 支持 |
|
||||
| `docs.cjs` | 文档更新工作流初始化、Markdown 扫描、Monorepo 检测 |
|
||||
| `workstream.cjs` | 工作流 CRUD、迁移、会话范围活动指针 |
|
||||
| `schema-detect.cjs` | ORM 模式（Prisma、Drizzle 等）的 schema 漂移检测 |
|
||||
| `profile-pipeline.cjs` | 用户行为分析数据管道、会话文件扫描 |
|
||||
| `profile-output.cjs` | 配置文件渲染、USER-PROFILE.md 和 dev-preferences.md 生成 |
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Agent 模型
|
||||
|
||||
### 编排器 → Agent 模式
|
||||
|
||||
```
|
||||
Orchestrator (workflow .md)
|
||||
│
|
||||
├── Load context: gsd-tools.cjs init <workflow> <phase>
|
||||
│ Returns JSON with: project info, config, state, phase details
|
||||
│
|
||||
├── Resolve model: gsd-tools.cjs resolve-model <agent-name>
|
||||
│ Returns: opus | sonnet | haiku | inherit
|
||||
│
|
||||
├── Spawn Agent (Task/SubAgent call)
|
||||
│ ├── Agent prompt (agents/*.md)
|
||||
│ ├── Context payload (init JSON)
|
||||
│ ├── Model assignment
|
||||
│ └── Tool permissions
|
||||
│
|
||||
├── Collect result
|
||||
│
|
||||
└── Update state: gsd-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)。
|
||||
|
||||
|
||||
| 类别 | 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 期间） |
|
||||
|
||||
|
||||
### 波次执行模型
|
||||
|
||||
在 `execute-phase` 期间，计划按依赖关系分组为波次：
|
||||
|
||||
```
|
||||
Wave Analysis:
|
||||
Plan 01 (no deps) ─┐
|
||||
Plan 02 (no deps) ─┤── Wave 1 (parallel)
|
||||
Plan 03 (depends: 01) ─┤── Wave 2 (waits for Wave 1)
|
||||
Plan 04 (depends: 02) ─┘
|
||||
Plan 05 (depends: 03,04) ── Wave 3 (waits for Wave 2)
|
||||
```
|
||||
|
||||
每个执行者获得：
|
||||
|
||||
- 全新的 200K 上下文窗口（支持的模型最高可达 1M）
|
||||
- 待执行的具体 PLAN.md
|
||||
- 项目上下文（PROJECT.md、STATE.md）
|
||||
- 阶段上下文（CONTEXT.md、RESEARCH.md（如可用））
|
||||
|
||||
### 自适应上下文增强（1M 模型）
|
||||
|
||||
当上下文窗口为 500K+ token 时（1M 级模型，如 Opus 4.6、Sonnet 4.6），子 Agent 提示词会自动增强额外上下文，这些内容在标准 200K 窗口中无法容纳：
|
||||
|
||||
- **执行者 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 窗口，提示词使用截断版本并以缓存友好的顺序排列，以最大化上下文效率。
|
||||
|
||||
#### 并行提交安全性
|
||||
|
||||
当多个执行者在同一波次内运行时，两种机制防止冲突：
|
||||
|
||||
1. `--no-verify` 提交 — 并行 Agent 跳过预提交 hook（可能导致构建锁争用，例如 Rust 项目中的 cargo lock 冲突）。编排器在每个波次完成后运行一次 `git hook run pre-commit`。
|
||||
2. **STATE.md 文件锁** — 所有 `writeStateMd()` 调用使用基于锁文件的互斥（`STATE.md.lock`，采用 `O_EXCL` 原子创建）。这防止了读-改-写竞态条件，即两个 Agent 同时读取 STATE.md、修改不同字段，而后写者覆盖前者更改的问题。包含陈旧锁检测（10 秒超时）和带抖动的自旋等待。
|
||||
|
||||
---
|
||||
|
||||
## 数据流
|
||||
|
||||
### 新项目流程
|
||||
|
||||
```
|
||||
User input (idea description)
|
||||
│
|
||||
▼
|
||||
Questions (questioning.md philosophy)
|
||||
│
|
||||
▼
|
||||
4x Project Researchers (parallel)
|
||||
├── Stack → STACK.md
|
||||
├── Features → FEATURES.md
|
||||
├── Architecture → ARCHITECTURE.md
|
||||
└── Pitfalls → PITFALLS.md
|
||||
│
|
||||
▼
|
||||
Research Synthesizer → SUMMARY.md
|
||||
│
|
||||
▼
|
||||
Requirements extraction → REQUIREMENTS.md
|
||||
│
|
||||
▼
|
||||
Roadmapper → ROADMAP.md
|
||||
│
|
||||
▼
|
||||
User approval → STATE.md initialized
|
||||
```
|
||||
|
||||
### 阶段执行流程
|
||||
|
||||
```
|
||||
discuss-phase → CONTEXT.md (user preferences)
|
||||
│
|
||||
▼
|
||||
ui-phase → UI-SPEC.md (design contract, optional)
|
||||
│
|
||||
▼
|
||||
plan-phase
|
||||
├── Research gate (blocks if RESEARCH.md has unresolved open questions)
|
||||
├── Phase Researcher → RESEARCH.md
|
||||
│ └── Package Legitimacy Gate: slopcheck on every package; [SLOP] removed,
|
||||
│ [SUS]/[ASSUMED] flagged; Audit table written to RESEARCH.md
|
||||
├── Planner (with reachability check) → PLAN.md files
|
||||
│ └── checkpoint:human-verify injected before [ASSUMED]/[SUS] installs;
|
||||
│ T-{phase}-SC STRIDE row added for install-bearing plans
|
||||
├── Plan Checker → Verify loop (max 3x)
|
||||
├── Requirements coverage gate (REQ-IDs → plans)
|
||||
└── Decision coverage gate (CONTEXT.md `<decisions>` → plans, BLOCKING — #2492)
|
||||
│
|
||||
▼
|
||||
state planned-phase → STATE.md (Planned/Ready to execute)
|
||||
│
|
||||
▼
|
||||
execute-phase (context reduction: truncated prompts, cache-friendly ordering)
|
||||
├── Wave analysis (dependency grouping)
|
||||
├── Executor per plan → code + atomic commits
|
||||
├── SUMMARY.md per plan
|
||||
└── Verifier → VERIFICATION.md
|
||||
└── Decision coverage gate (CONTEXT.md decisions → shipped artifacts, NON-BLOCKING — #2492)
|
||||
│
|
||||
▼
|
||||
verify-work → UAT.md (user acceptance testing)
|
||||
│
|
||||
▼
|
||||
ui-review → UI-REVIEW.md (visual audit, optional)
|
||||
```
|
||||
|
||||
### 上下文传播
|
||||
|
||||
每个工作流阶段生成的产物会传入后续阶段：
|
||||
|
||||
```
|
||||
PROJECT.md ────────────────────────────────────────────► All agents
|
||||
REQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor
|
||||
ROADMAP.md ────────────────────────────────────────────► Orchestrators
|
||||
STATE.md ──────────────────────────────────────────────► All agents (decisions, blockers)
|
||||
CONTEXT.md (per phase) ────────────────────────────────► Researcher, Planner, Executor
|
||||
RESEARCH.md (per phase) ───────────────────────────────► Planner, Plan Checker
|
||||
PLAN.md (per plan) ────────────────────────────────────► Executor, Plan Checker
|
||||
SUMMARY.md (per plan) ─────────────────────────────────► Verifier, State tracking
|
||||
UI-SPEC.md (per phase) ────────────────────────────────► Executor, UI Auditor
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 文件系统布局
|
||||
|
||||
### 安装文件
|
||||
|
||||
```
|
||||
~/.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
|
||||
├── get-shit-done/
|
||||
│ ├── bin/gsd-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)
|
||||
│ └── templates/ # Planning artifact templates
|
||||
├── agents/*.md # Agent definitions (authoritative roster: docs/INVENTORY.md)
|
||||
├── hooks/*.js # Node.js hooks (statusline, guards, monitors, update check)
|
||||
├── hooks/*.sh # Shell hooks (session state, commit validation, phase boundary)
|
||||
├── settings.json # Hook registrations
|
||||
└── VERSION # Installed version number
|
||||
```
|
||||
|
||||
其他运行时的等效路径：
|
||||
|
||||
- **OpenCode：** `~/.config/opencode/` 全局或 `./.opencode/` 本地
|
||||
- **Kilo：** `~/.config/kilo/` 全局或 `./.kilo/` 本地
|
||||
- **Gemini CLI：** `~/.gemini/` 全局或 `./.gemini/` 本地
|
||||
- **Codex：** `~/.codex/` 全局或 `./.codex/` 本地
|
||||
- **Copilot：** `~/.copilot/` 全局或 `./.github/` 本地
|
||||
- **Antigravity：** 自动检测全局根目录（`~/.gemini/antigravity/`、`~/.gemini/antigravity-ide/` 或 `~/.gemini/antigravity-cli/`）或 `./.agent/` 本地
|
||||
- **Cursor：** `~/.cursor/` 全局或 `./.cursor/` 本地
|
||||
- **Windsurf：** `~/.codeium/windsurf/` 全局或 `./.windsurf/` 本地
|
||||
- **Augment Code：** `~/.augment/` 全局或 `./.augment/` 本地
|
||||
- **Trae：** `~/.trae/` 全局或 `./.trae/` 本地
|
||||
- **Qwen Code：** `~/.qwen/` 全局或 `./.qwen/` 本地
|
||||
- **Hermes Agent：** `~/.hermes/` 全局或 `./.hermes/` 本地
|
||||
- **CodeBuddy：** `~/.codebuddy/` 全局或 `./.codebuddy/` 本地
|
||||
- **Cline：** `~/.cline/` 全局或项目根目录 `.clinerules` 本地
|
||||
|
||||
### 项目文件（`.planning/`）
|
||||
|
||||
```
|
||||
.planning/
|
||||
├── PROJECT.md # Project vision, constraints, decisions, evolution rules
|
||||
├── REQUIREMENTS.md # Scoped requirements (v1/v2/out-of-scope)
|
||||
├── ROADMAP.md # Phase breakdown with status tracking
|
||||
├── STATE.md # Living memory: position, decisions, blockers, metrics
|
||||
├── config.json # Workflow configuration
|
||||
├── MILESTONES.md # Completed milestone archive
|
||||
├── research/ # Domain research from /gsd-new-project
|
||||
│ ├── SUMMARY.md
|
||||
│ ├── STACK.md
|
||||
│ ├── FEATURES.md
|
||||
│ ├── ARCHITECTURE.md
|
||||
│ └── PITFALLS.md
|
||||
├── codebase/ # Brownfield mapping (from /gsd-map-codebase)
|
||||
│ ├── STACK.md # YAML frontmatter carries `last_mapped_commit`
|
||||
│ ├── ARCHITECTURE.md # for the post-execute drift gate (#2003)
|
||||
│ ├── CONVENTIONS.md
|
||||
│ ├── CONCERNS.md
|
||||
│ ├── STRUCTURE.md
|
||||
│ ├── TESTING.md
|
||||
│ └── INTEGRATIONS.md
|
||||
├── phases/
|
||||
│ └── XX-phase-name/
|
||||
│ ├── XX-CONTEXT.md # User preferences (from discuss-phase)
|
||||
│ ├── XX-RESEARCH.md # Ecosystem research (from plan-phase)
|
||||
│ ├── XX-YY-PLAN.md # Execution plans
|
||||
│ ├── XX-YY-SUMMARY.md # Execution outcomes
|
||||
│ ├── XX-VERIFICATION.md # Post-execution verification
|
||||
│ ├── XX-VALIDATION.md # Nyquist test coverage mapping
|
||||
│ ├── XX-UI-SPEC.md # UI design contract (from ui-phase)
|
||||
│ ├── XX-UI-REVIEW.md # Visual audit scores (from ui-review)
|
||||
│ └── XX-UAT.md # User acceptance test results
|
||||
├── quick/ # Quick task tracking
|
||||
│ └── YYMMDD-xxx-slug/
|
||||
│ ├── PLAN.md
|
||||
│ └── SUMMARY.md
|
||||
├── todos/
|
||||
│ ├── pending/ # Captured ideas
|
||||
│ └── done/ # Completed todos
|
||||
├── threads/ # Persistent context threads (from /gsd-thread)
|
||||
├── seeds/ # Forward-looking ideas (from /gsd-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)
|
||||
└── 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` 进行对比，并统计四类结构性元素：
|
||||
|
||||
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` 并将其范围限定为受影响的路径。检测或重新映射过程中的任何错误都会被记录，阶段继续执行——漂移检测不会导致验证失败。
|
||||
|
||||
`last_mapped_commit` 存储在每个 `.planning/codebase/*.md` 文件顶部的 YAML 前置元数据中；`bin/lib/drift.cjs` 提供 `readMappedCommit` 和 `writeMappedCommit` 往返辅助函数。
|
||||
|
||||
---
|
||||
|
||||
## 安装程序架构
|
||||
|
||||
安装程序（`bin/install.js`，约 10,700 行）处理以下事项：
|
||||
|
||||
1. **运行时检测** — 交互式提示或 CLI 标志（`--claude`、`--opencode`、`--gemini`、`--kilo`、`--codex`、`--copilot`、`--antigravity`、`--cursor`、`--windsurf`、`--augment`、`--trae`、`--qwen`、`--hermes`、`--codebuddy`、`--cline`、`--all`）
|
||||
2. **位置选择** — 全局（`--global`）或本地（`--local`）
|
||||
3. **文件部署** — 复制命令、技能、工作流、参考文档、模板、Agent 和 hook
|
||||
4. **运行时适配** — 按运行时转换文件内容：
|
||||
- Claude Code：原样使用
|
||||
- OpenCode：将命令/Agent 转换为 OpenCode 兼容的扁平命令 + 子 Agent 格式
|
||||
- Kilo：复用 OpenCode 转换流水线，使用 Kilo 配置路径
|
||||
- Codex：从命令生成 TOML 配置 + 技能
|
||||
- Copilot：映射工具名称（Read→read、Bash→execute 等）
|
||||
- Gemini：调整 hook 事件名称（`AfterTool` 而非 `PostToolUse`）
|
||||
- Antigravity：以技能为主，使用 Google 模型等效项
|
||||
- Cursor：以技能为主，带 Cursor 规则引用
|
||||
- Windsurf：以技能为主，带 Windsurf 规则引用
|
||||
- Trae：以技能为主安装到 `~/.trae` / `./.trae`，不含 `settings.json` 或 hook 集成
|
||||
- Qwen Code：以技能为主，带 Qwen 品牌路径和提示词重写
|
||||
- Hermes Agent：在 `skills/gsd/` 下按类别分组的技能
|
||||
- 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 和设置
|
||||
|
||||
安装时的文件移动、陈旧产物清理、配置重写和用户数据保留由安装程序迁移模块管理。请参阅[安装程序迁移](../installer-migrations.md)和 [ADR 0008](../adr/0008-installer-migration-module.md)。迁移模块还负责对旧版安装进行带关卡的首次基线扫描，在后续迁移移除或重写任何内容之前，对已知的运行时安装界面进行分类。
|
||||
|
||||
计划漂移防护（`plan_review.source_grounding`）——在执行前验证生成计划中的符号引用是否与实时源代码匹配——详见 [ADR 22](../adr/22-plan-drift-guard.md)。
|
||||
|
||||
### 平台处理
|
||||
|
||||
- **Windows：** 在子进程上设置 `windowsHide`，对受保护目录进行 EPERM/EACCES 保护，路径分隔符规范化
|
||||
- **WSL：** 检测在 WSL 上运行的 Windows Node.js 并警告路径不匹配
|
||||
- **Docker/CI：** 支持 `CLAUDE_CONFIG_DIR` 环境变量，用于自定义配置目录位置
|
||||
|
||||
---
|
||||
|
||||
## Hook 系统
|
||||
|
||||
### 架构
|
||||
|
||||
```
|
||||
Runtime Engine (Claude Code / Gemini CLI)
|
||||
│
|
||||
├── statusLine event ──► gsd-statusline.js
|
||||
│ Reads: stdin (session JSON)
|
||||
│ Writes: stdout (formatted status), /tmp/claude-ctx-{session}.json (bridge)
|
||||
│
|
||||
├── PostToolUse/AfterTool event ──► gsd-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
|
||||
Reads: VERSION file
|
||||
Writes: ~/.claude/cache/gsd-update-check.json (spawns background process)
|
||||
```
|
||||
|
||||
### 上下文监控阈值
|
||||
|
||||
|
||||
| 剩余上下文 | 级别 | Agent 行为 |
|
||||
| --------- | -------- | ----------------------------------------- |
|
||||
| > 35% | 正常 | 不注入警告 |
|
||||
| ≤ 35% | 警告 | "避免开始新的复杂工作" |
|
||||
| ≤ 25% | 严重 | "上下文即将耗尽，请告知用户" |
|
||||
|
||||
|
||||
防抖：每次重复警告之间间隔 5 次工具使用。严重性升级（WARNING→CRITICAL）绕过防抖。
|
||||
|
||||
### 安全属性
|
||||
|
||||
- 所有 hook 包裹在 try/catch 中，出错时静默退出
|
||||
- stdin 超时防护（3 秒），防止管道问题导致挂起
|
||||
- 忽略陈旧指标（超过 60 秒）
|
||||
- 优雅处理缺失的桥接文件（子 Agent、新会话）
|
||||
- 上下文监控器为建议性——不发出覆盖用户偏好的命令式指令
|
||||
|
||||
### 软件包合法性关卡（v1.42.1）
|
||||
|
||||
研究者 → 规划者 → 执行者流水线包含一个针对 slopsquatting（AI 幻觉软件包名称被预先注册并附带恶意安装后脚本）的供应链关卡。
|
||||
|
||||
**威胁模型：** GSD 将从"研究者命名一个软件包"到"执行者运行 `npm install`"的完整路径自动化。一个通过 `npm view`（仅证明已注册，而非合法性）的幻觉名称此前可能未被检测到而流入。约 20% 的 AI 生成软件包引用是幻觉；其中约 43% 的名称在不同提示词中反复出现，使攻击者的预先注册在经济上可行。
|
||||
|
||||
**关卡层次：**
|
||||
|
||||
| 层次 | 组件 | 操作 |
|
||||
|-------|-----------|--------|
|
||||
| 研究 | `gsd-phase-researcher` | 运行 `slopcheck install <pkgs> --json`；向 RESEARCH.md 写入 `## Package Legitimacy Audit` 表格；在写入 RESEARCH.md 之前剥离 `[SLOP]` 软件包 |
|
||||
| 规划 | `gsd-planner` | 读取审计表；在任何 `[ASSUMED]` 或 `[SUS]` 安装任务之前插入 `checkpoint:human-verify`；向 `<threat_model>` 添加 `T-{phase}-SC` STRIDE 供应链行 |
|
||||
| 执行 | `gsd-executor` | 规则 3 将软件包安装排除在自动修复范围之外；失败的安装以检查点形式呈现，而非静默替换 |
|
||||
|
||||
**声明溯源集成：** 通过 WebSearch 发现的软件包名称被标记为 `[ASSUMED]`（而非 `[VERIFIED]`），无论 `npm view` 结果如何。这通过在安装边界将溯源标签强制执行为硬关卡，扩展了现有的 `[ASSUMED]` / `[VERIFIED]` / `[CITED]` 溯源系统——`[ASSUMED]` 始终在 PLAN.md 中生成 `checkpoint:human-verify`。
|
||||
|
||||
**生态系统覆盖：** 研究者使用特定于注册表的验证命令——`npm view`（Node）、`pip index versions`（Python）、`cargo search`（Rust）——而非单一通用检查。这能捕获跨生态系统幻觉（2025 年 USENIX 研究记录的发生率约为 9%）。
|
||||
|
||||
**优雅降级：** 若 `slopcheck` 不可用，每个推荐软件包都被标记为 `[ASSUMED]` 并通过检查点设置关卡。研究和规划继续进行；系统不会因缺少工具依赖而硬性失败。
|
||||
|
||||
**外部依赖：** `slopcheck`（MIT 协议，可通过 pip 安装）。若被废弃，`[ASSUMED]` 关卡回退机制维持人工检查点覆盖。
|
||||
|
||||
---
|
||||
|
||||
### 安全 Hook（v1.27）
|
||||
|
||||
有关 hook 和防护层如何融入更广泛安全方法的概念概述，请参阅[安全模型](explanation/security-model.md)。
|
||||
|
||||
**提示词防护**（`gsd-prompt-guard.js`）：
|
||||
|
||||
- 触发于对 `.planning/` 文件的 Write/Edit
|
||||
- 扫描内容中的提示词注入模式（角色覆盖、指令绕过、系统标签注入）
|
||||
- 仅建议性——记录检测结果，不阻止操作
|
||||
- 模式已内联（`security.cjs` 的子集），以实现 hook 独立性
|
||||
|
||||
**工作流防护**（`gsd-workflow-guard.js`）：
|
||||
|
||||
- 触发于对非 `.planning/` 文件的 Write/Edit
|
||||
- 检测 GSD 工作流上下文之外的编辑（无活动的 `/gsd-` 命令或任务子 Agent）
|
||||
- 建议使用 `/gsd-quick` 或 `/gsd-fast` 进行状态跟踪的变更
|
||||
- 通过 `hooks.workflow_guard: true` 选择启用（默认：false）
|
||||
|
||||
---
|
||||
|
||||
## 运行时抽象
|
||||
|
||||
GSD 通过统一的命令/工作流架构支持多种 AI 编码运行时：
|
||||
|
||||
### 运行时安装契约矩阵
|
||||
|
||||
此矩阵描述安装程序当前实现的运行时界面。迁移特定的所有权和源代码快照位于[安装程序迁移](../installer-migrations.md#runtime-configuration-contract-registry)中。
|
||||
|
||||
| 运行时 | 全局根目录 | 本地根目录 | 调用界面 | 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 |
|
||||
| Gemini CLI | `~/.gemini` | `./.gemini` | `commands/gsd/*.toml` | `agents/gsd-*.md` | `settings.json` 功能标志、hook 和 statusline |
|
||||
| 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 |
|
||||
|
||||
### 上游契约来源
|
||||
|
||||
运行时安装预期在可用时对照主要文档进行检查。当前源代码快照为 2026-05-11：
|
||||
|
||||
- Claude Code：Anthropic 斜线命令、设置、hook 和子 Agent 文档。
|
||||
- OpenCode 和 Kilo：OpenCode 配置文档和 Kilo 自定义子 Agent 文档。
|
||||
- Gemini CLI 和 Qwen Code：命令/配置文档；Qwen 命令文档最后更新于 2026-05-06。
|
||||
- Codex：OpenAI Codex 文档和 `config-schema.json`；安装程序还支持 Codex 0.124.0 的 Agent 表格格式兼容性。
|
||||
- Copilot、Cursor、Cline、Augment、Hermes 和 CodeBuddy：自定义指令、规则、技能或配置的供应商文档。
|
||||
- Antigravity、Windsurf 和 Trae：来源有限的行。安装程序记录了当前的兼容性垫片，迁移前必须刷新这些来源后再重写其配置。
|
||||
|
||||
### 抽象点
|
||||
|
||||
1. **工具名称映射** — 每个运行时有其自己的工具名称（例如 Claude 的 `Bash` → Copilot 的 `execute`）
|
||||
2. **Hook 事件名称** — Claude 使用 `PostToolUse`，Gemini 使用 `AfterTool`
|
||||
3. **Agent 前置元数据** — 每个运行时有其自己的 Agent 定义格式
|
||||
4. **路径约定** — 每个运行时将配置存储在不同的目录中
|
||||
5. **模型引用** — `inherit` 配置文件让 GSD 推迟到运行时的模型选择
|
||||
|
||||
安装程序在安装时处理所有转换。工作流和 Agent 以 Claude Code 的原生格式编写，并在部署期间进行转换。
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [多 Agent 编排](explanation/multi-agent-orchestration.md)
|
||||
- [安全模型](explanation/security-model.md)
|
||||
- [CLI 工具](CLI-TOOLS.md)
|
||||
- [文档索引](README.md)
|
||||
499
docs/zh-CN/CLI-TOOLS.md
Normal file
499
docs/zh-CN/CLI-TOOLS.md
Normal file
@@ -0,0 +1,499 @@
|
||||
# GSD CLI 工具参考
|
||||
|
||||
> `gsd-tools` CLI（`get-shit-done/bin/gsd-tools.cjs`）参考文档。斜杠命令与用户流程请参见[命令参考](COMMANDS.md)。返回[文档索引](README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
`gsd-tools.cjs` 集中处理配置解析、模型解析、阶段查找、Git 提交、摘要验证、状态管理以及模板操作，供 GSD 命令、工作流和代理使用。
|
||||
|
||||
|
||||
| | |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| **发布路径** | `get-shit-done/bin/gsd-tools.cjs` |
|
||||
| **实现** | `get-shit-done/bin/lib/` 下的 20 个领域模块（以该目录为准） |
|
||||
| **状态** | 编排、工作流和自动化的主要运行时命令接口。 |
|
||||
|
||||
|
||||
**用法（CJS）：**
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
|
||||
```
|
||||
|
||||
**全局标志（CJS）：**
|
||||
|
||||
|
||||
| 标志 | 说明 |
|
||||
| -------------- | ---------------------------------------------------------------------------- |
|
||||
| `--raw` | 机器可读输出（JSON 或纯文本，无格式） |
|
||||
| `--cwd <path>` | 覆盖工作目录（用于沙箱子代理） |
|
||||
| `--ws <name>` | `.planning/workstreams/<name>` 路径的工作流上下文 |
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 状态命令
|
||||
|
||||
管理 `.planning/STATE.md`——项目的活动记忆。
|
||||
|
||||
```bash
|
||||
# 以 JSON 格式加载完整项目配置和状态
|
||||
node gsd-tools.cjs state load
|
||||
|
||||
# 以 JSON 格式输出 STATE.md frontmatter
|
||||
node gsd-tools.cjs state json
|
||||
|
||||
# 更新单个字段
|
||||
node gsd-tools.cjs state update <field> <value>
|
||||
|
||||
# 获取 STATE.md 内容或特定章节
|
||||
node gsd-tools.cjs state get [section]
|
||||
|
||||
# 批量更新多个字段
|
||||
node gsd-tools.cjs state patch --field1 val1 --field2 val2
|
||||
|
||||
# 递增计划计数器
|
||||
node gsd-tools.cjs state advance-plan
|
||||
|
||||
# 记录执行指标
|
||||
node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N]
|
||||
|
||||
# 重新计算进度条
|
||||
node gsd-tools.cjs state update-progress
|
||||
|
||||
# 添加决策
|
||||
node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
|
||||
# 或从文件读取：
|
||||
node gsd-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 gsd-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
|
||||
|
||||
# 代理可发现的阻塞信号（由 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
|
||||
```
|
||||
|
||||
### 状态快照
|
||||
|
||||
对完整 STATE.md 进行结构化解析：
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs state-snapshot
|
||||
```
|
||||
|
||||
返回 JSON，包含：当前位置、阶段、计划、状态、决策、阻塞项、指标、最后活动。
|
||||
|
||||
---
|
||||
|
||||
## 阶段命令
|
||||
|
||||
管理阶段——目录、编号和路线图同步。
|
||||
|
||||
```bash
|
||||
# 按编号查找阶段目录
|
||||
node gsd-tools.cjs find-phase <phase>
|
||||
|
||||
# 计算插入用的下一个小数阶段编号
|
||||
node gsd-tools.cjs phase next-decimal <phase>
|
||||
|
||||
# 向路线图追加新阶段并创建目录
|
||||
node gsd-tools.cjs phase add <description>
|
||||
|
||||
# 在现有阶段后插入小数阶段
|
||||
node gsd-tools.cjs phase insert <after> <description>
|
||||
|
||||
# 移除阶段，对后续阶段重新编号
|
||||
node gsd-tools.cjs phase remove <phase> [--force]
|
||||
|
||||
# 标记阶段完成，更新状态和路线图
|
||||
node gsd-tools.cjs phase complete <phase>
|
||||
|
||||
# 按波次和状态索引计划
|
||||
node gsd-tools.cjs phase-plan-index <phase>
|
||||
|
||||
# 列出阶段并过滤
|
||||
node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 路线图命令
|
||||
|
||||
解析和更新 `ROADMAP.md`。
|
||||
|
||||
```bash
|
||||
# 从 ROADMAP.md 提取阶段章节
|
||||
node gsd-tools.cjs roadmap get-phase <phase>
|
||||
|
||||
# 带磁盘状态的完整路线图解析
|
||||
node gsd-tools.cjs roadmap analyze
|
||||
|
||||
# 从磁盘更新进度表行
|
||||
node gsd-tools.cjs roadmap update-plan-progress <N>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 配置命令
|
||||
|
||||
读写 `.planning/config.json`。
|
||||
|
||||
```bash
|
||||
# 以默认值初始化 config.json
|
||||
node gsd-tools.cjs config-ensure-section
|
||||
|
||||
# 设置配置值（点号表示法）
|
||||
node gsd-tools.cjs config-set <key> <value>
|
||||
|
||||
# 获取配置值
|
||||
node gsd-tools.cjs config-get <key>
|
||||
|
||||
# 设置模型配置文件
|
||||
node gsd-tools.cjs config-set-model-profile <profile>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模型解析
|
||||
|
||||
```bash
|
||||
# 根据当前配置文件获取代理使用的模型
|
||||
node gsd-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`
|
||||
|
||||
---
|
||||
|
||||
## 验证命令
|
||||
|
||||
验证计划、阶段、引用和提交。
|
||||
|
||||
```bash
|
||||
# 验证 SUMMARY.md 文件
|
||||
node gsd-tools.cjs verify-summary <path> [--check-count N]
|
||||
|
||||
# 检查 PLAN.md 结构和任务
|
||||
node gsd-tools.cjs verify plan-structure <file>
|
||||
|
||||
# 检查所有计划是否有摘要
|
||||
node gsd-tools.cjs verify phase-completeness <phase>
|
||||
|
||||
# 检查 @-引用和路径是否可解析
|
||||
node gsd-tools.cjs verify references <file>
|
||||
|
||||
# 批量验证提交哈希
|
||||
node gsd-tools.cjs verify commits <hash1> [hash2] ...
|
||||
|
||||
# 检查 must_haves.artifacts
|
||||
node gsd-tools.cjs verify artifacts <plan-file>
|
||||
|
||||
# 检查 must_haves.key_links
|
||||
node gsd-tools.cjs verify key-links <plan-file>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 校验命令
|
||||
|
||||
检查项目完整性。
|
||||
|
||||
```bash
|
||||
# 检查阶段编号、磁盘/路线图同步
|
||||
node gsd-tools.cjs validate consistency
|
||||
|
||||
# 检查 .planning/ 完整性，可选修复
|
||||
node gsd-tools.cjs validate health [--repair]
|
||||
|
||||
# 探测上下文窗口利用率（用于状态行/钩子调用方）（v1.40.0）
|
||||
node gsd-tools.cjs validate context
|
||||
|
||||
# 以类型化 JSON 接口输出上下文利用率（#455）
|
||||
node gsd-tools.cjs validate context --json
|
||||
```
|
||||
|
||||
`validate context` 输出包含 `utilization`、`status`（在 60% / 70% 阈值处分别为 `ok` / `warn` / `critical`）以及 `suggestion` 字符串的结构化信封。相同数据支撑 `/gsd-health --context`。
|
||||
传入 `--json` 可直接接收类型化中间表示（适用于脚本和测试断言）。
|
||||
|
||||
---
|
||||
|
||||
## 模板命令
|
||||
|
||||
模板选择与填充。
|
||||
|
||||
```bash
|
||||
# 根据粒度选择摘要模板
|
||||
node gsd-tools.cjs template select <type>
|
||||
|
||||
# 用变量填充模板
|
||||
node gsd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']
|
||||
```
|
||||
|
||||
`fill` 的模板类型：`summary`、`plan`、`verification`
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter 命令
|
||||
|
||||
对任意 Markdown 文件执行 YAML frontmatter 的增删改查。
|
||||
|
||||
```bash
|
||||
# 以 JSON 格式提取 frontmatter
|
||||
node gsd-tools.cjs frontmatter get <file> [--field key]
|
||||
|
||||
# 更新单个字段
|
||||
node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal
|
||||
|
||||
# 将 JSON 合并到 frontmatter
|
||||
node gsd-tools.cjs frontmatter merge <file> --data '{json}'
|
||||
|
||||
# 验证必填字段
|
||||
node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verification
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 脚手架命令
|
||||
|
||||
创建预结构化文件和目录。
|
||||
|
||||
```bash
|
||||
# 创建 CONTEXT.md 模板
|
||||
node gsd-tools.cjs scaffold context --phase N
|
||||
|
||||
# 创建 UAT.md 模板
|
||||
node gsd-tools.cjs scaffold uat --phase N
|
||||
|
||||
# 创建 VERIFICATION.md 模板
|
||||
node gsd-tools.cjs scaffold verification --phase N
|
||||
|
||||
# 创建阶段目录
|
||||
node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Init 命令（复合上下文加载）
|
||||
|
||||
通过单次调用加载特定工作流所需的所有上下文。返回包含项目信息、配置、状态和工作流专属数据的 JSON。
|
||||
|
||||
```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 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
|
||||
|
||||
# 工作流范围的 init（`--ws` 标志）
|
||||
node gsd-tools.cjs init execute-phase <phase> --ws <name>
|
||||
node gsd-tools.cjs init plan-phase <phase> --ws <name>
|
||||
```
|
||||
|
||||
**大载荷处理：** 当输出超过约 50KB 时，CLI 会将内容写入临时文件并返回 `@file:/tmp/gsd-init-XXXXX.json`。工作流检查 `@file:` 前缀并从磁盘读取：
|
||||
|
||||
```bash
|
||||
INIT=$(node gsd-tools.cjs init execute-phase "1")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 里程碑命令
|
||||
|
||||
```bash
|
||||
# 归档里程碑
|
||||
node gsd-tools.cjs milestone complete <version> [--name <name>] [--archive-phases]
|
||||
|
||||
# 将需求标记为完成
|
||||
node gsd-tools.cjs requirements mark-complete <ids>
|
||||
# 接受格式：REQ-01,REQ-02 或 REQ-01 REQ-02 或 [REQ-01, REQ-02]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 代理技能
|
||||
|
||||
输出指定代理类型的技能块。
|
||||
|
||||
```bash
|
||||
# 输出原始 XML 技能块（默认——适合 shell 展开）
|
||||
node gsd-tools.cjs agent-skills <agent-type>
|
||||
|
||||
# 输出类型化 JSON 接口（#455）——{ agent_type, block, skills_count }
|
||||
node gsd-tools.cjs agent-skills <agent-type> --json
|
||||
```
|
||||
|
||||
`--json` 标志返回适合结构化消费和测试断言的类型化中间表示对象，而默认（无标志）保留工作流 shell 展开所依赖的原始 XML 输出。
|
||||
|
||||
---
|
||||
|
||||
## 技能清单
|
||||
|
||||
预计算并缓存技能发现结果，以加快命令加载速度。
|
||||
|
||||
```bash
|
||||
# 生成技能清单（写入 .claude/skill-manifest.json）
|
||||
node gsd-tools.cjs skill-manifest
|
||||
|
||||
# 生成并指定自定义输出路径
|
||||
node gsd-tools.cjs skill-manifest --output <path>
|
||||
```
|
||||
|
||||
返回所有可用 GSD 技能的 JSON 映射，包含其元数据（名称、描述、文件路径、参数提示）。由安装程序和会话启动钩子使用，以避免重复的文件系统扫描。
|
||||
|
||||
---
|
||||
|
||||
## 工具命令
|
||||
|
||||
```bash
|
||||
# 将文本转换为 URL 安全的 slug
|
||||
node gsd-tools.cjs generate-slug "Some Text Here"
|
||||
# → some-text-here
|
||||
|
||||
# 获取时间戳
|
||||
node gsd-tools.cjs current-timestamp [full|date|filename]
|
||||
|
||||
# 统计并列出待办事项
|
||||
node gsd-tools.cjs list-todos [area]
|
||||
|
||||
# 检查文件/目录是否存在
|
||||
node gsd-tools.cjs verify-path-exists <path>
|
||||
|
||||
# 聚合所有 SUMMARY.md 数据
|
||||
node gsd-tools.cjs history-digest
|
||||
|
||||
# 从 SUMMARY.md 提取结构化数据
|
||||
node gsd-tools.cjs summary-extract <path> [--fields field1,field2]
|
||||
|
||||
# 项目统计
|
||||
node gsd-tools.cjs stats [json|table]
|
||||
|
||||
# 进度渲染（人类可读）
|
||||
node gsd-tools.cjs progress [json|table|bar]
|
||||
|
||||
# 以类型化 JSON 接口输出进度（#455）
|
||||
node gsd-tools.cjs progress --json
|
||||
|
||||
# 完成待办事项
|
||||
node gsd-tools.cjs todo complete <filename>
|
||||
|
||||
# UAT 审计——扫描所有阶段的未解决事项
|
||||
node gsd-tools.cjs audit-uat
|
||||
|
||||
# 跨制品审计队列——扫描 `.planning/` 中未解决的审计事项
|
||||
node gsd-tools.cjs audit-open [--json]
|
||||
|
||||
# 将 GSD-2 项目反向迁移到当前结构（支撑 `/gsd-import --from-gsd2`）
|
||||
node gsd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
|
||||
|
||||
# 带配置检查的 Git 提交
|
||||
node gsd-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]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Graphify
|
||||
|
||||
在 `.planning/graphs/` 中构建、查询和检查项目知识图谱。需要在 `config.json` 中设置 `graphify.enabled: true`（参见[配置参考](CONFIGURATION.md#graphify-settings)）。
|
||||
|
||||
```bash
|
||||
# 构建或重建知识图谱
|
||||
node gsd-tools.cjs graphify build
|
||||
|
||||
# 在图谱中搜索某个词
|
||||
node gsd-tools.cjs graphify query <term>
|
||||
|
||||
# 显示图谱新鲜度和统计数据
|
||||
node gsd-tools.cjs graphify status
|
||||
|
||||
# 显示自上次构建以来的变更
|
||||
node gsd-tools.cjs graphify diff
|
||||
|
||||
# 写入当前图谱的命名快照
|
||||
node gsd-tools.cjs graphify snapshot [name]
|
||||
```
|
||||
|
||||
用户入口：`/gsd-graphify`（参见[命令参考](COMMANDS.md#gsd-graphify)）。
|
||||
|
||||
---
|
||||
|
||||
## 模块架构
|
||||
|
||||
| 模块 | 文件 | 导出 |
|
||||
|--------|------|---------|
|
||||
| 核心 | `lib/core.cjs` | `error()`、`output()`、`parseArgs()`、共享工具、兼容性重导出 |
|
||||
| 状态 | `lib/state.cjs` | 所有 `state` 子命令、`state-snapshot` |
|
||||
| 阶段 | `lib/phase.cjs` | 阶段增删改查、`find-phase`、`phase-plan-index`、`phases list` |
|
||||
| 规划工作区 | `lib/planning-workspace.cjs` | 规划接缝：`planningDir`、`planningPaths`、活跃工作流路由、`.planning/.lock` |
|
||||
| 路线图 | `lib/roadmap.cjs` | 路线图解析、阶段提取、进度更新 |
|
||||
| 配置 | `lib/config.cjs` | 配置读写、章节初始化 |
|
||||
| 验证 | `lib/verify.cjs` | 所有验证和校验命令 |
|
||||
| 模板 | `lib/template.cjs` | 模板选择和变量填充 |
|
||||
| Frontmatter | `lib/frontmatter.cjs` | YAML frontmatter 增删改查 |
|
||||
| Init | `lib/init.cjs` | 所有工作流的复合上下文加载 |
|
||||
| 里程碑 | `lib/milestone.cjs` | 里程碑归档、需求标记 |
|
||||
| 命令 | `lib/commands.cjs` | 杂项：slug、时间戳、待办事项、脚手架、统计、网页搜索 |
|
||||
| 模型配置文件 | `lib/model-profiles.cjs` | 配置文件解析表 |
|
||||
| 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`） |
|
||||
| 审计 | `lib/audit.cjs` | 阶段/里程碑审计队列处理器；`audit-open` 助手 |
|
||||
| GSD2 导入 | `lib/gsd2-import.cjs` | 从 GSD-2 项目反向迁移导入（支撑 `/gsd-import --from-gsd2`） |
|
||||
| Intel | `lib/intel.cjs` | 可查询的代码库智能索引（支撑 `/gsd-map-codebase --query`） |
|
||||
|
||||
---
|
||||
|
||||
## 审阅器 CLI 路由
|
||||
|
||||
`review.models.<cli>` 将审阅器类型映射到代码审查工作流调用的 shell 命令。通过 [`/gsd-config --integrations`](COMMANDS.md#gsd-config) 或直接设置：
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs config-set review.models.codex "codex exec --model gpt-5"
|
||||
node gsd-tools.cjs config-set review.models.gemini "gemini -m gemini-2.5-pro"
|
||||
node gsd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
|
||||
node gsd-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>`）。遮蔽实现请参见 `get-shit-done/bin/lib/secrets.cjs`。`config.json` 文件本身是安全边界——请通过文件系统权限保护它，并将其排除在 git 之外（`.planning/` 默认已被 gitignore）。
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [命令](COMMANDS.md)
|
||||
- [配置](CONFIGURATION.md)
|
||||
- [架构](ARCHITECTURE.md)
|
||||
- [文档索引](README.md)
|
||||
1521
docs/zh-CN/COMMANDS.md
Normal file
1521
docs/zh-CN/COMMANDS.md
Normal file
File diff suppressed because it is too large
Load Diff
1333
docs/zh-CN/CONFIGURATION.md
Normal file
1333
docs/zh-CN/CONFIGURATION.md
Normal file
File diff suppressed because it is too large
Load Diff
3006
docs/zh-CN/FEATURES.md
Normal file
3006
docs/zh-CN/FEATURES.md
Normal file
File diff suppressed because it is too large
Load Diff
493
docs/zh-CN/INVENTORY.md
Normal file
493
docs/zh-CN/INVENTORY.md
Normal file
@@ -0,0 +1,493 @@
|
||||
# GSD 已发布功能清单
|
||||
|
||||
> 所有已发布 GSD 功能面的权威目录：命令、代理、工作流、参考资料、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` 等命令。
|
||||
- 本文件列举了所有六大类别（代理、命令、工作流、参考资料、CLI 模块、钩子）中的每个已发布功能面。广义文档可能呈现叙述性内容或精选子集；当其与文件系统不一致时，本文件及目录清单为准。
|
||||
- v1.36.0 之后新增的功能面应首先在此处记录，再传播到广义文档中。`tests/inventory-counts.test.cjs`、`tests/commands-doc-parity.test.cjs`、`tests/agents-doc-parity.test.cjs`、`tests/cli-modules-doc-parity.test.cjs`、`tests/hooks-doc-parity.test.cjs`、`tests/architecture-counts.test.cjs` 和 `tests/command-count-sync.test.cjs` 中的漂移控制测试将数量和清单内容锚定到文件系统。
|
||||
|
||||
这是所有已发布 GSD Core 功能面的权威目录。请参阅 [文档索引](README.md) 按主题导航。
|
||||
|
||||
---
|
||||
|
||||
## 代理 (33 shipped)
|
||||
|
||||
完整清单位于 `agents/gsd-*.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 |
|
||||
|
||||
**覆盖说明。** `docs/AGENTS.md` 为 21 个主要代理提供了完整角色卡，并为 12 个高级代理提供了简洁存根。该文件中的代理工具权限摘要仅涵盖主要的 21 个代理；高级代理的工具列表记录在 `agents/gsd-*.md` 中各代理的 frontmatter 里。
|
||||
|
||||
---
|
||||
|
||||
## 命令 (67 shipped)
|
||||
|
||||
完整清单位于 `commands/gsd/*.md`。以下分组与 `docs/COMMANDS.md` 的章节顺序一致；每行包含命令名称、从命令 frontmatter `description:` 派生的一行角色描述，以及源文件链接。`tests/command-count-sync.test.cjs` 将数量锁定到文件系统。
|
||||
|
||||
### 命名空间元技能
|
||||
|
||||
以下六个路由器是仅包含描述符的条目，模型优先选择这些条目；每个条目的主体包含一个路由表，指向正确的具体子技能。它们的存在是为了在完整功能面仍可访问的情况下降低急切技能列举的令牌成本。请参阅 [#2792](https://github.com/open-gsd/gsd-core/issues/2792) 了解原因；路由表指向 [#2790](https://github.com/open-gsd/gsd-core/issues/2790) 合并后的功能面。
|
||||
|
||||
| 命令 | 角色 | 源文件 |
|
||||
|------|------|--------|
|
||||
| `/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) |
|
||||
|
||||
### 核心工作流
|
||||
|
||||
| 命令 | 角色 | 源文件 |
|
||||
|------|------|--------|
|
||||
| `/gsd-new-project` | 通过深度上下文收集和 PROJECT.md 初始化新项目。 | [commands/gsd/new-project.md](../../commands/gsd/new-project.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) |
|
||||
|
||||
### 阶段与里程碑管理
|
||||
|
||||
| 命令 | 角色 | 源文件 |
|
||||
|------|------|--------|
|
||||
| `/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) |
|
||||
|
||||
### 会话与导航
|
||||
|
||||
| 命令 | 角色 | 源文件 |
|
||||
|------|------|--------|
|
||||
| `/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) |
|
||||
|
||||
### 代码库智能
|
||||
|
||||
| 命令 | 角色 | 源文件 |
|
||||
|------|------|--------|
|
||||
| `/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) |
|
||||
|
||||
### 审查、调试与恢复
|
||||
|
||||
| 命令 | 角色 | 源文件 |
|
||||
|------|------|--------|
|
||||
| `/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) |
|
||||
|
||||
### 文档、用户档案与实用工具
|
||||
|
||||
| 命令 | 角色 | 源文件 |
|
||||
|------|------|--------|
|
||||
| `/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) |
|
||||
|
||||
---
|
||||
|
||||
## 工作流 (88 shipped)
|
||||
|
||||
完整清单位于 `get-shit-done/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`（自动诊断） |
|
||||
| `discovery-phase.md` | 以适当的深度级别执行发现。 | `/gsd-new-project`（发现路径） |
|
||||
| `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` |
|
||||
| `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` |
|
||||
| `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` |
|
||||
| `new-workspace.md` | 创建带有仓库 worktree/克隆和独立 `.planning/` 的隔离工作区。 | `/gsd-workspace --new` |
|
||||
| `next.md` | 检测当前项目状态并自动推进到下一个逻辑步骤。 | `/gsd-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-phase.md` | 通过目标反向分析验证阶段目标的达成情况。 | `execute-phase.md`（执行后） |
|
||||
| `verify-work.md` | 带自动诊断的对话式 UAT — 生成 UAT.md 和修复计划。 | `/gsd-verify-work` |
|
||||
|
||||
> **注意：** 某些工作流没有直接面向用户的命令（例如 `execute-plan.md`、`verify-phase.md`、`transition.md`、`node-repair.md`、`diagnose-issues.md`）— 它们由编排器工作流在内部调用。`discovery-phase.md` 是 `/gsd-new-project` 的备用入口。
|
||||
|
||||
---
|
||||
|
||||
## 参考资料 (62 shipped)
|
||||
|
||||
完整清单位于 `get-shit-done/references/*.md`。参考资料是工作流和代理 `@-reference` 的共享知识文档。以下分组与 [`docs/ARCHITECTURE.md`](ARCHITECTURE.md#references-get-shit-donereferencesmd) 一致 — 核心、工作流、思维模型集群和模块化规划器分解。
|
||||
|
||||
### 核心参考资料
|
||||
|
||||
| 参考资料 | 角色 |
|
||||
|----------|------|
|
||||
| `checkpoints.md` | 检查点类型定义和交互模式。 |
|
||||
| `gates.md` | 4 种规范关卡类型（Confirm、Quality、Safety、Transition），已连接到 plan-checker 和 verifier。 |
|
||||
| `model-profiles.md` | 每个代理的模型层级分配。 |
|
||||
| `model-profile-resolution.md` | 模型解析算法文档。 |
|
||||
| `verification-patterns.md` | 如何验证不同的产物类型。 |
|
||||
| `verification-overrides.md` | 每种产物的验证覆盖规则。 |
|
||||
| `planning-config.md` | 完整的配置模式和行为。 |
|
||||
| `git-integration.md` | Git 提交、分支和历史模式。 |
|
||||
| `git-planning-commit.md` | 规划目录提交约定。 |
|
||||
| `questioning.md` | 项目初始化的梦想提取哲学。 |
|
||||
| `tdd.md` | 测试驱动开发集成模式。 |
|
||||
| `ui-brand.md` | 视觉输出格式模式。 |
|
||||
| `common-bug-patterns.md` | 代码审查和验证的常见缺陷模式。 |
|
||||
| `debugger-philosophy.md` | 由 `gsd-debugger` 加载的长青调试准则。 |
|
||||
| `mandatory-initial-read.md` | 注入到代理提示中的共享必读样板文本。 |
|
||||
| `project-skills-discovery.md` | 注入到代理提示中的共享项目技能发现样板文本。 |
|
||||
|
||||
### 工作流参考资料
|
||||
|
||||
| 参考资料 | 角色 |
|
||||
|----------|------|
|
||||
| `agent-contracts.md` | 编排器与代理之间的正式接口。 |
|
||||
| `context-budget.md` | 上下文窗口预算分配规则。 |
|
||||
| `continuation-format.md` | 会话续传/恢复格式。 |
|
||||
| `domain-probes.md` | discuss-phase 的领域特定探究问题。 |
|
||||
| `gate-prompts.md` | 关卡/检查点提示模板。 |
|
||||
| `scout-codebase.md` | discuss-phase 侦察步骤的阶段类型→代码库映射选择表（通过 #2551 提取）。 |
|
||||
| `revision-loop.md` | 计划修订迭代模式。 |
|
||||
| `universal-anti-patterns.md` | 需要检测和避免的通用反模式。 |
|
||||
| `worktree-path-safety.md` | Worktree 守卫套件：HEAD 断言、cwd 漂移哨兵（步骤 0a，#3097）和绝对路径守卫（步骤 0b，#3099）— 通过 `<execution_context>` 加载到执行器生成提示中。 |
|
||||
| `artifact-types.md` | 规划产物类型定义。 |
|
||||
| `phase-argument-parsing.md` | 阶段参数解析约定。 |
|
||||
| `decimal-phase-calculation.md` | 十进制子阶段编号规则。 |
|
||||
| `workstream-flag.md` | 工作流活跃指针约定（`--ws`）。 |
|
||||
| `user-profiling.md` | 用户行为档案检测启发式方法。 |
|
||||
| `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 代理的已完成示例。 |
|
||||
| `doc-conflict-engine.md` | 摄取/导入工作流的共享冲突检测契约。 |
|
||||
| `execute-mvp-tdd.md` | MVP+TDD 模式下 execute-phase 的运行时关卡语义 — 任务前失败测试验证、阶段结束阻塞性审查。 |
|
||||
| `mvp-concepts.md` | 六个 MVP 相关参考文件的交叉引用索引；将每个文件映射到其目的和加载它的工作流。 |
|
||||
| `verify-mvp-mode.md` | MVP 模式阶段的 UAT 框架规则 — 用户流程优先排序、延迟技术检查、用户故事格式守卫。 |
|
||||
|
||||
### 草图参考资料
|
||||
|
||||
`/gsd-sketch` 工作流及其收尾配套使用的参考资料。
|
||||
|
||||
| 参考资料 | 角色 |
|
||||
|----------|------|
|
||||
| `sketch-interactivity.md` | 使 HTML 草图感觉交互性强且富有活力的规则。 |
|
||||
| `sketch-theme-system.md` | 用于跨草图一致性的共享 CSS 主题变量系统。 |
|
||||
| `sketch-tooling.md` | 每个草图中包含的浮动工具栏实用工具。 |
|
||||
| `sketch-variant-patterns.md` | 多变体 HTML 模式（标签页、并排、叠加层）。 |
|
||||
|
||||
### 思维模型参考资料
|
||||
|
||||
将思维类模型（o3、o4-mini、Gemini 2.5 Pro）集成到 GSD 工作流中的参考资料。
|
||||
|
||||
| 参考资料 | 角色 |
|
||||
|----------|------|
|
||||
| `thinking-models-debug.md` | 用于调试工作流的思维模型模式。 |
|
||||
| `thinking-models-execution.md` | 用于执行代理的思维模型模式。 |
|
||||
| `thinking-models-planning.md` | 用于规划代理的思维模型模式。 |
|
||||
| `thinking-models-research.md` | 用于研究代理的思维模型模式。 |
|
||||
| `thinking-models-verification.md` | 用于验证代理的思维模型模式。 |
|
||||
|
||||
### 模块化规划器分解
|
||||
|
||||
`gsd-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-revision.md` | 迭代细化的计划修订模式。 |
|
||||
| `planner-source-audit.md` | 规划器源代码审计和权限限制规则。 |
|
||||
| `planner-mvp-mode.md` | MVP 模式的垂直切片规划规则。 |
|
||||
| `planner-human-verify-mode.md` | `workflow.human_verify_mode = end-of-phase` 的规则：抑制 `checkpoint:human-verify` 任务发射，并通过 `<verify><human-check>` 路由延迟的项目。 |
|
||||
| `planner-graphify-auto-update.md` | `load_graph_context` 如何在现有陈旧性注释旁边显示 `.last-build-status.json` 自动更新状态（运行中/失败/陈旧头部）。通过 `graphify.auto_update` 选择启用（#3347）。 |
|
||||
| `planner-interface-context.md` | 执行器的接口上下文规则 — 如何从现有代码中提取关键接口/类型/导出，并记录下游计划将使用的新接口。 |
|
||||
| `skeleton-template.md` | 为新项目行走骨架（阶段 1 + `--mvp`）生成的 SKELETON.md 模板。 |
|
||||
| `user-story-template.md` | MVP 规划的用户故事格式 — "作为 / 我想要 / 以便" 结构化字段。 |
|
||||
| `spidr-splitting.md` | 用于在 MVP 模式下处理大型用户故事的 SPIDR 拆分分解规则。 |
|
||||
|
||||
> **子目录：** `get-shit-done/references/few-shot-examples/` 包含额外的少样本示例（`plan-checker.md`、`verifier.md`），这些示例从特定代理中引用。它们不计入 62 个顶级参考资料。
|
||||
|
||||
---
|
||||
|
||||
## CLI 模块 (81 shipped)
|
||||
|
||||
完整清单：`get-shit-done/bin/lib/*.cjs`。
|
||||
|
||||
| 模块 | 职责 |
|
||||
|------|------|
|
||||
| `active-workstream-store.cjs` | 工作流来源优先级和选择（CLI `--ws` > `GSD_WORKSTREAM` 环境变量 > 存储的指针）；名称验证和环境传播 |
|
||||
| `adr-parser.cjs` | 用于 plan-phase 摄取快速路径的 ADR 决策解析器；规范化章节同义词，解析状态/决策/范围围栏，并强制执行状态拒绝关卡 |
|
||||
| `agent-command-router.cjs` | `gsd-tools agent` 的轻量 CJS 子命令路由适配器 |
|
||||
| `artifacts.cjs` | 规范产物注册表 — 已知的 `.planning/` 根文件名；被 `gsd-health` W019 lint 使用 |
|
||||
| `audit.cjs` | 审计分发、审计开放会话、审计存储帮助器 |
|
||||
| `check-command-router.cjs` | `gsd-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` 路由的规范分发接缝 |
|
||||
| `command-aliases.cjs` | 清单支持的族路由器的别名/子命令元数据 |
|
||||
| `command-arg-projection.cjs` | 跨命令族路由器共享的类型化标志和位置参数投影帮助器 |
|
||||
| `command-routing-hub.cjs` | 纯结果分发中心，集中了所有命令族路由器的模式决策（SDK vs CJS）、错误分类和无抛出契约（#3788） |
|
||||
| `commands.cjs` | 杂项 CLI 命令（slug、时间戳、todo、脚手架、统计信息） |
|
||||
| `config-schema.cjs` | `VALID_CONFIG_KEYS` 和动态键模式的单一真实来源；由验证器和 config-schema-docs 奇偶性测试导入 |
|
||||
| `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） |
|
||||
| `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 审计适配器：二进制解析（`PATH` 然后 `node_modules/.bin`）、可操作的缺少二进制错误和结构性发现规范化 |
|
||||
| `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 子命令路由适配器 |
|
||||
| `init.cjs` | 每种工作流类型的复合上下文加载 |
|
||||
| `install-profiles.cjs` | `--minimal` 安装的安装配置文件允许列表和技能暂存（#2762）；哪些 `gsd-*` 技能/代理落入运行时配置目录的单一真实来源 |
|
||||
| `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` 的跨阶段学习提取 |
|
||||
| `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 子命令路由适配器 |
|
||||
| `phase-lifecycle.cjs` | 从 phase-lifecycle SDK 处理程序中提取的纯计算阶段生命周期帮助器 |
|
||||
| `phase.cjs` | 阶段目录操作、十进制编号、计划索引 |
|
||||
| `phases-command-router.cjs` | `gsd-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 子命令路由适配器 |
|
||||
| `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） |
|
||||
| `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.cjs` | STATE.md 解析、更新、进度推进、指标 |
|
||||
| `state-document.cjs` | 纯 STATE.md 字段提取、替换、状态规范化和进度计算转换 |
|
||||
| `surface.cjs` | 运行时 surface 模块 — 独立于安装时配置文件标记管理运行时启用/禁用 surface 状态（ADR-0011 阶段 2） |
|
||||
| `task-command-router.cjs` | `gsd-tools task` 的轻量 CJS 子命令路由适配器 |
|
||||
| `template.cjs` | 带变量替换的模板选择和填充 |
|
||||
| `uat.cjs` | UAT 文件解析、验证债务跟踪、audit-uat 支持 |
|
||||
| `ui-safety-gate.cjs` | 无 shell 的词边界 UI 令牌检测器（#3706，#3718）；从 stdin 读取阶段章节文本，退出 0（找到 UI）或 1（未找到 UI）；也部署到 `get-shit-done/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 子命令路由适配器 |
|
||||
| `validate.cjs` | 纯阶段变体规范化帮助器（`phaseVariants`、`buildRoadmapPhaseVariants`、`buildNotStartedPhaseVariants`），被 `verify.cjs` 用于 W006/W007 检查；无 I/O，无异步 |
|
||||
| `verify-command-router.cjs` | `gsd-tools verify` 的轻量 CJS 子命令路由适配器 |
|
||||
| `verify.cjs` | 计划结构、阶段完整性、参考、提交验证 |
|
||||
| `workstream-inventory-builder.cjs` | 纯工作流清单投影构建器 |
|
||||
| `workstream-inventory.cjs` | 共享工作流清单投影：状态字段、阶段/计划/摘要计数、路线图阶段计数和活跃标记 — 将纯投影委托给 `workstream-inventory-builder.cjs` 的轻量编排器 |
|
||||
| `workstream-name-policy.cjs` | 规范的工作流名称验证（`isValidActiveWorkstreamName`、`hasInvalidPathSegment`、`validateWorkstreamName`）和 slug 规范化（`toWorkstreamSlug`） |
|
||||
| `workstream.cjs` | 工作流增删改查、迁移、会话作用域活跃指针 |
|
||||
| `worktree-safety.cjs` | Worktree 根目录解析和非破坏性清理策略决策；拥有 W017 健康检查逻辑 |
|
||||
|
||||
[`docs/CLI-TOOLS.md`](CLI-TOOLS.md) 可能描述这些模块的子集；当其与文件系统不一致时，本表和目录清单为准。
|
||||
|
||||
---
|
||||
|
||||
## 钩子 (14 shipped)
|
||||
|
||||
完整清单：`hooks/`。
|
||||
|
||||
| 钩子 | 事件 | 目的 |
|
||||
|------|------|------|
|
||||
| `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-session-state.sh` | `PostToolUse` | 基于 shell 运行时的会话状态跟踪 |
|
||||
| `gsd-validate-commit.sh` | `PostToolUse` | 常规提交强制执行的提交验证 |
|
||||
| `gsd-phase-boundary.sh` | `PostToolUse` | 工作流过渡的阶段边界检测 |
|
||||
| `gsd-graphify-update.sh` | `PostToolUse` | 在主 HEAD 推进后自动重建知识图谱（可选启用，默认关闭 — #3347） |
|
||||
|
||||
---
|
||||
|
||||
## 维护
|
||||
|
||||
- 当新的命令、代理、工作流、参考资料、CLI 模块或钩子发布时，请在发布前更新此处对应的章节。
|
||||
- `tests/` 下的漂移守卫测试（参见上方的"使用说明"）断言每个已发布文件都在此清单中列举。未在此处有对应行的新文件将导致 CI 失败。
|
||||
- 当文件系统与 `docs/ARCHITECTURE.md` 的数量或精选子集文档（例如 `docs/AGENTS.md` 的主要名册）不一致时，本文件为准。
|
||||
|
||||
## 相关资料
|
||||
|
||||
- [命令](COMMANDS.md) — 面向用户的命令参考
|
||||
- [架构](ARCHITECTURE.md) — 功能面如何协同工作
|
||||
- [文档索引](README.md)
|
||||
@@ -1,729 +1,69 @@
|
||||
<div align="center">
|
||||
# GSD Core 文档
|
||||
|
||||
# GSD Core
|
||||
文档按四个象限组织：**教程**通过实践帮助你学习，**操作指南**解决具体任务，**参考文档**提供权威信息，**概念说明**探讨设计理念与决策。
|
||||
|
||||
**Git. Ship. Done.**
|
||||
|
||||
**一个轻量级且强大的元提示、上下文工程和规格驱动开发系统，支持 Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae 和 Cline。**
|
||||
|
||||
**解决上下文衰减 —— 即 Claude 填充上下文窗口时发生的质量退化问题。**
|
||||
|
||||
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
||||
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
||||
[](https://github.com/open-gsd/gsd-core/actions/workflows/test.yml)
|
||||
[](https://discord.gg/mYgfVNfA2r)
|
||||
[](https://x.com/gsd_foundation)
|
||||
[](https://dexscreener.com/solana/dwudwjvan7bzkw9zwlbyv6kspdlvhwzrqy6ebk8xzxkv)
|
||||
[](https://github.com/open-gsd/gsd-core)
|
||||
[](LICENSE)
|
||||
|
||||
<br>
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest
|
||||
```
|
||||
|
||||
**支持 Mac、Windows 和 Linux。**
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
<br>
|
||||
|
||||
*"如果你清楚自己想要什么，它真的会帮你构建出来。不忽悠。"*
|
||||
|
||||
*"我试过 SpecKit、OpenSpec 和 Taskmaster —— 这是我用过的效果最好的。"*
|
||||
|
||||
*"这是我用过的 Claude Code 最强大的扩展。没有过度设计。真的就是把事情做完。"*
|
||||
|
||||
<br>
|
||||
|
||||
**被 Amazon、Google、Shopify 和 Webflow 的工程师信赖使用。**
|
||||
|
||||
[我为什么开发这个](#我为什么开发这个) · [工作原理](#工作原理) · [命令](#命令) · [为什么有效](#为什么有效) · [用户指南](USER-GUIDE.md)
|
||||
|
||||
</div>
|
||||
语言版本：[English](../README.md) · [Português (pt-BR)](../pt-BR/README.md) · [日本語](../ja-JP/README.md) · [简体中文](README.md)
|
||||
|
||||
---
|
||||
|
||||
## 我为什么开发这个
|
||||
## Tutorials
|
||||
|
||||
我是一名独立开发者。我不写代码 —— Claude Code 写。
|
||||
|
||||
其他规格驱动开发工具确实存在，比如 BMAD、Speckit... 但它们似乎都把事情搞得比实际需要的复杂得多（冲刺会议、故事点、干系人同步、回顾、Jira 工作流），或者缺乏对你正在构建的东西的真正大局理解。我不是一个 50 人的软件公司。我不想搞企业级表演。我只是个想构建出好用的东西的创意人。
|
||||
|
||||
所以我开发了 GSD。复杂性在系统内部，不在你的工作流里。幕后是：上下文工程、XML 提示格式、子代理编排、状态管理。你看到的是：几个命令，用就完了。
|
||||
|
||||
系统给 Claude 提供了它完成工作**以及**验证工作所需的一切。我信任这个工作流。它就是做得好。
|
||||
|
||||
这就是它的本质。没有企业级角色扮演的废话。只是一个让 Claude Code 稳定可靠地构建酷东西的极其有效的系统。
|
||||
|
||||
— **TÂCHES**
|
||||
- [第一个项目](tutorials/your-first-project.md) — 从安装到首个已交付阶段，一条有保障的路径
|
||||
- [接入现有代码库](tutorials/onboarding-an-existing-codebase.md) — 将 GSD Core 引入已有项目的代码库
|
||||
|
||||
---
|
||||
|
||||
Vibecoding 名声不好。你描述想要什么，AI 生成代码，结果得到不一致的垃圾，规模一大就崩。
|
||||
## How-to guides
|
||||
|
||||
GSD 解决了这个问题。它是让 Claude Code 变得可靠的上下文工程层。描述你的想法，让系统提取它需要知道的一切，然后让 Claude Code 开始工作。
|
||||
- [在你的运行时上安装](how-to/install-on-your-runtime.md) — 适用于全部 15 个受支持运行时的安装步骤
|
||||
- [讨论一个阶段](how-to/discuss-a-phase.md) — 在规划开始前记录实现决策
|
||||
- [规划一个阶段](how-to/plan-a-phase.md) — 执行调研、分解工作并验证计划质量
|
||||
- [执行一个阶段](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/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` 进行探索性工作
|
||||
- [设计 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) — 重新运行安装程序以获取最新版本
|
||||
- [恢复与故障排查](how-to/recover-and-troubleshoot.md) — 修复常见问题、重建上下文并卸载
|
||||
|
||||
---
|
||||
|
||||
## 这个工具适合谁
|
||||
## Reference
|
||||
|
||||
想要描述需求然后正确构建出来的人 —— 不用假装自己在运营一个 50 人的工程组织。
|
||||
|
||||
内置的质量门禁能捕获真正的问题：模式漂移检测会标记缺少迁移的 ORM 变更，安全强制将验证锚定到威胁模型，范围缩减检测防止规划器默默丢弃你的需求。
|
||||
- [命令](COMMANDS.md) — 每个命令的标志和示例
|
||||
- [配置](CONFIGURATION.md) — 完整配置模式、模型配置文件、Git 分支策略
|
||||
- [CLI 工具](CLI-TOOLS.md) — `gsd-tools.cjs` 用于工作流和代理的编程式 API
|
||||
- [功能特性](FEATURES.md) — 完整功能索引
|
||||
- [清单](INVENTORY.md) — 已安装的技能与界面映射
|
||||
- [STATE.md 模式](reference/state-md.md) — `.planning/STATE.md` 的逐字段参考
|
||||
- [CONTEXT.md 模式](reference/context-md.md) — `.planning/phases/<N>/CONTEXT.md` 的逐字段参考
|
||||
- [PLAN.md 模式](reference/plan-md.md) — `.planning/phases/<N>/PLAN.md` 的逐字段参考
|
||||
- [规划产物](reference/planning-artifacts.md) — 所有 `.planning/` 文件及其作用
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
## Explanation
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest
|
||||
```
|
||||
|
||||
安装程序会提示你选择：
|
||||
1. **运行时** —— Claude Code、OpenCode、Gemini、Kilo、Codex 或全部
|
||||
2. **位置** —— 全局（所有项目）或本地（仅当前项目）
|
||||
|
||||
验证安装：
|
||||
- Claude Code / Gemini: `/gsd-help`
|
||||
- OpenCode: `/gsd-help`
|
||||
- Kilo: `/gsd-help`
|
||||
- Codex: `$gsd-help`
|
||||
|
||||
> [!NOTE]
|
||||
> Codex 安装使用技能（`skills/gsd-*/SKILL.md`）而非自定义提示。
|
||||
|
||||
### 保持更新
|
||||
|
||||
GSD 快速迭代。定期更新：
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary><strong>非交互式安装（Docker、CI、脚本）</strong></summary>
|
||||
|
||||
```bash
|
||||
# Claude Code
|
||||
npx @opengsd/gsd-core --claude --global # 安装到 ~/.claude/
|
||||
npx @opengsd/gsd-core --claude --local # 安装到 ./.claude/
|
||||
|
||||
# OpenCode
|
||||
npx @opengsd/gsd-core --opencode --global # 安装到 ~/.config/opencode/
|
||||
|
||||
# Gemini CLI
|
||||
npx @opengsd/gsd-core --gemini --global # 安装到 ~/.gemini/
|
||||
|
||||
# Kilo
|
||||
npx @opengsd/gsd-core --kilo --global # 安装到 ~/.config/kilo/
|
||||
npx @opengsd/gsd-core --kilo --local # 安装到 ./.kilo/
|
||||
|
||||
# Codex
|
||||
npx @opengsd/gsd-core --codex --global # 安装到 ~/.codex/
|
||||
npx @opengsd/gsd-core --codex --local # 安装到 ./.codex/
|
||||
|
||||
# 所有运行时
|
||||
npx @opengsd/gsd-core --all --global # 安装到所有目录
|
||||
```
|
||||
|
||||
使用 `--global`（`-g`）或 `--local`（`-l`）跳过位置提示。
|
||||
使用 `--claude`、`--opencode`、`--gemini`、`--kilo`、`--codex` 或 `--all` 跳过运行时提示。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>开发安装</strong></summary>
|
||||
|
||||
克隆仓库并本地运行安装程序：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/open-gsd/gsd-core.git
|
||||
cd gsd-core
|
||||
node bin/install.js --claude --local
|
||||
```
|
||||
|
||||
安装到 `./.claude/` 用于在贡献前测试修改。
|
||||
|
||||
</details>
|
||||
|
||||
### 推荐：跳过权限模式
|
||||
|
||||
GSD 设计为无摩擦自动化。运行 Claude Code 时使用：
|
||||
|
||||
```bash
|
||||
claude --dangerously-skip-permissions
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> 这是 GSD 的预期使用方式 —— 停下来 50 次批准 `date` 和 `git commit` 会失去意义。
|
||||
|
||||
<details>
|
||||
<summary><strong>替代方案：细粒度权限</strong></summary>
|
||||
|
||||
如果你不想使用那个标志，在项目的 `.claude/settings.json` 中添加：
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(date:*)",
|
||||
"Bash(echo:*)",
|
||||
"Bash(cat:*)",
|
||||
"Bash(ls:*)",
|
||||
"Bash(mkdir:*)",
|
||||
"Bash(wc:*)",
|
||||
"Bash(head:*)",
|
||||
"Bash(tail:*)",
|
||||
"Bash(sort:*)",
|
||||
"Bash(grep:*)",
|
||||
"Bash(tr:*)",
|
||||
"Bash(git add:*)",
|
||||
"Bash(git commit:*)",
|
||||
"Bash(git status:*)",
|
||||
"Bash(git log:*)",
|
||||
"Bash(git diff:*)",
|
||||
"Bash(git tag:*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
- [上下文工程](explanation/context-engineering.md) — 上下文腐化如何形成，以及 GSD Core 如何防止它
|
||||
- [阶段循环](explanation/the-phase-loop.md) — 讨论 → 规划 → 执行 → 验证 → 交付循环的设计原理
|
||||
- [多代理编排](explanation/multi-agent-orchestration.md) — 子代理的生成、范围界定和协调方式
|
||||
- [安全模型](explanation/security-model.md) — 信任边界、权限和安全自动化
|
||||
- [架构](ARCHITECTURE.md) — 系统架构、代理模型和数据流
|
||||
- [讨论模式](workflow-discuss-mode.md) — `/gsd-discuss-phase` 的假设模式与访谈模式
|
||||
- [上下文监控](context-monitor.md) — 上下文窗口监控钩子架构
|
||||
- [Issue 驱动编排](issue-driven-orchestration.md) — 使用现有原语从追踪器 issue 驱动 GSD 的方案
|
||||
|
||||
---
|
||||
|
||||
## 工作原理
|
||||
## Related
|
||||
|
||||
> **已有代码？** 先运行 `/gsd-map-codebase`。它会生成并行代理分析你的技术栈、架构、约定和关注点。然后 `/gsd-new-project` 就了解你的代码库了 —— 问题聚焦在你正在**添加**什么，规划会自动加载你的模式。
|
||||
|
||||
### 1. 初始化项目
|
||||
|
||||
```
|
||||
/gsd-new-project
|
||||
```
|
||||
|
||||
一条命令，一个流程。系统：
|
||||
|
||||
1. **提问** —— 问到完全理解你的想法为止（目标、约束、技术偏好、边缘情况）
|
||||
2. **研究** —— 生成并行代理调查领域（可选但推荐）
|
||||
3. **需求** —— 提取哪些是 v1、v2 和范围外
|
||||
4. **路线图** —— 创建映射到需求的阶段
|
||||
|
||||
你批准路线图。现在准备好构建了。
|
||||
|
||||
**创建：** `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md`、`.planning/research/`
|
||||
|
||||
---
|
||||
|
||||
### 2. 讨论阶段
|
||||
|
||||
```
|
||||
/gsd-discuss-phase 1
|
||||
```
|
||||
|
||||
**这是你塑造实现方式的地方。**
|
||||
|
||||
你的路线图每个阶段有一两句话。这不足以按照**你**想象的方式构建东西。这一步在研究或规划之前捕获你的偏好。
|
||||
|
||||
系统分析阶段并根据正在构建的内容识别灰色区域：
|
||||
|
||||
- **视觉功能** → 布局、密度、交互、空状态
|
||||
- **API/CLI** → 响应格式、标志、错误处理、详细程度
|
||||
- **内容系统** → 结构、语气、深度、流程
|
||||
- **组织任务** → 分组标准、命名、重复项、例外
|
||||
|
||||
对于你选择的每个领域，它会问到让你满意为止。输出 —— `CONTEXT.md` —— 直接输入接下来的两个步骤：
|
||||
|
||||
1. **研究员读取它** —— 知道要调查什么模式（"用户想要卡片布局" → 研究卡片组件库）
|
||||
2. **规划者读取它** —— 知道哪些决策已锁定（"无限滚动已决定" → 规划包含滚动处理）
|
||||
|
||||
你在这里走得越深，系统构建的就越是你真正想要的。跳过它你会得到合理的默认值。使用它你会得到**你的**愿景。
|
||||
|
||||
**创建：** `{阶段号}-CONTEXT.md`
|
||||
|
||||
---
|
||||
|
||||
### 3. 规划阶段
|
||||
|
||||
```
|
||||
/gsd-plan-phase 1
|
||||
```
|
||||
|
||||
系统：
|
||||
|
||||
1. **研究** —— 调查如何实现这个阶段，由你的 CONTEXT.md 决策指导
|
||||
2. **规划** —— 创建 2-3 个带有 XML 结构的原子任务计划
|
||||
3. **验证** —— 根据需求检查计划，循环直到通过
|
||||
|
||||
每个计划足够小，可以在全新的上下文窗口中执行。没有退化，没有"我现在会更简洁"。
|
||||
|
||||
**创建：** `{阶段号}-RESEARCH.md`、`{阶段号}-{N}-PLAN.md`
|
||||
|
||||
---
|
||||
|
||||
### 4. 执行阶段
|
||||
|
||||
```
|
||||
/gsd-execute-phase 1
|
||||
```
|
||||
|
||||
系统：
|
||||
|
||||
1. **按波次运行计划** —— 可能的话并行，有依赖时顺序
|
||||
2. **每个计划全新上下文** —— 200k token 纯粹用于实现，零累积垃圾
|
||||
3. **每个任务提交** —— 每个任务都有自己的原子提交
|
||||
4. **根据目标验证** —— 检查代码库是否交付了阶段承诺的内容
|
||||
|
||||
离开，回来看到完成的工作和干净的 git 历史。
|
||||
|
||||
**波次执行工作原理：**
|
||||
|
||||
计划根据依赖关系分组到"波次"。在每个波次内，计划并行运行。波次顺序执行。
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ 阶段执行 │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 波次 1 (并行) 波次 2 (并行) 波次 3 │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │ 计划 01 │ │ 计划 02 │ → │ 计划 03 │ │ 计划 04 │ → │ 计划 05 │ │
|
||||
│ │ │ │ │ │ │ │ │ │ │ │
|
||||
│ │ 用户 │ │ 产品 │ │ 订单 │ │ 购物车 │ │ 结账 │ │
|
||||
│ │ 模型 │ │ 模型 │ │ API │ │ API │ │ UI │ │
|
||||
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
|
||||
│ │ │ ↑ ↑ ↑ │
|
||||
│ └───────────┴──────────────┴───────────┘ │ │
|
||||
│ 依赖关系: 计划 03 需要计划 01 │ │
|
||||
│ 计划 04 需要计划 02 │ │
|
||||
│ 计划 05 需要计划 03 + 04 │ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**为什么波次重要：**
|
||||
- 独立计划 → 同一波次 → 并行运行
|
||||
- 依赖计划 → 后续波次 → 等待依赖
|
||||
- 文件冲突 → 顺序计划或同一计划
|
||||
|
||||
这就是为什么"垂直切片"（计划 01: 用户功能端到端）比"水平分层"（计划 01: 所有模型，计划 02: 所有 API）并行化更好。
|
||||
|
||||
**创建：** `{阶段号}-{N}-SUMMARY.md`、`{阶段号}-VERIFICATION.md`
|
||||
|
||||
---
|
||||
|
||||
### 5. 验证工作
|
||||
|
||||
```
|
||||
/gsd-verify-work 1
|
||||
```
|
||||
|
||||
**这是你确认它真的有效的地方。**
|
||||
|
||||
自动化验证检查代码存在和测试通过。但功能是否按你预期的方式**工作**？这是你使用它的机会。
|
||||
|
||||
系统：
|
||||
|
||||
1. **提取可测试交付物** —— 你现在应该能做什么
|
||||
2. **逐个引导你** —— "你能用邮箱登录吗？" 是/否，或描述有什么问题
|
||||
3. **自动诊断失败** —— 生成调试代理找根本原因
|
||||
4. **创建已验证的修复计划** —— 准备立即重新执行
|
||||
|
||||
如果一切通过，继续。如果有东西坏了，不用手动调试 —— 只需再次运行 `/gsd-execute-phase`，使用它创建的修复计划。
|
||||
|
||||
**创建：** `{阶段号}-UAT.md`，如果发现问题则创建修复计划
|
||||
|
||||
---
|
||||
|
||||
### 6. 循环 → 完成 → 下一个里程碑
|
||||
|
||||
```
|
||||
/gsd-discuss-phase 2
|
||||
/gsd-plan-phase 2
|
||||
/gsd-execute-phase 2
|
||||
/gsd-verify-work 2
|
||||
...
|
||||
/gsd-complete-milestone
|
||||
/gsd-new-milestone
|
||||
```
|
||||
|
||||
循环 **讨论 → 规划 → 执行 → 验证** 直到里程碑完成。
|
||||
|
||||
如果你想在讨论期间更快速地输入，使用 `/gsd-discuss-phase <n> --batch` 一次回答一组小问题，而不是一个一个来。使用 `--chain` 可以自动链式执行从讨论到规划+执行，中间不停顿。
|
||||
|
||||
每个阶段都会获得你的输入（讨论）、适当的研究（规划）、干净的执行（执行）和人工验证（验证）。上下文保持新鲜。质量保持高水平。
|
||||
|
||||
当所有阶段完成后，`/gsd-complete-milestone` 归档里程碑并标记发布。
|
||||
|
||||
然后 `/gsd-new-milestone` 开始下一个版本 —— 与 `new-project` 相同的流程，但针对你现有的代码库。你描述接下来想构建什么，系统研究领域，你界定需求范围，它创建新的路线图。每个里程碑是一个干净的周期：定义 → 构建 → 发布。
|
||||
|
||||
---
|
||||
|
||||
### 快速模式
|
||||
|
||||
```
|
||||
/gsd-quick
|
||||
```
|
||||
|
||||
**用于不需要完整规划的临时任务。**
|
||||
|
||||
快速模式给你 GSD 保证（原子提交、状态跟踪）和更快的路径：
|
||||
|
||||
- **相同代理** —— 规划者 + 执行者，相同质量
|
||||
- **跳过可选步骤** —— 默认无研究、无计划检查器、无验证器
|
||||
- **独立跟踪** —— 存放在 `.planning/quick/`，不是阶段
|
||||
|
||||
**`--discuss` 标志：** 规划前的轻量讨论，发现灰色地带。
|
||||
|
||||
**`--research` 标志：** 规划前启动聚焦研究员。调查实现方法、库选项和陷阱。当你不确定如何处理任务时使用。
|
||||
|
||||
**`--full` 标志：** 启用所有阶段 —— 讨论 + 研究 + 计划检查 + 验证。快速任务形式的完整 GSD 管道。
|
||||
|
||||
**`--validate` 标志：** 仅启用计划检查 + 执行后验证（之前 `--full` 的行为）。
|
||||
|
||||
标志可组合：`--discuss --research --validate` 提供讨论 + 研究 + 计划检查 + 验证。
|
||||
|
||||
```
|
||||
/gsd-quick
|
||||
> 你想做什么？"在设置中添加深色模式切换"
|
||||
```
|
||||
|
||||
**创建：** `.planning/quick/001-add-dark-mode-toggle/PLAN.md`、`SUMMARY.md`
|
||||
|
||||
---
|
||||
|
||||
## 为什么有效
|
||||
|
||||
### 上下文工程
|
||||
|
||||
Claude Code 非常强大，**如果你**给它需要的上下文。大多数人没有。
|
||||
|
||||
GSD 为你处理：
|
||||
|
||||
| 文件 | 作用 |
|
||||
|------|------|
|
||||
| `PROJECT.md` | 项目愿景，始终加载 |
|
||||
| `research/` | 生态知识（技术栈、功能、架构、陷阱） |
|
||||
| `REQUIREMENTS.md` | 界定 v1/v2 需求及阶段可追溯性 |
|
||||
| `ROADMAP.md` | 你要去哪里，完成了什么 |
|
||||
| `STATE.md` | 决策、阻塞项、位置 —— 跨会话记忆 |
|
||||
| `PLAN.md` | 带有 XML 结构和验证步骤的原子任务 |
|
||||
| `SUMMARY.md` | 发生了什么，改了什么，提交到历史 |
|
||||
| `todos/` | 为后续工作捕获的想法和任务 |
|
||||
|
||||
基于 Claude 质量退化的位置设置大小限制。保持在限制内，获得一致的卓越。
|
||||
|
||||
### XML 提示格式
|
||||
|
||||
每个计划都是为 Claude 优化的结构化 XML：
|
||||
|
||||
```xml
|
||||
<task type="auto">
|
||||
<name>创建登录端点</name>
|
||||
<files>src/app/api/auth/login/route.ts</files>
|
||||
<action>
|
||||
使用 jose 处理 JWT（不用 jsonwebtoken - CommonJS 问题）。
|
||||
根据 users 表验证凭据。
|
||||
成功时返回 httpOnly cookie。
|
||||
</action>
|
||||
<verify>curl -X POST localhost:3000/api/auth/login 返回 200 + Set-Cookie</verify>
|
||||
<done>有效凭据返回 cookie，无效返回 401</done>
|
||||
</task>
|
||||
```
|
||||
|
||||
精确的指令。不猜测。内置验证。
|
||||
|
||||
### 多代理编排
|
||||
|
||||
每个阶段使用相同模式：轻量编排器生成专门代理，收集结果，路由到下一步。
|
||||
|
||||
| 阶段 | 编排器做 | 代理做 |
|
||||
|-------|------------------|-----------|
|
||||
| 研究 | 协调，呈现发现 | 4 个并行研究员调查技术栈、功能、架构、陷阱 |
|
||||
| 规划 | 验证，管理迭代 | 规划者创建计划，检查器验证，循环直到通过 |
|
||||
| 执行 | 分组为波次，跟踪进度 | 执行者并行实现，每个有全新 200k 上下文 |
|
||||
| 验证 | 呈现结果，路由下一步 | 验证器根据目标检查代码库，调试器诊断失败 |
|
||||
|
||||
编排器从不做重活。它生成代理，等待，整合结果。
|
||||
|
||||
**结果：** 你可以运行整个阶段 —— 深度研究、多个计划创建和验证、跨并行执行者编写数千行代码、根据目标自动化验证 —— 你的主上下文窗口保持在 30-40%。工作在全新的子代理上下文中完成。你的会话保持快速和响应。
|
||||
|
||||
### 原子 Git 提交
|
||||
|
||||
每个任务在完成后立即获得自己的提交：
|
||||
|
||||
```bash
|
||||
abc123f docs(08-02): 完成用户注册计划
|
||||
def456g feat(08-02): 添加邮箱确认流程
|
||||
hij789k feat(08-02): 实现密码哈希
|
||||
lmn012o feat(08-02): 创建注册端点
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> **好处：** Git bisect 找到确切的失败任务。每个任务独立可回滚。未来会话中 Claude 的清晰历史。AI 自动化工作流中更好的可观察性。
|
||||
|
||||
每个提交都是精确的、可追溯的、有意义的。
|
||||
|
||||
### 模块化设计
|
||||
|
||||
- 向当前里程碑添加阶段
|
||||
- 在阶段之间插入紧急工作
|
||||
- 完成里程碑并重新开始
|
||||
- 调整计划而不重建一切
|
||||
|
||||
你永远不会被锁定。系统会适应。
|
||||
|
||||
---
|
||||
|
||||
## 命令
|
||||
|
||||
### 核心工作流
|
||||
|
||||
| 命令 | 作用 |
|
||||
|---------|--------------|
|
||||
| `/gsd-new-project [--auto]` | 完整初始化：提问 → 研究 → 需求 → 路线图 |
|
||||
| `/gsd-discuss-phase [N] [--auto] [--chain] [--power]` | 在规划前捕获实现决策（`--chain` 自动链式执行规划+执行，`--power` 文件批量输入） |
|
||||
| `/gsd-plan-phase [N] [--auto]` | 阶段的研究 + 规划 + 验证 |
|
||||
| `/gsd-execute-phase <N>` | 在并行波次中执行所有计划，完成后验证 |
|
||||
| `/gsd-verify-work [N]` | 手动用户验收测试 ¹ |
|
||||
| `/gsd-audit-milestone` | 验证里程碑达到了其完成定义 |
|
||||
| `/gsd-complete-milestone` | 归档里程碑，标记发布 |
|
||||
| `/gsd-new-milestone [name]` | 开始下一个版本：提问 → 研究 → 需求 → 路线图 |
|
||||
|
||||
### 导航
|
||||
|
||||
| 命令 | 作用 |
|
||||
|---------|--------------|
|
||||
| `/gsd-progress` | 我在哪？接下来做什么？ |
|
||||
| `/gsd-help` | 显示所有命令和使用指南 |
|
||||
| `/gsd-update` | 更新 GSD 并预览变更日志 |
|
||||
|
||||
### 现有代码库
|
||||
|
||||
| 命令 | 作用 |
|
||||
|---------|--------------|
|
||||
| `/gsd-map-codebase` | 在 new-project 之前分析现有代码库 |
|
||||
|
||||
### 阶段管理
|
||||
|
||||
| 命令 | 作用 |
|
||||
|---------|--------------|
|
||||
| `/gsd-phase` | 向路线图追加阶段 |
|
||||
| `/gsd-phase --insert [N]` | 在阶段之间插入紧急工作 |
|
||||
| `/gsd-phase --remove [N]` | 删除未来阶段，重新编号 |
|
||||
| `/gsd-discuss-phase --assumptions [N]` | 规划前查看 Claude 的预期方法 |
|
||||
| `/gsd-autonomous [--from N] [--to N] [--only N]` | 自主执行所有剩余阶段（`--to N` 执行到阶段 N 停止，`--only N` 只执行单个阶段） |
|
||||
| `/gsd-manager --analyze-deps` | 检测阶段间依赖关系并建议 ROADMAP.md 的 `Depends on` 条目 |
|
||||
|
||||
### 会话
|
||||
|
||||
| 命令 | 作用 |
|
||||
|---------|--------------|
|
||||
| `/gsd-pause-work` | 阶段中途停止时创建交接 |
|
||||
| `/gsd-resume-work` | 从上次会话恢复 |
|
||||
|
||||
### 工具
|
||||
|
||||
| 命令 | 作用 |
|
||||
|---------|--------------|
|
||||
| `/gsd-settings` | 配置模型配置文件和工作流代理 |
|
||||
| `/gsd-config --profile <profile>` | 切换模型配置文件（quality/balanced/budget/inherit） |
|
||||
| `/gsd-capture [desc]` | 捕获想法留待后用 |
|
||||
| `/gsd-capture --list` | 列出待处理事项 |
|
||||
| `/gsd-debug [desc] [--diagnose]` | 带持久状态的系统化调试（`--diagnose` 仅诊断不修复） |
|
||||
| `/gsd-quick [--full] [--discuss] [--research]` | 用 GSD 保证执行临时任务（`--full` 启用全部阶段，`--discuss` 先收集上下文，`--research` 规划前调查方法） |
|
||||
| `/gsd-health [--repair]` | 验证 `.planning/` 目录完整性，用 `--repair` 自动修复 |
|
||||
|
||||
<sup>¹ 由 Reddit 用户 OracleGreyBeard 贡献</sup>
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
GSD 在 `.planning/config.json` 中存储项目设置。在 `/gsd-new-project` 期间配置或稍后用 `/gsd-settings` 更新。完整配置模式、工作流开关、git 分支选项和每个代理的模型分解，请参阅[用户指南](USER-GUIDE.md#配置参考)。
|
||||
|
||||
### 核心设置
|
||||
|
||||
| 设置 | 选项 | 默认值 | 控制内容 |
|
||||
|---------|---------|---------|------------------|
|
||||
| `mode` | `yolo`, `interactive` | `interactive` | 自动批准 vs 每步确认 |
|
||||
| `granularity` | `coarse`, `standard`, `fine` | `standard` | 阶段粒度 —— 范围切分多细（阶段 × 计划） |
|
||||
|
||||
### 模型配置
|
||||
|
||||
控制每个代理使用哪个 Claude 模型。平衡质量和 token 消耗。
|
||||
|
||||
| 配置 | 规划 | 执行 | 验证 |
|
||||
|---------|----------|-----------|--------------|
|
||||
| `quality` | Opus | Opus | Sonnet |
|
||||
| `balanced`（默认） | Opus | Sonnet | Sonnet |
|
||||
| `budget` | Sonnet | Sonnet | Haiku |
|
||||
|
||||
切换配置：
|
||||
```
|
||||
/gsd-config --profile budget
|
||||
```
|
||||
|
||||
或通过 `/gsd-settings` 配置。
|
||||
|
||||
### 工作流代理
|
||||
|
||||
这些在规划/执行期间生成额外代理。它们提高质量但增加 token 和时间。
|
||||
|
||||
| 设置 | 默认值 | 作用 |
|
||||
|---------|---------|--------------|
|
||||
| `workflow.research` | `true` | 每个阶段规划前研究领域 |
|
||||
| `workflow.plan_check` | `true` | 执行前验证计划是否达到阶段目标 |
|
||||
| `workflow.verifier` | `true` | 执行后确认必须项已交付 |
|
||||
| `workflow.auto_advance` | `false` | 自动链式执行 讨论 → 规划 → 执行 |
|
||||
| `workflow.use_worktrees` | `true` | `false` 时禁用 git worktree 隔离 |
|
||||
| `security_enforcement` | `true` | 启用威胁模型安全验证 |
|
||||
| `response_language` | (无) | 代理响应的语言代码（如 `"zh"`、`"ja"`、`"ko"`） |
|
||||
|
||||
使用 `/gsd-settings` 切换这些，或每次调用时覆盖：
|
||||
- `/gsd-plan-phase --skip-research`
|
||||
- `/gsd-plan-phase --skip-verify`
|
||||
|
||||
### 执行
|
||||
|
||||
| 设置 | 默认值 | 控制内容 |
|
||||
|---------|---------|------------------|
|
||||
| `parallelization.enabled` | `true` | 同时运行独立计划 |
|
||||
| `planning.commit_docs` | `true` | 在 git 中跟踪 `.planning/` |
|
||||
|
||||
### Git 分支
|
||||
|
||||
控制 GSD 在执行期间如何处理分支。
|
||||
|
||||
| 设置 | 选项 | 默认值 | 作用 |
|
||||
|---------|---------|---------|--------------|
|
||||
| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | 分支创建策略 |
|
||||
| `git.phase_branch_template` | 字符串 | `gsd/phase-{phase}-{slug}` | 阶段分支模板 |
|
||||
| `git.milestone_branch_template` | 字符串 | `gsd/{milestone}-{slug}` | 里程碑分支模板 |
|
||||
|
||||
**策略：**
|
||||
- **`none`** —— 提交到当前分支（默认 GSD 行为）
|
||||
- **`phase`** —— 每个阶段创建一个分支，阶段完成时合并
|
||||
- **`milestone`** —— 为整个里程碑创建一个分支，完成时合并
|
||||
|
||||
在里程碑完成时，GSD 提供 squash 合并（推荐）或带历史合并。
|
||||
|
||||
---
|
||||
|
||||
## 安全
|
||||
|
||||
### 保护敏感文件
|
||||
|
||||
GSD 的代码库映射和分析命令读取文件以了解你的项目。**保护包含密钥的文件**，将它们添加到 Claude Code 的拒绝列表：
|
||||
|
||||
1. 打开 Claude Code 设置（`.claude/settings.json` 或全局）
|
||||
2. 将敏感文件模式添加到拒绝列表：
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"deny": [
|
||||
"Read(.env)",
|
||||
"Read(.env.*)",
|
||||
"Read(**/secrets/*)",
|
||||
"Read(**/*credential*)",
|
||||
"Read(**/*.pem)",
|
||||
"Read(**/*.key)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这完全阻止 Claude 读取这些文件，无论你运行什么命令。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> GSD 包含内置保护以防止提交密钥，但纵深防御是最佳实践。拒绝读取敏感文件作为第一道防线。
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
**安装后找不到命令？**
|
||||
- 重启运行时以重新加载命令/技能
|
||||
- 验证文件是否存在于 `~/.claude/commands/gsd/`（全局）或 `./.claude/commands/gsd/`（本地）
|
||||
- 对于 Codex，验证技能是否存在于 `~/.codex/skills/gsd-*/SKILL.md`（全局）或 `./.codex/skills/gsd-*/SKILL.md`（本地）
|
||||
|
||||
**命令没有按预期工作？**
|
||||
- 运行 `/gsd-help` 验证安装
|
||||
- 重新运行 `npx @opengsd/gsd-core` 重新安装
|
||||
|
||||
**更新到最新版本？**
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest
|
||||
```
|
||||
|
||||
**使用 Docker 或容器化环境？**
|
||||
|
||||
如果用波浪号路径（`~/.claude/...`）读取文件失败，在安装前设置 `CLAUDE_CONFIG_DIR`：
|
||||
```bash
|
||||
CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/gsd-core --global
|
||||
```
|
||||
这确保使用绝对路径而不是 `~`，后者在容器中可能无法正确展开。
|
||||
|
||||
### 卸载
|
||||
|
||||
完全删除 GSD：
|
||||
|
||||
```bash
|
||||
# 全局安装
|
||||
npx @opengsd/gsd-core --claude --global --uninstall
|
||||
npx @opengsd/gsd-core --opencode --global --uninstall
|
||||
npx @opengsd/gsd-core --kilo --global --uninstall
|
||||
npx @opengsd/gsd-core --codex --global --uninstall
|
||||
|
||||
# 本地安装（当前项目）
|
||||
npx @opengsd/gsd-core --claude --local --uninstall
|
||||
npx @opengsd/gsd-core --opencode --local --uninstall
|
||||
npx @opengsd/gsd-core --kilo --local --uninstall
|
||||
npx @opengsd/gsd-core --codex --local --uninstall
|
||||
```
|
||||
|
||||
这删除所有 GSD 命令、代理、钩子和设置，同时保留你的其他配置。
|
||||
|
||||
---
|
||||
|
||||
## 社区移植
|
||||
|
||||
OpenCode、Gemini CLI、Kilo 和 Codex 现在通过 `npx @opengsd/gsd-core` 原生支持。
|
||||
|
||||
这些社区移植开创了多运行时支持：
|
||||
|
||||
| 项目 | 平台 | 描述 |
|
||||
|---------|----------|-------------|
|
||||
| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | 原始 OpenCode 适配 |
|
||||
| gsd-gemini (已归档) | Gemini CLI | 由 uberfuzzy 开发的原始 Gemini 适配 |
|
||||
|
||||
---
|
||||
|
||||
## Star 历史
|
||||
|
||||
<a href="https://star-history.com/#open-gsd/gsd-core&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=open-gsd/gsd-core&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=open-gsd/gsd-core&type=Date" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=open-gsd/gsd-core&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT 许可证。详见 [LICENSE](../LICENSE)。
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**Claude Code 很强大。GSD 让它可靠。**
|
||||
|
||||
</div>
|
||||
- [根目录 README](../README.md) — 首页、快速开始和文档概览
|
||||
- [变更日志](../../CHANGELOG.md) — 发布历史
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
80
docs/zh-CN/context-monitor.md
Normal file
80
docs/zh-CN/context-monitor.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# 上下文窗口监视器
|
||||
|
||||
一个后置工具钩子（Claude Code 中的 `PostToolUse`，Gemini CLI 中的 `AfterTool`），当上下文窗口使用率较高时向 Agent 发出警告。
|
||||
|
||||
## 问题背景
|
||||
|
||||
状态栏向**用户**展示上下文使用情况，但 **Agent** 本身并不感知上下文限制。当上下文剩余量不足时，Agent 会持续工作直至触及上限——可能在任务进行到一半、状态尚未保存时就被迫中断。
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. 状态栏钩子将上下文指标写入 `/tmp/claude-ctx-{session_id}.json`
|
||||
2. 每次工具调用结束后，上下文监视器读取这些指标
|
||||
3. 当剩余上下文低于阈值时，以 `additionalContext` 的形式注入警告
|
||||
4. Agent 在对话中接收到警告后即可采取相应措施
|
||||
|
||||
## 阈值
|
||||
|
||||
| 级别 | 剩余量 | Agent 行为 |
|
||||
|-------|-----------|----------------|
|
||||
| 正常 | > 35% | 无警告 |
|
||||
| 警告 | <= 35% | 完成当前任务收尾，避免开启新的复杂工作 |
|
||||
| 严重 | <= 25% | 立即停止，保存状态（`/gsd-pause-work`） |
|
||||
|
||||
## 防抖机制
|
||||
|
||||
为避免反复向 Agent 发送重复警告：
|
||||
- 首次警告始终立即触发
|
||||
- 后续警告需间隔 5 次工具调用才会再次触发
|
||||
- 严重级别升级（WARNING -> CRITICAL）可绕过防抖机制
|
||||
|
||||
## 架构
|
||||
|
||||
```
|
||||
Statusline Hook (gsd-statusline.js)
|
||||
| writes
|
||||
v
|
||||
/tmp/claude-ctx-{session_id}.json
|
||||
^ reads
|
||||
|
|
||||
Context Monitor (gsd-context-monitor.js, PostToolUse/AfterTool)
|
||||
| injects
|
||||
v
|
||||
additionalContext -> Agent sees warning
|
||||
```
|
||||
|
||||
中间桥接文件是一个简单的 JSON 对象：
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"remaining_percentage": 28.5,
|
||||
"used_pct": 71,
|
||||
"timestamp": 1708200000
|
||||
}
|
||||
```
|
||||
|
||||
## 与 GSD 的集成
|
||||
|
||||
GSD 的 `/gsd-pause-work` 命令用于保存执行状态。WARNING 消息建议使用该命令，CRITICAL 消息则要求立即保存状态。
|
||||
|
||||
## 配置
|
||||
|
||||
两个钩子均在执行 `npx @opengsd/gsd-core` 安装时自动注册——正常情况下无需手动操作。有关钩子配置详情、阈值覆盖以及手动注册示例，请参阅[配置文档](CONFIGURATION.md)。
|
||||
|
||||
简要参考：状态栏钩子在 `settings.json` 中注册为 `statusLine`；上下文监视器（`gsd-context-monitor.js`）注册为 `PostToolUse` 钩子（Gemini CLI 中为 `AfterTool`）。两项配置均使用运行安装程序时的 Node 可执行文件绝对路径。在 Windows PowerShell 中，需在带引号的可执行文件路径前添加 `&` 前缀。
|
||||
|
||||
## 安全性
|
||||
|
||||
- 钩子对所有操作进行 try/catch 包裹，出错时静默退出
|
||||
- 不会阻塞工具执行——监视器出现故障不应影响 Agent 的工作流程
|
||||
- 过期指标（超过 60 秒）将被忽略
|
||||
- 缺失的桥接文件可被优雅处理（适用于子 Agent 及新会话）
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [架构](ARCHITECTURE.md)
|
||||
- [配置](CONFIGURATION.md)
|
||||
- [文档索引](README.md)
|
||||
90
docs/zh-CN/explanation/context-engineering.md
Normal file
90
docs/zh-CN/explanation/context-engineering.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# 上下文工程
|
||||
|
||||
> GSD Core 的存在原因及其旨在解决的问题。
|
||||
|
||||
---
|
||||
|
||||
## 问题：上下文腐化
|
||||
|
||||
每次 AI 编码会话都从全新开始。模型读取你的问题，对其进行推理，然后作出回复。但一次会话很少只有一轮交互。你会追问后续问题、粘贴错误信息、迭代代码，并在模型偏离方向时加以纠正。每一轮都会向上下文窗口中添加令牌——这是一个模型在同一时刻能"看到"的有限文本缓冲区。
|
||||
|
||||
随着该窗口逐渐填满，一些微妙的变化随之而来。模型不会高调地出错，它仍然持续作答，但答案的质量会悄然下降。早期的指令被推到它所能关注范围的边缘。最初几轮交互中的细节——你陈述的约束、你达成共识的架构、你标注的边界情况——都在与后续堆积的内容争夺注意力。研究人员将这种现象称为**上下文腐化**。
|
||||
|
||||
上下文腐化会以多种方式显现：
|
||||
|
||||
- 模型开始与它此前已认可的决定相矛盾。
|
||||
- 代码风格偏离了会话开始时确立的规范。
|
||||
- 计划开始忽略那些明确陈述过、但如今已深埋于历史记录中的需求。
|
||||
- 模型产生幻觉，给出二十条消息前还正确的文件名或函数签名。
|
||||
|
||||
这些问题都不是模型的 bug。这是 Transformer 注意力机制在长序列上运作的基本属性。模型并非在"遗忘"——它从未以人类的方式"记住"过任何东西。它在有限窗口中对相关性进行加权，而随着窗口被积累的噪声填满，信噪比不断下降。
|
||||
|
||||
最直觉的应对方式是使用 `/clear` 重新开始。但这会丢失连贯性。你必须重新解释背景、重新粘贴相关文件、重新陈述约束条件。会话实质上归零重启了。
|
||||
|
||||
---
|
||||
|
||||
## GSD Core 的答案：全新上下文的子智能体
|
||||
|
||||
GSD Core 的核心洞见是：编码会话中*大多数*工作根本无需在主上下文中完成。研究、规划、代码编写和验证各自是独立且边界清晰的任务。每项任务都可以交给一个专门的子智能体来处理——该智能体以一个干净、精心限定范围的上下文窗口启动，并将其结果报告给一个保持精简状态的薄层编排器。
|
||||
|
||||
这不是上下文腐化的变通之法，而是一种结构性解决方案。
|
||||
|
||||
编排器——也就是你的主会话——从不接触源文件。它生成智能体、收集其结果、更新共享状态，并路由到下一个步骤。正因为它自身承担的工作很少，其上下文窗口的增长缓慢且可预测。繁重的工作发生在各个智能体中——每个智能体都以全新状态启动，仅接收完成其任务所需的上下文，并在完成后终止。
|
||||
|
||||
考虑这在实践中意味着什么。当你运行 `/gsd-plan-phase` 时，编排器会：
|
||||
|
||||
1. 加载一个紧凑的 JSON 上下文有效载荷（项目摘要、阶段目标、相关配置）。
|
||||
2. 生成一个拥有 20 万令牌全新窗口的研究智能体。
|
||||
3. 以研究输出和阶段需求为输入，生成一个规划智能体。
|
||||
4. 生成一个计划检查智能体，在执行前验证计划。
|
||||
|
||||
每个智能体都以满负荷运行，不受会话积累历史的拖累。当规划器将其 `PLAN.md` 文件写入 `.planning/phases/` 时，该输出成为持久的产物——而非共享上下文窗口中脆弱的记忆。
|
||||
|
||||
---
|
||||
|
||||
## 规格驱动开发与元提示
|
||||
|
||||
仅靠上下文工程还不够。如果一个智能体以全新状态启动，却接收到模糊的指令，它产生的输出也将是模糊的。GSD Core 将全新上下文的子智能体与两项互补的原则相结合：
|
||||
|
||||
**规格驱动开发**意味着每个阶段在执行开始之前都会生成结构化产物。`CONTEXT.md` 捕获来自讨论步骤的实现决策。`RESEARCH.md` 记录研究智能体的发现。`PLAN.md` 将工作分解为离散的、按依赖关系排序的任务，并附有明确的验收标准。在执行器智能体接触文件之时，它已拥有一份精确的规格说明——而非对一段漫长对话的重新解读。
|
||||
|
||||
**元提示**意味着智能体定义本身就是经过精心设计的提示，而非临时指令。`get-shit-done/workflows/` 和 `agents/` 中的文件编码了关于如何限定任务范围、需要验证什么，以及何时上报至人工检查点的宝贵经验。用户无需在每次会话中重新解释这些知识；它已内嵌于系统自身的提示中。
|
||||
|
||||
这种组合是刻意为之的。全新上下文确保每个智能体清晰推理。规格驱动的产物确保每个智能体针对*正确的*事物进行推理。元提示确保每个智能体知道*如何*将其做好。
|
||||
|
||||
---
|
||||
|
||||
## `.planning/` 的作用
|
||||
|
||||
上下文工程要求知识能在上下文重置后得以保留。GSD Core 为此使用文件系统。每一项有意义的输出都以人类可读的 Markdown 或 JSON 格式写入 `.planning/`。这意味着：
|
||||
|
||||
- 重启会话（或模型崩溃）不会丢失工作成果。
|
||||
- 任何后续智能体都可以直接读取先前的产物，而无需依赖共享的对话历史。
|
||||
- 你可以检查、编辑规划产物，或将其提交到 git——它们是纯文本，而非数据库中不透明的状态。
|
||||
|
||||
`STATE.md` 是这个系统的支柱。它记录项目的当前位置（处于哪个里程碑、哪个阶段、哪些计划已完成）、活跃的决策和阻碍项，以及进度指标。每当工作流启动时，它都会读取 `STATE.md` 来定向自身。每当工作流完成一个有意义的步骤时，它都会回写 `STATE.md`。智能体不依赖记忆；它们依赖文件。
|
||||
|
||||
---
|
||||
|
||||
## 权衡
|
||||
|
||||
这里需要如实说明权衡之处。
|
||||
|
||||
**额外开销。** 阶段循环引入了真实的摩擦。将 `/gsd-discuss-phase`、`/gsd-plan-phase` 和 `/gsd-execute-phase` 作为独立步骤运行，比直接在普通会话中输入"实现这个功能"需要更多的耗时。对于小型、已充分理解的改动，这种开销并不值得。
|
||||
|
||||
**延迟。** 生成多个拥有全新上下文的子智能体，比单次上下文内编辑要慢。研究、规划和执行各自都会产生往返成本。
|
||||
|
||||
**简单任务的繁文缛节。** 如果你只需要重命名一个变量、修复一个错别字，或添加一个缺失的导入，阶段循环就是杀鸡用牛刀。GSD Core 提供了 `/gsd-quick` 和 `/gsd-fast`，用于处理不需要完整阶段的临时工作。请参阅[处理快速任务](../how-to/handle-quick-and-fast-tasks.md)。
|
||||
|
||||
当工作足够复杂、上下文腐化成为真实风险时，阶段循环才物有所值——例如多文件功能、横切重构、跨越数小时或多个会话的工作。其他情况下，请使用更轻量的原语。
|
||||
|
||||
一个有用的经验法则：如果任务可以用一个简短的提示完整描述，且无需进一步澄清就能在一次智能体回合中完成，跳过阶段循环。如果任务需要研究、涉及你近期未读取的文件，或依赖尚未确定的决策，阶段循环则能保护你。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [阶段循环](the-phase-loop.md) — 讨论 → 规划 → 执行 → 验证 → 发布的循环如何将上下文工程付诸实践
|
||||
- [多智能体编排](multi-agent-orchestration.md) — 子智能体如何被生成、限定范围和协调
|
||||
- [架构](../ARCHITECTURE.md) — 系统架构、智能体模型和数据流
|
||||
- [文档索引](../README.md)
|
||||
216
docs/zh-CN/explanation/multi-agent-orchestration.md
Normal file
216
docs/zh-CN/explanation/multi-agent-orchestration.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# GSD Core 中的多智能体编排
|
||||
|
||||
> **说明文档** — 本文档阐述 GSD Core *为何*围绕多智能体编排进行设计，以及*各组件如何协同工作*。这不是操作指南。有关配置，请参阅
|
||||
> [配置模型配置文件](../how-to/configure-model-profiles.md) 和
|
||||
> [配置参考](../CONFIGURATION.md)。有关完整的智能体清单，
|
||||
> 请参阅 [清单](../INVENTORY.md)。
|
||||
|
||||
---
|
||||
|
||||
## 本设计解决的问题
|
||||
|
||||
AI 编程智能体会逐渐退化。这并非因为模型变差，而是因为
|
||||
*上下文窗口被填满*。随着对话的增长，早期的决策和代码
|
||||
会被中间步骤的噪音挤出或稀释。当智能体在复杂任务中写到第五个文件时，
|
||||
它可能已经忘记了第一条消息中说明的约束条件。这种现象有时被称为*上下文腐化*。
|
||||
|
||||
GSD Core 的多智能体设计正是对这一问题的直接回应。与其让一个
|
||||
长期运行的智能体承担整个会话，不如让一个轻量编排器派生出
|
||||
短暂存在的专用智能体，每个智能体都拥有**全新的 200K token 上下文窗口**，
|
||||
并且*只获取完成其特定工作所需的工件*。编排器自身从不承担繁重工作；
|
||||
它加载上下文、派生合适的智能体、收集结果，并在 `.planning/` 中更新共享状态。
|
||||
|
||||
---
|
||||
|
||||
## 编排器 → 智能体模式
|
||||
|
||||
`get-shit-done/workflows/` 中的每个工作流都遵循相同的结构：
|
||||
|
||||
```text
|
||||
Orchestrator (workflow .md file)
|
||||
│
|
||||
├── Load context
|
||||
│ gsd-tools.cjs init <workflow> <phase>
|
||||
│ → JSON: project info, config, state, phase details
|
||||
│
|
||||
├── Resolve model
|
||||
│ gsd-tools.cjs resolve-model <agent-name>
|
||||
│ → opus | sonnet | haiku | inherit
|
||||
│
|
||||
├── Spawn specialised agent (Task/SubAgent call)
|
||||
│ ├── Agent definition (agents/*.md)
|
||||
│ ├── Context payload (init JSON)
|
||||
│ ├── Model assignment
|
||||
│ └── Tool permissions
|
||||
│
|
||||
├── Collect result
|
||||
│
|
||||
└── Update state
|
||||
gsd-tools.cjs state update / state patch / state advance-plan
|
||||
```
|
||||
|
||||
编排器被刻意设计为轻量级。它不对领域进行推理，
|
||||
不编写代码，也不解读结果——仅将结果路由到下一个步骤。
|
||||
这种边界使每一层的职责清晰，并防止编排器的上下文积累领域噪音。
|
||||
|
||||
### 智能体清单
|
||||
|
||||
GSD 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` | 顺序执行 |
|
||||
|
||||
每个智能体定义（位于 `agents/*.md`）声明了其允许的工具访问权限、
|
||||
用途以及终端输出颜色。仅需读取文件并写入单个输出文档的智能体
|
||||
只获得这些权限——无 Bash 执行权限，无法访问更广泛的状态。
|
||||
该约束是刻意为之的：如果智能体行为异常，可将影响范围控制在最小。
|
||||
|
||||
有关完整的 31 个智能体清单，请参阅 [清单](../INVENTORY.md#agents-31-shipped)。
|
||||
|
||||
---
|
||||
|
||||
## 基于波次的并行执行
|
||||
|
||||
多智能体设计最直观的体现是 `/gsd-execute-phase`
|
||||
如何处理一组可能相互依赖的计划。
|
||||
|
||||
在派生任何执行员之前，编排器会执行**波次分析**：
|
||||
读取每个 `PLAN.md` 文件中的依赖声明，并将计划分组成波次。
|
||||
没有声明依赖的计划构成第 1 波次并并行运行。
|
||||
依赖第 1 波次的计划构成第 2 波次，以此类推。
|
||||
|
||||
```text
|
||||
Plan 01 (no deps) ─┐
|
||||
Plan 02 (no deps) ─┤─── Wave 1 (parallel)
|
||||
Plan 03 (depends: 01) ─┤─── Wave 2 (waits for Wave 1)
|
||||
Plan 04 (depends: 02) ─┘
|
||||
Plan 05 (depends: 03, 04) ─── Wave 3 (waits for Wave 2)
|
||||
```
|
||||
|
||||
波次内的每个执行员：
|
||||
|
||||
- 接收一个全新的上下文窗口（200K token，或在支持的模型上最高 1M）
|
||||
- 接收其负责的特定 `PLAN.md`
|
||||
- 接收项目上下文（`PROJECT.md`、`STATE.md`）
|
||||
- 接收阶段上下文（`CONTEXT.md`、`RESEARCH.md`，如果可用）
|
||||
- 完成时生成原子 git 提交
|
||||
- 写入描述构建内容的 `SUMMARY.md`
|
||||
|
||||
当一个波次内的所有执行员完成后，编排器对整个波次运行一次
|
||||
pre-commit 钩子。执行员使用 `--no-verify` 提交，以防止
|
||||
多个智能体并行提交时发生构建锁定争用（例如 Rust 项目中的 Cargo 锁定冲突）。
|
||||
因此，钩子每个波次运行一次，而非每次提交运行一次。
|
||||
|
||||
### 并行提交安全性
|
||||
|
||||
两种机制防止多个执行员同时运行时发生写入冲突：
|
||||
|
||||
1. **`STATE.md` 的原子锁** — 每次写入 `STATE.md` 都使用
|
||||
带有 `O_EXCL` 原子创建的锁文件（`STATE.md.lock`）。这防止了
|
||||
两个智能体各自读取文件、修改不同字段、后写入者覆盖先写入者
|
||||
更改的读-改-写竞态条件。过期锁（超过 10 秒）会被自动清除。
|
||||
|
||||
2. **每波次运行钩子** — 每个执行员独立运行 pre-commit 钩子
|
||||
（这可能在共享构建工件上引发文件级争用），编排器在
|
||||
每个波次完成后运行一次 `git hook run pre-commit`。
|
||||
|
||||
---
|
||||
|
||||
## 针对大窗口模型的自适应上下文丰富
|
||||
|
||||
标准的 200K 上下文窗口足以让执行员实现一个专注的计划。
|
||||
当配置的 `context_window` 达到 500K token 或更大时
|
||||
（例如在 1M 级模式下使用 Opus 4.6 或 Sonnet 4.6），
|
||||
编排器会自动使用标准窗口无法容纳的额外上下文来丰富子智能体提示：
|
||||
|
||||
- **执行员智能体**接收前一波次的 `SUMMARY.md` 文件和阶段
|
||||
`CONTEXT.md`/`RESEARCH.md`，使其在阶段内具备跨计划感知能力
|
||||
- **验证员智能体**接收所有 `PLAN.md`、`SUMMARY.md` 和 `CONTEXT.md`
|
||||
文件以及 `REQUIREMENTS.md`，实现具有历史感知能力的验证
|
||||
|
||||
此丰富功能以 `config.json` 中的 `context_window` 值为条件。
|
||||
在标准窗口配置下，提示使用截断版本，并采用缓存友好的排序
|
||||
以最大化 token 效率。
|
||||
|
||||
---
|
||||
|
||||
## 为何采用此设计——与上下文工程的关联
|
||||
|
||||
只有作为更广泛的*上下文工程*方法的一部分，
|
||||
编排器 → 智能体模式才有意义：这一理念认为，
|
||||
AI 智能体上下文窗口中包含的内容与模型层级或提示质量同样重要。
|
||||
完整论述请参阅[上下文工程](context-engineering.md)。
|
||||
|
||||
多智能体编排以两种方式将上下文工程付诸实践：
|
||||
|
||||
**上下文隔离。** 每个智能体只接收它所需要的内容。研究员
|
||||
获取项目描述和领域问题；它不会获取完整的规划历史。
|
||||
验证员获取每个计划和摘要；它不会获取原始研究资料。
|
||||
隔离使每个智能体的上下文充满信号，而非被其他流水线阶段的噪音稀释。
|
||||
|
||||
**跨会话的上下文卫生。** 由于所有状态都以人类可读的 Markdown 和 JSON
|
||||
存储在 `.planning/` 中（而非任何智能体的上下文窗口中），
|
||||
GSD 工作流能够在上下文重置（`/clear`）、标签页切换和
|
||||
多日中断后继续运行。下一个智能体始终从持久化的、经过验证的
|
||||
工件启动，而非从漫长对话的重建记忆中启动。
|
||||
|
||||
---
|
||||
|
||||
## 权衡
|
||||
|
||||
多智能体编排并非没有代价。
|
||||
|
||||
**协调开销。** 每次智能体派生都是一次往返：编排器
|
||||
必须格式化提示、移交上下文、等待子智能体完成
|
||||
（通常需 1–5 分钟），然后解析结果。对于简单任务，
|
||||
单个能力强大的智能体在一个上下文中工作会更快完成。GSD 通过
|
||||
将并行化作为默认方式来缓解这一问题（在依赖关系允许的情况下）——
|
||||
`plan-phase` 中的四个研究员同时运行，而非顺序运行。
|
||||
|
||||
**执行期间的不透明性。** 当子智能体运行时，其工作对父会话不可见。
|
||||
没有实时进度流。这是全新上下文设计的刻意结果：
|
||||
子智能体在其自己的上下文窗口中运行。编排器在
|
||||
派生行显示活跃性提示（"runs in a subagent — no output until it returns"）
|
||||
以设定预期。
|
||||
|
||||
**上下文拼接成本。** 为每个智能体打包正确的工件
|
||||
需要编排器花费 token 来组装和传输上下文负载。
|
||||
这是隔离的代价。`gsd-tools.cjs init` 处理器
|
||||
生成一个在完整性与 token 预算之间取得平衡的 JSON 负载，
|
||||
采用缓存友好的排序，使负载中稳定的部分（项目定义、配置）
|
||||
在重复调用时命中缓存。
|
||||
|
||||
**模型成本放大。** 在 Opus 层级并行运行五个智能体
|
||||
比运行一个成本更高。模型配置文件系统（`model_profiles.md`，
|
||||
由 `model-profiles.cjs` 按智能体解析）让您可以为
|
||||
不那么关键的智能体分配更低成本的层级。`dynamic_routing` 功能
|
||||
通过以更低层级启动每个智能体并仅在软失败时升级来进一步降低成本。
|
||||
完整选项请参阅[配置](../CONFIGURATION.md)。
|
||||
|
||||
为换取这些代价，该设计实现了*大型阶段的一致质量*。
|
||||
在 400 行计划中编写第十个文件的执行员不会退化，
|
||||
因为其上下文是全新的。检查二十个需求的验证员不会忘记前十个，
|
||||
因为它以结构化输入而非对话历史的形式接收了所有需求。
|
||||
|
||||
---
|
||||
|
||||
## 相关资源
|
||||
|
||||
- [上下文工程](context-engineering.md) — 驱动本设计的上游原则
|
||||
- [配置模型配置文件](../how-to/configure-model-profiles.md) — 如何按智能体分配模型层级
|
||||
- [配置参考](../CONFIGURATION.md) — 完整的 `config.json` 架构，
|
||||
包括 `models`、`model_overrides`、`dynamic_routing` 和
|
||||
`context_window`
|
||||
- [清单](../INVENTORY.md) — 权威的智能体清单和工作流列表
|
||||
- [架构](../ARCHITECTURE.md#agent-model) — 编排器 → 智能体模式和
|
||||
波次执行模型的实现层面细节
|
||||
- [文档索引](../README.md)
|
||||
117
docs/zh-CN/explanation/security-model.md
Normal file
117
docs/zh-CN/explanation/security-model.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# GSD Core 安全模型
|
||||
|
||||
> **说明** — 本文档描述 GSD Core 为何采用当前的安全立场，以及各防护层如何协同工作。本文不是每个钩子参数的参考手册。有关 `/gsd-secure-phase` 命令及其选项，请参阅[命令文档](../COMMANDS.md)。有关实现层面的钩子架构，请参阅[架构文档 § 钩子系统](../ARCHITECTURE.md#hook-system)。有关组织级安全基线（扫描器控制、事件处理清单、所有权模型），请参阅 [SECURITY.md](../../../SECURITY.md)。
|
||||
|
||||
---
|
||||
|
||||
## 为何 AI 驱动的开发需要专项安全立场
|
||||
|
||||
传统代码编辑器不会代表用户执行任意软件包。GSD Core 会。其研究 → 计划 → 执行的流水线将从"命名一个软件包"到"运行 `npm install <package>`"、从"编写规划产物"到"将该产物用作 LLM 系统提示"的完整路径全部自动化。每一个自动化步骤都将人从环路中移除——而每次移除都是潜在的攻击面。
|
||||
|
||||
GSD Core 的安全模型围绕一个核心原则构建：**纵深防御**。没有任何单一控制措施被认为是完美的。多个相互重叠的层各自降低一类特定风险，共同使攻击面大幅难以利用——尽管并未彻底消除。本文档末尾的诚实总结说明了该系统无法防御的内容。
|
||||
|
||||
---
|
||||
|
||||
## 第一层 — 供应链保护：软件包合法性门控
|
||||
|
||||
### 威胁
|
||||
|
||||
AI 模型会产生幻觉性软件包名称。这并非边缘故障模式：2025 年的研究表明，AI 生成的软件包引用中约有 20% 是幻觉名称，与合法软件包并不对应。这些幻觉名称中有一部分——同一研究中约 43%——在提示词中持续重复出现，这意味着攻击者可以观察 AI 工具常见生成的名称，然后在 npm、PyPI 或 crates.io 上预先注册这些名称，并附带恶意的安装后脚本。这种技术称为 *slopsquatting*。
|
||||
|
||||
Slopsquatting 的隐蔽之处在于，通过 `npm view` 验证的幻觉名称*看起来是合法的*。注册表条目仅证明有人注册了该名称——并不能证明该软件包实现了 AI 所描述的功能，也不能证明它有任何合法用户，更不能证明其安装脚本是安全的。若没有门控，幻觉名称将无声地流过 GSD 的研究员 → 规划员 → 执行员流水线，最终在您的机器上作为 `npm install <attacker-package>` 运行。
|
||||
|
||||
### 门控机制
|
||||
|
||||
门控机制跨三个流水线阶段运行：
|
||||
|
||||
**研究阶段。** 当 `gsd-phase-researcher` 推荐外部软件包时，它会对每个软件包运行 `slopcheck install <pkgs> --json`。结果会以 `## Package Legitimacy Audit` 表格的形式写入 `RESEARCH.md`。标记为 `[SLOP]`（高置信度幻觉或攻击者注册）的软件包在保存前会**从 `RESEARCH.md` 中完全删除**，永远不会到达规划员。
|
||||
|
||||
**规划阶段。** `gsd-planner` 读取审计表。对于任何标记为 `[SUS]`（可疑：新注册、下载量低、无源代码仓库，或命名模式接近某热门软件包）或 `[ASSUMED]`（来自 WebSearch 而非直接注册表验证）的软件包，规划员会在安装步骤之前**插入一个 `checkpoint:human-verify` 任务**。该检查点包含指向注册表页面的直接链接，以及需要重点核查的内容：维护者历史、问题跟踪器活动、是否存在可疑的安装脚本。
|
||||
|
||||
**执行阶段。** 若安装失败，`gsd-executor` 会**触发检查点并停止**。它不会静默地尝试备用软件包名称——因为备用名称本身可能也是恶意的。这是执行员行为定义中的明确规则（执行员代理定义中的 RULE 3）。
|
||||
|
||||
### 为何 WebSearch 软件包始终标记为 `[ASSUMED]`
|
||||
|
||||
通过 WebSearch 发现的软件包名称无论 `npm view` 是否成功，均标记为 `[ASSUMED]`。在注册表中存在的软件包不等于可以安全安装的软件包。`npm view` 仅证明注册，而非合法性。`[ASSUMED]` 标签与 `[SUS]` 触发相同的人工验证检查点，确保任何未经验证的网络发现推荐在安装前均须经过人工审核。
|
||||
|
||||
### 生态系统覆盖范围
|
||||
|
||||
研究员使用各生态系统专属的验证命令，而非单一通用检查：
|
||||
|
||||
- Node.js：`npm view`
|
||||
- Python：`pip index versions`
|
||||
- Rust：`cargo search`
|
||||
|
||||
这覆盖了跨生态系统幻觉——根据 2025 年 USENIX 研究，其发生率约为 9%——即 AI 推荐的软件包存在于某个生态系统，但并不存在于实际使用的生态系统中。
|
||||
|
||||
### 优雅降级
|
||||
|
||||
若 `slopcheck` 不可用（未安装，或研究阶段 pip 安装失败），GSD 应用最严格的兜底策略：**每个推荐软件包均标记为 `[ASSUMED]`**，规划员对每次安装均设置 `checkpoint:human-verify` 任务。研究和规划照常进行——系统不会因缺少工具依赖而硬性失败。这有意比正常流程更严格：`slopcheck` 不可用意味着每次软件包安装都会有人工检查点。
|
||||
|
||||
`slopcheck` 工具采用 MIT 协议，可通过 pip 安装。若该工具被废弃，`[ASSUMED]` 门控兜底策略确保人工检查点覆盖无论如何均能维持。
|
||||
|
||||
---
|
||||
|
||||
## 第二层 — 提示注入防御
|
||||
|
||||
### 威胁
|
||||
|
||||
GSD Core 生成的 Markdown 文件会成为 LLM 系统提示。研究流水线读取外部网页内容；规划流水线接受用户提供的文本（`--text-file`、`--prd`）；执行流水线写入规划产物，这些产物稍后会作为代理上下文被重新读取。任何流入这些产物的用户可控文本都是潜在的**间接提示注入**向量——攻击者控制的字符串一旦进入系统提示，就会尝试覆盖代理指令或窃取信息。
|
||||
|
||||
### 防御机制
|
||||
|
||||
GSD Core 在三个层面应对提示注入。
|
||||
|
||||
**输入验证（`security.cjs`）。** `get-shit-done/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()` 该模块，因此即使模块路径改变也能运行）。检测结果**仅供参考**：钩子记录发现但不阻止写入。其原因在于，对合法规划写入的误报拦截比二级扫描层漏掉一次注入更具破坏性。
|
||||
|
||||
**运行时钩子：`gsd-read-injection-scanner.js`。** 该钩子在每次 Read 工具调用的输出时触发。它扫描*刚刚读取的内容*中在不可信内容中注入的指令——捕获攻击者在 GSD 即将纳入代理上下文的文件中嵌入指令的情况。
|
||||
|
||||
**CI 扫描器。** `prompt-injection-scan.test.cjs` 作为测试套件的一部分，扫描所有代理、工作流和命令文件中嵌入的注入向量。这能捕获 GSD 源代码本身的注入尝试——例如，修改工作流文件以添加角色覆盖指令的供应链攻击。
|
||||
|
||||
### 读取注入扫描器与提示守卫的对比
|
||||
|
||||
两个钩子覆盖互补的攻击面。`gsd-prompt-guard.js` 监视*对规划产物的写入*——捕获注入的植入。`gsd-read-injection-scanner.js` 监视*任何文件的读取*——捕获来自外部内容的注入摄取（依赖项的 README、第三方配置文件、用户提供的文档）。两者共同覆盖了摄取 → 存储 → 再读取的完整生命周期。
|
||||
|
||||
---
|
||||
|
||||
## 第三层 — 仓库与依赖完整性
|
||||
|
||||
在 GSD 运行时行为的上游，`open-gsd` 组织在仓库和软件包层面实施控制。这些控制在 [`docs/security/baseline.md`](../../security/baseline.md) 中有完整文档，此处为完整性摘要。
|
||||
|
||||
**依赖完整性。** 所有第三方依赖通过 `package-lock.json` 锁定，并在安装前与已发布的校验和进行验证。`scripts/check-npm-integrity.cjs` 门控在 CI 阶段检测版本无效、缺失软件包和多余软件包。这能缓解针对 GSD 自身依赖的依赖混淆和拼写抢注攻击。
|
||||
|
||||
**密钥扫描。** 每次提交和 PR 均扫描硬编码密钥。有意的测试夹具必须使用项目标准排除语法进行标注（标注格式见 `SECURITY.md`）。未标注的抑制项将导致 CI 失败。
|
||||
|
||||
**区域设置安全文本扫描。** 输出和面向用户的字符串会扫描 Unicode 同形字符、双向覆盖字符以及不可见 Unicode——即 CVE-2021-42574（"特洛伊木马源代码"）中记录的那类可在差异中隐藏恶意内容的攻击。
|
||||
|
||||
---
|
||||
|
||||
## 权衡与局限
|
||||
|
||||
本文描述的安全模型切实降低了 AI 驱动开发的攻击面，但并未消除供应链风险。
|
||||
|
||||
**软件包合法性门控降低的风险：** 幻觉或攻击者注册的软件包在没有人工检查点的情况下到达 `npm install` 的概率。`[SLOP]` 门控彻底删除高置信度的恶意软件包；`[SUS]` / `[ASSUMED]` 门控要求在执行前进行人工审核。这大幅提升了成功 slopsquatting 攻击的成本。
|
||||
|
||||
**软件包合法性门控无法消除的风险：** 之后遭到入侵的合法软件包（账户接管、其自身依赖树中的依赖混淆）不会被 slopcheck 捕获——slopcheck 在研究阶段检查注册信号。锁定文件和依赖完整性层的 `npm audit` 才是应对此类攻击的控制手段。
|
||||
|
||||
**提示注入防御降低的风险：** 规划产物中用户可控文本成功覆盖代理指令的概率。基于模式匹配的已知注入形式能捕获常见情况；新颖的越狱方法或低信号注入可能无法被检测到。仅供参考的立场意味着检测结果被记录但不会被阻止——这是一个经过深思熟虑的选择，以牺牲在检测时硬性停止为代价换取工作流的连续性。
|
||||
|
||||
**提示注入防御无法消除的风险：** 足够有创意的、与已知模式不匹配的注入，或通过钩子未覆盖渠道到来的注入（例如，注入到依赖项已发布 README 中、由子代理在浏览文档时读取的内容）。纵深防御意味着每一层使攻击更难——而非任何单一层使其不可能。
|
||||
|
||||
**漏洞报告。** 请通过 GitHub 私有安全公告提交，地址为 `https://github.com/open-gsd/gsd-core/security/advisories/new`。请勿开启公开 issue。响应时间表和披露政策请参阅 [SECURITY.md](../../../SECURITY.md)。
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [命令文档](../COMMANDS.md) — 包含 `/gsd-secure-phase` 和 `/gsd-code-review` 及安全相关标志
|
||||
- [架构文档 § 钩子系统](../ARCHITECTURE.md#hook-system) — 每个钩子的实现细节、事件触发器及安全属性
|
||||
- [SECURITY.md](../../../SECURITY.md) — 漏洞报告、组织级安全基线、密钥扫描排除治理及依赖完整性验证
|
||||
- [文档索引](../README.md)
|
||||
129
docs/zh-CN/explanation/the-phase-loop.md
Normal file
129
docs/zh-CN/explanation/the-phase-loop.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# 阶段循环
|
||||
|
||||
> GSD Core 组织工作的核心思维模型。
|
||||
|
||||
---
|
||||
|
||||
## 循环是什么
|
||||
|
||||
GSD Core 将所有开发工作结构化为一个重复周期：
|
||||
|
||||
```text
|
||||
Discuss → (UI design) → Plan → Execute → Verify → Ship
|
||||
```
|
||||
|
||||
每个工作单元——称为**阶段**——按顺序经历这些步骤。循环并非形式主义。每个步骤的存在都是为了防范某一类特定的失败，而这类失败是上一步骤单独无法预防的。
|
||||
|
||||
本文档解释*为什么*循环是这种形态。有关运行每个步骤的操作说明，请参见底部链接的操作指南。
|
||||
|
||||
---
|
||||
|
||||
## 每个步骤存在的原因
|
||||
|
||||
### Discuss
|
||||
|
||||
在知道*如何*构建某物之前，规划无法开始——而不仅仅是*构建什么*。`ROADMAP.md` 中的阶段目标描述了结果。Discuss 步骤捕捉塑造通往该结果路径的实现决策：选用哪些库、采用哪种错误处理策略、某功能是按路由还是全局实现、边缘情况应如何处理。
|
||||
|
||||
没有 Discuss 步骤，规划器必须自行做出这些判断。有时它猜对了。但往往猜得似是而非却实际有误——产出一个逻辑连贯却与你实际偏好相悖的计划。等到执行完成、发现错误时，你已经在撤销大量工作了。
|
||||
|
||||
Discuss 步骤刻意保持轻量。它是一次对话，而非规格说明练习。输出是阶段目录中的 `CONTEXT.md`：一份规划器、执行器和验证器都可以阅读的结构化决策记录。对话只需几分钟，却能节省数小时的返工时间。
|
||||
|
||||
### UI design（可选）
|
||||
|
||||
对于有视觉组件的阶段，在 Discuss 和 Plan 之间有一个可选的 `/gsd-ui-phase` 步骤。它生成 `UI-SPEC.md`——一份在编写任何代码之前描述布局、交互和视觉行为的设计契约。当 UI 足够复杂，设计中的歧义会导致不同的实现选择时，值得运行此步骤。一份清晰的设计契约比重新实现要便宜得多。
|
||||
|
||||
### Plan
|
||||
|
||||
Plan 步骤完成执行所需的研究、分解和结构性思考。它以一系列全新上下文的子代理运行：一个研究者调查生态系统并将发现记录在 `RESEARCH.md` 中，一个规划器同时阅读研究结果和 `CONTEXT.md` 以生成 `PLAN.md` 文件，以及一个计划检查器验证计划是否完整、一致且在范围内。
|
||||
|
||||
计划包含什么？每个 `PLAN.md` 描述一个有边界的工作单元：需要修改的文件、要做的具体更改、定义完成状态的验收标准。计划按依赖波次排序，以便并行执行是安全的——同一波次中的执行器处理互不重叠的关注点。
|
||||
|
||||
Plan 步骤是歧义代价最高的时刻。一个模糊的计划会产生一个需要做假设的执行器。多个并行执行器对同一关注点做出不同假设会产生冲突。计划检查器的工作是在执行开始前捕捉这些问题，而不是事后。
|
||||
|
||||
### Execute
|
||||
|
||||
执行运行计划。每个执行器获得一个全新的 200k token 上下文窗口，其中精确加载了它所需的内容：项目摘要、阶段上下文、研究结果，以及其任务对应的特定 `PLAN.md`。仅此而已。
|
||||
|
||||
执行器编写代码并原子性地提交。每次提交对应计划中的一个已完成任务。当一波并行执行器完成时，协调器合并其状态并开始下一波。
|
||||
|
||||
执行器的全新上下文不是便利设施——它是防止上下文腐化的机制。一个带着 180k token 积累会话历史运行的执行器是一个性能退化的执行器。一个干净启动、只读取其计划所需内容的执行器，是以满状态运行的执行器。
|
||||
|
||||
### Verify
|
||||
|
||||
所有执行器完成后，一个验证器代理读取阶段目标、`CONTEXT.md` 决策、计划和执行摘要——并检查构建的内容是否与预期相符。它生成 `VERIFICATION.md`，如果存在差异，则生成有针对性的修复计划。
|
||||
|
||||
验证不仅仅是测试。它检查需求覆盖率（所有 REQ-ID 都被处理了吗？）、决策覆盖率（`CONTEXT.md` 中记录的决策是否实际实现了？），以及整体阶段目标对齐情况。阶段完成不是因为执行没有报错。而是因为构建的内容符合计划，计划的内容符合决策。
|
||||
|
||||
### Ship
|
||||
|
||||
Ship 步骤创建拉取请求并归档阶段产出物。`STATE.md` 更新以标记阶段完成。循环随后为下一个阶段重新开始。
|
||||
|
||||
---
|
||||
|
||||
## 里程碑与阶段
|
||||
|
||||
**里程碑**是一个版本周期——项目有意义的、可发布的增量。它有名称、版本号，以及定义其必须交付内容的一组需求。当里程碑的所有阶段都已发布且需求都已覆盖时，里程碑才算完成。
|
||||
|
||||
**阶段**是里程碑中的一个工作单元。阶段有目标、它所处理的一组需求，以及实现它的一组计划。
|
||||
|
||||
这种关系很重要，因为里程碑和阶段有不同的关注范围。里程碑问："这个版本的产品能做什么，不能做什么？"阶段问："下一个我们可以研究、规划、执行和验证的有边界的事情是什么？"
|
||||
|
||||
里程碑边界划定在自然产品边界处——一个可部署的 API、一个可用的 UI 流程、一个完整的数据模型。阶段边界划定在可以在一次循环中安全执行而不使循环变得笨重的工作量极限处。
|
||||
|
||||
---
|
||||
|
||||
## 什么是好的阶段范围
|
||||
|
||||
这值得深入探讨，因为它是循环中最常见的摩擦来源。
|
||||
|
||||
阶段太大会变成一个独立的研究项目。规划器难以将其分解为独立计划。后续波次的执行器被阻塞，等待前面的波次。验证变成全面审计而非有针对性的审查。反馈周期从数小时延伸到数天，而在大量代码编写后期才发现根本性设计错误的风险急剧上升。
|
||||
|
||||
阶段太小则会将本属于一体的工作碎片化。你最终会得到只有几行的计划文件、在几分钟内完成的阶段，以及规划开销远超执行成本的局面。循环感觉像官僚主义而非帮助。
|
||||
|
||||
好的阶段范围具备以下特征：
|
||||
|
||||
- 目标可以用一句话表述，既不显然琐碎，也不可疑宽泛。
|
||||
- 规划所需的研究是有边界的——生态系统问题有答案，且不依赖于其他阶段的先行完成。
|
||||
- 执行可以并行化为少数几个不重叠的计划，而不是几十个。
|
||||
- 有清晰的、可测试的完成定义，验证器无需阅读整个代码库即可检查。
|
||||
|
||||
具体来说："添加 HMAC-SHA256 签名验证中间件"是一个好的阶段范围。"构建认证系统"通常不是——它几乎总是包含多个独立关注点，作为单独阶段会更好。"修复 README 中的拼写错误"低于循环能增添价值的门槛；请使用 `/gsd-quick` 代替。
|
||||
|
||||
有疑问时，拆分。更小的阶段完成得更快，验证更有把握，当设计决策被证明有误时也更容易纠偏。
|
||||
|
||||
---
|
||||
|
||||
## `.planning/` 如何在循环中保持状态
|
||||
|
||||
循环不是单次会话。研究、规划和执行可能跨越多个会话，中间有上下文重置。`.planning/` 目录使这成为可能。
|
||||
|
||||
循环的每个步骤都读取早期步骤产生的产出物，并为后续步骤写入产出物。Discuss 步骤生成的 CONTEXT.md 在规划器运行时仍然可用——即使那是数小时后的不同会话。规划器生成的 PLAN.md 文件在执行器运行时仍然可用——即使跨越重启。验证器写入的 VERIFICATION.md 在你审查阶段时仍然可用。
|
||||
|
||||
`STATE.md` 是凌驾于这一切之上的导航层。它精确记录项目当前在循环中所处的位置：哪个里程碑处于活动状态，哪个阶段正在进行，哪些计划已完成，哪些待处理。任何需要定向的代理或工作流都首先读取 `STATE.md`。
|
||||
|
||||
有关这些文件的精确结构，请参见[规划产出物](../reference/planning-artifacts.md)和 [STATE.md 架构](../reference/state-md.md)。
|
||||
|
||||
---
|
||||
|
||||
## 循环是一种节奏，而非约束
|
||||
|
||||
很容易将循环视为官僚主义——一组你在被允许编写代码之前必须执行的步骤。这种框架是错误的。
|
||||
|
||||
循环之所以存在，是因为每个步骤都能防范在事后修复真正代价高昂的失败。Discuss 防止在错误假设上规划。Plan 防止执行从根本上存在缺陷的设计。Verify 防止发布偏离了需求的工作。这些不是人为制造的问题。它们是真实功能规模的 AI 辅助开发的实际失败模式。
|
||||
|
||||
循环运行良好时，感觉像是一种节奏：有节奏的专注、有边界的工作，每个步骤都清晰，因为上一步骤做好了它的工作。开销是真实的，但它是前置支付的——用几分钟规划换取而不是数小时返工。
|
||||
|
||||
对于低于循环门槛的工作，GSD Core 提供更轻量的原语。阶段循环是一种工具，而非唯一工具。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [上下文工程](context-engineering.md) — 为什么全新上下文子代理能防止使循环成为必要的质量退化
|
||||
- [讨论一个阶段](../how-to/discuss-a-phase.md)
|
||||
- [规划一个阶段](../how-to/plan-a-phase.md)
|
||||
- [执行一个阶段](../how-to/execute-a-phase.md)
|
||||
- [验证与发布](../how-to/verify-and-ship.md)
|
||||
- [规划产出物](../reference/planning-artifacts.md)
|
||||
- [STATE.md 架构](../reference/state-md.md)
|
||||
- [文档索引](../README.md)
|
||||
218
docs/zh-CN/how-to/configure-model-profiles.md
Normal file
218
docs/zh-CN/how-to/configure-model-profiles.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 如何配置模型配置文件
|
||||
|
||||
为您的项目选择合适的模型层级策略，然后在不编写大型覆盖块的情况下调整单个代理或整个阶段类型。本指南从最简单的控制选项开始，逐步介绍到动态路由。
|
||||
|
||||
---
|
||||
|
||||
## 四种配置文件（以及 `adaptive` 和 `inherit`）
|
||||
|
||||
在 `.planning/config.json` 中设置 `model_profile`，或通过 `/gsd-config --profile <name>` 设置：
|
||||
|
||||
| 配置文件 | 规划器 | 执行器 | 研究员 | 验证器 | 适用场景 |
|
||||
|---------|---------|----------|-------------|----------|----------|
|
||||
| `quality` | Opus | Opus | Opus | Sonnet | 对成本要求较低、注重生产质量的工作 |
|
||||
| `balanced` | Opus | Sonnet | Sonnet | Sonnet | 常规开发——默认选项 |
|
||||
| `budget` | Sonnet | Sonnet | Haiku | Haiku | 快速原型开发、成本敏感场景 |
|
||||
| `adaptive` | Opus | Sonnet | Sonnet | Sonnet | 与其他层级在运行时感知配置文件下的解析方式相同；在频繁切换运行时环境时使用 |
|
||||
| `inherit` | （会话模型） | （会话模型） | （会话模型） | （会话模型） | 非 Anthropic 提供商（OpenRouter、本地模型）——所有代理遵循当前会话模型 |
|
||||
|
||||
上表展示的是代表性子集。全部 33 个内置代理在 `sdk/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
|
||||
```
|
||||
|
||||
**或直接编辑 `.planning/config.json`：**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_profile": "balanced"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 按代理覆盖（`model_overrides`）
|
||||
|
||||
如果某个代理需要不同的层级而不想更改整个配置文件，请使用 `model_overrides`：
|
||||
|
||||
```json
|
||||
{
|
||||
"model_profile": "balanced",
|
||||
"model_overrides": {
|
||||
"gsd-executor": "opus",
|
||||
"gsd-codebase-mapper": "haiku"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
有效值：`opus`、`sonnet`、`haiku`、`inherit`，或任何完全限定的模型 ID（例如 `"openai/o3"`、`"google/gemini-2.5-pro"`）。
|
||||
|
||||
`model_overrides` 可在 `.planning/config.json` 中按项目设置，也可在 `~/.gsd/defaults.json` 中全局设置。项目级条目在冲突时优先；不冲突的全局条目会被保留。
|
||||
|
||||
**关于 Codex 和 OpenCode 的重要说明：** 这些运行时会在安装时将解析后的模型嵌入每个代理的静态配置中。编辑 `model_overrides` 后，需重新运行安装程序使更改生效：
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --codex --global # or --opencode, --kilo, etc.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 按阶段类型设置模型（`models`）
|
||||
|
||||
如果您希望在不学习全部 33 个代理名称的情况下实现"规划阶段用 Opus、其余用 Sonnet"的效果，请使用 `models` 块。它将六种阶段类型映射到层级别名：
|
||||
|
||||
```json
|
||||
{
|
||||
"model_profile": "balanced",
|
||||
"models": {
|
||||
"planning": "opus",
|
||||
"discuss": "opus",
|
||||
"research": "sonnet",
|
||||
"execution": "opus",
|
||||
"verification": "sonnet",
|
||||
"completion": "sonnet"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
阶段类型及其对应的代理：
|
||||
|
||||
| 阶段类型 | 涵盖的代理 |
|
||||
|---|---|
|
||||
| `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` |
|
||||
| `discuss`、`completion` | 保留——目前无子代理；已被模式接受以备向后兼容 |
|
||||
|
||||
`models` 块仅接受层级别名（`opus`、`sonnet`、`haiku`、`inherit`）。如需使用完全限定的模型 ID，请改用按代理设置的 `model_overrides`。
|
||||
|
||||
**将 `models` 与按代理例外结合使用：**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_profile": "balanced",
|
||||
"models": {
|
||||
"research": "sonnet"
|
||||
},
|
||||
"model_overrides": {
|
||||
"gsd-codebase-mapper": "haiku"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
全部五个研究代理解析为 `sonnet`，*除* `gsd-codebase-mapper` 被固定为 `haiku` 之外。
|
||||
|
||||
---
|
||||
|
||||
## 动态路由——默认使用低成本层级，失败时升级
|
||||
|
||||
如果您希望默认使用较低成本的层级，仅在代理未通过质量门控时才升级，请启用 `dynamic_routing`：
|
||||
|
||||
```json
|
||||
{
|
||||
"dynamic_routing": {
|
||||
"enabled": true,
|
||||
"tier_models": {
|
||||
"light": "haiku",
|
||||
"standard": "sonnet",
|
||||
"heavy": "opus"
|
||||
},
|
||||
"escalate_on_failure": true,
|
||||
"max_escalations": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
每个代理都有一个默认层级（`light`、`standard` 或 `heavy`）。第一次尝试时，GSD Core 选择 `tier_models[default_tier]`。如果编排器检测到软失败（验证不确定、计划检查被标记等），则将代理提升一级重新启动。`max_escalations` 限制总重试次数。
|
||||
|
||||
已处于 `heavy` 层级的代理无法进一步升级。
|
||||
|
||||
**在保留动态解析的同时关闭升级：**
|
||||
|
||||
```json
|
||||
{
|
||||
"dynamic_routing": {
|
||||
"enabled": true,
|
||||
"escalate_on_failure": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
无论结果如何，每次尝试都使用 `tier_models[default_tier]`——适用于希望明确指定层级到模型的映射但不需要升级行为的场景。
|
||||
|
||||
`dynamic_routing` **默认禁用**。省略该块或设置 `enabled: false` 将保留静态解析。
|
||||
|
||||
---
|
||||
|
||||
## 在非 Anthropic 运行时上使用 GSD Core
|
||||
|
||||
如果您为 Codex、OpenCode、Gemini CLI 或 Kilo 安装了 GSD Core，安装程序已在您的配置中设置了 `resolve_model_ids: "omit"`。这告知 GSD Core 跳过 Anthropic 模型 ID 解析，让运行时选择其自己的默认模型。基本情况下无需手动设置。
|
||||
|
||||
**如果您希望在 Codex 上使用分层模型：**
|
||||
|
||||
```json
|
||||
{
|
||||
"runtime": "codex",
|
||||
"model_profile": "balanced"
|
||||
}
|
||||
```
|
||||
|
||||
GSD Core 将每个层级别名解析为运行时层级映射中定义的 Codex 原生模型和推理力度。
|
||||
|
||||
**如果您希望在任意非 Claude 运行时上使用按代理模型 ID：**
|
||||
|
||||
```json
|
||||
{
|
||||
"resolve_model_ids": "omit",
|
||||
"model_overrides": {
|
||||
"gsd-planner": "o3",
|
||||
"gsd-executor": "o4-mini",
|
||||
"gsd-debugger": "o3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
有关完整的运行时感知配置文件参考及 `model_policy` 接口（v1.42 中新增的提供商中立预设），请参阅[配置参考——模型配置文件](../CONFIGURATION.md#model-profiles)。
|
||||
|
||||
---
|
||||
|
||||
## 解析优先级（从高到低）
|
||||
|
||||
当多个层级同时适用时，解析器选取优先级最高的条目：
|
||||
|
||||
```text
|
||||
1. model_overrides[<agent>] — per-agent; full IDs; targeted exception
|
||||
2. dynamic_routing.tier_models[<tier>] — when enabled; escalates on soft failure
|
||||
3. models[<phase_type>] — coarse phase-level tier
|
||||
4. model_profile (per-agent column) — global tier strategy
|
||||
5. Runtime default — when nothing else applies
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 选择合适的控制选项
|
||||
|
||||
| 您的需求 | 使用 |
|
||||
|---|---|
|
||||
| 对所有代理采用统一的层级策略 | `model_profile` |
|
||||
| 粗粒度的阶段级调整（"规划阶段用 Opus"） | `models.<phase_type>` |
|
||||
| 按代理精细控制（"强制代码库映射器使用 Haiku"） | `model_overrides[<agent>]` |
|
||||
| 为特定代理指定完全限定的模型 ID | `model_overrides[<agent>]: "openai/gpt-5"` |
|
||||
| 默认低成本，仅在失败时升级 | `dynamic_routing` |
|
||||
| 所有代理遵循会话模型（非 Anthropic 提供商） | `model_profile: "inherit"` |
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [配置参考](../CONFIGURATION.md)
|
||||
- [多代理编排](../explanation/multi-agent-orchestration.md)
|
||||
- [命令参考](../COMMANDS.md)
|
||||
- [文档索引](../README.md)
|
||||
178
docs/zh-CN/how-to/debug-a-failed-execution.md
Normal file
178
docs/zh-CN/how-to/debug-a-failed-execution.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# 如何调试失败的执行
|
||||
|
||||
**目标：** 在某个阶段执行失败、卡住或产生不完整工作时进行恢复，并在不丢失进度或重复已成功工作的情况下干净地继续。
|
||||
|
||||
**前提条件：** 您已运行 `/gsd-execute-phase N`，执行在写入 `VERIFICATION.md` 之前停止，或者您看到意外输出、缺少文件，或进度条卡住不动。
|
||||
|
||||
---
|
||||
|
||||
## 判断执行是卡住还是失败
|
||||
|
||||
在采取任何恢复操作之前，先确认实际发生了什么。
|
||||
|
||||
### 如果您看到"Spawning…"后超过 1–5 分钟没有输出
|
||||
|
||||
这是正常现象，并非冻结。GSD 子代理在独立的上下文窗口中运行。spawn 行上的存活注释可以确认这一点。请不要中断会话。
|
||||
|
||||
如果超过 10 分钟仍无结果，请检查 Claude Code 侧边栏。如果代理任务显示已完成但没有输出，结果可能在上下文切换中丢失——请重新运行相同的命令：
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1
|
||||
```
|
||||
|
||||
GSD 在分派执行器之前会检查 `SUMMARY.md` 文件。已有该文件的计划将被自动跳过。
|
||||
|
||||
### 如果执行在某个 wave 中途停止并显示错误信息
|
||||
|
||||
检查 git 历史记录，查看哪些计划已成功提交：
|
||||
|
||||
```bash
|
||||
git log --oneline -20
|
||||
```
|
||||
|
||||
已提交工作的计划会有类似 `feat(01-02): …` 的条目。没有提交的计划是不完整的，重新运行时会被重新执行。
|
||||
|
||||
### 如果执行器已提交代码但未写入 SUMMARY.md
|
||||
|
||||
GSD 会在下次运行时检测到这一情况，并弹出一个安全恢复确认界面，提供三个选项：
|
||||
|
||||
- **手动收尾** — 自行检查提交内容，写入 `SUMMARY.md`，然后重新运行。
|
||||
- **从头重新执行** — 在分派新执行器之前，回滚或覆盖部分提交。
|
||||
- **标记并跳过** — 记录异常并继续，仅在您明确确认后执行。
|
||||
|
||||
---
|
||||
|
||||
## 诊断根本原因
|
||||
|
||||
### 运行 `/gsd-debug --diagnose`
|
||||
|
||||
如果执行产生了错误输出、存根代码或验证失败，使用诊断模式进行调查，而不应用任何修复：
|
||||
|
||||
```bash
|
||||
/gsd-debug --diagnose "Phase 2 executor produced stubs instead of real code"
|
||||
```
|
||||
|
||||
`--diagnose` 在找到根本原因后停止，不修改您的文件。它会在 `.planning/debug/<slug>.md` 创建一个会话文件，以便您在需要时稍后继续调查。
|
||||
|
||||
要启动同时应用修复的完整调试会话：
|
||||
|
||||
```bash
|
||||
/gsd-debug "Login middleware not handling 401 correctly after phase 3"
|
||||
```
|
||||
|
||||
GSD 收集症状，使用科学方法进行结构化调查，并提出修复方案。如果您的配置中设置了 `tdd_mode: true`，则在应用任何修复之前需要先有一个失败的测试。
|
||||
|
||||
### 查看活动调试会话
|
||||
|
||||
```bash
|
||||
/gsd-debug list
|
||||
```
|
||||
|
||||
显示所有打开的会话及其当前假设和下一步操作。要恢复特定会话：
|
||||
|
||||
```bash
|
||||
/gsd-debug continue <slug>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 使用 `/gsd-forensics` 进行事后分析
|
||||
|
||||
如果根本原因从错误输出中无法判断——例如，计划引用了不存在的文件、执行产生了意外结果，或状态似乎已损坏——请运行取证调查：
|
||||
|
||||
```bash
|
||||
/gsd-forensics "Phase 3 execution stalled after wave 1"
|
||||
```
|
||||
|
||||
GSD 分析 git 历史记录、`.planning/` 制品完整性、STATE.md 一致性、未提交的工作和孤立的 worktree。它将结构化报告写入 `.planning/forensics/report-<timestamp>.md`，并给出推荐的修复步骤。
|
||||
|
||||
`/gsd-forensics` 是只读的——它不会修改您的项目文件。
|
||||
|
||||
**可检测的问题：**
|
||||
|
||||
- **卡死循环** — 同一文件在短时间内出现在三个或更多连续提交中（如果提交消息相似，则置信度为 HIGH）
|
||||
- **缺失制品** — 某阶段有提交但没有 `SUMMARY.md` 或 `VERIFICATION.md`
|
||||
- **遗弃的工作** — 存在未提交的更改，且 STATE.md 显示执行进行到一半，最后一次提交超过两小时前
|
||||
- **崩溃或中断** — 未提交的更改结合活动的执行状态和孤立的 worktree
|
||||
- **范围漂移** — 最近的提交触及了当前阶段预期文件集之外的文件
|
||||
|
||||
---
|
||||
|
||||
## 恢复后继续执行
|
||||
|
||||
一旦底层问题解决，重新运行执行命令：
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1
|
||||
```
|
||||
|
||||
GSD 会跳过 `SUMMARY.md` 已存在的计划，仅为剩余计划分派执行器。
|
||||
|
||||
如果您只需要重新执行特定的 wave：
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1 --wave 2
|
||||
```
|
||||
|
||||
如果您想在分派前验证 `.planning/` 的完整性：
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1 --validate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 使用 `/gsd-undo` 回滚
|
||||
|
||||
如果执行产生了您想完全丢弃的代码，请使用计划清单进行回滚，而不是手动 `git revert`：
|
||||
|
||||
### 回滚单个计划
|
||||
|
||||
```bash
|
||||
/gsd-undo --plan 03-02
|
||||
```
|
||||
|
||||
回滚阶段 `3` 中计划 `02` 的所有提交。GSD 在写入任何更改之前会显示确认界面。
|
||||
|
||||
### 回滚整个阶段
|
||||
|
||||
```bash
|
||||
/gsd-undo --phase 03
|
||||
```
|
||||
|
||||
回滚阶段 `3` 的所有提交。GSD 会检查后续阶段是否依赖该阶段，并在继续之前发出警告。
|
||||
|
||||
### 从最近的提交中交互式选择
|
||||
|
||||
```bash
|
||||
/gsd-undo --last 5
|
||||
```
|
||||
|
||||
显示最近五个 GSD 提交，让您选择要回滚的内容。
|
||||
|
||||
---
|
||||
|
||||
## 中断后恢复会话上下文
|
||||
|
||||
如果您在上下文重置或新会话后返回项目：
|
||||
|
||||
```bash
|
||||
/gsd-resume-work
|
||||
```
|
||||
|
||||
从上次交接中恢复您的完整会话上下文，包括当前阶段、阻塞项以及执行停止的位置。
|
||||
|
||||
或者，要查看当前进度并自动跳转到下一个正确步骤：
|
||||
|
||||
```bash
|
||||
/gsd-progress --next
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [执行阶段](execute-a-phase.md)
|
||||
- [恢复与故障排查](recover-and-troubleshoot.md)
|
||||
- [命令](../COMMANDS.md)
|
||||
- [文档索引](../README.md)
|
||||
149
docs/zh-CN/how-to/design-a-ui-phase.md
Normal file
149
docs/zh-CN/how-to/design-a-ui-phase.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# 如何为阶段设计 UI
|
||||
|
||||
**目标：** 生成一份已锁定的 UI 设计契约（`UI-SPEC.md`），在规划者编写任务之前，确定间距、颜色、字体和文案的决策，从而防止执行阶段因随意选择样式导致视觉不一致。
|
||||
|
||||
**前置条件：** `.planning/ROADMAP.md` 已存在，且该阶段包含前端或 UI 工作。强烈建议先运行 `/gsd-discuss-phase N`——UI 研究员会读取 `CONTEXT.md`，以避免重复询问您已经做出的决策。
|
||||
|
||||
---
|
||||
|
||||
## 判断此阶段是否需要 UI 契约
|
||||
|
||||
并非所有阶段都需要 `/gsd-ui-phase`。在以下情况下使用它：
|
||||
|
||||
- 该阶段引入新的 UI 界面（页面、流程、布局）
|
||||
- 将构建多个组件，且视觉一致性至关重要
|
||||
- 您正在为新项目的前端建立设计系统基线
|
||||
- 您正在为现有项目新增大量 UI 工作，希望在执行前锁定 token、间距和颜色
|
||||
|
||||
在以下情况下跳过它：
|
||||
|
||||
- 该阶段纯粹是后端、基础设施或数据工作，没有面向用户的输出
|
||||
- 早期阶段已存在 UI-SPEC.md，且此阶段在完全相同的视觉模式上构建，不引入新界面
|
||||
|
||||
如果不确定，安全门会提示您：当 `workflow.ui_safety_gate` 启用时（默认启用），`/gsd-plan-phase` 在检测到前端工作但没有 UI-SPEC.md 时会发出警告，并询问是否先运行 `/gsd-ui-phase`。
|
||||
|
||||
---
|
||||
|
||||
## 运行 UI 设计契约
|
||||
|
||||
```bash
|
||||
/gsd-ui-phase 2
|
||||
```
|
||||
|
||||
如果未指定阶段编号，GSD Core 会以当前阶段为目标。
|
||||
|
||||
该命令分两个阶段运行：
|
||||
|
||||
1. **`gsd-ui-researcher`** — 读取 `CONTEXT.md`、`RESEARCH.md` 和 `REQUIREMENTS.md` 中的已有决策，检测设计系统状态（shadcn `components.json`、Tailwind 配置、现有 token），并仅针对以下五个领域中尚未回答的设计问题进行提问：间距、颜色、字体、文案和注册表安全。
|
||||
2. **`gsd-ui-checker`** — 从六个维度验证生成的 `UI-SPEC.md`。如果发现问题，修订循环会重新运行研究员（最多两次迭代），专门针对被标记的项目。
|
||||
|
||||
**输出：** `.planning/phases/{phase-dir}/` 中的 `{padded_phase}-UI-SPEC.md`。
|
||||
|
||||
---
|
||||
|
||||
## UI-SPEC 涵盖的内容
|
||||
|
||||
研究员在五个领域锁定决策：
|
||||
|
||||
| 领域 | 示例 |
|
||||
|---|---|
|
||||
| **间距** | 基础比例（4px 或 8px）、网格对齐、组件内边距 |
|
||||
| **颜色** | 主色、强调色、中性色调色板；60/30/10 规则；深色模式考量 |
|
||||
| **字体** | 字体家族、字号/字重比例约束、标题层次结构 |
|
||||
| **文案** | CTA 标签、空状态消息、错误状态文案、加载指示器 |
|
||||
| **注册表安全** | shadcn 组件检查协议（见下文） |
|
||||
|
||||
检查器按六个支柱验证规格，每项评分 1–4：文案、视觉、颜色、字体、间距和体验设计（加载/错误/空状态覆盖）。
|
||||
|
||||
---
|
||||
|
||||
## shadcn 初始化
|
||||
|
||||
对于 React、Next.js 和 Vite 项目，若未找到 `components.json`，研究员会提议初始化 shadcn。流程如下：
|
||||
|
||||
1. 访问 `ui.shadcn.com/create`，配置您的预设（颜色、边框圆角、字体）
|
||||
2. 复制预设字符串
|
||||
3. 运行：
|
||||
|
||||
```bash
|
||||
npx shadcn init --preset <paste>
|
||||
```
|
||||
|
||||
预设字符串成为 GSD Core 规划产物中的一等公民，可在各阶段和里程碑间复现。
|
||||
|
||||
---
|
||||
|
||||
## 注册表安全门
|
||||
|
||||
第三方 shadcn 注册表可能注入任意代码。当 `workflow.ui_safety_gate` 启用时（默认启用），规格要求在安装任何非官方组件之前执行以下步骤：
|
||||
|
||||
```bash
|
||||
npx shadcn view <component> # inspect source before installing
|
||||
npx shadcn diff <component> # compare against the official registry
|
||||
```
|
||||
|
||||
如果未处理注册表安全问题，检查器会将规格标记为 BLOCKED。若您的项目不使用 shadcn，或您有其他审查流程，可通过 `/gsd-settings` 禁用此门控。
|
||||
|
||||
---
|
||||
|
||||
## 使用草图发现结果作为起点
|
||||
|
||||
如果您已运行 `/gsd-sketch --wrap-up`，UI 研究员会自动加载 `.claude/skills/sketch-findings-[project]/`。经过预验证的决策（布局、调色板、字体、间距）将被视为已锁定——研究员不会重新询问它们。运行开始时会显示一条提示：
|
||||
|
||||
```text
|
||||
⚡ Sketch findings detected: .claude/skills/sketch-findings-[project]/SKILL.md
|
||||
Pre-validated decisions (layout, palette, typography, spacing) should be treated
|
||||
as locked — not re-asked.
|
||||
```
|
||||
|
||||
这是在 `/gsd-ui-phase` 之前运行 `/gsd-sketch --wrap-up` 的主要原因：它将对话式的设计探索转化为具有约束力的契约输入。
|
||||
|
||||
---
|
||||
|
||||
## 使用 `/gsd-ui-review` 进行事后视觉审计
|
||||
|
||||
`/gsd-ui-review` 在执行之后运行，而非之前。用它来对照 UI-SPEC 审计已实现的前端（当没有规格时，则对照抽象的六支柱标准进行审计）。
|
||||
|
||||
```bash
|
||||
/gsd-ui-review # audit the current phase
|
||||
/gsd-ui-review 3 # audit phase 3 specifically
|
||||
```
|
||||
|
||||
它适用于任何包含前端代码的项目——不需要 GSD 项目初始化。
|
||||
|
||||
**检查内容（六支柱，每项评分 1–4）：**
|
||||
|
||||
1. 文案 — CTA 标签、空状态、错误状态
|
||||
2. 视觉 — 焦点、视觉层次、图标无障碍性
|
||||
3. 颜色 — 强调色使用规范、60/30/10 合规性
|
||||
4. 字体 — 字号和字重约束遵循情况
|
||||
5. 间距 — 网格对齐、token 一致性
|
||||
6. 体验设计 — 加载、错误和空状态覆盖
|
||||
|
||||
**输出：** `{padded_phase}-UI-REVIEW.md`，包含评分和前三项优先修复事项。当配置了 `gsd-browser` 等浏览器 MCP 服务器时，审计还会捕获截图作为视觉证据。
|
||||
|
||||
**截图存储：** 截图保存至 `.planning/ui-reviews/`。系统会自动创建 `.gitignore` 以防止二进制文件提交到 git。截图会在 `/gsd-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)
|
||||
```
|
||||
|
||||
`/gsd-ui-phase` 位于 discuss 和 plan 之间，因为规划者会将 `UI-SPEC.md` 作为设计上下文读取——`PLAN.md` 中的任务会引用规格锁定的间距 token、颜色变量和文案决策。
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Spike 与草图](spike-and-sketch.md)
|
||||
- [规划阶段](plan-a-phase.md)
|
||||
- [命令参考](../COMMANDS.md)
|
||||
- [文档索引](../README.md)
|
||||
158
docs/zh-CN/how-to/discuss-a-phase.md
Normal file
158
docs/zh-CN/how-to/discuss-a-phase.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# 如何讨论一个阶段
|
||||
|
||||
**目标：** 在规划开始之前收集某个阶段所需的实施决策，以便研究员和规划员无需再次询问您。
|
||||
|
||||
**前提条件：** `.planning/ROADMAP.md` 文件已存在。如果没有，请先运行 `/gsd-new-project`。
|
||||
|
||||
---
|
||||
|
||||
## 选择讨论模式
|
||||
|
||||
GSD Core 提供两种模式。根据对代码库的熟悉程度进行选择。
|
||||
|
||||
**如果您想预先表达自己的实施偏好**（访谈模式，默认）：
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 2
|
||||
```
|
||||
|
||||
Claude 会识别阶段范围中的模糊地带，让您选择要讨论的内容，然后针对每个领域处理大约四个问题。
|
||||
|
||||
**如果代码库已有明确的模式，且大多数问题对您来说显而易见**（假设模式）：
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
|
||||
/gsd-discuss-phase 2
|
||||
```
|
||||
|
||||
Claude 通过子代理读取 5–15 个相关代码库文件，形成带有证据和置信度级别的假设，并呈现给您确认或纠正。通常只需 2–4 次交互，而非 15–20 次。
|
||||
|
||||
切换回原模式：
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs config-set workflow.discuss_mode discuss
|
||||
```
|
||||
|
||||
请参阅[讨论模式说明](../workflow-discuss-mode.md)以获取完整对比，包括各模式可能节省时间的场景。
|
||||
|
||||
---
|
||||
|
||||
## 不经选择步骤直接讨论所有模糊地带
|
||||
|
||||
默认情况下，Claude 会呈现模糊地带并询问您希望覆盖哪些内容。如果您想跳过该选择提示，直接处理所有内容：
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 2 --all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 加快处理简单明了的阶段
|
||||
|
||||
**如果该阶段已充分理解，您希望 Claude 无需提示即可选择推荐的默认值：**
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 3 --auto
|
||||
```
|
||||
|
||||
Claude 为每个问题选择推荐答案并记录选择。适用于决策风险较低或已在先前阶段中隐含的阶段。
|
||||
|
||||
**如果您有远程会话限制（无 TUI 菜单）：**
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 2 --text
|
||||
```
|
||||
|
||||
所有提示将以纯文本编号列表的形式呈现，而不是交互式选择器。
|
||||
|
||||
---
|
||||
|
||||
## 分组处理问题
|
||||
|
||||
如果您希望一次回答多个问题，而不是逐一回答：
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 2 --batch
|
||||
```
|
||||
|
||||
Claude 每轮分组 2–5 个问题。
|
||||
|
||||
---
|
||||
|
||||
## 为每个问题添加权衡分析
|
||||
|
||||
如果您希望在做出决定之前查看选项对比表：
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 2 --analyze
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 从准备好的文件中批量回答
|
||||
|
||||
如果您已有准备好的答案文件，并希望一次性提交所有决策：
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 1 --power
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 在讨论之前查看 Claude 的假设
|
||||
|
||||
**如果您希望在任何交互式会话之前了解 Claude 的假设和计划** — 适用于在投入讨论时间之前验证对齐情况：
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 3 --assumptions
|
||||
```
|
||||
|
||||
Claude 输出其假设（附带代码库证据和置信度级别）后退出。不会写入 CONTEXT.md。查看输出后，如有需要纠正的内容，再运行正常的讨论或假设模式会话。
|
||||
|
||||
---
|
||||
|
||||
## CONTEXT.md 的内容
|
||||
|
||||
讨论模式和假设模式都会在阶段目录中生成相同的 `{phase}-CONTEXT.md`。下游代理（研究员、规划员、计划检查员）以相同方式读取该文件，无论由哪种模式生成。它包含六个部分：
|
||||
|
||||
| 部分 | 用途 |
|
||||
|---|---|
|
||||
| `<domain>` | 阶段边界 — 本阶段交付的内容 |
|
||||
| `<decisions>` | 会话中锁定的实施决策 |
|
||||
| `<canonical_refs>` | 下游代理必须阅读的规格说明、ADR 和文档 |
|
||||
| `<code_context>` | 可复用资产、模式和集成点 |
|
||||
| `<specifics>` | 用户参考资料和偏好 |
|
||||
| `<deferred>` | 记录留待未来阶段处理的想法 |
|
||||
|
||||
`<canonical_refs>` 部分是必填项。如果您在讨论中引用了某个文档、规格说明或 ADR，Claude 会立即将其添加并读取，以便为后续问题提供参考。
|
||||
|
||||
请参阅 [CONTEXT.md 模式](../reference/context-md.md)以获取完整的字段参考。
|
||||
|
||||
---
|
||||
|
||||
## 决策如何影响规划
|
||||
|
||||
当您接下来运行 `/gsd-plan-phase` 时，规划员会读取 CONTEXT.md 以了解哪些决策已锁定。它不会重新询问此处已回答的问题。研究员会首先读取该文件以了解需要调查的内容。
|
||||
|
||||
**如果运行 `/gsd-plan-phase` 时 CONTEXT.md 缺失**，系统将提供两种选择：不使用上下文继续（计划仅使用研究和需求，不包含您的设计偏好），或先运行 `/gsd-discuss-phase`。
|
||||
|
||||
---
|
||||
|
||||
## 如果您已有 PRD 或验收标准文档
|
||||
|
||||
完全跳过 discuss-phase，直接进入规划：
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1 --prd path/to/prd.md
|
||||
```
|
||||
|
||||
规划员会从 PRD 综合生成 CONTEXT.md，并将所有需求视为锁定决策。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [规划一个阶段](plan-a-phase.md)
|
||||
- [讨论模式](../workflow-discuss-mode.md)
|
||||
- [CONTEXT.md 模式](../reference/context-md.md)
|
||||
- [文档索引](../README.md)
|
||||
176
docs/zh-CN/how-to/drive-gsd-from-a-tracker-issue.md
Normal file
176
docs/zh-CN/how-to/drive-gsd-from-a-tracker-issue.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# 如何从追踪器议题驱动 GSD Core
|
||||
|
||||
**目标：** 将一个范围明确的 GitHub、Linear 或 Jira 议题，通过完整的 GSD 流水线从隔离工作区推进至合并 PR——仅使用 GSD Core 中已有的命令，无需任何自定义脚本或追踪器集成。
|
||||
|
||||
**前提条件：** GSD Core 已安装。议题范围有边界、验收标准可观测，且无上游阻塞依赖。
|
||||
|
||||
有关该模式背后的概念与设计理由，请参阅[议题驱动编排详解](../issue-driven-orchestration.md)。
|
||||
|
||||
---
|
||||
|
||||
## 第一步：将议题映射到阶段
|
||||
|
||||
打开追踪器议题，决定它如何对应 `ROADMAP.md` 中的阶段：
|
||||
|
||||
- **议题与现有阶段匹配** → 记下阶段编号，转至第二步。
|
||||
- **议题是独立的新工作** → 添加一个阶段：
|
||||
|
||||
```bash
|
||||
/gsd-phase "描述与议题标题一致的内容"
|
||||
```
|
||||
|
||||
- **议题紧急，必须插入现有阶段之间** → 插入一个小数阶段：
|
||||
|
||||
```bash
|
||||
/gsd-phase --insert 3 "Fix: 来自议题的描述"
|
||||
```
|
||||
|
||||
复制追踪器议题的 URL。您将在第三步中将其粘贴到 `CONTEXT.md`，以便在上下文压缩后仍保留可追溯性。
|
||||
|
||||
---
|
||||
|
||||
## 第二步：创建隔离工作区
|
||||
|
||||
每个议题都有专属工作区——一个带有独立 `.planning/` 目录的 git worktree。未完成的工作、中止的计划和探索性提交均保留在 `main` 之外。
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name my-issue-slug --repos . --strategy worktree
|
||||
```
|
||||
|
||||
继续操作前，切换到工作区目录：
|
||||
|
||||
```bash
|
||||
cd ~/gsd-workspaces/my-issue-slug
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第三步：讨论阶段
|
||||
|
||||
运行 discuss-phase，在规划开始之前确定实现决策。会话打开后，将追踪器议题 URL 粘贴到讨论中，以便记录到 `CONTEXT.md`。
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase N
|
||||
```
|
||||
|
||||
GSD 会就议题范围中的模糊点进行提问——错误处理、边界情况、接口契约、技术选型。您的回答将影响后续生成的计划。
|
||||
|
||||
如果您已知晓所有答案并希望快速推进：
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase N --auto
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第四步：规划阶段
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase N
|
||||
```
|
||||
|
||||
GSD 会派生研究代理，读取您的 `CONTEXT.md` 决策（包括议题 URL），并生成原子化的 `PLAN.md` 文件。计划检查器会在保存前验证每份计划。
|
||||
|
||||
如果您希望在执行前由外部 AI CLI 进行同行评审（对于重大变更推荐使用）：
|
||||
|
||||
```bash
|
||||
/gsd-review --phase N
|
||||
/gsd-plan-phase N --reviews
|
||||
```
|
||||
|
||||
或运行完整的计划-评审-收敛循环，直到不再有 HIGH 级别的问题：
|
||||
|
||||
```bash
|
||||
/gsd-plan-review-convergence N
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第五步：执行阶段
|
||||
|
||||
交互式逐阶段执行：
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase N
|
||||
```
|
||||
|
||||
无人值守地运行所有剩余阶段：
|
||||
|
||||
```bash
|
||||
/gsd-autonomous
|
||||
```
|
||||
|
||||
在可视化仪表盘中监控进度并跨阶段调度工作：
|
||||
|
||||
```bash
|
||||
/gsd-manager
|
||||
```
|
||||
|
||||
三种方式均会更新 `STATE.md`，原子化提交每项任务，并运行阶段后验证器。
|
||||
|
||||
---
|
||||
|
||||
## 第六步：验证工作
|
||||
|
||||
```bash
|
||||
/gsd-verify-work N
|
||||
```
|
||||
|
||||
GSD 会逐条引导您核对阶段目标中的验收标准（与追踪器议题对应）。如有失败，GSD 会诊断根本原因并创建修复计划。重复执行和重新验证，直到所有检查通过。
|
||||
|
||||
即使代码看起来正确，也应将 `verification_failed` 视为阻塞——失败通常会揭示原始议题中遗漏的验收标准。
|
||||
|
||||
---
|
||||
|
||||
## 第七步：评审与发布
|
||||
|
||||
在开启 PR 前先进行代码评审：
|
||||
|
||||
```bash
|
||||
/gsd-code-review N
|
||||
/gsd-code-review N --fix
|
||||
```
|
||||
|
||||
然后创建 PR：
|
||||
|
||||
```bash
|
||||
/gsd-ship N
|
||||
```
|
||||
|
||||
GSD 会从您的规划产物中组装 PR 正文：阶段目标、变更摘要、已满足的需求、验证状态和关键决策。在 PR 正文中加入 `Closes #NNN` 或 `Fixes #NNN`（或通过 `/gsd-config` 设置），以便在 PR 合并时自动关闭追踪器议题。
|
||||
|
||||
---
|
||||
|
||||
## 第八步：记录后续工作
|
||||
|
||||
在处理议题的过程中，您常常会发现相关工作。在不丢失上下文的情况下进行记录：
|
||||
|
||||
```bash
|
||||
/gsd-capture "Follow-up: 发现的工作描述" # 作为待办事项添加
|
||||
/gsd-capture --seed "值得未来阶段考虑的想法" # 为下一个里程碑保留
|
||||
/gsd-capture --backlog "不紧急但值得跟踪的内容" # 存入待办列表
|
||||
```
|
||||
|
||||
GSD 不会自动向追踪器发布内容。从已记录的后续工作中创建追踪器议题是独立的手动步骤——这保留了人工审核的环节。
|
||||
|
||||
---
|
||||
|
||||
## 条件场景
|
||||
|
||||
| 情境 | 处理方式 |
|
||||
|-----------|-----------|
|
||||
| 议题非常小（拼写错误、配置变更） | 跳过工作区 + 讨论 + 规划；改用 `/gsd-quick` |
|
||||
| 议题包含多个独立子任务 | 使用 `/gsd-manager` 跨计划并行执行 |
|
||||
| 议题被其他议题阻塞 | 在上游阻塞解除前不要开始；GSD 没有自动依赖轮询 |
|
||||
| 执行中途发现议题范围比预期大 | 停止，运行 `/gsd-phase --insert N` 添加子阶段，然后继续 |
|
||||
| 想跳过交互式讨论 | 对 `/gsd-discuss-phase` 使用 `--auto` 标志，或为项目级自动化设置 `workflow.skip_discuss: true` |
|
||||
| 多个议题构成一个连贯的发布版本 | 运行 `/gsd-new-milestone` 将其分组，并运行 `/gsd-autonomous` 按顺序执行 |
|
||||
|
||||
---
|
||||
|
||||
## 相关资源
|
||||
|
||||
- [议题驱动编排详解](../issue-driven-orchestration.md)
|
||||
- [使用工作区隔离工作](isolate-work-with-workspaces.md)
|
||||
- [验证与发布](verify-and-ship.md)
|
||||
- [文档索引](../README.md)
|
||||
119
docs/zh-CN/how-to/execute-a-phase.md
Normal file
119
docs/zh-CN/how-to/execute-a-phase.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# 如何执行阶段
|
||||
|
||||
**目标：** 通过基于波次的并行执行来运行已规划的阶段，并将每个计划作为原子性 git 提交落地。
|
||||
|
||||
**前置条件：** 该阶段至少有一个 `PLAN.md` 文件。如果规划尚未完成，请先运行 `/gsd-plan-phase N` —— 参见[规划阶段](plan-a-phase.md)。
|
||||
|
||||
---
|
||||
|
||||
## 运行完整阶段
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1
|
||||
```
|
||||
|
||||
GSD Core 读取阶段的计划文件，将其按依赖关系分组为若干波次，并为每个计划生成独立的执行器代理。每个执行器在下一波次开始前以原子方式提交其工作。
|
||||
|
||||
在分发任何代理之前，GSD Core 会打印波次表：
|
||||
|
||||
```
|
||||
## Execution Plan
|
||||
|
||||
Phase 1: Core middleware — 3 plans across 2 wave(s)
|
||||
|
||||
| Wave | Plans | What it builds |
|
||||
|------|----------------|---------------------------|
|
||||
| 1 | 01-01, 01-02 | Core validation function |
|
||||
| 2 | 01-03 | Express middleware wrapper |
|
||||
```
|
||||
|
||||
第 1 波次的计划并行运行（每个在独立的 git 工作树中）。第 2 波次等待所有第 1 波次提交合并后才开始。
|
||||
|
||||
关于底层代理协调模型，请参见[多代理编排](../explanation/multi-agent-orchestration.md)。
|
||||
|
||||
---
|
||||
|
||||
## 运行单个波次
|
||||
|
||||
如果只想执行一个波次——例如，在进入第 2 波次之前先检查第 1 波次的输出——请使用 `--wave N`：
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1 --wave 2
|
||||
```
|
||||
|
||||
GSD Core 仅执行第 2 波次的计划。它会首先检查所有较早波次是否已完成；如果任何第 1 波次计划仍标记为未完成，则会停止并提示你先完成较早波次。
|
||||
|
||||
---
|
||||
|
||||
## 执行前验证状态
|
||||
|
||||
如果你怀疑 `.planning/` 目录与文件系统不同步——例如在崩溃或上一次运行中断之后——请传入 `--validate`：
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1 --validate
|
||||
```
|
||||
|
||||
GSD Core 在生成任何执行器之前运行状态一致性检查。检测到的偏差会被上报，你可以在继续之前接受或纠正。
|
||||
|
||||
---
|
||||
|
||||
## 恢复停滞的执行
|
||||
|
||||
如果执行中途停止——配额错误、网络断开或会话崩溃——波次级别的进度会被保留。GSD Core 会检查每个计划的 `SUMMARY.md` 文件；已有该文件的计划在重新运行时会自动跳过：
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1
|
||||
```
|
||||
|
||||
GSD Core 会跳过 `SUMMARY.md` 已存在的计划，并从第一个未完成的计划继续。
|
||||
|
||||
**如果提交存在但 `SUMMARY.md` 缺失**（执行器已提交，但在会话结束前未写入摘要），GSD Core 会弹出一个安全恢复门并提供三个选项：
|
||||
|
||||
- `close out manually` — 检查提交，手动编写 `SUMMARY.md`，然后重新运行。
|
||||
- `re-execute from scratch` — 在分发新执行器前回滚或替代部分提交。
|
||||
- `mark-and-skip` — 记录异常并继续，仅在明确确认后执行。
|
||||
|
||||
关于系统性故障诊断，请参见[调试失败的执行](debug-a-failed-execution.md)。
|
||||
|
||||
---
|
||||
|
||||
## 输出位置
|
||||
|
||||
所有波次完成后，阶段目录包含：
|
||||
|
||||
```
|
||||
.planning/phases/01-<name>/
|
||||
01-01-SUMMARY.md # What plan 01 built, key files, deviations
|
||||
01-02-SUMMARY.md
|
||||
01-03-SUMMARY.md
|
||||
VERIFICATION.md # Requirement-by-requirement pass/fail status
|
||||
```
|
||||
|
||||
所有波次完成后，`STATE.md` 和 `ROADMAP.md` 会自动更新。`VERIFICATION.md` 仅在阶段完全完成时写入。
|
||||
|
||||
Git 历史记录中每个任务会有一个提交（来自各执行器），随后是编排器的跟踪提交。
|
||||
|
||||
---
|
||||
|
||||
## 跨 AI 执行
|
||||
|
||||
要将执行委托给在 `workflow.cross_ai_command` 中配置的外部 AI CLI（Codex、Gemini 等）：
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 2 --cross-ai
|
||||
```
|
||||
|
||||
要在配置中启用跨 AI 时强制本地执行：
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 2 --no-cross-ai
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [规划阶段](plan-a-phase.md)
|
||||
- [验证与发布](verify-and-ship.md)
|
||||
- [调试失败的执行](debug-a-failed-execution.md)
|
||||
- [命令参考](../COMMANDS.md)
|
||||
121
docs/zh-CN/how-to/handle-quick-and-fast-tasks.md
Normal file
121
docs/zh-CN/how-to/handle-quick-and-fast-tasks.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# 如何处理快速轻量级任务
|
||||
|
||||
并非每项工作都需要完整的阶段流程。GSD 提供了两个轻量级命令，适用于不需要完整的讨论 → 计划 → 执行 → 验证循环的工作。
|
||||
|
||||
有关何时值得使用完整阶段流水线的说明，请参阅[上下文工程](../explanation/context-engineering.md)。
|
||||
|
||||
---
|
||||
|
||||
## 决定使用哪个命令
|
||||
|
||||
| 场景 | 命令 |
|
||||
|-----------|---------|
|
||||
| 修复 Bug、添加小功能，或任何无法概括为单一琐碎编辑的任务 | `/gsd-quick` |
|
||||
| 修复错别字、更新配置值、添加 `.gitignore` 条目，或任何涉及 ≤ 3 个文件且耗时不到一分钟的更改 | `/gsd-fast` |
|
||||
| 任务有未知因素、需要调研，或将涉及超过几个文件 | `/gsd-quick` 加 `--research` |
|
||||
|
||||
**经验法则：** 如果你哪怕有一刻犹豫该任务是否属于琐碎操作，就使用 `/gsd-quick`。当范围看起来不够简单时，`/gsd-fast` 会自动将你重定向到 `/gsd-quick`。
|
||||
|
||||
---
|
||||
|
||||
## `/gsd-quick` — 带有 GSD 保证的临时任务
|
||||
|
||||
`/gsd-quick` 运行一个规划器和执行器，提供与完整阶段相同的原子提交和 STATE.md 跟踪保证，但无需阶段开销（无 ROADMAP 条目、无讨论阶段、无跨多个计划的波次协调）。
|
||||
|
||||
### 基本用法
|
||||
|
||||
```bash
|
||||
/gsd-quick
|
||||
```
|
||||
|
||||
GSD 会提示你输入任务描述，然后进行规划和执行。产出物保存在 `.planning/quick/` 中。
|
||||
|
||||
你也可以直接传入描述：
|
||||
|
||||
```bash
|
||||
/gsd-quick "Fix the login button not responding on mobile Safari"
|
||||
```
|
||||
|
||||
### 标志
|
||||
|
||||
当任务需要时，添加标志可引入更多质量流水线步骤。
|
||||
|
||||
| 标志 | 功能说明 |
|
||||
|------|-------------|
|
||||
| `--discuss` | 在规划器运行前进行轻量级的预规划讨论，梳理灰色地带并将决策记录到 `CONTEXT.md` 中 |
|
||||
| `--research` | 由专注的调研代理在规划前调查方案、库和潜在问题 |
|
||||
| `--validate` | 计划检查（最多 2 次迭代）加上执行后验证 |
|
||||
| `--full` | 以上全部 — 等同于 `--discuss --research --validate` |
|
||||
|
||||
标志可自由组合：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 何时添加标志
|
||||
|
||||
- 当你不确定如何处理任务或使用哪个库时，添加 `--research`。
|
||||
- 当任务涉及关键代码路径，且你希望验证代理确认必要条件已满足时，添加 `--validate`。
|
||||
- 当任务有设计选择需要在规划器运行前锁定时，添加 `--discuss`——例如，当正确的错误处理行为不够明显时。
|
||||
- 当任务确实比较重要，通常应作为阶段规划，但又不属于 ROADMAP 范畴时，使用 `--full`。
|
||||
|
||||
### 列出和恢复快速任务
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/gsd-fast` — 内联琐碎编辑
|
||||
|
||||
`/gsd-fast` 直接在当前上下文中完成工作。没有子代理、没有 `PLAN.md`，也没有调研。它仅适用于你自己在一分钟内即可完成的更改。
|
||||
|
||||
```bash
|
||||
/gsd-fast "fix typo in README"
|
||||
/gsd-fast "add .env to .gitignore"
|
||||
```
|
||||
|
||||
如果你省略描述，GSD 会提示你输入。
|
||||
|
||||
`/gsd-fast` 在继续操作前会检查任务是否确实属于琐碎操作。如果判断范围过大，它会停止并重定向你：
|
||||
|
||||
```text
|
||||
This looks like it needs planning. Use /gsd-quick instead:
|
||||
/gsd-quick "your task description"
|
||||
```
|
||||
|
||||
完成更改后，`/gsd-fast` 以原子方式提交，并且如果 `.planning/STATE.md` 中存在 `Quick Tasks Completed` 表格，则向其追加一行。
|
||||
|
||||
---
|
||||
|
||||
## `/gsd-quick` 相比 `/gsd-fast` 多提供的能力
|
||||
|
||||
| 能力 | `/gsd-fast` | `/gsd-quick` |
|
||||
|------------|------------|--------------|
|
||||
| 子代理规划器 | 否 | 是 |
|
||||
| 子代理执行器 | 否 | 是 |
|
||||
| 调研代理 | 否 | 可选（`--research`） |
|
||||
| 计划检查 | 否 | 可选（`--validate`） |
|
||||
| 执行后验证 | 否 | 可选（`--validate`） |
|
||||
| 讨论阶段 | 否 | 可选（`--discuss`） |
|
||||
| 工作树隔离 | 否 | 是（默认） |
|
||||
| 每任务原子提交 | 单次提交 | 每个计划任务一次 |
|
||||
| STATE.md 跟踪 | 若表格存在则追加行 | 始终更新 |
|
||||
| `.planning/quick/` 产出物 | 否 | 是 |
|
||||
|
||||
关键区别在于子代理隔离。`/gsd-quick` 在独立的上下文窗口中启动全新的规划器和执行器，这意味着工作会被妥善规划，提交按任务原子化，且编排器可验证结果。`/gsd-fast` 仅使用当前上下文窗口，有意限制于无需上述任何流程的琐碎更改。
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [阶段循环](../explanation/the-phase-loop.md)
|
||||
- [上下文工程](../explanation/context-engineering.md)
|
||||
- [命令参考](../COMMANDS.md)
|
||||
- [文档索引](../README.md)
|
||||
291
docs/zh-CN/how-to/install-on-your-runtime.md
Normal file
291
docs/zh-CN/how-to/install-on-your-runtime.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# 如何在您的运行时上安装 GSD Core
|
||||
|
||||
将 GSD Core（`@opengsd/gsd-core`）安装到您日常使用的 AI 编码运行时中。本指南提供各支持运行时的标准安装路径，以及适用于未安装 Node.js 的机器的手动安装路径。
|
||||
|
||||
**所需条件：** Node.js 18+ 及 npm（或 npx）。如果您没有 Node.js，请跳转至[不使用 Node.js 安装](#不使用-nodejs-安装)。
|
||||
|
||||
---
|
||||
|
||||
## 为什么需要安装程序
|
||||
|
||||
GSD Core 以 Claude Code 原生 frontmatter 格式分发代理和命令文件。每个支持的运行时需要不同的 schema、目录结构和命令调用语法。安装程序负责执行必要的转换——例如，为 OpenCode 转换工具列表和颜色值、为 Codex 写入 TOML 代理条目，以及将所有命令体从连字符格式（`/gsd-update`）重写为冒号格式（`/gsd:update`）以适配 Gemini CLI。
|
||||
|
||||
**请勿直接从 `agents/` 或 `commands/` 复制文件。** 这样做会绕过转换过程，导致 schema 验证错误或命令缺失。
|
||||
|
||||
---
|
||||
|
||||
## 标准安装
|
||||
|
||||
在任意目录运行安装程序。它会提示您选择运行时，以及是全局安装（所有项目）还是本地安装（仅此项目）。
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest
|
||||
```
|
||||
|
||||
这是全新安装或切换运行时后重新运行安装程序所需的唯一命令。
|
||||
|
||||
---
|
||||
|
||||
## 各运行时安装说明
|
||||
|
||||
### Claude Code
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --claude --global
|
||||
```
|
||||
|
||||
技能文件存放于 `~/.claude/`。下次 Claude Code 会话中，命令将以 `/gsd-*` 斜杠命令的形式出现。重启 Claude Code 以加载它们。
|
||||
|
||||
**覆盖安装目录：**
|
||||
|
||||
```bash
|
||||
CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Gemini CLI
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --gemini --global
|
||||
```
|
||||
|
||||
技能文件存放于 `~/.gemini/`。安装程序将所有命令体重写为 Gemini 的冒号命名空间格式（`/gsd:update`、`/gsd:config` 等）。安装后重启 Gemini CLI。
|
||||
|
||||
**覆盖安装目录：**
|
||||
|
||||
```bash
|
||||
GEMINI_CONFIG_DIR=~/.gemini-alt npx @opengsd/gsd-core@latest --gemini --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### OpenCode
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --opencode --global
|
||||
```
|
||||
|
||||
技能文件存放于 `~/.config/opencode/`（XDG）或 `~/.opencode/`。安装程序将代理 frontmatter 转换为 OpenCode 的 schema——移除 `tools:` 字段并将颜色值转换为十六进制格式。如需了解具体变更内容，请参阅[不使用 Node.js 安装 — OpenCode 转换](#opencode--必要转换)。
|
||||
|
||||
**覆盖安装目录：**
|
||||
|
||||
```bash
|
||||
OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --opencode --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Kilo
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --kilo --global
|
||||
```
|
||||
|
||||
技能文件存放于 `~/.config/kilo/`（XDG）或 `~/.kilo/`。使用与 OpenCode 相同的平铺 Markdown 命令格式。
|
||||
|
||||
**覆盖安装目录：**
|
||||
|
||||
```bash
|
||||
KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Codex
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --codex --global
|
||||
```
|
||||
|
||||
技能文件存放于 `~/.codex/skills/gsd-*/SKILL.md`。代理以每个代理独立的 TOML 条目写入 `config.toml`。安装后重启 Codex（或运行 `codex --reload`）。
|
||||
|
||||
**最低支持版本：** Codex CLI 0.130.0。更早版本额外扫描技能根目录，可能导致重复列出条目。
|
||||
|
||||
---
|
||||
|
||||
### GitHub Copilot
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --copilot --global
|
||||
```
|
||||
|
||||
技能文件存放于 `~/.copilot/`。GSD 以代理 `.md` 文件和仓库指令文件的形式安装。
|
||||
|
||||
**覆盖安装目录：**
|
||||
|
||||
```bash
|
||||
COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Cursor
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --cursor --global
|
||||
```
|
||||
|
||||
技能文件存放于 `~/.cursor/`。GSD 安装技能、代理和规则引用。
|
||||
|
||||
**覆盖安装目录：**
|
||||
|
||||
```bash
|
||||
CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Windsurf
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --windsurf --global
|
||||
```
|
||||
|
||||
技能文件存放于 `~/.codeium/windsurf/`。GSD 安装技能、代理和工作区规则。
|
||||
|
||||
**覆盖安装目录：**
|
||||
|
||||
```bash
|
||||
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @opengsd/gsd-core@latest --windsurf --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Cline
|
||||
|
||||
Cline 使用基于规则的集成方式——GSD 以 `.clinerules` 形式安装，而非斜杠命令。
|
||||
|
||||
```bash
|
||||
# 全局安装（所有项目）
|
||||
npx @opengsd/gsd-core@latest --cline --global
|
||||
|
||||
# 本地安装（仅此项目）
|
||||
npx @opengsd/gsd-core@latest --cline --local
|
||||
```
|
||||
|
||||
全局安装写入 `~/.cline/`。本地安装写入 `./.cline/`。规则由 Cline 自动加载——不注册自定义斜杠命令。
|
||||
|
||||
---
|
||||
|
||||
### CodeBuddy
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --codebuddy --global
|
||||
```
|
||||
|
||||
技能文件存放于 `~/.codebuddy/skills/gsd-*/SKILL.md`。
|
||||
|
||||
---
|
||||
|
||||
### Qwen Code
|
||||
|
||||
Qwen Code 使用与 Claude Code 2.1.88+ 相同的开放技能标准。
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --qwen --global
|
||||
```
|
||||
|
||||
技能文件存放于 `~/.qwen/skills/gsd-*/SKILL.md`。
|
||||
|
||||
**覆盖安装目录：**
|
||||
|
||||
```bash
|
||||
QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Augment Code
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --augment --global
|
||||
```
|
||||
|
||||
技能文件存放于 `~/.augment/`。GSD 安装技能和代理，不拥有 hook 或状态栏所有权。
|
||||
|
||||
---
|
||||
|
||||
### Antigravity
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --antigravity --global
|
||||
```
|
||||
|
||||
安装程序自动检测 Antigravity 配置目录（`~/.gemini/antigravity`、`~/.gemini/antigravity-ide` 或 `~/.gemini/antigravity-cli`）。使用与 Gemini 兼容的设置策略。
|
||||
|
||||
**覆盖安装目录：**
|
||||
|
||||
```bash
|
||||
ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --antigravity --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Trae
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --trae --global
|
||||
```
|
||||
|
||||
技能文件存放于 `~/.trae/`。GSD 安装技能、代理和规则引用。
|
||||
|
||||
---
|
||||
|
||||
## 本地安装与全局安装
|
||||
|
||||
上述所有示例均使用 `--global`，即为您的用户账户全局安装 GSD。若要将安装范围限定到单个项目，请将 `--global` 替换为 `--local`：
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --claude --local
|
||||
```
|
||||
|
||||
本地安装写入项目根目录下的 `.claude/` 目录。当全局安装和本地安装同时存在时，本地安装的设置优先于全局设置。
|
||||
|
||||
---
|
||||
|
||||
## 安装预发布版（Next / Nightly / Insiders / Preview）
|
||||
|
||||
运行时的预发布版（Windsurf Next、Cursor Nightly、VS Code Insiders、Codex 预览通道等）从同级配置目录读取配置。在运行安装程序前设置对应的 `*_CONFIG_DIR` 环境变量：
|
||||
|
||||
```bash
|
||||
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
|
||||
```
|
||||
|
||||
在安装程序提示中选择对应的稳定版运行时。GSD 不将预发布版作为独立命名运行时枚举——它们通过此环境变量机制提供尽力支持，不在发布 CI 中单独测试。
|
||||
|
||||
---
|
||||
|
||||
## 不使用 Node.js 安装
|
||||
|
||||
如果您无法运行 `npx`（例如在没有 Node.js 的 Windows 机器上），有两种方案可选。
|
||||
|
||||
**方案 A——使用有 Node.js 的机器。** 任何有 Node.js 的机器均可：WSL、Linux 虚拟机、CI runner 或 Docker 容器。在那台机器上运行安装程序，然后将输出目录复制到目标机器。以 OpenCode 为例：
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-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` 函数。
|
||||
|
||||
---
|
||||
|
||||
## 安装后
|
||||
|
||||
重启您的运行时以加载新命令和代理。然后启动您的第一个项目：
|
||||
|
||||
```bash
|
||||
/gsd-new-project
|
||||
```
|
||||
|
||||
如果重启后找不到该命令，请确认安装目录与运行时预期的配置路径匹配。上方的预发布版章节介绍了最常见的路径不匹配情况。
|
||||
|
||||
---
|
||||
|
||||
## 相关链接
|
||||
|
||||
- [您的第一个项目](../tutorials/your-first-project.md)
|
||||
- [更新 GSD Core](update-gsd.md)
|
||||
- [配置](../CONFIGURATION.md)
|
||||
- [文档索引](../README.md)
|
||||
144
docs/zh-CN/how-to/isolate-work-with-workspaces.md
Normal file
144
docs/zh-CN/how-to/isolate-work-with-workspaces.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# 如何使用工作区隔离工作
|
||||
|
||||
**目标：** 创建一个完全隔离的 GSD 环境——独立的 git worktree、独立的 `.planning/` 根目录，以及可选的多仓库支持——适用于功能分支或多仓库工作场景。
|
||||
|
||||
**前提条件：** 已安装 `git` 且仓库支持 worktree。对于多仓库工作区，目标仓库需存在于本地或可通过路径访问。
|
||||
|
||||
---
|
||||
|
||||
## 什么是工作区
|
||||
|
||||
工作区是一个自包含的环境，将一个或多个 git worktree（或克隆）与独立的 `.planning/` 根目录配对。每个工作区包含：
|
||||
|
||||
- 独立的 `.planning/` 目录，**完全独立**于源仓库的 `.planning/`——并非其子目录
|
||||
- 独立的 `WORKSPACE.md` 清单文件，用于跟踪成员仓库
|
||||
- git worktree（默认）或指定仓库的完整克隆，在专用分支上检出（默认：`workspace/<name>`）
|
||||
|
||||
工作区默认存放在 `~/gsd-workspaces/<name>/` 下。
|
||||
|
||||
```
|
||||
~/gsd-workspaces/
|
||||
└── feature-b/
|
||||
├── WORKSPACE.md ← 清单文件
|
||||
├── .planning/ ← 完全独立的 GSD 状态
|
||||
│ ├── PROJECT.md
|
||||
│ ├── ROADMAP.md
|
||||
│ └── ...
|
||||
├── hr-ui/ ← hr-ui 仓库的 worktree 或克隆
|
||||
└── ZeymoAPI/ ← ZeymoAPI 仓库的 worktree 或克隆
|
||||
```
|
||||
|
||||
由于工作区的 `.planning/` 与源仓库相互独立，不会与源仓库中已有的规划状态发生重叠或冲突。
|
||||
|
||||
---
|
||||
|
||||
## 为多个仓库创建工作区
|
||||
|
||||
```bash
|
||||
/gsd-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` 使用。
|
||||
|
||||
自定义位置：
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI --path /projects/feature-b
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 为当前仓库创建工作区
|
||||
|
||||
当你需要在单个仓库上进行功能分支隔离——独立分支、独立 `.planning/`、不受 main 分支状态影响时：
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name payments-rework --repos .
|
||||
```
|
||||
|
||||
`.` 表示为当前仓库创建 worktree，该 worktree 会在 `workspace/payments-rework` 分支上检出。
|
||||
|
||||
若要强制使用完整克隆而非 worktree：
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name payments-rework --repos . --strategy clone
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 显式指定分支
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name payments-rework --repos . --branch feature/payments-v2
|
||||
```
|
||||
|
||||
`--branch` 标志为工作区中所有仓库设置分支名称，默认为 `workspace/<name>`。
|
||||
|
||||
---
|
||||
|
||||
## 跳过交互式询问
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name payments-rework --repos . --auto
|
||||
```
|
||||
|
||||
GSD 将接受所有默认值，无需提示确认。
|
||||
|
||||
---
|
||||
|
||||
## 在工作区内初始化 GSD
|
||||
|
||||
创建工作区后，进入工作区目录并初始化 GSD 项目：
|
||||
|
||||
```bash
|
||||
cd ~/gsd-workspaces/feature-b
|
||||
/gsd-new-project
|
||||
```
|
||||
|
||||
工作区内的 `.planning/` 目录是从该目录运行所有后续 GSD 命令的根目录。它与源仓库中存在的任何 `.planning/` 完全独立。
|
||||
|
||||
---
|
||||
|
||||
## 列出工作区
|
||||
|
||||
```bash
|
||||
/gsd-workspace --list
|
||||
```
|
||||
|
||||
打印所有活跃的 GSD 工作区及其状态。
|
||||
|
||||
---
|
||||
|
||||
## 删除工作区
|
||||
|
||||
```bash
|
||||
/gsd-workspace --remove feature-b
|
||||
```
|
||||
|
||||
GSD 会移除 git worktree 并清理工作区目录。此操作不会从远程仓库删除分支——仅删除本地 worktree 和工作区目录。
|
||||
|
||||
---
|
||||
|
||||
## 何时使用工作区而非工作流
|
||||
|
||||
选择工作区的场景：
|
||||
|
||||
- 你需要跨**多个仓库**协同工作，且这些仓库需要在同一个 GSD 项目下进行协调（例如，一个 API 仓库和一个 UI 仓库需要一起发布）
|
||||
- 你需要每个功能拥有**独立的 git worktree**，带有各自的分支、锁文件和构建产物——以确保一个环境中的构建和依赖安装不会影响另一个环境
|
||||
- 你希望拥有**完全独立的 `.planning/` 根目录**，而非主仓库 `.planning/` 的子目录
|
||||
- 你正在采用 Issue 驱动的工作流，将每个跟踪器 Issue 映射到一个工作区（参见[从跟踪器 Issue 驱动 GSD](drive-gsd-from-a-tracker-issue.md)）
|
||||
|
||||
选择[工作流](work-in-parallel-with-workstreams.md)的场景：
|
||||
|
||||
- 所有工作都在**单一仓库**中进行，共享相同的 git 历史
|
||||
- 你希望在不同关注领域（API、UI、基础设施）上并发运行 `/gsd-plan-phase` 或 `/gsd-discuss-phase`，且各自的 `STATE.md` 文件之间互不干扰
|
||||
- 你不需要每个关注领域拥有独立的 worktree；切换规划上下文即可满足需求
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [使用工作流并行工作](work-in-parallel-with-workstreams.md)
|
||||
- [从跟踪器 Issue 驱动 GSD](drive-gsd-from-a-tracker-issue.md)
|
||||
- [命令](../COMMANDS.md)
|
||||
- [文档索引](../README.md)
|
||||
145
docs/zh-CN/how-to/migrate-from-gsd-2.md
Normal file
145
docs/zh-CN/how-to/migrate-from-gsd-2.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# 如何从 GSD-2 迁移
|
||||
|
||||
**目标：** 将较旧的 GSD-2 项目（`.gsd/` 目录布局）升级迁移到 GSD Core（`.planning/` 布局），并可选择将项目仓库中已有的 ADR、PRD 或规范文档纳入新的规划结构。
|
||||
|
||||
**前提条件：** GSD Core 已安装。GSD-2 项目目录在磁盘上可访问。
|
||||
|
||||
---
|
||||
|
||||
## 了解迁移内容
|
||||
|
||||
GSD-2 使用 `.gsd/` 目录作为规划根目录，GSD Core 使用 `.planning/`。迁移过程读取 `.gsd/` 中的工件，并将其写入所有 GSD Core 命令所期望的标准 `.planning/` 结构中。
|
||||
|
||||
| GSD-2 中的现有内容 | `/gsd-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` 文件（强制重命名） |
|
||||
|
||||
冲突检测会在写入任何文件之前运行。如果目标目录中已存在 `PROJECT.md` 且导入内容与之矛盾，迁移将在 BLOCKER 门控处停止，并列出需要您解决的冲突。
|
||||
|
||||
---
|
||||
|
||||
## 执行迁移
|
||||
|
||||
### 迁移当前目录
|
||||
|
||||
```bash
|
||||
/gsd-import --from-gsd2
|
||||
```
|
||||
|
||||
GSD 读取当前工作目录下的 `.gsd/`，并将迁移后的工件写入 `.planning/`。
|
||||
|
||||
### 从其他路径迁移
|
||||
|
||||
```bash
|
||||
/gsd-import --from-gsd2 --path ~/projects/old-project
|
||||
```
|
||||
|
||||
当 GSD-2 项目不在当前工作目录时，使用 `--path` 指定路径。
|
||||
|
||||
---
|
||||
|
||||
## 解决冲突
|
||||
|
||||
如果冲突检测发现阻断项——例如，GSD-2 的技术栈声明与现有的 `.planning/PROJECT.md` 相矛盾——它会打印冲突报告并停止，不写入任何文件。
|
||||
|
||||
阅读报告，解决矛盾（编辑源文档或现有规划工件），然后重新运行 `/gsd-import --from-gsd2`。迁移可以安全地重复运行，直至顺利通过。
|
||||
|
||||
---
|
||||
|
||||
## 导入外部计划文件
|
||||
|
||||
如果您拥有的是独立的计划文档（团队规划文档、Markdown 规范、导出的任务列表），而非完整的 GSD-2 项目，请使用 `--from` 代替：
|
||||
|
||||
```bash
|
||||
/gsd-import --from /tmp/team-plan.md
|
||||
```
|
||||
|
||||
GSD 执行相同的冲突检测流程，将内容转换为 GSD Core `PLAN.md` 格式，并使用计划检查器验证结果。验证完成后，您将看到目标文件名和后续步骤。
|
||||
|
||||
---
|
||||
|
||||
## 吸收现有文档
|
||||
|
||||
如果您的仓库中已包含 ADR（架构决策记录）、PRD 或规范文档，可在迁移完成后使用 `/gsd-ingest-docs` 将其合并到 `.planning/` 结构中：
|
||||
|
||||
### 扫描整个仓库（自动检测模式）
|
||||
|
||||
```bash
|
||||
/gsd-ingest-docs
|
||||
```
|
||||
|
||||
如果 `.planning/` 已经存在（例如，刚完成迁移后），GSD 默认使用合并模式——将导入的文档与已有内容并行合并，而非覆盖。
|
||||
|
||||
### 限定到特定目录
|
||||
|
||||
```bash
|
||||
/gsd-ingest-docs docs/
|
||||
/gsd-ingest-docs docs/adr/
|
||||
```
|
||||
|
||||
### 使用显式优先级清单
|
||||
|
||||
当文档类型混合，或您希望控制冲突时哪份文档优先：
|
||||
|
||||
```bash
|
||||
/gsd-ingest-docs --manifest ingest.yaml
|
||||
```
|
||||
|
||||
清单是一个 YAML 文件，每个文档列出 `{path, type, precedence?}`。请参阅 [Commands](../COMMANDS.md) 中 `--manifest` 标志说明，了解其期望的结构。
|
||||
|
||||
### 强制指定模式
|
||||
|
||||
```bash
|
||||
/gsd-ingest-docs --mode merge # 合并到现有 .planning/
|
||||
/gsd-ingest-docs --mode new # 从零开始引导（覆盖）
|
||||
```
|
||||
|
||||
**输出：** `/gsd-ingest-docs` 始终生成一个 `INGEST-CONFLICTS.md`，其中包含三个类别——自动解决、竞争变体和未解决的阻断项。每次导入运行后请审查此文件。仅在 LOCKED 与 LOCKED 的 ADR 矛盾时才会硬停止；其他所有情况均会呈现供您审查，而不会被静默丢弃。
|
||||
|
||||
---
|
||||
|
||||
## 验证迁移后的项目
|
||||
|
||||
迁移及文档导入完成后，确认项目状态的一致性：
|
||||
|
||||
```bash
|
||||
/gsd-health
|
||||
/gsd-health --repair
|
||||
```
|
||||
|
||||
`/gsd-health` 检查 `.planning/` 目录的完整性并报告任何偏差。`--repair` 会自动修复可恢复的问题。
|
||||
|
||||
然后检查 GSD Core 是否能够读取您的项目状态：
|
||||
|
||||
```bash
|
||||
/gsd-progress
|
||||
```
|
||||
|
||||
如果项目迁移顺利，您将看到当前阶段状态和推荐的下一步操作。从此处起，适用标准 GSD Core 工作流程。
|
||||
|
||||
---
|
||||
|
||||
## 条件说明：什么能迁移，什么不能
|
||||
|
||||
| 情形 | 处理方式 |
|
||||
|-----------|-----------|
|
||||
| 当前目录中存在 `.gsd/` | 运行 `/gsd-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-health` 和 `/gsd-progress` 进行确认 |
|
||||
| INGEST-CONFLICTS.md 列出未解决的阻断项 | 这些需要手动解决，相关文档才能被纳入规划 |
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [您的第一个项目](../tutorials/your-first-project.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [文档索引](../README.md)
|
||||
216
docs/zh-CN/how-to/plan-a-phase.md
Normal file
216
docs/zh-CN/how-to/plan-a-phase.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# 如何规划阶段
|
||||
|
||||
**目标：** 将阶段决策和研究成果转化为可原子化执行、可验证的任务计划。
|
||||
|
||||
**前提条件：** `.planning/ROADMAP.md` 已存在。强烈建议（但非必须）先通过 `/gsd-discuss-phase` 生成 `{phase}-CONTEXT.md`。
|
||||
|
||||
---
|
||||
|
||||
## 运行标准规划流程
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 2
|
||||
```
|
||||
|
||||
该命令按顺序执行三个阶段：
|
||||
|
||||
1. **研究** — `gsd-phase-researcher` 子代理调查相关领域并写入 `{phase}-RESEARCH.md`。
|
||||
2. **规划** — `gsd-planner` 子代理读取上下文、研究成果和需求，然后写入一个或多个 `{phase}-{N}-PLAN.md` 文件。
|
||||
3. **验证** — `gsd-plan-checker` 子代理从八个维度验证计划质量，并触发修订循环（最多三次迭代），直至质量门控通过。
|
||||
|
||||
若未指定阶段编号，GSD Core 将自动定位 ROADMAP.md 中下一个未规划的阶段。
|
||||
|
||||
---
|
||||
|
||||
## 跳过或强制执行研究
|
||||
|
||||
**如果领域已熟悉且无需新的研究：**
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 3 --skip-research
|
||||
```
|
||||
|
||||
**如果 RESEARCH.md 已存在但需要强制刷新：**
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 3 --research
|
||||
```
|
||||
|
||||
**如果只想运行研究** — 写入 RESEARCH.md 后在规划前退出：
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase --research-phase 4
|
||||
```
|
||||
|
||||
若 RESEARCH.md 已存在，系统会提示选择更新、查看或跳过。如需强制刷新而不显示提示：
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase --research-phase 4 --research
|
||||
```
|
||||
|
||||
将现有 RESEARCH.md 打印到标准输出而不启动研究代理：
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase --research-phase 4 --view
|
||||
```
|
||||
|
||||
注意：`--research-phase <N>` 是 `/gsd-plan-phase` 上的标志。不存在独立的研究阶段命令——原来的独立研究命令已被弃用，以此标志取而代之。
|
||||
|
||||
---
|
||||
|
||||
## 按垂直功能切片而非水平层次进行规划
|
||||
|
||||
**如果希望任务按端到端的薄切片组织**（每个功能从 UI → API → DB），而非按技术层次：
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1 --mvp
|
||||
```
|
||||
|
||||
在新项目的第一阶段且无先前阶段摘要的情况下，`--mvp` 还会生成 `SKELETON.md`——一份 Walking Skeleton，涵盖项目脚手架、路由、一次真实的数据库读写、一次真实的 UI 交互以及开发部署。
|
||||
|
||||
也可在 ROADMAP.md 中该阶段的条目里添加 `**Mode:** mvp`，无需每次使用标志即可持久启用 MVP 模式。
|
||||
|
||||
---
|
||||
|
||||
## 要求每个新增行为任务包含一个失败测试
|
||||
|
||||
**如果需要强制 TDD** — 每个新增行为的任务在实现前先编写一个失败测试：
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1 --tdd
|
||||
```
|
||||
|
||||
可与 `--mvp` 组合使用：
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1 --mvp --tdd
|
||||
```
|
||||
|
||||
这将生成垂直切片，其中每个新增行为的任务均遵循 RED → GREEN → REFACTOR 流程。规划器会对符合条件的任务（业务逻辑、API 端点、数据转换）应用 `type: tdd`，并对 UI、配置和胶水代码使用标准的 `type: execute`。
|
||||
|
||||
TDD 模式也可在配置中持久化：
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs config-set workflow.tdd_mode true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 基于跨 AI 评审反馈重新规划
|
||||
|
||||
**如果已运行 `/gsd-review --phase N` 且存在 `REVIEWS.md`：**
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 3 --reviews
|
||||
```
|
||||
|
||||
规划器会读取 `REVIEWS.md` 并修订计划以解决反馈问题。不可与 `--gaps` 组合使用。
|
||||
|
||||
**如果需要自动化循环** — 持续重新规划和重新评审，直至不再存在 HIGH 级别关注点：
|
||||
|
||||
```bash
|
||||
/gsd-plan-review-convergence 3
|
||||
```
|
||||
|
||||
收敛循环执行规划 → 评审 → 重新规划 → 再评审的周期（默认最多三次）。使用 `--max-cycles N` 可覆盖上限。
|
||||
|
||||
---
|
||||
|
||||
## 在验证失败后弥补差距
|
||||
|
||||
**如果 `VERIFICATION.md` 存在未解决的差距，且只想针对这些差距重新规划：**
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 3 --gaps
|
||||
```
|
||||
|
||||
研究阶段将被跳过；规划器直接读取验证中的差距信息。
|
||||
|
||||
---
|
||||
|
||||
## 在规划开始前验证项目状态
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 2 --validate
|
||||
```
|
||||
|
||||
在启动研究代理前运行状态验证。如果怀疑 ROADMAP.md 或 STATE.md 已发生偏移，请使用此选项。
|
||||
|
||||
---
|
||||
|
||||
## 规划完成后运行外部弹跳验证
|
||||
|
||||
**如果已配置 `workflow.plan_bounce_script` 且需要对完成的计划进行外部验证：**
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1 --bounce
|
||||
```
|
||||
|
||||
即使在配置中已启用弹跳，也可跳过：
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1 --skip-bounce
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 禁止交互式确认
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase --auto
|
||||
```
|
||||
|
||||
跳过所有提示。适用于自动化流水线。若配置中 `research_enabled` 为 false，则跳过研究阶段。
|
||||
|
||||
---
|
||||
|
||||
## 计划输出内容
|
||||
|
||||
成功运行后会写入以下文件：
|
||||
|
||||
| 文件 | 用途 |
|
||||
|---|---|
|
||||
| `{phase}-RESEARCH.md` | 领域研究、软件包合法性审计、验证架构 |
|
||||
| `{phase}-VALIDATION.md` | 奈奎斯特测试映射——计划必须满足的测试用例（第 8 维度） |
|
||||
| `{phase}-{N}-PLAN.md` | 包含前置信息、波次分配和验收标准的可执行任务计划 |
|
||||
| `{phase}/SKELETON.md` | Walking Skeleton（MVP 模式，仅限新项目的第一阶段） |
|
||||
|
||||
每个 PLAN.md 包含带有强制 `<read_first>` 和 `<acceptance_criteria>` 字段的任务。每个 `<acceptance_criteria>` 条目均可作为源断言、行为断言、测试命令或 CLI 输出进行验证——绝不使用主观性语言。
|
||||
|
||||
完整的字段参考请参阅 [PLAN.md 模式](../reference/plan-md.md)。
|
||||
|
||||
### 计划质量维度
|
||||
|
||||
`gsd-plan-checker` 在允许执行前从八个维度验证计划：
|
||||
|
||||
1. 任务原子性——每个任务只关注单一问题
|
||||
2. 依赖正确性——波次顺序一致
|
||||
3. 验收标准可验证性——无主观标准
|
||||
4. `<read_first>` 完整性——被修改的文件始终列入其中
|
||||
5. 具体的 `<action>` 值——无模糊的"对齐"类指令
|
||||
6. `must_haves` 源自阶段目标
|
||||
7. 需求 ID 覆盖率——每个阶段需求 ID 至少出现在一个计划中
|
||||
8. 奈奎斯特测试映射——计划涵盖 VALIDATION.md 中的验证策略
|
||||
|
||||
修订循环最多运行三次。若三次迭代后质量门控仍未通过，检查器将显示剩余问题供人工审查。
|
||||
|
||||
---
|
||||
|
||||
## 重新规划已关闭的阶段
|
||||
|
||||
如果某阶段的 `VERIFICATION.md` 中 `status: passed`，则该阶段被视为已关闭。尝试重新规划会以错误终止。如果关闭操作有误，可使用 `--force` 覆盖：
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 2 --force
|
||||
```
|
||||
|
||||
警告信息将写入转录记录和所有已提交的计划文档中。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [讨论阶段](discuss-a-phase.md)
|
||||
- [执行阶段](execute-a-phase.md)
|
||||
- [PLAN.md 模式](../reference/plan-md.md)
|
||||
- [命令](../COMMANDS.md)
|
||||
323
docs/zh-CN/how-to/recover-and-troubleshoot.md
Normal file
323
docs/zh-CN/how-to/recover-and-troubleshoot.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# 如何恢复与排查问题
|
||||
|
||||
**目标：** 识别并修复常见问题——从上下文丢失、状态损坏，到安装失败和权限错误——采用条件化的处理步骤结构。
|
||||
|
||||
**前提条件：** GSD Core 已安装。若遇到安装问题，请参阅 [在您的运行时中安装](install-on-your-runtime.md)。
|
||||
|
||||
---
|
||||
|
||||
## 上下文与会话问题
|
||||
|
||||
### 如果您不清楚当前所处的位置
|
||||
|
||||
```bash
|
||||
/gsd-progress
|
||||
```
|
||||
|
||||
读取所有状态文件，并精确告知您当前位置以及下一步操作。
|
||||
|
||||
若要自动跳转到正确的下一步：
|
||||
|
||||
```bash
|
||||
/gsd-progress --next
|
||||
```
|
||||
|
||||
### 如果您正在开始新会话并需要恢复上下文
|
||||
|
||||
```bash
|
||||
/gsd-resume-work
|
||||
```
|
||||
|
||||
从上次交接中恢复完整的会话上下文，包括当前阶段、规划决策以及工作停止的位置。
|
||||
|
||||
### 如果长时间会话中质量开始下降
|
||||
|
||||
在执行主要命令之间清空上下文窗口：
|
||||
|
||||
```bash
|
||||
/clear
|
||||
```
|
||||
|
||||
然后恢复状态：
|
||||
|
||||
```bash
|
||||
/gsd-resume-work
|
||||
```
|
||||
|
||||
GSD 的设计围绕全新上下文展开。每个子代理已获得干净的 200k 窗口。主会话会随时间退化——清空并恢复才是正确的处理方式，而非继续硬撑。
|
||||
|
||||
### 如果您希望在停止前保存上下文
|
||||
|
||||
```bash
|
||||
/gsd-pause-work
|
||||
```
|
||||
|
||||
将当前位置创建为 `.planning/HANDOFF.json`。添加 `--report` 可同时将会话后摘要写入 `.planning/reports/`：
|
||||
|
||||
```bash
|
||||
/gsd-pause-work --report
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 规划完整性问题
|
||||
|
||||
### 如果 `.planning/` 完整性不确定
|
||||
|
||||
```bash
|
||||
/gsd-health
|
||||
```
|
||||
|
||||
以错误、警告和信息说明的形式报告状态：
|
||||
|
||||
| 状态 | 含义 |
|
||||
|--------|---------|
|
||||
| `HEALTHY` | 所有预期产物存在且格式正确 |
|
||||
| `DEGRADED` | 存在应当处理的警告，但工作可以继续 |
|
||||
| `BROKEN` | 存在将阻断执行的严重错误 |
|
||||
|
||||
可自动修复的常见问题（错误 E004、E005；警告 W003、W008）：
|
||||
|
||||
```bash
|
||||
/gsd-health --repair
|
||||
```
|
||||
|
||||
该命令会重新创建缺失的 `STATE.md`，将损坏的 `config.json` 重置为默认值，并补充所有缺失的配置键。它不会覆盖 `PROJECT.md` 或 `ROADMAP.md`。
|
||||
|
||||
### 如果 STATE.md 引用了不存在的阶段
|
||||
|
||||
这会产生警告 `W002`。使用状态 CLI 进行诊断和修复：
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate
|
||||
```
|
||||
|
||||
在不写入的情况下预览同步将更改的内容：
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify
|
||||
```
|
||||
|
||||
应用同步：
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync
|
||||
```
|
||||
|
||||
这些命令从磁盘上的实际项目状态重建 `STATE.md`，取代手动编辑 `STATE.md` 的操作。
|
||||
|
||||
### 如果看到"项目已初始化"
|
||||
|
||||
`.planning/PROJECT.md` 已存在。`/gsd-new-project` 是一项安全检查。如果您确实想重新开始，请先删除 `.planning/` 目录：
|
||||
|
||||
```bash
|
||||
rm -rf .planning/
|
||||
```
|
||||
|
||||
然后重新运行 `/gsd-new-project`。
|
||||
|
||||
### 如果上下文窗口利用率过高
|
||||
|
||||
```bash
|
||||
/gsd-health --context
|
||||
```
|
||||
|
||||
探测上下文窗口利用率保护机制。警告阈值为 60%，严重阈值为 70%。如果超过警告阈值，请在开始下一个主要命令前运行 `/clear` 后跟 `/gsd-resume-work`。
|
||||
|
||||
---
|
||||
|
||||
## 执行问题
|
||||
|
||||
### 如果执行器在执行 Bash 命令时遇到"Permission denied"
|
||||
|
||||
GSD 的 `gsd-executor` 子代理需要具有写入权限的 Bash 访问。在 `~/.claude/settings.json` 的 `permissions.allow` 下添加所需模式。至少需要：
|
||||
|
||||
```json
|
||||
"Bash(git add:*)",
|
||||
"Bash(git commit:*)",
|
||||
"Bash(git merge:*)",
|
||||
"Bash(git checkout:*)"
|
||||
```
|
||||
|
||||
针对特定技术栈的模式（Rails、Python、Node、Rust），请参阅 `docs/USER-GUIDE.md` 中"执行器子代理遇到 Permission denied"一节的完整表格。
|
||||
|
||||
按项目配置的替代方案：在项目根目录的 `.claude/settings.local.json` 中添加相同的配置块。
|
||||
|
||||
### 如果执行失败或产生存根代码
|
||||
|
||||
检查计划是否过于宏大。计划最多应包含两到三个任务。如果任务太大，则超出单个上下文窗口能可靠产出的范围。请以更小的范围重新规划该阶段：
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1
|
||||
```
|
||||
|
||||
若要系统性地诊断出错原因，请参阅 [调试失败的执行](debug-a-failed-execution.md)。
|
||||
|
||||
### 如果并行执行导致构建锁定错误或预提交钩子失败
|
||||
|
||||
这是由多个代理同时触发构建工具引起的。自 v1.26 起，GSD 自动处理此问题。如果您使用的是旧版本，或仍然出现竞争问题，请禁用并行执行：
|
||||
|
||||
```bash
|
||||
/gsd-settings
|
||||
```
|
||||
|
||||
将 `parallelization.enabled` 设置为 `false`。
|
||||
|
||||
### 如果子代理显示失败但提交已完成
|
||||
|
||||
在得出某些内容出错的结论之前，请检查 git 日志：
|
||||
|
||||
```bash
|
||||
git log --oneline -10
|
||||
```
|
||||
|
||||
Claude Code 中存在一个已知的分类错误，可能在工作实际成功时报告失败。GSD 的编排器会抽查实际输出，但如果您发现不一致，提交记录才是最终依据。
|
||||
|
||||
---
|
||||
|
||||
## 计划与阶段问题
|
||||
|
||||
### 如果计划看起来有误或与您的意图不符
|
||||
|
||||
在规划之前运行 `/gsd-discuss-phase N`。大多数计划质量问题来自本可由 `CONTEXT.md` 预防的假设：
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 1
|
||||
```
|
||||
|
||||
若要查看 GSD 当前做出的假设而无需开始完整会话：
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 3 --assumptions
|
||||
```
|
||||
|
||||
### 如果您需要在执行后更改某些内容
|
||||
|
||||
不要重新运行 `/gsd-execute-phase`。请使用 `/gsd-quick` 进行有针对性的修复：
|
||||
|
||||
```bash
|
||||
/gsd-quick "Fix the login button not responding on mobile Safari"
|
||||
```
|
||||
|
||||
或使用 `/gsd-verify-work N` 通过 UAT 系统性地识别和修复问题。
|
||||
|
||||
### 如果命令在"Spawning…"处似乎卡住了
|
||||
|
||||
请等待。GSD 子代理在独立的上下文窗口中运行。其工作在进行中对父会话不可见。生成行上的活跃度提示确认这是预期行为。研究和规划代理通常需要 1–5 分钟；验证代理在大型阶段中可能需要更长时间。
|
||||
|
||||
不要中断会话。终止它会丢弃进行中的子代理工作。
|
||||
|
||||
如果已超过 10 分钟，请检查代理任务在 Claude Code 侧边栏中是否仍显示为活跃状态。
|
||||
|
||||
---
|
||||
|
||||
## 工作流状态问题
|
||||
|
||||
### 如果工作流似乎已损坏或状态不一致
|
||||
|
||||
```bash
|
||||
/gsd-forensics
|
||||
```
|
||||
|
||||
或附带描述：
|
||||
|
||||
```bash
|
||||
/gsd-forensics "Phase 3 execution stalled after wave 1"
|
||||
```
|
||||
|
||||
`/gsd-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 提交中交互式选择
|
||||
```
|
||||
|
||||
`/gsd-undo` 在回滚前检查依赖阶段，并始终显示确认步骤。
|
||||
|
||||
---
|
||||
|
||||
## 安装与更新问题
|
||||
|
||||
### 如果安装后 GSD 未被识别
|
||||
|
||||
重启您的运行时。GSD 将斜杠命令安装到您运行时的命令目录中（例如 `~/.claude/commands/gsd/`）。大多数运行时仅在启动时发现新命令。
|
||||
|
||||
如果问题仍然存在，请验证安装：
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --claude --local
|
||||
```
|
||||
|
||||
有关特定运行时的安装路径和排查说明，请参阅 [在您的运行时中安装](install-on-your-runtime.md)。
|
||||
|
||||
### 如果更新覆盖了您的本地更改
|
||||
|
||||
自 v1.17 起，安装程序将本地修改的文件备份到 `gsd-local-patches/`。重新应用您的更改：
|
||||
|
||||
```bash
|
||||
/gsd-update --reapply
|
||||
```
|
||||
|
||||
### 如果无法通过 npm 更新
|
||||
|
||||
如果 `npx @opengsd/gsd-core` 因 npm 故障或网络限制而失败，请参阅 `docs/manual-update.md` 了解无需 npm 访问即可完成更新的逐步手动更新流程。
|
||||
|
||||
有关常规更新，请参阅 [更新 GSD](update-gsd.md)。
|
||||
|
||||
---
|
||||
|
||||
## 成本问题
|
||||
|
||||
### 如果模型费用过高
|
||||
|
||||
切换到预算配置文件：
|
||||
|
||||
```bash
|
||||
/gsd-config --profile budget
|
||||
```
|
||||
|
||||
如果对该领域已很熟悉，请通过设置禁用研究和计划检查代理：
|
||||
|
||||
```bash
|
||||
/gsd-settings
|
||||
```
|
||||
|
||||
另外，请审核已启用的 MCP 服务器。每个已启用的 MCP 服务器都会在每个回合中将其工具架构注入。浏览器和平台特定工具每个可能消耗 20k+ 个令牌。在 `.claude/settings.json` 中禁用当前阶段不需要的服务器：
|
||||
|
||||
```json
|
||||
{
|
||||
"disabledMcpjsonServers": ["playwright", "mac-tools"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 恢复快速参考
|
||||
|
||||
| 问题 | 解决方案 |
|
||||
|---------|---------|
|
||||
| 上下文丢失或新会话 | `/gsd-resume-work` 或 `/gsd-progress` |
|
||||
| 不知道下一步是什么 | `/gsd-progress --next` |
|
||||
| 阶段出错 | `/gsd-undo --phase NN`，然后重新规划 |
|
||||
| 某些内容损坏 | `/gsd-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` |
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [调试失败的执行](debug-a-failed-execution.md)
|
||||
- [在您的运行时中安装](install-on-your-runtime.md)
|
||||
- [命令](../COMMANDS.md)
|
||||
- [文档索引](../README.md)
|
||||
124
docs/zh-CN/how-to/run-phases-autonomously.md
Normal file
124
docs/zh-CN/how-to/run-phases-autonomously.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# 如何自主运行阶段
|
||||
|
||||
无需人工干预地运行所有剩余阶段——或指定范围内的阶段——GSD 将自动完成每个阶段的讨论 → 规划 → 执行流程。
|
||||
|
||||
有关自主运行期间阶段循环的工作原理，请参阅[阶段循环](../explanation/the-phase-loop.md)。
|
||||
|
||||
---
|
||||
|
||||
## 前提条件
|
||||
|
||||
- 已有包含 `.planning/ROADMAP.md` 和 `.planning/STATE.md` 的活跃项目
|
||||
- 所有要运行的阶段必须处于自主模式可驱动的状态（待处理或进行中；非已完成状态）
|
||||
- 您关心的所有设计决策应已记录在 `PROJECT.md` 中，或通过之前的 `/gsd-discuss-phase` 捕获——自主模式仅在使用 `--interactive` 时才能交互式地处理灰色地带
|
||||
|
||||
---
|
||||
|
||||
## 运行所有剩余阶段
|
||||
|
||||
```bash
|
||||
/gsd-autonomous
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
到达 `--to` 时，生命周期步骤会被跳过，因为并非所有里程碑阶段都已完成。完成横幅会告诉您如何继续：
|
||||
|
||||
```text
|
||||
Resume with: /gsd-autonomous --from 6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 以交互式讨论模式运行
|
||||
|
||||
默认情况下，自主模式使用智能讨论（批量表格提案）自动回答讨论问题。如果您希望自己回答设计问题，同时将规划和执行保持在主上下文之外：
|
||||
|
||||
```bash
|
||||
/gsd-autonomous --interactive
|
||||
```
|
||||
|
||||
交互模式下：
|
||||
- `/gsd-discuss-phase` 内联运行并等待您的回答
|
||||
- 规划和执行作为后台代理分发，以便您在讨论下一阶段时当前阶段仍在构建
|
||||
- 主上下文保持精简——只有讨论对话会累积
|
||||
|
||||
---
|
||||
|
||||
## 哪些安全门控仍然适用
|
||||
|
||||
自主模式不会绕过 GSD 的质量流水线。每个阶段仍然会：
|
||||
|
||||
- 在执行前运行计划检查器
|
||||
- 执行后读取 `VERIFICATION.md` 并根据结果进行路由
|
||||
- 当验证状态为 `human_needed` 或 `gaps_found` 时暂停并询问您的处理意见
|
||||
- 任何步骤失败时停止并提供选项（修复并重试、跳过阶段或停止）
|
||||
|
||||
与手动执行的唯一区别是：`passed` 状态的验证会自动推进——除非需要做出决策，否则不会在阶段间提示您。
|
||||
|
||||
包合法性门控也保持激活。如果计划中包含针对可疑包的 `checkpoint:human-verify` 任务，执行器将停止并显示检查点。自主模式不会静默安装被标记的包。
|
||||
|
||||
---
|
||||
|
||||
## 何时不使用自主模式
|
||||
|
||||
以下情况请勿使用 `/gsd-autonomous`：
|
||||
|
||||
- **阶段存在未解决的设计决策。** 如果您尚未运行 `/gsd-discuss-phase` 且 `PROJECT.md` 未捕获您的偏好，智能讨论将做出您可能不认同的自主选择。请先交互式地运行讨论，或使用 `--interactive`。
|
||||
|
||||
- **您需要对单个阶段进行精细控制。** 对于单个阶段，`/gsd-execute-phase N` 会提供逐步输出并允许您在继续之前做出反应。自主模式专为批量无人值守运行而设计。
|
||||
|
||||
- **阶段包含新颖或高风险的工作。** 自主模式除非遇到阻碍，否则会跳过暂停。对于预期有意外情况的阶段，请通过手动执行保持在循环中。
|
||||
|
||||
- **您正处于已部分执行的阶段中途。** 自主模式可以接管未完成的阶段，但不会恢复部分执行的波次。使用 `/gsd-execute-phase N` 完成已在进行中的阶段。
|
||||
|
||||
如果运行中途停止，请参阅[调试失败的执行](debug-a-failed-execution.md)了解如何诊断问题所在。
|
||||
|
||||
---
|
||||
|
||||
## 运行期间检查进度
|
||||
|
||||
自主模式在每个阶段前打印进度横幅：
|
||||
|
||||
```text
|
||||
GSD ► AUTONOMOUS ▸ Phase 3/7: Auth Middleware [████░░░░] 28%
|
||||
```
|
||||
|
||||
如果您需要在会话中途查看运行进度，请打开另一个终端并运行：
|
||||
|
||||
```bash
|
||||
/gsd-progress
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 停止后恢复
|
||||
|
||||
如果自主模式停止——无论是您从阻碍提示中选择了"停止自主模式"，还是会话被中断——请从停止处继续：
|
||||
|
||||
```bash
|
||||
/gsd-autonomous --from 4 # 将 4 替换为第一个未完成的阶段编号
|
||||
```
|
||||
|
||||
GSD 会自动跳过已完成的阶段，因此如果您不确定运行在何处停止，从较早的阶段编号重新运行是安全的。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [执行阶段](execute-a-phase.md)
|
||||
- [调试失败的执行](debug-a-failed-execution.md)
|
||||
- [命令](../COMMANDS.md)
|
||||
- [文档索引](../README.md)
|
||||
159
docs/zh-CN/how-to/set-up-cross-ai-review.md
Normal file
159
docs/zh-CN/how-to/set-up-cross-ai-review.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# 如何设置跨 AI 评审
|
||||
|
||||
**目标：** 配置参与计划评审的 AI 评审者，对已规划的阶段运行评审，并利用反馈收敛出无 HIGH 级别问题的计划。
|
||||
|
||||
**前提条件：** 该阶段已完成规划（`.planning/phases/` 目录中存在 `{phase}-PLAN.md` 文件），且至少安装并认证了一个外部 AI CLI。
|
||||
|
||||
---
|
||||
|
||||
## 决定使用哪些评审者
|
||||
|
||||
GSD Core 可将评审请求路由至以下任意组合：Gemini CLI、Claude（独立会话）、Codex CLI、CodeRabbit、OpenCode、Qwen Code、Cursor、Antigravity CLI、Ollama、LM Studio 以及 llama.cpp。
|
||||
|
||||
每位评审者会独立地对您的 `PLAN.md` 文件执行相同的结构化提示。由于不同模型存在不同的盲区，多评审者共识能比任何单一评审者发现更多问题。
|
||||
|
||||
**如果您尚未安装任何外部 CLI**，请至少安装一个：
|
||||
|
||||
```bash
|
||||
# Gemini CLI（使用 Google 凭据免费使用）
|
||||
npm install -g @google/gemini-cli
|
||||
|
||||
# Antigravity CLI（使用 Google 凭据免费使用）
|
||||
curl -fsSL https://antigravity.google/cli/install.sh | bash
|
||||
|
||||
# Codex CLI
|
||||
npm install -g @openai/codex
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 设置默认评审者（可选）
|
||||
|
||||
默认情况下，`/gsd-review` 会运行所有检测到的 CLI。若要将特定子集固定为项目默认值：
|
||||
|
||||
```bash
|
||||
/gsd-config --integrations
|
||||
```
|
||||
|
||||
集成向导涵盖 API 密钥、代码评审 CLI 路由以及 `review.default_reviewers` 列表。将该列表设置为您希望作为无标志默认值的评审者——例如 `["gemini","codex"]`。
|
||||
|
||||
或者，也可通过 `gsd-tools` 直接设置：
|
||||
|
||||
```bash
|
||||
gsd config-set review.default_reviewers '["gemini","codex"]'
|
||||
```
|
||||
|
||||
完整的集成设置架构（API 密钥、每个评审者的模型覆盖、本地服务器主机地址）请参阅[配置](../CONFIGURATION.md)。
|
||||
|
||||
---
|
||||
|
||||
## 运行评审
|
||||
|
||||
### 标准评审（使用已配置的默认值或所有检测到的 CLI）
|
||||
|
||||
```bash
|
||||
/gsd-review --phase 3
|
||||
```
|
||||
|
||||
GSD 会依次调用每位评审者，收集结构化反馈（摘要、优点、HIGH/MEDIUM/LOW 级别问题、建议、风险评估），并将合并后的输出写入 `.planning/phases/03-.../03-REVIEWS.md`。
|
||||
|
||||
### 为一次性运行选择单个评审者
|
||||
|
||||
```bash
|
||||
/gsd-review --phase 3 --gemini
|
||||
/gsd-review --phase 3 --codex
|
||||
/gsd-review --phase 3 --cursor
|
||||
```
|
||||
|
||||
任何显式标志都会覆盖该次运行的 `--all` 默认值和 `review.default_reviewers`。
|
||||
|
||||
### 并行运行所有可用评审者
|
||||
|
||||
```bash
|
||||
/gsd-review --phase 3 --all
|
||||
```
|
||||
|
||||
`--all` 始终覆盖配置，运行完整的检测集合，包括任何已配置的本地模型服务器（Ollama、LM Studio、llama.cpp）。
|
||||
|
||||
### 本地模型服务器评审者
|
||||
|
||||
如果您在本地运行 Ollama 或 LM Studio，当服务器可达时，使用 `--all` 会自动将其包含在内。您也可以显式指定：
|
||||
|
||||
```bash
|
||||
/gsd-review --phase 3 --ollama
|
||||
/gsd-review --phase 3 --lm-studio
|
||||
```
|
||||
|
||||
如果默认值（`localhost:11434` / `localhost:1234`）不适用，请通过 `/gsd-config --integrations` 在 `review.*` 键下配置主机地址和模型选择。
|
||||
|
||||
---
|
||||
|
||||
## 读取评审输出
|
||||
|
||||
`{padded_phase}-REVIEWS.md` 文件包含：
|
||||
|
||||
- 每位评审者的独立评审，附带按严重程度分类的问题
|
||||
- **共识摘要**部分，综合了两位或更多评审者提出的问题——从此处开始获取最高优先级信号
|
||||
- **分歧观点**部分，记录评审者意见不一致的领域
|
||||
|
||||
---
|
||||
|
||||
## 将反馈纳入计划
|
||||
|
||||
查看输出后，结合反馈重新规划：
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 3 --reviews
|
||||
```
|
||||
|
||||
规划器会读取 `REVIEWS.md`，并在保存前调整计划以解决相关问题。
|
||||
|
||||
---
|
||||
|
||||
## 自动化计划-评审-重规划循环
|
||||
|
||||
对于希望迭代直至所有 HIGH 级别问题解决的阶段，请使用收敛循环：
|
||||
|
||||
```bash
|
||||
/gsd-plan-review-convergence 3
|
||||
```
|
||||
|
||||
此命令运行 `plan-phase → review → replan → re-review`，最多循环三次（默认）。当 HIGH 级别问题数量降至零时，循环退出。
|
||||
|
||||
### 使用特定评审者进行收敛
|
||||
|
||||
```bash
|
||||
/gsd-plan-review-convergence 3 --codex
|
||||
/gsd-plan-review-convergence 3 --gemini
|
||||
```
|
||||
|
||||
### 使用所有评审者并提高循环上限进行收敛
|
||||
|
||||
```bash
|
||||
/gsd-plan-review-convergence 3 --all --max-cycles 5
|
||||
```
|
||||
|
||||
**停滞检测：** 如果 HIGH 级别问题数量在各轮次间未减少，GSD 会向您发出警告。当循环上限已达但仍存在未解决的 HIGH 级别问题时，升级门控会询问是否继续或手动审查。
|
||||
|
||||
---
|
||||
|
||||
## 条件判断：选择哪些评审者
|
||||
|
||||
| 场景 | 推荐方式 |
|
||||
|-----------|---------------------|
|
||||
| 已安装 Gemini CLI | `--gemini` 始终是良好的起始评审者 |
|
||||
| 希望免费多评审者覆盖 | `--gemini` + `--agy`（两者均使用 Google 凭据） |
|
||||
| 项目以 OpenAI 为主 | 添加 `--codex` 以获取 OpenAI 模型视角 |
|
||||
| 希望使用 GitHub Copilot 的模型 | 添加 `--opencode` |
|
||||
| 希望完全避免 API 费用 | 使用本地模型配置 Ollama 并使用 `--ollama` |
|
||||
| 发布前需要最大覆盖率 | `/gsd-plan-review-convergence N --all` |
|
||||
| 快速迭代并希望获得快速反馈 | 选择一个 CLI：`/gsd-review --phase N --gemini` |
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [验证并发布](verify-and-ship.md)
|
||||
- [配置](../CONFIGURATION.md)
|
||||
- [命令](../COMMANDS.md)
|
||||
- [文档索引](../README.md)
|
||||
160
docs/zh-CN/how-to/spike-and-sketch.md
Normal file
160
docs/zh-CN/how-to/spike-and-sketch.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 如何在正式提交前进行技术验证与界面草图
|
||||
|
||||
**目标：** 在将某个阶段锁定到具体方案之前，通过聚焦的可行性实验（spike）和一次性 HTML 原型（sketch）来降低实现风险。
|
||||
|
||||
**前提条件：** 无。`/gsd-spike` 和 `/gsd-sketch` 会自行创建所需的存储目录，不要求已初始化 GSD 项目。
|
||||
|
||||
---
|
||||
|
||||
## 决策：spike、sketch，还是两者都用
|
||||
|
||||
| 你想回答的问题… | 使用 |
|
||||
|---|---|
|
||||
| "这个技术方案真的可行吗？" | `/gsd-spike` |
|
||||
| "这个布局 / 交互 / 视觉处理感觉对吗？" | `/gsd-sketch` |
|
||||
| "正确的技术方案是什么，它应该长什么样？" | 两者都用，顺序是：先 spike，再 sketch |
|
||||
|
||||
Spike 通过可执行代码和 VALIDATED / INVALIDATED / PARTIAL 结论来回答二元可行性问题。Sketch 通过 2–3 个可在浏览器中对比的 HTML 变体来回答视觉问题。两者互为补充——spike 证明方案可构建，sketch 证明设计值得构建。
|
||||
|
||||
---
|
||||
|
||||
## 运行 spike
|
||||
|
||||
### 交互式引导（默认）
|
||||
|
||||
```bash
|
||||
/gsd-spike
|
||||
```
|
||||
|
||||
GSD 会询问技术问题，将其分解为 2–5 个独立实验，以 **Given / When / Then** 假设形式呈现，并在开始构建前请求确认。
|
||||
|
||||
### 直接提供想法
|
||||
|
||||
```bash
|
||||
/gsd-spike "can we stream LLM tokens through SSE"
|
||||
```
|
||||
|
||||
### 跳过引导，直接运行
|
||||
|
||||
```bash
|
||||
/gsd-spike --quick "websocket vs SSE latency"
|
||||
```
|
||||
|
||||
`--quick` 跳过分解对话，直接将参数作为单个 spike 问题处理。当问题已经足够具体、无需进一步细化时使用此选项。
|
||||
|
||||
### 每个实验产出内容
|
||||
|
||||
`.planning/spikes/NNN-descriptive-name/` 中的每个 spike 包含：
|
||||
|
||||
- 可运行的代码（非伪代码）
|
||||
- 在编写任何代码之前写好的 **Given / When / Then** 假设
|
||||
- 记录边界情况、方向调整和意外发现的调查轨迹
|
||||
- 附有证据的 **VALIDATED**、**INVALIDATED** 或 **PARTIAL** 结论
|
||||
- 包含 frontmatter、运行说明和结果的 `README.md`
|
||||
|
||||
所有 spike 均在 `.planning/spikes/MANIFEST.md` 中建立索引。
|
||||
|
||||
### 打包调查结果
|
||||
|
||||
当你获得有效信号后，将调查结果封装成项目本地技能，以便后续会话自动加载：
|
||||
|
||||
```bash
|
||||
/gsd-spike --wrap-up
|
||||
```
|
||||
|
||||
此命令会写入 `.claude/skills/spike-findings-[project]/`。该技能会被自动发现，并在后续的 `/gsd-sketch`、`/gsd-ui-phase` 和 `/gsd-plan-phase` 运行时加载——无需显式引用。
|
||||
|
||||
---
|
||||
|
||||
## 运行 sketch
|
||||
|
||||
### 风格引导（默认）
|
||||
|
||||
```bash
|
||||
/gsd-sketch
|
||||
```
|
||||
|
||||
GSD 会开启一段简短对话，在编写任何代码之前探索感觉、视觉参考和核心用户操作。它每次只问一个问题，只有在你说"开始"后才动手构建。
|
||||
|
||||
### 直接提供设计方向
|
||||
|
||||
```bash
|
||||
/gsd-sketch "dashboard layout"
|
||||
```
|
||||
|
||||
### 跳过风格引导，直接运行
|
||||
|
||||
```bash
|
||||
/gsd-sketch --quick "sidebar navigation"
|
||||
```
|
||||
|
||||
`--quick` 完全跳过引导对话，直接使用参数作为设计方向。
|
||||
|
||||
### 非 Claude 运行时（Codex、Gemini CLI 等）
|
||||
|
||||
```bash
|
||||
/gsd-sketch --text "onboarding flow"
|
||||
```
|
||||
|
||||
`--text` 将交互式提示替换为纯文本编号列表。当你的运行时不支持 `AskUserQuestion` 时使用此选项。
|
||||
|
||||
### 每个草图产出内容
|
||||
|
||||
`.planning/sketches/NNN-descriptive-name/` 中的每个 sketch 包含：
|
||||
|
||||
- 带有 2–3 个变体、可通过选项卡导航访问的 `index.html`——直接在浏览器中打开，无需构建步骤
|
||||
- 功能性交互元素（悬停、点击、过渡动画）
|
||||
- 使用来自先前 spike 调查结果的字段名和数据结构的近似真实内容
|
||||
- 来自 `.planning/sketches/themes/default.css` 的共享 CSS 变量
|
||||
- 包含设计问题、变体说明和关注点的 `README.md`
|
||||
|
||||
所有 sketch 均在 `.planning/sketches/MANIFEST.md` 中建立索引。
|
||||
|
||||
### 打包获胜的设计决策
|
||||
|
||||
选定变体后，将视觉决策捕获到项目本地技能中：
|
||||
|
||||
```bash
|
||||
/gsd-sketch --wrap-up
|
||||
```
|
||||
|
||||
此命令会写入 `.claude/skills/sketch-findings-[project]/`。该技能由 `/gsd-ui-phase` 自动获取——经过预验证的决策（布局、色彩方案、排版、间距）被视为已锁定，不会再次询问。
|
||||
|
||||
---
|
||||
|
||||
## 组合流程：spike → sketch → phase
|
||||
|
||||
当你对技术可行性和视觉方向都不确定时，推荐使用以下顺序：
|
||||
|
||||
```bash
|
||||
/gsd-spike "SSE vs WebSocket for real-time feed"
|
||||
/gsd-spike --wrap-up
|
||||
|
||||
/gsd-sketch "real-time feed UI"
|
||||
/gsd-sketch --wrap-up
|
||||
|
||||
/gsd-discuss-phase N
|
||||
/gsd-plan-phase N
|
||||
```
|
||||
|
||||
spike 调查结果会为 sketch 提供参考（真实数据结构、真实交互状态、实际约束）。两次 wrap-up 均会持久化决策，规划器和 UI 研究员会自动加载，因此在 `/gsd-discuss-phase` 或 `/gsd-ui-phase` 期间无需重新解释选择。
|
||||
|
||||
---
|
||||
|
||||
## spike 或 sketch 如何流入某个阶段
|
||||
|
||||
Spike 和 sketch 的产物不需要手动引用。GSD 会在以下两个时间点自动读取它们：
|
||||
|
||||
1. **`/gsd-sketch`** — 在构建原型前加载 `.claude/skills/spike-findings-*/`，使变体反映已验证的约束（流式状态、真实字段名等）
|
||||
2. **`/gsd-ui-phase N`** — 在生成 UI 设计契约前加载 `.claude/skills/sketch-findings-*/`；经过预验证的设计决策被视为已锁定
|
||||
|
||||
当存在 `spike-findings-*` 技能时，规划器也会读取 spike 调查结果，从而使已验证的技术选择（采用哪个库、哪种协议、哪种数据格式）直接流入任务计划，无需反复解释。
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [设计 UI 阶段](design-a-ui-phase.md)
|
||||
- [规划阶段](plan-a-phase.md)
|
||||
- [命令参考](../COMMANDS.md)
|
||||
- [文档索引](../README.md)
|
||||
120
docs/zh-CN/how-to/update-gsd.md
Normal file
120
docs/zh-CN/how-to/update-gsd.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# 如何更新 GSD Core
|
||||
|
||||
将现有的 GSD Core 安装更新到最新版本，在确认前预览变更日志，并恢复可能被更新覆盖的本地自定义配置。
|
||||
|
||||
**所需条件：** 与 GSD 安装时相同的运行时环境。更新命令在后台重新运行安装程序，因此需要 Node.js 和 npx（与最初安装时的要求相同）。
|
||||
|
||||
---
|
||||
|
||||
## 标准更新流程
|
||||
|
||||
在 AI 运行时内，执行：
|
||||
|
||||
```bash
|
||||
/gsd-update
|
||||
```
|
||||
|
||||
GSD 将执行以下操作：
|
||||
|
||||
1. 检测已安装的版本和安装范围（全局或本地）。
|
||||
2. 通过 npm 检查 `@opengsd/gsd-core` 的最新版本。
|
||||
3. 获取变更日志，并显示您已安装版本与最新版本之间的变更内容。
|
||||
4. 在执行任何操作前请求确认。
|
||||
5. 将 GSD 管理目录中发现的用户添加文件备份至 `gsd-user-files-backup/`。
|
||||
6. 运行安装程序（`npx @opengsd/gsd-core@latest --<runtime> --<scope>`）。
|
||||
7. 清除更新检查缓存，使状态栏指示器重置。
|
||||
8. 报告本地修改的 GSD 文件是否已备份至 `gsd-local-patches/`。
|
||||
|
||||
更新完成后请重启运行时，以加载新的命令和代理。
|
||||
|
||||
---
|
||||
|
||||
## 命令标志
|
||||
|
||||
| 标志 | 功能说明 |
|
||||
|------|--------------|
|
||||
| `--sync` | 更新后，从 GSD 注册表同步技能 |
|
||||
| `--reapply` | 更新后，将 `gsd-local-patches/` 中本地修改的 GSD 文件合并回来 |
|
||||
|
||||
```bash
|
||||
/gsd-update --sync # Update and sync skills
|
||||
/gsd-update --reapply # Update and reapply local patches
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 更新前查看变更日志
|
||||
|
||||
`/gsd-update` 在请求确认*之前*，始终会显示您已安装版本与最新版本之间的变更日志差异。您无需另行访问 GitHub。输出内容如下所示：
|
||||
|
||||
```text
|
||||
## GSD Update Available
|
||||
|
||||
Installed: 1.39.0
|
||||
Latest: 1.41.0
|
||||
|
||||
### What's New
|
||||
────────────────────────────────────────────────────────────
|
||||
[changelog entries for 1.40.0 and 1.41.0]
|
||||
────────────────────────────────────────────────────────────
|
||||
|
||||
Proceed with update? [Yes, update now / No, cancel]
|
||||
```
|
||||
|
||||
如果无法获取变更日志（无网络访问、npm 中断），更新在确认后仍会继续进行——不会因变更日志不可用而被阻断。
|
||||
|
||||
---
|
||||
|
||||
## 恢复本地自定义配置
|
||||
|
||||
### 您在 GSD 管理目录中添加的文件
|
||||
|
||||
如果您在 GSD 管理的目录中放置了自定义文件（例如，以 `gsd-` 为前缀的自定义代理，或 `commands/gsd/` 中的额外文件），安装程序会在清除这些目录前检测到它们，并将其复制到 `gsd-user-files-backup/`。更新完成后，请从该备份位置手动恢复这些文件。
|
||||
|
||||
您放置在 GSD 管理目录之外的文件——不以 `gsd-` 为前缀的自定义代理、`commands/gsd/` 之外的自定义命令、您的 `CLAUDE.md` 文件以及自定义钩子——安装程序不会对其进行任何操作。
|
||||
|
||||
### 您直接修改的 GSD 文件
|
||||
|
||||
如果您编辑了 GSD 安装的某个文件（例如，调整了某个代理的系统提示），安装程序会通过与清单的哈希比对检测到该修改，将文件备份至 `gsd-local-patches/`，然后用新版本替换它。更新完成后，执行：
|
||||
|
||||
```bash
|
||||
/gsd-update --reapply
|
||||
```
|
||||
|
||||
此命令会将您在 `gsd-local-patches/` 中的修改合并回新安装的文件中。
|
||||
|
||||
如果您在之前的更新后跳过了 `--reapply`，现在想应用补丁，执行：
|
||||
|
||||
```bash
|
||||
/gsd-update --reapply
|
||||
```
|
||||
|
||||
单独运行 `--reapply` 而不触发新下载是安全的——如果您已是最新版本，GSD 会跳过安装步骤，直接执行补丁重新应用。
|
||||
|
||||
---
|
||||
|
||||
## 当 npm 不可用时
|
||||
|
||||
如果 `npx @opengsd/gsd-core@latest` 因 npm 中断、网络限制，或因您正在使用源代码仓库而失败，请使用 [docs/manual-update.md](../../manual-update.md) 中的手动更新流程。该文档涵盖拉取最新提交、构建钩子分发包以及直接运行 `node bin/install.js` 的步骤。
|
||||
|
||||
---
|
||||
|
||||
## 如果您已是最新版本
|
||||
|
||||
`/gsd-update` 会提前退出并显示确认消息——无需下载、无需安装、无需重启。
|
||||
|
||||
---
|
||||
|
||||
## 安装程序迁移
|
||||
|
||||
每个 GSD 版本可能包含安装程序迁移，用于重命名、移动或停用管理文件。迁移层会在写入新包内容之前自动运行。会影响您已修改文件的迁移操作将提示确认，而不是静默执行。有关完整设计和运行时配置合约注册表，请参阅 [docs/installer-migrations.md](../../installer-migrations.md)。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [在您的运行时上安装](install-on-your-runtime.md)
|
||||
- [命令参考](../COMMANDS.md)
|
||||
- [手动更新](../../manual-update.md)
|
||||
- [安装程序迁移](../../installer-migrations.md)
|
||||
- [文档索引](../README.md)
|
||||
124
docs/zh-CN/how-to/verify-and-ship.md
Normal file
124
docs/zh-CN/how-to/verify-and-ship.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# 如何验证并发布阶段
|
||||
|
||||
**目标：** 对已执行的工作进行用户验收测试，诊断并修复任何失败，然后开启一个带有自动生成正文的拉取请求。
|
||||
|
||||
**前提条件：** 该阶段已执行完毕并包含 `SUMMARY.md` 文件。如果执行尚未完成，请参阅[执行阶段](execute-a-phase.md)。
|
||||
|
||||
---
|
||||
|
||||
## 运行用户验收测试
|
||||
|
||||
```bash
|
||||
/gsd-verify-work 1
|
||||
```
|
||||
|
||||
GSD Core 读取该阶段的 `SUMMARY.md` 文件，提取用户可观测的交付物，并逐一引导您完成验证。对于每个检查点，它会展示*应该*发生的情况，并询问实际情况是否与之匹配。
|
||||
|
||||
- `yes` / `y` / 直接回车 → 通过，进入下一项测试
|
||||
- 其他任何输入 → 记录为问题，严重程度根据您的描述推断
|
||||
|
||||
您无需手动分类严重程度——GSD Core 会从您的描述中推断（"崩溃" → 阻塞级，"无法使用" → 严重级，"看起来不对" → 外观级）。
|
||||
|
||||
进度将写入 `.planning/phases/01-<name>/01-UAT.md`，在 `/clear` 之后依然保留。若会话中断，重新运行 `/gsd-verify-work 1`，GSD Core 会提示是否从上次检查点恢复。
|
||||
|
||||
---
|
||||
|
||||
## 发现失败时：自动诊断与修复规划
|
||||
|
||||
如果有测试报告问题，GSD Core 会自动执行以下步骤：
|
||||
|
||||
1. **诊断根本原因** — 为每个问题并行启动调试代理，并将根本原因更新至 `UAT.md`。
|
||||
2. **规划差距弥补** — 在差距弥补模式下启动 `gsd-planner`，读取 `UAT.md`（含诊断结果）并生成新的 `PLAN.md` 文件。
|
||||
3. **验证修复计划** — 启动 `gsd-plan-checker` 确保计划可执行。若发现问题，规划器与检查器最多迭代三次。
|
||||
4. **呈现下一步** — 当计划通过检查器时：
|
||||
|
||||
```
|
||||
Plans verified and ready for execution.
|
||||
|
||||
`/clear` then `/gsd-execute-phase 1 --gaps-only`
|
||||
```
|
||||
|
||||
运行提示的命令以应用修复，然后重新运行 `/gsd-verify-work 1` 确认一切通过。
|
||||
|
||||
---
|
||||
|
||||
## 所有测试通过时：发布阶段
|
||||
|
||||
一旦所有 UAT 测试通过（或首次运行且未发现问题），该阶段将自动在 `ROADMAP.md` 和 `STATE.md` 中标记为已完成。
|
||||
|
||||
```bash
|
||||
/gsd-ship 1
|
||||
```
|
||||
|
||||
GSD Core 执行预检（验证状态、干净的工作树、分支、远程仓库、`gh` CLI 身份验证），推送分支并创建 PR：
|
||||
|
||||
```bash
|
||||
/gsd-ship 1 # 准备审查的 PR
|
||||
/gsd-ship 1 --draft # 草稿 PR — 当后续还有更多阶段时很有用
|
||||
```
|
||||
|
||||
PR 正文由规划产物自动组装：
|
||||
|
||||
- 来自 `ROADMAP.md` 的阶段目标
|
||||
- 来自 `SUMMARY.md` 文件及其关键文件的各计划摘要
|
||||
- 已解决的需求（REQ-IDs）
|
||||
- 来自 `VERIFICATION.md` 的验证状态
|
||||
- 来自 `STATE.md` 的关键决策
|
||||
|
||||
无需手动编写正文。
|
||||
|
||||
---
|
||||
|
||||
## 可选：发布前或发布后的代码审查
|
||||
|
||||
`/gsd-ship` 不会自动运行代码审查，但您可以在任意节点插入审查：
|
||||
|
||||
**验证前**（在 UAT 之前发现问题）：
|
||||
|
||||
```bash
|
||||
/gsd-code-review 1 # 标准审查
|
||||
/gsd-code-review 1 --fix # 审查后自动修复 Critical 和 Warning 发现
|
||||
```
|
||||
|
||||
**PR 开启后**（在合并前把关质量）：
|
||||
|
||||
```bash
|
||||
/gsd-code-review 1 --depth=deep # 包含导入图的跨文件分析
|
||||
```
|
||||
|
||||
请参阅[配置跨 AI 审查](set-up-cross-ai-review.md)，了解如何在周期早期为计划审查配置 Gemini、Codex 或其他审查工具。
|
||||
|
||||
---
|
||||
|
||||
## 可选：创建干净的 PR 分支
|
||||
|
||||
如果您的分支包含不希望审查者看到的 `.planning/` 提交：
|
||||
|
||||
```bash
|
||||
/gsd-pr-branch # 相对于 main 进行过滤
|
||||
/gsd-pr-branch develop # 相对于 develop 进行过滤
|
||||
```
|
||||
|
||||
`/gsd-pr-branch` 会创建一个仅包含代码变更的新分支——规划产物提交将被排除。若您的团队审查规范不包含规划噪音，请在 `/gsd-ship` 之前运行此命令。
|
||||
|
||||
---
|
||||
|
||||
## 关闭里程碑
|
||||
|
||||
如果这是里程碑中的最后一个阶段，请运行里程碑审计并将其归档：
|
||||
|
||||
```bash
|
||||
/gsd-audit-milestone # 验证所有需求已发布
|
||||
/gsd-complete-milestone # 归档，创建 git 标签
|
||||
```
|
||||
|
||||
`/gsd-complete-milestone` 是 PR 合并后的自然下一步。请参阅[阶段循环](../explanation/the-phase-loop.md)，了解验证与发布如何融入完整的项目生命周期。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [执行阶段](execute-a-phase.md)
|
||||
- [配置跨 AI 审查](set-up-cross-ai-review.md)
|
||||
- [阶段循环](../explanation/the-phase-loop.md)
|
||||
- [命令参考](../COMMANDS.md)
|
||||
157
docs/zh-CN/how-to/work-in-parallel-with-workstreams.md
Normal file
157
docs/zh-CN/how-to/work-in-parallel-with-workstreams.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# 如何通过工作流并行处理多个领域
|
||||
|
||||
**目标：** 并发推进不同里程碑领域（后端 API、前端仪表板、基础设施或其他关注点）的工作，同时避免一个领域的规划状态污染另一个领域。
|
||||
|
||||
**前提条件：** 已激活的 GSD Core 项目（`.planning/ROADMAP.md` 存在）。若尚未创建，请先运行 `/gsd-new-project`。
|
||||
|
||||
---
|
||||
|
||||
## 什么是工作流
|
||||
|
||||
工作流是单一代码库内部的隔离规划上下文。每个工作流拥有独立的 `.planning/workstreams/<name>/` 子树，其中包含独立的 `STATE.md`、`ROADMAP.md`、`REQUIREMENTS.md` 以及 `phases/` 目录。代码库本身——源代码、git 历史记录和分支——在所有工作流之间共享。
|
||||
|
||||
```
|
||||
.planning/
|
||||
├── PROJECT.md ← shared
|
||||
├── config.json ← shared
|
||||
├── codebase/ ← shared
|
||||
└── workstreams/
|
||||
├── backend-api/
|
||||
│ ├── STATE.md
|
||||
│ ├── ROADMAP.md
|
||||
│ ├── REQUIREMENTS.md
|
||||
│ └── phases/
|
||||
└── frontend-dash/
|
||||
├── STATE.md
|
||||
├── ROADMAP.md
|
||||
├── REQUIREMENTS.md
|
||||
└── phases/
|
||||
```
|
||||
|
||||
当某个工作流处于激活状态时，所有 GSD 命令——`/gsd-progress`、`/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase`——都将从该工作流的目录读取并写入。切换工作流会将所有这些命令重定向到另一个子树，而不会影响源代码树。
|
||||
|
||||
---
|
||||
|
||||
## 创建工作流
|
||||
|
||||
```bash
|
||||
/gsd-workstreams create backend-api
|
||||
```
|
||||
|
||||
GSD 会在 `.planning/workstreams/backend-api/` 下创建工作流目录，并初始化一个框架 `STATE.md` 和 `ROADMAP.md`。工作流不会自动激活——需要显式切换。
|
||||
|
||||
---
|
||||
|
||||
## 列出工作流
|
||||
|
||||
```bash
|
||||
/gsd-workstreams list
|
||||
```
|
||||
|
||||
显示所有工作流，以及当前会话中哪个工作流处于激活状态。
|
||||
|
||||
---
|
||||
|
||||
## 切换到某个工作流
|
||||
|
||||
```bash
|
||||
/gsd-workstreams switch backend-api
|
||||
```
|
||||
|
||||
从此时起，所有 GSD 工作流命令均在 `backend-api` 上下文中运行。切换是会话范围的：当多个 Claude Code 终端同时打开同一仓库时，每个会话可以持有不同的激活工作流，互不干扰。
|
||||
|
||||
切换后，按正常阶段工作流推进：
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 1
|
||||
/gsd-plan-phase 1
|
||||
/gsd-execute-phase 1
|
||||
/gsd-verify-work 1
|
||||
```
|
||||
|
||||
如需在另一个领域工作，在第二个终端中切换工作流：
|
||||
|
||||
```bash
|
||||
/gsd-workstreams switch frontend-dash
|
||||
/gsd-discuss-phase 1
|
||||
/gsd-plan-phase 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 查看所有工作流的进度
|
||||
|
||||
```bash
|
||||
/gsd-workstreams progress
|
||||
```
|
||||
|
||||
打印跨工作流摘要——每个工作流的阶段状态、当前位置和未完成工作——无需在工作流之间来回切换。
|
||||
|
||||
查看单个工作流的详细状态：
|
||||
|
||||
```bash
|
||||
/gsd-workstreams status backend-api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 在工作流中恢复工作
|
||||
|
||||
在上下文重置或新会话后，恢复您的位置：
|
||||
|
||||
```bash
|
||||
/gsd-workstreams resume backend-api
|
||||
```
|
||||
|
||||
此命令会激活该工作流并恢复上次已知位置，等价于切换后再运行 `/gsd-resume-work`。
|
||||
|
||||
---
|
||||
|
||||
## 归档已完成的工作流
|
||||
|
||||
当某个工作流的里程碑工作完成时：
|
||||
|
||||
```bash
|
||||
/gsd-workstreams complete backend-api
|
||||
```
|
||||
|
||||
GSD 会将该工作流标记为已归档，并将其从活跃列表中移出。规划产物将保留在 `.planning/workstreams/backend-api/` 下以供审计。
|
||||
|
||||
---
|
||||
|
||||
## 在不切换工作流的情况下将单条命令定向到特定工作流
|
||||
|
||||
如需对某个特定工作流运行一条命令，而不更改当前会话的激活上下文，请使用 `--ws` 标志：
|
||||
|
||||
```bash
|
||||
/gsd-progress --ws frontend-dash
|
||||
/gsd-plan-phase 2 --ws backend-api
|
||||
```
|
||||
|
||||
`--ws` 在解析顺序中具有最高优先级，不会更改会话范围的指针。
|
||||
|
||||
---
|
||||
|
||||
## 何时选择工作流而非工作区
|
||||
|
||||
在以下情况下选择工作流：
|
||||
|
||||
- 所有工作都位于**同一仓库**并共享相同的 git 历史记录
|
||||
- 您希望**并发**规划或讨论不同关注领域（API、UI、基础设施），而不让一个工作流的 `STATE.md` 覆盖另一个的
|
||||
- 创建时不需要为每个工作流单独建立分支（当然，您仍可在每个工作流的执行过程中正常创建分支）
|
||||
- 创建完整 git worktree 的开销与所需隔离程度不匹配
|
||||
|
||||
在以下情况下选择[工作区](isolate-work-with-workspaces.md)：
|
||||
|
||||
- 您需要在**多个仓库**之间工作（例如 `hr-ui` 和 `ZeymoAPI`）
|
||||
- 每个功能需要**独立 git worktree** 或克隆的隔离——完全独立的分支、锁文件和构建产物
|
||||
- 您希望在每个工作区中独立运行 `/gsd-new-project`，拥有完全独立的 `.planning/` 根目录，而不是主仓库 `.planning/` 的子目录
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [用工作区隔离工作](isolate-work-with-workspaces.md)
|
||||
- [阶段循环](../explanation/the-phase-loop.md)
|
||||
- [命令](../COMMANDS.md)
|
||||
- [文档索引](../README.md)
|
||||
96
docs/zh-CN/issue-driven-orchestration.md
Normal file
96
docs/zh-CN/issue-driven-orchestration.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# 使用 GSD 进行议题驱动的编排
|
||||
|
||||
**状态：** 稳定工作流指南
|
||||
**受众：** 在 GitHub Issues、Linear、Jira 或类似议题跟踪系统中管理工作的开发者，希望通过 GSD 现有原语驱动 AI 辅助实现。
|
||||
|
||||
## 本指南的内容
|
||||
|
||||
本指南提供一套方案，将 GSD 已有的命令组合成一个"议题跟踪 → 工作区 → 计划/执行 → 验证/审核 → PR"的循环。这仅是文档说明。无新命令、无守护进程、无跟踪系统集成 —— 下文引用的每一条命令在 GSD 中均已存在。
|
||||
|
||||
本方案的结构受到 OpenAI 开源 [Symphony 编排参考](https://openai.com/index/open-source-codex-orchestration-symphony/)（[代码库](https://github.com/openai/symphony)）的启发。GSD 不内嵌或封装 Symphony。Symphony 中的编排*概念*可以清晰地映射到 GSD 已有的原语上；本指南只是将这种映射明确阐述出来，让你无需编写粘合代码或绕过 GSD 的安全门控即可采用该模式。
|
||||
|
||||
## 为何存在本指南
|
||||
|
||||
GSD 具备议题驱动 AI 开发的基础构建块 ——
|
||||
`/gsd-workspace --new`、`/gsd-manager`、`/gsd-autonomous`、`/gsd-verify-work`、
|
||||
`/gsd-review`、`/gsd-ship`，以及 `STATE.md` 和阶段产物套件
|
||||
—— 但缺少一份说明如何从单个跟踪议题驱动它们、无需编写自定义编排脚本的指南。没有这份指南，常见的失效模式是：
|
||||
|
||||
- 使用不足：开发者手动运行 discuss/plan/execute，即使工作模式完全适合，也从未使用
|
||||
`/gsd-manager` 或 `/gsd-autonomous`。
|
||||
- 绕过脚本：开发者在跟踪系统与 `claude` 调用之间编写临时 shell 循环，绕过 `STATE.md`、阶段清单和验证门控。
|
||||
|
||||
本指南使规范循环变得易于发现。
|
||||
|
||||
## 概念映射
|
||||
|
||||
每行将 Symphony 风格的编排概念映射到 GSD 中对应的原语。在阅读 Symphony 文档、博客文章或第三方编排资料时，可将此表用作转换参考。
|
||||
|
||||
| Symphony 概念 | GSD 原语 |
|
||||
|---|---|
|
||||
| `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`，或手动打开的跟踪议题 |
|
||||
| 并发控制 | Manager / 后台代理语义（无持续轮询器） |
|
||||
|
||||
映射是单向的：GSD 持有安全门控（验证、人工审核、后续工作创建的明确确认）。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 不会自动向远程跟踪系统发布内容。
|
||||
|
||||
PR 合并后，循环关闭。PR 正文中的自动关闭关键词（`Closes #NNN` / `Fixes #NNN`）会在合并时关闭跟踪议题。
|
||||
|
||||
## 安全边界
|
||||
|
||||
该循环之所以安全，是因为四项不变量在构建上得到保证：
|
||||
|
||||
- **独立工作树。** 每个议题在 `/gsd-workspace --new` 工作树中运行，因此部分工作、中止的计划和探索性提交永远不会触及 `main`。`gsd-local-patches/` 是恢复入口，当工作树的手动编辑需要跨更新带回时可使用。
|
||||
- **明确的人工审核。** `/gsd-review` 和 `/gsd-ship` 均会停下来等待人工批准。没有自动合并，也没有从执行路径自动创建 PR 的路径。如果你想为特定代码库移除人工门控，那是你的分支保护 / 合并队列策略决定，而非 GSD 代为选择的。
|
||||
- **不自动公开发布。** GSD 从不在没有明确用户发起命令的情况下打开、评论或关闭跟踪议题。后续工作捕获默认写入本地产物（备注、种子、里程碑）；推回跟踪系统是单独的手动步骤。
|
||||
- **发布前先验证。** `/gsd-verify-work` 的 UAT.md 必须记录证据，才能运行 `/gsd-ship`。推荐的规范是将 `verification_failed` 视为阻塞项，即使实现看起来正确 —— 失败通常意味着遗漏了验收标准，而非测试不稳定。
|
||||
|
||||
如果这些不变量中的任何一项被绕过（例如直接对工作树运行 `claude`、跳过 `/gsd-verify-work`，或在没有用户确认的情况下通过跟踪 API 脚本化创建议题），本指南的保证将不再适用。
|
||||
|
||||
## 非目标
|
||||
|
||||
本指南刻意**不**提出以下任何内容。在此列出，以防止未来贡献者在代码审查中重新讨论：
|
||||
|
||||
- **不内嵌或复制 Symphony 代码。** GSD 复用自身原语。上述映射是概念性的；本代码库中不包含任何 Symphony 衍生源码。
|
||||
- **无长期运行的守护进程。** GSD 不轮询 GitHub 或 Linear。Manager 和自主工作流通过后台代理语义处理并发，而非通过守护进程。
|
||||
- **无强制跟踪系统依赖。** 该循环无需任何跟踪系统集成即可运行。"跟踪议题"步骤是一种*人工输入* —— URL 写入 `CONTEXT.md`。GSD 不关心你使用哪个跟踪系统，或者你是否使用跟踪系统。
|
||||
- **不绕过验证、审核或人工决策门控。** 即使在运行 `/gsd-autonomous` 时，验证和审核门控依然触发。"autonomous（自主）"标签指的是阶段间的推进，而非跳过人工批准。
|
||||
- **不扩展默认技能 / 命令面。** 本指南引用的每一条命令均已存在。本指南是文档面，而非功能面。
|
||||
|
||||
## 可能的未来后续
|
||||
|
||||
如果维护者在使用该循环的过程中积累了足够的经验，一个独立的 approved-enhancement 可在未来添加*最小化*的跟踪桥接：
|
||||
|
||||
- 将一个 GitHub 或 Linear 议题导入 GSD 工作区 / 阶段。
|
||||
- 将 `UAT.md` 证据作为评论导出到源议题。
|
||||
- 从 `/gsd-capture --seed` 输出生成后续跟踪议题。
|
||||
|
||||
上述每一项都将是独立的增强提案，因为每项都增加了集成面和持续维护负担。它们超出了本指南的范围。
|
||||
|
||||
## 相关资源
|
||||
|
||||
- [阶段循环](explanation/the-phase-loop.md) — 说明 discuss → plan → execute → verify → ship 如何作为重复循环组合在一起。
|
||||
- [工作区操作指南](how-to/work-in-parallel-with-workstreams.md) — 创建和管理并行工作树的逐步指南。
|
||||
- [文档索引](README.md) — GSD Core 文档的完整目录。
|
||||
- [docs/USER-GUIDE.md](./USER-GUIDE.md) — 上述各命令以任务为导向的操作指南。
|
||||
- [docs/COMMANDS.md](COMMANDS.md) — `/gsd-*` 命令的完整参考。
|
||||
- [docs/FEATURES.md](FEATURES.md) — 功能级能力矩阵（工作区、manager、autonomous、verify、review、ship）。
|
||||
- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — 阶段产物生命周期与 `STATE.md` 机制。
|
||||
148
docs/zh-CN/reference/context-md.md
Normal file
148
docs/zh-CN/reference/context-md.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# CONTEXT.md 结构参考
|
||||
|
||||
每个阶段的 `CONTEXT.md` 是 GSD Core 用于保存 `/gsd:discuss-phase` 阶段所收集的实现决策的载体。它是研究代理和规划代理的主要上游输入。本页面记录其结构。参见[文档索引](../README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
每个经过讨论工作流处理的阶段，均会在以下路径生成一份 `CONTEXT.md`：
|
||||
|
||||
```
|
||||
.planning/phases/<NN>-<slug>/<NN>-CONTEXT.md
|
||||
```
|
||||
|
||||
示例：`.planning/phases/03-post-feed/03-CONTEXT.md`。
|
||||
|
||||
该文件由 `get-shit-done/workflows/discuss-phase.md` 中的 `write_context` 步骤生成（或通过 PRD/ADR 摄入快速路径生成）。在正常操作中，该文件不会被手动编辑——讨论阶段工作流负责写入，下游代理将其作为封闭的可信来源读取。
|
||||
|
||||
---
|
||||
|
||||
## 前言（Frontmatter）
|
||||
|
||||
`CONTEXT.md` 不包含 YAML 前言。元数据以内联形式写在正文顶部：
|
||||
|
||||
```markdown
|
||||
# Phase [X]: [Name] - Context
|
||||
|
||||
**Gathered:** [ISO date]
|
||||
**Status:** Ready for planning
|
||||
```
|
||||
|
||||
`Status` 字段在文件首次写入时始终为 `Ready for planning`，创建后不再更新。
|
||||
|
||||
---
|
||||
|
||||
## 块结构
|
||||
|
||||
正文由若干具名 XML 风格的块组成，以固定顺序出现。下游代理通过块名而非行号来读取各块内容。
|
||||
|
||||
| 块名 | 用途 | 由谁填充 | 由谁消费 |
|
||||
|---|---|---|---|
|
||||
| `<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` |
|
||||
| `<deferred>` | 讨论中出现但属于其他阶段的想法，予以保留以免遗失。当待办事项经过审查但未纳入范围时，包含 `Reviewed Todos` 子节。 | `discuss-phase`（范围蔓延重定向） | 不被自动化代理消费；仅供人工参考 |
|
||||
|
||||
---
|
||||
|
||||
## 决策标识符格式
|
||||
|
||||
`<decisions>` 中的每条决策均带有顺序编号的 `D-NN` 标识符：
|
||||
|
||||
```markdown
|
||||
### Layout style
|
||||
- **D-01:** Card-based layout, not timeline or list
|
||||
- **D-02:** Each card shows: author avatar, name, timestamp, full post content, reaction counts
|
||||
```
|
||||
|
||||
标识符的作用域限定在阶段内。第 3 阶段中的 `D-01` 与第 7 阶段中的 `D-01` 无关。计划检查器（维度 7）会验证每个 `D-NN` 是否在生成计划中至少有一个任务动作加以覆盖。
|
||||
|
||||
---
|
||||
|
||||
## 规范引用
|
||||
|
||||
`<canonical_refs>` 块为**必填项**。如果代理发现其缺失，会将该 CONTEXT.md 视为不完整并发出警告。条目按主题分组，包含完整相对路径以及对文件所决定或定义内容的简要说明：
|
||||
|
||||
```markdown
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### Feed display
|
||||
- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
|
||||
- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualisation requirements
|
||||
|
||||
### Empty states
|
||||
- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
|
||||
|
||||
</canonical_refs>
|
||||
```
|
||||
|
||||
当项目没有外部规格文档时，该节应明确说明：
|
||||
|
||||
```
|
||||
No external specs — requirements fully captured in decisions above
|
||||
```
|
||||
|
||||
在 `<decisions>` 中散落的内联提及（如"参见 ADR-019"）是不够的；代理需要在专用节中获取完整路径。
|
||||
|
||||
---
|
||||
|
||||
## 决策覆盖关卡关系
|
||||
|
||||
计划检查器的**维度 7：上下文合规性**在规划完成后执行覆盖关卡检查：
|
||||
|
||||
1. `<decisions>` 中的每个 `D-NN` 标识符必须出现在至少一个计划任务的 `<action>` 或说明中。
|
||||
2. 任何任务均不得实现 `<deferred>` 中列出的内容（即范围蔓延）。
|
||||
3. `Claude's Discretion` 领域免于此检查——规划者可自由选择。
|
||||
|
||||
决策被成功纳入计划的 CONTEXT.md 被视为合规。决策被悄然丢弃或部分交付的 CONTEXT.md 会触发**维度 7b：范围缩减检测**，这始终是一个**阻断项**。
|
||||
|
||||
---
|
||||
|
||||
## SPEC.md 集成
|
||||
|
||||
当 `/gsd:spec-phase` 在讨论阶段之前运行时，`check_spec` 步骤会找到 `*-SPEC.md` 文件并激活 `<spec_lock>`：
|
||||
|
||||
```markdown
|
||||
<spec_lock>
|
||||
## Requirements (locked via SPEC.md)
|
||||
|
||||
**12 requirements are locked.** See `03-SPEC.md` for full requirements, boundaries, and acceptance criteria.
|
||||
|
||||
Downstream agents MUST read `03-SPEC.md` before planning or implementing. Requirements are not duplicated here.
|
||||
|
||||
**In scope (from SPEC.md):** [copied from SPEC.md Boundaries]
|
||||
**Out of scope (from SPEC.md):** [copied from SPEC.md Boundaries]
|
||||
|
||||
</spec_lock>
|
||||
```
|
||||
|
||||
当 `<spec_lock>` 存在时，`<decisions>` 中仅包含来自讨论的实现决策——即"如何做"，而非"做什么"。需求不会在两个文件之间重复。
|
||||
|
||||
---
|
||||
|
||||
## 页脚
|
||||
|
||||
每份 CONTEXT.md 以身份页脚结尾：
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
||||
*Phase: XX-name*
|
||||
*Context gathered: [date]*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [PLAN.md 结构](plan-md.md)
|
||||
- [规划产物](planning-artifacts.md)
|
||||
- [讨论模式](../workflow-discuss-mode.md)
|
||||
- [文档索引](../README.md)
|
||||
249
docs/zh-CN/reference/plan-md.md
Normal file
249
docs/zh-CN/reference/plan-md.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# PLAN.md 模式参考
|
||||
|
||||
每个计划的 `PLAN.md` 是 GSD Core 的可执行工作单元——一份结构化文档，精确告知执行器代理需要构建什么以及如何验证构建是否正确完成。本页记录其结构。参见[文档索引](../README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
计划存放在以下位置的阶段目录中：
|
||||
|
||||
```
|
||||
.planning/phases/<NN>-<slug>/<NN>-<PP>-PLAN.md
|
||||
```
|
||||
|
||||
例如：`.planning/phases/03-post-feed/03-02-PLAN.md`（第 3 阶段，第 2 计划）。
|
||||
|
||||
计划由 `gsd-planner` 代理生成（由 `/gsd:plan-phase` 触发），并由 `execute-phase` 消费。一个阶段通常包含一到四个计划；同一阶段内的计划被分配到执行波次，以便独立工作并行运行。
|
||||
|
||||
---
|
||||
|
||||
## YAML 前置元数据
|
||||
|
||||
每个 PLAN.md 以位于 `---` 分隔符之间的 YAML 前置元数据块开头。
|
||||
|
||||
### 注释示例
|
||||
|
||||
```yaml
|
||||
---
|
||||
phase: 03-post-feed
|
||||
plan: 02
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on: ["03-01"]
|
||||
files_modified:
|
||||
- src/components/PostFeed.tsx
|
||||
- src/components/PostCard.tsx
|
||||
- src/app/feed/page.tsx
|
||||
autonomous: true
|
||||
requirements: ["FEED-01", "FEED-03"]
|
||||
user_setup: []
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "User can scroll through posts from followed accounts"
|
||||
- "Each post shows author avatar, name, timestamp, and content"
|
||||
- "Empty state appears when no posts exist"
|
||||
artifacts:
|
||||
- path: "src/components/PostFeed.tsx"
|
||||
provides: "Scrollable post list"
|
||||
min_lines: 40
|
||||
- path: "src/components/PostCard.tsx"
|
||||
provides: "Individual post card"
|
||||
exports: ["PostCard"]
|
||||
key_links:
|
||||
- from: "src/components/PostFeed.tsx"
|
||||
to: "/api/feed"
|
||||
via: "fetch in useEffect"
|
||||
pattern: "fetch.*api/feed"
|
||||
---
|
||||
```
|
||||
|
||||
### 前置元数据字段参考
|
||||
|
||||
| 字段 | 是否必填 | 类型 | 用途 |
|
||||
|---|---|---|---|
|
||||
| `phase` | 是 | string | 阶段标识符，例如 `03-post-feed`。 |
|
||||
| `plan` | 是 | string | 阶段内的计划编号，例如 `02`。 |
|
||||
| `type` | 是 | `execute` 或 `tdd` | 标准计划使用 `execute`；测试驱动计划使用 `tdd`，测试在实现之前编写。 |
|
||||
| `wave` | 是 | integer | 执行波次。波次 1 中的计划并行运行（无依赖关系）。波次 2 及以上的计划等待上一波次的所有计划完成后才开始。由 `gsd-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`。 |
|
||||
| `requirements` | 是 | array of IDs | 该计划所对应的 ROADMAP.md 中的需求 ID。每个阶段需求 ID 必须出现在至少一个计划的 `requirements` 字段中。空数组是阻断项（BLOCKER）。 |
|
||||
| `user_setup` | 否 | array of objects | Claude 无法自动化的外部服务设置步骤（账户创建、密钥获取、控制台配置）。存在时，execute-phase 会为开发者生成 `USER-SETUP.md` 检查清单。 |
|
||||
| `must_haves` | 是 | object | 以目标为导向的验证标准。详见下文。 |
|
||||
|
||||
---
|
||||
|
||||
## `must_haves` 字段
|
||||
|
||||
`must_haves` 描述了阶段目标达成后必须可观测到的真实状态。该字段在规划阶段派生，并在执行后由 `gsd-verifier` 代理验证。
|
||||
|
||||
### 子字段
|
||||
|
||||
| 子字段 | 类型 | 用途 |
|
||||
|---|---|---|
|
||||
| `truths` | array of strings | 从用户视角可观测到的行为。每项必须可验证。示例：`"User can send a message"`，而非 `"WebSocket library installed"`。 |
|
||||
| `artifacts` | array of objects | 必须存在且具有实质性实现（非桩代码）的文件。 |
|
||||
| `artifacts[].path` | string | 相对于项目根目录的文件路径。 |
|
||||
| `artifacts[].provides` | string | 该文件所提供的能力。 |
|
||||
| `artifacts[].min_lines` | integer（可选） | 被视为非桩代码的最小行数。 |
|
||||
| `artifacts[].exports` | array of strings（可选） | 需要验证的预期命名导出项。 |
|
||||
| `artifacts[].contains` | string（可选） | 必须出现在文件中的正则表达式或字面量模式。 |
|
||||
| `key_links` | array of objects | 制品之间的关键连接——使系统端到端运行的接线。 |
|
||||
| `key_links[].from` | string | 源文件或组件。 |
|
||||
| `key_links[].to` | string | 目标文件、端点或模块。 |
|
||||
| `key_links[].via` | string | 连接方式描述（例如 `fetch in useEffect`、`Prisma query`、`import`）。 |
|
||||
| `key_links[].pattern` | string（可选） | 用于验证源代码中连接是否存在的正则表达式。 |
|
||||
|
||||
---
|
||||
|
||||
## 正文结构
|
||||
|
||||
前置元数据之后，计划正文使用执行器代理读取的具名 XML 风格块。
|
||||
|
||||
### `<objective>`
|
||||
|
||||
说明计划所交付的内容及其对项目的重要性：
|
||||
|
||||
```xml
|
||||
<objective>
|
||||
Implement the post feed as a scrollable card list.
|
||||
|
||||
Purpose: Core display feature for the social feed phase.
|
||||
Output: PostFeed and PostCard components wired to /api/feed.
|
||||
</objective>
|
||||
```
|
||||
|
||||
### `<execution_context>`
|
||||
|
||||
列出执行器在开始前读取的工作流文件。始终包含 execute-plan 工作流；当计划包含检查点任务时，额外添加检查点参考：
|
||||
|
||||
```xml
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@~/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
```
|
||||
|
||||
### `<context>`
|
||||
|
||||
引用执行器需要读取的源文件。包括项目级规划文档以及计划必须复用其模式或类型的源文件。仅当后续计划对其类型或决策存在真实依赖时，才引用前序计划的 `SUMMARY.md` 文件——而非无条件引用：
|
||||
|
||||
```xml
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@src/components/UserCard.tsx
|
||||
</context>
|
||||
```
|
||||
|
||||
### `<tasks>`
|
||||
|
||||
包含一个或多个 `<task>` 元素。对于 `type="auto"` 的任务，每个任务元素必须包含 `<name>`、`<files>`、`<read_first>`、`<action>`、`<verify>`、`<acceptance_criteria>` 和 `<done>`。
|
||||
|
||||
---
|
||||
|
||||
## 任务类型
|
||||
|
||||
| 类型 | 使用场景 | 自主程度 |
|
||||
|---|---|---|
|
||||
| `auto` | 执行器可独立完成的所有内容。 | 完全自主。 |
|
||||
| `checkpoint:human-verify` | 需要人工查看运行中的界面或服务进行视觉或功能验证。 | 暂停执行；呈现给开发者；批准后恢复。 |
|
||||
| `checkpoint:decision` | 执行过程中出现的需要开发者输入的实现选择。 | 暂停执行；呈现选项；选择后恢复。 |
|
||||
| `checkpoint:human-action` | 真正不可避免的手动步骤（账户创建、硬件交互）。谨慎使用。 | 暂停执行；确认后恢复。 |
|
||||
|
||||
包含任何检查点任务的计划必须在前置元数据中设置 `autonomous: false`。
|
||||
|
||||
---
|
||||
|
||||
## `auto` 任务结构
|
||||
|
||||
```xml
|
||||
<task type="auto">
|
||||
<name>Task 1: Create PostCard component</name>
|
||||
<files>src/components/PostCard.tsx</files>
|
||||
<read_first>src/components/UserCard.tsx, src/types/post.ts</read_first>
|
||||
<action>Create PostCard component accepting a Post prop (id, authorId, content, createdAt,
|
||||
reactionCount). Render author avatar using UserAvatar from UserCard pattern. Show timestamp
|
||||
using date-fns formatDistanceToNow. Export as named export PostCard.</action>
|
||||
<verify>npx tsc --noEmit</verify>
|
||||
<acceptance_criteria>
|
||||
- src/components/PostCard.tsx exports named export PostCard
|
||||
- PostCard.tsx contains "reactionCount" prop usage
|
||||
- npx tsc --noEmit exits 0
|
||||
</acceptance_criteria>
|
||||
<done>PostCard renders post content with author and timestamp</done>
|
||||
</task>
|
||||
```
|
||||
|
||||
### `auto` 任务必填字段
|
||||
|
||||
| 字段 | 规则 |
|
||||
|---|---|
|
||||
| `<files>` | 任务创建或修改的所有文件。执行器只写入这些文件。 |
|
||||
| `<read_first>` | 执行器在修改任何内容之前必须读取的文件——包括待修改文件、任何真实来源的模式文件以及必须复用其类型或约定的文件。 |
|
||||
| `<action>` | 包含精确标识符、文件路径、函数签名和预期值的具体指令。不能在未指定目标状态的情况下说"将 X 与 Y 对齐"。不包含代码围栏块或完整实现。 |
|
||||
| `<verify>` | 可运行的命令或检查，用于证明任务已成功完成。必须能区分通过与失败——`echo "done"` 无效。 |
|
||||
| `<acceptance_criteria>` | 可验证的条件：可通过 grep 验证的字符串、命令退出码、可观测行为。不含主观性语言（"看起来正确"、"配置正确"）。 |
|
||||
| `<done>` | 已完成结果的简短可量化陈述。 |
|
||||
|
||||
---
|
||||
|
||||
## 计划质量维度
|
||||
|
||||
`gsd-plan-checker` 代理在执行开始前对每个 PLAN.md 进行 12 个维度的审查。任何未通过 BLOCKER 级别检查的计划将被退回给 `gsd-planner` 修订（最多 3 次迭代）：
|
||||
|
||||
| 维度 | 检查内容 |
|
||||
|---|---|
|
||||
| **1 — 需求覆盖率** | ROADMAP.md 中每个阶段需求 ID 出现在至少一个计划的 `requirements` 前置元数据字段中，并有相应的覆盖任务。 |
|
||||
| **2 — 任务完整性** | 每个 `auto` 任务携带所有必填字段（`<files>`、`<action>`、`<verify>`、`<acceptance_criteria>`、`<done>`）。无模糊或空字段。 |
|
||||
| **3 — 依赖正确性** | `depends_on` 引用有效、无循环，并与波次编号一致。第 N 波次计划仅依赖波次 < N 的计划。 |
|
||||
| **4 — 关键链接规划** | `must_haves.key_links` 中的制品有对应的实现接线任务——而非仅创建制品。 |
|
||||
| **5 — 范围合理性** | 计划保持在上下文预算内：每个计划 2–3 个任务（4 个 = 警告，5 个及以上 = BLOCKER），每个计划 ≤ 8–10 个文件（15 个及以上 = BLOCKER）。 |
|
||||
| **6 — 验证推导** | `must_haves.truths` 是用户可观测行为，而非实现细节。制品映射到真实状态。关键链接覆盖关键接线。 |
|
||||
| **7 — 上下文合规性** | CONTEXT.md 中每个 `D-NN` 决策至少由一个任务处理。没有任务实现 `<deferred>` 中的内容。 |
|
||||
| **7b — 范围缩减检测** | 任务操作不会在未交付完整决策范围的情况下，悄悄将已锁定决策降级为"v1"、"桩代码"或"未来增强"。发现时始终为 BLOCKER。 |
|
||||
| **7c — 架构层级合规性** | 任务按照 RESEARCH.md 架构责任映射（如存在）将能力分配到正确层级。安全敏感能力分配到错误层级时为 BLOCKER。 |
|
||||
| **8 — 奈奎斯特合规性** | 当 `workflow.nyquist_validation` 已启用且 RESEARCH.md 存在时，每个任务有 `<automated>` 验证命令，连续 3 个任务的窗口内不缺少覆盖，且 VALIDATION.md 存在。 |
|
||||
| **9 — 跨计划数据契约** | 当计划共享数据管道时，其转换相互兼容——没有计划删除另一个计划需要原始形式的数据。 |
|
||||
| **10 — CLAUDE.md 合规性** | 计划遵守 `./CLAUDE.md` 中的项目特定约定、禁止模式、必需工具和安全要求。 |
|
||||
| **11 — 研究解决** | 当 RESEARCH.md 存在时，其 `## Open Questions` 部分在规划继续之前标记为 `(RESOLVED)`。 |
|
||||
| **12 — 模式合规性** | 当 PATTERNS.md 存在时，任务为每个新建或修改的文件引用正确的类比模式。 |
|
||||
|
||||
---
|
||||
|
||||
## 波次执行模型
|
||||
|
||||
波次编号在规划阶段预先计算。Execute-phase 按波次编号对计划进行分组，并行运行每个波次的计划：
|
||||
|
||||
```
|
||||
Wave 1: Plan 01, Plan 02, Plan 03 (all run simultaneously — no dependencies)
|
||||
Wave 2: Plan 04 (waits for Wave 1 to complete)
|
||||
Wave 3: Plan 05 (waits for Wave 2 to complete)
|
||||
```
|
||||
|
||||
同一波次中修改重叠文件的计划不得处于同一波次——计划检查器的维度 3 会将此标记为 BLOCKER。
|
||||
|
||||
---
|
||||
|
||||
## 计划输出
|
||||
|
||||
计划成功执行后，执行器在以下路径写入 SUMMARY.md：
|
||||
|
||||
```
|
||||
.planning/phases/<NN>-<slug>/<NN>-<PP>-SUMMARY.md
|
||||
```
|
||||
|
||||
SUMMARY.md 是所构建内容的权威记录。同一阶段内的后续计划，仅当对其类型或决策存在真实依赖时，才可引用该文件。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [CONTEXT.md 模式](context-md.md)
|
||||
- [规划制品](planning-artifacts.md)
|
||||
- [功能特性](../FEATURES.md)
|
||||
- [文档索引](../README.md)
|
||||
225
docs/zh-CN/reference/planning-artifacts.md
Normal file
225
docs/zh-CN/reference/planning-artifacts.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# 规划产物参考
|
||||
|
||||
`.planning/` 目录是 GSD Core 项目的共享记忆。所有工作流都会读取和写入该目录，并留下可审计的决策记录。本页列出每个文件、其用途，以及哪些命令负责生成或消费它。参见[文档索引](../README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
.planning/
|
||||
├── PROJECT.md # 项目标识与核心价值
|
||||
├── ROADMAP.md # 里程碑 + 阶段列表及目标
|
||||
├── REQUIREMENTS.md # 编号化验收标准
|
||||
├── STATE.md # 实时进度跟踪器
|
||||
├── config.json # 工作流与模型配置
|
||||
├── MILESTONES.md # 里程碑归档（可选）
|
||||
├── BACKLOG.md # 延期与未来工作（可选）
|
||||
├── LEARNINGS.md # 跨阶段积累的经验（可选）
|
||||
├── DECISIONS-INDEX.md # 历史决策滚动摘要（可选）
|
||||
├── METHODOLOGY.md # 可复用的解释框架（可选）
|
||||
├── HANDOFF.json # 机器可读的暂停状态（临时文件）
|
||||
├── codebase/ # 代码库映射（可选）
|
||||
│ ├── architecture.md
|
||||
│ ├── stack.md
|
||||
│ └── ...
|
||||
├── intel/ # 可查询的符号索引（可选，intel.enabled）
|
||||
│ └── API-SURFACE.md
|
||||
└── phases/
|
||||
└── <NN>-<slug>/ # 每个阶段一个目录
|
||||
├── <NN>-CONTEXT.md # 实现决策（discuss-phase）
|
||||
├── <NN>-DISCUSSION-LOG.md # 人类可读的讨论审计（discuss-phase）
|
||||
├── <NN>-RESEARCH.md # 技术研究结果（plan-phase）
|
||||
├── <NN>-VALIDATION.md # Nyquist 测试覆盖策略（plan-phase）
|
||||
├── <NN>-PATTERNS.md # 代码库类比映射（plan-phase，可选）
|
||||
├── <NN>-<PP>-PLAN.md # 可执行计划（plan-phase，每个计划一个）
|
||||
├── <NN>-<PP>-SUMMARY.md # 执行记录（execute-phase，每个计划一个）
|
||||
├── <NN>-VERIFICATION.md # 阶段目标验证报告（verify-phase）
|
||||
├── <NN>-UAT.md # 持久化 UAT 会话状态（execute-phase）
|
||||
└── .continue-here.md # 暂停后的恢复说明（pause-work）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 根级产物
|
||||
|
||||
### `PROJECT.md`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 规范的项目标识：项目内容、目标用户、核心价值、需求、约束和关键决策。随项目演进持续更新。 |
|
||||
| **生成者** | `/gsd-new-project`（初始创建）；由 `/gsd-complete-milestone` 在决策验证后更新。 |
|
||||
| **消费者** | 所有规划工作流；`gsd-phase-researcher`、`gsd-planner`（上下文）；`discuss-phase`（历史决策）；`gsd-plan-checker`（项目约束）。 |
|
||||
|
||||
### `ROADMAP.md`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 里程碑与阶段列表，含目标、需求 ID、成功标准以及每个阶段的规范参考。是项目构建内容和顺序的唯一可信来源。 |
|
||||
| **生成者** | `/gsd-new-project`（初始创建）；由 `/gsd-phase --insert` 和 `/gsd-complete-milestone` 更新。 |
|
||||
| **消费者** | `/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase`；所有需要阶段信息的编排命令；`gsd-planner`、`gsd-plan-checker`、`gsd-phase-researcher`。 |
|
||||
|
||||
### `REQUIREMENTS.md`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 编号化、可勾选的项目验收标准。每条需求带有 ID（如 `AUTH-01`），映射到路线图阶段。随着阶段执行，逐步标记需求为已完成。 |
|
||||
| **生成者** | `/gsd-new-project`（初始创建）；需求由 `execute-phase` 标记为已完成。 |
|
||||
| **消费者** | `gsd-planner`（计划必须覆盖所有阶段需求 ID）；`gsd-plan-checker` 维度 1（需求覆盖）；`discuss-phase`（历史需求）。 |
|
||||
|
||||
### `STATE.md`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 实时进度跟踪器——当前阶段与计划、进度指标、积累的决策、会话连续性说明。每次工作流运行时首先读取，每次重要操作后更新。 |
|
||||
| **生成者** | `/gsd-new-project`（初始创建）；由所有阶段工作流、`/gsd-pause-work`、`/gsd-resume-work` 持续更新。 |
|
||||
| **消费者** | 所有编排工作流；`/gsd-progress`；通过 `/gsd-quick` 执行的临时任务；`gsd-planner` 和 `gsd-phase-researcher`（项目决策）。 |
|
||||
|
||||
完整字段参考请参见 [STATE.md 模式](state-md.md)。
|
||||
|
||||
### `config.json`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 工作流配置：模型配置文件、研究与计划检查器开关、Git 分支策略、Nyquist 验证、并行化设置，以及每个代理的模型覆盖。 |
|
||||
| **生成者** | `/gsd-new-project`（初始创建）；`/gsd-settings`（交互式编辑）。 |
|
||||
| **消费者** | 每个工作流和子代理——在初始化时通过 `gsd-tools query config-get` 读取。 |
|
||||
|
||||
完整模式请参见 [CONFIGURATION](../CONFIGURATION.md)。
|
||||
|
||||
### `MILESTONES.md`（可选）
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 已完成里程碑的历史记录。每个里程碑关闭时填充；提供已交付内容及时间的存档快照。 |
|
||||
| **生成者** | `/gsd-complete-milestone`。 |
|
||||
| **消费者** | `/gsd-audit-milestone`；人工审查。 |
|
||||
|
||||
### `DECISIONS-INDEX.md`（可选）
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 先前阶段 CONTEXT.md 文件中捕获的决策的有界滚动摘要。存在时，`discuss-phase` 读取此单一文件，而不是逐一读取最多三个先前的 CONTEXT.md 文件，从而节省上下文预算。 |
|
||||
| **生成者** | 当先前阶段数量超过滚动读取阈值时生成。 |
|
||||
| **消费者** | `discuss-phase`（`load_prior_context` 步骤）。 |
|
||||
|
||||
### `HANDOFF.json`（临时文件）
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 工作中断时写入的机器可读暂停状态。包含恢复点、进行中的上下文以及继续说明。恰好消费一次——在恢复时。 |
|
||||
| **生成者** | `/gsd-pause-work`。 |
|
||||
| **消费者** | `/gsd-resume-work`。 |
|
||||
|
||||
---
|
||||
|
||||
## 每阶段产物
|
||||
|
||||
所有每阶段文件均位于 `.planning/phases/<NN>-<slug>/` 下，其中 `NN` 是补零的阶段编号，`slug` 是用连字符连接的阶段名称。
|
||||
|
||||
### `<NN>-CONTEXT.md`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 规划开始前捕获的实现决策。包含阶段边界（`<domain>`）、带有 `D-NN` 标识符的锁定决策（`<decisions>`）、规范文档参考（`<canonical_refs>`）、现有代码洞察（`<code_context>`）、具体灵感（`<specifics>`）以及推迟的想法（`<deferred>`）。 |
|
||||
| **生成者** | `/gsd-discuss-phase`（交互式讨论或 PRD/ADR 快速路径）。 |
|
||||
| **消费者** | `gsd-phase-researcher`（待调查内容）；`gsd-planner`（锁定决策）；`gsd-plan-checker` 维度 7（上下文合规性）。 |
|
||||
|
||||
完整字段参考请参见 [CONTEXT.md 模式](context-md.md)。
|
||||
|
||||
### `<NN>-DISCUSSION-LOG.md`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | discuss-phase 会话的人类可读审计记录：讨论的领域、提出的选项、所做的选择、推迟的想法以及留给 Claude 自行决定的事项。不被自动化工作流消费。 |
|
||||
| **生成者** | `/gsd-discuss-phase`（`git_commit` 步骤）。 |
|
||||
| **消费者** | 人工审查；回顾总结。 |
|
||||
|
||||
### `<NN>-RESEARCH.md`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 规划前产生的技术研究结果。回答"为了很好地规划此阶段，我需要了解什么？"——涵盖领域分析、模式、风险、架构职责映射以及验证架构部分（由 Nyquist 门控使用）。 |
|
||||
| **生成者** | `/gsd-plan-phase` 通过 `gsd-phase-researcher` 代理。 |
|
||||
| **消费者** | `gsd-planner`（规划输入）；`gsd-plan-checker` 维度 7c（层级合规性）、维度 8（Nyquist）、维度 11（研究解决）；`gsd-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`。 |
|
||||
|
||||
### `<NN>-PATTERNS.md`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 由 `gsd-pattern-mapper` 生成的代码库类比映射。针对本阶段每个待创建或修改的文件，识别最近似的现有类比，对文件的角色和数据流进行分类，并提取具体代码摘录。引导规划者采用一致的模式。 |
|
||||
| **生成者** | `/gsd-plan-phase` 通过 `gsd-pattern-mapper` 代理（可选；如果 `workflow.pattern_mapper: false` 则跳过）。 |
|
||||
| **消费者** | `gsd-planner`（模式指导）；`gsd-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` 进行执行后验证）。 |
|
||||
|
||||
完整字段参考请参见 [PLAN.md 模式](plan-md.md)。
|
||||
|
||||
### `<NN>-<PP>-SUMMARY.md`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 计划完成后写入的执行记录。记录已构建内容、与计划的偏差、对验收标准的自查，以及阶段的依赖关系图。 |
|
||||
| **生成者** | `execute-phase` 执行器代理（在每个计划执行结束时写入）。 |
|
||||
| **消费者** | `/gsd-progress`（阶段状态）；`gsd-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`；人工审查。 |
|
||||
|
||||
### `<NN>-UAT.md`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 持久化的 UAT 会话跟踪。在实时 UAT 会话中记录每个测试用例、预期的可观察行为、结果以及开发者响应。带有 YAML 前置内容（`status`、`phase`、`source`、时间戳）。 |
|
||||
| **生成者** | `/gsd-audit-uat`（交互式 UAT 会话）。 |
|
||||
| **消费者** | `/gsd-audit-uat`（恢复先前的 UAT 会话）。 |
|
||||
|
||||
### `.continue-here.md`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **用途** | 阶段工作暂停时写入的人类可读恢复说明。包含供恢复代理使用的上下文：关键反模式、阻塞问题、必读内容以及恢复的确切命令。 |
|
||||
| **生成者** | `/gsd-pause-work`。 |
|
||||
| **消费者** | 任何在阶段上启动的工作流——`discuss-phase` 和 `plan-phase` 在入口处均检查此文件，并要求代理在继续之前证明其理解了所有 `blocking` 反模式。 |
|
||||
|
||||
---
|
||||
|
||||
## 命名约定
|
||||
|
||||
| 片段 | 格式 | 示例 |
|
||||
|---|---|---|
|
||||
| 阶段目录 | `<NN>-<slug>` | `03-post-feed` |
|
||||
| 阶段级文件 | `<NN>-<ARTIFACT>.md` | `03-CONTEXT.md` |
|
||||
| 计划级文件 | `<NN>-<PP>-<ARTIFACT>.md` | `03-02-PLAN.md` |
|
||||
| `NN` | 补零的阶段编号 | `03` 表示第 3 阶段 |
|
||||
| `PP` | 阶段内补零的计划编号 | `02` 表示第 2 个计划 |
|
||||
|
||||
当 `config.json` 中设置了 `project_code` 时，阶段目录使用项目代码作为前缀：对于项目代码 `CK`、第 3 阶段，目录为 `CK-03-post-feed`。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [STATE.md 模式](state-md.md)
|
||||
- [CONTEXT.md 模式](context-md.md)
|
||||
- [PLAN.md 模式](plan-md.md)
|
||||
- [文档索引](../README.md)
|
||||
201
docs/zh-CN/reference/state-md.md
Normal file
201
docs/zh-CN/reference/state-md.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# STATE.md 架构参考
|
||||
|
||||
`STATE.md` 是 GSD Core 的动态项目记忆文件——一个记录项目当前状态、最近发生的事情以及下一步操作的单一 Markdown 文档。本页面记录其结构。参见[文档索引](../README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
由 GSD Core 管理的每个项目在 `.planning/STATE.md` 处保存一个 `STATE.md`。该文件在每次工作流开始时被读取，并在每次重要操作后被写入。该文件包含：
|
||||
|
||||
- **YAML 前置数据** — 机器可读字段，由状态行钩子（`parseStateMd`）和 `gsd-tools state` 命令使用。
|
||||
- **Markdown 正文** — 人类可读的章节，涵盖当前位置、累积的上下文、会话连续性以及性能指标。
|
||||
|
||||
该文件有意保持较小（目标：不超过 100 行）。它是项目状态的摘要，而非存档。
|
||||
|
||||
---
|
||||
|
||||
## YAML 前置数据
|
||||
|
||||
前置数据出现在文件最开头的 `---` 分隔符之间。除 `gsd_state_version` 和 `status` 外，所有字段均为可选；当相关数据尚不可用时，字段可以缺失。
|
||||
|
||||
### 注释示例
|
||||
|
||||
```yaml
|
||||
---
|
||||
gsd_state_version: '1.0'
|
||||
milestone: v2.0
|
||||
milestone_name: Code Quality
|
||||
status: executing
|
||||
|
||||
# Phase-lifecycle fields — all optional (added in v1.40.0, issue #2833)
|
||||
active_phase: "4.5"
|
||||
next_action: execute-phase
|
||||
next_phases: ["4.5"]
|
||||
|
||||
progress:
|
||||
total_phases: 17
|
||||
completed_phases: 10
|
||||
total_plans: 84
|
||||
completed_plans: 47
|
||||
percent: 59
|
||||
|
||||
# Additional fields written by syncStateFrontmatter
|
||||
current_phase: "4"
|
||||
current_phase_name: Observability
|
||||
current_plan: "3"
|
||||
last_updated: "2026-06-01T12:34:56.789Z"
|
||||
last_activity: "2026-06-01"
|
||||
stopped_at: "Phase 4 P3 execution complete"
|
||||
paused_at: null
|
||||
---
|
||||
```
|
||||
|
||||
### 字段参考
|
||||
|
||||
| 字段 | 类型 | 填充时机 | 用途 |
|
||||
|---|---|---|---|
|
||||
| `gsd_state_version` | 字符串（`'1.0'`） | 始终 | 架构版本；在第一次 `state.*` 调用时由 `syncStateFrontmatter` 写入。 |
|
||||
| `milestone` | 字符串（如 `v2.0`） | 配置了里程碑时 | 当前里程碑版本，从项目配置中读取。 |
|
||||
| `milestone_name` | 字符串 | 配置了里程碑时 | 里程碑的人类可读标签（如 `Code Quality`）。 |
|
||||
| `status` | 字符串 | 始终 | 当前生命周期阶段。由 `normalizeStateStatus()` 规范化——参见[状态值](#状态值)。 |
|
||||
| `active_phase` | 字符串（如 `"4.5"`） | 编排器命令正在处理该阶段时 | 当前正在处理的阶段编号。阶段之间时设为 `null`。 |
|
||||
| `next_action` | 字符串 | 空闲且有推荐命令时 | 下一步要运行的斜线命令：`discuss-phase`、`plan-phase`、`execute-phase` 或 `verify-phase`。当编排器正在运行或无可用推荐时设为 `null`。 |
|
||||
| `next_phases` | YAML 流数组（如 `["4.5"]`） | 与 `next_action` 配合使用 | `next_action` 适用的阶段 ID（通常 1–2 项）。与 `next_action` 相同条件下设为 `null`。 |
|
||||
| `progress.total_phases` | 整数 | 阶段数据可用时 | 当前里程碑中的阶段总数，从 ROADMAP.md 和阶段目录派生。 |
|
||||
| `progress.completed_phases` | 整数 | 阶段数据可用时 | 磁盘上所有计划摘要均已存在的阶段数量（即每个计划均已完成）。 |
|
||||
| `progress.total_plans` | 整数 | 计划文件存在时 | 当前里程碑中所有阶段的计划文件总数。 |
|
||||
| `progress.completed_plans` | 整数 | 摘要文件存在时 | 已完成的计划摘要总数（每个已执行计划一个 SUMMARY.md）。 |
|
||||
| `progress.percent` | 整数 0–100 | 进度数据可用时 | 里程碑在**阶段维度**的进度（`min(completed_plans/total_plans, completed_phases/total_phases)`）。状态行进度条仅在该字段存在时渲染——缺失时进度条不显示。 |
|
||||
| `current_phase` | 字符串 | 阶段正在执行时 | 从正文 `Current Phase:` 字段提取的阶段编号。 |
|
||||
| `current_phase_name` | 字符串 | 阶段有名称时 | 从正文 `Current Phase Name:` 字段提取的阶段名称。 |
|
||||
| `current_plan` | 字符串 | 计划进行中时 | 从正文 `Current Plan:` 字段提取的计划编号。 |
|
||||
| `last_updated` | ISO-8601 时间戳 | 始终（写入时） | 最后一次 `syncStateFrontmatter` 调用的时间戳；由 `realClock.nowIso()` 写入。 |
|
||||
| `last_activity` | 字符串 | 正文中设置时 | 最后活动日期，从正文 `Last Activity:` 字段提取。 |
|
||||
| `stopped_at` | 字符串 | 记录了停止点时 | 最后完成操作的描述；限定在 `## Session` 正文章节内，以避免匹配存档文本。 |
|
||||
| `paused_at` | 字符串 | 项目已暂停时 | 暂停点的自由描述；未暂停时缺失或为 `null`。 |
|
||||
|
||||
### 状态值
|
||||
|
||||
`get-shit-done/bin/lib/state-document.cjs` 中的 `normalizeStateStatus()` 将原始正文文本映射到以下规范值：
|
||||
|
||||
| 规范值 | 匹配文本（不区分大小写） |
|
||||
|---|---|
|
||||
| `discussing` | 包含 `discussing` |
|
||||
| `planning` | 包含 `planning` 或 `ready to plan` |
|
||||
| `executing` | 包含 `executing`、`in progress` 或 `ready to execute` |
|
||||
| `verifying` | 包含 `verif` |
|
||||
| `completed` | 包含 `complete` 或 `done` |
|
||||
| `paused` | 包含 `paused` 或 `stopped`，或 `paused_at` 有值 |
|
||||
| `unknown` | 以上均不符合 |
|
||||
|
||||
当编排器命令正在运行时，惯例（issue #2833）是直接将生命周期阶段写入 `status`：
|
||||
|
||||
| 命令 | 运行期间的 `status` |
|
||||
|---|---|
|
||||
| `/gsd-discuss-phase` | `discussing` |
|
||||
| `/gsd-plan-phase` | `planning` |
|
||||
| `/gsd-execute-phase` | `executing` |
|
||||
| `/gsd-verify-work` | `verifying` |
|
||||
|
||||
---
|
||||
|
||||
## 状态行渲染场景
|
||||
|
||||
`hooks/gsd-statusline.js` 中的 `formatGsdState()` 读取已解析的前置数据并输出**第一个匹配的场景**。如果没有新的生命周期字段适用，渲染将回退到与 v1.38.x 完全一致的原始格式。
|
||||
|
||||
| 场景 | 触发条件 | 显示示例 |
|
||||
|---|---|---|
|
||||
| **1. 阶段活跃** | `active_phase` 已填充 | `v2.0 [██░░░░░░░░] 20% · Phase 4.5 executing` |
|
||||
| **2. 空闲，有下一步推荐** | `active_phase` 为 null 且 `next_action` 和 `next_phases` 均已填充 | `v2.0 [██░░░░░░░░] 20% · next execute-phase 4.5` |
|
||||
| **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/enh-2833-phase-lifecycle-statusline.test.cjs` 中的 `"scene priority"` 测试套件覆盖。
|
||||
|
||||
进度条（`[██░░░░░░░░] 20%`）仅在前置数据中存在 `progress.percent` 时才追加到里程碑段；缺失则不显示进度条。
|
||||
|
||||
---
|
||||
|
||||
## 前置数据解析约束
|
||||
|
||||
状态行钩子使用基于正则表达式的解析（无完整 YAML 库），因此以下约束适用。这些约束在 `tests/enh-2833-phase-lifecycle-statusline.test.cjs` 中经过测试。
|
||||
|
||||
1. **前置数据必须从文件的第一个字符开始。** 任何内容——包括注释——出现在开头 `---` 之前都会使匹配失效。开头的 `---` 行必须恰好如此，不能有尾随空格。
|
||||
|
||||
2. **不支持嵌套块内的注释。** `progress:` 块解析器要求下一行为 `[ \t]+\w+:`。在 `progress:` 和其第一个键之间插入 `# comment` 会破坏匹配，进度条将消失。任何说明文档应放在 `STATE.md` 正文中，而不是放在前置数据块内。
|
||||
|
||||
3. **`next_phases` 首选格式为单行流式。** 解析器首先尝试 `next_phases: ["4.5", "4.6"]`。块序列（`- 4.5\n- 4.6`）也可解析，但对状态行渲染的可靠性较低。优先使用单行流式格式的 `next_phases` 以保持基于正则表达式的解析器的可预测性。如果需要记录大量候选阶段以供文档说明，请将其存储在 `STATE.md` 正文中。
|
||||
|
||||
如果未来的变更将正则表达式解析器替换为完整的 YAML 库，则这些约束可以放宽，并相应更新测试。
|
||||
|
||||
---
|
||||
|
||||
## Markdown 正文章节
|
||||
|
||||
正文（结束 `---` 之后的所有内容）遵循 `get-shit-done/templates/state.md` 中的模板。标准章节为：
|
||||
|
||||
### 项目参考
|
||||
|
||||
指向 `.planning/PROJECT.md`。包含：
|
||||
- **核心价值** — 来自 `PROJECT.md` 核心价值章节的一句话说明。
|
||||
- **当前焦点** — 哪个阶段处于活跃状态。
|
||||
|
||||
### 当前位置
|
||||
|
||||
项目当前所处的状态：
|
||||
|
||||
| 字段 | 格式 |
|
||||
|---|---|
|
||||
| `Phase:` | `X of Y (Phase name)` |
|
||||
| `Plan:` | `A of B in current phase` |
|
||||
| `Status:` | 自由文本，如 `Ready to execute`、`Executing Phase 4`、`Phase complete — ready for verification` |
|
||||
| `Last activity:` | 处理器写入时为 ISO 日期（`YYYY-MM-DD`）；执行器编写时为叙述性文本 |
|
||||
| `Progress:` | 可视化进度条，如 `[████░░░░░░] 40%` |
|
||||
|
||||
当现有值为已知模板默认值时，该章节中的 `Status:` 和 `Last activity:` 字段由 GSD 处理器更新（Knuth 不变式：执行器编写的值被保留）。已知处理器默认值的完整列表位于 `get-shit-done/bin/lib/state-document.cjs` 中的 `KNOWN_TEMPLATE_DEFAULTS`。
|
||||
|
||||
### 性能指标
|
||||
|
||||
执行速度跟踪：
|
||||
- 已完成计划总数，每个计划的平均耗时。
|
||||
- 每阶段明细表（`Phase | Plans | Total | Avg/Plan`）。
|
||||
- 近期趋势：改善中 / 稳定 / 下降中。
|
||||
|
||||
每次计划完成后更新。
|
||||
|
||||
### 累积的上下文
|
||||
|
||||
**决策** — 影响当前工作的近期决策摘要（完整日志在 `PROJECT.md` 中）。通过 `gsd-tools state add-decision` 添加。
|
||||
|
||||
**待处理的待办事项** — 数量及对 `.planning/todos/pending/` 的引用。通过 `/gsd-capture` 捕获。
|
||||
|
||||
**阻碍/关切** — 影响未来工作的问题，以发起阶段为前缀。通过 `gsd-tools state add-blocker` 添加；通过 `gsd-tools state resolve-blocker` 解决。
|
||||
|
||||
### 会话连续性
|
||||
|
||||
实现即时会话恢复：
|
||||
- `Last session:` — 上次会话的 ISO-8601 时间戳。
|
||||
- `Stopped at:` — 最后完成操作的描述。
|
||||
- `Resume file:` — 指向 `.continue-here*.md` 文件的路径（若存在），否则为 `None`。
|
||||
|
||||
---
|
||||
|
||||
## 向后兼容性
|
||||
|
||||
阶段生命周期字段（`active_phase`、`next_action`、`next_phases` 以及用于进度条的 `progress.percent`）是**按项目可选添加**的：
|
||||
|
||||
- 未填充任何生命周期字段的 `STATE.md` 渲染结果与 v1.38.x 及更早版本**逐字节完全相同**。
|
||||
- 添加任何生命周期字段是可选的——当字段缺失时，渲染器会优雅降级。
|
||||
- 即使 `progress` 块存在，进度条也是可选的：只有 `progress.percent` 触发进度条；单独的 `total_phases` 和 `completed_phases` 不会触发。
|
||||
|
||||
`tests/enh-2833-phase-lifecycle-statusline.test.cjs` 中的 `formatGsdState #2833 backward compatibility` 测试套件锁定了此保证；任何破坏旧版 `STATE.md` 渲染的变更都将导致该套件失败。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [规划产物](planning-artifacts.md)
|
||||
- [配置](../CONFIGURATION.md)
|
||||
- [阶段循环](../explanation/the-phase-loop.md)
|
||||
- [文档索引](../README.md)
|
||||
226
docs/zh-CN/tutorials/onboarding-an-existing-codebase.md
Normal file
226
docs/zh-CN/tutorials/onboarding-an-existing-codebase.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# 将现有代码库纳入工作流
|
||||
|
||||
在本教程中，您将把 GSD Core 引入一个已有代码的仓库。您将对代码库进行映射，创建一个描述您所*新增*内容的项目，并针对一个小型聚焦变更运行首次讨论与规划循环。完成后，GSD Core 的规划流水线将了解您的技术栈、规范和关注点——并在每次规划时运用这些知识。
|
||||
|
||||
---
|
||||
|
||||
## 您将构建的内容
|
||||
|
||||
我们将向一个现有的 Express 应用程序添加一个 `GET /health` 端点。该变更足够小，不会分散您对真正核心内容的注意力：GSD Core 在规划任何内容之前如何学习您的代码库。
|
||||
|
||||
---
|
||||
|
||||
## 前提条件
|
||||
|
||||
- **Node.js 18 或更高版本** — `node --version` 应输出 `v18.x.x` 或更高版本。
|
||||
- **一个现有项目** — 任何已有代码的仓库。不必须是 Express；这些步骤适用于任何技术栈。
|
||||
- **Claude Code** — 在您的仓库根目录中打开。
|
||||
|
||||
---
|
||||
|
||||
## 第 1 步 — 安装 GSD Core
|
||||
|
||||
在您的仓库根目录执行：
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest
|
||||
```
|
||||
|
||||
在提示时选择 **Claude Code** 和 **local**。您将看到：
|
||||
|
||||
```text
|
||||
✓ Installed 86 skills to .claude/commands/
|
||||
✓ Installed agents to .claude/agents/
|
||||
✓ GSD Core ready — run /gsd-new-project to start
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第 2 步 — 使用权限启动 Claude Code
|
||||
|
||||
```bash
|
||||
claude --dangerously-skip-permissions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第 3 步 — 映射代码库
|
||||
|
||||
在创建项目之前，先让 GSD Core 了解已有的内容。这是使棕地规划准确的关键步骤。
|
||||
|
||||
```text
|
||||
/gsd-map-codebase
|
||||
```
|
||||
|
||||
GSD Core 会派生四个并行映射子代理（您将看到"Spawning 4 parallel codebase mapper agents…"——这需要 1–5 分钟；请勿中断）。每个代理专注于不同的关注点：
|
||||
|
||||
| 代理 | 关注点 |
|
||||
|-------|-------|
|
||||
| 技术映射器 | 技术栈、框架、依赖项 |
|
||||
| 架构映射器 | 模式、层次、数据流 |
|
||||
| 质量映射器 | 规范、测试实践 |
|
||||
| 关注点映射器 | 技术债务、风险领域 |
|
||||
|
||||
当所有四个代理返回后，您将看到：
|
||||
|
||||
```text
|
||||
Codebase mapping complete.
|
||||
|
||||
Created .planning/codebase/:
|
||||
- STACK.md (47 lines) - Technologies and dependencies
|
||||
- ARCHITECTURE.md (62 lines) - System design and patterns
|
||||
- STRUCTURE.md (38 lines) - Directory layout and organisation
|
||||
- CONVENTIONS.md (55 lines) - Code style and patterns
|
||||
- TESTING.md (41 lines) - Test structure and practices
|
||||
- INTEGRATIONS.md (29 lines) - External services and APIs
|
||||
- CONCERNS.md (33 lines) - Technical debt and issues
|
||||
```
|
||||
|
||||
打开 `.planning/codebase/STACK.md`。您将看到 GSD Core 检测到的语言、运行时、框架版本和关键依赖项——这些内容基于实际读取的文件，而非猜测。
|
||||
|
||||
打开 `.planning/codebase/CONVENTIONS.md`。您将看到它从您的源代码中观察到的命名规范、错误处理模式和代码风格规则。GSD Core 为该仓库生成的每个计划都将自动遵循这些规范。
|
||||
|
||||
打开 `.planning/codebase/CONCERNS.md`。在进行任何新功能开发之前，这是最值得阅读的文件——它会展现可能影响您计划的技术债务和脆弱区域。
|
||||
|
||||
---
|
||||
|
||||
## 第 4 步 — 清除上下文并创建项目
|
||||
|
||||
清除会话窗口：
|
||||
|
||||
```text
|
||||
/clear
|
||||
```
|
||||
|
||||
现在创建项目。由于 GSD Core 在上一步中发现了现有代码，它已经知道这是一个棕地项目。当您运行 `/gsd-new-project` 时，问题将聚焦于您所*新增*的内容，而非重新描述已有的内容：
|
||||
|
||||
```text
|
||||
/gsd-new-project
|
||||
```
|
||||
|
||||
GSD Core 会询问您想构建什么。请用您正在添加的功能来回答，而不是描述整个代码库：
|
||||
|
||||
```text
|
||||
Add a GET /health endpoint to the Express app. It should return
|
||||
{ "status": "ok", "uptime": <seconds> }. We'll use it for load-balancer
|
||||
health checks.
|
||||
```
|
||||
|
||||
GSD Core 会进一步提出少量澄清问题，然后继续创建需求和路线图。由于它已读取 `ARCHITECTURE.md` 和 `STACK.md`，它会自动将现有能力映射到 `PROJECT.md` 的 **Validated** 部分——您无需描述现有的 API 接口。
|
||||
|
||||
对所有工作流设置选择推荐默认值。
|
||||
|
||||
当路线图子代理返回后，您将看到一个建议的路线图。对于单个小型变更，它将只有一个阶段：
|
||||
|
||||
```text
|
||||
Proposed Roadmap
|
||||
|
||||
1 phase | 2 requirements mapped | All v1 requirements covered ✓
|
||||
|
||||
| # | Phase | Goal | Requirements |
|
||||
|---|----------------|-----------------------------------------------|--------------|
|
||||
| 1 | Health endpoint| GET /health returning status and uptime JSON | HLT-01, HLT-02 |
|
||||
```
|
||||
|
||||
批准路线图。
|
||||
|
||||
**在 `.planning/` 中创建的内容：**
|
||||
|
||||
```text
|
||||
.planning/
|
||||
PROJECT.md ← project description; existing capabilities in "Validated"
|
||||
REQUIREMENTS.md ← HLT-01, HLT-02
|
||||
ROADMAP.md ← Phase 1, status: pending
|
||||
STATE.md ← session memory
|
||||
config.json ← workflow settings
|
||||
codebase/ ← the seven map files from Step 3
|
||||
```
|
||||
|
||||
注意 `.planning/codebase/` 已经从第 3 步存在。GSD Core 在编写 `PROJECT.md` 时读取了这些文件，这就是为什么它无需您描述即可填充已验证的需求。
|
||||
|
||||
---
|
||||
|
||||
## 第 5 步 — 清除上下文并讨论第 1 阶段
|
||||
|
||||
```text
|
||||
/clear
|
||||
```
|
||||
|
||||
```text
|
||||
/gsd-discuss-phase 1
|
||||
```
|
||||
|
||||
由于 GSD Core 已读取您的 `CONVENTIONS.md` 和 `ARCHITECTURE.md`，其问题基于您的实际代码库——而非通用建议。您可能会看到：
|
||||
|
||||
```text
|
||||
> Your routes are registered in src/routes/index.js. Should the health
|
||||
endpoint live there, or in a dedicated src/routes/health.js?
|
||||
A dedicated health.js — keep routes separated.
|
||||
|
||||
> Your existing error middleware returns { error: "message" }. Should
|
||||
/health use the same shape for error responses?
|
||||
Yes, stay consistent.
|
||||
|
||||
> Should uptime be calculated from process.uptime() or a stored start time?
|
||||
process.uptime() is fine.
|
||||
```
|
||||
|
||||
讨论结束后，GSD Core 将写入：
|
||||
|
||||
```text
|
||||
.planning/phases/01-health-endpoint/CONTEXT.md
|
||||
```
|
||||
|
||||
打开该文件。`## Implementation Decisions` 部分记录了您的回答。规划器将在编写任何任务之前读取此文件——因此您关于文件位置和响应格式的偏好将出现在计划中，而不仅仅停留在讨论里。
|
||||
|
||||
---
|
||||
|
||||
## 第 6 步 — 规划第 1 阶段
|
||||
|
||||
```text
|
||||
/gsd-plan-phase 1
|
||||
```
|
||||
|
||||
四个研究子代理并行运行（1–5 分钟）。当它们返回后，规划器读取 `CONTEXT.md`、研究结果和您的代码库映射，创建符合您规范的任务计划。
|
||||
|
||||
**创建的内容：**
|
||||
|
||||
```text
|
||||
.planning/phases/01-health-endpoint/
|
||||
RESEARCH.md ← findings on health endpoint patterns
|
||||
01-01-PLAN.md ← Task: create src/routes/health.js
|
||||
01-02-PLAN.md ← Task: register health route in src/routes/index.js
|
||||
```
|
||||
|
||||
打开 `01-01-PLAN.md`。注意 `<files>` 标签引用了 `src/routes/health.js`——正是您在讨论中指定的路径，与 GSD Core 在代码库映射中观察到的路由模式一致。这正是代码库映射发挥作用的体现。
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
您现在拥有一个带有代码库映射、讨论决策记录和经过验证的任务计划的项目——所有内容均基于您的实际代码。从这里开始，工作流与绿地项目完全相同：
|
||||
|
||||
```text
|
||||
/gsd-execute-phase 1
|
||||
/gsd-verify-work 1
|
||||
/gsd-ship 1
|
||||
```
|
||||
|
||||
对于每个未来的功能，当结构发生重大变化时，再次运行 `/gsd-map-codebase`，以保持代码库映射的时效性。
|
||||
|
||||
---
|
||||
|
||||
## 您学到了什么
|
||||
|
||||
- `/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` 中的每个问题——文件路径、模式和规范均来自您的实际代码。
|
||||
- 规划器如何读取 `CONTEXT.md` 和 `CONVENTIONS.md` 来生成符合您仓库风格的计划。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [您的第一个项目](your-first-project.md) — 从安装到 PR 的完整绿地循环
|
||||
- [通过命令使用映射代码库](../COMMANDS.md) — 所有 `/gsd-map-codebase` 标志和子命令
|
||||
- [文档索引](../README.md)
|
||||
291
docs/zh-CN/tutorials/your-first-project.md
Normal file
291
docs/zh-CN/tutorials/your-first-project.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# 你的第一个项目
|
||||
|
||||
在本教程中，你将安装 GSD Core 并从头构建一个小型命令行待办事项应用——一个阶段、一个 PR、完整的流程循环。完成后，你将至少运行过核心阶段循环中的每一条命令一次，并看到每条命令所生成的规划产物。
|
||||
|
||||
---
|
||||
|
||||
## 你将构建什么
|
||||
|
||||
一个 Node.js CLI 工具，支持添加、列出和完成存储在本地 JSON 文件中的待办事项。它足够小，可以在一次会话中完成，且仅使用 Node.js 标准库，无需安装任何额外依赖。
|
||||
|
||||
---
|
||||
|
||||
## 前提条件
|
||||
|
||||
- **Node.js 18 或更高版本** — `node --version` 应打印 `v18.x.x` 或更高版本。
|
||||
- **Claude Code** — 在你想使用的项目目录中打开。
|
||||
- 初次安装需要网络连接。
|
||||
|
||||
不需要其他工具。GSD Core 本身将在下一步安装。
|
||||
|
||||
---
|
||||
|
||||
## 第 1 步 — 安装 GSD Core
|
||||
|
||||
在项目目录中打开终端并运行：
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest
|
||||
```
|
||||
|
||||
安装程序会询问你使用的 AI 编程运行时，以及是全局安装还是安装到当前项目。现在选择 **Claude Code** 和**本地安装**（仅此项目）。
|
||||
|
||||
你将看到类似如下的输出：
|
||||
|
||||
```text
|
||||
✓ Installed 86 skills to .claude/commands/
|
||||
✓ Installed agents to .claude/agents/
|
||||
✓ GSD Core ready — run /gsd-new-project to start
|
||||
```
|
||||
|
||||
注意项目中现在存在一个 `.claude/` 目录。这是 GSD Core 的命令和代理所在的位置。
|
||||
|
||||
> 为什么选本地而不是全局？本地安装可将技能版本固定到该项目。如需全局安装，请参阅 [在你的运行时上安装](../how-to/install-on-your-runtime.md)。
|
||||
|
||||
---
|
||||
|
||||
## 第 2 步 — 以权限模式启动 Claude Code
|
||||
|
||||
GSD Core 会生成读写文件的子代理。以权限标志启动 Claude Code，这样它就不会在每次文件操作时暂停询问：
|
||||
|
||||
```bash
|
||||
claude --dangerously-skip-permissions
|
||||
```
|
||||
|
||||
你将进入项目目录中的 Claude Code 提示符。
|
||||
|
||||
---
|
||||
|
||||
## 第 3 步 — 创建项目
|
||||
|
||||
在 Claude Code 提示符处输入以下斜杠命令：
|
||||
|
||||
```text
|
||||
/gsd-new-project
|
||||
```
|
||||
|
||||
GSD Core 将开启一段对话。它首先提问：
|
||||
|
||||
```text
|
||||
What do you want to build?
|
||||
```
|
||||
|
||||
输入类似以下内容：
|
||||
|
||||
```text
|
||||
A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`,
|
||||
`todo list`, and `todo done 1`. Items are saved to a local todos.json file.
|
||||
No external dependencies — Node built-ins only.
|
||||
```
|
||||
|
||||
GSD Core 会继续提出几个澄清性问题。自然地回答即可。它在撰写任何计划之前，正在了解你的关注点。
|
||||
|
||||
问题结束后，它会提议进行领域调研。对于如此小的项目，你可以跳过调研——在提示时选择**跳过调研**。
|
||||
|
||||
GSD Core 随后会要求你选择工作流设置（模式、粒度、调研代理）。每项均选择推荐的默认值。这些设置将写入 `.planning/config.json`。
|
||||
|
||||
最后，一个路线图子代理开始运行（你会看到"Spawning roadmapper…"的提示——这是正常的，大约需要一分钟）。返回后，GSD Core 会展示一份路线图提案。对于单阶段项目，它看起来类似：
|
||||
|
||||
```text
|
||||
Proposed Roadmap
|
||||
|
||||
1 phase | 4 requirements mapped | All v1 requirements covered ✓
|
||||
|
||||
| # | Phase | Goal | Requirements |
|
||||
|---|--------------------|-----------------------------------------|-------------------|
|
||||
| 1 | Core CLI | add / list / done commands, todos.json | CLI-01 … CLI-04 |
|
||||
```
|
||||
|
||||
输入 **Approve** 以接受路线图。
|
||||
|
||||
**`.planning/` 中创建的内容：**
|
||||
|
||||
```text
|
||||
.planning/
|
||||
PROJECT.md ← 你的项目描述和需求
|
||||
REQUIREMENTS.md ← 每个 v1 功能的 REQ-ID
|
||||
ROADMAP.md ← 第 1 阶段，状态：待处理
|
||||
STATE.md ← 会话记忆，当前位置
|
||||
config.json ← 工作流设置
|
||||
```
|
||||
|
||||
现在打开 `.planning/ROADMAP.md` 并阅读。注意第 1 阶段有目标、必须满足的需求列表和成功标准——这些是执行必须交付的可观测行为。
|
||||
|
||||
---
|
||||
|
||||
## 第 4 步 — 清除上下文并讨论第 1 阶段
|
||||
|
||||
GSD Core 的设计围绕全新的上下文。在每个阶段之前清除主会话窗口：
|
||||
|
||||
```text
|
||||
/clear
|
||||
```
|
||||
|
||||
然后开始第 1 阶段的讨论：
|
||||
|
||||
```text
|
||||
/gsd-discuss-phase 1
|
||||
```
|
||||
|
||||
GSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响*如何*构建，而不仅仅是*构建什么*。示例交流：
|
||||
|
||||
```text
|
||||
> How should done items be stored — mark them in place or move them?
|
||||
Mark them in place with a "done" flag.
|
||||
|
||||
> Should `todo list` show completed items by default?
|
||||
No, hide them unless --all is passed.
|
||||
|
||||
> Error format when todos.json doesn't exist yet?
|
||||
Create it silently on first add.
|
||||
```
|
||||
|
||||
讨论结束后，GSD Core 会写入：
|
||||
|
||||
```text
|
||||
.planning/phases/01-core-cli/CONTEXT.md
|
||||
```
|
||||
|
||||
打开该文件。你会看到一个 `## Implementation Decisions` 章节，准确记录了你所说的内容。规划器读取该文件——因此你在此处做出的决定将贯穿到每个任务计划中。
|
||||
|
||||
---
|
||||
|
||||
## 第 5 步 — 规划第 1 阶段
|
||||
|
||||
```text
|
||||
/gsd-plan-phase 1
|
||||
```
|
||||
|
||||
四个调研子代理并行展开工作（你会看到"Spawning 4 researchers…"的提示）。这需要 1–5 分钟，请勿中断。
|
||||
|
||||
返回后，规划器读取 CONTEXT.md 和调研结果，创建原子任务计划。然后，计划检查器在保存之前验证每个计划是否实现了阶段目标。
|
||||
|
||||
**创建的内容：**
|
||||
|
||||
```text
|
||||
.planning/phases/01-core-cli/
|
||||
RESEARCH.md ← 领域调研结果
|
||||
01-01-PLAN.md ← 任务：创建 todos.json 读写助手
|
||||
01-02-PLAN.md ← 任务：实现 add / list / done 命令
|
||||
```
|
||||
|
||||
打开 `01-01-PLAN.md`。你会看到一个 `<task>` 块，包含名称、涉及的文件、操作步骤、验证命令和完成条件。注意 `<verify>` 标签——GSD Core 的执行器将在写入代码后运行该命令。
|
||||
|
||||
---
|
||||
|
||||
## 第 6 步 — 执行第 1 阶段
|
||||
|
||||
```text
|
||||
/gsd-execute-phase 1
|
||||
```
|
||||
|
||||
GSD Core 将计划分组为波次（独立计划并行运行），为每个计划生成一个全新的 200k 上下文执行器，并原子性地提交每个任务。
|
||||
|
||||
你将看到类似如下内容：
|
||||
|
||||
```text
|
||||
Wave 1 (parallel):
|
||||
[Executor A] → 01-01-PLAN.md (read/write helpers) ✓ committed
|
||||
[Executor B] → 01-02-PLAN.md (CLI commands) ✓ committed
|
||||
|
||||
[Verifier] Checking codebase against phase goals...
|
||||
CLI-01 todo add ✓
|
||||
CLI-02 todo list ✓
|
||||
CLI-03 todo done ✓
|
||||
CLI-04 --all flag ✓
|
||||
Status: PASS
|
||||
```
|
||||
|
||||
**创建的内容：**
|
||||
|
||||
```text
|
||||
.planning/phases/01-core-cli/
|
||||
01-01-SUMMARY.md ← 执行器 A 构建并提交的内容
|
||||
01-02-SUMMARY.md ← 执行器 B 构建并提交的内容
|
||||
VERIFICATION.md ← REQ 覆盖情况：PASS
|
||||
```
|
||||
|
||||
现在运行你的 CLI：
|
||||
|
||||
```bash
|
||||
node todo.js add "buy milk"
|
||||
node todo.js add "write tests"
|
||||
node todo.js list
|
||||
node todo.js done 1
|
||||
node todo.js list
|
||||
```
|
||||
|
||||
你应该看到条目出现，并且在标记完成后，条目 1 从默认列表中消失。这是 GSD Core 交付的你的第一个可见结果。
|
||||
|
||||
---
|
||||
|
||||
## 第 7 步 — 验证工作
|
||||
|
||||
```text
|
||||
/gsd-verify-work 1
|
||||
```
|
||||
|
||||
GSD Core 提取阶段的成功标准并逐一引导你完成：
|
||||
|
||||
```text
|
||||
[1/3] Can you run `node todo.js add "buy milk"` without errors?
|
||||
> yes
|
||||
|
||||
[2/3] Does `node todo.js list` show only incomplete items by default?
|
||||
> yes
|
||||
|
||||
[3/3] Does `node todo.js done 1` mark item 1 complete and hide it from the default list?
|
||||
> yes
|
||||
|
||||
All 3 checks passed. Phase 1 verified.
|
||||
```
|
||||
|
||||
如果任何检查失败，GSD Core 会诊断根本原因并创建修复计划。再次运行 `/gsd-execute-phase 1` 应用修复，然后重新运行 `/gsd-verify-work 1`。
|
||||
|
||||
**创建的内容：**
|
||||
|
||||
```text
|
||||
.planning/phases/01-core-cli/UAT.md ← 所有检查及其结果
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第 8 步 — 发布
|
||||
|
||||
```text
|
||||
/gsd-ship 1
|
||||
```
|
||||
|
||||
GSD Core 使用自动生成的正文创建拉取请求。PR 正文始终包含：摘要、变更内容、已解决的需求、验证情况和关键决策。
|
||||
|
||||
你将看到：
|
||||
|
||||
```text
|
||||
Pull request created: https://github.com/your-org/your-repo/pull/1
|
||||
|
||||
Title: feat(phase-1): core CLI — add / list / done commands
|
||||
```
|
||||
|
||||
这就是完整的流程——从想法到合并 PR——一个阶段。
|
||||
|
||||
---
|
||||
|
||||
## 你学到了什么
|
||||
|
||||
- 如何使用 `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` 如何将已验证的阶段转化为拉取请求。
|
||||
|
||||
对于多阶段项目，对每个阶段重复第 4–8 步，然后运行 `/gsd-progress --next`，让 GSD Core 自动检测下一步。
|
||||
|
||||
---
|
||||
|
||||
## 相关资源
|
||||
|
||||
- [阶段循环](../explanation/the-phase-loop.md) — 循环为何如此设计
|
||||
- [操作指南](../README.md#how-to-guides) — 针对特定情况的任务型操作说明
|
||||
- [接入现有代码库](onboarding-an-existing-codebase.md) — 将 GSD Core 引入棕地仓库
|
||||
75
docs/zh-CN/workflow-discuss-mode.md
Normal file
75
docs/zh-CN/workflow-discuss-mode.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# 讨论模式：假设模式与访谈模式
|
||||
|
||||
GSD Core 的讨论阶段提供两种模式，用于在规划开始前收集实现上下文。了解何时使用哪种模式，有助于减少来回沟通，更快地生成确认后的 `CONTEXT.md`。
|
||||
|
||||
有关运行任一模式的分步说明，请参阅[讨论阶段使用指南](how-to/discuss-a-phase.md)。
|
||||
|
||||
## 模式
|
||||
|
||||
### `discuss`（默认）
|
||||
|
||||
原始访谈式流程。Claude 识别阶段中的模糊区域，呈现供选择，然后针对每个区域提出大约四个问题。适用于：
|
||||
|
||||
- 代码库较新的早期阶段
|
||||
- 用户有强烈意见希望主动表达的阶段
|
||||
- 偏好有引导的对话式上下文收集的用户
|
||||
|
||||
### `assumptions`
|
||||
|
||||
以代码库为中心的流程。Claude 通过子代理深度分析代码库（读取 5–15 个相关文件），形成带有证据的假设，并呈现供确认或纠正。适用于：
|
||||
|
||||
- 具有清晰规范的成熟代码库
|
||||
- 觉得访谈问题显而易见的用户
|
||||
- 更快的上下文收集（约 2–4 次交互，而非约 15–20 次）
|
||||
|
||||
## 配置
|
||||
|
||||
```bash
|
||||
# 启用假设模式
|
||||
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
|
||||
|
||||
# 切换回访谈模式
|
||||
node gsd-tools.cjs config-set workflow.discuss_mode discuss
|
||||
```
|
||||
|
||||
该设置为每个项目独立存储（保存于 `.planning/config.json`）。有关两种模式所生成文件的完整结构，请参阅 [CONTEXT.md 结构说明](reference/context-md.md)。
|
||||
|
||||
## 假设模式的工作原理
|
||||
|
||||
1. **初始化** — 与讨论模式相同（加载先前上下文、探查代码库、检查待办事项）
|
||||
2. **深度分析** — 探索子代理读取与阶段相关的 5–15 个代码库文件
|
||||
3. **呈现假设** — 每条假设包含：
|
||||
- Claude 将做什么以及原因（引用文件路径）
|
||||
- 若假设不正确会出现什么问题
|
||||
- 置信度（确信 / 可能 / 不明确）
|
||||
4. **确认或纠正** — 用户审查假设，选择需要修改的条目
|
||||
5. **写入 CONTEXT.md** — 与讨论模式输出格式完全相同
|
||||
|
||||
## 标志兼容性
|
||||
|
||||
| 标志 | `discuss` 模式 | `assumptions` 模式 |
|
||||
|------|----------------|-------------------|
|
||||
| `--auto` | 自动选择推荐答案 | 跳过确认步骤，自动解决"不明确"项 |
|
||||
| `--batch` | 将问题分批分组 | 不适用（纠正已批量处理） |
|
||||
| `--text` | 纯文本问题（远程会话） | 纯文本问题（远程会话） |
|
||||
| `--analyze` | 每个问题显示权衡表 | 不适用（假设已包含证据） |
|
||||
|
||||
## 输出
|
||||
|
||||
两种模式均生成包含相同六个章节的 `CONTEXT.md`：
|
||||
|
||||
- `<domain>` — 阶段边界
|
||||
- `<decisions>` — 已锁定的实现决策
|
||||
- `<canonical_refs>` — 下游代理必须阅读的规范/文档
|
||||
- `<code_context>` — 可复用资产、规范、集成点
|
||||
- `<specifics>` — 用户参考和偏好
|
||||
- `<deferred>` — 记录供未来阶段使用的想法
|
||||
|
||||
下游代理（researcher、planner、checker）以相同方式使用此文件，无论由哪种模式生成。有关完整字段参考，请参阅 [CONTEXT.md 结构说明](reference/context-md.md)。
|
||||
|
||||
## 相关资源
|
||||
|
||||
- [讨论阶段](how-to/discuss-a-phase.md) — 运行 `/gsd-discuss-phase` 的分步指南（支持两种模式）。
|
||||
- [CONTEXT.md 结构说明](reference/context-md.md) — 两种模式所生成文件的完整字段参考。
|
||||
- [阶段循环](explanation/the-phase-loop.md) — 讨论如何融入更广泛的 讨论 → 规划 → 执行 → 验证 → 发布 循环。
|
||||
- [文档索引](README.md) — GSD Core 文档的完整目录。
|
||||
Reference in New Issue
Block a user