[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-giancarloerra--SocratiCode":3,"tool-giancarloerra--SocratiCode":62},[4,18,26,36,46,54],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",160015,2,"2026-04-18T11:30:52",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":42,"last_commit_at":43,"category_tags":44,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,45],"插件",{"id":47,"name":48,"github_repo":49,"description_zh":50,"stars":51,"difficulty_score":32,"last_commit_at":52,"category_tags":53,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",109154,"2026-04-18T11:18:24",[14,15,13],{"id":55,"name":56,"github_repo":57,"description_zh":58,"stars":59,"difficulty_score":32,"last_commit_at":60,"category_tags":61,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[45,13,15,14],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":78,"owner_email":79,"owner_twitter":79,"owner_website":80,"owner_url":81,"languages":82,"stars":91,"forks":92,"last_commit_at":93,"license":94,"difficulty_score":32,"env_os":95,"env_gpu":96,"env_ram":97,"env_deps":98,"category_tags":106,"github_topics":107,"view_count":32,"oss_zip_url":79,"oss_zip_packed_at":79,"status":17,"created_at":128,"updated_at":129,"faqs":130,"releases":160},9118,"giancarloerra\u002FSocratiCode","SocratiCode","Enterprise-grade (40m+ lines) codebase intelligence in a zero-setup, private and local Plugin\u002FSkill or MCP: managed indexing, hybrid semantic search, polyglot code dependency graphs, cross-project\u002Frepo & branch-aware search, and DB\u002FAPI\u002Finfra knowledge. Benchmark: 61% less tokens, 84% fewer calls, 37x faster than AI grep. Cloud in private beta.","SocratiCode 是一款专为 AI 编程助手打造的开源代码库智能引擎，旨在让 AI 真正“理解”而不仅仅是读取你的代码。它解决了大型项目中 AI 因缺乏全局上下文而导致回答不准、需要反复调用或消耗大量 Token 的痛点。通过零配置、本地化且完全隐私保护的部署方式，SocratiCode 能自动构建包含混合语义搜索、多语言依赖图谱以及数据库、API 和基础设施知识的深度索引。\n\n这款工具特别适合需要在大规模代码库（支持超 4000 万行代码）中工作的开发者、技术团队及企业用户。无论是使用 Claude Code、Cursor、VS Code 还是其他兼容 MCP 协议的 AI 编辑器，都能无缝集成。其独特亮点在于极高的效率与稳定性：相比传统搜索方式，它能减少 61% 的 Token 消耗和 84% 的调用次数，速度提升高达 37 倍。此外，SocratiCode 具备断点续传索引、文件实时监听更新以及多智能体协同工作能力，确保在复杂开发环境中始终提供准确、即时且安全的代码上下文支持，是提升 AI 编程效能的理想搭档。","\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fgiancarloerra_SocratiCode_readme_6b9a1753d8f4.png\" alt=\"SocratiCode logo\" \u002F>\n\u003C\u002Fp>\n\n# SocratiCode\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg\" alt=\"CI\">\u003C\u002Fa>\n  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-AGPL--3.0-blue.svg\" alt=\"License: AGPL-3.0\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fsocraticode\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fsocraticode.svg\" alt=\"npm version\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fnodejs.org\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnode-%3E%3D18-brightgreen.svg\" alt=\"Node.js >= 18\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fgiancarloerra\u002Fsocraticode?style=social\" alt=\"GitHub stars\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002F5DrMXfNG\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-Join-5865F2?logo=discord&logoColor=white\" alt=\"Discord\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#claude-code-plugin-recommended-for-claude-code-users\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude_Code-Install_Plugin-CC785C?style=flat-square&logoColor=white\" alt=\"Install Claude Code Plugin\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Finsiders.vscode.dev\u002Fredirect\u002Fmcp\u002Finstall?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FVS_Code-Install_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white\" alt=\"Install in VS Code\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Finsiders.vscode.dev\u002Fredirect\u002Fmcp\u002Finstall?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D&quality=insiders\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FVS_Code_Insiders-Install_MCP_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white\" alt=\"Install in VS Code Insiders\">\u003C\u002Fa>\n  \u003Ca href=\"cursor:\u002F\u002Fanysphere.cursor-deeplink\u002Fmcp\u002Finstall?name=socraticode&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNvY3JhdGljb2RlIl19\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCursor-Install_MCP_Server-F14C28?style=flat-square&logo=cursor&logoColor=white\" alt=\"Install in Cursor\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n> *\"There is only one good, knowledge, and one evil, ignorance.\"* — Socrates\n\n**Your AI reads code. SocratiCode understands it.**\n\n**The open-source codebase context engine: give any AI instant automated knowledge of your entire codebase (and infrastructure) — at scale, zero configuration, fully private, completely free.**\n\n\u003Cp align=\"center\">\n  Kindly sponsored by \u003Ca href=\"https:\u002F\u002Faltaire.com\">Altaire Limited\u003C\u002Fa>\n\u003C\u002Fp>\n\n> If SocratiCode has been useful to you, please ⭐ **star this repo** — it helps others discover it — and share it with your dev team and fellow developers!\n>\n> 💬 Questions or just want to chat? Join us on [Discord](https:\u002F\u002Fdiscord.gg\u002F5DrMXfNG).\n\n**One thing, done well: deep codebase intelligence — zero setup, no bloat, fully automatic.** SocratiCode gives AI assistants deep semantic understanding of your codebase — hybrid search, cross-project search, polyglot code dependency graphs, and searchable context artifacts (database schemas, API specs, infra configs, architecture docs). Zero configuration — add it to **any MCP host**, or install the native **plugin** for Claude Code, Cursor, VS Code Copilot, Codex or Gemini CLI. It manages everything automatically.\n\n**Production-ready**, battle-tested on **enterprise-level** large repositories (up to and over **~40 million lines of code**). **Batched**, automatic **resumable** indexing checkpoints progress — pauses, crashes, restarts, and interruptions don't lose work. The file watcher keeps the **index automatically updated** at every file change and across sessions. **Multi-agent ready** — multiple AI agents can work on the same codebase simultaneously, sharing a single index with automatic coordination and zero configuration.\n\n**Private and local by default** — Docker handles everything, no API keys required, no data leaves your machine. **Cloud ready** for embeddings (OpenAI, Google Gemini) and Qdrant, and a **full suite of configuration options** are all available when you need them.\n\n> **☁️ SocratiCode Cloud (private beta)** — Hosted, shared team index built on the same engine as the open-source version, plus SSO, audit logs, branch-aware indexing, and VPC \u002F air-gapped deployment options. The open-source core remains free forever. [Request early access →](https:\u002F\u002Fsocraticode.cloud)\n\nThe first Qdrant‑based MCP\u002FClaude Plugin\u002FSkill that pairs auto‑managed, zero‑config local Docker deployment with **AST‑aware code chunking, hybrid semantic + BM25 (RRF‑fused) code search**, polyglot dependency **graphs** with circular‑dependency visualization, and searchable **infra\u002FAPI\u002Fdatabase artifacts** in a single focused, zero-config and easy to use code intelligence engine.\n\n> **Benchmarked on VS Code (2.45M lines):** SocratiCode uses **61% less context**, **84% fewer tool calls**, and is **37x faster** than grep‑based exploration — tested live with Claude Opus 4.6. [See the full benchmark →](#real-world-benchmark-vs-code-245m-lines-of-code-with-claude-opus-46)\n\n\u003Cp align=\"center\">\n\u003Ca href=\"https:\u002F\u002Fwww.star-history.com\u002F?repos=giancarloerra%2Fsocraticode&type=date&logscale=&legend=top-left\">\n \u003Cpicture>\n   \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"https:\u002F\u002Fapi.star-history.com\u002Fimage?repos=giancarloerra\u002Fsocraticode&type=date&theme=dark&legend=top-left\" \u002F>\n   \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fgiancarloerra_SocratiCode_readme_864584439e89.png\" \u002F>\n   \u003Cimg alt=\"Star History Chart\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fgiancarloerra_SocratiCode_readme_864584439e89.png\" \u002F>\n \u003C\u002Fpicture>\n\u003C\u002Fa>\n\u003C\u002Fp>\n\n## Contents\n\n- [Quick Start](#quick-start)\n- [Plugins](#plugins)\n- [Why SocratiCode](#why-socraticode)\n- [Features](#features)\n- [Prerequisites](#prerequisites)\n- [Example Workflow](#example-workflow)\n- [Agent Instructions](#agent-instructions)\n- [Configuration](#configuration)\n- [Language Support](#language-support)\n- [Ignore Rules](#ignore-rules)\n- [Context Artifacts](#context-artifacts)\n- [Environment Variables](#environment-variables)\n- [Docker Resources](#docker-resources)\n- [Testing](#testing)\n- [Why Not Just Grep?](#why-not-just-grep)\n- [FAQ](#faq)\n- [Community](#community)\n- [SocratiCode Cloud](#socraticode-cloud)\n- [License](#license)\n\n---\n\n## Quick Start\n\n> **Only [Docker](https:\u002F\u002Fwww.docker.com\u002Fproducts\u002Fdocker-desktop\u002F) (running) required.**\n\n**One-click install** — Claude Code, VS Code and Cursor:\n\n[![Install Claude Code Plugin](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude_Code-Install_Plugin-CC785C?style=flat-square&logoColor=white)](#claude-code-plugin-recommended-for-claude-code-users)\n[![Install in VS Code](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FVS_Code-Install_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https:\u002F\u002Finsiders.vscode.dev\u002Fredirect\u002Fmcp\u002Finstall?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D) [![Install in VS Code Insiders](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FVS_Code_Insiders-Install_MCP_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https:\u002F\u002Finsiders.vscode.dev\u002Fredirect\u002Fmcp\u002Finstall?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D&quality=insiders) [![Install in Cursor](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCursor-Install_MCP_Server-F14C28?style=flat-square&logo=cursor&logoColor=white)](cursor:\u002F\u002Fanysphere.cursor-deeplink\u002Fmcp\u002Finstall?name=socraticode&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNvY3JhdGljb2RlIl19) \n\n**All MCP hosts** — add the following to your `mcpServers` (Claude Desktop, Windsurf, Cline, Roo Code) or `servers` (VS Code project-local `.vscode\u002Fmcp.json`) config:\n\n```json\n\"socraticode\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"socraticode\"]\n}\n```\n\n**Claude Code** — install the plugin (recommended, includes workflow skills for best results):\n\nFrom your shell:\n\n```bash\nclaude plugin marketplace add giancarloerra\u002Fsocraticode\nclaude plugin install socraticode@socraticode\n```\n\nOr from within Claude Code:\n\n```\n\u002Fplugin marketplace add giancarloerra\u002Fsocraticode\n\u002Fplugin install socraticode@socraticode\n```\n\n> **Auto-updates:** After installing, enable automatic updates by opening `\u002Fplugin` → Marketplaces → select `socraticode` → Enable auto-update.\n\nOr as MCP only (without skills):\n\n```bash\nclaude mcp add socraticode -- npx -y socraticode\n```\n\n> **Updating:** `npx` caches the package after the first run. To get the latest version, clear the cache and restart your MCP host: `rm -rf ~\u002F.npm\u002F_npx && claude mcp restart socraticode`. Alternatively, use `npx -y socraticode@latest` in your config to always check for updates on startup (slightly slower).\n\n**OpenCode** — add to your `opencode.json` (or `opencode.jsonc`):\n\n```json\n{\n  \"mcp\": {\n    \"socraticode\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"socraticode\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n**OpenAI Codex CLI** — add to `~\u002F.codex\u002Fconfig.toml`:\n\n```toml\n[mcp_servers.socraticode]\ncommand = \"npx\"\nargs = [\"-y\", \"socraticode\"]\n```\n\nRestart your host. On first use SocratiCode automatically pulls Docker images, starts its own Qdrant and Ollama containers, and downloads the embedding model — one-time setup, ~5 minutes depending on your connection. After that, it starts in seconds.\n\n**First time on a project** — ask your AI: **\"Index this codebase\"**. Indexing runs in the background; ask **\"What is the codebase index status?\"** to monitor progress. Depending on codebase size and whether you're using GPU-accelerated Ollama or cloud embeddings, first-time indexing can take anywhere from a few seconds to a few minutes (it takes under 10 minutes to first-index +3 million lines of code on a Macbook Pro M4). Once complete it doesn't need to be run again, you can search, explore the dependency graph, and query context artifacts.\n\n**Every time after that** — just use the tools (search, graph, etc.). On server startup SocratiCode automatically detects previously indexed projects, restarts the file watcher, and runs an incremental update to catch any changes made while the server was down. If indexing was interrupted, it resumes automatically from the last checkpoint. You can also explicitly start or restart the watcher with `codebase_watch { action: \"start\" }`.\n\n> **macOS \u002F Windows on large codebases**: Docker containers can't use the GPU. For medium-to-large repos, [install native Ollama](https:\u002F\u002Follama.com\u002Fdownload) (auto-detected, no config change needed) for Metal\u002FCUDA acceleration, or use [OpenAI embeddings](#openai-embeddings) for speed without a local install. [Full details.](#embedding-performance-on-macos--windows)\n\n> **Recommended**: For best results, add the [Agent Instructions](#agent-instructions) to your AI assistant's system prompt or project instructions file (`CLAUDE.md`, `AGENTS.md`, etc.). The key principle — **search before reading** — helps your AI use SocratiCode's tools effectively and avoid unnecessary file reads.\n\n> **Claude Code users**: If you installed the SocratiCode plugin, the Agent Instructions are included automatically as skills — no need to add them to your `CLAUDE.md`. The plugin also bundles the MCP server, so you don't need a separate `claude mcp add`.\n\n> **Advanced**: cloud embeddings (OpenAI \u002F Google), external Qdrant, remote Ollama, native Ollama, and dozens of tuning options are all available. See [Configuration](#configuration) below.\n\n## Plugins\n\nSocratiCode is available as a native plugin on multiple AI coding platforms. Plugins bundle the MCP server with workflow skills and agent instructions — one install gives you everything.\n\n| Platform | Install method |\n|:---------|:---------------|\n| Claude Code | `claude plugin marketplace add giancarloerra\u002Fsocraticode` — [full instructions](#claude-code-plugin-recommended-for-claude-code-users) |\n| Cursor | `\u002Fadd-plugin https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode` |\n| VS Code Copilot | Command Palette → `Chat: Install Plugin From Source` → `https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode` |\n| Zed | Add as a custom MCP server in Zed settings — [config example](#zed) |\n| Gemini CLI | `gemini extensions install https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode` |\n| OpenAI Codex | No public plugin directory yet — use the [MCP config](#quick-start) or see **Codex local install** below |\n\n> **VS Code Copilot**: The chat plugins feature is in preview. Enable it with `chat.plugins.enabled: true` in your VS Code settings.\n\n> **Codex local plugin install**: Clone the repo and register it in your personal plugin marketplace:\n> ```bash\n> git clone https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode.git ~\u002F.agents\u002Fplugins\u002Fsocraticode\n> ```\n> Then add it to `~\u002F.agents\u002Fplugins\u002Fmarketplace.json`:\n> ```json\n> {\n>   \"plugins\": [\n>     {\n>       \"name\": \"socraticode\",\n>       \"path\": \"~\u002F.agents\u002Fplugins\u002Fsocraticode\"\n>     }\n>   ]\n> }\n> ```\n> Codex will discover the plugin from `.codex-plugin\u002Fplugin.json` on next launch.\n\n> **All other MCP hosts** (Claude Desktop, Windsurf, Cline, Roo Code, OpenCode): Use the [MCP config](#quick-start) — works with any host that supports the MCP protocol.\n\n## Why SocratiCode\n\nI built SocratiCode because I regularly work on existing, large, and complex codebases across different languages and need to quickly understand them and act. Existing solutions were either too limited, insufficiently tested for production use, or bloated with unnecessary complexity. I wanted a single focused tool that does deep codebase intelligence well — zero setup, no bloat, fully automatic — and gets out of the way.\n\n### Built-in Code Search vs SocratiCode\n\n| Feature | Claude Code | Cursor | VS Code Copilot | + SocratiCode |\n|:--------|:-----------:|:------:|:---------------:|:-------------:|\n| Text \u002F grep search | ✅ | ✅ | ✅ | ✅ |\n| Semantic search | — | ✅ | ✅¹ | ✅ |\n| Hybrid search (fused) | — | — | — | ✅ |\n| Code dependency graph | — | — | ✅² | ✅ |\n| Circular dependency detection | — | — | — | ✅ |\n| Non-code knowledge (schemas, API specs) | — | — | — | ✅ |\n| Cross-project search | — | — | — | ✅ |\n| Branch-aware indexing | — | — | — | ✅ |\n| Multi-agent shared index | — | — | — | ✅ |\n| Tool-independent (survives switching AI) | — | — | — | ✅ |\n| Fully local \u002F private | ✅ | —³ | —⁴ | ✅ |\n| Resumable indexing | — | — | — | ✅ |\n| Live file watching | — | ✅ | — | ✅ |\n\n\u003Csub>¹ VS Code Copilot: remote index via GitHub \u002F Azure DevOps; local \"External Ingest\" gradually rolling out. ² LSP-based Find References \u002F Go to Definition (Usages tool), not a full dependency graph. ³ Cursor: embeddings processed on Cursor servers (encrypted in transit and at rest). ⁴ VS Code Copilot: remote index hosted on GitHub \u002F Azure DevOps. Sources: [Cursor docs](https:\u002F\u002Fdocs.cursor.com\u002Fcontext\u002Fcodebase-indexing), [Claude Code docs](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Foverview), [VS Code Copilot docs](https:\u002F\u002Fcode.visualstudio.com\u002Fdocs\u002Fcopilot\u002Fchat\u002Fcodebase-context).\u003C\u002Fsub>\n\n> **🔌 The context lives with your codebase, not with the assistant.** Built-in indexes (Cursor's, Copilot's) are tied to that one tool — switch assistants and you start from scratch. SocratiCode is independent: index once, then plug it into Claude Code, Cursor, Copilot, Windsurf, your own private model, or all of them at once. They share the same understanding of your code.\n\nOn VS Code's 2.45M‑line codebase, SocratiCode answers architectural questions with **61% less data**, **84% fewer steps**, and **37× faster** response than a grep‑based AI agent. [Full benchmark →](#real-world-benchmark-vs-code-245m-lines-of-code-with-claude-opus-46)\n\n## Features\n\n- **Hybrid code search** — Built on Qdrant, a purpose-built vector database with HNSW indexing, concurrent read\u002Fwrite, and payload filtering. Each chunk stores both a dense vector and a BM25 sparse vector; the Query API runs both sub-queries in a single round-trip and fuses results with Reciprocal Rank Fusion (RRF). Semantic search handles conceptual queries like \"authentication middleware\" even when those exact words don't appear in the code. BM25 handles exact identifier and keyword lookups. You get the best of both in every query with no tuning required.\n- **Configurable Qdrant** — Use the built-in Docker Qdrant (default, zero config) or connect to your own instance (self-hosted, remote server, or Qdrant Cloud). Configure via `QDRANT_MODE`, `QDRANT_URL`, and `QDRANT_API_KEY` environment variables.\n- **Configurable Ollama** — Use the built-in Docker Ollama (default, zero config) or point to your own Ollama instance (native install -GPU access-, remote server, etc.). Configure via `OLLAMA_MODE`, `OLLAMA_URL`, `EMBEDDING_MODEL` and `EMBEDDING_DIMENSIONS` environment variables.\n- **Multi-provider embeddings** — Switch between Local Ollama (private, GPU access), Docker Ollama (zero-config), OpenAI (`text-embedding-3-small`, fastest), or Google Gemini (`gemini-embedding-001`, free tier) with a single environment variable. No provider-specific configuration files.\n- **Private & secure** — Everything runs on your machine — your code never leaves your network. The default Docker setup includes Ollama (embeddings) and Qdrant (vector storage) with no external API calls. No API costs, no token limits. Suitable for air-gapped and on-premises environments. Optional cloud providers (OpenAI, Google Gemini, Qdrant Cloud) are available but never required.\n- **AST-aware chunking** — Files are split at function\u002Fclass boundaries using AST parsing (ast-grep), not arbitrary line counts. This produces higher-quality search results. Falls back to line-based chunking for unsupported languages.\n- **Polyglot code dependency graph** — Static analysis of import\u002Frequire\u002Fuse\u002Finclude statements using ast-grep for 18+ languages. No external tools like dependency-cruiser required. Detects circular dependencies and generates visual Mermaid diagrams.\n- **Language-agnostic** — Works with every programming language, framework, and file type out of the box. No per-language parsers to install, no grammar files to maintain, no \"unsupported language\" limitations. If your AI can read it, SocratiCode can index it.\n- **Incremental indexing** — After the first full index, only changed files are re-processed. Content hashes are persisted in Qdrant so state survives server restarts.\n- **Batched & resumable indexing** — Files are processed in batches of 50, with progress checkpointed to Qdrant after each batch. If the process crashes or is interrupted, the next run automatically resumes from where it left off — already-indexed files are skipped via hash comparison. This keeps peak memory low and makes indexing reliable even for very large codebases.\n- **Live file watching** — Optionally watch for file changes and keep the index updated in real time (debounced 2s). Watcher also invalidates the code graph cache.\n- **Parallel processing** — Files are scanned and chunked in parallel batches (50 at a time) for fast I\u002FO, while embedding generation and upserts are batched separately for optimal throughput.\n- **Multi-project** — Index multiple projects simultaneously. Each gets its own isolated collection with full project path tracking.\n- **Cross-project search** — Search across multiple related projects in a single query. Link projects via `.socraticode.json` or the `SOCRATICODE_LINKED_PROJECTS` env var, then set `includeLinked: true` on `codebase_search`. Results are tagged with project labels and deduplicated via client-side RRF fusion.\n- **Branch-aware indexing** — Maintain separate indexes per git branch by setting `SOCRATICODE_BRANCH_AWARE=true`. Each branch gets its own Qdrant collections, so switching branches instantly switches to the correct index. Ideal for CI\u002FCD pipelines and PR review workflows.\n- **Respects ignore rules** — Honors all `.gitignore` files (root + nested), plus an optional `.socraticodeignore` for additional exclusions. Includes sensible built-in defaults. `.gitignore` processing can be disabled via `RESPECT_GITIGNORE=false`. Dot-directories (e.g. `.agent`) can be included via `INCLUDE_DOT_FILES=true`.\n- **Custom file extensions** — Projects with non-standard extensions (e.g. `.tpl`, `.blade`) can be included via `EXTRA_EXTENSIONS` env var or `extraExtensions` tool parameter. Works for both indexing and code graph.\n- **Configurable infrastructure** — All ports, hosts, and API keys are configurable via environment variables. Qdrant API key support for enterprise deployments.\n- **Enterprise-ready simplicity** — No agent coordination tuning, no memory limit environment variables, no coordinator\u002Fconductor capacity knobs, no backpressure configuration. SocratiCode scales by relying on production-grade infrastructure (Qdrant, proven embedding APIs) rather than complex in-process orchestration.\n- **Auto-setup & zero configuration** — Just install the Claude Plugin\u002FSkill or add the MCP server to your AI host config. On first use, the server automatically checks Docker, pulls images, starts Qdrant and Ollama containers, and downloads the embedding model. No config files, no YAML, no environment variables to tune, no native dependencies to compile. Works everywhere Docker runs.\n- **Session resume** — When reopening a previously indexed project, the file watcher starts automatically on first tool use (search, status, update, or graph query). It catches any changes made since the last session and keeps the index live — no manual action needed.\n- **Auto-start watcher** — The file watcher is automatically activated when you use any SocratiCode tool on an indexed project. It starts after `codebase_index` completes, after `codebase_update`, and on the first `codebase_search`, `codebase_status`, or graph query. You can also start it manually with `codebase_watch { action: \"start\" }` if needed.\n- **Auto-build code graph** — The code dependency graph is automatically built after indexing and rebuilt when watched files change. No need to call `codebase_graph_build` manually unless you want to force a rebuild.\n- **Multi-agent collaboration** — Multiple AI agents (each running their own MCP instance) can work on the same codebase simultaneously and share a single index. One agent triggers indexing, all agents search against the same data. Only one watcher runs per project — every agent benefits from real-time updates. Cross-process file locking coordinates indexing and watching automatically. Ideal for workflows like one agent writing tests while another fixes code, or a planning agent and an implementation agent working in parallel.\n- **Cross-process safety** — File-based locking (`proper-lockfile`) prevents multiple MCP instances from simultaneously indexing or watching the same project. Stale locks from crashed processes are automatically reclaimed. When another MCP process is already watching a project, `codebase_status` reports \"active (watched by another process)\" instead of incorrectly showing \"inactive.\"\n- **Concurrency guards** — Duplicate indexing and graph-build operations are prevented. If you call `codebase_index` while indexing is already running, it returns the current progress instead of starting a second operation.\n- **Graceful stop** — Long-running indexing operations can be stopped safely with `codebase_stop`. The current batch finishes and checkpoints, preserving all progress. Re-run `codebase_index` to resume from where it left off.\n- **Graceful shutdown** — On server shutdown, active indexing operations are given up to 60 seconds to complete, all file watchers are stopped cleanly, and the everything closes gracefully.\n- **Structured logging** — All operations are logged with structured context for observability. Log level configurable via `SOCRATICODE_LOG_LEVEL`.\n- **Graceful degradation** — If infrastructure goes down during watch, the watcher backs off and retries instead of crashing.\n\n## Prerequisites\n\n| Dependency | Purpose | Install |\n|------------|---------|---------|\n| [Docker](https:\u002F\u002Fwww.docker.com\u002Fproducts\u002Fdocker-desktop\u002F) | Runs Qdrant (vector DB) and by default Ollama (embeddings) | [docker.com](https:\u002F\u002Fwww.docker.com\u002Fproducts\u002Fdocker-desktop\u002F) |\n| Node.js 18+ | Runs the MCP server | [nodejs.org](https:\u002F\u002Fnodejs.org\u002F) |\n\nDocker must be **running** when you use the server in the default `managed` mode. \n\nThe Qdrant container is managed automatically. If you set `QDRANT_MODE=external` and point `QDRANT_URL` at a remote or cloud Qdrant instance, Docker is only needed for Ollama (embeddings) in that case.\n\nThe Ollama container (embeddings) is also managed automatically in the default `auto` mode. SocratiCode first checks if Ollama is already running natively — if so it uses it. Otherwise it manages a Docker container for you. First-time download of the docker images or embedding models may take a few minutes, depending on your internet speed, and is required only at first launch.\n\n### Embedding performance on macOS \u002F Windows\n\nDocker containers on macOS and Windows cannot access the GPU (no Metal or CUDA passthrough). For small projects this is fine, but for medium-to-large codebases the CPU-only container is noticeably slower.\n\n**For best performance, install native Ollama:** download and run the installer from [ollama.com\u002Fdownload](https:\u002F\u002Follama.com\u002Fdownload). Once Ollama is running, SocratiCode will automatically detect and use it — no extra configuration needed (first-time download of the embedding model, if not present, might take a few minutes). This gives you Metal GPU acceleration on macOS and CUDA on Windows\u002FLinux.\n\nIf you prefer speed without a local install, see [OpenAI Embeddings](#openai-embeddings) and [Google Generative AI Embeddings](#google-generative-ai-embeddings) below for cloud-based options. OpenAI is very fast with no local setup required. Google’s free tier is functional but rate-limited. See [Environment Variables](#environment-variables) for configuration details.\n\n## Example Workflow\n\nAll tools default `projectPath` to the current working directory, so you never need to specify a path for the active project.\n\n```\nUser: \"Index this project\"\n→ codebase_index {}\n  ⚡ Indexing started in the background — call codebase_status to check progress\n→ codebase_status {}\n  ⚠ Full index in progress — Phase: generating embeddings (batch 1\u002F1)\n  Progress: 247\u002F1847 chunks embedded (13%) — Elapsed: 12s\n→ codebase_status {}\n  ✓ Indexing complete: 342 files, 1,847 chunks (took 115.2s)\n  File watcher: active (auto-updating on changes)\n\nUser: \"Search for how authentication is handled\"\n→ codebase_search { query: \"authentication handling\" }\n  Runs dense semantic search + BM25 keyword search in parallel, fuses results with RRF\n  Returns top 10 results ranked by combined relevance\n\nUser: \"What files depend on the auth middleware?\"\n→ codebase_graph_query { filePath: \"src\u002Fmiddleware\u002Fauth.ts\" }\n  Returns imports and dependents\n  (graph was auto-built after indexing — no manual build needed)\n\nUser: \"Show me the dependency graph\"\n→ codebase_graph_visualize {}\n  Returns a Mermaid diagram color-coded by language\n\nUser: \"Are there any circular dependencies?\"\n→ codebase_graph_circular {}\n  Found 2 cycles: src\u002Fa.ts → src\u002Fb.ts → src\u002Fa.ts\n```\n\n## Agent Instructions\n\n> **Claude Code plugin users**: These instructions are included automatically as skills in the SocratiCode plugin. You don't need to copy them into `CLAUDE.md`. The section below is for non-Claude Code hosts (VS Code, Cursor, Claude Desktop, etc.).\n\nFor best results, add instructions like the following to your AI assistant's project-level instructions file. The core principle: **search before reading**. The index gives you a map of the codebase in milliseconds; raw file reading is expensive and context-consuming.\n\n**Where to place these instructions** (per IDE):\n\n| IDE \u002F Tool | Instructions file |\n|:-----------|:-----------------|\n| Claude Code | `CLAUDE.md` at project root (auto-loaded). Plugin users get this via skills automatically. |\n| Cursor | `AGENTS.md` at project root, or `.cursor\u002Frules\u002Fsocraticode.mdc` for a dedicated rule file |\n| VS Code Copilot | `.github\u002Fcopilot-instructions.md`, or a custom instructions file in your VS Code User prompts folder |\n| Zed | `AGENTS.md` at project root (Zed auto-reads it), or use the Rules Library to create a default rule |\n| Windsurf | `.windsurfrules` at project root |\n| Claude Desktop \u002F Cline \u002F Roo Code | Add directly to your system prompt configuration |\n\n> **Why this matters**: Installing the MCP server alone gives your agent access to SocratiCode tools, but the agent still decides when to use them. Adding these instructions to your project ensures the agent consistently prefers SocratiCode search over raw file reads, uses the graph for dependency-aware tasks, and follows the search-before-reading workflow.\n\n```markdown\n## Codebase Search (SocratiCode)\n\nThis project is indexed with SocratiCode. Always use its MCP tools to explore the codebase\nbefore reading any files directly.\n\n### Workflow\n\n1. **Start most explorations with `codebase_search`.**\n   Hybrid semantic + keyword search (vector + BM25, RRF-fused) runs in a single call.\n   - Use broad, conceptual queries for orientation: \"how is authentication handled\",\n     \"database connection setup\", \"error handling patterns\".\n   - Use precise queries for symbol lookups: exact function names, constants, type names.\n   - Prefer search results to infer which files to read — do not speculatively open files.\n   - **When to use grep instead**: If you already know the exact identifier, error string,\n     or regex pattern, grep\u002Fripgrep is faster and more precise — no semantic gap to bridge.\n     Use `codebase_search` when you're exploring, asking conceptual questions, or don't\n     know which files to look in.\n\n2. **Follow the graph before following imports.**\n   Use `codebase_graph_query` to see what a file imports and what depends on it before\n   diving into its contents. This prevents unnecessary reading of transitive dependencies.\n   - **Before modifying or deleting a file**, check its dependents with `codebase_graph_query`\n     to understand the blast radius.\n   - **When planning a refactor**, use the graph to identify all affected files before\n     making changes.\n\n3. **Read files only after narrowing down via search.**\n   Once search results clearly point to 1–3 files, read only the relevant sections.\n   Never read a file just to find out if it's relevant — search first.\n\n4. **Use `codebase_graph_circular` when debugging unexpected behavior.**\n   Circular dependencies cause subtle runtime issues; check for them proactively.\n   Also run `codebase_graph_circular` when you notice import-related errors or unexpected\n   initialization order.\n\n5. **Check `codebase_status` if search returns no results.**\n   The project may not be indexed yet. Run `codebase_index` if needed, then wait for\n   `codebase_status` to confirm completion before searching.\n\n6. **Leverage context artifacts for non-code knowledge.**\n   Projects can define a `.socraticodecontextartifacts.json` config to expose database\n   schemas, API specs, infrastructure configs, architecture docs, and other project\n   knowledge that lives outside source code. These artifacts are auto-indexed alongside\n   code during `codebase_index` and `codebase_update`.\n   - Run `codebase_context` early to see what artifacts are available.\n   - Use `codebase_context_search` to find specific schemas, endpoints, or configs\n     before asking about database structure or API contracts.\n   - If `codebase_status` shows artifacts are stale, run `codebase_context_index` to\n     refresh them.\n\n### When to use each tool\n\n| Goal | Tool |\n|------|------|\n| Understand what a codebase does \u002F where a feature lives | `codebase_search` (broad query) |\n| Find a specific function, constant, or type | `codebase_search` (exact name) or grep if you know already the exact string |\n| Find exact error messages, log strings, or regex patterns | grep \u002F ripgrep |\n| See what a file imports or what depends on it | `codebase_graph_query` |\n| Check blast radius before modifying or deleting a file | `codebase_graph_query` (look at dependents) |\n| Spot architectural problems | `codebase_graph_circular`, `codebase_graph_stats` |\n| Visualise module structure | `codebase_graph_visualize` |\n| Verify index is up to date | `codebase_status` |\n| Discover what project knowledge (schemas, specs, configs) is available | `codebase_context` |\n| Find database tables, API endpoints, infra configs | `codebase_context_search` |\n```\n\n> **Why semantic search first?** A single `codebase_search` call returns ranked, deduplicated snippets from across the entire codebase in milliseconds. This gives you a broad map at negligible token cost — far cheaper than opening files speculatively. Once you know which files matter, targeted reading is both faster and more accurate. That said, grep remains the right tool when you have an exact string or pattern — use whichever fits the query.\n\n> **Keep the connection alive during indexing.** Indexing runs in the background — the MCP server continues working even when not actively responding to tool calls. However, some MCP hosts might disconnect an idle MCP connection after a period of inactivity, which might cut off the background process. Instruct your AI to call `codebase_status` roughly every 60 seconds after starting `codebase_index` until it completes. This keeps the host connection active and provides real-time progress.\n## Configuration\n\n### Install\n\n#### Claude Code plugin (recommended for Claude Code users)\n\nThe SocratiCode plugin bundles both the MCP server and workflow skills that teach Claude how to use the tools effectively. One install gives you everything:\n\nFrom your shell:\n\n```bash\nclaude plugin marketplace add giancarloerra\u002Fsocraticode\nclaude plugin install socraticode@socraticode\n```\n\nOr from within Claude Code:\n\n```\n\u002Fplugin marketplace add giancarloerra\u002Fsocraticode\n\u002Fplugin install socraticode@socraticode\n```\n\nThe plugin includes:\n- **MCP server** — all 21 SocratiCode tools (search, graph, context artifacts, etc.)\n- **Exploration skill** — teaches Claude the search-before-reading workflow\n- **Management skill** — guides setup, indexing, watching, and troubleshooting\n- **Explorer agent** — delegatable subagent for deep codebase analysis\n\n> If you previously installed SocratiCode as a standalone MCP (`claude mcp add socraticode`), remove it after installing the plugin to avoid duplicates: `claude mcp remove socraticode`\n\n**Auto-updates:** Third-party plugins don't auto-update by default. To enable automatic updates, open `\u002Fplugin` → Marketplaces → select `socraticode` → Enable auto-update. To update manually:\n\nFrom your shell:\n\n```bash\nclaude plugin marketplace update socraticode\nclaude plugin update socraticode@socraticode\n```\n\nOr from within Claude Code:\n\n```\n\u002Fplugin marketplace update socraticode\n\u002Fplugin update socraticode@socraticode\n```\n\n**Configuring environment variables:** SocratiCode works with zero config for most users (local Ollama + managed Qdrant). If you need cloud embeddings, a remote Qdrant, or other customization:\n\n1. **Claude Code settings** (recommended) — add to `~\u002F.claude\u002Fsettings.json`:\n   ```json\n   {\n     \"env\": {\n       \"EMBEDDING_PROVIDER\": \"openai\",\n       \"OPENAI_API_KEY\": \"sk-...\"\n     }\n   }\n   ```\n   This works in all environments — CLI, VS Code, and JetBrains.\n\n2. **Shell profile** — set vars in `~\u002F.zshrc` or `~\u002F.bashrc`:\n   ```bash\n   export EMBEDDING_PROVIDER=openai\n   export OPENAI_API_KEY=sk-...\n   ```\n   Works when Claude Code is launched from a terminal. Note: IDE-launched sessions (e.g. VS Code opened from Finder\u002FDock) may not inherit shell profile variables — use option 1 instead.\n\nRestart Claude Code after changing variables. See [Environment Variables](#environment-variables) for all options.\n\n#### npx (recommended for all other MCP hosts — no installation)\n\nRequires Node.js 18+ and Docker (running). Already covered in [Quick Start](#quick-start) above, add the following to your `mcpServers` (Claude Desktop, Windsurf, Cline, Roo Code) or `servers` (VS Code project-local `.vscode\u002Fmcp.json`) config:\n\n```json\n    \"socraticode\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"socraticode\"]\n    }\n```\n\n#### Zed\n\nAdd SocratiCode as a custom MCP server in Zed's settings (`Zed > Settings > Settings` or `cmd+,`). Under `context_servers`, add:\n\n```json\n{\n  \"context_servers\": {\n    \"socraticode\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"socraticode\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\nTo pass environment variables (e.g. for cloud embeddings or branch-aware indexing), add them to the `env` object:\n\n```json\n{\n  \"context_servers\": {\n    \"socraticode\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"socraticode\"],\n      \"env\": {\n        \"EMBEDDING_PROVIDER\": \"openai\",\n        \"OPENAI_API_KEY\": \"sk-...\"\n      }\n    }\n  }\n}\n```\n\nZed auto-reads `AGENTS.md` from the project root for agent instructions. Copy the [Agent Instructions](#agent-instructions) block into your project's `AGENTS.md` to ensure the agent uses SocratiCode tools effectively. You can also add them as a default rule in Zed's Rules Library (`agent: open rules library`).\n\n#### From source (for contributors)\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode.git\ncd socraticode\nnpm install\nnpm run build\n```\n\nThen use `node \u002Fabsolute\u002Fpath\u002Fto\u002Fsocraticode\u002Fdist\u002Findex.js` in place of `npx -y socraticode` in the config examples below.\n\n### MCP host config variants\n\n> All `env` options below apply equally to the `npx` install. Just add the `\"env\"` block to the npx config shown above.\n\nAdd to your MCP settings - `mcpServers` (Claude Desktop, Windsurf, Cline, Roo Code) or `servers` (VS Code project-local `.vscode\u002Fmcp.json`):\n\n#### Default (zero config, from source)\n\n> Using **npx**? Your config is already in [Quick Start](#quick-start). Add any `\"env\"` block from the examples below as needed.\n\n```json\n{\n  \"mcpServers\": {\n    \"socraticode\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fsocraticode\u002Fdist\u002Findex.js\"]\n    }\n  }\n}\n```\n\n> **Tip**: The default `OLLAMA_MODE=auto` detects native Ollama (port 11434) on startup and uses it if available, otherwise falls back to a managed Docker container. To make your config self-documenting, add an `\"env\"` block with explicit values. See [Environment Variables](#environment-variables) for all options.\n\n#### External Ollama (native install)\n\nIf you have [Ollama](https:\u002F\u002Follama.com) installed natively, set `OLLAMA_MODE=external` and point to your instance:\n\n```json\n{\n  \"mcpServers\": {\n    \"socraticode\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fsocraticode\u002Fdist\u002Findex.js\"],\n      \"env\": {\n        \"OLLAMA_MODE\": \"external\",\n        \"OLLAMA_URL\": \"http:\u002F\u002Flocalhost:11434\"\n      }\n    }\n  }\n}\n```\n\nThe embedding model is pulled automatically on first use. To pre-download: `ollama pull nomic-embed-text`\n\n#### Remote Ollama server\n\n```json\n{\n  \"mcpServers\": {\n    \"socraticode\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fsocraticode\u002Fdist\u002Findex.js\"],\n      \"env\": {\n        \"OLLAMA_MODE\": \"external\",\n        \"OLLAMA_URL\": \"http:\u002F\u002Fgpu-server.local:11434\"\n      }\n    }\n  }\n}\n```\n\n#### OpenAI Embeddings\n\nUse OpenAI's cloud embedding API instead of local Ollama. Requires an [API key](https:\u002F\u002Fplatform.openai.com\u002Fapi-keys).\n\n```json\n{\n  \"mcpServers\": {\n    \"socraticode\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fsocraticode\u002Fdist\u002Findex.js\"],\n      \"env\": {\n        \"EMBEDDING_PROVIDER\": \"openai\",\n        \"OPENAI_API_KEY\": \"sk-...\"\n      }\n    }\n  }\n}\n```\n\n> Defaults: `EMBEDDING_MODEL=text-embedding-3-small`, `EMBEDDING_DIMENSIONS=1536`. For higher quality, use `text-embedding-3-large` with `EMBEDDING_DIMENSIONS=3072`.\n\n#### Google Generative AI Embeddings\n\nUse Google's Gemini embedding API. Requires an [API key](https:\u002F\u002Faistudio.google.com\u002Fapikey).\n\n```json\n{\n  \"mcpServers\": {\n    \"socraticode\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fsocraticode\u002Fdist\u002Findex.js\"],\n      \"env\": {\n        \"EMBEDDING_PROVIDER\": \"google\",\n        \"GOOGLE_API_KEY\": \"AIza...\"\n      }\n    }\n  }\n}\n```\n\n> Defaults: `EMBEDDING_MODEL=gemini-embedding-001`, `EMBEDDING_DIMENSIONS=3072`.\n\n### Git Worktrees (shared index across directories)\n\nIf you use [git worktrees](https:\u002F\u002Fgit-scm.com\u002Fdocs\u002Fgit-worktree) — or any workflow where the same repository lives in multiple directories — each path would normally get its own Qdrant index. This means redundant embedding and storage for what is essentially the same codebase.\n\nSet `SOCRATICODE_PROJECT_ID` to share a single index across all directories of the same project.\n\n#### MCP hosts with git worktree detection (e.g. Claude Code)\n\nSome MCP hosts (like [Claude Code](https:\u002F\u002Fclaude.ai\u002Fclaude-code)) resolve the project root by following git worktree links. Since worktrees point back to the main repository's `.git` directory, the host automatically maps all worktrees to the same project config. This means you only need to configure the MCP server **once** for the main checkout — all worktrees inherit it automatically.\n\nFor Claude Code, add the server with local scope from your main checkout:\n\n```bash\ncd \u002Fpath\u002Fto\u002Fmain-checkout\nclaude mcp add -e SOCRATICODE_PROJECT_ID=my-project --scope local socraticode -- npx -y socraticode\n```\n\nAll worktrees created from this repo will automatically connect to socraticode with the shared project ID. No per-worktree setup needed.\n\n> **Note:** This only works for git worktrees. Separate `git clone`s of the same repo have independent `.git` directories and won't share the config.\n\n#### Other MCP hosts (per-project `.mcp.json`)\n\nFor MCP hosts that don't resolve git worktree paths, add a `.mcp.json` at the root of each worktree (and your main checkout):\n\n```json\n{\n  \"mcpServers\": {\n    \"socraticode\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"socraticode\"],\n      \"env\": {\n        \"SOCRATICODE_PROJECT_ID\": \"my-project\"\n      }\n    }\n  }\n}\n```\n\nAdd `.mcp.json` to your `.gitignore` if you don't want it tracked.\n\n#### How it works\n\nWith this config, agents running in `\u002Frepo\u002Fmain`, `\u002Frepo\u002Fworktree-feat-a`, and `\u002Frepo\u002Fworktree-fix-b` all share the same `codebase_my-project`, `codegraph_my-project`, and `context_my-project` Qdrant collections.\n\n**How it works in practice:**\n\n- The semantic index reflects whichever worktree last triggered a file change — but since branches typically differ by only a handful of files, the index is 99%+ accurate for all worktrees\n- Your AI agent reads actual file contents from its own worktree; the shared index is only used for discovery and navigation\n- When changes merge back to main, the file watcher re-indexes the changed files and the index converges\n\n### Cross-Project Search (linked projects)\n\nIf you work across multiple related repositories or packages, you can search them all in a single query.\n\n#### Configuration\n\nCreate a `.socraticode.json` file in your project root:\n\n```json\n{\n  \"linkedProjects\": [\n    \"..\u002Fshared-lib\",\n    \"\u002Fabsolute\u002Fpath\u002Fto\u002Fother-project\"\n  ]\n}\n```\n\nOr set the `SOCRATICODE_LINKED_PROJECTS` environment variable (comma-separated paths):\n\n```bash\nSOCRATICODE_LINKED_PROJECTS=\"..\u002Fshared-lib,\u002Fabsolute\u002Fpath\u002Fto\u002Fother-project\"\n```\n\nBoth sources are merged and deduplicated. Relative paths are resolved from the project root. Non-existent paths are silently skipped.\n\n#### Usage\n\nPass `includeLinked: true` to `codebase_search`:\n\n> Search for \"authentication middleware\" with includeLinked: true\n\nResults are tagged with `[project-name]` labels showing which project each result came from. The current project always has highest priority for deduplication — if the same file exists in multiple linked projects, the current project's version wins.\n\n> **Note:** Each linked project must be independently indexed (`codebase_index`) before it can be searched.\n\n### Branch-Aware Indexing\n\nBy default, all branches of a project share the same index. When you switch branches, changed files are re-indexed by the watcher, and the index reflects the current branch state.\n\nFor workflows where you need **separate, persistent indexes per branch** — such as CI\u002FCD pipelines or comparing code across branches — enable branch-aware mode:\n\n```bash\nSOCRATICODE_BRANCH_AWARE=true\n```\n\nWith this enabled, collection names include the branch name (e.g. `codebase_abc123__main`, `codebase_abc123__feat_my-feature`). Each branch maintains its own independent index, code graph, and context artifacts.\n\n**When to use:**\n- CI\u002FCD pipelines that index each branch\u002FPR separately\n- Comparing search results across branches\n- Keeping a pristine `main` index unaffected by feature branch changes\n\n**When NOT to use:**\n- Local development with frequent branch switching (default shared index is more efficient)\n- Projects tracked via `SOCRATICODE_PROJECT_ID` (explicit IDs bypass branch detection)\n\n> **How it works:** `projectIdFromPath()` detects the current git branch via `git rev-parse --abbrev-ref HEAD` and appends a sanitized branch suffix (e.g. `feat\u002Fmy-feature` → `feat_my-feature`) to the hash-based project ID. Detached HEAD states fall back to the branchless ID.\n\n### Available tools\n\nOnce connected, 21 tools are available to your AI assistant:\n\n#### Indexing\n\n| Tool | Description |\n|------|-------------|\n| `codebase_index` | Start indexing a codebase in the background (poll `codebase_status` for progress) |\n| `codebase_stop` | Gracefully stop an in-progress indexing operation (current batch finishes and checkpoints; resume with `codebase_index`) |\n| `codebase_update` | Incremental update — only re-indexes changed files |\n| `codebase_remove` | Remove a project's index (safely stops watcher, cancels in-flight indexing\u002Fupdate, waits for graph build) |\n| `codebase_watch` | Start\u002Fstop file watching — on start, catches up missed changes then watches for future ones |\n\n#### Search\n\n| Tool | Description |\n|------|-------------|\n| `codebase_search` | Hybrid semantic + keyword search (dense + BM25, RRF-fused) with optional file path, language filters, and cross-project search (`includeLinked`) |\n| `codebase_status` | Check index status and chunk count |\n\n#### Code Graph\n\n| Tool | Description |\n|------|-------------|\n| `codebase_graph_build` | Build a polyglot dependency graph (runs in background — poll with `codebase_graph_status`) |\n| `codebase_graph_query` | Query imports and dependents for a specific file |\n| `codebase_graph_stats` | Get graph statistics (most connected files, orphans, language breakdown) |\n| `codebase_graph_circular` | Detect circular dependencies |\n| `codebase_graph_visualize` | Generate a Mermaid diagram of the dependency graph |\n| `codebase_graph_status` | Check graph build progress or persisted graph metadata |\n| `codebase_graph_remove` | Remove a project's persisted code graph (waits for in-flight graph build to finish first) |\n\n#### Management\n\n| Tool | Description |\n|------|-------------|\n| `codebase_health` | Check Docker, Qdrant, and embedding provider status |\n| `codebase_list_projects` | List all indexed projects with paths and metadata |\n| `codebase_about` | Display info about SocratiCode |\n\n#### Context Artifacts\n\n| Tool | Description |\n|------|-------------|\n| `codebase_context` | List all context artifacts defined in `.socraticodecontextartifacts.json` with names, descriptions, and index status |\n| `codebase_context_search` | Semantic search across context artifacts (auto-indexes on first use, auto-detects staleness) |\n| `codebase_context_index` | Index or re-index all artifacts from `.socraticodecontextartifacts.json` |\n| `codebase_context_remove` | Remove all indexed context artifacts for a project (blocked while indexing is in progress) |\n\n## Language Support\n\nSocratiCode supports languages at three levels:\n\n### Full Support (indexing + code graph + AST chunking)\n\nJavaScript, TypeScript, TSX, Python, Java, Kotlin, Scala, C, C++, C#, Go, Rust, Ruby, PHP, Swift, Bash\u002FShell, HTML, CSS\u002FSCSS, Svelte, Vue\n\nSvelte and Vue: imports extracted from `\u003Cscript>` blocks (re-parsed as TypeScript) and CSS `@import`\u002F`@require` from `\u003Cstyle>` blocks (any combination of `lang`, `scoped`, `module`, `global` attributes). Path aliases from `tsconfig.json`\u002F`jsconfig.json` `compilerOptions.paths` are resolved (including `extends` chains). SCSS partial resolution (`_` prefix convention) is supported.\n\n### Code Graph via Regex + Indexing\n\nDart (import\u002Fexport\u002Fpart), Lua (require\u002Fdofile\u002Floadfile), SASS, LESS (CSS `@import` extraction)\n\n### Indexing Only (hybrid search, line-based chunking)\n\nJSON, YAML, TOML, XML, INI\u002FCFG, Markdown\u002FMDX, RST, SQL, R, Dockerfile, TXT, and any file matching a supported extension or special filename (Dockerfile, Makefile, Gemfile, Rakefile, etc.)\n\n**54 file extensions** + 8 special filenames supported out of the box.\n\n## Ignore Rules\n\nThe indexer combines three layers of ignore rules:\n\n1. **Built-in defaults** — `node_modules`, `.git`, `dist`, `build`, lock files, IDE folders, etc.\n2. **`.gitignore`** — All `.gitignore` files in the project (root and nested subdirectories). Set `RESPECT_GITIGNORE=false` to skip `.gitignore` processing entirely.\n3. **`.socraticodeignore`** — Optional file for indexer-specific exclusions. Same syntax as `.gitignore`.\n\n## Context Artifacts\n\nGive the AI awareness of project knowledge beyond source code — database schemas, API specs, infrastructure configs, architecture docs, and more.\n\n### Setup\n\nCreate a `.socraticodecontextartifacts.json` file in your project root (see [`.socraticodecontextartifacts.json.example`](.socraticodecontextartifacts.json.example) for a starter template):\n\n```json\n{\n  \"artifacts\": [\n    {\n      \"name\": \"database-schema\",\n      \"path\": \".\u002Fdocs\u002Fschema.sql\",\n      \"description\": \"Complete PostgreSQL schema — all tables, indexes, constraints, foreign keys. Use to understand what data the app stores and how tables relate.\"\n    },\n    {\n      \"name\": \"api-spec\",\n      \"path\": \".\u002Fdocs\u002Fopenapi.yaml\",\n      \"description\": \"OpenAPI 3.0 spec for the REST API. All endpoints, request\u002Fresponse schemas, auth requirements.\"\n    },\n    {\n      \"name\": \"k8s-manifests\",\n      \"path\": \".\u002Fdeploy\u002Fk8s\u002F\",\n      \"description\": \"Kubernetes deployment manifests. Shows how services are deployed, scaled, and networked.\"\n    }\n  ]\n}\n```\n\nEach artifact has:\n- **`name`** — Unique identifier (used to filter searches)\n- **`path`** — Path to a file or directory (relative to project root, or absolute). Directories are read recursively.\n- **`description`** — Tells the AI what this artifact is and how to use it\n\n### How it works\n\nArtifacts are chunked and embedded into Qdrant using the same hybrid dense + BM25 search as code. On first search, artifacts are auto-indexed. On subsequent searches, staleness is auto-detected via content hashing — changed files are re-indexed transparently.\n\n### Usage\n\n1. **Discover**: `codebase_context` — lists all defined artifacts and their index status\n2. **Search**: `codebase_context_search` — semantic search across all artifacts (or filter by name)\n3. **Re-index**: `codebase_context_index` — force re-index (usually not needed, auto-indexing handles it)\n4. **Clean up**: `codebase_context_remove` — remove all indexed artifacts\n\n### Why this matters: real workflow examples\n\nWithout artifacts, the agent only sees source code. With artifacts, it has the full picture and writes code that fits your project from the start.\n\n**Database schema** — You ask *\"add a last_login timestamp to users.\"* The agent runs `codebase_context_search` for \"users table\", finds the schema uses `snake_case` columns and every table has an `updated_at` with a trigger. The migration it writes matches existing conventions instead of guessing.\n\n```json\n{\n  \"name\": \"database-schema\",\n  \"path\": \".\u002Fdocs\u002Fschema.sql\",\n  \"description\": \"Complete PostgreSQL schema — all tables, columns, types, constraints, indexes, and triggers. Check this before writing migrations to match naming conventions and existing patterns.\"\n}\n```\n\n**API spec** — You ask *\"add a GET endpoint for user preferences.\"* The agent searches the OpenAPI spec, sees all endpoints use Bearer auth, return `{ data, meta }` wrappers, and paginate with `cursor`\u002F`limit`. The new endpoint follows the same patterns automatically.\n\n```json\n{\n  \"name\": \"api-spec\",\n  \"path\": \".\u002Fdocs\u002Fopenapi.yaml\",\n  \"description\": \"OpenAPI 3.0 spec for the REST API — all endpoints, request\u002Fresponse schemas, auth, pagination. Check this before adding or modifying endpoints to match existing conventions.\"\n}\n```\n\n**Domain glossary (DDD)** — You ask *\"add a way to cancel an order.\"* The agent searches your domain glossary, finds that cancellation is modeled as an `OrderVoided` event (not \"cancelled\"), that only orders in `Confirmed` status can be voided, and that the `Fulfillment` bounded context must be notified. The implementation uses the correct domain terms and integrates with the right bounded contexts.\n\n```json\n{\n  \"artifacts\": [\n    {\n      \"name\": \"ubiquitous-language\",\n      \"path\": \".\u002Fdocs\u002Fubiquitous-language.md\",\n      \"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.\"\n    },\n    {\n      \"name\": \"context-map\",\n      \"path\": \".\u002Fdocs\u002Fcontext-mapping.md\",\n      \"description\": \"Bounded context map — context boundaries, relationships (shared kernel, customer-supplier, etc.), and integration patterns. Check before implementing cross-context communication.\"\n    },\n    {\n      \"name\": \"event-storming\",\n      \"path\": \".\u002Fdocs\u002Fevent-storming\u002F\",\n      \"description\": \"Event storming output — domain events, commands, aggregates, policies, and read models. Check before adding new domain behavior to see how it fits the existing event flows.\"\n    }\n  ]\n}\n```\n\n> **The `description` field is the key lever.** It tells the AI not just *what* the artifact is, but *when to consult it*. Write descriptions that say \"check this before doing X\" so the agent reaches for the artifact at the right moment.\n\n### Example artifacts\n\n| Category | Examples |\n|----------|----------|\n| **Database** | SQL schema dumps (`pg_dump --schema-only`), Prisma schemas, Rails `schema.rb`, Django model dumps, migration files |\n| **API Contracts** | OpenAPI\u002FSwagger specs, GraphQL schemas, Protobuf definitions, AsyncAPI specs (Kafka, RabbitMQ) |\n| **Infrastructure** | Terraform\u002FPulumi configs, Kubernetes manifests, Docker Compose files, CI\u002FCD pipeline configs |\n| **Architecture** | Architecture Decision Records (ADRs), service topology docs, data flow diagrams, domain glossaries |\n| **Operations** | Monitoring\u002Falerting rules, RBAC\u002Fpermission matrices, auth flow documentation, feature flag configs |\n| **External** | Third-party API docs, compliance requirements (SOC2, HIPAA, GDPR), SLA definitions |\n\n> **Tip**: For database schemas, every major database can export its entire schema to a single file: `pg_dump --schema-only` (PostgreSQL), `mysqldump --no-data` (MySQL), `sqlite3 db.sqlite .schema` (SQLite). ORM schemas (Prisma, Rails, Django) are often already in your repo.\n\n## Environment Variables\n\n### Embedding Provider\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `EMBEDDING_PROVIDER` | `ollama` | Embedding backend: `ollama` (local, default), `openai`, or `google` |\n| `EMBEDDING_MODEL` | *(per provider)* | Model name. Defaults: `nomic-embed-text` (ollama), `text-embedding-3-small` (openai), `gemini-embedding-001` (google) |\n| `EMBEDDING_DIMENSIONS` | *(per provider)* | Vector dimensions. Defaults: `768` (ollama), `1536` (openai), `3072` (google) |\n| `EMBEDDING_CONTEXT_LENGTH` | *(auto-detected)* | Model context window in tokens. Auto-detected for known models. Set manually for custom models. |\n\n### Ollama Configuration (when `EMBEDDING_PROVIDER=ollama`)\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `OLLAMA_MODE` | `auto` | `auto` = use native Ollama on port 11434 if available, otherwise manage a Docker container (recommended). `docker` = always use managed Docker container on port 11435. `external` = user-managed Ollama instance (native, remote, etc.) |\n| `OLLAMA_URL` | `http:\u002F\u002Flocalhost:11434` (auto\u002Fexternal) \u002F `http:\u002F\u002Flocalhost:11435` (docker) | Full Ollama API endpoint |\n| `OLLAMA_PORT` | `11435` | Ollama container port (Docker mode). Ignored when `OLLAMA_URL` is set explicitly. |\n| `OLLAMA_HOST` | `http:\u002F\u002Flocalhost:{OLLAMA_PORT}` | Ollama base URL (alternative to `OLLAMA_URL`) |\n| `OLLAMA_API_KEY` | *(none)* | Optional API key for authenticated Ollama proxies |\n\n### Cloud Provider API Keys\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `OPENAI_API_KEY` | *(none)* | Required when `EMBEDDING_PROVIDER=openai`. Get from [platform.openai.com](https:\u002F\u002Fplatform.openai.com\u002Fapi-keys) |\n| `GOOGLE_API_KEY` | *(none)* | Required when `EMBEDDING_PROVIDER=google`. Get from [aistudio.google.com](https:\u002F\u002Faistudio.google.com\u002Fapikey) |\n\n### Qdrant Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `QDRANT_MODE` | `managed` | `managed` = Docker-managed local Qdrant (default). `external` = user-provided remote or cloud Qdrant (no Docker management). |\n| `QDRANT_URL` | *(none)* | Full URL of a remote\u002Fcloud Qdrant instance (e.g. `https:\u002F\u002Fxyz.aws.cloud.qdrant.io:6333`). When set, takes precedence over `QDRANT_HOST` + `QDRANT_PORT`. Port is auto-inferred from the URL: explicit port if present (e.g. `:8443`), otherwise `443` for `https:\u002F\u002F` or `6333` for `http:\u002F\u002F`. Required (or set `QDRANT_HOST`) when `QDRANT_MODE=external`. |\n| `QDRANT_PORT` | `16333` | Qdrant REST API port (managed mode, or external without `QDRANT_URL`) |\n| `QDRANT_GRPC_PORT` | `16334` | Qdrant gRPC port (managed mode only) |\n| `QDRANT_HOST` | `localhost` | Qdrant hostname (alternative to `QDRANT_URL` for non-HTTPS external instances) |\n| `QDRANT_API_KEY` | *(none)* | Qdrant API key (required for Qdrant Cloud and other authenticated deployments) |\n\n### Indexing Behavior\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `RESPECT_GITIGNORE` | `true` | Set to `false` to skip `.gitignore` processing. Built-in defaults and `.socraticodeignore` still apply. |\n| `INCLUDE_DOT_FILES` | `false` | Set to `true` to include dot-directories (e.g. `.agent`, `.config`) in indexing. By default, directories and files starting with `.` are excluded. Useful for projects where important code lives in dot-directories. |\n| `EXTRA_EXTENSIONS` | *(none)* | Comma-separated list of additional file extensions to scan (e.g. `.tpl,.blade,.hbs`). Applies to both indexing and code graph. Files with extra extensions are indexed as plaintext and appear as leaf nodes in the code graph. Can also be passed per-operation via the `extraExtensions` tool parameter. |\n| `MAX_FILE_SIZE_MB` | `5` | Maximum file size in MB. Files larger than this are skipped during indexing. Increase for repos with large generated or data files you want indexed. |\n| `SEARCH_DEFAULT_LIMIT` | `10` | Default number of results returned by `codebase_search` (1-50). Each result is a ranked code chunk with file path, line range, and content. Higher values give broader coverage but produce more output. Can still be overridden per-query via the `limit` tool parameter. |\n| `SEARCH_MIN_SCORE` | `0.10` | Minimum RRF (Reciprocal Rank Fusion) score threshold (0-1). Results below this score are filtered out. Helps remove low-relevance noise from search results. Set to `0` to disable filtering (returns all results up to `limit`). Can be overridden per-query via the `minScore` tool parameter. Works together with `limit`: results are first filtered by score, then capped at `limit`. |\n| `SOCRATICODE_PROJECT_ID` | *(none)* | Override the auto-generated project ID. When set, all paths resolve to the same Qdrant collections, allowing multiple directories (e.g. git worktrees of the same repo) to share a single index. Must match `[a-zA-Z0-9_-]+`. |\n| `SOCRATICODE_BRANCH_AWARE` | `false` | When `true`, append the current git branch name to the project ID, creating separate Qdrant collections per branch. Ignored when `SOCRATICODE_PROJECT_ID` is set. |\n| `SOCRATICODE_LINKED_PROJECTS` | *(none)* | Comma-separated list of additional project paths to include in cross-project search. Merged with paths from `.socraticode.json`. Non-existent paths are silently skipped. |\n| `SOCRATICODE_LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, `error` |\n| `SOCRATICODE_LOG_FILE` | *(none)* | Absolute path to a log file. When set, all log entries are appended to this file (a session separator is written on each server start). Useful for debugging when the MCP host doesn't surface log notifications. |\n\n> **Important**: If you change `EMBEDDING_PROVIDER`, `EMBEDDING_MODEL`, or `EMBEDDING_DIMENSIONS` after indexing, you must re-index your projects (`codebase_remove` then `codebase_index`) since existing vectors have different dimensions.\n\n## Docker Resources\n\nSocratiCode manages Docker containers and persistent volumes:\n\n| Resource | Name | Purpose | When |\n|----------|------|---------|------|\n| Container | `socraticode-qdrant` | Qdrant vector database (pinned `v1.17.0`) | `managed` mode only |\n| Container | `socraticode-ollama` | Ollama embedding server | `docker` mode only |\n| Volume | `socraticode_qdrant_data` | Persistent vector storage | `managed` mode only |\n| Volume | `socraticode_ollama_data` | Persistent model storage | `docker` mode only |\n\nIn `QDRANT_MODE=external` mode, the Qdrant container and volume are not created or started — SocratiCode connects directly to the configured remote endpoint. Server-side BM25 inference (used for hybrid search) requires **Qdrant v1.15.2 or later**. The managed container runs `v1.17.0`. If you bring your own Qdrant instance, ensure it meets this minimum.\n\nAll containers use `--restart unless-stopped` for automatic recovery.\n\n> **Why non-standard ports?** SocratiCode intentionally uses non-default ports for its managed containers — `16333`\u002F`16334` instead of Qdrant's defaults (`6333`\u002F`6334`), and `11435` instead of Ollama's default (`11434`). This avoids conflicts with any Qdrant or Ollama instance you may already be running locally. All ports are overridable via environment variables if needed.\n\n## Testing\n\nSocratiCode has a comprehensive test suite with **634 tests** across unit, integration, and end-to-end layers.\n\n### Prerequisites\n\n- **Unit tests**: No external dependencies required.\n- **Integration & E2E tests**: Require Docker running with Qdrant and Ollama containers. Containers are managed automatically by the test infrastructure.\n\n### Running Tests\n\n```bash\n# Run all tests\nnpm test\n\n# Run only unit tests (no Docker needed)\nnpm run test:unit\n\n# Run integration tests (requires Docker)\nnpm run test:integration\n\n# Run end-to-end tests (requires Docker)\nnpm run test:e2e\n\n# Watch mode (re-runs on file changes)\nnpm run test:watch\n\n# With coverage report\nnpm run test:coverage\n```\n\n### Test Architecture\n\n| Layer | Tests | Docker? | Description |\n|-------|-------|---------|-------------|\n| **Unit** (`tests\u002Funit\u002F`) | 477 | No | Config, constants, ignore rules, cross-process locking, logging, graph analysis, import extraction, path resolution, embedding config, indexer utilities, embeddings, startup lifecycle, watcher cross-process awareness |\n| **Integration** (`tests\u002Fintegration\u002F`) | 137 | Yes | Docker\u002FOllama setup, Qdrant CRUD, real embeddings, indexer, watcher, code graph, all MCP tools |\n| **E2E** (`tests\u002Fe2e\u002F`) | 20 | Yes | Complete lifecycle: health → index → search → graph → watch → remove  |\n\nIntegration and E2E tests that require Docker are automatically skipped when Docker is not available.\n\n## Why Not Just Grep?\n\nModern evaluations on real repositories show that hybrid lexical + semantic code search consistently outperforms plain grep once you care about natural-language queries, large codebases, or coding agents: reports show ~20% search-quality gains from BM25F ranking at scale, AST-aware retrieval improving recall and bug-fix performance on RepoEval and SWE-bench, and hybrid approach with grep (the default in SocratiCode) beats grep in 70% of agentic code-search tasks while cutting search operations by over half.\n\n### Real-world benchmark: VS Code (2.45M lines of code) with Claude Opus 4.6\n\nRunning a head-to-head comparison against the VS Code codebase (~2.45 million lines of TypeScript\u002FJavaScript across 5,300+ files, 55,437 indexed chunks) to measure what a Claude Opus 4.6 AI agent actually consumes when answering architectural questions.\n\n**Methodology:** For each question, the **grep approach** follows the realistic multi-step workflow an AI agent uses today: `grep -rl` to find matching files, identify core files, read them in chunks (200 lines at a time), and repeat until it has enough context. The **SocratiCode approach** performs a single semantic search call that returns the 10 most relevant code chunks from across the entire codebase.\n\n| Question | Grep (bytes) | SocratiCode (bytes) | Reduction | Speedup |\n|:---------|:-------------|:--------------------|:----------|:--------|\n| How does VS Code implement workspace trust restrictions? | 56,383 | 21,149 | **62.5%** | **49.7x** |\n| How does the diff editor compute and display text differences? | 37,650 | 15,961 | **57.6%** | **40.2x** |\n| How does VS Code handle extension activation and lifecycle? | 36,231 | 16,181 | **55.3%** | **34.4x** |\n| How does the integrated terminal spawn and manage shells? | 50,159 | 22,518 | **55.1%** | **31.1x** |\n| How does VS Code implement the command palette and quick pick? | 70,087 | 20,676 | **70.5%** | **31.7x** |\n| **Total** | **250,510** | **96,485** | **61.5%** | **37.2x** |\n\n**Key findings:**\n\n- **84% fewer tool calls** — Grep needed 31 steps across the 5 questions (6-7 per question). SocratiCode: 5 steps total (1 per question).\n- **61.5% less data consumed** — The AI agent processes ~150KB less context, which directly reduces token costs with any LLM.\n- **37x faster** — Grep scans across 2.45M lines can take up 2-3.5 seconds per question. Semantic search up to 60-90ms.\n\n> **Note:** This benchmark is _conservative_ for the grep approach. It assumes the agent already knows which files to read. In practice, a real AI agent needs additional exploratory grep calls, follows dead ends, reads irrelevant files, and often needs multiple rounds of narrowing. The actual savings might be larger.\n\n### When hybrid search wins\n\n**Natural-language and conceptual queries** — Queries like *\"Where do we handle database connection pooling?\"* or *\"How does this library implement exponential backoff?\"* describe behavior rather than naming a function. Evaluations on repository-level benchmarks (RepoEval, SWE-bench) show that AST-aware semantic retrieval improves recall by up to 4.3 points and downstream code-generation accuracy by ~2.7 points compared to fixed line-based chunks. Agentic evaluations on real open-source repos show a 70% win rate for hybrid search over vanilla grep on hard, conceptual questions — with 56% fewer search operations and ~60,000 fewer tokens per complex query.\n\n**Large repos and monorepos** — At multi-million LOC scale, full-text scans become expensive. Production search engines report ~20% relevance improvement from BM25F ranking over previous approaches, and use it as the first-stage retriever for semantic reranking. Hybrid search backed by inverted and vector indexes avoids full scans entirely, making it both faster and more precise at scale. Industry practitioners explicitly note that grep and find \"don't scale well to millions of files\" and that optimized embedding-based indexes can be faster at that scale.\n\n**Cross-file and cross-language reasoning** — Finding all code paths that eventually call an internal helper across services, or mapping a natural-language spec to implementations in Go and SQL, requires understanding that goes beyond string matching. Evaluations show that hybrid pipelines with tree-sitter parsing and dependency context outperform grep when naming is non-obvious and semantic understanding is needed. AST-based chunking with learned retrievers improves retrieval in cross-language benchmarks, and multi-vector semantic models show large gains over BM25 alone across diverse code search tasks (AppsRetrieval, CodeSearchNet, CosQA) where queries are in natural language and targets span many languages.\n\n**Mixed code + context artifacts** — Questions like *\"Where is rate-limiting configured?\"* might match Nginx configs, Terraform files, or YAML — not just application code. Hybrid search over mixed technical corpora (structured fields + free text) consistently outperforms pure lexical or pure vector approaches in published evaluations.\n\n### When grep still wins\n\nThe same research makes clear when grep (or ripgrep) is entirely reasonable — and sometimes optimal:\n\n- **You know the exact identifier, error string, or regex pattern.** No semantic gap to bridge.\n- **The repo is modest in size** — full scans are cheap and fast.\n- **Content is limited and structured code with distinctive names**, not prose or documentation.\n\nOn easy or directly-named queries, grep can match or beat semantic methods. That's why the best architectures don't replace grep — they extend it. SocratiCode's hybrid approach runs both BM25 keyword search and dense semantic search on every query, fusing results via RRF, so you get the precision of exact matching and the recall of semantic understanding in a single call.\n\n## FAQ\n\n### Indexing failed with an error — can I resume without starting over?\n\nYes. Indexing automatically resumes from where it left off. The indexer checkpoints\nfile hashes after every batch of files. When you ask your AI to index again (e.g. *\"index\nthis project\"*), it detects the existing data, skips every file that was already successfully\nembedded, and only re-processes the files that weren't checkpointed before the failure.\nAlready-indexed chunks are never deleted or re-embedded. Just ask your AI to index again and\nit will pick up where it stopped.\n\n### My MCP host disconnects while indexing a large codebase. What should I do?\n\nIndexing runs in the background on the MCP server. However, some MCP hosts (VS Code,\nClaude Desktop, etc.) disconnect an idle connection after a period of inactivity, which\nkills the background process. To keep the connection alive, ask your AI to check status\n(e.g. *\"check indexing status\"*) roughly every 60 seconds after starting indexing until it\ncompletes. If the connection does drop and indexing is interrupted, just ask your AI to\nindex again — it resumes automatically (see above).\n\n### Indexing keeps failing or won't resume properly. What should I do?\n\nIf indexing repeatedly fails, throws errors on resume, or gets stuck in a loop, the\nsimplest fix is to start fresh: ask your AI to *\"remove the index for this project\"*, then\nask it to index again. This clears all stored chunks and metadata for the project and\nbegins a clean re-index. It won't affect other indexed projects.\n\n### My codebase is very large — can I pause indexing and resume it later?\n\nYes. You can stop indexing at any time and resume it later without losing progress:\n\n1. **Ask your AI assistant to stop** — say something like *\"stop indexing\"* and it will\n   cancel the current operation at the next batch boundary. All batches completed so far\n   are checkpointed and preserved.\n2. **Or just close your project\u002Feditor** — SocratiCode detects the disconnection and shuts\n   down gracefully, preserving all checkpointed progress.\n3. **Come back whenever you want** — reopen the same project in your editor and ask the AI\n   to resume indexing (e.g. *\"resume indexing\"*). SocratiCode detects the incomplete index\n   automatically, skips every file already embedded, and picks up exactly where it left off.\n\nThis makes indexing very large codebases practical even on slower hardware — you can index in\nmultiple sessions across hours or days, and no work is ever repeated or lost.\n\n### I reopened my project but new\u002Fchanged files aren't showing up in search results.\n\nThe file watcher auto-starts on first tool use for any previously indexed project. When it\nstarts, it catches up all files modified while SocratiCode was down before watching for\nfuture changes.\n\nIf you want to force an immediate catch-up before searching, ask your AI to *\"start watching\nthis project\"* or *\"update the index\"* — both run an incremental update synchronously and\nthen start watching.\n\nThe watcher will not auto-start if a full index or incremental update is currently in\nprogress, if the project has not been indexed yet, or if another MCP process is already\nwatching the same project.\n\n### Can multiple AI agents work on the same codebase at the same time?\n\nYes — this is a first-class supported workflow. When multiple agents (each running their own MCP server instance) are pointed at the same project directory, they automatically share the same Qdrant index. The first agent to trigger indexing acquires a cross-process lock and builds the index; any other agent that tries to index simultaneously receives current progress instead of starting a duplicate operation. All agents can search concurrently with no coordination needed — Qdrant handles parallel reads natively.\n\nThe file watcher also coordinates automatically: only one process watches per project. Other instances detect this and skip watcher startup. When the watching process picks up a file change, it updates the shared index — and every agent's next search sees the updated results.\n\nIf the agent that owns the watcher or indexing lock crashes, its lock goes stale after 2 minutes and another agent's next interaction automatically reclaims it. No manual intervention needed.\n\nThis makes SocratiCode ideal for multi-agent workflows: one agent writing tests while another fixes code, a planning agent and an implementation agent working in parallel, or any combination of AI assistants sharing deep codebase knowledge without duplicating work.\n\n### Can I index multiple projects at the same time?\n\nYes. SocratiCode maintains a separate isolated collection for each project path. Ask your\nAI to *\"list all indexed projects\"* to see everything currently indexed.\n\n### What happens if I change my embedding provider or model?\n\nEach collection is created with a fixed vector size matching the model used at index time.\nIf you change `EMBEDDING_PROVIDER`, `EMBEDDING_MODEL`, or `EMBEDDING_DIMENSIONS` in your\nMCP config, any projects indexed with the old model will return a dimension mismatch error.\nAsk your AI to *\"remove the index for this project\"* and then to index again with the new\nmodel. Projects you haven't touched are unaffected.\n\n### How do I remove a project's index (e.g. to switch embedding model or reindex from scratch)?\n\n1. **Stop first** — if indexing is in progress, say *\"stop indexing this project\"*. Removing\n   while indexing is active would corrupt data, so the remove will be refused until the\n   current batch finishes.\n2. **Remove** — say *\"remove the index for this project\"*. This deletes the vector\n   collection, all stored chunk metadata, the code graph, and context artifact metadata for\n   that project only. Other projects are untouched.\n3. **Re-index** — update your MCP config with the new parameters if needed, then say\n   *\"index this project\"* to start fresh.\n\n### What is the code behind Socrates face in the SocratiCode logo?\n\nThe code you see behind Socrates is part of the original Apollo 11 guidance computer (AGC) source code for Command Module (Comanche055)!\n\n\n## Community\n\n- 💬 **[Discord](https:\u002F\u002Fdiscord.gg\u002F5DrMXfNG)** — chat with users and maintainers, ask \"how do I…\", share what you're building\n- 🐛 **[GitHub Issues](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fissues)** — bug reports and confirmed feature requests (please use the templates)\n- 📣 **Releases** — *Watch* the repo (top-right on GitHub → *Custom* → *Releases*) to be notified of new versions\n\nIf SocratiCode is useful to you, the single most helpful thing you can do is ⭐ **star the repo** — it's how others discover the project.\n\n---\n\n## SocratiCode Cloud\n\nThe full SocratiCode engine is — and will remain — free and open-source under AGPL-3.0. **SocratiCode Cloud** is an optional hosted version on top of the same engine, currently in **private beta**, for teams that want shared, managed, compliant infrastructure.\n\nWhat Cloud adds on top of the OSS engine:\n\n- **Shared team index** — every developer searches the same data, auto-indexed on every push across every branch\n- **Cross-repo search** — query every repository your organisation owns in one call\n- **SSO \u002F SAML, audit logs, IP allowlisting** — built in, not a later upsell\n- **Deployment models** — managed cloud (EU\u002FUS), your own VPC (AWS\u002FGCP\u002FAzure), or fully air-gapped on-prem\n- **Web dashboard** — search, dependency graphs, artefacts, team and repo management\n- **Zero local infrastructure** — no Docker, no Qdrant, no Ollama for the team to manage\n\nCurrently onboarding a small number of engineering teams. **[Request early access →](https:\u002F\u002Fsocraticode.cloud)**\n\n> The open-source engine in this repository is and will always be the same engine that powers Cloud. No bait-and-switch, no feature gating of the OSS core. Cloud only adds the team, deployment and compliance layer around it.\n\n---\n\n## License\n\nSocratiCode is dual-licensed:\n\n- **Open Source** — [AGPL-3.0](LICENSE). Free to use, modify, and distribute.\n  If you modify SocratiCode and offer it as a network service, you must release\n  your modifications under AGPL-3.0.\n\n- **Commercial** — For organizations that need to use SocratiCode in proprietary\n  products or services without AGPL obligations. See [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL)\n  or contact [giancarlo@altaire.com](mailto:giancarlo@altaire.com).\n\nCopyright (C) 2026 Giancarlo Erra - Altaire Limited.\n\n### Third-Party Licenses\n\nSocratiCode includes open-source dependencies under their own licenses\n(MIT, Apache 2.0, ISC). See [THIRD-PARTY-LICENSES](THIRD-PARTY-LICENSES) for details.\n\n### Contributing\n\nContributions are welcome. By submitting a pull request, you agree to the\n[Contributor License Agreement](CLA.md).\n","\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fgiancarloerra_SocratiCode_readme_6b9a1753d8f4.png\" alt=\"SocratiCode logo\" \u002F>\n\u003C\u002Fp>\n\n# SocratiCode\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg\" alt=\"CI\">\u003C\u002Fa>\n  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-AGPL--3.0-blue.svg\" alt=\"License: AGPL-3.0\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fsocraticode\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fsocraticode.svg\" alt=\"npm version\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fnodejs.org\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnode-%3E%3D18-brightgreen.svg\" alt=\"Node.js >= 18\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fgiancarloerra\u002Fsocraticode?style=social\" alt=\"GitHub stars\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002F5DrMXfNG\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-Join-5865F2?logo=discord&logoColor=white\" alt=\"Discord\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#claude-code-plugin-recommended-for-claude-code-users\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude_Code-Install_Plugin-CC785C?style=flat-square&logoColor=white\" alt=\"Install Claude Code Plugin\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Finsiders.vscode.dev\u002Fredirect\u002Fmcp\u002Finstall?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FVS_Code-Install_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white\" alt=\"Install in VS Code\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Finsiders.vscode.dev\u002Fredirect\u002Fmcp\u002Finstall?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D&quality=insiders\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FVS_Code_Insiders-Install_MCP_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white\" alt=\"Install in VS Code Insiders\">\u003C\u002Fa>\n  \u003Ca href=\"cursor:\u002F\u002Fanysphere.cursor-deeplink\u002Fmcp\u002Finstall?name=socraticode&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNvY3JhdGljb2RlIl19\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCursor-Install_MCP_Server-F14C28?style=flat-square&logo=cursor&logoColor=white\" alt=\"Install in Cursor\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n> *\"唯一的好就是知识，唯一的恶就是无知。\"* — 苏格拉底\n\n**你的 AI 可以读代码。而 SocratiCode 能够理解它。**\n\n**开源的代码库上下文引擎：为任何 AI 提供对你整个代码库（以及基础设施）的即时自动化知识——大规模、零配置、完全私密、彻底免费。**\n\n\u003Cp align=\"center\">\n  感谢 \u003Ca href=\"https:\u002F\u002Faltaire.com\">Altaire Limited\u003C\u002Fa> 的赞助\n\u003C\u002Fp>\n\n> 如果 SocratiCode 对你有所帮助，请 ⭐ **给这个仓库加星** —— 这有助于其他人发现它——并将其分享给你的开发团队和其他开发者！\n>\n> 💬 有问题或只是想聊聊？欢迎加入我们的 [Discord](https:\u002F\u002Fdiscord.gg\u002F5DrMXfNG)。\n\n**一件事，做到极致：深度代码库智能——无需设置，没有冗余，完全自动。** SocratiCode 为 AI 助手提供对代码库的深度语义理解——混合搜索、跨项目搜索、多语言代码依赖图，以及可搜索的上下文工件（数据库模式、API 规范、基础设施配置、架构文档）。零配置——只需将其添加到 **任何 MCP 主机**，或者为 Claude Code、Cursor、VS Code Copilot、Codex 或 Gemini CLI 安装原生 **插件**。一切均由其自动管理。\n\n**生产就绪**，经过企业级大型代码库的实战考验（高达 **~4000 万行代码**）。采用 **批处理**方式，自动且可恢复的索引检查点会持续推进——暂停、崩溃、重启和中断都不会丢失进度。文件监视器会在每次文件更改时以及跨会话期间保持 **索引自动更新**。**支持多代理**——多个 AI 代理可以同时在同一代码库上工作，共享单个索引，并实现自动协调，且无需任何配置。\n\n**默认私密且本地运行**——Docker 处理一切，无需 API 密钥，数据不会离开你的机器。**云端就绪**，可用于嵌入（OpenAI、Google Gemini）和 Qdrant，并且在你需要时，还提供 **全套配置选项**。\n\n> **☁️ SocratiCode Cloud（私密测试版）**——基于与开源版本相同引擎的托管式共享团队索引，额外提供 SSO、审计日志、分支感知索引，以及 VPC \u002F 空气隔离部署选项。开源核心部分将永远免费。[申请提前访问 →](https:\u002F\u002Fsocraticode.cloud)\n\n首个基于 Qdrant 的 MCP\u002FClaude 插件\u002F技能，将自动管理、零配置的本地 Docker 部署与 **AST 感知的代码分块、混合语义 + BM25（RRF 融合）代码搜索**、多语言依赖 **图谱**及循环依赖可视化，以及可搜索的 **基础设施\u002FAPI\u002F数据库工件**相结合，形成一个专注、零配置且易于使用的代码智能引擎。\n\n> **在 VS Code 上的基准测试（245 万行）：** SocratiCode 使用的 **上下文减少了 61%**，**工具调用减少了 84%**，并且比基于 grep 的探索快了 **37 倍**——使用 Claude Opus 4.6 实时测试。[查看完整基准测试 →](#real-world-benchmark-vs-code-245m-lines-of-code-with-claude-opus-46)\n\n\u003Cp align=\"center\">\n\u003Ca href=\"https:\u002F\u002Fwww.star-history.com\u002F?repos=giancarloerra%2Fsocraticode&type=date&logscale=&legend=top-left\">\n \u003Cpicture>\n   \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"https:\u002F\u002Fapi.star-history.com\u002Fimage?repos=giancarloerra\u002Fsocraticode&type=date&theme=dark&legend=top-left\" \u002F>\n   \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fgiancarloerra_SocratiCode_readme_864584439e89.png\" \u002F>\n   \u003Cimg alt=\"Star History Chart\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fgiancarloerra_SocratiCode_readme_864584439e89.png\" \u002F>\n \u003C\u002Fpicture>\n\u003C\u002Fa>\n\u003C\u002Fp>\n\n## 目录\n\n- [快速入门](#quick-start)\n- [插件](#plugins)\n- [为什么选择 SocratiCode](#why-socraticode)\n- [功能](#features)\n- [先决条件](#prerequisites)\n- [示例工作流程](#example-workflow)\n- [代理指令](#agent-instructions)\n- [配置](#configuration)\n- [语言支持](#language-support)\n- [忽略规则](#ignore-rules)\n- [上下文工件](#context-artifacts)\n- [环境变量](#environment-variables)\n- [Docker 资源](#docker-resources)\n- [测试](#testing)\n- [为何不直接使用 grep？](#why-not-just-grep)\n- [常见问题解答](#faq)\n- [社区](#community)\n- [SocratiCode Cloud](#socraticode-cloud)\n- [许可证](#license)\n\n---\n\n## 快速入门\n\n> **仅需运行 [Docker](https:\u002F\u002Fwww.docker.com\u002Fproducts\u002Fdocker-desktop\u002F)。**\n\n**一键安装** — Claude Code、VS Code 和 Cursor：\n\n[![安装 Claude Code 插件](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude_Code-Install_Plugin-CC785C?style=flat-square&logoColor=white)](#claude-code-plugin-recommended-for-claude-code-users)\n[![在 VS Code 中安装](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FVS_Code-Install_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https:\u002F\u002Finsiders.vscode.dev\u002Fredirect\u002Fmcp\u002Finstall?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D) [![在 VS Code Insiders 中安装](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FVS_Code_Insiders-Install_MCP_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https:\u002F\u002Finsiders.vscode.dev\u002Fredirect\u002Fmcp\u002Finstall?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D&quality=insiders) [![在 Cursor 中安装](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCursor-Install_MCP_Server-F14C28?style=flat-square&logo=cursor&logoColor=white)](cursor:\u002F\u002Fanysphere.cursor-deeplink\u002Fmcp\u002Finstall?name=socraticode&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNvY3JhdGljb2RlIl19) \n\n**所有 MCP 主机** — 将以下内容添加到你的 `mcpServers`（Claude Desktop、Windsurf、Cline、Roo Code）或 `servers`（VS Code 项目本地的 `.vscode\u002Fmcp.json`）配置中：\n\n```json\n\"socraticode\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"socraticode\"]\n}\n```\n\n**Claude Code** — 安装插件（推荐，包含工作流技能以获得最佳效果）：\n\n从你的终端：\n\n```bash\nclaude plugin marketplace add giancarloerra\u002Fsocraticode\nclaude plugin install socraticode@socraticode\n```\n\n或者在 Claude Code 内部：\n\n```\n\u002Fplugin marketplace add giancarloerra\u002Fsocraticode\n\u002Fplugin install socraticode@socraticode\n```\n\n> **自动更新：** 安装后，打开 `\u002Fplugin` → 市场 → 选择 `socraticode` → 启用自动更新。\n\n或者仅作为 MCP 使用（不带技能）：\n\n```bash\nclaude mcp add socraticode -- npx -y socraticode\n```\n\n> **更新：** `npx` 在首次运行后会缓存包。要获取最新版本，请清除缓存并重启你的 MCP 主机：`rm -rf ~\u002F.npm\u002F_npx && claude mcp restart socraticode`。或者，在你的配置中使用 `npx -y socraticode@latest`，以便每次启动时都检查更新（速度稍慢）。\n\n**OpenCode** — 添加到你的 `opencode.json`（或 `opencode.jsonc`）：\n\n```json\n{\n  \"mcp\": {\n    \"socraticode\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"socraticode\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n**OpenAI Codex CLI** — 添加到 `~\u002F.codex\u002Fconfig.toml`：\n\n```toml\n[mcp_servers.socraticode]\ncommand = \"npx\"\nargs = [\"-y\", \"socraticode\"]\n```\n\n重启你的主机。首次使用时，SocratiCode 会自动拉取 Docker 镜像，启动自己的 Qdrant 和 Ollama 容器，并下载嵌入模型——这是一次性设置，根据你的网络情况大约需要 5 分钟。之后，它会在几秒钟内启动。\n\n**首次在项目上使用** — 询问你的 AI：“索引这个代码库”。索引会在后台运行；你可以询问“代码库索引状态如何？”来监控进度。根据代码库大小以及你是否使用 GPU 加速的 Ollama 或云端嵌入，首次索引可能需要几秒到几分钟不等（在 Macbook Pro M4 上首次索引超过 300 万行代码通常不到 10 分钟）。一旦完成，无需再次运行，你可以进行搜索、探索依赖图并查询上下文工件。\n\n**此后每次使用** — 直接使用工具（搜索、图表等）。在服务器启动时，SocratiCode 会自动检测之前已索引的项目，重启文件监视器，并执行增量更新以捕获服务器关闭期间发生的任何更改。如果索引被中断，它会从最后一个检查点自动恢复。你也可以通过 `codebase_watch { action: \"start\" }` 显式启动或重启监视器。\n\n> **macOS \u002F Windows 上的大规模代码库**：Docker 容器无法使用 GPU。对于中大型仓库，建议安装原生 Ollama（自动检测，无需更改配置）以获得 Metal\u002FCUDA 加速，或使用 [OpenAI 嵌入](#openai-embeddings)以提升速度而无需本地安装。[详细信息。](#embedding-performance-on-macos--windows)\n\n> **推荐：** 为了获得最佳效果，将 [代理指令](#agent-instructions) 添加到你的 AI 助手的系统提示或项目说明文件（`CLAUDE.md`、`AGENTS.md` 等）中。关键原则——**先搜索再阅读**——有助于你的 AI 有效利用 SocratiCode 的工具，避免不必要的文件读取。\n\n> **Claude Code 用户：** 如果你安装了 SocratiCode 插件，代理指令会自动作为技能包含在内——无需将其添加到你的 `CLAUDE.md` 中。该插件还捆绑了 MCP 服务器，因此你不需要单独执行 `claude mcp add`。\n\n> **高级选项：** 云端嵌入（OpenAI \u002F Google）、外部 Qdrant、远程 Ollama、原生 Ollama 以及数十种调优选项均可使用。请参阅下方的 [配置](#configuration)。\n\n## 插件\n\nSocratiCode 可在多个 AI 编码平台上作为原生插件使用。这些插件将 MCP 服务器与工作流技能和代理指令打包在一起——只需一次安装即可获得所有功能。\n\n| 平台 | 安装方法 |\n|:---------|:---------------|\n| Claude Code | `claude plugin marketplace add giancarloerra\u002Fsocraticode` — [完整说明](#claude-code-plugin-recommended-for-claude-code-users) |\n| Cursor | `\u002Fadd-plugin https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode` |\n| VS Code Copilot | 命令面板 → `Chat: 从源安装插件` → `https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode` |\n| Zed | 在 Zed 设置中添加为自定义 MCP 服务器 — [配置示例](#zed) |\n| Gemini CLI | `gemini extensions install https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode` |\n| OpenAI Codex | 尚未有公开的插件目录——使用 [MCP 配置](#quick-start) 或参阅下方的 **Codex 本地安装** |\n\n> **VS Code Copilot：** 聊天插件功能目前处于预览阶段。请在 VS Code 设置中启用 `chat.plugins.enabled: true`。\n\n> **Codex 本地插件安装：** 克隆仓库并在你的个人插件市场中注册：\n> ```bash\n> git clone https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode.git ~\u002F.agents\u002Fplugins\u002Fsocraticode\n> ```\n> 然后将其添加到 `~\u002F.agents\u002Fplugins\u002Fmarketplace.json` 中：\n> ```json\n> {\n>   \"plugins\": [\n>     {\n>       \"name\": \"socraticode\",\n>       \"path\": \"~\u002F.agents\u002Fplugins\u002Fsocraticode\"\n>     }\n>   ]\n> }\n> ```\n> 下次启动时，Codex 将从 `.codex-plugin\u002Fplugin.json` 中发现该插件。\n\n> **所有其他 MCP 主机**（Claude Desktop、Windsurf、Cline、Roo Code、OpenCode）：使用 [MCP 配置](#quick-start)——适用于任何支持 MCP 协议的主机。\n\n## 为什么选择 SocratiCode\n\n我创建 SocratiCode 的原因在于，我经常需要处理跨多种语言的大型复杂代码库，并且需要快速理解这些代码并采取行动。然而，现有的解决方案要么功能过于有限，要么未经过充分的生产环境测试，要么充斥着不必要的复杂性。我希望有一个专注、单一的工具，能够出色地提供深度的代码库智能分析——无需任何设置、没有冗余功能、完全自动化——并且不会干扰我的工作流程。\n\n### 内置代码搜索与 SocratiCode 对比\n\n| 功能 | Claude Code | Cursor | VS Code Copilot | + SocratiCode |\n|:--------|:-----------:|:------:|:---------------:|:-------------:|\n| 文本 \u002F grep 搜索 | ✅ | ✅ | ✅ | ✅ |\n| 语义搜索 | — | ✅ | ✅¹ | ✅ |\n| 混合搜索（融合） | — | — | — | ✅ |\n| 代码依赖图 | — | — | ✅² | ✅ |\n| 循环依赖检测 | — | — | — | ✅ |\n| 非代码知识（模式、API 规范） | — | — | — | ✅ |\n| 跨项目搜索 | — | — | — | ✅ |\n| 分支感知索引 | — | — | — | ✅ |\n| 多代理共享索引 | — | — | — | ✅ |\n| 工具无关（切换 AI 时仍可用） | — | — | — | ✅ |\n| 完全本地化 \u002F 私有 | ✅ | —³ | —⁴ | ✅ |\n| 可恢复索引 | — | — | — | ✅ |\n| 实时文件监控 | — | ✅ | — | ✅ |\n\n\u003Csub>¹ VS Code Copilot：通过 GitHub \u002F Azure DevOps 进行远程索引；本地“外部数据导入”功能正在逐步推出。 ² 基于 LSP 的“查找引用”\u002F“转到定义”（用法工具），并非完整的依赖图。 ³ Cursor：嵌入向量在 Cursor 服务器上处理（传输和存储过程中均加密）。 ⁴ VS Code Copilot：远程索引托管在 GitHub \u002F Azure DevOps 上。 来源：[Cursor 文档](https:\u002F\u002Fdocs.cursor.com\u002Fcontext\u002Fcodebase-indexing)、[Claude Code 文档](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Foverview)、[VS Code Copilot 文档](https:\u002F\u002Fcode.visualstudio.com\u002Fdocs\u002Fcopilot\u002Fchat\u002Fcodebase-context)。\u003C\u002Fsub>\n\n> **🔌 上下文与你的代码库绑定，而非与某个助手绑定。** 内置索引（Cursor 和 Copilot 的）仅与特定工具相关联——一旦更换助手，就需要从头开始。而 SocratiCode 是独立的：只需索引一次，即可将其接入 Claude Code、Cursor、Copilot、Windsurf，或你自己的私有模型，甚至同时接入所有工具。它们将共享对你的代码的统一理解。\n\n在 VS Code 的 245 万行代码库中，SocratiCode 在回答架构相关问题时，所需的数据量减少了 **61%**，步骤减少了 **84%**，响应速度更是快了 **37 倍**，相比基于 grep 的 AI 助手而言。[完整基准测试 →](#real-world-benchmark-vs-code-245m-lines-of-code-with-claude-opus-46)\n\n## 功能\n\n- **混合代码搜索** — 基于 Qdrant 构建，Qdrant 是一款专为向量检索设计的数据库，支持 HNSW 索引、并发读写以及负载过滤。每个代码块同时存储稠密向量和 BM25 稀疏向量；Query API 会在一次请求中并行执行这两个子查询，并使用倒排秩融合（RRF）对结果进行融合。语义搜索能够处理“认证中间件”这类概念性查询，即使代码中并未出现这些确切词汇。而 BM25 则负责精确的标识符和关键词查找。在每次查询中，您都能同时获得两者的最佳效果，无需任何调优。\n  \n- **可配置的 Qdrant** — 您可以使用内置的 Docker 版 Qdrant（默认设置，无需配置），也可以连接到您自己的实例（自托管、远程服务器或 Qdrant Cloud）。通过 `QDRANT_MODE`、`QDRANT_URL` 和 `QDRANT_API_KEY` 环境变量进行配置。\n  \n- **可配置的 Ollama** — 您可以使用内置的 Docker 版 Ollama（默认设置，无需配置），也可以指向您自己的 Ollama 实例（原生安装且支持 GPU、远程服务器等）。通过 `OLLAMA_MODE`、`OLLAMA_URL`、`EMBEDDING_MODEL` 和 `EMBEDDING_DIMENSIONS` 环境变量进行配置。\n  \n- **多提供商嵌入模型** — 仅需一个环境变量即可在本地 Ollama（私有，支持 GPU）、Docker 版 Ollama（零配置）、OpenAI (`text-embedding-3-small`, 最快) 或 Google Gemini (`gemini-embedding-001`, 免费层级) 之间切换。无需针对特定提供商的配置文件。\n  \n- **私密且安全** — 所有操作均在您的机器上运行——您的代码永远不会离开您的网络。默认的 Docker 部署包含 Ollama（嵌入生成）和 Qdrant（向量存储），不涉及任何外部 API 调用。无 API 费用，无令牌限制。适用于气隙环境和本地部署场景。虽然可以选择 OpenAI、Google Gemini 或 Qdrant Cloud 等云服务提供商，但并非必需。\n  \n- **AST 感知的分块** — 文件通过 AST 解析（ast-grep）在函数或类的边界处进行分割，而非按任意行数切分。这样可以生成更高质量的搜索结果。对于不支持的语言，则回退到基于行数的分块方式。\n  \n- **多语言代码依赖图** — 使用 ast-grep 对 18 种以上语言的 import\u002Frequire\u002Fuse\u002Finclude 语句进行静态分析。无需依赖 dependency-cruiser 等外部工具。能够检测循环依赖，并生成可视化的 Mermaid 图表。\n  \n- **语言无关性** — 开箱即用，支持所有编程语言、框架和文件类型。无需安装特定语言的解析器，无需维护语法文件，也不存在“不支持的语言”的限制。只要您的 AI 能够读取，SocratiCode 就能对其进行索引。\n  \n- **增量索引** — 在完成首次全量索引后，仅重新处理发生变更的文件。内容哈希值会持久化存储在 Qdrant 中，因此即使服务器重启，索引状态也能保持不变。\n  \n- **批处理与可恢复索引** — 文件以每批 50 个为单位进行处理，每处理完一批后都会将进度检查点记录到 Qdrant 中。如果进程崩溃或中断，下次运行时会自动从上次停止的地方继续，已索引的文件则通过哈希比对跳过。这种方式能够有效降低峰值内存占用，使索引过程即便面对超大规模代码库也十分可靠。\n  \n- **实时文件监控** — 可选择监控文件变化，并实时更新索引（防抖延迟 2 秒）。文件监控器还会失效代码图缓存。\n  \n- **并行处理** — 文件以并行批次（每次 50 个）扫描和分块，以实现快速 I\u002FO；而嵌入向量的生成和插入操作则单独分批进行，以优化吞吐量。\n  \n- **多项目支持** — 可同时索引多个项目。每个项目拥有独立的集合，并完整记录项目路径。\n  \n- **跨项目搜索** — 可在一次查询中跨多个相关项目进行搜索。通过 `.socraticode.json` 文件或 `SOCRATICODE_LINKED_PROJECTS` 环境变量链接项目，然后在 `codebase_search` 中设置 `includeLinked: true`。结果会打上项目标签，并通过客户端 RRF 融合去重。\n  \n- **分支感知索引** — 通过设置 `SOCRATICODE_BRANCH_AWARE=true`，可为每个 Git 分支维护独立的索引。每个分支都有自己的 Qdrant 集合，切换分支时会立即切换到正确的索引。非常适合 CI\u002FCD 流水线和 PR 审查工作流。\n  \n- **尊重忽略规则** — 会遵守所有 `.gitignore` 文件（根目录及嵌套目录），并额外支持一个可选的 `.socraticodeignore` 文件用于进一步排除。内置合理的默认规则。可通过 `RESPECT_GITIGNORE=false` 禁用 `.gitignore` 处理。如需包含点目录（例如 `.agent`），可设置 `INCLUDE_DOT_FILES=true`。\n  \n- **自定义文件扩展名** — 对于使用非标准扩展名的项目（如 `.tpl`、`.blade`），可通过 `EXTRA_EXTENSIONS` 环境变量或 `extraExtensions` 工具参数将其纳入索引。该功能同时适用于索引构建和代码依赖图生成。\n  \n- **可配置的基础设施** — 所有端口、主机和 API 密钥均可通过环境变量进行配置。Qdrant API 密钥支持企业级部署。\n  \n- **企业级的简易性** — 无需调整代理协调参数，无需设置内存限制的环境变量，无需调节协调器或指挥官的容量旋钮，也不需要配置背压机制。SocratiCode 依靠生产级基础设施（Qdrant、成熟的嵌入式 API）来实现扩展，而非复杂的进程内编排。\n  \n- **自动安装与零配置** — 您只需安装 Claude 插件\u002F技能，或将 MCP 服务器添加到您的 AI 主机配置中。首次使用时，服务器会自动检查 Docker 环境，拉取镜像，启动 Qdrant 和 Ollama 容器，并下载嵌入模型。无需配置文件、YAML 或环境变量调优，也不需要编译原生依赖项。只要 Docker 能运行，即可使用。\n  \n- **会话恢复** — 当重新打开一个已索引的项目时，首次使用任何工具（搜索、状态查询、更新或代码图查询）时，文件监控器会自动启动。它会捕获自上次会话以来的所有更改，并保持索引的实时更新——无需手动操作。\n  \n- **自动启动监控器** — 当您在已索引的项目上使用任何 SocratiCode 工具时，文件监控器会自动激活。它会在 `codebase_index` 完成后、`codebase_update` 完成后，以及首次进行 `codebase_search`、`codebase_status` 或代码图查询时启动。如有需要，您也可以通过 `codebase_watch { action: \"start\" }` 手动启动。\n  \n- **自动构建代码图** — 代码依赖图会在索引完成后自动构建，并在受监控的文件发生变化时重新构建。除非您想强制重建，否则无需手动调用 `codebase_graph_build`。\n  \n- **多智能体协作** — 多个 AI 代理（各自运行独立的 MCP 实例）可以同时在同一代码库上工作，并共享同一索引。由一个代理触发索引构建，所有代理都基于相同的数据进行搜索。每个项目仅运行一个文件监控器——所有代理都能受益于实时更新。跨进程文件锁机制会自动协调索引和监控操作。非常适合以下场景：一个代理编写测试用例，另一个代理修复代码；或者规划代理与实施代理并行工作。\n  \n- **跨进程安全性** — 基于文件的锁机制（`proper-lockfile`）可防止多个 MCP 实例同时对同一个项目进行索引或监控。来自崩溃进程的过期锁会自动回收。当已有其他 MCP 进程正在监控某个项目时，`codebase_status` 会报告“正在监控（由其他进程）”，而不是错误地显示“未监控”。\n  \n- **并发保护** — 可防止重复的索引和图构建操作。如果您在索引正在进行时再次调用 `codebase_index`，系统会返回当前进度，而不是启动第二次操作。\n  \n- **优雅停止** — 长时间运行的索引操作可以通过 `codebase_stop` 安全终止。当前批次会完成并保存检查点，从而保留所有进度。重新运行 `codebase_index` 即可从中断处继续。\n  \n- **优雅关机** — 服务器关闭时，正在运行的索引操作会被给予最多 60 秒完成剩余工作，所有文件监控器会干净地停止，整个系统也会平稳关闭。\n  \n- **结构化日志记录** — 所有操作都会附带结构化的上下文信息，便于可观ability 监控。日志级别可通过 `SOCRATICODE_LOG_LEVEL` 进行配置。\n  \n- **优雅降级** — 如果监控过程中基础设施出现故障，监控器会退避并重试，而不是直接崩溃。\n\n## 前置条件\n\n| 依赖项 | 用途 | 安装 |\n|------------|---------|---------|\n| [Docker](https:\u002F\u002Fwww.docker.com\u002Fproducts\u002Fdocker-desktop\u002F) | 运行 Qdrant（向量数据库）以及默认的 Ollama（嵌入模型） | [docker.com](https:\u002F\u002Fwww.docker.com\u002Fproducts\u002Fdocker-desktop\u002F) |\n| Node.js 18+ | 运行 MCP 服务器 | [nodejs.org](https:\u002F\u002Fnodejs.org\u002F) |\n\n在使用默认的 `managed` 模式时，Docker 必须处于**运行状态**。\n\nQdrant 容器会自动管理。如果你将 `QDRANT_MODE=external` 设置，并将 `QDRANT_URL` 指向远程或云端的 Qdrant 实例，则此时 Docker 仅用于 Ollama（嵌入模型）。\n\nOllama 容器（嵌入模型）在默认的 `auto` 模式下也会自动管理。SocratiCode 首先会检查本地是否已运行 Ollama——如果已运行则直接使用；否则会为你管理一个 Docker 容器。首次下载 Docker 镜像或嵌入模型可能需要几分钟时间，具体取决于你的网络速度，且仅在首次启动时需要。\n\n### 在 macOS \u002F Windows 上的嵌入性能\n\nmacOS 和 Windows 上的 Docker 容器无法访问 GPU（没有 Metal 或 CUDA 直通）。对于小型项目这并无大碍，但对于中大型代码库而言，仅使用 CPU 的容器会明显更慢。\n\n**为获得最佳性能，请安装原生 Ollama**：从 [ollama.com\u002Fdownload](https:\u002F\u002Follama.com\u002Fdownload) 下载并运行安装程序。一旦 Ollama 运行起来，SocratiCode 将自动检测并使用它——无需额外配置（如果嵌入模型尚未下载，首次下载可能需要几分钟）。这样在 macOS 上可以获得 Metal GPU 加速，在 Windows\u002FLinux 上则可利用 CUDA。\n\n如果你希望在不进行本地安装的情况下追求速度，可参阅下方的 [OpenAI Embeddings](#openai-embeddings) 和 [Google Generative AI Embeddings](#google-generative-ai-embeddings)，它们提供了基于云的服务选项。OpenAI 速度极快，且无需任何本地设置。而 Google 的免费层级虽然可用，但存在速率限制。有关配置详情，请参阅 [环境变量](#environment-variables)。\n\n## 示例工作流程\n\n所有工具的默认 `projectPath` 都是当前工作目录，因此你无需为当前项目指定路径。\n\n```\n用户: “索引这个项目”\n→ codebase_index {}\n  ⚡ 索引已在后台开始——调用 codebase_status 查看进度\n→ codebase_status {}\n  ⚠ 全量索引正在进行中——阶段：生成嵌入（批次 1\u002F1）\n  进度：已嵌入 247\u002F1847 个块（13%）——耗时：12 秒\n→ codebase_status {}\n  ✓ 索引已完成：共 342 个文件，1,847 个块（耗时 115.2 秒）\n  文件监听器：已启用（更改时自动更新）\n\n用户: “搜索身份验证是如何处理的”\n→ codebase_search { query: \"authentication handling\" }\n  并行执行密集语义搜索和 BM25 关键字搜索，并通过 RRF 融合结果\n  返回按综合相关性排序的前 10 条结果\n\n用户: “哪些文件依赖于认证中间件？”\n→ codebase_graph_query { filePath: \"src\u002Fmiddleware\u002Fauth.ts\" }\n  返回导入与被依赖文件\n  （图谱在索引完成后自动构建——无需手动构建）\n\n用户: “展示依赖关系图”\n→ codebase_graph_visualize {}\n  返回按语言着色的 Mermaid 图表\n\n用户: “是否存在循环依赖？”\n→ codebase_graph_circular {}\n  发现 2 个循环：src\u002Fa.ts → src\u002Fb.ts → src\u002Fa.ts\n```\n\n## 助手指令\n\n> **Claude Code 插件用户**：这些指令已作为技能自动包含在 SocratiCode 插件中，你无需将其复制到 `CLAUDE.md` 中。以下部分适用于非 Claude Code 用户（如 VS Code、Cursor、Claude Desktop 等）。\n\n为获得最佳效果，建议将如下指令添加到你的 AI 助手的项目级指令文件中。核心原则是：**先搜索再阅读**。索引可在毫秒级内为你提供代码库的地图；而直接读取文件则既昂贵又会消耗大量上下文。\n\n**这些指令应放置的位置**（按 IDE 分类）：\n\n| IDE \u002F 工具 | 指令文件 |\n|:-----------|:-----------------|\n| Claude Code | 项目根目录下的 `CLAUDE.md`（自动加载）。插件用户可通过技能自动获取此文件。 |\n| Cursor | 项目根目录下的 `AGENTS.md`，或创建专用规则文件 `.cursor\u002Frules\u002Fsocraticode.mdc` |\n| VS Code Copilot | `.github\u002Fcopilot-instructions.md`，或在 VS Code 用户提示文件夹中创建自定义指令文件 |\n| Zed | 项目根目录下的 `AGENTS.md`（Zed 会自动读取），或使用规则库创建默认规则 |\n| Windsurf | 项目根目录下的 `.windsurfrules` |\n| Claude Desktop \u002F Cline \u002F Roo Code | 直接添加到系统提示配置中 |\n\n> **为何如此重要**：仅安装 MCP 服务器即可使你的助手获得 SocratiCode 工具的访问权限，但助手仍会自行决定何时使用这些工具。将这些指令添加到项目中，可确保助手始终优先使用 SocratiCode 搜索而非直接读取文件，利用图谱完成依赖感知任务，并遵循“先搜索再读取”的工作流程。\n\n```markdown\n## 代码库搜索（SocratiCode）\n\n该项目已使用 SocratiCode 进行索引。在直接读取任何文件之前，请务必先使用其 MCP 工具探索代码库。\n\n### 工作流程\n\n1. **大多数探索都应从 `codebase_search` 开始。**\n   混合语义 + 关键词搜索（向量 + BM25，RRF 融合）可在一次调用中完成。\n   - 使用宽泛、概念性的查询来定位方向：例如“如何处理身份验证”、“数据库连接的设置”、“错误处理模式”。\n   - 使用精确的查询来进行符号查找：如确切的函数名、常量名或类型名。\n   - 优先根据搜索结果推断需要阅读哪些文件——不要盲目打开文件。\n   - **何时使用 grep**：如果你已经知道确切的标识符、错误字符串或正则表达式模式，grep\u002Fripgrep 会更快且更精确——无需跨越语义鸿沟。而当你在探索、提出概念性问题，或者不确定该查看哪些文件时，则应使用 `codebase_search`。\n\n2. **先查看依赖图，再逐级导入。**\n   在深入研究某个文件的内容之前，先使用 `codebase_graph_query` 查看该文件导入了哪些内容，以及哪些部分依赖于它。这样可以避免不必要地阅读传递性依赖项。\n   - **在修改或删除文件之前**，请通过 `codebase_graph_query` 检查其依赖关系，以了解可能的影响范围。\n   - **在计划重构时**，利用依赖图识别所有受影响的文件，然后再进行更改。\n\n3. **仅在通过搜索缩小范围后才阅读文件。**\n   当搜索结果明确指向 1–3 个文件时，只需阅读相关部分即可。切勿仅仅为了判断文件是否相关就直接阅读——务必先进行搜索。\n\n4. **调试意外行为时使用 `codebase_graph_circular`。**\n   循环依赖会导致微妙的运行时问题；应主动检查是否存在此类问题。此外，当遇到与导入相关的错误或初始化顺序不符合预期时，也应运行 `codebase_graph_circular`。\n\n5. **如果搜索未返回任何结果，请检查 `codebase_status`。**\n   项目可能尚未被索引。如有需要，可运行 `codebase_index`，然后等待 `codebase_status` 确认索引已完成后再进行搜索。\n\n6. **利用上下文工件获取非代码知识。**\n   项目可以定义一个 `.socraticodecontextartifacts.json` 配置文件，用于暴露数据库模式、API 规范、基础设施配置、架构文档等位于源代码之外的项目知识。这些工件会在 `codebase_index` 和 `codebase_update` 过程中与代码一同自动索引。\n   - 提前运行 `codebase_context` 以查看有哪些可用的工件。\n   - 使用 `codebase_context_search` 来查找特定的模式、端点或配置，而不是先询问数据库结构或 API 协议。\n   - 如果 `codebase_status` 显示工件已过时，请运行 `codebase_context_index` 来刷新它们。\n\n### 各工具的适用场景\n\n| 目标 | 工具 |\n|------|------|\n| 了解代码库的功能或某个功能的位置 | `codebase_search`（宽泛查询） |\n| 查找特定的函数、常量或类型 | `codebase_search`（精确名称）或若已知确切字符串则使用 grep |\n| 查找确切的错误信息、日志字符串或正则表达式模式 | grep \u002F ripgrep |\n| 查看文件导入了什么或哪些内容依赖于它 | `codebase_graph_query` |\n| 在修改或删除文件前检查影响范围 | `codebase_graph_query`（查看依赖关系） |\n| 发现架构问题 | `codebase_graph_circular`、`codebase_graph_stats` |\n| 可视化模块结构 | `codebase_graph_visualize` |\n| 验证索引是否最新 | `codebase_status` |\n| 发现可用的项目知识（模式、规范、配置） | `codebase_context` |\n| 查找数据库表、API 端点或基础设施配置 | `codebase_context_search` |\n```\n\n> **为何优先使用语义搜索？** 一次 `codebase_search` 调用可在毫秒级时间内返回来自整个代码库的排序且去重后的代码片段。这种方式以极低的 token 成本为你提供全局概览——远比盲目打开文件要经济得多。一旦确定了相关文件，有针对性地阅读不仅更快，而且更准确。当然，如果你已经有了确切的字符串或模式，grep 仍然是更合适的选择——应根据具体查询选择合适的工具。\n\n> **索引过程中保持连接畅通。** 索引是在后台运行的——MCP 服务器即使在未主动响应工具调用时也会继续工作。然而，某些 MCP 主机可能会在一段时间无活动后断开空闲连接，从而中断后台进程。建议你的 AI 在启动 `codebase_index` 后，每隔约 60 秒调用一次 `codebase_status`，直到索引完成。这样既能保持主机连接活跃，又能实时掌握进度。\n## 配置\n\n### 安装\n\n#### Claude Code 插件（推荐给 Claude Code 用户）\n\nSocratiCode 插件集成了 MCP 服务器和工作流技能，可指导 Claude 如何高效使用工具。只需一次安装，即可获得所有功能：\n\n在终端中执行以下命令：\n\n```bash\nclaude plugin marketplace add giancarloerra\u002Fsocraticode\nclaude plugin install socraticode@socraticode\n```\n\n或在 Claude Code 内部执行：\n\n```\n\u002Fplugin marketplace add giancarloerra\u002Fsocraticode\n\u002Fplugin install socraticode@socraticode\n```\n\n该插件包含：\n- **MCP 服务器** — 包含全部 21 种 SocratiCode 工具（搜索、图表、上下文工件等）\n- **探索技能** — 教导 Claude “先搜索再阅读”的工作流程\n- **管理技能** — 指导设置、索引构建、监控及故障排除\n- **Explorer 代理** — 可委派的子代理，用于深度代码库分析\n\n> 如果您之前已将 SocratiCode 作为独立的 MCP 安装（`claude mcp add socraticode`），请在安装插件后将其移除，以避免重复：`claude mcp remove socraticode`\n\n**自动更新：** 第三方插件默认不会自动更新。如需启用自动更新，请进入 `\u002Fplugin` → 市场 → 选择 `socraticode` → 启用自动更新。若需手动更新：\n\n在终端中执行以下命令：\n\n```bash\nclaude plugin marketplace update socraticode\nclaude plugin update socraticode@socraticode\n```\n\n或在 Claude Code 内部执行：\n\n```\n\u002Fplugin marketplace update socraticode\n\u002Fplugin update socraticode@socraticode\n```\n\n**配置环境变量：** 对于大多数用户而言，SocratiCode 无需任何配置即可正常工作（本地 Ollama + 托管 Qdrant）。如果您需要云端嵌入、远程 Qdrant 或其他自定义配置：\n\n1. **Claude Code 设置**（推荐）— 将以下内容添加到 `~\u002F.claude\u002Fsettings.json` 文件中：\n\n   ```json\n   {\n     \"env\": {\n       \"EMBEDDING_PROVIDER\": \"openai\",\n       \"OPENAI_API_KEY\": \"sk-...\"\n     }\n   }\n   ```\n\n   此方法适用于所有环境——CLI、VS Code 和 JetBrains。\n\n2. **Shell 配置文件** — 在 `~\u002F.zshrc` 或 `~\u002F.bashrc` 中设置变量：\n\n   ```bash\n   export EMBEDDING_PROVIDER=openai\n   export OPENAI_API_KEY=sk-...\n   ```\n\n   当 Claude Code 从终端启动时有效。请注意：通过 IDE 启动的会话（例如从 Finder\u002FDock 打开 VS Code）可能无法继承 Shell 配置文件中的变量——建议使用方法 1。\n\n更改变量后，请重启 Claude Code。有关所有选项，请参阅[环境变量](#environment-variables)部分。\n\n#### npx（推荐给所有其他 MCP 主机——无需安装）\n\n需要 Node.js 18+ 和正在运行的 Docker。已在上方的[快速入门](#quick-start)中介绍过，只需将以下内容添加到您的 `mcpServers`（Claude Desktop、Windsurf、Cline、Roo Code）或 `servers`（VS Code 项目本地 `.vscode\u002Fmcp.json`）配置中：\n\n```json\n    \"socraticode\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"socraticode\"]\n    }\n```\n\n#### Zed\n\n在 Zed 的设置中（`Zed > Settings > Settings` 或 `cmd+,`），将 SocratiCode 添加为自定义 MCP 服务器。在 `context_servers` 下添加：\n\n```json\n{\n  \"context_servers\": {\n    \"socraticode\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"socraticode\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n如需传递环境变量（例如用于云端嵌入或分支感知索引），请将其添加到 `env` 对象中：\n\n```json\n{\n  \"context_servers\": {\n    \"socraticode\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"socraticode\"],\n      \"env\": {\n        \"EMBEDDING_PROVIDER\": \"openai\",\n        \"OPENAI_API_KEY\": \"sk-...\"\n      }\n    }\n  }\n}\n```\n\nZed 会自动读取项目根目录下的 `AGENTS.md` 文件以获取代理指令。请将[代理指令](#agent-instructions)部分复制到您项目的 `AGENTS.md` 文件中，以确保代理能够有效使用 SocratiCode 工具。您还可以将其作为默认规则添加到 Zed 的规则库中（`agent: open rules library`）。\n\n#### 从源码安装（面向贡献者）\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode.git\ncd socraticode\nnpm install\nnpm run build\n```\n\n然后在下方的配置示例中，使用 `node \u002Fabsolute\u002Fpath\u002Fto\u002Fsocraticode\u002Fdist\u002Findex.js` 替代 `npx -y socraticode`。\n\n### MCP 主机配置变体\n\n> 以下所有 `env` 选项同样适用于 `npx` 安装。只需将上述 `env` 块添加到 npx 配置中即可。\n\n请将以下内容添加到您的 MCP 设置中——`mcpServers`（Claude Desktop、Windsurf、Cline、Roo Code）或 `servers`（VS Code 项目本地 `.vscode\u002Fmcp.json`）：\n\n#### 默认配置（零配置，从源码安装）\n\n> 使用 `npx`？您的配置已在[快速入门](#quick-start)中说明。如有需要，可按需添加下方示例中的任何 `env` 块。\n\n```json\n{\n  \"mcpServers\": {\n    \"socraticode\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fsocraticode\u002Fdist\u002Findex.js\"]\n    }\n  }\n}\n```\n\n> **提示**：默认的 `OLLAMA_MODE=auto` 会在启动时检测本地 Ollama（端口 11434），如果可用则优先使用；否则回退到托管的 Docker 容器。为使您的配置更具可读性，可添加带有明确值的 `env` 块。有关所有选项，请参阅[环境变量](#environment-variables)部分。\n\n#### 外部 Ollama（本地安装）\n\n如果您已本地安装了 [Ollama](https:\u002F\u002Follama.com)，请将 `OLLAMA_MODE` 设置为 `external`，并指向您的实例：\n\n```json\n{\n  \"mcpServers\": {\n    \"socraticode\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fsocraticode\u002Fdist\u002Findex.js\"],\n      \"env\": {\n        \"OLLAMA_MODE\": \"external\",\n        \"OLLAMA_URL\": \"http:\u002F\u002Flocalhost:11434\"\n      }\n    }\n  }\n}\n```\n\n嵌入模型将在首次使用时自动拉取。如需提前下载：`ollama pull nomic-embed-text`\n\n#### 远程 Ollama 服务器\n\n```json\n{\n  \"mcpServers\": {\n    \"socraticode\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fsocraticode\u002Fdist\u002Findex.js\"],\n      \"env\": {\n        \"OLLAMA_MODE\": \"external\",\n        \"OLLAMA_URL\": \"http:\u002F\u002Fgpu-server.local:11434\"\n      }\n    }\n  }\n}\n```\n\n#### OpenAI 嵌入\n\n使用 OpenAI 的云端嵌入 API，而非本地 Ollama。需要一个 [API 密钥](https:\u002F\u002Fplatform.openai.com\u002Fapi-keys)。\n\n```json\n{\n  \"mcpServers\": {\n    \"socraticode\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fsocraticode\u002Fdist\u002Findex.js\"],\n      \"env\": {\n        \"EMBEDDING_PROVIDER\": \"openai\",\n        \"OPENAI_API_KEY\": \"sk-...\"\n      }\n    }\n  }\n}\n```\n\n> 默认设置：`EMBEDDING_MODEL=text-embedding-3-small`，`EMBEDDING_DIMENSIONS=1536`。如需更高品质，可使用 `text-embedding-3-large`，并设置 `EMBEDDING_DIMENSIONS=3072`。\n\n#### Google Generative AI 嵌入\n\n使用 Google 的 Gemini 嵌入 API。需要一个 [API 密钥](https:\u002F\u002Faistudio.google.com\u002Fapikey)。\n\n```json\n{\n  \"mcpServers\": {\n    \"socraticode\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fsocraticode\u002Fdist\u002Findex.js\"],\n      \"env\": {\n        \"EMBEDDING_PROVIDER\": \"google\",\n        \"GOOGLE_API_KEY\": \"AIza...\"\n      }\n    }\n  }\n}\n```\n\n> 默认设置：`EMBEDDING_MODEL=gemini-embedding-001`，`EMBEDDING_DIMENSIONS=3072`。\n\n### Git 工作树（跨目录共享索引）\n\n如果你使用 [git worktrees](https:\u002F\u002Fgit-scm.com\u002Fdocs\u002Fgit-worktree)，或者在多个目录中共享同一个仓库的工作流，通常每个路径都会拥有自己的 Qdrant 索引。这意味着对于本质上相同的代码库，会存在冗余的嵌入和存储。\n\n通过设置 `SOCRATICODE_PROJECT_ID`，可以在同一项目的所有目录之间共享单个索引。\n\n#### 支持 git worktree 检测的 MCP 主机（如 Claude Code）\n\n一些 MCP 主机（例如 [Claude Code](https:\u002F\u002Fclaude.ai\u002Fclaude-code)）会通过解析 git worktree 链接来确定项目根目录。由于 worktree 会指向主仓库的 `.git` 目录，主机可以自动将所有 worktree 映射到相同的项目配置。因此，你只需为主检出配置一次 MCP 服务器——所有 worktree 都会自动继承该配置。\n\n以 Claude Code 为例，在主检出目录下以本地作用域添加服务器：\n\n```bash\ncd \u002Fpath\u002Fto\u002Fmain-checkout\nclaude mcp add -e SOCRATICODE_PROJECT_ID=my-project --scope local socraticode -- npx -y socraticode\n```\n\n从此仓库创建的所有 worktree 都会自动连接到 socraticode，并使用共享的项目 ID。无需为每个 worktree 单独进行设置。\n\n> **注意：** 这仅适用于 git worktree。对同一仓库执行的独立 `git clone` 操作会有各自的 `.git` 目录，不会共享配置。\n\n#### 其他 MCP 主机（基于每个项目 `.mcp.json`）\n\n对于无法解析 git worktree 路径的 MCP 主机，需要在每个 worktree 的根目录以及主检出目录下添加 `.mcp.json` 文件：\n\n```json\n{\n  \"mcpServers\": {\n    \"socraticode\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"socraticode\"],\n      \"env\": {\n        \"SOCRATICODE_PROJECT_ID\": \"my-project\"\n      }\n    }\n  }\n}\n```\n\n如果你不希望跟踪 `.mcp.json` 文件，可以将其加入 `.gitignore` 中。\n\n#### 工作原理\n\n通过此配置，在 `\u002Frepo\u002Fmain`、`\u002Frepo\u002Fworktree-feat-a` 和 `\u002Frepo\u002Fworktree-fix-b` 中运行的代理都将共享相同的 `codebase_my-project`、`codegraph_my-project` 和 `context_my-project` Qdrant 集合。\n\n**实际工作方式：**\n\n- 语义索引会反映最近触发文件变更的 worktree；但由于分支之间通常只相差少量文件，因此该索引对于所有 worktree 的准确性可达 99% 以上。\n- 你的 AI 代理会从其所在 worktree 中读取实际的文件内容；共享索引仅用于发现和导航。\n- 当更改合并回主分支时，文件监视器会重新索引这些文件，从而使索引保持一致。\n\n### 跨项目搜索（关联项目）\n\n如果你同时处理多个相关仓库或包，可以通过一次查询同时搜索它们。\n\n#### 配置\n\n在项目根目录下创建一个 `.socraticode.json` 文件：\n\n```json\n{\n  \"linkedProjects\": [\n    \"..\u002Fshared-lib\",\n    \"\u002Fabsolute\u002Fpath\u002Fto\u002Fother-project\"\n  ]\n}\n```\n\n或者设置 `SOCRATICODE_LINKED_PROJECTS` 环境变量（用逗号分隔的路径）：\n\n```bash\nSOCRATICODE_LINKED_PROJECTS=\"..\u002Fshared-lib,\u002Fabsolute\u002Fpath\u002Fto\u002Fother-project\"\n```\n\n两种方式都会将源合并并去重。相对路径会从项目根目录解析，而不存在的路径则会被静默跳过。\n\n#### 使用方法\n\n在调用 `codebase_search` 时传递 `includeLinked: true` 参数：\n\n> 搜索“authentication middleware”，并启用 includeLinked: true\n\n结果会带有 `[project-name]` 标签，标明每条结果来自哪个项目。当前项目始终具有最高的去重优先级——如果多个关联项目中存在相同的文件，则当前项目的版本将被优先选择。\n\n> **注意：** 每个关联项目必须先独立完成索引构建（`codebase_index`），才能进行搜索。\n\n### 分支感知索引\n\n默认情况下，项目的各个分支共享同一个索引。当你切换分支时，文件监视器会重新索引已更改的文件，索引便会反映当前分支的状态。\n\n对于需要 **为每个分支维护独立且持久的索引** 的工作流——例如 CI\u002FCD 流水线或跨分支比较代码——可以启用分支感知模式：\n\n```bash\nSOCRATICODE_BRANCH_AWARE=true\n```\n\n启用后，集合名称会包含分支名称（例如 `codebase_abc123__main`、`codebase_abc123__feat_my-feature`）。每个分支将维护自己独立的索引、代码图和上下文数据。\n\n**适用场景：**\n- CI\u002FCD 流水线中为每个分支\u002FPR 单独索引\n- 比较不同分支之间的搜索结果\n- 保持 `main` 分支的原始索引不受特性分支更改的影响\n\n**不适用场景：**\n- 经常切换分支的本地开发（默认共享索引更为高效）\n- 使用 `SOCRATICODE_PROJECT_ID` 追踪的项目（显式 ID 会绕过分支检测）\n\n> **工作原理：** `projectIdFromPath()` 会通过 `git rev-parse --abbrev-ref HEAD` 检测当前的 Git 分支，并将规范化后的分支后缀（例如 `feat\u002Fmy-feature` → `feat_my-feature`）附加到基于哈希的项目 ID 上。对于分离的 HEAD 状态，则会回退到无分支的 ID。\n\n### 可用工具\n\n连接后，您的 AI 助手将可以使用 21 种工具：\n\n#### 索引\n\n| 工具 | 描述 |\n|------|-------------|\n| `codebase_index` | 在后台开始索引代码库（可通过 `codebase_status` 轮询进度） |\n| `codebase_stop` | 优雅地停止正在进行的索引操作（当前批次会完成并生成检查点；可使用 `codebase_index` 恢复） |\n| `codebase_update` | 增量更新——仅重新索引已更改的文件 |\n| `codebase_remove` | 删除项目的索引（安全停止文件监视器，取消正在进行的索引\u002F更新，并等待图构建完成） |\n| `codebase_watch` | 开始\u002F停止文件监视——启动时会补全遗漏的更改，然后继续监视未来的更改 |\n\n#### 搜索\n\n| 工具 | 描述 |\n|------|-------------|\n| `codebase_search` | 混合语义 + 关键词搜索（稠密向量 + BM25，RRF 融合），支持可选的文件路径、语言过滤以及跨项目搜索 (`includeLinked`) |\n| `codebase_status` | 检查索引状态和分块数量 |\n\n#### 代码图\n\n| 工具 | 描述 |\n|------|-------------|\n| `codebase_graph_build` | 构建多语言依赖图（在后台运行——可通过 `codebase_graph_status` 轮询） |\n| `codebase_graph_query` | 查询特定文件的导入和依赖项 |\n| `codebase_graph_stats` | 获取图统计信息（最连接的文件、孤立文件、语言分布等） |\n| `codebase_graph_circular` | 检测循环依赖 |\n| `codebase_graph_visualize` | 生成依赖图的 Mermaid 图表 |\n| `codebase_graph_status` | 检查图构建进度或持久化图元数据 |\n| `codebase_graph_remove` | 删除项目的持久化代码图（会先等待正在进行的图构建完成） |\n\n#### 管理\n\n| 工具 | 描述 |\n|------|-------------|\n| `codebase_health` | 检查 Docker、Qdrant 和嵌入服务提供商的状态 |\n| `codebase_list_projects` | 列出所有已索引的项目及其路径和元数据 |\n| `codebase_about` | 显示 SocratiCode 的相关信息 |\n\n#### 上下文工件\n\n| 工具 | 描述 |\n|------|-------------|\n| `codebase_context` | 列出 `.socraticodecontextartifacts.json` 中定义的所有上下文工件，包括名称、描述和索引状态 |\n| `codebase_context_search` | 在上下文工件中进行语义搜索（首次使用时自动索引，自动检测过时情况） |\n| `codebase_context_index` | 对 `.socraticodecontextartifacts.json` 中的所有工件进行索引或重新索引 |\n| `codebase_context_remove` | 删除项目的所有已索引的上下文工件（索引进行中时无法执行） |\n\n## 语言支持\n\nSocratiCode 在三个层次上支持多种语言：\n\n###  volle Unterstützung (Indexierung + Codegraph + AST-Chunking)\n\nJavaScript, TypeScript, TSX, Python, Java, Kotlin, Scala, C, C++, C#, Go, Rust, Ruby, PHP, Swift, Bash\u002FShell, HTML, CSS\u002FSCSS, Svelte, Vue\n\nSvelte und Vue: Importe werden aus `\u003Cscript>`-Blöcken extrahiert (wieder als TypeScript analysiert) und CSS `@import`\u002F`@require` aus `\u003Cstyle>`-Blöcken (jede Kombination von `lang`, `scoped`, `module`, `global` Attributen). Pfalalias aus `tsconfig.json`\u002F`jsconfig.json` `compilerOptions.paths` werden aufgelöst (einschließlich `extends`-Ketten). SCSS-Teillösung (`_`-Präfixkonvention) wird unterstützt.\n\n### Codegraph via Regex + Indexierung\n\nDart (Import\u002FExport\u002FPart), Lua (Require\u002FDofile\u002FLoadfile), SASS, LESS (CSS `@import` Extraktion)\n\n### Nur Indexierung (Hybridsuche, zeilenbasiertes Chunking)\n\nJSON, YAML, TOML, XML, INI\u002FCFG, Markdown\u002FMDX, RST, SQL, R, Dockerfile, TXT, sowie jede Datei, die einer unterstützten Erweiterung oder einem speziellen Dateinamen entspricht (Dockerfile, Makefile, Gemfile, Rakefile usw.).\n\n**54 Dateierweiterungen** + 8 Sonderdateinamen sind sofort verfügbar.\n\n## Ignorierungsregeln\n\nDer Indexer kombiniert drei Ebenen von Ignorierungsregeln:\n\n1. **Integrierte Standardregeln** — `node_modules`, `.git`, `dist`, `build`, Lock-Dateien, IDE-Ordner usw.\n2. **`.gitignore`** — Alle `.gitignore`-Dateien im Projekt (Stammverzeichnis und verschachtelte Unterordner). Setzen Sie `RESPECT_GITIGNORE=false`, um die Verarbeitung von `.gitignore` vollständig zu überspringen.\n3. **`.socraticodeignore`** — Optionale Datei für indexer-spezifische Ausschlüsse. Gleiche Syntax wie `.gitignore`.\n\n## Kontext-Artefakte\n\nGeben Sie der KI Einblick in Projektkenntnisse jenseits des Quellcodes — Datenbankschemata, API-Spezifikationen, Infrastrukturkonfigurationen, Architektur-Dokumentationen und mehr.\n\n### Einrichtung\n\nErstellen Sie eine `.socraticodecontextartifacts.json`-Datei im Stammverzeichnis Ihres Projekts (siehe [`.socraticodecontextartifacts.json.example`](.socraticodecontextartifacts.json.example) für eine Startervorlage):\n\n```json\n{\n  \"artifacts\": [\n    {\n      \"name\": \"database-schema\",\n      \"path\": \".\u002Fdocs\u002Fschema.sql\",\n      \"description\": \"Komplettes PostgreSQL-Schema — alle Tabellen, Indizes, Einschränkungen, Fremdschlüssel. Dient dazu, zu verstehen, welche Daten die Anwendung speichert und wie die Tabellen miteinander verbunden sind.\"\n    },\n    {\n      \"name\": \"api-spec\",\n      \"path\": \".\u002Fdocs\u002Fopenapi.yaml\",\n      \"description\": \"OpenAPI 3.0 Spezifikation für die REST-API. Alle Endpunkte, Anforderungs-\u002FAntwortschemas, Authentifizierungsanforderungen.\"\n    },\n    {\n      \"name\": \"k8s-manifests\",\n      \"path\": \".\u002Fdeploy\u002Fk8s\u002F\",\n      \"description\": \"Kubernetes-Bereitstellungsmanifeste. Zeigt, wie Dienste bereitgestellt, skaliert und vernetzt werden.\"\n    }\n  ]\n}\n```\n\nJedes Artefakt hat:\n- **`name`** — Eindeutiger Bezeichner (wird zum Filtern von Suchanfragen verwendet)\n- **`path`** — Pfad zu einer Datei oder einem Verzeichnis (relativ zum Projektstamm oder absolut). Verzeichnisse werden rekursiv gelesen.\n- **`description`** — Erklärt der KI, was dieses Artefakt ist und wie es verwendet werden kann\n\n### Funktionsweise\n\nArtefakte werden in Qdrant mit demselben hybriden Ansatz aus dichter und BM25-Suche wie Code indexiert. Bei der ersten Suche werden Artefakte automatisch indiziert. Bei nachfolgenden Suchen wird durch Inhalts-Hashing automatisch erkannt, ob sie veraltet sind — geänderte Dateien werden transparent neu indiziert.\n\n### Nutzung\n\n1. **Entdecken**: `codebase_context` — listet alle definierten Artefakte und deren Indexstatus auf\n2. **Suchen**: `codebase_context_search` — semantische Suche über alle Artefakte hinweg (oder nach Name filtern)\n3. **Neuindizieren**: `codebase_context_index` — erzwingt eine Neuindizierung (normalerweise nicht nötig, da die automatische Indizierung dies übernimmt)\n4. **Aufräumen**: `codebase_context_remove` — entfernt alle indizierten Artefakte\n\n### 为什么这很重要：实际工作流示例\n\n如果没有工件，代理只能看到源代码。而有了工件，它就能掌握全局信息，从一开始就编写符合项目需求的代码。\n\n**数据库模式** — 您提出：“在用户表中添加 `last_login` 时间戳。” 代理会运行 `codebase_context_search` 查询“用户表”，发现该模式使用 `snake_case` 命名的列，并且每张表都有一个带有触发器的 `updated_at` 字段。因此，生成的迁移脚本会遵循现有规范，而不是随意猜测。\n\n```json\n{\n  \"name\": \"database-schema\",\n  \"path\": \".\u002Fdocs\u002Fschema.sql\",\n  \"description\": \"完整的 PostgreSQL 数据库模式——包括所有表、列、数据类型、约束、索引和触发器。在编写迁移脚本之前，请先查看此文件，以确保命名规范和现有模式一致。\"\n}\n```\n\n**API 规范** — 您要求：“添加一个用于获取用户偏好设置的 GET 端点。” 代理会搜索 OpenAPI 规范，发现所有端点都使用 Bearer 认证，返回 `{ data, meta }` 包装结构，并通过 `cursor`\u002F`limit` 进行分页。新端点会自动遵循相同的模式。\n\n```json\n{\n  \"name\": \"api-spec\",\n  \"path\": \".\u002Fdocs\u002Fopenapi.yaml\",\n  \"description\": \"REST API 的 OpenAPI 3.0 规范——包含所有端点、请求\u002F响应模式、认证方式和分页机制。在添加或修改端点之前，请先查阅此文档，以确保符合现有规范。\"\n}\n```\n\n**领域术语表（DDD）** — 您提出：“添加一种取消订单的方式。” 代理会搜索您的领域术语表，发现取消操作被建模为 `OrderVoided` 事件（而非“已取消”），只有处于 `Confirmed` 状态的订单才能被取消，并且需要通知 `Fulfillment` 限界上下文。最终实现会使用正确的领域术语，并与相应的限界上下文无缝集成。\n\n```json\n{\n  \"artifacts\": [\n    {\n      \"name\": \"ubiquitous-language\",\n      \"path\": \".\u002Fdocs\u002Fubiquitous-language.md\",\n      \"description\": \"领域术语表——限界上下文中的术语、定义及其关系。在命名实体、事件或命令之前，请务必查阅此文档，以确保使用正确的领域语言。\"\n    },\n    {\n      \"name\": \"context-map\",\n      \"path\": \".\u002Fdocs\u002Fcontext-mapping.md\",\n      \"description\": \"限界上下文地图——上下文边界、相互关系（共享内核、客户-供应商等）以及集成模式。在实现跨上下文通信之前，请先检查此文档。\"\n    },\n    {\n      \"name\": \"event-storming\",\n      \"path\": \".\u002Fdocs\u002Fevent-storming\u002F\",\n      \"description\": \"事件风暴输出——领域事件、命令、聚合、策略和读模型。在添加新的领域行为之前，请先查看此文档，以了解其如何融入现有的事件流。\"\n    }\n  ]\n}\n```\n\n> **“description” 字段是关键杠杆。** 它不仅告诉 AI 工件是什么，还说明了“何时应该查阅它”。请撰写类似“在执行 X 之前请先查阅此文档”的描述，以便代理能够在恰当的时候调用相应工件。\n\n### 示例工件\n\n| 类别       | 示例                                                         |\n|------------|--------------------------------------------------------------|\n| **数据库** | SQL 模式转储（`pg_dump --schema-only`）、Prisma 模式、Rails `schema.rb`、Django 模型转储、迁移文件 |\n| **API 合同** | OpenAPI\u002FSwagger 规范、GraphQL 模式、Protobuf 定义、AsyncAPI 规范（Kafka、RabbitMQ） |\n| **基础设施** | Terraform\u002FPulumi 配置、Kubernetes 清单、Docker Compose 文件、CI\u002FCD 流水线配置 |\n| **架构**   | 架构决策记录 (ADR)、服务拓扑文档、数据流图、领域术语表         |\n| **运维**   | 监控\u002F告警规则、RBAC\u002F权限矩阵、认证流程文档、功能标记配置       |\n| **外部**   | 第三方 API 文档、合规性要求（SOC2、HIPAA、GDPR）、SLA 定义     |\n\n> **提示**：对于数据库模式，各大主流数据库都可以将其整个模式导出到一个文件中：`pg_dump --schema-only`（PostgreSQL）、`mysqldump --no-data`（MySQL）、`sqlite3 db.sqlite .schema`（SQLite）。ORM 模式的文件（Prisma、Rails、Django）通常已经存在于您的代码库中。\n\n## 环境变量\n\n### 嵌入提供者\n\n| 变量               | 默认值        | 描述                                                         |\n|--------------------|---------------|--------------------------------------------------------------|\n| `EMBEDDING_PROVIDER` | `ollama`      | 嵌入后端：`ollama`（本地，默认）、`openai` 或 `google`       |\n| `EMBEDDING_MODEL`   | *（依提供商而定）* | 模型名称。默认值：`nomic-embed-text`（ollama）、`text-embedding-3-small`（openai）、`gemini-embedding-001`（google） |\n| `EMBEDDING_DIMENSIONS` | *（依提供商而定）* | 向量维度。默认值：`768`（ollama）、`1536`（openai）、`3072`（google） |\n| `EMBEDDING_CONTEXT_LENGTH` | *（自动检测）* | 模型上下文窗口的令牌数。已知模型会自动检测，自定义模型则需手动设置。 |\n\n### Ollama 配置（当 `EMBEDDING_PROVIDER=ollama` 时）\n\n| 变量               | 默认值        | 描述                                                         |\n|--------------------|---------------|--------------------------------------------------------------|\n| `OLLAMA_MODE`      | `auto`        | `auto` = 如果本地 11434 端口可用，则使用原生 Ollama；否则管理一个 Docker 容器（推荐）。`docker` = 始终使用托管的 Docker 容器，运行在 11435 端口上。`external` = 用户自行管理的 Ollama 实例（本地、远程等）。 |\n| `OLLAMA_URL`       | `http:\u002F\u002Flocalhost:11434`（auto\u002Fexternal） \u002F `http:\u002F\u002Flocalhost:11435`（docker） | 完整的 Ollama API 端点                                       |\n| `OLLAMA_PORT`      | `11435`       | Ollama 容器端口（Docker 模式）。如果已明确设置了 `OLLAMA_URL`，则忽略此设置。 |\n| `OLLAMA_HOST`      | `http:\u002F\u002Flocalhost:{OLLAMA_PORT}` | Ollama 基础 URL（替代 `OLLAMA_URL`）                         |\n| `OLLAMA_API_KEY`   | *无*          | 用于经过身份验证的 Ollama 代理的可选 API 密钥                |\n\n### 云提供商 API 密钥\n\n| 变量               | 默认值        | 描述                                                         |\n|--------------------|---------------|--------------------------------------------------------------|\n| `OPENAI_API_KEY`   | *无*          | 当 `EMBEDDING_PROVIDER=openai` 时必需。可在 [platform.openai.com](https:\u002F\u002Fplatform.openai.com\u002Fapi-keys) 获取。 |\n| `GOOGLE_API_KEY`   | *无*          | 当 `EMBEDDING_PROVIDER=google` 时必需。可在 [aistudio.google.com](https:\u002F\u002Faistudio.google.com\u002Fapikey) 获取。 |\n\n### Qdrant 配置\n\n| 变量               | 默认值        | 描述                                                         |\n|--------------------|---------------|--------------------------------------------------------------|\n| `QDRANT_MODE`      | `managed`     | `managed` = 使用 Docker 托管的本地 Qdrant（默认）。`external` = 用户提供的远程或云端 Qdrant（不使用 Docker 管理）。 |\n| `QDRANT_URL`       | *无*          | 远程\u002F云上 Qdrant 实例的完整 URL（如 `https:\u002F\u002Fxyz.aws.cloud.qdrant.io:6333`）。一旦设置，将优先于 `QDRANT_HOST` + `QDRANT_PORT`。端口会根据 URL 自动推断：若 URL 中明确指定了端口（如 `:8443`），则使用该端口；否则，`https:\u002F\u002F` 使用 443 端口，`http:\u002F\u002F` 使用 6333 端口。当 `QDRANT_MODE=external` 时，必须设置此字段或至少指定 `QDRANT_HOST`。 |\n| `QDRANT_PORT`      | `16333`       | Qdrant REST API 端口（托管模式，或未使用 `QDRANT_URL` 的外部实例） |\n| `QDRANT_GRPC_PORT` | `16334`       | Qdrant gRPC 端口（仅托管模式）                               |\n| `QDRANT_HOST`      | `localhost`   | Qdrant 主机名（适用于非 HTTPS 的外部实例，作为 `QDRANT_URL` 的替代方案） |\n| `QDRANT_API_KEY`   | *无*          | Qdrant API 密钥（适用于 Qdrant Cloud 及其他需要身份验证的部署） |\n\n### 索引行为\n\n| 变量 | 默认值 | 描述 |\n|----------|---------|-------------|\n| `RESPECT_GITIGNORE` | `true` | 设置为 `false` 以跳过 `.gitignore` 处理。内置默认规则和 `.socraticodeignore` 仍会生效。 |\n| `INCLUDE_DOT_FILES` | `false` | 设置为 `true` 以在索引中包含点目录（例如 `.agent`、`.config`）。默认情况下，以 `.` 开头的目录和文件会被排除。对于重要代码位于点目录中的项目非常有用。 |\n| `EXTRA_EXTENSIONS` | *(无)* | 需要扫描的额外文件扩展名列表，用逗号分隔（例如 `.tpl,.blade,.hbs`）。适用于索引和代码图。带有额外扩展名的文件会被当作纯文本进行索引，并在代码图中显示为叶节点。也可以通过 `extraExtensions` 工具参数在每次操作时单独指定。 |\n| `MAX_FILE_SIZE_MB` | `5` | 最大文件大小，单位为 MB。超过此大小的文件在索引过程中会被跳过。对于包含大型生成文件或数据文件且希望被索引的仓库，可以适当提高该值。 |\n| `SEARCH_DEFAULT_LIMIT` | `10` | `codebase_search` 返回的结果数量默认值（1-50）。每个结果都是一个按相关性排序的代码片段，包含文件路径、行范围和内容。数值越高，覆盖范围越广，但输出结果也会越多。仍可通过 `limit` 工具参数在每次查询时覆盖该设置。 |\n| `SEARCH_MIN_SCORE` | `0.10` | 最低 RRF（倒数排名融合）得分阈值（0-1）。低于此分数的结果将被过滤掉。有助于去除搜索结果中的低相关性噪声。设置为 `0` 可禁用过滤（返回所有不超过 `limit` 的结果）。也可通过 `minScore` 工具参数在每次查询时覆盖该设置。与 `limit` 配合使用：先按分数过滤结果，再限制到 `limit` 数量。 |\n| `SOCRATICODE_PROJECT_ID` | *(无)* | 覆盖自动生成的项目 ID。设置后，所有路径都会解析到相同的 Qdrant 集合，允许多个目录（例如同一仓库的不同 Git 工作树）共享同一个索引。必须符合 `[a-zA-Z0-9_-]+` 格式。 |\n| `SOCRATICODE_BRANCH_AWARE` | `false` | 当设置为 `true` 时，会在项目 ID 后附加当前 Git 分支名称，从而为每个分支创建独立的 Qdrant 集合。如果已设置 `SOCRATICODE_PROJECT_ID`，则此选项将被忽略。 |\n| `SOCRATICODE_LINKED_PROJECTS` | *(无)* | 需要纳入跨项目搜索的其他项目路径列表，用逗号分隔。与 `.socraticode.json` 中的路径合并。不存在的路径将被静默跳过。 |\n| `SOCRATICODE_LOG_LEVEL` | `info` | 日志详细程度：`debug`、`info`、`warn`、`error` |\n| `SOCRATICODE_LOG_FILE` | *(无)* | 日志文件的绝对路径。设置后，所有日志条目都会追加到该文件中（每次服务器启动时会写入会话分隔符）。当 MCP 主机无法显示日志通知时，此功能对调试非常有用。 |\n\n> **重要提示**：如果您在索引完成后更改了 `EMBEDDING_PROVIDER`、`EMBEDDING_MODEL` 或 `EMBEDDING_DIMENSIONS`，则必须重新索引您的项目（先执行 `codebase_remove`，再执行 `codebase_index`），因为现有向量的维度会发生变化。\n\n## Docker 资源\n\nSocratiCode 管理 Docker 容器和持久化卷：\n\n| 资源 | 名称 | 用途 | 使用场景 |\n|----------|------|---------|------|\n| 容器 | `socraticode-qdrant` | Qdrant 向量数据库（固定版本 `v1.17.0`） | 仅限 `managed` 模式 |\n| 容器 | `socraticode-ollama` | Ollama 嵌入服务端 | 仅限 `docker` 模式 |\n| 卷 | `socraticode_qdrant_data` | 持久化向量存储 | 仅限 `managed` 模式 |\n| 卷 | `socraticode_ollama_data` | 持久化模型存储 | 仅限 `docker` 模式 |\n\n在 `QDRANT_MODE=external` 模式下，不会创建或启动 Qdrant 容器和卷——SocratiCode 将直接连接到配置的远程端点。服务器端 BM25 推理（用于混合搜索）需要 **Qdrant v1.15.2 或更高版本**。托管容器运行的是 `v1.17.0`。如果您使用自己的 Qdrant 实例，请确保其满足此最低要求。\n\n所有容器均使用 `--restart unless-stopped` 选项，以实现自动恢复。\n\n> **为什么使用非标准端口？** SocratiCode 故意为其托管容器使用非默认端口——`16333`\u002F`16334` 替代 Qdrant 的默认端口（`6333`\u002F`6334`），以及 `11435` 替代 Ollama 的默认端口（`11434`）。这样做是为了避免与您可能已经在本地运行的任何 Qdrant 或 Ollama 实例发生冲突。如有需要，所有端口均可通过环境变量进行覆盖。\n\n## 测试\n\nSocratiCode 拥有一套全面的测试套件，涵盖单元测试、集成测试和端到端测试，共计 **634 个测试用例**。\n\n### 前置条件\n\n- **单元测试**：无需外部依赖。\n- **集成测试和端到端测试**：需要运行包含 Qdrant 和 Ollama 容器的 Docker。这些容器由测试基础设施自动管理。\n\n### 运行测试\n\n```bash\n# 运行所有测试\nnpm test\n\n# 仅运行单元测试（无需 Docker）\nnpm run test:unit\n\n# 运行集成测试（需要 Docker）\nnpm run test:integration\n\n# 运行端到端测试（需要 Docker）\nnpm run test:e2e\n\n# 监视模式（文件更改时自动重跑）\nnpm run test:watch\n\n# 生成覆盖率报告\nnpm run test:coverage\n```\n\n### 测试架构\n\n| 层级 | 测试数量 | 是否需要 Docker | 描述 |\n|-------|-------|---------|-------------|\n| **单元测试** (`tests\u002Funit\u002F`) | 477 | 否 | 配置、常量、忽略规则、进程间锁、日志记录、图分析、导入提取、路径解析、嵌入配置、索引器工具、嵌入计算、启动生命周期、监视器的进程间感知 |\n| **集成测试** (`tests\u002Fintegration\u002F`) | 137 | 是 | Docker\u002FOllama 环境搭建、Qdrant 的 CRUD 操作、实际嵌入计算、索引器、监视器、代码图、所有 MCP 工具 |\n| **端到端测试** (`tests\u002Fe2e\u002F`) | 20 | 是 | 完整生命周期：健康检查 → 索引 → 搜索 → 图分析 → 监视 → 删除 |\n\n当 Docker 不可用时，需要 Docker 的集成测试和端到端测试将自动跳过。\n\n## 为什么不用单纯的 Grep？\n\n针对真实仓库的现代评估表明，一旦涉及自然语言查询、大型代码库或编码代理，混合的词法+语义代码搜索始终优于单纯的 Grep：报告显示，在大规模场景下，BM25F 排序可提升约 20% 的搜索质量；AST 感知检索在 RepoEval 和 SWE-bench 上能提高召回率并改善 bug 修复表现；而采用 Grep 作为默认方式的混合方法（如 SocratiCode 所采用）在 70% 的代理式代码搜索任务中表现优于纯 Grep，同时将搜索操作次数减少了一半以上。\n\n### 现实场景基准测试：VS Code（245万行代码）与 Claude Opus 4.6\n\n我们以 VS Code 代码库（包含 5,300 多个文件，总计约 245 万行 TypeScript\u002FJavaScript 代码，共 55,437 个索引片段）为基准，进行了一次直接对比，旨在衡量 Claude Opus 4.6 AI 代理在回答架构相关问题时的实际资源消耗。\n\n**方法论：** 对于每个问题，**grep 方法** 模拟当前 AI 代理所采用的多步骤工作流程：使用 `grep -rl` 查找匹配文件，确定核心文件后按每批 200 行的方式逐段读取，并重复此过程直至获取足够的上下文。而 **SocratiCode 方法** 则只需一次语义搜索调用，即可从整个代码库中返回最相关的 10 个代码片段。\n\n| 问题 | Grep（字节） | SocratiCode（字节） | 减少比例 | 加速倍数 |\n|:---------|:-------------|:--------------------|:----------|:--------|\n| VS Code 如何实现工作区信任限制？ | 56,383 | 21,149 | **62.5%** | **49.7x** |\n| 差异编辑器如何计算并显示文本差异？ | 37,650 | 15,961 | **57.6%** | **40.2x** |\n| VS Code 如何处理扩展激活与生命周期？ | 36,231 | 16,181 | **55.3%** | **34.4x** |\n| 集成终端如何启动和管理 Shell？ | 50,159 | 22,518 | **55.1%** | **31.1x** |\n| VS Code 如何实现命令面板与快速选择功能的？ | 70,087 | 20,676 | **70.5%** | **31.7x** |\n| **总计** | **250,510** | **96,485** | **61.5%** | **37.2x** |\n\n**关键发现：**\n\n- **工具调用次数减少 84%** — Grep 在 5 个问题中总共需要 31 步操作（平均每个问题 6–7 步）。而 SocratiCode 仅需 5 步（每个问题 1 步）。\n- **数据消耗减少 61.5%** — AI 代理处理的上下文减少了约 150KB，这将直接降低任何 LLM 的 token 成本。\n- **速度提升 37 倍** — Grep 需要扫描 245 万行代码，每次查询可能耗时 2–3.5 秒；而语义搜索则可在 60–90 毫秒内完成。\n\n> **注：** 该基准测试对 grep 方法而言是“保守”的。它假设代理已经知道要读取哪些文件。实际上，真正的 AI 代理还需要进行额外的探索性 grep 调用，可能会遇到无效路径、读取无关文件，并且往往需要多次迭代才能缩小范围。因此，实际节省的数据量可能会更大。\n\n### 混合搜索的优势所在\n\n**自然语言与概念性查询** — 诸如“我们在哪里处理数据库连接池？”或“这个库是如何实现指数退避算法的？”之类的查询，描述的是行为而非函数名称。基于仓库级别的基准测试（RepoEval、SWE-bench）表明，与基于固定行数的代码块相比，支持 AST 的语义检索可将召回率提高多达 4.3 个百分点，下游代码生成的准确率也提升约 2.7 个百分点。而在真实开源项目的代理评估中，混合搜索在解决复杂、概念性强的问题时，胜率比纯 grep 高出 70%，同时搜索操作次数减少 56%，每次复杂查询所需的 token 数量也减少了约 6 万个。\n\n**大型代码库与 monorepo** — 当代码规模达到数百万 LOC 时，全文扫描的成本会显著上升。生产级搜索引擎报告称，使用 BM25F 排序相比以往方法，相关性提升了约 20%，并且将其作为语义重排序的第一阶段检索器。而基于倒排索引和向量索引的混合搜索则完全避免了全量扫描，从而在大规模场景下既更快又更精准。行业从业者明确指出，grep 和 find “难以扩展到数百万文件”，而经过优化的嵌入式索引在该规模下反而更为高效。\n\n**跨文件与跨语言推理** — 要找到所有最终会调用某个内部辅助函数的代码路径，或者将自然语言规范映射到 Go 和 SQL 中的实现，都需要超越字符串匹配的理解能力。评估结果表明，在命名不直观且需要语义理解的情况下，结合 tree-sitter 解析与依赖关系上下文的混合管道表现优于 grep。基于 AST 的分块技术配合学习型检索器，能够提升跨语言基准测试中的检索效果；而多向量语义模型则在各种复杂的代码搜索任务中（AppsRetrieval、CodeSearchNet、CosQA），当查询以自然语言提出且目标跨越多种语言时，相较于单独使用 BM25 显著提升了性能。\n\n**代码与上下文文档混合** — 例如“速率限制是在哪里配置的？”这样的问题，可能匹配 Nginx 配置、Terraform 文件或 YAML，而不仅仅是应用代码。在针对混合技术语料库（结构化字段 + 自由文本）的公开评估中，混合搜索始终优于纯词法或纯向量方法。\n\n### grep 仍然占优的情况\n\n同一研究也明确了何时 grep（或 ripgrep）完全合理，甚至可能是最优选择：\n\n- **你清楚确切的标识符、错误信息或正则表达式模式。** 无需填补语义鸿沟。\n- **代码库规模较小** — 全文扫描既便宜又快速。\n- **内容有限且为结构化的代码，具有鲜明的命名风格，而非散文或文档。**\n\n对于简单或直接命名的查询，grep 完全可以媲美甚至超越语义方法。这就是为什么最佳架构并不是用其他方法取代 grep，而是对其进行扩展。SocratiCode 的混合方案会在每次查询时同时运行 BM25 关键字搜索和密集型语义搜索，并通过 RRF 融合结果，从而在一次调用中兼顾精确匹配的精度与语义理解的召回率。\n\n## 常见问题解答\n\n### 索引过程中出现错误并失败——能否从中断处继续，而无需重新开始？\n\n可以。索引会自动从上次中断的地方恢复。索引器会在每批文件处理完成后记录文件哈希值。当你再次让 AI 开始索引（例如：“索引该项目”）时，它会检测到已有的数据，跳过所有已成功嵌入的文件，只重新处理那些在故障发生前尚未完成检查点的文件。已经索引过的代码片段绝不会被删除或重新嵌入。只需再次请求 AI 索引，它就会从中断处继续。\n\n### 我的 MCP 主机在索引大型代码库时断开了连接，该怎么办？\n\n索引过程会在 MCP 服务器后台运行。然而，某些 MCP 主机（如 VS Code、Claude Desktop 等）会在一段时间无活动后断开空闲连接，从而终止后台进程。为了保持连接畅通，建议在开始索引后每隔约 60 秒询问 AI 索引状态（例如：“检查索引状态”），直到索引完成。如果连接确实中断且索引被迫停止，只需再次请求 AI 索引——它会自动从中断处恢复（参见上文）。\n\n### 索引总是失败或无法正确恢复，我应该怎么办？\n\n如果索引反复失败、恢复时抛出错误，或陷入循环，最简单的解决办法就是从头开始：让 AI 执行“移除该项目的索引”命令，然后重新发起索引请求。这样会清除该项目的所有存储代码片段和元数据，并从头开始重新索引。这不会影响其他已索引的项目。\n\n### 我的代码库非常大——我可以暂停索引并在稍后恢复吗？\n\n可以。您可以在任何时候停止索引，并在之后恢复，而不会丢失进度：\n\n1. **让您的 AI 助手停止索引**——只需说类似“停止索引”的话，它就会在下一个批次边界处取消当前操作。到目前为止已完成的所有批次都会被保存为检查点并保留。\n2. **或者直接关闭项目\u002F编辑器**——SocratiCode 会检测到断开连接并优雅地关闭，同时保留所有已保存的检查点进度。\n3. **随时回来继续**——在编辑器中重新打开同一项目，然后让 AI 恢复索引（例如：“恢复索引”）。SocratiCode 会自动检测到未完成的索引，跳过所有已经嵌入的文件，并从上次中断的地方继续。\n\n这使得即使在较慢的硬件上，对大型代码库进行索引也成为可能——您可以分多次、跨越数小时或数天来完成索引工作，而且不会重复任何工作或丢失任何内容。\n\n### 我重新打开了项目，但新文件或更改后的文件没有出现在搜索结果中。\n\n对于之前已经索引过的项目，文件监视器会在首次使用工具时自动启动。启动后，它会先同步所有在 SocratiCode 停止运行期间修改过的文件，然后再开始监控未来的更改。\n\n如果您希望在搜索之前立即同步这些更改，可以让 AI 执行“开始监视该项目”或“更新索引”命令——这两个命令都会同步执行增量更新，然后开始监视。\n\n如果当前正在进行完整索引或增量更新、项目尚未被索引，或者已经有其他 MCP 进程正在监视同一项目，则文件监视器不会自动启动。\n\n### 多个 AI 代理能否同时处理同一个代码库？\n\n可以——这是系统原生支持的工作流。当多个代理（各自运行自己的 MCP 服务器实例）指向同一个项目目录时，它们会自动共享同一个 Qdrant 索引。第一个触发索引的代理会获取跨进程锁并构建索引；任何试图同时进行索引的其他代理都会接收到当前的进度信息，而不是启动重复的操作。所有代理都可以并发搜索，无需任何协调——Qdrant 原生支持并行读取。\n\n文件监视器也会自动协调：每个项目只有一个进程负责监视。其他实例会检测到这一点并跳过监视器的启动。当监视进程检测到文件变更时，它会更新共享索引——这样，所有代理的下一次搜索都会看到最新的结果。\n\n如果拥有监视器或索引锁的代理崩溃了，其锁将在 2 分钟后失效，下一个与之交互的代理会自动重新获取该锁。整个过程无需人工干预。\n\n这使得 SocratiCode 非常适合多代理工作流：一个代理编写测试，另一个代理修复代码；规划代理和实现代理并行工作；或者任何需要共享深度代码库知识而不重复工作的 AI 助手组合。\n\n### 我可以同时索引多个项目吗？\n\n可以。SocratiCode 会为每个项目路径维护一个独立的隔离集合。您可以询问 AI“列出所有已索引的项目”，以查看当前已索引的所有项目。\n\n### 如果我更换嵌入提供者或模型，会发生什么？\n\n每个集合都是在索引时使用特定模型创建的，向量维度是固定的。如果您在 MCP 配置中更改 `EMBEDDING_PROVIDER`、`EMBEDDING_MODEL` 或 `EMBEDDING_DIMENSIONS`，那么使用旧模型索引的项目将会返回维度不匹配的错误。此时，您可以请 AI 删除该项目的索引，然后使用新模型重新索引。而您尚未触碰的项目则不受影响。\n\n### 如何删除某个项目的索引（例如为了切换嵌入模型或从头开始重新索引）？\n\n1. **先停止**——如果索引正在进行中，请说“停止索引该项目”。在索引进行中删除索引会导致数据损坏，因此系统会拒绝删除请求，直到当前批次完成。\n2. **删除索引**——请说“删除该项目的索引”。此操作将仅删除该项目的向量集合、所有存储的块元数据、代码图以及上下文工件元数据。其他项目不受影响。\n3. **重新索引**——如有必要，更新您的 MCP 配置以使用新的参数，然后让 AI 执行“索引该项目”以重新开始。\n\n### SocratiCode 标志中苏格拉底脸背后的代码是什么？\n\n您在苏格拉底背后看到的代码来自阿波罗 11 号指令舱（Comanche055）原始制导计算机（AGC）的源代码！\n\n\n## 社区\n\n- 💬 **[Discord](https:\u002F\u002Fdiscord.gg\u002F5DrMXfNG)**——与用户和维护者交流，提问“我该怎么做……”，分享您的项目成果\n- 🐛 **[GitHub Issues](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fissues)**——用于报告 bug 和确认功能请求（请使用模板）\n- 📣 **发布通知**——订阅仓库（GitHub 页面右上角 → *Custom* → *Releases*），以便及时获取新版本信息\n\n如果您觉得 SocratiCode 对您有帮助，最能帮上忙的一件事就是给这个仓库点个赞——这能让更多人发现这个项目。\n\n---\n\n## SocratiCode Cloud\n\n完整的 SocratiCode 引擎目前及未来都将以 AGPL-3.0 许可证开源。**SocratiCode Cloud** 是基于相同引擎的可选托管版本，目前处于**私密测试阶段**，专为希望使用共享、受管且合规基础设施的团队设计。\n\nCloud 在开源引擎的基础上增加了以下功能：\n\n- **共享团队索引**——每位开发者都能搜索相同的数据，每次推送和每个分支都会自动索引。\n- **跨仓库搜索**——只需一次查询即可搜索贵组织拥有的所有仓库。\n- **SSO \u002F SAML、审计日志、IP 允许列表**——这些功能内置其中，而非后期附加功能。\n- **部署模式**——托管云（欧盟\u002F美国）、您自己的 VPC（AWS\u002FGCP\u002FAzure），或完全气隙的本地部署。\n- **Web 控制面板**——用于搜索、依赖关系图、工件管理、团队和仓库管理。\n- **零本地基础设施**——团队无需管理 Docker、Qdrant 或 Ollama。\n\n目前正接入少量工程团队。**[申请早期访问→](https:\u002F\u002Fsocraticode.cloud)**\n\n> 此仓库中的开源引擎始终是驱动 Cloud 的同一引擎。绝无欺骗行为，也不会对开源核心进行功能限制。Cloud 只是在其基础上增加了团队、部署和合规层。\n\n---\n\n## 许可证\n\nSocratiCode 采用双重许可证：\n\n- **开源许可证**——[AGPL-3.0](LICENSE)。您可以自由使用、修改和分发。如果您修改了 SocratiCode 并将其作为网络服务提供，必须根据 AGPL-3.0 许可证公开您的修改内容。\n\n- **商业许可证**——适用于需要在专有产品或服务中使用 SocratiCode 而无需遵守 AGPL 条款的组织。详情请参阅 [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL)，或联系 [giancarlo@altaire.com](mailto:giancarlo@altaire.com)。\n\n版权所有 © 2026 Giancarlo Erra - Altaire Limited。\n\n### 第三方许可证\n\nSocratiCode 包含遵循各自许可证的开源依赖项（MIT、Apache 2.0、ISC）。详情请参阅 [THIRD-PARTY-LICENSES](THIRD-PARTY-LICENSES)。\n\n### 贡献\n\n我们欢迎贡献。通过提交拉取请求，即表示您同意 [贡献者许可协议](CLA.md)。","# SocratiCode 快速上手指南\n\nSocratiCode 是一款开源的代码库上下文引擎，能为 AI 助手提供对整个代码库（及基础设施）的深度语义理解。它支持混合搜索、跨项目搜索、多语言依赖图谱以及可搜索的上下文工件（如数据库架构、API 规范等），且无需复杂配置，完全本地化运行以保护隐私。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **操作系统**：Linux、macOS 或 Windows。\n*   **核心依赖**：必须安装并运行 **Docker** (推荐 Docker Desktop)。SocratiCode 将自动通过 Docker 部署 Qdrant 向量数据库和 Ollama 嵌入模型。\n*   **Node.js**：版本需 **>= 18**。\n*   **网络环境**：首次运行时需下载 Docker 镜像和嵌入模型，请确保网络连接畅通。\n    *   *提示*：国内用户若遇到 Docker 拉取缓慢问题，建议配置国内 Docker 镜像加速器。\n*   **硬件加速（可选但推荐）**：\n    *   对于中大型代码库，建议在 macOS (M 系列芯片) 或 Windows (NVIDIA 显卡) 上**原生安装 Ollama** 以启用 Metal\u002FCUDA 加速，否则仅依靠 Docker 容器可能无法调用 GPU。\n\n## 安装步骤\n\n您可以根据使用的 AI 编程工具选择以下任一方式进行安装。\n\n### 方式一：集成到主流 AI 编辑器（推荐）\n\n如果您使用 **Claude Code**、**VS Code** 或 **Cursor**，可通过以下命令一键安装插件或 MCP 服务。\n\n#### 1. Claude Code (推荐，包含工作流技能)\n在终端执行：\n```bash\nclaude plugin marketplace add giancarloerra\u002Fsocraticode\nclaude plugin install socraticode@socraticode\n```\n或者在 Claude Code 交互界面中输入：\n```text\n\u002Fplugin marketplace add giancarloerra\u002Fsocraticode\n\u002Fplugin install socraticode@socraticode\n```\n*安装后建议在插件设置中开启“自动更新”。*\n\n#### 2. VS Code \u002F VS Code Insiders\n点击以下链接直接安装 MCP Server，或手动在 `.vscode\u002Fmcp.json` 中添加配置：\n*   [安装到 VS Code](https:\u002F\u002Finsiders.vscode.dev\u002Fredirect\u002Fmcp\u002Finstall?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D)\n*   [安装到 VS Code Insiders](https:\u002F\u002Finsiders.vscode.dev\u002Fredirect\u002Fmcp\u002Finstall?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D&quality=insiders)\n\n手动配置示例 (` .vscode\u002Fmcp.json`)：\n```json\n\"socraticode\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"socraticode\"]\n}\n```\n\n#### 3. Cursor\n点击以下链接直接安装，或在 Cursor 设置中添加 MCP 服务器：\n*   [安装到 Cursor](cursor:\u002F\u002Fanysphere.cursor-deeplink\u002Fmcp\u002Finstall?name=socraticode&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNvY3JhdGljb2RlIl19)\n\n#### 4. 其他 MCP 宿主 (Windsurf, Cline, Roo Code 等)\n在您的 MCP 配置文件（通常为 `mcpServers` 部分）中添加：\n```json\n\"socraticode\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"socraticode\"]\n}\n```\n\n### 方式二：OpenCode 或 OpenAI Codex CLI\n\n**OpenCode** (`opencode.json`):\n```json\n{\n  \"mcp\": {\n    \"socraticode\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"socraticode\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n**OpenAI Codex CLI** (`~\u002F.codex\u002Fconfig.toml`):\n```toml\n[mcp_servers.socraticode]\ncommand = \"npx\"\nargs = [\"-y\", \"socraticode\"]\n```\n\n> **注意**：配置完成后请重启您的编辑器或 AI 宿主。首次运行时，SocratiCode 会自动拉取 Docker 镜像、启动容器并下载嵌入模型（耗时约 5 分钟，取决于网速）。后续启动仅需数秒。\n\n## 基本使用\n\n安装并重启宿主后，SocratiCode 即可投入使用。其核心理念是 **“先搜索，后阅读”**，以减少 AI 的上下文消耗并提高准确率。\n\n### 1. 初始化索引\n打开您的项目文件夹，向 AI 助手发送第一条指令：\n> **\"Index this codebase\"** (索引此代码库)\n\n*   索引将在后台运行。您可以随时询问 **\"What is the codebase index status?\"** 查看进度。\n*   对于大型项目（如 300 万行代码），在 M4 MacBook Pro 上首次索引通常少于 10 分钟。\n*   索引完成后无需重复执行，除非代码结构发生重大变化。\n\n### 2. 日常开发与查询\n索引完成后，您可以直接使用自然语言进行深度查询，例如：\n*   \"查找处理用户认证的所有相关文件。\"\n*   \"展示当前项目的数据库架构和 API 依赖关系图。\"\n*   \"解释 `src\u002Futils` 目录下的核心逻辑，并列出被调用的外部服务。\"\n*   \"搜索所有涉及支付超时的配置项。\"\n\n### 3. 增量更新与监控\n*   **自动更新**：SocratiCode 内置文件监听器，当您修改文件时，索引会自动增量更新。\n*   **断点续传**：如果索引过程因崩溃或中断停止，重启后会自动从上一个检查点恢复，不会丢失进度。\n*   **手动控制**：如需手动重启监听器，可指示 AI 执行：`codebase_watch { action: \"start\" }`。\n\n### 最佳实践提示\n为了获得最佳效果，建议在项目的 `CLAUDE.md` 或 `AGENTS.md` 文件中加入以下指引（若已安装 Claude Code 插件则自动包含，无需手动添加）：\n> \"Always search the codebase using SocratiCode tools before reading specific files to ensure context accuracy and reduce token usage.\"\n> (在使用 SocratiCode 工具搜索代码库之前，切勿直接读取具体文件，以确保上下文准确性并减少 Token 消耗。)","某大型金融科技团队需要在数千万行代码的遗留系统中，快速定位一个涉及多语言微服务、数据库变更及基础设施配置的复杂支付漏洞。\n\n### 没有 SocratiCode 时\n- **搜索效率极低**：开发者依赖传统的 `grep` 或基础语义搜索，面对海量代码库时响应缓慢，且无法跨项目或跨分支关联查找，往往需要数小时才能拼凑出线索。\n- **上下文理解割裂**：AI 助手因缺乏全局索引，无法理解多语言（Polyglot）间的依赖关系，经常遗漏关键的数据库 Schema 变更或基础设施配置细节，导致排查方向错误。\n- **资源消耗巨大**：为了让 AI 理解代码，开发者不得不手动粘贴大量文件片段，导致 Token 消耗量激增，API 调用次数频繁，不仅成本高昂且容易触发速率限制。\n- **协作与中断风险**：多人同时分析时缺乏统一的索引机制，且一旦索引构建过程中断（如崩溃或网络波动），进度全部丢失，需重新开始。\n\n### 使用 SocratiCode 后\n- **秒级精准定位**：SocratiCode 通过混合语义搜索和跨项目感知能力，瞬间锁定分散在不同仓库和分支中的相关代码段，将数小时的排查工作缩短至几分钟。\n- **全栈深度洞察**：工具自动构建包含数据库、API 规范及基础设施配置的全局依赖图谱，让 AI 能够“理解”而非仅仅“读取”代码，准确识别出底层配置引发的连锁反应。\n- **极致降本增效**：得益于智能索引管理，SocratiCode 使 Token 使用量减少 61%，API 调用降低 84%，搜索速度比传统 AI grep 快 37 倍，大幅节省计算资源。\n- **稳健的自动化体验**：零配置部署后，文件监听器自动实时更新索引，支持断点续传和多代理协同，确保团队在任意中断后都能无缝继续工作，无需重复劳动。\n\nSocratiCode 将原本碎片化、高成本的代码排查过程，转变为私有、即时且具备企业级深度的智能决策流。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fgiancarloerra_SocratiCode_c7d8e108.png","giancarloerra","Giancarlo Erra","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fgiancarloerra_524f6c16.jpg","Lead AI Consultant @ Altaire | Founder & Public Speaker | Creative Technologist | Software Builder | Professional Touring Musician & Producer","Altaire Limited","United Kingdom",null,"https:\u002F\u002Fwww.linkedin.com\u002Fin\u002Fgiancarloerra\u002F","https:\u002F\u002Fgithub.com\u002Fgiancarloerra",[83,87],{"name":84,"color":85,"percentage":86},"TypeScript","#3178c6",97.7,{"name":88,"color":89,"percentage":90},"JavaScript","#f1e05a",2.3,903,122,"2026-04-18T06:05:28","AGPL-3.0","Linux, macOS, Windows","非必需。本地部署时，macOS\u002FWindows 的 Docker 容器无法使用 GPU；建议安装原生 Ollama 以利用 Metal (Mac) 或 CUDA (Windows) 加速。未指定具体显卡型号、显存大小或 CUDA 版本要求。","未说明",{"notes":99,"python":100,"dependencies":101},"该工具主要基于 Node.js 运行，核心依赖是 Docker（用于自动部署 Qdrant 和 Ollama 容器）。首次运行需下载 Docker 镜像和嵌入模型（约 5 分钟）。对于大型代码库，建议在 macOS\u002FWindows 上安装原生 Ollama 以获得 GPU 加速，或使用云端嵌入服务（OpenAI\u002FGoogle Gemini）。支持断点续传索引和文件自动监听更新。","未说明 (基于 Node.js)",[102,103,104,105],"Node.js >= 18","Docker","Qdrant","Ollama",[45,13,15,16,14],[108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127],"ai","ai-assistant","embeddings","mcp","semantic","vector-database","vector-embeddings","vector-search","claude","codebase-intelligence","docker","gemini","openai","qdrant","ast","code-graph","semantic-search","context-engine","gemini-cli-extension","claude-code","2026-03-27T02:49:30.150509","2026-04-18T22:35:18.367413",[131,136,141,146,150,155],{"id":132,"question_zh":133,"answer_zh":134,"source_url":135},40915,"SocratiCode 是否支持除 Claude Code 以外的其他代理编码环境（如 OpenCode）？","是的，SocratiCode 完全平台无关，因为它基于 MCP（模型上下文协议），兼容 OpenCode 等其他环境。维护者已更新 README，提供了针对 OpenCode 的配置代码片段，用户可直接参考使用。","https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002FSocratiCode\u002Fissues\u002F18",{"id":137,"question_zh":138,"answer_zh":139,"source_url":140},40916,"如何在 SocratiCode 中实现跨项目搜索（Cross-project search）？","可以通过以下两种方式配置：\n1. 在项目根目录创建 `.socraticode.json` 文件，添加 linkedProjects 数组：\n```json\n{\n  \"linkedProjects\": [\"..\u002Fshared-lib\", \"\u002Fpath\u002Fto\u002Fother-project\"]\n}\n```\n2. 或者在 MCP 环境变量中设置：`SOCRATICODE_LINKED_PROJECTS=\"..\u002Fshared-lib,\u002Fpath\u002Fto\u002Fother-project\"`。\n配置后，搜索时加上 `includeLinked: true` 参数，结果将包含所有链接项目的内容，并自动去重和标记项目名称。注意：每个链接的项目必须先独立完成索引。","https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002FSocratiCode\u002Fissues\u002F19",{"id":142,"question_zh":143,"answer_zh":144,"source_url":145},40917,"为什么使用 SocratiCode 插件后 Token 消耗量激增到数百万？","这通常不是 SocratiCode 本身的问题，而是宿主工具（如 Claude Code）的行为导致的。例如，当要求 Claude Code 制定计划并结合其他 MCP（如 Figma MCP）时，它可能会自动启动多个子代理（sub-agents），每个子代理都携带大量上下文（如 50k tokens），从而导致总消耗剧增。\n建议解决方案：\n1. 减少 SocratiCode 返回的结果数量或提高阈值，以降低单个请求的上下文大小。\n2. 考虑使用 VSCode + Copilot 组合，它们通常更可控且 Token 消耗更低，不会像某些代理工具那样自主决策启动不必要的子任务。","https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002FSocratiCode\u002Fissues\u002F28",{"id":147,"question_zh":148,"answer_zh":149,"source_url":140},40918,"SocratiCode 如何处理团队开发中的长生命周期分支和多开发者协作冲突？","SocratiCode 引入了三层索引层级结构来解决此问题：\n1. **Main 层**：共享主索引，仅在合并时更新。\n2. **Branch 层**：基于 Main 层的快照分叉，对应特定分支，仅在推送时更新。通过 Qdrant 的快照恢复功能快速创建，无需重新嵌入整个代码库。\n3. **Head 层**：基于 Branch 层的个人快照，仅包含当前开发者未提交的本地修改（通过 `git status --porcelain` 识别）。每次推送后会丢弃并重新从 Branch 层分叉。\n搜索时，如果存在 Head 层，系统会并行查询 Head 和 Branch 层并去重，确保既能看到共享分支状态，又能看到个人实时修改。",{"id":151,"question_zh":152,"answer_zh":153,"source_url":154},40919,"SocratiCode 目前的依赖图功能支持哪些编程语言？Java 支持吗？","目前依赖图功能（`codebase_graph_query` 等）已支持 JavaScript\u002FTypeScript (ESM + CommonJS)、CSS (`@import`)、Svelte 和 Vue，这些主要通过文件路径解析。对于 Java 项目，由于导入语句是完全限定类名（如 `import cn.sino.sso.service.UserService`），需要对照源树（通常是 `src\u002Fmain\u002Fjava\u002F`）进行解析，目前尚未原生支持，因此会产生 0 条边。社区已提出通过正则表达式或 tree-sitter java 语法来解析 import 语句的建议，但截至该 Issue 关闭时，官方尚未完全实现企业级 Java\u002FSpring Boot 的依赖图解析功能。","https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002FSocratiCode\u002Fissues\u002F21",{"id":156,"question_zh":157,"answer_zh":158,"source_url":159},40920,"如何将自己的项目提交到 awesome-ai-plugins 列表？","提交步骤如下：\n1. Fork `awesome-ai-plugins` 仓库。\n2. 在 `README.md` 中找到最相关的分类部分，按照 `CONTRIBUTING.md` 规定的格式添加条目。\n3. 提交 Pull Request (PR)。\n成功列入该项目后，还有可能在 HOL 的插件目录 (https:\u002F\u002Fhol.org\u002Fregistry\u002Fplugins) 中展示。","https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002FSocratiCode\u002Fissues\u002F27",[161,166,171,176,181,186,191,196,201,206,211,216,221,226,231],{"id":162,"version":163,"summary_zh":164,"released_at":165},324467,"v1.6.1","## [1.6.1](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.6.0...v1.6.1) (2026-04-17)\n\n### 文档\n\n* 添加对 Zed 的支持、针对各 IDE 的操作指引路径，并强化图表触发机制 ([270d402](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F270d402f48f6a87e966120ce264bbacd0a19c9a7))","2026-04-17T10:19:41",{"id":167,"version":168,"summary_zh":169,"released_at":170},324468,"v1.6.0","## [1.6.0](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.5.0...v1.6.0) (2026-04-16)\n\n### 功能\n\n* 支持全局配置回退和可配置的批处理大小 ([9d04c44](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F9d04c4443a7b0892548868fe04e59f9a35e43dcf))\n\n### 错误修复\n\n* 解析全局配置回退和严格批处理大小校验中的相对路径 ([49b5b35](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F49b5b35bff2809c17f1096cb62db7670503594aa))\n\n### 文档\n\n* 将 CodeRabbit 审查期望添加到 PR 模板和贡献指南中 ([afd2da2](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fafd2da2771e5ebe9cd81e391179adb769463ddb8))\n* 在 README 中添加 Discord 社区、云部分以及工具可移植性说明 ([a8b069a](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fa8b069a900d5a4a20023b995ea0ecfe6b237cb7b))","2026-04-16T18:04:14",{"id":172,"version":173,"summary_zh":174,"released_at":175},324469,"v1.5.0","## [1.5.0](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.4.1...v1.5.0) (2026-04-13)\n\n### 功能\n\n* 多平台插件支持（Cursor、Codex、Gemini CLI、VS Code）([529d1b2](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F529d1b2a642d9681ffce437cb2f902efa5aa7e6f))\n\n### 错误修复\n\n* 修正 GEMINI.md 中“visualize”的拼写，并更新 README.md 中的 Codex 安装说明 ([b2333b5](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fb2333b574c3a978c6f3f5d6645e578b5d5bf03dc))\n\n### 文档\n\n* 整合 README ([61060d5](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F61060d51538a6f9fee550b7cda7f62ac47f07518))\n* 整合 README — 添加功能对比表并精简各部分内容 ([efec8dd](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fefec8dd29adb9da2c3308f1e3c470663c36773db))","2026-04-13T21:47:09",{"id":177,"version":178,"summary_zh":179,"released_at":180},324470,"v1.4.1","## [1.4.1](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.4.0...v1.4.1)（2026-04-12）\n\n### Bug 修复\n\n* 处理 CodeRabbit 的 PR 审查反馈 ([00f7be1](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F00f7be169c94661a098fff5e9354746823db1630))\n* 处理 CodeRabbit 的审查发现 ([bb5e6c3](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fbb5e6c3e198effb1809d0a6c5286a34f8da0df68))","2026-04-12T20:38:02",{"id":182,"version":183,"summary_zh":184,"released_at":185},324471,"v1.4.0","## [1.4.0](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.3.2...v1.4.0) (2026-04-12)\n\n### 功能特性\n\n* 通过 SOCRATICODE_BRANCH_AWARE 实现分支感知的集合命名（[3a4139d](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F3a4139d71426e7097a0b897db47dce99c5fac5b4)），关闭 [#19](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fissues\u002F19)\n* 通过 .socraticode.json 和 SOCRATICODE_LINKED_PROJECTS 支持关联项目（[61e868c](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F61e868cf9ef484cc83777d302094b10dd48ec5e3)），关闭 [#20](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fissues\u002F20)\n* 客户端 RRF 融合与去重的多集合搜索（[ad8db7f](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fad8db7f0db53bc0425e26282313706a8099fb792)），关闭 [#20](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fissues\u002F20) [#19](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fissues\u002F19) [#19](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fissues\u002F19) [#20](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fissues\u002F20)\n\n### 错误修复\n\n* 根据 CodeRabbit 的评审反馈改进测试（[f09f417](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Ff09f417c6ec5446482b3fd7dc069b31435e7b81d)）\n* 解决剩余的 CodeRabbit 生产代码问题（[f745d59](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Ff745d59ddd5baa722c49f2183bc2b922b630711d)）\n* 关联项目使用不带分支后缀的基础哈希值（[fc3c298](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Ffc3c2988fa44c4441f2bddd209c4a55d1e4d8a1b)）\n* 在 CI 中为临时仓库提交提供 Git 用户身份信息（[ad2e3b9](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fad2e3b9ea16f24a39c7f0122c2388eaa4ca442a9)）\n* 解析多模块 Maven\u002FGradle 项目中的 JVM 导入（[5a734eb](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F5a734eb301e9f9f53724be0da6818afa6927758f)）\n* 更新索引器和查询工具中的路径处理与类型导入（[096f59d](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F096f59da130b155b435b291be85b212c78ae25fa)）\n* 在分支感知测试中使用自包含的临时 Git 仓库（[ffa8e95](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fffa8e95bdf00f2a245bbd181dec0ea5fbbec6804)）\n\n### 文档更新\n\n* 在简介和“为什么选择 SocratiCode”部分添加跨项目和分支感知的高亮说明（[24faa10](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F24faa1075b77f88e63c785afb42c5bcd9538767d)）\n* 添加关于跨项目搜索和分支感知索引的文档（[76e3ff5](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F76e3ff5f59720402bbbe07819ed69e6c93976f43)）\n* 在 README 中添加 OpenCode 的设置说明（[0896164](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F0896164442e340c234f37437cae11ebc65b139f5)），关闭 [#18](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fissues\u002F18)\n\n### 测试改进\n\n* 添加 includeLinked 和 searchMultipleCollections 测试（[bf93e4a](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fbf93e4a992ae39d2030a1452c60b8613e72b4d2e)）","2026-04-12T18:31:20",{"id":187,"version":188,"summary_zh":189,"released_at":190},324472,"v1.3.2","## [1.3.2](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.3.1...v1.3.2) (2026-03-26)\n\n### 错误修复\n\n* 将 SessionStart 钩子类型由 prompt 改为 command ([72e4a5f](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F72e4a5f9983b0169044af6bac411e909398559aa))，关闭 [#16](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fissues\u002F16)","2026-03-26T18:07:11",{"id":192,"version":193,"summary_zh":194,"released_at":195},324473,"v1.3.1","## [1.3.1](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.3.0...v1.3.1) (2026-03-24)\n\n### Bug 修复\n\n* 添加 `prepublishOnly` 脚本，以确保在发布前重新构建 `dist\u002F` 目录 ([2f5b410](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F2f5b410a04eb8be6e76a18e19dcfa0c169fdd144))","2026-03-24T17:38:34",{"id":197,"version":198,"summary_zh":199,"released_at":200},324474,"v1.3.0","## [1.3.0](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.2.0...v1.3.0) (2026-03-19)\n\n### 功能\n\n* 在依赖图中添加对 CSS `@import` 的跟踪以及路径别名解析 ([c7e160c](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fc7e160cb5ca0c5bd6e0ba9e2a258587c106fbab5))\n\n### Bug 修复\n\n* 将 Stylus 添加到 CSS 解析场景及 getAstGrepLang 映射中 ([f80eec4](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Ff80eec476afc3c3979214ca2a331f08eb0cee0c8))\n\n### 文档\n\n* 更新语言支持和图表文档，以支持 CSS `@import` 和路径别名 ([f4c5518](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Ff4c5518453afd3752ea4777419b5b04036ffd07d))","2026-03-19T11:59:58",{"id":202,"version":203,"summary_zh":204,"released_at":205},324475,"v1.2.0","## [1.2.0](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.1.3...v1.2.0) (2026-03-18)\n\n### 功能\n\n* 添加环境变量支持，用于控制对隐藏文件的索引 ([7265247](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F7265247d838b1792242a7ad082e6a35ec0759ce2))\n* 将 Svelte 和 Vue 的导入解析添加到依赖图中 ([4c2bd0c](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F4c2bd0cc539e1fc170d019e073517b638ebbb294))\n* 自动从 QDRANT_URL 推断端口，以支持反向代理 ([507d823](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F507d823336a5340ea1c0bbba3b39acef9a1a35e0))\n\n### 错误修复\n\n* 仅在使用 Ollama 提供者时调用 ensureOllamaReady ([#8](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fissues\u002F8)) ([4d255f5](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F4d255f50ee46e75aa2e1b23ef48e9809dc6b80d7)), 关闭了 [#7](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fissues\u002F7)\n\n### 文档\n\n* 为仅安装 MCP 的情况添加 npx 缓存更新说明 ([4cd113b](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F4cd113b1e9e3776d127cd16545b9c048f353daf8))\n* 将 Svelte\u002FVue 添加到代码图的语言列表中 ([7b72cf0](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F7b72cf0363797ec7996e4b417abbfb538c6a1b78))","2026-03-18T13:56:48",{"id":207,"version":208,"summary_zh":209,"released_at":210},324476,"v1.1.3","## [1.1.3](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.1.2...v1.1.3) (2026-03-16)\n\n### 错误修复\n\n* 使用相对路径作为索引键，以支持共享工作树索引（[505fbd7](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F505fbd722bdb5cc310f7406df88a436e682a3b8b)）\n\n### 文档\n\n* 添加 Claude Code 插件的自动更新说明（[b26038a](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fb26038a8b184fc63e7315d8d4a5cf0af3e37ae31)）","2026-03-16T22:57:27",{"id":212,"version":213,"summary_zh":214,"released_at":215},324477,"v1.1.2","## [1.1.2](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.1.1...v1.1.2) (2026-03-16)\r\n\r\n### Bug Fixes\r\n\r\n* correct hooks.json format, remove explicit hooks path, and improve install docs ([db69a2d](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fdb69a2d9b4e63324746741cf8b29931e81d652da))","2026-03-16T01:00:47",{"id":217,"version":218,"summary_zh":219,"released_at":220},324478,"v1.1.1","## [1.1.1](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.1.0...v1.1.1) (2026-03-16)\r\n\r\n### Bug Fixes\r\n\r\n* correct Claude Code plugin install commands and add marketplace.json ([157b353](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F157b353bc47e519a35561488967f01107de5b380))","2026-03-16T00:42:18",{"id":222,"version":223,"summary_zh":224,"released_at":225},324479,"v1.1.0","## [1.1.0](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.0.1...v1.1.0) (2026-03-15)\r\n\r\n### Features\r\n\r\n* add Claude Code plugin with skills, agent, and MCP bundling ([31e5d74](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F31e5d748bc65681686642e19252282a440785520))\r\n* add SOCRATICODE_PROJECT_ID env var for shared indexes across directories ([fadfd8a](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Ffadfd8a80e6d33925fd071272a01d5132d7148cd))\r\n\r\n### Documentation\r\n\r\n* add Claude Code worktree auto-detection to git worktrees section ([d7c32d1](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002Fd7c32d1435021172762531860350f38f83173edf))\r\n* add git worktrees section to README ([3cad30a](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F3cad30a6509837af2346fe6e83c7ec3aadc04900))\r\n* add multi-agent collaboration as a featured capability ([72c7ce0](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F72c7ce05f840b2870e83182ad83e4b0ee1938bef))","2026-03-16T00:00:05",{"id":227,"version":228,"summary_zh":229,"released_at":230},324480,"v1.0.1","## [1.0.1](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcompare\u002Fv1.0.0...v1.0.1) (2026-03-04)\r\n\r\n### Bug Fixes\r\n\r\n* add mcpName and read version dynamically from package.json ([88c0e8f](https:\u002F\u002Fgithub.com\u002Fgiancarloerra\u002Fsocraticode\u002Fcommit\u002F88c0e8fee39c7fb733bdec4657d2eaf2c355292e))","2026-03-04T18:09:04",{"id":232,"version":233,"summary_zh":234,"released_at":235},324481,"v1.0.0","## SocratiCode v1.0.0\r\n\r\n**Give any AI instant automated knowledge of your entire codebase — at scale, zero configuration, fully private, completely free.**\r\n\r\nSocratiCode is an MCP server that gives AI assistants deep semantic understanding of your codebase. One-line install, zero configuration — it manages everything automatically via Docker.\r\n\r\n### Highlights\r\n\r\n- **Hybrid search** — Dense vector (semantic) + BM25 (keyword) search fused with Reciprocal Rank Fusion. Find code by meaning or by name, in a single query.\r\n- **AST-aware chunking** — Files split at function\u002Fclass boundaries using ast-grep, not arbitrary line counts. Higher-quality search results out of the box.\r\n- **Polyglot code dependency graph** — Static analysis of imports across 18+ languages. Circular dependency detection and Mermaid visualization.\r\n- **Context artifacts** — Index database schemas, API specs, infra configs, and architecture docs alongside your code.\r\n- **Zero configuration** — Add the MCP server config, and it handles Docker containers, embedding models, and vector storage automatically.\r\n- **Fully private & local** — Everything runs on your machine. No API keys required, no data leaves your network. Optional cloud providers (OpenAI, Google Gemini, Qdrant Cloud) available when you want them.\r\n- **Production-ready** — Battle-tested on enterprise repositories up to ~40M lines of code. Batched, resumable indexing with automatic checkpointing. Cross-process safety via file locking.\r\n- **Incremental & live** — After first index, only changed files are re-processed. File watcher keeps the index updated automatically.\r\n\r\n### Quick Start\r\n\r\n```json\r\n\"socraticode\": {\r\n  \"command\": \"npx\",\r\n  \"args\": [\"-y\", \"socraticode\"]\r\n}","2026-02-28T17:10:36"]