知识画布 NeoHotaru/dsh-knowledge-canvas

dsh-knowledge-canvas

English · 简体中文 · 使用手册

给 DeepSeek Harness 的知识库：模型靠判断去取，而不是靠相似度。

主要功能

- 知识画布：编辑节点、父子关系和关联线，支持四种布局与节点尺寸调整。
- 收起与查找：折叠暂时不用的分支，搜索时展开目标路径；长文可滚动，缩成标题后可悬停预览。
- 分层注入：知识库设置全文或按需默认方式，单个节点可覆盖。
- 改动审核：查看模型新增、修改、删除的内容，以及节点读写调用记录。
- 日记与回复：按会话保存日记，以日记本视图阅读，并从侧栏回复。
- 节点附件：存放图片和文件，按工作区选择按需或必须读取附件。

完整使用手册 · 版本变更记录 · GitHub Releases

问题

你把一件事讲清楚了，下一段对话它还是不知道 —— 或者更糟，它以为知道，而那条已经过时了。

这不是上下文长度的问题。在一个工作区里实测过：

$ node report-kb-use.mjs
50 tool call(s) in the log, 1 session(s)
写 13 次（ops / …）
读 1 次（read-animation） ⚠ 先写后读：第一次写入之前没有读过

写进去 13 次，读出来 1 次 —— 而那次读的还是另一个库。知识被记录了，而没有被用。记录是免费的：模型顺手就写了。用才是难的 —— 要用它，得先知道它存在，还得知道哪一条现在还算数。

它哪里不一样

这不是"带搜索框的笔记应用"。四个决定，其余都是它们的推论。

一、触发器行，而不是向量索引

每个节点正文的最后一行写它什么时候适用：

什么时候该想起它：<这个节点适用的情形>

按需模式下，系统提示携带标题、层级和触发器等索引信息，正文由模型调用工具读取；全文模式则会注入正文。触发器的作用是：

- 没有嵌入、没有向量库、没有相似度阈值。 检索是模型在判断，而它判断的依据是一句人写的话
- 一个节点能不能被找到，取决于写它的人有没有说清"什么时候"。 这就是全部的赌注：知识库难的不是存，是被查阅；而被查阅是写法的性质
- 没写的节点会被标出来。 索引里显示 （无触发器），而写工具在你写下的那一刻就告诉你 —— 因为一个全是找不到的节点的库，看起来和一个健康的库一模一样

二、索引是一棵树，不是一堆片段

父子关系本身是信息 ——"这条属于那个主题"。索引按层级展开，所以模型读到的是一套结构，而不是一把碎片。一个全是平级的库也是好库；而一个什么都不挂在任何东西下面的库，通常是失误。

三、审核标记在每一种模式下都保留

模型做的每处改动带 [新增] / [修改] / [已废弃]，直到你审过。全文注入时也保留 —— 而那正是最容易丢的地方，也确实丢过：一个测试会话发现它分不出哪些段落还没被审。

四、它会告诉你到底有没有用

report-kb-use.mjs 读插件的 activity.log，回答：这个会话里读了几次、写了几次、以及第一次写入之前有没有读过。上面"问题"里那个数字就是这么来的 —— 也是这个插件不声称任何它没量过的东西的原因。

装

npm（推荐）：包名 dsh-knowledge-canvas，在 DSH 的「添加插件」里填它。

手动安装时，在对应profile目录执行 pnpm add dsh-knowledge-canvas@latest，还必须将 dsh-knowledge-canvas 加入该profile的 dsh.profile.bundles（保留已有条目）。仅加入dependencies不会应用插件补丁。安装或升级后重启DSH。

从源码：

// profiles/desktop/package.json
"dependencies": { "dsh-knowledge-canvas": "link:<仓库路径>" },
"dsh": { "profile": { "bundles": [ ..., "dsh-knowledge-canvas" ] } }

本仓库、发布包与前端模块注册名均使用 dsh-knowledge-canvas。内部 Cordis id、标签页标识、路由及数据目录保留旧标识以兼容现有数据；不要把这些内部标识当成安装包名。

面板上能做什么

认位置

| 位置 | 是什么 |
| 顶上那排 | 搜索框、已读计数、刷新 |
| 每个库一行 | 标题、已读进度、一个开关（这个会话读不读它）、⋯ 菜单（改名、删除、颜色、导出） |
| 画布工具栏 | 缩放、适应、宽度（整库默认宽度，不是单个节点）、形状、颜色、布局 |
| 左下「定位到…」 | 输入 id 直接跳到那个节点，不用肉眼找 |

手势

| 动作 | 结果 |
| 单击节点 | 打开编辑器；再点一次关闭 |
| Enter / 空格（聚焦时） | 同上，键盘可达 |
| Shift+Enter | 开始连线；在目标上按 Enter 完成 |
| 拖动节点 | 移动；位置写进 layout.json |
| 按住约 0.26 秒再拖 | 画关联线（橙色），不是改父子关系 |
| Alt + 拖动节点 | 把目标变成它的父节点（灰线） |
| 右键节点 | 菜单：新建子节点 / 看修改历史 |
| 右键空白画布 | 菜单：新建父节点（顶层） |
| 拖出画布到输入框 | 把这个节点交给对话 |
| 节点右下角三个把手 | 改宽、改高、同时改 |

节点宽高有三层含义：这个节点的宽度 → 整库默认宽度 → 画布缩放。工具栏那个「宽度」改的是第二层。

视图与布局

四种布局：分层、放射、阶梯、紧凑。切换布局重算默认摆放，手动位置仍由你控制。

点标题箭头或右键菜单可折叠子树；嵌套折叠会保留，搜索、定位和未读跳转会展开目标的祖先路径。工具栏支持全部展开，以及主动整理可见节点。折叠只改变画布显示，不限制模型读取或注入。

长文正文可独立滚动，并提供编辑入口。缩小到只显示标题时，悬停或聚焦节点会出现阅读预览。

模型工具

| 工具 | 用途 |
| knowledge_read | 读一个库或一个节点；不给 base 时列出所有库 |
| knowledge_create_base | 建库，自带一个根节点。建完立刻可用，不需要再 knowledge_select |
| knowledge_write_node | 写或改一个节点。返回里带着刚建出来的节点 id，可以直接拿它当 parent |
| knowledge_link | 连两个节点，必须写一句"为什么相关"，那句注释会出现在对方的视图里 |
| knowledge_unlink | 断开一条关联；节点不动，只去掉那条虚线 |
| knowledge_remove_node | 标记移除（不删数据，可还原） |
| knowledge_select | 开关某个库对本会话是否可见 |
| knowledge_remove_base | 把一个库标记为移除（可恢复，不是删文件） |
| knowledge_show_images | 把一个节点挂的图片作为图片交给模型（按需模式下可单独调用；必须读取模式随节点返回图片） |

为什么是这个形状：模型拿到的东西必须可核对。每个节点的正文最后一行写「什么时候该想起它：…」，那一行被抽出来放大纲里 —— 所以模型按场景匹配，而不是按向量相似度猜。它读错了，你能在画布上直接看见并改掉。

设置：按工作区

设置 → 知识库，每个工作区一块：

- 这个工作区的路径（一眼确认你在改哪个）
- 记录调用过程 —— 打开后模型每调一次工具都会记一条，面板顶上显示「正在检索 n3（知识库插件的教程）」。默认关。
- 每个库一个 按需索引 / 全文注入 选择（前者给标题和要点，后者把正文也塞进去）；面板上那一行的开关是另一件事:这个会话读不读它

每个库有全文或按需的默认方式，单个节点可在编辑器或右键菜单中选择覆盖或跟随默认。覆写按工作区共享，仅作用于所选节点。按需索引仍有上下文成本；全文额度和超额行为见使用手册。附件读取策略独立设置。

工作区列表 = 会话里出现过的目录 ∪ 磁盘上有 .dsh-knowledge/ 的目录。后者从 $DSH_HOME/sessions/ 的目录名还原（那里每个会话一个目录，名字就是工作区路径，分隔符换成了 -），所以重启之后不会只剩一个工作区。

日记模式（可选）

给不想整理笔记、只想有人记得的人。面板顶上打开，按会话生效。

打开之后，那个会话在聊到一个段落时会自己写一篇 —— 写到属于它自己的那个库，不按天，也不在别的会话里写。

- 每个会话一份 diary-<哈希>.json。开关是会话级的，数据也是：同工作区的另一个会话既看不到它，也读不到它。
- 落盘是密文（AES-256-GCM）。模型 cat 那个文件只会看到 base64。
- 提示词只给约定，不给口吻。 人设由你的预设决定，插件不替你写信。

日记默认以日记本视图打开，支持按月目录、前后篇切换和修改记录；需要编辑时可切回画布。书页底部可直接回复，回复会连同该篇的正文节选送入当前会话，不替换聊天输入框中的草稿。回复记录与日记正文分开保存。

它不做什么

边界比功能更该写清楚：

- 不是聊天记录。 它不自动记录对话，只记你或模型显式写进去的东西。
- 不同步到云端。 全部在 <工作区>/.dsh-knowledge/ 下，普通 JSON，可以用记事本打开、提交进 git、整个拷走。没有账号、没有服务器。
- 日记的加密挡的是"顺手看见"，不是"想读的人"。 密钥由库名派生，读过这份源码的人可以解开。要挡住会翻文件的模型，需要密钥不落盘（口令或系统凭据），那是另一个设计。
- 不替你写人设。 日记模式注入的是一段写作约定，不是语气。
- 不做全文检索。 搜索框搜的是标题和正文的子串，没有倒排索引，也没有向量。

文件长在哪

<工作区>/.dsh-knowledge/ ├── <库 id>.json 每个库一个文件：节点、连线、seed 指纹 ├── selection.json 这个工作区默认读哪些库、怎么注入、记录调用过程 ├── layout.json 位置、宽度、形状、颜色 ├── .sessions/<id>.json 这一个会话自己的开关（含日记） └── activity.log 工具调用记录（仅当「记录调用过程」打开）

- 宿主（index.js、lib/）负责：注入点、工具、路由、种子教程、日记约定。
- 面板（client.js）负责：画布、手势、编辑器、设置页。它直接读这些 JSON 文件，不走宿主的接口 —— 所以"面板看不到某个库"时，先查它自己读到了什么，而不是查宿主。
- 大纲在每次模型调用前组装，只放标题、要点和触发行；正文要模型主动 knowledge_read。

给改代码的人

- npm run check:all 跑四样：标识符、精灵图宽高比、公开树检查、以及存储/路由/工具三层断言（数目以运行输出为准）。
- 改了手势，就改教程里对应那句（lib/seed.js 顶层的操作表），否则教程会描述一个不存在的操作。
- 旧工作区的教程按内容认（谁的节点 id 与种子重合过半，谁就是教程），不是按文件名 —— 这一条是被三个工作区用三种文件名教育出来的。

第一次用

① 装完重启一次 → 侧边栏出现「知识库」 ② 展开「怎么用这个知识库」→ 那就是教程，讲的就是这个面板 ③ 随便找一段对话，跟模型说:"把刚才的结论写进知识库" → 它会调 knowledge_write_node，节点出现在画布上 ④ 在画布上拖动它、给它连一条线、改一遍正文 ⑤ 下一段对话里问它一件旧事 —— 如果它读了，面板顶上会出现「正在检索 xxx（id）」（这需要先在设置里打开「记录调用过程」）

判断它有没有用的那个数字：node report-kb-use.mjs —— 它数日志里"写了几次、读了几次"，以及第一次写入之前有没有读过。

常见问题

面板里看不到某个库。 先看那个库的开关，再看你所在的会话有没有自己的开关（面板顶上「开关作用于 默认 / 仅本会话」）。会话级的列表是一份快照；新建的库会被自动补进去，但手工关掉的不会自己回来。

日记在别的会话里也能看见。 不该。日记按会话隔离，四层都过滤：大纲、面板、工具、以及提示词。如果还看得见，查那个会话的 .sessions/<id>.json 里 diary 是不是 true —— 那份文件属于那个会话，它看见了就是它开着。

改完代码没生效。 分两半：改的是 client.js（面板）→ 刷新页面，必要时硬刷新；改的是 index.js / lib/（宿主）→ 重启 DSH。混在一起猜会浪费很多次重启。

发布之后 registry.npmjs.org 上查不到新版本。
npm 的自动审查没结束，版本状态是 Validating。这期间 tarball 是 404 —— 404 不等于没发出去。等它变成 Published 再判断。

教程没更新。 教程只在工作区第一次使用时种下，之后靠"种子版本"和"内容指纹"升级；而且它按内容认教程（节点 id 与种子重合过半的就是它），所以你把那个库改了名也不影响升级。

开发

npm run check:all # 4 项检查 + 断言全绿

改 index.js / lib/* 后必须重启 Harness（宿主那一半在进程启动时加载一次）；改 client.js 后刷新页面即可。

许可

MIT

附件

节点的正文下面可以挂文件：粘贴截图、拖进虚线框、或者点「＋ 添加附件」选。图片直接画在卡片里（限高 160 px，点开看原图），其它文件显示成 📎 文件名，点开在新标签查看。

附件按内容存放在 .dsh-knowledge/assets/，同一份文件挂两次只存一份。在 DSH「设置 → 知识库」中，每个工作区可选择附件读取方式：

- 按需读取（默认）：knowledge_read 返回节点正文和附件清单，不自动发送图片或附件正文。模型可用同一工具的 attachment 参数读取指定附件；文本支持 offset / limit（字符数，每次最多 8,000）。图片也可使用 knowledge_show_images。
- 必须读取：读取节点或整库时自动返回可解析的文本、Office 内容和图片。每份文本最多 8,000 字符，每次最多 6 张图片；超过限制会提示续读方式。图片会增加视觉 token 消耗，选择此模式不会保证模型一定理解或采用附件。

此选项独立于「全文注入／按需索引」，不会把图片自动塞进系统提示词。PDF、压缩包等尚不支持文本提取的附件会列出路径；缺失文件或图像传递失败会明确提示。手动把节点拖进对话时，仍按会话附件发送，不受该工具设置控制。

例如：knowledge_read({"base":"notes","node":"n1","attachment":"assets/0123456789abcdef.txt","offset":8000,"limit":2000})。附件必须由该节点引用，不能读取任意路径。