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. 全域樣式擷取 — 代理程式會將色彩、印刷樣式和間距提取至styles/styles.css，作為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**)會建立下拉式清單。

由於Document Authoring的自動換行行為，導覽中的連結可能會呈現為按鈕。

• 標題區塊包含從導覽連結中移除按鈕類別的程式碼。

代理程式會遵循內容導向開發(CDD)，這是所有Edge Delivery Services開發的強製程式。

• 它會在編寫程式碼之前詢問內容模型和測試內容。

CDD的理念是，作者需要先於開發人員需要提出。

• 內容模型必須讓作者直覺化，即使這意味著更複雜的裝飾程式碼。

建立測試內容會先提供：

• 立即測試功能
• PSI檢查的PR驗證連結
• 作者的生活檔案
• 發現程式碼優先處理遺漏的邊緣案例

在實作之前，代理程式會在區塊集合和區塊關係人中搜尋類似的區塊，以尋找模式和可重複使用的程式碼。

僅針對僅CSS的簡單微調跳過CDD （但仍會識別要驗證的測試內容）。

Edge Delivery Services有四種標準模型型別：

• 獨立：​不同的視覺/敘述元素(hero、blockquote)
  • 含有區塊內容的單一表格
• 集合：​重複半結構化內容（卡片、輪播）
  • 具有重複列樣式的表格
• 設定： API驅動或設定控制項顯示的動態內容（部落格清單、搜尋結果）
  • 含有索引鍵值設定列的表格。
• 自動封鎖：​作者建立為區段/預設內容的複雜結構，然後進行轉換(索引標籤、YouTube內嵌)

每列最多只能有四個儲存格。

• 將相關元素群組至儲存格。

如出現樣式差異，建議使用區塊變體而非設定儲存格。

遵循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檢查本機預覽。