Section Refactor with Todo Routing (v2)

目的

在不必全篇重构的情况下，完成三件事：

1. •全局导航：抽取文件内所有标题（H1-H6），并为每个标题输出：
   • •一句话“含义/本节讲什么”
   • •一句话“引导注释：读完你会…”
2. •局部重构：只对用户指定章节（1~N 个，可变）进行重构整理（精简啰嗦、增强连贯、边界清晰、学习路径更顺滑、术语一致）。
3. •越界内容路由：指定章节中若存在不属于该章节边界的内容块：
   • •路由到更合适的目标标题下；
   • •若目标标题下缺少合适容器或需要暂存，则在该目标标题下新增子标题 待整理 并把内容放入其中；
   • •便于用户后续“点名某个待整理模块”继续整理。

依赖

• •$learning-notes-organizer
  • •用于边界判断、归类、学习路径、精修重写、格式保真等规范（本 skill 不重复展开细则）
• •$planning-with-files
  • •用于组织执行流程与交付结构（抽取→规划→映射→交付）

输入

必填：

• •target_file: 目标 Markdown 文件路径
• •focus_sections: 需要重构的章节列表（1~N 个，可变）
  • •支持：标题名（模糊）或标题路径（精确）
  • •示例：
    • •["学习资源与概览", "核心概念与内存背景"]
    • •["核心概念与内存背景/ByteBuf", "Pipeline/Handler"]

可选参数（v2 新增，推荐默认即可）：

读取/抽取

• •heading_level_support: 默认 H1-H6
• •meaning_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) 越界内容路由清单（从指定章节迁出）

D) 新增 待整理 清单

调用模板（推荐）

使用 $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