From 6c458fb02a594aeae45081dcfd8a5cc97badf36c Mon Sep 17 00:00:00 2001
From: Research Assistant <research@example.com>
Date: Tue, 19 May 2026 14:52:09 +0800
Subject: [PATCH] refactor(skill): migrate single-paper and deep-read molecules

---
 .../molecules/deep-analyze-paper.md           | 186 +++++++++++++++++-
 .../paperforge/molecules/read-known-paper.md  | 113 ++++++++++-
 2 files changed, 297 insertions(+), 2 deletions(-)

diff --git a/paperforge/skills/paperforge/molecules/deep-analyze-paper.md b/paperforge/skills/paperforge/molecules/deep-analyze-paper.md
index d286399c..05139914 100644
--- a/paperforge/skills/paperforge/molecules/deep-analyze-paper.md
+++ b/paperforge/skills/paperforge/molecules/deep-analyze-paper.md
@@ -1,3 +1,187 @@
 # deep-analyze-paper
 
-Perform deep structural and methodological analysis of a paper.
+> [!warning] Safety Rules
+> - **禁止主动加 `--force`** — 只有用户明确要求重读时才能用
+> - **禁止猜测 `--figures N`** — N 必须来自 Step 1 prepare 输出的实际数字
+> - **禁止重复跑 `prepare`** — prepare 只跑一次。跑了两次以上 → 检查 note 结构是否被破坏
+> - 不要在 Pass 1 完成前碰 Pass 2/3
+> - 不要把推断写成文献事实——区分"作者说了 X"和"我推断 Y"
+> - 不要跨 figure 写综合判断（Pass 2 逐图，Pass 3 才做综合）
+> - validate 失败超过 3 轮 → 执行自查清单，不要盲目重试
+
+Keshav 三阶段精读。在 formal note 中写入结构化的 `## 精读` 区域。
+
+---
+
+## 前置检查
+
+### Step 0: paper-context（必须）
+
+```bash
+$PYTHON -m paperforge --vault "$VAULT" paper-context <zotero_key> --json
+```
+
+检查返回 JSON：
+- `ok: false` → 报告 `error.message`，停止
+- `data.paper.ocr_status != "done"` → "OCR 未完成，请先运行 paperforge ocr"，停止
+- `data.paper.analyze != true` → "analyze 未开启，请在 formal note frontmatter 中设为 true"，停止
+
+**检查 prior_notes：**
+- 如果存在 `data.prior_notes`，逐条看 `verified` 字段
+- `verified: false` 的条目记入 recheck_targets，精读时必须回原文复核这些位置
+- `verified: true` 的条目可以信任，但标注"之前已验证"
+
+**记录关键路径：**
+- `data.paper.note_path`（formal note 路径）
+- `data.paper.fulltext_path`（fulltext 路径）
+- 记下 `recheck_targets` 列表
+
+---
+
+## 执行流程
+
+### Step 1: Prepare（跑脚本）
+
+```bash
+$PYTHON "$SKILL_DIR/scripts/pf_deep.py" prepare --key <zotero_key> --vault "$VAULT"
+```
+
+> [!warning] `--force` 禁止在精读过程中使用。`--force` 会清除已有精读内容重新生成骨架，仅在用户明确要求重读时才能用。任何时候都不要主动加 `--force`。
+
+解析返回 JSON：
+- `status: "ok"` → **记下 `figures`（数字）、`tables`（数字）、`figure_map`、`chart_type_map`、`formal_note`、`fulltext_md` 路径**
+- `status: "warn"` + `deep_reading_status: done` → 告知用户"该文献已精读过"，确认是否重读
+- `status: "error"` → 报告 `message`，停止
+
+**把 `figures` 数量记在当前上下文**——Step 4 要用。
+
+读 formal note，确认 `## 精读` 骨架已插入。
+
+---
+
+### Step 2: Pass 1 — 概览
+
+只填 `### Pass 1: 概览`。不碰 Pass 2/3。
+
+填写内容必须来自原文，不可推断：
+
+- **一句话总览**：论文类型 + 核心发现，一句话
+- **5 Cs 快速评估**：
+  - Category（RCT / 队列 / 综述 / 基础研究等）
+  - Context（领域共识，本文要解决什么）
+  - Correctness（初步直觉，逻辑有否明显漏洞）
+  - Contributions（1-3 条）
+  - Clarity（写作质量，图表可读性）
+- **Figure 导读**（基于 fulltext 浏览各图 caption）：
+  - 关键主图：列出，一句话概括要证明什么
+  - 证据转折点：哪个 figure 是叙事关键转折
+  - 需要重点展开的 supplementary
+  - 关键表格
+
+填完立即保存。
+
+---
+
+### Step 3: Pass 2 — 精读还原
+
+填 `### Pass 2: 精读还原`。**按 figure 顺序逐个处理**。
+
+每处理完一个 figure 立即保存。
+
+#### 图表类型定位（两步）
+
+**A: 读 chart-type-map**（prepare 输出中包含该路径）。这是关键词命中建议。
+
+**B: Agent 读 caption 做最终判断**
+1. 读该 figure 的 caption（来自 fulltext）
+2. 打开 `atoms/chart-reading/INDEX.md`，对照 caption 内容判断图表类型
+3. chart-type-map 建议和 Agent 判断不一致时 → 以 Agent 判断为准
+4. 无法确定类型 → 跳过 chart guide，按通用结构分析
+5. 确定类型 → 读对应 chart-reading 指南，按指南中的检查清单分析
+
+#### 每张 Figure 的子标题（固定，不可跳过）
+
+```
+**图像定位与核心问题**：页码 + 要回答什么问题
+**方法与结果**：实验设计 / 数据来源 / 技术手段；核心数据、趋势、对比
+**图表质量审查**：按 chart-reading 指南检查坐标轴、单位、误差棒、统计标注
+**作者解释**：作者在正文中对该图的解读
+**我的理解**：自己的理解（必须与作者解释做明显区分）
+**疑点/局限**：用 `> [!warning]` 突出
+```
+
+#### 每张 Table 的子标题（简化版）
+
+```
+回答什么问题、关键字段/分组、主要结果、我的理解、疑点/局限
+```
+
+#### 所有 figure/table 处理完后
+
+**关键方法补课**：简要解释不熟悉的实验技术（1-2 项）
+
+**主要发现与新意**：
+- 发现 1：...（来源：Figure X）
+- 发现 2：...（来源：Table Y）
+- 每条发现必须标注来源（Figure 编号或正文段落）
+
+---
+
+### Step 4: Postprocess（跑校验，修正问题）
+
+**`N` = Step 1 prepare 输出中的 `figures` 值，不要自己猜。**
+
+```bash
+$PYTHON "$SKILL_DIR/scripts/pf_deep.py" postprocess-pass2 "<formal_note_path>" --figures <N>
+```
+
+- 输出 `OK` → 继续 Step 5
+- 输出错误列表（含行号）→ 按提示修正，修正后重新跑
+- 最多 3 轮修正。3 轮后仍失败 → 报告剩余错误给用户
+
+---
+
+### Step 5: Pass 3 — 深度理解
+
+填 `### Pass 3: 深度理解`。基于 Pass 1/2 已写内容。
+
+- **假设挑战与隐藏缺陷**：隐含假设；放宽假设后结论还成立吗；缺少的关键引用；实验/分析技术潜在问题
+- **哪些结论扎实，哪些仍存疑**：
+  - 较扎实：...
+  - 仍存疑：...（用 `> [!warning]`）
+- **Discussion 与 Conclusion 怎么读**：作者实际完成了什么；哪些有拔高；哪些是推测
+- **对我的启发**：研究设计、figure 组织、方法组合、未来工作
+- **遗留问题**：...（用 `> [!question]`）
+
+---
+
+### Step 6: Final Validation
+
+```bash
+$PYTHON "$SKILL_DIR/scripts/pf_deep.py" validate-note "<formal_note_path>" --fulltext "<fulltext_path>"
+```
+
+- 输出 `OK` → 告知用户精读完成
+- 输出错误 → 修正缺失项，直到通过
+
+**如果 validate 反复失败（超过 3 轮）→ 先自查：**
+1. 检查 note 结构：`## 🔍 精读` 骨架是否完整？是否被多次 `prepare` 破坏？
+2. 检查 `Pass 2` 中每个 figure 的子标题是否完整（6 个子标题全部存在？）
+3. 检查 Pass 1 和 Pass 2 之间是否有内容错位
+4. 检查 `--figures N` 是否和 paper 实际图片数一致（读 fulltext caption 核实）
+5. 以上都确认无误还失败 → 报告全部错误给用户，不要继续重试
+
+### Post-action: 保存/归档
+
+如果用户要求保存精读成果到项目知识库，跳转至 `capture-project-knowledge.md`。
+
+---
+
+## Callout 格式规则
+
+- `> [!important]` — 每个 main finding
+- `> [!warning]` — 疑问、局限、证据边界、仍存疑条目
+- `> [!question]` — 遗留问题
+- **相邻 callout 之间必须有空行**（否则 Obsidian 合并）：
+  - 正确：`> [!important] A\n\n> [!important] B`
+  - 错误：`> [!important] A\n> [!important] B`
diff --git a/paperforge/skills/paperforge/molecules/read-known-paper.md b/paperforge/skills/paperforge/molecules/read-known-paper.md
index 0766ca57..bb3ac427 100644
--- a/paperforge/skills/paperforge/molecules/read-known-paper.md
+++ b/paperforge/skills/paperforge/molecules/read-known-paper.md
@@ -1,3 +1,114 @@
 # read-known-paper
 
-Locate and interactively read a single known paper.
+> [!warning] Safety Rules
+> - 不要捏造论文未提及的内容
+> - 不要把推断写成论文事实——严格区分"文献说了什么"和"我推断什么"
+> - 引用原文时标注来源页码/章节
+> - 论文未提及的内容明确说明"论文中未提及"
+
+交互式文献问答。不强制要求 OCR，但 OCR 完成后回答更准确。
+
+---
+
+## 前置条件
+
+- bootstrap 已完成（有 `$VAULT`、`$PYTHON`）
+
+---
+
+## 步骤
+
+### Step 1: 定位论文
+
+用户可能给 zotero_key、DOI、标题片段、作者+年份。按以下方式查找：
+
+**如果用户给的是 zotero_key：**
+
+```bash
+$PYTHON -m paperforge --vault "$VAULT" paper-context <zotero_key> --json
+```
+
+返回 JSON 包含 paper 元数据、OCR 状态、prior_notes 等。
+
+**如果用户给的是 DOI、标题片段、作者+年份，先解析成候选：**
+
+```bash
+$PYTHON -m paperforge --vault "$VAULT" paper-status "<query>" --json
+```
+
+如果 `paper-status` 直接唯一命中，取返回的 `zotero_key` 再调 `paper-context`。
+
+**paper-status 无法唯一定位时的备选：**
+
+```bash
+$PYTHON -m paperforge --vault "$VAULT" search "<query>" --json --limit 5
+```
+
+如果多候选，列出让用户选；用户选定后，再用选中的 `zotero_key` 调 `paper-context`。
+如果无结果，告知用户并停止。
+
+### Step 2: 加载文献内容
+
+1. 从 paper-context 或 formal note frontmatter 获取：标题、作者、期刊、年份、domain
+2. 读 `fulltext.md`（如果 OCR done）作为主要回答依据
+3. 如果 fulltext 不存在："OCR 文本不可用，回答将基于元数据和公开信息"
+
+### Step 3: 展示论文信息 + 进入 Q&A
+
+```
+已加载: <title> (<year>, <journal>)
+作者: <authors> | Key: <zotero_key> | 领域: <domain>
+OCR: done / 不可用
+结束对话时说"保存"即可保存讨论。
+请问有什么问题？
+```
+
+### Step 4: Q&A 循环
+
+- 等待用户提问
+- 每次回答后等待下一个问题
+- 持续到用户说"保存"、"结束"、"完成"
+
+**回答原则：**
+- 严格基于 fulltext.md 中的文本内容
+- 引用原文时标注来源页码/章节
+- 论文未提及的内容明确说明"论文中未提及"
+- 区分"文献说了什么"和"我推断什么"
+
+### Step 5: 保存讨论
+
+用户说"保存"、"结束"、"完成"时执行。
+
+**收集 Q&A 对**，序列化为 JSON 数组：
+
+```json
+[
+  {
+    "question": "用户的问题",
+    "answer": "Agent 的回答",
+    "source": "user_question",
+    "timestamp": "2026-05-14T12:00:00+08:00"
+  }
+]
+```
+
+`source`: `"user_question"`（用户提问）或 `"agent_analysis"`（Agent 主动分析）。
+
+**调 discussion 模块：**
+
+```bash
+$PYTHON -m paperforge.worker.discussion record <zotero_key> \
+    --vault "$VAULT" \
+    --agent pf-paper \
+    --model "<current_model>" \
+    --qa-pairs '<JSON_ARRAY>'
+```
+
+- 返回 `ok` → 告知用户已保存
+- 返回 `error` → 重试一次，仍失败则告知用户
+
+> [!important] 不要自动保存。仅用户明确要求时执行。
+
+### Post-action: 保存/归档
+
+如果用户要求保存讨论内容到项目知识库，跳转至 `capture-project-knowledge.md`。