manuscript-provenance

手稿溯源审计

**流程位置：**第 2a 阶段（依据审计）。与 manuscript-typography 并行运行。依赖项：第 1 阶段修复后内容已定稿。生成宏清单，供 manuscript-review 第 13 轮（跨元素一致性）使用。

目的

验证手稿是否忠实呈现了计算输出。文档中的每个数字、表格、图、类别标签、排序和阈值，都必须能追溯到特定脚本、配置文件或流程输出。在手稿中手动录入数据属于可复现性缺陷。

此技能会生成一份溯源图谱——一份结构化报告，将每个手稿元素关联到生成它的代码，并标记链路中的所有断点。

配套技能：manuscript-review 将文档作为 prose 进行审查（结构、论证、引用）。此技能审查文档内容是否有计算依据。若要在出版前进行完整检查，请同时运行两者。

与 manuscript-review 的职责边界

关注点	manuscript-review	此技能（manuscript-provenance）
可复现性	论文是否提供了足够的信息以便复现？（§6）	代码是否确实生成了论文所声称的内容？（§1、§7）
图表	是否清晰、易读且格式良好？（§12）	是否由脚本生成，而非手动录入？（§2、§3）
渲染后的视觉元素	按印刷尺寸是否易读？是否靠近引用位置？（§23）	图表生成脚本是否输出了正确格式？（§3）
超参数	论文中是否列出并说明理由？（§6）	值是否可追溯至配置文件，而非硬编码？（§1、§8）
代码可用性	论文中是否有相关声明？（§17）	仓库 URL 是否有效、README 是否准确、流程是否可运行？（§11）
术语	文档中的缩写是否一致？（§14）	术语是否与代码标识符一致？（§5）
有效数字	文档中的精度是否一致？（§12）	精度是否与脚本输出一致？（§2）
图表格式	格式是否符合文档质量要求？（§12）	格式是否由脚本生成，而非手动导出？（§3）
计算成本	论文中是否报告？（§7）	数值是否可追溯至基准测试脚本？（§1）
宏与正文的一致性	正文的表述是否适合插入的值？（§24）	值是否可追溯至代码，是否生成了宏清单？（§4）
跨元素一致性	正文、图注、图和表是否相互一致？（§24）	所有元素是否来自同一次运行／流程输出？（§9）

**规则：**此技能绝不评判 prose 质量。manuscript-review 绝不打开代码库。只要有对方的报告，双方都会读取。

集成点——宏清单：此技能会在 §4 审计中生成一份宏清单，列出每个通过宏注入的值，并包含：

• 宏名称（例如，\bestf）
• 解析后的值（例如，0.847）
• 来源（生成该值的脚本和输出文件）
• 在手稿正文中的位置（文件、行号及其所在句子）
• 分类（TRACED / MACRO-TRACED / CONFIG-TRACED / UNTRACED / STALE）

manuscript-review 第 13 轮（跨元素一致性，§24）会使用此清单，检查每个注入值周围的正文是否适合实际数值。溯源审计负责确认“该值是否有计算依据？”，审查则负责确认“围绕该值的文字是否合理？”

范围

范围内：

• 手稿文本中的数字、指标和百分比
• 表格（内容、顺序、格式）
• 图（生成脚本、数据来源）
• LaTeX 宏（\newcommand、\def、\pgfmathsetmacro）
• 术语、模式名称、机制标签、类别名称
• 枚举项、表格和讨论内容的顺序
• 配置值（阈值、超参数、模型名称）
• 流水线完整性（原始数据 → 最终 PDF）
• 时间戳一致性（脚本与输出）

范围外：

• 文本质量（→ manuscript-review）
• 引用规范性（→ manuscript-review）
• 论证结构（→ manuscript-review）
• 代码质量／风格（单独关注）

输入

此审计需要两项材料：

1. 手稿源文件 — LaTeX .tex 文件（首选），或作为备选的 PDF/DOCX
2. 代码库 — 生成手稿内容的脚本、配置和流水线

如果用户只提供其中一项，请索要另一项。强烈建议优先提供 LaTeX 源文件，而不是编译后的 PDF——审计来源需要查看原始标记、宏和输入命令。

工作流

第 1 阶段 — 清点

1a. 提取手稿材料

读取所有 .tex 文件（主文件及通过 \input/\include 引入的文件）。提取：

• 行内数值：正文中的裸数字（百分比、计数、指标、p 值、置信区间、阈值、大小）
• LaTeX 宏：所有承载数据值的 \newcommand、\def、\pgfmathsetmacro 和自定义命令定义
• 表格：每个 tabular/table 环境的完整内容——单元格值、行列顺序、表头
• 图：\includegraphics 路径、图注内容、引用的数据
• 输入文件：任何通过 \input{generated/*.tex} 模式引入脚本生成的 LaTeX 片段
• 标签和引用：用于交叉引用的 \label/\ref 配对
• 术语：正文中使用的命名模式、机制、策略、类别和方法名称
• 有序列表：任何枚举或排序项（比较的方法、列出的特性、排序的结果）

建立材料清单——列出手稿中每个承载数据的元素，并注明其位置（文件、行号）。

1b. 代码库映射

扫描项目目录。识别：

• 流水线入口：Makefile、snakemake、dvc.yaml、run.sh、main.py 或同类编排文件
• 分析脚本：生成数字、表格和图的文件
• 配置文件：config.toml、config.yaml、.env、params.yaml、超参数文件
• 输出目录：脚本写入结果的位置（results/、output/、figures/、tables/、generated/）
• 生成的 LaTeX 片段：输出目录中由脚本生成、供 \input 引入的 .tex 文件
• 数据文件：CSV、JSON、HDF5、pickle 等中间结果流经的文件

建立来源清单——列出每个生成或配置手稿内容的代码材料。

阶段 2 — 溯源追踪

尝试为工件注册表中的每个条目建立一条溯源链：手稿中的值 → 生成的输出 → 脚本 → 输入数据/配置。

2a. 数值溯源

对于手稿中的每个数字：

1. 在脚本输出（日志、结果文件、生成的 LaTeX）中搜索该值
2. 将输出追溯到生成它的脚本
3. 验证脚本读取的是数据/配置（而非硬编码）
4. 记录完整链路，或标记为未追溯

分类：

• 已追溯 — 从手稿中的值到生成代码的完整链路
• 宏追溯 — 值定义在 LaTeX 宏中，且该宏由脚本生成
• 配置追溯 — 值来自脚本读取的配置文件
• 未追溯 — 未找到溯源链；手动输入
• 过期 — 溯源链存在，但输出比生成脚本更旧

2b. 表格溯源

对于每个表格：

1. 表格内容是否由脚本生成（CSV → LaTeX，或直接生成 LaTeX）？
2. 行/列顺序由代码决定（按指标排序、按字母顺序排列、按类别分组），还是手动排列？
3. 表头标签是否与代码定义的名称一致？
4. 格式选择（最佳项加粗、有效数字）是否由代码应用？

分类：

• 已生成 — 整个表格由脚本生成
• 部分生成 — 部分单元格由脚本生成，部分为手动填写
• 手动编排 — 未找到生成脚本
• 顺序手动设定 — 内容由脚本生成，但顺序为手动设定

2c. 图表溯源

对于每张图：

1. 是否有脚本生成 \includegraphics 引用的确切文件？
2. 脚本是否使用确定性种子以保证可复现性？
3. 脚本中的图表输出路径是否与 LaTeX 引用一致？
4. 图表参数（颜色、标签、坐标轴范围）是在代码中设置，还是在生成后手动编辑？

分类：

• 已生成 — 脚本生成确切文件
• 后期编辑 — 脚本生成基础图表，但检测到手动编辑 （例如，Illustrator 元数据、校验和与脚本输出不同）
• 手动绘制 — 未找到生成脚本
• 过期 — 生成脚本的修改时间晚于图表文件

2d. 术语溯源

对于每个命名模式、机制、类别或方法标签：

1. 术语是否在代码中定义（枚举、常量、配置键、类名）？
2. 手稿中的术语是否与代码术语完全一致？
3. 如果手稿使用了适合展示的名称，代码或配置中是否有显式映射？

分类：

• 代码定义 — 术语与代码定义一致
• 已映射 — 存在显式的代码→展示名称映射
• 未映射 — 术语出现在手稿中，但未出现在代码中
• 不一致 — 术语同时出现在两者中，但有所不同（例如，代码写作 greedy_search，手稿中有些地方写作“Greedy Search”，而另一些地方 写作“greedy approach”）

2e. 顺序溯源

对于每个有序列表、排名比较或顺序枚举：

1. 顺序是否由代码决定（按指标排序、按字母顺序排列、按枚举顺序排列）？
2. 手稿中的顺序是否与代码决定的顺序一致？
3. 手稿列表中是否有代码输出中不存在的项目，或反之？

分类：

• 代码排序 — 顺序与代码输出一致
• 手动排序 — 顺序与代码输出不同，或代码中没有排序逻辑
• 子集不匹配 — 手稿列出的项目与代码生成的项目不同

第 3 阶段 — 基础设施审计

3a. LaTeX 宏规范

• 每个承载数据的宏都应由脚本生成，而非在导言区手动输入
• 检测模式：在 .tex 文件中直接定义 \newcommand{\someMetric}{42.7}（错误），而非使用 \input{generated/metrics.tex}，其中该文件由脚本生成（正确）
• 标记其值未出现在任何脚本输出中的宏
• 标记在主 .tex 文件中定义且承载数值／数据的宏

3b. 流水线完整性

• 是否有一条命令能从原始数据重现所有稿件产物？
• 是否记录了流水线（Makefile、README、CI 配置）？
• 中间步骤是否有缓存，还是每次都需要完整重新执行？
• 是否固定了随机种子以确保可复现？
• 是否固定了软件版本（requirements.txt、environment.yml、锁定文件）？

3c. 配置与代码分离

• 超参数、阈值和模型名称是否位于配置文件中？
• 文件路径是相对路径（可移植）还是绝对路径（脆弱）？
• 已提交的代码中是否没有凭据、API 密钥或特定机器的路径？
• 是否有统一的配置入口，还是设置散落在各个脚本中？

3d. 过时输出检测

• 比较修改时间戳：脚本与其输出文件
• 标记比生成脚本更旧的输出（过时）
• 标记没有对应脚本的输出（孤立文件）
• 标记没有对应输出的脚本（死代码或未运行的代码）

3e. 版本固定

• 是否锁定了依赖项（含版本号的 requirements.txt、conda environment.yml、 poetry.lock、package-lock.json）？
• 是否跟踪了数据版本（DVC、git-lfs、数据校验和）？
• 稿件是否与代码一同进行版本管理（位于同一仓库，并有带标签的发布版本）？

第 4 阶段 — 交叉引用与清单生成

4a. 宏清单生成

生成宏清单——交付给 manuscript-review 的主要交接产物。 对于在第 1a 阶段识别并在第 2a 阶段追踪的每个承载数据的宏：

Macro: \bestf
Value: 0.847
Source: results/metrics.json → scripts/generate_latex_macros.py → generated/metrics.tex
Locations:
  - paper.tex:142 — "achieving an F1 score of \bestf{}"
  - paper.tex:287 — "The \bestf{} result represents a substantial improvement"
  - abstract.tex:8 — "...with \bestf{} F1 score"
Classification: MACRO-TRACED

还要包括在第 1a 阶段发现的所有承载数据的裸数字（非宏），例如指标、计数、参数——这些值本应写成宏，却没有这样做：

Bare value: 50
Location: paper.tex:198 — "convergence after 50 epochs"
Should-be-macro: YES — this is a training parameter, should trace to config
Classification: UNTRACED (no macro, no provenance)

将清单保存为 [manuscript-name]-macro-manifest.json，与溯源报告放在一起。manuscript-review Pass 13 （跨元素一致性）会使用此文件来验证文字描述与数值是否恰当。

4b. 与 manuscript-review 交叉引用

如果存在这篇稿件的 manuscript-review 报告，请加载该报告并执行以下操作：

• 将 UNTRACED 值映射到 manuscript-review §6（方法）和 §7（结果）的 发现——溯源缺口往往与可复现性问题同时出现
• 将术语不一致标记为 manuscript-review 框架中可能涉及 §14（缩写）或 §15 （符号）的问题
• 将高优先级的溯源问题作为 §6／§7 的失败项
• 将宏清单纳入 manuscript-review §24（跨元素一致性）的 发现——如果数值周围的文字使用了不恰当的定性描述（例如将 14.3% 称为“微不足道”，将 0.3% 称为“显著”），则属于 §24 失败项

如果不存在 manuscript-review 报告，建议将其作为配套审计运行，并注明宏清单可供其 Pass 13 使用。

第 5 阶段 — 报告生成

加载 references/checklist.md 和 references/report-template.md。

Read references/checklist.md
Read references/report-template.md

按照模板结构生成溯源报告：

1. 溯源摘要 — 总体评分、各类别细分
2. 溯源映射 — 每个稿件产物及其来源
3. 缺陷登记表 — 每项 UNTRACED、STALE、MANUAL、INCONSISTENT 发现
4. 基础设施评估 — 流水线、配置和版本管理状态
5. 修复队列 — 按优先级排列的修复项
6. 检查清单状态 — 完整检查清单，以及每个检查点的通过／失败状态

阶段 6 — 输出

在稿件目录中保存两个文件：

1. [manuscript-name]-provenance-report.md — 完整的溯源报告
2. [manuscript-name]-macro-manifest.json — 结构化宏清单，供 manuscript-review Pass 13 使用

宏清单 JSON 结构：

{
  "macros": [
    {
      "name": "\\bestf",
      "value": "0.847",
      "source_chain": "results/metrics.json → scripts/gen_macros.py → generated/metrics.tex",
      "locations": [
        {
          "file": "paper.tex",
          "line": 142,
          "context": "achieving an F1 score of \\bestf{}"
        },
        {
          "file": "paper.tex",
          "line": 287,
          "context": "The \\bestf{} result represents a substantial improvement"
        }
      ],
      "classification": "MACRO-TRACED"
    }
  ],
  "bare_numbers": [
    {
      "value": "50",
      "location": {
        "file": "paper.tex",
        "line": 198,
        "context": "convergence after 50 epochs"
      },
      "section": "methodology",
      "should_be_macro": true,
      "rationale": "Training parameter — should trace to config",
      "classification": "UNTRACED"
    }
  ]
}

向用户展示：

• 溯源覆盖率百分比（TRACED / 工件总数）
• 按严重程度统计的 UNTRACED / STALE / MANUAL 发现数量
• 应改用宏的裸数字数量
• 前 5 项整改措施
• 流水线完整性判定
• 说明宏清单可供 manuscript-review Pass 13 使用

严重程度分类

• CRITICAL — 稿件中的值没有溯源链，且属于关键结果（主要发现、摘要指标、表格中的醒目数字）。这意味着无法通过代码验证论文的核心主张。

• HIGH — 值／表格／图表未溯源或已过时，且出现在结果或方法部分。存在可复现性缺口。

• MEDIUM — 术语不匹配、手动排序、表格仅部分生成、脚本中硬编码配置值。存在维护和一致性风险。

• LOW — 次要问题：缺少显示名称映射，但术语相近；非关键图表没有生成脚本；对生成的图表进行外观层面的后期编辑。

核心原则

• 二元溯源。 每个工件要么已溯源，要么未溯源。不存在“部分可复现”——部分可复现意味着流程有问题。

• 代码为准。 当稿件与代码不一致时，除非有证据证明相反，否则应视稿件有误。标出不一致之处；不要假设稿件作者“本意是”覆盖代码输出。

• 用宏取代魔法数字。 LaTeX 中的每个数据值都应是宏。每个宏都应由程序生成。所谓“显而易见”的值也不例外。

• 流水线即证明。 如果 make（或等效工具）无法从原始数据生成 PDF，则稿件不可复现。流水线不完整只能获得部分认可，不能通过审核。

• 配置不是代码。 超参数、阈值、模型名称、文件路径等都应放在配置文件中，而不是散落在脚本正文里。

• 排序也是数据。 表格或枚举中的项目顺序是一种断言。它必须来自代码（排序顺序、枚举定义），而不是作者觉得“看起来合适”。

• 时间戳很重要。 如果图表是上个月用一个昨天才修改的脚本生成的，就值得怀疑。过时的输出属于溯源失败。

• 配套而非替代。 此审计检查计算依据；manuscript-review 检查文档质量。两者缺一不可，互不替代。

示例调用方式

用户说出以下任一内容时：

• “检查溯源”
• “我的数字来自代码吗”
• “审计我的流水线”
• “验证可复现性”
• “将稿件与脚本对照检查”
• “溯源审计”
• “我的表格是自动生成的吗”
• “我的图表来自脚本吗”
• “/manuscript-provenance”

以上内容均会触发此技能。