前言¶
在 DSH 里跑 Agent，默认找资料多半靠 read、grep、glob。常见情况是 grep 命中多个文件，再逐个 read，最后才发现真正要用的只是一段。知识若散落在 docs/*.md 里，行号会变、引用难维护，也没有统一的结构自检。
下面介绍维护者 levodoubt 的 DSH 插件 project-node-memory（社区分类：记忆）。它把项目下的 .nodekb/ 当作知识库：没有索引数据库、没有向量、没有后台进程，删掉插件后仍是一堆普通 Markdown 文件。
这是什么¶
一句话：Markdown-as-database——为 Agent 提供 10 个 kb_* 工具，为人类提供侧栏「项目节点知识库」三列面板；支持稳定 TID 寻址、转写（transclusion）、结构自检。
- 目录页：skillhub.cn/plugins/levodoubt/project-node-memory
- 源码：github.com/levodoubt/project-node-memory
- 许可证：MIT（见
package.json） - 当前包版本：1.3.2；要求 Node.js >= 18；DSH 兼容
>=0.1.5-rc.1
典型目录形态：
项目/
└── .nodekb/
├── index/entry.md
├── doc/03-build.md
├── lessons/001.md
└── diag_ignore.json # 可选：豁免样板块
核心能力¶
相对裸用 read/grep 的四件事¶
| 能力 | 工具 | 作用 |
|---|---|---|
| 先看结构再读正文 | kb_read mode=toc |
用约 200 token 的目录视图替代整篇 read |
稳定 TID（如 doc:03-build:3.1） |
kb_read target=… |
不依赖行号，改文件不打断引用 |
| 引用就地展开 | kb_read mode=subtree |
一次拿到装配好的上下文 |
| 结构自检 | kb_diag |
悬空引用、引用位置型段落、循环、孤儿等 |
mode=subtree 超过 maxlen（默认 50000 字符）会直接报错，并提示改用 toc / node，不会悄悄截断。
10 个 kb_* 工具¶
| 工具 | 用途 |
|---|---|
kb_list |
列出库与默认库；不确定 kb 参数时先调 |
kb_read |
target + mode（subtree / node / toc / raw）+ maxlen |
kb_search |
中文友好检索，返回稳定 TID、类型、源行、片段 |
kb_diag |
结构自检；有 error 时直接失败 |
kb_backlinks |
谁引用了该节点；改 TID 或删节点前建议先跑 |
kb_init |
幂等创建 .nodekb 骨架与落位约定 |
kb_write |
append / replace / create / node；写前校验、写后自检 |
kb_rename |
文件改名并改写全库引用 |
kb_vcs_status |
库内嵌 git 的快照与未提交改动（无 git 时仅说明） |
让人类 Agent 优先走 kb_* 的四层¶
- 系统提示词段落（默认开，
prompt.enabled=false可关）：规则约五行，引导沉淀知识用.nodekb/与kb_*，而非用write手搭docs/*.md。可用GET /nodekb/api/prompt自证是否注册。 kb_init：一次调用铺出doc/、lessons/、todo/、index/entry.md等，避免 Agent 自造目录。kb_write：校验 TID、<node>独占一行、路径边界；写后跑 diag。普通write无同等约束。- 随包技能
project-node-memory-guide（skill.enabled=false可关）：详写法规程在skills/project-node-memory-guide/SKILL.md；插件通过ctx.skills.register()注册到内存，不依赖 npm 包内skills/被 DSH 自动发现。GET /nodekb/api/skill可自证。
面板（只读浏览）¶
侧栏「项目节点知识库」打开后为三列：左为节点树与图设置，中为节点图（树形布局、类型着色），右为 Markdown 渲染内容与节点属性；[[TID]] 可点。数据来自宿主 /nodekb/api/*。右栏正文单次最多渲染 10000 字符。写库仍须改 md（write / edit 或 kb_write）。
安装与配置¶
安装¶
npm 发布后：
dsh plugin add project-node-memory
从源码打包（开发用）：
npm pack
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 |
exclude |
见 README | 库发现忽略目录名，支持 * 与 !pattern |
prompt.enabled |
true |
是否注册系统提示词段落 |
skill.enabled |
true |
是否注册随包 Skill |
exclude 示例：
config:
exclude: ['tmp_*', '!tmp_keep', 'scratch']
工作区解析优先级（摘要）：exec 上下文（面板目录 / 会话工作区）→ config.workspace → 环境变量 DSH_NODEKB_WORKSPACE → 最近一次工具用过的目录 → 进程 cwd。调试可看 GET /nodekb/api/where。
典型用法¶
1、初始化库¶
Agent 或你在会话中调用 kb_init，在工作区生成标准 .nodekb/ 结构（已存在则不覆盖）。
2、按 TID 读与展开¶
不确定库名时先 kb_list；读某节点用 kb_read，例如 target 设为 doc:03-build:3.1，需要装配上下文时用默认 mode=subtree。
3、写法与语法（节选）¶
位置型标题与显式节点：
## 3.1 编译契约 → tid = doc:03-build:3.1
<node name="fact:abi" type="fact" parent="doc:03-build">
正文
</node>
结构引用与值嵌入：
[[node="doc:03-build:3.1"]]
[[tscl="fact:abi"]]
改库用 kb_write；大改前用 kb_backlinks 与 kb_diag。库定位参数 kb 可传注册名或路径；不传时按工作区 .nodekb、唯一发现库或唯一注册表项解析。工作区内还会按约定位置自动发现（如 <ws>/.dsh/skills/<技能>/.nodekb/），详见 README「库怎么定位」。
适用场景与注意¶
适合：希望项目知识以 Markdown 落地、Agent 需要稳定引用与结构自检、多人用 git 管理 .nodekb/ 的团队。
注意：
- 插件以当前 DSH 进程权限运行；安装前请自行查看源码与 MIT 许可证。
- 社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本文仅介绍该插件能力，不编造案例或用户数据。
- GitHub 上该仓库星标为 0（以目录页线索为准）；功能与命令以 README 与
package.json为准。
结尾¶
project-node-memory 把「试探式 grep + 多读文件」收敛成目录视图、TID 寻址、转写与 kb_diag，知识留在 .nodekb/ 的 md 里。若要安装或读完整语法与注册表格式，请打开 插件目录页 与 GitHub README。
