repro-pilot0.2.0

ReproPilot

English | 简体中文

ReproPilot 是一个基于 Pi Coding Agent 的 issue 复现 agent。

给它一个 GitHub issue 链接，它会在对应仓库的本地副本中调查问题、复现行为、创建回归测试，并用实际执行过的命令和测试作为证据。加上 --fix 后，它还会尝试修复并验证。

适合谁

• 想学习证据驱动 coding agent 如何工作的开发者。
• 想把 issue 转换成可复现测试案例的项目维护者。
• 想先确认 bug，再决定是否修复的开发者。

ReproPilot 在本地运行，不会自动 commit、push 或创建 PR。

它会做什么

读取 issue → 分析 → 复现 → 创建失败的回归测试
                              ↓
                 不加 --fix：验证并报告
                 加上 --fix：修复 → 验证 → 报告

仅仅阅读代码不能证明问题已复现。ReproPilot 必须获得实际运行命令或测试产生的证据。

架构

ReproPilot 是一个 Pi package，主要组成如下：

路径	职责
extensions/repro-workflow/	接入 Pi：注册 /repro、自定义工具、Session 事件和 TUI 状态
skills/repro-workflow/	告诉模型应该按照什么步骤复现问题
src/core/	不依赖 Pi，负责工作流状态、证据规则、持久化验证和报告生成
src/github.ts	加载并验证 GitHub issue，同时检查当前仓库是否匹配
src/workspace.ts	记录 Git 基线，检测仓库文件内容变化

Pi 提供模型循环和内置仓库工具；ReproPilot 只增加 issue 复现流程和由代码强制执行的证据门槛。

使用要求

• Node.js 22.19 或更高版本。
• 已配置模型的 Pi Coding Agent。
• issue 所属仓库的本地副本，并具有正确的 GitHub origin。
• 目标仓库需要的依赖和本地运行环境。

目标仓库不受编程语言或测试框架限制。

ReproPilot 会在当前仓库中运行命令，也可能创建或修改文件。运行前请检查工作区状态，或者使用单独的分支。

快速开始

使用 npm 安装 Pi：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts 会在安装过程中禁用依赖项生命周期脚本。Pi 在正常的 npm 安装过程中不需要安装脚本。

也可以使用安装程序：

curl -fsSL https://pi.dev/install.sh | sh

使用 API 密钥进行身份验证：

export ANTHROPIC_API_KEY=sk-ant-...
pi

或者使用已有订阅：

pi
/login  # 然后选择提供商

然后安装一次 ReproPilot：

pi install npm:repro-pilot

公开 issue 不需要 GitHub token。对于需要登录才能访问的 issue，请在启动 Pi 前设置 GITHUB_TOKEN。

运行

先下载或打开 issue 所属仓库：

git clone https://github.com/OWNER/REPOSITORY.git
cd REPOSITORY
git switch -c test-repro-pilot
pi

建议使用独立分支，因为 ReproPilot 可能创建测试或修改源码。分支名可以自行修改。

请直接正常启动 Pi，不要添加 --no-skills：它会禁用 ReproPilot 自己的 workflow skill。ReproPilot 不包含任何无关 skill。

替换其中的大写占位符，然后在 Pi 中运行：

/repro https://github.com/OWNER/REPOSITORY/issues/ISSUE_NUMBER

这会复现问题并创建回归测试，但不会修改源代码来修复问题。

如果还希望尝试修复：

/repro https://github.com/OWNER/REPOSITORY/issues/ISSUE_NUMBER --fix

issue 所属仓库必须与当前仓库的 GitHub origin 一致。两者不匹配时，ReproPilot 会停止，避免修改错误的代码库。

查看运行状态

Pi 会显示类似状态：

repro:triage outcome:in_progress evidence:0 test:not_started fix:not_started

• repro：当前工作阶段。
• outcome：当前或最终结果。
• evidence：已记录的证据数量。
• test：回归测试状态。
• fix：修复状态。

阶段	含义
triage	理解 issue，定位相关代码和测试
reproduce	运行代码，比较实际行为与预期行为
test	创建回归测试，并确认它在原始代码上失败
fix	修改源代码，仅在使用 --fix 时进入
verify	运行回归测试和相关现有测试
report	生成最终报告

test 可能是 not_started、failing、passing 或 blocked；fix 可能是 not_started 或 applied。

查看最终结果

结果	含义
reproduced	问题已复现，回归测试在原始代码上失败，但没有修复源代码
fixed	问题已复现并修复，回归测试和相关现有测试都通过
not_reproduced	已实际尝试复现，但没有观察到 issue 描述的问题
blocked	因信息、依赖或环境不足而无法继续

最终报告写入目标仓库：

.repro-pilot/runs/<run-id>/report.md

阅读报告时，先看 Outcome 和 Verification。需要检查结论依据时，再看 Evidence Details 中的命令、退出码和相关输出。每条证据使用 E1、E2 等编号。

当前限制

• 只接受 github.com 的 issue URL。
• 需要用户提前打开匹配的本地仓库。
• 目标项目的依赖和测试必须能够在本地运行。
• 不提供云端隔离环境，不自动 commit、push 或创建 PR。

执行记录与恢复

插件现在从 Pi 的真实 bash 执行中登记命令、输出和退出码。模型通过执行编号引用这些记录，不能自行填写执行结果。报告会区分“程序正常运行但没有观察到 bug”和“缺少依赖、命令中断等阻塞”。

测试通过以后，如果代码又改了，必须重新测试；后来失败的结果也不能被以前的通过记录掩盖。复现模式下，新增的回归测试应保持失败；修复模式下，同一个回归测试和原有测试都应通过。

同一时间只能有一个未结束的运行。保存状态失败时，请重启 Pi 后再继续；报告写入失败时，运行保持未完成，可以重试。已经结束的运行不会再追加证据。

旧的 schema-v1 存档没有真实执行记录，需要重新开始运行。当前内容快照要求 Git 已有提交，覆盖受 Git 管理及未被忽略的新文件，排除 .repro-pilot 生成物；暂不接受子模块和特殊文件。命令若产生文件改动，需要在文件稳定后重新执行，再将结果用作证据。