# label-master（标签大师）

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

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

## 什么时候使用

适合使用这个 skill 的场景：

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

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

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

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

## 核心判断流程

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

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

运行时入口：

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

## 目录结构

```text
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`，再读命中的高频边界卡。

## 维护规则

### 修改标签定义

优先修改：

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

适合改这里的内容：

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

### 修改高频边界

优先修改：

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

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

边界卡建议包含：

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

### 修改输出格式

优先修改：

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

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

### 修改索引

人工可维护：

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

脚本生成，不要手改：

- `knowledge/索引/label_manifest.json`

## 脚本

### 生成 manifest

修改 Markdown 知识后，运行：

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

检查 manifest 是否最新：

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

### 校验 target

校验 Agent 标签：

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

校验 function program：

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

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

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

批量校验 records 文件：

```bash
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。