gemini-paper-summary

Use Gemini's multimodal long context to directly "read and understand" PDF papers (including figures, tables, and formulas), following outline style structured template outputChinese Markdown summary。Opening has no # Reference / no standalone ## 团队背景介绍 section—Metadata uses a 3-column table (Title / Venue / Topic) + quote block link + team item immediately following the paper link,section skeleton is unified as: opening table + team item → ## 3 句话总结 → ## 背景与动机 / Method Design / Representative Experimental Results / Business Implications & Value / Limitations and Future Work. For evaluation / benchmark papers, "Method Design + Representative Experimental Results" is replaced with "Evaluation Design + Evaluation Findings" (see the "Output" section below). Markdown style follows the repository's established fingerprint（* bullet / ==高亮== / ```mermaidjs block-level / tables / line width ≤ 120), output can be directly copied into outline-wiki or displayed in Obsidian. The agent can directly call this skill's scripts to summarize a single paper or batch summarize, or can follow references/api-quickstart.md to call the SDK within the session.

Dependencies: Python ≥ 3.7,google-genai（pip install -U google-genai), environment variable GEMINI_API_KEY(created in Google AI Studio ). See the "Prerequisites" section at the end for detailed dependencies and failure troubleshooting.

When to use / not use

Use

• The user provides onelocal PDF paperand wants a structured summary in Chinese
• The user wants to batch-processmultiple paperswith a concise quick readfor each(single source of character count target is in assets/prompt-template.md）
• The paper contains many figures/tables / formulas, and plain text extraction (pdftotext / PyPDF2) would lose information
• The user wants to use Gemini to read the PDF directly, rather than OCR first

Do not use

• The paper is not a PDF (webpage, Markdown, plain text)—convert to PDF first or use another skill
• Needword-for-word translation / full-text reproduction(this skill is "summarization", not translation)
• Needto compare multiple papers—this skill handles one paper at a time; for multiple papers, call it multiple times and manually combine
• Only want to extract key sentences or extractive summarization—this skill is generative structured summarization
• The user is unwilling or unable to provide GEMINI_API_KEY
• Do not use --full mode + any directory——--full forces --output <wiki_root>, and the output must be written directly to the raw side (raw/papers/<slug>.quick.md + .full.md; quick figures go to raw/assets/<slug>/fig-NN.png). full mode does not produce PNG (2026-06-30 second-round flip; full is self-contained, mermaid/ASCII stays in markdown, for agents doing multi-turn queries). If you want to output to any directory, just run quick by default (it includes figures by default, no need for --extract-figures)

Input / Output

Input

Field	Required	Description
PDF path	✓	Local .pdf file, absolute or relative path is fine
GEMINI_API_KEY	✓	Environment variable
Model ID	✗	Default gemini-3.5-flash(omit --model to use it);only override when there is a clear reason, see the "Model Selection" section below for details
Focus	✗	--focus "重点关注实验部分" and the like are appended to the prompt;full mode behaves differently—it does not append a "insights / follow-up questions" section at the end, but instead injects a ### 用户关注点: <focus> subsection under the corresponding native PDF section (see references/full-mode-contract.md key behavior guardrails)
Output path	✗	quick includes figures by default:--output is treated as adirectory(writes summary.md + figures/);--no-figures is treated as a .md file; if omitted, stdout (clears broken figures, does not export figures)
Template	✗	--template academic(default)
Extract images	✗	[向后兼容] --extract-figures: quick includes figures by default, passing this is equivalent to the default; see A' below for details
Disable images	✗	--no-figures: disables figure export and reverts to pure Markdown (for batch skimming / text-only quick review)
Render scale	✗	--figure-dpi 2.0(default 2.0 = 144 DPI), only takes effect when figure export is enabled (enabled by default in quick)
Image format	✗	--figure-format {png,webp,jpeg}, default png; for webp/jpeg you can use --figure-quality compression
Compression quality	✗	--figure-quality 1-100, default 85; only takes effect for webp/jpeg
Pixel limit	✗	--max-width N, after rendering, scale proportionally to ≤ N px wide; None means no limit
Size limit	✗	--max-size-kb N, automatically degrades when exceeding N KB (quality → format → scale); None means no limit
Thumbnail	✗	--thumbnail additionally generates thumbnails;--thumbnail-width(default 400px) controls the width
Stage 2 visual grounding	✗	--refine-figures / --no-refine-figures(default True), see A' §Stage 2 below for details
Stage 2 render scale	✗	--refine-dpi 2.0, only takes effect when --refine-figures is enabled
Full extraction mode	✗	--full, a single call produces both a quick summary + full-text-level extractiontwoartifacts;the produced layout is forced to raw-compatible——--output <wiki_root>, artifacts land in <wiki_root>/raw/papers/<slug>.quick.md + .full.md(full is self-contained, no PNG companion); quick mode additionally produces <wiki_root>/raw/assets/<slug>/fig-NN.png; for the full contract see references/full-mode-contract.md
Paper slug	✗	--slug <kebab-case>, only takes effect for --full ; if omitted, inferred from the PDF filename (kebab-cased); same origin as the raw/papers + raw/assets layout
Force overwrite	✗	--force-full, only takes effect for --full ; on the raw side, when <slug>.quick.md / .full.md already exists, overwriting is refused by default to prevent losing downstream references; add this flag to explicitly overwrite

Model Selection

Default = omit --model. The script default gemini-3.5-flash has been selected (stable, no shutdown date, officially recommended as the replacement for the deprecated 2.5 series), if you don't know what to choose / have no special reason → just use the default。

Decision flow：

1. 跑 gemini_paper_summary.py（不传 --model，用默认）
2. 输出不满意？
   ├─ 否 → 用默认就好
   └─ 是 → 先调 prompt（--focus 或改 prompt-template.md），再考虑换模型
3. 真要换模型 → 从下方"当前推荐"里按场景选；不要凭印象写 model 字符串

Current recommendation (based on gemini-api-docs-mcp real-world testing, 2026-06)：

Model	Status	Positioning	When to explicitly override (vs default)
gemini-3.5-flash（Default）	Stable	General quality/cost optimal	In most scenarios, just don't pass --model is sufficient
gemini-3.1-flash-lite	Stable	Cheapest, lightweight	Batch passing / simple surveys / large context but low requirements
gemini-3.1-pro-preview	Preview	Strongest for complex reasoning	Formal proofs / hard math / reasoning-sensitive papers

Primary model unavailable → error and exit, no end-to-end degradation(Strengthened 2026-06-30, agent blind spot patched 2026-07-01): In the table above,anymodel encountering 503 / 429 / 5xx, after the script retries 3 times,directly throws an errorto the upper layer— never silently switch to lite/pro or any other cheaper model.And when the agent receives this error, it must not switch models and rerun on its own (in the script error, "use --model <id> to switch models" is an instruction for the user, not for the agent), and must faithfully present the error + three-step suggestion to the user, letting the user decide. Switching models must be explicitly specified with --model <id> , for the complete policy see §Core Principles #8(including the error message format and three-step suggestion).

Avoid using：

• ==gemini-2.5-flash==: deprecated, officially recommended replacement gemini-3.5-flash（has a shutdown date）
• gemini-2.5-pro: deprecated, replacement gemini-3.1-pro-preview
• gemini-2.5-flash-lite: deprecated, replacement gemini-3.1-flash-lite
• Any *-preview-09-2025 / *-preview-12-2025 and other old preview snapshots—expired, officially abandoned

The deprecated series will be shut down over time. The shutdown dates in this table are based on mcp__gemini-api-docs-mcp__search_documentation / get_current_model actual measurements; before use, agent / usercheck once firstto confirm they haven't changed.Do notfix the shutdown dates / deprecated list to a month; this section should be reviewed once a year/quarter.

Anti-patterns（Don'tdo this):

• Writing from memory --model "gemini-2.5-flash" / any 2.5-* string—already deprecated
• The default value works, yet "to be safe" manually adding --model <默认>—pointless and error-prone
• Using a preview model without realizing preview rate limits are stricter
• In prompts / SKILL commentshardcoding model="gemini-X.Y-Z"—model availability changes, should follow the two paths of "default value / user explicit override"

Output

According to outline style structured template output Markdown (single source of truth for character count target：assets/prompt-template.md header declaration + §Basic Requirements #4,do notwrite specific values here again—avoid dual-maintenance drift).Unified section order: Opening 3-column table → team item (immediately following the paper link) → ## 3 句话总结 → ## 背景与动机 → ## 方法设计 → ## 代表性实验结果 → ## 业务启示 & 价值 → ## 局限与未来工作。 Evaluation / benchmark papers(the evaluation itself is the contribution, e.g. HELM / MMLU / Chatbot Arena) automatically replace ## 方法设计 + ## 代表性实验结果 with ## 评测设计 + ## 评测发现, other sections unchanged; the two paper typeschoose one of the twoand do not output both. For the determination criteria and the bullets for the two sections, see assets/prompt-template.md（single source of truth）。 Nonexistent sections may be omitted. "Open-source implementation" and "Related work / highly cited" are presented ## 业务启示 & 价值 as subsections; "Inspiration / follow-up questions" is output only when --focus is passed. Default Chinese(titles, narrative, connectives), but terms, model names, product names, library names, etc. are kept in English directlywhen necessary (see core principles #4 and #9 below).

Conciseness first(for the specific character count see the assets/prompt-template.md header,single source）：every paragraph and every bullet should be cut wherever possible: if it can be said clearly in 1 sentence, do not split it into 3; omit any setup / repetition / concept definition that can be omitted; the test is: "if this passage is deleted, the reader would misunderstand / miss key information" is the only thing that "must stay"; otherwise cut it all. Density of the summary > length of the summary.

Opening structure(unified, no A / B distinction):

| **Title** | **Venue** | **Topic** |
|-------|-------|-------|
| 论文全英文标题 | 会议'年份（如 OSDI'06） | 领域关键词 |

* 论文链接（**留空，由用户在 Outline UI 手动填写**；Gemini 不必补）

  > <TODO>

* **团队/机构**：<一作 姓名>、<导师 姓名（如能识别）>；<机构> <Lab 名（如有）>；<Lab 研究方向（如知道）>

## 3 句话总结

1. **论文主旨一句话**：方法 + 关键 insight
2. **核心设计 / 关键数据**：用具体数字说话
3. **落地 / 影响**：被谁采用、超越了什么 baseline

Key conventions：

• Do nothave a separate ## 团队背景介绍 subsection — team informationis only one item * **团队/机构**：<作者>；<机构> <Lab（可选）>；<Lab 研究方向（可选）>, joined with semicolons
• If you do not know a field, omit it(do not fabricate author names / lab names / research directions), butunder no circumstanceswrite a one-sentence summary of the paper's content at the end of a team item (such as "proposes method Y for problem X") — the summary is the responsibility of ## 3 句话总结 , do not squeeze it into the team item
• Do not start * **背景**：… / * **会议级别**：… or other sub-items
• Do notwrite subjective ratings such as "conference level" / "tier-1?" / "best paper?" / "top conference" — the conference level of the paper itself is carried by the doc title / the 3-column table, and the body does not repeat it
• ## 3 句话总结 is thefirstsection after the opening (immediately following the team item), using a 3-item numbered list 1-2-3 to summarize the paper's main ideas, each item 1 sentence
  • Sentence 1 = what problem the paper solves and what method it gives
  • Sentence 2 = core design points / key data
  • Sentence 3 = deployment / key baseline comparison

Why not include a # Reference section / not record author homepages / not record reference implementations?

• Metadata such as the paper title, author homepage, and reference implementation is carried in outline-wiki by the title field (and Gemini easilyfreely fabricatesauthor homepages and reference repository URLs); writing # Reference again will duplicate title ,and Gemini fabricating links is a common source of errors
• The paper link fieldreserves a positionas a placeholder, to be filled in manually by the user in the Outline UI — this both unifies the template for local Markdown / Obsidian and the outline-wiki scenario, and avoids Gemini guessing the URL wrong

Main body sections(fully unified starting from ## 背景与动机 ):

## 背景与动机

* 论文要解决的领域问题（一句话定位：什么场景、什么痛点）
* 现有方法 / 现状的不足（**2–3 条最关键的**，避免展开成 related work）
* 论文核心目标 / 关键约束 / 假设（一两句话）

> 概念 / 术语 / 数据模型 / 系统组件等细节**不在本章展开**——在
> `## 方法设计` 节里随算法 / 协议一并介绍即可；"## 背景与动机"只
> 负责把"问题是什么、为什么需要解决"讲清楚。

## 方法设计

* 总体架构 / 核心思路
* 关键组件 / 数据结构 / 算法（bullet 嵌套 / mermaid 块示意）
* 关键流程 / 协议
* **主要设计点推荐用 `###` 三级标题单独列出**（参见核心原则 #2）

### 自适应内部节点（示例）

* 4 种节点类型按子节点数量动态选择（Node4 / 16 / 48 / 256）
* 关键 insight：节点大小自适应 + 路径压缩 + 延迟扩展叠加
* 如图 N 所示，<在这里插入图> — <1-2 句说明这张图在方法中的角色>

## 代表性实验结果

* 实验设置（一句话：数据集 / baseline / 评测指标，**不展开**）
* **最关键的 2–3 条**关键性能数据（**保留具体数值**，避免"显著提升"这类空话）；
  优先选最能说明问题的 1–2 个图 / 表，不要把全文实验都搬进来

## 业务启示 & 价值

* 工业界落地 / 后续工作 / 同领域影响
* 关键设计取舍 / 实践中的经验教训
* **开源实现**（若无任何链接则整段省略，参见核心原则 #7）
* **相关工作 / 高频引用**（可选表格，3-5 条；无相关工作时整段省略，参见核心原则 #6）

## 局限与未来工作

* 作者自陈的局限（如有，忠实原文）
* 论文未覆盖但明显是下一步的方向

## 启发 / 追问
（仅在 `--focus` 关注点时输出）

For the complete template and figure citation conventions, see assets/prompt-template.md。

Execution principles / boundaries

Core principles

1. Feed the PDF directly to Gemini, do not extract text first

   • Use Part.from_bytes(data=<bytes>, mime_type="application/pdf") for the multimodal path
   • Do not first extract plain text with pdftotext / PyPDF2 / pdfplumber or the like (this loses figures, tables, and formulas)

2. Structured summary, not a retelling

   • Following the outline-style template'smain-line order and namingfor output (opening table → team item → ## 3 句话总结 → background and motivation → method design → representative experimental results → business implications & value → limitations and future work), conciseness first; target character count see assets/prompt-template.md（single source, do not hard-code values in the body)
   • Sections that do not exist may be omitted(e.g., omit "representative experimental results" for purely theoretical papers with no experimental data)
   • Evaluation paper branch: when the paper's main contribution is evaluation / benchmark (i.e., the evaluation itself is the contribution, rather than proposing a new method and then validating it with experiments), ## 方法设计 + ## 代表性实验结果 automatically switch to ## 评测设计 + ## 评测发现—— evaluation paperdoes notoutput ## 方法设计 / ## 代表性实验结果, non-evaluation paperdoes notoutput ## 评测设计 / ## 评测发现, choose one of the two. The determination is done by conditions within the prompt, no flag needed (caliber and the two sections' bullets see assets/prompt-template.md）
   • Key data / values must be retained, avoid speaking in generalities
   • "Representative experimental results" subsection: the 2–3 most critical——just pick the 1–2 figures / tables / key numbers that best illustrate the point; do not bring in all the experimental data / all baseline comparisons from the full text, that would be retelling rather than summarizing
   • ## 方法设计 Within the section: for main design points, it is recommended to use ### level-3 headings to list them separately(e.g., ### 自适应内部节点 / ### 路径压缩与延迟扩展 / ### 二进制可比键), for easy scanning; consistent with the repository documentation style's level-2 subsection convention.Criteria：
     • A single design point ≥ 3 bullets
     • Concepts independent enough to form their own paragraph (e.g., algorithm, data structure, protocol each independent)
     • Needs a mermaid block / key figure
     • A concept the reader must stop to understand
   • With fewer than 2-3 design points, fall back to nested bullets,not mandatory
   • ### The content under the heading still uses bullets rather than pure paragraphs (consistent with the #9 bullet convention)

3. Faithful to the original, no filling in gaps

   • If the paper does not say it, mark "not specified in the original"
   • When citing conclusions, indicate the source (e.g., "see Section 4.2 Experiments")

4. Not forcing all-Chinese: keep English where it should be kept

   • The main output language is still Chinese, but the following five categoriesare kept directly in English, do not force-translate:
     • Academic proper nouns / method names: Transformer, RLHF, LoRA, Mixture-of-Experts, Beam Search
     • Model / product / tool names: Gemini, GPT-4, Claude, PyTorch, vLLM, Hugging Face
     • Library / API / file names:transformers、pip、requirements.txt、<config> field names
     • Algorithm / protocol / standard names: Top-p, TCP, gRPC, REST, IEEE 802.11ax
     • Metrics / abbreviations / proper indicators: BLEU, ROUGE, ACL, GPU, FLOPS, perplexity
   • Criteria: when translation would instead cause ambiguity, lose semantics, or the English is already the standard usage in the field, keep it unconditionally. Mixed Chinese-English is the norm (e.g., "training uses LoRA (low-rank adaptation)")
   • In lists / tables, if an item itself is an English term, keep the entire item in English

5. Key architecture diagrams / conceptual illustrations: (page, fig_num, bbox) reference + inline into the corresponding method context, caption written to the image alt field (v3.2 final)

   quick mode includes images by default + Stage 2 (--refine-figures) enabled by default(2026-07-01) — quick is for humans to read, so it must include high-quality images; Stage 2 uses Gemini to look at images and directly give precise bboxes, ensuring image quality (solves the three long-standing problems of inaccurate boundaries / truncated captions / whitespace above).--no-figures disables image export; unless the user explicitly says "don't use Gemini visual localization / it's too slow / don't want to spend tokens", otherwisedo notadd --no-refine-figures. For detailed specifications see references/figure-processing.md。

   Image selection / layout / alt writing / fallback for images that cannot be handled— these are the truly authoritative rules for Gemini to see, uniformly collected in assets/prompt-template.md §Image reference conventions. This section only covers the meta / process constraints that Gemini cannot see.

   • Images do not include captions(v3.2 final): captions are written to the alt field of the markdown image — ![图 N: <中文翻译+总结>](<url> "=WxH") is the only channel that the outline UI renders as caption text below the image
   • Three-stage format(different forms of the same image reference across the 3 stages):
     • Gemini output: ![图 N: <中文翻译+总结>](PDF p.<页> fig.<N> bbox=<x0,y0,x1,y1>)
     • After script image export processing (quick default): ![图 N: <中文翻译+总结>](figures/figure-pX-fN.png "=WxH")
     • After pushing to outline: ![图 N: <中文翻译+总结>](/api/attachments.redirect?id=<uuid> "=WxH") (via outline-wiki-upload SKILL.md's attachment 3 steps)
   • =WxH automatically injected by the script embed_figure_refs at render_figures_to_pngs after obtaining the exact pixel dimensions
   • fig.N is the Figure number in the paper, corresponding to "Figure N" in the alt text
   • bbox=<x0,y0,x1,y1>(optional,strongly recommended) is the bounding box of the image in the PDF, unit is PDF point (1 point = 1/72 inch), origin at top-left; A4 ≈ 595×842, Letter ≈ 612×792
   • When image export is enabled (quick default),the script uses the bbox to precisely crop the image itself(excluding the caption, which is carried by markdown)
   • If bbox is not written: the script will, on that page, use Figure N: caption to auto-locate,crop to the top of the caption(caption text is retained for markdown)
   • Page numbers follow the actual PDF page numbers (the paper's first page is p.1); do not write "Figure 1 is around page 3"
   • If the paper has no key figures (e.g., a purely theoretical paper),omit entirely— neither a separate section nor inline images

6. Related work / high-frequency citations: as a sub-paragraph of "Business insights & value"

   • No longer an independent ## 高频引用 / Take-aways paragraph, but a bullet sub-paragraph (if any) at the end of ## 业务启示 & 价值 The final bullet sub-section (if any)
   • Table columns:# / paper (author-year + title + conference/journal) / one-sentence core viewpoint
   • Omit the "citation count" column— Gemini finds it hard to estimate accurately, and forcing it would pad the content
   • Sort in descending order of "importance to this paper",3-5 items
   • Key inclusions (in descending order of relevance): baseline methods directly compared in this paper's experiments (those appearing in the performance comparison tables / figures) > foundational works / recent SOTA / direct predecessors of this paper's method
   • Exclude one-off mentions, self-citations, and works with no direct relation to this paper's method
   • For conferences/journals, use the field's conventional abbreviations (NeurIPS / ICML / SIGMOD / VLDB / ICDE / OSDI / TODS / VLDBJ, etc.); when unsure, follow the format used in the paper PDF's reference list
   • Citation detail accuracy(critical, to avoid Gemini fabricating):
     • Conference/journal + yearbased on the reference list in the paper PDF
     • When unsure, fill in only author + year, omitting the conference/journal abbreviation——better to leave it blank than to get it wrong
     • Author name order follows the format in the PDF reference list; do not arbitrarily expand to First M. Last
     • Titles retain the original PDF text (usually English); do not arbitrarily translate or abbreviate
   • When the paper has no introduction / related work section (e.g., short papers, pure experimental reports), omit the entire section

7. Open-source implementation: as a sub-section of "Business implications & value"

   • Place within the ## 业务启示 & 价值 section, do not start a separate ### 开源实现 sub-section
   • LinkExtract only from the paper body / footnotes / reference list, never fabricate; URLs explicitly given in the paper must be retained(do not omit them due to "omission first"), but never supplement with author homepages / GitHub from your own knowledge
   • Format:- **代码仓库**：<URL>（简述：实现语言 / 仓库活跃度）、- **数据集**：...、- **在线 Demo**：...
   • When the link type is unclear (e.g., a project page in a footnote), classify it under the "code repository" line
   • If there are multiple related links, add multiple lines (e.g., paper-website, video, slides)
   • Papercompletely does not mentionany prototype link,omit the entire section(do not write "no open source" or placeholder text)

8. Model selection: for defaults and the "when to explicitly override" guidelines, see the §Model selection subsection (script DEFAULT_MODEL constants in scripts/gemini_paper_summary.py:65). The actually available models are subject to the current Gemini documentation (verify using gemini-api-docs-mcp 's get_current_model ). Why the model names are not relisted here: the model selection table is the SSOT, listed in the §Model selection subsection

   • Result quality > system availability · no automatic fallback(2026-06-21 decision, 2026-06-30 hardening): when the default model encounters 503 UNAVAILABLE / 429 RESOURCE_EXHAUSTED / 5xx and other high-concurrency / rate-limiting errors, uniformly go through 3 retries (2s/4s backoff; 4xx permanent errors are not retried and are thrown directly)——if it still fails, the scriptthrows the error directlyto the upper layer,neversilently degrades to a cheaper model. Reason: different models differ significantly in output quality for the v3.2 prompt template (alt field deviations, table row misalignment, section omissions, etc.); with silent fallback, users cannot perceive that it is caused by model degradation and only see "weird results"—— the quality risk outweighs the convenience. To switch models, use --model <id> Explicitly specified.
   • No end-to-end degradation · the agent must not switch models on its own either(2026-07-01 hardening): the previous item "no fallback" is anend-to-end contract, not just a constraint on the script—the script throws RuntimeError (including model= + status= + three-step suggestion), meaning the task has failed,the agent must noton its own add --model gemini-3.1-flash-lite and other cheap models to rerun. The "use --model <id> to explicitly switch models" suggestion in the script error is for theuser, not an instruction for the agent to execute automatically; the agent must present the original error text + the three-step suggestion faithfully to the user, and whether to switch models is decided by the user. The rationale is the same as for the script not degrading: with a silent model switch the user only sees "weird results", and the quality risk > convenience. (Supplementing the agent behavior blind spot missed after the 2026-06-30 script-side hardening)
   • Final failure error message is clearly actionable(2026-06-30): the thrown RuntimeError must contain model=<id> + status=<code> + type and message, and include a three-step suggestion: retry later / check GEMINI_API_KEY and quota / --model <id> explicitly switch models. The unified policy is implemented in scripts/gemini_paper_summary.py:_gemini_call_with_retry, and both the main call and Stage 2 delegate to it—the SSOT will not drift in policy.

9. Markdown style conventions (repository unified baseline)

   • Always use *，Do notuse - or +for bullet markers (repository unified baseline; other skills in this repository also follow this convention)
   • Use ==text== to highlightkey terms (default color), do not invent colored syntax (Markdown cannot express it)
   • Mermaid blocks block-level：```mermaidjs should be placed outside bullets, not nested inside bullet sub-items; only use the graph series (TD / LR)
   • Use mermaidjsuniformly for Mermaid identifiers: it works directly with standard Markdown renderers, outline-wiki, and Obsidian, with no need to switch manually per target scenario
   • Code block language is required：```bash / ```python / ```json / ```yaml ， Do notwrite an empty language ```
   • Tables vs bullets: use tables for data examples / concept comparisons / field definitions; prefer bullets in other scenarios
   • Blockquotes use > plus a space at the start of the line only when quoting the original words of source material,Do notuse them as containers
   • Line width ≤ 120 characters(aligned with .markdownlint.jsonc MD013)
   • Use ##for section headings: every section heading is always ##(level two),Do notdowngrade to ###; do not write H1 in the body (#), the title is carried by the file name / parent directory
   • Do not write invented syntax：!!! warning / :::tip / <mark> / <details> / decorative emoji placeholders (🎉🎉🎉), etc.Do notlet them appear (Outline does not support them, and the repository .markdownlint.jsonc will also reject them)
   • Math / ranges / formulas: MathJax is prohibited：$...$ / $$...$$ outline-wiki does not render—— switch to plain text / Unicode: range [1, 2^64), superscript 2^64 / 2⁶⁴, operation ≥ ≤ × → ≈

Boundaries

• Only process local PDFs; anything that is not a PDF must first be converted to PDF
• No full-text translation; no multi-paper comparison
• One paper at a time
• Single PDF size recommended ≤ 50 MB (File API hard limit)
• Figures that truly cannot be processed are not included in the summary(2026-06-21 user request): render_figures_to_pngs three-layer positioning (Stage 2 visual_bbox → caption locator → bbox hint) all failwhen all fail, the entire figure is removed from the markdowndelete the entire line，andalso strip the figure number reference in the preceding standalone referring sentence such as "as shown in Figure N" / "see Figure N" / "Figure N shows..." (keep the descriptive text).
  • Trigger scenarios: bbox returned by Stage 2 visual positioning is out of bounds / Gemini full-page call fails / caption locator cannot find the caption / bbox hint width < 50pt, etc.
  • Anti-pattern:Do notkeep ![图 N: ...](PDF p.X fig.N ...) this kind of unreplaced PDF reference string——outline rendering will becomebroken image（![]() protocol outline does not recognize)
  • Script log:INFO: 跳过 N 张图（视觉定位 + caption locator + bbox hint 三层 均失败），已从 markdown 删除对应行 + 呼应句
• Distinguishing figure references in the body text vs real captions(2026-06-21 ART-ICDE'13 p.11 Fig 16 case): The paper body text often contains references like "Figure 16 shows that...", with the line text starting with Figure N starting with. The original find_figure_caption simple regex would be matched by such body-text references, returning the bbox of the body-text block (rather than the real caption), causing the caption locator to treat the entire body paragraph as the figure region. Fix: the line text must be in the form Figure N[.:] + description to count as a caption (Figure 16 shows... in which the number is followed by a space + verb, will be filtered out). At the same time, line length ≤ 120 characters is used as an auxiliary criterion.
• bbox hint sanity check（2026-06-21，Threshold SSOT in references/figure-extraction.md §1): When Stage 1 Gemini freely writes bbox=... , it easily frames the entire body paragraph immediately below the figure (typical case: p.11 Fig 16, hint height ~375pt, actual figure only ~150pt). render_figures_to_pngs Before using the bbox hint fallback, first check the height (250pt threshold + ≥ 50pt only then accept the caption locator replacing the hint). For the specific implementation, see the above references file.

Post-generation self-check (image integrity + boundary damage)

Why： User feedback on 2026-06-21——image integrity, attachment upload failures, and boundary damage are often missed. The self-check is the last line of defense in the generation process, divided into 3 layers (reference integrity / binary integrity / boundary damage).

See references/post-generation-self-check.md： for the full specification. Automation layering, runtime strategy, failure handling, and why visual diff is not done automatically.

Workflow / Steps

A. Agent calls during the session (recommended process)

1. 确认 PDF 存在且可读
2. 确认 GEMINI_API_KEY 已设置；未设置则提示用户去 aistudio.google.com/apikey 申请
3. 确认 google-genai 已安装：python3 -c "import google.genai" 或 pip install -U google-genai
4. 调用 scripts/gemini_paper_summary.py（quick 模式默认带图，--output 视作目录）：
   python3 gemini-paper-summary/scripts/gemini_paper_summary.py \
     --pdf <path> \
     --output <output-dir>  # 产出 <dir>/summary.md + <dir>/figures/*.png
   # 默认护栏：quick 默认带图 + Stage 2 视觉定位（--refine-figures）默认开，保证图质量；
   # 纯文字速读 / 批量场景加 --no-figures；仅在用户明确要求"跳过 Gemini 视觉定位"时加 --no-refine-figures
5. 把生成的 Markdown 总结（含图）呈现给用户
6. 标注所用模型与论文文件名
7. **失败处理（重要）**：若第 4 步脚本抛 RuntimeError（503/429/5xx 重试耗尽），
   agent **不得**自行加 `--model` 换便宜模型重跑——把错误原文 + 三步建议如实
   呈现给用户并停下，换不换模型由用户决定（见 §核心原则 #8 端到端不降级）

You can also call the SDK directly in the session (for API details, see references/api-quickstart.md）。

A'. Figure export (default behavior of quick mode)

quick modeincludes figures by default(no need for --extract-figures; this flag is retained only for backward compatibility)——the script uses pymupdf to crop only the rectangular region of the figure itself(not the full page), and replace the (PDF p.X fig.N [bbox=...]) in Markdown with figures/figure-pX-fN.png。--output is treated as a directory path, --no-figures when disabled falls back to pure Markdown. Directory structure:

<--output 指定的目录>/
├── summary.md              # 自动写到这里
└── figures/
    ├── figure-p1-f1.png    # Figure 1 在第 1 页
    ├── figure-p4-f4.png    # Figure 4 在第 4 页
    ├── figure-p4-f5.png    # Figure 5 在第 4 页（同页多图各自一张）
    └── figure-p5-f6.png    # Figure 6 在第 5 页

summary.md figure references in the form:

- ![图 1：自适应基数树节点](figures/figure-p1-f1.png) — 展示了 ART 如何...
- ![图 4：传统基数树对比](figures/figure-p4-f4.png) — ...

Cropping logic(by priority, from high to low;Stage numbering SSOT in references/figure-extraction.md §1）：

1. Stage 2 (Gemini visual localization)(only when --refine-figures is enabled): render the page as a PNG and send it to Gemini multimodal, and let itvisuallygive each figure's tight bbox + full caption + whether it is a key figure. Highest precision, and it can automatically skip decorative figures/logos/axes/tables. See §Stage 2 below.
2. caption locator(local algorithm, multi-strategy fallback): on that page, use the Figure N: caption to infer the figure region in reverse—
   • Under a two-column layout, determine the figure's column (left / right) based on the caption's x center
   • Figure top detection tries the following three strategies in order:
     1. Bottom of body paragraph: the bottom of the nearest "wide + multi-line" body paragraph above the caption (≥2 lines + width ≥ 60% of column width). Handles the common case where body text is directly above the figure.
     2. Top of annotation: the topmost y0 of all "non-body" text blocks in the same column above the caption (figure annotation / label / node numbering and other "narrow + single-line" blocks).Specifically solves the case where there is only an annotation above the figure and no body text (such as Figure 6 on page 5 of ART-ICDE'13, where above the caption there are only B/F/A/O/R/O node labels + path compression / lazy expansion annotations), avoiding the old version falling back to the page top and framing the entire header.
     3. Page top fallback: when all of the above fail, fall back to the page top (ensuring the figure is framed, but it may include the page header)
3. bbox hint fallback(only as a last resort, poor precision): the script directly uses the bbox=x0,y0,x1,y1 region cropping embedded in the Stage 1 prompt, without caption verification.Threshold and sanity check rulessee references/figure-extraction.md §1
4. Localization failure: skip that figure and print WARN to stderr; references in Markdown remain unchanged

Known edge cases(when there is no Stage 2, caption localization fallback as a last resort):

• Single-column PDF: caption localization works very well
• Two-column PDF: each column is cropped separately, and it will not "eat" the figure in the other column across columns
• Multiple figures adjacent vertically in the same column: the caption of the upper one will be recognized as a "body paragraph" (strategy 1 hits), but if the upper onehas no body paragraph, strategy 2 will use the top of the annotation to avoid cropping incorrectly
• Figure at the top of the page (such as below the title on page 1): there is usually a body paragraph above the caption, and strategy 1 hits; when there is completely no body text, strategy 2 may still frame the page header, requiring Stage 2 refinement

Recommended to always enable --refine-figures(enabled by default): Stage 2 uses Gemini to look at the image and directly give a precise bbox, the above three edge-case problems basically disappear; the only cost is one extra Gemini call per referenced page + ~5-15s latency (cost SSOT see references/full-mode-contract.md §Key Discipline #4 Stage 2 is a dumb-parameter strip).

Stage 2 / size format / thumbnail parameters

When you must read references/figure-processing.md(any case outside the default guardrails):

• The user asks about the specific behavior of Stage 2 / --refine-figures , why it fails, and how failures fall back
• The user passes --no-refine-figures or requests "don't use Gemini visual localization"
• The user changes DPI / --figure-format / --thumbnail / --max-size-kb expected effect
• The user asks about specific failures such as "the image was cropped incorrectly / too much whitespace / incomplete caption"
• The user asks about controlled experiments / Stage 2 cost estimation

Whennotneed to read: daily script tuning (defaults are already guardrailed) → directly python3 gemini_paper_summary.py --pdf X.pdf --output <dir> is enough (includes figures by default).

Key summary(to avoid making wrong decisions from missing a read):

• Stage 2 is on by default（--refine-figures), you must explicitly --no-refine-figures to turn it off—don't add it from impression --no-refine-figures "for speed"
• Algorithm principles, caption discrimination, bbox sanity check see references/figure-extraction.md
• Default parameter source of truth：gemini_paper_summary.py 's parse_args()（--figure-dpi / --figure-format / --figure-quality / --refine-dpi / --thumbnail-width) —— To change defaults, first change the script argparse, then sync this document's table
• DPI: Stage 2 and the final output images are independent of each other (--refine-dpi / --figure-dpi）
• Failure fallback: a single-page Stage 2 failure does not affect other pages, and automatically falls back to the caption locator

Stage 2 controlled experiment

Turn off Stage 2 and visually compare its output with the output when it is enabled:

# 开启 Stage 2(默认)
python3 gemini-paper-summary/scripts/gemini_paper_summary.py \
  --pdf ~/papers/attention.pdf --output ~/out_with_stage2

# 关闭 Stage 2
python3 gemini-paper-summary/scripts/gemini_paper_summary.py \
  --pdf ~/papers/attention.pdf --output ~/out_without_stage2 \
  --no-refine-figures

# 对比每张图
ls -la ~/out_with_stage2/figures/ ~/out_without_stage2/figures/

A''. Output targets and image handling (cross-skill division of labor)

This skill only produces local files——All PNGs captured with figures by default in section A' land locally in the figures/ directory,will notautomatically upload to outline-wiki. Uploading to outline-wiki is not managed by this skill, please follow outline-wiki-upload the 3-step attachment process in SKILL.md (create_attachment → curl upload → Markdown reference /api/attachments.redirect?id=...）。

Decide this skill's parameters based on the output target：

Output target	Figure export (on by default in quick)	Reason
Local Markdown / VS Code / Obsidian	On by default (--no-figures can turn off)	Readers can view it directly locally figures/*.png
Direct upload to outline-wiki	==On by default, don't turn it off==	If turned off (--no-figures), the Markdown  reference is abroken image——outline does not recognize PDF paths / bbox references, there must be a real attachment URL
Text-only quick read / no figures	--no-figures off	PNG not needed, saves time + pymupdf dependency

End-to-end workflow (paper summary → outline-wiki note with figures)：

1. 本 skill：跑 gemini_paper_summary.py --output <dir> → 产出（默认带图）
   <output_dir>/summary.md + <output_dir>/figures/*.png
2. outline-wiki-upload：拿每张 figures/*.png 走 attachment 3 步
   （create_attachment → curl 上传 → 拿到 /api/attachments.redirect?id=...）
3. 用 update_document + editMode=patch + findText 把 summary.md 里的
   ![图 N](figures/figure-pX-fN.png) 替换为
   ![图 N](/api/attachments.redirect?id=<uuid> "=WxH")
4. （可选）删本地 figures/ 目录与 summary.md 的 figures/ 引用条目

Anti-pattern（don'tdo this):

• Write in the outline-wiki document ![图 N](figures/figure-p1-f1.png)——local paths in outline arebroken images(unless you first follow the 3-step attachment process to get a real URL)
• Write in the outline-wiki document ![图 N](PDF p.X fig.Y ...)——same as above
• Assume gemini-paper-summary willautomaticallyupload images to outline-wiki——it will not, this skill stays local only

B. Batch quick scan

1. 列出目录下所有 *.pdf
2. 对每篇并行（或限流并发）调用 gemini_paper_summary.py（批量速读加 `--no-figures` 跳过图，省时省钱）
3. 每篇输出文件名 <paper-stem>.summary.md（`--no-figures` 模式 `--output` 是 .md 文件），放在同目录
4. 结束时汇总哪些论文成功 / 失败

C. Troubleshooting

Symptom	Cause	Resolution
ModuleNotFoundError: google.genai	SDK not installed	pip install --user --break-system-packages google-genai
--extract-figures / quick reports "pymupdf required" with images by default	pymupdf not installed	pip install --user --break-system-packages pymupdf(or --no-figures skip images)
DefaultCredentialsError / api_key not set	Missing GEMINI_API_KEY	export GEMINI_API_KEY=... or .env + direnv
400 INVALID_ARGUMENT + mime type error	PDF corrupted / encrypted / not a PDF header	Verify with file <pdf> ; decrypt or re-download
413 REQUEST_TOO_LARGE	PDF exceeds 50 MB	Upload via File API (see references/api-quickstart.md §Oversized PDFs)
Model 404	Model name misspelled or deprecated	Use gemini-api-docs-mcp 's get_current_model to check currently available models; avoid the deprecated series (gemini-2.5-* etc.)
Ran with a deprecated model (gemini-2.5-*) successfully but nearing shutdown	Model still works but is deprecated	Migrate to gemini-3.5-flash(default) or gemini-3.1-pro-preview; see the "Model selection" section
Output character count far exceeds the target declared in the prompt	Gemini does not strictly follow prompt character-count constraints	First adjust the prompt (specific values in assets/prompt-template.md）/ --focus; then post-process trimming; do not rely on a single prompt constraint
Output empty / truncated	Hit the output token limit (default 65k)	Reducing max_output_tokens will not help——shorten the prompt or switch models
503 UNAVAILABLE / 429 RESOURCE_EXHAUSTED Still fails after 3 retries	Primary model temporarily unavailable / rate limited	No degradation end-to-end——the script throws an error directly (including model name + status + three-step suggestion);upon receiving this error the agent must not switch models and re-run on its own, and must report it faithfully to the user, who decides whether to --model retry explicitly. For the full strategy see §Core Principles #8

Reference examples

Example 1: Single-paper summary

User: "Please ~/papers/attention_is_all_you_need.pdf summarize into Chinese"

Execution：

python3 gemini-paper-summary/scripts/gemini_paper_summary.py \
  --pdf ~/papers/attention_is_all_you_need.pdf \
  --output ~/papers/summaries/attention_is_all_you_need  # 目录：summary.md + figures/*.png

Present the generated summary.md(including images) content to the user, noting the model used (see §Model selection section for the default).

Example 2: With focus points

User: "Summarize ~/papers/diffusion.pdf, focus on the mathematical derivation and sampling efficiency"

Execution：

python3 gemini-paper-summary/scripts/gemini_paper_summary.py \
  --pdf ~/papers/diffusion.pdf \
  --focus "重点关注数学推导的关键步骤和采样效率优化" \
  --output ~/papers/summaries/diffusion  # 目录：summary.md + figures/*.png

The generated summary will emphasize the "Method / Key Results" sections and add a "Insights / Follow-up Questions" section at the end.

Example 3: Batch quick scan

User: "There are 20 PDFs under ~/papers/, give me a 300-word quick read of each"

Execution：

for pdf in ~/papers/*.pdf; do
  python3 gemini-paper-summary/scripts/gemini_paper_summary.py \
    --pdf "$pdf" \
    --model gemini-3.1-flash-lite \
    --focus "300 字内的速览版" \
    --output "${pdf%.pdf}.summary.md"
done

Example 4: Export key architecture diagrams (so Markdown preview can show the images directly)

User: "Summarize ~/papers/attention.pdf, the key architecture diagram must be directly visible"

Execute：

# 一次性：Gemini 总结 + 渲染关键页为 PNG + 替换 Markdown 引用 + 写文件
python3 gemini-paper-summary/scripts/gemini_paper_summary.py \
  --pdf ~/papers/attention.pdf \
  --output ~/papers/summaries/attention  # 默认带图：summary.md + figures/*.png

Output:

~/papers/summaries/attention/
├── summary.md
└── figures/
    ├── figure-01-p1.png
    ├── figure-02-p3.png
    └── figure-03-p5.png

summary.md All image references in become relative paths (figures/figure-01-p1.png), and the images can be viewed directly in any Markdown previewer such as VS Code / Obsidian / GitHub.

Example 5: evaluation / benchmark papers (automatically take the evaluation branch)

User: "Summarize this HELM PDF:~/papers/helm.pdf”

Execute(exactly the same as for a normal paper, no extra parameters needed):

python3 gemini-paper-summary/scripts/gemini_paper_summary.py \
  --pdf ~/papers/helm.pdf \
  --output ~/papers/helm.summary.md

Expected: Gemini determines from the template that this is an evaluation paper, and automatically replaces the two default sections "Method Design + Representative Experimental Results" with "Evaluation Design (evaluation target / benchmark construction / evaluation protocol / scale) + Evaluation Findings (leaderboard conclusions / cross-dimension findings / insights / validity of the evaluation method)", while the remaining sections stay unchanged. For the criteria used to make this determination and the true authoritative definitions of the bullets in the two sections, see assets/prompt-template.md。

D. --full full-document extraction mode (raw-compatible layout)

The complete contract (interface agreement / invocation form / artifact layout / key discipline / key behavior guardrails / anti-patterns / troubleshooting) has been moved to references/full-mode-contract.md。

The 5 key points that are enough to read here：

1. Interface core: a single invocation produces both artifacts at once—the quick summary + the full PDF→Markdown transcription—and the layout is forced to raw-compatible (--output <wiki_root> is treated as the wiki repo root, and the artifacts land in <wiki_root>/raw/papers/<slug>.{quick,full}.md）。Do notuse --full to place artifacts in an arbitrary directory— that is the responsibility of --extract-figures 's responsibilities
2. 2026-06-30 second-round flip: full mode does not produce PNGs, does not run Stage 2, and does not write ![图 N](...) references (self-contained: architecture diagrams are drawn with ```mermaidjs blocks, data charts are converted to tables, and decorative images are omitted). If you want PNGs, run quick mode (includes images by default)
3. Two artifacts must be produced in one call: splitting into two calls will cause the two artifacts to mismatch due to inconsistent prompts; forcibly producing only full also violates the intent of the design
4. Does not consume --refine-figures / --thumbnail: these two flags are dummy parameters in full mode (full does not produce PNGs), and the script prints an INFO notice to stderr
5. --focus behavior: quick mode uses FOCUS_INJECTION (appends a "## Inspiration / Follow-up Questions" section at the end), and full mode uses FOCUS_INJECTION_FULL (injects under the corresponding native PDF section, in the form of ### 用户关注点: <focus> subsections). The script automatically switches based on template="full" , and the contract tests are in eval/evals.json test #2 assertion 2

Other details(the specific parameters of the 5 post-hoc content self-check thresholds, the Output token upper limit SSOT, the full no-rewrite contract, anti-patterns / troubleshooting, etc.)—all go through references/full-mode-contract.md。

Why move the contract to references/ instead of keeping it in SKILL.md?--full mode is a relatively marginal product feature (a v3.x increment, just flipped on 2026-06-30), and its agent trigger frequency is far lower than quick mode. Having SKILL.md directly carry 134 lines would push the word count to the 5000-word limit; the on-demand-loaded references/ after npx distribution is only read in the few scenarios that need --full , and the main flow is unaffected.

Prerequisites

• Python ≥ 3.7(the script follows the repository's Python 3.7 specification)
• google-genai Python SDK(old google-generativeai is deprecated, please use the new package): pip install -U google-genai(for Debian/WSL system Python add --break-system-packages）
• pymupdf（soft dependency, only needed for image export—quick mode includes images by default, so it is needed;--no-figures may be skipped): pip install --user --break-system-packages pymupdf
• GEMINI_API_KEY: After Google AI Studio is created export GEMINI_API_KEY="你的 key"
• Readable PDF file: single file ≤ 50 MB; if you need to process a larger file, use the File API instead (references/api-quickstart.md §Oversized PDF)

Reference documentation

• Gemini API documentation
• google-genai Python SDK
• In-repo yzr-skill-creator/(skill writing conventions)
• In-repo design-doc-edit/(Markdown writing conventions from the same source, line width ≤ 120)