paperflow-notes

name	paperflow-notes
description	论文笔记生成（手动入口，不属于每日推荐自动流水线）。补充概念库，为推荐论文生成完整笔记， 链接回填到推荐文件；目录页默认自动刷新，git 自动化默认关闭。 触发词："批量笔记"、"跑一下论文笔记"、"为这些论文生成笔记"

开始前: 先说一声 "开始整理笔记 📝" 并告知今天日期。

论文笔记 (Concepts + Notes + Backfill)

你是 用户的论文笔记系统（手动入口）。补充概念库 → 生成论文笔记 → 链接回填 → 刷新目录页。

重要：每日论文推荐完成后，不要自动运行本 skill。只有用户明确要求批量笔记或指定论文生成笔记时，才进入本流程。用户说"今日论文推荐/最近 N 天论文推荐"时，应只完成抓取和点评推荐，不要自动生成"必读"论文笔记。

Step 0: 读取共享配置

先读取 ../_shared/user-config.json，如果 ../_shared/user-config.local.json 存在，再用它覆盖默认值。

显式生成并在后续统一使用这些变量：

• VAULT_PATH
• NOTES_PATH
• CONCEPTS_PATH
• DAILY_PAPERS_PATH
• AUTO_REFRESH_INDEXES
• GIT_COMMIT_ENABLED
• GIT_PUSH_ENABLED
• ENRICHED_INPUT = /tmp/daily_papers_enriched.json

其中：

• NOTES_PATH = {VAULT_PATH}/{paper_notes_folder}
• CONCEPTS_PATH = {NOTES_PATH}/{concepts_folder}
• DAILY_PAPERS_PATH = {VAULT_PATH}/{daily_papers_folder}
• GIT_PUSH_ENABLED 只有在 GIT_COMMIT_ENABLED=true 时才可能为真

后续步骤统一使用上面的变量。

前置检查

1. 检查 /tmp/daily_papers_enriched.json 是否存在
2. 检查今天的推荐文件 {DAILY_PAPERS_PATH}/YYYY-MM-DD-论文推荐.md 是否存在
3. 如果任一不存在，告知用户需要先运行前置步骤，然后停止

工作流程

Step 1: 概念库补充

1a: 提取概念列表

1. 扫描今天的推荐文件，提取所有 [[...]] 链接
2. 额外从 /tmp/daily_papers_enriched.json 的 method_names 列表中提取所有方法名
3. 合并去重

1b: 过滤 只保留以下类型的术语（跳过通用词、论文自身名称、公司名、人名）：

• 方法/模型名（如 Q-Former, Parseval Regularization, CVAE, PCM）
• 数据集名（如 AMASS, LaFan1, MotionX, AndroidCode）
• 仿真器/框架名（如 OmniGibson, IsaacLab, Acados）
• 技术概念名（如 System Level Synthesis, Consistency Model）

1c: 别名归一化（必须先做）

python3 ../_shared/concept_alias_resolver.py --resolve "<概念名>"

把候选概念名先 normalize 到 canonical（QFormer → Q-Former、BLIP2 → BLIP-2），避免重复建笔记。

1d: 创建缺失的概念笔记（自动归类） 对每个 canonical 概念名，检查 {CONCEPTS_PATH}/ 下是否已存在（搜索所有子目录）。对于缺失的概念，根据概念类型自动归类到对应子目录，不要全扔 0-uncategorized/。文件名也用 canonical 形式。

分类规则见 ../paperflow-reader/references/concept-categories.md

概念笔记模板见 ../paperflow-reader/references/concept-categories.md

Step 2: 论文笔记生成

为推荐论文生成完整论文笔记：

1. 从今天的推荐文件中，读取分流表，筛选出标记为"必读"的论文（"值得看"和"可跳过"的不生成笔记）
2. 质量检查已有笔记（用脚本，不是只看文件是否存在）：

   python3 ../_shared/note_quality_check.py "{笔记完整路径}"
   

   • exit 0 = PASS → 跳过此论文
   • exit 1 + STATUS=FAIL → 删除旧文件，重新调用 paperflow-reader 生成
   • exit 1 + STATUS=blocked-by-source → 不要重新生成（重新生成也只能拿到 abs-only 内容）；保留旧笔记并在最终汇总里告知用户"该论文的笔记内容受限于源不完整"
   • 检查项包括：行数 ≥ 80（防止纯骨架）、≥3 个具体数字、≥1 个对比 baseline 或表格行、≥5 个 [[wikilink]]、≥2 个 $$ 公式块、≥1 张图、必需 section（仅当 template_version: integrated 时检查）
3. 对每篇需要生成/重新生成的论文，使用 Task agent 调用 /paperflow-reader skill（传入 arXiv 链接）
   • 不要指定固定的输出路径，让 paperflow-reader 自行决定文件名和分类目录
   • paperflow-reader 会用方法名缩写作为文件名（如 DAPL.md），并自动分类到正确子目录
   • agent 完成后，用 find 或 Glob 找到实际生成的笔记文件路径和文件名，记录下来供 Step 3 回填用
4. 笔记生成后，paperflow-reader 会自动补充概念库，无需重复

铁律：不论论文数量多少，"必读"的论文全部生成笔记，一篇不能少。 耗时长是正常的，不是偷懒的理由。如果 context 接近上限，先把已完成内容落盘； 只有在 GIT_COMMIT_ENABLED=true 时才允许做阶段性 commit。然后告知用户剩余论文需要在新会话中继续，绝对不能默默跳过。

⚠️ 笔记质量硬性要求

绝对禁止自己手写简化版笔记。每篇论文必须通过 paperflow-reader skill 生成。 不要因为"怕 context overflow"或"论文太多"就自己写个 70 行的骨架糊弄过去。 如果当前会话上下文接近上限，可以开启新的 Claude Code 会话继续剩余论文；但不能跳过任何一篇必读论文。

笔记质量由 paperflow-reader skill 自身保证（模板、公式、图片、概念链接等规则均在 paperflow-reader 中定义）。

🔍 生成后质量验证（每篇必须执行）

每篇笔记生成后，立即跑：

python3 ../_shared/note_quality_check.py "{笔记完整路径}"

行为：

• PASS：继续下一篇
• FAIL（exit 1，未 blocked-by-source）：删除文件并重新调用 paperflow-reader 生成。不要手动改笔记凑指标 — 失败大概率是 paperflow-reader 中途偷工，重跑通常能修
• blocked-by-source（content_source ∈ {webfetch-abs, search-only} 或 incomplete=true）：不要删；保留笔记并把这篇加进最终汇总的"内容受限论文"清单，告知用户"建议 24h 后重试"或"PDF 不可用"

绝不允许：跳过验证、自己手写 70 行骨架、看到文件存在就当作合格。

Step 3: 笔记链接回填

论文笔记全部生成完成后，将笔记链接回填到当天的推荐文件中。

3a: 收集已有笔记

用 Glob 扫描 {NOTES_PATH}/ 下所有子目录（跳过 {CONCEPTS_PATH}），获取所有 .md 文件列表，建立 {文件名(不含.md): 相对路径} 的索引。

3b: 匹配论文与笔记

读取当天推荐文件 {DAILY_PAPERS_PATH}/YYYY-MM-DD-论文推荐.md，对每篇论文（### N. 开头的段落）：

1. 从论文标题中提取方法名/模型名（通常是标题冒号前的缩写，如 "DM0"、"BPP"、"PA3FF"）
2. 与 3a 的笔记索引匹配（不区分大小写）
3. 也检查富化数据的 method_names（如果有残留数据）

3c: 插入笔记链接 + 修正分流表

对匹配到笔记的论文，在 - **来源**: 行之后插入一行：

- 📒 **笔记**: [[笔记名]]

其中 笔记名 是不含 .md 后缀的文件名（Obsidian 会自动解析到正确路径）。

• 如果该论文已有 📒 **已有笔记** 或 📒 **笔记** 行，跳过不重复添加
• 使用 Edit 工具逐篇插入，确保不破坏文件其他内容

3d: 同步修正分流表 wikilink

paperflow-reader 生成笔记时会自行决定文件名（通常用方法名缩写，如 DAPL），可能与分流表中的 [[wikilink]] 不一致（如分流表写了 [[Emerging Extrinsic Dexterity]]）。因此回填时必须检查并修正：

1. 对每篇已生成笔记的论文，拿到实际笔记文件名（如 DAPL）
2. 在分流表（## 分流表 区域）中查找该论文的 [[...]] 链接
3. 如果 wikilink 文本与实际笔记文件名不一致，用 Edit 替换为 [[实际文件名]]
4. 同样检查论文详评标题下方是否有不一致的 wikilink，一并修正

Step 4: 刷新 MOC 索引

只有在 AUTO_REFRESH_INDEXES=true 时才执行：

python3 ../_shared/generate_concept_mocs.py
python3 ../_shared/generate_paper_mocs.py

默认配置下这个开关是开启的，所以新增的概念和论文笔记通常会自动反映到各分类目录页中。

Step 5: Git 提交

仅当 GIT_COMMIT_ENABLED=true 时执行，并且必须先检查：

1. VAULT_PATH/.git 存在
2. git add -A 后确实有 staged changes

满足条件后才 commit：

cd {VAULT_PATH} && git add -A && git commit -m "daily papers: notes YYYY-MM-DD"

只有在 GIT_PUSH_ENABLED=true 且仓库已配置远端时才 push。

输出

完成后告知用户：

• 创建了多少个新概念
• 生成了多少篇论文笔记
• 回填了多少个笔记链接
• 流水线全部完成

注意事项

• 如果前置文件不存在，必须先运行前面的步骤
• paperflow-reader skill 会自动处理概念库补充，不要重复创建
• 本 skill 只在用户明确请求批量笔记时运行；不要被每日推荐自动触发
• 默认仅为"必读"论文生成笔记，"值得看"不生成；如果用户指定具体论文列表，以用户指定为准
• 默认自动刷新目录页，但默认不做 git commit / push
• 绝对禁止以下偷懒行为：
  • 自己手写 70 行骨架笔记代替 paperflow-reader 输出
  • 以"context overflow"为由跳过论文不生成笔记
  • 看到文件已存在就跳过，不检查质量
  • 生成笔记后不做质量验证
• 如果 context 真的接近上限：先保存已完成的笔记；只有在 GIT_COMMIT_ENABLED=true 时才 commit。然后明确告知用户还有 N 篇未完成，需要在新会话中运行 跑一下论文笔记 继续。绝不能默默跳过