@remixmate/cli 0.1.0 → 0.1.1

package/skills/web-capture/SKILL.md

@@ -1,183 +1,474 @@
 ---
 name: web-capture
 description: |
-  Web page capture skill. Drives a headless browser (Playwright) to turn a URL into reusable visual assets — viewport / full-page screenshots, or a smooth top-to-bottom scrolling video (MP4). These assets are the upstream material for the `screen-walkthrough` template.
-
-  Use this skill as soon as the user mentions any of these intents:
-  - Screenshot a web page / website / a specific URL, full-page screenshot
-  - Record a page scrolling top-to-bottom into a video, "scroll video" of a site
-  - Produce screen-recording / walkthrough footage of a GitHub repo, landing page, or product page
-
-  Even when the user does not say "Playwright" or "browser", use this skill whenever they want to turn a web address into a screenshot or a scrolling demo video.
+  网页截屏 / 录屏 / 分镜视频技能，基于 Playwright Python，对任意 URL 落盘到本地。
+  支持：整页 / 元素 / 区域截屏、固定时长 / 条件触发录屏、自动滚动录屏、分镜视频（高亮 / 聚焦 / 放大 / 滚动 / 虚拟光标点击 / 字幕 / 标题卡 / 箭头 / 编号序列 / 打码 / 代码行高亮）。
+
+  当用户提到以下任何需求时，立即使用本 skill：
+  - 网页截图、网页截屏、整页截图、长截图、full page screenshot
+  - 截某个元素 / 区域、局部截屏、focus 某个区域
+  - 录屏、网页录制、录制视频、录一段操作、生成 webm
+  - 滚动录屏、页面从头划到尾的视频
+  - 多场景视频、分镜视频、storyboard、按时间线编排（红框高亮 / 局部放大 / 滚动介绍）
+  - 演示点击 / 输入 / 悬停（虚拟鼠标 + 涟漪 / 打字机 / 触发 tooltip）
+  - 加箭头、加字幕条、加标题卡 / 片头片尾、按顺序编号高亮多个区域
+  - 截图前隐藏元素 / 涂盖打码（cookie banner、敏感信息）
+  - 给静态截图加注释（红框 / 箭头 / 标签）
+  - 高亮某文件的 L5-L20 代码行
+  - 等待元素出现/消失后再截屏或停止录屏
+  - 移动端 / 设备模拟（iPhone / Pixel 等）
+  - 带 cookie / 登录态、storageState 截屏 / 录屏
+
+  即使用户没明确提「playwright」，只要他们想对一个 URL 截屏/录屏/做分镜视频并拿到本地文件，也要使用本 skill。
 triggers:
-  - Screenshot a web page / website / a specific URL, full-page screenshot
-  - Record a page scrolling top-to-bottom into a video, "scroll video" of a site
-  - Produce screen-recording / walkthrough footage of a GitHub repo, landing page, or product page
+  - 网页截图、网页截屏、整页截图、长截图、full page screenshot
+  - 截某个元素 / 区域、局部截屏、focus 某个区域
+  - 录屏、网页录制、录制视频、录一段操作、生成 webm
+  - 滚动录屏、页面从头划到尾的视频
+  - 多场景视频、分镜视频、storyboard、按时间线编排
+  - 演示点击 / 输入 / 悬停（虚拟鼠标 + 涟漪 / 打字机 / 触发 tooltip）
+  - 加箭头、加字幕条、加标题卡 / 片头片尾、按顺序编号高亮多个区域
+  - 截图前隐藏元素 / 涂盖打码、给静态截图加注释（红框 / 箭头 / 标签）
+  - 移动端 / 设备模拟、带 cookie / 登录态截屏 / 录屏
 ---
 
-# Web Page Capture Skill
+# 网页截屏 / 录屏 Skill
 
-Drives a **headless browser via Playwright (Python)** to capture a web page as reusable visual assets:
+两个入口脚本，纯 Python 实现：
 
-- **Screenshots** — viewport, full scrollable page, or a single element.
-- **Scroll video** — opens the page and smoothly scrolls top-to-bottom, capturing frames and assembling a deterministic MP4 with ffmpeg.
-- **Record video** — Playwright's native context recording (webm), transcoded to MP4.
+- **`scripts/screenshot.py`** — 截图。整页 / 视口 / 元素 / 区域。
+- **`scripts/record.py`** — 录屏（webm）。固定时长 / 条件停止 / 自动滚动 / 分镜（storyboard）/ **模板（templates/）**。
 
-The MP4 / PNG output is designed to feed the **`screen-walkthrough`** template's screen stage.
+底层共享 **`scripts/_media_screenshot/`** 包，封装 Playwright Python API + 所有浏览器侧 JS 注入（overlay / zoom / scroll 等）。
 
-## Dependencies
+**模板目录** `templates/`：参数化的 storyboard，常见场景一行命令出片。详见下文 "分镜视频 / 模板"。
 
-Aligned with method 1 of the design — the runtime provides the browser, the skill does not bundle it.
+> 路径约定：读取系统注入的 `Base directory for this skill: <path>` 作为 `<SkillDir>`，命令里的 `<SkillDir>` 替换为该路径，切勿硬编码绝对路径。`python` 在 macOS 上可能需写成 `python3`。
 
-- **Python 3** with **Playwright**: `pip install playwright` then `playwright install chromium` (one-time; downloads the browser binary).
-- **ffmpeg**: must be installed locally (`brew install ffmpeg`) — used to assemble the scroll-video frames and transcode native recordings to MP4. Same dependency the `video-parser` skill relies on.
+## 前置依赖
 
-The script checks for both at startup and prints an actionable install hint if either is missing (`__progress__` phase `web-capture:preflight`).
+- **Python 3.9+**
+- **`playwright` pip 包 + chromium 内核**：首次运行**自动 bootstrap**——脚本检测到缺包会执行 `pip install playwright` + `playwright install chromium`。
+  - 也可提前手动装：
+    ```bash
+    pip install playwright
+    playwright install chromium
+    ```
+- **ffmpeg**（可选）：仅 storyboard 模式用来精确裁剪开头加载段。无 ffmpeg 时会保留原片并提示。
 
-## Multi-user isolation & security
+## 截屏 `screenshot.py`
 
-ab-agent spawns one fresh `python3` process per tool call (`spawn('python3', ...)`), and this script launches its own Playwright browser instance per run and closes it on exit. So **concurrent users are isolated at the process + browser-instance level** — no cookie/session bleed between users. The skill hardens a few defaults on top of that:
+### 最小用法
 
-- **Unique output dir**: when `--output-dir` is omitted, output goes to a unique system temp dir (`tempfile.mkdtemp`), never the script's cwd. Concurrent calls can't collide or pollute `skills/`.
-- **Temp cleanup**: per-frame images (`_frames/`) and native-recording webm (`_rec/`) are removed in a `finally` block, so failures don't leak temp data.
-- **SSRF guard**: the user-supplied `url` is validated before any browser launch — only `http`/`https`, and the resolved IP must not be private / loopback / link-local / reserved / cloud-metadata (`169.254.169.254`). Rejection exits with code 5.
-- **Sandbox on by default**: Chromium keeps its sandbox; `--no-sandbox` is only added when `WEB_CAPTURE_NO_SANDBOX=1`.
+```bash
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://example.com" \
+  --output "example.png"
+```
 
-Not handled in-skill (orchestration concern): **concurrency limits**. Each browser is ~150–300MB; many simultaneous `scroll-video` calls can exhaust host memory. Gate concurrency at the ab-agent layer or via host resources.
+### 整页截图
 
-### Environment variables
+```bash
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://example.com" \
+  --output "example_full.png" \
+  --full-page
+```
 
-| Env var | Description | Default |
-|---------|-------------|---------|
-| `WEB_CAPTURE_BROWSER` | Default browser engine (`--browser` overrides). | `chromium` |
-| `WEB_CAPTURE_OUTPUT_BASE` | Base dir for the auto-created temp output dir. | system tempdir |
-| `WEB_CAPTURE_NO_SANDBOX` | Set `1` to add `--no-sandbox` (only for containers that can't use user namespaces). | unset (sandbox on) |
-| `WEB_CAPTURE_ALLOW_PRIVATE_HOSTS` | Set `1` to disable the private/internal-IP SSRF block (single-tenant / trusted intranet only). | unset (block on) |
-| `PLAYWRIGHT_BROWSERS_PATH` | Playwright browser binary location (provided by the runtime). | Playwright default |
+### 元素截屏（局部 focus）
 
-## Operations
+按 CSS 选择器截**元素本身**（自动 `scrollIntoViewIfNeeded`）：
 
-1. **Script path**: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>` and always use `<SkillDir>/scripts/web_capture.py`. Never hard-code paths.
-2. **Pick the mode**: `screenshot` (default), `scroll-video`, or `record-video`.
-3. **Run the capture** and wait for it to finish.
-4. **Inspect the result**: a `capture.json` manifest plus the produced `*.png` / `*.mp4` under `--output-dir`.
+```bash
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://example.com" \
+  --output "card.png" \
+  --selector ".card.featured" \
+  --wait-for-selector ".card.featured"
+```
+
+如不希望自动滚动：加 `--no-scroll-into-view`。
 
-### Viewport screenshot
+### 区域截屏（像素矩形 clip）
 
 ```bash
-python3 <SkillDir>/scripts/web_capture.py \
-  --url "https://github.com/microsoft/playwright" \
-  --mode screenshot
+# 全页像素坐标
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://example.com" \
+  --output "region.png" \
+  --clip "100,200,600,400"     # x, y, w, h
+
+# 以元素为基点偏移裁剪（先 scrollIntoView 该元素，再用其 boundingBox 起点 + 偏移裁剪）
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://example.com" \
+  --output "region_in_card.png" \
+  --selector ".card" \
+  --clip "0,0,300,180"
 ```
 
-### Full-page screenshot (whole scrollable page)
+### 移动端 / 设备模拟
 
 ```bash
-python3 <SkillDir>/scripts/web_capture.py \
-  --url "https://example.com" \
-  --mode screenshot \
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://m.example.com" \
+  --output "mobile.png" \
+  --device "iPhone 15 Pro" \
   --full-page
 ```
 
-### Element-only screenshot
+自定义 viewport：
+
+```bash
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://example.com" \
+  --output "wide.png" \
+  --viewport "1440,900"
+```
+
+### 等待动态内容
+
+```bash
+# 等待选择器出现
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://example.com" \
+  --output "ready.png" \
+  --wait-for-selector "main .loaded" \
+  --timeout 30000
+
+# 固定延时（适合纯前端动画）
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://example.com" \
+  --output "delayed.png" \
+  --wait-for-timeout 2000
+```
+
+### 隐藏 / 涂盖元素
 
 ```bash
-python3 <SkillDir>/scripts/web_capture.py \
+# 隐藏 cookie banner、登录浮层等干扰元素（可重复）
+python3 <SkillDir>/scripts/screenshot.py \
   --url "https://example.com" \
-  --mode screenshot \
-  --selector "#readme"
+  --output "clean.png" \
+  --hide-selector ".cookie-banner" \
+  --hide-selector "#login-modal"
+
+# 涂盖敏感信息（Playwright 原生 mask，默认粉色，可自定义颜色）
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://app.example.com/dashboard" \
+  --output "redacted.png" \
+  --mask-selector ".user-email" \
+  --mask-selector ".api-token" \
+  --mask-color "#222"
+```
+
+### 静态截图加注释（红框 / 箭头 / 字幕 / 编号 / 打码）
+
+`--annotate` 接受一份 JSON（路径或字符串），里面用 storyboard 的场景类型描述要画的注解。所有场景在截屏前一次性画好。
+
+```bash
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://github.com/user/repo" \
+  --output "annotated.png" \
+  --annotate annotate.json
+```
+
+`annotate.json` 示例：
+
+```json
+{
+  "annotations": [
+    { "type": "highlight", "selector": "strong[itemprop=\"name\"] a",
+      "color": "#ff3b30", "label": "看这里" },
+    { "type": "arrow",
+      "from": { "selector": "#repo-stars-counter-star" },
+      "to":   { "selector": "strong[itemprop=\"name\"] a", "side": "right" },
+      "color": "#ff9500", "label": "⭐" },
+    { "type": "caption", "text": "项目主页", "position": "bottom" },
+    { "type": "redact", "selectors": [".user-email"], "mode": "blur" }
+  ],
+  "settleMs": 900
+}
 ```
 
-### Scrolling video (top-to-bottom)
+> 顶层也可以直接是数组：`[{"type": "highlight", ...}]`。`settleMs` 是画完后等动画稳定再截屏的时长，默认 900ms。
+
+### 带登录态截屏
+
+两种方式，二选一：
+
+**A. 直接传 storageState（推荐）**
 
 ```bash
-python3 <SkillDir>/scripts/web_capture.py \
-  --url "https://github.com/microsoft/playwright" \
-  --mode scroll-video \
-  --width 1280 --height 720 \
-  --fps 30 \
-  --scroll-duration 8
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://app.example.com/dashboard" \
+  --output "dashboard.png" \
+  --storage-state "./auth.json"
 ```
 
-Produces a deterministic `scroll.mp4` — fps, resolution and scroll speed are all controllable, which keeps the output aligned with the `screen-walkthrough` timeline.
+> `auth.json` 可由 `npx playwright codegen --save-storage=auth.json <url>` 在登录后导出。
 
-### Native recording (webm → mp4)
+**B. 仅传 cookies JSON**
 
 ```bash
-python3 <SkillDir>/scripts/web_capture.py \
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://app.example.com/dashboard" \
+  --output "dashboard.png" \
+  --cookies "./cookies.json"
+```
+
+cookies 顶层必须是数组，每项遵循 Playwright cookie 格式：
+
+```json
+[
+  {"name": "session", "value": "abc", "domain": ".example.com", "path": "/", "httpOnly": true, "secure": true}
+]
+```
+
+### screenshot.py 参数
+
+| 参数 | 说明 | 默认 |
+|------|------|------|
+| `-u` / `--url` | 目标 URL（必填） | — |
+| `-o` / `--output` | 本地输出路径 | `screenshot.png` |
+| `-b` / `--browser` | `chromium` / `firefox` / `webkit` | `chromium` |
+| `--device` | 设备模拟名 | 无 |
+| `--viewport` | `"宽,高"` | 无 |
+| `--full-page` | 整页截屏 | 关 |
+| `--selector` | 截元素本身 | 无 |
+| `--clip` | `"x,y,w,h"` 区域截屏；和 selector 同设时基于元素 boundingBox 偏移 | 无 |
+| `--no-scroll-into-view` | selector 模式下关闭自动滚动 | 关 |
+| `--wait-for-selector` | 操作前等待选择器出现 | 无 |
+| `--wait-for-timeout` | 操作前固定等待（ms） | 无 |
+| `--color-scheme` | `light` / `dark` / `no-preference` | 无 |
+| `--user-agent` | 覆盖 UA | 无 |
+| `--timeout` | Playwright 全局超时（ms） | 无 |
+| `--ignore-https-errors` | 忽略证书错误 | 关 |
+| `--storage-state` | storageState JSON 文件路径 | 无 |
+| `--cookies` | cookies JSON 字符串或文件 | 无 |
+| `--hide-selector` | 截屏前 display:none 该选择器，可重复 | 无 |
+| `--mask-selector` | Playwright 原生 mask 涂盖该选择器，可重复 | 无 |
+| `--mask-color` | mask 填充色 | Playwright 粉 |
+| `--annotate` | 注释 JSON 文件或字符串（数组或 `{annotations, settleMs}`） | 无 |
+
+## 录屏 `record.py`
+
+> 输出为 **`.webm`**（Playwright 录屏的原生格式）。如需 mp4，请用 ffmpeg 后处理。
+
+### 固定时长录屏
+
+```bash
+python3 <SkillDir>/scripts/record.py \
   --url "https://example.com" \
-  --mode record-video \
-  --scroll-duration 6
+  --output "demo.webm" \
+  --viewport "1280,720" \
+  --duration 8000
 ```
 
-Simpler than frame-capture but the frame rate is not precisely controllable; prefer `scroll-video` when timing matters.
+### 等条件结束（推荐配合 max-duration 防卡死）
+
+```bash
+# 等到 "加载完成" 元素出现就停
+python3 <SkillDir>/scripts/record.py \
+  --url "https://example.com" \
+  --output "loaded.webm" \
+  --stop-when-selector "div.loaded" \
+  --max-duration 30000
+
+# 等到 loading 转圈消失就停
+python3 <SkillDir>/scripts/record.py \
+  --url "https://example.com" \
+  --output "spinner_done.webm" \
+  --stop-when-hidden ".spinner" \
+  --max-duration 30000
+```
 
-### JSON pipeline mode
+### 组合：先满足谁就停
 
 ```bash
-python3 <SkillDir>/scripts/web_capture.py \
+python3 <SkillDir>/scripts/record.py \
   --url "https://example.com" \
-  --mode screenshot \
-  --json-output
+  --output "race.webm" \
+  --duration 15000 \
+  --stop-when-selector ".done" \
+  --max-duration 20000
 ```
 
-Prints only the final `capture.json` payload to stdout — no progress lines — suitable for piping into downstream skills.
+### 录屏前等页面就绪
 
-See every option: `python3 <SkillDir>/scripts/web_capture.py --help`.
+```bash
+python3 <SkillDir>/scripts/record.py \
+  --url "https://app.example.com" \
+  --output "after_login.webm" \
+  --storage-state "./auth.json" \
+  --wait-for-selector "#dashboard" \
+  --duration 6000
+```
+
+### 自动滚动录屏（从头划到尾）
 
-## Common CLI flags
+```bash
+python3 <SkillDir>/scripts/record.py \
+  --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
+```
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--url` | Target page URL (http/https). | required |
-| `--mode` | `screenshot` / `scroll-video` / `record-video`. | `screenshot` |
-| `-o` / `--output-dir` | Output directory. | unique system temp dir |
-| `--width` | Viewport width (px). | `1280` |
-| `--height` | Viewport height (px). | `720` |
-| `--device-scale-factor` | Device pixel ratio (crisp / retina). | `2` |
-| `--full-page` | Screenshot mode: capture the whole scrollable page. | off |
-| `--selector` | Screenshot mode: capture only this CSS element. | none |
-| `--fps` | Scroll / record video frame rate. | `30` |
-| `--scroll-duration` | Seconds for the full top-to-bottom scroll. | `8` |
-| `--browser` | `chromium` / `firefox` / `webkit`. | `chromium` |
-| `--wait-until` | `load` / `domcontentloaded` / `networkidle`. | `networkidle` |
-| `--wait-ms` | Extra wait after load before capture (ms). | `1500` |
-| `--json-output` | Pipeline mode — JSON-only stdout. | off |
+### 模板视频（快捷出片）
 
-## Output layout
+`templates/` 下提供参数化的 storyboard 模板，常见结构一行命令出片：
 
+```bash
+# 列出可用模板
+python3 <SkillDir>/scripts/record.py --list-templates
+
+# 用 github-repo-intro 模板录任意 GitHub 仓库
+python3 <SkillDir>/scripts/record.py \
+  --template github-repo-intro \
+  --param repo_url=https://github.com/user/repo \
+  --output repo.webm
 ```
-<output-dir>/
-├── capture.json          # asset manifest (mode, url, viewport, produced files)
-├── screenshot.png         # screenshot mode
-└── scroll.mp4             # scroll-video / record-video mode
+
+可重复 `--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>/templates/` 下放一个 JSON，按 storyboard 格式写场景，里面用 `{{var_name}}` 占位。可选加 `_meta.params` 声明参数（标 `required: true` / `default: ...`）。占位单独成串时会自动转 int/float/bool（如 `"scale": "{{zoom_scale}}"` 渲染后是数字）。
+
+### 自定义分镜（storyboard）
+
+把一系列「场景」组合成一段视频，场景间用 overlay 淡入淡出过渡（**不会黑屏**）。
+
+```bash
+python3 <SkillDir>/scripts/record.py \
+  --url "https://github.com/user/repo" \
+  --output "story.webm" \
+  --viewport "1440,900" \
+  --storyboard story.json
 ```
 
-### `capture.json` shape
+`story.json` 示例：
 
 ```json
 {
-  "source": { "url": "https://example.com", "finalUrl": "https://example.com/" },
-  "mode": "scroll-video",
-  "viewport": { "width": 1280, "height": 720, "deviceScaleFactor": 2 },
-  "outputs": [
-    { "type": "video", "localPath": "<output-dir>/scroll.mp4", "fps": 30, "durationSec": 8.0, "frames": 240 }
+  "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
+    }
   ]
 }
 ```
 
-For `screenshot` mode each entry is `{ "type": "image", "localPath": "...", "fullPage": false }`.
-
-## Notes on the deprecated `microsoft/playwright-cli`
-
-The original `microsoft/playwright-cli` repository was **archived (read-only) in January 2021** and is deprecated; its functionality was folded into the main `playwright` package. This skill therefore uses the maintained **Playwright Python** library directly. Pure screenshots are also available via `npx playwright screenshot`, but scrolling-video capture requires script-driven scrolling + frame assembly, which is what this skill provides.
-
-## Error handling
-
-- **Playwright not installed**: the script detects it and prints `pip install playwright && playwright install chromium`.
-- **Browser binary missing** (`Executable doesn't exist`): run `playwright install chromium` (or the chosen browser).
-- **ffmpeg not installed** (video modes): the script prompts `brew install ffmpeg`.
-- **URL rejected (exit 5)**: non-http(s) scheme, or the host resolves to a private/internal/metadata address. Use a public URL, or set `WEB_CAPTURE_ALLOW_PRIVATE_HOSTS=1` for a trusted intranet target.
-- **Navigation timeout**: the page took too long; try `--wait-until load` or a smaller `--wait-ms`.
-- **Blank / partial capture**: increase `--wait-ms`, or some sites block headless browsers.
-- **Network**: verify the URL is reachable from the runtime host.
+**场景类型**：
+
+*视觉强调*
+- `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 帧精度裁掉开头加载段，最终视频长度 ≈ 各场景总时长。
+
+### record.py 参数
+
+| 参数 | 说明 | 默认 |
+|------|------|------|
+| `-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 字符串或文件 | 无 |
+
+至少需提供 `--duration` / `--stop-when-selector` / `--stop-when-hidden` / `--scroll-through` / `--storyboard` / `--template` 之一；组合使用时**先满足谁就停**，同时受 `--max-duration` 兜底。模板 / storyboard JSON 可自带 `url`，此时可省略 `--url`。
+
+## 错误处理
+
+- **首次跑慢**：脚本自动 `pip install playwright` + `playwright install chromium`，耐心等一次即可。
+- **`Cannot find module 'playwright'` / `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`。
+- **截屏空白 / 没渲染完**：加 `--wait-for-selector` 等业务关键元素；纯动画类用 `--wait-for-timeout`。
+- **`selector "X" has no bounding box`**：元素存在但不可见 / 尺寸为 0；先用 `--wait-for-selector` 等可见。
+- **登录态失效**：重新导出 `storageState` 或更新 `cookies` JSON；`domain` / `path` 必须匹配。
+- **HTTPS 证书报错**：测试环境可加 `--ignore-https-errors`。
+- **录屏文件没产生**：检查 `--output` 后缀是否 `.webm`；查看 stderr 的 `stop reason`。
+- **storyboard 开头还有加载残影**：装 ffmpeg；或加大 `settleMs` / `waitForReadySelectors`。

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

@@ -0,0 +1,21 @@
+"""media-screenshot internal package.
+
+Public surface used by the entry-point scripts. Anything else under this
+package is implementation detail.
+"""
+from __future__ import annotations
+
+from . import cli_args, scenes, template, trim
+from .recording import do_record
+from .screenshot import do_screenshot
+from .storyboard import do_storyboard
+
+__all__ = [
+    "cli_args",
+    "do_record",
+    "do_screenshot",
+    "do_storyboard",
+    "scenes",
+    "template",
+    "trim",
+]

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

@@ -0,0 +1,34 @@
+"""Auto-install playwright + chromium on first run."""
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def _pip_install(pkg: str) -> None:
+    print(f"[bootstrap] pip install {pkg} ...", file=sys.stderr)
+    subprocess.check_call(
+        [sys.executable, "-m", "pip", "install", "--quiet", pkg]
+    )
+
+
+def _ensure_playwright_pkg() -> None:
+    try:
+        import playwright.sync_api  # noqa: F401
+        return
+    except ImportError:
+        pass
+    _pip_install("playwright")
+
+
+def ensure_chromium() -> None:
+    """Install the chromium browser via `playwright install`."""
+    print("[bootstrap] playwright install chromium ...", file=sys.stderr)
+    subprocess.check_call(
+        [sys.executable, "-m", "playwright", "install", "chromium"]
+    )
+
+
+def ensure_runtime() -> None:
+    """Make sure the playwright pip package is importable."""
+    _ensure_playwright_pkg()