CodeWave IDE

Appearance

功能规格说明：内置 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「插件变更的就地重载」。
  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. 假设 技术方案获得批准，当 退出技术方案模式时，则 进入编码阶段。

用户故事：任务列表追踪各阶段进度（优先级：P2） ​

作为开发者，我希望规格、技术方案与编码各阶段进度显示在任务列表中，以便随时了解工作流当前处于哪个阶段。

为什么是这个优先级：进度追踪提升可见性但不影响流程正确性，故为 P2。

独立测试：可以通过走完一次完整工作流，验证任务列表按阶段出现「进行中」并依次标记完成、跳过可选阶段时无对应任务来进行测试。

验收场景：

  1. 假设 规格阶段开始，当 AI 编写规格说明时，则 任务列表出现规格编写任务并标记进行中，规格确认后标记完成。
  2. 假设 用户选择制定技术方案，当 技术方案制定进行时，则 任务列表出现技术方案任务并标记进行中，方案批准后标记完成。
  3. 假设 进入编码阶段，当 功能实现进行时，则 任务列表出现编码任务并标记进行中，实现完成时标记完成。
  4. 假设 用户跳过可选阶段，当 对应衔接被跳过时，则 不创建该阶段的任务，任务列表只反映实际经过的阶段。

边界情况 ​

  • AI 触发规格编写但对话中没有明确的功能描述时，如何处理？→ 不猜测需求，先向用户澄清要编写或更新哪个功能。
  • 规格目录存在但为空时，分组约定如何确定？→ 无既有分组则使用扁平结构，直接放在规格根目录下。
  • 生成的 slug 与既有规格文件重名时如何处理？→ 生成与组内已有文件名不冲突的新 slug。
  • 校验脚本绝对路径随 SDK 安装位置（npm 重装、不同工作树）动态变化，自动放行如何保持有效？→ 允许规则用通配符锚定脚本文件名（spec-count.js），与具体安装路径解耦。
  • 自动放行是否会误放行插件外的其他 node 命令？→ 规则锚定命令目标为 spec-count.js，其他 node 命令（含插件内其他脚本）仍走正常权限流程。
  • 技术方案阶段可选，最短流程只有哪几个阶段？→ 规格 + 编码（规格决策时选择"直接实现"即跳过可选阶段）。
  • 最多可以有几个阶段、顺序如何？→ 规格 + 技术方案 + 编码（3 个阶段），顺序固定为 规格 → 技术方案 → 编码。
  • 用户在衔接处如何表达选择？→ 一律通过 AskUserQuestion 单选（直接实现 / 制定技术方案，外加工具自动提供的「其他」自定义输入），不要求自然语言输入；选「其他」即输入修改意见，视为规格需要调整，若用户主动用自然语言表达选择，等同单选结果处理。AI 不在选项中手动添加「其他」，避免与工具自动提供的「其他」重复。