literature-handout

name	literature-handout
description	从学术论文生成结构化中文讲义（markdown），存放在 Obsidian vault 中，纯 Obsidian 原生导航（[[#Heading]]）。触发条件：用户提供论文（arXiv URL / PDF / 标题），要求生成讲义 / 写讲义 / 读论文写讲义 / 生成 handout。

文献讲义生成流程（Vault-Aware, Obsidian Native）

从学术论文生成结构化中文讲义，中文学术风格，物理系视角。默认产物是纯 Obsidian markdown 文件（[[#Heading]] 导航，无 {#anchor-N}）。不主动问是否要 PDF，用户说了才生成。自动扫描用户的两个 Obsidian 知识库，引用已有知识、检测新知识点并提示补全。

当前默认讲义标准（start_up 标准，2026-06-06 更新）

以后生成论文讲义时，默认以 Handout by AI/start_up.md 的写法作为质量与结构标杆。该讲义对应的原始论文 PDF 位于：

C:\Personal Profile\Profile\ScienceResearch\Literature\2603 Quantum Computing 文献调研\2023-parallel gates.pdf

该路径是参考样例的论文来源；生成其他论文讲义时，应读取用户提供的新论文来源，但写作风格、解释深度、章节组织和图表规范参照 start_up.md。

start_up 标准的核心特征

1. 极速起步式导言：开头明确读者画像、已具备前置知识、本文要解决的论文问题，并用亲切但严谨的中文建立学习动机。
2. 按物理故事线组织，而不是机械复述论文：章节应沿着“物理载体 → 相干操控 → 关键机制 → 门/协议设计 → 实验验证 → 核心公式 → 新知识点”的逻辑展开。允许重排论文结构，只要更利于理解。
3. 物理图像先行：每个大节先回答“这件事在物理上是什么、为什么要这样做”，再进入 Hamiltonian、态矢量、矩阵或实验参数。
4. 循循善诱的推导：公式必须逐步解释，不能只给结果。关键推导要写出假设、代入、近似、物理含义和适用条件。
5. 面向用户背景降维讲清楚：默认面向物理系本科高年级/刚进入科研训练的读者。可使用量子力学表象、矩阵、Hamiltonian、角动量基础，但遇到新工具（如绝热消去、暗态、SPAM、benchmarking）必须自包含解释。
6. 中英双语术语首现：关键术语第一次出现必须给出英文，如“暗态（Dark State）”“相干 dressing（coherent dressing）”。后续可用中文或缩写。
7. Callout 强化直觉与易错点：优先使用 [!tip] 写物理直觉、[!info] 写补充背景、[!warning] 写符号约定与常见误解。
8. Python 图表作为理解工具：凡是出现动力学、势能曲线、脉冲波形、衰减拟合、能级结构等可视化对象，应加入可运行 Python + matplotlib 代码块；图表内部文字和代码注释一律英文，并在写入前用 ast.parse 检查语法。
9. 保留 Obsidian 原生性：使用 wiki-link 引用已有知识点；目录如需存在，使用 [[#完整标题]]；不要在标题后添加 {#anchor-N}；不要把 wiki-link 包在反引号里。
10. 结尾必须有三件套：## 📐 核心公式摘要、## 💡 新知识点补全提醒、## 📝 更新记录。
11. 核心公式表的 Markdown 安全：表格中的量子态必须写作 \vert 0\rangle，不要写 $|0\rangle$，避免 | 破坏 Markdown 表格。
12. 学习进度 block reference 谨慎保留：若用户正在用 ^YYMMDD / ^nuYYMMDD 标注学习进度，更新旧讲义时不得删除或改变其区间含义；新生成讲义默认不主动添加学习进度标记，除非用户要求。

推荐章节骨架（论文讲义默认）

# 🚀 极速起步：论文主题中文讲义（短标题）

> **导言**
> 面向谁、已有前置知识、论文解决什么问题、本讲义会如何讲清楚。

---

## 🔬 第一部分：物理载体 / 问题设置
## ⚡ 第二部分：相干操控 / 基础机制
## 🧠 第三部分：核心物理机制 / 关键理论
## 🎨 第四部分：方法设计 / 门方案 / 协议
## 📊 第五部分：实验验证 / 数值结果 / benchmark
## 📐 核心公式摘要
## 💡 新知识点补全提醒
## 📝 更新记录

具体章节名必须根据论文内容调整，不要机械套模板；但应保持 start_up.md 那种“每一部分解决一个清晰物理问题”的节奏。

核心约束

• 讲解要详细：多解释"为什么这么做"，不堆公式
• 正文语言：保留论文标题、文件名、已有英文标题和标准术语；讲义正文、表格说明、总结、导航说明、学习建议等新增解释性内容必须以中文为主，标准术语首次出现时可附英文或中文解释。
• Python 与图表内部英文：所有 Python 代码、代码注释、matplotlib 标题/坐标轴/legend/annotation 必须使用英文，避免 CJK 乱码或 glyph warning。不要因为图表规则把讲义正文改成英文。
• 默认 Obsidian markdown：目录用 [[#章节标题]] 链接到对应 ## 标题，不在标题末尾加 {#anchor-N}（PDF 锚点）
• 可选 PDF 生成：仅当用户明确说「生成 pdf / 转 pdf / 发 pdf」时才执行 PDF 步骤。没说要 PDF 就只给 .md
• 物理视角：假设读者已掌握量子力学算符基础、量子门概念和拉比振荡物理
• Vault 感知：生成前必扫 vault，后必检新知
• 中英双语术语：每个关键名词（概念、方法、门操作、物理量）首次出现时，都标注英文。格式：CZ 门（Controlled-Z Gate） 或 拉比振荡（Rabi Oscillation / Rabi Flopping）。后续可直接用中文或缩写，但首次必须附英文。
• Python 可视化：遇到物理情景（拉比振荡、里德堡势、DRAG 脉冲、RB 衰减等），必须在讲义中添加可运行的 Python + matplotlib 代码块。代码需遵循 vault 规范（CJK-Warning-Free 英文标签、plt.tight_layout()、无框图例 frameon=False）。

---

标准流程

第零步：扫描知识库（前置）

目的：了解用户已经学过什么，避免重复基础讲解，并在讲义中引用 vault 笔记。

扫描内容：

1. Quantum Computing Vault：C:\Personal Profile\Profile\ScienceResearch\Quantum Computing\Rydberg atom\ 下的所有知识点笔记
2. MathPhysCore Vault：C:\Personal Profile\Profile\MathPhysCore\Knowledge Point\ 下的所有笔记
3. User Profile：C:\Personal Profile\Profile\ScienceResearch\Quantum Computing\.agents\memory\user_profile.json — 获取用户学业阶段、已完成/进行中的课程

输出：建立「已有知识索引」，包含：

• vault 中已有的概念名称列表（从笔记文件名 + YAML aliases 提取）
• 每条笔记的 status（Draft / In-Progress / Evergreen）
• 用户的数学和物理背景完成度

原则：

• 对已学概念，讲义中直接引用 vault 笔记："你在 [[Rabi-Flopping]] 中学过拉比振荡…"
• 对已学但不用在讲义主体中重复推导的内容，一句话带过并指向 vault
• 对 status=Draft 或空内容的笔记，视为「知道名字但未深入」，可按需在讲义中适当补充

第一步：获取论文信息

根据用户提供的线索定位论文：

• arXiv URL → 直接用 browser_navigate 打开 arXiv 摘要页
• arXiv ID → 导航到 https://arxiv.org/abs/<ID>
• 标题关键词 → 用 mmx search 或 browser_navigate 到 arXiv 搜索
• PDF 文件 → 用 pdf-read skill 提取文本内容

读取摘要、作者、单位、关键图表标题，建立对论文的第一印象。

第二步：分析论文结构（深度阅读）

通过以下方式深度理解论文：

1. 读摘要：提取核心创新点、方法、关键结果
2. 读引言：理解动机、领域背景、科学问题
3. 读方法/理论部分：理解核心技术路线
4. 读结果：关键数据、图表解读
5. 读结论：意义、局限性、延伸方向

用 mmx search 补充背景知识（相关工作、术语解释）。

输出：在脑中建立论文的章节框架，识别需要详细讲解的核心内容。

第三步：规划讲义结构

根据论文内容设计讲义章节，原则：

• 按论文自然逻辑展开，但不抄原文
• 每章聚焦一个核心概念，用物理图像引入
• 公式要解释"这是什么"、"为什么重要"、"怎么用"
• 避免大段引用原文，转化为自己的讲解语言
• Vault 感知：对已在 vault 中的概念，用 wiki-link 引用回顾；对不在 vault 中的新概念，做完整讲解
• 分层讲解策略：
  • status=Evergreen / In-Progress 的概念 → 引用 vault 笔记，一句话回顾核心，直接进入新内容
  • status=Draft（有空内容）的概念 → 可适当补充推导细节以完善理解
  • 不在 vault 中的概念 → 做完整物理图像 + 公式推导

默认优先采用 start_up.md 式“物理故事线”结构，而不是机械复述论文目录。典型结构可参考：

## 🔬 第一部分：物理载体 / 问题设置
## ⚡ 第二部分：相干操控 / 基础机制
## 🧠 第三部分：核心物理机制 / 关键理论
## 🎨 第四部分：方法设计 / 门方案 / 协议
## 📊 第五部分：实验验证 / 数值结果 / benchmark
## 📐 核心公式摘要
## 💡 新知识点补全提醒
## 📝 更新记录

章节名称要按论文内容定制；每一部分都要像 start_up.md 一样围绕一个具体物理问题展开。

第四步：写 Markdown 讲义

写讲义时的关键规范：

文件命名：[年份]-[论文关键词]-handout.md，例如 2023-parallel-gates-handout.md

文件头：默认参照 start_up.md 的“极速起步”导言风格：

# 🚀 极速起步：论文主题中文讲义（短标题）

> **导言**
> 说明本讲义面向的读者、用户已具备的前置知识、论文解决的核心问题，以及本讲义将如何用物理图像和逐步推导讲清楚。

---

如讲义较长可添加目录；目录必须使用 Obsidian 原生 [[#完整章节标题]] 链接。

章节格式：

## N. 章节标题

### 物理图像：...（用生活/物理类比引入）

### 核心概念
（详细解释，包含公式推导）

### 关键点
（总结要点）

注意事项：

• ## 标题末尾不要加 {#anchor-N}，那是 PDF 用的
• 目录链接用 [[#完整的章节标题]]，纯 Obsidian 原生跳转
• LaTeX 公式用 $$ ... $$（行间）和 $ ... $（行内）
• 避免直接大段引用原文
• 需要 Python 可视化时，直接插入可运行的 matplotlib 代码块（参见 vault CJK-Warning-Free 规范）

第五步：新知识点检测与补全提醒

目的：论文中引入的新概念，可能尚未被收录到 vault 中，提示用户补充。

操作流程：

1. 列出讲义中讲解的所有主要知识点（从各章节标题和内容提取）
2. 逐一对照「第零步」建立的已有知识索引
3. 筛选出「不在任何一个 vault 中的」新知识点
4. 对每个新知识点，做简短介绍（3-5 句物理直觉 + 核心公式/概念）
5. 给出补全建议

输出格式（放在讲义的末尾，## 延伸阅读 之后）：

---

## 💡 新知识点补全提醒

以下概念在本次讲义中出现，但目前尚未收录到你的两个知识库中：

### 1. 新概念名称（英文）

> **简要介绍**：3-5 句话的物理直觉 + 核心公式/概念

> 📍 **建议位置**：`Rydberg atom/New-Concept-Name.md`（Quantum Computing Vault）
> 或 `Knowledge Point/分类/New-Concept-Name.md`（MathPhysCore Vault）

> 🔗 **建议链接**：[[已有概念A]]、[[已有概念B]]

第六步（可选）：PDF 生成

仅当用户明确要求「生成 pdf / 转 pdf / 发 pdf」时执行。完整流程在 pdf-gen skill 的 B. 从 Obsidian 原生讲义转换 中，包含三步：

1. 渲染 Python 代码块为图片（如有）→ 提取、修改为 savefig、运行、替换为图片引用
2. 加锚点 → 给 ## 标题加 {#anchor-N}，目录 [[#标题]] 换 [标题](#anchor-N)
3. 生成 PDF → 用 pdf-gen 脚本，清理临时文件

不动原始 .md 文件。

告知用户：

• markdown 源文件路径
• 提醒目录已使用 Obsidian 原生 [[#]] 链接，可在 Obsidian 中直接点击跳转
• 提醒查看讲义末尾的「新知识点补全提醒」

---

补充流程 A：课程材料讲义（从 physics-lecture-notes 合并）

当用户提供的是课程材料（教材 PDF、课件、作业）而非论文时，适用此流程。目标："学会了就能用" 风格，聚焦怎么用工具，不堆严格数学证明。

步骤

A0. 读材料：用 pdf-read skill 提取内容。如有作业，一并读入。

A1. 按以下结构组织：

1. 核心概念 — 这个工具的物理直觉（一段话）
2. 关键公式 + 物理系记忆法 — 公式 + 怎么从物理上记住它
3. 操作步骤 — 编号的"菜谱式"步骤
4. 常见应用场景 / 物理类比 — 在哪些物理问题中出现
5. 速查表 — 末尾放"什么情况用什么方法"表格

A2. 写作规范：

规则	示例
跳过证明，直接给结论	❌ "由格林公式推导..." → ✅ "Green 函数满足：LG = δ(x-ξ)"
解释物理含义	"这就是库仑定律的积分形式"
用表格对比公式	2D/3D Green 函数对比表
加 物理理解 callout	> **物理理解：** 把连续的源看成点源的叠加
末尾放方法选择器	"什么时候用什么方法" 表格

A3. 输出位置：

• 论文类：Handout by AI/
• 课程类：C:\Personal Profile\Profile\UCAS\[课程名]\

用户不再使用独立的 physics-lecture-notes skill，此流程已合并至此。如有 physics-lecture-notes 需求，直接走此流程。

当用户要求「按新标准升级之前的讲义」时，对已有 .md 文件执行以下改造步骤：

改造步骤

1. 读取完整文件：用 read_file 读取整个文件（不指定 limit，确保完整）

2. 扫描知识库：执行「第零步」的 vault 扫描，建立已有知识索引

3. 补全英文术语：

• 通读全文，逐节识别中文-only 的关键名词
• 对每个术语，先用 search_files 确认全文所有出现位置
• 用 patch 在第一次出现处添加英文标注（格式：中文（English Term））
• 关键技巧：patch 的 old_string 必须包含足够上下文以保证唯一匹配。不要只用单个术语做匹配，用整句话（12-20 字）作为上下文
• 已标注过的术语不再重复标注

4. 检查 vault 引用：

• 确认讲义中已学概念的 wiki-link 引用是否齐全
• 缺少的补上 [[Note-Name]] 格式链接
• 链接应指向 Rydberg atom/ 或 Knowledge Point/ 下的笔记

5. 将 PDF 锚点迁移为 Obsidian 导航：

• 删除所有 ## 标题末尾的 {#anchor-N}
• 将目录中的 [标题](#anchor-N) 替换为 [[#标题]]

6. 追加新知识点提醒：

• 列出讲义所有主要概念，对照第零步的知识索引
• 筛选出不在 vault 中的新概念
• 参照「第五步」的输出格式，追加在文件末尾
• 对新概念给出 3-5 句简介、建议文件路径、建议 wiki-link

7. 验证：

• 确认没有任何 {#anchor-N} 残留
• 确认所有目录链接都是 [[#...]] 格式

坑点

• patch 的 old_string 必须是当前文件中的精确原文。如果 subagent 已经改过了一些内容，必须在 parent 侧 read_file 后重定位再 patch
• 术语在文献中可能有多种中文写法（如「里德堡态」vs「里德伯态」），先确认文件中实际用的是哪种
• 删除 {#anchor-N} 时，注意标题末尾可能还有空格，用 search_files 确认精确原文

---

质量检查清单

生成前自检：

• 讲义有明确的目标读者定位和前置知识说明
• 公式都有物理含义解释，不只是堆砌
• 已完成 vault 扫描（第零步）
• 对已有知识点了引用 vault 笔记（不是重复推导）
• 已列出新知识点并给出补全建议（第五步）
• 目录使用 [[#标题]]，没有 {#anchor-N} 残留
• 每个关键名词首次出现有英文标注
• Python 代码块符合 CJK-Warning-Free 规范，且写入前已用 ast.parse 自检
• 讲义整体达到 Handout by AI/start_up.md 的解释深度：物理图像先行、推导不跳步、每节回答一个清晰物理问题
• 结尾包含 ## 📐 核心公式摘要、## 💡 新知识点补全提醒、## 📝 更新记录
• 表格中的量子态使用 \vert ... \rangle，没有让 | 破坏 Markdown 表格