什么是 SiteSpec——网站真正的存储形态

SiteSpec 是网站被存储成的那份 JSON 文档。它不是构建产物，不是缓存，也不是导出结果：它就是网站本身。当你向构建器描述一个站点、当你在工作台里编辑它、当某个渲染器把它送到访客面前时，三方读的是同一份文档。

这个名字来自 specification——规格。它规定的是站点包含什么，而不是它如何被构建出来，也不是某个框架该拿它怎么办。

它装了什么

这份文档很小，而且是封闭的：十个顶层字段，除此之外一概不读。

• name——站点叫什么。
• theme——字体、颜色、圆角、明暗模式，以及限定作用域的 CSS 覆盖。
• pages——各自由路由、语言版本，以及一段有序的区块列表构成。
• collections——带类型的数据行，以及它们的字段定义。
• forms——站点级的表单定义，由用到它们的表单区块引用。
• header、footer、floats——页面四周的那一圈。
• seo——搜索设置。
• locales——基准语言，以及它被翻译成的那些语言。

渲染器会用到的每一个字段都会被校验，其余的则被刻意忽略。原因很简单：这份文档由语言模型撰写，而这份契约的职责，是让一份格式错误的文档在边界上大声失败，而不是渲染出一张空白页面。

区块词表

一个页面是一串区块，而区块取自一组已注册的二十四种类型：hero、features、richText、gallery、pricing、faq、contact、cta、stats、testimonials、team、collection、form、logos、timeline、video、banner、comparison、codeSnippet、splitFeature、menu、location、booking、marquee。

它是一个封闭集合，而这正是重点。一个页面不是任意 HTML 的拼装——它是一串已知的形状，这既让渲染器可以是确定性的，也让校验器能在发布之前告诉你某个区块类型不存在，而不是之后。

为什么是文档，而不是生成出来的代码

text
                         one document
                      ┌──────────────┐
                      │   SiteSpec   │
                      └───────┬───────┘
                              │
            ┌─────────────────┼─────────────────┐
            │                 │                 │
       the builder        the studio       the renderer
        writes it          edits it         serves it

因为代码必须被运行，而运行就意味着要选定运行时、框架，以及两者的版本——然后永远维护这个选择。文档只需要被读取，而每一个读取者都可以替换，文档本身不必改变。

这正是「工作台里的一次编辑」与「对话里的一次重新生成」永远不可能对站点内容产生分歧的全部原因：它们不是关于这个站点的两份描述，而是同一份文档的两个视图。

它换来了什么

由这个形态自然导出三件事：

1. 可移植是一次编译，不是一次抢救。 在我们边缘节点上渲染的那份文档，是一份开放的 JSON，其内容可以通过公开 API 读取，不需要密钥。没有什么需要被「解锁」，因为从来就没有什么被锁住，而可移植指南替代了那个按钮。
2. 可 diff。 站点的变化就是文档的变化，因此它可以像你其余的代码一样被审阅、版本化与合并。
3. 可在渲染器之间迁移。 工作台预览与租户 Worker 是同一种格式的两个读取者，而你自己跑的一次构建是第三个——而不是三个需要时刻保持一致的实现。

你怎么把这份文档取出来

三条路，都不收费：

• 工作台的代码面板，就是这份文档的一份可复制的 JSON 视图。
• 公开 API 可以读它：内容集合、它们的字段定义，以及已发布的行，不需要密钥，也不需要登录。草稿不公开，从来如此。
• 你自己在别处做的构建，由同一条边缘线路原样送出——所以一份静态产物包在这里是一等公民，而不是一个事后补丁。

可移植性指南是完整流程；退订之后网站会怎样是同一个问题的另一头。

诚实的边界

一份 SiteSpec 描述的是 Zeso 能够渲染的站点。它不是一个通用 Web 平台：没有注册的区块类型不会渲染，字段没有类型化的集合数据行也不会出现。这个格式是封闭的，而封闭正是它确定性的来源——但封闭是一种边界，不是一片无限。