paper-research：把论文读成能用的东西

四件事：找文献（策略）→ 读文献（卡片）→ 定方向（优化）→ 啃正文（精读）。

核心不是"生成一段像样的文献综述"，而是产出能核对的判断： 每个结论后面跟着 (p.7)，你翻到第 7 页就能看见原文那句话； 没读到的地方老实写"未读"，而不是用领域常识补上。

本机 DSH 适配规则（实测约束）

本节只记录本机环境约束。本 skill 的四处缺陷已在本机副本中修复 （含 arXiv 检索走不通），所以下文不再有"绕开缺陷"的规则。

调用方式（PDF 相关命令用这个解释器）

<py> = C:\Users\zhouyi\.agents\skills\paper-research\.venv\Scripts\python.exe
<skill> = C:\Users\zhouyi\.agents\skills\paper-research
命令：<py> "<skill>\scripts\papertool.py" <子命令> ...

本机已按正文"命令速查"的优先级 #1 建好自带 venv，装了 pymupdf 1.28.2 与 httpx 0.28.1， probe / extract / search 都可用。纯标准库部分用系统 python 也能跑，但统一用这个解释器最省事。 （依赖清单位于 <skill>\requirements.txt；缺 httpx 时只有 arXiv 一条源会失败。）

三条仍然成立的注意

1. 报告与命令对不上时，先分清"文件不存在"和"读不了文件"。 这两类现在会分别报错 （找不到文件 / 不是 PDF / 没有文字层），照提示走即可。
2. 扫描版仍要先补文字层再校验。 原文没有文字层时，verify 会把引文判为"无法核对"并给警告 （不再误报成"对不上原文"），但警告不等于通过——这类报告要回原页面图逐条人工确认。
3. probe 报的"参考文献从第几页起"在存在续页标题时可能偏大（这个上游缺陷未修）。 正文范围以自己 extract 出来的 .pages.txt 为准。

本机环境约束

• 更新本 skill 不要用 git clone：本机 git/curl 的 HTTPS 不可用 （schannel SEC_E_NO_CREDENTIALS），改用 node -e "fetch(...)" 拉 zip 解压覆盖。
• 本 skill 不碰 tempfile，沙箱目录权限坑与它无关。

已修复的缺陷（本机副本已改，上游待 PR）

本 skill 三种支撑度，别去找不存在的命令

实测基线（可拿来对照自己的结果）

四种模式：先认领任务，再动手

模式可以连着走：①找出候选 → ②筛出核心 10 篇 → ④精读 3 篇 → ③定方向。 用户只说了半句（"我上传了篇文章"）时，默认按 ④ 正文精读做，读完再问要不要接着做 ②/③。 用户批量给文献又说"快速/大致/先看看"时，按 ② 的卡片级做，别擅自升级成全文精读。

用户说不清研究问题时：先给一版工作版表述，并把你的假设逐条列出来让他推翻 （例如"我按研究对象=XX、场景=YY、时间下限=2015 来做的，不对就说"）。 不要静默假设；也不要因为拿不到答案就停下来不做。 用户明确禁止提问（"别问我"）时，同样走这条路：工作版 + 假设清单。

四条铁律

1. 无出处不下结论。 每个实质判断都要带页锚 (p.N)。引文必须逐字； 要引用中文翻译就写成 原文「…」(p.7)（译：…）——译文放在引号外面， 不然机器和人都分不清哪句是作者说的、哪句是你说的。写不出页锚的句子， 要么删掉，要么明确标注「以下是我的判断，不是本文结论」。
2. 不替作者补全。 作者没报告的（样本量、置信区间、局限），写「本文未报告 X」， 不要用领域常识填。这是本 skill 最容易犯、也最致命的错。
3. 元数据要核实。 年份、期刊、卷期、DOI、作者一律当"待核实"： 用 papertool.py meta 查 Crossref，或从原文首页抄并标注来源页。 查不到就写「未核实」，不要凭印象写 2021。
4. 覆盖度诚实。 只读了摘要就写「仅读摘要」；只读了前 6 页就写「精读范围 p.1–p.6」。 低覆盖不是错误，假称读全了才是。

写完任何一份产出，跑一遍闸门再交付（见下）。不通过的先修，别直接交。

闸门的适用范围（别用错地方）：

引号只留给逐字原文：报告里做强调用【】或反引号，不要用引号包住自己的话。 闸门把引号里的内容当"作者原话"核对，包错了轻则警告、重则被误判成编造。

工作区

跑之前先建一个工作区，产物集中放，别散在对话里：

.paperwork/
├─ <论文>.pages.txt      带 [[p.N]] 页锚的全文（精读的原料）
├─ <论文>.meta.json      页数/文字层/正文页范围/DOI 猜测
├─ 文献卡/<slug>.md
├─ 精读报告/<slug>.md
└─ 检索策略.md / 方向优化.md / 文献矩阵.md

.pages.txt 的格式和 pdf-toolkit、book-kb-builder 一致（[[p.N]] 行 + 页文本）， 所以三个 skill 的产物可以互相当输入。

命令速查

脚本在本 skill 目录的 scripts/ 下。PDF 读取需要 pymupdf，按这个顺序挑解释器：

# 1) 本 skill 自带 venv（如果建过）
<本skill目录>/.venv/Scripts/python.exe
# 2) 否则用 pdf-toolkit 的 venv（本机已装好 pymupdf，Win 路径）
~/.agents/skills/pdf-toolkit/.venv/Scripts/python.exe
# 3) 都没有就用系统 python —— 除 probe/extract 外都能跑（纯文本、检索、校验不需要 pymupdf）
python

# 探 PDF：页数、有没有文字层、参考文献从第几页起（含"参考文献同页仍有正文"的提醒）
<py> scripts/papertool.py probe 论文.pdf

# 抽带页锚的全文 → .paperwork/<标题>.pages.txt
<py> scripts/papertool.py extract 论文.pdf --out .paperwork

# 开放检索（现在就能跑的三个源）
<py> scripts/papertool.py search "query" --source crossref|arxiv|pubmed --n 10 --from-year 2018

# 元数据核实（写进报告前必做）；arXiv 的 10.48550/... DOI 会自动转走 arXiv API
<py> scripts/papertool.py meta --doi 10.18653/v1/N19-1423
<py> scripts/papertool.py meta --title "Attention Is All You Need"

# 找合法免费全文（Unpaywall）；查不到就说查不到，别硬凑
<py> scripts/papertool.py oa --doi 10.3390/buildings16142775

# 生成各库检索式（同义词分组、括号、字段标签都由脚本保证正确）
<py> scripts/build_queries.py --in concepts.json --out 检索策略.md --truncate

# 闸门：页锚越界 / 引文对不上原文 / 数字在原文找不到 / 缺覆盖度声明
<py> scripts/papertool.py verify --report 精读报告.md --corpus .paperwork/论文.pages.txt
<py> scripts/papertool.py verify --report 文献矩阵.md \
     --corpus .paperwork/A.pages.txt --corpus .paperwork/B.pages.txt --corpus .paperwork/C.pages.txt

verify 退出码 0 才叫通过。它报两类问题：错误（必须改，改不了就删句）和 警告（逐条自己判断，别一律删）。同类问题超过几条会自动折叠成一条带计数， 省得几百行刷屏。它认这些写作约定：

• 引文与页锚要挨着：「原文」(p.7) 或 (p.7)「原文」；两者之间只允许少量标点或 几个字的引导词。离得太远会被判成"无锚引文"（警告），不会硬配到远处的锚上。
• 代码块（``` 围起来的部分）里的引号和数字一律跳过——检索式、JSON、路径不该被核对。
• 元数据行（含 DOI / 核实于 / 被引 / 卷期页 等字样的行）上的数字跳过： 那些数字本来就不在正文里，另有核实渠道。
• 中文报告里把西文原文译成中文放在引号内，会降级成警告并提醒你标「译」。 编造的中文引文这个闸门查不出来，通过时它会明确告诉你还有几段没核对。

各模式怎么做

① 检索策略

问清楚三件事再动手：研究对象/人群、场景或数据、干预或变量。 拿不准就先问用户，或者先给一版让他改——不要凭空替他假设研究问题。

流程：概念分解 → 凑同义词（从 3–5 篇种子文献里抄词，别凭空想）→ build_queries.py 生成各库检索式 → 定纳排标准 → 金标准测试 → 记录表。 方法细节、各库语法差异、宽窄调参见 references/search-strategy.md。

能跑的和不能跑的要说清：CNKI、Web of Science、Scopus 需要机构订阅， 你跑不了——给用户的检索式是让他去库里跑的。开放源（Crossref、arXiv、PubMed） 你可以当场跑，把命中列表当种子文献给出去，每条都标注来源与检索日期。

② 文献卡 / 文献矩阵

单篇 → 按 assets/templates/文献卡.md 填；一批 → 按 assets/templates/文献矩阵.md 做成对齐表（文献 × 问题/方法/数据/样本/指标/结论/缺口）。

「一句话定位」是这张卡的核心，句式： 本文用【方法】针对【问题/对象】发现【结论】，不超过 40 字，必须能在原文找到依据。 关键词给 3–6 个，优先用作者自己的 keyword（标明「作者关键词」）， 自己加的要标明「我加的」——混在一起以后就分不清了。

③ 方向优化

先铺缺口矩阵（已读文献 × 研究要素），空格就是候选缺口； 再按 references/direction-refinement.md 的类型学给缺口分类， 用"可回答吗 / 有人做过吗 / 做得出吗"三问筛一遍； 最后写成一句可检验的方向陈述，并给出与最接近的 3 篇的差异点。

不要为了让用户安心而夸大新颖性。 "我没查到"不等于"没人做过"， 每次都要写清结论只基于哪几篇、检索覆盖了什么范围。

④ 正文精读

顺序：标题摘要 → 引言（问题、缺口、贡献声明）→ 方法 → 结果 → 讨论/局限 → （可选）附录与参考文献。每一节要抓什么、怎么标页锚、怎么区分 "作者声称"与"证据支持"，见 references/close-reading.md。

主结果一律抄成表（条件/指标/数值/来源页），不要用转述代替数字。 长论文分段读：先把读过的部分写成报告，再继续读，别一口气读 40 页才开始写。

与其它 skill 的交接

常见坑

• 预印本 ≠ 正式版：arXiv 版和期刊版的年份、卷期、结论措辞都可能不同， 引用时写清用的是哪一版。同一条结论在摘要、正文表格、结论之间也可能不一致 ——遇到这种情况以表格/正文的数字为准，并把原文自身的不一致写进报告。
• 元数据核实的三条现实：① meta --doi 对 arXiv 的 10.48550/... 会转到 arXiv API， 但 NeurIPS/ICML/CVPR 这类会议论文集 Crossref 覆盖很差，常常查不到，改用官方 proceedings 页或 arXiv 页面并在报告里写明核实渠道；② meta --title 会返回同名记录 （书评、章节、重复投放），不要拿第一条当答案，看相似度、看作者与年份； ③ 查不到就写「未核实」并说明你查了什么，绝不编一个 DOI。
• 摘要会夸大：摘要里的"显著提升"在正文里常带条件（特定数据集、特定基线）。 要写具体数字，必须读正文对应段落并带页锚。
• 图内文字抽不出来：pages.txt 里只有文字层的内容，图里的坐标轴标签、 流程图文字可能缺失。发现"图里的关键信息读不到"就如实说明， 必要时用 pdf-toolkit render 出页图后看图。
• 参考文献那页常常还有正文：双栏排版会把结论、致谢排在参考文献同一页的另一栏， 附录也会跟在参考文献后面。probe 会提醒，别看到"参考文献"就停止阅读。
• 综述不是证据：综述用来找缺口和滚雪球（翻它的参考文献）， 它的结论不能当作原始证据引用。
• 被引数要给来源和日期：Crossref 的被引数偏低，Scholar 偏高， 写的时候注明"据 X，检索于 YYYY-MM-DD"。
• 出版商网页多半下不动：MDPI/Elsevier/Frontiers 等会挡非浏览器请求。 papertool.py oa 拿到链接后如果下载失败，改用 WebFetch 读落地页， 或用 WebSearch 找机构库版本；找不到就基于摘要写并标注「仅基于摘要」。
• CNKI 的 .caj 不能按扩展名判断：同一个 .caj 下面混着两种格式——有的是标准 PDF （能直接读），有的是 CNKI 专有 CAJ（读不了）。脚本按文件头判断并在遇到专有格式时 给出重下建议；一个文件夹里混装时用 probe <整个目录的 *.caj> 一次性盘点，它读不了的 会逐条跳过并列出清单，不会中断。中文期刊的 PDF 常是大字号著录项排在最上面， 标题猜测偶尔会指错，遇到可疑标题回首页核对一下再引用。
• 中文期刊的元数据基本核实不了：CNKI 的 DOI 前缀 10.13806、10.3969 等多不在 Crossref，标题检索返回的往往是同主题的另一篇文章（相似度会很低，工具会明说"没有一条 像你要找的"）。这时以原文首页（题名/作者/刊名/卷期/文章编号/页脚 DOI）为准抄录， 并写清"未在 Crossref 核实，来源为原文首页"。
• 别假装读过：拿不到全文就基于摘要写，并在开头写明"仅基于摘要"。