2026-02-11 13:00:01 +08:00
|
|
|
|
---
|
|
|
|
|
|
name: openspec-sync-specs
|
2026-02-11 14:42:46 +08:00
|
|
|
|
description: 将变更的 delta specs 同步到主 specs。当用户想要使用 delta spec 的更改更新主 specs，而不归档变更时使用。
|
2026-02-11 13:00:01 +08:00
|
|
|
|
license: MIT
|
|
|
|
|
|
compatibility: Requires openspec CLI.
|
|
|
|
|
|
metadata:
|
|
|
|
|
|
author: openspec
|
|
|
|
|
|
version: "1.0"
|
|
|
|
|
|
generatedBy: "1.1.1"
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
将变更的 delta specs 同步到主 specs。
|
|
|
|
|
|
|
|
|
|
|
|
这是一个**代理驱动**的操作 - 你将读取 delta specs 并直接编辑主 specs 以应用更改。这允许智能合并 (例如,添加场景而不复制整个需求)。
|
|
|
|
|
|
|
|
|
|
|
|
**输入**: 可选择指定变更名称。如果省略,检查是否可以从对话上下文中推断。如果模糊或不明确,你**必须**提示可用的变更。
|
|
|
|
|
|
|
|
|
|
|
|
**步骤**
|
|
|
|
|
|
|
|
|
|
|
|
1. **如果未提供变更名称,提示用户选择**
|
|
|
|
|
|
|
|
|
|
|
|
运行 `openspec list --json` 获取可用的变更。使用 **AskUserQuestion 工具**让用户选择。
|
|
|
|
|
|
|
|
|
|
|
|
显示具有 delta specs 的变更 (在 `specs/` 目录下)。
|
|
|
|
|
|
|
|
|
|
|
|
**重要**: 不要猜测或自动选择变更。始终让用户选择。
|
|
|
|
|
|
|
|
|
|
|
|
2. **查找 delta specs**
|
|
|
|
|
|
|
|
|
|
|
|
在 `openspec/changes/<name>/specs/*/spec.md` 中查找 delta spec 文件。
|
|
|
|
|
|
|
|
|
|
|
|
每个 delta spec 文件包含如下部分:
|
|
|
|
|
|
- `## ADDED Requirements` - 要添加的新需求
|
|
|
|
|
|
- `## MODIFIED Requirements` - 对现有需求的更改
|
|
|
|
|
|
- `## REMOVED Requirements` - 要删除的需求
|
|
|
|
|
|
- `## RENAMED Requirements` - 要重命名的需求 (FROM:/TO: 格式)
|
|
|
|
|
|
|
|
|
|
|
|
如果未找到 delta specs,通知用户并停止。
|
|
|
|
|
|
|
|
|
|
|
|
3. **对于每个 delta spec,将更改应用到主 specs**
|
|
|
|
|
|
|
|
|
|
|
|
对于每个在 `openspec/changes/<name>/specs/<capability>/spec.md` 有 delta spec 的 capability:
|
|
|
|
|
|
|
|
|
|
|
|
a. **读取 delta spec** 以了解预期的更改
|
|
|
|
|
|
|
|
|
|
|
|
b. **读取主 spec** 在 `openspec/specs/<capability>/spec.md` (可能尚不存在)
|
|
|
|
|
|
|
|
|
|
|
|
c. **智能应用更改**:
|
|
|
|
|
|
|
|
|
|
|
|
**ADDED Requirements:**
|
|
|
|
|
|
- 如果需求在主 spec 中不存在 → 添加它
|
|
|
|
|
|
- 如果需求已存在 → 更新它以匹配 (视为隐式 MODIFIED)
|
|
|
|
|
|
|
|
|
|
|
|
**MODIFIED Requirements:**
|
|
|
|
|
|
- 在主 spec 中找到需求
|
|
|
|
|
|
- 应用更改 - 这可以是:
|
|
|
|
|
|
- 添加新场景 (不需要复制现有场景)
|
|
|
|
|
|
- 修改现有场景
|
|
|
|
|
|
- 更改需求描述
|
|
|
|
|
|
- 保留 delta 中未提及的场景/内容
|
|
|
|
|
|
|
|
|
|
|
|
**REMOVED Requirements:**
|
|
|
|
|
|
- 从主 spec 中删除整个需求块
|
|
|
|
|
|
|
|
|
|
|
|
**RENAMED Requirements:**
|
|
|
|
|
|
- 找到 FROM 需求,重命名为 TO
|
|
|
|
|
|
|
|
|
|
|
|
d. **创建新的主 spec** 如果 capability 尚不存在:
|
|
|
|
|
|
- 创建 `openspec/specs/<capability>/spec.md`
|
|
|
|
|
|
- 添加 Purpose 部分 (可以简短,标记为 TBD)
|
|
|
|
|
|
- 添加 Requirements 部分,包含 ADDED 需求
|
|
|
|
|
|
|
|
|
|
|
|
4. **显示摘要**
|
|
|
|
|
|
|
|
|
|
|
|
应用所有更改后,总结:
|
|
|
|
|
|
- 更新了哪些 capabilities
|
|
|
|
|
|
- 做了哪些更改 (需求添加/修改/删除/重命名)
|
|
|
|
|
|
|
|
|
|
|
|
**Delta Spec 格式参考**
|
|
|
|
|
|
|
|
|
|
|
|
```markdown
|
|
|
|
|
|
## ADDED Requirements
|
|
|
|
|
|
|
|
|
|
|
|
### Requirement: 新功能
|
|
|
|
|
|
系统应当做某件新事情。
|
|
|
|
|
|
|
|
|
|
|
|
#### Scenario: 基本情况
|
|
|
|
|
|
- **WHEN** 用户执行 X
|
|
|
|
|
|
- **THEN** 系统执行 Y
|
|
|
|
|
|
|
|
|
|
|
|
## MODIFIED Requirements
|
|
|
|
|
|
|
|
|
|
|
|
### Requirement: 现有功能
|
|
|
|
|
|
#### Scenario: 要添加的新场景
|
|
|
|
|
|
- **WHEN** 用户执行 A
|
|
|
|
|
|
- **THEN** 系统执行 B
|
|
|
|
|
|
|
|
|
|
|
|
## REMOVED Requirements
|
|
|
|
|
|
|
|
|
|
|
|
### Requirement: 已弃用功能
|
|
|
|
|
|
|
|
|
|
|
|
## RENAMED Requirements
|
|
|
|
|
|
|
|
|
|
|
|
- FROM: `### Requirement: 旧名称`
|
|
|
|
|
|
- TO: `### Requirement: 新名称`
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**核心原则: 智能合并**
|
|
|
|
|
|
|
|
|
|
|
|
与程序化合并不同,你可以应用**部分更新**:
|
|
|
|
|
|
- 要添加场景,只需在 MODIFIED 下包含该场景 - 不要复制现有场景
|
|
|
|
|
|
- Delta 代表*意图*,而不是全部替换
|
|
|
|
|
|
- 使用你的判断合理地合并更改
|
|
|
|
|
|
|
|
|
|
|
|
**成功时的输出**
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
## Specs 已同步: <change-name>
|
|
|
|
|
|
|
|
|
|
|
|
更新的主 specs:
|
|
|
|
|
|
|
|
|
|
|
|
**<capability-1>**:
|
|
|
|
|
|
- 添加需求: "新功能"
|
|
|
|
|
|
- 修改需求: "现有功能" (添加 1 个场景)
|
|
|
|
|
|
|
|
|
|
|
|
**<capability-2>**:
|
|
|
|
|
|
- 创建新 spec 文件
|
|
|
|
|
|
- 添加需求: "另一个功能"
|
|
|
|
|
|
|
|
|
|
|
|
主 specs 现已更新。变更保持活跃 - 实现完成后归档。
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**防护机制**
|
|
|
|
|
|
- 在进行更改前读取 delta 和主 specs
|
|
|
|
|
|
- 保留 delta 中未提及的现有内容
|
|
|
|
|
|
- 如果有不清楚的地方,请求澄清
|
|
|
|
|
|
- 边做边显示你正在更改的内容
|
|
|
|
|
|
- 操作应该是幂等的 - 运行两次应该给出相同结果
|
