🔍 Agent 轨迹数据质检工具

针对 Agent 轨迹生产项目的自动化质检工具，覆盖 Claude Code 原生 / OpenClaw / Hermes（会话导出） 三种真实数据格式，提供网页图形界面与命令行两种用法。纯 Python 标准库实现，无需安装任何第三方依赖。

✨ 特性

• 零依赖：只用 Python 3.9+ 标准库，同事拿到文件夹双击 start.bat 即可使用
• 试卷式配置：单选题（严格度档位、数据格式）、多选题（检查项开关、检测类型）、填空题（各类阈值）、标签输入（模型白名单、关键词）
• 上传灵活：支持单个 .json / .jsonl，或包含多条轨迹的 .zip（可多文件）
• 逐项报告：每项给出 ✅通过 / ❌失败 / ⚠️警告，问题定位到具体行/条，含指标统计
• 一票否决：致命项任一失败即判整条轨迹不通过；警告项只提示
• 批次汇总：通过率、格式/模型分布、高频失败项、跨文件指令查重（反模板化）
• 报告导出：JSON 报告下载、浏览器打印 / 另存 PDF
• 数据不出本机：全程本地运行，不联网、不上传

🚀 快速开始（网页）

Windows

双击项目根目录的 start.bat，浏览器会自动打开 http://127.0.0.1:8765/。

macOS / Linux

./start.sh

然后在页面上：

1. 选择严格度档位（宽松 / 标准 / 严格）与数据格式（默认自动识别）
2. 勾选检查项、按需调整阈值
3. 上传文件（单文件或 zip，可多选）
4. 点击「开始质检」，查看报告

关闭命令行窗口即停止服务。

⌨️ 命令行用法

# 质检单个文件（自动识别格式，标准档）
python -m qc.cli 路径/xxx.jsonl

# 质检整个目录或一个 zip
python -m qc.cli 路径/某批次目录
python -m qc.cli 批次.zip --preset strict

# 指定格式 / 严格度 / 导出 JSON 报告
python -m qc.cli 轨迹.jsonl --format openclaw --preset loose --report report.json

# 只看每条结论
python -m qc.cli 目录/ --quiet

退出码：0 全部通过；1 存在不通过；2 输入路径无效（可用于 CI 卡口）。

📋 质检项一览（共 27 项）

分组	检查项	默认级别
结构合法性	文件可解析性、角色合法性、异常连续角色、工具调用-结果配对、消息块结构合法、截断/未完成检测、Token 用量字段	多为致命，连续角色/用量为警告
模型合规	模型一致性、模型白名单、推理强度合规	一致性/白名单致命
思考过程	思考密度、思考内容充实度、思考签名完整性	密度/签名致命，充实度警告
交互完整性	最少交互轮次、任务收尾完整	致命
工具调用	工具调用错误率、字段完整性、调用总数范围、工具多样性、重复调用检测、危险操作检测	错误率/字段致命，其余警告
内容质量	垃圾/占位输入、敷衍短回复、敏感信息泄露、语言比例	垃圾输入/泄密致命，语言比例默认关
批次汇总	批次内指令重复率、压缩包/批次完整性	警告

所有阈值、白名单、关键词均可在网页调整；每个检查项可单独开关，也可把某项在「致命/警告」间调整（配置 JSON 中设置 severity）。

📁 支持的数据格式

• Claude Code 原生转录（.jsonl）：每行事件，type=user/assistant；同一逻辑回合（相同 message.id）被拆成 thinking/text/tool_use 多行时会自动合并；thinking 块内嵌 signature；工具结果为 user 消息中的 tool_result 块。
• OpenClaw 事件流（.jsonl）：session/model_change/message/compaction 事件；内嵌 role=user/assistant/toolResult，块类型 toolCall/thinking/text；自动识别 stopReason=error/aborted 失败重试轮与 isError 工具结果。
• Hermes / 会话导出（.json 或单行 .jsonl）：顶层对象含 messages；OpenAI 风格 tool_calls + role=tool；思考取自 reasoning_details / reasoning_content / reasoning；强度取自 model_config.reasoning_config.effort。

格式识别为自动完成，一般无需手动指定。解析失败的单个文件会被隔离上报，不会中断整批质检。

🧪 生成演示样例

python samples/generate_samples.py

会生成 1 个不合格样例（集中展示多项失败与行号定位）和 2 个合格样例，可直接上传体验。

📂 目录结构

trace-checking-tool/
├─ start.bat / start.sh      # 一键启动网页
├─ qc/
│  ├─ specs.py               # 检查项目录与默认配置（前端表单的唯一数据源）
│  ├─ adapters.py            # 三种格式 → 统一轨迹模型
│  ├─ loader.py              # json/jsonl/zip/目录 加载
│  ├─ checks.py              # 全部检查项实现
│  ├─ runner.py / batch.py   # 单条/批次编排与判定
│  ├─ webapi.py              # 前端配置归一化
│  ├─ serve.py               # 零依赖本地网页服务
│  └─ cli.py                 # 命令行入口
├─ static/                   # 网页前端（index.html / app.js / styles.css）
└─ samples/                  # 样例生成脚本

🔧 判定规则

• 每个启用的致命项（fatal）出现 fail → 该条轨迹不通过
• **警告项（warning）**失败只提示，不影响通过
• skip 表示该项不适用（如非 Claude 格式不产出签名、Hermes 不提供逐条 usage）或未启用
• 批次的指令查重、压缩包完整性为批次级结论，单独展示

❓ 常见问题

• 提示找不到 Python：安装 Python 3.9+ 时勾选 Add Python to PATH。
• 端口被占用：会自动改用 8766 起的其他端口，以命令行窗口显示的地址为准。
• 想改默认模型白名单/阈值：直接在网页调整；或复制网页导出的配置结构，编辑后通过 CLI --config 传入。