# Agent 搜索 API 文档
面向 agent 提供 pattern 数据库的分类树和元素查询接口

本文档包含三个搜索相关的 API 接口：

1. **关键词搜索** - 根据关键词搜索分类和元素
2. **获取分类树** - 获取指定分类的完整路径和子树
3. **获取全量元素** - 分页浏览元素，支持排序和筛选

---

## 接口 1：关键词搜索

### 接口地址

```
GET http://8.147.104.190:8001/api/agent/search
```

### 功能说明

搜索全局分类库中的分类（Category）和元素（Element），支持文本匹配、上下文扩展、平台筛选等功能。

## 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| q | string | ✓ | - | 搜索关键词 |
| source_type | string | ✓ | - | 元素类型：`实质` / `形式` / `意图` |
| entity_type | string | ✗ | all | 搜索对象类型：`category`（分类）/ `element`（元素）/ `all`（全部） |
| top_k | integer | ✗ | 20 | 返回结果数量，范围 1-100 |
| use_description | boolean | ✗ | false | 是否在描述字段中搜索（true=搜索名称+描述，false=仅搜索名称） |
| execution_id | integer | ✗ | null | 按执行 ID 筛选（可选） |
| platform | string | ✗ | null | 按平台筛选元素（如：`小红书`、`抖音` 等），仅对元素有效 |
| include_ancestors | boolean | ✗ | false | 是否返回祖先路径（从根节点到父节点的完整路径） |
| descendant_depth | integer | ✗ | 0 | 返回 N 代以内的子孙节点，0=不返回，1=直接子节点，2=子节点+孙节点... |

## 返回格式

```json
{
  "success": true,
  "query": "搜索关键词",
  "source_type": "实质",
  "entity_type": "all",
  "count": 3,
  "results": [
    {
      "entity_type": "category",
      "entity_id": 123,
      "stable_id": 456,
      "name": "分类名称",
      "description": "分类描述",
      "path": "/一级分类/二级分类",
      "category_nature": "领域层级",
      "level": 2
    },
    {
      "entity_type": "element",
      "entity_id": 789,
      "name": "元素名称",
      "description": "元素描述",
      "category_path": "/一级分类/二级分类"
    }
  ]
}
```

### 返回字段说明

#### 通用字段
- `success`: 请求是否成功
- `query`: 搜索关键词
- `source_type`: 元素类型
- `entity_type`: 搜索对象类型
- `count`: 返回结果数量
- `results`: 结果列表

#### 结果对象字段（分类 Category）
- `entity_type`: 固定为 "category"
- `entity_id`: 分类数据库 ID
- `stable_id`: 分类稳定 ID（source_stable_id）
- `name`: 分类名称
- `description`: 分类描述
- `path`: 分类路径（如 `/主体/角色类型/人物角色`）
- `category_nature`: 分类性质（领域层级/元描述层级）
- `level`: 层级深度（1=根节点）

#### 结果对象字段（元素 Element）
- `entity_type`: 固定为 "element"
- `entity_id`: 元素数据库 ID
- `name`: 元素名称
- `description`: 元素描述
- `category_path`: 所属分类路径

---

## 使用示例

### 1. 基础搜索

#### 搜索所有（分类+元素）
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色" \
  --data-urlencode "source_type=实质"
```

#### 只搜索分类
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=主体" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=category"
```

#### 只搜索元素
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=猫咪" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "entity_type=element"
```

#### 限制返回数量
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "top_k=5"
```

### 2. 扩展搜索范围

#### 搜索名称+描述
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=拟人" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "use_description=true"
```

### 3. 获取上下文信息

#### 返回祖先路径
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=人物角色" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=category" \
  --data-urlencode "include_ancestors=true"
```

#### 返回1代子孙节点
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=主体" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=category" \
  --data-urlencode "descendant_depth=1"
```

#### 返回2代子孙节点
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=主体" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=category" \
  --data-urlencode "descendant_depth=2"
```

#### 同时返回祖先+子孙
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色类型" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=category" \
  --data-urlencode "include_ancestors=true" \
  --data-urlencode "descendant_depth=2"
```

### 4. 平台筛选

#### 只搜索小红书平台的元素
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=element" \
  --data-urlencode "platform=小红书"
```

#### 搜索抖音平台的元素
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=主体" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "platform=抖音"
```

#### 平台筛选+描述搜索
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=拟人" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "platform=小红书" \
  --data-urlencode "use_description=true"
```

### 5. 组合查询

#### 全功能组合
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=all" \
  --data-urlencode "top_k=10" \
  --data-urlencode "use_description=true" \
  --data-urlencode "include_ancestors=true" \
  --data-urlencode "descendant_depth=1" \
  --data-urlencode "platform=小红书"
```

#### 不同 source_type 的搜索
```bash
# 搜索意图维度
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=情感" \
  --data-urlencode "source_type=意图"

# 搜索形式维度
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=视觉" \
  --data-urlencode "source_type=形式"
```

### 6. 浏览器直接访问

```
http://8.147.104.190:8001/api/agent/search?q=角色&source_type=实质
http://8.147.104.190:8001/api/agent/search?q=主体&source_type=实质&entity_type=category&include_ancestors=true&descendant_depth=2
http://8.147.104.190:8001/api/agent/search?q=猫咪&source_type=形式&platform=小红书
```

### 7. FastAPI 交互式文档

访问以下地址可以在网页上直接测试 API：

```
http://8.147.104.190:8001/docs
```

在文档页面找到 `/api/search` 接口，点击 "Try it out" 按钮，填写参数后点击 "Execute" 即可测试。

---

## 返回示例

### 示例 1：基础搜索

**请求：**
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色" \
  --data-urlencode "source_type=实质"
```

**响应：**
```json
{
  "success": true,
  "query": "角色",
  "source_type": "实质",
  "entity_type": "all",
  "count": 2,
  "results": [
    {
      "entity_type": "category",
      "entity_id": 123,
      "stable_id": 456,
      "name": "角色类型",
      "description": "内容主体的角色分类",
      "path": "/主体/角色类型",
      "category_nature": "领域层级",
      "level": 2,
      "score": 0.95,
      "scores": {
        "text": 0.95,
        "vector": 0.0
      }
    },
    {
      "entity_type": "element",
      "entity_id": 789,
      "name": "人物角色",
      "description": "真实或虚拟的人物形象",
      "belong_category_stable_id": 456,
      "occurrence_count": 25,
      "score": 0.88,
      "scores": {
        "text": 0.88,
        "vector": 0.0
      }
    }
  ]
}
```

### 示例 2：带祖先和子孙的搜索

**请求：**
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色类型" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=category" \
  --data-urlencode "include_ancestors=true" \
  --data-urlencode "descendant_depth=2"
```

**响应：**
```json
{
  "success": true,
  "query": "角色类型",
  "source_type": "实质",
  "entity_type": "category",
  "count": 1,
  "results": [
    {
      "entity_type": "category",
      "entity_id": 123,
      "stable_id": 456,
      "name": "角色类型",
      "description": "内容主体的角色分类",
      "path": "/主体/角色类型",
      "category_nature": "领域层级",
      "level": 2,
      "score": 1.0,
      "scores": {
        "text": 1.0,
        "vector": 0.0
      },
      "ancestors": [
        {
          "stable_id": 1,
          "name": "主体",
          "level": 1
        }
      ],
      "descendants": [
        {
          "stable_id": 500,
          "name": "人物角色",
          "level": 3,
          "depth_from_parent": 1,
          "is_leaf": false
        },
        {
          "stable_id": 501,
          "name": "动物角色",
          "level": 3,
          "depth_from_parent": 1,
          "is_leaf": false
        },
        {
          "stable_id": 600,
          "name": "真人角色",
          "level": 4,
          "depth_from_parent": 2,
          "is_leaf": true
        },
        {
          "stable_id": 601,
          "name": "虚拟角色",
          "level": 4,
          "depth_from_parent": 2,
          "is_leaf": true
        }
      ]
    }
  ]
}
```

### 示例 3：平台筛选

**请求：**
```bash
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=猫咪" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "entity_type=element" \
  --data-urlencode "platform=小红书"
```

**响应：**
```json
{
  "success": true,
  "query": "猫咪",
  "source_type": "形式",
  "entity_type": "element",
  "count": 3,
  "results": [
    {
      "entity_type": "element",
      "entity_id": 1001,
      "name": "猫咪",
      "description": "可爱的猫咪形象",
      "belong_category_stable_id": 200,
      "occurrence_count": 15,
      "score": 1.0,
      "scores": {
        "text": 1.0,
        "vector": 0.0
      }
    },
    {
      "entity_type": "element",
      "entity_id": 1002,
      "name": "猫咪拟人",
      "description": "拟人化的猫咪角色",
      "belong_category_stable_id": 201,
      "occurrence_count": 8,
      "score": 0.85,
      "scores": {
        "text": 0.85,
        "vector": 0.0
      }
    }
  ]
}
```

---

## 错误处理

### 错误响应格式

```json
{
  "detail": "错误信息描述"
}
```

### 常见错误

| HTTP 状态码 | 错误原因 | 解决方法 |
|------------|---------|---------|
| 400 | 缺少必填参数（q 或 source_type） | 检查请求参数 |
| 400 | source_type 值不合法 | 使用 `实质`、`形式` 或 `意图` |
| 400 | entity_type 值不合法 | 使用 `category`、`element` 或 `all` |
| 400 | mode 不支持 | 当前仅支持 `text` 模式 |
| 500 | 服务器内部错误 | 联系技术支持 |

---

## 注意事项

1. **中文参数编码**：使用 curl 时，中文参数需要用 `--data-urlencode` 进行 URL 编码
2. **平台筛选限制**：`platform` 参数仅对元素（element）有效，对分类（category）无效
3. **性能考虑**：
   - `use_description=true` 会增加搜索范围，可能降低精确度
   - `descendant_depth` 越大，返回数据越多，响应时间越长
   - 建议 `top_k` 不超过 50
4. **搜索模式**：当前仅支持 `text` 模式，`vector` 和 `hybrid` 模式将在后续版本中支持
5. **平台名称**：`platform` 参数值需要与数据库中的平台名称完全一致（区分大小写）

---

## 接口 2：获取分类树

### 接口地址

```
GET http://8.147.104.190:8001/api/agent/search/category/{stable_id}
```

### 功能说明

获取指定分类的完整路径和子树结构，用于导航和展示分类层级关系。

### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| stable_id | integer | ✓ | - | 分类的 stable_id（路径参数） |
| source_type | string | ✓ | - | 元素类型：`实质` / `形式` / `意图` |
| include_ancestors | boolean | ✗ | true | 是否返回祖先路径（从根节点到当前节点） |
| descendant_depth | integer | ✗ | -1 | 返回子孙深度，-1=全部，0=仅当前节点，1=子节点，2=子+孙... |

### 返回格式

```json
{
  "success": true,
  "current": {
    "stable_id": 125,
    "name": "吉祥用语",
    "description": "通用的吉祥话语和祝福词句",
    "path": "/表象/符号/表达符号/祝福语/吉祥用语",
    "level": 5
  },
  "ancestors": [
    {
      "stable_id": 38,
      "name": "表象",
      "path": "/表象",
      "level": 1
    },
    {
      "stable_id": 40,
      "name": "符号",
      "path": "/表象/符号",
      "level": 2
    }
  ],
  "descendants": [
    {
      "stable_id": 126,
      "name": "新年祝福",
      "description": "新年相关的祝福语",
      "path": "/表象/符号/表达符号/祝福语/吉祥用语/新年祝福",
      "level": 6,
      "children": []
    }
  ]
}
```

### 使用示例

#### 获取分类的完整路径和所有子孙
```bash
curl -G "http://8.147.104.190:8001/api/agent/search/category/125" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "include_ancestors=true" \
  --data-urlencode "descendant_depth=-1"
```

#### 只获取当前节点和祖先路径
```bash
curl -G "http://8.147.104.190:8001/api/agent/search/category/125" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "include_ancestors=true" \
  --data-urlencode "descendant_depth=0"
```

#### 获取2代子孙节点
```bash
curl -G "http://8.147.104.190:8001/api/agent/search/category/125" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "descendant_depth=2"
```

---

## 接口 3：获取全量元素数据

### 接口地址

```
GET http://8.147.104.190:8001/api/agent/search/elements
```

### 功能说明

获取全量元素数据，支持分页、排序、筛选。主要用于获取高频元素、按分类浏览元素等场景。

### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| source_type | string | ✓ | - | 元素类型：`实质` / `形式` / `意图` |
| execution_id | integer | ✗ | null | 按执行 ID 筛选（可选） |
| page | integer | ✗ | 1 | 页码（从1开始） |
| page_size | integer | ✗ | 50 | 每页数量（1-200） |
| sort_by | string | ✗ | name | 排序字段：`name` / `id` / `occurrence_count` |
| order | string | ✗ | asc | 排序方向：`asc` / `desc` |
| category_path | string | ✗ | null | 按分类路径前缀筛选（可选） |
| platform | string | ✗ | null | 按平台筛选（可选） |
| min_occurrence | integer | ✗ | null | 最小出现次数（可选） |

### 返回格式

```json
{
  "success": true,
  "source_type": "实质",
  "page": 1,
  "page_size": 50,
  "total": 4082,
  "total_pages": 82,
  "results": [
    {
      "id": 45,
      "name": "祝福语",
      "description": "'吉祥如意'、'幸福安康'等文字内容",
      "occurrence_count": 974,
      "element_sub_type": "具象概念",
      "category": {
        "stable_id": 125,
        "name": "吉祥用语",
        "path": "/表象/符号/表达符号/祝福语/吉祥用语"
      }
    }
  ]
}
```

### 使用示例

#### 获取高频元素前50（默认）
```bash
curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质"
```

#### 获取高频元素前10
```bash
curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=10" \
  --data-urlencode "sort_by=occurrence_count" \
  --data-urlencode "order=desc"
```

#### 按名称排序
```bash
curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "sort_by=name" \
  --data-urlencode "order=asc"
```

#### 筛选指定分类下的元素
```bash
curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "category_stable_id=125"
```

#### 筛选出现次数>=10的元素
```bash
curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "min_occurrence=10"
```

#### 按平台筛选元素
```bash
curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "platform=小红书"
```

#### 组合筛选：指定分类+最小出现次数
```bash
curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "category_stable_id=125" \
  --data-urlencode "min_occurrence=50" \
  --data-urlencode "page_size=20"
```

#### 分页浏览
```bash
# 第1页
curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=50"

# 第2页
curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "page=2" \
  --data-urlencode "page_size=50"
```

---