maintain-skills

维护技能

保持此库中引入的技能与上游同步，同时保留适合此环境的轻量本地调整。调整约定定义了此环境，并说明如何评估每项上游变更。维护指南介绍了这些步骤所用的辅助命令、运行时状态、检查和分支规则。

以以下两种模式之一运行：

• 上游：采纳每项技能自其已审核位置以来的上游变更，引入新的上游技能，并审核自上次运行以来文件发生变更的技能。
• 审计：完成上游工作后，逐一处理沿用事项、保真度待办项、待处理技能和过期审核，并根据当前工具、文档和仓库约定检查每项技能。

用户或计划任务可以指定模式；否则由 begin 选择。只有明确指定的技能子集才会缩小任一模式的范围。

全程使用 /swarm。为每位工作者分配一个部分，例如一组来源、一批技能或一项修复，并提供确切的本地修订版本、不可变候选版本、调整约定、证据要求以及允许其写入的文件。工作者直接完成各自的部分，不要再启动另一个协调者。协调者负责获取来源、管理检查点和规范文档，并负责集成，同时收集每位工作者的结果；失败或缺失的结果仍保持待处理。若不进行委派，则按顺序完成工作，并在运行报告中注明因此失去的独立性。

1. 开始

阅读仓库的 AGENTS.md、调整约定和维护指南。运行 begin。若它报告锁已被占用，则停止并指出持有锁的运行。否则，此运行将持有该锁，直到运行 release。

记录 begin 的 leftovers（即某次运行结束但尚未交付的编辑），供报告使用；随后按照指南中的分支规则同步两个工作树，此操作会丢弃这些编辑。此类工作会自行恢复：只有在交付后，运行才会结算其检查点和沿用事项，因此，中断运行中的事项在 begin 找到的状态下仍保持待处理。若 begin 报告了 legacyNextActions，则将该文件转换为 next-actions.json。阅读开放维护 PR 上，以及问题所链接的 PR 上，自 commentsSince 之后发布的负责人评论。使用 scripts/check-installs.py 检查已安装副本；若副本已过期，则按 AGENTS.md 的说明刷新。使用库工作树和 begin 的检查点运行 inventory --resume。

**完成条件：**此运行持有锁，两个工作树均符合各自的同步规则，并且你已掌握 begin 返回的模式、检查点、问题、沿用事项和遗留编辑，commentsSince 之后的所有负责人评论，最新的安装检查，以及包含 changedSince、contextChanged 和 staleReviews 列表的清单；或者，运行因锁已被占用而停止，并指出持有锁的运行。

2. 查找变更

运行 fetch，然后运行带有 --resume 的 compare --fetch。将清单、获取结果和比较报告保存到运行文件夹中。按以下顺序建立工作清单，这也是处理顺序：

1. 尚未应用的所有者答复和评论，以及已推送但没有 PR 的维护分支。
2. 已更改的上游技能和共享输入，以及获取失败的每个来源。
3. 目录套件中的新增、移除或移动的上游技能。
4. changedSince 中的技能（包括新技能），以及 contextChanged 中的输入。
5. 仅限审计模式：待处理事项，先处理逾期事项；清单中的 fidelityBacklog；检查点列为待处理的技能；然后是最旧的 staleReviews，最多占库中技能的四分之一。

在上游模式下，如果第 1 至 4 项均为空，则根据比较报告保存检查点，清理旧运行，运行 release，然后停止。无需为无变更的运行创建分支、检查、评审、PR 或报告。

**完成条件：**每个尚未应用的所有者答复、已推送但没有 PR 的分支、比较报告条目、获取失败的来源、changedSince 技能和 contextChanged 输入，以及在审计模式下的每个待处理事项、fidelityBacklog 记录、待处理技能和最旧的 staleReviews（最多占库中技能的四分之一），都已列入工作清单或记录为未变更；或者运行已作为无变更运行停止。

3. 决策并修复

按照指南的分支规则，在维护分支上编辑。依据适配契约决定如何处理每项上游变更，并按契约所述记录每项决策。使用 /writing-for-agents 将修复分派给相互隔离的编写者，并检查每份返回的差异。按照契约所述导入新的上游技能并提出弃用建议。如果变更涉及共享所有者，请检查其在两个套件中的使用方。

对于 changedSince 中的每项技能，检查其编辑是否保留了记录的适配内容和仓库约定。对于 contextChanged 中的每项输入，阅读其相对于检查点 libraryRevision 的差异，并列出每项受其评审影响的技能。在审计模式下，根据每项技能所支持的环境，检查工具名称、命令、链接和实践；从已公开的工具架构、已安装的版本和本地帮助输出着手。使用 /writing-for-agents 评审第一方技能和本地适配文本；对于来源文本，遵循契约的最小偏离规则。

对每个你编辑的来源技能或在 changedSince 中发现的来源技能运行契约规定的保真度检查；在审计模式下，也要对待处理记录运行检查。

对于检查点未跟踪的修复（例如本次运行在某项技能或本技能自身文本中发现的问题），在编辑前将其添加到 next-actions.json 并注明今天的日期，以便运行中断后仍会保留为待处理事项。按照契约中对决策记录的说明，将每项需要所有者处理的事项作为问题提出。只有在预算耗尽或需要等待后续上游修订时，才将事项列为待处理：在 next-actions.json 中保留或添加该条目，并注明它首次被列为待处理的日期。逾期待处理事项已经经历过一次审计；请在本次审计中完成，或将其作为问题提出。

**完成条件：**工作清单中的每项事项都已采纳、适配、排除、作为问题提出，或连同原因记录在 next-actions.json 中；每项逾期待处理事项都已完成或作为问题提出；已列出每项 contextChanged 输入所影响的技能；每项已编辑或在本地更改的来源技能均通过两个方向的保真度检查。

4. 验证

从头到尾阅读已更改的说明，并运行维护指南中的检查。在一个小型隔离示例中试用已更改的脚本或工作流，并确认撤回修复后，每个新增的回归测试都会失败。安排一次独立的最终审查，检查确切的差异、相关决策、保真度和覆盖范围，并处理审查发现的问题。重新枚举技能，将运行期间新增的技能纳入覆盖范围。

只有在某项技能的整个上游差异都已作出决定且检查通过后，才推进该技能的已审阅位置。

**完成条件：**检查通过；撤回修复后每个新增的回归测试都会失败；每项最终审查发现的问题都已修复、提出询问或记录待处理；每个已推进的已审阅位置所涵盖的整个差异都已作出决定。

5. 交付

在各自独立的维护分支上提交库更改和对此技能自身流程的更改，按照指南的推送规则分别推送，并在操作授权范围内为每个分支创建或更新一个草稿 PR：计划运行时使用计划提示词的授权；受请求触发运行时使用用户请求的授权。验证每个 PR 后，结算运行时状态：移除其提交已完成的待处理项或其描述要求移除的待处理项，以及其提交已记录答案的问题；然后保存检查点，纳入本次运行已完成的本地审查。若第 3 步审阅了上下文更改，则添加 --context-reviewed 并列出受影响的技能；检查点绝不推进任何位置。清理旧运行，然后执行 release。

报告更改内容、等待负责人答复的问题、失败项（例如失败的数据源和丢弃的遗留项），以及仍待完成的覆盖范围。

到达预算收尾节点时，不要开始新的工作清单项：验证、交付并保存已完成内容的检查点，其余内容作为待处理项记录。

**完成条件：**每个 PR 都是草稿，其托管仓库上的头提交与已推送的提交一致，且描述列出所有未解决的问题，并注明指南要求的每个 /usage-review 合约；运行时状态已结算，且在验证完成后保存了检查点；报告已写好；所有操作都在授权范围内；并且锁已释放。