paperconan

paperconan

paperconan 会扫描论文源数据表，并可注册本地图像资源，供外部 Agent 审查。请将每项命中都视为信号，而非定论：报告位置和模式，绝不推断意图或指责个人。PaperConan 不管理模型密钥或提供商 SDK，也不执行自主语义判断。

工具仓库：https://github.com/zixixr/paperconan

核心工作流

0. 扫描前确认 CLI 可用：运行 paperconan --version。如果 CLI 缺失且 pip 可用，请运行 pip install "paperconan[all]" 安装一次（如果用户倾向于使用虚拟环境或非全局安装，请先询问；如果 pip 因 PEP 668 的 externally-managed-environment 错误而拒绝安装，请改用 uv tool install "paperconan[all]" 或 pipx install "paperconan[all]"——请参阅“安装和运行”）。如果 Python/pip 不可用，请让用户自行安装并在本地运行，绝不要编造输出。
1. 确认用户提供的内容：
   • 本地源数据目录：运行 paperconan <input-dir>。
   • DOI 或标题：运行 paperconan fetch "<DOI or title>"，选择匹配的表格数据集，下载后扫描下载目录。
   • 仅有现成的审计结果：读取 audit/scan.json，并使用 audit/report.html 作为证据浏览器进行分类梳理，然后给出判定后的回答。不要将原始 report.html 直接作为“结果”交给用户（请参阅下文“报告的定位”）。
2. 优先使用真实 CLI。不要凭肉眼查看表格来编造发现。
3. 分层读取扫描结果——从 paperconan overview 开始，而不是解析整个 scan.json（请参阅下文“分层读取扫描结果”）。加载任务所需的参考文件。
4. 将严重发现描述为值得跟进时，请打开原始表格。如果原始数据不可用，请说明该发现尚未核实。
5. 谨慎作答：解释异常、合理的非恶意解释，以及需要哪些人工背景信息。

分层读取扫描结果

一篇论文的补充材料通常会产生数百到数千条发现，以及一个数 MB 的 scan.json。通读全部内容会浪费你用于判断的注意力，也会让少数值得采取行动的信号淹没在大量常规结果中。

检测器会刻意扩大检测范围，避免真实信号因阈值而遗漏，因此缩小范围要靠你在阅读方式上下功夫，而不是改变检测结果。不会过滤任何内容；你可以分阶段逐步查看。

paperconan overview audit/scan.json                    # which locations carry signal
paperconan drill    audit/scan.json 2                  # that location, grouped by kind
paperconan drill    audit/scan.json 2 --kind identical_column
paperconan explain  audit/scan.json seed:17942ad206854a66
paperconan explain  audit/scan.json seed:17942ad206854a66 --full

需要结构而非文本时，可为其中任一命令添加 --json。

证据窗口有界，并会明确说明。 扫描结果会保存高亮单元格周围的窗口，而非整个区块——对于密集的补充材料，这些窗口可能占文件的大部分字节。经过裁剪的窗口会标明自身范围，例如 ! this window is 20x30 of a 300x200 block, trimmed by the scan.。应将其理解为“异常在此处，而且你看到的内容并未涵盖整个区块”，而不是把窗口当作整个区块。需要核对具体单元格时（例如将数值与论文对照，或判断某种模式是否贯穿整列），explain --full 会从源数据重新读取该区块。

--full 遇到不确定情况会拒绝，而不会猜测。扫描结果会记录每个输入的大小和时间戳，因此如果源文件已移动、被编辑，或已缺失该发现涉及的行或列，就会返回原因且不提供行数据——盲目读取会让你在此发现的标题下看到一张不同的表。需要了解两个限制：如果源文件被重写为相同字节数且时间戳恢复原样，则无法检测到（检查只比较大小，不比较内容）；如果扫描是在此检查功能推出前生成的，则会退回到比较范围，这能发现源文件缩小，但无法发现原位编辑。它还会受单元格数量上限限制（PAPERCONAN_MAX_FULL_EVIDENCE_CELLS）；如果窗口受此上限限制，会明确说明并指出该变量，而不是让你重新运行 --full。

逐层深入，找到足以回答问题的最浅层后就停止：

1. 概览 — 涉及哪些位置、信号有多强、有哪些类别。通常足以看出某个位置上的派生关系被反复重述了许多次。
2. drill <n> — 该位置上的各类发现，以及每类一个具体示例。n 较大且示例模式化的类别，通常表示某种结构被反复表达；n=1 的类别仍可能是该位置上最强烈的信号。
3. drill <n> --kind <kind> — 各项具体发现，每项都有一个 id。
4. explain <id> — 一项发现及其参数和证据表。在判断某项内容值得跟进之前，先打开原始表格。

阅读时请牢记三点：

• detector=high displayed=low 表示显示配置降低了它的权重，并不代表它是良性的。 explain 会打印记录的原因。请判断这个原因——密集区块或重复轴通常是合理判断，但完全重复的列可能仅仅因为与许多其他关系共享一个区块而被降级。不要因为某项发现显示的严重性较低就跳过它。
• 阅读 ! 行——每一层都有。 overview 和两种 drill 形式都包含 coverage 区块；explain 会在行内说明自身的限制（扫描裁剪掉的证据窗口、只有 --json 才会显示的结构化参数）。这些内容会说明哪些内容未显示以及原因：超出所列数量的位置、超出列表上限的发现、此层不处理的类别（数字分布、小数结尾、图像发现）、扫描自身的上限在各层看到之前就丢弃的发现，以及仍未进入任何渠道的检测器级上限。提高 --max-locations / --max-findings 可查看更多剩余内容；其余限制属于扫描本身，而非视图。
• scan: 行说明扫描层的限制，不只是检测器的限制。 以下是你最常遇到的形式，均为原样引用；代码还会以相同形式输出其他内容（作用于工作表的行会在文件名后附上工作表名称）。完全跳过检测器的情况除外——它们不会进入任何渠道，也不会在此处显示名称。
  • scan: file too large in big.xlsx——文件完全未被读取。scan: unreadable in notes.xlsx 属于同一类：该文件中没有任何内容经过检查。
  • scan: formula cache missing in m.xlsx Fig 3b (cells=['C4', 'C5', 'C6'], count=812)——count 是没有存储缓存值的公式单元格数量；cells 是一小部分示例，而非完整集合。paperconan 从未看到这些单元格计算出的数值，因此这些数值未经审计，且该工作表部分内容未读取。
  • scan: formula cache unreadable in m.xlsx——公式缓存检查本身未能完成，因此 paperconan 无法判断该文件是否包含未读取的公式单元格。没有针对该文件的 formula cache missing 行并不能证明什么。formula metadata byte limit 和 formula metadata sheet limit 属于同一类，分别指出是哪项限制中止了检查。
  • scan: report block limit in m.xlsx Fig 3b (count=3)——该工作表的区块收集在输出预算用尽时停止，因此之后的区块从未经过分析。两项预算都会输出同一行：提高 PAPERCONAN_MAX_REPORT_BLOCKS；如果没有变化，再提高 PAPERCONAN_MAX_TOTAL_FINDINGS。
  • scan: detector candidate pool limit in detect_short_row_reuse (limit=400)——检测器达到上限后停止生成候选项，因此之后的行从未进行比较。
  • scan: detector finding limit in detect_row_pair_digit_coupling (limit=25)——检测器达到上限后停止输出发现。
  • scan: detector compute budget limit in detect_row_relations——检测器耗尽了工作预算。
  • scan: detector row limit in detect_local_pair_runs——高于 PAPERCONAN_LOCAL_RUN_MAX_ROWS 的区块在此轮处理中不会逐行比较；其列仍会比较，除非该区块的宽度也超过 PAPERCONAN_MAX_BLOCK_COLS，此时列对也不会比较。
  • scan: detector within row folded independent repeat in detect_recurring_row_vectors (count=2)——这不是截断，而是省略：行内处理会将同一次物理重复产生的重叠窗口合并为一项发现；这些合并后的候选项中，有这么多在本页没有任何发现覆盖的位置也重复出现。该计数就是记录中的全部信息；要找到具体位置，需要阅读该行。 以上任何一种情况都表示 scan_status 不是 complete（可能是 partial，也可能在完全无法读取时为 failed），因此该输入没有报告结果，并不能证明内容没有问题。本段其余部分讨论的是被截短的行，也就是上面除 detector within row folded independent repeat 以外的所有行。（这里按名称列出，而非按位置列出，因此即使追加一个项目，这句话也不会悄然对其中两项说错。）该项报告的是遗漏而非截断：没有内容未被检查，阅读该行即可解决问题。但它也并非独立于上限——它会与已输出的发现进行比较，因此当同一检测器在同一次扫描中出现 detector finding limit 时，较窄的输入可能输出更多内容，并改变该行是否出现。曾在实际的补充材料中见过这种情况。两项同时出现时，请结合起来阅读。 检测器行不会注明 文件或工作表：记录中没有这类信息，因此该行无法告诉你截断发生在哪里——可能是一个区块，也可能是多个区块。原样重新运行无法证明任何事情：扫描是确定性的，因此会逐字节重现相同的截断结果。提高相应的 PAPERCONAN_* 上限（PAPERCONAN_SHORT_ROW_MAX_ROWS、PAPERCONAN_ROW_PAIR_MAX_ROWS、*_BUDGET 变量），或使用范围更窄的输入重新运行。有些上限是固定默认值，没有可调参数；对于这些上限，缩小输入范围是唯一的解决办法。另有一条注意事项涉及整个检测器被跳过的情况（区块过宽或过高）；这类区块不会进入任何通道，因此这里不会列出。
• 概览中没有提示，并不代表文档没有问题。 这表示这些检测器在所提供的数据中，按照当前阈值没有发现问题。

从特定主张入手

overview 回答的是“哪里有信号”，当你一无所知时，这是正确的首要问题。但如果你已经有了一个主张——有人说这篇论文的图 2j 看起来有问题——那就不该问这个问题，因为没有发现的工作表根本不会出现在那里，而“没有发现”恰恰是你被要求核查的内容。

paperconan sheets audit/scan.json          # every sheet read, signal or not

然后，自己判断哪个工作表包含该图。补充材料通常会把几百个工作表分散在十几个文件中，名称可能是 Fig. 2j、Fig2J、ED_Fig.7b、Source Data Fig 2、Supplementary Figure 8e，也可能按内容而非编号命名。没有哪条规则能可靠地将这些名称与图对应起来——阅读并判断是你的工作，这也是为什么该工具只列出它们而不进行匹配。

不同文件中的名称可能重复，因此也要查看文件列，而不只是工作表名称。

然后：

• 有一个工作表匹配，且它有信号——照常对其运行 drill。drill 接受 overview 的序号，因此，如果工作表的排名超出默认页数，就需要提高 overview --max-locations 的值，直到它出现；
• 有一个工作表匹配，但它没有信号——信号列只涵盖此层负责路由的类别。digit_distribution、decimal_endings、decimal_tail_clusters 和 image_findings 不在其中，列表会通过自己的 ! 行说明这一点，但不会指出每项对应哪个工作表。在判定该工作表没有问题之前，请先在 scan.json 中查看该工作表的这些键——信号列为空并不代表万事大吉，就像 image_findings 列表为空也不代表万事大吉一样。完成检查后，“数据已存在，且该位置没有检测器发现任何问题”是值得报告的答案，也比“无法获取来源”更好；
• 有多个工作表可能匹配——逐一检查。仅凭碰巧选中的那个工作表就得出“数据存在，未发现问题”的结论，比“无法获取”更像是言之凿凿的错误答案，也会让读者付出更多代价；
• 没有匹配的工作表——说明该图的数据不在已获取的内容中，并指出搜索了哪些文件。

列表还会报告它无法读取的内容：没有提供任何工作表的文件，以及超过大小上限的工作表（标记为 not read）。如果某张图的数据位于其中，就说明尚未核查，不能报告为没有问题。

未先运行 sheets，不得得出“无法获取源数据”的结论。 在本项目自己的基准测试中，16 条经裁定无法获取来源的主张，其所指的图实际上都位于已下载的工作表中——其中一条甚至位于一个包含 161 个工作表的文件里——而这些工作表中有 12 个如今检测到了发现。数据明明就在那里，只是没人把图和工作表对应起来。

如果确实缺少该工作表，paperconan fetch 可能会找到首次下载时漏掉的副本（参见“获取数据”）；此外，每个补充文件的发布方标签也有记录，可帮助你判断应该索取哪个文件。

自适应图像审查

当用户要求审查图像，或源目录中包含应与数值材料一并审查的图表时，使用此工作流：

1. 运行 paperconan <input-dir> --images；仅在确定性提示有用时添加 --image-diagnostics。
2. 阅读 image_assets 中的每个条目；确定性 image_findings 只是提示，并非完整的审查范围。image_findings 列表为空，并不意味着所有图像问题都已解决。确定性配对提示仅比较同一已登记资源中的两个区域，不比较不同资源。
3. 确认当前 Agent 能否打开本地图像。
   • 如果能，先检查整张图像，再使用原生像素裁剪查看小面板或尚未解决的细节。
   • 如果不能，将 image_review.status 设为 unavailable_no_multimodal，继续进行数值审查，并说明图像语义审查尚未完成。
4. 对每项资源，必须在 reviewed_asset_ids、unresolved_asset_ids、unreadable_asset_ids 或 deferred_asset_ids 中恰好记录一种覆盖结果。image_review.status: "completed" 表示覆盖情况的记录已完成；不表示每个图像问题都已得到解释。
5. 在升级图像相似性信号之前，检查图中标签、通道、处理步骤、共用对照、插图、前后布局、图例和 Methods。
6. 外部多模态 Agent 负责跨资源比较，即使 image_findings 为空，也可以使用 image_refs 创建图像发现。此类仅由 Agent 生成的图像发现应放在结论中，而不是确定性 scan.json 中。
7. 将数值发现和图像发现放入同一个 verdict.json findings[]，然后使用 paperconan report 生成一份统一报告。

PaperConan 提供已登记的本地资源、有范围限制的报告预览，以及可选的确定性提示。外部多模态 Agent 负责能力检测、语义审查、覆盖情况记录，以及谨慎的上下文解读。

审查模式

选择满足用户请求的最轻量模式：

• 单篇论文扫描：如有需要，获取/扫描论文；对于重要发现，查看源数据表；如有条件，检查标签/图例/Methods；然后给出简洁答复。仅在用户要求报告时，使用 references/report-templates.md。
• 单篇论文正式审查：扫描并核验源数据表后，加载 references/adjudication-tiers.md 和 references/report-templates.md。Tier 标签仅用于表示审查优先级/无辜解释的难度，绝不可用作对作者意图的结论。
• 批量审查：使用 references/batch-workflow.md。将确定性的 paperconan 输出与 Agent 判断分开。保留 DROP 原因，因为重复出现的误报有助于改进未来的过滤器。
• 对抗性审查：对于 Tier 1/Tier 2、PubPeer 草稿、面向公众的声明，或基于所谓误报而进行的过滤器更改，加载 references/adversarial-review.md，并在确认问题之前尝试反驳相关疑虑。

普通扫描摘要无需撰写完整的八节报告。仅在 Tier 1/Tier 2 KEEP、撰写 PubPeer 风格的草稿、正式的研究诚信说明，或用户明确要求时，才使用完整报告。

报告定位

工作流为 扫描 → Agent 分流/判断 → 审定报告。请区分以下两种报告产物：

• audit/report.html（由裸 CLI 生成）是确定性检测器／证据浏览器——一个分流工作清单。它按设计会包含大量误报，且不代表任何判断。这是一个中间产物，并非面向用户的交付内容。切勿将其称为“审计结果”。
• 面向用户的交付内容始终经过 Agent 审定：只有在分流 scan.json、针对严重发现打开源表格并权衡良性解释后才会生成。普通情况提供简短的审定摘要；对于 Tier 1/Tier 2 KEEP 以及正式／公开写作，则提供八部分报告（paperconan report scan.json --verdict verdict.json --out …）。

因此，原始 report.html 是你用来分流的内容；审定摘要或八部分报告才是用户收到的内容。只运行 paperconan <dir> 的纯 CLI 用户没有 Agent 参与，因此只能看到原始浏览器——请告知他们，在人工／Agent 分流之前，这些发现没有实际意义。

安装和运行

pip install paperconan
pip install "paperconan[image]" # image assets, PDF page rendering, optional hints
pip install "paperconan[all]"   # includes PDF / Word table extraction
paperconan --version
paperconan <input-dir>

如果系统因 externally-managed-environment 错误（PEP 668，例如 Homebrew 或 Debian Python）而拒绝 pip install，请安装到隔离环境中，而不是强制使用 --break-system-packages：

uv tool install "paperconan[all]"   # or: pipx install "paperconan[all]"
# or a plain virtualenv:
python3 -m venv ~/.venvs/paperconan && ~/.venvs/paperconan/bin/pip install "paperconan[all]"

默认输出：

<input-dir>/audit/scan.json
<input-dir>/audit/report.html

实用变体：

paperconan <input-dir> --out /tmp/audit-X
paperconan <input-dir> --md
paperconan <input-dir> --no-html
paperconan <input-dir> --profile forensic
paperconan <input-dir> --images
paperconan <input-dir> --images --image-diagnostics
paperconan report /tmp/audit-X/scan.json --verdict verdict.json --out adjudication.html

如果无法使用 Python 或访问软件包，请告知用户在本地运行该命令。只有作为非权威提示时，才可以提供人工审查；不得将其说成是 paperconan 的输出。

获取数据

只有当用户提供 DOI／标题而非本地文件时，才使用 fetch：

paperconan fetch "<DOI or title>"
paperconan fetch "<DOI or title>" --json
paperconan fetch "<DOI>" --download <id> --out data/
paperconan fetch "<DOI or title>" --auto --images --out data/
paperconan data/
paperconan data/ --images

优先选择 doi_in_related: true 的候选项。仓库搜索可能会返回无关的存档，因此请如实说明匹配结果较弱；不要暗示“未找到数据”就意味着“论文没有问题”。不要绕过付费墙或抓取出版商网站。

配置方案

--profile {review,forensic,triage} 会更改你在 scan.json 中看到的内容：

• review 是默认配置。它会保留可能的误报以供查看，但可能将其降为 low。
• forensic 会保留检测器的原始严重程度。在声称某个令人担忧的命中在原始检测器下仅为低严重程度之前，请使用此配置。
• triage 会隐藏可能的误报。

如果某项发现的 profile_action: "demoted" 或 profile_action: "hidden"，则活动配置更改了其显示的严重程度。请使用 prefilter_reason、prefilter_flags 和 false_positive_context 说明原因，然后判断该过滤理由是否确实符合表格上下文。

对于确定性图像提示，profile_action: "kept" 仅供参考。 图像提示不会经过数值预过滤，也不会被 review、forensic 或 triage 降级或隐藏。

参考资料路由

仅在需要时加载参考资料：

• references/output-schema.md：在解析 scan.json，或解释 profile_action、prefilter_reason、value_sample、col_a_sample 或 cross_sheet_findings 等字段前阅读。
• references/detectors.md：在解读检测器类型及其常见误报时阅读。
• references/judgment-rubric.md：在对发现排序、判断列内信号或撰写 PubPeer／研究诚信相关文字前阅读。
• references/interpretation.md：在撰写面向用户的最终答复，或处理指控、揭露或升级处理的请求时阅读。
• references/adjudication-tiers.md：在划分 Tier 1/2/3、KEEP、DROP、NEEDS_HUMAN 或 impact_scope 前阅读。
• references/report-templates.md：在撰写正式报告、PubPeer 草稿、研究诚信说明或批次判定 JSON 前阅读。
• references/adversarial-review.md：在确认 Tier 1/Tier 2、面向公众的问题或拟议的筛选器变更前阅读。
• references/batch-workflow.md：在审查多篇论文或整理候选队列时阅读。
• references/case-patterns.md：仅用于合成校准模式；不得将其视为真实案例先例。

判定原则

• 切勿将 severity 转化为关于作者意图的结论。severity 表示当前配置文件下异常的强度，而非作者意图。
• 切勿将 Tier 1/2/3 转化为关于作者意图的结论。Tier 表示后续跟进的优先级，以及审查上下文后无辜解释的难度。
• 优先检查跨工作表复用和跨列变换，再检查较弱的单列模式。
• 优先考虑良性的结构性解释：共享对照、重新绘图、单位换算、公式、索引、比率、归一化值、模型输出、检测下限和有界评分尺度。
• 默认将 within_col_* 发现视为误报风险较高。对于 n < 10、类别／索引标签、派生列、固定分母比率、取整网格、上下限或重复填充值，不要作出强烈报告。
• 如果无法确认行是否独立、是否为原始测量值、是否由公式生成、方法／图例的含义或原始表格的出处，请注明“需要人工核实上下文”。
• 撰写 PubPeer 风格的内容时，提供具体的文件／工作表／列证据并向作者提出问题；不要指控作者，也不要断言其意图。
• 除非用户明确要求准备特定的公开说明，且证据已根据源数据和论文上下文核实，否则不要使用真实论文作为公开校准示例。

输出格式

常规扫描摘要应包括：

1. 扫描了什么，以及是否有文件解析失败。
2. 经人工／字段级分流后优先级最高的发现，按文件分组。
3. 具体证据片段：检测器类型、位置、rule、n，以及适用时提供一小段值样本。
4. 合理的良性解释，以及需要哪些信息才能消除疑虑。
5. 指向 report.html，以查看表格中高亮的上下文。

对于批处理或 Agent 间工作流，可选的 verdict JSON 可使用： verdict、suspicion_tier、impact_scope、tier_why、drop_reason、 innocent_explanation、needs_author_data、report_md、review_status 和 finding_refs（用于指定该 verdict 判定了哪些扫描发现的选择器， 以便渲染后的报告将证据面板限定为这些发现）。当一篇论文有 多个不同的发现时，请使用包含 findings 数组的论文级对象（每个条目都单独判定其层级／状态，并附有自己的 finding_ref）；报告随后会为每项发现渲染一个独立完整的区块。 请参阅 references/adjudication-tiers.md 和 references/report-templates.md。

对于自适应图像审查，scan.json image_assets[] 是完整的已登记 资源清单，而 image_findings[] 仅包含可选的确定性提示。将 Agent 的结论作为 finding_type: "image" 条目添加，并附上 image_refs，同时补充顶层的 image_review 覆盖信息。数值和图像条目（包括仅由 Agent 得出的跨资源观察结果）都保留在同一个 findings[] 和统一报告中；不要创建单独的图像 verdict 或第二份面向用户的报告。

如果 verdict JSON 已存在，paperconan report <scan.json> --verdict <verdict.json> --out <html> 会渲染一份单独的判定报告。不要将其与默认的确定性 audit/report.html 混淆；判定报告的可靠性仅取决于其背后的人类／AI 判定和源上下文。

如果用户要求判断作者意图，请回答 paperconan 无法确定这一点。下一步应核实原始数据；如果疑虑仍然存在，可通过 PubPeer、期刊或研究诚信办公室请求澄清。