内容
# 格子
[](https://github.com/anrasch/lattice/actions/workflows/ci.yml)
[](https://github.com/anrasch/lattice/releases)
[](./LICENSE)
本地优先的 Markdown 知识库，优化用于 AI 协作。通过 MCP 查询笔记，编辑它们时使用原生 Rust 和 Tauri 应用。
格子将一个目录的纯 `.md` 文件视为知识图谱。人类通过原生应用阅读和编辑；AI 代理（Claude 和其他 MCP 客户端）通过查询而不是 `grep` 来导航同一个知识库。Markdown 文件保持为真实来源；图谱是一个派生的、可重建的索引。
## 状态
**v0.3.0** — 可作为单用户、本地工具日常使用（macOS 应用 + 跨平台引擎/CLI/MCP）。读取和结构化写入工具稳定且已投入使用，桌面应用是实时视图，反映外部更改，并允许代理在其中打开笔记。参见 [更新日志](CHANGELOG.md) 和 [发布版本](https://github.com/anrasch/lattice/releases)。
## 为什么
Obsidian 的图谱和反向链接是为人类点击设计的，而不是为代理设计的。格子将相同的图谱公开为机器面向的查询 API（反向链接、前端过滤器、孤立节点、损坏链接和 token 预算的上下文包），并附带其自己的原生读取和编辑界面，因此它不依赖于第三方应用。
## 架构
一个 Rust `core` crate，三个界面：
- **MCP 服务器** (`rmcp`, stdio) — 主要的 AI 界面。代理调用类型化工具。
- **CLI** (`clap`) — 用于脚本和人类的相同查询。
- **原生应用** (Tauri + Svelte) — 读取、编辑和实时协作视图。
知识库的 `.md` 文件是真实来源。从它们派生出 SQLite (`rusqlite`, FTS5) 索引，并通过文件监视器 (`notify`) 保持同步。
## 原语
- **忽略层** — `.aiignore`（gitignore 语法）将系统文件和生成的文件排除在图谱之外。
- **节点** — 每个 `.md` 文件都是一个节点；目录的 `README.md` 是一个 `index` 节点（其入口点）。
- **边** — `[[wikilinks]]` 和 Markdown 链接、前置引用和目录包含，所有这些都可查询。
- **前置元数据** — YAML 前置元数据是类型化、可查询的结构化数据。
## 布局
```
crates/core 引擎库（解析、索引、查询、编辑）
crates/mcp rmcp 服务器二进制文件
crates/cli clap 二进制文件
app/ Tauri 应用（Rust 后端 + Svelte 网页视图）
fixtures/ 用于测试的综合知识库
```
## 用法
构建工作区：
```bash
cargo build --release
```
### CLI
在 shell 中对知识库运行任何查询（JSON 输出）：
```bash
lattice --root /path/to/vault backlinks docs/guide.md
lattice --root /path/to/vault query type=spec status=active
lattice --root /path/to/vault broken-links
lattice --root /path/to/vault context docs/guide.md --budget 8000
```
### 作为 MCP 服务器
`lattice-mcp` 通过 stdio 使用模型上下文协议。指向它到知识库
使用 `LATTICE_ROOT` 并在任何 MCP 客户端注册它。对于 Claude Code，请添加到
`.mcp.json`:
```json
{
"mcpServers": {
"lattice": {
"command": "/path/to/lattice/target/release/lattice-mcp",
"env": { "LATTICE_ROOT": "/path/to/vault", "LATTICE_DB": "/tmp/lattice.db" }
}
}
}
```
**读取工具：** `vault_backlinks`、`vault_links`、`vault_query`、`vault_search`、
`vault_orphans`、`vault_broken_links`、`vault_index`、`vault_dirs`、`vault_keys`、
`vault_changed_since`、`vault_superseded`、`vault_context_bundle`.
**写入工具（仅结构）：** `vault_rename`（移动笔记 + 修复每个传入链接）和 `vault_patch_frontmatter`（设置/添加/取消键，手术 YAML）。
两者默认为**干运行** — 它们返回差异计划；传递 `apply: true` 以
写入。格子只会编辑工作树文件；它永远不会暂存或提交到
git，并且永远不会写入正文（使用您的编辑器进行此操作）。
**协作：** `vault_open` 在运行的桌面应用中打开并聚焦一个笔记，因此
代理和人类查看相同的文档（共 15 个工具）。
```bash
# 预览重命名（无写入）；添加 --apply 以执行
lattice --root /path/to/vault rename docs/old.md docs/new.md
lattice --root /path/to/vault patch docs/spec.md --set status=shipped --apply
```
### 使您的代理实际使用它
注册服务器使工具*可用*，但代理默认使用
`grep`/读取。出于习惯，在您的项目代理指令中添加一个指令
（`CLAUDE.md`、`AGENTS.md` 或等效），以便它默认使用格子。
您可以粘贴和修剪以下内容作为起点：
```markdown
## 知识库 — 使用格子，而不是 grep
此仓库由 `lattice` MCP 服务器索引（`vault_*` 工具）。优先使用它们
而不是原始 grep/读取 — 它们返回结构和关系，而不是文件转储：
- “X 在哪里有文档/什么链接到这里？”→ `vault_search`、`vault_backlinks`，
然后 `vault_context_bundle` 以加载 token 预算的包之前执行任务。
- 形状和发现 → `vault_dirs`、`vault_index`、`vault_keys` → `vault_query`。
- 清洁度 → `vault_broken_links`、`vault_orphans`、`vault_changed_since`、
`vault_superseded`（不要引用已逆转的决定）。
- 结构编辑 → `vault_rename`（移动笔记 + 修复每个反向链接）和
`vault_patch_frontmatter`（设置/添加/取消键）。两者默认为干运行：
预览差异，然后重新调用 `apply:true`。它们永远不会触及 git。
- 协作 → `vault_open` 以在我的格子窗口中显示正在讨论的笔记，
以便我们查看相同的文档。
格子只看到索引的知识库，并且只编辑结构（位置/
前置元数据/链接）；正文内容保留在您的普通编辑工具中。
```
## 桌面应用
用于人类侧的原生、签名 + notarized macOS 应用（Tauri + Svelte）。从 [发布版本](https://github.com/anrasch/lattice/releases)
下载最新的 `.dmg` 并双击 — 带有文件夹选择器的欢迎屏幕打开（最近的知识库被记住），因此不需要 `LATTICE_ROOT`。
- **三面板工作区** — 带有孤立节点/损坏链接/搜索的侧边栏的嵌套文件树，
渲染的笔记带有（可折叠的）反向链接/链接面板和 CodeMirror 编辑器，
该编辑器写入时带有哈希不匹配保护。浅色和深色主题（在功能区切换）。
- **实时** — 文件监视器实时反映外部更改（git、另一个编辑器、MCP/CLI）：
树、打开的笔记和连接在无需重新加载的情况下刷新，并且正在进行的编辑
被防止覆盖（⌘R 强制重新同步）。
- **预览标签** — 单击预览一个笔记在一个重用的标签中；双击
或编辑固定它，因此浏览树不会堆积标签。
- **代理定向打开** — 当代理调用 `vault_open`（或您运行
`lattice open <note>`），应用提高并聚焦该笔记，因此您和代理
查看相同的文档。
您可以自己构建：
```bash
# 开发，针对任意知识库
cd app && LATTICE_ROOT=/path/to/vault npm run tauri dev
# 发布包 -> app/src-tauri/target/release/bundle/{macos/Lattice.app, dmg/*.dmg}
cd app && npm run tauri build
```
## 许可证
Apache-2.0。参见 [LICENSE](./LICENSE)。
