---
name: list_document_metadata_fields
description: 列出当前知识库文档中使用的元数据字段及其常见取值，用于后续的知识库搜索过滤
triggers:
  - 需要了解知识库中有哪些可用的元数据过滤字段
  - 需要知道某个字段有哪些可选值
  - 构造知识库搜索请求前需要确定过滤条件
  - 用户询问可以按什么条件筛选知识库内容
anti_triggers:
  - 已知可用的过滤字段
  - 不需要元数据过滤
  - 用户问题与知识库无关
tools:
  - list_document_metadata_fields
---

## 使用指南

### 何时使用
当需要了解知识库中有哪些可用的元数据过滤字段时使用。这个工具会返回当前文档中实际使用的元数据字段及其常见取值。

### 何时不使用
当已知可用的过滤字段，或不需要元数据过滤时不需要调用。

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| tenant_id | string | 否 | 租户 ID（系统自动注入） |
| kb_id | string | 否 | 知识库 ID，用于限定范围 |
| include_values | boolean | 否 | 是否包含常见值列表，默认 true |
| top_n | integer | 否 | 每个字段返回的常见值数量，默认 10 |

### 示例调用

```json
{
  "include_values": true,
  "top_n": 5
}
```

### 结果解释

返回结果包含：
- `fields`: 字段列表，每个字段包含：
  - `field_key`: 字段标识
  - `field_type`: 字段类型（string/number/boolean/enum/array_enum）
  - `label`: 字段显示名称
  - `description`: 用途说明
  - `common_values`: 常见取值列表
  - `value_count`: 该字段在多少文档中出现
  - `is_filterable`: 是否可用于过滤
  - `options`: 预定义的可选值（如果有）
- `total_documents`: 文档总数

### 使用场景

1. **构造搜索过滤条件前**
   - 先调用此工具了解可用字段
   - 根据返回的字段信息构造过滤条件

2. **用户询问筛选条件**
   - 用户问"可以按什么条件筛选？"
   - 调用此工具返回可用字段

3. **确定字段取值范围**
   - 需要知道某个字段有哪些可选值
   - 调用此工具获取 common_values

### 注意事项

1. tenant_id 由系统自动注入，模型不要填写
2. 返回的字段是从实际文档中聚合得到的，反映了真实使用情况
3. common_values 是从文档中统计的常见值，不是预定义的可选值
4. 如果字段有预定义的 options，则只能使用 options 中的值
