fix(literature-qa): add mandatory pre-flight, vault discovery, STAGE state machine to prevent agent drift

paperforge/skills/literature-qa/SKILL.md

@@ -11,13 +11,43 @@ compatibility: all
 
 # Literature QA — 学术文献精读、问答与检索
 
-## 共享知识
+---
 
-Agent 首先加载 [references/vault-knowledge.md](references/vault-knowledge.md)，了解 Vault 结构、Domain/Collection 概念、索引格式、Workspace 布局。
+## MANDATORY FIRST STEP — 必须先执行，不可跳过
+
+在任何文献操作之前，你必须完成以下三步。跑不完不要进入后续路由。
+
+### Step A: 识别 Vault
+
+检查当前目录及其父目录是否存在 `paperforge.json`：
+
+```
+Test-Path paperforge.json
+```
+
+如果不存在，逐级往上找（`..`、`..\..`），直到找到。如果找不到，**问用户**："你的 PaperForge Vault 根目录路径是什么？"
+
+记下 vault 根目录为 `$VAULT`，后续所有 `--vault` 参数都用这个路径。
+
+### Step B: 获取路径
+
+```
+python -m paperforge.worker.paper_resolver paths --vault "$VAULT"
+```
+
+如果报 `No module named paperforge`，说明当前 Python 环境没装 paperforge。不要硬闯文件的目录树——**问用户**："你用的是哪个 Python？Vault 里的 `.venv` 路径是什么？"
+
+### Step C: 加载共享知识
+
+加载 [references/vault-knowledge.md](references/vault-knowledge.md) 了解 Vault 结构、Domain/Collection 概念、索引格式。
+
+只有在 Step A+B+C 全部完成之后，才能进入下面的路由表。
+
+---
 
 ## 路由表
 
-Agent 读到本文件后，首先根据用户意图路由到对应的 reference 文件：
+Agent 根据用户意图路由到对应的 reference 文件：
 
 | 用户意图 | 典型输入 | 加载文件 |
 |---------|---------|---------|
@@ -28,7 +58,7 @@ Agent 读到本文件后，首先根据用户意图路由到对应的 reference
 | 论文问答 | `/pf-paper <query>`, `pf-paper <query>`, "做这篇的问答", "帮我看看 XXX", "这篇文章讲了什么", "查一下" | [references/paper-qa.md](references/paper-qa.md) |
 | 保存讨论记录 | `/pf-end`, `pf-end`, "保存", "结束讨论", "完成讨论", "保存记录" | [references/save-session.md](references/save-session.md) |
 
-> **重要：** 加载 reference 文件后，严格按照该文件的流程执行。不要跳过任何步骤。
+> **重要：** 加载 reference 文件后，**严格按照该文件的流程执行，不要跳过任何步骤。** 如果你不知道下一步干什么，回顾 reference 文件的流程，不要自己发明步骤。
 
 ## 论文定位
 

paperforge/skills/literature-qa/references/paper-search.md

@@ -4,6 +4,25 @@
 
 ---
 
+## Stage 状态机
+
+你必须明确知道当前在哪个 stage。每完成一个 stage 问自己："下一步是什么？" 不要在 stage 之间来回跳跃。
+
+| Stage | 你在干什么                       | 完成后做什么                         |
+| ----- | -------------------------------- | ------------------------------------ |
+| S1    | 理解用户要找什么（domain/关键词） | 进入 S2                              |
+| S2    | 执行搜索（paper_resolver 或 JSON） | 进入 S3                              |
+| S3    | 展示候选清单给用户               | 等用户选择                           |
+| S4    | 用户选了文献，决定下一步路由     | 进入对应 reference 流程，不再回来   |
+| S5    | 写作辅助：读完文献后整合输出     | 结束                                 |
+
+**不要做的事**：
+- 不要在 S2 阶段去读论文全文
+- 不要在 S3 阶段自作主张替用户选文献
+- 不要在找不到结果时硬猜文件路径
+
+---
+
 ## 触发场景
 
 - "找一下骨科里面关于骨再生的文献"

paperforge/skills/literature-qa/references/vault-knowledge.md

@@ -2,6 +2,19 @@
 
 本文件是 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. **记住这些路径** — 后面所有文件读写都用这些路径，不硬编码
+
+如果 `paper_resolver` 报错，先解决报错再继续。**不要在没有 paths 数据的情况下自己猜路径。**
+
+---
+
 ## 浏览场景
 
 用户说"看一下库里内容"、"看一下文献库"、"库里有什么"、"浏览文献"时，Agent 展示 Vault 概况：
@@ -47,7 +60,7 @@ python -m paperforge.worker.paper_resolver paths --vault .
 │   └── {literature_dir}/              ← 正式文献笔记
 │       ├── 骨科/                       ← 领域 (domain)
 │       │   ├── ABC12345 - Paper Title/ ← workspace 目录
-│       │   │   ├── ABC12345 - Paper Title.md  ← 正式笔记 (含 frontmatter)
+│       │   │   ├── ABC12345.md          ← 正式笔记 (文件名 = key)
 │       │   │   ├── fulltext.md               ← OCR 全文
 │       │   │   └── ai/                        ← Agent 工作区
 │       │   └── ...
@@ -102,7 +115,7 @@ Agent 读这个 JSON 可以按 domain、年份、作者、标题关键词等筛
 
 ```
 {literature_dir}/{domain}/{KEY} - {Title}/
-├── {KEY} - {Title}.md       ← 正式笔记 (frontmatter + 精读内容)
+├── {KEY}.md                   ← 正式笔记 (文件名 = key, 标题在 frontmatter title + aliases)
 ├── fulltext.md                ← OCR 全文 (含 <!-- page N --> 分页标记)
 ├── paper-meta.json            ← 生命周期追踪
 └── ai/                         ← Agent 工作区