TraceFact MCP Server

60 秒快速上手

git clone https://github.com/Alex0AI/tracefact.git
cd tracefact
npm ci
npm run build
node dist/cli.js analyze examples/offline-demo.codex.jsonl --out report

打开 report/report.html。它是独立的，可离线使用。该命令还会写入 report.json、report.md、report.sarif 以及一个经哈希验证的 run.tracefact.gz 重放胶囊。

更喜欢用浏览器？打开在线演示，拖入一条追踪，然后导出报告。文件永远不会离开页面。

Related MCP server: jaeger-mcp

输入什么；输出什么；为何可信

flowchart LR
  A[Codex / Gemini CLI / Browser Use / JSONL / OTel] --> B[Open Agent Trace Schema]
  B --> C[Redaction]
  C --> D[Evidence Graph]
  C --> E[Deterministic failure rules]
  D --> F[HTML · JSON · Markdown · SARIF]
  E --> F
  C --> G[Replay Capsule + SHA-256]

TraceFact 不会将正确性隐藏在一个 LLM-as-judge 评分背后。它提取明确的完成声明，并将每一条与可观察的工具结果、测试、差异、浏览器操作、来源和工件哈希关联起来。每条失败发现都带有精确的事件 ID。缺失的遥测数据会以不确定性的形式呈现。

原创核心

• Open Agent Trace Schema (OATS) 1.0 —— 一个带版本、可扩展的追踪封装，包含 JSON Schema、严格的 TypeScript 类型和迁移。

• 证据图 —— supported、weak、unsupported 或 conflicting 的声明，带有因果证据边和解释。

• 重放胶囊 —— 一个可移植、已脱敏、gzip 压缩的运行记录，包含规范化后的追踪、环境摘要、来源元数据、报告和哈希。审查不需要原始模型或 API 密钥。

• 失败分类法 —— 确定性定位循环、重复调用、检索漂移、未经验证的更改、失败的测试、无证据的完成、成本激增、提前终止和恢复失败。

• 可靠性报告 —— 独立的 HTML 以及 JSON、Markdown 和 SARIF。基准分数始终限定在其原始基准范围内。

适配器

适配器是插件。实现从 tracefact/adapter-sdk 导出的精简 TraceAdapter 接口；未知字段会保留在 attributes 或 extensions 中。

CLI

tracefact analyze <trace> [--adapter auto] [--out tracefact-report]
tracefact replay <run.tracefact.gz> [--out replay.html]
tracefact verify <run.tracefact.gz>
tracefact migrate <old-trace.json> --out migrated.json
tracefact adapters
tracefact serve --dir web-dist --port 4173

GitHub Action

- uses: Alex0AI/tracefact/action@v0.1.2
  with:
    trace: artifacts/codex-rollout.jsonl
    adapter: auto

该 Action 会追加作业摘要，在授予 pull-requests: write 权限时更新基于标记的 PR 评论，并上传完整的 HTML/JSON/Markdown/SARIF/胶囊捆绑包。不会向第三方发送任何追踪。

只读 MCP 服务器

{
  "mcpServers": {
    "tracefact": {
      "command": "node",
      "args": ["/absolute/path/to/tracefact/dist/mcp.js"],
      "env": { "TRACEFACT_STORE": "/absolute/path/to/traces" }
    }
  }
}

工具：list_runs、get_run 和 get_reliability_report。没有写入工具。

小型、可复现的证据集

dataset/generated/ 包含 60 条确定性的 CC0-1.0 合成追踪，涵盖成功、失败的测试、工具循环、不支持的完成、成本异常和成功恢复。使用 npm run dataset:generate 重新生成；使用 npm run experiment 进行评估。

v0.1 实验在规则编写的合成标签上报告了微平均精确率 0.833、召回率 1.000 和 F1 0.909。所有 10 个明显的假阳性都是 hallucinated_completion 发现，出现在主标签为 test_failure 的夹具上：完成声明与失败的测试相冲突，但该次要标签被有意省略。这暴露了多标签歧义，而不是隐藏它。该结果是回归证据，而非现实世界泛化的证明。参见数据卡、原始结果和技术报告。

TraceFact 的定位

这是基于公开文档的范围比较，审阅于 2026-08-20——并非质量排名。TraceFact 可以摄取现有可观测性栈导出的 OpenTelemetry，而不是取代它们。

隐私与安全

脱敏涵盖常见的 API 密钥、Bearer 令牌、Cookie、电子邮件、Windows/macOS/Linux 主目录路径，以及名称类似机密的字段。请将脱敏视为纵深防御：发布胶囊前先进行审查。TraceFact 默认使用公共仓库数据，没有遥测，并且从不上传追踪。

开发

npm ci
npm run check
npm run test:coverage

CI 在 Windows、Linux 和 macOS 上使用 Node 20 和 22 运行。参见 CONTRIBUTING.md、SECURITY.md 和 DECISIONS.md。

许可证

Apache-2.0。它对商业和研究用途都很宽松，包含明确的专利授权，并要求保留声明。数据集夹具为 CC0-1.0。外部项目和数据仍遵循其各自的许可证；参见 THIRD_PARTY.md 和 DATA_SOURCES.md。