| 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 标准的核心特征
- 极速起步式导言：开头明确读者画像、已具备前置知识、本文要解决的论文问题，并用亲切但严谨的中文建立学习动机。
- 按物理故事线组织，而不是机械复述论文：章节应沿着“物理载体 → 相干操控 → 关键机制 → 门/协议设计 → 实验验证 → 核心公式 → 新知识点”的逻辑展开。允许重排论文结构，只要更利于理解。
- 物理图像先行：每个大节先回答“这件事在物理上是什么、为什么要这样做”，再进入 Hamiltonian、态矢量、矩阵或实验参数。
- 循循善诱的推导：公式必须逐步解释，不能只给结果。关键推导要写出假设、代入、近似、物理含义和适用条件。
- 面向用户背景降维讲清楚：默认面向物理系本科高年级/刚进入科研训练的读者。可使用量子力学表象、矩阵、Hamiltonian、角动量基础，但遇到新工具（如绝热消去、暗态、SPAM、benchmarking）必须自包含解释。
- 中英双语术语首现：关键术语第一次出现必须给出英文，如“暗态（Dark State）”“相干 dressing（coherent dressing）”。后续可用中文或缩写。
- Callout 强化直觉与易错点：优先使用
[!tip] 写物理直觉、[!info] 写补充背景、[!warning] 写符号约定与常见误解。
- Python 图表作为理解工具：凡是出现动力学、势能曲线、脉冲波形、衰减拟合、能级结构等可视化对象，应加入可运行 Python + matplotlib 代码块；图表内部文字和代码注释一律英文，并在写入前用
ast.parse 检查语法。
- 保留 Obsidian 原生性：使用 wiki-link 引用已有知识点；目录如需存在，使用
[[#完整标题]]；不要在标题后添加 {#anchor-N}；不要把 wiki-link 包在反引号里。
- 结尾必须有三件套：
## 📐 核心公式摘要、## 💡 新知识点补全提醒、## 📝 更新记录。
- 核心公式表的 Markdown 安全：表格中的量子态必须写作
\vert 0\rangle，不要写 $|0\rangle$，避免 | 破坏 Markdown 表格。
- 学习进度 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 笔记。
扫描内容：
- Quantum Computing Vault：
C:\Personal Profile\Profile\ScienceResearch\Quantum Computing\Rydberg atom\ 下的所有知识点笔记
- MathPhysCore Vault：
C:\Personal Profile\Profile\MathPhysCore\Knowledge Point\ 下的所有笔记
- 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 提取文本内容
读取摘要、作者、单位、关键图表标题，建立对论文的第一印象。
第二步：分析论文结构（深度阅读）
通过以下方式深度理解论文：
- 读摘要：提取核心创新点、方法、关键结果
- 读引言：理解动机、领域背景、科学问题
- 读方法/理论部分：理解核心技术路线
- 读结果：关键数据、图表解读
- 读结论：意义、局限性、延伸方向
用 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 中，提示用户补充。
操作流程：
- 列出讲义中讲解的所有主要知识点（从各章节标题和内容提取）
- 逐一对照「第零步」建立的已有知识索引
- 筛选出「不在任何一个 vault 中的」新知识点
- 对每个新知识点，做简短介绍（3-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 原生讲义转换 中，包含三步：
- 渲染 Python 代码块为图片（如有）→ 提取、修改为 savefig、运行、替换为图片引用
- 加锚点 → 给
## 标题加 {#anchor-N}，目录 [[#标题]] 换 [标题](#anchor-N)
- 生成 PDF → 用 pdf-gen 脚本，清理临时文件
不动原始 .md 文件。
告知用户：
- markdown 源文件路径
- 提醒目录已使用 Obsidian 原生
[[#]] 链接，可在 Obsidian 中直接点击跳转
- 提醒查看讲义末尾的「新知识点补全提醒」
补充流程 A：课程材料讲义（从 physics-lecture-notes 合并）
当用户提供的是课程材料（教材 PDF、课件、作业）而非论文时，适用此流程。目标："学会了就能用" 风格，聚焦怎么用工具，不堆严格数学证明。
步骤
A0. 读材料：用 pdf-read skill 提取内容。如有作业，一并读入。
A1. 按以下结构组织：
- 核心概念 — 这个工具的物理直觉（一段话）
- 关键公式 + 物理系记忆法 — 公式 + 怎么从物理上记住它
- 操作步骤 — 编号的"菜谱式"步骤
- 常见应用场景 / 物理类比 — 在哪些物理问题中出现
- 速查表 — 末尾放"什么情况用什么方法"表格
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 确认精确原文
质量检查清单
生成前自检：
