Stabilize product data export flow

2026-05-11 11:46:09 +08:00
parent 1752c81913
commit 0e2a00990f
19 changed files with 659 additions and 31 deletions
@@ -28,6 +28,7 @@ skills/product-data/
    normalize_dataset_draft.py
    validate_dataset_records.py
    export_dataset_records.py
+    export_dataset_table.py
 ```

 在 ZK Data Agent 平台里，优先使用已注册的 `data_agent_*` 工具，因为它们带有平台级 review 状态、确认门禁和会话 output 路由。
@@ -164,9 +165,16 @@ review 展示必须简短清晰，不要重复解释工具和流程。每次 rev
 11. 生成 dataset draft text v1。
 12. 调用 `data_agent_normalize_dataset_draft`，必须传入 `confirmed_plan_id`。
 13. 调用 `data_agent_validate_dataset_records`。
-14. 如果用户要求落盘 canonical records，调用 `data_agent_export_dataset_records`，`output_path` 固定传 `output/records.jsonl`，默认导出紧凑 JSONL，不要用 `write_file` 手写 JSON。
+14. 如果用户要求落盘 canonical records，调用 `data_agent_export_dataset_records`，`output_path` 固定传 `output/records.jsonl`，默认导出紧凑 JSONL，并同时生成同目录 `records.csv` 表格，不要用 `write_file` 手写 JSON 或 CSV。
 15. 本阶段默认只推进到 canonical metadata records；除非用户另行要求，不做最终训练/评测格式导出。

+生成阶段要避免一次性把大量数据塞进工具参数：
+
+- 单次 `data_agent_normalize_dataset_draft` 最多处理 8 条 case；计划数量更多时，分批生成、分批 normalize，再汇总校验和导出。
+- dataset draft 中的 Agent target 推荐写成单引号形式，例如 `target: Agent(tag='地图导航')`。工具会规范化为 `Agent(tag="地图导航")`，这样可以降低 tool call JSON 里双引号转义失败的概率。
+- 如果 draft 已经保存在文件中，优先传 `draft_path`，不要再把大段 `draft_text` 作为工具参数传入。
+- 校验和导出 records 时，如果 records 已经保存在 JSON/JSONL 文件中，优先传 `records_path`。
+
 ## 数据生成输出格式

 当需要生成数据样本时，默认使用 dataset draft text v1，不要直接输出 JSON、JSONL、CSV 或最终表格格式。除非用户明确要求机器可读格式，否则优先输出便于人工 review 的文本格式。
@@ -196,6 +204,7 @@ notes: 可选，说明覆盖的问题或边界
 - `小爱:` 表示小爱回复 tts。
 - 最后一个 `用户:` 是本轮 query。
 - `target:` 是本轮 query 对应的监督标签，必须存在。
+- 为避免工具参数 JSON 转义失败，dataset draft 里 Agent 标签优先写 `target: Agent(tag='xxx')`；转换工具会统一规范为 `Agent(tag="xxx")`。
 - 单轮数据只需要写一行 `用户:`，然后写 `target:`。
 - 多轮数据需要按照时间顺序写多组 `用户:` / `小爱:`。
 - 多轮数据的最后一轮只写 `用户:` 和 `target:`，不要写最后一轮 `小爱:`，因为本轮 query 不包含 tts。
@@ -207,7 +216,7 @@ notes: 可选，说明覆盖的问题或边界

 `data_agent_normalize_dataset_draft` 会把 dataset draft text 转成 canonical records，并统一补齐 `record_id`、`source`、`timestamp`、`context`、`target_type` 等机械字段。

-canonical records 落盘必须使用 `data_agent_export_dataset_records`，默认格式是紧凑 JSONL：一行一个 canonical record，不带外层数组，不手写缩进 JSON。默认 `output_path` 固定传 `output/records.jsonl`；不要传 `output/<数据集名>/records.jsonl`，不要传 `tasks/...`，不要自定义文件名。只有用户明确要求兼容旧文件时，才使用 `output_format="json"` 导出紧凑 JSON 数组，此时工具会归一为 `output/records.json`。
+canonical records 落盘必须使用 `data_agent_export_dataset_records`，默认格式是紧凑 JSONL：一行一个 canonical record，不带外层数组，不手写缩进 JSON。默认 `output_path` 固定传 `output/records.jsonl`；不要传 `output/<数据集名>/records.jsonl`，不要传 `tasks/...`，不要自定义文件名。工具默认同时在同目录生成 `records.csv`，用于同事之间流转和表格查看。只有用户明确要求兼容旧文件时，才使用 `output_format="json"` 导出紧凑 JSON 数组，此时工具会归一为 `output/records.json`，但表格仍然是同目录 `records.csv`。

 当前 canonical record v1 工作格式：

@@ -337,12 +346,18 @@ skills/product-data/scripts/normalize_dataset_draft.py

 ```json
 {
-  "draft_text": "# dataset_label: 地图餐饮边界\n\n### case: 找附近美食\n用户: 附近有什么好吃的\ntarget: Agent(tag=\"餐饮服务\")",
+  "draft_text": "# dataset_label: 地图餐饮边界\n\n### case: 找附近美食\n用户: 附近有什么好吃的\ntarget: Agent(tag='餐饮服务')",
  "batch_id": "aabbccdd",
  "source_type": "generated"
 }
 ```

+如果草稿已经落盘，也可以传：
+
+```json
+{"draft_path": "output/dataset_draft.txt", "batch_id": "aabbccdd", "source_type": "generated"}
+```
+
 用途：把 dataset draft text v1 转成 canonical records。

 ### `product_data_validate_dataset_records`
@@ -387,6 +402,31 @@ skills/product-data/scripts/export_dataset_records.py

 用途：导出紧凑 JSONL/JSON。默认文件名是 `records.jsonl` 或 `records.json`。

+默认还会生成同目录 `records.csv` 表格，字段固定为：
+
+```text
+request_id,timestamp,query,prev_session,context,label,是否迁移Function,function
+```
+
+### `product_data_export_dataset_table`
+
+脚本：
+
+```text
+skills/product-data/scripts/export_dataset_table.py
+```
+
+输入支持：
+
+```json
+{
+  "records_path": "output/records.jsonl",
+  "output_dir": "output"
+}
+```
+
+用途：已有 canonical records 时，只补生成同事流转表格 `records.csv`，不改写元数据文件。主流程仍优先用 `product_data_export_dataset_records`，因为它会一次性导出元数据和表格。
+
 ## 当前可用工具

 - `read_file`：读取用户提供的产品定义、标签定义、样例 query 文件。
@@ -405,16 +445,16 @@ skills/product-data/scripts/export_dataset_records.py
 - `data_agent_show_generation_plan`：用户要求查看当前计划，或继续上下文时需要恢复计划详情时使用。
 - `data_agent_update_generation_plan`：用户对计划提出修改意见后使用，更新计划并重新展示。
 - `data_agent_confirm_generation_plan`：用户明确确认当前计划版本后使用，获取 `confirmed_plan_id`。
- `data_agent_normalize_dataset_draft`：用户确认计划后，把 dataset draft text v1 转成 canonical records；必须传入 `confirmed_plan_id`。
- `data_agent_validate_dataset_records`：对 canonical records 做结构、标签、时间戳和多轮上下文校验。
- `data_agent_export_dataset_records`：校验 canonical records 并落盘；默认写紧凑 JSONL，一行一条，固定传 `output/records.jsonl`，不要再用 `write_file` 手写 records 文件。
+- `data_agent_normalize_dataset_draft`：用户确认计划后，把 dataset draft text v1 转成 canonical records；必须传入 `confirmed_plan_id`；支持 `draft_text` 或 `draft_path`，大草稿优先 `draft_path`。
+- `data_agent_validate_dataset_records`：对 canonical records 做结构、标签、时间戳和多轮上下文校验；支持 `records` 或 `records_path`。
+- `data_agent_export_dataset_records`：校验 canonical records 并落盘；支持 `records` 或 `records_path`；默认写紧凑 JSONL，一行一条，固定传 `output/records.jsonl`，并同时生成 `output/records.csv` 表格，不要再用 `write_file` 手写 records 或表格文件。

 ## 约束

 - 不要静默解决产品或标签歧义。
 - 如果 `ask_user_question` 不可用，使用普通回复向用户提问并停止，不要自己替用户确认。
 - canonical records 通过校验前，不要生成最终导出格式。
- canonical records 需要落盘时，必须用 `data_agent_export_dataset_records`；不要自己拼接 JSON/JSONL；不要创建数据集子目录或自定义 records 文件名。
+- canonical records 需要落盘时，必须用 `data_agent_export_dataset_records`；不要自己拼接 JSON/JSONL/CSV；不要创建数据集子目录或自定义 records 文件名。
 - 如果使用 portable scripts，它们只负责格式转换、校验和导出，不替代 `generation_goal` / `generation_plan` 的用户 review。
 - 除非用户明确要求，否则不要把“修改标签定义”和“生成数据”混在一起做。
 - 不要因为用户说“生成一些数据”就跳过边界总结和 generation plan review。