日常文档维护

让下一位使用者或开发者读到的说明与本次变化一致。只维护受影响的文档；只读任务只报告差异。

需要接入收尾时，由 agent-entrypoints 在项目共享入口配置以下约定，Skill 名替换为实际可读取路径，外部插件使用完整路径：

任务改变了文档承载的行为、接口、路径、需求或需持续交接的风险时，按 docs-maintenance 同步受影响主记录；没有这些变化则直接交付，只读任务只报告差异。

“一轮”指完整任务，维护本身不递归触发。入口约定由 Agent 执行，Skill 文件本身不会自动运行，也不自行安装 Hook。

1. 确定这次改变了什么

结合本轮对话、实际 diff 和确认材料，说清什么行为变了、影响谁、依据是什么，不只列改过的文件。例如“订单取消时限从 30 分钟改为 60 分钟”，会影响用户说明与验收条件。由模块变更流程进入时，复用任务基线、影响清单和回归结果。

区分已确认需求、实际实现、上线状态与验证结果；测试失败或未运行不能写成已验收。未改变文档事实的内部修复、样式调整或问答，在回复说明依据后结束，不为收尾运行全量审计或创建记录。缺少 Git 基线时依据现有材料核对，标出无法确定的旧状态。

2. 找到受影响的说明，就地更新

先复用本轮有效影响分析：范围、版本及未提交变化一致，且包含该范围要求的审计结果；出现新变化、失败或未覆盖项时，不沿用旧结论，按 skills/engineering/change-impact/SKILL.md 的“按事实核对文档”补查。它提供候选与依据，本 Skill 判断并修改正文。沿项目入口补查相关说明；零命中不等于无影响。

对每处说明判断：下一位读者照着做，是否还会得到文档承诺的结果？ 根据变化定位现有主记录：

沿用项目实际路径，不为凑齐表格创建文件。MAP 只管导航事实，不记录每次改动；LOG 只保留重要历史，不复制 MAP 或普通测试结果。小任务可以零文档变更；确有事实变化才修改主记录和必要引用；不默认联动写入 STATUS、LOG、产品阶段和验收记录。同一结论在回复或既有记录留一份可追溯证据，其他位置需要时引用；项目明确要求的历史或门禁仍执行。在获准范围内修改过时条目、失效引用和重复的现役正文，保留条件、例外和必要案例。

例如，接口字段改名后，更新当前接入指南和调用示例；历史日志中的旧字段名可以保留。实现与已确认需求冲突时分别记录依据，不能直接把需求改成代码现状；主源不明或无法裁决时列出待确认项。

3. 验证更新，并交代剩余差异

先检查受影响的路径、引用与正文，再运行项目已有相关检查；示例或其依赖变化时按下节验证。旧结论依赖的行为或条件变化后须复验，未运行标待复验。

示例与命令怎么验证

本轮修改了示例，或改变了它依赖的接口、参数、配置、环境时，再验证相关示例与命令：

• 从文档原文取示例，确认适用版本、工作目录、依赖和预期结果，复用现有测试或契约检查；说明占位符替换，不只验证手写副本。
• 可安全执行的内容在隔离环境运行，同时检查退出码和实际输出。片段缺少前置条件时说明检查限制；发布、删除、付费或使用凭据仍须在已有授权范围内，不全量执行文档代码块。
• 失败时区分过期示例、实现错误和环境缺失，按已确认需求修复本轮问题后复跑，保留原验收要求。历史示例保留当时语义，不当作当前指南执行。

接口样例的失败、修复与复验见可复跑案例。

完成时在回复或已有测试记录中简述：已同步内容（或无需同步的理由）、待确认差异、失败及未验证范围；附受检版本、文档位置和实际命令／环境、预期与结果。本次受影响的主记录和查到的引用均应已处理；未解决项写清位置、依据和下一步，并标为部分完成。无需另建报告或台账，脚本通过不代表内容全部一致。