conversation-purge

English | 简体中文

你在 WorkBuddy 里点了「删除对话」，它没有真的删除。
这个文件，直到你动手之前，一直躺在你的硬盘上。

一个用于彻底清除 WorkBuddy 本地对话记录的工具，可独立运行，也可作为 Agent Skill 被对话式触发。

本项目为第三方独立工具，由个人开发者维护，与任何平台方无隶属或合作关系；名称与图标均为原创中性设计，不使用任何第三方品牌名称或官方头像。

一、需求从哪来

一个很具体的场景：某天翻了下自己的用户目录，发现 ~/.workbuddy/projects/ 下堆着十几个文件夹，打开一看是 .jsonl —— 逐行 JSON，明文，完整记录每一轮对话。

包括：

你说的每一句话
模型的思考过程
每一次工具调用的完整入参和返回结果（文件路径、命令输出、API 响应）

然后发现一件更麻烦的事：界面上已经删掉的对话，正文文件全都还在。

实测情形：projects/ 目录下堆着十几个文件夹，全部明文；其中若干条早已在界面里「删」过，正文依然完整保留。

二、为什么做这个

因为「删除」这个词在这个场景下具有误导性

在 WorkBuddy 界面删除会话，实际发生的事情是给数据库打个标记：

UPDATE sessions SET deleted_at = <时间戳> WHERE id = <会话UUID>

仅此而已。 列表里看不见了，文件一个没动。

这带来三个真问题：

问题	后果
隐私残留	你以为清掉了，别人打开文件夹就能看。含工具调用的完整上下文，信息密度远高于聊天文本本身
空间不释放	越积越多，`blobs`/`traces` 这类缓存目录增长更快，实测能占到上百 MB
无法批量处理	手动找文件路径靠肉眼，会话 UUID 和对话标题之间没有可读的对应关系

因为现成的办法都不好用

手动删 —— 要先从 SQLite 里查 UUID，再对着文件名找，十几条能忍，几十条不行
重装软件 —— 为了清聊天记录重装，代价完全不成比例
第三方清理软件 —— 不知道它具体删了什么，反而更不可控

所以需要一个：能看清删的是什么、能后悔、能批量的工具。

三、原理

数据落在哪

内容	路径
对话正文	`~/.workbuddy/projects/<项目ID>/<会话UUID>.jsonl`
回滚快照	同目录 `<UUID>.file-rollback.ndjson`
会话元信息	同目录 `<UUID>.meta.json`
软删除标记	`~/.workbuddy/workbuddy.db` → `sessions.deleted_at`
附件缓存	`~/.workbuddy/blobs`、`file-history`、`traces`、`artifact-index`

工具做了什么

读 workbuddy.db，拿到「哪些会话被标记删除」以及标题 —— 让 UUID 变回人能看懂的东西
扫描 projects/，把 <UUID>.jsonl / .file-rollback.ndjson / .meta.json 三个文件归为一组
先列清单给你看，标好大小和标题
确认后才删除，删完自动回收变空的项目文件夹

四、安装

作为 Skill（推荐，WorkBuddy / Claude Code 用户）

两份工具用同一份 SKILL.md，只是安装目录不同 —— 按你手上的工具挑一个：

# WorkBuddy
git clone https://github.com/DF-Guan/conversation-purge.git \
    ~/.workbuddy/skills/conversation-purge

# Claude Code
git clone https://github.com/DF-Guan/conversation-purge.git \
    ~/.claude/skills/conversation-purge

装好后直接在对话里说：

清理对话 / 删除聊天记录 / 释放空间 / 清理缓存 / purge chat history

Agent 会自动加载并按流程执行。

给 Claude Code 用户的提示：调用技能时工作目录不会切换到技能目录，因此务必用 ${CLAUDE_SKILL_DIR} 拼脚本路径：
python "${CLAUDE_SKILL_DIR}/scripts/cleanup.py" --list
SKILL.md 里已把这条写成硬性第一步。

作为独立脚本（不用 AI 工具的人）

git clone https://github.com/DF-Guan/conversation-purge.git
cd conversation-purge
python scripts/cleanup.py          # 弹出菜单，按提示操作

Windows 用户直接双击 Run-Cleanup.bat。

五、用法

Skill 模式（对话触发，最省心）

你只管说需求，剩下的 Agent 来做：

你：帮我清理对话
Agent：先给你看清单 → 你要 xx MB 吗？
你：删
Agent：请先退出 WorkBuddy → 执行 → 报告释放了多少空间

CLI 模式（想自己控制）

# 先看清单，什么都不删（这一步建议永远别跳过）
python scripts/cleanup.py --list

# 看看最占地方的是哪几个（按体积倒序）
python scripts/cleanup.py --list --top 10

# 只预览缓存清理会长什么样
python scripts/cleanup.py --list --cache-only

# 【最常用】只清缓存，保留所有对话
python scripts/cleanup.py --cache-only --backup --yes

# 只清界面里已删除的那些
python scripts/cleanup.py --soft-deleted --backup --yes

# 只清 30 天前的对话（支持 30d / 6m / 1y）
python scripts/cleanup.py --older-than 30d --backup --yes

# 清全部对话
python scripts/cleanup.py --all --backup --yes

# 全部对话 + 缓存目录
python scripts/cleanup.py --all --include-cache --backup --yes

# 连界面会话列表一起清空（数据库会先备份）
python scripts/cleanup.py --all --purge-db --backup --yes

# 后悔了，从备份还原
python scripts/cleanup.py --restore ~/Desktop/Chat-Purge-Backup/files-0911-092353

参数

参数	作用
`--list`	只预览，绝不删除。可与其他模式组合（`--list --cache-only`）
`--cache-only`	只清缓存，保留所有对话
`--soft-deleted`	只处理 `deleted_at` 非空的会话
`--older-than AGE`	只处理早于该时间的会话，支持 `30d` / `6m` / `1y`
`--all`	处理所有会话
`--top N`	按体积倒序只取前 N 项
`--include-cache`	附带清理 blobs / file-history / traces / artifact-index
`--backup`	删除前备份到 `~/Desktop/Chat-Purge-Backup/<时间戳>/`（含 `_manifest.txt`）
`--restore DIR`	从备份目录还原，文件回到原始路径
`--purge-db`	额外清空数据库里的会话列表（会先备份数据库）
`--yes`	跳过 `DELETE` 确认输入
`--backup-dir PATH`	自定义备份根目录

六、安全设计

删除是不可逆的，所以工具在几个地方刻意做得很保守：

强制预览 —— Agent 模式下，SKILL.md 硬性规定：没有把清单给用户看过，不允许执行删除
进程守护 —— 检测到 WorkBuddy 还在跑就不删（预览除外），避免删掉一半
双重确认 —— 手动输入 DELETE，或 Agent 已在对话中征得同意后才用 --yes
默认可备份 —— 备份开着才会后悔有门
备份可还原 —— 备份目录里带 _manifest.txt，记录原始绝对路径，--restore 能把文件放回原位
范围严格限定 —— 只碰 projects/、四个缓存目录和 workbuddy.db；不碰 skills/、connectors/、credentials/
--purge-db 会先备份数据库 —— 包括 .db / -wal / -shm 三个文件
留痕 —— 每次删除追加一行到 ~/.workbuddy/cleanup-audit.log，事后可查删了什么、什么时候删的

顺序很重要

先在界面里删（打软删除标记），再跑脚本删文件。

反过来会导致数据库记录和磁盘状态对不上。--soft-deleted 模式依赖这个标记。

七、常见问题

Q：删完界面列表还在？
正常。删文件不会同步删列表，数据库记录独立存在。想连列表一起清，用 --purge-db。

Q：Remove-Item 报 trash-failed 错？
多半实际已经删掉了（Windows 上的回收站机制所致）。删完重新列一遍目录确认，别只看报错。

Q：为什么有的条目没有标题？
少数会话（如后台定时任务）在数据库里没有标题字段，工具会退回显示其所属的项目文件夹名。

Q：当前正在聊的这个对话能删吗？
不能，文件正被占用。退出 WorkBuddy 后自然可删，不需要特殊处理。

Q：我只想释放空间，不想删对话？
用 --cache-only。blobs 和 traces 通常比对话本体大得多，清这两个就够了。

Q：之前 --all --include-cache 会连对话一起删，太吓人？
那是 1.0 的设计缺陷，1.1 已修：缓存清理现在是独立模式，不再捆绑删除对话。

Q：删完后悔了怎么办？
只要当时带了 --backup，就能还原：python scripts/cleanup.py --restore <备份目录>。
若备份里没有 _manifest.txt（1.0 生成的老备份没有），则无法自动定位原始路径。

Q：多久清一次合适？
blobs 和 traces 增长最快，建议一个月左右 --cache-only 一次。

Q：作为 Claude Code 技能为什么报「找不到脚本」？
调用技能不会切换工作目录，相对路径会失效。用 ${CLAUDE_SKILL_DIR}/scripts/cleanup.py。

八、⚠️ 使用前请注意

本工具会永久删除文件。

第一次用建议选 --list 先看一遍清单
不确定就带上 --backup
数据无价，动手前请确认自己知道在删什么

作为 Skill 使用时请留意：Agent 拥有了删除你本地文件的能力。SKILL.md 中已写明「预览后方可删除」的硬约束，若你自行修改该约束，风险自负。

九、兼容性

平台	状态
Windows	✅ 已实测（含回收站行为、PowerShell 编码）
macOS / Linux	⚠️ 代码支持（`pgrep` 检测、`expanduser("~")` 路径），尚未实机测试
Claude Code	✅ 兼容（frontmatter 字段均被支持），需用 `${CLAUDE_SKILL_DIR}` 定位脚本
WorkBuddy	✅ 原生支持

需要 Python 3.9+，无第三方依赖。三平台 × 三个 Python 版本由 GitHub Actions 自动跑测试。

自行验证

python tests/test_cleanup.py

9 个用例，全部用临时目录和假数据，不会碰到你的真实文件。

更新记录

2.5.0（2026-11） —— 合规重命名：技能名去掉平台缩写前缀，中文名改为「会话记录彻底清理」，英文名 Conversation Purge；图标换为原创中性图形（数据碎片消散），不再使用任何吉祥物/头像风格；SKILL.md 与 README 增加「第三方工具、非官方出品」声明；备份目录更名为 ~/Desktop/Chat-Purge-Backup/（旧目录 WB-Cleanup-Backup 仍可被 --list-backups / --restore-latest 识别，历史备份不丢）
2.4.1（2026-10） —— 更换应用图标，同步仓库与技能包
2.4.0（2026-10） —— 体验升级：清理完成后给出前后对比 + 对话/缓存分账报告；新增 --restore-latest（一键还原最近备份）与 --list-backups（列出可还原备份）；交互菜单新增「一键清理」档，且运行中即可操作不再要求退出应用
2.3.0（2026-10） —— 覆盖面与易用性升级：新增 --auto 一键模式（软删除残留 + 全部可再生缓存）；缓存范围补充 cache / shell-snapshots / logs/*.old.log；file-history、changes-detail 归为回滚数据默认保留；删除改为逐文件执行（单个占用文件不再中断整目录，也不触发环境批量删除保护）；--list 增加根目录总占用与可清理量总览；描述改为触发优先，并明确提示 agent 不要手工用 PowerShell 清理
2.2.0（2026-10） —— 支持 WorkBuddy 运行中直接清理：不再强制退出应用，被占用文件（如当前对话）自动跳过并标注，其余照常删除；--purge-db 运行中会明确拒绝并提示；释放空间统计改为按实际删除量计算
2.1.0（2026-09-30） —— 应用图标随包分发（assets/icon.png）；SKILL.md 增加 examples_zh / examples_en 示例问题，对齐开放平台「试试这样问我」表单
2.0.0（2026-09） —— 技能更名（当次定名 wb-conversation-purge，2.5.0 起改为 conversation-purge）；修复 --purge-db 参数从未传入执行函数的 bug；Windows 控制台输出加 UTF-8 保护；purge-db 与缓存清理写入审计日志；SKILL.md 按 WorkBuddy 开放平台规范补齐字段，已具备上架技能市场的完整 frontmatter
1.1.0 —— 缓存清理独立成模式，不再捆绑删除对话；新增备份与一键还原
1.0.0 —— 首发

License

MIT