跳转至

Docsite 交互与产品数据契约

{
  "scope": "global",
  "triggers": {
    "docsite": [
      "DEC-1",
      "DEC-2",
      "DEC-3",
      "DEC-5",
      "FR3",
      "FR8",
      "FR13",
      "FR16",
      "FR17",
      "FR18",
      "FR19",
      "FR20",
      "FR21",
      "DEC-7",
      "DEC-8"
    ]
  }
}
{
  "paths": ["apps/docsite/**"]
}

意图

使用 Astryx Docsite 的用户应当看到所属产品目录的如实投影,以及一个当前的交互状态。链接、浏览器历史、可见内容、分析数据以及 latest/canary 呈现,都应当与用户所选择和实际可用的内容保持一致。

本契约统辖 Docsite 共享的交互与产品数据规则。它让那些恢复这些规则的常规修复变得可审查,而无需为每个 bug 单独编写规格说明。

非目标

  • 定义上游组件、模板、主题、包或目录的编写模式。本契约始于 Docsite 所消费的注册表边界。
  • 定义由 spec:AST-028 负责的模板夹具预览与复制行为。
  • 为单个 Docsite 页面选择视觉设计、动画、布局或文案。
  • 选择遥测供应商、传输方式、保留策略或仪表盘。
  • 添加包 API、主题目标或消费者运行时。
  • 将某个拉取请求、bug 或当前实现机制视为权威。

需求

规范产品数据

  • FR1 — 上游所有者提供产品事实。 规范的组件、模板、主题、包和目录所有者定义条目身份、包所有权、分类法、就绪状态、发布渠道准入和显式可见性。路由所有者定义稳定目的地。Docsite 流水线和生成的注册表将这些事实具体化;它们 MUST NOT 凭空捏造第二套身份、分类、就绪状态、可用性规则或可见性规则。当当前没有上游所有者定义某个必要事实时,Docsite 会报告或路由该权威缺口,而不是在视图代码中自行决定。
  • FR2 — 投影保留目录事实。 画廊、侧边栏、直接路由、详情页、预览、playground 交接以及 Docsite API 投影 MUST 从生成的注册表派生成员资格和规范条目事实。某个界面可以定义本地显示顺序、缩短标签,或从规范字段以确定性回退方式派生仅用于显示的组。这些呈现选择 MUST NOT 改变目录成员资格,也不得被导出或复用为规范分类法。站点搜索使用 CLI 自身的搜索来回答:构建过程会存储构建站点所用的 CLI 包的 exportSearchIndex() 在站点项目中所收集的候选内容,站点的搜索端点使用该包的 rankSearchIndex() 对它们排序,并按 CLI 的顺序返回结果,因此站点与 astryx search 给出同一个答案。端点在回答时不收集任何内容:启动的搜索服务器不会读取任何文档或包。存储的候选内容是该 CLI 自身的收集结果,由同一个 CLI 版本生成并排序,并且它们保留在服务器上。生成的注册表仍然是这些结果所打开的页面与链接的源头。
  • FR3 — 可用性与可见性是相互独立的投影。 可用性是指某个具名的 Docsite 操作拥有在当前内容线路上呈现已准入条目所需的来源、加载器、路由或交接。可见性是指一个本来可用的条目被列在某个具名界面上。可见性字段 MUST 指明或记录它所排除的投影。从概览中隐藏某个条目 MUST NOT 静默移除其直接路由、搜索结果、预览或 playground 可用性,并且某个投影 MUST NOT 从类似的标志推断这些影响。缺失、无效或矛盾的准入元数据应当失败即关闭,而不是让一个不可用的条目看起来可用。

Latest、Canary 与就绪状态

  • FR4 — 发布渠道、就绪状态和可见性彼此不同。 包的 canaryOnly 元数据负责包发布渠道的准入。当前生成的组件将该包渠道投影为 isReady: false;它们不会另行编写独立的组件就绪字段。模板的 isReady 仍然是模板编写的条目就绪状态。显式可见性元数据负责已准入条目被列在何处。任何投影都不得发明另一种渠道、就绪状态或可见性状态。
  • FR5 — 每次构建都标识其实际的内容来源。 latest 固定已发布的稳定包元数据和包文档。Canary、本地开发和拉取请求预览可以读取已配置的 workspace/canary 包。在流水线当前声明该边界的两个目标上,可执行的 CLI 模板和块、它们的实时示例、长篇 CLI 文档以及 Docsite 编写的内容仍然以 workspace 为后端。某个投影 MUST NOT 仅仅因为构建目标是 latest,就把以 workspace 为后端的内容描述为发布固定。站点搜索在两个目标上均以 workspace 为后端:它使用构建站点所用的 CLI 进行排序,排序的对象是该 CLI 在站点构建时所读取的 workspace 文档和包,与站点的 CLI 参考页面同出一个来源。在 latest 上,它会排除没有已发布文档的集成;如果某个结果的页面尚未发布,则会链接到最近的已发布索引页。
  • FR6 — Canary 状态在其所属层级只投影一次。 当子项共享 canary 状态时,界面应当将 canary 状态归组到包或类别层级,而不是在每个条目上重复标记。安装命令、搜索结果、详情页和 API 输出 MUST 与相同的渠道和就绪事实保持一致。可见性仍然是一个独立投影。
  • FR7 — Docsite 目标操作使用共享导航契约。 其结果是一个 URL 或另一个可寻址 Docsite 状态的操作,即导航目标。family:navigation-destinations 负责目标验收以及受支持的原生/路由行为,包括真正的 href/to 接收端和浏览器自带的交互能力。点击处理器可以添加分析,但 MUST NOT 成为第二个或唯一的导航机制。
  • FR8 — 可寻址状态在每个界面上只有一个规范 URL。 组件、模板、主题、标签页或其他旨在直接链接或恢复的状态,在其所属界面上 MUST 有一种规范 URL 编码。历史别名或便利别名可以重定向或规范化到该 URL。直接加载、应用内打开与关闭、软导航、后退和前进 MUST 保持一致。由目录支持的标识通过所属注册表解析;路由本地的标签页和其他视图值通过路由所有者解析,而不是嵌入或复制产品数据。
  • FR9 — 主选择压入历史;次要视图状态替换当前条目。 选择不同的主目录条目会创建一条历史记录,后退和前进会遍历这些选择。URL 编码的标签页、选择器、筛选器、排序顺序和规范化会替换当前条目。纯粹本地且瞬态的呈现状态无需进入 URL。某个界面 MUST NOT 仅仅为了不恢复主可寻址选择而使用替换。

选择与异步工作

  • FR10 — 当前选择拥有可见内容。 所选项目的标题、正文、操作、命令、无障碍名称和分析上下文 MUST 从同一当前已提交的选择中解析。打开、重新打开、深链接、URL 恢复或直接选择 MUST NOT 显示先前所选项目的内容。
  • FR11 — 延迟内容限定在其发起过渡内。 仅当发起该工作的确切导航仍保持当前状态时,过渡 MAY 在显式待处理效果之下保留先前内容。关闭、取消、更新的选择、更新的导航或卸载都会取代该工作。已关闭或被取代的工作 MUST NOT 重新绘制可见内容、替换当前元数据、移动焦点、更新规范 URL 或发出成功事件。
  • FR12 — 影响选择的异步完成通过当前所有权提交。 能够重新绘制所选预览或提交选择所属元数据、焦点或 URL 状态的异步工作 MUST 在提交前验证其请求仍然拥有该选择。请求身份或取消由实现负责;没有请求所有权的全局待处理状态是不够的。常规 Docsite 请求生命周期和外部同步仍由本记录及所属 Docsite 组件负责;architecture:react-component-runtime 提供了类似的 Core/Lab 生命周期约束,但不拥有 apps/docsite。复制、保存、导出和分享的结算时机仍归 FR15 管理。

交互分析

  • FR13 — 单一类型化模块拥有自定义分析。 共享的 Docsite 分析模块拥有小型自定义事件词汇和属性模式。item、package 和 category 属性使用规范注册表标识符。每个有限的代码自有维度——包括页面、目标、来源、类型、方向、标签页、视图和切换值——都使用封闭的代码自有词汇,而非不受限制的调用方字符串。事件 MUST NOT 包含用户撰写的来源、自由格式内容、URL 片段或其他可识别个人身份或意外高基数的数据。
  • FR14 — 语义操作拥有者仅发出一次。 接受或提交直接用户操作的代码最多发出一个匹配的自定义事件。渲染、水合、副作用、URL 恢复、路由器同步、预取、后台工作和自动页面加载不得发出自定义交互事件。Root analytics 拥有自动页面浏览。
  • FR15 — 事件时机遵循声明。 导航意图在有效用户激活被接受时可能记录日志,因为真正的链接拥有完成权。复制、导出、保存、分享及类似成功声明仅在操作成功后记录日志。已取消、被拒绝、失败、被忽略、已关闭或被取代的工作 MUST NOT 发出成功事件。

Playground 存储与父页面隔离

  • FR16 — 生产 Playground 代码与存储和父页面隔离。 生产环境预览(包括已部署的拉取请求预览)MUST 以不透明来源(opaque origin)执行用户编写的代码,无权访问 Docsite 绑定来源的存储或父页面 DOM。本地存储可能被完全阻止;被预览的代码没有持久性保证。Playground MUST 向用户解释这些限制。本地开发 MAY 有所不同,但 MUST NOT 充当生产隔离证据。

重新加载或恶意导航可能会重置预览运行时状态。Playground MUST 以编辑器的当前代码和活动主题/模式恢复可信预览。替换内容 MUST NOT 仅仅因为占据预览位置就获得编辑器源代码、主题状态或编辑父页面的权限。

对此边界的更改需要真实生产浏览器的证据,证明存储和父 DOM 被拒绝、重载和恶意导航后可可信恢复,以及当前代码和主题/模式被恢复。

已发布表面与部署身份

  • FR17 — 生产环境有唯一的精确头部拥有者。 规范的生产 Docsite 来源 MUST 从同一次成功的主分支部署中提供文档、/storybook/ 和 /sandbox/。无法暂存任一静态应用的构建 MUST 失败,而不是发布部分版本。Docsite MUST 向两个应用提供真实链接。
  • FR18 — 静态应用路由保持可寻址。 Storybook 管理器和 iframe URL、Sandbox 路由目录和嵌入、静态资源、查询参数和片段 MUST 在其规范路径上直接加载后仍然有效。路由规范化 MAY 保留或移除尾部斜杠,但 MUST 保留所选的应用状态,且 MUST NOT 回退到无关的 Docsite 内容。
  • FR19 — 规范和索引元数据与表面匹配。 生产环境入口和可寻址路由页面标明其 https://astryx.atmeta.com 规范 URL。拉取请求预览、独立 Storybook 框架、Sandbox 嵌入和兼容性页面 MUST 为 noindex;预览 MUST NOT 声明生产规范 URL。
  • FR20 — 部署身份精确且由生成产生。 每个 Vercel Preview 和生产构建 MUST 在 /version.json 中暴露其完整的 40 字符源代码提交和部署环境。缺少源代码身份会使构建失败。生成的标识和暂存的应用 MUST NOT 进入源代码管理。
  • FR21 — 原有 Pages 来源是单一兼容表面。 GitHub Pages MUST 仅提供一个小型、无障碍、响应式落地页和等效的深路径恢复页面。文档是主要的规范目标;Storybook 和 Sandbox 被标记为次要目标。旧的 Storybook 或 Sandbox 路径 MAY 随其查询和片段带入相应的链接,但兼容性页面 MUST NOT 自动重定向、构建任一应用或托管 CI 证据。

博客文章

  • FR22 — 博客文章渲染可运行示例代码块。 博客文章 Markdown 中信息字符串为 tsx live 的围栏代码块,通过 Docsite 现有的实时示例渲染器——Playground 预览框架(/playground/preview)——渲染为可运行示例;该框架在浏览器中编译代码块源代码,并针对生成的预览作用域解析其导入。示例以沙盒方式运行,因此文章不会破坏页面:每个代码块都有自己遵循 FR16 边界的框架,一个仅含 allow-scripts 的沙盒,具有不透明来源,因此其样式和脚本仅停留在该框架内;编译或运行时错误显示在框架内,而文章的其余部分照常渲染。示例 MAY 导入已发布的 Astryx 包和位于文章 Markdown 文件旁的帖子本地示例资源,例如仅文档演示组件(如塔罗牌);这些资源不是 Astryx 组件,不从任何包导出,不进入任何目录,并且仅为其所属文章解析。纯文本文章路由在运行示例的位置显示静态回退:代码块源代码以普通代码块形式展示,读取方式与页面读取围栏的方式相同(也读取块引用和列表项内部,且绝不在另一个围栏代码块内部读取)。RSS 条目携带文章的描述且不包含正文,因此示例不会进入订阅源。文章的示例资源存放在以文章命名的文件夹中,位于其 Markdown 文件旁,并且仅在该文章实时示例的框架中加载。位于 src/content/blog/fixtures/ 下的测试 fixture 文章仅在 canary 中提供,且绝不会列在博客索引、订阅源或站点地图中。

示例代码

  • FR23 — 示例源码以与复制相同的方式替换演示内容。 在动效或手势示例中,真实的 Astryx 组件可能包裹仅用于文档的演示内容,例如 <Card><PlayingCardContents /></Card>。实时示例渲染原始内容。每个分发示例源码的界面都在 spec:AST-028 FR13 的演示内容元素替换之后携带该源码:每个演示内容元素变为通用占位符,源码不保留对定义它的代码的任何引用,外层组件保留其属性和行为。如果某个演示内容包装器只是为真实组件添加仅用于文档的呈现(例如用法提示),则将其移除而非替换:源码保留被包裹的组件及其属性,如同该包装器不存在一样。仅分发源码的界面只执行该替换,因此各自保留其固定媒体:Code 标签页及其复制操作;Open in Playground,它会打开并运行替换后的源码,因此 Playground 显示占位符;Sandbox 代码视图及其 Copy source 操作;以及 MCP 服务器的 get(),其组件结果携带展示示例的源码和另一个示例的源码,其模板结果携带模板的示例源码,若无示例源码则携带页面源码。shadcn Install 项将示例写入使用方的项目,因此它是 spec:AST-028 FR13 下的一份副本,其注册表项携带的源码中固定媒体和演示内容元素均已替换。集成包块显示 template show 的输出,因此其显示的代码已替换固定媒体。

权威路由

architecture:knowledge-contracts 负责公共增量路由和变更处置。本记录提供预期的 Docsite 行为;它不会因为某个拉取请求的标题声称是 bug 修复而预先批准它。审查者将每个可观察的增量映射到适用的当前所有者。新的交互模型、异常、公共 API、事件含义、可见性轴、分类法或数据所有者仍然是一个独立的合约增量。

平台支持

  • 支持的功能/引擎下限:Docsite 当前支持的浏览器和 Next.js 路由器集成。
  • 不支持的行为:无法保留真实链接或规范 URL 的客户端 MUST 保留可用的整页导航;它 MUST NOT 用仅点击的控件代替,或静默丢失目标地址。
  • 浏览器证据:真实 Chromium 验证链接可供性、后退/前进、选区恢复、焦点以及待处理/关闭/取代行为。仅 DOM 层面的证据不能证明浏览器历史记录,也不能证明未出现绘制的陈旧内容。

当前状态影响

当前 Docsite 已经从仓库元数据生成包、组件、模板、文档、块、主题和组件预览注册表。已发布的包元数据和包文档使用 latest/canary 内容根,而可执行模板、块、示例、长篇 CLI 文档以及 Docsite 自编内容仍然以工作区为支撑。 大多数导航操作暴露真实链接,一个分析模块拥有一个小型事件词汇表。

已知的符合性差距仍是实现工作:

  • 一些画廊和 Playground 的成员资格/分类数据仍保留在页面或脚本本地列表中,而非规范元数据或生成的注册表中;模板实时预览的成员资格仍保留在手工维护的映射中;
  • 模板就绪状态和可见性未在画廊、搜索、直接路由、预览和 Playground 之间一致地呈现;
  • 主主题选择目前会替换历史记录,主题搜索结果会将每个选中的主题折叠为裸 /themes,从而恢复默认种子而不是搜索到的身份;
  • 可寻址的模板预览具有规范的 ?preview= URL,但画廊卡片和 Preview 按钮仍然是仅点击的控件,而非链接支持的目的地;
  • 主模板预览选择目前会替换历史记录,而不是创建浏览步骤;
  • 模板预览可能在其所属的确切待处理导航之外保留延迟的先前选择;
  • 分析仍然允许 item、package、category、source、type、tab、view 和 toggle-value 字段使用不受限制的字符串上下文,并且嵌套的模板预览激活可能对同一语义动作触发两次;以及
  • 现有交互测试尚未覆盖完整的主选择、后退/前进、关闭、取消和取代矩阵。

Code 标签页、Open in Playground、Sandbox 代码视图和 MCP 服务器的 get() 在演示内容元素替换后携带示例源码,并保留固定媒体。shadcn Install 项携带的示例源码中,演示内容元素和固定媒体均已替换(FR23)。

稳定的 Storybook 和 Sandbox 目前使用拆分部署:拉取请求预览暂存在 Vercel Docsite 内部,而稳定的 main 通过单独的 GitHub Pages 分支重新构建并发布。这导致应用构建重复,使生产环境所有权变得模糊,并使原来的 Pages 源站承载无关的预览和证据存储。

已接受的目标让 Vercel 成为所有三个界面的唯一生产环境所有者,并将 GitHub Pages 缩减为 FR21 兼容页面。它不新增任何包或使用方运行时 API;/version.json 是用于验证已在为这些公共界面提供服务的确切源码的部署证据。

验证

合约 验证 代表性状态 变更或失败预期
--------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FR1–FR3 生成器/数据提取测试及跨投影清单;搜索端点与 astryx search --json 保持一致,并保留其首次请求的读取记录 包、组件、模板、主题;画廊、侧边栏、搜索、直接路由、预览、游乐场 本地映射更改成员资格或规范条目事实,可用性与可见性合并为单一投影,或搜索端点在应答时才收集数据
FR4–FR6 最新版/canary 生成与投影测试 稳定包、仅 canary 包、就绪/未就绪条目、概览隐藏条目、无效集成元数据 最新版暴露 canary 包文档,工作区支持的内容被称为发布固定,出现第二种就绪状态,或投影不一致
FR7–FR9 导航系列检查及真实浏览器导航/历史记录测试 直接链接、修饰点击、新标签页、深层链接、主选择、辅助标签/筛选、规范化、后退/前进 Docsite 对目标位置错误分类,规范身份产生分歧,主选择相互替换,或辅助状态使历史记录杂乱
FR10–FR12 选择/过渡测试以及真实浏览器的可见内容检查 初始打开、重新打开、深链、直接选择、待定的上一个/下一个、关闭、取代、拒绝、卸载 头部/正文/操作不一致、过期内容在没有其所属待定状态的情况下被渲染、或过时的选择工作在取代之后被提交
FR13–FR15 分析数据结构以及使用传输探针的交互测试 导航意图、复制成功/失败、取消、URL 恢复、渲染/副作用、重复激活 事件名称/属性漂移、记录了自由格式/高基数数据、被动生命周期发出事件、失败时记录成功、或同一操作发出两次事件
FR16 生产浏览器 playground 的隔离与恢复测试 直接加载、重新加载、恶意导航、存储与父级 DOM 访问被拒 预览代码触达父级/存储,或可信恢复还原了过时的源码/主题
FR17–FR21 精确 head 的 Vercel 构建、路由/资源探针、元数据检查以及 Pages 落地契约 生产环境与 PR Preview;Storybook 管理器/frame;Sandbox 路由/嵌入;旧根路径/深层路径;桌面端/移动端;浅色/深色 某个应用缺失或过时、直接资源/路由失败、元数据声明了错误的所有者、身份漂移,或 Pages 承载了兼容页之外的更多内容
FR22 e2e/blog-live-examples.spec.ts(真实浏览器中的文章、纯文本路由、feed、sitemap 和索引检查)以及 blog-live-examples.test.tsx(围栏规则、静态回退、fixture 列表、运行器) 一篇文章包含 tsx live 代码块;该文章的纯文本路由;一个导入文章本地资源的代码块;一个编译失败或抛错的代码块;位于块引用、列表项,以及较长围栏内部被引用的 live 围栏 live 代码块未在浏览器中运行;文本路由显示的不是页面所运行围栏的源码回退;文章本地导入无法解析;损坏的示例导致其框架之外的页面崩溃;或者 feed、sitemap 或索引列出了该 fixture
FR23 对每个输出面进行输出检查,外加真实浏览器的 live 示例检查 一个 motion 或 gesture 示例,其 Card 包装了 demo-content 元素;一个 Card 位于仅文档(docs-only)提示包装器中的示例;其 Code 选项卡及复制的文本;其 Open in Playground 源码;其 Sandbox 代码视图及复制的源码;其 MCP get() 组件和模板结果;其 shadcn 注册表项以及安装的 .astryx/<item>.json 收据;一个带 fixture 媒体的示例;集成包代码块显示的代码;其 live 预览 任何这些输出面仍然引用 demo-content 元素或定义它的代码,或仍保留仅文档包装器或其提示文本;外层组件或其 props 发生变化;仅提供源码的输出面上 fixture 媒体发生变化;shadcn 注册表项或集成包代码块显示的代码仍然引用 /template-assets/,或安装的收据不是已发布 v2 形态;或 live 预览不再渲染原始内容

决策日志

DEC-1 — 产品数据只有一个由注册表支持的所有者

参考: spec:AST-033/DEC-1 决策者: cixzhang,2026-09-09

上游的权威元数据和目录所有者定义产品事实。生成的注册表为 Docsite 物化这些事实;视图投影它们,而不会创建另一个目录。

已否决:页面拥有的条目列表、并行的成员/分类映射,以及在没有上游所有者时由生成器编造产品策略的做法。

站点搜索遵循 DEC-8。

DEC-2 — 浏览器历史遵循语义权重

参考: spec:AST-033/DEC-2 决策者: cixzhang,2026-05-01

主要目录项选择属于导航行为并会压入历史记录。URL 编码的次要标签页、选择器、过滤器、排序顺序和规范化操作会替换当前条目。纯本地的临时性展示不必进入 URL。这样可让后退和前进跟随用户的浏览路径,而不会让次要控件变得繁琐。

已否决:替换主要选择、将每次次要调整都压入历史,以及把不可寻址的临时性展示放入历史记录。

DEC-3 — 自定义分析归属于直接用户操作

参考: spec:AST-033/DEC-3 决策者: cixzhang,2026-06-10

一套类型化词汇表记录直接交互。根级分析拥有自动页面浏览;渲染、效果和 URL 恢复不会制造自定义互动。成功事件只在成功后触发。

已否决:页面加载效果重复触发自动分析,以及在实际完成之前就触发的乐观复制/保存成功事件。

DEC-4 — Canary 通道与就绪状态保持分离

参考: spec:AST-033/DEC-4 决策者: cixzhang, 2026-09-06

仅限 Canary 的包在 canary 线上公开可见,用于晋升前的审查,并且不出现在最新包文档中。包通道可以呈现组件的 isReady: false;Docsite 视图不会发明另一种不稳定状态,可见性保持独立。

已否决:并行的不稳定标志、隐藏的 Canary 专用内容,以及页面级 Canary 白名单。

DEC-5 — 当前选择优先于过期的异步工作

参考: spec:AST-033/DEC-5 决策者: cixzhang, 2026-09-09

当前已提交的选择拥有可见内容。延迟内容仅允许出现在保留它的那个确切待处理转换中,并带有明确的待处理标记。关闭或取代该转换即结束该权限。

已否决:用一个全局的 pending/延迟值来重绘新打开、已关闭或更新的选择。

DEC-6 — 试用代码不要求持久化或父页面访问

参考: spec:AST-033/DEC-6 决策者: cixzhang, 2026-09-23

Playground 用于试用 Astryx 代码,而不是存储本地数据。生产环境预览具有不透明来源,无法访问 Docsite 的来源绑定存储或父页面 DOM。被预览的代码没有持久性保证;相关限制会向用户说明。开发环境可能有所不同。重新加载或恶意导航后,会以当前的编辑器代码和主题/模式恢复出一个受信任的预览。

已否决:将本地持久化或父页面 DOM 访问视为 Playground 的保证。

DEC-7 — Vercel 拥有每一个受维护的生产界面

参考: spec:AST-033/DEC-7 决策者: cixzhang, 2026-09-29

生产环境的 Docsite、Storybook 和 Sandbox 从权威 Vercel 源上的确切主提交一起发布。GitHub Pages 仅保留为一个面向旧书签的 noindex 兼容着陆页,文档优先,并附带 Storybook 和 Sandbox 的直接目标地址。拉取请求预览保持相同的 Vercel 路径,并继续保持非权威性。

已否决:在 gh-pages 上继续构建第二个稳定应用、静默丢弃旧书签、在没有恢复选择的情况下自动重定向所有旧深层路径,以及使用兼容源作为视觉或测试证据。

参考: spec:AST-033/DEC-8 决策者: josephfarina, 2026-10-21

维护者决定:站点搜索使用 CLI 的搜索,而不是使用从注册表派生的单独索引,并在每个目标上读取站点构建所使用的工作区文档,从而让每项搜索改进都能到达线上站点。因为只有一份排名实现,所以每项搜索改进都能抵达站点,且无需保留任何需要同步的副本。一项一致性测试将端点与站点项目的 astryx search --json 保持相等。

已否决:站点自有的索引或排名,以及必须跟踪每个 CLI 版本的浏览器端搜索数据副本。

DEC-9 — 博客文章在现有沙盒渲染器中运行示例

参考: spec:AST-033/DEC-9 决策者: cixzhang, 2026-11-01

博客文章支持在文章内部包含可运行的 HTML 块,因此文章可以用不是 Astryx 组件的演示素材(例如塔罗牌)来演示 Astryx。tsx live 代码围栏通过 Playground 预览框架及其 FR16 隔离运行,因此文章示例与 Playground 会话共享同一个渲染器和同一个沙盒边界。文章本地的演示素材留在文章旁边,并位于所有包和目录之外。

已否决:额外构建一个仅用于博客、且需要自带隔离机制的渲染器。

DEC-10 — 示例代码像复制那样替换演示内容

参考: spec:AST-033/DEC-10 决策者: cixzhang, 2026-11-01

动效和手势示例可以在真实 Astryx 组件内部展示仅文档可见的演示内容(例如扑克牌面),而无需为每个示例维护第二份副本。每个分发示例源码的界面都会运行 CLI 复制操作的演示内容元素替换(spec:AST-028/DEC-4),因此个人或代理读取、复制、打开或安装到的演示内容,都是 CLI 复制写入的通用占位符。仅分发源码的界面不运行其他复制步骤。shadcn 的 Install 项会写入使用者的项目,因此它既是一次复制,同时也会替换固定媒体。

已否决:为每个示例维护仅文档用的重复副本,这会增加需要同步的文档。

未决问题

无。

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