refactor(skill): rewrite compound router for skill graph

2026-07-22 06:50:53 +00:00 · 2026-05-19 14:48:15 +08:00 · 2026-05-19 14:48:15 +08:00 · d9ab8fdbe7
commit d9ab8fdbe7
parent 1fd4ae1f9f
1 changed files with 74 additions and 54 deletions
--- a/paperforge/skills/paperforge/SKILL.md
+++ b/paperforge/skills/paperforge/SKILL.md
@ -5,7 +5,8 @@ description: >
  工作记录、方法论提取。Triggered by:
  pf-deep pf-paper pf-sync pf-ocr pf-status,
  "精读" "找文献" "搜文献" "文献问答" "读一下" "看看这篇"
-  "讨论" "记录阅读" "记录工作" "总结会话" "提取方法论".
+  "讨论" "记录阅读" "记录工作" "总结会话" "提取方法论"
+  "记一下" "保存这次" "找证据" "找75 Hz" "找支持" "collection" "库里".
 source: paperforge
 ---

@ -22,7 +23,7 @@ PaperForge 将文献、阅读痕迹、工作过程、方法论和产物
 python $SKILL_DIR/scripts/pf_bootstrap.py --vault "$VAULT"
 ```

-返回 JSON。记录以下变量（所有 workflow 文件继承，不再重复声明）：
+返回 JSON。记录以下变量（所有 molecule 文件继承，不再重复声明）：

 | 变量          | JSON 字段               | 用途                           |
 | ------------- | ----------------------- | ------------------------------ |
@ -37,6 +38,8 @@ python $SKILL_DIR/scripts/pf_bootstrap.py --vault "$VAULT"
 如果 `python_verified` 为 `false` 或 `python_candidate` 为 `null`：
 依次尝试 `python` 再 `python3`。全部失败则停止，提示用户在 `paperforge.json` 中设置 `python_path`。

+bootstrap 现在也返回一个 `capabilities` 块（rg, semantic, metadata 等）。
+
 ---

 ## 2. Agent Context — bootstrap 成功后执行
@ -65,21 +68,63 @@ $PYTHON -m paperforge --vault "$VAULT" runtime-health --json

 检查返回 JSON：

- `data.summary.safe_read == false`：禁止路由到 `paper-search`、`paper-qa`、`deep-reading`
- `data.summary.safe_write == false`：禁止路由到 `reading-log`、`project-log`
+- `data.summary.safe_read == false`：禁止路由到 paper-search、paper-qa、deep-reading
+- `data.summary.safe_write == false`：禁止路由到 reading-log、project-log
 - `data.layers.vector.status != "ok"`：禁止把 semantic retrieve 当主路径，必要时退回 FTS / paper-context / fulltext
 - `data.layers.*.repair_command` 存在时，优先把该命令作为修复建议返回给用户

-一旦 runtime-health 通过，后续 molecule 继承该状态，**不要在每个 workflow 里重复跑 preflight**。
+一旦 runtime-health 通过，后续 molecule 继承该状态，**不要在每个 molecule 里重复跑 preflight**。

 Dashboard 的 `System Status` 只是这个 contract 的薄展示，不是第二套真相源。

 ---

-## 4. Methodology Index — bootstrap 自动提供
+## 4. 意图路由

-bootstrap 已返回 `methodology_index`（从 `System/PaperForge/methodology/archive/` 扫描）。
-Agent 在需要时自行读取对应卡片（`read System/PaperForge/methodology/archive/<id>.md`）。
+用户输入按以下顺序判定并路由到 molecule。
+
+### A. 机械命令（不经过 research intent routing）
+
+| 用户说        | 动作                                                       |
+| ------------- | ---------------------------------------------------------- |
+| `/pf-sync`    | 执行 `paperforge sync`，解释结果                           |
+| `/pf-ocr`     | 执行 `paperforge ocr`，解释结果                            |
+| `/pf-status`  | 执行 `paperforge status --json` 或 `runtime-health --json` |
+
+### B. 研究命令别名
+
+| 用户说      | 路由到的 intent              |
+| ----------- | ---------------------------- |
+| `/pf-deep`  | `deep_analyze_paper`         |
+| `/pf-paper` | `read_known_paper`           |
+
+### C. 顶层研究意图（按判定顺序）
+
+1. **`capture_project_knowledge`** — 直接保存/归档/提取（用户说"记一下"、"保存这次"、"提取方法论"）
+2. **`read_known_paper`** — 用户给定了明确的 paper（key/DOI/标题）
+3. **`discover_papers`** — 用户要找一批论文（"找XX的文章"、"collection里有什么"）
+4. **`find_supporting_evidence`** — 用户要找具体证据/参数/术语（"找75 Hz"、"找支持这句话的依据"）
+5. **`deep_analyze_paper`** — 用户明确要精读（"/pf-deep"）
+
+**判定顺序（必须严格按此顺序执行）：**
+
+```text
+0. 处理机械命令（A 节）
+1. 处理别名（B 节）→ deep_analyze_paper / read_known_paper
+2. 如果用户要求保存/归档/从上下文提取 → capture_project_knowledge
+3. 如果用户已指向单一论文 → read_known_paper
+4. 如果用户想要论文列表 → discover_papers
+5. 如果用户想要证据/支持 → find_supporting_evidence
+6. 如果意图无法判定 → 打开 atoms/clarify-user-intent.md
+7. post-action：molecule 输出后，如果用户要求保存 → capture_project_knowledge
+```
+
+### D. Clarify 回退
+
+- 不能稳定判定 intent 时，打开 `atoms/clarify-user-intent.md`
+- 最多两轮
+
+未知或拼错的 `/pf-*` 命令不要静默掉进 `project-engineering`，必须明确提示用户命令不存在或请澄清意图。

 ---

@ -96,37 +141,7 @@ Reading-log 不是事实源。它记录的是**之前的关注点、解读和预

 ---

-## 6. 意图路由
-
-用户输入分两类处理：
-
-### A. 机械命令（直接执行并解读结果，不走研究 workflow）
-
-| 用户说 | 动作 |
-| --- | --- |
-| `/pf-sync` | 执行 `paperforge sync`，检查结果并解释 |
-| `/pf-ocr` | 执行 `paperforge ocr`，检查结果并解释 |
-| `/pf-status` | 执行 `paperforge status --json` 或 `paperforge runtime-health --json`，解读状态 |
-
-### B. 研究工作流（打开唯一 workflow 文件并执行完整流程）
-
-| 用户说                                                   | 打开                             |
-| -------------------------------------------------------- | -------------------------------- |
-| "找文献" "搜" "库里有没有XX" "collection 里关于YY"       | `workflows/paper-search.md`      |
-| "精读 <key>" "/pf-deep" "三阶段阅读"                     | `workflows/deep-reading.md`      |
-| "读一下" "看看" "讨论" "/pf-paper" "<key> 这篇讲了什么"  | `workflows/paper-qa.md`          |
-| "记一下" "记录阅读" "reading log" "读完这段记一下"       | `workflows/reading-log.md`       |
-| "总结会话" "工作记录" "项目记录" "project log" "记决策"   | `workflows/project-log.md`       |
-| "提取方法论" "总结规律" "存档写作规律"                    | `workflows/methodology.md`       |
-| "branch" "代码审查" "feature" "dashboard" "memory layer" "用户反馈" "报错" "安装失败" "Git" "Zotero" "BetterBibTeX" "插件" | `workflows/project-engineering.md` |
-| 不确定 / 空输入                                          | 问用户：搜文献、精读、问答、记笔记、记工作、提方法论？ |
-
-路由后如用户切换意图，重新判断并打开对应 workflow。
-未知或拼错的 `/pf-*` 命令不要静默掉进 `project-engineering`，必须明确提示用户命令不存在或请澄清意图。
-
---
-
-## 7. 全局禁止规则
+## 6. 全局禁止规则

 - **禁止自行拼接文件路径**。所有路径从 bootstrap 或 paper-context 获取。
 - **禁止绕过 CLI 直接操作文件**。搜索用 `$PYTHON -m paperforge search`，不用 glob/grep 扫库。
@ -137,20 +152,25 @@ Reading-log 不是事实源。它记录的是**之前的关注点、解读和预
 ## 文件结构

 ```
-paperforge/
+paperforge/skills/paperforge/
 ├── SKILL.md              ← 本文件（compound：启动注入 + 路由 + 全局规则）
-├── workflows/            ← molecules：原子序列 + 分支条件
-│   ├── paper-search.md
-│   ├── deep-reading.md
-│   ├── paper-qa.md
-│   ├── reading-log.md
-│   ├── project-log.md
-│   ├── methodology.md
-│   └── project-engineering.md
-├── references/           ← 共享参考
-│   ├── chart-reading/    ← 19 种图表阅读指南
-│   └── method-card-template.md
-└── scripts/              ← 脚本 atoms
-    ├── pf_bootstrap.py
-    └── pf_deep.py
+├── molecules/            ← 1 molecule = 1 intent 的完整执行流程
+│   ├── read-known-paper.md
+│   ├── discover-papers.md
+│   ├── find-supporting-evidence.md
+│   ├── deep-analyze-paper.md
+│   └── capture-project-knowledge.md
+├── atoms/                ← 可复用子步骤
+│   ├── clarify-user-intent.md
+│   ├── retrieval-routing.md
+│   ├── write-reading-log-jsonl.md
+│   ├── write-project-reading-log.md
+│   ├── write-project-log.md
+│   ├── extract-methodology-card.md
+│   └── chart-reading/
+├── scripts/
+│   ├── pf_bootstrap.py
+│   └── pf_deep.py
+└── workflows/
+    └── project-engineering.md
 ```