From d9ab8fdbe7daebe7ccd128c55767c66939f79fcf Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Tue, 19 May 2026 14:48:15 +0800 Subject: [PATCH] refactor(skill): rewrite compound router for skill graph --- paperforge/skills/paperforge/SKILL.md | 128 +++++++++++++++----------- 1 file changed, 74 insertions(+), 54 deletions(-) diff --git a/paperforge/skills/paperforge/SKILL.md b/paperforge/skills/paperforge/SKILL.md index 48e719a7..012fe720 100644 --- 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/.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` | -| "精读 " "/pf-deep" "三阶段阅读" | `workflows/deep-reading.md` | -| "读一下" "看看" "讨论" "/pf-paper" " 这篇讲了什么" | `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 ```