project-node-memory 1.0.6 → 1.1.2

package/README.md

@@ -2,7 +2,7 @@
 
 > 简体中文 · [English](README_EN.md)
 
-把 **Markdown 目录当成知识库** 的 DSH 插件：为 Agent 提供 9 个 `kb_*` 工具，为人类提供知识节点面板（侧栏入口名「项目节点知识库」）。
+把 **Markdown 目录当成知识库** 的 DSH 插件：为 Agent 提供 10 个 `kb_*` 工具，为人类提供知识节点面板（侧栏入口名「项目节点知识库」）。
 
 没有索引数据库、没有向量、没有后台进程。完整知识库位于项目下的 `.nodekb/` 目录——一堆 md 文件，删掉插件之后它仍然是普通 md。
 
@@ -35,7 +35,7 @@ Agent 默认靠 `read` / `grep` / `glob` 找东西，代价是**试探**：grep
 1. **系统提示词段落**（默认开，`prompt.enabled=false` 可关）——每轮都在，规则只有五行：要沉淀就用 `.nodekb/` + `kb_*`，别拿 `write` 手搭 `docs/*.md`。
    段落常驻约 450 字，实测 `GET /nodekb/api/prompt` 可自证是否注册成功。
 
-2. **把「建库」变成一次调用**——`kb_init` 直接铺出 `doc/ facts/ lessons/ todo/ index/entry.md` 与 `.nodekb/README.md` 里的落位约定（幂等，已存在不覆盖）。没有这一步，Agent 会自己发明目录结构。
+2. **把「建库」变成一次调用**——`kb_init` 直接铺出 `doc/ lessons/ todo/ index/entry.md` 与 `.nodekb/README.md` 里的落位约定（幂等，已存在不覆盖）。没有这一步，Agent 会自己发明目录结构。
 
 3. **写也走工具**——`kb_write` 写前校验 TID / `<node>` 独占一行 / 路径不越界，写后立刻跑 diag 把悬空引用与重复块报回来。`write` 没有任何一层会拦，所以规则只能靠记。
 
@@ -92,7 +92,7 @@ config:
 面板只读，数据走宿主侧注册的 `/nodekb/api/*`。写库就是写 md——用 `write` / `edit` 工具，或者 `kb_write`。
 右栏正文单次最多渲染 10000 字符（超出显示截断提示）；宽表格横向滚动，长文本纵向滚动。
 
-## 9 个工具
+## 10 个工具
 
 | 工具            | 干什么                                                                                         |
 | --------------- | ---------------------------------------------------------------------------------------------- |
@@ -101,9 +101,10 @@ config:
 | `kb_search`     | 中文友好检索（2-gram + 多词加权 + 少见时退化子串），返回稳定 TID、类型、源行、片段             |
 | `kb_diag`       | 结构自检；有 error 时直接失败，别读完才发现引用断了                                            |
 | `kb_backlinks`  | 谁引用了它。改 TID / 删节点前先跑                                                              |
-| `kb_init`       | 建 `.nodekb` 骨架（幂等），铺出 `doc/ facts/ lessons/ todo/ index/` 与落位约定                 |
+| `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 缺失时只说明，不报错）                                  |
 
 ## 库怎么定位
@@ -163,21 +164,30 @@ config:
 ## 语法
 
 ```md
-## 3.1 编译契约            → 节点 tid = doc:03-build:3.1（位置型，不能当引用目标）
+## 3.1 编译契约            → 节点 tid = doc:03-build:3.1（位置型）
 <node name="fact:abi" type="fact" parent="doc:03-build">
-正文                                    ← 显式节点，引用只展开它自己
+正文                                    ← 显式节点
 </node>
 
-[[fact:abi]]              → 引用；渲染时就地展开
-[[doc:03-build]]          → 引文件/文件夹 = 展开整支子树
+[[node="doc:03-build:3.1"]]   → 结构引用：渲染成一个链接，不复制正文
+[[tscl="fact:abi"]]           → 值嵌入：把 <tscl id="fact:abi"> 的定义体替换进来
+
+<tscl id="fact:abi">
+三条硬规则：…（这个 id 全库只能定义一次）
+</tscl>
 ```
 
-硬规则只有两条：`<node>` / `</node>` 必须各占整行；显式节点名不能和文件派生 TID 撞。
+一条原则：**结构用节点（链接），值用 tscl（嵌入）**。同一个数字/结论写两遍就是漂移，
+`kb_diag` 会报；写成 `<tscl>` 定义后各处只留一个引用，改一处全库同步。
+
+硬规则：`<node>` / `</node>` 必须各占整行；`<tscl>` 内部不做结构解析（里面的 `##` 不算标题）；
+同一 `tscl` id 全库只能定义一次，且不能与节点 TID 同名。
+旧写法 `[[TID]]` 仍兼容（有定义时当宏、否则当链接），`kb_diag` 会 warning，2.0 移除。
 
 ## 自检（不装 DSH 也能跑）
 
 ```bash
-node scripts/check.mjs      # 235 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / 提示词段落 / 随包技能
+node scripts/check.mjs      # 275 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / 提示词段落 / 随包技能
 node test/parity.mjs        # 与 Python 原实现逐条对拍（需要 python 与 nodekb 源码）
 ```
 

package/README_EN.md

@@ -35,7 +35,7 @@ There is a hard size gate too: a `mode=subtree` render above `maxlen` (default 5
 A tool description is only read *after* the agent has already decided "I should record knowledge". Getting it to prefer this path takes four layers:
 
 1. **A system-prompt section** (on by default, `prompt.enabled=false` to disable). It is present every turn, and the rule is five lines: to record something use `.nodekb/` + `kb_*`, don't hand-roll `docs/*.md` with `write`. The section is ~450 characters; `GET /nodekb/api/prompt` proves whether it registered.
-2. **Make "create a library" one call.** `kb_init` lays out `doc/ facts/ lessons/ todo/ index/entry.md` plus the placement conventions in `.nodekb/README.md` (idempotent, never overwrites). Without it, the agent invents its own directory structure.
+2. **Make "create a library" one call.** `kb_init` lays out `doc/ lessons/ todo/ index/entry.md` plus the placement conventions in `.nodekb/README.md` (idempotent, never overwrites). Without it, the agent invents its own directory structure.
 3. **Writes go through a tool too.** `kb_write` validates TID syntax, that `<node>` / `</node>` sit on their own lines, and that the path stays inside the library — then runs `diag` immediately and reports dangling refs and duplicate blocks. Plain `write` has no such layer, so the rules survive only by memory.
 4. **A bundled skill, `project-node-memory-guide`** (loaded on demand). The prompt section is five lines; the writing conventions (how to split files, how to name TIDs, what to read before writing, three anti-patterns) live in `skills/project-node-memory-guide/SKILL.md`. It works out of the box with **no manual step**: when the host exposes a `skills` service, the plugin registers the body in memory via `ctx.skills.register()` (no prompt cost until used, withdrawn when the plugin is disabled). `skill.enabled=false` disables it; `GET /nodekb/api/skill` proves whether it registered.
 
@@ -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 |
 |---|---|
@@ -98,9 +98,10 @@ The right column renders at most 10,000 characters per view (with a truncation n
 | `kb_search` | CJK-friendly retrieval (2-gram index + multi-term weighting + substring fallback), returns stable TID, type, source line, snippet |
 | `kb_diag` | Structure self-check; fails outright on errors so you don't finish a read before noticing a broken ref |
 | `kb_backlinks` | Who references this node. Run before renaming a TID or deleting a node |
-| `kb_init` | Scaffold `.nodekb` (idempotent): `doc/ facts/ lessons/ todo/ index/` plus placement conventions |
+| `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
@@ -140,21 +141,32 @@ The panel has no session context, so it follows **the workspace of the most rece
 ## Syntax (the whole of it)
 
 ```md
-## 3.1 Compile contract     → node tid = doc:03-build:3.1 (positional, cannot be a reference target)
+## 3.1 Compile contract     → node tid = doc:03-build:3.1 (positional)
 <node name="fact:abi" type="fact" parent="doc:03-build">
-body                                    ← explicit node; a reference expands only this
+body                                    ← explicit node
 </node>
 
-[[fact:abi]]              → reference; expanded in place at render time
-[[doc:03-build]]          → referencing a file/folder = expand its whole subtree
+[[node="doc:03-build:3.1"]]   → structural reference: becomes a link, body is NOT copied
+[[tscl="fact:abi"]]           → value embed: the body of <tscl id="fact:abi"> is substituted
+
+<tscl id="fact:abi">
+three hard rules: … (this id may be defined exactly once per library)
+</tscl>
 ```
 
-Only two hard rules: `<node>` / `</node>` must each occupy an entire line, and an explicit node name must not collide with a file-derived TID.
+One rule of thumb: **structure is a node (link), a single value is tscl (embed)**. Writing the
+same number or conclusion twice is drift, and `kb_diag` reports it; define it once as `<tscl>` and
+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.
 
 ## Self-check (no DSH required)
 
 ```bash
-node scripts/check.mjs      # 235 checks: manifest contract / tools / routes / client slots / rename rewriting / scaffold + write / prompt section / bundled skill
+node scripts/check.mjs      # 275 checks: manifest contract / tools / routes / client slots / rename rewriting / scaffold + write / 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

@@ -186,6 +186,7 @@
         '.nkb-muted{opacity:.55}',
         '.nkb-err{color:#d9534f;white-space:pre-wrap}',
         '.nkb-link{color:#3b82f6;cursor:pointer;text-decoration:underline dotted}',
+      '.nkb-macro{color:#b45309;cursor:help;text-decoration:underline dashed}',
         '.nkb-kv{display:flex;gap:6px}',
         '.nkb-kv .k{opacity:.5;flex:0 0 58px}',
         '.nkb-kv .v{word-break:break-all}',
@@ -199,17 +200,19 @@
     }
 
     // ── 小组件 ────────────────────────────────────────────────────────────
-    /** 把 [[TID]] 变成可点的链接 */
+    /** 把 [[node="x"]] / [[tscl="x"]] / [[x]] 变成可点条目（点击跳到节点；宏点击跳到定义所在处） */
     function Rich(props) {
       var text = props.text || ''
       var parts = useMemo(function () {
         var out = []
-        var re = /\[\[([a-zA-Z0-9\u4e00-\u9fff:._-]+)\]\]/g
+        var re = /\[\[node\s*=\s*"([^"]+)"\]\]|\[\[tscl\s*=\s*"([^"]+)"\]\]|\[\[([a-zA-Z0-9\u4e00-\u9fff:._-]+)\]\]/g
         var last = 0
         var m
         while ((m = re.exec(text))) {
           if (m.index > last) out.push({ t: text.slice(last, m.index) })
-          out.push({ t: m[0], tid: m[1] })
+          var kind = m[1] !== undefined ? 'node' : m[2] !== undefined ? 'tscl' : 'bare'
+          var id = m[1] !== undefined ? m[1] : m[2] !== undefined ? m[2] : m[3]
+          out.push({ t: m[0], tid: kind === 'tscl' ? '' : id, macro: kind === 'tscl' ? id : '' })
           last = m.index + m[0].length
         }
         if (last < text.length) out.push({ t: text.slice(last) })
@@ -219,6 +222,13 @@
         'pre',
         { className: 'nkb-text' },
         parts.map(function (p, i) {
+          if (p.macro) {
+            return h(
+              'span',
+              { key: i, className: 'nkb-macro', title: '宏：' + p.macro, onClick: function () { props.onMacro && props.onMacro(p.macro) } },
+              p.t,
+            )
+          }
           if (!p.tid) return p.t
           return h(
             'span',
@@ -482,7 +492,7 @@
     }
 
     // ── 极简 markdown 渲染（不引第三方库）─────────────────────────────────
-    var MD_INLINE = /`([^`\n]+)`|\$\$([\s\S]+?)\$\$|\$([^$\n]+?)\$|\[\[([a-zA-Z0-9\u4e00-\u9fff:._-]+)\]\]|\*\*([^*\n]+)\*\*|\*([^*\n]+)\*|\[([^\]\n]+)\]\((https?:[^)\s]+)\)/g
+    var MD_INLINE = /`([^`\n]+)`|\$\$([\s\S]+?)\$\$|\$([^$\n]+?)\$|\[\[node\s*=\s*"([^"]+)"\]\]|\[\[tscl\s*=\s*"([^"]+)"\]\]|\[\[([a-zA-Z0-9\u4e00-\u9fff:._-]+)\]\]|\*\*([^*\n]+)\*\*|\*([^*\n]+)\*|\[([^\]\n]+)\]\((https?:[^)\s]+)\)/g
 
     function mdInline(text, onOpen, kbKey) {
       var out = []
@@ -498,20 +508,23 @@
         } else if (m[2] !== undefined || m[3] !== undefined) {
           var texSrc = m[2] !== undefined ? m[2] : m[3]
           out.push(h('span', { key: key, className: 'nkb-math', dangerouslySetInnerHTML: { __html: safeTex(texSrc, m[2] !== undefined) } }))
-        } else if (m[4] !== undefined) {
+        } else if (m[4] !== undefined || m[6] !== undefined) {
+          var nid = m[4] !== undefined ? m[4] : m[6]
           out.push(
             h(
               'span',
-              { key: key, className: 'nkb-link', title: m[4], onClick: (function (tid) { return function () { onOpen && onOpen(tid) } })(m[4]) },
-              m[4],
+              { key: key, className: 'nkb-link', title: nid, onClick: (function (tid) { return function () { onOpen && onOpen(tid) } })(nid) },
+              nid,
             ),
           )
         } else if (m[5] !== undefined) {
-          out.push(h('strong', { key: key }, m[5]))
-        } else if (m[6] !== undefined) {
-          out.push(h('em', { key: key }, m[6]))
+          out.push(h('span', { key: key, className: 'nkb-macro', title: '宏：' + m[5] }, m[5]))
         } else if (m[7] !== undefined) {
-          out.push(h('a', { key: key, href: m[8], target: '_blank', rel: 'noreferrer' }, m[7]))
+          out.push(h('strong', { key: key }, m[7]))
+        } else if (m[8] !== undefined) {
+          out.push(h('em', { key: key }, m[8]))
+        } else if (m[9] !== undefined) {
+          out.push(h('a', { key: key, href: m[10], target: '_blank', rel: 'noreferrer' }, m[9]))
         }
         last = m.index + m[0].length
       }

package/lib/engine/commands.js

@@ -9,13 +9,20 @@
 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 { lib_root_tids } from './mdlib.js'
 
 // 整支渲染字符上限（0 = 不限）。防止一次调用打爆上下文（root ≈ 23.5 万字符）
 export const DEFAULT_MAXLEN = 50000
 
+/** 渲染上下文：有传入就用传入的（宿主侧会缓存），否则现扫一遍定义表 */
+export function renderCtx(nodes, defs, libRoot) {
+  if (defs) return { defs, libRoot }
+  return { defs: collectDefs(nodes).defs, libRoot }
+}
+
 /** 读取：默认整支；node=仅该节点；toc=目录；raw=元信息 */
-export function cmdRead(nodes, target, { node = false, raw = false, toc = false, maxlen = 0 } = {}) {
+export function cmdRead(nodes, target, { node = false, raw = false, toc = false, maxlen = 0, defs, libRoot } = {}) {
   let tid
   try {
     tid = resolve_path(nodes, target)
@@ -34,8 +41,9 @@ export function cmdRead(nodes, target, { node = false, raw = false, toc = false,
   try {
     if (toc) return { text: toc_lines(nodes, tid).join('\n'), code: 0 }
     if (raw) return { text: JSON.stringify(node_info(nodes, tid), null, 2), code: 0 }
+    const ctx = renderCtx(nodes, defs, libRoot)
     if (node) {
-      let out = render_node(nodes, tid)
+      let out = render_node(nodes, tid, ctx)
       const kids = [...nodes.values()].filter((c) => c.parent_tid === tid)
       if (kids.length) {
         // 反直觉提示：带 ## 子节的页面只读 node 只回前言
@@ -43,7 +51,7 @@ export function cmdRead(nodes, target, { node = false, raw = false, toc = false,
       }
       return { text: out, code: 0 }
     }
-    const out = render_subtree(nodes, tid)
+    const out = render_subtree(nodes, tid, 1, ctx)
     if (maxlen && out.length > maxlen) {
       return {
         text:
@@ -66,15 +74,16 @@ export function cmdSearch(nodes, query, opts = {}) {
 }
 
 /** 自检 */
-export function cmdDiag(nodes, { problems = [], strict = false, libRoot } = {}) {
-  return diag(nodes, { problems, strict, libRoot })
+export function cmdDiag(nodes, { problems = [], strict = false, libRoot, defs } = {}) {
+  return diag(nodes, { problems, strict, libRoot, defs })
 }
 
 /** 导出整库为渲染 md 树（一个一级节点一个文件） */
-export function cmdDump(nodes, outDir, fs, path) {
+export function cmdDump(nodes, outDir, fs, path, defs) {
   const written = []
+  const ctx = renderCtx(nodes, defs)
   for (const tid of lib_root_tids(nodes)) {
-    const text = render_subtree(nodes, tid)
+    const text = render_subtree(nodes, tid, 1, ctx)
     const p = path.join(outDir, `${tid}.md`)
     fs.mkdirSync(outDir, { recursive: true })
     fs.writeFileSync(p, text, 'utf8')

package/lib/engine/defs.js

@@ -0,0 +1,60 @@
+/**
+ * defs —— 全库 `<tscl id="x">…</tscl>` 定义表。
+ *
+ * 定义可以写在任何节点正文里（通常写在 facts/ 的自然语言段落里，也可以就近写在
+ * 引用它的文档旁）。这里把全书扫一遍，产出 id → { id, body, ownerTid, source }。
+ *
+ * 不做的事：不判断「该不该只有一处」以外的语义——重复、与节点 TID 撞名、嵌套开标签、
+ * 无人引用，全部以 problems 形式交回给 diag 定级。
+ */
+
+import { extract_defs } from './parse.js'
+
+const NESTED_OPEN = /<tscl\b[^>]*>(?:(?!<\/tscl>)[\s\S])*?<tscl\b/
+
+/**
+ * @param {Map<string, {tid:string, content:string, source:string, title:string}>} nodes
+ * @returns {{ defs: Map<string, object>, problems: object[] }}
+ */
+export function collectDefs(nodes) {
+  const defs = new Map()
+  const problems = []
+
+  for (const node of nodes.values()) {
+    const content = node.content || ''
+    if (!content.includes('<tscl')) continue
+    if (NESTED_OPEN.test(content)) {
+      problems.push({ code: 'nested-tscl', tid: node.tid, where: node.source })
+    }
+    for (const [id, body] of extract_defs(content)) {
+      const prev = defs.get(id)
+      if (prev) {
+        prev.count += 1
+        prev.owners.push(node.tid)
+        problems.push({
+          code: 'dup-def',
+          id,
+          owners: prev.owners.slice(),
+          where: node.source,
+        })
+        continue
+      }
+      defs.set(id, {
+        id,
+        body,
+        ownerTid: node.tid,
+        ownerTitle: node.title || '',
+        source: node.source || '',
+        count: 1,
+        owners: [node.tid],
+      })
+    }
+  }
+
+  return { defs, problems }
+}
+
+/** 定义体是否有跨行内容（跨行定义不能内联进表格单元格） */
+export function isMultiline(body) {
+  return String(body || '').replace(/\s+$/, '').includes('\n')
+}

package/lib/engine/diag.js

@@ -1,16 +1,17 @@
 /**
  * diag —— 结构自检。
  *
- * errors  = 真损坏（悬空/位置型引用、循环、孤儿、树环、重复 TID），退出码 2。
- * warnings = 疑似漂移（跨节点重复块 / 节点内重复行），默认只报；strict 时算失败。
+ * errors  = 真损坏（悬空/位置型引用、循环、孤儿、树环、重复 TID、重复/冲突/悬空的 tscl 定义），退出码 2。
+ * warnings = 疑似漂移（跨节点重复块 / 节点内重复行 / 旧语法 / 无人引用的定义），默认只报；strict 时算失败。
  *
  * 逐行对齐 Python 版 commands.cmd_diag（含 _is_boilerplate 的全部豁免规则）。
  */
 
 import fs from 'node:fs'
 import path from 'node:path'
-import { extract_refs } from './parse.js'
-import { render_node, TransclusionError } from './render.js'
+import { extractRefs, extract_refs } from './parse.js'
+import { render_node, resolve_path, TransclusionError } from './render.js'
+import { collectDefs, isMultiline } from './defs.js'
 
 const POSITIONAL_SEG = /^\d+(\.\d+)*$/
 const DUP_MIN_LEN = 40 // 视为漂移候选的文本块最短长度
@@ -172,25 +173,73 @@ function typeCounts(nodes) {
  * 自检。
  * @returns {{report:object, code:number}}
  */
-export function diag(nodes, { problems = [], strict = false, libRoot } = {}) {
+export function diag(nodes, { problems = [], strict = false, libRoot, defs = null } = {}) {
   const errors = [...problems]
+  const warnings = []
+
+  // 定义表：全库 <tscl id="x">…</tscl>
+  let defsMap = defs
+  if (!defsMap) {
+    const collected = collectDefs(nodes)
+    defsMap = collected.defs
+    for (const p of collected.problems) {
+      if (p.code === 'dup-def') errors.push(`重复定义（必须恰好一处）: <tscl id="${p.id}"> 出现在 ${p.owners.join('、')}`)
+      else if (p.code === 'nested-tscl') errors.push(`嵌套 <tscl> 开标签: ${p.tid}`)
+    }
+  }
+  for (const id of defsMap.keys()) {
+    if (nodes.has(id)) errors.push(`命名空间冲突: tscl 定义 "${id}" 与节点 TID 同名（一个名字只能有一种含义）`)
+  }
+  const referenced = new Set()
 
   for (const node of nodes.values()) {
-    for (const refTid of extract_refs(node.content)) {
-      if (!nodes.has(refTid)) {
-        errors.push(`悬空引用: ${node.tid} → [[${refTid}]]`)
-      } else {
-        const segs = refTid.split(':')
-        if (segs.length >= 3 && POSITIONAL_SEG.test(segs[segs.length - 1])) {
-          // 位置型段落 TID（文件:序号）：插章节就漂移，禁止作为引用目标
-          errors.push(`位置型 TID 引用（插章节会漂移）: ${node.tid} → [[${refTid}]]`)
+    const content = String(node.content || '')
+    for (const ref of extractRefs(content)) {
+      const lineOfRef = content.slice(0, ref.index).split('\n').pop() || ''
+      if (ref.kind === 'tscl' || (ref.kind === 'legacy' && defsMap.has(ref.id))) {
+        if (ref.kind === 'tscl') referenced.add(ref.id)
+        if (!defsMap.has(ref.id)) {
+          errors.push(`悬空 tscl 引用: ${node.tid} → [[tscl="${ref.id}"]]`)
+          continue
+        }
+        if (ref.kind === 'legacy') {
+          warnings.push(`旧语法（实为宏）: ${node.tid} → [[${ref.id}]]，请写成 [[tscl="${ref.id}"]]`)
         }
+        const body = defsMap.get(ref.id).body
+        if (/^\s*\|/.test(lineOfRef) && isMultiline(body)) {
+          warnings.push(`跨行宏被内联进表格单元格: ${node.tid} → [[tscl="${ref.id}"]]（表格里只放单行宏）`)
+        }
+        continue
+      }
+
+      if (ref.kind === 'legacy') {
+        warnings.push(`旧语法: ${node.tid} → [[${ref.id}]]，请写成 [[node="${ref.id}"]]（2.0 将移除裸引用）`)
+      }
+
+      // 节点引用（node= 或旧语法）：允许三级前缀唯一解析，与 kb_read 一致
+      const hit = nodes.has(ref.id) ? ref.id : resolve_path(nodes, ref.id)
+      if (!hit) {
+        errors.push(`悬空引用: ${node.tid} → ${ref.raw}`)
+        continue
+      }
+      const segs = hit.split(':')
+      if (segs.length >= 3 && POSITIONAL_SEG.test(segs[segs.length - 1])) {
+        // 位置型段落 TID（文件:序号）：插章节就漂移。1.1 起 node 引用只是链接、
+        // 不再复制正文，误指也就跳错一节 → 降为 warning。
+        warnings.push(`位置型 TID 链接（插章节会漂移）: ${node.tid} → ${ref.raw}`)
       }
     }
   }
+
+  for (const def of defsMap.values()) {
+    if (!referenced.has(def.id)) {
+      warnings.push(`未被引用的定义: <tscl id="${def.id}">（在 ${def.ownerTid}）`)
+    }
+  }
+
   for (const tid of nodes.keys()) {
     try {
-      render_node(nodes, tid)
+      render_node(nodes, tid, { defs: defsMap })
     } catch (e) {
       if (e instanceof TransclusionError) errors.push(`循环引用 @${tid}: ${e.message}`)
       else throw e
@@ -205,7 +254,7 @@ export function diag(nodes, { problems = [], strict = false, libRoot } = {}) {
 
   const root = libRoot || libRootOf(nodes)
   const ignore = loadIgnore(root)
-  const warnings = [...dupBlocks(nodes, ignore.blocks), ...intraDupLines(nodes, ignore.lines)]
+  warnings.push(...dupBlocks(nodes, ignore.blocks), ...intraDupLines(nodes, ignore.lines))
 
   const code = errors.length || (strict && warnings.length) ? 2 : 0
   const report = {
@@ -213,6 +262,7 @@ export function diag(nodes, { problems = [], strict = false, libRoot } = {}) {
     errors,
     warnings,
     node_count: nodes.size,
+    def_count: defsMap.size,
     types: typeCounts(nodes),
   }
   if (!errors.length && !warnings.length) report.status = 'ok'

package/lib/engine/mdlib.js

@@ -100,6 +100,7 @@ export function parse_file(absPath, file_tid, folder_type, parent_tid) {
   let sec_index = 0
   const stack = [] // 显式 <node> 嵌套栈
   fenced = false // ``` 围栏内一律视为原文，不做任何标记解析
+  let tscl_open = false // <tscl> 定义块内不做结构解析（宏体可含任意 md）
 
   const default_parent = () => (first_node_tid ? first_node_tid : file_tid)
   // 内容落到哪：最内层 <node> 栈 → 当前 H2 段 → 文件节点
@@ -118,6 +119,18 @@ export function parse_file(absPath, file_tid, folder_type, parent_tid) {
       content_target().content.push(line)
       continue
     }
+    // <tscl> 定义块内部一律按原文处理：不切 H2、不建节点、不弹栈
+    if (tscl_open) {
+      content_target().content.push(line)
+      if (/^\s*<\/tscl>\s*$/.test(line)) tscl_open = false
+      continue
+    }
+    if (/^\s*<tscl\b/.test(line)) {
+      content_target().content.push(line)
+      const afterOpen = line.slice(line.indexOf('>') + 1)
+      if (!/<\/tscl>/.test(afterOpen)) tscl_open = true
+      continue
+    }
     if (stack.length) {
       if (line.trim() === '</node>') {
         stack.pop()

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/engine/parse.js

@@ -9,8 +9,17 @@
 
 const CJK = '\\u4e00-\\u9fff'
 
-// 引用：[[TID]]（允许 CJK，便于中文文件名/标题直接进入 TID）
+// 引用（1.1 起双语法）：
+//   [[node="tid 或相对路径"]]  → 链接（不展开）
+//   [[tscl="id"]]              → 值嵌入（替换成 <tscl> 定义体）
+//   [[tid]]                    → 旧语法，1.x 兼容并按目标类型推断，2.0 移除
 export const REF_SOURCE = '\\[\\[([a-zA-Z0-9\\u4e00-\\u9fff:._-]+)\\]\\]'
+export const NODE_REF_SOURCE = '\\[\\[node\\s*=\\s*"([^"]+)"\\]\\]'
+export const TSCL_REF_SOURCE = '\\[\\[tscl\\s*=\\s*"([^"]+)"\\]\\]'
+const LEGACY_REF_SOURCE = '\\[\\[(?!node\\s*=|tscl\\s*=)([a-zA-Z0-9\\u4e00-\\u9fff:._-]+)\\]\\]'
+const ANY_REF_SOURCE =
+  `\\[\\[node\\s*=\\s*"([^"]+)"\\]\\]|\\[\\[tscl\\s*=\\s*"([^"]+)"\\]\\]|` +
+  `\\[\\[(?!node\\s*=|tscl\\s*=)([a-zA-Z0-9\\u4e00-\\u9fff:._-]+)\\]\\]`
 
 const TSCL_SOURCE = '<tscl id="([^"]+)">([\\s\\S]*?)<\\/tscl>'
 const TID_RE = new RegExp(`^[a-z0-9${CJK}][a-z0-9${CJK}:._-]*$`)
@@ -21,6 +30,30 @@ export function refRegex() {
   return new RegExp(REF_SOURCE, 'g')
 }
 
+export function nodeRefRegex() {
+  return new RegExp(NODE_REF_SOURCE, 'g')
+}
+
+export function tsclRefRegex() {
+  return new RegExp(TSCL_REF_SOURCE, 'g')
+}
+
+/** 三种引用合一的 global 正则（组 1=node 组 2=tscl 组 3=legacy），渲染用 */
+export function anyRefRegex() {
+  return new RegExp(ANY_REF_SOURCE, 'g')
+}
+
+/** 一次扫过三种引用（保序），返回 [{kind:'node'|'tscl'|'legacy', id, raw, index}] */
+export function extractRefs(text) {
+  const out = []
+  for (const m of String(text).matchAll(new RegExp(ANY_REF_SOURCE, 'g'))) {
+    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 })
+  }
+  return out
+}
+
 export function is_valid_tid(tid) {
   return TID_RE.test(String(tid))
 }

package/lib/engine/render.js

@@ -1,13 +1,21 @@
 /**
  * render —— 基于内存节点模型的渲染层（md 即库，无持久化状态）。
  *
- * - render_node / render_subtree：[[TID]] 就地填充（transclusion 展开）
- * - toc_lines：目录视图（tid · 标题 · 字符数，不渲染正文）
- * - node_info：节点元信息（含 source 行号）
- * - 环检测：展开路径重复出现同一 TID 抛 TransclusionError；悬空引用保留 [[TID]] 原文
+ * 1.1 起引用分两种，写法与结果都不同：
+ * - `[[node="x"]]` → 链接，**不展开**。结构由节点承担，引用只留一行指针。
+ * - `[[tscl="x"]]` → 值嵌入：替换成 `<tscl id="x">…</tscl>` 的定义体。
+ * - `[[x]]`        → 1.x 旧语法，先查定义、再查节点；2.0 移除（diag 报 warning）。
+ *
+ * 为什么不展开节点：整支复制会让同一句话在库里出现两次、改一处忘另一处——这正是
+ * nodekb 想消灭的重复。需要「完整内容」时走 kb_read target=…（整支投影），而不是复制文本。
+ *
+ * 其它导出：toc_lines / toc_tree / node_info / resolve_path；环检测抛 TransclusionError。
  */
 
-import { refRegex } from './parse.js'
+import path from 'node:path'
+import { anyRefRegex, strip_tags } from './parse.js'
+
+const MAX_EMBED = 64 // 单次渲染最多展开的宏个数（防病态文件自引用爆炸）
 
 export class TransclusionError extends Error {
   constructor(message) {
@@ -24,62 +32,100 @@ function children(nodes, tid) {
 }
 
 function cycle_msg(seen, target, nodes) {
-  let msg = `循环引用: ${[...seen, target].join(' -> ')}`
+  const chain = [...seen, target].map((s) => String(s).replace(/^tscl:/, 'tscl:'))
+  let msg = `循环引用: ${chain.join(' -> ')}`
   const node = nodes.get(target)
   if (node && node.source) msg += `（重复节点源: ${node.source}）`
   return msg
 }
 
-/** 容器节点（文件夹/文件）转译：整支子树投影（`## 标题` + 内容 + 子节递归） */
-function project_container(nodes, tid, seen) {
-  const node = nodes.get(tid)
-  const parts = []
-  const title = node.title || tid
-  if (title !== tid) parts.push('## ' + title) // 显式节点（title===tid）内联时不输出标题，避免列表内噪音
-  parts.push(expand(node.content, nodes, seen))
-  for (const child of children(nodes, tid)) {
-    parts.push(project_container(nodes, child.tid, [...seen, child.tid]))
+const fileOf = (source) => String(source || '').replace(/#L\d+(-L\d+)?$/, '')
+
+function lineOf(source) {
+  const m = /#L(\d+)/.exec(String(source || ''))
+  return m ? Number(m[1]) : 0
+}
+
+/** 节点 → 一行 md 链接。文件夹没有可点的文件，就给粗体标题。 */
+function linkTo(node, ctx) {
+  const label = String(node.title || node.tid).replace(/[[\]]/g, (c) => '\\' + c)
+  const file = fileOf(node.source)
+  if (!file) return `**${label}**`
+  let target = file
+  if (ctx && ctx.libRoot) {
+    const rel = path.relative(ctx.libRoot, file)
+    if (rel && !rel.startsWith('..')) target = rel.split(path.sep).join('/')
   }
-  return parts.join('\n\n')
+  const line = node.kind === 'section' || node.positional ? lineOf(node.source) : 0
+  return `[${label}](${target}${line ? `#L${line}` : ''})`
 }
 
-function expand(text, nodes, seen) {
+function resolveNode(nodes, id) {
+  if (nodes.has(id)) return nodes.get(id)
+  const hit = resolve_path(nodes, id)
+  return hit ? nodes.get(hit) : null
+}
+
+/**
+ * 把正文里的三种引用渲染掉。
+ * ctx = { defs: Map<id,{body,ownerTid,source}>, libRoot?: string }
+ */
+export function expand(text, nodes, seen = [], ctx = {}) {
+  const defs = (ctx && ctx.defs) || new Map()
+  // 定义块在正文里就地显示为它的内容（标签本身不出现）
+  const source = strip_tags(text)
   const out = []
   let pos = 0
-  for (const m of String(text).matchAll(refRegex())) {
-    out.push(text.slice(pos, m.index))
-    const target = m[1]
-    if (seen.includes(target)) throw new TransclusionError(cycle_msg(seen, target, nodes))
-    const nxt = [...seen, target]
-    const node = nodes.get(target)
-    if (node) {
-      // 仅 文件夹/文件 容器展开整支子树；显式 <node> 原子引用只展开自身（避免同文件兄弟被连带展开）
-      if (node.kind === 'folder' || node.kind === 'file') out.push(project_container(nodes, target, nxt))
-      else out.push(expand(node.content, nodes, nxt))
-    } else {
-      out.push(m[0]) // 悬空：保留原文，diag 报告
+  let embeds = 0
+  for (const m of String(source).matchAll(anyRefRegex())) {
+    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]
+    let handled = false
+
+    // 值嵌入：tscl 显式请求，或旧语法且确有同名定义
+    if ((kind === 'tscl' || kind === 'legacy') && defs.has(id)) {
+      const key = 'tscl:' + id
+      if (seen.includes(key)) throw new TransclusionError(cycle_msg(seen, key, nodes))
+      if (++embeds > MAX_EMBED) {
+        throw new TransclusionError(`宏展开超过 ${MAX_EMBED} 次（疑似病态引用）: ${id}`)
+      }
+      const body = String(defs.get(id).body || '').replace(/\s+$/, '')
+      out.push(expand(body, nodes, [...seen, key], ctx))
+      handled = true
+    }
+
+    // 结构引用：只出链接，不再复制子树
+    if (!handled && (kind === 'node' || kind === 'legacy')) {
+      const node = resolveNode(nodes, id)
+      if (node) {
+        out.push(linkTo(node, ctx))
+        handled = true
+      }
     }
+
+    if (!handled) out.push(m[0]) // 悬空：保留原文，diag 报告
     pos = m.index + m[0].length
   }
-  out.push(text.slice(pos))
+  out.push(String(source).slice(pos))
   return out.join('')
 }
 
 /** 渲染单节点内容（不含标题行） */
-export function render_node(nodes, tid) {
+export function render_node(nodes, tid, ctx = {}) {
   const node = nodes.get(tid)
   if (!node) throw new Error(`节点不存在: ${tid}`)
-  return expand(node.content, nodes, [tid])
+  return expand(node.content, nodes, [tid], ctx)
 }
 
-/** 渲染整支：递归子树为带标题层级的 md */
-export function render_subtree(nodes, tid, level = 1) {
+/** 渲染整支：递归子树为带标题层级的 md（节点引用只在原文位置出现一次） */
+export function render_subtree(nodes, tid, level = 1, 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])]
-  for (const child of children(nodes, tid)) parts.push(render_subtree(nodes, child.tid, level + 1))
+  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))
   return parts.join('\n\n')
 }
 

package/lib/engine/scaffold.js

@@ -4,6 +4,9 @@
  * 目的不是「生成一堆空文件」，而是把**约定**写进库里：后来的人（或 Agent）
  * 打开 .nodekb/README.md 就知道该放哪、该多大、什么时候引用而不是复述。
  * 幂等：已存在的文件一律跳过，绝不动用户已写的内容。
+ *
+ * 1.1 起不再预建 facts/：需要「唯一事实」时用 <tscl> 定义 + 引用，而不是单独开目录。
+ * 目录与节点类型都是约定，不是约束——项目需要什么就加减什么。
  */
 
 import fs from 'node:fs'
@@ -19,39 +22,47 @@ const README = `# 本库约定（.nodekb）
 | 目录 | 放什么 | 判据 |
 |---|---|---|
 | \`doc/\` | 主题文档（一块一块的正文） | 会随版本演进、需要通读的解释性内容 |
-| \`facts/\` | 事实常量（一个节点一条） | 值本身即答案：版本号、公差、系数、路径、阈值 |
 | \`lessons/\` | 踩过的坑 | 换个人还会再踩，且「怎么发现的」比结论更值钱 |
 | \`todo/\` | 待办与计划 | 有明确完成条件 |
-| \`index/entry.md\` | 入口索引 | 只放指针（\`[[TID]]\`），不要复述正文 |
+| \`index/entry.md\` | 入口索引 | 只放指针，不要复述正文 |
+
+**目录与节点类型都是约定，不是约束**：项目没有待办就别建 \`todo/\`，需要 \`adr/\`、\`api/\`、\`runbook/\` 就自己加，
+节点类型也一样（\`type="fact"\`、\`type="decision"\`、\`type="api"\` 都是自由的）。
+上面这张表只是「不知道放哪时」的默认答案，不是白名单。
 
-## 三条硬规则
+## 四条硬规则
 
 1. **一个主题一个文件，取 < 4KB**。超过就拆成 \`doc/03-xxx.md\` 的多节，入口表加一行指针。
-2. **不要复述**。同一段数字/结论只写一次，其它地方用 \`[[TID]]\` 引用；改名时 \`kb_rename\` 会一起改写。
-3. **写之前先 \`kb_read mode=toc\` 看结构**，写完跑 \`kb_diag\`：悬空引用、引用位置型段落、循环、重复 TID 都会当场报出来。
+2. **不要复述**。同一句话只写一次：结构用 \`[[node="…"]]\` 指过去，真正的「值」写成 \`<tscl>\` 定义再引用。
+3. **写之前先 \`kb_read mode=toc\` 看结构**，写完跑 \`kb_diag\`：悬空引用、重复定义、循环、重复 TID 都会当场报出来。
+4. **事实只写一处**。同一个数字/结论出现两次就算漂移，\`kb_diag\` 会报。
 
-## 语法（就两条）
+## 语法（三种标记）
 
 - 文件即节点：\`doc/03-build.md\` → TID \`doc:03-build\`；\`## 3.1 标题\` → 子节点 \`doc:03-build:3.1\`
-- 显式节点：\`<node name="fact:abi" type="fact">\` … \`</node>\`，标签必须**独占一行**
-- 引用：\`[[doc:03-build:3.1]]\`（引用文件夹/文件展开整支，引用显式节点只展开它自己）
+- 显式节点：\`<node name="lesson:abi" type="lesson">\` … \`</node>\`，标签必须**独占一行**
+- 结构引用：\`[[node="doc:03-build:3.1"]]\` —— 渲染成一个链接，**不展开**（内容不复制）
+- 值嵌入：先定义
+  \`\`\`md
+  <tscl id="fact:abi">
+  三条硬规则：1) 只用 C ABI；2) 名字加前缀 \`fm_\`；3) 导出结构体必须定长。
+  </tscl>
+  \`\`\`
+  再写 \`[[tscl="fact:abi"]]\` —— 渲染时整段替换进来。**同一个 id 全库只能定义一次**，
+  改一处，所有引用处同时变；这就是用引用代替复述的意义。
 `
 
 const ENTRY = `# 入口索引
 
-只放指针，不复述正文。每条一行：\`- [[TID]] 一句话说明\`。
+只放指针，不复述正文。结构用 \`[[node="TID"]]\`，值用 \`[[tscl="id"]]\`。
 
 ## 主题
 
-- [[doc:00-overview]] 项目概览与结构
-
-## 事实
-
-（\`facts/\` 下的节点）
+- [[node="doc:00-overview"]] 项目概览与结构
 
-## 待办
+## 其它
 
-（\`todo/\` 下的条目）
+按项目实际增删：待办（\`todo/\`）、决策（\`adr/\`）、接口（\`api/\`）……没有的目录直接删掉。
 `
 
 const OVERVIEW = `# 项目概览
@@ -80,12 +91,6 @@ const TODO = `# 待办
 一条一个 \`<node name="todo:xxx" type="todo">\`，每条要有**明确的完成条件**。
 `
 
-const FACTS = `# 事实
-
-一个常量一条 \`<node name="fact:xxx" type="fact">\`：值 + 单位 + 出处 + 什么时候会变。
-值本身即答案的东西才放这里，解释性内容放 doc/。
-`
-
 const IGNORE = `{
   "blocks": [],
   "lines": []
@@ -96,7 +101,6 @@ const SEEDS = [
   ['README.md', README],
   ['index/entry.md', ENTRY],
   ['doc/00-overview.md', OVERVIEW],
-  ['facts/README.md', FACTS],
   ['lessons/README.md', LESSONS],
   ['todo/README.md', TODO],
   ['diag_ignore.json', IGNORE],

package/lib/host/prompt.js

@@ -16,11 +16,12 @@ export const DEFAULT_PROMPT = [
   '',
   '本项目需要沉淀长期知识（设计决策、踩坑、事实常量、待办、交接）时，**用 `.nodekb/` + `kb_*` 工具**，不要用 write/edit 手搭 `docs/*.md` 式的渐进式文档——手写没有校验、没有稳定 TID、没有引用展开。',
   '',
-  '- 建库：`kb_init` 一次铺出骨架（`doc/ facts/ lessons/ todo/ index/entry.md` + 约定说明）。已有 `.nodekb/` 就别重建。',
-  '- 写库：`kb_write`（append/replace/create，或对显式节点用 mode=node）。它写前校验 TID 与 `<node>` 独占一行，写后立刻跑 diag 把悬空引用/重复块报回来；同样的事用 write 做没有任何一层会拦。',
+  '- 建库：`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_backlinks`，改名用 `kb_rename`（会重写全库引用并跳过被并发改过的文件）。',
-  '- 一个主题一个文件、取 < 4KB；结论只写一次，别处用 `[[TID]]` 引用。',
+  '- 引用分两种，别混：**结构**用 `[[node="doc:03-build:3.1"]]`（只出一个链接，不复制正文）；**值只写一处**——定义 `<tscl id="fact:abi">…</tscl>`，各处写 `[[tscl="fact:abi"]]`，同一 id 全库只能定义一次。',
+  '- 旧写法 `[[TID]]` 仍能用但 `kb_diag` 会 warning，2.0 移除（老库可先跑 `kb_migrate` 演练，确认后 `dry_run=false` 批量迁）。',
 ].join('\n')
 
 function textOf(config) {

package/lib/host/routes.js

@@ -10,8 +10,9 @@ import path from 'node:path'
 import { render_node, render_subtree, toc_tree, node_info, resolve_path } from '../engine/render.js'
 import { search, formatSearch } from '../engine/search.js'
 import { diag } from '../engine/diag.js'
-import { extract_refs } from '../engine/parse.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'
@@ -171,10 +172,11 @@ export function registerRoutes(ctx, config) {
           return
         }
         const node = lib.nodes.get(tid)
+        const ctx = { defs: lib.defs, libRoot: lib.nodekb }
         let text
-        if (mode === 'node') text = render_node(lib.nodes, tid)
+        if (mode === 'node') text = render_node(lib.nodes, tid, ctx)
         else if (mode === 'raw') text = node.content
-        else text = render_subtree(lib.nodes, tid)
+        else text = render_subtree(lib.nodes, tid, 1, ctx)
         send(res, 200, {
           kb: lib.name,
           ...node_info(lib.nodes, tid),
@@ -227,7 +229,7 @@ export function registerRoutes(ctx, config) {
 
       if (url.pathname === `${PREFIX}/diag`) {
         const lib = open()
-        const { report } = diag(lib.nodes, { problems: lib.problems, libRoot: lib.nodekb })
+        const { report } = diag(lib.nodes, { problems: lib.problems, libRoot: lib.nodekb, defs: lib.defs })
         send(res, 200, { kb: lib.name, ...report })
         return
       }
@@ -242,7 +244,8 @@ export function registerRoutes(ctx, config) {
         }
         const rows = []
         for (const node of lib.nodes.values()) {
-          if (node.tid !== tid && extract_refs(node.content).includes(tid)) {
+          const hit = extractRefs(node.content).some((r) => r.kind !== 'tscl' && r.id === tid)
+          if (node.tid !== tid && hit) {
             rows.push({ tid: node.tid, title: node.title, type: node.type, source: node.source })
           }
         }
@@ -277,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/runtime.js

@@ -8,9 +8,10 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { parse_library } from '../engine/mdlib.js'
+import { collectDefs } from '../engine/defs.js'
 import { resolveLibrary, listLibraries } from '../engine/registry.js'
 
-const CACHE = new Map() // nodekb -> { sig, nodes, problems }
+const CACHE = new Map() // nodekb -> { sig, nodes, problems, defs }
 const MAX_CACHE = 8
 
 // 面板没有会话上下文，只能靠人指定工作区（ws 参数）。
@@ -99,13 +100,18 @@ export function openLibrary(config, exec, { kb, lib, remember = true } = {}) {
   const sig = signature(resolved.nodekb)
   const hit = CACHE.get(resolved.nodekb)
   if (hit && hit.sig === sig) {
-    return { ...resolved, nodes: hit.nodes, problems: hit.problems, cached: true }
+    return { ...resolved, nodes: hit.nodes, defs: hit.defs, problems: hit.problems, cached: true }
   }
   const problems = []
   const nodes = parse_library(resolved.nodekb, problems)
-  CACHE.set(resolved.nodekb, { sig, nodes, problems })
+  const found = collectDefs(nodes)
+  for (const p of found.problems) {
+    if (p.code === 'dup-def') problems.push(`重复定义: <tscl id="${p.id}"> 出现在 ${p.owners.join('、')}`)
+    else if (p.code === 'nested-tscl') problems.push(`嵌套 <tscl> 开标签: ${p.tid}`)
+  }
+  CACHE.set(resolved.nodekb, { sig, nodes, defs: found.defs, problems })
   if (CACHE.size > MAX_CACHE) CACHE.delete(CACHE.keys().next().value)
-  return { ...resolved, nodes, problems, cached: false }
+  return { ...resolved, nodes, defs: found.defs, problems, cached: false }
 }
 
 export function knownLibraries(config, exec, opts = {}) {

package/lib/host/tools.js

@@ -12,8 +12,9 @@ import { execFileSync } from 'node:child_process'
 import { render_node, render_subtree, toc_lines, node_info, resolve_path } from '../engine/render.js'
 import { search, formatSearch } from '../engine/search.js'
 import { diag } from '../engine/diag.js'
-import { extract_refs } from '../engine/parse.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'
@@ -137,16 +138,17 @@ export function buildTools(ctx, config) {
       }
 
       let out
+      const ctx = { defs: lib.defs, libRoot: lib.nodekb }
       if (mode === 'toc') {
         out = toc_lines(lib.nodes, tid).join('\n')
       } else if (mode === 'raw') {
         out = JSON.stringify(node_info(lib.nodes, tid), null, 2)
       } else if (mode === 'node') {
-        out = render_node(lib.nodes, tid)
+        out = render_node(lib.nodes, tid, ctx)
         const kids = [...lib.nodes.values()].filter((c) => c.parent_tid === tid).length
         if (kids) out += `\n\n（本节点含 ${kids} 个子节：正文在子节里；看结构用 mode=toc，看整支不传 mode）`
       } else {
-        out = render_subtree(lib.nodes, tid)
+        out = render_subtree(lib.nodes, tid, 1, ctx)
         if (maxlen && out.length > maxlen) {
           throw new Error(
             `渲染超上限: ${out.length} 字符 > ${maxlen}。建议 mode=node 单节点、先 mode=toc 看结构、或指定小节 tid；` +
@@ -230,7 +232,7 @@ export function buildTools(ctx, config) {
     },
     async execute(args, exec) {
       const lib = locate(config, exec, args)
-      const { report, code } = diag(lib.nodes, { problems: lib.problems, strict: !!args.strict, libRoot: lib.nodekb })
+      const { report, code } = diag(lib.nodes, { problems: lib.problems, strict: !!args.strict, libRoot: lib.nodekb, defs: lib.defs })
       const text_ = JSON.stringify(report, null, 2)
       if (code !== 0) {
         const e = new Error(text_)
@@ -267,8 +269,8 @@ export function buildTools(ctx, config) {
       const rows = []
       for (const node of lib.nodes.values()) {
         if (node.tid === tid) continue
-        const refs = extract_refs(node.content)
-        if (refs.includes(tid)) rows.push({ tid: node.tid, title: node.title, type: node.type, source: node.source })
+        const hit = extractRefs(node.content).some((r) => r.kind !== 'tscl' && r.id === tid)
+        if (hit) rows.push({ tid: node.tid, title: node.title, type: node.type, source: node.source })
       }
       const lines = [`引用 ${tid} 的节点：${rows.length} 个`]
       for (const r of rows) lines.push(`- ${r.tid} [${r.type}] ${r.title}  ${r.source}`)
@@ -308,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',
@@ -435,7 +464,7 @@ export function buildTools(ctx, config) {
       let report = null
       try {
         const fresh = openLibrary(config, exec, { kb: args.kb, lib: args.lib })
-        report = diag(fresh.nodes, { problems: fresh.problems, libRoot: fresh.nodekb })
+        report = diag(fresh.nodes, { problems: fresh.problems, libRoot: fresh.nodekb, defs: fresh.defs })
       } catch (e) {
         report = { report: { errors: [`写后解析失败: ${e.message}`], warnings: [], node_count: 0 }, code: 2 }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-node-memory",
-  "version": "1.0.6",
+  "version": "1.1.2",
   "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,6 +1,6 @@
 ---
 name: project-node-memory-guide
-description: 用 .nodekb/ + kb_* 工具沉淀项目长期知识（设计决策、踩坑、事实常量、待办、交接）时的写法规范——什么时候该写、文件怎么分、TID 怎么起、先读什么再写什么。准备手写 docs/*.md 之前先读这一条。
+description: 用 .nodekb/ + kb_* 工具沉淀项目长期知识（设计决策、踩坑、事实常量、待办、交接）时的写法规范——什么时候该写、文件怎么分、TID 怎么起、唯一事实用 tscl 怎么共享、先读什么再写什么。准备手写 docs/*.md 之前先读这一条。
 ---
 
 # 写项目节点知识库（`.nodekb/`）
@@ -15,7 +15,7 @@ description: 用 .nodekb/ + kb_* 工具沉淀项目长期知识（设计决策
 
 ```
 kb_read mode=toc            # 结构 + 每节字符数，几百 token
-kb_read target=<TID>        # 按需读一支（引用会就地展开）
+kb_read target=<TID>        # 按需读一支
 kb_search query=...         # toc 里找不到再搜
 ```
 
@@ -26,19 +26,43 @@ kb_search query=...         # toc 里找不到再搜
 | 目录 | 放什么 | 判据 |
 |---|---|---|
 | `doc/` | 主题文档：架构、模块、流程、配置 | 「是什么、怎么运转」 |
-| `facts/` | 常量与事实：版本、路径、阈值、接口 | 一句话能说完、会被反复引用 |
 | `lessons/` | 踩坑记录 | 「症状 → 根因 → 对策」三行齐全 |
 | `todo/` | 未完成事项、阻塞、交接 | 有明确的下一步动作 |
 | `index/entry.md` | 总入口与落位约定 | 只放导航，不放正文 |
 
-一个主题一个文件，**单文件取 < 4KB**；变大就按子主题拆成 `## 3.x` 段或独立文件。结论只写一次，别处用 `[[TID]]` 引用。
+这张表是「不知道放哪时」的默认答案，**不是白名单**：项目没有待办就别建 `todo/`，需要 `adr/`、`api/`、`runbook/`、`metrics/` 就自己加；节点 `type` 同样自由（`type="decision"`、`type="api"` 都行）。
+
+一个主题一个文件，**单文件取 < 4KB**；变大就按子主题拆成 `## 3.x` 段或独立文件。
+
+## 两种引用，别混
+
+| 写法 | 渲染成 | 用在 |
+|---|---|---|
+| `[[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 全库只能定义一次**，否则 `kb_diag` 报 error（重复定义）。
+- id 不能和节点 TID 同名（命名空间冲突 = error）。惯例：值用 `fact:` 前缀，结构用目录前缀。
+- 宏体**跨行**时不要内联进表格单元格（diag 会 warning，渲染也会断行）。
+- 定义块内部的 `##` **不会**变成节点——它只是文本。
+
+旧写法 `[[TID]]` 仍能解析（有定义时当宏、否则当链接），但 `kb_diag` 会 warning，2.0 移除。
+接手老库时先跑 `kb_migrate`（默认只演练），看清每处会改成 `[[node=…]]` 还是 `[[tscl=…]]` 再 `dry_run=false`。
 
 ## TID 规则
 
 - 文件节点：`<目录>:<文件名 slug>`，例如 `doc/03-工程经验与坑.md` → `doc:03-工程经验与坑`
 - 显式节点：`<node name="abi">` 里的 `name` 原样就是 TID，可跨文件引用
-- 段节点：`## 3.1 xxx` → `<文件TID>:3.1`，但它是**位置型**的，不受引用校验保护——别拿它当引用目标，要引用就用显式节点
-- 引用写成 `[[TID]]` 或 `[[显示文字|TID]]`；改名走 `kb_rename`，它会重写全库引用
+- 段节点：`## 3.1 xxx` → `<文件TID>:3.1`，是**位置型**的：插一节就漂。链接它只是 warning（指错了跳错节），但**别拿它当需要长期稳定的锚点**——要稳定就写显式节点
+- 改名走 `kb_rename`，它会重写全库引用
 
 ## 写
 
@@ -48,12 +72,12 @@ 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/` 各写一份 —— 引用它，别复制它。
+2. 同一件事在 `doc/` 和 `lessons/` 各写一份 —— 抽成 `<tscl>` 定义，两处都引用它。
 3. 只写「改了什么」不写「为什么」 —— 半年后没人知道能不能改回去。