5.8 KiB
5.8 KiB
name, description, category, complexity, mcp-servers, personas
| name | description | category | complexity | mcp-servers | personas | ||
|---|---|---|---|---|---|---|---|
| serena-index | 异步执行 Serena 项目索引，为项目建立语义理解和代码符号索引 | project | standard |
|
|
/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
- 环境检测: 验证 Git 仓库、Python 环境、Serena MCP 配置
- 配置准备: 可选生成
.serena/project.yml配置文件 - 委托执行: 将索引任务委托给 serena-indexer agent 异步执行
- 进度监控: 跟踪索引进度和统计信息
- 完成验证: 验证索引数据完整性和可用性
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
- 强制使用特定的索引策略