# Design Note

> 为 MathRepo 中的新笔记设计完整的 Part-Chapter-Section 目录结构。涵盖教材基线分析、职责边界划定、逻辑链路设计、内容丰富度把控、注释蓝图写入和覆盖度验证。适用于从零规划一份新笔记的宏观骨架。

- Skill: `locusyuri/design-note` (Agent Skill)
- Install (CLI): `npx skillmds@latest add locusyuri/design-note`
- Raw SKILL.md: https://api.skillmd.com/api/skills/locusyuri/design-note/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: locusyuri (https://skillmd.com/u/locusyuri)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/locusyuri/design-note

---


# 笔记目录结构设计技能

## 1. 何时使用

当需要为 MathRepo 中**尚未有目录蓝图的新笔记**设计完整的 Part → Chapter → Section 层级结构时激活。本技能在**写作之前**运行，产出一份带设计思路注释的目录蓝图（commented blueprint），供用户确认后写入 `initial.typ`。

### 1.1 与 make-outline 的区别

| 维度 | design-note（本技能） | make-outline |
|------|----------------------|--------------|
| **粒度** | 整本笔记的宏观骨架 | 单章/单节的微观大纲 |
| **产出** | Part-Chapter-Section 层级 + 设计注释 | 知识点表、组件规划、标签系统、图片规划 |
| **关注点** | 主题划分、逻辑链路、职责边界、覆盖度 | 定义/定理/例题的编排、交叉引用、标签命名 |
| **运行时机** | 笔记创建前（从零设计） | 章节写作前（已有骨架，细化内容） |

**协作流程**：先用本技能设计整本笔记的目录蓝图 → 确认后写入 `initial.typ` → 逐章用 `make-outline` 细化 → 逐节写作。

## 2. 设计原则

### 2.1 教材基线原则

> 目录必须完整覆盖用户指定教材的所有知识点。

- 用户指定教材是**知识点基线**，不可遗漏
- 组织顺序可以与教材不同，但知识点集合必须 ⊇ 教材知识点集合
- 在产出中提供**覆盖度映射表**（见 §5.4），逐条标注教材知识点在目录中的对应位置

### 2.2 职责边界原则 (SRP)

> 每本笔记只负责自己领域内的内容，不重复其他笔记已有的定义或理论。

- 设计前必须**扫描仓库中已有的相关笔记**，识别职责重叠区域
- 对每个潜在重叠点，明确裁决：本笔记包含 vs. 交叉引用到 XX 笔记
- 典型边界场景：
  - 集合论基础 → 归属 Théorie des Ensembles，其他笔记仅引用
  - 测度论 → 归属 Analyse Réelle，概率论笔记仅引用结果
  - Lebesgue 积分 → 归属 Analyse Réelle
  - 拓扑空间基础 → 归属 Analyse Fonctionnelle
- 边界裁决应在设计注释中显式说明理由

### 2.3 逻辑链路原则

> Part 和 Chapter 的排列必须体现数学知识的内在依赖关系，而非教材章节的简单复制。

- 每本笔记应有一条**主线叙事**（如"理论 → 方法 → 应用"、"基础 → 进阶 → 专题"）
- Part 级划分应体现主线的大阶段转换，每个 Part 开头写设计注释说明：
  - 本 Part 在主线中的位置
  - 与前后 Part 的逻辑关系
  - 对应教材的哪些章节
- Chapter 级排列应遵循知识依赖：前置概念先于依赖它的概念
- 可接受的非线性安排：将工具性内容（如生成函数）提前，即使教材放在后面，因为后续章节需要它

### 2.4 内容丰富度原则

> 目录不应只是教材目录的翻版，而应根据数学知识的内在联系适当扩展。

- 如果某个在教材中分散出现的话题可以聚合为一个有意义的专题，应独立成章
- 如果某个在教材中一笔带过的话题在本笔记的上下文中需要更完整的处理，应补充
- 典型扩展场景：
  - 数学分析笔记包含曲面论（为曲线/曲面积分提供完整理论工具）
  - 概率论笔记包含生成函数专题（教材分散在各章，但作为工具值得聚合）
- 扩展不能违反职责边界原则（§2.2）

### 2.5 过渡衔接原则

> 笔记之间应有明确的衔接设计，而非孤立的知识点集合。

- 如果本笔记是某个更大知识体系的一部分，应设计**过渡 Part/Chapter**
  - 例如：概率论笔记的 Part V（抽样分布与充分统计量）是从概率论到统计推断的过渡
- 如果本笔记为后续笔记做铺垫，最后的 Part 可以设计为**导论性专题**
  - 例如：概率论笔记的 Part IX（随机过程初步）为 Processus Stochastique 笔记搭桥
- 过渡部分在设计注释中标明"本部分仅作导论，深入理论参见 XX 笔记"

## 3. 设计流程

```
Step 1: 已有笔记扫描
  ↓
Step 2: 教材基线分析（知识点清单）
  ↓
Step 3: 职责边界裁决
  ↓
Step 4: 主线叙事设计 → Part 划分
  ↓
Step 5: Chapter 排列 → Section 细化
  ↓
Step 6: 覆盖度验证（映射表）
  ↓
Step 7: 对关键决策点征求用户意见
  ↓
Step 8: 写入注释蓝图到 initial.typ
```

### 3.1 已有笔记扫描

在动手设计前，先了解仓库的现状：

- **Grep 仓库中所有 `initial.typ`** 的 `#part(` 和 `^= ` 标题行，获取已有笔记的主题覆盖
- **重点阅读**与本笔记主题相关的笔记目录（如设计概率论笔记时，阅读 Analyse Réelle、Théorie des Ensembles 的目录）
- 识别**可交叉引用的标签**（已写笔记中的 `<def:>` `<thm:>` 等）
- 记录**职责边界裁决**：哪些话题属于其他笔记，本笔记只引用不重复

### 3.2 教材基线分析

- 如果用户指定了教材，**逐章逐节提取知识点清单**
- 标注每个知识点的教材位置（章、节、页码范围）
- 如果用户未指定教材，参考 2-3 本主流教材的目录取并集

### 3.3 职责边界裁决

对教材基线中的每个知识点，裁决其归属：

| 知识点 | 归属 | 理由 |
|--------|------|------|
| σ-代数 | Théorie des Ensembles | 集合论已有完整处理 |
| Lebesgue 测度 | Analyse Réelle | 测度论已在实分析中建立 |
| 条件概率 | 本笔记 | 概率论核心概念 |

### 3.4 主线叙事设计

设计一条贯穿全笔记的主线，并据此划分 Part：

- 主线用一句话概括（如"概率论 → 统计推断 → 应用拓展"三段式）
- 每个 Part 对应主线的一个阶段
- Part 数量建议：3-6 个（太少则粒度粗，太多则碎片化）
- 每个 Part 写设计注释，说明：
  - 在主线中的角色
  - 包含的 Chapter 范围
  - 对应教材的哪些章节
  - 设计思路（为什么这样划分）

### 3.5 Chapter 排列与 Section 细化

- Chapter 排列遵循知识依赖顺序
- 每个 Chapter 包含 3-6 个 Section（太少内容单薄，太多应拆分）
- Section 标题使用双语格式：`== Title // 中文翻译`
- 如果需要 Subsection，使用 `=== Subtitle // 中文翻译`

### 3.6 覆盖度验证

产出**教材覆盖度映射表**（详见 §5.4），确保无遗漏。

## 4. 注释蓝图格式

写入 `initial.typ` 的目录蓝图必须遵循以下格式，与仓库中已有笔记（如 Analyse Fonctionnelle）保持一致：

### 4.1 整体结构

```typst
#import "../../TypstTemplate/math-notes.typ": *

#set document(
  title: "NoteTitle",
  author: "Violet",
  date: datetime.today(),
)

#show: apply-style

// --------------------------------------------------------------------------
// Cover + Outline
// --------------------------------------------------------------------------

#make-cover(
  "NoteTitle",
  "Violet",
  subtitle: "...",
  institute: "Notiz Mathematiques",
  date: datetime.today().display(),
  version: "v0.2.0",
  extra-info: "...",
)

#make-outline(depth: 2, title: "Contents")

// ==========================================================================
// 目录蓝图 (Planned Outline)
// ==========================================================================
// [... 注释蓝图内容 ...]

#bibliography("references.bib")

// 目录
```

### 4.2 注释层级

```typst
// ==========================================================================
// Part N — Part Title (中文标题)
// ==========================================================================
// 设计思路：说明本 Part 在主线中的角色、包含内容、对应教材章节。
// 对应教材：第X章–第Y章

// --- Chapter M: Chapter Title (中文标题) ---

//   Section M.1: Section Title (中文标题)
//     - 知识点 1
//     - 知识点 2

//   Section M.2: Section Title (中文标题)
//     - 知识点 1
```

### 4.3 格式要点

- Part 分隔线使用 `// ==========================================================================`（76 个 `=`）
- Chapter 标题使用 `// --- Chapter N: Title ---`
- Section 标题缩进 2 空格：`//   Section N.M: Title`
- 知识点列表缩进 4 空格：`//     - 知识点`
- 所有标题**英文在前，中文注释在后**（与正文的双语标题一致）
- 设计思路注释写在 Part 分隔线之后、Chapter 列表之前

### 4.4 Structure Note

在目录蓝图的末尾（`#bibliography` 之前），写一段 **Structure Note**，总结全笔记的结构设计：

```typst
// ==========================================================================
// 结构说明 (Structure Note)
// ==========================================================================
// 本笔记遵循"阶段A → 阶段B → 阶段C"的三段式主线，共 N Part、M Chapter。
//
// Part I–X（阶段A，Ch 1–K）：...
//
// Part X–Y（阶段B，Ch K+1–L）：...
//
// Part Y–N（阶段C，Ch L+1–M）：...
//
// 教材覆盖：XX教材全部 N 章知识点均已覆盖。
// ==========================================================================
```

## 5. 产出要素

### 5.1 主线叙事

一句话概括 + 段落说明。

### 5.2 Part-Chapter-Section 层级表

完整的目录树，含双语标题。

### 5.3 职责边界表

| 知识点 | 归属 | 处理方式 |
|--------|------|---------|
| XX | 其他笔记 | 交叉引用 `@label` |
| YY | 本笔记 | 包含在 §N.M |

### 5.4 教材覆盖度映射表

逐条列出教材知识点，标注在本笔记中的位置：

| 教材位置 | 知识点 | 本笔记位置 | 备注 |
|---------|--------|-----------|------|
| §1.1 | XX | Ch 1, §1.1 | 直接对应 |
| §3.2 | YY | Ch 5, §5.2 | 重组到更合适的位置 |
| §6.3 | ZZ | Ch 8, §8.1 | 拆分后分散在多处 |

如果某知识点被裁决为属于其他笔记，在"备注"列注明。

### 5.5 设计决策记录

记录关键的设计决策及其理由，例如：
- 为什么把 XX 从教材的第 3 章移到本笔记的第 7 章
- 为什么把 XX 独立成章而不与其他节合并
- 为什么新增教材中没有的 XX 专题

## 6. 交互流程

### 6.1 决策点规则

- 只对**真正影响结构且用户可能有偏好**的决策提问
  - 如"XX 是否独立成章 vs 并入 YY 章"
  - 如"主线采用 A 方案 vs B 方案"
- 每个问题给 2-3 个选项，标注推荐项 `(Recommended)`
- 不超过 5 个问题
- 不对细节（如标题措辞、Section 划分）提问——这些自己决定

### 6.2 确认流程

```
Step 1: 产出目录方案（§5 的所有要素）
  ↓
Step 2: 对关键决策点用 AskUserQuestion 征求用户意见
  ↓
Step 3: 根据反馈调整
  ↓
Step 4: 用户确认后写入 initial.typ 的注释蓝图
```

## 7. 自检清单

设计完成后逐项检查：

- [ ] 教材基线中的所有知识点均已覆盖（映射表无遗漏行）
- [ ] 职责边界已裁决，无与其他笔记重复的内容
- [ ] 主线叙事清晰，Part 划分体现主线阶段
- [ ] 每个 Part 有设计思路注释
- [ ] Chapter 排列符合知识依赖顺序
- [ ] 所有标题双语（英文 + 中文翻译）
- [ ] 注释蓝图格式与仓库已有笔记一致
- [ ] Structure Note 已撰写
- [ ] 关键设计决策有理由说明
- [ ] 过渡/衔接部分已标注（如有）
- [ ] 扩展内容有合理理由（不违反职责边界）

## 8. 常见模式

### 8.1 三段递进模式

适用于内容天然分为"基础 → 核心 → 应用"的学科：

```
Part I:   基础理论（公理、定义、基本性质）
Part II:  核心理论（主要定理、方法、工具）
Part III: 应用与拓展（具体应用、计算技术、跨领域连接）
```

### 8.2 对象递进模式

适用于研究对象的复杂度逐步升级的学科：

```
Part I:   简单对象（一维、有限维、线性）
Part II:  中等对象（多维、无穷维）
Part III: 复杂对象（非线性、随机、奇异）
```

### 8.3 方法论模式

适用于以方法论为主线的学科：

```
Part I:   建模工具（定义、基本模型）
Part II:  分析工具（变换、分解、逼近）
Part III: 求解工具（解析方法、数值方法、近似方法）
```

### 8.4 桥梁模式

适用于需要衔接前后知识的过渡性笔记：

```
Part I:     回顾与深化（前置知识的进阶视角）
Part II:    核心理论（本领域主体内容）
Part III:   导论与展望（为后续笔记铺垫）
```

## 9. 写作阶段衔接

目录蓝图确认后，进入逐章写作阶段时：

1. 按 `make-outline` 技能逐章细化大纲
2. 按 `typst-writing-conventions` 技能执行写入
3. 写作过程中如发现目录需要微调（新增/合并/拆分章节），应在注释蓝图中同步更新，保持蓝图与实际内容一致
4. 每完成一个 Part，编译验证一次（`typst compile "<subject>/initial.typ" "<subject>/initial.pdf" --root .`）