zk-data-agent/skills/label-master/README.md

label-master（标签大师）

label-master 是中控标签知识库 skill，中文名“标签大师”。它用于帮助 Agent 理解标签体系、比较标签边界、校验数据生成目标，并把旧标签文档逐步沉淀成可维护、可检索、可校验的 Markdown 知识。

这个目录不是一个黑盒分类器。它的目标是让 Agent 像人工标注同学一样，按步骤阅读知识、收敛候选、解释依据，并在不确定时向人确认。

什么时候使用

适合使用这个 skill 的场景：

• 判断一个 query 应该归属哪个标签。
• 解释两个标签之间的边界。
• 校验数据集里的 target 是否是合法标签、function、intent 或 Agent 包装。
• 为数据生成任务确认标签定义和输出形式。
• 分析线上 badcase 为什么容易混淆。
• 维护中控标签知识、补充边界经验。

不适合使用这个 skill 的场景：

• 直接生成训练集或评测集记录。
• 导出 jsonl、csv、prompt 表格等数据格式。
• 直接查询线上数据。
• 替代人工确认尚未共识的标签迁移方案。

这些能力应由 product-data、online-mining 或其他数据开发 skill 承接。

核心判断流程

标签判断不要直接从关键词跳到最终标签。推荐流程是：

输入理解
  -> 结构维度预判：complex / 多指令 / 自动任务
  -> 候选召回：按动作、对象、资源、设备缩小候选
  -> 业务标签判断：读取标签卡片和高频边界
  -> 输出能力判断：function / intent / object / Agent 包装
  -> 组合最终 target
  -> 不确定则向用户确认

运行时入口：

• SKILL.md：给 Agent 注入的使用协议。
• knowledge/决策流程.md：完整判断顺序。
• knowledge/索引/候选召回索引.md：第一步缩小候选范围。
• knowledge/边界/边界索引.md：高频边界入口。

目录结构

label-master/
  SKILL.md
  README.md
  knowledge/
    决策流程.md
    标签总览.md
    迁移记录.md
    标签迁移索引.md
    索引/
      候选召回索引.md
      标签索引.md
      维度索引.md
      label_manifest.json
    标签/
      ...
    边界/
      README.md
      边界索引.md
      高频混淆/
      领域概览/
    判断维度/
      复杂度判断.md
      多指令判断.md
      自动任务判断.md
      标注输出形态.md
    输出能力/
      README.md
      函数目录.md
      对象目录.md
      意图目录.md
      输出组合规范.md
  scripts/
    build_label_manifest.py
    validate_label_output.py
    迁移_docx标签表.py

知识分层

判断维度/

维护独立于业务标签的判断维度：

• 复杂度判断.md：快慢系统、complex 维度。
• 多指令判断.md：是否需要拆成多个 subquery。
• 自动任务判断.md：条件触发、condition 作用域、自动化任务。
• 标注输出形态.md：最终输出应该是 function、intent、Agent 包装，还是需要确认。

这些维度不要写进每个标签卡片里。

标签/

维护业务标签卡片。每个标签卡片描述：

• 标注输出候选。
• 适用范围。
• 典型 query。
• Function / Agent 说明。
• 满足边界问题。
• 易混淆标签。
• 划分原则。

标签卡片是业务能力知识，不直接决定最终输出格式。

输出能力/

维护最终可消费 target 的能力定义：

• 函数目录.md：function 类型和参数。
• 对象目录.md：Location、Resource、PersonalDate 等 object。
• 意图目录.md：intent 名、承接 Agent 和范围。
• 输出组合规范.md：如何组合 object + function、多指令 JSON、自动任务 JSON。

注意：object 只用于 function 填参，通常不单独作为最终 target。

边界/

维护跨标签混淆经验：

• 高频混淆/：人工维护的高频边界卡，运行时优先读取。
• 领域概览/：从旧标签资料自动迁移出来的领域边界概览，只作为背景补充。

不要直接全量读取 边界/。先读 边界索引.md，再读命中的高频边界卡。

维护规则

修改标签定义

优先修改：

knowledge/标签/<领域>/<标签名>.md

适合改这里的内容：

• 标签适用范围。
• 典型 query。
• Function / Agent 说明。
• 易混淆标签。
• 划分原则。

修改高频边界

优先修改：

knowledge/边界/高频混淆/*.md

如果某类 badcase 或数据生成任务反复出现同一类混淆，应新增一张高频边界卡。

边界卡建议包含：

• 适用场景。
• 候选集合。
• 决策顺序。
• 正例。
• 反例。
• 输出建议。
• 仍需确认的问题。

修改输出格式

优先修改：

knowledge/判断维度/标注输出形态.md
knowledge/输出能力/

不要在单个标签卡片里散落维护 function、intent、object 的全局规则。

修改索引

人工可维护：

• knowledge/索引/候选召回索引.md
• knowledge/边界/边界索引.md

脚本生成，不要手改：

• knowledge/索引/label_manifest.json

脚本

生成 manifest

修改 Markdown 知识后，运行：

python skills/label-master/scripts/build_label_manifest.py

检查 manifest 是否最新：

python skills/label-master/scripts/build_label_manifest.py --check

校验 target

校验 Agent 标签：

python skills/label-master/scripts/validate_label_output.py --target 'Agent(tag="地图导航")'

校验 function program：

python skills/label-master/scripts/validate_label_output.py --target $'x0=Resource(type="DOC")\nSummarize(object=x0)'

校验多指令或自动任务 JSON：

python skills/label-master/scripts/validate_label_output.py --target '[{"condition": null, "querys": [{"subquery": "附近有什么好吃的", "intent": "餐饮服务"}]}]'

批量校验 records 文件：

python skills/label-master/scripts/validate_label_output.py --file output/records.jsonl --field target

校验脚本只检查格式、存在性和引用关系，不负责判断 query 语义是否正确。

旧文件迁移状态

主体标签知识来自 标签定义/Label定义-*.docx，已经迁移为 Markdown 标签卡片。

暂不作为核心知识迁移：

• 标签定义/Agent技术方案汇总.docx：主要是旧 Agent 方案、context 和统计信息，不是标签定义表。
• 标签定义/重构数据标签梳理.xlsx：当前只有一个单元格 老标签，没有有效迁移内容。

旧文档只作为迁移输入和历史参考。后续维护以 knowledge/ 下的 Markdown 为准。

推荐工作流

判断一个 query 的标签

1. 读 knowledge/决策流程.md。
2. 判断是否涉及 complex、多指令、自动任务。
3. 读 knowledge/索引/候选召回索引.md。
4. 读候选标签卡片。
5. 如命中混淆，读 knowledge/边界/边界索引.md 和对应高频边界卡。
6. 如需最终 target，读 knowledge/判断维度/标注输出形态.md 和 knowledge/输出能力/。
7. 输出推荐标签、候选标签、依据、排除项、输出形态和不确定点。

维护一次标签知识

1. 修改标签卡片或高频边界卡。
2. 如新增高频边界，更新 knowledge/边界/边界索引.md。
3. 如新增召回信号，更新 knowledge/索引/候选召回索引.md。
4. 运行 build_label_manifest.py。
5. 用 validate_label_output.py 校验关键 target。

注意事项

• 不要把所有规则都塞进 SKILL.md。SKILL.md 只写 Agent 如何使用知识。
• 不要把 complex、多指令、自动任务写进每个标签卡片。
• 不要默认所有标签都输出 Agent(tag="xxx")。
• 不要手动修改 label_manifest.json。
• 不要长期依赖旧 docx/xlsx，知识确认后应沉淀到 Markdown。