From 465ad0a932bf55bfe65d67ac2ba15f754191f577 Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Mon, 11 May 2026 18:49:33 +0800 Subject: [PATCH] feat(skill): add vault-knowledge + paper-search reference files, update routing table --- paperforge/skills/literature-qa/SKILL.md | 43 ++++--- .../literature-qa/references/paper-search.md | 72 ++++++++++++ .../references/vault-knowledge.md | 109 ++++++++++++++++++ 3 files changed, 202 insertions(+), 22 deletions(-) create mode 100644 paperforge/skills/literature-qa/references/paper-search.md create mode 100644 paperforge/skills/literature-qa/references/vault-knowledge.md diff --git a/paperforge/skills/literature-qa/SKILL.md b/paperforge/skills/literature-qa/SKILL.md index 63d4618e..541c840a 100644 --- 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, "精读 ", "文献问答 ", "结束讨论", "保存记录", - "精读队列". 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 `, `pf-deep `, "精读 XXX", "深度阅读 XXX", "带我读", "组会讲这篇", "读一下这篇" | [references/deep-reading.md](references/deep-reading.md) | | 三阶段精读（查看队列） | `/pf-deep`（无参数）, "精读队列", "有哪些该读了" | [references/deep-reading.md](references/deep-reading.md) | | 论文问答 | `/pf-paper `, `pf-paper `, "做这篇的问答", "帮我看看 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 --vault .` | -| 定位论文（按 DOI） | `python -m paperforge.worker.paper_resolver resolve-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 --vault .` | +| 定位论文（按 DOI） | `python -m paperforge.worker.paper_resolver resolve-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/ diff --git a/paperforge/skills/literature-qa/references/paper-search.md b/paperforge/skills/literature-qa/references/paper-search.md new file mode 100644 index 00000000..c11acb48 --- /dev/null +++ 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 diff --git a/paperforge/skills/literature-qa/references/vault-knowledge.md b/paperforge/skills/literature-qa/references/vault-knowledge.md new file mode 100644 index 00000000..a9969332 --- /dev/null +++ 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 全文 (含 分页标记) +├── 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 --vault .` | +| 按 DOMAIN 搜关键词 | `python -m paperforge.worker.paper_resolver search --title "..." --domain "..." --vault .`
或直接 grep formal-library.json 的 title | + +## 7. 论文定位 + +详见 [paper-resolution.md](paper-resolution.md)。定位论文后，用返回的 workspace 路径找到 `fulltext.md` 读内容。