name: clawd-media-track description: "Resource tracking and acquisition workflow for media resources. MUST use when the user asks to get, add, track, monitor, search, acquire, transfer, or initialize movies, TV shows, anime, Pansou resources, or 115 cloud storage items with the clawd-media-track system. For every clawd-media-track task: first read mandatory references in order, identify task type (Type 1/2/3), output step-labeled checkpoints, wait for explicit user confirmation before any side-effecting action, and verify side effects after execution."

clawd-media-track Skill

FIRST ACTIONS (MANDATORY)

Before any clawd-media-track reasoning or tool use:

1. Read references/00-bootstrap-init.md
2. Check whether bootstrap is complete
3. If bootstrap is incomplete, stay in init mode and do not enter Type 1 / 2 / 3 yet
4. If bootstrap is complete, read references/01-environment-contract.md
5. Read references/02-global-constraints.md
6. Read references/03-methods-reference.md
7. Determine whether the task is Type 1, Type 2, or Type 3
8. Read the matching type checklist
9. Output the current checkpoint as [Type X - Step N]
10. STOP and wait for user confirmation before any side-effecting action

DO NOT:

• skip mandatory references
• guess the task type
• claim "no resource" before query completion/retry
• execute transfer/create/delete/mark actions without explicit user confirmation
• skip post-action verification

Critical Safety Notes

This system can make destructive or rate-limit-sensitive 115 calls if used carelessly.

Read the references in order and follow the checklist for the current task type. Do not improvise around them.

In particular:

• Directory targets come from environment-backed CID configuration, not guesswork.
• flatten_directory() is only valid on final landing directories:
  • movie leaf directories directly under MOVIES_CID
  • season leaf directories ending with Season <number>
• Root/media/category directories are protected and must never be used as flatten targets.
• list_files() is shallow by default. Recursive scans on protected directories are blocked for safety.
• If a method raises SAFETY_VIOLATION, stop and report the exact target/path instead of retrying with guesses.
• Code-level guardrails are a backstop, not a substitute for reading the checklist and choosing the correct target.

This skill is split for progressive loading.

Read only what is needed, but never skip required safety/rules for the current task type.

Mandatory Reading Order

For any clawd-media-track task, read in this order:

1. references/00-bootstrap-init.md (init gate for bootstrap Step 1 and Step 2)
2. references/01-environment-contract.md (required config contract after bootstrap)
3. references/02-global-constraints.md (hard safety rules + execution protocol)
4. references/03-methods-reference.md (allowed module methods only)

Then route by task type:

• Type 1 (one-time acquisition: movies / completed series): read references/05-type1-checklist.md
• Type 2 (tracking initialization: ongoing/incomplete): read references/06-type2-checklist.md
• Type 3 (scheduled monitoring / cron): read references/07-type3-checklist.md

Read additional references when needed:

• Error handling, retries, dedup, season split strategy: references/04-error-and-dedup-rules.md
• Directory structure and common mistakes: references/08-directory-and-mistakes.md

Non-Negotiable Rules (Always Enforced)

• MUST follow: Evidence → Derived Facts → Decision before every critical action
• MUST process protected collections with .each(); DO NOT slice/sample/top-N them
• MUST NOT use glue scripts, regex helpers, or ad-hoc string parsing to make decision logic
• MUST execute Type 3 Step 3b (missing-vs-existing coverage branch) without skipping
• MUST bind transfer URLs once and execute via bound variable(s); DO NOT re-extract between decision and transfer
• MUST verify side effects (transfer/delete/mark/create) with re-read checks
• MUST treat any skipped rule as task failure and report honestly

If any hard rule is violated, stop and report failure instead of improvising.

Execution Context

• Project directory: skill repo root
• Python runtime: ./.venv/bin/python
• Auth/config: constructors read environment-backed config; do not hardcode cookies, tokens, base URLs, or CIDs in the skill

File Map

• references/00-bootstrap-init.md
• references/01-environment-contract.md
• references/02-global-constraints.md
• references/03-methods-reference.md
• references/04-error-and-dedup-rules.md
• references/05-type1-checklist.md
• references/06-type2-checklist.md
• references/07-type3-checklist.md
• references/08-directory-and-mistakes.md

Migration Note

This refactor keeps original procedural content but routes detailed material into references for reliability and context efficiency.

You ask for a movie, show, or anime; an LLM agent scouts resources across your indexers, transfers the best match into your own 115 / Quark / 光鸭 drive, verifies what landed, and keeps tracking what's still missing.

Above: the read-only live demo — search → 获取 → the agent works through search, transfer, and verification.

Install

Desktop app (recommended — easiest)

1. Download and install
2. Open the app
3. Go to Settings — connect a drive, add an LLM endpoint
4. Search a title, hit 获取 — that's it

No Docker, no Postgres, no terminal. The app bundles its own SQLite data layer and runs the full engine inside an Electron shell.

Every release is machine-verified before it ships: CI installs the freshly-built Windows package on a clean runner, boots the real app, and requires an HTTP 200 health response, while the macOS build must pass native-ABI verification, signing, and notarization. Both platforms are published together in a single final step — if either gate fails, neither asset is uploaded, so a broken build can't reach the Releases page.

Docker (power users — always-on server)

cp .env.example .env   # optional — most config can be set in the UI
docker compose up -d

Then open http://<host>:3000 and configure in Settings. Full walkthrough: docs/deploy.md.

🇨🇳 Can't reach Docker Hub (mainland China)? See docs/deploy.md → registry mirror.

Which path?

Both paths share one codebase — all product logic is identical. The data layer (SQLite vs Postgres) is selected by the MEDIA_TRACK_SQLITE_PATH env var, not the process shell — desktop sets it automatically, Docker defaults to Postgres.

Features

Search → acquire — find a title, hit 获取, the agent takes over
Library wall — what you have, per drive, with missing / airing badges
Show detail — season coverage, gaps, tracking state
Realtime activity — a live queue + agent action ticker while it works
Notifications — per-acquisition + daily digest, multi-channel push
Settings — drives, quality, language, LLM (BYO-key), Prowlarr, PanSou

Multiple drives appear as a workspace switcher with per-brand icons:

What it is

Most "media automation" either searches well but doesn't know what you're actually missing, or moves files but never verifies what landed. Mediary Scout treats acquisition as a state problem, driven by an agent that acts from evidence, not vibes:

• Multi-drive, brand-extensible — five drives today (Quark, 115, 光鸭 GuangYaPan, 123, 天翼 Tianyi), each a first-class workspace (a tree model: one account, many drives). Adding a new drive brand is a contained plugin.
• Agent-driven selection — the agent reads real search results and picks by quality preference, Chinese-subtitle needs, and de-duplication, then verifies the transfer after it happens.
• Tracking & scheduled gap-fill — season-level state machine; a scheduled sweep comes back only for shows that still have missing episodes.
• Cloud-native — it transfers shares/magnets straight into your drive (秒传 / save), it does not download to a local disk.

Supported drives

Five Chinese cloud drives, each a first-class workspace — ordered by how many PanSou resources each can consume (115 and 123 are dual-path: own share links and magnets):

• Quark / 夸克 (quark) — share-link transfer (no magnet web API). The largest share pool on PanSou by far.
• 123网盘 (pan123) — dual-path like 115: share-link transfer (123pan.com/s/…) and magnets via its native offline-download API (resolve → submit → poll). A magnet is a magnet — whether it came from PanSou or a Prowlarr indexer. QR login (~90-day token) or paste a token. Free accounts can transfer (server-side copy costs no download quota). Setup guide
• 115 (pan115) — full support: 115 share links and magnets (built-in offline path, plus Prowlarr).
• GuangYaPan / 光鸭云盘 (guangya) — Xunlei-family drive; magnet / offline-download only (transfers magnet/ed2k/BT via its offline-task API — it does not transfer share links in v1). Token auth. Pairs well with Prowlarr. Setup guide
• Tianyi / 天翼云盘 (tianyi) — share-link transfer (cloud.189.cn/t/…); QR login or paste an SSON cookie. Smallest share pool on PanSou today (weak for movies, workable for shows/anime). Setup guide

Measured share volume per drive (2026-07 point-in-time sample: six popular titles across movie / drama / anime, one PanSou instance with curated channels — your channels will vary):

New brands plug into a storage-brand registry; the bulk of adding one is a drive client + a storage executor for that drive's transfer API.

Agent API (agent-first control)

Both the desktop app and the container expose a local HTTP API that lets any coding agent (Claude Code, Codex, opencode, …) operate Mediary Scout without opening the GUI — change settings, trigger acquisitions, check download progress.

Desktop: automatic — on first launch the app writes a discovery file to ~/.mediary/agent.json. Container: set MEDIA_TRACK_AGENT_TOKEN env var to opt in.

Install the agent skill:

mkdir -p ~/.claude/skills/ && cp -r skills/mediary-scout ~/.claude/skills/      # or ~/.codex/skills/, ~/.config/opencode/skills/

Then tell your agent things like "帮我找进击的巨人第二季" or "蜘蛛侠下好了吗" or "把画质改成 high". See skills/mediary-scout/SKILL.md for the full trigger list.

All require Authorization: Bearer <token>. No token configured → 404 (invisible). Wrong/missing token → 401.

Architecture

A web app enqueues work; a long-running worker drives a sandboxed agent that has narrow, audited powers while the deterministic workflow owns every side effect and re-reads real state to verify.

flowchart LR
    UI["Web UI<br/>(Next.js)"] -->|enqueue| Q["Postgres / SQLite<br/>+ run state"]
    Q --> W["In-process worker"]
    W --> AG["V2 sandbox agent"]
    AG -->|search| SRC["PanSou / Prowlarr"]
    AG -->|transfer| DR["Quark / 115 / 光鸭 / 123 / 天翼 drive"]
    AG -->|read back| DR
    AG -->|verify + mark| Q
    Q -->|realtime| UI
    CRON["Scheduled sweep"] -->|gaps only| Q

• State lives in Postgres (container) or SQLite (desktop) — runs are resumable across restarts (the agent rebuilds from real drive + DB state, not cached chat history).
• Metadata comes from TMDB (with a built-in proxy fallback so it works out of the box); resource search from PanSou and optionally Prowlarr (torrent/magnet indexers).

Demo

🔭 Try it live: demo.mediaryscout.app

A public, read-only demo — mock drives, real TMDB search across the whole catalog, and a