核心用法
aria2-json-rpc 是一款面向 AI Agent 的下载管理技能，通过 JSON-RPC 2.0 协议与 aria2 下载引擎交互。用户可通过自然语言指令完成以下操作：
下载管理：支持添加 HTTP/HTTPS/FTP/Magnet/Torrent/Metalink 等多种协议的任务，可自定义下载选项如保存路径、连接数、限速等。
任务监控：实时查询下载状态（GID 标识）、查看活跃/等待/已停止任务列表、获取全局统计信息，支持 WebSocket 实时推送监控。
批量控制：暂停/恢复单个或全部任务、移除下载、清理已完成结果，适合批量运维场景。
配置管理：采用分层配置策略（环境变量 > 项目配置 > 用户配置 > 默认值），支持本地开发、项目隔离和全局复用三种模式，用户配置可 survives skill 更新。
Agent 必须遵循规范工作流：先执行 python3 scripts/config_loader.py test 检测配置，通过后使用 python3 scripts/rpc_client.py <method> 调用封装脚本，禁止手动构造 JSON-RPC 请求。
显著优点
协议覆盖全面：aria2 作为业界成熟的开源下载工具，单机支持 16 线程并发，Segmented Downloading 技术可最大化带宽利用率，对冷门种子和金属链接支持优异。
架构轻量安全：纯 Python 标准库实现（仅 urllib），websockets 为可选依赖，代码结构清晰无危险函数调用，依赖面积极小无已知 CVE。
配置灵活持久：用户级配置存储于 ~/.config/aria2-skill/config.json，更新 skill 时保留；支持反向代理、HTTPS/WSS 加密、Token 认证等企业级部署。
Agent 友好设计：提供完整命令映射表、参数格式化规则、常见错误规避指南，内置配置初始化与验证脚本，降低 AI 执行出错概率。
潜在缺点与局限性
前置依赖门槛：要求用户已部署 aria2 RPC 服务端并开放端口，对纯新手存在环境搭建成本；Windows 平台 aria2 部署相对 Linux/macOS 复杂。
安全配置默认偏宽松：默认使用 HTTP 明文通信（secure: false），远程连接存在中间人攻击风险；需用户手动启用 HTTPS 或配置防火墙隔离。
功能边界明确：仅作为 aria2 的控制客户端，不解决 aria2 本身的网络封锁穿透、DHT 连接数优化等底层问题，复杂网络环境需额外配置。
WebSocket 功能降级：实时监控需额外安装 websockets 库，未安装时抛出 ImportError，依赖管理不够静默优雅。
适合的目标群体
NAS/服务器用户：拥有 24h 运行的 aria2 服务，需要远程任务管理的下载爱好者。
开发运维人员：需批量下载日志、数据集、依赖包的自动化场景，可集成至 CI/CD 或定时任务。
技术型内容创作者：频繁通过种子/磁力链获取素材，追求多线程高效下载的摄影师、设计师。
隐私敏感用户：倾向于自建下载基础设施、避免 SaaS 云端存储的自主可控需求者。
常规使用风险
网络性能风险：aria2 默认连接数较高，在弱网或限速环境可能触发目标服务器 IP 封禁；建议配置 max-concurrent-downloads 与 split 参数适配网络环境。
存储空间风险：批量下载缺乏自动磁盘容量检查，大文件任务可能撑爆存储分区；需用户自行监控 aria2.getGlobalStat 输出。
配置泄露风险：RPC secret 存储于明文配置文件，多用户共享系统需设置文件权限 600；建议优先使用 localhost 监听配合 SSH 隧道访问。
依赖服务可用性：技能本身不托管 aria2 进程，服务端崩溃/重启后任务状态丢失（若未启用 aria2 的 save-session 持久化），Agent 需提示用户检查服务端健康。
协议兼容性风险：部分站点对 aria2 的 User-Agent 或并发特征有反爬策略，可能需要通过 --header 自定义请求头伪装浏览器。