企业官网建设流程全解析

如何与整个团队共享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/SocratiCode

SocratiCode 代码索引团队共享的核心思路是：整个团队共用一个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 进程，配置相同的三个环境变量：

两个硬性前提：

1. 自建 Qdrant 需v1.15.2 或更高版本（混合搜索依赖服务端 BM25 推断）；
2. 所有进程必须使用相同的嵌入提供商、模型、维度和索引表示设置——向量空间不一致会导致搜索结果不可用，且已有索引不会静默转换。

各宿主（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", "socraticode@latest"], "env": { "QDRANT_MODE": "external", "QDRANT_URL": "https://你的共享qdrant地址" } } } }

关键点：

• 上表中的QDRANT_URL必须是团队共享的同一个地址；
• QDRANT_API_KEY放入各人私有的宿主配置（用户级 env 文件、进程环境等），永远不要提交进项目文件；
• 嵌入设置（提供商 / 模型 / 维度）全员对齐，例如都用本地 Ollama 或都指向同一个远程嵌入服务。

第三步：指定一个「写入者」检出，其余成员只读

共享索引需要明确的写入分工，避免多个进程同时改写同一集合：

📝 写入者（指定一位成员的一个检出）

1. 运行codebase_index一次，并通过codebase_status等待完成；
2. 保持默认的文件监听器（watcher）运行——源码变更时自动增量更新索引；
3. 或在源码变更后，从该检出手动运行codebase_update。

🔍 读者（其他所有成员）

在各自 MCP 进程中设置：

SOCRATICODE_WATCHER=off SOCRATICODE_AUTO_RESUME=off

然后直接搜索共享集合，不要运行 update 或 index 操作。这样读者只消费索引，索引的新鲜度由写入者保证。

💡 这不是「共享实时工作区」或跨机器文件监听——它共享的是一份索引。读者在搜索前，最好与团队对齐源码版本（同一 commit/分支状态），把结果当作当前代码。

Git Worktree 模式：多目录共享同一索引

如果你的工作流是Git Worktree（同一仓库同时存在于多个目录，比如主分支 + 两个功能分支各开一个目录），可以更进一步——连写入者分工都不必那么严格：

方案 A：支持 worktree 检测的 MCP 宿主（如 Claude Code）

这类宿主会沿 git worktree 链接解析项目根目录。只需在主检出中配置一次：

claude mcp add -e SOCRATICODE_PROJECT_ID=my-project --scope local socraticode -- npx -y --prefer-online socraticode@latest

之后所有从该仓库创建的 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」的方案。

验证：确认团队共享索引已生效

从任意一个读者检出（源码版本与写入者一致时）执行：

1. codebase_status— 确认能看到共享集合的状态与分块数量；
2. codebase_search— 搜索一个你已知位置的功能，例如「authentication middleware」；
3. 检查结果是否指向预期的仓库文件。

如果读者进程报告「另一个进程正在监听该项目」的提示，说明写入者的 watcher 正在正常工作，共享索引仍会自动更新。

常见坑清单

延伸阅读

• 团队共享索引官方指南：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