zk-data-agent/skills/online-mining/SKILL.md

name, description, when_to_use, aliases, allowed_tools

name	description	when_to_use	aliases	allowed_tools
online-mining	历史版线上挖掘 skill，已停用；新任务请使用 online-mining-v2。	不再用于新任务；保留此文件仅用于查看旧 parquet 挖掘流程说明。	badcase-mining, router-mining	read_file, grep_search, glob_search

这个 skill 是历史版实现，依赖的 router-session 平台工具已经下线。 新的线上挖掘任务请使用 online-mining-v2，通过 skill 内脚本和 elk-fetch 能力完成。

使用这个 skill 处理“badcase 或标签定义 -> 挖掘策略 -> 候选召回 -> 抽样 review -> 策略迭代 -> mined dataset”的工作流。

输出目录约束

所有线上挖掘产物必须放在当前用户当前会话的 output 目录下。不要把 records、候选样本、策略说明、review 报告或中间结果写到项目根目录的 output/、tasks/、src/、skills/ 或其他源码目录。

落盘规则：

• canonical records 必须用 data_agent_export_dataset_records 导出，output_path 固定传 output/records.jsonl。工具会把它路由到当前会话 output/records.jsonl，展示给用户时以工具返回的实际路径为准。
• 不要用 write_file 手写 records、JSONL 或最终样本文件。
• 如果系统提示词提供了“会话 scratchpad 目录”，当前会话 output 目录就是该 scratchpad 的同级 output 目录。例如 .../<session_id>/scratchpad 对应 .../<session_id>/output。
• 如果需要保存策略草案、候选样本、review 报告等非 records 产物，只有在已经拿到或能从 scratchpad 推导出当前会话 output 目录的实际路径时，才可以用 write_file 写入该目录下的稳定文件名；否则只在对话中展示，不要猜测路径。
• 不要按数据集名创建子目录，不要自定义时间戳、中文专题名、随机文件名或临时脚本名。
• 用户显式指定外部输出目录时，先复述风险并确认；未确认前仍使用当前会话 output 目录。

两条分支

线上挖掘后必须先判断用户要的是哪条分支。

分支 A：线上候选直接作为数据样本

当用户说“把筛选出的数据变成样本”“拿这些线上数据做评测集”“保留这批线上 case”“导出候选样本”时，走这个分支。

流程：

1. 用 data_agent_profile_router_sessions 查看数据概貌。
2. 用 data_agent_search_router_sessions 按策略召回线上候选。
3. 用 data_agent_sample_router_candidates 抽样展示给用户 review。
4. 根据用户 review 意见形成 include/exclude/uncertain 决策和目标标签。
5. 用 data_agent_convert_router_candidates_to_records 把线上候选直接转换为 canonical records。
6. 如果用户要求落盘，用 data_agent_export_dataset_records 导出紧凑 JSONL，output_path 固定传 output/records.jsonl。不要用 write_file 手写最终 records。

这个分支不生成新 query，不调用数据生成计划工具，不调用 dataset draft 归一化工具。

分支 B：基于线上问题再生成补充数据

当用户明确说“生成/扩写/构造/造一批类似 case/补充训练数据”时，才走这个分支。

流程：

1. 先完成线上召回、抽样和 review。
2. 总结线上问题模式和需要覆盖的边界。
3. 再切换到数据生成流程，创建待 review 的 generation goal 和 generation plan。
4. 用户确认后才生成 draft，并转换为 canonical records。

如果用户只是要求“把线上数据作为样本”，不要进入这个分支。

输入假设

用户可能会提供：

• 产品或标签定义
• 线上 badcase 样例
• 期望/正确 label
• 线上预测 label
• query、tts、agent type、function name、垂域、设备、日期、模型版本或其他元数据

线上字段和允许使用的筛选条件还没有最终确定。

必要工作流

1. 读取用户提供的 badcase 或定义文件。
2. 分析 badcase 共性：
   • query 模式
   • label 混淆
   • agent/function 类型
   • 垂域
   • 如存在，分析设备/日期/模型等元数据
3. 起草带明确筛选条件的挖掘策略。
4. 当筛选条件不清或影响较大时，先请用户 review，再做宽泛线上召回。
5. 只使用批准的工具检索或请求候选数据。
6. 先抽取小批 review 样本，通常约 100 条。
7. 总结样本命中率和主要 false positive 模式。
8. 根据结果调整策略，并按需重复。
9. 最终产出以下一种或多种：
   • 线上问题评估报告
   • 专项评测集候选
   • 专项 badcase 集合
   • 训练候选数据

当前工具状态

当前先使用已有工具完成本地分析和策略起草：

• read_file
• write_file：只用于用户明确要求保存非 records 文档，并且路径已经明确位于当前会话 output 目录时；不要写项目根目录、tasks/ 或源码目录。
• edit_file：只用于修改用户明确指定的已有文档；不要用它移动或重写最终数据产物。
• grep_search
• glob_search
• ask_user_question
• data_agent_profile_router_sessions：读取 /data/online_data/router_session_parquet/date=YYYYMMDD/ 的小样本概貌，查看 schema、设备、轮次、domain、intent、func 等分布。
• data_agent_search_router_sessions：按日期、设备、domain、intent、func、query 关键词/正则、轮次数等条件召回线上 session 候选；输出命中 turn、前文 turn、req_id 和 action_json 解析结果。
• data_agent_sample_router_candidates：对召回候选做稳定抽样，并输出 review 需要的基础统计。
• data_agent_convert_router_candidates_to_records：把 review 后的线上候选直接转换为 canonical records；用于“线上数据作为样本”的分支。
• data_agent_export_dataset_records：后续把 review 后的线上候选转换为 canonical records 后落盘；默认紧凑 JSONL，固定传 output/records.jsonl，不要再用 write_file 手写 records 文件。

TODO：后续规划中的专用工具：

• analyze_badcases
• build_mining_strategy
• create_annotation_batch
• read_annotation_result
• evaluate_mining_precision
• refine_mining_strategy
• export_mined_dataset

不要手写 raw SQL，也不要用宽泛 shell 命令进行数据检索。

推荐产物

output/source_context.md
output/badcase_analysis.md
output/mining_strategy.md
output/candidate_sample.jsonl
output/review_report.md
output/mined_candidates.jsonl
output/records.jsonl

上面的 output/... 是逻辑文件名，实际路径必须是当前会话 output 目录下的路径。对 canonical records，只能通过 data_agent_export_dataset_records 写 output/records.jsonl，由工具返回实际落盘路径。

约束

• 除非批准的工具输出已经脱敏，否则不要导出敏感线上原始字段。
• 不要把第一版挖掘策略当成最终策略。
• 始终让筛选条件和抽样决策可 review。
• 只有用户明确要求生成、扩写或构造新数据时，才进入数据生成分支。
• 如果用户要求把筛选出的线上候选变成样本，必须先使用 data_agent_convert_router_candidates_to_records，不要改走 generation goal/plan。
• 任何落盘动作都必须遵守“输出目录约束”；路径不明确时，宁可只展示摘要并询问用户，也不要写到项目目录。