前言¶
在智能体或自动化流程里，让模型代为提交下载、查进度、暂停或取消任务，常见做法是手写脚本调用 aria2c，或在对话外单独维护一套下载面板。DeepSeek Harness（DSH）通过插件把能力挂进运行时；若你本地或内网已经跑着持久化的 aria2，并开放了 JSON-RPC，本插件只做 HTTP 桥接，不向 DSH 内置下载器、也不接管 aria2 进程生命周期。下面介绍插件定位、工具面、安装配置与使用约束。
这是什么¶
@rosmeowtis/dsh-aria2-rpc 由 Rosmeowtis 维护，归类为联网工具。它连接已有的 aria2 JSON-RPC 服务（HTTP，/jsonrpc），为模型暴露四个工具；不携带、不启动、不管理 aria2。社区目录页见 SkillHub 条目，源码与说明见 GitHub 仓库。
当前 npm 包版本为 0.1.1，许可证 MIT；运行要求 Node >=22.18，DSH ^0.2.1-rc.5。工具定义的上下文占用约 400 token。
核心功能¶
插件向模型提供下表四个工具（名称与行为以 README 为准）：
| 工具 | 作用 |
|---|---|
aria2_download |
提交单文件直链下载，立即返回 GID；可选保存目录、文件名、来源提供的校验和（sha-256 / sha-1 / md5，实际计算由 aria2 执行）、任务级 HTTP 代理。 |
aria2_status |
读取任务状态、进度、速度、文件路径与脱敏错误。 |
aria2_list |
列出 active / waiting / stopped 或全部任务；只读，支持 limit/offset。 |
aria2_control |
pause / resume / cancel。取消保留部分文件，不关闭 aria2。 |
下载完成或失败时，插件通过 aria2 的 WebSocket 通知向发起会话推送一条消息。只跟踪本进程内由 aria2_download 创建的任务；插件重载后，重载前创建的任务不再推送。
创建与控制仅在退出计划模式后的完全访问模式执行；状态读取不受此限。结果未知的修改请求会返回可查询的 GID，不会自动重复提交。
安装与启用¶
以 web 预设举例。装完必须重启该 profile（dsh web）：bundle 层在启动时组装。
npm 渠道（版本受控）：
dsh plugin --profile web add @rosmeowtis/dsh-aria2-rpc
dsh web
GitHub 渠道（跟仓库 HEAD，用于先于发布验证）：
dsh plugin --profile web add github:Rosmeowtis/dsh-aria2-rpc
通过 git 依赖安装时，prepare 会在安装阶段构建；pnpm 默认可能拦截构建脚本。若首次安装失败并打印 allowBuilds key，需把该 key 写入对应 profile 的 pnpm-workspace.yaml 后重跑同一条安装命令。key 中带 commit，仓库有新提交后需按新打印的 key 重新放行。
本地开发可在本仓库执行 npm run build 后：
dsh plugin --profile web add .
配置与连接测试¶
在 DSH 设置 → 插件 → Aria2 RPC 中可配置：
rpcHost、rpcPort- 密钥与请求超时
密钥固定使用凭据 ARIA2_RPC_SECRET；无密钥时不发送。RPC 走 HTTP，不加密；远程连接请仅在可信网络或加密隧道中使用。
设置页的「测试连接」使用当前输入的主机、端口与超时调用 aria2.getVersion，无需先保存。密钥框有内容时使用该临时值，否则从当前凭据引用读取；测试不保存配置、不创建任务。成功时显示 aria2 版本，失败时提示连通性、超时或鉴权问题。
典型前置条件：你已部署并长期运行 aria2，且 RPC 监听地址与插件配置一致（含 rpc-secret 与 DSH 凭据一致，若启用）。
典型用法（对话侧）¶
模型在具备工具权限的会话中可这样使用（概念流程，非固定话术）：
- 用
aria2_download传入直链 URL，按需指定目录、文件名、校验和或代理；拿到 GID。 - 用
aria2_status或aria2_list查看进度与队列。 - 用
aria2_control对指定 GID 执行pause、resume或cancel。 - 对本会话内由
aria2_download创建的任务，可在完成或失败时收到 WebSocket 推送，无需轮询到底。
如需在改动 aria2 任务状态前确认环境，可先「测试连接」再发起下载。
适用场景与注意¶
适合： 已有 aria2 后台（家庭 NAS、内网节点、长期开的下载机），希望 DSH 对话里用自然语言或工作流创建、查询、管控下载，而不把 aria2 装进 DSH 或交给插件启停。
不适合： 期望插件自带 aria2、安装即下载、或代管 aria2 进程与系统服务；这些不在设计范围内。
插件以当前 DSH 进程权限运行，RPC 调用范围等价于该进程能访问的网络与配置。安装前建议阅读仓库源码与 MIT 许可证，确认 RPC 密钥与保存路径符合你的安全策略。DSH 生态强调「一切皆插件」；SkillHub 为社区目录，与 DeepSeek / 幻方无官方从属关系。
结尾¶
@rosmeowtis/dsh-aria2-rpc 的价值在于：在假定 aria2 已独立部署的前提下，用四个精简工具把 JSON-RPC 能力纳入 DSH，并支持会话内任务完成通知。安装后配置 RPC 与 ARIA2_RPC_SECRET，重启 web profile 即可使用。
- 目录页：https://www.skillhub.cn/plugins/Rosmeowtis/dsh-aria2-rpc
- GitHub：https://github.com/Rosmeowtis/dsh-aria2-rpc
