@remixmate/cli 0.9.14 → 0.9.16

package/skills/web-screenshot/SKILL.md

@@ -1,56 +1,53 @@
 ---
 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。
+  Web-page screenshot skill (still images only, png/jpg), built on Playwright Python — captures any URL to a local image file.
+  Supports: full-page / viewport / element / region capture, device emulation, waiting for dynamic content, hiding or masking distracting elements, and static annotations (highlight box / arrow / caption / numbered sequence / redact / code-line highlight).
+
+  Images only (`.png` / `.jpg`). For video (`.webm` / screen recording / storyboard clips) use web-record / `web_record`.
+
+  Use this skill immediately whenever the user asks for any of:
+  - Web page screenshot, screen capture, full-page screenshot, long screenshot
+  - Capture a specific element / region, partial screenshot, focus on an area
+  - Hide or mask elements before capturing (cookie banner, sensitive information)
+  - Annotate a still screenshot (highlight box / arrow / label / caption bar / numbering)
+  - Highlight lines L5-L20 of a file and screenshot it
+  - Wait for an element to appear, then capture
+  - Mobile / device-emulated screenshot (iPhone / Pixel, etc.)
+  - Capture with cookies / a logged-in session / storageState
+
+  Even when the user does not say "playwright", any request to screenshot a URL and get a local image file should route here.
 triggers:
-  - 网页截图、网页截屏、整页截图、长截图、full page screenshot
-  - 截某个元素 / 区域、局部截屏、focus 某个区域
-  - 截图前隐藏元素 / 涂盖打码、给静态截图加注释（红框 / 箭头 / 标签）
-  - 高亮某文件的 L5-L20 代码行并截图
-  - 移动端 / 设备模拟截图、带 cookie / 登录态截图
+  - Web page screenshot, screen capture, full-page screenshot, long screenshot
+  - Capture a specific element / region, partial screenshot, focus on an area
+  - Hide or mask elements before capturing, annotate a still screenshot (highlight box / arrow / label)
+  - Highlight lines L5-L20 of a file and screenshot it
+  - Mobile / device-emulated screenshot, capture with cookies / a logged-in session
 ---
 
-# 网页截图 Skill（web_screenshot）
+# Web Screenshot Skill (`web_screenshot`)
 
-入口脚本 **`scripts/screenshot.py`**，纯 Python 实现，输出 **`.png` / `.jpg`**。整页 / 视口 / 元素 / 区域。
+Entry script **`scripts/screenshot.py`**, pure Python, outputs **`.png` / `.jpg`**. Full page / viewport / element / region.
 
-> **只出图片。** 录屏 / 分镜视频（`.webm`）走 **web-record / `web_record`**——传 `--output xxx.webm`
-> 到本 skill 会被直接拒绝并提示改用 `web_record`。录屏入口脚本 `scripts/record.py` 与本 skill 同处
-> 一个目录（两者共享下面的 `_media_screenshot/` 包），但它属于 web-record 这个工具，用法见
-> **`skills/web-record/SKILL.md`**。
+> **Still images only.** Screen recording and storyboard video (`.webm`) go through **web-record / `web_record`** — passing `--output xxx.webm` to this skill is rejected outright with a pointer to `web_record`. The recording entry script `scripts/record.py` lives in this same directory (both share the `_media_screenshot/` package below), but it belongs to the web-record tool; see **`skills/web-record/SKILL.md`** for its usage.
 
-底层共享 **`scripts/_media_screenshot/`** 包，封装 Playwright Python API + 所有浏览器侧 JS 注入（overlay / zoom / scroll 等）。
+Both share the **`scripts/_media_screenshot/`** package underneath, which wraps the Playwright Python API plus every browser-side JS injection (overlay / zoom / scroll, etc.).
 
-> 路径约定：读取系统注入的 `Base directory for this skill: <path>` 作为 `<SkillDir>`，命令里的 `<SkillDir>` 替换为该路径，切勿硬编码绝对路径。`python` 在 macOS 上可能需写成 `python3`。
+> Path convention: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>` and substitute it for `<SkillDir>` in the commands below. Never hardcode an absolute path.
 
-## 前置依赖
+## Prerequisites
 
 - **Python 3.9+**
-- **`playwright` pip 包 + chromium 内核**：首次运行**自动 bootstrap**——脚本检测到缺包会执行 `pip install playwright` + `playwright install chromium`。
-  - 也可提前手动装：
+- **The `playwright` pip package + the chromium engine**: the first run **bootstraps automatically** — when the script detects the package is missing it runs `pip install playwright` + `playwright install chromium`.
+  - You can also install it up front:
     ```bash
     pip install playwright
     playwright install chromium
     ```
 
-## 截屏 `screenshot.py`
+## Capturing with `screenshot.py`
 
-### 最小用法
+### Minimal usage
 
 ```bash
 python3 <SkillDir>/scripts/screenshot.py \
@@ -58,7 +55,7 @@ python3 <SkillDir>/scripts/screenshot.py \
   --output "example.png"
 ```
 
-### 整页截图
+### Full-page screenshot
 
 ```bash
 python3 <SkillDir>/scripts/screenshot.py \
@@ -67,9 +64,9 @@ python3 <SkillDir>/scripts/screenshot.py \
   --full-page
 ```
 
-### 元素截屏（局部 focus）
+### Element capture (focus on one part)
 
-按 CSS 选择器截**元素本身**（自动 `scrollIntoViewIfNeeded`）：
+Capture **the element itself** by CSS selector (automatically `scrollIntoViewIfNeeded`):
 
 ```bash
 python3 <SkillDir>/scripts/screenshot.py \
@@ -79,18 +76,18 @@ python3 <SkillDir>/scripts/screenshot.py \
   --wait-for-selector ".card.featured"
 ```
 
-如不希望自动滚动：加 `--no-scroll-into-view`。
+To suppress the automatic scroll, add `--no-scroll-into-view`.
 
-### 区域截屏（像素矩形 clip）
+### Region capture (pixel clip rectangle)
 
 ```bash
-# 全页像素坐标
+# Full-page pixel coordinates
 python3 <SkillDir>/scripts/screenshot.py \
   --url "https://example.com" \
   --output "region.png" \
   --clip "100,200,600,400"     # x, y, w, h
 
-# 以元素为基点偏移裁剪（先 scrollIntoView 该元素，再用其 boundingBox 起点 + 偏移裁剪）
+# Clip relative to an element (scrolls the element into view first, then clips from its boundingBox origin plus the offset)
 python3 <SkillDir>/scripts/screenshot.py \
   --url "https://example.com" \
   --output "region_in_card.png" \
@@ -98,7 +95,7 @@ python3 <SkillDir>/scripts/screenshot.py \
   --clip "0,0,300,180"
 ```
 
-### 移动端 / 设备模拟
+### Mobile / device emulation
 
 ```bash
 python3 <SkillDir>/scripts/screenshot.py \
@@ -108,7 +105,7 @@ python3 <SkillDir>/scripts/screenshot.py \
   --full-page
 ```
 
-自定义 viewport：
+Custom viewport:
 
 ```bash
 python3 <SkillDir>/scripts/screenshot.py \
@@ -117,34 +114,34 @@ python3 <SkillDir>/scripts/screenshot.py \
   --viewport "1440,900"
 ```
 
-### 等待动态内容
+### Waiting for dynamic content
 
 ```bash
-# 等待选择器出现
+# Wait for a selector to appear
 python3 <SkillDir>/scripts/screenshot.py \
   --url "https://example.com" \
   --output "ready.png" \
   --wait-for-selector "main .loaded" \
   --timeout 30000
 
-# 固定延时（适合纯前端动画）
+# Fixed delay (good for pure front-end animation)
 python3 <SkillDir>/scripts/screenshot.py \
   --url "https://example.com" \
   --output "delayed.png" \
   --wait-for-timeout 2000
 ```
 
-### 隐藏 / 涂盖元素
+### Hiding / masking elements
 
 ```bash
-# 隐藏 cookie banner、登录浮层等干扰元素（可重复）
+# Hide cookie banners, login overlays and other distractions (repeatable)
 python3 <SkillDir>/scripts/screenshot.py \
   --url "https://example.com" \
   --output "clean.png" \
   --hide-selector ".cookie-banner" \
   --hide-selector "#login-modal"
 
-# 涂盖敏感信息（Playwright 原生 mask，默认粉色，可自定义颜色）
+# Mask sensitive information (Playwright's native mask, pink by default, color customizable)
 python3 <SkillDir>/scripts/screenshot.py \
   --url "https://app.example.com/dashboard" \
   --output "redacted.png" \
@@ -153,9 +150,9 @@ python3 <SkillDir>/scripts/screenshot.py \
   --mask-color "#222"
 ```
 
-### 静态截图加注释（红框 / 箭头 / 字幕 / 编号 / 打码）
+### Annotating a still screenshot (highlight box / arrow / caption / numbering / redact)
 
-`--annotate` 接受一份 JSON（路径或字符串），里面用 storyboard 的场景类型描述要画的注解。所有场景在截屏前一次性画好。
+`--annotate` takes a JSON document (file path or inline string) describing the annotations to draw, using the storyboard scene types. Every scene is drawn once, before the capture.
 
 ```bash
 python3 <SkillDir>/scripts/screenshot.py \
@@ -164,31 +161,31 @@ python3 <SkillDir>/scripts/screenshot.py \
   --annotate annotate.json
 ```
 
-`annotate.json` 示例：
+Example `annotate.json`:
 
 ```json
 {
   "annotations": [
     { "type": "highlight", "selector": "strong[itemprop=\"name\"] a",
-      "color": "#ff3b30", "label": "看这里" },
+      "color": "#ff3b30", "label": "Look here" },
     { "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": "caption", "text": "Project home page", "position": "bottom" },
     { "type": "redact", "selectors": [".user-email"], "mode": "blur" }
   ],
   "settleMs": 900
 }
 ```
 
-> 顶层也可以直接是数组：`[{"type": "highlight", ...}]`。`settleMs` 是画完后等动画稳定再截屏的时长，默认 900ms。
+> The top level may also be a bare array: `[{"type": "highlight", ...}]`. `settleMs` is how long to let animations settle after drawing before capturing; it defaults to 900ms.
 
-### 带登录态截屏
+### Capturing with a logged-in session
 
-两种方式，二选一：
+Two options, pick one:
 
-**A. 直接传 storageState（推荐）**
+**A. Pass storageState directly (recommended)**
 
 ```bash
 python3 <SkillDir>/scripts/screenshot.py \
@@ -197,9 +194,9 @@ python3 <SkillDir>/scripts/screenshot.py \
   --storage-state "./auth.json"
 ```
 
-> `auth.json` 可由 `npx playwright codegen --save-storage=auth.json <url>` 在登录后导出。
+> `auth.json` can be exported after logging in via `npx playwright codegen --save-storage=auth.json <url>`.
 
-**B. 仅传 cookies JSON**
+**B. Pass a cookies JSON only**
 
 ```bash
 python3 <SkillDir>/scripts/screenshot.py \
@@ -208,7 +205,7 @@ python3 <SkillDir>/scripts/screenshot.py \
   --cookies "./cookies.json"
 ```
 
-cookies 顶层必须是数组，每项遵循 Playwright cookie 格式：
+The cookies top level must be an array, each entry following the Playwright cookie format:
 
 ```json
 [
@@ -216,40 +213,40 @@ cookies 顶层必须是数组，每项遵循 Playwright cookie 格式：
 ]
 ```
 
-### screenshot.py 参数
+### `screenshot.py` flags
 
-| 参数 | 说明 | 默认 |
-|------|------|------|
-| `-u` / `--url` | 目标 URL（必填） | — |
-| `-o` / `--output` | 本地输出路径 | `screenshot.png` |
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-u` / `--url` | Target URL (required) | — |
+| `-o` / `--output` | Local output path | `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`。
+| `--device` | Device-emulation name | none |
+| `--viewport` | `"width,height"` | none |
+| `--full-page` | Capture the whole scrollable page | off |
+| `--selector` | Capture the element itself | none |
+| `--clip` | `"x,y,w,h"` region capture; combined with `--selector` it offsets from the element's boundingBox | none |
+| `--no-scroll-into-view` | In selector mode, disable the automatic scroll | off |
+| `--wait-for-selector` | Wait for this selector before acting | none |
+| `--wait-for-timeout` | Fixed wait before acting (ms) | none |
+| `--color-scheme` | `light` / `dark` / `no-preference` | none |
+| `--user-agent` | Override the User-Agent | none |
+| `--timeout` | Playwright global timeout (ms) | none |
+| `--ignore-https-errors` | Ignore certificate errors | off |
+| `--storage-state` | storageState JSON file path | none |
+| `--cookies` | cookies JSON string or file | none |
+| `--hide-selector` | `display:none` this selector before capturing (repeatable) | none |
+| `--mask-selector` | Mask this selector with Playwright's native mask (repeatable) | none |
+| `--mask-color` | Mask fill color | Playwright pink |
+| `--annotate` | Annotation JSON file or string (array or `{annotations, settleMs}`) | none |
+
+## Error handling
+
+- **The first run is slow**: the script auto-runs `pip install playwright` + `playwright install chromium`. Wait it out once.
+- **`Cannot find module 'playwright'` / `ModuleNotFoundError: playwright`**: the bootstrap did not complete; run `pip install playwright && playwright install chromium` manually.
+- **`Executable doesn't exist`**: the browser engine is missing; run `playwright install chromium` (the script usually triggers this itself).
+- **`Timeout ... exceeded`**: raise `--timeout` / `--wait-for-timeout`, or switch to a more reliable `--wait-for-selector`.
+- **Blank capture / page not finished rendering**: add `--wait-for-selector` on a key element; for pure animation use `--wait-for-timeout`.
+- **`selector "X" has no bounding box`**: the element exists but is invisible or zero-sized; wait for visibility with `--wait-for-selector` first.
+- **Session expired**: re-export `storageState` or update the cookies JSON — `domain` / `path` must match.
+- **HTTPS certificate errors**: in test environments add `--ignore-https-errors`.
+- **"The screenshot entry only emits still images"**: `--output` used a video extension such as `.webm` / `.mp4`. Switch to the `web_record` tool, or change the extension to `.png` / `.jpg`.

package/skills/web-screenshot/version.json

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