koishi-plugin-aria2-plus

项目介绍

中文

这是一个为 Koishi 机器人框架开发的 aria2 下载服务插件，通过 HTTP JSON-RPC 与 aria2 守护进程通信，并支持可选的 WebSocket 实时事件推送。插件完全封装了 aria2 的所有核心 JSON-RPC 方法。

English

This is an aria2 download service plugin developed for the Koishi bot framework. It communicates with the aria2 daemon via HTTP JSON-RPC and supports optional WebSocket real-time event push. The plugin fully encapsulates all of aria2's core JSON-RPC methods.

安装

npm install koishi-plugin-aria2-plus

前置要求：
必须先在服务器上安装并启动 aria2 守护进程，并启用 RPC 模式。
示例启动命令：

aria2c --enable-rpc --rpc-listen-all=true --rpc-allow-origin-all --rpc-secret=你的密钥

配置项说明

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | host | string | localhost | aria2 RPC 服务地址 | | port | number | 6800 | aria2 RPC 服务端口 | | secure | boolean | false | 是否使用 HTTPS 连接 | | path | string | /jsonrpc | RPC 接口路径（需与 aria2.conf 中一致） | | secret | string | '' | RPC 密钥（对应 aria2 的 rpc-secret） | | timeout | number | 10000 | 单次请求的超时时间（毫秒） | | retry | number | 2 | 网络错误时的重试次数 | | events | boolean | false | 是否启用下载事件通知。开启后会自动尝试使用 WebSocket，若环境不支持则自动降级为轮询模式（默认每 3 秒检查一次，可通过 pollInterval 调整） | | pollInterval | number | 3000 | 轮询模式下的检查间隔（毫秒，最小 500） | | debug | boolean | false | 是否开启调试日志（打印完整请求与响应） |

在其他插件中使用

本插件作为一个服务（Service）提供，所有封装好的方法都可以通过 ctx.aria2 直接调用。

1. 声明依赖

import { Context } from 'koishi'

export const inject = ['aria2']  // 声明依赖

export function apply(ctx: Context) {
  // 这里可以安全地使用 ctx.aria2
}

2. 基本调用示例

ctx.command('download <url>')
  .action(async ({ session }, url) => {
    const gid = await ctx.aria2.addUri([url], { dir: '/downloads' })
    return `任务已添加，GID: ${gid}`
  })

3. 监听下载事件

ctx.on('aria2/event', (event) => {
  if (event.event === 'complete') {
    // 下载完成后执行操作
  }
})

4. API 方法速查

任务管理

addUri(uris, options?) : Promise<string>
addTorrent(torrent, uris?, options?) : Promise<string>
addMetalink(metalink, options?) : Promise<string>
pause(gid) : Promise<string>
pauseAll() : Promise<string>
forcePause(gid) : Promise<string>
forcePauseAll() : Promise<string>
unpause(gid) : Promise<string>
unpauseAll() : Promise<string>
remove(gid) : Promise<string>
forceRemove(gid) : Promise<string>
changeOption(gid, options) : Promise<string>
changeUri(gid, fileIndex, delUris, addUris) : Promise<string>
getOption(gid) : Promise<Record<string, string>>
changePosition(gid, pos, how) : Promise<number>

状态查询

tellStatus(gid, keys?) : Promise<Aria2Status>
tellActive(keys?) : Promise<Aria2Status[]>
tellWaiting(offset?, num?, keys?) : Promise<Aria2Status[]>
tellStopped(offset?, num?, keys?) : Promise<Aria2Status[]>
tellAll(keys?) : Promise<{active, waiting, stopped}>
getFiles(gid) : Promise<Aria2File[]>
getPeers(gid) : Promise<Record<string, any>[]>
getServers(gid) : Promise<Record<string, any>[]>

全局操作

getGlobalStat() : Promise<GlobalStat>
getGlobalOption() : Promise<Record<string, string>>
changeGlobalOption(options) : Promise<string>
purgeDownloadResult() : Promise<string>
removeDownloadResult(gid) : Promise<string>
getSessionInfo() : Promise<SessionInfo>
saveSession() : Promise<string>
shutdown() : Promise<string>
forceShutdown() : Promise<string>
getVersion() : Promise<{version, enabledFeatures}>
multicall(methods) : Promise<any[]>

所有方法均返回 Promise，并有完整的 TypeScript 类型定义。

依赖关系

• 必需（peerDependencies）：koishi >= 4.18.7
• 可选（optional）：ws（当 events 开启时需要，用于连接 aria2 的 WebSocket）

事件系统

插件支持以下下载事件，可通过 ctx.on('aria2/event', handler) 监听：

| 事件名 | 触发时机 | |--------|----------| | start | 下载任务开始 | | pause | 下载任务暂停 | | stop | 下载任务停止 | | complete | 下载任务完成 | | error | 下载任务出错 | | btComplete | BT 下载完成 |

事件对象格式：{ gid: string, event: string, ...其他字段 }

• WebSocket 模式（推荐）：实时推送，延迟最低
• 轮询模式：当 WebSocket 不可用时自动降级，通过 pollInterval 配置检查间隔，首次轮询仅建立基线，后续增量检测状态变化

项目贡献者 (Contributors)

| 贡献者 | 贡献内容 | |--------|----------| | Minecraft-1314 | 插件完整开发 |

（欢迎通过 Issues 或 PR 成为贡献者）

许可协议 (License)

本项目采用 MIT 许可证，详情参见 LICENSE 文件。

This project is licensed under the MIT License, see the LICENSE file for details.

支持我们 (Support Us)

如果这个项目对您有帮助，欢迎点亮右上角的 Star ⭐ 支持我们，这将是对所有贡献者最大的鼓励！

If this project is helpful to you, please feel free to star it in the upper right corner ⭐ to support us, which will be the greatest encouragement to all contributors!