paper-notes

论文笔记

触发条件与路由

• 触发条件：论文笔记、结构化笔记、阅读笔记、论文笔记、paper_notes.jsonl。
• 适用场景：综述的证据阶段（C3）；已有 papers/core_set.csv（以及可选的全文），需要为后续 claims/citations/writing 准备可引用的证据。

生成一致且可搜索的论文笔记，供后续步骤（claims、可视化、写作）可靠地综合使用。

这仍然是不写正文：笔记应采用项目符号或简短字段，而非叙述性段落。

加载顺序

始终阅读：

• references/overview.md
• references/note_schema.md

按任务阅读：

• 编写或审查局限性时，阅读 references/limitation_taxonomy.md（避免套话）
• 提取 key_results 时，阅读 references/result_extraction_examples.md（查看优劣示例）
• 当 result/limitation 字段仍保留论文自述或作者包装的结果表述时，阅读 references/source_text_hygiene.md

机器可读资源：

• assets/note_schema.json — 用于验证的 JSONL 记录架构
• assets/evidence_tags.json — 证据库标记类别（可扩展，无需更改代码）
• assets/source_text_hygiene.json — 笔记字段的源句清理策略
• 仓库级 assets/limitation-signals.json — 用于区分尚未解决的约束与已解决的失败或改进的共享极性规则

脚本边界

仅将 scripts/run.py 用于：

• 根据 core_set 和元数据生成确定性脚手架
• 根据映射覆盖率进行优先级选择
• 根据结构化笔记字段构建证据库

不要将 run.py 用作：

• 撰写论文专属的局限性文字（请参考 references/limitation_taxonomy.md）
• 在代码中隐藏领域专属评估启发式规则
• 编写面向读者的叙述文本

角色卡（提示词级指导）

• 细读者

  • 任务：提取具体且可核查的内容（设置、方法、指标、限制）。
  • 应做：指出具体任务/基准以及论文实际测量的内容。
  • 避免：可套用于任何论文的泛泛总结套话。

• 结果记录员

  • 任务：记录后续写作所需的评估锚点。
  • 应做：尽可能记录任务 + 指标 + 约束（预算/工具访问权限）。
  • 避免：脱离使数字具有意义的评估设置，单独照抄数字。
  • 避免：将对成果的介绍（X enables ...、our framework features ...）提升为 key_results。
  • 避免：将基准定位、领域动机或作者行文导引类句子（we apply ... and show ...、we then discuss how ...）提升为 key_results。

• 局限记录员

  • 任务：记录会改变解读方式的注意事项。
  • 应做：撰写论文专属的局限性（协议不匹配、缺少消融实验、威胁模型缺口）。
  • 避免：反复使用“可能无法泛化”等缺乏具体内容的通用局限性。

适用场景

• 已有核心文献集（最好也有映射），并需要准备好可用于证据的笔记时。
• 撰写综述草稿之前。

输入

• papers/core_set.csv
• 可选：outline/mapping.tsv（用于确定优先级）
• 可选：papers/fulltext_index.jsonl + papers/fulltext/*.txt（在全文模式下运行时使用）

输出

• papers/paper_notes.jsonl（JSONL；每篇论文一条记录）
• papers/evidence_bank.jsonl（JSONL；根据笔记生成的可寻址证据片段；目标配置：课程论文平均每篇 >=4 项，A150++ 平均每篇 >=7 项）

决策：证据深度

• 如果已提取文本（papers/fulltext/*.txt）→ 使用全文片段丰富重点论文，并设置 evidence_level: "fulltext"。
• 如果只有摘要（默认情况）→ 长尾笔记保持摘要级别，但仍需充分丰富高优先级论文（见下文）。

工作流（启发式）

使用：outline/mapping.tsv、papers/fulltext_index.jsonl。

1. 确保覆盖完整：papers/core_set.csv 中的每个 paper_id 都必须有一条 JSONL 记录。
2. 使用映射表选择高优先级论文：
   • 在多个子章节中被大量复用
   • 固定经典论文（ReAct/Toolformer/Reflexion…，如果在范围内）
3. 对于高优先级论文，记录：
   • 3–6 条摘要要点（新内容、问题设定、循环过程）
   • method（机制和架构；与基线有何不同）
   • key_results（基准测试/指标；如有数据，请注明）
   • limitations（具体假设/失效模式；避免泛泛而谈的套话）
4. 对于长尾论文：
   • 摘要要点保持简短（可基于摘要）
   • 仍至少包含一项局限，但尽可能具体
5. 为每篇论文分配一个稳定的 bibkey，用于生成引文。

质量检查清单

• 覆盖完整：papers/core_set.csv 中的每个 paper_id 都出现在 papers/paper_notes.jsonl 中。

• 高优先级论文的 method/results/limitations 均非 TODO。

• 不要在多篇论文中复制粘贴相同的局限。

• 正确设置 evidence_level（abstract 与 fulltext）。

• 证据库：papers/evidence_bank.jsonl 存在，且符合所选配置（课程论文平均每篇 ≥4 条；A150++ 平均每篇 ≥7 条）。

辅助脚本（可选）

快速开始

• uv run python .codex/skills/paper-notes/scripts/run.py --help
• uv run python .codex/skills/paper-notes/scripts/run.py --workspace <workspace>

所有选项

• 参见 --help（此辅助脚本有意保持精简）

示例

• 生成笔记，然后可选择性地补充 priority=high 的论文：
  • 运行一次辅助脚本，然后完善 papers/paper_notes.jsonl（例如，为关键论文添加全文细节并丰富局限）。

备注

• 辅助脚本会生成确定性的元数据/摘要级笔记，并将关键论文标记为 priority=high。
• 在 pipeline.py --strict 模式下，如果高优先级笔记不完整（缺少 method/key_results/limitations）或包含占位符，流程将被阻止。

故障排除

常见问题

问题：高优先级笔记看起来仍像脚手架

症状：

• 质量门禁报告缺少 method/key_results 或存在 TODO 占位符。

原因：

• 笔记仅根据摘要生成；关键论文尚未补充完善。

解决方案：

• 完整补充 priority=high 的论文：填写 method、≥1 项 key_results、≥3 条 summary_bullets、≥1 项具体的 limitations。
• 如果需要全文证据，请对关键论文以 fulltext 模式运行 pdf-text-extractor。

问题：多篇论文中重复出现相同局限

症状：

• 质量门禁报告存在重复的局限套话。

原因：

• 复制粘贴了局限，而非描述论文特有的失效模式/假设。

解决方案：

• 用论文特有的局限替换套话（设置、数据、评估缺口、失败案例）。

恢复检查清单

• papers/paper_notes.jsonl 涵盖 papers/core_set.csv 中的所有 paper_id。
• ≥80% 的 priority=high 笔记满足 method/results/limitations 完整性要求。
• 高优先级笔记中不再有 TODO。