aria2-rpc：通过 JSON-RPC 2.0 协议远程控制 aria2 下载管理器

名称： aria2-json-rpc
描述： 通过 JSON-RPC 2.0 与 aria2 下载管理器交互。使用自然语言命令管理下载、查询状态和控制任务。适用于 aria2 操作、下载管理或种子任务。
许可证： MIT
compatibility: 需要 Python 3.6+。WebSocket 支持需要 websockets 包 (pip install websockets)，且 Python 版本需满足依赖要求。
元数据：
author: ISON
version: "1.1.0"

功能概述

本技能使您能够通过自然语言命令控制 aria2 下载管理器：
- 下载文件（HTTP/HTTPS/FTP/Magnet/种子/Metalink）
- 监控下载进度和状态
- 控制下载（暂停、恢复、移除）
- 管理批量操作（暂停所有、恢复所有）
- 查看统计信息和配置选项

使用方法（面向 AI 助手）

⚠️ 关键：切勿手动构造 JSON-RPC 请求。

✅ 务必使用 scripts/ 目录中的 Python 脚本。

⚠️ 重要：使用 python3 命令，而非 python（尤其在 macOS 上，python 符号链接可能不存在）

工作流程（必须遵循）

步骤 1：检查配置状态

在执行任何 aria2 命令前，务必检查配置是否就绪：

python3 scripts/config_loader.py test

• 若成功：继续执行用户命令
• 若失败：引导用户初始化配置（见步骤 2）

步骤 2：初始化配置（如需要）

若连接测试失败，引导用户设置配置：

# 推荐：用户配置（技能更新后仍保留）
python3 scripts/config_loader.py init --user

# 备选：本地配置（项目特定）
python3 scripts/config_loader.py init --local

然后指导用户编辑生成的配置文件，填入其 aria2 服务器信息。

步骤 3：执行用户命令

配置就绪后，执行请求的 aria2 操作。

示例流程

用户： "下载 http://example.com/file.zip"

您执行：

# 1. 检查配置
python3 scripts/config_loader.py test

若测试通过：

# 2. 执行下载命令
python3 scripts/rpc_client.py aria2.addUri '["http://example.com/file.zip"]'

您回复： "✓ 下载已启动！GID：2089b05ecca3d829"

若测试失败：

配置未就绪。请初始化：
1. 运行：python3 scripts/config_loader.py init --user
2. 编辑 ~/.config/aria2-skill/config.json，填入您的 aria2 服务器信息
3. 运行：python3 scripts/config_loader.py test（以验证）

文档结构

详细执行指南，请参阅：
- references/execution-guide.md - AI 助手完整指南，包含：
- 命令映射表（用户意图 → 脚本调用）
- 参数格式化规则
- 分步示例
- 常见错误避免
- 响应格式化指南

aria2 方法参考，请参阅：
- references/aria2-methods.md - 详细的 aria2 RPC 方法文档

常用命令速查

详细用法及更多命令，请参阅 execution-guide.md。

可用脚本

• scripts/rpc_client.py - RPC 调用的主接口
• scripts/examples/list-downloads.py - 格式化下载列表
• scripts/examples/pause-all.py - 暂停所有下载
• scripts/examples/add-torrent.py - 添加种子下载
• scripts/examples/monitor-downloads.py - 实时监控
• scripts/examples/set-options.py - 修改选项

配置

脚本自动从多个来源加载配置，优先级如下（从高到低）：

配置优先级

1. 环境变量（最高优先级 - 临时覆盖）
   - ARIA2_RPC_HOST、ARIA2_RPC_PORT、ARIA2_RPC_PATH 等
   - 适用于：CI/CD 流水线、临时覆盖、测试
   - 注意：仅供参考。助手应使用配置文件。

2. 技能目录配置（项目特定配置）
   - 位置：skills/aria2-json-rpc/config.json
   - 适用于：项目特定设置、本地测试、开发
   - ⚠️ 警告：通过 npx skills add 更新技能时会丢失

3. 用户配置目录（全局回退，更新安全）🆕
   - 位置：~/.config/aria2-skill/config.json
   - 适用于：跨所有项目的个人默认设置
   - ✅ 安全：通过 npx skills add 更新技能后仍保留

4. 默认值（localhost:6800）
   - 本地开发的零配置回退

配置选项

• host：主机名或 IP 地址（默认：localhost）
• port：端口号（默认：6800）
• path：URL 路径（默认：null）。标准 aria2 设为 /jsonrpc，反向代理设为自定义路径
• secret：RPC 密钥令牌（默认：null）
• secure：使用 HTTPS 而非 HTTP（默认：false）
• timeout：请求超时（毫秒）（默认：30000）

快速设置（面向 AI 助手）

重要：始终使用 Python 脚本管理配置。切勿直接使用 shell 命令。

步骤 1：检查当前配置状态

python3 scripts/config_loader.py show

步骤 2：如需要，初始化配置

用户配置（推荐 - 更新后保留）：

python3 scripts/config_loader.py init --user

本地配置（项目特定）：

python3 scripts/config_loader.py init --local

步骤 3：指导用户编辑配置文件

初始化后，工具将显示配置文件路径。指导用户编辑该文件，填入其 aria2 服务器信息（主机、端口、密钥等）。

步骤 4：验证配置

python3 scripts/config_loader.py test

配置文件内容示例：

{
  "host": "localhost",
  "port": 6800,
  "secret": "your-secret-token",
  "secure": false,
  "timeout": 30000
}

配置管理（面向 AI 助手）

用于配置管理的可用 Python 脚本：

# 检查当前配置及来源
python3 scripts/config_loader.py show

# 初始化用户配置（推荐 - 更新安全）
python3 scripts/config_loader.py init --user

# 初始化本地配置（项目特定）
python3 scripts/config_loader.py init --local

# 测试连接到 aria2 服务器
python3 scripts/config_loader.py test

助手配置设置工作流程：

1. 检查配置是否存在：运行 python3 scripts/config_loader.py show
2. 若配置缺失或无效：引导用户运行 python3 scripts/config_loader.py init --user
3. 用户编辑配置：告知用户文件路径及必填字段（主机、端口、密钥）
4. 验证设置：运行 python3 scripts/config_loader.py test
5. 继续操作：测试通过后，执行用户的 aria2 命令

高级配置

反向代理设置：

对于如 https://example.com:443/jsonrpc 的反向代理设置，配置文件应包含：

{
  "host": "example.com",
  "port": 443,
  "path": "/jsonrpc",
  "secret": "your-secret-token",
  "secure": true
}

环境变量（仅供参考）：

配置也可通过环境变量覆盖：
- ARIA2_RPC_HOST：主机名
- ARIA2_RPC_PORT：端口号
- ARIA2_RPC_PATH：URL 路径
- ARIA2_RPC_SECRET：密钥令牌
- ARIA2_RPC_SECURE："true" 或 "false"

注意：请使用 Python 脚本进行配置管理。此处记录环境变量仅供参考。

核心原则（面向 AI 助手）

1. 切勿手动构造 JSON-RPC 请求
2. 始终通过 Bash 工具使用 python3（而非 python）调用 Python 脚本
3. 始终在执行命令前检查配置：
   - 首先运行 python3 scripts/config_loader.py test
   - 若测试失败，引导用户完成初始化
4. 切勿直接运行原始 shell 命令（mkdir、cat、export 等）
   - 使用 Python 脚本：config_loader.py init、config_loader.py show 等
5. 解析脚本输出并格式化给用户
6. 不确定时参考 execution-guide.md

支持的操作

下载管理

• 添加下载（HTTP/FTP/Magnet/种子/Metalink）
• 暂停/恢复（单个或全部）
• 移除下载
• 使用自定义选项添加

监控

• 检查下载状态
• 列出活动/等待/已停止的下载
• 获取全局统计信息
• 实时监控

配置

• 获取/更改下载选项
• 获取/更改全局选项
• 查询 aria2 版本
• 列出可用方法

维护

• 清理下载结果
• 移除特定结果

需要帮助？

• 执行详情： references/execution-guide.md
• 方法参考： references/aria2-methods.md
• 故障排除： references/troubleshooting.md
• aria2 官方文档： https://aria2.github.io/