多平台资源下载工作台

给「电脑水平有限的新手」和「连不上外网的国内用户」准备的一整套下载方案：从装浏览器、装扩展、导出 Cookie，到打开一个可视化网页点按钮下载，全流程有人带着走。

开箱即用：技能包自带便携 Python 运行时和全部下载引擎。用户电脑上不需要装过 Python、pip、uv、gallery-dl、yt-dlp 或任何命令行工具，解压即用。配置向导也不会去翻用户的硬盘。

本 skill 里不含任何个人凭据。cookies.txt 一律由用户自己在本地导出，只存在用户自己的电脑上。

智能体优先：用户是电脑小白，能自动化的环节一律不要交给用户。详见第一节。

简介（发布页可直接用，也可作为向用户介绍的开场白）

帮你把网上的图片视频存到电脑里的小工具

✨ 亮点一：可视化操作，新手零门槛 打开就是一个本地网页，大按钮、进度条、状态灯，下到哪一步一目了然 —— 不用敲命令，不用装 Python，解压双击就能用。

✨ 亮点二：一次下载整个账号的全部作品 粘一次主页链接，博主名下所有资源自动批量下载，不用一条条点。

支持的网站：小红书、抖音、微博、推特（X）、Instagram、TikTok

两种下载方式

主页链接 → 下载该账号所有资源
单条链接 → 下载这一条视频 / 图文

其它

自带运行环境，不用装 Python 或任何命令行工具
不收集账号密码，登录信息只存在你自己电脑上
支持开机自启，配好后开电脑直接用

发布页分类建议填「媒体处理」，开源协议填 Apache-2.0。包内含第三方开源组件（Cookie 导出扩展、各平台下载引擎），版权归各自作者所有。

〇、先获取技能包（本文件只是入口）

完整技能包有 2 万多个文件、约 700 MB，超过平台的上传限制，所以 平台上只放这一份 SKILL.md，程序本体托管在 GitHub 仓库：

https://github.com/zwqq1766616918-tech/media-downloader

取包这件事由智能体完成，不要丢给用户。 拿到本体后目录结构就是第六节写的那样（app/、runtime/、engines/ …），再按第三节的流程往下走。 这一步没做完，后面所有步骤都无从谈起。

智能体自己取（默认走这条）

国内环境优先走镜像 —— GitHub 直连常被 DNS 污染，镜像稳定得多：

# 国内推荐：走镜像
git clone https://gh-proxy.com/https://github.com/zwqq1766616918-tech/media-downloader.git

# 能直连 GitHub 时
git clone https://github.com/zwqq1766616918-tech/media-downloader.git

克隆下来的目录本身就是完整技能包，放到当前环境的 skills 目录（Trae 是 .trae/skills/media-downloader/）后直接进第三节。

环境里没有 git 时，用 ZIP 直链，同样由智能体执行：

# 国内推荐：走镜像
curl -L -o media-downloader.zip https://gh-proxy.com/https://github.com/zwqq1766616918-tech/media-downloader/archive/refs/heads/main.zip

# 能直连 GitHub 时
curl -L -o media-downloader.zip https://codeload.github.com/zwqq1766616918-tech/media-downloader/zip/refs/heads/main

ZIP 解压后会多一层 media-downloader-main/，记得摊平到 skills 目录下，保证 .trae/skills/media-downloader/app/ 这一层存在。

兜底：智能体确实没法联网执行时

只有当所在环境既不能 git 也不能 curl 时，才把链接交给用户自己去点。国内用户直接打开这个加速链接，浏览器就会开始下载，不用装任何东西：

https://gh-proxy.com/https://github.com/zwqq1766616918-tech/media-downloader/archive/refs/heads/main.zip

能直连 GitHub 的话也可以走原站：打开 https://github.com/zwqq1766616918-tech/media-downloader → 点绿色 Code 按钮 → Download ZIP。

下载完解压到路径短、无空格、无中文的位置（例如 D:\media-downloader），然后告诉智能体包在哪，由智能体接着往下做。

镜像站说明

用法就是在原始 GitHub 地址前面拼一个前缀，clone、ZIP、Release 都适用。

| 镜像前缀 | 状态（2026-10 实测） | | --- | --- | | https://gh-proxy.com/ | ✅ 可用，首选 | | https://gh-proxy.org/ | ✅ 可用，备选 | | https://ghfast.top/ | 时好时坏 | | https://mirror.ghproxy.com/ | 时好时坏 |

公益加速站时好时坏是常态：首选挂了就换备选，两个都挂再试其它前缀， 不要把某一个写死。这类站点会看到你请求的仓库地址，但本仓库全是公开内容，没有隐私风险。

已经连了 GitHub 的环境

用 GitHub 连接器直接读仓库文件即可，不必整包克隆 —— 但 runtime/、engines/ 是二进制依赖，必须落到本地磁盘才能运行，不能只读不存。

一、核心原则：能自动化的，绝不交给用户

本 skill 面向的是电脑小白。让他们双击 bat、敲命令、复制粘贴路径，基本等于让他们放弃 —— 所以默认工作方式是智能体全程代办。

| 环节 | 谁来做 | 具体做法 | | --- | --- | --- | | 取技能包 | 智能体 | git clone 镜像 / curl ZIP 解压（第〇节） | | 生成配置 | 智能体 | python app/配置向导.py --yes | | 准备浏览器 | 智能体 | 先检测本机；没有就下便携版解压到 browser/ | | 启动下载服务 | 智能体 | 后台起服务，再自己探一次 /api/state | | 下发下载任务 | 智能体 | POST /api/task | | 盯进度、报结果 | 智能体 | 轮询 GET /api/state，用大白话汇报 | | 帮用户打开文件夹 | 智能体 | POST /api/opendir | | 扫码登录 | 用户 | 抖音 / 小红书，需要用户的手机 | | 用本人账号登录网站 | 用户 | 推特 / Instagram / 微博 / TikTok | | 极耗时操作的等待 | 可交给用户 | 任务已入队，用户可先干别的 |

明确不要做的事：

❌ 不要让用户双击 bat、不要让用户敲命令、不要让用户复制粘贴路径
❌ 不要让用户自己去装 Python / 下载引擎 / 浏览器
❌ 不要把「怎么启动服务」这种问题丢给用户琢磨
❌ 不要在没试过自动化之前，就宣布「这一步需要用户手动」

只有两种情况例外：智能体确实做不到（需要用户的手机、用户的账号），或者这一步非常耗时（下 200 MB 浏览器、下几千条作品）—— 此时可以请用户参与，但也只请他做那一个动作，别让他理解原理。

二、能做什么

| 能力 | 说明 | | --- | --- | | 单条下载 | 粘贴一条作品链接，只下载那一条 | | 主页批量 | 粘贴博主主页链接，下载该号全部作品 | | 可视化界面 | 本地网页，大按钮、状态灯、进度条，无需命令行 | | 开机自启 | 可一键加入开机自动后台运行（需先征询用户） |

支持的平台：小红书、抖音、推特 X、Instagram、TikTok、微博。

平台能力差异（务必先告知用户，避免踩空）：

抖音：主页和单条都支持（/user/、/video/、/note/、v.douyin.com 短链、纯数字 ID 都行）；需要额外装「抖音补充包」，且电脑上要有 Chrome / Edge（本包不带浏览器内核，见第八节）
小红书：必须先启动本地 MCP 服务并扫码登录，否则报「MCP 服务未启动」
推特 / Instagram / 微博 / TikTok：需要 cookies.txt，缺失时自动退回读本机 Chrome 登录态（不一定成功）

三、智能体标准作业流程

按顺序执行，每一步都由智能体动手，只在第四节列出的情形才请用户参与。

第 1 步：取包

见第〇节。智能体自己 git clone（优先镜像）或 curl + 解压，最终确保 .trae/skills/media-downloader/app/ 存在。

第 2 步：生成配置（全自动）

python app/配置向导.py --yes

--yes = 直接写入，不再询问（这正是智能体要的）。只想体检、不写配置用 --check。

检测到自带的 runtime/ 和 engines/ 时，它直接生成配置，不会扫描用户硬盘；只有在自带件缺失（老用户自行改过包）时，才会退回去扫描本机的下载引擎。

第 3 步：准备浏览器（全自动）

抖音需要一个真实浏览器来生成签名、保存扫码登录态。先检测：

python app/配置向导.py --check      # 输出里有「浏览器」一项

本机没有 Chrome / Edge 时，智能体自己下一个便携版，不要引导用户去装：

# 1) 查最新稳定版号（返回 JSON 目录列表，取最后一个版本目录名）
curl -s https://registry.npmmirror.com/-/binary/chrome-for-testing/

# 2) 下 win64 便携包（约 200 MB，纯国内直连，不用翻墙）
curl -L -o chrome-win64.zip https://registry.npmmirror.com/-/binary/chrome-for-testing/<版本号>/win64/chrome-win64.zip

# 3) 解压到技能目录下的 browser\（例如 browser\chrome-win64\）

实测可用（2026-10）：.../157.0.8087.2/win64/chrome-win64.zip → HTTP 200，约 200 MB。解压后 browser\chrome-win64\chrome.exe 会被自动识别，不用改任何配置 （browser/ 目录递归找 chrome.exe / msedge.exe）。

200 MB 下载比较久，属于「可交给用户」的耗时情形：智能体可以先下，也可以把这一步交给用户点一下 —— 但不要把它变成一道用户必须理解的技术题。

第 4 步：启动下载服务（全自动）

后台起服务，不要弹黑窗口打扰用户：

python app/下载工作台.py

服务地址 http://127.0.0.1:8790。启动后智能体先自己探一次再往下走：

curl -s http://127.0.0.1:8790/api/state

返回 ok: true 说明服务活着；platforms 是各平台状态灯，browser 是识别到的浏览器路径。

第 5 步：下发下载任务（全自动）

curl -X POST http://127.0.0.1:8790/api/task \
  -H "Content-Type: application/json" \
  -d '{"url":"<链接>","mode":"author","dest":"<保存目录>","limit":0}'

| 字段 | 说明 | | --- | --- | | url | 主页链接或单条链接，可以一次给多条（每行一条） | | mode | author = 下载整个主页；single = 只下载这一条 | | dest | 保存目录，不存在会自动创建；留空则用默认目录 | | limit | 数量上限，0 或留空 = 全部 |

返回 {"ok":true,"created":[{"id":"...","url":"...","platform":"..."}]}。

抖音的单条 / 主页由程序自动判别，智能体不用自己判断链接类型 —— 粘 /video/、/note/、短链、纯数字 ID 都会走单条，粘 /user/ 走主页。

第 6 步：盯进度、报结果（全自动）

curl -s http://127.0.0.1:8790/api/state

tasks 里每条含 status（queued/doing/done/failed）、stage、error、 img_count、vid_count、author_dir。轮询到 done 或 failed 为止，然后只把结果讲给用户听：

「下完了，XX 的 128 张图、6 个视频，在 D:\下载\XX 里。」

用户想看一眼文件夹，用 POST /api/opendir {"dir":"..."} 帮他打开，别让他自己找。

失败时看 error 字段，对照 references/故障排查.md 处理；常见的就是 Cookie 失效（第 4 节第 2 条）或没登录。

第 7 步：问一句要不要开机自启

只需问一次，用户不关心就直接跳过。要的话由智能体执行 app/开机自启-开启.bat；想取消执行 app/开机自启-关闭.bat。

加入自启后：开机自动在后台运行（不弹黑窗口、不自动开浏览器），用户只要打开浏览器访问 http://127.0.0.1:8790 即可。

四、必须用户参与的情形（白名单）

只有下面几种才把用户请出来，其余一律智能体代办。

1. 扫码登录（抖音、小红书）

需要用户的手机，智能体代替不了。做法：智能体启动登录流程，浏览器窗口会弹出二维码，告诉用户「用抖音 / 小红书 App 扫一下这个码」，扫完由智能体继续。不要把「扫码登录」讲成一串技术步骤，用户只需要掏出手机扫一下。

2. 需要用户账号的网站（推特 X / Instagram / 微博 / TikTok）

这些站必须登录才能看内容，登录态属于用户本人。两条路，按顺序试：

先试全自动：程序在缺 cookies.txt 时会自动读用户本机 Chrome 的登录态 （--cookies-from-browser chrome）。用户平时在这台电脑的 Chrome 上登录过这些网站，就常常能直接跑通 —— 先走这条，成功了就完全不用打扰用户。
自动失败再请用户：让用户在自己 Chrome 里登录该网站，再用扩展导出 cookies.txt。这一步用户必须参与（涉及他的账号），但要把步骤压到最短：扩展是离线自带的（assets/cookie导出工具/，不用商店），智能体帮他打开 chrome://extensions，他只需要「开发者模式 → 加载已解压的扩展程序 → 选那个文件夹」三下。

各平台必须包含的关键字段（缺了基本抓不到数据）：微博 SUB/SUBP、Instagram sessionid/csrftoken、推特 auth_token/ct0、TikTok sessionid。

导出后放到 cookies/<平台>/cookies.txt（目录由配置向导自动创建）：推特 cookies/twitter/、Instagram cookies/instagram/、微博 cookies/weibo/、TikTok cookies/tiktok/。

3. 极耗时的操作

下 200 MB 的浏览器、下几千条作品这类。任务入队后告诉用户「这个要跑一会儿，你可以先干别的」，而不是让他盯着屏幕等。智能体自己能挂着跑就自己挂。

4. 需要用户拍板的

下载存到哪个盘、要不要开机自启。问一句就行，别展开成技术讨论。

五、界面怎么用（当用户坚持自己点）

界面是给用户兜底的：智能体能代劳就代劳；用户想看进度、或想自己粘链接时，再把这个讲给他。

粘贴链接：主页链接或单条链接都行，可以一次粘多条（每行一条）
选方式：「下载整个主页」/「只下载这一条」
选保存位置：默认已设好；想换就点「选择文件夹」
数量上限（可选）：想先试水填 20，留空就是全部
点 开始下载，在下面「下载记录」看进度

顶部状态灯：绿色 = 该平台已就绪；红色 = 还没配好，鼠标放上去会显示原因。

六、目录结构

media-downloader/
├── SKILL.md                  ← 本文件
├── runtime/                  ← 【自带】便携运行时，用户无需装 Python
│   ├── python/               便携 Python 3.12（跑 gallery-dl / 小红书 / TikTok）
│   └── pkgs/                 各引擎的依赖包组
│       ├── gallerydl/        gallery-dl + yt-dlp + 依赖
│       ├── xhs/              小红书 XHS-Downloader 的依赖
│       └── mediacrawler/     （可选补充包）抖音 MediaCrawler 的依赖
├── engines/                  ← 【自带】下载引擎
│   ├── tiktok/tiktok_dl.py   TikTok 下载器
│   ├── xhs-downloader/       小红书 XHS-Downloader 源码
│   ├── xiaohongshu-mcp/      小红书 MCP 服务（含扫码登录）
│   └── mediacrawler/         （可选补充包）抖音 MediaCrawler 源码
├── tools/
│   └── 打包-抖音补充包.py     维护用：把本机 MediaCrawler 打成抖音补充包
├── references/
│   ├── 环境准备.md            ← 浏览器/扩展/cookie 的详细图文步骤（含国内下载地址）
│   ├── 平台与引擎对照.md       ← 每个平台用什么引擎、需要什么凭据
│   └── 故障排查.md            ← 常见报错与处理
├── assets/
│   └── cookie导出工具/         ← 离线版 Cookie 导出扩展 + 一键安装脚本
├── app/
│   ├── 下载工作台.py           ← 本地下载服务（只用 Python 标准库）
│   ├── 配置向导.py             ← 生成 config.json（自带件优先，不扫本机）
│   ├── config.example.json     ← 配置模板（不含任何个人信息）
│   ├── 网页/index.html         ← 可视化下载界面
│   ├── engine/xhs_worker.py    ← 小红书下载子进程（便携版）
│   ├── 启动下载工作台.bat
│   ├── 配置向导.bat
│   ├── 安装浏览器.bat          ← 检测/引导安装 Chrome 或 Edge（抖音用）
│   ├── 开机自启-开启.bat
│   ├── 开机自启-关闭.bat
│   └── 后台启动.vbs
├── browser/                  ← 便携版浏览器（智能体自动下载解压，非必需）
└── cookies/                  ← 用户自己导出的 cookies.txt（运行后才有）

运行时才会产生、不随包分发的三项：config.json（向导生成）、运行记录/、下载/。装了抖音补充包还会多出 runtime/python311/。抖音所需的浏览器不随包分发 —— 优先用用户本机已装的 Chrome / Edge，没有就由智能体下载便携版解压到 browser/ （见第三节第 3 步）。

七、分享给别人之前（重要）

技能包出厂时就不含任何个人数据，可以直接分享。分享前只确认这三项不存在：

config.json（里面记着本机路径）
运行记录/（任务历史与日志）
下载/（下载下来的内容）

另外，cookies/ 目录里如果有你自己导出的 cookies.txt，也必须删掉再分享。 cookies.txt 从来不进 assets/、app/、references/、runtime/、engines/，只存在用户自己电脑上。

整包已托管在 GitHub 仓库（见第〇节），分享时把仓库链接给对方即可 —— 对方那边的智能体会自己把包取到本地。

八、抖音补充包（可选）

抖音走 MediaCrawler，它的依赖是 Python 3.11 编译的（跟主运行时的 3.12 不通用），加起来约 600 MB，所以不放进主包 —— 装不装都不影响其它五个平台。

抖音需要一个真实浏览器来执行签名脚本、保存扫码登录态。本包不再自带 Playwright 的 Chromium 内核（约 400MB），改为复用本机浏览器（MediaCrawler 侧读环境变量 MC_BROWSER_PATH）：优先本机已装的 Chrome / Edge，其次技能目录下 browser/ 里的便携版。

分发时把补充包一起带上（在技能目录下执行，需要本机已装好 MediaCrawler）：

python tools/打包-抖音补充包.py

它会产出：

| 路径 | 内容 | | --- | --- | | engines/mediacrawler/ | MediaCrawler 源码（已剔除登录态、下载数据）+ 三个启动脚本 | | runtime/python311/ | 便携 Python 3.11 | | runtime/pkgs/mediacrawler/ | MediaCrawler 的依赖 |

打包完再跑一次配置向导，抖音状态灯就会变绿。

抖音的三种用法：

| 方式 | 说明 | | --- | --- | | 界面里粘主页链接 | 自动按「下载整个主页」采集该博主全部作品 | | 界面里粘单条链接 | 自动按「只下载这一条」处理（/video/、/note/、短链、纯数字 ID） | | POST /api/task 带 mode | 智能体走接口下发，效果同上 |

第一次会弹出浏览器窗口，用抖音 App 扫码登录即可（这一步需要用户，见第四节第 1 条），登录态缓存在 engines/mediacrawler/browser_data/，之后一般不用重复登录。

不想带抖音：跳过这一步即可，抖音状态灯会显示「未安装抖音补充包（可选）」。想删掉已打的包：python tools/打包-抖音补充包.py --clean 电脑上没有 Chrome / Edge 时，由智能体下载便携版解压到 browser/（第三节第 3 步），不要引导用户去理解「浏览器内核」这回事。

九、硬性约束

绝不读取、复制、上传用户的 cookies.txt 内容；只把它当作路径传给下载器
绝不把用户的 Cookie、账号、下载内容写进 skill 的任何文件
绝不在自带件齐全时扫描用户硬盘
能自动化的绝不交给用户：不要把 bat 脚本、命令行、路径复制粘贴丢给小白用户；只有扫码登录、用户本人账号登录、极耗时等待这三类才请用户参与
抖音不需要浏览器内核随包分发；缺浏览器时由智能体下载便携版解压到 browser/ （或复用本机已装的 Chrome / Edge），不要自己往包里塞内核
下载任务串行执行（单 worker），不要并发拉多个平台
首次使用务必先跑配置向导；config.json 不存在时启动脚本会自动引导