无仓库无 DA 内容时，从零创建 AEM Edge…

当需要新建一个全新的 AEM Edge Delivery 站点、且尚无 GitHub 仓库和 DA 内容时，用这套流程建仓、安装同步应用、初始化 nav/footer/index 并触发预览。

适用场景

解决思路

1. 开始前确认前置条件：GitHub 账号有目标 org 的建仓权限；Adobe IMS 账号可访问 DA（da.live）；`gh` CLI 已认证（`gh auth status`）或已有 `repo` scope 的 GitHub PAT；Node.js 可用于通过 da-auth-helper 管理 DA token。
2. 创建 TodoList 跟踪进度：1 收集输入；2 从模板创建 GitHub 仓库；3 安装 aem-code-sync（人工操作）；4 DA 认证；5 在 DA 创建 nav、footer、index；6 触发预览；7 交付预览 URL 和 DA 链接。
3. 收集输入：向用户询问 GitHub org（如 `my-org`）、项目名/仓库名（小写且仅用连字符，如 `my-site`）、站点名（人类可读，如 `My Site`；未提供则从项目名推导）。全部必填后再继续。存为 `{{ORG}}`、`{{REPO}}`、`{{SITE_NAME}}`。
4. 用 `adobe/aem-boilerplate` 模板创建 GitHub 仓库。优先 Option A（gh CLI，自动处理认证）：先运行 `gh auth status`，未认证则运行 `gh auth login`，然后运行 `gh repo create {{ORG}}/{{REPO}} --template adobe/aem-boilerplate --description "{{SITE_NAME}} — AEM Edge Delivery site" --public`。
5. 如果无 `gh` CLI，用 Option B（GitHub API）：`POST https://api.github.com/repos/adobe/aem-boilerplate/generate`，Header 为 `Authorization: Bearer {{GITHUB_TOKEN}}`、`Content-Type: application/json`，Body 为 `{"owner":"{{ORG}}","name":"{{REPO}}","description":"{{SITE_NAME}} — AEM Edge Delivery site","private":false,"include_all_branches":false}`。Token 从 https://github.com/settings/tokens/new 获取，scope `repo`。成功标志：API HTTP 201 或 CLI exit code 0。仓库地址为 `https://github.com/{{ORG}}/{{REPO}}`。
6. 安装 aem-code-sync（人工操作，不能自动化）：告诉用户打开 https://github.com/apps/aem-code-sync/installations/new；在 Repository access 选 Only select repositories；从列表选择 `{{ORG}}/{{REPO}}`；点 Save；完成后回复 done。等待确认再继续。
7. 验证 aem-code-sync：确认后检查 `https://admin.hlx.page/status/{{ORG}}/{{REPO}}/main/` 是否返回有效 JSON 而不是 404；若是 404，重新发送安装 URL。
8. DA 认证 Option A（首选 da-auth-helper）：先检查缓存 `~/.aem/da-token.json`，不要直接触发新 OAuth。检查有效缓存：`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());"`。
9. 如果缓存有效，捕获 token 并跳到 Step 5：`DA_TOKEN=$(node -e "const t = require(process.env.HOME + '/.aem/da-token.json'); process.stdout.write(t.access_token);")`。
10. 如果缓存缺失或过期：从 GitHub 安装 da-auth-helper（它未发布到 npm）：`npm install -g github:adobe-rnd/da-auth-helper`，然后运行 `da-auth-helper token`。这会打开浏览器进行 Adobe IMS 登录，并把新 token 写入 `~/.aem/da-token.json`；之后按上一步捕获 token。
11. DA 认证 Option B：如果配置了 DA MCP server，调用其认证工具启动 OAuth 流程，并把授权 URL 发给用户。
12. DA 认证 Option C：请用户从浏览器（如 DA network tab 或已有会话）获取 IMS token 并粘贴，存为 `{{DA_TOKEN}}`。
13. 在 DA 创建 EDS 站点必需的三个页面：`nav.html`、`footer.html`、`index.html`。使用下方模板原样创建，它们已预验证符合 EDS。Option A（DA MCP）：用 DA create source tool 调用三次。Option B（DA API）：先把每个文件写入临时文件，再用 `@` 语法 POST；不要用 `-F 'data=...'` 内联多行内容，否则 curl 失败 exit 26；在子 shell 中显式用 `/usr/bin/curl` 避免 PATH 解析问题。示例：`cat > /tmp/nav.html << 'EOF' ... 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，token 已过期，回到 Step 4。
14. 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>`
15. footer.html 模板：`<main> <div> <p>© 2024 {{SITE_NAME}}. All rights reserved.</p> </div> </main>`
16. 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>`
17. 触发预览：预览会把 DA 内容拉入 AEM 交付管线并使其在 `.aem.page` 域可访问。DA 来源内容即使仓库公开，预览请求也要求 Bearer token；显式使用 `/usr/bin/curl`。分别对 nav、footer、根路径执行：`/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/`。
18. 确认并交付：告诉用户站点就绪，给出预览 `https://main--{{REPO}}--{{ORG}}.aem.page/`、DA 浏览 `https://da.live/#/{{ORG}}/{{REPO}}/`、编辑首页 `https://da.live/edit#/{{ORG}}/{{REPO}}/index`、编辑 nav `https://da.live/edit#/{{ORG}}/{{REPO}}/nav`、编辑 footer `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`。询问下一步：加更多页面、定制 block、设置自定义域名。
19. DA URL 模式：浏览文件夹 `https://da.live/#/{{org}}/{{repo}}{{folder-path}}`；编辑 HTML 文档 `https://da.live/edit#/{{org}}/{{repo}}{{path-without-extension}}`；编辑 JSON/sheet `https://da.live/sheet#/{{org}}/{{repo}}{{path-without-extension}}`。
20. 故障排查：Step 2 返回 422 通常因仓库名已存在，让用户换名；Step 3 验证返回 404 通常因 aem-code-sync 未安装，重发安装 URL；Step 4 缓存 token 缺失/过期通常因本机没有 DA 会话，从 GitHub 安装 da-auth-helper（`npm install -g github:adobe-rnd/da-auth-helper`）并运行 `da-auth-helper token`；Step 5 curl 退出码 26 通常因 `-F` 内联多行内容，改为写临时文件并用 `@/tmp/file.html`；Step 5 返回 401 通常因 IMS token 过期或缺失，重新检查 `~/.aem/da-token.json` 过期时间或让用户提供新 token；Step 5 返回 403 通常因 token 对该 org/repo 无权限，确认用户在 DA 中对 `{{ORG}}/{{REPO}}` 有写权限；Step 6 返回 401 因 DA 来源内容预览需要认证，给 preview 请求加 `-H "Authorization: Bearer {{DA_TOKEN}}"`；Step 6 返回 404 因 aem-code-sync 安装不正确，验证 Step 3 后重试；脚本中 `curl: command not found` 因子 shell 未解析 PATH，显式用 `/usr/bin/curl`；预览 URL 空白页因 nav 或 index 未预览，对失败路径重跑 Step 6。
21. 参考：Boilerplate https://github.com/adobe/aem-boilerplate；aem-code-sync app https://github.com/apps/aem-code-sync；DA docs https://da.live/docs；DA Admin API https://opensource.adobe.com/da-admin/；DA Auth https://github.com/adobe-rnd/da-auth-helper；AEM Admin API https://www.aem.live/docs/admin.html；完整 onboarding guide https://www.aem.live/developer/create-site.md。

适用边界 · 注意事项

• 导入或迁移现有页面时不要用，改用 page-import skill。
• 在已存在站点上构建或修改 blocks 时不要用，改用 content-driven-development skill；实现新 block 代码用 building-blocks skill。
• 已有 GitHub 仓库或 DA 内容时不要用此从零创建流程。