showreel

# 展示影片 **将网址和 CSS 选择器转化为成品视觉效果 — 注释截图、流程 GIF、电影式录制和终端捕获。每个命令单独执行。代理永远不会猜测像素；每个输出在保存前都会经过像素验证。** [](https://github.com/HeyRenan/showreel/actions/workflows/ci.yml) [](showreel/.claude-plugin/plugin.json) [](LICENSE) [](https://claude.com/claude-code) [English](README.md) · [Português](README.pt-BR.md) ## 展示 [](assets/showcase.mp4) *一次拍摄，所有功能 — 抽屉、相机、放大镜、聚光灯、实时模糊、输入表单、区域选择、实时图例面板，一键部署。插件完全针对捆绑的演示页面生成。 ([点击播放完整 MP4](assets/showcase.mp4))* > 本 README 中的每个图像都是由 Showreel 自身生成的，针对捆绑的“Lumen”演示页面运行。运行相同的命令，获取相同的文件。 ## 它是什么 一个 [Claude Code](https://claude.com/claude-code) 插件，用于 **视觉文档**：用图片而不是段落解释更改、错误、功能或教程步骤。 您将其指向一个页面，并通过 **CSS 选择器**命名元素。Showreel 测量 DOM，准确地在目标上绘制注释，并在退出前 **验证结果** — 不会生成低质量的截图，而是直接报错。无需截图 → 人工校验 → 重试循环，无需像素坐标，无需浪费令牌进行猜测。 - **自包含** — 捆绑自己的无头 Chromium；无需浏览器 MCP，无需凭证，无需发送任何数据。 - **确定性** — 相同的选择器输入，相同的像素输出。放置是计算的，而不是猜测的。 - **高效** — `--batch` 在一次浏览器启动中渲染多个捕获。 ## 快速开始 ```bash # 安装 claude plugin marketplace add HeyRenan/showreel claude plugin install showreel@showreel # 一次性：检查机器 + 预热引擎 (~90MB Chromium，一次) bash ~/.claude/plugins/showreel/showreel/scripts/preflight.sh node ~/.claude/plugins/showreel/showreel/scripts/ensure-deps.mjs ``` 重启 Claude Code，然后调用 **`/showreel`** 并描述要捕获的内容。或者直接运行脚本： ```bash # 注释一个元素，经过像素验证 node scripts/prove.mjs https://example.com ".cards .card:first-child" out.png --label "服务卡验证" ``` `/showreel:guide` 打开视觉设置指南。本地文件夹安装和完整路径在 [INSTALL.md](INSTALL.md) 中。 ## 功能 每个功能，一个命令。所有脚本都位于 `showreel/scripts/` 中。代理始终使用 **选择器 + 文本**，而非像素。 | 功能 | 脚本 | 输出 | |---|---|---| | **注释证明** | `prove.mjs` | DOM 精确矩形 + 标注 + 箭头，经过像素验证 (`vcheck`) — 仅在通过时退出。标志： `--circle`， `--blur "<sel>"`， `--zoom`， `--batch jobs.json`。 | | **注释基元** | `demo.mjs` | 一个概念对应一个图像： `rect`， `circle`， `arrow`， `badge`， `blur`， `zoom`， `callout`， `label`。 `--batch` = 8 个捕获在一个启动中。 | | **流程录制** | `rec.mjs` | JSON 步骤的叙述 GIF/MP4 — 光标运动、涟漪、滚动、叙述模态、步骤时间戳。上面的英雄 GIF 就是一个调用。 | | **电影式相机** | `rec.mjs` | 真实的视口移动：页面滑动 + 缩放下动画转换。 `camera` 框定元素， `follow` 追踪光标， `inset` 是放大镜。 | | **聚光灯 / 慢动作 / 自动注释** | `rec.mjs` | `spotlight` 仅保留目标；每步骤 `speed` 减慢动画； `--auto-annotate` 概述一个裸 `click`/`fill`。 | | **实时元素** | `rec.mjs` | 一个 `glossary`/`modal` 带有 `id` 成为 **实时** — 后续 `live` 步骤在原处追加/更新/重新着色/替换/删除行，无需重建，无需闪烁。每个项目颜色，主题匹配文本。 | | **离线渲染** | `rec.mjs --offline` | 在页面的虚拟时钟上渲染 — 阅读停留时间坍缩，文本丰富的拍摄在几分之一的时间内完成。适用于静态/文本拍摄；运动爆发 (`confetti`， `sparkline`) 需要实时拍摄。 | | **终端录制** | `tape.mjs` | 通过 [vhs](https://github.com/charmbracelet/vhs) 的 CLI 证明：JSON 步骤 → `.tape` → GIF。下面的预飞行 GIF 就是一个调用。 | | **前后对比** | `compose.mjs`， `lh-ba.sh` | 两个 PNG 或两个 GIF 并排带有标签。 `lh-ba.sh` 在两个分支上运行真正的 Lighthouse。 | | **尺寸优化器** | `shrink.mjs` | 在没有可见质量损失的情况下重新编码 gif/png； `--target-kb` 走质量阶梯。这里的每个图像都经过了它。 | | **紧密裁剪** | `shot.mjs` | 只是元素，没有注释。 | ### 录制：步骤如何工作 `rec.mjs` 获取 JSON 步骤 — 每个步骤都命名一个元素和要执行的操作。脚本控制所有运动。 ```bash node scripts/rec.mjs <url> --steps-json '[ {"click":"#menu","note":"抽屉打开","badge":1,"screen":"仪表盘"}, {"scrollTo":".cards","rect":true,"glide":true,"note":"活动服务","badge":2}, {"fill":"#email","text":"dana@example.com"}, {"camera":{"sel":".kpis","zoom":1.3},"note":"构图 KPI"}, {"click":"#deploy","follow":1.6,"note":"相机追踪光标"} ]' out.gif ``` **56 个步骤键** （未知键在前端被拒绝）： - **动作** — `click, fill, text, select, option, scrollTo, scrollIn, to, hide` - **注释** — `note, arrow, badge, rect, circle, marks, glossary, inset, modal` - **相机 / 运动** — `camera, zoom, follow, glide, speed` - **强调** — `spotlight, blur, redact, highlight, pulse, ripple, shake, glow, flash` - **状态 / 数据** — `checkmark, typeon, reveal, orbit, kenburns, progress, countdown, countup, sparkline, confetti, trail` - **实时** — `live` （在步骤之间修改 `glossary`/`modal` — 追加/更新/重新着色/替换/删除） - **浏览器 / 时间** — `screen, topbar, bottombar, wait, delay, fade, stagger, accent` - **每个效果的旋钮** — `size, dur, count, intensity` **作者快速**: `--dry` 在 <1 秒内针对实时页面解析每个选择器（ `[ok]`/`[MISS]` per 步骤，无录制） — 修复错误，录制一次。 `--pace fast` 修剪约 45% 用于草稿。 `--contact-sheet` 编写一个约 24 帧的图块，以便拍摄自行审查。 ### 查看每个功能 每个功能都经过演示 — 每个图像都是插件针对演示页面生成的。 | | | | |:---:|:---:|:---:| |  |  |  | | **prove** — 注释证明 | **camera** — 视口移动 | **marks** — 子徽章 | |  |  |  | | **modal** — 叙述 | **bars** — 上下文 | **spotlight** — 仅保留目标 | |  |  |  | | **speed** — 每步骤慢动作 | **auto-annotate** — 免费大纲 | **stamp** — 步骤计数器 | |  |  |  | | **fill** — 输入文本 | **select** — 下拉选择 | **inset** — 放大镜 | |  |  |  | | **glossary** — 徽章图例面板 | **hide** — 删除元素 | **glide** — 动画滚动 | |  |  |  | | **compose** — 前后对比（动态） | **tape** — 终端捕获 | **compose** — 前后对比（静态） | **实时元素和状态** — 面板实时增长，加上完整的状态工具包： | | | | |:---:|:---:|:---:| |  |  |  | | **live** — 原位追加行 | **confetti** — 庆祝成功 | **countup** — 数字滚动 | |  |  |  | | **sparkline** — 绘制趋势 | **progress** — 滚动条 | **countdown** — 倒计时 | |  |  |  | | **pulse** — 注意力环 | **ripple** — 点击反馈 | **glow** — 激活强调 | |  |  |  | | **checkmark** — 阶段完成 | **reveal** — 新内容进入 | **flash** — 状态闪烁 | |  |  |  | | **orbit** — 工作中旋转器 | **trail** — A→B 连接器 | **shake** — 阻止/错误 | |  |  |  | | **typeon** — 流式文本 | **kenburns** — 慢速缩放 | **redact** — 隐藏敏感数据 | |  | | | | **highlight** — 标记滑动 | | | ### 注释基元 (`demo.mjs`) 八种标注样式，每个概念对应一个图像 — 所有八种样式均来自单个 `demo --batch` 启动： | | | | | |:---:|:---:|:---:|:---:| |  |  |  |  | | **rect** | **circle** | **arrow** | **badge** | |  |  |  |  | | **blur** | **zoom** | **callout** | **label** | ## 为什么它很快 在该代码库上测量（Apple Silicon，预热引擎）： | | 天真 | Showreel | |---|---|---| | 8 个注释捕获 | 8 次浏览器启动 ≈ 60 秒 | `demo --batch` ≈ **6 秒**，一次启动 | | 注释放置 | 读取 PNG → 猜测像素 → 重试 | 确定性 `autoplace`， **0 重试** | | 暗/亮页面上的对比度 | 手动颜色选择 | **自适应** 页面亮度 | | 重叠注释 | 手动调整 | **冲突感知**，永远不会覆盖目标 | ## 它如何工作 代理发送选择器 + 文本。引擎（`scripts/.deps/` 中的自包含 Chromium）测量 DOM，确定性地放置每个注释（`lib/autoplace.mjs`），并在保存前自我验证（`vcheck`）— 因此没有猜测/重试循环。网页捕获通过 Chromium 进行；终端捕获通过 `vhs` 进行。 `rec.mjs` 是模块化的：单一职责模块（`rec-steps`、`cam-inject`、`rec-camera`、`rec-motion`、`rec-annotate`、`rec-input`、`rec-encode`、`rec-page`）在一个时钟上运行，使实时和离线成为同一时间合同的两个实现。 ## 需求 node 18+。可选：`ffmpeg`（最佳 GIF 质量），`vhs`（终端录制）。无需 git，无需令牌，无需配置。 `preflight.sh` 打印任何缺失内容的确切设置命令。完整的矩阵在 [INSTALL.md](INSTALL.md) 中，版本历史在 [CHANGELOG.md](CHANGELOG.md) 中。 ## 测试 ```bash cd showreel && node --test 'scripts/__tests__/*.test.mjs' # 无网络或浏览器 ``` ## 许可证 [MIT](LICENSE)