Deeppapernote

DeepPaperNote

Use this skill when the user wants one outcome:

• read one paper carefully
• generate a high-quality Markdown note
• save the note into an Obsidian-style vault when configured, or into the current workspace when no vault is configured

Chinese trigger examples:

• 给这篇论文生成深度笔记
• 写一篇高质量论文精读笔记
• 把这篇文章整理成 obsidian 笔记
• 读这篇论文并生成 md 笔记

This skill is intentionally narrow:

• it handles one paper at a time
• it does not update daily reading lists
• it does not treat a shallow abstract rewrite as a successful output
• it does not split the public entrypoint into separate setup, troubleshooting, or start commands

Core Standard

The finished note must be more than a summary. It should reconstruct the paper's argument:

• what problem it solves
• how the task is defined
• what data or materials it uses
• how the method or analysis actually works
• what results matter most
• what the paper does not prove
• why the paper is worth keeping

Default writer persona:

• a top-tier researcher or algorithm engineer
• writing a replication-oriented lab note
• not writing a popular-science explanation
• assuming the reader can follow Python, PyTorch, training loops, and evaluation logic

The note must adapt to the paper type. Use the same base structure, but shift emphasis for AI methods, benchmarks, clinical studies, and humanities or social-science papers.

Workflow

Follow this order: 1. resolve the paper identity 2. collect metadata 3. acquire the best available PDF 4. extract canonical raw source text: *_raw_sections.jsonl, *_source_manifest.json, and optional derived *_full_text.md 5. extract structural indexes and PDF assets 6. plan figure placement 7. build the full figure/table decision table 8. build the manifest synthesis bundle 9. have the model read the bundle plus raw sections and plan the note 10. run grounding lint on the note plan before drafting from it 11. have the model write the note 12. lint the final note — if the lint output contains passes_style_gate: false, apply the Style Gate Enforcement rule before advancing to step 13, 14, or 15 13. perform final_quality_review after lint passes 14. perform final_readability_review after the quality review passes 15. write into Obsidian

This is the required workflow for a normal single-paper note request, not a loose suggestion. Unless this skill explicitly marks a stage as optional, required stages must not be silently skipped, reordered into a shortcut, or treated as complete just because a partial artifact already exists.

Global no-short-circuit rule:

• do not stop after only the early stages and present the workflow as finished
• do not treat slowness, inconvenience, or temporary uncertainty as permission to bypass a required stage
• do not replace the declared workflow with an improvised shortcut
• if a required stage fails, only do one of three things:
• retry that stage
• enter a fallback that is explicitly allowed by this skill
• stop and report which stage is blocked and which downstream required stages remain incomplete
• do not describe the whole task as complete while required downstream stages are still pending

Completion-language rule:

• say 笔记已完成 only when the required workflow is actually complete
• say 已生成草稿 when drafting is done but lint, final readability review, or save is still pending
• say 已通过校验 only when lint has actually been run and passed
• say 已保存到 Obsidian only when the write step has actually succeeded
• do not treat lint 已通过 as equivalent to 整篇笔记已经润色完成
• if final readability review is still pending, explicitly say the draft passed script lint but has not finished final language review
• if the workflow stopped early, name the current stage and the still-missing required stages instead of using completion language
• lint is a floor, not the writing objective

Core Execution Contract

SKILL.md plus the generated synthesis_bundle.json must be enough to complete a normal note-generation run. Files under references/ are optional stage-specific deep dives, not a default reading checklist.

Non-negotiable rules:

• evidence-first: draft from the synthesis bundle, source_manifest, raw sections, coverage metadata, explicit note_plan, and inspected paper evidence; never finish from title/abstract/headings alone
• raw-source authority: for ordinary PDFs, *_raw_sections.jsonl and *_source_manifest.json are the canonical reading material; old top-N evidence buckets, truncated section_texts, and candidate_chunks are not model-facing writing inputs
• fail-closed: if a usable PDF or sufficient evidence cannot be obtained after supported acquisition paths, stop and ask for better source material rather than producing a finished degraded note
• model-first: scripts structure evidence, but the model must decide emphasis, contribution, mechanism, limitations, and final Chinese prose
• explicit planning: before drafting, save a compact JSON note_plan such as <note>.plan.json or *_note_plan.json; pass it to scripts/lint_note.py --plan-file ...
• grounding gate: after the JSON note_plan exists, run scripts/lint_grounding.py --note-plan ... --source-manifest ... --bundle-json ... --figure-decisions ...; each substantive section must cite valid section_id values or valid page ranges
• required structure: include the canonical required sections, with 原文摘要翻译 before 一句话总结 and a dedicated 创新点 section immediately after 原文摘要翻译
• abstract translation: when abstract metadata exists, 原文摘要翻译 is a faithful Chinese translation of the original abstract, not a bilingual block and not the model's own summary
• mechanism depth: method, framework, and system papers should include ### 机制流程 under 方法主线, normally as a 3 to 4 step numbered flow with input, operation, and output destination
• placeholder-first figures: plan major figure/table placeholders first; replace one only when identity match and visual usability are both strong; otherwise keep the placeholder
• final quality gates: lint is a floor; after lint passes, first run final_quality_review for analytical depth, then run final_readability_review for language polish, and rerun lint if either review edits the note
• Obsidian-first save: if a vault is configured, treat it as the required target, create the paper-local images/ directory, and never present a fallback/workspace write as a successful vault save

Reference usage policy:

• do not load every reference file by default
• consult references/workflow.md only for detailed data contracts or pipeline debugging
• consult references/evidence-first.md, references/deep-analysis.md, or references/final-writing.md only when the paper is complex or the draft is too shallow
• consult references/figure-placement.md only for ambiguous figure/table placement or image replacement decisions
• consult references/obsidian-format.md only for Markdown, vault, frontmatter, or reference-link formatting details
• consult references/note-quality.md or references/paper-types.md only for final review or domain adaptation
• consult references/metadata-sources.md only when metadata is incomplete, and references/architecture.md only for repository maintenance decisions

Tool and Source Priority

Prefer the strongest available source in this order: 1. local PDF path given by the user 2. local Zotero item and local Zotero attachment if available 3. DOI and publisher metadata 4. arXiv or open-access PDF sources 5. Semantic Scholar or OpenAlex for metadata backfill

Before resolving the paper, actively check Zotero integration: attempt to call the Zotero MCP tool (for example, search for the paper title or list libraries). If the tool responds without error, Zotero is available and the local-library-first rule below applies. If the call fails or the tool is not present, record "Zotero not available" and proceed without it. Do not skip this check — the check itself determines whether local-library-first applies.

Local-library-first rule (applies only when the Zotero check above succeeds):

• search the local Zotero library first using the paper title, DOI, or arXiv id
• If Zotero finds the paper, treat that result as the canonical identity resolution step.
• If the attachment path is not exposed by the integration, use scripts/locate_zotero_attachment.py with the attachment key and filename to find the local PDF under the user's Zotero storage.
• If a local attachment path is available, pass it forward as the preferred PDF source.
• If no local attachment is found, still use the library-resolved metadata to avoid title ambiguity, then fall back to network PDF acquisition only for the file itself.
• Do not let a weaker title-only internet match override a confident local-library hit.

Output Rules

• The default output is a Markdown note written into the Obsidian vault when configured.
• Workspace fallback is allowed only when no Obsidian vault is configured at all.
• Before using workspace fallback, you must ask the user: "I don't see an Obsidian vault configured. Do you have a vault path you'd like me to save this note to? If yes, please provide the path. If no, I'll save to the current workspace instead." Do not write anywhere until the user responds.
• If an Obsidian vault is configured, DeepPaperNote must treat that vault as the required save target rather than silently switching output roots.
• If the configured vault or its paper-local subdirectories are outside the current writable scope, DeepPaperNote must ask the user for permission escalation instead of downgrading to workspace output.
• If the user refuses that permission escalation, DeepPaperNote must clearly report that the note has not been saved into Obsidian yet.
• After such a refusal, DeepPaperNote may save to the workspace only if it asks again and receives explicit user consent for that fallback.
• By default, each paper should be written into its own same-name folder, with the note and images stored together.
• The note should never default to the bare Research/Papers root. Choose a domain folder first.
• Domain selection should be conservative: prefer an existing domain folder in the user's vault when there is a reasonable match; only create a new domain folder when no existing domain fits well.
• A normal note-generation request should complete in one pass: note text, figure placeholder decisions, image materialization when confident, and final save.
• Do not stop after a text-only draft just to ask whether the user wants figures inserted. Finish the figure replacement decision inside the same task unless the user explicitly asked for text only.
• Always create the paper-local images/ folder during final save, even if no high-confidence images were materialized.
• The images/ folder is part of the required save protocol, not an optional cleanup step. If permission is missing, request it; do not skip the directory.
• Do not present a workspace write as if the Obsidian save already succeeded.
• The note must use real heading levels: #, ##, and ###.
• Every final note must start with an Obsidian YAML properties block above the # title heading. Include at least a tags field with a papers/<domain> value and useful aliases; include date, doi, or arxiv_id when known, and omit unavailable fields rather than inventing placeholders.
• ## 核心信息 must be a fixed metadata block only. Use only these fields, in this order, as - 字段名: 值 bullets: 标题, 标题翻译, 作者, 机构, 发表时间, 发表渠道, DOI, arXiv, 论文链接, 代码 / 项目, 数据 / 资源, 论文类型. Omit unavailable fields; put any guide sentence, takeaway, or analysis in 一句话总结 or a later section instead.
• The note should include 原文摘要翻译 near the beginning when abstract metadata is available, before 一句话总结.
• When abstract metadata is available, 原文摘要翻译 should directly translate the original paper abstract into Chinese rather than restating it as your own summary.
• The 原文摘要翻译 section itself should be Chinese-only; do not place English abstract sentences or English paragraph excerpts in that section.
• Do not mix later judgments, innovation summaries, or hindsight explanations into 原文摘要翻译; keep it as the original abstract translated into Chinese.
• The note should include a dedicated 创新点 section immediately after 原文摘要翻译 and before 一句话总结.
• The 创新点 section should not be empty praise. It should enumerate the paper's actual innovations and briefly explain why each one matters.
• High-quality notes should usually contain multiple meaningful ### subheadings in the technical sections when the paper is non-trivial.
• The note must include figure/table placeholders for all major visuals rather than silently skipping them.
• Every kept figure/table placeholder must appear directly under the most relevant analytical section named by its 建议位置; do not collect unresolved placeholders in catch-all sections such as 剩余图表占位 or Remaining figures.
• Every kept figure/table placeholder must use the standard > [!figure] callout format with 建议位置, 放置原因, and 当前状态; do not use ordinary paragraph markers such as [图表占位 | Fig. 1], 图表占位：Table 2, or Figure Placeholder | Fig. 3.
• Real images replace placeholders when they clearly match the corresponding paper figure/table and pass the visual-usability gate.
• When inserting a real image, use the relative_markdown_embed from figure_table_decisions.json; final save with scripts/write_obsidian_note.py --figure-decisions ... copies the image into the paper-local images/ directory.
• When a real image is inserted, render it as the Obsidian embed or Markdown image embed followed immediately by one italic caption line.
• Do not keep a redundant > [!figure] placeholder callout for the same inserted real figure.
• Figure captions in the note must preserve the original paper numbering such as Fig. 1 or Table 2.
• If a figure/table candidate is marked usable and has a real image path, insert the real image. Do not keep a placeholder merely because the figure/table is lower priority, supplemental, already summarized in text, or less central than another inserted figure.
• A kept placeholder is valid only when the image cannot be safely inserted because of a concrete visual defect, missing candidate, unresolved visual review, identity mismatch, contamination, or materialization/copy/write failure.
• For usable_candidate or needs_visual_quality_check / review candidates, make the visual decision only after inspecting the actual candidate image file exposed by the pipeline. Record the concrete visual observation behind the decision. Do not claim manual visual review, visual inspection, or "no reliable insertable candidate" unless the candidate image was actually opened and inspected.
• reject_visual_quality and asset_candidate_missing are fail-closed script states. They do not require manual visual review before keeping a placeholder or skipping insertion; treat them as automatic extraction outcomes unless you explicitly inspect or re-extract the source asset.
• Do not misreport missing candidates as materialization failures: asset_candidate_missing, empty source_image_path, or no independent crop means the placeholder status should say no high-confidence image candidate was extracted. Use materialization/copy/write failure language only after a real chosen image asset failed to copy or write.
• If a candidate crop contains another Figure/Table caption or a second figure body, treat that as contamination or lack of an independent crop; do not insert it and do not call it a clean usable candidate just because the target label is present.
• When figure_table_decisions.json contains insert rows, pass it to scripts/write_obsidian_note.py --figure-decisions ...; the writer must copy those images into the paper-local images/ directory and refuse a note that does not reference the selected image path.
• Do not use soft reasons such as keeping the note light, values already transcribed, future lookup, or convenient back-reference as the standalone 当前状态 for a usable candidate.
• The note must pass a style gate: no mixed Chinese-English prose lines except stable proper nouns or citation metadata.
• The style gate also rejects mechanical term-replacement artifacts such as KV缓存 of, 批量ing, In相关 Researcher, or Single 序列 generation; rewrite the sentence naturally instead of preserving a partially translated phrase.
• Style gate enforcement: when lint_note.py output contains passes_style_gate: false, fix the reported issues and re-run lint. Keep fixing and re-running until lint passes — multiple rounds are normal and expected. Do not decide that any failure is an acceptable exception — proper nouns, math formulas, and citation metadata are not automatic exemptions. Only escalate to the user if the same failures appear unchanged across multiple rounds with no reduction, indicating the model is unable to make further progress independently.
• If PDF or evidence quality is insufficient for a real deep note, fail closed: stop, report the blocked stage, and ask for the better PDF, OCR/source material, or other input needed to continue.

Model-first rule:

• scripts may gather and structure evidence
• scripts must not be the primary mechanism for understanding the paper
• final paper understanding and note writing belong to the model
• before writing the final note, create an explicit short note_plan artifact rather than relying on hidden planning only
• save note_plan as the canonical short JSON file outside the final note body, such as <note>.plan.json or a run-scoped *_note_plan.json
• choose note_plan.paper_type from the synthesis bundle's allowed paper types before drafting; the bundle must not bind writing behavior to a script-selected summary paper type
• keep the same 12 top-level note sections for every paper type, then use contracts_by_paper_type[note_plan.paper_type].section_semantics to interpret the typed meaning of those fixed sections and contracts_by_paper_type[note_plan.paper_type].recommended_subsections to draft note_plan.section_plan
• the note plan must include the analysis coverage fields from the writing contract: central_claims, claim_boundaries, negative_or_limiting_results, mechanism_result_map, comparative_positioning, reuse_takeaways, and followup_questions
• each central_claims item must state the claim, source-grounded supporting evidence, what the evidence actually proves, and what it does not prove
• mechanism_result_map must connect paper-specific mechanisms, design choices, protocols, constructs, or data decisions to the exact result pattern or diagnostic evidence they explain
• comparative_positioning must explain how the paper differs from strong baselines, prior routes, human/clinical references, or obvious alternatives, and why that difference changes interpretation
• followup_questions must be concrete replication, engineering, research, or validity checks that a reader could reuse later
• pass that JSON file to scripts/lint_note.py --plan-file ... when linting the final note; if omitted, lint looks for sibling <note>.plan.json
• pass the same JSON plan to scripts/lint_grounding.py before using it for final drafting; broad references such as synthesis_bundle.evidence.method_evidence are invalid
• interactive sessions may additionally show a compact <note_plan>...</note_plan> block as display-only context, but it does not replace the JSON file
• do not require or expose a long free-form <thinking> block
• for technical papers, prefer replication-grade explanation over high-level summary
• if formulas, objectives, or complexity expressions are central, include the key ones in the final note
• render math as $...$ or $$...$$, not as inline code or fenced code blocks
• before final save, explicitly self-review whether the note contains enough technical detail, key numbers, and any necessary formulas
• during final_quality_review, check the full note against seven questions: whether the central evidence chain is complete, whether key settings and numbers are present, whether mechanisms or protocols are mapped to the result pattern they explain, whether the paper is positioned against strong baselines or alternative routes, whether Discussion/Limitations conclusions are explained mechanistically, whether proven claims are separated from unproven claims, and whether the research, engineering, replication, or validity takeaways are specific enough to reuse
• central quantitative comparisons with three or more systems, settings, tasks, datasets, metrics, or ablation rows should normally be written as compact Markdown tables, followed by interpretation; do not leave the main result table as a loose bullet list when a table would be clearer
• short papers still need a complete deep note: use the saved space to explain protocol details, ablations, limitations, and deployment or replication implications rather than compressing the note into a terse summary
• after final_quality_review passes, reread the full note once more for readability; do not stop at formal compliance only
• in final_readability_review, ordinary English phrase leftovers should usually be rewritten into natural Chinese, while stable proper nouns may remain in English
• do not use final_readability_review to invent new facts, empty filler text, or shallower but safer wording just to satisfy lint

The topic references above can improve difficult runs, but the normal execution path should not depend on reading all of them.

Scripts

Use these bundled scripts rather than rebuilding the workflow from scratch:

• scripts/check_environment.py
• scripts/create_input_record.py
• scripts/locate_zotero_attachment.py
• scripts/resolve_paper.py
• scripts/run_pipeline.py
• scripts/collect_metadata.py
• scripts/fetch_pdf.py
• scripts/extract_source_text.py
• scripts/extract_evidence.py
• scripts/extract_pdf_assets.py
• scripts/plan_figures.py
• scripts/plan_figure_table_decisions.py
• scripts/build_synthesis_bundle.py
• scripts/lint_grounding.py
• scripts/lint_note.py
• scripts/materialize_figure_asset.py
• scripts/write_obsidian_note.py

Preferred usage pattern: 1. if local bibliography integration is available, search the local Zotero library first 2. if the library resolves the paper, inspect child attachments; if needed use scripts/locate_zotero_attachment.py to find the local PDF 3. use scripts/create_input_record.py to materialize a trusted JSON input record 4. run scripts/run_pipeline.py on the JSON record or original exact source to produce the bundle 5. read the bundle yourself 6. write the note in your own words 7. lint the note 8. write it into Obsidian only after lint passes and the final readability review is complete

Python interpreter rule:

• DeepPaperNote requires Python >=3.10.
• Before running repository scripts, check the interpreter version instead of assuming the current shell default is compatible.
• If the default python3 is below 3.10, automatically look for another available interpreter that satisfies the requirement, such as python3.12, python3.11, python3.10, /opt/anaconda3/bin/python3, /opt/homebrew/bin/python3, or /usr/local/bin/python3.
• Use the first compatible interpreter you find and continue with that interpreter for the repository scripts in the current task.
• If no compatible interpreter is available, stop and clearly tell the user which interpreter was found, which version it reported, and that DeepPaperNote requires Python >=3.10.

Troubleshooting rule:

• use scripts/check_environment.py only when a concrete dependency or integration question is blocking execution
• explain required dependencies, optional enhancements, and downgrade behavior directly rather than redirecting the skill into a separate troubleshooting workflow
• do not feature environment inspection as a public pseudo-command surface

Current status:

• the single-paper deterministic core pipeline is implemented as an MVP
• scripts/run_pipeline.py now defaults to building a model-facing synthesis bundle
• scripts/write_obsidian_note.py can write the final note into a target vault
• patch the scripts rather than replacing the workflow ad hoc

Limits

• If the paper identity is ambiguous, confirm before writing.
• If the PDF is unavailable after all supported acquisition paths have been tried, stop and report what input is needed; do not produce a degraded, provisional, or abstract-only note as the finished output. Supported acquisition paths include local PDF, Zotero attachment, metadata pdf_url, direct PDF URL, arXiv/open-access sources, publisher PDF if accessible, DOI enrichment, and any other current fetch path implemented by the workflow.
• Placeholder-first figure planning is required; image extraction is optional and must never reduce textual coverage.

DeepPaperNote Agent Guide

Repository Purpose

DeepPaperNote is:

• a single-skill repository
• designed for deep reading of one paper at a time
• intended to support both Claude Code and Codex
• focused on producing a high-quality Obsidian-oriented paper note

DeepPaperNote is not:

• a multi-paper review framework
• a shallow summary generator

Canonical Sources

Use the following source-of-truth hierarchy when working in this repository:

• root SKILL.md is the canonical workflow definition
• scripts/ and references/ are part of the reusable core
• README.md and README.zh-CN.md are user-facing documentation, not the canonical workflow
• agents/openai.yaml is the Codex adapter layer; the root SKILL.md is the Claude Code skill entrypoint

Adapter layers should stay thin and should not redefine the workflow independently.

Non-Negotiable Product Invariants

Future changes should preserve these product invariants:

• DeepPaperNote handles one paper at a time
• the workflow remains evidence-first
• required stages must not be silently skipped
• weak evidence should fail closed rather than being presented as a full deep read
• figure and table placeholder-first handling remains required
• lint plus final readability review remain required before completion
• Obsidian-first save semantics remain intact
• the paper-local images/ directory remains part of the save protocol
• scripts remain deterministic support tools, while paper understanding and final note writing remain model-led

Repository Structure

The repository is layered as follows:

• SKILL.md is the canonical workflow definition and the skill entrypoint for both Claude Code and other agents
• CLAUDE.md provides Claude Code project-level guidance and includes AGENTS.md via @AGENTS.md
• references/ stores durable workflow and writing guidance
• scripts/ implements the deterministic pipeline and support utilities
• agents/openai.yaml is the Codex adapter
• README.md and README.zh-CN.md are user-facing documentation

Environment and Onboarding Boundary

• user installation, configuration, and onboarding belong primarily in README.md and README.zh-CN.md
• scripts/check_environment.py is a maintenance and troubleshooting utility
• DeepPaperNote should not reintroduce a separate public doctor, setup, or start skill surface

Working Commands

Common commands for local validation and maintenance:

• install the core runtime dependency with python3 -m pip install PyMuPDF
• install the local development environment with python3 -m pip install -e '.[dev]'
• run the test suite with python3 -m pytest -q
• when checking environment-related problems, use python3 scripts/check_environment.py

Verification Expectations

When making meaningful changes:

• run python3 -m pytest -q
• confirm adapters remain aligned with the root SKILL.md
• confirm no wrapper introduces a second conflicting workflow
• confirm legacy public pseudo-commands are not reintroduced
• if packaging files are touched, keep them syntactically valid

{{title}}

核心信息

• 标题:
• 标题翻译:
• 作者:
• 机构:
• 发表时间:
• 发表渠道:
• DOI:
• arXiv:
• 论文链接:
• 代码 / 项目:
• 数据 / 资源:
• 论文类型:

原文摘要翻译

创新点

一句话总结

研究问题

数据与任务定义

方法主线

机制流程

关键结果

深度分析

局限

我的笔记

引用

Changelog

This file tracks notable release-level changes to DeepPaperNote.

It is not intended to record every small edit, wording tweak, or internal refactor. Add an entry here when the project meaningfully changes for users, for example:

• a new capability is added
• a new workflow becomes officially supported
• a new integration or interface is introduced
• a release changes how users install, run, or rely on the skill

Unreleased

No unreleased user-facing changes yet.

v2.0.0

• Strengthened note-depth planning with source-grounded central claims, claim boundaries, limiting-result coverage, mechanism-to-result mapping, comparative positioning, reusable takeaways, follow-up questions, and a separate final analytical quality review before readability polish.
• Expanded benchmark/dataset and clinical paper guidance to cover sample statistics, data access, privacy constraints, and reproducibility boundaries when the paper reports them.

v1.1.1

Small patch release that fixes existing logic gaps.

Fixed

• Tightened final-note linting so retained figure/table placeholders must use the standard [!figure] callout format.
• Strengthened table crop quality checks so crops contaminated by running prose or other figure/table captions fail closed.

Notes

• This remains a stable release.
• The release asset continues to ship as a clean manually installable DeepPaperNote.zip.

v1.1.0

Minor stable release with a major figure/table extraction quality upgrade.

Added

• Added figure-level PDF asset extraction that renders caption-anchored page regions instead of relying only on raw xref image objects.
• Added richer figure_assets metadata for extracted figures and tables, including labels, captions, extraction kind, and visual quality signals.
• Added visual quality gates so weak crops can fail closed and remain placeholders instead of being treated as insertion-ready images.
• Added figure_assets to the synthesis bundle so model-side review can inspect richer figure/table candidates.
• Added regression tests for figure asset candidates, placeholder-first planning, label normalization, and visual quality rejection.

Changed

• Improved extraction for complete figures, vector-heavy papers, fragmented LaTeX tables, and caption-on-bottom tables.
• Preserved DeepPaperNote's placeholder-first behavior: extracted figure assets are exposed as candidates, not automatic note insertions.
• Strengthened figure-placement and final-writing guidance around visual quality review and candidate handling.

Contributors

• Incorporated the figure-level extraction work from PR #1 by KuangjuX, with follow-up changes to keep insertion semantics placeholder-first.

Notes

• This remains a stable release.
• The release asset continues to ship as a clean manually installable DeepPaperNote.zip.

v1.0.1

Patch release after v1.0.0.

Changed

• Added YAML frontmatter and wikilink rules for Obsidian-native features.
• Fixed lint_note.py compatibility with YAML frontmatter.
• Added tests for frontmatter stripping and frontmatter-aware lint compatibility.
• Fixed wikilink target resolution with a lookup-first, fail-closed approach.
• Removed unused image assets that were no longer referenced by the README files.

Notes

• This remains a stable release.
• The release asset continues to ship as a clean manually installable DeepPaperNote.zip.

v1.0.0

First stable release of DeepPaperNote.

Changed

• Reframed DeepPaperNote as a pure cross-agent skill for Claude Code, Codex, Cursor, Copilot, Gemini CLI, and other Agent Skills-compatible environments.
• Kept the root SKILL.md as the single canonical skill entrypoint.
• Updated installation guidance for npx skills add 917Dhj/DeepPaperNote -a codex and npx skills add 917Dhj/DeepPaperNote -a claude-code.
• Removed experimental onboarding/setup pseudo-surfaces and the temporary Claude plugin wrapper structure.
• Added AGENTS.md and CLAUDE.md for repo-level agent guidance.
• Added explicit Python >=3.10 interpreter guidance for agents running bundled scripts.

Preserved

• The evidence-first deep-reading pipeline.
• Obsidian-first output behavior.
• Figure/table placeholder-first policy.
• Lint gate and final readability review.

v0.3.2-alpha

Fifth public alpha release of DeepPaperNote.

Changed

• Strengthened local_pdf -> enrich_metadata so Zotero-style attachment filenames no longer dominate metadata resolution.
• Added local PDF metadata hints that prefer embedded PDF title, DOI, arXiv identifiers, and first-page title signals before falling back to cleaned filenames.
• Added local-PDF-only title correction so high-confidence external matches can replace noisy attachment-style titles without changing the global merge policy.
• Tightened candidate scoring so published venue/DOI records are preferred over preprint-style matches when both are available.
• Normalized common PDF ligatures such as fi and fl during text extraction so titles and other extracted strings are cleaner and more stable.

Packaging

• Rebuilt the release zip from the latest main branch state for v0.3.2-alpha.

Notes

• This is still an alpha release.
• Chinese remains the only fully supported output language.
• Figure replacement is still conservative and placeholder-first when image confidence is insufficient.

v0.3.1-alpha

Fourth public alpha release of DeepPaperNote.

Changed

• Changed the default Obsidian paper root from 20_Research/Papers to Research/Papers.
• Aligned runtime path resolution, save behavior, and tests with the new default paper root so new notes land in the updated location consistently.

Packaging

• Rebuilt the release zip from the latest main branch state for v0.3.1-alpha.

Notes

• This is still an alpha release.
• Chinese remains the only fully supported output language.
• Figure replacement is still conservative and placeholder-first when image confidence is insufficient.

v0.3.0-alpha

Third public alpha release of DeepPaperNote.

Changed

• Added a dedicated 创新点 section near the front of the note and strengthened the front-matter contract.
• Added explicit ### 机制流程 guidance for method and system papers so the execution chain is reconstructed more clearly.
• Strengthened ablation handling so notes are more likely to capture failed settings, weaker variants, and trade-offs rather than only best-case results.
• Renamed the opening abstract block to 原文摘要翻译 and tightened the contract so it is treated as a Chinese translation of the original abstract rather than a newly written summary.
• Tightened the 核心信息 block into a fixed metadata zone and explicitly forbade analysis or judgment from leaking into it.
• Added a required final_readability_review stage after script lint to improve fluency, remove stiff phrasing, and reduce unnecessary English leftovers.
• Added a dedicated math syntax gate to catch common Obsidian / MathJax rendering failures before final save.
• Strengthened the overall workflow contract so the model is less likely to silently skip required stages, downgrade output behavior, or claim completion too early.
• Tightened Obsidian save rules and fixed the duplicated paper-slug directory bug during note writing.

Packaging

• Added a release zip asset for v0.3.0-alpha and narrowed the release package to omit README files, license/changelog docs, and showcase media.

Notes

• This is still an alpha release.
• Chinese remains the only fully supported output language.
• Figure replacement is still conservative and placeholder-first when image confidence is insufficient.

v0.2.0-alpha

Second public alpha release of DeepPaperNote.

Changed

• Strengthened the note-writing contract so technical papers are pushed closer to replication-oriented reading notes rather than polished summary rewrites.
• Added explicit short note planning before final note generation.
• Added equation-aware output guidance so key formulas can be preserved in LaTeX when they are central to understanding the method.
• Added stricter final self-review requirements for key numbers, method explanation depth, and technical completeness.
• Added stronger formatting checks for suspicious mid-sentence line breaks and math accidentally rendered as code.
• Updated the abstract section contract to keep both the original abstract and a Chinese translation.
• Made the Chinese README the default GitHub homepage and clarified that Chinese is currently the only fully supported note language.

Documentation

• Split the English README into README.en.md while keeping the Chinese README as the default repository homepage.
• Updated homepage messaging to better emphasize replication-oriented technical note quality.

Notes

• This is still an alpha release.
• Chinese remains the only fully supported output language at this stage.
• High-confidence figure replacement remains conservative; placeholder-first behavior is still preferred when image certainty is low.

v0.1.0-alpha

First public alpha release of DeepPaperNote.

Added

• Initial public Codex skill workflow for generating a deep-reading note from one paper.
• Model-facing synthesis bundle pipeline with deterministic evidence gathering.
• Placeholder-first figure planning and Obsidian folder-per-paper output structure.
• Zotero-first helper workflow for local-library-first paper resolution.
• Workspace fallback output when no Obsidian vault is configured.
• OCR fallback for low-text PDF pages.
• Domain-aware note routing that prefers existing vault domains before creating new ones.
• Minimal automated test suite and GitHub Actions CI.
• Setup-assistant entry points such as /deeppapernote doctor and /deeppapernote start.

Documentation

• Bilingual project README (README.md and README.zh-CN.md).
• MIT license and initial project metadata via pyproject.toml.

Changed

• Standardized figure placeholders to a stable callout format.
• Shifted the architecture toward model-first paper understanding.
• Moved image output into paper-local images/ folders.

Notes

• This is an alpha release.
• Figure replacement quality still depends on extraction quality and semantic matching confidence.
• Some environments may expose different python3 interpreters across sessions; doctor now reports the active interpreter explicitly.

@AGENTS.md

Claude Code Integration

The root SKILL.md is both the canonical workflow definition and the Claude Code skill entrypoint. There is no separate Claude Code wrapper — SKILL.md is loaded directly when the skill is invoked.

• Do not fork or restate the DeepPaperNote workflow in any Claude-only file.
• All workflow logic stays in the root SKILL.md.

Skill Invocation

End users running Claude Code invoke the skill with natural language or the /deeppapernote slash command. Recognized trigger examples:

• 给这篇论文生成深度笔记
• 写一篇高质量论文精读笔记
• 把这篇文章整理成 obsidian 笔记
• /deeppapernote <paper title, DOI, arXiv ID, or local PDF path>

<div align="center">

DeepPaperNote

Turn a complex paper into an Obsidian note you will actually want to keep.

English | 简体中文

        

</div>


Do you often run into this situation: you want to study a classic paper carefully, but the hardest part is no longer reading it — it is turning that reading into usable notes? The real time sink usually looks like this:

• jumping back and forth between PDFs, Zotero, web pages, and your note app
• manually organizing metadata, abstracts, figures, and the method backbone
• understanding part of the paper, but still spending a long time turning that understanding into structured notes
• ending up with a note that looks complete but is not something you actually want to revisit later

DeepPaperNote is built for exactly that layer of repetitive, mechanical, but very expensive work. It takes over the gathering, structuring, figure placement, and note production work so you can keep your attention on actual thinking.

DeepPaperNote is a skill for deep paper reading. The same core skill can be used from Claude Code and Codex. It cares about a harder set of questions:

• What problem is this paper actually solving?
• How does the mechanism really work?
• Are the key equations, experiments, and figure context preserved?
• Does the final note become something worth keeping in your long-term knowledge base?

[!tip]

If you already have an Obsidian or Zotero workflow, DeepPaperNote automates the most tedious parts of evidence gathering, structuring, and note production.

🎯 What problems does it solve?

!DeepPaperNote usage example

In one sentence:

DeepPaperNote is a paper-reading-note workflow, not a paper-summary generator.

✨ How does it do that?

DeepPaperNote does not achieve higher note quality by simply rewriting the abstract in smoother prose. It raises note quality through a few workflow rules:

👀 Who It Is For

<table> <tr> <td valign="top" width="33%"> <strong>👓 People studying hard or classic papers closely</strong><br><br> You are not reading papers just to skim the abstract and move on. You are reading papers with dense formulas, complex architectures, or layered experiments, and you want a note that actually untangles the method backbone, key results, and figure structure. </td> <td valign="top" width="33%"> <strong>🗂️ People building a long-term Obsidian knowledge base</strong><br><br> You want paper notes to remain searchable, linkable, and reusable over time. DeepPaperNote files papers into a more suitable place based on their domain, then creates the Markdown note and <code>images/</code> folder so the result fits a real knowledge base. </td> <td valign="top" width="33%"> <strong>🤖 People who want more than AI summaries</strong><br><br> You are not looking for a polished-looking recap. You want to know what the paper actually solves, how the method works, which results matter, and where the real limitations or misunderstandings are. DeepPaperNote aims closer to a research note than a summary generator. </td> </tr> </table>

🚀 Quick Start

1) Install DeepPaperNote into your agent skill directory

DeepPaperNote supports both Claude Code and Codex.

npx Skills (Recommended)

For most users, install directly with npx. Run in your terminal:

npx skills add 917Dhj/DeepPaperNote

This command installs to the shared .agents/skills directory by default. Skills in that directory can be recognized and used by Codex and most other agents. If you also want to use DeepPaperNote in Claude Code, choose Claude Code in the Additional agents prompt.

You can also install for a specific agent directly:

npx skills add 917Dhj/DeepPaperNote -a codex
npx skills add 917Dhj/DeepPaperNote -a claude-code

Update

To update an existing DeepPaperNote installation, rerun the same command; it will replace the copy in the target skill directory.

Manual install

If you prefer the manual path, download the latest release zip and extract it.

For Codex, place the extracted DeepPaperNote folder into:

~/.codex/skills/DeepPaperNote

For Claude Code, place the extracted DeepPaperNote folder into:

~/.claude/skills/DeepPaperNote

You can also clone the source repository directly:

git clone https://github.com/917Dhj/DeepPaperNote.git ~/.codex/skills/DeepPaperNote
git clone https://github.com/917Dhj/DeepPaperNote.git ~/.claude/skills/DeepPaperNote

After installation, restart your agent so the skill is loaded.

2) Install the core Python dependency

Before your first real paper run, install the most important Python dependency:

python3 -m pip install PyMuPDF

Why this step matters:

• DeepPaperNote reads PDFs through PyMuPDF
• if PyMuPDF is missing, the core PDF extraction pipeline will not work

3) Start using it immediately

After that, just hand a paper to the agent. A title, DOI, URL, arXiv ID, or local PDF all work. Prompts like these are enough:

Typical prompts:

• Generate a deep-reading note for this paper: Attention Is All You Need
• Turn this paper into an Obsidian note: https://arxiv.org/abs/1706.03762
• Read this PDF and produce a Markdown note with figure context
• Use DeepPaperNote on this paper: 10.48550/arXiv.1706.03762

By default, DeepPaperNote writes the note in Chinese. At the moment, Chinese is the only note language that can fully benefit from the skill's current writing and linting rules. If you need English notes, please stay tuned for a future update.

By default, DeepPaperNote will:

• resolve the paper identity
• gather metadata and PDF evidence
• insert figures directly when usable; keep placeholders only for real failures such as missing candidates, visual defects, or copy errors
• generate the final Markdown note
• save it into Obsidian when configured, or ask for your vault path before falling back to the current workspace's output folder

4) You do not need perfect setup on day one

You can try DeepPaperNote even if you have not finished configuring Obsidian, Zotero, or OCR yet.

If you want the Python dependencies for local development:

python3 -m pip install -e '.[dev]'

If you want to check the environment first, you can also ask the agent with short requests such as:

• Please check whether DeepPaperNote is ready on this machine
• 查看 deeppapernote 的可用情况
• deeppapernote 有什么功能

🔧 Configuration (works out of the box, improves with setup)

Once you have PyMuPDF installed, you're ready to start generating notes with DeepPaperNote right away. The configurations outlined below are extensions of the core features, designed to help you seamlessly integrate the generated notes into your actual research workflow.

• if no Obsidian vault is configured, it can still save notes under the current workspace's fallback output folder, DeepPaperNote_output by default
• if you want an Obsidian-native long-term workflow, you should configure your vault path
• everything else in this section is optional and improves specific workflows

Core setup: point DeepPaperNote to your Obsidian vault

The cleanest setup is:

export DEEPPAPERNOTE_OBSIDIAN_VAULT="/absolute/path/to/your/Obsidian_Documents"

If you want your agent to keep seeing this default configuration in future terminal sessions:

• on macOS / Linux, add it to your shell config such as ~/.zshrc, then reload your shell (or restart the agent):

echo 'export DEEPPAPERNOTE_OBSIDIAN_VAULT="/absolute/path/to/your/Obsidian_Documents"' >> ~/.zshrc
source ~/.zshrc

• on Windows PowerShell, persist it as a user environment variable and then restart your terminal:

setx DEEPPAPERNOTE_OBSIDIAN_VAULT "C:\Users\YourName\Documents\Obsidian_Documents"

<details> <summary><strong>🛠️ Show advanced configuration (directories / Zotero / Semantic Scholar / OCR)</strong></summary>

Directory-related settings

If you want to customize paper output paths or intermediate artifact paths:

export DEEPPAPERNOTE_PAPERS_DIR="Research/Papers"
export DEEPPAPERNOTE_OUTPUT_DIR="tmp/DeepPaperNote"

If you want your agent to keep using these values by default:

• on macOS / Linux, add them to your ~/.zshrc as well:

echo 'export DEEPPAPERNOTE_PAPERS_DIR="Research/Papers"' >> ~/.zshrc
source ~/.zshrc

• on Windows PowerShell, persist them as user environment variables:

setx DEEPPAPERNOTE_PAPERS_DIR "Research/Papers"

Why the optional path settings can help:

• DEEPPAPERNOTE_PAPERS_DIR

Useful if your vault does not store papers under Research/Papers, or if you want DeepPaperNote to fit an existing folder convention without extra manual moves.

• DEEPPAPERNOTE_OUTPUT_DIR

Useful if you want all intermediate artifacts in a predictable location for debugging, cleanup, or experimentation.

Domain routing is controlled by the editable taxonomy in references/domain_rules.yaml. DeepPaperNote checks application domains before fallback method domains, and it only reuses an existing first-level Obsidian folder when the title or abstract provides conservative evidence for that folder.

Optional: Zotero for local-library-first workflows

DeepPaperNote can work without Zotero. But if you want the agent to search your local Zotero library first, you should expose a Zotero integration that your agent runtime can actually use.

This is most worth setting up if you already use Zotero as your main paper-management or reading workflow.

Recommended ways to think about it:

Why it matters:

• local Zotero hits are usually the best identity anchor
• if the paper is already in your local Zotero library, DeepPaperNote can often reuse local records and attachments instead of searching and downloading again, which also tends to make note generation faster
• the agent can prefer your local paper library before internet search
• local attachments can reduce wrong-title matches
• it is especially helpful when you already curate papers in Zotero and do not want DeepPaperNote to rediscover the same paper from weaker web matches
• it also improves reliability for published papers whose title may collide with preprints, workshop versions, or mirrored pages

Important note:

• DeepPaperNote does not require one specific Zotero integration
• for DeepPaperNote, the key capability is that the agent can search Zotero items, inspect metadata, and ideally read local PDF attachments
• the two routes above are not always plug-and-play, so stable use may still require some adaptation on your side

Optional: Semantic Scholar API key

This is not required, but if you have a Semantic Scholar API key you can expose it as:

export DEEPPAPERNOTE_SEMANTIC_SCHOLAR_API_KEY="your_api_key"

Why it can help:

• metadata lookup is usually more stable when Semantic Scholar is available
• title-based paper resolution can be more reliable for hard-to-match papers
• author, venue, and abstract backfill may be more complete in some cases
• it gives DeepPaperNote one more strong source before falling back to weaker guesses

Optional: OCR tooling for scanned PDFs

OCR is not required for many modern PDFs. But it becomes useful when a paper is:

• a scanned PDF
• an image-based PDF with poor embedded text
• an older paper where direct text extraction is incomplete

Why DeepPaperNote uses OCR:

• to recover page text when direct PDF extraction is too weak
• to preserve method and results evidence that would otherwise be lost
• to improve page-level context around figures and captions

Current OCR logic in DeepPaperNote:

• DeepPaperNote first tries normal PDF text extraction with PyMuPDF
• for each page, it counts how much searchable text was extracted
• if a page has too little extracted text, it becomes an OCR fallback candidate
• OCR is then applied to that page only
• the recovered OCR text is mainly used as page context for later evidence handling and figure/page semantic matching

Important scope note:

• OCR is currently a page-text fallback
• it is not the primary extraction path for all PDFs
• it is not used as a replacement for model-side understanding
• it is not used to understand images directly

Without OCR, DeepPaperNote still works well on normal digital PDFs. For scanned or low-quality PDFs, if extracted evidence is too weak for a real deep note, the workflow should ask for OCR or a better source rather than finishing a lower-quality output.

Required software and packages for OCR:

Install on macOS:

brew install tesseract
python3 -m pip install --user pytesseract Pillow

Install on Windows:

winget install UB-Mannheim.TesseractOCR
py -m pip install --user pytesseract Pillow

If winget is unavailable, install Tesseract OCR manually and then run:

py -m pip install --user pytesseract Pillow

Quick verification:

tesseract --version
python3 -c "import pytesseract, PIL; print('python_ok')"
python3 -c "import pytesseract; print(pytesseract.get_tesseract_version())"

</details>

📝 Changelog Preview

For release-level updates, see CHANGELOG.md.

⚙️ Workflow

The default path is:

1. resolve the paper identity 2. collect metadata 3. fetch the best available PDF 4. extract canonical raw source text and a source manifest 5. extract structural indexes and PDF image assets 6. plan figure placement 7. build the full figure/table decision table 8. build a manifest synthesis bundle 9. let the model read the raw source records and plan the note 10. run grounding lint on the plan 11. let the model write the note 12. lint the final note 13. perform the final analytical quality review 14. perform the final readability review 15. write into Obsidian

Core principle:

• scripts gather source text, metadata, assets, and quality signals
• the model understands and writes
• linting, final quality review, and final readability review are the final gates before saving

Related docs:

• Workflow
• Architecture
• Model Synthesis

🖼️ Figure Strategy

DeepPaperNote treats figure insertion and placeholder decisions as two separate questions.

When a figure or table candidate is usable — the crop is visually clean, it matches the intended figure, and the image path is valid — it is inserted into the note as a real image embed.

Placeholders are reserved for real problems:

• no usable candidate was found
• the crop has visual defects, truncation, or contamination
• the image cannot be confirmed to match the intended figure
• the file copy or write step failed

When a placeholder is needed, DeepPaperNote keeps the semantic position, explanation, and context so the note structure stays intact and you know which figure belonged there:

> [!figure] Fig. 3 Data Distribution and Quality Evaluation
> Suggested location: Data and task definition
> Why here: This figure combines sample composition, conversation-length statistics, and expert quality checks, making it one of the most important figures for understanding the data boundaries.
> Current status: Placeholder kept; current extraction only recovered partial subpanels and cannot yet reconstruct the full original figure reliably.

See figure placement rules.

✅ Quality Bar

DeepPaperNote has a concrete bar for what counts as a usable note.

The final note should:

• clearly separate the research question and the task definition
• explain the real method or analytical pipeline
• capture the numbers that actually matter
• cover key experimental settings and conditions
• distinguish what the evidence proves from what it does not prove
• point out where the paper is easiest to misread
• include at least one honest limitation with bounded conclusions
• include at least one reusable research or engineering takeaway
• use real heading structure: #, ##, ###
• avoid mixed Chinese-English prose in the body

If the evidence is not strong enough, the workflow should degrade gracefully or fail instead of pretending that a deep reading note is complete.

Related docs:

• Evidence First
• Deep Analysis
• Note Quality
• Final Writing
• Figure Placement

🗂️ Repository Layout

DeepPaperNote/
├── SKILL.md
├── README.md
├── README.zh-CN.md
├── CHANGELOG.md
├── LICENSE
├── pyproject.toml
├── agents/
│   └── openai.yaml
├── assets/
│   ├── hero-academic.svg
│   ├── usage-example.png
│   └── note_template.md
├── references/
│   ├── architecture.md
│   ├── deep-analysis.md
│   ├── domain_rules.yaml
│   ├── evidence-first.md
│   ├── figure-placement.md
│   ├── final-writing.md
│   ├── metadata-sources.md
│   ├── model-synthesis.md
│   ├── note-quality.md
│   ├── obsidian-format.md
│   ├── paper-types.md
│   └── workflow.md
└── scripts/
    ├── build_synthesis_bundle.py
    ├── check_environment.py
    ├── citation_links.py
    ├── collect_metadata.py
    ├── common.py
    ├── contracts.py
    ├── create_input_record.py
    ├── extract_evidence.py
    ├── extract_pdf_assets.py
    ├── extract_source_text.py
    ├── fetch_pdf.py
    ├── lint_grounding.py
    ├── lint_note.py
    ├── locate_zotero_attachment.py
    ├── materialize_figure_asset.py
    ├── plan_figure_table_decisions.py
    ├── plan_figures.py
    ├── resolve_paper.py
    ├── run_pipeline.py
    └── write_obsidian_note.py

🧰 Recommended Environment

🧭 Design Principles

The core judgment behind DeepPaperNote is simple:

1. A good paper note is not just a paragraph-style summary.

A useful note should help you understand:

• how the method works
• where the evidence comes from
• what the experiments actually show
• what the real boundaries and limitations are

2. The goal of paper reading is a reusable research asset.

Not just “I kind of get it right now,” but something you can revisit, cite, and build on later.

3. Note generation should serve a real research workflow.

That is why it is designed to fit naturally with:

• Obsidian
• Zotero
• local paper management
• long-term knowledge-base building

🧭 Inspirations

DeepPaperNote was influenced by projects that take paper reading, evidence extraction, and note generation seriously, especially:

• heleninsights-dot/phd-deepread-workflow
• juliye2025/evil-read-arxiv

Star History

<a href="https://www.star-history.com/?repos=917Dhj%2FDeepPaperNote&type=date&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=917Dhj/DeepPaperNote&type=date&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=917Dhj/DeepPaperNote&type=date&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/image?repos=917Dhj/DeepPaperNote&type=date&legend=top-left" /> </picture> </a>

<p align="center"> <em>Thanks for reading, using, and supporting DeepPaperNote. May your paper-reading days be a little clearer, calmer, and more rewarding.</em> </p>

<p align="center"> <a href="./LICENSE">MIT License</a> &copy; <a href="https://github.com/917Dhj">917Dhj</a> </p>

<div align="center">

DeepPaperNote

把一篇难读的论文，变成一份真正值得保留的 Obsidian 深度笔记。

English | 简体中文

        

</div>


你是否经常遇到这种情况：准备精读一篇经典论文时，最累的往往不是看，而是整理成笔记。真正耗时间的，通常是这些环节：

• 在 PDF、Zotero、网页和笔记软件之间来回切换
• 手动整理元数据、摘要、图表和方法主线
• 明明已经读懂了一部分，却还要花很多时间把它写成结构化笔记
• 最后留下的仍然只是一篇“看起来完整，但以后未必还想回看”的笔记

DeepPaperNote 想解决的，就是这一层重复、机械、但又非常耗时的工作。它会先把整理、结构化、图表定位和笔记成形这些环节做掉，让你把精力留给真正的思考。

DeepPaperNote 是一个面向论文深度阅读的技能，同一套核心能力可以运行在 Claude Code 和 Codex 上。它更关注：

• 论文到底在解决什么问题
• 方法机制是怎么工作的
• 关键公式、实验结论和图表信息是否被保留下来
• 最终能不能沉淀成一份适合长期积累的 Obsidian 笔记

[!tip]

如果你已经有自己的 Obsidian / Zotero 工作流，DeepPaperNote 会把最耗时、最容易出错的取证、整理和成稿环节自动化。

🎯 它帮你解决什么问题？

!DeepPaperNote usage example

✨ 它是怎么做到的？

DeepPaperNote 不是靠“把摘要重新措辞一遍”来显得更完整，而是靠下面这几条工作流原则，把笔记质量往上抬：

一句话说：

DeepPaperNote 更像一个“论文读书笔记生成工作流”，而不是“论文摘要总结器”。

👀 它更适合谁

<table> <tr> <td valign="top" width="33%"> <strong>👓 啃硬核论文、精读经典论文的人</strong><br><br> 你读的不是扫一眼摘要就结束的论文，而是公式多、架构复杂、实验设计绕、值得反复回看的论文。你需要的不是一篇“漂亮总结”，而是一份能帮你把方法主线、关键结果和图表结构真正理清楚的笔记。 </td> <td valign="top" width="33%"> <strong>🗂️ 用 Obsidian 做长期知识沉淀的人</strong><br><br> 你希望论文笔记不是一次性消费品，而是能长期回看、链接、复用的知识资产。DeepPaperNote 会结合论文领域归档到更合适的位置，再生成 Markdown 笔记和 <code>images/</code> 文件夹，让沉淀这件事更顺手。 </td> <td valign="top" width="33%"> <strong>🤖 不满足于 AI 摘要总结的人</strong><br><br> 你不是只想看一段“看起来很完整”的摘要，而是想知道：这篇论文到底解决了什么、方法是怎么工作的、哪些结果最重要、哪里最容易被误读。DeepPaperNote 更接近研究笔记，而不是摘要生成器。 </td> </tr> </table>

🚀 快速上手

1) 将 DeepPaperNote 安装到你的 agent 技能目录

DeepPaperNote 同时支持 Claude Code 和 Codex。

npx Skills（推荐）

大多数情况下，可以直接用 npx 安装。在终端运行：

npx skills add 917Dhj/DeepPaperNote

此命令会默认安装到共享的.agents/skills目录，这个目录中的 skill 可以被 Codex 等大部分 agent 识别并使用。如果你也想在 Claude Code 里使用，在 Additional agents 提示中选择 Claude Code即可。

你也可以直接指定安装给某个 agent：

npx skills add 917Dhj/DeepPaperNote -a codex
npx skills add 917Dhj/DeepPaperNote -a claude-code

更新

如果要更新已有的 DeepPaperNote 版本，重新运行 npx 安装命令即可；它会替换目标 skills 目录中的现有版本。

手动安装

如果你更习惯手动安装，推荐去 release 页面下载最新版本的 zip 包并解压。

Codex 用户可以把解压出来的 DeepPaperNote 文件夹放到：

~/.codex/skills/DeepPaperNote

Claude Code 用户可以把解压出来的 DeepPaperNote 文件夹放到：

~/.claude/skills/DeepPaperNote

也可以直接 git clone：

git clone https://github.com/917Dhj/DeepPaperNote.git ~/.codex/skills/DeepPaperNote
git clone https://github.com/917Dhj/DeepPaperNote.git ~/.claude/skills/DeepPaperNote

安装完成后，重启你的 agent 让技能生效。

2) 安装核心 Python 依赖

在正式处理论文前，需要安装最核心的 Python 依赖：

python3 -m pip install PyMuPDF

为什么这一步很重要：

• DeepPaperNote 读取 PDF 主要依赖 PyMuPDF
• 如果没装 PyMuPDF，最核心的 PDF 抽取流程就跑不起来

3) 直接开始使用

接下来你只需要把论文丢给 agent 就行，标题、DOI、URL、本地 PDF 都可以，你可以直接给出类似这样的指令：

• 💬 给这篇论文生成深度笔记：Attention Is All You Need
• 💬 把这篇文章整理成 Obsidian 笔记：https://arxiv.org/abs/1706.03762
• 💬 帮我精读一下这篇 PDF，生成带图表的 Markdown
• 💬 请用 DeepPaperNote 处理这篇论文：10.48550/arXiv.1706.03762

默认情况下，DeepPaperNote 会生成中文笔记。当前写作规范和格式校验也主要围绕中文笔记构建；目前中文是唯一能够发挥 skill 完全能力的笔记语言，如需生成英文版笔记，请期待后续更新。

默认情况下，DeepPaperNote 会自己完成：

• 精准识别论文身份
• 获取 PDF、元数据和正文证据
• 图表候选可用时直接插入真实图片；只有候选缺失、视觉缺陷或写入失败等真实问题才保留占位符
• 生成最终 Markdown 笔记
• 自动写入 Obsidian；如果没有配置 Obsidian，则会先询问你是否有库路径，再决定是否降级输出到当前工作区的输出目录

4) 首次使用不必追求完整配置

如果你还没有完整配置 Obsidian / Zotero / OCR，也可以先试跑。

如果你要在本地开发、跑测试或 lint，可以安装开发依赖：

python3 -m pip install -e '.[dev]'

如果你想先检查环境，也可以直接对 agent 说：

• 💬 请帮我检查这台机器上的 DeepPaperNote 是否已经准备好
• 💬 查看 deeppapernote 的可用情况
• 💬 deeppapernote 有什么功能

🔧 配置指南（开箱即用，按需进阶）

如果你已经安装好了 PyMuPDF，那么你就可以直接开始使用 DeepPaperNote 生成笔记了。以下介绍的配置都是核心功能的扩展，让你能够将 DeepPaperNote 生成的笔记真正融入你的科研工作流中。

• 如果你没有配置 Obsidian，它也能把笔记输出到当前工作区下的回退输出目录，默认是 DeepPaperNote_output。
• 但如果你想要更好的长期管理体验，还是强烈建议配置你的 Obsidian 库路径。

📍 核心配置：指定你的 Obsidian 库

export DEEPPAPERNOTE_OBSIDIAN_VAULT="/你的/Obsidian_Documents/绝对路径"

如果你希望 agent 在之后的新终端会话里也一直读到这个默认配置：

• 在 macOS / Linux 上，建议把它写进 ~/.zshrc 之类的 shell 配置文件，然后重新加载 shell 或重启 agent：

echo 'export DEEPPAPERNOTE_OBSIDIAN_VAULT="/你的/Obsidian_Documents/绝对路径"' >> ~/.zshrc
source ~/.zshrc

• 在 Windows PowerShell 上，可以把它持久化成用户环境变量，然后重新打开终端：

setx DEEPPAPERNOTE_OBSIDIAN_VAULT "C:\Users\YourName\Documents\Obsidian_Documents"

<details> <summary><strong>🛠️ 展开查看更多进阶配置（目录自定义 / Zotero / Semantic Scholar / OCR）</strong></summary>

目录相关配置

如果你希望自定义论文目录或中间产物目录，也可以再加：

export DEEPPAPERNOTE_PAPERS_DIR="Research/Papers"
export DEEPPAPERNOTE_OUTPUT_DIR="tmp/DeepPaperNote"

如果你希望 agent 后续一直默认使用这些值：

• 在 macOS / Linux 上，也建议把它们写进 ~/.zshrc：

echo 'export DEEPPAPERNOTE_PAPERS_DIR="Research/Papers"' >> ~/.zshrc
source ~/.zshrc

• 在 Windows PowerShell 上，可以把它们持久化成用户环境变量：

setx DEEPPAPERNOTE_PAPERS_DIR "Research/Papers"

这些可选路径配置的实际好处是：

• DEEPPAPERNOTE_PAPERS_DIR

如果你的 Obsidian 库不是把论文放在 Research/Papers 下，或者你已经有自己的目录约定，这个配置可以让 DeepPaperNote 直接适配你的现有结构，减少后续手动移动文件。

• DEEPPAPERNOTE_OUTPUT_DIR

如果你希望中间产物统一落在一个固定位置，方便调试、清理或做实验，这个配置会比较有用。

领域路由由 references/domain_rules.yaml 中的可编辑分类表控制。DeepPaperNote 会先判断应用领域，再回退到方法领域；只有标题或摘要能提供相对保守的证据时，才会复用已有的 Obsidian 一级领域目录。

可选：用于本地文献库优先工作流的 Zotero

DeepPaperNote 不依赖 Zotero 才能工作。 但如果你本来就用 Zotero 做文献管理，配置一个你的 agent 真的能用的 Zotero 集成会很值。

它最适合这样的人：

• 你本来就用 Zotero 做文献管理
• 你平时主要在 Zotero 里读论文、整理附件和元数据

可以这样理解不同路线：

为什么值得配：

• 本地 Zotero 命中通常是最可靠的论文身份锚点
• 如果论文已经在你的本地 Zotero 库里，DeepPaperNote 往往可以直接复用本地条目和附件信息，不必再重新联网搜索和下载，因此生成速度通常也会更快
• agent 可以先查你的本地论文库，再决定要不要联网
• 本地附件也更有助于减少标题误匹配
• 如果你本来就用 Zotero 做论文管理，这会比重新去网上“猜测这篇论文是谁”稳得多
• 对正式发表版、预印本、镜像页面标题相似的场景，Zotero 优先通常会明显降低误匹配概率

⚠️需要特别说明的是：

• DeepPaperNote 不强依赖某一个固定的 Zotero 集成仓库
• 对 DeepPaperNote 来说，需要的关键能力是：让 agent 能搜索 Zotero 条目、查看元数据、最好还能读取本地 PDF 附件
• 上面提到的两条路线目前都不一定是即插即用方案，如果你想稳定使用，通常还需要自己做一层适配或改造

可选：Semantic Scholar API Key

这不是必需项，但如果你有 Semantic Scholar API key，可以设置：

export DEEPPAPERNOTE_SEMANTIC_SCHOLAR_API_KEY="your_api_key"

它的好处主要是：

• 元数据补全通常会更稳一些
• 对一些标题不好匹配的论文，身份解析会更可靠
• 在作者、venue、摘要等信息回填上，有时会更完整
• 它能给 DeepPaperNote 多一个较强的元数据来源，减少退回到弱匹配的概率

可选：OCR 工具

很多现代 PDF 并不需要 OCR。 但如果论文是下面这些情况，OCR 会很有帮助：

• 扫描版 PDF
• 以图片为主、嵌入文本质量很差的 PDF
• 一些比较老的论文，直接抽文本时内容残缺

DeepPaperNote 当前的 OCR 使用逻辑是：

• 先用 PyMuPDF 做正常的 PDF 文本提取
• 对每一页统计可搜索文本的字符数
• 如果某一页直接抽到的文本太少，就把这页视为 OCR 回退候选
• 只对这类页面单独做 OCR
• OCR 恢复出的文本，主要用于补页级证据和后续图表/页面语义匹配的上下文

需要特别说明的是：

• OCR 目前只是 页文本兜底方案
• 它 不是 所有 PDF 的主提取路径
• 它 不会 代替模型去理解论文
• 它 不会 直接负责“理解图片内容”

如果没有 OCR，DeepPaperNote 处理普通数字版 PDF 依然没问题。面对扫描版或低质量 PDF 时，如果抽取到的证据不足以支撑真正的深度笔记，流程应该要求补充 OCR 或更好的来源，而不是完成一篇低质量输出。

OCR 需要的依赖如下：

在 macOS 上的安装方式：

brew install tesseract
python3 -m pip install --user pytesseract Pillow

在 Windows 上，可以用下面这种方式：

winget install UB-Mannheim.TesseractOCR
py -m pip install --user pytesseract Pillow

如果 winget 不可用，也可以手动安装 Tesseract OCR，再执行：

py -m pip install --user pytesseract Pillow

快速验证：

tesseract --version
python3 -c "import pytesseract, PIL; print('python_ok')"
python3 -c "import pytesseract; print(pytesseract.get_tesseract_version())"

</details>

📝 更新日志概览

更完整的版本级更新请见 CHANGELOG.md。

⚙️ 工作流

默认流程是：

1. 解析论文身份 2. 收集元数据 3. 获取最佳可用 PDF 4. 抽取完整原文与 source manifest 5. 抽取结构化索引和 PDF 图像资产 6. 规划图表位置 7. 构建全量图表决策表 8. 构建 manifest synthesis bundle 9. 让模型读取 raw sections 并规划笔记 10. 对 note_plan 运行 grounding lint 11. 让模型写笔记 12. 校验最终笔记 13. 做最终内容质量复核 14. 做最终可读性复核 15. 写入 Obsidian

核心原则：

• 脚本负责原文、元数据、资产和质量信号
• 模型负责写作
• 格式校验、最终内容质量复核和最终可读性复核在写入前兜底

相关文档：

• 工作流
• 架构
• 模型综合写作

🖼️ 图表策略

DeepPaperNote 把”图片是否插入”和”是否保留占位”当作两个独立问题来处理。

当图表候选可用时——裁图视觉质量合格、能确认是目标图表、图片路径有效——直接插入为真实图片嵌入。

占位符只保留给真实问题：

• 没有可用的图表候选
• 裁图有视觉缺陷、截断或污染
• 无法确认图片与目标图表匹配
• 文件复制或写入失败

当确实需要占位时，DeepPaperNote 会保留语义位置、说明和上下文，让笔记结构不断掉，也让你知道这个位置原本对应什么图：

> [!figure] Fig. 3 数据分布与质量评估
> 建议位置：数据与任务定义
> 放置原因：这张图同时展示样本构成、对话长度统计和专家质检结果，是理解 `PsyInterview` 数据边界最重要的图之一。
> 当前状态：保留占位；当前提取结果只拿到局部子图，无法稳定恢复成可独立解释的完整原图。

详见 图表放置规则。

✅ 质量标准

DeepPaperNote 对“什么算一篇合格笔记”有明确门槛。

最终笔记应该：

• 区分研究问题和任务定义
• 讲清楚真正的方法或分析流程
• 抓住真正重要的关键数字
• 覆盖关键的实验设置和条件
• 区分证据实际证明了什么和尚未证明什么
• 指出哪些地方最容易被误读
• 至少写出一个真实局限，并给出边界约束
• 至少包含一个可复用的研究或工程 takeaway
• 使用真实标题层级：#、##、###
• 避免正文出现半中半英的句子

如果证据质量不够，就应该降级或直接失败，而不是假装完成了深度精读。

相关文档：

• 证据优先
• 深度分析
• 最终写作
• 笔记质量标准

🗂️ 仓库结构

DeepPaperNote/
├── SKILL.md
├── README.md
├── README.zh-CN.md
├── CHANGELOG.md
├── LICENSE
├── pyproject.toml
├── agents/
│   └── openai.yaml
├── assets/
│   ├── hero-academic.svg
│   ├── usage-example.png
│   └── note_template.md
├── references/
│   ├── architecture.md
│   ├── deep-analysis.md
│   ├── domain_rules.yaml
│   ├── evidence-first.md
│   ├── figure-placement.md
│   ├── final-writing.md
│   ├── metadata-sources.md
│   ├── model-synthesis.md
│   ├── note-quality.md
│   ├── obsidian-format.md
│   ├── paper-types.md
│   └── workflow.md
└── scripts/
    ├── build_synthesis_bundle.py
    ├── check_environment.py
    ├── citation_links.py
    ├── collect_metadata.py
    ├── common.py
    ├── contracts.py
    ├── create_input_record.py
    ├── extract_evidence.py
    ├── extract_pdf_assets.py
    ├── extract_source_text.py
    ├── fetch_pdf.py
    ├── lint_grounding.py
    ├── lint_note.py
    ├── locate_zotero_attachment.py
    ├── materialize_figure_asset.py
    ├── plan_figure_table_decisions.py
    ├── plan_figures.py
    ├── resolve_paper.py
    ├── run_pipeline.py
    └── write_obsidian_note.py

🧰 推荐环境

🧭 设计原则

DeepPaperNote 背后的基本判断很简单：

1. 好的论文笔记，不等于段落式摘要

真正有价值的笔记，应该帮助你理解：

• 方法怎么工作
• 证据在哪里
• 实验说明了什么
• 有哪些边界与局限

2. 论文的阅读目标，是沉淀的可复用资产

不是当下“懂了一点”，而是未来还能回看、能引用、能接着研究。

3. 笔记生成应该服务真实研究工作流

所以它更贴近：

• Obsidian
• Zotero
• 本地论文管理
• 长期知识库构建和管理

🧭 致谢与灵感

DeepPaperNote 在工作流设计上受到了这些论文阅读 / 笔记生成项目的启发：

• heleninsights-dot/phd-deepread-workflow
• juliye2025/evil-read-arxiv

Star History

<a href="https://www.star-history.com/?repos=917Dhj%2FDeepPaperNote&type=date&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=917Dhj/DeepPaperNote&type=date&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=917Dhj/DeepPaperNote&type=date&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/image?repos=917Dhj/DeepPaperNote&type=date&legend=top-left" /> </picture> </a>

<p align="center"> <em>感谢你阅读、使用和支持 DeepPaperNote。愿你的每一次论文精读，都更清晰、更从容，也更有收获。</em> </p>

<p align="center"> <a href="./LICENSE">MIT License</a> &copy; <a href="https://github.com/917Dhj">917Dhj</a> </p>

Architecture

This skill should be implemented as:

• a reusable core workflow
• thin platform adapters

That separation keeps the project useful even if the host environment changes later.

Layer 1: Reusable Core

The reusable core includes:

• paper resolution logic
• metadata aggregation
• PDF acquisition strategy
• evidence extraction
• figure planning
• synthesis-bundle assembly
• note-quality checks
• Markdown note rendering constraints
• JSON contracts between stages

These pieces should live primarily in:

• scripts/
• references/
• assets/

The core should be agent-agnostic wherever possible.

Layer 2: Platform Adapter Layer

A platform adapter can include:

• SKILL.md
• agents/openai.yaml
• other distribution-specific manifest files
• trigger phrasing
• tool-selection instructions for the host environment
• interaction-style notes
• host-specific Obsidian or local-library calling conventions

This layer should stay thin. Do not bury core business logic only inside prompt text or distribution metadata.

Design Rule

When adding a new behavior, ask:

1. Would another agent framework also need this behavior?

• If yes, put it in the core.

2. Is this only about how one host environment discovers or invokes the workflow?

• If yes, put it in the adapter layer.

What Belongs in Scripts

Put deterministic or repeated logic in scripts:

• normalization
• parsing
• metadata merge
• PDF discovery
• evidence-pack assembly
• synthesis-bundle assembly
• contract validation
• linting
• file writing

Do not put paper understanding into scripts:

• deciding the paper's real contribution
• choosing which result matters most
• reconstructing the true method chain
• writing the final deep-reading note prose

Those tasks belong to the language model after the deterministic bundle is prepared.

What Belongs in References

Put durable reasoning guidance in references:

• what counts as a high-quality note
• how to adapt to paper types
• figure placement heuristics
• formatting rules
• source-priority rules

What Belongs in SKILL.md

Keep only:

• when the skill should trigger
• the high-level workflow
• which scripts to use
• which references to read
• the non-negotiable workflow constraints that must remain visible at the entrypoint

Portability Goals

A future adapter on another platform should be able to reuse:

• the same scripts
• the same contracts
• the same note template
• the same evidence-first workflow

It should only need a different outer adapter.

Anti-Patterns

Avoid:

• embedding essential contracts only in prompt text
• mixing platform-specific phrasing into script outputs
• writing natural-language-only intermediate artifacts when structured JSON is possible
• allowing note quality to depend on undocumented one-off prompt behavior

Deep Analysis

Use this guide when the user wants a note that feels like a real research note rather than a cleaned-up summary.

Goal

Produce a Chinese paper note that helps future rereading answer:

• this paper is really solving what problem
• the core route or method chain is what
• which evidence actually supports the claim
• where the paper is weak, bounded, or easy to misread
• whether it is worth follow-up, comparison, implementation, or citation

Key Principle

Do not treat deterministic script output as the final note.

Scripts in DeepPaperNote are for:

• resolving the paper
• fetching metadata and PDF
• extracting evidence and PDF assets
• planning figure/table candidates
• linting and writing files

The real value comes from the model reading the available material and writing the note in its own words.

Source Priority

Use sources in this order:

1. synthesis bundle metadata 2. evidence extracted from the full PDF 3. figure/table captions and candidate assets 4. abstract metadata only for identity and context, not as a substitute for a finished deep note

For a finished long-term note, require a usable PDF-backed evidence path.

If you only have the abstract after the supported PDF acquisition paths have failed, stop and ask for a usable PDF, OCR, or source material rather than writing a provisional or abstract-only note.

Recommended Workflow

1. Resolve the paper and build the synthesis bundle. 2. Read the bundle closely before writing. 3. Infer the paper type yourself:

• method
• system/framework
• benchmark/dataset
• clinical/psychology empirical
• survey/tutorial
• humanities/social science

4. Make a short explicit note plan before drafting. The plan should decide:

• which sections deserve the most weight
• which details need ### subheadings
• which 3 to 6 numbers matter most
• which central claims are supported by which source sections or pages
• what each central claim actually proves and does not prove
• which negative, weak, missing, or limiting results constrain the conclusion
• which research or engineering takeaways are specific enough to reuse
• which figure/table placeholders are essential
• whether the paper needs explicit formulas, objective functions, or complexity expressions

5. Write the final note in Chinese. 6. Lint it. 7. Run the final readability review. 8. Save into the Obsidian vault only after the note passes lint and the final readability review.

Writing Rules

• Write for future rereading, not for one-time display.
• Prefer interpretation over translation.
• Prefer “这篇论文真正有价值的点是...” over “本文提出了...” style filler.
• Avoid pasting long English sentences into Chinese sections.
• Do not fabricate metrics, ablations, or claims not supported by evidence.
• If evidence is weak, write a weak-but-honest note instead of pretending the paper was fully analyzed.
• For method papers, write like a replication-minded researcher rather than a summary assistant.

Section Guide

核心信息

Must include:

• title
• authors
• affiliations or institutions when available
• published date
• venue or journal when available
• DOI
• source URL
• code repo or project page when available
• domain

一句话总结

Do not paraphrase the abstract.

Answer:

• what the paper's real contribution is
• what the title may overstate

研究问题

Answer:

• the concrete pain point
• why existing methods are not enough
• whether this is a new problem, a new angle on an old problem, or a more realistic reformulation

数据与任务定义

Must separate:

• where the data comes from
• what labels or supervision exist
• what the actual task is
• what the paper is not predicting

For clinical or social-science papers, spell out:

• collection setting
• weak supervision risks
• annotation or rating assumptions
• whether the task is realistic or simplified

方法主线

This is usually where a shallow note fails.

Explain:

• the information flow
• what each stage consumes and produces
• what the model is actually doing
• what is standard versus paper-specific
• what the training target or optimization target really is
• how inference or sampling actually proceeds
• which implementation details matter for reproducing the claimed gain
• even if an extracted Algorithm block is broken, reconstruct the mechanism in plain engineering language rather than giving up
• make the reader feel the Input -> key transformation -> Output flow, not just the paper's terminology

For method, framework, or system papers:

• default to an explicit ### 机制流程 subsection inside 方法主线
• write it as a 3 to 4 step numbered list rather than a long paragraph
• each step should say what goes in, what operation happens, and where the output goes next
• if the paper has both training and inference details, use ### 机制流程 for the dominant execution chain and leave training recipe details to neighboring subsections

For complex papers, use ### subheadings such as:

• ### 机制流程
• ### 数据构建
• ### 中间表征抽取
• ### 模型结构
• ### 训练与推理

关键结果

Do not dump all metrics.

Include:

• the most important comparison
• the most important numbers
• at least one result that looks strong
• at least one result that limits the claim

For method papers, also ask:

• does the result support the claimed mechanism
• is the gain internal-only or external too
• if the paper reports ablations or removed-module comparisons, include at least one setting that hurt performance, made training unstable, or revealed a trade-off
• if the evidence bundle contains no such negative ablation signal, say explicitly that the paper did not clearly report failed or unstable settings

深度分析

This is the most important part.

Include:

• research value
• practical value
• why the method may work
• where the evidence is still thin
• hidden assumptions
• what the paper does not prove

Use the plan's central_claims as the spine of this section:

• connect each major claim to the evidence that supports it
• say exactly what the evidence proves
• say what remains unproven, untested, or only indirectly supported
• use mechanism_result_map to explain why the paper's mechanism, protocol, construct, or data decision should produce the observed result pattern
• use comparative_positioning to say what changes relative to strong baselines or obvious alternatives, not only that the paper is better
• when the paper has Discussion or Limitations, explain the mechanism behind those caveats rather than copying them as a list

Good subsections often include:

• ### 真正贡献是什么
• ### 为什么结果成立
• ### 哪些地方容易被误读
• ### 训练目标
• ### 推理与采样链路
• ### 复杂度与扩展性

局限

Write real limitations, not polite filler.

Prefer:

• dataset or sampling boundaries
• label leakage or weak-supervision risks
• evaluation mismatch
• deployment gap
• missing baselines
• unrealistic task framing

我的笔记

Seed future follow-up with prompts such as:

• one reusable idea
• one questionable assumption
• one experiment worth replicating
• one related paper to compare next

Figures And Tables

When the paper has useful visuals:

• preserve placeholders for the important ones
• prioritize one method figure, one data/task figure, and one result figure or table
• if a high-confidence pipeline or architecture figure clearly matches the core execution chain, place it in ### 机制流程 first
• explain why each figure matters
• keep original paper numbering such as Fig. 1 or Table 2

Do not dump every extracted image into the note body.

Formula Guidance

If a formula is central to understanding the method, do not leave it out just because the rest of the prose reads smoothly.

Typical cases where a formula should appear:

• probability factorization
• optimization objective
• loss definition
• complexity comparison
• scaling-law fit

Prefer a few stable, well-explained formulas over many noisy ones.

• after each retained formula, add one short engineering explanation of what it means in implementation terms
• do not stop at naming variables; explain what operation, objective term, or state update the formula corresponds to

Minimum Honesty Standard

If the note is based mostly on abstract plus metadata, say so explicitly and soften the judgment. If the note uses full PDF evidence, figures, and key numbers, the judgment can be stronger.

Evidence-First Note Writing

Use this guide when the goal is to approach the quality of a hand-written research note rather than a template-filled summary.

Core Rule

Do not write the finished note directly from:

• the title
• the abstract
• one or two extracted snippets
• fixed headings alone

Instead, use a three-stage model-first pipeline:

1. build raw-source artifacts and a manifest bundle 2. create the canonical short JSON note_plan around source sections/pages 3. run the grounding gate 4. let the model write the note from the raw source, bundle, and plan

Source Manifest Bundle

The source manifest and bundle should answer:

• what type of paper this is
• which parts of the PDF were actually found
• where the raw source text lives
• which numbers matter
• which datasets, metrics, baselines, or cohorts matter
• which figures are method figures, data figures, and result figures
• which conclusions are about scale, transfer, cost, limitations, or practical value
• which central claims have source evidence and which boundaries the evidence cannot cross

In DeepPaperNote, use:

• scripts/run_pipeline.py
• scripts/extract_source_text.py
• scripts/build_synthesis_bundle.py

Explicit Note Plan

Before drafting the final note, the agent should create an explicit short planning artifact rather than silently "thinking it through" and jumping straight to the final Markdown.

Do not require or expose a long free-form chain-of-thought block such as <thinking>...</thinking>. Instead, require a compact and inspectable JSON planning file. The canonical artifact is a short JSON file such as <note>.plan.json or a run-scoped *_note_plan.json. Pass that file to scripts/lint_note.py --plan-file ... when linting; if omitted, lint looks for a sibling <note>.plan.json. In interactive contexts, you may additionally show a compact <note_plan>...</note_plan> block as display-only context, but it does not replace the JSON file.

The plan should state:

• which sections this paper actually deserves
• which sections need more technical depth
• which subsections deserve ### headings
• which evidence feeds each section
• which 3 to 6 numbers matter most
• which comparisons are the real ones
• which central claims are supported by which source sections or pages
• what each central claim actually proves and does not prove
• which weak, negative, limiting, or explicitly unreported results constrain the conclusion
• which research or engineering takeaways are reusable beyond the current paper
• whether this is mostly a method note, system note, dataset note, benchmark note, or empirical/clinical note
• whether key formulas or complexity expressions need to appear in the final note

Good note plans often add paper-specific sections such as:

• ### 数据构建
• ### 量表代理特征抽取
• ### 训练细节
• ### 关键洞察
• ### 为什么结果不等于临床可用

Recommended shape:

{
  "paper_type": "AI_method",
  "paper_type_rationale": "The paper proposes a model mechanism and evaluates it against baselines; the script suggestion was treated only as a hint.",
  "dominant_domain": "machine learning",
  "must_cover": ["数据构建", "方法主线", "关键消融"],
  "key_numbers": ["主结果提升 3.2 points", "训练成本降低 40%"],
  "real_comparisons": ["against the strongest reported baseline"],
  "central_claims": [
    {
      "claim": "The proposed mechanism improves multi-step tool use reliability.",
      "supporting_evidence": [{"section_id": "sec:experiments"}, {"pages": [7, 8]}],
      "what_it_actually_proves": "The reported benchmark settings show fewer unrecoverable tool errors than the named baseline.",
      "what_it_does_not_prove": "It does not prove robustness to arbitrary tools or production latency failures."
    }
  ],
  "claim_boundaries": ["The result is tied to the paper's tool set and benchmark distribution."],
  "negative_or_limiting_results": ["The paper does not clearly report a failed external-tool setting."],
  "mechanism_result_map": ["The state transition design explains the lower unrecoverable-error rate by preserving failed tool-call state for later repair."],
  "comparative_positioning": ["Compared with answer-only baselines, the paper evaluates a mechanism that keeps intermediate failure states inspectable."],
  "reuse_takeaways": ["Track tool failures as first-class state rather than hiding them in the final answer."],
  "followup_questions": ["Does the same state logging still help when external tools are slow, missing, or adversarially noisy?"],
  "section_plan": [
    {
      "section": "方法主线",
      "weight": "high",
      "subsections": ["机制流程", "训练目标"],
      "evidence_sources": [{"section_id": "sec:method"}, {"pages": [4, 6]}]
    }
  ]
}

Before drafting from this plan, run scripts/lint_grounding.py --note-plan ... --source-manifest ... --bundle-json ... --figure-decisions ....

The plan should be short, structured, and directly useful for the final draft.

Writing Layer

Only after the evidence bundle and explicit JSON note_plan exist should the model draft the final note.

Good final notes should:

• prioritize numbers and comparisons over generic summary sentences
• add paper-specific subsections when the evidence supports them
• avoid abstract-only rewriting
• explain why a figure or table matters, not just attach it
• separate “作者声称了什么” from “论文真正证明了什么”
• carry the plan's claim boundaries into 深度分析 and 局限
• explain the mechanism deeply enough that an engineer could re-explain or re-implement the main flow

Minimum Quality Bar

If the note does not clearly contain:

• the most important numbers
• the most important comparison
• one paper-specific insight
• one honest limitation
• one technically detailed subsection
• and, when necessary, one key formula or formal expression

then the note is still too close to a template summary.

Figure Placement

In MVP, the skill must plan figure placement even when it cannot extract image files.

Goal

Plan placeholders for every high-value figure or table that materially helps the note. Do not collapse the paper down to only 1 to 3 items if the paper clearly has more important visuals.

What to Prefer

Priority order: 1. study overview or method overview figure 2. data or task-definition figure 3. key result figure or table 4. other supporting figures that clarify a major argument

Placement Logic

• Put method overview figures in ### 机制流程 when they directly explain the core execution chain
• If the match is weaker or the note does not need that micro-structure, keep them in 方法主线
• Put data or task figures in 数据与任务定义
• Put main result figures or tables in 关键结果
• Put conceptual diagrams in 研究问题 or 深度分析 if they clarify the argument

What to Read

Use:

• figure captions
• nearby正文对 figure 的引用
• section context
• candidate pages and candidate images from deterministic PDF asset extraction

Do not place figures by paper order alone. Do not let scripts make the final semantic choice; scripts should only prepare candidates.

Placeholder-First Rule

• The final note should first have the right placeholder structure.
• If a usable image is extracted and semantically matched with high confidence, replace that placeholder with the real image.
• If a reliable image is not available, keep the placeholder.
• Never silently remove a figure just because extraction failed.
• Text correctness is more important than image completeness.
• Figure replacement decisions should be completed inside the same note-generation task.
• Do not produce a text-only note first and then ask the user in a follow-up whether figures should be inserted.
• If no figure can be confidently replaced, finish the note with placeholders and explain that outcome in the final response.

Usable Candidate Decision Contract

usable_candidate means the pipeline found a candidate that is visually eligible to insert. For every usable figure/table candidate, resolve the final note into one of these states:

• insert: materialize the image and replace the placeholder with the real image plus one italic caption line
• kept_placeholder_visual_defect: keep the placeholder because manual review found a concrete visual defect, such as contamination, truncation, missing table body, partial subfigure, or caption loss
• kept_placeholder_materialization_blocked: keep the placeholder because materialize_figure_asset.py or file copy/write permission failed

Do not keep a usable candidate as a placeholder merely because it is lower priority, supplemental, already summarized in text, or less central than another inserted figure/table. If a usable candidate is important enough to appear as a callout in the final note, insert the real image. If it is not important enough to appear, omit it or summarize it in prose rather than leaving a placeholder.

For usable_candidate and needs_visual_quality_check / review candidates, final visual judgment requires opening and inspecting the actual candidate image file. Do not write that manual visual review found no reliable insertable candidate unless that inspection actually happened. If no manual inspection happened, name the state as an unresolved visual review requirement or an automatic script outcome, not as a reviewed visual defect.

Keep missing-candidate cases separate from materialization failures:

• if source_image_path is empty, skip_reason is asset_candidate_missing, or no independent matching crop exists, write 当前状态 as missing/unavailable candidate, not as copy/materialization blocked
• reserve materialization blocked only for a real chosen image asset that failed during materialize_figure_asset.py, final copy, permission, or write_obsidian_note.py
• if a crop includes another Figure/Table caption or another figure body, treat it as a visual defect or missing independent candidate; do not call it usable just because it contains the target label

plan_figure_table_decisions.py preselects planned usable figure/table crops as insert. That does not mean run_pipeline.py writes into the vault; materialization happens at the final save step, where write_obsidian_note.py --figure-decisions ... copies the selected images and refuses a note that does not reference the selected image path.

Do not use soft reasons such as keeping the note light, values already transcribed, future lookup, or convenient back-reference as the standalone reason for keeping a usable candidate as a placeholder.

Integrated Placement Rule

Every kept placeholder must be placed directly under the most relevant substantive section named by its 建议位置. Do not collect unresolved placeholders into a catch-all section such as 剩余图表占位, 未放置图表, Remaining figures, or Leftover figures.

reject_visual_quality means the candidate image must not be inserted. It does not by itself require a final-note placeholder. The final placeholder set should come from semantic importance to the note, not from the number of failed extraction candidates. reject_visual_quality and asset_candidate_missing are automatic fail-closed script outcomes and do not require manual visual review.

For survey papers with many representative project figures, appendix tables, or repetitive supplemental visuals:

• keep a callout only when the visual materially helps the reader understand the argument
• otherwise summarize the pattern in prose or point the reader back to the appendix/source paper
• do not stack low-value callouts just to demonstrate that the pipeline saw them

Visual Quality Gate

Figure/table insertion has two separate gates:

• identity match: the candidate label, caption, and local context match the planned figure/table
• visual usability: the crop actually contains the visual body needed by the reader

A label or caption match is not insertion approval. Fail closed when visual usability is weak: keep the placeholder instead of inserting the candidate.

Reject candidates that are:

• caption-only crops
• tables with no visible table body
• table crops contaminated by running prose outside the table body or another Figure/Table caption
• figure crops contaminated by another Figure/Table caption or by a second figure body
• large text, title-page, or abstract crops masquerading as figures
• crops where the visual body is tiny relative to the crop

Placeholder Requirements

Every kept placeholder in the final note must use the standard [!figure] callout format. This callout is only valid for figures or tables that remain placeholders. Do not use ordinary paragraph markers such as [图表占位 | Fig. 1], 图表占位：Table 2, or Figure Placeholder | Fig. 3.

Each placeholder should include:

• figure or table id
• a short label
• target note section
• reason for placement
• current status
• if available, the most plausible candidate image file(s)

Preferred final-note format:

> [!figure] Fig. 3 数据分布与质量评估
> 建议位置：数据与任务定义
> 放置原因：这张图同时展示样本构成、对话长度统计和专家质检结果，是理解数据边界最重要的图之一。
> 当前状态：保留占位；当前提取结果只拿到局部子图，无法稳定恢复成可独立解释的完整原图。

The placeholder text should be stable and explicit:

• 建议位置 says where the figure belongs in the note
• 放置原因 says why the figure matters for understanding the paper
• 当前状态 says why the note keeps this placeholder
• 当前状态 must preserve truth over neatness; if extraction is uncertain, say so plainly

If a real image is inserted:

• keep the original paper identifier, for example Fig. 2 or Table 1
• do not renumber it according to note order
• use the relative_markdown_embed from figure_table_decisions.json; final save with write_obsidian_note.py --figure-decisions ... copies the image into the paper-local images/ directory
• render the embed followed immediately by one italic caption line
• do not keep a redundant [!figure] callout for that same inserted figure
• if the extracted image is only a subpanel or partial crop, say so explicitly

Preferred final-note format for inserted real images:

![[Research/Papers/DeepPaperNote/paper_slug/images/page_003_img_01.png]]
*论文原图编号：Fig. 2。数据生成流程图。这里插入是因为它最能帮助理解方法主线。*

When to Skip

If the paper has no informative figures or tables:

• do not force one
• state that no high-value figure placeholder was added

Metadata Sources

Use the strongest available source first, but backfill aggressively.

Preferred Order

1. user-provided exact source 2. local Zotero metadata and attachments 3. DOI resolution and publisher metadata 4. Semantic Scholar 5. OpenAlex 6. arXiv metadata

Required Fields to Attempt

• title
• authors
• affiliations
• year
• venue
• DOI
• source URL

Optional Fields

• abstract
• code URL
• project URL
• citation counts
• arXiv ID
• Zotero key

Rules

• If the paper is already in the local Zotero library, treat Zotero as the identity anchor before doing title-based web resolution.
• If Zotero resolves the paper but does not expose a local attachment path, still use the Zotero metadata to avoid title ambiguity.
• Do not let a weaker internet title match override a confident Zotero hit.
• Do not invent missing metadata.
• If a Chinese title is assistant-generated, mark it as a translation.
• Distinguish:
• not found
• not provided by source
• ambiguous