openspec/changes/archive/ 保存已经完成的 change。归档不是删除，也不是把几个 Markdown 压缩起来；它把一次变化的完整上下文从活动工作区移到带日期的历史目录，同时要求当前主规格已经反映最终行为。

📷 [图片 token=AGwBbQ3p0oPgOTx2bXpc1k1Yn2f（未能下载，见飞书原文）]

归档前要检查什么

OncallAgent 的本地 archive Skill 依次检查 artifact 状态、tasks 完成度和 delta spec 同步状态。

**Artifact 完整性。**proposal、specs、design、tasks 是否都处于 done。缺产物时会警告，不能假装 change 已经完整。

**任务完成度。**统计 - [ ] 与 - [x]。存在未完成项时必须显式确认风险。

**规格同步评估。**逐个比较 delta spec 与 openspec/specs/<capability>/spec.md，说明哪些 requirement 需要新增、修改、删除或重命名。推荐先 sync，再归档。

**实现验证。**archive Skill 自身的文件检查不能替代 openspec-verify-change、测试、类型检查和构建。归档是生命周期动作，不是自动质量认证。

📷 [图片 token=QXknbVmKsoiBTmxxm2ccYX76nPd（未能下载，见飞书原文）]

归档后的目录结构

openspec/changes/archive/
└── 2026-07-11-limit-qwen-embedding-batch-size/
    ├── .openspec.yaml
    ├── proposal.md
    ├── design.md
    ├── tasks.md
    └── specs/
        └── qwen-openai-provider/
            └── spec.md

日期前缀让目录天然表达归档时间，原 change 名保留语义。所有产物一起移动，因此以后既能看到最终需求和设计，也能看到当时的任务状态与 delta。.openspec.yaml 继续保存 schema 和创建时间。

📷 [图片 token=VUIIbCT4gohdOuxbnBpc3ySVncb（未能下载，见飞书原文）]

主规格和 archive 分别回答什么

主规格回答“系统当前应该怎样表现”。archive 回答“某次变化为什么发生、当时考虑了什么、怎样实施和验收”。两者一起才构成可追溯工程记录。

以主案例为例，当前是否要求 Embedding 每批最多 10 条，应查看 main spec；为什么把限制放在 Provider 层、为什么不修改索引业务、当时接受了怎样的吞吐代价，应查看 archive 中的 proposal 和 design。

📷 [图片 token=UKD3bFtUdoTo2kxrvdncZindnio（未能下载，见飞书原文）]

为什么归档目录不能继续开发

直接修改旧 archive 会改写历史，使当时的 proposal、tasks 与实际提交不再对应，也可能让 VitePress WIKI 在不知情的情况下展示被篡改的决策。

如果后续厂商把上限提高到 20，应创建新的 change，例如 raise-qwen-embedding-batch-size，用新的 proposal 解释动机，用 MODIFIED delta 更新 requirement，再记录新的设计和测试。这样演进链完整，而不是把旧的“10”悄悄改成“20”。

📷 [图片 token=MEFmbU3kwo8kKqxTUj3cluA6nwb（未能下载，见飞书原文）]

归档不等于 Git 回滚

OpenSpec 保存意图与规格演进，Git 保存代码和文件版本。需要撤销实现时，应使用经过审查的 Git revert，或创建一个反向 OpenSpec change 来表达新行为；OpenSpec archive 本身不会自动还原代码。

同样，归档目录被保留并不代表可以删除相关测试。测试仍然保护当前行为，除非新的 change 明确改变该行为。

📷 [图片 token=VOesbBzdtoaF5sxdH5scLwI7nfh（未能下载，见飞书原文）]

本地 Skill 与参考站的差异

参考站点的 v2.x 文档把 archive 概括为 CLI 合并 delta 并移动目录。OncallAgent 当前本地 archive Skill 采用 Agent 驱动的 sync 评估，必要时调用同步流程，然后用文件移动把 changeRoot 放入日期目录。教学和面试应以仓库本地 Skill 为准，不应把外部示例说成已经在本机执行的实现。

另一个边界是：通用 archive Skill 在没有 delta specs 时可以继续，但 OncallAgent 的 wiki-sync 要求每个归档都有 delta spec，缺失时默认阻断。仓库级约束比通用流程更严格，这是为了保证每个 WIKI 历史页都能建立规格追踪。

📷 [图片 token=TlCVbCrrnoCo1Hxxkvdc6wxcnmb（未能下载，见飞书原文）]

归档后的下一步

OpenSpec 目录移动完成后，还需要运行仓库级 wiki-sync，并执行 VitePress 构建：

python3 .codex/skills/wiki-sync/scripts/sync_wiki.py archive \
  limit-qwen-embedding-batch-size

npm run docs:build

这两步不会改变产品行为，而是保证归档内容可以在仓库 WIKI 中浏览，索引和 Sidebar 与文件系统一致。OpenSpec 结构本身还应运行 openspec validate --all；若本机没有 CLI，必须明确报告未执行。

📷 [图片 token=YTZmbYjGAoMlyDxcg4VcYbfanCg（未能下载，见飞书原文）]

面试表达

归档不是把需求删掉，而是把已完成 change 从活动区移动到带日期的审计区。归档前检查产物、任务、实现和 delta 同步；归档后主规格保存当前事实，archive 保存决策历史。后续变化新建 change，不能改旧 archive 重写历史。