# Learning Notes Organizer

> 对 Markdown 学习笔记做结构重构与精修：两阶段 Plan-and-Execute 工作流——先诊断归类（出清单/大纲/映射/scaffold），再精修交付（重写正文、越界路由、资源追踪）。支持全文或指定章节两种 scope；支持只出清单或直接输出整理后正文。

- Skill: `z-soulx/learning-notes-organizer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add z-soulx/learning-notes-organizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/z-soulx/learning-notes-organizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: z-soulx (https://skillmd.com/u/z-soulx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/z-soulx/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：迁移顺序建议

**迁移块模板：**

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

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

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

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

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

（把原文复制到这里）
```

---

## 执行约束

### 必须满足

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

### 不做（非目标）

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

---

## 调用模板

```text
请按 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`](./EVOLUTION.md) 协议执行迭代升级。