zk-data-agent/skills/product-data/SKILL.md at ca2f6f36fc4d2659d2dde08d119433804812ec16

wuyang/zk-data-agent

Fork 0

Files

T

wuyang6 ca2f6f36fc Make product-data skill portable

2026-05-11 10:58:35 +08:00

23 KiB

Raw Blame History

name, description, when_to_use, aliases, allowed_tools

name	description	when_to_use	aliases	allowed_tools
product-data	从产品/标签定义、手写边界规则或示例 query 中提取标签边界，并生成可 review 的数据计划、dataset draft text 和 canonical metadata records。	当用户提供产品定义、标签规则、路由边界文档、示例 query、手写标签边界，并希望生成训练/评测/专项数据时使用。	definition-data, label-data	read_file, write_file, edit_file, grep_search, glob_search, ask_user_question, python_exec, data_agent_load_input_sources, data_agent_render_source_context, data_agent_extract_case_evidence, data_agent_prepare_generation_goal, data_agent_confirm_generation_goal, 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, data_agent_export_dataset_records

使用这个 skill 作为“产品/标签定义/手写规则/示例 query -> 输入文本化 -> generation goal 草案 -> 人工 review -> 生成计划 review -> dataset draft text -> canonical metadata records”的统一入口。

本 skill 内置数据记录生成协议。其他数据开发 skill 如果需要生成或整理标准数据，可以复用这里的“交互门禁、dataset draft text v1、canonical record v1”规则。

能力组织

本 skill 按 portable skill contract 组织，能力本体在 skill 目录内：

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

在 ZK Data Agent 平台里，优先使用已注册的 data_agent_* 工具，因为它们带有平台级 review 状态、确认门禁和会话 output 路由。

迁移到其他 Agent 或没有平台注册能力时，可以直接执行 scripts/ 下的 portable scripts。脚本支持 --input input.json 或 stdin JSON，stdout 只输出一个 JSON 对象。tools.yaml 描述了这些脚本如何被平台注册为工具；如果平台不支持 tools.yaml，不影响脚本独立使用。

脚本能力和平台注册的关系是：

脚本能力是本体
平台注册是适配层

portable scripts 不包含人类 review 状态机。生成式数据仍必须先由 Agent 按本 skill 的 review 门禁获得用户确认，再调用脚本做格式转换、校验和导出。

输入假设

用户可能会提供：

产品定义文档、标签定义文档、路由规则文档。
表格、Markdown、JSON、CSV 或普通文本里的标签定义。
手写的标签边界规则。
一组 example query、badcase、正例或反例。
已知边界冲突，例如某类 query 应该进入哪个 Agent/function。

输入可能不完整或存在歧义。保留不确定性，不要自行发明隐藏规则。

任务定位

先判断用户输入属于哪一类：

文件定义型：用户提供文件路径、文档、表格或粘贴的大段定义内容。
手写规则型：用户直接描述标签边界，例如“找附近美食是餐饮服务，导航去某地是地图导航”。
示例归纳型：用户只给 query/example/badcase，需要先归纳边界和标签倾向。

三类输入最后都要统一产出：

dataset_label:
target 或 target_definitions:
plan_hint:
coverage:
exclusions:
open_questions:
source_refs:

这一步称为 generation_goal。它是模型基于输入资料整理出的数据生成目标草案，不是最终生成计划。

generation_goal 必须先展示给用户 review。只有用户确认 generation goal 后，才能进入本 skill 内置的 generation plan review 流程。

交互门禁

默认不要一步到位生成数据。除非用户已经明确说“开始生成”“确认计划”“按这个计划生成”或同义表达，否则只能做目标对齐、计划草案和问题确认。

为了减少重复确认，优先按下面两种门禁模式选择：

一次确认模式：用户直接给出手写规则、完整 target 表达，并且明确希望生成数据时，直接调用 data_agent_prepare_generation_plan，传 direct_review=true 和 target_definitions。这一次 review 同时确认目标、数量、轮次和路径；用户回复“确认，开始生成”后即可调用 data_agent_confirm_generation_plan。
两段确认模式：用户提供文件、表格、badcase、长文档，或者标签/边界/字段含义有歧义时，先用 data_agent_prepare_generation_goal 做目标 review；目标确认后再做 plan review。

所有数据产物必须放在当前用户当前会话的 output 目录下。不要把 records、draft 或 validation 写到项目根目录的 output/、tasks/ 或其他源码目录。canonical records 的稳定输出文件名固定为 output/records.jsonl，不要按数据集名创建子目录，不要自定义时间戳、中文专题名或随机文件名。工具会把相对 output_path 自动路由到会话 output 目录，并把 records 路径归一到当前会话 output/records.jsonl；展示给用户时以工具返回的实际路径为准。

开始生成前必须确认这些信息：

dataset_label：数据集或专题名称。
target / target_definitions：最终监督标签。单标签任务用 target，多标签边界任务必须用 target_definitions 列出每个标签和判定规则。
生成数量：总条数，以及单轮/多轮数量或比例。
覆盖范围：需要覆盖哪些 query 类型、意图边界或错误类型。
负例/排除项：哪些表达不要生成，或哪些边界容易误判。
落盘路径：canonical records 固定使用 output/records.jsonl，由工具路由到当前会话 output 目录。

如果任一信息缺失，不要生成数据，不要调用 data_agent_prepare_generation_plan，不要调用 data_agent_normalize_dataset_draft，不要调用 data_agent_validate_dataset_records，只向用户提出需要确认的问题。

两段确认模式下，信息完整后，调用 data_agent_prepare_generation_goal 创建 pending goal。这个工具会暂停本轮，必须把返回的 generation_goal 展示给用户 review。用户确认 goal 之后，调用 data_agent_confirm_generation_goal 获取 confirmed_goal_id，再调用 data_agent_prepare_generation_plan 创建 pending plan。创建 plan 后也会暂停本轮，必须等待用户 review。

一次确认模式下，不要先创建 generation goal；直接创建 pending plan，并在 plan 里包含 target_definitions、total_count、turn_mix、coverage、exclusions、output_path。output_path 固定传 output/records.jsonl。不要让用户先确认目标再确认计划。

用户确认后，拿到 confirmed_plan_id，才能生成 dataset draft text，并继续调用工具。

data_agent_normalize_dataset_draft 对生成数据有代码级门禁：没有 confirmed_plan_id，或者计划未确认，会拒绝执行。

如果用户在原始需求里已经写出 Agent(tag="xxx")、function 调用或其他完整标签表达，target 必须原样保留这个完整表达，不要简化成纯标签名。例如用户说 Agent(tag="餐饮服务")，则 target_definitions[*].target 和后续 draft 的 target: 都必须写 Agent(tag="餐饮服务")，不要写成 餐饮服务。

review 展示必须简短清晰，不要重复解释工具和流程。每次 review 最多展示 6 行，格式优先如下：

我先把生成目标整理好了，先确认边界，暂时不生成数据。
- 数据集：xxx
- 标签：A -> Agent(tag="A")；B -> Agent(tag="B")
- 边界：一句话说明核心判定规则
- 覆盖：一句话说明主要 case 类型
- 内部：goal_id `...`，revision `...`

你看这个目标是否准确？没问题就回“确认目标”；想改的话直接说哪里不对。

计划 review 也最多展示 6 行，只展示数量、轮次、覆盖、输出路径和确认口令。不要把 goal 的完整内容再次复制到 plan review 中，开头必须说明“目标已确认，现在只补充生成参数，标签边界沿用上一步”。确认口令可以自然一点，例如“如果这个数量和路径可以，就回‘确认，开始生成’；想调整就直接说，比如‘改成 20 条，全单轮’。”

多标签边界数据不要拆成多个互不相关的单标签计划。应该创建一个计划，并在 target_definitions 中列出所有候选标签。例如：

[
  {
    "name": "餐饮服务",
    "target": "Agent(tag=\"餐饮服务\")",
    "rule": "找附近的美食、奶茶、餐厅等，没有明确要求导航。"
  },
  {
    "name": "地图导航",
    "target": "Agent(tag=\"地图导航\")",
    "rule": "明确出现导航去某地点、带我去某地点、路线规划等。"
  }
]

生成 draft text 时，每条 case 的 target: 必须从已确认计划的 target 或 target_definitions[*].target 中选择。不要临时发明新 target。

必须遵守的数据生成协议

不要直接生成 canonical JSON，不要直接导出最终训练/评测格式，不要绕过人类 review。

如果需要生成数据，必须按顺序执行：

用 data_agent_load_input_sources 读取文件。
用 data_agent_render_source_context 把输入渲染成大模型可读 evidence text。
大模型只基于 evidence text 抽取 generation_goal，包括 dataset_label、target_definitions、plan_hint、coverage、exclusions、open_questions、source_refs。
如果目标标签、边界或字段含义不清楚，先用普通回复向用户提问并停止。
如果是手写规则且信息完整，调用 data_agent_prepare_generation_plan，设置 direct_review=true，创建一次确认的 pending 计划，并停止等待用户 review。
如果是文件/示例归纳/歧义场景，调用 data_agent_prepare_generation_goal 创建 pending goal，并停止等待用户 review。
用户确认 generation goal 后，调用 data_agent_confirm_generation_goal 获取 confirmed_goal_id，再调用 data_agent_prepare_generation_plan 创建 pending 计划。
展示计划后停止本轮，等待用户 review。
用户提出修改意见时，调用 data_agent_update_generation_plan，再展示计划。
用户明确确认当前计划版本后，调用 data_agent_confirm_generation_plan。
生成 dataset draft text v1。
调用 data_agent_normalize_dataset_draft，必须传入 confirmed_plan_id。
调用 data_agent_validate_dataset_records。
如果用户要求落盘 canonical records，调用 data_agent_export_dataset_records，output_path 固定传 output/records.jsonl，默认导出紧凑 JSONL，不要用 write_file 手写 JSON。
本阶段默认只推进到 canonical metadata records；除非用户另行要求，不做最终训练/评测格式导出。

数据生成输出格式

当需要生成数据样本时，默认使用 dataset draft text v1，不要直接输出 JSON、JSONL、CSV 或最终表格格式。除非用户明确要求机器可读格式，否则优先输出便于人工 review 的文本格式。

格式

# 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 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 record v1 工作格式：

{
  "record_id": "gen_aabbccdd_000001",
  "source": {
    "type": "generated",
    "request_id": "aabbccdd",
    "timestamp": 1755567930500
  },
  "turn": {
    "query": "本轮 query",
    "timestamp": 1755567930500
  },
  "prev_session": [
    {
      "query": "前一轮 query",
      "tts": "前一轮 tts",
      "timestamp": 1755567870500
    }
  ],
  "context": {},
  "label": {
    "dataset_label": "数据集或专题名称",
    "target": "Agent(tag=\"xxx\")",
    "target_type": "agent"
  },
  "meta": {
    "case_name": "case名称",
    "notes": ""
  }
}

场景工作流

文件定义型

使用 data_agent_load_input_sources 读取用户提供的文件。
如果用户只描述了文件名或主题但没给路径，先询问路径，不要猜。
使用 data_agent_render_source_context 文本化输入资料，必要时用 focus_keywords 缩小到 query、功能点、标签、badcase 相关内容。
大模型基于 evidence text 总结 query 语义、功能点、边界、正例、反例、冲突点和缺失假设。
把标签边界整理为 generation_goal.target_definitions。
如果文档里没有明确 target 格式，向用户确认，例如 Agent(tag="xxx") 还是 function 调用格式。
调用 data_agent_prepare_generation_goal，由工具暂停等待用户 review；用户确认后再调用 data_agent_confirm_generation_goal 和 data_agent_prepare_generation_plan。

手写规则型

直接从用户描述里抽取标签边界。
多标签边界必须使用 target_definitions，不要拆成多个无关单标签计划。
识别规则中的冲突词、优先级和反例。
如果用户已经给出完整 target 表达，直接写入 target_definitions；如果 target 表达不明确，先提出问题。
如果数量、轮次或输出路径未指定，可以由模型给出保守建议，走一次确认模式；不要为了这些默认参数单独多问一轮。
调用 data_agent_prepare_generation_plan，传入 direct_review=true，让用户一次确认目标和生成参数。

示例归纳型

先把 example query / badcase 按意图和可能标签分组。
输出边界归纳和不确定点，不要马上生成数据。
如果 query 没有明确正确标签，必须向用户确认标签或允许的 target 集合。
用户确认后，整理为 generation_goal.target_definitions 和 generation_goal.coverage。
调用 data_agent_prepare_generation_goal 展示 generation_goal 给用户 review；用户确认后再调用 data_agent_confirm_generation_goal 和 data_agent_prepare_generation_plan。

Generation Goal 草案格式

大模型完成产品定义或 badcase 分析后，先输出下面的草案给用户 review：

{
  "dataset_label": "数据集或专题名称",
  "goal_summary": "这批数据要解决什么问题",
  "target_definitions": [
    {
      "name": "标签名称",
      "target": "Agent(tag=\"xxx\") 或 function 调用",
      "rule": "哪些 query 应该进入这个标签",
      "positive_examples": [],
      "negative_examples": [],
      "boundary_notes": [],
      "source_refs": []
    }
  ],
  "plan_hint": "建议先生成 50 条单轮，输出到 output/records.jsonl；具体数量和轮次在 generation plan 中确认。",
  "coverage": "需要覆盖的 query 语义、功能点、错误类型",
  "exclusions": "不要生成或需要排除的表达",
  "open_questions": [],
  "source_refs": []
}

generation_goal 只确认“做什么数据、为什么做、标签边界是什么”。不要在 goal 中维护结构化的 total_count、turn_mix 或 output_path；这些字段属于后续 generation_plan。如果需要在 goal review 阶段提示执行方向，只写一句 plan_hint，例如“建议先生成 50 条单轮，输出到 output/records.jsonl；具体数量和轮次在 generation plan 中确认”。

如果未来增加 data_agent_validate_generation_goal，它只做结构校验和缺失字段提示，不做语义判断，不替代用户 review，也不替代 data_agent_prepare_generation_plan。

现在已经有代码级 goal review 门禁：不要手写 goal 后直接进入 plan，必须先调用 data_agent_prepare_generation_goal，并在用户确认后用 data_agent_confirm_generation_goal 取得 confirmed_goal_id。

输入文本化平台工具

当前前链路只保留三个工具。不要再假设有 data_agent_load_definition_source、data_agent_extract_target_definitions 这类更细工具。

`data_agent_load_input_sources`

读取目录或文件，统一抽取 xlsx/csv/docx/pdf/txt/md/json/jsonl 的段落、表格预览、行数据样例和 source refs。

`data_agent_render_source_context`

把 data_agent_load_input_sources 的结构化结果渲染成大模型可读的 evidence text。产品定义/PRD/走查文档的语义理解应该基于这个文本由大模型完成，不要依赖程序规则直接抽语义。

`data_agent_extract_case_evidence`

从 badcase、评测表、走查表里识别 query、上下文、预期标签、模型预测、类型和备注。字段不明确时，它会返回 required_questions，此时必须向用户确认字段含义。

Portable Scripts

当平台注册工具不可用时，使用 python_exec 执行这些脚本。不要用 bash 执行 Python。

`product_data_normalize_dataset_draft`

脚本：

skills/product-data/scripts/normalize_dataset_draft.py

输入示例：

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

用途：把 dataset draft text v1 转成 canonical records。

`product_data_validate_dataset_records`

脚本：

skills/product-data/scripts/validate_dataset_records.py

输入支持：

{"records": []}

或：

{"records_path": "output/records.jsonl"}

用途：校验 canonical records。

`product_data_export_dataset_records`

脚本：

skills/product-data/scripts/export_dataset_records.py