DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

firehuzi /

firehuzi/scalpel-downloadx

Topic repository only

刃研社-DownloadX:本地优先、无广告、可被 Agent 调用的下载器(多连接断点续传 / SHA-256 / 视频站点分流)

★ 0 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@fbb25b5d

刃研社-DownloadX v0.2

Windows 优先、跨平台设计、本地优先、无广告、低资源占用、可被 Agent 调用的下载器。

代码里的标识仍是 downloadx(Python 包名、%LOCALAPPDATA%\DownloadX 状态目录、CLI 命令名), 「刃研社-DownloadX」是它的正式名称。改名会让已有任务记录和已装 skill 对不上,所以两者刻意分开。

仓库 https://github.com/firehuzi/scalpel-downloadx · 许可 MIT · Python ≥ 3.10 · 依赖只有 5 个(aiohttp / httpx / fastapi / uvicorn / pydantic)

它不是迅雷的复刻,目标是一个 可靠、可扩展、可被程序调用的本地下载基础设施:

用户 / LLM / 脚本
        │  自然语言 · URL · 工具调用
        ▼
  Download Agent(api/agent_api)
        │  确定性工具调用
        ▼
  Download Engine(core + queue + network + storage)   ←── 完全独立,不需要 LLM
        ▼
   本地文件

核心约束:AI 是控制层,不是下载引擎。 关掉网络、删掉 API Key、断开一切模型, 下载引擎照常工作(测试里就是这么跑的)。


快速开始

# 1. 装依赖(只有 5 个)
cd outputs\DownloadX
pip install -r requirements.txt

# 2. 方式 A:启动服务 + 内置 Web UI
python -m downloadx serve
#   打开 http://127.0.0.1:8720/

# 3. 方式 B:直接下,像 wget 一样(不需要服务)
python -m downloadx add https://example.com/big.zip
python -m downloadx add https://example.com/big.zip --conn 16 --priority 0 --limit 5

# 4. 安装成命令行工具(可选)
pip install -e .
downloadx serve

视频/音频(YouTube、B 站、X 等)走额外工具链:yt-dlp 负责解析、ffmpeg 负责合并 (720P 以上一定是音视频分离的)。两者缺失时 skill 只报告、不自动安装:

python -m pip install -U yt-dlp     # 解析
winget install Gyan.FFmpeg          # 合并(或自行放置 ffmpeg 到 PATH)

常用命令:

downloadx add <url>                  # 前台下载,带进度条
downloadx add <url> --no-wait        # 只入队(交给常驻服务下载)
downloadx list --status downloading  # 列出下载中的任务
downloadx get <task_id>              # 单任务详情
downloadx pause|resume|cancel <id>   # 暂停 / 继续 / 取消
downloadx retry <id> [--reset]       # 重试(默认断点续传,--reset 从零重下)
downloadx rm <id> [--delete-file]    # 移除任务
downloadx stats | history | probe <url> | config
downloadx nl "把那个大文件暂停,其他继续"     # 自然语言(默认规则解析,可接 LLM)
downloadx tools                      # 列出 15 个可被 Agent 调用的工具

MVP 能力(任务书 §2 全部覆盖)

能力 状态 实现位置
HTTP / HTTPS / URL 下载 ✅ network/http_client.py
多连接分片下载 ✅ core/segment.py + core/download_worker.py
HTTP Range 协商(含"服务端假装支持"的识别) ✅ network/range_request.py
断点续传(真实偏移续传) ✅ core/download_worker.py + storage/segment_store.py
暂停 / 恢复 / 取消 ✅ core/scheduler.py 协作式停止
重试(区分临时错误与永久错误) ✅ network/retry.py
下载队列 + 优先级 ✅ queue/priority_queue.py
速度显示 / 剩余时间估算 ✅ core/metrics.py
文件大小 / 已完成大小 / 状态 ✅ core/download_task.py
下载历史 / 错误记录 ✅ storage/metadata_store.py
SHA-256 校验(校验通过才改名成最终文件) ✅ storage/checksum.py
崩溃恢复(重启自动续传) ✅ storage/checkpoint.py + core/download_manager.py
带宽控制(全局 + 单任务) ✅ queue/bandwidth_controller.py
自适应并发(可见限流 429/503 自动降级 + 静默限速靠自校准发现) ✅ core/download_worker.py
HLS / DASH 流媒体(分片下载 + 按分片续传 + 合并成 mp4) ✅ network/hls.py、network/dash.py + core/download_worker.py
本地 API + Web UI + Agent API ✅ api/、ui/index.html

分阶段推进的项见 docs/ROADMAP.md:浏览器扩展与 API 鉴权已完成(P1), 媒体能力补全(P2)、BT / Magnet / DHT(P3)、账号与云同步(P4)、LLM 对话(P5)依次排期。

明确不做:网盘破解、DRM 绕过 —— 绕过访问控制不是下载功能。


关键设计取舍

1. 未完成的数据永不等于最终文件。 所有下载先落到 <文件名>.dxpart,只有 SHA-256 校验通过后,才用 os.replace 原子改名成最终文件。断电、崩溃、校验失败都不会留下"看起来下好了其实是坏文件"的结果。

2. 续传靠偏移,不靠"续传 API"。 每个分片失败后,用 Range: bytes=<已收字节>-<结束> 重新请求。所以暂停、断网、 换网络、进程被杀,恢复逻辑都是同一条路径。

3. 探测必须可信。 服务端返回 404/500 时,绝不把错误响应体的 Content-Length 当成文件大小 (这个坑在开发中真实踩到过,已修)。HEAD 不被允许时才回退到 Range: bytes=0-0 验证。

4. 默认 Accept-Encoding: identity。 下载器必须拿原始字节,一旦被 gzip 解压,Range 偏移和进度就全错。

5. 重启后先比对远端是否变了。 恢复任务前用大小 / ETag / Last-Modified 判断文件是否被替换;变了就丢弃旧分片重下, 宁可重下也不要拼出一个坏文件。

6. "连接数越多越快"是错的,而且引擎现在会自己发现这件事。 实测中科大镜像在 4/16 连接下直接返回 429;CacheFly 则是在 8 连接时聚合吞吐反而比 单连接低 23%(3.95 vs 5.10 MB/s)——后者不报错,属于静默按连接限速。 引擎的处理分两层:收到 429/503/504 就立刻收紧并发;对静默限速则在同一个任务内 先单连接量一段、再放开量一段(预热后采样,排除 TLS 慢启动),聚合吞吐没有 15% 以上 提升就退回单连接,并把结论写进 plan_reason。真机实测:8 连接被判"没收益",自动回到 1。


项目结构

DownloadX/
├── downloadx/
│   ├── core/        # 引擎:任务、状态机、调度、执行、事件、计量
│   ├── network/     # HTTP 客户端、连接池、Range、重试、网络监视
│   ├── storage/     # 文件写入、分片账本、元数据、检查点、校验、单实例锁
│   ├── queue/       # 优先级队列、令牌桶限速、任务队列
│   ├── api/         # local_api(REST+WebSocket)、agent_api(工具调用)
│   ├── ui/          # 单文件 Web UI(离线可用,无 CDN)
│   ├── cli.py       # 命令行(前台下载 / 连服务两种模式)
│   └── config.py    # 配置(默认值 -> config.json -> 环境变量)
├── extension/       # 浏览器扩展(MV3):右键链接直接交给本机引擎
├── tests/           # 139 个测试(BT 的 2 个需装可选依赖,否则跳过)
├── skill/           # 配套 Codex skill(薄封装,见下)
├── docs/            # 架构 / API / Agent API / 测试说明
└── scripts/         # 联调冒烟 + 压测脚本

规模:61 个 Python 文件、约 12.5k 行(含测试与脚本)、UI 单文件 479 行。


文档

  • docs/ARCHITECTURE.md —— 分层、真实数据回路、状态机、并发与可靠性机制
  • docs/API.md —— 本地 REST 接口、WebSocket 事件、错误码
  • docs/AGENT_API.md —— 15 个工具、自然语言层、如何用 LLM 驱动
  • docs/TESTING.md —— 怎么跑测试、测试服务覆盖了哪些恶劣情况
  • docs/PERFORMANCE.md —— 实测速度:回环上限、外网、国内镜像、多连接收益
  • docs/BT_SPIKE.md —— P3 可行性 spike:libtorrent 实测结论与集成建议

配套 Codex skill

skill/downloadx/ 是这个项目的 Codex skill:让任意会话一句话就能用它下载,而不用先找到 引擎在哪。它只做薄封装,不含任何下载逻辑,永远指向引擎本体(避免两份实现漂移)。

skill/downloadx/
├── SKILL.md                  # 什么时候用、怎么用、哪些不变量不能破
├── scripts/dx.py             # 定位引擎 + 挑解释器 + 原样转发参数
├── scripts/fetch_video.py    # 视频/音频分流:yt-dlp / X skill / 引擎,按 URL 自动选
└── references/               # cli.md / agent-api.md / troubleshooting.md / video-sites.md

视频站点由 fetch_video.py 分流:YouTube、Bilibili 等交给 yt-dlp(B 站会自动补上躲开 HTTP 412 的四个请求头),X/Twitter 交给已有的 download-x-video skill,直链媒体文件交回 引擎(续传 + 队列 + 校验)。工具缺失时只报告、不自动安装。

需要登录或走代理的站点用站点档案记住一次即可: fetch_video.py --site-set bilibili.com --cookies <file>,之后同域名的链接自动带上。

还能定期体检:check_sites.py 几秒钟探一遍 B 站 / YouTube / X / HLS / DASH, 报告"现在还能不能下、最高什么画质",失败时退出码 1(可接定时任务)。

附加产物用 --extras 一次拿全:字幕(转 srt)、章节(.chapters.txt)、B 站弹幕(.danmaku.xml)。


作为 Agent Skill 安装(Install as Agent Skill)

DownloadX 自带一个薄封装 skill(skill/downloadx/):它不含任何下载逻辑,只负责定位本机引擎并原样转发参数。 装好后,任意会话一句话就能调用本机下载能力 —— 视频、大文件、断点续传、队列、SHA-256 校验全走引擎本体。

本地优先(local-first):引擎必须装在本机。云端 Agent 沙箱跑不了这个 skill(没有 Python 引擎、下载落点也不明确),别往云端 Pay Skill 沙箱塞。

前置条件

pip install -e .                       # 本机先装好引擎
python -m downloadx serve              # 或前台模式,引擎照常工作

各平台安装

平台 方式 备注
OpenClaw / ClawHub 仓库打 openclaw-skill topic 后 OpenClaw 自动索引;或 clawhub.ai 搜 downloadx 安装 已备 clawhub.yaml + 英文 SOUL.md
WorkBuddy 开放平台后台「技能」上传 skill/downloadx/SKILL.md 已含 display_name / description_zh / description_en,分类选 coding
SkillHub(腾讯,免费) 企业认证后传含 SKILL.md 的包(≤10MB) 仅限本地优先 skill,非云端 Pay Skill
skills.sh(Vercel) npx skills add firehuzi/scalpel-downloadx 约定 skills/<name>/SKILL.md;本仓库用单数 skill/,若命令找不到 skill,走下方手动安装
手动 / 任意宿主 复制 skill/downloadx/ 到对应 skills 目录(下表) 最稳妥,跨宿主通用(遵循 agentskills.io)

手动安装路径

# Codex
Copy-Item -Recurse skill/downloadx $env:USERPROFILE\.codex\skills\downloadx
# WorkBuddy(用户级)
Copy-Item -Recurse skill/downloadx $env:USERPROFILE\.workbuddy\skills\downloadx
# 其他遵循 agentskills.io 的宿主:放到各自的 skills/<name>/ 目录即可

验证

python $env:USERPROFILE\.codex\skills\downloadx\scripts\dx.py doctor   # 应解析出引擎路径 / 解释器 / 版本
python $env:USERPROFILE\.codex\skills\downloadx\scripts\dx.py add <url> --wait --json

更新

改 skill/downloadx/ 源,再用 scripts/sync_skill.py 同步到所有副本(Codex 加载目录 + 归档目录), 或各平台重新安装 / 拉取最新版。


同步到「我的AI助手」中台

scripts/install_to_assistant.py 把下载能力装进本机的 AI 中台(默认 D:\Projects\我的AI助手):

写什么 内容
Skill 库 「下载工具 DownloadX」——SKILL.md 正文 + 视频站点分流那份 reference,中台里的模型据此知道怎么调用
应用广场 「下载器面板 DownloadX」——本地应用,端口 8720,一键启停
python scripts\install_to_assistant.py --check    # 只报告现状
python scripts\install_to_assistant.py            # 同步技能 + 应用
python scripts\install_to_assistant.py --update   # 技能已存在时覆盖(技能改动后重跑)
python scripts\install_to_assistant.py --no-app   # 只同步技能

中台开了登录之后 API 需要密码;不给 --password 时脚本自动退回直接写 data/hub.db (写前自动备份 hub.db.bak-<时间戳>-downloadx,并同步写 data/skills/<id>.md 镜像)。 两条路都实测过:应用行里的启动命令能真的拉起面板(/api/health 返回 DownloadX 0.2.0), 页面刷新即可见、不需要重启中台。

注意面板和命令行共用同一个引擎状态目录(%LOCALAPPDATA%\DownloadX),而引擎是单实例: 如果命令行正跑着前台下载,中台点「启动」不会成功(中台把子进程输出丢掉了,所以界面上 看不出原因)。这时要么先在命令行那边结束,要么让两边都连已启动的服务。

这里(项目内)是源,改完用一条命令同步到所有副本(Codex 加载目录 + 归档目录):

python scripts\sync_skill.py            # 同步到 ~\.codex\skills\downloadx 与 D:\Projects\skill\downloadx
python scripts\sync_skill.py --check    # 只报告差异,不写文件
python scripts\sync_skill.py --prune    # 顺带删除目标里多余的文件(精确镜像)

同步脚本按相对路径逐文件复制并校验 sha256 —— 直接 Copy-Item -Recurse 一个文件夹到 同名已存在目录会套出一层 downloadx\downloadx\(踩过,会让 skills 列表里出现两条同名 skill)。

三份副本的分工:

位置 角色
outputs/DownloadX/skill/downloadx/ 源,只改这里
~\.codex\skills\downloadx\ Codex 实际加载的那份,重启后生效
D:\Projects\skill\downloadx\ 归档 / 分发副本

用法(在任意会话里):

python "$env:USERPROFILE\.codex\skills\downloadx\scripts\dx.py" add <url> --wait --json
python "$env:USERPROFILE\.codex\skills\downloadx\scripts\dx.py" doctor   # 引擎/解释器解析诊断

引擎被挪走时用 DOWNLOADX_HOME=<路径> 指一次,不用改任何代码。


配置

优先级:环境变量 > config.json > 内置默认值。

$env:DOWNLOADX_DOWNLOAD_DIR       = "D:\Downloads"
$env:DOWNLOADX_MAX_CONCURRENT_TASKS = "5"
$env:DOWNLOADX_GLOBAL_SPEED_LIMIT = "2097152"   # 2 MiB/s,0 表示不限速
$env:DOWNLOADX_VERIFY_SHA256      = "true"
$env:DOWNLOADX_RAMP_ENABLED       = "true"      # 并发自校准(大文件才触发)
python -m downloadx serve

并发自校准的相关参数(默认值即可,通常不用动):

变量 默认 含义
DOWNLOADX_RAMP_ENABLED true 是否启用自校准
DOWNLOADX_RAMP_MIN_TOTAL_SIZE 25165824 小于 24 MB 的任务不做校准(不值得为测量花时间)
DOWNLOADX_RAMP_WARMUP_SECONDS 2.0 单连接测量窗口(其中前 25% 用于预热,不计入速率)
DOWNLOADX_RAMP_WARMUP_BYTES 4194304 单连接测量窗口的字节上限
DOWNLOADX_RAMP_PROBE_SECONDS 4.0 放开并发后的对比窗口
DOWNLOADX_RAMP_GAIN_THRESHOLD 1.15 放开后吞吐至少要是单连接的 1.15 倍,否则退回单连接

默认状态目录:%LOCALAPPDATA%\DownloadX(任务元数据、history.jsonl、单实例锁)。 下载文件不会放进状态目录。


已知边界

  • 服务只监听本地回环,没有鉴权 —— 它是本地工具,不要往公网暴露。
  • 单实例锁是"心跳 + 过期接管",不依赖 Windows 专有 API,跨平台一致。
  • 流式模式(服务端不给 Content-Length)无法断点续传,这是 HTTP 协议本身的限制。
  • 视频站点只做分流(交给 yt-dlp / 已有的 X skill),引擎自己不做解析;本机没有的工具不会自动安装。
  • BT / Magnet / 账号 / 云同步 / LLM 对话尚未实现,按 docs/ROADMAP.md 分阶段推进。

许可证

MIT © 2026 刃研社 (SCALPEL LAB)

下载行为与内容版权由使用者自行负责:本项目只提供工具,不绕过 DRM、付费墙、地域限制或账号限制。

—/ 5

No ratings yet

Manifest verification required

Commit fbb25b5d14c1

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout