尧图网页设计 
Fleet 仓库 OpenSpec 工作流如何安全归档一个已完成的变更【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet导读在 FleetGo 后端 React/TypeScript 前端的设备管理与安全项目仓库中OpenSpec 是一套可选的 spec-driven 工作流工具用于在写代码之前为较大的变更留下书面记录。本篇文章聚焦这套工作流的最后一个环节——归档Archive当某个变更实现完毕并合并后如何将它从openspec/changes/name/移入openspec/changes/archive/并同步其规格specs。读完本文你将掌握openspec archive技能的完整执行步骤、delta spec 同步评估逻辑、任务与产物artifacts的完成度检查方法以及各种边界情况的处理方式。OpenSpec 与 Fleet 仓库的explore → propose → apply → archive流程在深入归档之前先理解 OpenSpec 在 Fleet 仓库中的定位。根据仓库根目录下的 openspec/README.mdOpenSpec 是可选的辅助工具不是开发流程的强制部分团队也未将其定为必须遵循的规范使用它无需任何 PR。它适用于如下场景横跨数据存储、服务、端点和 UI 的跨切面功能涉及多个文件、需要在实现前就达成一致形态的重构希望在投入代码之前与人或 AI协作评审的 RFC 式设计。反之绝大多数日常工作bug 修复、小功能、依赖升级、文档微调不需要它——如果一次改动塞进一条 PR 描述就够了那就直接写 PR 描述。OpenSpec 的完整工作流是四个阶段explore → propose → apply → archiveexplore对应 .claude/skills/openspec-explore/SKILL.md思考想法不写代码、不产出产物propose对应 .claude/skills/openspec-propose/SKILL.md在openspec/changes/change-name/下生成proposal.md做什么、为什么、design.md怎么做、tasks.md实现步骤apply对应 .claude/skills/openspec-apply-change/SKILL.md按tasks.md逐步实现- [ ]→- [x]标记完成archive本文主题将已完成变更移入openspec/changes/archive/并同步 specs。步骤可以自由跳过大多数变更只需proposeapply小型改动甚至只走explore。仓库中实际的 in-flight 变更都位于 changes/ 目录如16797-csv-formula-injection、43181-cancel-mdm-commands、fix-pack-config-cache-label-scoping等归档后它们会被移动到openspec/changes/archive/。OpenSpec CLI 对归档目录拥有所有权openspec update会覆盖其中的任何本地改动因此不要手工编辑.claude/skills/openspec-*/与.claude/commands/opsx/下的文件行为定制应通过 openspec/config.yaml 完成。归档前准备环境与目录结构归档技能.claude/skills/openspec-archive-change/SKILL.md的元数据声明了两个前置条件license: MIT由 openspec 生成generatedBy: 1.3.1版本 1.0compatibility: Requires openspec CLI——所有归档操作都依赖openspec命令它必须在$PATH上。按 openspec/README.md 的安装方式macOS 上可通过 Homebrew 安装brew install openspec需要注意的是阅读openspec/下的 Markdown 产物不需要 CLI但执行归档流程必须依赖它。CLI 的相关命令包括openspec list --json列出可用变更openspec status --change name --json查看变更的产物完成状态归档动作本身由mkdir与mv完成见下文步骤五。归档流程遵循以下目录约定路径含义openspec/changes/name/进行中的提案与任务in-flight proposals and tasksopenspec/changes/archive/已完成的变更归档openspec/specs/已接受的正式规格accepted specificationsopenspec/config.yaml项目上下文与 AI 必须遵守的规则指向.claude/CLAUDE.md仓库内的 openspec/config.yaml 是当前配置的实例schema: spec-drivencontext中写明Fleet: Go backend React/TypeScript frontend for device management and security权威项目指引在.claude/CLAUDE.md。同时定义了按产物注入的rules当前proposal与tasks的规则列表为空会静默跳过。归档的六步流程归档技能定义了清晰的六步流程每一步都有明确的执行与确认规则。注意该技能描述与仓库中的 slash 命令 .claude/commands/opsx/archive.md/opsx:archive在语义上完全一致前者是可供 Agent 调用的 Skill后者是用户可直接触发的命令。第一步没有指定 change 名称时提示用户选择归档需要一个明确的变更名称。输入规则用户可以显式指定 change 名称如/opsx:archive add-auth如果未指定先检查能否从对话上下文中推断如果名称含糊或存在歧义必须让用户选择不能猜测。选择方式为openspec list --json用AskUserQuestion 工具让用户从列表中挑选。展示时只显示活跃变更active changes即尚未归档的变更如果可用同时展示每个变更所使用的 schema。关键约束IMPORTANT不要猜测或自动选择一个变更始终让用户自己决定。第二步检查产物artifact完成状态选定变更后查询其产物完成情况openspec status --change name --json解析返回的 JSON重点关注两个字段schemaName当前使用的 workflow例如spec-drivenartifacts产物列表每个产物带有状态done或其他。如果存在任何状态不是done的产物需要展示警告列出所有未完成的产物用AskUserQuestion 工具向用户确认是否仍要继续归档用户确认后继续。这个检查对应openspec status --json中的 artifact graph它是判断完成度的权威依据。第三步检查任务tasks完成状态读取任务文件通常是tasks.md由 propose 阶段生成统计完成情况统计标记为- [ ]的未完成任务数量统计标记为- [x]的已完成任务数量。处理规则如果发现未完成任务展示警告显示未完成任务数量用AskUserQuestion 工具向用户确认是否继续确认后继续如果不存在任务文件则直接跳过任务相关警告继续流程。从仓库结构看每个变更目录如 changes/43181-cancel-mdm-commands在 propose 阶段会生成tasks.md作为实现的清单归档前应已全部勾选。第四步评估 delta spec 同步状态这是归档流程中最具决策价值的一步。首先检查变更目录下是否存在 delta specsopenspec/changes/name/specs/如果不存在delta specs则跳过同步提示直接进入归档。如果存在则进行同步评估将每个 delta spec 与openspec/specs/capability/spec.md中对应的主 spec 逐条对比确定将被应用的具体变更类型新增 adds、修改 modifications、移除 removals、重命名 renames在提示用户之前展示一个合并后的摘要combined summary而不是零散地逐个询问。随后给出提示选项选项取决于同步状态如果主 spec 需要更新Sync now (recommended)立即同步推荐或 Archive without syncing不同步直接归档如果已经同步过Archive now直接归档、Sync anyway无论如何再同步一次或 Cancel取消。如果用户选择同步则通过 Task 工具subagent_type:general-purpose调用 openspec-sync-specs 技能prompt 中必须携带已分析的 delta spec 摘要Use Skill tool to invoke openspec-sync-specs for change . Delta spec analysis: 无论用户是否选择同步之后都继续执行归档。第五步执行归档归档动作本身由两个文件系统操作完成创建归档目录若不存在mkdir -p openspec/changes/archive生成目标名称使用当前日期YYYY-MM-DD-change-name。检查目标是否已存在已存在以错误结束流程建议重命名现有归档或改换日期不存在将变更目录移动到归档目录mv openspec/changes/name openspec/changes/archive/YYYY-MM-DD-name需要注意.openspec.yaml随目录一起移动它本来就随目录一起迁移归档后依然保留在变更目录内无需单独处理。第六步显示归档总结归档完成后展示包含以下信息的总结变更名称Change name所使用的 schemaSchema that was used归档位置Archive locationspecs 是否已同步如果适用关于任何警告未完成产物/任务的说明。标准输出模板成功已同步## Archive Complete **Change:** change-name **Schema:** schema-name **Archived to:** openspec/changes/archive/YYYY-MM-DD-name/ **Specs:** ✓ Synced to main specs All artifacts complete. All tasks complete.成功无 delta specs## Archive Complete **Change:** change-name **Schema:** schema-name **Archived to:** openspec/changes/archive/YYYY-MM-DD-name/ **Specs:** No delta specs All artifacts complete. All tasks complete.成功但有警告## Archive Complete (with warnings) **Change:** change-name **Schema:** schema-name **Archived to:** openspec/changes/archive/YYYY-MM-DD-name/ **Specs:** Sync skipped (user chose to skip) **Warnings:** - Archived with 2 incomplete artifacts - Archived with 3 incomplete tasks - Delta spec sync was skipped (user chose to skip) Review the archive if this was not intentional.失败归档目标已存在## Archive Failed **Change:** change-name **Target:** openspec/changes/archive/YYYY-MM-DD-name/ Target archive directory already exists. **Options:** 1. Rename the existing archive 2. Delete the existing archive if its a duplicate 3. Wait until a different date to archive护栏规则Guardrails与最佳实践归档技能在结尾明确了八条护栏规则它们是流程正确性的保障未提供 change 名称时始终提示选择——绝不自动猜测使用 artifact graphopenspec status --json检查完成度而非凭印象判断不要用警告阻塞归档——警告只需告知并确认即可继续归档时保留.openspec.yaml——它随目录一起移动无需额外处理展示清晰的发生了什么——完整呈现归档结果与 spec 同步状态如果需要同步采用 openspec-sync-specs 的 agent-driven 方式如果存在 delta specs必须先执行同步评估并在提示前展示合并摘要。从实现角度看这套流程的设计哲学是告知并确认但不阻塞未完成的产物、未完成的任务、被跳过的 spec 同步都不会成为归档的硬性障碍但每一项都必须显式地告知用户并获得确认。这与 OpenSpec 的定位一致——根据 openspec/README.mdopenspec/中的产物应当被当作文档而非契约代码评审仍然是最终的事实来源source of truth。与相邻技能的关系归档是整个 OpenSpec 工作流的收尾环节它与前序技能构成完整的闭环openspec-explore/SKILL.md探索模式只思考不实现其产物是捕获思考的提案/设计/specsopenspec-propose/SKILL.md一次生成 proposal、design、tasks 三个产物openspec-apply-change/SKILL.md实现 tasks全部完成后会提示Ready to archive this change——这正是调用归档技能的时机。对应地用户也可以通过/opsx:archive命令直接触发同样的归档逻辑见 .claude/commands/opsx/archive.md。常见问题Q归档后还能找到变更内容吗可以。变更目录被完整移动到openspec/changes/archive/YYYY-MM-DD-name/其中的 proposal、design、tasks、specs 以及.openspec.yaml全部保留。Q归档时发现了未完成的任务怎么办流程不会强行阻止但会展示警告并要求用户确认。如果这不是有意为之建议在归档前先完成剩余任务或重新打开变更继续实现。Qdelta specs 和主 specs 不同步怎么办推荐选择 Sync nowAgent 会调用 openspec-sync-specs依据你看到的 delta spec 分析摘要把变更同步到openspec/specs/capability/spec.md下的主 specs。Qopenspec/changes/archive/下的内容可以手工修改吗不可以。OpenSpec CLI 拥有这些目录包括.claude/skills/openspec-*/与.claude/commands/opsx/openspec update会覆盖本地改动。如有定制需求应通过 openspec/config.yaml 配置或复制技能到新名称下避免被更新器覆盖。通过本篇文章梳理的六步流程与护栏规则你可以在 Fleet 仓库中规范、可追溯地完成每次变更的归档让openspec/changes/始终只保留真正在途的工作而让已沉淀的设计进入archive/与specs/成为团队长期可检索的决策记录。【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Fleet 仓库 OpenSpec 工作流：如何安全归档一个已完成的变更
Fleet 仓库 OpenSpec 工作流如何安全归档一个已完成的变更【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet导读在 FleetGo 后端 React/TypeScript 前端的设备管理与安全项目仓库中OpenSpec 是一套可选的 spec-driven 工作流工具用于在写代码之前为较大的变更留下书面记录。本篇文章聚焦这套工作流的最后一个环节——归档Archive当某个变更实现完毕并合并后如何将它从openspec/changes/name/移入openspec/changes/archive/并同步其规格specs。读完本文你将掌握openspec archive技能的完整执行步骤、delta spec 同步评估逻辑、任务与产物artifacts的完成度检查方法以及各种边界情况的处理方式。OpenSpec 与 Fleet 仓库的explore → propose → apply → archive流程在深入归档之前先理解 OpenSpec 在 Fleet 仓库中的定位。根据仓库根目录下的 openspec/README.mdOpenSpec 是可选的辅助工具不是开发流程的强制部分团队也未将其定为必须遵循的规范使用它无需任何 PR。它适用于如下场景横跨数据存储、服务、端点和 UI 的跨切面功能涉及多个文件、需要在实现前就达成一致形态的重构希望在投入代码之前与人或 AI协作评审的 RFC 式设计。反之绝大多数日常工作bug 修复、小功能、依赖升级、文档微调不需要它——如果一次改动塞进一条 PR 描述就够了那就直接写 PR 描述。OpenSpec 的完整工作流是四个阶段explore → propose → apply → archiveexplore对应 .claude/skills/openspec-explore/SKILL.md思考想法不写代码、不产出产物propose对应 .claude/skills/openspec-propose/SKILL.md在openspec/changes/change-name/下生成proposal.md做什么、为什么、design.md怎么做、tasks.md实现步骤apply对应 .claude/skills/openspec-apply-change/SKILL.md按tasks.md逐步实现- [ ]→- [x]标记完成archive本文主题将已完成变更移入openspec/changes/archive/并同步 specs。步骤可以自由跳过大多数变更只需proposeapply小型改动甚至只走explore。仓库中实际的 in-flight 变更都位于 changes/ 目录如16797-csv-formula-injection、43181-cancel-mdm-commands、fix-pack-config-cache-label-scoping等归档后它们会被移动到openspec/changes/archive/。OpenSpec CLI 对归档目录拥有所有权openspec update会覆盖其中的任何本地改动因此不要手工编辑.claude/skills/openspec-*/与.claude/commands/opsx/下的文件行为定制应通过 openspec/config.yaml 完成。归档前准备环境与目录结构归档技能.claude/skills/openspec-archive-change/SKILL.md的元数据声明了两个前置条件license: MIT由 openspec 生成generatedBy: 1.3.1版本 1.0compatibility: Requires openspec CLI——所有归档操作都依赖openspec命令它必须在$PATH上。按 openspec/README.md 的安装方式macOS 上可通过 Homebrew 安装brew install openspec需要注意的是阅读openspec/下的 Markdown 产物不需要 CLI但执行归档流程必须依赖它。CLI 的相关命令包括openspec list --json列出可用变更openspec status --change name --json查看变更的产物完成状态归档动作本身由mkdir与mv完成见下文步骤五。归档流程遵循以下目录约定路径含义openspec/changes/name/进行中的提案与任务in-flight proposals and tasksopenspec/changes/archive/已完成的变更归档openspec/specs/已接受的正式规格accepted specificationsopenspec/config.yaml项目上下文与 AI 必须遵守的规则指向.claude/CLAUDE.md仓库内的 openspec/config.yaml 是当前配置的实例schema: spec-drivencontext中写明Fleet: Go backend React/TypeScript frontend for device management and security权威项目指引在.claude/CLAUDE.md。同时定义了按产物注入的rules当前proposal与tasks的规则列表为空会静默跳过。归档的六步流程归档技能定义了清晰的六步流程每一步都有明确的执行与确认规则。注意该技能描述与仓库中的 slash 命令 .claude/commands/opsx/archive.md/opsx:archive在语义上完全一致前者是可供 Agent 调用的 Skill后者是用户可直接触发的命令。第一步没有指定 change 名称时提示用户选择归档需要一个明确的变更名称。输入规则用户可以显式指定 change 名称如/opsx:archive add-auth如果未指定先检查能否从对话上下文中推断如果名称含糊或存在歧义必须让用户选择不能猜测。选择方式为openspec list --json用AskUserQuestion 工具让用户从列表中挑选。展示时只显示活跃变更active changes即尚未归档的变更如果可用同时展示每个变更所使用的 schema。关键约束IMPORTANT不要猜测或自动选择一个变更始终让用户自己决定。第二步检查产物artifact完成状态选定变更后查询其产物完成情况openspec status --change name --json解析返回的 JSON重点关注两个字段schemaName当前使用的 workflow例如spec-drivenartifacts产物列表每个产物带有状态done或其他。如果存在任何状态不是done的产物需要展示警告列出所有未完成的产物用AskUserQuestion 工具向用户确认是否仍要继续归档用户确认后继续。这个检查对应openspec status --json中的 artifact graph它是判断完成度的权威依据。第三步检查任务tasks完成状态读取任务文件通常是tasks.md由 propose 阶段生成统计完成情况统计标记为- [ ]的未完成任务数量统计标记为- [x]的已完成任务数量。处理规则如果发现未完成任务展示警告显示未完成任务数量用AskUserQuestion 工具向用户确认是否继续确认后继续如果不存在任务文件则直接跳过任务相关警告继续流程。从仓库结构看每个变更目录如 changes/43181-cancel-mdm-commands在 propose 阶段会生成tasks.md作为实现的清单归档前应已全部勾选。第四步评估 delta spec 同步状态这是归档流程中最具决策价值的一步。首先检查变更目录下是否存在 delta specsopenspec/changes/name/specs/如果不存在delta specs则跳过同步提示直接进入归档。如果存在则进行同步评估将每个 delta spec 与openspec/specs/capability/spec.md中对应的主 spec 逐条对比确定将被应用的具体变更类型新增 adds、修改 modifications、移除 removals、重命名 renames在提示用户之前展示一个合并后的摘要combined summary而不是零散地逐个询问。随后给出提示选项选项取决于同步状态如果主 spec 需要更新Sync now (recommended)立即同步推荐或 Archive without syncing不同步直接归档如果已经同步过Archive now直接归档、Sync anyway无论如何再同步一次或 Cancel取消。如果用户选择同步则通过 Task 工具subagent_type:general-purpose调用 openspec-sync-specs 技能prompt 中必须携带已分析的 delta spec 摘要Use Skill tool to invoke openspec-sync-specs for change . Delta spec analysis: 无论用户是否选择同步之后都继续执行归档。第五步执行归档归档动作本身由两个文件系统操作完成创建归档目录若不存在mkdir -p openspec/changes/archive生成目标名称使用当前日期YYYY-MM-DD-change-name。检查目标是否已存在已存在以错误结束流程建议重命名现有归档或改换日期不存在将变更目录移动到归档目录mv openspec/changes/name openspec/changes/archive/YYYY-MM-DD-name需要注意.openspec.yaml随目录一起移动它本来就随目录一起迁移归档后依然保留在变更目录内无需单独处理。第六步显示归档总结归档完成后展示包含以下信息的总结变更名称Change name所使用的 schemaSchema that was used归档位置Archive locationspecs 是否已同步如果适用关于任何警告未完成产物/任务的说明。标准输出模板成功已同步## Archive Complete **Change:** change-name **Schema:** schema-name **Archived to:** openspec/changes/archive/YYYY-MM-DD-name/ **Specs:** ✓ Synced to main specs All artifacts complete. All tasks complete.成功无 delta specs## Archive Complete **Change:** change-name **Schema:** schema-name **Archived to:** openspec/changes/archive/YYYY-MM-DD-name/ **Specs:** No delta specs All artifacts complete. All tasks complete.成功但有警告## Archive Complete (with warnings) **Change:** change-name **Schema:** schema-name **Archived to:** openspec/changes/archive/YYYY-MM-DD-name/ **Specs:** Sync skipped (user chose to skip) **Warnings:** - Archived with 2 incomplete artifacts - Archived with 3 incomplete tasks - Delta spec sync was skipped (user chose to skip) Review the archive if this was not intentional.失败归档目标已存在## Archive Failed **Change:** change-name **Target:** openspec/changes/archive/YYYY-MM-DD-name/ Target archive directory already exists. **Options:** 1. Rename the existing archive 2. Delete the existing archive if its a duplicate 3. Wait until a different date to archive护栏规则Guardrails与最佳实践归档技能在结尾明确了八条护栏规则它们是流程正确性的保障未提供 change 名称时始终提示选择——绝不自动猜测使用 artifact graphopenspec status --json检查完成度而非凭印象判断不要用警告阻塞归档——警告只需告知并确认即可继续归档时保留.openspec.yaml——它随目录一起移动无需额外处理展示清晰的发生了什么——完整呈现归档结果与 spec 同步状态如果需要同步采用 openspec-sync-specs 的 agent-driven 方式如果存在 delta specs必须先执行同步评估并在提示前展示合并摘要。从实现角度看这套流程的设计哲学是告知并确认但不阻塞未完成的产物、未完成的任务、被跳过的 spec 同步都不会成为归档的硬性障碍但每一项都必须显式地告知用户并获得确认。这与 OpenSpec 的定位一致——根据 openspec/README.mdopenspec/中的产物应当被当作文档而非契约代码评审仍然是最终的事实来源source of truth。与相邻技能的关系归档是整个 OpenSpec 工作流的收尾环节它与前序技能构成完整的闭环openspec-explore/SKILL.md探索模式只思考不实现其产物是捕获思考的提案/设计/specsopenspec-propose/SKILL.md一次生成 proposal、design、tasks 三个产物openspec-apply-change/SKILL.md实现 tasks全部完成后会提示Ready to archive this change——这正是调用归档技能的时机。对应地用户也可以通过/opsx:archive命令直接触发同样的归档逻辑见 .claude/commands/opsx/archive.md。常见问题Q归档后还能找到变更内容吗可以。变更目录被完整移动到openspec/changes/archive/YYYY-MM-DD-name/其中的 proposal、design、tasks、specs 以及.openspec.yaml全部保留。Q归档时发现了未完成的任务怎么办流程不会强行阻止但会展示警告并要求用户确认。如果这不是有意为之建议在归档前先完成剩余任务或重新打开变更继续实现。Qdelta specs 和主 specs 不同步怎么办推荐选择 Sync nowAgent 会调用 openspec-sync-specs依据你看到的 delta spec 分析摘要把变更同步到openspec/specs/capability/spec.md下的主 specs。Qopenspec/changes/archive/下的内容可以手工修改吗不可以。OpenSpec CLI 拥有这些目录包括.claude/skills/openspec-*/与.claude/commands/opsx/openspec update会覆盖本地改动。如有定制需求应通过 openspec/config.yaml 配置或复制技能到新名称下避免被更新器覆盖。通过本篇文章梳理的六步流程与护栏规则你可以在 Fleet 仓库中规范、可追溯地完成每次变更的归档让openspec/changes/始终只保留真正在途的工作而让已沉淀的设计进入archive/与specs/成为团队长期可检索的决策记录。【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考