The user provides a public social media link that they have the right to save; this Skill identifies the platform, reuses existing authorization, downloads the original media, and delivers the file plus a JSON verification report. Prioritize reducing wait time, repeated logins, and intermediate choices.
Triggers
Activate when
- The user says “download this video link”, “save this WeChat Channels video”, “grab this Douyin/Xiaohongshu/Bilibili content”.
- The user directly provides a
weixin.qq.com/sph/..., Douyin, Xiaohongshu, Kuaishou, Bilibili, Weibo, Tieba, or Zhihu content link and requests a local file. - User asks “help me download this media link”, “save this WeChat Channels video”, or “fetch this post and its media”.
Do not activate when
- The user provides only a title and asks to search for a movie, compare versions, or download a torrent; hand off to
lov-media-fetch。 - The user already has footage and asks for editing, mixing, transcoding, or producing a final cut for publishing; hand off to
lov-media-creator。 - The user wants to batch-scrape accounts, comments, or user profiles, or wants private, paid, or geo-restricted content they have no right to access; this Skill only handles a single public link or a small number of explicitly listed public links and does not bypass access controls.
User Profile (cross-session)
Each run reads the skill.yaml declared in user-profile/v1: user language, workspace output location, shared preferences, and the Skill records under skills.lov-media-crawler . Resolution order is current request, project context, Skill records, shared preferences, user Profile, safe defaults.
When the user explicitly declares a long-term output directory, download concurrency, or media format preference, use scripts/profile_store.py record --confirm to write it back to the Profile, and report the saved path. Cookies, Tokens, proxy passwords, and browser login states are never written to the Profile; WeChat Channels Yuanbao authorization goes only into the OS credential store or the current process environment. See the full contract at references/user-profile.md。
Skill Group Composition
Read before running references/skill-composition.md. This Skill independently owns the acceptance of “known link → verified local media”; adjacent Skills hand off only via links or local files and are not hidden dependencies.
Workflow (MANDATORY)
Must be executed in the following order.
Step 0: Resolve root directory, Profile, and runtime
- Use
SKILL_DIR, otherwise infer the install directory from the current Skill context. - Verify that
scripts/media_crawler.py、scripts/authorize_yuanbao.py、references/platform-matrix.md、references/upstream-and-licenses.mdexists. - Run
python3 "$SKILL_DIR/scripts/media_crawler.py" doctor --json, installing only the optional dependencies that the current link actually requires. - By default, output to the user's explicit directory, the Profile's
records.output_dir, the project output directory, and finallydownloads/under the current directory. Existing finished files must not be overwritten.
When running manually:
export SKILL_DIR="/path/to/lov-media-crawler"
Step 1: Verify link, permissions, and target
- Extract the unique link from the request; for multiple links, create an independent job for each and do not mix them in one directory.
- Only process content the user has the right to access and save. Do not bypass login, payment, private, geo, or DRM controls.
- When the user does not specify a format, keep the source media; do not transcode by default. When the user does not specify a filename, generate a safe filename from the author/title.
- Probe before downloading; the probe phase must not create fake success files:
python3 "$SKILL_DIR/scripts/media_crawler.py" probe URL --json
Step 2: Choose the shortest usable path
Route according to references/platform-matrix.md :
-
WeChat Channels: first read the system credential or
LOV_MEDIA_CRAWLER_YUANBAO_COOKIE, parse the share link through Tencent Yuanbao, then obtain the CDN address via the WeChat Channels API. When authorization is missing, run a visible browser authorization once:python3 "$SKILL_DIR/scripts/authorize_yuanbao.py" --test-url URLPublic Workers are disabled by default. Use it only when the user explicitly agrees to send public share links to that service:
--allow-public-resolver; prefer the user's self-hosted--worker-url. When a user decision is needed (whether to hand the link to a public parsing service, whether to download a third-party stream-fetching program), ask one focused question via the host's AskUserQuestion; do not assume consent in the conversation.Yuanbao auth passes but returns empty
wx_export_id(resolver_failed), which means the publisher restricted parsing outside WeChat, and re-authorization is ineffective. In this case useWeChat client stream fetching:downloaddefault--via auto, falling back automatically when Yuanbao fails and localwx_channels_downloadis online;--via wxclientforces this path. Preparation steps:python3 "$SKILL_DIR/scripts/media_crawler.py" setup-wxclient # 下载固定版本、校验 SHA256、生成工作目录 bash "$SKILL_DIR/scripts/wxclient.sh" start # 用户自行执行:需要管理员权限 bash "$SKILL_DIR/scripts/wxclient.sh" status # 确认 API 在线且视频号页面已连接Startup installs the proxy root certificate and points the system proxy to 127.0.0.1:2023; this is a system security setting and must be executed by the user in their own terminal; the Agent must not run it on their behalf. Then the user opens any Channels page in the WeChat PC client and keeps it open; the Skill uses
127.0.0.1:2022's/api/channels/feed/profileto fetch details,/api/v1/download_task/createto create a task and poll until completion, then performs the same media verification. -
Platforms supported by MediaCrawler: use an existing local checkout; if none, first inform about the upstream non-commercial learning license, then run:
python3 "$SKILL_DIR/scripts/media_crawler.py" setup-mediacrawler \ --accept-noncommercial-licenseThe adapter pins a verified commit, disables comment scraping, scrapes only the specified content, enables media download, and starts an isolated Chrome Profile on an available debug port starting from 9333, without connecting to 9222 or other existing debug instances.
-
Direct media URL: skip the browser and crawler and go directly to the transport layer.
Do not hide the fact that MediaCrawler does not support Channels; the Channels adapter is this Skill's independent extension path.
Step 3: Download and immediate feedback
python3 "$SKILL_DIR/scripts/media_crawler.py" download URL \
--output-dir OUTPUT_DIR \
--connections 8 \
--json-report OUTPUT_DIR/result.json
- Prefer aria2's multi-connection and resumable download; when aria2 is unavailable, use curl's resume, retry and progress bar.
- The first visible feedback should appear immediately after link parsing; during long downloads, report progress, current rate and ETA at least once per minute.
- On failure keep a resumable
.partfile; retry the same URL and output path without creating a second full payload. - On filename conflicts, generate a stable suffix unless the user explicitly allows overwriting.
Step 4: Verify the finished product
The completion condition is not HTTP 200, but:
- The file exists and is non-zero, and the response is not an HTML/JSON error page.
- For MP4/MOV check
ftyp, for WebM/MKV check EBML, for images check PNG/JPEG/GIF/WebP magic numbers; when video is available, additionally useffprobeto verify streams, duration, codec and resolution. - The actual byte count matches
Content-Length(when provided by the server). - The JSON report includes
status、platform、source_url、output_path、bytes、elapsed_seconds、average_mbps、verificationandcontext_id。
When Channels yields only title/cover but no video stream, the status must be authorization_required or resolver_failed, and must not be written as downloaded.
Step 5: Report results
The first sentence gives success/failure and the local file path. On success, add size, elapsed time, average speed, platform and verification results; on failure, give the error code,context_id, missing conditions, and a ready-to-copy next-step command. Distinguish:
resolved: metadata or media URL obtained;downloaded: payload written to disk;verified: container/stream and size checks passed.
Dependencies
- Required: Python 3.9+, curl.
- Recommended: aria2 (multiple connections and reliable resume), ffprobe (media verification).
- WeChat Channels one-time authorization: Playwright Python package and Chrome; credentials are stored in the macOS Keychain by default.
- WeChat Channels client stream capture (macOS):
ltaoo/wx_channels_downloadpinned version v260907, downloaded and verified bysetup-wxclient; launching requires administrator privileges, and WeChat PC client must be logged in. - MediaCrawler path: Git, uv, Node.js, Chrome, plus the upstream project's own dependencies; its code and use are governed by the upstream non-commercial learning license.
For the full platform boundaries, see references/platform-matrix.md; for upstream and licenses, see references/upstream-and-licenses.md; for error codes, see references/troubleshooting.md。
General feedback loop
When a user raises revision feedback during a Skill-driven task, the following must be done before continuing with the current artifact:
- First determine whether the feedback is
task-specific(this task only) orreusable(reusable across tasks). task-specificModify only the current task; do not change the Skill.reusableFirst determine the scope: for domain rules, update the corresponding canonical Skill first; for rules that apply to all Skills, update the shared specification first.- After completing the rule update, version, lint, and distribution verification, then apply the changes to the current task.
reusableModifications invalidate prior "confirm," "continue," and "send it" approvals; after completing the current artifact modification and reading it back, you must stop and wait for the user's next instruction, without automatically proceeding to publishing, submitting, or any other external write.