project-node-memory 1.3.0 → 1.3.3

package/README.md

@@ -2,15 +2,17 @@
 
 > 简体中文 · [English](README_EN.md)
 
-把 **Markdown 目录当成知识库** 的 DSH 插件：为 Agent 提供 10 个 `kb_*` 工具，为人类提供知识节点面板（侧栏入口名「项目节点知识库」）。
+把 **Markdown 目录当成知识库** 的 DSH 插件：为 Agent 提供 9 个 `kb_*` 工具，为人类提供知识节点面板（侧栏入口名「项目节点知识库」）。
 
 没有索引数据库、没有向量、没有后台进程。完整知识库位于项目下的 `.nodekb/` 目录——一堆 md 文件，删掉插件之后它仍然是普通 md。
 
+本 README 只描述**当前版本**的行为；每个版本的变更记录在 [Releases](https://github.com/levodoubt/project-node-memory/releases)。
+
 ```
 项目/
 └── .nodekb/
     ├── index/entry.md        ## 3.1 编译契约
-    ├── doc/03-build.md       <node name="fact:abi" type="fact">…</node>
+    ├── doc/03-build.md       <tscl id="fact:abi">…</tscl>
     ├── lessons/001.md
     └── diag_ignore.json      可选：豁免样板块
 ```
@@ -92,7 +94,7 @@ config:
 面板只读，数据走宿主侧注册的 `/nodekb/api/*`。写库就是写 md——用 `write` / `edit` 工具，或者 `kb_write`。
 右栏正文单次最多渲染 10000 字符（超出显示截断提示）；宽表格横向滚动，长文本纵向滚动。
 
-## 10 个工具
+## 9 个工具
 
 | 工具            | 干什么                                                                                         |
 | --------------- | ---------------------------------------------------------------------------------------------- |
@@ -197,23 +199,6 @@ ABI 校验见 [[tscl="fact:ver"]]。
 
 旧写法 `[[TID]]` 仍兼容（有定义时当宏、否则当链接），`kb_diag` 会 warning，2.0 移除。
 
-## 从 1.0 升到 1.1
-
-数据格式没变——md 还是 md，TID 还是那些 TID，插件卸了照样能读。变化只有两条：
-
-1. **`[[x]]` 现在只出链接**，不再把被引用节点的正文复制进来（要复制原文请显式写 `<tscl>`）。
-   好处是引用不再撑大渲染结果，位置型小节 `## 3.1` 也能点了。
-2. **`kb_init` 不再建 `facts/`**。已有的 `facts/` 不会被动，`kb_read`/`kb_search` 照常；只是新库默认只有
-   `doc/ lessons/ todo/ index/`，事实改写成 `<tscl>` 定义放进它所属的 `doc/` 里。
-
-老库要不要迁？**不迁也能用**，只是 `kb_diag` 会给每条裸引用一条 warning。要迁就让 Agent 按
-`kb_diag` 的清单逐条改成 `[[node="…"]]` / `[[tscl="…"]]`（只改写法，不动 TID 与文件）：
-
-```text
-kb_diag                                    # 列出每条 `旧语法引用`
-kb_write mode=node target=<TID> content=…  # 逐条改，或直接改 md 再 kb_diag 复验
-```
-
 ## 自检（不装 DSH 也能跑）
 
 ```bash

package/README_EN.md

@@ -4,7 +4,7 @@
 
 A DSH plugin that treats **a directory of Markdown as a database**: nine `kb_*` tools for the agent, and a center-column panel for humans (sidebar entry: 「项目节点知识库」).
 
-> Renamed from `dsh-nodekb` at 0.2.0. Tool names (`kb_*`) and the on-disk format are unchanged.
+This README describes **the current version only**; per-version changes live in [Releases](https://github.com/levodoubt/project-node-memory/releases).
 
 No index database, no embeddings, no background process. The library *is* the `.nodekb/` directory in your project — a pile of Markdown files that stay ordinary Markdown if you uninstall the plugin.
 
@@ -12,7 +12,7 @@ No index database, no embeddings, no background process. The library *is* the `.
 project/
 └── .nodekb/
     ├── index/entry.md        ## 3.1 Compile contract
-    ├── doc/03-build.md       <node name="fact:abi" type="fact">…</node>
+    ├── doc/03-build.md       <tscl id="fact:abi">…</tscl>
     ├── lessons/001.md
     └── diag_ignore.json      optional: whitelist boilerplate blocks
 ```
@@ -89,7 +89,7 @@ The Markdown renderer is a small home-grown one (headings, lists, code, tables,
 The panel is read-only; data flows through host routes under `/nodekb/api/*`. Writing a library means writing Markdown — via `write` / `edit`, or `kb_write`.
 The right column renders at most 10,000 characters per view (with a truncation notice); wide tables scroll horizontally and long text scrolls vertically.
 
-## The ten tools
+## The nine tools
 
 | Tool | What it does |
 |---|---|
@@ -179,27 +179,6 @@ and who references it.
 The old `[[TID]]` form still works (macro when a definition exists, link otherwise) with a
 `kb_diag` warning, and goes away in 2.0.
 
-## Upgrading from 1.0
-
-The data format is unchanged — Markdown stays Markdown, TIDs stay the same, and the library remains
-readable after the plugin is removed. Only two things changed:
-
-1. **`[[x]]` now renders a link only**; it no longer copies the referenced node's body into the
-   output (use an explicit `<tscl>` for that). References stop inflating rendered size, and
-   positional sections (`## 3.1`) become clickable.
-2. **`kb_init` no longer creates `facts/`.** Existing `facts/` folders are untouched and still
-   readable/searchable; new libraries get `doc/ lessons/ todo/ index/` only, and facts become
-   `<tscl>` definitions inside the `doc/` file they belong to.
-
-Do old libraries need migrating? **No** — they keep working, `kb_diag` just emits one warning per
-bare reference. To migrate, have the agent walk the `kb_diag` list and fix each one (syntax only, no
-TID or file changes):
-
-```text
-kb_diag                                    # lists every `旧语法引用` (legacy bare ref)
-kb_write mode=node target=<TID> content=…  # fix one at a time, or edit the md and re-run kb_diag
-```
-
 ## Self-check (no DSH required)
 
 ```bash

package/lib/host/prompt.js

@@ -14,14 +14,13 @@ export const PROMPT_SECTION_ORDER = 100
 export const DEFAULT_PROMPT = [
   '## 项目知识库（project-node-memory）',
   '',
-  '本项目需要沉淀长期知识（设计决策、踩坑、事实常量、待办、交接）时，**用 `.nodekb/` + `kb_*` 工具**，不要用 write/edit 手搭 `docs/*.md` 式的渐进式文档——手写没有校验、没有稳定 TID、没有引用展开。',
+  '当本项目需要沉淀长期知识（设计决策、踩坑、事实常量、待办、交接）时，可用 `.nodekb/` + `kb_*` 工具。',
   '',
-  '- 建库：`kb_init` 一次铺出骨架（`doc/ lessons/ todo/ index/entry.md` + 约定说明）。已有 `.nodekb/` 就别重建；目录与节点类型都可按项目实际增删。',
-  '- 写库：`kb_write`（append/replace/create，或对显式节点用 mode=node）。写前校验 TID 与标签独占一行，写后立刻 `kb_diag` 报悬空引用/重复定义；用 write 做这些没有任何一层会拦。',
-  '- 读库：先 `kb_read mode=toc` 看结构（几百 token），再按 TID 读一支；找不到就 `kb_search`。别一次性把整库读进上下文。',
+  '- 建库：`kb_init` 一次铺出骨架 `doc/ lessons/ todo/ index/entry.md` + 落位约定。已有 `.nodekb/` 就别重建；目录与节点类型都可按项目实际增删。',
+  '- 写库：`kb_write`（append/replace/create，或对显式节点用 mode=node）。写前校验 TID 与标签独占一行，写后 `kb_diag` 报悬空引用/重复定义。',
+  '- 读库：先 `kb_read mode=toc` 看结构，再按 TID 读一支；找不到就 `kb_search`。别一次性把整库读进上下文。',
   '- 改名前先 `kb_backlinks`，改名用 `kb_rename`（会重写全库引用并跳过被并发改过的文件）。',
-  '- 引用分两种，别混：**结构**用 `[[node="doc:03-build:3.1"]]`（只出一个链接，不复制正文）；**值只写一处**——定义 `<tscl id="fact:abi">…</tscl>`，各处写 `[[tscl="fact:abi"]]`，同一 id 全库只能定义一次。定义可就近写在正文句子里（单行、别写进表格）。读一个值用 `kb_read target=<定义 id>`。',
-  '- 旧写法 `[[TID]]` 仍能用但 `kb_diag` 会 warning，2.0 移除（老库按 diag 清单逐处改成 `[[node=…]]` / `[[tscl=…]]`）。',
+  '- 引用分两种：结构用 `[[node="xxx"]]`（只出一个链接，不复制正文）；值只写一处——定义 `<tscl id="xxx:xxx">…</tscl>`，嵌入处写 `[[tscl="xxx:xxx"]]`，同一 id 全库只能定义一次。定义可就近写在正文句子里（单行、别写进表格）。读一个值用 `kb_read target=<定义 id>`。',
 ].join('\n')
 
 function textOf(config) {

package/lib/host/tools.js

@@ -73,8 +73,7 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_list',
     description:
-      '列出当前可用的 nodekb 知识库（名字 + 路径 + 是否存在），以及本次调用实际会命中的默认库。' +
-      '不确定该传什么 kb 参数时先调它。只读、极轻量。',
+      '列出当前可用的 nodekb 知识库以及本次调用实际会命中的默认库。不确定该传什么 kb 参数时先用它。',
     parameters: { type: 'object', properties: {} },
     output: {
       schema: {},
@@ -97,13 +96,15 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_read',
     description:
-      '读知识库的一个节点。target = TID 或其唯一前缀（空/"." = 库根），也可以是 <tscl id> 定义的名字（回定义体、定义处、被谁引用）。' +
-      'mode: subtree（默认，整支投影）| toc（只看结构，' +
-      '先定位再读）| node（只本节点）| raw（元信息+原文）。比 read 好在 TID 不随行号漂移；超 maxlen 会报错并提示换 toc/node。',
+      '读知识库的一个节点。target = TID 或其唯一前缀（空/"." = 库根），也可以是 <tscl id> 定义的名字。' +
+      'mode: subtree（默认，整支投影）| toc（只看结构，先定位再读）| node（只本节点）| raw（元信息+原文）。',
     parameters: {
       type: 'object',
       properties: {
-        target: { type: 'string', description: '节点 TID 或其唯一前缀。空字符串或 "." 表示库根。' },
+        target: {
+          type: 'string',
+          description: '节点 TID 或其唯一前缀；也可以是 <tscl id> 定义的名字（回定义体、定义处、被谁引用）。空字符串或 "." 表示库根。',
+        },
         kb: KB_PARAM,
         mode: {
           type: 'string',
@@ -185,8 +186,7 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_search',
     description:
-      '检索知识库（中文 2-gram + 多词加权 + 子串兜底）。返回稳定 TID、类型、标题、源行、片段。' +
-      '先 kb_search 拿 tid 再 kb_read，比 grep 后逐个 read 省往返。',
+      '检索知识库（中文 2-gram + 多词加权 + 子串兜底）。建议先 kb_search 拿 tid 再 kb_read。',
     parameters: {
       type: 'object',
       properties: {
@@ -224,8 +224,7 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_diag',
     description:
-      '结构自检。errors = 真损坏（悬空/位置型引用、循环、孤儿、树环、重复 TID、tscl 定义问题）；' +
-      'warnings = 疑似漂移（同一段文字出现在多处），默认不算失败。写完 md 就跑一次。',
+      '结构自检。errors = 真损坏；warnings = 疑似漂移，默认不算失败。建议写完 md 就跑一次。',
     parameters: {
       type: 'object',
       properties: {
@@ -254,8 +253,7 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_backlinks',
     description:
-      '反查：谁引用了这个 id（`[[node=…]]`/`[[tscl=…]]`/旧式 `[[TID]]` 都算）。改 TID 或删节点前先跑，' +
-      '比全库 grep 准——只认真实引用语法。',
+      '反查：谁引用了这个 id。建议改 TID 或删节点前先跑。',
     parameters: {
       type: 'object',
       properties: {
@@ -289,8 +287,7 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_rename',
     description:
-      '重命名 md 文件并改写全库指向它的引用（含子节点）。TID 由文件名派生，所以用 mv 改名必然留悬空引用；' +
-      '写前重读校验，别人刚改过的文件跳过不覆盖。',
+      '重命名 md 文件并改写全库指向它的引用。写前重读校验，别人刚改过的文件跳过不覆盖。',
     parameters: {
       type: 'object',
       properties: {
@@ -403,8 +400,8 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_write',
     description:
-      '写库并立刻自检（悬空引用/重复定义/结构错误当场报回来）。写前校验 TID 与 <node> 独占一行；' +
-      '用 write/edit 直接改没有这层。mode=append（追加，不存在则建）| replace（整篇）| create（只新建）| node（就地改一个 <node> 块）。',
+      '写库并立刻自检。写前会校验 TID 与 <node> 规范。' +
+      'mode=append（追加，不存在则建）| replace（整篇）| create（只新建）| node（就地改一个 <node> 块）。',
     parameters: {
       type: 'object',
       properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-node-memory",
-  "version": "1.3.0",
+  "version": "1.3.3",
   "description": "Project node knowledge base for DSH agents: markdown-as-database, stable TIDs, transclusion projection, structure self-check.",
   "type": "module",
   "license": "MIT",

package/skills/project-node-memory-guide/SKILL.md

@@ -36,10 +36,10 @@ kb_search query=...         # toc 里找不到再搜
 
 ## 两种引用方法
 
-| 写法                          | 渲染成                                         | 用在                              |
-| ----------------------------- | ---------------------------------------------- | --------------------------------- |
-| `[[node="doc:03-build:3.1"]]` | 一个链接，**不复制正文**                       | 指向另一段结构：「细节见 …」      |
-| `[[tscl="fact:abi"]]`         | 把 `<tscl id="fact:abi">` 的定义体**替换进来** | 同一句话/同一组数字必须在多处出现 |
+| 写法                          | 渲染成                                         |
+| ----------------------------- | ---------------------------------------------- |
+| `[[node="doc:03-build:3.1"]]` | 一个链接，**不复制正文**                       |
+| `[[tscl="fact:abi"]]`         | 把 `<tscl id="fact:abi">` 的定义体**替换进来** |
 
 ```md
 <tscl id="fact:sample">
@@ -81,5 +81,3 @@ kb_write target=doc/03-...md          mode=append  content=...
 
 1. 不要把整段对话贴进 `doc/` —— 记的是过程，不是结论。
 2. 不要把同一件事在 `doc/` 和 `lessons/` 各写一份 —— 抽成 `<tscl>` 定义，两处都引用它。
-
-