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：分析每条批注的意图

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

步骤 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 才继续。
• 命令格式：

  typst compile "<subject>/initial.typ" "<subject>/initial.pdf" --root .
  

  工作目录为仓库根 c:\Notiz\MathRepo。
• 涉及多个笔记时，每个笔记都要编译一遍。

步骤 7：总结

全部完成后，给出：

• 每条问题的修改位置（可点击链接）
• 编译验证结果（两个笔记的退出码）

4. 注意事项

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