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 时，遵循以下规则：
- •零丢失（Hard）
- •外链与图片绝不删除、绝不消失。
- •每一条外链/图片必须在整理后满足：
- •要么出现在“应该放的位置”的正文中（可能被移动到别的小节）
- •要么出现在某个小节的
资料参考中（仅当 TO_REVIEW）
- •优先正确归位（Hard）
- •不要求“留在原位置”。
- •必须优先按方法论将资源放到其语义上更合适的位置（与解释段落/主题边界一致）。
- •资料参考只收纳“待删候选”（Hard）
- •
资料参考仅收纳：整理后判断对主线不必要、重复、旁支，且“倾向删除”的资源。 - •放入
资料参考的每条资源必须附：- •
（待人工确认是否删除）+ 简短原因（例如：重复/旁支/已被更权威资源替代）
- •
- •不确定就保留在正文（误判保护）
- •若无法确定某资源是否不必要：保留在正文的合适位置，不放
资料参考。
- •资源去向账本（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 ...
- •H2 ...（引导注释：...）
B) 主要移动映射（旧 → 新）
| 旧节(含层级) | 动作(KEEP/MOVE/MERGE/SPLIT/RENAME/DROP/TBD) | 新节路径 | 备注 |
|---|
C) 重命名建议（仅列需要的）
- •
旧标题->建议标题（原因：更标准/更短/更可检索/边界更准确）
D) 待确认问题（最多 3-7 条）
- •...
E) 执行检查清单勾选情况
- •必须满足：✅/⚠️（若⚠️需说明原因与待办）
- •允许但克制：✅/⚠️
F) 最终整理后的正文（仅当 deliverable_mode=full_refactor）
- •输出完整正文
- •确保链接/锚点可用、格式与规则一致、强调标记尽量保真
- •若启用
asset_policy=place_correctly_and_track：- •链接/图片优先归位到应该放的位置
- •仅“倾向删除”的链接/图片放入对应小节的
资料参考（待人工确认是否删除）
G) 资源去向账本（Link/Image Ledger）（当 asset_ledger=required）
| 资源类型 | 原文显示文本/alt | URL/路径 | 原位置（标题路径） | 状态（KEPT/MOVED/MERGED/TO_REVIEW） | 新位置（标题路径/资料参考） | 说明 |
|---|
提示词模板（建议）
text
请按 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 资源账本