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类型角色默认值含义shareTitlestringcontentShare分享面板顶部的标题senderNamestringcontentHyperFrames发送方名称即广告主品牌真名portrays: [subject_name]itemLabelstringcontenta video分享项补全句子… would like to share …stripTextstringcontentOPEN-SOURCE VIDEO ENGINE · SHIP FROM HTML品牌条定位语小号大写位于 logo 旁portrays: [subject_tagline]acceptLabelstringcontentAccept右侧操作按钮文案declineLabelstringcontentDecline左侧操作按钮文案slideImage1imagecontentassets/slide-01.jpg第 1 张轮播图同时驱动其模糊背景slideImage2imagecontentassets/slide-02.jpg第 2 张轮播图同时驱动其模糊背景slideImage3imagecontentassets/slide-03.jpg第 3 张轮播图同时驱动其模糊背景slideImage4imagecontentassets/slide-04.jpg第 4 张轮播图同时驱动其模糊背景brandLogoimagecontentassets/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是声明数组定义 schemaid/type/label/default而渲染时的--variables与挂载时的data-variable-values是以 id 为键的值对象。三、安全编辑机制只用set_template_variable_defaults改默认值契约对改稿方式给出明确的操作纪律使用已有的变量 id 及其新默认值只调用一次set_template_variable_defaults。不要直接编辑或重写index.html或其data-composition-variables属性——该导入声明是 HTML 实体编码的 JSONsetter 会保留这种编码。永远不要编辑__template_baseline__.html或重复的组合文件。对于图片槽位只传入图片工具返回的 token。setter 成功后再做校验。逐条拆解其背后的原因data-composition-variables是 HTML-entity-encoded JSON属性值中的引号等字符以实体形式存在例如quot;直接重写极易破坏转义结构。契约、以及测试 registryBlocks.test.ts 都要求每个被推广模板的TEMPLATE.md必须包含HTML-entity-encoded JSON字样说明这是仓库对模板作者与改稿 Agent 的硬性约定。图片槽位传 token 而非路径图片变量在 Studio/Agent 工作流中由图片工具先产出 tokensetter 只接收 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-srcslideImageN品牌条内 logo 带data-var-srcbrandLogo。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.mdhyperframes: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.htmldiv >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 驱动的广告改稿这意味着可安全替换的内容全部显式声明、不可触碰的部分全部显式禁止——照着这份契约执行就能在不破坏模板动效与系统拟真度的前提下把任意品牌放进这个分享面板。相关资源编辑契约原文registry/blocks/share-sheet-carousel/TEMPLATE.md模板源码registry/blocks/share-sheet-carousel/share-sheet-carousel.html注册清单含变量 schemaregistry/blocks/share-sheet-carousel/registry-item.json目录页含交互式变量预览与完整源码docs/catalog/blocks/share-sheet-carousel.mdx契约强制测试packages/cli/src/registry/registryBlocks.test.ts变量机制总述docs/concepts/variables.mdx、skills/hyperframes-core/references/variables-and-media.mdCLIadd/render用法docs/packages/cli.mdx【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考