用途
Alcove 解决 AI 编程智能体不了解项目背景的问题。智能体每次会话都从零开始，不知道架构、忽略既有决策约束、反复要求解释同样内容。把所有文档塞进智能体配置会造成上下文膨胀（10 份文档可能浪费 50K 以上 token），复制粘贴无法跨会话扩展，放任不管则导致智能体凭空发明需求。Alcove 让智能体在需要时主动搜索所需文档，而不是注入文档。
主要能力
- 按需检索：智能体按需搜索项目文档，不把文档加载进上下文，节省 token 与注意力。
- 混合搜索：BM25（由 tantivy 提供）与向量相似度搜索（由 fastembed 提供）结合，支持 CLI 搜索与基于智能体的工具。默认模型 ArcticEmbedXS（90 MB，多语言）。
- 代码索引：用 tree-sitter 解析源代码，生成模块级 Markdown 摘要 CODE_INDEX.md，并接入 Tantivy 搜索流水线。官方二进制启用全部 12 种解析器（lang-all 特性）。
- 多项目与全局搜索：默认按终端工作目录检测当前项目，也可用 MCP_PROJECT_NAME 覆盖；支持跨所有项目的全局搜索（scope: "global"）。
- 文档策略：通过 policy.toml 定义团队文档标准，优先级为项目 > 团队 > 内置默认。
- 文档校验与生成：lint 检查四项内容；文档分类为不同层级；audit 工具扫描文档仓库与本地项目目录并给出建议。
- 知识库 Vault：独立于项目文档的知识库，用于研究笔记、参考资料等，拥有独立索引、缓存与搜索，互不影响。
- 搜索质量度量：内置 IR 指标与回归检测，支持隔离语料模式（19 篇合成文档、25 条查询，60 秒内完成）用于 CI 基准测试。回归阈值为精度 >5%、延迟 >20%、吞吐 >15%，达到阈值一半时告警。
- 后台服务：持久后台服务消除每次会话冷启动延迟；stdio 进程作为轻量代理转发请求至热服务。
使用方式
安装后必须运行一次 alcove setup 配置文档根目录并启用完整功能；插件会自动启动 API 服务器，但未运行 setup 前无法搜索或索引文档。
安装渠道：Claude 插件、Codex 插件、Antigravity（Gemini CLI）、Grok Build（仅 macOS Apple Silicon）。
macOS 无 Homebrew 时使用安装脚本；Windows 目前未发布预构建二进制，需从源码构建；也可通过 Rust 工具链 cargo install。注意：cargo binstall 下载的预构建二进制含混合搜索；从源码构建需 --features full-macos 或 --features full-cross 才支持混合搜索，否则只有 BM25 关键词搜索。
setup 交互式引导内容：文档存放位置、跟踪的文档类别、偏好图表格式、混合搜索的嵌入模型、后台服务、要配置的 AI 智能体。可随时重新运行 setup，会记住此前选择。
CLI 常用命令：alcove search、项目切换、--scope global、alcove validate、alcove index、alcove rebuild、alcove doctor、alcove token、alcove api env。
智能体通过本地 HTTP API 使用 Alcove（端口 58301）。示例：智能体调用 POST /v1/search，再通过 GET /docs/{path}?project=... 读取最相关文档。MCP 仍可用，手动 stdio 设置见 registry/mcp.json。
适用场景
- 多项目、多智能体环境下保持统一文档层。
- 需要私密文档不进入公开仓库的团队。
- 多语言项目的语义检索（默认模型支持多语言）。
- 单体仓库（monorepo）的代码索引。
- 与 Obsidian 配合：搭配 obsidian-forge 生成器，将 docs_root 指向 obsidian-forge 项目归档，另三类知识区域作为独立 vault 链接。
限制与已知问题
- 必须先运行一次
alcove setup，否则无法搜索或索引。 - Windows 预构建二进制暂未发布，需自行构建。
- 从源码构建若不带 full 特性，仅支持 BM25 关键词搜索，无向量混合搜索。
- 无 pdftotext 时回退到内置 PDF 解析器，可能对部分文件失败。
- 首次索引或完整重建时内存峰值随语料规模增长，加载嵌入模型约 235–500 MB，大模型（如 BGEM3、ArcticEmbedMLong）重建时可达 1.5–2 GB；完成后稳态约 50–200 MB。
- 后台服务出现 403 需设置 ALCOVE_TOKEN。
- 搜索无结果可能是索引未建立，需先运行
alcove index。
补充说明
Alcove 不替代 CLAUDE.md / AGENTS.md：后者定义行为规则（提交风格、语言偏好、安全约束），Alcove 管理机构知识（架构决策、进度跟踪、编码规范、代码结构）。相比直接用 ripgrep 作为 MCP 工具，Alcove 对文档分块、排序，仅返回最相关段落，并提供 ripgrep 不具备的向量语义搜索。支持的语言与智能体列表、配置项详见官方仓库。
