@remixmate/cli 0.1.0 → 0.1.2

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

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""
+template-registry CLI — list available video templates.
+
+Single source of truth: registry loading, caching and stable/beta status
+gating all live in ``registry_loader.py`` (the same module ``render-video``
+and ``gen-script`` import in-process). This entry point only adds the CLI
+surface — flag parsing, tag/aspect/language filtering, and table/JSON
+rendering — that used to be re-implemented in TypeScript
+(``src/handlers/template-bind.ts``). Deleting that handler removes the
+TS↔Python duplication; this is now the only place the list verb is realized.
+
+The DSL → TemplateBinding logic stays in ``match_template.py`` and is invoked
+in-process by ``render-video``; it is intentionally NOT exposed as a CLI verb.
+
+Flags:
+  --list-templates                 (accepted; listing is the only verb)
+  --list-examples                  list *.dsl.json / *.binding.json reference
+                                   examples grouped by templateId (consumed
+                                   by downstream agents that want to read a
+                                   template's reference shape before producing
+                                   new DSL)
+  --filter-tag <substr>            keep templates whose styleTags match
+  --filter-aspect <ratio>          keep templates supporting this aspect ratio
+  --filter-language <zh|en|...>    keep templates tagged with this content lang
+                                   (templates with no contentLanguage are kept)
+  --include-beta                   also show beta templates (else stable-only)
+  --json-output                    emit {"templates": [...]} or {"examples": [...]}
+                                   instead of a table
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+# When run as `python3 <skillDir>/scripts/list_templates.py`, this script's own
+# directory is sys.path[0], so the sibling shared modules import directly.
+from registry_loader import list_templates as load_visible_templates  # noqa: E402
+
+
+def _matches(tpl: dict, tag: str | None, aspect: str | None, language: str | None) -> bool:
+    if tag:
+        needle = tag.lower()
+        tags = [str(t).lower() for t in (tpl.get("styleTags") or [])]
+        if not any(needle in t or t in needle for t in tags):
+            return False
+    if aspect:
+        want = aspect.lower()
+        ratios = [str(r).lower() for r in (tpl.get("supportedAspectRatios") or [])]
+        if want not in ratios:
+            return False
+    if language:
+        # Unknown language (absent/empty) is never excluded by a language filter.
+        langs = [str(l).lower() for l in (tpl.get("contentLanguage") or [])]
+        if langs and language.lower() not in langs:
+            return False
+    return True
+
+
+def _status_of(tpl: dict) -> str:
+    raw = tpl.get("status")
+    if isinstance(raw, str) and raw.strip():
+        return raw.strip().lower()
+    return "stable"
+
+
+# ----- Examples discovery (--list-examples) ---------------------------------
+#
+# Examples live under <SkillDir>/video_dsl/schema/examples/ as `*.dsl.json` and
+# `*.binding.json` files. Naming convention (per gen-script SKILL.md) is
+# `<templateId>.dsl.json` / `<templateId>.binding.json`, occasionally with
+# variant suffixes (`<templateId>.<variant>.dsl.json`).
+#
+# We do not parse the JSON content here (downstream agents read the raw files
+# they care about); we just enumerate paths so the agent doesn't have to guess
+# the directory layout. When the directory does not exist (e.g. inside a slim
+# package distribution), we return an empty list — non-fatal.
+
+# Resolve the examples directory relative to this script.
+#   <skill>/scripts/list_templates.py  →  <skill>/video_dsl/schema/examples/
+_EXAMPLES_DIR = Path(__file__).resolve().parent.parent / "video_dsl" / "schema" / "examples"
+
+
+def _collect_examples() -> list[dict]:
+    if not _EXAMPLES_DIR.is_dir():
+        return []
+    by_template: dict[str, dict] = {}
+    for entry in sorted(_EXAMPLES_DIR.iterdir()):
+        if not entry.is_file():
+            continue
+        name = entry.name
+        # Recognise *.dsl.json / *.binding.json
+        if name.endswith(".dsl.json"):
+            kind = "dsl"
+            base = name[: -len(".dsl.json")]
+        elif name.endswith(".binding.json"):
+            kind = "binding"
+            base = name[: -len(".binding.json")]
+        else:
+            continue
+        # Variant: 'foo.bar.dsl.json' → templateId='foo', variant='bar'
+        if "." in base:
+            template_id, variant = base.split(".", 1)
+        else:
+            template_id, variant = base, None
+        bucket = by_template.setdefault(template_id, {"templateId": template_id, "files": []})
+        bucket["files"].append({
+            "kind": kind,
+            "variant": variant,
+            "path": str(entry.relative_to(_EXAMPLES_DIR.parent.parent.parent)),  # relative to skill dir
+            "absolutePath": str(entry),
+            "sizeBytes": entry.stat().st_size,
+        })
+    return list(by_template.values())
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        description="List available video templates from the registry.",
+    )
+    ap.add_argument("--list-templates", action="store_true",
+                    help="List every available template (the only CLI verb).")
+    ap.add_argument("--list-examples", action="store_true",
+                    help="List reference examples (*.dsl.json / *.binding.json) grouped by templateId.")
+    ap.add_argument("--filter-tag", help="Keep templates whose styleTags match this substring.")
+    ap.add_argument("--filter-aspect", help="Keep templates supporting this aspect ratio (e.g. 9:16).")
+    ap.add_argument("--filter-language", help="Keep templates tagged with this content language (zh|en|...).")
+    ap.add_argument("--include-beta", action="store_true", help="Also show beta templates (default: stable only).")
+    ap.add_argument("--json-output", action="store_true", help='Emit JSON ({"templates":[...]} or {"examples":[...]}) instead of a table.')
+    args = ap.parse_args()
+
+    # --include-beta flips registry_loader's documented status gate via env, so
+    # the CLI and in-process callers share one gating implementation.
+    if args.include_beta:
+        os.environ["ENABLE_BETA_TEMPLATES"] = "1"
+
+    # ----- examples mode -----------------------------------------------------
+    if args.list_examples:
+        examples = _collect_examples()
+        if args.json_output:
+            print(json.dumps({"examples": examples}, ensure_ascii=False))
+            return
+        if not examples:
+            print(
+                f"⚠️  No examples found under {_EXAMPLES_DIR}.\n"
+                "   This package may have shipped without reference examples; "
+                "check the cli source repo or upgrade @remixmate/cli.",
+            )
+            return
+        print(f"\n{'Template ID':<28} Files")
+        print(f"{'-' * 28} {'-' * 60}")
+        for bucket in examples:
+            tid = str(bucket["templateId"])[:28].ljust(28)
+            files = bucket["files"]
+            for i, f in enumerate(files):
+                marker = tid if i == 0 else " " * 28
+                kind = f["kind"]
+                variant = f"@{f['variant']}" if f.get("variant") else ""
+                print(f"{marker} [{kind}{variant}] {f['path']} ({f['sizeBytes']}B)")
+        print(f"\n{sum(len(b['files']) for b in examples)} example file(s) across {len(examples)} template(s)")
+        return
+
+    try:
+        templates = load_visible_templates()
+    except RuntimeError as exc:
+        print(f"❌ {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    visible = [
+        t for t in templates
+        if _matches(t, args.filter_tag, args.filter_aspect, args.filter_language)
+    ]
+
+    if args.json_output:
+        print(json.dumps({"templates": visible}, ensure_ascii=False))
+        return
+
+    if not visible:
+        print(
+            "⚠️  No templates match the current filters "
+            "(check --include-beta or relax --filter-*).",
+        )
+        return
+
+    header = (
+        f"\n{'Template ID':<22} {'Name':<18} {'Aspect':<12} "
+        f"{'Lang':<8} {'Status':<8} Tags / LLM hint"
+    )
+    print(header)
+    print(
+        f"{'-' * 22} {'-' * 18} {'-' * 12} {'-' * 8} {'-' * 8} {'-' * 60}"
+    )
+    for tpl in visible:
+        tid = str(tpl.get("templateId", ""))[:22].ljust(22)
+        name = str(tpl.get("name", ""))[:18].ljust(18)
+        ratios = ",".join(tpl.get("supportedAspectRatios") or [])[:12].ljust(12)
+        lang = (",".join(tpl.get("contentLanguage") or []) or "-")[:8].ljust(8)
+        status = _status_of(tpl).ljust(8)
+        tags = ", ".join((tpl.get("styleTags") or [])[:5])
+        print(f"{tid} {name} {ratios} {lang} {status} {tags}")
+        hint = tpl.get("llmHint")
+        if hint:
+            hint = hint if len(hint) <= 200 else hint[:197] + "..."
+            print(f"{' ' * 22}   ↳ {hint}")
+
+    print(f"\n{len(visible)} template(s) shown")
+
+
+if __name__ == "__main__":
+    main()

package/skills/{template-bind → template-registry}/scripts/match_template.py

@@ -1,10 +1,11 @@
 """
-template-bind 库模块 — DSL → TemplateBinding 的纯函数实现。
+template-registry 库模块 — DSL → TemplateBinding 的纯函数实现。
 
 仅作为 Python library 被 render-video 的 render_video.py / gen-script 的
 gen_script.py 通过 `sys.path.insert` 后 `import match_template` 引入；
-对外不再暴露 CLI（template-bind skill 已迁移到 ab-skill CLI 的 builtin
-handler，由 src/handlers/template-bind.ts 处理 --list-templates）。
+对外不暴露 binding CLI。template-registry skill 的 `--list-templates` 入口由
+sibling 的 `list_templates.py` 实现（它复用 registry_loader 的统一加载 +
+状态门控），两者共享同一份 registry 读取逻辑，无 TS 侧重复实现。
 
 提供的公共接口：
   load_registry()                 → list[dict]   模板列表

package/skills/{template-bind → template-registry}/scripts/registry_loader.py

@@ -3,7 +3,7 @@
 模板 registry 加载器 - 统一抽象本地文件 / HTTP API 两种数据源。
 
 为什么独立成一个模块：
-  template-bind、render-video 等多个 skill 都要读 registry，集中在一处便于：
+  template-registry、render-video 等多个 skill 都要读 registry，集中在一处便于：
     - 缓存策略一致（HTTP 拉取 5 分钟 TTL + ETag 复用）
     - 解析顺序一致（环境变量 → 本地文件 → monorepo 回退）
     - 错误降级一致（HTTP 故障时复用上一次缓存）

package/skills/{template-bind → template-registry}/scripts/template_paths.py

@@ -6,9 +6,9 @@ Before this file landed, every caller that needed to reach into the
 monorepo's ``template-library/`` from inside ``apps/ab-skill/`` had to count
 ``..`` segments by hand. The depth differs per call site:
 
-    skills/template-bind/scripts/registry_loader.py        → 5 × ".."
-    skills/template-bind/scripts/check_contracts.py        → 3 × ".."
-    skills/template-bind/video_dsl/runtime/template_binder → 6 × ".."
+    skills/template-registry/scripts/registry_loader.py    → 5 × ".."
+    skills/template-registry/scripts/check_contracts.py    → 3 × ".."
+    skills/template-registry/video_dsl/runtime/template_binder → 6 × ".."
     skills/gen-script/scripts/gen_script.py                → 5 × ".."
     skills/render-video/scripts/render_video.py            → 4 × ".."
 
@@ -17,9 +17,9 @@ move silently breaks one site without touching the others. This module
 computes the monorepo root **once** from its own location and exposes
 helpers so callers no longer count.
 
-All sibling skills now go through these helpers; the TS handler in
-``src/handlers/template-bind.ts`` keeps its own one-off computation
-because it cannot import this Python module.
+All sibling skills (including the ``list_templates.py`` CLI entry, via
+``registry_loader``) go through these helpers, so the monorepo-root
+computation lives in exactly one place.
 """
 from __future__ import annotations
 
@@ -29,7 +29,7 @@ from typing import Optional
 __all__ = ["monorepo_root", "monorepo_registry_path", "monorepo_template_src_dir"]
 
 # This file lives at:
-#   <repo>/apps/ab-skill/skills/template-bind/scripts/template_paths.py
+#   <repo>/apps/ab-skill/skills/template-registry/scripts/template_paths.py
 # So the monorepo root is 5 levels up.
 _HERE = os.path.dirname(os.path.abspath(__file__))
 _REPO_ROOT = os.path.normpath(os.path.join(_HERE, "..", "..", "..", "..", ".."))

package/skills/{template-bind → template-registry}/skill.json

@@ -1,19 +1,22 @@
 {
-  "name": "template-bind",
-  "toolName": "template_bind",
+  "name": "template-registry",
+  "toolName": "template_registry",
   "tier": "orchestration",
-  "title": "Template Registry (List-only)",
+  "category": "authoring",
+  "title": "Video Template Registry",
   "description": "List all available video templates (templateId / name / aspect ratio / style tags). Template-to-DSL binding is no longer exposed as a separate step — once prepare_video_assets receives a template_id it runs the full DSL→RenderPlan pipeline internally.",
   "envVars": ["PRIV_TOKEN", "VIDEO_TEMPLATE_REGISTRY", "VIDEO_TEMPLATE_REGISTRY_URL", "VIDEO_TEMPLATE_REGISTRY_HTTP_METHOD"],
-  "entry": { "type": "builtin", "handler": "template-bind" },
+  "entry": { "type": "python", "scriptPath": "scripts/list_templates.py" },
   "parameters": {
     "type": "object",
     "properties": {
       "list_templates": { "type": "boolean", "description": "List available templates (default behavior; also implied when other flags are passed)." },
+      "list_examples": { "type": "boolean", "description": "List the *.dsl.json / *.binding.json reference examples shipped under template-registry/video_dsl/schema/examples/, grouped by templateId. Useful for downstream agents (e.g. a creation agent) that want to read a template's reference shape before producing new DSL." },
       "filter_tag": { "type": "string", "description": "Show only templates whose styleTags contain (or are contained in) this string. Case-insensitive. E.g. 'tech' / '科普' / 'walkthrough'." },
       "filter_aspect": { "type": "string", "description": "Show only templates that declare this aspect ratio. E.g. '9:16' / '16:9' / '1:1'." },
       "filter_language": { "type": "string", "description": "Show only templates whose contentLanguage includes this code ('zh' or 'en'). Templates with no declared language are always shown (treated as language-agnostic)." },
-      "include_beta": { "type": "boolean", "description": "Also list templates with status='beta'. Default off (only 'stable' shows). The ENABLE_BETA_TEMPLATES env var has the same effect process-wide." }
+      "include_beta": { "type": "boolean", "description": "Also list templates with status='beta'. Default off (only 'stable' shows). The ENABLE_BETA_TEMPLATES env var has the same effect process-wide." },
+      "json_output": { "type": "boolean", "description": "Emit a JSON result ({ templates: [...] } or { examples: [...] }) instead of the human-readable table." }
     },
     "required": []
   }

package/skills/template-registry/version.json

@@ -0,0 +1,7 @@
+{
+  "skillName": "template-registry",
+  "repoName": "agent-skill-media-maker",
+  "skillId": "475",
+  "version": "V12",
+  "skillDescription": "视频模板仓库（列表查询）。存储所有视频模板定义，对外只暴露「列出可用模板」一个能力；DSL→TemplateBinding 的绑定逻辑已内嵌进 prepare-video-assets，不再作为独立步骤暴露。同时是跨 skill 共享 Python 库（registry_loader / match_template / template_paths / video_dsl 等）的存放位置。\n\n当用户提到以下任何需求时，立即使用本 skill：\n- 查看可用模板、列出所有模板"
+}

package/skills/{template-bind → template-registry}/video_dsl/README.md

@@ -47,7 +47,7 @@ video_dsl/
 ```
 主题 → [gen-script] → Video DSL
                           ↓
-                   [template-bind] → TemplateBinding
+                   [template-registry] → TemplateBinding
                           ↓
                    [render-video] → RenderPlan → MP4 / 剪映草稿
 ```
@@ -67,7 +67,7 @@ video_dsl/
 | 模块 | 职责 | 被谁调用 |
 |------|------|----------|
 | `dsl_validator.py` | DSL JSON Schema 校验与参数标准化 | gen-script、render-video |
-| `template_binder.py` | 将 DSL scene 映射到模板 slot，生成 TemplateBinding（从 @ab-templates/metadata 读取模板定义） | template-bind |
+| `template_binder.py` | 将 DSL scene 映射到模板 slot，生成 TemplateBinding（从 @ab-templates/metadata 读取模板定义） | template-registry |
 | `timeline_compiler.py` | 帧号计算、字幕切片（`split_subtitle`）、旁白分段（`segment_narration`） | render-video（跨 skill import） |
 | `asset_adapter.py` | 素材格式适配 | render-video |
 | `prompt_enhancer.py` | 图片 prompt 增强 | render-video |

package/skills/{template-bind → template-registry}/video_dsl/runtime/__init__.py

@@ -1,7 +1,7 @@
 """Package marker for ``video_dsl.runtime`` — kept intentionally empty.
 
 This file exists so ``from video_dsl.runtime.<mod> import …`` resolves when
-``skills/template-bind/`` is on sys.path (the pattern used by render-video
+``skills/template-registry/`` is on sys.path (the pattern used by render-video
 and gen-script). Public modules:
 
     - timeline_compiler  : DSL → Remotion frame-axis timeline + subtitle splits

package/skills/video-parser/SKILL.md

@@ -17,222 +17,109 @@ triggers:
 
 # Video Deconstruction Skill
 
-Splits a video into reusable content assets — audio, ASR transcript (with per-word timestamps), scene cuts, keyframe images. Emits a structured asset-manifest JSON.
+Splits a video into reusable content assets — audio, ASR transcript (with per-word timestamps), scene cuts, keyframe images — and returns a structured asset-manifest JSON.
 
-## Dependencies
-
-- **ffmpeg**: must be installed locally (`brew install ffmpeg`) — used for audio extraction, scene-change detection, and keyframe capture.
-- **Python 3**: standard library only, no third-party dependencies.
+The skill entry (`scripts/parse_via_render.py`) runs the deconstruction **through the ab-render HTTP service** (`POST /parse` → poll `POST /parseStatus`). It needs **no local ffmpeg** — the heavy lifting happens server-side and the manifest (with cloud-hosted asset URLs) comes back as JSON on stdout.
 
 ## Authentication & environment
 
-There is no dedicated env file; the **process environment** variables of the caller apply. Examples use `python`; on macOS without that alias use `python3`.
+No skill-local env file — the executing process inherits the system environment.
 
-- **Enterprise OpenClaw**: auth is injected, **no** `PRIV_TOKEN` / `--priv-token` needed.
-- **Other environments**: configure a token — obtain a `PRIV_TOKEN` from your ab-api service. Non-interactive invocations may fail when the token is missing; interactive runs prompt for one.
+- **Enterprise OpenClaw**: auth + service address are injected; nothing to configure.
+- **Other environments**: set `RENDER_API_URL` (the ab-render service) and `PRIV_TOKEN`. Without them the run fails fast with an actionable message.
 
 | Env var | Description | Default |
 |---------|-------------|---------|
-| `PRIV_TOKEN` | Tianyan token; overridable with `--priv-token`. | (none) |
-| `MM_API_BASE_URL` | API root URL. | `http://localhost:3001/api` |
-| `AGENT_NAME` | Optional, sent as the `x-invoke-agent` request header. | (none) |
+| `RENDER_API_URL` | ab-render service base URL (e.g. `http://localhost:3000`). Required. | (none) |
+| `PRIV_TOKEN` | Tianyan token, sent as `X-Priv-Token`. | (none) |
+| `CONVERSATION_ID` | Optional, sent as `x-conversation-id` for file association. | (none) |
 
 ## Steps
 
-1. **Script path**: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. Every command below uses `<SkillDir>/scripts/deconstruct_video.py`; never hard-code paths.
-2. **Confirm ffmpeg**: run `ffmpeg -version` to confirm it is installed locally.
-3. **Pick the input**: either a direct video URL or a local file path (one of the two).
-4. **Run the deconstruction**: invoke the script and wait for it to finish.
-5. **Inspect the result**: check `deconstruction.json`, `audio.mp3`, and the `keyframes/` directory in the output folder.
+1. **Script path**: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. The entry is always `<SkillDir>/scripts/parse_via_render.py`; never hard-code paths.
+2. **Provide a direct video URL** (`--url`). Page links (Douyin / Xiaohongshu share pages) are not supported — pass a direct video file URL.
+3. **Run and wait**: the script submits the task and polls until it finishes (up to ~10 minutes), printing progress lines.
+4. **Consume the result**: a JSON asset-manifest is printed to stdout (audio / ASR / scenes / keyframes, with cloud URLs). Save or pipe it as needed.
 
-### Deconstruct from a URL
+### Deconstruct a video
 
 ```bash
-python3 <SkillDir>/scripts/deconstruct_video.py \
-  --url "https://example.com/video.mp4" \
-  --output-dir ./output_deconstructed
-```
-
-### Deconstruct from a local file
-
-```bash
-python3 <SkillDir>/scripts/deconstruct_video.py \
-  --local /path/to/video.mp4 \
-  --output-dir ./output_deconstructed
+python3 <SkillDir>/scripts/parse_via_render.py \
+  --url "https://example.com/video.mp4"
 ```
 
 ### Custom scene-change threshold
 
 ```bash
-python3 <SkillDir>/scripts/deconstruct_video.py \
+python3 <SkillDir>/scripts/parse_via_render.py \
   --url "https://example.com/video.mp4" \
   --scene-threshold 0.4
 ```
 
-Lower values are more sensitive (more cuts), higher values are looser (fewer cuts). Default is 0.3.
+Lower values are more sensitive (more cuts), higher values looser (fewer cuts). Default `0.3`.
 
-### Audio + ASR only (skip keyframes)
+### Skip ASR or keyframes
 
 ```bash
-python3 <SkillDir>/scripts/deconstruct_video.py \
-  --url "https://example.com/video.mp4" \
-  --skip-keyframes
-```
-
-### Keyframes only (skip ASR)
+# audio + scenes only (skip keyframes)
+python3 <SkillDir>/scripts/parse_via_render.py --url "https://example.com/video.mp4" --skip-keyframes
 
-```bash
-python3 <SkillDir>/scripts/deconstruct_video.py \
-  --url "https://example.com/video.mp4" \
-  --skip-asr
+# keyframes + scenes only (skip ASR)
+python3 <SkillDir>/scripts/parse_via_render.py --url "https://example.com/video.mp4" --skip-asr
 ```
 
 ### JSON pipeline mode
 
 ```bash
-python3 <SkillDir>/scripts/deconstruct_video.py \
+python3 <SkillDir>/scripts/parse_via_render.py \
   --url "https://example.com/video.mp4" \
   --json-output
 ```
 
-Prints only the final `deconstruction.json` payload to stdout — no progress lines — suitable for piping.
-
-See every option: `python3 <SkillDir>/scripts/deconstruct_video.py --help`.
+Prints only the final manifest JSON to stdout — no progress lines — suitable for piping into downstream tools.
 
 ## Common CLI flags
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--url` | Remote video URL (mutually exclusive with `--local`). | — |
-| `--local` | Local video path (mutually exclusive with `--url`). | — |
-| `-o` / `--output-dir` | Output directory. | `./deconstructed_<timestamp>` |
-| `--scene-threshold` | Scene-change threshold 0.0–1.0. | `0.3` |
-| `--private-token` | Override `privateToken`. | env var |
-| `--json-output` | Pipeline mode — JSON-only stdout. | off |
+| `--url` | Direct remote video URL (required). | — |
+| `--scene-threshold` | Scene-change sensitivity 0.0–1.0. | `0.3` |
 | `--skip-asr` | Skip the ASR step. | off |
 | `--skip-keyframes` | Skip the keyframe-extraction step. | off |
+| `--json-output` | Pipeline mode — JSON-only stdout. | off |
 
-## Output layout
-
-The script writes the following under `--output-dir`:
-
-```
-<output-dir>/
-├── audio.mp3              # Extracted audio file
-├── deconstruction.json    # Asset-manifest JSON
-└── keyframes/             # Keyframe images
-    ├── frame_001.jpg
-    ├── frame_002.jpg
-    └── ...
-```
+## Result manifest shape
 
-### `deconstruction.json` shape
+`parse_via_render.py` prints the service's `result` payload — a structured manifest whose top-level fields are:
 
 ```json
 {
-  "source": {
-    "url": "original URL (if any)",
-    "localPath": "local video path",
-    "durationMs": 12345
-  },
-  "audio": {
-    "localPath": "output_dir/audio.mp3",
-    "url": "uploaded OSS URL"
-  },
-  "asr": {
-    "text": "full recognized transcript",
-    "duration": 3816,
-    "utterances": [
-      {
-        "text": "per-utterance text",
-        "startTime": 0,
-        "endTime": 1000,
-        "words": [...]
-      }
-    ]
-  },
-  "scenes": [
-    {
-      "index": 0,
-      "startTimeSec": 0.0,
-      "endTimeSec": 3.5,
-      "keyframe": "keyframes/frame_001.jpg"
-    }
-  ],
-  "keyframes": [
-    {
-      "index": 0,
-      "timestampSec": 0.0,
-      "localPath": "keyframes/frame_001.jpg"
-    }
-  ]
+  "source":   { "url": "original URL", "durationMs": 12345 },
+  "audio":    { "url": "cloud audio URL" },
+  "asr":      { "text": "full transcript", "utterances": [ { "text": "...", "startTime": 0, "endTime": 1000, "words": [] } ] },
+  "scenes":   [ { "index": 0, "startTimeSec": 0.0, "endTimeSec": 3.5, "keyframe": "cloud keyframe URL" } ],
+  "keyframes":[ { "index": 0, "timestampSec": 0.0, "url": "cloud keyframe URL" } ]
 }
 ```
 
-## Deconstruction → structural analysis
-
-Reads the deconstruction artifacts and extracts hook, narrative structure, copy pacing, scene composition, etc., emitting a structured analysis report. Script path: `<SkillDir>/scripts/analyze_video.py`.
-
-The analysis report can be used to:
-- Feed an AI to write a new script with the same structure.
-- Guide a human re-creator to replicate the video's rhythm.
-- Inform downstream template development.
+(Exact fields are defined by the ab-render service; treat the above as representative.)
 
-### Basic usage
+## Optional local tools (not the skill entry)
 
-```bash
-python3 <SkillDir>/scripts/analyze_video.py \
-  -i ./output/deconstructed_xxx/deconstruction.json
-```
-
-### Specify the output directory
-
-```bash
-python3 <SkillDir>/scripts/analyze_video.py \
-  -i ./output/deconstructed_xxx/ \
-  -o ./reports/
-```
+Two extra scripts ship alongside the entry for local / offline use. They are **not** invoked by the `video_parser` tool and are **not** the skill entry — call them directly with `python3` only when you specifically need local processing:
 
-### Pipeline mode
+- **`scripts/deconstruct_video.py`** — a fully local deconstruction alternative that **requires ffmpeg** (`brew install ffmpeg`) and writes `audio.mp3` + `keyframes/` + `deconstruction.json` to an `--output-dir`. Use when there is no ab-render service available. Flags: `--url` / `--local`, `-o/--output-dir`, `--scene-threshold`, `--skip-asr`, `--skip-keyframes`, `--json-output`.
+- **`scripts/analyze_video.py`** — a second stage that reads a `deconstruction.json` (or the manifest above saved to disk) and emits a structural-analysis report (hook, narrative structure, pacing, CTA, …). Flags: `-i/--input`, `-o/--output-dir`, `--json-output`.
 
-```bash
-python3 <SkillDir>/scripts/analyze_video.py \
-  -i ./output/deconstructed_xxx/ \
-  --json-output
-```
-
-Prints only the `analysis.json` payload to stdout, no progress text, suitable for piping.
-
-### analyze_video.py flags
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `-i` / `--input` | Path to `deconstruction.json` or its parent directory. | required |
-| `-o` / `--output-dir` | Output directory. | same as input |
-| `--json-output` | Pipeline mode (JSON-only stdout). | off |
-
-### Output files
-
-`analysis.json`: the structured analysis report. Covers the following dimensions:
-
-| Field | Description |
-|-------|-------------|
-| `source` | Original video information (URL, duration). |
-| `overview` | Language, scene count, copy length, asset types. |
-| `hook` | Opening-hook text, duration, strategy classification. |
-| `narrativeStructure` | Per-scene narrative structure (role, duration share, text density). |
-| `pacing` | Pacing analysis (scene-duration distribution, rhythm type). |
-| `textStructure` | Copy structure (speaking rate, silent gaps, keywords). |
-| `audioPattern` | Audio pattern (speech vs. silence ratio). |
-| `cta` | CTA detection (closing copy, whether an explicit CTA exists). |
-| `assets` | Asset manifest (audio, keyframes). |
+  ```bash
+  python3 <SkillDir>/scripts/analyze_video.py -i ./deconstruction.json
+  ```
 
 ## Error handling
 
-- **ffmpeg not installed**: the script detects this and prompts `brew install ffmpeg`.
-- **401 / token missing** (non-OpenClaw): check or set the token via the Feishu link above.
+- **`RENDER_API_URL` not configured**: the script exits with a clear message; set the ab-render service URL.
+- **401 / token missing** (non-OpenClaw): set `PRIV_TOKEN`.
 - **Business `code != 0`**: read the `msg` printed on stderr.
-- **Video download failed**: confirm the URL is a direct video link (page links such as Douyin / Xiaohongshu are not supported).
-- **ASR timeout**: large files can take a while; the script defaults to a 300-second timeout.
-- **No scene change detected**: too-high threshold can yield zero cuts — try lowering `--scene-threshold`.
-- **Network**: check connectivity and `MM_API_BASE_URL`.
+- **Video download failed**: confirm the URL is a direct video link (share/page links are not supported).
+- **Timeout**: very long videos may exceed the ~10-minute poll window; retry or pre-trim.
+- **No scene change detected**: a too-high threshold yields zero cuts — lower `--scene-threshold`.

package/skills/video-parser/skill.json

@@ -2,20 +2,20 @@
   "name": "video-parser",
   "toolName": "video_parser",
   "tier": "tool",
+  "category": "consuming",
   "title": "Video Deconstruction",
   "description": "Video deconstruction: split a video into reusable assets (audio extraction, ASR transcript, keyframe extraction, scene segmentation).",
-  "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME", "RENDER_API_URL"],
+  "envVars": ["RENDER_API_URL", "PRIV_TOKEN", "CONVERSATION_ID"],
   "scriptPath": "scripts/parse_via_render.py",
   "parameters": {
     "type": "object",
     "properties": {
-      "url": { "type": "string", "description": "Remote video URL (or use local)" },
-      "local": { "type": "string", "description": "Local video path (or use url)" },
+      "url": { "type": "string", "description": "Direct remote video URL (required). Share/page links are not supported." },
       "scene_threshold": { "type": "number", "description": "Scene-cut detection threshold 0.0-1.0 (default 0.3)" },
       "skip_asr": { "type": "boolean", "description": "Skip the ASR step" },
       "skip_keyframes": { "type": "boolean", "description": "Skip the keyframe-extraction step" },
       "json_output": { "type": "boolean", "description": "Pipeline mode — emit JSON only on stdout" }
     },
-    "required": []
+    "required": ["url"]
   }
 }