From 279f56386c32d70171264b0ee1dda3a59e102386 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=AD=A6=E9=98=B3?= <wuy398@chinaunicom.cn>
Date: Wed, 29 Apr 2026 19:31:48 +0800
Subject: [PATCH] Document data record review workflow

---
 .../bundled/data-record-format/SKILL.md       | 163 +++++++++++++++---
 .../eval-error-data-generation/SKILL.md       |   2 +-
 2 files changed, 140 insertions(+), 25 deletions(-)

diff --git a/src/skills/bundled/data-record-format/SKILL.md b/src/skills/bundled/data-record-format/SKILL.md
index ef8f5af..714741e 100644
--- a/src/skills/bundled/data-record-format/SKILL.md
+++ b/src/skills/bundled/data-record-format/SKILL.md
@@ -3,55 +3,170 @@ name: data-record-format
 description: 定义、检查、校验并准备标准数据记录，作为导出前的统一中间格式。
 when_to_use: 当用户想讨论、创建、校验、归一化或转换标准数据记录格式时使用。
 aliases: canonical-record, record-format
-allowed_tools: read_file, write_file, edit_file, grep_search, glob_search, ask_user_question
+allowed_tools: read_file, write_file, edit_file, grep_search, glob_search, ask_user_question, data_agent_prepare_generation_plan, data_agent_show_generation_plan, data_agent_update_generation_plan, data_agent_confirm_generation_plan, data_agent_normalize_dataset_draft, data_agent_validate_dataset_records
 ---
 
-使用这个 skill 处理共享的数据格式层。目标是让生成、挖掘、历史导入的数据都先进入同一个 canonical record 格式，再导出为训练、评测、prompt 或展示格式。
+使用这个 skill 处理共享的数据格式层。目标是让模型先输出便于人工 review 的 dataset draft text，再通过工具进入统一 canonical record，最后再导出为训练、评测、prompt 或展示格式。
 
-## 当前 Canonical Record 状态
+## 交互门禁
 
-TODO：canonical record v1 还没有最终确定。
+默认不要一步到位生成数据。除非用户已经明确说“开始生成”“确认计划”“按这个计划生成”或同义表达，否则只能做目标对齐、计划草案和问题确认。
 
-在最终确定前，先把下面结构当作工作草案：
+开始生成前必须确认这些信息：
+
+- `dataset_label`：数据集或专题名称。
+- `target` / `target_definitions`：最终监督标签。单标签任务用 `target`，多标签边界任务必须用 `target_definitions` 列出每个标签和判定规则。
+- 生成数量：总条数，以及单轮/多轮数量或比例。
+- 覆盖范围：需要覆盖哪些 query 类型、意图边界或错误类型。
+- 负例/排除项：哪些表达不要生成，或哪些边界容易误判。
+- 落盘路径：draft、canonical records、validation result 写到哪里。
+
+如果任一信息缺失，不要生成数据，不要调用 `data_agent_normalize_dataset_draft`，不要调用 `data_agent_validate_dataset_records`，只向用户提出需要确认的问题。
+
+信息完整后，先调用 `data_agent_prepare_generation_plan` 创建 pending 计划，并把返回的计划展示给用户。此时必须停止，等待用户 review。
+
+在真正生成前，必须先给用户展示一份简短生成计划，包含：
+
+```text
+dataset_label:
+target 或 target_definitions:
+生成数量:
+单轮/多轮:
+覆盖范围:
+负例/排除项:
+落盘路径:
+```
+
+展示计划后停下来等用户 review。
+
+- 如果用户提出修改意见，调用 `data_agent_update_generation_plan` 更新计划，然后重新展示计划并继续等待 review。
+- 如果用户要求查看当前计划，调用 `data_agent_show_generation_plan`。
+- 只有用户明确确认当前计划版本后，才能调用 `data_agent_confirm_generation_plan`。确认时传入刚展示给用户的 `reviewed_revision`。
+
+用户确认后，拿到 `confirmed_plan_id`，才能生成 dataset draft text，并继续调用工具。
+
+`data_agent_normalize_dataset_draft` 对生成数据有代码级门禁：没有 `confirmed_plan_id`，或者计划未确认，会拒绝执行。
+
+多标签边界数据不要拆成多个互不相关的单标签计划。应该创建一个计划，并在 `target_definitions` 中列出所有候选标签。例如：
+
+```json
+[
+  {
+    "name": "餐饮服务",
+    "target": "Agent(tag=\"餐饮服务\")",
+    "rule": "找附近的美食、奶茶、餐厅等，没有明确要求导航。"
+  },
+  {
+    "name": "地图导航",
+    "target": "Agent(tag=\"地图导航\")",
+    "rule": "明确出现导航去某地点、带我去某地点、路线规划等。"
+  }
+]
+```
+
+生成 draft text 时，每条 case 的 `target:` 必须从已确认计划的 `target` 或 `target_definitions[*].target` 中选择。不要临时发明新 target。
+
+## 数据生成输出格式
+
+当需要生成数据样本时，默认使用 dataset draft text v1，不要直接输出 JSON、JSONL、CSV 或最终表格格式。除非用户明确要求机器可读格式，否则优先输出便于人工 review 的文本格式。
+
+### 格式
+
+```text
+# dataset_label: 数据集或专题名称
+
+### case: case名称
+用户: 本轮 query
+target: Agent(tag="xxx")
+notes: 可选，说明覆盖的问题或边界
+
+### case: 多轮 case 名称
+用户: 前一轮 query
+小爱: 前一轮 tts
+用户: 本轮 query
+target: Agent(tag="xxx")
+notes: 可选，说明覆盖的问题或边界
+```
+
+### 规则
+
+- 每条数据用一个 `### case:` 开始。
+- `用户:` 表示用户 query。
+- `小爱:` 表示小爱回复 tts。
+- 最后一个 `用户:` 是本轮 query。
+- `target:` 是本轮 query 对应的监督标签，必须存在。
+- 单轮数据只需要写一行 `用户:`，然后写 `target:`。
+- 多轮数据需要按照时间顺序写多组 `用户:` / `小爱:`。
+- 多轮数据的最后一轮只写 `用户:` 和 `target:`，不要写最后一轮 `小爱:`，因为本轮 query 不包含 tts。
+- 如果 `target` 无法确定，不要编造，必须向用户确认。
+- 不要手写 `record_id`、`request_id`、`timestamp`、`context`。
+- 线上挖掘数据如有真实 `request_id` 和 `timestamp`，可以附加在 case 中；没有则不写。
+
+## Canonical Record
+
+`data_agent_normalize_dataset_draft` 会把 dataset draft text 转成 canonical records，并统一补齐 `record_id`、`source`、`timestamp`、`context`、`target_type` 等机械字段。
+
+当前 canonical record v1 工作格式：
 
 ```json
 {
-  "record_id": "optional-stable-id",
-  "conversation": [
+  "record_id": "gen_aabbccdd_000001",
+  "source": {
+    "type": "generated",
+    "request_id": "aabbccdd",
+    "timestamp": 1755567930500
+  },
+  "turn": {
+    "query": "本轮 query",
+    "timestamp": 1755567930500
+  },
+  "prev_session": [
     {
-      "query": "...",
-      "tts": "...",
-      "metadata": {}
+      "query": "前一轮 query",
+      "tts": "前一轮 tts",
+      "timestamp": 1755567870500
     }
   ],
+  "context": {},
   "label": {
-    "type": "function_or_agent",
-    "name": "...",
-    "arguments": {}
+    "dataset_label": "数据集或专题名称",
+    "target": "Agent(tag=\"xxx\")",
+    "target_type": "agent"
   },
-  "source": {
-    "type": "generated|mined|eval_error|manual",
-    "task_id": "...",
-    "notes": "..."
-  },
-  "metadata": {}
+  "meta": {
+    "case_name": "case名称",
+    "notes": ""
+  }
 }
 ```
 
 ## 必要工作循环
 
-1. 先判断用户讨论的是 canonical record 层，还是下游导出格式层。
+1. 先判断用户讨论的是模型生成草稿、canonical record 层，还是下游导出格式层。
 2. 如果用户提供了文件，先检查文件结构，再提出转换或校验方案。
-3. 明确记录必填字段中的不确定点，尤其是 `tts`、标签类型、标签名称、多轮结构和来源元数据。
-4. 如果当前 schema 信息不足以继续，提出简短问题，或把问题写入任务笔记。
-5. 在 canonical records 存在之前，不要直接创建最终训练、评测或展示格式。
+3. 如果生成目标没有确认完整，按“交互门禁”提问，不要继续生成。
+4. 信息完整后，调用 `data_agent_prepare_generation_plan` 创建 pending 计划，展示计划并等待用户 review。
+5. 用户提出修改意见时，调用 `data_agent_update_generation_plan`，然后重新展示计划。
+6. 用户明确确认当前计划版本后，调用 `data_agent_confirm_generation_plan` 获取 `confirmed_plan_id`。
+7. 让模型优先生成 dataset draft text，而不是直接生成 canonical JSON。
+8. 调用 `data_agent_normalize_dataset_draft`，并传入 `confirmed_plan_id`，转成 canonical records。
+9. 调用 `data_agent_validate_dataset_records` 校验字段、标签、时间戳和多轮结构。
+10. 明确记录必填字段中的不确定点，尤其是 `target`、标签类型、多轮结构和来源元数据。
+11. 如果当前 schema 信息不足以继续，提出简短问题，或把问题写入任务笔记。
+12. 在 canonical records 存在之前，不要直接创建最终训练、评测或展示格式。
 
 ## 工具使用建议
 
 - 用 `read_file` 读取用户提供的样例或 schema 笔记。
 - 用 `write_file` 或 `edit_file` 起草 schema 笔记、样例记录或 open questions。
 - 用 `grep_search` 和 `glob_search` 查找已有 data-agent 文档和样例。
-- TODO：工具实现后，使用 `validate_dataset_records`、`normalize_dataset_records`、`convert_dataset_format` 和 `export_dataset`。
+- 用 `data_agent_prepare_generation_plan` 创建待确认生成计划。
+- 用 `data_agent_show_generation_plan` 查看当前计划。
+- 用 `data_agent_update_generation_plan` 根据用户 review 意见修改计划。
+- 用 `data_agent_confirm_generation_plan` 记录用户确认，并获取 `confirmed_plan_id`。
+- 用 `data_agent_normalize_dataset_draft` 把 dataset draft text 转成 canonical records，生成数据必须传入 `confirmed_plan_id`。
+- 用 `data_agent_validate_dataset_records` 校验 canonical records。
+- 后续导出阶段再使用 `convert_dataset_format` 或 `export_dataset`。
 
 ## 推荐产物
 
diff --git a/src/skills/bundled/eval-error-data-generation/SKILL.md b/src/skills/bundled/eval-error-data-generation/SKILL.md
index b73ba42..ca66d06 100644
--- a/src/skills/bundled/eval-error-data-generation/SKILL.md
+++ b/src/skills/bundled/eval-error-data-generation/SKILL.md
@@ -38,7 +38,7 @@ allowed_tools: read_file, write_file, edit_file, grep_search, glob_search, ask_u
    - 要生成的正例、反例、边界例
    - 必要元数据
 7. 只有在计划清楚后，才生成或请求 canonical records。
-8. TODO：工具实现后，在预览或导出前运行 `validate_dataset_records`。
+8. TODO：工具实现后，在预览或导出前运行 `data_agent_validate_dataset_records`。
 9. TODO：工具实现后，运行 `render_dataset_preview` 和 `export_dataset`。
 
 ## 当前工具状态