Make product-data skill portable

skills/product-data/SKILL.md

@@ -3,13 +3,46 @@ name: product-data
 description: 从产品/标签定义、手写边界规则或示例 query 中提取标签边界，并生成可 review 的数据计划、dataset draft text 和 canonical metadata records。
 when_to_use: 当用户提供产品定义、标签规则、路由边界文档、示例 query、手写标签边界，并希望生成训练/评测/专项数据时使用。
 aliases: definition-data, label-data
-allowed_tools: read_file, write_file, edit_file, grep_search, glob_search, ask_user_question, 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
+allowed_tools: 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 目录内：
+
+```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
+```
+
+在 ZK Data Agent 平台里，优先使用已注册的 `data_agent_*` 工具，因为它们带有平台级 review 状态、确认门禁和会话 output 路由。
+
+迁移到其他 Agent 或没有平台注册能力时，可以直接执行 `scripts/` 下的 portable scripts。脚本支持 `--input input.json` 或 stdin JSON，stdout 只输出一个 JSON 对象。`tools.yaml` 描述了这些脚本如何被平台注册为工具；如果平台不支持 `tools.yaml`，不影响脚本独立使用。
+
+脚本能力和平台注册的关系是：
+
+```text
+脚本能力是本体
+平台注册是适配层
+```
+
+portable scripts 不包含人类 review 状态机。生成式数据仍必须先由 Agent 按本 skill 的 review 门禁获得用户确认，再调用脚本做格式转换、校验和导出。
+
 ## 输入假设
 
 用户可能会提供：
@@ -272,7 +305,7 @@ canonical records 落盘必须使用 `data_agent_export_dataset_records`，默
 
 现在已经有代码级 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` 这类更细工具。
 
@@ -288,6 +321,72 @@ canonical records 落盘必须使用 `data_agent_export_dataset_records`，默
 
 从 badcase、评测表、走查表里识别 query、上下文、预期标签、模型预测、类型和备注。字段不明确时，它会返回 `required_questions`，此时必须向用户确认字段含义。
 
+## Portable Scripts
+
+当平台注册工具不可用时，使用 `python_exec` 执行这些脚本。不要用 `bash` 执行 Python。
+
+### `product_data_normalize_dataset_draft`
+
+脚本：
+
+```text
+skills/product-data/scripts/normalize_dataset_draft.py
+```
+
+输入示例：
+
+```json
+{
+  "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`
+
+脚本：
+
+```text
+skills/product-data/scripts/validate_dataset_records.py
+```
+
+输入支持：
+
+```json
+{"records": []}
+```
+
+或：
+
+```json
+{"records_path": "output/records.jsonl"}
+```
+
+用途：校验 canonical records。
+
+### `product_data_export_dataset_records`
+
+脚本：
+
+```text
+skills/product-data/scripts/export_dataset_records.py
+```
+
+输入支持：
+
+```json
+{
+  "records": [],
+  "output_dir": "output",
+  "output_format": "jsonl"
+}
+```
+
+用途：导出紧凑 JSONL/JSON。默认文件名是 `records.jsonl` 或 `records.json`。
+
 ## 当前可用工具
 
 - `read_file`：读取用户提供的产品定义、标签定义、样例 query 文件。
@@ -296,6 +395,7 @@ canonical records 落盘必须使用 `data_agent_export_dataset_records`，默
 - `grep_search`：在项目中搜索已有标签定义、历史数据样例或相关文档。
 - `glob_search`：按路径模式查找定义文件、样例文件或历史产物。
 - `ask_user_question`：需要用户明确选择或补充关键信息时使用；如果不可用，就用普通回复提问并停止。
+- `python_exec`：仅在已注册 `data_agent_*` 工具不可用、或需要迁移验证 portable scripts 时使用；优先执行 `skills/product-data/scripts/` 下脚本。
 - `data_agent_load_input_sources`：读取用户给的目录或文件，把 docx/xlsx/pdf 等输入统一抽成段落、表格和 source refs。
 - `data_agent_render_source_context`：把结构化输入渲染成大模型可读文本，支持 `max_chars`、表格行数和关键词过滤，用于后续模型语义抽取。
 - `data_agent_extract_case_evidence`：从 badcase/评测/走查表中抽取 query、预期标签、模型预测、上下文和备注；字段歧义会返回需要确认的问题。
@@ -315,5 +415,6 @@ canonical records 落盘必须使用 `data_agent_export_dataset_records`，默
 - 如果 `ask_user_question` 不可用，使用普通回复向用户提问并停止，不要自己替用户确认。
 - canonical records 通过校验前，不要生成最终导出格式。
 - canonical records 需要落盘时，必须用 `data_agent_export_dataset_records`；不要自己拼接 JSON/JSONL；不要创建数据集子目录或自定义 records 文件名。
+- 如果使用 portable scripts，它们只负责格式转换、校验和导出，不替代 `generation_goal` / `generation_plan` 的用户 review。
 - 除非用户明确要求，否则不要把“修改标签定义”和“生成数据”混在一起做。
 - 不要因为用户说“生成一些数据”就跳过边界总结和 generation plan review。