FailTrace

本地服务

github.com开发工具08 周前更新

代码仓库访问官网

关于 FailTrace

FailTrace 是面向编码 Agent 的本地命令行工具和 MCP 服务，用于调查间歇性测试失败。它保存可重复的试验结果，帮助对照已捕获的失败检查修复方案。

主要功能

01重复测试并捕获失败基线
02比较正常与失败的试验
03通过 bisect 搜索 Git 历史
04缩减复现问题的输入
05根据已存基线验证补丁
06保存可重放的调查记录

适用场景

01编辑前捕获不稳定测试失败
02根据原始失败检查修复方案
03查找与回归相关的 Git 变更
04将输入缩减为更小的复现样例

MCP 相关

本地 stdio MCP 服务提供七种工具，与命令行共用引擎，可重复试验、比较结果、搜索回归、缩减输入、验证和重放。MCP 客户端还可读取已保存的试验与日志页面。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "lbarimi-failtrace": {
      "command": "npx",
      "args": [
        "-y",
        "failtrace"
      ]
    }
  }
}

启动命令npx -y failtrace

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmfailtrace1.5.0stdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
cwd	string	否	工作目录；相对路径相对于服务端工作目录解析。
env	object	否	显式环境变量覆盖项。null 会取消继承的变量。
args	array	否	字面量可执行文件参数（包括空数组）会停用 Shell 解析。Minimize 仅将整个 `{input}` 参数替换为每个候选路径。Windows 的 .cmd/.bat shim 需要 Shell 模式。
repeat	integer	否
command	string	是	args 缺省时为 Shell 命令；存在 args 时为可执行文件。命令和参数合计不得超过 64 KiB。使用你的本地权限执行。
predicate	any	否
timeoutMs	integer	否
captureEnv	array	否	仅将这些选定的环境变量记录在元数据中。
concurrency	integer	否	同时运行的试验上限；默认为 1，最多为 64。共享端口、文件、数据库以及资源竞争可能改变失败概率。
artifactsDir	string	否
captureContext	object	否	捕获已声明的常规输入/设置/源文件标识以供验证。指定源文件时，范围仅限文件；否则捕获 Git 标识。相关变量名请另行使用 captureEnv。
captureContext.inputFiles	array	否
captureContext.setupFiles	array	否
captureContext.sourceFiles	array	否
maxOutputBytes	integer	否	每次试验的 stdout/stderr 合计字节上限；默认为 16 MiB。达到上限的结果无法确定。
maxTotalOutputBytes	integer	否	整个实验（包括所有候选项）的输出字节总上限；默认为 256 MiB。
executionRequirement	object	否	在预期检查运行后发出的可选检查点。缺少证据会导致分类/验证无法确定；Verify 会从基线继承此项。
executionRequirement.stream	enum	是	stdout \| stderr
executionRequirement.contains	string	是

详细介绍

FailTrace

复现故障。验证修复。

测试会间歇性失败。你的编码 Agent 修改了代码。只重试一次并通过，仍然无法让你确定是否修好了。

FailTrace 会重复运行同一项检查、保存失败基线，并据此检查拟议的修复。使用 CLI 或 MCP 工具获取试验结果、更精简的复现用例，以及 Agent 在接受补丁前可以检查的证据。

本地执行。无需 AI API、账户或遥测。继续使用现有的测试运行器和断言。

快速开始

在任意工作目录中，使用 Node.js 22.12+ 和 npm 运行以下命令：

npx --yes failtrace demo

FailTrace 演示：捕获故障、缩减输入、拒绝无关崩溃，并检查补丁

静态演示 · 静态海报 · 演示指南

演示会将六个输入项缩减为 ["BUG"]，拒绝一个因其他原因而崩溃的补丁，并检查一个可正常工作的补丁。它会将证据保存在 .failtrace/ 中，并打印一条重放命令。

面向编码 Agent

通过客户端的配置连接本地 stdio MCP 服务：

npx --yes [email protected] mcp --cwd "/absolute/path/to/your/project"

复制 MCP 配置并检查连接 →

客户端会启动此命令。在终端中单独运行该命令会等待 MCP 请求。本指南包含 Windows 设置说明。

然后向 Agent 提出以下请求：

修改代码前，使用 FailTrace 捕获此测试故障。选择准确的测试或失败消息，保存有界基线，并检查匹配的试验。修改后，针对该基线进行验证，并说明任何无关错误或不完整的证据。

这七个 MCP 工具共用 CLI 的 Core 引擎。它们会在重复运行、比较、回归搜索、最小化、验证和重放过程中保留故障特征及调查证据。Agent 无需重新运行命令，即可获取已保存的试验和日志页面。支持 Shell 的 Agent 也可以使用带 --json 的 CLI。

MCP 工作流：捕获目标、检查已保存的 stderr，并验证声明的补丁

Agent 可以先检查已保存的故障，再检查补丁。

重新检查现有单元测试

针对一项确切的 NUnit 或 Unity 测试，跟踪修复过程。 每次尝试都会生成一份全新的 NUnit 3 报告。缺失或已跳过的测试，以及无关的失败，都会被判定为结论不明，因此 Agent 不能将它们当作所选测试已通过的证据。

连接你的测试，或尝试原始 EditMode 示例 →

NUnit 支持从 1.3.0 版本起通过 CLI 和 MCP 提供。文档中的 Unity 验证涵盖 Windows EditMode 示例。

NUnit 证据：失败的基线、通过的候选项，以及被判定为结论不明的已跳过测试

所选测试保持不变；已跳过的报告不会被视为测试通过。

在自己的故障上使用

在你的项目中，将命令和消息替换为你自己的内容：

npx --yes [email protected] run "npm test -- checkout" --repeat 20 --stderr-contains "checkout failed" --capture-context

在 Git 项目中，编辑前运行此命令。--capture-context 会记录源身份，供 Verify 使用；在 Git 项目之外，请使用 --context-source 选择文件。每次试验都会保存其输出，退出码 1 可能表示已成功捕获目标。然后编辑并验证补丁 →

你的下一个问题	命令
此故障出现得有多频繁？	`run`
正常试验和故障试验之间有哪些差异？	`compare`
是哪次 Git 更改引入了它？	`bisect`
重现它需要什么输入？	`minimize`
拟议修复后发生了什么？	`verify`
如何重放这次调查？	`bundle`