create-site

创建新的 AEM Edge Delivery 网站

此技能将引导你完成新建 AEM Edge Delivery 网站的完整接入流程。它会处理所有可自动化的事项，并明确指出需要人工操作的步骤。

何时使用此技能

在以下情况下使用此技能：

• 用户想从头创建一个全新的 AEM Edge Delivery 网站
• 用户要求“设置新网站”“创建新的 EDS 项目”或“接入新网站”
• 项目尚无 GitHub 仓库或 DA 内容

请勿在以下情况下使用此技能：

• 导入或迁移现有页面（请使用 page-import 技能）
• 在现有网站上构建或修改区块（请使用 content-driven-development 技能）

前提条件

• 拥有可在目标组织中创建仓库权限的 GitHub 帐户
• 可访问 DA（da.live）的 Adobe IMS 帐户
• 已通过身份验证的 gh CLI（gh auth status）或具有 repo 范围的 GitHub 个人访问令牌
• Node.js（用于通过 da-auth-helper 管理 DA 令牌）

相关技能

• page-import — 将现有页面导入新创建的网站
• content-driven-development — 网站创建后构建和修改区块
• building-blocks — 实现新的区块代码

---

步骤 0：创建 TodoList

创建一个清单以跟踪进度（如果有，请使用 Agent 的任务跟踪工具）：

1. 收集输入信息 — 已收集组织、仓库名称和网站名称
2. 创建 GitHub 仓库 — 已通过样板模板创建仓库
3. 安装 aem-code-sync （人工操作） — 已在仓库中安装 GitHub App
4. 通过 DA 进行身份验证 — 已获取有效的 IMS 令牌
5. 在 DA 中创建初始内容 — 已创建导航、页脚和索引
6. 触发预览 — 三个路径均返回 200/201
7. 交接 — 已向用户提供预览 URL 和 DA 链接

---

步骤 1：收集输入信息

向用户询问以下信息。提供所有必需信息之前，请勿继续。

1. GitHub 组织 — 将要创建仓库的 GitHub 组织或用户名（例如 my-org）
2. 项目名称 — 仓库名称，仅使用小写字母和连字符（例如 my-site）
3. 网站名称 — 内容中使用的易读名称（例如 My Site）。如果未提供，请根据项目名称生成。

存储为：{{ORG}}、{{REPO}}、{{SITE_NAME}}

---

步骤 2：创建 GitHub 仓库

使用 adobe/aem-boilerplate 模板创建新仓库。

选项 A — GitHub CLI（首选，可自动处理身份验证）：

gh repo create {{ORG}}/{{REPO}} \
  --template adobe/aem-boilerplate \
  --description "{{SITE_NAME}} — AEM Edge Delivery site" \
  --public

使用 gh auth status 检查 gh 是否可用。如果尚未通过身份验证，请先运行 gh auth login。

选项 B — GitHub API（如果 gh CLI 不可用）：

POST https://api.github.com/repos/adobe/aem-boilerplate/generate
Authorization: Bearer {{GITHUB_TOKEN}}
Content-Type: application/json

{
  "owner": "{{ORG}}",
  "name": "{{REPO}}",
  "description": "{{SITE_NAME}} — AEM Edge Delivery site",
  "private": false,
  "include_all_branches": false
}

获取令牌：https://github.com/settings/tokens/new — 范围：repo。

成功条件： HTTP 201（API）或退出代码 0（CLI）。仓库现已在 https://github.com/{{ORG}}/{{REPO}} 上线。

---

步骤 3：安装 aem-code-sync （需要人工操作）

aem-code-sync GitHub App 会将仓库连接到 AEM 的内容交付管道。此步骤无法自动化，用户必须在浏览器中完成。

告知用户：

需要执行操作： 在新仓库中安装 AEM Code Sync 应用。

1. 打开此 URL：https://github.com/apps/aem-code-sync/installations/new
2. 在“Repository access”下，选择 Only select repositories
3. 从列表中选择 {{ORG}}/{{REPO}}
4. 点击 Save

完成后回复“done”。

等待用户确认后再继续。

验证： 用户确认后，检查 https://admin.hlx.page/status/{{ORG}}/{{REPO}}/main/ 是否返回有效的 JSON 响应（而不是 404）。如果是，则表示应用已正确安装。

---

步骤 4：使用 DA 进行身份验证

DA 需要 Adobe IMS 身份验证。请选择合适的方式：

选项 A — da-auth-helper（首选）

da-auth-helper (https://github.com/adobe-rnd/da-auth-helper) 会将 IMS 令牌缓存到 ~/.aem/da-token.json。触发新的 OAuth 流程前，请务必先检查缓存。

1. 检查是否有有效的缓存令牌：

node -e "
  const fs = require('fs');
  const p = process.env.HOME + '/.aem/da-token.json';
  if (!fs.existsSync(p)) { console.log('No cache'); process.exit(1); }
  const t = JSON.parse(fs.readFileSync(p));
  console.log('Valid:', t.expires_at > Date.now());
  console.log('Expires:', new Date(t.expires_at).toISOString());
"

2. 如果有效，获取令牌并跳到步骤 5：

DA_TOKEN=$(node -e "const t = require(process.env.HOME + '/.aem/da-token.json'); process.stdout.write(t.access_token);")

3. 如果缺失或已过期，请从 GitHub 安装 da-auth-helper（它未发布到 npm）并刷新令牌：

npm install -g github:adobe-rnd/da-auth-helper
da-auth-helper token

这会打开浏览器以登录 Adobe IMS，并将新令牌写入 ~/.aem/da-token.json。然后按照步骤 2 获取令牌。

选项 B — 已配置 DA MCP

如果 DA MCP 服务可用，请触发身份验证工具以启动 OAuth 流程，并将授权 URL 提供给用户。

选项 C — 手动提供令牌

请用户从浏览器获取 IMS 令牌（例如，从 DA 网络标签页或现有会话中获取）并粘贴。将其存储为 {{DA_TOKEN}}。

---

步骤 5：在 DA 中创建初始内容

创建每个 EDS 网站都必须包含的三个页面。请严格使用以下模板——这些模板已通过 EDS 合规性验证。

选项 A — DA MCP： 使用以下内容调用 DA 创建源工具三次。

选项 B — DA API：

先将每个文件写入临时文件，然后使用 @ 语法发送 POST 请求。使用 -F 'data=...' 内联多行内容会导致 curl 失败（退出码 26）。请显式使用 /usr/bin/curl，以避免子 Shell 中的 PATH 解析问题。

cat > /tmp/nav.html << 'EOF'
<nav content>
EOF
/usr/bin/curl -s -o /dev/null -w "%{http_code}" -X POST "https://admin.da.live/source/{{ORG}}/{{REPO}}/nav.html" \
  -H "Authorization: Bearer {{DA_TOKEN}}" \
  -F "data=@/tmp/nav.html;type=text/html"

对 footer.html 和 index.html 重复此操作。

验证： 每次 POST 后，都应收到 HTTP 201。如果收到 401，说明令牌已过期——请返回步骤 4。

---

nav.html

<main>
  <div>
    <p><a href="/">{{SITE_NAME}}</a></p>
  </div>
  <div>
    <ul>
      <li><a href="/">Home</a></li>
    </ul>
  </div>
  <div></div>
</main>

footer.html

<main>
  <div>
    <p>© 2024 {{SITE_NAME}}. All rights reserved.</p>
  </div>
</main>

index.html

<main>
  <div>
    <h1>Welcome to {{SITE_NAME}}</h1>
    <p>Your new site is ready. Start editing this page in DA.</p>
  </div>
</main>

---

步骤 6：触发预览

预览会将 DA 内容拉取到 AEM 交付管道中，并使其可通过 .aem.page 域名访问。

来自 DA 的内容在预览请求中需要 Bearer 令牌——即使是公开仓库也一样。请显式使用 /usr/bin/curl。

/usr/bin/curl -s -o /dev/null -w "%{http_code}" -X POST "https://admin.hlx.page/preview/{{ORG}}/{{REPO}}/main/nav" \
  -H "Authorization: Bearer {{DA_TOKEN}}"
/usr/bin/curl -s -o /dev/null -w "%{http_code}" -X POST "https://admin.hlx.page/preview/{{ORG}}/{{REPO}}/main/footer" \
  -H "Authorization: Bearer {{DA_TOKEN}}"
/usr/bin/curl -s -o /dev/null -w "%{http_code}" -X POST "https://admin.hlx.page/preview/{{ORG}}/{{REPO}}/main/" \
  -H "Authorization: Bearer {{DA_TOKEN}}"

成功： 每个请求都应返回 HTTP 200 或 201。现在，首页已上线，可通过以下地址访问：

https://main--{{REPO}}--{{ORG}}.aem.page/

---

步骤 7：确认并交接

告知用户：

您的网站已就绪！

• 预览： https://main--{{REPO}}--{{ORG}}.aem.page/
• 在 DA 中浏览内容： https://da.live/#/{{ORG}}/{{REPO}}/
• 编辑首页： https://da.live/edit#/{{ORG}}/{{REPO}}/index
• 编辑导航栏： https://da.live/edit#/{{ORG}}/{{REPO}}/nav
• 编辑页脚： https://da.live/edit#/{{ORG}}/{{REPO}}/footer
• GitHub 仓库： https://github.com/{{ORG}}/{{REPO}}

若要开始本地开发：

git clone https://github.com/{{ORG}}/{{REPO}}.git
cd {{REPO}}
npm install
aem up

接下来您想做什么——添加更多页面、自定义区块，还是设置自定义域名？

---

故障排查

现象	可能原因	解决方法
第 2 步返回 422	仓库名称已存在	请用户换一个名称
第 3 步验证返回 404	未安装 aem-code-sync	重新发送安装 URL
第 4 步缓存的令牌缺失或已过期	此机器上没有之前的 DA 会话	从 GitHub 安装 da-auth-helper（npm install -g github:adobe-rnd/da-auth-helper），然后运行 da-auth-helper token
第 5 步 curl 以代码 26 退出	-F 标记中内联了多行内容	将内容写入临时文件，并使用 @/tmp/file.html 语法
第 5 步返回 401	IMS 令牌已过期或缺失	检查 ~/.aem/da-token.json 中的过期时间；请用户提供新的令牌
第 5 步返回 403	令牌没有此组织/仓库的权限	确认用户在 DA 中对 {{ORG}}/{{REPO}} 具有写入权限
第 6 步返回 401	从 DA 获取的内容在预览时需要身份验证	在预览请求中添加 -H "Authorization: Bearer {{DA_TOKEN}}"
第 6 步返回 404	aem-code-sync 未正确安装	验证第 3 步，然后重试
脚本中出现 curl: command not found	子 Shell 中未解析 PATH	显式使用 /usr/bin/curl
预览 URL 显示空白页面	未预览 nav 或 index	对失败的路径重新运行第 6 步

---

参考

• 脚手架：https://github.com/adobe/aem-boilerplate
• aem-code-sync 应用：https://github.com/apps/aem-code-sync
• DA 文档：https://da.live/docs
• DA Admin API：https://opensource.adobe.com/da-admin/
• DA Auth（IMS 令牌助手）：https://github.com/adobe-rnd/da-auth-helper
• AEM Admin API：https://www.aem.live/docs/admin.html
• 完整入门指南：https://www.aem.live/developer/create-site.md

DA URL 模式

• 浏览文件夹：https://da.live/#/{{org}}/{{repo}}{{folder-path}}
• 编辑 HTML 文档：https://da.live/edit#/{{org}}/{{repo}}{{path-without-extension}}
• 编辑 JSON/表格：https://da.live/sheet#/{{org}}/{{repo}}{{path-without-extension}}