zk-data-agent/docs/technical-architecture/06-product-data.md

06. product-data Skill 实现

1. 定位

product-data 是数据开发链路的核心 Skill，负责：

产品定义 / 标签规则 / 手写边界 / 示例 query / badcase
  -> 输入文本化
  -> generation goal
  -> 用户 review
  -> generation plan
  -> 用户确认数量、标签、边界、路径
  -> dataset draft text
  -> canonical records
  -> validate
  -> export records / table / training / eval

位置：

skills/product-data/SKILL.md
skills/product-data/knowledge/
skills/product-data/scripts/

2. Skill 目录结构

当前 SKILL.md 中定义的能力组织：

skills/product-data/
  SKILL.md
  tools.yaml
  requirements.txt
  knowledge/
    dataset_draft_v1.md
    canonical_record_v1.md
    portable_skill_contract.md
  schemas/
  scripts/
    normalize_dataset_draft.py
    validate_dataset_records.py
    export_dataset_records.py
    export_dataset_table.py
    export_training_jsonl.py
    export_planning_eval_csv.py

分工：

SKILL.md
  流程协议、门禁、工具调用顺序、禁止事项。

knowledge/
  数据草稿、canonical record 和 portable skill contract。

scripts/
  确定性转换、校验和导出。

data_agent_* 平台工具
  负责输入文本化和 review 状态机。

3. 输入类型

Skill 将输入分成三类：

文件定义型
  产品定义、标签定义、路由规则、表格、Markdown、CSV。

手写规则型
  用户直接描述边界，例如“找附近美食给餐饮服务，导航去某地给地图导航”。

示例归纳型
  用户只给 query/example/badcase，需要先归纳边界和标签倾向。

三类输入最后统一整理成：

dataset_label
target / target_definitions
plan_hint
coverage
exclusions
open_questions
source_refs
complex 规则

这一步称为 generation_goal。

4. Review 门禁

product-data 有两个门禁模式。

4.1 一次确认模式

适用：

• 用户直接给出清晰手写规则。
• target 表达明确。
• 用户已经希望生成数据。

链路：

data_agent_prepare_generation_plan(direct_review=true)
  -> 展示目标 + 数量 + 路径
  -> 等待“确认，开始生成”

4.2 两段确认模式

适用：

• 用户提供文件、表格、badcase、长文档。
• 标签、边界、字段有歧义。
• 需要先从资料中抽取 generation goal。

链路：

data_agent_load_input_sources
  -> data_agent_render_source_context
  -> Agent 整理 generation_goal
  -> data_agent_prepare_generation_goal
  -> 用户确认目标
  -> data_agent_confirm_generation_goal
  -> data_agent_prepare_generation_plan
  -> 用户确认计划
  -> data_agent_confirm_generation_plan

5. 和 Agent Loop 的关系

product-data 明确利用 Agent loop 做分阶段控制。

第一轮：
  模型选择 product-data
  调输入工具
  调 prepare_generation_goal 或 prepare_generation_plan
  输出 review 信息
  停止

第二轮：
  用户确认目标或计划
  Agent resume session
  调 confirm 工具
  继续下一阶段

第三轮：
  用户确认计划
  Agent 生成 dataset draft
  每批调用 normalize 脚本
  调 validate 脚本
  调 export 脚本
  输出最终文件路径

重点是：确认状态不是靠自由文本记忆，而是由工具维护 confirmed_goal_id 和 confirmed_plan_id。

6. 数据格式设计

6.1 dataset draft text

面向模型生成，要求模型用较低结构负担描述：

• 用户 / 小爱 对话。
• 当前 query。
• target。
• complex。
• 场景说明。

设计目标是降低模型直接写 JSONL 的难度。

6.2 canonical record

面向工具处理，字段稳定。

用于：

• 校验结构。
• 导出流转 CSV。
• 导出训练 JSONL。
• 导出评测 planningPrompt CSV。

6.3 complex 独立维度

complex 不属于 target。

内部保存：

complex: false
target: Agent(tag="地图导航")

训练输出组合：

complex=false
Agent(tag="地图导航")

评测 CSV 里：

code标签: Agent(tag="地图导航")
complex: FALSE

7. 脚本链路

生成式数据确认后，Skill 要求使用 python_exec.script_path 调脚本。

典型顺序：

normalize_dataset_draft.py
  输入 draft + confirmed_plan_id
  输出/追加 scratchpad/normalized_records.jsonl

validate_dataset_records.py
  读取 normalized_records.jsonl
  校验字段、target、complex、时间戳、多轮上下文

export_dataset_records.py
  导出 output/records.jsonl
  同时生成 output/records.csv

export_training_jsonl.py
  导出 output/training.jsonl

export_planning_eval_csv.py
  导出 output/eval_planning.csv

为什么不用 write_file：

• records、CSV、JSONL 都是强格式数据。
• 模型手写容易出错。
• 脚本能统一 timestamp、prev_session、context、complex/target 组合。

8. 输出约束

固定逻辑输出：

output/records.jsonl
output/records.csv
output/training.jsonl
output/eval_planning.csv

通过路径路由，实际写入：

.port_sessions/accounts/<account>/sessions/<session>/output/

Skill 明确禁止：

• 按数据集名创建随机子目录。
• 把 records 写到项目根目录。
• 用 write_file 手写最终 JSONL/CSV。
• 在未确认 plan 前生成数据。

9. 设计边界

product-data 负责：

• 数据目标对齐。
• 生成计划 review。
• dataset draft 生成协议。
• canonical records 转换和导出。

不负责：

• 判断所有标签知识。
• 查询线上数据。
• ELK 检索。
• 模型训练或 git 数据仓库提交。

标签知识应由 label-master 辅助，线上数据由 online-mining-v2 或相关 Skill 获取。