@danhachuel/thunderbolt 0.2.18 → 0.2.20

package/integrations/platforms.py

@@ -3,9 +3,11 @@ from __future__ import annotations
 import json
 import os
 import re
+import xml.etree.ElementTree as ET
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
+from urllib.parse import urlparse
 
 import requests
 
@@ -106,6 +108,72 @@ def _thumbnail_from_metadata(metadata: dict[str, Any]) -> str:
     return ""
 
 
+def _meta_content(document: str, *names: str) -> str:
+    for name in names:
+        pattern = rf'<meta[^>]+(?:name|property)=["\']{re.escape(name)}["\'][^>]+content=["\']([^"\']*)["\']'
+        match = re.search(pattern, document, flags=re.IGNORECASE)
+        if match:
+            return match.group(1).strip()
+        reverse_pattern = rf'<meta[^>]+content=["\']([^"\']*)["\'][^>]+(?:name|property)=["\']{re.escape(name)}["\']'
+        match = re.search(reverse_pattern, document, flags=re.IGNORECASE)
+        if match:
+            return match.group(1).strip()
+    return ""
+
+
+def _public_page_candidates(source: str) -> list[str]:
+    source = source.strip()
+    if source.startswith(("http://", "https://")):
+        parsed = urlparse(source)
+        base = f"https://{parsed.netloc}{parsed.path}".rstrip("/")
+        if parsed.netloc.lower().endswith("youtube.com"):
+            base = base.replace("/about", "").replace("/videos", "")
+    elif source.startswith("UC"):
+        base = f"https://www.youtube.com/channel/{source}"
+    else:
+        handle = source if source.startswith("@") else f"@{source}"
+        base = f"https://www.youtube.com/{handle}"
+    return list(dict.fromkeys([
+        f"{base}/about?hl=pt-BR&gl=BR",
+        f"{base}?hl=pt-BR&gl=BR",
+        f"{base}/videos?hl=pt-BR&gl=BR",
+    ]))
+
+
+def _channel_id_from_document(document: str, canonical_url: str = "") -> str:
+    patterns = [
+        r'"externalId"\s*:\s*"(UC[A-Za-z0-9_-]+)"',
+        r'"channelId"\s*:\s*"(UC[A-Za-z0-9_-]+)"',
+        r"/channel/(UC[A-Za-z0-9_-]+)",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, document)
+        if match:
+            return match.group(1)
+    match = re.search(r"/channel/(UC[A-Za-z0-9_-]+)", canonical_url)
+    return match.group(1) if match else ""
+
+
+def _public_feed_data(channel_id: str, headers: dict[str, str]) -> dict[str, Any]:
+    if not channel_id:
+        return {}
+    try:
+        response = requests.get(
+            f"https://www.youtube.com/feeds/videos.xml?channel_id={channel_id}",
+            headers=headers,
+            timeout=12,
+        )
+        response.raise_for_status()
+        root = ET.fromstring(response.text)
+        namespace = {"yt": "http://www.youtube.com/xml/schemas/2015", "atom": "http://www.w3.org/2005/Atom"}
+        title = root.findtext("atom:title", default="", namespaces=namespace).strip()
+        feed_id = root.findtext("yt:channelId", default=channel_id, namespaces=namespace).strip()
+        entries = root.findall("atom:entry", namespace)
+        return {"name": title, "youtube_id": feed_id, "video_count": len(entries) if entries else None}
+    except (requests.RequestException, ET.ParseError, ValueError):
+        return {}
+
+
 @dataclass
 class IntegrationResult:
     ok: bool
@@ -125,70 +193,72 @@ class YouTubeAdapter:
         return match.group(1) if match else value
 
     def fetch_channel_public(self, value: str) -> IntegrationResult:
-        """Fetch public channel metadata from YouTube HTML without an API key."""
+        """Fetch public channel metadata without requiring a YouTube Data API key."""
         source = (value or "").strip()
         if not source:
             return IntegrationResult(False, "Introduza o nome, handle, URL ou ID do canal.", {})
-        try:
-            if source.startswith("http://") or source.startswith("https://"):
-                page_url = source.rstrip("/")
-            elif source.startswith("UC"):
-                page_url = f"https://www.youtube.com/channel/{source}"
-            else:
-                handle = source if source.startswith("@") else f"@{source}"
-                page_url = f"https://www.youtube.com/{handle}"
-            if not page_url.endswith("/about"):
-                page_url = f"{page_url}/about"
-            response = requests.get(
-                page_url,
-                headers={
-                    "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/124 Safari/537.36",
-                    "Accept-Language": "pt-BR,pt;q=0.9,en;q=0.8",
-                },
-                timeout=20,
-            )
-            response.raise_for_status()
-            document = response.text
-            initial_data = _extract_json_assignment(document, "ytInitialData")
-            metadata = _find_first_key(initial_data or {}, "channelMetadataRenderer") or {}
-            header = _find_first_key(initial_data or {}, "pageHeaderViewModel") or {}
-            if not metadata and not header:
-                return IntegrationResult(False, "O YouTube não disponibilizou dados públicos para este canal. Confirme o link ou tente a aba Cadastro manual.", {"url": page_url})
+        headers = {
+            "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/124 Safari/537.36",
+            "Accept-Language": "pt-BR,pt;q=0.9,en;q=0.8",
+            "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        }
+        last_url = source
+        last_error = ""
+        for page_url in _public_page_candidates(source):
+            last_url = page_url
+            try:
+                response = requests.get(page_url, headers=headers, timeout=20)
+                response.raise_for_status()
+            except requests.RequestException as exc:
+                last_error = str(exc)
+                continue
+            document = response.text or ""
+            initial_data = _extract_json_assignment(document, "ytInitialData") or {}
+            metadata = _find_first_key(initial_data, "channelMetadataRenderer") or {}
+            header = _find_first_key(initial_data, "pageHeaderViewModel") or {}
+            canonical_url = _meta_content(document, "og:url", "twitter:url") or page_url.split("?", 1)[0].rstrip("/")
             owner_urls = metadata.get("ownerUrls", []) if isinstance(metadata, dict) else []
-            canonical_url = owner_urls[0] if owner_urls else page_url.removesuffix("/about")
-            canonical_url = canonical_url.replace("http://", "https://")
-            handle_match = re.search(r"/@([^/?]+)", canonical_url)
-            handle = f"@{handle_match.group(1)}" if handle_match else ""
+            if owner_urls:
+                canonical_url = str(owner_urls[0])
+            canonical_url = canonical_url.replace("http://", "https://").removesuffix("/about")
+            youtube_id = str(metadata.get("externalId", "")) if isinstance(metadata, dict) else ""
+            if not youtube_id:
+                youtube_id = _channel_id_from_document(document, canonical_url)
+            feed = _public_feed_data(youtube_id, headers)
             title = _text_from_node(metadata.get("title")) if isinstance(metadata, dict) else ""
             if not title and isinstance(header, dict):
                 title = _text_from_node(header.get("title"))
                 if not title:
                     title = _text_from_node(_find_first_key(header, "dynamicTextViewModel"))
+            if not title:
+                title = _meta_content(document, "og:title", "twitter:title") or feed.get("name", "")
             description = _text_from_node(metadata.get("description")) if isinstance(metadata, dict) else ""
-            youtube_id = str(metadata.get("externalId", "")) if isinstance(metadata, dict) else ""
-            if not youtube_id:
-                id_match = re.search(r"/channel/(UC[A-Za-z0-9_-]+)", canonical_url)
-                youtube_id = id_match.group(1) if id_match else ""
-            subscriber_value = _find_first_key(initial_data or {}, "subscriberCountText")
-            video_value = _find_first_key(initial_data or {}, "videoCountText")
+            description = description or _meta_content(document, "description", "og:description")
+            thumbnail_url = _thumbnail_from_metadata(metadata) or _meta_content(document, "og:image", "twitter:image")
+            handle_match = re.search(r"/@([^/?]+)", canonical_url)
+            handle = f"@{handle_match.group(1)}" if handle_match else ""
+            if not handle:
+                handle_match = re.search(r"/@([^/?]+)", document)
+                handle = f"@{handle_match.group(1)}" if handle_match else ""
+            subscriber_value = _find_first_key(initial_data, "subscriberCountText")
+            video_value = _find_first_key(initial_data, "videoCountText")
             data = {
-                "youtube_id": youtube_id,
+                "youtube_id": youtube_id or feed.get("youtube_id", ""),
                 "name": title,
                 "handle": handle,
                 "url": canonical_url,
                 "description": description,
-                "thumbnail_url": _thumbnail_from_metadata(metadata),
+                "thumbnail_url": thumbnail_url,
                 "subscriber_count": _parse_public_count(subscriber_value),
-                "video_count": _parse_public_count(video_value),
+                "video_count": _parse_public_count(video_value) or feed.get("video_count"),
                 "view_count": None,
                 "metrics_source": "youtube_public_page",
                 "public_lookup": True,
             }
-            return IntegrationResult(True, "Canal encontrado publicamente no YouTube, sem API Key. Reveja os dados antes de guardar.", data)
-        except requests.RequestException as exc:
-            return IntegrationResult(False, f"Não foi possível consultar a página pública do YouTube: {exc}", {"url": source})
-        except (json.JSONDecodeError, TypeError, ValueError) as exc:
-            return IntegrationResult(False, f"A página pública do YouTube mudou ou não pôde ser interpretada: {exc}", {"url": source})
+            if data["name"] or data["youtube_id"] or data["thumbnail_url"]:
+                return IntegrationResult(True, "Canal encontrado publicamente no YouTube, sem API Key. Reveja os dados antes de guardar.", data)
+            last_error = "A página respondeu sem metadados reconhecíveis."
+        return IntegrationResult(False, f"Não foi possível obter dados públicos do YouTube sem API Key. Confirme o URL/handle ou use Cadastro manual. {last_error}".strip(), {"url": last_url, "public_lookup": True})
 
     def fetch_channel(self, value: str) -> IntegrationResult:
         ref = self.extract_channel_ref(value)

package/integrations/youtube_direct_upload.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import secrets
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+import requests
+
+
+CHUNK_GRANULARITY = 262144
+SUPPORTED_EXTENSIONS = {".mp4", ".mov", ".webm", ".avi", ".mpeg", ".mpg", ".flv", ".wmv", ".3gpp"}
+COOKIE_KEYS = ("SID", "SSID", "HSID", "APISID", "SAPISID")
+
+
+@dataclass
+class DirectUploadResult:
+    ok: bool
+    message: str
+    data: dict[str, Any]
+
+
+def _cookie_settings(settings: dict[str, Any]) -> dict[str, str]:
+    return {key: str(settings.get(f"direct_cookie_{key.lower()}", "") or "").strip() for key in COOKIE_KEYS}
+
+
+def _cookie_header(cookies: dict[str, str]) -> str:
+    return ";".join(["CONSENT=YES+cb"] + [f"{key}={value}" for key, value in cookies.items() if value])
+
+
+def _sapishash(sapisid: str, origin: str = "https://studio.youtube.com") -> str:
+    timestamp = int(time.time())
+    digest = hashlib.sha1(f"{timestamp} {sapisid} {origin}".encode("utf-8")).hexdigest()
+    return f"{timestamp}_{digest}"
+
+
+def _innertube_id() -> str:
+    return f"innertube_studio:{secrets.token_hex(18)}:0"
+
+
+def _header(response: requests.Response, name: str) -> str:
+    wanted = name.lower()
+    for key, value in response.headers.items():
+        if key.lower() == wanted:
+            return str(value)
+    return ""
+
+
+def validate_direct_upload(video_path: str | Path, channel: dict[str, Any], settings: dict[str, Any]) -> str | None:
+    path = Path(video_path)
+    if not path.exists() or not path.is_file():
+        return "Ficheiro de vídeo não encontrado."
+    if path.suffix.lower() not in SUPPORTED_EXTENSIONS:
+        return "Formato de vídeo não suportado pelo upload directo."
+    if path.stat().st_size <= 0:
+        return "O ficheiro de vídeo está vazio."
+    missing_cookies = [key for key, value in _cookie_settings(settings).items() if not value]
+    if missing_cookies:
+        return f"Faltam cookies de sessão para upload directo: {', '.join(missing_cookies)}."
+    if not str(settings.get("direct_session_info", "") or "").strip():
+        return "Configure o token sessionInfo do upload directo."
+    if not str(settings.get("direct_innertube_api_key", "") or "").strip():
+        return "Configure o INNERTUBE_API_KEY do upload directo."
+    if not str(channel.get("delegated_session_id", "") or "").strip():
+        return "Este canal não tem DELEGATED_SESSION_ID configurado."
+    return None
+
+
+class YouTubeDirectUploader:
+    def __init__(self, settings: dict[str, Any], channel: dict[str, Any], *, session: requests.Session | None = None):
+        self.settings = settings
+        self.channel = channel
+        self.session = session or requests.Session()
+        self.cookies = _cookie_settings(settings)
+        self.cookie_header = _cookie_header(self.cookies)
+        self.user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/124 Safari/537.36"
+        self.inner_tube = _innertube_id()
+        self.google_upload: dict[str, str] = {}
+        self.video_id = ""
+
+    def _base_headers(self) -> dict[str, str]:
+        return {
+            "User-Agent": self.user_agent,
+            "Origin": "https://studio.youtube.com",
+            "Referer": "https://studio.youtube.com/",
+            "Cookie": self.cookie_header,
+        }
+
+    def describe_file(self, path: Path) -> None:
+        headers = {
+            **self._base_headers(),
+            "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+            "X-Goog-Upload-File-Name": path.name,
+            "X-Goog-Upload-Header-Content-Length": str(path.stat().st_size),
+            "X-Goog-Upload-Command": "start",
+            "X-Goog-Upload-Protocol": "resumable",
+        }
+        response = self.session.post("https://upload.youtube.com/upload/studio?authuser=0", headers=headers, data={"frontendUploadId": self.inner_tube}, timeout=60)
+        response.raise_for_status()
+        self.google_upload = {
+            "resource_id": _header(response, "x-goog-upload-header-scotty-resource-id"),
+            "upload_url": _header(response, "x-goog-upload-url"),
+            "upload_id": _header(response, "x-guploader-uploadid"),
+        }
+        if not self.google_upload["upload_url"] or not self.google_upload["resource_id"]:
+            raise RuntimeError("O YouTube não devolveu uma sessão de upload directo válida.")
+
+    def create_video(self, title: str, description: str, visibility: str) -> None:
+        payload = {
+            "resourceId": {"scottyResourceId": {"id": self.google_upload["resource_id"]}},
+            "frontendUploadId": self.inner_tube,
+            "initialMetadata": {
+                "title": {"newTitle": title},
+                "description": {"newDescription": description},
+                "privacy": {"newPrivacy": visibility},
+                "draftState": {"isDraft": False},
+                "targetedAudience": {"operation": "MDE_TARGETED_AUDIENCE_UPDATE_OPERATION_SET", "newTargetedAudience": "MDE_TARGETED_AUDIENCE_TYPE_ALL"},
+            },
+            "botguardClientResponse": f"${hashlib.sha1(os.urandom(16)).hexdigest()}",
+            "context": {
+                "client": {"clientName": 62, "clientVersion": "1.20210806.02.00", "hl": "pt-BR", "gl": "BR", "experimentsToken": "", "utcOffsetMinutes": 0},
+                "request": {"sessionInfo": {"token": str(self.settings.get("direct_session_info", ""))}},
+                "user": {"onBehalfOfUser": str(self.channel.get("delegated_session_id", ""))},
+            },
+        }
+        api_key = str(self.settings.get("direct_innertube_api_key", "")).strip()
+        endpoint = f"https://studio.youtube.com/youtubei/v1/upload/createvideo?alt=json&key={quote(api_key)}"
+        headers = {**self._base_headers(), "Content-Type": "application/json", "X-Youtube-Client-Name": "62", "X-Youtube-Client-Version": "1.20210806.02.00", "X-Goog-PageId": str(self.channel.get("delegated_session_id", "")), "Authorization": f"SAPISIDHASH {_sapishash(self.cookies['SAPISID'])}"}
+        response = self.session.post(endpoint, headers=headers, data=json.dumps(payload), timeout=60)
+        response.raise_for_status()
+        body = response.json() if response.content else {}
+        self.video_id = str(body.get("videoId") or body.get("video_id") or "")
+        if not self.video_id:
+            raise RuntimeError("O YouTube não devolveu o videoId após createvideo.")
+
+    def upload_chunks(self, path: Path, chunk_size: int = CHUNK_GRANULARITY) -> None:
+        chunk_size = max(CHUNK_GRANULARITY, int(chunk_size))
+        chunk_size -= chunk_size % CHUNK_GRANULARITY
+        if chunk_size == 0:
+            chunk_size = CHUNK_GRANULARITY
+        offset = 0
+        with path.open("rb") as handle:
+            while True:
+                chunk = handle.read(chunk_size)
+                if not chunk:
+                    break
+                last = offset + len(chunk) >= path.stat().st_size
+                headers = {**self._base_headers(), "Content-Type": "application/x-www-form-urlencoded;charset=utf-8", "X-Goog-Upload-Command": "upload, finalize" if last else "upload", "X-Goog-Upload-Offset": str(offset), "X-Goog-Upload-File-Name": quote(path.name)}
+                response = self.session.post(self.google_upload["upload_url"], headers=headers, data=chunk, timeout=180)
+                response.raise_for_status()
+                offset += len(chunk)
+
+    def upload(self, video_path: str | Path, *, title: str, description: str = "", visibility: str = "private", chunk_size: int = CHUNK_GRANULARITY) -> DirectUploadResult:
+        path = Path(video_path)
+        validation_error = validate_direct_upload(path, self.channel, self.settings)
+        if validation_error:
+            return DirectUploadResult(False, validation_error, {"mechanism": "youtube-frontend-direct"})
+        try:
+            self.describe_file(path)
+            self.create_video(title, description, visibility)
+            self.upload_chunks(path, chunk_size)
+            return DirectUploadResult(True, f"Upload directo concluído: {self.video_id}", {"mechanism": "youtube-frontend-direct", "video_id": self.video_id, "page_id": self.channel.get("delegated_session_id", "")})
+        except (requests.RequestException, OSError, ValueError, RuntimeError) as exc:
+            return DirectUploadResult(False, f"Upload directo falhou: {exc}", {"mechanism": "youtube-frontend-direct", "video_id": self.video_id})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "main": "scripts/cli.mjs",
   "type": "module",
@@ -11,9 +11,11 @@
     "app/main.py",
     "hermes_ui/*.py",
     "integrations/*.py",
+    "integrations/data/*.json",
     "scripts/*.mjs",
     "storage/blueprints/**/*.json",
     "seed/blueprints/**/*.json",
+    "seed/skills/*.md",
     "README.md",
     "MANUAL-INSTALACAO.md",
     "requirements.txt",

package/requirements.txt

@@ -6,3 +6,4 @@ toml>=0.10,<1
 google-auth>=2.29,<3
 google-auth-oauthlib>=1.2,<2
 google-api-python-client>=2.120,<3
+edge-tts>=7.0,<8

package/scripts/cli.mjs

@@ -76,6 +76,9 @@ function ensureRuntimeStorage() {
     join(storageRoot, "metadata_cleaner"),
     join(storageRoot, "metadata_cleaner", "originals"),
     join(storageRoot, "metadata_cleaner", "outputs"),
+    join(storageRoot, "skills"),
+    join(storageRoot, "music"),
+    join(storageRoot, "voice_previews"),
   ];
   for (const directory of directories) mkdirSync(directory, { recursive: true });
   const seedRoot = resolve(root, "seed", "blueprints");
@@ -95,7 +98,7 @@ function check() {
     console.error(`Python não encontrado. Execute: npx.cmd --yes @danhachuel/thunderbolt install`);
     process.exit(1);
   }
-  const requiredModules = ["streamlit", "requests", "pandas", "toml", "imageio_ffmpeg"];
+  const requiredModules = ["streamlit", "requests", "pandas", "toml", "imageio_ffmpeg", "edge_tts"];
   const missing = requiredModules.filter((moduleName) => !moduleAvailable(moduleName));
   const ffmpeg = moduleAvailable("imageio_ffmpeg");
   const mptPath = configuredMoneyPrinterPath();

package/scripts/install.mjs

@@ -107,6 +107,9 @@ function ensureDirs() {
     join(storageRoot, "metadata_cleaner", "originals"),
     join(storageRoot, "metadata_cleaner", "outputs"),
     join(storageRoot, "artifacts"),
+    join(storageRoot, "skills"),
+    join(storageRoot, "music"),
+    join(storageRoot, "voice_previews"),
   ];
   for (const directory of directories) mkdirSync(directory, { recursive: true });
   copySeedBlueprints(storageRoot);
@@ -287,7 +290,7 @@ function writeSettings(moneyprinterPath) {
 
 function installThunderboltDependencies(python) {
   if (!existsSync(pythonBin)) run(python.command, [...python.args, "-m", "venv", venvPath]);
-  installRequirementIfNeeded(join(root, "requirements.txt"), "thunderbolt_requirements_sha256", ["streamlit", "requests", "pandas", "toml", "imageio_ffmpeg", "google.auth", "google_auth_oauthlib", "googleapiclient"], "Thunderbolt");
+  installRequirementIfNeeded(join(root, "requirements.txt"), "thunderbolt_requirements_sha256", ["streamlit", "requests", "pandas", "toml", "imageio_ffmpeg", "edge_tts", "google.auth", "google_auth_oauthlib", "googleapiclient"], "Thunderbolt");
 }
 
 function installMoneyPrinterDependencies(moneyprinterPath) {

package/seed/skills/moneyprinterturbo-video.md

@@ -0,0 +1,132 @@
+---
+name: moneyprinterturbo-video
+description: Use this skill whenever the user wants to create a finished video from a topic, title, idea, prompt, or script with MoneyPrinterTurbo. This includes short-form, voice-over, educational, marketing, social-media, and stock-footage videos. Also use it when the user mentions MoneyPrinterTurbo, provides this Skill URL, asks an AI agent to install or configure MoneyPrinterTurbo, needs missing API keys identified, wants a failed generation repaired, or wants a generated MP4 located and delivered. Use this skill when the expected outcome is a final video file, not setup instructions.
+compatibility: Requires an AI agent with terminal, network, filesystem, and long-running command support. Supports macOS and Windows and uses uv exclusively.
+metadata:
+  author: "harry0703@hotmail.com"
+  version: "1.3.2"
+  upstream: "https://github.com/harry0703/MoneyPrinterTurbo"
+---
+
+# MoneyPrinterTurbo Video Generation
+
+The user only needs to provide a video topic or script. Complete installation, configuration reuse, generation, waiting, and final MP4 delivery automatically. Do not stop after giving instructions or commands.
+
+## Required Behavior
+
+1. Ask the user only for required API credentials that are missing, rejected, or unusable. Combine all required credentials into one request.
+2. Do not ask for confirmation before installing, generating, waiting, using defaults, or returning the result.
+3. Do not create or repeatedly update a detailed plan for a standard generation request. Send one short progress update and execute.
+4. Run the helper as one foreground command with a timeout of at least 20 minutes.
+5. Never poll with `sleep`, `echo`, `ps`, repeated `ls`, or repeated `tail`. If the terminal returns a resumable session ID, continue waiting on that same session.
+6. Do not read the full log after success. Read only the short reported error or the relevant log tail after failure.
+7. Never print API keys, tokens, the full `config.toml`, or credential-bearing configuration fragments.
+
+## Defaults
+
+Unless the user requests otherwise, generate one Chinese `9:16` portrait video with Pexels footage, the default Chinese Edge TTS voice, subtitles, and background music. Install MoneyPrinterTurbo under the user's home directory.
+
+## Execution
+
+### 1. Locate the helper
+
+Resolve `SKILL_DIR` from this `SKILL.md` file. The helper is the adjacent `mpt_agent.py`. Set the terminal tool's working directory to `SKILL_DIR` and invoke the helper by its relative filename. Do not put the absolute helper path in the command, and do not run an extra `ls` or `dir` check.
+
+This is required on Windows because some agent terminal validators remove backslashes from absolute paths embedded in commands. Using `mpt_agent.py` with `workdir=SKILL_DIR` avoids that failure and works on both macOS and Windows.
+
+If the client loaded only the remote `SKILL.md`, download the helper from the official repository to a temporary directory, then use that temporary directory as the command working directory:
+
+```text
+https://raw.githubusercontent.com/harry0703/MoneyPrinterTurbo/main/docs/skill/mpt_agent.py
+```
+
+### 2. Run the helper
+
+Do not run a separate `uv --version` preflight. Run the helper directly. If the shell explicitly reports that uv is missing, install uv and retry the same helper command once.
+
+macOS uv installation:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Windows PowerShell uv installation:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Use this foreground command with `workdir=SKILL_DIR` and a timeout of at least 20 minutes:
+
+```bash
+uv run --no-project --python 3.11 python mpt_agent.py --subject "<video topic>"
+```
+
+On Windows, do not try absolute backslash paths, absolute forward-slash paths, or copies in the workspace before this relative command. If a terminal tool reports `referenced_script_path_missing`, verify that its working directory is exactly `SKILL_DIR` and retry the relative command once. Do not cycle through path variants.
+
+Do not use Docker, Conda, system pip, or a manually managed virtual environment.
+
+## Exit Handling
+
+### Exit code 0: deliver the result
+
+Successful output has this form:
+
+```text
+MPT_RESULT
+VIDEO_FILE=<absolute path>/final-1.mp4
+TASK_DIR=<absolute path>/storage/tasks/<task_id>
+LOG_FILE=<absolute path>/run-<task_id>.log
+RESULT_FILE=<absolute path>/latest-result.json
+```
+
+`mpt_agent.py` emits `VIDEO_FILE` only after confirming that the file exists and is non-empty. Do not run another `ls`, `stat`, or file validation command.
+
+If the terminal reports `exitCode=0` but truncates the output or returns a history-file reference without `MPT_RESULT`, do not infer failure and do not inspect old logs. Read this file once:
+
+```text
+~/MoneyPrinterTurbo/.agent-logs/moneyprinterturbo-video/latest-result.json
+```
+
+Treat `status=completed` as success. Return only the absolute video path and a concise description, for example:
+
+```text
+The video is ready.
+Topic: ...
+Video file: /absolute/path/to/final-1.mp4
+Summary: Chinese portrait video with voice-over, subtitles, and background music.
+```
+
+### Exit code 10: request credentials once
+
+`MPT_NEEDS_INPUT` includes only the required fields, recommended LLM providers and signup links, custom OpenAI-compatible requirements, and the Pexels signup link. Ask only for the listed values and do not request credentials already found in `config.toml`.
+
+After the user responds, rerun the same foreground command with only the required environment variables:
+
+```text
+MPT_LLM_PROVIDER
+MPT_LLM_API_KEY
+MPT_LLM_BASE_URL
+MPT_LLM_MODEL_NAME
+MPT_PEXELS_API_KEY
+```
+
+### Exit code 1: repair or report
+
+Use `MPT_ERROR` and `LOG_FILE` to repair a recoverable problem and retry once. Ask the user only if the repair requires a new API key. If the retry fails, report the failed stage, a short error, and the log path.
+
+A terminal-tool path validation error is not a video-generation failure because the helper did not start. Correct the working directory and retry the relative command once. Never ask the user to copy `mpt_agent.py`, run commands manually, or confirm whether the agent should continue.
+
+## Configuration and Background Fallback
+
+The helper may read the complete local `config.toml` to reuse existing settings, but it must never print its contents. It reuses a working LLM provider automatically and validates configured Pexels keys through the authenticated My Collections endpoint before generation.
+
+Use background mode only if the agent platform cannot wait for a foreground process. Wait for the platform's process-completion notification without polling, then read `latest-result.json` once.
+
+## Scope
+
+- Support macOS and Windows only.
+- Use uv and the MoneyPrinterTurbo CLI only.
+- Do not start Docker, WebUI, or API services.
+- Do not run multiple video jobs concurrently.
+- Pass additional video requirements after `--`. Run `cli.py --help` once only when an unfamiliar option must be verified.