下面是中文翻译：

# 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 和其他消费格式，就应该成为确定性的工具逻辑。

实际规则是：

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

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

## 标准 Record 层

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

建议的标准 record 结构：

```json
{
  "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。

建议输入：

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

建议输出：

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

说明：

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

## `normalize_dataset_records`

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

建议输入：

```json
{
  "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`。

建议输入：

```json
{
  "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。

建议输入：

```json
{
  "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 转换成一个批准的下游格式。

建议格式：

```text
training_jsonl
eval_prompt_csv
review_table_csv
markdown_preview
```

建议输入：

```json
{
  "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 渲染成人类评审用的格式。

建议输入：

```json
{
  "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。

建议输入：

```json
{
  "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，并转换成标准内部表。

建议输入：

```json
{
  "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 中产出结构化统计和切片分析。

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

建议输出：

```json
{
  "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 经常需要人工解释。
* 之前的聚类是交互式的，这一点应该保留。

建议设计：

```json
{
  "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 标题、疑似根因、示例、建议的数据生成方向。

建议输入：

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

说明：

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

## `create_review_packet`

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

建议输入：

```json
{
  "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 或标签定义创建结构化生成计划。

建议输入：

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

建议输出形态：

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

建议输入：

```json
{
  "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。

建议输入：

```json
{
  "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。

建议输入：

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

说明：

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

## `extract_label_definition`

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

建议输出：

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

说明：

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

## `render_label_boundary_summary`

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

建议输出：

```text
artifacts/label_boundary_summary.md
```

说明：

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

# P2：在线挖掘工具

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

## `analyze_badcases`

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

建议输出：

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

## `build_mining_strategy`

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

建议输出形态：

```json
{
  "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。

建议输入：

```json
{
  "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 负责发布或版本化。

# 建议的首批实现集合

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

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

然后再添加：

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

最后添加在线挖掘工具：

```text
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 前需要人工确认？