ljg-paper · diff
git:20260820.e62dabe to git:20260905.682e50b
33 added, 45 removed. Audit A to A.
---
name: ljg-paper
- description: "Paper reader for non-academics. Reconstructs a paper on three independent axes: the reader can identify its research problem and product, experience the evidence-driven change in understanding, and rebuild the mechanism, central experiment, and boundary. USE WHEN the user shares an arXiv link, paper URL, PDF, local paper, paper title, or asks to read, explain, analyze, or understand a paper. Defaults to a saved Org note. NOT FOR reproduction, formal peer review, benchmark tables, or literature surveys."
+ description: "Explain research papers to readers without a specialist background: what the paper studies, what the authors contribute, how the findings follow, and what the evidence does not establish. USE WHEN the user shares an arXiv link, paper URL, PDF, local paper, or paper title, or asks to read, explain, analyze, or understand a paper. Defaults to a saved Org note. NOT FOR reproduction, formal peer review, benchmark tables, or literature surveys."
---
- # ljg-paper：让一篇论文可辨认、可经历、可重建
+ # ljg-paper：讲清论文，让读者理解结论是怎样得来的
- 具体案例负责让读者进入，不能替代论文身份。证据负责迫使理解改变，不能变成前台配额。最终成品既要读得进去，也要让陌生读者知道作者面对什么旧缺口、实际造了什么、为什么结果改变、证据停在哪里。
+ 面向没有专业背景的读者，把一篇论文讲清楚：它研究什么问题，已有方法哪里不够，作者提出了什么，以及证据能支持到什么程度。
- 稳定的扶手不一定是同一个物件。它可以是一个研究问题、一段因果关系、一条组件链、一个不断受压的判断，或几个同时作用的变量。载体可以在前一个结果已经逼出下一问时更换；读者正在追问的事不能丢。
+ 具体案例帮助读者理解论文。案例中的对象、方法和结果要与论文对应起来，避免故事讲得很顺，读者却仍然不知道这篇论文做了什么。
+ 全文应围绕清楚的问题展开。随着解释深入，可以更换案例或场景，但要交代它与前文的联系，以及为什么需要借助它继续说明。
+
## Workflow Routing
- | 输入 | 必读 | 输出 |
+ | 输入 | 必读材料 | 输出 |
|---|---|---|
- | arXiv、PDF、paper URL、本地论文 | `ReadingGuide.md`、`references/template.org`、`references/paper-map.md` | 保存一份由论文内容命名的 Org 与后台 paper-map |
- | 只有论文标题 | 找到可靠原文后读同一组文件 | 保存 Org 与 paper-map |
- | 用户明确只要口头解释 | `ReadingGuide.md` | 不写文件，仍兑现同一三重合同 |
-
- Org 默认保存到 `~/Context/`。文件名沿用 Denote：`{YYYYMMDDTHHMMSS}--paper-{方法名或论文关键词}__paper.org`；时间戳由 `date +%Y%m%dT%H%M%S` 生成。
-
- ## 三重成品合同
-
- - **论文身份。** 只读成品的人能说出研究对象、旧方法看不见什么、作者的产物或贡献类型、组件怎样从输入运行到输出、哪些研究主线不可省，以及最强证据边界。最迟读完前两个一级标题，这条方向必须已经出现。
- - **认识更新。** 读者先在具体处境中形成自然理解，再亲眼看见论文证据为什么使它不够；新关系只在需要时出现，并立即改变原来的判断、动作或尺度。
- - **解释重建。** 若论文存在能推出多个结果的机制、过程或测量关系，读者能用它解释至少两个相隔较远的发现、预测一个相邻条件，并指出失效边界。没有单一生成器时明确说明，不用公式伪造完整性。
-
- 任一边失败都不能交付。只有论文身份，会得到准确却费力的摘要；只有认识更新，会得到一篇流畅但可以移植到许多论文上的主题文章；解释无法重建时，案例再顺也仍把最难的归纳留给读者。
+ | arXiv、PDF、论文链接、本地论文 | `ReadingGuide.md`、`references/template.org`、`references/paper-map.md` | 一份 Org 解读笔记和一份 paper-map 研究记录 |
+ | 只有论文标题 | 找到可靠原文后，读同一组文件 | Org 笔记和 paper-map |
+ | 明确只要口头解释 | `ReadingGuide.md` | 直接解释，不保存文件；仍满足下面三个目标 |
- ## Gotchas
+ Org 默认保存到 `~/Context/`。文件名沿用 Denote：`{YYYYMMDDTHHMMSS}--paper-{方法名或论文关键词}__paper.org`；时间戳由 `date +%Y%m%dT%H%M%S` 生成。改写已有笔记时，保留原文件与 identifier，核对原文，不另建重复笔记。
- - **局部因果顺畅，不等于整篇论文已经出现。** 一个例子、三句复述和若干数字可以全部正确，读者仍可能不知道论文研究什么、造了什么。真实读者出现这种反馈时，重建论文坐标，不润色句子。
- - **扶手稳定，载体不必固定。** 强迫一个日常物件承载多研究问题，会把后半篇写成指标附录。多组件或多问题论文可以换场，前一个结果必须说明为什么现在非换不可。
- - **作者的产物必须可辨认。** 方法、理论、评测、资源或系统不是背景标签；读者要知道作者实际增加了什么可运行对象、关系、尺子或可行范围。
- - **突出中心不能删掉独立主线。** 论文若明确以多个研究问题组成同一产物，paper-map 要记录每条主线为何不可省、证据是否闭合；正文可以压缩，但不能让陌生读者误认论文只做了中心实验。
- - **后台覆盖不能变成正文配额。** paper-map 可以保留全部实验；正文只留下中心证据，以及没有它就无法逼出下一次认识变化的必要证据。
- - **数字没有实验坐标就只是噪声。** 数据进入前，读者应已知道它在回答什么、固定了什么、和谁比较；数据之后立刻说明它改变了什么判断。
- - **把数字拆进短段，仍然是数字主导。** 单段不过载不能证明全文有叙事；默认正文只保留一个结果形状。只有论文的主产物本身是新尺子或评测、且少一层定量对照就无法看见产物时，paper-map 才能说明额外定量前台，完整表格和分支结果仍留在后台。
- - **稳定主题不等于解释生成器。** “更可靠、更智能、更通用”不能推出具体结果。生成器必须固定输入、作用关系、结果方向与失效条件。
- - **相邻标题可以换序，说明仍是平行摘要。** 每个新标题都要继承上一段尚未解决的问题；换序测试写进 paper-map。
- - **边界不能把写作者带进镜头。** 来源身份、删留决定和核验状态留在 paper-map；正文只写眼前对象已经回答什么、再往前还需要什么条件。
- - **机械通过不能证明理解。** validator 只拦截结构退化；论文身份五问与认识更新三句复述必须由未参与写作的新上下文完成。
+ ## 解读要达到的三个目标
- ## Quick Reference
+ - **说清论文做了什么。** 读者能说出研究问题、作者的主要贡献、方法或关系如何起作用，以及关键证据的适用范围。读到前两节时，就应知道论文在研究什么、作者做了什么。论文中不可省略的研究问题也要有所交代。
+ - **让读者理解为什么需要修正原有认识。** 从具体问题出发，说明通常会怎样理解，再用论文证据展示这种理解哪里不够、作者补充了什么、判断因此发生了什么变化。变化可以是纠正，也可以是补充、区分或缩小适用范围，无须制造戏剧性的反转。
+ - **让读者能够自己解释结果。** 如果论文提出了能解释多个发现的机制，读者应能用它说明至少两个不同发现，并推想改变相关条件后会发生什么。区分论文验证过的结论与依据机制作出的预测。论文没有统一解释时，如实说明各项发现之间的关系和仍未解决的问题。
- - 用原始论文锁定研究对象、旧缺口、作者产物、组件链、中心发现与边界，再选择前台案例。
- - 先在 `paper-map` 给证据分级：中心、必要、后台；级别不是数量配额。
- - 开头让普通读者进入，前两个标题内让论文身份和必要的生成器开始运行。
- - 一个中心主张只保留一个代表结果形状的证据单元；完整模型名、表格与分支结果留在后台。
- - 陌生读者先不用数字讲回发生链，并说明标题为何不能换序；只会复述分数或实验清单即失败。
- - 交付同时通过叙事主位门、五问论文身份门、三句认识更新门、Denote/consult-notes/Org lint 与确定性 validator。
+ 三个目标分别检查。讲得流畅、内容准确、能够解释结果，各有要求，不能相互替代。
- ## Examples
+ ## 容易出错的地方
- **方法论文**
+ - **案例讲清了，论文仍可能没讲清。** 读者说不出研究问题或主要贡献时，回到原文重新组织解释。只修句子无法补上缺失的内容。
+ - **不要强迫一个例子讲完整篇论文。** 一个案例说明不了所有研究问题时，可以换例子，保持问题与解释的联系。
+ - **贡献要说具体。** 写出作者提出的方法、理论、评测、资源或系统具体增加了什么。评测发现差异，不等于已经解释差异的原因。
+ - **重点突出，也要保留重要分支。** paper-map 记录每条必要研究主线及其证据；正文说明它们如何共同回答论文的问题，不能把整篇论文缩成一个中心实验。
+ - **按信息作用取舍证据。** 优先讲清最有代表性的结果。补充结果应提供不同信息、限制结论或解释例外；不按实验数量平均分配篇幅，也不强求全文只写一种结果。
+ - **数字需要上下文。** 交代实验在问什么、固定了什么、和谁比较，再说明结果改变了哪个判断。把数字拆成短段，或全部写成汉字，都不能代替解释。
+ - **章节可以递进，也可以并列。** 换序用于检查联系是否清楚。两个独立实验可以交换顺序，但应说明它们分别支持什么、为什么都需要。
+ - **检查工具只能检查格式与记录。** 它不能证明文章易懂。理解检查由未参与写作的新上下文完成，评估者只读最终笔记，并按 `ReadingGuide.md` 检查自己是否用专业知识补足了正文缺失的前提。
- 读者先让旧做法在一个小任务里得到结果。作者的产物随后以输入→组件→输出链出现；中心实验固定任务与预算，只改变关键动作。结尾说明新方法改善了哪一步，以及换掉哪个条件后仍未知。
+ ## 示例
- **评测论文**
+ **方法论文：** 用一个小任务说明旧做法卡在哪里，再解释新方法如何处理输入、经过哪些关键步骤、得到什么结果。中心实验说明比较条件与动作差异，结尾交代改善发生在哪一步，以及哪些情况仍未验证。
- 两份对象先被旧尺子判成相同。论文的新尺子让一个此前被压平的差异可见；代表性对照说明它能区分什么。成品停在“差异变得可测”，不把新 benchmark 冒充成现实因果解释。
+ **评测论文：** 两个系统在旧指标上表现相近，新评测发现了原先没有区分的差异。解释新评测测量什么、代表性对照显示了什么，以及这些差异能支持哪些判断。不要把测量结果直接写成现实中的因果结论。
- ## Completion
+ ## 保存与检查
- 写作与取舍遵循 `ReadingGuide.md`；Org 使用 `references/template.org`；后台复制并填写 `references/paper-map.md`。
+ 具体写法见 `ReadingGuide.md`。正文使用 `references/template.org`，研究与取舍记录使用 `references/paper-map.md`。新记录使用格式版本 3；验证脚本兼容旧版本 1、2，旧记录不必为了本次升级批量改写。
写入后运行：
```sh
bun {skill_dir}/scripts/validate_note.ts /absolute/path/to/note.org \
--map /absolute/path/to/paper-map.md
```
- 随后用真实 Emacs 读回 Denote identifier、文件名、目录索引、consult-notes 与 `org-lint`。最后只给陌生读者成品：先不用阿拉伯数字讲回全文发生链、说出最先留下的机制，并用相邻标题换序说明因果依赖；得到 `NARRATIVE_PASS` 后，才回答研究问题、贡献／产物、组件链、实验坐标、最强边界五问，前两问任何一项含混即失败；再用三句普通话复述原理解、论文改写、结果与边界。叙事、身份与认识更新三张成绩单互不补分。
+ 用真实 Emacs 读回 identifier、文件名、目录索引、consult-notes 与 `org-lint`。再按指南完成独立阅读检查，记录全文复述、研究问题与贡献、认识变化、结果解释四项结果。全部通过后重新运行脚本，确认最终文件与检查记录一致。
+
+ 验证脚本接受尚未填写阅读检查结果的记录用于诊断，但会返回失败；不能先写 PASS 再请人检查。验证器或独立评估不可用时，明确报告哪项尚未完成。