# https://github.com/Fission-AI/OpenSpec 项目说明书 生成时间：2026-05-13 10:35:14 UTC ## 目录 - [OpenSpec概述](#page-overview) - [安装与初始化](#page-installation) - [系统架构](#page-architecture) - [核心模块详解](#page-core-modules) - [变更工作流](#page-change-workflow) - [工件图系统](#page-artifact-graph) - [AI工具集成](#page-ai-integration) - [CLI命令参考](#page-cli-commands) - [工作流模板](#page-workflow-templates) - [配置系统](#page-configuration) ## OpenSpec概述 ### 相关页面 相关主题：[安装与初始化](#page-installation), [系统架构](#page-architecture), [变更工作流](#page-change-workflow)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) - [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md) - [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md) - [openspec/changes/archive/2026-02-17-merge-init-experimental/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-merge-init-experimental/design.md) - [WORKSPACE_REIMPLEMENTATION_DIRECTION.md](https://github.com/Fission-AI/OpenSpec/blob/main/WORKSPACE_REIMPLEMENTATION_DIRECTION.md)
# OpenSpec概述 ## 简介 OpenSpec 是一个轻量级的规范（Specification）管理框架，专为 AI 编程助手设计。其核心目标是**在编写代码之前让人类和 AI 就需求规范达成一致**，从而提高 AI 代码助手的可预测性和可靠性。 资料来源：[README.md:25-30]() ### 设计理念 | 理念 | 说明 | |------|------| | **Fluid not Rigid** | 灵活而非僵化，随时可更新工件 | | **Iterative not Waterfall** | 迭代而非瀑布式开发 | | **Easy not Complex** | 简单而非复杂 | | **Built for Brownfield not Just Greenfield** | 支持存量项目而非仅支持新项目 | | **Scalable** | 从个人项目到企业级均可使用 | 资料来源：[README.md:72-78]() ## 核心架构 ### 系统组件 ```mermaid graph TD A[用户/AI助手] --> B[OpenSpec CLI] B --> C[Change 目录] C --> D[proposal.md] C --> E[specs/] C --> F[design.md] C --> G[tasks.md] B --> H[Schema 系统] H --> I[模板定义] H --> J[工件序列] ``` ### 工件类型 OpenSpec 使用结构化的工件（Artifact）来组织变更： | 工件 | 文件 | 用途 | |------|------|------| | **Proposal** | `proposal.md` | 说明变更原因和内容 | | **Specs** | `specs/*.md` | 需求和场景定义 | | **Design** | `design.md` | 技术设计方案（可选） | | **Tasks** | `tasks.md` | 实现检查清单 | 资料来源：[README.md:150-165]() ## 工作流程 ### 标准工作流 ```mermaid graph LR A[提出变更] --> B[编写规范] B --> C[设计方案] C --> D[创建任务] D --> E[实施任务] E --> F[归档变更] ``` #### 步骤 1：提出变更 用户通过自然语言或斜杠命令提出变更需求： ``` You: /opsx:propose add-dark-mode AI: Created openspec/changes/add-dark-mode/ ✓ proposal.md — why we're doing this, what's changing ✓ specs/ — requirements and scenarios ✓ design.md — technical approach ✓ tasks.md — implementation checklist ``` 资料来源：[README.md:96-105]() #### 步骤 2：实施任务 规范确认后开始实现： ``` You: The specs look good. Let's implement this change. AI: I'll work through the tasks in the add-profile-filters change. *Implements tasks from openspec/changes/add-profile-filters/tasks.md* ``` 资料来源：[README.md:140-145]() #### 步骤 3：归档变更 实现完成后归档变更： ```bash openspec archive add-profile-filters --yes ``` 归档后的变更会被移至 `openspec/changes/archive/-/` 目录。 ### 实验性工作流 (/opsx) 新版实验性工作流提供更简化的命令： | 命令 | 功能 | |------|------| | `/opsx:propose` | 创建新变更 | | `/opsx:continue` | 继续下一个工件 | | `/opsx:ff` | 快进到完成 | | `/opsx:verify` | 验证工件 | | `/opsx:bulk-archive` | 批量归档 | | `/opsx:onboard` | 新项目引导 | 启用方式：`openspec experimental` 资料来源：[README.md:85-92]() ## 支持的工具 ### 原生斜杠命令支持 | 工具 | 命令格式 | 配置目录 | |------|----------|----------| | **Claude Code** | `/openspec:propose`, `/openspec:apply`, `/openspec:archive` | 内置支持 | | **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.amazonq/prompts/` | | **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` | | **CodeBuddy Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.codebuddy/commands/` | | **Cline** | Workflows | `.clinerules/workflows/openspec-*.md` | | **Kilo Code** | `/openspec-proposal.md` 等 | `.kilocode/workflows/` | | **Windsurf** | `/openspec-proposal` 等 | `.windsurf/workflows/` | 资料来源：[README.md:40-70]() ### AGENTS.md 兼容工具 以下工具通过读取 `openspec/AGENTS.md` 自动发现工作流程： - Amp - Jules - 其他支持 AGENTS.md 约定的工具 ## 安装与配置 ### 系统要求 - **Node.js**: >= 20.19.0 资料来源：[README.md:107-108]() ### 安装步骤 #### 方式 A：npm 全局安装 ```bash npm install -g @fission-ai/openspec@latest ``` 验证安装： ```bash openspec --version ``` #### 方式 B：Nix 安装 ```bash # 直接运行 nix run github:Fission-AI/OpenSpec -- init # 安装到用户 profile nix profile install github:Fission-AI/OpenSpec ``` #### 方式 C：pnpm/yarn/bun OpenSpec 同时支持 pnpm、yarn、bun 等包管理器。 资料来源：[README.md:110-125]() ### 初始化项目 ```bash cd your-project openspec init ``` 初始化后会创建基础目录结构： ``` openspec/ ├── config.yaml # 项目配置 ├── specs/ # 规范源文件 │ └── / │ └── spec.md └── changes/ # 变更目录 ``` ## CLI 命令参考 | 命令 | 功能 | |------|------| | `openspec init` | 初始化 OpenSpec | | `openspec list` | 查看活跃变更 | | `openspec view` | 交互式仪表板 | | `openspec show ` | 显示变更详情 | | `openspec validate ` | 检查规范格式 | | `openspec archive [--yes]` | 归档完成变更 | | `openspec config profile` | 选择工作流配置 | | `openspec update` | 更新配置文件 | | `openspec experimental` | 启用实验性功能 | 资料来源：[README.md:155-165]() ## 项目配置 ### config.yaml 结构 ```yaml context: | # 项目上下文信息 # 将自动注入到所有工件中 rules: proposal: - 遵循简洁原则 specs: - 使用 WHEN/THEN 格式 ``` ### 上下文注入 ```bash openspec instructions specs --change my-feature ``` 输出包含： ```markdown [项目上下文] - 特定工件的规则 ``` 资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md:15-35]() ## 规范格式 ### 需求格式 ```markdown ### Requirement: <需求名称> 系统应该在特定条件下执行特定行为。 #### Scenario: <场景名称> - **WHEN** <触发条件> - **THEN** <预期结果> ``` **格式要求**： - 使用 SHALL/MUST 表示规范性需求 - 场景标题必须使用 4 个 `#` (`####`) - 每个需求必须至少包含一个场景 资料来源：[schemas/spec-driven/schema.yaml:1-25]() ### MODIFIED 需求工作流 修改现有需求时： 1. 在原规范文件中定位需求 2. 复制完整需求块 3. 粘贴到 `## MODIFIED Requirements` 下 4. 编辑以反映新行为 ```markdown ## MODIFIED Requirements ### Requirement: User can export data The system SHALL allow users to export their data in CSV format. #### Scenario: Successful export - **WHEN** user clicks "Export" button - **THEN** system downloads a CSV file ``` ## 变更目录结构 ### AI 创建的文件结构 ``` openspec/ ├── specs/ │ └── auth/ │ └── spec.md # 当前规范（源） └── changes/ └── add-2fa/ # 变更目录 ├── proposal.md # 变更原因 ├── tasks.md # 实现检查清单 ├── design.md # 技术决策（可选） └── specs/ └── auth/ └── spec.md # 增量规范 ``` 资料来源：[README.md:150-165]() ## 遥测与隐私 OpenSpec 收集**匿名使用统计**（可选退出）： - 仅收集命令名称和版本 - 不收集参数、路径、内容或 PII - CI 环境中自动禁用 **退出方式**： ```bash export OPENSPEC_TELEMETRY=0 # 或 export DO_NOT_TRACK=1 ``` ## 开发指南 ### 本地开发 ```bash # 安装依赖 pnpm install # 构建 pnpm run build # 测试 pnpm test # 开发 CLI pnpm run dev # 或 pnpm run dev:cli # 提交规范 git commit -m "type(scope): subject" ``` 资料来源：[README.md:190-196]() ## 工作空间功能 ### 多仓库支持 OpenSpec 支持跨多个仓库的工作空间管理： ```bash openspec workspace explore ``` ### 状态查询 ```bash openspec status openspec status --change integrate-docs ``` 输出示例： ``` Change: integrate-docs Scope: openspec, landing Proposal: present Design: present Tasks: present Ready for apply: yes/no ``` 状态检查会捕获结构性问题： - `specs/` 下未知的仓库文件夹 - 缺失的任务文件 - 未确认的受影响仓库 - 缺失的仓库链接或路径 资料来源：[WORKSPACE_REIMPLEMENTATION_DIRECTION.md:1-50]() ## 总结 OpenSpec 提供了一个轻量级但结构化的规范管理框架，其核心价值在于： 1. **前置对齐**：在编码前达成共识 2. **组织化**：每个变更都有独立文件夹 3. **灵活性**：可随时更新工件，无需僵化的阶段门控 4. **工具兼容性**：支持 25+ AI 编程助手 无论是个人项目还是企业级开发，OpenSpec 都能帮助团队更高效、更可靠地进行 AI 辅助开发。 --- ## 安装与初始化 ### 相关页面 相关主题：[OpenSpec概述](#page-overview), [CLI命令参考](#page-cli-commands)
相关源码文件 以下源码文件用于生成本页说明： - [docs/installation.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/installation.md) - [docs/getting-started.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md) - [docs/cli.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md) - [src/core/init.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/init.ts) - [src/core/update.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/update.ts) - [package.json](https://github.com/Fission-AI/OpenSpec/blob/main/package.json) - [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)
# 安装与初始化 ## 概述 OpenSpec 是一个基于 AI 的规范框架，用于在 AI 编码助手项目中建立结构化的变更管理流程。安装与初始化是用户首次使用 OpenSpec 的关键步骤，涉及 CLI 工具安装、项目目录配置、配置文件生成以及与 AI 工具的集成设置。 本章节详细说明 OpenSpec 的各种安装方式、系统要求、初始化流程以及配置选项，帮助用户快速上手并在团队中推广使用。 ## 系统要求 | 要求项 | 最低版本 | 说明 | |--------|----------|------| | Node.js | 20.19.0 | 核心运行时环境 | | 包管理器 | npm/pnpm/yarn/bun/nix | 任选其一 | | 操作系统 |跨平台 | Linux、macOS、Windows | 资料来源：[README.md:67](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ## 安装方式 ### npm 全局安装 通过 npm 将 OpenSpec 安装为全局 CLI 工具： ```bash npm install -g @fission-ai/openspec@latest ``` 安装完成后验证版本： ```bash openspec --version ``` 资料来源：[README.md:69-75](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ### pnpm 安装 ```bash pnpm add -g @fission-ai/openspec ``` ### yarn 安装 ```bash yarn global add @fission-ai/openspec ``` ### bun 安装 ```bash bun add -g @fission-ai/openspec ``` 资料来源：[README.md:56](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ### Nix 安装（无安装方式） 对于使用 Nix 或 NixOS 的用户，可以直接运行而不安装： ```bash nix run github:Fission-AI/OpenSpec -- init ``` 或安装到用户 profile： ```bash nix profile install github:Fission-AI/OpenSpec ``` 或添加到 `flake.nix` 的 inputs 中： ```nix inputs.openspec.url = "github:Fission-AI/OpenSpec"; ``` 资料来源：[README.md:80-91](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ## 项目初始化流程 ### 基本初始化 初始化是创建 OpenSpec 项目结构的核心步骤。在项目根目录下运行： ```bash cd your-project openspec init ``` 该命令会创建以下目录结构： ``` project-root/ ├── openspec/ │ ├── config.yaml # 项目配置文件 │ ├── specs/ # 规范文件目录 │ │ └── / │ │ └── spec.md │ ├── AGENTS.md # AI 代理指令文件 │ └── changes/ # 变更记录目录 └── .openspec/ # 内部状态目录 ``` ### 交互式初始化选项 初始化过程支持多种命令行参数： | 参数 | 说明 | 使用场景 | |------|------|----------| | `--yes` | 接受所有默认值，无需交互确认 | 自动化脚本、CI 环境 | | `--no-input` | 跳过所有提示，使用命令行参数 | 无人值守安装 | | `--force` | 强制覆盖已存在的 OpenSpec 目录 | 重新初始化 | | `--dry-run` | 预览将要创建的内容，不实际写入 | 测试配置 | 资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-08-06-add-init-command/design.md) ### 初始化事务机制 OpenSpec 使用原子化目录创建机制，包含事务回滚功能： ```typescript interface InitTransaction { createdPaths: string[]; rollback(): Promise; commit(): Promise; } ``` **事务保障**： - 如果创建过程中失败，已创建的文件会被回滚清除 - 防止部分安装导致的脏状态 - 确保初始化要么完全成功，要么完全回滚 资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:28-35](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-08-06-add-init-command/design.md) ## 项目配置 ### config.yaml 结构 初始化后生成的 `openspec/config.yaml` 是项目的核心配置文件： ```yaml schema: spec-driven context: projectName: "My Project" techStack: [] conventions: "" rules: {} ``` ### 配置字段说明 | 字段 | 类型 | 说明 | |------|------|------| | `schema` | string | 使用的 schema 名称，默认为 `spec-driven` | | `context.projectName` | string | 项目名称 | | `context.techStack` | string[] | 技术栈列表 | | `context.conventions` | string | 项目约定和规范 | | `rules` | object | 按 artifact 类型定义的规则 | 资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md) ### 动态指令系统 新版本 OpenSpec 采用三层指令架构： ```mermaid graph TD A[用户运行命令] --> B[Context 上下文层] A --> C[Rules 规则层] A --> D[Template 模板层] B --> E[config.yaml 项目背景] C --> F[Artifact-specific 约束] D --> G[Schema 定义的模板] E --> H[CLI 动态组装] F --> H G --> H H --> I[AI 接收实时指令] ``` **三层职责**： 1. **Context（上下文）**：从 `config.yaml` 读取项目背景信息 2. **Rules（规则）**：Artifact 特定的约束条件 3. **Template（模板）**：Schema 定义的输出文件结构 资料来源：[CHANGELOG.md:15-30](https://github.com/Fission-AI/OpenSpec/blob/main/CHANGELOG.md) ## Schema 管理 ### Schema 加载优先级 OpenSpec 按以下顺序查找 Schema： | 优先级 | 位置 | 说明 | |--------|------|------| | 1 | `project/openspec/schemas//` | 项目本地自定义 | | 2 | `~/.local/share/openspec/schemas//` | 用户级别覆盖 | | 3 | `@fission-ai/openspec/schemas//` | 包内置（最低优先级） | 项目本地的 Schema 会覆盖同名的内置 Schema，实现团队定制化。 资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md) ### 查看可用 Schema ```bash openspec schemas ``` 输出示例： ``` Available schemas: - spec-driven (built-in) - custom-schema (project) ``` ## 更新与维护 ### 升级 CLI ```bash npm update -g @fission-ai/openspec ``` ### 更新项目配置 当 OpenSpec 发布新版本或项目结构需要同步时： ```bash openspec update ``` 更新操作会： - 刷新 `openspec/AGENTS.md` 文件 - 更新现有 artifact 模板 - 清理过时的配置文件 ### 切换实验性工作流 新版 OpenSpec 引入了基于 artifact 的实验性工作流： ```bash openspec experimental ``` 实验性工作流提供以下命令： | 命令 | 功能 | |------|------| | `/opsx:propose` | 创建新的变更提案 | | `/opsx:new` | 启动新变更 | | `/opsx:continue` | 逐步创建 artifact | | `/opsx:ff` | 快速推进变更 | | `/opsx:verify` | 验证变更完整性 | | `/opsx:bulk-archive` | 批量归档变更 | | `/opsx:onboard` | 新成员引导 | 资料来源：[README.md:55-60](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ### 配置文件选择 查看当前使用的配置文件类型： ```bash openspec config profile ``` 可选配置文件类型： - **旧版配置**：生成 CLAUDE.md、.cursorrules 等工具配置文件 - **新版配置**：使用 openspec/AGENTS.md 和 config.yaml 资料来源：[README.md:50-55](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ## 与 AI 工具集成 ### 支持的工具类型 | 集成类型 | 工具示例 | 配置方式 | |----------|----------|----------| | 原生斜杠命令 | Claude Code, CodeBuddy | 内置支持 | | 配置文件 | Cursor, Windsurf | 生成 .cursorrules 等 | | 工作流文件 | Cline, Kilo Code | 生成 .clinerules 等 | ### 主要支持的 AI 助手 | 工具 | 命令格式 | 配置目录 | |------|----------|----------| | Claude Code | `/openspec:propose`, `/openspec:apply`, `/openspec:archive` | 内置 | | Amazon Q Developer | `@openspec-proposal`, `@openspec-apply` | `.amazonq/prompts/` | | Cursor | 斜杠命令 | `.cursor/rules/` | | CodeBuddy | `/openspec:proposal` | `.codebuddy/commands/` | | Cline | 配置文件方式 | `.clinerules/workflows/` | 资料来源：[README.md:99-130](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ## 安全性与最佳实践 ### 安全考量 1. **路径遍历防护**：所有用户提供的路径都经过清理验证 2. **文件权限检查**：写入前验证目录权限 3. **现有文件保护**：未使用 `--force` 不会覆盖已有文件 4. **模板注入防护**：用户输入在模板中被清理 ### 遥测数据收集 OpenSpec 默认收集匿名使用统计： - 仅收集命令名称和版本号 - 不收集参数、路径、内容或个人信息 - CI 环境中自动禁用 **禁用遥测**： ```bash export OPENSPEC_TELEMETRY=0 # 或 export DO_NOT_TRACK=1 ``` 资料来源：[README.md:60-67](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ## 快速入门工作流 ```mermaid graph LR A[安装 CLI] --> B[初始化项目] B --> C[运行 openspec init] C --> D[配置 AI 助手] D --> E[使用 /opsx:propose 开始] E --> F[创建提案] F --> G[实现任务] G --> H[归档变更] ``` **标准快速入门步骤**： 1. 安装 OpenSpec：`npm install -g @fission-ai/openspec@latest` 2. 进入项目目录：`cd your-project` 3. 初始化：`openspec init` 4. 向 AI 助手发送指令：`/opsx:propose <你想要构建的功能>` 资料来源：[README.md:68-78](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ## 常见问题 ### Q: Node.js 版本不满足要求 ```bash # 检查版本 node --version # 使用 nvm 升级 nvm install 20.19.0 nvm use 20.19.0 ``` ### Q: 初始化失败权限错误 ```bash # 检查目录权限 ls -la # 使用 sudo（不推荐） sudo openspec init ``` ### Q: 想使用实验性工作流 ```bash openspec experimental ``` ### Q: 想要查看所有可用命令 ```bash openspec --help ``` ## 贡献开发 如需为 OpenSpec 贡献代码： ```bash # 克隆仓库 git clone https://github.com/Fission-AI/OpenSpec.git cd OpenSpec # 安装依赖 pnpm install # 构建项目 pnpm run build # 运行测试 pnpm test # 本地开发 CLI pnpm run dev # 或 pnpm run dev:cli ``` 提交代码使用 conventional commits 格式：`type(scope): subject` 资料来源：[README.md:145-150](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) --- ## 系统架构 ### 相关页面 相关主题：[核心模块详解](#page-core-modules), [AI工具集成](#page-ai-integration), [工件图系统](#page-artifact-graph)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) - [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md) - [openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md) - [openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md) - [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md) - [openspec/changes/archive/2025-08-06-add-init-command/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-08-06-add-init-command/design.md) - [schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)
# 系统架构 ## 概述 OpenSpec 是一个轻量级的规范框架，专为 AI 编程助手设计。其核心目标是让人类开发者和 AI 在编写代码之前先就规范达成共识，从而提高代码质量和项目可预测性。 **技术栈要求：** - Node.js 20.19.0 或更高版本 - 支持 pnpm、yarn、bun、nix 等包管理器 资料来源：[README.md:1]() ## 核心架构分层 OpenSpec 采用分层架构设计，主要分为以下几层： | 层级 | 职责 | 关键模块 | |------|------|----------| | CLI 层 | 命令行接口，接收用户指令 | 主入口、命令解析 | | 核心层 | 业务逻辑处理 | 模式管理、工件图、模板系统 | | 适配层 | 工具集成 | 斜杠命令生成、工具适配器 | ```mermaid graph TD A[用户/AI 助手] --> B[CLI 交互层] B --> C[核心业务层] C --> D[Schema 管理] C --> E[工件图引擎] C --> F[模板系统] D --> G[文件系统] E --> G F --> G ``` 资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:1]() ## Schema 系统 ### Schema 分层结构 OpenSpec 采用三级 Schema 存储策略，优先级从高到低： ```mermaid graph TD A[Schema 解析请求] --> B{检查项目目录} B -->|存在| C[openspec/schemas/] B -->|不存在| D{检查用户目录} D -->|存在| E[~/.local/share/openspec/schemas/] D -->|不存在| F[npm 包内置 schemas/] ``` | 层级 | 路径 | 说明 | |------|------|------| | 项目级 | `/openspec/schemas//` | 项目本地自定义模式 | | 用户级 | `~/.local/share/openspec/schemas//` | 用户级别的覆盖配置 | | 包级 | `/schemas//` | 包内置默认模式 | **优先级规则：** 当项目本地 schema 与内置 schema 名称相同时，项目本地版本优先。 资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md:3]() ### Schema 解析顺序 工件 Schema 的解析遵循明确的优先级顺序： 1. `--schema` CLI 参数（显式覆盖） 2. `openspec/changes//.openspec.yaml`（变更级别绑定） 3. `openspec/config.yaml` 的 schema 字段（项目默认） 4. `"spec-driven"`（硬编码回退值） 资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:4]() ## 工件图系统 ### 工件类型 OpenSpec 定义了标准化工件类型，每个变更包含以下工件： | 工件 ID | 生成文件 | 依赖 | 说明 | |---------|----------|------|------| | proposal | proposal.md | 无 | 变更提案和动机 | | specs | specs/*.md | proposal | 需求规格说明 | | design | design.md | proposal, specs | 技术设计方案 | | tasks | tasks.md | specs, design | 实施任务清单 | | apply | - | 所有工件 | 应用/执行指令 | 资料来源：[schemas/spec-driven/schema.yaml:1]() ### 工件状态追踪 工件图引擎负责追踪每个工件的状态，状态包括： - **ready**：可以开始创建 - **blocked**：等待前置依赖完成 - **done**：已完成 ```mermaid graph LR A[proposal] --> B[specs] B --> C[design] C --> D[tasks] D --> E[apply] A --> C B --> D ``` 资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:5]() ### 指令加载机制 指令加载器负责组装动态指令，包含三个层次： 1. **Context（上下文）**：来自 `config.yaml` 的项目背景信息 2. **Rules（规则）**：工件特定的约束条件 3. **Template（模板）**：输出文件的实际结构 ```typescript // 指令组装流程 let enrichedInstruction = ''; // 添加上下文（所有工件） if (projectConfig?.context) { enrichedInstruction += `\n${projectConfig.context}\n\n\n`; } // 添加规则（仅限匹配的工件） const rulesForArtifact = projectConfig?.rules?.[artifactId]; if (rulesForArtifact) { enrichedInstruction += `\n${rulesForArtifact.join('\n')}\n\n\n`; } // 添加原始模板 enrichedInstruction += ``; ``` 资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:1]() ## 命令生成系统 ### 斜杠命令架构 OpenSpec 通过适配器模式支持 25+ AI 工具的斜杠命令： ```mermaid graph TD A[TemplateManager] --> B[SlashCommandConfigurator] B --> C[Claude Code 适配器] B --> D[Cursor 适配器] B --> E[Codex 适配器] B --> F[其他工具适配器...] C --> G[.claude/commands/openspec/] D --> H[.cursor/commands/] E --> I[项目配置] ``` **命令命名约定：** - Claude Code：使用命名空间 `/openspec/proposal`、`/openspec/apply` - Cursor：使用扁平命名 `/openspec-proposal` 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1]() ### 文件标记规范 斜杠命令文件必须包含特定标记以确保可被正确识别和更新： ```markdown --- # Frontmatter（工具特定配置） --- ...命令正文内容... ``` **关键规则：** - 标记仅包裹 Markdown 正文内容 - Frontmatter 必须位于标记之前 - 避免在 YAML 块内插入标记 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1]() ## 模板系统 ### 模板存储结构 模板采用 Markdown 格式存储，结构清晰： ```markdown --- change: artifact: schema: output: --- ## Dependencies - [x] (依赖列表) ## Next Steps 下一步操作说明 --- [原始模板内容...] ``` 资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:4]() ### 模板引擎特点 | 特性 | 说明 | |------|------| | 无需模板引擎 | 使用简单字符串拼接 | | 上下文注入 | 在模板前添加上下文信息 | | 清晰分隔 | 保持模板和注入内容的边界 | 资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:4]() ## 工作流系统 ### 标准工作流程 ```mermaid graph TD A[/opsx:propose] --> B[创建提案] B --> C[/opsx:continue] C --> D[创建 specs] D --> E[创建 design] E --> F[创建 tasks] F --> G[/opsx:apply] G --> H[执行任务] H --> I[/opsx:archive] I --> J[归档到 archive/] ``` ### 动作命令映射 | 命令 | 功能 | |------|------| | `/opsx:explore` | 在提交变更前思考和探索想法 | | `/opsx:new` | 开始一个新变更 | | `/opsx:continue` | 逐步创建工件（单步式） | | `/opsx:propose` | 创建完整的变更结构 | | `/opsx:ff` | 快进到下一个待处理的工件 | | `/opsx:verify` | 验证变更状态 | | `/opsx:bulk-archive` | 批量归档 | | `/opsx:onboard` | 新项目引导 | | `/opsx:archive` | 归档已完成的工作 | 资料来源：[README.md:1]() ## 项目配置 ### config.yaml 结构 ```yaml context: | Tech stack: TypeScript, React 项目约定: ... schema: spec-driven # 默认 schema 名称 rules: proposal: # 提案工件规则 - Include risk assessment specs: # 规格工件规则 - Use Given/When/Then format ``` ### 配置注入格式 OpenSpec 使用 XML 风格的标签进行配置注入： ```xml 技术栈: TypeScript, React - Include rollback plan ``` **设计决策：** - 使用 XML 标签避免与 Markdown 内容冲突 - 便于 AI 代理解析结构 - 与代码库中特殊部分现有模式匹配 资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:3]() ## 变更目录结构 每个变更创建独立的文件夹结构： ``` openspec/ ├── config.yaml # 项目配置 ├── changes/ │ ├── / │ │ ├── .openspec.yaml # 变更级别 schema 绑定 │ │ ├── proposal.md # 提案文档 │ │ ├── specs/ # 规格文档目录 │ │ │ └── *.md │ │ ├── design.md # 设计文档 │ │ └── tasks.md # 任务清单 │ └── archive/ # 归档目录 │ └── YYYY-MM-DD-/ └── schemas/ # 项目本地 schemas └── / ``` **设计原则：** - 每个变更独立存放，职责清晰 - 归档保留历史版本 - 镜像 `.github/` 目录结构 资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md:2]() ## CLI 命令参考 ### 核心命令 | 命令 | 说明 | |------|------| | `openspec init` | 初始化项目 | | `openspec list` | 列出活跃变更 | | `openspec show ` | 显示变更详情 | | `openspec view` | 交互式仪表板 | | `openspec archive ` | 归档变更 | | `openspec config profile` | 配置工作流配置 | | `openspec experimental` | 启用实验性功能 | | `openspec instructions ` | 获取工件指令 | | `openspec schemas` | 管理 schemas | ### Schema 管理命令 | 命令 | 说明 | |------|------| | `openspec schema init ` | 创建新 schema | | `openspec schema which` | 显示当前 schema | | `openspec schema fork ` | 派生现有 schema | 资料来源：[README.md:1]() ## 安全与验证 ### 路径遍历防护 所有用户提供的路径必须经过清理，防止路径遍历攻击。 ```typescript // 安全检查清单 - 检查文件写入权限 - 不使用 --force 标志不覆盖现有文件 - 清理模板中的用户输入 ``` ### 初始化事务处理 ```typescript interface InitTransaction { createdPaths: string[]; rollback(): Promise; // 失败时回滚 commit(): Promise; // 成功时提交 } ``` **设计目标：** - 防止部分安装 - 清晰的错误状态 - 更好的用户体验 资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:1]() ## 扩展性设计 ### 社区 Schema OpenSpec 支持第三方 Schema 包分发，类似于 `github/spec-kit` 的扩展目录模式： ```bash # 第三方 Schema 仓库结构 / ├── schemas/ │ └── / │ ├── schema.yaml │ └── templates/ └── README.md ``` ### 适配器扩展 新增工具支持只需实现适配器接口： ```typescript interface ToolAdapter { getTargets(): Array<{ path: string; kind: 'slash'; id: string }>; generateAll(projectPath: string, openspecDir: string): void; updateExisting(projectPath: string, openspecDir: string): void; } ``` 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1]() ## 贡献指南 | 操作 | 命令 | |------|------| | 安装依赖 | `pnpm install` | | 构建 | `pnpm run build` | | 测试 | `pnpm test` | | 本地开发 CLI | `pnpm run dev` 或 `pnpm run dev:cli` | | 提交规范 | 常规提交格式：`type(scope): subject` | 资料来源：[README.md:1]() --- ## 核心模块详解 ### 相关页面 相关主题：[系统架构](#page-architecture), [变更工作流](#page-change-workflow)
相关源码文件 以下源码文件用于生成本页说明： - [src/core/artifact-graph/types.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/types.ts) - [src/core/artifact-graph/schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/schema.ts) - [src/core/artifact-graph/graph.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/graph.ts) - [src/core/artifact-graph/state.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/state.ts) - [src/core/artifact-graph/template.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/template.ts) - [src/core/artifact-graph/context.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/context.ts) - [src/core/artifact-graph/instructions.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/instructions.ts) - [schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)
# 核心模块详解 ## 概述 OpenSpec 的核心模块围绕**变更工件图（Artifact Graph）** 构建，提供了从规范定义、工件管理到指令生成的完整技术栈。核心模块采用 TypeScript/Zod 实现类型安全，使用 YAML 定义规范结构，通过模块化设计支持多 schema 扩展。 核心模块的架构设计遵循以下原则： - **无模板引擎依赖**：使用简单的字符串拼接实现上下文注入 - **Schema 驱动的资源解析**：支持项目级、用户级、包级三层 Schema 解析顺序 - **动态状态检测**：基于工件文件存在性自动判断阻塞状态 - **Zod Schema 验证**：运行时类型检查确保数据完整性 资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md]() ## 核心模块架构 ### 模块目录结构 ``` src/core/artifact-graph/ ├── index.ts # 模块导出入口 ├── types.ts # 类型定义（Zod Schema） ├── schema.ts # Schema YAML 解析器 ├── graph.ts # 工件图与拓扑排序 ├── state.ts # 状态检测逻辑 ├── template.ts # 模板加载器 ├── context.ts # ChangeContext 加载器 └── instructions.ts # 指令丰富化与格式化 ``` ### 核心组件关系图 ```mermaid graph TD A[Schema.yaml] -->|解析| B[ArtifactGraph] B -->|拓扑排序| C[getBuildOrder] B -->|状态检测| D[State Detection] D --> E{工件状态} F[Change Context] -->|注入| G[Instructions] H[Project Config] -->|上下文| G I[Template] -->|内容| G E -->|done/ready/blocked| J[Status Output] G -->|富化指令| K[Agent Output] ``` ## Schema 系统 ### Schema 解析层级 OpenSpec 采用三级 Schema 解析顺序，从高优先级到低优先级排列： | 优先级 | 来源 | 路径 | |--------|------|------| | 1 (最高) | 项目本地覆盖 | `/openspec/schemas//` | | 2 | 用户配置 | `~/.local/share/openspec/schemas//` | | 3 (最低) | 包内置 | `/schemas//` | 资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md]() ### 工件依赖模型 每个 Schema 定义一组工件及其依赖关系： ```yaml name: spec-driven version: 1 artifacts: - id: proposal generates: "proposal.md" template: "proposal.md" requires: [] - id: specs generates: "specs/*.md" template: "specs.md" requires: - proposal - id: design generates: "design.md" template: "design.md" requires: - proposal - specs - id: tasks generates: "tasks.md" template: "tasks.md" requires: - specs - design ``` 资料来源：[schemas/spec-driven/schema.yaml]() ## 类型系统 ### 核心类型定义 `types.ts` 使用 Zod 定义所有类型约束： ```typescript // 工件定义 Schema const ArtifactSchema = z.object({ id: z.string(), generates: z.string(), template: z.string(), requires: z.array(z.string()), }); // Schema YAML 主结构 const SchemaYamlSchema = z.object({ name: z.string(), version: z.number(), artifacts: z.array(ArtifactSchema), }); ``` ### 运行时状态类型 | 类型名 | 描述 | 结构 | |--------|------|------| | `CompletedSet` | 已完成工件集合 | `Set` | | `BlockedArtifacts` | 阻塞中的工件映射 | `Record` | | `ArtifactGraphResult` | 图操作返回结果 | 包含 `graph`、`buildOrder`、`artifacts` | 资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md]() ## 工件图核心 ### ArtifactGraph 类 工件图类封装所有图相关操作： ```typescript export class ArtifactGraph { // 从 YAML 文件加载 static fromYaml(path: string): ArtifactGraph; // 获取拓扑排序后的构建顺序 getBuildOrder(): string[]; // 获取单个工件定义 getArtifact(id: string): ArtifactSchema | undefined; // 列出所有工件 getAllArtifacts(): ArtifactSchema[]; } ``` ### 拓扑排序算法 使用 Kahn 算法实现拓扑排序： ```mermaid graph LR A[proposal] --> B[specs] A --> C[design] B --> D[tasks] C --> D E[Kahn排序] --> F[proposal] F --> G[specs/design] G --> H[tasks] ``` **排序特性**： - 保证依赖永远在被依赖项之前 - 循环依赖检测：`"Cyclic dependency detected: A → B → C → A"` - 无环图验证 资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md]() ## Schema 解析器 ### schema.ts 功能 | 功能 | 描述 | |------|------| | YAML 加载 | 使用 `fs.readFileSync` 读取并 `yaml.parse` | | Zod 验证 | `.safeParse()` 验证结构 | | 依赖引用验证 | 确保 `requires` 引用有效 artifact ID | | 重复 ID 检测 | 拒绝重复的 artifact ID | | 循环依赖检测 | 构建依赖图时检测环 | ### 验证规则 ```typescript // 依赖引用验证伪代码 for (const artifact of artifacts) { for (const reqId of artifact.requires) { if (!artifacts.find(a => a.id === reqId)) { throw new Error(`Invalid reference: ${artifact.id} requires ${reqId}`); } } } ``` ## 状态检测系统 ### 状态枚举 | 状态 | 含义 | 触发条件 | |------|------|----------| | `done` | 已完成 | 工件文件存在 | | `ready` | 就绪可创建 | 所有依赖均为 `done` | | `blocked` | 阻塞 | 至少一个依赖为 `blocked` 或不存在 | ### 状态输出格式 ```markdown ## Change: add-auth (spec-driven) | Artifact | Status | Output | |----------|--------|--------| | proposal | done | proposal.md | | specs | ready | specs/*.md | | design | blocked (needs: proposal) | design.md | | tasks | blocked (needs: specs, design) | tasks.md | ``` 资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md]() ## 指令加载系统 ### 指令生成流程 ```mermaid graph TD A[loadInstructions] --> B[resolveSchema] B --> C[loadTemplate] C --> D[loadChangeContext] D --> E[loadProjectConfig] E --> F[injectContext] F --> G[injectRules] G --> H[formatXML] H --> I[返回富化指令] ``` ### 上下文注入格式 ```xml Tech stack: TypeScript, React Project conventions: ... - Use Given/When/Then format for scenarios - Reference existing patterns before inventing new ones ``` ### 指令丰富化逻辑 | 组件 | 注入位置 | 条件 | |------|----------|------| | `context` | 所有工件 | `projectConfig.context` 存在 | | `rules` | 特定工件 | `projectConfig.rules[artifactId]` 存在 | | `template` | 所有工件 | 始终 | 资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md]() ## 包路径解析 ### 跨环境路径解析 ```typescript function getPackageSchemasDir(): string { const currentFile = fileURLToPath(import.meta.url); // 从 src/core/artifact-graph/ 导航到包根目录 return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas'); } ``` **设计决策**： - 使用 `import.meta.url` 而非硬编码路径 - 适配 ESM 模块系统 - 相对路径计算确保包内引用正确 ## 项目配置集成 ### 配置 Schema 验证 项目配置文件 `openspec/config.yaml` 结构： ```yaml schema: spec-driven # 默认 schema context: | # 注入到所有工件的上下文 Tech stack: TypeScript Database: PostgreSQL rules: # 规则（按工件 ID） specs: - Use Given/When/Then format design: - Include rollback plan ``` ### Schema 解析优先级 ``` 1. --schema CLI 参数 (最高优先级) 2. .openspec.yaml (change 目录内) 3. openspec/config.yaml schema 字段 4. "spec-driven" (硬编码默认值) ``` ## Schema 解析器详情 ### schema.ts 核心实现 | 功能点 | 实现方式 | |--------|----------| | YAML 解析 | `yaml.parse(content)` | | 类型验证 | Zod `.safeParse()` | | 错误处理 | 自定义错误消息 | | 文件缓存 | 可选内存缓存 | ### 循环依赖检测算法 ```typescript function detectCycles(artifacts: Artifact[]): string[] | null { const visited = new Set(); const recursionStack = new Set(); for (const artifact of artifacts) { if (hasCycle(artifact.id, artifacts, visited, recursionStack)) { return buildCyclePath(recursionStack); } } return null; } ``` ## 状态检测实现 ### state.ts 文件结构 ```typescript // 状态检测核心逻辑 export interface StateDetectionResult { completed: CompletedSet; blocked: BlockedArtifacts; ready: string[]; } // 文件存在性检查 function checkArtifactExists(artifact: Artifact, changeDir: string): boolean { const path = path.join(changeDir, artifact.generates); return fs.existsSync(path); } ``` ### 状态计算伪代码 ```typescript function detectState(graph: ArtifactGraph, changeDir: string): StateResult { const completed = new Set(); const blocked: Record = {}; const ready: string[] = []; for (const artifact of graph.getAllArtifacts()) { if (fileExists(artifact, changeDir)) { completed.add(artifact.id); } else if (canBuild(artifact, completed)) { ready.push(artifact.id); } else { blocked[artifact.id] = getMissingDeps(artifact, completed); } } return { completed, blocked, ready }; } ``` ## Apply 阶段支持 ### ApplyPhase Schema 扩展 ```yaml artifacts: - id: proposal # ... apply: requires: - proposal - specs - design - tasks tracks: progress instruction: "All artifacts complete. Proceed with implementation." ``` ### 动态工件检测 与硬编码路径不同，Apply 指令检查逻辑： ```typescript // 从 schema 加载要求，而非硬编码 const schema = await resolveSchema(schemaName); const applyConfig = schema.apply; // 动态检查所有要求的工件 for (const requiredId of applyConfig.requires) { if (!completed.has(requiredId)) { return { ready: false, missing: requiredId }; } } ``` ## 最佳实践 ### Schema 设计原则 1. **最小依赖**：每个工件只依赖真正需要的前置项 2. **清晰命名**：artifact ID 使用 kebab-case 3. **模板分离**：每个 schema 拥有独立的 `templates/` 目录 4. **版本控制**：schema.yaml 包含 version 字段便于迁移 ### 指令注入最佳实践 | 场景 | 推荐做法 | |------|----------| | 项目级上下文 | 放在 `config.yaml.context` | | 工件特定规则 | 使用 `config.yaml.rules[artifactId]` | | 变更描述 | 使用 ChangeContext 文件 | | 避免冲突 | 使用 XML 标签 `` 而非 Markdown 标题 | ### 错误处理 | 错误类型 | 处理方式 | |----------|----------| | Schema 未找到 | 按优先级继续搜索下一级 | | YAML 解析失败 | 显示具体行号和错误 | | 循环依赖 | 终止并显示环路径 | | 验证失败 | 警告但不阻止操作 | ## 总结 OpenSpec 的核心模块通过**工件图（Artifact Graph）** 这一核心概念，将变更管理抽象为工件的有向无环图（DAG）。配合 Zod 类型系统、YAML Schema 定义和模块化的解析器架构，实现了： - **声明式规范**：通过 schema.yaml 定义工件结构和依赖 - **运行时验证**：状态检测确保按序创建工件 - **灵活扩展**：支持项目级、用户级、包级三层 Schema 定制 - **上下文感知**：项目配置和变更上下文自动注入到指令中 这套架构既保持了简单性（无模板引擎依赖），又提供了足够的灵活性来支持复杂的团队工作流程。 --- ## 变更工作流 ### 相关页面 相关主题：[工件图系统](#page-artifact-graph), [工作流模板](#page-workflow-templates), [CLI命令参考](#page-cli-commands)
相关源码文件 以下源码文件用于生成本页说明： - [src/core/templates/workflows/propose.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/propose.ts) - [src/core/templates/workflows/apply-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/apply-change.ts) - [src/core/templates/workflows/archive-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/archive-change.ts) - [src/core/parsers/change-parser.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/parsers/change-parser.ts) - [src/core/archive.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/archive.ts) - [src/commands/change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/change.ts)
# 变更工作流 ## 概述 变更工作流（Change Workflow）是 OpenSpec 框架的核心功能，它定义了一套标准化的流程，用于管理项目变更的生命周期。该工作流涵盖从变更提议、规格编写、设计文档、任务规划到实现完成并归档的全过程。 OpenSpec 的变更工作流采用 **提案 → 应用 → 归档** 的三阶段模式，每个阶段都有明确的输入、输出和验收标准，确保人类开发者和 AI 助手之间能够高效协作。 ## 工作流架构 ### 整体流程图 ```mermaid graph TD A[开始新变更] --> B{选择工具} B --> C[Claude Code] B --> D[Cursor] B --> E[VS Code] B --> F[其他工具] C --> G[/opsx:propose] D --> H[/openspec-proposal] E --> I[自然语言请求] F --> I G --> J[创建变更目录] H --> J I --> J J --> K[proposal.md] K --> L[specs/ 目录] L --> M[design.md] M --> N[tasks.md] N --> O{实现完成?} O -->|否| P[继续开发] P --> N O -->|是| Q[/opsx:archive] Q --> R[归档到 archive/] R --> S[更新主规格文档] style G fill:#e1f5fe style H fill:#e1f5fe style I fill:#fff3e0 style Q fill:#c8e6c9 ``` ### 变更目录结构 每个变更在 `openspec/changes/{change-id}/` 目录下创建完整的工作空间： | 文件/目录 | 说明 | 必需 | |-----------|------|------| | `proposal.md` | 变更提案，说明变更原因和目标 | ✓ | | `design.md` | 技术设计方案 | 可选 | | `tasks.md` | 实现任务清单 | ✓ | | `specs/` | 规格变更增量文件 | 可选 | 归档后，变更目录移至 `openspec/changes/archive/{date}-{change-id}/`。 ## 提案阶段（Propose） ### 触发方式 不同 AI 工具通过不同的命令触发提案创建： | 工具类型 | 命令格式 | 说明 | |----------|----------|------| | Claude Code | `/opsx:propose ` | 使用斜杠命令 | | Cursor | `/openspec-proposal ` | 扁平化前缀命名 | | 其他工具 | 自然语言请求 | "创建一个 OpenSpec 提案" | ### 提案模板内容 提案文件包含以下标准结构： ```yaml --- proposal category: OpenSpec description: Scaffold a new OpenSpec change and validate strictly. --- ``` 模板内容需包含： - **Guardrails（防护规则）**：1-2 个澄清问题 - **Minimal-complexity rules（最小复杂度规则）** - **Step list（步骤列表）**：针对提案阶段的操作指令 - **Pointers（指针）**：指向 `openspec show`、`openspec list` 等命令 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md]() ### 提案生成流程 ```mermaid sequenceDiagram participant User as 用户 participant AI as AI 助手 participant CLI as OpenSpec CLI User->>AI: /opsx:propose add-dark-mode AI->>CLI: 解析命令 CLI->>AI: 返回指令模板 AI->>AI: 创建变更目录结构 AI->>AI: 生成 proposal.md AI->>AI: 生成 specs/ 目录 AI->>AI: 生成 design.md AI->>AI: 生成 tasks.md AI->>User: 变更已创建 ``` ## 规格阶段（Specs） ### 规格文件格式 规格文件使用 Markdown 格式，遵循严格的头部层级结构： ```markdown ## ADDED Requirements ### Requirement: <需求名称> <需求描述，使用 SHALL/MUST 描述规范> #### Scenario: <场景名称> - **WHEN** <触发条件> - **THEN** <预期结果> - **AND** <附加结果> ``` ### 关键格式要求 | 要求 | 说明 | 重要性 | |------|------|--------| | 需求头部 | 使用 `### Requirement:` | 必须 | | 规范语气 | 使用 SHALL/MUST，避免 should/may | 必须 | | 场景头部 | 必须使用 `#### Scenario:`（4个#） | 关键 | | 场景格式 | 使用 `- **WHEN**` / `- **THEN**` 格式 | 必须 | > ⚠️ **常见错误**：使用 3 个 `#` 或使用列表格式会导致场景解析失败。 资料来源：[schemas/spec-driven/schema.yaml]() ### 规格操作类型 规格变更支持以下操作类型： | 操作 | 说明 | 示例 | |------|------|------| | `ADDED` | 新增需求 | 添加新功能 | | `MODIFIED` | 修改现有需求 | 更改现有行为 | | `REMOVED` | 删除需求 | 移除废弃功能 | | `RENAMED` | 重命名需求 | 迁移命名 | ### MODIFIED 工作流 修改现有需求时，必须遵循以下步骤： 1. 在 `openspec/specs//spec.md` 中定位现有需求 2. 复制**完整**的需求块（从 `### Requirement:` 到所有场景） 3. 粘贴到 `## MODIFIED Requirements` 下并编辑 4. 确保头部文本完全匹配（忽略空白差异） 资料来源：[schemas/spec-driven/schema.yaml]() ## 应用阶段（Apply） ### 触发方式 | 工具 | 命令格式 | |------|----------| | Claude Code | `/opsx:apply ` | | Cursor | `/openspec-apply ` | | 其他 | 自然语言请求 | ### 应用指令生成 应用阶段指令的生成遵循以下流程： ```mermaid graph TD A[用户请求应用] --> B[加载变更元数据] B --> C[检查 design.md 是否存在] C --> D[检查 tasks.md 是否存在] D --> E[构建上下文文件列表] E --> F[生成应用指令] F --> G[返回指令给 AI] G --> H[AI 执行任务] H --> I[标记完成的任务] ``` ### 应用指令结构 ```typescript { instruction: "执行以下任务的指令", contextFiles: [ "proposal.md", "design.md", "tasks.md", "specs/**/*.md" ], tracks: ["Task 1.1 ✓", "Task 1.2 ✓", ...] } ``` ## 归档阶段（Archive） ### 归档流程 ```mermaid graph LR A[openspec/changes/{id}/] --> B[验证所有任务完成] B --> C{验证通过?} C -->|是| D[移动到 archive/] C -->|否| E[返回错误信息] D --> F[按日期命名子目录] D --> G[更新主规格文档] ``` ### 归档命令 ```bash # 标准归档 openspec archive # 非交互式归档（跳过确认） openspec archive --yes # 缩写形式 openspec archive -y ``` ### 带参数的归档 部分工具支持传入变更 ID 参数： ```bash /openspec:archive ``` 参数处理逻辑： 1. 验证 `$ARGUMENTS` 占位符是否存在 2. 解析传入的变更 ID 3. 使用 `openspec list` 验证变更存在 4. 执行归档操作 资料来源：[openspec/changes/archive/2025-10-22-add-archive-command-arguments/tasks.md]() ### 归档后操作 归档完成后，系统自动执行以下操作： 1. 将变更目录移动到 `openspec/changes/archive/{YYYY-MM-DD}-{change-id}/` 2. 从规格增量文件中提取变更，更新到主规格文档 3. 从任务列表中移除已完成的变更 ## CLI 命令参考 ### 变更管理命令 | 命令 | 说明 | |------|------| | `openspec list` | 列出活跃的变更 | | `openspec show ` | 显示变更详情 | | `openspec validate ` | 验证规格格式和结构 | | `openspec archive [--yes]` | 归档完成的变更 | ### 查看命令选项 ```bash # 查看变更详情 openspec show # JSON 格式输出（仅显示增量） openspec show --json --deltas-only # 严格验证模式 openspec validate --strict ``` ## 工具支持矩阵 | 工具 | 提案命令 | 应用命令 | 归档命令 | |------|----------|----------|----------| | Claude Code | `/opsx:propose` | `/opsx:apply` | `/opsx:archive` | | Cursor | `/openspec-proposal` | `/openspec-apply` | `/openspec-archive` | | Roo Code | `/openspec/proposal` | `/openspec/apply` | `/openspec/archive` | | CodeBuddy | `/openspec/proposal` | `/openspec/apply` | `/openspec/archive` | | Windsurf | `/openspec-proposal` | `/openspec-apply` | `/openspec-archive` | | Kilo Code | `/openspec-proposal.md` | `/openspec-apply.md` | `/openspec-archive.md` | | 其他 | 自然语言 | 自然语言 | 自然语言 | > 注：Kilo Code 会自动发现团队工作流，命令需保存为 `.kilocode/workflows/` 下的 Markdown 文件。 ## 最佳实践 ### 1. 变更命名规范 - 使用 kebab-case 格式：`add-dark-mode`、`fix-auth-bug` - 简洁明了，反映变更本质 - 避免使用 `new-feature`、`update-1` 等模糊名称 ### 2. 规格编写要点 - 每个需求必须有至少一个场景 - 场景描述需具体、可测试 - 使用 Gherkin 语法（Given/When/Then）保持一致性 ### 3. 任务拆解建议 - 任务粒度适中，便于进度跟踪 - 包含验证步骤，确保实现正确 - 标记依赖关系，合理安排执行顺序 ### 4. 变更周期管理 ```mermaid graph TD A[提案] --> B{规格评审} B -->|通过| C[设计] B -->|不通过| A C --> D{设计评审} D -->|通过| E[任务规划] D -->|不通过| C E --> F[实现] F --> G{测试} G -->|通过| H[归档] G -->|失败| F ``` ## 常见问题排查 | 问题 | 原因 | 解决方案 | |------|------|----------| | "变更必须有至少一个增量" | `specs/` 目录不存在或为空 | 确保 `specs/` 目录包含 `.md` 文件 | | "需求必须有至少一个场景" | 场景格式错误 | 检查使用 `#### Scenario:`（4个#） | | 场景解析静默失败 | 头部格式不正确 | 使用 `openspec show --json --deltas-only` 调试 | | 归档失败 | 存在未完成任务 | 完成所有任务或使用 `--skip-checks` | --- ## 工件图系统 ### 相关页面 相关主题：[变更工作流](#page-change-workflow), [系统架构](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [src/core/artifact-graph/graph.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/graph.ts) - [src/core/artifact-graph/instruction-loader.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/instruction-loader.ts) - [src/core/artifact-graph/outputs.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/outputs.ts) - [src/core/artifact-graph/resolver.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/resolver.ts) - [src/core/artifact-graph/state.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/state.ts) - [src/core/artifact-graph/types.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/types.ts)
# 工件图系统 ## 概述 工件图系统（Artifact Graph System）是 OpenSpec 的核心子系统，负责管理软件开发变更中的工件（Artifact）及其依赖关系。该系统通过图结构建模工件的创建顺序、依赖状态和生成路径，实现动态指令生成和状态追踪。 **核心能力：** - 将工件定义为节点，依赖关系定义为边，构建有向无环图（DAG） - 基于拓扑排序确定工件创建顺序 - 实时检测工件完成状态（已完成、就绪、阻塞） - 动态加载模式匹配的指令模板 资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md) --- ## 架构设计 ### 系统分层 ```mermaid graph TD subgraph "表现层" CLI[CLI 命令] Workflow[工作流模板] end subgraph "核心层" IG[工件图] IL[指令加载器] ST[状态追踪] RS[模式解析] end subgraph "数据层" YAML[Schema YAML] TMPL[模板文件] CFG[项目配置] end CLI --> IG CLI --> IL Workflow --> IL IG --> IL IG --> ST IG --> RS RS --> YAML IL --> TMPL IL --> CFG style IG fill:#e1f5fe style IL fill:#e8f5e8 style ST fill:#fff3e0 style RS fill:#f3e5f5 ``` ### 目录结构 ``` src/core/artifact-graph/ ├── index.ts # 公共导出 ├── types.ts # Zod 类型定义和接口 ├── graph.ts # ArtifactGraph 类 ├── state.ts # 状态检测逻辑 ├── resolver.ts # Schema 解析（全局 → 内置） ├── instruction-loader.ts # 模板加载与指令丰富 ├── outputs.ts # 输出格式化 └── schemas/ # 内置模式定义 ├── spec-driven.yaml └── tdd.yaml ``` 资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md) --- ## 核心类型定义 ### Schema 结构 模式（Schema）是定义工件及其依赖关系的 YAML 配置文件，位于 `src/core/artifact-graph/types.ts`。 | 字段 | 类型 | 描述 | |------|------|------| | `name` | string | 模式名称 | | `version` | number | 模式版本 | | `description` | string | 模式描述 | | `artifacts` | Artifact[] | 工件定义数组 | | `apply` | ApplyPhase | 可选的 apply 阶段配置 | **Artifact 对象结构：** | 字段 | 类型 | 描述 | |------|------|------| | `id` | string | 工件唯一标识符 | | `generates` | string | 生成的文件路径 | | `template` | string | 模板文件路径（相对） | | `requires` | string[] | 前置依赖工件 ID | | `description` | string | 工件描述 | 资料来源：[src/core/artifact-graph/types.ts](src/core/artifact-graph/types.ts) ### 运行时状态类型 ```typescript // 已完成的工件 ID 集合 type CompletedSet = Set; // 阻塞工件：artifact → 未满足的依赖列表 type BlockedArtifacts = Map; // 工件图结果 interface ArtifactGraphResult { completed: string[]; // 已完成的工件 ready: string[]; // 就绪可创建的工件 blocked: BlockedArtifacts; // 阻塞的工件及其原因 buildOrder: string[]; // 构建顺序（拓扑排序结果） } ``` 资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md) --- ## 工件图类 `ArtifactGraph` 类是系统的核心组件，位于 `src/core/artifact-graph/graph.ts`。 ### 主要方法 | 方法 | 返回值 | 功能描述 | |------|--------|----------| | `fromYaml(path)` | `ArtifactGraph` | 从 Schema YAML 文件加载工件图 | | `getBuildOrder()` | `string[]` | 获取拓扑排序后的工件顺序 | | `getArtifact(id)` | `Artifact \| undefined` | 获取单个工件定义 | | `getAllArtifacts()` | `Artifact[]` | 获取所有工件定义 | ### 拓扑排序算法 系统使用 **Kahn算法**（Kahn's Algorithm）进行拓扑排序： ```mermaid graph LR A[proposal] --> B[specs] B --> C[design] C --> D[tasks] style A fill:#4caf50 style B fill:#ffeb3b style C fill:#ffeb3b style D fill:#ff9800 ``` **算法特点：** - 自动检测循环依赖，检测到时抛出明确错误 - 错误格式：`Cyclic dependency detected: A → B → C → A` - 返回的顺序保证所有依赖在依赖者之前 资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md) --- ## 状态检测 状态检测模块负责判断工件的就绪状态，位于 `src/core/artifact-graph/state.ts`。 ### 检测逻辑 ```mermaid graph TD START[检查工件] --> IS_BLOCKED{是否有未完成的依赖?} IS_BLOCKED -->|是| MISSING[标记为 blocked] IS_BLOCKED -->|否| HAS_OUTPUT{输出文件是否存在?} HAS_OUTPUT -->|是| COMPLETED[标记为 completed] HAS_OUTPUT -->|否| READY[标记为 ready] style COMPLETED fill:#4caf50 style READY fill:#ffeb3b style MISSING fill:#ff9800 ``` ### 状态类型 | 状态 | 描述 | 条件 | |------|------|------| | `completed` | 已完成 | 所有前置依赖完成且输出文件存在 | | `ready` | 就绪 | 所有前置依赖完成但输出文件不存在 | | `blocked` | 阻塞 | 存在未完成的前置依赖 | 资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md) --- ## Schema 解析 Schema 解析器负责定位和加载模式定义，位于 `src/core/artifact-graph/resolver.ts`。 ### 解析路径优先级 ```mermaid graph TD REQ[请求加载 Schema] --> GLOBAL{检查全局覆盖} GLOBAL -->|存在| GLOBAL_LOAD[加载全局 Schema] GLOBAL -->|不存在| BUILTIN{检查内置 Schema} BUILTIN -->|存在| BUILTIN_LOAD[加载内置 Schema] BUILTIN -->|不存在| ERROR[抛出错误] GLOBAL_LOAD --> RESULT[返回 Schema] BUILTIN_LOAD --> RESULT style GLOBAL_LOAD fill:#e1f5fe style BUILTIN_LOAD fill:#e8f5e8 style ERROR fill:#ffcdd2 ``` | 优先级 | 路径 | 说明 | |--------|------|------| | 1 | `${XDG_DATA_HOME}/openspec/schemas//schema.yaml` | 用户全局覆盖 | | 2 | `/schemas//schema.yaml` | 包内置 Schema | 资料来源：[openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md](openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md) ### 内置 Schema 示例 **spec-driven 模式**（默认）： ```yaml name: spec-driven version: 1 artifacts: - id: proposal generates: "proposal.md" requires: [] - id: specs generates: "specs.md" requires: [proposal] - id: design generates: "design.md" requires: [specs] - id: tasks generates: "tasks.md" requires: [specs, design] apply: requires: [tasks] instruction: "Read context files, work through pending tasks" ``` 资料来源：[schemas/spec-driven/schema.yaml](schemas/spec-driven/schema.yaml) --- ## 指令加载器 指令加载器负责将工件模板与变更上下文结合，生成最终指令，位于 `src/core/artifact-graph/instruction-loader.ts`。 ### 变更上下文 ```typescript interface ChangeContext { changeName: string; // 变更名称 changeDir: string; // 变更目录路径 schemaName: string; // 使用的模式名 graph: ArtifactGraph; // 工件图实例 completed: CompletedSet; // 已完成工件集合 } ``` ### 指令结构 ```mermaid graph LR TMPL[模板] --> CTX[上下文注入] RULES[规则] --> RULES_INJ[规则注入] CTX --> OUTPUT[最终指令] RULES_INJ --> OUTPUT style CTX fill:#e8f5e8 style OUTPUT fill:#e1f5fe ``` ### 输出格式 生成的指令包含以下 XML 标签结构： | 标签 | 内容 | 说明 | |------|------|------| | `` | 工件元信息 | 包含 id, change, schema 属性 | | `` | 任务描述 | 要创建的工件说明 | | `` | 项目上下文 | 来自 config.yaml 的背景信息 | | `` | 约束规则 | 特定工件的行为约束 | | `