codebase-exploration

SocratiCode 代码库探索

使用 SocratiCode MCP 工具高效探索代码库。核心原则： 先搜索，再阅读——索引能在毫秒内为你绘制代码库地图； 直接读取文件既耗时，又会占用上下文。

工作流

1. 大多数探索任务都从 codebase_search 开始

混合语义 + 关键词搜索（向量 + BM25，通过 RRF 融合）在一次调用中完成。

• 用于了解概况的宽泛查询："如何处理身份验证"、"数据库连接设置"、"错误处理模式"
• 用于查找符号的精确查询：确切的函数名、常量、类型名
• 优先根据搜索结果推断要读取哪些文件——不要凭猜测打开文件
• 使用 fileFilter 将搜索范围缩小到一个文件；路径必须与结果标题中显示的完全一致。目录、glob 模式或根目录下文件的裸文件名都无法匹配
• 使用 languageFilter 将搜索范围缩小到一种语言；标签必须与结果标题方括号中的内容完全一致（例如 typescript，而不是 ts）
• 调整 minScore（默认值为 0.10），在精确率和召回率之间取舍——值越低，结果越多；值越高，匹配越严格

何时改用 grep：如果你已知确切的标识符、错误字符串或正则表达式模式，grep/ripgrep 会更快、更准确——无需弥合语义差距。探索代码库、提出概念性问题，或不知道该查找哪些文件时，使用 codebase_search。

2. 先查看依赖图，再追踪导入

深入文件内容之前，先用 codebase_graph_query 查看文件导入了什么，以及哪些内容依赖它。这可以避免不必要地读取传递依赖。

• codebase_graph_query——查询任意文件的导入项和依赖方（传入相对路径）
• codebase_graph_stats——架构概览：文件总数、边数、连接最多的文件、孤立文件、语言分布
• codebase_graph_circular——查找循环依赖（它们会导致不易察觉的运行时错误；调试意外行为时应主动检查）
• codebase_graph_visualize——按语言着色的 Mermaid 图，并以红色突出显示循环依赖。也可以传入 mode: "interactive"，改为打开独立的 HTML 探索器（文件与符号视图、影响范围叠加层、搜索、PNG 导出——支持离线使用）。

索引完成后会自动构建依赖图。使用 codebase_graph_status 检查依赖图是否就绪。在 SOCRATICODE_WATCHER=manual 或 off 模式下，依赖图查询不会创建缺失的依赖图；如有需要，请显式运行 codebase_graph_build。

3. 先通过搜索缩小范围，再读取文件

搜索结果明确指向 1-3 个文件后，只读取相关部分。切勿为了判断文件是否相关而读取文件——先搜索。

一次 codebase_search 调用即可在毫秒内返回遍布整个代码库、按相关度排序且去重的代码片段。这能以极低的 token 成本为你绘制全局地图——远比凭猜测打开文件划算。

4. 利用上下文资料了解非代码知识

项目可以定义 .socraticodecontextartifacts.json 配置，以提供数据库架构、API 规范、基础设施配置、架构文档以及其他存储在源代码之外的项目知识。

• codebase_context——列出可用资料（名称、描述、路径、索引状态）
• codebase_context_search——对所有资料进行语义搜索（或使用 artifactName 筛选）
• 首次搜索时会自动为资料建立索引，并自动检测内容是否过时

尽早运行 codebase_context，查看有哪些资料可用。询问数据库结构、API 契约或基础设施相关问题前，先使用 codebase_context_search。

5. 如果似乎有问题，请检查状态

• codebase_status — 检查索引状态、进度、监视器状态和图状态
• 如果搜索没有返回结果，项目可能尚未建立索引
• 如果监视器未激活，结果可能已过时——运行 codebase_update；仅当状态未显示已禁用时才启动监视器
• 在快照模式下（SOCRATICODE_WATCHER=off 加上 SOCRATICODE_AUTO_RESUME=off），在显式更新之前，结果过时是预期情况。不要启用或启动监视器。
• 在 Git 模式下（SOCRATICODE_WATCHER=git），搜索、图和状态请求会报告刷新状态。不要将待处理、失败或未经验证的结果视为当前结果。Git 状态变化会触发刷新；如需立即刷新工作树编辑，请使用 codebase_update。不要启动文件监视器。

6. 查看所有工具概览

• codebase_about — 快速了解所有 SocratiCode 工具和典型工作流

目标 → 工具速查表

目标	工具
了解代码库的用途 / 某项功能的位置	codebase_search（宽泛查询）
查找特定函数、常量或类型	codebase_search（精确名称）或 grep
查找精确的错误消息、日志字符串或正则表达式模式	grep / ripgrep
查看文件导入了什么，或有哪些内容依赖它	codebase_graph_query
获取架构概览（文件、边、连接最多的节点）	codebase_graph_stats
查找循环依赖	codebase_graph_circular
可视化模块结构（文本 / Mermaid）	codebase_graph_visualize
用户要求提供可视化 / 交互式 / 可分享的图	codebase_graph_visualize mode="interactive"
检查图的构建状态	codebase_graph_status
确认索引是否为最新	codebase_status
发现可用的架构、规范和配置	codebase_context
查找数据库表、API 端点和基础设施配置	codebase_context_search
快速了解所有工具	codebase_about

如需了解每个工具的完整参数详情，请参阅 references/tool-reference.md。