feat: restructure literature-qa v2 — SKILL.md as central hub with decision tree, add multi-reading, simplify refs

2026-07-22 06:50:53 +00:00 · 2026-05-11 23:58:46 +08:00 · 2026-05-11 23:58:46 +08:00 · f244f72056
commit f244f72056
parent a5c3026dc2
9 changed files with 642 additions and 182 deletions
--- a/docs/superpowers/plans/2026-05-11-literature-qa-v2-restructure.md
+++ b/docs/superpowers/plans/2026-05-11-literature-qa-v2-restructure.md
@ -0,0 +1,375 @@
+# Literature-QA Skill v2 Restructuring Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Restructure literature-qa skill so that SKILL.md is the single hub containing bootstrap, decision tree, and tool usage guidelines. Reference files become pure workflow instructions. Add multi-reading workflow. Remove unused routes.
+
+**Architecture:** SKILL.md = bootstrap + overview + decision tree + tool rules + routing table. Each reference file = one workflow (no path discovery, no Python discovery). All `$PYTHON`/`$VAULT` context inherited from SKILL.md.
+
+**Tech Stack:** Markdown, Python (pf_bootstrap.py, ld_deep.py)
+
+---
+
+## File Changes
+
+| File | Action | Responsibility |
+|------|--------|---------------|
+| `SKILL.md` | **Rewrite** | Bootstrap, vault overview, decision tree, tool guidelines, routing table |
+| `references/vault-knowledge.md` | **Delete** | Merged into SKILL.md |
+| `references/multi-reading.md` | **Create** | Batch reading workflow with reading log |
+| `references/paper-search.md` | **Simplify** | Remove `$PYTHON`/`$VAULT` preamble (inherited) |
+| `references/paper-qa.md` | **Simplify** | Remove `$PYTHON`/`$VAULT` preamble |
+| `references/deep-reading.md` | **Simplify** | Remove `$PYTHON`/`$VAULT` preamble; remove "精读队列" variant |
+| `references/save-session.md` | **Simplify** | Remove `$PYTHON`/`$VAULT` preamble |
+| `references/paper-resolution.md` | **Simplify** | Remove `$PYTHON`/`$VAULT` preamble, just the protocol |
+
+---
+
+## Task Breakdown
+
+### Task 1: Rewrite SKILL.md
+
+**Files:**
+- Rewrite: `paperforge/skills/literature-qa/SKILL.md`
+
+**New structure:**
+
+```markdown
+---
+name: literature-qa
+description: >
+  学术文献库操作。Triggered by: /pf-deep /pf-paper /pf-end,
+  "精读", "文献问答", "结束讨论", "找文献", "搜文献",
+  "文献库", "文献检索", "精读队列", "库里有什么",
+  "搜一下库里", "看一下文献库".
+---
+
+# Literature QA
+
+---
+
+## 1. Bootstrap — 进入本 Skill 后必须先执行
+
+跑这个脚本，拿到所有你需要的信息：
+
+```
+python <skill_dir>/scripts/pf_bootstrap.py
+```
+
+返回 JSON 记住以下变量：
+
+| 变量       | 来源                  | 示例值                                                    |
+| ---------- | --------------------- | --------------------------------------------------------- |
+| `$VAULT`     | `vault_root`            | `D:\L\OB\Literature-hub`                                    |
+| `$PYTHON`    | `python_candidate`      | `D:\L\OB\Literature-hub\.venv\Scripts\python.exe`           |
+| `$LIT_DIR`   | `paths.literature_dir`  | `D:\L\OB\Literature-hub\Resources\Literature`               |
+| `$IDX_PATH`  | `paths.index_path`      | `D:\L\OB\Literature-hub\System\PaperForge\indexes\formal-library.json` |
+| `$OCR_DIR`   | `paths.ocr_dir`         | `D:\L\OB\Literature-hub\System\PaperForge\ocr`              |
+| `$DOMAINS`   | `domains`               | `["骨科", "运动医学"]`                                      |
+| `$SUMMARY`   | `index_summary`         | `{"骨科": 550, "运动医学": 263}`                             |
+
+如果 `ok: false`，报告 `error` 给用户，**停止。不要自己猜任何路径。**
+
+---
+
+## 2. Vault 概览 — 直接展示
+
+```
+当前 Vault: $VAULT
+文献库概况:
+  骨科 — 550 篇
+  运动医学 — 263 篇
+共 813 篇
+```
+
+---
+
+## 3. 决策树 — Agent 如何判断用户要干什么
+
+```
+用户输入
+  │
+  ├─ "看一下库"/"浏览文献"/"库里有什么"
+  │   └─ 上面已经展示了。等用户下一步。
+  │
+  ├─ 给出文献标识 (key/DOI/标题/作者年份) + 想精读
+  │   └─ 路由 → deep-reading.md
+  │
+  ├─ 给出文献标识 (key/DOI/标题/作者年份) + 想问答/讨论
+  │   └─ 路由 → paper-qa.md
+  │
+  ├─ 搜索文献 ("找文献"/"搜文献"/"库里有没有XXX"/"文献检索")
+  │   └─ 路由 → paper-search.md
+  │
+  ├─ 批量阅读/综述整理
+  │   触发词: "读一下这个collection", "帮我看一下这方向的文章",
+  │           "总结一下库里关于XXX的文献", "写一段文献综述",
+  │           用户给了多篇文献要求一起读
+  │   └─ 路由 → multi-reading.md
+  │
+  ├─ "结束"/"保存"/"/pf-end"
+  │   └─ 路由 → save-session.md
+  │       (仅 paper-qa 或 deep-reading 会话中有效)
+  │
+  └─ 不确定 → 问用户："你是想精读一篇、搜索文献、还是批量阅读？"
+```
+
+---
+
+## 4. 工具使用指南
+
+**什么时候用命令（paper_resolver / ld_deep 等）：**
+
+| 场景                  | 命令                                                         | 原因                        |
+| --------------------- | ------------------------------------------------------------ | --------------------------- |
+| 定位论文（按 key）    | `$PYTHON -m paperforge.worker.paper_resolver resolve-key <KEY> --vault "$VAULT"` | 确定性匹配，返回 workspace 路径 |
+| 定位论文（按 DOI）    | `$PYTHON -m paperforge.worker.paper_resolver resolve-doi "<DOI>" --vault "$VAULT"` | 同上                        |
+| 搜索论文（结构化）    | `$PYTHON -m paperforge.worker.paper_resolver search --title "..." --domain "..." --vault "$VAULT"` | 返回结构化 JSON，含相关性打分 |
+| 精读 prepare/校验     | `$PYTHON "$SKILL_DIR/scripts/ld_deep.py" prepare --key <KEY> --vault "$VAULT"` | 机械操作，Agent 不做         |
+| 保存讨论              | `$PYTHON -m paperforge.worker.discussion record <KEY> --vault "$VAULT" --agent pf-paper --model "<MODEL>" --qa-pairs '...'` | 写入 discussion.md/json      |
+
+**什么时候自己 grep/glob/read：**
+
+| 场景                    | 操作                                                    | 原因                       |
+| ----------------------- | ------------------------------------------------------- | -------------------------- |
+| 按关键词在全部文献里搜 | `grep <关键词> $IDX_PATH` 或读 JSON 筛 `title`/`abstract` | 模糊搜索，paper_resolver 不够 |
+| 读论文全文/精读笔记    | 直接 read `$LIT_DIR/<domain>/<key> - <title>/fulltext.md` | 收到 resolve-key 返回的路径后直接读 |
+| 按 collection 筛选       | 读 `$IDX_PATH`，筛 `collection_path` 字段                 | paper_resolver 不支持 collection |
+| 遍历所有笔记做统计      | `rg <pattern> $LIT_DIR/ --include '*.md'`               | 批量操作                   |
+
+---
+
+## 5. 路由表
+
+| 路由         | 触发词                                     | 加载文件                                 |
+| ------------ | ------------------------------------------ | ---------------------------------------- |
+| 精读         | `/pf-deep <key>`, "精读 <key>"              | [deep-reading.md](references/deep-reading.md) |
+| 问答         | `/pf-paper <key>`, "文献问答 <key>"         | [paper-qa.md](references/paper-qa.md)       |
+| 文献检索     | "找文献", "搜文献", "文献检索", "搜一下库里"  | [paper-search.md](references/paper-search.md) |
+| 批量阅读     | "读一下collection", "这篇方向", "总结文献"   | [multi-reading.md](references/multi-reading.md) |
+| 保存记录     | `/pf-end`, "结束讨论", "保存"               | [save-session.md](references/save-session.md) |
+| 论文定位协议 | 共享                                       | [paper-resolution.md](references/paper-resolution.md) |
+
+---
+
+## 文件结构
+
+```
+literature-qa/
+├── SKILL.md
+├── references/
+│   ├── deep-reading.md
+│   ├── paper-qa.md
+│   ├── paper-search.md
+│   ├── multi-reading.md       ← NEW
+│   ├── save-session.md
+│   ├── paper-resolution.md
+│   └── chart-reading/
+└── scripts/
+    ├── pf_bootstrap.py
+    └── ld_deep.py
+```
+```
+
+- [ ] **Step 1: Write the new SKILL.md**
+- [ ] **Step 2: Run a syntax check (it's markdown, read it back for typos)**
+- [ ] **Step 3: Commit**
+
+```bash
+git add paperforge/skills/literature-qa/SKILL.md
+git commit -m "feat: restructure SKILL.md as central hub with decision tree and tool guidelines"
+```
+
+---
+
+### Task 2: Delete vault-knowledge.md
+
+**Files:**
+- Delete: `paperforge/skills/literature-qa/references/vault-knowledge.md`
+
+Content merged into SKILL.md sections 1+2+3+4.
+
+- [ ] **Step 1: Delete the file**
+- [ ] **Step 2: Commit**
+
+```bash
+git rm paperforge/skills/literature-qa/references/vault-knowledge.md
+git commit -m "refactor: remove vault-knowledge.md (merged into SKILL.md)"
+```
+
+---
+
+### Task 3: Create multi-reading.md
+
+**Files:**
+- Create: `paperforge/skills/literature-qa/references/multi-reading.md`
+
+**Content:**
+
+```markdown
+# 批量文献阅读
+
+用户需要阅读多篇文献并总结——综述写作、找引用、研究方向调研等。
+
+---
+
+## 触发条件
+
+- 用户给了一个 collection 名（Zotero 收藏夹）
+- 用户给了模糊方向（"帮我看一下骨科里关于支架材料的文章"）
+- 用户给了一个多篇文献阅读任务（"读一下这几篇写一段综述"）
+- 用户说"总结库里XXX方向的文献"
+
+---
+
+## 执行流程
+
+### Step 1: 确定文献范围
+
+先和用户确认要读哪些文献：
+- 如果用户给了 collection 名 → 读 `$IDX_PATH`，筛 `collection_path` 包含该名称的条目
+- 如果用户给了关键词 → 用 paper_resolver search 或直接 grep `$IDX_PATH`
+- 如果用户给了多篇 key → 直接确认 key 列表
+
+列出候选文献清单让用户确认：
+
+```
+找到 N 篇匹配：collection = "自发电"
+
+[1] ABC12345 — Piezoelectric Scaffolds for Cartilage (2024)
+[2] DEF67890 — Triboelectric Nanogenerators (2023)
+...
+
+要全部读，还是选几篇？(输入编号如 "1,3,5" 或 "all")
+```
+
+### Step 2: 逐篇阅读
+
+对每篇选定的文献：
+1. 运行 `$PYTHON -m paperforge.worker.paper_resolver resolve-key <KEY> --vault "$VAULT"` 获取 workspace 路径
+2. 读 formal note 的 frontmatter 了解元数据
+3. 如果有 fulltext.md → 读关键段落（Abstract、Results、Discussion）
+4. 如果没有 fulltext → 只能基于已知信息
+
+### Step 3: 生成 Reading Log
+
+每篇读完后立即在 `$VAULT/Bases/` 下生成 `reading-log-<timestamp>.md` 文件（追加模式，不要覆盖之前的记录）：
+
+```markdown
+# Reading Log — <timestamp>
+
+## [KEY] <title> (作者, 年份, 期刊)
+
+- **核心发现**: <一句话>
+- **方法**: <实验设计简述>
+- **关键数据**: <主要结果>
+- **与主题相关性**: <为什么对当前任务有用>
+- **引用值**: <适合引什么→什么结论>
+```
+
+### Step 4: 整合输出
+
+全部读完，根据用户原始意图输出：
+
+**如果是综述写作**：
+```
+从 N 篇文献中总结：
+- 主题A 的共识: ...
+- 主题A 的争议: ...
+- 方法论趋势: ...
+- 可引用的关键结论及其文献来源:
+  1. "...[结论]" — [KEY] (作者, 年份)
+  2. ...
+```
+
+**如果是找引用**：
+```
+以下文献适合引用：
+- 支撑"XXX"观点 → [KEY] (作者, 年份), Fig.3
+- 支撑"YYY"方法 → [KEY] (作者, 年份), Methods section
+```
+
+### Step 5: 问用户
+
+问用户：
+- "Reading log 已保存到 `Bases/reading-log-<ts>.md`。需要我把总结写到哪里？"
+- 用户可以指定目标文件路径
+
+---
+
+## 注意事项
+
+- Reading log **追加**写入同一个文件（同一次多篇阅读任务），不要每篇新建一个
+- 暂时不支持多篇阅读后运行 /pf-end
+- 如果某篇文献没有 fulltext，如实告知用户
+```
+
+- [ ] **Step 1: Write the file**
+- [ ] **Step 2: Commit**
+
+```bash
+git add paperforge/skills/literature-qa/references/multi-reading.md
+git commit -m "feat: add multi-reading workflow with reading log"
+```
+
+---
+
+### Task 4: Simplify reference files (remove $PYTHON/$VAULT preamble)
+
+**Files:**
+- Modify: `references/deep-reading.md` — remove preamble, remove "精读队列" variant
+- Modify: `references/paper-qa.md` — remove preamble
+- Modify: `references/paper-search.md` — remove preamble
+- Modify: `references/save-session.md` — remove preamble
+- Modify: `references/paper-resolution.md` — remove preamble
+
+Each file's preamble like:
+```markdown
+**所有 Python 命令用 `$PYTHON`（来自 pf_bootstrap 的 `python_candidate`），vault 路径用 `$VAULT`。**
+```
+→ **Delete**. The variables are now inherited from SKILL.md.
+
+- [ ] **Step 1: Strip preamble from all 5 files**
+- [ ] **Step 2: In deep-reading.md, remove the "精读队列" variant (line references to `/pf-deep` without args)**
+- [ ] **Step 3: Commit**
+
+```bash
+git add paperforge/skills/literature-qa/references/
+git commit -m "refactor: simplify reference files — remove $PYTHON/$VAULT preamble (inherited), drop unused route"
+```
+
+---
+
+### Task 5: Integration Check
+
+- [ ] **Step 1: Read all files end-to-end, verify no broken references**
+- [ ] **Step 2: Verify SKILL.md routing table links are all valid**
+- [ ] **Step 3: Run bootstrap script to verify it still works**
+
+```bash
+python paperforge/skills/literature-qa/scripts/pf_bootstrap.py --vault "D:\L\OB\Literature-hub"
+```
+
+Expected: `"ok": true` with domains and index summary.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git commit -m "chore: integration check — all routes verified"
+```
+
+---
+
+## Rollback Plan
+
+1. Restore `vault-knowledge.md` from git history
+2. Revert `SKILL.md` to pre-restructure version
+3. Revert reference file preambles
+
+## Risk Assessment
+
+| Risk | Level | Mitigation |
+|------|-------|-----------|
+| Agent confused by missing vault-knowledge.md | Low | All info now in SKILL.md sections 1-4 |
+| multi-reading generates too large reading logs | Low | Append mode; user asked before saving final output |
+| "精读队列" still in ld_deep.py code | Low | Skill just removes the routing trigger; code stays |
--- a/paperforge/skills/literature-qa/SKILL.md
+++ b/paperforge/skills/literature-qa/SKILL.md
@ -1,84 +1,156 @@
 ---
 name: literature-qa
 description: >
-  学术文献库操作：精读、问答、检索、浏览。Triggered by:
-  /pf-deep /pf-paper /pf-end,
-  "精读", "文献问答", "结束讨论", "保存记录",
-  "找文献", "搜文献", "文献库", "文献检索", "精读队列", "库里有什么",
-  "搜一下库里", "看一下文献库", "浏览文献库".
-  Uses Zotero key, DOI, title, or domain keywords to locate papers.
-license: Apache-2.0
-compatibility: all
+  学术文献库操作：精读、问答、检索、批量阅读。Triggered by:
+  pf-deep pf-paper pf-end,
+  "精读", "文献问答", "结束讨论", "找文献", "搜文献",
+  "文献库", "文献检索", "库里有什么", "搜一下库里", "看一下文献库",
+  "读一下collection", "总结文献", "批量阅读", "读一下这个方向".
 ---

-# Literature QA — 学术文献精读、问答与检索
+# Literature QA

 ---

-## MANDATORY FIRST STEP — 必须先执行，不可跳过
+## 1. Bootstrap — 必须先执行

-**只做一个操作：跑这个脚本。**
+跑这个脚本：

 ```
-python scripts/pf_bootstrap.py
+python <skill_dir>/scripts/pf_bootstrap.py
 ```

-（如果当前目录没有 `pf_bootstrap.py`，用完整路径：`python <skill_dir>/scripts/pf_bootstrap.py --vault .` 或让用户告诉你 vault 在哪。）
+返回 JSON。记住以下变量：

-脚本返回一个 JSON，里面有所有你需要的信息：
- `paths` — 文献目录、索引文件、OCR 目录的完整路径
- `domains` — 有哪些领域
- `index_summary` — 每个领域多少篇论文
- `python_candidate` — 装了 paperforge 的 Python 路径
+| 变量        | 来自 JSON 的         | 用于                                    |
+| ----------- | -------------------- | --------------------------------------- |
+| `$VAULT`      | `vault_root`           | 所有 `--vault` 参数                       |
+| `$PYTHON`     | `python_candidate`     | 所有 Python 命令                         |
+| `$LIT_DIR`    | `paths.literature_dir` | 文献笔记根目录                          |
+| `$IDX_PATH`   | `paths.index_path`     | 索引文件                                |
+| `$OCR_DIR`    | `paths.ocr_dir`        | OCR 目录                                |
+| `$DOMAINS`    | `domains`              | 领域列表                                |
+| `$SUMMARY`    | `index_summary`        | 每领域论文数                            |

-**如果 `ok: false`，报告 `error` 给用户，停止。不要自己猜路径。**
-
-**如果 `ok: true`，记住 `paths` 里的所有值。后面所有文件读写用这些路径，一个都不许自己拼。**
-
-加载 [references/vault-knowledge.md](references/vault-knowledge.md) 了解 Vault 结构，然后进入下面的路由表。
+如果 `ok: false` → 报告 `error` 给用户，**停止。不许自己拼路径。**

 ---

-## 路由表
+## 2. Vault 概览

-加载本 Skill 后，根据用户的 **具体意图** 选择一条路由，加载对应的 reference 文件：
+展示：

-| 用户意图 | 典型输入 | 加载文件 | 说明 |
-|---------|---------|---------|------|
-| 了解库概况 | "看一下库里有什么", "库里内容" | [vault-knowledge.md](references/vault-knowledge.md) | 展示 domain 分布和统计 |
-| 文献检索 | "找文献", "搜文献", "库里有没有XX", "文献检索", "搜一下库里" | [paper-search.md](references/paper-search.md) | 在库里搜索论文 |
-| 精读 | `/pf-deep <key>`, "精读 <key>" | [deep-reading.md](references/deep-reading.md) | Keshav 三阶段精读 |
-| 精读队列 | `/pf-deep` 无参数, "精读队列" | [deep-reading.md](references/deep-reading.md) | 查看待精读列表 |
-| 论文问答 | `/pf-paper <key>`, "文献问答 <key>" | [paper-qa.md](references/paper-qa.md) | 交互式 Q&A |
-| 保存记录 | `/pf-end`, "结束讨论", "保存记录" | [save-session.md](references/save-session.md) | 存档问答记录 |
+```
+Vault: $VAULT
+文献库:
+  <domain1> — N1 篇
+  <domain2> — N2 篇
+共 M 篇
+```

-> **重要：** 加载 reference 文件后，**严格按照该文件的流程执行，不要跳过任何步骤。** 如果你不知道下一步干什么，回顾 reference 文件的流程，不要自己发明步骤。
+**如果用户是空输入触发的 skill**（没给任何具体指令），展示概览后加一句交互：

-## 论文定位
+```
+你可以：
+  [1] 精读一篇论文   → "精读 <key/标题>"
+  [2] 文献问答       → "文献问答 <key/标题>"
+  [3] 搜索文献       → "找文献 <关键词>" / "库里有没有 <关键词>"
+  [4] 批量阅读       → "读一下 <collection名>" / "总结 <方向> 文献"
+  [5] 返回
+```

-所有路由共享的论文定位协议：见 [references/paper-resolution.md](references/paper-resolution.md)。
+**如果用户给了具体指令**，直接进入决策树。

-**核心原则：路径从 `paths` 获取，不硬编码。Python 从 Step B 找到的 `$PYTHON` 用，不用系统的 `python`。**
+---

-| 获取 vault 路径 | 已由 `pf_bootstrap.py` 完成 |
-| 定位论文（按 key） | `$PYTHON -m paperforge.worker.paper_resolver resolve-key <KEY> --vault "$VAULT"` |
-| 定位论文（按 DOI） | `$PYTHON -m paperforge.worker.paper_resolver resolve-doi "<DOI>" --vault "$VAULT"` |
-| 搜索论文       | `$PYTHON -m paperforge.worker.paper_resolver search --title "..." --domain "..." --vault "$VAULT"` |
+## 3. 决策树
+
+```
+用户输入
+  │
+  ├─ 文献标识 (key/DOI/标题/作者年份) + 精读意图
+  │   └─ 路由 → deep-reading.md
+  │
+  ├─ 文献标识 (key/DOI/标题/作者年份) + 问答/讨论意图
+  │   └─ 路由 → paper-qa.md
+  │
+  ├─ 搜索意图 ("找文献"/"搜文献"/"库里有没有"/"文献检索")
+  │   └─ 路由 → paper-search.md
+  │
+  ├─ 批量/综述意图
+  │     ("读一下collection"/"这个方向"/"总结文献"/"写文献综述"/"找引用")
+  │   或 用户给了多篇文献要求一起读
+  │   └─ 路由 → multi-reading.md
+  │
+  ├─ 结束/保存 ("结束讨论"/"保存"/"pf-end")
+  │   └─ 路由 → save-session.md
+  │     （仅 paper-qa 或 deep-reading 会话中有意义）
+  │
+  └─ 不确定 → 问用户
+      "你是想精读一篇、问答一篇、搜索文献、还是批量阅读？"
+```
+
+---
+
+## 4. 工具使用指南
+
+本 Skill 提供两类工具：**确定性命令** 和 **Agent 自查**。必须根据场景选择正确的方式。
+
+### 确定性命令 — 优先使用
+
+| 场景                   | 命令                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------ |
+| 按 key 定位论文        | `$PYTHON -m paperforge.worker.paper_resolver resolve-key <KEY> --vault "$VAULT"`             |
+| 按 DOI 定位论文        | `$PYTHON -m paperforge.worker.paper_resolver resolve-doi "<DOI>" --vault "$VAULT"`           |
+| 按字段搜索论文         | `$PYTHON -m paperforge.worker.paper_resolver search --title "..." --author "..." --year ... --domain "..." --vault "$VAULT"` |
+| 精读 prepare           | `$PYTHON "$SKILL_DIR/scripts/ld_deep.py" prepare --key <KEY> --vault "$VAULT"`               |
+| 精读 postprocess       | `$PYTHON "$SKILL_DIR/scripts/ld_deep.py" postprocess-pass2 <FORMAL_NOTE_PATH> --figures <N> --vault "$VAULT"` |
+| 精读 validate          | `$PYTHON "$SKILL_DIR/scripts/ld_deep.py" validate-note <FORMAL_NOTE_PATH> --fulltext <FULLTEXT_PATH>` |
+| 保存讨论               | `$PYTHON -m paperforge.worker.discussion record <KEY> --vault "$VAULT" --agent pf-paper --model "<MODEL>" --qa-pairs '<JSON>'` |
+
+### Agent 自查 — 当命令覆盖不到时用
+
+| 场景                     | 操作                                                        |
+| ------------------------ | ----------------------------------------------------------- |
+| 按关键词模糊搜索全部文献 | 读 `$IDX_PATH` 的 JSON，筛 `title` / `abstract` / `journal`   |
+| 按 collection 筛选       | 读 `$IDX_PATH`，筛 `collection_path` 字段                     |
+| 读论文全文               | 已通过 resolve-key 拿到 `fulltext_path` → 直接 read           |
+| 读精读笔记               | 已拿到 `formal_note_path` → read 的 `## 🔍 精读` 区域          |
+| 遍历笔记做批量统计       | `rg <pattern> $LIT_DIR/ --include '*.md'`                   |
+| **禁止的操作**           | **根据 vault-knowledge 示例拼接路径、把目录名写死在文件路径里** |
+
+---
+
+## 5. 路由表
+
+| 路由          | 触发词                                                     | 加载文件                                 |
+| ------------- | ---------------------------------------------------------- | ---------------------------------------- |
+| 精读          | `pf-deep <key>`, "精读 <key>"                               | [deep-reading.md](references/deep-reading.md) |
+| 问答          | `pf-paper <key>`, "文献问答 <key>"                          | [paper-qa.md](references/paper-qa.md)       |
+| 文献检索      | "找文献", "搜文献", "文献检索", "搜一下库里", "库里有没有"   | [paper-search.md](references/paper-search.md) |
+| 批量阅读      | "读一下collection", "这个方向", "总结文献", "批量阅读"       | [multi-reading.md](references/multi-reading.md) |
+| 保存记录      | `pf-end`, "结束讨论", "保存"                                | [save-session.md](references/save-session.md) |
+| 论文定位协议  | 所有路由共享                                               | [paper-resolution.md](references/paper-resolution.md) |
+
+> 所有路由继承 Skill 级别的 `$PYTHON` / `$VAULT` / `$LIT_DIR` 等变量。reference 文件不再重复声明。
+
+---

 ## 文件结构

 ```
 literature-qa/
-├── SKILL.md                       ← 本文件（路由入口）
+├── SKILL.md                         ← 本文件
 ├── references/
-│   ├── vault-knowledge.md         ← Vault 结构共享知识
-│   ├── paper-resolution.md        ← 论文定位详细协议
-│   ├── paper-search.md            ← 文献检索工作流
-│   ├── deep-reading.md            ← 精读工作流
-│   ├── paper-qa.md                ← 问答工作流
-│   ├── save-session.md            ← 保存记录工作流
-│   ├── deep-subagent.md           ← 子代理提示词模板
-│   └── chart-reading/             ← 19 个图表类型阅读指南
+│   ├── deep-reading.md              ← 精读工作流
+│   ├── paper-qa.md                  ← 问答工作流
+│   ├── paper-search.md              ← 文献检索工作流
+│   ├── multi-reading.md             ← 批量阅读工作流
+│   ├── save-session.md              ← 保存记录工作流
+│   ├── paper-resolution.md          ← 论文定位协议
+│   ├── deep-subagent.md
+│   └── chart-reading/
 └── scripts/
-    └── ld_deep.py                 ← 精读引擎（Python）
+    ├── pf_bootstrap.py              ← Bootstrap 入口
+    └── ld_deep.py                   ← 精读引擎
 ```
--- a/paperforge/skills/literature-qa/references/deep-reading.md
+++ b/paperforge/skills/literature-qa/references/deep-reading.md
@ -2,8 +2,6 @@

 Keshav 三阶段组会式精读。触发后执行以下工作流。

-**所有 Python 命令用 `$PYTHON`（来自 pf_bootstrap 的 `python_candidate`），vault 路径用 `$VAULT`（来自 pf_bootstrap 的 `vault_root`）。**
-
 ---

 ## 前置条件检查
--- a/paperforge/skills/literature-qa/references/multi-reading.md
+++ b/paperforge/skills/literature-qa/references/multi-reading.md
@ -0,0 +1,144 @@
+# 批量文献阅读
+
+用户需要阅读多篇文献并总结——综述写作、找引用、研究方向调研等。
+
+---
+
+## 触发条件
+
+- 用户给了一个 collection 名（Zotero 收藏夹）
+- 用户给了模糊方向（"帮我看一下骨科里关于支架材料的文章"）
+- 用户给了多篇文献要求一起读
+- 用户说"总结库里XXX方向的文献"、"写一段文献综述"
+
+---
+
+## 执行流程
+
+### Step 1: 确定文献范围
+
+和用户确认要读哪些文献：
+- 用户给了 collection 名 → 读 `$IDX_PATH`，筛 `collection_path` 包含该名称的条目
+- 用户给了关键词方向 → 用 paper_resolver search 或直接 grep `$IDX_PATH`
+- 用户给了多篇 key → 直接确认 key 列表
+
+列出候选让用户确认：
+
+```
+找到 N 篇匹配 (<collection名/关键词>):
+
+[1] ABC12345 — Title (Author, Year, Domain, OCR: done/pending)
+[2] DEF67890 — Title (Author, Year, Domain, OCR: done/pending)
+...
+
+要全部读，还是选几篇？(输入编号如 "1,3,5" 或 "all")
+```
+
+### Step 2: 逐篇阅读
+
+对每篇选定文献：
+
+1. `$PYTHON -m paperforge.worker.paper_resolver resolve-key <KEY> --vault "$VAULT"` → 获取 workspace 路径
+2. 读 formal note frontmatter → 元数据
+3. 如果有 `fulltext.md` → 读 Abstract、Results、Discussion
+4. 如果有 `ocr_status == "done"` 但 fulltext 内容太长 → 先读 caption + figure 描述定位关键段落
+5. 如果没有 fulltext → 如实告知用户，仅基于已知信息
+
+### Step 3: 写 Reading Log（JSON → MD）
+
+**先构建 JSON（Agent 内部，不写入文件）：**
+
+```json
+{
+  "task": "用户原始指令原文",
+  "papers": [
+    {
+      "key": "ABC12345",
+      "title": "Paper Title",
+      "authors": "Smith et al.",
+      "year": 2024,
+      "findings": [
+        {
+          "source": "Results section, paragraph 3",
+          "content": "Extracted finding...",
+          "citation_use": "可用于支撑 XXX 观点"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**再渲染为 MD，追加写入 `$VAULT/Bases/reading-log-<timestamp>.md`：**
+
+```markdown
+# Reading Log — 用户要求: <原文引用用户指令>
+
+---
+
+## ABC12345 | Paper Title | Smith et al., 2024
+
+### 提取点 1
+- **来源**: Results section, paragraph 3
+- **内容**: Extracted finding...
+- **引用建议**: 可用于支撑 XXX 观点
+
+### 提取点 2
+- **来源**: Discussion, final paragraph
+- **内容**: ...
+- **引用建议**: ...
+
+---
+
+## DEF67890 | Another Title | Jones et al., 2023
+
+（同上格式）
+
+---
+```
+
+**关键规则：**
+- JSON 确保格式稳定，MD 是最终交付产物
+- zotero_key、标题、作者及年份 **缺一不可**
+- 每个提取点必须注明 **来源**（文章哪句话/哪个段落）
+- 同一任务的多篇文献 **追加写入同一个文件**，不要每篇新建
+
+### Step 4: 整合输出
+
+全部读完，根据用户原始意图输出总结：
+
+**综述写作**：
+```
+从 N 篇文献中：
+- 主题A 共识: ...
+- 主题A 争议: ...
+- 方法论趋势: ...
+- 关键引用:
+  1. "...[结论]" — ABC12345 (Author, Year), Fig.X
+  2. ...
+```
+
+**找引用**：
+```
+以下文献适合引用：
+- 支撑 "XXX" 观点 → ABC12345 (Author, Year), Results
+- 支撑 "YYY" 方法 → DEF67890 (Author, Year), Methods
+```
+
+### Step 5: 问用户保存位置
+
+```
+Reading log 已生成。要保存到哪里？
+(留空 → 默认 $VAULT/Bases/reading-log-<ts>.md)
+```
+
+让用户指定路径。如果用户说不清，默认放到 `$VAULT/Bases/`。
+
+---
+
+## 注意事项
+
+- **暂时不支持多篇阅读后运行 pf-end / 结束讨论**（该功能待定）
+- 如果某篇文献没有 fulltext，如实告知用户，不要捏造内容
+- Reading log 中每条提取点必须在原文中有据可查
+- JSON → MD 转换由 Agent 完成，用户只看到 MD 文件
--- a/paperforge/skills/literature-qa/references/paper-qa.md
+++ b/paperforge/skills/literature-qa/references/paper-qa.md
@ -2,8 +2,6 @@

 交互式论文 Q&A 工作台。不强制要求 OCR，但 OCR 完成后回答更准确。

-**所有 Python 命令用 `$PYTHON`（来自 pf_bootstrap 的 `python_candidate`），vault 路径用 `$VAULT`。**
-
 ---

 ## 前置条件
--- a/paperforge/skills/literature-qa/references/paper-resolution.md
+++ b/paperforge/skills/literature-qa/references/paper-resolution.md
@ -2,8 +2,6 @@

 本文件定义如何将用户输入解析为论文 workspace。所有子流程公用。

-**所有 Python 命令用 `$PYTHON`（来自 pf_bootstrap），vault 路径用 `$VAULT`。**
-
 ## 核心原则

 1. **Python 做确定性查找。** key、DOI、标题片段、作者+年份。
--- a/paperforge/skills/literature-qa/references/paper-search.md
+++ b/paperforge/skills/literature-qa/references/paper-search.md
@ -2,8 +2,6 @@

 轻量流程：用户想**在库里找文献**（不涉及精读或问答）。

-**所有 Python 命令用 `$PYTHON`（来自 pf_bootstrap 的 `python_candidate`），vault 路径用 `$VAULT`。**
-
 ---

 ## Stage 状态机
--- a/paperforge/skills/literature-qa/references/save-session.md
+++ b/paperforge/skills/literature-qa/references/save-session.md
@ -2,8 +2,6 @@

 将 paper-qa 会话中的 Q&A 记录持久化到论文工作区。

-**所有 Python 命令用 `$PYTHON`（来自 pf_bootstrap 的 `python_candidate`），vault 路径用 `$VAULT`。**
-
 ---

 ## 触发条件
--- a/paperforge/skills/literature-qa/references/vault-knowledge.md
+++ b/paperforge/skills/literature-qa/references/vault-knowledge.md
@ -1,121 +0,0 @@
-# PaperForge Vault 结构知识
-
-本文件是 Agent 理解 PaperForge Vault 的共享参考。精读、问答、检索等所有工作流都先从这里获取基础概念。
-
---
-
-## 0. Pre-flight Checklist — 进任何流程前必做
-
-1. **确认 vault 路径** — 找到 `paperforge.json` 的目录
-2. **跑 paths 获取实际目录** — `python -m paperforge.worker.paper_resolver paths --vault "$VAULT"`
-3. **确认 paths 命令成功** — 拿到 `literature_dir`、`index_path`、`ocr_dir`
-4. **记住这些路径** — 后面所有文件读写都用 `paths` 返回的实际值。**禁止将示例路径（如 `D:\...\System\PaperForge`）与 paperforge.json 里的目录名（如 `system_dir: "99_System"`）拼接。** 一切路径完全来自 `paper_resolver paths` 或 `paper_resolver resolve-key` 返回的 JSON。
-
-如果 `paper_resolver` 报错，先解决报错再继续。**绝对不要在没有 paths JSON 的情况下自己通过拼接目录名来猜测路径。**
-
---
-
-## 浏览场景
-
-用户说"看一下库里内容"、"库里有什么"、"浏览文献库"时：
-
-pf_bootstrap 已经返回了 `domains` 和 `index_summary`。直接展示：
-
-```
-Vault: <vault_root>
-Domains:
-  - 骨科: 550 篇
-  - 运动医学: 263 篇
-共 813 篇
-```
-
-如果用户继续问具体内容，Agent 加载 [paper-search.md](paper-search.md) 搜索。
-
---
-
-## 1. 目录结构速览
-
-Path 全部由 pf_bootstrap 的 `paths` JSON 提供，不要自己拼。
-
-```
-{vault_root}/
-├── {resources_dir}/
-│   └── {literature_dir}/              ← 正式文献笔记
-│       ├── 骨科/                       ← 领域 (domain)
-│       │   ├── ABC12345 - Paper Title/ ← workspace 目录
-│       │   │   ├── ABC12345.md          ← 正式笔记 (文件名 = key)
-│       │   │   ├── fulltext.md               ← OCR 全文
-│       │   │   └── ai/                        ← Agent 工作区
-│       │   └── ...
-│       └── 运动医学/
-│           └── ...
-├── {system_dir}/
-│   └── PaperForge/
-│       ├── exports/                   ← Zotero BBT 导出 JSON
-│       ├── ocr/{KEY}/                 ← OCR 原始结果 (fulltext.md, images/, meta.json)
-│       └── indexes/
-│           └── formal-library.json    ← 核心索引
-```
-
-## 2. Domain 与 Collection
-
- **Domain**（领域）= `literature_dir` 下的子目录名，如 `骨科`、`运动医学`
- **Collection**（Zotero 收藏夹）= BBT JSON 里的分组，映射关系在 `{system_dir}/PaperForge/config/domain-collections.json`
- 每篇论文属于一个 domain，可能有子分类 (`collection_path`)
-
-Domain 列表可以直接 `Get-ChildItem {literature_dir} -Directory` 获取，不需要读配置。
-
-## 3. formal-library.json — 核心索引
-
-位置：pf_bootstrap 的 `paths.index_path`
-
-结构：
-
-```json
-{
-  "items": {
-    "ABC12345": {
-      "key": "ABC12345",
-      "title": "Paper Title",
-      "domain": "骨科",
-      "year": 2024,
-      "doi": "10.xxxx/xxxxx",
-      "first_author": "Smith",
-      "journal": "Journal of ...",
-      "ocr_status": "done",
-      "has_pdf": true,
-      "collection_path": "子分类名"
-    }
-  }
-}
-```
-
-Agent 读这个 JSON 可以按 domain、年份、作者、标题关键词等筛选。
-
-## 4. Workspace 结构
-
-每篇论文的 workspace 目录：
-
-```
-{literature_dir}/{domain}/{KEY} - {Title}/
-├── {KEY}.md                   ← 正式笔记 (文件名 = key, 标题在 frontmatter title + aliases)
-├── fulltext.md                ← OCR 全文 (含 <!-- page N --> 分页标记)
-├── paper-meta.json            ← 生命周期追踪
-└── ai/                         ← Agent 工作区
-    ├── discussion.md           ← /pf-paper 讨论记录
-    └── discussion.json         ← 结构化 Q&A
-```
-
-## 5. 如何读论文内容
-
-| 你要做什么         | 操作                                                                                                                                   |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
-| 看论文元数据       | 读 formal-library.json 或正式笔记 frontmatter                                                                                         |
-| 读 OCR 全文        | 读 workspace 的 `fulltext.md`（如果 `ocr_status == "done"`）                                                                            |
-| 读精读笔记         | 读正式笔记的 `## 🔍 精读` 区域                                                                                                           |
-| 按 key 查完整路径  | `$PYTHON -m paperforge.worker.paper_resolver resolve-key <KEY> --vault "$VAULT"`                                                         |
-| 按 domain 搜关键词 | `$PYTHON -m paperforge.worker.paper_resolver search --title "..." --domain "..." --vault "$VAULT"`<br>或直接读 formal-library.json      |
-
-## 6. 论文定位
-
-详见 [paper-resolution.md](paper-resolution.md)。定位论文后，用返回的 workspace 路径找到 `fulltext.md` 读内容。