| name | lov-media-fetch |
| description | Use when the user asks to find and download a film, series, or long video. 以 aria2 为默认传输后端，完成多源测速、续传、容量预检、版本核验与字幕验收；也适用于“帮我下载这部电影”。
|
| license | MIT |
| compatibility | Portable Agent Skills format; Python 3.9+, aria2 1.36+, and ffprobe recommended. qBittorrent 5.x Web API is an optional discovery, BitTorrent-management, and seeding adapter.
|
| metadata | {"author":"contributors","version":"0.4.0","tags":["media-discovery","release-selection","download-orchestration","quality-control","aria2-primary","optional-qbittorrent","resumable-download","subtitle-handoff"],"card_standard":"lovstudio/skill-card/v1","dependencies":["python","pyyaml","aria2","ffprobe"]} |
Media Fetch
Turn one natural-language request into a verified local media file. Search broadly,
identify the actual cut, balance picture quality against size, check storage before
transfer, race viable sources, monitor the winner, recover from stalls, and inspect
the completed file.
Triggers
Activate when
- 用户说“帮我找并下载这部电影”“下载导演剪辑版，画质好一点但别太大”“找带中英字幕的完整版”。
- 用户给出片名、年份、版本偏好，或已有 Magnet/Torrent，希望自动完成选择、下载和验收。
- The user asks to find and download the best release, fetch an extended cut, or download a compact high-quality copy with Chinese and English subtitles.
Do not activate when
- 用户只想了解影片资料、比较不同剪辑或获得观看建议，不要求取得本地文件。
- 用户只要下载普通网页文件、软件安装包、网页视频片段或直播流。
- 用户明确要求发布、上传、转码压制或制作字幕；这些是下载完成后的独立任务。
Product contract
- One request should normally run end to end without repeated confirmation.
- Prefer an edition whose identity is supported by runtime, release metadata, or
file-level evidence. A filename alone is weak evidence.
- “Best” means the highest useful viewing quality inside the user's size and disk
budget, not the largest file or highest advertised resolution.
- Default to embedded Simplified Chinese plus English subtitles. Treat filename
claims as hints until streams or synchronized external subtitles are inspected.
- Ask the user only when title identity is ambiguous, editions contain materially
different content, or the top candidates are close enough that taste decides.
- Never begin payload transfer before the destination capacity check passes.
- Keep observing an active job. A task added to a client is not a completed result.
- Completion means that the final local payload exists and the verification report is
written. A client-reported 100% is only an intermediate signal.
- Keep advertised seeders, observed peers, metadata readiness, received bytes, and
sustained speed as separate evidence fields. A large seeder count is not a speed
promise.
- Use aria2 as the default transfer backend for direct URLs, Metalinks, Magnets, and
Torrent inputs. Enable qBittorrent only when its search plugins, queue UI, swarm
inspection, or long-term seeding materially helps the task. Record every backend
choice and switch; do not create a second full payload by accident.
- A missing
zh-Hans stream is a recoverable subtitle gap, not a reason to mislabel
the media. The subtitle branch may consult lov-subtitle-freedom-skill for
timestamp-preserving UTF-8 SRT handling. Its English-learning gloss and ASS modes
stay opt-in; plain Chinese subtitle delivery remains a separate, clearly named SRT.
User configuration
Resolve defaults through $KIT_DIR/references/user-config.md. On first use, show the
resolved output directory and preferences before persisting them. Keep credentials in
environment variables or the operating system credential store.
Skill Kit modules
Load the selected module completely before acting:
$SKILL_DIR/skills/media-discovery/SKILL.md — identify the title and collect normalized candidates from several independent discovery paths.$SKILL_DIR/skills/media-selection/SKILL.md — verify editions and rank picture, codec, size, audio, subtitles, health, and evidence.$SKILL_DIR/skills/media-acquisition/SKILL.md — capacity preflight, parallel swarm probing, winner selection, progress observation, stall recovery, and cleanup.$SKILL_DIR/skills/media-verification/SKILL.md — inspect the downloaded files, edition runtime, streams, subtitle coverage, completeness, and final path.
kit.yaml defines the available pipelines. Shared schemas and decision rules live in
$KIT_DIR/references/.
Workflow (MANDATORY)
You MUST follow these steps in order.
Step 0: Resolve runtime and select a pipeline
- Resolve
SKILL_DIR, KIT_DIR, configuration, aria2 availability, and ffprobe.
Detect qBittorrent as an optional capability; its absence must not block discovery,
transfer, resume, verification, or reporting.
- On first use, bootstrap missing stable aria2 and ffprobe dependencies through the
platform's native package manager. When qBittorrent is explicitly enabled, keep its
WebUI on loopback and its credential in the operating system credential store. Do
not put secrets in profile or reports.
- Preserve existing client tasks. Every task created by this Skill must receive a
unique job tag and an isolated probe directory.
- Select
full for a title request, choose for comparison only, download-known
for supplied links, resume for an existing job, or verify for a local file.
- Read
$KIT_DIR/references/candidate-schema.md, then validate all handoff JSON.
Step 1: Resolve the requested work
Capture title, year, media type, season/episode when relevant, edition preference,
maximum size, destination override, audio/subtitle preference, and urgency. Infer
omitted values from the portable profile. Do not ask the user to choose tooling.
Step 2: Discover independent candidates
Run the discovery module. Use at least two independent discovery paths when possible:
direct web or catalog research, a local DHT index such as Rats Search, user-supplied
links, or the optional qBittorrent search API. Deduplicate by info hash and canonical release identity. Preserve
a .torrent URL or local Torrent path even when its info hash is not known until
metadata resolution.
For title and edition truth, prefer distributor, studio, disc, catalog, or reliable
release metadata. Keep search-result claims separate from verified facts.
Step 3: Rank releases and resolve genuine ambiguity
Run the selection module and scripts/rank_candidates.py. Apply
$KIT_DIR/references/quality-policy.md.
- Auto-select when one candidate clearly leads and its edition is supported.
- Show at most three concise choices when the output says
choice_required=true.
- Explain only the user-facing tradeoff: edition/content, picture, size, subtitles,
and current health. Do not expose internal scoring mechanics unless asked.
Step 4: Preflight destination capacity
Resolve the destination, candidate size, probe concurrency, temporary probe budget,
fallback resume allowance, and free-space reserve. Run scripts/storage_preflight.py
before starting either backend.
If capacity is short, report available, required, and shortfall immediately. Offer the
best smaller candidate or a different destination, then wait for that user-facing
decision. Never silently consume the reserve.
Step 5: Probe, select, and download
Run the acquisition module and $KIT_DIR/references/acquisition-policy.md.
- Probe up to the configured concurrency in isolated per-candidate directories. Use
aria2 by default and allocate distinct listen/RPC ports for concurrent jobs.
- Observe warm speed, sustained speed, availability, peers, metadata readiness, and
ETA; a short burst alone does not win.
- Pause non-winners, move the winner to the final destination, and continue polling.
- If the winner stalls beyond the configured threshold, pause it and first try the
next proven candidate. Preserve the same aria2 job identity and
.aria2 state when
restarting an input. Switch to qBittorrent only when it is enabled and measured
evidence shows a healthier swarm or the user needs its queue/seeding behavior.
Record the reason, backend, and observed rate for each switch.
- If all candidates are slow, return to discovery for another wave.
- Keep the terminal session alive and poll at intervals short enough to provide the
user a progress update at least once per minute during active work.
- Clean only exact job-tagged losing tasks and their isolated probe files after the
final candidate is complete. Leave pre-existing client tasks untouched.
Step 6: Verify the completed media
Run the verification module and scripts/verify_media.py.
- Confirm a readable video stream, non-zero duration, expected resolution and codec,
audio tracks, subtitle streams, and duration close to the selected edition.
- Inspect every episode for episodic requests; a season folder is complete only when
the requested episode set is present.
- When preferred subtitles are missing, search for a subtitle from the exact release
or a synchronized subtitle checked against duration and scene boundaries. For a
Simplified Chinese SRT handoff, preserve cue timing, UTF-8, source immutability,
and adjacent naming as described in
references/subtitle-handoff.md; do not create
an English-learning gloss or ASS file unless explicitly requested.
- Recheck final free space and ensure no partial suffix remains on the primary file.
Step 7: Report the result
Lead with completion status and the exact local path. Include title/edition, video and
audio summary, subtitle coverage, final size, advertised versus observed source
health, transport trace, elapsed time, and any remaining evidence gap. Distinguish
download_status, verification_status, and subtitle_status.
References
$KIT_DIR/references/candidate-schema.md — normalized candidate and decision JSON.$KIT_DIR/references/quality-policy.md — edition, picture, codec, size, language, and ambiguity rules.$KIT_DIR/references/acquisition-policy.md — capacity, probing, monitoring, switching, and cleanup rules.$KIT_DIR/references/user-config.md — portable defaults and secrets handling.$KIT_DIR/references/subtitle-handoff.md — Simplified Chinese SRT matching and the
opt-in handoff to lov-subtitle-freedom-skill.
Dependencies
- Python 3.9+ for deterministic helpers.
- aria2 1.36+ for primary HTTP(S), Metalink, Magnet, and Torrent acquisition.
- Optional qBittorrent 5.x with WebUI enabled for integrated search, BT management,
queue visibility, or long-term seeding.
- Search plugins or another discovery adapter for title search.
ffprobe from FFmpeg for final stream and duration inspection.- Optional Rats Search for independent DHT discovery.
Runtime context (shared)
运行前读取本 Skill 包的 skill.yaml，由宿主提供 skill-runtime/v1 上下文。字段解析顺序为：当前请求、项目上下文、个人 Preferences、品牌 Profile、通用默认值。
- 只使用 Manifest 声明的字段；Profile 保存公开品牌事实，Preferences 保存个人工作偏好。
required: true 字段缺失时，按 Manifest 的问题配置向用户提出一个聚焦问题；用户明确同意后再保存回答。- 报错提供可复制的
context_id、字段路径与来源，诊断内容避开秘密、完整私人路径和原始配置。
