deeppapernote

DeepPaperNote

当用户希望实现以下某一目标时使用此技能：

• 仔细阅读一篇论文
• 生成高质量的 Markdown 笔记
• 根据已解析的配置，将笔记保存到工作区或 Obsidian 目标位置

中文触发示例：

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

英文触发示例：

• Generate a deep-reading note for this paper
• Turn this paper into an Obsidian research note

用户配置

在常规论文处理流程开始前，阅读 references/user-configuration.md，了解配置准入、迁移、修复、运行覆盖项和偏好更改。

首先从明确请求、CLI 和当前进程环境中解析运行覆盖项。如果这些覆盖项能为所选保存模式组成完整有效的配置，则配置就绪，不需要读取用户配置。只有当运行覆盖项需要回退值时，才检查用户配置。

语言完整性约定

配置就绪后，为本次运行解析一个 output_language（zh-CN 或 en）。source_manifest.language_hint 仅描述源文本，不用于选择笔记配置文件。

在以下各阶段中绑定该确切值：保存目标准入 → 图示规划 → 图表决策 → 综合包 → 笔记规划 → 依据核查 → 最终笔记核查 → 最终质量审查 → 最终可读性审查 → 正式保存：

• 流程中的每个 JSON 构件都必须在顶层携带 output_language；综合包还必须在 writing_contract.language 中携带相同的值。
• 每个相邻阶段的处理环节在生成输出前，都必须检查每项输入的语言，并与已解析的值进行比较。若值缺失、不受支持或不匹配，则停止流程；任何阶段都不得推断或默认构件语言。
• 最终质量审查和最终可读性审查都必须接收已解析的值，并仅依据对应的配置文件检查笔记。
• 最终笔记核查会记录 note_sha256。任何审查编辑都会使先前的核查失效，因此必须在相同语言下重新运行最终笔记核查。正式保存要求核查语言和 note_sha256 与最终笔记一致，并在执行任何保存操作前验证图表决策的语言。

只有在每个指定阶段都绑定到已解析的值，且正式保存验证了最终文件内容后，此约定才算完整。起草或调试任一语言的内容时，请阅读 references/output-language.md 了解配置文件内容。

此技能的适用范围有意保持狭窄：

• 这是一个规范 Skill 和一条包含两种输出配置的流程
• 一次只处理一篇论文
• 不更新每日阅读列表
• 不将对摘要的浅层改写视为成功输出
• 不将公开入口拆分为单独的设置、故障排除或启动命令

核心标准

完成的笔记不能只是摘要，而应重构论文的论证：

• 它解决了什么问题
• 任务如何定义
• 使用了哪些数据或材料
• 方法或分析的实际运作方式
• 哪些结果最重要
• 论文未能证明什么
• 这篇论文为何值得留存

默认写作者身份：

• 顶尖研究人员或算法工程师
• 撰写面向复现的实验室笔记
• 不撰写科普说明
• 假设读者能够理解 Python、PyTorch、训练循环和评估逻辑

笔记必须适配论文类型。沿用相同的基本结构，但根据 AI 方法、基准测试、临床研究、人文或社会科学论文调整侧重点。

工作流

按以下顺序执行：

1. 完成配置就绪检查：先解决运行覆盖项，仅当它们不完整时才检查用户配置；只有在解析后的运行配置完整且有效后，才能继续
2. 确定论文身份
3. 收集元数据
4. 使用已确认的身份和用户提供的原始引用（fetch_pdf.py --reference）获取最佳可用 PDF；在 Obsidian 模式下，下载前先验证并复用匹配的本地归档，并按照 references/paper-archive.md 选择版本/来源
5. 提取规范原始源文本：*_raw_sections.jsonl、*_source_manifest.json，以及可选的派生文件 *_full_text.md
6. 在起草或进行领域路由之前，执行保存目标准入：
   • 对于 Obsidian 模式，使用已解析的标题、准确的 output_language、Vault 和 *_source_manifest.json 运行 scripts/write_obsidian_note.py --preflight；该程序的结果具有权威性，因此不要用仅基于提示词的重复检查取代它
   • 如果准入结果要求复用，则使用该目录并跳过领域选择；已验证的仅含 PDF 的目录无需注册确认。从预检结果读取 asset_subdir，并将其用于绑定源文件的图像嵌入
   • 如果结果为 same_language_note_exists，则在起草前停止，并询问用户是否覆盖报告的笔记。如果用户同意，则使用 --overwrite-existing-note --expected-existing-note-sha256 <reported_sha256> 重新运行预检，并在正式保存时附带这项确切确认；如果用户拒绝，则停止且不写入
   • 如果匹配到多个目录或来源，则按照 references/paper-archive.md 操作：询问当前选择，并在预检和正式保存时沿用该选择
   • 对于任何其他阻止操作的冲突，报告返回的歧义并停止，不要创建第二个目录
   • 工作区模式不会扫描 Obsidian Vault，而是按常规领域路由流程继续
7. 提取结构索引和 PDF 资源
8. 规划图表位置
9. 构建完整的图表/表格决策表
10. 构建清单综合包
11. 让模型读取该综合包和原始章节，并创建简短的 JSON note_plan，满足生成的综合包契约，包括准确的 output_language
12. 只有通过依据核验关卡后，才能根据计划起草
13. 让模型撰写笔记
14. 根据同一份 note_plan 对最终笔记进行 lint 检查——只有在 lint 产物存在且所有报告的 passes_* 关卡均为 true 时，此阶段才算完成；否则进行修订并重新运行 lint。如果 lint 输出包含 passes_style_gate: false，则必须在进入第 15、16 或 17 步之前应用风格关卡强制规则
15. 在 lint 通过后执行 final_quality_review
16. 在质量审查通过后执行 final_readability_review
17. 使用 scripts/write_obsidian_note.py、同一份 Source Manifest 以及任何经用户批准的覆盖哈希，将笔记正式保存到准入的目标位置；脚本会在首次保存产生副作用前重新执行准入检查

这是常规单篇论文笔记请求的必需工作流，不是可随意采用的建议。 除非此技能明确标记某个阶段为可选，否则不得悄悄跳过必需阶段、将其重新排序以走捷径，也不得仅仅因为已有部分产物就视为该阶段已完成。

全局禁止走捷径规则：

• 不得只完成前期阶段就停止，并将工作流说成已经完成
• 不得以速度慢、不方便或暂时不确定为由绕过必需阶段
• 不得用临时编造的捷径取代规定的工作流
• 如果必需阶段失败，只能采取以下三种做法之一：
  • 重试该阶段
  • 进入此技能明确允许的后备流程
  • 停止并报告受阻阶段，以及仍未完成的下游必需阶段
• 当必需的下游阶段仍待完成时，不得将整个任务描述为已完成 完成状态用语规则：
• 只有在所需工作流确实完成时，才说 笔记已完成
• 草稿已完成，但 lint、最终可读性审查或保存仍待处理时，说 已生成草稿
• 只有实际运行并通过 lint 后，才说 已通过校验
• 只有写入步骤实际成功后，才说 已保存到 Obsidian
• 不要把 lint 已通过 等同于 整篇笔记已经润色完成
• 如果最终可读性审查仍待处理，请明确说明草稿已通过脚本 lint，但尚未完成最终语言审查
• 如果工作流提前停止，请指出当前阶段以及仍缺少的必需阶段，而不要使用表示完成的措辞
• lint 是底线，不是写作目标

最终用户报告：

• 使用上述定义的完成状态用语。正式保存成功后，使用用户对话所用的语言进行报告。
• 首先提供最终笔记链接或路径、保存模式以及实际保存的领域。在 Obsidian 模式下，从最终笔记路径（位于配置的论文根目录下）读取领域；在工作区模式下，从输出根目录读取领域；如果 Save Target Admission 复用了现有目录，则报告该目录已有的领域。
• 然后按以下顺序报告：
  1. 论文标题和最有力的已验证标识符
  2. Grounding Lint、Final Note Lint、Final Quality Review 和 Final Readability Review 的结果，以及警告数量
  3. 已生成并保留占位符的图表/表格数量
  4. 已保存笔记的 SHA-256 是否与 Final Note Lint 中的 note_sha256 匹配
• 仅在确实发生时，补充覆盖操作、偏好变更或与用户相关的警告。
• 报告仅包含这些字段，并确保每项说明都以本次运行产物为依据。

核心执行约定

SKILL.md 和生成的 synthesis_bundle.json 必须足以完成一次常规笔记生成任务。 references/ 下的文件是可选的、针对特定阶段的深入参考资料，不是默认阅读清单。

不可妥协的规则：

• 证据优先：根据综合信息包、source_manifest、原始章节、覆盖范围元数据、明确的 note_plan 和经过检查的论文证据撰写；绝不能仅凭标题、摘要或章节标题完成笔记
• 原始来源优先：对于普通 PDF，*_raw_sections.jsonl 和 *_source_manifest.json 是规范的阅读材料；旧版 Top-N 证据分类、截断的 section_texts 和 candidate_chunks 不是面向模型的写作输入
• 失败即停止：如果无法通过受支持的获取途径获得可用的 PDF 或充分证据，就停止并要求提供更好的源材料，而不是生成质量降级的最终笔记
• 模型优先：脚本负责组织证据，但重点、贡献、机制、局限性以及最终文案必须由模型以配置的语言决定
• 必需结构：按 writing_contract.must_include_sections 中声明的顺序，纳入本地化的规范章节
• 摘要忠实度：保留原始摘要的含义，不添加后续证据或模型判断；在 zh-CN 模式下翻译摘要，在 en 模式下以英文忠实呈现
• 机制深度：方法、框架和系统类论文应在本地化的方法章节下加入本地化的机制流程小节，通常采用 3 到 4 步的编号流程，并说明输入、操作和输出去向
• 图片占位符优先：先规划主要图表占位符；只有在身份匹配和视觉可用性都很可靠时才替换占位符，否则保留占位符

参考资料使用策略：

• 默认不要加载所有参考文件
• 仅当论文较复杂或草稿过于浅显时，查阅 references/evidence-first.md、references/deep-analysis.md 或 references/final-writing.md
• 仅当图表位置不明确或需要决定是否替换图像时，查阅 references/figure-placement.md
• 对于现有的 Obsidian 目录、本地 PDF 版本选择或 Connector 交接，查阅 references/paper-archive.md
• 仅在需要了解 Markdown、知识库、frontmatter 或引用链接格式细节时，查阅 references/obsidian-format.md
• 仅在进行最终审核或领域适配时，查阅 references/note-quality.md 或 references/paper-types.md
• 仅在元数据不完整时，查阅 references/metadata-sources.md；仅在需要维护代码仓库时，查阅 references/architecture.md

工具和来源优先级

按以下顺序优先使用最可靠的来源：

1. 用户提供的本地 PDF 路径
2. 本地 Zotero 条目及其本地附件（如有）
3. 与已确认作品及所请求版本相符的已验证本地 Obsidian PDF
4. DOI 和出版商元数据
5. arXiv 或开放获取 PDF 来源
6. Semantic Scholar 或 OpenAlex，用于补充元数据

在通过网络解析之前，使用随附的 scripts/resolve_paper.py Zotero Local API 路径检查桌面文献库。其默认的 --zotero-mode auto 会优先选择唯一的本地匹配项；如果 Zotero 不可用或没有匹配项，则回退到现有提供方。显式指定的 Zotero 键没有安全的网络回退方案，必须在本地验证。使用 off 不发出 Local API 请求；如果引用必须通过 Zotero 解析，则使用 required。受信任的 JSON 产物或显式指定的本地 PDF 仍具有权威性，并会跳过此查找。可用时，兼容的会话级 Zotero/MCP 集成仍可提供受信任的输入产物，但内置路径不依赖该集成。

本地文献库优先规则：

• 首先使用论文标题、DOI、arXiv id 或确切的 Zotero 条目键搜索本地 Zotero 文献库
• 如果 Zotero 找到该论文，将该结果视为规范的身份解析步骤。
• 优先使用内置 Local API 返回的安全本地附件路径。如果其他兼容集成仅提供附件键和文件名，则使用 scripts/locate_zotero_attachment.py 在用户的 Zotero 存储目录下查找 PDF。
• 如果存在本地附件路径，将其作为首选 PDF 来源传递。
• 如果未找到本地附件，仍使用文献库解析出的元数据避免标题歧义，然后仅针对文件本身回退到网络 PDF 获取。
• 如果有多个本地条目同样符合条件，则停止解析并要求提供 DOI、arXiv id 或确切的 Zotero 键，不要任意选择。
• 不要让较弱的、仅基于标题的互联网匹配覆盖可信的本地文献库匹配结果。

输出规则

正式保存状态：

保存目标状态	必需操作
save_mode=obsidian 且已配置的 Vault 可用	将内容正式保存到该 Vault。
save_mode=obsidian 且正式保存失败	保留当前保存目标并尝试范围内的恢复。如果仍无法完成，则报告 blocked；不要切换到工作区。
save_mode=workspace	在当前工作区输出根目录内正式保存。

• 正常的笔记生成请求应一次完成：撰写笔记文本、决定图示占位符、在有把握时生成图片，并最终保存。
• 不要只完成纯文本草稿后就停下来询问用户是否要插入图示。除非用户明确要求只提供文本，否则应在同一任务中完成图示替换决策。
• 笔记必须使用真实的标题级别：#、## 和 ###。
• 每篇最终笔记都必须以 Obsidian YAML 属性块开头，并置于 # 标题上方。至少包含一个值为 papers/<domain> 的 tags 字段，以及有用的 aliases；如果已知，则包含 date、doi 或 arxiv_id，对于不可用的字段则省略，不要编造占位符。
• 本地化的 Core Information 部分必须仅包含固定元数据块。只能使用 writing_contract.core_info_fields 中声明的字段和顺序；省略不可用的字段，并将评论性内容移至后续分析部分。
• 如果有摘要元数据，应在笔记开头附近加入本地化的 Abstract 部分，并置于一句话总结之前。
• Abstract 部分应以配置的语言忠实呈现论文原始摘要，而不是替换为模型撰写的总结。
• 不要在 Abstract 部分中混入后续的判断、贡献总结或事后解释。
• 紧接 Abstract 部分之后、在一句话总结之前，加入专门的本地化 Contributions 部分。
• Contributions 部分应逐条列出论文的实际创新，并说明每项创新的重要性，而不是空泛赞誉。
• 对于非平凡论文，高质量笔记的技术部分通常应包含多个有意义的 ### 子标题。
• 起草或保存之前，生成完整的图表决策表，并满足生成的 writing_contract.figure_table_contract。
• 构建完综合材料包后，在创建 note_plan 之前，完成由模型主导的 Visual Review Gate 和 Figure/Table Decision Freeze；不得让任何 review_pending 项越过该关口。
• 通过 grounding 和最终笔记的图表关卡后，方可继续；若任何决策覆盖、插入、结构或状态检查未通过，必须修改。
• 只有在 Formal Save 将选定图片写入论文专属的 images/ 目录且写入成功后，insert 决策才算完成。
• 笔记必须通过其配置语言对应的风格检查：zh-CN 会拒绝中英混杂的行文，en 会拒绝引文元数据之外的中文行文。
• 风格检查还会拒绝机械的术语替换产物，例如 KV缓存 of、批量ing、In相关 Researcher 或 Single 序列 generation；应将句子改写得自然，不要保留只翻译了一部分的短语。
• 风格检查执行要求：当 lint_note.py 的输出包含 passes_style_gate: false 时，修复报告的问题并重新运行 lint。持续修复并重新运行，直到 lint 通过为止——通常需要多轮，这是正常且预期的。不要将任何失败判定为可接受的例外——专有名词、数学公式和引文元数据均不会自动豁免。只有当多轮之后同样的问题仍原样出现且没有减少，表明模型无法继续独立改进时，才向用户升级处理。
• 如果 PDF 或证据质量不足以支持真正深入的笔记，则应拒绝继续：停止处理，报告受阻的阶段，并请用户提供质量更好的 PDF、OCR/源材料或继续处理所需的其他输入。 以模型为先的规则：
• 脚本可以收集并整理证据
• 脚本不得作为理解论文的主要手段
• 最终的论文理解和笔记撰写应由模型完成
• 使用生成的 bundle 合约来选择论文类型、章节语义、有证据支撑的论点、边界、比较对象和可复用的后续问题；脚本建议仅供参考，不具有写作决定权
• 不得要求或暴露冗长的自由格式 <thinking> 区块
• 对于技术论文，优先撰写可用于复现的详细说明，而非高层摘要
• 如果公式、目标函数或复杂度表达式是核心内容，请在最终笔记中纳入关键公式
• 数学公式应使用 $...$ 或 $$...$$ 格式，不要写成行内代码或围栏代码块
• 最终保存前，明确自查笔记是否包含足够的技术细节、关键数字和所有必要公式
• 在 final_quality_review 期间，依据以下七个问题检查完整笔记：核心证据链是否完整；关键设置和数字是否齐全；是否将机制或协议与其解释的结果模式对应起来；论文是否与强基线或替代方案进行比较并明确定位；是否从机制层面解释了 Discussion/Limitations 中的结论；是否区分了已证实和未证实的论点；研究、工程、复现或有效性方面的启示是否足够具体且可复用
• 涉及三个或更多系统、设置、任务、数据集、指标或消融行的核心定量比较，通常应整理为紧凑的 Markdown 表格，并在表格后进行解读；如果表格更清晰，就不要把主要结果表留作松散的项目符号列表
• 短论文同样需要完整深入的笔记：应利用节省的篇幅说明协议细节、消融、局限性，以及部署或复现方面的启示，而不是将笔记压缩成简略摘要
• final_quality_review 通过后，再通读完整笔记一次，检查可读性；不要只满足形式上的合规要求
• 在 final_readability_review 中，将遗留的外语内容改写为配置语言的自然表达，同时保留稳定的专有名称
• 不要为了通过 lint 而在 final_readability_review 中编造新事实、添加空洞填充内容，或改用更浅显但更稳妥的措辞

以上主题参考资料有助于应对困难任务，但正常执行流程不应依赖于阅读所有资料。

脚本

使用这些捆绑脚本，而不要从头重建工作流：

• scripts/check_environment.py
• scripts/user_configuration.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

Python 解释器规则：

• DeepPaperNote 要求 Python >=3.10。
• 运行仓库脚本之前，请检查解释器版本，不要假设当前 Shell 默认使用的解释器兼容。
• 如果默认的 python3 版本低于 3.10，请自动查找其他满足要求的可用解释器，例如 python3.12、python3.11、python3.10、/opt/anaconda3/bin/python3、/opt/homebrew/bin/python3 或 /usr/local/bin/python3。
• 找到的第一个兼容解释器将用于当前任务中的仓库脚本，并在后续过程中继续使用该解释器。
• 如果没有可用的兼容解释器，请停止并明确告知用户找到的解释器及其报告的版本，以及 DeepPaperNote 要求 Python >=3.10。

故障排除规则：

• 只有在具体的依赖项或集成问题阻碍执行时，才使用 scripts/check_environment.py
• 直接说明所需依赖项、可选增强功能和降级行为，不要将该技能引导至单独的故障排除工作流
• 不要将环境检查包装成面向用户的伪命令入口

当前状态：

• 单篇论文的确定性核心工作流已作为 MVP 实现
• scripts/run_pipeline.py 现在默认构建面向模型的综合资料包
• scripts/write_obsidian_note.py 可以将最终笔记写入目标知识库
• 应修改脚本，而不是临时替换工作流

限制

• 如果论文身份不明确，请在写入前确认。
• 如果尝试所有受支持的获取途径后仍无法获取 PDF，请停止并说明需要什么输入；不要将降级版、临时版或仅基于摘要的笔记作为最终输出。受支持的获取途径包括本地 PDF、Zotero 附件、元数据中的 pdf_url、直接 PDF URL、arXiv／开放获取来源、可访问的出版商 PDF、DOI 补充信息，以及工作流当前实现的其他获取途径。
• 必须先规划占位图；提取图像是可选的，且绝不能因此减少文本覆盖范围。