aria2-json-rpc

核心用法

aria2-json-rpc 是一个面向 AI Agent 的 aria2 下载管理器控制技能，通过封装 JSON-RPC 2.0 协议，让用户能够以自然语言指令操控下载任务。核心工作流分为三步：首先通过 config_loader.py test 检测配置状态，若未就绪则引导用户初始化配置（推荐 --user 模式以持久化保存），最后通过 rpc_client.py 执行具体的 aria2 操作。

该技能支持完整的下载生命周期管理：添加任务（aria2.addUri）、状态查询（aria2.tellStatus/tellActive）、任务控制（pause/unpause/remove）以及全局统计（getGlobalStat）。特别支持种子文件和磁力链下载，并提供 WebSocket 实时监听作为可选功能。

显著优点

1. 自然语言交互：内置命令映射器，将"下载这个文件""暂停所有任务"等口语化指令自动转换为精确的 RPC 调用，大幅降低使用门槛。

2. 配置管理智能：采用四级配置优先级（环境变量 > 项目配置 > 用户配置 > 默认值），--user 模式确保技能更新后配置不丢失，兼顾灵活性与持久性。

3. 安全设计到位：敏感信息（RPC Secret）在显示时自动脱敏为 ******；支持 HTTPS 加密通信和 Token 认证；所有文件操作均使用标准库，无危险函数。

4. 依赖极简：核心功能仅依赖 Python 3.6+ 标准库（urllib、json、os），WebSocket 为可选依赖，部署成本极低。

5. 文档完善：提供执行指南、方法参考、故障排查三层文档体系，AI Agent 可按图索骥完成复杂操作。

潜在缺点与局限性

1. 前置依赖较重：必须自行部署并配置 aria2 服务端（RPC 模式），技能本身仅为客户端，无法独立工作。对无运维经验的用户存在门槛。

2. 路径验证不足：用户提供的种子文件路径仅做 os.path.isfile 基础检查，缺乏严格的目录遍历防护，存在潜在的文件越界读取风险。

3. 权限管理粗放：初始化配置时未自动设置文件权限（如 600），依赖用户手动执行 chmod，可能导致敏感配置泄露。

4. 错误处理依赖服务端：所有业务逻辑错误（如无效 URL、磁盘空间不足）均来自 aria2 服务端返回，技能层仅做透传，调试体验受限于服务端配置。

5. WebSocket 功能受限：实时监听功能需要额外安装 websockets 库，且对 Python 版本有匹配要求，部分环境可能无法启用。

适合的目标群体

• NAS/服务器用户：已在设备上部署 aria2，希望通过自然语言快速管理下载任务
• 自动化工作流开发者：需要将下载能力集成到 AI Agent 或自动化脚本中
• 技术爱好者：熟悉 aria2 生态，追求更优雅的交互方式而非手动构造 RPC 请求
• 多设备同步用户：利用用户级配置实现跨项目、跨会话的持久化设置

使用风险

1. 网络暴露风险：若 aria2 服务端配置不当（如监听 0.0.0.0 且无 Secret），配合此技能可能导致未授权下载控制，建议严格限制 RPC 监听地址。

2. 配置泄露风险：~/.config/aria2-skill/config.json 默认权限依赖 umask，在多用户环境可能可读，需手动加固。

3. 依赖项版本冲突：WebSocket 功能对 websockets 库版本敏感，与某些 Python 环境可能存在兼容性问题。

4. 下载内容合规性：技能本身不审查下载内容，用户需自行确保种子/磁力链来源合法，避免版权或法律风险。