CodeWave IDE

Appearance

功能规格说明：自定义斜杠命令 ​

创建日期：2024-12-19

用户场景与测试 （必填） ​

用户故事：创建和使用基础自定义命令（优先级：P1） ​

用户可以通过将 markdown 文件放置在指定目录中来创建自定义斜杠命令，以自动化常用任务和工作流。

为什么是这个优先级：这是通过允许用户将复杂指令封装为简单命令来提供即时生产力价值的核心功能。

独立测试：可以通过创建一个简单的命令文件（例如 /project-info）并执行它来验证命令运行并产生预期输出来完整测试。

验收场景：

  1. 假设 用户的项目中有一个 .wave/commands/ 目录，当 他们创建一个名为 project-info.md 的 markdown 文件并包含命令内容，则 系统自动将其加载为 /project-info 命令
  2. 假设 存在一个自定义命令，当 用户在聊天中输入 /project-info，则 命令执行并在对话中显示结果
  3. 假设 自定义命令文件被修改，当 系统重新加载命令，则 更新的命令行为立即可用

用户故事：命令发现和自动补全（优先级：P1） ​

用户可以通过带有自动补全功能的交互式命令选择器发现可用的自定义命令。

为什么是这个优先级：对可用性至关重要 - 用户需要知道有哪些命令可用并能轻松找到它们。

独立测试：可以通过输入 / 并验证命令选择器出现，显示内置和自定义命令，以及功能搜索过滤来测试。

验收场景：

  1. 假设 自定义命令已加载，当 用户在输入框中输入 /，则 命令选择器出现，显示内置和自定义命令
  2. 假设 命令选择器已打开，当 用户在 / 后输入字符，则 列表过滤仅显示匹配的命令
  3. 假设 命令选择器显示过滤结果，当 用户用方向键导航并按 Enter，则 选中的命令被执行

用户故事：参数化命令（优先级：P2） ​

用户可以创建接受参数并使用参数替换的命令，以创建灵活、可复用的命令模板。

为什么是这个优先级：通过允许动态内容和减少对多个相似命令的需求来显著提高命令实用性。

独立测试：可以通过创建带有 $ARGUMENTS 或 $1, $2 占位符的命令并验证在调用命令时正确替换参数来测试。

验收场景：

  1. 假设 命令内容包含 $ARGUMENTS，当 用户执行 /command-name some arguments，则 $ARGUMENTS 被替换为 "some arguments"
  2. 假设 命令包含 $1 $2 占位符，当 用户执行 /command-name first second，则 $1 变为 "first"，$2 变为 "second"
  3. 假设 命令期望参数，当 用户提供带空格的引号参数，则 引号内容被视为单个参数
  4. 假设 命令不包含参数占位符，当 用户执行 /command-name some arguments，则 "some arguments" 自动追加到命令内容末尾

用户故事：命令配置和模型选择（优先级：P2） ​

用户可以使用 YAML frontmatter 为自定义命令配置特定的 AI 模型。

为什么是这个优先级：支持针对特定用例优化命令。

独立测试：可以通过创建 frontmatter 中指定模型的命令，然后验证 AI 在执行期间使用指定配置来测试。

验收场景：

  1. 假设 命令的 frontmatter 中有 model: gpt-4，当 命令执行，则 AI 使用指定模型而非默认值
  2. 假设 命令在 frontmatter 中有自定义描述，当 显示命令选择器，则 显示自定义描述而非自动生成的文本
  3. 假设 命令的 frontmatter 用 YAML 块标量写多行值（>／>-／|／|- 等），当 命令被加载，则 model／description 等字段必须是折叠／保留后的真实文本（不含 >、|、- 这类指示符），续行不得被解析成独立的 frontmatter 键；命令选择器里展示的描述就是解析后的结果

用户故事：项目和用户级命令作用域（优先级：P3） ​

用户可以在项目级（.wave/commands/）和用户级（~/.wave/commands/）定义命令，项目命令优先。

为什么是这个优先级：为项目特定工作流和跨项目的个人生产力命令提供灵活性。

独立测试：可以通过在两个位置创建同名命令并验证项目级命令覆盖用户级命令来测试。

验收场景：

  1. 假设 用户在 ~/.wave/commands/ 中有命令，当 他们使用任何项目，则 这些命令全局可用
  2. 假设 用户和项目目录都包含同名命令，当 命令被执行，则 使用项目级版本
  3. 假设 项目没有 .wave/commands/ 目录，当 用户级命令存在，则 它们仍被加载并可用

用户故事：自动批准的工具执行（优先级：P1） ​

作为用户，我希望在触发斜杠命令时 AI 自动执行特定工具，这样我就不必手动确认已知工作流的每一步。

为什么是这个优先级：这是一个高价值增强功能，减少常见自动化任务的摩擦。

独立测试：可以通过触发带有 allowed-tools 的斜杠命令并验证 AI 执行这些工具时不提示用户确认来测试。

验收场景：

  1. 假设 斜杠命令定义了 allowed-tools: Bash(git commit *)，当 用户触发此命令且 AI 调用 Bash(git commit -m "test")，则 工具应立即执行，无需确认提示，因为它匹配模式
  2. 假设 斜杠命令定义了 allowed-tools: Bash(git commit *)，当 用户触发此命令且 AI 调用 Bash(git commit -m "test" && rm -rf /)，则 工具必须被阻止或需要确认，因为命令链的第二部分不被允许
  3. 假设 斜杠命令有 allowed-tools，当 AI 调用不在列表中的工具（例如 Write），则 系统必须像往常一样提示用户确认（除非它已在 settings.json 中被允许）
  4. 假设 带有 allowed-tools 的活跃斜杠命令会话，当 AI 完成任务且响应周期结束，则 所有后续工具执行必须需要手动确认

边界情况 ​

  • 命令文件包含无效 YAML frontmatter 时会怎样？
  • 系统如何处理具有无限循环或长时间运行操作的命令？
  • 命令引用不存在的参数时会怎样（例如只有 2 个参数但引用 $5）？
  • 重载操作期间如何处理同名命令？
  • 自定义命令中的 bash 命令失败或超时时会怎样？
  • 空允许工具：如果斜杠命令未定义 allowed-tools，所有工具执行必须需要手动确认
  • 无效模式语法：如果 allowed-tools 模式语法无效，系统应忽略该特定模式并对匹配工具默认使用手动确认
  • 会话持久性：如果用户开始新任务或切换上下文，之前斜杠命令的任何活跃 allowed-tools 权限必须被撤销
  • 重叠模式：如果多个模式匹配工具执行，最宽松的一个（自动批准）优先