Study Note Refactor (v2.2)

目标

将“长期积累但逐渐散乱”的学习笔记重构成边界清晰、体系完整、渐进可学、可检索、可持续增量维护的笔记体系，并保持后续维护友好。

关键附加目标（v2.2）：

• 外部链接与图片 绝不丢失
• 整理后链接/图片应优先被放置到“应该放的位置”（可移动、可合并、可归类到更合适的小节）
• 只有“整理后倾向删除/判定主线不必要”的链接/图片，才进入该小节 资料参考 并标注待人工确认
• 必须输出“资源去向账本”，避免出现“是被删还是被忘”的不透明情况

使用场景

• 你希望把零散笔记整理成“可复习、可导航、可持续维护”的知识库
• 你希望先规划结构（清单），再手动迁移正文
• 你希望一次性输出最终重构后的正文版本
• 你希望外链与图片可追踪：每一条都有明确去向与处理原因

可配置参数（建议在调用时显式指定）

交付模式 deliverable_mode

• plan_only：只输出规划清单（新大纲/映射/重命名/迁移步骤/检查清单），不输出最终正文
• full_refactor：输出最终整理后的正文（同时也包含规划清单）

默认建议：full_refactor

阅读范围 read_scope

• headings_only：仅依据标题做规划（不确定性较高，映射需更多 TBD）
• headings_plus_snippets：标题 + 每节少量片段（推荐用于“先出清单/框架”）
• full_text：通读全文（推荐用于 full_refactor）

默认建议：full_text

资源策略（v2.2 修正与强化）

• asset_policy（默认：place_correctly_and_track）

  • place_correctly_and_track：外链/图片绝不丢失；优先按方法论放到“应该放的位置”（可移动/合并/归类）；仅对“倾向删除”的资源放入 资料参考 并标注待人工确认；必须输出资源去向账本
  • preserve_strict：外链/图片绝不丢失且不移动（仅允许修复断链格式）；仍输出资源去向账本（全部为 KEPT）

• references_heading_name（默认：资料参考）

  • 仅用于收纳 TO_REVIEW（倾向删除/主线不必要） 的链接/图片
  • 不是默认收纳所有资源的“垃圾桶”

• asset_ledger（默认：required）

  • required：必须输出资源去向账本
  • off：不输出账本（不推荐）

其他建议参数（可选）

• keep_heading_numbering: false（标题不自动编号；原文自带编号则保留）
• preserve_marks: true（保留强调标记与形态）
• max_intro_lines_per_section: 1（每个一级/二级标题引导注释最多 1 行）
• max_questions: 7（待确认问题最多 3-7 条）

分步计划（流程）

若任务较大，可先创建 task_plan.md 与 notes.md，按阶段更新计划与记录，再进入内容整理。

Step 1. 阅读与抽取（按 read_scope）

• full_text：通读全篇；抽取章节结构、主题域、重复点与跨章节关联
• headings_plus_snippets：提取全部标题；每节读取前 N 行/1-3 段，仅用于判断主题归属与边界
• headings_only：只提取标题树；所有归类与映射需保留较多 TBD

输出：标题树 + 初步诊断要点（不改正文）。

v2.2：在 full_refactor 模式下，必须先抽取“资源清单基线”（外链/图片列表），用于后续账本比对。

Step 2. 整体规划与重划边界

• 重划边界：按“概念/机制/实践/坑点/优化/源码（如适用）”或更合理的知识边界分区
• 归类重组：合并相近主题、拆分过宽章节、移动错位内容
• 形成学习路径：从基础到高级串联，并标注关键前置依赖

输出：新的规划大纲（含引导注释）。

Step 3. 章节内整理（先局部、后整体）

• 先局部优化：在单章节内处理排版、去冗余、结构化要点（允许重写表述以精简啰嗦与增强连贯）
• 再全局一致：统一术语、修复链接锚点、补跨章节引用与“你应该去哪里继续学”

输出：章节质量稳定后再推进下一章，避免全局杂乱返工。

资源处理规则（v2.2 核心）

当 asset_policy=place_correctly_and_track 时，遵循以下规则：

1. 零丢失（Hard）

• 外链与图片绝不删除、绝不消失。
• 每一条外链/图片必须在整理后满足：
  • 要么出现在“应该放的位置”的正文中（可能被移动到别的小节）
  • 要么出现在某个小节的 资料参考 中（仅当 TO_REVIEW）

2. 优先正确归位（Hard）

• 不要求“留在原位置”。
• 必须优先按方法论将资源放到其语义上更合适的位置（与解释段落/主题边界一致）。

3. 资料参考只收纳“待删候选”（Hard）

• 资料参考 仅收纳：整理后判断对主线不必要、重复、旁支，且“倾向删除”的资源。
• 放入 资料参考 的每条资源必须附：
  • （待人工确认是否删除） + 简短原因（例如：重复/旁支/已被更权威资源替代）

4. 不确定就保留在正文（误判保护）

• 若无法确定某资源是否不必要：保留在正文的合适位置，不放 资料参考。

5. 资源去向账本（Hard）

• 必须输出《资源去向账本（Link/Image Ledger）》：
  • 列出整理前的所有外链/图片（至少 URL/路径 + 文本/alt + 原位置）
  • 给出整理后的状态与落点：
    • KEPT：仍在正文且不需要迁移
    • MOVED：移动到更合适的小节正文
    • MERGED：与同义资源合并（但原 URL 仍需可追溯；账本必须标注合并到哪一条）
    • TO_REVIEW：放入 资料参考（待人工确认是否删除）
  • 若状态为 TO_REVIEW / MERGED：必须给简短原因

v2.2 关键：即使正文中只保留“bbb 的链接”，aaa 的链接也必须出现在账本中并标注“MERGED/TO_REVIEW”，并说明去向，否则视为违规（疑似遗忘）。

Step 4. 交付（按 deliverable_mode）

• plan_only：只输出规划清单（不输出整理后的正文）
• full_refactor：输出规划清单 + 最终整理正文（可直接替换原文版本）
• 若 asset_ledger=required：交付中必须包含《资源去向账本》

执行检查清单（可勾选验收）

必须满足（Hard Requirements）

• 标题不启用/生成自动编号（原文标题若自带编号则保留）
• 保留原有强调标记与形态：==高亮==、<u>、<mark>、粗斜删、行内代码、代码块围栏、引用块、分隔线、Setext 标题
• 不改变代码语义、不破坏代码块结构
• 移动章节后修复链接与锚点，确保引用可用（或明确标记待修复项）
• 列表缩进、空行、段落排版一致；避免“忽长忽短”的混乱排版
• 标题层级建议不超过 4 层（除非内容确实需要）

外部链接与图片保全（v2.2 新增 Hard Requirements）

• 外部链接 零丢失：每条原始链接都能在正文或 资料参考 或“资源去向账本”中找到明确去向
• 图片 零丢失：![]() / <img> 等均可追踪，整理后仍存在于正文或 资料参考
• 资料参考 只收纳 TO_REVIEW（倾向删除） 的资源，且每条带“待人工确认是否删除”与原因
• 输出《资源去向账本》并可用它解释任意一条资源（避免“忘了还是删了”的不透明）

允许但需克制（Soft Rules）

• 允许添加“引导注释/必要注释”，但不扩写成新教程
• 允许等价替换强调标记仅在必要时发生，且满足：
  • 强调强度不降低
  • 含义更清晰或渲染更一致
  • 优先保留原写法；必要时“保留原写法 + 增强补标记”
• 允许将“倾向删除”的链接/图片移动到 资料参考（仅当 asset_policy=place_correctly_and_track）

非目标（明确不做，除非用户要求）

• 不做事实正确性校验/纠错（除非用户明确要求）
• 不补充大量新内容（只做结构、引导、注释、排版与去冗余）
• 不引入新的编号体系到标题中

标题与命名规范（补充）

• 标题用可检索的术语/名词短语，避免弱标题：
  • 避免：杂谈/随记/一些坑/总结一下/记录/待完善
  • 倾向：概念/机制/协议/模型/实践/排障/性能/源码
• 标题尽量短而准（过长拆成“标题 + 引导注释”）
• 不在标题里写步骤编号；步骤编号只放正文列表

输出格式（强约束）

A) 新目录/章节大纲（含引导注释）

• H1 …
  • H2 …（引导注释：…）
    • H3 …

B) 主要移动映射（旧 → 新）

C) 重命名建议（仅列需要的）

• 旧标题 -> 建议标题（原因：更标准/更短/更可检索/边界更准确）

D) 待确认问题（最多 3-7 条）

• …

E) 执行检查清单勾选情况

• 必须满足：✅/⚠️（若⚠️需说明原因与待办）
• 允许但克制：✅/⚠️

F) 最终整理后的正文（仅当 deliverable_mode=full_refactor）

• 输出完整正文
• 确保链接/锚点可用、格式与规则一致、强调标记尽量保真
• 若启用 asset_policy=place_correctly_and_track：
  • 链接/图片优先归位到应该放的位置
  • 仅“倾向删除”的链接/图片放入对应小节的 资料参考（待人工确认是否删除）

G) 资源去向账本（Link/Image Ledger）（当 asset_ledger=required）

提示词模板（建议）

请按 skill: learning-notes-organizer 执行。

目标文件：{目标文件路径}
交付模式：{deliverable_mode=plan_only|full_refactor}
阅读范围：{read_scope=headings_only|headings_plus_snippets|full_text}

资源策略：
asset_policy=place_correctly_and_track
asset_ledger=required
references_heading_name=资料参考

要求：
- 标题不自动编号（原文已有编号保留）
- 尽量保留原文强调标记与形态（==、<u>、Setext 等）
- 外部链接与图片绝不丢失：优先归位到应该放的位置；仅“倾向删除”的放入对应小节的“资料参考”（待人工确认是否删除）
- 必须输出资源去向账本（Link/Image Ledger），避免“删了还是忘了”的不透明
- 先给出 A-E（大纲/映射/重命名/问题/验收）
- 若 deliverable_mode=full_refactor，再给 F 最终正文与 G 资源账本