reproagent 安装

面向 Python 和 pytest 的本地复现工具

把 Bug 描述，
变成一份可复查的
复现报告。

ReproAgent 读原始 Issue，写候选 pytest 测试，先证明它在问题版失败，再独立重跑一次，最后用修复版对照。你得到的不是一段聊天记录，而是一份可以打开、重放和检查的报告。

Windows 安装 macOS 安装 看看证据长什么样

安装和检查不调用模型。第一次真实复现才会使用你的模型配置和凭据。

~/work/my-project — zsh
~ % claude
> /reproagent 帮我复现当前项目里的这个 Bug
reading issue and repository facts
exploring code and building the contract
writing the candidate pytest
+ testing/test_repro_default_log_format.py
+ assert "%(name)s" in DEFAULT_LOG_FORMAT
running on the buggy version
FAILED testing/test_repro_default_log_format.py::test_format_has_name_field
3 failed, 1 passed in 0.41s
rerunning in a fresh copy
3 failed, 1 passed in 0.47s
validating the fixed version
4 passed in 0.12s
sealing the evidence package
DIFFERENTIAL_VALIDATED 原版失败，同一候选独立重跑仍失败，修复版通过。
report.mdtrace.jsonmanifest.jsonreplay.py
report.md
DIFFERENTIAL_VALIDATED

原版失败，独立重跑失败，修复版通过。

问题版 FAIL 独立重跑 FAIL 修复版 PASS
report.mdtrace.jsonmanifest.json

macOS 终端里的一次 Claude Code 调用

跑完只是开始，
证据包才是结果。

每次复现都留下同一组文件。报告说结论，trace 说过程，manifest 固定内容，replay 让你在全新副本里再跑一次。

文件都在本地；哈希记录在 manifest.json 里。

repro-results/pytest-dev__pytest-5227/ sealed
  • ▾package/一次复现的全部记录
  • ├─report.md结论、三次运行、失败摘要
  • ├─trace.json模型调用、工具步骤、耗时
  • ├─manifest.json文件哈希与证据清单
  • └─replay.py在全新副本里重跑候选
manifest.jsonhash recorded

不是生成一个测试，
而是证明它复现了问题。

生成测试很容易。难的是确认它真的调用到目标代码、断言打到目标行为，并且在问题版和修复版上给出相反结果。

同一份候选测试 testing/test_repro_default_log_format.py
问题版 FAIL exit 1 3 failed, 1 passed
独立重跑 FAIL exit 1 3 failed, 1 passed
修复版 PASS exit 0 4 passed
DIFFERENTIAL_VALIDATED

结果相反，才说明候选测试复现的是这个 Bug，而不是别的东西。

verify

差分验证

原版失败，独立重跑失败，修复版通过。缺一段就停在更低的证据等级。

execute

候选测试真实执行

记录目标模块调用、断言结果、pytest 退出码和 probe 是否完整，不用字符串自比较充数。

local

本地执行

目标代码和测试在你的机器上跑；使用你的 Python、pytest 和模型配置。

hosts

Claude Code 和 Codex

Windows 一条安装命令写好两个用户级入口，之后用 /reproagent 或 $reproagent 调用。

preflight

目标项目检查

检查目标 Python、pytest、测试目录和模块；需要时再用 -CollectOnly 跑一次真实收集。

从一个 Issue 到一份封存报告。

这是一条有顺序的流水线：先理解，再执行，最后封存。每一步都留下可检查的记录。

  1. 01issue

    读描述与代码事实

    issue facts
  2. 02contract

    建立触发与观察点

    contract
  3. 03candidate

    写候选 pytest 测试

    test_*.py
  4. 04buggy

    在问题版上执行

    exit 1
  5. 05rerun

    用新副本独立重跑

    exit 1
  6. 06fixed

    用修复版对照

    exit 0
  7. 07sealed

    导出报告和证据包

    manifest
报告等级由最后三段决定。 buggy → rerun → fixed

DONE 不是差分验证。

“跑完了”只说明流程结束。报告会把证据等级写清楚，避免用一句成功掩盖不确定性。

  1. 01
    DONE流程结束，不证明复现
  2. 02
    SINGLE_OBSERVATION只发生了一次原版运行
  3. 03
    REPEATED_OBSERVATION同一候选独立重跑过
  4. 04
    DIFFERENTIAL_VALIDATED原版失败、独立重跑失败、修复版通过
    最高等级

如果缺少修复版，或者只发生了一次失败，报告会停在更低的等级，不会写成 DIFFERENTIAL_VALIDATED。

test_repro_default_log_format.py testing/ pytest 
import logging
from _pytest.logging import DEFAULT_LOG_FORMAT
 
def _render(name, filename, lineno, message):
    record = logging.LogRecord(
        name, logging.DEBUG, filename, lineno, message, (), None
    )
    return logging.Formatter(DEFAULT_LOG_FORMAT).format(record)
 
def test_format_has_name_field():
    assert "%(name)s" in DEFAULT_LOG_FORMAT
 
def test_renders_django_name():
    assert "django.db.backends" in _render(
        "django.db.backends", "utils.py", 114, "SELECT"
    )
 
# buggy: AssertionError
# fixed: 4 passed
buggy AssertionError fixed 4 passed manifest.json · hash recorded

装好，给它一个 Bug。

Windows 一键安装，macOS 命令行接入。两个平台都接好 Claude Code 和 Codex 入口，安装不调用模型。

Windows / PowerShell

一条命令完成安装

安装器准备私有工具环境，复用现有 Python；找不到时再尝试自动安装。之后写入 Claude Code 和 Codex 的用户级入口。

  • 01准备工具环境
  • 02检测 Python 和 pytest
  • 03写入 Claude Code / Codex 入口
  • 04运行 setup --check
PowerShell 
git clone https://github.com/kyy-logs/ReproAgent.git
cd ReproAgent
.\install.cmd -Force

setup --check: ready
Claude Code / Codex 入口已写入

安装不调用模型

装好之后

在目标项目里
Claude Code

重启会话，直接给 Bug 描述或 task 配置。

/reproagent 帮我复现当前项目里的这个 Bug
Codex

同一套入口和模型配置，使用 $reproagent。

$reproagent 帮我复现当前项目里的这个 Bug
先检查目标项目

只读检查 Python、pytest、测试目录和模块；-CollectOnly 再跑一次收集。

.\install.cmd -Project E:\your-project -CollectOnly

完整参数和退出码在 docs/windows-install.md。

macOS 安装

macOS 通过命令行安装和接入。
Windows 一键安装器只支持 Windows。

Claude Code~/.claude/skills/reproagent
Codex~/.agents/skills/reproagent

需要 Python 3.11+。安装后在目标项目里启动 claude，输入 /reproagent ...。

页面顶部的终端演示从这一步开始。完整接入说明见 docs/ai-tool-integration.md。

Terminal — bash 
git clone https://github.com/kyy-logs/ReproAgent.git
cd ReproAgent
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/reproagent setup
setup: ready

它适合什么，不适合什么。

边界写清楚，比把所有东西都说得像万能工具更可信。

适合

4
  • Python 和 pytest 项目，需要一个能复查的回归测试。
  • 维护者、QA、AI coding agent 用户，想确认真实复现而不是看聊天结论。
  • 需要把“问题版失败、修复版通过”固化成证据的团队。
  • 希望本地执行、自己控制模型 provider 和凭据的团队。

不适合

4
  • 非 Python、非 pytest 项目。
  • 期待工具自动修改业务代码、直接给出最终修复。
  • 期待保证所有 Bug 都能复现，或把单次成功当成整体复现率。
  • 需要托管式云端执行、完全不用本地环境的产品。

ReproAgent 不替代人的审查。它把事实、执行和证据摆出来；最终是否相信这个复现，仍然由你判断。

几个常见问题。

安装、调用、证据等级和目标项目边界。

还有问题？看 接入说明 和 Windows 安装文档。

安装会调用模型吗？

不会。安装、setup --check、启动器检查和目标项目检测都不调用模型。第一次真实复现才会使用你配置的模型和凭据。

它会自动修 Bug 吗？

不会。它生成并验证回归测试；修复版由你提供，ReproAgent 负责做问题版、独立重跑和修复版的差分验证。

为什么强调 DONE 和 DIFFERENTIAL_VALIDATED？

DONE 只代表任务流程结束；DIFFERENTIAL_VALIDATED 才代表原版失败、独立重跑失败、修复版通过这三段对照成立。

Windows 需要先装 Python 吗？

安装器会先找现有 Python（包括项目 .venv），找不到再尝试 winget 或官方安装包。可以用 -NoPythonInstall 关闭自动安装。

支持 Claude Code 和 Codex 吗？

支持。安装器会写入两个用户级入口；重启会话后分别使用 /reproagent 和 $reproagent。

目标项目的依赖会自动安装吗？

不会。目标项目的 Python、pytest 和业务依赖仍由目标项目提供；-Project 只做只读检查，不会安装或修改目标环境。

先用一个 Bug 试试。

不用先跑整个数据集。
装好，给它一个 issue，看看它能不能把证据链摆出来。

Windows 安装 打开 GitHub
Windows / PowerShellno model calls
.\install.cmd -Force
安装不调用模型。旧入口会先备份。