Initial commit

2025-11-30 09:08:25 +08:00
commit abdf2c7c8f
10 changed files with 1653 additions and 0 deletions
--- a/commands/serena-cleanup.md
+++ b/commands/serena-cleanup.md
@@ -0,0 +1,238 @@
+---
+name: serena-cleanup
+description: "清理 Serena 索引数据，移除过期、损坏或冗余的索引文件以优化性能"
+category: maintenance
+complexity: standard
+mcp-servers: [serena]
+personas: [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
+
+清理行为可以通过环境变量配置：
+
+```bash
+# 默认保留天数
+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 后重试
+```
--- a/commands/serena-index.md
+++ b/commands/serena-index.md
@@ -0,0 +1,195 @@
+---
+name: serena-index
+description: "异步执行 Serena 项目索引，为项目建立语义理解和代码符号索引"
+category: project
+complexity: standard
+mcp-servers: [serena]
+personas: [architect]
+---
+
+# /serena-index - Serena 项目索引
+
+## Triggers
+- 项目首次使用 Serena MCP 时需要建立索引
+- 代码库发生重大变更后需要重新索引
+- 手动请求项目索引更新
+- 新项目 onboarding 流程的一部分
+- 索引工具响应变慢时需要重新索引
+
+## Usage
+```
+/serena-index [project-path] [options]
+
+Options:
+  --generate-config   # 生成 .serena/project.yml 配置文件
+  --reindex          # 强制重新索引，清除旧索引数据
+  --setup-hooks      # 配置自动索引 hook（会话开始时自动索引）
+  --status           # 查询当前索引状态和健康度
+  --smart            # 智能决策（仅在需要时索引）
+  --verify           # 验证索引完整性
+  --cleanup          # 清理过期索引数据
+```
+
+## 环境要求
+- 项目必须是 Git 仓库（需要 `.git` 目录）
+- Python 环境和 uvx 工具可用
+- 磁盘空间充足（索引文件可能较大）
+- Serena MCP 已配置并启用
+
+## Behavioral Flow
+1. **环境检测**: 验证 Git 仓库、Python 环境、Serena MCP 配置
+2. **配置准备**: 可选生成 `.serena/project.yml` 配置文件
+3. **委托执行**: 将索引任务委托给 serena-indexer agent 异步执行
+4. **进度监控**: 跟踪索引进度和统计信息
+5. **完成验证**: 验证索引数据完整性和可用性
+
+Key behaviors:
+- 自动检测项目是否配置了 Serena MCP
+- 使用 Task agent 异步执行，不阻塞主工作流
+- 提供清晰的进度反馈和完成状态
+- 支持配置文件生成和重新索引
+- 索引数据存储在 `.serena/` 目录
+
+## MCP Integration
+- **Serena MCP**: 执行 `uvx --from git+https://github.com/oraios/serena serena project index`
+- **Sequential MCP**: 用于复杂的索引状态分析和验证
+
+## Tool Coordination
+- **Task**: 委托给 serena-indexer agent 进行异步索引执行
+- **Bash**: 检查 MCP 配置和执行索引命令
+- **Read**: 读取项目配置文件验证 Serena 可用性
+
+## Key Patterns
+- **异步执行**: Task(serena-indexer) → 不阻塞主流程
+- **配置管理**: 生成配置 → 执行索引 → 验证完成
+- **环境验证**: Git 检查 → Python 检查 → MCP 配置检查
+- **错误处理**: 优雅处理索引失败，提供清晰错误信息和解决方案
+
+## Examples
+
+### 基本用法
+```
+/serena-index
+# 自动检测当前项目并异步执行索引
+# 索引数据将存储在 .serena/ 目录
+```
+
+### 首次使用（生成配置）
+```
+/serena-index --generate-config
+# 首先生成 .serena/project.yml 配置文件
+# 然后执行项目索引
+```
+
+### 指定项目路径
+```
+/serena-index /path/to/project
+# 为指定路径的项目执行索引
+```
+
+### 重新索引
+```
+/serena-index --reindex
+# 强制重新索引，清除旧索引数据
+# 适用于代码库发生重大变更的情况
+```
+
+### 配置自动索引 Hook
+```
+/serena-index --setup-hooks
+# 交互流程：
+# ? 选择配置范围:
+#   > 全局配置（所有项目）: ~/.claude/settings.json
+#     项目配置（仅当前项目）: .claude/settings.json
+# ? 选择触发时机:
+#   > SessionStart（会话开始时）
+#     PreToolUse（使用 Serena MCP 工具前）
+#     仅手动触发
+# ? 选择索引策略:
+#     总是索引
+#   > 智能判断（推荐）
+#     仅手动触发
+# ✅ Hook 配置已创建: .claude/settings.json
+# ✅ Hook 脚本已创建: .claude/hooks/serena-auto-index.sh
+#
+# 下次会话开始或使用 Serena MCP 工具时，hook 将自动检查并更新索引
+```
+
+### 查询索引状态
+```
+/serena-index --status
+# 输出：
+# 📊 Serena 索引状态
+#
+# 项目: /path/to/your/project
+# 上次索引: 2小时前 (2025-10-15 17:30:45)
+# 索引文件: 94 个 Go 文件
+# 提取符号: 1,248 个（函数: 453, 类: 127, 变量: 668）
+# 索引大小: 12.3 MB
+# 健康度: ✅ 良好（索引新鲜，数据完整）
+#
+# 建议: 无需重新索引
+```
+
+### 智能索引
+```
+/serena-index --smart
+# 智能判断是否需要重新索引
+# 如果索引新鲜且文件变更少，则跳过索引
+# 输出：
+# 🔍 检查索引状态...
+# ✅ 索引仍然新鲜（2小时前），跳过索引
+# 或
+# 🔄 检测到 15 个文件变更，正在更新索引...
+```
+
+### 验证索引完整性
+```
+/serena-index --verify
+# 验证索引数据是否完整和可访问
+# 输出：
+# 🔍 正在验证索引完整性...
+# ✅ 索引数据完整，所有符号可访问
+# 或
+# ❌ 检测到索引损坏，建议重新索引
+```
+
+### 清理旧索引
+```
+/serena-index --cleanup
+# 清理过期或损坏的索引数据
+# 输出：
+# 🗑️ 清理旧索引数据...
+# ✅ 已清理 45.2 MB 过期索引
+```
+
+## 索引输出
+- **索引位置**: `.serena/` 目录
+- **日志文件**: `.claude/doc/serena_index_log.md`
+- **统计信息**: 文件数量、符号数量、执行时长
+- **错误报告**: 详细的错误堆栈和解决建议
+
+## Boundaries
+
+**Will:**
+- 自动检测 Serena MCP 配置状态和 Git 仓库
+- 异步执行索引命令，不阻塞主工作流
+- 可选生成项目配置文件 `.serena/project.yml`
+- 生成自动索引 hook 脚本（--setup-hooks）
+- 查询索引状态和健康度（--status）
+- 智能决策是否需要重新索引（--smart）
+- 验证索引完整性（--verify）
+- 清理过期索引数据（--cleanup）
+- 提供清晰的进度和状态反馈
+- 验证索引完成和项目可用性
+- 处理索引失败并提供解决方案
+- 询问用户偏好（hook 范围、触发时机、索引策略）
+
+**Will Not:**
+- 在未配置 Serena MCP 时强制执行索引
+- 在非 Git 仓库中执行索引
+- 在索引过程中占用主对话流程
+- 覆盖用户的 MCP 配置设置
+- 修改项目源代码文件
+- 在用户未确认的情况下安装 hook
+- 强制使用特定的索引策略
--- a/commands/serena-status.md
+++ b/commands/serena-status.md
@@ -0,0 +1,161 @@
+---
+name: serena-status
+description: "查询 Serena 索引状态和健康度，提供详细的索引统计信息"
+category: monitoring
+complexity: simple
+mcp-servers: [serena]
+personas: [monitor]
+---
+
+# /serena-status - Serena 索引状态查询
+
+## Triggers
+- 需要检查索引是否最新
+- 索引响应变慢时诊断
+- 定期维护和监控
+- 验证索引完整性
+
+## Usage
+```
+/serena-status [options]
+
+Options:
+  --detailed          # 显示详细的统计信息
+  --health           # 执行健康度检查
+  --performance      # 显示性能指标
+  --format json|table|markdown  # 输出格式
+```
+
+## Behavioral Flow
+1. **索引检测**: 检查 .serena 目录和元数据文件
+2. **统计分析**: 分析索引文件大小、符号数量、更新时间
+3. **健康评估**: 评估索引完整性和性能状态
+4. **建议输出**: 提供维护建议和优化选项
+
+## Examples
+
+### 基本状态查询
+```
+/serena-status
+# 输出：
+# 📊 Serena 索引状态
+#
+# 项目: /Users/zephyr/my-project
+# 状态: ✅ 健康
+# 上次索引: 2小时前 (2025-10-15 17:30:45)
+# 索引文件: 94 个 Go 文件
+# 提取符号: 1,248 个
+#  - 函数: 453 个
+#  - 类: 127 个
+#  - 变量: 668 个
+# 索引大小: 12.3 MB
+#
+# 建议: 索引状态良好，无需更新
+```
+
+### 详细状态查询
+```
+/serena-status --detailed
+# 输出：
+# 📊 Serena 详细索引状态
+#
+# 🗂️ 索引文件信息:
+# - project_index.json: 8.2 MB (主索引)
+# - symbols_functions.json: 2.1 MB (函数符号)
+# - symbols_classes.json: 1.8 MB (类符号)
+# - symbols_variables.json: 3.2 MB (变量符号)
+# - metadata.json: 15.6 KB (元数据)
+#
+# 📈 性能指标:
+# - 平均查询时间: 45ms
+# - 内存占用: 23.4 MB
+# - 缓存命中率: 87%
+# - 并发查询支持: ✅
+#
+# 🔄 更新历史:
+# - 最后更新: 2025-10-15 17:30:45
+# - 更新耗时: 4m 32s
+# - 更新原因: 15 个文件变更
+# - 更新策略: 增量更新
+#
+# 💡 优化建议:
+# - 索引质量优秀，性能良好
+# - 建议定期执行完整性检查
+# - 可考虑启用智能缓存优化
+```
+
+### 健康检查
+```
+/serena-status --health
+# 输出：
+# 🔍 Serena 索引健康检查
+#
+# ✅ 索引完整性: 通过
+# ✅ 符号可访问性: 通过
+# ✅ 文件同步状态: 通过
+# ✅ 缓存状态: 优秀
+# ⚠️ 索引年龄: 2小时 (建议<6小时)
+# ✅ 磁盘空间: 充足 (1.2GB 可用)
+# ✅ 权限设置: 正常
+#
+# 🎯 总体健康度: 95/100 (优秀)
+#
+# 📋 维护建议:
+# - 索引状态良好，建议保持当前配置
+# - 可设置自动更新策略以保持索引新鲜度
+```
+
+### 性能分析
+```
+/serena-status --performance
+# 输出：
+# ⚡ Serena 性能分析
+#
+# 📊 响应时间统计:
+# - 平均查询时间: 45ms
+# - 95% 分位时间: 89ms
+# - 最慢查询: 234ms (查找复杂符号)
+# - 最快查询: 12ms (简单函数查找)
+#
+# 💾 内存使用分析:
+# - 索引加载: 23.4 MB
+# - 缓存占用: 8.7 MB
+# - 查询缓存: 5.2 MB
+# - 总内存占用: 37.3 MB
+#
+# 🚀 性能优化建议:
+# - 索引性能优秀，无需优化
+# - 可增加缓存大小以提升命中率
+# - 考虑启用并行查询以提升复杂查询性能
+```
+
+## Output Format Options
+
+### JSON 格式
+```
+/serena-status --format json
+# 输出结构化的 JSON 数据，便于程序化处理
+```
+
+### Table 格式
+```
+/serena-status --format table
+# 输出表格格式，便于快速浏览
+```
+
+### Markdown 格式
+```
+/serena-status --format markdown
+# 输出 Markdown 格式，便于文档生成
+```
+
+## Integration with Other Commands
+- 与 `/serena-index` 配合使用进行索引管理
+- 与 `/serena-cleanup` 配合进行性能优化
+- 支持 pipe 输出到其他工具
+
+## Error Handling
+- 索引不存在时提供清晰的指导
+- 权限问题时提供解决方案
+- 磁盘空间不足时发出警告
+- 索引损坏时建议重建