SuperAPI AI 工具集

sweep

部署与运维

查看项目

更新于 10-16 08:48

技能介绍

一、用途 sweep 用于会话之间可能丢失工作的场景,例如崩溃、卡死、并行会话切换,或只是怀疑“我们是不是漏了什么”。目标是找出卡在“磁盘上存在”与“已合并并部署”之间的工作,并在一次批量批准后有条理地恢复。该技能来自一次真实的多会话崩溃恢复(2026-07-09),每种检测都对应实际发生过的失败模式。

二、调用与范围 /sweep:当前仓库及其所有 git worktree list 条目(默认)。 /sweep all:Config 表中的每个仓库。 /sweep <path>:指定仓库(及其 worktree)。

三、配置 技能内有 Config 表模板,可编辑为你的仓库,包含 Repo、Policy、Deploy provenance 三列。策略有 normal 与 report_only;report_only 仓库只允许报告和 port-out(把内容移植到正常仓库),Phase 4 拒绝在该仓库内执行任何变更。发现阶段跳过 git fetch,并记录 refs 的获取时间。

四、基本规则(不可协商)

  1. 机器状态不是事实。Journal/handoff/memory 中的“SHIPPED”或“PENDING”只是声明,必须对照真实产物验证:git containment、live BUILD_SHA/bundle hash、HTTP 读取、gh pr list。
  2. 发现与分诊为非破坏性。Phase 1–3 只允许三种写:(a) normal 仓库中的 git fetch(仅远端跟踪引用,绝不 checkout/pull/工作树);(b) 台账文件;(c) 其他都不允许。使用 git fsck --unreachable --no-reflogs,绝不用 --lost-found(它会写)。
  3. 一次批量门控,之上仍逐个重问。恢复仅在用户批准台账后运行。即使在已批准的批量中,以下仍必须逐个重问:prod/staging 部署、任何推送共享/受保护分支(含 fast-forward)、合并到 main、--force-with-lease、分支/worktree 删除、丢弃任何 diff。恢复止于打开 PR;部署是带有确切受门控命令的建议,绝不执行。
  4. 尊重其他会话。非你创建的未提交 WIP 属于他人,直到证明已过期(文件 mtime + ACTIVE journal 心跳 + 活动会话;如有 orphaned-wip-adopter 过期测试则用之,否则内联应用该测试)。活动工作为 leave-active / 请勿触碰:绝不 staged、stashed 或在其上构建。
  5. 某类别零发现要明确说明(沉默会被读作“未检查”)。来源报错是 DATA GAP,必须报告,绝不编造。

五、四个阶段 Phase 1 发现(只读):按仓库派发一个子代理(Agent 工具,model: sonnet 固定),提示其读取 ~/.claude/skills/sweep/references/discovery-protocol.md,并复制配置上下文到提示中(子代理看不到 SKILL.md)。/sweep all 时在一条消息中派发所有仓库。 Phase 2 分诊:对每个发现运行 ~/.claude/skills/sweep/references/triage-rules.md 中的检查(主会话,或大范围扫描时每个仓库一个 sonnet 子代理;分诊子代理提示也必须携带仓库 Config 行与解析后的 journal 路径;取代性判断可用 model: opus)。每个存活项携带:证据命令+输出(按 triage-rules 脱敏)、它反驳的声明(如有)、一行修复建议、建议处置。 Phase 3 台账+单一门控:将台账写到调用 /sweep 所在仓库的 docs/digests/YYYY-MM-DD-sweep.md,绝不写入 report_only 仓库;若调用目录是 report_only 或不是仓库,则写 ~/.claude/coordination/sweep/YYYY-MM-DD-<repo>-sweep.md。No-clobber:若文件名已存在(同日重扫),绝不覆盖——现有 Recovery log 是已执行内容的检查点记录。写 YYYY-MM-DD-sweep-2.md(-3…),在顶部链接上一个台账,并携带其已执行/被阻止项,确保不会重跑。在聊天中呈现紧凑表格,请用户批准/编辑/否决批量——一个问题,列出每个项的 id、类别、一行说明和建议处置。台账模板包含状态、基线,以及 LOSS-RISK、NEEDS MERGE、NEEDS DEPLOY、NEEDS RECONCILE、SUSPECT ARTIFACTS、UNFINISHED INTENT、HYGIENE 七类;每类条目或写“None found — checked.”;Recovery log 由 Phase 4 追加,每项后检查点。 Phase 4 恢复(仅在批准后):按类别顺序逐项执行,通过 ~/.claude/skills/sweep/references/recovery-playbooks.md 中匹配的剧本。每项之后更新台账 Recovery log(- [x] + 结果)——二次崩溃本身也必须可被 sweep。按规则 3 逐个重问。report_only 仓库:拒绝仓库内变更,仅可 port-out。

六、非目标 不是日常摘要技能(若你有)、不是实时项目看板(若有,例如 /pm)、不做 issue-tracker 扫描(若有)、不做 memory/聊天历史挖掘(此处由 /sitrep 的历史通道覆盖,若存在)。绝不自动合并到 main、部署、强制推送或清理。

七、使用限制 需按你的仓库编辑 Config 表和 Provenance notes,提供 URL 与端点(如 /version、/health)。没有 SHA 端点的仓库,部署来源比较在设计上就是声明式限制,记录“deploy provenance: liveness-only (no SHA endpoint)”,不要寻找 SHA,也不要标为 DATA GAP。无法映射的只读 bundle hash 报告为“DATA GAP: bundle-hash unmapped”。发现/分诊期间绝不运行本地构建(会写构建产物,违反非破坏性规则)。其他功能与配置细节暂未提供。