Seekstone Obsidian Mcp Server

无需插件、无需运行 Obsidian 应用的 Obsidian MCP 服务——而且不会撑爆你的上下文窗口。

直接访问文件系统 · 关键词搜索耗时个位数毫秒 · 语义搜索约 26 ms · 负载约 2 KB · 25 个工具 · macOS · Linux · Windows

seekstone.dev →

---

	Seekstone	obsidian-mcp-server（下载量排名第 1）	REST 代理服务
本地 REST API 插件	不需要	需要	需要
Obsidian 应用运行	不需要——Obsidian 关闭时也能工作	需要	需要
10k 条笔记时的搜索负载	2.0 KB	47 KB	最高 95 MB
10k 条笔记时的热搜索延迟	5.6 ms	732 ms（慢约 131 倍）	最高 1,550 ms
结构化 frontmatter 查询	内置（query_notes）——属性／日期／大小谓词，答案仅需几百字节	通过 REST 使用 JSONLogic	因情况而异
相同查询、相同的已提交知识库、各运行 20 次、同一台机器。进程内适配器于 2026 年 9 月在 fixture-v2 知识库上重新运行；REST 代理行（rest、obsidian-mcp-server、mcp-obsidian）以及 obsidian-mcp 和 obsidian-mcp-pro 是 2026 年 6 月在 fixture v1 上采集的数据——每行数据的来源记录在 benchmarks.json 中；该文件是生成的事实来源，CI 会据此核验此处的每个数字——下方查看八个服务、三种知识库大小的完整结果，所有结果均可通过测试工具完整复现。

---

---

什么是 Seekstone？

Seekstone 是一款 Obsidian MCP 服务——它让 Claude（以及任何 Model Context Protocol 客户端）能够直接读取和写入你的 Obsidian 知识库。无需打开 Obsidian 应用，无需安装插件，也不会有任何数据离开你的机器。

它直接从磁盘读取知识库，而不是通过 Obsidian Local REST API 插件中转，并在进程内维护一个热的全文索引。实际区别主要有两点：

• 速度。 热缓存下，关键词搜索只需个位数毫秒，语义搜索约需 26 毫秒——比我们测试过的所有其他 Obsidian MCP 服务快最多 约 508 倍，因为无需启动子进程，也无需为每次查询进行 HTTP 往返。
• 上下文。 REST 代理服务通过一次宽泛搜索返回数千万字节和数百万个 token，而 Seekstone 只返回约 2 KB——最多可减少约 47,000 倍，且知识库越大，差距越明显。

搜索有三种模式：排序后的全文搜索（模糊匹配和前缀匹配）、可选的本地语义搜索（基于含义，通过小型本地嵌入模型实现——需选择启用；一次性下载约 30 MB 模型后，运行时可离线使用），以及结构化元数据查询——query_notes 可按 frontmatter 属性（status、due、type 等）、标签、文件夹、修改时间和大小进行筛选，让你用几百字节就能回答“哪些草稿笔记在本周有更改？”之类的问题，无需反复搜索和读取。

Claude 可以在毫秒内搜索和读取整个笔记库，无需在一次工具调用中耗费大部分上下文窗口。

此项目已发布到 npm，名称为 seekstone——使用 npx -y seekstone 安装。（此前也曾以 obsidian-mcp-seekstone 发布；该别名已弃用，但现有安装仍可正常使用。）

---

为什么选择 Seekstone？看数据。

大多数 Obsidian MCP 服务会为每个搜索结果返回完整笔记内容。宽泛查询会产生数百万字节的文本，供大模型处理——其中大部分都无关紧要，却全都要占用上下文窗口。

Seekstone 返回的是简短的排序摘录（默认约 120 个字符，可按查询调整）。我们将 Seekstone 与另外 7 个 Obsidian MCP 服务进行了基准测试——总计 8 个服务——覆盖三种知识库大小：1,000 / 5,000 / 10,000 条笔记（各运行 20 次）。以下所有数字都可以完整复现：知识库已提交到此仓库（由公共领域的 1911 年《大英百科全书》生成），你可以克隆仓库并运行完全相同的基准测试。

测试三种大小的意义在于，不同架构的差异会在这里显现——真实知识库只会不断增长。

搜索载荷——每次查询返回的字节数（上下文开销；越低越好）

服务	架构	1k 条笔记	5k 条笔记	10k 条笔记
🥇 Seekstone	进程内索引	1.6 KB	1.8 KB	2.0 KB
mcpvault	直接访问文件系统的子进程	1.7 KB	1.9 KB	2.2 KB
obsidian-mcp-rs	直接访问文件系统，每次查询扫描	5.4 KB	5.8 KB	6.2 KB
obsidian-tc	SQLite 平台	4.6 KB	6.8 KB	7.3 KB
obsidian-mcp-server	REST API	55 KB	47 KB	47 KB
obsidian-mcp-pro	直接访问文件系统的子进程	25 KB	84 KB	114 KB
obsidian-mcp	直接访问文件系统的子进程	18 KB	105 KB	203 KB
mcp-obsidian	REST API	9.8 MB	45 MB	95 MB

无论知识库有多大，Seekstone 的负载都保持稳定在约 2 KB，因为它始终返回排序后的摘录；如今，它也是测试过的所有服务中负载最小的，在三种规模下都略胜 mcpvault。REST 代理服务会返回每个匹配项的完整笔记内容，因此负载会随知识库增大——mcp-obsidian 在 10k 条笔记时达到 95 MB，而单次宽泛查询（the capital of）在 20 次运行中平均每次调用产生 370.9 MB / 9,780 万个 token。在 10k 条笔记时，二者的上下文开销相差约 47,000 倍。

搜索延迟——预热后的平均值，毫秒（越低越好）

服务	1k 条笔记	5k 条笔记	10k 条笔记	相较于 Seekstone（10k 条）
🥇 Seekstone	1.0	2.8	5.6	—
obsidian-mcp-rs	6.0	19	36	慢约 6 倍
obsidian-mcp-pro	41	200	407	慢约 73 倍
obsidian-mcp-server	82	356	732	慢约 131 倍
obsidian-mcp	78	380	772	慢约 138 倍
mcpvault	90	431	893	慢约 159 倍
mcp-obsidian	164	740	1,550	慢约 277 倍
obsidian-tc	273	1,380	2,849	慢约 508 倍

每个竞品都会为每次查询启动子进程或进行 HTTP 往返，而且大多数服务的工作量会随知识库规模增长。Seekstone 将预热后的索引保留在进程内——无需 IPC，也无需网络——因此即使有 10,000 条笔记，关键词搜索仍能保持在个位数毫秒（随附的语义处理流水线——嵌入、扫描、MaxSim 重排——耗时约 26 毫秒）。而且，规模越大，差距就越明显：笔记数从 1k 增至 10k，竞品会慢 5–10 倍，而 Seekstone 几乎没有变化。即使是最快的替代方案 obsidian-mcp-rs——每次查询都会重新扫描知识库——在 10k 条笔记、预热状态下也慢约 6 倍，且负载是其 3 倍；REST 代理这一代服务则慢约 100–280 倍。

工具列表——首次调用前加载的 token 数（越低越好）

会话启动时，大多数 MCP 客户端会在调用任何工具之前，将服务的工具列表（每个工具的名称、说明和输入架构）加载到模型的上下文中。有些客户端（例如启用了工具搜索的 Claude Code）只会先加载名称，等到需要某个工具时再加载其详细信息。若完整加载，Seekstone 的 25 个工具会占用约 5,742 个 token（26 KB）。设置 SEEKSTONE_READ_ONLY=1 后，列表中会移除 11 个写入工具，token 数降至约 3,261 个，减少 43%。测试框架通过 MCP 测量已构建的服务（npm run harness -- schema-tax），CI 会在每次提交时重新测量，因此任何工具说明或架构的变更都会导致构建失败，直至更新已发布的数据。

在我们的基准测试中，Seekstone 是唯一一款在所有知识库规模下都同时实现约 2 KB 负载和个位数毫秒关键词延迟的服务；据我们所知，它也是唯一一款发布了可复现基准测试数据的 Obsidian MCP 服务。测试框架、合成知识库和完整结果均已开源：请参阅 benchmark-scaling.md 和测试框架。克隆、运行、验证。

---

安装

选择最适合你的方式。

正在使用 AI Agent？粘贴此提示词

如果你使用 Claude Code、Cursor 或其他编码 Agent，无需亲自遵循任何说明——粘贴此提示词，让 Agent 完成安装：

为此编辑器安装 seekstone MCP 服务。运行 npx -y seekstone init --client code --write（其他客户端请使用 desktop、cursor 或 vscode）。该命令会自动检测我的 Obsidian 库；如果列出多个库，请询问我选择哪一个，然后使用 --vault "<path>" 重新运行。将任何错误转告我，然后提醒我重启此会话，以便加载 seekstone 工具。

seekstone init 完全无需交互——使用 --write 后，它会一次性验证库并修改客户端配置（Claude Code 通过 claude mcp add，其他客户端则通过附带时间戳备份的增量 JSON 补丁）。

选项 1 — 一键安装（Claude Desktop，无需使用终端）

1. 下载 seekstone.mcpb（直接链接，始终指向最新版本）
2. 使用 Claude Desktop 打开该文件——在 Finder 中双击，或右键点击 →“打开方式”→ Claude Desktop
3. 根据提示选择你的 Obsidian 库文件夹

当 seekstone 出现在 Claude 的工具栏中时，就表示安装成功。无需编辑 JSON、使用终端或安装 Node.js。

想要语义搜索？改为下载 seekstone-semantic.mcpb——它是同一 MCP 服务，已在安装包中附带本地嵌入模型（体积约大 28 MB），因此开箱即用地支持基于含义的搜索：仍然无需使用终端，运行时也不会下载任何内容。

选项 2 — 引导式设置（推荐 CLI 用户使用）

打开终端（macOS：按 Cmd+Space，输入“Terminal”，然后按 Enter）并运行：

npx -y seekstone init

当 Seekstone 出现在 Claude 工具栏的插件图标下时，就表示安装成功。

Seekstone 会读取 Obsidian 自带的库注册表来检测你的库、验证该库，然后打印供你粘贴的配置块，或直接修改 Claude Desktop 配置：

# Auto-detect vault, print config to paste
npx -y seekstone init

# Auto-detect vault, patch Claude Desktop in place (with backup)
npx -y seekstone init --write

# Specify vault explicitly if you have multiple
npx -y seekstone init --vault "/path/to/vault"

# Auto-configure Claude Code in one step (auto-detects vault, runs claude mcp add)
npx -y seekstone init --client code --write

# Or just print the Claude Code command without running it
npx -y seekstone init --client code

选项 3 — 手动配置（Claude Desktop）

将以下内容添加到 claude_desktop_config.json（设置 → 开发者 → 编辑配置）：

{
  "mcpServers": {
    "seekstone": {
      "command": "npx",
      "args": ["-y", "seekstone"],
      "env": { "SEEKSTONE_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}

选项 4 — Claude Code

自动检测你的库，并通过一条命令配置 Claude Code：

npx -y seekstone init --client code --write

如果你想明确指定库路径，也可以手动配置：

claude mcp add seekstone --env SEEKSTONE_VAULT=/absolute/path/to/your/vault -- npx -y seekstone

选项 5 — Cursor

一键安装： — 然后在 Cursor 的 MCP 设置中，将 SEEKSTONE_VAULT 设置为你的库的绝对路径（该链接安装的是占位配置）。

或者，让 CLI 自动检测你的库并修改 ~/.cursor/mcp.json（同时创建备份）：

npx -y seekstone init --client cursor --write

或者手动将配置块添加到 ~/.cursor/mcp.json（全局）或 <project>/.cursor/mcp.json（针对单个项目）：

{
  "mcpServers": {
    "seekstone": {
      "command": "npx",
      "args": ["-y", "seekstone"],
      "env": { "SEEKSTONE_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}

选项 6 — VS Code

一键安装： — 然后在 VS Code 打开服务配置时，将 SEEKSTONE_VAULT 设置为保管库的绝对路径（该链接会安装一个占位配置）。

或者让 CLI 自动检测保管库并写入工作区配置（当前目录中的 .vscode/mcp.json）：

npx -y seekstone init --client vscode --write

或者从终端添加：

code --add-mcp '{"name":"seekstone","command":"npx","args":["-y","seekstone"],"env":{"SEEKSTONE_VAULT":"/absolute/path/to/your/vault"}}'

或者手动将代码块添加到 .vscode/mcp.json（工作区），或通过命令面板 → MCP: Open User Configuration（全局用户配置）添加。请注意 VS Code 的两个特殊之处：顶层键是 servers（而非 mcpServers），且必须指定 "type": "stdio"：

{
  "servers": {
    "seekstone": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "seekstone"],
      "env": { "SEEKSTONE_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}

需要 VS Code 1.102 或更高版本；Seekstone 会显示在 Copilot Chat 的 Agent 模式工具选择器中。

其他 MCP 客户端（Windsurf、Cline 等）

Seekstone 是标准的 MCP stdio 服务 — 任何 MCP 客户端都可以运行它。在客户端的 MCP 配置中使用上面的同一个 JSON 代码块（command: npx、args: ["-y", "seekstone"]、环境变量 SEEKSTONE_VAULT）。

---

安装后，请重启客户端。启动时，Seekstone 会遍历保管库，构建内存中的全文索引（数千条笔记只需几秒），并在你编辑时保持索引实时更新。随后，Claude 即可使用以下 25 个工具。

CLI 选项需要 Node.js ≥ 22。一键安装的 .mcpb 包无需外部依赖。

如果 Seekstone 为你节省了上下文空间，不妨考虑 ⭐ 为仓库加星 — 这有助于其他人发现它。

---

Claude 可以用你的保管库做什么？

连接 Seekstone 后，你可以向 Claude 提出类似这样的请求：

• “搜索我的笔记中关于 [主题] 的所有内容，并给我一份摘要” — 使用 search，返回按相关性排序的摘录，而非完整文件
• “查找所有带有 #project 标签的笔记，并列出标题” — 使用 list_notes 并按标签筛选
• “本周的每日笔记中还有哪些事项未完成？” — 使用 list_tasks，每个复选框返回一行简洁记录，而非整篇笔记；update_task 只需编辑一个字符即可勾选完成
• “只读取我的 [项目] 笔记中的‘决策’部分” — 使用 read_note 并指定章节，因此只有该部分会进入上下文
• “哪些笔记链接到我的 [主题] 笔记？它又链接到了哪些笔记？” — 使用 get_backlinks 和 get_links 遍历你的图谱
• “将今天的站会笔记追加到我的每日笔记中” — 使用 append_periodic_note，根据保管库配置解析每日笔记路径（无需打开 Obsidian）
• “修正这篇笔记中所有旧项目名称的出现位置” — 使用 replace_in_note，写入前会提供试运行预览
• “在 [笔记] 的末尾添加摘要部分” — 使用 append_note，绝不会修改 frontmatter
• “将 /inbox 中的所有笔记移动到 /archive/[year]” — 使用 move_note
• “将这篇笔记 frontmatter 中的状态字段更新为 'done'” — 使用 patch_frontmatter，保留键的顺序和引号样式
• “使用标准模板为今天创建一篇新会议笔记” — 使用 create_note

Claude 不会一次性看到你的整个保管库 — 它会按需搜索和读取，因此即使保管库很大（超过 10k 条笔记），也能控制在上下文预算内。

---

工具

读取

工具	描述
search	全文搜索。返回按相关度排序的摘录（默认约 120 个字符，可通过 excerptLength 调整），而非完整笔记。支持模糊匹配和前缀匹配；设置 SEEKSTONE_SEMANTIC=1 后，mode: "semantic"/"hybrid" 会通过本地嵌入模型按语义搜索（不会有任何内容离开你的设备）。
query_notes	结构化元数据查询。按 frontmatter 键值谓词（eq、ne、contains、exists、missing、gt/gte/lt/lte）、标签、文件夹、修改时间和大小筛选；排序并选择所需字段。返回紧凑的行（默认包含路径和标题），而非笔记内容。
context_pack	通过一次调用，为自然语言问题提供可直接用于回答的上下文，并严格限制在字节预算内（默认 2 KB）：按相关度排序的摘录、附带单行摘要的关联邻近笔记，以及后续来源路径——无需再进行“搜索 → 读取 → 获取反向链接”的往返操作。可按 folder/tag 限定范围，并使用与 search 相同的 mode。
read_note	按相对于 vault 的路径读取笔记的完整内容。支持返回单个章节、区块或行范围。
read_notes	一次调用中读取最多 20 篇笔记（或章节、区块、行范围），并受总字节预算限制（默认 16 KB）。超出预算时，每篇笔记会按公平份额截断并标记为 truncated；单个无效路径会返回自身错误，不会导致整个批次失败。
list_notes	列出笔记，可选择按文件夹前缀或标签筛选。
list_tags	列出 vault 中所有标签，并按使用次数排序（或按字母顺序排序）。
list_tasks	将 Markdown 复选框任务列为紧凑的结构化行（路径、行号、状态、文本、最近的标题）——可遍历整个 vault，也可按笔记、文件夹、标签、状态或修改时间筛选。自定义标记（- [/]、- [-]、……）会作为单字符状态一等处理。
outline_note	返回笔记的标题和区块结构，不包含完整内容——在定向读取前可低成本浏览。
get_backlinks	查找所有链接到指定笔记的笔记。
get_links	列出笔记中的所有出站 wikilink 和 Markdown 链接。
resolve_note	将笔记名称、路径或 frontmatter 别名解析为其规范 vault 路径——为每个匹配项提供来源信息；存在歧义时列出所有候选项，未匹配时提供“你是否要找”建议。
get_periodic_note	读取今天（或任意日期）的每日、每周、每月、每季度或每年笔记——根据 vault 配置解析路径，无需 Obsidian。
list_writes	日志中的近期写入记录——序号、时间戳、工具、涉及的路径，以及每条记录是否仍可撤销。仅包含元数据，绝不包含笔记内容。

写入

工具	描述
create_note	创建笔记（可选的 frontmatter + 正文）；会自动创建父目录。
delete_note	将笔记移至 vault 的 .trash/ 文件夹（兼容 Obsidian，可恢复）。传入 permanent: true 可跳过回收站 — 写入日志仍可让 undo_write 恢复笔记。
move_note	移动或重命名笔记 — 会重写其他笔记中指向它的 wikilink 和 Markdown 链接，避免链接失效（设置 rewriteLinks: false 可禁用）；会自动创建目标目录。
rename_heading	重命名笔记中的标题 — 会重写整个 vault 中的每个 [[note#heading]] wikilink 和嵌入内容，确保引用仍然有效（保留别名，不处理围栏代码块）。
append_note	在笔记正文末尾追加文本，不改动 frontmatter。
patch_frontmatter	设置、更新或删除 frontmatter 键，不改变现有键的顺序或引号样式。
patch_note	在标题或块引用处追加、前置或替换文本（设置 createIfMissing 可添加该章节）— 不改动 frontmatter。
replace_in_note	在笔记正文中查找并替换文本 — 支持字面匹配或正则表达式、区分大小写、整词匹配、可选的 limit（默认替换所有匹配项），并提供试运行预览。
append_periodic_note	追加到今天的周期笔记；如果笔记不存在，则根据模板创建。
update_task	根据路径 + 行号（来自 list_tasks）设置一个复选框的状态 — 只改写一个字符，其他每个字节都保持不变。如果任务文本自列出后发生变化，expectText 防护会拒绝操作。
undo_write	撤销一项已记录的写入：将其触及的每个文件恢复为写入前逐字节相同的状态（多文件移动或标题重命名会整体恢复；即使删除操作设置了 permanent，也能恢复）。默认撤销最近一次写入；如果文件此后发生变化，则拒绝操作并返回 undo_conflict，除非设置 force: true。撤销操作本身也会记录日志 — 对撤销条目调用 undo_write({ seq }) 可重做。

每个写入工具（append_note、patch_note、patch_frontmatter、replace_in_note、rename_heading、move_note、delete_note、append_periodic_note、update_task，以及设置了 overwrite: true 的 create_note）都支持可选的比较并交换：将从 read_note 获取的 contentHash 作为 prevHash 传入，如果笔记期间发生变化，调用会安全失败 — 不会悄然丢弃并发编辑，也不会移动或删除你未查看过的内容。每个变更结果都会返回新的 contentHash，因此连续编辑无需重新读取。

每次写入都可撤销。 在任何写入工具改动任何字节之前，它都会将即将触及的每个文件的写入前状态记录到 <vault>/.seekstone/history/ — 按内容寻址（相同状态只存储一次），并在 vault 写入提交前执行 fsync。list_writes 会显示日志；undo_write 会逐字节恢复：多文件 move_note 或 rename_heading 会整体恢复（笔记以及每一处链接重写），delete_note 即使设置了 permanent 也能恢复。外部编辑后执行撤销会被拒绝并返回结构化的 undo_conflict，除非传入 force: true — 即使如此，被覆盖的状态也会先记录到日志中，因此绝不会丢失内容。撤销操作本身也会记录日志：连续执行默认撤销会沿历史记录逐步回退，对撤销条目调用 undo_write({ seq }) 可重做。.seekstone/ 与 .trash/ 一样，不会被索引或搜索；请将它添加到 vault 的 .gitignore 中。它与 git 和 Obsidian 的文件恢复功能互为补充，而非取而代之 — 这是 Agent 可驱动的恢复路径。 每次写入都会留下记录。 设置 SEEKSTONE_AUDIT_FILE 后，每次写入工具调用——无论成功还是被拒绝——都会追加一行 JSON：工具、相对于知识库的路径、写入前后的 sha-256、结果（ok、hash_conflict、undo_conflict、policy_denied、error），以及操作元数据，例如替换次数或 .trash/ 目标位置；绝不记录笔记内容、frontmatter 值或搜索查询，因此可以放心将该文件附在错误报告中。

{"v":1,"ts":"2026-08-29T21:02:11.042Z","tool":"replace_in_note","outcome":"ok","durationMs":1.8,"seq":42,"files":[{"path":"notes/a.md","hashBefore":"3f9c…","hashAfter":"b71e…"}],"path":"notes/a.md","replacements":3}

哈希值与 read_note 返回的 contentHash 值相同，因此可以对照知识库核验每条记录；seq 是该调用提交的日志条目，因此可通过行索引直接定位到 list_writes / undo_write。记录会在知识库写入提交后追加并执行 fsync；超过 SEEKSTONE_AUDIT_MAX_SIZE 后，文件会轮转为 <file>.1；无法写入审计文件路径会导致启动失败；若追加失败，调用会报告结构化的 audit_failed 错误，而非干净地返回成功。以下是一些 jq 用法示例：

jq -r '[.tool, .outcome] | @tsv' audit.jsonl | sort | uniq -c            # session summary by tool + outcome
jq -c 'select(.files[]?.path == "notes/a.md")' audit.jsonl              # history of one note
jq -c 'select(.ts > "2026-08-29T21:00:00Z" and .outcome == "ok")' audit.jsonl   # what changed since a timestamp

快速，且全面。 在我们的基准测试集里，Seekstone 是唯一将 list_tags、outline_note、get_backlinks 和 get_links 作为一等工具提供的 Obsidian MCP 服务。还有四项能力让它脱颖而出：

• 本地语义搜索，完全在进程内运行。 设置 SEEKSTONE_SEMANTIC=1 后，search 和 context_pack 会新增 mode: "semantic" 和 "hybrid"，即通过小型设备端嵌入模型进行基于含义的检索（只需下载一次 npx -y seekstone fetch-model，或使用内置模型的 seekstone-semantic.mcpb 包；运行中的服务不会访问网络），并从 0.17.0 起加入 MaxSim 后期交互重排。在我们提交的 1 万篇笔记基准测试知识库上（150 条查询的黄金集，fixture v2），默认模型——通过实际搜索工具端到端测量——总体 hit@5 得分为 83.3%，留出集得分为 86.7%（而纯关键词搜索为 34.7%），预热 p50 延迟约为 26 毫秒；选择启用的 potion-retrieval-32M 模型（SEEKSTONE_SEMANTIC_MODEL；约 129 MB）则达到 总体 hit@5 为 86.7%，留出集得分为 86.7%，延迟约为 55 毫秒。我们纳入基准测试的其他服务都没有提供离线、零原生依赖的嵌入功能——而且我们在同一黄金集、同一次运行和已提交的开发集/留出集划分上对替代方案进行了正面对比（已提交的对比结果，结果解读见 COMPETITORS-SHA-322）：obsidian-tc 的纯 Ollama 语义搜索在留出集上略胜我们（90.0% 对比我们的 86.7%），但每次查询耗时 169 毫秒，建索引需 30 分钟，而我们约为 28 秒；其 GraphRAG 模式得分超过我们纳入基准测试的所有方案（留出集 95.0%），代价是每次查询耗时数秒（p50 为 2.9 秒，p95 为 4.2 秒，而我们为 26–55 毫秒）、负载约为 8 倍（每次查询 16 KB 对比约 2 KB），还需要安装并运行第二个服务（Ollama + 一个 1.37 亿参数模型）。我们预先登记了争夺第一名的门槛（GATE-V2-SHA-316，在 fixture v1 上运行），但未能达标——这一结论的公布显著程度与获胜时相同；v2 上没有运行新的门槛测试，相同条款重新计算后结果依然未达标。obsidian-mcp-pro 完全无法为 1 万篇笔记的知识库建立索引（嵌入约 17 分钟后，其 JSON 向量存储超出 JavaScript 字符串长度限制）。如何取舍由你决定——所有数据都已提交。
• 周期笔记，直接访问文件系统。 get_periodic_note 和 append_periodic_note 会读取你自己的知识库配置（.obsidian/daily-notes.json 和 Periodic Notes 插件），解析每日、每周、每月、每季度和每年的笔记路径——即使 Obsidian 已关闭也可以。 基于 REST 的服务只能在应用运行时执行此操作。
• 确保前置元数据逐字节一致。 patch_frontmatter 会原地编辑 YAML，保留键顺序、引号样式和注释；测试框架已通过逐字节比对验证写入安全性。我们调查过的其他服务都无法作出这项保证。
• 零耦合。 无需 Obsidian 应用、Local REST API 插件，也不受插件版本变动影响。只需使用磁盘上的文件。

配置

变量	必填	描述
SEEKSTONE_VAULT	是	Obsidian 库的绝对路径。
SEEKSTONE_LOG_LEVEL	否	error | warn | info（默认）| debug。
SEEKSTONE_LOG_FILE	否	绝对路径；设置后，JSON 行日志会追加到此处（按大小轮转）。
SEEKSTONE_LOG_MAX_SIZE	否	SEEKSTONE_LOG_FILE 的日志轮转阈值（例如 10mb；默认 5 MB）。
SEEKSTONE_WATCH_POLL	否	设为 1，以轮询文件状态来检测更改，而不是使用原生 OS 事件——速度较慢，但在网络驱动器、WSL 和某些容器中更可靠。
SEEKSTONE_WATCH_POLL_INTERVAL	否	文件状态轮询间隔，单位为 ms（默认 10000）。仅在 SEEKSTONE_WATCH_POLL=1 时使用。间隔越短，发现外部编辑越快，但 CPU 占用越高；在较慢的网络或 9p 挂载上应调高此值。
SEEKSTONE_READ_ONLY	否	设为 1 以只读模式运行：11 个写入工具会从工具列表中完全移除（即使被调用也会被拒绝），因此可以确证会话无法修改你的库。
SEEKSTONE_WRITE_PATHS	否	以逗号分隔的库相对路径 glob（例如 journal/**,inbox/*.md）。仅允许写入匹配路径下的内容；库的其余部分保持只读。
SEEKSTONE_HISTORY	否	设为 0 可禁用写入日志（默认开启）。启用后，每个写入工具都会将其修改的每个文件的写入前内容存储在 <vault>/.seekstone/history/ 下，以便 undo_write 逐字节还原文件。
SEEKSTONE_HISTORY_MAX_SIZE	否	写入前内容的存储上限（例如 100mb；默认 50 MB）。先淘汰最旧的条目，然后在 list_writes 中显示 undoable: false——绝不会静默处理。
SEEKSTONE_HISTORY_MAX_ENTRIES	否	日志条目上限（默认 1000）；超过上限后会丢弃最旧的条目。
SEEKSTONE_AUDIT_FILE	否	绝对路径；仅在设置后启用。每次写入工具调用（成功或拒绝）都会追加一条 JSON 行审计记录，其中包含工具、路径、写入前后的 sha-256、结果和操作元数据。绝不记录笔记内容。
SEEKSTONE_AUDIT_MAX_SIZE	否	超过此大小后，将审计文件轮转为 <file>.1（例如 10mb；默认 10 MB）。
SEEKSTONE_SEMANTIC	否	设为 1 可启用语义搜索（search 和 context_pack 将支持 mode: "semantic" 和 "hybrid"）。需要本地嵌入模型——使用 npx -y seekstone fetch-model 下载一次；运行中的服务绝不会访问网络。seekstone-semantic.mcpb 包会自动设置此项，并内置该模型。
SEEKSTONE_SEMANTIC_MODEL	否	要加载的本地模型：potion-base-8M（默认，约 30 MB，256 维）或 potion-retrieval-32M（约 129 MB，512 维——对描述式查询更准确，查询延迟约为 2 倍）。请先使用 npx -y seekstone fetch-model --model potion-retrieval-32M 下载。
SEEKSTONE_MODEL_PATH	否	存放 Model2Vec 嵌入模型的目录（默认：fetch-model 将所选模型放入的缓存目录）。
SEEKSTONE_CACHE_DIR	否	下载的模型和每个库的嵌入缓存所在的缓存根目录（默认 ~/.cache/seekstone）。
SEEKSTONE_BUNDLED_MODEL_DIR	否	由 seekstone-semantic.mcpb 包的清单设置——指向扩展中内置的分片模型文件，服务会在启动时将其重新组装到模型目录中（仅写入磁盘，并根据固定的 SHA-256 哈希进行验证）。通常无需手动设置。
SEEKSTONE_INSTRUCTIONS	否	文件路径，该文件的内容将成为 MCP 服务的 instructions 字符串（与工具列表一同呈现给客户端）。相对路径以库根目录为基准解析。启动时读取一次，去除首尾空白，限制为 16 KB（超出时截断并发出警告）。文件不存在、无法读取或去除首尾空白后为空时，不提供任何指令——不会导致启动失败。

---

工作原理

Seekstone 使用 fast-glob 遍历知识库，解析每篇笔记的 frontmatter（按字节处理，因此写入前后可以验证 frontmatter 区域的字节完全一致），并在内存中构建 MiniSearch 全文索引。搜索返回经过排序的简短摘录，而非整篇笔记——上下文成本的降低正是源于这种“摘录而非文档”的设计。跨平台文件监视器（chokidar）会在你使用 Obsidian 编辑时保持索引最新。

写入功能在设计上力求保守：append_note 绝不触碰 frontmatter，patch_frontmatter 则直接修改 YAML 文档，而不是重新序列化，从而保留键的顺序、引号样式和注释。

它的设计目标是持续稳定运行。Seekstone 会在每次提交时通过 CI 在 macOS、Linux 和 Windows 上接受测试；其写入工具经过强化，可抵御病态输入（ReDoS）；对于意外的未处理拒绝，会记录日志而不是崩溃——因此，长期运行的 MCP 会话能够保留热索引，不会在对话中途意外退出。

如需逐层了解代码库——包括各个包、服务内部实现、端到端请求流程和测量工具——请参阅 docs/ARCHITECTURE.md。

---

安全与隐私

Seekstone 会读取本地磁盘上 SEEKSTONE_VAULT 下的文件，并可通过写入工具修改这些文件。运行中的服务不会进行网络调用，也不会发送遥测数据（包中唯一的网络路径是显式运行 npx -y seekstone fetch-model 子命令：一次性下载可选的语义搜索模型，并通过 SHA-256 验证；该命令会在服务启动前退出；seekstone-semantic.mcpb bundle 则连这一步也省去了，因为它将模型随包提供，并在启动时从磁盘重新组装，且会使用相同的固定哈希进行验证）。默认情况下，日志只包含元数据（只有在 debug 级别才会出现笔记内容）。除可选的日志文件（需自行配置）以及启用 SEEKSTONE_SEMANTIC=1 时位于 ~/.cache/seekstone 的每个知识库嵌入缓存（由笔记生成的向量——绝不会发送到任何地方）外，不会在知识库之外写入任何内容。

写入安全契约

允许 AI 写入你的笔记，光说“请相信我们”还不够。Seekstone 提供了一份具名且经过测试的契约——docs/WRITE-SAFETY.md——其中列出了十项保证，每项都链接到负责强制执行的代码和用于验证的测试。这些保证会由 CI 中的安全测试套件逐字节验证，并在每次提交和发布时运行：零网络访问、知识库沙盒、编辑正文时 frontmatter 字节完全一致、原子写入（不会产生残缺文件）、创建操作绝不覆盖现有文件、可恢复删除（.trash/）、每个写入工具均支持可选的比较并交换、可配置写入范围／只读模式、可撤销每次写入的写入日志（undo_write），以及可通过哈希验证的审计日志——每次写入调用都会留下回执。同一测试套件也会以无头模式对其他直接操作文件系统的服务运行；契约中包含对比表。

常见问题

需要运行 Obsidian 应用吗？ 不需要。Seekstone 直接从磁盘读取库文件夹。Obsidian 可以处于打开或关闭状态。

我需要安装 Local REST API 插件吗？ 不需要。Seekstone 完全绕过它——这正是有效载荷减少高达 47,000 倍的原因。无需安装任何插件。

它支持哪些 AI 客户端？ 任何支持通过标准输入/输出使用 Model Context Protocol（MCP）的客户端——Claude Desktop、Claude Code、Cursor、Windsurf、Continue 等。

在我的库中使用安全吗？ Seekstone 绝不会修改文件，除非你明确调用它的某个写入工具（上表中的十个工具——create_note、append_note、patch_note、patch_frontmatter、replace_in_note、move_note、rename_heading、delete_note、append_periodic_note、undo_write）。每个工具都会先记录其要修改的每个文件的原始内容，因此 undo_write 可以逐字节还原——请参阅上文的写入日志说明。设置 SEEKSTONE_AUDIT_FILE 后，每次写入调用都会留下可通过哈希验证的审计记录（包括被拒绝的尝试）。运行中的服务不会发起网络请求（语义搜索模型由显式调用的 fetch-model 子命令在服务之外下载一次）。库路径受到沙盒限制——任何工具都无法在此路径之外读取或写入。你还可以进一步收紧限制：SEEKSTONE_READ_ONLY=1 会从会话中完全移除写入工具，而 SEEKSTONE_WRITE_PATHS 会将写入限制在你允许的文件夹中（例如，仅允许 journal/**）。这两项限制都在分发层执行，而非由各个工具单独执行，因此没有工具会漏掉检查。

它能在 Windows 上运行吗？ 能。Seekstone 会在每次提交时通过 CI 在 macOS、Linux 和 Windows 上进行测试。

搜索能处理拼写错误吗？ 可以处理轻微的拼写错误。关键词搜索允许 3–7 个字母的单词每个有一个拼写错误，8 个或更多字母的单词每个有两个拼写错误，因此输入 benchamrk 仍能找到 “benchmark”。一个或两个字母的单词必须完全匹配，交换两个字母则算作两个拼写错误。搜索也会匹配单词前缀：kuber 可以找到 “Kubernetes”。search、context_pack、query_notes 和 list_notes 中的 tag 筛选器与 Obsidian 的行为相同：忽略大小写并包含嵌套标签，因此 project 可以匹配 #Project/alpha。如果某个标签不存在，工具会返回 unknown_tag 错误并列出最接近的现有标签。

它能处理多大的 Obsidian 库？ Seekstone 已针对包含数千篇笔记的库进行性能分析。在已提交的 10,000 篇笔记基准测试库中，冷启动索引构建需要几十秒，进程 RSS 低于约 100 MB；典型的个人库只需几秒即可完成索引。语义模式会在启动后于后台生成嵌入（10,000 篇笔记约需 30 秒，之后会按库缓存，因此重启时可在不到一秒内重新加载）。

seekstone init 如何自动找到我的库？ 它会读取 Obsidian 自己的库注册表（obsidian.json）——Obsidian 用同一文件跟踪你已知的库。如果你只有一个库，系统会自动选择。如果你有多个库，系统会列出它们，并要求你使用 --vault 选择。

.mcpb 文件是什么？ MCP Bundle——一个包含服务及其清单的独立压缩包。安装方法：在 Finder 中双击（或右键点击 →“打开方式”→ Claude Desktop），选择你的库，即可完成安装。无需使用终端或 Node.js。每个版本都提供两个变体：seekstone.mcpb（标准版）和 seekstone-semantic.mcpb（相同的服务，内置本地嵌入模型，开箱即用语义搜索）。

---

贡献与开发

欢迎贡献。请参阅 CONTRIBUTING.md 了解指南，或直接开始：

npm install                                          # install all workspace deps
npm test                                             # run all tests
npm run lint                                         # biome check
npm run build -w seekstone                           # tsup → dist/
npm run build:mcpb                                   # build seekstone.mcpb bundle

npx vitest run packages/server/src/tools/search.test.ts  # single test file
npx vitest run -t 'parses a typical frontmatter'         # single test by name
npx tsc -p packages/server/tsconfig.json --noEmit        # typecheck

仓库布局

包	用途
packages/server	已发布的 seekstone MCP 服务（25 个工具、stdio、MiniSearch 索引、chokidar 监视器）。
packages/core	共享的知识库基础功能——遍历、frontmatter 解析器、链接/标签提取器、大纲、百分位数、pmap 和 Model2Vec 嵌入器。会打包到服务构建产物中。
packages/harness	分析器 + 基准测试 + 写入安全测试框架（REST 与文件系统），用于生成上述负载数据。仅用于开发；不会发布。

服务会实际构建（tsup → dist/）并发布到 npm。测试框架通过 tsx 从源码运行。发布流程已自动化——参见 docs/RELEASING.md。

测量测试框架

该测试框架用于复现促成文件系统直连设计的基准测试数据。默认复现路径（针对已提交的合成知识库使用 fs/seekstone 后端）不需要任何额外配置；只有基于 REST 的后端（rest、mcp-obsidian、obsidian-mcp-server）需要在 Obsidian 运行并启用 Local REST API 插件。

export SEEKSTONE_VAULT="/absolute/path/to/your/vault"

npx tsx packages/harness/src/cli.ts profile --vault "$SEEKSTONE_VAULT"
npx tsx packages/harness/src/cli.ts bench \
  --queries packages/harness/queries/default.json \
  --stats reports/vault-stats.json
npx tsx packages/harness/src/cli.ts safety --vault "$SEEKSTONE_VAULT"

测试框架环境变量：SEEKSTONE_REST_API_KEY（来自 Local REST API 插件）和 SEEKSTONE_REST_URL（默认为 https://127.0.0.1:27124）。

---

支持

Seekstone 免费且开源。如果它为你节省了上下文（和金钱），你可以请我喝杯咖啡。

---

许可证

MIT © Shaq Mughal