Add directory-based project skills

2026-04-28 10:17:23 +08:00
parent fed0999f55
commit a040d80096
21 changed files with 1795 additions and 119 deletions
@@ -0,0 +1,730 @@
+下面是中文翻译：
+
+# 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 前需要人工确认？