笔记库构建与维护说明
这份文件是给"下一个维护者"(人或 AI)看的
记录这套英文阅读笔记库的结构约定、质量门槛与自动校验方式,方便继续扩充而不破坏一致性。
一、目录约定
英文论文阅读笔记库/
├── 00-索引.md ← 由脚本生成,不要手改
├── 01-科技与人工智能/ 01-01 … 01-06
├── 02-健康与医学/ 02-01 … 02-06
├── 03-环境与能源/ 03-01 … 03-06
├── 04-社会与人文/ 04-01 … 04-06
├── 05-经济与商业/ 05-01 … 05-06
├── 06-太空与地球科学/ 06-01 … 06-06
├── 07-心理与认知/ 07-01 … 07-06
└── _工具与校验/
├── 笔记规范.md ← 写作规范(新文章必须照它写)
├── 英语长文阅读方法.md ← 给学习者的方法论
├── build-index.py ← 由 frontmatter 生成 00-索引.md
├── verify-english-notes.py← 全库自动校验
└── last-report.json ← 最近一次校验的 JSON 报告
文件名规则:<主题编号>-<两位序号>-<中文短标题>.md
- 主题编号与目录编号一致;
- 序号在主题内从 01 连续编号,不跳号、不重号;
- 中文短标题 ≤20 字,不含
/ \ : * ? " < > |。
二、每篇笔记的结构(固定骨架)
| 区块 | 内容 | 硬性门槛 |
|---|---|---|
| YAML frontmatter | title / title_zh / source / author / date / url / type / level / word_count / tags / reading_time / related | 12 个字段缺一不可;tags 第一项为 英语阅读/<主题> |
## 一、英文正文 | 真实原文的连续摘录(逐字,可删节,删节处 [...]) | ≥700 词;纯英文;无表格、无代码围栏 |
## 二、生词与短语精讲 | 生词表(音标/词性/英文释义/中文释义/文中例句)+ 高频搭配表 | 生词表 ≥18 行 |
## 三、长难句解析 | 3 个 > [!example] 块:原句 / 结构拆解 / 参考翻译 | 恰好 3 句,每句 ≥30 词且逐字取自正文 |
## 四、专业词汇标注 | 专业词汇 / 中文解释 / 所属领域 | ≥6 行 |
## 五、阅读训练建议 | 三遍读法勾选项 + 关联阅读双链 | 双链只指向真实存在的文件 |
## 六、来源与版权说明 | 原题、来源、日期、URL、节选与版权声明 | 必须写明"仅供个人学习" |
三条铁律
1. 不许编造:URL、标题、作者、日期、英文正文都必须来自真实可抓取的页面(用
web_fetch确认 HTTP 200)。2. 正文是主体:生词/长难句/专业词汇只能放在正文之后,不得插在正文中间。
3. 英文正文逐字照录:允许删节(标
[...]),不允许改写、简化或"仿写"。
三、自动校验
$py = "C:\Users\Wuyanlin\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\python\python.exe"
$root = "D:\DSH_Workspace\Prog1\英文论文阅读笔记库"
# 1) 校验全库(退出码 0 = 全部通过)
& $py "$root\_工具与校验\verify-english-notes.py" --json "$root\_工具与校验\last-report.json"
# 2) 重新生成总索引(新增文章后必须跑)
& $py "$root\_工具与校验\build-index.py"
校验器会检查:frontmatter 字段完整性、小节顺序、英文正文词数与中文混入、生词表行数、长难句数量、
专业词汇行数、word_count 与实测偏差、双链是否指向真实文件、索引是否死链。
四、扩充新文章的标准流程
- 读
笔记规范.md,按骨架写;新文件序号接在该主题最后一个序号之后。 - 来源优先选可稳定抓全文的:PMC(
pmc.ncbi.nlm.nih.gov/articles/PMC…)、CDC/WHO/NOAA/NASA/ESA/USGS/NIST/DOE/EPA、
Our World in Data、MIT News、World Bank Blogs、地区联储、Quanta Magazine、PLOS、Smithsonian Magazine。
已知常失败:www.nih.gov、newsinhealth.nih.gov(403)、Pew / Brookings(fetch failed)、OECD / WEF(403)。
- 抓不到全文(<700 词)就换来源,不要用摘要凑正文。
- 写完运行校验器 + 重建索引;
word_count用「## 一、英文正文到## 二、之间的英文词数」实测值。 - 修改已有文件时用
edit/write工具;不要用 PowerShellGet-Content -Raw+Set-Content批量替换,
会引入 UTF-8 BOM(导致 frontmatter 解析失败)和全角字符损坏。
五、已知的坑(都踩过一遍)
| 坑 | 现象 | 处置 | |
|---|---|---|---|
| UTF-8 BOM | Set-Content -Encoding UTF8 写出 BOM,校验器报"缺少 YAML frontmatter" | 用 Python 去掉文件头 EF BB BF 三字节 | |
| 全角括号变数字 | PowerShell 往返写文件后 ( 变成 4 | 用 edit 定点修复,避免 PowerShell 字符串往返 | |
| 双链指向不存在文件 | 写笔记时凭记忆编文件名 | 先定文件名再写链接;用校验器的双链检查兜底 | |
| 并行 agent 序号撞车 | 两个 agent 写同一个 07-05-… | 启动前按序号区间分工,禁止重叠 | |
| 索引表格死链 | 表格里写 `[[文件名\ | 显示名]],解析器把 \` 当成文件名一部分 | 解析时先剥掉尾部反斜杠(校验器已处理) |
六、相关
- 总导航:00-索引
- 写作规范:笔记规范
- 学习方法:英语长文阅读方法