内容
# 遗嘱
[](https://github.com/colehellman/codicil/actions/workflows/test.yml)
[](https://pypi.org/project/codicil/)
[](LICENSE)
**适用于MCP兼容编码助手的持久、可搜索的文档。**
遗嘱索引存储库中已有的文档，并公开两个MCP工具：
`query_docs` 用于检索，`reindex_docs` 用于刷新。它使用兼容的嵌入端点，当可用时。如果端点不可用，搜索将继续使用关键字回退，读取磁盘上的当前文件。
> 状态：早期，单用户软件。核心索引和回退路径已测试，但命令行界面和存储格式可能会在稳定版本之前更改。
## 功能
- 索引 `.md`、`.mdx`、`.rst`、`.txt`、`.yaml`、`.yml` 和 `.toml` 文件。
- 在 H1 和 H2 标题处分割 Markdown；其他文件使用重叠字符块。
- 默认情况下，在 `.codicil/` 中存储本地 Chroma 索引。
- 当嵌入可用时返回语义匹配，否则返回关键字匹配。
- 使用文件修改时间增量重新索引。
诸如 `.git`、`.venv`、`node_modules`、`dist`、`build` 和 `.codicil` 等目录被排除。没有索引内容的空文件被记录并删除任何较旧的块。
## 快速开始
要求：Python 3.11+ 和类似 Unix 的主机。遗嘱使用 advisory 文件锁保护其本地存储。
```bash
python3.11 -m venv .venv
./.venv/bin/pip install -e ".[dev]"
# 可选：无需嵌入服务器，使用关键字回退。
./.venv/bin/codicil index .
./.venv/bin/codicil serve .
```
`serve` 启动 stdio MCP 服务器。如果其选定的索引为空，它将尝试自动进行初始索引。如果没有可达的嵌入端点，该初始索引将跳过语义嵌入，并且 `query_docs` 仍将直接搜索文件。
使用以下命令运行离线测试套件：
```bash
./.venv/bin/python -m pytest -q
```
## 连接 MCP 客户端
存储库包含此本地 Claude Code 配置：
```json
{
"mcpServers": {
"codicil": {
"command": ".venv/bin/codicil",
"args": ["serve", "."]
}
}
}
```
将等效配置放在要搜索的存储库中，根据需要调整 `command` 为安装的 `codicil` 可执行文件的绝对路径。传递给 `serve` 的路径是 Codicil 索引的存储库。
然后，您的客户端可以调用：
```text
query_docs(query="反向代理如何配置？", n_results=5)
reindex_docs(force=false)
```
*示例 — Claude Code 聊天界面不是终端记录可以复制的。*
*上面的 GIF 是真实的、未经编辑的输出 — 相同的 `query_docs` 函数直接在终端中调用，而不是通过 MCP。录制时没有运行本地嵌入主机，因此它通过关键字回退而不是语义搜索来回答，这是一个关于项目实际目标的现场演示。*
`n_results` 应在 1 和 10 之间。`reindex_docs()` 是刷新索引的受支持方式，而 MCP 服务器拥有存储时。
## 嵌入和回退
默认情况下，Codicil 调用 `http://localhost:11434/api/embeddings` 并带有 `nomic-embed-text` 模型。启动兼容的本地服务以启用语义搜索，然后索引存储库：
```bash
export CODICIL_EMBED_URL=http://localhost:11434
export CODICIL_EMBED_MODEL=nomic-embed-text
./.venv/bin/codicil index .
```
对于 `nomic` 模型，Codicil 自动使用推荐的文档和查询任务前缀。其他模型名称将发送不带前缀。
如果无法访问嵌入主机，或者选定的索引没有块，`query_docs` 将使用存储库上的关键字搜索。关键字结果按匹配查询词的顺序排列文件，并包含附近的行；它们很有用，但不理解同义词或语义相似性。
使用远程嵌入端点会将索引文本和搜索查询发送到该端点。请保留默认的 localhost URL 或使用您信任的端点。不要在 `.mcp.json` 中提交私有主机名或凭据。
## 配置
在服务器模块启动时读取配置，因此在运行 `codicil` 或启动 MCP 客户端之前设置环境变量。
| 变量 | 默认值 | 含义 |
| --- | --- | --- |
| `CODICIL_REPO` | `.` | 要索引的存储库。CLI 从其路径参数中设置此变量。 |
| `CODICIL_STORE` | `<repo>/.codicil` | 本地 Chroma 数据、索引状态和锁定文件。 |
| `CODICIL_EMBED_URL` | `http://localhost:11434` | 兼容 Ollama 的嵌入主机的基本 URL。 |
| `CODICIL_EMBED_MODEL` | `nomic-embed-text` | 从主机请求的嵌入模型。 |
| `CODICIL_EMBED_WORKERS` | `3` | 索引期间的并发嵌入请求。 |
| `CODICIL_MIN_SCORE` | `0.5` | `query_docs` 返回的最小语义相似性得分。 |
更改 `CODICIL_EMBED_MODEL` 会选择一个单独的集合和状态文件，避免不兼容的向量维度。在更改模型后运行 `codicil index`；现有的集合将保留在存储中，直到您故意删除存储，同时没有任何 Codicil 进程正在运行。
## 操作和限制
`codicil index [path]` 索引存储库并退出。添加 `--force` 以忽略记录的 mtime 并重新嵌入每个可索引文件。`codicil serve [path]` 运行 MCP 服务器。
同一时间只有一个 Codicil 进程可以使用存储。启动 `codicil index` 时，`codicil serve` 拥有相同的存储会故意失败。使用 `reindex_docs` 从正在运行的 MCP 服务器，或在运行 CLI 索引器之前停止服务器。
Codicil 目前设计用于单个本地存储库和单个用户。它不提供文件监视、git 钩子、多用户访问或跨存储库检索。
## 故障排除
- **“存储已被占用”**：另一个 Codicil 进程拥有 `CODICIL_STORE`。停止它，或通过正在运行的 MCP 服务器调用 `reindex_docs`。
- **关键字结果而不是分数**：嵌入端点不可用或选定的模型尚未索引。检查 `CODICIL_EMBED_URL`，然后运行 `codicil index`。
- **没有匹配的文件**：确认文件扩展名受支持且不在排除的目录中。仅包含两个或更少字符的单词的查询没有回退搜索词。
- **需要干净的重建**：停止每个 Codicil 进程，然后删除本地存储并运行 `codicil index`。这将永久删除该存储的所有本地集合。
有关开发详细信息和可靠性不变性，请参阅 [CLAUDE.md](CLAUDE.md)。有关更详细的安装指南，请参阅 [docs/SETUP.md](docs/SETUP.md)。
## 许可证
在 [MIT 许可证](LICENSE) 下发布。
