TraceCrate：本地优先的 AI 智能体轨迹工作台

TraceCrate

TraceCrate 把你选中的文件处理成可搜索的时间线、记录下来的指标、启发式诊断（heuristic diagnostics）以及并排对比。无后端、无遥测（telemetry）、无账号、无 API 密钥。它只读取 trace，不会运行智能体（agent），也不会执行记录下来的命令。

打开实时演示、查看 v0.1.0 版本，或者前往 GitHub 贡献代码、查看源码。不用安装任何东西就能浏览合成的运行结果，也可以在本地跑起来。

30 秒走完一遍流程

打开托管的演示，按下面的引导操作即可。本地使用需要 Node.js ≥ 22.12（推荐 24）和 npm：

git clone https://github.com/FankChen/tracecrate.git
cd tracecrate
npm ci
npm run dev

本地使用时，打开 Vite 打印的地址就行。安装时间不计入 30 秒流程。

- 0–10 秒，两个合成的分页运行结果会自动加载。在 Timeline 中打开一个工具事件，按事件类型搜索或筛选。
- 10–20 秒，打开 Insights，再打开 Compare，检查记录下来的差异。「Baseline」和「optimized」只是演示用的标签，不是实测出来的改进。
- 20–30 秒，选择 Export report → Structure only → Show redacted preview，然后下载 JSON 或独立的 HTML 报告。分享前请审阅完整下载内容。

不需要安装 Claude/Codex，也不需要运行智能体命令。要用你自己的数据，就用 Choose files 或直接拖放受支持的文件。Claude 会话文件属于隐私内容，请只选择你被授权查看的文件，TraceCrate 不会扫描智能体目录。切勿把真实的会话记录作为样例（fixtures）上传贡献。

能做什么

- 搜索、按事件类型筛选、相对时间、工具输入/输出、元数据，每页 100 条事件。
- 看证据，不看凭空的确定性，包括报告的 token 数、显式错误、以及存在时的耗时；缺失的值保持未知，不做成本估算。
- 发现规律，包括显式的工具错误、过长的工具耗时、巨大的输出，以及重复出现的同名/同输入。启发式方法不能确立原因或意图。
- 对比两个会话的指标差异（B − A）和工具调用次数，这是描述性的，不是受控基准测试。
- 默认严格的仅结构导出（strict structure-only export），可选的尽力而为模式脱敏（best-effort pattern redaction）。HTML 报告不包含脚本或外部资源，原生 JSON 可以被再次导入。
- 工作流保持本地，文件读取与解析在 Web Worker 里进行，会话驻留在内存中，并支持 clear-session 取消。重新加载会丢弃已导入的会话、恢复演示，下载下来的文件保留在磁盘上。

格式支持 · 只是子集，不是全盘接收

| 格式 | 支持的输入 | 重要边界 |
| --- | --- | --- |
| Claude Code | 普通消息的 JSONL；文本、工具调用/结果、选定的 system/result 记录 | 忽略部分流式增量；私有会话变体可能有所不同 |
| Codex | 包含 session_meta、turn_context、response_item、选定 event_msg 的 rollout JSONL | 不支持任意 codex exec --json 事件；不导入推理/增量内容 |
| OTLP JSON | resourceSpans → scopeSpans → spans，以及选定的 GenAI 属性 | 不支持 protobuf、采集器端点、完整 OTLP 或 MCP 会话记录 |
| TraceCrate native | 单一经过验证的 schemaVersion: 1 JSON 报告 | 有边界的 schema；未知字段会被剥离；JSON 导出是用于分享的转换结果，并非原始备份 |参见 formats、合成样例以及公开的上游参考资料。

Usage.input 包含 cacheRead 和 cacheWrite，这些是子计数，不是叠加项。报告的总 token 数 = input + output。

限制

- 每个文件 20 MiB UTF-8，最多 20,000 条输入记录与归一化事件，嵌套深度 60；
- 单次选择最多 5 个文件，内存中最多 10 个会话（含演示）；
- 必须支持 Web Worker；
- 导入是整体读取文件，不是流式读取；导出与分析仍使用 UI 线程；
- 详情/预览渲染上限 50,000 字符，不是下载报告的全部内容。

参见 architecture。

隐私是边界，不是保证

该应用没有 trace 上传或遥测的通路。但环境本身和导出动作未必都安全。浏览器扩展、被入侵的浏览器/设备，以及被篡改的托管代码，都可能读取数据。即使是静态托管，服务器仍会收到常规的请求元数据，比如 IP 地址和 User-Agent。

Structure-only 通过严格的允许列表（allowlist）移除任意自由文本、原始标识符/名称、输入、输出以及模型名称。事件关系、状态、token 指标以及时间戳/耗时会保留，这些仍可能泄露敏感信息。

Pattern redaction 保留文本，但可能遗漏机密信息。

这两种模式都不能保证匿名化，请逐一检查完整下载内容的每个字段。清除内存并不等同于安全擦除。请阅读 privacy 与 export 详情，以及 security reporting。

开发与发布状态

- npm run check 运行 lint、单元测试以及生产构建。
- npm run test:e2e 调用 Playwright，浏览器二进制文件需单独安装。参见 contribution checks。

已验证的发布 · 2026-09-10 · v0.1.0

在已测试的提交 52d9ae9b73f815c264a3eb39f5fc3eedc5cb9715 上创建。

CI 运行 34462095959 通过了 lint、TypeScript/构建、107 项单元测试以及 36 项桌面 Chromium / Pixel 7 模拟浏览器测试。记录的 core/adapters 行覆盖率为 96.58%（不含 UI 覆盖率）。

实时验证

Pages 运行 34462098830 在构建、部署，以及针对真实公网站点的 Playwright 冒烟测试中均取得成功，覆盖子路径资源、页面加载后用合成 Claude 样例做的冷启动离线首次导入、默认的 structure-only HTML 下载，以及无 console/页面错误。上方的截图来自其下载的证据文件。参见