3步搞定Gopeed插件开发：下载完成事件深度指南

你是否在开发Gopeed扩展插件时，为下载完成事件的处理逻辑感到困惑？本文将通过实战案例，带你从事件注册到功能实现，轻松掌握下载完成事件（OnDone）的处理技巧，让你的插件具备自动分类、通知推送等实用功能。

事件处理基础架构

Gopeed的扩展系统通过事件驱动架构实现插件与主程序的交互。在pkg/download/extension.go中定义了四大核心事件类型：

const (
    EventOnResolve ActivationEvent = "onResolve"  // 链接解析时触发
    EventOnStart   ActivationEvent = "onStart"    // 下载开始时触发
    EventOnError   ActivationEvent = "onError"    // 下载出错时触发
    EventOnDone    ActivationEvent = "onDone"     // 下载完成时触发
)

下载完成事件（EventOnDone）在任务成功结束后自动触发，插件可通过注册该事件实现文件重命名、通知发送、格式转换等后续操作。Gopeed会将包含任务元数据的上下文对象（Context）传递给事件处理函数，结构定义见pkg/download/extension.go#L696-L699。

开发实战：实现下载完成自动分类

1. 插件清单配置

首先创建manifest.json文件，声明插件基本信息和事件订阅：

{
  "name": "file-organizer",
  "author": "gopeed",
  "title": "文件自动分类插件",
  "version": "1.0.0",
  "scripts": [
    {
      "event": "onDone",
      "match": { "urls": ["*"] },
      "entry": "index.js"
    }
  ]
}

• event: "onDone" 声明订阅下载完成事件
• match: { "urls": ["*"] } 匹配所有下载链接
• entry: "index.js" 指定事件处理脚本路径

完整的清单规范可参考官方插件开发文档。

2. 事件处理逻辑实现

创建index.js文件，编写下载完成后的文件分类逻辑：

gopeed.events.onDone(async function (ctx) {
    const task = ctx.task;
    const fileExt = task.name.split('.').pop().toLowerCase();
    
    // 根据文件类型创建分类目录
    let category = "other";
    if (['mp4', 'avi', 'mkv'].includes(fileExt)) {
        category = "videos";
    } else if (['jpg', 'png', 'gif'].includes(fileExt)) {
        category = "images";
    }
    
    // 获取用户配置的下载目录
    const downloadDir = gopeed.settings.get('downloadPath');
    const newPath = `${downloadDir}/${category}/${task.name}`;
    
    // 移动文件到分类目录
    await gopeed.util.moveFile(task.path, newPath);
    
    // 记录分类日志
    gopeed.logger.info(`文件已分类至${category}: ${task.name}`);
});

上述代码实现了：

• 通过ctx.task获取下载任务信息
• 使用gopeed.settings读取用户配置
• 调用gopeed.util工具函数操作文件
• 通过gopeed.logger记录运行日志

3. 本地调试与测试

将插件目录链接到Gopeed的扩展目录进行调试：

ln -s /path/to/your/plugin ~/.config/gopeed/extensions/file-organizer

启动Gopeed后在扩展管理界面启用开发模式，即可实时调试插件。测试用例可参考官方示例插件，该示例展示了如何修改任务标签：

gopeed.events.onDone(async function (ctx) {
    gopeed.logger.info("下载完成:", ctx.task.meta.req.url);
    ctx.task.meta.req.labels['processed'] = 'true';
});

高级应用场景

事件上下文详解

下载完成事件的上下文对象（ctx）包含丰富的任务信息，主要字段如下：

字段路径	类型	说明
ctx.task.id	string	任务唯一标识
ctx.task.name	string	文件名
ctx.task.path	string	文件保存路径
ctx.task.size	number	文件大小(字节)
ctx.task.meta.req.url	string	原始下载链接
ctx.task.progress	number	下载进度(0-100)

完整的上下文结构定义见ExtensionTask类。

跨事件数据共享

使用插件存储API在不同事件间共享数据：

// 在onStart事件中记录开始时间
gopeed.events.onStart(ctx => {
    gopeed.storage.set('startTime', new Date().toISOString());
});

// 在onDone事件中计算下载耗时
gopeed.events.onDone(async ctx => {
    const startTime = new Date(gopeed.storage.get('startTime'));
    const duration = (new Date() - startTime) / 1000;
    gopeed.logger.info(`下载耗时: ${duration}秒`);
});

存储API的实现原理见ContextStorage类，支持键值对的增删改查操作。

常见问题解决

事件不触发排查步骤

1. 检查manifest.json中的event字段是否为"onDone"
2. 确认match规则是否匹配当前下载链接
3. 通过插件日志查看是否有加载错误
4. 验证插件是否在扩展管理界面中启用

权限与安全限制

Gopeed对插件实施严格的安全沙箱限制：

• 文件操作仅允许访问下载目录和系统临时目录
• 网络请求需要在manifest中声明permissions
• 不允许执行系统命令或访问敏感系统资源

详细的安全策略可参考扩展安全文档。

总结与扩展学习

通过本文你已掌握：

• 下载完成事件（OnDone）的注册与处理
• 上下文对象的使用与数据获取
• 插件的调试、测试与部署流程

建议进一步学习：

• 官方插件开发文档
• 事件系统源码实现
• 完整插件示例库

如果你开发了实用的插件，欢迎提交到Gopeed社区仓库，优秀插件将被纳入官方推荐列表！

本文配套示例代码已上传至examples/on-done-demo，包含文件分类、邮件通知等完整功能实现。

通过事件驱动架构，Gopeed插件系统为下载任务提供了强大的扩展能力。无论是简单的文件操作还是复杂的工作流集成，OnDone事件都能满足你的需求。现在就动手开发属于你的第一个Gopeed插件吧！