笔记整理规范
笔记整理规范
我整理学习笔记时遵守的规范：命名编号、frontmatter 字段、标签、图片、正文结构，以及练习题的出题、批改与重做
笔记整理规范
这份文档是整理学习笔记、出练习题的唯一规范来源。AI 助手（ZCode 里的
note-organizer技能）每次整理笔记或出题前都会先读这篇并严格执行；规则要改时只改这一篇，技能的指针不用动。
一、基本原则
- 内容准确性第一：整理资料（图片、PPT、PDF）时不能直接照搬，先确认知识点本身是对的；有疑问先查证再写。
- 补全核心内容：资料里没讲但属于核心前置的知识点要补上，保证笔记能独立看懂。
- 不允许遗忘：资料里出现的知识点都要覆盖，包括没有文字、只有截图的页面。
- 不允许擅自删减（2026-09-21 补充）：资料里讲到的知识点、案例、参数表、返回字段、报错与输出示例、注意事项、“了解”级别的旁支内容，都要写进笔记；只有纯排版性内容（页眉页脚、页码、目录页）可以省略。整理完后要逐节对照原资料自查一遍：原资料的每一小节在笔记里能不能找到对应内容？找不到的必须补上（这一条是站长明确要求后加的，之前几章因为”压缩成一句话”被指出漏了整节内容）。
- 看不清就说：图片模糊、内容有歧义、原资料可能有错的地方，必须单独列出来告诉我，不许猜。
- 练习题不掺进正文：练习题只放在笔记末尾独立的
## 练习题区块（见第十节），不混进知识点讲解里。
二、放在哪里：文件夹就是分类
- 笔记文件放在
src/content/posts/<分类文件夹>/下，放哪个文件夹就是哪个分类。 - 禁止写
category字段：这个字段已经废弃，写了会被忽略，用后台（PagesCMS）编辑时还会被直接丢弃。 - 要新建分类就新建文件夹，但先问过我。
三、文件命名与编号
格式：NN-知识点名称.md
- 两位数字前缀，补零到两位（
01-、09-、10-），保证按文件名排序时10-在09-之后。 - 编号 = 学习顺序（按教材章节、知识脉络排），不是按录入时间。
- 名称用中文知识点名，不要用括号、顿号、冒号、空格等标点：URL 规则会把标点吞掉（
面向对象（高级）.md的网址会变成面向对象高级），文件名和网址对不上，站内链接容易写错。 - 一个知识点一个文件，宁短勿堆。
编号维护规则
- 一个新课程 = 一个新的笔记文件夹，编号从
01重新开始（如MySQL学习笔记/01-17、LangChain学习笔记/01-…）；同一个课程内才连续编号 - 新增笔记 = 当前文件夹最大编号 + 1，一律加在末尾（如
Python学习笔记现在到68-，新笔记就是69-） - 只有在中间插入笔记时才需要重编号，且必须同步四件事：
- 后续文件重命名
- 每篇的
order字段 - 站内链接
/posts/编程学习/<课程文件夹小写>/NN-xxx/ - 对应的
assets/<NN-笔记名>/目录名，以及正文里的图片相对路径
- 现在的编号分配：
Python学习笔记里01-26= Python3 教程系列、27-41= AI 应用系列、42-50= 爬虫、51-59= 数据分析、60-68= Web 开发；LangChain学习笔记（独立课程、独立编号）里01-03= 第1章 概述与开发环境、04-05= 第2章 模型的创建与调用、06= 第3章 LangSmith、07-08= 第4章 Message 与提示词模板、09-10= 第5章 Tools、11-12= 第6章 结构化输出、13-18= 第7章 智能体、19-21= 第8章 中间件、22-23= 第9章 上下文与记忆、24-25= 第10章 RAG。方法类与规范类文档不带编号，统一放在编程学习/学习方法/
四、frontmatter 写什么
只写有用的字段（对齐 src/content.config.ts 的校验规则）：
---title: Python3 列表published: 2026-09-18updated: 2026-09-18 # 只在追加或修订已有笔记时写description: 一句话说清这篇讲什么tags: - Pythonorder: 10 # 与文件名序号一致，必写---published写YYYY-MM-DD，不加引号。order必写，且等于文件名里的序号。站点排序规则是”置顶 →published倒序 → 同一天按order升序”，只改文件名不写order，博客上的顺序不会变——文件名只管文件管理器和网址。同一天发布的多篇笔记不写order，在归档页和分类页就是乱序。- 封面
image不用写，站点有随机封面池兜底。
五、标签（tags）
- 只能从已有标签里挑，写之前先查一遍现有的标签，大小写严格一致（
Python就写Python，不要写py或python）。 - 确实没有的标签才新增，一篇 2~4 个。
- 标签写法不统一会让标签页和标签图谱把同一个主题拆成好几块。
六、图片
资料里的插图默认全部提取、插入笔记（2026-09-21 修正：以前写成”每篇 0~3 张、别全搬”，结果 PDF 讲义里的架构图/流程图/输出截图全被丢掉，被站长指出”图片怎么没保留”。图片是学习资料的一部分，不许因为”省事”或”控制数量”而丢）：
| 保留（全部要） | 跳过（纯装饰） |
|---|---|
| 结构图、流程图、架构图、示意图、公式 | 品牌 logo、平台首页图 |
| 真实报文、报错截图、控制台/运行输出截图 | 单个图标（路由器、服务器、信封等） |
| 软件界面截图（成品效果、操作入口、配置页面） | 重复使用的装饰底图 |
| 官方文档截图（含参数表、示例代码） | 页面上重复出现的同一张图（只插一次） |
- 数量不设上限：有几张和信息相关就插几张；同一张图在多页重复只插一次。
- 纯文字、表格、代码类的截图：同时转成文字与代码块并保留原图——文字方便搜索和朗读，原图方便核对。
- 图片要插在讲对应内容的小节里（不是堆到文末），并配一行斜体图注说明这张图在讲什么。
- 存放与引用（路径以笔记所在目录为基准）：
图片放 assets/<笔记名>/ 下，文件名用 <来源标记>-<页码或序号>-<中文描述>*图：RAG 的六个环节——数据源、加载、转换、嵌入、存储、检索*构建时 Astro 会自动压缩并转成 webp（实测 234 张原图会被优化成 avif/webp，页面里引用的是 /_astro/xxx.webp）。
- 禁止
这种 Obsidian 宽度写法：实测会在图片下方渲染出一行可见的文字|500。
从 PDF/PPT 提取图片的标准流程（Windows 本机可用）
pdftotext 只能取文字，取图要另走一步（本机没有 pdfimages，用 PyMuPDF）：
pip install pymupdf # 本机已装# ① 逐页取图并按「章-页-尺寸」命名（过滤 logo/图标：宽<80 或高<40 或 <8KB 的不要）python -c "import pymupdf, os; ..." # 见 scripts 里的临时脚本写法# ② 压缩：Pixmap 缩放（最大宽 1400）+ 存 jpg 质量 82，10 章原图 130+ 张约 9MB# ③ 复制进 src/content/posts/编程学习/<课程>/assets/<NN-笔记名>/，在笔记里插入引用- 提取时同时导出「页码 → 该页文字 → 该页图片文件名」对照表，才能判断每张图该插到哪篇笔记的哪一节。
- 页面上重复出现的同一张图（同一 md5）只保留一份。
七、正文结构
按内容取舍，不硬凑：
- 概念：先用大白话讲清”它解决什么问题”，再给定义。
- 代码：最小可运行示例，标清语言（
python /bash / ```json）；资料里被截断的 import、上下文要补齐。 - 表格：只用于对比类知识（如三种部署方式的优缺点）。
- 提醒框：站点支持 callout，写
> [!TIP]、> [!WARNING]、> [!NOTE]等，用来标易错点与坑。 - 相关链接：可以在结尾用站内链接指向同目录其它笔记；链接格式是
/posts/编程学习/python学习笔记/NN-xxx/（英文会自动小写，中文保留）。 - 练习题只放在末尾的
## 练习题区块里（见第十节），不掺进知识点正文。
八、整理流程
- 读规范（本篇）→ 读资料：多张图一张不落，PPT/PDF 里没有文字的纯图页也要逐张看图，顺手记下”看不清/有疑问”的清单。
- 索引现状：目标目录编号到几号了、现有标签有哪些、同主题是不是已经有笔记。
- 判断新建还是追加：同主题已有笔记就追加到那篇并加
updated；不同主题才新建，编号接末尾。 - 写：按上面第三到第七节。
- 验证：跑
pnpm build（会校验 frontmatter 字段和图片路径，字段写错会直接报错）。 - 回报：改动的文件清单、补全了哪些内容、存疑清单、构建结果。
九、已知的坑
| 坑 | 后果 |
|---|---|
| 改文件名会改网址 | URL 由文件名决定（小写化、去标点）。改名后站内链接必须同步，否则静默 404（构建不报错）；评论区的浏览量计数也会重置 |
只改文件名不写 order | 博客上的顺序完全不变 |
| 标签大小写/中英混用 | 标签页和标签图谱被拆成多个标签 |
| 图片目录名和笔记名不同步 | 改名后图片找不到（构建时报错） |
用 category 字段 | 被忽略；后台保存时被丢弃 |
十、练习题
适用范围：本节只约束新出的题。2026-09-18 之前的旧题（24 篇笔记里的 124 道，以及练习库里那批旧格式文件）保留原样、不改造——它们把答案写在练习文件里、提示也直接，与新规范不同，看到时不用惊讶。
10.1 唯一来源：笔记
- 题目与分级提示只写在笔记末尾的
## 练习题区块 - 参考答案就写在每道题后面，用折叠块包起来（
> [!TIP]- 参考答案（做完再点开））——做完再展开对照，不想被剧透就别点开；也可以直接说「看答案 07 第3题」让助手发给你 - 填空组的答案同样折叠在填空组末尾（
> [!TIP]- 填空答案） - 练习文件（
E:\GithubProgect\MyRunProject\Daily-Learning\python\）由笔记自动生成，里面只有题目要求和写作区，不含答案——做题时在编辑器里看不到答案 - 生成规则：
- 文件不存在 → 按题目创建（题目注释块 + 写作区）
- 文件已存在 → 只刷新顶部的题目注释块（到第一个
# 在下面写你的代码：之前），你写的代码原样保留 - 综合题只在首次创建、不自动更新，避免覆盖你的多步代码
10.2 题型与题量：每次 4~6 道
| 题型 | 数量 | 作用 | 提示 |
|---|---|---|---|
| 回忆填空题组 | 1 道（内含 8~10 个空） | 广度：把这篇笔记的 API/方法串成一张速查表，一题覆盖全部知识点 | 不给 |
| 裸写题 | 3 道左右 | 深度：只给需求，自己回忆该用什么 | 三级提示（折叠） |
| 综合题 | 0~1 道 | 串联：把多个知识点组合成一个能用的小程序 | 分步引导 |
概念型笔记（没有可写代码的知识点，如 AI 概念、网络基础、HTTP 协议）：填空组照常出（把术语、数字、对应关系都塞进去），把「裸写题」换成「概念自测」——用自己的话解释、判断对错、对比区别这类口头能答的题，不出练习文件。
硬性要求：
- 题目里禁止出现答案级提示（像
-> list.append(元素)这种）。要提示就放进下面的折叠块。 - 覆盖检查：出完题对照笔记把知识点列成清单逐条打勾，没覆盖的补进填空题组，或者说明为什么不单独出题（纯概念类的）。
- 难度递增：填空（认得出）→ 裸写（写得出）→ 综合（用得上）。
10.3 三级提示（解决”没提示又写不出来”）
卡住时逐级展开——展开本身也是学习信号：
> [!TIP]- 提示（先自己想，实在想不出再点开）> **一级 · 思路**：想想列表有哪几种"加元素"的方法> **二级 · 方法**：`append()` 在末尾加、`insert()` 在指定位置插> **三级 · 骨架**：`nums.____(4)` / `nums.____(1, 10)`（折叠 callout 语法 > [!TIP]-，站点原生支持，默认收起。类型名大小写不敏感。）
10.4 批改：结果写回笔记
- 触发：说
批改 07（编号或笔记名） - 必须实际运行你写的代码（本机 Python），不靠肉眼看
- 批改结论写在笔记里对应题目下面：
- [x] **2. 列表添加元素** 题目要求……
> [!NOTE]- 批改记录（2026-09-19） > ✅ 通过：`append` / `insert` 用法正确。 > ⚠️ 风格：`if price != None` 建议写成 `if price is not None`——`!=` 比的是值，`is not` 比的是身份。- 做错的题在题目行加
❌标记（如- [ ] **3. 删除元素** ❌），表示待重做 - 不建单独的错题本，错题台账就是笔记本身
10.5 重做
- 说
重做错题 07→ 从笔记里挑出带❌的题 → 在练习库生成不带提示、不带答案的重做文件（retry_NN_主题.py） - 重做通过后，把笔记里的
❌去掉
10.6 出题质量硬要求
- 参考答案和题目骨架必须验证后才交付：能在本机跑的（文件操作、json、os、纯逻辑）必须实跑一遍；需要 API Key 或 Streamlit 运行时的，至少通过语法编译检查，并对照笔记里已验证可用的完整代码核对。交付时要说清哪些实跑了、哪些只做了语法检查。
- 只考这篇笔记讲过的知识点；用到没讲过的（如
class）要么补一句说明，要么降级成提示 - 答案允许多种写法：批改看行为对不对，不要求跟参考答案一字不差
10.7 练习库结构
```text Daily-Learning/ ├─ python/ ← Python 课程（第 1-6 章） │ ├─ 26-Python-with关键字/ ← 目录名 = 笔记的 NN-笔记名 │ │ ├─ test_01_with.py │ │ └─ test_02_multi.py │ └─ … └─ langchain1.2_tutorial/ ← LangChain 课程（课程代码工程也在这里） └─ 03-开发环境搭建-conda/ └─ test_01_env_check.py ```
- 每个课程一个根目录（
python/、langchain1.2_tutorial/…），课程内再按NN-笔记名/分子目录 - 目录名 = 对应的笔记名（含编号），与同一课程文件夹里的笔记一一对应
- 文件名
test_NN_主题.py，重做文件retry_NN_主题.py - 旧目录（按笔记标题命名的那批）渐进迁移：下次给哪篇笔记出题，顺手把那篇的目录改成新命名
10.8 格式模板
笔记里：回忆填空题组
### 一、回忆填空（写完再展开对答案）
1. `nums.____(4)` —— 在列表末尾添加元素2. `nums.____(1, 10)` —— 在索引 1 处插入 10
> [!TIP]- 填空答案（做完再点开）> 1. `append` 2. `insert`笔记里：裸写题
- [ ] **2-1 用列表模拟浏览器的前进后退** 只给需求文字，不给任何 API 提示。
> [!TIP]- 提示（先自己想，实在想不出再点开） > **一级 · 思路**：想想列表里"加"和"删"分别有什么方法 > **二级 · 方法**：`append()` / `pop()` > **三级 · 骨架**：`history.____(url)` / `history.____()`笔记里：综合题（保留原来的分步引导格式）
#### 购物车管理系统
**需求**：1. … 2. …
**第一步：定义商品类**- 步骤说明
**涉及知识点**
| 知识点 | 应用 || --- | --- |练习文件：test_NN_主题.py（没有答案块——答案在笔记里）
# ============================================# 题目1：列表添加元素# ============================================# 完成以下操作：# 1. 创建列表 nums = [1, 2, 3]# 2. 在末尾添加 4# 3. 在索引 1 处插入 10# 4. 打印每次操作后的列表# ============================================
# 在下面写你的代码：生成/刷新时的边界就是 # 在下面写你的代码： 这一行：它以上的内容可以被重写，以下的一律不动。
10.9 触发词
| 说什么 | 我做什么 |
|---|---|
出题 07 | 在笔记末尾写题（填空组 + 裸写题 + 三级提示），并生成练习文件 |
批改 07 | 跑你的代码，结论写回笔记对应题目下，错题打 ❌ |
批改 27-33 | 批量批改一个范围：逐篇跑代码、逐篇写回结论，最后再给一份汇总（哪几篇错、错在哪一类知识点） |
重做错题 07 | 挑出带 ❌ 的题，生成不带提示的重做文件 |
看答案 07 第3题 | 把参考答案发给你 |
这份规范的执行入口是 ZCode 技能
.agents/skills/note-organizer/SKILL.md，它只做一件事：每次先来读这篇。 使用手册（怎么触发、一次流程长什么样、文件放在哪）见《笔记整理与出题助手使用说明》。
评论区
[ 标签 ]
[ 分类 ]
[ 公告 ]
如果你喜欢，那么欢迎来到我的世界！
了解更多[ 音乐 ]
音乐
暂未播放
0:000:00
找不到相关结果。
[ contents ]
[ 全部文章 ]
