@remixmate/cli 0.9.8 → 0.9.10

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.8",
-  "generatedAt": "2026-07-20T11:13:57.597Z",
+  "version": "0.9.10",
+  "generatedAt": "2026-07-26T14:43:29.935Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -245,7 +245,7 @@
       "tier": "tool",
       "category": "consuming",
       "title": "Web Page Capture",
-      "summary": "Drive a headless browser (Playwright Python) to capture any URL to local files: full-page / element / region screenshots, fixed-duration / condition-triggered / auto-scroll recordings, and storyboard videos (highlight / focus / zoom / scroll / virtual-cursor click / caption / title-card / arrow / numbered sequence / redact / code-line highlight). Two entry scripts: scripts/screenshot.py (stills) and scripts/record.py (webm video, storyboards, templates).",
+      "summary": "Drive a headless browser (Playwright Python) to capture any URL to a local STILL IMAGE (png/jpg): full-page / viewport / element / region screenshots, with device emulation, waiting, hide/mask/redact, and static annotations (highlight / arrow / caption / numbered sequence / redact). Images only — for video / recording / scroll-through / storyboard clips (webm) use the web_record tool instead.",
       "triggers": [
         "网页截图、网页截屏、整页截图、长截图、full page screenshot",
         "截某个元素 / 区域、局部截屏、focus 某个区域",
@@ -269,6 +269,34 @@
         "WEB_CAPTURE_ALLOW_PRIVATE_HOSTS",
         "PLAYWRIGHT_BROWSERS_PATH"
       ]
+    },
+    {
+      "id": "web-record",
+      "tier": "tool",
+      "category": "consuming",
+      "title": "Web Page Recording",
+      "summary": "Drive a headless browser (Playwright Python) to RECORD any URL to a video, then (by default) transcode to mp4, grab a cover frame, upload to VOD and return a playable CDN URL. Modes: fixed-duration recording, condition-triggered stop (element appears / disappears), auto-scroll from top to bottom, custom storyboards, and parameterized templates. Storyboard scenes: highlight / focus / zoom / scroll / virtual-cursor click / type / hover / caption / title-card / arrow / numbered sequence / redact / code-line highlight. For still images (png/jpg) use the web_capture tool instead. Use this tool whenever the user wants a video / recording / screencast of a web page: record a page, scroll-through video, page-from-top-to-bottom clip, demo of clicks/typing/hover, storyboard / multi-scene intro video, or a template-based clip.",
+      "triggers": [
+        "录屏、网页录制、录制视频、录一段操作、生成 webm、screencast",
+        "滚动录屏、页面从头划到尾的视频",
+        "多场景视频、分镜视频、storyboard、按时间线编排",
+        "演示点击 / 输入 / 悬停（虚拟鼠标 + 涟漪 / 打字机 / 触发 tooltip）",
+        "模板视频一行出片、按顺序编号高亮多个区域并录制"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "../web-capture/scripts/record.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "WEB_CAPTURE_BROWSER",
+        "WEB_CAPTURE_OUTPUT_BASE",
+        "WEB_CAPTURE_NO_SANDBOX",
+        "WEB_CAPTURE_ALLOW_PRIVATE_HOSTS",
+        "PLAYWRIGHT_BROWSERS_PATH",
+        "REMOTION_RENDER_API_URL",
+        "PRIV_TOKEN"
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "description": "AI media generation skills for Claude Code / Codex — 11 skills covering image, video, voice, digital human, web capture, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",

package/skills/render-video/scripts/_vod_polling.py

@@ -40,7 +40,10 @@ def poll_vod_playback_url(
       - 看到阿里云 OSS 直链时记为 fallback，继续等 CDN
       - 超时仍未拿到 CDN 时退回到 OSS 原始地址
     """
-    api_base = os.environ.get("MM_BACKEND_API_URL", "https://api.remixmate.com/api").rstrip("/")
+    api_base = os.environ.get(
+        "MM_API_BASE_URL",
+        os.environ.get("MM_BACKEND_API_URL", "https://api.remixmate.com/api"),
+    ).rstrip("/")
     url = f"{api_base}/file/get"
     headers = {
         "Content-Type": "application/json",

package/skills/template-registry/scripts/render_job_client.py

@@ -6,7 +6,9 @@ render_job_client.py — ab-api renderJob 接口 Python 客户端
 gen_jianying_draft.py 使用。
 
 认证方式: X-Priv-Token header（与其他 skill 脚本一致）
-接口地址: 由环境变量 MM_BACKEND_API_URL 控制（默认 https://api.remixmate.com/api）
+接口地址: 优先读 MM_API_BASE_URL（executor 显式转发、全链路标准名），
+         回退 MM_BACKEND_API_URL，再回退默认 https://api.remixmate.com/api。
+         两个变量语义相同，保留回退是为兼容只配了其中一个的部署环境。
 """
 
 import json
@@ -17,7 +19,10 @@ import urllib.request
 
 
 def _api_base() -> str:
-    return os.environ.get("MM_BACKEND_API_URL", "https://api.remixmate.com/api").rstrip("/")
+    return os.environ.get(
+        "MM_API_BASE_URL",
+        os.environ.get("MM_BACKEND_API_URL", "https://api.remixmate.com/api"),
+    ).rstrip("/")
 
 
 def _make_headers(priv_token: str) -> dict:

package/skills/web-capture/scripts/_media_screenshot/recording.py

@@ -11,6 +11,7 @@ from .browser import (
     apply_pre_action_waits,
     build_context_options,
     launch_with_browser_install,
+    wait_until_settled,
 )
 
 
@@ -57,8 +58,12 @@ def _wait_for_stop_condition(page, cfg: dict) -> str:
     return "duration" if duration else "cap"
 
 
-def do_record(cfg: dict) -> Path:
-    """Plain recording — returns the absolute output path."""
+def do_record(cfg: dict) -> tuple[Path, int, int]:
+    """Plain recording — returns (output_path, start_ms, end_ms).
+
+    start_ms/end_ms 是相对视频起点（context 创建）的内容窗口：start_ms=页面加载就绪时刻，
+    end_ms=内容动作结束时刻。调用方据此端锚裁掉开头加载段（skill 侧或委托 ab-render）。
+    """
     ensure_runtime()
     from playwright.sync_api import sync_playwright
 
@@ -69,19 +74,29 @@ def do_record(cfg: dict) -> Path:
     with sync_playwright() as p:
         browser = launch_with_browser_install(p, cfg.get("browser"))
         try:
+            # t0 ≈ 视频开始录制的时刻（context 创建即开录）；用于测量加载头/内容窗口，
+            # 供 trim_video 端锚裁剪。
+            t0 = time.time()
             context = browser.new_context(**build_context_options(p, cfg, out_dir))
             if cfg.get("timeout"):
                 context.set_default_timeout(cfg["timeout"])
             page = context.new_page()
             video_path: str | None = None
+            start_ms = 0
+            end_ms = 0
             try:
                 page.goto(cfg["url"], wait_until="domcontentloaded")
                 apply_pre_action_waits(page, cfg)
+                # 无条件等页面真正加载完成（networkidle + settled 检测 + settleMs）再开录内容——
+                # 对所有 URL 生效。加载/白屏段仍会被录进原始视频，随后由 trim_video 端锚裁掉。
+                wait_until_settled(page, cfg)
+                start_ms = int((time.time() - t0) * 1000)
                 if cfg.get("scrollThrough"):
                     _scroll_through(page, cfg)
                     reason = "scrollThrough"
                 else:
                     reason = _wait_for_stop_condition(page, cfg)
+                end_ms = int((time.time() - t0) * 1000)
                 print(f"[runner] stop reason: {reason}", file=sys.stderr)
                 video = page.video
                 context.close()
@@ -97,4 +112,6 @@ def do_record(cfg: dict) -> Path:
     src = Path(video_path)
     if src.resolve() != output:
         src.replace(output)
-    return output
+    # 不在此处裁剪：加载头由调用方在收尾/转码那一步端锚裁掉（见 record.py），
+    # 避免 skill 侧依赖 ffmpeg 并省去一次重编码。
+    return output, start_ms, end_ms

package/skills/web-capture/scripts/_media_screenshot/screenshot.py

@@ -96,6 +96,7 @@ def do_screenshot(cfg: dict) -> Path:
     """Take a screenshot per cfg. Returns the absolute output path."""
     ensure_runtime()
     from playwright.sync_api import sync_playwright
+    from playwright.sync_api import TimeoutError as PlaywrightTimeoutError
 
     output = Path(cfg["output"]).resolve()
     output.parent.mkdir(parents=True, exist_ok=True)
@@ -125,6 +126,23 @@ def do_screenshot(cfg: dict) -> Path:
 
                 if cfg.get("selector"):
                     locator = page.locator(cfg["selector"]).first
+                    # 先用较短超时确认元素确实存在。否则选择器不匹配时，
+                    # scroll_into_view_if_needed() 会干等全局超时（默认 30s）才抛出
+                    # 一大段难懂的 Playwright traceback、以 exit 1 崩溃。这里快速失败，
+                    # 返回一条模型可读、可据以换选择器的错误信息。
+                    probe_timeout = cfg.get("selectorTimeout")
+                    if probe_timeout is None:
+                        # 页面 domcontentloaded 已触发，元素在则几乎立即命中；
+                        # 不在则无需等满 30s。取全局 timeout 与 8s 的较小值。
+                        probe_timeout = min(cfg.get("timeout") or 8000, 8000)
+                    try:
+                        locator.wait_for(state="attached", timeout=probe_timeout)
+                    except PlaywrightTimeoutError:
+                        raise SystemExit(
+                            f'selector "{cfg["selector"]}" 在页面上未找到'
+                            f'（{cfg["url"]}）。该元素可能不存在或页面结构已变化。'
+                            f'请换用其它选择器，或去掉 --selector 改用整页/区域截屏。'
+                        )
                     if cfg.get("scrollIntoView", True):
                         locator.scroll_into_view_if_needed()
                     if isinstance(cfg.get("clip"), (list, tuple)) and len(cfg["clip"]) == 4:

package/skills/web-capture/scripts/_media_upload.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""录屏产物收尾客户端 —— 把本地视频推给 ab-render 的 /finalize 端点。
+
+ab-render 侧（apps/ab-render/server/finalize.ts）负责：webm→mp4 转码 + 抽首帧封面
++ 上传阿里云 VOD + 轮询拿到 CDN 播放地址。本模块只做 HTTP 层：POST 原始字节 +
+轮询 /finalizeStatus。纯标准库，不依赖 ffmpeg / OSS / 阿里云 SDK。
+
+与 render-video 的 remote_renderer_client 一样直连 ab-render：
+  Base URL 优先级：显式传入 > 环境变量 REMOTION_RENDER_API_URL > 默认生产地址。
+
+认证头（复用 X-Priv-Token 规范）：
+  X-Priv-Token: <PRIV_TOKEN>
+  x-invoke-skill:  web-record
+  x-invoke-agent:  <AGENT_NAME>   # optional
+  x-conversation-id: <CONVERSATION_ID>  # optional
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Callable, Optional
+
+DEFAULT_API_BASE_URL = "https://api-render.remixmate.com"
+SKILL_NAME = "web-record"
+
+TERMINAL_SUCCESS = {"succeeded", "succeed", "completed"}
+TERMINAL_FAILURE = {"failed", "cancelled"}
+
+
+class FinalizeError(RuntimeError):
+    """上传/收尾失败，交由调用方决定是否降级为「仅本地文件」。"""
+
+
+def _base_url(explicit: Optional[str]) -> str:
+    base = (explicit or os.environ.get("REMOTION_RENDER_API_URL") or DEFAULT_API_BASE_URL).strip()
+    return base.rstrip("/")
+
+
+def _headers(private_token: str, *, content_type: Optional[str], conversation_id: Optional[str]) -> dict:
+    if not private_token:
+        raise FinalizeError("PrivToken 未设置（PRIV_TOKEN）")
+    h = {"X-Priv-Token": private_token, "x-invoke-skill": SKILL_NAME}
+    if content_type:
+        h["Content-Type"] = content_type
+    agent = os.environ.get("AGENT_NAME", "")
+    if agent:
+        h["x-invoke-agent"] = agent
+    if conversation_id:
+        h["x-conversation-id"] = conversation_id
+    return h
+
+
+def _submit(
+    local_path: str,
+    *,
+    private_token: str,
+    base_url: str,
+    transcode: bool,
+    cover: bool,
+    cover_at_sec: float,
+    title: Optional[str],
+    resolve_cdn: bool,
+    keep_tail_sec: Optional[float],
+    conversation_id: Optional[str],
+    request_timeout: float,
+) -> str:
+    """POST /finalize（原始字节 + query options）→ 返回 taskId。"""
+    ext = Path(local_path).suffix.lstrip(".").lower() or "webm"
+    query = {
+        "transcode": "1" if transcode else "0",
+        "cover": "1" if cover else "0",
+        "coverAtSec": str(cover_at_sec),
+        "resolveCdn": "1" if resolve_cdn else "0",
+        "ext": ext,
+    }
+    if title:
+        query["title"] = title
+    # 端锚裁剪窗口：让 ab-render 在转码同一 pass 里切掉开头加载段（skill 侧不再裁）。
+    if keep_tail_sec and keep_tail_sec > 0:
+        query["keepTailSec"] = f"{keep_tail_sec:.3f}"
+    url = f"{base_url}/finalize?{urllib.parse.urlencode(query)}"
+
+    with open(local_path, "rb") as f:
+        body = f.read()
+
+    req = urllib.request.Request(
+        url,
+        data=body,
+        headers=_headers(private_token, content_type="application/octet-stream", conversation_id=conversation_id),
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=request_timeout) as resp:
+            result = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = ""
+        try:
+            detail = exc.read().decode("utf-8")[:200]
+        except Exception:
+            pass
+        raise FinalizeError(f"/finalize HTTP {exc.code}: {detail}") from exc
+    except (urllib.error.URLError, OSError) as exc:
+        raise FinalizeError(f"/finalize 网络错误: {exc}") from exc
+
+    if result.get("code") != 0:
+        raise FinalizeError(f"/finalize code={result.get('code')}: {result.get('msg')}")
+    task_id = (result.get("data") or {}).get("taskId")
+    if not task_id:
+        raise FinalizeError(f"/finalize 未返回 taskId: {result}")
+    return str(task_id)
+
+
+def _poll(
+    task_id: str,
+    *,
+    private_token: str,
+    base_url: str,
+    timeout: float,
+    interval: float,
+    request_timeout: float,
+    on_progress: Optional[Callable[[dict], None]],
+) -> dict:
+    """POST /finalizeStatus 轮询直到 succeeded/failed/超时。成功返回 data dict。"""
+    start = time.monotonic()
+    consecutive_errors = 0
+    while True:
+        if time.monotonic() - start > timeout:
+            raise FinalizeError(
+                f"/finalizeStatus 轮询超时（{timeout:.0f}s, taskId={task_id}）；任务可能仍在后端运行"
+            )
+        try:
+            req = urllib.request.Request(
+                f"{base_url}/finalizeStatus",
+                data=json.dumps({"taskId": task_id}).encode("utf-8"),
+                headers=_headers(private_token, content_type="application/json", conversation_id=None),
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=request_timeout) as resp:
+                result = json.loads(resp.read().decode("utf-8"))
+            consecutive_errors = 0
+        except (urllib.error.URLError, OSError, ConnectionError) as exc:
+            consecutive_errors += 1
+            if consecutive_errors >= 5:
+                raise FinalizeError(f"/finalizeStatus 连续网络错误，放弃（taskId={task_id}）: {exc}") from exc
+            time.sleep(interval)
+            continue
+
+        if result.get("code") != 0:
+            raise FinalizeError(f"/finalizeStatus code={result.get('code')}: {result.get('msg')}")
+        data = result.get("data") or {}
+        if on_progress is not None:
+            try:
+                on_progress(data)
+            except Exception:
+                pass
+
+        status = str(data.get("status") or "").lower()
+        if status in TERMINAL_SUCCESS:
+            return data
+        if status in TERMINAL_FAILURE:
+            raise FinalizeError(f"收尾失败（{status}）: {data.get('error') or 'unknown'}")
+        time.sleep(interval)
+
+
+def finalize_recording(
+    local_path: str,
+    *,
+    private_token: str,
+    transcode: bool = True,
+    cover: bool = True,
+    cover_at_sec: float = 0.5,
+    title: Optional[str] = None,
+    resolve_cdn: bool = True,
+    keep_tail_sec: Optional[float] = None,
+    base_url: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    on_progress: Optional[Callable[[dict], None]] = None,
+    poll_timeout: float = 300.0,
+    poll_interval: float = 3.0,
+    request_timeout: float = 300.0,
+) -> dict:
+    """把本地视频推给 ab-render 收尾并轮询到终态。
+
+    keep_tail_sec：端锚裁剪窗口（保留视频尾部这么多秒，切掉开头加载段）；由 skill 测量的
+    内容窗口得出，None 表示不裁。裁剪与转码在 ab-render 合并成一次 pass。
+
+    返回 finalizeStatus 的 data dict，关键字段：
+      fileUrl（CDN 或 vod://）、vodRef、fileId、coverUrl、durationSec。
+    失败抛 FinalizeError，由调用方决定降级。
+    """
+    base = _base_url(base_url)
+    # 诊断：明确打出实际请求的 ab-render 地址 + 裁剪窗口，便于排查「发去哪/有没有裁」。
+    print(
+        f"[record] finalize target: {base}  keepTailSec={keep_tail_sec}",
+        file=sys.stderr,
+        flush=True,
+    )
+    task_id = _submit(
+        local_path,
+        private_token=private_token,
+        base_url=base,
+        transcode=transcode,
+        cover=cover,
+        cover_at_sec=cover_at_sec,
+        title=title,
+        resolve_cdn=resolve_cdn,
+        keep_tail_sec=keep_tail_sec,
+        conversation_id=conversation_id,
+        request_timeout=request_timeout,
+    )
+    return _poll(
+        task_id,
+        private_token=private_token,
+        base_url=base,
+        timeout=poll_timeout,
+        interval=poll_interval,
+        request_timeout=60.0,
+        on_progress=on_progress,
+    )
+
+
+__all__ = ["finalize_recording", "FinalizeError"]

package/skills/web-capture/scripts/record.py

@@ -23,6 +23,7 @@ from _media_screenshot import (  # noqa: E402
     template,
     trim,
 )
+from _media_upload import finalize_recording  # noqa: E402
 
 
 def main() -> None:
@@ -72,6 +73,21 @@ def main() -> None:
         help="列出可用模板并退出",
     )
 
+    # 收尾（transcode + 封面 + VOD 上传，默认开；委托 ab-render /finalize）
+    ap.add_argument(
+        "--no-upload", action="store_true",
+        help="录完不上传 VOD，只保留本地 webm（默认会转码+封面+上传并返回 CDN 地址）",
+    )
+    ap.add_argument("--vod-title", help="上传到 VOD 的标题（默认取输出文件名）")
+    ap.add_argument(
+        "--cover-at-sec", type=float, default=0.5,
+        help="封面抽帧时间点（秒，默认 0.5，避开首帧白屏）",
+    )
+    ap.add_argument(
+        "--keep-webm", action="store_true",
+        help="上传成功后保留本地 webm（默认删除，VOD 已持有）",
+    )
+
     cli_args.add_common_args(ap)
 
     args = ap.parse_args()
@@ -166,9 +182,8 @@ def main() -> None:
     try:
         if is_storyboard:
             out, start_ms, end_ms = do_storyboard(cfg)
-            trim.trim_video(out, start_ms, end_ms)
         else:
-            out = do_record(cfg)
+            out, start_ms, end_ms = do_record(cfg)
     finally:
         if is_temp and storage_path:
             try:
@@ -179,7 +194,88 @@ def main() -> None:
     if not out.exists():
         print(f"录屏未生成：{out}", file=sys.stderr)
         sys.exit(1)
-    print(str(out))
+
+    local_path = str(out)
+
+    # 端锚裁剪窗口：保留内容窗口 + 边距（与 _media_screenshot/trim.py 的常量一致）。
+    # 上传路径把它交给 ab-render 在转码同一 pass 里裁；--no-upload 单机路径才本地裁。
+    keep_tail_sec = None
+    if end_ms > start_ms:
+        keep_tail_sec = ((end_ms - start_ms) + 80 + 200) / 1000.0
+
+    # ── 收尾：转码 + 封面 + 上传 VOD（默认开）───────────────────────────────
+    # ffmpeg / OSS 全部在 ab-render 侧完成，本 skill 只推文件 + 轮询状态。
+    # 环境缺失（如裸跑 CLI 无 PRIV_TOKEN）或收尾失败 → 优雅降级为「仅本地文件」。
+    upload_enabled = not args.no_upload
+    priv_token = os.environ.get("PRIV_TOKEN", "")
+    if upload_enabled and not priv_token:
+        print("[record] 未设置 PRIV_TOKEN，跳过 VOD 上传，仅保留本地文件。", file=sys.stderr)
+        upload_enabled = False
+
+    if not upload_enabled:
+        # 单机 / 不上传：没有 ab-render 帮忙裁，就在本地尽力裁一刀（需系统 ffmpeg，
+        # 缺失则 trim.trim_video 保留原片并提示）。
+        trim.trim_video(out, start_ms, end_ms)
+        print(local_path)
+        return
+
+    def _on_progress(data: dict) -> None:
+        # finalizeStatus 的 phase/progress → __progress__，喂 ab-agent SSE 时间线
+        line: dict = {"__progress__": True, "phase": data.get("phase")}
+        prog = data.get("progress")
+        if isinstance(prog, (int, float)):
+            line["progress"] = float(prog)
+        print(json.dumps(line), flush=True)
+
+    conversation_id = os.environ.get("CONVERSATION_ID") or None
+    title = args.vod_title or Path(local_path).stem
+    try:
+        result = finalize_recording(
+            local_path,
+            private_token=priv_token,
+            transcode=True,
+            cover=True,
+            cover_at_sec=args.cover_at_sec,
+            title=title,
+            resolve_cdn=True,
+            keep_tail_sec=keep_tail_sec,
+            conversation_id=conversation_id,
+            on_progress=_on_progress,
+        )
+    except Exception as e:  # noqa: BLE001 — 收尾失败不应丢掉已录好的本地文件
+        print(f"[record] VOD 上传收尾失败，降级为仅本地文件：{e}", file=sys.stderr)
+        print(local_path)
+        return
+
+    cdn_url = result.get("fileUrl") or ""
+    cover_url = result.get("coverUrl") or ""
+    duration = result.get("durationSec")
+    vod_ref = result.get("vodRef") or ""
+    file_id = result.get("fileId")
+
+    # 上传成功，默认删本地 webm（VOD 已持有），除非 --keep-webm
+    if not args.keep_webm:
+        try:
+            os.unlink(local_path)
+        except OSError:
+            pass
+
+    print("✅ 录屏已生成并上传 VOD")
+    if cdn_url:
+        print(f"🔗 视频地址：{cdn_url}")
+    if cover_url:
+        print(f"🖼️ 封面：{cover_url}")
+    if isinstance(duration, (int, float)):
+        print(f"🕐 时长：{duration:.1f}s")
+    # 结构化 asset 标记：ab-agent postcall 解析这一行下发前端播放器
+    asset = {
+        "url": cdn_url,
+        "coverUrl": cover_url,
+        "durationSec": duration,
+        "vodRef": vod_ref,
+        "fileId": file_id,
+    }
+    print("__web_record_asset__ " + json.dumps(asset, ensure_ascii=False))
 
 
 if __name__ == "__main__":

package/skills/web-capture/scripts/screenshot.py

@@ -50,6 +50,21 @@ def main() -> None:
     cli_args.add_common_args(ap)
 
     args = ap.parse_args()
+
+    # 截屏只出图片。若 --output 是视频后缀，Playwright 的 page.screenshot() 会按扩展名
+    # 推断出 video/webm 并抛一串晦涩的 mime 错误。这里提前拦截，返回面向模型的清晰指引，
+    # 把请求导向 web_record（录屏入口）。
+    video_exts = (".webm", ".mp4", ".mov", ".mkv", ".avi", ".gif")
+    if args.output.lower().endswith(video_exts):
+        ext = Path(args.output).suffix or "(video)"
+        print(
+            f"截屏入口只输出静态图片（.png/.jpg），不能生成 {ext} 视频。"
+            "请改用 web_record 工具录屏（固定时长 / 自动滚动 / storyboard），"
+            "或把 --output 换成 .png / .jpg 后缀。",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
     storage_path, is_temp = cli_args.build_storage(args)
 
     cfg: dict = {

package/skills/web-capture/skill.json

@@ -4,14 +4,14 @@
   "tier": "tool",
   "category": "consuming",
   "title": "Web Page Capture",
-  "description": "Drive a headless browser (Playwright Python) to capture any URL to local files: full-page / element / region screenshots, fixed-duration / condition-triggered / auto-scroll recordings, and storyboard videos (highlight / focus / zoom / scroll / virtual-cursor click / caption / title-card / arrow / numbered sequence / redact / code-line highlight). Two entry scripts: scripts/screenshot.py (stills) and scripts/record.py (webm video, storyboards, templates).",
+  "description": "Drive a headless browser (Playwright Python) to capture any URL to a local STILL IMAGE (png/jpg): full-page / viewport / element / region screenshots, with device emulation, waiting, hide/mask/redact, and static annotations (highlight / arrow / caption / numbered sequence / redact). Images only — for video / recording / scroll-through / storyboard clips (webm) use the web_record tool instead.",
   "envVars": ["WEB_CAPTURE_BROWSER", "WEB_CAPTURE_OUTPUT_BASE", "WEB_CAPTURE_NO_SANDBOX", "WEB_CAPTURE_ALLOW_PRIVATE_HOSTS", "PLAYWRIGHT_BROWSERS_PATH"],
   "entry": { "type": "python", "scriptPath": "scripts/screenshot.py" },
   "parameters": {
     "type": "object",
     "properties": {
       "url": { "type": "string", "description": "Target page URL (http/https)" },
-      "output": { "type": "string", "description": "Local output path (screenshot.py: *.png, default screenshot.png)" },
+      "output": { "type": "string", "description": "Local output path, must be an image (*.png / *.jpg, default screenshot.png). For .webm video use the web_record tool." },
       "browser": { "type": "string", "description": "chromium | firefox | webkit (default chromium)" },
       "device": { "type": "string", "description": "Device emulation name, e.g. 'iPhone 15 Pro'" },
       "viewport": { "type": "string", "description": "Viewport as 'width,height', e.g. '1280,800'" },

package/skills/web-record/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: web-record
+description: |
+  网页录屏 / 分镜视频技能（输出 webm），基于 Playwright Python，对任意 URL 落盘到本地。
+  支持：固定时长 / 条件触发（元素出现 / 消失）停止、自动滚动录屏（从头划到尾）、自定义分镜（storyboard）、参数化模板。
+  分镜场景：高亮 / 聚焦 / 放大 / 滚动 / 虚拟光标点击 / 打字 / 悬停 / 字幕 / 标题卡 / 箭头 / 编号序列 / 打码 / 代码行高亮。
+
+  只出视频（.webm）。要静态截图（png/jpg）请用 web-capture / web_capture。
+
+  当用户提到以下任何需求时，立即使用本 skill：
+  - 录屏、网页录制、录制视频、录一段操作、生成 webm、screencast
+  - 滚动录屏、页面从头划到尾的视频
+  - 多场景视频、分镜视频、storyboard、按时间线编排（红框高亮 / 局部放大 / 滚动介绍）
+  - 演示点击 / 输入 / 悬停（虚拟鼠标 + 涟漪 / 打字机 / 触发 tooltip）的动态视频
+  - 用模板一行出片（github-repo-intro / github-readme-tour / github-code-tour 等）
+triggers:
+  - 录屏、网页录制、录制视频、录一段操作、生成 webm、screencast
+  - 滚动录屏、页面从头划到尾的视频
+  - 多场景视频、分镜视频、storyboard、按时间线编排
+  - 演示点击 / 输入 / 悬停（虚拟鼠标 + 涟漪 / 打字机 / 触发 tooltip）
+  - 模板视频一行出片、按顺序编号高亮多个区域并录制
+---
+
+# 网页录屏 / 分镜视频 Skill（web_record）
+
+录屏入口，输出 **`.webm`**。底层复用 web-capture 的 `scripts/record.py` 与 `_media_screenshot/` 包
+（本 skill 的 `entry.scriptPath` 相对指向 `../web-capture/scripts/record.py`）。静态截图请改用
+**web-capture / `web_capture`**。
+
+完整的参数说明、storyboard 场景类型、模板列表与用法，见 **web-capture 的 `SKILL.md`「录屏 `record.py`」章节**——本 skill 就是把那条录屏路径独立成一个工具，避免把 `.webm` 误喂给截图入口。
+
+## 常见用法
+
+固定时长：
+
+```bash
+python3 <SkillDir>/../web-capture/scripts/record.py \
+  --url "https://example.com" --output "demo.webm" \
+  --viewport "1280,720" --duration 8000
+```
+
+自动滚动（从头划到尾）：
+
+```bash
+python3 <SkillDir>/../web-capture/scripts/record.py \
+  --url "https://example.com" --output "scroll.webm" \
+  --viewport "1440,900" --scroll-through \
+  --scroll-pause-top 1000 --scroll-pause-bottom 1500
+```
+
+模板出片：
+
+```bash
+python3 <SkillDir>/../web-capture/scripts/record.py \
+  --template github-repo-intro \
+  --param repo_url=https://github.com/user/repo \
+  --output repo.webm
+```
+
+至少需提供 `--duration` / `--stop-when-selector` / `--stop-when-hidden` / `--scroll-through`
+/ `--storyboard` / `--template` 之一。模板 / storyboard JSON 可自带 `url`。

package/skills/web-record/skill.json

@@ -0,0 +1,46 @@
+{
+  "name": "web-record",
+  "toolName": "web_record",
+  "tier": "tool",
+  "category": "consuming",
+  "title": "Web Page Recording",
+  "description": "Drive a headless browser (Playwright Python) to RECORD any URL to a video, then (by default) transcode to mp4, grab a cover frame, upload to VOD and return a playable CDN URL. Modes: fixed-duration recording, condition-triggered stop (element appears / disappears), auto-scroll from top to bottom, custom storyboards, and parameterized templates. Storyboard scenes: highlight / focus / zoom / scroll / virtual-cursor click / type / hover / caption / title-card / arrow / numbered sequence / redact / code-line highlight. For still images (png/jpg) use the web_capture tool instead. Use this tool whenever the user wants a video / recording / screencast of a web page: record a page, scroll-through video, page-from-top-to-bottom clip, demo of clicks/typing/hover, storyboard / multi-scene intro video, or a template-based clip.",
+  "envVars": ["WEB_CAPTURE_BROWSER", "WEB_CAPTURE_OUTPUT_BASE", "WEB_CAPTURE_NO_SANDBOX", "WEB_CAPTURE_ALLOW_PRIVATE_HOSTS", "PLAYWRIGHT_BROWSERS_PATH", "REMOTION_RENDER_API_URL", "PRIV_TOKEN"],
+  "entry": { "type": "python", "scriptPath": "../web-capture/scripts/record.py" },
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "url": { "type": "string", "description": "Target page URL (http/https). May be omitted only when a template or storyboard JSON supplies its own url." },
+      "output": { "type": "string", "description": "Local output path, must end in .webm (default recording.webm)" },
+      "browser": { "type": "string", "description": "chromium | firefox | webkit (default chromium; chromium recommended for recording)" },
+      "device": { "type": "string", "description": "Device emulation name, e.g. 'iPhone 15 Pro'" },
+      "viewport": { "type": "string", "description": "Viewport as 'width,height', e.g. '1280,720'" },
+      "duration": { "type": "number", "description": "Fixed recording length in ms" },
+      "stop_when_selector": { "type": "string", "description": "Stop recording once this CSS selector appears" },
+      "stop_when_hidden": { "type": "string", "description": "Stop recording once this CSS selector disappears" },
+      "max_duration": { "type": "number", "description": "Safety cap (ms) for condition-based stop modes (default 60000)" },
+      "scroll_through": { "type": "boolean", "description": "Auto-scroll smoothly from top to bottom while recording" },
+      "scroll_step": { "type": "number", "description": "Pixels per scroll step (default 60)" },
+      "scroll_interval": { "type": "number", "description": "Interval between scroll steps in ms (default 50)" },
+      "scroll_pause_top": { "type": "number", "description": "Pause at the top before scrolling, ms (default 800)" },
+      "scroll_pause_bottom": { "type": "number", "description": "Pause at the bottom after scrolling, ms (default 1200)" },
+      "storyboard": { "type": "string", "description": "Path to a storyboard JSON file describing scenes (mutually exclusive with template)" },
+      "template": { "type": "string", "description": "Template name under templates/ (e.g. github-repo-intro); combine with param (mutually exclusive with storyboard)" },
+      "param": { "type": "array", "description": "Template params as 'key=value' strings; repeatable" },
+      "list_templates": { "type": "boolean", "description": "List available templates and exit" },
+      "wait_for_selector": { "type": "string", "description": "Wait for this CSS selector before recording" },
+      "wait_for_timeout": { "type": "number", "description": "Fixed wait (ms) before recording" },
+      "color_scheme": { "type": "string", "description": "light | dark | no-preference (emulate prefers-color-scheme)" },
+      "user_agent": { "type": "string", "description": "Override User-Agent" },
+      "timeout": { "type": "number", "description": "Playwright global action timeout in ms" },
+      "ignore_https_errors": { "type": "boolean", "description": "Ignore HTTPS certificate errors" },
+      "storage_state": { "type": "string", "description": "storageState JSON file path (logged-in recording)" },
+      "cookies": { "type": "string", "description": "Playwright cookies JSON string or file (top-level array)" },
+      "no_upload": { "type": "boolean", "description": "Skip VOD upload; keep only the local webm. By default the recording is transcoded to mp4, a cover frame is grabbed, uploaded to VOD, and a playable CDN URL is returned." },
+      "vod_title": { "type": "string", "description": "Title for the uploaded VOD asset (defaults to the output file name)" },
+      "cover_at_sec": { "type": "number", "description": "Cover frame timestamp in seconds (default 0.5)" },
+      "keep_webm": { "type": "boolean", "description": "Keep the local webm after a successful upload (default: delete it since VOD holds the copy)" }
+    },
+    "required": ["url"]
+  }
+}