AI Search

提供 AI 语意搜索功能，支持文字搜索、以图搜图等智能搜索能力。

需要 AI Search 插件。 此功能需要安装并启用 AI Search 插件。

---

AI Search 插件简介

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

主要功能

• 文字语意搜索 - 使用自然语言描述，搜索相关图片

• 以图搜图 - 使用图片搜索相似的图片

• Item ID 搜索 - 根据已有项目搜索相似图片

---

如何使用 AI Search

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

状态查询

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

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);
});

服务控制

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 - 相似度分数

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> - 搜索结果

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> - 搜索结果

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();
    }
});

---

完整示例

创建相似图片搜索功能

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 搜索相似图片

搜索结果格式

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

提示：搜索结果中的 item 是完整的 Item 对象实例，可以直接使用 save()、refreshThumbnail() 等所有 Item 方法。