网页工具介绍片

何时用

先按输入形态选技能 —— 这是最容易选错的一步。

判据一句话：有现成视频文件要剪，就走 hsf 系；素材是「链接或静态图」，才走本技能。 别硬套：hsf 系第一步就要一个录屏路径（抽帧聚类切段），喂链接跑不起来。

渲染底座同源（截图/切片 → PIL 图层 → ffmpeg 直管出片），但视觉语言各成一套（本技能是 「深色画布 + 屏幕块 + 逐行点亮字幕」，chatcut 是「黑科技底 + 1:1 画中画 + 紫蓝霓虹描边」）， 不要混用版式。

---

环境

# 用 WorkBuddy 托管的 Python（路径随用户名/系统而变，用 ~ 代替用户名）：
#   Windows: %USERPROFILE%\.workbuddy\binaries\python\envs\default\Scripts\python.exe
#   其它:    ~/.workbuddy/binaries/python/envs/default/bin/python
# 下面这行会自动算出本机正确路径，直接复制用即可：
PY=$(python -c "import os,sys;print(os.path.expanduser('~/.workbuddy/binaries/python/envs/default/Scripts/python.exe' if sys.platform=='win32' else '~/.workbuddy/binaries/python/envs/default/bin/python'))")

依赖见 requirements.txt，首次使用先装：$PY -m pip install -r requirements.txt （edge-tts pillow numpy imageio-ffmpeg mutagen）。 浏览器：脚本自动探测 Edge；找不到时回退 Chrome/Chromium。可用环境变量 WB_EDGE 强制指定浏览器路径；macOS / Linux 上若没 Edge 需自行安装或设 WB_EDGE。

这个 bash 环境缺 coreutils（没有 ls/head/mkdir/dirname），所有文件操作走 Python。 中文路径不要经 shell 传参（-c 里写中文字符串做比对会因编码丢失匹配失败），要改文件用编辑器工具。

---

推荐工程化入口（v1.1）

新片优先初始化一个独立工程目录，不要直接在 skill 包里产出素材：

$PY <skill-dir>/scripts/init_project.py --output <video-dir> \
  --tool-name "工具名" --url "https://example.com/tool" \
  --page-type unknown --accent "#ff7a3d"

初始化会生成：plan.json、BRIEF.md、ref/、shots/、audio/、out/、evidence/，并复制可编辑脚本。 随后在 <video-dir>/scripts/ 里改 mkshots.py / tts.py / render.py。

先跑环境检查，只修报告出来的缺项，不要盲装：

$PY scripts/check_environment.py --project . --output evidence/environment.json

plan.json 是轻量总表：记录工具名、页面类型、画幅、主色、合规要求、镜头、旁白和字幕断句。 v1.2 起：tts.py 会优先读取 plan.voice / plan.lines；render.py 会优先读取 plan.accent / panelBg / cover / end / shots / subs。复杂镜头仍可直接改 render.py。 正式交付前运行：

$PY scripts/check_delivery.py --project . --video out/video.mp4 --output evidence/delivery-check.json

它会检查 plan / timeline / MP4 的结构、分辨率、帧率、音轨、时长窗口和字幕断句连续匹配；但不替代人工看片、听音和合规审查。

---

六步流程

1. 抓页面、摸清结构

urllib.request 抓 HTML → 存 ref/page.html

要摸出三件事：

• 交互模型：是「表单填值 + 点按钮出结果」，还是「多步向导」（.step + show(n)）？

• 状态变量：表单页找 getElementById 的 id 列表；向导页找全局状态对象（如 var S={...}）和 show/next/selField 之类函数。

• 配色：读 :root 变量，拿到主色（--accent），后面视频强调色跟它走。

先判断页面形态，它决定截图策略：

卡片总览型（如「工具包总览页」，6 个模块各一张卡）是最特殊的一种：

• 页面本身没有交互，截图一次就够，但一屏能装 3 张卡，靠"卡片居中"建立不了焦点

• 因此镜头逻辑改成：每镜给目标卡套 hl，再 draw_focus() 把其余卡压暗（见第 5 步）

• 旁白不要按页面编号顺序讲 —— 按"人群/阶段"串，一个模块一句话，

天然覆盖"它解决什么问题、谁该用"。顺序与页面一致时镜头只往下走，不会来回跳

单页切换型（如「卖点提炼」，① 验证已有卖点 / ② 生成新卖点方案）：

比同一个源里做交叉淡化更像真实交互

• 状态切换处用硬切而不是渐变 —— 换 src（第二张截图）就等于"用户点了一下"，

• 两种状态的内容长度常不一样（说明文案 3 行 vs 2 行），会让下方所有元素整体位移。

别去维护两套坐标 —— 在本地副本注入一句 #copy-build{min-height:99px} 把 两块拉成等高，两态几何就对齐了，全片共用一套 oy（见第 2 步「几何拉平」）

长表单型的 oy 合法范围 = [PH - N, 0]（N = 截图高）。先在截图上扫出各 panel 的 y 区间， 再按「每镜覆盖约 PH 高度、相邻镜推进 150~400px」排镜头 —— 这个节奏既不呆滞也不会大跳。

2. 造状态变体 + headless 截图

scripts/mkshots.py 是模板：生成本地副本（不动线上）→ 往 </body> 前注入状态脚本 → 逐个截图 → 按背景色差自动裁掉底部空白。

CASES = [("intro", "..."), ("s1_loc", "..."), ...]   # 每个镜头状态的注入 JS
EDGE ... --headless=new --force-device-scale-factor=2 --window-size=520,2600 \
        --virtual-time-budget=5000 --screenshot=xxx.png  file:///本地副本.html

改状态必须派发事件 —— 宿主页面的监听器绑在元素上（addEventListener('input'/'change')）， 直接改 el.value 不会触发重算。统一走这三个小工具，在注入脚本里预置：

function _ck(id){ var el=document.getElementById(id); el.checked=true; el.dispatchEvent(new Event('change')); }
function _sv(id,v){ var el=document.getElementById(id); el.value=v; el.dispatchEvent(new Event('input')); }
function _pill(sel,i){ document.querySelectorAll(sel)[i].click(); }

要出哪些状态：总览/首页 → 每个关键步骤的「已填/已选」态 → 最终结果页，一般 7~9 张； 长表单型则只需「默认态 + 最坏态」两张。

排镜头前必须拿到每个区块的精确 y 坐标。两种办法，首选第二种：

# 办法一：按背景色差扫（长表单型够用）
a = np.asarray(im.convert("RGB")).astype(int)
isbg = (np.abs(a - np.array([244, 244, 246])).sum(axis=2) < 20).mean(axis=1) > 0.97
# isbg 为 False 的连续段 = 各 panel 的 (y0, y1)，留高度 > 40 的

# 办法二（可靠，坐标一目了然）：洋红 outline 标记 + 检测
# 注入：.hero,.card{outline:4px solid #ff00ff !important;outline-offset:0 !important}
# 截图后检测：mag = (R>180) & (B>180) & (G<110)；每行 mag 占比 > 0.5 即为一条边界线
# 聚类相邻行 -> 每 2 条 = 一个元素的 (top, bottom)

# 办法三（最省事，精确到 1px，首选）：scripts/probe_rect.py
#   py probe_rect.py 本地副本.html 520 3400 h1 .modes .frame-box iframe .deep
# 原理：注入脚本把 getBoundingClientRect() 写进 DOM，再 --dump-dom 读回来。
# 不截图、不做图像处理，直接打印「逻辑 y -> 物理 y（×2）」对照表。

几何拉平：单页切换型 / 多状态页里，若某个状态的内容少一行，它下面所有元素会整体上移， 逼你为每个状态维护一套坐标。别这么干 —— 在本地副本里给短的那块注入一句 min-height:（取长的那块的高度），两态几何就完全对齐，全片共用一套 oy。

裁顶要留够余量：裁掉页面导航栏时，不要裁到紧贴第一个卡片的上缘 —— 留 30~40px 页背景，否则卡片的圆角上缘和阴影会被面板顶边切平，看着像"页面从中间开始"。 先探测出第一个元素的 top，再把裁线定在它上方 30px 左右。

2b. 嵌入第三方内容（问卷 iframe）怎么处理

页面主体是 <iframe src="https://wj.qq.com/...">（腾讯问卷 / 问卷星 / 金数据等）时：

加载转圈。iframe 里的表单是二级文档，虚拟时间下它的 JS 起不来。别在这上面耗时间。

• headless 截不到 iframe 本体 —— 给足 --virtual-time-budget=9000 也只截到一个

--window-size=600,2800。宽度别用 520 —— 这类表单常有 ~750px 的最小宽度， 视口窄于 ~600 时头部标题会溢出裁切，问题文案也会被切半。

• 改截「问卷页本身」：把 iframe 的 src 当普通 URL 直接截（同一份表单，独立打开），

底部「XX 提供技术支持」+ 隐私声明/举报链接。红色提示条必须裁掉，放进片子里很吓人； 底部平台署名属于第三方品牌，一律不入画。

• 裁掉平台自己的东西：顶部红色提示条（"当前问卷可能含有敏感内容…"）、

取 min 而不是"按宽铺满"，否则底部的「提交」按钮会被框的下沿切掉一半。 差额（此时表单比框窄几十像素）留在两侧 —— 表单底就是白色，看不出来。 裁切范围用 mkshots.py 里的常量写死（如 FORM_CROP = (90, 3480)），别每次重算。

• 等比贴回 iframe 区：k = min(框宽/表单宽, 框高/表单高) ——

• 合成完 必须目视核对：表单头部完整、无平台署名、提交按钮完整。

3. 写旁白稿（先定字数，再动笔）

时长靠字数控制，不要靠调语速。

• 基准：zh-CN-YunyangNeural + RATE=+4% ≈ 4.9 字/秒（含标点）

• 10 句、句间静音 0.28s → 目标 260 字 ≈ 60 秒

• 要带结尾卡台词就是 11 句 → 275 字 ≈ 58.5 秒（末句留给结尾卡，写纯主张、别放数字）

• 写完先跑 tts.py 看总长，超了就从长句里删字，删到 59~60s

句子结构：封面钩子 → 引子 → 每步一句（动词开头）→ 结果 → 收尾金句。 默认一镜一句。遇到 "一句话点名一长串条目" 的句子就拆成两镜（见第 5 步「同句拆镜」）， 否则那句会有 7 秒以上画面几乎不动。

文案强化四招 —— 首稿"讲清楚了"不等于"说得动"，交付前按这四刀再过一遍：

另三条铁律：

• 收尾句不放新信息、不放数字 —— 只回扣钩子。带数字的收尾会让观众以为还有下文。

例：① 验证已有卖点 / ② 生成新卖点方案 两个按钮，首稿把 ② 写成「让工具从零长出一套 能站住的卖点」，观众会理解成不用填表、系统自动生成；而页面 .lead / .note 原文写的是 「选一种，填完报告发你邮箱」—— 两条路都是「填同一份问卷 → 报告自动发邮箱」， 差别只在"你怎么答"。凡「都要 / 自动 / 免费 / 几分钟内」这类共性条件， 一律对着 .lead / .note / .mode-copy 抄，不要从按钮名反推路径。 修法：把共性条件单独起一句（本例「两种用法都要填这份问卷，填完提交，报告自动发到你邮箱。」）， 且这一句的镜头要同时框住「机制提示块 + 表单头部」，让画面替口播作证。

• 多模式工具的「操作路径」必须回页面原文逐条核 —— 模式名只讲结果、不讲路径。

• 改文案必须同步改三处：LINES（旁白）、SUBS（字幕断句）、COVER_* / END_*（卡片字）。

SUBS 的每行必须是新句子的连续子串且前后有序，否则 sub_block() 里 text.find() 落空会 静默错位（不报错、字幕亮错行）。改完先跑断句校验，再配音：

# 断句自检：改完 LINES/SUBS 先跑这个，全 OK 再 synth
for ln in tl["lines"]:
    rows = R.SUBS.get(ln["idx"]) or []
    cur = 0
    for r in rows:
        p = r.replace("{", "").replace("}", "")
        i = ln["text"].find(p, cur)
        assert i >= 0, ("MISS", ln["idx"], p)
        cur = i + len(p)

4. 配音 + 时间轴

scripts/tts.py：优先读取 plan.json 的 voice 和 lines；缺失时用脚本内置示例。 逐句 edge-tts 合成 → ffmpeg 拼成 out/voice.m4a，写项目根目录 timeline.json （每句含 idx/text/file/start/end/dur/words，顶层含 total）。

5. 逐帧渲染

scripts/render.py 是模板。v1.2 起优先读取 plan.json 的主色、封面/结尾、shots 和 subs；复杂镜头仍可直接改脚本。核心参数（改这几处就能复用）：

W, H, FPS = 1080, 1920, 30
PANEL   = (22, 104, 1058, 1500)      # 内容面板；上方 104px 留给标签 + 进度条
SRC_W   = 1040                       # 截图物理宽（2x 设备像素 → 逻辑 520）
PANEL_BG= (246,247,249)              # 页面底色，填留白
ACCENT  = (255,122,61)               # ← 换成该工具的主色
SHOTS   = [dict(line=0, kind="cover"), dict(line=1, src="intro", oy=-16, oy2=-112), ...]
SUBS    = {1: ["验车有检查单，", "选址也该有份{写字楼}。"], ...}   # {} 内为高亮

oy 是「截图相对面板左上角的偏移」，负值 = 画面往上走；合法范围 [min(0, PH-N), max(0, PH-N)]

• 截图 1:1 满宽（不缩放，保证文字锐利），只做纵向 oy 平移；

• 用圆角 mask 把截图裁成「屏幕块」（浅色页面在深色画布上，直角会很脏）

• 底部逐行点亮字幕，字号 46，最后一行不固定、按行数在 SUB_CENTER_Y 附近居中

• 封面/结尾卡走 render_card（径向渐变底 + 大标题 + 描边标签）

• 帧序列直接管道喂 ffmpeg：-f rawvideo -pix_fmt rgb24 -s 1080x1920 -r 30 -i -，不要落盘 PNG 序列

• 先跑 scripts/preview.py 出关键帧网格看构图，再全片渲（约 90~250ms/帧）

同句拆镜（一个 line 拆成多个镜头，不动配音、不改时间轴）：

dict(line=2, at=0.00, src="main", oy=-120, oy2=-160, subs=["第一关硬门槛，", "{五条一票否决}："]),
dict(line=2, at=0.36, src="main", oy=-150, oy2=-175, subs=["排烟电力上下水、油烟、", "{时段错配、证照}、商圈衰退。"]),

at = 切分点（相对该句时长的比例），subs = 该镜只显示这几行。 build_spans() 会把分镜表折算成 [(t0,t1)]；镜头内的进度 e 按本段时长算，不是按整句 —— 所以第二个子镜的开头不会已经"走完位移"。拆镜只动 SHOTS，一句改两镜不用重跑 TTS。

高亮框（给静止画面造落点，用来解决"页面滚到底了、画面没法再动"的镜头）：

dict(line=9, oy=-4254, oy2=-4254, hl=(5390, 5610, 50, 955)),        # 固定框：圈住结论区
dict(line=2, at=0.36, ...,                                           # 跟读框：念一条框一条
     seq=[(0.00,(576,695)), (0.32,(688,807)), (0.44,(800,919))], seqx=(48, 958)),

• 框坐标用截图像素（(y0,y1,x0,x1)），draw_marks() 会按当前 oy 换算到面板坐标

• 框层要用 ImageChops.multiply(..., panel_mask()) 裁一次，否则框线会溢出圆角面板

• seq 的进度点按旁白字符比例折算（见第 4 步），别按均分 —— 均分跟念到哪条对不上

• 长句「点名一长串条目」的场景，seq + 拆镜是最高性价比的组合：画面 7 秒不再死板

压暗非当前区域（一屏装了多张卡 / 多个区块时必需，draw_focus()）：

# 整块铺半透明黑，再把当前卡的圆角矩形"挖空"（挖空区做高斯羽化，避免硬边）
ov  = Image.new("RGBA", (PW, PH), (0,0,0,0)); ImageDraw.Draw(ov).rectangle([...], fill=(8,6,5,120))
hole= Image.new("L", (PW, PH), 255); ImageDraw.Draw(hole).rounded_rectangle([...], radius=26, fill=0)
hole= hole.filter(ImageFilter.GaussianBlur(24))

• 只在有 hl 的镜头上压暗；总览镜（无 hl）保持全亮，让观众先看全貌

• 透明度 120/255（约 47%）刚好：焦点明确，但被压暗的卡依然读得出是"上下文"

• 挖空区比 hl 各边多留 18px，配合 24px 羽化，过渡才自然

6. 出片 + 验收

$PY scripts/render.py            # 后台跑，2~4 分钟
$PY scripts/check_delivery.py --project . --video out/video.mp4 --output evidence/delivery-check.json

验收四条：

• check_delivery.py 必须无 errors；warnings 要逐条判断是否可接受

• 抽 10 帧拼网格，确认无黑帧、字幕位置对、每镜构图成立

• 看最终 MP4，而不是只看 preview；确认无裁切、无 URL/二维码/私域 CTA 泄漏

• 听最终 MP4；确认旁白完整、无长静音、结尾不突兀

最后把 out/video.mp4 复制到工作区根目录，命名 <工具名>_60秒介绍片.mp4（品牌后缀按需要自行加；规格 1080x1920 / 30fps / H.264+AAC 不写进文件名）。

---

交付物

• <工具名>_60秒介绍片.mp4（品牌后缀按需要自行加；规格 1080x1920 / 30fps / H.264+AAC 不写进文件名）

• 工程目录：plan.json、BRIEF.md、ref/（页面 HTML）、shots/（各状态截图 + 本地副本）、audio/（分段 mp3）、out/（成片与 voice.m4a）、evidence/（环境与交付检查报告）

• 可重跑脚本：scripts/mkshots.py、scripts/tts.py、scripts/render.py、scripts/check_environment.py、scripts/check_delivery.py

常见问题