Agent 守则

Agent 对自己在本机留下的东西负责。用完的临时环境随手回收；有持久价值的结果放到约定位置；不给用户和下一个 Agent 留下垃圾或谜题。

实际出现过的反例：

• Docker：761 个悬空匿名卷约 60G，都是测试用 Postgres 容器删除时没带 -v 留下的。
• /tmp：项目测试 mkdtemp 后不删，一天积累数百个同名前缀的临时目录。
• 失效 worktree：多个仓库登记着指向 /tmp/...、.worktrees/... 的 worktree，目录早已删除，记录还在。
• 分支堆积：PR squash 合入后，本地和远端分支都没人删，一个仓库攒下两百多个远端分支；本地 origin/HEAD 还指向早已不是默认分支的旧分支。
• 报告和证据进了仓库：有的作为 docs/evidence/ 之类的目录提交到远程，有的以未跟踪目录留在仓库里（.task-artifacts/）。
• 工作区根杂物：工作区根被生成了 node_modules/。
• 任务目录散落：~/.cache、~/.local/share 下有按任务命名的目录。

东西放哪

工作区根指仓库所在的上一级目录，例如 ~/workspaces/<项目组>/。

• 报告和证据不进仓库。 只有两种例外：用户本次明确要求，或项目指令（AGENTS.md、CLAUDE.md 等）明确规定该交付物入库。提交上去会给协作者添麻烦；不提交、留在仓库里，又会被下一个 Agent 当成别人没做完的工作。仓库里不留 .task-artifacts/、REPORT.*、截图、tsconfig.tsbuildinfo 这类任务产物。
• 工作区根只放仓库和 reports/、evidence/。 不在工作区根运行会生成 node_modules、缓存或构建输出的命令，也不在这里建草稿、备份或任务目录。
• 不在 ~/.cache/<任务>、~/.local/share/<任务>、仓库内 .worktrees/ 另起任务目录。 debian-testvm 这类工具管理的存储，通过它们自己的 CLI 使用。
• 用户或项目有约定的，按约定执行。 已有约定的报告目录照用。项目明确规定的单一任务目录可以复用，回收义务和临时根相同。用户本次指定了运行路径，就照指定的路径走，收尾时仍按类别回收其中的一次性内容。
• 报告目录只放交付物。 最终 HTML 报告和它必需的非机密配套配置放在一起；报告目录里不放完整的一次性运行现场。证据只留最小必要部分，不保留全部原始文件，也不保留重复的完整 body / HAR 快照。私有配置和真实业务数据不放进可回收的工作区。

创建时就为回收做准备

• 记录起点和临时根。 任务开始时记下开始时间（收尾扫描要用），并用 mktemp -d 建一个任务临时根。这个任务的所有 worker 都用父 Agent 交下来的这一个临时根，按需建子目录，不各自另建带日期的目录。在任务说明或交接里分清三样东西：源码工作区、临时根、报告目录。写新任务说明时，按当前全局规则和本技能写，不照抄旧任务的 REPORT.md 或「永久保留」条款。
• Docker 按用途选参数：
  • 一次性容器用 docker run --rm。
  • 要活到任务后段的容器，加 --label owner=<任务> --label purpose=<用途> --label release-when=<条件>；条件写成本任务结束前就能核对的事件（见「什么要留」）。删除时用 docker rm -v，不带 -v 会留下匿名卷。
  • postgres、redis、minio 这类镜像声明了 VOLUME，每次启动都会生成匿名卷。需要保留的数据用带标签的命名卷或绑定挂载。
  • compose 项目只有在整个项目都属于本任务时，才用 docker compose down -v。
  • 回收时只处理带本任务标签、且释放条件已满足的资源。未加标签的容器和卷视为归属不明。
• 测试的 teardown 包含失败路径。 测试创建的临时目录、容器、端口、数据库都要在 teardown / afterAll 中清理，失败路径也一样。发现项目测试漏清理，当作 bug 修，或在结果里指出位置。
• 长驻进程按全局规则用 systemd-run --user --scope，unit 名带上任务名，收尾按 unit 精确停止。

Worktree

需要和主工作树隔离时（并行任务、主工作树有别人的改动、要在另一个基线上验证）用 worktree。不用 CoW：它不支持子模块，在 ext4 上每个基线都是完整拷贝，成果还要导出 bundle 再合回来。

bun <skill-dir>/scripts/wt.ts add --repo <主仓库> --name <任务名> [--branch <分支>] [--base <提交>]
bun <skill-dir>/scripts/wt.ts remove --path <worktree>
bun <skill-dir>/scripts/wt.ts gc --workspace <工作区根>... [--apply]

• add 建好就能用。
  • 位置固定在 ~/.local/share/worktrees/<仓库名>/<任务名>（AGENT_WORKTREE_ROOT 可改），在仓库和工作区之外。
  • 默认先从 origin 读取实际的默认分支并 fetch，从它新建 wt/<任务名> 分支；本地 origin/HEAD 可能过期，不作依据。连不上 origin 时退回本地记录，并在输出的 baseNote 中说明。不从主工作树当前检出的分支起步，那常常是别人进行中的工作。按项目分支命名时传 --branch。
  • 链接主仓库的 .env，任务差异写 .env.local，不改链接目标。
  • 子模块从主仓库的本地副本检出，没有对应提交时才走远端。
  • 按锁文件离线安装依赖；pnpm 从 store 硬链接，通常几秒完成。
  • stdout 输出 JSON，cwd 就是工作目录。
• 改用 add，不要直接 git worktree add。 运行环境自带的隔离（如 Claude Code 的 isolation: worktree）会自建 worktree，本技能管不到创建这一步。这类 worktree 照样在收尾时用 remove 回收，或者由 gc 兜底。
• remove 先核对，再删除。 依次核对：没有未提交改动、没有未合入默认分支的提交、没有进程在用；通过后删除 worktree，已合入的本地任务分支一并删除。合入的判断和 branch.ts 相同：以 origin 实际声明的默认分支为准，squash、rebase 合入都算。远端还有同名分支时，输出的 remoteBranch 会列出，按下面的「分支」一节处理。确认成果可以丢弃时才加 --force；有进程在用时，加 --force 也拒绝。
• gc 是兜底，不管 worktree 是谁建的。 它盘点工作区内所有仓库的 worktree，分三类：
  • 失效记录：HEAD 仍在某个分支上的，标为清理；
  • 已合入、无改动、无进程占用、闲置超过 --min-idle（默认 24h）的，标为可回收；
  • 其余一律保留。 默认只列出，加 --apply 才执行；失效记录逐条删除，不做整仓 prune。remove、gc 和收尾扫描都向 origin 查询实际默认分支（只读），连不上时才用本地 origin/HEAD 记录。
• 端口和数据不随 worktree 隔离。 并行服务各用各的端口；数据库、Redis、对象存储按全局数据规则隔离。数据库文件、bind mount 和私有配置不放进 worktree，删除 worktree 时被忽略的文件会一起删掉。

分支

任务分支合入主线后，本地和远端的副本都要清理。是否已合入、删不删、怎么留痕，都交给 branch.ts 判断；不要凭分支名、日期或 git branch --merged 手动删除。

bun <skill-dir>/scripts/branch.ts --repo <仓库> [--branch <分支>]... [--remote] [--apply --record <文件>]

• 以远端实际默认分支为准。 先 fetch --prune，再向 origin 查询它声明的默认分支。本地 main、过期的 origin/HEAD 都不作依据。
• 三种情况算已合入：
  • 分支头是默认分支的祖先（merge、fast-forward）；
  • 分支上的提交逐个 rebase 进了默认分支；
  • 整个分支被 squash 成默认分支上的一个提交。
• 内容判断不出时，看 PR。 squash 时手工改过内容的，内容比对认不出来。这时以 GitHub PR 为证据：已合入的 PR 覆盖了分支头，且合并提交在默认分支上。
• 这些不算已合入： 长期不活跃、上游显示 [gone]。
• 一律保留：
  • 默认分支；
  • 在任一工作树检出的分支；
  • 有未关闭 PR 的分支；
  • 有未合入提交的分支，包括 PR 合入后又推了新提交的。
• 远端从严：
  • GitHub 仓库只删有已合入 PR 证据的分支；gh 查不到 PR 时，远端分支一律保留。
  • 删除带 --force-with-lease：判断之后有人推了新提交，删除会被拒绝。
  • 受保护分支由服务端拒绝删除。
• 删除要留痕。 --apply 必须同时用 --record 指定一个新文件，写入每个分支删除前的 SHA、证据、PR 和恢复命令。记录放在 <工作区根>/evidence/branch-cleanup/<仓库>-<日期>.json，不放进仓库。
• 按场景处理：

收尾回收

• 默认回收本任务的一次性资源。 范围包括临时目录、fixture、隔离的测试数据、容器和卷、worktree、未交付的 R2 分享对象。回收的前提是三点都已确认：归属和隔离明确、交付和交接已完成、对其状态的具体依赖已结束。验证过归属的本任务一次性资源，不需要再等用户确认才回收。
• worktree 和分支合入后清理。 合入主线后，用 wt.ts remove 删除 worktree 和本地任务分支，远端分支按上面的「分支」一节处理。不用 git worktree prune：它会清掉仓库里所有失效记录，包括别人的。
• 构建产物同样回收。 一次性目录里的 .next、dist、.vite 等构建产物和缓存，在服务停止、复验和排障依赖结束后回收；构建无论成败，只留必要的诊断证据。真实项目正在使用的产物，以及工具共享的缓存，不在回收范围内。
• 失败现场按需保留。 只有后续诊断确实需要、又不能简单重建时才保留。可以复现的一次性状态，先存最小诊断信息，再回收。
• 跨会话恢复用的暂存目录不算持久数据。 选一个外部暂存根，在既有任务或交接记录里写明所有者、未完成的具体工作或依赖它的消费者、可观察的释放条件；条件满足就回收。
• worker 的资源也要验收，回收不往外推。 父 Agent 验收 worker 时，同时核对它留下的资源，只停掉进程不算闭环。worker 要么自己回收，要么在交接里逐项列出名称、路径或端口、依赖和释放条件。父 Agent 就是这些资源的最终负责人：先确认交付物和保留的证据完好，再回收临时根、容器和卷、视图和可回收的基线，不再写「留给 owner 审查后处置」。

R2 分享对象

设计文档和验收报告用 feature-delivery 的 share.ts 上传到 R2。每个对象在 ~/.local/state/r2-share/ledger.jsonl 追加一行 JSON 登记：op、at、task、releaseWhen、account、bucket、key、url、entry（所属页面）、source（本地源）、md5（桶内 etag）、size、contentType；删除时再追加一行 op: "delete" 记录，不改写旧行。

bun <feature-delivery>/scripts/share.ts list [--task <任务>]
bun <feature-delivery>/scripts/share.ts remove --task <任务> [--key <对象或页面 key>]...

• 交给用户的链接是交付物，按「什么要留」和最终报告一样保留。上传时用 --release-when 写明释放条件（默认「用户不再需要该链接」），条件满足或用户确认不再需要时删除。
• 其余上传是一次性资源，收尾删除： 自测和探测对象、被新版本替代的旧版本、核对失败的上传。
• remove 只删登记在该任务名下的对象，不按前缀批量删除，不碰桶里未登记的文件。每个对象先列出确认它仍在、etag 与登记一致，被改写过的拒绝删除并列出；再以完整参数预演、执行，重新列出确认已删除，读取公网链接核对 404，最后追加删除记录。已不在桶里的只补记录。给页面 key 时整组删除它的资源。
• 核对 404 时带一次性查询参数绕过边缘缓存。删除前被直接访问过的图片等可缓存文件，边缘缓存仍可能继续提供最多 4 小时；HTML 不缓存，不受影响。

收尾自检

收尾前运行只读扫描，时间窗从任务开始算起：

bun <skill-dir>/scripts/scan.ts --since <任务开始时间或 6h> --workspace <工作区根>

扫描会列出以下几类候选：

• 窗口内新建的临时目录，范围是 $TMPDIR、/tmp、~/.cache、~/.local/share，随机后缀会归组显示；
• 窗口内创建的已停止容器、未加 owner 标签的运行中容器、新增的悬空卷；
• 所有带 owner 标签的容器，不限窗口，附 release-when；
• 各仓库的 worktree（失效、已合入、位于仓库内的会标出）、未跟踪文件、被忽略的报告或证据目录、已合入（含 squash）的本地分支；
• 工作区根下除仓库和 reports/、evidence/ 之外的杂项；
• 登记中尚未删除的 R2 分享对象，不限窗口，附 task 和 release-when（只读登记，不访问远端）。

加 --json 输出机器可读结果，--help 查看参数。扫描不删除任何内容。

扫描结果是待核实的候选，不是删除清单：并行的其他 Agent 也会在同一时间窗内创建资源。逐项判断归属：

• 本任务创建的，按上面的规则回收；
• 不属于本任务、但明显是遗留的，不动，在最终回复里列出；带标签且释放条件已满足、所属任务已结束的，列为可回收，交用户确认；
• 归属不明的，保留。

什么要留

• 有持久价值的要留： 最终报告及交给用户的分享链接、必要的证据、开发数据库及其迁移记录、用户要求保留的环境（例如带 environment.json 写明 lifetime 的打包环境）、别人正在使用的资源。
• 保留临时资源要写明理由： 写清所有者、具体依赖、可观察的释放条件，并在最终回复中说明。「以后可能还要复验」「留给 owner／用户审查后处置」都不是保留理由：前者没有终点，后者把回收推给了不会再回来的人。释放条件写成本任务结束前就能核对的事件，例如「报告交付后」；条件在本任务内满足的，收尾时当场回收。确需跨任务保留的，在最终回复里交给用户决定。
• 不扩大清理范围： 不用 docker volume prune、docker system prune、docker compose down -v（项目不归本任务时）、批量 rm /tmp/* 这类宽泛命令。不删其他任务的 worktree、分支和数据。共享实例、数据卷、Redis、对象存储只按精确归属清理。

汇报

最终回复分开说明两件事：

• 已回收： 回收了哪些资源、范围多大；
• 仍保留： 保留了哪些资源，各自的原因、所有者、释放条件，以及相关端口、路径或分享链接。

扫描发现的非本任务遗留单独列出，不和本任务的回收混在一起。