# 语法明细：节点、TID、引用、代码区

`SKILL.md` 里只留了每次都用得到的部分；这里是完整规则，**写不清的时候读这一份**。

## TID 怎么起

- **文件节点**：`<目录>:<文件名 slug>`，例如 `doc/03-工程经验与坑.md` → `doc:03-工程经验与坑`。
- **显式节点**：`<node name="abi">` 里的 `name` 原样就是 TID，可跨文件引用（`tid="…"` 等价，`title="…"` 可另给显示名）。**TID 不要求含冒号**。
- **库根直接放的文件**（如 `README.md`、`README_EN.md`）TID **没有目录前缀**，就是 `readme`；但它是**文件节点**，`kb_write` 只能用「路径 + replace」改整篇，写 `target=readme` 会被拒绝。
- **段节点**：`## 3.1 xxx` → `<文件TID>:3.1`。它是**位置型**的：插一节就漂。链接它只是 warning（指错了跳错节），别拿它当需要长期稳定的锚点——要稳定就写显式节点。
- **段节点的父节点恒为文件节点**，不会被同文件里的 `<node>` 抢走。所以「按 `##` 组织」和「具名锚点」可以同时用在一个文件里，TOC 里两者并列。
- **ASCII 部分会被小写化**：文件名里的 `SSH`、`T7` 在 TID 里是 `ssh`、`t7`。引用大写的 TID 一律悬空（diag 会报「TID 大小写不合规 … → 应写 …」）。

## 属性缺省（1.5.8 起）

- `title` 缺省 = `name`（H1 只决定**文件节点**的标题，不进任何节点正文）。
- `type` 缺省取所在目录名（`doc` / `lessons` …）。
- `parent` 缺省 = **文件节点**——同一文件里多个 `<node>` 是彼此并列的兄弟，**不会**链式挂到「本文件第一个 `<node>`」下面。要嵌套就把外层 `<node>` 写开、把内层写进去，或显式写 `parent="…"`。
- 属性**单双引号等价**（`name='abi'` 与 `name="abi"` 一样）。

## 手写 `<node>` 的规矩

- 开闭标签各占一行；缺 `name` / `tid` 的块会整段退回正文并在 diag 里 warning，不会静默丢失。
- 单行写法 `<node name="x">正文</node>` 合法（1.5.6 起）。
- 正文里**不要**出现 `</node>`——它会把节点提前截断。

## 读的时候可以偷懒

- **前缀兜底**：`kb_read target=doc:02` 能命中 `doc:02-运行环境`（按 slug 前缀匹配，唯一才命中；多个候选会报 `未找到节点 … 候选:`）。
- **写引用仍要写全 TID**——前缀只对读生效。

## 两种引用

| 写法                          | 渲染成                                         |
| ----------------------------- | ---------------------------------------------- |
| `[[node="doc:03-build:3.1"]]` | 一个链接，**不复制正文**                       |
| `[[tscl="fact:abi"]]`         | 把 `<tscl id="fact:abi">` 的定义体**替换进来** |

**tscl 规则**：

- **同一个 id 全库只能定义一次**。
- id 不能和节点 TID 同名。惯例：值用 `fact:` 前缀，结构用目录前缀。
- 定义可以**就地写在正文句子里**：`当前版本号为：<tscl id="fact:ver">v1.23.45</tscl>，向下兼容 v1.22。`（渲染时标签被剥掉，别处写 `[[tscl="fact:ver"]]` 展开同一个值）。这种句内定义**必须单行闭合**。
- 宏体**跨行**时不要内联进表格单元格；定义本身也别写进表格行（`|` 会破格）。
- 要核一个值：`kb_read target=<定义 id>` 直接回定义体、定义处、被谁引用。
- 定义块内部的 `##` **不会**变成节点——它只是文本。

## 代码区不解析

- ` ``` ` / `~~~` 围栏与行内代码里的 `[[…]]`、`<node>`、`<tscl>` 都是示例：不解析、不计引用、不跟着改名。
- 两种围栏**同等对待**：闭围栏必须同字符且不短于开围栏。
- 讲语法时直接写在代码里即可（写入校验、诊断、改名、advice 全部走同一个 `makeFenceTracker`）。

## 渲染细节

- 一次渲染里宏展开上限 **64 次**（病态循环引用会直接报错，而不是把上下文撑爆）。
- 读一支子树时会**渲染两遍**：第一遍收集这一支里哪些定义被展开过，第二遍把同支内的定义块抹掉——所以定义和它的引用在同一支里时，值只出现一次。
