Obsidian 知识库面板 2026heshao/dsh-obsidian-board

dsh-obsidian-board

一个 DeepSeek Harness (DSH) 插件，把本地 Obsidian vault 变成 DSH GUI 里的专属 RAG 聊天面板——侧边栏入口点进去是完整的三栏页面：左边笔记浏览器，中间检索增强聊天，右边引用笔记原文。桌面应用和 Web GUI 用的是同一套浏览器渲染客户端，所以面板在两边表现一致。索引和 BM25 匹配100% 本地运行（不用嵌入模型，不用向量数据库）；可选的 planner 查询改写和答案生成走你已经在 DSH 里配好的模型通道——只发送你的问题、最近的对话和检索到的片段，vault 本身绝不上传。

不是 MCP 集成，也不是 Obsidian 插件——这是一个双半 DSH 插件（host + 浏览器客户端）。UI 以 main 槽位页面的形式注入 DSH 主窗口（和切换会话是同一套机制）；模型调用复用 host 的 ctx.llm；知识库指向你本地的 vault 目录（Obsidian 都不用开着）。

兼容性：对照实际安装的 DeepSeek Harness 44.7.0 验证过（host 自带 @deepseek-ai/dsh-typert-protocol@0.2.1-rc.2 / cordis 4.0.5）；声明的 peer 范围 >=0.1.5-rc.1 仍然覆盖它。从 v0.2.5 起，浏览器那一半还会从 host 的浏览器模块表里取 react、react-dom 和 @deepseek-ai/dsh-client-ui-primitives（模型菜单就是这样复用 host 自己的 primitives——兄弟插件 dsh-forget-session 在 44.x 上已经要求这三个模块）；如果某个配置档缺了它们，面板页面会直接渲染失败，而不是降级。44.7.0 验证之后的改动由仓库测试套件（node --test）覆盖；索引和 watcher 的数字来自本地合成的 1 万条笔记 vault 上重跑的结果，UI 那批（composer 和模型菜单）还没做过新一轮应用内回归。

功能

- 🔍 本地优先检索——BM25 加 CJK 二元分词，标题/路径加权，识别 Obsidian 标签和别名。不用嵌入模型；索引和 BM25 匹配不发任何网络请求，vault 本身永远不离开你的机器。答案生成（以及可选的 planner 查询改写）走你配置的 DSH 模型通道——只发问题、最近的对话和检索到的片段。
- 🎯 找得到你真正写下的内容——你自己的笔记排在收集来的第三方材料前面（公开技能库会降权），github_pat_… 这类长标识符按字面匹配，有意义的隐藏文件夹（比如 .workbuddy/）会被索引，而不是悄悄跳过。
- 🛑 真正能停下的停止按钮 — 停止按钮在任何阶段都生效，包括检索/规划阶段，以及模型输出第一个 token 之前的静默期。已停止的回复显示为中性的「已停止」状态，而不是红色错误。在页面任意位置连按两次 Escape 也能达到同样效果。
- ⌨️ 行为与主聊天一致的输入框 — 输入卡片按宿主 InputBar 的几何尺寸和交互约定重建：发送和停止共用一个主按钮（回复流式输出且输入框为空时显示停止方块），回复仍在生成时按 Enter 会把消息排队而不是丢失（排队项列在卡片上方，当前回答结束后自动发送，每项可单独移除，显式停止会把文本交还输入框而不是丢弃），尊重输入法组合状态，用 Enter 选候选词绝不会发出半截消息，输入框自动增高，发送后焦点回到输入框。焦点指示器画在圆角卡片上，不会有矩形轮廓浮在上面。
- 🎚 从宿主移植的模型菜单 — 选择器是移植的宿主 ModelSelect，不是仿制品：两级「模型 / 推理强度」菜单，服务商分组带吸顶标题，列表超过 4 项时出现搜索，完整键盘导航带焦点交接，向上展开的 portal 菜单在滚动和缩放时重新定位，每行带元数据（免费 / 额度 / 上下文窗口 / 支持的强度）。它显示宿主的实际默认模型，而不是笼统的「默认模型」标签，你看到的强度就是实际发送的强度。选择只作用于面板的下一条消息——这是按消息覆盖路由，你的 DSH 全局设置保持不变。
- 🧵 输出绝不串字或卡死 — 流式管道按每次尝试分别键控，切换服务商回退时不会把两个回答拼在一起，也不会悄悄吞掉回复；每个回答显示实际产出它的模型，在回退通道上重新生成的回复带有「回退通道」标签，绕行可见，不被隐藏。面板刷新导致中途中断的回复标记为「已中断」并带重试按钮，而不是一直转圈。
- 📖 引用与召回如实分开 — 回答中的每个 [n] 和下方的标签都会在右侧来源面板打开对应笔记。标签按回答实际标记的 [n]（已引用）与检索浮现但回答从未引用的内容（相关片段）分组，使用与正文渲染 [n] 相同的匹配器，.md 导出保留同样的两个分区。
- 📊 丰富的 Markdown 回答 — 表格、标题、链接、斜体和任务列表在回答和来源面板中都能渲染，并做沙箱隔离（无可执行链接）。
- 📡 实时仓库同步 — 可选的文件监听直接从监听事件里定位改动的笔记，只重建那一篇：在下面这个 1 万篇笔记的仓库上，端到端约 0.2 秒（精简仓库）到约 0.26 秒（内容丰富的仓库），已含 150 毫秒防抖，期间不做任何全目录扫描。无法定位到单个文件的事件——重命名、删除、不报告文件名的批量改动——回退到合并后的全量增量扫描（约 1.2 秒窗口），不会悄悄漏掉任何改动。
- 📃 长仓库照样好用 — 笔记列表随滚动分页，每条回答显示所处阶段（检索 → 规划 → 生成）。
- 🧭 引导式设置 — 仓库路径无效会在配置阶段就被拦下，并给出明确的合法性提示；回答超时可配置。
- 🗂 自动发现仓库 — 读取 Obsidian 自己的仓库注册表，扫描常见位置，提供系统目录选择器，也可以粘贴路径。
- ⚡ 增量索引 — 基于 mtime。在一个合成的 1 万篇笔记 / 4 万个分块的仓库上实测（本机，Node 24）：全量索引约 2 秒，单篇笔记改动后重建约 50 毫秒。这个 ≈50 ms 只覆盖单篇笔记的构建 + 提交 + 统计重算：端到端增量扫描仍要遍历目录并对每个文件做 stat，同一仓库实测约 0.9–1.0 秒。监听器走的是定向路径，所以一次保存约 0.2–0.26 秒落地（定向之前约 1.5 秒）。
- 🧩 原生面板体验 — 注册在侧边栏的「Panels」分组下（和插件管理器、计时器并列）；面板在浏览器里维护自己的聊天记录，与 DSH 会话日志分开。
- ⬇️ 导出走下载，不写仓库 — 「Export chat .md」触发真正的浏览器下载（位置由你选；非 DOM 宿主回退为把全文复制到剪贴板），而不是悄悄写进仓库。
- ↔️ 可调整的源码面板 — 拖动聊天区和右侧笔记预览之间的分隔条即可调整宽度（支持键盘操作，双击复位，宽度在刷新后保留）。

安装

方式 1 — dsh-market（应用内，最省事）： 在 DSH 插件市场搜索完整包名 dsh-obsidian-board 并安装（只搜 obsidian 也会匹配到无关条目；市场显示名以列表页为准）。

方式 2 — 命令行：

dsh plugin --profile web add "dsh-obsidian-board"

方式 3 — 从源码（本仓库）：

dsh plugin --profile web add file:"<path to this repo clone>"

或手动操作：在 ~/.dsh/profiles/<profile>/package.json 的 dependencies 里加上 "dsh-obsidian-board": "file:<path>"，在 dsh.profile.bundles 里加上 "dsh-obsidian-board"，然后在该目录运行 pnpm install，重启 DSH。

桌面应用用户：装到 desktop 配置档——把上面命令里的 --profile web 换成 --profile desktop（~/.dsh/profiles/web 换成 ~/.dsh/profiles/desktop）。其余完全相同。

配置

在配置档补丁里设置 vault 路径（~/.dsh/profiles/<profile>/cordis.patch.yml）：

- insert:
- id: dsh-obsidian-board
name: dsh-obsidian-board
config:
vaultPath: "D:\\notes\\MyVault" # vault root (absolute; ~ works too)
provider: "" # DSH llm provider route; empty = host default
model: "" # model id; empty = provider default
topK: 8 # retrieved chunks fed to the answer (only those marked [n] are labelled as citations)
chunkLimit: 1200 # max chars per chunk in the prompt
systemPrompt: "" # custom RAG system prompt (empty = built-in)

vaultPath 可以留空 —— 首次打开时面板会显示设置卡片，你可以在那里交互式地发现、挑选或粘贴 vault 路径。

用法

1. 点击侧边栏「Panels」分组里的 Obsidian（或侧边栏底部的入口）。
2. 首次使用：选择你的 vault → 连接（索引在本地运行，不发起网络请求；在由短笔记构成的合成 vault 上实测：50 条笔记约 9 ms，200 条约 52 ms，500 条约 0.12 s，1 万条约 2 s）。
3. 提问，比如 「我的笔记里关于 X 都说了什么？」 或 「总结 #tag 下的要点」。
4. 点击 [1] [2] 引用或答案下方的标签（分为 cited / related snippets 两组）→ 笔记会在右侧打开。
5. 回车发送；回复生成过程中按回车会把消息排队，而不是打断它。输入框下方的标签打开模型菜单（模型 + 推理强度）—— 它只覆盖本面板后续提问的路由，绝不会改动你的 DSH 全局默认值。

工作原理

dsh-obsidian-board/
├── lib/
│ ├── index.js # Host half: ObsidianBoardGateway (TypertRemoteService)
│ │ # status/configure/discoverVaults/pickVault/revealVault/
│ │ # listNotes/readNote/search/reindex/chat
│ │ # BM25 runs locally; chat streams via ctx.llm (DSH model channel)
│ ├── typert.js # RPC contract (dual-key codec, 0.1.5-rc.x and 0.1.6+ compatible)
│ ├── vault.js # Zero-dependency Node indexer: scan/frontmatter/BM25/incremental
│ └── client.js # Browser half: main-slot page + sidebar panellist/footer entries
├── cordis.patch.yml
└── locale/.json, icon.svg

面板聊天不会写入 DSH 会话日志：历史记录在面板内按 vault 划分命名空间，并通过 historyGet/historySet 同步到宿主，因此面板重新加载后仍然保留（localStorage 作为本地兜底）。宿主侧的历史记录保存在内存中，服务重启即清空。模型调用走宿主的 ctx.llm，所以配额、重试和服务商路由的行为与你的主 DSH 会话完全一致。

已知限制

- 检索用的是 BM25 + 中文 bigram + 标题/标签加权，不是语义向量检索。专有名词、关键词、标签效果最好；长句改写的提问可能召回不到（后续计划接入本地 embedding 模型，接口已经预留）。长标识符（PAT、哈希、文件名）按字面匹配，用来补偿这一点。
- 收集来的第三方材料（_公网收集、vendor、node_modules 这类路径）会降权，让你自己的笔记排前面——它们仍可检索，只是排名低于你自己写的内容。
- 隐藏文件夹只在有意义时才建索引（.workbuddy 在允许列表里）；结构性/缓存类文件夹（.obsidian、.trash、.git）一律跳过。
- 插件的完整配置项由 lib/index.js 里的 Config 定义（覆盖所有字段，包括 planner、timeout、scan/watch 调优）——本 README 里的 cordis.patch.yml 片段只是安装模板（6 个键）；面板里的配置卡片可以编辑每一个字段。
- 面板历史按 vault 分命名空间，通过 historyGet/historySet 同步到宿主；面板重载后仍在，支持 JSON 导出/导入。宿主侧历史存在内存里（服务重启即清空），本地用 localStorage 兜底。
- 面板聊天有意不支持 DSH 主会话的工具调用 / 子代理（知识库问答用不上）。
- 输入框对齐主聊天的发送 / 停止 / 排队 / 模型菜单行为，但刻意没有附件、没有 / 命令、没有 @ 文件引用——原因同上。

License

MIT

把本地 Obsidian vault 变成 DeepSeek Harness 里的专属知识库对话页面（桌面端与 Web 端通用）：侧栏多一个「Obsidian」入口，点开就是一个完整面板——左侧笔记浏览器、中间 RAG 聊天、右侧引用原文。索引与 BM25 召回全部本地完成，回答走 DSH 已配置的模型通道（只发送问题、最近对话与命中片段，整库不上传）。

不是 MCP 接入，也不是 Obsidian 插件——这是一个 DSH 客户端+宿主双半插件：UI 注入进 DSH 主窗口（main slot 页面，与切换对话同构），模型调用复用宿主 ctx.llm，知识库指向你本地的 vault 目录（无需 Obsidian 运行）。

兼容性：已在真实安装的 DeepSeek Harness 44.7.0（宿主内置 @deepseek-ai/dsh-typert-protocol@0.2.1-rc.2 / cordis 4.0.5）上做过兼容性核对；声明的 peer 范围 >=0.1.5-rc.1 继续覆盖。自 v0.2.5 起，客户端半还会从宿主的浏览器模块表里取 react、react-dom、@deepseek-ai/dsh-client-ui-primitives 三项（模型菜单复用宿主自带 primitives 的代价——同目录的姊妹插件 dsh-forget-session 在 44.x 上就是按同样方式 require 这三个模块）；万一某个 profile 缺这几项，面板页面会直接渲染不出来而不是降级。44.7.0 核对之后的改动由仓库测试（node --test）覆盖，索引与监听的性能数字是本机 10k 合成库复测所得；UI 批次（输入框与模型菜单）未在实机做过一轮完整回归。

特性

- 🔍 本地优先检索——BM25 + 中文 bigram 切词、标题/路径加权、Obsidian 标签与别名感知。不用 embedding；索引与 BM25 召回不发任何网络请求，vault 整库不出本机——回答生成（以及可选的 planner 查询改写）走你在 DSH 配好的模型通道，只发送问题、最近对话与命中片段。
- 🎯 找得到你真正写的东西——自有笔记优先于收集来的第三方语料（公开 skill 库降权）、github_pat_… 这类长标识符按字面精确匹配、有意义的隐藏目录（如 .workbuddy/）也会纳入索引而非被静默跳过。
- 🛑 停止真的能停——停止按钮在任何阶段都生效，包括检索/规划阶段、以及模型吐首字前的静默期；被停止的回复显示中性「已停止」状态，而不是红色报错。页面任意位置连按两次 Esc 同样能停。
- ⌨️ 输入框与主对话页同构——输入卡按宿主 InputBar 的几何与交互契约重做：发送与停止共用一个主按钮（生成中且输入框为空时变成停止方块）；生成中按 Enter 不再打断当前回答，而是把消息排进队列（队列条目列在输入卡上方，本轮回答结束后自动发送，可单条移除；显式停止时会把待发的文本退回输入框，不静默吞掉）；输入法合成期按 Enter 只选词不发送，中文候选词不会把半截消息发出去；输入框自动增高，发送后焦点回到输入框。聚焦态的高亮画在圆角卡片上，不会再浮出一个和卡片不贴合的直角蓝框。
- 🎚 模型菜单直接搬宿主实现——不是「照着画」，是把宿主 ModelSelect 移植过来：「模型 / 推理档位」两级菜单、provider 分组 + 吸顶分组头、超过 4 条自动出搜索框、完整键盘导航与焦点回归、向上弹出的 portal 菜单并在滚动/缩放时重新定位、每行带免费/费率/上下文窗口/可用档位信息。未显式选择时显示的是宿主配置的真实默认模型，而不是笼统的「默认模型」；看到的档位就是实际下发的档位。选择只作用于本面板的下一条消息（消息级路由覆盖），不改你在 DSH 的全局默认。
- 🧵 输出不再错乱、不再卡死——流式管线按「尝试轮次」对齐增量，provider 回退切换时不会把两次回答拼在一起、也不会静默吞掉整段回答；每条回答都会标注真正产出它的模型，走备用通道重生成的回答还会额外标出「备用通道」——绕路要看得见，才算真的标了来源。面板被刷新打断的半截回答会标记为「已中断」并给出重试按钮，而不是永远转圈。
- 📖 引用与召回分开说——回答里的 [n] 与底部引用 chips 都能点开右栏对应笔记原文。chips 按「正文真的标了 [n]」分成引用与相关片段两组，判据与正文渲染 [n] 用的是同一条正则；导出的 .md 同样分两节写，不把召回一律冒充成引用。
- 📊 Markdown 富渲染——回答与原文栏支持表格、标题、链接、斜体、任务列表，沙箱化渲染（无可执行链接）。
- 📡 vault 变更自动同步——可选文件监听：从事件里的文件名直接定位到变动的那篇，只重建那一篇（10k 库实测端到端约 0.2–0.26s，含 150ms 防抖，期间零全量扫描）；定位不到单篇的事件（改名、删除、批量变动不给文件名）退回全量增量对账（约 1.2s 合并窗口），不漏改动。
- 📃 长列表依然顺手——笔记列表滚动触底分页，回答过程可见阶段（检索 → 规划 → 生成）。
- 🧭 配置有引导——vault 路径无效会在配置时报错并给出有效性提示，回答超时可配置。
- 🗂 自动发现仓库——读 Obsidian 自己的仓库注册表、扫描常见位置、支持系统目录选择对话框，或直接粘贴路径。
- ⚡ 增量索引——按 mtime 增量刷新。本机实测（合成库 10k 笔记 / 40k chunk，Node 24）：全量索引约 2s，单篇「构建 + 提交 + 重算统计」约 50ms。口径注意：端到端增量仍要走一次目录扫描 + 逐文件 stat，同一库实测约 0.9–1.0s；文件监走走的是定向路径，保存后约 0.2–0.26s 就能检索到新内容（改造前约 1.5s）。
- 🧩 原生面板体验——注册在侧栏「全局面板」组（与插件管理、定时任务同组）；面板对话历史独立存于浏览器，与 DSH 会话日志互不干扰。
- ⬇️ 导出即下载——「导出对话 .md」触发浏览器真实下载（保存位置由你决定；无下载 API 的宿主环境降级为复制全文到剪贴板），不再静默写入 vault。
- ↔️ 原文栏可拖宽——对话区与右侧笔记预览之间的分割线可拖动缩放（键盘可达、双击复位、宽度跨刷新记忆）。

安装

方式一——dsh-market（应用内，最简单）： 在 DSH 插件市场按精确包名搜 dsh-obsidian-board 安装（只搜 obsidian 会同时命中其他无关条目；市场里的显示名以条目自身为准）。

方式二——CLI：

dsh plugin --profile web add "dsh-obsidian-board"

方式三——从本仓库源码：

dsh plugin --profile web add file:"<本仓库 clone 路径>"

或手动：在 ~/.dsh/profiles/<profile>/package.json 的 dependencies 加 "dsh-obsidian-board": "file:<路径>"、dsh.profile.bundles 加 "dsh-obsidian-board"，然后在该目录 pnpm install 并重启 DSH。

桌面端装进 desktop profile：把上面命令里的 --profile web 换成 --profile desktop（~/.dsh/profiles/web 换成 ~/.dsh/profiles/desktop），其余步骤相同。

配置

编辑 profile 补丁（~/.dsh/profiles/<profile>/cordis.patch.yml）里 dsh-obsidian-board 条目的 config：

- insert:
- id: dsh-obsidian-board
name: dsh-obsidian-board
config:
vaultPath: "D:\\笔记库\\MyVault" # vault 根目录（绝对路径；支持 ~ 开头） provider: "" # DSH llm provider 路由名；空=宿主默认路由 model: "" # 模型 id；空=provider 默认 topK: 8 # 每次送进回答的召回片段数（正文真标了 [n] 的才算引用） chunkLimit: 1200 # 单片段最大字符数 systemPrompt: "" # 自定义 RAG 系统提示词（空=内置）

vaultPath 留空也可以：第一次打开面板时会有配置卡，在面板里直接发现/选择/粘贴路径连接。

使用

1. 侧栏「全局面板」里点 Obsidian（或侧栏底部入口）
2. 首次使用：选 vault → 连接（建索引在本地跑、不联网；合成短笔记实测：50 篇约 9ms、200 篇约 52ms、500 篇约 0.12s、万级库约 2s）
3. 直接提问：「我关于 X 的笔记说了什么」「总结 #标签 下的要点」
4. 回答里的 [1] [2] 引用与底部 chips（引用 / 相关片段两组）可点击 → 右栏打开笔记原文
5. Enter 发送；生成中按 Enter 是排队而不是打断当前回答。输入框下方的模型按钮打开模型菜单（模型 + 推理档位），选择只作用于本面板后续的提问（消息级路由覆盖），不会改你在 DSH 的全局默认

架构

dsh-obsidian-board/
├── lib/
│ ├── index.js # 宿主半：ObsidianBoardGateway（TypertRemoteService） │ │ # status/configure/discoverVaults/pickVault/revealVault/ │ │ # listNotes/readNote/search/reindex/chat │ │ # 检索本地 BM25；chat 走 ctx.llm.stream（DSH 模型通道） │ ├── typert.js # RPC 契约（双键 codec，兼容 0.1.5-rc.x 与 0.1.6+） │ ├── vault.js # 纯 Node 零依赖索引器：扫描/frontmatter/BM25/增量刷新 │ └── client.js # 客户端半：main slot 页面 + panellist/footer 入口 ├── cordis.patch.yml └── locale/.json, icon.svg

与 DSH 主会话的关系

面板对话不写入 DSH session log：面板历史按仓库隔离并与宿主端 historyGet/historySet 同步（localStorage 兜底），面板重载后仍在；宿主端历史为内存态，服务重启即清。模型调用走宿主 ctx.llm，所以配额、重试、provider 路由与 DSH 主会话完全一致。

已知边界

- 检索引擎是 BM25 + 中文 bigram + 标题/标签加权，不是 embedding 语义检索——专有名词、关键词、标签检索效果最好，长句意译可能漏召回（二期可挂本地 embedding 模型，接口已留好）。PAT / 哈希 / 文件名这类长标识符已按字面精确匹配补偿。
- 收集来的第三方语料（_公网收集、vendor、node_modules 等路径）会降权，让你的自有笔记排在前面——不是剔除，真要查这些资料仍可召回，只是排序靠后。
- 隐藏目录只在「有意义」时才纳入索引（.workbuddy 已在白名单）；.obsidian、.trash、.git 这类结构/缓存目录始终跳过。
- 插件的完整配置面以 lib/index.js 的 Config 为准（含 planner、超时、扫描/监听调优等全部字段）——本 README 里 cordis.patch.yml 片段只是接入模板（仅 6 键）；面板内配置卡可编辑全部字段。
- 面板历史按仓库隔离（history:<vaultHash> 键），支持导出/导入 JSON，并与宿主端 historyGet/historySet 同步；宿主端为内存态（服务重启即清），本地 localStorage 兜底。
- 面板会话不支持 DSH 主会话的工具调用/子代理（这是设计取舍：知识库问答不需要）
- 输入框对齐了主对话页的发送 / 停止 / 排队 / 模型菜单，但不含附件、/ 指令与 @ 文件引用——同上，知识库问答不需要

License

MIT