---
url: /wave-agent/specs/commands/builtin-sdd-plugin.md
description: 规格优先工作流插件：`specify` 技能、会话引导、spec-count 校验、阶段单选衔接与执行方式选择
---

# 功能规格说明：内置 SDD 插件

**创建日期**：2026-08-03

## 用户场景与测试 *（必填）*

### 用户故事：按需启用内置插件（优先级：P1）

作为用户，我希望内置插件默认不生效、仅在需要时通过配置启用，以便不想要的插件不会干扰我的会话，同时新能力可以随 SDK 一起分发而无需额外安装。

**为什么是这个优先级**：这是内置插件机制的基础——默认关闭避免行为意外变化，配置启用提供可控性。

**独立测试**：可以通过在项目设置中切换 SDD 开关，验证变更落盘后不重建任何会话、只出现一次「插件已变更」提示（桌面端为确认框），点「立即重新加载」或敲 `/reload-plugins` 后插件能力在同一会话内立即生效（不打断正在生成的回合）来进行完整测试。

**验收场景**：

1. **假设** `enabledPlugins` 中没有 `sdd@builtin` 条目，**当**我启动会话时，**则** SDD 插件的技能、会话引导与校验命令均不可用。
2. **假设** 我在 `enabledPlugins` 中设置 `"sdd@builtin": true`，**当**我切换开关后，**则** 变更落盘只产生一个「待应用」信号并出现一次提示，敲 `/reload-plugins` 后 SDD 插件的技能与引导在**同一会话内**立即生效——不销毁、不重建 Agent（会话 id 不变、消息与转录连续、不打断正在生成的回合），用户无需新开对话；完整语义与逐字文案见 [plugin.md](../ecosystem/plugin.md)「插件变更的就地重载」。
3. **假设** 设置页「项目设置」视图已打开，**当**我切换 SDD 开关时，**则** 写入项目 `.wave/settings.json` 的 `enabledPlugins` 并按场景 2 的语义生效（开关状态与配置文件保持同步，切换结果自动刷新）。

***

### 用户故事：用自然语言创建或更新规格说明（优先级：P1）

作为开发者，我希望在对话中直接描述需求，由 AI 自动生成包含用户故事与验收场景的功能规格说明，以便在编码前明确功能设计并获得确认，无需手动调用任何命令。

**为什么是这个优先级**：这是 SDD 插件的核心能力，直接支撑"规格优先"工作流。

**独立测试**：可以通过在会话中描述一个功能需求，验证 AI 生成包含用户故事与验收场景的规格文件来进行完整测试。

**验收场景**：

1. **假设** 项目存在 `docs/specs/` 目录且 SDD 插件已启用，**当** 我在对话中描述一个功能需求时，**则** AI 生成规格文件到 `docs/specs/` 下已有分组约定的位置，且包含用户故事（`### 用户故事：`）与验收场景（`N. **假设** … **当** … **则** …`）。
2. **假设** 项目只有 `specs/` 目录且没有 `docs/specs/`，**当** AI 触发规格编写时，**则** 规格文件写入 `specs/` 目录。
3. **假设** 项目两个目录都不存在，**当** AI 触发规格编写时，**则** 默认使用 `specs/`，并在完成报告中说明所选目录，便于用户纠正。
4. **假设** 规格中有不明确的关键决策，**当** AI 编写规格时，**则** 规格中以「待澄清」标记（最多 3 处）呈现问题，等待用户回复后更新文件。
5. **假设** SDD 插件已启用，**当** 我打开斜杠命令列表时，**则** 规格编写技能不出现在命令列表中（技能由 AI 自动触发，不占用手动命令）。

***

### 用户故事：会话开始时获得规格优先工作流引导（优先级：P2）

作为开发者，我希望每次会话开始时自动收到"先写规格、再写代码"的简短引导，以便在新会话中不会忘记规格优先流程，也无需手动查找文档。该引导仅注入 AI 上下文（对用户不可见），不占用聊天界面。

**为什么是这个优先级**：引导提升流程一致性，但即使缺失也不阻塞核心对话，故为 P2。

**独立测试**：可以通过启用插件后启动新会话，验证引导文本出现在会话上下文中（如请求一次规划类任务时行为符合引导）来进行测试。

**验收场景**：

1. **假设** 已启用 SDD 插件，**当** 我启动新会话时，**则** 会话上下文中包含规格优先工作流的指引，说明需求变更时应先更新规格说明。
2. **假设** 已启用 SDD 插件，**当** 我启动新会话时，**则** 指引中给出 `spec-count` 校验命令的可用调用方式，供 agent 在修改规格后执行。
3. **假设** 已启用 SDD 插件，**当** 我启动新会话时，**则** 该引导只对 AI 可见、不出现在聊天界面中，用户无感知。

***

### 用户故事：校验规格完整性（优先级：P2）

作为开发者，我希望有一个命令统计规格目录下的用户故事与验收场景数量，并警告缺少必要章节的文件，以便在提交前快速发现规格不完整的问题。

**为什么是这个优先级**：校验保障规格质量与可度量性，属于工作流的重要辅助，故为 P2。

**独立测试**：可以通过在规格目录下运行校验命令，验证输出包含各文件的故事/场景计数，并可故意删掉某文件章节观察警告来进行完整测试。

**验收场景**：

1. **假设** 项目存在 `docs/specs/` 目录，**当** 我运行规格校验命令时，**则** 输出每个规格文件的用户故事与验收场景计数，以及汇总统计。
2. **假设** 某规格文件缺少 `## 用户场景与测试` 章节或没有验收场景，**当** 我运行校验命令时，**则** 输出针对该文件的警告。
3. **假设** 项目既没有 `docs/specs/` 也没有 `specs/` 目录，**当** 我运行校验命令时，**则** 提示未找到规格目录并跳过校验（不报错退出）。

***

### 用户故事：校验脚本自动放行（优先级：P2）

作为开发者，我希望启用 SDD 插件后，规格校验脚本在默认权限模式下运行时不触发权限确认，以便只读的校验命令不打断规格优先工作流，也无需在设置中手写随安装路径变化的精确规则。SDK 加载内置插件时自动注册实例级允许规则（通配符形式 `Bash(node *spec-count.js*)`，锚定脚本文件名、兼容不同安装路径与引号写法），只放行 spec-count，不影响插件其他脚本。

**为什么是这个优先级**：这是"校验规格完整性"故事的使用体验补全——脚本只读、随 SDK 分发且绝对路径动态，手写规则脆弱；与校验能力的 P2 定位一致。

**独立测试**：可以通过启用 SDD 插件后运行校验命令，验证默认权限模式下不出现权限确认、插件内其他脚本仍按正常权限流程处理、且设置文件中未新增持久化规则来进行完整测试。

**验收场景**：

1. **假设** 已启用 `sdd@builtin` 且处于默认权限模式，**当** agent 运行 `node "<SDK 安装路径>/scripts/spec-count.js"`（带引号的绝对路径）时，**则** 命令直接执行，不触发权限确认。
2. **假设** 已启用 `sdd@builtin`，**当** agent 以不带引号的绝对路径运行同一脚本时，**则** 同样直接执行（通配符规则兼容引号写法差异）。
3. **假设** 已启用 `sdd@builtin`，**当** agent 运行 SDD 插件内其他脚本（如 `node ".../scripts/other.js"`）时，**则** 无自动放行，仍按正常权限流程处理。
4. **假设** 未启用 `sdd@builtin`，**当** agent 运行校验脚本时，**则** 无自动放行，仍按正常权限流程处理。
5. **假设** 已启用 `sdd@builtin` 且校验脚本已被放行执行，**当** 我检查 `settings.local.json` 时，**则** 未新增任何持久化权限规则（放行规则仅存在于本次会话内存中）。
6. **假设** 主 agent 委派子代理执行规格校验，**当** 子代理运行校验脚本时，**则** 同样无需授权（实例级规则随子代理创建继承）。

***

### 用户故事：内置插件随 SDK 通用分发（优先级：P3）

作为插件开发者，我希望内置插件不绑定特定项目的目录或领域概念，以便任意项目启用后都能直接工作。

**为什么是这个优先级**：通用性是内置插件随 SDK 分发的先决条件，但属于改进性需求，故为 P3。

**独立测试**：可以在一个不含任何 Wave 特定配置的全新目录中启用插件并描述一个功能需求，验证 AI 自动创建规格来进行测试。

**验收场景**：

1. **假设** 我在一个全新项目目录中启用 SDD 插件，**当** AI 触发规格编写时，**则** 插件自动探测 `docs/specs/` 或 `specs/`，不依赖任何项目专属路径或领域名称。
2. **假设** 校验脚本在任意目录运行，**当** 校验脚本执行时，**则** 仅依赖 Node.js 标准库，无需项目构建产物或文档站模块。

***

### 用户故事：通过单选决策衔接工作流各阶段（优先级：P1）

作为开发者，我希望规格确认、技术方案等可选阶段的衔接以及执行方式的选择均通过单选按钮决策，以便不必输入自然语言即可点击推进工作流。

**为什么是这个优先级**：衔接方式是改造后工作流的骨架——所有阶段切换都依赖单选决策，属于 P1 核心体验。

**独立测试**：可以通过在会话中描述一个需求，验证 spec 确认及后续衔接均弹出单选选项、仅凭点击即可推进流程来进行完整测试。

**验收场景**：

1. **假设** 规格说明已编写完成，**当** AI 请求决策时，**则** 通过 AskUserQuestion 呈现单选选项（直接实现 / 制定技术方案），并在问题文案中说明选「其他」可输入修改意见；「其他」选项由 AskUserQuestion 自动提供，弹窗中只出现一个「其他」。
2. **假设** 用户选择"其他"并输入修改意见，**当** 提交后，**则** AI 视为规格需要调整，更新规格说明后再次通过单选请求决策。
3. **假设** 用户选择"制定技术方案"，**当** 流程继续时，**则** 进入技术方案模式制定技术方案。
4. **假设** 用户选择"直接实现"，**当** 流程继续时，**则** 跳过技术方案阶段进入执行阶段，并在执行阶段入口弹出执行方式单选。
5. **假设** 工作流处于阶段衔接处，**当** 用户全程只点击单选、不输入任何自然语言时，**则** 流程仍能推进到下一阶段。

***

### 用户故事：可选技术方案阶段（优先级：P1）

作为开发者，我希望在规格确认时通过单选选择进入技术方案模式制定技术方案，以便复杂需求在编码前先明确实现路径并获批准。

**为什么是这个优先级**：技术方案阶段是新增的核心可选环节，直接决定流程深度，故为 P1。

**独立测试**：可以通过在规格确认时选择"制定技术方案"，验证 AI 产出技术方案并经批准后进入执行阶段；再选择"直接实现"验证跳过该阶段直接进入执行阶段来进行测试。

**验收场景**：

1. **假设** 规格确认时用户选择"制定技术方案"，**当** 进入技术方案模式时，**则** AI 制定技术方案（技术选型、架构设计、实现步骤）并请求用户批准。
2. **假设** 用户在规格确认时选择"直接实现"，**当** 流程继续时，**则** 跳过技术方案阶段，直接进入执行阶段。
3. **假设** 技术方案被用户拒绝，**当** 用户给出修改意见时，**则** AI 更新方案后重新请求批准。
4. **假设** 技术方案获得批准，**当** 退出技术方案模式时，**则** 进入执行阶段。

***

### 用户故事：执行阶段选择执行方式（优先级：P1）

作为开发者，我希望进入执行阶段时用单选选择执行方式（普通执行 / 子代理驱动 / 工作流编排），以便按改动规模在"省"与"质量门密度"之间取舍，而不是所有改动都走同一种执行。

**为什么是这个优先级**：这是执行阶段的入口能力——执行的第一步就是这一次选择，三档执行方式都挂在它后面，故为 P1。

**独立测试**：可以通过分别走"直接实现"与"制定技术方案"两条路径进入执行阶段，验证两条路径都弹出执行方式单选、且每档选完后按该档实际执行（普通执行在本会话逐项实现、子代理驱动每任务一实现一评审、工作流编排按名字调用插件工作流）来进行完整测试。

**验收场景**：

1. **假设** 规格已确认或技术方案已获批准，**当** 流程进入执行阶段时，**则** 通过 AskUserQuestion 呈现单选选项（普通执行 / 子代理驱动 / 工作流编排），外加工具自动提供的「其他」；问题文案给出一句推荐及理由（依据规格中用户故事的条数与各故事的"独立测试"描述），不要求自然语言输入。
2. **假设** 用户选择"普通执行"，**当** 执行开始时，**则** AI 在当前会话内按任务清单逐项实现，任务之间不再询问是否继续，全部完成后做一次整体评审。
3. **假设** 用户选择"子代理驱动"，**当** 执行开始时，**则** AI 为每个任务派一个 general-purpose 子代理实现，实现交回后派一个评审子代理给出"规格合规 + 代码质量"结论；评审不通过则把阻断项回灌重做一个来回，仍不通过就停下问用户。
4. **假设** 用户选择"工作流编排"，**当** 执行开始时，**则** AI 自己编写一条工作流脚本（任务清单写进脚本本体），写阶段串行、只读阶段可并行，工作流在后台运行、可用 `/workflows` 查看进度；此后 AI 不再自己动手实现同一批任务，等完成通知按裁决收口。
5. **假设** 用户在执行方式选择中选「其他」并输入意见（如"别问，直接写"），**当** 提交后，**则** 按该意见执行，不再重复询问。
6. **假设** 规格确认时用户选择了"制定技术方案"且方案已获批准，**当** 进入执行阶段时，**则** 同样弹出执行方式单选——与"直接实现"路径使用同一决策点，不沿用此前任何选择。
7. **假设** 执行阶段已经开始，**当** 任务之间推进时，**则** 不出现"是否继续"类提问，也不再重复询问执行方式。
8. **假设** 执行中途会话被压缩或重启，**当** 恢复执行时，**则** 依据规格里的验收场景与 git 提交历史续做，不重复已完成的任务。

***

### 边界情况

* AI 触发规格编写但对话中没有明确的功能描述时，如何处理？→ 不猜测需求，先向用户澄清要编写或更新哪个功能。
* 规格目录存在但为空时，分组约定如何确定？→ 无既有分组则使用扁平结构，直接放在规格根目录下。
* 生成的 slug 与既有规格文件重名时如何处理？→ 生成与组内已有文件名不冲突的新 slug。
* 校验脚本绝对路径随 SDK 安装位置（npm 重装、不同工作树）动态变化，自动放行如何保持有效？→ 允许规则用通配符锚定脚本文件名（`spec-count.js`），与具体安装路径解耦。
* 自动放行是否会误放行插件外的其他 node 命令？→ 规则锚定命令目标为 spec-count.js，其他 node 命令（含插件内其他脚本）仍走正常权限流程。
* 技术方案阶段可选，最短流程只有哪几个阶段？→ 规格 + 执行（规格决策时选择"直接实现"即跳过技术方案阶段，直接进入执行阶段）。
* 最多可以有几个阶段、顺序如何？→ 规格 + 技术方案 + 执行（3 个阶段），顺序固定为 规格 → 技术方案 → 执行；执行阶段内部第一步是执行方式单选，随后以规格里的验收场景作为任务清单（一条验收场景 = 一个任务）逐项实现。
* 阶段进度如何展示？→ 不另建任务列表：任务清单直接取自已确认规格里的验收场景，三档执行方式都按它逐条推进，续做的判断依据是验收场景与 git 提交历史。规格一旦定稿，进度就是「哪些验收场景已经落地」，不需要一份会与会话同生共死的副本。
* 三档执行方式是否各自维护一套工件？→ 不。规格说明是权威来源、任务清单是唯一任务源、整体评审只做一次；三档只替换"谁来执行任务"与"评审粒度"，其余流程一致，避免三份流程各自漂移。
* 用户在衔接处如何表达选择？→ 规格确认与技术方案批准用 AskUserQuestion 单选（直接实现 / 制定技术方案）；执行阶段入口用同一工具单选执行方式（普通执行 / 子代理驱动 / 工作流编排），两处都由工具自动提供「其他」自定义输入，不要求自然语言输入；选「其他」即输入修改意见，若用户主动用自然语言表达选择，等同单选结果处理。AI 不在选项中手动添加「其他」，避免与工具自动提供的「其他」重复。
* 选"工作流编排"是否满足 Workflow 工具的调用前提？→ 是。用户在该单选里明确选中即构成"用户明确要求多智能体编排"；未选中时不得主动调用该工具，也不得为"顺手并行"自行升级到工作流。
* 工作流脚本能否读取磁盘上的任务清单？→ 不能，脚本运行环境没有文件系统访问能力；任务清单要写进脚本本体。
* 多个实现子代理能否并行？→ 能：每个子代理带工作树隔离时改动留在各自工作树里，共享文件也不在执行期冲突。判据是任务之间**有无依赖**——隔离工作树看不到彼此的产出，有依赖的任务必须串行。并行时收口需要按序合并各工作树、解决冲突、合并后重跑验证，再逐支评审。工作流模式做不到（工作流里的 agent 拿不到工作树隔离），写阶段只能串行。
* 改动很小时是否仍弹出执行方式单选？→ 是。执行阶段入口一律问一次，不按改动规模跳过：跳过判据会随项目漂移，跳过也让阶段边界变得不清晰；用户若确实嫌繁琐，可在「其他」里说明一次口径并沿用它。