# 写入明细（`kb_write`）

`SKILL.md` 里只留三条铁律；这里是完整规则，**写入被拒或回执看不懂时读这一份**。

## 四种写法

```
kb_write target=lessons/003-cp936.md   mode=create  content=...
kb_write target=<显式节点TID>          mode=node    content=...   # 只换 <node> 之间的正文
kb_write target=<段节点TID>            mode=node    content=...   # 也可以换 ## 段落的正文
kb_write target=doc/03-...md           mode=append  content=...
```

## `target` 判定顺序

库里已有的 TID（含没有冒号的）→ 库根文件名 → 像路径的字符串（补 `.md`）。三者都不是就报「没有名为 … 的文件或节点」。

## 基本要求

- 写完**看返回值里的校验结果**：悬空引用、重复定义、`<node>` 没独占一行，都会当场报回来。
- 改已有内容用 `append` / `node`，**不要 `replace` 整篇**（会丢掉别人刚写的段落）。
- 新建文件前先 `kb_read mode=toc` 确认没有同主题的旧文件。
- 库是内嵌 git 仓库，**写入/改名成功后会自动快照**：commit message 形如 `autosnap: 3 处变更`，回执里有一行 `快照: autosnap: 3 处变更`。**写后自检有 error 时不再快照**，修好后的下一次写入会一并提交。看历史用 `kb_vcs_status`（默认最近 5 条，`count` 可调）。不想要快照就配 `git: false`。

## `mode=node` 的限制

- 段节点一旦写过 `<node>` / `<tscl>` 标签，或段内还有更深的标题（`###`…），这段就**不能再用 `mode=node` 改**（工具会拒绝），改走「路径 + `mode=replace`」，或先 `kb_read` 出来整段重写。围栏里的标签与 `#` 是示例，不算数。
- 段写入的标题语义（1.5.15 起有明确三条）：
  - 首行是**同级或更浅**的标题 → 连标题一起换（改段名、降级都靠这条，不用整篇 `replace` 了）；
  - 首行**恰好是本段标题** → 自动剥掉（`kb_read` 渲染出来就带标题，直接贴回去是常见操作，不该变成第二个同名段）；
  - 首行比本段**更深**，或正文中间还有标题行 → 拒绝——段正文里插标题会新开一个段、把本段静默劈成两半。要加子节请用路径 + `replace` 整篇重写。
- 段边界只认围栏外的 `#` / `##`；`###` 及更深**不建节点、也不切段**——它是段正文的一部分（所以别写 `[[node="doc:01-x:1.1"]]`，diag 会报「TID 前缀指向不存在的节点」）。

## 格式与校验

- 文件原本用 CRLF 就继续用 CRLF（不会被写成混排）。`content` 里的 CRLF 会被归一成 LF、落盘时再按原文件的换行写回；`append` 的结尾换行由工具补。
- 路径必须是**小写 `.md`**，且不能有点开头的目录/文件（解析器会跳过）。回执里的路径统一 `/` 分隔。
- 段写入会自动补「标题 / 空行 / 正文 / 空行」，且**幂等**——同一段连写多次不会每次多长一个空行。
- 写入校验与解析器同一口径：围栏和**行内代码**里的 `<node>` / `<tscl>` 是示例，不拦；报错行号按你传的 `content` 算（首尾空行不计）。
- `content` 里**不要写 `</node>`**：它会把节点提前截断；工具会直接拒。`<node>` / `<tscl>` 开标签要求成对，未闭合会吞掉后面的节点/段，同样被拒。两种合法写法：单行 `<node name="x">正文</node>`、「行首定义 + 同行后缀」的 `<tscl id="v">1</tscl>` 后面带说明；整篇 `mode=replace` 不受成对检查限制。
- 写进去的坏结构（手改、git 合并、`replace` 逃生口）由**解析器收尾兜底**：未闭合的 `<node>` / `<tscl>` 会让 `kb_diag` 报 **error**。

## 写入校验的两层

- `validateContent`：标签形态 + 成对（`mode=replace` 关掉成对那半）+ 标题行。
- `writeInto` 入口：换行归一、路径检查、段边界解析。
- 改名除了重写引用，收尾也跑一次 `diag` 把 error 带进回执。

## 板块纪律：todo 只放未完成项

`todo/` 是**待办列表**，不是流水账。做完的事当场搬走：定稿结论进 `doc/` 对应板块，踩坑进 `lessons/`，已发布的批次/收口清单/流程约定进 `doc/` 的版本史一类文件。留在 todo 里的「已完成」段落会让下一个人分不清「还在做」和「早做完了」——要么重复做，要么漏做。
