From f533b6e6e363cb29a1c1f2157cacf777d7e2a610 Mon Sep 17 00:00:00 2001
From: Research Assistant <research@example.com>
Date: Tue, 19 May 2026 14:51:07 +0800
Subject: [PATCH] refactor(skill): split discovery and evidence molecules

---
 .../paperforge/molecules/discover-papers.md   | 107 +++++++++++++++++-
 .../molecules/find-supporting-evidence.md     |  93 ++++++++++++++-
 2 files changed, 198 insertions(+), 2 deletions(-)

diff --git a/paperforge/skills/paperforge/molecules/discover-papers.md b/paperforge/skills/paperforge/molecules/discover-papers.md
index f9e2da88..520586f2 100644
--- a/paperforge/skills/paperforge/molecules/discover-papers.md
+++ b/paperforge/skills/paperforge/molecules/discover-papers.md
@@ -1,3 +1,108 @@
 # discover-papers
 
-Search for and discover new papers relevant to the project.
+从文献库中发现和检索论文，返回候选清单（candidate list）。
+
+---
+
+## 前置条件
+
+- bootstrap 已完成（有 `$VAULT`、`$PYTHON`、`$LIT_DIR`）
+
+---
+
+## 步骤
+
+### Step 1: 解析用户搜索意图
+
+提取以下信息（缺什么就问用户）：
+- **搜索词**：关键词、作者名、年份
+- **范围**：domain（如"骨科"）、不指定=全库
+- **过滤条件**：OCR 状态、年份范围（`--year-from`/`--year-to`）、lifecycle
+
+### Step 2: 执行元数据搜索（`paperforge search`）
+
+```bash
+$PYTHON -m paperforge --vault "$VAULT" search <query> --json --limit 15 \
+    [--domain "<domain>"] \
+    [--year-from <N>] [--year-to <N>] \
+    [--ocr <done|pending|failed|processing>] \
+    [--lifecycle <indexed|pdf_ready|fulltext_ready|deep_read_done>]
+```
+
+返回 JSON 结构（候选论文清单）：
+```json
+{
+  "ok": true,
+  "data": {
+    "query": "<query>",
+    "matches": [
+      {
+        "zotero_key": "ABC12345",
+        "title": "论文标题",
+        "year": "2024",
+        "first_author": "Smith",
+        "domain": "骨科",
+        "ocr_status": "done",
+        "deep_reading_status": "pending",
+        "lifecycle": "pdf_ready",
+        "has_pdf": true
+      }
+    ],
+    "count": 5
+  }
+}
+```
+
+- 如果 `ok: false` → 报告 `error.message`，问用户是否换搜索词
+- 如果 `data.count == 0` → 告知用户无结果，建议换词或扩大范围
+- 如果 `data.count > 0` → 进入 Step 3
+
+### Step 3: Top-hit 富化（`paperforge paper-context`）
+
+对每个 match，调 `paper-context` 获取更详细的可读状态：
+
+```bash
+$PYTHON -m paperforge --vault "$VAULT" paper-context <zotero_key> --json
+```
+
+目的：拿到 `ocr_status`、`prior_notes` 数量、`analyze` 状态，帮助用户判断哪些可以直接读。
+
+### Step 4: 展示候选清单
+
+格式（每条一行）：
+
+```
+找到 N 篇匹配 "<query>"：
+
+[1] ABC12345 | Smith 2024 | 论文标题 | 骨科 | OCR: done | 精读: pending | 阅读笔记: 3
+[2] DEF67890 | Jones 2023 | 论文标题 | 骨科 | OCR: done | 精读: done   | 阅读笔记: 0
+[3] GHI11111 | Wang 2022  | 论文标题 | 骨科 | OCR: pending |           | 阅读笔记: 0
+```
+
+关键字段：`zotero_key`、`first_author`、`year`、`title`、`domain`、`ocr_status`、`deep_reading_status`
+
+### Step 5: 等用户选择后续操作
+
+展示候选后不要自己决定下一步。等用户说：
+- "读一下 [1]" → 路由到 `read-known-paper.md`
+- "精读 [2]" → 路由到 `deep-analyze-paper.md`
+- "换个关键词" / "refine" → 回到 Step 1
+- "不找了" → 结束
+
+---
+
+## 过渡路由
+
+| 用户动作 | 路由目标 |
+|---------|---------|
+| 用户选了一篇论文 | `read-known-paper.md` |
+| 用户想重新搜索、缩小范围 | 返回 Step 1（refine） |
+| 用户想精读（deep read） | `deep-analyze-paper.md` |
+
+---
+
+## 禁止
+
+- 不要在搜索结果中替用户决定读哪篇
+- 不要在搜索阶段读全文
+- 不要对 0 结果硬猜路径
diff --git a/paperforge/skills/paperforge/molecules/find-supporting-evidence.md b/paperforge/skills/paperforge/molecules/find-supporting-evidence.md
index b27ba204..9d750104 100644
--- a/paperforge/skills/paperforge/molecules/find-supporting-evidence.md
+++ b/paperforge/skills/paperforge/molecules/find-supporting-evidence.md
@@ -1,3 +1,94 @@
 # find-supporting-evidence
 
-Find evidence to support a specific claim or question.
+为特定论点或问题查找文献中的证据支持。
+
+---
+
+## 前置条件
+
+- bootstrap 已完成（有 `$VAULT`、`$PYTHON`、`$LIT_DIR`）
+- `atoms/retrieval-routing.md` 已就绪（提供检索梯级选择）
+
+---
+
+## 步骤
+
+### Step 1: 解析用户证据需求
+
+提取以下信息（缺什么就问用户）：
+- **论点/问题**：用户需要支持的具体主张或疑问
+- **范围限制**：是否限定特定 domain、作者、年份
+- **证据类型**：统计结果、方法引用、临床发现、机制解释等
+
+### Step 2: 检索梯级选择（`atoms/retrieval-routing.md`）
+
+根据运行时状态选择合适的梯级：
+
+1. **Ladder B**（优先）-- 用 `rg` 在全文中定位精确证据
+   - 先用 `paperforge search` 生成元数据候选集
+   - 用 `runtime-health` 或 `paper-context` 筛选有 OCR/全文的论文
+   - 在解析后的全文中运行 `rg` 定位匹配片段
+2. **Ladder C**（回退）-- 无 `rg` 时用 `grep`/`findstr`
+3. **Ladder D**（补充）-- 语义候选扩展（仅当 `semantic_enabled && semantic_ready`）
+4. **元数据降级** -- 当没有任何论文有 OCR/全文时，只出候选论文列表，不做片段验证
+
+### Step 3: 展示分组证据命中（grouped evidence hits with snippets）
+
+格式：
+
+```
+找到 N 条与 "<论点>" 相关的证据：
+
+=== Smith 2024 (zotero_key: ABC12345) ===
+[1] 第 5 页 · 方法部分
+    匹配片段："...we used a randomized controlled trial..."
+    上下文：在讨论实验设计时作者描述了...
+
+=== Jones 2023 (zotero_key: DEF67890) ===
+[2] 第 12 页 · 讨论部分
+    匹配片段："...our findings align with previous meta-analyses..."
+    上下文：作者比较本研究与已有综述的一致性...
+
+（共 N 条，来自 M 篇论文）
+```
+
+每项包含：
+- 论文标识（`zotero_key`、标题）
+- 章节或页码引用
+- 匹配片段
+- 简短上下文
+
+### Step 4: 等用户选择后续操作
+
+- "看 [1] 的详情" → 路由到 `read-known-paper.md`
+- "保存 [1]" / "记录这条证据" → 路由到 `capture-project-knowledge.md`
+- "换个关键词" → 回到 Step 1
+- "够了" → 结束
+
+---
+
+## 过渡路由
+
+| 用户动作 | 路由目标 |
+|---------|---------|
+| 用户想查看论文详情 | `read-known-paper.md` |
+| 用户想保存证据到项目知识 | `capture-project-knowledge.md` |
+| 用户想重新搜索 | 回到 Step 1 |
+
+---
+
+## 元数据降级
+
+当 `runtime-health` 显示没有任何论文有 OCR 或全文可用时：
+
+> 精确证据验证受限 -- 降级到元数据级支持
+
+仅输出候选论文列表（不含片段验证），告知用户当前无法做全文级证据检索。
+
+---
+
+## 禁止
+
+- 不要在没有 OCR/全文的情况下虚构引用位置或片段
+- 不要在没有 `rg`/`grep` 验证的情况下把语义检索结果当最终证据
+- 不要在用户未要求时自动保存证据