# Review Annotation

> 处理 reviewer 批注文件：解析批注、定位源码、分析问题、给出修改方案，待用户确认后执行并编译验证。当用户提供批注文件（如 temp/【批注】XXX.censoring.md）并要求处理时调用。

- Skill: `locusyuri/review-annotation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add locusyuri/review-annotation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/locusyuri/review-annotation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: locusyuri (https://skillmd.com/u/locusyuri)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/locusyuri/review-annotation

---


# Review Annotation Processor // 批注处理

## 1. 何时使用

当用户提供一个 reviewer 批注文件（典型路径 `temp/【批注】<笔记名>.censoring.md`），并要求"处理批注"/"修改"/"分析问题"时，激活本技能。

本技能的核心契约是：**先分析 + 出方案 + 等用户确认，再动手改代码**。绝不跳过确认直接修改。

## 2. 批注文件格式

批注文件通常长这样（来自 PDF 高亮导出）：

```
1.第4页 【高亮】

Familiar operations: addition and

附注：它只是一个S2 到 S的映射，并没有什么

2.第6页 【高亮】

1.2 Equivalence Relations and Quotient Sets

附注：全部移动到集合论
```

每条批注由三部分组成：
- **编号 + 页码**：`N.第X页 【高亮】` —— **页码不可靠，忽略不用，不写入方案**。
- **高亮文本**：被 reviewer 标出的原文片段，是 PDF 渲染后的文本，与源码中的 Typst 源码形式可能差异较大（见步骤 2）。
- **附注**：reviewer 的修改意见（中文）

## 3. 工作流

### 步骤 1：读取批注文件

- 用户会给出文件路径（如 `temp/【批注】Algèbre Abstraite.censoring.md`）。
- 用 Read 工具读取全文。

### 步骤 2：定位高亮文本在源码中的位置

**唯一可靠的定位依据是高亮文本本身**，不是页码。高亮文本是 PDF 渲染后的输出，与 Typst 源码可能存在显著差异，需要按下述流程处理：

1. **识别高亮文本类型**：
   - **纯英文散文**（如 `Familiar operations: addition and`）—— 直接作为搜索词。
   - **章节标题**（如 `1.2 Equivalence Relations and Quotient Sets`）—— 取标题核心词搜索 `== ` 标题行。
   - **含数学符号的片段**（如 `𝑆 ≡ 𝑇`、`a ∼ b iff ...`）—— PDF 渲染的 Unicode 数学符号必须先转换为 Typst 数学语法再搜索。常见转换：
     | PDF 渲染 | Typst 源码 |
     |---------|-----------|
     | `𝑆` `𝑇` 等粗斜体大写 | `S` `T` |
     | `≡` | `equiv` |
     | `∼` `~` | `tilde` 或 `~` |
     | `≠` | `!=` |
     | `⊆` | `subset.eq` |
     | `∩` | `intersection` 或 `sect` |
     | `∪` | `union` |
     | `→` | `arrow.r` |
     | `×` | `times` |
     | `∈` | `in` |
     | `∅` | `emptyset` |
     | `ℤ` `ℝ` `ℚ` | `bb(Z)` `bb(R)` `bb(Q)` |
     | `⊕` | `plus.circle` 或 Unicode `⊕` |
     | 上标如 `S²` | `S^2` |
     | 下标如 `a₁` | `a_1` |
   - **纯 Unicode 数学片段**（如 `𝑆 ≡ 𝑇`）—— 转换为 Typst 语法（`S equiv T`）后搜索。

2. **Grep 搜索**：在目标笔记的 `initial.typ` 中搜索转换后的关键词。取最有辨识度的 3-5 个连续词，避免取注释或常见词（如 `the` `a` `is`）。
   - 若一次搜索命中多个位置，结合附注内容判断哪个是目标位置。
   - 若搜索无结果，尝试缩短关键词或换一组关键词重试。

3. **读取上下文**：定位到行号后，读取前后约 30 行，理解该处组件结构和上下文，确认是批注指向的位置。

4. **找不到位置时的兜底**：若多次搜索均无法定位，**询问用户**："批注 N 的高亮文本是『XXX』，在源码中未找到对应位置，请指出该处在 `initial.typ` 的大致行号或所属小节标题。" **不要猜位置、不要跳过该批注**。

### 步骤 3：分析每条批注的意图

把批注归类为以下常见类型之一（可组合）：

| 类型 | 附注典型措辞 | 处理方向 |
|------|-------------|---------|
| **补充说明** | "说明清楚…"、"仅仅是…"、"并没有什么特别之处" | 在该位置附近新增 `#note` 或散文段落，把 reviewer 想强调的点讲透 |
| **迁移内容** | "全部移动到集合论"、"移到 XX 笔记" | 把对应块迁移到目标笔记；更新所有跨文档引用（见步骤 5） |
| **补充定义/定理** | "少了自同态"、"缺保运算律" | 在相关定义/性质之后新增对应组件 |
| **纠错** | "这里错了"、"符号不对" | 直接修正公式/符号 |
| **重写** | "重写这一段"、"逻辑不清" | 重写该段，保持原有标签不变（若已有） |

### 步骤 4：输出修改方案并请求确认

对每条批注，给出结构化方案：

```
**问题 N**：<一句话概括 reviewer 的诉求>

**位置**：[section 标题](file:///绝对路径#L起-L止)

**现状**：<当前内容的问题>

**方案**：<具体怎么改——新增/删除/迁移/修改，涉及哪些组件和标签>
```

全部问题列完后，问用户："请确认是否按上述方案执行？如有调整请指出。"

**等待用户明确同意后**才进入步骤 5。用户说"按你的建议来"/"确认"/"开始"即为同意。

### 步骤 5：执行修改

按方案逐条修改，遵循以下纪律：

1. **符号规范**：优先用 Unicode 符号（`⊕` `∘` `∩` `⊆` 等）而非 Typst 修饰符；遇到不确定的符号先试编译再修。常见坑见项目记忆。
2. **跨文档标签**：每个 `initial.typ` 独立编译，`#link(<label>)` **不跨文档**。若把某块从笔记 A 迁到笔记 B：
   - A 中指向该块标签的 `#link` 必须改为文字提及（如"见 Théorie des Ensembles 笔记"）。
   - B 中保留原标签（在 B 内部仍可用 `#link`）。
3. **图片迁移**：若被迁内容含 `#figure(image("img/xxx.svg"))`，需把图片文件复制到目标笔记的 `img/` 目录（不存在则新建），并从原笔记 `img/` 删除孤立副本。
4. **保留标签**：修改时尽量保留已有 `<label>`，避免破坏后文 `#link`。若必须删除标签，先 Grep 全文确认无引用。

### 步骤 6：分批编译验证

- 每完成一类改动（如一个问题、或一个文件），立即 `typst compile` 验证，退出码 0 才继续。
- 命令格式：
  ```bash
  typst compile "<subject>/initial.typ" "<subject>/initial.pdf" --root .
  ```
  工作目录为仓库根 `c:\Notiz\MathRepo`。
- 涉及多个笔记时，每个笔记都要编译一遍。

### 步骤 7：总结

全部完成后，给出：
- 每条问题的修改位置（可点击链接）
- 编译验证结果（两个笔记的退出码）

## 4. 注意事项

- **不要跳过确认**：哪怕方案看起来显而易见，也必须先呈现方案等用户同意。这是本技能的硬约束。
- **页码不可靠，忽略不用**：批注里的"第 X 页"是 PDF 页码，与源码行号无对应关系；定位唯一依据是高亮文本。方案中**不写页码**，只写源码行号链接。
- **高亮文本是 PDF 渲染后的形式**：与 Typst 源码差异可能很大（数学符号最明显），必须先转换再搜索，见步骤 2 的转换表。
- **找不到位置就问用户**：不要靠页码猜、不要跳过该批注，直接询问用户该处的源码位置。
- **高亮文本可能截断**：搜索时用关键词而非整句匹配。
- **方案要具体**：不要只说"在这里加个说明"，要说清楚加 `#note` 还是散文、放在哪个组件之后、标签叫什么。
- **改动最小化**：只改批注涉及的部分，不顺手重构无关内容。