Socrati Code

社会法典

= 18">

*“只有一种善，即知识，还有一种恶，即无知。”* --苏格拉底

你的AI会读取代码。SocratiCode理解这一点。

开源代码库上下文引擎：为任何AI提供整个代码库（和基础设施）的即时自动化知识——大规模、零配置、完全私有、完全免费。

Kindly sponsored by Altaire Limited

🛡️ 需要MCP治理和代码库上下文吗？ 查看我们的兄弟项目 JanuScope --本地第一MCP策略代理：工具阻塞、SQL变异门、PII编辑、审计、速率限制。

如果SocratiCode对您有用，请⭐ 为这个回购加星 --它可以帮助其他人发现它，并与您的开发团队和其他开发人员分享！ 💬 有问题还是只是想聊天？加入我们 Discord 的中文翻译是“不和谐”或“纷争”。.

☁️ SocratiCode Cloud（私人测试版） --托管、共享的团队索引构建在与开源版本相同的引擎上，加上SSO、审计日志、分支感知索引和VPC/气隙部署选项。开源核心永远是免费的。 请求提前访问→

有一件事做得很好：深度代码库智能——零设置，无膨胀，全自动。 SocratiCode为AI助手提供了对代码库的深入语义理解-- 混合搜索、跨项目搜索、多语言代码依赖关系图、符号级影响分析和流、用于视觉导航的交互式HTML图资源管理器，以及可搜索的上下文工件（数据库架构、API规范、基础设施配置、架构文档）.Zero配置--将其添加到 任何MCP主机，或安装 本机插件 适用于Claude Code、Cursor、VS Code Copilot、Codex或Gemini CLI。它自动管理一切。

生产就绪，战斗考验 企业级 大型存储库（最多和超过 约4000万行代码). 批量，自动 可恢复的 索引检查点进度——暂停、崩溃、重新启动和中断不会丢失工作。文件监视器会保持 索引自动更新 在每次文件更改和会话之间。 多分支、多回购 和 多代理就绪 --多个AI代理可以同时处理同一代码库，共享一个索引，自动协调，零配置。

默认情况下为私有和本地 -Docker处理一切，无需API密钥，无需数据离开您的机器。 云就绪 用于嵌入（OpenAI、Google Gemini）和Qdrant，以及 全套配置选项 当你需要的时候，它们都是可用的。

属于您的代码智能，与AI和主机无关 --你的代码库的理解与代码息息相关，而不是锁定在任何一个助手、IDE或模型上。由于SocratiCode预先计算了硬部分（爆炸半径、调用流、依赖遍历）， 较小的模型可以处理架构复杂的任务，否则这些任务需要顶层推理，进一步节省代币成本。

第一个基于Qdrant的MCP/Claude Plugin/Skill，将自动管理、零配置的本地Docker部署与 AST感知代码分块、混合语义+BM25（RRF融合）代码搜索，多语言依赖 图表 通过循环依赖可视化， 符号级影响分析 （18种语言的爆炸半径和呼叫流跟踪），可搜索 基础设施/API/数据库工件 在一个专注、零配置、易于使用的代码智能引擎中。

以VS代码为基准（245万行）： SocratiCode使用 上下文减少61%, 工具调用减少84%，并且是 快37倍 基于grep的探索——用Claude Opus 4.6进行了现场测试。 查看完整的基准测试→

目录

• 快速开始
• 插件
• 为什么选择SocratiCode
• 特性
• 先决条件
• 工作流示例
• 代理说明
• 配置
• 语言支持
• 忽略规则
• 上下文伪影
• 环境变量
• 测试
• 为什么不只是Grep？
• 常见问题
• 社区
• SocratiCode云
• 许可证

______________________________________________________________________

快速开始

仅 码头工人 （跑步）是必需的。

一键安装 --克劳德码、VS码和游标：


所有MCP主机 --将以下内容添加到您的 mcpServers （Claude Desktop、Windsurf、Cline、Roo Code）或 servers （VS代码项目本地 .vscode/mcp.json)配置：

"socraticode": {
  "command": "npx",
  "args": ["-y", "socraticode"]
}

克劳德代码 --安装插件（推荐，包括工作流程技能以获得最佳效果）：

从你的壳：

claude plugin marketplace add giancarloerra/socraticode
claude plugin install socraticode@socraticode

或者从克劳德代码中：

/plugin marketplace add giancarloerra/socraticode
/plugin install socraticode@socraticode

自动更新： 安装后，通过打开启用自动更新 /plugin → 市场→ 选择 socraticode → 启用自动更新。

或者仅作为MCP（无技能）：

claude mcp add socraticode -- npx -y socraticode

正在更新： npx 在第一次运行后缓存包。要获取最新版本，请清除缓存并重新启动MCP主机： rm -rf ~/.npm/_npx && claude mcp restart socraticode。或者，使用 npx -y socraticode@latest 在您的配置中，始终在启动时检查更新（稍慢）。

开源代码 --添加到您的 opencode.json （或 opencode.jsonc):

{
  "mcp": {
    "socraticode": {
      "type": "local",
      "command": ["npx", "-y", "socraticode"],
      "enabled": true
    }
  }
}

OpenAI Codex命令行界面 --添加到 ~/.codex/config.toml:

[mcp_servers.socraticode]
command = "npx"
args = ["-y", "socraticode"]

重新启动主机。首次使用时，SocratiCode会自动提取Docker镜像，启动自己的Qdrant和Ollama容器，并下载嵌入模型——一次性设置，约5分钟，具体取决于您的连接。之后，它将在几秒钟内开始。

首次参与项目 --问你的AI： “索引此代码库”.索引在后台运行；问 “代码库索引状态是什么？” 以监控进展。根据代码库大小以及您是使用GPU加速的Ollama还是云嵌入，首次索引可能需要几秒钟到几分钟的时间（在Macbook Pro M4上首次索引+300万行代码需要不到10分钟的时间）。一旦完成，就不需要再次运行，您可以搜索、探索依赖关系图和查询上下文工件。

每次之后 --只需使用工具（搜索、图表等）。在服务器启动时，SocratiCode会自动检测以前索引的项目，重新启动文件监视器，并运行增量更新以捕获服务器停机时所做的任何更改。如果索引中断，它将从最后一个检查点自动恢复。您还可以使用以下命令显式启动或重新启动观察器 codebase_watch { action: "start" }.

推荐：为了获得最佳效果，请添加 代理说明 到AI助手的系统提示或项目说明文件(CLAUDE.md, AGENTS.md等等）。关键原则-- 阅读前搜索 --帮助您的AI有效地使用SocratiCode的工具，避免不必要的文件读取。

Claude Code用户：如果您安装了SocratiCode插件，则Agent指令会自动作为技能包含在内，无需将其添加到您的 CLAUDE.md该插件还捆绑了MCP服务器，因此您不需要单独的 claude mcp add.

高级：云嵌入（OpenAI/Google）、外部Qdrant、远程Ollama、本地Ollama和数十种调优选项都可用。看 配置 在......下面

插件

SocratiCode是多个AI编码平台上的原生插件。插件将MCP服务器与工作流技能和代理说明捆绑在一起——一次安装就可以提供一切。

扩展与插件（在vs代码/游标中安装什么）： - 这 扩展 （Marketplace/Open VSX列表）是一个常规的VS Code风格的扩展。它在Copilot代理模式、Cline、Continue、Roo Code中自动注册MCP服务器，并添加侧边栏、状态栏项、交互式图形Web视图、漫游和调色板命令。最适合大多数用户。 - 这 插件 (/add-plugin 对于光标， Chat: Install Plugin From Source 对于VS代码副本）捆绑MCP服务器 加上技能+代理说明 教人工智能有效地使用SocratiCode工具。最好是当你想让代理人对使用SocratiCode固执己见时。 - 您可以同时安装这两个。扩展只注册MCP服务器一次，因此它们不会冲突。 - VS代码副本注释：聊天插件功能正在预览中。启用它 chat.plugins.enabled: true 在您的VS代码设置中。

Codex本地插件安装：克隆仓库并在您的个人插件市场中注册： ``bash git clone https://github.com/giancarloerra/socraticode.git ~/.agents/plugins/socraticode ` 然后将其添加到 ~/.agents/plugins/marketplace.json: `json { "plugins": [ { "name": "socraticode", "path": "~/.agents/plugins/socraticode" } ] } ` Codex将从以下位置发现该插件 .codex-plugin/plugin.json` 下次发射时。

所有其他MCP主机 （Claude Desktop、Windsurf、Cline、Roo Code、OpenCode）：使用 MCP配置 --适用于支持MCP协议的任何主机。

为什么选择SocratiCode

我创建SocratiCode是因为我经常在不同语言的现有、大型和复杂的代码库上工作，需要快速理解它们并采取行动。现有的解决方案要么太有限，要么在生产使用中测试不足，要么因不必要的复杂性而臃肿。我想要一个专注于深度代码库智能的工具——零设置、无膨胀、全自动——并且不碍事。

内置代码搜索与SocratiCode

🔌 上下文与你的代码库共存，而不是与助手共存。 内置索引（Cursor、Copilot）绑定到一个工具——切换助手，然后从头开始。SocratiCode是独立的：索引一次，然后将其插入Claude Code、Cursor、Copilot、Windsurf、您自己的私有模型，或同时插入所有这些模型。他们对你的代码有着相同的理解。

在VS Code的2.45M行代码库中，SocratiCode通过以下方式回答架构问题 数据减少61%, 步数减少84%，以及 快37倍 与基于grep的AI代理相比。 完整基准测试→

特性

• 混合代码搜索 --基于Qdrant构建，Qdrant是一个专门构建的向量数据库，具有HNSW索引、并发读/写和有效载荷过滤功能。每个块都存储一个密集向量和一个BM25稀疏向量；查询API在单个往返行程中运行两个子查询，并将结果与倒数秩融合（RRF）融合。语义搜索处理概念查询，如“身份验证中间件”，即使这些确切的单词没有出现在代码中。BM25处理精确的标识符和关键字查找。在每个查询中，您都可以获得两者的最佳效果，而无需进行调优。
• 可配置Qdrant --使用内置的Docker Qdrant（默认，零配置）或连接到您自己的实例（自托管、远程服务器或Qdrant云）。通过配置 QDRANT_MODE, QDRANT_URL，以及 QDRANT_API_KEY 环境变量。
• 可配置的Olama --使用内置的Docker Ollama（默认，零配置）或指向您自己的Ollama实例（本地安装-GPU访问-远程服务器等）。通过配置 OLLAMA_MODE, OLLAMA_URL, EMBEDDING_MODEL 和 EMBEDDING_DIMENSIONS 环境变量。
• 多提供商嵌入 --在本地Ollama（私有，GPU访问）、Docker Ollama、OpenAI之间切换(text-embedding-3-small，最快），谷歌双子座(gemini-embedding-001，免费层）、LM Studio（本地OpenAI兼容服务器）或LiteLLM（100多个提供商前的代理网关），具有单个环境变量。没有特定于提供程序的配置文件。
• 私密且安全 -一切都在你的机器上运行-你的代码永远不会离开你的网络。默认的Docker设置包括Ollama（嵌入）和Qdrant（矢量存储），没有外部API调用。没有API成本，没有代币限制。适用于气隙和现场环境。可选的云提供商（OpenAI、Google Gemini、Qdrant cloud）可用，但从未被要求。
• AST感知分块 --使用AST解析（AST-grep）在函数/类边界处分割文件，而不是任意行数。这会产生更高质量的搜索结果。对于不支持的语言，回到基于行的分块。
• Polyglot代码依赖关系图 --使用ast grep对18种以上语言的import/require/use/include语句进行静态分析。不需要依赖性巡洋舰等外部工具。检测循环依赖关系并生成可视化美人鱼图。
• 语言不可知论 --适用于所有编程语言、框架和文件类型。无需安装每种语言的解析器，无需维护语法文件，也没有“不受支持的语言”限制。如果你的AI可以读取它，SocratiCode可以对其进行索引。
• 增量索引 --在第一个完整索引之后，只有更改的文件才会被重新处理。内容哈希值保存在Qdrant中，因此状态在服务器重启后仍然有效。
• 批量和可恢复索引 --文件以50个为一批处理，每批处理后进度检查指向Qdrant。如果进程崩溃或中断，下一次运行会自动从中断的地方继续——通过哈希比较跳过已经索引的文件。这使得峰值内存保持较低水平，即使对于非常大的代码库，索引也很可靠。
• 实时文件观看 --可以选择监视文件更改并实时更新索引（取消2秒）。Watcher还会使代码图缓存无效。
• 并行处理 --文件以并行批处理（一次50个）进行扫描和分块，以实现快速I/O，而嵌入生成和追加处理则分别进行批处理，以实现最佳吞吐量。
• 多项目 --同时索引多个项目。每个项目都有自己的独立集合，并有完整的项目路径跟踪。
• 跨项目搜索 --在单个查询中搜索多个相关项目。通过链接项目 .socraticode.json 或 SOCRATICODE_LINKED_PROJECTS env var，然后设置 includeLinked: true 上 codebase_search结果用项目标签标记，并通过客户端RRF融合进行重复数据消除。
• 分支感知索引 --通过设置来维护每个git分支的单独索引 SOCRATICODE_BRANCH_AWARE=true每个分支都有自己的Qdrant集合，因此切换分支会立即切换到正确的索引。非常适合CI/CD管道和PR审查工作流程。
• 尊重忽略规则 --荣誉全部 .gitignore 文件（根+嵌套），加上可选 .socraticodeignore 其他除外责任。包括合理的内置默认值。 .gitignore 可以通过以下方式禁用处理 RESPECT_GITIGNORE=false.Dot目录（例如。 .agent)可以通过以下方式包含 INCLUDE_DOT_FILES=true.
• 自定义文件扩展名 --具有非标准扩展的项目（例如。 .tpl, .blade)可以通过以下方式包含 EXTRA_EXTENSIONS env变量或 extraExtensions 刀具参数。适用于索引和代码图。
• 可配置的基础设施 -所有端口、主机和API密钥都可以通过环境变量进行配置。Qdrant API对企业部署的关键支持。
• 企业就绪的简单性 --没有代理协调调优，没有内存限制环境变量，没有协调器/导体容量旋钮，没有背压配置。SocratiCode的扩展依赖于生产级基础设施（Qdrant，经过验证的嵌入式API），而不是复杂的进程内编排。
• 自动设置和零配置 --只需安装Claude插件/Skill或将MCP服务器添加到您的AI主机配置中。首次使用时，服务器会自动检查Docker，提取映像，启动Qdrant和Ollama容器，并下载嵌入模型。无需配置文件，无需YAML，无需调整环境变量，无需编译本机依赖项。适用于Docker运行的任何地方。
• 会话恢复 --重新打开以前索引的项目时，文件查看器会在首次使用工具（搜索、状态、更新或图形查询）时自动启动。它捕获自上次会话以来所做的任何更改，并保持索引处于活动状态，无需手动操作。
• 自动启动监视器 --当您在索引项目上使用任何SocratiCode工具时，文件监视器会自动激活。它开始于 codebase_index 完成后 codebase_update，在第一个 codebase_search, codebase_status，或图形查询。您还可以手动启动它 codebase_watch { action: "start" } 如果需要的话。
• 自动构建代码图 --代码依赖关系图在索引后自动构建，并在观察到的文件发生变化时重建。无需致电 codebase_graph_build 手动，除非您想强制重建。
• 多Agent协作 --多个AI代理（每个都运行自己的MCP实例）可以同时处理同一个代码库并共享一个索引。一个代理触发索引，所有代理针对相同的数据进行搜索。每个项目只运行一个观察者——每个代理都受益于实时更新。跨进程文件锁定坐标自动索引和监视。非常适合一个代理编写测试而另一个代理修复代码，或者计划代理和实现代理并行工作的工作流。
• 跨过程安全 --基于文件的锁定(proper-lockfile)防止多个MCP实例同时索引或监视同一项目。来自崩溃进程的过期锁会自动回收。当另一个MCP进程已经在监视项目时， codebase_status 报告“活动（由另一个进程监视）”，而不是错误地显示“非活动”
• 并发防护 --防止重复索引和图构建操作。如果你打电话 codebase_index 当索引已经运行时，它返回当前进度，而不是开始第二个操作。
• 优雅停止 --长时间运行的索引操作可以通过以下方式安全停止 codebase_stop。当前批处理完成并检查点，保留所有进度。重新运行 codebase_index 从中断的地方继续。
• 平滑关闭 --在服务器关闭时，活动索引操作最多需要60秒才能完成，所有文件监视器都会干净地停止，一切都会优雅地关闭。
• 结构化日志记录 --所有操作都记录在结构化上下文中，以便于观察。日志级别可通过以下方式配置 SOCRATICODE_LOG_LEVEL.
• 优雅降级 --如果基础设施在监视期间发生故障，监视器会退出并重试，而不是崩溃。

先决条件

Docker必须 跑步 在默认情况下使用服务器时 managed 模式。

Qdrant容器是自动管理的。如果你设置 QDRANT_MODE=external 和点 QDRANT_URL 在远程或云Qdrant实例中，在这种情况下，Ollama（嵌入）只需要Docker。

默认情况下，Ollama容器（嵌入）也会自动管理 auto 模式。SocratiCode首先检查Ollama是否已经在本地运行——如果是的话，它会使用它。否则，它会为您管理一个Docker容器。docker镜像或嵌入模型的首次下载可能需要几分钟，具体取决于您的互联网速度，并且仅在首次启动时才需要。

在macOS/Windows上嵌入性能

macOS和Windows上的Docker容器无法访问GPU（没有Metal或CUDA passthrough）。对于小型项目来说，这很好，但对于中大型代码库来说，仅使用CPU的容器明显较慢。

为了获得最佳性能，请安装本地Ollama： 从下载并运行安装程序 ollama.com/下载Ollama运行后，SocratiCode将自动检测并使用它，无需额外配置（首次下载嵌入模型，如果不存在，可能需要几分钟）。这为您提供了macOS上的Metal GPU加速和Windows/Linux上的CUDA加速。

如果您更喜欢无需本地安装的速度，请参阅 OpenAI嵌入 和 谷歌生成的人工智能嵌入 下面是基于云的选项。OpenAI非常快，不需要本地设置。谷歌的免费套餐功能齐全，但价格有限。看 环境变量 有关配置详细信息。

工作流示例

所有工具默认 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]

代理说明

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

为了获得最佳效果，请将以下说明添加到AI助手的项目级说明文件中。核心原则： 阅读前搜索该索引以毫秒为单位为您提供代码库的映射；原始文件读取既昂贵又消耗上下文。

在哪里放置这些说明 （每个IDE）：

为什么这很重要：单独安装MCP服务器可以让您的代理访问SocratiCode工具，但代理仍然决定何时使用它们。将这些说明添加到您的项目中，可以确保代理始终更喜欢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 调用以毫秒为单位返回整个代码库中经过排序和重复数据消除的片段。这为您提供了一个可以忽略不计的令牌成本的广阔地图，比推测性地打开文件便宜得多。一旦你知道哪些文件很重要，有针对性的阅读就会更快、更准确。也就是说，当你有一个精确的字符串或模式时，grep仍然是正确的工具——使用任何适合查询的工具。

在索引过程中保持连接活动。 索引在后台运行——即使没有主动响应工具调用，MCP服务器也会继续工作。但是，一些MCP主机可能会在一段时间不活动后断开空闲的MCP连接，这可能会切断后台进程。指示您的AI呼叫 codebase_status 启动后大约每60秒一次 codebase_index 直到它完成。这将使主机连接保持活动状态并提供实时进度。

配置

安装

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

SocratiCode插件将MCP服务器和工作流技能捆绑在一起，教Claude如何有效地使用这些工具。一次安装即可提供一切：

从你的壳：

claude plugin marketplace add giancarloerra/socraticode
claude plugin install socraticode@socraticode

或者从克劳德代码中：

/plugin marketplace add giancarloerra/socraticode
/plugin install socraticode@socraticode

该插件包括：

• MCP服务器 --所有21个SocratiCode工具（搜索、图形、上下文工件等）
• 勘探技能 --教克劳德阅读前的搜索工作流程
• 管理技能 --指导设置、索引、观察和故障排除
• Explorer代理 --用于深度代码库分析的可委托子代理

如果您之前将SocratiCode安装为独立的MCP(claude mcp add socraticode)，安装插件后将其删除以避免重复： claude mcp remove socraticode

自动更新： 默认情况下，第三方插件不会自动更新。要启用自动更新，请打开 /plugin → 市场→ 选择 socraticode → 启用自动更新。要手动更新，请执行以下操作：

从你的壳：

claude plugin marketplace update socraticode
claude plugin update socraticode@socraticode

或者从克劳德代码中：

/plugin marketplace update socraticode
/plugin update socraticode@socraticode

配置环境变量： SocratiCode适用于大多数用户的零配置（本地Ollama+托管Qdrant）。如果你需要云嵌入、远程Qdrant或其他定制：

1. 克劳德代码设置 （推荐）--添加到 ~/.claude/settings.json:

   {
     "env": {
       "EMBEDDING_PROVIDER": "openai",
       "OPENAI_API_KEY": "sk-..."
     }
   }

这适用于所有环境——CLI、VS Code和JetBrains。

1. 外壳外形 --设置变量 ~/.zshrc 或 ~/.bashrc:

   export EMBEDDING_PROVIDER=openai
   export OPENAI_API_KEY=sk-...

当Claude Code从终端启动时工作。注意：IDE启动的会话（例如从Finder/Dock打开的VS代码）可能不会继承shell配置文件变量——请改用选项1。

更改变量后重新启动Claude代码。看 环境变量 对于所有选项。

npx（建议用于所有其他MCP主机，无需安装）

需要Node.js 18+和Docker（正在运行）。已覆盖 快速开始 在上面，将以下内容添加到您的 mcpServers （Claude Desktop、Windsurf、Cline、Roo Code）或 servers （VS代码项目本地 .vscode/mcp.json)配置：

    "socraticode": {
      "command": "npx",
      "args": ["-y", "socraticode"]
    }

泽德

在Zed的设置中添加SocratiCode作为自定义MCP服务器(Zed > Settings > Settings 或 cmd+,).在...之下 context_servers，添加：

{
  "context_servers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "socraticode"],
      "env": {}
    }
  }
}

要传递环境变量（例如用于云嵌入或分支感知索引），请将它们添加到 env 对象：

{
  "context_servers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "socraticode"],
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Zed自动读取 AGENTS.md 从项目根获取代理指令。复制 代理说明 阻止您的项目 AGENTS.md 以确保代理有效地使用SocratiCode工具。您还可以将它们添加为Zed规则库中的默认规则(agent: open rules library).

来源（供贡献者使用）

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

然后使用 node /absolute/path/to/socraticode/dist/index.js 代替 npx -y socraticode 在下面的配置示例中。

MCP主机配置变体

全部 env 以下选项同样适用于 npx 安装。只需添加 "env" 阻塞上面显示的npx配置。

添加到MCP设置- mcpServers （Claude Desktop、Windsurf、Cline、Roo Code）或 servers （VS代码项目本地 .vscode/mcp.json):

默认值（零配置，来自源代码）

使用 npx？您的配置已在 快速开始.添加任何 "env" 根据需要，从以下示例中删除。

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

小贴士：默认值 OLLAMA_MODE=auto 在启动时检测本地Ollama（端口11434），如果可用，则使用它，否则回退到托管Docker容器。要使您的配置自文档化，请添加 "env" 具有明确值的块。看 环境变量 对于所有选项。

外部Ollama（本地安装）

如果你有 奥拉玛 本机安装，set 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的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 工作室 附带一个本地服务器，该服务器公开了与OpenAI兼容的 API开启 http://localhost:1234/v1。当您想托管嵌入模型时，请使用此提供程序 在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工作室 没有现成的嵌入模型；您可以在“本地服务器”选项卡中自己加载一个。SocratiCode 如果其中任何一个丢失，都会很快失败。 可选： LMSTUDIO_URL （默认值 http://localhost:1234/v1)对于非默认端口； LMSTUDIO_API_KEY 如果您已经在LM Studio中启用了API密钥身份验证。

LiteLLM（代理网关，100多家提供商）

轻量级LLM 代理服务器公开了一个与OpenAI兼容的 /v1/embeddings 端点和扇出到100多个底层提供商（OpenAI、Anthropic、Adobe等）中的任何一个， 《科赫尔》、《航海》、《拥抱的脸》、《基岩》、《顶点AI》、《奥利玛》。..).在需要时使用此提供程序 集中密钥管理 （每个开发人员一个虚拟密钥，而不是分散的N个提供商密钥 跨MCP配置）， 回退/负载平衡 在嵌入后端之间，或 与提供者无关的索引 在后端交换中幸存下来。

{
  "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后端拒绝请求）。

Git工作树（跨目录共享索引）

如果你使用 git工作树 --或者同一存储库位于多个目录中的任何工作流——每个路径通常都有自己的Qdrant索引。这意味着对本质上相同的代码库进行冗余嵌入和存储。

集 SOCRATICODE_PROJECT_ID 在同一项目的所有目录中共享一个索引。

具有git工作树检测功能的MCP主机（例如Claude Code）

一些MCP主机（如 克劳德代码)通过以下git工作树链接解析项目根。由于工作树指向主存储库 .git 目录，主机会自动将所有工作树映射到相同的项目配置。这意味着您只需配置MCP服务器 一次 对于主签出，所有工作树都会自动继承它。

对于Claude Code，从主签出中添加具有本地作用域的服务器：

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

从该仓库创建的所有工作树都将使用共享项目ID自动连接到socraticode。不需要为每个工作树设置。

注： 这只适用于git工作树。分开 git clone同一回购的s具有独立性 .git 目录，不会共享配置。

其他MCP主机（每个项目 .mcp.json)

对于不解析git工作树路径的MCP主机，添加一个 .mcp.json 在每个工作台的根部（以及您的主结账台）：

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

添加 .mcp.json 致你的 .gitignore 如果你不想被追踪。

运作原理

使用此配置，运行中的代理 /repo/main, /repo/worktree-feat-a，以及 /repo/worktree-fix-b 都是一样的 codebase_my-project, codegraph_my-project，以及 context_my-project Qdrant系列。

它在实践中是如何工作的：

• 语义索引反映了上一次触发文件更改的工作树，但由于分支通常只相差少数文件，因此该索引对所有工作树的准确率为99%以上
• 您的AI代理从其自己的工作树读取实际文件内容；共享索引仅用于发现和导航
• 当更改合并回main时，文件监视器会对更改的文件重新索引，索引会收敛

团队共享索引（已提交 projectId)

上面的env-var方法适用于每台机器。对于每个队友（和CI跑者）自动获取的稳定标识符，请提交 projectId 在 .socraticode.json 在项目根：

{
  "projectId": "my-project"
}

现在，任何对仓库的签出——无论它位于磁盘的哪个位置，也不管它属于哪个用户帐户——都会指向相同的地址 codebase_my-project, codegraph_my-project，以及 context_my-project Qdrant系列。这是共享Qdrant实例的团队的推荐设置：索引是一次性构建的，对每个人都有好处，即使是在不同的操作系统用户和具有完全不同文件系统布局的笔记本电脑之间。

该值必须匹配 [a-zA-Z0-9_-]+；空格被修剪，缺失或为空的值将恢复为路径哈希默认值。这 SOCRATICODE_PROJECT_ID env-var在设置时优先于此文件，这对于每台机器的ad-hoc覆盖非常方便，而无需触及repo。

跨项目搜索（链接项目）

如果您在多个相关的存储库或包中工作，则可以在单个查询中搜索它们。

配置

创建一个 .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:

使用includeLink:true搜索“身份验证中间件”

结果标记为 [project-name] 标签显示每个结果来自哪个项目。当前项目始终具有最高的重复数据删除优先级——如果同一文件存在于多个链接的项目中，则当前项目的版本获胜。

注： 每个链接的项目都必须独立索引(codebase_index)在可以搜索之前。

分支感知索引

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

适用于您需要的工作流程 每个分支都有单独的持久索引 --例如CI/CD管道或跨分支比较代码——启用分支感知模式：

SOCRATICODE_BRANCH_AWARE=true

启用此选项后，集合名称包括分支名称（例如。 codebase_abc123__main, codebase_abc123__feat_my-feature).每个分支都维护自己的独立索引、代码图和上下文工件。

何时使用：

• 分别索引每个分支/PR的CI/CD管道
• 跨分支比较搜索结果
• 保持原始状态 main 索引不受特征分支更改的影响

何时不使用：

• 本地开发，频繁切换分支（默认共享索引更高效）
• 通过以下方式跟踪项目 SOCRATICODE_PROJECT_ID （显式ID绕过分支检测）

它是如何工作的： projectIdFromPath() 通过以下方式检测当前的git分支 git rev-parse --abbrev-ref HEAD 并附加一个经过净化的分支后缀（例如。 feat/my-feature → feat_my-feature)到基于哈希的项目ID。分离的HEAD状态回退到无分支ID。

可用工具

连接后，您的AI助手可以使用21个工具：

索引

搜索

代码图

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

第二个图层比文件导入更深入一步——它跟踪哪些函数 方法调用which。在重构、重命名或删除代码之前使用这些工具。

可接受的限制。 调用图是基于静态分析的，没有类型推理。动态调度(getattr, obj[key](...)、反射， eval)、未展开的宏和框架魔术（Spring @Autowired，角DI，Rails has_many，装饰器驱动的路由）是不可见的。仅通过这些机制到达方法的调用者将不会出现在 codebase_impact.将“零调用者”视为对DI密集型代码库进行双重检查的提示。 codebase_graph_status 报告 unresolvedEdgePct 作为质量信号。看 开发商.md§影响分析 查看完整列表。

交互式图形浏览器

问你的AI *“显示此项目的交互式图形”* （或援引 codebase_graph_visualize 随着 mode: "interactive")SocratiCode生成一个自包含的HTML页面，并在默认浏览器中打开它：

• 文件视图 --每个源文件都作为一个节点，以边的形式导入，语言颜色为红色，圆形deps为红色。
• 符号视图 --切换以将函数/类/方法视为具有调用边的节点（当符号图符合嵌入上限时可用；高于该阈值时，文件视图保持不变，横幅指向 codebase_impact 用于符号级查询）。
• 侧边栏 --单击节点可以查看文件/行号中的导入/依赖项/符号，以及爆炸半径和调用流的操作按钮。
• 右键单击任何节点 → 突出显示其反向传递闭包（如果此情况发生变化，谁会打破）。
• 实时搜索 过滤器和中心匹配节点。 布局切换器 --Dagre/力导向/同心/宽度优先/网格/圆。 导出PNG 生成可共享的图像。
• 离线保险箱 --Cytoscape.js+Dagre在SocratiCode包中提供。没有CDN，没有网络，在空气间隙环境中工作。

输出是一个HTML文件（写入操作系统临时目录，每个项目一个），您还可以将其提交给PR或在Slack上共享。

管理

上下文伪影

语言支持

SocratiCode支持三个级别的语言：

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

JavaScript、TypeScript、TSX、Python、Java、Kotlin、Scala、C、C++、C#、Go、Rust、Ruby、PHP、Swift、Bash/Shell、HTML、CSS/SCSS、Svelte、Vue

Svelte和Vue：从中提取的导入 ` 块（重新解析为TypeScript）和CSS @import/@require 从 块（以下各项的任意组合 lang, scoped, module, global 属性）。来自的路径别名 tsconfig.json/jsconfig.json compilerOptions.paths 已解决（包括 extends 链条）。SCSS部分分辨率(_` 前缀约定）。

通过正则表达式+索引的代码图

Dart（导入/导出/部分）、Lua（require/dofile/loadfile）、SASS、LESS（CSS） @import 提取）

仅索引（混合搜索、基于行的分块）

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

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

忽略规则

索引器结合了三层忽略规则：

1. 内置默认值 — node_modules, .git, dist, build，锁定文件、IDE文件夹等。
2. .gitignore --全部 .gitignore 项目中的文件（根目录和嵌套子目录）。集 RESPECT_GITIGNORE=false 跳过 .gitignore 完全处理。
3. .socraticodeignore --索引器特定排除的可选文件。语法与 .gitignore.

上下文伪影

让人工智能了解源代码之外的项目知识——数据库模式、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 --文件或目录的路径（相对于项目根目录或绝对路径）。目录是递归读取的。
• description -告诉人工智能这个工件是什么以及如何使用它

运作原理

使用与代码相同的混合密集+BM25搜索将工件分块并嵌入Qdrant中。第一次搜索时，工件会自动索引。在后续搜索中，通过内容哈希自动检测过时性——更改的文件会透明地重新索引。

用法

1. 发现: codebase_context --列出所有已定义的工件及其索引状态
2. 搜索: codebase_context_search --跨所有工件的语义搜索（或按名称过滤）
3. 重新索引: codebase_context_index --强制重新索引（通常不需要，自动索引可以处理）
4. 清理: codebase_context_remove --删除所有索引工件

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

没有工件，代理只能看到源代码。通过工件，它可以全面了解情况，并从一开始就编写适合您项目的代码。

数据库模式 --你问 *“向用户添加last_login时间戳。”* 代理人跑 codebase_context_search 对于“用户表”，查找模式使用 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端点。”* 代理搜索OpenAPI规范，看到所有端点都使用Bearer auth，返回 { 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） --你问 *“添加取消订单的方法。”* 代理搜索您的域术语表，发现取消被建模为 OrderVoided 事件（非“取消”），仅在 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 场地是关键杠杆。 它告诉人工智能 *什么* 人工制品是，但是 *何时咨询*。写下描述“在执行X操作之前检查一下”，这样代理就可以在正确的时刻找到工件。

示例工件

小贴士：对于数据库模式，每个主要数据库都可以将其整个模式导出到一个文件中： pg_dump --schema-only （PostgreSQL）， mysqldump --no-data （MySQL）， sqlite3 db.sqlite .schema （SQLite）。ORM模式（Prisma、Rails、Django）通常已经在你的仓库中了。

环境变量

SocratiCode从环境变量中读取配置。传递它们的方式取决于您的MCP主机——三种主要配置风格的密钥名和文件格式不同。如果env变量似乎被忽略了，请先检查主机的配置格式——大多数“它没有获取我的设置”问题都是不匹配的密钥。

按主机传递env变量

使用几个env变量集的工作示例：

标准MCP JSON --Claude Code、Claude Desktop、Windsurf、Cline、Roo Code、Cursor、VS Code复制品：

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

开源代码 --注： environment，不 env:

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

OpenAI Codex命令行界面 --env变量放在单独的 [mcp_servers.NAME.env] 表：

[mcp_servers.socraticode]
command = "npx"
args = ["-y", "socraticode"]

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

本节的其余部分将记录变量本身。使用与主机匹配的任何语法传递它们。

嵌入提供者

Ollama配置（当 EMBEDDING_PROVIDER=ollama)

云提供商API密钥

LM Studio配置（当 EMBEDDING_PROVIDER=lmstudio)

LiteLLM配置（当 EMBEDDING_PROVIDER=litellm)

Qdrant配置

索引行为

重要：如果你改变 EMBEDDING_PROVIDER, EMBEDDING_MODEL，或 EMBEDDING_DIMENSIONS 索引后，您必须重新索引您的项目(codebase_remove 然后 codebase_index)因为现有向量具有不同的维度。

Docker资源

SocratiCode管理Docker容器和持久卷：

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

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

为什么选择非标准端口？ SocratiCode有意为其托管容器使用非默认端口-- 16333/16334 而不是Qdrant的默认值(6333/6334)，以及 11435 而不是Ollama的违约(11434).这避免了与您可能已经在本地运行的任何Qdrant或Ollama实例发生冲突。如果需要，所有端口都可以通过环境变量覆盖。

测试

SocratiCode有一个全面的测试套件 634测试 跨单元、集成和端到端层。

先决条件

• 单元测试：不需要外部依赖关系。
• 集成和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不可用时，需要Docker的集成和E2E测试会自动跳过。

为什么不只是Grep？

对真实存储库的现代评估表明，一旦你关心自然语言查询、大型代码库或编码代理，混合词汇+语义代码搜索始终优于普通grep：报告显示，BM25F大规模排名可提高约20%的搜索质量，AST感知检索可提高RepoEval和SWE工作台上的召回率和错误修复性能，与grep（SocratiCode中的默认值）的混合方法在70%的代理代码搜索任务中击败grep，同时将搜索操作减少一半以上。

现实世界基准测试：VS Code（245万行代码），采用Claude Opus 4.6

与VS Code代码库（5300多个文件、55437个索引块中约245万行Types/JavaScript）进行直接比较，以衡量Claude Opus 4.6 AI代理在回答架构问题时实际消耗的内容。

方法论： 对于每个问题 grep方法 遵循人工智能代理目前使用的现实多步骤工作流程： grep -rl 要找到匹配的文件，识别核心文件，分块读取（一次200行），并重复直到有足够的上下文。这 SocratiCode方法 执行一个语义搜索调用，返回整个代码库中10个最相关的代码块。

主要发现：

• 工具调用减少84% --Grep在5个问题中需要31个步骤（每个问题6-7个）。SocratiCode:共5步（每题1步）。
• 数据消耗减少61.5% --AI代理处理的上下文减少了约150KB，这直接降低了任何LLM的令牌成本。
• 快37倍 --在2.45M行中进行Grep扫描，每个问题可能需要2-3.5秒。语义搜索时间可达60-90ms。

注： 这个基准是 _保守的_ 对于grep方法。它假设代理已经知道要读取哪些文件。在实践中，真正的AI代理需要额外的探索性grep调用，遵循死胡同，读取无关的文件，并且通常需要多轮筛选。实际节省的金额可能更大。

当混合搜索获胜时

自然语言和概念查询 --查询如下 *“我们在哪里处理数据库连接池？”* 或 *“这个库是如何实现指数回退的？”* 描述行为而不是命名函数。对存储库级基准（RepoEval、SWE bench）的评估表明，与基于固定行的块相比，AST感知语义检索将召回率提高了4.3点，下游代码生成准确率提高了2.7点。对真正的开源仓库的代理评估显示，在硬概念问题上，混合搜索的胜率比普通grep高出70%，搜索操作减少了56%，每个复杂查询减少了约60000个令牌。

大型回购和单回购 --在数百万LOC的规模下，全文扫描变得昂贵。生产搜索引擎报告称，与之前的方法相比，BM25F排名的相关性提高了约20%，并将其用作语义重新排名的第一阶段检索器。由倒排索引和向量索引支持的混合搜索完全避免了全扫描，使其在规模上更快、更精确。行业从业者明确指出，grep和find“不能很好地扩展到数百万个文件”，而优化的基于嵌入的索引在这个规模上可以更快。

跨文件和跨语言推理 --找到最终跨服务调用内部帮助程序的所有代码路径，或者将自然语言规范映射到Go和SQL中的实现，需要理解字符串匹配之外的内容。评估表明，当命名不明显且需要语义理解时，具有树型解析和依赖上下文的混合管道优于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 *“删除此项目的索引”*那么 让它重新索引。这将清除项目的所有存储块和元数据 开始一个干净的重新索引。它不会影响其他索引项目。

我的代码库非常大——我可以暂停索引并稍后恢复吗？

对。您可以随时停止索引，稍后恢复，而不会丢失进度：

1. 让你的AI助手停止 --说类似的话 *“停止索引”* 它将会

在下一批处理边界取消当前操作。到目前为止已完成的所有批次 被检查并保存。

1. 或者直接关闭您的项目/编辑器 --SocratiCode检测到断开连接并关闭

优雅地下降，保留所有检查点进度。

1. 你想什么时候回来都行 --在编辑器中重新打开同一个项目并询问AI

恢复索引（例如。 *“简历索引”*).SocratiCode检测到不完整的索引 它会自动跳过已嵌入的每个文件，并精确地从停止的位置继续。

这使得索引非常大的代码库变得实用，即使在较慢的硬件上也是如此——您可以在 在数小时或数天内进行多次会话，并且不会重复或丢失任何工作。

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

对于任何以前索引过的项目，文件查看器在首次使用工具时会自动启动。当它 启动时，它会先捕获SocratiCode关闭时修改的所有文件，然后再进行监视 未来的变化。

如果你想在搜索前立即追赶，请让你的人工智能 *“开始观看 这个项目”* 或 *“更新索引”* --两者都同步运行增量更新 然后开始观看。

如果当前有完整索引或增量更新，监视器将不会自动启动 进度，如果项目尚未编入索引，或者已经有另一个MCP流程 观看同一个项目。

多个AI代理可以同时在同一代码库上工作吗？

是的，这是一个一流的支持工作流。当多个代理（每个代理运行自己的MCP服务器实例）指向同一个项目目录时，它们会自动共享相同的Qdrant索引。第一个触发索引的代理获取跨进程锁并构建索引；任何其他试图同时索引的代理都会收到当前进度，而不是开始重复操作。所有代理都可以并发搜索，不需要协调——Qdrant本机处理并行读取。

文件监视器也会自动协调：每个项目只有一个进程监视。其他实例检测到此情况并跳过监视器启动。当监视进程检测到文件更改时，它会更新共享索引，每个代理的下一次搜索都会看到更新的结果。

如果拥有观察器或索引锁的代理崩溃，其锁将在2分钟后失效，另一个代理的下一次交互会自动回收它。不需要手动干预。

这使得SocratiCode成为多代理工作流的理想选择：一个代理编写测试，另一个代理修复代码，一个规划代理和一个实现代理并行工作，或者共享深度代码库知识而不重复工作的人工智能助手的任何组合。

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

对。SocratiCode为每个项目路径维护一个单独的隔离集合。问你的 AI到 *“列出所有索引项目”* 查看当前索引的所有内容。

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

每个集合都是使用与索引时使用的模型匹配的固定向量大小创建的。 如果你改变 EMBEDDING_PROVIDER, EMBEDDING_MODEL，或 EMBEDDING_DIMENSIONS 在你的 MCP配置，任何使用旧模型索引的项目都将返回维度不匹配错误。 让你的AI *“删除此项目的索引”* 然后用新的索引再次索引 模型。你没有接触过的项目不会受到影响。

如何删除项目的索引（例如，切换嵌入模型或从头开始重新索引）？

1. 先停下 --如果索引正在进行中，例如 *“停止为此项目编制索引”*.拆卸

当索引处于活动状态时，会损坏数据，因此删除将被拒绝，直到 当前批次完成。

1. 移除 --说 *“删除此项目的索引”*。这将删除向量

集合、所有存储的块元数据、代码图和上下文工件元数据 只有这个项目。其他项目未受影响。

1. 重新索引 --如果需要，用新参数更新MCP配置，然后说

*“索引此项目”* 重新开始。

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

苏格拉底背后的代码是阿波罗11号指令舱（Comanche055）原始制导计算机（AGC）源代码的一部分！

社区

• 💬 Discord 的中文翻译是“不和谐”或“纷争”。 --与用户和维护人员聊天，询问“我该如何……”，分享你正在构建的内容
• 🐛 **** --错误报告和确认的功能请求（请使用模板）
• 📣 发布 — *手表* 仓库（GitHub右上角→ *自定义* → *发布*)收到新版本的通知

如果SocratiCode对你有用，你能做的最有帮助的事情就是⭐ 明星回购 --这就是其他人发现这个项目的方式。

______________________________________________________________________

SocratiCode云

在AGPL-3.0下，完整的SocratiCode引擎是免费和开源的，并且将继续如此。 SocratiCode云 是同一引擎之上的可选托管版本，当前位于 私人测试版，适用于希望共享、管理、合规基础设施的团队。

Cloud在OSS引擎之上添加了什么：

• 共享团队索引 --每个开发人员搜索相同的数据，并在每个分支的每次推送时自动索引
• 跨回购搜索 --在一次调用中查询您组织拥有的每个存储库
• SSO/SAML、审计日志、IP分配 --内置，而非后期追加销售
• 部署模型 --托管云（欧盟/美国）、您自己的VPC（AWS/GCP/Azure）或完全气隙本地
• 网络仪表盘 --搜索、依赖关系图、工件、团队和仓库管理
• 零本地基础设施 --没有Docker，没有Qdrant，没有Ollama供团队管理

目前正在组建少数工程团队。 请求提前访问→

这个存储库中的开源引擎现在是，将来也永远是为云提供动力的引擎。没有诱饵和开关，没有OSS核心的功能门控。云只增加了围绕它的团队、部署和合规层。

______________________________________________________________________

许可证

SocratiCode具有双重许可：

• 开源 — AGPL-3.0。免费使用、修改和分发。

如果您修改SocratiCode并将其作为网络服务提供，则必须发布 您在AGPL-3.0下的修改。

• 商业的 --适用于需要在专有代码中使用SocratiCode的组织

没有AGPL义务的产品或服务。看 许可电子商务 或联系 giancarlo@altaire.com.

版权所有（C）2026 Giancarlo Erra-Altaire有限公司。

第三方许可证

SocratiCode在自己的许可证下包含开源依赖项 （麻省理工学院、Apache 2.0、ISC）。看 第三方许可证 了解详情。

贡献

欢迎捐款。提交pull请求即表示您同意 贡献者许可协议.