project-node-memory 1.1.4 → 1.3.0

package/README.md

@@ -108,8 +108,10 @@ config:
 
 ## 库怎么定位
 
-1. `lib` 参数给路径（技能目录，或其下的 `.nodekb`）——必须落在工作区或已注册库内
-2. `kb` 参数给名字（注册表里的名字，或工作区里发现的名字，如某个技能名）
+所有 `kb_*` 工具只有一个定位参数 `kb`，它同时接受**名字**与**路径**：
+
+1. `kb` 给路径（技能目录，或其下的 `.nodekb`，绝对或相对工作区）——必须落在工作区或已注册库内
+2. `kb` 给名字（注册表里的名字，或工作区里发现的名字，如某个技能名）
 3. 都不给：工作区自带的 `.nodekb/` → 工作区里发现且唯一的库 → 注册表里唯一的库
 
 **自动发现**：给了工作区之后，库里不只在工作区根找，还会按约定位置下钻（有界 BFS，默认 2 层）：
@@ -181,6 +183,18 @@ config:
 
 硬规则：`<node>` / `</node>` 必须各占整行；`<tscl>` 内部不做结构解析（里面的 `##` 不算标题）；
 同一 `tscl` id 全库只能定义一次，且不能与节点 TID 同名。
+
+定义也可以**就地写在句子中间**，渲染时标签被剥掉、值留在原处：
+
+```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 移除。
 
 ## 从 1.0 升到 1.1
@@ -203,7 +217,7 @@ kb_write mode=node target=<TID> content=…  # 逐条改，或直接改 md 再 k
 ## 自检（不装 DSH 也能跑）
 
 ```bash
-node scripts/check.mjs      # 275 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / tscl / 提示词段落 / 随包技能
+node scripts/check.mjs      # 292 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / tscl / 提示词段落 / 随包技能
 node test/parity.mjs        # 与 Python 原实现逐条对拍（需要 python 与 nodekb 源码）
 ```
 

package/README_EN.md

@@ -105,8 +105,10 @@ The right column renders at most 10,000 characters per view (with a truncation n
 
 ## How a library is located
 
-1. `lib` — a path (a skill directory or its `.nodekb`), which must fall inside the workspace or a registered library.
-2. `kb` — a name (from a registry, or discovered in the workspace, e.g. a skill name).
+Every `kb_*` tool takes exactly one location parameter, `kb`, which accepts **either a name or a path**:
+
+1. `kb` = a path (a skill directory or its `.nodekb`, absolute or workspace-relative) — must fall inside the workspace or a registered library.
+2. `kb` = a name (from a registry, or discovered in the workspace, e.g. a skill name).
 3. Neither — the workspace's own `.nodekb/` → the single library discovered in the workspace → the single registered library.
 
 **Discovery**: given a workspace, it looks beyond the root at conventional locations (bounded BFS, depth 2 by default):
@@ -159,8 +161,23 @@ leave references at every use site, so a single edit updates the whole library.
 
 Hard rules: `<node>` / `</node>` must each occupy an entire line; nothing inside `<tscl>` is parsed
 as structure (a `##` there is not a heading); a `tscl` id may be defined exactly once and must not
-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.
+collide with a node TID.
+
+A definition may also sit **inline in the middle of a sentence** — the tags are stripped when
+rendered and the value stays where it is written:
+
+```md
+Current version: <tscl id="fact:ver">v1.23.45</tscl>, backward compatible with v1.22.
+ABI check: [[tscl="fact:ver"]].
+```
+
+An inline definition **must close on the same line** (only a line-start `<tscl>` gets cross-line
+protection), and it must not go into a table row (a `|` inside the body breaks the row; `kb_diag`
+warns). To check one value, `kb_read target=<definition id>` returns the body, where it is defined,
+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
 
@@ -186,7 +203,7 @@ kb_write mode=node target=<TID> content=…  # fix one at a time, or edit the md
 ## Self-check (no DSH required)
 
 ```bash
-node scripts/check.mjs      # 275 checks: manifest contract / tools / routes / client slots / rename rewriting / scaffold + write / tscl / prompt section / bundled skill
+node scripts/check.mjs      # 292 checks: manifest contract / tools / routes / client slots / rename rewriting / scaffold + write / tscl / prompt section / bundled skill
 node test/parity.mjs        # case-by-case parity against the Python implementation (needs python and nodekb sources)
 ```
 

package/lib/client.js

@@ -1190,6 +1190,21 @@
         setQuery('')
       }
 
+      /** 点开一个 [[tscl="id"]]：跳到定义所在的节点（值就在那一段话里） */
+      function openDef(id) {
+        if (!kb || !id) return
+        get('/defs', { kb: kb, id: id })
+          .then(function (r) {
+            if (!r || !r.owner_tid) { setErr('未找到定义: ' + id); return }
+            setErr('')
+            setHits(null)
+            setQuery('')
+            setSel(r.owner_tid)
+            setView('node')
+          })
+          .catch(function (e) { setErr(e.message) })
+      }
+
       function runSearch() {
         var q = (query || '').trim()
         if (!q) { setHits(null); return }
@@ -1441,7 +1456,7 @@
                 : null,
             )
           : view === 'raw' || view === 'source' || view === 'toc'
-            ? h(Rich, { text: shownText, onOpen: open })
+            ? h(Rich, { text: shownText, onOpen: open, onMacro: openDef })
             : h(Md, { text: shownText, onOpen: open })
       var cutNotice = textCut
         ? h(

package/lib/engine/commands.js

@@ -9,7 +9,7 @@
 import { render_node, render_subtree, toc_lines, node_info, resolve_path, TransclusionError } from './render.js'
 import { search, formatSearch } from './search.js'
 import { diag } from './diag.js'
-import { collectDefs } from './defs.js'
+import { collectDefs, refsToDef, formatDefRead } from './defs.js'
 import { lib_root_tids } from './mdlib.js'
 
 // 整支渲染字符上限（0 = 不限）。防止一次调用打爆上下文（root ≈ 23.5 万字符）
@@ -30,12 +30,18 @@ export function cmdRead(nodes, target, { node = false, raw = false, toc = false,
     return { text: e.message, code: 2 }
   }
   if (tid === null) {
+    // 不是节点：再看是不是一个 tscl 定义 id（值的老家可能只是一句话）
+    const defsMap = defs || collectDefs(nodes).defs
+    const def = defsMap.get(target)
+    if (def) return { text: formatDefRead(def, refsToDef(nodes, target)), code: 0, def: target }
     const cands = [...nodes.keys()]
       .filter((t) => t.startsWith(target) || t.startsWith(target + ':'))
       .sort()
       .slice(0, 10)
     let msg = `未找到节点: ${target}`
     if (cands.length) msg += '；候选: ' + cands.join('、')
+    const defSuffix = [...defsMap.keys()].filter((d) => d.includes(target)).sort().slice(0, 5)
+    if (defSuffix.length) msg += '；同名 tscl 定义候选: ' + defSuffix.join('、')
     return { text: msg, code: 2 }
   }
   try {

package/lib/engine/defs.js

@@ -8,7 +8,7 @@
  * 无人引用，全部以 problems 形式交回给 diag 定级。
  */
 
-import { extract_defs } from './parse.js'
+import { extract_defs, extractRefs } from './parse.js'
 
 const NESTED_OPEN = /<tscl\b[^>]*>(?:(?!<\/tscl>)[\s\S])*?<tscl\b/
 
@@ -58,3 +58,41 @@ export function collectDefs(nodes) {
 export function isMultiline(body) {
   return String(body || '').replace(/\s+$/, '').includes('\n')
 }
+
+/** 谁在正文里引用了这个定义（[[tscl="id"]]，或指向它的旧语法裸引用）→ [{tid,title,source,line,legacy}] */
+export function refsToDef(nodes, id) {
+  const out = []
+  for (const node of nodes.values()) {
+    const content = String(node.content || '')
+    if (!content.includes(id)) continue
+    for (const ref of extractRefs(content)) {
+      if (ref.id !== id) continue
+      if (ref.kind !== 'tscl' && ref.kind !== 'legacy') continue
+      out.push({
+        tid: node.tid,
+        title: node.title || '',
+        source: node.source || '',
+        line: content.slice(0, ref.index).split('\n').length,
+        legacy: ref.kind === 'legacy',
+      })
+    }
+  }
+  return out
+}
+
+/** 定义 → 人读文本（kb_read 按 tscl id 读、面板点宏时跳转用） */
+export function formatDefRead(def, refs = []) {
+  const src = String(def.source || '').split(/[\\/]/).filter(Boolean).slice(-2).join('/')
+  const lines = [`定义体 <tscl id="${def.id}"> · 定义在 ${def.ownerTid}${src ? `（${src}）` : ''}`, '', String(def.body || '').replace(/\s+$/, '')]
+  if (def.count > 1) lines.push('', `重复定义 ${def.count} 处（必须只剩一处）: ${def.owners.join('、')}`)
+  if (refs.length) {
+    lines.push('', `被引用 ${refs.length} 处：`)
+    for (const r of refs) {
+      const at = String(r.source || '').split(/[\\/]/).filter(Boolean).slice(-2).join('/')
+      lines.push(`- ${r.tid}${r.title ? ` · ${r.title}` : ''}${at ? `（${at}#L${r.line}）` : ''}${r.legacy ? `  ← 旧语法，建议 [[tscl="${def.id}"]]` : ''}`)
+    }
+  } else {
+    lines.push('', '尚未被任何 [[tscl="…"]] 引用。')
+  }
+  return lines.join('\n')
+}

package/lib/engine/diag.js

@@ -229,6 +229,17 @@ export function diag(nodes, { problems = [], strict = false, libRoot, defs = nul
         warnings.push(`位置型 TID 链接（插章节会漂移）: ${node.tid} → ${ref.raw}`)
       }
     }
+
+    // 定义写在表格行里：表格只放单行宏，定义体含 | 会破格
+    if (content.includes('<tscl')) {
+      const lines = content.split('\n')
+      for (let li = 0; li < lines.length; li++) {
+        if (!/<tscl\b/.test(lines[li])) continue
+        if (/^\s*\|/.test(lines[li])) {
+          warnings.push(`定义写在表格行里: ${node.tid} 第 ${li + 1} 行 → <tscl>（定义体含 | 会破格；把定义移到正文段落）`)
+        }
+      }
+    }
   }
 
   for (const def of defsMap.values()) {

package/lib/engine/registry.js

@@ -194,6 +194,11 @@ export function discoverLibraries(root, { depth = 2, budget = 300, limit = 60, e
  */
 export function resolveLibrary({ kb, lib, workspace, config } = {}) {
   const ws = path.resolve(workspace || process.cwd())
+  // kb 同时接受「库名」与「路径」：带分隔符 / 绝对路径 / 指向 .nodekb 的一律当路径。
+  const raw = kb === undefined || kb === null ? '' : String(kb).trim()
+  const looksLikePath = !!raw && (path.isAbsolute(raw) || /[\\/]/.test(raw) || /\.nodekb$/i.test(raw))
+  const explicit = lib || (looksLikePath ? raw : undefined)
+  const kbName = looksLikePath ? undefined : raw
   const exclude = config && config.exclude
   const discover = () => discoverLibraries(ws, { exclude })
   const registries = loadRegistries(
@@ -202,10 +207,10 @@ export function resolveLibrary({ kb, lib, workspace, config } = {}) {
   )
 
   // 1) 显式路径
-  if (lib) {
-    const p = path.resolve(ws, lib)
+  if (explicit) {
+    const p = path.resolve(ws, explicit)
     const nodekb = path.basename(p) === '.nodekb' ? p : path.join(p, '.nodekb')
-    if (!isDir(nodekb)) throw new Error(`库目录不存在: ${nodekb}（你传入: ${lib}）`)
+    if (!isDir(nodekb)) throw new Error(`库目录不存在: ${nodekb}（你传入: ${explicit}）`)
     const allowed = [ws, ...[...registries.values()].map((e) => e.path)]
     if (!allowed.some((root) => isInside(nodekb, root))) {
       throw new Error(
@@ -217,7 +222,7 @@ export function resolveLibrary({ kb, lib, workspace, config } = {}) {
   }
 
   // 2) 名字
-  const name = kb && String(kb).trim()
+  const name = kbName
   if (name) {
     const entry = registries.get(name)
     if (entry) {
@@ -234,7 +239,7 @@ export function resolveLibrary({ kb, lib, workspace, config } = {}) {
       if (wsLib) return wsLib
     }
     const names = [...registries.keys(), ...discover().map((r) => r.name)]
-    throw new Error(`未注册的库: ${name}（可用: ${names.join(', ') || '无'}；或用 lib 参数给绝对路径）`)
+    throw new Error(`未注册的库: ${name}（可用: ${names.join(', ') || '无'}；kb 也可以直接传库目录路径）`)
   }
 
   // 3) 无参：工作区自带 → 工作区里唯一发现 → 唯一的注册表库

package/lib/host/prompt.js

@@ -20,7 +20,7 @@ export const DEFAULT_PROMPT = [
   '- 写库：`kb_write`（append/replace/create，或对显式节点用 mode=node）。写前校验 TID 与标签独占一行，写后立刻 `kb_diag` 报悬空引用/重复定义；用 write 做这些没有任何一层会拦。',
   '- 读库：先 `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 全库只能定义一次。',
+  '- 引用分两种，别混：**结构**用 `[[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=…]]`）。',
 ].join('\n')
 

package/lib/host/routes.js

@@ -11,6 +11,7 @@ import { render_node, render_subtree, toc_tree, node_info, resolve_path } from '
 import { search, formatSearch } from '../engine/search.js'
 import { diag } from '../engine/diag.js'
 import { extractRefs } from '../engine/parse.js'
+import { refsToDef, formatDefRead } from '../engine/defs.js'
 import { renameFileNode, formatRename } from '../engine/rename.js'
 import { openLibrary, knownLibraries, whereInfo, workspaceOf } from './runtime.js'
 import { promptState } from './prompt.js'
@@ -187,6 +188,40 @@ export function registerRoutes(ctx, config) {
         return
       }
 
+      if (url.pathname === `${PREFIX}/defs`) {
+        const lib = open()
+        const id = q.get('id')
+        if (id) {
+          const def = lib.defs.get(id)
+          if (!def) {
+            send(res, 404, { error: `未找到定义: ${id}`, kb: lib.name })
+            return
+          }
+          const refs = refsToDef(lib.nodes, id)
+          send(res, 200, {
+            kb: lib.name,
+            id,
+            owner_tid: def.ownerTid,
+            owner_title: def.ownerTitle || '',
+            source: def.source,
+            body: def.body,
+            count: def.count,
+            refs,
+            text: formatDefRead(def, refs),
+          })
+          return
+        }
+        const defs = [...lib.defs.values()].map((d) => ({
+          id: d.id,
+          owner_tid: d.ownerTid,
+          source: d.source,
+          chars: String(d.body || '').length,
+          count: d.count,
+        }))
+        send(res, 200, { kb: lib.name, count: defs.length, defs })
+        return
+      }
+
       if (url.pathname === `${PREFIX}/source`) {
         const lib = open()
         const target = q.get('tid') || 'root'

package/lib/host/tools.js

@@ -13,6 +13,7 @@ import { render_node, render_subtree, toc_lines, node_info, resolve_path } from
 import { search, formatSearch } from '../engine/search.js'
 import { diag } from '../engine/diag.js'
 import { extractRefs } from '../engine/parse.js'
+import { refsToDef, formatDefRead } from '../engine/defs.js'
 import { renameFileNode, formatRename } from '../engine/rename.js'
 import { scaffold } from '../engine/scaffold.js'
 import { writeInto } from '../engine/write.js'
@@ -30,11 +31,7 @@ export function toolState() {
 
 const KB_PARAM = {
   type: 'string',
-  description: '库名（注册表里的名字，或工作区自带的 workspace）。省略则用工作区 .nodekb；都不存在时用唯一已注册的库。',
-}
-const LIB_PARAM = {
-  type: 'string',
-  description: '库根路径的备用写法：技能目录或其下的 .nodekb 绝对路径（也可相对工作区）。仅当库没有注册名时使用。',
+  description: '库：名字（注册表/工作区里的名字）或目录路径（技能目录或其 .nodekb）。省略则用工作区默认库。',
 }
 
 function text(t) {
@@ -60,7 +57,7 @@ function allowedRoots(config, exec) {
 /** 库定位失败时补一句「有哪些库可用」，别让模型瞎猜 */
 function locate(config, exec, args) {
   try {
-    return openLibrary(config, exec, { kb: args.kb, lib: args.lib })
+    return openLibrary(config, exec, { kb: args.kb })
   } catch (e) {
     const hint = libraryHint(config, exec)
     const err = new Error(`${e.message}${hint ? `\n${hint}` : ''}`)
@@ -100,17 +97,14 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_read',
     description:
-      '读取 nodekb 知识库的一个节点。target 是 TID（如 doc:03-工程经验与坑:3.1）或唯一前缀（如 3.1 不行、doc:03 可以）。' +
-      'mode 默认 subtree = 整支渲染（本节点的 [[TID]] 引用就地展开成内容，再递归子节点）；' +
-      'toc = 只看结构不看正文（每个节点一行：tid · 标题 · 字符数，适合先定位再读）；' +
-      'node = 只读本节点自身（不含子节点，也不展开子节）；raw = 元信息 + 原始内容（含未展开的 [[TID]]）。' +
-      '比 read 工具好在：一次拿到装配好的上下文，且 TID 不受文件行号漂移影响。超过 maxlen 会报错并提示改用 toc/node。',
+      '读知识库的一个节点。target = TID 或其唯一前缀（空/"." = 库根），也可以是 <tscl id> 定义的名字（回定义体、定义处、被谁引用）。' +
+      'mode: subtree（默认，整支投影）| toc（只看结构，' +
+      '先定位再读）| node（只本节点）| raw（元信息+原文）。比 read 好在 TID 不随行号漂移；超 maxlen 会报错并提示换 toc/node。',
     parameters: {
       type: 'object',
       properties: {
         target: { type: 'string', description: '节点 TID 或其唯一前缀。空字符串或 "." 表示库根。' },
         kb: KB_PARAM,
-        lib: LIB_PARAM,
         mode: {
           type: 'string',
           enum: ['subtree', 'node', 'toc', 'raw'],
@@ -132,8 +126,26 @@ export function buildTools(ctx, config) {
 
       const tid = resolve_path(lib.nodes, target)
       if (tid === null) {
+        // target 也可能是 tscl 定义 id（值的老家可能只是一句话，没有节点）
+        const def = lib.defs.get(target)
+        if (def) {
+          return {
+            tid: target,
+            kind: 'def',
+            title: def.ownerTitle || '',
+            type: '',
+            source: def.source || '',
+            kb: lib.name,
+            mode,
+            chars: String(def.body || '').length,
+            text: warnPrefix(lib) + formatDefRead(def, refsToDef(lib.nodes, target)),
+          }
+        }
         const cands = [...lib.nodes.keys()].filter((t) => t.startsWith(target) || t.startsWith(target + ':')).sort().slice(0, 10)
-        throw new Error(`未找到节点: ${target}${cands.length ? `；候选: ${cands.join('、')}` : ''}`)
+        const defCands = [...lib.defs.keys()].filter((d) => d.includes(target)).sort().slice(0, 5)
+        throw new Error(
+          `未找到节点: ${target}${cands.length ? `；候选: ${cands.join('、')}` : ''}${defCands.length ? `；tscl 定义候选: ${defCands.join('、')}` : ''}`,
+        )
       }
 
       let out
@@ -173,15 +185,13 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_search',
     description:
-      '在 nodekb 知识库里检索（中文自然语言可用：连续中文按 2-gram 拆分并过滤虚词，多词命中加权，无命中时退化为整句子串匹配）。' +
-      '返回每条命中的稳定 TID（positional=true 表示命中的是位置型段落，tid 已上溯到文件/显式节点，ref 是实际命中点）、类型、标题、源文件行号与命中片段。' +
-      '用 kb_search 找到 tid，再用 kb_read 读，比 grep 后逐个 read 省往返。',
+      '检索知识库（中文 2-gram + 多词加权 + 子串兜底）。返回稳定 TID、类型、标题、源行、片段。' +
+      '先 kb_search 拿 tid 再 kb_read，比 grep 后逐个 read 省往返。',
     parameters: {
       type: 'object',
       properties: {
         query: { type: 'string', description: '检索词或自然语言问句。' },
         kb: KB_PARAM,
-        lib: LIB_PARAM,
         type: { type: 'string', description: '只保留该类型的节点（如 doc / todo / handover）。' },
         limit: { type: 'integer', description: '返回条数上限，默认 10。' },
         offset: { type: 'integer', description: '跳过前 N 条，用于翻页。' },
@@ -214,14 +224,12 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_diag',
     description:
-      '知识库结构自检。errors = 真损坏（悬空引用 [[TID]]、引用位置型段落 TID、循环引用、孤儿节点、树环、重复 TID）；' +
-      'warnings = 疑似内容漂移（同一段文字出现在多个节点 / 节点内重复行），默认不影响结论。' +
-      '改完 md 之后跑一次，比人工核对可靠。库根可放 diag_ignore.json 豁免样板块。',
+      '结构自检。errors = 真损坏（悬空/位置型引用、循环、孤儿、树环、重复 TID、tscl 定义问题）；' +
+      'warnings = 疑似漂移（同一段文字出现在多处），默认不算失败。写完 md 就跑一次。',
     parameters: {
       type: 'object',
       properties: {
         kb: KB_PARAM,
-        lib: LIB_PARAM,
         strict: { type: 'boolean', description: '严格模式：把 warnings 也算失败。' },
       },
     },
@@ -246,14 +254,13 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_backlinks',
     description:
-      '反查：谁引用了这个节点（[[TID]] 指向它）。改 TID / 删节点之前先跑，能一次列出所有会断的地方——' +
-      '比全库 grep 更准（只认真实引用语法，不受正文里偶然出现的同名文字干扰）。',
+      '反查：谁引用了这个 id（`[[node=…]]`/`[[tscl=…]]`/旧式 `[[TID]]` 都算）。改 TID 或删节点前先跑，' +
+      '比全库 grep 准——只认真实引用语法。',
     parameters: {
       type: 'object',
       properties: {
         target: { type: 'string', description: '节点 TID 或其唯一前缀。' },
         kb: KB_PARAM,
-        lib: LIB_PARAM,
       },
       required: ['target'],
     },
@@ -282,9 +289,8 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_rename',
     description:
-      '重命名库里的一个 md 文件，并把全库指向它的 [[TID]] 引用一起改写（含 [[tid:1.2]] 这种子节点引用）。' +
-      'nodekb 的 TID 由文件名派生，所以「用 mv / 编辑器改名」必然留下一堆悬空引用；要么用这个工具，' +
-      '要么改名后自己跑 kb_diag 逐个修。写前会重读校验，别人刚改过的文件不覆盖、只报出来。',
+      '重命名 md 文件并改写全库指向它的引用（含子节点）。TID 由文件名派生，所以用 mv 改名必然留悬空引用；' +
+      '写前重读校验，别人刚改过的文件跳过不覆盖。',
     parameters: {
       type: 'object',
       properties: {
@@ -292,7 +298,6 @@ export function buildTools(ctx, config) {
         new_name: { type: 'string', description: '新文件名（.md 可省略，不能带目录）。' },
         dry_run: { type: 'boolean', description: 'true = 只报「会改哪些引用」，不动文件。' },
         kb: KB_PARAM,
-        lib: LIB_PARAM,
       },
       required: ['target', 'new_name'],
     },
@@ -313,13 +318,11 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_vcs_status',
     description:
-      '查看知识库内嵌 git 仓库的状态（最近提交 + 未提交改动）。nodekb 每次解析后会自动快照，' +
-      '所以这里能看到「库的改动历史」；文件系统上有改动但没进快照时也会列出来。git 不可用时返回说明而不报错。',
+      '库内嵌 git 的快照历史与未提交改动（每次解析后自动快照）；git 不可用时只说明不报错。',
     parameters: {
       type: 'object',
       properties: {
         kb: KB_PARAM,
-        lib: LIB_PARAM,
       },
     },
     output: {
@@ -365,11 +368,8 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_init',
     description:
-      '为一个项目建 .nodekb 知识库骨架（幂等：已存在的文件不覆盖）。' +
-      '当用户要在项目里沉淀长期知识、而你准备开始写第一份文档之前，先调这个——' +
-      '它一次铺出 doc/ facts/ lessons/ todo/ index/entry.md 与 .nodekb/README.md 里的落位约定，' +
-      '比你自己拿 write 从零设计目录结构更省事，也让后续 Agent 知道该往哪写。' +
-      '已经有 .nodekb/ 就不要调（先用 kb_list 看）。',
+      '建 .nodekb 骨架（幂等，已有的不覆盖）：doc/ lessons/ todo/ index/entry.md + 落位约定。' +
+      '准备手写 docs/*.md 之前先调这个；已经有 .nodekb/ 就别调（先 kb_list 看）。',
     parameters: {
       type: 'object',
       properties: {
@@ -403,10 +403,8 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_write',
     description:
-      '往 nodekb 库里写内容，并在写后立刻自检（悬空引用/位置型引用/重复块）。' +
-      '这是「用知识库管知识」的正路：同样写 md，但写前校验 TID 与 <node> 独占一行，写后把结构错误当场报回来；' +
-      '直接用 write/edit 没有这一层。' +
-      'mode=append 追加到文件（不存在则创建）、replace 整篇覆盖、create 只新建、node 就地改写一个 <node> 块。',
+      '写库并立刻自检（悬空引用/重复定义/结构错误当场报回来）。写前校验 TID 与 <node> 独占一行；' +
+      '用 write/edit 直接改没有这层。mode=append（追加，不存在则建）| replace（整篇）| create（只新建）| node（就地改一个 <node> 块）。',
     parameters: {
       type: 'object',
       properties: {
@@ -421,7 +419,6 @@ export function buildTools(ctx, config) {
           description: '默认：路径→append，TID→node。create 遇到已存在会报错，避免覆盖。',
         },
         kb: KB_PARAM,
-        lib: LIB_PARAM,
       },
       required: ['target', 'content'],
     },

package/package.json

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

@@ -1,17 +1,17 @@
 ---
 name: project-node-memory-guide
-description: 用 .nodekb/ + kb_* 工具沉淀项目长期知识（设计决策、踩坑、事实常量、待办、交接）时的写法规范——什么时候该写、文件怎么分、TID 怎么起、唯一事实用 tscl 怎么共享、先读什么再写什么。准备手写 docs/*.md 之前先读这一条。
+description: 用 .nodekb/ + kb_* 工具沉淀项目长期知识（设计决策、踩坑、事实常量、待办、交接）时的写法规范——什么时候该写、文件怎么分、TID 怎么起、唯一事实用 tscl 怎么共享、先读什么再写什么。准备创建知识库时先读该技能。
 ---
 
 # 写项目节点知识库（`.nodekb/`）
 
 ## 什么时候该写
 
-值得沉淀的：**设计决策与理由**、**踩过的坑（症状 + 根因 + 对策）**、**事实常量**（版本号、路径、阈值、接口字段）、**待办与交接**、**环境和操作手册**。
+值得沉淀的：**设计决策与理由**、**踩过的坑（症状 + 根因 + 对策）**、**事实常量**（版本号、路径、阈值、接口字段）、**待办与交接**、**环境和操作手册**等。
 
 不该写的：一次性的调试输出、能从代码直接读出来的内容（函数签名、目录列表）、临时状态。判据是「下次换个人/换个会话，不知道这条会不会重做一遍错事」。
 
-## 先读，再写
+## 先读再写
 
 ```
 kb_read mode=toc            # 结构 + 每节字符数，几百 token
@@ -19,44 +19,45 @@ kb_read target=<TID>        # 按需读一支
 kb_search query=...         # toc 里找不到再搜
 ```
 
-**不要**一次把整库读进上下文。写之前先确认：这个结论是不是已经写在别处了？是的话改那一处，别新开一条（同一结论写两遍，两份迟早打架）。
+**不要**一次把整库读进上下文。写之前先确认：这个结论是不是已经写在别处了？是的话改那一处，不要把同一结论写两遍。
 
-## 目录怎么分
+## 目录规划
 
-| 目录 | 放什么 | 判据 |
-|---|---|---|
-| `doc/` | 主题文档：架构、模块、流程、配置 | 「是什么、怎么运转」 |
-| `lessons/` | 踩坑记录 | 「症状 → 根因 → 对策」三行齐全 |
-| `todo/` | 未完成事项、阻塞、交接 | 有明确的下一步动作 |
-| `index/entry.md` | 总入口与落位约定 | 只放导航，不放正文 |
+| 目录             | 放什么                           | 判据                           |
+| ---------------- | -------------------------------- | ------------------------------ |
+| `doc/`           | 主题文档：架构、模块、流程、配置 | 「是什么、怎么运转」           |
+| `lessons/`       | 踩坑记录                         | 「症状 → 根因 → 对策」三行齐全 |
+| `todo/`          | 未完成事项、阻塞、交接           | 有明确的下一步动作             |
+| `index/entry.md` | 总入口与落位约定                 | 只放导航，不放正文             |
 
-这张表是「不知道放哪时」的默认答案，**不是白名单**：项目没有待办就别建 `todo/`，需要 `adr/`、`api/`、`runbook/`、`metrics/` 就自己加；节点 `type` 同样自由（`type="decision"`、`type="api"` 都行）。
+这张表是**推荐做法**，你可以自行根据项目实际情况进行规划。如项目没有待办就别建 `todo/`，需要 `adr/`、`api/` 等就自己加；节点 `type` 同样自由。
 
 一个主题一个文件，**单文件取 < 4KB**；变大就按子主题拆成 `## 3.x` 段或独立文件。
 
-## 两种引用，别混
+## 两种引用方法
 
-| 写法 | 渲染成 | 用在 |
-|---|---|---|
-| `[[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:abi">
-三条硬规则：1) 只用 C ABI；2) 名字加前缀 `fm_`；3) 导出结构体必须定长。
+<tscl id="fact:sample">
+tscl 机制支持段落标记与行内标记
 </tscl>
+
+<tscl id="fact:sample2">tscl 机制支持段落标记与行内标记</tscl>
 ```
 
 规则：
 
-- **同一个 id 全库只能定义一次**，否则 `kb_diag` 报 error（重复定义）。
-- id 不能和节点 TID 同名（命名空间冲突 = error）。惯例：值用 `fact:` 前缀，结构用目录前缀。
-- 宏体**跨行**时不要内联进表格单元格（diag 会 warning，渲染也会断行）。
+- **同一个 id 全库只能定义一次**。
+- id 不能和节点 TID 同名。惯例：值用 `fact:` 前缀，结构用目录前缀。
+- 定义可以**就地写在正文句子里**：`当前版本号为：<tscl id="fact:ver">v1.23.45</tscl>，向下兼容 v1.22。`（渲染时标签被剥掉，别处写 `[[tscl="fact:ver"]]` 展开同一个值）。这种句内定义**必须单行闭合**。
+- 宏体**跨行**时不要内联进表格单元格；定义本身也别写进表格行（`|` 会破格）。
+- 要核一个值，`kb_read target=<定义 id>` 直接回定义体、定义处、被谁引用。
 - 定义块内部的 `##` **不会**变成节点——它只是文本。
 
-旧写法 `[[TID]]` 仍能解析（有定义时当宏、否则当链接），但 `kb_diag` 会 warning，2.0 移除。
-接手老库时按 `kb_diag` 的「旧语法引用」清单逐处改成 `[[node=…]]` 或 `[[tscl=…]]`，改完再跑一次 `kb_diag`。
-
 ## TID 规则
 
 - 文件节点：`<目录>:<文件名 slug>`，例如 `doc/03-工程经验与坑.md` → `doc:03-工程经验与坑`
@@ -72,12 +73,13 @@ kb_write target=<显式节点TID>          mode=node    content=...   # 只换 <
 kb_write target=doc/03-...md          mode=append  content=...
 ```
 
-- 写完**看返回值里的校验结果**：悬空引用、重复定义、`<node>` 没独占一行，都会当场报回来。看到就修，别留着。
+- 写完**看返回值里的校验结果**：悬空引用、重复定义、`<node>` 没独占一行，都会当场报回来。
 - 改已有内容用 `append` / `node`，不要 `replace` 整篇（会丢掉别人刚写的段落）。
 - 新建文件前先 `kb_read mode=toc` 确认没有同主题的旧文件。
 
-## 三个反例
+## 注意事项
+
+1. 不要把整段对话贴进 `doc/` —— 记的是过程，不是结论。
+2. 不要把同一件事在 `doc/` 和 `lessons/` 各写一份 —— 抽成 `<tscl>` 定义，两处都引用它。
+
 
-1. 把整段对话贴进 `doc/` —— 记的是过程，不是结论。
-2. 同一件事在 `doc/` 和 `lessons/` 各写一份 —— 抽成 `<tscl>` 定义，两处都引用它。
-3. 只写「改了什么」不写「为什么」 —— 半年后没人知道能不能改回去。