跳转至

模板创作架构

目的

Astryx 模板是可复制的起点。页面模板为完整的内容表面搭建脚手架。块模板提供聚焦的模式和组件示例。本记录负责它们的源形态、目录身份、验证边界、消费者投影和复制语义。

本记录不复制贡献者说明或内部审计-发布工作流。公开的分级标准由随附的模板质量指南承载,公开的贡献者指南会链接到该来源。

系统模型

发布状态

Astryx 随附两种模板类型。展示示例(showcase)是块所承担的一种角色,而非第三种类型。

类型或角色 当前源形态 当前身份与用途
内置页面 pages/<slug>/page.tsx 加上 template.doc.mjs 目录 slug 即 CLI id。该页面是完整路由的起点。
内置块 blocks/ 下配对的 <Name>.tsx 和 <Name>.doc.mjs 文件主名(stem)即 CLI id。该块是一个聚焦示例或可复用模式。
外部块 通过 astryx.blocks 声明的包下同样配对的文件 包、类型和文件主名共同标识该条目。
集成模板 已配置的集成 templates 根目录下配对的 <id>.tsx 和 <id>.template.* 或旧版 <id>.doc.* 包、类型和相对于根目录的 id 标识该条目。支持嵌套 id。
主要展示示例 设置了 isShowcase: true 的块 为其 exampleFor 目标提供主打示例。
次要展示示例 在 alsoShowcaseFor 中点名目标的块 复用同一源,作为其他组件或 hook 页面的主打示例。
附加示例 在 alsoExampleFor 中点名目标的块 在附加的 Examples 部分复用同一源。

name 和 displayName 是面向人类的标签,而非目录身份。它们可以重复。可解析的身份是 (package, type, id);当 id 在多个包或类型中存在时,调用方会对其进行收窄。

当前随附的加载器尚未共用同一个验证边界:

  • 内置页面直接加载元数据,并对某些缺失值提供默认值。
  • 内置块和外部块要求存在配对的源文件,除此之外直接加载元数据,并对某些缺失值提供默认值。
  • 集成模板会经过 parseTemplate() 处理,并报告源缺失、加载或封装(envelope)错误。

当前随附的消费者也会收集不同的集合:

  • discoverAll() 为模板 API、搜索和布局提供数据。
  • Project.templates() 会独立重新收集集成模板,用于项目诊断和去重。
  • listTemplates() 返回所有内置页面目录而不读取元数据;程序化 init 在应用指定的起始页时会使用该列表。
  • 沙盒和文档站点会独立生成元数据/源注册表。
  • 文档站点概览读取生成的元数据,而实时页面预览则依赖 templateComponents.ts 中单独手工维护的懒加载映射。

复制会将源输出到采用方项目中。它不会与目录保持实时关系,后续的模板发布也不会改写已复制的项目。

规范化目录契约

在本记录变为 current 之前,每个源都必须规范化为一条目录条目,并通过同一个验证边界。该边界使用以下要求:

范围 必需 可选或条件性
每个条目 id、package、type、name、displayName、非空的 description、显式的 isReady,以及存在的源文件 keywords;源特定的溯源与诊断信息
页面 以上所有项;当符合概览条件时需有 category scaffold、isHiddenFromOverview;隐藏的特殊用途页面可省略 category
块 以上所有项,外加 exampleFor、正的 aspectRatio,以及完整的 componentsUsed scale、isShowcase、alsoExampleFor、alsoShowcaseFor
主要展示示例 块的全部要求,外加 isShowcase: true;每个 (package, target) 最多解析出一个主要展示示例 同一块可通过 alsoShowcaseFor 服务于其他目标
附加放置 一个有效的块,以及由 alsoExampleFor 或 alsoShowcaseFor 指名的有效目标 放置不会创建另一个模板身份

页面和块元数据可以使用更丰富的第一方类型,或使用较窄的集成封装(envelope)来编写。源适配器将这些特定于源的形态转换为公共条目。投影(projection) 是为某个消费者提供的目录过滤视图;它不会发现另一份成员列表。

已收敛的投影结果如下:

  • CLI 模板与搜索界面会选择所有符合条件的页面与块。
  • 布局仅选择块。
  • init 选择每个已命名的内置页面。
  • 文档站点概览选择未标记 scaffold 或 isHiddenFromOverview 的就绪页面。
  • 文档站点实时预览选择相同的合格页面条目,并导入其目录源。
  • 组件与 Hook 文档从块元数据中选择普通示例、主展示位和显式的次要放置位。
  • 项目诊断消费同一组目录错误,而不是重新收集集成成员关系。

无效的必需数据会产生诊断信息。它不会被隐式默认值修复,也不会被静默跳过。TypeScript 检查仍然是第一方编写过程中的额外检查;它不会取代运行时的目录验证。

边界与不变量

  • INV1 — 页面和块是仅有的模板种类。 展示位和附加示例放置是块的角色,而不是独立的源种类或身份。
  • INV2 — 身份与标签彼此分离。 (package, type, id) 解析出一个模板。name 和 displayName 可以更改或重复,而不会成为身份。
  • INV3 — 角色要求是显式的。 每个被接受的条目都满足上述规范化字段矩阵。在消费者接收条目之前,会先验证源配对与投影元数据。
  • INV4 — 特定于源的编写工作在一个边界收敛。 内置、外部与集成源可以有不同适配器,但没有任何一个能绕过规范化验证。
  • INV5 — 成员关系由单一目录拥有。 CLI、搜索、布局、项目、init、沙盒与文档站点之间的差异来自声明的投影,而不是独立的文件系统扫描或手工维护的成员列表。
  • INV6 — 预览源即实际交付的源。 页面预览导入与目录所提供的同一个 page.tsx。生成的懒加载映射可以实现该投影,但不能决定成员关系。
  • INV7 — 页面仍保持宿主可组合性。 普通页面拥有页面内容,而非宿主应用的全局外壳。处于显式 Shell - 类别中的页面可以拥有 AppShell 和全局导航,因为演示该外壳正是其目的。精确的根组件配方由贡献者指南负责。
  • INV8 — 复制是自包含的快照。 生成的源属于采用该模板的项目。在复制过程中,仅存在于仓库中的演示资源和演示内容元素会被替换为通用占位符,仅用于文档的展示包装会被移除;template copy 与文档站点的 shadcn Install 项均为复制操作。template show 返回与复制所写入相同的源。没有随复制分发的其他示例源只替换演示内容元素并移除仅用于文档的展示包装。实时预览渲染原始内容。后续的目录更新不会修改已复制的项目。
  • INV9 — 目录值可以演进。 模板 id、标签、元数据、类别、示例数据和初始源码是 spec:AST-017/DEC-2 下可变的目录数据。
  • INV10 — 围绕目录的操作仍受契约约束。 template 命令、受支持的选项、退出行为以及机器可读的响应模式仍由 CLI 契约管辖。
  • INV11 — 共享行为需要共享契约。 相似模板不会隐式构成一个家族。共享的状态、交互、响应式行为与约束,需要经批准的家族、设计或系统记录。
  • INV12 — 证据与具体修订绑定。 一个评分得分标识其测得的确切模板提交与评分规则版本。它可以支持审查,但不能授予设计批准、实现批准或当前记录权威。

委托授权

本记录不吸纳相邻事实:

  • 随附的 authoring/building-blocks/templates/write-good-templates 指南拥有公开的评分规则、评分规则版本、等级段、类别、权重与代理工作流。公开的 Contributing Templates 指南拥有贡献者工作流与评分账本发布流程,并链接到随附的评分规则而不是复制它。其中关于“重命名即破坏性变更”的现行声明已被 spec:AST-017/DEC-2 取代。
  • design:template-composition 拥有共享的人类视觉、层级、响应式与交互意图。在其权威状态为 draft 期间,它仍是候选记录。
  • 组件、模块与家族记录拥有由模板组合出的组件的行为。一个良好的评分得分不会覆盖这些契约。
  • spec:AST-017/DEC-2 拥有可变目录值与稳定 CLI 周边操作之间的兼容性切分。
  • TemplateDoc 类型与 parseTemplate() 实现编写包络。它们必须在本记录的字段要求上收敛;当二者不一致时,任何一方都不能悄然成为策略。

变更耦合

  • 模板源或元数据的变更会重新运行其源适配器、规范化验证及所有受影响的投影检查。
  • 对必需元数据或模板角色的变更会同时更新 TypeScript 类型、运行时解析器、贡献者字段表、生成器、API 响应和有效记录。实质性形态变更遵循仓库的模式版本与迁移规则。
  • 页面的新增、移除或投影标志变更会更新生成的沙盒与文档站点数据,并验证每个被接纳的页面均有实时预览覆盖。
  • 展示位或示例放置的变更会为每个目标验证一个已解析的主展示位,并重新生成展示位/示例注册表。
  • 视觉或交互变更遵循适用的现行设计、家族与组件记录。一次审查不能替代另一次审查。
  • 评分规则变更会同时更新随附模板质量指南的版本与评分账本契约。仅当它移动系统边界时,才会改变此架构。
  • 跨多个模板共享行为的提案应更新相关家族、设计或系统记录,而不是从相似性推断契约。

拥有代码

  • packages/cli/assets/docs/tree/template-quality.doc.mjs 及其子指南 —— 规范的公开评分标准和代理评分工作流。
  • scripts/template-score-ledger.mjs —— 评分分数持久化;从指南导入 规范版本、等级区间、类别和权重。
  • packages/cli/assets/templates/ —— 内置页面和块源代码及元数据。
  • packages/cli/authoring/doctypes/template/ —— 第一方创作类型和 运行时模板封装。
  • packages/cli/foundation/discovery/template-adapter.mjs —— 当前的源加载器、 规范化、投影和共享模板 IO。
  • template-adapter.mjs 中的 replaceDemoMedia —— INV8 替换步骤, 复制和显示代码共用的步骤。它替换 /template-assets/ 媒体 URL。在 动效和手势示例中,真实 Astryx 组件包裹仅文档内容时, 例如 <Card><PlayingCardContents /></Card>,它还会将每个 demo-content 元素替换为通用占位符,并保留外层 组件。demo-content 元素是从唯一的、仅限仓库的 demo-content 模块导入的元素;该步骤会移除该导入。该模块 和导入规则是内部机制,而非公共契约 (architecture:knowledge-contracts/INV18);spec:AST-028 FR13 规定了 结果。template copy、template show 以及 docsite 的 shadcn Install 项会运行两遍;复制回执和 template show 响应 会将元素数量报告为 demoContentReplaced。docsite 的 Code 标签页、Open in Playground、Sandbox 代码视图、docsite MCP 服务器的 get() 以及 astryx component <Name> --showcase 只运行元素这一遍,因此它们保留 各自的夹具媒体(spec:AST-033 FR23)。实现缺口: demo-content 模块、元素遍历和 demoContentReplaced 尚未构建, 并且 shadcn Install 项两遍都不会运行。
  • packages/cli/foundation/config/project.mjs —— 项目诊断和当前 integration-template 重新收集。
  • packages/cli/api/template/ —— list、show、skeleton 和 copy 操作。
  • scripts/sync-templates.js —— 当前的沙箱注册表和预览路由。
  • apps/docsite/scripts/generate-data.mjs —— 当前的 docsite 页面、块、示例 和展示注册表。
  • apps/docsite/src/components/templateComponents.ts —— 当前手工维护的页面 预览加载器;其独立的成员关系是一个迁移缺口。

决定规范

  • spec:AST-017/DEC-2 —— 模板标识、元数据和起始源代码是可变的目录数据; 周围的 CLI 操作仍保持契约性。

验证

范围 当前证据 在 current 之前缺失
源形态与集成解析 parse.test.mjs、template-suffix.test.mjs、template-integration.test.mjs 一个语料库检查,将每个已发布的页面和块都通过规范化边界运行
目录成员资格与诊断 template-adapter.test.mjs、project.test.mjs 一个目录实现;无重复收集;每个无效源都被一致地报告
init 投影 init.test.mjs 从目录中选择每个指定的内置页面,而不是通过目录扫描
Docsite 与沙箱投影 data-extraction.test.ts、生成的注册表检查 从目录元数据派生的成员资格一致性和实时预览覆盖
复制边界 template.test.mjs、template-suffix.test.mjs 针对仅预览资源移除和快照独立性的变异覆盖
演示内容替换 无;尚未构建 Copy、template show、shadcn Install 项、Code 选项卡、Open in Playground、Sandbox 代码视图、MCP get() 和 --showcase 输出均不包含 demo-content 元素或 demo-content 导入;copy 回执和 template show 会对这些元素计数;shadcn Install 项不包含 /template-assets/ 引用;只提供源代码的界面保留其 fixture 媒体;实时预览渲染的是原始内容
评分标准证据 携带 commit 和 rubricVersion 的版本化记分卡 架构方面无缺失;分数仍然是审计证据,而非权威依据

已发布目录审计

在 067b176 进行的一次精确源代码审计发现:

  • 53 个页面源代码/元数据对。全部通过当前的 parseTemplate() 边界。 其中四十个是 overview 投影中可见的、就绪的非脚手架页面。其中一个 work-item-detail 缺少实时预览加载器。
  • 所有四十个 overview 可见页面都保留了 host-chrome 边界。唯一的 源代码形态例外是未完成的 messaging-shell;blank 是有意为之的最小脚手架, 而非画廊页面。
  • 644 个块源代码/元数据对,没有孤立的源代码或元数据文件。每个 块都声明了 type、name、displayName、isReady、exampleFor、正数的 aspectRatio 和非空的 componentsUsed。审计并未证明每个 数组都列出了其源代码导入的每一个组件;这种完整性仍然需要 一项可执行的检查。
  • 158 个主 showcase 块解析到 158 个不同的主目标。十四个 块添加了次 showcase 目标,二十个添加了次示例目标; 174 个扩展后的 showcase 目标没有冲突。
  • 三十五个主 showcase 省略了 description。当前内置发现机制 会将其转换为空字符串,而 parseTemplate() 会拒绝它。这是一个元数据 回填缺口,而非有意的 showcase 例外。
  • 核心块文件名主干 id 是唯一的。三对共享面向人类的 name 值; 这是 INV2 所允许的,并且不会产生 CLI 歧义。
  • TypeScript 类型、运行时解析器和贡献者字段表在 displayName、description、isReady、exampleFor、aspectRatio 和 componentsUsed 是否为必填项上存在分歧。解析器还接受 preview, 而 TypeScript 类型并未声明该字段。在此记录成为 current 之前,它们必须保持一致。

决策日志

目录收敛方向 — 2026-09-05

一个经过验证的目录拥有模板成员资格。特定于源代码的创作形态可以保持不同, 但每个源代码都通过相同的验证边界进行规范化。CLI、init、项目、sandbox 和 docsite 行为成为显式的、由元数据驱动的投影。并行的收集器和手工维护的 成员资格是迁移缺口。

语料库审计 — 2026-09-09

在 067b176 处枚举了每个已发布的页面和块。审计添加了上面的角色矩阵, 并识别出执行、元数据和预览注册方面的缺口。这些缺口阻碍了向 current 的提升;它们不会让清单消失,也不会将现有的审计分数变成架构权威。

未决问题

  • OQ1 — 审批路由。 在此记录成为 current 之前,哪些仓库所有者 必须批准一项既涉及模板视觉意图又涉及创作/运行时行为的变更?
  • OQ2 — 评分标准所在地。 版本化的评分标准是否应移入其自己的 仓库记录,同时让 wiki 成为面向贡献者的参考文档,还是 wiki 仍应保持其权威地位?

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx