在 AEM Edge Delivery Services…

适用于所有 AEM EDS（Franklin/Helix）的代码改动：先确定或创建真实测试内容，再设计内容模型并据此开发和验证。

适用场景

解决思路

1. 第一步：用 TodoWrite 工具创建包含 8 项任务的 todo 列表：启动 dev server、分析与规划、设计内容模型、确定/创建测试内容、实现、lint 与测试、最终验证、提交发布。
2. 第二步：启动 dev server。先用 `curl -s -o /dev/null -w "%{http_code}" http://localhost:3000` 检查是否已在运行（期望 200 或连接错误）；若未运行则执行 `aem up --no-open --forward-browser-logs`（需全局安装 AEM CLI：`npm install -g @adobe/aem-cli`，或用 `npx -y @adobe/aem-cli up --no-open --forward-browser-logs`），尽量后台运行，检查输出中的端口占用、CLI 未安装、配置错误等问题，再次用 curl 验证返回 200。
3. 第三步：分析与规划。调用 analyze-and-plan skill，提供用户任务描述以及截图、设计文件或现有 URL；由其引导任务分析、定义验收标准，并可选分析视觉设计稿，把分析结果写入文件供后续步骤使用。
4. 第四步：设计内容模型（纯 CSS 且不影响内容结构时可跳过）。调用 content-modeling skill，提供第二步的分析结果（内容需求、作者输入）以及 block 名称与用途；由其设计表格结构（行、列、语义化格式）、按最佳实践（每行 4 个单元格、语义化格式）校验，并记录内容模型供作者参考。
5. 第五步：确定或创建测试内容，最终要拿到覆盖所有测试场景的可访问测试内容 URL。
6. 第五步·方案 A（用户已提供测试 URL）：用 `curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/path` 验证 URL 返回 200，记录 URL 后完成。
7. 第五步·方案 B（全新 block，无现有内容）：跳过搜索，直接创建测试内容。方式一（推荐）：请用户在 CMS（Google Drive/SharePoint/DA/Universal Editor）中按第三步的内容模型创建内容并提供 URL，再用 curl 验证返回 200；若需用 DA 以编程方式推送 HTML，先调用 da-auth skill 获取有效的 `DA_TOKEN`，再用 DA Admin API（`POST https://admin.da.live/source/{org}/{repo}/{path}`）推送内容并触发预览。方式二（临时本地 HTML）：在 `drafts/tmp/{block-name}.plain.html` 创建 HTML 文件，按第三步内容模型组织结构，参考 references/html-structure.md 的本地 HTML 格式指南，用 `aem up --html-folder drafts --no-open --forward-browser-logs` 重启 dev server，再用 curl 验证 `http://localhost:3000/drafts/tmp/{block-name}` 返回 200；注意 PR 前用户仍必须在 CMS 中创建内容以生成预览链接。
8. 第五步·方案 C（已有 block 的修改/修复/样式）：先调用 find-test-content skill（提供 block 名称、可选 dev server URL，默认 localhost:3000），由其搜索包含该 block 的现有内容页并自动检测报告所有变体（URL、实例数、变体信息）；若内容充足则记录 URL 并用 curl 验证返回 200；若内容不足或缺失，则按方案 B 的方式补充创建测试内容并验证。
9. 第六步：实现。调用 building-blocks skill，提供第三步的内容模型（如适用）、第四步的测试内容 URL、第二步的分析/需求以及改动类型（新 block、修改现有 block、纯 CSS 等）；由其指导实现方式、处理 JavaScript decoration、处理 CSS 样式（移动优先、响应式），并在开发过程中持续在浏览器中迭代测试，确保功能在所有视口（手机、平板、桌面）正常且无控制台错误。
10. 第七步：Lint 与测试。运行 `npm run lint`，若有错误则修复（可用 `npm run lint:fix` 自动修复）并重复直到通过；再运行 `npm test`（单元测试为可选，仅逻辑较重的工具函数需要；浏览器测试由 building-blocks 在第六步调用的 testing-blocks skill 负责）。
11. 第八步：最终验证。阅读第二步创建的分析文档，逐条核对验收标准；在浏览器中加载测试内容 URL，检查手机、平板、桌面视口，确认无控制台错误、无视觉回归；若修改现有 block 则测试现有变体仍正常，若修改核心功能则抽查若干页面。
12. 第九步：提交发布。若不在特性分支则 `git checkout -b block-name`；只暂存实际改动的文件（如 `git add blocks/{block-name}/{block-name}.js blocks/{block-name}/{block-name}.css`），绝不使用 `git add .`；用约定式提交格式提交（如 `git commit -m "feat(block-name): add new block"`），在提交信息中包含相关细节并在 footer 加入 agent 归属（`Co-authored-by: cursor <noreply@cursor.com>`）；执行 `git push origin HEAD`；创建带预览链接的 PR，分支预览 URL 格式为 `https://{branch}--{repo}--{owner}.aem.page/{path}`，PR 描述中必须包含预览链接（用于自动化 PSI 检查），必要时添加多个预览链接（不同变体、边界情况）。
13. 第九步·判断是否需要 draft PR：当只有本地测试内容用于新功能/新变体、测试内容展示了 CMS 中尚不存在的新特性、或需要用户先创建 CMS 内容才能做最终验证时，创建 draft PR（`gh pr create --draft`）；当所有测试内容都已在 CMS 中可预览、或改动只影响现有内容（可用现有 CMS 内容测回归）时，创建普通 PR。
14. 第九步·draft PR 流程：创建 draft PR；包含现有内容的预览链接（如适用，用于回归测试）；在 PR 描述中写明后续步骤——描述本地使用的测试内容及其覆盖场景，建议创建相同/相似内容并预览、把链接加入 PR，步骤要简短可执行；指导用户创建 CMS 内容：在浏览器打开本地测试内容 `http://localhost:3000/drafts/tmp/[test-file]`，右键 AEM Sidekick 扩展，点击 "View document source"，用复制按钮复制文档内容，粘贴到 Word/Google Docs/Document Authoring（Universal Editor 场景下仅作参考，不能直接复制粘贴），预览 CMS 内容；用户把预览 URL 加入 PR 描述并将 PR 标记为 ready for review（或在用户提供信息后由 agent 完成）。
15. 第九步·PR 描述模板：包含 `## Description` 简述改动；若存在 issue 则写 `Fix #<gh-issue-id>`；列出 Test URLs（对每个相关 URL 重复）：`- Before: https://main--{repo}--{owner}.aem.page/{path}` 与 `- After: https://{branch}--{repo}--{owner}.aem.page/{path}`；若仅有本地测试内容（draft PR）则注明该 PR 为 draft、等待创建 CMS 测试内容，并添加 `### Next Steps to Complete PR:` 及相应步骤。
16. 避免反模式：不要在理解内容模型之前就开始写代码；不要在没有看到真实示例的情况下假设内容结构；不要创建开发者友好但作者不友好的内容模型；不要为了省时间而跳过内容创建（后期会花更多时间）。

适用边界 · 注意事项

• 仅做文档修改时
• 不影响作者创作的配置变更时
• 尚不需要做任何代码改动的研究任务时