zk-data-agent/docs/technical-architecture/08-label-master.md

08. label-master Skill 实现

1. 定位

label-master 是标签知识和边界分析 Skill。

它不把“给 query 打标签”做成一个黑盒工具，而是让 Agent 逐步读取知识、比较候选、解释依据，并在必要时调用脚本校验最终输出格式。

典型链路：

query / 标签边界问题 / target 校验需求
  -> 读取决策流程
  -> 读取候选召回索引
  -> 找 2-5 个候选标签
  -> 读取候选标签卡片
  -> 命中混淆时读取边界卡
  -> 判断 complex / 多指令 / 自动任务等结构维度
  -> 判断输出形态
  -> 给出推荐、候选、依据、排除项和不确定点
  -> 如要落数据，调用 validate_label_output.py

位置：

skills/label-master/SKILL.md
skills/label-master/knowledge/
skills/label-master/scripts/

2. 知识组织

核心目录：

knowledge/
  标签总览.md
  决策流程.md
  索引/
    候选召回索引.md
    标签索引.md
    维度索引.md
    label_manifest.json
  判断维度/
    复杂度/
    多指令/
    自动任务/
    标注输出形态.md
  输出能力/
  标签/
  边界/
    边界索引.md
    高频混淆/
    领域概览/
  迁移记录.md

设计原则：

索引先行
  不直接读全量标签卡。

维度分离
  complex、多指令、自动任务不是业务标签。

标签卡片中文维护
  方便人工编辑。

输出能力独立
  function、intent、object、Agent 包装放在输出能力层。

边界卡优先人工维护
  高频混淆写清楚，不只依赖自动迁移总结。

3. Agent 使用方式

label-master 的关键在于利用 Agent 的多轮阅读和规划能力。

典型 Agent loop：

模型选择 label-master
  -> read_file knowledge/决策流程.md
  -> read_file knowledge/索引/候选召回索引.md
  -> read_file 候选标签卡片
  -> read_file 高频混淆边界卡
  -> 必要时 read_file 判断维度/复杂度/*
  -> 必要时 read_file 输出能力/*
  -> 输出可 review 判断

为什么不做成单个 classify_query(query) -> label 工具：

• 标签判断常常需要比较候选和排除项。
• function / intent / Agent 包装要看迁移状态。
• complex、多指令、自动任务是独立维度。
• 人类 review 需要看到依据，而不是只看到最终标签。

因此脚本只做索引和校验，不替代语义判断。

4. 输出形态

标签知识中存在多种输出形态：

Agent(tag="xxx")
function program
intent
object + function 组合
多指令 JSON
自动任务 JSON
complex=true/false

complex 是独立维度，不应该混在 target 里。

例如训练输出可以组合成：

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

但内部判断要拆成：

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

5. 脚本能力

5.1 build_label_manifest.py

用途：

把 Markdown 知识生成机器索引。

位置：

skills/label-master/scripts/build_label_manifest.py

输出：

skills/label-master/knowledge/索引/label_manifest.json

使用场景：

• 新增标签卡。
• 修改输出能力。
• 修改判断维度。
• 修改边界知识。

5.2 validate_label_output.py

用途：

校验 target/function/intent/Agent/多指令/自动任务输出格式。

位置：

skills/label-master/scripts/validate_label_output.py

典型调用：

python_exec(script_path="skills/label-master/scripts/validate_label_output.py", args=["--target", "Agent(tag=\"地图导航\")"])

批量校验：

--file output/records.jsonl --field target

6. 和 product-data 的关系

product-data 在需要确认 target 或生成边界数据时，可以读取 label-master 的知识。

分工：

label-master
  判断标签知识、边界、输出形态、target 合法性。

product-data
  做数据生成 review、draft、canonical records、导出。

当用户给出模糊标签名时，应该先用 label-master 辅助确认：

标签是否存在
使用 Agent 包装还是 function
complex 默认是什么
是否有高频混淆边界

再进入 product-data 的生成计划。

7. 设计边界

label-master 负责：

• 标签知识检索。
• 候选标签比较。
• 边界解释。
• 输出形态判断。
• target 格式校验。

不负责：

• 生成数据集。
• 线上日志挖掘。
• 导出训练/评测格式。
• 直接替用户确认争议边界。