# AI Search

{% hint style="info" %}
**需要 AI Search 插件。** 此功能需要安装并启用 [AI Search](https://eagle.cool/support/article/ai-search) 插件。
{% endhint %}

***

## AI Search 插件简介

「AI Search」是一款提供 AI 语意搜索功能的插件，支持文字语意搜索、以图搜图等智能搜索能力。通过整合此插件，开发者可以在自己的插件中轻松实现强大的 AI 搜索功能。

### 主要功能

* **文字语意搜索** - 使用自然语言描述，搜索相关图片
* **以图搜图** - 使用图片搜索相似的图片
* **Item ID 搜索** - 根据已有项目搜索相似图片

***

## 如何使用 AI Search

使用 `eagle.extraModule.aiSearch` 来调用 AI Search 插件提供的功能。

### 状态查询

在调用搜索方法前，建议先检查服务状态：

```javascript
eagle.onPluginCreate(async (plugin) => {
    const aiSearch = eagle.extraModule.aiSearch;

    // 检查插件是否已安装
    const isInstalled = await aiSearch.isInstalled();
    console.log('已安装:', isInstalled);

    // 检查服务是否就绪
    const isReady = await aiSearch.isReady();
    console.log('服务就绪:', isReady);

    // 检查是否正在启动中
    const isStarting = await aiSearch.isStarting();
    console.log('启动中:', isStarting);

    // 检查是否正在同步数据
    const isSyncing = await aiSearch.isSyncing();
    console.log('同步中:', isSyncing);
});
```

### 服务控制

```javascript
eagle.onPluginCreate(async (plugin) => {
    const aiSearch = eagle.extraModule.aiSearch;

    // 打开 AI Search 插件（若未安装会提示安装）
    await aiSearch.open();

    // 检查服务健康状态
    const isHealthy = await aiSearch.checkServiceHealth();
    console.log('服务健康:', isHealthy);

    // 获取同步状态详情
    const syncStatus = await aiSearch.getSyncStatus();
    console.log('同步状态:', syncStatus);
});
```

***

## 搜索方法

### searchByText(query, options) - 文字语意搜索

使用自然语言描述搜索相关图片。

* `query` string - 搜索关键字或描述
* `options` Object (可选) - 搜索选项
  * `limit` number - 结果数量限制，默认 20
* 返回 `Promise<Object>` - 搜索结果
  * `results` Array - 搜索结果数组
    * `item` Item - 完整的 Item 对象
    * `score` number - 相似度分数

```javascript
eagle.onPluginCreate(async (plugin) => {
    const aiSearch = eagle.extraModule.aiSearch;

    // 检查服务是否就绪
    if (!await aiSearch.isReady()) {
        console.log('AI Search 服务尚未就绪');
        return;
    }

    // 文字语意搜索
    const result = await aiSearch.searchByText('一只橘色的猫咪', {
        limit: 10
    });

    // 遍历搜索结果
    result.results.forEach(r => {
        console.log('相似度:', r.score);
        console.log('文件名称:', r.item.name);
        console.log('标签:', r.item.tags);
    });
});
```

### searchByBase64(base64, options) - Base64 图片搜索

使用 Base64 编码的图片搜索相似图片。

* `base64` string - Base64 编码的图片字符串
* `options` Object (可选) - 搜索选项
  * `limit` number - 结果数量限制，默认 20
* 返回 `Promise<Object>` - 搜索结果

```javascript
eagle.onPluginCreate(async (plugin) => {
    const aiSearch = eagle.extraModule.aiSearch;

    // 使用 Base64 图片搜索
    const base64Image = 'data:image/jpeg;base64,/9j/4AAQSkZJRg...';
    const result = await aiSearch.searchByBase64(base64Image, {
        limit: 20
    });

    console.log('找到', result.results.length, '个相似图片');

    result.results.forEach(r => {
        console.log(`${r.item.name} - 相似度: ${(r.score * 100).toFixed(1)}%`);
    });
});
```

### searchByItemId(itemId, options) - 以现有项目搜索

使用已存在的 Eagle 项目 ID 搜索相似图片。

* `itemId` string - Eagle 项目 ID
* `options` Object (可选) - 搜索选项
  * `limit` number - 结果数量限制，默认 20
* 返回 `Promise<Object>` - 搜索结果

```javascript
eagle.onPluginCreate(async (plugin) => {
    const aiSearch = eagle.extraModule.aiSearch;

    // 获取当前选中的项目
    const selectedItems = await eagle.item.get({ isSelected: true });

    if (selectedItems.length === 0) {
        console.log('请先选择一个项目');
        return;
    }

    // 使用选中项目的 ID 搜索相似图片
    const result = await aiSearch.searchByItemId(selectedItems[0].id, {
        limit: 30
    });

    console.log('找到', result.results.length, '个相似图片');

    // 结果中的 item 是完整的 Item 对象，可以直接使用其方法
    for (const r of result.results) {
        console.log(`${r.item.name} (${r.item.ext}) - 相似度: ${r.score}`);

        // 可以直接使用 Item 的方法
        // await r.item.save();
    }
});
```

***

## 完整示例

### 创建相似图片搜索功能

```javascript
eagle.onPluginCreate(async (plugin) => {
    const aiSearch = eagle.extraModule.aiSearch;

    // 1. 检查服务状态
    if (!await aiSearch.isInstalled()) {
        // 打开安装提示
        await aiSearch.open();
        return;
    }

    if (!await aiSearch.isReady()) {
        console.log('请等待 AI Search 服务启动完成');
        return;
    }

    // 2. 执行搜索
    try {
        const result = await aiSearch.searchByText('日落时的海滩风景');

        if (result.results.length === 0) {
            console.log('没有找到相关图片');
            return;
        }

        // 3. 处理搜索结果
        const topResults = result.results
            .filter(r => r.score > 0.5)  // 只保留相似度 > 50% 的结果
            .slice(0, 10);               // 取前 10 个

        console.log(`找到 ${topResults.length} 个高相关度图片：`);

        topResults.forEach((r, index) => {
            console.log(`${index + 1}. ${r.item.name}`);
            console.log(`   相似度: ${(r.score * 100).toFixed(1)}%`);
            console.log(`   尺寸: ${r.item.width} x ${r.item.height}`);
            console.log(`   标签: ${r.item.tags.join(', ') || '无'}`);
        });

        // 4. 可以进一步操作这些项目
        // 例如：选中这些项目
        const itemIds = topResults.map(r => r.item.id);
        await eagle.item.select(itemIds);

    } catch (error) {
        console.error('搜索失败:', error.message);
    }
});
```

***

## API 参考

### 状态查询方法

| 方法              | 返回类型               | 说明                   |
| --------------- | ------------------ | -------------------- |
| `isInstalled()` | `Promise<boolean>` | 检查 AI Search 插件是否已安装 |
| `isReady()`     | `Promise<boolean>` | 检查服务是否就绪可用           |
| `isStarting()`  | `Promise<boolean>` | 检查服务是否正在启动中          |
| `isSyncing()`   | `Promise<boolean>` | 检查是否正在同步数据           |

### 服务控制方法

| 方法                     | 返回类型               | 说明              |
| ---------------------- | ------------------ | --------------- |
| `open()`               | `Promise<void>`    | 打开 AI Search 插件 |
| `checkServiceHealth()` | `Promise<boolean>` | 检查服务健康状态        |
| `getSyncStatus()`      | `Promise<Object>`  | 获取详细的同步状态       |

### 搜索方法

| 方法                                 | 返回类型              | 说明            |
| ---------------------------------- | ----------------- | ------------- |
| `searchByText(query, options?)`    | `Promise<Object>` | 文字语意搜索        |
| `searchByBase64(base64, options?)` | `Promise<Object>` | Base64 图片搜索   |
| `searchByItemId(itemId, options?)` | `Promise<Object>` | 以项目 ID 搜索相似图片 |

### 搜索结果格式

```javascript
{
    // ... 其他字段
    results: [
        {
            item: Item,    // 完整的 Item 对象，包含所有属性和方法
            score: number  // 相似度分数 (0-1)
        },
        // ...
    ]
}
```

{% hint style="info" %}
**提示**：搜索结果中的 `item` 是完整的 Item 对象实例，可以直接使用 `save()`、`refreshThumbnail()` 等所有 Item 方法。
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.eagle.cool/plugin-api/zh-cn/extra-module/ai-search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.