project-node-memory 1.2.1 → 1.3.2

package/README.md

@@ -183,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
@@ -205,7 +217,7 @@ kb_write mode=node target=<TID> content=…  # 逐条改，或直接改 md 再 k
 ## 自检（不装 DSH 也能跑）
 
 ```bash
-node scripts/check.mjs      # 280 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / tscl / 提示词段落 / 随包技能
+node scripts/check.mjs      # 292 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / tscl / 提示词段落 / 随包技能
 node test/parity.mjs        # 与 Python 原实现逐条对拍（需要 python 与 nodekb 源码）
 ```
 

package/README_EN.md

@@ -161,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
 
@@ -188,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      # 280 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/host/prompt.js

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-node-memory",
-  "version": "1.2.1",
+  "version": "1.3.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,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,11 @@ 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>` 定义，两处都引用它。
-3. 只写「改了什么」不写「为什么」 —— 半年后没人知道能不能改回去。
+1. 不要把整段对话贴进 `doc/` —— 记的是过程，不是结论。
+2. 不要把同一件事在 `doc/` 和 `lessons/` 各写一份 —— 抽成 `<tscl>` 定义，两处都引用它。