/opsx:archive的作用可以概括为宣告一个 OpenSpec Change 已经完成把它从“正在进行的变更”转成“历史记录”同时确保 Main Spec 反映最终实现。它不是压缩文件也不是删除文档而是 OpenSpec 生命周期中的“结项”操作。归档前后发生什么开发期间目录一般是openspec/ ├── specs/ # 当前生效的主规范 └── changes/ └── add-user-login/ # 正在开发的 Change ├── proposal.md ├── design.md ├── tasks.md └── specs/ └── auth/ └── spec.md # Delta Spec执行/opsx:archive add-user-login归档后变成openspec/ ├── specs/ │ └── auth/ │ └── spec.md # 已同步最终需求 └── changes/ └── archive/ └── 2026-07-12-add-user-login/ ├── proposal.md ├── design.md ├── tasks.md └── specs/ └── auth/ └── spec.md也就是Active Change ↓ 检查完成状态 ↓ 同步 Delta Spec ↓ 移入 archive ↓ Historical Change/opsx:archive会做哪些事情1. 确定要归档哪个 Change如果指定名称/opsx:archive add-user-login就处理该 Change。如果没有指定/opsx:archiveAgent 会查询openspec list--json如果无法唯一确定应该让用户选择而不是随便挑选。2. 检查 Artifact 是否完整它会检查 Change 中是否存在必要产物例如proposal.md specs/ design.md tasks.md通常会通过openspec status--changeadd-user-login--json获取完成状态。3. 检查任务是否完成读取tasks.md检查是否还有- [ ] 未完成任务理想状态应该全部完成- [x] 创建数据模型 - [x] 实现登录接口 - [x] 添加异常处理 - [x] 编写单元测试如果仍有未完成任务归档工作流通常会警告并要求确认。它不一定绝对阻止归档因为有些任务可能被取消、转移或确认不再需要。更规范的做法是先修改tasks.md明确反映最终状态而不是带着含义不清的未完成项归档。4. 判断 Delta Spec 是否已经同步如果存在openspec/changes/add-user-login/specs/auth/spec.md它会检查对应的 Main Specopenspec/specs/auth/spec.md是否已经包含这些变更。如果还没有同步通常会询问Delta specs have not been synced. Sync now?选择同步后效果类似/opsx:sync add-user-login把ADDED、MODIFIED、REMOVED、RENAMED反映到 Main Spec。5. 移动到带日期的归档目录最终把openspec/changes/add-user-login/移动到openspec/changes/archive/2026-07-12-add-user-login/日期可以帮助确定变更发生的时间和先后顺序。为什么最后必须归档严格地说不归档并不会让已经写好的 Python 或其他业务代码停止运行。程序运行不依赖 archive 状态。但从 OpenSpec 管理角度看归档非常重要。区分“当前状态”和“变更过程”OpenSpec 中有两个不同概念openspec/specs/ 当前系统应该具备什么行为 openspec/changes/ 当前准备改变什么行为开发完成后如果 Change 一直留在 active 目录后续 Agent 会认为它仍在开发中。这可能导致openspec list长期显示已完成项目Agent 不清楚 Change 是否还要继续新 Change 可能重复实现同一功能后续规划把已完成任务当成未完成任务多个 Change 之间更容易出现错误依赖团队无法区分进行中工作与历史工作归档就是明确完成状态这个 Change 已经结束不再继续修改 其最终需求已经进入 Main Spec 原始决策过程保留为历史。防止 Delta Spec 永远悬空Delta Spec 只是“相对于当前规范要改变什么”不是系统长期的规范来源。例如## MODIFIED Requirements ### Requirement: Session Timeout 会话超时从 60 分钟修改为 30 分钟。它只描述变化不一定包含完整需求。长期有效的规范应该整理到openspec/specs/auth/spec.md归档前同步确保最终事实变成### Requirement: Session Timeout The system SHALL expire an inactive session after 30 minutes.后续 Agent 只需要读取 Main Spec就能知道当前系统要求而不必遍历所有历史 Delta。归档后还有作用吗有而且归档记录是 OpenSpec 的重要价值之一。1. 保留需求演变历史Main Spec 告诉你系统现在应该是什么样。Archive 告诉你为什么变成这样当时考虑过什么如何实施的。例如openspec/changes/archive/2026-07-12-add-user-login/可以保留为什么增加登录功能proposal.md技术方案如何选择design.md具体改变了哪些需求Delta Spec实施时拆分了哪些任务tasks.md哪些任务最终完成2. 帮助后续 Agent 理解设计决策后续开发者可能提出把 JWT 改成服务端 SessionAgent 可以查看之前归档的design.md了解当时为什么选择 JWT是否为了无状态部署是否考虑过 Session是否有移动客户端要求是否受现有网关约束这能避免反复讨论或者推翻一个仍然有效的设计决定。不过需要注意正常情况下后续 Agent 应先读取 Main Spec只有需要理解历史原因时才读取 Archive。Archive 不是当前规范的替代品。3. 审计和追溯归档目录可以回答某个需求什么时候加入是哪个 Change 修改的为什么删除一个 Requirement当时预计有哪些风险实现是否覆盖了计划任务某项设计是一次性选择还是长期约束它相当于代码仓库内的轻量变更档案。4. 帮助处理回归和故障如果新功能上线后出现问题可以根据归档内容对照proposal → spec → design → tasks → code判断问题来自原始需求遗漏设计判断错误任务拆分遗漏实现偏离 Spec测试覆盖不足5. 为类似功能提供参考以后新增相似功能时可以参考历史 Change 的Requirement 写法Scenario 边界条件设计模板测试策略任务拆分粒度但不建议直接复制整个归档因为旧约束可能已经失效。Archive 与 Git 历史有什么区别两者互补不能完全替代。内容Git 历史OpenSpec Archive哪些代码发生变化强一般谁在什么时候提交强依赖 Git为什么做这个功能通常较弱强原始需求是什么不一定完整强设计方案是什么不一定记录强验收场景是什么分散在测试中明确任务如何拆分通常没有tasks.mdMain Spec 如何演变需要分析 diffDelta Spec明确描述Git 记录“文件怎么变了”OpenSpec Archive 记录“需求为什么变、计划如何落地”。因此归档目录应当和代码一起提交到 Gitgitaddopenspecgitcommit-mdocs(openspec): archive add-user-login归档后还需要继续修改吗通常不应该直接修改归档内容。归档目录应视为历史快照openspec/changes/archive/2026-07-12-add-user-login/如果后来发现需求需要改变应创建新的 Change/opsx:propose revise-user-login-lockout而不是修改旧归档2026-07-12-add-user-login正确的历史应该是2026-07-12-add-user-login 2026-08-03-add-login-lockout 2026-09-15-adjust-lockout-duration这样才能看出规范如何一步步演变。只有以下情况适合修正归档文件明显拼写错误敏感信息误提交需要安全清理归档过程产生结构错误仓库维护规则明确允许修复历史文档推荐的完整收尾顺序对于重要 Change建议/opsx:apply add-user-login确认 tasks 全部完成再执行/opsx:verify add-user-login运行项目测试pytest检查规范openspec validate--all--strict必要时单独同步/opsx:sync add-user-login查看差异gitdiff-- openspec/specs最后归档/opsx:archive add-user-login再次检查openspec list openspec list--specsopenspec validate--all--strictgitdiff一句话理解/opsx:archive不是把完成的材料“收起来不用了”而是把临时的变更提案结算为当前规范并把提案、设计和任务保存为可追溯的历史证据。后续日常开发读取 Main Spec需要理解“为什么这样设计”时再查 Archive。官方命令说明可参考 OpenSpec/opsx:archive文档。