HyperFrames Share-Sheet Carousel 模板编辑契约：给 Agent 的安全改稿边界与变量机制解析-开发者社区

HyperFrames Share-Sheet Carousel 模板编辑契约：给 Agent 的安全改稿边界与变量机制解析

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

本篇技术指南围绕 HyperFrames 开源仓库中registry/blocks/share-sheet-carousel这一广告模板的编辑契约（Editing Contract）展开。该模板用 HTML 复刻了一个操作系统分享面板（share sheet）的 1080×1920 竖版动效：面板从底部弹簧式升起、卡片内四张幻灯片快速轮切、背景同步切换模糊地面，最后以一次"Accept"点按收尾。读完本文，你将掌握：该模板"哪些内容可改、哪些内容受保护"的边界划分、通过set_template_variable_defaults安全替换变量的标准操作流程，以及这些约束在仓库源码与测试中的落地方式。

一、编辑契约是什么：模板的"表面所有权"划分

该模板的契约文档 TEMPLATE.md 开篇就明确了表面所有权（Surface ownership）：模板描绘的是一个操作系统分享面板，被嵌入的网站/品牌是面板中显示的"分享项或发送方"（item or sender），它不拥有周围系统 UI 的所有权。最终成片是这个品牌的一支广告：发送方名称（sender name）、品牌条（brand strip）与文字商标（wordmark）承载其真实身份。

这一划分决定了改稿的底层立场：

系统 UI（面板结构、圆角卡片、分割线、按钮几何）属于"操作系统"，不可改动；
品牌内容（发送方、标语、logo、轮播图）属于"广告主"，是唯一可以替换的部分；
改稿是"把品牌放进去"，而不是"把系统 UI 改造成品牌风格"。

同样的契约模式还存在于 chatgpt-exchange/TEMPLATE.md、ai-chat-reveal/TEMPLATE.md、slack-notification-ad/TEMPLATE.md 等一批被标记为ad-template的推广模板中，它们共同构成仓库中"模拟真实系统 UI 做品牌广告"的模板家族。

二、可编辑槽位：变量声明即编辑边界

契约规定：只有data-composition-variables中声明的默认值才是可编辑的。这份声明位于 share-sheet-carousel.html 的<html>根元素上，同时在 registry-item.json 中以结构化形式重复登记。完整槽位如下：

变量 id	类型	角色	默认值	含义
`shareTitle`	string	content	`Share`	分享面板顶部的标题
`senderName`	string	content	`HyperFrames`	发送方名称，即广告主品牌真名，`portrays: ["subject_name"]`
`itemLabel`	string	content	`a video`	分享项，补全句子"… would like to share …"
`stripText`	string	content	`OPEN-SOURCE VIDEO ENGINE · SHIP FROM HTML`	品牌条定位语（小号大写，位于 logo 旁），`portrays: ["subject_tagline"]`
`acceptLabel`	string	content	`Accept`	右侧操作按钮文案
`declineLabel`	string	content	`Decline`	左侧操作按钮文案
`slideImage1`	image	content	`assets/slide-01.jpg`	第 1 张轮播图，同时驱动其模糊背景
`slideImage2`	image	content	`assets/slide-02.jpg`	第 2 张轮播图，同时驱动其模糊背景
`slideImage3`	image	content	`assets/slide-03.jpg`	第 3 张轮播图，同时驱动其模糊背景
`slideImage4`	image	content	`assets/slide-04.jpg`	第 4 张轮播图，同时驱动其模糊背景
`brandLogo`	image	content	`assets/hyperframes-logo-black.svg`	品牌横向透明文字商标，显示在预览底部的品牌条中，`portrays: ["subject_logo"]`

其中三条约束值得单独强调：

文字替换长度锁定：替换文案长度须保持在原文的 20% 以内（"Keep replacement copy within 20% of the original length"），防止文案撑破面板几何。
图片的双重驱动：每张幻灯片图既显示在卡片轮播区（582×476px），又作为其模糊背景（.ssc-bg放大到 1240×2080px 并施加blur(46px) saturate(1.1) brightness(0.88)滤镜）——替换一张图会同时影响前景与背景，share-sheet-carousel.html 的 CSS 注释明确写着"the ground behind the sheet is the current slide blown up and blurred"。
品牌身份槽位的portrays元数据：senderName、stripText、brandLogo分别携带subject_name、subject_tagline、subject_logo。按 docs/concepts/variables.mdx 的说明，portrays告诉编辑 Agent 哪些槽位承载品牌身份、绝不能用凭空捏造的文案填充——这正是本模板要求senderName填品牌真名的原因。

关于声明格式，注意区分两种 JSON 形态（variables-and-media.md 中专门提醒过）：data-composition-variables是声明数组（定义 schema：id/type/label/default），而渲染时的--variables与挂载时的data-variable-values是以 id 为键的值对象。

三、安全编辑机制：只用`set_template_variable_defaults`改默认值

契约对改稿方式给出明确的操作纪律：

使用已有的变量 id 及其新默认值，只调用一次set_template_variable_defaults。不要直接编辑或重写index.html或其data-composition-variables属性——该导入声明是 HTML 实体编码的 JSON，setter 会保留这种编码。永远不要编辑__template_baseline__.html或重复的组合文件。对于图片槽位，只传入图片工具返回的 token。setter 成功后再做校验。

逐条拆解其背后的原因：

data-composition-variables是 HTML-entity-encoded JSON：属性值中的引号等字符以实体形式存在（例如"），直接重写极易破坏转义结构。契约、以及测试 registryBlocks.test.ts 都要求每个被推广模板的TEMPLATE.md必须包含HTML-entity-encoded JSON字样，说明这是仓库对模板作者与改稿 Agent 的硬性约定。
图片槽位传 token 而非路径：图片变量在 Studio/Agent 工作流中由图片工具先产出 token，setter 只接收 token，避免绕过校验直接塞路径。
__template_baseline__.html是基线副本：它保存模板的原始状态，用于 diff 与回归，改稿时不能碰。
改后必校验：setter 成功后需要验证变量是否按预期生效，这与渲染时--strict-variables把未声明键/类型错误升级为错误的校验哲学一致。

四、受保护区域：哪些东西绝对不能动

契约的 Protected 清单要求保留：

分享面板的配色、字体、按钮、几何结构（668×974 卡片位于 (206,473)、34px 圆角、333px 分割按钮等，均来自源码中标注为spec provenance: measured的实测值）；
轮播布局、场景结构、时长（7.2333s）、时序、缓动与点按动画；
不得替换声明槽位之外的任何图片；
不得重新着色操作系统界面（面板属于"系统"，不是品牌资产）。

从源码 share-sheet-carousel.html 可以看到这些"受保护"的动效细节：SPRING数组是逐帧采样自参考视频的弹簧入场关键帧（从y:1450弹跳到y:0，伴随autoAlpha淡入）；CUTS数组定义了 13 个切点（0.99s 至 5.156667s），配合(i + 1) % 4的取模逻辑实现 14 次前景/背景同步互换、循环四张图；末尾 6.323333s–6.656667s 是 Accept 点按（卡片下压 3px、按压单元格高亮再释放）。这些都属于"受保护"的既有设计，改稿时只换内容、不动动效。

五、源码级原理：变量如何在运行时落到画面上

模板同时使用了声明式绑定与运行时读取两种变量消费方式（机制详见 variables-and-media.md）：

声明式绑定：四个背景<img>与四个幻灯片<img>均带data-var-src="slideImageN"，品牌条内 logo 带data-var-src="brandLogo"。data-var-src会在预览与渲染中一致地替换元素src，作者的src属性充当 fallback。
脚本读取：文本槽位（shareTitle、senderName、itemLabel、stripText、acceptLabel、declineLabel）通过window.__hyperframes.getVariables()一次性读取，再写入对应 DOM。源码中的text()工具函数还隐含一个 60 字符截断规则——超过 60 字符的替换文案会被截断，这与契约"长度控制在 20% 以内"互为双保险。

值得注意，该模板没有直接使用data-var-text（因为副标题需要把加粗的senderName与普通文本拼接），而是走getVariables()+textContent的路径——这正是 docs/concepts/variables.mdx 中"仅当需要条件、循环或派生值时使用getVariables()"的典型实例。

六、契约的仓库级保障：测试如何强制每个推广模板合规

编辑契约不是口头约定，而是被测试强制执行的。在 registryBlocks.test.ts 中，针对所有带ad-template标签的推广块（promoted templates），测试断言：

每个推广模板必须恰好携带一个TEMPLATE.md（hyperframes:asset类型）与一个组合文件；
TEMPLATE.md必须包含## Safe editing mechanics、set_template_variable_defaults、HTML-entity-encoded JSON三个关键契约要素；
组合 HTML 必须解析出非空的data-composition-variables声明；
每个image类型变量必须被绑定（存在对应的data-var-src元素）或在源码中出现多次（本模板的图片变量同时驱动前景与背景，正是"出现多次"的情形）；
推广模板禁止内嵌<video>固定媒体。

这意味着：只要你在该仓库中新增一个ad-template块，就必须同步提供这份编辑契约，否则 CI 测试直接失败——这也是"编辑契约"这一机制能被 Agent 可靠依赖的根本原因。

七、实战：安装、挂载与渲染变量覆盖

安装模板

在已有项目中执行（详见 docs/packages/cli.mdx 的add命令）：

npx hyperframes add share-sheet-carousel

该命令会把 share-sheet-carousel.html 写入compositions/share-sheet-carousel.html，并把 5 个资源文件（4 张轮播图 + 1 个 logo SVG）写入assets/目录，同时把粘贴片段复制到剪贴板。

挂载进主组合

模板时长 7.2333 秒、画幅 1080×1920。将其作为子组合挂载到index.html：

<div ><div >npx hyperframes render \ --variables '{"senderName":"YourBrand","stripText":"YOUR BRAND TAGLINE"}' \ --strict-variables \ --output share-sheet-ad.mp4

若要按数据行批量渲染，可改用--batch rows.json与--variables-file（见 docs/concepts/variables.mdx）。

改稿时的操作清单（对照契约）

确定要改的槽位：只允许契约列出的 11 个变量；
文字长度控制在新值在原值 ±20% 内，且不超过 60 字符（运行时截断线）；
图片只换slideImage1..4与brandLogo五个槽位，其余图片一律不动；
通过set_template_variable_defaults一次性提交新默认值，绝不直接改data-composition-variables、__template_baseline__.html或重复组合文件；
setter 成功后校验渲染结果，确认品牌身份槽位（senderName/stripText/brandLogo）是品牌真名真标。

总结

Share-Sheet Carousel 的编辑契约浓缩了 HyperFrames 模板体系的核心设计：用data-composition-variables声明编辑边界，用set_template_variable_defaults保证改稿不破坏编码结构，用 Protected 清单守住系统 UI 的真实性，用测试强制每个推广模板都交付契约。对于 Agent 驱动的广告改稿，这意味着：可安全替换的内容全部显式声明、不可触碰的部分全部显式禁止——照着这份契约执行，就能在不破坏模板动效与系统拟真度的前提下，把任意品牌放进这个分享面板。

HyperFrames Share-Sheet Carousel 模板编辑契约：给 Agent 的安全改稿边界与变量机制解析