Menu
归档已完成的变更并将规范差异合并到常驻文档。用于变更已部署、准备归档或实施后需要更新规范时。触发词包括 "openspec归档", "归档", "归档提案", "合并规范", "完成提案", "更新文档", "定稿规范", "标记完成"。
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
| name | openspec-archiving-cn |
| description | 归档已完成的变更并将规范差异合并到常驻文档。用于变更已部署、准备归档或实施后需要更新规范时。触发词包括 "openspec归档", "归档", "归档提案", "合并规范", "完成提案", "更新文档", "定稿规范", "标记完成"。 |
归档已完成的变更提案，并将其规范差异合并到常驻规范文档中。
归档包含两项主要操作：
关键规则：在归档前验证所有任务已完成。归档意味着已部署且完成。
复制此清单并跟踪进度：
归档进度:
- [ ] 第 1 步：验证实施完成
- [ ] 第 2 步：审阅待合并的规范差异
- [ ] 第 3 步：创建带时间戳的归档目录
- [ ] 第 4 步：合并 ADDED 需求到常驻规范
- [ ] 第 5 步：合并 MODIFIED 需求到常驻规范
- [ ] 第 6 步：合并 REMOVED 需求到常驻规范
- [ ] 第 7 步：移动变更目录到归档
- [ ] 第 8 步：验证常驻规范结构
在归档前确认所有工作已完成：
# 检查 IMPLEMENTED 标记
test -f spec/changes/{change-id}/IMPLEMENTED && echo "✓ 已实施" || echo "✗ 未实施"
# 查看任务
cat spec/changes/{change-id}/tasks.json
# 使用 git 检查未提交工作
git status
询问用户：
所有任务是否已完成并通过测试？
该变更是否已部署到生产？
是否继续归档？
了解需要合并的内容：
# 列出所有规范差异文件
find spec/changes/{change-id}/specs -name "*.md" -type f
# 读取每个差异文件
for file in spec/changes/{change-id}/specs/**/*.md; do
echo "=== $file ==="
cat "$file"
done
识别：
# 以当天日期创建归档目录
TIMESTAMP=$(date +%Y-%m-%d)
mkdir -p spec/archive/${TIMESTAMP}-{change-id}
示例：
# 对 2025-10-26 归档的 "add-user-auth" 变更
mkdir -p spec/archive/2025-10-26-add-user-auth
对每个 ## ADDED Requirements 部分：
流程：
示例：
来源（spec/changes/add-user-auth/specs/authentication/spec-delta.md）：
## ADDED Requirements
### Requirement: 用户登录
WHEN 用户提交有效凭据,
系统 SHALL 认证用户并创建会话。
#### Scenario: 登录成功
GIVEN 有效的凭据
WHEN 用户提交登录表单
THEN 系统创建会话
目标（spec/specs/authentication/spec.md）：
# 追加到常驻规范
cat >> spec/specs/authentication/spec.md << 'EOF'
### Requirement: 用户登录
WHEN 用户提交有效凭据,
系统 SHALL 认证用户并创建会话。
#### Scenario: 登录成功
GIVEN 有效的凭据
WHEN 用户提交登录表单
THEN 系统创建会话
EOF
对每个 ## MODIFIED Requirements 部分：
流程：
示例（使用 sed）：
# 查找并替换需求块
# 这是概念示例——实际实现取决于结构
# 首先，确定旧需求的起始行
START_LINE=$(grep -n "### Requirement: 用户登录" spec/specs/authentication/spec.md | cut -d: -f1)
# 查找结束位置（下一个需求或文件末尾）
END_LINE=$(tail -n +$((START_LINE + 1)) spec/specs/authentication/spec.md | \
grep -n "^### Requirement:" | head -1 | cut -d: -f1)
# 删除旧需求
sed -i "${START_LINE},${END_LINE}d" spec/specs/authentication/spec.md
# 在相同位置插入新需求
#（从差异文件提取并插入）
手动方式（出于安全建议）：
1. 在编辑器中打开常驻规范
2. 通过名称查找目标需求
3. 删除整个块（需求 + 所有场景）
4. 将差异文件中的更新需求粘贴到该处
5. 保存
对每个 ## REMOVED Requirements 部分：
流程：
示例：
# 方案 1：带注释删除
# 手动编辑 spec/specs/authentication/spec.md
# 添加弃用注释
echo "<!-- Requirement 'Legacy Password Reset' removed $(date +%Y-%m-%d) -->" >> spec/specs/authentication/spec.md
# 通过手动或 sed 删除该需求块
模式：
<!-- Removed 2025-10-26: 用户需使用基于邮件的密码重置 -->
~~### Requirement: SMS Password Reset~~
在所有差异合并后：
# 将完整的变更目录移动到归档
mv spec/changes/{change-id} spec/archive/${TIMESTAMP}-{change-id}
验证移动成功：
# 检查归档是否存在
ls -la spec/archive/${TIMESTAMP}-{change-id}
# 检查 changes 目录是否干净
ls spec/changes/ | grep "{change-id}" # 应无结果
在合并后，验证常驻规范的完整性：
# 检查需求格式
grep -n "### Requirement:" spec/specs/**/*.md
# 检查场景格式
grep -n "#### Scenario:" spec/specs/**/*.md
# 统计每个规范中的需求数量
for spec in spec/specs/**/spec.md; do
count=$(grep -c "### Requirement:" "$spec")
echo "$spec: $count 条需求"
done
手动审阅：
动作：追加到常驻规范
位置：文件末尾（任何页脚/附录之前）
格式：按原文复制需求与全部场景
动作：替换现有需求
位置：通过需求名称定位，替换整个块
格式：使用差异文件的完整更新文本（不拼接，直接替换）
说明：旧版本保留在归档中
动作：删除需求，并添加弃用注释
位置：通过需求名称定位
格式：删除整个块，可选添加 <!-- Removed YYYY-MM-DD: reason -->
动作：更新需求名称，保留内容
位置：通过旧名称定位，更新为新名称
格式：仅修改标题：### Requirement: 新名称
说明：通常使用 MODIFIED 更为常见
务必在移动到归档前验证差异合并：
# 合并后查看差异
git diff spec/specs/
# 审阅变更
git diff spec/specs/authentication/spec.md
# 若正确则提交
git add spec/specs/
git commit -m "Merge spec deltas from add-user-auth"
# 然后再归档
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth
归档整个变更，而非单个文件：
好：
# 移动完整变更目录
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth
坏：
# 不要挑拣文件
mv spec/changes/add-user-auth/proposal.md spec/archive/
#（会留下孤儿文件）
归档是历史记录。切勿修改归档文件：
❌ 不要：编辑 spec/archive/
✓ 要：将归档视为只读历史
推荐提交流程：
# 提交 1：合并差异
git add spec/specs/
git commit -m "Merge spec deltas from add-user-auth
- Added User Login requirement
- Modified Password Policy requirement
- Removed Legacy Auth requirement"
# 提交 2：归档变更
git add spec/archive/ spec/changes/
git commit -m "Archive add-user-auth change"
复杂差异：见 reference/MERGE_LOGIC.md
冲突解决：若多个变更修改同一需求，需手动合并。
回滚策略：若需回滚归档，反向执行流程（从归档移回 changes，并从常驻规范移除已合并内容）。
变更新增 1 条需求 → 追加到规范 → 归档
变更修改 1 条需求 → 在规范中替换 → 归档
变更移除 1 条需求 → 删除并添加注释 → 归档
变更在 2 个规范中新增 5 条需求
→ 分别追加到相应规范
→ 验证全部已合并
→ 归档
不要：
要：
解决方案：
1. 若名称相同但内容不同 → 使用 MODIFIED 模式
2. 若确实是不同需求 → 重命名其中之一
3. 若属重复错误 → 选择正确版本
解决方案：
1. 按部分名称搜索：grep -i "login" spec/specs/**/*.md
2. 检查是否已被移除
3. 检查是否位于其他能力文件
解决方案：
1. 手动修复格式
2. 重新运行验证：grep -n "###" spec/specs/**/*.md
3. 确保标题层级一致
Token 预算：此 SKILL.md 约 430 行，低于建议的 500 行上限。
加载项目上下文，列出现有规范与变更，搜索能力与需求。用于用户询问项目状态、现有规范、进行中的变更、可用能力或需要发现上下文时。触发词包括"openspec上下文", "有哪些规范", "显示变更", "列出能力", "项目上下文", "查找规范", "规范包含什么", "展示规范"。
以测试与验证为先的方式，按序执行并实现已批准的规范提案。用于实施变更、应用提案、执行规范任务或按已批准计划构建。触发词包括 "openspec开发", "开发", "实施" "实现提案", "应用变更", "执行规范", "按顺序完成任务", "构建功能", "开始实施"。
通过openspec规范驱动的方法创建结构化的变更提案与规范差异。用于规划功能、创建提案、编写规范、引入新能力或启动开发流程。触发词包括 "openspec提案", "规划", "创建提案", "规划变更", "规范功能", "新功能", "新特性", "新需求", "添加功能规划", "设计规范"。
从交互式或提供的原则输入创建或更新项目章程，确保所有依赖模板保持同步。用于项目管理、规范制定、章程维护和团队协作场景。触发词包括 "speckit章程"、"创建章程"、"更新章程"、"项目章程"、"制定规范"、"团队章程"。
执行实施规划工作流程，使用计划模板生成设计工件。触发词包括："speckit计划"。
中文功能规范创建工具，用于将自然语言功能描述转换为结构化的功能规范文档。支持自动生成分支名称、创建Git分支、初始化规范文件和质量验证。触发词包括："speckit规范"、"功能规范"、"创建规范"、"功能描述转换"、"speckit-specify"。当用户需要将功能想法转换为结构化规范时使用此技能。