giancarloerra/SocratiCode

SocratiCode – 具备代码库感知能力的 AI 引擎

它是什么 – SocratiCode 是一个开源的代码库上下文引擎，让任何 LLM（Claude、OpenAI、Gemini 等）都能理解存储库的完整语义，而无需模型在查询时读取每个文件。它会建立一个本地索引（嵌入 + AST 感知区块、依赖关系图、符号级影响数据），并透过 Claude Code、OpenAI Codex、VS Code、Cursor、Gemini CLI 和其他主机使用的 MCP (Multi-Chat-Protocol) 接口提供服务。

为什么它很重要 – 大型代码库（数千万行）喂给 LLM 的成本很高：代币成本、延迟和幻觉。SocratiCode 会预先计算繁重的工作，然后让助手在几毫秒内检索精确的符号、调用流程和相关工件（数据库架构、API 规格、基础设施配置）。这减少了上下文大小、代币使用量和工具调用，并使更小、更便宜的模型能够执行架构级的推理。

---

核心功能（如 README 中所述）

• 混合搜索 – 结合语义（嵌入）和 BM25（关键字）检索与倒数排名融合。
• 多语言依赖图 – 解析 18 种语言，建立符号级调用流程/爆炸半径图，并在交互式 HTML 浏览器中可视化。
• 影响分析 – 追踪变更会影响哪些函数、类或文件。
• 上下文工件 – 索引并搜索数据库架构、OpenAPI 规格、Terraform/云端配置、架构文档等。
• 零配置启动 – npx socraticode@latest 自动启动 Docker 堆栈（Qdrant 向量数据库 + Ollama 用于本地嵌入）。
• 自动增量索引 – 文件监控器会在每次变更时更新索引；可恢复的检查点可在崩溃后继续执行。
• 多存储库 / 多分支 / 多代理 – 单一索引可供多个 AI 代理同时共享。
• 默认私有 – 所有内容都在本地运行；除非您选择使用云端嵌入（OpenAI、Google Gemini）或外部 Qdrant 实例，否则不需要 API 密钥。
• 云端就绪 – SocratiCode Cloud（私人测试版）增加了 SSO、审计日志、分支感知索引和 VPC/隔离网络部署，同时保持核心引擎免费。
• 广泛的主机集成 – 原生插件支持 Claude Code、OpenAI Codex、VS Code（代理插件与编辑器扩展功能）、Cursor、Gemini CLI、Continue、Cline、Zed、OpenCode，以及直接 MCP 模式。
• 基准性能 – 在 245 万行的 VS Code 项目上，它减少了 61% 的上下文，减少了 84% 的工具调用，并且比基于 grep 的工作流程（Claude Opus 4.6）快 37 倍。

---

入门（快速启动流程）

1. 先决条件 – Node ≥ 18.17，npx 在 PATH 中，Docker 正在运行（用于默认的 Qdrant + Ollama 堆栈）。
2. 安装 – 最简单的路径是透过 MCP 主机：

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

   或者使用 Claude Code、VS Code 或 Cursor 的一键徽章（README 提供了触发相同 npx 指令的徽章链接）。
3. 首次索引 – 在聊天中，询问助手“Index this codebase”。SocratiCode 会在后台运行，监控存储库并透过 codebase_update / codebase_watch 指令报告进度。
4. 使用 – 索引完成后，您可以：
   • codebase_search { query: "…" } – 混合语义 + BM25 搜索。
   • codebase_graph { symbol: "MyClass.method" } – 查看依赖关系图。
   • codebase_impact { symbol: "…" } – 获取爆炸半径分析。
   • 查询工件，如 schema_search、api_spec_search 等。
5. 保持最新 – 引擎会在每次 MCP 服务器启动时自动更新 (npm @latest)。插件/扩展功能透过主机的正常扩展更新机制进行更新。

---

典型工作流程示例

User:  Index this codebase.
Assistant (via SocratiCode):  Indexing started… 45 % done.
User:  What function reads the `config.yaml` file?
Assistant:  (runs `codebase_search` → returns `loadConfig` in `src/config.ts`)
User:  Show me the call-flow from `loadConfig`.
Assistant:  (runs `codebase_graph` → displays interactive HTML graph)
User:  Which modules would be affected if I change `Database.connect`?
Assistant:  (runs `codebase_impact` → lists dependent services, tests, docs)

所有繁重的分析都在本地运行；LLM 只会收到简洁的结果。

---

配置亮点

• 嵌入提供者 – EMBEDDING_PROVIDER 可以是 ollama（默认，本地）、openai 或 google。透过环境变量设置适当的 API 密钥。
• 监控模式 – SOCRATICODE_WATCHER=off|manual|auto 控制自动文件监控更新。
• 恢复行为 – SOCRATICODE_AUTO_RESUME_PROJECTS / SOCRATICODE_AUTO_RESUME 让您预先加载多个存储库。
• 版本锁定 – 将 SOCRATICODE_SPEC 设置为具体的 npm 版本（例如 socraticode@1.14.0）以在重新启动时冻结引擎。
• Docker 资源 – README 解释了如何为大型存储库分配 CPU/RAM 给 Qdrant/Ollama 容器。

---

谁应该使用它

• 开发者，希望他们的 LLM 助手（Claude、ChatGPT、Gemini 等）能够在不将源代码暴露给外部服务的情况下，对单体存储库、微服务架构或基础设施即代码进行推理。
• 团队，正在构建内部 AI 驱动的开发运维工具、代码审查机器人或自动化影响分析管线。
• 企业，需要一个自托管、政策可控的代码智能层（请参阅姊妹项目 JanuScope 以进行 MCP 治理、PII 去识别化、速率限制等）。

---

授权与社区

• 授权： AGPL-3.0（提供完整源代码，商业使用需遵守 AGPL）。
• 社区： Discord 服务器提供支持，GitHub Issues 用于错误/功能请求，以及为需要托管、SSO 和审计日志的团队提供的私人测试版托管 SaaS 服务 (SocratiCode Cloud)。

---

总结

SocratiCode 透过为您的整个存储库建立本地、最新的索引，并透过标准 MCP 接口公开强大的搜索、图表和影响分析工具，将任何 LLM 转变为具备代码感知能力的助手。它专为企业规模的零配置、隐私优先部署而设计，同时透过一键式 VS Code 或 Claude Code 插件，让单一开发者也能轻松使用。