> For the complete documentation index, see [llms.txt](https://developer.eagle.cool/plugin-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.eagle.cool/plugin-api/zh-cn/changelog.md).

# 更新日志

{% hint style="info" %}
已更新：Eagle 4.0 Build12 已正式发布。本文中标注「Eagle 4.0 Build12+」的功能现已可用。 若您仍使用旧版本，请先升级至 4.0 build12 或更高版本。
{% endhint %}

## 2026年7月21日

### 🛡️ 插件审核流程与标准

* 新增[审核流程](/plugin-api/zh-cn/plugin-review/review.md)，说明初步扫描与人工审核两个阶段。
* 新增[审核标准](/plugin-api/zh-cn/plugin-review/criteria.md)，包含七个审核方面：
  * 发布设置与可审核性
  * 商店文案
  * 视觉素材
  * 安全与隐私
  * 安装包内容
  * 文件安全
  * 功能与政策合规
* 新增[审核结果与重新提交](/plugin-api/zh-cn/plugin-review/results.md)，说明未通过原因、修改要求与重新投稿方式。
* 更新准备、打包、发布与更新插件文档，加入新的审核流程与投稿前检查清单。
* 新增 AI 辅助开发责任规范：开发者必须理解、审查并测试提交的全部代码与依赖项。
* 重新整理左侧导航，新增“插件审核”与“上架资源”区块。
* 新标准自 2026 年 7 月 21 日起适用于所有新插件投稿与版本更新。

## 2026年3月24日

### 📄 Item API 增强

**新增功能：标注 CRUD API (Eagle 4.0 build22+)**

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

* 新增 [`item.comments`](/plugin-api/zh-cn/api/item.md#comments-object) 只读属性，访问条目的标注数据
* 新增 [`item.addComment(commentData)`](/plugin-api/zh-cn/api/item.md#add-comment) 方法，添加图片框选标注或视频时间轴注解
* 新增 [`item.updateComment(commentId, updateData)`](/plugin-api/zh-cn/api/item.md#update-comment) 方法，更新现有标注
* 新增 [`item.removeComment(commentId)`](/plugin-api/zh-cn/api/item.md#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`](/plugin-api/zh-cn/api/smart-folder.md) 模块，完整支持智能文件夹管理
* 新增 `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()`](/plugin-api/zh-cn/api/app.md#show) 方法，让插件可以将 Eagle 主应用程序窗口唤起并显示在画面最上方

```javascript
// 将 Eagle 主窗口显示在最上方
await eagle.app.show();
```

### 📄 Item API 增强

**新增功能：修改导入时间 (Eagle 4.0 build18+)**

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

* [`item.importedAt`](/plugin-api/zh-cn/api/item.md#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`](/plugin-api/zh-cn/extra-module/ai-search.md) 模块，提供 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()`](/plugin-api/zh-cn/api/tag-group.md#addtags) - 增量添加或移动标签到群组，不需要传入完整的标签数组
* [`tagGroup.removeTags()`](/plugin-api/zh-cn/api/tag-group.md#removetags) - 从群组移除指定标签
* [`eagle.tag.merge()`](/plugin-api/zh-cn/api/tag.md#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`](/plugin-api/zh-cn/api/tag-group.md) 新增 `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()`](/plugin-api/zh-cn/api/tag.md#starred) 方法，获取用户收藏的常用标签列表

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

**文档修正**

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

## 2025年8月21日

### 💻 App API 增强

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

* 新增 [`app.userDataPath`](/plugin-api/zh-cn/api/app.md#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`](/plugin-api/zh-cn/api/folder.md#woenk) 属性修改支持，允许动态调整文件夹层级结构
* 支持将文件夹移动到不同父目录或根目录

```javascript
// 移动到其他父文件夹
folder.parent = 'parent_folder_id';
await folder.save();

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

**新增功能：文件夹 iconColor 属性可修改 (Eagle 4.0 build12+)**

* 将 [`folder.iconColor`](/plugin-api/zh-cn/api/folder.md#woenk) 属性从只读变更为可修改
* 新增 [`eagle.folder.IconColor`](/plugin-api/zh-cn/api/folder.md#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()`](/plugin-api/zh-cn/api/tag.md#x9nu2) 方法新增 `name` 参数，支持按名称模糊搜索标签
* Tag 实例新增 [`save()`](/plugin-api/zh-cn/api/tag.md#instance-methods) 方法，支持修改标签名称
* 新增 Tag 实例属性：[`name`](/plugin-api/zh-cn/api/tag.md#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()`](/plugin-api/zh-cn/api/item.md#bdcw2) 新增 `fields` 参数，支持选择性字段返回，大幅提升查询性能
* 新增 [`eagle.item.getIdsWithModifiedAt()`](/plugin-api/zh-cn/api/item.md#getidswithmodifiedat) 方法，专为增量同步优化
* 新增 [`modifiedAt`](/plugin-api/zh-cn/api/item.md#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)`](/plugin-api/zh-cn/api/item.md#count) - 条件计数
* 新增 [`eagle.item.countAll()`](/plugin-api/zh-cn/api/item.md#countall) - 总文件数
* 新增 [`eagle.item.countSelected()`](/plugin-api/zh-cn/api/item.md#countselected) - 选中文件数
* 新增 [`eagle.item.select(itemIds)`](/plugin-api/zh-cn/api/item.md#select) - 程序化选择文件

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

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

* [`eagle.item.open()`](/plugin-api/zh-cn/api/item.md#yxkul) 新增 `window` 选项，支持在新窗口打开文件

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

## 2025年7月31日

### 🪟 Window API 扩展

**新增功能：窗口几何控制**

* 新增 [`eagle.window.getSize()`](/plugin-api/zh-cn/api/window.md#mq0dz) - 获取窗口大小
* 新增 [`eagle.window.setBounds(bounds)`](/plugin-api/zh-cn/api/window.md#setbounds-bounds) - 设置窗口边界（位置+大小）
* 新增 [`eagle.window.getBounds()`](/plugin-api/zh-cn/api/window.md#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)`](/plugin-api/zh-cn/api/tag-group.md#x9nu2) - 创建新标签分组
* 新增 [`tagGroup.save()`](/plugin-api/zh-cn/api/tag-group.md#x9nu2) - 保存修改
* 新增 [`tagGroup.remove()`](/plugin-api/zh-cn/api/tag-group.md#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()`](/plugin-api/zh-cn/api/item.md#movetotrash) 实例方法，将文件移至系统回收站

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

## 2024年7月25日

### 🪟 Window API 增强

**新增功能：HTTP Referer 设置**

* 新增 [`eagle.window.setReferer(url)`](/plugin-api/zh-cn/api/window.md#4a6f) 方法，为后续网络请求设置 referer header

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

## 2024年5月10日

### 🖱️ Context Menu API

**新增功能：自定义右键菜单**

* 新增 [`eagle.contextMenu.open()`](/plugin-api/zh-cn/api/context-menu.md#tkp0d) 方法，支持自定义右键菜单
* 支持多层级子菜单、自定义点击事件、系统原生样式

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

### 🪟 Window API 截图功能

**新增功能：页面截图**

* 新增 [`eagle.window.capturePage(rect)`](/plugin-api/zh-cn/api/window.md#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`](/plugin-api/zh-cn/get-started/plugin-types/preview.md) 参数，控制是否允许用户缩放预览内容

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