笔记整理规范

这份文档是整理学习笔记、出练习题的唯一规范来源。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-）
只有在中间插入笔记时才需要重编号，且必须同步四件事：
1. 后续文件重命名
2. 每篇的 order 字段
3. 站内链接 /posts/编程学习/<课程文件夹小写>/NN-xxx/
4. 对应的 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 的校验规则）：

yaml

---
title: Python3 列表
published: 2026-09-18
updated: 2026-09-18        # 只在追加或修订已有笔记时写
description: 一句话说清这篇讲什么
tags:
  - Python
order: 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、平台首页图
真实报文、报错截图、控制台/运行输出截图	单个图标（路由器、服务器、信封等）
软件界面截图（成品效果、操作入口、配置页面）	重复使用的装饰底图
官方文档截图（含参数表、示例代码）	页面上重复出现的同一张图（只插一次）

数量不设上限：有几张和信息相关就插几张；同一张图在多页重复只插一次。
纯文字、表格、代码类的截图：同时转成文字与代码块并保留原图——文字方便搜索和朗读，原图方便核对。
图片要插在讲对应内容的小节里（不是堆到文末），并配一行斜体图注说明这张图在讲什么。
存放与引用（路径以笔记所在目录为基准）：

markdown

图片放 assets/<笔记名>/ 下，文件名用 <来源标记>-<页码或序号>-<中文描述>
*（原图缺失：'ch10-p003-rag六环节流程.jpg'，待重传图床后补回）*
*图：RAG 的六个环节——数据源、加载、转换、嵌入、存储、检索*

构建时 Astro 会自动压缩并转成 webp（实测 234 张原图会被优化成 avif/webp，页面里引用的是 /_astro/xxx.webp）。

禁止 ![|500](xxx.png) 这种 Obsidian 宽度写法：实测会在图片下方渲染出一行可见的文字 |500。

从 PDF/PPT 提取图片的标准流程（Windows 本机可用）

pdftotext 只能取文字，取图要另走一步（本机没有 pdfimages，用 PyMuPDF）：

bash

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-28 起）。历史上那批"旧格式"题（答案直接写在题目下面、-> list.append(元素) 式的直给提示）已于 2026-09-28 全部改造成本节的标准形态（Python 课程 20 篇、LangChain 课程 25 篇一起统一的），所以"旧题保留原样"那条豁免已经作废——看到不符合本节格式的题，就是"待修"。

10.1 唯一来源：笔记

题目与分级提示只写在笔记末尾的 ## 练习题 区块
参考答案就写在每道题后面，用折叠块包起来（> [!TIP]- 参考答案（做完再点开））——做完再展开对照，不想被剧透就别点开；也可以直接说「看答案 07 第3题」让助手发给你
知识回顾条目直接给出答案、不折叠（它不是题，是速查表，见 10.2）
练习文件（E:\GithubProgect\MyRunProject\Daily-Learning\）由笔记自动生成，里面只有题目要求和写作区，不含答案——做题时在编辑器里看不到答案
生成规则：
- 文件不存在 → 按题目创建（题目注释块 + 写作区）
- 文件已存在 → 只刷新顶部的题目注释块（到第一个 # 在下面写你的代码： 之前），你写的代码原样保留
- 综合题只在首次创建、不自动更新，避免覆盖你的多步代码

10.2 题型与题量：每次 4~6 道

题型	数量	作用	提示
知识回顾	1 组（8~10 个编号条目）	广度：把这篇笔记的关键点整理成可以直接读的速查条目，读一遍即复习	不给（答案就写在条目里）
裸写题	3 道左右	深度：只给需求，自己动手写	三级提示（折叠）
综合题	0~1 道	串联：把多个知识点组合成一个能用的小程序	分步引导

为什么不再用「填空」（2026-09-23 改）：____ 这种空在 Obsidian 里必须先把下划线删掉才能填，很别扭。改成「知识回顾」后：上半部分是读的（速查表，答案直接写出来），动手只留在下面的实践题。

概念型笔记（没有可写代码的知识点，如 AI 概念、网络基础、HTTP 协议）：知识回顾照常出（术语、数字、对应关系都写进去），把「裸写题」换成「概念自测」——用自己的话解释、判断对错、对比区别这类口头能答的题，不出练习文件。

硬性要求：

题目里禁止出现答案级提示（像 -> list.append(元素) 这种）。要提示就放进下面的折叠块。
知识回顾里不留空：不留 ____、不留 （），把答案直接写出来（API 名用行内代码、关键值加粗），让人一遍读过去。
覆盖检查：出完题对照笔记把知识点列成清单逐条打勾，没覆盖的补进知识回顾，或者说明为什么不单独出题（纯概念类的）。
难度递增：知识回顾（读一遍）→ 裸写（写得出）→ 综合（用得上）。

10.3 三级提示（解决"没提示又写不出来"）

卡住时逐级展开——展开本身也是学习信号：

markdown

> [!TIP]- 提示（先自己想，实在想不出再点开）
> **一级 · 思路**：想想列表有哪几种"加元素"的方法
> **二级 · 方法**：`append()` 在末尾加、`insert()` 在指定位置插
> **三级 · 骨架**：`nums.____(4)` / `nums.____(1, 10)`

（折叠 callout 语法 > [!TIP]-，站点原生支持，默认收起。类型名大小写不敏感。）

10.4 批改：结果写回笔记

触发：说 批改 07（编号或笔记名）
必须实际运行你写的代码（本机 Python），不靠肉眼看
批改结论写在笔记里对应题目下面（2026-09-28 统一成"一行式"，跟着题目走）：

markdown

- [x] **2-1 列表添加元素** ❌
  题目要求……

  > **批改（2026-09-28）**：❌ `append` 写成了 `appendd`，运行报 `AttributeError`；正确写法 `nums.append(4)`。

判定用三个符号：✅ 正确 / ⚠️ 部分完成（少做步骤、缺测试点、有调试残留） / ❌ 错误（逻辑或输出不对）
结论里写清：错在哪 + 正确写法；引用用户代码用反引号，别贴大段代码
⚠️ 的题在题目行不加 ❌（❌ 只留给明确错误的题，供"重做错题"扫）
没做过的题（练习文件是空的）不写批改行
做错的题在题目行加 ❌ 标记（如 - [ ] **2-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 格式模板

笔记里：知识回顾（答案直接写出来，读一遍即可；不留 ____）

markdown

### 一、知识回顾（读完直接做下面的实践题）

1. 在列表末尾添加元素用 `append()`；在索引 1 处插入 10 用 `insert(1, 10)`
2. 删除元素：`pop()` 按索引、`remove()` 按值、`del` 按索引

笔记里：裸写题

markdown

- [ ] **2-1 用列表模拟浏览器的前进后退**
  只给需求文字，不给任何 API 提示。

  > [!TIP]- 提示（先自己想，实在想不出再点开）
  > **一级 · 思路**：想想列表里"加"和"删"分别有什么方法
  > **二级 · 方法**：`append()` / `pop()`
  > **三级 · 骨架**：`history.____(url)` / `history.____()`

注意：三级提示里可以用 ____（那是给你动脑的骨架），但知识回顾里一律不留空。

题面里"能写什么"的分寸（2026-09-28 统一口径）：

可以写在题面	要收进折叠提示
运算符与语法关键字：`+`、`in`、`for`、`if`、`while`、`match`、`class`、`def`、`with`、`import`	某个库/模块的方法与参数写法：`list.append(x)`、`str.split(",")`、`df.dropna()`、`re.match(...)`、`ChatDeepSeek(...)`、`st.session_state`
通用内置函数：`print`、`input`、`len`、`type`、`range`、`int`、`str`	`-> 方法()` 这种直接给答案的提示
自定义函数名、文件名、数据文件路径（`data/sales.csv`）	答案要用到的具体调用写法

一句话：运算符和语法是自己就该会的基础，留在题面；库方法名才是要回忆的东西，收进提示。

笔记里：综合题（保留原来的分步引导格式）

markdown

#### 购物车管理系统

**需求**：1. … 2. …

**第一步：定义商品类**
- 步骤说明

**涉及知识点**

| 知识点 | 应用 |
| --- | --- |

练习文件：test_NN_主题.py（没有答案块——答案在笔记里）

python

# ============================================
# 题目2-1：列表添加元素
# ============================================
# 完成以下操作：
# 1. 创建列表 nums = [1, 2, 3]
# 2. 在末尾添加 4
# 3. 在索引 1 处插入 10
# 4. 打印每次操作后的列表
# ============================================

# 在下面写你的代码：

文件模板的硬要求（2026-09-28 统一）：

分隔线固定 44 个 =（顶、题名后、底各一条）；步骤行用 # 1. …，不用 Markdown 的 - 或 **。
题号与笔记一致：裸写题写 # 题目2-1：…，综合题写 # 综合题：…。
题面只写需求（按上面的"分寸"表）；不写提示、不写答案、末尾不留答案注释块——那些都在笔记里。
# 在下面写你的代码： 之后是用户的写作区：刷新题面时只改这一行以上，以下一个字节都不动；多步骤综合题（文件里有多个标记）只刷新第一个标记之前的头部。
用户没做过的文件也要保持这个模板（方便以后刷新）。

生成/刷新时的边界就是 # 在下面写你的代码： 这一行：它以上的内容可以被重写，以下的一律不动。

10.9 触发词

说什么	我做什么
`出题 07`	在笔记末尾写题（知识回顾 + 裸写题 + 三级提示），并生成练习文件
`批改 07`	跑你的代码，结论写回笔记对应题目下，错题打 ❌
`批改 27-33`	批量批改一个范围：逐篇跑代码、逐篇写回结论，最后再给一份汇总（哪几篇错、错在哪一类知识点）
`重做错题 07`	挑出带 ❌ 的题，生成不带提示的重做文件
`看答案 07 第3题`	把参考答案发给你

这份规范的执行入口是 ZCode 技能 .agents/skills/note-organizer/SKILL.md，它只做一件事：每次先来读这篇。使用手册（怎么触发、一次流程长什么样、文件放在哪）见《笔记整理与出题助手使用说明》。

笔记整理规范 ​

一、基本原则 ​

二、放在哪里：文件夹就是分类 ​

三、文件命名与编号 ​

编号维护规则 ​

四、frontmatter 写什么 ​

五、标签（tags） ​

六、图片 ​

从 PDF/PPT 提取图片的标准流程（Windows 本机可用） ​

七、正文结构 ​

八、整理流程 ​

九、已知的坑 ​

十、练习题 ​

10.1 唯一来源：笔记 ​

10.2 题型与题量：每次 4~6 道 ​

10.3 三级提示（解决"没提示又写不出来"） ​

10.4 批改：结果写回笔记 ​

10.5 重做 ​

10.6 出题质量硬要求 ​

10.7 练习库结构 ​

10.8 格式模板 ​

10.9 触发词 ​

笔记整理规范

一、基本原则

二、放在哪里：文件夹就是分类

三、文件命名与编号

编号维护规则

四、frontmatter 写什么

五、标签（tags）

六、图片

从 PDF/PPT 提取图片的标准流程（Windows 本机可用）

七、正文结构

八、整理流程

九、已知的坑

十、练习题

10.1 唯一来源：笔记

10.2 题型与题量：每次 4~6 道

10.3 三级提示（解决"没提示又写不出来"）

10.4 批改：结果写回笔记

10.5 重做

10.6 出题质量硬要求

10.7 练习库结构

10.8 格式模板

10.9 触发词