Socraticode

Name: Socraticode
Author: giancarloerra

本地服务

github.com/giancarloerra记忆与知识3.4k5 天前更新

代码仓库

关于 Socraticode

SocratiCode 是面向 AI 助手的开源代码库上下文引擎，通过 MCP 为大型代码库提供语义搜索、依赖图和影响分析。项目主打零配置、本地运行，默认使用 Docker 部署，无需 API 密钥。

主要功能

01混合语义搜索与 BM25 代码检索
02多语言代码依赖图与循环依赖可视化
03符号级影响分析与调用流追踪
04数据库、API 与基础设施产物的可搜索索引
05文件变更自动监听与可续传的索引

适用场景

01为 AI 助手快速理解数百万行级代码库
02分析修改某个符号时的影响范围
03检索数据库结构、API 规范等上下文文档

MCP 相关

SocratiCode 是一个 MCP 服务，向支持本地 stdio 服务的 MCP 客户端暴露代码搜索、依赖图和索引管理等工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "socraticode": {
      "command": "npx",
      "args": [
        "-y",
        "socraticode"
      ],
      "env": {
        "EMBEDDING_PROVIDER": "<EMBEDDING_PROVIDER>",
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "GOOGLE_API_KEY": "<GOOGLE_API_KEY>",
        "OLLAMA_URL": "<OLLAMA_URL>",
        "EMBEDDING_MODEL": "<EMBEDDING_MODEL>",
        "EMBEDDING_DIMENSIONS": "<EMBEDDING_DIMENSIONS>",
        "OLLAMA_MODE": "<OLLAMA_MODE>",
        "OLLAMA_API_KEY": "<OLLAMA_API_KEY>",
        "LMSTUDIO_URL": "<LMSTUDIO_URL>",
        "LMSTUDIO_API_KEY": "<LMSTUDIO_API_KEY>",
        "LMSTUDIO_ALLOW_MISSING_MODEL_LISTING": "<LMSTUDIO_ALLOW_MISSING_MODEL_LISTING>",
        "LITELLM_URL": "<LITELLM_URL>",
        "LITELLM_API_KEY": "<LITELLM_API_KEY>",
        "LITELLM_SEND_DIMENSIONS": "<LITELLM_SEND_DIMENSIONS>",
        "QDRANT_MODE": "<QDRANT_MODE>",
        "QDRANT_URL": "<QDRANT_URL>",
        "QDRANT_API_KEY": "<QDRANT_API_KEY>"
      }
    }
  }
}

启动命令npx -y socraticode

需要配置的环境变量

EMBEDDING_PROVIDEREmbedding provider to use: ollama (default), openai, google, lmstudio, or litellm

OPENAI_API_KEY密钥API key for OpenAI embeddings (required only when EMBEDDING_PROVIDER=openai)

GOOGLE_API_KEY密钥API key for Google embeddings (required only when EMBEDDING_PROVIDER=google)

OLLAMA_URLURL of the Ollama server (default: auto-detected; Docker-managed or http://localhost:11434)

EMBEDDING_MODELEmbedding model name (defaults per provider; required for lmstudio and litellm)

EMBEDDING_DIMENSIONSEmbedding vector dimensions (defaults per provider; required for lmstudio and litellm)

OLLAMA_MODEOllama mode: auto (default), docker, or external

OLLAMA_API_KEY密钥Optional API key for authenticated Ollama proxies

LMSTUDIO_URLLM Studio OpenAI-compatible base URL (default: http://localhost:1234/v1)

LMSTUDIO_API_KEY密钥Optional API key when LM Studio authentication is enabled

LMSTUDIO_ALLOW_MISSING_MODEL_LISTINGAllow compatible embedding servers without a models endpoint to be probed directly

LITELLM_URLLiteLLM OpenAI-compatible base URL (default: http://localhost:4000/v1)

LITELLM_API_KEY密钥LiteLLM master or virtual API key (required when EMBEDDING_PROVIDER=litellm)

LITELLM_SEND_DIMENSIONSForward the dimensions parameter through LiteLLM when explicitly enabled

QDRANT_MODEQdrant mode: managed (default, Docker-managed) or external (user-provided instance)

QDRANT_URLFull URL for remote/cloud Qdrant (e.g. https://xyz.cloud.qdrant.io:6333). Only needed when QDRANT_MODE=external

QDRANT_API_KEY密钥API key for remote Qdrant instance. Only needed when QDRANT_MODE=external

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmsocraticode1.16.1stdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
projectPath	string	否	项目目录的绝对路径。省略时使用当前工作目录。
extraExtensions	string	否	要建立索引的额外文件扩展名列表，以逗号分隔，范围超出内置集合（例如：'.tpl,.blade,.hbs'）。适用于使用非标准文件扩展名的项目。也可通过 EXTRA_EXTENSIONS 环境变量全局设置。

详细介绍

SocratiCode 徽标

SocratiCode

“只有一种善，那就是知识；只有一种恶，那就是无知。” —— 苏格拉底

你的 AI 会读取代码。SocratiCode 能理解代码。

开源代码库上下文引擎：让任何 AI 即刻自动掌握整个代码库（及基础设施）的知识——可扩展、零配置、完全私密，而且完全免费。

感谢 Altaire Limited 慷慨赞助

🛡️ 需要同时实现 MCP 治理和代码库上下文吗？ 请参阅我们的姊妹项目 JanuScope——本地优先的 MCP 策略代理：工具拦截、SQL 修改门控、PII 脱敏、审计、速率限制。

如果 SocratiCode 对你有帮助，请 ⭐ 为此仓库点星——这有助于其他人发现它——并分享给你的开发团队和其他开发者！

💬 有问题或只是想聊聊？欢迎加入我们的 Discord。 ☁️ SocratiCode Cloud（私人测试版） — 托管式共享团队索引，采用与开源版本相同的引擎，并提供 SSO、审计日志、支持分支的索引，以及 VPC / 隔离网络部署选项。开源核心永久免费。申请提前体验 →

专注做好一件事：无需设置、没有臃肿功能、全自动运行的深度代码库智能。 SocratiCode 让 AI 助手深入理解你的代码库：混合搜索、跨项目搜索、多语言代码依赖图、符号级影响分析与调用流程、用于可视化导航的交互式 HTML 图谱浏览器，以及可搜索的上下文资料（数据库架构、API 规范、基础设施配置、架构文档）。无需配置：将它添加到支持本地 stdio 服务的 MCP 宿主，或使用受支持的插件或扩展。所有工作均由它自动处理。

已可用于生产环境，并经过企业级大型代码仓库的实战检验（多达并超过约 4,000 万行代码）。分批自动索引并可恢复，会记录进度——暂停、崩溃、重启和中断都不会导致工作丢失。文件监视器会在每次文件更改时以及跨会话自动更新索引。支持多分支、多仓库和多 Agent — 多个 AI Agent 可以同时处理同一代码库，共享单个索引，自动协调且无需配置。

默认私密且本地运行 — 所有工作均由 Docker 处理，无需 API 密钥，数据不会离开你的设备。需要时，还可使用面向嵌入的云服务（OpenAI、Google Gemini）和 Qdrant，以及完整的配置选项套件。

属于你的代码智能，不受 AI 和宿主限制 — 代码库的理解能力与代码本身共存，不会被锁定在某个助手、IDE 或模型中。由于 SocratiCode 会预先计算复杂部分（影响范围、调用流程、依赖遍历），较小的模型也能处理原本需要顶级推理能力的架构复杂任务，进一步节省 token 成本。

首个基于 Qdrant 的 MCP/Claude 插件/技能，将自动管理、零配置的本地 Docker 部署与支持 AST 的代码分块、混合语义 + BM25（RRF 融合）代码搜索、带循环依赖可视化的多语言依赖图谱、符号级影响分析（跨 18 种语言追踪影响范围和调用流程），以及可搜索的基础设施/API/数据库资料相结合，打造专注、零配置且易于使用的代码智能引擎。

在 VS Code（245 万行代码）上进行的基准测试： 与基于 grep 的探索相比，SocratiCode 减少 61% 的上下文用量、减少 84% 的工具调用，并且快 37 倍 — 使用 Claude Opus 4.6 进行实时测试。查看完整基准测试 →

快速开始

**要求：**安装 Node.js 18.17 或更高版本，并确保 npx 位于 PATH 中；此外，Docker 需处于运行状态，以启动默认的本地 Qdrant 和 Ollama 堆栈。

如需了解每种主机推荐的一种设置方式，以及简短实用的场景，请参阅快速指南。本 README 介绍其他安装方式和完整配置。

Claude Code、VS Code 和 Cursor 的快速安装指引：

使用 JSON mcpServers 对象的 MCP 主机可使用以下完整配置：

{
  "mcpServers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"]
    }
  }
}

配置架构因主机而异。Continue、VS Code、Zed、OpenCode、Gemini CLI 和 Cline 的专用示例，请参阅插件和主机集成。

让 SocratiCode 保持最新

SocratiCode 有两条独立的更新路径。MCP 引擎是发布到 npm 的 socraticode 软件包。以下每种基于 npm 的配置都会使用 npx -y --prefer-online socraticode@latest，在每次 MCP 服务启动时检查 npm 上的最新 latest 版本。运行中的服务无法替换自身；只有在 npm 注册表可访问时，才能下载新发布的版本，因此版本发布后，请重启或重新连接服务。

原生插件和扩展还包含技能、指令、清单或 UI 文件。请按照下文说明通过相应主机更新这些文件，然后启动新会话，以加载新版插件文件。直接安装 MCP 只包含引擎，不会安装 SocratiCode 的插件技能。

集成	更新插件、技能和集成文件
Claude Code 插件	启用市场自动更新，或运行 `claude plugin marketplace update socraticode`，然后运行 `claude plugin update --scope user socraticode@socraticode`
OpenAI Codex 插件	运行 `codex plugin marketplace upgrade socraticode`，然后运行 `codex plugin add socraticode@socraticode` 并启动新任务
VS Code Agent 插件	保持 `extensions.autoUpdate` 启用以每日检查，或运行扩展：检查扩展更新，然后开始新的聊天
VS Code 编辑器扩展	通过“扩展”视图或扩展：检查扩展更新进行更新，然后重新加载窗口
Cursor 本地插件	按照 Cursor 部分中的命令更新到最新的 GitHub 发布标签，然后重新加载 Cursor
Gemini CLI 直接 MCP	重启 Gemini，以重新连接服务并获取当前 npm 版本
仅直接 MCP	未安装单独的插件文件；重启或重新连接 MCP 服务以获取当前 npm 版本
`@latest` 指 npm 发布的 `latest` 分发标签；它不是 Git 分支。`--prefer-online` 会强制 npm 检查是否有更新的包元数据，即使缓存仍然有效。如果同一注册表暂时不可用，npm 仍可使用已填充的缓存；首次安装仍需要访问注册表。请参阅 npm exec 缓存文档和 npm 分发标签文档。

重启宿主。在默认本地配置下，首次使用时会拉取所需的 Docker 镜像并启动受管理的 Qdrant。OLLAMA_MODE=auto 会复用检测到的原生 Ollama 实例，或启动受管理的 Ollama，然后下载本地嵌入模型（如果尚未下载）。云端和外部嵌入服务提供商不会下载本地模型。初始设置通常需要约五分钟，具体取决于网络连接；之后启动只需几秒。

首次在某个项目中使用： 请 AI 执行：“索引此代码库”。索引会在后台运行；可以询问 “代码库索引状态如何？” 来查看进度。首次索引所需时间可能从几秒到几分钟不等，具体取决于代码库大小，以及你使用的是 GPU 加速的 Ollama 还是云端嵌入服务（在 Macbook Pro M4 上，首次索引 300 多万行代码不到 10 分钟）。完成后无需再次运行，你可以搜索、探索依赖关系图并查询上下文制品。

此后每次使用： 直接使用工具（搜索、图谱等）。默认情况下，服务启动时会恢复由 MCP 进程工作目录表示的已索引项目：完整索引会启动文件监视器并进行一次增量追赶更新，中断的索引则会从上一个检查点恢复。SOCRATICODE_AUTO_RESUME_PROJECTS 和 SOCRATICODE_AUTO_RESUME=all 可用于选择其他项目。启动时未处理的已完成索引项目，会在首次搜索、状态查询或图谱交互时启动备用文件监视器。你也可以通过 codebase_watch { action: "start" } 显式启动或重启文件监视器。

更倾向于使用有意控制的索引快照？ 对每个使用此代码库的 MCP 进程设置 SOCRATICODE_WATCHER=off 和 SOCRATICODE_AUTO_RESUME=off，然后仅在需要刷新时运行 codebase_update。现有索引无需重建即可继续使用。如果仍希望可以通过显式执行 codebase_watch { action: "start" } 来启动文件监视器，请改用 SOCRATICODE_WATCHER=manual。请参阅索引行为和按宿主传递环境变量。

更倾向于在 Git 状态切换时更新？ 设置 SOCRATICODE_WATCHER=git。已激活的索引代码库会在检出的引用或 HEAD 发生变化时刷新，无需使用原生文件监视器。请参阅 Git 触发的刷新。

macOS / Windows 上的大型代码库：Docker 容器无法使用 GPU。对于中大型代码仓库，请安装原生 Ollama（会自动检测，无需更改配置）以使用 Metal/CUDA 加速，或使用 OpenAI embeddings，无需本地安装即可获得更快速度。查看完整详情。

推荐：为获得最佳效果，请将 Agent Instructions 添加到 AI 助手的系统提示词或项目说明文件（CLAUDE.md、AGENTS.md 等）中。关键原则是先搜索，再阅读，这有助于 AI 有效使用 SocratiCode 的工具，避免不必要地读取文件。

Claude Code 用户：如果你安装了 SocratiCode 插件，Agent Instructions 会自动作为技能提供，因此无需将其添加到 CLAUDE.md 中。插件也会捆绑 MCP 服务，因此无需单独运行 claude mcp add。

高级选项：云端 embeddings（OpenAI / Google）、外部 Qdrant、远程 Ollama、原生 Ollama，以及数十种调优选项均可使用。请参阅下方的配置。

插件和宿主集成

SocratiCode 可以作为原生 Agent 插件、VS Code 编辑器扩展，或直接配置的本地 stdio MCP 服务进行安装。这些属于不同的集成类型，配置和更新方式也各不相同。

SocratiCode 引擎需要 Node.js 18.17 或更高版本，并且 npx 必须位于 PATH 中；部分宿主需要更新版本的 Node.js。默认本地技术栈还要求 Docker 正在运行。如果使用外部 Qdrant，且 embeddings 使用已检测到的原生 Ollama 实例、云端提供方或外部提供方，则无需 Docker。

宿主	推荐集成方式	范围
Claude Code	原生插件	用户
OpenAI Codex	原生插件	用户
VS Code	Agent Plugin 或编辑器扩展	当前 VS Code 配置文件
Cursor	本地 Cursor 插件或直接配置 MCP	用户或项目
Gemini CLI	直接配置 MCP	用户
Continue	直接配置 MCP	项目或用户配置
Cline	直接配置 MCP	项目或用户配置
Zed	直接配置 MCP	用户或项目设置
OpenCode	直接配置 MCP	项目或用户配置

Claude Code 插件（推荐 Claude Code 用户使用）

原生插件捆绑了 MCP 服务、工作流技能和 Agent 指令。为当前用户安装：

claude plugin marketplace add giancarloerra/socraticode
claude plugin install --scope user socraticode@socraticode
claude plugin list

安装后，请启动新的 Claude Code 会话。现有会话不会加载新安装的插件。要启用自动更新，请打开 /plugin，选择 Marketplaces，选择 socraticode，并启用自动更新。要手动更新：

claude plugin marketplace update socraticode
claude plugin update --scope user socraticode@socraticode

更新后运行 /reload-plugins 或启动新会话。如果之前已将 SocratiCode 作为独立 MCP 服务添加，请使用 claude mcp remove socraticode 移除此重复项；插件已包含该服务。

若要使用自定义提供方或外部 Qdrant，请将继承的变量放入 Claude Code 的用户设置中，并重启会话：

{
  "env": {
    "EMBEDDING_PROVIDER": "openai",
    "OPENAI_API_KEY": "<your key>"
  }
}

请妥善保管此用户级文件，或通过进程环境提供密钥。切勿提交密钥值。

固定引擎版本

默认情况下，插件会启动 npx -y --prefer-online socraticode@latest，每次服务器启动时都会检查 npm 上的最新版本。每次启动都会独立解析版本，因此同一主机上不同时间启动的两个服务器可能运行不同版本。

SOCRATICODE_SPEC 用于替换软件包规格。未设置时，它会解析为 socraticode@latest，启动器保持不变，因此现有安装无需重新配置。请在插件服务器继承环境变量的位置进行设置，即 Claude Code 的用户设置中：

{
  "env": {
    "SOCRATICODE_SPEC": "[email protected]"
  }
}

移除该条目即可恢复默认值；空字符串也是一个值，并非未设置，传给 npm 后会被用作规格。

这样，该主机上的每个服务器都会解析到相同的构建版本。仍会联系 npm 获取元数据，因此启动并非完全无开销；但固定版本在首次解析后就会保存在 npx 缓存中，后续每次发布都不会重新下载。固定的引擎不会自动更新——请主动提高版本值以获取新版本。

这仅适用于 Claude Code 插件。Codex 和 Cursor 会读取共享的 .mcp.json，其启动器保持不变；VS Code 扩展则提供等效的 socraticode.command 和 socraticode.args 设置。

参见 Claude Code 插件文档。

Claude Code 仅 MCP 安装

如需安装到用户范围且不包含捆绑技能：

claude mcp add --scope user socraticode -- npx -y --prefer-online socraticode@latest
claude mcp list

启动新会话，或运行 /mcp 并选择 Reconnect。显式指定 @latest 的命令会在每次服务器启动时检查最新发布的引擎。若省略 --scope user，claude mcp add 默认使用项目本地范围。参见 Claude Code MCP 文档。

OpenAI Codex 插件

Codex 插件捆绑了 SocratiCode 的 MCP 服务、技能和说明。添加 Git 市场并为当前用户安装插件：

codex plugin marketplace add giancarloerra/socraticode --ref main
codex plugin add socraticode@socraticode
codex plugin list --available --json

安装后启动新的 Codex 任务或 CLI 会话。重新打开现有任务不会加载新安装的技能或 MCP 工具。使用以下命令更新并验证：

codex plugin marketplace upgrade socraticode
codex plugin add socraticode@socraticode
codex plugin list --available --json

如果 SocratiCode 在 Codex Desktop 中启动失败并显示 No such file or directory，Codex 可能无法找到 npx。运行 command -v npx。某些桌面启动仅使用 /usr/bin:/bin:/usr/sbin:/sbin；如果 npx 安装在其他位置，请在下方的自定义 Codex 配置中将其目录添加到 PATH，然后重启 Codex。

Codex 有公开的插件目录，但 SocratiCode 目前尚未发布到其中。ChatGPT 桌面版 Codex 环境和 Codex CLI 支持插件。Codex IDE 扩展支持共享 MCP 配置，但不支持发现插件。参见 OpenAI 插件文档。

Codex 目前支持设置插件捆绑 MCP 服务的启用状态和工具策略，但没有提供针对该捆绑定义的、文档化的逐用户环境变量覆盖方式。若要保留插件技能，同时使用自定义 SocratiCode 变量，请仅禁用捆绑服务，并在 ~/.codex/config.toml 中添加一个顶层服务：

[plugins."socraticode@socraticode".mcp_servers.socraticode]
enabled = false

[mcp_servers.socraticode]
command = "npx"
args = ["-y", "--prefer-online", "socraticode@latest"]

[mcp_servers.socraticode.env]
QDRANT_MODE = "external"
QDRANT_URL = "https://xyz.qdrant.io"

重启 Codex，确认插件技能仍可用，并使用 /mcp 或 codex mcp list 验证恰好有一个 SocratiCode 服务处于活动状态。参见捆绑 MCP 服务策略和 Codex 配置参考。

OpenAI Codex 仅 MCP 安装

codex mcp add 会将用户配置写入 ~/.codex/config.toml：

codex mcp add socraticode -- npx -y --prefer-online socraticode@latest
codex mcp list

安装后启动新的任务或 CLI 会话。等效的 TOML 如下：

[mcp_servers.socraticode]
command = "npx"
args = ["-y", "--prefer-online", "socraticode@latest"]

内联的 env = { ... } 和嵌套的 [mcp_servers.socraticode.env] 表都有效。CLI 的 --env KEY=value 选项通常更清晰。参见 OpenAI Codex MCP 文档。

VS Code Agent 插件

此插件打包了供 VS Code 原生 Agent 使用的 MCP 服务、技能和 Agent 指令。它与 SocratiCode 编辑器扩展相互独立。

安装前，将以下完整设置添加到当前 VS Code 配置文件：
```
{
  "chat.plugins.enabled": true
}
```
在命令面板中运行 Chat: Install Plugin From Source，并输入 https://github.com/giancarloerra/socraticode。
开始新的 Chat 会话。
在 Agent Plugins - Installed 下确认 SocratiCode，然后运行 MCP: List Servers 并确认其服务正在运行。

运行 Extensions: Check for Extension Updates 以刷新已安装的 Agent 插件，然后开始新的 Chat 会话。请参阅 VS Code Agent Plugins。

VS Code 未提供插件内置 MCP 定义的按用户环境覆盖配置。若要保留插件技能并应用自定义变量，请运行 MCP: List Servers，禁用内置的 SocratiCode 服务，然后通过 MCP: Open User Configuration 添加以下用户范围的直接服务：

{
  "servers": {
    "socraticode-configured": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"],
      "env": {
        "QDRANT_MODE": "external",
        "QDRANT_URL": "https://xyz.qdrant.io"
      }
    }
  }
}

开始新的 Chat 会话，并使用 MCP: List Servers 确认只有 socraticode-configured 处于活动状态。如果变量应从单独的本地文件读取，请使用 envFile 而不是 env。服务启用状态与共享插件定义分开存储。请参阅 VS Code MCP server management 和 env / envFile reference。

VS Code 编辑器扩展

单独发布的编辑器扩展提供 SocratiCode 侧边栏、状态项、命令、导览和交互式图谱 Webview。在当前 VS Code 配置文件中，通过 Visual Studio Marketplace 安装 SocratiCode。

在 Microsoft VS Code 1.99+ 及实现 VS Code MCP 提供程序 API 的兼容编辑器中，该扩展会将 SocratiCode 注册到编辑器的原生 MCP 注册表。它不会配置 Cline 或 Continue 等独立客户端。

启用 VS Code 的 AI 功能，并登录 GitHub Copilot，以使用原生 Agent Chat。在 VS Code 1.122+ 中，无需登录 GitHub，也可以使用支持工具调用的 BYOK 模型。安装后重新加载窗口并开始新的 Chat 会话。运行 MCP: List Servers 确认 SocratiCode 正在运行，并打开 SocratiCode 侧边栏以确认编辑器 UI。通过“扩展”视图或 Extensions: Check for Extension Updates 更新扩展。

Open VSX 包可安装在基于 VS Code 的编辑器中，但原生 MCP 注册要求该编辑器实现 vscode.lm.registerMcpServerDefinitionProvider。请参阅 VS Code MCP extension API。

VS Code 直接安装 MCP

使用上方的 Stable 或 Insiders 徽章，在 VS Code 中选择用户或工作区范围，然后开始新的 Chat 会话。项目范围的 .vscode/mcp.json 使用以下完整对象：

{
  "servers": {
    "socraticode": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"]
    }
  }
}

使用 MCP: List Servers 进行验证。通过该命令重启服务，并在发布新版本后开始新的 Chat 会话。

Cursor

该仓库包含一个 Cursor 格式的插件，其中包含 MCP 服务、技能和说明。SocratiCode 目前尚未发布到 Cursor Marketplace，因此请使用 Cursor 文档中说明的用户级本地插件目录。克隆仓库，然后检出最新 SocratiCode 版本页面上显示的稳定版本：

mkdir -p ~/.cursor/plugins/local
git clone https://github.com/giancarloerra/socraticode.git ~/.cursor/plugins/local/socraticode
git -C ~/.cursor/plugins/local/socraticode checkout <latest-release-tag>

将 <latest-release-tag> 替换为该页面上显示的版本标签，例如 vX.Y.Z。重启 Cursor，或运行 Developer: Reload Window，然后在 Customize 中确认插件。若要更新到之后发布的版本：

git -C ~/.cursor/plugins/local/socraticode fetch --tags
git -C ~/.cursor/plugins/local/socraticode checkout <latest-release-tag>

更新后重新加载 Cursor。这些命令有意使用版本标签，而不是 main 上尚未发布的提交。参见 Cursor 插件。

若要直接配置 MCP，请使用上方的 Cursor 徽章，并在 Cursor 中选择预期的用户级或项目级范围。启动新的 Agent 聊天，然后在 Customize → MCPs 下确认 socraticode。安装链接已使用最新版本的引擎命令。参见 Cursor MCP 安装链接。

当前的本地插件未声明可由用户配置的变量。若要保留其技能并应用自定义变量，请打开 Customize，禁用插件提供的 SocratiCode MCP 服务，然后在用户级或项目级 mcp.json 中添加一个直接配置的服务：

{
  "mcpServers": {
    "socraticode-configured": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"],
      "env": {
        "QDRANT_MODE": "external",
        "QDRANT_URL": "https://xyz.qdrant.io"
      }
    }
  }
}

重新加载 Cursor，并在 Customize 下确认只有 socraticode-configured 处于启用状态。参见 Cursor 插件变量和 MCP 服务管理。

Open VSX 上的 SocratiCode 软件包是 VS Code 风格的编辑器扩展，不是 Cursor 插件。安装该扩展并不能证明 Cursor 实现了 VS Code 原生 MCP 提供程序 API。如果需要使用 MCP，请采用本地插件或直接 MCP 配置方式。

Gemini CLI

添加用户级 MCP 服务并确认其配置，然后重启所有正在运行的 Gemini CLI 会话：

gemini mcp add --scope user socraticode npx -y --prefer-online socraticode@latest
gemini mcp list

如需高级配置，请在用户级范围（~/.gemini/settings.json）中编辑服务，或在工作区级范围（.gemini/settings.json）中定义服务，并显式转发 env 中列出的变量：

{
  "mcpServers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"],
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "QDRANT_MODE": "external",
        "QDRANT_URL": "${QDRANT_URL}",
        "QDRANT_API_KEY": "${QDRANT_API_KEY}"
      }
    }
  }
}

请将密钥值保存在进程环境中，而不要提交到仓库。重启 Gemini，然后运行 gemini mcp list，确认服务配置无误。参见 Gemini MCP 配置。

Continue

Continue 使用 YAML mcpServers 列表。若要配置项目级范围，请创建 .continue/mcpServers/socraticode.yaml：

name: SocratiCode MCP
version: 1.0.0
schema: v1
mcpServers:
  - name: SocratiCode
    type: stdio
    command: npx
    args:
      - "-y"
      - "--prefer-online"
      - socraticode@latest

Continue 会自动刷新已保存的配置。打开新的 Continue Agent 会话，并确认列表中显示 SocratiCode 工具。若要配置用户级范围，请将相同的 mcpServers 列表添加到 ~/.continue/config.yaml。Continue 也可以导入放置在 .continue/mcpServers/ 中的完整 JSON MCP 文件。参见 Continue MCP 配置和 Continue YAML 参考。

Cline

若要配置项目级范围，请将此完整对象保存为 .cline/mcp.json。若要配置用户级范围，请通过 Cline 的 MCP 设置界面，将相同的服务添加到 ~/.cline/data/settings/cline_mcp_settings.json 中：

{
  "mcpServers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

启动新的 Cline 任务，并在 MCP Servers 视图中确认 socraticode 及其工具已显示。发布新版本后，重新连接该服务。参见 Cline MCP 文档。

Zed

打开 Settings → AI → MCP Servers → Add Server → Add Local Server。界面会写入用户级设置。请使用以下完整的服务定义，可在此处添加，也可添加到项目级 .zed/settings.json 中：

{
  "context_servers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"],
      "env": {}
    }
  }
}

确认 SocratiCode 旁边的指示灯为绿色，且其工具提示显示 Server is active，然后开始新的 Agent 对话。发布新版本后，请从 MCP Servers 页面重启服务。

Zed 使用 ~/.config/zed/AGENTS.md 保存个人指令。对于项目指令，它会使用第一个匹配的受支持文件，可以是 AGENTS.md、CLAUDE.md、GEMINI.md 或其他受支持的兼容文件。Zed Rules 已由 Skills 和 Instructions 取代。请参阅 Zed MCP servers 和 Zed Instructions。

OpenCode

项目级配置请使用项目根目录下的 opencode.json 或 opencode.jsonc。用户级配置请使用 ~/.config/opencode/opencode.json 或 opencode.jsonc：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "socraticode": {
      "type": "local",
      "command": ["npx", "-y", "--prefer-online", "socraticode@latest"],
      "enabled": true
    }
  }
}

重启 OpenCode，并通过 opencode mcp list 确认服务。发布新版本后，请重启 OpenCode，以便 npm 检查当前引擎。这是 OpenCode 1.x 的架构。

OpenCode V2 将服务名称嵌套在 mcp.servers 下，并使用 disabled 代替 enabled；其本地服务定义其余部分相同：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "socraticode": {
        "type": "local",
        "command": ["npx", "-y", "--prefer-online", "socraticode@latest"],
        "disabled": false,
        "environment": {}
      }
    }
  }
}

请参阅 OpenCode 1.x MCP servers、OpenCode V2 MCP servers 和 OpenCode configuration。

其他本地 stdio MCP 宿主

Quick Start 中的完整 JSON 对象仅适用于文档指定使用 mcpServers 对象的宿主。请在该宿主文档指定的用户级或项目级位置添加该对象，然后重启 MCP 服务或开始新会话，并在宿主的 MCP 服务和工具列表中确认 SocratiCode。该示例会在每次服务启动时检查是否有最新发布的引擎。仅支持远程 HTTP MCP 服务的宿主无法直接启动 SocratiCode。

为什么选择 SocratiCode

我开发 SocratiCode，是因为我经常需要处理使用不同语言编写的现有大型复杂代码库，并快速理解和操作它们。现有解决方案要么功能过于有限，要么未经充分测试，不适合用于生产环境，要么因为不必要的复杂性而显得臃肿。我希望打造一款专注的工具，能够出色地深入分析代码库——无需设置、没有冗余、全自动，并且不会碍事。

内置代码搜索与 SocratiCode 对比

功能	Claude Code	Cursor	VS Code Copilot	+ SocratiCode
文本 / grep 搜索	✅	✅	✅	✅
语义搜索	—	✅	✅¹	✅
混合搜索（融合）	—	—	—	✅
代码依赖关系图	—	—	✅²	✅
符号级影响分析 / 影响范围	—	—	—	✅
调用流程追踪（入口点 → 被调用方）	—	—	—	✅
交互式可视化关系图浏览器	—	—	—	✅
循环依赖检测	—	—	—	✅
非代码知识（架构、API 规范）	—	—	—	✅
跨项目搜索	—	—	—	✅
感知分支的索引	—	—	—	✅
多 Agent 共享索引	—	—	—	✅
与工具无关（切换 AI 后仍可使用）	—	—	—	✅
完全本地 / 私密	✅	—³	—⁴	✅
可续传的索引	—	—	—	✅
实时文件监视	—	✅	—	✅

_{¹ VS Code Copilot：通过 GitHub / Azure DevOps 使用远程索引；本地“External Ingest”正在逐步推出。 ² 基于 LSP 的“查找引用” / “转到定义”（Usages 工具），并非完整的依赖关系图。 ³ Cursor：在 Cursor 服务器上处理嵌入数据（传输中和静态数据均已加密）。 ⁴ VS Code Copilot：远程索引托管在 GitHub / Azure DevOps 上。来源：Cursor 文档、Claude Code 文档、VS Code Copilot 文档。}

🔌 上下文属于你的代码库，而非助手。 内置索引（Cursor 的、Copilot 的）都绑定到各自的工具上——切换助手就得从头开始。SocratiCode 独立于工具：只需索引一次，即可将其接入 Claude Code、Cursor、Copilot、Windsurf、你自己的私有模型，或同时接入所有这些工具。它们共享对代码的相同理解。

在 VS Code 的 245 万行代码库上，与基于 grep 的 AI Agent 相比，SocratiCode 回答架构问题所需的数据减少 61%、步骤减少 84%，响应速度快 37 倍。完整基准测试 →

功能

混合式代码搜索 — 基于 Qdrant 构建。Qdrant 是专为此用途打造的向量数据库，支持 HNSW 索引、并发读写和负载过滤。每个代码块同时存储一个稠密向量和一个 BM25 稀疏向量；Query API 在一次往返请求中运行两个子查询，并使用 Reciprocal Rank Fusion（RRF）融合结果。即使代码中没有出现“authentication middleware”这样的原词，语义搜索也能处理这类概念性查询。BM25 则负责精确标识符和关键词查找。每次查询都能兼得两者优势，无需调整参数。
可配置的 Qdrant — 使用内置的 Docker Qdrant（默认，无需配置），也可以连接到自己的实例（可自托管、远程服务或 Qdrant Cloud）。通过 QDRANT_MODE、QDRANT_URL 和 QDRANT_API_KEY 环境变量进行配置。
可配置的 Ollama — 使用内置的 Docker Ollama（默认，无需配置），也可以指定自己的 Ollama 实例（原生安装，可访问 GPU、远程服务等）。通过 OLLAMA_MODE、OLLAMA_URL、EMBEDDING_MODEL 和 EMBEDDING_DIMENSIONS 环境变量进行配置。
多提供商嵌入 — 只需设置一个环境变量，即可在 Local Ollama（私有，可访问 GPU）、Docker Ollama（零配置）、OpenAI（text-embedding-3-small，速度最快）、Google Gemini（gemini-embedding-001，免费套餐）、LM Studio（本地兼容 OpenAI 的服务）或 LiteLLM（位于 100 多家提供商之前的代理网关）之间切换。无需针对不同提供商使用专门的配置文件。
私密且安全 — 所有操作都在你的机器上运行，代码绝不会离开你的网络。默认的 Docker 设置包含 Ollama（嵌入）和 Qdrant（向量存储），不会调用外部 API。无需支付 API 费用，也没有令牌限制。适用于隔离网络和本地部署环境。可选的云服务提供商（OpenAI、Google Gemini、Qdrant Cloud）可供使用，但并非必需。
感知 AST 的代码块切分 — 使用 AST 解析（ast-grep）在函数／类边界处分割文件，而不是按任意行数切分，从而获得更高质量的搜索结果。对于不支持的语言，则回退到按行切分。
多语言代码依赖图 — 使用 ast-grep 对 19 种以上语言的 import／require／use／include 语句进行静态分析。无需 dependency-cruiser 等外部工具。可检测循环依赖并生成可视化 Mermaid 图表。
广泛的语言支持 — 开箱即用，支持所有受支持的文件类型。完全支持的语言会附带其语法。GDScript 在兼容时使用可选的原生解析器，否则使用感知语法的回退方案。对于非标准扩展名，可配置 EXTRA_EXTENSIONS。只要 AI 能读取，SocratiCode 就能为其建立索引。
增量索引 — 首次完成完整索引后，只会重新处理已更改的文件。内容哈希会保存在 Qdrant 中，因此服务器重启后状态仍会保留。
分批且可恢复的索引 — 文件以每批 50 个的方式处理，每批完成后都会将进度检查点保存到 Qdrant。如果进程崩溃或被中断，下次运行时会自动从上次中断处继续，并通过哈希比较跳过已建立索引的文件。这样可将峰值内存占用保持在较低水平，即使面对超大型代码库也能可靠地建立索引。
实时文件监控 — 可选择监控文件变更并实时更新索引（防抖 2 秒）。监控器也会使代码图缓存失效。
并行处理 — 文件会以每批 50 个的方式并行扫描和切分，以加快 I/O；嵌入生成和数据写入则分别分批处理，以实现最佳吞吐量。
多项目 — 可同时为多个项目建立索引。每个项目都有独立的集合，并会完整跟踪项目路径。
跨项目搜索 — 可在一次查询中搜索多个相关项目。通过 .socraticode.json 或 SOCRATICODE_LINKED_PROJECTS 环境变量关联项目，然后在 codebase_search 中设置 includeLinked: true。结果会标注项目标签，并按余弦相似度排序；不同规模项目之间的余弦相似度具有可比性（如果某个结果没有余弦相似度，则回退到排名融合）。
感知分支的索引 — 设置 SOCRATICODE_BRANCH_AWARE=true，即可为每个 git 分支维护独立索引。每个分支都有自己的 Qdrant 集合，因此切换分支时会立即切换到对应的索引。非常适合 CI/CD 流水线和 PR 审查工作流。需要使用基于路径的项目 ID：显式 ID（SOCRATICODE_PROJECT_ID 或 .socraticode.json 中的 projectId）会被视为稳定标识，绝不会添加后缀，因此此模式不适用于这些项目。
遵循忽略规则 — 遵循所有 .gitignore 文件（根目录及嵌套目录），并支持使用可选的 .socraticodeignore 添加排除项。内置了合理的默认规则。可通过 RESPECT_GITIGNORE=false 禁用 .gitignore 处理。可通过 INCLUDE_DOT_FILES=true 纳入点目录（例如 .agent）。
自定义文件扩展名 — 可通过 EXTRA_EXTENSIONS 环境变量或 extraExtensions 工具参数，纳入使用非标准扩展名（例如 .tpl、.blade）的项目文件。此类文件会作为纯文本建立索引，并在代码图中显示为叶节点（不进行 AST 切分或符号分析）。若要将自定义扩展名作为真实语言处理（完整 AST 切分、符号和调用图），请使用 EXTENSION_LANGUAGE_MAP 映射扩展名（例如 .inc:php）。
可配置的基础设施 — 所有端口、主机和 API 密钥均可通过环境变量配置。支持在企业部署中使用 Qdrant API 密钥。
适用于企业的简洁性 — 无需调整 Agent 协调参数，无需设置内存限制环境变量，也无需配置协调器／指挥器容量参数或背压。SocratiCode 依靠生产级基础设施（Qdrant、经过验证的嵌入 API）而非复杂的进程内编排来实现扩展。
自动设置与零配置 — 只需安装 Claude Plugin／Skill，或将 MCP 服务添加到 AI 主机配置中。首次使用时，服务会自动检查 Docker、拉取镜像、启动 Qdrant 和 Ollama 容器，并下载嵌入模型。无需配置文件、YAML、环境变量或原生编译。若没有兼容的原生版本，可选的 GDScript 解析器会安全地回退。只要 Docker 能运行，就能使用。
会话恢复 — 默认情况下，服务器启动时会恢复与 MCP 进程工作目录相对应的已建立索引项目。完整索引会启动监控器并进行增量补齐更新；中断的索引则从上一个检查点继续。显式指定项目列表以及设置 SOCRATICODE_AUTO_RESUME=all，可将此功能扩展到其他已建立索引的项目。
自动启动监控器 — 在默认的 SOCRATICODE_WATCHER=auto 模式下，文件监控器会在启动恢复期间以及 codebase_index 或 codebase_update 之后启动。对于启动时未选中的已完成索引项目，会在首次搜索、状态或图交互时启动备用监控器。manual 模式仅允许通过显式调用 codebase_watch { action: "start" } 启动监控器；off 则会完全禁用监控器启动。
手动索引快照 — 设置 SOCRATICODE_WATCHER=off 和 SOCRATICODE_AUTO_RESUME=off，可防止隐式更新代码索引、生成嵌入以及创建代码图。现有代码索引和代码图仍可读取；如需刷新，请显式调用 codebase_index、codebase_update 或 codebase_graph_build。
由 Git 触发刷新：SOCRATICODE_WATCHER=git 会每 10 秒检查一次活动的已建立索引检出，并在收到搜索、状态和图请求时进行检查。检出的 ref 或 HEAD 发生变化时，会触发现有的增量更新器和代码图同步。原生文件监控会保持禁用状态，包括显式启动监控器的情况。
自动构建代码图 — 建立索引后会自动构建代码依赖图，受监控的文件发生变化时也会重新构建。如果一次更新没有更改用于构建代码图的内容——例如 README、测试样例或迁移文件——则会复用现有代码图，而非重新构建；每次构建都会记录其读取的输入，只有当这些输入全部未发生变化时才会跳过重建。任何与代码图相关的新增内容都会触发重建——包括构建时检查位置出现的新文件，但不包括被忽略规则排除的文件；任何配置变更也会触发重建，若代码图没有此类记录，同样会触发重建。除非要强制重建，否则无需手动调用 codebase_graph_build。
多 Agent 协作 — 多个 AI Agent（各自运行独立的 MCP 实例）可以同时处理同一代码库并共享单个索引。一个 Agent 触发索引，所有 Agent 都能基于同一数据进行搜索。每个项目只运行一个监控器，所有 Agent 都能受益于实时更新。跨进程文件锁会自动协调索引和监控。非常适合一个 Agent 编写测试、另一个修复代码，或规划 Agent 与实现 Agent 并行工作的工作流。
跨进程安全 — 基于文件的锁定（proper-lockfile）可防止多个 MCP 实例同时为同一项目建立索引或进行监控。进程崩溃后遗留的锁会自动回收。当另一个 MCP 进程已在监控项目时，codebase_status 会报告“活动（由另一个进程监控）”，而不是错误地显示“非活动”。
并发保护 — 可防止重复执行索引和代码图构建操作。如果索引已在运行时调用 codebase_index，它会返回当前进度，而不是启动第二个操作。
安全停止 — 可使用 codebase_stop 安全停止长时间运行的索引操作。当前批次会完成并保存检查点，以保留全部进度。重新运行 codebase_index 即可从中断处继续。
显式回收 — codebase_prune 会列出存储中的内容，并且每次只删除一个标识；只有在明确确认后才会应用删除。请参阅回收已存储的标识。
安全关闭 — 服务器关闭时，会为活动的索引操作预留最多 60 秒以完成处理，会妥善停止所有文件监控器，并安全关闭一切内容。
结构化日志 — 所有操作都会记录带结构化上下文的日志，以便进行可观测性监控。可通过 SOCRATICODE_LOG_LEVEL 配置日志级别。
优雅降级 — 监控期间如果基础设施发生故障，监控器会退避并重试，而不是崩溃。

前置条件

依赖项	用途	安装
Docker	运行 Qdrant（向量数据库），并默认运行 Ollama（嵌入）	docker.com
`PATH` 中的 Node.js 18.17+ 和 `npx`	运行 MCP 服务	nodejs.org

在默认的 managed 模式下使用此服务时，Docker 必须处于运行中。

Qdrant 容器会自动管理。如果设置 QDRANT_MODE=external 并将 QDRANT_URL 指向远程或云端 Qdrant 实例，那么此时 Docker 仅用于 Ollama（嵌入）。

在默认的 auto 模式下，Ollama 容器（嵌入）也会自动管理。SocratiCode 会先检查 Ollama 是否已在本机运行——如果是，就会使用它；否则会为你管理一个 Docker 容器。首次下载 Docker 镜像或嵌入模型可能需要几分钟，具体取决于网速，且只需在首次启动时进行。

macOS / Windows 上的嵌入性能

macOS 和 Windows 上的 Docker 容器无法访问 GPU（不支持 Metal 或 CUDA 直通）。对于小型项目，这没有问题；但对于中大型代码库，仅使用 CPU 的容器会明显较慢。

为获得最佳性能，请安装本机版 Ollama： 从 ollama.com/download 下载并运行安装程序。Ollama 运行后，SocratiCode 会自动检测并使用它——无需额外配置（如果尚未下载嵌入模型，首次下载可能需要几分钟）。这样即可在 macOS 上使用 Metal GPU 加速，并在 Windows/Linux 上使用 CUDA。

如果你希望获得更快速度但不想本地安装，请参阅下文的 OpenAI Embeddings 和 Google Generative AI Embeddings，了解基于云的选项。OpenAI 速度很快，且无需本地设置。Google 的免费套餐可用，但有速率限制。配置详情请参阅环境变量。

示例工作流

所有工具的 projectPath 默认指向当前工作目录，因此你无需为当前项目指定路径。

User: "Index this project"
→ codebase_index {}
  ⚡ Indexing started in the background — call codebase_status to check progress
→ codebase_status {}
  ⚠ Full index in progress — Phase: generating embeddings (batch 1/1)
  Progress: 247/1847 chunks embedded (13%) — Elapsed: 12s
→ codebase_status {}
  ✓ Indexing complete: 342 files, 1,847 chunks (took 115.2s)
  File watcher: active (auto-updating on changes)

User: "Search for how authentication is handled"
→ codebase_search { query: "authentication handling" }
  Runs dense semantic search + BM25 keyword search in parallel, fuses results with RRF
  Returns top 10 results ranked by combined relevance

User: "What files depend on the auth middleware?"
→ codebase_graph_query { filePath: "src/middleware/auth.ts" }
  Returns imports and dependents
  (graph was auto-built after indexing — no manual build needed)

User: "Show me the dependency graph"
→ codebase_graph_visualize {}
  Returns a Mermaid diagram colour-coded by language

User: "Are there any circular dependencies?"
→ codebase_graph_circular {}
  Found 2 cycles: src/a.ts → src/b.ts → src/a.ts

User: "What breaks if I rename validateUser?"
→ codebase_impact { target: "validateUser" }
  Blast radius for symbol: validateUser
  Hop 1 (3 files): src/auth/login.ts, src/api/users.ts, tests/auth.test.ts
  Hop 2 (5 files): ...

User: "What does the server entry point actually do?"
→ codebase_flow {}
  Detected 4 entry point(s):
    main (cmd/server.go:10) — well-known-name:main
    healthz (src/api/routes.ts:42) — framework:get
    ...
→ codebase_flow { entrypoint: "main" }
  └── main (cmd/server.go:10)
      ├── loadConfig (cmd/server.go:15)
      └── startServer (src/server.ts:8)
          └── ...

User: "Who calls bcryptCompare and what does it call?"
→ codebase_symbol { name: "bcryptCompare" }
  Symbol: bcryptCompare (function)
  Defined: src/auth/hash.ts:42–58
  Callers (3): ← src/auth/login.ts:12, ← src/auth/reset.ts:30 ...
  Callees (1): → compare [unique, 1 candidate]

Agent 指令

Claude Code 插件用户：这些指令会作为技能自动包含在 SocratiCode 插件中。你无需将它们复制到 CLAUDE.md。以下部分适用于非 Claude Code 宿主（VS Code、Cursor、Claude Desktop 等）。

为获得最佳效果，请将以下指令添加到 AI 助手的项目级指令文件中。核心原则：先搜索，再阅读。索引能在毫秒内为你绘制代码库地图；直接读取原始文件则耗费资源并占用上下文。

这些指令的放置位置（按 IDE 划分）：

IDE / 工具	指令文件
Claude Code	项目根目录中的 `CLAUDE.md`（自动加载）。插件用户会通过技能自动获得这些指令。
Cursor	项目根目录中的 `AGENTS.md`，或用于专用规则文件的 `.cursor/rules/socraticode.mdc`
VS Code Copilot	`.github/copilot-instructions.md`，或 VS Code 用户提示文件夹中的自定义指令文件
Zed	项目根目录中的 `AGENTS.md`，或个人指令文件 `~/.config/zed/AGENTS.md`。Zed 会使用第一个匹配的受支持项目指令文件。
Windsurf	项目根目录中的 `.windsurfrules`
Claude Desktop / Cline	直接添加到系统提示配置中

为何这很重要：仅安装 MCP 服务能让 Agent 使用 SocratiCode 工具，但何时使用这些工具仍由 Agent 决定。将这些指令添加到项目中，可确保 Agent 始终优先使用 SocratiCode 搜索，而不是直接读取原始文件；在需要考虑依赖关系的任务中使用图谱，并遵循先搜索后阅读的工作流。

## Codebase Search (SocratiCode)

This project is indexed with SocratiCode. Always use its MCP tools to explore the codebase
before reading any files directly.

### Workflow

1. **Start most explorations with `codebase_search`.**
   Hybrid semantic + keyword search (vector + BM25, RRF-fused) runs in a single call.
   - Use broad, conceptual queries for orientation: "how is authentication handled",
     "database connection setup", "error handling patterns".
   - Use precise queries for symbol lookups: exact function names, constants, type names.
   - Prefer search results to infer which files to read — do not speculatively open files.
   - **When to use grep instead**: If you already know the exact identifier, error string,
     or regex pattern, grep/ripgrep is faster and more precise — no semantic gap to bridge.
     Use `codebase_search` when you're exploring, asking conceptual questions, or don't
     know which files to look in.

2. **Follow the graph before following imports.**
   Use `codebase_graph_query` to see what a file imports and what depends on it before
   diving into its contents. This prevents unnecessary reading of transitive dependencies.
   - **Before modifying or deleting a file**, check its dependents with `codebase_graph_query`
     to understand the blast radius.
   - **When planning a refactor**, use the graph to identify all affected files before
     making changes.

3. **Use Impact Analysis BEFORE refactoring, renaming, or deleting code.**
   The symbol-level call graph (`codebase_impact`, `codebase_flow`, `codebase_symbol`,
   `codebase_symbols`) goes one step deeper than the file graph: it knows which
   functions and methods call which.
   - `codebase_impact` answers "what breaks if I change X?" (blast radius — every file
     that transitively calls into the target).
   - `codebase_flow` answers "what does this code do?" by tracing forward from an entry
     point. Call with no `entrypoint` to discover candidate entry points (auto-detected
     via orphans, conventional names like `main()`, framework routes, tests).
   - `codebase_symbol` gives a 360° view of one function: definition, callers, callees.
   - `codebase_symbols` lists symbols in a file or searches by name.
   - Always prefer these over reading multiple files when the question is about
     dependencies between functions, not concepts.

4. **Read files only after narrowing down via search.**
   Once search results clearly point to 1–3 files, read only the relevant sections.
   Never read a file just to find out if it's relevant — search first.

5. **Use `codebase_graph_circular` when debugging unexpected behaviour.**
   Circular dependencies cause subtle runtime issues; check for them proactively.
   Also run `codebase_graph_circular` when you notice import-related errors or unexpected
   initialisation order.

6. **Check `codebase_status` if search returns no results.**
   The project may not be indexed yet. Run `codebase_index` if needed, then wait for
   `codebase_status` to confirm completion before searching.

7. **Leverage context artifacts for non-code knowledge.**
   Projects can define a `.socraticodecontextartifacts.json` config to expose database
   schemas, API specs, infrastructure configs, architecture docs, and other project
   knowledge that lives outside source code. These artifacts are auto-indexed alongside
   code during `codebase_index` and `codebase_update`.
   - Run `codebase_context` early to see what artifacts are available.
   - Use `codebase_context_search` to find specific schemas, endpoints, or configs
     before asking about database structure or API contracts.
   - If `codebase_status` shows artifacts are stale, run `codebase_context_index` to
     refresh them.

### When to use each tool

| Goal | Tool |
|------|------|
| Understand what a codebase does / where a feature lives | `codebase_search` (broad query) |
| Find a specific function, constant, or type | `codebase_search` (exact name) or grep if you know already the exact string |
| Find exact error messages, log strings, or regex patterns | grep / ripgrep |
| See what a file imports or what depends on it | `codebase_graph_query` |
| Check blast radius before modifying or deleting a file | `codebase_impact` (symbol-level) or `codebase_graph_query` (file-level) |
| **What breaks if I change function X?** | `codebase_impact target=X` |
| **What does this entry point actually do?** | `codebase_flow entrypoint=X` |
| **List entry points in this codebase** | `codebase_flow` (no args) |
| **Who calls this function and what does it call?** | `codebase_symbol name=X` |
| **What functions/classes exist in this file?** | `codebase_symbols file=path` |
| **Search for symbols by name across the project** | `codebase_symbols query=X` |
| Spot architectural problems | `codebase_graph_circular`, `codebase_graph_stats` |
| Visualise module structure | `codebase_graph_visualize` |
| Verify index is up to date | `codebase_status` |
| Discover what project knowledge (schemas, specs, configs) is available | `codebase_context` |
| Find database tables, API endpoints, infra configs | `codebase_context_search` |

为何要先进行语义搜索？ 一次 codebase_search 调用就能在毫秒内从整个代码库返回经过排序和去重的代码片段。这能以极低的 token 成本为你提供全局概览，远比试探性地打开文件便宜得多。了解哪些文件重要后，再有针对性地阅读会更快、更准确。话虽如此，如果你要查找确切的字符串或模式，grep 仍是合适的工具——根据查询选择工具即可。

索引期间保持连接。 索引在后台运行——即使 MCP 服务没有主动响应工具调用，也会继续工作。不过，一些 MCP 宿主可能会在连接闲置一段时间后断开连接，从而可能中断后台进程。启动 codebase_index 后，指示 AI 大约每隔 60 秒调用一次 codebase_status，直到索引完成。这样可以保持宿主连接处于活动状态，并实时提供进度。

配置

安装

请按照插件和宿主集成中的宿主专属步骤操作。这些步骤涵盖安装范围、激活、验证、更新，以及各宿主实际使用的配置架构。

从源代码安装（适用于贡献者）

git clone https://github.com/giancarloerra/socraticode.git
cd socraticode
npm install
npm run build

在 MCP 宿主支持的用户级或项目级范围内，将 node /absolute/path/to/socraticode/dist/index.js 注册为 MCP 服务，然后重启服务或启动新会话。在宿主的 MCP 服务列表中确认 SocratiCode 已就绪。如需更新，请在克隆目录中运行 git pull --ff-only、npm install 和 npm run build，然后重启 MCP 服务并再次确认。

MCP 宿主配置变体

以下示例使用常见的 JSON mcpServers 结构来展示 SocratiCode 设置。请通过插件和宿主集成中记载的宿主专属架构，应用相同的命令和环境变量值。Continue、Gemini CLI、VS Code、Zed 和 OpenCode 使用不同的配置路径或包装器。

默认（零配置，源码运行）

使用 npx？将下面的 node 命令和源码路径替换为 "command": "npx" 和 "args": ["-y", "--prefer-online", "socraticode@latest"]。

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"]
    }
  }
}

提示：默认的 OLLAMA_MODE=auto 会在启动时检测原生 Ollama（端口 11434），如果可用则使用它，否则回退到托管 Docker 容器。要让配置自带说明，请添加包含明确值的 "env" 块。所有选项请参见环境变量。

外部 Ollama（原生安装）

如果你已原生安装 Ollama，请设置 OLLAMA_MODE=external 并指向你的实例：

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "OLLAMA_MODE": "external",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

首次使用时会自动拉取嵌入模型。要预先下载：ollama pull nomic-embed-text

远程 Ollama 服务

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "OLLAMA_MODE": "external",
        "OLLAMA_URL": "http://gpu-server.local:11434"
      }
    }
  }
}

OpenAI 嵌入

使用 OpenAI 的云端嵌入 API 替代本地 Ollama。需要API 密钥。

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

默认值：EMBEDDING_MODEL=text-embedding-3-small、EMBEDDING_DIMENSIONS=1536。若要获得更高质量，可使用 text-embedding-3-large，并将 EMBEDDING_DIMENSIONS=3072。

Google Generative AI 嵌入

使用 Google 的 Gemini 嵌入 API。需要API 密钥。

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "google",
        "GOOGLE_API_KEY": "AIza..."
      }
    }
  }
}

默认值：EMBEDDING_MODEL=gemini-embedding-001、EMBEDDING_DIMENSIONS=3072。

LM Studio（本地，兼容 OpenAI）

LM Studio 附带本地服务器，可通过 http://localhost:1234/v1 提供兼容 OpenAI 的 API。当你想在 LM Studio 中托管嵌入模型时，请使用此提供方（例如，LM Studio 是聊天和嵌入模型的统一来源，或者你想使用适合 Mac/Windows 的桌面 UI 来管理 GGUF 模型）。

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "lmstudio",
        "EMBEDDING_MODEL": "nomic-embed-text-v1.5",
        "EMBEDDING_DIMENSIONS": "768"
      }
    }
  }
}

无默认值——必须设置 EMBEDDING_MODEL 和 EMBEDDING_DIMENSIONS。 LM Studio 不附带可直接使用的嵌入模型；你需要在本地服务器选项卡中自行加载。若缺少任一变量，SocratiCode 会立即报错。

可选项：LMSTUDIO_URL（默认值为 http://localhost:1234/v1），用于指定非默认端口；如果你在 LM Studio 中启用了 API 密钥身份验证，可设置 LMSTUDIO_API_KEY；对于没有 /v1/models 端点的兼容 OpenAI 的服务器，可设置 LMSTUDIO_ALLOW_MISSING_MODEL_LISTING=true（见下文）。

此提供方也适用于任何支持 OpenAI 嵌入 API 的其他服务器。 HuggingFace Text Embeddings Inference (TEI) 等单模型服务器会在启动时固定模型，并对 /v1/models 返回 404，因此就绪检查需要设置 LMSTUDIO_ALLOW_MISSING_MODEL_LISTING=true，以便回退到探测 /v1/embeddings：

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "lmstudio",
        "LMSTUDIO_URL": "http://localhost:8080/v1",
        "EMBEDDING_MODEL": "BAAI/bge-m3",
        "EMBEDDING_DIMENSIONS": "1024",
        "LMSTUDIO_ALLOW_MISSING_MODEL_LISTING": "true"
      }
    }
  }
}

EMBEDDING_MODEL 应填写服务器启动时使用的模型（TEI 的 --model-id），而且 EMBEDDING_DIMENSIONS 必须与该模型的输出维度相符——探测会检查这一点，若不匹配则立即报错，因为没有 /v1/models 时就没有其他依据可供验证。

LiteLLM（代理网关，100+ 个提供商）

LiteLLM 代理服务提供兼容 OpenAI 的 /v1/embeddings 端点，并将请求分发到 100 多个底层提供商（OpenAI、Anthropic、 Cohere、Voyage、HuggingFace、Bedrock、Vertex AI、Ollama 等）。如果你需要集中管理密钥 （为每位开发者使用一个虚拟密钥，而不是在 MCP 配置中分散使用 N 个提供商密钥）、在嵌入后端之间 故障转移／负载均衡，或创建在更换后端时仍可使用的与提供商无关的索引，请使用此提供商。

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "litellm",
        "LITELLM_API_KEY": "sk-...",
        "EMBEDDING_MODEL": "text-embedding-3-small",
        "EMBEDDING_DIMENSIONS": "1536"
      }
    }
  }
}

必须设置 LITELLM_API_KEY、EMBEDDING_MODEL 和 EMBEDDING_DIMENSIONS。 LiteLLM 代理始终需要身份验证（主密钥或通过 /key/generate 生成的虚拟密钥）；别名名称和底层维度来自你的 config.yaml。缺少任何一项时，SocratiCode 都会立即报错。

可选：LITELLM_URL（默认为 http://localhost:4000/v1）——必须包含 /v1 后缀；LITELLM_SEND_DIMENSIONS=true 可通过代理转发 OpenAI 的 dimensions 参数（仅适用于支持 Matryoshka 的后端，例如 text-embedding-3-* 或 voyage-3；不支持 Matryoshka 的后端会拒绝请求）。

这是 LiteLLM _代理服务_的客户端，不是 LiteLLM Python 库，也不会自行路由 provider/model 字符串。 它会原样将 EMBEDDING_MODEL 发送到 LITELLM_URL，并要求该名称出现在代理的 /v1/models 中。若要访问 OpenRouter 等后端，请在代理的 config.yaml model_list 中注册该后端（将 model_name 设为你填入 EMBEDDING_MODEL 的值，并将 litellm_params.model 设为例如 openrouter/qwen/qwen3-embedding-8b）；代理负责路由，SocratiCode 只发送别名。只有当非 LiteLLM 端点兼容 OpenAI、在 /v1/models 下列出你的 EMBEDDING_MODEL，并且能以其自身的原生模型 ID（不带 LiteLLM provider/ 前缀）接受该模型时，直接将 LITELLM_URL 指向该端点才可行。

Git Worktrees（跨目录共享索引）

如果你使用 git worktrees——或任何让同一仓库位于多个目录中的工作流——通常每个路径都会拥有独立的 Qdrant 索引。这会导致重复嵌入和存储本质上相同的代码库。

设置 SOCRATICODE_PROJECT_ID，即可让同一项目的所有目录共享单个索引。

支持检测 git worktree 的 MCP 宿主（例如 Claude Code）

一些 MCP 宿主（例如 Claude Code）会通过跟随 git worktree 链接来解析项目根目录。由于 worktree 会指向主仓库的 .git 目录，宿主会自动将所有 worktree 映射到同一项目配置。这意味着你只需为主检出配置一次 MCP 服务——所有 worktree 都会自动继承该配置。

对于 Claude Code，请在主检出目录中以本地作用域添加服务：

cd /path/to/main-checkout
claude mcp add -e SOCRATICODE_PROJECT_ID=my-project --scope local socraticode -- npx -y --prefer-online socraticode@latest

从此仓库创建的所有 worktree 都会自动使用共享的项目 ID 连接到 socraticode。无需单独配置每个 worktree。

注意： 这只适用于 git worktree。同一仓库的独立 git clone 会有各自独立的 .git 目录，因此不会共享配置。

其他 MCP 宿主（每个项目一个 `.mcp.json`）

对于无法解析 git worktree 路径的 MCP 宿主，请在每个 worktree（以及主检出目录）的根目录中添加 .mcp.json：

{
  "mcpServers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"],
      "env": {
        "SOCRATICODE_PROJECT_ID": "my-project"
      }
    }
  }
}

如果不想跟踪 .mcp.json，请将其添加到 .gitignore。

工作原理

使用此配置时，运行在 /repo/main、/repo/worktree-feat-a 和 /repo/worktree-fix-b 中的 Agent 都会共享同一组 Qdrant 集合：codebase_my-project、codegraph_my-project 和 context_my-project。

实际运行方式：

语义索引反映的是最近触发文件变更的工作树；但由于各分支通常只有少数文件不同，因此索引对所有工作树的准确率都在 99% 以上
你的 AI Agent 会从自己的工作树中读取实际文件内容；共享索引仅用于发现和导航
更改合并回 main 后，文件监视器会重新索引变更的文件，索引也会随之收敛

团队共享索引（提交 `projectId`）

上面的环境变量方案适用于单台机器。若要使用稳定标识符，让每位团队成员（以及 CI 运行器）都能自动获取，请在项目根目录的 .socraticode.json 中提交 projectId：

{
  "projectId": "my-project"
}

现在，无论仓库检出到磁盘上的什么位置，也无论由哪个用户帐户持有，所有检出版本都会访问同一组 Qdrant 集合：codebase_my-project、codegraph_my-project 和 context_my-project。对于共享 Qdrant 实例的团队，推荐采用这种设置：索引只需构建一次，就能让所有人受益，即使他们使用不同的 OS 用户，笔记本电脑的文件系统布局也完全不同。

该值必须匹配 [a-zA-Z0-9_-]+；首尾空白会被去除，若值缺失或为空，则会回退到基于路径哈希的默认值。设置 SOCRATICODE_PROJECT_ID 环境变量时，其优先级高于此文件，便于临时按机器覆盖设置，而无需修改仓库。

跨项目搜索（关联项目）

如果你需要跨多个相关仓库或包开展工作，可以通过单个查询搜索所有项目。

配置

在项目根目录中创建 .socraticode.json 文件：

{
  "linkedProjects": [
    "../shared-lib",
    "/absolute/path/to/other-project"
  ]
}

或者设置 SOCRATICODE_LINKED_PROJECTS 环境变量（以逗号分隔的路径）：

SOCRATICODE_LINKED_PROJECTS="../shared-lib,/absolute/path/to/other-project"

两个来源会合并并去重。相对路径会基于项目根目录解析。不存在的路径会被静默跳过。

用法

将 includeLinked: true 传递给 codebase_search：

使用 includeLinked: true 搜索“authentication middleware”

结果按与查询的余弦相似度排序，而不是按每个命中项在其所属项目中的位置排序。排名只在其所属列表中有意义，因此按排名排序会让小型项目中的首个命中项排在大型项目中强得多的命中项之前，并将所有跨项目分数限制在 1/61 ≈ 0.016，低于 SEARCH_MIN_SCORE 的默认值 0.10，导致结果全部被丢弃。余弦相似度是相对于同一查询向量的绝对度量，因此可以跨项目比较，且数值范围与阈值预期一致。单项目搜索不受影响，仍使用 Qdrant 的服务端 RRF。

如果无法为每个命中项计算余弦相似度，整个查询会回退到先前的排名融合方式，而不是混用两种不同的度量。以下三种情况会触发回退，且日志会记录涉及的集合：返回的块没有可用的稠密向量、向量的模为零，以及向量的维度与查询向量不同。请注意最后一种情况的局限：它能检测出使用不同维度模型进行嵌入的集合，但无法区分使用相同维度、不同模型的情况，这类集合仍会被评分。因此，请确保关联项目使用同一种嵌入模型。

在回退模式下，单个命中项最多贡献 1/(60+0+1) ≈ 0.0164，但同一文件若匹配到多个块，则会累积每个块的贡献（1/61 + 1/62 ≈ 0.0325），因此最终分数可能超过这个上限。无论如何，这些分数都远低于默认值 0.10，所以如果遇到这种情况，请为该查询调低 minScore。

结果会带有 [project-name] 标签，显示每条结果来自哪个项目。去重仅在单个项目内进行：如果两个不同项目中存在相同的相对路径，会保留为两条独立结果，因为它们确实是不同的文件（你自己的 src/util.ts 和关联项目中的同名文件不能互换）。在同一个项目内，路径优先级较高的匹配项会保留。

注意： 每个关联项目都必须先独立编制索引（codebase_index），才能进行搜索。

Python 导入根目录

对于导入根目录不是项目根目录、src/、lib/ 或 pyproject.toml 中声明的目录的 Python 项目，可以在项目根目录的 .socraticode.json 中列出运行时路径条目。例如，Apache Airflow 会将 dags/ 添加到 sys.path，因此 DAG 仓库可以这样声明：

{
  "pythonRoots": ["dags"]
}

条目必须是相对于项目根目录的现有目录路径。系统会对其进行去除空白、规范化和去重，同时保留声明顺序。绝对路径、项目根目录之外的路径（包括指向目录外部的符号链接）、不存在的路径、文件以及非字符串值都会被忽略。如果未设置 pythonRoots、其值为空，或没有可用条目，Python 解析行为将与之前完全相同。

解析时会优先保留现有的探测顺序：项目根目录、项目根目录下的 src/ 和 lib/，以及导入文件所在的目录。之后按声明顺序尝试配置的根目录，再尝试从适用的 pyproject.toml 清单中推导出的根目录。这样，显式的运行时布局就能优先于从清单推导出的备选路径，同时不会改变现有项目的行为。

添加、移除、重新排序或更改有效根目录后，代码图会在下次增量更新时重建。这不会重建或使代码／向量索引失效，也不需要手动重新编制索引。

分支感知索引

默认情况下，项目的所有分支共享同一个索引。切换分支时，监视器会重新索引已更改的文件，索引也会反映当前分支的状态。

对于需要为每个分支保留独立、持久索引的工作流（例如 CI/CD 流水线，或跨分支比较代码），请启用分支感知模式：

SOCRATICODE_BRANCH_AWARE=true

启用后，集合名称会包含分支名称（例如 codebase_abc123__main、codebase_abc123__feat_my-feature）。每个分支都有自己独立的索引、代码图和上下文制品。

还需要可用的分支名称。 分支名称会经过清理，以便用于集合名称。因此，若分支名称仅由分隔符组成（例如 ___），清理后后缀将为空，也不会创建分支专属集合。遇到这种情况时，请改为设置分支专属的 SOCRATICODE_PROJECT_ID。

仅适用于从路径派生的项目 ID。 如果项目固定了 ID（通过 SOCRATICODE_PROJECT_ID 或 .socraticode.json 中的 projectId），则该 ID 会被视为稳定身份，永远不会添加分支后缀，因此所有分支仍会共享一个索引。这是有意为之：给显式 ID 添加后缀会更改现有安装已使用的集合名称，并导致其索引看起来像是丢失了。启用分支感知模式但因此原因而被忽略时，SocratiCode 会针对每个项目记录一次警告。若要使用分支专属集合，请移除显式 ID，让从路径派生的 ID 可以附加后缀；或者有意设置分支专属的 SOCRATICODE_PROJECT_ID。

适用场景：

为每个分支或 PR 分别建立索引的 CI/CD 流水线
跨分支比较搜索结果
保持 main 索引不受功能分支更改影响

不适用场景：

经常切换分支的本地开发（默认共享索引效率更高）
通过 SOCRATICODE_PROJECT_ID 跟踪的项目（显式 ID 会绕过分支检测）

工作原理： projectIdFromPath() 会通过 git rev-parse --abbrev-ref HEAD 检测当前 git 分支，并将经过清理的分支后缀（例如 feat/my-feature → feat_my-feature）追加到基于哈希的项目 ID。处于分离 HEAD 状态时，会回退到不带分支后缀的 ID。

回收已存储的身份

工作树被移除、克隆被删除或文件夹被重命名后，索引仍会保留：codebase_remove 通过路径定位项目，因此已不存在的目录无法再被指定。codebase_prune 则根据存储中已有的记录进行操作。

报告。 不带参数调用 codebase_prune 会生成一份不做更改的清单。对于每个已存储的身份，它会列出所有使用该身份名称的集合（代码、图、符号图、上下文）和每条元数据记录，并将记录的路径报告为以下状态之一：

路径状态	含义
`present-on-this-host`	记录的目录可在此计算机上解析。
`absent-on-this-host`	检查明确返回了 `ENOENT`/`ENOTDIR`。这只是一次观察，并不能证明该目录已弃用：在共享的 Qdrant 中，路径仅存在于写入该索引的主机上。
`unknown/inaccessible`	权限被拒绝、挂载不可用，或没有记录路径。绝不能据此删除。
两个身份记录了同一个规范路径——同一检出对应的路径哈希身份和之后固定的 `projectId`——会被标记为 `possible-superseded`，仅作提示。若某个身份的记录对其路径存在分歧，则会被标记为需要人工检查，且本工具无法删除它。无法归属于任何身份的元数据点会连同其点 ID 和原因一并列出，也不会被处理。同样，如果某个集合名称可能属于两个身份，该集合也会被保留：固定的 `projectId` 若本身以 `codebase_`、`codegraph_` 或 `context_` 开头，或以 `_symgraph_meta`／`_file`／`_index` 结尾，就可能生成其他身份也能拥有的名称；清单会根据存储中的信息判定归属（元数据点会指明系列集合，完整的符号图三元组会指明符号图），其余情况则会列出供人工检查；所有可能拥有该名称的身份也都会被排除在删除范围之外，因为删除其中一个会移除证据，导致下次读取时该集合被判给另一个身份。

应用。 删除操作需要提供报告中的确切 identity、其旁边显示的 confirmationToken，以及 acknowledgeNoRemoteWriters: true。该令牌会对该身份的所有集合和元数据记录生成指纹，因此报告生成后的任何变更——新增记录、状态变更、资源新增或移除——都会导致应用操作被拒绝，并要求重新生成报告。如果该身份正在此进程中进行索引、监视、构建图或建立上下文索引，或者此主机上的另一个进程持有该身份的任何写入锁（index、watch、graph、context），又或者无法检查某个锁，删除都会被拒绝。从最终验证开始直至最后一次删除完成，工具会持有一个作用域为该身份的屏障：prune 锁及所有写入锁。每个写入器都会在启动前检查屏障，并在运行时以不可重入方式获取自己的锁（本进程已持有的锁绝不会被接管），因此，另一个本地进程中的图构建或上下文索引操作也会像索引器或监视器一样被排除；如果某个进程正在构建同一身份的图，第二个进程请求构建时会被拒绝，而不会与其并行运行。

共享存储限制。 锁文件位于此主机上。它们无法表明另一台共享同一 Qdrant 的机器是否空闲；acknowledgeNoRemoteWriters 表示操作员对此作出确认，工具不会自行推断这一点。

结果。 每个资源都会单独报告结果。每次写入前都会检查屏障所有权；如果清理过程中发现屏障锁已丢失，删除会在下一次写入前停止，剩余资源会报告为已跳过，清理结果则会报告为未完成。已不存在的资源会计为已删除，因此部分失败后重复应用是安全的；对于已无剩余资源的情况，不会执行任何操作。只有删除后重新读取清单，确认该身份的资源均已不存在，才会报告成功；否则会列出剩余资源。此进程中以该身份为键的缓存——图、已加载文件的哈希值和符号图——都会被清除。现有索引无需迁移或重新索引即可被报告。

可选的自动本地清理

默认情况下禁用自动清理。仅当 Qdrant 仅供本机使用，且未与其他机器共享时，才设置 SOCRATICODE_AUTO_CLEANUP=local。这会明确声明本地所有权；此操作要求使用托管模式和环回端点。共享或外部存储，以及显式项目 ID，仍由操作员通过 codebase_prune 管理。

新建且符合条件的索引会记录本地安装 UUID，以及其原始仓库、精确分支引用、工作区和 Git 管理目录。UUID 存储在用户主目录下的 .socraticode/local-index-owner 中，并在重启后继续使用。对于现有记录和缺乏充分证明的孤立资源，只会自动报告，不会迁移或要求重新索引。丢失本地所有权文件并不授权接管这些记录。在禁用清理期间写入的索引元数据不会获得自动清理所有权。

MCP 服务会在启动时和之后每分钟检查一次，且独立于自动恢复功能。它会复用 prune 的清单指纹、写入屏障、资源删除和验证机制。只有在 Git 注销链接工作区、其原始 Git 管理目录已删除，且其源目录在同一个已验证可访问的文件系统上不存在之后，该工作区才符合条件。只有在删除精确的本地引用，且没有已注册的工作区使用该引用之后，分支感知索引才符合条件。合并、压缩合并、分支切换、工作区移动、仅目录缺失、挂载不可用、权限错误、身份不明确或存在活动写入者，都不会授权删除。只会移除索引资源和元数据，绝不会移除源目录或 Git 分支。删除、拒绝操作和未完成的清理会通过 MCP 日志通知报告。部分集合删除失败时会保留所有权元数据，以便之后安全重试。

可用工具

连接后，AI 助手可使用以下工具：

索引

工具	描述
`codebase_index`	在后台开始索引代码库（轮询 `codebase_status` 查看进度）
`codebase_stop`	平稳停止正在进行的索引操作（当前批次会完成并创建检查点；使用 `codebase_index` 恢复）
`codebase_update`	增量更新——仅重新索引已更改的文件
`codebase_remove`	移除项目索引（安全停止监视器、取消正在进行的索引/更新，并等待图谱构建完成）
`codebase_prune`	清点每个已存储的项目身份及其集合和元数据；只有提供精确身份、新鲜的确认令牌以及共享存储确认后才能删除（参见回收已存储的身份）
`codebase_watch`	启动/停止文件监视——启动时会补上遗漏的更改，然后继续监视后续更改

搜索

工具	描述
`codebase_search`	混合语义 + 关键词搜索（密集向量 + BM25，通过 RRF 融合），可选文件路径、语言筛选器和跨项目搜索（`includeLinked`）
`codebase_status`	检查索引状态和分块数量

代码图谱

工具	描述
`codebase_graph_build`	构建多语言依赖图（在后台运行——使用 `codebase_graph_status` 轮询）
`codebase_graph_query`	查询特定文件的导入项和依赖方
`codebase_graph_stats`	获取图谱统计信息（连接最多的文件、孤立文件、语言分布）
`codebase_graph_circular`	检测循环依赖
`codebase_graph_visualize`	生成 Mermaid 图表（`mode=mermaid`，默认）或交互式 HTML 浏览器（`mode=interactive`），用于展示依赖图。交互模式会写入一个自包含页面（内置 Cytoscape.js + Dagre，可离线使用），并在默认浏览器中打开——支持文件和符号视图、影响范围叠加层、实时搜索、PNG 导出。
`codebase_graph_status`	检查图谱构建进度或持久化的图谱元数据（当解析成功的已捕获导入项较少时会给出提示，避免将近乎空白的图谱误认为正常；还会指出构建图谱的版本，避免将升级后遗留的图谱误认为是解析器故障）
`codebase_graph_remove`	删除项目持久化的代码图谱（会先等待正在进行的图谱构建完成）

影响分析（符号级调用图）

第二层图谱比文件导入关系更深入一步——它会追踪函数和方法之间的调用关系。在重构、重命名或删除代码之前，请使用这些工具。

工具	描述
`codebase_impact`	影响范围——更改文件/函数 X 会导致哪些文件出问题（通过反向调用边进行 BFS）。传入 `limit` 可仅列出有歧义的符号名称对应的前 N 个候选项；若有候选项未列出，答案会给出完整数量
`codebase_flow`	从入口点追踪向前的执行流。不带参数调用可发现入口点（孤立项、`main()`、框架路由、测试）。传入 `limit` 可仅列出有歧义的入口点名称对应的前 N 个候选项；若有候选项未列出，答案会给出完整数量
`codebase_symbol`	查看一个符号的 360° 视图——其定义、调用方和被调用方。传入 `limit` 可仅解析非唯一名称的前 N 个定义；若有定义未列出，答案会给出完整数量
`codebase_symbols`	列出文件中的符号，或按名称搜索整个项目

适用限制。 调用图基于静态分析——不进行类型推断。动态分派（getattr、obj[key](...)、反射、eval）、未展开的宏以及框架魔法（Spring @Autowired、Angular DI、Rails has_many、装饰器驱动的路由）都无法识别。仅通过这些机制调用方法的调用方不会出现在 codebase_impact 中。在依赖注入较多的代码库中，请将“零个调用方”视为需要进一步检查的提示。codebase_graph_status 会报告未解析占比（unresolvedEdgePct），作为质量信号：已捕获的符号边（调用、导入、重新导出以及类型或值引用）中，未匹配到任何项目符号的百分比，不包括 GDScript 引擎调用。该占比也包含指向运行时内置项和外部库的边（例如 setTimeout、JSON.stringify、SDK 客户端的方法），这些边无法解析到项目符号，因此在正常的 TypeScript/JavaScript 代码中该占比可能较高，并不代表解析器故障。完整列表请参阅 DEVELOPER.md § Impact Analysis。

交互式图谱探索器

向 AI 提问 “显示此项目的交互式图谱”（或调用 codebase_graph_visualize 并设置 mode: "interactive"），SocratiCode 会生成一个独立的 HTML 页面，并在默认浏览器中打开：

文件视图 — 将每个源文件显示为一个节点，将导入关系显示为边；按语言着色，并以红色标出循环依赖。
符号视图 — 切换后，可将函数／类／方法显示为带有调用边的节点（当符号图符合嵌入上限时可用；超过该阈值后会保留文件视图，并通过横幅提示使用 codebase_impact 进行符号级查询）。
侧边栏 — 点击节点可查看导入项／依赖方／文件中的符号／行号，还可使用操作按钮查看影响范围和调用流。
右键点击任意节点 → 高亮其反向传递闭包（此项变更会影响哪些对象）。
实时搜索可筛选并聚焦匹配的节点。布局切换器 — Dagre／力导向／同心圆／广度优先／网格／圆形。导出 PNG 可生成便于分享的图像。
可离线使用 — Cytoscape.js + Dagre 已随 SocratiCode 软件包一起提供。无需 CDN 或网络连接，可在隔离网络环境中运行。

输出为单个 HTML 文件（写入操作系统临时目录，每个项目对应一个），你也可以将其提交到 PR 或分享到 Slack。

管理

工具	描述
`codebase_health`	检查 Docker、Qdrant 和嵌入服务提供方的状态
`codebase_list_projects`	列出所有已索引项目及其路径和元数据
`codebase_about`	显示有关 SocratiCode 的信息

上下文制品

工具	描述
`codebase_context`	列出 `.socraticodecontextartifacts.json` 中定义的所有上下文制品，包括名称、描述和索引状态
`codebase_context_search`	对上下文制品进行语义搜索（首次使用时自动建立索引，并自动检测索引是否过时）
`codebase_context_index`	对 `.socraticodecontextartifacts.json` 中的所有制品建立或重新建立索引
`codebase_context_remove`	移除项目中所有已索引的上下文制品（索引正在进行时无法执行）

语言支持

SocratiCode 在三个层级上支持多种语言：

完整支持（索引 + 代码图谱 + AST 分块）

JavaScript、TypeScript、TSX、Python、Java、Kotlin、Scala、C、C++、C#、Go、Rust、Ruby、PHP、Swift、Dart、Elixir（包括 HEEx/EEx）、Bash/Shell、HTML、CSS/SCSS、Svelte、Vue

有条件的 AST 支持

GDScript：.gd 文件使用可选的原生二进制程序（tree-sitter-gdscript）进行 AST 分块、符号提取和调用点解析。原生解析器不可用时，语法感知型回退方案会处理导入提取和按行分块，且不会根据注释或字符串创建边。系统可解析 class_name 声明、extends/preload/load 导入以及 res:// 路径。相对 extends 和 preload 路径以脚本目录为基准；相对运行时 load 路径以 Godot 项目根目录为基准。系统会按文件发现 project.godot，支持嵌套和同级 Godot 项目。Godot 场景和资源（.tscn/.tres）按行分块建立索引。[ext_resource] 声明会通过令牌解析器提取为依赖边，该解析器可处理任意空白字符、属性顺序、转义引号，以及 uid="uid://..." 和 path="..." 两种属性。两者同时存在时，优先使用 UID。根据 TSCN 文档，系统同时支持 res:// 路径和相对于 .tscn/.tres 文件的路径。res:// 路径会在代码图谱中解析为 .gd、.tscn 和 .tres 目标。 Svelte 和 Vue：从 <script> 代码块提取导入项（重新解析为 TypeScript），并从 <style> 代码块提取 CSS @import/@require（支持 lang、scoped、module、global 属性的任意组合）。可解析 tsconfig.json/jsconfig.json 中 compilerOptions.paths 配置的路径别名（包括 extends 链）。支持 SCSS partial 解析（_ 前缀约定）。

Python：绝对导入通过项目 pyproject.toml 文件所隐含的导入根目录进行解析——包括根目录和嵌套目录，因此 uv 工作区会建立跨包边；涵盖 src/ 布局（packages/<dist>/src/<module>/…，即 uv init --lib、hatchling 和 setuptools 生成的布局）和与各清单文件同级的扁平布局，包括 PEP 420 命名空间包和单模块发行版。只有当清单文件位于某文件的祖先路径上，或某个祖先清单将其声明为 [tool.uv.workspace] 成员时，该清单才适用于此文件；因此，样例应用、文档项目或包含自身清单文件的已检入 sdist 不会成为无关代码的导入根目录。只读取 [tool.uv.workspace]，因此 poetry、pdm 和 hatch 路径依赖单体仓库会按祖先路径限定作用范围，且不会建立跨包边；适用的根目录按从近到远的顺序尝试，因此包会先解析自身模块，再解析同级包。相对导入以及项目根目录下的 src//lib/ 和同级扁平布局约定保持不变——同级扁平布局回退方式的优先级仍高于这些根目录，这与 CPython 一致，因为 CPython 会将脚本所在目录放在 sys.path[0]。

PHP：use 导入通过项目 composer.json 文件中声明的 PSR-4 前缀进行解析——包括根目录和嵌套目录，因此 Composer 单体仓库的路径包会建立跨包边。如果没有前缀匹配，则根据项目自身找到的 namespace 以及类/接口/trait/enum 声明进行解析，这样就能找到以 "autoload": {} 发布、并在运行时注册命名空间（$loader->addNamespace(...)，即 WordPress 插件的惯例）的包——不涉及对 spl_autoload_register 的解释。逗号分隔列表（use A\B, A\C;）、分组导入（use A\{B, C};，包括成员级别的 function/const 修饰符）以及完全限定名称（use \A\B;）都会被读取。require/include 会解析相对路径、裸路径（先查源目录，再查项目根目录）以及 __DIR__ . '<literal>' / dirname(__FILE__) . '<literal>'；这是 Composer 之外最常见的 include 写法。它们会从 include 表达式本身读取，因此无论出现在什么位置都能被找到——return require __DIR__ . '/routes.php'; 和 $config = include 'config.php'; 都会被计入，而注释中的 include 或字符串中的 include 则不会。与运行时值拼接的 include（ABSPATH . '/x.php'、$base . '/x.php'）会保持未解析状态，而不会进行猜测。

Dart：符号（类、mixins、枚举、扩展、typedef、函数、getter、setter、运算符、构造函数，包括命名构造函数和工厂构造函数，以及抽象/无函数体成员）、调用点（方法调用、级联调用、构造函数调用）、main() 入口点检测和 AST 分块均基于 tree-sitter；import/export/part 边通过正则表达式提取。项目内部的 package: 导入（Flutter 惯例）通过项目的 pubspec.yaml 文件进行解析——包括根目录和嵌套目录，因此 pub 工作区/melos 单体仓库会建立跨包边——采用 pub 的 package:<name>/<rest> → <package_root>/lib/<rest> 映射；dart: 和未知包名会保留为外部导入。捆绑的语法（@ast-grep/lang-dart）早于 Dart 3 类修饰符（sealed/base/interface/final/mixin class）和 extension type，因此在上游语法更新前，使用这些声明的代码会被跳过（并记录一次性警告），而每个文件的其余部分仍会正常建立索引。 Elixir：.ex 和 .exs 文件使用 ast-grep 语法进行分块。alias、import、require 和 use 指令会解析为项目内的 defmodule 声明；没有上述指令的完全限定调用仍无法解析。defmodule、def、defp 和普通调用会生成符号和调用边。分块以模块为单位；大型模块会改用按行窗口分块，而不是按函数分块。目前，defprotocol、defimpl、defguard、defmacro 和 defdelegate 声明不会注册符号；协议和实现作用域也不会被表示，因此其中的函数会显示为顶层符号。独立的 .heex 和 .eex 模板使用专用的 tree-sitter 语法进行 AST 分块、远程组件依赖分析，以及嵌入式 Elixir 表达式的调用提取；标记和注释绝不会被解析为 Elixir。.leex 会尽力使用 EEx 语法解析；如果解析失败，则安全地回退为按行分块且不提取边。

基于正则表达式和索引的代码图谱

Lua（require/dofile/loadfile）、SASS、LESS、Stylus（提取 CSS @import/@require）

仅索引（混合搜索，按行分块）

JSON、YAML、TOML、XML、INI/CFG、Markdown/MDX、RST、SQL、R、Dockerfile、TXT，以及所有扩展名受支持或文件名特殊的文件（Dockerfile、Makefile、Gemfile、Rakefile 等）

开箱即支持 63 种文件扩展名 + 8 个特殊文件名。

启用 INDEX_EXTENSIONLESS 后（默认启用），也会通过基于内容的语言检测对无扩展名文件（Unix 脚本、健康探测文件、被引入的库）进行索引——请参阅下文中的该环境变量。

忽略规则

索引器会合并以下三层忽略规则：

内置默认规则 — node_modules、.git、dist、build、锁文件、IDE 文件夹等。
.gitignore — 项目中的所有 .gitignore 文件（根目录和嵌套子目录）。将 RESPECT_GITIGNORE=false 可完全跳过 .gitignore 处理。
.socraticodeignore — 可选文件，用于设置索引器专属排除项。语法与 .gitignore 相同。

这三层规则也适用于指向目录的上下文产物，但它们以产物目录而非项目根目录为基准解析。项目根目录下的 .gitignore 或 .socraticodeignore 会控制代码索引，但不会作用于目录产物。目录产物适用的规则包括：内置默认规则、产物根目录下的 .gitignore 及任何嵌套的 .gitignore 文件，以及仅位于产物根目录下的 .socraticodeignore。不会读取嵌套的 .socraticodeignore 文件。要从目录产物中排除内容，请将模式写入上述适用文件之一。

请注意，目录产物会完整继承所有内置默认规则，而不仅仅是构建输出相关规则。除 __pycache__、*.pyc、dist 和 build 外，该列表还包含一些产物目录可能会合理使用的名称：env、vendor、target、out、coverage、*.map、*.log。如果目录产物需要其中某项，请在产物根目录的 .socraticodeignore 中使用 ! 模式重新纳入，并否定名称本身（!env）。根据 Gitignore 语义，无法重新纳入其父目录已被排除的文件，因此单独使用 !env/** 不起作用。target 还有一项额外限制：可以重新纳入其中的内容，但发现嵌套 .gitignore 文件时会跳过 target/，因此不会加载 target/.gitignore 中的规则。请将这些规则放在产物根目录的 .gitignore 或 .socraticodeignore 中。被忽略规则排除、二进制检查排除或因无法读取而未处理的文件，会计入索引该产物时对应的日志行。node_modules、.git 和点文件会在遍历开始前被剪枝，因此不会计入任何数量。

上下文资源

让 AI 了解源代码之外的项目知识 ———例如数据库架构、API 规范、基础设施配置、架构文档等。

设置

在项目根目录中创建 .socraticodecontextartifacts.json 文件（请参阅 .socraticodecontextartifacts.json.example 获取入门模板）：

{
  "artifacts": [
    {
      "name": "database-schema",
      "path": "./docs/schema.sql",
      "description": "Complete PostgreSQL schema — all tables, indexes, constraints, foreign keys. Use to understand what data the app stores and how tables relate."
    },
    {
      "name": "api-spec",
      "path": "./docs/openapi.yaml",
      "description": "OpenAPI 3.0 spec for the REST API. All endpoints, request/response schemas, auth requirements."
    },
    {
      "name": "k8s-manifests",
      "path": "./deploy/k8s/",
      "description": "Kubernetes deployment manifests. Shows how services are deployed, scaled, and networked."
    }
  ]
}

每个资源包含：

name — 唯一标识符（用于筛选搜索结果）
path — 文件或目录的路径（相对于项目根目录，也可以是绝对路径）。目录会递归读取，但会排除：点文件和点目录（.pytest_cache/、.tox/）；与针对资源目录解析的忽略规则匹配的内容；以及二进制文件（通过检查前 8 KiB 中是否包含 NUL 字节来检测）。排除的文件会按目录汇总数量并记录日志。指向单个文件的路径会原样读取 — 不应用任何排除规则，因此声明的二进制文件仍会被索引。
description — 告诉 AI 该资源是什么以及如何使用它

工作原理

资源会分块并嵌入 Qdrant，使用与代码相同的混合稠密 + BM25 搜索。首次搜索时，资源会自动编入索引。后续搜索时，系统会通过内容哈希自动检测是否过时 — 更改过的文件会被自动重新索引。

由于排除规则会在计算内容哈希前应用，资源目录下的构建输出不再会导致资源被标记为过时。若由早期版本编入索引的目录资源在之前的遍历中嵌入了现已排除的文件，则会在下次哈希检查时重新索引 — 重新索引后，其分块数量可能会减少。没有需要排除内容的资源，其哈希值保持不变，因此不会受到影响。

用法

发现：codebase_context — 列出所有已定义资源及其索引状态
搜索：codebase_context_search — 跨所有资源进行语义搜索（也可按名称筛选）
重新索引：codebase_context_index — 强制重新索引（通常不需要，自动索引会处理）
清理：codebase_context_remove — 移除所有已索引的资源

为什么这很重要：实际工作流示例

没有资源时，Agent 只能看到源代码。有了资源，它就能掌握全貌，从一开始就编写符合项目要求的代码。

数据库架构 — 你提出 “为 users 添加一个 last_login 时间戳。” Agent 使用 codebase_context_search 搜索“users 表”，发现架构采用 snake_case 列名，而且每张表都有一个由触发器维护的 updated_at。它编写的迁移会遵循现有约定，而不是凭空猜测。

{
  "name": "database-schema",
  "path": "./docs/schema.sql",
  "description": "Complete PostgreSQL schema — all tables, columns, types, constraints, indexes, and triggers. Check this before writing migrations to match naming conventions and existing patterns."
}

API 规范 — 你提出 “为用户偏好设置添加一个 GET 端点。” Agent 搜索 OpenAPI 规范，发现所有端点都使用 Bearer 身份验证，返回 { data, meta } 包装结构，并使用 cursor/limit 分页。新端点会自动遵循相同模式。

{
  "name": "api-spec",
  "path": "./docs/openapi.yaml",
  "description": "OpenAPI 3.0 spec for the REST API — all endpoints, request/response schemas, auth, pagination. Check this before adding or modifying endpoints to match existing conventions."
}

领域术语表（DDD） — 你提出 “添加一种取消订单的方式。” Agent 搜索领域术语表，发现取消操作建模为 OrderVoided 事件（而不是“cancelled”），只有处于 Confirmed 状态的订单才能作废，并且必须通知 Fulfillment 限界上下文。实现会使用正确的领域术语，并与恰当的限界上下文集成。

{
  "artifacts": [
    {
      "name": "ubiquitous-language",
      "path": "./docs/ubiquitous-language.md",
      "description": "Domain glossary — bounded context terms, their definitions, and relationships. Always check this before naming entities, events, or commands to use the correct domain language."
    },
    {
      "name": "context-map",
      "path": "./docs/context-mapping.md",
      "description": "Bounded context map — context boundaries, relationships (shared kernel, customer-supplier, etc.), and integration patterns. Check before implementing cross-context communication."
    },
    {
      "name": "event-storming",
      "path": "./docs/event-storming/",
      "description": "Event storming output — domain events, commands, aggregates, policies, and read models. Check before adding new domain behaviour to see how it fits the existing event flows."
    }
  ]
}

description 字段是关键所在。 它告诉 AI 不仅要了解资源是什么，还要了解何时查阅。编写描述时，应注明“执行 X 前请检查此内容”，这样 Agent 就能在合适的时机查阅资源。

示例制品

类别	示例
数据库	SQL 架构转储（`pg_dump --schema-only`）、Prisma 架构、Rails `schema.rb`、Django 模型转储、迁移文件
API 契约	OpenAPI/Swagger 规范、GraphQL 架构、Protobuf 定义、AsyncAPI 规范（Kafka、RabbitMQ）
基础设施	Terraform/Pulumi 配置、Kubernetes 清单、Docker Compose 文件、CI/CD 流水线配置
架构	架构决策记录（ADR）、服务拓扑文档、数据流图、领域术语表
运维	监控/告警规则、RBAC/权限矩阵、身份验证流程文档、功能标志配置
外部	第三方 API 文档、合规要求（SOC2、HIPAA、GDPR）、SLA 定义

提示：对于数据库架构，每种主流数据库都可以将完整架构导出到单个文件：pg_dump --schema-only（PostgreSQL）、mysqldump --no-data（MySQL）、sqlite3 db.sqlite .schema（SQLite）。ORM 架构（Prisma、Rails、Django）通常已存在于你的仓库中。

环境变量

SocratiCode 在 MCP 服务启动时读取环境变量中的配置。变量名称和文件格式取决于 MCP 宿主；插件捆绑的服务不一定会继承直接注册的服务所使用的配置。更改变量后，请重启或重新连接服务，并开启新的宿主会话。如果变量似乎未生效，请先检查宿主的文档说明，包括其配置架构和安装范围。

运维设置会应用于新进程。定义已存储向量、分块、路径或其他索引表示形式的设置遵循有效索引配置文件：对于现有集合，更改后的值会标记为待应用；集合仍可使用，且绝不会自动重建或部分重写。只有在确实要让更改后的表示形式生效时，才移除集合并重新建立索引。

按宿主传递环境变量

宿主	配置文件	环境变量语法
Claude Code 原生插件	`~/.claude/settings.json`	顶层 `"env": { "KEY": "value" }`
仅使用 MCP 的 Claude Code	用户或项目 MCP 配置	`claude mcp add --env KEY=value ...`，或已存储的服务定义中的 `env` 对象
Claude Desktop、Windsurf 和 Cline	宿主 MCP JSON	服务定义中的 `"env": { "KEY": "value" }`
OpenAI Codex 原生插件	`~/.codex/config.toml`	禁用其捆绑服务并添加一个顶层配置服务
仅使用 MCP 的 OpenAI Codex	`~/.codex/config.toml`	`codex mcp add --env KEY=value`、内联 TOML `env = { ... }`，或 `[mcp_servers.NAME.env]`
VS Code Agent 插件	VS Code MCP 服务状态及用户 MCP 配置	使用 `env` 或 `envFile` 保留插件、禁用其捆绑服务并添加一个直接服务
VS Code 直接使用 MCP	`.vscode/mcp.json` 或用户 MCP 配置	`servers` 条目中服务定义里的 `"env": { "KEY": "value" }`
VS Code 编辑器扩展	VS Code 设置	`"socraticode.env": { "KEY": "value" }`
Cursor 本地插件	Cursor 自定义及直接 MCP 配置	使用 `env` 保留插件、禁用其捆绑服务并添加一个直接服务
Cursor 直接使用 MCP	用户或项目 `mcp.json`	服务定义中的 `"env": { "KEY": "value" }`
Continue	YAML 配置	`mcpServers` 列表项中的 `env:` 映射
Zed	`context_servers` JSON	`"env": { "KEY": "value" }`
Gemini CLI 直接使用 MCP	`~/.gemini/settings.json` 或 `.gemini/settings.json`	为服务显式设置 `"env"` 条目
OpenCode 1.x / V2	`opencode.json` / `opencode.jsonc`（架构）	`"environment": { "KEY": "value" }`，而非 `"env"`；V2 将服务嵌套在 `mcp.servers` 下

设置了几个环境变量的示例：

MCP JSON 宿主，例如 Claude Desktop、Windsurf、Cline 和 Cursor：

{
  "mcpServers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"],
      "env": {
        "QDRANT_MODE": "external",
        "QDRANT_URL": "https://xyz.qdrant.io"
      }
    }
  }
}

OpenCode——注意使用 environment，而非 env：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "socraticode": {
      "type": "local",
      "command": ["npx", "-y", "--prefer-online", "socraticode@latest"],
      "enabled": true,
      "environment": {
        "QDRANT_MODE": "external",
        "QDRANT_URL": "https://xyz.qdrant.io"
      }
    }
  }
}

OpenAI Codex CLI，使用嵌套表格形式：

[mcp_servers.socraticode]
command = "npx"
args = ["-y", "--prefer-online", "socraticode@latest"]

[mcp_servers.socraticode.env]
QDRANT_MODE = "external"
QDRANT_URL = "https://xyz.qdrant.io"

对应的 CLI 形式为 codex mcp add socraticode --env QDRANT_MODE=external --env QDRANT_URL=https://xyz.qdrant.io -- npx -y --prefer-online socraticode@latest。内联 env = { ... } 也是有效的 TOML。

本节其余部分介绍这些变量本身。请使用与宿主相匹配的语法传递它们。

有效索引配置

代码和上下文集合会持久保存用于定义其存储表示形式的设置。现有集合会继续使用其有效配置进行索引、监视器更新和搜索。搜索和状态查询会解析未配置有效配置的旧版集合，但不会写入元数据；下一次索引或更新操作会在更改向量之前持久保存解析后的配置。如果嵌入提供方、模型、维度、上下文长度、查询或文档前缀、路径包含设置、分块上限、扩展名-语言映射、文件大小上限或 LiteLLM 维度标志发生变化，codebase_status 会将其报告为待处理变更，且不会部分更改集合。使用 codebase_remove 移除集合，然后运行 codebase_index，即可在全新索引中启用所请求的配置。对于新引入的设置，旧版集合仍可使用已发布的默认值；历史上不可用的值会标记为 legacy-unverified。

Embedding 提供方

变量	默认值	说明
`EMBEDDING_PROVIDER`	`ollama`	Embedding 后端：`ollama`（本地，默认）、`openai`、`google`、`lmstudio` 或 `litellm`
`EMBEDDING_MODEL`	(因提供方而异)	模型名称。默认值：`nomic-embed-text`（ollama）、`text-embedding-3-small`（openai）、`gemini-embedding-001`（google）。`lmstudio` 和 `litellm` 必须设置（无默认值）。
`EMBEDDING_DIMENSIONS`	(因提供方而异)	向量维度。默认值：`768`（ollama）、`1536`（openai）、`3072`（google）。`lmstudio` 和 `litellm` 必须设置（无默认值；因已加载的模型或代理别名而异）。
`EMBEDDING_CONTEXT_LENGTH`	(自动检测)	模型的上下文窗口长度（以 token 计）。对于已知模型名称会自动检测（适用于与底层模型名称匹配的 LiteLLM 别名）。对于自定义 LM Studio 模型或任意 LiteLLM 别名，请手动设置。
`EMBEDDING_QUERY_PREFIX`	`"search_query: "`	在查询进行 embedding 前添加的任务前缀。请根据模型设置：`multilingual-e5-` 使用 `"query: "`，`cl-nagoya/ruri-v3-` 使用 `"検索クエリ: "`，`bge-m3` 使用空字符串（该模型不需要前缀）。设置为 `""` 可禁用。省略该变量与将其设为空值并不相同：未设置时会使用默认值，而 `=` 后不填写任何内容则表示完全不添加前缀。
`EMBEDDING_DOCUMENT_PREFIX`	`"search_document: "`	在文档进行 embedding 前添加的任务前缀。对应的前缀：`multilingual-e5-` 使用 `"passage: "`，`cl-nagoya/ruri-v3-` 使用 `"検索文書: "`，`bge-m3` 使用空字符串。设置为 `""` 可禁用，未设置与设为空值的区别同上。必须与 `EMBEDDING_QUERY_PREFIX` 一起更改。现有集合会保留其实际使用的前缀；删除集合并重新索引后，更改的值才会生效。
`EMBEDDING_DOCUMENT_INCLUDE_PATH`	`true`	是否将文件路径与文本块一起进行 embedding，置于 `EMBEDDING_DOCUMENT_PREFIX` 和内容之间。接受 `true` / `1` / `yes` 和 `false` / `0` / `no`，不区分大小写，并忽略首尾空格；留空与未设置相同，任何其他值都会被拒绝，并在错误中指出该值。路径 token 有助于匹配路径形式的查询，但会给以文本内容为主的语料库引入噪声。设置为 `false` 后，只对文档前缀和文本块内容进行 embedding，两者之间不添加分隔符，前缀本身末尾包含的内容除外。相同文本也会用于稠密 embedding 和 BM25 词法索引，因此由路径生成的 token 也不会再匹配关键词搜索；对于上下文产物，`context:<name>:<path>` 标识符也会随路径一并移除。现有集合会保留其实际使用的路径设置；删除集合并重新索引后，更改的值才会生效。

Ollama 配置（当 `EMBEDDING_PROVIDER=ollama` 时）

变量	默认值	说明
`OLLAMA_MODE`	`auto`	`auto` = 如果端口 11434 上有可用的原生 Ollama，则使用它；否则管理 Docker 容器（推荐）。`docker` = 始终使用端口 11435 上由系统管理的 Docker 容器。`external` = 使用由用户管理的 Ollama 实例（原生、本地远程实例等）
`OLLAMA_URL`	`http://localhost:11434`（auto/external） / `http://localhost:11435`（docker）	完整的 Ollama API 端点
`OLLAMA_PORT`	`11435`	Ollama 容器端口（Docker 模式）。显式设置 `OLLAMA_URL` 时会忽略此项。
`OLLAMA_HOST`	`http://localhost:{OLLAMA_PORT}`	Ollama 基础 URL（可替代 `OLLAMA_URL`）
`OLLAMA_API_KEY`	(无)	用于通过身份验证的 Ollama 代理的可选 API 密钥

云服务商 API 密钥

变量	默认值	描述
`OPENAI_API_KEY`	(none)	当 `EMBEDDING_PROVIDER=openai` 时必需。请从 platform.openai.com 获取
`GOOGLE_API_KEY`	(none)	当 `EMBEDDING_PROVIDER=google` 时必需。请从 aistudio.google.com 获取

LM Studio 配置（当 `EMBEDDING_PROVIDER=lmstudio` 时）

变量	默认值	描述
`LMSTUDIO_URL`	`http://localhost:1234/v1`	LM Studio 兼容 OpenAI 的本地服务的完整基础 URL。若服务运行在非默认端口或远程机器上，请覆盖此值（例如 `http://gpu-rig.local:5678/v1`）。必须包含 `/v1` 后缀。
`LMSTUDIO_API_KEY`	(none)	可选。LM Studio 的本地服务默认不启用身份验证；仅当你在 LM Studio UI 中启用了 API 密钥身份验证时才设置此项。
`LMSTUDIO_ALLOW_MISSING_MODEL_LISTING`	`false`	接受没有 `/v1/models` 端点的 OpenAI 兼容服务。HuggingFace Text Embeddings Inference（TEI）等单模型服务会在启动时固定模型，并对模型列表请求返回 404，而 `/v1/embeddings` 可正常工作。启用时（`true` / `1` / `yes`），就绪状态和健康检查会改为使用一个临时输入探测 `/v1/embeddings`，并检查探测返回的向量维度是否与 `EMBEDDING_DIMENSIONS` 一致。只有模型列表请求返回 404 或 405 时才会触发回退；连接被拒绝、返回 401 或 5xx 时，仍会报告 LM Studio 诊断信息。也接受 `false` / `0` / `no`；其他任何非空值都会在启动时被拒绝，而不会被静默地视为 `false`。

LiteLLM 配置（当 `EMBEDDING_PROVIDER=litellm` 时）

变量	默认值	描述
`LITELLM_URL`	`http://localhost:4000/v1`	LiteLLM 代理兼容 OpenAI 的端点的完整基础 URL。非默认端口或远程代理请覆盖此值（例如 `https://litellm.internal:4001/v1`）。必须包含 `/v1` 后缀——LiteLLM 会在此前缀下提供 `/v1/embeddings`。
`LITELLM_API_KEY`	(none)	必需。主密钥（代理 `config.yaml` 中的 `general_settings.master_key`），或通过 LiteLLM 的 `/key/generate` 端点签发的虚拟密钥。与 LM Studio 不同，LiteLLM 始终会进行身份验证——`/v1/models` 本身也受身份验证保护。
`LITELLM_SEND_DIMENSIONS`	`false`	选择启用（`true` / `1` / `yes`）。通过代理转发 OpenAI 风格的 `dimensions` 参数。仅适用于支持 Matryoshka 的后端（`text-embedding-3-*`、`voyage-3`）；其他后端（BGE、`nomic-embed-text`、Cohere v3）会拒绝该请求。除非确定你的别名解析到 Matryoshka 模型，否则请勿设置。

Qdrant 配置

变量	默认值	描述
`QDRANT_MODE`	`managed`	`managed` = 由 Docker 管理的本地 Qdrant（默认）。`external` = 用户提供的远程或云端 Qdrant（不由 Docker 管理）。
`QDRANT_URL`	(none)	远程或云端 Qdrant 实例的完整 URL（例如 `https://xyz.aws.cloud.qdrant.io:6333`）。设置后，其优先级高于 `QDRANT_HOST` + `QDRANT_PORT`。端口会根据 URL 自动推断：如果 URL 中指定了端口，则使用该端口（例如 `:8443`）；否则，`https://` 使用 `443`，`http://` 使用 `6333`。当 `QDRANT_MODE=external` 时，必须设置此变量（或设置 `QDRANT_HOST`）。
`QDRANT_PORT`	`16333`	Qdrant REST API 端口（托管模式下使用，或在未设置 `QDRANT_URL` 的外部模式下使用）
`QDRANT_GRPC_PORT`	`16334`	Qdrant gRPC 端口（仅托管模式下使用）
`QDRANT_HOST`	`localhost`	Qdrant 主机名（可替代 `QDRANT_URL`，用于非 HTTPS 外部实例）
`QDRANT_API_KEY`	(none)	Qdrant API 密钥（Qdrant Cloud 和其他需要身份验证的部署必须设置）。设置后，URL 必须使用 `https://...`，以免通过普通 HTTP 传输密钥。本地开发时，环回 URL（`localhost`、`127.0.0.1`、`[::1]`）可使用 `http://`。
`QDRANT_COLLECTION_PREFIX`	(empty)	可选前缀，会添加到 SocratiCode 创建的每个 Qdrant 集合名称前。适用于与其他应用（Open-WebUI、自定义 RAG 等）共用一个 Qdrant 实例，或让多个 SocratiCode 实例连接同一个 Qdrant，以区分项目、环境或每位用户的索引。默认空字符串会使集合名称与之前的版本保持一致（完全向后兼容）。如果设置，必须符合 `[a-zA-Z0-9_-]+`；无效前缀会在启动时引发错误。更改前缀会导致之前的集合变成孤立集合；如需迁移，请先使用 `codebase_remove`。

索引行为

变量	默认值	描述
`RESPECT_GITIGNORE`	`true`	设置为 `false` 可跳过 `.gitignore` 处理。内置默认规则和 `.socraticodeignore` 仍然生效。
`INCLUDE_DOT_FILES`	`false`	设置为 `true` 可在索引中包含点目录（例如 `.agent`、`.config`）。默认情况下，以 `.` 开头的目录和文件会被排除。适用于重要代码位于点目录中的项目。
`EXTRA_EXTENSIONS`	(无)	以逗号分隔的其他要扫描的文件扩展名列表（例如 `.tpl,.blade,.hbs`）。同时适用于索引和代码图。使用额外扩展名的文件会以纯文本形式编入索引，并作为代码图中的叶节点。也可通过工具参数 `extraExtensions` 按操作传入。
`EXTENSION_LANGUAGE_MAP`	(无)	以逗号分隔的 `extension:language` 覆盖项，用于将非标准扩展名端到端地视为真实语言（语义/AST 分块、符号、调用图），例如 Drupal/PHP 可使用 `EXTENSION_LANGUAGE_MAP=.inc:php,.module:php`。与 `EXTRA_EXTENSIONS`（以纯文本形式编入索引）不同，映射后的扩展名会获得完整的语言处理，且无需同时列入 `EXTRA_EXTENSIONS` 即可自动发现。目标必须是 SocratiCode 支持 AST 文法的语言（上文的完整支持列表以及 AST 图语言）；未知目标会被忽略，并在启动时发出警告。也可覆盖内置映射（例如 `.h:cpp`）。现有代码集合会保留其有效映射，直到重新编入索引。
`INDEX_EXTENSIONLESS`	`true`	启用时（默认），如果无扩展名文件的内容表明其为代码，则会编入索引，例如 shebang（`#!/bin/bash`、`#!/usr/bin/env python3` 等）或保守的内容嗅探（无 shebang 的 Python/shell）。带有未映射解释器（perl、awk、make 等）的 shebang 文件会作为可搜索纯文本编入索引。二进制文件（文件头中有 NUL 字节）和无法检测的文本（配置、许可证、数据）绝不会编入索引。始终保留磁盘上的真实路径——只推断检测到的语言/文法，因此检测为 `.txt` 的文件不会进入代码图。设置为 `false` 或 `0` 可恢复之前的行为（仅当无扩展名文件的确切名称属于特殊文件，如 `Dockerfile`/`Makefile` 时才编入索引）。写入端一致性：写入同一集合的每个进程都必须对此标志保持一致——混合配置会导致无扩展名代码块在交替运行时反复增删。
`MAX_FILE_SIZE_MB`	`5`	文件大小上限，单位为 MB。该值必须是完整的有限数字；格式不完整的值（例如 `5MB`）会被拒绝。索引时会跳过大于此值的文件。如果仓库中有希望编入索引的大型生成文件或数据文件，可提高此值。现有代码集合会保留其有效上限，直到重新编入索引。超过有效上限的文件会被移除旧代码块。
`MAX_CHUNK_CHARS`	`2000`	每个代码块的字符上限。对于以格式 2 编入索引的集合，超出上限的代码块会被拆分，而非截断：分块按行数切分（100 行），因此代码块可能超过按字符数计算的上限；若超过，溢出部分会成为后续代码块，而不会被丢弃。若存在换行符，普通代码块会在不超过上限的最后一个换行符处结束。对于压缩或打包代码，已发布的分块器还会考虑空格、制表符、分号和逗号边界，并尽可能避免在标识符内部拆分。如果没有符合条件的边界，该片段会在上限处结束。为保留代理对或 CRLF，边界可能移动一个 UTF-16 代码单元，因此上限为 `1` 时可能生成 2 个代码单元的片段。除只包含空白字符的片段外，不会丢弃任何内容。以格式 2 之前的格式编入索引的集合仍会截断——代码块存储前，上限之后的内容就会被丢弃，因此不会进入向量、载荷或关键词（BM25）文本。这种索引仍可正常使用，但覆盖范围可能已被截断；执行 `codebase_remove` 后再执行 `codebase_index` 可采用格式 2 并恢复被省略的内容，但并非必须这样做。如果嵌入模型的上下文小于默认值所假定的范围，请降低此上限。将上限提高到超过模型上下文长度 × 服务商每个 token 的字符数估值，并不会增加单个嵌入包含的内容：服务商会预先截断，因此额外字符会进入存储载荷和关键词（BM25）文本，但不会在向量中体现。现有代码集合和上下文集合会保留其有效上限，直到重新编入索引。
`SEARCH_DEFAULT_LIMIT`	`10`	`codebase_search` 默认返回的结果数（1-50）。每个结果都是经过排名的代码块，包含文件路径、行范围和内容。数值越高，覆盖范围越广，但输出也越多。仍可通过工具参数 `limit` 按查询覆盖。
`SEARCH_MIN_SCORE`	`0.10`	最低分数阈值（0-1）。低于此分数的结果会被过滤。可帮助去除搜索结果中的低相关性噪声。设置为 `0` 可禁用过滤（返回不超过 `limit` 的所有结果）。可通过工具参数 `minScore` 按查询覆盖。该设置与 `limit` 配合使用：先按分数过滤结果，再将结果数限制在 `limit` 以内。单项目搜索的分数为 RRF（倒数排名融合）值，跨项目搜索（`includeLinked: true`）的分数为余弦相似度；如果任何命中项无法计算余弦相似度，则回退到 RRF——关于分数尺度为何不同以及这对该阈值的影响，请参见下文的跨项目搜索。
`SOCRATICODE_PROJECT_ID`	(无)	覆盖自动生成的项目 ID。设置后，所有路径都会解析到相同的 Qdrant 集合，使多个目录（例如同一仓库的 git worktree）能够共用一个索引。必须符合 `[a-zA-Z0-9_-]+`。优先级高于 `.socraticode.json` 中的 `projectId` 字段。
`SOCRATICODE_BRANCH_AWARE`	`false`	设置为 `true` 时，会将当前 git 分支名称附加到项目 ID，为每个分支创建单独的 Qdrant 集合。如果设置了 `SOCRATICODE_PROJECT_ID`，或在 `.socraticode.json` 中设置了 `projectId`，则忽略此项。
`SOCRATICODE_LINKED_PROJECTS`	(无)	以逗号分隔的其他项目路径列表，包含在跨项目搜索中。会与 `.socraticode.json` 中的路径合并。不存在的路径会被静默跳过。
`SOCRATICODE_WATCHER`	`auto`	刷新策略，不区分大小写：`auto` 保留默认的文件监视器；`manual` 仅允许显式启动监视器；`off` 拒绝启动任何监视器；`git` 拒绝启动文件监视器，并在引用/HEAD 变更时刷新已激活的索引检出。在 `manual` 和 `off` 模式下，图查询不会创建缺失的图。无效值会导致启动失败。所有共用检出和索引的 MCP 进程都必须进行相同配置。无需重新编入索引。
`SOCRATICODE_AUTO_RESUME`	(无)	启动策略：未设置时，保留现有的当前项目追赶/恢复行为；`all` 会依次恢复所有具有已存储路径的已索引项目；`off` 会在访问 Docker 或 Qdrant 之前，跳过所有启动时的追赶更新和中断索引恢复。`off` 的优先级高于 `SOCRATICODE_AUTO_RESUME_PROJECTS`。这不会禁用后续工具使用触发的监视器启动；如需明确使用快照，请与 `SOCRATICODE_WATCHER=off` 配合。
`SOCRATICODE_AUTO_RESUME_PROJECTS`	(无)	以逗号分隔的项目路径列表，服务器启动时会依次自动恢复这些项目，例如 `/repos/api,/repos/web`。优先级高于未设置/`all` 时的行为，但低于 `SOCRATICODE_AUTO_RESUME=off`。不存在或尚未编入索引的路径会被跳过，并发出警告。
`SOCRATICODE_AUTO_CLEANUP`	(off)	仅设置为 `local`，以声明由主机独占管理的环回 Qdrant，并选择自动清理已确认退役且由本地拥有的 worktree/分支标识。未设置或设为 `off` 时，不执行自动清理。现有的非自有记录仍只会报告，不会清理。此项独立于自动恢复。参见可选的本地自动清理。
`SOCRATICODE_LOG_LEVEL`	`info`	日志详细程度：`debug`、`info`、`warn`、`error`
`SOCRATICODE_LOG_FILE`	(无)	日志文件的绝对路径。设置后，所有日志条目都会追加到此文件（每次服务器启动时都会写入会话分隔符）。当 MCP 宿主不显示日志通知时，可用于调试。

重要：运行时设置变更时，现有集合会保留其存储的有效提供方、模型和维度。codebase_status 会将请求的差异报告为待处理。要激活这些变更，请使用 codebase_remove 移除集合，然后使用 codebase_index 创建新索引。必须显式重建才能激活变更；继续使用现有索引则无需重建。

Docker 资源

SocratiCode 管理 Docker 容器和持久化卷：

资源	名称	用途	适用情况
容器	`socraticode-qdrant`	Qdrant 向量数据库（固定为 `v1.17.0`）	仅限 `managed` 模式
容器	`socraticode-ollama`	Ollama 嵌入服务	仅限 `docker` 模式
卷	`socraticode_qdrant_data`	持久化向量存储	仅限 `managed` 模式
卷	`socraticode_ollama_data`	持久化模型存储	仅限 `docker` 模式

在 QDRANT_MODE=external 模式下，不会创建或启动 Qdrant 容器和卷；SocratiCode 会直接连接到配置的远程端点。服务端 BM25 推理（用于混合搜索）要求使用 Qdrant v1.15.2 或更高版本。受管容器运行 v1.17.0。如果使用自有 Qdrant 实例，请确保其满足此最低版本要求。

所有容器均使用 --restart unless-stopped 自动恢复。

为什么使用非标准端口？ SocratiCode 有意为其受管容器使用非默认端口：Qdrant 使用 16333/16334，而非其默认端口（6333/6334）；Ollama 使用 11435，而非其默认端口（11434）。这样可以避免与本地可能已在运行的 Qdrant 或 Ollama 实例发生冲突。如有需要，所有端口均可通过环境变量覆盖。

测试

SocratiCode 拥有一套全面的测试套件，涵盖单元、集成和端到端测试。

前提条件

单元测试：无需外部依赖。
集成和 E2E 测试：需要运行 Docker，并包含 Qdrant 和 Ollama 容器。测试基础设施会自动管理这些容器。

运行测试

# Run all tests
npm test

# Run only unit tests (no Docker needed)
npm run test:unit

# Run integration tests (requires Docker)
npm run test:integration

# Run end-to-end tests (requires Docker)
npm run test:e2e

# Watch mode (re-runs on file changes)
npm run test:watch

# With coverage report
npm run test:coverage

测试架构

层级	需要 Docker？	说明
单元测试（`tests/unit/`）	否	配置、常量、忽略规则、跨进程锁定、日志记录、图分析、导入提取、路径解析、嵌入配置、索引器工具、嵌入、启动生命周期、监视器跨进程感知
集成测试（`tests/integration/`）	是	Docker/Ollama 设置、Qdrant CRUD、真实嵌入、索引器、监视器、代码图、所有 MCP 工具
E2E（`tests/e2e/`）	是	完整生命周期：健康检查 → 索引 → 搜索 → 图 → 监视 → 移除

需要 Docker 的集成测试和 E2E 测试会在 Docker 不可用时自动跳过。

为什么不直接用 Grep？

对真实代码库进行的现代评估显示，当你关注自然语言查询、大型代码库或编码 Agent 时，混合词法 + 语义代码搜索的表现始终优于纯 Grep：报告显示，BM25F 排序在大规模场景下可提升约 20% 的搜索质量；AST 感知检索可提高 RepoEval 和 SWE-bench 上的召回率及修复缺陷表现；而结合 Grep 的混合方法（SocratiCode 的默认配置）在 70% 的 Agent 代码搜索任务中优于 Grep，同时将搜索操作减少了一半以上。

真实场景基准测试：使用 Claude Opus 4.6 分析 VS Code（245 万行代码）

针对 VS Code 代码库（包含约 245 万行 TypeScript/JavaScript，分布在 5,300 多个文件中，索引了 55,437 个代码块）进行正面对比，衡量 Claude Opus 4.6 AI Agent 回答架构问题时实际会读取多少内容。

方法： 对于每个问题，grep 方案遵循 AI Agent 目前实际采用的多步工作流：使用 grep -rl 查找匹配的文件，确定核心文件，分块读取（每次 200 行），并重复此过程，直到获得足够的上下文。SocratiCode 方案只需调用一次语义搜索，即可从整个代码库中返回最相关的 10 个代码块。

问题	Grep（字节）	SocratiCode（字节）	减少比例	加速比
VS Code 如何实现工作区信任限制？	56,383	21,149	62.5%	49.7x
差异编辑器如何计算并显示文本差异？	37,650	15,961	57.6%	40.2x
VS Code 如何处理扩展激活及生命周期？	36,231	16,181	55.3%	34.4x
集成终端如何启动和管理 shell？	50,159	22,518	55.1%	31.1x
VS Code 如何实现命令面板和快速选取？	70,087	20,676	70.5%	31.7x
总计	250,510	96,485	61.5%	37.2x

主要发现：

工具调用减少 84% —— Grep 在 5 个问题中共需 31 步（每个问题 6-7 步）。SocratiCode：总计 5 步（每个问题 1 步）。
处理的数据减少 61.5% —— AI Agent 处理的上下文减少约 150 KB，从而直接降低使用任意大模型时的令牌成本。
速度提升 37 倍 —— Grep 扫描 245 万行代码，每个问题可能需要 2-3.5 秒。语义搜索最快仅需 60-90 毫秒。

注意： 这个基准测试对 grep 方案的估算_较为保守_。它假设 Agent 已经知道要读取哪些文件。在实际使用中，真正的 AI Agent 还需要额外调用 grep 进行探索、会遇到死胡同、会读取无关文件，而且通常需要多轮筛选。因此，实际节省可能更多。

混合搜索更胜一筹的场景

自然语言和概念性查询——例如 “我们在哪里处理数据库连接池？” 或 “这个库如何实现指数退避？” 这样的查询，描述的是行为，而不是函数名称。针对代码库级基准（RepoEval、SWE-bench）的评测显示，与固定行数分块相比，支持 AST 感知的语义检索可将召回率提高最多 4.3 个百分点，下游代码生成准确率提高约 2.7 个百分点。对真实开源代码库进行的 Agent 评测显示，在困难的概念性问题上，混合搜索相较于原生 grep 的胜率为 70%，搜索操作减少 56%，每个复杂查询减少约 60,000 个 token。

大型代码库和单体仓库——在数百万行代码的规模下，全文扫描会变得昂贵。生产级搜索引擎报告称，BM25F 排序相比先前方法可将相关性提高约 20%，并将其用作语义重排序的第一阶段检索器。由倒排索引和向量索引支持的混合搜索完全避免了全量扫描，因此在大规模场景下既更快也更精准。业内从业者明确指出，grep 和 find“无法很好地扩展到数百万个文件”，而经过优化的基于嵌入的索引在这种规模下可以更快。

跨文件和跨语言推理——要找出所有最终调用某个内部辅助函数的代码路径，或将自然语言规范映射到 Go 和 SQL 中的实现，需要具备超越字符串匹配的理解能力。评测显示，当命名不直观且需要语义理解时，采用 tree-sitter 解析和依赖上下文的混合搜索流水线优于 grep。基于 AST 的分块配合经过训练的检索器，可提升跨语言基准中的检索效果；在查询使用自然语言、目标涵盖多种语言的各类代码搜索任务（AppsRetrieval、CodeSearchNet、CosQA）中，多向量语义模型相比单独使用 BM25 也取得了显著提升。

代码与上下文资料混合的场景——“在哪里配置了速率限制？”这样的问题，可能匹配到 Nginx 配置、Terraform 文件或 YAML，而不仅仅是应用代码。在已发表的评测中，对混合技术语料（结构化字段和自由文本）进行的混合搜索始终优于纯词法搜索或纯向量搜索。

grep 仍然更胜一筹的场景

同一项研究也明确指出了 grep（或 ripgrep）完全合理、有时甚至是最佳选择的场景：

你知道确切的标识符、错误字符串或正则表达式模式。 无需弥合语义差距。
代码库规模适中——全量扫描成本低、速度快。
内容是有限且结构化的代码，并且名称具有辨识度，而不是散文或文档。

对于简单或直接命名的查询，grep 可以媲美甚至胜过语义方法。这就是为什么最好的架构不会取代 grep，而是对其进行扩展。SocratiCode 的混合搜索方法会对每个查询同时运行 BM25 关键词搜索和稠密语义搜索，再通过 RRF 融合结果，让你在一次调用中同时获得精确匹配的准确性和语义理解的召回率。

常见问题

索引时出错——我可以接着处理，而不用从头开始吗？

可以。索引会自动从上次停止的位置继续。索引器会在每批文件处理完成后，对文件哈希进行检查点记录。当你再次让 AI 建立索引时（例如 “为这个项目建立索引”），它会检测到现有数据，跳过所有已成功嵌入的文件，只重新处理之前失败时未记录检查点的文件。已建立索引的代码块绝不会被删除或重新嵌入。只需再次让 AI 建立索引，它就会从停止的位置继续。

对大型代码库编制索引时，MCP 主机断开连接了。该怎么办？

索引会在 MCP 服务后台运行。不过，某些 MCP 主机（VS Code、 Claude Desktop 等）会在一段时间无活动后断开空闲连接，从而终止后台进程。要保持连接，请在开始编制索引后，让 AI 大约每隔 60 秒检查一次状态（例如 “检查索引状态”），直到索引完成。如果连接确实断开，导致索引中断，只需让 AI 再次编制索引即可——系统会自动从中断处继续（见上文）。

索引总是失败或无法正常恢复。该怎么办？

如果索引反复失败、恢复时出错，或陷入循环，最简单的解决办法是从头开始：让 AI “移除此项目的索引”，然后让它再次编制索引。这会清除该项目的所有已存储分块和元数据，并开始重新编制索引。其他已编制索引的项目不会受到影响。

我的代码库非常大——可以暂停索引，以后再继续吗？

可以。你可以随时停止索引，并在之后继续，而不会丢失进度：

让 AI 助手停止——说类似 “停止编制索引” 的话，它会在下一个批次边界取消当前操作。到目前为止已完成的所有批次都会创建检查点并保留。
或者直接关闭项目／编辑器——SocratiCode 会检测到断开连接，并平稳关闭，同时保留所有已创建检查点的进度。
之后随时回来——在编辑器中重新打开同一项目，并让 AI 恢复编制索引（例如 “恢复编制索引”）。SocratiCode 会自动检测未完成的索引，跳过所有已嵌入的文件，并从停止的位置准确继续。

这样一来，即使硬件较慢，编制大型代码库的索引也切实可行——你可以在数小时或数天内分多次完成，而且不会重复或丢失任何工作。

我重新打开了项目，但搜索结果中没有显示新增／更改的文件。

在默认的 SOCRATICODE_WATCHER=auto 模式下，服务启动时会恢复 MCP 进程工作目录所对应的已编制索引项目。它会启动监视器，并在监视后续更改之前，补齐 SocratiCode 停止运行期间所有已修改文件的索引。使用 SOCRATICODE_AUTO_RESUME_PROJECTS 或 SOCRATICODE_AUTO_RESUME=all 可在启动时选择其他项目。启动时未被选中的、已完成索引的项目，会在首次搜索、状态查询或图交互时采用相同的后备方式启动监视器。

如果你想在搜索前立即强制补齐索引，请让 AI “开始监视此项目” 或 “更新索引”——这两种操作都会同步运行增量更新，然后启动监视器。

如果当前正在进行完整索引或增量更新、项目尚未编制索引，或另一个 MCP 进程已在监视同一项目，监视器不会自动启动。在 manual 或 off 模式下也不会自动启动。在这些模式下， codebase_status 和搜索输出会将索引标记为快照，而不是要求 Agent 重启监视器。

如果要完全采用有意管理的快照，请在使用该检出目录的每个 MCP 进程中同时设置 SOCRATICODE_WATCHER=off 和 SOCRATICODE_AUTO_RESUME=off。现有索引和图仍可读取，无需重新编制索引。运行 codebase_update 可刷新代码索引，运行 codebase_graph_build 可显式创建或重建图。如果需要临时显式监视，请改用 SOCRATICODE_WATCHER=manual。

如果你在多个已编制索引的代码仓库中工作，并希望服务器启动时恢复所有仓库（启动监视器并补齐索引），而不仅仅是你打开的那个，请参阅索引行为表中的 SOCRATICODE_AUTO_RESUME 和 SOCRATICODE_AUTO_RESUME_PROJECTS 环境变量。

Git 触发的刷新

设置 SOCRATICODE_WATCHER=git，即可在 MCP 服务运行期间，用固定的 10 秒 Git 状态检查替代持续文件监视。搜索、状态和图谱请求也会检查当前 ref 和 HEAD。提交、切换检出、快进、变基以及切换到同一提交的分支都会触发增量刷新；普通文件保存以及不会改变已检出 ref 和 HEAD 的 fetch 操作不会触发刷新。

Git 是触发条件，而不是内容来源：刷新会为工作树建立索引，包括未提交的编辑内容。如果需要在下一次 Git 状态变更前让这些编辑内容可供搜索，请运行 codebase_update。此模式下，codebase_watch 无法启动原生监视器。服务器的 PATH 中必须有 Git；如果找不到可执行文件或目录不是 Git 仓库，系统会显示诊断信息，且不会回退到文件监视器。非 Git 项目仍可显式建立索引。

只有在启动时选定或之后被工具使用的、已建立索引的检出目录才会受到监视。选择此模式不会为项目创建首个索引，也不会发现其他工作树。现有的启动项目选择设置仍然适用。SOCRATICODE_AUTO_RESUME=off 会禁止启动时追赶更新：之后的首次工具请求只会启动监视，不会将现有索引视为最新状态；显式更新或之后的 Git 状态变更会使索引更新至最新状态。

现有的共享身份和分支感知身份会继续保留。监视已建立索引的检出目录后，如果切换到尚未建立索引的分支，且启用了分支感知身份，系统可能会为该分支创建索引。分离 HEAD 遵循现有的基于路径的身份规则。显式项目 ID 仍具有优先权。

搜索和图谱结果会报告待处理、失败或未经验证的刷新。锁被占用、操作取消、刷新失败或刷新期间检出目录发生变化时，刷新都会保持待处理状态并重试；只有在稳定的状态下成功建立索引并完成图谱协调，才会报告为已同步。多个 MCP 进程会使用现有的跨进程写入锁。无需钩子、服务、持久化 Git 游标、迁移或重置索引。请确保所有进程的配置一致：其他进程中的文件监视器仍可能在文件保存时更新共享索引。同一主机上协作的进程必须对现有锁使用相同的操作系统临时目录。这些锁无法协调不同主机上的写入者；共享团队索引仍需要指定写入者。

多个 AI Agent 可以同时处理同一代码库吗？

可以——这是正式支持的工作流。多个 Agent（每个都运行自己的 MCP 服务实例）指向同一项目目录时，会自动共享同一个 Qdrant 索引。第一个触发索引的 Agent 会获取跨进程锁并建立索引；其他同时尝试建立索引的 Agent 会收到当前进度，而不会启动重复操作。所有 Agent 都可以并发搜索，无需协调——Qdrant 原生支持并行读取。

文件监视器也会自动协调：每个项目只有一个进程负责监视。其他实例会检测到这一点，并跳过启动监视器。负责监视的进程发现文件变更后，会更新共享索引；每个 Agent 在下一次搜索时都会看到更新后的结果。

如果拥有监视器或索引锁的 Agent 崩溃，其锁会在 2 分钟后失效，另一个 Agent 会在下一次交互时自动接管，无需手动干预。

因此，SocratiCode 非常适合多 Agent 工作流：一个 Agent 编写测试，另一个修复代码；一个规划 Agent 和一个实现 Agent 并行工作；或者任意组合的 AI 助手共享对代码库的深入了解，而无需重复劳动。

我可以同时为多个项目建立索引吗？

可以。SocratiCode 会为每个项目路径维护一个独立的隔离集合。让你的 AI “列出所有已建立索引的项目”，即可查看当前已建立索引的所有项目。

如果我更改嵌入提供方或模型，会发生什么？

每个集合都会记录创建索引时生效的提供方、模型、维度和查询行为。更改 MCP 配置中的这些设置不会影响现有集合。索引和搜索会继续使用集合中存储的配置文件，而 codebase_status 会将请求的设置报告为待处理状态。要启用新设置，请让你的 AI “移除此项目的索引”，然后重新为其建立索引。其他集合会继续使用各自的配置文件。

如何移除项目的索引（例如切换嵌入模型或从头重新建立索引）？

先停止 — 如果正在建立索引，请说 “停止为此项目建立索引”。在建立索引期间移除会损坏数据，因此当前批次完成之前，移除操作会被拒绝。
移除 — 说 “移除此项目的索引”。这只会删除该项目的向量集合、所有已存储的分块元数据、代码图和上下文制品元数据，不会影响其他项目。
重新建立索引 — 如有需要，使用新参数更新 MCP 配置，然后说 “为此项目建立索引”，即可重新开始。

SocratiCode 标志中苏格拉底头像背后的代码是什么？

你在苏格拉底头像背后看到的代码，是阿波罗 11 号制导计算机（AGC）命令舱（Comanche055）原始源代码的一部分！

社区

💬 Discord — 与用户和维护者交流，提问“如何……”，分享你正在构建的内容
🐛 GitHub Issues — 提交错误报告和已确认的功能请求（请使用模板）
📣 版本发布 — 关注此仓库（在 GitHub 右上角选择 → Custom → Releases），即可收到新版本通知

如果 SocratiCode 对你有帮助，你能做的最有帮助的一件事就是 ⭐ 为仓库点星 — 这能帮助其他人发现这个项目。

SocratiCode Cloud

完整的 SocratiCode 引擎采用 AGPL-3.0 许可，现为开源，并将始终保持开源。SocratiCode Cloud 是基于同一引擎的可选托管版本，目前处于私有测试阶段，面向需要共享、托管式、合规基础设施的团队。

Cloud 在开源引擎的基础上增加了以下功能：

共享团队索引 — 每位开发者都能搜索相同的数据；每次推送时，所有分支都会自动建立索引
跨仓库搜索 — 一次调用即可查询组织拥有的所有仓库
SSO / SAML、审计日志、IP 允许列表 — 内置提供，而非后续加价选项
部署模式 — 托管云（欧盟／美国）、自有 VPC（AWS/GCP/Azure），或完全隔离的本地部署
Web 控制面板 — 搜索、依赖关系图、制品、团队和仓库管理
无需本地基础设施 — 团队无需管理 Docker、Qdrant 或 Ollama

目前正在为少数工程团队办理接入。申请提前体验 →

本仓库中的开源引擎与驱动 Cloud 的引擎完全相同，而且将始终如此。没有诱导后变卦，也不会限制开源核心的功能。Cloud 只是在其基础上增加团队、部署和合规层。

许可证

SocratiCode 采用双重许可：

开源 — AGPL-3.0。可免费使用、修改和分发。如果你修改 SocratiCode 并将其作为网络服务提供，则必须根据 AGPL-3.0 发布你的修改。
商业许可 — 面向需要在专有产品或服务中使用 SocratiCode，且不希望承担 AGPL 义务的组织。请参阅 LICENSE-COMMERCIAL 或联系 [email protected]。

第三方许可证

SocratiCode 包含采用各自许可证（MIT、Apache 2.0、ISC、BSD 3-Clause）的开源依赖项。详情请参阅 THIRD-PARTY-LICENSES。

贡献

欢迎贡献。提交拉取请求即表示您同意贡献者许可协议。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Socraticode

关于 Socraticode

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

SocratiCode

目录

快速开始

让 SocratiCode 保持最新

插件和宿主集成

Claude Code 插件（推荐 Claude Code 用户使用）

固定引擎版本

Claude Code 仅 MCP 安装

OpenAI Codex 插件

OpenAI Codex 仅 MCP 安装

VS Code Agent 插件

VS Code 编辑器扩展

VS Code 直接安装 MCP

Cursor

Gemini CLI

Continue

Cline

Zed

OpenCode

其他本地 stdio MCP 宿主

为什么选择 SocratiCode

内置代码搜索与 SocratiCode 对比

功能

前置条件

macOS / Windows 上的嵌入性能

示例工作流

Agent 指令

配置

安装

从源代码安装（适用于贡献者）

MCP 宿主配置变体

默认（零配置，源码运行）

外部 Ollama（原生安装）

远程 Ollama 服务

OpenAI 嵌入

Google Generative AI 嵌入

LM Studio（本地，兼容 OpenAI）

LiteLLM（代理网关，100+ 个提供商）

Git Worktrees（跨目录共享索引）

支持检测 git worktree 的 MCP 宿主（例如 Claude Code）

其他 MCP 宿主（每个项目一个 .mcp.json）

工作原理

团队共享索引（提交 projectId）

跨项目搜索（关联项目）

配置

用法

Python 导入根目录

分支感知索引

回收已存储的身份

可选的自动本地清理

可用工具

索引

搜索

代码图谱

影响分析（符号级调用图）

交互式图谱探索器

管理

上下文制品

语言支持

完整支持（索引 + 代码图谱 + AST 分块）

有条件的 AST 支持

基于正则表达式和索引的代码图谱

仅索引（混合搜索，按行分块）

忽略规则

上下文资源

设置

工作原理

用法

为什么这很重要：实际工作流示例

示例制品

环境变量

按宿主传递环境变量

其他 MCP 宿主（每个项目一个 `.mcp.json`）

团队共享索引（提交 `projectId`）

Ollama 配置（当 `EMBEDDING_PROVIDER=ollama` 时）

LM Studio 配置（当 `EMBEDDING_PROVIDER=lmstudio` 时）

LiteLLM 配置（当 `EMBEDDING_PROVIDER=litellm` 时）