project-node-memory

dsh plugin --profile web add project-node-memory

project-node-memory

简体中文 · [English](README_EN.md)

把 Markdown 目录当成知识库 的 DSH 插件：为 Agent 提供 10 个 kb_* 工具，为人类提供知识节点面板（侧栏入口名「项目节点知识库」）。

没有索引数据库、没有向量、没有后台进程。完整知识库位于项目下的 .nodekb/ 目录——一堆 md 文件，删掉插件之后它仍然是普通 md。

它能为 Agent 带来什么

Agent 默认靠 read / grep / glob 找东西，代价是试探：grep 到 5 个文件，逐个 read，才发现真正要的只有其中一段。本插件把这层收敛成四件事：

能力 · 对应工具 · 省下什么

先看结构再读正文 · kb_read mode=toc · 一次 ~200 token 的目录视图替代整篇 read

稳定 TID 寻址（doc:03-build:3.1） · kb_read target=… · 不受行号漂移影响；改文件不打断引用

引用就地展开（转写） · kb_read mode=subtree · 一次拿到装配好的上下文，不用手动拼

大节点分窗读 / 找词只要命中行 · kb_read offset/limit/find · 17k 字符的段不用整段吃进上下文

结构自检 · kb_diag · 悬空引用 / 引用位置型段落 / 循环 / 孤儿，改完就查

返回文本体积设上限：mode=subtree 超过 maxlen（默认 50000 字符）会截断到行边界，并在结尾给出 offset= 续读坐标（maxlen=0 仍可强取全量）——不静默丢内容，也不因为「太长」整次调用失败。

怎么让 Agent 真的用它

工具描述只在 Agent 已经决定「我要沉淀知识」时才被读到；要让它优先选这条路，靠四层：

1. 系统提示词段落（默认开，prompt.enabled=false 可关）

每轮都在，规则只有五行：要沉淀就用 .nodekb/ + kb_，别拿 write 手搭 docs/.md。

段落常驻约 450 字，实测 GET /nodekb/api/prompt 可自证是否注册成功。

2. 把「建库」变成一次调用

kb_init 直接铺出 doc/ lessons/ todo/ index/entry.md 与 .nodekb/README.md 里的落位约定（幂等，已存在不覆盖）。没有这一步，Agent 会自己发明目录结构。

3. 写也走工具

kb_write 写前校验 TID / <node> 独占一行 / 路径不越界，写后立刻跑 diag 把悬空引用与重复块报回来。write 没有任何一层会拦，所以规则只能靠记。

4. 随包技能 project-node-memory-guide（按需加载）

提示词段落只有五行，写法规程（文件怎么分、TID 怎么起、先读什么再写什么、三个反例）放在 skills/project-node-memory-guide/SKILL.md——它只留每次都要用的那一小撮（约 5 K 字符），明细在同目录的 references/（syntax / write / diag / cli / rules 五份）按需读。注册时带 resourceBase: { kind: "directory", path }，模型才能按相对路径打开它们（不带的话宿主只会说「资源由 provider 管理」，相对路径无从解析）。

装好即生效，不需要任何手工步骤：宿主 skills 服务可用时插件用 ctx.skills.register() 把正文注册在内存里（不用时零提示词开销，禁用插件即撤回）。skill.enabled=false 可关；GET /nodekb/api/skill 自证是否注册成功。

> 注：DSH 的 skill 文件发现只扫 $DSH_HOME/skills、<workspace>/.dsh/skills 与 preset 里显式声明的路径，不会去扫 npm 包内的 skills/ 目录。所以「把 SKILL.md 打进包」本身不会让它被发现——要么注册进内存（本插件的做法），要么启动时把文件写进用户的 skill 根目录（会在家目录留残留）。

安装

dsh plugin add project-node-memory      # npm 发布后

从源码装（开发用）：

npm pack                       # 产出 project-node-memory-<版本>.tgz
dsh plugin add ./project-node-memory-<版本>.tgz

打包后再 add 那个 .tgz，不要直接 add 源码目录：目录形式装的是 link 依赖，目录被移动或删除后 DSH 会起不来。Host 侧改动需要重启 DSH；面板改动重新安装即热载。

配置

全部可选，写在 cordis.patch.yml 的该行 config: 下：

键 · 默认 · 作用

workspace · 无（自动判定） · 覆盖「工作区」。判定顺序见下；工具侧优先取会话头里的 cwd

libraries · 无 · 名字: 目录，显式登记工作区之外的库（目录下需有 .nodekb/）

registries · 工作区 .nodekb/registry.json + 用户全局注册表 · 额外的 kb_registry.json（与 Python 版同格式）

exclude · 见下 · 库发现时忽略的目录名，支持 * 通配；!pattern 强制放行

prompt.enabled · true · 是否注册系统提示词段落

skill.enabled · true · 是否把随包 Skill 注册进宿主 skills 服务

git · true · 库内嵌 git 快照：每次 kb_write 后自动 commit；false 关掉

advice · { display: true, minFragNodes: 10, fragChars: 500, longSection: 10000, maxItems: 5 } · kb_diag 第三档 advice：display: false 整块关掉，limit 控条数（0 = 不限），其余是阈值

exclude 默认忽略这些名字：tmp、tmp_、temp、.tmp、_probe、nodekb_lab、__pycache__、_release_assets、venv。临时目录、探针目录里的 .nodekb 通常是实验残渣，列进选择器只会碍事。要放行某个目录写 "!tmp_keep"；要额外忽略写 "scratch"（与默认名单叠加）。

config:
  exclude: ['tmp_*', '!tmp_keep', 'scratch']

面板

侧边栏多一个图标（名字「项目节点知识库」），点开是中栏三列（左右两栏的宽度都能拖拽调节，6px 抓手，宽度记在浏览器 localStorage）：

• 左：上半是节点树（标题 · 类型 · 字符数），顶部搜索框回车换成命中列表；下半是图设置——布局（电路板（默认）/ 上下 / 左右）、展开层数、类型筛选（点一下隐藏该类型）、全部展开 / 适应视图。
• 检索态（1.5.10）：命中词在左侧列表里直接高亮；点任一条目，右栏预览换到该节点并滚到第一处命中，检索列表留在原地、可继续点其它条目；右上搜索框右侧的 ×（或 Esc）才退出检索。
• 中：默认是电路板视图（1.5.19）。整块板 = 一个库：一级目录是模块，模块面积按它内含的节点数占全库的比例切（squarified treemap），模块里再递归铺下一层模块，没有子节点的节点画成焊盘（小圆点，只在鼠标悬停时用 <title> 报 tid）；默认铺 5 层，可在图设置或「设置」里改 2–8。点模块（或双击芯片）下钻，面包屑 / ↑ / Esc 回上一级；下钻时板子按原宽高比缩放，所以外形不变、只是放大。模块右上角是节点计数。排线是真实引用（正文里的 [[node=]] / [[tscl=]]，宿主 /tree 一次带回全部边）：颜色取所属节点的类型色，平时 95% 不透明，鼠标移上去该节点连同对端焊盘一起变蓝、其它排线压到 22%。另有「上下 / 左右」的整齐树视图，框宽固定、框高随标题自适应（1.5.11）：标题最多 30 个字符、超出补 …，自动换行最多 3 行，不拆连续单词（pip、ASCII、kb_read 整词换行），收尾标点不另起一行。
• 顶栏「设置」（1.5.19）：板底 / 模块填充 / 排线 / 焊盘四个不透明度、焊盘大小、排线线宽、丝印字号、最大层数，底部一键「恢复默认」。参数只影响显示，存在 localStorage。
• 右：上半是节点内容（markdown 渲染，[[TID]] 可点），下半是节点属性（tid、类型、父、源文件行号、字符数、子节数、被谁引用、文件改名按钮）。「原文 / 源码」两个视图保持等宽纯文本。

图上所有颜色都写在元素的内联 style 里，样式表只留结构与指针样式：SVG 的表现属性（fill= / stroke=）优先级低于任何同名 CSS 规则，而插件热更新时旧的 <style> 可能还挂在页面上 —— 只要有一条 .nkb-bpad circle{fill:…} 残留，整块颜色就会被盖成灰的。

正文的 markdown 是自己写的小渲染器（标题 / 列表 / 代码 / 表格 / 引用 / 强调 / 链接），LaTeX 走 MathML：$…$ 行内、$$…$$ 与 ``math 围栏是独立公式块。不依赖 KaTeX、不带字体文件，排版交给浏览器原生的 MathML 引擎。支持分数、根号、上下标、希腊字母、∑∏∫、矩阵（pmatrix/bmatrix/vmatrix）、cases、\left…\right、\text{}、\mathrm/\mathbf/\mathbb` 等常用子集；不认识的命令按字面显示，不会崩。

面板只读，数据走宿主侧注册的 /nodekb/api/*。写库就是写 md——用 write / edit 工具，或者 `k

…(truncated)