Cleanup 是一个用于回收磁盘空间并清理 AI 编程代理遗留资源的技能。它通过一次扫描、一次确认、一次执行的方式，帮助用户清理已合并或废弃的 git worktree、已合并分支、过期的构建产物、包缓存、代理日志和回收站内容。
用途
该技能旨在解决 AI 编程代理在运行过程中产生的磁盘占用问题，例如合并或废弃的 git worktree、已合并分支、过期的构建产物等。它适用于需要释放磁盘空间、整理项目环境的场景。
主要能力
- 扫描范围：可选择扫描当前仓库（默认）或整台机器。当前仓库扫描覆盖该仓库、代理 worktree 文件夹（Codex、Cursor、Conductor、Vibe Kanban）、包缓存、代理日志和回收站。整机扫描需通过 --root 指定包含项目的文件夹，常见路径包括 ~/code、~/dev、~/src、~/projects、~/repos、~/Developer、~/Documents/* 等。
- 类别限定：可通过 --only git,artifacts,archives,caches,agents,trash 限定只处理某一类，例如“只处理分支”对应 --only git。
- 远程分支：仅当用户希望同时删除 origin 上的已合并分支时，才添加 --remote。
- 扫描结果分类：扫描为只读操作（--fetch 会更新远程跟踪引用），输出四类编号项目并保存计划。REMOVE 表示已合并到基础分支、可重新生成，或 worktree 目录已不存在（注销它保留其分支）。NEEDS-DECISION 表示包含唯一内容（未提交或忽略的文件、未合并或未推送的提交、构建输出、归档、旧日志）。KEEP-ACTIVE 和 SKIP 表示打开的 PR、近期工作、长期分支、主检出、锁定或正在 rebase 的 worktree、有运行进程正在使用的目录、未挂载的驱动器，这些永远不会被操作。
- 阈值参数：--help 列出阈值选项，包括 --stale-days、--keep-days、--min-size。
使用方式
-
选择范围：从仓库内运行且不带 --root 则扫描当前仓库；用户表示磁盘满、所有项目或全部时，为每个包含项目的文件夹添加 --root <dir>。若常见路径均不存在，需询问用户。通过 --only 缩小范围，仅在用户希望删除 origin 上的已合并分支时添加 --remote。
-
扫描：运行 python3 <skill-dir>/scripts/agent_cleanup.py scan --fetch [--root DIR ...] [--only ...] [--remote]。扫描为只读，打印四类编号项目并保存计划，显示可回收总量。
-
一次确认：使用多选问题工具或单条消息询问一次并等待回答。REMOVE 项预选，每项一行显示 id、大小、路径和备注；项目较多时按类型分组（worktree、分支、产物、缓存）并保持每个 id 可见。说明缓存会按需重新下载，产物会在下次安装或构建时恢复。每个 NEEDS-DECISION 项单独一行且不选中，显示路径、大小和其中唯一的内容（备注）。代理日志和归档一旦删除无法恢复。若使用了 --remote，远程分支作为单独问题询问，删除会影响所有使用该仓库的人。KEEP-ACTIVE 和 SKIP 给出一行摘要，让用户知道它们已被查看。
-
执行：传入用户选择的 id，例如 python3 <skill-dir>/scripts/agent_cleanup.py apply 1 2 5 9-14。仅当所选 id 包含用户在其问题中批准的远程分支时才添加 --remote。apply --recommended 会处理所有 REMOVE 项，仅在用户批准全部且无其他项时使用。apply 为每项打印一行结果：done、skipped（自扫描以来已变化、已消失或正在使用）、refused 或 failed 并附 git 的原因。按打印内容逐项报告。skipped 和 refused 项保持原样，下次扫描会重新分类。若计划超过 24 小时，apply 会拒绝：需重新扫描并再次确认。git worktree remove 会拒绝有未提交更改的 worktree，仅对用户明确接受丢失更改的 id 添加 --force。分离 worktree 的唯一提交在移除前保存到 refs/agent-cleanup/ 下。
-
报告：告知用户释放了多少空间、移除了什么、留下了什么及原因；对于每个代理数据项，说明其备注中提到的代理内置保留设置，以便日志不再堆积。所有操作记录到 ~/.local/state/agent-cleanup/history.jsonl。
适用场景
适用于需要回收磁盘空间、清理 AI 编程代理遗留的 git worktree、分支、构建产物、缓存、日志和回收站内容的开发环境。
限制
- 扫描为只读，但 --fetch 会更新远程跟踪引用。
- 执行前会重新检查项目，跳过自扫描以来发生变化的项目。
- 计划超过 24 小时会被拒绝执行。
- git worktree remove 拒绝有未提交更改的 worktree，除非使用 --force。
- 代理日志和归档一旦删除无法恢复。
- 删除远程分支会影响所有使用该仓库的人。
- 具体阈值默认值、支持的代理类型细节、脚本内部实现等暂未提供。