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 才新建,并按结构文件路由规则选域/编号(沾边不足时含"新建目录候选"问用户)。深化既有笔记模式不需查重(目标笔记已知)
执行流程
- 读原笔记(若是新主题则跳过):明确它已覆盖什么、缺什么
- 联网研究:官方文档、survey 论文优先,至少交叉核对 3 个来源;时效性论断必须当场验证
- 重写为教材级结构(见下),在原文件上扩写(保留 frontmatter,
状态 改为 教材级,补 更新日期)
- 来源标注:每个关键论断标
[训练集] / [联网:链接] / [知识库:文件]
- 遵循同一工具包内
save-to-kb/references/standards.md 的全部写作与排版规范(术语英文原词(中文)、中英空格、表格优先);知识库根目录 知识库结构.md 声明的写作偏好与之冲突时,以结构文件为准
- 若产生新概念,检查是否需要 [[wikilink]] 到其他笔记;必要时更新 MOC
- 向用户报告:文件路径、扩写前后字数、新增了哪些板块、引用了几个来源
- 维护人类导航层(条件条款):仅当结构文件声明了「人类导航层/人读索引」时执行——深化/新建的笔记按结构文件该节维护对应索引条目(纯指针、不写正文;如 Obsidian 用路径式
[[目录/文件|显示名]] 链接);顺带校验既有条目链接未失效,笔记改名/移动则同步。结构文件未声明此层的知识库跳过本条
- 版本提交:在知识库根目录运行
git add -A && git commit -m "expand-note: <本次深化的文件名>"(扩写是大改动,独立 commit 才能用 git diff 审计、git checkout <commit> -- <文件> 回滚);仓库不存在或提交失败时向用户报告原因,不中断流程
教材级结构(其中"原理系统展开/示例与反例/常见误区与 FAQ/练习与自测"四个板块缺一不可)
# 标题
> 一句话定义
## 摘要 ← 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(原文摘录 + 正/反写对照,动笔前必读;含开源书站链接可深度校准)
1---2name: expand-note3description: 把知识库中一篇既有笔记深化为教材级学习内容(原理系统展开、多示例+反例、常见误区 FAQ、练习自测题),或对一个新主题做深度研究后写成教材级笔记。触发场景:用户说"深化/拓展某篇笔记"、"拓展某主题"、"写成教材/深度笔记/expand note/deepen this note"等。需要联网多来源交叉研究,一次只处理一个主题。4---56# Expand Note(教材级深化)78## Overview910把一篇"概要级"笔记升级为**教材级学习内容**,或对新主题直接产出教材级笔记。与 save-to-kb 的分工:**save 管快速记录(会话策展),本 skill 管深度成文(联网研究)**。一次只深化一篇,可以长,但只讲一个主题。1112## 知识库定位1314- 按 save-to-kb 的通用协议定位:环境变量 `KB_ROOT` → 当前 harness 加载的指令文件(AGENTS.md/CLAUDE.md 等)声明的路径 → 问用户;再读知识库根目录的 `知识库结构.md` 确定笔记所在域与对应 MOC,禁止凭记忆猜结构;结构文件不存在时按 save-to-kb 的冷启动流程处理(询问是否按模板创建),不猜结构15- **新主题写前查重(仅"拓展 <新主题>"模式)**:动笔前运行 `KB_ROOT=<知识库根目录> python3 <本工具包安装目录>/save-to-kb/scripts/find_related.py <关键词...>`——命中既有笔记则改为**深化那篇**(走既有笔记模式),而非新建第二个权威版本;`NO_MATCH` 才新建,并按结构文件路由规则选域/编号(沾边不足时含"新建目录候选"问用户)。深化既有笔记模式不需查重(目标笔记已知)1617## 执行流程18191. **读原笔记**(若是新主题则跳过):明确它已覆盖什么、缺什么202. **联网研究**:官方文档、survey 论文优先,**至少交叉核对 3 个来源**;时效性论断必须当场验证213. **重写为教材级结构**(见下),在原文件上扩写(保留 frontmatter,`状态` 改为 `教材级`,补 `更新日期`)224. **来源标注**:每个关键论断标 `[训练集]` / `[联网:链接]` / `[知识库:文件]`235. 遵循同一工具包内 `save-to-kb/references/standards.md` 的全部写作与排版规范(术语英文原词(中文)、中英空格、表格优先);知识库根目录 `知识库结构.md` 声明的写作偏好与之冲突时,以结构文件为准246. 若产生新概念,检查是否需要 [[wikilink]] 到其他笔记;必要时更新 MOC257. 向用户报告:文件路径、扩写前后字数、新增了哪些板块、引用了几个来源268. **维护人类导航层(条件条款)**:仅当结构文件声明了「人类导航层/人读索引」时执行——深化/新建的笔记按结构文件该节维护对应索引条目(纯指针、不写正文;如 Obsidian 用**路径式** `[[目录/文件|显示名]]` 链接);顺带校验既有条目链接未失效,笔记改名/移动则同步。结构文件未声明此层的知识库跳过本条279. **版本提交**:在知识库根目录运行 `git add -A && git commit -m "expand-note: <本次深化的文件名>"`(扩写是大改动,独立 commit 才能用 `git diff` 审计、`git checkout <commit> -- <文件>` 回滚);仓库不存在或提交失败时向用户报告原因,不中断流程2829## 教材级结构(其中"原理系统展开/示例与反例/常见误区与 FAQ/练习与自测"四个板块缺一不可)3031```markdown32# 标题33> 一句话定义34## 摘要 ← 3~5 条核心结论 bullets,自足可读(等价论文 Abstract;未来向量化时作为 Summary Index(摘要索引) 的检索层)35## 动机(解决什么问题) ← 用类比或真实场景切入,先建立直觉36## 原理系统展开 ← 讲到"能指导动手决策"为止;工程机制可以深,学术评测不进正文37## 示例与反例 ← 每个核心概念 ≥2 个正例 + ≥1 个"什么时候不成立"的反例38## 常见误区与 FAQ ← 新手易错点、易混概念辨析(如 RAG≠向量库)39## 练习与自测 ← 3~5 道检验理解的问题(附简答,用 Obsidian 折叠语法或文末统一给)40## 边界与局限41## 相关笔记42## 名词对照 ← 正文出现的术语应收尽收;常用词嵌入域术语表 ![[<前缀>-00-01-术语表#词]],生僻词本地一行大白话43## 参考来源 ← 本次研究的全部来源,带链接44```4546## 质量红线4748- **难度定标(最重要,详见 standards 第 6 节)**:读者是动手搭系统的工程实践者,不是研究员——风格参照李博杰《深入理解 AI Agent》:类比切入、直觉先行、深在工程机制;**论文实验数据/消融表/数学推导不进正文**(最多一句结论,出处放参考来源);理论侧术语(幂等、append-only 等)用大白话表达49- **禁止不联网就扩写**——教材级的增量知识必须来自研究,不能靠模型脑补;无法验证的写"推断"50- 一次只深化一篇;用户说"批量"时也要逐篇执行、逐篇报告51- 扩写是**增强不是替换**:原笔记的正确结论必须保留,发现原文有错要显式指出并修正52- 篇幅服务于理解,不凑字数;每个板块都要有实质内容5354## Resources5556- 写作规范复用:同一工具包内 `save-to-kb/references/standards.md`(Diátaxis、排版、来源标注)57- 风格样例:同一工具包内 `save-to-kb/references/style-examples.md`(原文摘录 + 正/反写对照,动笔前必读;含开源书站链接可深度校准)
Criss404