Remove unused project artifacts
This commit is contained in:
武阳
@@ -1,41 +0,0 @@
|
||||
# 数据 Agent 实现任务表
|
||||
|
||||
范围：先在现有 agent loop 上开发和调试 data-agent 的 tools 与 skills，暂时不改主运行链路。
|
||||
|
||||
## 极简任务表
|
||||
|
||||
| 顺序 | 任务 | 产物 | 验证方式 |
|
||||
|---|---|---|---|
|
||||
| 1 | 定义 canonical record v1 | `src/data_agent_schema.py` 或 `src/data_agent/records.py` | 单测覆盖合法和非法样本 |
|
||||
| 2 | 实现 `validate_dataset_records` 工具 | 新增 `AgentTool` 注册和 handler | 用 JSONL 样例跑工具，检查结构化错误 |
|
||||
| 3 | 实现 `render_dataset_preview` 工具 | 生成面向人工 review 的 Markdown 预览 | 用 3 条样本生成预览 |
|
||||
| 4 | 实现 `convert_dataset_format` 工具 | 至少支持 `training_jsonl`、`eval_prompt_csv`、`review_table_csv` | 输入 canonical JSONL，检查导出文件 |
|
||||
| 5 | 实现 `export_dataset` 工具 | 多格式导出和 manifest | 校验失败时拒绝导出 |
|
||||
| 6 | 增加最小 data skill | 新增类似 `dataset-construction` 的目录化 skill | Web UI 中可见，并指导 validate/export 循环 |
|
||||
| 7 | 准备调试样例 | `test_data/data_agent/*.jsonl` | 通过 Web UI 跑 skill + tools |
|
||||
| 8 | 实现 `normalize_dataset_records` 工具 | 支持简单 CSV/JSONL 字段映射到 canonical JSONL | 输入 CSV，输出 canonical JSONL |
|
||||
| 9 | 实现 `dedup_dataset_records` 工具 | 按 query + label 做精确去重 | 输出去重后 JSONL 和重复样本报告 |
|
||||
| 10 | 按需增强 Web UI trace | 更清晰展示 tool 参数和结果 | 人工 UI 验证 |
|
||||
|
||||
## 第一批实现切片
|
||||
|
||||
先做任务 1、2、6、7：
|
||||
|
||||
```text
|
||||
skill 指导
|
||||
-> Agent 生成 canonical JSONL
|
||||
-> validate_dataset_records 校验
|
||||
-> Web UI 展示工具调用参数和校验错误
|
||||
```
|
||||
|
||||
## 预计第一批文件
|
||||
|
||||
```text
|
||||
src/data_agent_schema.py
|
||||
src/agent_tools.py
|
||||
src/bundled_skills.py
|
||||
tests/test_data_agent_schema.py
|
||||
tests/test_data_agent_tools.py
|
||||
test_data/data_agent/valid_records.jsonl
|
||||
test_data/data_agent/invalid_records.jsonl
|
||||
```
|
||||
@@ -1,730 +0,0 @@
|
||||
下面是中文翻译：
|
||||
|
||||
# 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 前需要人工确认？
|
||||
@@ -1,26 +0,0 @@
|
||||
# 数据 Agent Skill 地图
|
||||
|
||||
这是一份第一批 data-agent 目录化 skill 的工作索引。
|
||||
|
||||
## Skill 列表
|
||||
|
||||
| Skill | 主要用途 | 当前状态 |
|
||||
|---|---|---|
|
||||
| `eval-error-data-generation` | 分析评测错误，并规划针对性训练/评测数据生成 | 草案；数据工具仍待实现 |
|
||||
| `product-definition-data-generation` | 从产品/标签定义、手写规则或示例 query 生成边界感知的数据计划、dataset draft text 和 canonical records | 草案；已合并数据格式协议，定义抽取工具仍待实现 |
|
||||
| `online-badcase-mining` | 分析 badcase，并起草可迭代的线上挖掘策略 | 草案；线上挖掘工具仍待实现 |
|
||||
| `tool-smoke-test` | 验证目录化 skill 加载和基础工具 trace | 可用 smoke test |
|
||||
|
||||
## 示例触发 Query
|
||||
|
||||
```text
|
||||
Use the eval-error-data-generation skill. 输入文件：tasks/debug/context/eval_errors.csv。请先起草错误分析和数据生成计划。
|
||||
```
|
||||
|
||||
```text
|
||||
Use the product-definition-data-generation skill. 输入文件：tasks/debug/context/product_definition.md。请总结标签边界并起草数据生成计划，确认后生成 dataset draft text 并转成 canonical records。
|
||||
```
|
||||
|
||||
```text
|
||||
Use the online-badcase-mining skill. 输入文件：tasks/debug/context/badcases.jsonl。请分析共性模式并起草挖掘策略。
|
||||
```
|
||||
@@ -1,189 +0,0 @@
|
||||
# Data Agent 工具清单
|
||||
|
||||
本文档是当前 `claw-code-agent` 工具能力面的工作清单，用于未来的数据 Agent 改造。
|
||||
|
||||
范围：
|
||||
|
||||
* 源注册表：`src.agent_tools.default_tool_registry()`
|
||||
* 工具形态：`AgentTool(name, description, parameters, handler)`
|
||||
* 运行时执行：模型输出 `tool_calls`，随后 `LocalCodingAgent` 执行匹配的 handler，并把结果作为 tool message 写回。
|
||||
|
||||
## 当前工具生命周期
|
||||
|
||||
1. `default_tool_registry()` 构建基础注册表。
|
||||
2. 在 `LocalCodingAgent.__post_init__` 阶段，可能会把插件别名和虚拟工具合并进注册表。
|
||||
3. 每个 `AgentTool` 会通过 `to_openai_tool()` 转换成 OpenAI 兼容的 function schema。
|
||||
4. 模型接收 `messages` 和 `tool_specs`。
|
||||
5. 如果模型返回 `tool_calls`，运行时会执行每个指定名称的工具。
|
||||
6. 工具 handler 接收 `(arguments, ToolExecutionContext)`。
|
||||
7. handler 返回字符串，或返回 `(content, metadata)`。
|
||||
8. 运行时序列化结果，并把它作为 `role="tool"` 的消息追加进去，供下一轮模型调用使用。
|
||||
|
||||
## Data-Agent 处置标记说明
|
||||
|
||||
* `Keep`：适合首版 data-agent MVP 使用。
|
||||
* `Candidate`：可能有用，但应只在具体数据工作流需要时启用。
|
||||
* `Wrap`：能力有用，但应该通过数据专用工具名或更窄的 schema 暴露。
|
||||
* `Defer`：首版 data-agent MVP 暂不需要。
|
||||
* `Disable`：对首版 data-agent MVP 来说太宽泛，或过于面向代码。
|
||||
* `Special`：由 agent loop 特殊处理，不是普通业务工具。
|
||||
|
||||
## 工作区与文件工具
|
||||
|
||||
| 工具 | 当前描述 | Data-Agent 处置 | 备注 |
|
||||
| --------------- | ------------------------------------------------------- | ------------- | ----------------------------------------------- |
|
||||
| `list_dir` | 列出 workspace 路径下的文件和目录。 | Keep | 用于任务工作区检查。 |
|
||||
| `read_file` | 读取 workspace 内 UTF-8 文本文件内容。 | Keep | Markdown 优先流程和 artifact 读取的核心工具。 |
|
||||
| `write_file` | 在 workspace 内完整写入文件；必要时创建父目录。 | Keep | 用于 `goal.md`、memory 文件、报告、JSONL artifact。需要写权限。 |
|
||||
| `edit_file` | 使用精确字符串匹配替换 workspace 文件中的文本。 | Keep | 适合增量更新 memory / artifact。 |
|
||||
| `notebook_edit` | 通过替换或追加 source 来编辑 `.ipynb` 文件中的 Jupyter notebook cell。 | Defer | data-agent MVP 应优先使用 Markdown、JSONL、CSV 和报告。 |
|
||||
| `glob_search` | 在 workspace 内查找匹配 glob pattern 的文件。 | Keep | 用于发现任务文件和 skill 文件。 |
|
||||
| `grep_search` | 在 workspace 文件中搜索字符串或正则表达式。 | Keep | 用于本地标签定义、历史笔记和 skill 查找。 |
|
||||
|
||||
## Shell 与代码智能工具
|
||||
|
||||
| 工具 | 当前描述 | Data-Agent 处置 | 备注 |
|
||||
| ------ | ------------------------- | ------------- | --------------------------------------- |
|
||||
| `bash` | 在 workspace 内运行 shell 命令。 | Disable | 对 data-agent MVP 来说过于宽泛。优先使用专用数据工具和校验器。 |
|
||||
| `LSP` | 使用本地 LSP 风格的代码智能能力。 | Disable | 面向代码的能力；数据任务不需要。 |
|
||||
|
||||
## Web 与搜索工具
|
||||
|
||||
| 工具 | 当前描述 | Data-Agent 处置 | 备注 |
|
||||
| -------------------------- | ------------------------------- | ------------- | ---------------------------------------- |
|
||||
| `web_fetch` | 从 HTTP、HTTPS 或 file URL 获取文本资源。 | Defer | 可能用于文档读取，但不是核心数据工作流。 |
|
||||
| `search_status` | 显示本地搜索运行时摘要。 | Candidate | 仅当在线 session / 搜索 provider 被建模为搜索运行时时有用。 |
|
||||
| `search_list_providers` | 列出已配置的本地搜索 provider。 | Candidate | 同上。 |
|
||||
| `search_activate_provider` | 设置当前激活的本地搜索 provider。 | Defer | 属于配置动作，不应是普通 agent 任务行为。 |
|
||||
| `web_search` | 通过已配置后端执行真实 Web 搜索。 | Defer | 外部 Web 搜索不同于内部数据挖掘。 |
|
||||
| `tool_search` | 搜索当前激活的工具注册表。 | Keep | 在工具面持续演进时有用。之后进入严格生产模式可以移除。 |
|
||||
| `sleep` | 暂停执行一小段时间。 | Defer | 适合轮询，但在存在异步任务之前不需要。 |
|
||||
|
||||
## 人工评审与决策工具
|
||||
|
||||
| 工具 | 当前描述 | Data-Agent 处置 | 备注 |
|
||||
| ------------------- | ---------------------------- | ------------- | -------------- |
|
||||
| `ask_user_question` | 向本地 ask-user runtime 请求用户回答。 | Keep | 对边界澄清和人工裁决很重要。 |
|
||||
|
||||
## 账号与配置工具
|
||||
|
||||
| 工具 | 当前描述 | Data-Agent 处置 | 备注 |
|
||||
| ----------------------- | ------------------------------------ | ------------- | --------------------------------- |
|
||||
| `account_status` | 显示本地账号运行时摘要。 | Candidate | 如果数据系统需要账号 profile，会有用。 |
|
||||
| `account_list_profiles` | 列出已配置的本地账号 profile。 | Candidate | 用于调试访问配置。 |
|
||||
| `account_login` | 激活本地账号 profile 或临时身份。 | Defer | 不应出现在常规自主数据任务循环里。 |
|
||||
| `account_logout` | 清空当前激活账号 session 状态。 | Defer | 运维动作。 |
|
||||
| `config_list` | 列出合并后的或特定来源的 workspace 配置 key。 | Candidate | 用于检查 data-agent 配置。 |
|
||||
| `config_get` | 通过 dotted key path 读取 workspace 配置值。 | Candidate | 用于 data-agent policy / config 查询。 |
|
||||
| `config_set` | 写入 workspace 配置值。 | Disable | 配置变更应由人控制。 |
|
||||
|
||||
## MCP 工具
|
||||
|
||||
| 工具 | 当前描述 | Data-Agent 处置 | 备注 |
|
||||
| -------------------- | ------------------------------- | ------------- | ----------------------------------------------------------------------- |
|
||||
| `mcp_list_resources` | 列出本地 MCP resources。 | Candidate | 适合 skill / resource 发现或内部文档读取。 |
|
||||
| `mcp_read_resource` | 通过 URI 读取本地 MCP resource。 | Candidate | 如果标签、策略或历史决策以 resource 形式暴露，会有用。 |
|
||||
| `mcp_list_tools` | 列出已配置 MCP server 暴露的 MCP tools。 | Candidate | 用于发现数据系统工具。 |
|
||||
| `mcp_call_tool` | 调用已配置 MCP server 暴露的 MCP tool。 | Wrap | 这是强大的通用桥接能力。常规 agent 使用时，应优先使用 `search_online_sessions` 这类数据专用 wrapper。 |
|
||||
|
||||
## Remote、Worktree、Workflow 与 Trigger 工具
|
||||
|
||||
| 工具 | 当前描述 | Data-Agent 处置 | 备注 |
|
||||
| ---------------------- | -------------------------------- | ------------- | --------------------------------- |
|
||||
| `remote_status` | 显示本地 remote 运行时摘要。 | Defer | 运维相关。 |
|
||||
| `remote_list_profiles` | 列出已配置的本地 remote profile。 | Defer | 运维相关。 |
|
||||
| `remote_connect` | 激活本地 remote target / profile。 | Disable | 对 data-agent 自主模式来说过于宽泛。 |
|
||||
| `remote_disconnect` | 清空当前激活 remote connection。 | Disable | 运维变更。 |
|
||||
| `worktree_status` | 显示当前受管 git worktree session 状态。 | Disable | 面向代码。 |
|
||||
| `worktree_enter` | 创建并进入隔离 git worktree。 | Disable | 面向代码。 |
|
||||
| `worktree_exit` | 离开当前受管 worktree session。 | Disable | 面向代码。 |
|
||||
| `workflow_list` | 列出本地 workflow 定义。 | Candidate | 如果数据 pipeline 以 workflow 表示，可能有用。 |
|
||||
| `workflow_get` | 显示某个本地 workflow 定义。 | Candidate | 同上。 |
|
||||
| `workflow_run` | 记录并渲染一次 workflow 执行请求。 | Wrap | 应变成明确的数据动作，而不是任意 workflow 执行。 |
|
||||
| `remote_trigger` | 列出、查看、创建、更新或运行本地 remote trigger。 | Defer | 更偏自动化，首版 data-agent MVP 暂不需要。 |
|
||||
|
||||
## Planning、Task、Team 与后台工具
|
||||
|
||||
| 工具 | 当前描述 | Data-Agent 处置 | 备注 |
|
||||
| --------------- | ----------------------------- | ------------- | -------------------------------------- |
|
||||
| `plan_get` | 显示当前本地运行时 plan。 | Candidate | 对结构化长周期数据任务有用。 |
|
||||
| `update_plan` | 替换当前运行时 plan。 | Candidate | 有用，但不能替代任务 workspace memory。 |
|
||||
| `plan_clear` | 清空当前运行时 plan。 | Defer | 运维动作。 |
|
||||
| `task_next` | 显示下一批可执行 runtime task。 | Candidate | 之后可映射到数据任务 backlog。 |
|
||||
| `task_list` | 列出本地存储的 runtime task。 | Candidate | 可支持数据任务状态。 |
|
||||
| `task_get` | 通过 id 显示本地存储的 runtime task。 | Candidate | 同上。 |
|
||||
| `task_create` | 创建本地存储的 runtime task。 | Defer | 优先使用 task workspace。 |
|
||||
| `task_update` | 更新本地存储的 runtime task。 | Defer | 优先使用 task workspace。 |
|
||||
| `task_start` | 标记任务为进行中。 | Defer | 优先使用 task workspace。 |
|
||||
| `task_complete` | 标记任务为完成。 | Defer | 优先使用 task workspace。 |
|
||||
| `task_block` | 标记任务被阻塞。 | Defer | 优先使用 `open_questions.md`。 |
|
||||
| `task_cancel` | 标记任务被取消。 | Defer | 运维动作。 |
|
||||
| `team_list` | 列出本地配置的协作团队。 | Defer | 非核心 MVP。 |
|
||||
| `team_get` | 显示某个本地配置的协作团队。 | Defer | 非核心 MVP。 |
|
||||
| `team_create` | 创建本地存储的协作团队。 | Disable | 非核心 MVP；属于变更动作。 |
|
||||
| `team_delete` | 删除本地存储的协作团队。 | Disable | 破坏性运维动作。 |
|
||||
| `send_message` | 发送本地协作消息。 | Defer | 之后在评审路由中可能有用。 |
|
||||
| `team_messages` | 显示已记录的协作消息。 | Defer | 之后在评审路由中可能有用。 |
|
||||
| `todo_write` | 用结构化 todo list 替换当前本地运行时任务列表。 | Candidate | 可用于 agent 自组织；但 task workspace 仍应是事实源。 |
|
||||
| `TaskOutput` | 通过 ID 获取后台任务输出。 | Defer | 等异步数据任务存在后有用。 |
|
||||
| `TaskStop` | 通过 ID 停止运行中的后台任务。 | Defer | 等异步数据任务存在后有用。 |
|
||||
|
||||
## Loop 特殊工具
|
||||
|
||||
| 工具 | 当前描述 | Data-Agent 处置 | 备注 |
|
||||
| ---------------- | ------------------- | ------------- | ----------------------------------------- |
|
||||
| `EnterPlanMode` | 进入 plan mode。 | Special | coding-agent 行为；可能会被 data-agent 任务规划指导替代。 |
|
||||
| `ExitPlanMode` | 退出 plan mode。 | Special | 同上。 |
|
||||
| `Agent` | 为复杂任务启动一个新 agent。 | Defer | 之后可用于并行挖掘 / 评审，但首版 MVP 应保持单 agent loop。 |
|
||||
| `delegate_agent` | 旧版：把子任务委托给嵌套 agent。 | Disable | 如果之后需要委托，优先使用 `Agent`。 |
|
||||
| `Skill` | 在主对话中执行 skill。 | Special | 作为概念入口保留，但基于目录的数据 skills 需要单独设计。 |
|
||||
|
||||
## 建议的 MVP Data Tool Registry
|
||||
|
||||
首版 data-agent 实验建议从这个最小注册表开始：
|
||||
|
||||
```text
|
||||
list_dir
|
||||
read_file
|
||||
write_file
|
||||
edit_file
|
||||
glob_search
|
||||
grep_search
|
||||
ask_user_question
|
||||
tool_search
|
||||
```
|
||||
|
||||
原型阶段可选 MCP 桥接：
|
||||
|
||||
```text
|
||||
mcp_list_resources
|
||||
mcp_read_resource
|
||||
mcp_list_tools
|
||||
mcp_call_tool
|
||||
```
|
||||
|
||||
当内部数据工具准备好后，应优先添加窄口径的数据专用工具，而不是暴露宽泛工具：
|
||||
|
||||
```text
|
||||
search_online_sessions
|
||||
sample_top_queries
|
||||
find_similar_cases
|
||||
mine_by_pattern
|
||||
mine_by_model_disagreement
|
||||
cluster_and_dedup
|
||||
generate_eval_candidates
|
||||
validate_eval_jsonl
|
||||
run_router_eval
|
||||
run_online_replay
|
||||
create_annotation_queue
|
||||
read_human_review_result
|
||||
persist_dataset_artifact
|
||||
```
|
||||
|
||||
## Data-Agent 改造实现说明
|
||||
|
||||
* 新增 `default_data_tool_registry()`，不要直接修改 `default_tool_registry()`。
|
||||
* 第一阶段保留文件工具、人工评审工具，以及可选的 MCP discovery。
|
||||
* 内部数据系统应通过稳定、可审计的数据工具暴露，而不是通过 `bash`、原始 SQL 或通用 `mcp_call_tool` 暴露。
|
||||
* 将 `mcp_call_tool` 视为开发桥接；生产 data-agent 流程应使用面向目的构建的 wrapper tools。
|
||||
* 工具权限应与数据治理动作对齐，而不只是与底层执行机制对齐。
|
||||
@@ -1,43 +0,0 @@
|
||||
# Task 001：目录化 Skills
|
||||
|
||||
## 目标
|
||||
|
||||
把 skill 内容从 Python 内置字符串迁移到文件目录中，让 data-agent 工作流可以用文件形式开发、review 和维护。
|
||||
|
||||
## 范围
|
||||
|
||||
- 保持当前 `Skill` 工具和 agent loop 不变。
|
||||
- 支持从 `src/skills/bundled/*/SKILL.md` 加载内置目录化 skill。
|
||||
- 保持 Python 动态 skill 可用。
|
||||
- 使用已有内置 skill 作为迁移样例。
|
||||
|
||||
## 第一批切片
|
||||
|
||||
- `simplify` 和 `debug` 继续保留 Python 实现，因为它们需要读取动态运行时数据。
|
||||
- `verify` 和 `update-config` 迁移到目录化 skill。
|
||||
- `SKILL.md` 支持简单 front matter：
|
||||
|
||||
```text
|
||||
---
|
||||
name: verify
|
||||
description: Verify a code change works by running the app and tests.
|
||||
when_to_use: When the user asks to verify, test, or check that recent changes work.
|
||||
allowed_tools: read_file, bash, grep_search, glob_search
|
||||
---
|
||||
|
||||
Skill prompt body...
|
||||
```
|
||||
|
||||
## 成功标准
|
||||
|
||||
- `/skills` 仍然能列出迁移后的 skills。
|
||||
- Web UI `/api/skills` 仍然能返回迁移后的 skills。
|
||||
- `Skill({"skill": "verify"})` 返回 `SKILL.md` 中的 prompt 正文。
|
||||
- 现有 Python 动态 skills 仍然可用。
|
||||
|
||||
## 当前状态
|
||||
|
||||
- 目录化 skill loader 已在 `src/bundled_skills.py` 实现。
|
||||
- `verify` 已迁移到 `src/skills/bundled/verify/SKILL.md`。
|
||||
- `update-config` 已迁移到 `src/skills/bundled/update-config/SKILL.md`。
|
||||
- 动态 skills `simplify` 和 `debug` 继续保持 Python 实现。
|
||||
@@ -1,33 +0,0 @@
|
||||
# Task 002：项目级 Skills
|
||||
|
||||
## 目标
|
||||
|
||||
允许项目维护者直接在 workspace 根目录添加 skills：
|
||||
|
||||
```text
|
||||
skills/
|
||||
my-skill/
|
||||
SKILL.md
|
||||
```
|
||||
|
||||
## 查找顺序
|
||||
|
||||
当存在 workspace `cwd` 时：
|
||||
|
||||
1. `cwd/skills/*/SKILL.md`
|
||||
2. `src/skills/bundled/*/SKILL.md`
|
||||
3. Python 动态 skills
|
||||
|
||||
项目级 skills 优先于同名的内置目录 skill 或 Python 动态 skill。
|
||||
|
||||
## 接入点
|
||||
|
||||
- `Skill` 工具执行时，会通过当前 runtime `cwd` 解析项目级 skills。
|
||||
- `/skills` 会列出当前 workspace 下的项目级 skills。
|
||||
- Web UI `/api/skills` 会列出当前 Working dir 下的项目级 skills。
|
||||
|
||||
## 说明
|
||||
|
||||
- 项目级 skill 与内置目录化 skill 共用同一套 `SKILL.md` front matter 格式。
|
||||
- `name`、`aliases`、`allowed_tools` 保持面向机器的英文字段。
|
||||
- skill 正文可以使用中文或英文维护。
|
||||
Reference in New Issue
Block a user