project-node-memory 1.4.1 → 1.4.4

package/README.md

@@ -197,7 +197,15 @@ config:
 `kb_diag` 会报；写成 `<tscl>` 定义后各处只留一个引用，改一处全库同步。
 
 硬规则：`<node>` / `</node>` 必须各占整行；`<tscl>` 内部不做结构解析（里面的 `##` 不算标题）；
-同一 `tscl` id 全库只能定义一次，且不能与节点 TID 同名。
+同一 `tscl` id 全库只能定义一次，且不能与节点 TID 同名。`<node tid="…">` 与
+`<node name="…">` 等价（`title="…"` 可另给显示名）；缺 `name`/`tid` 的 `<node>` 会整段
+按正文处理并在 `kb_diag` 里报 warning —— 不会静默消失，`</node>` 也不会漏进正文。
+
+代码区（``` 围栏与 `行内代码`）里的 `[[…]]` 和 `<tscl>` 都当**示例**：不解析、不计引用、
+不算定义。写文档时不必再改全角括号。
+
+TID 支持前缀兜底：`kb_read target=doc:02` 能命中 `doc:02-运行环境`（多个候选中取唯一的
+文件/文件夹节点；纯前缀歧义仍报错并给候选）。
 
 定义也可以**就地写在句子中间**，渲染时标签被剥掉、值留在原处：
 

package/lib/engine/defs.js

@@ -59,15 +59,16 @@ export function isMultiline(body) {
   return String(body || '').replace(/\s+$/, '').includes('\n')
 }
 
-/** 谁在正文里引用了这个定义（[[tscl="id"]]，或指向它的旧语法裸引用）→ [{tid,title,source,line,legacy}]
- *  `ownerTid` 传进来的话，定义所在节点自己不算「引用者」——定义就写在它里面，
- *  再把它列成一处引用会让计数虚高。 */
+/** 谁在正文里引用了这个定义（[[tscl="id"]]，或指向它的旧语法裸引用）
+ *  → [{tid,title,source,line,legacy,self}]
+ *  ownerTid 只用来标记「定义所在节点自己也引用了一次」（self:true）；计数时排除，
+ *  但列表里保留，免得用户以为那处引用凭空消失。line 是文件内的绝对行号。 */
 export function refsToDef(nodes, id, ownerTid = '') {
   const out = []
   for (const node of nodes.values()) {
-    if (ownerTid && node.tid === ownerTid) continue
     const content = String(node.content || '')
     if (!content.includes(id)) continue
+    const base = Number(node.content_line || 1)
     for (const ref of extractRefs(content)) {
       if (ref.id !== id) continue
       if (ref.kind !== 'tscl' && ref.kind !== 'legacy') continue
@@ -75,8 +76,9 @@ export function refsToDef(nodes, id, ownerTid = '') {
         tid: node.tid,
         title: node.title || '',
         source: node.source || '',
-        line: content.slice(0, ref.index).split('\n').length,
+        line: base + content.slice(0, ref.index).split('\n').length - 1,
         legacy: ref.kind === 'legacy',
+        self: Boolean(ownerTid) && node.tid === ownerTid,
       })
     }
   }
@@ -89,14 +91,22 @@ export function formatDefRead(def, refs = []) {
   const src = fileOf(def.source)
   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 outside = refs.filter((r) => !r.self)
+  const selfRefs = refs.filter((r) => r.self)
+  if (outside.length) {
+    lines.push('', `被引用 ${outside.length} 处：`)
+    for (const r of outside) {
       const at = fileOf(r.source)
       lines.push(`- ${r.tid}${r.title ? ` · ${r.title}` : ''}${at ? `（${at}#L${r.line}）` : ''}${r.legacy ? `  ← 旧语法，建议 [[tscl="${def.id}"]]` : ''}`)
     }
   } else {
     lines.push('', '尚未被任何 [[tscl="…"]] 引用。')
   }
+  if (selfRefs.length) {
+    const where = selfRefs
+      .map((r) => `${fileOf(r.source) || r.tid}#L${r.line}`)
+      .join('、')
+    lines.push('', `定义所在节点自己也引用了 ${selfRefs.length} 次（不计入上面的引用数）: ${where}`)
+  }
   return lines.join('\n')
 }

package/lib/engine/diag.js

@@ -174,8 +174,11 @@ function typeCounts(nodes) {
  * @returns {{report:object, code:number}}
  */
 export function diag(nodes, { problems = [], strict = false, libRoot, defs = null } = {}) {
-  const errors = [...problems]
-  const warnings = []
+  // 解析期的「形状问题」分两级：真损坏（重复 TID、树环）算 error；
+  // 手写 <node> 出错（缺 name、孤立 </node>）算 warning —— 那行按正文处理，库仍可用。
+  const SOFT_PARSE = /^(显式节点缺|孤立的 <\/node>)/
+  const errors = problems.filter((p) => !SOFT_PARSE.test(String(p)))
+  const warnings = problems.filter((p) => SOFT_PARSE.test(String(p)))
 
   // 定义表：全库 <tscl id="x">…</tscl>
   let defsMap = defs

package/lib/engine/mdlib.js

@@ -58,10 +58,13 @@ function toPosix(p) {
 /**
  * 解析单个 md 文件为节点列表（文件节点 + 隐式 H2 段 + 显式 <node>，按物理行序）。
  */
-export function parse_file(absPath, file_tid, folder_type, parent_tid) {
+export function parse_file(absPath, file_tid, folder_type, parent_tid, problems) {
   const text = fs.readFileSync(absPath, 'utf8').replace(/^\uFEFF+/, '')
   const lines = splitLines(text)
   const rel = toPosix(absPath)
+  const warn = (msg) => {
+    if (Array.isArray(problems)) problems.push(`${msg}（${rel}）`)
+  }
 
   // 1) 先找 H1（围栏内的 # 不算标题）：它决定文件节点的 title，且整行不进任何节点正文
   let h1 = null
@@ -94,6 +97,7 @@ export function parse_file(absPath, file_tid, folder_type, parent_tid) {
     'file',
   )
   nodes.push(file_node)
+  file_node.content_line = h1_line ? h1_line + 1 : 1
 
   let first_node_tid = null // 文件根（第一个 <node> 的 name）
   let sec_node = null
@@ -139,16 +143,17 @@ export function parse_file(absPath, file_tid, folder_type, parent_tid) {
       // 内层 <node>（须单行闭合；只认行首，正文里提到 <node> 不算）
       if (line.replace(/^\s+/, '').startsWith('<node')) {
         const attrs = Object.fromEntries([...line.matchAll(ATTR_RE)].map((m) => [m[1], m[2]]))
-        const name = (attrs.name || '').trim()
+        const name = (attrs.name || attrs.tid || '').trim()
         if (name) {
           const n = newNode(
             name,
-            name,
+            (attrs.title || '').trim() || name,
             (attrs.type || '').trim() || folder_type,
             (attrs.parent || '').trim() || default_parent(),
             lineno,
             `${rel}#L${lineno}`,
           )
+          n.content_line = lineno + 1
           nodes.push(n)
           const gt = line.indexOf('>')
           const rest = gt >= 0 ? line.slice(gt + 1) : ''
@@ -156,20 +161,32 @@ export function parse_file(absPath, file_tid, folder_type, parent_tid) {
             n.content.push(rest.split('</node>')[0])
             const after = rest.split('</node>').slice(1).join('</node>')
             if (after) stack[stack.length - 1].content.push(after)
+          } else {
+            stack.push(n)
           }
+        } else {
+          // 缺 name/tid：不能静默吞掉（否则开标签消失、闭标签漏进正文）
+          warn(`显式节点缺 name（或 tid）属性: <node> 在第 ${lineno} 行，整段按正文处理`)
+          content_target().content.push(line)
         }
         continue
       }
       stack[stack.length - 1].content.push(line)
       continue
     }
+    if (line.trim() === '</node>') {
+      warn(`孤立的 </node>: 第 ${lineno} 行没有对应的 <node>（已忽略，不会漏进正文）`)
+      continue
+    }
     if (line.replace(/^\s+/, '').startsWith('<node')) {
       const attrs = Object.fromEntries([...line.matchAll(ATTR_RE)].map((m) => [m[1], m[2]]))
-      const name = (attrs.name || '').trim()
+      const name = (attrs.name || attrs.tid || '').trim()
       if (name) {
         const parent = (attrs.parent || '').trim() || default_parent()
         const ptype = (attrs.type || '').trim() || folder_type
-        const n = newNode(name, name, ptype, parent, lineno, `${rel}#L${lineno}`)
+        const title = (attrs.title || '').trim() || name
+        const n = newNode(name, title, ptype, parent, lineno, `${rel}#L${lineno}`)
+        n.content_line = lineno + 1
         nodes.push(n)
         if (first_node_tid === null) first_node_tid = name
         const gt = line.indexOf('>')
@@ -180,6 +197,9 @@ export function parse_file(absPath, file_tid, folder_type, parent_tid) {
         } else {
           stack.push(n)
         }
+      } else {
+        warn(`显式节点缺 name（或 tid）属性: <node> 在第 ${lineno} 行，整段按正文处理`)
+        ;(sec_node || file_node).content.push(line)
       }
       continue
     }
@@ -190,13 +210,21 @@ export function parse_file(absPath, file_tid, folder_type, parent_tid) {
       const tid = section_tid(file_tid, title, sec_index)
       sec_node = newNode(tid, title, folder_type, default_parent(), lineno, `${rel}#L${lineno}`, [], 'section')
       sec_node.positional = true // 位置型段落 TID：插章节就漂移，不可作引用/检索句柄
+      sec_node.content_line = lineno + 1
       nodes.push(sec_node)
       continue
     }
     ;(sec_node || file_node).content.push(line)
   }
 
-  for (const n of nodes) n.content = n.content.join('\n').trim()
+  for (const n of nodes) {
+    const joined = n.content.join('\n')
+    // trim 会吃掉节点正文开头的空行；行号基准要跟着往下挪，否则引用定位偏前。
+    const leadChars = joined.length - joined.replace(/^\s+/, '').length
+    const leadLines = (joined.slice(0, leadChars).match(/\n/g) || []).length
+    n.content_line = Number(n.content_line || 1) + leadLines
+    n.content = joined.trim()
+  }
   return nodes
 }
 
@@ -271,7 +299,7 @@ export function parse_library(lib_dir, problems) {
       const md = path.join(dir, name)
       const stem = slugify(path.basename(name, path.extname(name)))
       const fileTid = ftid !== ROOT_TID ? `${ftid}:${stem}` : stem
-      for (const node of parse_file(md, fileTid, ftype, ftid)) {
+      for (const node of parse_file(md, fileTid, ftype, ftid, problems)) {
         if (nodes.has(node.tid)) {
           duplicate(node.tid, name)
           continue

package/lib/engine/parse.js

@@ -43,10 +43,14 @@ export function anyRefRegex() {
   return new RegExp(ANY_REF_SOURCE, 'g')
 }
 
-/** 一次扫过三种引用（保序），返回 [{kind:'node'|'tscl'|'legacy', id, raw, index}] */
+/** 一次扫过三种引用（保序），返回 [{kind:'node'|'tscl'|'legacy', id, raw, index}]
+ *  围栏与行内代码里的 `[[…]]` 是「示例」，不是引用：跳过（否则写文档会自我投毒）。 */
 export function extractRefs(text) {
+  const src = String(text)
+  const regions = codeRegions(src)
   const out = []
-  for (const m of String(text).matchAll(new RegExp(ANY_REF_SOURCE, 'g'))) {
+  for (const m of src.matchAll(new RegExp(ANY_REF_SOURCE, 'g'))) {
+    if (inCode(regions, m.index)) continue
     const kind = m[1] !== undefined ? 'node' : m[2] !== undefined ? 'tscl' : 'legacy'
     const id = m[1] !== undefined ? m[1] : m[2] !== undefined ? m[2] : m[3]
     out.push({ kind, id, raw: m[0], index: m.index })
@@ -54,6 +58,38 @@ export function extractRefs(text) {
   return out
 }
 
+/** 代码区段（围栏块与行内代码），[start, end) 半开区间，按出现顺序 */
+export function codeRegions(text) {
+  const s = String(text)
+  const regions = []
+  let offset = 0
+  let open = -1
+  let openMark = ''
+  for (const line of s.split('\n')) {
+    const m = /^\s{0,3}(`{3,}|~{3,})/.exec(line)
+    if (m) {
+      if (open < 0) {
+        open = offset
+        openMark = m[1]
+      } else if (m[1][0] === openMark[0] && m[1].length >= openMark.length) {
+        regions.push([open, offset + line.length])
+        open = -1
+      }
+    }
+    offset += line.length + 1
+  }
+  if (open >= 0) regions.push([open, s.length])
+  for (const m of s.matchAll(/(`+)([^`\n]*?)\1/g)) {
+    const start = m.index
+    if (!regions.some(([a, b]) => start >= a && start < b)) regions.push([start, start + m[0].length])
+  }
+  return regions
+}
+
+export function inCode(regions, index) {
+  return regions.some(([a, b]) => index >= a && index < b)
+}
+
 export function is_valid_tid(tid) {
   return TID_RE.test(String(tid))
 }
@@ -71,10 +107,13 @@ export function slugify(name) {
   return s.replace(/^[-_]+/, '').replace(/[-_]+$/, '')
 }
 
-/** 提取全部 <tscl> 定义 → [[tid, text]]（保序） */
+/** 提取全部 <tscl> 定义 → [[tid, text]]（保序）。代码块里的定义是示例，不算定义。 */
 export function extract_defs(content) {
+  const src = String(content)
+  const regions = codeRegions(src)
   const out = []
-  for (const m of String(content).matchAll(new RegExp(TSCL_SOURCE, 'gs'))) {
+  for (const m of src.matchAll(new RegExp(TSCL_SOURCE, 'gs'))) {
+    if (inCode(regions, m.index)) continue
     out.push([m[1], m[2]])
   }
   return out
@@ -87,9 +126,23 @@ export function extract_refs(content) {
   return out
 }
 
-/** 剥离 <tscl> 标签本身，保留内部文本（渲染投影的基础变换） */
+/** 抹掉指定 id 的定义块（整块删除，不只是标签）。代码块里的不算定义，保持原样。 */
+export function strip_defs(content, ids) {
+  const src = String(content)
+  if (!ids || !ids.size) return src
+  const regions = codeRegions(src)
+  return src.replace(new RegExp(TSCL_SOURCE, 'gs'), (m, id, body, offset) =>
+    !inCode(regions, offset) && ids.has(id) ? '' : m,
+  )
+}
+
+/** 剥离 <tscl> 标签本身，保留内部文本（渲染投影的基础变换）。代码块里的标签是示例，保留原样。 */
 export function strip_tags(content) {
-  return String(content).replace(new RegExp(TSCL_SOURCE, 'gs'), '$2')
+  const src = String(content)
+  const regions = codeRegions(src)
+  return src.replace(new RegExp(TSCL_SOURCE, 'gs'), (m, id, body, offset) =>
+    inCode(regions, offset) ? m : body,
+  )
 }
 
 /** 同一节点内重复定义的 tid */

package/lib/engine/registry.js

@@ -201,10 +201,11 @@ export function resolveLibrary({ kb, lib, workspace, config, extraRoots = [] } =
   const kbName = looksLikePath ? undefined : raw
   const exclude = config && config.exclude
   const discover = () => discoverLibraries(ws, { exclude })
-  const registries = loadRegistries(
-    config && config.registries ? config.registries : defaultRegistryPaths(ws),
-    config && config.libraries,
-  )
+  // config.registries 是「额外」路径，不是「替代」：否则项目里的 kb_registry.json
+  // （kb_register 写的那份）永远读不到，登记完立刻就不认。
+  const cfgRegs = (config && config.registries) || []
+  const regPaths = [...cfgRegs, ...defaultRegistryPaths(ws).filter((p) => !cfgRegs.includes(p))]
+  const registries = loadRegistries(regPaths, config && config.libraries)
 
   // 1) 显式路径
   if (explicit) {
@@ -284,10 +285,11 @@ export function resolveLibrary({ kb, lib, workspace, config, extraRoots = [] } =
  */
 export function listLibraries({ workspace, config, scope, includeHidden = false } = {}) {
   const ws = path.resolve(workspace || process.cwd())
-  const registries = loadRegistries(
-    config && config.registries ? config.registries : defaultRegistryPaths(ws),
-    config && config.libraries,
-  )
+  // config.registries 是「额外」路径，不是「替代」：否则项目里的 kb_registry.json
+  // （kb_register 写的那份）永远读不到，登记完立刻就不认。
+  const cfgRegs = (config && config.registries) || []
+  const regPaths = [...cfgRegs, ...defaultRegistryPaths(ws).filter((p) => !cfgRegs.includes(p))]
+  const registries = loadRegistries(regPaths, config && config.libraries)
   const rows = []
   const seen = new Set()
   for (const r of discoverLibraries(ws, { exclude: config && config.exclude })) {

package/lib/engine/render.js

@@ -13,7 +13,7 @@
  */
 
 import path from 'node:path'
-import { anyRefRegex, strip_tags } from './parse.js'
+import { anyRefRegex, strip_tags, strip_defs, codeRegions, inCode } from './parse.js'
 import { ROOT_TID } from './mdlib.js'
 
 const MAX_EMBED = 64 // 单次渲染最多展开的宏个数（防病态文件自引用爆炸）
@@ -73,12 +73,16 @@ function resolveNode(nodes, id) {
  */
 export function expand(text, nodes, seen = [], ctx = {}) {
   const defs = (ctx && ctx.defs) || new Map()
+  // 同一支里既打印定义体、又在引用处展开，会让一个值出现两遍：第二遍渲染时抹掉定义块
+  const rawText = ctx && ctx.suppress && ctx.suppress.size ? strip_defs(text, ctx.suppress) : text
   // 定义块在正文里就地显示为它的内容（标签本身不出现）
-  const source = strip_tags(text)
+  const source = strip_tags(rawText)
+  const regions = codeRegions(source)
   const out = []
   let pos = 0
   let embeds = 0
   for (const m of String(source).matchAll(anyRefRegex())) {
+    if (inCode(regions, m.index)) continue // 代码里的 [[…]] 是示例，原样保留
     out.push(String(source).slice(pos, m.index))
     const kind = m[1] !== undefined ? 'node' : m[2] !== undefined ? 'tscl' : 'legacy'
     const id = m[1] !== undefined ? m[1] : m[2] !== undefined ? m[2] : m[3]
@@ -86,6 +90,7 @@ export function expand(text, nodes, seen = [], ctx = {}) {
 
     // 值嵌入：tscl 显式请求，或旧语法且确有同名定义
     if ((kind === 'tscl' || kind === 'legacy') && defs.has(id)) {
+      if (ctx && ctx.expanded) ctx.expanded.add(id)
       const key = 'tscl:' + id
       if (seen.includes(key)) throw new TransclusionError(cycle_msg(seen, key, nodes))
       if (++embeds > MAX_EMBED) {
@@ -119,14 +124,46 @@ export function render_node(nodes, tid, ctx = {}) {
   return expand(node.content, nodes, [tid], ctx)
 }
 
-/** 渲染整支：递归子树为带标题层级的 md（节点引用只在原文位置出现一次） */
+/** 渲染整支：递归子树为带标题层级的 md（节点引用只在原文位置出现一次）
+ *  两遍：第一遍收集「在这支里被展开过的定义」，第二遍把这些定义块从正文里抹掉——
+ *  否则同一支里既打印定义体、又在引用处展开一次，同一个值出现两遍。 */
 export function render_subtree(nodes, tid, level = 1, ctx = {}) {
+  const node = nodes.get(tid)
+  if (!node) throw new Error(`节点不存在: ${tid}`)
+  if (!ctx._pass2) {
+    const expanded = new Set()
+    renderSubtreeRaw(nodes, tid, level, { ...ctx, expanded })
+    const inside = subtreeTids(nodes, tid)
+    const suppress = new Set(
+      [...expanded].filter((id) => {
+        const def = ctx && ctx.defs ? ctx.defs.get(id) : null
+        return def && inside.has(def.ownerTid)
+      }),
+    )
+    return renderSubtreeRaw(nodes, tid, level, { ...ctx, _pass2: true, suppress })
+  }
+  return renderSubtreeRaw(nodes, tid, level, ctx)
+}
+
+/** 子树内的全部 TID（含自身） */
+export function subtreeTids(nodes, tid) {
+  const out = new Set()
+  const walk = (t) => {
+    if (out.has(t) || !nodes.has(t)) return
+    out.add(t)
+    for (const c of children(nodes, t)) walk(c.tid)
+  }
+  walk(tid)
+  return out
+}
+
+function renderSubtreeRaw(nodes, tid, level, ctx) {
   const node = nodes.get(tid)
   if (!node) throw new Error(`节点不存在: ${tid}`)
   const title = node.title || tid
   const head = '#'.repeat(level) + ' ' + title
   const parts = [head, expand(node.content, nodes, [tid], ctx)]
-  for (const child of children(nodes, tid)) parts.push(render_subtree(nodes, child.tid, level + 1, ctx))
+  for (const child of children(nodes, tid)) parts.push(renderSubtreeRaw(nodes, child.tid, level + 1, ctx))
   return parts.join('\n\n')
 }
 
@@ -184,5 +221,17 @@ export function resolve_path(nodes, p) {
     hits = keys.filter((t) => t.startsWith(target)).sort()
     if (hits.length === 1) return hits[0]
   }
+  // 多个命中：只要其中有唯一的「文件/文件夹」节点，它就是用户想要的
+  // （doc:02 命中 doc:02-运行环境 与 doc:02-运行环境:2.1 —— 后者是前者的子节）
+  if (hits.length > 1) {
+    const containers = hits.filter((t) => {
+      const n = nodes.get(t)
+      return n && (n.kind === 'file' || n.kind === 'folder')
+    })
+    if (containers.length === 1) return containers[0]
+    // 都在同一文件里：取最短的那个（父节点）
+    const shortest = hits.reduce((a, b) => (b.length < a.length ? b : a))
+    if (hits.every((t) => t.startsWith(shortest))) return shortest
+  }
   return null
 }

package/lib/engine/write.js

@@ -91,30 +91,61 @@ export function writeInto(lib, input) {
     const abs = path.isAbsolute(rel) ? path.normalize(rel) : absIn(lib.nodekb, rel)
     if (!fs.existsSync(abs)) fail(`源文件不存在: ${abs}`)
     const raw = fs.readFileSync(abs, 'utf8')
-    // 用 source 里的行号定位（`path#L12-L30`），在行上找 <node …> 与 </node>，替换两者之间
+    // 用 source 里的行号定位开标签，再**向后扫**找最近的 </node>。
+    // （旧实现只扫 from..from+1，于是「标签独占一行」的合法块永远定位失败——死锁。）
     const hm = /#L(\d+)(?:-L(\d+))?/.exec(node.source || '')
     if (!hm) fail('这个节点没有行号信息，无法就地改写；请用相对路径 + mode=replace 整篇重写')
     const from = Number(hm[1]) - 1
-    const to = hm[2] ? Number(hm[2]) : from + 1
     const lines = raw.split('\n')
     let openAt = -1
     let closeAt = -1
-    for (let i = from; i < Math.min(to + 1, lines.length); i++) {
-      if (openAt < 0 && /^\s*<node\b/.test(lines[i])) {
-        openAt = i
+    for (let i = from; i < lines.length; i++) {
+      if (openAt < 0) {
+        if (/^\s*<node\b/.test(lines[i])) {
+          openAt = i
+          // 单行形式 <node …>正文</node>
+          if (/<\/node>/.test(lines[i])) {
+            closeAt = i
+            break
+          }
+        }
         continue
       }
-      if (openAt >= 0 && /^\s*<\/node>\s*$/.test(lines[i])) {
+      if (/^\s*<\/node>\s*$/.test(lines[i])) {
         closeAt = i
         break
       }
     }
-    if (openAt < 0 || closeAt < 0) fail(`无法在 ${rel} 的第 ${hm[1]}–${to} 行定位 <node> 块`)
+    if (openAt < 0) fail(`无法在 ${rel} 第 ${from + 1} 行起找到 <node> 开标签；内容可能已被改动，先 kb_read 重看`)
+    if (closeAt < 0) {
+      fail(
+        `无法在 ${rel} 定位 </node>：开标签在第 ${openAt + 1} 行，` +
+          `向后扫到文件末（第 ${lines.length} 行）都没有独占一行的 </node>。` +
+          `请补上闭合标签，或用相对路径 + mode=replace 整篇重写`,
+      )
+    }
     validateContent(content, path.basename(abs))
     const bodyLines = content.replace(/^\n+|\n+$/g, '').split('\n')
-    lines.splice(openAt + 1, closeAt - openAt - 1, ...bodyLines)
+    if (openAt === closeAt) {
+      // 单行 <node …>旧正文</node> → 就地换掉中间那段
+      const line = lines[openAt]
+      const gt = line.indexOf('>')
+      const head = line.slice(0, gt + 1)
+      lines[openAt] = `${head}${bodyLines.join(' ')}</node>`
+    } else {
+      lines.splice(openAt + 1, closeAt - openAt - 1, ...bodyLines)
+    }
     fs.writeFileSync(abs, lines.join('\n'), 'utf8')
-    return { rel, abs, bytes: Buffer.byteLength(content, 'utf8'), mode, created: false, tid: target }
+    return {
+      rel,
+      abs,
+      bytes: Buffer.byteLength(content, 'utf8'),
+      mode,
+      created: false,
+      tid: target,
+      // 回执里给真实行区间，便于核对
+      lines: `${openAt + 1}–${closeAt + 1}`,
+    }
   }
 
   mode = mode || 'append'

package/lib/host/tools.js

@@ -282,11 +282,11 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_backlinks',
     description:
-      '反查：谁引用了这个 id。建议改 TID 或删节点前先跑。',
+      '反查：谁引用了这个 id（节点 TID 或 <tscl> 定义 id 都认）。建议改 TID 或删节点前先跑。',
     parameters: {
       type: 'object',
       properties: {
-        target: { type: 'string', description: '节点 TID 或其唯一前缀。' },
+        target: { type: 'string', description: '节点 TID 或其唯一前缀；也可以是 <tscl id> 定义的名字。' },
         kb: KB_PARAM,
       },
       required: ['target'],
@@ -297,8 +297,24 @@ export function buildTools(ctx, config) {
     },
     async execute(args, exec) {
       const lib = locate(config, exec, args)
-      const tid = resolve_path(lib.nodes, String(args.target ?? ''))
-      if (tid === null) throw new Error(`未找到节点: ${args.target}`)
+      const raw = String(args.target ?? '').trim()
+      const tid = resolve_path(lib.nodes, raw)
+      if (tid === null) {
+        // 与 kb_read 同一口径：节点找不到时再看是不是 <tscl> 定义
+        const def = lib.defs && (lib.defs.get(raw) || lib.defs.get(raw.replace(/^tscl:/, '')))
+        if (def) {
+          const refs = refsToDef(lib.nodes, def.id, def.ownerTid)
+          const outside = refs.filter((r) => !r.self)
+          const lines = [`引用定义 <tscl id="${def.id}"> 的位置：${outside.length} 处（定义在 ${def.ownerTid}）`]
+          for (const r of outside) {
+            lines.push(`- ${r.tid} · ${r.title}${r.legacy ? '（旧语法）' : ''}  ${r.source}`)
+          }
+          if (!outside.length) lines.push('（没有任何节点展开它）')
+          if (refs.length > outside.length) lines.push(`另有 ${refs.length - outside.length} 处在定义所在节点内部（不计入）`)
+          return { target: def.id, kind: 'def', count: outside.length, backlinks: outside, kb: lib.name, text: warnPrefix(lib) + lines.join('\n') }
+        }
+        throw new Error(`未找到节点或定义: ${args.target}`)
+      }
       const rows = []
       for (const node of lib.nodes.values()) {
         if (node.tid === tid) continue

package/package.json

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

@@ -61,7 +61,10 @@ tscl 机制支持段落标记与行内标记
 ## TID 规则
 
 - 文件节点：`<目录>:<文件名 slug>`，例如 `doc/03-工程经验与坑.md` → `doc:03-工程经验与坑`
-- 显式节点：`<node name="abi">` 里的 `name` 原样就是 TID，可跨文件引用
+- 显式节点：`<node name="abi">` 里的 `name` 原样就是 TID，可跨文件引用（`tid="…"` 等价，`title="…"` 可另给显示名）
+- 手写 `<node>` 时开闭标签各占一行；缺 `name`/`tid` 的块会整段退回正文并在 diag 里 warning，不会静默丢失
+- 读的时候允许前缀兜底：`kb_read target=doc:02` 能命中 `doc:02-运行环境`；但**写引用仍要写全 TID**
+- 代码区（``` 围栏与 `行内代码`）里的 `[[…]]` / `<tscl>` 是示例，不解析也不计引用——讲语法时直接写在代码里即可
 - 段节点：`## 3.1 xxx` → `<文件TID>:3.1`，是**位置型**的：插一节就漂。链接它只是 warning（指错了跳错节），但**别拿它当需要长期稳定的锚点**——要稳定就写显式节点
 - 改名走 `kb_rename`，它会重写全库引用