Tracely-ai - 把生产环境中的失败轨迹冻结成可回放的回归测试

Tracely-ai 是一个面向 AI Agent 的可观测与回归测试工具，项目自述的定位是「trace 原生的 CI/CD」。它要解决的问题是：多数 agent 可观测工具止步于仪表盘——你能看到 agent 坏了，但接下来呢？据项目说明，常见的评测工具要求使用者手工编写数据集，而那份数据集只是对「可能坏在哪里」的猜测；Tracely 的思路是把生产环境里真实失败的那次运行直接冻结成测试。它适合已经在生产环境跑 agent、并且希望把线上故障转化为可重复验证的回归用例的团队，也适合需要为 agent 变更设置合并前卡点（CI gate）的工程团队。

维护者与状态

项目由 jwuthri-cloud 维护，仓库创建于 2026-10-11，最后提交时间为 2026-10-25。截至 2026-10-26 的数据读取时间，仓库获得 1183 个星标。项目尚无正式 release，也就是说目前没有可引用的版本号，使用者只能跟随仓库主干的代码状态。

许可证为 MIT。项目另有一个产品站点，见下文「使用入口」。

主要能力

以下能力均据项目 README 自述整理，未经独立验证。

• 分层观测：trace 通过标准 OTLP 接入，agent 语义字段（如 agent.id、conversation.id、turn、step）被提升为一级索引列，使运行按会话线程聚合，而不是散成扁平的 span 列表。瀑布视图展示 agent → thinking → skill → generation → hand-off 的层级，失败 span 标红并附输入输出。
• 评测器即列：评测器不是独立标签页，而是 trace 表格上的列，可在会话、运行或 span 级别打分，结果实时通过 SSE 流入表格。评测器分两类：无需模型的结构化检查，以及 LLM-as-judge。
• 失败聚类与分诊：线上评测器对每条落地的运行打分，失败随后按结构与语义聚类，把大量失败运行收敛成「一个带计数的 issue」，并可为每个簇建议本可捕获它的评测器。
• 回归用例：一键把失败 trace 提升为封闭用例，把记录的输入、工具与 LLM 输出打包为 fixture，并附带 fail-to-pass 契约——用例必须在旧代码上失败、在修复后通过，否则该提升不被信任。
• 多轮场景：多轮行为用 scenario 表达，可以是脚本化对话，也可以是由红队模型自行发挥的对抗性目标（目标达成即判 FAIL）。
• CI 卡点：测试套件在 CI 中针对录制 fixture 回放，项目称其为确定性、离线、无需 API key 且无模型开销；tracely gate 以非零退出码结束，并写入 commit status 与 PR 评论。
• 告警流：规则由「何时触发」与「发生什么」两半组成，在画布上绘制；支持条件分支、Slack、邮件、带自定义方法与请求头的 webhook、一个可供后续步骤使用的 LLM 步骤，以及 Python 表达式。也可用应用内助手描述需求，由它把流程画到画布上。
• 趋势与评测器校准：每日失败率与 gate 通过率、延迟分位、token 花费、按 agent 的跨指标元分析；校准页可把评测器判定与人工复核对照，查看各评测器的一致率，从而在让某个评测器参与 gate 之前发现它是否过度报警。
• 其他组件：应用内助手（⌘J）、把 API 兼作 MCP 端点（/mcp）以便编码 agent 驱动工作区、三种鉴权模式（dev / local / clerk）、组织与工作区、席位与 API key，以及队列深度、worker 存活、接入新鲜度等运维自检。

使用入口

代码仓库地址：jwuthri-cloud/Tracely-ai；产品站点：tracely-ai.com。

据 README，最快的上手方式是用 Docker Compose 起整套栈，前置条件只有 Docker 与 Docker Compose：

git clone https://github.com/jwuthri-cloud/Tracely-ai && cd Tracely
docker compose --profile demo up -d --build --wait
open http://localhost:3001

该命令会拉起 ClickHouse、Postgres、Redis 与 MinIO，执行全部迁移，播种默认项目与接入密钥（tracely_dev_key），并填充 trace、聚类、用例与 gate 数据，使应用打开时不是空壳。默认宿主端口为 web :3001、backend :8000，可用 TRACELY_WEB_PORT / TRACELY_BACKEND_PORT 改写。

本地开发模式（热重载）另需 uv 与 Node 20+ / pnpm，流程为复制 .env.example 后依次执行 make infra-up、make install、make migrate、make seed，再分别启动 backend 与 workers。README 特别提示：Celery worker 不做热重载，改动后需重启容器。

许可与限制

许可证为 MIT，可据此判断使用与分发条件，具体以仓库 LICENSE 文件为准。

据项目说明，需要注意的边界包括：项目尚无正式 release，接口与部署方式可能随主干变动；完整栈依赖 Docker Compose，并会启动 ClickHouse、Postgres、Redis、MinIO 四个基础组件，对本地资源有一定要求；CI 回放依赖事先录制的 fixture，因此其「离线、无模型开销」的前提是失败 trace 已被成功提升为用例；评测器校准功能的存在本身也说明 LLM-as-judge 的判定需要人工对照，不宜直接当作发布卡点。README 中提到的近期计划与长期路线图属于规划内容，不构成已交付能力。