paper-map：用字段契约和自动校验管理论文笔记

半年前我想找回一篇读过的论文，只记得它讲的是"用某种约束让生成结果更稳定"，具体标题、作者、发表年份全忘了。我在三个不同的笔记文件里翻了四十分钟，最后在一份命名为"临时-2.md"的文件第 137 行找到了它，正文只有一句话：这篇思路不错。那一刻我意识到，问题不在我记性差，而在于我把论文研究记录当成了日记来写。

后来我把整套流程重做成了一套叫ljg-paper的记录体系，其中的核心是paper-map——一份定义"每条论文记录必须长什么样"的字段映射表，外加一套能自动跑起来的校验脚本。这篇就聊这套东西：字段为什么这么切、每个字段到底该填什么、怎么用脚本把"靠自觉"变成"跑一遍就知道有没有错"。适合正在做文献综述、需要长期维护阅读笔记、或者带人做课题的朋友参考，不需要什么前置基础，能看懂 YAML 和命令行就行。

1. 论文笔记从自由发挥改成填表，到底解决了什么

1.1 自由格式笔记的三个失效现场

我先复盘一下自己原先的写法，估计很多人跟我一样。第一种失效是检索失效：笔记是散文，想找"哪几篇讨论过采样偏差"只能靠全文搜索，而我当时用的词是"分布不均"，搜"采样偏差"是搜不到的。第二种是对比失效：想横向比较三篇论文的方法差异，得把三个文件并排打开，人眼对齐，五分钟能完成的事拖成半小时。第三种最隐蔽，叫遗忘失效：一条记录写着"读完，方法有意思"，三个月后我完全不记得"有意思"指的是哪一点，这条记录等于作废。

这三种失效的根源是同一个：自由文本把"结构"交给了写作者的临场状态。心情好的时候记得详细，赶时间的时候一句话打发，最后整个笔记库的质量方差极大，你没法对一堆方差极大的数据做任何批量操作。

1.2 paper-map 的定位：它不是目录，是索引契约

我最初也试过加模板，就是那种"标题 / 作者 / 摘要 / 感想"四段式。用了两周就废了，因为它只是个空壳，填不填、填多少全靠自觉。paper-map 的区别在于它带约束：每个字段有类型、有取值范围、有必填与否，而且这套约束能被机器读取并检查。

说白一点，paper-map 是一份契约——你承诺每条记录都包含这十几个字段，工具承诺只要字段齐全，就能按任意维度筛选、聚合、对比。契约的价值不在于写得漂亮，而在于违约会被立刻发现。这也是为什么字段体系和自动化验证必须一起做，只做前者等于立了个没人执行的规矩。

1.3 每加一个字段，都是一笔长期负债

这里必须泼一盆冷水。字段不是越多越好，每加一个字段，你未来每写一条记录就多一次决策成本，而且这个成本是线性叠加的。我第一版设计了 28 个字段，包括"实验环境""数据集规模""代码是否开源""复现难度"等等，结果写了十几条之后开始逃避，最后整件事停摆。

第二版砍到 15 个，核心原则是：只保留会被查询的字段。判断方法很粗暴——问自己"我会不会按这个字段筛选或排序"。会，就留；只是"填了显得完整"，一律砍掉。像"复现难度"这种我从来没真正排序过的字段，全部删掉，需要的时候写在自由备注里。

2. paper-map 的四层字段结构与取舍逻辑

整套字段我按职责分成四层：标识层、内容层、关系层、状态层。分层不是为了好看，是因为这四层的变更频率完全不同——标识层几乎不动，内容层写完就冻结，关系层会随着阅读量增长不断追加，状态层则天天在变。变更频率不同的东西混在一起，改起来会互相牵连。

2.1 标识层：让每条记录有唯一可寻址的名字

标识层解决的是"引用"问题。字段包括id、title、authors、year、venue、link。

id我用固定格式p{年份}-{三位序号}，比如p2024-031。为什么不用标题做 ID？因为标题会重名、会有特殊字符、会因为翻译而变。为什么不用随机 UUID？因为人脑记不住，写交叉引用的时候要复制粘贴，很烦。短序号是唯一一个"机器唯一 + 人眼可读 + 手打不累"的方案。

序号只在当年递增，跨年重新从 001 开始。这个细节很重要：如果用全局递增，一年后序号会变成四位数，手打成本上去了；如果完全不编号靠时间戳，人眼排序时又要在脑子里做一次字符串比较。

authors我存成数组而不是字符串，就是为了后面能按作者聚合。link我要求必须是可访问的稳定地址，优先用 DOI 形式的永久链接，而不是搜索引擎结果页——后者半年后大概率失效。

2.2 内容层：问题、方法、结论的三段式

内容层是这套体系的重心，只有五个字段：problem、method、result、limitation、takeaway。

这个切法借鉴了技术写作里的"问题—方案—证据"结构，但做了两处调整。第一处是把limitation单独拎出来，因为我在做综述时最需要的信息恰恰是"这篇没解决什么"，而这部分内容在原文里通常是作者轻描淡写带过的，不单独设字段就一定会漏。第二处是加了takeaway，强制回答"这篇对我当前的工作有什么用"，这一条是防止"读完就忘"的关键闸门——写不出 takeaway，说明这次阅读没有产出，不如不记。

字段的具体定义如下表：

注意result的约束里写了"含至少一个可量化信息或明确结论"。这不是形式主义，是因为我发现自己的历史笔记里大量出现"效果不错""提升明显"这种无法验证的表述，而真正有价值的是"在某某设定下比基线高了 X 个点"或者"在样本量小时反而不如基线"。前者可以引用，后者可以成为你的研究切入点。

2.3 关系层：论文不是孤岛

关系层是我认为最容易被忽略、但收益最高的一层。字段有三个：builds_on、contradicts、same_thread，值都是id数组。

builds_on记录"这篇建立在哪篇之上"，contradicts记录"这篇的结论和哪篇冲突"，same_thread记录"哪几篇属于同一条研究线索"。三者的区别在于语义强度：第一个是有向的继承关系，第二个是有向的冲突关系，第三个是无向的聚类关系。

为什么要区分这么细？因为做综述的时候你需要的东西不一样。写"研究脉络"章节时你要builds_on构成的链；写"争议点"章节时你要contradicts构成的对抗组；而当你只是想在某个方向上快速找几篇对读时，same_thread最省事。如果只用一个笼统的related字段，这三种查询全都做不了。

关系字段还有一个隐性好处：它逼你在记录时思考定位。填写builds_on的那一刻，你必须回答"这篇到底是在谁的肩膀上"，这个动作本身就是一次理解检验。

2.4 状态层：记录的生命周期

状态层管的是"这条记录现在处于什么阶段"，字段包括status、depth、added_at、review_at。

status用四态枚举：inbox（只存了链接）、reading（在读）、digested（已消化）、archived（归档不再用）。四态比"读/未读"两态好在哪？好在inbox这个缓冲区的存在。以前我遇到感兴趣的论文必须当场读完做笔记，否则就丢了；有了inbox，我可以先存链接，攒到周末批量处理，心理负担小很多。

depth用三档：skim（只看摘要和图表）、digest（通读并做结构化记录）、deep（复现或推导过）。这个字段决定了你后面引用这条记录时的可信度——一条skim级别的记录，其result字段大概率是从摘要里抄的，引用要谨慎。

review_at是我后来加的，是个日期，用来标记"什么时候该回来看一眼"。有些论文当时看不懂，但半年后你的知识背景变了，再看会有新发现。这个字段本质上是个轻量的间隔重复机制。

3. 填写规范：每个字段的边界在哪

字段定义清楚只是第一步，真正的坑在"怎么填"。同一个字段，两个人能填出完全不同的东西，校验脚本拦不住这种偏差。所以除了 schema，我还写了一份填写规范，把每个字段的"该写什么、不该写什么"用正反例固定下来。

3.1 problem 字段：写"缺口"，不写"领域"

最常见的错误是把problem写成领域名。比如写成"目标检测"，这不是问题，是范围。合格的写法是描述一个具体的缺口，比如"在遮挡比例超过 40% 的场景下，现有方法的召回率下降到不可用水平"。

判断标准很简单：能写成一个疑问句吗。"现有方法在什么条件下失效"——能问出来，说明它是个问题；问不出来，说明只是个标签。我把这条写进了规范开头，因为它是最高频的错误。

另一个边界是长度。problem我限制在 30–120 字。低于 30 字通常信息不足，高于 120 字往往是因为把背景介绍也塞进去了。背景不用写，那是论文本身的事，你要记的是它的靶子在哪。

3.2 method 字段：写机制，不写流程

method是重灾区。我早期写出来的是这样："先用编码器提取特征，然后过一个注意力模块，最后接分类头。"这是流程复述，把论文的图 2 翻译了一遍文字，没有任何信息增量。

后来我改成一句话回答"这个东西为什么能work"：它的关键机制是什么，这个机制替换掉了原来的什么，代价是什么。比如写成："把全局归一化换成逐组归一化，牺牲了跨组的信息交互，换来在小批量下的稳定性。"这一句话里有机制、有取舍、有适用条件，比三段式流程描述有用得多。

规范里我给了个检验方法：把 method 字段单独拿给别人看，对方能不能判断出这篇论文和另一篇的差别。能，就合格；不能，说明你写的是通用流程，不是这篇的特点。

3.3 tags 字段：受控词表，别自由发挥

tags我强制从受控词表里选，不允许自造。词表存在仓库根目录的一个文件里，大概三四十个词，分三组：任务类（比如"分类""生成""检索"）、方法类（比如"对比学习""蒸馏""剪枝"）、场景类（比如"资源受限""在线""多模态"）。

为什么强制？因为自由标签半年后必然出现"目标检测""检测""object detection""目标识别"四个同义词，然后你的筛选就废了。受控词表本质上是在维护一套一致的命名空间，代价是你偶尔会想说某个意思但没有现成的词——这时候正确做法是提一个新增词条的改动，而不是临时造一个。

词表我建议控制在 50 个词以内。超过这个数，人会开始记不住，然后又开始自由发挥。

3.4 关系字段：填写顺序有讲究

关系字段我规定了一个填写顺序：先填same_thread，再填builds_on，最后填contradicts。

先说为什么先填same_thread。聚类是最容易判断的，"这条和那三条讲的是同一件事"，这个直觉很可靠。先把聚类做出来，后面两个字段的候选集就从"整个库"缩小到了"同一条线索里"，工作量小一个数量级。

builds_on要后填，因为你需要先确认对方的方法确实被这篇继承或改进了，而不是单纯引用了。有些论文的引用只是"相关工作里提了一句"，那不算builds_on。

contradicts放最后，因为它的判定门槛最高，需要你真的读过两篇的实验设定才能判断结论是否真的冲突。我的经验是二三十篇里能找出一两对真冲突就不错了，如果发现满屏都是冲突，大概率是你把"适用条件不同"误判成了"结论冲突"。

一个反直觉的提醒：contradicts字段宁可留空也别硬凑。虚假的冲突关系比没有关系更有害，它会让你在写综述时得出错误的对立结论。

4. 自动化验证：把自律变成命令行

字段写清楚、规范也写了，下一个问题是执行。人是有惰性的，赶时间的时候必然走捷径。所以我把所有能机器判断的规则全部交给了脚本，剩下的才靠人。

4.1 验证规则分成三档

我把校验规则分成三档，按严格程度递增：

分档的意义在于渐进。我刚迁移存量数据的时候只开 L1，跑通之后开 L2，最后才开 L3。如果一开始全开，几百条历史记录会瞬间刷出上千条错误，人会直接放弃。

4.2 用 schema 描述 paper-map

L1 和 L2 我用 JSON Schema 描述，存成schema/paper-map.schema.json。摘一段核心部分：

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "paper-map", "type": "object", "required": ["id", "title", "year", "status", "depth", "problem", "method", "result", "takeaway", "tags"], "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^p[0-9]{4}-[0-9]{3}$" }, "year": { "type": "integer", "minimum": 1950, "maximum": 2100 }, "status": { "enum": ["inbox", "reading", "digested", "archived"] }, "depth": { "enum": ["skim", "digest", "deep"] }, "problem": { "type": "string", "minLength": 30, "maxLength": 120 }, "method": { "type": "string", "minLength": 60, "maxLength": 300 }, "result": { "type": "string", "minLength": 20, "maxLength": 300 }, "takeaway": { "type": "string", "minLength": 10, "maxLength": 150 }, "tags": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } }, "builds_on": { "type": "array", "items": { "type": "string", "pattern": "^p[0-9]{4}-[0-9]{3}$" } }, "contradicts": { "type": "array", "items": { "type": "string", "pattern": "^p[0-9]{4}-[0-9]{3}$" } }, "same_thread": { "type": "array", "items": { "type": "string", "pattern": "^p[0-9]{4}-[0-9]{3}$" } } } }

几个关键选择解释一下。additionalProperties: false是故意的——它会把字段名拼错的情况直接抓出来。我踩过一次坑，把takeaway打成了takeaways，结果所有记录的该字段都被当成"未填"，而 schema 没报错，因为多了个未知属性而已。加上这一行之后，这类错误立刻暴露。

minLength这些约束别设得太乐观。我一开始给problem设了 50 字下限，结果发现自己写的时候经常刚好卡在 45 字左右，然后再也没法精简。后来放到 30 字，反而写得更顺。约束的目的是拦住"敷衍"，不是逼你注水。

4.3 语义校验得自己写脚本

L3 的规则 schema 表达不了，得写脚本。我用一个单文件脚本tools/validate.py，核心逻辑大概是这样：

import sys, re, yaml, json from pathlib import Path ROOT = Path(__file__).resolve().parent.parent TAGS = set(json.loads((ROOT / "schema/tags.json").read_text())) def load_all(folder): records = {} for p in sorted(Path(folder).glob("*.yaml")): data = yaml.safe_load(p.read_text()) records[data["id"]] = (p, data) return records def check_semantics(records): errors, warns = [], [] for rid, (path, r) in records.items(): for tag in r.get("tags", []): if tag not in TAGS: errors.append(f"{path.name}: 未知标签 '{tag}'") for field in ("builds_on", "contradicts", "same_thread"): for ref in r.get(field, []): if ref not in records: errors.append(f"{path.name}: {field} 引用了不存在的 {ref}") if ref == rid: errors.append(f"{path.name}: {field} 不能引用自己") if r["status"] == "digested" and r["depth"] == "skim": warns.append(f"{path.name}: 状态已消化但深度为 skim，确认一下") return errors, warns if __name__ == "__main__": records = load_all(sys.argv[1] if len(sys.argv) > 1 else "papers") errs, warns = check_semantics(records) for w in warns: print(f"[warn] {w}") for e in errs: print(f"[error] {e}") print(f"\n共 {len(records)} 条记录，{len(errs)} 个错误，{len(warns)} 个警告") sys.exit(1 if errs else 0)

这段脚本里最值得说的是最后那个sys.exit(1 if errs else 0)。退出码决定了它能不能接进自动化流程——返回非零，钩子就会拦截提交。警告只打印不拦截，因为警告类规则总有合理的例外，硬拦会让人想办法绕过。

还有一处细节：status == "digested"却depth == "skim"我设成了警告而不是错误。原因是有些论文确实只看摘要就能判断不值得深读，直接标"已消化"是合理的，脚本没资格替人做这个决定。

4.4 接进提交流程

脚本单独跑很容易忘，得挂到动作路径上。我用的是提交前钩子，配置文件写成这样：

repos: - repo: local hooks: - id: paper-map-validate name: paper-map 字段校验 entry: python tools/validate.py papers language: system files: ^papers/.*\.yaml$

这样每次改动papers/下的文件，提交前都会自动跑一遍。如果只是想临时跳过，用--no-verify也行，但我建议别养成习惯——一旦开始绕过，整套约束就名存实亡了。

除了钩子，我还加了一个每周跑一次的批量检查，输出一份清单：哪些记录还是inbox状态超过 30 天、哪些reading卡了两周没动。这个清单比校验错误更有用，它管的是"进度"，而不是"格式"。

一个实操建议：把校验脚本的输出做成两行摘要放在最前面，比如"共 214 条，3 错 7 警"。人扫一眼就知道要不要细看，比刷屏几十行错误友好得多。

4.5 报错信息要能直接指导修改

这条单独拎出来说，因为它是决定这套东西能不能坚持下去的关键。校验脚本最常见的失败不是漏检，而是报了错但看不懂怎么改。

我最初的报错是validation failed: papers/p2024-031.yaml。看到这个我完全不知道哪里错了，还要自己去读 schema。后来改成三段式：文件名、字段、期望值。比如：

[error] p2024-031.yaml: method 长度 41，低于下限 60 [error] p2024-037.yaml: tags 含未知标签 '目标识别'，最接近的是 '目标检测' [error] p2024-052.yaml: builds_on 引用了不存在的 p2023-118

第二条那个"最接近的"是我后来加的，用编辑距离算一下就行，几行代码的事，但省下来的时间很多——人看到"未知标签"第一反应是自己造词错了还是拼写错了，给出候选词就能立刻判断。

5. 存量记录迁移：把两百多条历史笔记塞进新字段

新体系上线时，最麻烦的不是设计，是存量。我当时有 230 多条散落在各处的旧笔记，格式五花八门。直接重写不现实，我的做法是三步走。

5.1 先做一次空字段统计

第一步不是动手填，是量化缺口。我写了个小脚本，把旧笔记按行切分，粗略映射到新字段，然后统计每个字段的填充率。结果出来我吓了一跳：method填充率 62%，limitation只有 11%，takeaway只有 8%。

这个数据直接影响了我的策略。如果limitation和takeaway的缺口是均匀分布的，那我可能要重新考虑这两个字段是不是必要；但 11% 和 8% 这个量级说明，它们不是"难填"，而是从来没被要求填过。这反而验证了设字段的价值——正是因为没强制，这两块最有价值的信息一直是空白的。

5.2 半自动填充，别指望全自动

第二步是补全。我试过用脚本从摘要里抽句子填problem和result，效果很差——抽出来的句子大多是背景铺垫，或者带着一堆限定语的长句，读起来不像人话。后来改成"脚本生成草稿 + 人工确认"，效率高很多。

具体做法是：脚本从原文里抽出摘要的前两句、结论段的第一句，拼接成一个草稿放进method的位置，同时在前面加一个TODO:标记。然后我逐条过，把TODO改写成真正的机制描述。230 条里，能直接改两句就用的大约三分之一，需要重读的另外三分之一，剩下的三分之一直接归档——因为我发现有些笔记对应的论文我根本不记得为什么存它了，说明它对我没有价值。

这个"三分之一归档"的结果值得说一下。迁移过程本身是一次盘点，它强迫你重新面对每一条记录，而很多记录在重新面对的那一刻就自动失效了。所以别把迁移当成纯负担，它是有产出的。

5.3 复核要分优先级

第三步是人工复核。我没有平均用力，而是按一个优先级队列来：先复核被其他记录引用过的（也就是在图里有入边的节点），再复核digested状态的，最后才是inbox里的。

理由很直接：被引用过的记录一旦有错，错误会在整个引用链上传播；而inbox里的记录本来就只是个待办，错了也不影响什么。这个排序让我在只复核了 40% 记录的情况下，把最关键的那部分全部校准了。

6. 跑起来之后的检索、迭代与踩坑

6.1 几个高频查询组合

体系跑顺之后，最有价值的不是"记录得很整齐"，而是能做一些以前做不了的查询。我常用的有这么几个：

按问题域 + 深度筛：tags含某个任务词 且depth为deep，用来快速定位某个方向上我真正读懂过的论文。这个组合在写相关工作章节时特别省时间，因为它把"看过"和"读懂"区分开了。

反向引用查询：给定一篇论文，找出所有builds_on指向它的记录。这相当于一个局部的影响力分析，能看出某篇论文在你的阅读范围里被后继工作继承了几次。如果一篇论文被继承了很多次而你只记了一笔，说明它值得回去重读。

冲突对扫描：把所有contradicts关系拉出来，看看哪些冲突对集中在同一个标签下。集中出现的地方往往就是该领域真正没定论的点，也是最容易出成果的地方。

6.2 什么时候该加字段，什么时候该删

字段体系的迭代我定了个简单规则：某个信息你连续三次在自由备注里重复写，就该升格成字段；某个字段连续半年没有参与过任何筛选，就该删。

前一条我实际触发过两次。一次是"数据集"，我在备注里反复写用了什么数据，后来升格成dataset字段；一次是"代码是否可用"，也是为了快速筛可复现的工作，升格成了code字段。

后一条也触发过。review_at我本来设成必填，强制自己排复习时间，结果半年后发现我从来没有按这个字段做过任何查询，每次都是随手翻。后来改成选填，只在"当时没看懂、想以后再看"的记录上填，使用率反而上去了。

6.3 我踩过的三个坑

第一个坑是过度规范化导致记录变慢。有段时间我要求method必须写满 150 字，结果每写一条要磨十分钟，一周只记了三条。后来把下限降到 60 字，记录速度回来了，质量也没明显下降。约束的作用是防敷衍，不是防简洁。

第二个坑是忽略 YAML 的类型陷阱。year我一开始写成了字符串"2023"，在 schema 里定义的是integer，校验直接炸了。更隐蔽的是id里的p2024-031，YAML 会把它当普通字符串没问题，但如果哪天写成纯数字的2024，YAML 会解析成整数，pattern校验就永远通不过。所以我的规范里加了一条：所有 ID 类字段必须带字母前缀。

第三个坑是把校验错误当成噪音。有一阵子警告积累到几十条，我开始习惯性忽略脚本输出。这就是危险信号——一旦输出被无视，整套验证就等于不存在。后来我给自己定了个规矩：警告数超过 5 条就停下来清理，宁可少记几条新的，也不让积压。这个规矩执行了几个月，效果比任何技术改进都明显。

6.4 一个不太起眼但很省事的技巧

最后分享一个小的。我在仓库根目录放了一个templates/paper.yaml，里面所有字段都预填了占位符和长度提示，比如：

id: p2025-000 # 格式 p{年份}-{三位序号} title: "" year: 2025 status: inbox # inbox | reading | digested | archived depth: skim # skim | digest | deep problem: "" # 30–120 字，写缺口不写领域 method: "" # 60–300 字，写机制不写流程 result: "" # 有量化信息或明确结论 limitation: "" takeaway: "" # 对我当前工作有什么用 tags: [] # 从 schema/tags.json 里选

新建记录时直接复制这个文件，改个 ID 就开始填。注释就写在行尾，填的时候眼睛扫一眼就知道边界在哪，不用再去翻规范文档。这个改动听起来微不足道，但它把"查规范"这个动作从流程里消掉了，而正是那些需要额外查文档的小摩擦，最后会把习惯磨没。

这套东西我从最开始的 230 条旧笔记跑到现在六百多条，字段改过四轮，校验脚本重写过两次。回头看，真正起作用的不是字段设计得多精巧，而是那条最简单的原则：能交给机器判断的规则，一条都不要留给人。