gh-zephyrdeng-cc-plugins-plugins-serena-indexer/commands/serena-cleanup.md

name, description, category, complexity, mcp-servers, personas

name	description	category	complexity	mcp-servers	personas
serena-cleanup	清理 Serena 索引数据，移除过期、损坏或冗余的索引文件以优化性能	maintenance	standard	serena	maintainer

/serena-cleanup - Serena 索引清理

Triggers

• 索引文件过大影响性能
• 磁盘空间不足
• 索引数据损坏需要重建
• 项目结构调整后的清理工作
• 定期维护和优化

Usage

/serena-cleanup [options]

Options:
  --dry-run          # 预览将要删除的文件，不实际删除
  --aggressive       # 激进清理，删除更多缓存文件
  --force           # 强制清理，不询问确认
  --backup          # 清理前创建备份
  --keep-days N     # 保留最近N天的索引（默认：7天）
  --cache-only      # 仅清理缓存文件，保留主索引
  --all             # 清理所有索引数据（重建用）

Behavioral Flow

1. 安全检查: 验证操作安全性和权限
2. 扫描分析: 识别过期、损坏和冗余文件
3. 空间计算: 计算可释放的磁盘空间
4. 用户确认: 显示清理计划并请求确认（除非使用 --force）
5. 执行清理: 安全删除标识的文件
6. 状态更新: 更新索引元数据

Examples

基本清理

/serena-cleanup
# 输出：
# 🔍 扫描索引数据...
#
# 📊 发现可清理文件:
# - 过期索引: 3 个文件 (45.2 MB)
# - 临时文件: 12 个文件 (8.7 MB)
# - 缓存文件: 156 个文件 (23.1 MB)
# - 损坏文件: 1 个文件 (2.3 MB)
#
# 💾 总计可释放: 79.3 MB
#
# ❓ 确认清理这些文件吗？[y/N]

预览清理

/serena-cleanup --dry-run
# 输出：
# 🔍 Serena 索引清理预览
#
# 📋 将要清理的文件:
# - .serena/cache_old/ (23.4 MB) - 过期缓存
# - .serena/tmp_20251015/ (12.7 MB) - 临时文件
# - .serena/index_backup.json (8.9 MB) - 旧备份
# - .serena/symbols_corrupt.json (2.1 MB) - 损坏文件
#
# 💾 可释放空间: 47.1 MB
# ⚠️ 这只是预览，不会实际删除文件

激进清理

/serena-cleanup --aggressive --keep-days 3
# 输出：
# 🧹 Serena 激进清理模式
#
# 📊 清理策略:
# - 保留最近: 3 天的索引
# - 清理范围: 所有缓存、备份、临时文件
# - 激进选项: 包括部分有用的缓存文件
#
# 📋 发现清理目标:
# - 过期索引: 8 个文件 (67.3 MB)
# - 缓存文件: 234 个文件 (45.8 MB)
# - 临时文件: 19 个文件 (15.2 MB)
# - 日志文件: 45 个文件 (8.9 MB)
#
# 💾 总计可释放: 137.2 MB
# ⚠️ 激进清理可能影响首次查询性能

仅清理缓存

/serena-cleanup --cache-only
# 输出：
# 🧹 Serena 缓存清理
#
# 📊 缓存文件统计:
# - 查询缓存: 89 个文件 (23.4 MB)
# - 符号缓存: 156 个文件 (34.7 MB)
# - 元数据缓存: 23 个文件 (5.6 MB)
# - 临时缓存: 67 个文件 (12.3 MB)
#
# 💾 可释放缓存空间: 76.0 MB
# ✅ 主索引文件将保留

备份清理

/serena-cleanup --backup
# 输出：
# 💾 创建清理备份...
# ✅ 备份已创建: .serena/backup_20251015_183022.tar.gz (89.2 MB)
#
# 🧹 执行清理操作...
# 📊 清理统计:
# - 删除文件: 167 个
# - 释放空间: 79.3 MB
# - 保留索引: ✅ 正常
#
# 🔒 备份位置: .serena/backup_20251015_183022.tar.gz
# ⚠️ 备份将在30天后自动删除

全部清理

/serena-cleanup --all --force
# 输出：
# ⚠️ 警告：将删除所有索引数据！
# 🗑️ 清理范围: .serena/ 目录下的所有文件
# 💾 将释放空间: 245.6 MB
#
# 🔄 执行全部清理...
# ✅ 索引数据已完全清理
#
# 📝 后续步骤:
# 1. 运行 /serena-index 重建索引
# 2. 验证索引完整性: /serena-status --health
# 3. 测试查询功能

Cleanup Targets

过期索引

• 超过保留期的旧索引文件
• 版本过时的索引数据
• 项目结构调整后的无效索引

缓存文件

• 查询结果缓存
• 符号解析缓存
• 临时计算缓存

临时文件

• 索引过程中生成的临时文件
• 中间处理结果
• 调试和日志文件

损坏文件

• 无法读取的索引文件
• 格式错误的数据文件
• 不完整的索引片段

Safety Features

自动备份

• 清理前自动创建备份
• 备份文件自动过期清理
• 支持自定义备份保留策略

权限检查

• 验证文件删除权限
• 检查索引文件完整性
• 防止误删重要数据

操作回滚

• 支持从备份恢复
• 清理日志记录
• 错误时自动回滚

Configuration Options

清理行为可以通过环境变量配置：

# 默认保留天数
export SERENA_CLEANUP_KEEP_DAYS=7

# 备份保留天数
export SERENA_BACKUP_RETENTION_DAYS=30

# 自动备份阈值 (MB)
export SERENA_AUTO_BACKUP_THRESHOLD=100

# 激进清理模式
export SERENA_AGGRESSIVE_CLEANUP=false

Integration with Monitoring

清理操作会生成详细报告：

• 清理统计信息
• 性能改进建议
• 后续维护计划

Error Handling

权限不足

❌ 权限不足，无法删除索引文件
💡 解决方案:
   1. 检查文件权限: ls -la .serena/
   2. 修复权限: chmod -R 755 .serena/
   3. 使用 sudo 重新运行 (不推荐)

磁盘空间不足

❌ 磁盘空间不足，无法创建备份
💡 解决方案:
   1. 使用 --no-backup 跳过备份
   2. 清理其他文件释放空间
   3. 使用外部存储设备

索引正在使用

⚠️ 检测到索引正在被使用
💡 建议操作:
   1. 等待当前查询完成
   2. 使用 --force 强制清理
   3. 重启 Claude Code 后重试