WorkBuddy 删除任务后清理痕迹（workbuddy-cleanup-traces）

背景

WorkBuddy 在 UI 中「删除任务 / 删除会话」只是软删除：

• workbuddy.db 的 sessions.deleted_at 被置位，列表不再显示该会话；
• 但本地痕迹不会自动消失，包括：
• 工作空间文件夹 ~/WorkBuddy/<timestamp|name>/（如 2026-07-09-22-17-24、Claw）
• 对话记录 ~/.workbuddy/projects/c-Users-...-WorkBuddy-<folder>/
• 运行时文件 ~/.workbuddy/sessions/<pid>.json
• 跟踪目录 ~/.workbuddy/traces/<pid>/
• 产物索引 ~/.workbuddy/artifact-index/<conversationId>.json

> ⚠️ 关于会话索引 app/sessions.json：它不是本 Skill 的清理对象。该文件由 WorkBuddy 依据 workbuddy.db 自动维护——删除任务的会话条目本就会因为数据库里的软删除（deleted_at 已置位）而继续保留在索引中。这是 WorkBuddy 自身的行为，无需也不应由本 Skill 去改动。本 Skill 只清理上面那些真实占用磁盘空间的文件痕迹，这些应用不会自动重建。

因此用户删完任务后，硬盘上仍留有空目录 / 零碎记录，需手动或脚本同步清理。本 Skill 把这套清理流程固化成一个可复用的确定性脚本。

何时使用

• 用户说「删了任务但工作空间还在」「清理删除任务的痕迹」「同步清理工作空间」「清一下 workbuddy 残留」「删除会话后把本地文件也清掉」。
• 用户刚在 UI 里删除了若干任务/会话，想要一键清理其对应痕迹。
• 用户询问「WorkBuddy 删除任务是否会清理工作空间」（此时先解释机制，再按需清理）。

小白版三步（给非技术用户）

你在 WorkBuddy 里删了任务或会话，却发现硬盘上对应的工作空间文件夹还在？三步就能清干净，而且不会误删任何还在用的东西：

第 1 步 · 先看清单（预览，只看不动）
对助手说「清理痕迹」，它会先跑「预览模式」，列出：哪些已删任务的残留可以清、哪些因为和正在用的任务共用同一个工作空间而会被自动保留。这一步什么都不会改。

第 2 步 · 确认后再执行（移动备份，不是硬删）
你看清单没问题，说一声「确认清理」，助手才把那些痕迹整体搬进一个名为 _cleanup_trash 的备份文件夹。它不是永久删除，随时能找回。

第 3 步 · 确认无误再清空（可恢复）
备份在 WorkBuddy/_cleanup_trash/。你确认清对了，再去那里手动删除释放空间；万一清错了，从备份里拿回来就行。

为什么放心：全程是「移动备份」而不是「rm 硬删除」，并且会自动跳过仍被使用的文件夹——你正在用的任务绝不会被影响。

如何使用

第 1 步：定位脚本与运行时

• 脚本位于本 Skill 的 scripts/cleanup.py。
• 运行环境：任意 Python 3 即可（脚本仅用 Python 标准库，无需安装任何第三方依赖）。直接用 python3（或 python）运行下面的命令即可；若想用 WorkBuddy 自带的受管 Python，它位于 ~/.workbuddy/binaries/python/versions/<版本>/python.exe，请把 <版本> 换成你机器上的实际版本号、并把 ~ 换成你的用户主目录。

第 2 步：先自测（可选，强烈推荐新手）

装好 Skill 后先跑一句自测，确认环境与逻辑正常（只用临时文件，完全不碰你的真实数据）：

python3 "<skill_dir>/scripts/cleanup.py" --selftest

看到 ✅ SELFTEST PASS 即说明脚本在你的机器上可正常运行；若报错，见下方「常见报错 / 排查」。

第 3 步：dry-run 预览

执行预览模式（不加 --apply，仅打印将要清理的内容，不改动任何文件）：

python3 "<skill_dir>/scripts/cleanup.py"

预览会列出每个「已删除会话」对应的：工作空间文件夹、projects 记录、session 文件、trace 目录、artifact 索引，并标注：

• 是否「与现存会话共用工作空间」（此时文件夹与 projects 记录会被跳过保留，仅清理按会话 ID 隔离的记录，避免误伤现存会话）；
• 是否有残留痕迹可清理。

第 4 步：向用户确认

把预览结果呈现给用户，特别说明：

• 哪些文件夹将被移入 _cleanup_trash/（备份目录，可恢复）；
• 哪些因「共用工作空间」被跳过（保留给现存会话）；
• 全程是移动备份，不是 rm -rf 硬删。

在用户确认前，不要执行 --apply。

第 5 步：执行清理

用户确认后，加 --apply 执行：

python3 "<skill_dir>/scripts/cleanup.py" --apply

脚本会：

1. 把每个可清理目标移入 <WorkBuddy根>/_cleanup_trash/（文件夹）与 <WorkBuddy根>/_cleanup_trash/.wb_records/（记录），已存在则追加 .dup 防覆盖；
2. 不修改 workbuddy.db、也不改动 app/sessions.json（索引由应用自动维护，见「背景」说明）。

第 6 步：汇报与后续

向用户说明：

• 共清理了几个会话、移动了多少项；
• 备份位于 <WorkBuddy根>/_cleanup_trash/，确认无误后可手动清空以永久释放空间；误删时可从备份恢复。
• 提示：目前 WorkBuddy 没有「删除即清理」的原生开关，删任务后想顺手清痕迹，直接说「清理痕迹」即可复用本 Skill。

安全规范（必须遵循）

• 绝不硬删：一律 move 到 _cleanup_trash/，不使用 rm -rf、不绕过回收站。
• 共用工作空间保护：若文件夹同时被「已删除会话」与「现存会话」引用（保存到同一空间），跳过文件夹与 projects/ 记录，避免误伤现存会话。
• 受保护 workspace 豁免（用户自定义、常驻）：protected_workspaces.json 的 names 数组存放用户指定的保护项（空间名或完整路径），即使对应会话已删除也永不清理其文件夹与 projects/ 记录。默认空（公用 skill 不内置任何具体产品）。
• 指定（常驻）：在指令中用关键字 保护空间 / protect（后跟冒号，全角 ： 或半角 : 均可）列出空间，例如 清理痕迹，保护空间：我的项目A 或 protect: C:/Users/me/WorkBuddy/另一个号；多空间用 ，,、空格 分隔。AI 会校验存在性——不存在会反馈「未找到」，存在则写入名单长期有效。
• 取消：取消保护空间：我的项目A / unprotect: 我的项目A / 取消保护：...，从名单移除。
• 查看：列出保护空间 / list protect。
• 也可手动编辑 JSON 的 names 数组。
• 先预览后执行：必须先用 dry-run 呈现计划，经用户确认再 --apply。
• 不碰 workbuddy.db：只清理文件系统残留，数据库软删除状态已一致，不改库。

备注 / 排查要点

• 路径推导：projects/ 子目录名 = re.sub(r'[:\\/]','-', cwd).lower()，例如 C:\Users\你的用户名\WorkBuddy\Claw → c-Users-你的用户名-WorkBuddy-Claw（把 你的用户名 换成实际用户名即可）。
• 会话 ID 一致性：sessions 表的 id == app/sessions.json 的 conversationId == artifact-index/<cid>.json 的文件名；sessions/*.json 运行时文件内 sessionId 字段与之对应；traces/<pid>/ 内 trace 文件正文含有 conversationId。脚本据此精确匹配，避免误删同名路径。
• 若用户希望更彻底（含数据库层面），需向官方反馈「删除任务时同时删除工作空间」的产品需求——这超出本 Skill 能力范围。

常见报错 / 排查（新手友好）

脚本已内置较友好的报错提示，若仍遇到以下情况，按对应方案处理：

• [错误] 找不到数据库: .../workbuddy.db
  → 说明本机还没生成过 WorkBuddy 数据库。先正常打开并登录一次 WorkBuddy（它会自动建库），再运行本 Skill。
• python3: command not found / 不是内部或外部命令
  → 机器上 Python 命令名可能不同。依次尝试：python、py；或填 WorkBuddy 自带 Python 的完整路径（~/.workbuddy/binaries/python/versions/<版本>/python.exe）。也可在 WorkBuddy 对话里直接说「清理痕迹」，由助手代为执行。
• [错误] 读取数据库失败：database is locked
  → WorkBuddy 正在占用数据库。关闭 WorkBuddy（或等其空闲）后重试。
• PermissionError: [Errno 13] Permission denied
  → 目标文件被占用或无权限。关闭可能占用该文件的程序（如编辑器/资源管理器预览），以普通用户权限运行即可；不要用管理员强制抢占。
• 其他未知报错
  → 脚本会打印 类型: 信息。一切已移入 _cleanup_trash/ 的内容均可恢复，不会丢失；把报错信息反馈即可进一步定位。

已知限制

• 幂等安全：脚本可重复运行。已移入 _cleanup_trash/ 的目标在重跑时会被 safe_move 跳过（源已不存在），不会重复移动或误删。
• Git Bash 路径陷阱：在 Windows 上用 Git Bash 调脚本时，/c/Users/... 路径常被 MSYS 错误拼接成 c:\c\Users\...。若需显式写绝对路径，请用原生 Windows 反斜杠路径传给 Python（如 "C:\Users\你的用户名\.workbuddy\skills\workbuddy-cleanup-traces\scripts\cleanup.py"）。推荐直接用 python3 调用，可避开此问题。
• docstring 陷阱：脚本内含 C:\Users\... 的模块/函数 docstring 必须用原始字符串 r"""/r'''，否则 \U 会被当作 Unicode 转义导致 SyntaxError。