# Expand Note

> 把知识库中一篇既有笔记深化为教材级学习内容(原理系统展开、多示例+反例、常见误区 FAQ、练习自测题),或对一个新主题做深度研究后写成教材级笔记。触发场景:用户说"深化/拓展某篇笔记"、"拓展某主题"、"写成教材/深度笔记/expand note/deepen this note"等。需要联网多来源交叉研究,一次只处理一个主题。

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

---


# Expand Note(教材级深化)

## Overview

把一篇"概要级"笔记升级为**教材级学习内容**,或对新主题直接产出教材级笔记。与 save-to-kb 的分工:**save 管快速记录(会话策展),本 skill 管深度成文(联网研究)**。一次只深化一篇,可以长,但只讲一个主题。

## 知识库定位

- 按 save-to-kb 的通用协议定位:环境变量 `KB_ROOT` → 当前 harness 加载的指令文件(AGENTS.md/CLAUDE.md 等)声明的路径 → 问用户;再读知识库根目录的 `知识库结构.md` 确定笔记所在域与对应 MOC,禁止凭记忆猜结构;结构文件不存在时按 save-to-kb 的冷启动流程处理(询问是否按模板创建),不猜结构
- **新主题写前查重(仅"拓展 <新主题>"模式)**:动笔前运行 `KB_ROOT=<知识库根目录> python3 <本工具包安装目录>/save-to-kb/scripts/find_related.py <关键词...>`——命中既有笔记则改为**深化那篇**(走既有笔记模式),而非新建第二个权威版本;`NO_MATCH` 才新建,并按结构文件路由规则选域/编号(沾边不足时含"新建目录候选"问用户)。深化既有笔记模式不需查重(目标笔记已知)

## 执行流程

1. **读原笔记**(若是新主题则跳过):明确它已覆盖什么、缺什么
2. **联网研究**:官方文档、survey 论文优先,**至少交叉核对 3 个来源**;时效性论断必须当场验证
3. **重写为教材级结构**(见下),在原文件上扩写(保留 frontmatter,`状态` 改为 `教材级`,补 `更新日期`)
4. **来源标注**:每个关键论断标 `[训练集]` / `[联网:链接]` / `[知识库:文件]`
5. 遵循同一工具包内 `save-to-kb/references/standards.md` 的全部写作与排版规范(术语英文原词(中文)、中英空格、表格优先);知识库根目录 `知识库结构.md` 声明的写作偏好与之冲突时,以结构文件为准
6. 若产生新概念,检查是否需要 [[wikilink]] 到其他笔记;必要时更新 MOC
7. 向用户报告:文件路径、扩写前后字数、新增了哪些板块、引用了几个来源
8. **维护人类导航层(条件条款)**:仅当结构文件声明了「人类导航层/人读索引」时执行——深化/新建的笔记按结构文件该节维护对应索引条目(纯指针、不写正文;如 Obsidian 用**路径式** `[[目录/文件|显示名]]` 链接);顺带校验既有条目链接未失效,笔记改名/移动则同步。结构文件未声明此层的知识库跳过本条
9. **版本提交**:在知识库根目录运行 `git add -A && git commit -m "expand-note: <本次深化的文件名>"`(扩写是大改动,独立 commit 才能用 `git diff` 审计、`git checkout <commit> -- <文件>` 回滚);仓库不存在或提交失败时向用户报告原因,不中断流程

## 教材级结构(其中"原理系统展开/示例与反例/常见误区与 FAQ/练习与自测"四个板块缺一不可)

```markdown
# 标题
> 一句话定义
## 摘要                ← 3~5 条核心结论 bullets,自足可读(等价论文 Abstract;未来向量化时作为 Summary Index(摘要索引) 的检索层)
## 动机(解决什么问题)  ← 用类比或真实场景切入,先建立直觉
## 原理系统展开        ← 讲到"能指导动手决策"为止;工程机制可以深,学术评测不进正文
## 示例与反例          ← 每个核心概念 ≥2 个正例 + ≥1 个"什么时候不成立"的反例
## 常见误区与 FAQ      ← 新手易错点、易混概念辨析(如 RAG≠向量库)
## 练习与自测          ← 3~5 道检验理解的问题(附简答,用 Obsidian 折叠语法或文末统一给)
## 边界与局限
## 相关笔记
## 名词对照          ← 正文出现的术语应收尽收;常用词嵌入域术语表 ![[<前缀>-00-01-术语表#词]],生僻词本地一行大白话
## 参考来源            ← 本次研究的全部来源,带链接
```

## 质量红线

- **难度定标(最重要,详见 standards 第 6 节)**:读者是动手搭系统的工程实践者,不是研究员——风格参照李博杰《深入理解 AI Agent》:类比切入、直觉先行、深在工程机制;**论文实验数据/消融表/数学推导不进正文**(最多一句结论,出处放参考来源);理论侧术语(幂等、append-only 等)用大白话表达
- **禁止不联网就扩写**——教材级的增量知识必须来自研究,不能靠模型脑补;无法验证的写"推断"
- 一次只深化一篇;用户说"批量"时也要逐篇执行、逐篇报告
- 扩写是**增强不是替换**:原笔记的正确结论必须保留,发现原文有错要显式指出并修正
- 篇幅服务于理解,不凑字数;每个板块都要有实质内容

## Resources

- 写作规范复用:同一工具包内 `save-to-kb/references/standards.md`(Diátaxis、排版、来源标注)
- 风格样例:同一工具包内 `save-to-kb/references/style-examples.md`(原文摘录 + 正/反写对照,动笔前必读;含开源书站链接可深度校准)