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 ...

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） 新位置（标题路径/资料参考） 说明

提示词模板（建议）

请按 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 资源账本