@remixmate/cli 0.9.11 → 0.9.13

package/README.md

@@ -94,7 +94,7 @@ cp .env.example .env
 source .env
 ```
 
-Python skills (6 of 11) require `python3 >= 3.10`. `web-capture` requires Playwright (auto-installs chromium on first run). `ffmpeg` is only needed for `video-parser`'s optional local tool (`deconstruct_video.py`); the default `video-parser` entry runs server-side via ab-render and needs no local ffmpeg.
+Python skills (8 of 12) require `python3 >= 3.10`. `web-screenshot` / `web-record` require Playwright (auto-installs chromium on first run). `ffmpeg` is only needed for `video-parser`'s optional local tool (`deconstruct_video.py`); the default `video-parser` entry runs server-side via ab-render and needs no local ffmpeg.
 
 ## Skills
 
@@ -119,7 +119,8 @@ This project contains 11 AI media generation skills covering the full pipeline f
 ├─────────────────────────────────────────────────────────────┤
 │ Tool Skills                                                  │
 │  video-parser      Video deconstruction (audio / ASR / kf)  │
-│  web-capture       Web page screenshot / scroll-record      │
+│  web-screenshot    Web page screenshot (png / jpg)          │
+│  web-record        Web page recording / storyboard video    │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -140,7 +141,8 @@ This project contains 11 AI media generation skills covering the full pipeline f
 │   ├── render-video/           # orchestration: Phase 3 Remotion render (canonical render_video.py)
 │   ├── export-jianying/        # orchestration: export Jianying draft ZIP
 │   ├── video-parser/           # tool: video deconstruction & analysis
-│   └── web-capture/            # tool: headless-browser screenshot / recording
+│   ├── web-screenshot/         # tool: headless-browser screenshot (also hosts record.py)
+│   └── web-record/             # tool: headless-browser recording (entry -> web-screenshot/scripts/record.py)
 └── README.md
 ```
 
@@ -158,7 +160,8 @@ This project contains 11 AI media generation skills covering the full pipeline f
 | render-video | orchestration | job_id → Remotion render → upload | python `scripts/render_video.py` |
 | export-jianying | orchestration | Asset URLs → Jianying draft ZIP (auto-converts from RenderPlan) | python `scripts/gen_jianying_draft.py` |
 | video-parser | tool | Video → audio + ASR + keyframes + scene segmentation | python `scripts/parse_via_render.py` |
-| web-capture | tool | Web page screenshot / scroll-record / storyboard video | python `scripts/screenshot.py`, `scripts/record.py` |
+| web-screenshot | tool | Web page screenshot (png / jpg) | python `scripts/screenshot.py` |
+| web-record | tool | Web page recording / scroll-through / storyboard video (webm -> mp4 -> VOD) | python `../web-screenshot/scripts/record.py` |
 
 ### Core workflows
 
@@ -217,7 +220,8 @@ remixmate prepare-video-assets --help
 remixmate render-video --help
 remixmate export-jianying --help
 remixmate video-parser --help
-remixmate web-capture --help
+remixmate web-screenshot --help
+remixmate web-record --help
 remixmate template-registry --help
 
 # http skills (gen-image, gen-video, gen-voice, gen-digital-human) take no

package/README.zh-CN.md

@@ -70,11 +70,11 @@ cp .env.example .env
 source .env
 ```
 
-Python 技能（11 个中的 6 个）需要 `python3 >= 3.10`。`web-capture` 需要 Playwright（首次运行自动安装 chromium）。`ffmpeg` 仅 `video-parser` 的可选本地工具（`deconstruct_video.py`）需要；`video-parser` 默认入口走 ab-render 服务端解构，无需本地 ffmpeg。
+Python 技能（12 个中的 8 个）需要 `python3 >= 3.10`。`web-screenshot` / `web-record` 需要 Playwright（首次运行自动安装 chromium）。`ffmpeg` 仅 `video-parser` 的可选本地工具（`deconstruct_video.py`）需要；`video-parser` 默认入口走 ab-render 服务端解构，无需本地 ffmpeg。
 
 ## 技能
 
-本项目包含 11 个 AI 媒体生成技能，覆盖从素材生成、脚本编排、模板绑定、视频渲染到剪映导出的完整视频内容生产链路。
+本项目包含 12 个 AI 媒体生成技能，覆盖从素材生成、脚本编排、模板绑定、视频渲染到剪映导出的完整视频内容生产链路。
 
 ### 技能分层
 
@@ -95,7 +95,8 @@ Python 技能（11 个中的 6 个）需要 `python3 >= 3.10`。`web-capture`
 ├─────────────────────────────────────────────────────────────┤
 │ 工具层 Skills                                                │
 │  video-parser      视频解构（音频提取 / ASR / 关键帧）       │
-│  web-capture       网页截图 / 滚动录屏 / 分镜视频            │
+│  web-screenshot    网页截图（png / jpg）                     │
+│  web-record        网页录屏 / 滚动录屏 / 分镜视频            │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -116,7 +117,8 @@ Python 技能（11 个中的 6 个）需要 `python3 >= 3.10`。`web-capture`
 │   ├── render-video/           # 编排: Phase 3 Remotion 渲染（含 render_video.py 实现）
 │   ├── export-jianying/        # 编排: 导出剪映草稿 ZIP
 │   ├── video-parser/           # 工具: 视频解构与分析
-│   └── web-capture/            # 工具: 无头浏览器截图 / 录屏
+│   ├── web-screenshot/         # 工具: 无头浏览器截图（record.py 也放在这里）
+│   └── web-record/             # 工具: 无头浏览器录屏（入口指向 web-screenshot/scripts/record.py）
 └── README.md
 ```
 
@@ -134,7 +136,8 @@ Python 技能（11 个中的 6 个）需要 `python3 >= 3.10`。`web-capture`
 | render-video | 编排 | job_id → Remotion 渲染 → 上传 | python `scripts/render_video.py` |
 | export-jianying | 编排 | 素材 URL → 剪映草稿 ZIP（支持从 RenderPlan 自动转换） | python `scripts/gen_jianying_draft.py` |
 | video-parser | 工具 | 视频 → 音频 + ASR + 关键帧 + 场景分段 | python `scripts/parse_via_render.py` |
-| web-capture | 工具 | 网页截图 / 滚动录屏 / 分镜视频 | python `scripts/screenshot.py`、`scripts/record.py` |
+| web-screenshot | 工具 | 网页截图（png / jpg） | python `scripts/screenshot.py` |
+| web-record | 工具 | 网页录屏 / 滚动录屏 / 分镜视频（webm → mp4 → VOD） | python `../web-screenshot/scripts/record.py` |
 
 ### 核心链路
 
@@ -170,7 +173,8 @@ remixmate prepare-video-assets --help
 remixmate render-video --help
 remixmate export-jianying --help
 remixmate video-parser --help
-remixmate web-capture --help
+remixmate web-screenshot --help
+remixmate web-record --help
 remixmate template-registry --help
 
 # http 技能（gen-image、gen-video、gen-voice、gen-digital-human）没有

package/dist/cli.js

@@ -33,7 +33,10 @@ function resolveBaseDir() {
 }
 function describeEntryTail(s) {
     if (s.entry.type === 'python') {
-        return `(scripts/${s.entry.scriptPath.replace(/^scripts\//, '')})`;
+        // scriptPath 可以指向别的 skill 目录（如 web-record → ../web-screenshot/…），
+        // 这种相对路径原样打印，只给同目录脚本补上 scripts/ 前缀。
+        const p = s.entry.scriptPath;
+        return `(${p.startsWith('.') ? p : `scripts/${p.replace(/^scripts\//, '')}`})`;
     }
     return `[${s.entry.handler}]`;
 }

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.11",
-  "generatedAt": "2026-07-27T06:23:26.117Z",
+  "version": "0.9.13",
+  "generatedAt": "2026-08-12T07:37:17.101Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -241,25 +241,21 @@
       ]
     },
     {
-      "id": "web-capture",
+      "id": "web-record",
       "tier": "tool",
       "category": "consuming",
-      "title": "Web Page Capture",
-      "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.",
+      "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_screenshot 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": [
-        "网页截图、网页截屏、整页截图、长截图、full page screenshot",
-        "截某个元素 / 区域、局部截屏、focus 某个区域",
-        "录屏、网页录制、录制视频、录一段操作、生成 webm",
+        "录屏、网页录制、录制视频、录一段操作、生成 webm、screencast",
         "滚动录屏、页面从头划到尾的视频",
         "多场景视频、分镜视频、storyboard、按时间线编排",
         "演示点击 / 输入 / 悬停（虚拟鼠标 + 涟漪 / 打字机 / 触发 tooltip）",
-        "加箭头、加字幕条、加标题卡 / 片头片尾、按顺序编号高亮多个区域",
-        "截图前隐藏元素 / 涂盖打码、给静态截图加注释（红框 / 箭头 / 标签）",
-        "移动端 / 设备模拟、带 cookie / 登录态截屏 / 录屏"
+        "模板视频一行出片、按顺序编号高亮多个区域并录制"
       ],
       "entry": {
         "type": "python",
-        "scriptPath": "scripts/screenshot.py"
+        "scriptPath": "../web-screenshot/scripts/record.py"
       },
       "runtime": "python",
       "envVars": [
@@ -267,25 +263,27 @@
         "WEB_CAPTURE_OUTPUT_BASE",
         "WEB_CAPTURE_NO_SANDBOX",
         "WEB_CAPTURE_ALLOW_PRIVATE_HOSTS",
-        "PLAYWRIGHT_BROWSERS_PATH"
+        "PLAYWRIGHT_BROWSERS_PATH",
+        "REMOTION_RENDER_API_URL",
+        "PRIV_TOKEN"
       ]
     },
     {
-      "id": "web-record",
+      "id": "web-screenshot",
       "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.",
+      "title": "Web Page Screenshot",
+      "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": [
-        "录屏、网页录制、录制视频、录一段操作、生成 webm、screencast",
-        "滚动录屏、页面从头划到尾的视频",
-        "多场景视频、分镜视频、storyboard、按时间线编排",
-        "演示点击 / 输入 / 悬停（虚拟鼠标 + 涟漪 / 打字机 / 触发 tooltip）",
-        "模板视频一行出片、按顺序编号高亮多个区域并录制"
+        "网页截图、网页截屏、整页截图、长截图、full page screenshot",
+        "截某个元素 / 区域、局部截屏、focus 某个区域",
+        "截图前隐藏元素 / 涂盖打码、给静态截图加注释（红框 / 箭头 / 标签）",
+        "高亮某文件的 L5-L20 代码行并截图",
+        "移动端 / 设备模拟截图、带 cookie / 登录态截图"
       ],
       "entry": {
         "type": "python",
-        "scriptPath": "../web-capture/scripts/record.py"
+        "scriptPath": "scripts/screenshot.py"
       },
       "runtime": "python",
       "envVars": [
@@ -293,9 +291,7 @@
         "WEB_CAPTURE_OUTPUT_BASE",
         "WEB_CAPTURE_NO_SANDBOX",
         "WEB_CAPTURE_ALLOW_PRIVATE_HOSTS",
-        "PLAYWRIGHT_BROWSERS_PATH",
-        "REMOTION_RENDER_API_URL",
-        "PRIV_TOKEN"
+        "PLAYWRIGHT_BROWSERS_PATH"
       ]
     }
   ]

package/dist/skill-schema.d.ts

@@ -27,7 +27,7 @@ export type SkillEntry = {
  * - "authoring": 创建 / 编辑模板期间使用，例如 template-registry / gen-script /
  *                render-video（用于 try_render） / prepare-video-assets。
  * - "consuming": 消费已有模板生成媒体，例如 export-jianying / video-parser /
- *                web-capture（与"创建模板"无关，是消费侧场景）。
+ *                web-screenshot / web-record（与"创建模板"无关，是消费侧场景）。
  * - "asset":     生成单一类型素材的原子 skill：gen-image / gen-voice /
  *                gen-video / gen-digital-human。authoring 也会用，但通过 stub
  *                方式占位；consuming 场景下是真调用。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.11",
-  "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.",
+  "version": "0.9.13",
+  "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",
   "types": "dist/index.d.ts",

package/skills/gen-script/SKILL.md

@@ -9,6 +9,8 @@ description: |
   - Turn a topic into a video structure / video content plan
 
   Even when the user does not say "generate the DSL", use this skill whenever they want to turn a topic into a structured video plan.
+
+  ⚠️ 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.
 triggers:
   - Write a video script, generate a video script, plan a video, write storyboards
   - Create a short video, plan video content, generate a Video DSL
@@ -19,6 +21,13 @@ triggers:
 
 Turns a user-supplied **topic** into a **Video DSL v1alpha1** JSON describing what the final video should look like (scene structure, asset requirements, narration text, visual layout). It never produces any asset itself.
 
+> ⚠️ **Stop-and-confirm gate (mandatory, do not skip).**
+> This skill produces a *draft* for the user to review, not an input to chain onward automatically.
+> After it returns, show the full script and **stop your turn** — wait for the user to explicitly confirm.
+> **Never** call `prepare_video_assets` in the same turn as `gen_script`: asset generation spends
+> image and TTS credits that cannot be refunded, and a wrong narration line means paying for the
+> whole batch twice. See **"Agent behavior: script confirmation"** below for the required summary format.
+
 ## Core concepts
 
 - **Video DSL**: a declarative description language for videos — describes the final structure, not the orchestration calls.
@@ -84,9 +93,19 @@ This skill does not hit any external API; no token required. The script only doe
 ### Confirmation flow
 
 1. After the agent generates or modifies the DSL, **show the script summary first; do not pass it downstream yet**.
-2. Wait for the user to explicitly confirm (e.g. "OK", "looks good", "continue with template binding") before handing it to `prepare-video-assets` (or `template-registry` for a list-only lookup).
+2. **End your turn there and wait** for the user to explicitly confirm (e.g. "OK", "looks good", "continue with template binding") before handing it to `prepare-video-assets` (or `template-registry` for a list-only lookup).
 3. If the user asks for changes (adjust narration, add or remove scenes, change durations), the agent updates the DSL and shows the summary again, then waits for confirmation once more.
 
+> ⚠️ **Never** call `prepare_video_assets` before the user has confirmed — not even when the original
+> request was a single end-to-end instruction like "make me a video about X". That request authorizes
+> the *pipeline*, not the skipping of its review steps. "Finish the task in one go" does **not** apply
+> here: stopping for confirmation **is** the correct completion of this step.
+
+### Showing the script
+
+Show **every scene in full** — do not collapse them with phrases like "scenes 2–6 same as above".
+The user is reviewing the narration word by word; a summary they cannot proofread defeats the gate.
+
 ### Summary content
 
 The agent should show the following in clear Markdown:

package/skills/prepare-video-assets/SKILL.md

@@ -9,6 +9,8 @@ description: |
   - Regenerate one asset (image / audio) for a specific scene
 
   Next step: after the user confirms the resolved assets, call `render_video` with the `job_id` returned by this skill.
+
+  ⚠️ Stop-and-confirm gate: this skill runs only after the user has confirmed the script, and after it returns you must show the resolved assets and wait for the user's explicit confirmation. Never call `render_video` in the same turn.
 triggers:
   - Generate / prepare video assets
   - Resolve missing assets in a DSL
@@ -20,6 +22,14 @@ triggers:
 
 Phase 1 of the two-phase video pipeline. Takes a Video DSL plus a template binding, walks every `AssetRef` declared in the DSL, calls the matching atomic skills to fill in missing assets (`gen-image`, `gen-voice`, `gen-video`, `gen-digital-human`), persists the resulting RenderPlan to ab-api, and prints a `job_id` for the user-confirmation step.
 
+> ⚠️ **Stop-and-confirm gate (mandatory, do not skip) — both sides of this skill.**
+> **Before**: only run this skill after the user has confirmed the script produced by `gen_script`.
+> **After**: show the resolved assets (images inline, audio as links) and **stop your turn** — wait for
+> the user to explicitly confirm before rendering. **Never** call `render_video` in the same turn as
+> `prepare_video_assets`. This is the last checkpoint where a bad image or a wrong TTS take can be
+> fixed for the price of one asset instead of a whole re-render.
+> See **"Pre-render user confirmation (Phase 2)"** below for the required summary format.
+
 > **Next step**: after the user reviews the assets and confirms, call **`render_video`** with the `job_id` returned by this skill.
 
 ## Pipeline (this skill's part only)
@@ -94,7 +104,13 @@ python3 <SkillDir>/scripts/prepare_video_assets.py \
 
 ## Pre-render user confirmation (Phase 2)
 
-This skill is the **first half** of a two-phase user-confirmation flow. After it returns, the agent must show the user the resolved assets and wait for confirmation before calling `render_video`. The recommended summary format:
+This skill is the **first half** of a two-phase user-confirmation flow. After it returns, the agent **must** show the user the resolved assets, then **end its turn and wait** for confirmation before calling `render_video`.
+
+> ⚠️ **Never** start the final render before the user confirms. An end-to-end request ("make me a video
+> about X") authorizes the pipeline, not the skipping of its review steps — stopping here **is** the
+> correct completion of this step, not an unfinished task.
+
+Read the `job_id` from the stdout line `📦 render job jobId: N` and remember it; asset URLs come from the `🔊 TTS audio:` and `🖼  Image assets:` sections. Show images inline (`![name](https://...)`) and audio as links (`[🔊 listen](http://cdn.../x.mp3)`) so the user can actually review them. The recommended summary format:
 
 ```markdown
 ## Render confirmation

package/skills/render-video/SKILL.md

@@ -9,6 +9,8 @@ description: |
   - Render with Remotion
 
   Prerequisite: 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.
+
+  ⚠️ 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.
 triggers:
   - Render the video, composite the video, export the video
   - Turn the prepared assets into the final clip
@@ -22,6 +24,17 @@ Loads a persisted RenderPlan from the database (or a local file fallback), compi
 
 > **Prerequisite**: assets must already be generated via `prepare_video_assets`. That skill returns a `job_id` integer; pass it here.
 
+> ⚠️ **Stop-and-confirm gate (mandatory, do not skip).**
+> **Never** call this skill until the user has explicitly confirmed the assets shown after
+> `prepare_video_assets`. If those assets were prepared in the current turn and the user has not
+> replied since, **stop and ask** — do not render. This step spends render credits and uploads the
+> result; it is the one action in the pipeline that cannot be walked back cheaply.
+>
+> "Confirmed" means the user said so **in a message of their own** (e.g. "confirm", "go ahead",
+> "looks good", "continue"). An end-to-end instruction from earlier in the conversation
+> ("make me a video about X") is **not** confirmation — it authorizes the pipeline, not the
+> skipping of its review steps. Stopping to ask **is** the correct completion of this step.
+
 ## Render pipeline (this skill's part only)
 
 ```

package/skills/web-record/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: web-record
 description: |
-  网页录屏 / 分镜视频技能（输出 webm），基于 Playwright Python，对任意 URL 落盘到本地。
+  网页录屏 / 分镜视频技能（录制 webm，默认转码 mp4 + 抽封面 + 上传 VOD 并返回 CDN 地址），基于 Playwright Python。
   支持：固定时长 / 条件触发（元素出现 / 消失）停止、自动滚动录屏（从头划到尾）、自定义分镜（storyboard）、参数化模板。
   分镜场景：高亮 / 聚焦 / 放大 / 滚动 / 虚拟光标点击 / 打字 / 悬停 / 字幕 / 标题卡 / 箭头 / 编号序列 / 打码 / 代码行高亮。
 
-  只出视频（.webm）。要静态截图（png/jpg）请用 web-capture / web_capture。
+  只出视频。要静态截图（png/jpg）请用 web-screenshot / `web_screenshot`。
 
   当用户提到以下任何需求时，立即使用本 skill：
   - 录屏、网页录制、录制视频、录一段操作、生成 webm、screencast
@@ -23,39 +23,255 @@ triggers:
 
 # 网页录屏 / 分镜视频 Skill（web_record）
 
-录屏入口，输出 **`.webm`**。底层复用 web-capture 的 `scripts/record.py` 与 `_media_screenshot/` 包
-（本 skill 的 `entry.scriptPath` 相对指向 `../web-capture/scripts/record.py`）。静态截图请改用
-**web-capture / `web_capture`**。
+录屏入口。静态截图请改用 **web-screenshot / `web_screenshot`**。
 
-完整的参数说明、storyboard 场景类型、模板列表与用法，见 **web-capture 的 `SKILL.md`「录屏 `record.py`」章节**——本 skill 就是把那条录屏路径独立成一个工具，避免把 `.webm` 误喂给截图入口。
+**脚本位置**：本 skill 没有自己的 `scripts/`，复用 web-screenshot 目录下的 `record.py` 与
+`_media_screenshot/` 包（`skill.json` 的 `entry.scriptPath` 相对指向
+`../web-screenshot/scripts/record.py`）。下文命令里的 **`<RecordScript>`** 一律替换为：
 
-## 常见用法
+```
+<SkillDir>/../web-screenshot/scripts/record.py
+```
+
+> 路径约定：读取系统注入的 `Base directory for this skill: <path>` 作为 `<SkillDir>`，切勿硬编码绝对路径。`python` 在 macOS 上可能需写成 `python3`。
+
+## 前置依赖
+
+- **Python 3.9+**
+- **`playwright` pip 包 + chromium 内核**：首次运行**自动 bootstrap**（`pip install playwright` + `playwright install chromium`）。
+- **ffmpeg**（可选）：只在 `--no-upload` 的单机路径下用于裁掉开头加载段。默认的上传路径由 ab-render 在转码同一 pass 里裁，本机不需要 ffmpeg。
+
+## 输出与上传
+
+默认行为（**不是**只落一个 webm）：录制 `.webm` → 交给 ab-render 转码 mp4 + 抽封面 → 上传 VOD → 打印可播放的 CDN 地址，并**删除本地 webm**（VOD 已持有）。
+
+- `--no-upload`：跳过收尾，只保留本地 `.webm`（此时用本机 ffmpeg 尽力裁开头，缺 ffmpeg 则保留原片并提示）。
+- `--keep-webm`：上传成功后仍保留本地 `.webm`。
+- `--cover-at-sec`：封面抽帧时间点，默认 `0.5` 秒（避开首帧白屏）。
+- `--vod-title`：VOD 资源标题，默认取输出文件名。
+
+需要 env **`PRIV_TOKEN`**（鉴权）与 **`REMOTION_RENDER_API_URL`**（ab-render 地址）。未设 `PRIV_TOKEN` 时自动降级为「仅本地文件」并在 stderr 提示；上传过程出错同样降级，不会丢掉已录好的文件。
+
+## 录屏用法
+
+### 固定时长录屏
+
+```bash
+python3 <RecordScript> \
+  --url "https://example.com" \
+  --output "demo.webm" \
+  --viewport "1280,720" \
+  --duration 8000
+```
+
+### 等条件结束（推荐配合 max-duration 防卡死）
+
+```bash
+# 等到 "加载完成" 元素出现就停
+python3 <RecordScript> \
+  --url "https://example.com" \
+  --output "loaded.webm" \
+  --stop-when-selector "div.loaded" \
+  --max-duration 30000
+
+# 等到 loading 转圈消失就停
+python3 <RecordScript> \
+  --url "https://example.com" \
+  --output "spinner_done.webm" \
+  --stop-when-hidden ".spinner" \
+  --max-duration 30000
+```
+
+### 组合：先满足谁就停
+
+```bash
+python3 <RecordScript> \
+  --url "https://example.com" \
+  --output "race.webm" \
+  --duration 15000 \
+  --stop-when-selector ".done" \
+  --max-duration 20000
+```
 
-固定时长：
+### 录屏前等页面就绪
 
 ```bash
-python3 <SkillDir>/../web-capture/scripts/record.py \
-  --url "https://example.com" --output "demo.webm" \
-  --viewport "1280,720" --duration 8000
+python3 <RecordScript> \
+  --url "https://app.example.com" \
+  --output "after_login.webm" \
+  --storage-state "./auth.json" \
+  --wait-for-selector "#dashboard" \
+  --duration 6000
 ```
 
-自动滚动（从头划到尾）：
+### 自动滚动录屏（从头划到尾）
 
 ```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
+python3 <RecordScript> \
+  --url "https://example.com" \
+  --output "scroll.webm" \
+  --viewport "1440,900" \
+  --scroll-through \
+  --scroll-step 50 \
+  --scroll-interval 60 \
+  --scroll-pause-top 1000 \
+  --scroll-pause-bottom 1500
 ```
 
-模板出片：
+### 模板视频（快捷出片）
+
+`templates/` 下提供参数化的 storyboard 模板，常见结构一行命令出片：
 
 ```bash
-python3 <SkillDir>/../web-capture/scripts/record.py \
+# 列出可用模板
+python3 <RecordScript> --list-templates
+
+# 用 github-repo-intro 模板录任意 GitHub 仓库
+python3 <RecordScript> \
   --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`。
+可重复 `--param key=value` 覆盖模板里的默认值（标签文字、颜色、缩放倍数等）。模板内 `_meta.params` 声明可接收的参数。
+
+**当前模板**：
+
+| 名字 | 说明 | 必填参数 |
+|------|------|---------|
+| `github-repo-intro` | GitHub 仓库三连：项目名红框 → star 页面 zoom → README 滚动 | `repo_url` |
+| `github-readme-tour` | 标题卡 → 项目名 → 光标 hover star → README 滚动 → 结尾呼吁 | `repo_url` |
+| `github-code-tour` | 跳转到文件 → 高亮行范围 → 字幕讲解 | `file_url` / `start_line` / `end_line` |
+
+**新增模板**：在 `<SkillDir>/../web-screenshot/templates/` 下放一个 JSON，按 storyboard 格式写场景，里面用 `{{var_name}}` 占位。可选加 `_meta.params` 声明参数（标 `required: true` / `default: ...`）。占位单独成串时会自动转 int/float/bool（如 `"scale": "{{zoom_scale}}"` 渲染后是数字）。
+
+### 自定义分镜（storyboard）
+
+把一系列「场景」组合成一段视频，场景间用 overlay 淡入淡出过渡（**不会黑屏**）。
+
+```bash
+python3 <RecordScript> \
+  --url "https://github.com/user/repo" \
+  --output "story.webm" \
+  --viewport "1440,900" \
+  --storyboard story.json
+```
+
+`story.json` 示例：
+
+```json
+{
+  "url": "https://github.com/user/repo",
+  "viewport": [1440, 900],
+  "waitForReadySelectors": ["article.markdown-body"],
+  "settleMs": 1200,
+  "transition": { "fadeOutMs": 320, "gapMs": 180 },
+  "scenes": [
+    {
+      "type": "highlight",
+      "selector": "strong[itemprop=\"name\"] a",
+      "color": "#ff3b30",
+      "lineWidth": 5,
+      "padding": 10,
+      "label": "项目名称",
+      "duration": 3000
+    },
+    {
+      "type": "zoom",
+      "target": "page",
+      "selector": "#repo-stars-counter-star",
+      "scale": 2.4,
+      "rampInMs": 900,
+      "holdMs": 2200,
+      "rampOutMs": 700,
+      "label": "⭐ Star 数量"
+    },
+    {
+      "type": "scroll",
+      "fromSelector": "article.markdown-body",
+      "step": 50,
+      "interval": 70,
+      "duration": 10000,
+      "holdAtEnd": 800
+    }
+  ]
+}
+```
+
+**场景类型**：
+
+*视觉强调*
+- `highlight` — 元素红框 + 标签，`padding` / `lineWidth` / `color` / `duration`
+- `focus` — 周围暗化（spotlight）+ 元素描边 + 标签
+- `zoom` — 放大动画
+  - `target: "element"` (默认) — 缩放目标元素本身（弹性曲线）
+  - `target: "page"` — 像浏览器 zoom 一样整个页面以目标元素中心放大
+  - `scale` / `rampInMs` / `rampOutMs` / `holdMs` / `dim` / `label` / `color`
+- `scroll` — 滚动到目标。`fromSelector` 起点、`toSelector` 终点、`step` / `interval` / `duration` / `holdAtEnd`
+- `wait` — 单纯停顿 `duration`
+
+*交互模拟（虚拟光标）*
+- `click` — 光标飞向元素 → 涟漪 → 真实触发 `el.click()`。`moveMs` / `preHoldMs` / `postHoldMs` / `rippleMs` / `color` / `realClick`(默认 true，可设 false 只动画不点)
+- `type` — 光标飞向输入框 → focus → 逐字打字。`text` / `delay`(ms/字) / `clearFirst` / `moveCursor`
+- `hover` — 光标移到元素并触发原生 hover，常用于悬出 tooltip / hover card。`moveMs` / `holdMs`
+
+*注释表达*
+- `arrow` — 从一个锚点画 SVG 弧线箭头指向另一个锚点。锚点 `from` / `to` 形如 `{selector, side}`（side: center/left/right/top/bottom）或 `{x, y}`。`color` / `lineWidth` / `label` / `duration`
+- `sequence` — 多个 selector 顺序出 ①②③ 圆形 badge + 红框 + 标签。`items: [{selector, label}, ...]` / `stepMs` 控制每步间隔 / `color` / `holdMs`
+- `caption` — 顶部/底部滑入字幕条。`text` / `position: top|bottom` / `background` / `color` / `fontSize` / `duration`
+- `title-card` — 全屏开场/结尾大标题卡。`title` / `subtitle`（可选） / `background` / `accent` / `duration`
+- `redact` — 局部打码：blur / pixelate / 实色。`selectors: [...]` 或 `selector` / `mode: "blur" | "pixelate" | "solid"` / `color`(实色时) / `duration`
+
+*GitHub 专属*
+- `code-lines` — 高亮连续代码行范围（默认匹配新版 React blob `[data-line-number="{n}"]`；老版 blob 表格用 `linePattern: "#LC{n}"`）。`startLine` / `endLine` / `linePattern` / `color` / `label` / `duration`
+
+**自动裁剪**：storyboard 模式录制时会等待页面真正稳定（networkidle + skeleton 消失），并在事后用 ffmpeg 帧精度裁掉开头加载段，最终视频长度 ≈ 各场景总时长。
+
+### 完整参数
+
+| 参数 | 说明 | 默认 |
+|------|------|------|
+| `-u` / `--url` | 目标 URL（必填） | — |
+| `-o` / `--output` | 本地输出 `.webm` 路径 | `recording.webm` |
+| `-b` / `--browser` | `chromium` / `firefox` / `webkit`（建议 chromium） | `chromium` |
+| `--device` | 设备模拟 | 无 |
+| `--viewport` | `"宽,高"` | 无 |
+| `--duration` | 固定录制时长（ms） | 无 |
+| `--stop-when-selector` | 选择器出现就停 | 无 |
+| `--stop-when-hidden` | 选择器消失就停 | 无 |
+| `--max-duration` | 条件模式安全上限（ms） | 60000 |
+| `--scroll-through` | 自动从顶部滚到底部 | 关 |
+| `--scroll-step` | 每步像素 | 60 |
+| `--scroll-interval` | 每步间隔（ms） | 50 |
+| `--scroll-pause-top` | 顶部停留（ms） | 800 |
+| `--scroll-pause-bottom` | 底部停留（ms） | 1200 |
+| `--storyboard` | 分镜 JSON 文件路径 | 无 |
+| `--template` | 模板名（templates/<name>.json）；与 `--storyboard` 互斥 | 无 |
+| `--param` | 模板参数 `key=value`，可重复 | 无 |
+| `--list-templates` | 列出可用模板并退出 | — |
+| `--wait-for-selector` | 开始录前等待出现 | 无 |
+| `--wait-for-timeout` | 开始录前固定等待（ms） | 无 |
+| `--color-scheme` | prefers-color-scheme | 无 |
+| `--user-agent` | 覆盖 UA | 无 |
+| `--timeout` | Playwright 全局超时（ms） | 无 |
+| `--ignore-https-errors` | 忽略证书错误 | 关 |
+| `--storage-state` | storageState JSON 文件 | 无 |
+| `--cookies` | cookies JSON 字符串或文件 | 无 |
+| `--no-upload` | 录完不上传，只保留本地 webm | 关（默认上传） |
+| `--vod-title` | 上传到 VOD 的标题 | 输出文件名 |
+| `--cover-at-sec` | 封面抽帧时间点（秒） | 0.5 |
+| `--keep-webm` | 上传成功后保留本地 webm | 关（默认删除） |
+
+至少需提供 `--duration` / `--stop-when-selector` / `--stop-when-hidden` / `--scroll-through` / `--storyboard` / `--template` 之一；组合使用时**先满足谁就停**，同时受 `--max-duration` 兜底。模板 / storyboard JSON 可自带 `url`，此时可省略 `--url`。
+
+## 错误处理
+
+- **首次跑慢**：脚本自动 `pip install playwright` + `playwright install chromium`，耐心等一次即可。
+- **`ModuleNotFoundError: playwright`**：bootstrap 没装上，手动跑 `pip install playwright && playwright install chromium`。
+- **`Executable doesn't exist`**：浏览器内核没装，跑 `playwright install chromium`。
+- **`Timeout ... exceeded`**：拉大 `--timeout`、`--wait-for-timeout`，或换更稳的 `--wait-for-selector`。
+- **录屏文件没产生**：检查 `--output` 后缀是否 `.webm`；查看 stderr 的 `stop reason`。
+- **只拿到本地路径、没有 CDN 地址**：多半是没设 `PRIV_TOKEN`，或收尾失败降级了，stderr 里有原因。
+- **storyboard 开头还有加载残影**：加大 `settleMs` / `waitForReadySelectors`；`--no-upload` 路径还需本机装 ffmpeg。
+- **登录态失效**：重新导出 `storageState` 或更新 `cookies` JSON；`domain` / `path` 必须匹配。
+- **HTTPS 证书报错**：测试环境可加 `--ignore-https-errors`。