# 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 根目录（会在家目录留残留）。

## 安装

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

从源码装（开发用）：

```bash
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"`（与默认名单叠加）。

```yaml
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` 工具，或者 `kb_write`。 
右栏正文单次最多渲染 10000 字符（超出显示截断提示）；宽表格横向滚动，长文本纵向滚动。

## 工具

| 工具            | 干什么                                                                                                                                       |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `kb_list`       | 有哪些库（含绝对路径与来源）、本会话判定的工作区；末尾还会提醒「另有 N 个库不在本工作区」（打开过的库记在 `~/.dsh/nodekb/index.json`，不参与名字解析）。不确定传什么 `kb` 时先调它 |
| `kb_read`       | `target` + `mode`（`subtree` 默认 / `node` / `toc` / `raw`）+ `maxlen`；`toc` 默认只展开两层（`depth` 可调，`0` = 只看本节点），有子节的节点会报「整支 N 字符」；另有 `offset` / `limit`（行窗）与 `find`（只回命中行，带文件行号；整串没中时按词退让） |
| `kb_search`     | 中文友好检索（2-gram + 多词加权 + 少见时退化子串），返回稳定 TID、类型、源行、片段；`lines: true` 再加每节点 ≤3 条行级命中                |
| `kb_diag`       | 结构自检：`errors` / `warnings` / `advice` 三档；`advice` 是「还能更省」的改进建议，不影响退出码                                             |
| `kb_backlinks`  | 谁引用了它。改 TID / 删节点前先跑                                                                                                            |
| `kb_init`       | 建 `.nodekb` 骨架（幂等），默认铺出 `doc/ lessons/ todo/ index/` 与落位约定；`parts` 只要其中几个                                            |
| `kb_register`   | 把已有的库登记进**项目自己**的 `kb_registry.json`（不写全局表、不改配置）                                                                    |
| `kb_write`      | 写库：`append` / `replace` / `create` / `node`（就地改写一个 `<node>` 块或 `##` 段）；写前校验、写后自检、**成功后自动快照**                 |
| `kb_rename`     | 文件改名 + 全库引用一起改写；写前重读，别人刚改的不覆盖                                                                                      |
| `kb_vcs_status` | 内嵌 git 的最近几条快照 + 未提交改动（`count` 默认 5）；`kb_write` / `kb_rename` 成功后自动快照，`git: false` 可关；git 缺失时只说明，不报错 |

读类工具（`kb_list` / `kb_read` / `kb_search` / `kb_backlinks` / `kb_diag`）都接受 `format: "json"`：直接把算好的结构化字段给出来（`tid/source/lines/chars/hits`，diag 为 `{errors, warnings, advice, exit_code}`），Agent 不用再回头解析散文；`kb_diag` 在 json 模式下不抛异常，成败看 `exit_code`。

### 自检的三档

- `errors`：悬空引用、重复 TID、重复定义、树环、未闭合的 `<node>` / `<tscl>` —— 库结构已坏，必修。
- `warnings`：旧语法裸引用、位置型 TID 链接、跨行宏进表格、孤儿节点，**散文/行内代码里形如 TID 的文本解析不了**（`不可解析的 TID 文本 … 文件第 N 行「…」；最接近: …`）、**TID 大小写不合规**（`→ 应写「doc:01-real」`），以及**违反本库 `rules.json` 的规矩**（见下）——按需处理。
- `advice`：**写得对但还能更省**，六类 —— 同父目录下 ≥10 个「整篇不足 500 字符」的 md（按整篇算：导语 + 全部 `##` 段 + `<node>` 正文，所以「一文件一章节」不会被误判）、同一句散在多个节点（建议提出 `<tscl>` 定义）、库根缺 `index/entry.md`、md 缺一级标题、段节点超过 10000 字符（`fix` 会点明拆节会让位置型 TID 漂移）、**示例被写成了定义**（行首 `<tscl id="示例">` 会真的开定义块，把后面的章节吞进定义体；`example-tscl` 会点名是哪个 `##` / `<node>` 被吃掉了）。每条都带 `fix`，**不影响 `exit_code`**，CI 里可以无视。

`advice` 也能管（1.5.15）：`advice: { display: false }` 整块关掉（刻意松散的库看建议只会分心）、`advice: { limit: 10 }` 控条数（`0` = 全部给出）、`advice: { maxItems: 10 }` 改默认上限；逐条豁免写 `diag_ignore.json` 的第四项 `advice: [{code, tid}]`（`code` 与 `tid` 都是正则，同时命中才压掉）。`warnings` 也能整条压掉（1.5.17）：`diag_ignore.json` 的第五项 `warnings` 按告警文案正则匹配，一条命中就把它从报告里拿掉——比 `tids` 粗，能不用就不用。

小节的父节点**恒为文件节点**：同一份文件里「按 `##` 组织」和「具名 `<node>` 锚点」并存时，TOC 里两者是并列的，不会再串成 `3.1 → lesson1 → 3.2` 的链。

默认父节点由**结构**决定，而不是「本文件第一个 `<node>`」：同文件里多个并列写开的 `<node>` 都挂文件节点，写进另一个 `<node>` 里的才挂外层（想并列就平铺，想嵌套就把标签写开）。`###` 及更深**不建节点、也不切段**——它是段正文的一部分，拿 `doc:x:1.1` 这种 TID 去引用会报「前缀指向不存在的节点」。长段阈值等 advice 参数可在插件配置 `advice: { … }` 里覆盖。

插件升级后第一次跑 `kb_diag`，报告里会多一条 `plugin-updated`，提醒重读随包技能；每个库只提醒一次（状态记在 `.nodekb/.plugin-state.json`，由 `.git/info/exclude` 忽略——诊断不该把库弄成「有未提交改动」）。这条提醒**不受** `advice: { display: false }` 控制（那个开关只关改进建议），但**计入** `advice.limit` / `maxItems`，且排在最前；命令行 `nodekb diag` 与它同构。状态文件写不进去（只读库、权限不足）时，回执会追加一句「（状态文件写不进去，下次还会提醒）」。

## 库自己的规矩（`.nodekb/rules.json`）

`diag_ignore.json` 管「哪些警告别报」，`rules.json` 管「我们这儿必须这么写」。没有这个文件时行为不变。

```json
{
  "refStyle": { "default": "plain", "doc": "expand", "lessons": "expand" },
  "limits": { "bytes": { "default": 12288, "lessons": 4096 } }
}
```

- 目录键是文件相对库根的**第一段目录**，库根下的散文件用 `.`；未列出的目录回落到 `default`。
- `refStyle` = `expand`：允许 `[[node="…"]]`，`[[tscl="…"]]` 只允许指向 `fact:` 开头的定义；= `plain`：不许写 `[[…]]`，改写成反引号纯文本。
- `limits.bytes`：单文件体积上限（字节），超了报 warning。
- 围栏示例与行内代码不算违规；违规带库内相对路径与文件行号；`rules.json` 写坏只报一条 warning，不影响读库。

## 命令行（`nodekb`）

不在 DSH 里也想用同一套引擎（CI、定时任务、别的 agent 平台）时，装完包直接调：

```bash
nodekb list --all
nodekb read doc:03-semantics --kb about-node-memory --find 行号
nodekb search "回归闸门" --kb F:/proj --lines
nodekb diag --kb F:/proj --json          # 退出码 0/2，脚本里直接判
nodekb diag --kb F:/proj --out out.json  # .json 后缀自动当 --json；Windows 管道会坏中文，落文件最省事
nodekb write doc:05-x --kb F:/proj --file 新正文.md --mode replace
nodekb rename doc:05-x 06-x --kb F:/proj --dry-run
nodekb rename --batch 计划.json --kb F:/proj --dry-run   # 批量改名，逐条重读库、中途失败即停
nodekb vcs log --kb F:/proj --count 5
```

- 库定位：`--kb <库名|库目录|任意目录>`，省略时用当前目录的 `.nodekb`。命令行里显式给路径即授权，不受工作区白名单限制。
- **库名两边一致**（1.5.15）：插件启动时会把生效配置（`registries` / `libraries` / `workspace` / `exclude` / `advice`）抄到 `~/.dsh/nodekb/config.json`，命令行据此算名字——工具层认的 `kb="filmmeasure"`，命令行 `--kb filmmeasure` 同样认；`config.libraries` 里写技能目录或 `.nodekb` 本身都能定位。
- 每个命令都支持 `--json`，字段与工具层 `format: "json"` 一致；`--out 名字.json` 按后缀自动结构化。`nodekb diag` 与 `kb_diag` 同构：同样算 advice、同样在升级后给一次性的 `plugin-updated`。读命令退出码 `0` 成功、`1` 无命中、`2` 参数错或自检有 error。
- 工具层与命令行**共用同一份引擎**（`lib/engine/*`），没有第二套判定逻辑；`require('project-node-memory/engine')` 或 `import … from 'project-node-memory/engine/mdlib.js'` 可直接拿解析器，不必再按绝对路径 import 源码。

## 库怎么定位

所有 `kb_*` 工具只有一个定位参数 `kb`，它同时接受**名字**与**路径**：

1. `kb` 给路径（技能目录，或其下的 `.nodekb`，绝对或相对工作区）——必须落在**本会话工作区、任一已登记工作区或已注册库**内。
2. `kb` 给名字（注册表里的名字，或工作区里发现的名字，如某个技能名）。
3. 都不给：工作区自带的 `.nodekb/` → 工作区里发现且唯一的库 → 注册表里唯一的库。

### 自动发现

给了工作区之后，库里不只在工作区根找，还会按约定位置下钻（有界 BFS，默认 2 层）：

```text
<ws>/.nodekb                          → 名字 workspace
<ws>/.dsh/skills/<技能>/.nodekb        → 名字 <技能>
<ws>/<子目录>/.nodekb                  → 名字 相对路径
<ws>/<子目录>/.dsh/skills/<技能>/.nodekb
```

跳过 `node_modules` / `dist` / `build` / `out` / `target` / `coverage` / 点目录，`readdir` 次数有上限，所以面板每次加载都敢调。这就是「知识库跟着项目走」：指到项目根，技能里那些 `.nodekb/` 自己会浮出来。

一个库可以有两套名字（发现出来的名字 + 注册表里的名字）。`kb_list` 把它们**并到同一行**，标成 `- <发现名>  <路径>  （别名：<注册名>）`——否则「`kb=` 能用的名字」在 list 里根本看不见，人只能凭记忆猜。

### 注册表

注册表与 Python 版 `kb_registry.json` 同格式，默认读工作区下的 `.nodekb/registry.json` 与用户目录里的全局注册表。插件配置也可以直接内联：

```yaml
- insert:
    - id: nodekb
      name: project-node-memory
      config:
        libraries:
          my-notes: D:\notes      # 名字 → 目录（目录下需有 .nodekb/）
        registries:
          - D:\shared\kb_registry.json
```

### 工作区判定

「工作区」是解析库与判断可写范围的基准，判定顺序是：

1. **会话头里的 `cwd`**（工具调用时）——`exec.agent.id` → `ctx.get('sessions').get(id).header.cwd`。这是唯一可靠来源：DSH 交给工具的 `exec` 里没有 `cwd`/`workspace` 字段。
2. `exec` 里显式的目录（面板请求带的 `ws`）。
3. `config.workspace`。
4. 环境变量 `DSH_NODEKB_WORKSPACE`。
5. 面板没有会话，才退到「最近一次工具用过的工作区」；最后是进程 cwd。

每次 `kb_list` / `kb_init` 的回执都会写明**这次用的是哪个工作区、来源是哪一层**；`GET /nodekb/api/where` 给同样的信息。

写库或建库时，若目标落在**另一个**已登记工作区里，`kb_init` 会直接拒绝并打印双方路径——这是为了防止相对路径被解析到别的项目里。真要在那边建，去那个项目开会话；或者先用 `kb_register` 把已有的库登记进当前项目。

`kb_register` 只写 `<项目>/kb_registry.json`（建议随仓库提交），不碰全局注册表、不碰插件配置——所以权限问题可以在工具集内部自己解决，不用去改一个模型看不见的文件。

面板拿不到会话上下文，所以它默认跟随**最近一次 `kb_*` 工具调用所在的工作区**（Agent 读过哪个项目，面板就显示哪个项目）；顶栏的目录下拉只列出 DSH 用过的、且**真的有 `.nodekb`** 的项目目录（标了各自发现几个库），点右上「目录」也可以手填路径。选择存在浏览器 localStorage，只影响面板，不影响工具。

面板的两个下拉是联动的：**工作区 → 该工作区里的库**（`GET /nodekb/api/libs?scope=workspace`），全局注册表里的库单独归到「全局注册」分组，路径已不存在的注册项不显示（`exists:false`）。

想知道某个请求最后解析成了哪个工作区，直接看 `GET /nodekb/api/where`：它把 config / env / exec / 上次记忆 / 进程 cwd 与最终结论一起输出。

### 「注册」到底指什么

没有注册这一步也能用——只要库落在工作区里的约定位置（见上），它就会出现在列表里。`kb_registry.json` 只是给**不在工作区里**的库用的（比如 F 盘另一个项目、共享笔记目录）：

```json
{ "libraries": { "my-notes": { "path": "D:\\notes" } } }
```

读取顺序：`config.libraries` → `config.registries` 指定的文件 → `<ws>/.nodekb/registry.json` → `<ws>/kb_registry.json` → 用户目录的全局注册表（`~/.dsh/nodekb/registry.json`）。注册表里登记的名字优先级高于自动发现的名字，路径重复的以先出现的为准。

给条目加 `"hidden": true` 后，它**只作为别名**存在：仍然可以用 `kb="my-notes"` 调用（老文档里写死的库名不会失效），但不会出现在面板的知识库下拉里，也不进 `kb_list`（`includeHidden` 时才列出）。非 hidden 且指向已发现库的注册名，会作为 `（别名：…）` 并到那个库那一行。

```json
{ "libraries": { "my-notes": { "path": "D:\\notes", "hidden": true } } }
```

## 语法

```md
## 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"]]           → 值嵌入：把 <tscl id="fact:abi"> 的定义体替换进来

<tscl id="fact:abi">
三条硬规则：…（这个 id 全库只能定义一次）
</tscl>
```

一条原则：**结构用节点（链接），值用 tscl（嵌入）**。同一个数字/结论写两遍就是漂移，`kb_diag` 会报；写成 `<tscl>` 定义后各处只留一个引用，改一处全库同步。

硬规则：

- `<node>` / `</node>` 必须各占整行。
- `<tscl>` 内部不做结构解析（里面的 `##` 不算标题）。
- 同一 `tscl` id 全库只能定义一次，且不能与节点 TID 同名。
- `<node tid="…">` 与 `<node name="…">` 等价（`title="…"` 可另给显示名）。
- 缺 `name`/`tid` 的 `<node>` 会整段按正文处理并在 `kb_diag` 里报 warning——不会静默消失，`</node>` 也不会漏进正文。

代码区（``` / ~~~ 围栏与 `行内代码`）里的 `[[…]]`、`<node>`、`<tscl>` 都当**示例**：不解析、不计引用、不算定义、也不跟着改名（闭围栏要同字符且不短于开围栏）。写文档时不必再改全角括号。

显式节点的 TID **不要求含冒号**（`<node name="abi">` 的 TID 就是 `abi`）；属性值单双引号等价。`kb_write` 的 `target` 先查库里的 TID，再当库根文件名 / 路径（自动补 `.md`），三者都不是就拒绝，不会在库根凭空造出解析器看不见的文件。

### 写入时的四道硬性拦截

都是「写成功、库却被写坏」那一类，1.5.5 补上：

1. `content` 里的 CRLF 先归一成 LF，落盘再按原文件的换行拼回去——不会写出 `\r\r\n`；`append` 的结尾换行由工具补，`CRLF` 文件里不会混进裸 `LF`。
2. `content` 里出现 `</node>` 直接拒（它是包在本节点外面的结构，写进正文会把节点提前截断）；`<node>` / `<tscl>` 开标签要求成对（未闭合会吞掉后面的节点/段）。单行的 `<node name="x">正文</node>` 与「行首定义 + 同行后缀」的 `<tscl id="v">1</tscl> 说明` 都是合法写法。整篇 `replace` 不校验成对——那种情况作者说了算。
3. 路径必须是小写 `.md`，且不能有点开头的目录/文件（`.draft/x.md`、`.hidden.md` 解析器会跳过，等于写了个看不见的文件）。
4. 回执里的路径统一 `/` 分隔；段写入自动补「标题 / 空行 / 正文 / 空行」，且连写多次不会累积空行。

写进去的坏结构（手改 / git 合并 / `replace` 逃生口）由解析器收尾兜底：未闭合的 `<node>` / `<tscl>` 会让 `kb_diag` 报 **error**（1.5.6 前是 0 error / 0 warning，段节点会悄悄消失）。

写入校验与解析器同一口径（1.5.7）：围栏和**行内代码**里的 `<node>` / `<tscl>` 是示例，不拦——「教怎么写 nodekb」的正文可以随手用 `` `<node>` `` 举例；报错行号按你传的 `content` 算（首尾空行不计），不会再出现「说第 7 行、问题在第 8 行」。

TID 支持前缀兜底：`kb_read target=doc:02` 能命中 `doc:02-运行环境`（多个候选中取唯一的文件/文件夹节点；纯前缀歧义仍报错并给候选）。

### 句内定义

定义也可以**就地写在句子中间**，渲染时标签被剥掉、值留在原处：

```md
当前版本号为：<tscl id="fact:ver">v1.23.45</tscl>，向下兼容 v1.22。
ABI 校验见 [[tscl="fact:ver"]]。
```

句内定义**必须单行闭合**（行首的 `<tscl>` 才有跨行保护）；定义别写进表格行（`|` 会破格，`kb_diag` 会 warning）。要核一个值，`kb_read target=<定义 id>` 直接回「定义体 / 定义在哪个节点 / 被谁引用」。

旧写法 `[[TID]]` 仍兼容（有定义时当宏、否则当链接），`kb_diag` 会 warning，2.0 移除。

## 自检与端点

不装 DSH 也能跑：

```bash
node scripts/check.mjs      # 自检全量：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / tscl / 提示词段落 / 随包技能（结尾打印 N passed）
node test/parity.mjs        # 与 Python 原实现逐条对拍（需要 python 与 nodekb 源码）
```

`scripts/check.mjs` 在 vm 里跑客户端 bundle，捕获 `__ModuleLoader__.load({id, factory})`，断言 `id === package.json.name`（写错这个 id 会报 `bundle loaded without registering`）。

装进 DSH 之后，五个端点就地自证（`http://127.0.0.1:<端口>/nodekb/api/`）：

| 端点             | 说明什么                                               |
| ---------------- | ------------------------------------------------------ |
| `/version`       | 活着的处理器是哪一版（热载后旧路由可能还在，用这个认） |
| `/tools`         | 宿主收下几个 `kb_*`，被拒的是哪个                      |
| `/prompt`        | 系统提示词段落挂上没有                                 |
| `/skill`         | 随包 Skill 有没有进宿主技能表                          |
| `/client-report` | 浏览器侧槽位注册到了哪一步（图标不出现时看这个）       |

## 边界

- **写操作有边界**：`kb_init` 只建骨架（不覆盖），`kb_write` 只写库内路径（越界直接拒绝），`kb_rename` 负责改名的引用搬迁。其它随意改写仍可走 `write` / `edit`，只是没有校验。
- **不做自动记忆**：不抓会话、不后台扫描。库里的内容是人（或 Agent 显式）放进去的。
- **零依赖**：不 import 任何 `@deepseek-ai/*`，不声明 peerDependencies。
- 缓存按全库 md 的 `mtime/size` 签名失效，不依赖 `fs.watch`。

## 对 DSH 版本的依赖面

插件只碰宿主 8 个 API，全部集中在 `lib/host/`。哪一条变了、坏到什么程度，都在这张表里：

| 宿主 API                                                | 用在哪                   | 变了会怎样                                                  | 已有的隔离                                                            |
| ------------------------------------------------------- | ------------------------ | ----------------------------------------------------------- | --------------------------------------------------------------------- |
| `apply(ctx, config)` + `inject = ['tools','webServer']` | `lib/index.js`           | 服务名不存在 → 整行不激活（**静默不加载**，DSH 仍正常启动） | 静态 inject，不抛错                                                   |
| `ctx.tools.register(def)`                               | `lib/host/tools.js`      | 定义字段被拒收 → 该工具消失                                 | **逐条注册**，一条失败不影响其余；`GET /nodekb/api/tools` 报 `failed` |
| `ctx.webServer.register({kind:'prefix',…})`             | `lib/host/routes.js`     | 注册被拒 → 面板无数据，工具照旧                             | 异常被吞，`globalThis` 跳板让旧路由转发到新处理器                     |
| `ctx.inject([...], cb)`                                 | `prompt.js` / `skill.js` | 动态注入不可用 → 段落/技能不注册                            | 退回同步取值；仍失败只告警                                            |
| `ctx.systemPrompt.section({name,order,text})`           | `lib/host/prompt.js`     | 段落不出现 → Agent 不优先用它（工具仍在）                   | 失败被吞，`/api/prompt` 自证                                          |
| `ctx.skills.register({…})`                              | `lib/host/skill.js`      | 写法规范不进技能目录                                        | 失败被吞，`/api/skill` 自证                                           |
| `exec.workspace / cwd / session`                        | `lib/host/runtime.js`    | 定位不到工作区 → 默认库位置错                               | 4 级回退：exec → config → env → 上次工具用过的 → 进程 cwd             |
| `window.__ModuleLoader__.load({id,factory})`            | `lib/client.js`          | id 不匹配 → `bundle loaded without registering`             | 自检断言 id === 包名                                                  |
| `ctx.slots.inject` / `slots.register`                   | `lib/client.js`          | 槽名或 props 改名 → 图标不出现                              | 走 official `inject`，失败写 `/api/client-report` 并在面板内自述      |

**引擎与数据格式不依赖 DSH 任何东西**（纯 `node:fs` + `node:path`），所以数据侧不会被宿主版本变化波及。

## 卸载之后

`.nodekb/` 就是普通 Markdown 目录，没有任何私存格式：

- 直接 `read` / `grep` / `edit` 照常，`[[TID]]` 退化成普通文本（不再展开、不再校验）。
- Python 版 nodekb（MCP）读同一个库，格式一致——`test/parity.mjs` 16 项对拍守的就是这条。
- 重新装回任意后续版本，库不需要迁移。
- 唯一会变糙的是**维护性**：手改文件后没有 `diag` 兜底，改名要靠手搬引用（`kb_rename` 不在时没人帮你改 `[[old]]`）。

## License

MIT
<!-- probe -->
<!-- probe -->
