learning-notes-organizer

Learning Notes Organizer (v3)

目标

将散乱的学习笔记重构成边界清晰、结构完整、渐进可学、可检索、长期可维护的笔记体系。

两阶段工作流（Plan-and-Execute）

Phase 1 — 诊断归类（Diagnose & Classify）

做什么： 只读不写，产出结构规划清单。

1. 提取标题树（H1-H6），为每个标题输出一句话含义与一句话引导注释（"读完你会…"）
2. 诊断问题：重复/交叉、过宽/过碎、顺序不合理（缺前置/高级内容提前）、命名不规范
3. 提出新大纲（基础→机制→实践→坑点/优化，按内容需要调整）
4. 旧→新映射表，每条标注动作标签（KEEP/MOVE/MERGE/SPLIT/RENAME/DROP/TBD）
5. 重命名建议（仅列确实需要的）
6. 若 scope=sections：标注指定章节的越界内容候选（粗粒度，Phase 2 细化）
7. 若 scaffold=true：生成 <base>-待整理.md 框架文件（详见 Scaffold 格式）

输出： 清单（大纲/映射/重命名/问题），以及 scaffold 文件路径+内容（若启用）。

---

Phase 2 — 精修交付（Refactor & Deliver）

做什么： 对 scope 范围内的内容执行精修重写，并处理越界碎片。

1. 章节精修：精简啰嗦、增强连贯、边界清晰、术语一致、标注学习路径关联
2. 执行中越界路由：精修时发现不属于当前边界的碎片内容，路由到正确章节（或新增"待整理"子节暂存），并生成路由清单
3. 资源追踪（asset_policy=place_correctly_and_track 时）：外链/图片零丢失，输出资源去向账本
   • 图片描述检测：扫描所有图片引用，检测 alt 为空、或 alt 仅为文件名（含扩展名如 .png/.jpg）、或为占位符（如"在这里插入图片描述"）的条目
   • 若发现 ≥1 张缺失语义描述的图片：在资源账本 G 中用 ⚠️ ALT_MISSING 标注，并在输出末尾提示："发现 N 张图片缺少语义描述，建议执行 /image-alt-title-filler 补全（账本中已标注）"
   • 不自动调用，由用户决定是否运行 image-alt-title-filler
4. 范围外章节最小改动（仅允许接收路由内容，不做重写）

输出： 可直接替换的 Markdown + 越界路由清单 + 资源账本（若启用）。

---

参数

必填

• target_file：目标 Markdown 文件路径

核心参数

参数	可选值	默认	说明
scope	full / sections: ["章节1", ...]	full	全文 or 指定章节（支持标题名或路径）
deliverable_mode	plan_only / full_refactor	full_refactor	只做 Phase 1 / 两阶段都做
scaffold	true / false	false	是否生成待整理框架文件（plan_only 时常用）

资源策略

参数	可选值	默认
asset_policy	place_correctly_and_track / preserve_strict	place_correctly_and_track
asset_ledger	required / off	required

• place_correctly_and_track：外链/图片优先归位到语义合适的位置；仅"倾向删除"的放入 资料参考；必须输出账本
• preserve_strict：不移动资源，只修复断链格式；仍输出账本

---

执行步骤

deliverable_mode=plan_only

1. Read：提取标题树 + 每节少量片段（判断主题归属，不通读全文）
2. Diagnose：按 Phase 1 诊断归类
3. Deliver：输出清单 A-D；若 scaffold=true，生成框架文件

deliverable_mode=full_refactor

1. Read：通读全文（或指定章节全文 + 其余标题）
2. Diagnose：Phase 1 诊断归类（必须先出清单供参考，再进入 Phase 2）
3. Refactor：Phase 2 精修 + 越界路由
4. Deliver：输出清单 A-D + 精修后正文 E + 路由清单 F + 资源账本 G（若启用）

---

输出格式

A) 新规划大纲（含引导注释）

H1 ...
  H2 ...（引导注释：读完你会…）
    H3 ...

B) 旧→新映射表

旧标题（含层级）	动作	新标题路径	图片	备注

动作标签：KEEP / MOVE / MERGE / SPLIT / RENAME / DROP / TBD

图片列：—（无图）/ ✓（有图且有 alt）/ ⚠️（有图但缺 alt/title）

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

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

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

E) 精修后正文（仅当 full_refactor）

• 输出完整正文（scope=sections 时只输出被重构章节，含必要父级标题上下文）
• 标题不自动编号；保留原有强调标记（==高亮==、<u>、<mark>、代码块等）
• 末尾追加"整理记录"区块（内嵌 F）

F) 越界路由清单（full_refactor 时输出）

MIG-ID	来源位置	内容块简述	目标路径	落点（章节/待整理）

同时追加写入到 E 末尾的"整理记录"区块，便于文档内留档。

G) 资源去向账本（asset_ledger=required 时输出）

类型	显示文本/alt	URL/路径	原位置	状态	新位置	说明

状态：KEPT / MOVED / MERGED / TO_REVIEW / ⚠️ ALT_MISSING（图片缺失语义描述，建议用 /image-alt-title-filler 补全）

---

Scaffold 文件格式（scaffold=true 时生成）

写入路径： dirname(target_file)/<base>-待整理.md（已存在则追加 -v2/-v3）

结构：

1. 顶部元信息（源文件、生成时间、说明）
2. 新大纲与迁移工作区（每个新标题一个迁移块）
3. 附录 A：旧→新映射表（全量）
4. 附录 B：重命名建议
5. 附录 C：待确认问题
6. 附录 D：迁移顺序建议

迁移块模板：

### <新标题>
> 引导注释：<一句话>

**来源旧标题：**
- (MOVE) `旧标题1`
- (MERGE) `旧标题2`

**重命名建议（仅列需要的）：**
- `旧标题2` → `建议标题`（原因：...）

**迁移要点：**
- <注意事项>

⬇️ 在下面粘贴原文内容 ⬇️

（把原文复制到这里）

---

执行约束

必须满足

• 标题不启用自动编号（原文已有编号保留）
• 保留强调标记：==高亮==、<u>、<mark>、粗/斜/删、行内代码、代码块、引用块、Setext 标题
• 不改变代码语义，不破坏代码块结构
• 外链/图片零丢失：每条都有明确去向（正文/资料参考/账本）
• 资料参考 只收纳"倾向删除"的资源，且每条附"待人工确认"与原因

不做（非目标）

• 不做事实正确性校验
• 不补充大量新内容
• 不引入新的编号体系

---

调用模板

请按 learning-notes-organizer 执行。

target_file: <path/to/file.md>
scope: full                          # 或 sections: ["章节A", "章节B"]
deliverable_mode: full_refactor      # 或 plan_only
scaffold: false                      # plan_only 时建议 true

asset_policy: place_correctly_and_track
asset_ledger: required

典型场景对照：

场景	参数组合
只要规划清单和框架文件	deliverable_mode=plan_only, scaffold=true
直接整理全文	deliverable_mode=full_refactor, scope=full
只整理指定几个章节	deliverable_mode=full_refactor, scope=sections:[...]

---

自我进化

本 skill 支持渐进式进化。当实战中发现行为偏差，参照 EVOLUTION.md 协议执行迭代升级。