zk-data-agent/docs/data_agent_new_tools.md

下面是中文翻译：

Data Agent 新工具提案

本文档列出了 data-agent 改造中建议新增的工具。范围刻意聚焦在第一阶段实现：数据 schema、生成、校验、格式转换、评审，以及后续在线挖掘。

设计原则

• 优先使用窄口径的数据工具，而不是通用 shell、SQL 或临时代码。
• 工具应该稳定数据格式和可重复操作。
• 开放式推理、聚类解释和生成策略可以保留在 Agent loop 中；工具负责提供结构化输入、校验和可重复转换。
• 每个工具都应该返回机器可读的 metadata，以及人类可读的摘要。
• 生成的数据集必须在导出或持久化前完成校验。

优先级

• P0：短期立即实现所必需。
• P1：很快需要，但可以在第一条 schema / 生成链路跑通后再加。
• P2：用于在线挖掘或生产级加固。

P0：数据集 Schema 与格式工具

这些是基础工具，避免 Agent 手写脆弱的格式转换逻辑。

数据格式设计分两层：

1. 标准数据记录层：验证数据要素是否完整。该层回答一个 record 是否具备所需的对话轮次、query、tts 和最终 label。数据生成和在线挖掘工具应该直接产出这一标准层，或者在进一步使用前先 normalize 到这一层。
2. 导出格式层：把标准 records 转换成固定的下游格式。一旦标准 metadata 格式稳定，转换到 training JSONL、prompt/eval CSV、review tables、display markdown 和其他消费格式，就应该成为确定性的工具逻辑。

实际规则是：

generation/mining output
  -> canonical records
  -> validation
  -> dedup/review
  -> deterministic exports

Agent 应该负责理解数据意图和编写计划，但 schema 校验和格式转换应该由工具负责。

标准 Record 层

这一层定义生成或挖掘数据的内部事实源。第一版应该足够严格，避免缺失关键元素；同时也要足够灵活，以支持单轮和多轮对话。

建议的标准 record 结构：

{
  "record_id": "optional-stable-id",
  "conversation": [
    {
      "query": "...",
      "tts": "...",
      "metadata": {}
    }
  ],
  "label": {
    "type": "function_or_agent",
    "name": "...",
    "arguments": {}
  },
  "source": {
    "type": "generated|mined|eval_error|manual",
    "task_id": "...",
    "notes": "..."
  },
  "metadata": {}
}

待确认的 schema 问题：

• tts 是否应该每一轮都必填？还是当源数据没有 TTS 时可以为空？
• label type 是否应该标准化为 function 和 agent 这样的 enum？
• label arguments 应该是必填、可选，还是由目标格式决定？
• record-level metadata 是否应该包含 model version、device、date、source table、mining strategy、reviewer decision 等信息？

validate_dataset_records

用途：校验 records 是否符合标准数据 schema。

建议输入：

{
  "input_path": "artifacts/candidates.jsonl",
  "schema_name": "router_conversation_v1",
  "max_errors": 50
}

建议输出：

{
  "valid": true,
  "record_count": 120,
  "error_count": 0,
  "errors": []
}

说明：

• 检查多轮对话、query、tts、最终 label 等必填字段。
• 应同时支持单轮和多轮 records。
• 应在生成 / 挖掘之后运行，并在 dedup、export 或 persistence 之前运行。
• 这是完整性和结构校验，不是下游格式校验。

normalize_dataset_records

用途：把历史数据、生成数据、挖掘数据或 eval result 中略有差异的 record 形态转换成标准 record schema。

建议输入：

{
  "input_path": "context/raw_cases.csv",
  "output_path": "artifacts/normalized_cases.jsonl",
  "source_format": "auto",
  "schema_name": "router_conversation_v1",
  "field_mapping": {
    "query": "query",
    "tts": "tts",
    "label": "correct_label"
  }
}

说明：

• 现有 eval 文件、文档和表格可能存在格式差异，因此这个工具有用。
• 不应该过度猜测。如果必填字段含义不明确，应返回 mapping error，让 Agent 向用户确认。
• 对于在线挖掘，挖掘工具最好直接输出标准 records。这个 normalizer 主要适合 legacy 文件和用户提供的表格。

generate_record_ids

用途：为标准 records 填充稳定的 record_id。

建议输入：

{
  "input_path": "artifacts/normalized_cases.jsonl",
  "output_path": "artifacts/normalized_cases.with_ids.jsonl",
  "id_strategy": "hash"
}

说明：

• 稳定 ID 会让 review、dedup、export manifest 和 git diff 更容易处理。
• 默认策略可以对标准化后的 conversation 和 label 做 hash。

数据集质量层

这些工具在导出前作用于标准 records。

dedup_dataset_records

用途：导出前删除或标记重复、近重复 records。

建议输入：

{
  "input_path": "artifacts/eval_candidates.jsonl",
  "output_path": "artifacts/eval_candidates_deduped.jsonl",
  "keys": ["conversation.query", "label.name"],
  "mode": "flag"
}

说明：

• 在 eval set 中，重复样本会抬高指标，或让专项集看起来比实际更大。
• 在 training set 中，重复样本可能会无意中加重某种 pattern 的权重。
• MVP 可以先从精确重复检测开始。近重复检测可以放到 P1 / P2。
• mode="flag" 比直接删除更安全，因为 reviewer 可以检查哪些内容被移除了。

导出格式层

convert_dataset_format

用途：把已校验的标准 records 转换成一个批准的下游格式。

建议格式：

training_jsonl
eval_prompt_csv
review_table_csv
markdown_preview

建议输入：

{
  "input_path": "artifacts/eval_candidates.jsonl",
  "output_path": "artifacts/eval_candidates.csv",
  "target_format": "eval_prompt_csv",
  "schema_name": "router_conversation_v1"
}

说明：

• 这个工具和 validation 分开，因为不同转换目标可能有不同的列要求和布局要求。
• 它不应该改变语义内容。如果目标格式无法表达某个字段，工具应该在 metadata 中说明哪些字段被省略。

render_dataset_preview

用途：把 records 渲染成人类评审用的格式。

建议输入：

{
  "input_path": "artifacts/eval_candidates.jsonl",
  "output_path": "artifacts/eval_candidates_preview.md",
  "max_records": 50,
  "group_by": "label"
}

说明：

• Review 格式应该对人友好，但不应被当作训练 / 评测的标准格式。

export_dataset

用途：把已校验的标准 records 导出为一个或多个批准的 artifact 文件，并写入 export manifest。

建议输入：

{
  "input_path": "artifacts/eval_candidates_deduped.jsonl",
  "exports": [
    {
      "target_format": "training_jsonl",
      "output_path": "artifacts/export/train.jsonl"
    },
    {
      "target_format": "eval_prompt_csv",
      "output_path": "artifacts/export/eval.csv"
    },
    {
      "target_format": "markdown_preview",
      "output_path": "artifacts/export/review.md"
    }
  ],
  "require_valid": true
}

说明：

• 这个工具可以在写入最终输出前内部调用 validation。
• 应生成 manifest，包含 record 数量、schema version、export paths 和 validation status。
• 这是基于确定性转换的便利性 / 编排工具。调试时，仍然可以直接调用 convert_dataset_format。

P1：Eval 输入与错误分析工具

这些工具支撑任务 1：利用现有 eval errors 规划并生成针对性数据。

load_eval_results

用途：从 CSV、JSONL 或类 spreadsheet 导出文件中加载 eval result，并转换成标准内部表。

建议输入：

{
  "input_path": "context/eval_errors.csv",
  "output_path": "artifacts/eval_results.normalized.jsonl",
  "field_mapping": {
    "query": "query",
    "expected_label": "correct_label",
    "predicted_label": "model_label"
  }
}

说明：

• 应支持显式 field mapping。
• 可以支持 field_mapping="auto"，但应返回低置信度 mapping warning，而不是静默猜测。

profile_error_cases

用途：从 eval errors 中产出结构化统计和切片分析。

这是比全自动聚类更安全的第一版。

建议输出：

{
  "total_errors": 328,
  "by_expected_label": {},
  "by_predicted_label": {},
  "confusion_pairs": [],
  "top_terms": [],
  "sample_records": []
}

说明：

• 这个工具给 Agent 提供分析证据。
• 随后 Agent 可以写 artifacts/error_analysis.md。

cluster_error_cases

用途：把相似错误样本分组，便于分析。

处置：P1，但应被视为辅助聚类，而不是最终事实。

难点：

• 输入文件格式不一致。
• 好的 cluster 经常需要人工解释。
• 之前的聚类是交互式的，这一点应该保留。

建议设计：

{
  "input_path": "artifacts/eval_results.normalized.jsonl",
  "output_path": "artifacts/error_clusters.json",
  "features": ["query", "expected_label", "predicted_label"],
  "method": "heuristic",
  "max_clusters": 20,
  "include_examples": 10
}

推荐 MVP：

• 从 profile_error_cases 开始，再基于 confusion pair、label、keywords 或显式字段做简单分组。
• 由 Agent 在 markdown 中产出 cluster 名称和假设。
• 由人工评审、合并、拆分 clusters。

summarize_error_clusters

用途：把 cluster 数据转换成人类可评审的报告。

与 cluster_error_cases 的关系：

• cluster_error_cases 创建结构化分组和代表样例。
• summarize_error_clusters 把这些分组转换成报告：cluster 标题、疑似根因、示例、建议的数据生成方向。

建议输入：

{
  "clusters_path": "artifacts/error_clusters.json",
  "output_path": "artifacts/error_cluster_summary.md"
}

说明：

• 这个工具可能部分由 Agent 编写。工具可以渲染基础确定性报告；Agent 可以在其上补充推理。

create_review_packet

用途：把分析结果打包成一个紧凑的人类评审 artifact。

建议输入：

{
  "inputs": [
    "artifacts/error_analysis.md",
    "artifacts/error_cluster_summary.md"
  ],
  "output_path": "artifacts/review_packet.md",
  "questions_path": "memory/open_questions.md"
}

说明：

• 在调用 ask_user_question 前有用。
• 可以让交互式评审始终基于文件内容展开。

P1：数据规划与生成工具

这些工具支撑任务 1 和任务 2。

generate_data_plan

用途：基于已评审的错误 clusters 或标签定义创建结构化生成计划。

建议输入：

{
  "analysis_path": "artifacts/error_cluster_summary.md",
  "constraints_path": "context/data_requirements.md",
  "output_path": "artifacts/generation_plan.json"
}

建议输出形态：

{
  "batches": [
    {
      "name": "hard_negative_fast_direct",
      "target_label": "SLOW_FILTER_RANK",
      "count": 50,
      "scenario": "...",
      "requirements": [],
      "negative_constraints": []
    }
  ]
}

说明：

• 可以由 Agent 生成，再由工具校验。
• 短期内，这个工具可以先负责校验和规范化计划，而不是完整生成计划。

validate_data_plan

用途：校验 generation plan 是否完整、可执行。

说明：

• 检查数量、标签、必填字段、schema names 和不支持的指令。
• 有助于保持交互式 plan review 稳定。

generate_dataset_records

用途：根据已校验的 plan 和 data schema 生成 records。

建议输入：

{
  "plan_path": "artifacts/generation_plan.json",
  "output_path": "artifacts/generated_candidates.jsonl",
  "schema_name": "router_conversation_v1",
  "generation_mode": "llm_assisted"
}

说明：

• 如果内部使用 LLM，工具输出仍然需要校验。
• 更简单的 MVP 是：Agent 生成候选 JSONL，然后调用 validate_dataset_records。
• 长期看，这个工具可以负责生成，减少格式漂移。

validate_label_coverage

用途：检查生成数据是否覆盖了计划要求的 labels、scenarios 和 boundary types。

建议输入：

{
  "dataset_path": "artifacts/generated_candidates.jsonl",
  "plan_path": "artifacts/generation_plan.json",
  "output_path": "artifacts/coverage_report.md"
}

说明：

• 这和 schema validation 不同。
• Schema validation 问的是：“record 结构是否合法？”
• Coverage validation 问的是：“是否生成了计划中想要的数据？”

P1：产品或标签定义工具

这些工具支撑任务 2。

load_definition_document

用途：把产品或标签定义文档加载为标准 markdown / text。

建议输入：

{
  "input_path": "context/product_definition.md",
  "output_path": "artifacts/definition.normalized.md"
}

说明：

• 可以支持 markdown、txt、csv，之后按需支持 docx / pdf。

extract_label_definition

用途：抽取候选标签定义、正例、反例和模糊边界。

建议输出：

{
  "labels": [],
  "positive_rules": [],
  "negative_rules": [],
  "ambiguous_boundaries": [],
  "examples": []
}

说明：

• 可以由 LLM 辅助，但应输出结构化 JSON 和 markdown summary。

render_label_boundary_summary

用途：基于抽取出的定义创建可评审的标签边界摘要。

建议输出：

artifacts/label_boundary_summary.md

说明：

• 应接入 ask_user_question 或人工评审流程。

P2：在线挖掘工具

这些工具支撑任务 3。应在 schema / generation 工具稳定后再添加。

analyze_badcases

用途：总结输入 badcases 的共性特征。

建议输出：

• 常见 query patterns
• 涉及 labels
• 候选过滤条件
• 高风险 / 模糊字段
• 代表样例

build_mining_strategy

用途：把 badcase 分析转换成结构化在线数据搜索策略。

建议输出形态：

{
  "filters": {
    "date_range": {},
    "device": [],
    "agent_type": [],
    "keywords": [],
    "regex": [],
    "domain": []
  },
  "sampling": {
    "limit": 100,
    "method": "diverse"
  }
}

说明：

• 大规模查询前，应支持人工评审。

search_online_sessions

用途：通过受控、可审计的 filters 查询线上 sessions。

说明：

• Agent 不应该写原始 SQL。
• 工具 schema 应只暴露被批准的字段和过滤操作符。
• 敏感字段应在工具边界完成脱敏。

sample_online_candidates

用途：从检索到的线上 sessions 中采样候选样本，供评审使用。

说明：

• 支持“先标注 100 条”的循环。
• 应包含确定性 sampling metadata，保证可复现。

create_annotation_batch

用途：从采样候选中创建 review / annotation packet。

说明：

• MVP 可以是本地 markdown / CSV。
• 之后可以接入标注系统。

read_annotation_result

用途：把人工评审结果读回 task workspace。

说明：

• 应规范化 review labels 和 comments。

evaluate_mining_precision

用途：评估当前 mining strategy 的精度是否足够。

建议输出：

• 已评审数量
• 正样本数量
• Precision
• 主要误召 pattern
• 推荐的下一步过滤条件调整

refine_mining_strategy

用途：根据评估结果生成修订版 mining strategy。

说明：

• 初期可以保留为 Agent 编写；工具负责校验 strategy JSON。

export_mined_dataset

用途：把挖掘数据导出成 badcase set、eval set 或 training set 格式。

说明：

• 应调用或复用 validation、dedup、conversion 和 export 逻辑。

持久化与 Git 工具

persist_dataset_artifact

用途：持久化已批准的数据集导出，并写入 manifest。

建议输入：

{
  "artifact_paths": [
    "artifacts/export/train.jsonl",
    "artifacts/export/eval.csv"
  ],
  "manifest_path": "artifacts/export/manifest.json",
  "destination": "workspace"
}

说明：

• destination="workspace" 可作为 MVP。
• 之后 destination 可以包括对象存储、dataset registry 或内部平台。

prepare_dataset_git_commit

用途：stage 已批准的数据集 artifacts，并生成 commit summary。

处置：P1/P2。

说明：

• 实际 git push 应需要人工确认。
• 这个工具应和 dataset export 分开。Export 负责创建文件；git persistence 负责发布或版本化。

建议的首批实现集合

当前短期工作建议先实现这些：

validate_dataset_records
normalize_dataset_records
generate_record_ids
convert_dataset_format
render_dataset_preview
dedup_dataset_records
export_dataset
load_eval_results
profile_error_cases
validate_data_plan
persist_dataset_artifact

然后再添加：

cluster_error_cases
summarize_error_clusters
generate_data_plan
generate_dataset_records
validate_label_coverage
load_definition_document
extract_label_definition
render_label_boundary_summary

最后添加在线挖掘工具：

analyze_badcases
build_mining_strategy
search_online_sessions
sample_online_candidates
create_annotation_batch
read_annotation_result
evaluate_mining_precision
refine_mining_strategy
export_mined_dataset

开放问题

• 对话 records 的 canonical schema name 和 version 是什么？
• 确切接受哪些 export formats？需要哪些必填列？
• 生成 records 中的 tts 应该是必填、可选，还是派生字段？
• 哪些 labels 是合法的？label registry 存在哪里？
• 在线挖掘时，哪些字段允许用于过滤和导出？
• 哪些动作在持久化或 git push 前需要人工确认？