dsh-knowledgenet-plugin

@local/dsh-knowledgenet

把本地知识图谱接进 DSH：一个节点就是一个 markdown 文件，节点之间记「前置依赖」， 用右侧栏的「知识库图谱」面板看全局、随手补点，用 kn_* 工具按需读取学习节点、按纪律写。

它是什么 / 不是什么

• 是：DSH 的一个插件。给每个工作区提供一个知识库（工作区里的 .dsh_knowledge/），

以及一组让模型读写这个知识库的工具。

• 不是：通用笔记软件，也不是把工作区变成"知识库工作区"的开关 —— 任何工作区都可以有知识库，

有没有完全由"目录里有没有 .dsh_knowledge/"决定。

存储格式（v3，一节点 = 一个 markdown）

<工作区>/.dsh_knowledge/
  library.json          { formatVersion: 3, libraryId, title, createdAt, storage: "single-file-markdown" }
  Nodes/注意力机制.md      ← 一个节点 = 一个文件
  Nodes/注意力机制-2.md    ← 允许同名，自动加后缀
  graph.json            { revision, edges: [ A → B + 为什么 + 出处 ] }

节点文件长这样 —— 头部是元数据，正文就是笔记本身：

---
id: 01M3NHE78B55MHMDQ9D192MXAM   ← 唯一标识（ULID）：**永不随标题或文件名变化**
title: 注意力机制
status: todo                      ← todo | learning | done
aliases: [Attention, 注意机制]
createdAt: 2026-09-29T03:00:00.000Z
updatedAt: 2026-09-29T03:05:00.000Z
rev: 2
---

这里是正文，随便写；用编辑器直接改也不会坏（front-matter 之后的都是正文）。

身份与名称彻底解耦

你做的事 · 结果 改 title: · 身份不变，关系不断 ✓ 重命名文件（注意力机制.md → Attn.md） · 身份不变，关系不断 ✓（面板按 id 找） 建两个同名节点 · 两个不同身份 ✓（标题.md / 标题-2.md） 手工丢一个没有 front-matter 的 md 进 Nodes/ · 先给临时身份（adopted-…），首次写入时固化成正式 ULID ✓

不兼容老格式（v2）

老格式（一节点一个文件夹 + .meta/knowledgenet/node.json + 每个节点一份 relations.json） 已不再支持 ✓。遇到它时不给含糊结果，而是明确报错：

unsupported_format：这个知识库是老格式（formatVersion=2），当前版本只支持新格式…
请把 <库根> 整个删掉，然后在面板里点「知识库图谱」重新创建。

迁移方式：删掉那个目录 → 打开「知识库图谱」→ 自动建一个新的 v3 库（空库，不会动工作区其它文件）✓。

库 ↔ 工作区

• 任意工作区都可以有一个知识库，位置固定为 /.dsh_knowledge/ ✓。
• 打开方式：右侧栏「知识库图谱」标签页（所有工作区都可见 ✓）。第一次打开若还没有库，

会静默创建一个（不弹窗、不问问题 ✓）；已经有的直接显示。

• 会话 cwd 在库的子目录里也能向上找到库 ✓。
• 也可以在工作区之外用配置固定一个库（cordis.patch.yml 的 libraryRoot）。

「看不到插件」是怎么做到的（隔离）

没有知识库的工作区：kn_* 工具对该会话被 restrict 移除、协议提示词渲染为空 ⇒ 模型完全看不到插件 ✓。有知识库的工作区才可见 ✓，而且建库后当前会话立刻放开 （不用等下一个会话 ✓）。

工具

工具 · 作用 · 读写 kn_list_graph · 默认聚焦一跳；学习时可自主选择 overview 查询全库结构，正文不随结构返回 · 只读 kn_find_node · 按标题/别名查（判重、找复用） · 只读 kn_read_node · 分页读目标正文、理解标记和关系计数；关系显式请求 · 只读 kn_current_node · 查询活动视图聚焦、首轮入口或历史目标的身份与理解标记，不返回正文 · 只读 kn_enter_node / kn_back · 进入前置 / 返回上一层（学习栈） · 会话内状态 kn_write_note · 写正文（必须带 `userConsent: true`，且带内容指纹冲突守卫，绝不静默覆盖） · 写 kn_add_prerequisite · 记一条前置（必要时建点；命中相近候选会先要你确认） · 写 kn_propose_prerequisites · 一次提案多个前置（只写计划文件，不建点） · 写计划 kn_plan_status · 查提案状态（落地了哪些、有没有失败） · 只读 kn_status · 自诊断（路由是否注册、缓存/扫描指标、隔离判定留痕） · 只读

写入纪律（写进系统提示，模型必须遵守）：搜索类请求不得调用写入工具；建点前必须说明并等你同意； 一轮最多一次 kn_add_prerequisite；要一次处理多个概念只能提案，落地只能由你在面板里点击。

笔记属于你本人（写进系统提示 + 工具硬闸门）：节点正文是使用者记录自己想法的地方， 不是装解释/资料/摘要的框子 ⇒ 解释概念、回答问题、顺手"整理一下"都不是改笔记的理由。 模型只有在你明确要求、或明确同意某个具体改动时才写；写之前要先把"准备写什么、写进哪个节点"说清楚并等你点头。 kn_write_note 少了 userConsent: true 会被直接拒绝（文件一字不动），并回一句"先去问用户"。 换句话说：它只能在你点头之后才写得进去。

笔记用于参考，不是标准答案：插件要求模型把正文、标题和关系当作用户的学习记录，“已理解”也不证明记录正确。模型应核查与当前问题相关的说法，发现错误时指出具体内容、简短解释原因并给出修正；区分错误、简化表达和缺少限定条件。不确定时说明需要核实，分页未读完整时注意后续限定。纠错留在对话里，不自动改笔记、理解标记或依赖关系。kn_read_node 每页明确返回 note.contentRole: user_learning_record；这是一条回答策略和数据来源说明，不保证模型能够发现所有错误。详见 笔记参考与纠错策略。

界面

• 右侧栏「知识库图谱」：所有工作区可见 ✓。顶部只有「重新整理 / 刷新」两个按钮

（库名与计数不再显示：库必然在当前工作区的 .dsh_knowledge 里，属冗余信息 ✓）。

• 建节点：面板空白处右键 → 菜单「创建节点」。（不再有双击建点：那是右键菜单坏掉时的临时兜底，已移除 ✓。）
• 加前置：右键节点 → 「添加前置节点…」（2–3 条推荐 + 搜索）。
• 删依赖：右键连线 → 「删除这条依赖」。
• 删节点：右键节点 → 「删除当前节点」→ 确认后直接删掉那个 `.md`（不可恢复 ✓）。

节点就是一个文档，所以没有回收站、也没有墓碑：想留底就自己复制一份 .md ✓。

• 提案审阅：agent 提交的提案会自动弹出一个悬浮在聊天窗口上的弹窗（agent 一交完就出现：客户端每 2 秒自己拉一次，不等图的刷新 ✓）。

弹窗只有两个出口：勾选后点「创建选中的 N 条」（落地，弹窗立即消失 ✓）或点「取消这提案」（丢弃：弹窗立即消失、永久不再出现 ✓，并让宿主删掉计划文件 ✓；点 × / Esc / 点背景与「取消」同一语义）。 没有「稍后再说」，面板上也没有「待审提案」这种入口 ✓ —— 待审就等于你还没决定，所以下次打开还会弹 ✓。 落地后面板里只留一条10 秒的短暂回执（「已新建 N 个 · 撤销」，可点 × 立刻收起，到点自己消失 ✓ —— 不做长期占位的卡片）。 撤销会把这批新建的节点删掉 ✓（落地时它们是空节点，所以不会丢内容 ✓）；回执消失后要撤掉那几个空节点，用图谱的「删除当前节点」即可。

• 节点笔记编辑器（右键节点或选中条上的「编辑笔记」打开）：打开后以图谱区域内的留边弹窗显示，保留背景图谱和上方工具栏 ✓

（3D 图谱、状态灯、视角图、提示条一起让位 ✓；点 × 关闭即原样回来、镜头不重置 ✓）， 面板够宽时正文收成一条居中的阅读栏 ✓（一行不会拖太长 ✓）； 只有一条标题栏（节点名 + 关闭），高度全留给正文 ✓；没有模式切换，打开就是正文（所见即所得）。 正文比视口短时，下面那块空白也是编辑区 ✓：点它会落到一个末尾空段落（已经有空段落就直接用它，不无脑加空行 ✓） ⇒ 在那儿右键同样能弹出块菜单、插表格 / 公式（不再"点了没反应"✗）。 正文里右键 ⇒ 弹出块菜单 ✓（标题 / 列表 / 引用 / 表格 / 公式 / 图片 / 代码块…）；＋ 块手柄打开的是同一个菜单 ✓， 正文下方空白处右键也是它 ✓（追加到末尾）。条目来自 Crepe 官方 buildMenu 快照 ⇒ 图标 / 文案 / 插入命令与旧斜杠菜单 同源 ✓（中文文案按插件词典，未收录的新条目用 Crepe 原文兜底 ✓）。菜单里只有块插入 ✓ （行内格式统一在"选中文字 → 浮动工具栏"里 ✓，不在右键菜单重复列一遍 ✗ —— 2026-10-22 用户反馈 ✓）。 表格单元格右键仍是表格操作菜单 ✓； 代码块 / 图片、编辑器里的浮动工具（工具栏 / 语言选择 / 表格菜单）以及已选中文字上不接管右键 ⇒ 保留浏览器原生菜单（复制源码 / 保存图片 / 复制文字 ✓）；只读、初始化中也照旧给原生菜单 ✓。 输入 `/` 一律是普通字符 ✓，不再唤起菜单（Crepe 自带的斜杠触发已在构建期关掉 ✓，详见 块菜单改版）。 其余正文排版也跟随 DSH 的 Markdown 渲染 ✓（标题字号/字重/32-16px 外边距、段落 16px、列表间距与 marker、 链接颜色/字重/无下划线、分隔线 0.5px + 32px、加粗 600、图片圆角、首个/末个块外边距）✓；\n 列表序号/圆点与正文垂直居中（标记盒行高 = DSH base line-height ✓）。 字号/行高走 DSH 的 --dsw-font-markdown-* token（跟随 DSH 内容字号设置 ✓）。 表格与代码块保留插件自己的设计 ✓（表头可辨识、代码块工具条；理由见 正文排版对齐）。 打开笔记更快了 ✓：不再固定等 200ms，而是按"代码块/公式 NodeView 真的渲染出来"判定， 纯文字笔记从 ~580ms 降到 ~307ms、含代码/公式从 ~590ms 降到 ~508ms（详见 打开速度优化）； 打开笔记不再"一闪而逝" ✓：富编辑器的过渡首帧（代码块/公式还没换成正式渲染时就先画一遍 ✗） 在渲染稳定前隐藏，稳定后再淡入 ✓；加载提示会一直显示到内容真正就绪 ✓ （详见 首帧渲染）。 引用块样式与 DSH 的 Markdown 渲染对齐 ✓：2px 细竖线（--dsw-alias-label-caption）+ 14px 左内边距 + 正常正文色 ✓ （原来是 3px 粗线 + 整块文字变淡 ✗，用户实测"有点丑"✗；Crepe 自带的 4px 伪元素竖线已隐藏 ✓，只保留 DSH 这一条 ✓）；空段落 / 空引用的输入提示也改成中文「输入内容…」✓ （Crepe 默认英文 "Please enter..." ✗，详见 引用块与输入提示）。 插入项后保留光标前后的原文 ✓：正文 / 标题里在右键处拆出中间的空段落、命令只改它，两侧文字与列表 / 引用结构都保留 ✓； 代码块 / 图片 / 表格这类拆不开的块则在这一块之后插空段落 ✓。 行内格式（2026-10-21 修复"看起来没生效" ✗；2026-10-22 第四轮按"和浮动工具栏重复"从右键菜单里删掉 ✓， 详见 行内格式修复）： 行内代码样式与 DSH 正文的 Markdown 渲染一致 ✓（inline-flex / 0.875em / 0.5px 细边 / 主题行内代码底色 / 小圆角 / 左右 5px 内边距 ✓，2026-10-22 用户要求）。 统一走「选中文字 → 浮动工具栏」 ✓ —— 右键菜单里不再重复列一遍行内格式项 ✗（用户反馈 ✓）； 浮动工具栏提供 加粗 / 斜体 / 删除线 / 行内代码 / 行内公式 / 链接 / 清除文字格式 ✓， 这些动作绝不拆开段落 ✓、两侧文字原样保留 ✓；快捷键（Ctrl/⌘+B / I 等）照旧可用 ✓。 链接弹的是中文输入框（"粘贴链接…" ✓），粘贴 / 输入 URL 回车即插入 ✓。 「＋ 添加前置节点」也并进了同一条工具栏 ✓（第 8 个按钮， 点它关系面板直接以选中原文预填打开 ✓）—— 原来它是一块贴着选区的独立浮钮，会和格式化工具栏 互相遮挡 ✗（2026-10-22 用户截图），现在选区旁只留一条工具栏 ✓。 工具栏图标改成主题文字色（原来用的边框色，截图里几乎看不见 ✗）✓；行内公式的编辑小浮窗也重新主题化了 ✓： 确认按钮按文字自适应宽度、不再把「完成」挤成竖排 ✗（用户截图 ✓），点「完成」后浮窗会自动收起、焦点回正文继续输入 ✓（不再一直挂着 ✗）；选中文字时右键仍保留浏览器原生的复制 / 剪切菜单 ✓。 没有保存按钮：改完按 Ctrl / ⌘ + S 保存（提示挂在标题栏悬停里）； 未保存时节点名右上角有个 *，保存中转成「正在保存…」，保存失败与冲突另有提示条与重试入口 ✓。 保存完成后光标与焦点留在原处 ✓：保存期间编辑器会短暂切只读（浏览器会把焦点移走 ✗）， 现在结束后自动还给正文 ✓ —— 不用再用鼠标点一下才能继续写 ✓（前提：保存期间没把焦点点到别的控件 ✓）。 正文里若有富编辑器保不住的语法（原始 HTML、脚注、指令等）自动改用纯文本编辑、原文一字不动 ✓； 想回正文需显式点一次「仍要用正文编辑」，把那些语法删干净后会自动回正文 ✓。 提示按实际模式说 ✓：还在正文模式时只说明"这里有保不住的语法、保存时这一处可能被改写"， 只有真的切到纯文本才说"已改用纯文本编辑"（不再"没切换却说切了"✗）。 代码块复制会带上块结构 ✓：点代码块的「复制」同时写入裸代码（粘到终端 / IDE 照旧 ✓）、 转义后的 ` ✓，以及本插件自己的一份载荷 ✓ —— 在本插件正文里粘贴时会**还原成一个完整代码块**（语言、缩进、空行、 一字不改 ✓， 一次撤销回到粘贴前 ✓）；在已有代码块里粘贴仍然只插字符、不嵌套新块 ✓， 从别处复制的**普通** Markdown / HTML（不包含代码）继续走原有粘贴 ✓。 **手动选中复制 = 纯文本** ✓（2026-10-22 用户要求）：在代码块 / 公式块里**手动划选文字**复制， 粘回来就是**纯文本** ✓（不再自动还原成块 ✗）；只有点右上角「复制」按钮才是结构化复制 ✓ （粘贴还原完整代码块 / 公式块 ✓）——两种复制语义互不串 ✓（详见 复制语义拆分）。 **从别的应用复制代码粘进来**（剪贴板只有纯文本 / 网页 的情况）也会**自动插成完整代码块** ✓， 不再被当成 Markdown 拆散（#include` 不再变原始 HTML、不会因此整篇被踢进纯文本 ✗， 详见 粘贴与引用块健壮性）。 代码 / 公式块不再像 IDE ✓：活动行浅底只在聚焦时显示（点块外空白即消失 ✓）； 选中文字时活动行灰条让位、点旁边任意区域（包括不可聚焦的标题区）选区都会折叠消失 ✓； 选中文字时也不会再出现 CodeMirror 默认的绿色"选中匹配"方块 ✓ （详见 代码块活动行与选中匹配）。 引用块能退出 ✓：光标在引用段落最前面按 Backspace（或最末尾按 Delete）⇒ 空引用直接删掉、 单段落引用拆掉引用壳但保留文字 ✓（不再有一条清不掉的竖条 ✗）。

• Mermaid 图块：正文里的 mermaid 围栏渲染成图（文件里仍只有围栏源码，不落 SVG / HTML ✓）。

打开笔记默认「只看结果」✓，图悬停出「复制为代码 / 下载图像」✓（下载优先 PNG，画不出来就退回 SVG ✓）； 点「编辑源码」可改围栏内容 ✓。渲染失败时图的位置显示失败原因，源码照旧可编辑、可复制 ✓。 公式块/预览型代码块：插入后直接进源码编辑区 ✓，首次输入不会把编辑区自动收起 ✓（只修"空块输入首字就切预览"这个上游行为 ✗，详见 公式块首字修复）；面板在 shadow DOM 里也验证过 ✓（document.activeElement 只是 host ⇒ 补丁按 shadow-aware 焦点判断 ✓）；点「只看结果」才看渲染 ✓。 代码块 / 公式块的上下留白已收紧 ✓（用户实测"占据太宽"✗）：外边距统一 8px ✓、代码块工具条 26px ✓； 公式块的「复制 / 只看结果 / 编辑源码」改成悬停浮层 ✓（不再常驻占一行 ✗）—— 公式块从 ~88px 收到 ~31px ✓ （详见 紧凑块与保存焦点）。 语言列表里补了 mermaid 一项（没有语法高亮，纯文本编辑 ✓），新建块、粘贴含 mermaid 围栏的 Markdown 都可用 ✓。 浅色 / 深色、中文字体跟随宿主主题 token 与正文 ✓；一页多张图各自渲染、互不串 ✓。 渲染器本体是按需加载的（client.mermaid.js，见下）：页面启动不再背 6.8 MB ✓， 第一次打开含图笔记时才从宿主路由取运行时 ✓；加载失败会明确提示「重启 DSH 或重装插件」✓。 源码里的 %%{init}%% 中 themeCSS / htmlLabels 会被收窄（防止外部资源 / HTML 标签 ✓）， 其余 init 配置照旧生效 ✓。细节与实测见 设计记录。

• 打开有多快：读正文不再扫全库 ✓ —— 宿主按"节点身份 → 文件路径"的索引只读目标文件

（图谱/工具刚扫过的结果会直接喂给索引，所以通常一个文件都不多扫 ✓）， 接口的格式检查也只看 library.json 一个小文件 ✓（不再顺手加载整个图谱 ✗）； 索引可以活很久 ✓（每次读都现场校验身份 + 一次 readdir 的目录变动检测 ✓）， 建索引时每个文件只读头部 4KB ✓（只取 front-matter 的 id、不读整篇正文 ✓；头部不够会自动退回读整份 ✓）， 冷启动的扫描与建索引都是有界并发 ✓（不再一个文件一次串行往返 ✓）； 保存前仍然现场读磁盘文件比对指纹 ✓，缓存不参与判定 ✓。 界面上两段提示是分开的：读取阶段只说「正在读取笔记」，组件真的挂载后才说「正在准备编辑器」✓ （kn_status 里 status.docReads 记宿主走了 index / index-miss / full-scan 与毫秒， status.noteApi 记接口端到端耗时（含根目录解析与格式检查 ✓）， 客户端记 note-open-start / -loaded / -ready 并带同一个 requestId ⇒ 两端可对齐 ✓， 卡在读盘还是卡在编辑器创建一眼可辨 ✓）。

• 保存 / 关闭 / 再打开：未保存时关闭或切节点会问一次，按钮写明动作（「保存并关闭」/「保存并切换」）✓；

保存确认后先同步落缓存、再通知离开 ⇒ 重新打开直接显示刚保存的正文， 不会再把自己的保存当成"文件在外部发生了变化"✓。"磁盘基线"与"编辑器快照"分开存： 宿主落盘会去掉末尾空白、编辑器输出会补回末尾换行，这类编辑器自己的写法不算未保存修改 ✓ （真的改了内容 —— 包括行首缩进与空行 —— 照旧算 ✓）。真冲突仍受保护，但默认只有一句话 +「比较修改」， 点开才分栏比较「我的修改」/「文件最新版本」，且只对差异行做局部标注 ✓。

• 表格：就是文档里的普通表格 —— 没有常驻的十字线 / 加号 / 行列抓手，划过单元格也不会点亮整行整列；

点击落的是原生文字插入光标（编辑器不再装虚拟光标，颜色跟随正文 ✓）。Crepe 自带的表格节点视图会 接管单元格点击、并异步地选中整段 ✗ —— 插件在事务派发这一层（所有选区变化的唯一漏斗 ✓） 把它改写成离点击最近的文字位置 ✓：点击后是折叠光标、输入只插入、原有文字不被替换 ✓， 也不会被上游那次 scrollIntoView() 拽动正文 ✓。 光标进表格、或鼠标悬停表格时，表格角上会出现一个带文字的小入口「表格操作」✓（只读 / 保存中保留但禁用 ✓）； 入口纵向跟着当前单元格 / 正文可见区走 ✓ —— 长表格往下滚时它不会留在早已滚出视口的表格顶部被裁掉 ✓ （表格整个滚出视口时明确收起 ✓，菜单也保证整块落在正文视口里 ✓）。 入口就贴在当前单元格的右上角 ✓，而且是在格子外面（纵向放在这一格上方、横向贴它的右边 ✓）， 所以不会挡住你正在编辑的那一格 ✓；这一格就在可见区最顶上、上面也放不下时， 它会先退到"表格顶部之外"，实在没地方才压回格子角上并收成 22px 小图标 ✓（尽量少挡 ✓， 仍然半透明、悬停显示「表格操作」✓）。 定位用的是正文表格本身 ✓ —— Crepe 在正文表格前面还放了一张隐藏的拖拽预览表， 按"块里第一张 table"取会拿到那张零尺寸的预览表、入口就永远不显示 ✓； 现在按"排除预览表 + 必须在 table-wrapper 里 + 必须有尺寸"过滤 ✓（有光标单元格时直接用它所在的表格 ✓）， 收起时也会说明是「没找到正文表格 / 尺寸为零 / 滚出视口 / 放不下」哪一种 ✓； 多表格时鼠标悬停的那张优先 ✓，菜单打开期间锁定目标表格 ✗（不会跨表格误操作 ✓）。 表格在阅读栏里横向居中 ✓（短表格不再贴左 ✓；比可视宽度还宽时 auto 外边距按 0 处理， 仍然从左开始、由表格外层横向滚动 ✓，不会出现"左边那截滚不到"✓）。 点开才是完整菜单，一共十三条：上/下插行、左/右插列、左/中/右对齐、上移/下移本行、左移/右移本列、 删本行、删本列 ✓。移动是整体搬整行 / 整列（内容、对齐、列宽都跟着走，可撤销 ✓）； 到边界、表头行、多行多列选择或有合并单元格时会禁用并写出原因 ✓。Esc 关掉并回到正文、键盘也能用 ✓ （面板跑在 Shadow DOM 里：判"点的是不是菜单内部"用 composedPath + 节点引用 ✓，点菜单项不会被当成点外面 ✓； 打开菜单会把焦点放进菜单 ✓，↑/↓ 与 Esc 才真正生效 ✓）。 多单元格选择的底纹是低对比的 10%，复制矩形区域照常可以 ✓，拖列宽的手柄也还在 ✓。

• 只有空间视图（三维）。聚焦（二维）视图按需求已整体移除 ✓。

滚轮不再让视角前进 ✓（整套"滚轮 → 相机沿视线移动"逻辑已删 ✓），拖动旋转 / 平移 / 双击定位照旧 ✓； 右下角那张「视角位置图」（两张圆形投影图）也一并删除 ✓（用户要求，详见 空间视图删滚轮与位置图）， 底部提示语已同步去掉"滚轮靠近" ✓。

后台开销（桌面端流畅度）

面板只在真的看得见时工作 ✓：

• 面板自身可见性由 IntersectionObserver 判断：收起侧栏、被覆盖、零尺寸时 ⇒ 不取数、不渲染三维

（requestAnimationFrame 一起停 ✓）；

• 切换标签页即卸载（keepMounted: false）✓；
• 取数有请求序号 + AbortController：切换工作区/刷新时旧请求被取消，过期响应不会覆盖新数据 ✓；
• 划词浮条先判断有没有选中文字，没有就一个请求都不发（普通点击、拖拽结束不再打扰宿主 ✓）。

安全边界

• 库根必须存在、且写操作不越出库根（路径守卫，拒绝 .. 与绝对路径）。
• 写正文用内容指纹做乐观并发：外部编辑器改过就拒绝，并回传实际指纹。
• 关系写在 graph.json：加边幂等、自环与成环拒绝；删节点会摘掉它的边。
• 提案的落地/撤销只有界面能触发，agent 无法自己落地 ✓。
• 删除是彻底删除（无回收站、无墓碑文件）；Backup/ 与 .knowledgenet/ 都已随该决定移除（老库里若还留着，可以手动删掉 ✓）。
• 旧格式（v2）库不会被动过：只会报 unsupported_format 并告诉你怎么办 ✓。

安装

profile 的 cordis.patch.yml 插入本插件（@local/dsh-knowledgenet）。 插件零运行时依赖（第三方代码内联），安装时不执行任何脚本。 发布产物：index.js（宿主）、client.js（客户端主包）、client.mermaid.js（按需加载的 Mermaid 运行时 ✓）、 cordis.patch.yml、icon.svg、locale/*.json。 安装包只包含上面这些发布产物 ✓（package.json 的 files 白名单 ✓，实测 npm pack 只打 9 个文件 ✓）—— 仓库里的 src/、tests/、scripts/、tools/、build.mjs、design/ 是开发内容 ✓，不会发到用户机器上 ✓ （所以它们留在 git 里不影响安装 ✓；要自己构建 / 跑测试见下面「开发」✓）。

开发

node build.mjs                 # 构建宿主 + 客户端 + 布局 Worker + Mermaid 运行时（四个产物）
node --test "tests/*.test.mjs" # 全部测试（当前 909 个，全绿）
node scripts/sync-vendor.mjs --check   # 上游副本必须逐字节一致（77 个文件）

浏览器端到端测试（需要 DSH 源码/依赖仓库里的 playwright 与 rolldown）：

$env:KN_PROJECT='D:/AppInstallation/DSH/deepseek-harness'
node --test tests/mermaid-note.browser.mjs   # Mermaid 图块（14 个：图 / 复制 / 下载 / 输入保护 / 缓存 / 安全 / 运行时缺失）
node --test tests/current-note-focus.browser.mjs   # 焦点与当前节点
node --test tests/block-menu.browser.mjs   # 右键块菜单（真 client.js + 宿主 Menu 契约替身）
node --test tests/inline-format.browser.mjs   # 行内格式（真实面板 UI：浮动工具栏 8 项 / 行内代码样式 / 复制语义 / 公式 / 链接 / 关系弹窗点外关闭）
node --test tests/block-robustness.browser.mjs   # 粘贴/引用块健壮性（外部代码粘成代码块、空引用可删除、误判样本）
node --test tests/node-conversations.browser.mjs   # 节点对话：侧栏标签恢复 / 历史实时更新 / 新建前置（输入后按 Enter）→ 打开笔记 → 创建对话

• 上游（src/vendor/upstream/**）是逐字节冻结的开放格式实现：只读、不手改；

需要改行为时用 build.mjs 的 needle 补丁，或写在自己模块里。

• 单测直接用 node --test 跑 .ts 源码 ⇒ 只能用 Node 类型剥离模式支持的语法（不要写构造参数属性 / enum /

namespace / import =）；tests/node-strip-syntax.test.mjs 会扫全仓拦下新增违规 ✓。

• 类型体检：node_modules/.bin/tsc --noEmit --ignoreDeprecations 6.0 -p tsconfig.json。

目前有约 85 条既有类型宽松（never、缺 @types/node 等）—— 建议当棘轮用： 只看你这次改动有没有引入新错误（它抓过"本地函数漏定义"这类构建不报、运行时才炸的问题 ✓）。

已知取舍 / 尚未实现

• 两个客户端产物：client.js 8.12 MB（回到加 Mermaid 之前的量级 ✓）
• 按需加载的 client.mermaid.js 3.43 MB（minified，gzip 916 KB）。实测（headless Chrome，5 轮中位数）

页面启动相对旧产物 +26.9 ms pluginReady / +14.7 ms 可交互（拆分前是 +454.5 / +474.0 ✓）； 代价是每页首次开图多 ~0.21 s（运行时下载+求值），但「页面启动 → 第一张图」反而早 ~0.24 s ✓， 第二张图 / 再打开无差异，不开图的会话每页净赚约 0.43 s ✓。

• 新增宿主路由要宿主半重新加载（重启 DSH，或让插件重新 apply）：client.mermaid.js 由 Host 半注册的

/api/knowledgenet.mermaid.js 提供（同源 ` + 浏览器 cookie 通过 /api 鉴权围栏 ✓）。 node build.mjs 之后：**客户端半刷新页面即可** ✓，**宿主半必须重启 DSH** ✓ （Host 模块走 ESM 缓存，重装插件不保证重新加载新模块 ✗；重启是可靠路径 ✓）； 没重启时图块会显示「Mermaid 渲染运行时加载失败（请重启 DSH 或重装插件）」，源码仍可编辑 ✓。 安装包已把 client.mermaid.js 列进 package.json.files` ✓（git/npm 安装不会漏 ✓）。

• Mermaid 下载：优先 PNG（2× 缩放、铺渲染时的主题底色 ✓）；个别图元 / 老浏览器画不出来时

自动退回 .svg ✓。先切主题再下载旧图也没问题：底色用的是渲染时记下的那一份 ✓。

• 正在编辑的 mermaid 块：图在失焦后才刷新（编辑中先让路，否则异步预览回填会把源码藏起来、

打断输入——真实浏览器实测过 ✗；失焦后立刻回焦继续打字也有保护 ✓）。这是有意取舍，不是"没实现"。

• Mermaid 主题兜底：宿主 token 若换用 oklch / color-mix 等现代颜色语法，

渲染器会用 canvas 采样成 legacy rgb() 再交给 mermaid ✓；万一采样不可用就退回内置浅色兜底 ✓ （图不会渲染失败，但配色可能朴素一点）。

• v2 兼容代码仍在源码里但不可达（loadLibrary 只认 v3）⇒ 可以整体删除，属机械清理。
• 一个工作区一个知识库（固定的 .dsh_knowledge/）；多库、跨工作区共享尚未实现。
• 图谱面板与模型查询分别返回数据；模型节点页、边页和正文页可独立续读。
• 三维视图为上游实现（构建期补丁注入四元数 trackball）；标签密度等仅有固定策略。

笔记弹窗标题栏提供前置、被依赖列表；「＋ 添加前置」已挪进「前置」弹窗里 ✓（使用频率不高 ⇒ 不占标题栏 ✓）， 输入节点名后直接按 Enter 就会创建前置节点 ✓（等价于点「新建「x」并设为前置」✓；中文输入法选词时的 Enter 不会误建 ✓）， 前置 / 被依赖弹窗点旁边空白或按 Esc 会自动关闭 ✓；正文选中文字后仍可从浮动工具栏直接创建前置节点 ✓。 表格结构操作由单元格右键菜单进入，支持删除整张表格并撤销。

图片与理解标记