From f244f72056fb3fdf6c44e4c2b97dbac39fc9b1fd Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Mon, 11 May 2026 23:58:46 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20restructure=20literature-qa=20v2=20?= =?UTF-8?q?=E2=80=94=20SKILL.md=20as=20central=20hub=20with=20decision=20t?= =?UTF-8?q?ree,=20add=20multi-reading,=20simplify=20refs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...2026-05-11-literature-qa-v2-restructure.md | 375 ++++++++++++++++++ paperforge/skills/literature-qa/SKILL.md | 174 +++++--- .../literature-qa/references/deep-reading.md | 2 - .../literature-qa/references/multi-reading.md | 144 +++++++ .../literature-qa/references/paper-qa.md | 2 - .../references/paper-resolution.md | 2 - .../literature-qa/references/paper-search.md | 2 - .../literature-qa/references/save-session.md | 2 - .../references/vault-knowledge.md | 121 ------ 9 files changed, 642 insertions(+), 182 deletions(-) create mode 100644 docs/superpowers/plans/2026-05-11-literature-qa-v2-restructure.md create mode 100644 paperforge/skills/literature-qa/references/multi-reading.md delete mode 100644 paperforge/skills/literature-qa/references/vault-knowledge.md diff --git a/docs/superpowers/plans/2026-05-11-literature-qa-v2-restructure.md b/docs/superpowers/plans/2026-05-11-literature-qa-v2-restructure.md new file mode 100644 index 00000000..91468773 --- /dev/null +++ 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 /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 --vault "$VAULT"` | 确定性匹配，返回 workspace 路径 | +| 定位论文（按 DOI） | `$PYTHON -m paperforge.worker.paper_resolver resolve-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 --vault "$VAULT"` | 机械操作，Agent 不做 | +| 保存讨论 | `$PYTHON -m paperforge.worker.discussion record --vault "$VAULT" --agent pf-paper --model "" --qa-pairs '...'` | 写入 discussion.md/json | + +**什么时候自己 grep/glob/read：** + +| 场景 | 操作 | 原因 | +| ----------------------- | ------------------------------------------------------- | -------------------------- | +| 按关键词在全部文献里搜 | `grep <关键词> $IDX_PATH` 或读 JSON 筛 `title`/`abstract` | 模糊搜索，paper_resolver 不够 | +| 读论文全文/精读笔记 | 直接 read `$LIT_DIR// - /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 | diff --git a/paperforge/skills/literature-qa/SKILL.md b/paperforge/skills/literature-qa/SKILL.md index c46f7c98..0fdb5465 100644 --- 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 ← 精读引擎 ``` diff --git a/paperforge/skills/literature-qa/references/deep-reading.md b/paperforge/skills/literature-qa/references/deep-reading.md index 48f0fcd1..dc406d32 100644 --- 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`）。** - --- ## 前置条件检查 diff --git a/paperforge/skills/literature-qa/references/multi-reading.md b/paperforge/skills/literature-qa/references/multi-reading.md new file mode 100644 index 00000000..091e4530 --- /dev/null +++ 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 文件 diff --git a/paperforge/skills/literature-qa/references/paper-qa.md b/paperforge/skills/literature-qa/references/paper-qa.md index ee8323c1..626f23e0 100644 --- 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`。** - --- ## 前置条件 diff --git a/paperforge/skills/literature-qa/references/paper-resolution.md b/paperforge/skills/literature-qa/references/paper-resolution.md index 363635aa..dee38b0d 100644 --- 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、标题片段、作者+年份。 diff --git a/paperforge/skills/literature-qa/references/paper-search.md b/paperforge/skills/literature-qa/references/paper-search.md index 917b25d1..57aa634f 100644 --- 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 状态机 diff --git a/paperforge/skills/literature-qa/references/save-session.md b/paperforge/skills/literature-qa/references/save-session.md index aa4abb10..9e3785de 100644 --- 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`。** - --- ## 触发条件 diff --git a/paperforge/skills/literature-qa/references/vault-knowledge.md b/paperforge/skills/literature-qa/references/vault-knowledge.md deleted file mode 100644 index f961cd03..00000000 --- a/paperforge/skills/literature-qa/references/vault-knowledge.md +++ /dev/null @@ -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` 读内容。