w wyl123ly 的博客
MD

笔记库构建与维护说明

6 KB 2026.10.13 原文件

笔记库构建与维护说明

这份文件是给"下一个维护者"(人或 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 frontmattertitle / title_zh / source / author / date / url / type / level / word_count / tags / reading_time / related12 个字段缺一不可;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 与实测偏差、双链是否指向真实文件、索引是否死链。


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

  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)。

  1. 抓不到全文(<700 词)就换来源,不要用摘要凑正文。
  2. 写完运行校验器 + 重建索引;word_count 用「## 一、英文正文 到 ## 二、 之间的英文词数」实测值。
  3. 修改已有文件时用 edit / write 工具;不要用 PowerShell Get-Content -Raw + Set-Content 批量替换,

会引入 UTF-8 BOM(导致 frontmatter 解析失败)和全角字符损坏。


五、已知的坑(都踩过一遍)

坑现象处置
UTF-8 BOMSet-Content -Encoding UTF8 写出 BOM,校验器报"缺少 YAML frontmatter"用 Python 去掉文件头 EF BB BF 三字节
全角括号变数字PowerShell 往返写文件后 ( 变成 4用 edit 定点修复,避免 PowerShell 字符串往返
双链指向不存在文件写笔记时凭记忆编文件名先定文件名再写链接;用校验器的双链检查兜底
并行 agent 序号撞车两个 agent 写同一个 07-05-…启动前按序号区间分工,禁止重叠
索引表格死链表格里写 `[[文件名\显示名]],解析器把 \` 当成文件名一部分解析时先剥掉尾部反斜杠(校验器已处理)

六、相关

  • 总导航:00-索引
  • 写作规范:笔记规范
  • 学习方法:英语长文阅读方法