---
title: "笔记库构建与维护说明（handoff）"
tags:
  - 元/维护
  - 英语阅读/索引
date: 2026-10-13
---

# 笔记库构建与维护说明

> [!note] 这份文件是给"下一个维护者"（人或 AI）看的
> 记录这套英文阅读笔记库的结构约定、质量门槛与自动校验方式，方便继续扩充而不破坏一致性。

---

## 一、目录约定

```text
英文论文阅读笔记库/
├── 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、节选与版权声明 | 必须写明"仅供个人学习" |

> [!important] 三条铁律
> 1. **不许编造**：URL、标题、作者、日期、英文正文都必须来自真实可抓取的页面（用 `web_fetch` 确认 HTTP 200）。
> 2. **正文是主体**：生词/长难句/专业词汇只能放在正文**之后**，不得插在正文中间。
> 3. **英文正文逐字照录**：允许删节（标 `[...]`），不允许改写、简化或"仿写"。

---

## 三、自动校验

```powershell
$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` 与实测偏差、双链是否指向真实文件、索引是否死链。

---

## 四、扩充新文章的标准流程

1. 读 `笔记规范.md`，按骨架写；新文件序号接在该主题最后一个序号之后。
2. 来源优先选**可稳定抓全文**的：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）。
3. 抓不到全文（<700 词）就**换来源**，不要用摘要凑正文。
4. 写完运行校验器 + 重建索引；`word_count` 用「`## 一、英文正文` 到 `## 二、` 之间的英文词数」实测值。
5. 修改已有文件时用 `edit` / `write` 工具；**不要用 PowerShell `Get-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-索引]]
- 写作规范：[[笔记规范]]
- 学习方法：[[英语长文阅读方法]]
