# 更新日志

{% 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-cn/api/item#comments-object) 只读属性，访问条目的标注数据
* 新增 [`item.addComment(commentData)`](https://developer.eagle.cool/plugin-api/zh-cn/api/item#add-comment) 方法，添加图片框选标注或视频时间轴注解
* 新增 [`item.updateComment(commentId, updateData)`](https://developer.eagle.cool/plugin-api/zh-cn/api/item#update-comment) 方法，更新现有标注
* 新增 [`item.removeComment(commentId)`](https://developer.eagle.cool/plugin-api/zh-cn/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-cn/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-cn/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-cn/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-cn/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-cn/api/tag-group#addtags) - 增量添加或移动标签到群组，不需要传入完整的标签数组
* [`tagGroup.removeTags()`](https://developer.eagle.cool/plugin-api/zh-cn/api/tag-group#removetags) - 从群组移除指定标签
* [`eagle.tag.merge()`](https://developer.eagle.cool/plugin-api/zh-cn/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-cn/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-cn/api/tag#starred) 方法，获取用户收藏的常用标签列表

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

**文档修正**

* 修正 API 方法名称错误：`getRecents()` → [`getRecentTags()`](https://developer.eagle.cool/plugin-api/zh-cn/api/tag#dwsxw)

## 2025年8月21日

### 💻 App API 增强

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

* 新增 [`app.userDataPath`](https://developer.eagle.cool/plugin-api/zh-cn/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-cn/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-cn/api/folder#woenk) 属性从只读变更为可修改
* 新增 [`eagle.folder.IconColor`](https://developer.eagle.cool/plugin-api/zh-cn/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-cn/api/tag#x9nu2) 方法新增 `name` 参数，支持按名称模糊搜索标签
* Tag 实例新增 [`save()`](https://developer.eagle.cool/plugin-api/zh-cn/api/tag#instance-methods) 方法，支持修改标签名称
* 新增 Tag 实例属性：[`name`](https://developer.eagle.cool/plugin-api/zh-cn/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-cn/api/item#bdcw2) 新增 `fields` 参数，支持选择性字段返回，大幅提升查询性能
* 新增 [`eagle.item.getIdsWithModifiedAt()`](https://developer.eagle.cool/plugin-api/zh-cn/api/item#getidswithmodifiedat) 方法，专为增量同步优化
* 新增 [`modifiedAt`](https://developer.eagle.cool/plugin-api/zh-cn/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-cn/api/item#count) - 条件计数
* 新增 [`eagle.item.countAll()`](https://developer.eagle.cool/plugin-api/zh-cn/api/item#countall) - 总文件数
* 新增 [`eagle.item.countSelected()`](https://developer.eagle.cool/plugin-api/zh-cn/api/item#countselected) - 选中文件数
* 新增 [`eagle.item.select(itemIds)`](https://developer.eagle.cool/plugin-api/zh-cn/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-cn/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-cn/api/window#mq0dz) - 获取窗口大小
* 新增 [`eagle.window.setBounds(bounds)`](https://developer.eagle.cool/plugin-api/zh-cn/api/window#setbounds-bounds) - 设置窗口边界（位置+大小）
* 新增 [`eagle.window.getBounds()`](https://developer.eagle.cool/plugin-api/zh-cn/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-cn/api/tag-group#x9nu2) - 创建新标签分组
* 新增 [`tagGroup.save()`](https://developer.eagle.cool/plugin-api/zh-cn/api/tag-group#x9nu2) - 保存修改
* 新增 [`tagGroup.remove()`](https://developer.eagle.cool/plugin-api/zh-cn/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-cn/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-cn/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-cn/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-cn/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-cn/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-cn/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.