Research Repo Doctor

Research Repo Doctor

在截止日期前，为 Artifact Evaluation 做好研究工件准备： 扫描仓库，为简单修复搭建脚手架，验证运行路径，并生成附录。

公开仓库的 Web 演示：https://research-repo-doctor-bckncrcwwmg6jrbsrd6btj.streamlit.app/ 如果托管演示正在启动或重新安装依赖，下面的本地零安装 命令是可靠的备用方案：

uvx rrdoctor scan .

维护者可以使用 python scripts/check_live_demo.py https://research-repo-doctor-bckncrcwwmg6jrbsrd6btj.streamlit.app/ 检查匿名演示访问权限。

rrdoctor 是用于准备研究工件的本地 CLI 和 GitHub Action。它会审查仓库是否便于评审、可供引用且接近可运行；为安全的机械性修复搭建脚手架；将发现映射到 AE 风格的就绪级别；并将其余事项整理成清单，供任何编码 Agent 或人工完成。

将其设为拉取请求门禁

GitHub Action 是主要的采用方式：准备工件时运行 CLI，然后在每个拉取请求上继续执行相同的确定性预检。

name: Reproducibility preflight

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  rrdoctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: Tom409114/[email protected]
        with:
          profile: standard
          fail-on: error

完整的 GitHub Action 指南涵盖固定式 PR 评论、新发现基线、Agent 计划、附录以及完整的 AE 准备包。

AE 截止期限工作流

uvx rrdoctor prepare . --profile acm --out-dir rrdoctor-prep

# Or run the pieces explicitly:
uvx rrdoctor scan . --profile acm
uvx rrdoctor fix . --write
uvx rrdoctor appendix . --profile acm --output ARTIFACT_APPENDIX.md
uvx rrdoctor verify . --profile acm
uvx rrdoctor verify . --profile acm --run --timeout 600 --fail-on error  # trusted repos only
# Or pin the official quickstart command as the dynamic gate:
uvx rrdoctor verify . --profile acm --command "python train.py config/default.py" --run --timeout 600 --fail-on error

对于可信仓库，rrdoctor verify --run 可以执行超出静态检查范围的验证。对于受支持的 Python 仓库，它会创建临时隔离环境，安装已声明的依赖，并在超时限制内运行已声明的入口点。其他生态系统则保留显式的解析器预检。使用默认门禁（--fail-on error）时，失败或受阻的动态 L2/L3 步骤会返回非零退出代码。如果工件有评审者应运行的特定冒烟测试或快速入门命令，请使用 --command。动态模式可能会运行依赖项的构建/安装钩子以及入口点，因此切勿将其用于不可信代码。rrdoctor prepare 会将报告、Agent 计划、工件附录和验证阶梯写入同一个本地证据目录。

Artifact Evaluation 主席和实验室维护者可以参阅 AE 主席指南，了解可选的提交前措辞和 CI 示例。

公开校准证据请参阅 80 个仓库的数据简报和 nanoGPT 首次运行回归案例研究。

可检测的问题

• “你的 --seed 标志不起作用。” RRD052 会发现声明了种子选项，却从未调用 random.seed、np.random.seed、torch.manual_seed、tf.random.set_seed 或 random_state=seed 的代码。
• “这在我的笔记本电脑上能运行。” 仅限本地的数据路径、缺失的数据来源信息以及未记录的数据获取步骤。
• “环境悄无声息地发生了变化。” 未锁定版本的依赖、缺失的运行时版本、未声明的导入以及缺失的依赖清单。
• “笔记本有误导性。” 过时的输出、顺序不正确的执行、检查点工件以及类似机密信息的笔记本输出。
• “评审者无法判断如何引用或重新运行它。” 缺失许可证、引用信息、CI、测试、变更日志、结果来源信息或实验入口点。

安装

运行一次，无需安装：

uvx rrdoctor scan .

其他方式：

pipx run rrdoctor scan .
pip install rrdoctor
rrdoctor scan .

从源代码进行开发者安装：

git clone https://github.com/Tom409114/research-repo-doctor.git
cd research-repo-doctor
python -m pip install -e ".[dev]"
rrdoctor scan .

修复简单的缺漏

让 rrdoctor 为你创建安全的脚手架。它具有确定性、幂等性， 且绝不会覆盖现有文件。

rrdoctor fix . --write

它可以为缺失的治理文档、引用元数据、数据／结果溯源说明、 可复现种子辅助工具、变更日志条目以及常见的研究 .gitignore 条目搭建脚手架。 棘手部分会变成可供审查的计划：

rrdoctor plan . --output plan.md

与编码 Agent 配合使用

将以下内容粘贴到 Claude Code、Cursor、GitHub Copilot 或其他编码 Agent 中：

Use rrdoctor as the deterministic, offline, no-API-key grader for this research repo.

Run:
rrdoctor scan . --format json --output baseline.json
rrdoctor plan . --output plan.md

Work through plan.md without weakening rrdoctor checks.

Definition of done:
rrdoctor scan . --baseline baseline.json --fail-on-new error

最后一条命令是目标门槛：它会根据起始基线验证 Agent 的工作，并且仅在出现新引入的错误时失败。

可在 integrations/ 获取可复制的 Agent 模板，适用于 Agent Skills / Claude Code 风格的工作流，以及 Cursor 项目规则。

关键词：研究软件、可复现性、制品评估、仓库审计、自动修复、编码 Agent、AGENTS.md、GitHub Action、笔记本、数据可用性、引用元数据。

帮助校准规则

改进 rrdoctor 最快的方式，是收集真实研究仓库的实际扫描反馈。扫描一次后，这份低门槛的 10 分钟试用报告 只会询问哪些内容有用、错误或缺失，以及该工具是否适合真实的截止期限。如需报告特定规则的问题，请创建 误报、 漏报、 扫描案例 或新规则 问题。请提供规则 ID、命令、rrdoctor 版本以及经过脱敏的最小仓库结构。请参阅反馈与校准中的简短检查清单。

为什么这很重要

研究代码常常在截止期限的压力下上传到 GitHub。审稿人或未来的实验室成员发现了一个颇有前景的仓库，却可能因为环境说明不充分、数据路径是本地路径、笔记本包含过时的输出、依赖未锁定版本，或引用信息不明确而浪费数小时。

Research Repo Doctor 将这些反复出现的发布障碍转化为确定性检查，并提供具体的整改建议；在安全可行的情况下，还会搭建机械性工作的起始脚手架。它旨在融入日常维护流程：准备发布时在本地运行，随后通过 GitHub Actions 在拉取请求上自动运行。

审计无需 AI API 密钥、网络访问或托管服务即可运行。同样的确定性也让它成为公正的评估工具：它可以验证由人员或编码 Agent 完成的修复。

audit -> fix -> plan -> (your coding agent / you) -> verify -> PR
  |       |       |                                  |
  |       |       rrdoctor plan                      rrdoctor scan --baseline
  |       rrdoctor fix --write                       --fail-on-new error
  rrdoctor scan

0.2.24 版新增内容

• 更全面地覆盖系统制品：现有检查现在可识别 Cargo、 CMake、Meson、容器和 Nix 相关证据，以及入口点、测试、CI 和发布工作流中的 文档化制品脚本与 Cargo 命令。
• 更安静的静态扫描：抑制目标源码中的 SyntaxWarning 噪声， 并避免转义后的 Python 异常文本被误判为本地 Windows 路径。
• 重新核验首次运行时的可信度：公开 PyPI 上的 rrdoctor==0.2.23 仍将 nanoGPT 评为 Functional，得分为 76/100，错误数为 0；此前的 RRD050 和 RRD063 噪声发现仍未出现。
• 明确的 JOSS 边界：论文草稿说明现已将公开历史超过 6 个月这一门槛，与维护者必须提供的研究用途、作者身份、利益冲突和 AI 披露证据区分开来。
• 真正管控扫描的配置文件：CLI 和 MCP 调用会从任意工作目录加载目标仓库的 .rrdoctor.yml； 配置文件中的配置档、报告、阈值、失败设置、包含／排除项和规则设置现在均可生效，但显式 CLI 覆盖项除外。

0.2.23 版更新内容

• 更安全的发布路径：在新版本传播期间，托管演示可以固定使用最新发布的 PyPI 软件包，避免 Trusted Publishing 期间 Streamlit 部署出现故障。
• 一流的 GitHub Action 路径：精简的拉取请求工作流现在显示在 README 顶部附近，并由公开就绪性测试提供保障。
• 更短的反馈周期：完成网页演示扫描后，会链接到一份结构化的 10 分钟试用报告，用于记录有价值的发现、误报、漏报以及实际截止日期的适配情况。
• 通过 Official MCP Registry 分发：v0.2.24 已作为 io.github.Tom409114/rrdoctor 发布，MCP 支持仍是可选附加项，而非核心扫描器依赖。列入 Registry 属于分发元数据，不代表认可或采用证明。
• 更强的动态验证覆盖：一项离线集成测试证明，L3 可以在其临时 Python 环境中安装并导入已声明的本地 wheel。

0.2.22 版更新内容

• 真实的 Python 环境验证：rrdoctor verify --run 现在会创建临时隔离的 venv，安装仓库声明的依赖，并使用该解释器和 PATH 运行 L3，而不再止步于解析器试运行。
• 如实说明执行边界：验证报告会披露依赖构建钩子的风险、隐藏机器特定的临时路径，并在运行后移除临时环境。其他生态系统仍会明确执行解析器预检。
• 更严格的隔离检查：会移除继承的 PYTHONHOME 和 PYTHONPATH 值，并将 python3.10 等带版本号的启动器重定向到临时环境。

0.2.21 版更新内容

• 更如实地呈现语料库证据：公开的 80 个仓库校准语料库现在包含 80 份有针对性的审查说明，待定向审查的仓库数为 0，并附有简明的数据简报，解释语料库能证明什么、不能证明什么。
• 降低模型发布扫描的噪声：RRD050 和 verify 现在会识别常见的模型发布入口点，例如根目录、scripts/ 和 tools/ 布局中的 demo.py、inference.py、predict.py、sample.py 和 generate.py。
• 降低密钥检查的噪声：RRD063 和 RRD090 现在会要求通用 api_key/token/secret/password 赋值具有更强的熵证据，同时仍会标记符合服务提供商特征的密钥。
• 更多 Agent 集成：仓库现已包含可直接复制的 GitHub Copilot 指令，以及现有的 Agent Skill 和 Cursor 模板，用于执行 baseline -> plan -> verify 流程。
• 更清晰的发布材料：JOSS 草稿现在更明确地说明评估证据及其局限性；实时演示检查现在会先遵循 Streamlit 的匿名重定向握手，再判断应用是否可访问。

0.2.20 版本更新

• 降低成熟科学软件包扫描的噪声：RRD010 现在可识别 LICENSE.txt 等常见许可证文件名，RRD043 会忽略 CI／devcontainer 路径、测试／fixture、URL 路径段，以及文档中说明的占位符／示例绝对路径。
• 降低库和密钥启发式检测的噪声：RRD050 不再将成熟的软件包／库项目（包括常见的嵌套 package/ 布局）误判为缺少论文实验入口；RRD090 会忽略 URL 查询参数中的令牌、本地函数调用或方法调用的令牌变量、测试辅助代码中的通用假令牌，以及嵌入较长生物学／测试序列中的类似服务商名称的子串。
• 增加经过审查的语料库证据：SciPy 是重点审查案例，也是针对 RRD010 和 RRD043 的预期缺失回归关卡；scikit-image、JAX、NetworkX、Keras、Transformers、PyTorch Lightning、Biopython、torchvision、MDAnalysis、QuTiP、ESM、stable-diffusion、detectron2、DINO、StyleGAN2-ADA PyTorch、instant-ngp、Big Vision、latent-diffusion、taming-transformers、generative-models、pytorch-image-models、Brax、ArviZ、PyMC、Pyro、TensorFlow Probability、statsmodels、Optax 以及其余语料库条目，现在都会新增首次运行信任关卡或重点审查证据。最新的 80 个仓库语料库关卡有 0 个预期缺失回归、80 条已审查记录，且没有仍待重点审查的仓库。
• 自动修复输出更少模板化：生成引用和来源信息框架时，rrdoctor fix --write 现在可以静态读取简单的字面量 setup.py 元数据，而无需执行仓库代码。
• 补全更多 Artifact Appendix 访问信息：对于旧式 setup.py／setup.cfg 项目，rrdoctor appendix 会复用相同的本地元数据推断，预填仓库 URL 和版本。
• L2 环境检查更贴近实际：rrdoctor verify --run 现在会解析常见的嵌套 Python 依赖文件（如 requirements/base.txt 和 requirements/main.txt），以及 .yaml Conda 环境文件，不再跳过这些仓库布局。
• 降低 Notebook 密钥检查的噪声：RRD063 现在也会使用 RRD090 的测试／fixture 通用假令牌抑制机制，同时仍会标记独立出现的服务商风格密钥。

0.2.19 版本更新

• 降低实验入口检测的噪声：RRD050 现在可识别软件包级研究二进制文件（如 t5x/train.py）、文档中说明的 python3 ${T5X_DIR}/t5x/train.py 命令，以及带有明确命名的演示／示例／复现 Notebook（如 graphcast_demo.ipynb）的 Notebook 优先型工件。
• 增加更多首次运行语料库证据：重点审查记录现在涵盖 60 个种子语料库仓库中的 32 个。最新的 60 个仓库静态语料库扫描有 0 个预期缺失回归，并将 t5x 和 GraphCast 保留为入口回归关卡。

0.2.18 版本更新

• 降低依赖检查的噪声：RRD034 现在会解析 Python AST 导入，而不是用正则表达式匹配源文本，因此注释、文档字符串和说明性示例不会被误认为缺少软件包。
• 以运行时为重点的依赖信号：在报告依赖缺口之前，会先过滤文档、测试、基准测试、供应商代码、维护者工具、conftest.py、构建系统依赖项和本地同级模块。
• 增加更多语料库审查证据：重点审查记录现在涵盖 60 个种子语料库仓库中的 30 个，其中包括对 scikit-learn、Astropy、scvi-tools 和 DINOv2 的依赖信号噪声检查。
• 当前安装路径：PyPI、GitHub Action 示例、演示依赖项、引用元数据和自扫描报告均与此版本保持一致。

0.2.15 版本更新

• 验证证据更清晰：rrdoctor verify 报告现在会优先显示门禁结果、失败阈值、超时时间、信任边界、重新运行命令，以及任何 L3 动态命令的来源。
• Artifact Appendix 框架更完善：rrdoctor appendix 现在会在可用时预先填入本地 README/项目元数据、依赖清单、数据/结果文档、配置文件和检测到的入口命令。
• 生成的数据说明更实用：生成 DATA.md 框架时，rrdoctor fix --write 会沿用候选数据集 URL、DOI、README 中的数据命令和本地数据脚本。
• 维护者发布门禁：python scripts/check.py 和 python scripts/check_public_readiness.py 提供跨平台本地检查，用于评估发布、JOSS、Artifact Evaluation 和公众推广的准备情况。

0.2.14 版本更新

• 一键生成 AE 证据包：rrdoctor prepare 会将静态报告、Agent 修复计划、Artifact Appendix 和验证阶梯写入同一个本地目录，方便在截止日期前交接。
• 通过 CI 上传 AE 证据包：GitHub Action 现在支持 prepare: "true" 和 prepare-output，因此拉取请求和发布门禁可以上传同一份方便评审的证据包。
• 固定运行路径验证：verify --command "..."、Action 的 verify-command 输入和 MCP verify 工具允许维护者将官方快速入门命令和超时时间固定为 L3 门禁。
• 减少首次运行时的噪声：现在会更谨慎地处理 MAE 风格的根目录 main_*.py 脚本、AlphaFold 风格的 random_seed= 传递、测试文件中的随机性，以及占位绝对路径。

0.2.13 版本更新

• 扫描报告现在会引导至 AE 工作流：Markdown 报告和 Agent 修复计划现在包含后续步骤命令，用于运行 rrdoctor plan、rrdoctor appendix、静态 rrdoctor verify 和仅对可信代码运行的动态 verify --run。
• 自动修复框架更完善：生成的 AGENTS.md 文件现在包含扫描 -> 计划 -> 基线验证循环；生成的结果溯源说明则包含本地仓库上下文、当前结果文件和结构化结果清单表。
• 采用指南更实用：公开文档现在包含反馈/校准流程，以及 Artifact Evaluation 主席指南，其中提供可选的提交前措辞和 CI 示例。

0.2.12 版本更新

• 可信动态 Action 门禁：GitHub Action 用户现在可以设置 verify-run: "true" 和 verify-fail-on: error，使可信动态验证阻止 CI，同时仍上传验证报告。
• Agent 分发模板：仓库 Copilot 指令、Agent Skill 模板和 Cursor 项目规则，让确定性的扫描 -> 计划 -> 验证循环可以在编码 Agent 工作流中复制使用。
• 证据措辞更严谨：语料库和 JOSS 草稿的措辞现在会区分重点审查说明与完整的人工仓库审计。

0.2.11 版本更新

• 首次运行信任调优：README 安装/运行命令、设定种子的本地 RNG、PyTorch 参数初始化、类似 UUID 的标识符以及经典 ML 仓库现在产生的误报更少。
• 真正的动态门禁：当依赖解析或检测到的运行路径失败或受阻时，rrdoctor verify --run --fail-on error 现在会以非零状态退出。
• 更多校准证据：现在已提交 22 条重点审查说明，其中包括 BERT、CLIP、improved-diffusion、MAE 和 AlphaFold 的后续审查，以及针对已修复的噪声发现项的预期缺失检查。

0.2.10 版本更新

• 语料校准更可靠：公开评估语料运行器现在会在 git clone 超时时回退到 GitHub 存档，减少首次运行的信任检查对不稳定传输的依赖。
• 维护者自动化更完善：一方工作流和文档示例现在使用与 Node 24 兼容的最新 GitHub Actions 版本。
• 诊断更精准：只有在软件包及导入时依赖项确实能加载时，rrdoctor doctor 才会报告可选 MCP 集成的可用性。

0.2.9 版本更新

• 首次运行时的 CLI 行为更清晰：rrdoctor --version 现在会报告已安装的软件包版本，直接运行 rrdoctor 也能成功显示根帮助页面。

0.2.8 版本更新

• 更准确地识别 README 中记录的运行路径：README 中记录的 python -m package.train ... 命令现在会在映射到本地仓库模块时，被视为实验入口点。
• 增强对 ML 启动器的动态验证：当 python -m torch.distributed.run train.py ... 等模块运行器命令包含本地 Python 入口点时，rrdoctor verify 现在可以识别它们。

0.2.7 版本更新

• 更完善的引用信息模板：生成 CITATION.cff 时，rrdoctor fix --write 现在会读取结构化 PEP 621 和 Poetry 元数据、保留多位作者、规范化 SSH git 远程地址，并处理 git worktree 的 origin URL。
• 减少噪声的依赖项检查：RRD034 现在能理解 PEP 621 环境标记和 Poetry 依赖组，从而减少未声明导入的误报。

0.2.6 版本更新

• 减少噪声的密钥检查：Rcpp Generator token 标记和公开的 pkgdown docsearch.api_key 搜索配置不再触发 RRD090，但类似凭据的通用 API 密钥仍会触发。
• 语料扫描更可靠：评估运行器现在会在 git clone 传输不稳定时回退到 GitHub 存档下载，且不会安装或执行目标仓库。
• 更多人工校准证据：当前公开语料快照涵盖 60/60 次成功的静态扫描、该快照中载入的 22 条专项审查备注，以及 0 项预期缺失回归。

0.2.5 版本更新

• 模型发布入口点：README 中记录的 python scripts/*.py / python tools/*.py 命令以及 pyproject 中声明的 CLI 命令，现在都会被视为实验入口点，从而减少在 Segment Anything 和 Whisper 等仓库中的首次运行误报。
• ML 工具入口点：常见的 tools/train.py、tools/test.py 及相关 ML 框架命令，现在会计入 RRD050。
• 种子辅助函数模板：rrdoctor fix --write 可以为 RRD052 生成可复现的 set_global_seed(seed) 辅助函数模板，而不会覆盖项目代码。
• 语料回归门槛：入口点修复由专项审查备注和公开评估语料中的 expected_absent 检查提供支持。

0.2.4 版本更新

• 改善首次运行时的信任度：根目录下的 train.py/main.py/run.py、Snakemake/Nextflow 工作流以及 README 运行命令现在都会被视为实验入口点。
• 减少噪声的安全检查：笔记本和仓库密钥检测现在只有在发现高度可信的类凭据值时，才会报告阻断性错误。
• 更贴近实际的 README 检查：具体的训练、评估、基准测试、工作流或复现命令，现在会被视为可复现结果的证据。
• 由语料支持的规则校准：公开评估语料会跟踪误报和漏报审查备注、预期缺失的回归门槛，以及规则频率汇总。
• 发布规范：引用指南检测可以识别 README 中的 Citing 部分、BibTeX、DOI 链接和「请引用」文本；本地 git 标签也会被视为确定性版本证据。
• 发布完善：演示 GIF 已生成，问题访问权限已开放，已提交的自扫描报告为 100/100。

0.2.0 版本新增内容

• rrdoctor fix 可针对常见缺项提供确定性、幂等的自动修复（治理文档、引用元数据、数据／结果溯源信息、种子辅助工具脚手架、变更日志、忽略条目）。绝不覆盖现有内容。
• rrdoctor plan 会生成与工具无关的修复计划，可交给任意编码 Agent；每项任务都会注明用于验证的确定性检查。
• 基线门控：rrdoctor scan --baseline report.json --fail-on-new error 仅在出现新引入的问题时失败，因此大型代码仓库可以逐步采用审计。
• rrdoctor badge 会生成 Shields.io 端点或 SVG 工件就绪徽章。
• 工件就绪标签会将问题映射到 AE 风格的级别：Available、Functional 或 Reproduced-ready。数值评分仍作为辅助分诊信号。
• 一流的 PR 自动化：Action 会发布固定在 PR 中的评论、写入作业摘要，并可附加修复计划，且仅使用内置的 GITHUB_TOKEN。
• 新增规则包括未固定版本的依赖项、已提交的 Notebook 检查点、pre-commit 配置，以及供 Agent 和人工贡献者使用的 AGENTS.md 任务指南。

快速入门

rrdoctor scan .                   # deterministic audit (Markdown report)
rrdoctor fix . --write            # apply safe scaffolding for easy gaps
rrdoctor plan . --output plan.md  # tool-agnostic work order for the rest
rrdoctor scan . --format json --output baseline.json --fail-on none
rrdoctor scan . --baseline baseline.json --fail-on-new error  # gate regressions

更严格的门控和报告文件：

rrdoctor scan . --profile strict --fail-on warning --output rrdoctor-report.md

机器可读输出和 Agent 输出：

rrdoctor scan . --format sarif --output rrdoctor.sarif --fail-on none
rrdoctor scan . --format agent --output fix-plan.md

提交截止日期前：

rrdoctor prepare . --profile acm --out-dir rrdoctor-prep          # one local AE packet
rrdoctor appendix . --profile acm --output ARTIFACT_APPENDIX.md   # appendix + checklist mapping
rrdoctor verify . --profile neurips                               # L1/L2/L3 ladder (static)
rrdoctor verify . --run --timeout 600 --fail-on error              # build + run gate (trusted repos)
rrdoctor verify . --command "python train.py config/default.py" --run --timeout 600

提交配置文件：acm、neurips、icml、ml-paper、fair4rs、joss（以及通用的 minimal/standard/strict/ml 层级）。静态依赖项和运行时检查也支持 R、Julia、Rust/Cargo、基于 CMake 的构建、容器和 Nix 环境，而不只是 Python 和 JavaScript。

审计 -> 修复 -> 验证循环

确定性检查器可复现且值得信赖，但无法撰写文字或判断意图。编码 Agent 擅长编辑，但需要精确的规范和客观的完成定义。Research Repo Doctor 两者兼备：

1. 审计：rrdoctor scan 会生成确定性检查结果。
2. 修复简单问题：rrdoctor fix --write 会生成治理文档、引用元数据、溯源说明、种子辅助工具、变更日志和忽略条目的脚手架（幂等，绝不覆盖现有内容）。
3. 规划其余工作：rrdoctor plan 会生成与工具无关的工作单。将其粘贴到你选择的编码 Agent 中、附加到 issue，或手动处理。
4. 验证：针对基线重新运行审计。由于验证具有确定性且无需密钥，因此可作为可靠的评分器，评估来自任何来源的更改。

参见 docs/agent-workflows.md 和 docs/autofix.md。

GitHub Action

在多个代码仓库中添加同一个工作流，即可在拉取请求和推送时获得一致的可复现性报告。该 Action 无需 API 密钥。

name: Reproducibility audit

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  rrdoctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: Tom409114/[email protected]
        with:
          profile: standard
          fail-on: none
          comment-pr: "true"     # sticky PR comment with the report
          step-summary: "true"   # report in the job summary
          plan: "true"           # attach an agent-ready fix plan
          appendix: "true"       # attach an Artifact Evaluation appendix
          verify: "true"         # attach the L1/L2/L3 verification ladder
          prepare: "true"        # upload a complete AE prep packet directory
          # For trusted repos, add verify-run: "true" and verify-fail-on: error

有关新问题门控和已提交基线的信息，请参见 docs/pull-request-automation.md。

输出示例

Research Repo Doctor Summary
Profile: standard
Readiness: Functional
Score: 64/100
Errors: 0
Warnings: 5
Rules evaluated: 32

How to fix first:
- RRD030 No dependency manifest found: Add pyproject.toml, requirements.txt, or another manifest.
- RRD040 Data availability documentation missing: Add DATA.md, docs/data.md, or a README section.

完整示例见 examples/reports/，其中包括修复计划和自扫描报告。

命令

命令	用途
rrdoctor scan	运行确定性审计；支持 --baseline 和 --fail-on-new。
rrdoctor fix	为常见缺漏应用安全、幂等的脚手架（使用 --write 应用）。
rrdoctor plan	输出与工具无关的修复计划（Markdown 或 JSON）。
rrdoctor prepare	写入本地 AE 准备材料包：报告、计划、附录和验证结果。
rrdoctor verify	可复现性阶梯 L1/L2/L3；--command 固定官方快速入门命令；--run 会实际构建并执行。
rrdoctor appendix	生成 ACM Artifact Appendix 和 ACM/NeurIPS 检查清单映射。
rrdoctor badge	输出工件就绪状态徽章（Shields.io 端点或 SVG）。
rrdoctor mcp	运行 MCP 服务（将 scan/verify/appendix 作为 Agent 工具）。
rrdoctor init	写入带说明的 .rrdoctor.yml。
rrdoctor list-rules	列出所有已注册规则。
rrdoctor explain RRD0xx	说明规则及其修复方法。
rrdoctor doctor	自诊断。
rrdoctor --version	显示已安装的软件包版本。

规则类别

文档、环境、数据、实验、笔记本、引用、治理、测试、 CI、安全、发布和元数据。完整列表见 docs/checks.md； 其中标明了可自动修复的规则。

可复现性立场

Research Repo Doctor 不声称能够证明论文具有可复现性。它会检查有助于尝试复现的发布规范。报告基于启发式方法，应由维护者审阅。生成的修复仅为起点，发布前还需补全其中的占位符。

理念

确定性优先。扫描器易于理解、易于测试，且无需网络访问也能发挥作用。核心扫描器不会添加网络调用，不会要求托管服务 API 密钥，也不会捏造采用情况指标。AI 是你可以用来处理输出的工具——绝不是审计本身的依赖，也不会绑定到单一工具。

配置

version: 1
profile: standard
paths:
  exclude: [".git", ".venv", "node_modules", "__pycache__"]
thresholds:
  large_file_mb: 50
  large_notebook_output_kb: 1024
rules:
  RRD032:
    enabled: false
  RRD042:
    severity: warning
fail_on: error

参见 docs/configuration.md。

参与贡献

欢迎贡献。请先阅读 CONTRIBUTING.md 和 AGENTS.md， 提交规则请求或误报报告，并尽可能附上最小化的测试样例。

安全

请勿在公开议题中报告疑似凭据泄露。参见 SECURITY.md。

引用

请使用随附的 CITATION.cff，或引用此版本的 DOI： 10.5281/zenodo.21289885。 稳定的概念 DOI 10.5281/zenodo.21045161 会指向 最新归档版本，并保留完整的版本沿革。

paper/ 中提供了一份 JOSS 风格的论文草稿，供审阅。 该草稿尚未提交，并有意避免未经核实的采用情况声明； 只有在信息属实时才会更新正式投稿元数据。

@software{research_repo_doctor_2026,
  title = {Research Repo Doctor},
  author = {{Research Repo Doctor Maintainers}},
  version = {0.2.24},
  year = {2026},
  doi = {10.5281/zenodo.21289885},
  url = {https://github.com/Tom409114/research-repo-doctor}
}

许可证

MIT。参见 LICENSE。