Add label master skill

2026-05-09 17:49:53 +08:00
parent 84b715a293
commit 010dc1a88d
166 changed files with 13099 additions and 3 deletions
@@ -0,0 +1,276 @@
+# 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。