maintain-agent-docs

维护 Agent 文档

使用时机

在以下情况下使用此技能：

• 用户要求更新、添加、审核或刷新 Agent 文档。
• 会话中发现了持久偏好、重复出现的更正、稳定的项目事实或可复用的工作流。
• 文档可能已过时、存在重复或相互矛盾的内容，或缺少链接。
• 项目需要刷新增量式对话索引。

不要用它来保留一次性任务详情、机密、私人数据、临时调试上下文、特定工单事实或推测性结论。

运行模式

• 始终将文档变更作为提案展示；绝不直接写入文档文件。仅应用用户选择的提案。
• 按目标文件分组提供拟议差异，并注明置信度和依据。用户选择提案前，不要编写文档。
• 索引、本地注册表和运行状态更新属于记录性工作，而非文档编辑。应以原子方式写入，确保保留转录和 Git 进度，无论是否应用提案。
• 分批处理时，将目前学到的候选项保存在临时运行状态 （.agents/state/agent-updated-docs-run-state.json）中，以便后续批次延续同一轮运行。 此文件仅供本地使用，并非事实来源。参见 resources/run-state.md。
• 展示提案后，通过可用的提问工具提出结构化问题，并将每项提案列为一个选项。仅应用用户选择的提案。没有提案时完全跳过提问——回复“没有高信号记忆更新。”即可。索引刷新属于记录性工作，不是提案：绝不要将其列入问题选项。
• 每次调用都应针对当前请求进行全新、完整的处理。除非用户明确要求延续，否则不要复用之前 maintain-agent-docs 运行的结论、提案或“无需更新”结果；索引游标和扫描仅用于限定处理范围及记录工作进度。
• 子 Agent 委派与工作投入：
  • 绝不使用比父 Agent 更强的模型；处理转录或 Git 批次时绝不使用最高或特高推理级别，这类任务不需要。
  • 机械性工作（枚举提交、列出 git diff-tree 文件、阅读差异、跳过锁文件或生成文件）适合使用快速、低推理级别的模型。
  • 阅读差异并判断其对文档的影响，至少需要中等推理能力；有歧义时应通过结构化问题交由用户决定，不要通过更深入的推理自行判断。
  • 候选项综合、去重、置信度评分和冲突处理由父 Agent 完成；不要委派。
• 每批次完成后持久化（具体规则参见资源文档）：
  • 根据 resources/index-format.md 和 resources/run-state.md 写入精简索引；注册表有变更时写入本地注册表；同时写入运行状态。
  • 开始下一批或展示提案之前，确认当前批次的所有项目均已处理并持久化，且所有已发现的剩余来源均已排入后续批次，或已明确说明跳过原因。
  • 只要上下文容量允许安全处理，就自动继续下一批。
  • 绝不要将未完成的扫描报告为已完成。
  • 仅在以下情况下暂停：需要用户决策（缺少 baselineHead 或其无法访问；需要在完整扫描、有界扫描和跳过之间选择；候选项存在歧义）；工作区变更与暂存变更超出批次预算；上下文不足以处理下一批；索引或运行状态写入失败；运行模式或工具策略阻止写入；或运行已完成且提案需要验证。
  • 写入受阻时，询问用户如何处理，或中止。
  • 需要用户输入时，若可用则使用提问工具；否则告知用户可以回复 continue。
• 如果没有有意义的更新，必须准确回复：

No high-signal memory updates.

• 如果进行了文档变更，且处理了转录或 Git 上下文，也要刷新记录状态。
• 如果文档未变更但处理了转录，只刷新记录状态。

工作流

1. 在提出更改前，先阅读当前项目的入口文件和文档。使用 resources/source-discovery.md。
2. 如果存在项目文档笔记和源配置，请加载。使用 resources/project-notes-lookup.md。
3. 如果存在 .agents/state/agent-updated-docs-index.json，请加载。使用 resources/index-format.md。如果索引不是最新版本，或仍包含旧版转录条目，请在进行任何转录或 git 处理之前（步骤 3a-5），使用 resources/index-migrations.md 完成迁移并持久化到当前架构。如果符合该资源中的 When To Ask 条件，请暂停并先询问。 3a. 如果存在 .agents/state/agent-updated-docs-run-state.json，请加载。使用 resources/run-state.md。对于多批次运行，每批处理后都要写入运行状态。
4. 先处理转录源，再处理 git：
   • 从紧凑索引水位线、近期安全窗口和本地注册表（若有）中选择转录文件。
   • 每批最多处理 transcriptBatchLimit 个。
   • 通过紧凑索引、本地注册表（有更改时）和运行状态，持久化源进度。
   • 达到批次上限时，先持久化该批次；如果仍有待处理内容且下一批可安全处理，则自动继续。转录全部处理完毕前，不要开始或恢复 git 处理。
5. 仅在转录处理完毕后，运行 git 文档影响检查：
   • 在任何提交扫描前，始终检查当前工作树和已暂存的更改。
   • 如果工作树与已暂存更改的总量超过批次预算，请停止并让用户提交更改或以其他方式缩减更改。每次调用都会重新读取大量未提交的更改，并阻碍可靠推进。
   • 如果存在 git.sweep，请先恢复它，再开始新扫描。
   • 如果没有 git.baselineHead，或存储的基准不可用，或不是当前目标的祖先，请在 git 处理前提出结构化问题。提供完整扫描、有限近期窗口或仅处理转录/跳过 git 这几个选项。未经用户明确确认，绝不要开始完整历史扫描。
   • 仅对所选范围保证穷尽处理；明确排除的较早历史属于范围外，不算已处理。 5a. 在结束影响检查前，按照 resources/source-discovery.md 的说明，逐个提交列出所选范围内提交更改的文件清单，以及工作树和已暂存更改。将每个路径与 resources/merge-policy.md 中的影响区域进行匹配。提交消息、摘要和最终树差异不能替代逐提交文件清单。 5b. 在判断是否需要更改文档前，阅读更改文件的实际差异：
   • 使用 resources/source-discovery.md 中的确定性提交列表。
   • 使用 resources/index-format.md 中定义的字段存储扫描状态，恢复时重新构建相同列表。
   • 针对当前批次范围运行差异统计；当工作树和已暂存更改符合预算时，也要运行相应统计。
   • 对当前批次中的每个更改文件，在判断文档影响前，阅读相关提交、已暂存或工作树差异。
   • 跳过明显不会影响任何已记录约定的文件（锁文件、生成产物、资源文件更新）。
   • 阅读差异达到约 300 KB 或约 50 个文件时，持久化该批次；安全时自动继续。绝不要对未阅读的差异仅凭文件名做判断。
6. 仅从每个已完成的转录或 git 批次中提取持久、可复用的信号：
   • 反复出现的用户偏好或纠正
   • 稳定的工作区事实
   • 可重复执行的工作流
   • 会影响未来 Agent 行为的架构、工具或流程事实
7. 对有用但不确定、含糊、敏感或相互矛盾的候选内容，在用于文档前提出结构化问题。
8. 应用 resources/merge-policy.md 中的合并和放置规则。
9. 验证结果：
   • AGENTS.md 中的链接仍可访问
   • 未引入重复或矛盾的规则
   • 每个 SKILL.md 均少于 500 行
   • 资源链接保持一层深度
   • 未直接编辑 .cursor/rules
10. 每个转录或 git 批次处理后，以及转录或 git 全部完成后，都要以原子方式刷新索引。写入失败时必须保留原有索引，不得更改。
11. 仅在运行完成且候选内容已提出、接受、拒绝或判定为无意义并丢弃后，才清除临时运行状态。

安全规则

• 切勿在索引中存储对话记录内容、对话记录摘要、摘录、绝对本地路径、机密或私人数据。
• 让运行状态保持实用，但不要鲁莽：其中可以包含比索引更丰富的临时候选信息，但不要故意存储明显的机密、令牌、私钥、.env 值、生产环境转储文件或原始私人日志。
• 切勿将包含私人路径、姓名、令牌、.env 值、客户数据或敏感工单详情的原始对话记录片段复制到文档中。
• 如果 skills-lock.json 将某项技能标记为 sourceType: "github"，则应将该技能视为由上游所有。不要直接修改该技能或其资源；请将项目专属覆盖内容放在项目文档、规则、笔记或单独的项目自有技能中。
• 如果某个已发现元素的含义、范围、持久性、敏感性或放置位置不确定，请先询问，再使用它。
• 如果新信号与现有文档相矛盾，请在提案中指出冲突，并在更改前征求确认；除非现有文档明显有误。
• 当较新的重复证据表明旧约定已过时，应移除或替换过时文档；不要只追加新规则。

资源

• resources/source-discovery.md：要检查的文档、对话记录和 git 来源。
• resources/project-notes-lookup.md：项目本地文档笔记和来源配置查询。
• resources/index-format.md：当前紧凑型索引架构、本地对话记录注册表、git 扫描字段和常规原子写入。
• resources/index-migrations.md：仅在需要时加载的旧版索引迁移流程。
• resources/run-state.md：跨对话记录和 git 批次的临时本地候选状态。
• resources/merge-policy.md：信号筛选、置信度、放置位置、冲突、提案格式和验证。