
pstack Worktree Cleanup 实践指南安全回收磁盘空间的六步安全门禁流程【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins导读本文基于 pstack 插件中 poteto-mode 的 Worktree and simulator cleanup playbookpstack/skills/poteto-mode/playbooks/worktree-cleanup.md完整拆解它在本地磁盘清理场景下的执行策略如何审计并裁剪已合并或废弃的 git worktree、清除陈旧的 iOS 模拟器同时保证不可逆删除操作绝不触碰正在使用或持有未提交成果的工作区。读完本文你将掌握一套审计先行、人工确认、逐路径验证、最终裁剪的安全清理方法论并深入理解其底层审计脚本 worktree-audit.sh 的分类逻辑与安全门禁设计。一、Playbook 在 poteto-mode 中的定位pstack 的 poteto-mode 是主入口技能它读取任务请求从 23 个 playbook 中匹配最合适的流程并把该 playbook 的步骤逐字复制进 todo list 后按步执行。Worktree cleanup 是其中唯一一个直接删除用户状态的 playbookSKILL.md对应触发场景包括whats using my disk我的磁盘被什么占满了clean up worktrees清理 worktreeprune safe-to-prune worktrees裁剪可安全删除的 worktreefree up space释放空间delete old simulators删除旧模拟器它的核心定位在 playbook 第一句就点明You own the disk and the safety gate.即执行者同时拥有磁盘操作的权限与安全把关责任。删除不可逆因此每一步都要防误删正在使用的工作区或持有未提交成果的工作区。由于这个 playbook 删除用户状态时没有代码评审环节来兜底no code review to catch a slipplaybook 中的一道道门禁本身就充当了评审the gates above are the review。二、六步安全门禁流程总览整个流程由 6 个步骤组成可以归纳为一条主线盘点audit→ 交叉校验cross-check→ 核实使用状态verify→ 对不可逆损失暂停pause→ 裁剪已确认集合prune→ 扩展回收其他空间reclaim。步骤动作关键门禁1快照并审计记录df -h /后台运行scripts/worktree-audit.sh2交叉校验bucket 只是建议以钉住/活跃的 chat 集合为准3删除前核实使用情况对每条 verify-recent-chat 记录派子代理读 transcript4对不可逆损失暂停wip:N需先展示 diff 并取得决定scratch:N可安全丢弃但需点名文件5裁剪确认集合逐路径git worktree remove --force必要时rm -rfgit worktree prune6模拟器与其他回收项simctl系列命令清理模拟器、运行时、DerivedData 等缓存下面逐一展开每一道门禁的意图与实现依据。三、步骤 1快照与审计让数据说话3.1 先记录基线清理前先执行df -h /记录当前根文件系统的磁盘占用快照。这份基线既是后续回收了多少空间的对比依据也是 playbook 要求最终回复中必须给出的证据。3.2 审计脚本的输入来源绝不手打路径审计工作交给 worktree-audit.sh它通过git worktree list --porcelain读取 worktree 路径绝不使用手打路径。playbook 给出一个真实的反面教材手打myrepo-worktrees/x会漏掉实际位于.cursor/worktrees/myrepo/x的工作区。这正是 principle-encode-lessons-in-structure把教训编码进结构的体现与其依赖执行者记住worktree 可能藏在哪不如让脚本直接从 git 的真实状态读取路径把错误在结构层面变成不可能。脚本的核心实现如下worktree-audit.shgit worktree list --porcelain | awk /^worktree /{print $2} | while read -r wt; do [ $wt $main_wt ] continue # 主工作区永远是第一个条目跳过 ... done3.3 审计脚本按 8 个维度分类每个 worktree脚本对每个非主工作区输出一张表格列包括SIZE、AGE、MERGED、DIRTY、REMOTE、PR、LAST_CHAT、BUCKET、WORKTREE并按大小降序排序。各维度判定逻辑如下全部来自 worktree-audit.sh 源码大小SIZEdu -sh $wt直接统计目录占用。年龄AGE取 HEAD 提交时间戳计算距离现在的天数输出形如3d。合并状态MERGED用git merge-base --is-ancestor HEAD origin/main判断。脚本注释明确说明squash 合并的分支并不是 main 的祖先所以 merge-base 只能捕获 fast-forward/rebase 合并真正信号要看 PR 状态。脏状态DIRTY通过git status --porcelain区分三种情况输出为空 →clean存在非??前缀行即被跟踪文件的改动→wip:N其中 N 是跟踪改动条数全部是??前缀行仅未跟踪文件→scratch:N即一次性废弃物。远端状态REMOTE分支无对应远端 →detached本地与origin/branch一致 →pushed领先 N 个提交 →aheadN无远端分支 →no-remote。PR 状态PR调用gh pr list --author me --state all --limit 1000 --json number,state,headRefName一次性拉取按分支名匹配输出形如#123/OPENgh不可用时为空数组。最近对话LAST_CHAT扫描~/.cursor/projects/slugified-repo-path/agent-transcripts目录slug 由仓库路径去掉前导/并把/替换为-生成用 rg 匹配包含该 worktree 路径的 transcript取修改时间最近的一条。匹配时要求路径后跟/或引号避免glint-482误匹配glint-482-r37。建议分桶BUCKET由以上维度推导出建议处置类别。3.4 五种建议分桶bucket的判定逻辑分桶判定来自 worktree-audit.shcase $dirty in wip:*) buckethold-wip ;; *) case $pr in *OPEN*) buckethold-open-pr ;; *) if [ $recent yes ]; then bucketverify-recent-chat elif [ $merged YES ] || [ $pr ! - ]; then bucketsafe else bucketreview; fi ;; esac ;; esacbucket含义处置hold-wip存在被跟踪文件的未提交改动暂停需人工决定hold-open-pr该分支有 OPEN 状态的 PR暂停PR 未合并不动verify-recent-chat最近 4 天内now - last_ts 4天有 chat 触碰过先核实再决定safe已合并到 main 或有 PR 记录无论合并与否建议裁剪review其余情况人工复核脚本为只读审计Never deletes anything; deletion stays a human-gated step in the playbook这正符合 principle-build-the-lever构建杠杆工具负责把工作做得一致、可重跑删除始终是 playbook 中由人把关的步骤。playbook 还提醒transcript 扫描很慢应放入后台执行background it呼应 principle-guard-the-context-window守护上下文窗口——大体积输出交给子代理或后台主线程只保留摘要。四、步骤 2Bucket 只是建议不是许可playbook 强调The bucket is advice, not permission.审计脚本标记为safe的工作区有可能正是用户钉住pinned的那个。真正的工件real artifact是钉住的聊天和活跃的聊天集合这符合 principle-prove-it-works证明它真的有效不要相信代理或脚本的二手判断直接对着真实工件交叉核对。操作方式从用户或侧边栏sidebar获取 pinned / active 的 chat 集合逐一交叉核对审计表中的候选对象如果杠杆脚本把用户钉住的工作区标成了safe以 pinned 集合为准——pinned 集合胜出the pinned set wins。五、步骤 3删除前核实使用情况fan-out 子代理读 transcript对于审计结果中每一条verify-recent-chat行以及任何你存疑的对象都需要派出子代理去读 transcript报告该 chat 是否 pinned 或仍在进行中以及它触碰了哪些 worktree。这里有两个关键原因transcript 是批量数据全部读进主上下文会撑爆上下文窗口因此派子代理去读、只把摘要带回主线程——这是 principle-guard-the-context-window 的直接应用。pinned chat 会通过后台子代理在兄弟 worktree 中生成 arena 和 repro 树这些派生工作区即使名字从未出现在侧边栏也处于使用中。只看侧边栏名字会漏判。也就是说没在侧边栏出现不等于没被使用核实必须下沉到 transcript 层而不是停留在名字层。六、步骤 4对不可逆损失暂停Pause on irreversible loss这是全流程最核心的安全门禁涉及两种脏状态的区别对待6.1wip:N—— N 个被跟踪的未提交编辑性质真实未保存的工作成果。处置必须先展示 diff取得用户的明确决定get a decision first暂停。原理删除一个干净的工作区可以从它的分支恢复branch refs survive, so no commits are lost但未提交的工作一旦删除就永久消失。6.2scratch:N—— N 个未跟踪的废弃文件性质untracked throwaway一次性废弃物安全可丢。处置可以安全删除但必须点名文件name the files让用户清楚丢了什么。6.3 自主权边界根据 poteto-mode 的 Autonomy 规则SKILL.md可逆工作无需请示直接执行不可逆写入必须始终暂停Always pause for irreversible writes: force-push to shared branches, deploys, data deletion, customer messages。落到本 playbook 上就是最后一句判定clean and merged and not-in-use proceeds. wip and in-use pause.干净、已合并且未被使用的工作区 → 继续执行wip 和正在使用的 → 暂停。这个可恢复性优先的暂停原则也与 pause-safely.md 一脉相承任何暂停点都不得留下不可逆操作未提交内容要么落盘为wip:提交要么明确暴露其存在。七、步骤 5裁剪已确认集合经过前面四道门禁确认后的对象才进入实际删除阶段逐路径执行git worktree remove --force path如果目录因被忽略的构建产物ignored build artifacts而残留则rm -rf清理该目录随后执行git worktree prune确认分支引用仍然存在branch refs survive因此没有任何提交丢失用df -h /再次测量并重新列出 worktree 清单验证结果。playbook 要求最终回复包含裁剪前后的df -h /对比、被裁剪的 worktree 列表以及每个被保留对象的单行原因被哪个 chat 使用或存在未提交工作。这里 step 1 记录基线 → step 5 再次测量 构成了 prove-it-works 的闭环回收了多少空间不是靠估算而是靠磁盘真实快照的前后对比。八、步骤 6模拟器与其他空间回收项模拟器通常是继 worktree 之后的第二大空间赢家Simulators are usually the next-biggest win。playbook 给出完整的xcrun simctl命令集# 删除 XCTestDevices 克隆testing 环境专用设备 xcrun simctl --set testing delete all # 删除不可用的模拟器 xcrun simctl delete unavailable # 列出运行时删除旧版本运行时 xcrun simctl runtime list xcrun simctl runtime delete id其中--set testing是针对 XCTestDevices 克隆的专用操作测试框架会为 CI/测试创建设备克隆这些克隆往往被遗忘并持续占用磁盘。其他按需处理的回收项More when neededXcode 的DerivedData与iOS DeviceSupport目录~/Library/Application Support/Cursor下的state.vscdb.backup以及snapshots/roots/root——当一个以你打开过的文件夹命名的root不断膨胀时就是磁盘大户包管理器缓存pnpm、uv、brew、yarn。最后一道原则性约束只清理用户没有明确说要保留的缓存Clear only caches the user has not said to keep。九、回复格式可审计的输出契约playbook 要求执行完成后按固定契约汇报Reply:字段清理前后的df -h /对比明确回收的空间被裁剪的 worktree 清单每个被保留对象的一行原因被哪个 chat 使用in-use by which chat或存在未提交工作uncommitted work。这份回复契约与 poteto-mode 的通用写作规范SKILL.md一致每条主张都要在同一句话中携带证据或标签Every claim carries its evidence or its label in the same sentence绝不捏造链接、引用或 transcript 引用。十、设计要点总结为什么这套流程值得复用输入自动化路径来自git worktree list --porcelain而非手打把记错路径这一类错误消灭在结构层面worktree-audit.sh。工具与决策分离脚本只审计、只建议、绝不删除删除权永远留在人工把关的步骤中。脚本本身即评审者可重跑的工件符合 principle-build-the-lever。分桶优于一刀切hold-wip、hold-open-pr、verify-recent-chat、safe、review五种 bucket 让可删/不可删的判断有了可解释的依据而不是凭感觉。不可逆优先wip被跟踪改动暂停、scratch未跟踪废弃物可删但点名、cleanmergednot-in-use 才放行这条优先级在所有门禁中层层贯穿。上下文窗口守护transcript 扫描后台化、核实工作派给子代理主线程只收摘要principle-guard-the-context-window。证据闭环df -h /前后对比 重新列出 worktree让确实回收了空间、确实没有误删成为可验证事实principle-prove-it-works。如果你想在自己的仓库中复刻这套流程最小可落地的组合是把 worktree-audit.sh 复制到项目scripts/下它是只读审计不会删任何东西配合git worktree list --porcelaingit status --porcelain的输出解读再套用本 playbook 的六道门禁顺序执行删除。安全的关键永远不在命令本身而在于删除动作必须发生在人工核实之后。【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考