openspec-sync-specs

name	openspec-sync-specs
description	将变更中的增量规范同步到主规范。当用户想要使用增量规范中的更改更新主规范，而不归档该变更时使用。
license	MIT
compatibility	需要 openspec CLI。
metadata	{"author":"openspec","version":"1.0","generatedBy":"1.2.0"}

将变更中的增量规范同步到主规范。

这是一个 Agent 驱动 的操作 - 你将读取增量规范并直接编辑主规范以应用更改。这允许智能合并（例如，添加场景而不复制整个需求）。

输入：可选指定变更名称。如果省略，检查是否可以从对话上下文中推断。如果模糊或不明确，你必须提示获取可用变更。

步骤

1. 如果没有提供变更名称，提示选择

   运行 openspec-cn list --json 获取可用变更。使用 AskUserQuestion tool 让用户选择。

   显示具有增量规范（在 specs/ 目录下）的变更。

   重要提示：不要猜测或自动选择变更。始终让用户选择。

2. 查找增量规范

   在 openspec/changes/<name>/specs/*/spec.md 中查找增量规范文件。

   每个增量规范文件包含如下部分：

   • ## 新增需求 - 要添加的新需求
   • ## 修改需求 - 对现有需求的更改
   • ## 移除需求 - 要移除的需求
   • ## 重命名需求 - 要重命名的需求（从/到 格式）

   如果没有找到增量规范，通知用户并停止。

3. 对于每个增量规范，将更改应用到主规范

   对于在 openspec/changes/<name>/specs/<capability>/spec.md 处具有增量规范的每个 capability：

   a. 阅读增量规范 以了解预期的更改

   b. 阅读主规范 于 openspec/specs/<capability>/spec.md（可能尚不存在）

   c. 智能地应用更改：

   新增需求：

   • 如果需求在主规范中不存在 → 添加它
   • 如果需求已存在 → 更新它以匹配（视为隐式 MODIFIED）

   修改需求：

   • 在主规范中找到该需求
   • 应用更改 - 这可能是：
     • 添加新场景（不需要复制现有场景）
     • 修改现有场景
     • 更改需求描述
   • 保留增量中未提及的场景/内容

   移除需求：

   • 从主规范中移除整个需求块

   重命名需求：

   • 找到 FROM 需求，重命名为 TO

   d. 创建新主规范 如果 capability 尚不存在：

   • 创建 openspec/specs/<capability>/spec.md
   • 添加 目的 部分（可以简短，标记为 待定）
   • 添加 需求 部分以及 新增需求

4. 显示摘要

   应用所有更改后，总结：

   • 哪些 capability 已更新
   • 做了什么更改（需求添加/修改/移除/重命名）

增量规范格式参考

## 新增需求

### 需求: 新功能
系统 应当 实现新的能力。

#### 场景: 基本场景
- **当** 用户执行 X
- **那么** 系统执行 Y

## 修改需求

### 需求: 现有功能
#### 场景: 需要新增的场景
- **当** 用户执行 A
- **那么** 系统执行 B

## 移除需求

### 需求: 已废弃功能

## 重命名需求

- 从: `### 需求: Old Name`
- 到: `### 需求: New Name`

关键原则：智能合并

与程序化合并不同，你可以应用 部分更新：

• 要添加场景，只需将该场景包含在 MODIFIED 下 - 不要复制现有场景
• 增量代表 意图，而不是整体替换
• 使用你的判断力合理地合并更改

成功时的输出

## 规范已同步：<change-name>

已更新主规范：

**<capability-1>**：
- 添加需求："新功能"
- 修改需求："现有功能"（添加了 1 个场景）

**<capability-2>**：
- 创建了新规范文件
- 添加需求："另一个功能"

主规范现已更新。变更保持活动状态 - 在实现完成后归档。

护栏

• 在进行更改之前阅读增量规范和主规范
• 保留增量中未提及的现有内容
• 如果不清楚，询问澄清
• 在进行时显示你正在更改的内容
• 操作应该是幂等的 - 运行两次应给出相同的结果