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` 还是散文、放在哪个组件之后、标签叫什么。 - **改动最小化**：只改批注涉及的部分，不顺手重构无关内容。