fresh-eyes-sweep

Fresh Eyes Sweep

如果斜杠或美元符号调用已将这些指令添加到对话中，请直接遵循。在这种情况下，不要再通过技能工具调用此技能。

检查指定的 Git 范围，查找有证据支持的错误。修复所有安全的问题。逐一处理所有映射文件。 只有在覆盖范围完整且完整检查未发现新问题时，才能确认无需更改。保持正确的内容不变。无需编辑即可证明检查成功。

--max-runtime DURATION 为可选项：格式为正整数，后跟 m 或 h，例如 45m 或 3h。无效时长、未知选项或含义不明确的位置参数均应拒绝。如果指定了截止时间，请在审计前计算截止时间。此时，预留最后 15% 的时间用于汇总验证和报告，并将其限制在 5–30 分钟内，且不得超过总运行时间。在该时间窗口内，完成正在进行的分项工作，不要开始新的修复。如果检查未完成，请附上台账报告未完成状态，不要超时。

Overnight Autonomy

调用时，读取环境的本地时间。如果严格晚于 22:00 或严格早于 08:00，则将整个运行视为自主运行，即使运行稍后跨过时间边界也不例外。恰好在 22:00 或 08:00 时不属于此时间窗口。

在夜间自主运行期间：

• 不要向用户提问，也不要暂停以请求澄清、选择或批准。这不会扩大此技能的权限：不得执行具有破坏性、涉及信息披露、购买、公共契约或其他依赖审批的操作。
• 采用最小且安全、可逆的解释，并继续所有独立工作。将所有含糊事项、阻塞问题和依赖审批的选择记入夜间待办事项，而不是中断运行。
• 结束时列出待办事项，并说明每项的证据、安全处置、影响及所需决策。将条目表述为发现，而非问题。若待办事项为空，则省略该部分。

Ledger Interface

根据此 SKILL.md 的位置解析 scripts/sweep-ledger.py。在仓库外创建临时台账：

uv run "<skill-dir>/scripts/sweep-ledger.py" init \
  --root <repo> --ledger <scratch.json> [<path>...]

不指定路径时，init 会映射整个仓库。指定路径时，则只映射这些 Git 范围。若某个路径与任何已跟踪文件或未被忽略的未跟踪文件都不匹配，init 会失败。它会记录每个已跟踪文件和未被忽略的未跟踪文件，以及每个路径在运行前的工作区状态。此辅助程序不会判定文件是否为生成文件、供应商文件、二进制文件、安全文件、重要文件或有缺陷文件。

只有在检查或以其他方式处理某个路径后，才能原子地记录 Agent 的决定：

uv run "<skill-dir>/scripts/sweep-ledger.py" mark \
  --ledger <scratch.json> --status <pending|inspected|fixed|reported|excluded> \
  --path <path> [--path <path>...] [--reason <text>]

excluded 必须附带由 Agent 撰写的理由。未知路径或无效批次会导致失败，且不会进行部分更新。并行的 mark 调用会通过旁路文件 <scratch.json>.lock 串行执行，因此并行子 Agent 可以各自标记路径。

uv run "<skill-dir>/scripts/sweep-ledger.py" pending --ledger <scratch.json> [--limit <n>]
uv run "<skill-dir>/scripts/sweep-ledger.py" summary --ledger <scratch.json>

pending 按稳定顺序返回下一个尚未处理的路径。summary 返回精确的状态计数、运行前的编辑数量、完整性、百分比计算输入以及十格进度条。直接使用这些数据。切勿估算进度或重新实现台账计算。

设置

1. 要求使用 Git，并阅读适用的仓库说明。记录工作树根目录、起始提交、起始状态、已解析的范围，以及截止时间和验证时间窗口（如有）。

2. 为请求的范围初始化清单。Agent 还可以检查理解该范围所需的共享配置和说明。不要默默扩大清单范围。如果 init 映射的文件超过约 2,000 个，且用户未提供 [paths]，则将映射后的清单划分为有边界、了解系统的目录或子系统切片，并继续执行，不要仅因文件数量而询问用户。在清单中保留完整的请求范围，并通过系统图和整体验证维护跨切片不变量。

   如果提供的截止时间不足以覆盖所有切片，则在验证时间窗口结束时停止，并报告可恢复的进度节点。只有在没有安全的分区方式能够维护重要不变量，且用户必须选择更窄的结果时，才询问用户。在自主执行的隔夜任务中，将该选择记录在隔夜待办事项中，并完成所有仍可独立安全执行的工作。

3. 对生成文件、供应文件、压缩文件、二进制文件和批量数据文件进行分类。如果不适合逐行审查，则通过其生成器、架构或不变量进行验证，然后注明 Agent 给出的理由。

4. 构建精简的系统图：可执行入口、工作区或软件包的依赖方向、公共接口、生成器和派生文件、外部及持久化数据边界，以及每项重要不变量的负责人。选择切片前，端到端追踪风险最高的工作流。

5. 检查近期历史记录和差异，尤其是最新更改，以查找受影响的调用方、依赖项、测试、配置和文档。根据证据评定切片和修复的优先级。优先处理正确性、数据丢失、安全性，以及对外暴露的个人数据或信息泄露风险。之后再评定可靠性、可维护性、经测量的性能和开发者体验。将时效性作为一种优先级信号，而不是覆盖检查的替代品。

6. 找出构建、测试、lint、类型检查、格式检查和代码生成检查。

7. 在首次修复前，为每项安全且相关的检查建立基线。如果检查失败，则优先处理可复现的失败，再进行可自行决定的工作。对于需要不明确或被禁止操作才能解决的失败，暂缓处理，同时继续开展可独立验证的工作。

8. 保留清单中记录的所有既有编辑。不要还原、吸收、提交这些编辑，也不要将其报告为发现项。

完成映射后，报告 ### 🔎 Sweep mapped — <files> files · <slices> slices · ledger <scratch.json>。切片数量由 Agent 自行决定。文件数量以清单为准。

清单的有效期超出当前会话。后续会话可通过指向同一清单路径来恢复同一轮检查，而不必重新运行 init：pending 定义了待处理范围，已登记的路径无需再次检查。每次进度更新都应附上清单路径；报告未完成的检查时，也要再次注明该路径，以便用户交给下一个会话。

子 Agent

• 仅在实质性提升覆盖范围或缩短完成时间时，才委派相互独立的工作部分。使用能有效完成任务的最小团队规模，并遵守宿主限制和用户的委派偏好。
• 宿主支持选择模型时，应针对任务谨慎选择审查模型和修复模型。否则，使用宿主默认模型。
• 启动前用一行说明计划如何分派任务：Agent 数量以及各组使用的模型。
• 除非用户提高上限，否则并发审查 Agent 不得超过 4 个，且始终不得超出宿主支持的并发上限。
• 将每个已启动任务的 ID 记录到协调者的工作切片计划中，以便后续停止请求能够对应到真实 ID。清单中的 reason 仅记录排除项。
• 为编写 Agent 指定稳定 ID、依赖波次、精确且互不重叠的写入范围、代码仓库约束，以及必须提供的完成证据。每份切片简报中的完成证据都必须涵盖该切片写入范围内语言所适用的所有严格静态检查门禁——类型检查、lint 和格式／导入顺序检查，并尽可能将检查范围限定在工具允许的最小范围内。待受影响的切片稳定后，将每项全仓库检查门禁指派给一名验证负责人。其他 Agent 应报告该依赖，而不是重复运行检查。共享清单文件、锁文件、导出项和集成文件应指派给一名负责人，按顺序处理。
• 启动依赖项之前，先完成当前波次的协调。若独立审查能针对具体风险（例如并发、安全或跨切片不变量）提供保障，则使用全新上下文的验证者。常规编辑本身无需验证者。
• 子 Agent 和工作者不得提交代码。协调会话应按顺序提交已稳定的切片作为检查点提交，以确保只有一个进程操作 Git 索引。
• 一个会话持有一个协调声明，每个新声明都会替换上一个声明。若代码仓库使用基于声明的协调器（例如 ai-coord），则在启动编写者之前，先声明所有正在进行的写入切片（运行中的 Agent 加协调者自身的编辑）的并集。扩展声明时应改为新的并集，不得缩小范围以致漏掉仍在写入的切片；仅在所有进行中的切片都已协调并提交后才释放声明。
• 检查点提交期间若 lint-staged 或其他钩子失败，请遵循 $commit 的故障恢复指南，不要在此处诊断索引争用问题。

检查和修复

按逻辑连贯的切片开展工作，让实现、调用方、测试、配置和文档能够一并审查。针对每个切片，应从基本原理出发，根据用户请求和代码仓库证据，确定预期结果和所需行为。当前实现应被视为有待论证的方案，而非必须遵循的要求。按以下顺序审视：

1. 哪些内容是不必要的、过于复杂，或建立在薄弱假设之上？结合证据质疑这些假设。
2. 在保留所需行为和契约的前提下，哪些内容可以彻底删除？得出某部分不必要的结论前，先检查使用方和不变量。
3. 删除不必要的内容后，剩余逻辑、接口或工作流有哪些可以简化？

优先删除，而非简化；优先简化，而非优化；优先优化，而非自动化。在请求范围内落实经确认且安全的改进。上述顺序并不意味着可以放弃要求或自动化无谓的工作。

端到端追踪重要的控制流、数据流、并发路径和错误路径。查找具体的错误、遗漏、不成立的假设、未处理的边界情况、安全／可靠性失效、不一致、重复内容、死代码、过时文档和不必要的复杂性。还应检查证据明确表明存在的性能、依赖项、数据格式和扩展、配置、可观测性、无障碍性、Agent 上下文、命名和目录结构问题。风格偏好和未经验证的猜测不算发现。

在适用的外部边界和持久化数据边界，检查以下问题：

• 校验、领域精度和单位。
• 确定性排序和去重。
• 幂等性和重复运行行为。
• 原子性和中断安全性。
• 重试和分页完整性。
• 有界并发、取消和资源清理。
• 密钥、日志、路径、临时文件和命令安全。

编辑前确认每个问题。如果意图明确且有可用的验证方式，就修复最小范围的根因。如果新增回归测试能保护现有覆盖中缺失的重要故障模式，就添加测试。不要添加同义反复的测试，也不要添加仅仅复述可逆的文字或配置修改的测试。报告前，修复每个可验证且在范围内的风险。不要将其报告为剩余风险。

仅在确实需要作出决定时才标记为 reported：意图不明确、安全修复会改变仓库外使用者依赖的公开契约，或没有可用的验证方式。为每条 reported 发现给出建议修复方案及其影响范围。不要添加推测性功能、大范围重构或纯外观改动。

将超过 1000 行的源文件和超过 2000 行的测试文件仅视为待进一步检查的候选项。只有在内聚性、耦合性、变更风险或可测试性表明确实存在更好的边界时，才拆分文件。行数本身不是证据。若已确认的结构性问题需要重新设计接口或边界，且 $codebase-design 可用，请使用它。在所属模块中集中维护不变量，对透传模块应用删除测试，仅在行为确实存在差异时引入边界，并让调用方和测试使用最终接口。

更改接口、持久化格式、导出名称或路径前，列举并迁移每个生产者、消费者、架构、夹具、生成器、导出或清单、脚本或配方、检查项、配置引用和文档。之后搜索旧标识符，并说明每个有意保留的实例。只有在迁移具备原子性、兼容性可以证明且仓库检查能够验证时，才进行依赖或框架更新、数据格式或扩展名变更、重命名和重组。若没有记录的基准指标和可重复的基准测试，不要保留性能改动。

如果实验未达到证据门槛，只撤销可归因于该实验的改动。绝不要使用全仓库清理、检出或重置命令。每轮非平凡改动后，如果 $code-polish 可用，就对该轮所有确切变更文件的并集运行它。否则，在当前范围内遵循同样固定的约束：仅在能切实提升可理解性或降低缺陷风险时进行简化，按严重程度审查，修复有证据支持的缺陷，并重新运行范围最小的验证检查。

长时间运行时，只有在完整且连贯的工作片段结束后才发布进度更新，并使用账本摘要中的确切进度条和计数。进度条表示路径核算情况，而非检查深度。

测试

像审查代码一样，基于同样的第一性原理问题审查测试，目标是缩小测试套件，同时捕获同样多或更多的缺陷。对于每项测试，先确定它保护的必要行为，然后：

• 删除同义反复的测试：这类测试必然会通过，被测代码中不存在任何合理缺陷能让它们失败。常见形式包括：

  • 断言模拟对象或测试固件自身配置的值。
  • 用被测代码或其逻辑副本推导预期值。
  • 断言常量、类型或字面值等于自身。
  • 重述语言、框架或依赖项的行为。

  快速检查方法：在脑中破坏实现。如果测试仍然通过，它就是同义反复。

• 删除过时或无用的测试：这类测试针对已移除或重命名的行为，只靠模拟对象或测试固件维持；没有有意义的断言；将不依赖于任何需求的偶然实现细节或调用顺序固定下来；或已跳过、注释掉且没有仍然有效的理由。

• 合并实际证明同一件事的测试：仅输入不同、路径相同的测试应合并为一个表驱动或参数化测试。如果另一项测试的断言已完全覆盖某项范围更窄的测试，就删除后者。将不同文件中的重复测试合并到所属测试套件中。

删除或合并前，先确认受保护的行为已过时，或仍由一项明确保留的测试覆盖。如果重叠之处不明显，请查看覆盖率输出，或暂时破坏目标代码。

合并后须保留每项不同的断言、输入和可诊断的失败消息。已修复缺陷的回归测试应予以保留，除非有其他测试明确覆盖相同情况。切勿为了让检查通过而删除或跳过失败或不稳定的测试。修复原因，或将其标记为 reported。合并前后都运行受影响的测试套件，并记录测试数量的变化。

注释

将每条注释与它所描述的代码、调用方和历史进行比较。只修正明确属于 STALE（描述的行为已不再存在）、ORPHANED（提及了缺失的符号、路径、标志或概念）、MISLEADING（实质上暗示了不同的行为）或 REDUNDANT（只叙述一目了然的代码，未说明意图、约束或背景）的注释。证据能证明正确说法时，就改写注释；否则，删除注释。切勿仅为使注释属实而更改可执行代码；对于有用的理由说明和虽不完美但准确的措辞，应予以保留。

将影响行为的注释视为代码：编译器和工具指令（//go:*、构建约束、cgo 前导代码、go:embed、@ts-expect-error、lint 抑制指令、覆盖率编译指示）、许可证头、公共 API 文档，以及并发、所有权或安全约定。只有在工具语义已得到证实，并经相关工具验证后，才能编辑这些注释。否则，将其标记为 reported。

验证并报告

运行能够证明每项修复有效的最小范围检查，包括适用于已更改文件的所有已发现类型检查、lint 检查和格式／导入顺序门禁，然后汇总针对已更改文件的检查。重新检查受影响的路径并重复此过程，直到某次检查通过且未发现新的证据问题。宣布完成前，针对结果重新审视第一性原理问题，包括本次扫描新增的内容。检查通过本身并不能证明复杂化是必要的。

在给定截止时间的验证窗口内，协调归属自己的编辑，并根据最终已更改文件的并集，运行有依据的汇总格式、lint、类型、测试、构建和不变量检查。将最终结果与记录的基线进行比较。在宣称完成前，根据工具输出审计覆盖范围、修复和检查。

如果本次扫描推送了提交，且仓库定义了 CI 工作流（例如 .github/workflows），则在报告前监控所推送提交头的运行（gh run list --commit <sha>，然后运行 gh run watch <run-id>；如果主机支持后台运行，则在后台执行）。此时，修复归因于本次扫描的失败，并报告 CI 结果。如果更改后的代码在不同平台上的行为不同，而本地检查只覆盖了其中一个平台，则将未验证的平台列为风险。

仅当辅助程序 complete 为 true 时，才以 ### ✅ 扫描台账已完成 — <accounted>/<mapped> 个文件已核算（已检查 <inspected> 个，已排除 <excluded> 个） 开头。否则，使用 ### ⛔ 扫描未完成。总结已修复、已报告、已排除和检查的数量，以及已删除和已合并的测试数量变化；如果注释修复数量非零，也要汇总。包含精简的 Check | Baseline | Final 表格、已更改的产物和已验证的修复，以及子 Agent 的结果。

将每项 reported 发现视为 Open 条目。Open 条目只能涉及用户提供的输入、仓库外的操作或确认边界（破坏性操作、购买、部署或外部写入）。如果任务允许写入，且仓库内的更改可以解决某个条目，则应在报告前依据既定维护授权完成该更改。对于常规工程决策，不要写“需要所有者决策”“仅报告”或“残余风险”。做出决定、完成更改，并在报告中说明决定。

如果以下内容非空，也要包含已回退的实验及其失败证据、每项已报告发现及其证据、建议的修复方案和影响范围，以及适用时的隔夜待办事项。在 ### ⛔ 扫描未完成 时，写明台账路径，以便下一次会话从 pending 继续。不要倾倒临时台账内容、无关的预存更改或大批数据。当任务相关证据能够实质性支持报告时，应将其纳入。

在交互式（非隔夜）运行中，如果存在任何已报告发现，结尾应提出一个决策问题，列出这些发现，并询问是按建议全部修复、选择特定项目，还是保留为已报告状态。如果调用措辞已授权修复（例如“修复所有问题”或“我会遵从你的判断”），则视为已预先批准，无需提问；但破坏性操作、外部写入和购买仍始终需要明确确认。获得批准后，针对已批准的项目执行一轮修复，遵循相同的扫描规则——确认、修复、验证、更新台账，并重新运行 $code-polish——然后报告更新后的台账和检查结果。在自主隔夜运行期间，跳过提问，并将已报告的发现留在隔夜待办事项中。

完成要求：所有已映射路径均已核算；每项发现均已修复并验证、在获批的修复轮次中修复，或附有证据并等待决策而列为已报告；所有相关检查均已通过，或已明确说明其失败原因。