feat(skill): add vault-knowledge + paper-search reference files, update routing table

2026-07-22 06:50:53 +00:00 · 2026-05-11 18:49:33 +08:00 · 2026-05-11 18:49:33 +08:00 · 465ad0a932
commit 465ad0a932
parent 12d7ff62a4
3 changed files with 202 additions and 22 deletions
--- a/paperforge/skills/literature-qa/SKILL.md
+++ b/paperforge/skills/literature-qa/SKILL.md
@ -1,14 +1,19 @@
 ---
 name: literature-qa
 description: >
-  学术文献精读与问答。Triggered by: /pf-deep /pf-paper /pf-end,
+  学术文献精读、问答与检索。Triggered by: /pf-deep /pf-paper /pf-end,
  "精读 <key/title>", "文献问答 <key/title>", "结束讨论", "保存记录",
-  "精读队列". Uses Zotero key, DOI, or title to locate papers.
+  "找一下...文献", "查一下...", "库里有没有", "精读队列".
+  Uses Zotero key, DOI, title, or domain keywords to locate papers.
 license: Apache-2.0
 compatibility: all
 ---

-# Literature QA — 学术文献精读与问答
+# Literature QA — 学术文献精读、问答与检索
+
+## 共享知识
+
+Agent 首先加载 [references/vault-knowledge.md](references/vault-knowledge.md)，了解 Vault 结构、Domain/Collection 概念、索引格式、Workspace 布局。

 ## 路由表

@ -16,6 +21,7 @@ Agent 读到本文件后，首先根据用户意图路由到对应的 reference

 | 用户意图 | 典型输入 | 加载文件 |
 |---------|---------|---------|
+| 文献检索 | "找一下骨科...文献", "查一下 TGF-beta", "库里有没有支架材料的", "搜一下 Smith 的文章", "collection 里有没有" | [references/paper-search.md](references/paper-search.md) |
 | 三阶段精读（指定论文） | `/pf-deep <query>`, `pf-deep <query>`, "精读 XXX", "深度阅读 XXX", "带我读", "组会讲这篇", "读一下这篇" | [references/deep-reading.md](references/deep-reading.md) |
 | 三阶段精读（查看队列） | `/pf-deep`（无参数）, "精读队列", "有哪些该读了" | [references/deep-reading.md](references/deep-reading.md) |
 | 论文问答 | `/pf-paper <query>`, `pf-paper <query>`, "做这篇的问答", "帮我看看 XXX", "这篇文章讲了什么", "查一下" | [references/paper-qa.md](references/paper-qa.md) |
@ -23,27 +29,18 @@ Agent 读到本文件后，首先根据用户意图路由到对应的 reference

 > **重要：** 加载 reference 文件后，严格按照该文件的流程执行。不要跳过任何步骤。

-## 论文定位（所有路由共用，先执行）
+## 论文定位

-详见 [references/paper-resolution.md](references/paper-resolution.md)。
+所有路由共享的论文定位协议：见 [references/paper-resolution.md](references/paper-resolution.md)。

-**核心原则：所有路径操作走 Python，Agent 只管调命令、读输出。零硬编码、零平台依赖。**
+**核心原则：路径从 `paths` 获取，不硬编码。**

-### 快速索引
-
-| 你要做什么 | 跑这个 Python 命令 |
-|-----------|-------------------|
-| 定位论文（按 key） | `python -m paperforge.worker.paper_resolver resolve-key <KEY> --vault .` |
-| 定位论文（按 DOI） | `python -m paperforge.worker.paper_resolver resolve-doi "<DOI>" --vault .` |
-| 搜索论文（字段匹配） | `python -m paperforge.worker.paper_resolver search --title "..." --author "..." --year ... --vault .` |
-| 获取 vault 路径 | `python -m paperforge.worker.paper_resolver paths --vault .` |
-
-### 处理结果
-
- **Python 返回匹配：** 直接使用返回的 workspace
- **Python 返回空：** Agent 自己搜。用 `paths` 拿到的 `literature_dir` 和 `index_path`，grep frontmatter / 读 formal-library.json
- **自然语言输入：** Agent 自己理解语义，读 formal-library.json（`paths` 里的 `index_path`）搜索
- **命中多篇：** 列出候选清单（key, title, year, domain, ocr_status），让用户选
+| 你要做什么     | 跑这个 Python 命令                                                               |
+| -------------- | -------------------------------------------------------------------------------- |
+| 获取 vault 路径 | `python -m paperforge.worker.paper_resolver paths --vault .`                      |
+| 定位论文（按 key） | `python -m paperforge.worker.paper_resolver resolve-key <KEY> --vault .`          |
+| 定位论文（按 DOI） | `python -m paperforge.worker.paper_resolver resolve-doi "<DOI>" --vault .`        |
+| 搜索论文       | `python -m paperforge.worker.paper_resolver search --title "..." --domain "..." --vault .` |

 ## 文件结构

@ -51,10 +48,12 @@ Agent 读到本文件后，首先根据用户意图路由到对应的 reference
 literature-qa/
 ├── SKILL.md                       ← 本文件（路由入口）
 ├── references/
+│   ├── vault-knowledge.md         ← Vault 结构共享知识
+│   ├── paper-resolution.md        ← 论文定位详细协议
+│   ├── paper-search.md            ← 文献检索工作流
 │   ├── deep-reading.md            ← 精读工作流
 │   ├── paper-qa.md                ← 问答工作流
 │   ├── save-session.md            ← 保存记录工作流
-│   ├── paper-resolution.md        ← 论文定位详细协议
 │   ├── deep-subagent.md           ← 子代理提示词模板
 │   └── chart-reading/             ← 19 个图表类型阅读指南
 └── scripts/
--- a/paperforge/skills/literature-qa/references/paper-search.md
+++ b/paperforge/skills/literature-qa/references/paper-search.md
@ -0,0 +1,72 @@
+# 文献检索工作流
+
+轻量流程：用户想**在库里找文献**（不涉及精读或问答）。
+
+---
+
+## 触发场景
+
+- "找一下骨科里面关于骨再生的文献"
+- "查一下 TGF-beta 相关的文章"
+- "库里有没有讲支架材料的"
+- "这个 collection 有哪些文献"
+- "搜一下 Smith 2024 的文章"
+
+## 流程
+
+### Step 1: 获取路径
+
+```
+python -m paperforge.worker.paper_resolver paths --vault .
+```
+
+得到 `index_path` 和 `literature_dir`。
+
+### Step 2: 解析用户意图
+
+从用户输入提取：
+- **domain**（如果有）：`骨科`、`运动医学` 等 → 对应 `literature_dir` 子目录
+- **关键词**：标题、作者、年份、期刊、主题词
+- **collection 路径**：Zotero 子分类，如 `电刺激软骨修复综述`
+
+### Step 3: 搜索
+
+**优先：Python paper_resolver**（确定性匹配）
+
+```
+python -m paperforge.worker.paper_resolver search --title "关键词" --author "Smith" --year 2024 --domain "骨科" --vault .
+```
+
+**Fallback：读 formal-library.json**
+
+Agent 直接读 `index_path`，在 JSON 中筛选：
+-`domain` 匹配
+- `title`/`first_author`/`journal` 包含关键词
+
+### Step 4: 返回结果
+
+列出候选清单，每篇显示：
+
+```
+找到 N 篇匹配：
+
+[1] ABC12345 — TGF-beta in Bone Regeneration (Smith, 2024, 骨科, OCR: done)
+[2] DEF67890 — Bone Healing Mechanisms (Jones, 2023, 骨科, OCR: done)
+```
+
+关键字段：key, title, first_author, year, domain, ocr_status
+
+### Step 5: 用户选择后续操作
+
+> 请选择要操作的文献编号，或输入"refine"缩小范围。
+
+选中文献后，按用户意图自动进入对应路由：
+- `精读这篇` → 进入 [deep-reading.md](deep-reading.md) 流程
+- `这篇讲了什么` → 进入 [paper-qa.md](paper-qa.md) 流程
+- 不需要继续 → 结束
+
+## 注意事项
+
+- 如果是大型 library（>500 篇），优先用 paper_resolver 而不是全量读 JSON
+- OCR status 为 `done` 的论文可以读 fulltext 内容
+- OCR status 为 `pending` 的只有 formal note frontmatter
--- a/paperforge/skills/literature-qa/references/vault-knowledge.md
+++ b/paperforge/skills/literature-qa/references/vault-knowledge.md
@ -0,0 +1,109 @@
+# PaperForge Vault 结构知识
+
+本文件是 Agent 理解 PaperForge Vault 的共享参考。精读、问答、检索等所有工作流都先从这里获取基础概念。
+
+---
+
+## 1. 获取路径
+
+所有路径从 `paperforge.json` 配置派生。Agent 不硬编码。每次需要路径时先跑：
+
+```
+python -m paperforge.worker.paper_resolver paths --vault .
+```
+
+返回：
+
+```json
+{
+  "vault_root": "D:\\...\\Vault",
+  "index_path": "D:\\...\\System\\PaperForge\\indexes\\formal-library.json",
+  "literature_dir": "D:\\...\\Resources\\Literature",
+  "ocr_dir": "D:\\...\\System\\PaperForge\\ocr"
+}
+```
+
+## 2. 目录结构速览
+
+```
+{vault_root}/
+├── {resources_dir}/
+│   └── {literature_dir}/              ← 正式文献笔记
+│       ├── 骨科/                       ← 领域 (domain)
+│       │   ├── ABC12345 - Paper Title/ ← workspace 目录
+│       │   │   ├── ABC12345 - Paper Title.md  ← 正式笔记 (含 frontmatter)
+│       │   │   ├── fulltext.md               ← OCR 全文
+│       │   │   └── ai/                        ← Agent 工作区
+│       │   └── ...
+│       └── 运动医学/
+│           └── ...
+├── {system_dir}/
+│   └── PaperForge/
+│       ├── exports/                   ← Zotero BBT 导出 JSON
+│       ├── ocr/{KEY}/                 ← OCR 原始结果 (fulltext.md, images/, meta.json)
+│       └── indexes/
+│           └── formal-library.json    ← 核心索引
+```
+
+## 3. 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` 获取，不需要读配置。
+
+## 4. formal-library.json — 核心索引
+
+位置：`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、年份、作者、标题关键词等筛选。
+
+## 5. Workspace 结构
+
+每篇论文的 workspace 目录：
+
+```
+{literature_dir}/{domain}/{KEY} - {Title}/
+├── {KEY} - {Title}.md       ← 正式笔记 (frontmatter + 精读内容)
+├── fulltext.md                ← OCR 全文 (含 <!-- page N --> 分页标记)
+├── paper-meta.json            ← 生命周期追踪
+└── ai/                         ← Agent 工作区
+    ├── discussion.md           ← /pf-paper 讨论记录
+    └── discussion.json         ← 结构化 Q&A
+```
+
+## 6. 如何读论文内容
+
+| 你要做什么         | 操作                                                                                                                                   |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| 看论文元数据       | 读 formal-library.json 或正式笔记 frontmatter                                                                                         |
+| 读 OCR 全文        | 读 workspace 的 `fulltext.md`（如果 `ocr_status == "done"`）                                                                            |
+| 读精读笔记         | 读正式笔记的 `## 🔍 精读` 区域                                                                                                           |
+| 按 key 查完整路径  | `python -m paperforge.worker.paper_resolver resolve-key <KEY> --vault .`                                                                |
+| 按 DOMAIN 搜关键词 | `python -m paperforge.worker.paper_resolver search --title "..." --domain "..." --vault .`<br>或直接 grep formal-library.json 的 title |
+
+## 7. 论文定位
+
+详见 [paper-resolution.md](paper-resolution.md)。定位论文后，用返回的 workspace 路径找到 `fulltext.md` 读内容。