命令

这是 OpenSpec 斜杠命令的参考文档。这些命令在 AI 编程助手的聊天界面中调用（例如 Claude Code、Cursor、Devin Desktop）。

有关工作流模式以及何时使用每个命令，请参阅工作流。有关 CLI 命令，请参阅 CLI。

这些页面使用 /opsx:<command> 作为标准名称。某些工具的拼写方式不同 —— Cursor 和 GitHub Copilot 注册为 /opsx-propose，Codex 使用 $openspec-propose —— 因此请查看如何调用以获取您所用工具的信息。OpenSpec 生成的文件已经使用了正确的形式。

快速参考

默认快速路径 (`core` 配置)

命令	用途
`/opsx:propose`	一步创建变更并生成规划工件
`/opsx:explore`	在确定变更之前思考想法
`/opsx:apply`	实施变更中的任务
`/opsx:update`	修订变更的规划工件并保持其一致性
`/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

You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md
     ✓ specs/ui/spec.md
     ✓ design.md
     ✓ tasks.md
     Ready for implementation. Run /opsx:apply.

提示：

使用此命令可获得最快的端到端路径
如果需要逐步控制产物，请启用扩展工作流并使用 /opsx:new + /opsx:continue

`/opsx:explore`

不确定时从这里开始。 Explore 是一个零风险的思考伙伴：它读取你的代码库，比较各种方案，在任何变更存在之前将模糊的想法打磨成具体的计划。它包含在默认配置中。完整案例和更多示例请参阅 Explore First 指南。

在提交变更之前，思考想法、调查问题并明确需求。

语法：

/opsx:explore [topic]

参数：

参数	是否必填	描述
`topic`	否	你想要探索或调查的内容

功能：

开启一个无需固定结构的探索性对话
调查代码库以回答问题
比较各种选项和方案
创建可视化图表以澄清思路
当洞察明确时，可过渡到 /opsx:propose（默认）或 /opsx:new（扩展工作流）

示例：

text

You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle authentication for the mobile app?

AI:  Let me investigate your current auth setup...
     [Analyzes codebase]

     I see you're using session-based auth for the web app.
     For mobile, we have three main options:

     1. JWT tokens (stateless, works offline)
     2. OAuth2 (if you need third-party login)
     3. Extend current sessions (simpler, but requires connectivity)

     Your API already has CORS configured. Which direction interests you?

You: Let's go with JWT. Can we start a change for that?

AI:  Ready when you are. Run /opsx:propose add-jwt-auth to begin.

提示：

当需求不明确或需要调查时使用
探索过程中不会创建任何产物
适合在做出决定前比较多种方案
可以读取文件并搜索代码库

`/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    # Change metadata (schema, created date)

示例：

You: /opsx:new add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     Schema: spec-driven

     Ready to create: proposal
     Use /opsx:continue to create it, or /opsx:ff to create all artifacts.

提示：

使用描述性名称：add-feature、fix-bug、refactor-module
避免使用通用名称如 update、changes、wip
模式也可以在项目配置中设置（openspec/config.yaml）

`/opsx:continue`

创建依赖链中的下一个产物。一次创建一个产物以实现增量推进。

语法：

/opsx:continue [change-name]

参数：

参数	是否必填	描述
`change-name`	否	要继续的变更（未提供时从上下文推断）

功能：

查询产物依赖图
显示哪些产物已就绪、哪些被阻塞
创建第一个就绪的产物
读取依赖文件以获取上下文
显示创建后可用的内容

示例：

You: /opsx:continue

AI:  Change: add-dark-mode

     Artifact status:
     ✓ proposal    (done)
     ◆ specs       (ready)
     ◆ design      (ready)
     ○ tasks       (blocked - needs: specs, design)

     Creating specs...

     [Reads proposal.md, creates specs based on requirements]

     ✓ Created openspec/changes/add-dark-mode/specs/ui/spec.md

     Now available: design
     Run /opsx:continue to create the next artifact.

提示：

当你想在继续之前审查每个产物时使用
适合需要控制的复杂变更
多个产物可能同时变为就绪状态
你可以在继续之前编辑已创建的产物

`/opsx:ff`

快速推进产物创建。一次性创建所有规划产物。

语法：

/opsx:ff [change-name]

参数：

参数	是否必填	描述
`change-name`	否	要快速推进的变更（未提供时从上下文推断）

功能：

按依赖顺序创建所有产物
通过待办列表跟踪进度
当所有 apply-required 产物完成时停止
在创建下一个产物之前读取每个依赖

示例：

You: /opsx:ff add-dark-mode

AI:  Fast-forwarding add-dark-mode...

     ✓ Creating proposal.md
     ✓ Creating specs/ui/spec.md
     ✓ Creating design.md
     ✓ Creating tasks.md

     All planning artifacts complete!
     Ready for implementation. Run /opsx:apply to begin.

提示：

当你清楚要构建什么时使用
对于简单变更比 /opsx:continue 更快
之后仍然可以编辑产物
适合中小型功能

`/opsx:apply`

实施变更中的任务。逐项处理任务列表，编写代码并勾选完成项。

语法：

/opsx:apply [change-name]

参数：

参数	是否必填	描述
`change-name`	否	要实施的变更（未提供时从上下文推断）

功能：

读取 tasks.md 并识别未完成任务
逐项处理任务
按需编写代码、创建文件、运行测试
使用复选框 [x] 标记任务完成

示例：

You: /opsx:apply

AI:  Implementing add-dark-mode...

     Reading tasks.md:
     - [ ] 1.1 Create ThemeContext
     - [ ] 1.2 Add CSS custom properties
     - [ ] 1.3 Implement localStorage persistence

     Working on 1.1: Create ThemeContext...
     [Creates src/context/ThemeContext.tsx]

     ✓ 1.1 Complete

     Working on 1.2: Add CSS custom properties...
     [Updates src/styles/globals.css]

     ✓ 1.2 Complete
     ...

提示：

如果被打断，可以从上次中断处恢复
通过指定变更名称来并行处理多个变更
完成状态通过 tasks.md 中的复选框跟踪

`/opsx:update`

修订变更的现有规划产物并保持它们之间的一致性。仅处理规划产物——绝不编辑代码。

语法：

text

/opsx:update [change-name]

参数：

参数	是否必填	描述
`change-name`	否	要更新的变更（未提供时从上下文推断）

功能：

通过 openspec status --change <name> --json 读取变更的产物
应用你请求的修订，或者如果你没有指定具体修订内容，则审查产物中的矛盾之处
在任何方向上协调其他现有产物（设计编辑可能会反向影响提案）
每次写入前逐一与你确认每个编辑，逐个产物进行
最后推荐下一步：/opsx:continue（缺少产物）、/opsx:apply（将修订后的计划落实到代码中）或 /opsx:archive（全部完成）

示例：

text

You: /opsx:update add-dark-mode - we're storing the theme in a cookie now, not localStorage

AI:  Reading add-dark-mode artifacts...

     The design references localStorage in two places; tasks 1.3 covers
     localStorage persistence; the proposal doesn't mention storage.

     Proposed revisions:
     1. design.md - swap localStorage decision for cookie storage
     2. tasks.md - reword task 1.3 to cookie persistence

     Apply revision 1? (design.md)

提示：

它不会创建缺失的产物——那是 /opsx:continue 的工作
如果变更已经实施，请跟进 /opsx:apply 以使代码与修订后的计划一致
如果你的修订改变了变更的意图，请重新开始一个新变更（参见何时更新 vs. 重新开始）

`/opsx:verify`

验证实施是否与变更产物匹配。检查完整性、正确性和一致性。

语法：

/opsx:verify [change-name]

参数：

参数	是否必填	描述
`change-name`	否	要验证的变更（未提供时从上下文推断）

功能：

检查实施质量的三个维度
搜索代码库以查找实施证据
将问题分类报告为 CRITICAL、WARNING 或 SUGGESTION
不阻止归档，但会暴露问题

验证维度：

维度	验证内容
完整性	所有任务已完成，所有需求已实施，场景已覆盖
正确性	实施符合规范意图，边界情况已处理
一致性	设计决策反映在代码中，模式一致

示例：

You: /opsx:verify

AI:  Verifying add-dark-mode...

     COMPLETENESS
     ✓ All 8 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "System preference detection" has no test coverage

     CORRECTNESS
     ✓ Implementation matches spec intent
     ✓ Edge cases from scenarios are handled
     ✓ Error states match spec definitions

     COHERENCE
     ✓ Design decisions reflected in code structure
     ✓ Naming conventions consistent with design.md
     ⚠ Design mentions "CSS variables" but implementation uses Tailwind classes

     SUMMARY
     ─────────────────────────────
     Critical issues: 0
     Warnings: 2
     Ready to archive: Yes (with warnings)

     Recommendations:
     1. Add test for system preference detection
     2. Update design.md to reflect Tailwind usage, or refactor to use CSS variables

提示：

在归档前运行以尽早发现不匹配
警告不会阻止归档，但表明潜在问题
适合在提交前审查 AI 的工作
可以揭示产物与实施之间的偏差

`/opsx:sync`

可选命令。 将变更中的增量规范合并到主规范中。归档时会在需要时提示同步，因此你通常不需要手动运行此命令。

语法：

/opsx:sync [change-name]

参数：

参数	是否必填	描述
`change-name`	否	要同步的变更（未提供时从上下文推断）

功能：

从变更文件夹读取增量规范
解析 ADDED/MODIFIED/REMOVED/RENAMED 部分
将变更合并到主 openspec/specs/ 目录
保留增量中未提及的现有内容
不归档变更（保持活跃状态）

示例：

text

You: /opsx:sync

AI:  Syncing add-dark-mode delta specs...

     Reading: openspec/changes/add-dark-mode/specs/ui/spec.md
     Target:  openspec/specs/ui/spec.md

     Changes to apply:
     ✓ ADDED: Theme Selection requirement (2 scenarios)
     ✓ ADDED: Accessibility requirement (1 scenario)

     Merging...
     ✓ openspec/specs/ui/spec.md updated

     Change remains active. Run /opsx:archive when ready to complete.

何时手动使用：

场景	使用 sync？
长期变更，希望在归档前将规范纳入主目录	是
多个并行变更需要更新后的基础规范	是
希望单独预览/审查合并结果	是
快速变更，直接归档	否（归档会处理）

提示：

同步是智能的，不是简单的复制粘贴
可以向现有需求添加场景而不会重复
同步后变更保持活跃状态（未归档）
大多数用户永远不需要直接调用此命令——归档时会在需要时提示

`/opsx:archive`

归档已完成的变更。完成变更并将其移动到归档文件夹。

语法：

/opsx:archive [change-name]

参数：

参数	是否必填	描述
`change-name`	否	要归档的变更（未提供时从上下文推断）

功能：

检查产物完成状态
检查任务完成情况（未完成时发出警告）
如果尚未同步，提供同步增量规范的选项
将变更文件夹移动到 openspec/changes/archive/YYYY-MM-DD-<name>/
保留所有产物以供审计追踪

示例：

text

You: /opsx:archive

AI:  Archiving add-dark-mode...

     Artifact status:
     ✓ proposal.md exists
     ✓ specs/ exists
     ✓ design.md exists
     ✓ tasks.md exists (8/8 tasks complete)

     Delta specs: Not yet synced
     → Sync now? (recommended)

You: Yes

AI:  ✓ Synced specs to openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/

     Change archived successfully.

提示：

归档不会因任务未完成而阻塞，但会发出警告
增量规范可以在归档时或归档前同步
已归档的变更会保留以供历史查阅
先使用 /opsx:verify 以发现问题

`/opsx:bulk-archive`

一次性归档多个已完成的变更。处理变更之间的规范冲突。

语法：

/opsx:bulk-archive [change-names...]

参数：

参数	是否必填	描述
`change-names`	否	要归档的具体变更（未提供时会提示选择）

功能：

列出所有已完成的变更
在归档前验证每个变更
检测变更之间的规范冲突
通过检查实际实施内容来解决冲突
按时间顺序归档

示例：

You: /opsx:bulk-archive

AI:  Found 3 completed changes:
     - add-dark-mode (8/8 tasks complete)
     - fix-login-bug (3/3 tasks complete)
     - update-footer (2/2 tasks complete)

     Checking for spec conflicts...
     ⚠ add-dark-mode and update-footer both touch specs/ui/

     Inspecting codebase to resolve...
     Both changes are implemented. Will merge in chronological order:
     1. add-dark-mode (created Jan 20)
     2. update-footer (created Jan 22)

     Archive all 3 changes?

You: Yes

AI:  ✓ Archived add-dark-mode
     ✓ Archived fix-login-bug
     ✓ Archived update-footer
     Specs merged: add-dark-mode → update-footer

提示：

适合并行工作流
冲突解决是智能的（检查代码库）
变更按创建顺序归档
覆盖规范内容前会提示确认

`/opsx:onboard`

引导式入门，完整体验 OpenSpec 工作流。一个使用你实际代码库的交互式教程。

语法：

/opsx:onboard

功能：

带旁白地走完一个完整的工作流周期
扫描你的代码库以发现真实的改进机会
创建一个包含真实产物的实际变更
实施实际工作（小型、安全的变更）
归档已完成的变更
在每一步发生时进行解释

阶段：

欢迎和代码库分析
寻找改进机会
创建变更（/opsx:new）
编写提案
创建规范
编写设计
创建任务
实施任务（/opsx:apply）
验证实施
归档变更
总结和下一步

示例：

You: /opsx:onboard

AI:  Welcome to OpenSpec!

     I'll walk you through the complete workflow using your actual codebase.
     We'll find something small to improve, create a proper change for it,
     implement it, and archive it.

     Let me scan your codebase for opportunities...

     [Analyzes codebase]

     I found a few things we could work on:
     1. Add input validation to the contact form
     2. Improve error messages in the auth flow
     3. Add loading states to async buttons

     Which interests you? (or suggest something else)

提示：

最适合学习工作流的新用户
使用真实代码，而非玩具示例
创建一个你可以保留或丢弃的真实变更
完成需要 15-30 分钟

按 AI 工具的命令语法

不同的 AI 工具使用的命令语法略有差异。使用与您的工具匹配的格式：

您的工具的命令文件	语法示例	示例工具
`.../commands/opsx/<id>.*`	`/opsx:propose`、`/opsx:apply`	Claude Code、Gemini CLI、Crush
`.../opsx-<id>.*`	`/opsx-propose`、`/opsx-apply`	Cursor、Devin Desktop、Copilot（IDE）、Trae、Oh My Pi
无——仅技能（skills）	`/openspec-propose`、`/openspec-apply-change`	CodeArts、ForgeCode、Hermes、MiniMax Code、Mistral Vibe、Zed Agent、共享的 `.agents`
无——Kimi Code	`/skill:openspec-propose`	Kimi Code
无——Codex CLI	`$openspec-propose`	Codex

Devin Desktop 与 Devin Local 对比： .devin/workflows/opsx-*.md 文件为 Devin Desktop 提供 /opsx-propose。Devin Local 没有工作流——请使用 OpenSpec 写入 .devin/skills/ 的技能，例如 /openspec-propose，这些技能在两个代理上均可使用。

各工具背后的意图是相同的，但命令的呈现方式可能因集成而异。如何调用列出了所有受支持的工具；此表格仅展示每种形式的示例。

注意： 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 以获得更多控制

下一步

工作流 - 常见模式以及何时使用每个命令
CLI - 用于管理和验证的终端命令
自定义 - 创建自定义模式和工作流

命令 ​

快速参考 ​

默认快速路径 (core 配置) ​

扩展工作流命令（自定义工作流选择） ​

命令参考 ​

/opsx:propose ​

/opsx:explore ​

/opsx:new ​

/opsx:continue ​

/opsx:ff ​

/opsx:apply ​

/opsx:update ​

/opsx:verify ​

/opsx:sync ​

/opsx:archive ​

/opsx:bulk-archive ​

/opsx:onboard ​

按 AI 工具的命令语法 ​

旧版命令 ​

故障排除 ​

“变更未找到” ​

“无可用制品” ​

“模式未找到” ​

命令无法识别 ​

制品未正确生成 ​

下一步 ​

命令

快速参考

默认快速路径 (`core` 配置)

扩展工作流命令（自定义工作流选择）

命令参考

`/opsx:propose`

`/opsx:explore`

`/opsx:new`

`/opsx:continue`

`/opsx:ff`

`/opsx:apply`

`/opsx:update`

`/opsx:verify`

`/opsx:sync`

`/opsx:archive`

`/opsx:bulk-archive`

`/opsx:onboard`

按 AI 工具的命令语法

旧版命令

故障排除

“变更未找到”

“无可用制品”

“模式未找到”

命令无法识别

制品未正确生成

下一步