---
name: annotate
description: >-
  给一本书某个阅读单元的原文，写一条划线批注笔记，存进旁车 `NN.notes.md`（原文不动），
  让 Obsidian 高亮那段、点开看笔记。当陪读 / 讨论中聊清了原文某处此处的意思、想留个重读时
  就地浮现的记号，或用户说「给这段写个批注 / 记个笔记 / 标一下这里 / 划线记一下 / 在这旁边记一笔」时，
  使用本 skill。划线范围默认就是用户带进上下文的那段原文，逐字照抄；脚本把锚点对原文做精确校验、按格式写入。
---

# annotate — 给原文写一条批注笔记

批注 = 贴在阅读单元 `NN.md` 某段原文上的划线笔记，存进同目录旁车 `NN.notes.md`，**原文一字不改**。读的时候 Obsidian 的 notes-anchor 插件会把那段高亮、点开显示笔记。

## 锚点划哪段

**默认：就是用户带进上下文的那段原文。** 批注几乎都发生在用户把一段原文贴进提问、问「这段什么意思」的时候——他贴的那段（一句、两三句、还是一整段）**就是**锚点，**逐字照抄、整段照划，不从里面再挑某一句**。

**例外：用户没带原文、但确实聊清了某处值得就地留记号**——这时才由你回 `NN.md`，自己定锚在哪段 / 哪句 / 哪几句上。

你只定两件事：**锚点**（默认即用户那段原文）和**笔记写什么**。格式、frontmatter、追加还是新建、以及最容易翻车的「锚点对不对得上原文」，全交给脚本。

## 怎么写一条

1. 认准是哪个单元（`book` / `chapter` / `unit`），锚点回 `NN.md` **核对、取它在原文里的逐字写法**——标点、全 / 半角都要对上，脚本按精确子串校验，对不上会报错。
2. 跑脚本，从 stdin 喂一段 JSON（`SKILL` = 本 skill 目录）：

```bash
python3 SKILL/scripts/write_note.py <<'JSON'
{"book":"道德经","chapter":"ch08","unit":"01",
 "anchor":"上善若水。水善利万物而不争，处众人之所恶，故几于道。",
 "body":"不争不是退让，是水利万物却不抢功、不居其上——有能力者的处下。"}
JSON
```

`author` 默认 `Claude`、`date` 默认今天、`root` 默认项目根，一般不用填。`body` 可多行（JSON 里用 `\n`）。

3. 脚本把锚点和原文都剥掉 `**` / `*` / `` ` `` 再比对：**对不上就报错、不写**——这是批注唯一会出错的地方，交给它兜底。通过则按 callout 格式写好署名，追加进 `NN.notes.md`（没有就新建带 frontmatter）。
4. 脚本打印写入路径，**据此简短告知用户**，如：「已为《道德经》`ch08/01` 的「上善若水……」写了批注 → `books/道德经/ch08/01.notes.md`」。

## 几条要把握的

- **锚点落在同一个自然段内**——跨段插件高亮不出来。用户带来的那段若跨了自然段，按段拆成多条批注。
- **不重复备读**：第 2-4 段（字词注 / 白话 / 注家对照）里已经写过的，别再钉成批注。批注只收**对话现场新解清**的那一笔。
- **body 两种**：
  - 独立批注——就这段此处的理解，直接写清楚；
  - 指针批注（中间地带：同一处你又写了一条 insight）——只写一句指过去、别抄 insight 全文，如 `这段是 [[概念/不争]] 的出处`。
- **只给 `NN.md` 写**：insight、INDEX 等衍生文件不写批注旁车，它们靠续写 + 互链演化。

## 脚本产出的 callout 长这样（供对照）

```markdown
> [!note] 划线：上善若水。水善利万物而不争，处众人之所恶，故几于道。
> 不争不是退让，是水利万物却不抢功、不居其上——有能力者的处下。
> · Claude 2026-06-05
```
