此技能的功能

该技能支持您通过自然语言指令控制 aria2 下载管理器：

• 下载文件（HTTP/HTTPS/FTP/Magnet/Torrent/Metalink）
• 监控下载进度与状态
• 控制下载任务（暂停、恢复、删除）
• 批量操作管理（全部暂停、全部恢复）
• 查看统计信息及配置选项

使用方法（面向 AI Agent）

⚠️ 关键提示：切勿手动构造 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 Agent 的完整指南，包含：
  • 用户意图与脚本调用映射表
  • 参数格式化规则
  • 分步示例
  • 常见错误规避指南
  • 响应格式规范

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 —— 添加 Torrent 下载任务
• scripts/examples/monitor-downloads.py —— 实时监控下载状态
• scripts/examples/set-options.py —— 修改 aria2 配置选项

配置说明

脚本会按以下优先级顺序自动加载配置（由高到低）：

配置优先级

1. 环境变量（最高优先级 —— 临时覆盖）

   • ARIA2_RPC_HOST、ARIA2_RPC_PORT、ARIA2_RPC_PATH 等
   • 适用场景：CI/CD 流水线、临时覆盖、测试
   • 注意：仅作参考。AI Agent 应优先使用配置文件方式。

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（默认：false）
• timeout：请求超时时间（毫秒，默认：30000）

快速配置（面向 AI Agent）

重要提示：始终使用 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 服务端信息（host、port、secret 等）。

步骤 4：验证配置

python3 scripts/config_loader.py test

配置文件内容示例：

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

配置管理（面向 AI Agent）

可用于配置管理的 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

AI Agent 配置建立工作流：

1. 检查配置是否存在：运行 python3 scripts/config_loader.py show
2. 若配置缺失或无效：引导用户运行 python3 scripts/config_loader.py init --user
3. 用户编辑配置：告知用户配置文件路径及必需字段（host、port、secret）
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 Agent）

1. 严禁手动构造 JSON-RPC 请求
2. 必须通过 Bash 工具调用 Python 脚本，且使用 python3（非 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/Torrent/Metalink）
• 暂停/恢复任务（单个或全部）
• 移除下载任务
• 带自定义选项添加任务

监控功能

• 查询下载任务状态
• 列出活跃/等待/已停止任务
• 获取全局统计信息
• 实时监控下载状态

配置管理

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

维护操作

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

需要帮助？

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