模板本地固定资源和预览回退约定¶
意图¶
人们应该能够使用真实的媒体资源预览 Astryx 模板,将其复制到自己的项目中,然后替换演示内容,而不会继承 Astryx 的预览基础设施,也不会将示例媒体误认为产品资产。
模板是起点。它们旨在被使用者复制和修改。模板附带的图片和视频用于演示模板所设计的构图、裁剪、密度和状态;它们不是生产内容,也不是受支持的使用者资产库。
范围¶
本约定管理模板使用的静态演示资产,包括图片、海报和视频。它涵盖这些资产的编写引用、维护者预览、复制输出和回退。它还管理演示内容元素:仅存在于仓库中的元素,用于代替仅存在于文档中的演示内容,例如一张扑克牌牌面,真实 Astryx 组件在动效或手势示例中会将其包裹。
它不管理图标。图标可能是组件属性、注册表值、导入的模块、内联符号或产品资产,其转换和可移植性问题需要单独的约定。
非目标¶
- 将 Astryx 的模板媒体作为使用者资产包发布。
- 将每个演示图片或视频复制到使用者的项目中。
- 定义图标解析、图标导入、SVG 组件转换、favicon 或应用图标。
- 保证演示内容适合使用者的品牌、产品、地区或生产许可需求。
- 定义产品数据加载器或更广泛的模板数据边界。
- 使模板在复制后不可变。
要求¶
模板和资产所有权¶
- FR1 — 模板是可编辑的源代码。 复制后的页面或区块模板必须是普通的使用者自有源代码,可以被更改、拆分、连接到产品数据或删除,而不会保留对 Astryx 预览宿主的运行时依赖。
- FR2 — 静态模板媒体是演示内容。 为模板提供的图片、海报和视频必须被视为演示预期构图和状态的固定资源。它们在模板中的存在不得暗示使用者应在产品中交付这些文件、URL、主题、文案或品牌。
- FR3 — 固定资源的所有权是明确且本地的。 Astryx 拥有的静态模板固定资源必须使用仓库指定的模板固定资源命名空间,并且必须在没有私有网络访问权限的情况下对维护者可用。产品拥有的路径和明确的第三方 URL 不是 Astryx 固定资源引用,不得仅仅因为它们出现在模板源代码中就被重写。
预览行为¶
- FR4 — 维护者预览显示真实的固定资源。 本地开发、文档站点、沙箱和拉取请求预览必须将每个 Astryx 拥有的静态固定资源解析为具有代表性的图片或视频。预览可以重写部署基础路径,但该重写必须保持可移植的模板源代码不变。
- FR5 — 一个规范的固定资源可以服务于多个预览。 预览部署可以共享一套已发布的固定资源,而不是将媒体复制到每个预览中。拥有部署必须保持引用确定性,并防止预览静默解析到不相关的文件。
- FR6 — 预览失败是可见且有界的。 缺失或不支持的固定资源必须产生可操作的作品编写或预览失败,并指明该引用。它不得静默渲染错误媒体类型的回退,并声称模板预览具有代表性。
复制行为¶
- FR7 — 复制的源代码移除预览依赖。 复制或搭建模板必须从生成的源代码中移除每个 Astryx 拥有的静态固定资源引用。输出不得在运行时从 Astryx 文档站点、沙箱、GitHub Pages 预览、私有 CDN 或仅限仓库的
/template-assets/命名空间获取内容。 - FR8 — 回退保留源代码可用性,而非演示内容。 复制路径必须生成无需设置即可解析和渲染的源代码。图片和海报引用可以变为中性的自包含视觉占位符。当不存在经过验证的可移植视频占位符时,视频引用可以变为明确的空或不播放的替换点。无论哪种情况,输出都不得声称原始演示内容已被复制。
- FR9 — 回退具有媒体类型安全性。 图片回退不得作为视频源提供,视频字节不得作为图片回退提供。分类必须使用完整的最终文件名字尾,并且不区分大小写。如果复制路径无法安全地分类 Astryx 拥有的固定资源,它必须带着固定资源路径和不支持的格式失败,而不是猜测或留下仅限预览的引用。
- FR10 — 混合静态媒体独立转换。 包含图片海报和视频源的模板必须根据每种媒体类型独立转换每个引用。一个不支持的引用不得导致另一个引用收到错误的回退。
- FR11 — 复制收据披露替换。 成功的复制操作必须在 Astryx 演示媒体被替换时告知使用者,并指明需要他们自定义的生成文件或替换点。收据不得暗示已安装生产就绪的媒体。
- FR13 — 演示内容元素在复制期间被替换。 在动效或手势示例中,真实 Astryx 组件可以包裹仅存在于文档中的演示内容,例如
<Card><PlayingCardContents /></Card>。演示内容元素是仅存在于仓库中的元素,用于代替这些内容。每次复制都必须用通用占位符替换仓库专用的演示资产(FR7–FR10)和每个演示内容元素,保留外层组件及其属性,并且复制的源代码不得引用定义演示内容元素的仓库专用代码。仅围绕真实组件添加文档专用呈现的演示内容包装器(例如用法提示)应被移除而非替换:复制保留被包装的组件及其属性,如同包装器不存在一样,demoContentReplaced只统计占位符,因为只有它们需要使用者自己的内容。 这些复制操作是template copy和文档站点的 shadcn Install 项,后者将示例写入使用者的项目。复制收据(FR11)必须将替换的元素计为demoContentReplaced。 在下一个次要版本之前,持久化的.astryx/<item>.json收据保持其 v2 形状(已发布的读取器严格验证它),因此替换计数出现在template copy和template show报告的复制响应中。template show返回与复制写入相同的源代码,并且必须在其响应中报告demoContentReplaced,如同报告demoMediaReplaced一样。 对于 Astryx 不控制其输出的 shadcn Install 项,FR11 的披露由占位符本身承担(每个被替换的元素和媒体引用在其替换点处都是明显标记的占位符),并由注册表项的描述承担。在 0.8.0(下一个次要版本)中,持久化的计数移至 v3 收据,并带有迁移说明(CLN-0027)。 除了这些复制操作和template show之外,其他将示例源代码分发出去但不将其写入项目的界面只替换演示内容元素并保留其固定资源媒体:astryx component <Name> --showcase,它打印组件的展示源代码,以及spec:AST-033FR23 的文档站点界面。实时预览渲染原始内容(FR4)。当复制、显示或分发出去的输出仍然引用演示内容元素或定义它的代码时,检查必须失败。 演示内容元素如何被标记和替换属于architecture:template-authoring。
图标边界¶
- FR12 — 图标按角色排除,而非按文件扩展名。 组件图标、registry 图标、导入的 SVG 图标组件以及应用图标 MUST NOT 仅因其源表示为图像格式,而被归类为本契约下的静态模板素材。任何针对图标的复制、导入重写、registry 转换或回退行为,都需要其自身已获接受的契约。
当前状态影响¶
Astryx 模板目前使用仓库本地的 /template-assets/* 引用来表示代表性图片和视频。docsite 和 sandbox 拥有这些文件用于预览,已部署的预览只能将可执行 bundle 重写为共享的已发布位置。可移植源码保留根相对路径的素材路径。
CLI 复制路径目前会识别 Astryx 的素材命名空间,并将图片替换为自包含的 SVG 占位符。它会将识别出的视频源剥离为空字符串,而不是将图片数据放入 video 元素。
template copy 和 template show 会将每个 demo-content 元素(FR13)替换为 <Text>Card content</Text> 占位符;当源尚未导入 Astryx 的 Text 时,会为其导入 Text,并移除 demo-content 导入。它们会移除仅用于文档的展示包装器(例如使用提示),并保留其包裹的组件。两个响应都将占位符数量报告为 demoContentReplaced。
astryx template <name> --skeleton 会概要呈现替换后的源,并列出其组件。astryx component <Name> --showcase 会打印 showcase 源码,其中每个 demo-content 元素均被替换,且其素材媒体保持不变。shadcn 的 Install 条目会安装 block 和 page 源码,其中 demo-content 元素和素材媒体均被替换,各自成为带有可见标记的占位符;其 registry 条目描述会说明被替换的数量。其 .astryx/<item>.json 收据在 CLN-0027 之前保持 v2 结构。
验证¶
| 契约 | 验证方式 | 代表性用例 | 失败预期 |
|---|---|---|---|
| FR1–FR3 | 模板源与复制边界测试 | 内置 page、block、integration 模板;Astryx 素材;消费方路径;第三方 URL | 复制后的源保留预览运行时依赖,或改写了消费方拥有的内容 |
| FR4–FR6 | 真实预览请求与渲染媒体检查 | local、docsite、main sandbox、PR preview;图片和视频;缺失素材 | 代表性媒体返回 404、解析到另一个文件,或静默使用了错误类型 |
| FR7–FR8 | 端到端 CLI 复制测试 | 仅图片模板、仅视频模板、无媒体模板 | 生成的源码保留 /template-assets/,或在未完成设置的情况下无法解析/渲染 |
| FR9–FR10 | 分类器与混合来源变更测试 | 大写/小写;多圆点文件名;图片海报加视频;未知后缀 | 最后一个后缀被误读、图片数据进入视频、或对不支持的类型进行猜测 |
| FR11 | 人工与结构化接收确认测试 | 无替换;一张图片;混合媒体 | 消费者未被告知必须替换哪些内容,或被错误告知资源已安装 |
| FR12 | 作用域守卫测试与审查 | 图标属性、注册表图标、导入的 SVG 组件、静态主视觉图像 | 图标行为被静默并入静态夹具转换器 |
| FR13 | 端到端 CLI copy、show 及 --showcase 测试、shadcn 安装测试,以及真实预览检查 |
一个 motion 或 gesture 示例,其 Card 包裹一个 demo-content 元素;一个包含两个此类元素的示例;一个 Card 位于仅文档提示包装器中的示例;一个不包含任何此类元素的示例;其 template show 响应;其 --showcase 输出;其安装到项目中的 shadcn 安装结果、其注册表项描述及其 .astryx/<item>.json 收据;其实时预览 |
复制、展示或安装后的输出仍引用 demo-content 元素,或保留仅文档包装器或其提示文本(带提示的示例仅复制 Card 及其占位符)、定义该元素的代码或 /template-assets/;--showcase 输出引用 demo-content 元素或更改其夹具媒体;外层组件或其 props 发生变化;复制收据或 template show 响应遗漏或错误计数 demoContentReplaced;shadcn 安装遗留了被替换的元素或媒体引用,且没有可见标记的占位符,或其注册表项描述未披露该替换;安装后的 .astryx/<item>.json 收据新增字段,或在 CLN-0027 之前无法通过已发布的严格 v2 读取器;或实时预览停止渲染原始内容 |
完成标准¶
本规范仅在以下条件全部满足时从 accepted 移至 shipped:
- 预览环境在无需私有网络访问或按预览复制要求的情况下渲染相同的规范静态夹具;
- 复制的模板不保留任何仅限 Astryx 预览的媒体引用;
- 图像、海报和视频回退是类型安全的,并已获得端到端覆盖;
- 不支持的静态夹具格式以可操作的引用方式失败;
- 复制收据标识被替换的演示媒体;
- 复制和安装的模板不保留 demo-content 元素或对定义该元素的代码的引用,且收据计数被替换的元素;以及
- 在引入任何图标转换之前,图标来源已在此转换之外得到验证,并链接到单独的契约。
决策日志¶
DEC-1 — 模板媒体演示一种组合;消费者自行替换¶
参考: spec:AST-028/DEC-1
决策者: cixzhang,2026-09-04
Astryx 模板中的图像和视频是用于展示预期组合的本地夹具。复制的模板是消费者拥有的可编辑源码,不是分发生产媒体或保留 Astryx 预览运行时依赖的渠道。
已拒绝:将已检入的演示文件视为受支持的消费者资产库,或默认将它们复制到每个项目中。
DEC-2 — 预览和复制承担不同的义务¶
参考: spec:AST-028/DEC-2
决策者: cixzhang, 2026-09-04
维护者预览展示真实的样例资源,以便模板可被评估。复制后的源码移除了对预览的依赖,并替换为媒体种类安全、可移植的替换点,供消费者自定义。
已拒绝:在每个维护者预览中显示占位符,并在生成的项目中保留仅存在于仓库的样例资源 URL。
DEC-3 — 图标需要单独的契约¶
参考: spec:AST-028/DEC-3
决策者: cixzhang, 2026-09-04
该契约涵盖静态图片和视频样例资源,以及 DEC-4 的演示内容元素;它不涵盖图标。图标在语义、导入、注册表和转换方面有各自独立的关注点;将它们与演示媒体归为一类,会在未明示的情况下决定另一个公共边界。
已拒绝:将所有 SVG 或类似图像的源文件归类为模板样例资源。
DEC-4 — 演示内容元素是复制操作会替换的样例资源¶
参考: spec:AST-028/DEC-4
决策者: cixzhang, 2026-11-01
动效和手势示例可以在真实 Astryx 组件中展示仅用于文档的演示内容(例如扑克牌牌面),而无需为每个示例维护第二份副本。这些内容在 DEC-1 的意义上属于样例资源:复制操作会用通用占位符替换每个演示内容元素,并保留外层组件;移除仅添加文档展示(例如使用提示)的包装器,并保留其包裹的内容;预览则渲染原始内容(DEC-2)。shadcn Install 项会将示例写入消费者的项目,因此它属于复制操作,并像 template copy 一样替换样例媒体和演示内容元素。template show 返回与复制操作写入的相同的源码;其他仅提供源码的渠道只会替换演示内容元素。没有演示内容元素的示例保留其源码,但其 shadcn install 会像任何复制操作一样替换样例媒体(FR7)。
已拒绝:为每个示例提供仅用于文档的重复版本,这会增加需要保持同步的文档。
弃用与清理记录¶
CLN-0027 — 安装收据统计复制操作所替换的内容¶
| 字段 | 值 |
|---|---|
| id | CLN-0027 |
| lifecycle | 无弃用:针对 FR13 的已暂定 [breaking] 变更(spec:AST-017 FR28) |
| delta | shadcn Install 项会写入一份 v3 .astryx/<item>.json 收据,其中新增了 demoMediaReplaced 和 demoContentReplaced。astryx upgrade 可读取 v1、v2 和 v3 收据;在 0.8.0 之前发布的 CLI 无法读取 v3 收据,因此迁移说明会告知消费者在升级从 0.8.0 起安装的项之前,先升级 CLI。 |
| rollback | 从最终补丁基线恢复 v2 收据写入器。 |
| state | pending — 随下一个次要版本 0.8.0 落地,并带有其 [breaking] Changeset。 |
开放问题¶
无。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx