图书短视频矩阵

品类边界（与相邻图书类 skill 的分工）

已废弃、不要单独触发：hsf-shipintuiguang（金句三段式与 OCR 喂料已并入本 skill）。

把「一次性的视频制作」变成「可移动、可复用的账号矩阵工作区」，同时内置一套已验证的金句拆书成片引擎，让矩阵里的每条视频都带拆书级文案质量 + 高清画面 + 对齐字幕。

不可违反的规则

• 所有写入配置的素材路径必须相对于账号目录。不得把绝对路径写入 workspace.yaml、account.yaml、book.yaml、日志或导出清单。

• API Key 只从进程环境或工作区 .env.local 读取；不得回显、复制到模板或提交到版本库。

• 不捆绑字体、音乐、视频、参考声音或账号凭据。只创建空素材目录。

• 先检查当前 Agent 实际拥有的工具。不得假装某阶段已经完成，也不得擅自安装大型依赖、下载模型或调用付费接口。

• 默认在文案、图片、预览三个节点等待确认。不得自动发布到社交平台。

• 书籍内容以事实摘要、观点提炼和原创表达为主，不复制大段原文。提醒用户只使用有权使用的声音、字体、图片、音乐与视频。

• 历史/传记/纪实类书：人名、年代、岁数、子嗣、金句出处必须核查原文，不能凭印象编（见 references/写稿规范.md）。

入口判断

• 用户指定工作区时使用其指定位置；否则使用当前项目下的 hsf-book-video-workspace。

• 若工作区不存在，进入「首次初始化」。

• 若工作区存在但账号不明确：只有一个账号时使用它；多个账号时询问目标账号。

• 用户给出书名后进入「单书生产」；用户只要求规划目录、增加账号或检查状态时，只完成对应管理任务。

• 已存在的配置不要重复询问。只询问会改变结果且无法从文件或工具发现的信息。

工作区契约

即使模板或脚本不可用，也必须能按下面的结构直接创建：

hsf-book-video-workspace/
├── workspace.yaml
├── .env.local
├── .gitignore
└── accounts/
    └── <account-id>/
        ├── account.yaml
        ├── production.csv
        ├── shared/
        │   ├── intro/
        │   ├── bgm/
        │   ├── voice-reference/
…（完整代码见技能源码）

最小账号配置必须覆盖这些边界：

account_id: account-01
platform: xiaohongshu
video:
  width: 1080
  height: 1920
  target_duration_seconds: 40
  intro: ""
  opening:
    title_format: "《{book_title}》"
  intro_to_main_transition:
    type: glitch
    duration_seconds: 0.35
…（完整代码见技能源码）

配置优先级

发生冲突时严格按以下顺序取值：

• 当前对话中用户明确提出的新要求。

• 本书 book.yaml 的临时覆盖项。

• 账号 account.yaml 的长期规则。

• 工作区 workspace.yaml 的工具选择。

• 本 Skill 的通用默认值。

用户确认某项以后都要沿用时，更新账号配置；只影响当前书时，写入 book.yaml。

首次初始化

• 创建工作区和 .gitignore，确保 .env.local 被忽略。

• 创建账号 ID；ID 只使用小写字母、数字和连字符。

• 收集并保存账号长期规则：平台、画幅、目标时长、片头、标题、转场、声音、BGM、字幕、图片风格和确认节点。

• 把用户提供的共享素材复制到相应 shared/ 目录，再在配置中记录相对路径。

• 检查研究、图片、TTS、转录、混音和渲染能力，把选择写入 workspace.yaml 或 account.yaml。默认渲染器与 TTS = 本 skill 自带 hsf 引擎（见下），无需额外配置 key。

• 运行工作区校验。

如果 Python 可用，可从 Skill 根目录运行可选脚本：

python scripts/workspace.py init --root ./hsf-book-video-workspace
python scripts/workspace.py add-account --root ./hsf-book-video-workspace --id account-01
python scripts/workspace.py validate --root ./hsf-book-video-workspace

没有 Python 时直接用文件工具创建相同结构。

单书生产

1. 建立任务

• 接收目标账号、书名和作者；作者未知时允许留空，但研究阶段要核实。

• 创建递增三位编号和安全目录名，生成 book.yaml，在 production.csv 新增一行。

• 若同一账号已存在同名书，继续已有任务，不覆盖文件。

2. 研究与文案（默认引擎 = 金句三段式）

• 优先使用已配置的读书或搜索工具；也可用用户提供的书摘、笔记、资料，或用 ocr_points.py（RapidOCR）把「观点长图」抠成素材库。

• 把来源、事实摘要和资料缺口写入 01-research/sources.md。

• 文案按 references/写稿规范.md 的金句三段式 + 黄金 8 镜写作（这是本 skill 默认文案引擎，取代 factory 的「自然口播」泛要求）：

• 主线一句话 + 3~5 个反直觉精华 + 一个可复用「镜片」；

• 每镜 caption（旁白原句，用于配音+字幕）+ sub（观点钉短句）；

• 核心金句放「转折/点化」情节节点，标题/正文/结尾用一个核心意象贯穿；

• 片尾：主金句 + 2~4 条原书金句归纳 + 数字指令式 CTA。

• 保存 02-script/script-v1.md 与 segments.json（hsf 引擎的合成输入），报告传播角度和预计时长。

• 若 require_script_approval 为真，在这里停止并等待确认。

3. 分镜与图片

• 按口播含义拆 8 镜（黄金 8 镜），切换点放在断句边界，保存 03-storyboard/storyboard-v1.yaml。

3a. 视觉风格预览（P1-1，图生成前必做）

若账号 images.style_preview 为真（默认），生成正式图之前先走风格矩阵：

• 从 01-research / 书名判断书类，按 [视觉风格矩阵](references/visual-style-matrix.md)（JSON 在 assets/templates/visual-style-matrix.json）取 3 个候选 id。

• 挑一个承载全书核心隐喻的场景，用该场景文案生成 3 张预览（04-images/style-preview-{id}.png，提示词带 no text 约束），并排展示请用户挑 1 个。

• 把选定 id 写入账号 account.yaml 的 images.default_style（或本书 book.yaml.overrides.images.default_style），全片统一冻结该风格，不再逐镜重选。图已生成后想换风格，按 P0-1 只改 render-manifest 重渲或重做图片阶段。

3b. 素材来源（P1-2）

按账号 source_strategy 决定来料：

• opening: real-video（默认）：开场优先用真实动态视频片段（用户素材 / 可商用库 / 视频生成），落到 shared/intro/ 并记 [来源账本](references/source-strategy.md)（模板 assets/templates/source-ledger.json）。无合适真视频时明确告知用户并降级为动态图形 / Ken Burns，不假装实拍。

• body: image-gen（默认）：正文背景默认文生图；用户指定某镜用真实片段或视频生成时，改动同样记入账本。

• 不得静默替换用户指定的来源；库素材必须登记 creator / license / attribution / sha256。

• 图片只做背景与情绪隐喻，不生成书名、作者、字幕、Logo、水印或平台 UI；提示词必须带「no text / 无文字」约束，避免 AI 在书页/图上生成乱字。

• 用同一视觉语言（即 3a 冻结的 default_style）生成图片，保存为 04-images/scene-01.* 等稳定文件名。

• 图片生成务必单张顺序调用（并行调用会丢 output_dir、同名互相覆盖），生成后校验张数再重命名。

• 若 require_image_approval 为真，展示图片并等待确认。

4. 配音、字幕与渲染（默认渲染器 = hsf 引擎）

• 开场若按 P1-2 选用真实动态视频，把它作为片头素材接入 compose_engine 的开场段，而非静态图 + Ken Burns；其余正文段用 3a 冻结风格生成的图。

• 配音用 scripts/gen_audio.py（edge-tts + boundary=WordBoundary 词级时间戳），产出 05-audio/*.mp3 + words.json。文案变了必须重新配音。

• 多音字读音修正：edge-tts 会误读多音字（如「了凡」读 le、「行善」读 háng），且不支持任何读音标签（<phoneme>/<sub> 全被拒）。解法：在 segments.json 的 segment 里加 "say" 字段——caption 是字幕原字，say 是配音文本（多音字 1:1 替换成同音字：了→瞭、行→形），gen_audio.py 配音用 say、再把词级时间戳里的同音字映射回原字，字幕仍显原字。

• 合成用 scripts/build_compose.py（读 segments.json → 调 compose_engine.py 合成主体，字幕=旁白 caption、与配音词级时间戳精确对齐）。

• 片尾金句卡用 scripts/gen_ending_card.py（主金句 + 补充金句 + CTA，CTA 超宽自动换行）+ scripts/concat_ending.py 拼接。

• 运行上述脚本前必须 cd 到工作目录（segments.json 里相对 image 路径相对 HSF_WORKDIR 解析），或用绝对路径。

• BGM 从账号配置指定时间进入，不足时按配置循环，ducking 压低，最终混音可叠加在成片之上（hsf 引擎不内置 BGM，混音走 factory 的 audio_mix 契约）。

• 发布级音效必须做轻量设计：不要让 60s+ 视频只有干 TTS。至少检查 4 类点位：开篇 0-5s（翻书/环境底声/远钟，建立书卷气）；关键转折前后（短静音或低频停顿，制造顿悟）；章节转场（罗盘/书页/木鱼/钟磬等轻提示，音量低于口播）；结尾金句（轻钟磬定住）。没有授权音效素材时，可用 FFmpeg/Python 生成极轻合成音效层，但不得压过人声。

• 静态画面必须有呼吸感：主体分镜默认保留 _kenburns_vf() 1.0→1.06 缓推/拉；片尾金句卡也必须做慢推/拉，不得直接静止 8-10s。若用户指出某镜“按住观众”，优先加镜头运动、换图或拆分镜头；手部/笔尖/灯光变化这类动作，只有在有分层素材、视频生成工具或额外动效资产时才做，不要在单张 PNG 上粗糙伪造。

• 正式版一律零平台/AI/WorkBuddy 水印：图片提示词必须要求 no text / no letters / no watermark；片尾卡不得使用可能带 AI 生成字样、水印、Logo 的底图。若底图右下角疑似有水印，改用干净封面/其他无字背景重渲染，或裁切/遮盖后再导出正式版。

• 渲染工程存 07-render/compose_engine/，预览 08-preview/preview-vN.mp4，成片 09-output/final-vN.mp4。

5. 预览、导出与状态

• 若 require_preview_approval_before_render 为真，等待确认后才正式渲染。

• 正式成片复制到账号 exports/ready/。更新 book.yaml 和 production.csv。Skill 不负责上传或发布。

质量基线（已固化，默认生效，勿当变量手调）

以下参数已写死进 scripts/compose_engine.py / build_compose.py / gen_ending_card.py，矩阵里每条视频自动带上，无需每次重调：

• 码率：-crf 18 -b:v 4000k -maxrate 4500k -bufsize 9000k -preset slow。⚠️ x264 中 crf 优先、b:v 被忽略，实际走 CRF 18 恒定质量（静止插画约 2.3~2.6 Mbps，已视觉无损）。

• Ken Burns 平滑镜头：_kenburns_vf() 已内置 —— fps 归一 + 4x 超采样（scale 到 7680×4320 再 crop）+ zoompan 1.0→1.06 缓慢推/拉（奇偶镜交替方向）+ 入出场淡入淡出。4x 超采样必须保留，否则 zoompan 亚像素取整会产生周期性抖动。

• 字幕：字幕文本 = caption（旁白原句，与配音词级时间戳对齐）；每行 ≤ 12 字；关键词高亮；淡入 400ms / 淡出 350ms；单句最短停留 1.2s 且持续到下一句开始。标点以 caption 为唯一真源，尤其中文分号/冒号/顿号要逐字保留；用户指出字幕错字时，不能只改 segments.json，必须重新跑 build_compose.py 重烧主体字幕。

• 片尾金句卡：主金句(66pt) + 补充金句 + 数字指令式 CTA；CTA 超宽自动换行兜底。片尾卡必须无水印、无署名、无 AI 生成标识，并做轻微慢推动态，不得静止卡住。

• 声音体验：默认 TTS 可以用，但发布前必须评估“干 TTS 感”。文化/历史/传记类视频至少加入低存在感书卷/钟磬/转场音效；若用户要求情绪更强，再考虑真人录音或更高级 AI 配音，而不是通过加快语速解决体验问题。

已知坑

• 必须传 video_width/video_height —— 否则竖屏被压横屏+黑边。

• 音频驱动时长 —— 视频段由音频决定（-shortest），别写虚高 duration。

• 字幕文本必须 = caption（旁白原句） —— 用 sub 做字幕会导致词级时间戳错位（只显半句/看起来没字幕）。

• 运行脚本必须 cd 到工作目录 —— 否则相对 image 路径找不到、clip 列表为空、concat 报错。

• ImageGen 多图并行会丢 output_dir —— 必须单张顺序生成，每张独立目录，生成后校验张数。

• OCR 喂料在 Python 3.13 坏 —— rapidocr-onnxruntime 报 DLL load failed，仅影响可选 ocr_points.py。

• Windows 无 /tmp —— 落盘用绝对路径。

• edge-tts 多音字误读 —— 「了凡」读 le、「行善」读 háng 等，且不支持任何读音标签（<phoneme>/<sub> 被拒）。用 segment 的 say 字段（同音字替换配音 + 词级时间戳映射回原字）解决，见「单书生产 · 4」。

• 顶部进度条/目录条 —— build_compose.py 默认 chapter_titles=["拆书"]，会在视频顶部渲染一条"板块标题 + 当前高亮 + 进度线"的导航条（视觉上像目录）。如正式发布不要任何章节/目录导航，在 segments.json 设 "chapter_titles": [] 即可关闭（compose_engine 中 use_progress_bar=False，所有 overlay 走 else 分支，不崩溃）。注意：sub 观点钉只作写稿辅助，不渲染上屏，无需处理。

• 只改 JSON 不等于改成片字幕 —— movie_body.mp4 已经烧录字幕，用户指出标点/错字后，必须重新跑 gen_audio.py（若 caption/say 改动影响配音）和 build_compose.py，再重新拼接片尾；只做后处理拼接会保留旧字幕。

• 片尾卡容易把底图水印带回来 —— 主体图可能已去水印，但 gen_ending_card.py 若拿 scene_008.png 等生成图当底，会把右下角 AI/WORKBUDDY/乱字带回正式版。发布版片尾优先使用干净封面、纯背景或人工遮盖后的底图，并抽右下角 crop 复查。

• 长静态镜头是体验短板 —— 6-10s 同一画面即使有口播也会拖。默认 Ken Burns 不够时，优先拆镜、换图、加更明显慢推/拉；复杂动作（手放下、笔尖移动、灯光渐暗）需要分层/视频化素材，否则不要硬做廉价动效。

• 音频不能只有人声 —— 90s 左右视频若无环境/BGM/转折音效，会显得“6分 TTS”。至少加轻量音效标记开篇、转折、顿悟和结尾；音量以不抢人声为原则。

常见问题