Section Refactor with Todo Routing (v2)
目的
在不必全篇重构的情况下，完成三件事：
- 全局导航：抽取文件内所有标题（H1-H6），并为每个标题输出：
- 一句话“含义/本节讲什么” - 一句话“引导注释：读完你会…”
- 局部重构：只对用户指定章节（1~N 个，可变）进行重构整理（精简啰嗦、增强连贯、边界清晰、学习路径更顺滑、术语一致）。
- 越界内容路由：指定章节中若存在不属于该章节边界的内容块：
- 路由到更合适的目标标题下； - 若目标标题下缺少合适容器或需要暂存，则在该目标标题下新增子标题 待整理 并把内容放入其中； - 便于用户后续“点名某个待整理模块”继续整理。
依赖
$learning-notes-organizer
- 用于边界判断、归类、学习路径、精修重写、格式保真等规范（本 skill 不重复展开细则）
$planning-with-files
- 用于组织执行流程与交付结构（抽取→规划→映射→交付）
输入
必填：
target_file: 目标 Markdown 文件路径focus_sections: 需要重构的章节列表（1~N 个，可变）
- 支持：标题名（模糊）或标题路径（精确） - 示例： - ["学习资源与概览", "核心概念与内存背景"] - ["核心概念与内存背景/ByteBuf", "Pipeline/Handler"]
可选参数（v2 新增，推荐默认即可）：
读取/抽取
heading_level_support: 默认H1-H6meaning_source:"title_plus_snippets"|"full_text"
- 默认 "title_plus_snippets"（含义/引导注释基于标题+少量内容）
intro_policy:"prefer_existing_then_generate"|"generate_if_missing"|"existing_only"
- 默认 "prefer_existing_then_generate"
匹配策略
section_match_policy:"prefer_path_then_title"|"title_only"
- 默认 "prefer_path_then_title"
duplicate_title_policy:"ask_tbd"|"pick_best_match_with_reason"
- 默认 "pick_best_match_with_reason"（并在摘要说明匹配理由；实在不确定标记 TBD）
越界内容与待整理容器
routing_unit:"subsection"|"paragraph_block"
- 默认 "paragraph_block"（更细粒度；必要时可按小节搬）
todo_bucket_name: 默认"待整理"add_todo_bucket_policy:"only_when_needed"|"always_when_routing"
- 默认 "only_when_needed"
todo_insert_position:"top_of_target_section"|"bottom_of_target_section"
- 默认 "top_of_target_section"（更醒目）
范围外改动策略
outside_scope_edit_policy:"minimal_only"|"allow_small_fixes"
- 默认 "minimal_only" - minimal_only：只允许在目标标题下新增待整理并插入迁移内容 - allow_small_fixes：在 minimal 基础上，允许做小修复（断链/术语一致/必要过渡），但不得扩展为范围外重写
可追踪标记（便于后续点名继续整理）
migration_id_policy:"auto_ids"|"none"
- 默认 "auto_ids"（为迁移内容块生成可引用 ID）
执行步骤（必须按 $planning-with-files 输出）
Step 1 — 抽取（Extract）
- 提取完整标题树（H1-H6，含层级路径）
- 为每个标题输出：
- 含义：一句话“这节讲什么” - 引导注释：一句话“读完你会…”
- 引导注释生成遵循
intro_policy
Step 2 — 规划（Plan）
- 仅针对
focus_sections：
- 给出章节边界（应包含/不包含什么） - 调整内部结构与顺序（基础→机制→实践→坑点/优化；按内容需要） - 标记越界内容块（按 routing_unit）
Step 3 — 映射（Map）
- 对指定章节内内容块：
- 旧位置 → 新位置（同章内部重排）
- 对越界内容块：
- 来源位置 → 目标标题路径 - 若目标标题下缺少合适容器或需要暂存： - 新增子标题 待整理（按 todo_bucket_name） - 将内容放入该 待整理（按 todo_insert_position）
- 若
migration_id_policy=auto_ids：
- 为每个迁移内容块生成 MIG-xxx 标记，便于后续点名继续整理
Step 4 — 交付（Deliver）
- 输出“全标题索引+含义+引导注释”
- 输出“指定章节重构后的最终 Markdown”（可直接替换回原文件）
- 输出“迁移与待整理新增清单”（可追踪、可复盘）
- 输出“变更摘要”
交付物格式（必须包含）
A) 全标题索引（H1-H6）+ 含义 + 引导注释
- 用树形层级展示（路径清晰）
- 每个标题至少两行：
- 含义：... - 引导注释：...
B) 指定章节重构结果（可直接替换的 Markdown）
- 仅输出被重构的章节（包含必要的父级标题上下文）
- 标题不自动编号；强调标记/代码块结构尽量保真（细则由 learning-notes-organizer 管）
C) 越界内容路由清单（从指定章节迁出）
| MIG-ID | 来源位置（章节/小节） | 内容块简述 | 目标标题路径 | 落点（目标标题/待整理） |
|---|
D) 新增 待整理 清单
| 目标标题路径 | 是否新增 待整理 | 插入位置（bottom） | 放入了哪些 MIG-ID/内容块 |
|---|
调用模板（推荐）
使用 $section-refactor-with-todo-routing（v2）
target_file: <path/to/file.md>
focus_sections: ["章节1", "章节2", ...]
# 可选：
outside_scope_edit_policy: minimal_only
add_todo_bucket_policy: only_when_needed
migration_id_policy: auto_ids