# 更新日誌

{% hint style="info" %}
已更新：Eagle 4.0 Build12 已正式釋出。本文中標註「Eagle 4.0 Build12+」的功能現已可用。 若您仍使用較舊版本，請先升級至 4.0 build12 或以上版本。
{% endhint %}

## 2026年3月24日

### 📄 Item API 增強

**新增功能：標註 CRUD API (Eagle 4.0 build22+)**

{% hint style="danger" %}
**版本需求**：此功能需要 Eagle 4.0 build22 或更高版本。
{% endhint %}

* 新增 [`item.comments`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#comments-object) 唯讀屬性，存取項目的標註資料
* 新增 [`item.addComment(commentData)`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#add-comment) 方法，新增圖片框選標註或影片時間軸註解
* 新增 [`item.updateComment(commentId, updateData)`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#update-comment) 方法，更新現有標註
* 新增 [`item.removeComment(commentId)`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#remove-comment) 方法，移除標註

```javascript
let item = await eagle.item.getById('item_id');

// 讀取標註
console.log(item.comments);

// 新增圖片框選標註
await item.addComment({ x: 350, y: 480, width: 380, height: 400, annotation: "臉部區域" });

// 新增影片時間軸註解
await item.addComment({ duration: 65.5, annotation: "重要場景" });

// 更新標註
await item.updateComment('comment_id', { annotation: "更新後的文字" });

// 移除標註
await item.removeComment('comment_id');
```

### 📁 Smart Folder API

**新增功能：智慧型資料夾 CRUD API (Eagle 4.0 build22+)**

{% hint style="danger" %}
**版本需求**：此功能需要 Eagle 4.0 build22 或更高版本。
{% endhint %}

* 新增 [`eagle.smartFolder`](https://developer.eagle.cool/plugin-api/zh-tw/api/smart-folder) 模組，完整支援智慧型資料夾管理
* 新增 `create()`、`get()`、`getAll()`、`getById()`、`getByIds()`、`remove()` 方法
* 新增 `getRules()` 方法，取得可用的篩選規則 schema
* 新增 `rule()` 流暢建構器和 `Condition.create()` helper
* SmartFolder 實例支援 `save()` 和 `getItems()` 方法

```javascript
// 使用流暢建構器
const sf = await eagle.smartFolder.create({
    name: '大尺寸圖片',
    conditions: [
        eagle.smartFolder.Condition.create('AND', [
            eagle.smartFolder.rule('width')['>']([1920]),
            eagle.smartFolder.rule('type').equal('png'),
        ])
    ]
});

// 查詢規則 schema
const rules = await eagle.smartFolder.getRules();

// 取得符合條件的項目
const items = await sf.getItems();
```

### 🔧 Manifest 設定增強

**新增功能：followCursor 視窗定位 (Eagle 4.0 build22+)**

{% hint style="danger" %}
**版本需求**：此功能需要 Eagle 4.0 build22 或更高版本。
{% endhint %}

* 新增 `followCursor` manifest 設定，開啟後視窗會自動定位在游標附近
* 適合需要快速互動的工具型插件，讓用戶能以最短距離觸發交互
* 啟用後視窗不會記憶位置，每次開啟都會跟隨游標

```json
{
    "main": {
        "followCursor": true
    }
}
```

## 2026年1月22日

### 💻 App API 增強

**新增功能：顯示主視窗 (Eagle 4.0 build18+)**

{% hint style="danger" %}
**版本需求**：此功能需要 Eagle 4.0 build18 或更高版本。
{% endhint %}

* 新增 [`eagle.app.show()`](https://developer.eagle.cool/plugin-api/zh-tw/api/app#show) 方法，讓插件可以將 Eagle 主應用程序視窗喚起並顯示在畫面最上方

```javascript
// 將 Eagle 主視窗顯示在最上方
await eagle.app.show();
```

### 📄 Item API 增強

**新增功能：修改導入時間 (Eagle 4.0 build18+)**

{% hint style="danger" %}
**版本需求**：此功能需要 Eagle 4.0 build18 或更高版本。
{% endhint %}

* [`item.importedAt`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#importedat-interger) 屬性現在支援修改，讓插件可以自訂檔案的導入時間
* 適用於批次匯入歷史檔案、資料遷移等需要保留原始時間戳記的場景

```javascript
// 修改導入時間
item.importedAt = new Date('2024-01-01').getTime();
await item.save();
```

## 2026年1月9日

### 🔍 AI Search 語意搜尋 API

**新增功能：AI 語意搜尋整合 (Eagle 4.0 build18+)**

* 新增 [`eagle.extraModule.aiSearch`](https://developer.eagle.cool/plugin-api/zh-tw/extra-module/ai-search) 模組，提供 AI 語意搜尋功能
* **狀態查詢方法**：
  * `isInstalled()` - 檢查 AI Search 插件是否已安裝
  * `isReady()` - 檢查服務是否就緒
  * `isStarting()` - 檢查服務是否正在啟動中
  * `isSyncing()` - 檢查是否正在同步資料
* **服務控制方法**：
  * `open()` - 開啟 AI Search 插件
  * `checkServiceHealth()` - 檢查服務健康狀態
  * `getSyncStatus()` - 取得詳細的同步狀態
* **搜尋方法**：
  * `searchByText(query, options)` - 文字語意搜尋
  * `searchByBase64(base64, options)` - Base64 圖片搜尋
  * `searchByItemId(itemId, options)` - 以項目 ID 搜尋相似圖片

```javascript
const aiSearch = eagle.extraModule.aiSearch;

// 檢查服務狀態
if (await aiSearch.isReady()) {
    // 文字語意搜尋
    const result = await aiSearch.searchByText('一隻橘色的貓咪', { limit: 10 });

    // 結果包含完整的 Item 物件
    result.results.forEach(r => {
        console.log(`${r.item.name} - 相似度: ${(r.score * 100).toFixed(1)}%`);
    });
}
```

## 2026年1月8日

### 🏷️ TagGroup/Tag API 增量操作方法

**新增功能：標籤群組增量操作 (Eagle 4.0 build18+)**

* [`tagGroup.addTags()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag-group#addtags) - 增量添加或移動標籤到群組，不需要傳入完整的標籤陣列
* [`tagGroup.removeTags()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag-group#removetags) - 從群組移除指定標籤
* [`eagle.tag.merge()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag#merge) - 合併標籤，將來源標籤重新命名為目標標籤

```javascript
// 添加標籤到群組
await tagGroup.addTags({ tags: ['UI', 'UX'] });

// 移動標籤（從原群組移除）
await tagGroup.addTags({ tags: ['Branding'], removeFromSource: true });

// 從群組移除標籤
await tagGroup.removeTags({ tags: ['Outdated'] });

// 合併標籤
const result = await eagle.tag.merge({ source: 'UI Design', target: 'UI' });
```

### 🏷️ TagGroup API 增強

**新增功能：標籤群組描述屬性 (Eagle 4.0 build18+)**

* [`tagGroup`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag-group) 新增 `description` 屬性，可為標籤群組添加描述文字
* 支援在 `create()` 和 `save()` 方法中設定描述

```javascript
// 建立帶有描述的標籤群組
await eagle.tagGroup.create({
    name: "new group",
    description: "群組描述"
});

// 修改標籤群組描述
tagGroup.description = "新的描述";
await tagGroup.save();
```

## 2026年1月6日

### 🏷️ Tag API 增強

**新增功能：取得常用標籤 (Eagle 4.0 build18+)**

* 新增 [`eagle.tag.getStarredTags()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag#starred) 方法，取得使用者收藏的常用標籤列表

```javascript
const starred = await eagle.tag.getStarredTags();
```

**文件修正**

* 修正 API 方法名稱錯誤：`getRecents()` → [`getRecentTags()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag#dwsxw)

## 2025年8月21日

### 💻 App API 增強

**新增功能：app.userDataPath 屬性 (Eagle 4.0 build12+)**

* 新增 [`app.userDataPath`](https://developer.eagle.cool/plugin-api/zh-tw/api/app#ud9km) 屬性，返回當前使用者資料目錄的路徑
* 提供快速存取 Eagle 使用者資料儲存位置的途徑

```javascript
console.log(eagle.app.userDataPath);
// "C:\Users\User\AppData\Roaming\Eagle"
```

## 2025年8月19日

### 📁 Folder API 增強

**新增功能：資料夾 parent 屬性可修改 (Eagle 4.0 build12+)**

* 新增 [`folder.parent`](https://developer.eagle.cool/plugin-api/zh-tw/api/folder#woenk) 屬性修改支援，允許動態調整資料夾層級結構
* 支援將資料夾移動到不同父目錄或根目錄

```javascript
// 移動到其他父資料夾
folder.parent = 'parent_folder_id';
await folder.save();

// 移動到根目錄  
folder.parent = null;
await folder.save();
```

**新增功能：資料夾 iconColor 屬性可修改 (Eagle 4.0 build12+)**

* 將 [`folder.iconColor`](https://developer.eagle.cool/plugin-api/zh-tw/api/folder#woenk) 屬性從唯讀變更為可修改
* 新增 [`eagle.folder.IconColor`](https://developer.eagle.cool/plugin-api/zh-tw/api/folder#static-properties) 靜態常數物件，提供預定義顏色選項
* 支援的顏色：Red, Orange, Yellow, Green, Aqua, Blue, Purple, Pink

```javascript
folder.iconColor = eagle.folder.IconColor.Blue;
await folder.save();
```

## 2025年8月13日

### 🏷️ Tag API 功能擴展

**新增功能：標籤過濾和 Tag 類別增強**

* [`eagle.tag.get()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag#x9nu2) 方法新增 `name` 參數，支援按名稱模糊搜尋標籤
* Tag 實例新增 [`save()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag#instance-methods) 方法，支援修改標籤名稱
* 新增 Tag 實例屬性：[`name`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag#instance-properties)（可修改）、`count`、`color`、`groups`、`pinyin`

```javascript
// 過濾標籤
const filteredTags = await eagle.tag.get({ name: "design" });

// 修改標籤名稱  
tag.name = 'new-name';
await tag.save();
```

⚠️ **注意：修改標籤名稱會自動更新所有使用該標籤的檔案**

## 2025年8月5日

### 📄 Item API 性能和選擇功能大幅增強

**新增功能：性能優化**

* [`eagle.item.get()`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#bdcw2) 新增 `fields` 參數，支援選擇性欄位返回，大幅提升查詢性能
* 新增 [`eagle.item.getIdsWithModifiedAt()`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#getidswithmodifiedat) 方法，專為增量同步優化
* 新增 [`modifiedAt`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#woenk) 屬性，記錄檔案最後修改時間

```javascript
// 只返回需要的欄位
let items = await eagle.item.get({
    tags: ["Design"],
    fields: ["id", "name", "tags", "modifiedAt"]
});

// 高效增量同步
let fileInfo = await eagle.item.getIdsWithModifiedAt();
```

**新增功能：計數和選擇方法**

* 新增 [`eagle.item.count(options)`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#count) - 條件計數
* 新增 [`eagle.item.countAll()`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#countall) - 總檔案數
* 新增 [`eagle.item.countSelected()`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#countselected) - 選中檔案數
* 新增 [`eagle.item.select(itemIds)`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#select) - 程式化選擇檔案

```javascript
let count = await eagle.item.count({ isSelected: true });
await eagle.item.select(['ITEM_ID_1', 'ITEM_ID_2']);
```

**增強功能：open() 方法**

* [`eagle.item.open()`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#yxkul) 新增 `window` 選項，支援在新視窗開啟檔案

```javascript
await eagle.item.open('item_id', { window: true });
```

## 2025年7月31日

### 🪟 Window API 擴展

**新增功能：視窗幾何控制**

* 新增 [`eagle.window.getSize()`](https://developer.eagle.cool/plugin-api/zh-tw/api/window#mq0dz) - 取得視窗大小
* 新增 [`eagle.window.setBounds(bounds)`](https://developer.eagle.cool/plugin-api/zh-tw/api/window#setbounds-bounds) - 設定視窗邊界（位置+大小）
* 新增 [`eagle.window.getBounds()`](https://developer.eagle.cool/plugin-api/zh-tw/api/window#getbounds) - 取得視窗邊界資訊

```javascript
await eagle.window.getSize();
await eagle.window.setBounds({ x: 440, y: 225, width: 800, height: 600 });
await eagle.window.getBounds();
```

## 2024年11月28日

### 🏷️ TagGroup CRUD 操作

**新增功能：完整的標籤群組管理**

* 新增 [`eagle.tagGroup.create(options)`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag-group#x9nu2) - 創建新標籤群組
* 新增 [`tagGroup.save()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag-group#x9nu2) - 保存修改
* 新增 [`tagGroup.remove()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag-group#x9nu2) - 刪除標籤群組

```javascript
// 創建標籤群組
await eagle.tagGroup.create({
    name: "new group",
    color: "red", 
    tags: ["tag1", "tag2"]
});

// 修改與保存
tagGroup.name = "new name";
await tagGroup.save();

// 刪除群組
await tagGroup.remove();
```

### 🗑️ Item 刪除功能

**新增功能：檔案垃圾桶操作**

* 新增 [`item.moveToTrash()`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#movetotrash) 實例方法，將檔案移至系統垃圾桶

```javascript
let item = await eagle.item.getById('item_id');
await item.moveToTrash();
```

## 2024年7月25日

### 🪟 Window API 增強

**新增功能：HTTP Referer 設定**

* 新增 [`eagle.window.setReferer(url)`](https://developer.eagle.cool/plugin-api/zh-tw/api/window#4a6f) 方法，為後續網路請求設定 referer header

```javascript
eagle.window.setReferer("https://example.com");
```

## 2024年5月10日

### 🖱️ Context Menu API

**新增功能：自定義右鍵選單**

* 新增 [`eagle.contextMenu.open()`](https://developer.eagle.cool/plugin-api/zh-tw/api/context-menu#tkp0d) 方法，支援自定義右鍵選單
* 支援多層次子選單、自定義點擊事件、系統原生樣式

```javascript
eagle.contextMenu.open([
    {
        id: "edit",
        label: "編輯",
        submenu: [...],
        click: () => { ... }
    }
]);
```

### 🪟 Window API 截圖功能

**新增功能：頁面截圖**

* 新增 [`eagle.window.capturePage(rect)`](https://developer.eagle.cool/plugin-api/zh-tw/api/window#yvfx9) 方法，支援全頁或指定區域截圖
* 返回 NativeImage 物件，可轉換為 base64 或 PNG buffer

```javascript
// 全頁截圖
const image = await eagle.window.capturePage();

// 指定區域截圖
const image2 = await eagle.window.capturePage({ 
    x: 0, y: 0, width: 100, height: 50 
});
```

## 2024年4月17日

### 🔍 預覽插件功能增強

**新增功能：縮放控制參數**

* 預覽插件配置新增 [`allowZoom`](https://developer.eagle.cool/plugin-api/zh-tw/get-started/plugin-types/preview) 參數，控制是否允許使用者縮放預覽內容

```json
"thumbnail": {
    "path": "thumbnail/icns.js",
    "size": 400,
    "allowZoom": false
}
```


---

# 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-tw/changelog.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.