docs: add technical architecture guide

2026-05-18 19:28:02 +08:00
parent c4b935692c
commit 3054b3bc6b
53 changed files with 6692 additions and 2234 deletions
@@ -0,0 +1,292 @@
+# 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 获取。