### Getting Started

Source: https://developer.eagle.cool/plugin-api/zh-cn/index

Information on how to begin developing plugins for Eagle, including community resources.

```APIDOC
## Getting Started

### Description

This section covers the initial steps for plugin development and introduces the developer community.

### Resources

- **Developer Community:** Engage with other developers and find support.
- **Get Started Guide:** A step-by-step guide to begin your plugin development journey.

### Links

- [Developer Community](/plugin-api/zh-cn/get-started/dev-community)
```

--------------------------------

### Full Inspector Plugin Configuration in manifest.json

Source: https://developer.eagle.cool/plugin-api/zh-cn/get-started/plugin-types/inspector

This comprehensive `manifest.json` example includes essential plugin metadata and the `preview` configuration, specifying the HTML file path, height, and multi-select behavior for JPG and PNG files.

```json
{
    "id": "cc41e899-5fc3-445c-a113-2d9573d6edcc",
    "version": "1.0.0",
    "platform": "all",
    "arch": "all",
    "name": "Inspector Plugin",
    "logo": "/logo.png",
    "keywords": [],
    "devTools": true,
    "preview": {
        "jpg,png": {
            "inspector": {
                "path": "index.html",
                "height": 100,
                "multiSelect": false
            }
        }
    }
}
```

--------------------------------

### Distribution

Source: https://developer.eagle.cool/plugin-api/zh-cn/index

Guides on how to prepare, package, publish, and update your Eagle plugins.

```APIDOC
## Plugin Distribution

### Description

This section details the process of distributing your Eagle plugins, including preparation, packaging, publishing, updating, and adhering to developer policies.

### Topics

- **Prepare Plugin:** Steps to prepare your plugin for distribution.
- **Package Plugin:** How to package your plugin for the Eagle ecosystem.
- **Publish Plugin:** Guide to publishing your plugin.
- **Update Plugin:** Information on updating existing plugins.
- **Developer Policies:** Guidelines and policies for plugin developers.

### External Resources

- **Plugin Icon Template:** Figma template for creating plugin icons.
  - [Figma Community Link](https://www.figma.com/community/file/1301114081447826240/)
```

--------------------------------

### Get App and System Info - JavaScript

Source: https://context7.com/context7/developer_eagle_cool_plugin-api_zh-cn/llms.txt

This snippet demonstrates how to retrieve various application and system details using the Eagle API. It covers app version, build, locale, architecture, platform, process ID, and checks for specific operating systems or translation environments. It also shows how to get system paths like desktop, documents, and temp directories, access environment variables, and retrieve file icons and generate thumbnails.

```javascript
// 应用基本信息
console.log('Eagle 版本:', eagle.app.version);
console.log('Build 号:', eagle.app.build);
console.log('界面语言:', eagle.app.locale);  // en, zh_CN, zh_TW, ja_JP等
console.log('系统架构:', eagle.app.arch);     // x64, arm64, x86
console.log('操作系统:', eagle.app.platform); // darwin(macOS), win32(Windows)
console.log('进程 ID:', eagle.app.pid);

// 平台判断
if (eagle.app.isWindows) {
    console.log('当前运行在 Windows 系统');
} else if (eagle.app.isMac) {
    console.log('当前运行在 macOS 系统');
}

// Rosetta 转译检测
if (eagle.app.runningUnderARM64Translation) {
    console.warn('当前在 ARM64 转译环境下运行,建议下载原生版本以获得更好性能');
}

// 主题检测
const isDark = eagle.app.isDarkColors();
console.log('当前主题:', eagle.app.theme);
console.log('深色模式:', isDark);

// 获取系统路径
const desktopPath = await eagle.app.getPath('desktop');
const documentsPath = await eagle.app.getPath('documents');
const picturesPath = await eagle.app.getPath('pictures');
const downloadsPath = await eagle.app.getPath('downloads');
const tempPath = await eagle.app.getPath('temp');
const appDataPath = await eagle.app.getPath('appData');

console.log('桌面路径:', desktopPath);
console.log('用户数据路径:', eagle.app.userDataPath);

// 环境变量
console.log('临时目录:', eagle.app.env.TEMP);
console.log('用户主目录:', eagle.app.env.HOME || eagle.app.env.USERPROFILE);

// 获取文件图标
const fileIcon = await eagle.app.getFileIcon('/path/to/file.pdf', {
    size: 'normal'  // small(16x16), normal(32x32), large
});
const iconBase64 = fileIcon.toDataURL();
const iconSize = fileIcon.getSize();

// 生成文件缩略图
const thumbnail = await eagle.app.createThumbnailFromPath('/path/to/image.jpg', {
    width: 400,
    height: 400
});
const thumbnailBuffer = thumbnail.toPNG();
require('fs').writeFileSync('thumbnail.png', thumbnailBuffer);
```

--------------------------------

### Making Network Requests with Node.js https module

Source: https://developer.eagle.cool/plugin-api/zh-cn/tutorial/network-request

When browser security restrictions limit the `fetch` method, Node.js's native network APIs can be used for greater flexibility. The `https.get` method provides a straightforward way to send HTTP GET requests. This example shows how to initiate a GET request and handle the response and potential errors.

```javascript
const https = require('https');

https.get('https://www.example.com', (res) => {
  console.log(`Got response: ${res.statusCode}`);

  res.on('data', (d) => {
    // 处理响应数据
  });

}).on('error', (e) => {
  console.error(`Got error: ${e.message}`);
});
```

--------------------------------

### Example manifest.json for Background Service Plugin

Source: https://developer.eagle.cool/plugin-api/zh-cn/get-started/plugin-types/service

A complete `manifest.json` example for a background service plugin. It includes essential fields like `id`, `version`, `name`, `logo`, and `main` configuration with `serviceMode` set to true. This file defines the plugin's metadata and execution mode.

```json
{
    "id": "LBCZEHP8BBO94",
    "version": "1.0.0",
    "name": "Service Plugin",
    "logo": "/logo.png",
    "keywords": [],
    "main":
    {
        "serviceMode": true,
        "url": "index.html",
        "width": 640,
        "height": 480
    }
}
```

--------------------------------

### Making Network Requests with JavaScript fetch API

Source: https://developer.eagle.cool/plugin-api/zh-cn/tutorial/network-request

The `fetch` function is a versatile tool for accessing network resources and sending HTTP requests. It supports various methods like GET, POST, PUT, and DELETE, and allows customization of request and response bodies. This example demonstrates a simple GET request and how to process the JSON response.

```javascript
fetch('https://example.com/api/endpoint')
    .then(response => response.json())
    .then(data => {
    	// 在这里处理响应
    });
```

--------------------------------

### Clipboard API - Overall Usage

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/clipboard

This section provides an overview of how to use the Clipboard API, including examples for writing and reading text.

```APIDOC
## Clipboard API

This API allows you to interact with the system clipboard.

### Usage Examples

**Writing Text:**
```javascript
await eagle.clipboard.writeText('Example string');
```

**Reading Text:**
```javascript
console.log(await eagle.clipboard.readText());
```

**Writing Buffer:**
```javascript
const buffer = Buffer.from('writeBuffer', 'utf8'); eagle.clipboard.writeBuffer('public/utf8-plain-text', buffer);
```

**Reading Buffer:**
```javascript
const out = eagle.clipboard.readBuffer('public/utf8-plain-text');
```

**Writing Image:**
```javascript
let img = nativeImage.createFromPath('path_to_img_file'); eagle.clipboard.writeImage(img);
```

**Reading Image:**
```javascript
let output = eagle.clipboard.readImage();
```

**Writing HTML:**
```javascript eagle.clipboard.writeHTML('<b>Hi</b>');
```

**Reading HTML:**
```javascript
console.log(eagle.clipboard.readHTML());
```

**Copying Files:**
```javascript eagle.clipboard.copyFiles([
    'path_to_file',
    'path_to_file2'
]);
```
```

--------------------------------

### Invoke FFmpeg Functionality in JavaScript

Source: https://developer.eagle.cool/plugin-api/zh-cn/extra-module/ffmpeg

Use the `eagle.extraModule.ffmpeg` object in your plugin's JavaScript to interact with the FFmpeg dependency. This example demonstrates checking if FFmpeg is installed, prompting installation if not, and retrieving FFmpeg binary paths for execution.

```javascript
eagle.onPluginCreate(async (plugin) => {

    // 检查 FFmpeg 依赖插件是否已经安装
    const isFFemptInstalled = await eagle.extraModule.ffmpeg.isInstalled();
    
    // 从打开插件中心，弹出安装 FFmpeg 依赖插件页面。
    if (!isFFemptInstalled) {
        await eagle.extraModule.ffmpeg.install();
        return;
    }
    
    // 获取 FFmpeg 二进制文件所在位置
    const ffmpegPaths= await eagle.extraModule.ffmpeg.getPaths();
    const ffmpegBinaryPath = ffmpegPaths.ffmpeg;
    const ffprobeBinaryPath = ffmpegPaths.ffprobe;
    
    // 使用 spwan 指令执行相关操作
    const spawn = require('child_process').spawn;
    const ffprobe = spawn(ffprobePath, [
	'-v',
	'error',
	'-print_format',
	'json',
	'-show_format',
	'-show_streams',
	"C:\\your_file.mp4"
    ]);
});
```

--------------------------------

### Access FFmpeg via extraModule in JavaScript

Source: https://developer.eagle.cool/plugin-api/zh-cn/extra-module/ffmpeg

Access FFmpeg functionalities through the `extraModule` object provided to your plugin's entry point. This snippet shows how to get the FFmpeg module, check its installation status, retrieve binary paths, and use `child_process.spawn` to execute `ffprobe`.

```javascript
module.exports = async ({ src, dest, item, plugin, extraModule }) => {
    return new Promise(async (resolve, reject) => {
        try {
        
            const ffmpegModule = extraModule.ffmpeg;
	
            // 检查 FFmpeg 依赖插件是否已经安装
            if (!ffmpegModule.isInstalled) {
		return reject(new Error(`ffmpeg is not installed.`));
	    }
	    
            // 获取 FFmpeg 二进制文件所在位置
            const { ffmpeg, ffprobe } = ffmpegModule.paths;
            
            // 使用 spwan 指令执行相关操作
            const spawn = require('child_process').spawn;
            const ffprobe = spawn(ffprobePath, [
	        '-v',
        	'-print_format',
	        'json',
	        '-show_format',
	        '-show_streams',
	        "C:\\your_file.mp4"
            ]);
            
            return resolve(item);
        }
        catch (err) {
            return reject(err);
        }
    });
}
```

--------------------------------

### Configuring Inspector Plugin for Specific File Types (JPG, PNG)

Source: https://developer.eagle.cool/plugin-api/zh-cn/get-started/plugin-types/inspector

This JSON example demonstrates how to specify the file extensions (e.g., 'jpg,png') for which the inspector plugin should be active within the `manifest.json`.

```json
{
    "preview": {
        "jpg,png": {}
    }
}
```

--------------------------------

### Basic Inspector Plugin Manifest Configuration

Source: https://developer.eagle.cool/plugin-api/zh-cn/get-started/plugin-types/inspector

This JSON snippet shows the minimal `manifest.json` structure required for an inspector plugin, specifically the `preview` property.

```json
{
    "preview": {}
}
```

--------------------------------

### Open a Folder Instance with Eagle API

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/folder

This example shows how to open a specific folder instance directly using its open() method. This is presented as an alternative to using the eagle.folder.open(folderId) method for opening a folder.

```javascript
let folder = await eagle.folder.getById('folder_id');
await folder.open();

// 等价于
await eagle.folder.open('folder_id');
```

--------------------------------

### Structured Object Generation with AI SDK

Source: https://developer.eagle.cool/plugin-api/zh-cn/extra-module/ai-sdk

This JavaScript example illustrates how to use the `generateObject` function to generate structured data based on a provided schema. It includes setting up the model, schema, and messages, demonstrating how to process image inputs and generate tagged outputs.

```javascript
eagle.onPluginCreate(async (plugin) => {
    const ai = eagle.extraModule.ai;
    const { openai } = await ai.getProviders();
    const { generateObject } = ai;

    // 生成结构化数据
    const result = await generateObject({
        model: anthropic("claude-4-sonnet"),
        schema: {
            type: "object",
            properties: {
                tags: {
                    type: "array",
                    items: {
                        type: "object",
                        properties: {
                            name: { type: "string" },
                            reason: { type: "string" },
                        },
                    },
                },
                description: { type: "string" },
            },
        },
        messages: [
            {
                role: "system",
                content: "你是一个专业的图像分析专家，能够准确识别图像内容并给出合适的标签和描述。",
            },
            {
                role: "user",
                content": [
                    {
                        type: "text",
                        text: "请分析这张图片并给出5个相关标签，每个标签需要说明原因，同时提供一个简洁的图片描述。",
                    },
                    {
                        type: "image",
                        image: "https://example.com/sample-image.jpg",
                    },
                ],
            },
        ],
    });

    console.log("标签:", result.object.tags);
    console.log("描述:", result.object.description);
});
```

--------------------------------

### Screen API - Get All Displays

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/screen

Retrieves an array containing information about all available display monitors.

```APIDOC
## GET /screen/all-displays

### Description
Gets an array of Display objects, representing all available screens.

### Method
GET

### Endpoint
/screen/all-displays

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **displays** (Array<Display>) - An array of Display objects, each containing information about an available screen. Refer to Electron's Display structure for details.

#### Response Example
```json
{
  "displays": [
    {
      "id": 1,
      "bounds": {
        "x": 0,
        "y": 0,
        "width": 1920,
        "height": 1080
      },
      "workArea": {
        "x": 0,
        "y": 0,
        "width": 1920,
        "height": 1040
      },
      "size": {
        "width": 1920,
        "height": 1080
      },
      "scaleFactor": 1,
      "isPrimary": true,
      "rotation": 0,
      "depthPerComponent": 24,
      "வுகளில்": false
    },
    {
      "id": 2,
      "bounds": {
        "x": 1920,
        "y": 0,
        "width": 1600,
        "height": 900
      },
      "workArea": {
        "x": 1920,
        "y": 0,
        "width": 1600,
        "height": 860
      },
      "size": {
        "width": 1600,
        "height": 900
      },
      "scaleFactor": 1,
      "isPrimary": false,
      "rotation": 0,
      "depthPerComponent": 24,
      "வுகளில்": false
    }
  ]
}
```
```

--------------------------------

### Create a New Folder with Eagle API

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/folder

This code example shows how to create a new folder using the eagle.folder.create() method. It includes setting the folder's name and description. The method returns a Promise that resolves with the newly created folder object.

```javascript
let newFoler = await eagle.folder.create({
    name: 'New Folder',
    description: 'Folder\'s description.',
});
```

--------------------------------

### Write Text to Clipboard - JavaScript

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/clipboard

A straightforward example of writing a string to the clipboard using the `writeText` method. It also shows how to verify the content by reading it back.

```javascript
eagle.clipboard.writeText('Example string');
console.log(eagle.clipboard.readText()); // 'Example string'
```

--------------------------------

### Flash Window Frame using JavaScript

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/window

Starts or stops flashing the plugin window's frame to attract user attention. Takes a boolean flag as input. Returns a Promise.

```javascript
await eagle.window.flashFrame(true);
await eagle.window.flashFrame(false);
```

--------------------------------

### Get All Available Displays - JavaScript

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/screen

Retrieves an array containing information for all displays currently connected and available to the system. It returns a Promise that resolves to an array of Display objects.

```javascript
let displays = await eagle.screen.getAllDisplays();
```

--------------------------------

### Access Folder Children with JavaScript

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/folder

Shows how to access the array of child folders associated with a given folder object. It includes an example of logging the first child and opening it.

```javascript
let children = folder.children;

console.log(children[0]);
await children[0].open();
```

--------------------------------

### Get System Paths (JavaScript)

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/app

Retrieves various system paths by name, such as home directory, app data, user documents, and more. This method returns a Promise that resolves with the requested path string.

```javascript
await eagle.app.getPath('appData');	// 'C:\Users\User\AppData\Roaming'
await eagle.app.getPath('pictures');	// 'C:\Users\User\Pictures'
await eagle.app.getPath('desktop');	// 'C:\Users\User\Desktop'
```

--------------------------------

### Start File Drag Operation with JavaScript

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/drag

Initiates a file drag operation to display a notification window. It accepts an array of file paths as input and returns a Promise. This function is analogous to Electron's `webContents.startDrag`.

```javascript
await eagle.drag.startDrag([
    "C:\\Users\\User\\Pictures\\drag1.jpg",
    "C:\\Users\\User\\Pictures\\drag2.jpg"
]);
```

--------------------------------

### Get Library Info - JavaScript

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/library

Retrieves detailed information about the current library, including folders, smart folders, and tag groups. It returns a Promise that resolves with a data object containing library attributes. This function has no external dependencies.

```javascript
console.log(await eagle.library.info());
```

--------------------------------

### Read Buffer from Clipboard - JavaScript

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/clipboard

Explains how to read binary data from the clipboard in a specific format using `readBuffer`. It includes an example of writing a buffer and then reading it back to confirm data integrity.

```javascript
const buffer = Buffer.from('this is binary', 'utf8'); eagle.clipboard.writeBuffer('public/utf8-plain-text', buffer);

const out = eagle.clipboard.readBuffer('public/utf8-plain-text');

console.log(buffer.equals(out)); // true
```

--------------------------------

### Tutorials

Source: https://developer.eagle.cool/plugin-api/zh-cn/index

Step-by-step tutorials on various aspects of Eagle plugin development.

```APIDOC
## Tutorials

### Description

This section provides practical tutorials to help you learn and implement various features in Eagle plugin development.

### Tutorial Topics

- **manifest.json Configuration:** Understanding and configuring the `manifest.json` file.
- **Getting Eagle Data:** How to retrieve data from Eagle.
- **Modifying Eagle Data:** How to modify data within Eagle.
- **Accessing Local Files:** Reading and writing to local files.
- **Network Requests:** Making network requests from your plugin.
- **Using Node.js Native API:** Utilizing Node.js capabilities.
- **Using 3rd Party Modules:** Integrating third-party modules.
- **Internationalization (i18n):** Implementing multi-language support.
- **Frameless Window:** Creating frameless windows for your plugin UI.
```

--------------------------------

### Open a Folder by ID with Eagle API

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/folder

This example demonstrates how to open a specific folder in Eagle by its ID using the eagle.folder.open() method. This action brings the specified folder into focus within the application. An alternative approach using the folder instance's open() method is also mentioned.

```javascript
await eagle.folder.open('folder_id');

// 等价于
let folder = await eagle.folder.getById('folder_id');
await folder.open();
```

--------------------------------

### flashFrame API

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/window

Starts or stops flashing the window to get the user's attention.

```APIDOC
## PUT /window/flashFrame

### Description
Starts or stops flashing the window to get the user's attention.

### Method
PUT

### Endpoint
/window/flashFrame

### Parameters
#### Query Parameters
- **flag** (boolean) - Required - Whether to flash the frame.

### Request Example
```json
{
  "flag": true
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates success.

#### Response Example
```json
{
  "message": "Flash frame status updated."
}
```
```

--------------------------------

### Get Currently Selected Folders with Eagle API

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/folder

This code example demonstrates how to get the folders that are currently selected in the Eagle application using the eagle.folder.getSelected() method. It returns a Promise that resolves with an array of selected folder objects.

```javascript
let folders = eagle.folder.getSelected();
```

--------------------------------

### Get OS Type (JavaScript)

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/os

Returns the name of the operating system. For example, it returns 'Darwin' on macOS and 'Windows_NT' on Windows. This function takes no arguments and is useful for platform-specific logic.

```javascript
eagle.os.type();         // 'Windows_NT', 'Darwin'
```

--------------------------------

### 配置插件窗口属性 (JSON)

Source: https://developer.eagle.cool/plugin-api/zh-cn/get-started/plugin-types/window

通过修改`manifest.json`文件中的`main`字段来设置窗口的默认URL、宽度和高度。这些配置决定了插件窗口的初始显示状态。

```json
{
    "main": {}
}
```

```json
{
    "main": {
        "url": "index.html"
    }
}
```

```json
{
    "main": {
        "url": "index.html",
        "width": 640,
        "height": 480
    }
}
```

--------------------------------

### Folder Instance Methods and Properties

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/folder

Details on how to interact with individual Folder objects after retrieval, including saving changes and accessing properties.

```APIDOC
## Class: Folder

### Description
Represents a folder object returned by the Folder API. Allows for modification and saving of folder properties.

### Instance Methods
#### save()

##### Description
Saves all modifications made to the folder instance.

##### Method
`folder.save()`

##### Returns
`Promise<void>`

##### Example
```javascript
let folder = await eagle.folder.getById('folder_id');
folder.name = 'New Folder Name';
await folder.save();
```

#### open()

##### Description
Opens the folder instance in the Eagle application.

##### Method
`folder.open()`

##### Returns
`Promise<void>`

##### Example
```javascript
let folder = await eagle.folder.getById('folder_id');
await folder.open();
```

### Instance Properties

- **`id`** (string, Readonly)
  - The unique identifier for the folder.

- **`name`** (string)
  - The name of the folder. Can be modified.

- **`description`** (string)
  - The description of the folder. Can be modified.

- **`icon`** (string, Readonly)
  - The path to the folder's icon.

- **`iconColor`** (string)
  - The color of the folder's icon. Can be modified.

  #### Example
  ```javascript
  let folder = await eagle.folder.getById('folder_id');
  folder.iconColor = eagle.folder.IconColor.Red; // or 'red'
  await folder.save();
  ```

- **`createdAt`** (Integer, Readonly)
  - The timestamp indicating when the folder was created.

  #### Example
  ```javascript
  let date = new Date(folder.createdAt);
  ```
```

--------------------------------

### Get Library Name - JavaScript

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/library

Accesses the `name` property of the `library` module to get the current library's name. This is a direct property access and has no input or output other than the string name. No external dependencies are required.

```javascript
console.log(eagle.library.name)
// test
```

--------------------------------

### Plugin Lifecycle Events

Source: https://context7.com/context7/developer_eagle_cool_plugin-api_zh-cn/llms.txt

Manage the lifecycle of your Eagle plugin by responding to events such as creation, running, and before exit. This section also covers listening for library and theme changes.

```APIDOC
## Plugin Lifecycle Events

### Description

Manage the lifecycle of your Eagle plugin by responding to events such as creation, running, and before exit. This section also covers listening for library and theme changes.

### Method

Event Listeners

### Endpoint

N/A (Event-driven)

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example

```javascript
// Plugin initialization - get plugin configuration information eagle.onPluginCreate(async (plugin) => {
    console.log('Plugin Name:', plugin.manifest.name);
    console.log('Plugin Version:', plugin.manifest.version);
    console.log('Plugin Path:', plugin.path);

    // Initialize database connections, load configurations, etc.
    await initializePlugin();
 });

// Plugin run - triggered when the user clicks on the plugin eagle.onPluginRun(() => {
    console.log('User launched the plugin');
    showMainInterface();
 });

// Before plugin exit - clean up resources eagle.onPluginBeforeExit(() => {
    console.log('Plugin is about to exit, saving data...');
    saveUserData();
 });

// Prevent window from closing window.onbeforeunload = (event) => {
    if (hasUnsavedChanges()) {
        return event.returnValue = false;
    }
 };

// Library change listener eagle.onLibraryChanged((libraryPath) => {
    console.log('Library has changed:', libraryPath);
    reloadLibraryData(libraryPath);
 });

// Theme change listener eagle.onThemeChanged((theme) => {
    console.log('Theme changed to:', theme);
    applyTheme(theme);
 });
```

### Response

#### Success Response (200)

N/A (Event handlers do not return explicit responses in this format)

#### Response Example

N/A
```

--------------------------------

### 系统剪贴板操作 (Clipboard API)

Source: https://context7.com/context7/developer_eagle_cool_plugin-api_zh-cn/llms.txt

使用 Eagle Plugin API 进行系统剪贴板的读写操作，支持文本、HTML、图片、Buffer 和文件。提供 `writeText`, `readText`, `writeHTML`, `readHTML`, `writeImage`, `readImage`, `writeBuffer`, `readBuffer`, `copyFiles` 等方法。需引入 'electron' 模块处理图片。

```javascript
// 文本操作 eagle.clipboard.writeText('Eagle Plugin API 示例代码');
const text = eagle.clipboard.readText();
console.log('剪贴板文本:', text);

// 清空剪贴板 eagle.clipboard.clear();

// HTML 操作 eagle.clipboard.writeHTML('<h1>标题</h1><p>这是一段<strong>富文本</strong>内容</p>');
const html = eagle.clipboard.readHTML();
console.log('剪贴板 HTML:', html);

// 图片操作
const { nativeImage } = require('electron');
const image = nativeImage.createFromPath('/path/to/image.png');
 eagle.clipboard.writeImage(image);

const clipboardImage = eagle.clipboard.readImage();
const imageBuffer = clipboardImage.toPNG();
require('fs').writeFileSync('clipboard_image.png', imageBuffer);

// Buffer 操作
const buffer = Buffer.from('自定义数据格式', 'utf8');
 eagle.clipboard.writeBuffer('application/custom-format', buffer);

if (eagle.clipboard.has('application/custom-format')) {
    const readBuffer = eagle.clipboard.readBuffer('application/custom-format');
    console.log('读取成功:', buffer.equals(readBuffer));
}

// 复制文件到剪贴板
const selectedItems = await eagle.item.getSelected();
const filePaths = selectedItems.map(item => item.filePath);
 eagle.clipboard.copyFiles(filePaths);
console.log(`已复制 ${filePaths.length} 个文件到剪贴板`);

// 实现"复制为 Markdown"功能
async function copyAsMarkdown() {
    const items = await eagle.item.getSelected();
    const markdown = items.map(item => {
        return `![${item.name}](${item.filePath})
*${item.annotation || '无描述'}*
标签: ${item.tags.join(', ')}`;
    }).join('

---

');

 eagle.clipboard.writeText(markdown);
    await eagle.notification.show({
        title: '已复制',
        body: `${items.length} 个文件已复制为 Markdown 格式`,
        duration: 2000
    });
}
```

--------------------------------

### Screen API - Get Primary Display

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/screen

Retrieves information about the primary display monitor.

```APIDOC
## GET /screen/primary-display

### Description
Gets information about the primary display monitor.

### Method
GET

### Endpoint
/screen/primary-display

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **display** (Display) - An object representing the primary display's information. Refer to Electron's Display structure for details.

#### Response Example
```json
{
  "display": {
    "id": 1,
    "bounds": {
      "x": 0,
      "y": 0,
      "width": 1920,
      "height": 1080
    },
    "workArea": {
      "x": 0,
      "y": 0,
      "width": 1920,
      "height": 1040
    },
    "size": {
      "width": 1920,
      "height": 1080
    },
    "scaleFactor": 1,
    "isPrimary": true,
    "rotation": 0,
    "depthPerComponent": 24,
    "வுகளில்": false
  }
}
```
```

--------------------------------

### library.info()

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/library

Retrieves detailed information about the current library, including folders, smart folders, and tag groups.

```APIDOC
## GET /library/info

### Description
Retrieves detailed information about the current library, including folders, smart folders, and tag groups.

### Method
GET

### Endpoint
/library/info

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **data** (Object) - An object containing various properties of the library.
  - **folders** (Array) - List of folders in the library.
  - **smartFolders** (Array) - List of smart folders in the library.
  - **tagGroups** (Array) - List of tag groups in the library.

#### Response Example
```json
{
  "data": {
    "folders": [...],
    "smartFolders": [...],
    "tagGroups": [...] 
  }
}
```
```

--------------------------------

### Folder Management API

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/folder

This section covers the core functionalities of the Folder API, including creating, retrieving, and managing folders.

```APIDOC
## POST /api/folders/create

### Description
Creates a new folder.

### Method
POST

### Endpoint
`/api/folders/create`

### Parameters
#### Request Body
- **name** (string) - Required - The name of the folder.
- **description** (string) - Optional - The description of the folder.
- **parent** (string) - Optional - The ID of the parent folder to create a subfolder.

### Request Example
```json
{
  "name": "New Folder",
  "description": "Folder's description."
}
```

### Response
#### Success Response (200)
- **folder** (Folder) - The newly created folder object.

#### Response Example
```json
{
  "folder": {
    "id": "folder_id",
    "name": "New Folder",
    "description": "Folder's description.",
    "icon": "icon_path",
    "iconColor": "default_color",
    "createdAt": 1678886400
  }
}
```

## POST /api/folders/createSubfolder

### Description
Creates a new subfolder within a specified parent folder.

### Method
POST

### Endpoint
`/api/folders/createSubfolder`

### Parameters
#### Request Body
- **parentId** (string) - Required - The ID of the parent folder.
- **options** (object) - Required - Options for creating the subfolder.
  - **name** (string) - Required - The name of the subfolder.
  - **description** (string) - Optional - The description of the subfolder.

### Request Example
```json
{
  "parentId": "parent_folder_id",
  "options": {
    "name": "Subfolder",
    "description": "Subfolder description."
  }
}
```

### Response
#### Success Response (200)
- **folder** (Folder) - The newly created subfolder object.

#### Response Example
```json
{
  "folder": {
    "id": "subfolder_id",
    "name": "Subfolder",
    "description": "Subfolder description.",
    "icon": "icon_path",
    "iconColor": "default_color",
    "createdAt": 1678886400
  }
}
```

## GET /api/folders/get

### Description
Retrieves folders based on specified criteria.

### Method
GET

### Endpoint
`/api/folders/get`

### Parameters
#### Query Parameters
- **id** (string) - Optional - The ID of the folder to retrieve.
- **ids** (string[]) - Optional - An array of folder IDs to retrieve.
- **isSelected** (boolean) - Optional - Filter by folders that are currently selected.
- **isRecent** (boolean) - Optional - Filter by recently accessed folders.

### Response
#### Success Response (200)
- **folders** (Folder[]) - An array of folder objects matching the criteria.

#### Response Example
```json
{
  "folders": [
    {
      "id": "folder_id1",
      "name": "Folder 1",
      "description": "Description 1",
      "icon": "icon_path1",
      "iconColor": "color1",
      "createdAt": 1678886400
    },
    {
      "id": "folder_id2",
      "name": "Folder 2",
      "description": "Description 2",
      "icon": "icon_path2",
      "iconColor": "color2",
      "createdAt": 1678886401
    }
  ]
}
```

## GET /api/folders/getAll

### Description
Retrieves all folders available in the application.

### Method
GET

### Endpoint
`/api/folders/getAll`

### Response
#### Success Response (200)
- **folders** (Folder[]) - An array of all folder objects.

#### Response Example
```json
{
  "folders": [
    {
      "id": "folder_id1",
      "name": "Folder 1",
      "description": "Description 1",
      "icon": "icon_path1",
      "iconColor": "color1",
      "createdAt": 1678886400
    }
  ]
}
```

## GET /api/folders/getById

### Description
Retrieves a specific folder by its ID.

### Method
GET

### Endpoint
`/api/folders/getById`

### Parameters
#### Query Parameters
- **folderId** (string) - Required - The ID of the folder to retrieve.

### Response
#### Success Response (200)
- **folder** (Folder) - The folder object corresponding to the provided ID.

#### Response Example
```json
{
  "folder": {
    "id": "folder_id",
    "name": "Specific Folder",
    "description": "This is the specific folder.",
    "icon": "icon_path",
    "iconColor": "default_color",
    "createdAt": 1678886400
  }
}
```

## GET /api/folders/getByIds

### Description
Retrieves multiple folders by their IDs.

### Method
GET

### Endpoint
`/api/folders/getByIds`

### Parameters
#### Query Parameters
- **folderIds** (string[]) - Required - An array of folder IDs.

### Response
#### Success Response (200)
- **folders** (Folder[]) - An array of folder objects corresponding to the provided IDs.

#### Response Example
```json
{
  "folders": [
    {
      "id": "folder_id1",
      "name": "Folder 1",
      "description": "Description 1",
      "icon": "icon_path1",
      "iconColor": "color1",
      "createdAt": 1678886400
    },
    {
      "id": "folder_id2",
      "name": "Folder 2",
      "description": "Description 2",
      "icon": "icon_path2",
      "iconColor": "color2",
      "createdAt": 1678886401
    }
  ]
}
```

## GET /api/folders/getSelected

### Description
Retrieves the currently selected folder(s) in the Eagle application.

### Method
GET

### Endpoint
`/api/folders/getSelected`

### Response
#### Success Response (200)
- **folders** (Folder[]) - An array of selected folder objects.

#### Response Example
```json
{
  "folders": [
    {
      "id": "selected_folder_id",
      "name": "Selected Folder",
      "description": "This is the selected folder.",
      "icon": "icon_path",
      "iconColor": "default_color",
      "createdAt": 1678886400
    }
  ]
}
```

## GET /api/folders/getRecents

### Description
Retrieves the recently accessed folders.

### Method
GET

### Endpoint
`/api/folders/getRecents`

### Response
#### Success Response (200)
- **folders** (Folder[]) - An array of recently accessed folder objects.

#### Response Example
```json
{
  "folders": [
    {
      "id": "recent_folder_id1",
      "name": "Recent Folder 1",
      "description": "Description 1",
      "icon": "icon_path1",
      "iconColor": "color1",
      "createdAt": 1678886400
    }
  ]
}
```

## POST /api/folders/open

### Description
Opens a specific folder in the Eagle application.

### Method
POST

### Endpoint
`/api/folders/open`

### Parameters
#### Request Body
- **folderId** (string) - Required - The ID of the folder to open.

### Request Example
```json
{
  "folderId": "folder_to_open_id"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the folder was opened successfully.

#### Response Example
```json
{
  "message": "Folder opened successfully."
}
```
```

--------------------------------

### Get Execution Path (JavaScript)

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/app

Retrieves the absolute path of the currently executing application. This is useful for locating application resources or configuration files.

```javascript
console.log(eagle.app.execPath);

"C:\\Program Files\\Eagle\\Eagle.exe"
```

--------------------------------

### Screen API - Get Display Nearest Point

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/screen

Retrieves information about the display monitor nearest to a specified point (x, y).

```APIDOC
## POST /screen/nearest-display

### Description
Gets the display monitor that is nearest to the specified point (x, y).

### Method
POST

### Endpoint
/screen/nearest-display

### Parameters
#### Request Body
- **point** (Object) - Required - The point to check.
  - **point.x** (Integer) - Required - The x-coordinate of the point.
  - **point.y** (Integer) - Required - The y-coordinate of the point.

### Request Example
```json
{
  "point": {
    "x": 100,
    "y": 100
  }
}
```

### Response
#### Success Response (200)
- **display** (Display) - An object representing the nearest display's information. Refer to Electron's Display structure for details.

#### Response Example
```json
{
  "display": {
    "id": 1,
    "bounds": {
      "x": 0,
      "y": 0,
      "width": 1920,
      "height": 1080
    },
    "workArea": {
      "x": 0,
      "y": 0,
      "width": 1920,
      "height": 1040
    },
    "size": {
      "width": 1920,
      "height": 1080
    },
    "scaleFactor": 1,
    "isPrimary": true,
    "rotation": 0,
    "depthPerComponent": 24,
    "வுகளில்": false
  }
}
```
```

--------------------------------

### Configure Preview for Multiple File Formats (JSON)

Source: https://developer.eagle.cool/plugin-api/zh-cn/get-started/plugin-types/preview

Defines how to extend Eagle's preview capabilities for multiple file formats like ICNS and ICO within the `manifest.json` file. It specifies paths to thumbnail generation scripts and viewer HTML files.

```json
{
    "id": "LARSKLB8OTOC2",
    "version": "1.0.0",
    "platform": "all",
    "arch": "all",
    "name": "Preview Plugin",
    "logo": "/logo.png",
    "keywords": [
        "icns"
    ],
    "devTools": false,
    "preview": {
        "icns,ico": {
            "thumbnail": {
                "path": "thumbnail/icns.js",
                "size": 400,
                "allowZoom": false
            },
            "viewer": {
                "path": "viewer/icns.html"
            }
        }
    }
}
```

--------------------------------

### Screen API - Get Cursor Screen Point

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/screen

Retrieves the absolute screen coordinates (x, y) of the current mouse cursor.

```APIDOC
## GET /screen/cursor

### Description
Gets the absolute position (x, y) of the current mouse cursor.

### Method
GET

### Endpoint
/screen/cursor

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **point** (Object) - An object containing the x and y coordinates of the cursor.
  - **point.x** (Integer) - The x-coordinate of the cursor.
  - **point.y** (Integer) - The y-coordinate of the cursor.

#### Response Example
```json
{
  "point": {
    "x": 100,
    "y": 200
  }
}
```
```

--------------------------------

### Native Dialogs for File Selection and Saving

Source: https://developer.eagle.cool/plugin-api/zh-cn/tutorial/access-local-files

Utilize the `eagle.dialog` module to present native system dialogs for opening files or directories, and for saving files.

```APIDOC
## Native Dialogs

### Description
This API allows plugins to interact with the user through native system dialogs for selecting files/directories to open or specifying a location to save files.

### Method
Asynchronous (using `await`)

### Endpoint
`eagle.dialog` module

### Parameters
#### `showOpenDialog` Parameters
- **options** (Object) - Configuration for the open dialog.
  - **properties** (Array) - An array of strings specifying the type of dialog. Common values include `'openFile'` and `'openDirectory'`.

#### `showSaveDialog` Parameters
- **options** (Object) - Configuration for the save dialog.
  - **properties** (Array) - An array of strings specifying the type of dialog. Common values include `'openDirectory'`.

### Request Example
```javascript
// Example 1: Show file/directory open dialog
let openResult = await eagle.dialog.showOpenDialog({
    properties: ['openFile', 'openDirectory']
});

// Example 2: Show file save dialog
let saveResult = await eagle.dialog.showSaveDialog({
    properties: ['openDirectory']
});
```

### Response
#### Success Response (N/A)
- **openResult / saveResult** (Array | String | null) - The result from the dialog. This typically contains the path(s) selected by the user or `null` if the dialog was cancelled.

#### Response Example
```json
// For showOpenDialog with properties: ['openFile'], result might be:
// ["/path/to/selected/file.png"]
// For showSaveDialog, result might be:
// "/path/to/save/new_file.png"
// If cancelled, result will be null.
```

### Further Information
For a comprehensive guide, refer to the [dialog module documentation](https://developer.eagle.cool/plugin-api/zh-cn/api/dialog).
```

--------------------------------

### Get Environment Variables (JavaScript)

Source: https://developer.eagle.cool/plugin-api/zh-cn/api/app

Retrieves an object containing the environment variables of the application. You can access individual environment variables using bracket notation.

```javascript
console.log(eagle.app.env);

{
  APPDATA: "C:\\Users\\User\\AppData\\Roaming",
  HOMEDRIVE: "C:",
  HOMEPATH: "\\Users\\User",
  LANG: "zh_TW.UTF-8",
  TEMP: "C:\\Users\\User\\AppData\\Local\\Temp"
}
```

```javascript
console.log(eagle.app.env['TEMP']);

"C:\\Users\\User\\AppData\\Local\\Temp"
```