@remixmate/cli 0.9.40 → 0.9.43

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.40",
-  "generatedAt": "2026-09-22T08:04:46.896Z",
+  "version": "0.9.43",
+  "generatedAt": "2026-09-22T14:20:35.434Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -464,7 +464,7 @@
             "items": {
               "type": "string"
             },
-            "description": "Media URLs for the template's image/video carousel. When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
+            "description": "Media URLs for the template's image/video carousel. When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed into customPayload.sequence.items when payloadDefaults.sequence is declared, otherwise customPayload.carousel.items, as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
           },
           "scene_images": {
             "type": "array",
@@ -478,7 +478,7 @@
             "items": {
               "type": "string"
             },
-            "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). Each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
+            "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). For image sequences (payloadDefaults.sequence), lines map in order to sequence.items[].caption, with at most one line per image. Otherwise each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
           },
           "stub_image_url": {
             "type": "string",
@@ -1043,7 +1043,7 @@
       "tier": "tool",
       "category": "consuming",
       "title": "Web Page Reader",
-      "summary": "Open any URL in a headless browser (Playwright Python) and return the page's MAIN TEXT — title, headings, paragraphs, lists, code blocks and tables — as Markdown, plain text, or structured JSON. Boilerplate (nav / sidebar / comments / ads / footer) is stripped by a Readability-style pass, and JS-rendered pages work because a real browser runs the page. This is the tool to use whenever you need to KNOW WHAT A PAGE SAYS: summarizing an article, pulling source material for a script, reading a README or docs page, checking what a link contains. It returns text, not pictures — for a screenshot (png/jpg) use web_screenshot, for a recording (mp4/webm) use web_record. Output is capped by max_chars (default 20000) and truncated on a block boundary; pass an `output` path to keep the full text on disk.",
+      "summary": "Open any URL in a headless browser (Playwright Python) and return the page's MAIN TEXT — title, headings, paragraphs, lists, code blocks and tables — as Markdown, plain text, or structured JSON. Boilerplate (nav / sidebar / comments / ads / footer) is stripped by a Readability-style pass, and JS-rendered pages work because a real browser runs the page. This is the tool to use whenever you need to KNOW WHAT A PAGE SAYS: summarizing an article, pulling source material for a script, reading a README or docs page, checking what a link contains. It returns text, not pictures — for a screenshot (png/jpg) use web_screenshot, for a recording (mp4/webm) use web_record. GitHub repository pages also return observed Stars/Forks/Watchers before sidebar cleanup (missing counters stay unknown). Reuse successful reads across script and template fields; do not repeat the same URL just for counters already returned. Output is capped by max_chars (default 20000) and truncated on a block boundary; pass an `output` path to keep the full text on disk.",
       "triggers": [
         "Read this link / what does this page say / summarize this article",
         "Fetch page content, extract article text, get the text of a URL",
@@ -1083,7 +1083,7 @@
           },
           "selector": {
             "type": "string",
-            "description": "Read only inside this CSS selector. Leave empty to auto-detect the article container — only reach for this when the auto-detected container was wrong."
+            "description": "Read only inside this CSS selector, preserving the selected region's sidebar/button text instead of pruning boilerplate. Scripts/styles are still removed. Leave empty to auto-detect the article container; use a targeted selector only for a concrete missing required fact."
           },
           "include_links": {
             "type": "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.40",
+  "version": "0.9.43",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",
@@ -22,6 +22,7 @@
     "test:cli": "npm run build && node --test test/*.test.mjs",
     "test:validators": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-validators.py",
     "test:web-read": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-web-read.py",
+    "test:web-read:browser": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-web-read-browser.py",
     "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 node dist/cli.js exec -- python3 scripts/test-template-pipeline.py",
     "test:props-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-props-contract.py",
     "test:card-array-keys": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-card-array-keys.py",
@@ -37,6 +38,8 @@
     "check:render": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/render-template-check.py",
     "clean": "node scripts/clean.mjs",
     "test:countdown": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-countdown-strategy.py",
+    "test:prepare-contracts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-prepare-contracts.py",
+    "test:image-sequence": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-image-sequence.py",
     "test:ranking-count": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-ranking-count.py"
   },
   "keywords": [

package/skills/gen-script/scripts/gen_script.py

@@ -22,6 +22,8 @@ import math
 import os
 import sys
 import uuid
+from copy import deepcopy
+from urllib.parse import urlsplit
 
 SCHEMA_PATH = os.environ.get(
     "VIDEO_DSL_SCHEMA_PATH",
@@ -66,12 +68,16 @@ except ImportError:
 try:
     from registry_loader import (
         load_registry_data as _load_registry_data,
-        get_template as _get_template,
+        require_visible_template as _get_template,
+        TemplateStatusGatedError,
     )
     _HAS_REGISTRY_LOADER = True
 except ImportError:
     _HAS_REGISTRY_LOADER = False
 
+    class TemplateStatusGatedError(RuntimeError):  # type: ignore[no-redef]
+        """占位：共享模块不可导入时（单测 / 裁剪安装）永远不会被抛出。"""
+
 VALID_RATIOS = ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9"]
 VALID_PURPOSES = ["opening", "point", "example", "explanation", "highlight", "cta", "ending"]
 
@@ -376,11 +382,19 @@ def _load_template_config(template_id: str) -> dict | None:
          （仅在仓库还残留旧目录时使用）。
     返回完整 template dict（含 supportedAspectRatios / assetRequirements / slotMapping 等），
     找不到时返回 None。
+
+    ⚠️ 一个例外**不走**兜底：模板存在、但被状态门控挡在可见集合外（``beta`` 而本进程
+    没开 ENABLE_BETA_TEMPLATES）时 ``TemplateStatusGatedError`` 原样上抛。下面那些
+    ``_template_*`` / ``_resolve_contract`` 读到 None 会一路退回通用默认值 —— arc 三段式、
+    默认 layout、空 customPayload，而且 llmHint 根本不会打给模型。对「id 不存在」这是
+    合理容错，对「模板在线但本进程看不见」则是把配置问题伪装成一条能跑通的废片。
     """
     # 优先使用 registry_loader（这是模板元数据的唯一权威来源）
     if _HAS_REGISTRY_LOADER:
         try:
             return _get_template(template_id)
+        except TemplateStatusGatedError:
+            raise
         except Exception as exc:
             print(
                 f"⚠️  registry_loader failed, falling back to local template.json: {exc}",
@@ -480,7 +494,7 @@ def _template_needs_image(template_config: dict | None) -> bool:
 #   - countdown         dict|None    countdown 策略的解析结果（见 countdown_spec 模块；
 #                                    非 countdown 模板为 None）
 #   - payload_style     str          capabilities.payloadStyle ∈ {visual-overlay, slide, carousel-caption}
-#   - duration_strategy str          capabilities.durationStrategy ∈ {explicit, fit-caption}
+#   - duration_strategy str          capabilities.durationStrategy ∈ {explicit, fit-caption, fit-images}
 #   - payload_defaults  dict         capabilities.payloadDefaults（carousel-caption 的轮播/字幕默认值）
 #   - duration_model    dict|None    capabilities.durationModel（fit-caption 估时用的节奏数值，
 #                                    由模板声明；缺省则不估时，见 _estimate_fit_caption_duration）
@@ -524,7 +538,7 @@ def _resolve_contract(template_config: dict | None) -> dict:
         payload_style = "slide" if primary_visual_type == "none" else "visual-overlay"
 
     duration_strategy = caps.get("durationStrategy")
-    if duration_strategy not in ("explicit", "fit-caption"):
+    if duration_strategy not in ("explicit", "fit-caption", "fit-images"):
         duration_strategy = "explicit"
 
     fixed_scenes = caps.get("fixedScenes")
@@ -786,6 +800,29 @@ def _estimate_fit_caption_duration(
     return max(headline_intro, caption_sec, carousel_sec) + duration_model.get("tailPaddingSec", 0)
 
 
+def _estimate_fit_images_duration(sequence: dict, model: dict | None, fps: int = 30) -> float:
+    """Apply template-declared image timing, in frames just like the renderer.
+
+    Hold tiers and transition margins belong to durationModel.sequence; never
+    infer them from a template id or silently use the caller's target duration.
+    """
+    timing = (model or {}).get("sequence", {})
+    tiers = timing.get("holdSecByCount", [])
+    count = len(sequence["items"])
+    rule_hold = next((tier["holdSec"] for tier in tiers if count <= tier["maxItems"]), None)
+    if rule_hold is None:
+        raise ValueError("fit-images requires durationModel.sequence.holdSecByCount covering the image count")
+    base_hold = sequence.get("defaultHoldSec", rule_hold)
+    transition_ms = sequence.get("transitionMs", timing.get("transitionMs"))
+    margin = timing.get("minHoldMarginFrames")
+    if transition_ms is None or margin is None:
+        raise ValueError("fit-images requires sequence transitionMs and durationModel.sequence.minHoldMarginFrames")
+    # Python round uses ties-to-even; JS Math.round uses floor(x + 0.5).
+    min_frames = max(2, math.floor(transition_ms / 1000 * fps + 0.5)) + margin
+    return sum(max(min_frames, math.floor(item.get("holdSec", base_hold) * fps + 0.5))
+               for item in sequence["items"]) / fps
+
+
 def _build_carousel_caption_dsl(
     *,
     template_id: str,
@@ -814,7 +851,12 @@ def _build_carousel_caption_dsl(
     needsNarration），不再读 input-schema.json，也没有 if template_id==X 分支。
     轮播素材由调用方在 carousel_items 里直接给 URL（existing 资产），不触发 AI 生图。
     """
-    defaults = payload_defaults or {}
+    defaults = deepcopy(payload_defaults or {})
+    sequence_mode = isinstance(defaults.get("sequence"), dict)
+    if sequence_mode and not carousel_items:
+        raise ValueError("Image sequence needs --carousel-items; caption text alone cannot supply images")
+    if sequence_mode and len(caption_lines) > len(carousel_items):
+        raise ValueError("Image sequence has more --caption-lines than images; use at most one caption per image")
 
     # ── Build assets from carousel_items ──────────────────────────────────
     assets = []
@@ -822,7 +864,9 @@ def _build_carousel_caption_dsl(
     for idx, url in enumerate(carousel_items):
         asset_id = f"carousel-img-{idx + 1:02d}"
         # Determine if URL is a video (basic heuristic on extension)
-        is_video = any(url.lower().endswith(ext) for ext in (".mp4", ".mov", ".webm", ".avi"))
+        is_video = urlsplit(url).path.lower().endswith((".mp4", ".mov", ".webm", ".avi"))
+        if sequence_mode and is_video:
+            raise ValueError("Image sequence requires image URLs in --carousel-items, not video URLs")
         assets.append({
             "assetId": asset_id,
             "type": "video" if is_video else "image",
@@ -889,6 +933,18 @@ def _build_carousel_caption_dsl(
         if defaults.get(key):
             custom_payload[key] = defaults[key]
 
+    # The carousel-caption capability also covers full-frame image sequences.
+    # Its declared sequence defaults select that payload shape; do not send
+    # carousel entrance/exit or a typewriter caption block to such components.
+    if sequence_mode:
+        sequence_config = defaults["sequence"]
+        sequence_config["items"] = [
+            {"assetRef": asset_id,
+             **({"caption": caption_lines[index]} if index < len(caption_lines) else {})}
+            for index, (asset_id, _) in enumerate(carousel_asset_ids)
+        ]
+        custom_payload = {"sequence": sequence_config}
+
     # ── Narration skeleton ────────────────────────────────────────────────
     narration_text = _localize_label(output_language, "narration_opening",
                                      label="", topic=topic, duration=duration)
@@ -898,6 +954,10 @@ def _build_carousel_caption_dsl(
     # 这是打字机/画面驱动模板的核心——没有旁白来"撑"时长，
     # 必须由 caption 自己定，否则文字打完后画面会静止到 targetDuration。
     effective_duration = duration
+    if duration_strategy == "fit-images":
+        if not sequence_mode:
+            raise ValueError("fit-images requires capabilities.payloadDefaults.sequence")
+        effective_duration = _estimate_fit_images_duration(custom_payload["sequence"], duration_model)
     if duration_strategy == "fit-caption":
         est = _estimate_fit_caption_duration(custom_payload, duration_model, template_id)
         if est > 0:
@@ -1631,7 +1691,8 @@ Examples:
              "--carousel-items url1 --carousel-items url2. "
              "For templates declaring capabilities.payloadStyle=carousel-caption, "
              "these URLs are placed directly into "
-             "customPayload.carousel.items as existing assets, bypassing AI image generation entirely.",
+             "customPayload.sequence.items when payloadDefaults.sequence is declared, otherwise "
+             "customPayload.carousel.items, as existing assets without AI image generation.",
     )
     parser.add_argument(
         "--scene-images",
@@ -1654,7 +1715,8 @@ Examples:
         help="On-screen caption line. Can be repeated: "
              "--caption-lines 'line1' --caption-lines 'line2'. "
              "For templates declaring capabilities.payloadStyle=carousel-caption, "
-             "these are placed into customPayload.caption.lines. "
+             "these are placed into customPayload.caption.lines, or sequence.items[].caption "
+             "in image order when payloadDefaults.sequence is declared. "
              "Line count limits and whether **emphasis** is parsed are declared per "
              "template — see the chosen template's llmHint.",
     )
@@ -1833,4 +1895,11 @@ Examples:
 
 
 if __name__ == "__main__":
-    main()
+    try:
+        main()
+    except TemplateStatusGatedError as exc:
+        # 状态门控挡住了一个确实在线的模板。这是配置问题，不是调用方参数错误，
+        # 所以给一条可执行的提示而不是 traceback —— 并且**必须**非零退出：静默
+        # 退回通用骨架正是这次要消灭的失败形态。
+        print(f"❌ {exc}", file=sys.stderr)
+        sys.exit(1)

package/skills/gen-script/skill.json

@@ -61,7 +61,7 @@
         "items": {
           "type": "string"
         },
-        "description": "Media URLs for the template's image/video carousel. When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
+        "description": "Media URLs for the template's image/video carousel. When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed into customPayload.sequence.items when payloadDefaults.sequence is declared, otherwise customPayload.carousel.items, as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
       },
       "scene_images": {
         "type": "array",
@@ -75,7 +75,7 @@
         "items": {
           "type": "string"
         },
-        "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). Each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
+        "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). For image sequences (payloadDefaults.sequence), lines map in order to sequence.items[].caption, with at most one line per image. Otherwise each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
       },
       "stub_image_url": {
         "type": "string",

package/skills/gen-script/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-script",
   "repoName": "agent-skill-media-maker",
   "skillId": "474",
-  "version": "V13",
+  "version": "V15",
   "skillDescription": "Video-script generation skill. Turns a user-supplied topic into a structured Video DSL (JSON) that describes the full video — scene structure, asset requirements, and narrative flow.\n\nUse this skill as soon as the user mentions any of these intents:\n- Write a video script, generate a video script, plan a video, write storyboards\n- Create a short video, plan video content, generate a Video DSL\n- Turn a topic into a video structure / video content plan\n\nEven when the user does not say \"generate the DSL\", use this skill whenever they want to turn a topic into a structured video plan.\n\n⚠️ Stop-and-confirm gate: after this skill returns a DSL, show the full script and wait for the user's explicit confirmation. Never call `prepare_video_assets` in the same turn."
 }

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

@@ -331,11 +331,18 @@ def resolve_remotion_entry(template_id: str, aspect_ratio: str) -> str:
 
     Falls back to ``MainVideo16x9`` / ``MainVideo`` when the template isn't
     found, the registry can't be loaded, or the aspect ratio isn't keyed.
+
+    ``include_all_statuses=True`` —— 状态门控是**选型策略**，不是渲染策略。
+    它要回答的是"列表里该不该出现这个模板、agent 该不该挑它"，一旦模板已经被选定并
+    通过校验，渲染就必须读到它真实的定义。把门控带到这里的后果是静默换成另一个
+    composition / 丢掉封面，成片与模板声明不符，而日志里只字未提。
+    「能不能被选中」由 template-registry 的 ``--include-beta`` 与
+    ``dsl_validator._check_template_status_gate`` 负责把关。
     """
     if template_id:
         try:
             from registry_loader import get_template  # type: ignore
-            tpl = get_template(template_id)
+            tpl = get_template(template_id, include_all_statuses=True)
             if tpl:
                 entry_map = tpl.get("remotionEntry") or {}
                 hit = entry_map.get(aspect_ratio)
@@ -356,6 +363,9 @@ def resolve_cover_composition_id(template_id: str) -> Optional[str]:
     Reading from the registry rather than the template.json file directly so
     behaviour matches what ab-render's manifest exposes (the registry is the
     aggregated truth used by both ab-render and ab-skill).
+
+    ``include_all_statuses=True`` 的理由同 ``resolve_remotion_entry``：门控管选型，
+    不管渲染。带上门控的话 beta 模板的封面会无声无息地不渲。
     """
     if not template_id:
         return None
@@ -363,7 +373,7 @@ def resolve_cover_composition_id(template_id: str) -> Optional[str]:
         # sys.path setup happens once at module top — see header.
         from registry_loader import get_template  # type: ignore
 
-        tpl = get_template(template_id)
+        tpl = get_template(template_id, include_all_statuses=True)
         if not tpl:
             return None
         for comp in tpl.get("compositions", []) or []:
@@ -554,7 +564,8 @@ def validate_and_fix_render_plan(render_plan: dict) -> list:
     if template_id:
         try:
             from registry_loader import get_template  # type: ignore
-            _tpl = get_template(template_id)
+            # include_all_statuses：门控管选型不管渲染（理由见 resolve_remotion_entry）。
+            _tpl = get_template(template_id, include_all_statuses=True)
             needs_video_duration = bool(
                 ((_tpl or {}).get("capabilities") or {}).get("needsVideoDuration")
             )
@@ -1790,7 +1801,10 @@ def render_with_remote_api(
     if template_id:
         try:
             from registry_loader import get_template  # type: ignore
-            _meta = get_template(template_id)
+            # include_all_statuses：门控管选型不管渲染（理由见 resolve_remotion_entry）。
+            # 漏掉它的话私有 beta 模板会丢 sourceOssKey，转而按内置模板渲——渲出来的
+            # 是另一个模板的画面。
+            _meta = get_template(template_id, include_all_statuses=True)
             if _meta and not _meta.get("isBuiltin"):
                 source_oss_key = _meta.get("sourceOssKey")
         except Exception:
@@ -2086,6 +2100,26 @@ def auto_bind_template(dsl: dict, template_id: str) -> dict:
         LogPrint(f"❌ template not found: {template_id} (available: {available})", file=sys.stderr)
         sys.exit(1)
 
+    # 选型门控在这里落地，而不是在上面的查表上：查表刻意用未门控的列表，因为绑定
+    # 必须读到模板真实的定义（slotMapping / compositions）。门控管的是"允许不允许
+    # 选中它"，而 auto_bind 正是"一个 id 变成本次成片所用模板"的那一刻。
+    #
+    # dsl_validator 已经在更早的位置报同一件事，但它只看 meta.templateId；手写的
+    # DSL 可能没有那个字段，只靠 --template-id 传进来 —— 这里补上那条路。
+    try:
+        from registry_loader import gated_status  # type: ignore
+        _gated = gated_status(template_id)
+    except Exception:
+        _gated = None
+    if _gated:
+        LogPrint(
+            f"❌ template '{template_id}' exists but its status is '{_gated}', so this "
+            f"process is not allowed to select it. Set ENABLE_BETA_TEMPLATES=1 to admit "
+            f"beta templates, or promote the template to stable.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
     selected = match_template.load_full_template(selected)
     LogPrint(f"📋 auto-bound template: {selected.get('name', '')} ({template_id})", file=sys.stderr)
     binding = match_template.build_binding(selected, dsl)
@@ -2363,6 +2397,14 @@ Examples:
             LogPrint(f"❌ {exc}", file=sys.stderr)
             sys.exit(2)
 
+    from video_dsl.runtime.payload_contract import plan_asset_errors
+    reference_errors = plan_asset_errors(render_plan)
+    if reference_errors:
+        LogPrint("❌ RenderPlan asset references are invalid:", file=sys.stderr)
+        for error in reference_errors[:10]:
+            LogPrint(f"   - {error}", file=sys.stderr)
+        sys.exit(2)
+
     if not args.skip_asset_resolve:
         # Stub mode: short-circuit gen-image / gen-video before counting pending.
         # CLI flag takes precedence; env vars act as fallback with a visible warning

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

@@ -17,6 +17,8 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "template-registry" / "scripts"))
 
 from countdown_spec import resolve_countdown_spec  # noqa: E402
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "template-registry"))
+from video_dsl.runtime.payload_contract import required_payload_errors  # noqa: E402
 
 
 def _payload_prop(props: dict, key: str):
@@ -84,6 +86,7 @@ def validate_required_props(template: dict, rows: list[dict]) -> None:
         schema = template.get("customPayloadSchema") or {}
         missing = [error for key in sorted(required)
                    for error in _required_value_errors(_payload_prop(props, key), schema.get(key, {}), key)]
+        missing += required_payload_errors(template, props)
         if missing:
             failures.append(f"scene {row.get('sceneId', '?')}: {', '.join(missing)}")
 

package/skills/render-video/version.json

@@ -2,6 +2,6 @@
   "skillName": "render-video",
   "repoName": "agent-skill-media-maker",
   "skillId": "473",
-  "version": "V23",
+  "version": "V25",
   "skillDescription": "Final-render skill: loads a persisted RenderPlan by `job_id` and drives the Remotion engine to produce the final video.\n\nUse this skill as soon as the user mentions any of these intents (after assets are already prepared):\n- Render the video, composite the video, export the video\n- Turn the prepared assets into the final clip\n- Render with Remotion\n\nPrerequisite: assets must already be generated via `prepare_video_assets`. This skill never resolves or regenerates assets — pass it a `job_id` from a previous `prepare_video_assets` call.\n\n⚠️ Stop-and-confirm gate: never call this skill until the user has explicitly confirmed the assets prepared by `prepare_video_assets`. If those assets were prepared in the current turn and the user has not replied since, stop and ask instead of rendering."
 }

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

@@ -53,10 +53,13 @@ __all__ = [
     "load_registry_data",
     "load_registry_indexed",
     "get_template",
+    "require_visible_template",
+    "gated_status",
     "list_templates",
     "invalidate_cache",
     "RegistryAuthError",
     "RegistryUnreachableError",
+    "TemplateStatusGatedError",
     "EXIT_NOT_AUTHENTICATED",
     "EXIT_BACKEND_UNREACHABLE",
 ]
@@ -78,6 +81,15 @@ class RegistryAuthError(RuntimeError):
 class RegistryUnreachableError(RuntimeError):
     """网络不通 / 超时 / 5xx —— 用户无需重新登录，重试或修配置即可。"""
 
+
+class TemplateStatusGatedError(RuntimeError):
+    """模板存在，但它的 ``status`` 不在当前进程的可见集合里（见 ``_allowed_statuses``）。
+
+    与「id 不存在」分开的独立失败模式：前者要改 id，后者要开门控开关
+    （``ENABLE_BETA_TEMPLATES=1``）或把模板转正。压成同一个 ``None`` 返回值的后果见
+    ``require_visible_template`` 的文档。
+    """
+
 # 默认缓存 TTL（秒）。HTTP 拉取后该时间内不再重新请求。
 _DEFAULT_TTL_SECONDS = 300
 
@@ -386,6 +398,46 @@ def get_template(template_id: str, *, include_all_statuses: bool = False) -> Opt
     return load_registry_indexed(include_all_statuses=include_all_statuses).get(template_id)
 
 
+def gated_status(template_id: str) -> Optional[str]:
+    """模板存在、但被状态门控挡在可见集合外时返回它的真实 status；否则 None。
+
+    ``get_template`` 用 ``None`` 同时表达「registry 里没有这个 id」和「有,但被
+    门控挡了」两件完全不同的事。前者是调用方拼错了 id,后者是运行时配置问题
+    （模板确实在线,只是当前进程没开 beta）—— 两者的处置方式不同,却在一个返回
+    值里混成一样。这个函数把后者单独识别出来。
+    """
+    if not template_id:
+        return None
+    if get_template(template_id) is not None:
+        return None
+    tpl = get_template(template_id, include_all_statuses=True)
+    return _resolve_status(tpl) if tpl is not None else None
+
+
+def require_visible_template(template_id: str) -> Optional[dict]:
+    """与 ``get_template`` 相同,但模板**被状态门控挡住**时抛异常而不是返回 None。
+
+    为什么需要它：``get_template`` 返回 None 之后,调用方普遍的写法是「拿不到就用
+    默认值继续」—— 对"这个 id 不存在"是合理的容错,对"模板在线但本进程看不到"却是
+    灾难性的静默降级:模板的 llmHint / customPayloadSchema / capabilities 全部蒸发,
+    脚本按通用骨架生成、payload 契约整段跳过,最后烧掉渲染积分换一条废片,而日志里
+    一个字都没有。
+
+    返回 None 只剩一个含义：registry 里没有这个 templateId。
+    """
+    tpl = get_template(template_id)
+    if tpl is not None:
+        return tpl
+    status = gated_status(template_id)
+    if status is None:
+        return None
+    raise TemplateStatusGatedError(
+        f"模板 '{template_id}' 存在,但状态是 '{status}',当前进程的可见集合只有 "
+        f"{sorted(_allowed_statuses())}。设置 {_BETA_GATE_ENV}=1 放行 beta,"
+        f"或把该模板转为 stable —— 继续往下走只会拿不到它的契约并产出通用结果。"
+    )
+
+
 def list_templates(*, include_all_statuses: bool = False) -> list[dict]:
     """Return the visible templates as a list (status-filtered)."""
     return list(load_registry_indexed(include_all_statuses=include_all_statuses).values())

package/skills/template-registry/version.json

@@ -2,6 +2,6 @@
   "skillName": "template-registry",
   "repoName": "agent-skill-media-maker",
   "skillId": "475",
-  "version": "V15",
+  "version": "V18",
   "skillDescription": "Video-template registry skill. Stores every video-template definition and lists the available templates (templateId / name / aspect ratio / style tags).\n\nUse this skill as soon as the user mentions any of these intents:\n- View available templates / list every template\n\nNote: DSL→TemplateBinding is no longer a separate exposed step — once prepare_video_assets receives a template_id it builds the binding internally."
 }

package/skills/template-registry/video_dsl/runtime/dsl_validator.py

@@ -131,6 +131,10 @@ def _get_template_cfg(template_id: Optional[str]) -> Optional[dict]:
         shared-lib sys.path)
       - the registry can't be loaded (network/file/etc.)
       - the template isn't in the visible set (e.g. beta gate hides it)
+
+    最后那一条是**静默跳过整套模板契约校验**的入口 —— payload 必填字段、版式字段名、
+    逐句对齐全部形同不存在。它由 ``_check_template_status_gate`` 单独报一条错来兜底,
+    所以这里保持返回 None 不变(否则每个 ``_check_*`` 都会为同一件事各报一遍)。
     """
     if not template_id:
         return None
@@ -144,6 +148,39 @@ def _get_template_cfg(template_id: Optional[str]) -> Optional[dict]:
         return None
 
 
+def _check_template_status_gate(dsl: dict) -> list[ValidationError]:
+    """模板存在、却被状态门控挡在可见集合外 → 一条 error。
+
+    为什么必须报错而不是继续:下面所有读 ``_get_template_cfg`` 的检查(payload 必填、
+    slideSchemas 字段名、lineSyncSlides)拿到 None 之后都是 ``return []`` —— 于是一个
+    beta 模板的 DSL 能"零错误"通过校验,再一路烧掉 TTS 与渲染积分产出空壳画面。
+    contracts 测试之所以没发现这一点,是因为它们 patch 掉了 ``_get_template_cfg``,
+    生产里的门控在测试里从不生效。
+    """
+    template_id = _pick_template_id(dsl)
+    if not template_id:
+        return []
+    try:
+        from registry_loader import gated_status  # type: ignore
+    except ImportError:
+        return []
+    try:
+        status = gated_status(template_id)
+    except Exception:
+        # registry 不可达等问题由各自的加载路径报,这里不重复成第二条噪声。
+        return []
+    if not status:
+        return []
+    return [ValidationError(
+        "meta.templateId",
+        f"template '{template_id}' exists but its status is '{status}', so it is hidden "
+        f"from this process — every template-specific contract check (payload required "
+        f"fields, slide schemas, line-sync) would be skipped instead of enforced. "
+        f"Set ENABLE_BETA_TEMPLATES=1 to admit beta templates, or promote the template "
+        f"to stable.",
+    )]
+
+
 def _contains_cjk(text: str) -> bool:
     return bool(text) and bool(_CJK_PATTERN.search(text))
 
@@ -300,29 +337,17 @@ def _check_asset_enums(dsl: dict) -> list[ValidationError]:
 def _check_scene_asset_refs(dsl: dict) -> list[ValidationError]:
     """render-video 历史:scene 引用的 assetRef 必须在 assets[] 声明过。
 
-    检查范围:
-      - scene.audio.narration.assetRef
-      - scene.visuals.background.assetRef
+    包括 customPayload / templateData 中的嵌套 assetRef 与 global 引用。
     """
     errors: list[ValidationError] = []
     declared = {
         a.get("assetId") for a in (dsl.get("assets") or []) if a.get("assetId")
     }
-    for idx, scene in enumerate(dsl.get("scenes", []) or []):
-        sid = scene.get("id", f"scenes[{idx}]")
-        nar = (scene.get("audio") or {}).get("narration") or {}
-        nar_ref = nar.get("assetRef")
-        if nar_ref and nar_ref not in declared:
-            errors.append(ValidationError(
-                f"scenes[{idx}].audio.narration.assetRef",
-                f"scene '{sid}': narration.assetRef '{nar_ref}' not found in assets[]",
-            ))
-        bg_ref = ((scene.get("visuals") or {}).get("background") or {}).get("assetRef")
-        if bg_ref and bg_ref not in declared:
-            errors.append(ValidationError(
-                f"scenes[{idx}].visuals.background.assetRef",
-                f"scene '{sid}': visuals.background.assetRef '{bg_ref}' not found in assets[]",
-            ))
+    from .payload_contract import asset_references
+    for key in ("scenes", "global"):
+        for path, ref in asset_references(dsl.get(key), key):
+            if ref not in declared:
+                errors.append(ValidationError(path, "assetRef not found in assets[]"))
     return errors
 
 
@@ -742,14 +767,22 @@ def _check_custom_payload_fields(dsl: dict) -> list[ValidationError]:
     tpl = _get_template_cfg(_pick_template_id(dsl))
     if not tpl:
         return []
+    from .payload_contract import required_payload_errors
+    errors: list[ValidationError] = []
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        custom = scene.get("customPayload")
+        custom = dict(custom) if isinstance(custom, dict) else {}
+        if not custom.get("templateData") and isinstance(scene.get("templateData"), dict):
+            custom["templateData"] = scene["templateData"]
+        errors += [ValidationError(f"scenes[{idx}].customPayload", message)
+                   for message in required_payload_errors(tpl, custom)]
     if isinstance(tpl.get("slideSchemas"), dict):
-        return []  # 多版式模板走 _check_slide_payload_fields
+        return errors  # 多版式字段走 _check_slide_payload_fields
     cps = tpl.get("customPayloadSchema")
     if not isinstance(cps, dict) or not cps:
-        return []
+        return errors
 
     root = {"type": "object", "properties": cps}
-    errors: list[ValidationError] = []
     for idx, scene in enumerate(dsl.get("scenes", []) or []):
         custom = scene.get("customPayload")
         if not isinstance(custom, dict) or not custom:
@@ -1014,6 +1047,9 @@ def validate_integrity(dsl: dict) -> list[ValidationError]:
     # render-video 与 prepare_video_assets 都走这条 —— 而"没选版式"正是要在烧掉渲染
     # 积分之前拦住的东西。单版式模板不受影响,见 _check_slide_id_chosen。
     errors += _check_slide_id_chosen(dsl)
+    # 必须排在下面那批模板契约检查**之前**:模板被状态门控挡住时它们会集体空转,
+    # 于是"零错误通过"其实是"一条都没查"。见 _check_template_status_gate。
+    errors += _check_template_status_gate(dsl)
     # 同理:字段名写错同样是「渲染成功但画面是空壳」,必须在烧掉 TTS / 渲染积分
     # 之前拦住。只对声明了 slideSchemas 的模板生效,见 _check_slide_payload_fields。
     errors += _check_slide_payload_fields(dsl)
@@ -1048,10 +1084,9 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors += _check_narration_items_text_coexist(dsl)
     errors += _check_narration_language_strict(dsl)
     errors += _check_slide_id_chosen(dsl)
+    errors += _check_template_status_gate(dsl)
     errors += _check_slide_payload_fields(dsl)
     errors += _check_custom_payload_fields(dsl)
     errors += _check_line_sync_narration(dsl)
     errors += _check_slide_cross_field(dsl)
     return errors
-
-

package/skills/template-registry/video_dsl/runtime/payload_contract.py

@@ -0,0 +1,82 @@
+"""Template-declared content requirements and recursive asset references.
+
+Shared by DSL preparation and saved RenderPlan validation. Requirements use a
+small JSON Schema subset; values never appear in diagnostic messages.
+"""
+
+
+def payload_values(props: dict) -> dict:
+    """Flatten templateData wrappers, with non-null outer props taking precedence."""
+    layers, seen = [], set()
+    while isinstance(props, dict) and id(props) not in seen and len(layers) < 10:
+        layers.append(props)
+        seen.add(id(props))
+        props = props.get("templateData")
+    result = {}
+    for layer in reversed(layers):
+        result.update({k: v for k, v in layer.items() if k != "templateData" and v is not None})
+    return result
+
+
+def requirement_errors(value, schema: dict, path: str = "customPayload") -> list[str]:
+    """Enforce type/const/enum/required/properties/items/minItems/anyOf."""
+    errors = []
+    kind = schema.get("type")
+    matches = {"object": isinstance(value, dict), "array": isinstance(value, list),
+               "string": isinstance(value, str)}
+    if kind in matches and not matches[kind]:
+        return [f"{path} (expected {kind})"]
+    if "const" in schema and value != schema["const"]:
+        return [f"{path} (unexpected value)"]
+    if "enum" in schema and value not in schema["enum"]:
+        return [f"{path} (unexpected value)"]
+    if isinstance(value, dict):
+        for key in schema.get("required", []):
+            if value.get(key) is None or value.get(key) == "":
+                errors.append(f"{path}.{key} (required)")
+        for key, child in schema.get("properties", {}).items():
+            if key in value:
+                errors += requirement_errors(value[key], child, f"{path}.{key}")
+    if isinstance(value, list):
+        if len(value) < schema.get("minItems", 0):
+            errors.append(f"{path} (too few items)")
+        if "items" in schema:
+            for index, item in enumerate(value):
+                errors += requirement_errors(item, schema["items"], f"{path}[{index}]")
+    if "anyOf" in schema:
+        branches = [requirement_errors(value, branch, path) for branch in schema["anyOf"]]
+        if not branches or all(branches):
+            alternatives = " OR ".join("; ".join(branch) for branch in branches)
+            errors.append(f"{path} must satisfy one content alternative: {alternatives}")
+    return errors
+
+
+def required_payload_errors(template: dict, props: dict) -> list[str]:
+    caps = template.get("capabilities")
+    schema = caps.get("payloadRequirements") if isinstance(caps, dict) else None
+    return requirement_errors(payload_values(props), schema) if isinstance(schema, dict) else []
+
+
+def asset_references(value, path: str = "", *, bound_props: bool = False):
+    """Walk nested assetRef fields; bound props also use *AssetId names."""
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            yield from asset_references(item, f"{path}[{index}]", bound_props=bound_props)
+    elif isinstance(value, dict):
+        for key, child in value.items():
+            child_path = f"{path}.{key}" if path else key
+            if key == "assetRef" or (bound_props and key.endswith("AssetId")):
+                if isinstance(child, str) and child.strip():
+                    yield child_path, child
+            else:
+                yield from asset_references(child, child_path, bound_props=bound_props)
+
+
+def plan_asset_errors(plan: dict) -> list[str]:
+    declared = {asset.get("assetId") for asset in plan.get("resolvedAssets", []) if isinstance(asset, dict)}
+    errors = []
+    for index, row in enumerate(plan.get("timeline", [])):
+        for path, ref in asset_references(row.get("props", {}), f"timeline[{index}].props", bound_props=True):
+            if ref not in declared:
+                errors.append(f"{path} references an asset missing from resolvedAssets[]")
+    return errors

package/skills/web-read/SKILL.md

@@ -50,6 +50,10 @@ python3 <ReadScript> --url "https://example.com/article/123"
 
 Prints a Markdown document: an `# title` line, a `site · author · date · url` line, then the body. A one-line extraction diagnostic (`blocks / chars / container`) goes to **stderr**, so piping stdout gives you clean text.
 
+GitHub repository pages also include Stars / Forks / Watchers found on that page, captured before sidebar cleanup. JSON exposes them as `metadata.repository`; Markdown and plain text include a statistics line. Counts retain the page's precision (e.g. `47.2k`); missing counters are unknown, not zero.
+
+Reuse a successful read for both the script and template fields. Re-read only for a specific missing required fact, an extraction failure/truncation, or an explicit request for fresh data. Change the relevant selector/limit/wait setting for corrective reads. Do not repeatedly fetch the same page for optional popularity text: reuse returned counters or use factual non-numeric wording.
+
 ## Output formats
 
 ```bash
@@ -84,6 +88,8 @@ python3 <ReadScript> --url "https://example.com/post" --max-chars 0
 
 The container is picked by paragraph-density scoring, which is right on ordinary article/docs/blog pages and can miss on unusual layouts. In order of what to try:
 
+An explicit `--selector` opts out of boilerplate pruning inside that scope, so a sidebar, button, or counter can be read intentionally. Non-content elements such as scripts and styles are still removed.
+
 ```bash
 # 1. Content renders late (SPA): wait for the real element
 python3 <ReadScript> --url "https://app.example.com/doc/1" --wait-for-selector "article.body"

package/skills/web-read/skill.json

@@ -4,7 +4,7 @@
   "tier": "tool",
   "category": "consuming",
   "title": "Web Page Reader",
-  "description": "Open any URL in a headless browser (Playwright Python) and return the page's MAIN TEXT — title, headings, paragraphs, lists, code blocks and tables — as Markdown, plain text, or structured JSON. Boilerplate (nav / sidebar / comments / ads / footer) is stripped by a Readability-style pass, and JS-rendered pages work because a real browser runs the page. This is the tool to use whenever you need to KNOW WHAT A PAGE SAYS: summarizing an article, pulling source material for a script, reading a README or docs page, checking what a link contains. It returns text, not pictures — for a screenshot (png/jpg) use web_screenshot, for a recording (mp4/webm) use web_record. Output is capped by max_chars (default 20000) and truncated on a block boundary; pass an `output` path to keep the full text on disk.",
+  "description": "Open any URL in a headless browser (Playwright Python) and return the page's MAIN TEXT — title, headings, paragraphs, lists, code blocks and tables — as Markdown, plain text, or structured JSON. Boilerplate (nav / sidebar / comments / ads / footer) is stripped by a Readability-style pass, and JS-rendered pages work because a real browser runs the page. This is the tool to use whenever you need to KNOW WHAT A PAGE SAYS: summarizing an article, pulling source material for a script, reading a README or docs page, checking what a link contains. It returns text, not pictures — for a screenshot (png/jpg) use web_screenshot, for a recording (mp4/webm) use web_record. GitHub repository pages also return observed Stars/Forks/Watchers before sidebar cleanup (missing counters stay unknown). Reuse successful reads across script and template fields; do not repeat the same URL just for counters already returned. Output is capped by max_chars (default 20000) and truncated on a block boundary; pass an `output` path to keep the full text on disk.",
   "auth": "none",
   "envVars": [
     "WEB_CAPTURE_BROWSER",
@@ -33,7 +33,7 @@
       },
       "selector": {
         "type": "string",
-        "description": "Read only inside this CSS selector. Leave empty to auto-detect the article container — only reach for this when the auto-detected container was wrong."
+        "description": "Read only inside this CSS selector, preserving the selected region's sidebar/button text instead of pruning boilerplate. Scripts/styles are still removed. Leave empty to auto-detect the article container; use a targeted selector only for a concrete missing required fact."
       },
       "include_links": {
         "type": "boolean",

package/skills/web-screenshot/scripts/_media_screenshot/js/extract_article.js

@@ -48,6 +48,41 @@
 
   const bodyCharCount = rawLen(document.body);
 
+  // Repository counters live outside the README. Capture them before the
+  // readability pass removes forms / sidebars, without another page request.
+  // Keep GitHub's displayed precision (e.g. 47.2k); never invent missing counts.
+  const repoPath = location.pathname.replace(/\/+$/, '');
+  if (location.hostname === 'github.com' && /^\/[^/]+\/[^/]+$/.test(repoPath)) {
+    const repository = { name: repoPath.slice(1), url: `${location.origin}${repoPath}` };
+    const countPattern = /^\d[\d,.]*(?:[kmb])?$/i;
+    const links = Array.from(document.querySelectorAll('a[href]'));
+    for (const [key, suffix] of [['stars', 'stargazers'], ['forks', 'forks'], ['watchers', 'watchers']]) {
+      const candidates = links.filter((a) => {
+        try {
+          const url = new URL(a.href, location.href);
+          return url.origin === location.origin && url.pathname.replace(/\/+$/, '') === `${repoPath}/${suffix}`;
+        } catch { return false; }
+      });
+      for (const link of candidates) {
+        const exact = [link, ...link.querySelectorAll('[title]')]
+          .map((el) => squash(el.getAttribute('title'))).find((value) => countPattern.test(value));
+        const displayed = squash(link.textContent).match(/(?:^|\s)(\d[\d,.]*(?:[kmb])?)(?=\s|$)/i);
+        if (exact || displayed) {
+          repository[key] = exact || displayed[1];
+          break;
+        }
+      }
+    }
+    if (Object.keys(repository).length > 2) metadata.repository = repository;
+  }
+
+  // Resolve explicit scopes on the original DOM. A caller may intentionally
+  // request a sidebar, a button, or a node nested inside one.
+  const selected = opts.selector ? document.querySelector(opts.selector) : null;
+  if (opts.selector && !selected) {
+    return { error: 'selector-not-found', selector: opts.selector, metadata };
+  }
+
   // ── 1. strip boilerplate (structural only, see below) ────────────────────
   const JUNK_TAGS = [
     'script', 'style', 'noscript', 'template', 'svg', 'canvas', 'iframe',
@@ -65,7 +100,10 @@
     return typeof tokens === 'string' && JUNK_WORDS.test(tokens);
   };
 
-  document.querySelectorAll(JUNK_TAGS).forEach((el) => {
+  const cleanupSelector = selected
+    ? 'script,style,noscript,template,svg,canvas,iframe'
+    : JUNK_TAGS;
+  document.querySelectorAll(cleanupSelector).forEach((el) => {
     try { el.remove(); } catch (e) { /* already detached */ }
   });
 
@@ -102,10 +140,7 @@
   let containerReason = '';
 
   if (opts.selector) {
-    container = document.querySelector(opts.selector);
-    if (!container) {
-      return { error: 'selector-not-found', selector: opts.selector, metadata };
-    }
+    container = selected;
     containerReason = `selector:${opts.selector}`;
   } else {
     // Readability's scoring:每个够长的段落给自己父/祖父/曾祖父记分（1/2、1/3 衰减），
@@ -165,6 +200,7 @@
   Array.prototype.slice.call(container.querySelectorAll('div,section,ul,ol,span,header,p,figure'))
     .forEach((el) => {
       if (!container.contains(el) || el === container) return;
+      if (selected) return; // Explicit scopes opt out of boilerplate pruning.
       if (!isJunkClass(el)) return;
       if (rawLen(el) / containerChars > 0.4) return;
       try { el.remove(); } catch (e) { /* already detached */ }
@@ -328,7 +364,7 @@
     const flush = () => {
       const t = squash(buffer);
       buffer = '';
-      if (t.length >= 2) push({ type: 'paragraph', text: t });
+      if (t.length >= (selected ? 1 : 2)) push({ type: 'paragraph', text: t });
     };
     el.childNodes.forEach((child) => {
       if (child.nodeType === 3) { buffer += child.nodeValue; return; }
@@ -354,7 +390,8 @@
     flush();
   };
 
-  walk(container, 0);
+  if (EMIT.has(container.tagName)) emit(container);
+  else walk(container, 0);
 
   const charCount = blocks.reduce((n, b) => {
     if (b.type === 'list') return n + b.items.reduce((m, i) => m + i.text.length, 0);

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

@@ -150,6 +150,12 @@ def _header(data: dict, fmt: str) -> str:
         trailer.append(meta["publishedTime"])
     trailer.append(data.get("finalUrl") or meta.get("url") or "")
     lines.append(" · ".join(t for t in trailer if t))
+    repository = meta.get("repository") or {}
+    stats = [f"{label}: {repository[key]}" for key, label in
+             (("stars", "Stars"), ("forks", "Forks"), ("watchers", "Watchers"))
+             if repository.get(key) is not None]
+    if stats:
+        lines.append("GitHub repository statistics (observed on page): " + " · ".join(stats))
     return "\n".join(lines)
 
 

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

@@ -98,6 +98,9 @@ def main() -> None:
     chars = result["charCount"]
     body_chars = result["bodyCharCount"]
     status = result.get("status")
+    # A targeted read of a counter/button can legitimately be one character.
+    # Empty scopes still deserve a warning; HTTP warnings remain independent.
+    unexpectedly_short = chars < 100 and (not args.selector or chars == 0)
     if isinstance(status, int) and status >= 400:
         # 错误页也有正文（"404 Not Found"），照读不误——但不说一声的话，调用方
         # 会把一张错误页当成文章内容去写脚本。
@@ -105,14 +108,14 @@ def main() -> None:
             f"⚠️  服务器返回 HTTP {status}，下面读到的很可能是错误页而不是目标内容。",
             file=sys.stderr,
         )
-    if chars < 100 and body_chars >= 2000:
+    if unexpectedly_short and body_chars >= 2000:
         print(
             f"⚠️  整页有 {body_chars} 字符，却只抽到 {chars} 字符"
             f"（容器 {result.get('container')}）——正文容器多半没认对。"
             "可用 --selector <正文容器> 指定，或 --format json 看抽到了哪些块。",
             file=sys.stderr,
         )
-    elif chars < 100:
+    elif unexpectedly_short:
         print(
             f"⚠️  这个页面几乎没有文本（整页 {body_chars} 字符，HTTP {result.get('status')}）。"
             "多半是登录墙、反爬拦截，或正文由 JS 延迟渲染还没出来。"

package/skills/web-screenshot/version.json

@@ -2,6 +2,6 @@
   "skillName": "web-screenshot",
   "repoName": "agent-skill-media-maker",
   "skillId": "555",
-  "version": "V5",
+  "version": "V6",
   "skillDescription": "Web-page screenshot skill (still images only, png/jpg), built on Playwright Python — captures any URL to a local image file.\nSupports: full-page / viewport / element / region capture, device emulation, waiting for dynamic content, hiding or masking distracting elements, and static annotations (highlight box / arrow / caption / numbered sequence / redact / code-line highlight).\n\nImages only (`.png` / `.jpg`). For video (`.webm` / screen recording / storyboard clips) use web-record / `web_record`.\n\nUse this skill immediately whenever the user asks for any of:\n- Web page screenshot, screen capture, full-page screenshot, long screenshot\n- Capture a specific element / region, partial screenshot, focus on an area\n- Hide or mask elements before capturing (cookie banner, sensitive information)\n- Annotate a still screenshot (highlight box / arrow / label / caption bar / numbering)\n- Highlight lines L5-L20 of a file and screenshot it\n- Wait for an element to appear, then capture\n- Mobile / device-emulated screenshot (iPhone / Pixel, etc.)\n- Capture with cookies / a logged-in session / storageState\n\nEven when the user does not say \"playwright\", any request to screenshot a URL and get a local image file should route here."
 }