| name | learning-notes-organizer |
| description | 对 Markdown 学习笔记做结构重构与精修：两阶段 Plan-and-Execute 工作流——先诊断归类（出清单/大纲/映射/scaffold），再精修交付（重写正文、越界路由、资源追踪）。支持全文或指定章节两种 scope；支持只出清单或直接输出整理后正文。 |
| user-invocable | true |
| metadata | {"short-description":"学习笔记整理（全文或指定章节；先归类再精修；支持只出清单或输出全文）","version":"v3.0"} |
Learning Notes Organizer (v3)
目标
将散乱的学习笔记重构成边界清晰、结构完整、渐进可学、可检索、长期可维护的笔记体系。
两阶段工作流（Plan-and-Execute）
Phase 1 — 诊断归类（Diagnose & Classify）
做什么： 只读不写，产出结构规划清单。
- 提取标题树（H1-H6），为每个标题输出一句话含义与一句话引导注释（"读完你会…"）
- 诊断问题：重复/交叉、过宽/过碎、顺序不合理（缺前置/高级内容提前）、命名不规范
- 提出新大纲（基础→机制→实践→坑点/优化，按内容需要调整）
- 旧→新映射表，每条标注动作标签（KEEP/MOVE/MERGE/SPLIT/RENAME/DROP/TBD）
- 重命名建议（仅列确实需要的）
- 若
scope=sections：标注指定章节的越界内容候选（粗粒度，Phase 2 细化）
- 若
scaffold=true：生成 <base>-待整理.md 框架文件（详见 Scaffold 格式）
输出： 清单（大纲/映射/重命名/问题），以及 scaffold 文件路径+内容（若启用）。
Phase 2 — 精修交付（Refactor & Deliver）
做什么： 对 scope 范围内的内容执行精修重写，并处理越界碎片。
- 章节精修：精简啰嗦、增强连贯、边界清晰、术语一致、标注学习路径关联
- 执行中越界路由：精修时发现不属于当前边界的碎片内容，路由到正确章节（或新增"待整理"子节暂存），并生成路由清单
- 资源追踪（
asset_policy=place_correctly_and_track 时）：外链/图片零丢失，输出资源去向账本
- 图片描述检测：扫描所有图片引用，检测
alt 为空、或 alt 仅为文件名（含扩展名如 .png/.jpg）、或为占位符（如"在这里插入图片描述"）的条目
- 若发现 ≥1 张缺失语义描述的图片：在资源账本 G 中用
⚠️ ALT_MISSING 标注，并在输出末尾提示："发现 N 张图片缺少语义描述，建议执行 /image-alt-title-filler 补全（账本中已标注）"
- 不自动调用，由用户决定是否运行 image-alt-title-filler
- 范围外章节最小改动（仅允许接收路由内容，不做重写）
输出： 可直接替换的 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
- Read：提取标题树 + 每节少量片段（判断主题归属，不通读全文）
- Diagnose：按 Phase 1 诊断归类
- Deliver：输出清单 A-D；若 scaffold=true，生成框架文件
deliverable_mode=full_refactor
- Read：通读全文（或指定章节全文 + 其余标题）
- Diagnose：Phase 1 诊断归类（必须先出清单供参考，再进入 Phase 2）
- Refactor：Phase 2 精修 + 越界路由
- 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）
结构：
- 顶部元信息（源文件、生成时间、说明）
- 新大纲与迁移工作区（每个新标题一个迁移块）
- 附录 A：旧→新映射表（全量）
- 附录 B：重命名建议
- 附录 C：待确认问题
- 附录 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 协议执行迭代升级。
