zcode-session-delete

删除 ZCode 会话，并生成可撤销备份。支持删除、恢复、撤销和备份列表查看。

适用场景

• 你需要在 ZCode 中删除某个会话，但原版没有直接删除能力。
• 你想保留可恢复的备份，避免误删。
• 你希望用统一 CLI 处理会话删除和恢复。

快速开始

python3 skills/zcode-session-delete/scripts/zcode-session-delete --help

常用命令

1. 验证会话是否存在

python3 skills/zcode-session-delete/scripts/zcode-session-delete verify <session_id>

2. 删除会话

python3 skills/zcode-session-delete/scripts/zcode-session-delete delete <session_id>

3. 批量删除项目会话

# 预览项目相关会话
python3 skills/zcode-session-delete/scripts/zcode-session-delete bulk-delete "<project>" --dry-run

# 执行删除
python3 skills/zcode-session-delete/scripts/zcode-session-delete bulk-delete "<project>"

# 跳过指定会话
python3 skills/zcode-session-delete/scripts/zcode-session-delete bulk-delete "<project>" --skip <session_id>

4. 查看备份列表

python3 skills/zcode-session-delete/scripts/zcode-session-delete list

5. 撤销删除

python3 skills/zcode-session-delete/scripts/zcode-session-delete undo <undo_token>

或直接恢复：

python3 skills/zcode-session-delete/scripts/zcode-session-delete restore <backup_path>

自定义备份目录

python3 skills/zcode-session-delete/scripts/zcode-session-delete \
  delete <session_id> --backup-dir /tmp/my-backups

成功标准

• 目标会话不再出现在 ~/.zcode/cli/db/db.sqlite 的 session 表和 ~/.zcode/v2/tasks-index.sqlite 的 tasks 表。
• 存在备份文件，可用于恢复。

注意事项

• 删除前会先备份；若删除失败会回滚数据库事务。
• 如发现数据异常，优先使用 undo <undo_token> 恢复。
• 可同时查看 ~/.zcode-session-delete/backups/ 了解历史备份。

故障排查

1. verify 返回 NOT_FOUND

• 确认 session_id 是否拼写正确。
• 检查 ~/.zcode/cli/db/db.sqlite 是否存在。
• 该会话可能已被删除，可执行 list 查看历史备份。

2. delete / bulk-delete 提示 "Session ... not found"

• 先执行 verify 或 bulk-delete --dry-run 确认会话是否仍存在。
• 确认你使用的是正确的名称或 session_id。

3. bulk-delete 匹配过多或过少

• 匹配基于 project_id、directory、path 的大小写不敏感模糊匹配。
• 使用 --dry-run 先查看匹配列表。
• 使用 --skip 排除不需要删除的会话。

4. 删除失败或中断

• 脚本在数据库删除阶段失败时会回滚已修改的 state 库。
• 如果数据库已回滚但备份文件已生成，可直接使用该备份。

5. 恢复失败

• 确认备份文件路径正确，且未手动修改 JSON。
• 如果提示已存在，脚本使用 INSERT OR IGNORE，不会覆盖已有数据。
• 如需强制恢复，可手动备份当前数据后再操作。

6. 权限问题

• 确保当前用户对 ~/.zcode/cli/db/db.sqlite 和 ~/.zcode-session-delete/backups 有读写权限。
• macOS/Linux 可使用 ls -ld 查看目录权限。

7. 需要人工检查

• 查看备份目录：ls -la ~/.zcode-session-delete/backups
• 查看当前 state 库：sqlite3 ~/.zcode/cli/db/db.sqlite "SELECT id, title FROM session WHERE id = '<session_id>';"