前言¶
在 DSH 里让智能体「下文件」，常见做法是 curl、wget 或自己写脚本：大文件、磁力链和 BT 任务往往要占用会话进程，进度还要靠轮询或人工盯盘。若本机已经在用 Gopeed 做下载管理，更稳妥的路径是把任务交给 Gopeed 的 HTTP 接口，由 Gopeed 负责出站流量和落盘，智能体只创建任务、读进度、收完成通知。dsh-gopeed-downloader（维护者 Keridium，社区分类：联网工具）就是按这个思路做的 Cordis 插件：注册 7 个工具，并在下载结束时通过 DSH 后台任务唤醒空闲智能体。
这是什么¶
插件全名 dsh-gopeed-downloader，npm 包名同为 dsh-gopeed-downloader（当前资料中 package.json 版本为 0.3.3，MIT 许可证）。它运行在 DeepSeek Harness (DSH) 宿主进程内，不依赖本机单独安装 Node.js/npm/pnpm 来「跑插件」——安装 bundle 由 DSH 自带的插件管理完成。
智能体通过 loopback 访问本机 Gopeed；链接经 Gopeed 发出，文件写在磁盘上，不经过模型或 shell 转发。Gopeed 桌面版默认每次启动随机端口，插件在未固定端口时会从运行中的进程读取实际端口（配置里可 pin）。依赖 Gopeed 1.9.3+（README 写明在 1.9.3 上验证过）。
若你维护的是「会调用工具的 Agent」，官方要求先读合约文档 docs/AGENTS.md（工具字段、gopeed_add 禁止轮询等规则），而不是只读人类向 README。
核心功能¶
README 用表格归纳了 7 个工具的目标对应关系，下面按同一事实展开。
| 目标 | 工具 |
|---|---|
| 发起下载并在结束时收到通知 | gopeed_add：支持 HTTP/HTTPS 直链、磁力链、远程 .torrent URL；返回后台 job，完成通知由 DSH 投递（忙着的智能体下一步读结果，空闲的可被唤醒） |
| 查看进度 | gopeed_list、gopeed_status：扁平任务结构（如 percent、sizeKnown、速度、真实保存目录） |
| 控制任务 | gopeed_control：通过 action 暂停 / 恢复 / 删除；remove 默认会删文件，除非 force: false |
| 诊断环境 | gopeed_process：六种 verdict 之一，并带 pid、内存、版本、可执行路径、webhook 状态等 |
| 启动未运行的 Gopeed | gopeed_launch：相当于在资源管理器里双击图标，无参数 |
| 接收 Gopeed 推送事件 | gopeed_events：读取 DOWNLOAD_DONE / DOWNLOAD_ERROR；action: "apply" 可在 auto 模式下把 webhook 地址写入 Gopeed 配置 |
支持的 URL 类型与 Gopeed 本身一致：不支持上传本地 .torrent 文件，应改用该文件来源的 URL。BT 细节（peer、DHT、做种等）仍在 Gopeed 内，插件只创建任务并读进度。
明确不做的事¶
- 没有任何工具能重启或结束 Gopeed 进程；重启需在插件设置页点用户侧的「Restart Gopeed」，以免打断进行中的任务。
gopeed_launch仅启动缺失的进程。 - 进程相关能力仅 Windows：
gopeed_process、gopeed_launch、设置页重启按钮、可执行文件自动发现等调用 Windows 工具（PowerShell 5.1、tasklist、netstat等）。下载类 REST 工具在 Gopeed 能跑的平台均可使用。 - Webhook 监听只绑定
127.0.0.1；Docker 或其它机器上的 Gopeed 无法直接推送到该 listener，需改用gopeed_list/gopeed_status轮询。 - 插件不会向对话里伪造用户消息；指引写在工具返回结果里。
安装与启用¶
前提：DSH 已运行，且当前 profile 能安装 bundle（plugin_manager 或 Web Plugins 页）。
在会话里让智能体安装 npm 包（等价于 plugin_manager 的 action: "install_bundle"，target: "dsh-gopeed-downloader"）：
Install the dsh-gopeed-downloader bundle from npm.
命令行等价写法（资料原文）：
dsh plugin --profile web add dsh-gopeed-downloader
需要开发版或固定 commit 时，target 可为 github:Keridium/dsh-gopeed-downloader，并支持版本 pin，例如 dsh-gopeed-downloader@0.3.2 或 github:Keridium/dsh-gopeed-downloader#v0.3.2。卸载使用 action: "remove_bundle"、target: "dsh-gopeed-downloader"，或 Web Plugins → Installed。
安装后若 DSH 提示重启则重启。首次使用前打开 Plugins → Installed → Gopeed Downloader → row gopeed → Configure，若 Gopeed 使用 token 或固定端口，在表单中填写。表单保存后立即生效，无需 remount 或重启 DSH；各字段提示为「Default: X; empty = Y」。
配置项（资料已截断部分仍明确出现的字段）：
downloadTarget：workspace（默认）/gopeed/custom。workspace落在会话当前工作目录（随cd变化）；gopeed_add显式传入的path始终优先。customDownloadPath：在 target 为custom时使用；留空则回退为 Gopeed 自带下载目录。
Git URL 安装时插件管理器会先 git ls-remote，因此 用 Git spec 安装时本机需有 git；否则可用 release tarball URL。
典型用法¶
README 给出的首次调用示例：
gopeed_add { "url": "https://example.com/file.iso" }
# -> taskId, path, jobId; stop here -- the completion notice arrives on its own
含义是：提交 URL 后拿到 taskId、path、jobId 即可停步，不要对 gopeed_add 做完成轮询（合约在 AGENTS.md）；完成时由 DSH 后台 job / 事件链路通知。跟进进度用 gopeed_list 或 gopeed_status；暂停、恢复、删除用 gopeed_control；环境不对时用 gopeed_process 看 verdict，必要时 gopeed_launch 或用户在设置页重启 Gopeed。
适用场景与注意¶
适合：已在本地用 Gopeed 管理 HTTP/磁力/BT 任务，希望 DSH 智能体「代点添加、看进度、收完成回调」，且接受 Gopeed 负责磁盘与网络栈。
注意：
- 插件以 当前 DSH 进程权限 运行；安装前请自行查看 GitHub 源码 与 MIT 许可证，确认符合你的安全策略。
- 社区目录 skillhub.cn 插件页 与 DeepSeek / 幻方无官方从属关系，DSH 生态是「一切皆插件」的独立扩展方式，本文事实以仓库 README 与 npm 包元数据为准。
结尾¶
dsh-gopeed-downloader 把 Gopeed 1.9.3+ 的下载能力封装成 7 个 DSH 工具，跨平台 REST 与 Windows 进程辅助并存，并用后台 job 在下载结束时唤醒空闲智能体。查阅与安装可从这里开始：
- 目录页：https://www.skillhub.cn/plugins/Keridium/dsh-gopeed-downloader
- GitHub：https://github.com/Keridium/dsh-gopeed-downloader
- Agent 合约：https://github.com/Keridium/dsh-gopeed-downloader/blob/main/docs/AGENTS.md
