命令
这是 OpenSpec 斜杠命令的参考文档。这些命令在您的 AI 编程助手聊天界面中调用（例如 Claude Code、Cursor、Windsurf）。
有关工作流模式以及何时使用每个命令，请参阅工作流。有关 CLI 命令，请参阅 CLI。
快速参考
默认快速路径（core 配置）
| 命令 | 用途 |
|---|---|
/opsx:propose | 一步创建变更并生成规划产物 |
/opsx:explore | 在提交变更前深入思考想法 |
/opsx:apply | 实施变更中的任务 |
/opsx:sync | 将增量规范合并到主规范中 |
/opsx:archive | 归档已完成的变更 |
扩展工作流命令（自定义工作流选择）
| 命令 | 用途 |
|---|---|
/opsx:new | 开始新的变更脚手架 |
/opsx:continue | 基于依赖关系创建下一个产物 |
/opsx:ff | 快进：一次性创建所有规划产物 |
/opsx:verify | 验证实现是否与产物匹配 |
/opsx:bulk-archive | 一次性归档多个变更 |
/opsx:onboard | 完整工作流的引导式教程 |
默认全局配置为 core。要启用扩展工作流命令，请运行 openspec config profile，选择工作流，然后在您的项目中运行 openspec update。
命令参考
/opsx:propose
一步创建新变更并生成规划工件。这是 core 配置文件中的默认启动命令。
语法：
text
/opsx:propose [change-name-or-description]参数：
| 参数 | 必需 | 描述 |
|---|---|---|
change-name-or-description | 否 | 短横线命名的名称或自然语言的变更描述 |
功能说明：
- 创建
openspec/changes/<change-name>/目录 - 生成实施前所需的工件（对于
spec-driven：提案、规范、设计、任务） - 当变更准备好执行
/opsx:apply时停止
示例：
text
你: /opsx:propose add-dark-mode
AI: 已创建 openspec/changes/add-dark-mode/
✓ proposal.md
✓ specs/ui/spec.md
✓ design.md
✓ tasks.md
准备就绪，可以实施。运行 /opsx:apply。提示：
- 用于最快的端到端流程
- 如果需要逐步控制工件，请启用扩展工作流并使用
/opsx:new+/opsx:continue
/opsx:explore
在提交变更之前，梳理思路、调查问题并明确需求。
语法：
/opsx:explore [topic]参数：
| 参数 | 必需 | 描述 |
|---|---|---|
topic | 否 | 你想要探索或调查的主题 |
功能说明：
- 开启一个无需固定结构的探索性对话
- 调查代码库以回答问题
- 比较各种选项和方案
- 创建可视化图表以理清思路
- 当思路清晰时，可以过渡到
/opsx:propose（默认）或/opsx:new（扩展工作流）
示例：
text
你: /opsx:explore
AI: 你想探索什么？
你: 我们应该如何为移动应用处理身份验证？
AI: 让我调查一下你当前的身份验证设置...
[分析代码库]
我看到你为 Web 应用使用了基于会话的身份验证。
对于移动端，我们主要有三个选项：
1. JWT 令牌（无状态，支持离线）
2. OAuth2（如果你需要第三方登录）
3. 扩展当前会话（更简单，但需要连接）
你的 API 已经配置了 CORS。你对哪个方向感兴趣？
你: 我们选择 JWT。可以为此开始一个变更吗？
AI: 随时可以。运行 /opsx:propose add-jwt-auth 开始。提示：
- 当需求不明确或需要调查时使用
- 探索期间不会创建任何工件
- 适合在决定前比较多种方案
- 可以读取文件和搜索代码库
/opsx:new
启动一个新的变更脚手架。创建变更文件夹，并等待你使用 /opsx:continue 或 /opsx:ff 生成工件。
此命令是扩展工作流集的一部分（不包含在默认的 core 配置文件中）。
语法：
/opsx:new [change-name] [--schema <schema-name>]参数：
| 参数 | 必需 | 描述 |
|---|---|---|
change-name | 否 | 变更文件夹的名称（如果未提供则会提示） |
--schema | 否 | 要使用的工作流模式（默认：来自配置或 spec-driven） |
功能说明：
- 创建
openspec/changes/<change-name>/目录 - 在变更文件夹中创建
.openspec.yaml元数据文件 - 显示准备好创建的第一个工件模板
- 如果未提供变更名称和模式，则进行提示
创建内容：
openspec/changes/<change-name>/
└── .openspec.yaml # 变更元数据（模式、创建日期）示例：
你: /opsx:new add-dark-mode
AI: 已创建 openspec/changes/add-dark-mode/
模式: spec-driven
准备创建: 提案
使用 /opsx:continue 创建它，或使用 /opsx:ff 创建所有工件。提示：
- 使用描述性名称：
add-feature、fix-bug、refactor-module - 避免使用通用名称如
update、changes、wip - 模式也可以在项目配置 (
openspec/config.yaml) 中设置
/opsx:continue
创建依赖链中的下一个工件。一次创建一个工件，实现增量进展。
语法：
/opsx:continue [change-name]参数：
| 参数 | 必需 | 描述 |
|---|---|---|
change-name | 否 | 要继续的变更（如果未提供则从上下文推断） |
功能说明：
- 查询工件依赖图
- 显示哪些工件已就绪，哪些被阻塞
- 创建第一个就绪的工件
- 读取依赖文件以获取上下文
- 显示创建后哪些工件变得可用
示例：
你: /opsx:continue
AI: 变更: add-dark-mode
工件状态:
✓ 提案 (完成)
◆ 规范 (就绪)
◆ 设计 (就绪)
○ 任务 (阻塞 - 需要: 规范)
正在创建规范...
[读取 proposal.md，根据需求创建规范]
✓ 已创建 openspec/changes/add-dark-mode/specs/ui/spec.md
现在可用: 任务
运行 /opsx:continue 创建下一个工件。提示：
- 当你想在继续前审查每个工件时使用
- 适合需要控制的复杂变更
- 多个工件可能同时就绪
- 你可以在继续前编辑已创建的工件
/opsx:ff
快速推进工件创建。一次性创建所有规划工件。
语法：
/opsx:ff [change-name]参数：
| 参数 | 必需 | 描述 |
|---|---|---|
change-name | 否 | 要快速推进的变更（如果未提供则从上下文推断） |
功能说明：
- 按依赖顺序创建所有工件
- 通过待办事项列表跟踪进度
- 当所有
apply-required工件完成时停止 - 在创建下一个工件前读取每个依赖项
示例：
你: /opsx:ff add-dark-mode
AI: 快速推进 add-dark-mode...
✓ 正在创建 proposal.md
✓ 正在创建 specs/ui/spec.md
✓ 正在创建 design.md
✓ 正在创建 tasks.md
所有规划工件完成！
准备就绪，可以实施。运行 /opsx:apply 开始。提示：
- 当你对要构建的内容有清晰构想时使用
- 对于直接的变更，比
/opsx:continue更快 - 你仍然可以在之后编辑工件
- 适合中小型功能
/opsx:apply
实施变更中的任务。按任务列表工作，编写代码并勾选完成项。
语法：
/opsx:apply [change-name]参数：
| 参数 | 必需 | 描述 |
|---|---|---|
change-name | 否 | 要实施的变更（如果未提供则从上下文推断） |
功能说明：
- 读取
tasks.md并识别未完成的任务 - 逐个处理任务
- 根据需要编写代码、创建文件、运行测试
- 使用复选框
[x]标记任务完成
示例：
你: /opsx:apply
AI: 正在实施 add-dark-mode...
读取 tasks.md:
- [ ] 1.1 创建 ThemeContext
- [ ] 1.2 添加 CSS 自定义属性
- [ ] 1.3 实现 localStorage 持久化
正在处理 1.1: 创建 ThemeContext...
[创建 src/context/ThemeContext.tsx]
✓ 1.1 完成
正在处理 1.2: 添加 CSS 自定义属性...
[更新 src/styles/globals.css]
✓ 1.2 完成
...提示：
- 如果中断，可以从中断处继续
- 通过指定变更名称，可用于并行变更
- 完成状态在
tasks.md的复选框中跟踪
/opsx:verify
验证实现是否与你的变更工件匹配。检查完整性、正确性和一致性。
语法：
/opsx:verify [change-name]参数：
| 参数 | 必需 | 描述 |
|---|---|---|
change-name | 否 | 要验证的变更（如果未提供则从上下文推断） |
功能说明：
- 检查实现质量的三个维度
- 在代码库中搜索实现证据
- 报告问题，分为严重、警告或建议类别
- 不会阻止归档，但会指出问题
验证维度：
| 维度 | 验证内容 |
|---|---|
| 完整性 | 所有任务完成，所有需求已实现，场景已覆盖 |
| 正确性 | 实现符合规范意图，边界情况已处理 |
| 一致性 | 设计决策反映在代码中，模式保持一致 |
示例：
你: /opsx:verify
AI: 正在验证 add-dark-mode...
完整性
✓ tasks.md 中所有 8 个任务已勾选
✓ 规范中的所有需求都有对应代码
⚠ 场景“系统偏好检测”没有测试覆盖
正确性
✓ 实现符合规范意图
✓ 场景中的边界情况已处理
✓ 错误状态符合规范定义
一致性
✓ 设计决策反映在代码结构中
✓ 命名约定与 design.md 一致
⚠ 设计提到“CSS 变量”但实现使用了 Tailwind 类
总结
─────────────────────────────
严重问题: 0
警告: 2
可以归档: 是（有警告）
建议:
1. 为系统偏好检测添加测试
2. 更新 design.md 以反映 Tailwind 的使用，或重构为使用 CSS 变量提示：
- 在归档前运行，以尽早发现不匹配
- 警告不会阻止归档，但表明潜在问题
- 适合在提交前审查 AI 的工作
- 可以揭示工件与实现之间的偏差
/opsx:sync
可选命令。 将变更中的增量规范合并到主规范中。如果需要，归档操作会提示进行同步，因此通常你不需要手动运行此命令。
语法：
/opsx:sync [change-name]参数：
| 参数 | 必需 | 描述 |
|---|---|---|
change-name | 否 | 要同步的变更（如果未提供则从上下文推断） |
功能说明：
- 从变更文件夹读取增量规范
- 解析 ADDED/MODIFIED/REMOVED/RENAMED 部分
- 将更改合并到主
openspec/specs/目录 - 保留增量中未提及的现有内容
- 不会归档变更（保持活动状态）
示例：
text
你: /opsx:sync
AI: 正在同步 add-dark-mode 增量规范...
读取: openspec/changes/add-dark-mode/specs/ui/spec.md
目标: openspec/specs/ui/spec.md
要应用的更改:
✓ 已添加: 主题选择需求（2 个场景）
✓ 已添加: 无障碍需求（1 个场景）
合并中...
✓ openspec/specs/ui/spec.md 已更新
变更保持活动状态。准备好时运行 /opsx:archive 完成。何时手动使用：
| 场景 | 使用同步？ |
|---|---|
| 长期运行的变更，希望在归档前将规范放入主目录 | 是 |
| 多个并行变更需要更新的基础规范 | 是 |
| 希望单独预览/审查合并 | 是 |
| 快速变更，直接归档 | 否（归档会处理） |
提示：
- 同步是智能的，不是简单的复制粘贴
- 可以向现有需求添加场景而不会重复
- 同步后变更保持活动状态（未归档）
- 大多数用户永远不需要直接调用此命令——如果需要，归档操作会提示
/opsx:archive
归档已完成的变更。完成变更并将其移动到归档文件夹。
语法：
/opsx:archive [change-name]参数：
| 参数 | 必需 | 描述 |
|---|---|---|
change-name | 否 | 要归档的变更（如果未提供则从上下文推断） |
功能说明：
- 检查工件完成状态
- 检查任务完成情况（如果未完成则警告）
- 如果尚未同步，提供同步增量规范的选项
- 将变更文件夹移动到
openspec/changes/archive/YYYY-MM-DD-<name>/ - 保留所有工件以供审计追踪
示例：
text
你: /opsx:archive
AI: 正在归档 add-dark-mode...
工件状态:
✓ proposal.md 存在
✓ specs/ 存在
✓ design.md 存在
✓ tasks.md 存在（8/8 任务完成）
增量规范: 尚未同步
→ 立即同步？（推荐）
你: 是
AI: ✓ 已将规范同步到 openspec/specs/ui/spec.md
✓ 已移动到 openspec/changes/archive/2025-01-24-add-dark-mode/
变更归档成功。提示：
- 归档不会因任务未完成而阻止，但会发出警告
- 增量规范可以在归档期间或之前同步
- 已归档的变更会保留以供历史记录
- 使用
/opsx:verify先行检查问题
/opsx:bulk-archive
一次归档多个已完成的变更。处理变更之间的规范冲突。
语法：
/opsx:bulk-archive [change-names...]参数：
| 参数 | 必需 | 描述 |
|---|---|---|
change-names | 否 | 要归档的特定变更（如果未提供则提示选择） |
功能说明：
- 列出所有已完成的变更
- 在归档前验证每个变更
- 检测变更之间的规范冲突
- 通过检查实际实现来解决冲突
- 按时间顺序归档
示例：
你: /opsx:bulk-archive
AI: 找到 3 个已完成的变更:
- add-dark-mode (8/8 任务完成)
- fix-login-bug (3/3 任务完成)
- update-footer (2/2 任务完成)
检查规范冲突...
⚠ add-dark-mode 和 update-footer 都涉及 specs/ui/
检查代码库以解决...
两个变更都已实现。将按时间顺序合并:
1. add-dark-mode (创建于 1月20日)
2. update-footer (创建于 1月22日)
归档所有 3 个变更？
你: 是
AI: ✓ 已归档 add-dark-mode
✓ 已归档 fix-login-bug
✓ 已归档 update-footer
规范已合并: add-dark-mode → update-footer提示：
- 适合并行工作流
- 冲突解决是智能的（检查代码库）
- 变更按创建顺序归档
- 在覆盖规范内容前会提示
/opsx:onboard
引导式入门，贯穿完整的 OpenSpec 工作流。一个使用你实际代码库的交互式教程。
语法：
/opsx:onboard功能说明：
- 带讲解地走完一个完整的工作流周期
- 扫描你的代码库以寻找真实的改进机会
- 创建一个带有真实工件的实际变更
- 实施实际工作（小而安全的更改）
- 归档已完成的变更
- 在每一步发生时进行解释
阶段：
- 欢迎与代码库分析
- 寻找改进机会
- 创建变更 (
/opsx:new) - 编写提案
- 创建规范
- 编写设计
- 创建任务
- 实施任务 (
/opsx:apply) - 验证实现
- 归档变更
- 总结与后续步骤
示例：
你: /opsx:onboard
AI: 欢迎使用 OpenSpec！
我将使用你实际的代码库，带你走完整个工作流程。
我们将找到一些小的改进点，为其创建一个正式的变更，
实施它，然后归档它。
让我扫描你的代码库寻找机会...
[分析代码库]
我找到了一些我们可以着手的事情:
1. 为联系表单添加输入验证
2. 改进身份验证流程中的错误消息
3. 为异步按钮添加加载状态
你对哪个感兴趣？（或建议其他内容）提示：
- 最适合学习工作流的新用户
- 使用真实代码，而非玩具示例
- 创建一个你可以保留或丢弃的真实变更
- 完成需要 15-30 分钟
各 AI 工具的命令语法
不同的 AI 工具使用略有不同的命令语法。请使用与您工具匹配的格式：
| 工具 | 语法示例 |
|---|---|
| Claude Code | /opsx:propose, /opsx:apply |
| Cursor | /opsx-propose, /opsx-apply |
| Windsurf | /opsx-propose, /opsx-apply |
| Copilot (IDE) | /opsx-propose, /opsx-apply |
| Kimi CLI | 基于技能的调用，例如 /skill:openspec-propose, /skill:openspec-apply-change（不生成 opsx-* 命令文件） |
| Trae | 基于技能的调用，例如 /openspec-propose, /openspec-apply-change（不生成 opsx-* 命令文件） |
各工具的意图相同，但命令的呈现方式可能因集成方式而异。
注意： GitHub Copilot 命令（
.github/prompts/*.prompt.md）仅在 IDE 扩展（VS Code、JetBrains、Visual Studio）中可用。GitHub Copilot CLI 目前不支持自定义提示文件 — 详情和解决方法请参见支持的工具。
旧版命令
这些命令使用较旧的“一次性”工作流。它们仍然有效，但推荐使用 OPSX 命令。
| 命令 | 功能 |
|---|---|
/openspec:proposal | 一次性创建所有工件（提案、规范、设计、任务） |
/openspec:apply | 实施变更 |
/openspec:archive | 归档变更 |
何时使用旧版命令：
- 使用旧工作流的现有项目
- 不需要增量创建工件的简单变更
- 偏好“全有或全无”的方式
迁移到 OPSX： 旧版变更可以使用 OPSX 命令继续。工件结构是兼容的。
故障排除
“未找到变更”
命令无法识别要处理哪个变更。
解决方案：
- 明确指定变更名称：
/opsx:apply add-dark-mode - 检查变更文件夹是否存在：
openspec list - 确认您位于正确的项目目录中
“没有就绪的工件”
所有工件要么已完成，要么因缺少依赖项而被阻塞。
解决方案：
- 运行
openspec status --change <name>查看阻塞原因 - 检查所需工件是否存在
- 首先创建缺失的依赖工件
“未找到模式”
指定的模式不存在。
解决方案：
- 列出可用模式：
openspec schemas - 检查模式名称的拼写
- 如果是自定义模式，请创建它：
openspec schema init <name>
命令未被识别
AI 工具无法识别 OpenSpec 命令。
解决方案：
- 确保 OpenSpec 已初始化：
openspec init - 重新生成技能：
openspec update - 检查
.claude/skills/目录是否存在（针对 Claude Code） - 重启您的 AI 工具以加载新技能
工件生成不正确
AI 创建了不完整或不正确的工件。
解决方案：
- 在
openspec/config.yaml中添加项目上下文 - 为特定指导添加每工件规则
- 在变更描述中提供更多细节
- 使用
/opsx:continue而不是/opsx:ff以获得更多控制