@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	列出节点与依赖（可按 focusId 看一跳邻里）	只读
kn_find_node	按标题/别名查（判重、找复用）	只读
kn_read_node	读一个节点的正文与关系（含"为什么依赖"、出处）	只读
kn_enter_node / kn_back	进入前置 / 返回上一层（学习栈）	会话内状态
kn_write_note	写正文（带内容指纹冲突守卫，绝不静默覆盖）	写
kn_add_prerequisite	记一条前置（必要时建点；命中相近候选会先要你确认）	写
kn_propose_prerequisites	一次提案多个前置（只写计划文件，不建点）	写计划
kn_plan_status	查提案状态（落地了哪些、有没有失败）	只读
kn_status	自诊断（路由是否注册、缓存/扫描指标、隔离判定留痕）	只读

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

界面

• 右侧栏「知识库图谱」：所有工作区可见 ✓。顶部只有「重新整理 / 刷新」两个按钮 （库名与计数不再显示：库必然在当前工作区的 .dsh_knowledge 里，属冗余信息 ✓）。
• 建节点：面板空白处右键 → 菜单「创建节点」。（不再有双击建点：那是右键菜单坏掉时的临时兜底，已移除 ✓。）
• 加前置：右键节点 → 「添加前置节点…」（2–3 条推荐 + 搜索）。
• 删依赖：右键连线 → 「删除这条依赖」。
• 删节点：右键节点 → 「删除当前节点」→ 确认后直接删掉那个 .md（不可恢复 ✓）。 节点就是一个文档，所以没有回收站、也没有墓碑：想留底就自己复制一份 .md ✓。
• 提案审阅：agent 提交的提案显示在图上方的审阅区，勾选后点「落地」；已落地的可以「撤销」 （把这次新建的节点删掉 ✓ —— 落地时它们是空节点，所以不会丢内容 ✓）。
• 只有空间视图（三维）。聚焦（二维）视图按需求已整体移除 ✓。

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

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

• 面板自身可见性由 IntersectionObserver 判断：收起侧栏、被覆盖、零尺寸时 ⇒ 不取数、不渲染三维 （requestAnimationFrame 一起停 ✓）；
• 切换标签页即卸载（keepMounted: false）✓；
• 取数有请求序号 + AbortController：切换工作区/刷新时旧请求被取消，过期响应不会覆盖新数据 ✓；
• 划词浮条先判断有没有选中文字，没有就一个请求都不发（普通点击、拖拽结束不再打扰宿主 ✓）。

安全边界

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

安装

profile 的 cordis.patch.yml 插入本插件（@local/dsh-knowledgenet）。 插件零运行时依赖（第三方代码内联），安装时不执行任何脚本。

开发

node build.mjs                 # 构建宿主 + 客户端两个半
node --test "tests/*.test.mjs" # 全部测试
node scripts/sync-vendor.mjs --check   # 上游副本必须逐字节一致（77 个文件）

• 上游（src/vendor/upstream/**）是逐字节冻结的开放格式实现：只读、不手改； 需要改行为时用 build.mjs 的 needle 补丁，或写在自己模块里。
• 类型体检：node_modules/.bin/tsc --noEmit --ignoreDeprecations 6.0 -p tsconfig.json。 目前有约 85 条既有类型宽松（never、缺 @types/node 等）—— 建议当棘轮用： 只看你这次改动有没有引入新错误（它抓过"本地函数漏定义"这类构建不报、运行时才炸的问题 ✓）。

已知取舍 / 尚未实现

• v2 兼容代码仍在源码里但不可达（loadLibrary 只认 v3）⇒ 可以整体删除，属机械清理。
• 一个工作区一个知识库（固定的 .dsh_knowledge/）；多库、跨工作区共享尚未实现。
• kn_list_graph 一次返回整张图（默认上限 400 节点）；大库分页未做。
• 三维视图为上游实现（构建期补丁注入四元数 trackball）；标签密度等仅有固定策略。