Context Tools for Claude Code

这个技能为大型代码库提供智能上下文管理，通过：

仓库映射：解析Python、Rust和C++代码以提取类、函数和方法
重复检测：使用模糊匹配识别相似的代码模式
MCP符号服务器：通过search_symbols和get_file_symbols工具实现快速符号搜索
自动索引：文件变化时进行背景增量更新

使用MCP工具 - 主要代码探索方法

⚡ 决策树 - 在使用Grep/Search/Bash之前问自己：

我是否在搜索代码符号（函数、类、枚举、结构体、类型）？
├─ 是 → 使用MCP工具（search_symbols / get_symbol_content / get_file_symbols）
│         例如：寻找 "enum InstructionData" → search_symbols("InstructionData")
│         例如：寻找 "Phi" 变体 → get_symbol_content("InstructionData")
│
└─ 否 → 我是否在搜索文本/注释/字符串/配置值？
          └─ 是 → 使用Grep/Search
                   例如：寻找字符串字面量、文档、JSON值

关键：当你需要：

按名称或模式查找函数/类/方法 → search_symbols
了解如何使用一个函数（参数、返回类型）→ search_symbols或get_symbol_content
获取特定函数/类的源代码 → get_symbol_content
查看文件中的所有代码 → get_file_symbols
发现代码库中存在的功能 → 使用模式search_symbols

不要使用Grep或Bash进行这些任务 - 仓库映射工具是：

更快（预索引SQLite数据库）
更准确（AST解析，不是正则表达式）
更多信息（包括签名、文档字符串、行范围）

何时使用Grep代替：

搜索字符串字面量、注释或任意文本
在非代码文件中搜索（markdown、配置等）
跨文件文本模式搜索

工具可用性检查： 在尝试使用MCP工具（mcp__plugin_context-tools_repo-map__*）之前，检查.claude/repo-map.db是否存在：

如果是：尝试MCP工具。如果失败（不可用），请使用sqlite3回退。
如果没有：项目尚未索引。要么等待索引完成，要么运行/context-tools:repo-map生成它。

回退顺序：

首先尝试MCP工具
如果工具未找到，使用sqlite3回退以回答问题
解释会话需要重新启动以加载MCP服务器以供将来使用

真实世界使用示例

示例1：用户问“我们可以与OSDI比较吗？”

低效方法（不要这样做）：

grep -r "setup_model\|setup_instance" jax_spice/devices/*.py

问题：慢，容易出错的模式匹配，在大型代码库上容易中断。

高效方法（这样做）：

mcp__plugin_context-tools_repo-map__search_symbols
pattern: "setup_*"

结果：立即列出所有setup_model、setup_instance等，包括位置和签名。

示例2：用户问“配置加载器如何工作？”

低效方法（不要这样做）：

find . -name "*.py" -exec grep -l "class.*Config" {} \;

高效方法（这样做）：

mcp__plugin_context-tools_repo-map__search_symbols
pattern: "*Config*"
kind: "class"

然后获取源代码：

mcp__plugin_context-tools_repo-map__get_symbol_content
name: "ConfigLoader"

示例3：用户问“utils.py中有哪些函数？”

低效方法（不要这样做）：

grep "^def " src/utils.py

高效方法（这样做）：

mcp__plugin_context-tools_repo-map__get_file_symbols
file: "src/utils.py"

结果：完整的所有函数/类列表，包括签名和文档字符串。

示例4：寻找Rust枚举变体（真实用户案例）

用户需要检查enum InstructionData中是Phi还是PhiNode。

低效方法（不要这样做）：

grep -n "enum InstructionData" openvaf-py/vendor/OpenVAF/openvaf/mir/src
grep -n "Phi" openvaf-py/vendor/OpenVAF/openvaf/mir/src/instructions.rs

问题：多次搜索，手动解析，容易错过正确的变体。

高效方法（这样做）：

mcp__plugin_context-tools_repo-map__search_symbols
pattern: "InstructionData"

mcp__plugin_context-tools_repo-map__get_symbol_content
name: "InstructionData"

结果：完整的枚举，包括所有变体，包括PhiNode(_)。

第一次设置

重要：如果用户刚刚安装了这个插件：

"我看到你安装了context-tools插件。MCP服务器应该在重新启动后自动配置。重新启动Claude Code后，运行/mcp以验证repo-map服务器是否已加载。

如果它没有自动加载，请告诉我，我可以帮助使用/context-tools:setup-mcp进行故障排除。"

MCP服务器从插件清单自动配置。只有在自动配置失败时才运行/context-tools:setup-mcp进行故障排除。

包含组件

钩子

SessionStart：生成项目清单并显示状态
PreCompact：在压缩前刷新上下文
SessionEnd：清理操作

注意：索引现在由MCP服务器本身处理（不需要PreToolUse钩子）。

MCP服务器（repo-map）

数据库架构（.claude/repo-map.db）：

symbols表列：
- name (TEXT): 符号名称（函数/类/方法名称）
- kind (TEXT): "function", "class", 或 "method"
- signature (TEXT): 完整的函数/方法签名，包括参数和类型提示
  例子：
  - "extract_symbols_from_python(file_path: Path, relative_to: Path) -> list[Symbol]"
  - "analyze_files(files: list[Path], extractor, language: str, root: Path)"
- docstring (TEXT): 文档字符串的第一行或完整文档字符串
- file_path (TEXT): 从项目根目录的相对路径
- line_number (INTEGER): 开始行（1-索引）
- end_line_number (INTEGER): 结束行（1-索引）
- parent (TEXT): 对于方法，类名称

metadata表（v0.7.0+）：
- key (TEXT PRIMARY KEY): 元数据键
- value (TEXT): 元数据值
键：
- 'status': 'idle' | 'indexing' | 'completed' | 'failed'
- 'index_start_time': 索引开始时的ISO8601时间戳
- 'last_indexed': 上次完成时的ISO8601时间戳
- 'symbol_count': 索引的总符号数（字符串）
- 'error_message': 如果状态='failed'，则为错误消息

索引状态和自动等待（v0.7.0+）：

MCP服务器在元数据表中跟踪索引状态
工具自动等待（最多60秒）如果索引正在进行
看门狗：检测挂起的索引（>10分钟）并将状态重置为’failed’
首次使用：在新代码库中首次使用时，索引自动开始
行为：大多数工具等待完成，repo_map_status不等待（用于检查进度）

可用MCP工具：

mcp__plugin_context-tools_repo-map__search_symbols - 按模式搜索符号（支持通配符）
- 返回：name, kind, signature, file_path, line_number, docstring, parent
- AUTO-WAIT：如果索引正在进行，自动等待最多60秒完成
mcp__plugin_context-tools_repo-map__get_file_symbols - 获取特定文件中的所有符号
- 返回：所有符号的完整元数据
- AUTO-WAIT：如果索引正在进行，自动等待最多60秒完成
mcp__plugin_context-tools_repo-map__get_symbol_content - 通过确切名称获取符号的完整源代码
- 返回：符号元数据+内容（源代码文本）+位置
- AUTO-WAIT：如果索引正在进行，自动等待最多60秒完成
mcp__plugin_context-tools_repo-map__list_files - 列出所有索引的文件，可选地按通配符模式过滤
- 返回：与模式匹配的文件路径列表（例如，“.va", “psp103”, "**/devices/”）
- 比find/ls快得多 - 查询预构建索引而不是文件系统遍历
- AUTO-WAIT：如果索引正在进行，自动等待最多60秒完成
mcp__plugin_context-tools_repo-map__reindex_repo_map - 触发手动重新索引
- 不自动等待（用于强制重新索引）
mcp__plugin_context-tools_repo-map__repo_map_status - 检查索引状态和陈旧性
- 返回：index_status (idle/indexing/completed/failed), symbol_count, last_indexed, indexing_duration_seconds
- 不自动等待（用于检查状态）
mcp__plugin_context-tools_repo-map__wait_for_index - 显式等待索引完成
- 接受：timeout_seconds（默认：60）
- 返回：success (bool), message (str)
- 当你想要等待超过默认60秒自动等待超时时使用

MCP工具不可用时的回退： 直接在.claude/repo-map.db上使用sqlite3：

# 搜索符号
sqlite3 .claude/repo-map.db "SELECT name, kind, signature, file_path, line_number FROM symbols WHERE name LIKE 'pattern%' LIMIT 20"

# 获取带源代码的符号
sqlite3 .claude/repo-map.db "SELECT * FROM symbols WHERE name = 'function_name'"
# 然后读取file_path行line_number到end_line_number

斜杠命令

/context-tools:repo-map - 重新生成仓库映射
/context-tools:manifest - 刷新项目清单
/context-tools:learnings - 管理项目学习
/context-tools:status - 显示插件状态

语言支持

语言	解析器	文件扩展名
Python	AST	`.py`
Rust	tree-sitter-rust	`.rs`
C++	tree-sitter-cpp	`.cpp`, `.cc`, `.cxx`, `.hpp`, `.h`, `.hxx`