research-paper-summaries
Use when summarizing a research paper or technical report into Obsidian notes. Single-file or split-set workflows with quote, number, and style verification against the PDF.
- License 许可
- MIT
- 最近更新
- 2026-11-03
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- research-paper-summaries
- author
- curator
- license
- MIT
- version
- 1.3.0
- metadata
- { "hermes": { "tags": [ "papers", "summarization", "obsidian", "arxiv", "verification" ], "related_skills": [ "narrative-book-summaries", "oralita-book-sum-obs", "obsidian" ] } }
- platforms
- [ "windows", "linux", "macos" ]
- description
- Use when summarizing a research paper or technical report into Obsidian notes. Single-file or split-set workflows with quote, number, and style verification against the PDF.
02 资源文件 3
- 参考文档references/large-report-splits.md2.4 KB
- 脚本scripts/verify_paper_note.py8.3 KB
- 参考文档templates/paper-study-note.md2.7 KB
03 SKILL.md 正文
Research Paper → Obsidian Study Notes (Single File or Split Set)
When to Use
A research paper, preprint, or technical report the user wants as ONE durable note. A paper is one coherent unit, so the default output is a single study note written by one writer in one pass. This is a different shape from book vaults.
| Source | Skill |
|---|---|
| Research paper / preprint / tech report (one note) | this skill |
| Technical book or multi-file source set (vault) | oralita-book-sum-obs (user-protected) |
| Narrative/argument book (per-chapter vault) | narrative-book-summaries |
Large reports split into sets. Rule confirmed with this user on a 59-page technical report: papers/guides up to about 45 pages with one coherent story get ONE file (a 44-page model report worked as a single ~3,600-word note); large reports (60+ pages, with results/appendices taking roughly half) get a numbered set in a subfolder. The user's preferred split for big technical reports: content files (methods and story) + one tests file + an overview:
00_Overview.md— MOC: lineup table, headline numbers, file map, reading paths.01_...mdand up — content files in the report's own order, method-focused, pointing to the tests file for full numbers.- an evaluation file (for example
04_Evaluation.md) — the tests file: ALL formal evaluation material consolidated (benchmark tables, human-evaluation win rates with representative cases, case studies, appendix test sections).
Present the split as a table (file / covers / source pages) in one clarify when a big report first appears; afterwards apply the convention. Full pattern and worked example: references/large-report-splits.md.
Default landing zone for this user's paper summaries: F:/obsidian_note/oralita_md/daily-paper/ with a kebab-case filename (e.g. deepseek-llm-scaling-with-longtermism.md). Confirm destination and depth the first time a new paper or format comes up; afterwards apply the established convention and state it in the report instead of re-asking. oralita_md and ai-knowledge are separate Obsidian vaults, so cross-vault [[wikilinks]] do not resolve; reference other vaults as plain code paths.
Always-On Rules
- Feasibility first, from inspection. When the user asks "can this be one file / which approach", answer from the actual PDF: page count, a content breakdown (main body vs references vs appendix), a one-file verdict, and the proposed note sections. Never answer from the abstract or from vibes.
- Direct synthesis, no delegation. One file has nothing to parallelize, and even split sets (4–6 files) are written directly for voice consistency. Read the full extract, write the note(s), verify. Delegation stays for chapter-level book vault runs.
- Confirm shape decisions in ONE clarify call the first time a new paper or format comes up: destination, granularity (single file vs split set), and depth. Depth options: study note ~1,800–3,500 words (recommended for this user), brief ~1,000, deep dive ~5,000+.
- Citations: establish whether printed page = PDF page (check page footers in the extraction) and state the convention in the note header. When they differ (journal articles, old scans), compute the offset from the footers (printed = PDF page + k), record it in the note header AND the manifest row, and cite printed pages in the body. Cite pages from the source only; never invent page numbers or quotes.
- Version fidelity: cite the exact version matching the PDF (page-1 stamp reads
arXiv:<id>vN). Summarize what that version says, not the latest revision. - Two-layer format: plain body first, dense appendix last (standing user preference, set after a "mid range" note proved unreadable to them). The body teaches the paper in normal words: what it is via analogy, the 2-4 ideas that matter explained as sentences not formulas, results one line each, the most memorable story told as narrative, why the reader should care. Formulas, full benchmark tables, hyperparameters, and verbatim quotes all move to an
# Appendix: The Dense DetailsH1 at the end of the SAME file, page-cited. Never write a single-density academic-style note; the user cannot learn from it. Body roughly 1,200-2,000 words, appendix carries the rest. - Quotes verbatim and page-attributed; everything else own words. Short quotes only, never long passages.
- Style (standing user preferences): no em-dashes in prose (use commas/colons/parens); en-dashes only in page ranges (
pp. 8–9); English; label your own additions(synthesis); kebab-case filename in oralita_md. - Report real counts at the end: quotes verified, number spot-checks, hash match, and honest limitations (including what was deliberately not summarized).
Workflow
1. Inspect and decide the shape
import pymupdf
doc = pymupdf.open(pdf_path)
print(doc.page_count, len(doc.get_toc())) # page count + section map (get_toc is doc-level, not per page)
print(doc[0].get_text()[:1200]) # title page: version stamp, abstract
If import pymupdf fails, the shell's default python is not the one that carries it: probe the candidate interpreters (where python, the hermes-agent venv python) and run extraction/verification with the interpreter that imports it, rather than reinstalling.
- Sample first/middle/last pages to confirm a real text layer. LaTeX PDFs extract clean; scans with a usable (even noisy) text layer can go straight through with
--ocr-tolerantverification; re-OCR viaocr-and-documentsonly when there is no text layer or it is unusably corrupt. - Build the content breakdown: main body pages (source of the summary), references pages (skip for summary value), appendix pages (substance vs boilerplate).
- Pin section boundaries from page text heads:
get_toc()entries can be one page off; the first line of a page is ground truth. - Present breakdown table + one-file verdict + proposed sections, then stop for the user's destination/depth decisions.
2. Preflight
- Confirm the target path and check the target file does not already exist.
- Workspace outside the vault:
tempfile.gettempdir()/oralita-book/<slug>/, with a lightmanifest.json(source metadata, page ranges, one output row, status). - Nothing except the final note may land in the vault folder.
3. Extract with page markers
with open(out, "w", encoding="utf-8") as f:
for i in range(start - 1, end): # inclusive, 1-based pages
f.write(f"\n\n===== [PDF p. {i+1}] =====\n\n")
f.write(doc[i].get_text())
- Extract the main body (title page through conclusion) as
extract_main.md; extract appendix substance sections separately; inventory remaining appendix pages as first-lines only. - Tables re-order in the text layer: rebuild table values deliberately from the extract cells and spot-check them later; never trust extracted row order.
4. Write the note (direct synthesis)
Follow templates/paper-study-note.md (for split sets, reuse this anatomy per file). Anatomy is two layers:
Plain-language body (the part the user reads):
- Frontmatter:
title,tags,created,source(fit the destination vault's convention; oralita_md uses title/tags/created, addsource). - H1 + source blockquote: full citation, page convention, coverage note, and a pointer that dense detail lives in the appendix.
## What Is This Paper, In Plain Words— the paper via one everyday analogy, no jargon; what the lab did and why.## The <N> Ideas That Matter— one subsection per load-bearing finding, each explained in normal sentences ("the best settings can be calculated, not searched"), page-cited.- Results in one line each, plus at most one Mermaid diagram only for a real relationship.
- The most memorable/human story from the paper told as narrative (e.g. an honesty experiment, a failure analysis).
## Why You Should Care— 2-4 concrete reasons aimed at the reader's own work.
# Appendix: The Dense Details (H1, reference layer):
- Paper map table (section / pp. / what it delivers).
- Formulas in inline code with the original constants (
M_opt = 0.1715 * C^0.5243); full results tables; hyperparameters; pre-training specifics. Limitations and Future Work— the paper's own section; keep it.Practitioner Takeaways— numbered, page-cited.Memorable Quotes— 3–4 verbatim quotes as> "..." (p. N)(the checker parses this exact line shape).
Closing (after the appendix):
## Related— source PDF path, arXiv URL, deliberate cross-note links, related vault paths as code, not wikilinks.- Footer: date, version summarized, note the body+appendix restructure if revising, verification statement.
5. Verify, then promote
Stage the note outside the vault, run the checker, fix findings, then copy into the vault and compare hashes:
python scripts/verify_paper_note.py --note <staged.md> --source <extract.md> --numbers "0.5243,5.8316,89.8" [--scan-all] [--quotes extra.txt] [--allow-links stem1,stem2]
sha256sum <staged.md> <vault.md> # must match
The checker verifies: quotes verbatim (whitespace-normalized, split-quote aware, retried with hyphen line-breaks joined), number checks with variants (trailing punctuation stripped, thousands separators and inter-digit spaces tolerated; optional --scan-all over every token), zero em-dashes, frontmatter keys, balanced fences, wikilink allow-list (--allow-links), word count. For scanned PDFs pass --ocr-tolerant: ligatures map to ASCII and quotes/numbers are re-compared with all whitespace and ASCII hyphens stripped, which survives merged-word layers. Treat a MISS as "verify manually", then repair. Update the manifest row to written with the hash; report only after hash equality.
Pitfalls
- A scratch script named after a stdlib module breaks pymupdf.
inspect.pyshadows stdlibinspect, and pymupdf dies at import with a misleading "partially initialized module / circular import" error. Name scratch scripts with a prefix (pdf_inspect.py). - Split quotes across page breaks. The extraction's own
===== [PDF p. N] =====markers sever every page-crossing quote, and the PDF text layer can also place a floating figure caption between the two halves of a sentence, so a valid quote fails a naive grep. Strip the page markers from the source before substring matching (the bundled checker's split-quote retry also treats caption text between halves as legitimate). Verify both fragments and confirm the only text between them is the caption/footer/page marker; for high-stakes quotes cross-check the arXiv HTML (curl -sL https://arxiv.org/html/<id>vN | grep ...). Never alter or drop the quote to make the check pass. - PDF outline numbers can be off by one. Verify each section's start page against the page's own text, not the
get_toc()entry. - References and boilerplate appendix pages get a page range, not a summary. Summarize appendix pages only where they carry substance; list the rest in the coverage note.
- The number spot-check list is the extraction's tripwire. Keep a list of the note's load-bearing numbers (fitted constants, dataset sizes, benchmark scores) and grep them against the extract; extraction garbling shows up here first.
- Separate Obsidian vaults do not share wikilinks. Inside a note in oralita_md,
[[ai-knowledge/...]]will not resolve. Use plain code paths for cross-vault references. - Hyphenated line breaks break verbatim quote and number checks. PDF text layers split words across lines ("develop-\nment", "Qwen3-\nCoder"); whitespace flattening is not enough. On any MISS, retry with "- " removed (joined form) before concluding anything; for hyphenated tokens also try the spaced form (
Qwen3-Codermatches sourceQwen3- Coder). - Scanned/OCR PDFs need artifact-tolerant quote matching. Old scans (PDF 1.3-era conversions, no TOC, first-page sample full of ligatures like fi/fl or merged words like "Eventhoughwehave") break whitespace normalization: words merge and characters corrupt ("my be" for "may be", "built-ln" for "built-in", "i~s" for "is"). Use
--ocr-tolerant(ligatures to ASCII, then compare with ALL whitespace and ASCII hyphens stripped); pick quotes from clean passages of the text layer and paraphrase anything too corrupt to verify verbatim. A quote you cannot verify against the layer is not quotable. - Scans often do not print their own bibliographic data. When venue/year/DOI are absent from the PDF, complete the citation from the ACM DL / DBLP record, keep the page range as the scan's own footers show it, and mark the completed fields as externally verified in the note footer and manifest. Label non-source body content (e.g. "the language became CLU") with an explicit (external) marker, distinct from (synthesis).
- Number checks need variants. Tokens pick up trailing punctuation ("4.32."); "50,000" may be "50 000" in the extract. Strip trailing punctuation, remove thousands commas, and on the source side remove inter-digit spaces. Spot-check with the SOURCE's spelling, not the note's: math-heavy PDFs use λ, ×, ≈, and U+2212 minus where the note writes lambda/x/~/-; arXiv LaTeX often writes bare
100000/2400where the note adds thousands separators, and prose may spell1.5 million/5 millionwhere the note compresses to 1.5M/5M; math-italic letters live in U+1D400–U+1D7FF (6𝑁𝐷not6ND), so fold that whole block to ASCII (index % 52 maps to A–Za–z) in the normalizer before comparing. Probe the extract for the actual form before declaring a MISS. A full-token scan (--scan-all) catches transcription typos a hand-written list misses. - The zero-em-dash gate covers titles and link lists too. Em-dashes sneak in as "Title — Subtitle" and in Related bullets (wikilink then em-dash then reason); use ":" as the separator in both. Prefer quotes without em-dashes so the gate stays clean; a verbatim quote that contains one keeps its punctuation.
- Cross-paper links: deliberate pairs only, never folder lists. The user removed all generic "More paper summaries in this folder" lists and sibling links: they accumulate without bound. Link two notes only when the connection is specific and substantive (companion study + practitioner guide; a model report + the benchmark paper it headlines), wire it BOTH ways with a one-line reason, and announce it in the report. When patching a promoted note, read it first, keep staged copy and manifest hash in sync, and record the pair in memory so the allow-list stays current.
Reporting
Close with the real numbers: output path and word count, coverage (what was summarized, what was skipped), verification results (quotes checked, numbers checked, hash), and honest limitations. The user values verified counts over optimistic summaries.
Files
templates/paper-study-note.md— fill-in starter with the approved two-layer anatomy (plain body + dense appendix).scripts/verify_paper_note.py— staged-note checker: quotes (hyphen-break and split-quote aware), number checks with variants, em-dash/fence/frontmatter/wikilink gates,--ocr-tolerantfor scanned PDFs (ligature map + whitespace/hyphen-stripped comparison). A safety net, not a substitute for reading the note.references/large-report-splits.md— the numbered-set pattern for big technical reports, with the worked example.
04 同仓库更多 Skills
project-spec-docs
Fill/update project_spec docs (templates, MM handoffs).
penpot-mcp
Penpot MCP: connect, verify, and fix streaming via nginx.
nginx-streaming-proxy
Configure nginx for streaming endpoints (SSE, MCP, WS).
branding-ci
Use for brand/CI identity, style guides, and brand docs.
yuanbao
Yuanbao (元宝) groups: @mention users, query info/members.
slidev
Create and present web-based slidedecks for developers using Slidev with Markdown, Vue components, code highlighting, animations, and interactive features. Use when building technical presentations, conference talks, code walkthroughs, teaching materials, or developer decks.