# 07. online-mining-v2 Skill 实现

![online-mining-v2 Skill 实现](assets/07-online-mining-v2.png)

## 1. 定位

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

典型链路：

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

位置：

```text
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` 执行。

```text
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. 默认数据源

当前重点支持两类索引：

```text
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 的交互不是“一次查询结束”，而是策略迭代：

```text
用户描述需求
  -> 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 直接线上样本分支

适用：

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

行为：

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

典型输出：

```text
output/records.jsonl
output/records.csv
```

### 5.2 补充生成分支

适用：

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

行为：

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

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

## 6. 和 product-data 的关系

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

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

复用脚本：

```text
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。