codebase-management

SocratiCode 管理

设置、索引和管理 SocratiCode 代码库索引、文件监视、代码图谱及上下文工件。

首次设置

1. 检查基础设施：codebase_health — 验证 Docker、Qdrant、Ollama/嵌入提供商及嵌入模型
2. 开始索引：codebase_index — 在后台运行并立即返回
3. 轮询进度：codebase_status — 每隔约 60 秒调用一次，直到完成 100%
   • 这也会保持 MCP 连接处于活动状态（某些宿主会断开闲置连接）
4. 完成：索引完成后会自动构建图谱。在默认监视器模式下，文件监视器会自动启动。现在可以开始搜索。

首次使用时，SocratiCode 会自动拉取 Docker 镜像、启动容器并下载嵌入模型（一次性设置约需 5 分钟）。

增量更新与文件监视

在默认的 SOCRATICODE_WATCHER=auto 模式下，文件监视器会自动保持索引更新。

• codebase_watch { action: "start" } — 启动监视器（先执行补齐更新）
• codebase_watch { action: "stop" } — 停止监视器
• codebase_watch { action: "status" } — 列出正在监视的项目（包括跨进程项目）
• codebase_update — 手动执行增量更新（仅更新有更改的文件，同步执行）。如果监视器处于活动状态，通常不需要手动更新。

如果需要固定代码索引快照，请将所有使用此检出的 MCP 进程配置为 SOCRATICODE_WATCHER=off 和 SOCRATICODE_AUTO_RESUME=off。搜索和图谱工具仍会读取现有索引和图谱；只有在需要刷新时才运行 codebase_update 和 codebase_graph_build。如果希望仍可显式调用 codebase_watch { action: "start" }，请改用监视器模式 manual。如果监视器状态显示其已禁用，切勿尝试重启。

使用 SOCRATICODE_WATCHER=git 时，活动索引检出会在检出的 ref/HEAD 发生变化时刷新；每 10 秒检查一次，也会在收到搜索、状态或图谱请求时检查。不会启动原生文件监视器。待处理或失败的刷新结果并非最新结果。Git 会触发更新，但实际索引内容是工作树，包括未提交的编辑。对于不会更改 ref/HEAD 的文件保存，请使用 codebase_update。选择 Git 模式不会创建初始索引。SOCRATICODE_AUTO_RESUME=off 会禁止启动时的补齐更新，但不会禁止之后由 Git 触发的更新。不得通过启动监视器来绕过 Git 诊断。

管理索引

• codebase_stop — 安全暂停正在进行的索引。当前批次会完成并创建检查点。所有进度都会保留。使用 codebase_index 恢复。
• codebase_remove — 删除整个索引（不可逆操作）。会安全停止监视器、取消索引，并等待图谱构建完成。
• codebase_prune — 清点已存储的标识；按精确标识删除，并需要新的确认令牌和共享存储确认。路径不存在仅供参考，绝不会作为候选集。
• codebase_list_projects — 列出所有已索引项目及其元数据、图谱信息和工件状态。

管理代码图谱

索引完成后会自动构建依赖图。在监视器模式 manual 和 off 下，图谱查询会读取现有图谱；如果图谱缺失，则会要求显式构建，而不会将创建图谱作为副作用。

• codebase_graph_build — 手动重新构建（在后台异步运行）。使用 codebase_graph_status 轮询状态。
• codebase_graph_remove — 删除图谱（下次运行 codebase_index 时会自动重建）
• codebase_graph_status — 检查构建进度或图谱是否就绪

上下文工件设置

要为非代码知识建立索引，请在项目根目录中创建 .socraticodecontextartifacts.json：

{
  "artifacts": [
    {
      "name": "database-schema",
      "path": "./docs/schema.sql",
      "description": "PostgreSQL schema — all tables, indexes, constraints, foreign keys."
    }
  ]
}

支持的类型：SQL 架构、OpenAPI/Protobuf API 规范、Terraform/CloudFormation 配置、Kubernetes 清单、架构文档、环境配置——任何基于文本的文件或目录。

• codebase_context_index — 手动为所有工件建立索引或重新建立索引（通常会自动触发）
• codebase_context_remove — 移除所有已建立索引的工件（索引期间不可用）

故障排除

问题	解决方案
Docker 不可用	从 https://docker.com 安装 Docker Desktop，并确保其正在运行
macOS/Windows 上索引缓慢	Docker 无法使用 GPU。请从 https://ollama.com/download 安装原生 Ollama，以利用 Metal/CUDA 加速。也可使用云端嵌入。
想改用云端嵌入	设置 EMBEDDING_PROVIDER=openai + OPENAI_API_KEY，或设置 EMBEDDING_PROVIDER=google + GOOGLE_API_KEY
搜索没有返回结果	检查 codebase_status——项目可能尚未建立索引。运行 codebase_index。
结果过时	检查 codebase_status。运行 codebase_update；仅当状态未显示已禁用时才启动监视器。
索引过程被中断	再次运行 codebase_index——它会自动从上一个检查点恢复。
另一个进程正在建立索引	codebase_status 可检测跨进程索引。请等待其完成，或使用 codebase_stop。

关键环境变量

变量	默认值	说明
QDRANT_MODE	managed	managed（Docker）或 external（远程/云端 Qdrant）
QDRANT_URL	—	远程 Qdrant 的完整 URL（例如 https://xyz.cloud.qdrant.io:6333）
QDRANT_API_KEY	—	远程 Qdrant 的 API 密钥
EMBEDDING_PROVIDER	ollama	ollama、openai 或 google
OPENAI_API_KEY	—	当 EMBEDDING_PROVIDER=openai 时必需
GOOGLE_API_KEY	—	当 EMBEDDING_PROVIDER=google 时必需
OLLAMA_MODE	auto	auto（检测原生安装，回退到 Docker）、docker、external
EMBEDDING_MODEL	nomic-embed-text	模型名称（取决于提供方）
SEARCH_DEFAULT_LIMIT	10	codebase_search 的默认结果数量限制（1-50）
SEARCH_MIN_SCORE	0.10	默认 RRF 最低分数阈值（0-1）
MAX_FILE_SIZE_MB	5	建立索引时允许的最大文件大小，单位为 MB；必须是完整的有限数值
EXTRA_EXTENSIONS	—	要建立索引的其他文件扩展名（例如 .tpl,.blade,.hbs）
SOCRATICODE_WATCHER	auto	auto、manual（仅显式启动）、off（不运行监视器）或 git（由 ref/HEAD 触发刷新，不使用原生监视器）
SOCRATICODE_AUTO_RESUME	—	all 恢复所有已存储的项目；off 禁用启动时补齐和中断索引恢复

如需了解每个工具的完整参数详情，请参阅 references/tool-reference.md。