Alcove 是一个 MCP 服务器，它让 AI 编码代理能够按需访问你的私有项目文档——无需将所有内容塞入上下文窗口，不会将文档泄露到公共仓库，也不需要为每个使用的代理进行单独的项目配置。

演示

Alcove 代理演示

Claude、Gemini、Codex — 搜索 · 切换项目 · 全局搜索 · 验证与生成。只需一次设置。

Alcove CLI 演示

alcove search · 项目切换 · --scope global · alcove validate

问题所在

你有两个糟糕的选择。

选项 A：将文档放入 CLAUDE.md / AGENTS.md 每个文件在每次运行时都会被注入到上下文窗口中。对于简短的约定有效。但面对真实的项目文档时就会崩溃。 10 个架构文件 = 上下文臃肿 = 响应变慢、成本更高、准确性降低。

选项 B：不放入文档 你的代理会凭空捏造你已经记录过的需求。它会忽略你已经做出的决策所带来的约束。它会要求你在每次会话中解释相同的事情。

这两种选择都无法扩展。现在将其乘以 5 个项目和 3 个代理，每个代理的配置方式都不同。每次切换时，你都会丢失上下文。

Alcove 如何解决这个问题

Alcove 不会注入你的文档。代理在需要时搜索它们所需的内容。

~/projects/my-app $ claude "how is auth implemented?"

  → Alcove detects project: my-app
  → BM25 search: "auth" → ARCHITECTURE.md (score: 0.94), DECISIONS.md (score: 0.71)
  → Agent gets the 2 most relevant docs, not all 12

~/projects/my-api $ codex "review the API design"

  → Alcove detects project: my-api
  → Same doc structure, same access pattern
  → Different project, zero reconfiguration

随时切换代理。随时切换项目。文档层保持标准化。

正确的拆分

CLAUDE.md / AGENTS.md 用于代理行为：要避免的重复错误、编码约定和特定于会话的指令。保持在 200 行以内。

Alcove 用于项目知识：架构、决策、运行手册、API 文档以及你的代理需要理解的其他任何内容——但不一定在每次运行时都需要。

模式：

CLAUDE.md | AGENTS.md                             ← agent rules, coding conventions, recurring corrections
~/.config/alcove/docs/my-app/
  ARCHITECTURE.md                      ← tech stack, data model, system design
  DECISIONS.md                         ← why X was chosen over Y
  DEBT.md                              ← known issues, workarounds
  ...                                  ← agent searches here when it needs context

代理调用 search_project_docs("auth flow") 并获取 2 个最相关的文档——而不是全部 12 个。除非确实需要，否则没有任何内容会进入上下文窗口。

为什么选择 Alcove

为什么不直接使用 CLAUDE.md？简短的约定和代理行为适合放在那里。项目文档——架构、决策、运行手册、PRD——在上下文文件中无法扩展。Alcove 不是替代品；它是 CLAUDE.md 本不该承担的那一层。

没有 Alcove	使用 Alcove
文档在 `CLAUDE.md` 中，每次运行都会导致上下文臃肿	BM25 搜索 — 代理仅提取所需内容
内部文档分散在 Notion、Google Docs、本地文件中	一个文档仓库，按项目结构化
每个 AI 代理单独配置文档访问权限	一次设置，所有代理共享相同访问权限
切换项目意味着重新解释上下文	CWD 自动检测，即时项目切换
代理搜索返回随机匹配行	排序结果 — 最匹配的在前，每个文件一个结果
“搜索我关于 OAuth 的所有笔记” — 不可能	一次查询即可跨所有项目进行全局搜索
敏感文档存放在项目仓库中	私有文档在你的机器上，绝不会进入公共仓库
文档结构因项目和团队成员而异	`policy.toml` 在所有项目中强制执行标准
无法检查文档是否完整	`validate` 捕获缺失文件、空模板、缺失章节

快速入门

# macOS
brew install epicsagas/alcove/alcove

# Linux / Windows — pre-built binary (fast, no compilation)
cargo install cargo-binstall
cargo binstall alcove

# Any platform — build from source
cargo install alcove

# Clone and build
git clone https://github.com/epicsagas/alcove.git
cd alcove
make install

alcove setup

注意：提供适用于 Linux (x86_64)、macOS (Apple Silicon & Intel) 和 Windows 的预构建二进制文件。

setup 会以交互方式引导你完成所有操作：

文档存放位置
要跟踪的文档类别
首选图表格式
要配置的 AI 代理（MCP + 技能文件）

随时重新运行 alcove setup 以更改设置。它会记住你之前的选择。

工作原理

flowchart LR
    subgraph Projects["Your projects"]
        A1["my-app/\n  src/ ..."]
        A2["my-api/\n  src/ ..."]
    end

    subgraph Docs["Your private docs (one repo)"]
        D1["my-app/\n  PRD.md\n  ARCH.md"]
        D2["my-api/\n  PRD.md\n  ..."]
        P1["policy.toml"]
    end

    subgraph Agents["Any MCP agent"]
        AG["Claude Code · Cursor\nGemini CLI · Codex · Copilot\n+4 more"]
    end

    subgraph MCP["Alcove MCP server"]
        T["search · get_file\noverview · audit\ninit · validate"]
    end

    A1 -- "CWD detected" --> D1
    A2 -- "CWD detected" --> D2
    Agents -- "stdio MCP" --> MCP
    MCP -- "scoped access" --> Docs

你的文档组织在一个单独的目录 (DOCS_ROOT) 中，每个项目一个文件夹。Alcove 在那里管理文档，并通过 stdio 将它们提供给任何兼容 MCP 的 AI 代理。你的代理调用诸如 search_project_docs("auth flow") 之类的工具，并获得排序后的、特定于项目的结果——无论你使用的是哪个代理。

功能特性

按需文档检索 — 代理搜索并检索；没有任何内容预加载到上下文中
BM25 排序搜索 — 由 tantivy 提供支持的快速全文搜索；最相关的文档优先，自动索引，回退到 grep
一个文档仓库，多个项目 — 私有文档按项目组织，集中管理
一次设置，任何代理 — 配置一次，每个兼容 MCP 的代理都能获得相同的访问权限
从 CWD 自动检测你的项目 — 无需每个项目进行配置
作用域访问 — 每个项目只能看到自己的文档
跨项目搜索 — 使用 scope: "global" 一次搜索所有项目
私有文档保持私有 — 文档绝不触碰你的公共仓库，完全在你的机器上通过 stdio 运行
标准化文档结构 — policy.toml 在所有项目和团队中强制执行一致的文档
跨仓库审计 — 查找存放在项目仓库中的内部文档，建议修复方案
文档验证 — 检查缺失文件、未填写的模板、必需的章节
支持 9+ 种代理 — Claude Code, Cursor, Claude Desktop, Cline, OpenCode, Codex, Copilot, Antigravity, Gemini CLI

MCP 工具

工具	功能
`get_project_docs_overview`	列出所有带有分类和大小的文档
`search_project_docs`	智能搜索 — 自动选择 BM25 排序或 grep，支持 `scope: "global"` 进行跨项目搜索
`get_doc_file`	按路径读取特定文档（支持大文件的 `offset`/`limit`）
`list_projects`	显示文档仓库中的所有项目
`audit_project`	跨仓库审计 — 扫描文档仓库和本地项目仓库，建议操作
`init_project`	为新项目搭建文档框架（内部 + 外部文档，选择性文件创建）
`validate_docs`	根据团队策略 (`policy.toml`) 验证文档
`rebuild_index`	重建全文搜索索引（通常是自动的）
`check_doc_changes`	检测自上次索引构建以来添加、修改或删除的文档

CLI

alcove              Start MCP server (agents call this)
alcove setup        Interactive setup — re-run anytime to reconfigure
alcove doctor       Check the health of your alcove installation
alcove validate     Validate docs against policy (--format json, --exit-code)
alcove index        Build or rebuild the full-text search index for ranked search
alcove search       Search docs from the terminal
alcove uninstall    Remove skills, config, and legacy files

搜索

Alcove 会自动选择最佳搜索策略。当搜索索引存在时，它使用 BM25 排序搜索（由 tantivy 提供支持）以获得相关性评分结果。当索引不存在时，它会回退到 grep。你无需考虑这些。

# Search the current project (auto-detected from CWD)
alcove search "authentication flow"

# Force grep mode if you want exact substring matching
alcove search "FR-023" --mode grep

当 MCP 服务器启动时，索引会在后台自动构建，并在检测到文件更改时重建。无需 cron 作业，无需手动步骤。

对代理的工作方式： 代理只需使用查询调用 search_project_docs。Alcove 处理其余部分——排序、去重（每个文件一个结果）、跨项目搜索和回退。代理无需选择搜索模式。

全局搜索

每一个架构决策、每一个运行手册、每一个项目笔记——都可以在所有项目中同时搜索。

# Search across ALL projects
alcove search "rate limiting patterns" --scope global
alcove search "OAuth token refresh" --scope global

代理可以在 search_project_docs 中使用 scope: "global" 执行相同的操作。一次查询，所有项目。

项目检测

默认情况下，Alcove 从你终端的工作目录 (CWD) 检测当前项目。你可以使用 MCP_PROJECT_NAME 环境变量覆盖此设置：

MCP_PROJECT_NAME=my-api alcove

当你的 CWD 与文档仓库中的项目名称不匹配时，这非常有用。

文档策略

在文档仓库中使用 policy.toml 定义全团队的文档标准：

[policy]
enforce = "strict"    # strict | warn

[[policy.required]]
name = "PRD.md"
aliases = ["prd.md", "product-requirements.md"]

[[policy.required]]
name = "ARCHITECTURE.md"

  [[policy.required.sections]]
  heading = "## Overview"
  required = true

  [[policy.required.sections]]
  heading = "## Components"
  required = true
  min_items = 2

策略文件的解析优先级为：项目 (<project>/.alcove/policy.toml) > 团队 (DOCS_ROOT/.alcove/policy.toml) > 内置默认值（来自你的 config.toml 核心文件）。这确保了所有项目文档质量的一致性，同时允许针对特定项目进行覆盖。

文档分类

Alcove 将文档分为几个层级：

分类	存放位置	示例
doc-repo-required	Alcove (私有)	PRD, 架构, 决策, 约定
doc-repo-supplementary	Alcove (私有)	部署, 入职, 测试, 运行手册
reference	Alcove `reports/` 文件夹	审计报告, 基准测试, 分析
project-repo	你的 GitHub 仓库 (公开)	README, CHANGELOG, CONTRIBUTING

audit 工具会扫描你的文档仓库和本地项目目录，然后建议操作——例如从你的私有 PRD 生成公共 README，或将放错位置的报告拉回 Alcove。

配置

配置位于 ~/.config/alcove/config.toml：

docs_root = "/Users/you/documents"

[core]
files = ["PRD.md", "ARCHITECTURE.md", "PROGRESS.md", "DECISIONS.md", "CONVENTIONS.md", "SECRETS_MAP.md", "DEBT.md"]

[team]
files = ["ENV_SETUP.md", "ONBOARDING.md", "DEPLOYMENT.md", "TESTING.md", ...]

[public]
files = ["README.md", "CHANGELOG.md", "CONTRIBUTING.md", "SECURITY.md", ...]

[diagram]
format = "mermaid"

所有这些都是通过 alcove setup 交互式设置的。你也可以直接编辑该文件。

文件列表是完全可定制的——将任何文件名添加到任何类别，或在类别之间移动文件以匹配你团队的工作流程：

[core]
files = ["PRD.md", "ARCHITECTURE.md", "DECISIONS.md", "MY_SPEC.md"]  # added custom doc

[public]
files = ["README.md", "CHANGELOG.md", "PRD.md"]  # PRD exposed as public for this project

支持的代理

代理	MCP	技能
Claude Code	`~/.claude.json`	`~/.claude/skills/alcove/`
Cursor	`~/.cursor/mcp.json`	`~/.cursor/skills/alcove/`
Claude Desktop	平台配置	—
Cline (VS Code)	VS Code globalStorage	`~/.cline/skills/alcove/`
OpenCode	`~/.config/opencode/opencode.json`	`~/.opencode/skills/alcove/`
Codex CLI	`~/.codex/config.toml`	`~/.codex/skills/alcove/`
Copilot CLI	`~/.copilot/mcp-config.json`	`~/.copilot/skills/alcove/`
Antigravity	`~/.gemini/antigravity/mcp_config.json`	—
Gemini CLI	`~/.gemini/settings.json`	`~/.gemini/skills/alcove/`

支持技能的代理会在你询问项目架构、约定、决策或状态时自动激活 Alcove。它们也可以被显式调用：

/alcove                          Summarize current project docs and status
/alcove search auth flow         Search docs for a specific topic
/alcove what conventions apply?  Ask a doc question directly

支持的语言

CLI 会自动检测你的系统区域设置。你也可以使用 ALCOVE_LANG 环境变量覆盖它。

语言	代码
English	`en`
한국어	`ko`
简体中文	`zh-CN`
日本語	`ja`
Español	`es`
हिन्दी	`hi`
Português (Brasil)	`pt-BR`
Deutsch	`de`
Français	`fr`
Русский	`ru`

# Override language
ALCOVE_LANG=ko alcove setup

更新

# Homebrew
brew upgrade epicsagas/alcove/alcove

# cargo-binstall
cargo binstall alcove

# From source
cargo install alcove

卸载

alcove uninstall          # remove skills & config
cargo uninstall alcove    # remove binary

生态系统

obsidian-forge

Alcove 与 obsidian-forge（一个 Obsidian 知识库生成器和自动化守护进程）完美搭配。使用 obsidian-forge 构建和加强你在 Obsidian 中的知识图谱，然后将 alcove 的 DOCS_ROOT 指向该知识库——你的 AI 代理即可在你的整个个人知识库中进行排序、有作用域的搜索，而不会出现任何上下文臃肿。

贡献

欢迎提交错误报告、功能请求和拉取请求。请在 GitHub 上开启一个 issue 以开始讨论。

许可证

Apache-2.0

Alcove

演示