# 06. product-data Skill 实现

![product-data Skill 实现](assets/06-product-data.png)

## 1. 定位

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

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

位置：

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

## 2. Skill 目录结构

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

```text
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
```

分工：

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

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

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

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

## 3. 输入类型

Skill 将输入分成三类：

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

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

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

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

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

这一步称为 `generation_goal`。

## 4. Review 门禁

`product-data` 有两个门禁模式。

### 4.1 一次确认模式

适用：

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

链路：

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

### 4.2 两段确认模式

适用：

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

链路：

```text
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 做分阶段控制。

```text
第一轮：
  模型选择 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。

内部保存：

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

训练输出组合：

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

评测 CSV 里：

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

## 7. 脚本链路

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

典型顺序：

```text
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. 输出约束

固定逻辑输出：

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

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

```text
.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 获取。