AI Search

提供 AI 語意搜尋功能，支援文字搜尋、以圖搜圖等智慧搜尋能力。

此功能尚未發佈：此功能需要 Eagle 4.0 build18+ 版本，並安裝未來的「AI Search」插件才能使用。詳細發佈時間請關注 Eagle 官網。

---

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 方法。