da-content

DA + EDS 内容参考

参考技能——不是工作流。每当你需要了解通过 Adobe Document Authoring（DA）和 Edge Delivery Services（EDS）生成、上传或交付内容的规则时，请使用它。

此技能汇总了三个主要方面的规则。根据当前任务加载相应参考文档：

操作	阅读
为 DA 上传生成 HTML	references/html-content.md
上传图片、视频、PDF、字体	references/media.md
调用 DA 管理 API、处理身份验证、预览/发布	references/platform.md
通过实证重新验证资源边界行为	references/fixtures/README.md

参考文档中的每项事实性陈述都标有 [verified]（从代码读取或通过实证观察）或 [assumed]（根据文档推断，未直接验证）。

何时使用此技能

遇到以下情况时，请调用此技能：

• 生成要上传到 DA 的 HTML（admin.da.live/source/...）。
• 向 DA 上传任何二进制文件（PNG、JPG、SVG、MP4、PDF、WOFF2）。
• 直接调用 admin.da.live（Source API）或 admin.hlx.page（预览/发布 API）。
• 读取存储在 DA 中的 HTML 文档，并在重新上传前对其进行修改。
• 诊断为什么生成的页面在 aem.page / aem.live 上渲染不正确（无提示失败：图片显示为 about:error、缺少 meta 标签、区块渲染为不带 JS 或 CSS 的纯 HTML）。

何时不要使用此技能

• 为项目编写区块 JS 或 CSS——请使用 building-blocks。此技能涵盖内容侧，而非代码侧。
• Universal Editor、结构化内容创作或 AEM Cloud Service（Java / OSGi / JCR）。这些内容不在此技能范围内。

相关技能

• da-auth — 获取每次 admin.da.live 和 admin.hlx.page 调用所需的 IMS token。在此技能中执行任何需要 DA_TOKEN 的操作前，请先调用。
• generate-import-html — 为导入的页面生成符合 DA 要求的 HTML；此技能提供 HTML 必须符合的规则。
• page-import — 将完整页面导入规范的 EDS 区块格式。它会参考此技能中的 DA 侧规则。
• snowflake — 将静态内容转换为 EDS 覆盖层。除自身方法外，它还会加载此技能中的 DA HTML 和管理 API 规则。

最简上传示例

最常见的操作——将 HTML 文档上传到 DA。此示例集中展示了不太直观的规则：multipart/form-data 请求体、字段名 data、类型为 text/html 的 blob、Bearer IMS token，然后单独调用预览接口，让页面可通过 aem.page 访问。完整约定请参阅 references/platform.md，HTML 负载的格式要求请参阅 references/html-content.md。

# Use $DA_TOKEN from the da-auth skill, or read a cached token file directly.
# See platform.md §3 for the cache locations the various Adobe DA tools use.
TOKEN="${DA_TOKEN:?invoke the da-auth skill to obtain a DA admin token}"

# 1. Upload HTML — note multipart with field name "data" (other names silently fail)
curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -F "data=@./page.html;type=text/html" \
  "https://admin.da.live/source/{org}/{repo}/path/to/page.html"

# 2. Trigger preview — required separate step, path WITHOUT .html extension
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "https://admin.hlx.page/preview/{org}/{repo}/main/path/to/page"

# 3. Optional: publish to aem.live
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "https://admin.hlx.page/live/{org}/{repo}/main/path/to/page"

图片二进制文件采用相同方式上传（PUT 到 admin.da.live/source/...），但无需单独调用预览/发布接口——上传后会直接从 content.da.live 提供。引用这些图片的文档进行预览时，图片会被拉取到 Media Bus（按内容寻址，并生成响应式变体）——资源生命周期详见 references/media.md §2。

11 条静默失败规则

违反以下规则会导致内容损坏，而 DA、处理流水线或渲染器都不会报错。请牢记这些规则；上传前务必检查生成的输出。

1. DA HTML 是 body 片段。 不要包含 <!DOCTYPE>、<html>、<head>、<script>、<style> 或内联 style= 属性。交付时，处理流水线会从 Code Bus 注入 head、脚本和样式。 → html-content.md §1

2. 区块类用于编码区块标识（规范的 div 形式）。 最外层 <div> 带有 class="<block-name> [<variant>…]"。第一个 class 标记是区块名称，对应 /blocks/<name>/<name>.{js,css}。对于可接受的表格形式，表头为 <tr><td colspan="N">Name</td></tr>，其中 N 与内容行中单元格最多的行的单元格数相同；单列区块可以省略 colspan。格式错误的区块（缺少 div class、多列区块缺少 colspan、表头单元格为空）会作为普通 HTML 渲染，不加载区块 JS 或 CSS。 → html-content.md §3

3. 区块名称只能使用字母数字字符和单连字符。 不允许使用下划线、双连字符，也不能以数字开头。div 形式的变体：名称后的额外 class 标记（class="hero cta center"）。表格形式的变体：名称后括号中的内容（Hero (cta, center)）。两者通过 toBlockCSSClassNames 规范化为相同形式。 → html-content.md §3

4. Page Metadata 区块名称必须为 metadata。 div 形式：class="metadata"（单个小写标记）。表格形式：表头文本为 Metadata（不区分大小写）。任一形式中的拼写错误都会被静默忽略，不会生成 <meta> 标签。 → html-content.md §5

5. <img src> URL 必须可从 EDS 预览基础设施访问。 预览步骤会获取每个 <img src> 和 <source srcset> URL，对字节内容进行哈希，并将其存储在 Media Bus 中；交付的页面正是通过这种方式获得响应式 <picture> 变体。任何无法返回图片字节的 URL（DNS 失败、4xx/5xx、HTML 响应、超时超过 5 秒）都会生成 <img src="about:error">。不含主机名的路径（相对于仓库的 /path/foo.png、相对于文档的 ./foo.png）也会失败，因为摄取器没有可获取的内容。外部 URL 可正常使用，并会在首次预览时被旁加载。 → media.md §2，html-content.md §9

6. 只有需要稳定 URL 时才预先上传二进制文件。 旁加载意味着引用 HTML 中的图片前，无需将其上传到 DA；任何可访问的 URL 都可以使用。若希望二进制文件由 DA 管理，则预先上传到 /media/<scope>/<file>：这样不受第三方主机变更影响，可通过稳定的 content.da.live URL 访问，并且每次预览时都会重新获取到 Media Bus。 → media.md §2.5，media.md §13.2

7. DA Source API 要求使用字段名为 data 的 multipart/form-data。 使用其他字段名（file、image）会返回 200 OK，但不会写入文件。 → platform.md §2

8. SVG 硬性上限为 40 KB。 PNG/JPG/AVIF/WEBP 上限为 20 MB。MP4 上限为 36 MB。超出上限的 SVG 会导致预览 POST 失败，并返回 409 AEM_BACKEND_FETCH_FAILED（“Images N have failed validation”）；上传前请先检查文件大小。 → media.md §6.1

9. 预览 / 发布是必需的独立步骤。 上传到 DA 并不会让文档显示在 aem.page / aem.live 上。上传后，先向 admin.hlx.page/preview/... 发送 POST，再向 /live/... 发送 POST。 → platform.md §6

10. IMS 令牌会在不提示的情况下过期，并返回 401 和空响应体。 开发令牌有效期为 24 小时。长时间上传前，务必根据缓存令牌文件（da-auth 使用 ~/.aem/da-token.json，@adobe/aem-cli 使用 .hlx/.da-token.json）中的 expires_at 预先检查是否过期。 → platform.md §3

11. **块单元格内容采用比默认内容更严格的行内标签规范化规则。**在块单元格中，流水线会将 <b>/<i>/<s>/<mark>/<kbd> 重写为对应的语义标签 （<strong>/<em>/<del>/<em>/<code>），移除 <span> 和 <ins>，并按照位置规则处理 <br>。重写后，视觉样式仍会保留，但针对原始标签 或已移除类的 CSS 选择器将不再匹配。请仅使用 §3.9 保留列表生成 单元格内容，以避免内容被静默重塑。 → html-content.md §3.9

术语表

三个参考文档中使用的术语。

• Admin API — https://admin.hlx.page/<action>/... 端点系列。 用于控制文档生命周期（预览、发布、状态）。与 DA Source API 不同。
• Code Bus — 从受 Git 跟踪的 GitHub 分支提供的文件（通常包括 /fonts/、/icons/、/blocks/、/scripts/、/styles/、 /head.html）。通过代码部署更新。
• Content Bus — 从 DA 原始路径提供的文件（SVG、PDF、HTML、JSON、ICO、WOFF2）。通过预览/发布更新。
• DA editor — 面向用户编写文档的 Web 界面，地址为 https://da.live/edit#/...。
• DA Source API — 用于读取/写入 DA 跟踪文件（HTML 和二进制文件）的 https://admin.da.live/source/... 端点。
• Default content — EDS 页面中块以外的所有内容： 标题、段落、列表、链接、图像。以标准 HTML 呈现。
• Dot-folder — DA editor 自动创建的 /<parent>/.<docname>/ 文件夹，用于存放每个文档作者上传的图像。
• EDS — Edge Delivery Services。负责呈现并提供 aem.page（预览）和 aem.live（生产环境）的流水线，使用 DA 内容 + Code Bus + Media Bus。
• IMS token — Adobe Identity Management 访问令牌。缓存于 ~/.aem/da-token.json（通过 da-auth 技能）或 .hlx/.da-token.json （通过 @adobe/aem-cli 工具）。用于对 DA Source API 和 Admin API 进行身份验证。
• Media Bus — 用于图像和视频二进制文件（PNG、JPG、AVIF、WEBP、MP4）的内容寻址后端。 通过 SHA 哈希去重；永久缓存。
• /media folder — 用于存放多个文档/分支/迭代共用二进制文件的顶层 DA 文件夹惯例。首次 PUT 时自动创建。
• Preview / Publish — Admin API 操作，可将文档从“存储在 DA 中”转为“可通过 aem.page 访问”（预览）或“可通过 aem.live 访问”（发布）。
• Section — DA HTML 文档中直接位于 <main> 内部的 <div>。 装饰后会变为 <div class="section">。
• Section Metadata — 其 Style 键会为外层 section 添加 CSS 类的块。不是用于 SEO 元数据（SEO 元数据使用 Page Metadata）。
• Page Metadata — 键值行会在交付时转换为 <head> <meta> 标签的块。每页一个；通常位于文档末尾。