WorkBuddy 问题调试和C盘清理

何时使用

• WorkBuddy 更新时弹出"安装目录下存在用户项目目录""安装目录下有项目目录"等拦截提示
• 想重装到干净状态，或怀疑安装目录里被误写了 .workbuddy 用户数据
• 需要清理 C 盘 / 用户目录下与 WorkBuddy 相关的历史迁移、备份、旧项目残留
• 排查 workspaces 注册表脏数据导致的异常
• 侧边栏反复出现清不掉的"幽灵项目"（如 Claw）：清 workspaces 表无效、删目录后又被重建
• 根因不在 workspaces，而在 sessions 表的 cwd 字段（见下方核心根因②）

核心根因（先懂再做，避免走弯路）

WorkBuddy 用环境变量 WORKBUDDY_DATA_FOLDER_NAME=.workbuddy，会给每一个被当作"项目/工作根目录"的文件夹自动生成 <目录>/.workbuddy 来存用户数据（automations / memory / trash / sessions）。
主配置目录由 WORKBUDDY_CONFIG_DIR 决定（默认 ~/.workbuddy，独立于安装位置，与重装解耦）。

复发开关：当安装目录本身落在某个"工作根"之下（典型场景：E:\ 被设为默认工作目录，而安装目录是 E:\Program Files\WorkBuddy），且安装目录曾被登记为 workspace → app 把安装目录也当项目根 → 在其内生成 E:\Program Files\WorkBuddy\.workbuddy → 触发"安装目录下存在用户项目目录"更新拦截。

> 关键认知：用户数据（skills/记忆/连接器/workbuddy.db）在 WORKBUDDY_CONFIG_DIR，重装不碰它们；"重装后记录都在"是成功标志，不是失败。

② 侧边栏幽灵项目根因（实测，极易误判）：WorkBuddy 侧边栏的项目列表由 sessions 表的 cwd 字段驱动，不是 workspaces 表。当某条历史会话的 cwd 指向一个已不存在的路径（例如 E:\workbuddy\默认工作空间\Claw 或 C:\Users\Administrator\WorkBuddy\Claw），WorkBuddy 每次启动会：①在侧边栏自动恢复显示该项目；②在磁盘上重建空壳目录。因此——
- 清 workspaces 表 → 无效（它不驱动侧边栏）；
- 清 projects/ 归档 → 无效（重启又复活）；
- 删 E:\Claw 空壳 → 无效（重启又被重建）；
- 唯一根治：把失效的 cwd 改写为有效路径（UPDATE sessions SET cwd='E:\' WHERE cwd LIKE '%Claw%'），保留历史记录不丢。本 skill 提供 fix_sessions.py 自动执行该修复（带备份）。

标准流程（四步法）

步骤 1 · 只读诊断（先看清，别急着删）

运行 scripts/diagnose.py（只读，零风险）。它会：
- 定位安装目录与主配置目录（自动探测 + 环境变量）
- 检测安装目录内是否有 .workbuddy（复发开关）
- 读取 workbuddy.db 的 workspaces 表，找安装目录类脏记录
- 读取 sessions 表，找出指向失效路径的 cwd（侧边栏幽灵项目复活源）
- 列出 C:/E:/D: 上所有 WorkBuddy 相关目录，给出"清洁度结论"

步骤 2 · 分级修复（按稳健度）

• ① 重装到 C:\Program Files\WorkBuddy（最稳·彻底斩断根因）：安装盘与工作盘物理隔离，E:\ 工作根再怎么扫也碰不到 C:\ 安装目录。关键：主配置在 WORKBUDDY_CONFIG_DIR，与安装位置解耦——重装时务必保留用户数据、只卸载程序；技能/记忆/连接器配置不丢，仅重登 + 重接连接器。重装前先全量备份主配置与 E:\.workbuddy（含 live 自动化）。
• ② 绝不开 / 登记安装目录为 workspace（零代价习惯）：不要把安装目录当项目浏览或打开。
• ③ 守护脚本兜底：scripts/guard-install-workbuddy.ps1 默认仅检查 + 写日志；加 -Fix 备份后移走误写的 .workbuddy，数据零丢失。

> ⚠️ 卸载必须由用户在退出实例后手动执行——WorkBuddy 正运行在被卸载的程序里，当前会话内卸载会杀掉自身。

步骤 2.5 · 侧边栏幽灵项目（如 Claw）特效修复

若 diagnose.py 报 "sessions 表有指向失效路径的 session"，说明侧边栏项目由失效 cwd 驱动、会反复复活。运行 scripts/fix_sessions.py（先自动备份 workbuddy.db，再改写失效 cwd 为有效路径，保留历史记录）：

python scripts/fix_sessions.py --dry-run   # 预览将要改写的条目
python scripts/fix_sessions.py             # 实际执行（自动备份 + 改写）

执行后重启 WorkBuddy，幽灵项目不再复活。回滚：用备份的 workbuddy.db.backup-sessionsfix-* 覆盖还原即可。

步骤 3 · 清理历史残留（回收站，非硬删）

只清理冗余 / 历史 / 备份类，绝不碰运行核心与实时缓存。用 scripts/recycle_cleanup.py 把目标送回收站（可恢复）。
- 可清理（送回收站）：旧安装位置残留目录（如 C:\Users\Administrator\WorkBuddy）、wb_backup_archive_*、*.workbuddy-moved-from-install-*、workbuddy.db.backup-*、automation-backups / plans / cloudstudio-deploy-history 等非实时历史目录。
- 绝不碰：安装目录程序本体 C:\Program Files\WorkBuddy；主配置内的 skills/memory/projects/sessions/connectors/settings.json/workbuddy.db 等运行核心；blobs/file-history/artifact-index/clipboard-images/app/logs 等运行时实时缓存（运行中硬删会破坏当前会话，且重启自动重建，无收益）。
- claw-state 等实时状态目录删后会被运行时重建，属运行必需，保留。

步骤 4 · 验证与记录

重跑 diagnose.py / guard-install-workbuddy.ps1 确认：安装目录内无 .workbuddy、workspaces 表无安装目录类记录。将清理结果记入项目记忆。

配套脚本

• scripts/diagnose.py — 只读诊断，自动探测安装/配置目录、检测 .workbuddy、读 workspaces+sessions 表并出清洁度结论
• scripts/fix_sessions.py — 修复侧边栏幽灵项目：备份后改写失效 cwd 为有效路径（根治 Claw 反复复活）
• scripts/guard-install-workbuddy.ps1 — 复发开关守护；默认检查，-Fix 清理
• scripts/recycle_cleanup.py — 送回收站安全清理（非硬删，可恢复）

详细 playbook（根因机制 / 三档方案 / 重装 SOP / 清理清单）

见 references/playbook.md。

注意

• 所有删除走回收站（recycle_cleanup.py），不硬删，留可恢复余量。
• 用户数据核心在 WORKBUDDY_CONFIG_DIR，与安装位置解耦；重装 / 清理前先备份该目录。
• workbuddy.db 可能含令牌 / 历史，清理前确认备份完整。