project-node-memory 1.1.0 → 1.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 > 简体中文 · [English](README_EN.md)
 
-把 **Markdown 目录当成知识库** 的 DSH 插件：为 Agent 提供 9 个 `kb_*` 工具，为人类提供知识节点面板（侧栏入口名「项目节点知识库」）。
+把 **Markdown 目录当成知识库** 的 DSH 插件：为 Agent 提供 10 个 `kb_*` 工具，为人类提供知识节点面板（侧栏入口名「项目节点知识库」）。
 
 没有索引数据库、没有向量、没有后台进程。完整知识库位于项目下的 `.nodekb/` 目录——一堆 md 文件，删掉插件之后它仍然是普通 md。
 
@@ -92,7 +92,7 @@ config:
 面板只读，数据走宿主侧注册的 `/nodekb/api/*`。写库就是写 md——用 `write` / `edit` 工具，或者 `kb_write`。
 右栏正文单次最多渲染 10000 字符（超出显示截断提示）；宽表格横向滚动，长文本纵向滚动。
 
-## 9 个工具
+## 10 个工具
 
 | 工具            | 干什么                                                                                         |
 | --------------- | ---------------------------------------------------------------------------------------------- |
@@ -103,7 +103,8 @@ config:
 | `kb_backlinks`  | 谁引用了它。改 TID / 删节点前先跑                                                              |
 | `kb_init`       | 建 `.nodekb` 骨架（幂等），铺出 `doc/ lessons/ todo/ index/` 与落位约定                 |
 | `kb_write`      | 写库：`append` / `replace` / `create` / `node`（就地改写一个 `<node>` 块）；写前校验、写后自检 |
-| `kb_rename`     | 文件改名 + 全库 `[[TID]]` 引用一起改写（含 `[[tid:1.2]]`）；写前重读，别人刚改的不覆盖         |
+| `kb_rename`     | 文件改名 + 全库引用一起改写；写前重读，别人刚改的不覆盖                                        |
+| `kb_migrate`    | 旧语法裸引用 `[[x]]` → `[[node="x"]]` / `[[tscl="x"]]`；**默认只演练**，`dry_run=false` 才落盘    |
 | `kb_vcs_status` | 库内嵌 git 的快照历史与未提交改动（git 缺失时只说明，不报错）                                  |
 
 ## 库怎么定位
@@ -183,10 +184,29 @@ config:
 同一 `tscl` id 全库只能定义一次，且不能与节点 TID 同名。
 旧写法 `[[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。要迁就跑：
+
+```text
+kb_migrate                        # 演练：报每个文件会改几处、哪些引用本来就悬空
+kb_migrate dry_run=false          # 确认后落盘
+```
+
+迁移只改写法（`[[doc:x]]` → `[[node="doc:x"]]`，命中定义则 `[[tscl="…"]]`），不动任何 TID、不搬文件，
+所以引用关系与渲染结果都不变；围栏代码块内一律跳过。
+
 ## 自检（不装 DSH 也能跑）
 
 ```bash
-node scripts/check.mjs      # 275 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / 提示词段落 / 随包技能
+node scripts/check.mjs      # 290 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / tscl / 迁移 / 提示词段落 / 随包技能
 node test/parity.mjs        # 与 Python 原实现逐条对拍（需要 python 与 nodekb 源码）
 ```
 

package/README_EN.md

@@ -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 nine tools
+## The ten tools
 
 | Tool | What it does |
 |---|---|
@@ -100,7 +100,8 @@ The right column renders at most 10,000 characters per view (with a truncation n
 | `kb_backlinks` | Who references this node. Run before renaming a TID or deleting a node |
 | `kb_init` | Scaffold `.nodekb` (idempotent): `doc/ lessons/ todo/ index/` plus placement conventions |
 | `kb_write` | Write into the library: `append` / `replace` / `create` / `node` (rewrite one `<node>` block in place); validates before writing, self-checks after |
-| `kb_rename` | Rename a file and rewrite every `[[TID]]` pointing at it (including `[[tid:1.2]]`); re-reads before writing, so concurrent edits are never clobbered |
+| `kb_rename` | Rename a file and rewrite every reference pointing at it; re-reads before writing, so concurrent edits are never clobbered |
+| `kb_migrate` | Rewrites legacy bare refs `[[x]]` into `[[node="x"]]` / `[[tscl="x"]]`; **dry-run by default**, pass `dry_run=false` to write |
 | `kb_vcs_status` | Snapshot history and uncommitted changes of the library's embedded git repo (explains itself when git is missing) |
 
 ## How a library is located
@@ -162,10 +163,34 @@ as structure (a `##` there is not a heading); a `tscl` id may be defined exactly
 collide with a node TID. 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:
+
+```text
+kb_migrate                        # dry run: how many refs per file, which ones are already dangling
+kb_migrate dry_run=false          # write
+```
+
+Migration only changes syntax (`[[doc:x]]` → `[[node="doc:x"]]`, or `[[tscl="…"]]` when the id is a
+definition). No TID changes, no file moves, so references and rendered output stay identical; fenced
+code blocks are skipped.
+
 ## Self-check (no DSH required)
 
 ```bash
-node scripts/check.mjs      # 275 checks: manifest contract / tools / routes / client slots / rename rewriting / scaffold + write / prompt section / bundled skill
+node scripts/check.mjs      # 290 checks: manifest contract / tools / routes / client slots / rename rewriting / scaffold + write / tscl / migration / prompt section / bundled skill
 node test/parity.mjs        # case-by-case parity against the Python implementation (needs python and nodekb sources)
 ```
 

package/lib/engine/migrate.js

@@ -0,0 +1,171 @@
+/**
+ * migrate —— 把旧写法裸引用 `[[x]]` 迁成 1.1 的双语法。
+ *
+ * 规则：
+ *   - x 是 tscl 定义 id  → `[[tscl="x"]]`（值嵌入）
+ *   - x 是节点 TID        → `[[node="x"]]`（链接）
+ *   - 两者都不是          → 原样保留，记进 unresolved（本来就悬空，迁移不该猜）
+ *
+ * 三条纪律与 rename 一致：围栏内不动、写前重读复核 mtime/size、默认只演练（dry_run）。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { ROOT_TID } from './mdlib.js'
+
+const FENCE = '```'
+const BARE_REF = /\[\[([^[\]"=\s][^[\]]*)\]\]/g
+
+function absOf(lib, node) {
+  const raw = String(node.source || '').split('#')[0]
+  if (!raw) return ''
+  return path.isAbsolute(raw) ? path.normalize(raw) : path.join(lib.nodekb, raw)
+}
+
+function relOf(lib, abs) {
+  return path.relative(lib.nodekb, abs).split(path.sep).join('/')
+}
+
+function allMarkdown(nodekb) {
+  const out = []
+  const walk = (d) => {
+    let entries
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue
+      const p = path.join(d, e.name)
+      if (e.isDirectory()) walk(p)
+      else if (e.name.endsWith('.md')) out.push(p)
+    }
+  }
+  walk(nodekb)
+  return out
+}
+
+/** 纯函数：把一段 md 文本里的裸引用改写（可单测） */
+export function migrateText(text, { isTid, isDef }) {
+  const out = []
+  const hits = { node: 0, tscl: 0, unresolved: [] }
+  let fenced = false
+  for (const line of String(text).split('\n')) {
+    if (line.trim().startsWith(FENCE)) {
+      fenced = !fenced
+      out.push(line)
+      continue
+    }
+    if (fenced) {
+      out.push(line)
+      continue
+    }
+    out.push(
+      line.replace(BARE_REF, (whole, inner) => {
+        const id = inner.trim()
+        if (isDef(id)) {
+          hits.tscl += 1
+          return `[[tscl="${id}"]]`
+        }
+        if (isTid(id)) {
+          hits.node += 1
+          return `[[node="${id}"]]`
+        }
+        hits.unresolved.push(id)
+        return whole
+      }),
+    )
+  }
+  return { text: out.join('\n'), hits }
+}
+
+/**
+ * 迁移整个库。
+ * @param {{nodekb:string, nodes:Map, defs?:Map}} lib openLibrary 的结果
+ * @param {{dryRun?:boolean}} [opts] 默认演练
+ */
+export function migrateLibrary(lib, opts = {}) {
+  const dryRun = opts.dryRun !== false
+  const defs = lib.defs || new Map()
+  const nodes = lib.nodes
+  const isTid = (id) => nodes.has(id)
+  const isDef = (id) => defs.has(id)
+
+  const report = { dry_run: dryRun, files: [], node: 0, tscl: 0, unresolved: [], skipped: [] }
+  const edits = []
+  const visited = new Set()
+
+  for (const node of nodes.values()) {
+    if (node.kind !== 'file') continue
+    const abs = absOf(lib, node)
+    if (!abs) continue
+    visited.add(path.resolve(abs))
+    let text
+    let st1
+    try {
+      st1 = fs.statSync(abs)
+      text = fs.readFileSync(abs, 'utf8')
+    } catch (e) {
+      report.skipped.push({ path: relOf(lib, abs), why: `读失败: ${e.message}` })
+      continue
+    }
+    if (!text.includes('[[')) continue
+    const { text: next, hits } = migrateText(text, { isTid, isDef })
+    const changed = hits.node + hits.tscl
+    for (const u of hits.unresolved) report.unresolved.push({ path: relOf(lib, abs), ref: u })
+    if (!changed) continue
+    report.node += hits.node
+    report.tscl += hits.tscl
+    report.files.push({ path: relOf(lib, abs), count: changed, node: hits.node, tscl: hits.tscl })
+    edits.push({ abs, st1, next, path: relOf(lib, abs) })
+  }
+
+  if (!dryRun) {
+    for (const e of edits) {
+      try {
+        const st2 = fs.statSync(e.abs)
+        if (st2.mtimeMs !== e.st1.mtimeMs || st2.size !== e.st1.size) {
+          report.skipped.push({ path: e.path, why: '读后被改动，未覆盖' })
+          continue
+        }
+        fs.writeFileSync(e.abs, e.next, 'utf8')
+      } catch (err) {
+        report.skipped.push({ path: e.path, why: err.message })
+      }
+    }
+  }
+
+  // 兜底：只报「存在但没进索引」的 md（解析失败的孤儿文件），不重复报已处理的
+  for (const abs of allMarkdown(lib.nodekb)) {
+    if (visited.has(path.resolve(abs))) continue
+    report.skipped.push({ path: relOf(lib, abs), why: '未被解析为目标节点，未处理' })
+  }
+
+  return report
+}
+
+export function formatMigrate(report) {
+  const lines = []
+  lines.push(report.dry_run ? '（演练，未落盘；确认后传 dry_run=false 才写）' : '已写入')
+  const total = report.files.reduce((s, f) => s + f.count, 0)
+  if (!total) {
+    lines.push('没有需要迁移的裸引用')
+  } else {
+    lines.push(`共 ${total} 处裸引用 → ${report.tscl} 处 [[tscl="…"]]、${report.node} 处 [[node="…"]]`)
+    for (const f of report.files.slice(0, 20)) lines.push(`  - ${f.path}: ${f.count}（tscl ${f.tscl} / node ${f.node}）`)
+    if (report.files.length > 20) lines.push(`  …另有 ${report.files.length - 20} 个文件`)
+  }
+  if (report.unresolved.length) {
+    lines.push(`保留未改 ${report.unresolved.length} 处（指向的 id 既不是节点也不是定义，本来悬空）：`)
+    for (const u of report.unresolved.slice(0, 10)) lines.push(`  - ${u.path}: [[${u.ref}]]`)
+    if (report.unresolved.length > 10) lines.push(`  …另有 ${report.unresolved.length - 10} 处`)
+  }
+  if (report.skipped.length) {
+    lines.push(`跳过 ${report.skipped.length} 个文件：`)
+    for (const s of report.skipped.slice(0, 10)) lines.push(`  - ${s.path}: ${s.why}`)
+  }
+  return lines.join('\n')
+}
+
+export { ROOT_TID }

package/lib/host/prompt.js

@@ -21,7 +21,7 @@ export const DEFAULT_PROMPT = [
   '- 读库：先 `kb_read mode=toc` 看结构（几百 token），再按 TID 读一支；找不到就 `kb_search`。别一次性把整库读进上下文。',
   '- 改名前先 `kb_backlinks`，改名用 `kb_rename`（会重写全库引用并跳过被并发改过的文件）。',
   '- 引用分两种，别混：**结构**用 `[[node="doc:03-build:3.1"]]`（只出一个链接，不复制正文）；**值只写一处**——定义 `<tscl id="fact:abi">…</tscl>`，各处写 `[[tscl="fact:abi"]]`，同一 id 全库只能定义一次。',
-  '- 旧写法 `[[TID]]` 仍能用但 `kb_diag` 会 warning，2.0 移除。',
+  '- 旧写法 `[[TID]]` 仍能用但 `kb_diag` 会 warning，2.0 移除（老库可先跑 `kb_migrate` 演练，确认后 `dry_run=false` 批量迁）。',
 ].join('\n')
 
 function textOf(config) {

package/lib/host/routes.js

@@ -12,6 +12,7 @@ import { search, formatSearch } from '../engine/search.js'
 import { diag } from '../engine/diag.js'
 import { extractRefs } from '../engine/parse.js'
 import { renameFileNode, formatRename } from '../engine/rename.js'
+import { migrateLibrary, formatMigrate } from '../engine/migrate.js'
 import { openLibrary, knownLibraries, whereInfo, workspaceOf } from './runtime.js'
 import { promptState } from './prompt.js'
 import { skillState } from './skill.js'
@@ -279,6 +280,14 @@ export function registerRoutes(ctx, config) {
         return
       }
 
+      if (url.pathname === `${PREFIX}/migrate`) {
+        const lib = open()
+        const dryRun = !(q.get('dry_run') === '0' || q.get('dry_run') === 'false')
+        const report = migrateLibrary(lib, { dryRun })
+        send(res, 200, { kb: lib.name, ...report, text: formatMigrate(report) })
+        return
+      }
+
       send(res, 404, { error: `未知端点: ${url.pathname}` })
     } catch (e) {
       send(res, 400, { error: e && e.message ? e.message : String(e) })

package/lib/host/tools.js

@@ -14,6 +14,7 @@ import { search, formatSearch } from '../engine/search.js'
 import { diag } from '../engine/diag.js'
 import { extractRefs } from '../engine/parse.js'
 import { renameFileNode, formatRename } from '../engine/rename.js'
+import { migrateLibrary, formatMigrate } from '../engine/migrate.js'
 import { scaffold } from '../engine/scaffold.js'
 import { writeInto } from '../engine/write.js'
 import { isInside } from '../engine/registry.js'
@@ -309,6 +310,33 @@ export function buildTools(ctx, config) {
     },
   })
 
+  // ── kb_migrate ───────────────────────────────────────────────────────────
+  tools.push({
+    name: 'kb_migrate',
+    description:
+      '把库里的旧写法裸引用 [[x]] 迁成 1.1 的双语法：[[tscl="x"]]（x 是定义）或 [[node="x"]]（x 是节点 TID）。' +
+      '默认只演练（dry_run 缺省为 true），返回每个文件会改几处、哪些引用指向不存在的 id 会原样保留。' +
+      '围栏代码块内不动；写前重读校验，别人刚改过的文件不覆盖。',
+    parameters: {
+      type: 'object',
+      properties: {
+        dry_run: { type: 'boolean', description: '默认 true（只报告）。确认无误后传 false 才真正写盘。' },
+        kb: KB_PARAM,
+        lib: LIB_PARAM,
+      },
+    },
+    output: {
+      schema: {},
+      render: (_args, value) => text(value.text),
+    },
+    async execute(args, exec) {
+      const lib = locate(config, exec, args)
+      const dryRun = args.dry_run === undefined ? true : Boolean(args.dry_run)
+      const report = migrateLibrary(lib, { dryRun })
+      return { ...report, kb: lib.name, text: warnPrefix(lib) + formatMigrate(report) }
+    },
+  })
+
   // ── kb_vcs_status ────────────────────────────────────────────────────────
   tools.push({
     name: 'kb_vcs_status',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-node-memory",
-  "version": "1.1.0",
+  "version": "1.1.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

@@ -55,6 +55,7 @@ kb_search query=...         # toc 里找不到再搜
 - 定义块内部的 `##` **不会**变成节点——它只是文本。
 
 旧写法 `[[TID]]` 仍能解析（有定义时当宏、否则当链接），但 `kb_diag` 会 warning，2.0 移除。
+接手老库时先跑 `kb_migrate`（默认只演练），看清每处会改成 `[[node=…]]` 还是 `[[tscl=…]]` 再 `dry_run=false`。
 
 ## TID 规则