cleanup

清理技能

VCS 提供商

此技能通过 Exarchos MCP 操作（list_prs、get_pr_comments 等）执行 VCS 操作。 这些操作会自动检测并路由到正确的 VCS 提供商（GitHub、GitLab、Azure DevOps）。 无需使用 gh/glab/az 命令——MCP 服务会处理提供商分发。

概述

通过单次操作，将已合并工作流的状态设为 completed。取代 PR 堆栈合并后手动导航 HSM 守卫的多步骤流程。

批量清理过期工作流

若要批量清理累积的过期或已放弃工作流（而非解决单个已合并工作流），请使用 @skills/prune/SKILL.md。该技能会以试运行模式调用 exarchos_orchestrate prune_stale_workflows，展示候选项，并在用户确认后执行。保护机制会自动跳过存在未关闭 PR 或近期提交的工作流。

经验法则： 清理针对单个工作流（一个已合并的功能 → completed）；修剪针对批量工作流（N 个非活跃工作流 → cancelled）。二者互为补充，并非替代关系。

触发条件

在以下情况下激活此技能：

• 用户运行 cleanup 命令
• 用户说“cleanup”“resolve workflow”“mark as done”
• PR 堆栈已合并，工作流需要解决
• 用户想要结束已完成的功能

前提条件

• 工作流处于任何非终止阶段
• 所有 PR 均已在 GitHub 上合并

流程

1. 确定目标工作流

读取工作流状态，以获取当前阶段和元数据：

exarchos:exarchos_workflow({ action: "get", featureId: "<id>" })

如果未提供 featureId，使用流水线视图列出活跃工作流：

exarchos:exarchos_view({ action: "pipeline" })

流水线视图默认限定在当前仓库——仅显示调用方的仓库。其他仓库中启动的工作流不会显示；如果响应中的 unscopedTotal 大于 page.total，请使用 scope: "all" 重新查询，以显示隐藏的行。

2. 验证合并状态

验证与工作流关联的每个 PR 是否已合并。

主要方法——VCS MCP 操作：

exarchos_orchestrate({ action: "list_prs", state: "merged" })

如需查看单个 PR 的详细信息，请使用 exarchos_orchestrate({ action: "get_pr_comments", prId: "<number>" }) 或 VCS 提供商的原生 API。

从已合并的 PR 中收集：

• prUrl：PR URL（对于堆叠 PR，为 URL 数组）
• mergedBranches：已合并的头部分支名称

安全检查： 如果任意 PR 尚未合并，则中止并显示清晰的错误消息。

详细的验证指南请参阅 references/merge-verification.md。

2.5. 合并后回归检查（建议）

验证合并状态后，运行合并后回归检查：

exarchos_orchestrate({
  action: "check_post_merge",
  featureId: "<id>",
  prUrl: "<url>",
  mergeSha: "<sha>",
  repoRoot: "<repo-root>"
})

repoRoot 是包含合并提交的检出目录的绝对路径。检查会运行工具链解析器为该检出目录找到的测试命令。如果未解析到测试命令，则测试检查会失败，并提示你需要在 .exarchos.yml 中添加什么内容。

此检查仅供参考——会报告检查结果，但不会阻止清理。如果检测到问题，请在继续前记录下来并告知用户。

3. 调用清理操作

使用收集的数据调用 MCP 清理操作：

exarchos:exarchos_workflow({
  action: "cleanup",
  featureId: "<id>",
  mergeVerified: true,
  prUrl: "<url-or-array>",
  mergedBranches: ["branch1", "branch2"]
})

此单次调用会：

• 回填 synthesis.prUrl 和 synthesis.mergedBranches
• 强制将所有阻塞性审核状态解析为 approved
• 通过通用清理路径将状态转换为 completed
• 向事件存储区发出 workflow.cleanup 事件

4. 清理 Worktree

通过受管垃圾回收器 prune_worktrees 回收与该工作流关联的所有 worktree，不要临时使用 git worktree remove。

GC 执行时机——synthesize 之后（INV-12）。 工作流进入综合阶段后，受管 worktree 即可回收；清理在合并后运行（synthesize 完成后），因此这是执行回收的自然时机。从综合阶段开始，next_actions 投影会提供相同的 prune_worktrees 试运行入口。

prune_worktrees 会执行故障关闭安全阶梯（有未保存工作时会拒绝销毁 worktree），并为每个已删除的 worktree 自动生成 worktree.remove.requested / worktree.remove.executed 事件对。先试运行（默认方式——报告候选项、可回收字节数及按组归类的跳过原因，不会删除任何内容），然后再应用：

// Dry-run (default) — preview candidates, delete nothing
exarchos:exarchos_orchestrate({ action: "prune_worktrees", repoRoot: "<repo-root>" })

// Apply — reclaim the delete-eligible candidates
exarchos:exarchos_orchestrate({ action: "prune_worktrees", repoRoot: "<repo-root>", dryRun: false })

如果 worktree 已被移除，请妥善处理。如果 GC 跳过某个 worktree（例如存在未提交的工作），请先解决报告的原因再重新应用——绝不要手动强制移除有未提交更改的 worktree。

5. 同步分支

移除已合并的本地分支：

git fetch --prune
git branch -d <merged-branch-1> <merged-branch-2> ...

6. 报告完成情况

输出摘要：

## Cleanup Complete

**Feature:** <featureId>
**Transition:** <previousPhase> → completed
**PRs merged:** <count>
**Worktrees removed:** <count>
**Branches synced:** ✓

试运行

使用 dryRun: true 预览清理操作，而不修改状态：

exarchos:exarchos_workflow({
  action: "cleanup",
  featureId: "<id>",
  mergeVerified: true,
  dryRun: true
})

错误处理

错误	原因	解决方法
STATE_NOT_FOUND	featureId 无效	检查流水线视图中的活跃工作流（默认按仓库限定；如果工作流可能位于其他仓库，请添加 scope: "all"）
ALREADY_COMPLETED	工作流已完成	无需操作
INVALID_TRANSITION	工作流已取消	无法清理已取消的工作流
GUARD_FAILED	mergeVerified 为 false	清理前确认 PR 已合并

反模式

不要这样做	应该这样做
在实现期间将清理用作逃生手段	仅在 PR 合并后使用
跳过合并验证	始终通过 GitHub API 验证
合并后手动处理 HSM 守卫	使用清理操作
清理后留下 worktree	将移除 worktree 纳入流程

Exarchos 集成

清理操作会自动生成事件——不要手动生成：

• workflow.cleanup——由 MCP 清理操作为阶段变更为已完成而生成