docs: add subagent guidance and replay diff skill

2026-06-12 14:39:07 +08:00
parent c2f08821b9
commit 77d360c1e8
7 changed files with 840 additions and 0 deletions
@@ -0,0 +1,107 @@
+---
+name: online-replay-diff
+description: 处理线上流量回放产生的 diff Excel 文件；当用户要处理线上系统回放 diff、计算 car/phone/glass 等回放数据 diff 率、整理 is_same=False 待标注样本，或复用 data-diff 的 fix_excel / diff_all / select_false 流程时使用。
+metadata:
+  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. 确认依赖可用：
+   ```bash
+   python - <<'PY'
+   import pandas, openpyxl, xlrd
+   print("excel deps ok")
+   PY
+   ```
+   缺依赖时，在项目虚拟环境里安装：`pip install pandas openpyxl xlrd==2.0.1`。
+3. 运行脚本：
+   ```bash
+   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` 作为待标注数据交付。
+
+## 脚本
+
+```text
+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`：可粘贴到在线文档的处理摘要。
+
+## 汇报格式
+
+处理完优先这样回复：
+
+```text
+已处理 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`。
+- 是否输入了脚本刚产出的汇总文件，导致重复处理输出文件。