zk-data-agent/docs/technical-architecture/07-online-mining-v2.md

07. online-mining-v2 Skill 实现

1. 定位

online-mining-v2 用于从线上 ELK 日志中挖掘 case，并把候选样本转换成 product-data 兼容的标准数据。

典型链路：

线上挖掘需求
  -> 明确目标标签、complex、筛选特征
  -> 探索 ELK 表字段
  -> 搜索候选
  -> 抽样 review
  -> 调整策略
  -> 直接转 canonical records
  -> 或转 product-data 生成补数

位置：

skills/online-mining-v2/SKILL.md
skills/online-mining-v2/knowledge/
skills/online-mining-v2/scripts/

2. 能力组织

online-mining-v2 不新增平台注册工具。它把能力放在 Skill 目录下，通过 python_exec.script_path 执行。

scripts/
  online_mining_common.py
  elk_profile_index.py
  elk_search_cases.py
  elk_fetch_by_request_ids.py
  elk_join_request_logs.py
  build_dataset_draft.py
  build_online_records.py

这样做的原因：

• ELK 查询逻辑属于该 Skill 的业务能力。
• 迁移到其他 Agent 时可以直接跑脚本。
• 平台只需要提供通用 python_exec 和 python_package。

3. 默认数据源

当前重点支持两类索引：

pre-processing*
  前处理日志。
  适合拿模型 prompt、模型输出、候选 domain、excellent_domains_result。

arch-flat-nlp-log-f-*
  主 NLP 日志。
  适合拿 query、domain、func、request_id、device_id、device、tts/text/to_speak。

Skill 文档中会引导 Agent：

• 先用 elk_profile_index.py 看字段和样本。
• 再用 elk_search_cases.py 根据 query/domain/model output 搜索。
• 必要时用 request_id 做双表 join。

4. 和 Agent Loop 的关系

这个 Skill 的交互不是“一次查询结束”，而是策略迭代：

用户描述需求
  -> Agent 整理目标标签和筛选特征
  -> 如缺目标标签或字段，先问用户
  -> python_exec 调 elk_profile_index.py
  -> 模型观察字段和样本
  -> python_exec 调 elk_search_cases.py
  -> 模型观察候选质量
  -> 抽样展示给用户 review
  -> 用户说哪里不对
  -> 调整 filters / regex / domain / model output 条件
  -> 再搜索

Agent loop 的价值在这里很明显：每次工具结果都会进入上下文，模型可以基于真实候选调整策略。

5. 两条分支

online-mining-v2 最重要的设计是强制区分两个分支。

5.1 直接线上样本分支

适用：

用户想把线上筛出来的真实 case 作为评测集或专项集。

行为：

不生成新 query。
不进入 product-data generation plan。
用 build_online_records.py 直接转 canonical records。

典型输出：

output/records.jsonl
output/records.csv

5.2 补充生成分支

适用：

用户想围绕线上问题扩写更多类似 case。

行为：

先分析线上 badcase。
整理错误类型和覆盖目标。
再转 product-data 的 generation goal / plan / draft / records 流程。

这条边界避免了旧流程里出现的错误：用户只是想“把候选转样本”，Agent 却误走“生成新数据”。

6. 和 product-data 的关系

online-mining-v2 后处理复用 product-data 的标准：

canonical record v1
records.jsonl
records.csv
training.jsonl
eval_planning.csv

复用脚本：

skills/product-data/scripts/normalize_dataset_draft.py
skills/product-data/scripts/validate_dataset_records.py
skills/product-data/scripts/export_dataset_records.py
skills/product-data/scripts/export_training_jsonl.py
skills/product-data/scripts/export_planning_eval_csv.py

因此线上挖掘和产品定义生成最终可以进入同一套数据格式。

7. 设计边界

online-mining-v2 负责：

• ELK 字段探索。
• ELK 条件搜索。
• request_id 补全。
• 候选样本 review。
• 线上候选转 canonical records。

不负责：

• 定义 canonical record 标准。
• 生成全新补数。
• 判断复杂标签知识。
• 训练数据提交。

这些分别交给 product-data、label-master 或后续数据仓库 Skill。