brand-kit

用途

brand-kit 用于解决一个具体问题：让用户制作的视频在视觉上保持一致性。它的核心观点是，一种“外观”属于用户本人，而不是某一个项目，因此它会被用户未来制作的每一支视频复用。正因如此，这种外观应当保存在一个文件里，而不是写在某个生成脚本内部，也不应依赖对当前会话的记忆。

主要能力：外观预设

该方案目前提供的是“外观预设”（Look Presets），通过 video-studio styles 系列命令操作：

video-studio styles --list
video-studio styles --show tourism
video-studio styles --apply tourism --storyboard <project>/storyboard.json
video-studio styles --save theirs --from <project>/storyboard.json

一个预设就是一个 markdown 文件，包含三部分：frontmatter（name、description）、说明何时使用它的散文、以及一个围栏 JSON 代码块承载具体数值。JSON 只覆盖两类内容：

captions：colour、stroke、strokeWidth、fontSize、wordGap、wordsPerPage、uppercase、bottom、palette
cards：把 label、stat、title、cta 这类具名角色映射到 bg、fg、fontFamily、italic、weight、fontSize、tracking、align 以及一个 rect

未知的键会被报告出来，而不是被静默丢弃，因为一个拼错的键会渲染成空，看起来却像是一种样式选择。

使用方式

预设的解析顺序为，先匹配者胜出：

<project>/styles/
$VIDEO_STUDIO_STYLES
用户自己的 ~/.config/video-studio/styles/
工具链自带的预设

其中用户级目录是最关键的，因为保存在某次代码检出目录里的预设会随之消失。

卡片可以指定自己的字体。fontFamily 接受编辑器能加载的任何字族（所有 Google 字体加系统字体栈），旁边可配 italic 和 weight。bg: "transparent" 会让文字直接落在画面上、没有面板。建议写明真实的回退字体（例如 "Playfair Display, Didot, Georgia, serif"），并为不常见的展示字体明确指定 fontSize，因为自动尺寸是按 Inter 的宽度校准的。

应当按角色而非颜色来编写卡片。写 {"card": {"style": "label", "heading": "TOKYO"}}，让 --apply 去填充 bg、fg、tracking 和 rect。任何场景显式设置的项都会优先，因此一次性覆盖不会意味着放弃品牌。

当用户描述想要的外观时，应当保存它。--save 会从已完成的 storyboard 中提取外观，生成一个预设文件，默认放进用户自己的配置目录。只存在于本次对话中的外观，到明天就消失了——这正是该功能存在的意义。应当告诉用户它被保存到了哪里，以及下次该如何称呼它。

应用是一个展开步骤，而不是渲染时的查找：storyboard 最终会持有真实数值，因此它仍然是一份可读的文档，而且之后编辑预设也不会悄悄改变一支已经确认过的视频的样式。

标题一致性

在排版之前，应当对每一个文本元素进行分类，不要把屏幕上所有文字都当作“标题”。

字幕（Subtitles）是旁白的辅助。它们来自语音时序文件，通过 captionStyle 渲染——预设的 captions 块正是让它们在各视频间保持一致的部分。将其保持在下方安全区附近；只有当画面元素占据该区域时才按场景覆盖。
标签（Labels）是编辑性覆盖层：名称、排名、日期、统计数据、分类标签、下三分之一字幕、CTA。应当把它们构建为卡片角色，让品牌来掌控它们。标签承载个性——它们可以滑动、弹出、做成徽章或加边框。
标牌（Signs）是画面内的文字对象：海报、标牌、记分牌、手机通知。应当把它们作为卡片合成。永远不要向生成器索要可读文字，它会自行发明字形。

保持对比度决策系统化——先做品牌级颜色、描边、阴影和面板，再做逐场景例外。标签动效默认使用滑动/飞入加缩放/弹出，一个品牌只用一套入场语汇，仅按场景能量改变方向、延迟和强度。不要在同一个视频里混用互不相关的标签样式；如果某种处理发生变化，应让这一变化有叙事动机，并从该点起复用新处理。

品牌捆绑包（提案，尚未构建）

预设覆盖颜色、字幕和卡片几何，但不覆盖一个身份的其余部分。提案中的捆绑包目录位于 ~/.config/video-studio/brands/<name>/，由同一条链解析（<project>/brands/ → $VIDEO_STUDIO_BRANDS → 用户 → 自带），并采用相同的 frontmatter 加 JSON 格式：

brand.md —— 与今天完全一样的外观 JSON，外加一个捆绑包名称，让用户可以说“使用 Northwind”而不是说出某种颜色。
logo/ —— wordmark 与标志，提供 SVG 和透明 PNG，旁边写有安全区与最小尺寸规则。
fonts/ —— 实际的字体文件。今天的 fontFamily 只是命名一个渲染主机可能并未安装的字体。
voice.md —— 旁白身份：用哪个声音、语速，以及这个品牌不说的词。
cta.md —— 结尾台词，提供不同格式所需的两到三种长度。

这些目前都无法解析。styles 只读取 captions 和 cards，并把其他所有键标记为未知，因此品牌捆绑包需要新代码才能兑现承诺。在它存在之前：应当与用户就这些额外部分达成一致，把它们写进项目里，并明确说明只有字幕、卡片颜色和卡片几何会自动保留到下一支视频。

限制与反模式

不要逐视频重新决定调色板。同一个会话里手工构建的三个位置，会漂移成同一种标签却有三个不同的标签高度。预设文件正是用来防止这种漂移的。
不要描述品牌捆绑包好像已经能用。logo、字体、语音和 CTA 文案都只是提案。当只有外观被持久化时，说“已保存到你的品牌”是一个下一次会话就会打破的承诺。
不要只把品牌留在聊天里。如果你没有把它写入文件并明确说出路径，它就没有被保存。
不要只命名字体而不提供字体文件。渲染主机缺少的 fontFamily 会静默回退，而最终交付的就是那个回退结果。

依赖说明

预设机制依赖 styles，需要先安装：

pip install 'video-studio-engine @ https://github.com/scrollmark/social-skills/archive/refs/heads/master.tar.gz'

（基础安装，不含额外组件），然后以 video-studio styles … 运行。它未被打包在此处，因为它需要读写 styles 树和 storyboard 文档，不是可以放在技能文件夹里的单个文件。没有该安装，就没有 --list、--show、--apply 或 --save，也没有任何东西会把预设展开进 storyboard——你仍然可以与用户商定品牌并手写文件，但应用它就变成手工编辑。--apply 和 --save 还假定 storyboard JSON 符合引擎的形状。