跳到主要内容
AI教程

使用 EmDash Build 构建并运行可编辑的 AI 生成网站

了解 EmDash Build 如何将需求简介转换为可编辑的 EmDash 和 Astro 网站，了解其 Cloudflare 架构的工作原理，以及如何在本地进行配置和运行。本教程还将介绍代理工作流、验证命令、持久化、发布控制、安全注意事项和实用开发技巧。

AI我搜编辑部阅读约 10 分钟
使用 EmDash Build 构建并运行可编辑的 AI 生成网站

什么是 EmDash Build？

EmDash Build 是一个开源 AI 网站构建器，可将书面需求转化为可编辑的 EmDash 网站。它不会只生成静态页面标记，而是会创建结构化内容模型，通过 EmDash 的模型上下文协议服务器填充该模型，并生成用于渲染内容的类型化 Astro 页面和组件。

生成的项目包含服务器渲染页面、结构化内容、媒体存储以及 EmDash 管理界面。首次生成后，编辑者仍可继续使用该网站：更新文本和媒体、添加或复制区块、重新排列内容区块、安排文章发布时间，还可以要求代理执行较大规模的内容或设计修改。

重要提示：EmDash Build 是面向托管服务商、网站构建器和平台的 Alpha 参考应用。托管演示中的发布功能已禁用。

你可以探索托管演示，但无法从中发布网站。

主要功能

  • 结构化澄清：当需求中有重要决策尚未确定时，代理会提出有针对性的问题。
  • 由代理设计的内容模型：它会为可复用实体创建集合，并为编辑者可以重新排序的页面区块创建结构化区块。
  • 可编辑的 Astro 网站：前端使用类型化 Astro 组件，而普通内容仍可通过 EmDash 进行管理。
  • 实时预览与修复：项目会在私有 Builder 预览中渲染。代理可以验证输出、检查故障，并在同一循环中修复问题。
  • 内容工作流：编辑者可以通过 EmDash 管理界面管理文本、媒体、区段、区块和定时内容。
  • 持久化历史：源代码和本地 CMS 状态会以 Git 提交的形式存储在 Cloudflare Artifacts 中。
  • 受控发布：经过验证的静态版本可以打包到 Workers for Platforms，但只有在运营者明确启用并配置发布功能时才会执行。

架构工作方式

每个生成的项目都会获得一个 Cloudflare Sandbox，其中包含预先配置好的 EmDash、Astro 和 Tailwind 项目。一个名为 BuilderAgent 的 Durable Object 负责管理对话以及模型与工具的循环。

代理使用 EmDash MCP 工具创建架构和内容。它在 Sandbox 内编写公共前端，启动私有预览，验证渲染后的网站，并在完成一轮操作前修复错误。

Cloudflare Artifacts 将每个完整一致的项目状态作为 Git 历史记录存储。如果 Sandbox 进入休眠状态，EmDash Build 可以将源代码和本地 CMS 状态恢复到新的容器中，并重新启动预览。

代理工作流

  1. 理解：阅读需求并确定缺失的重要素材和决策。
  2. 建模：决定哪些数据应成为可复用集合，以及哪些页面需要结构化区块。
  3. 构建：创建 EmDash 架构、刷新生成的类型，并编写类型化 Astro 渲染器。
  4. 填充：通过 EmDash MCP 工具添加具有代表性的内容和媒体。
  5. 验证：对项目进行类型检查，渲染公共路由，检查预览并修复故障。
  6. 保存：将完整的项目状态提交到 Cloudflare Artifacts。

前置条件

本地开发同时依赖本地工具以及对多个 Cloudflare 服务的访问权限。在继续之前，请准备以下内容：

  • Node.js 24 或更高版本
  • pnpm 11.9
  • 正在运行的兼容 Docker 的守护进程
  • 已通过身份验证并连接到 Cloudflare 账户的 Wrangler
  • Cloudflare Workers 访问权限
  • Durable Objects 访问权限
  • Cloudflare Sandbox 访问权限
  • Workers AI 和 AI Gateway 访问权限
  • Cloudflare Artifacts 访问权限
  • Workers for Platforms 访问权限

由于提供商资源和信任边界需要谨慎配置，请在部署应用前阅读仓库中的自托管指南。

安装和配置 EmDash Build

1. 安装依赖

在仓库根目录中，安装锁定的依赖版本：

pnpm install --frozen-lockfile

2. 创建提供商配置

将 provider.config.example.json 复制为被忽略的 provider.config.json 文件：

cp provider.config.example.json provider.config.json

打开 provider.config.json，将每个示例值替换为 Cloudflare 账户中的对应资源。请按照自托管指南创建所需资源，不要依赖示例值。

3. 验证并渲染配置

运行预检，然后生成特定于提供商的 Wrangler 配置：

pnpm preflight
pnpm configure

文档所述本地启动命令使用的生成配置文件是 wrangler.provider.jsonc。在部署或运行敏感环境之前，请检查此提供商专用文件。

4. 配置本地密钥

复制开发环境密钥模板：

cp .dev.vars.example .dev.vars

将构建器所需的 AI Gateway 凭据添加到 .dev.vars 中。UNSPLASH_ACCESS_KEY 是可选的；添加后可在生成过程中启用图库图片搜索。

请勿将提供商凭据放入生成的项目中。发布由服务器控制，生成的网站不会获得提供商凭据。

5. 启动完整的本地应用

使用生成的提供商配置启动 EmDash Build：

EMDASH_WRANGLER_CONFIG=wrangler.provider.jsonc pnpm dev

开发服务器就绪后，打开 http://localhost:5173。

6. 在适当情况下启动仅 UI 模式

如果只需处理界面，请使用：

pnpm dev:ui

此模式不会启动基于 Sandbox 的网站生成。需要测试构建代理、项目创建或实时生成预览时，请使用完整的开发命令。

基本用法：根据需求生成网站

1. 编写有用的需求说明

描述目标网站、受众、主要页面、可复用内容以及期望的视觉方向。例如：

为一位冰岛风景摄影师创建一个作品集网站。
包括主页、可复用的照片集、关于页面，
以及编辑者可以重新排序的结构化页面区块。

如果需求说明中有重要选择尚未确定，代理可能会提出针对性的澄清问题。在期待生成一致的架构和前端之前，请先回答这些问题。

2. 让代理建模并构建网站

完成澄清后，代理会确定哪些信息应归入可复用集合，以及哪些叙事页面应使用结构化区块。随后，它会创建 EmDash 架构、刷新生成的类型、编写 Astro 渲染器，并通过 MCP 工具添加示例内容。

3. 查看私有预览

使用 Builder 的实时预览检查生成的路由和整体设计。EmDash Build 会验证生成的项目，并可在代理循环中修复检测到的问题。

4. 在 EmDash 中继续编辑

初始项目可用后，通过 EmDash 管理界面管理日常内容。你可以编辑文本和媒体、添加或复制区块、重新排列区块，以及安排文章发布。需要更大范围的结构、内容或设计变更时，再返回代理。

5. 保存和恢复项目状态

一致的项目状态会作为 Git 历史提交到 Cloudflare Artifacts。这种持久化机制使 EmDash Build 能够在 Sandbox 休眠且需要新容器时，恢复项目源代码和本地 CMS 状态。

验证与开发命令

请根据所做变更的类型，使用相应的仓库命令：

  • pnpm dev 使用默认配置启动 EmDash Build。
  • pnpm dev:ui 在不启动 Cloudflare Sandbox 容器的情况下启动界面。
  • pnpm check 对应用和 Worker 测试执行类型检查。
  • pnpm test 运行应用测试套件。
  • pnpm test:worker 运行 Workers 集成测试套件。
  • pnpm build 使用默认配置构建 EmDash Build。
  • pnpm build:provider 使用 wrangler.provider.jsonc 进行构建。
  • pnpm format 使用 oxfmt 格式化仓库。

提交贡献前，请运行项目建议的完整验证流程：

pnpm format
pnpm check
pnpm test
pnpm test:worker
pnpm build

高级提示

选择正确的开发模式

隔离处理界面工作时，请使用 pnpm dev:ui，因为它不会启动 Sandbox 容器。不要使用它来验证生成流程：仅 UI 模式不支持基于 Sandbox 的生成。

分离内容编辑与结构变更

日常编辑工作，例如修改文本、媒体、区块和排序，应使用 EmDash 管理界面。更大的设计或内容模型变更应使用代理。这样可以保持结构化 CMS 数据与类型化 Astro 渲染代码之间的职责划分。

检查提供商配置

仅将示例提供商配置视为模板。替换每个示例值，运行 pnpm preflight，使用 pnpm configure 生成 Wrangler 配置，并检查输出是否对应目标 Cloudflare 账户。

明确控制发布

公开发布由服务器控制，默认处于禁用状态。只有在运行中的提供商已准备好为 Workers for Platforms 打包经过验证的静态版本时，才启用并配置发布功能。托管演示也会保持发布禁用。

部署前检查安全边界

请参阅仓库的威胁模型，了解模型工具、Sandbox 执行、密钥、私有预览、持久化和发布的详细信息。有关运维检查，请使用运维指南。

高效浏览仓库

  • src/worker 包含 Worker 路由、BuilderAgent、提示词、工具、持久化和发布控制。
  • src/client 包含 React Builder 界面、聊天、活动视图和实时预览。
  • prototype/builder-cloudflare 包含用于新项目的预配置空白 EmDash 和 Astro 脚手架。
  • migrations 包含身份验证和提供商控制数据库迁移。
  • scripts 包含提供商配置、冒烟测试和运维辅助工具。
  • test 包含应用和 Worker 测试覆盖。
  • docs 包含自托管、安全、运维和实现文档。

结语

EmDash Build 将 AI 辅助生成与持久、可编辑的 CMS 工作流相结合。它会创建结构化的 EmDash 内容和类型化的 Astro 组件，在私有 Cloudflare Sandbox 预览中验证结果，并将项目历史记录存储在 Cloudflare Artifacts 中。由于它是一个 Alpha 参考应用，对基础设施有较高要求，请谨慎配置提供商资源，查阅安全文档，并确保对公开发布进行明确控制。