---
name: shb-label
version: "1.0.0"
description: "当用户提到标签相关操作时触发，包括：查询/搜索标签列表、按标签名称找标签ID、按标签过滤工单/事件/客户/产品/备件搜索结果、查询某模块下有哪些标签分组。通过 shb-cli 查询跨模块的智能标签（智能标签分组）列表，是工单/事件/客户/产品/备件搜索按标签过滤的前置依赖：其它模块搜索标签时会指引到本技能。"
metadata:
  requires:
    bins: ["shb-cli"]
  cliHelp: "shb-cli label --help"
---

# label (v1.0)

**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../shb-shared/SKILL.md`](../shb-shared/SKILL.md)，其中包含 profile 初始化、环境选择、OAuth2 登录、token 导入、租户切换、安全规则。所有 label 命令都依赖 `shb-shared` 描述的认证状态。**

## Core Concepts

- **智能标签（标签）**：跨模块的标签体系。标签数据本身独立于业务模块——查标签列表统一走本技能的 `label list`，不属于 task/customer/product/event/part 各自的子命令。
- **biz-type（模块判别）**：查标签时必须用 `--biz-type` 指定"查哪个模块的标签"，目前支持 `task` / `event` / `customer` / `product` / `part`（对应 shb-cli 现有的 5 个业务模块）。**不要猜测传其它值**——warehouse（云仓物料/BOM/替换）、paas 这类模块在智能标签体系里没有对应 bizType，查不了标签。
- **labelId**：标签的唯一标识，来自 `label list` 返回结果里的 `id` 字段。按标签过滤搜索时传的就是这个 id，不是标签名称。
- **标签分组（group）**：标签在后端按分组组织，`label list --format-data` 输出的 `groupName` 列即为所在分组名，纯展示用，过滤搜索时不需要传分组信息。

## 查询标签列表

```bash
# 按名称模糊查（找 labelId 最常用的方式）
shb-cli label list --biz-type task --keyword "紧急" --format-data

# 不传 --keyword 查该模块下全部标签（page-size 默认 1000，足够拿全部）
shb-cli label list --biz-type customer --format-data

# product/event/part 同理，换 --biz-type 即可
shb-cli label list --biz-type product --keyword "重点" --format-data
shb-cli label list --biz-type event --format-data
shb-cli label list --biz-type part --format-data
```

`--format-data` 输出表格：`groupName`（标签分组）/ `id`（标签ID）/ `name`（标签名称）/ `logoColor`（颜色）/ `enabled`（是否启用）。不加 `--format-data` 则输出接口原始响应。

## 按标签过滤 task/event/customer/product/part 搜索

标签过滤不是 `label` 模块自己的能力，而是传给各业务模块搜索命令的 `labelQuery` 字段（只能通过 `--data`/`--file` 传，无对应快捷 flag）：

```json
"labelQuery": {"labelIds": [12345, 67890], "labelExists": null}
```

- `labelIds`：命中任一即可（数组内部 OR），与其他过滤条件（keyword、状态等）是 AND 关系。
- `labelExists`：`false` 表示只查"无标签"的记录；不传或为 `null` 表示不按"有无标签"过滤。

标准两步流程（5 个模块通用，只是搜索命令、`--biz-type` 值和 `--data` 里其它字段名不同）：

```bash
# 1. 用本技能查到 labelId
shb-cli label list --biz-type task --keyword "紧急" --format-data

# 2. 把 labelId 传给对应模块的搜索命令
shb-cli task search --data '{"keyword":"审批","labelQuery":{"labelIds":[12345]}}'
shb-cli event search --data '{"labelQuery":{"labelIds":[12345]}}'
shb-cli customer list --data '{"labelQuery":{"labelIds":[12345]}}'
shb-cli product search --data '{"labelQuery":{"labelIds":[12345]}}'
shb-cli part search --data '{"labelQuery":{"labelIds":[12345]}}'

# 只看"无标签"的记录（以工单为例，其它模块同理）
shb-cli task search --data '{"labelQuery":{"labelExists":false}}'
```

具体某个模块的搜索命令语法/其它过滤字段，见该模块自己的技能文档（`shb-task`/`shb-event`/`shb-customer`/`shb-product`/`shb-part` 的 search reference）。

## 注意

- `--biz-type` 目前只支持 `task`/`event`/`customer`/`product`/`part`；传其它值会直接报错，**不要臆造或猜测其它模块的 biz-type**。
- 标签过滤走 `--data`，没有 `--tag-ids` 之类的快捷 flag。
- labelId 是数字，展示给用户时不需要提及；给用户看的是标签名称（`name`）。
- 若用户只给出标签名称、且当前会话未查过对应 labelId，先用 `label list --keyword <名称>` 查到 id 再过滤，不要凭记忆或猜测编 id。