Provides sandboxed isolation for reproduction runs, allowing the agent to execute and verify research code inside a Docker container via runfix reproduce --sandbox docker instead of on the host machine.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
面向科研代码的自主运行诊断、环境修复与实验复现 Agent。
退出码为 0，不等于实验复现成功。 这是整个项目的设计前提：RunFix 的每一条结论都必须能指回它采集到的证据， 证据不足时它会降级并说明缺什么，而不是补一句猜测。
Related MCP server: Hoplon
RunFix 接收一个科研代码仓库，自主完成「理解项目 → 诊断环境 → 定位根因 → 受控修复 → 运行验证 → 判定是否复现」的闭环， 并对每一步给出可核查的证据。
科研人员复现一篇论文的代码时，通常不是卡在一个点上，而是连续卡在三个断层的交界处：
断层 | 典型症状 | 现有工具的局限 |
环境断层 | conda/pip 装完仍然报错；CUDA 与 PyTorch 版本不匹配 | 依赖安装器只管装，不判断“装完能不能跑” |
代码断层 |
| 报错解释器只解释文本，不结合依赖清单与已安装版本 |
结果断层 |
| 评测框架通常只跑一次，把“没报错”当成成功 |
只解决其中一环的工具，会在另外两环失效。RunFix 的判断是：这三件事必须在同一条工作流里解决， 否则每一步的结论都无法被下一步验证。
RunFix 不是一个“更好用的依赖安装器”，也不是“更聪明的报错解释器”，而是一个有决策、执行、观察、 修复和验证能力的 Agent：
项目理解 → 环境诊断 → 根因定位 → 方案规划 → 受控执行 → 测试验证 → 结果反馈 → 自适应调整参考了三个方向，并在它们止步的地方继续：
参考方向 | 借鉴 | RunFix 的增量 |
Repo2Run | 科研仓库到可运行环境的构建思路 | 增加运行失败后的诊断、修复与验证闭环 |
Env-Doctor | Python 环境与依赖问题识别 | 把环境问题与真实日志、源码、测试结果关联成证据图 |
ResearchEnvBench | 科研环境构建与复现能力的评测思路 | 建立自己的可复现基准与消融实验 |
差异化可以概括为一句：
RunFix = 项目理解 + 环境诊断 + Agent 决策 + 安全修复 + 实验复现 + 可验证评测。
项目 | 内容 |
名称 | RunFix（Python 包名 |
版本 | 1.0.0 |
语言 / 运行环境 | Python 3.10+；Windows 10/11 + Anaconda 或 venv（主目标平台），Linux 亦可 |
核心接口 | CLI（19 个子命令）、MCP Server（stdio，23 个工具）、本地 Web 控制台 |
运行时依赖 | 无（ |
代码规模 |
|
文档 |
|
许可 | MIT |
仓库 | |
项目性质 | 开源课程作业：在原有 0.6.0 代码基线上完成审计、稳定化、功能扩展到 1.0.0，并逐项验证 |
可追溯的诊断：每个根因候选都列出支持事实与反证，置信度可由代码复算。
可回滚的修复：任何文件修改都是事务，失败可自动回滚，崩溃后可恢复。
可判定的复现：用七级证据阶梯代替“退出码 0”，并写明为什么没到下一级。
可审计的执行：特权操作进入 SHA-256 哈希链，权限只能收紧不能放宽。
不是通用依赖安装器，也不替代 conda/pip。
不修改系统驱动、不改全局 PATH、不提权。
不下载数据集 / 模型权重 / 许可资源，除非用户显式授权。
不在没有证据时宣称“已修复”或“已复现”。
能力 | 命令 | 说明 |
项目扫描 |
| 结构、入口、依赖清单、import、语法错误、git 状态 |
环境诊断 |
| Python / PyTorch / CUDA / GPU / nvidia-smi |
分层验证 |
| C0–C5：静态检查 → 入口运行 → 框架对齐 → 单卡 → 多卡 → 证据审计 |
错误分析 |
| 支持 CPython 与 pytest 两种 traceback 风格，附源码上下文 |
证据化根因 |
| 证据图 + 13 类候选 + 可复算置信度 |
补丁校验 / 应用 / 恢复 |
| 七道闸 + 事务 + 回滚 + 崩溃恢复 |
自主 Agent |
| Plan–Act–Observe，按根因排序决策，支持断点恢复 |
实验复现 |
| 理解 → 计划 → 执行 → 指标 → 七级判定 |
隔离执行 |
| 容器 / WSL 内运行，后端缺失则拒绝而非降级 |
MCP Server |
| 23 个工具，三层权限门禁，可对接 Codex/Claude 类客户端 |
多项目控制台 |
| 项目注册表 + 任务/审计/报告视图 |
操作审计 |
| SHA-256 哈希链， |
权限审批 |
| 一次性、带有效期、可撤销 |
断点列表 |
| 查看 / 恢复历史 Agent 运行 |
自评测 |
| 11 个任务的基准 + 4 组消融 |
这是本文档的核心部分：每一步读什么、按什么规则判、判不出来怎么办。 完整版（含公式推导、判定树伪代码、已知弱点）见 docs/EVIDENCE_CRITERIA.zh-CN.md。
证据 | 判定规则 | 产出 |
README | 按优先级匹配 | 安装命令、运行命令、标题结构 |
入口脚本 | 文件名基础分 +40（README 提及）+20（ |
|
配置文件 | 扫 |
|
配置解析 |
| 每个配置记录用了哪个解析器 |
数据集 | 键名匹配 |
|
设备需求 | 代码出现 |
|
CUDA 线索 | 依赖与 README 中的 |
|
Python 要求 |
|
|
判不出来时：没有 README、没有入口、没有依赖清单都写进 warnings；数据集缺失写进 missing_datasets 且不会自动下载。
这一步只读文件。基准测试用“诊断前后全量文件 SHA-256 比对”证明未改动任何文件（
files_modified_by_diagnosis必须为 0）。
探针采集：Python 版本与路径、平台、8 个常见科学计算包版本、torch 是否可导入及其
cuda_available / cuda_version / GPU 数量与名称、nvidia-smi 是否可用及输出。
判定项 | 依据 | 结论 |
Python 兼容 | 解释器版本与 |
|
CUDA 兼容 | 声明的轮子标签（ | 驱动 ≥ 所需 → |
环境清单 | 固定优先级 |
|
数据集 | 第一步的 |
|
GPU 风险 | 代码需要 CUDA，但探针看不到 GPU |
|
关键取舍：CUDA 兼容性不做猜测。没有声明轮子标签、或拿不到驱动版本，答案就是“无法判定”并说明原因。
先把异常、调用帧、源码文件、import、声明约束、实际版本、候选测试连成证据图：
节点：project、git_revision、environment、framework、dependency、installed_package、module、source_file、test_file、exception
边：failed_with、raised_in（带行号与函数）、imports、references、declares、resolved_to、tested_by、has_revision、runs_on、provides
再生成 13 类根因候选，每类都带“陈述 + 支持证据 + 反证 + 一个具体动作”：
候选 | 触发 | 建议动作 |
| 报错点名某模块，清单声明了但它没装 |
|
| 报错点名某模块，任何清单都没声明 |
|
| 无报错，但清单里有包没装 |
|
| 安装版本落在约束外 |
|
| 两份清单对同一包约束冲突 |
|
|
|
|
| 声明 |
|
| 代码要 CUDA 但看不到 GPU |
|
| 配置里的数据路径不存在 |
|
|
|
|
| 语法错误 |
|
| 断言失败且有项目内调用帧 |
|
| 以上都不成立 |
|
置信度公式（确定性、可复算）：
置信度 = 基础分(按候选类型, 0.30–0.90)
+ min(0.09, 0.03 × (证据条数 − 1))
+ 一致加分（traceback 分类器给出同一类 +0.06；CUDA 驱动判定一致 +0.05）
− 0.12 × 反证条数
裁剪到 [0.05, 0.98]
排序分 = 置信度 + 0.01 × min(5, 证据条数)实算示例（演示项目的真实输出）：module_declared_missing = 基础 0.86 + 0.03（2 条证据）+ 0.06（分类器一致）= 0.95。
什么时候不给结论：没有任何规则命中时返回 unclassified_error（0.30）并列出建议补采的证据。
基准集里专门有一个无缺陷对照任务，要求的正确行为就是弃权——只会“总能找出点问题”的系统并不可信。
三道门禁（缺一不可）：服务端开关（--enable-write 等）→ 单次调用确认（confirm_write）→
可选的一次性、带有效期审批（--require-approval）。
七道补丁闸（全部通过才落盘）：
项目内相对路径，禁止 ..、绝对路径、盘符；
禁止修改 .git 与 .runfix；
扩展名白名单；
逐段符号链接检查，拒绝穿越；
拒绝二进制补丁、子模块补丁、符号链接模式补丁；
git apply --check 必须成功；
在隔离临时树里应用后，改动的 Python 文件必须能 ast.parse。
事务与回滚判定：
场景 | 判定依据 | 结果 |
应用 | 事务 ID + 原文件备份 + 前后 SHA-256 + 项目级跨进程锁 |
|
回滚 | 所有目标文件当前哈希必须等于记录里的 | 全等才回滚，否则拒绝并列出冲突 |
崩溃后（ | 哈希 == |
|
应用成功不等于修复成功——必须过第五步。
Agent 何时修、何时停：策略读的是排名第一的根因动作，而不是固定流程。
排名第一的动作 | 行为 |
| 有安装权限 → 建隔离环境；没有 → 停在 |
| 有写权限 → 校验 → 应用 → 验证；没有 → 停在 |
| 停在对应原因，交人决策 |
| 停在 |
显式 argv、shell=False、超时、stdout/stderr 合并写入 .runfix/repro/<run-id>/run.log。
测试选择（先跑哪些）：+100 测试文件本身出现在 traceback；+15 测试源码引用了报错源文件的相对路径； +10 静态 import 了 traceback 中的模块；+5 同名 basename。先跑相关测试，通过后再跑全量； 无法确定关联就直接跑全量。
运行状态机（五态，互斥）：
状态 | 依据 |
| 进程启动即失败 |
| 超过超时被杀 |
| 退出码 ≠ 0 |
| 退出码 0 且有完成证据 |
| 退出码 0 但没有任何完成证据 |
完成证据（三者之一即可）：解析到 ≥1 个指标观测点；命中 13 个完成标记之一
（training complete、training finished、all epochs、final results、final test、
best model saved、saved checkpoint、evaluation results、test results、experiment finished、
reproduction complete 等）；或匹配调用方提供的 --completion-regex。
同时记录：git commit / branch / dirty、依赖清单 SHA-256、解释器与 torch/CUDA 版本、GPU 名称、 运行期间新建或修改的文件（产物）。
这是“是否复现”的正式判定：取当前证据能支撑的最高一级，并写明为什么没有更高。
级别 | 进入条件（缺一不可） |
| 读过仓库 |
| 有环境 / 运行计划 |
| 命令真的跑过（超时、失败也算） |
| 退出码 0 且有完成证据 |
| 从输出解析出最终指标 |
| 声明的目标值全部匹配 |
| 指标匹配 且 运行期间工作区干净 且 有 git commit |
指标比较规则：名称按别名表归一（acc → accuracy、f1_score → f1 等）；
目标值 |v| ≤ 1 用绝对容差 0.02，否则用相对容差 2%；每个目标值为
match / mismatch / missing（输出里没有该指标）三态，全部 match 才升级。
判定树（对应 derive_verdict）：
没执行 → plan_ready
启动失败 → 停在 plan_ready，附启动错误
超时 / 失败 / 零退出码无输出 → executed，并写明具体原因
退出码 0 且有完成证据 → completed
解析到指标 → metrics_recorded
未声明目标值 → 停在 metrics_recorded，写明"无法与论文比较"
目标值全部匹配 → metrics_matched
工作区脏 / 无 git 提交 → 停在 metrics_matched，写明原因
否则 → reproducedreproduced 的准确含义：
是：在这台机器、这个提交、这套依赖版本下，文档里的命令跑通了，解析出的指标满足你声明的目标值，工作区没有未提交改动。
不是：论文结论正确、方法优于基线、结果在别的机器上可重复、统计显著。这些写入报告的 limitations，不用措辞掩盖。
以下都是本仓库真实运行的输出，不是示意图。
① 诊断：项目声明了 numpy 但没安装——
$ runfix diagnose-root-cause . --traceback-file error.log
top kind : module_declared_missing conf=0.95 rank=1
statement : 'numpy' is declared by the project but is not installed in the selected interpreter.
action : install_package -> pip install numpy>=1.20
evidence : requirements.txt, traceback, analysis（独立分类器一致）
graph : 11 nodes / 12 edges② 复现：同一个项目，声明论文里的指标——
$ runfix reproduce . --allow-execution --expect accuracy=0.8 --expect f1=0.74
verdict : reproduced
run status : completed (rc=0, 0.53s)
comparison : accuracy match, f1 match
artifacts : outputs/base/metrics.json
git commit : 4ea2158 dirty=False③ 证据不足时明确降级：
情况 | 判定 | 报告里的理由 |
不声明目标指标 |
| “未声明目标值，无法与论文比较” |
进程退出码 0 但没有任何输出 |
| “零退出码本身不是实验完成的证据” |
声明 |
| “expected 0.99, observed 0.8（允许误差 0.02）” |
工作区有未提交改动 |
| “结果无法绑定到某个提交” |
┌──────────────────────────── 交互层 ────────────────────────────┐
│ CLI（19 子命令） MCP Server（stdio, 23 工具） Web 控制台 │
└───────────────┬───────────────────────────┬────────────────────┘
│ │
┌───────────────▼───────────┐ ┌────────────▼────────────────────┐
│ Agent 层 │ │ 复现层 (repro) │
│ policy(策略) brain(LLM) │ │ understand → plan → run → │
│ tools(白名单) core(循环) │ │ metrics → report(证据阶梯) │
└───────────────┬───────────┘ └────────────┬────────────────────┘
│ │
┌───────────────▼───────────────────────────▼────────────────────┐
│ 诊断层 (diagnosis) │
│ evidence(证据图) dependencies(PEP 440 子集) rootcause(排序) │
└───────────────┬────────────────────────────────────────────────┘
│
┌───────────────▼────────────────────────────────────────────────┐
│ 基础能力层 │
│ scanner diagnostics analyzer validation patches │
│ environments task_manager sandbox test_selection │
└───────────────┬────────────────────────────────────────────────┘
│
┌───────────────▼────────────────────────────────────────────────┐
│ 产品支撑层 │
│ audit(哈希链) approvals(一次性授权) checkpoint(断点) bench │
└─────────────────────────────────────────────────────────────────┘数据流：项目路径 → scanner/diagnostics → 失败日志 → analyzer → diagnosis(证据图+根因) → 动作(安装/补丁/运行) → 报告 + 审计
runfix/
agent/ 决策与执行：policy(策略) brain(LLM) tools(白名单) core(循环)
diagnosis/ 证据图、依赖求解、根因排序
repro/ 项目理解、环境计划、执行、指标、报告
bench/ 基准集、指标、消融、报告
mcp/ MCP Server（23 工具）与端到端冒烟
web/ 多项目控制台
audit.py 哈希链审计
approvals.py 一次性授权
checkpoint.py 断点恢复
patches.py 事务式补丁
sandbox.py Docker/WSL 隔离
scanner.py diagnostics.py analyzer.py validation.py environments.py task_manager.py
docs/ 17 份设计 / 使用 / 审计文档
tests/ 24 个测试文件
scripts/ 一键安装、升级、诊断Windows 10/11 + Python 3.10+（Anaconda 或普通 Python）。脚本不会装进你启动它的那个解释器。
# 虚拟环境方案（.venv/）
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install_windows.ps1
# 或 Conda 前缀环境（.conda_env/，不动你的 base 环境）
.\scripts\install_conda.ps1
# 一键体检：Python / git / conda / GPU / MCP 握手
.\scripts\diagnose_windows.ps1安装脚本最后会跑一次真实的 MCP stdio 自检，所以“安装成功”是验证过的成功。手动等价步骤：
python -m pip install -e ".[dev,mcp]"
python -m runfix --version # RunFix 1.0.0
python -m pytest -q # 249 passed, 2 skipped
python -m runfix.mcp.smoke --full # 23/23 工具走真实协议# 1. 只看不跑：读 README、识别入口/配置/数据集/CUDA 要求，输出环境与运行计划
runfix reproduce "D:\research\paper-code" --plan-only
# 2. 拿真实报错做证据化诊断
runfix diagnose-root-cause "D:\research\paper-code" --traceback-file .\error.log
# 3. 在明确授权下让 Agent 自主工作（可断点恢复）
runfix agent "D:\research\paper-code" --allow-project-code --allow-write --use-llm
runfix agent "D:\research\paper-code" --resume <run_key>
# 4. 跑文档里的实验，并与论文指标对比
runfix reproduce "D:\research\paper-code" --allow-execution --expect accuracy=0.812
# 5. 接入 MCP 客户端（Codex / Claude Desktop 等）
runfix mcp --allowed-root "D:\research" --enable-execution --enable-write
# 6. 多项目管理与审计
runfix web --state .\.runfix-web
runfix audit "D:\research\paper-code" --verify全部为本机实测（Windows 11、Python 3.11、mcp==2.3.0）。
检查项 | 结果 |
测试套件 | 249 passed, 2 skipped |
MCP 协议 | 23/23 工具真实 stdio 调用，exit 0 |
可复现基准 | 11 个任务，top-1 准确率 1.0，诊断修改文件数 0 |
消融：去掉依赖分析 | top-1 1.0 → 0.6364（−36.4 个百分点） |
消融：去掉评分排序 | top-1 1.0 → 0.9091（−9.1 个百分点） |
审计链 | 真实三类操作后 |
打包 | wheel 在干净 venv 安装， |
一键安装 | 真实执行（Python 3.14 + mcp 2.3.0），退出码 0 |
Web 控制台 | 真实 HTTP 调用 health/projects/tasks/audit/首页全部通过 |
2 个跳过项需要 Windows 符号链接特权（SeCreateSymbolicLinkPrivilege），在具备该权限的账户上会自动执行。
自己验证一遍：
git clone https://github.com/liaooss/RunFixMCP.git
cd RunFixMCP
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install_windows.ps1
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m runfix.mcp.smoke --full
.\.venv\Scripts\python.exe -m runfix bench --ablations三步分别验证：单元/集成正确性、协议级可用性、自身诊断能力的量化与消融。
版本 | 主题 | 关键交付 |
0.1–0.6 | 既有基线（接手前） | 扫描、诊断、Agent 循环、MCP Server、任务管理、事务补丁 |
0.6.1 | 稳定性与真实部署 | 修复 13 项缺陷：MCP v2 权限语义、Windows conda 解释器、报告换行、C5 假审计、pytest traceback、事务并发与崩溃恢复、任务退出码跨重启 |
0.7.0 | 科研实验自动复现 |
|
0.8.0 | 深度诊断与隔离 | 证据图、PEP 440 依赖求解、13 类根因排序、Docker/WSL 隔离 |
0.9.0 | 基准与消融 |
|
1.0.0 | 产品化 | 哈希链审计、断点恢复、一次性审批、多项目控制台、wheel 安装验证 |
任务书要求 | 状态 | 证据 |
① 全面审计源码，输出 | ✅ 完成 | 40 KB 审计报告；实测推翻交接文档“67 passed”，实为 4 failed / 61 passed / 3 skipped |
② 0.6.1 稳定性（真实环境、MCP 握手、任务恢复、事务并发、回归测试） | ✅ 完成 | 13 项缺陷全修；MCP 真实握手通过；105 passed |
③ 0.7.0 科研实验自动复现 Agent | ✅ 完成 |
|
④ 0.8.0 深度诊断与自适应修复 | ✅ 完成 | 证据图 + 13 类根因 + 依赖求解；Agent 按根因动作决策 |
⑤ 0.8.0 Docker/WSL 隔离 | ⚠️ 代码完成，容器内执行未验证 | 命令构造、路径改写、缺失即拒绝已测；本机无 Docker 守护进程、无 WSL 发行版 |
⑥ 0.9.0 基准评测 | ⚠️ 部分完成 | 自建 |
⑦ 1.0.0 产品化（审计、审批、断点、多项目） | ✅ 完成 | 审计链 |
⑧ 完整文档与测试 | ✅ 完成 | 17 份文档；249 个测试；中英判定依据文档 |
项目 | 原因 |
真实 Docker 容器 / WSL 发行版内执行 | 开发机无守护进程、无发行版； |
LLM 规划与 LLM 生成补丁 | 无 API key；离线策略已验证，LLM 路径未实测 |
真实已发表论文仓库上的准确率 | 基准集为自建，满分是回归护栏，不是真实世界精度 |
浏览器级 UI 与可访问性 | 只做了 HTTP 层验证，未在浏览器中人工点检 |
与 Repo2Run / Env-Doctor / ResearchEnvBench 的对比实验 | 需要统一真实语料与硬件条件 |
完成标记是启发式的：只写文件、不打印任何东西的项目会被判为 process_exited，此时用 --completion-regex 兜底。
指标只从 stdout/stderr 解析：只写 TensorBoard/W&B 的项目采集不到指标。
别名表有限：冷门指标名会表现为 missing 而不是 mismatch。
目标值必须由人给出：RunFix 不读论文 PDF，不替你决定“这篇论文的 accuracy 应该是多少”。
一次运行不等于可重复性：没有多种子方差分析。
干净 git 只保证可追溯，不保证科学正确。
文档 | 内容 |
文档总索引 | |
六步判定依据完整版：规则、公式、判定树、已知弱点 | |
项目简介详细版（背景、架构、版本、验证、边界） | |
接手时的逐项审计与缺陷清单（含 file:line） | |
分层结构、数据流、产品面 | |
证据图、依赖求解、置信度模型 | |
七级证据阶梯与每一级要求 | |
评测集、指标、消融、未测量项 | |
权限模型与失败处理 | |
防篡改审计 | |
23 个工具、门禁、Codex 配置 | |
多项目控制台 | |
规划器、策略、工具注册、停止原因 | |
已完成与仍未完成的路线 | |
各版本变更记录 |
贡献：见 CONTRIBUTING.md。本项目的核心规则是“无证据不下结论”， PR 需要说明改了什么、如何复现验证、以及没有验证什么。
安全：见 SECURITY.md。安全问题请走私下渠道，不要开公开 Issue。
行为准则：见 CODE_OF_CONDUCT.md。
许可：MIT，见 LICENSE；第三方组件与思路来源见 THIRD_PARTY_NOTICES.md。
引用：见 CITATION.cff。
RunFix 是一个助手。它缩短“仓库跑不起来”到“实验复现成功”之间的距离，并且如实说明这段距离还有哪一段没有走完。
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Governed MCP: agent audit, provenance, deterministic checks, and receipt-backed FragGate execution.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Remote MCP for A2A dependency inspector MCP, structured receipts, audit logs, and reviewer-ready evi
Hosted remote MCP for protected account access, permissions, activity history and supported undo.