paper-analysis

# Paper Analysis — 论文精读 Skill 把论文做成结构化、有据可查的深度解读。核心 **Map-Reduce + 脚本控制 PDF**:脚本拆页,逐页精读,汇总。**所有结论落到具体数字和引用,不许含糊。** [CRITICAL — 触发本 skill 时,必须严格按下列流程用 `shell`/`file_write` 工具执行脚本完成精读,**禁止用 web_search/web_fetch 直接抓 arXiv 摘要/HTML 然后写浅层解读。** 拿不到 PDF → 直接告诉用户,不允许"我读了摘要给你讲讲"这种降级。即使 shell 被拒/脚本报错,也绝对**不要**绕到 web_fetch 写一份无图表无实验数据的浅层解读。] ## 脚本路径(重要,先确定) 脚本目录有两种可能,**开工前依次 `ls` 两条(两个独立的只读 shell,都不弹 consent 弹窗)。命中哪条存在就用哪条,不要用 `||` 或 `2>/dev/null` 串起来。** - 先跑: ```bash ls ./ethan/defaults/skills/paper-analysis/scripts/ && echo USE_PKG ``` - 输出末尾有 `USE_PKG` → 脚本根 `SCRIPTS=./ethan/defaults/skills/paper-analysis/scripts` - 如果上面 `ls` 报"目录不存在"错误,再跑: ```bash ls ~/.ethan/skills/paper-analysis/scripts/ ``` - 这条能列出文件 → 脚本根 `SCRIPTS=~/.ethan/skills/paper-analysis/scripts` - 如果**两条都不存在**(`ls` 两条都报 No such file or directory):不要硬猜路径,直接告诉用户脚本未安装,结束。 (下文统一写 `$SCRIPTS/xxx.py`;不要用 `fd_find` 满仓库找脚本。) | 脚本 | 作用 | |---|---| | `fetch_paper.py` | arXiv ID/URL/本地路径 → PDF(仅标准库) | | `extract_pages.py` | PDF → 逐页 PNG + `text/page_NNN.txt` + manifest.json(`uv run --with pymupdf`) | | `analyze_page_vision.py` | 【路径A】单页 vision → 5维 JSON(脚本内调多模态 API,`uv run --with openai`) | | `merge_analysis.py` | 收拢逐页 JSON → Reduce 输入 | | `extract_paper_content.py` | 【路径C】PDF → 章节文本 + 图片(含语义命名) + 表格标题 + 公式行(`uv run --with pypdf,pillow`) | 脚本 **stdout 末行打印一行 JSON**,解析它拿路径,不要解析中间日志。 ## 路径选择(关键) - **路径 A(vision,精度高)**:环境变量 `VISION_API_KEY`(或 `OPENAI_API_KEY`)+ `VISION_BASE_URL` 存在 → 走这条。脚本把 PNG 喂多模态模型,能看清图表/公式/表格。先用 `shell: echo $VISION_API_KEY` 确认。 - **路径 B(text,通用)**:无 vision 配置 → 直接 `file_read` 脚本已落盘的每页文字 `text/page_NNN.txt`(见下),逐页分析。图表/公式精度有限(文字层常把表格拍平、公式变乱码),失真处诚实标注。 - **路径 C(结构化提取,辅助)**:可选预处理,与 A/B 不冲突。`extract_paper_content.py` 用 pypdf 把 PDF 拆成「章节文本 + 图片清单(含语义命名) + 表格标题 + 公式行」,适合需要快速定位「这张图在第几页」「这篇有几个公式」或单独抽图给用户看的场景。**注意**:pypdf 抽的公式是文字层片段,会丢上下标/特殊符号;表格只检测标题不含内容——要原貌仍需走路径 A 看 page_NNN.png。 ## 路径 C 用法(可选,结构化提取) ```bash uv run --with pypdf,pillow python $SCRIPTS/extract_paper_content.py "<pdf>" # 解析末行 result_file / useful_images_dir / formulas_dir 等 ``` 末行 JSON 字段速查:`result_file`(完整汇总)、`useful_images`(有价值图片数,尺寸≥20×20)、`useful_images_dir`(语义命名,如 `Figure1_attention_useful.png`)、`tables`(检测到的 Table N 标题)、`formulas`(Equation N / 数学符号 / 等式行)、`sections`(按章节切分的全文)。 - 典型场景 1:用户问"这篇论文有哪些图" → 跑路径 C,`ls` useful_images_dir 给用户看。 - 典型场景 2:Reduce 阶段需要核对某公式原文 → `file_read` formulas_dir 下的 `pageN_formulaM.txt`。 - 典型场景 3:想快速读章节而不是逐页 → `file_read` result_file 的 `text.sections` 数组。 - **不要把路径 C 当 vision 的替代**——它给不出图表的视觉结构、表格的行列对应、公式的真实排版。需要看图必走路径 A。 ## 工作流程 ### 第 0 步:拿 PDF + 拆页 ```bash python $SCRIPTS/fetch_paper.py "<源>" --out-dir ./paper_work # 解析末行 pdf_path uv run --with pymupdf python $SCRIPTS/extract_pages.py "<pdf>" --dpi 150 # 解析末行 manifest、effective_pages、references_start_page、text_dir ``` 脚本默认最多 30 页,自动检测 References 起始页。末行 JSON 的 **`effective_pages`** = 实际该精读的页数(含 References 起始页、封顶 30)。每页文字层已落盘到 **`text_dir/page_NNN.txt`**(路径 B 直接读)。 > **页数上限可调,不是写死的**:默认 30 只是速度与覆盖度的折中(逐页精读每页都要发请求、耗工具轮数)。读长综述/长论文时按需放宽:`--max-pages 60` 抬高上限,`--max-pages 0` 完全不封顶(处理全部正文页)。正文本身不足上限时,`effective_pages` 会自动取正文实际页数,不会硬凑。 ### Phase 1 — MAP(逐页精读,**并行批处理**) [CRITICAL — **只处理第 1 到 `effective_pages` 页**。`effective_pages` 已自动扣除 References 及之后、并封顶 `--max-pages`(默认 30)。**绝不要处理 `effective_pages` 之后的页**(那是参考文献/附录,精读无意义且会耗光工具迭代轮数导致没机会输出报告)。**总精读页数 = `effective_pages`,不是 `num_pages`!**] **必须逐页,每页产出独立结果。** 每完成一批输出 `✓ 第 N1-N2 页完成(共 effective_pages 页)`。 **并行提速(关键,避免迭代耗尽)**:agent 工具执行器对**同一轮的多个 tool_call 用 asyncio.gather 并行执行**。**两条路径都要并行批处理**: - 路径 A(vision):一轮发起 **2-3 个** `shell`(各带不同 `--page`,vision 请求重,批太大易触发网关限流) - 路径 B(text):一轮发起 **4-5 个** `file_write` 路径 A — 每页一个 shell(一轮发起多个,各带不同 `--page`,并行): ```bash uv run --with openai python $SCRIPTS/analyze_page_vision.py "<manifest>" --page N --timeout 120 ``` 脚本读 `VISION_BASE_URL`/`VISION_API_KEY`/`VISION_MODEL`,产出 `analysis_page_NNN.json`,末行 `{page,out,chars}`。**若连续报 503/超时(网关限流或端点不稳),立即转路径 B**(读文字层分析),不要在 vision 上耗轮数。 路径 B — 直接 `file_read` 拆页时已落盘的 **`<text_dir>/page_NNN.txt`**(仅 1..effective_pages),按 5 维分析,每页一个 `file_write` 存 `analysis_page_NNN.txt`,**一轮读/写多页**。`text_dir` 取自 extract_pages 末行 JSON(形如 `<pdf>_pages/text`)。**不要自己写 `python -c` 去拼 manifest 的 text 字段**——文字已按页落盘,直接读对应 txt 即可。 ### Phase 2 — REDUCE(汇总) ```bash python $SCRIPTS/merge_analysis.py "<pages_dir>" # 末行 merged 路径 # 强烈推荐：同时提取论文图片，供配图使用（不要用 2>/dev/null 吞掉 stderr， # 否则提取失败时 agent 无法感知，会静默跳过配图环节） uv run --with pypdf,pillow python $SCRIPTS/extract_paper_content.py "<pdf>" # 末行 useful_images_dir ``` `file_read` 合并后的 `merged_analysis.json`,深度整合(合并同类项/去重/数据成表/创新点↔实验对应),**流式输出最终报告**: **配图要求(重要,不能只有文字)**:论文解读必须配图,两类都要有: 1. **从论文提取有价值的图**:上一步 `useful_images_dir` 里有语义命名的图片(`Figure1_xxx_useful.png`),挑 2-4 张最有价值的(核心架构图、主结果图、关键流程图),在报告对应章节插入。插入方式随输出载体而定(飞书文档用 `docs +media-insert`,Markdown 用 ``)。 2. **自己画的方法流程图**:把论文方法的核心流程/模块关系/数据流画成 Mermaid,至少 1 张全景流程图。遵循 feishu-writer 的图种速选表与 Mermaid 净化规则(节点名双引号包裹、无斜杠括号 Emoji)。 ``` # <标题> **arXiv: <编号>** ## 1.执行摘要 ## 2.为什么重要 ## 3.前人工作(对比表) ## 4.创新点(逐条+技术原理 + 方法流程图) ## 5.实验结果(主结果表+消融表 + 论文原图) ## 总体评价(创新/实用/严谨打星 + 启发) ``` ### Phase 3 — 默认存档到知识库（除非用户明确说不存） [CRITICAL — 只要用户没在对话里明确说「不用存知识库」「别存」「只给我看报告」这类跳过存档的指令，**必须**执行本步骤。先流式输出报告给用户看、再调工具存档，不要让用户等存档。] 存档内容：**把上述最终报告（含 Markdown 标题层级、配图 Mermaid、表格）完整作为 content 存一篇。** Mermaid 流程图保留 ```mermaid ``` 代码块原样，不用额外渲染成图片。 调用 `knowledge_add`： ``` knowledge_add( title="论文精读：<论文主标题>（arXiv:<编号>）", content=<完整的最终 Markdown 报告，含 # 标题、章节、表格、mermaid、插图 Markdown>, tags=["paper/<arXiv 编号或短标题>", "paper-analysis", "ai-paper"], scene="work", frontmatter={ "source": "https://arxiv.org/abs/<arxiv_id>", "paper_arxiv_id": "<arxiv_id>", "paper_pdf_url": "<PDF 原 URL>", "type": "paper-analysis" } ) ``` 目录规则：`tags[0]` 是 `"paper/..."`，Obsidian / Filesystem 后端会按 tags[0] 的第一段 `paper/` 自动创建 `paper/` 子目录，所有论文精读归档到知识库 `paper/` 下，避免散落在根目录。 存档完成后末尾追加一行轻提示即可，不要喧宾夺主：`📚 已存档到知识库 paper/ 目录。` - 用户如果说过「不用存/别存知识库」：跳过本步，**不要**调 `knowledge_add`，也不要提存档。 [IMPORTANT — 判定「流程跑完整」的唯一标准 = 已经执行过 Phase 3（要么存档完成、要么用户明确说了不存）。如果中途因为 fetch_paper 失败、extract_pages 报错、页面请求超时等原因**没走到 REDUCE 出完整报告**，就视为没跑完整：此时要把报错/卡点明确告诉用户并说明没有存档，**不得**假装完成、更不得跳过存档提示。] ## 5 维度框架(每页按此分析,**只填该页涉及的维度,带原文数字**) 1. **摘要** — 核心问题/方案/关键创新(1-3)/成果(必须具体数字) 2. **为什么重要** — 痛点/真实场景/不解决后果/一句话通俗总结 3. **前人工作** — 2-4 流派,各带代表作+年份+缺陷(带数据) 4. **创新点** — 逐个:技术原理(通俗)/对比优势/架构(文字描述) 5. **实验** — 性能对比表(列全 baseline)/消融(每模块独立贡献)/3-5 洞察 ## 铁律 - 实验数据**必须有具体数字**:"提升明显"❌ → "top-1 76.2%→81.5%"✅ - 创新点必须与实验一一对应;消融分析每模块独立贡献 - 路径 B 文字层失真的图/公式/表格,标注"文字层不可读,建议路径 A 重跑" - 详细 5 维 schema 见 `references/analysis-framework.md`(可 `file_read`)