如何与整个团队共享SocratiCode代码索引？Git Worktree+共享Qdrant配置完全教程

如何与整个团队共享SocratiCode代码索引Git Worktree共享Qdrant配置完全教程【免费下载链接】SocratiCodeEnterprise-grade (40m LOC) codebase intelligence, zero-setup, local private Plugin/Skill/Extension or MCP: hybrid semantic search, polyglot dependency graphs, symbol-level impact analysis call-flow, interactive HTML viewer, cross-project branch-aware search, DB/API/infra knowledge. 61% less tokens, 84% fewer calls, 37x faster. Cloud in beta.项目地址: https://gitcode.com/gh_mirrors/so/SocratiCodeSocratiCode 代码索引团队共享的核心思路是整个团队共用一个Qdrant 向量数据库所有成员无论代码在本地哪个目录都指向同一套索引集合codebase_my-project、codegraph_my-project、context_my-project。这样只需构建一次索引全员受益避免每个人各自嵌入embedding一遍相同代码带来的重复存储与算力浪费。配合Git Worktree工作流你甚至可以在多个目录中同时工作却只维护一份语义索引。本教程面向新手按「共享 Qdrant → 固定项目身份 → 配置团队 → 指定写入者 → 验证」的顺序带你完成全部设置。官方团队指南见 docs/guides/team.md。为什么团队要共享一份 SocratiCode 代码索引先理解默认行为SocratiCode 会为每个项目路径生成独立的 Qdrant 索引。这意味着每位同事克隆同一个仓库后各自索引一遍——嵌入计算和存储全部重复多个 Git Worktree同一仓库的不同工作目录也会各自生成索引同样冗余。共享索引之后索引构建一次全员搜索受益即使大家使用不同的操作系统、不同的用户账户、完全不同的文件系统布局都指向同一份代码知识。这正是 README.md 中「Team-Shared Index」与「Git Worktrees」章节推荐的团队用法。准备工作部署一个共享 Qdrant 实例默认情况下 SocratiCode 用 Docker 自动管理本地 Qdrant但团队共享场景必须使用外部 Qdrant自建服务器、Qdrant Cloud 均可。⚠️ 注意边界与默认的本地部署不同源代码分块和索引元数据会发送到这个共享端点请确保它在团队受信任的网络内。对每个使用共享索引的 SocratiCode MCP 进程配置相同的三个环境变量变量作用QDRANT_MODEexternal告诉 SocratiCode 使用外部 Qdrant不再管理本地容器QDRANT_URL共享 Qdrant 的完整 URL所有成员必须一致QDRANT_API_KEY认证密钥如需要通过私有配置传递严禁提交到仓库两个硬性前提自建 Qdrant 需v1.15.2 或更高版本混合搜索依赖服务端 BM25 推断所有进程必须使用相同的嵌入提供商、模型、维度和索引表示设置——向量空间不一致会导致搜索结果不可用且已有索引不会静默转换。各宿主Claude Code、Cursor、VS Code 等传递环境变量的具体写法可参考 README.md 的「Passing env vars by host」章节。第一步在 .socraticode.json 中固定项目身份这是团队共享最关键的一步。在仓库根目录创建并提交.socraticode.json{ projectId: team-service }规则与细节取值只能包含字母、数字、_或-正则[a-zA-Z0-9_-]空白会被自动修剪建议直接使用仓库自身名称作为标识如team-service、my-project提交前保留该文件中已有的其他配置不要设置SOCRATICODE_PROJECT_ID环境变量——它会覆盖文件中的projectId破坏团队一致性该值一旦确定就保持稳定已存在于其他 ID 下的旧索引不会迁移只会保持独立。配置后任何检出——无论落在磁盘哪个路径、属于哪个用户——都会寻址同一套 Qdrant 集合。这正是团队共享 Qdrant 实例的推荐设置。第二步为每位队友配置相同的 SocratiCode MCP 进程每位成员在自己的 MCP 宿主中安装 SocratiCode并统一设置{ mcpServers: { socraticode: { command: npx, args: [-y, --prefer-online, socraticodelatest], env: { QDRANT_MODE: external, QDRANT_URL: https://你的共享qdrant地址 } } } }关键点上表中的QDRANT_URL必须是团队共享的同一个地址QDRANT_API_KEY放入各人私有的宿主配置用户级 env 文件、进程环境等永远不要提交进项目文件嵌入设置提供商 / 模型 / 维度全员对齐例如都用本地 Ollama 或都指向同一个远程嵌入服务。第三步指定一个「写入者」检出其余成员只读共享索引需要明确的写入分工避免多个进程同时改写同一集合 写入者指定一位成员的一个检出运行codebase_index一次并通过codebase_status等待完成保持默认的文件监听器watcher运行——源码变更时自动增量更新索引或在源码变更后从该检出手动运行codebase_update。 读者其他所有成员在各自 MCP 进程中设置SOCRATICODE_WATCHERoff SOCRATICODE_AUTO_RESUMEoff然后直接搜索共享集合不要运行 update 或 index 操作。这样读者只消费索引索引的新鲜度由写入者保证。 这不是「共享实时工作区」或跨机器文件监听——它共享的是一份索引。读者在搜索前最好与团队对齐源码版本同一 commit/分支状态把结果当作当前代码。Git Worktree 模式多目录共享同一索引如果你的工作流是Git Worktree同一仓库同时存在于多个目录比如主分支 两个功能分支各开一个目录可以更进一步——连写入者分工都不必那么严格方案 A支持 worktree 检测的 MCP 宿主如 Claude Code这类宿主会沿 git worktree 链接解析项目根目录。只需在主检出中配置一次claude mcp add -e SOCRATICODE_PROJECT_IDmy-project --scope local socraticode -- npx -y --prefer-online socraticodelatest之后所有从该仓库创建的 worktree 都会自动继承共享项目 ID无需逐个 worktree 配置。方案 B其他 MCP 宿主在每个 worktree以及主检出根目录放置.mcp.json写入带SOCRATICODE_PROJECT_ID: my-project的服务定义见第二步的 JSON 模板在env中加上该变量即可。不想要跟踪的话可将其加入.gitignore。实际效果如何所有 worktree 共享同一套codebase_my-project、codegraph_my-project、context_my-project集合索引反映「最近触发文件变更的 worktree」的状态——由于分支间通常只差少量文件对全部 worktree 的准确率都在 99% 以上AI 代理读取的始终是自己 worktree 中的真实文件内容共享索引只用于发现和导航变更合回主分支后文件监听器会重新索引变更文件索引自动收敛。⚠️ 注意这仅对真正的 git worktree 生效。独立的git clone拥有各自独立的.git目录不会共享配置——团队成员场景请用「提交projectId」的方案。验证确认团队共享索引已生效从任意一个读者检出源码版本与写入者一致时执行codebase_status— 确认能看到共享集合的状态与分块数量codebase_search— 搜索一个你已知位置的功能例如「authentication middleware」检查结果是否指向预期的仓库文件。如果读者进程报告「另一个进程正在监听该项目」的提示说明写入者的 watcher 正在正常工作共享索引仍会自动更新。常见坑清单问题原因与解决团队各搜各的索引没共享QDRANT_URL不一致或有人漏设QDRANT_MODEexternal改了projectId旧索引消失显式 ID 变更等于新身份旧集合不会迁移ID 一旦提交就保持稳定搜索结果质量差嵌入提供商/模型/维度未全员对齐已有向量不会静默转换需删除重建设置了SOCRATICODE_PROJECT_ID后行为异常环境变量优先级高于.socraticode.json团队场景应取消该变量读者误触发更新操作读者进程务必设置SOCRATICODE_WATCHERoff与SOCRATICODE_AUTO_RESUMEoff想清理废弃索引用codebase_prune先盘点再按确认令牌删除共享 Qdrant 中需确认没有其他远程写入者延伸阅读团队共享索引官方指南docs/guides/team.md完整配置与环境变量参考QDRANT_*、SOCRATICODE_PROJECT_ID、SOCRATICODE_BRANCH_AWARE等README.md快速上手指南合集docs/guides/README.md本地纯私有不共享的对照方案docs/guides/local-only.md按以上步骤完成配置后你的团队就拥有了一份构建、全员共享的 SocratiCode 代码索引——语义搜索、依赖图、符号级影响分析对每位成员即刻可用。【免费下载链接】SocratiCodeEnterprise-grade (40m LOC) codebase intelligence, zero-setup, local private Plugin/Skill/Extension or MCP: hybrid semantic search, polyglot dependency graphs, symbol-level impact analysis call-flow, interactive HTML viewer, cross-project branch-aware search, DB/API/infra knowledge. 61% less tokens, 84% fewer calls, 37x faster. Cloud in beta.项目地址: https://gitcode.com/gh_mirrors/so/SocratiCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考