Experience现代化代理的提示指南 prompting-guide

迁移遵循七步工作流程：

1. 代理将擦除源页面。
2. 它标识节结构。
3. 它执行创作分析。
4. 它将内容映射到块变体。
5. 它会生成Markdown。
6. 那个创造进口基础设施。
7. 预览结果。

代理使用两级层次结构分析页面：

• 首先，它确定截面边界（背景变化、间距偏移）
• 然后，它标识每个部分中的内容序列。

创作分析遵循David的模型。

• 对于每个内容序列，它首先会检查“作者能否通过正常键入方式创建内容？”
• 默认内容（标题、段落、列表、内嵌图像）优先于块。

在创建新块之前，代理会尝试重用存储库块库中的现有块。

• 当内容无法映射到现有块时，它会创建新的块变体。
• 您可以提示进行更改、请求新变体或以交互方式调整映射。

块变体使用元数据进行跟踪。

• 在迁移多个页面时，代理会先加载现有的自定义变体，并在样式匹配时重用这些变体（根据目的、颜色、排版、间距、布局设置，相似性阈值为70%）。

页眉、导航和页脚将从页面迁移中排除。 这些由专门的技能处理。

每次迁移都会创建导入基础结构（页面模板、块解析器、转换器），以供将来批量导入。

• 这包括页面模板（区域结构）、转换器（站点范围DOM清理）和解析器(特定于块的HTML到表转换)。

• 它不会从头开始推断模板。

• 不支持在单个运行中混合使用模板。

此提示通常会在页面迁移的第一步自动调用。

如果内容存在于DOM中，则也会捕获通过CSS隐藏的内容。

延迟加载的图像和客户端渲染的内容可通过在headless Chromium中滚动页面并允许脚本执行来处理。

为了兼容，WebP/AVIF/SVG图像已转换为PNG。

元数据包括标题、描述、开放图形标签、JSON-LD结构化数据、规范URL。

DOM中的图像是固定的。

• background-image转换为img。
• 图片元素已展开
• srcset已解析为src
• 相对URL将转换为绝对URL
• 要的内联SVG将转换为img文件。

生成经过清理的文档路径（小写字母无.html扩展名）。

产出如下：

• screenshot.png
• cleaned.html （无脚本/样式）
• metadata.json
• 具有本地副本的images/文件夹

用户可以询问有关屏幕快照维度的信息，并请求特定设备大小（移动设备、桌面）来进行内容提取。

在多个断点提取内容会增加处理时间。

设计迁移分为两个阶段：

1. 阶段1（站点范围）将以下内容提取到styles/styles.css：

   • 全局调色板和主题色
   • 排版系统（字体、大小、粗细）
   • 间距系统（填充、边距、间隙）
   • 截面背景（浅、深、彩色）
   • 基本组件样式（按钮、链接、图像）
   • 输出至

2. 阶段2迁移单个块样式并在/blocks/{name}/{name}.css中创建块特定的CSS。

块样式（第2阶段）要求首先完成站点范围的设计（第1阶段）。

• 全局设计系统提供阻止引用的CSS自定义属性。

预计时间：

• 阶段1:5-10分钟
• 阶段2:10-15分钟

模棱两可的请求默认完成迁移（两个阶段）。

块批评将迁移的块与其原始源进行比较，并反复应用CSS修复，直到达到85%的视觉相似性或完成三次迭代。

该技能要求块首先由页面迁移创建。

块批评遵循六个步骤的工作流程：

1. 它使用XPath选择器从源页面捕获原始块。
2. 它会初始化批评会话。
3. 它会检查原始块(屏幕快照、样式、HTML)。
4. 它会检查迁移的块。
5. 它会比较元素并生成与CSS修复的相似性分数。
6. 它会应用修复并重新检查，直到达到85%的目标。

每个迭代都会显示一个包含所有差异的完整评估报告，应用所有CSS修复（按视觉影响划分优先级），在预览中验证，重新检查并显示改进量度。

在设计迁移完成后使用块批注。

页面批评在原始页面和迁移页面之间执行全页可视化比较，不断迭代，直到达到85%的相似性目标或完成三次迭代。

页面评论包含五个步骤的工作流程：

1. 它会初始化一个批评会话。
2. 它检查原始页面上的所有元素。
3. 它检查已迁移页面上的所有元素。
4. 它会比较并生成与优先级排列的CSS修复的相似性得分。
5. 它会应用修复并重新检查，直到达到85%的目标。

页面评论需要源页面URL和迁移的路径（例如，"/about"）作为输入。

在验证总体页面保真度或同时验证多个块时使用页面批次。

使用块评论对特定组件进行重点验证。

建议使用以下工作流程：

1. 迁移页面。
2. 应用设计。
3. 对关键块运行块评论
4. 运行页面批评以进行完全验证。

此技能每次迁移一个块，而不是整个页面或完整的Figma文件。

为获得最佳结果：

• 选择要在Figma中迁移的特定块，并复制其链接（带node-id）或名称。
• 在URL中提供node-id参数以定位确切的块。

运行此技能时，将在托管环境中自动执行以下步骤：

1. 块结构发现 — 代理读取Figma节点以了解层和组件。
2. 全局样式提取 — 代理将颜色、排版规则和间距作为CSS自定义属性（设计令牌）提取到styles/styles.css中。
3. 块特定的样式创建 — 代理会创建特定于正在迁移的块的其他CSS自定义属性。
4. 映射到现有块 — 代理识别项目块库中最接近的匹配块并创建自定义变体。
5. CSS生成 — 代理写入引用提取的CSS自定义属性的样式，以确保设计的一致性。
6. 资源下载 — 代理将图像和图标从Figma保存到托管环境的工作区。
7. Edge Delivery Services内容生成 — 代理将按照EDS块结构创建Markdown文件
8. 输出验证 — 代理预览结果，并对原始的Figma设计执行视觉比较。

该技能首先读取元数据（步骤1）以了解结构，然后提取详细的设计上下文（步骤2-5）。

• 这种分阶段的方法可以防止大型或复杂的Figma文件出现问题。

这项技能采取的是风格优先的方法。

• 在写入任何CSS之前，所有样式都会提取为CSS自定义属性（设计令牌）。
• 这可确保迁移的块与您的设计系统保持一致。

该提示符需要Figma URL（包含fileKey和可选的node-id）或Figma文件键直接作为输入。

Edge Delivery Services导航强制实施三部分结构（由header.js强制）：

1. 品牌（第1部分）：徽标和主要品牌链接
2. 节（节2）：带有可选下拉菜单的主导航菜单
3. 工具（第3部分）：实用工具链接（订阅、登录、购物车）

导航内容位于根目录的nav.md中。

分区由(---)个标记分隔。

包含嵌套列表的粗体项目(**Text**)将创建下拉列表。

由于文档创作的自动换行行为，导航中的链接可能会呈现为按钮。

• 标头块包含从导航链接中删除按钮类的代码。

代理遵循内容驱动开发(CDD)，这是所有Edge Delivery Services开发的强制过程。

• 在编写代码之前，它将询问内容模型和测试内容。

CDD的理念是，作者需要先于开发人员的需要。

• 内容模型必须对作者来说是直观的，即使这意味着要更复杂的修饰代码。

创建测试内容首先提供：

• 即时测试功能
• PSI检查的PR验证链接
• 作者的动态文档
• 发现代码优先方法缺失的边缘案例

代理将在实现之前搜索块集合和块参与方中的类似块，以查找模式和可重用的代码。

仅对于简单的仅CSS调整，跳过CDD（但仍标识测试内容以进行验证）。

Edge Delivery Services有四种标准模型类型：

• 独立：​不同的可视化/叙述元素（主页、块引用）
  • 具有块内容的单个表
• 收藏集：​重复半结构化内容（卡片、轮播）
  • 具有重复行模式的表
• 配置： API驱动的内容或显示配置控件的动态内容（博客列表、搜索结果）
  • 具有键值配置行的表。
• 自动阻止：​作者创建为节/默认内容的复杂结构，然后进行转换(制表符、YouTube嵌入)

每行限制为4个单元格。

• 将相关元素分组到单元格中。

与配置单元格相比，首选块变体以体现样式差异。

遵循Postel定律：对输入结构持灵活态度。

• 无论内容位于一个单元格中、在两个单元格之间拆分还是位于单独的行中，主页块都应该正常工作。

这项技能通常在块创建期间由内容驱动开发自动调用。

块收藏集由Adobe维护和审查，以获得最佳实践、卓越的内容建模、高性能和可访问性。

• 仅限于常见需要的块。 从这里开始。

阻止群是社区驱动型的，它提供更广泛的类型，包括实验方法。

• 它还包括sidekick插件、构建工具(webpack、vite、sass)和集成。
• 在块集合没有您需要的特性时使用。

在搜索时考虑替代名称

• 常见问题解答=折叠
• 图库=轮播/幻灯片放映
• 导航=菜单/标题

阻止交易方仅返回已批准/策划的条目。

测试遵循“价值与成本”的理念，即当测试的价值超过成本时，您可以创建和维护测试。

• 守护程序测试（单元测试）用于逻辑密集型实用程序、数据处理、API集成。 这些方法快速、易于维护，并捕获重用代码中的回归。
• 一次性测试（浏览器测试）用于DOM转换和可视化验证。 使用验证实施，捕获PR审核的屏幕快照，然后放弃。

一次性测试在test/tmp/中进行，在drafts/tmp/中测试内容（均已授予）。

在打开PR之前，请确保：

• 现有测试通过
• 单元测试是针对新逻辑编写的
• 浏览器验证已完成
• 测试所有变体
• 已验证响应式行为
• 斜纹刀路

常见问题具有已知模式：

• 图像显示“关于:error”：块JS中通常缺少createOptimizedPicture调用，或者在DOM重构之前调用
• 块未呈现：检查Markdown中的块名称格式并验证该块在.js中同时具有.css和blocks/文件。
• CSS未加载：检查文件路径，验证CSS文件存在，并在浏览器中检查“网络”选项卡。
• 更改未出现：代码同步需要3-5秒。 尝试硬刷新(Ctrl+Shift+R)。

代理程序会系统地检查每个层：

1. Source文件
2. 已渲染输出
3. 块代码
4. 浏览器控制台

该代理能够在http://localhost:3000检查本地预览。