# 诊断明细（`kb_diag` / `kb_search` / `kb_read` 的读法）

`SKILL.md` 里只留三档与阈值；这里是**报警看不懂时**要读的那一份。

## 三档各是什么

| 档         | 含义                                                                            | 怎么处理                   |
| ---------- | ------------------------------------------------------------------------------- | -------------------------- |
| `errors`   | 真损坏：悬空引用、重复 TID、重复定义、树环、未闭合的 `<node>` / `<tscl>`          | 必修，否则库结构已坏       |
| `warnings` | 疑似漂移：旧语法裸引用、位置型 TID 链接、跨行宏进表格、孤儿节点、散文/反引号里不可解析的 TID 文本、TID 大小写不合规、违反本库 `rules.json` 的规矩 | 按需处理                   |
| `advice`   | **没有问题，但可改进**：碎片文件过多、同一句散在多处、缺入口、缺 H1、段节点过长、示例被写成了定义 | 建议处理，不影响 exit_code |

`advice` 每条都带 `fix`，一次最多报 5 条，**不会让 `kb_diag` 失败**——CI 里可以无视。

## advice 阈值（默认值，可在插件配置 `advice: { … }` 里覆盖同名项）

| 项             | 默认  | 判据                                                         |
| -------------- | ----- | ------------------------------------------------------------ |
| `minFragNodes` | 10    | 「整篇都很小」的文件达到这么多个才提示合并                   |
| `fragChars`    | 500   | 「整篇」= 导语 + 全部 `##` 段 + 显式节点正文；小于它算小文件 |
| `longSection`  | 10000 | 单个 `##` 段节点超过这么多字符 → 建议拆节                    |
| `maxItems`     | 5     | 一次最多报几条 advice                                        |

段节点过长按**单个 `##` 段**算：拆节请拆 `##`（`###` 不建节点，拆了还是同一段）。`long-section` 的 `fix` 会点明拆节会让位置型 TID 漂移。

## advice 怎么关、怎么限量、怎么豁免（1.5.15；1.5.17 起整条 warnings 也能压）

- 整块关掉：插件配置 `advice: { display: false }`（有的库结构刻意松散，看建议只会分心）。
- 条数：`advice: { maxItems: 10 }` 改默认上限；`advice: { limit: 0 }` = 全部给出（`limit` 显式给了就以它为准，`0` 不是"没有"）。
- 逐条豁免：`diag_ignore.json` 的第四项 `advice`，形如 `{"advice":[{"code":"long-section","tid":"lesson:0"}]}`；`code` 与 `tid` 都是正则、**同时命中**才压掉（只写 `code` 会把同类建议全压掉，只写 `tid` 会压掉该节点的全部建议）。
- **整条 warnings 豁免**（1.5.17）：`diag_ignore.json` 的第五项 `warnings` 是正则列表，匹配的是告警文案本身（如 `不可解析的 TID 文本`），一条命中就把那条告警从报告里拿掉。适合「库里大量手写示例、又不想挨条改」的场景；比 `tids` 粗，能不用就不用。
- 命令行（`nodekb diag`）与工具层吃同一份配置：同一个库、同样的阈值，两边结论一致。

`merge-fragments` 按**整篇**判（文件节点正文 + 它下面全部 `##` 段与 `<node>` 的总字数），不只数 H1 到第一个 `##` 之间那句导语——「一文件一章节、正文都在 `##` 下」是推荐布局，不该被判碎片。「同一句散在多处」只报最扎眼的 2 条。

## `example-tscl`：示例被写成了定义（1.5.17）

> 2 个定义体里带着 `##` 标题 / `<node>` 标签：doc:01-a、doc:02-b——多半是把示例写成了定义

根因：`<tscl …>` 出现在**行首**就是真定义，后面不写 `</tscl>` 会一路吞到下一个闭合标签，示例后面的正文全进了定义体。

修：示例放进 ``` 围栏（围栏里不解析）或改成行内写法；真要定义就把值收成一句话、`</tscl>` 紧跟着写。

## 豁免表 `.nodekb/diag_ignore.json`

`{"blocks":[…],"lines":[…],"tids":[…],"advice":[…],"warnings":[…]}`：前三组与 `warnings` 是**正则**列表（逐条 `new RegExp(...)`），`advice` 是对象列表。

- 按字面匹配要自己转义 `(` `)` `[` `]` `+` `|` `\` 这类元字符；非法正则会被静默跳过、不报错，于是「整段原文直接贴」只对不含元字符的样板有效。
- `blocks` 比的是归一化空白后的整段文本；`lines` 比的是单行原文。
- `tids` 只压「不可解析的 TID 文本」与「TID 大小写不合规」这两条，匹配的是 token 本身（如 `^doc:01-ignored$`）。
- `warnings` 匹配告警文案全文，如 `^不可解析的 TID 文本`；`advice` 是 `{code, tid}` 同时命中（见上）。

## 外形像 TID 的文本也会被核对（1.5.12）

围栏外散文与行内代码里形如 `命名空间:其余` 的 token，只要命名空间是本库真实存在的（某个 TID 的首段、目录 `type`、`root`），就会被检查能否解析：

- `doc:03-build` 这种手写错的 TID：`不可解析的 TID 文本 … 文件第 N 行「…」；最接近: …`
- 大小写写错（`doc:01-REAL`）：`TID 大小写不合规 … → 应写「doc:01-real」`
- 不报：反例（`×` / `✗` 前缀）、占位符（`doc:x`）、URL、markdown 链接目标、路径样子（`doc/03-build.md`）、别的命名空间。

## 悬空引用的两种可能（1.5.15）

`悬空引用: doc:… → [[node="doc:示例"]]（目标不存在：要么 TID 写错了，要么这里只是举例——举例请用反引号包起来：\`[[node="doc:示例"]]\`）`

文档里要**展示**引用写法时，把示例放进反引号（行内代码或围栏）——解析器不会把代码里的 `[[…]]` 当真引用。同一处不会再被「不可解析的 TID 文本」重复报一遍。

## 插件升级后的一次性提醒

插件升级后第一次跑 `kb_diag`，报告里会多出一条 `plugin-updated`：「规则变了，先重读本技能」。每条库只提醒一次（记在 `.nodekb/.plugin-state.json`，位置在 `.git/info/exclude` 里——诊断不会把库弄成「有未提交改动」）。

这条提醒**不受** `advice: { display: false }` 控制（那个开关只关改进建议），但**计入** `advice.limit` / `maxItems`——它排在 advice 最前，超上限时先被截掉的是后面的建议。状态文件写不进去时（只读库、权限不足），回执里会多一句「（状态文件写不进去，下次还会提醒）」；命令行 `nodekb diag` 与 `kb_diag` 行为一致（1.5.18 起命令行也吃 `advice.limit`）。
