docs: add technical architecture guide

docs/technical-architecture/07-online-mining-v2.md

@@ -0,0 +1,177 @@
+# 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。