面向中小型 Agent 团队的本地失败治理工具 — 把难以阅读的执行轨迹，变成可统计、可复盘、可进 CI 的失败信号。
主定位：Agent 回归测试与失败治理门禁（非完整 APM、非云 tracing）
独立项目 · 框架无关 · react-agent 仅为参考集成
本项目是 Agent 发布前的失败治理门禁：接入标准轨迹后，可以判断“哪里坏了、是否比上一版变差、能否安全发版”，而不是把日志堆成一个不可行动的总分。
| 业务环节 | 项目交付 | 决策用途 |
|---|---|---|
| 运行采集 | Format B 轨迹、StepWatcher、Artifact 引用 | 保留可复盘的执行证据 |
| 失败识别 | 8 类可解释启发式、JSONL findings、统计聚合 | 定位工具、检索、验收、策略和轨迹问题 |
| 版本比较 | baseline、scan --compare、golden CI |
检查发版后失败分布是否退化 |
| 发布协作 | 可读报告、修复边界、intervention ledger | 支持 review/hold 与后续复盘 |
当前阶段： 适合本地或 CI 的低成本回归门禁。已在独立 GitHub 沙箱中复现验收失败，输出
acceptance_failed 并交给评测引擎形成 hold；这属于 external_real_sandbox，不是生产团队接入。
项目仍不是完整 APM、云 tracing 或自动修复系统；真实团队接入仍需脱敏、权限和时序存储。
Agent 团队把运行轨迹接入 trace-debugger 之后：
- 自动识别 8 类常见失败（工具报错、验收失败、搜索空结果、重复调用等）
- 形成记录 — JSONL + 可读 log，便于复盘
- 发版前对比 —
tdebug scan+--compare发现失败分布是否变差 - 结构化 findings —
--findings-out输出门禁判定 + 修复边界（Harness Health，v0.2.7+） - CI 门禁 — 黄金集 27 条 + 可选分布快照
pip install -e .
tdebug scan trajectories/ 50 \
--json-out snapshots/latest.json \
--compare snapshots/baseline.json \
--findings-out snapshots/latest_findings.json \
--project-root .
python -m pytest tests/test_failure_golden.py # CI 同款输入：Format B 轨迹 JSON · 输出：失败标签、分布表、回归 diff
完整价值说明（含已证明 / 未证明）：docs/VALUE.md
| 选 trace-debugger | 选 Langfuse / LangSmith 等 |
|---|---|
| 只需本地 JSON 轨迹 + 失败分类 | 需要生产链路 tracing、团队看板 |
| 要极低成本建 回归基线 + CI 门禁 | 要云 SaaS、采样、告警一体化 |
| 规则可解释、可 git 验证 | 深度集成特定 Agent SDK 栈 |
| 角色 | 在主场景里的作用 |
|---|---|
| Agent 开发者 | 接入轨迹 / adapter；本地 tdebug 查单条 |
| 质量 / 测试 | 维护 baseline、--compare、CI golden |
| 项目负责人 | 看失败分布与周报；判断能否发版 |
运行时 StepWatcher、单条复盘、Judge prompt
- 运行时：
FailureHarness+StepEvent— 边跑边记，见 docs/INTEGRATIONS.md - 调试：
tdebug replay、tdebug judge（导出 prompt 接 eval） - 演示：
examples/portable_harness_demo.py、examples/adapters/
| 已交付 | 说明 |
|---|---|
| 8 类启发式 + CLI | tdebug / stats / validate |
| 黄金集 + CI | 27/27 — 规则回归 |
| 发版 compare | --compare + 试点 baseline / 案例 |
| Harness Health (v0.2.7) | 五维 Agent Work Loop · 证据状态 · findings.json · intervention ledger |
| 跨 Agent Episode (v0.4.0) | 导入 evaluation-episode/v1，保留框架、Agent 版本、split 与业务终态校验证据；无需安装轨迹生产方 SDK |
| 可移植数据目录 (v0.4.0) | failure log 默认写入平台用户数据目录；TDEBUG_DATA_DIR / TDEBUG_RECORD_PATH 可覆盖 |
| 试点与当前集成 | 链接 |
|---|---|
| Phase 0–5 + 能力 manifest | docs/pilot/README.md |
| held-out 基线 7/80 | docs/pilot/CAPABILITY_HELD_OUT_RUN.md |
| 发版前决策案例 | docs/cases/regression_gate_20260730.md |
| 干预 ledger（Learning Capture） | docs/intervention_ledger.json |
| 业务证明自评 ~65% | docs/VALUE.md |
外部沙箱证据：agent-delivery-sandbox
已完成非模拟 PR 的接受、拒绝、回滚，以及 acceptance_failed -> hold 故障回流。
仍缺：真人执行耗时基线、生产团队接入复现、长期时序数据和告警闭环。
Golden CI：docs/golden_evidence_baseline.md
| 命令 | 说明 |
|---|---|
tdebug scan <dir> [N] --compare baseline.json |
主路径：批量 + 回归对比 |
tdebug scan … --findings-out findings.json |
Harness Health：门禁判定 + 修复建议 |
tdebug <file.json> |
单条分析 |
tdebug stats [jsonl] |
失败类型聚合 |
tdebug validate <file.json> |
Format B 校验 |
完整命令与选项
tdebug fixtures/failure_golden/tool_error.json --record
tdebug failures .tdebug/failures.jsonl
tdebug judge offtrack.json --prompt-out judge.txt选项：--json-out · --findings-out · --project-root · --record · --compare · --session · --schema（validate）
- Schema：schemas/agent_trajectory.schema.json
- 集成：docs/INTEGRATIONS.md · Adapters：examples/adapters/
- Episode：
evaluation-episode/v1可由不同 Agent SDK 导出后离线导入；本仓不依赖 LangGraph、OpenAI Agents SDK 或生产方 Python 包 - 运行数据：docs/PORTABILITY.md；默认不再写入已安装包目录
- Analyzer 可配置：
final_answer_markers、search_tool_names等
| 文档 | 说明 |
|---|---|
| docs/VALUE.md | 价值、主场景、业务证明缺口、下一步 |
| docs/pilot/WORKFLOW.md | 试点 scan + compare + findings 工作流 |
| docs/intervention_ledger.json | 纵向干预记录（Learning Capture） |
| schemas/findings.schema.json | findings.json 契约 |
| docs/RISKS.md | 风险与边界 |
| docs/GOLDEN_FAILURE_INDEX.md | 黄金集 |
| docs/INTEGRATIONS.md | Format B、Episode 与运行时 Hook 接入 |
| docs/PORTABILITY.md | failure log 路径和 SDK 解耦约定 |
| SECURITY.md | 数据安全 |
我们有意收窄 scope，避免对外过度承诺：
- 准确率：规则是 CI 门禁，不是判决书；
llm_offtrack曾有真实批次假阳性（6→1 校准）→ RISKS.md §1 - 业务价值：试点 Phase 0–5 + held-out 能力轨；VALUE.md · CAPABILITY_MANIFEST.md
- 数据安全：
--record落盘 query/thought；企业须 adapter 脱敏 → SECURITY.md - 定位：失败治理门禁，不替代完整 APM
Format B 支持 input_artifacts、output_artifacts 和步骤级 artifacts。 Trace Debugger 将这些字段作为轨迹引用保存和校验，不计算图片、视频或音频的语义质量。
MIT — CONTRIBUTING.md · CHANGELOG.md