国庆节10月1日
--
笔记整理规范
笔记整理规范
AI 摘要- DeepSeek
我整理学习笔记时遵守的规范：命名编号、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-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 三级提示（解决”没提示又写不出来”）
卡住时逐级展开——展开本身也是学习信号：
> [!TIP]- 提示（先自己想，实在想不出再点开）> **一级 · 思路**：想想列表有哪几种"加元素"的方法> **二级 · 方法**：`append()` 在末尾加、`insert()` 在指定位置插> **三级 · 骨架**：`nums.____(4)` / `nums.____(1, 10)`（折叠 callout 语法 > [!TIP]-，站点原生支持，默认收起。类型名大小写不敏感。）
10.4 批改：结果写回笔记
- 触发：说
批改 07（编号或笔记名） - 必须实际运行你写的代码（本机 Python），不靠肉眼看
- 批改结论写在笔记里对应题目下面（2026-09-28 统一成”一行式”，跟着题目走）：
- [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 格式模板
笔记里：知识回顾（答案直接写出来，读一遍即可；不留 ____）
### 一、知识回顾（读完直接做下面的实践题）
1. 在列表末尾添加元素用 `append()`；在索引 1 处插入 10 用 `insert(1, 10)`2. 删除元素：`pop()` 按索引、`remove()` 按值、`del` 按索引笔记里：裸写题
- [ ] **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） | 答案要用到的具体调用写法 |
一句话：运算符和语法是自己就该会的基础，留在题面；库方法名才是要回忆的东西，收进提示。
笔记里：综合题（保留原来的分步引导格式）
#### 购物车管理系统
**需求**：1. … 2. …
**第一步：定义商品类**- 步骤说明
**涉及知识点**
| 知识点 | 应用 || --- | --- |练习文件：test_NN_主题.py（没有答案块——答案在笔记里）
# ============================================# 题目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，它只做一件事：每次先来读这篇。 使用手册（怎么触发、一次流程长什么样、文件放在哪）见《笔记整理与出题助手使用说明》。
评论区
[ 标签 ]
[ 分类 ]
[ 公告 ]
如果你喜欢，那么欢迎来到我的世界！
了解更多[ 音乐 ]
音乐
暂未播放
0:000:00
找不到相关结果。
[ contents ]
[ 全部文章 ]
