@remixmate/cli 0.9.11 → 0.9.13

package/skills/web-record/skill.json

@@ -4,9 +4,9 @@
   "tier": "tool",
   "category": "consuming",
   "title": "Web Page Recording",
-  "description": "Drive a headless browser (Playwright Python) to RECORD any URL to a video, then (by default) transcode to mp4, grab a cover frame, upload to VOD and return a playable CDN URL. Modes: fixed-duration recording, condition-triggered stop (element appears / disappears), auto-scroll from top to bottom, custom storyboards, and parameterized templates. Storyboard scenes: highlight / focus / zoom / scroll / virtual-cursor click / type / hover / caption / title-card / arrow / numbered sequence / redact / code-line highlight. For still images (png/jpg) use the web_capture tool instead. Use this tool whenever the user wants a video / recording / screencast of a web page: record a page, scroll-through video, page-from-top-to-bottom clip, demo of clicks/typing/hover, storyboard / multi-scene intro video, or a template-based clip.",
+  "description": "Drive a headless browser (Playwright Python) to RECORD any URL to a video, then (by default) transcode to mp4, grab a cover frame, upload to VOD and return a playable CDN URL. Modes: fixed-duration recording, condition-triggered stop (element appears / disappears), auto-scroll from top to bottom, custom storyboards, and parameterized templates. Storyboard scenes: highlight / focus / zoom / scroll / virtual-cursor click / type / hover / caption / title-card / arrow / numbered sequence / redact / code-line highlight. For still images (png/jpg) use the web_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.",
   "envVars": ["WEB_CAPTURE_BROWSER", "WEB_CAPTURE_OUTPUT_BASE", "WEB_CAPTURE_NO_SANDBOX", "WEB_CAPTURE_ALLOW_PRIVATE_HOSTS", "PLAYWRIGHT_BROWSERS_PATH", "REMOTION_RENDER_API_URL", "PRIV_TOKEN"],
-  "entry": { "type": "python", "scriptPath": "../web-capture/scripts/record.py" },
+  "entry": { "type": "python", "scriptPath": "../web-screenshot/scripts/record.py" },
   "parameters": {
     "type": "object",
     "properties": {

package/skills/web-screenshot/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: web-screenshot
+description: |
+  网页截图技能（只出静态图片 png/jpg），基于 Playwright Python，对任意 URL 落盘到本地。
+  支持：整页 / 视口 / 元素 / 区域截图、设备模拟、等待动态内容、隐藏 / 涂盖干扰元素、静态注释（红框 / 箭头 / 字幕 / 编号 / 打码 / 代码行高亮）。
+
+  只出图片（.png / .jpg）。要视频（.webm / 录屏 / 分镜）请用 web-record / `web_record`。
+
+  当用户提到以下任何需求时，立即使用本 skill：
+  - 网页截图、网页截屏、整页截图、长截图、full page screenshot
+  - 截某个元素 / 区域、局部截屏、focus 某个区域
+  - 截图前隐藏元素 / 涂盖打码（cookie banner、敏感信息）
+  - 给静态截图加注释（红框 / 箭头 / 标签 / 字幕条 / 编号）
+  - 高亮某文件的 L5-L20 代码行并截图
+  - 等元素出现后再截图
+  - 移动端 / 设备模拟截图（iPhone / Pixel 等）
+  - 带 cookie / 登录态、storageState 截图
+
+  即使用户没明确提「playwright」，只要他们想对一个 URL 截图并拿到本地图片文件，也要使用本 skill。
+triggers:
+  - 网页截图、网页截屏、整页截图、长截图、full page screenshot
+  - 截某个元素 / 区域、局部截屏、focus 某个区域
+  - 截图前隐藏元素 / 涂盖打码、给静态截图加注释（红框 / 箭头 / 标签）
+  - 高亮某文件的 L5-L20 代码行并截图
+  - 移动端 / 设备模拟截图、带 cookie / 登录态截图
+---
+
+# 网页截图 Skill（web_screenshot）
+
+入口脚本 **`scripts/screenshot.py`**，纯 Python 实现，输出 **`.png` / `.jpg`**。整页 / 视口 / 元素 / 区域。
+
+> **只出图片。** 录屏 / 分镜视频（`.webm`）走 **web-record / `web_record`**——传 `--output xxx.webm`
+> 到本 skill 会被直接拒绝并提示改用 `web_record`。录屏入口脚本 `scripts/record.py` 与本 skill 同处
+> 一个目录（两者共享下面的 `_media_screenshot/` 包），但它属于 web-record 这个工具，用法见
+> **`skills/web-record/SKILL.md`**。
+
+底层共享 **`scripts/_media_screenshot/`** 包，封装 Playwright Python API + 所有浏览器侧 JS 注入（overlay / zoom / scroll 等）。
+
+> 路径约定：读取系统注入的 `Base directory for this skill: <path>` 作为 `<SkillDir>`，命令里的 `<SkillDir>` 替换为该路径，切勿硬编码绝对路径。`python` 在 macOS 上可能需写成 `python3`。
+
+## 前置依赖
+
+- **Python 3.9+**
+- **`playwright` pip 包 + chromium 内核**：首次运行**自动 bootstrap**——脚本检测到缺包会执行 `pip install playwright` + `playwright install chromium`。
+  - 也可提前手动装：
+    ```bash
+    pip install playwright
+    playwright install chromium
+    ```
+
+## 截屏 `screenshot.py`
+
+### 最小用法
+
+```bash
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://example.com" \
+  --output "example.png"
+```
+
+### 整页截图
+
+```bash
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://example.com" \
+  --output "example_full.png" \
+  --full-page
+```
+
+### 元素截屏（局部 focus）
+
+按 CSS 选择器截**元素本身**（自动 `scrollIntoViewIfNeeded`）：
+
+```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`。
+
+### 区域截屏（像素矩形 clip）
+
+```bash
+# 全页像素坐标
+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"
+```
+
+### 移动端 / 设备模拟
+
+```bash
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://m.example.com" \
+  --output "mobile.png" \
+  --device "iPhone 15 Pro" \
+  --full-page
+```
+
+自定义 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
+# 隐藏 cookie banner、登录浮层等干扰元素（可重复）
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://example.com" \
+  --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
+}
+```
+
+> 顶层也可以直接是数组：`[{"type": "highlight", ...}]`。`settleMs` 是画完后等动画稳定再截屏的时长，默认 900ms。
+
+### 带登录态截屏
+
+两种方式，二选一：
+
+**A. 直接传 storageState（推荐）**
+
+```bash
+python3 <SkillDir>/scripts/screenshot.py \
+  --url "https://app.example.com/dashboard" \
+  --output "dashboard.png" \
+  --storage-state "./auth.json"
+```
+
+> `auth.json` 可由 `npx playwright codegen --save-storage=auth.json <url>` 在登录后导出。
+
+**B. 仅传 cookies JSON**
+
+```bash
+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}`） | 无 |
+
+## 错误处理
+
+- **首次跑慢**：脚本自动 `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` / `.mp4` 等视频后缀。改用 `web_record` 工具，或把后缀换成 `.png` / `.jpg`。

package/skills/{web-capture → web-screenshot}/skill.json

@@ -1,9 +1,9 @@
 {
-  "name": "web-capture",
-  "toolName": "web_capture",
+  "name": "web-screenshot",
+  "toolName": "web_screenshot",
   "tier": "tool",
   "category": "consuming",
-  "title": "Web Page Capture",
+  "title": "Web Page Screenshot",
   "description": "Drive a headless browser (Playwright Python) to capture any URL to a local STILL IMAGE (png/jpg): full-page / viewport / element / region screenshots, with device emulation, waiting, hide/mask/redact, and static annotations (highlight / arrow / caption / numbered sequence / redact). Images only — for video / recording / scroll-through / storyboard clips (webm) use the web_record tool instead.",
   "envVars": ["WEB_CAPTURE_BROWSER", "WEB_CAPTURE_OUTPUT_BASE", "WEB_CAPTURE_NO_SANDBOX", "WEB_CAPTURE_ALLOW_PRIVATE_HOSTS", "PLAYWRIGHT_BROWSERS_PATH"],
   "entry": { "type": "python", "scriptPath": "scripts/screenshot.py" },

package/skills/web-screenshot/version.json

@@ -0,0 +1,7 @@
+{
+  "skillName": "web-screenshot",
+  "repoName": "agent-skill-media-maker",
+  "skillId": "555",
+  "version": "V5",
+  "skillDescription": "网页截图技能（只出静态图片 png/jpg），基于 Playwright Python，对任意 URL 落盘到本地。支持整页 / 视口 / 元素 / 区域截图、设备模拟、等待动态内容、隐藏 / 涂盖干扰元素，以及静态注释（红框 / 箭头 / 字幕条 / 编号序列 / 打码 / 代码行高亮）。入口脚本 scripts/screenshot.py。\n\n当用户提到网页截图、整页 / 长截图、元素 / 区域截屏、给截图加注释、隐藏或打码敏感信息、代码行高亮、移动端模拟、带登录态截图等需求时，立即使用本 skill。录屏 / 分镜视频（webm）请改用 web-record / web_record。"
+}