zk-data-agent/skills/online-replay-diff/SKILL.md

name, description, metadata

name	description	metadata
online-replay-diff	处理线上流量回放产生的 diff Excel 文件；当用户要处理线上系统回放 diff、计算 car/phone/glass 等回放数据 diff 率、整理 is_same=False 待标注样本，或复用 data-diff 的 fix_excel / diff_all / select_false 流程时使用。	short-description 计算线上回放 diff 率并输出待标注 False 样本

使用这个 skill 处理线上流量回放导出的 Excel diff 文件：把 .xls/.xlsx 清洗成稳定表头，计算 is_same，统计 diff 率，并输出待人工标注的数据。

输入形态

常见输入是线上回放导出的老式 .xls：

• 第 1 行是标题，例如 DiffCase数据。
• 第 2 行是真实表头。
• 必须包含 Query、Preview环境domain、Ptr环境domain。
• 常见文件名：car_random.xls、car_top.xls、phone_random.xls、glass_top.xls。

脚本也兼容已经清洗过的 .xlsx，会在前 10 行自动寻找真实表头。

处理口径

• is_same=True：Preview环境domain 与 Ptr环境domain 完全相同，或落在同一等价组。
• is_same=False：两边 domain 不同且不在等价组内，进入待标注输出。
• diff 率：is_same=False 行数 / 总行数。

默认等价组在 knowledge/equivalence_groups.json：

• CalendarQA / time / TimeDistance
• Chat / QA / dialogCopilot
• controlCopilot / soundboxControl / smartMiot / smartApp:defaultApp / smartApp:app-commander / camera
• music / station

如果用户给出新的等价关系，优先更新或另存一个 JSON，通过 --equiv-config 传入；不要直接在脚本里临时写死。

推荐流程

1. 确认输入文件和输出目录。用户没指定时，优先在当前工作目录下找 .xls/.xlsx，输出到 output/。
2. 确认依赖可用：

   python - <<'PY'
   import pandas, openpyxl, xlrd
   print("excel deps ok")
   PY
   

   缺依赖时，在项目虚拟环境里安装：pip install pandas openpyxl xlrd==2.0.1。
3. 运行脚本：

   python /Users/wuyang/Project/claw-code-agent/skills/online-replay-diff/scripts/process_replay_diff.py \
     car_random.xls car_top.xls \
     --output-dir output \
     --prefix car
   

4. 检查控制台 JSON 或 *_summary.md，向用户汇报每个文件和总体 diff 率。
5. 把 *_待标注_仅False.xlsx 作为待标注数据交付。

脚本

skills/online-replay-diff/
  SKILL.md
  knowledge/
    equivalence_groups.json
  scripts/
    process_replay_diff.py

process_replay_diff.py

参数：

• 位置参数：输入 .xls/.xlsx 文件或目录。
• --input-dir：输入目录；和位置参数目录等价。
• --glob：目录扫描通配符，默认 *.xls*。
• --output-dir：输出目录，默认 output。
• --prefix：输出文件名前缀，默认 replay_diff。
• --equiv-config：domain 等价规则 JSON。

输出：

• normalized/<stem>.xlsx：每个输入文件清洗首行标题后的单表。
• <prefix>_汇总结果.xlsx：每个输入文件一个 sheet，补齐固定列并追加 is_same。
• <prefix>_待标注_仅False.xlsx：只保留 is_same=False 的待标注数据。
• <prefix>_summary.json：机器可读统计。
• <prefix>_summary.csv：每文件统计表。
• <prefix>_summary.md：可粘贴到在线文档的处理摘要。

汇报格式

处理完优先这样回复：

已处理 N 个回放 diff 文件。

- car_random：总行数 7,285，diff 416，diff 率 5.7104%
- car_top：总行数 12,260，diff 485，diff 率 3.9560%
- 总体：总行数 19,545，diff 901，diff 率 4.6099%

待标注数据：/abs/path/output/car_待标注_仅False.xlsx
汇总结果：/abs/path/output/car_汇总结果.xlsx

如果脚本失败，先检查：

• 是否缺 xlrd，老式 .xls 必须用它读。
• 是否找不到真实表头；前 10 行必须能看到 Query、Preview环境domain、Ptr环境domain。
• 是否输入了脚本刚产出的汇总文件，导致重复处理输出文件。