内容
# 凯恩
**一个本地优先、开源的本地文件组织工具，搭配 AI 代理使用。**
将 Claude Code、Codex、Cursor 或任何 MCP 客户端指向一个文件夹，您的代理将获得一个完整的文件组织工具集：列表、读取、搜索、grep、编辑、移动、标签、导入文档和语义检索。不需要账户，不需要云端，不需要 UI。您的文件永远不会离开您的机器。
```bash
claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/笔记
```
然后要求您的代理 *"组织此文件夹并为所有文件添加标签"* — 它将使用在您自己的文件上运行的工具完成此任务。
> 凯恩是一堆石头，标志着一条小径。这个凯恩让您的文件保持有序，并为您指引通往它们的道路。
---
## 快速入门（2 分钟）
如果您使用 **Claude Code**，设置只需要一条命令 — 唯一的先决条件是 [`uv`](https://docs.astral.sh/uv/)，它提供了 `uvx`:
```bash
# 1. 安装 uv（如果您还没有安装）（提供 uvx）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. 将 Cairn 添加到 Claude Code，指向您要组织的文件夹
claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/笔记
```
重新打开 Claude Code 并要求：
> *"组织此文件夹并为所有文件添加标签。"*
Cairn 的工具在您的文件上本地运行 — 读取操作自由执行，任何移动/重命名/编辑操作都会首先要求确认。第一次运行会自动下载软件包（~5 秒）；不需要克隆，不需要构建，不需要账户。
> [!TIP]
> 将 `--workspace` 指向您第一次运行的 **副本** — Cairn 可以移动、重命名和编辑文件。
**使用 Codex？** 相同的单命令流程（然后在会话中运行 `/mcp` 以确认）：
```bash
codex mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/笔记
```
**使用 Cursor 或另一个 MCP 客户端？** 相同的软件包，JSON 配置：
```json
{ "mcpServers": { "cairn": { "command": "uvx",
"args": ["cairn-mcp-server", "--workspace", "~/Documents/笔记"] } } }
```
`~` 由 Cairn 扩展，因此 `~/Documents/笔记` 在 CLI 和配置文件中都有效。
**只是想试用一下，不使用代理？**
```bash
uvx cairn-cli --workspace ~/Documents/笔记 tree
```
## 为什么是本地文件组织工具
代理-本地文件组织工具生态系统 converged 于一个明确的模式：模型和代理循环是由客户端（Claude Code、Codex、OpenCode）提供的商品。持久的价值在于**工具和本地数据**。因此，Cairn 提供*工具，而不是代理* — 客户端提供循环、批准提示（由我们的工具注释驱动）和聊天。Cairn 只是一个本地文件组织工具集，可以与您已经使用的任何本地文件组织工具配合使用。
## 架构
所有内容都是一个薄适配器，位于一个标准库核心之上，因此接口永远不会漂移。
```
core/ cairn-core — 引擎（仅限标准库）：.uni 文档格式、
文件操作、标签、检索；可选文档导入（docx/pdf/pptx/xlsx/md）
和基于嵌入的搜索。
mcp-server/ cairn-mcp-server — MCP 服务器：21 个工具，带有只读/破坏性注释、
资源和提示。 ← 旗舰
cli/ cairn-cli — 可脚本化的 CLI、本地 HTTP API (`serve`)，
和一个 `mcp` 启动器。
web/ cairn-web — 可选的零构建本地 Web UI
（浏览 / 编辑 / 查看 / 标签 / 搜索）。
```
## 使用它
**在 Claude Code / Codex / Cursor 中（主要）：**
```bash
claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/笔记
# 带有真实文档导入：uvx --with "cairn-core[convert]" cairn-mcp-server ...
```
服务器公开只读工具（列表、读取、搜索、grep、检索），客户端可以自由运行，还提供破坏性工具（移动、删除、编辑），客户端会先确认 — 由 MCP 工具注释驱动，因此您会在没有我们的 UI 的情况下收到批准提示。
**作为 CLI：**
```bash
uvx cairn-cli --workspace ~/Documents/笔记 tree
uvx cairn-cli --workspace ~/Documents/笔记 retrieve "预算规划"
```
**使用可选的 Web UI：**
```bash
pip install cairn-cli cairn-web
cairn --workspace ~/Documents/笔记 serve # → http://127.0.0.1:4177/
```
## `.uni` 格式
`.uni` 文件是一个小型 JSON 文档 — `{ uuid, content: "<html>", metadata, tags }` — 标签存储*在文件中*。工作区只是一个目录：完全可移植，无需外部数据库。源文档（docx/pdf/pptx/…）导入为可编辑的 `.uni` 文档；默认保留原始文档。
## 本地优先和自带密钥
- 无账户，无登录，无云同步。文件系统是事实来源。
- 默认检索器是词法检索，不需要任何东西。嵌入式检索是可选的，带自带密钥（任何 OpenAI 兼容的端点，包括 Ollama 或 LM Studio 等本地服务器）；向量存储在 `<workspace>/.cairn/` 下的本地 SQLite 索引中，永远不会离开您的机器。
## 路线图
Cairn 还很年轻。粗略的方向和最欢迎帮助的地方：
- **更多文档界面** — 更丰富的元数据支持（嵌套元数据、日期）和导入的源格式的双向编辑。
- **更智能的摘要** — 使用已配置的嵌入式模型时生成摘要，并保存视图（`.cairn/views/*.md`）。
- **更多检索后端** — 可插拔的重新排序器；一流的本地模型预设（Ollama、LM Studio）超出通用 OpenAI 兼容路径。
- **编辑器/代理集成** — 将 Cairn 连接到常见 MCP 客户端和笔记设置的薄配方。
- **打包** — 签名发布和 Homebrew 公式。
有不适合的用例吗？[打开一个问题](https://github.com/luckyjackluo/cairn/issues) 或开始一个[讨论](https://github.com/luckyjackluo/cairn/discussions)。
## 贡献
欢迎各种规模的贡献 — 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解项目布局、开发设置和如何添加工具。标有 [`good first issue`](https://github.com/luckyjackluo/cairn/labels/good%20first%20issue) 的问题是良好的起点。
## 开发
```bash
make setup # uv venv (3.11) + 所有软件包的可编辑安装 + 额外功能
make test # 运行测试套件
make serve WORKSPACE=~/Documents/笔记 # Web UI
```
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
