内容
# 监护人
[](https://github.com/alexnodeland/curator/actions/workflows/ci.yml)
[](https://github.com/alexnodeland/curator/releases)
[](LICENSE)
> **v0.1.0** — 首个公开版本。四个合约是 v1；Rust API 是预-1.0 且仍在完善。**网站：**
> <https://alexnodeland.github.io/curator/> ·
> 路线图：[docs/design/roadmap.md](docs/design/roadmap.md)。
监护人是您的个人知识系统下的知识平面：
**任意纯 Markdown 仓库** + **一个嵌入式索引** + **MCP 代理** +
**一个确定性图书管理员**。一个二进制文件，一个 SQLite 文件 — 无守护进程，无服务，无遥测。
- **您的笔记保留为纯文件。** Markdown+YAML 目录在 git 下是整个规范存储；索引是派生且可丢弃的 — 重建，从不迁移。无需插件，无专有格式，无实时编辑器。您可以自带查看器。
- **代理是首要的读取者。** 一个 MCP 入口点为任意代理提供搜索、检索和相关性功能，涵盖整个语料库，包括引用。
- **代理提出，您决定。** 唯一的写入路径是经过验证的、人工应用的提议。表面上的任何工具都不会直接写入您的笔记。
- **图书管理员是确定性的。** 针对您当前兴趣的新内容的有序、分组摘要 — 零 LLM 需求；代理托管是一个可选的散文增强器。
> 任何将符合 markdown+frontmatter 的内容写入仓库的工具都是有效的生产者。那句话就是整个集成故事 — Curio 读取器、Zotero、网页剪辑和您自己的脚本都以相同的方式连接。
## 它做什么
| | |
|---|---|
| 🔎 **混合搜索** | sqlite-vec 向量 + FTS5 BM25 + 关系边，融合递归排名融合 — `hybrid` \| `vector` \| `fts`, 从 CLI 或 MCP |
| 🧭 **一个索引，可丢弃** | 一个嵌入式 `index.db`，具有蓝/绿纪元 — 崩溃重建从不影响服务副本；派生它，从不迁移它 |
| 🤖 **MCP 代理** | 一个入口点，六个工具 (`search` / `get_note` / `related` / `recent` / `propose` / `digest_latest`) 通过 stdio 或带有身份验证的 HTTP |
| 📰 **确定性图书管理员** | 针对您的 `now.md` 兴趣，排名分组摘要 — 零 LLM，字节相同输入相同输出 |
| ✍️ **代理提出，您决定** | 唯一的写入路径是经过验证的、人工应用的 `proposals/v1` 变更集；`.curio/` 和托管区域被严格拒绝 |
| 🖥️ **交互式 TUI** | `curator review` 打开一个标签式终端应用 — **查看** 提议（彩色差异 + 非破坏性飞行前漂移检查，应用/拒绝），**搜索** 语料库（混合，打开笔记，相关），和预览/生成图书管理员 **摘要** |
| 📚 **Zotero，双通道** | 只读增量 +全文同步到纯笔记 — 引用键命名，RFC3339 日期，DOI / 标签 / 摘要映射 |
| 📥 **生产者，不插件** | 任何写入符合 markdown 的工具都是源：Curio 读取器，浏览器网页剪辑，您的脚本 |
| 🧩 **嵌入您的选择** | 进程内 ONNX (`bge-small`, 384-dim) 或离线确定性 `hash` 嵌入器 — 一个配置开关，无模型服务器 |
| 🩺 **可操作** | `curator doctor` 健康检查 + `curator status` 快照， `--json` 在每个命令上，Docker/compose 配置文件 (`core` \| `zotero` \| `librarian`) |
| 🔒 **本地优先和私有** | 一个二进制文件，一个 SQLite 文件 — 无守护进程，无账户，无遥测；您的笔记保留为纯文件在您自己的 git 下 |
## 您的知识流动
```mermaid
flowchart LR
z["Zotero"] -->|双通道同步| v
c["Curio 读取器"] -->|curio.frontmatter.v1| v
w["网页剪辑 · 您的脚本"] -->|纯 Markdown| v
v["您的仓库<br/>Markdown + YAML"] -->|摄入| idx
subgraph curator["监护人"]
direction TB
idx["index.db<br/>向量 · FTS · 边"] --> eng["引擎"]
eng --> cli["CLI"]
eng --> mcp["MCP 表面 v1"]
end
mcp -->|搜索 · 摘要| ag["代理"]
ag -.->|提议/v1| v
cli --> you["您"]
```
## 交互式 TUI
`curator review`（无 ID，在终端中）打开一个**标签式终端应用** —
三个屏幕浏览您的仓库。`Tab` / `1` `2` `3` 切换；索引和嵌入器延迟加载，因此它立即启动。
**查看** — 代理提出，您决定：提议队列，每个变更集的彩色差异，和 **应用 / 拒绝**，带有确认。**飞行前** 横幅检查 — 非破坏性地 — 补丁是否仍能干净地应用于您当前的仓库，因此漂移在您提交前可见（失败的应用是终端拒绝）。
**搜索** — 交互式混合检索，基于 MCP 表面相同的引擎：输入查询，移动通过排名结果，打开笔记，或跳转到其嵌入式最近邻居。
**摘要** — 当前图书管理员将显示的内容的可读预览（排名候选人，得分，显示原因），和一个一键 **生成**，将当天的摘要作为提议进行审查。
`curator review <id>` 仍然打印一个可脚本化的单个提议渲染，和一个管道/非交互式 `curator review` 打印指导而不是阻塞。
完整键映射：
[CLI 参考](https://alexnodeland.github.io/curator/reference/cli.html#curator-review-apply-reject-proposals-list).
## 安装
主要安装是通过 Cargo，直接从源代码树：
```sh
git clone https://github.com/alexnodeland/curator && cd curator
cargo install --locked --path crates/curator-cli
curator --version
```
（同样，无需检查：
`cargo install --locked --git https://github.com/alexnodeland/curator curator-cli`）
其他渠道：
- **Homebrew** — 从源代码构建的公式，在运行时加载 Homebrew 的
`onnxruntime` （所以 `curator` 带有真正的语义嵌入器，不是离线备用）：
```sh
brew install alexnodeland/tap/curator
```
详情：[`dist/homebrew/README.md`](dist/homebrew/README.md)。
- **发布二进制文件** — 每个 `v*` 标签为 linux x86_64 +
macOS arm64 构建 `curator`，带有 `SHA256SUMS` 进入一个*草稿* GitHub 发布
（`.github/workflows/release.yml`）；人类审查并发布。
- **容器** — [`Dockerfile`](Dockerfile)（多阶段，精简运行时）+
[`compose.yaml`](compose.yaml) 带有配置文件 `core`（MCP over HTTP）|
`zotero`（同步循环）| `librarian`（定时摘要）。配置 + 仓库是
绑定挂载；秘密通过 env 仅进入。
- **crates.io** — 一个分阶段的后续，跟进发布中故意不发布。
## 快速开始
无模型服务器，无数据库服务，无守护进程 — 一个二进制文件，一个 SQLite
文件。尝试整个循环，首先在捆绑的示例仓库上 — 离线，确定性，非交互：
```sh
just demo # 临时目录初始化 → 摄入 → 搜索 → 摘要演练
```
**两个您需要了解的下载。** 默认构建编译进程内 ONNX 嵌入器：`cargo build`/`cargo install` 在构建时获取 ONNX Runtime
二进制文件（通过 `ort` 下载功能），第一个嵌入命令（例如默认配置 `curator init` / `curator ingest`）从 Hugging Face 获取固定的约 130 MB 嵌入模型到 `.kp/models/`（一次性，带有进度条）。对于完全离线或精简设置：在 `curator.toml` 中设置
`embedder = "hash"`（确定性，无 ML），或使用
`cargo build -p curator-cli --no-default-features` 构建 — 该二进制文件没有 ONNX
堆栈，在构建或运行时不执行任何下载。
复制 [`curator.example.toml`](curator.example.toml) 到 `curator.toml`（遗留名称 `kp.toml` 仍然被接受）并将 `[vault].path` 指向您的
Markdown 目录 — 或让 `curator init` 搭建一个。`curator --help`
列出表面：摄入，索引重建，Zotero 同步，搜索 / 获取 / 相关 /
最近，`mcp serve`，提议 / 审查 / 应用 / 拒绝（`curator review` 无
ID 打开交互式审查器），图书管理员摘要，医生和状态。（预发布：API 仍在完善 — `docs/design/` 是
设计记录。）
对于开发：`just` 列出入口（`just ci` = CI 运行的确切内容）。
## 四个合约
系统边界上的一切都是四个已发布的合约之一；其他一切都是内部的，自由变化。
| 合约 | 管辖 | 规范 |
|---|---|---|
| `kp-note/v1` | 笔记身份 + 丰富 frontmatter | [contracts/kp-note/v1.md](contracts/kp-note/v1.md) |
| `kp-config/v1` | `curator.toml` 配置（遗留名称 `kp.toml`） | [contracts/kp-config/v1.md](contracts/kp-config/v1.md) |
| `proposals/v1` | 唯一的代理写入路径 | [contracts/proposals/v1.md](contracts/proposals/v1.md) |
| MCP 表面 v1 | 代理工具表面 | [contracts/mcp/v1.md](contracts/mcp/v1.md) |
任何将符合 markdown+frontmatter 的内容写入仓库的生产者都是有效的生产者 — 那句话就是整个集成故事。 sibling Curio 读取器和 Zotero 以这种方式集成（参见
[docs/design/architecture.md](docs/design/architecture.md)）。
## 文档
文档站点 — 快速入门，概念，集成，操作和完整的配置/CLI/MCP 参考 — 从
[`docs/site/`](docs/site/) 通过存储库生成器（`just site`，实现
在 `xtask/src/docs.rs` 中）并在每次推送到 `main` 时部署到 GitHub Pages
（`.github/workflows/pages.yml`）。在 `target/site/` 使用 `just site-open` 构建它。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)， [GOVERNANCE.md](GOVERNANCE.md)， [SECURITY.md](SECURITY.md)，和
[行为准则](CODE_OF_CONDUCT.md)。
## 许可证
[MIT](LICENSE) 2026 Alex Nodeland。
