OpenSpec

命令如何工作 ​

首要须知：OpenSpec 有两种命令，它们运行在两个不同的地方。

  • openspec ... 命令在你的终端中运行。（例如：openspec init。）
  • /opsx:... 命令在你的 AI 助手的聊天窗口中运行。（例如：/opsx:propose。）

如果你在终端里输入 /opsx:propose 却发现什么都没有发生，本页就是原因——你找错了 OpenSpec 的那一半。斜杠命令不是终端命令，而是你在 AI 编码助手的同一个聊天框中输入的指令，就像你平时输入「加一个登录表单」一样。

这个区别是新用户最容易绊倒的地方，所以让我们把它彻底讲清楚。

两个半部分 ​

OpenSpec 是一个项目，但戴着两顶帽子。

CLI（终端那一半）。 一个名为 openspec 的程序，你从 shell 中安装并运行它。它用于初始化项目、列出和验证变更、展示仪表盘以及归档已完成的工作。你在 iTerm、VS Code 终端、PowerShell 等任何可以运行 git 或 npm 的地方输入这些命令。

bash
openspec init        # 在此项目中设置 OpenSpec
openspec list        # 查看活跃的变更
openspec view        # 打开交互式仪表盘

斜杠命令（聊天那一半）。 像 /opsx:propose 和 /opsx:apply 这样的简短命令，你可以在 AI 助手中输入。它们指示 AI 遵循 OpenSpec 工作流：起草提案、撰写规约、根据任务清单构建、完成后归档。你在 Claude Code、Cursor、Devin Desktop、Copilot 或其他你使用的助手中输入它们。

text
/opsx:propose add-dark-mode    （在 AI 聊天中输入）
/opsx:apply                     （在 AI 聊天中输入）
/opsx:archive                   （在 AI 聊天中输入）

下面这张图描绘了心智模型：

text
        你的终端                           你的 AI 助手的聊天窗口
   ┌──────────────────────┐               ┌──────────────────────────────┐
   │  $ openspec init     │   安装        │  /opsx:propose add-dark-mode  │
   │  $ openspec list     │  ──────────►  │  /opsx:apply                  │
   │  $ openspec view     │   命令和技能   │  /opsx:archive                │
   └──────────────────────┘               └──────────────────────────────┘
        在这里运行 openspec                      在这里运行 /opsx:*

注意箭头。在终端运行 openspec init 会将斜杠命令安装到你的 AI 工具中。终端那一半负责设置聊天那一半。之后，日常的驱动大多在聊天中完成。

「如何启动交互模式？」 ​

不存在需要单独启动的交互模式。 这个问题经常被问到，所以值得直截了当地回答。

你不需要进入某个特殊的 OpenSpec 模式。像平时一样打开你的 AI 编码助手，然后在聊天框中输入一个斜杠命令。斜杠命令就是你「进入」OpenSpec 的方式。你的助手会识别它，加载匹配的 OpenSpec 技能，然后开始遵循工作流。

所以真正的操作步骤是：

  1. 在你的项目中打开 AI 编码助手（如 Claude Code、Cursor、Devin Desktop 等）。
  2. 在它的聊天框中输入 /opsx:propose，就像输入任何其他请求一样。
  3. 观察自动补全：如果 OpenSpec 已安装，当你输入斜杠时，会看到 /opsx:propose、/opsx:apply 等选项出现。

就是这样。没有需要切换的模式，没有需要启动的后台进程，也没有单独的窗口。

有一个真正交互的东西存在于终端中：openspec view。它会打开一个用于浏览规约和变更的仪表盘。但那是一个查看器，并非你提建议和构建的地方。构建是通过聊天中的斜杠命令完成的。

为什么会有这种分离 ​

这一点值得理解，因为它解释了为什么 OpenSpec 能与 30 多种不同的 AI 工具协同工作。

CLI 是引擎。它了解规则：变更文件夹应该是什么样子、哪些产物依赖于哪些、如何将增量规约合并到你的单一事实来源中。它在每个地方都一样。

斜杠命令是方向盘，而每个 AI 工具的方向盘都略有不同。Claude Code 称它们为命令。Cursor 和 Devin Desktop 有自己的格式。有些工具叫它们技能。当你运行 openspec init 时，OpenSpec 会为你选择的每个工具生成正确类型的文件，因此无论你偏爱哪个助手，/opsx:propose 这一意图都能正常工作。

这种设计的优势在于：你只需学习一次工作流，就可以在工具之间携带。权衡之处是：命令的确切语法在不同工具之间可能略有不同，这正是下一节要讲的内容。

按工具区分斜杠命令语法 ​

意图在所有地方都一样。拼写则取决于你的工具加载的文件。

你的工具的命令文件输入方式示例工具
.../commands/opsx/<id>.*/opsx:proposeClaude Code、Gemini CLI、Crush
.../opsx-<id>.*/opsx-proposeCursor、GitHub Copilot (IDE)、Devin Desktop、Trae、Oh My Pi
.amazonq/prompts/opsx-<id>.md@opsx-proposeAmazon Q Developer
无 — 仅技能/openspec-proposeCodeArts、ForgeCode、Hermes、Mistral Vibe、Zed Agent、共享 .agents
无 — Kimi Code/skill:openspec-proposeKimi Code
无 — Codex CLI$openspec-proposeCodex

Devin 是唯一一个跨两行的工具。Devin Desktop 读取 .devin/workflows/，因此 /opsx-propose 在那里可用；而 Devin Local 不支持，所以在那类代理上需改用 /openspec-propose 技能。OpenSpec 写入 .devin/skills/ 的技能在两者上都有效，这也是它们通过技能名称相互引用的原因。

每种工具都在如何调用中列出 — 那份表格是权威参考。其中有几行根本不是斜杠命令：Amazon Q 将其文件加载到通过 @ 调用的提示库中，而最后三行使用的是技能名称，而不是命令 ID（例如 /opsx:apply 对应的是 openspec-apply-change 技能）。

如有疑问，请查看 openspec init 打印的「入门」提示：它已经使用了你的工具注册的形式。输入斜杠并观察自动补全也有效（对于会显示斜杠命令的工具）。

命令是如何到达的：技能与命令 ​

当你运行 openspec init（或 openspec update）时，OpenSpec 会在你的项目中写入小文件，以便你的 AI 工具能找到工作流。根据你的工具和设置，这些可能是技能、命令，或两者兼有。

  • 技能 位于诸如 .claude/skills/openspec-*/SKILL.md 之类的位置。它们是新兴的跨工具标准：一个包含指令的文件夹，你的助手会自动检测。
  • 命令 位于诸如 .cursor/commands/opsx-<id>.md 或 .claude/commands/opsx/<id>.md 之类的位置 — 布局由工具决定，并决定了你如何输入命令。它们是较早的、为特定工具编写的斜杠命令文件。Codex 不会生成命令文件；请使用 .agents/skills/openspec-*。

你不需要关心你的工具使用哪一种。你只需输入斜杠命令，它就能工作。但了解这些文件的存在有助于在出问题时排查：如果你的命令消失了，通常意味着这些文件缺失或过时了，而 openspec update 会重新生成它们。

有关每个工具的确切路径，请参阅支持的工具；有关技能如何取代旧的仅命令方式，请参阅迁移指南。

确认安装成功 ​

快速检查方法，从快到慢：

  1. 在你的 AI 聊天中输入一个斜杠。 开始输入 /opsx 并观察自动补全建议。如果出现了，就说明你已就绪。对于仅支持技能的工具（Codex、Kimi Code、CodeArts、ForgeCode、Hermes、Mistral Vibe、Zed Agent 或共享 .agents 目标），即使安装正常，/opsx 也不会自动补全 — 请从上表中改用技能名称。
  2. 查看文件。 对于 Claude Code，检查 .claude/skills/ 是否包含 openspec-* 文件夹。其他工具使用自己的目录（支持的工具中列出了它们）。
  3. 重新运行设置。 从你的项目根目录运行 openspec update。这会为你配置的所有工具重新生成技能和命令文件。
  4. 重启你的助手。 许多工具在启动时会扫描技能和命令，因此打开一个新窗口可能是缺失的那一步。

我到底有哪些命令？ ​

默认情况下，OpenSpec 安装核心斜杠命令集：

  • /opsx:explore：在承诺变更之前与 AI 一起思考想法（当你还不确定时，这是很棒的第一步）
  • /opsx:propose：创建变更并一步起草所有规划产物
  • /opsx:apply：通过完成其任务清单来构建变更
  • /opsx:update：修订变更的规划产物并保持它们一致
  • /opsx:sync：将变更的规约更新合并到你的主规约中（通常是自动的）
  • /opsx:archive：完成变更并将其归档

一个不错的默认节律：当你在琢磨要做什么时用 explore，然后依次用 propose、apply、archive。探索优先指南解释了为什么这一步很有价值。

还有一个扩展命令集，适用于希望更精细控制的人（包括 /opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:bulk-archive、/opsx:onboard）。你可以通过 openspec config profile 启用它，然后通过 openspec update 应用。

对这些都不熟悉？/opsx:onboard（在扩展集中）会在你实际的代码库上引导你完成一个完整的变更，并解说每一步。这是最友好的入门方式。

欲知每个命令的详细信息，请参阅命令。关于何时使用哪个命令，请参阅工作流。

一个清晰的首次运行流程 ​

综合来看，以下是完整序列，每一步都标注了发生的地点。

text
终端       $ npm install -g @fission-ai/openspec@latest
终端       $ cd your-project
终端       $ openspec init
              （将斜杠命令安装到你的 AI 工具中）

AI 聊天      /opsx:explore
              （可选：先和 AI 一起构思想法）

AI 聊天      /opsx:propose add-dark-mode
              （AI 起草提案、规约、设计、任务）

AI 聊天      /opsx:apply
              （AI 开始构建，逐项勾选任务）

AI 聊天      /opsx:archive
              （变更合并到你的规约中并归档）

终端两步设置。然后你就活在聊天中了。这就是工作节奏。

相关链接 ​