tooyoung:cc-session-cleaner

CC Session Cleaner — CC 会话清理

清理 Claude Code ~/.claude/projects/<project-slug>/ 下不再需要的会话文件。默认不是按标题自动删除，而是先列出当前项目最近会话，让用户挑选后再删除。

背景知识

每个 CC 会话在 ~/.claude/projects/<project-slug>/ 下通常对应两类路径：

<session-id>.jsonl   ← 会话消息流（可能含 custom-title 行）
<session-id>/        ← 同名子目录：附件、shell snapshot 等

cc resume 列表里的标题来自 .jsonl 中的 custom-title 行：

{ "type": "custom-title", "customTitle": "xxx", "sessionId": "<session-id>" }

触发场景

用户说出以下任一意图即触发：

• "清理 cc 会话" / "清理会话" / "删除一些历史会话"
• "看看最近有哪些会话可以删" / "列出没必要的会话"
• "cc resume 里有些会话想删掉"
• "cc session cleaner" / "clean cc sessions" / "clean marked sessions"
• "清理标题是 xxx 的会话" / "看看有哪些标了待删除"

默认工作流

默认走交互挑选模式：

1. 定位项目目录：按「项目目录推导」探测当前 cwd 对应的 ~/.claude/projects/<project-slug>/。
2. 列出会话：默认展示最近 30 条 .jsonl，按 mtime 倒序排列；用户明确要求"全部"/all 时展示全部会话。
3. 等待用户挑选：用户用序号或 sessionId 指定要删除的会话，例如 删除 1 3 8 或 删除 abc def。
4. 复述删除清单：列出将删除的 .jsonl 与同名子目录；如果用户选中当前会话，保留在提示中但标记为不可删除并剔除。
5. 二次确认后删除：只在收到强确认后删除可删除项。
6. 核验残留：删除后确认 .jsonl 与同名目录均不存在。

输出字段

预览表必须包含：

字段	说明
#	本次预览序号，用于用户选择
current	当前会话标记；匹配显式 current session id 时显示 CURRENT，否则为空
sessionId	.jsonl 文件名去掉后缀
title	最近一条 custom-title，没有则为空
mtime	.jsonl 修改时间
size	.jsonl 大小，按 B/KB/MB/GB 自动切换
first user prompt	首条非 caveat 的 user prompt，截断 80 字
recent user prompt	最近一条非 caveat 的 user prompt，截断 80 字

表格展示要求

预览和删除复述都必须优先使用 Markdown 表格，避免用散乱项目符号代替关键清单：

• 最终回复必须是渲染后的 Markdown 表格：脚本输出可以作为数据源，但不要把原始终端输出或代码块当作最终预览交给用户。
• 预览会话时，先用一句话说明项目目录与命中数量，再输出完整预览表；列顺序固定为 #、current、sessionId、title、mtime、size、first user prompt、recent user prompt。
• 复述将删除的会话时，必须使用表格列出 sessionId、jsonl path、attachment dir、status。
• 如果选中当前会话，仍在复述表中展示，但 status 必须标为 不可删除：当前会话，且不得传入删除脚本。
• 表格单元格内容应压缩到可读长度；prompt 已由预览脚本截断，路径可完整展示以便用户确认。

用法示例

用户口谕	行为
"清理一下 cc 会话"	列出当前项目最近 30 条会话，等待选择
"列出最近 50 条会话"	列出当前项目最近 50 条会话
"列出全部会话" / "list all"	列出当前项目全部会话
"删除 1 3 8"	复述序号 1、3、8 对应会话，等待 确认删除
"删除 sid=abc sid=xyz"	复述指定 sessionId，等待 确认删除
"看看 title 是 待删除 的会话"	严格筛选 customTitle == "待删除" 后展示

二次确认协议（删除红线）

任何形态的删除一律走两步，即便用户首条口谕已显含"删除"语义：

Step 1. AI 列表/解析选择 → 复述将删除的路径 → 询问：「是否执行删除？请回复『确认删除』或『取消』。」
Step 2. AI 等待 → 仅当用户回复强确认词才执行删除。

视为有效的强确认：

• 中文：确认删除 / 确认清理
• 英文：confirm delete / yes delete

不视为确认：

• 模糊回应：好 / 嗯 / ok / 行 / 知道了 / 继续 / 执行 / 删
• 沉默 / 切换话题 / 重新提其他要求
• 反问：这些是什么时候的？ / 能恢复吗？

用户说"直接删"、"不用预览"、"不用确认"也不能绕过预览和二次确认。CC 会话删除后不可由本 skill 恢复。

项目目录推导（多候选探测 + 兜底）

CC 把每个项目的会话存在 ~/.claude/projects/<slug>/，但 slug 规则随 CC 版本演进，磁盘上可能多代命名并存：

路径片	旧规则	新规则
/	-	-
.（隐藏目录如 .config）	保留	-
空格	保留	-

没有可靠的 $CLAUDE_PROJECT_DIR 环境变量可直接使用，必须自行推导。

derive_projdir() {
  local cwd="${1:-$PWD}"
  local base="$HOME/.claude/projects"
  local c1="$base/$(printf '%s' "$cwd" | sed 's|/|-|g')"
  local c2="$base/$(printf '%s' "$cwd" | sed -e 's|/|-|g' -e 's|\.|-|g')"
  local c3="$base/$(printf '%s' "$cwd" | sed -e 's|/|-|g' -e 's|\.|-|g' -e 's| |-|g')"
  for cand in "$c1" "$c2" "$c3"; do
    [ -d "$cand" ] && { echo "$cand"; return 0; }
  done
  return 1
}

候选全空时，列出 ~/.claude/projects/ 目录请用户确认，不要擅自模糊匹配。

推荐脚本结构

按 Agent Skills 标准结构，长脚本应拆到 skill 目录下的 scripts/：

skills/cc-session-cleaner/
├── SKILL.md
└── scripts/
    ├── preview_sessions.py
    └── delete_sessions.py

• scripts/preview_sessions.py：列出会话，输出 Markdown 表格数据。
• scripts/delete_sessions.py：仅在强确认后删除指定 sessionId 的 .jsonl 与同名目录。
• SKILL.md 只保留流程、参数约定、安全红线和展示要求。

推荐预览命令

PROJDIR="${1:-$(derive_projdir)}" || { echo "无法定位项目目录，请显式指定" >&2; exit 1; }
LIMIT="${2:-30}"
MARK="${3:-}"
CURRENT_SESSION_ID="${4:-${CLAUDE_SESSION_ID:-}}"
python3 skills/cc-session-cleaner/scripts/preview_sessions.py "$PROJDIR" --limit "$LIMIT" --mark "$MARK" --current-session-id "$CURRENT_SESSION_ID"

当前会话说明：每个 Claude Code 会话都有 sessionId；如果 shell 中没有 $CLAUDE_SESSION_ID，只表示脚本没有拿到当前会话 id，不表示当前会话没有 id。若用户从 /status 或其它可靠来源提供当前 sessionId，应作为 --current-session-id 传入并用于 CURRENT 标记。

选择解析规则

• 用户可以用本次预览的序号选择：删除 1 3 8。
• 用户可以用 sessionId 选择：删除 abc123 def456。
• 只允许删除本次预览表里出现过的 sessionId；未出现在预览表里的 id 必须重新预览或要求用户确认来源。
• 如果用户混用序号和 sessionId，AI 需要归一化成 sessionId 并复述。
• 预览表可以列出当前会话；如果用户选择当前会话，必须明确提示"当前会话不能删除"，并把它从实际删除清单中剔除。
• 预览表必须包含 current 列；如果拿到显式 current session id（例如用户从 /status 提供，或环境变量 $CLAUDE_SESSION_ID 可用），匹配行显示 CURRENT。
• 如果无法取得当前 session id，不要声称已自动识别当前会话；只能说明当前会话 id 未传入或未暴露给脚本。

当前会话保护

• 当前会话也可以出现在预览表里，方便用户理解 cc resume 中看到的完整候选集。
• 每个 Claude Code 会话都有 sessionId；$CLAUDE_SESSION_ID 为空只表示脚本没拿到当前会话 id，不表示当前会话没有 id。
• 预览时如能从显式参数或 $CLAUDE_SESSION_ID 识别当前会话，必须在 current 列标记为 CURRENT。
• 删除前如能识别当前会话，且用户选中了它，必须在复述清单中单独列为"不可删除"。
• 不可删除项不得传入删除脚本；如果用户只选择了当前会话，不执行删除，并说明需要选择其他会话。
• 如果无法取得当前 sessionId，不要声称已识别当前会话，也不要基于标题、mtime 或 prompt 猜测当前会话。

删除命令（仅在强确认后执行）

PROJDIR="$HOME/.claude/projects/<slug>"
python3 skills/cc-session-cleaner/scripts/delete_sessions.py "$PROJDIR" sid1 sid2 sid3

安全护栏（红线）

• ❌ 未经二次确认不可删除：必须先预览或复述删除清单，再等强确认。
• ❌ 不得默认跨项目删除：除非用户明确指定其他项目目录，否则只动当前项目目录。
• ❌ 不得自动按时间批量删除：本 skill 只列出候选并让用户挑选。
• ❌ 不得 fuzzy 匹配标题：标题筛选必须 customTitle == MARK 严格相等。
• ❌ 不得删除预览表外的会话：用户输入序号或 sessionId 后，必须映射到已展示候选。
• ❌ 不得删除当前会话：当前会话可展示但不可删除；选中时必须提示并剔除。
• ❌ 不得扩大确认范围：多个项目目录必须分别预览、分别确认。

边界情况

• 零会话：告知当前项目没有可展示的 .jsonl 会话。
• 用户只说"清理"：只展示最近会话，不删除。
• 用户选择不存在的序号：指出无效序号并要求重新选择。
• 当前会话被选中：如能识别当前 sessionId，提示当前会话不能删除，并从实际删除清单剔除。
• 目录不存在：明确告知项目目录不存在，请用户提供正确路径。

与相关 skill 的边界

• 本 skill 只清理 Claude Code 会话 .jsonl 与同名附件目录。
• 本 skill 不动 memory 系统（memory/MEMORY.md 等）。
• 如果系统里装了 claude-mem 等基于 .jsonl 建索引的插件，删除前提醒：相关 observations / corpus 引用可能指向已删除原文，但记忆数据本身仍在。