開始使用適用於 GitHub Copilot CLI 和 Claude Code 的 Power Pages 外掛程式

GitHub Copilot CLI 及 Claude Code 的 Power Pages 插件提供 AI 輔助的工作流程，用於在 Power Pages 上建立、部署及管理現代 單頁應用程式（SPA） 網站。 與其手動搭建專案架構、撰寫模板 API 程式碼或設定權限，不如用自然語言描述你想要的，外掛就會自動處理實作。

此外掛程式透過對話式技能，支援完整的網站開發生命週期。 從精選的 SPA 範本建立網站，或從頭建立網站骨架，然後自訂網站、設定 Dataverse 資料模型及驗證。 GitHub Copilot CLI 和 Claude Code 都可以透過 /create-site 使用範本建立功能。

先決條件

在開始之前，請確認你擁有所需的軟體和權限。

軟體需求

您也會需要：

• 一個啟用 Power Pages 的 Power Platform 環境。
• 一個 經過認證的 PAC CLI 會話 連接到你的目標環境。 如果你還沒有連線，請執行 pac auth create 。
• Azure CLI 工作階段已登入同一個租用戶。 執行 az login --allow-no-subscriptions 來驗證。

驗證身份：

用指令 pac auth list 確認你已經認證。

pac auth list           # Should show authenticated profile

如果你沒有認證，請執行這個指令：

pac auth create --environment <Instance url>        # Authenticate to Power Platform

安裝外掛

從市集安裝 Power Pages 外掛。 如果你使用 GitHub Copilot CLI，請參閱 Copilot CLI 擴充功能文件 中的相同安裝步驟。 以下指令使用 Claude Code 語法。

快速安裝（建議）

執行安裝程式，設定所有啟用自動更新的插件：

Windows （PowerShell）：

iwr https://raw.githubusercontent.com/microsoft/power-platform-skills/main/scripts/install.js -OutFile install.js; node install.js; del install.js

macOS/Linux/Windows （cmd）：

curl -fsSL https://raw.githubusercontent.com/microsoft/power-platform-skills/main/scripts/install.js | node

安裝程式會自動執行：

• 若尚未安裝 pac CLI，則會進行安裝。
• 偵測可用工具，如 Claude Code 與 GitHub Copilot CLI。
• 註冊插件市集並安裝所有列出的插件。
• 啟用自動更新，讓外掛保持最新。

安裝後，重新啟動 Claude Code 或 GitHub Copilot CLI，即可在代理會話中以斜線指令存取外掛的技能。

從市集安裝

1. 在你的終端機裡開啟 Claude Code。

2. 新增 Microsoft 市集：

   /plugin marketplace add microsoft/power-platform-skills
   

3. 安裝 Power Pages 外掛：

   /plugin install power-pages@power-platform-skills
   

安裝外掛後，請重新啟動 Claude Code 或 GitHub Copilot CLI，以便在代理會話中以斜線指令的方式存取外掛功能。

技能概觀

該外掛提供涵蓋 Power Pages 網站完整生命週期的技能。 在對話中召喚每個技能，無論是用斬擊指令，還是描述你想做的事。

典型工作流程

常見的端到端工作流程如下：

1. /create-site：從精選的 SPA 範本或骨架開始，設計並建置頁面。
2. /deploy-site：上傳到你的 Power Pages 環境。
3. /activate-site：設定公開 URL。
4. /setup-datamodel ：建立 Dataverse 表格。
5. /add-sample-data ：將測試資料填入資料表。
6. /integrate-webapi ：產生 API 用戶端程式碼並設定權限。
7. /create-webroles ：定義存取角色。
8. /setup-auth：新增登入、登出及以角色為基礎的介面。
9. /add-server-logic ：新增安全的伺服器端端點。
10. /add-cloud-flow：整合現有的 Power Automate 流程。
11. /add-seo ：新增搜尋引擎優化。
12. /deploy-site：推送最終變更上線。
13. /security-review ：在進入生產環境前執行端對端的安全審查。
14. /plan-alm：將您的網站部署到測試及生產環境。

建立你的 Power Pages 網站

本導覽涵蓋使用外掛建置 Power Pages 網站的完整生命週期，從支架架構到部署。 每個步驟都描述你說了什麼，以及外掛的回應。

步驟 1：建立你的網站

用自然語言描述你想要的網站：用途、需要哪些頁面，以及任何設計偏好，例如配色、版面風格或字體。 執行 /create-site 或描述你的網站，外掛就能辨識你的意圖。

外掛會檢查最新發布的範本目錄，並建議符合你需求的範本。 你可以預覽匹配的範本、瀏覽所有可用的 SPA 範本，或選擇 從頭開始。

從範本建立網站

使用範本從一個已打包好的網站及其支援的 Dataverse 解決方案開始，而不是從零開始生成每個頁面。 例如，請將此請求輸入 GitHub Copilot CLI 或 Claude Code：

/create-site Create a citizen services site from a Power Pages SPA template.
I need service requests, request tracking, a city service map, and knowledge articles.

這個外掛會引導你完成以下步驟：

1. 開啟一個唯讀的瀏覽器圖庫，包含範本描述、預覽圖片及可用的框架變體。 請在終端機中選取範本和架構，而不是在資源庫中選取。 如果一個範本有多個變體，請從該範本可用的框架中選擇。
2. 詢問在哪裡建立本地專案。 選擇新的目錄或空的現有目錄。
3. 它要求你確認目標的 Power Platform 環境。 它會驗證 PAC CLI 與 Azure CLI 是否使用相同租戶，檢查所需的 Dataverse 語言，並檢查環境是否允許 JavaScript 附件。 如果 .js 附件遭到封鎖，此技能會先徵求您的同意，才會從封鎖的副檔名清單中只移除 js。
4. 它會要求你核准安裝所選範本。 安裝會匯入所需的未受控支援解決方案，將打包的網站程式碼複製到本地目錄，安裝相依性，建置專案，並上傳新的程式碼網站版本。
5. 在有範本種子資料時套用並回報結果。 種子資料錯誤不會阻礙網站建立或啟用。
6. 透過 /activate-site 啟用新網站，系統會要求你選擇子網域並確認啟用作業。 瀏覽器狀態頁面會追蹤安裝進度，並在啟用成功時重新導向線上網站。 DNS 變更傳播期間，網站可能需要幾分鐘才能載入。
7. 會顯示即時網址和本地專案路徑，然後詢問你是否要自訂專案。 在批准變更前，請先檢視擬議的客製化計畫。 本地自訂功能不會自動重新部署；等你準備好發佈時再執行 /deploy-site。

如果目錄無法取得或沒有支援的 SPA 範本，外掛會告訴你，並繼續從零開始建立。 若缺少所需的 Dataverse 語言，範本安裝會在匯入解決方案前停止;你可以從頭開始，也可以取消。 如果解決方案匯入或網站建立失敗，請在選擇重試、從頭開始或停止前，先檢視顯示的錯誤訊息。 早期匯入、部分未受管理的匯入、本地檔案或部分網站上傳可能會保留；切換路徑並不會自動移除這些項目。

從零開始建立一個網站

選擇 從零開始 以使用現有的腳手架工作流程，而非安裝精選範本。 外掛會要求你選擇一個框架（React、Vue、Angular 或 Astro）和專案位置，然後：

1. 根據框架的起始檔案建立專案架構，套用你的網站名稱、顏色和設計代幣。
2. 安裝相依性、啟動開發伺服器，並開啟即時預覽。
3. 它會用相關的圖片來建構你要求的每一頁、元件和路線。
4. 在重要里程碑處建立 git 提交，讓您有內建的復原歷程記錄。

繼續進行第 2 和第 3 步，部署並啟用從零開始建立的網站。

步驟二：部署您的網站

執行 /deploy-site 將你的網站上傳至 Power Pages。 插件：

1. 確認 PAC CLI 已安裝且你的認證會話仍在啟動。
2. 在繼續前，先與你確認目標環境。
3. 執行生產環境建置並上傳編譯輸出。
4. 若不存在部署工件目錄，則會建立一個。

步驟三：啟用您的網站

執行 /activate-site 使網站對外開放。 插件：

1. 根據你的網站名稱建議子網域，並讓你自訂。
2. 透過 Power Platform API 提供網站紀錄。
3. 輪詢直到網站上線，並傳回公用 URL。

此時，你有一個可用的公開網址網站。 剩下的步驟則會加入資料、驗證和 SEO。 跳過任何不適用於你網站的步驟。

步驟四：建立你的資料模型

執行 /setup-datamodel 以建立你網站所需的 Dataverse 表格。 如果你已經有 ER 圖或特定架構，直接提供，不要讓客服分析你的程式碼。

該外掛會產生一個 資料模型架構代理程式，該代理會：

1. 分析您網站的程式碼，判斷頁面和元件需要哪些資料。
2. 查詢 Dataverse 環境中現有的資料表以避免重複。
3. 提出一個包含資料表、欄位、資料型態與關係的資料模型，並以ER圖示方式視覺化。

你審查並批准提案。 插件在你確認之前不會產生任何東西。 核准後，外掛會透過 API 呼叫建立資料表和欄位，並儲存一個清單檔案，步驟 5 和 6 會使用。

步驟 5：新增範例資料（可選）

執行 /add-sample-data 任務，將測試記錄填滿你的資料表。 此步驟需使用第四步的資料模型。

該外掛執行以下動作：

1. 閱讀清單以了解你的表格、欄位和關係。
2. 為每種欄位類型產生符合情境的值，例如真實的電子郵件、合理的日期及格式化的貨幣金額。
3. 依相依順序插入紀錄（父資料表置於子資料表之前），並在批量插入時自動刷新認證權杖。

步驟 6：與 Dataverse Web API 整合

執行 /integrate-webapi 以即時 Dataverse 查詢取代模擬資料。 此步驟需使用第四步的資料模型。

該外掛執行以下動作：

1. 掃描程式碼基底，找出使用模擬資料、預留位置擷取呼叫或硬式編碼陣列的元件。 它會將這些元件對應到你的 Dataverse 資料表。
2. 為每個資料表生成 Web API 整合 代理程式，該代理程式會產生以下內容：
   • 一個共享的 API 客戶端，具備防偽造令牌管理與重試邏輯。
   • TypeScript 實體類型與領域映射器。
   • CRUD 服務層。
   • 框架專用的模式，例如 React 鉤子、Vue 組合檔或 Angular 服務。
3. 會產生一個 權限架構 代理程式，提出表格權限與站點設定。

你審查並批准權限提案。 外掛在你確認之前不會建立任何設定檔。

新增 AI 生成的摘要（可選）

執行 /add-ai-webapi，即可在你的 Web API 整合上疊加生成式 AI 摘要。 此技能將兩個預覽摘要 API 連接到您的記錄細節與清單頁面：

• 搜尋摘要 API：回傳 AI 精簡的搜尋結果摘要，並附有引用。
• 資料摘要 API：傳回 Dataverse 資料表中每筆記錄的摘要或清單層級的深入解析。

此步驟建立在第 4 步的資料模型及第 6 步的 Web API 整合之上。 該外掛執行以下動作：

1. 掃描你的程式碼尋找摘要整合點，並確認目標頁面、表格及使用哪些 API。
2. 將任何缺少的 Web API 前置條件——資料表權限、欄位列表和網頁角色——委派給 /integrate-webapi 和 /create-webroles，確保權限有一個單一的真實來源。
3. 繁衍一個產生具類型摘要服務 () 的 aiSummaryService.ts Agent，並在目標頁面中提供防偽權杖處理、架構特定包裝函式 (React 掛勾、Vue 可組合函式或 Angular 服務) 和固定呼叫位置。
4. 會產生 一個 AI Web API 設定 架構師代理程式，負責建立 Summarization 網站提示與內容限制的設定。

你審查並批准提案。 外掛不會在你確認前產生程式碼或建立設定。

步驟七：建立網頁角色

執行 /create-webroles 以定義使用者存取角色。 插件：

1. 查詢您的環境中現有的 web 角色以避免重複。
2. 產生具有唯一識別碼的角色定義。
3. 強制每個站點最多擁有一個匿名角色和一個認證角色。

步驟八：設定認證

執行 /setup-auth 後可為你的網站新增登入、登出及基於角色的存取控制。 該外掛支援以下身份提供者，且可同時設定一個或多個提供者。

欲了解更多支援提供者的資訊，包括協定與設定考量，請參閱 Power Pages。

插件：

1. 分析你的網站（目的、頁面、受眾），並提出合理的預設方案。 例如，該外掛建議面向客戶的網站使用採開放註冊的 Microsoft Entra 外部 ID，或建議內部入口網站使用採僅限邀請註冊的 Microsoft Entra ID。 你可以接受推薦，或是自己選擇服務提供者。
2. 針對每個提供者，它會引導你完成身份提供者管理中心的所有前置步驟，例如建立租戶、註冊應用程式、建立使用者流程，以及擷取客戶端 ID 和重定向 URI。 外掛會驗證你貼回對話中的每個值，並計算你網站的精確重定向 URI，確保貼在應用程式註冊中的值與網站設定中的值相符。
3. 詢問使用者個人資料資料如何從身分提供者流向 Dataverse 聯絡記錄（宣告對應）、是否每次登入同步或僅首次登入，以及是否透過電子郵件自動連結外部登入與現有聯絡人。
4. 產生驗證服務、類型宣告、角色型授權公用程式 (hasRole、RequireAuth、RequireRole)、可防止 SPA 工作階段無預警過期的工作階段保持運作掛勾，以及與網站版面配置整合的登入/登出 UI 元件。 外掛程式全程採用您的架構模式，例如 React 掛勾、Vue 可組合函式、Angular 服務或 Astro 元件。
5. 當設定多個提供者時，會產生一個以你所選版面配置呈現的 /login 頁面：水平排列、垂直堆疊、主要焦點或分頁。
6. 在 .powerpages-site/site-settings/ 下寫入每個提供者、註冊模式、宣告對應和選用功能的相應網站設定。

當你開啟外掛時，外掛也會配置以下可選功能：

• 條款與條件： /terms 用戶必須在完成登入前接受 SPA 頁面，並附上相應的網站設定與內容片段。
• User 個人頁面：一個 /user-profile SPA 頁面，登入使用者可透過 Power Pages Web API 編輯聯絡資訊。
• 同盟登出：對於共用裝置或受監管案例，當使用者從網站登出時，他們也會在識別提供者處登出。

步驟 9：新增伺服器邏輯

執行 /add-server-logic 以在您的網站新增安全的伺服器端點。 當你的網站需要無法在瀏覽器執行的邏輯時，例如外部 API 呼叫、伺服器端驗證、秘密管理或跨實體資料操作，請使用 Server Logic 。

請用淺顯的語言描述你需要什麼，以及外掛：

1. 會產生一個 Server Logic Architect 代理程式，分析你的使用案例並分類其複雜度。
2. 提出端點設計、安全設定及任何必要的資料表權限供您審查。
3. 核准後，會在 /_api/serverlogics/<name> 生成伺服器端的 JavaScript 端點。
4. 建立具類型的用戶端服務以從您的元件叫用端點。
5. 更新您裝置的元件，使其能呼叫新的服務。
6. 設定端點的網頁角色指派與資料表權限。

你審查並批准提案。 在你確認之前，不會產生任何程式碼。

常見用例：

• 連接外部服務。 呼叫 REST API、Azure Functions 或第三方服務，且不暴露憑證。 （教學：與外部服務互動）
• 執行安全的資料操作。 查詢、更新或刪除 Dataverse 紀錄，並具備一致的伺服器端驗證。 （教學：與 Dataverse 表格互動）
• 執行自訂邏輯。 在資料表間彙整資料、執行業務規則，或在將結果回傳給用戶端前計算衍生值。
• 伺服器端管理秘密資訊。 憑證和 API 金鑰儲存在伺服器端，絕不存在客戶端程式碼。 （教學：與Microsoft Graph及SharePoint互動）

步驟 10：整合雲端流程

執行 /add-cloud-flow，將現有的Power Automate雲端流程整合到你的網站。 這項技能能將您的 Power Pages 網站與您已在 Power Automate 中建立的流程連結起來。 它不會創建新的雲端工作流程。

插件：

1. 將現有的雲端流程註冊於您的網站。
2. 產生用戶端程式碼以從您的頁面觸發流程。
3. 處理非同步工作流程狀態與回調模式。
4. 連結頁面與流程之間的資料交換。

使用 /add-cloud-flow 來處理比伺服器端端點更適合由Power Automate執行的核准工作流程、電子郵件通知、排程工作和事件驅動自動化。

替代方案：使用 /integrate-backend 來規劃完整服務層

如果你不確定哪些功能需要 Web API、伺服器邏輯或雲端流程，建議執行 /integrate-backend 步驟 4 到 10 步驟，而不是手動執行。 此技能作為一種調度者，能夠：

1. 分析你的原型，找出所有需要服務層的功能。
2. 將每個功能分類為正確的方法：標準 CRUD 的 Web API、伺服器端驗證與外部 API 的 Server Logic，或審核工作流程與自動化的雲端流程。
3. 提出包含所有技能、相依性與配置的序列執行計畫。
4. 系統在您核准後，依正確順序編排技能。

計畫是持久的、可恢復且可編輯的。 每一步結束後，先停下來檢視產生的程式碼或測試網站，然後再跑 /integrate-backend 一遍，從中斷的地方繼續。

步驟 11：加入 SEO

執行 /add-seo 以優化您的網站，使其對搜尋引擎更友好。 插件：

1. 從你的架構路由器設定中發現路由。
2. 為所有發現路線產生搜尋引擎指令及網站地圖。
3. 新增中繼標籤：檢視區、字元集、描述、Open Graph、Twitter Card 和最愛圖示參考。

新增當地語系化 (選用)

在 GitHub Copilot CLI 或 Claude Code 中執行 /add-localization，為你的 SPA 介面新增語言。 例如：

/add-localization Add French (fr-FR) and Arabic (ar-SA) to my site.
Preserve the existing default language and add a language selector.

使用 powerpages.config.json 搭配現有的 Power Pages 程式碼網站專案。 此技能目前支援 React、Vue 和 Angular 的執行時語言切換。 Astro 本地化與 Angular 靜態/建置時間本地化暫時無法使用。

插件：

1. 偵測您的架構和現有的當地語系化設定。 你可以新增語言，或修復或重新配置安裝。 新增語言時，會保留現有套件、預設地區設定及非空翻譯。
2. 驗證 BCP-47 格式的語言標籤，如 fr-FR 和 ar-SA，並在需要時確認預設地區設定。 對於新的設定，建議使用符合框架的本地化工具，並允許你選擇代理生成的翻譯或空白翻譯值供手動完成。
3. 開啟一份 HTML 實作計畫供審查。 在外掛安裝套件或更改網站實作檔案之前，先在終端機中核准計畫。
4. 將使用者可見的字串萃取到翻譯資源中，包括導覽、驗證訊息、無障礙標籤及頁面元資料。 它新增了語言選擇器、預設語言備援，以及文件語言和文字方向設定。
5. 驗證本地化資源、建置專案，並檢查語言切換、文字展開，以及瀏覽器中的由左至右與由右至左版面配置。 有阻塞問題的區域在這些問題解決前仍無法使用。
6. 呈現結果供您審查。 獨立運行後，會提供 立即部署 或 暫時跳過的選項。 只有在你選擇時才會進行部署；否則，請稍後執行 /deploy-site。

步驟 12：部署最終站點

如果你完成了任何可選步驟，請再次執行 /deploy-site 以將變更上線。 該外掛會執行生產環境建置，並將網站及所有部署產物（資料表權限、網站設定、網頁角色、伺服器邏輯檔案）上傳到你的 Power Pages 環境。

步驟 13：進行安全審查

在部署至正式環境之前，請執行 /security-review，對您的網站進行端對端安全審查。 該技能協調聚焦的安全技能，並將所有發現整合成單一的 HTML 報告。docs/security-review-<timestamp>.html

外掛會以淺白易懂的方式詢問一個關於您目標的問題，並挑選出相符的一組重點技能：

確認後，外掛會平行執行匹配重點技能，並將發現寫入單一報告：

• /scan-code： 對本地原始碼檔案執行靜態分析（opengrep）及相依掃描（trivy）。 找出程式碼模式、有漏洞的套件、硬式編碼的機密資訊以及授權問題。 如果沒有安裝任何一個工具，技能會提供手動程式碼審查作為備用。
• /scan-site：開始對現場站點進行伺服器端安全掃描，並取得最新報告。 掃描時間取決於站點大小——小型站點幾分鐘內完成，大型站點可能需要數小時。 發現依嚴重程度分組。 需要已部署的網站。
• /manage-headers： 檢查以下設定下的 .powerpages-site/site-settings/HTTP 安全標頭：內容安全政策、X-Frame-Options、CORS、cookie SameSite 及相關設定。 識別缺失或弱值並建議預設值。
• /manage-firewall： 檢查生產站點的網頁應用防火牆（WAF），包括管理規則狀態及自訂規則（IP 區塊、國家區塊、路徑區塊、速率限制）。 僅在支援區域的生產現場提供;該技能能偵測並回報資格問題。
• /audit-permissions：根據網站程式碼和 Dataverse 中繼資料，稽核現有資料表權限。 會出現缺少權限、過於寬鬆的角色、未使用的權限，以及 YAML 架構問題。

合併報告會按章節彙整發現事項、在您的預設瀏覽器中開啟，並提供以淺白易懂文字撰寫的修補指引。 根據對話內容，外掛接著會帶你逐步完成修正——選擇一項發現結果後，外掛便會互動式地啟用相符的專門技能來套用變更。

請驗證你的網站

完成技能後，請確認你的 Power Pages 網站是否正常運作。

1. 請前往Power Pages。
2. 請在 活躍網站 列表中找到您的網站。
3. 使用 預覽 選項在桌面版預覽您的網站。
4. 測試功能。

跨環境推廣你的網站

當你的網站在開發環境中運作良好後，運用應用程式生命週期管理（ALM）技能，將其推廣到測試與生產環境。 該外掛會將您的網站打包為 Power Platform 解決方案，辨識不同環境間的數值，並透過 Power Platform Pipelines 或手動匯出匯入來部署解決方案。

要使用 ALM 技能，你還需要至少一個目標 Power Platform 環境（測試、生產環境或兩者兼有）。 要使用可選的 Azure Key Vault 流程來管理秘密，你也需要在 Azure 訂閱中取得建立 Key Vault 的權限。

規劃部署

執行 /plan-alm 以開始。 /plan-alm 是 ALM 的入門點，並協調其他 ALM 技能，所以通常不會直接執行。 插件：

1. 偵測您專案、解決方案及目標環境的當前狀態。
2. 詢問您的升階策略 (Power Platform 管線或手動匯出與匯入)、目標階段，以及任何要套用的限制式。
3. 會在 docs/alm-plan.html 產生一個視覺化計畫，顯示其打算採取的每一項行動。
4. 在執行任何下游技能前，等待你的批准。

計畫會持續存在磁碟，因此每個下游技能都會從同一個持久化計畫讀取和寫入。 如果某個階段失敗，再跑 /plan-alm 一次，它就會從停止的地方繼續。

撰寫解決方案

執行 /setup-solution ，將你的網站包裝成 Power Platform 解決方案。 插件：

1. 建立發佈者與解決方案，然後新增您的 Power Pages 元件：網站、網頁角色、伺服器邏輯端點、雲端流程註冊及 OAuth 提供者設定。
2. 依敏感度分類每個場址環境，並提出環境變 數 以應不同環境差異值。
3. 提供佈建 Azure Key Vault 並在其中儲存認證類型值（例如連線字串和 API 金鑰）的功能。
4. 當網站已有解決方案時，會以同步模式運行，以調整各項元件而無需創建新解決方案。

你審查並批准提案。 插件在你確認之前不會建立任何設定。

使用 Power Platform Pipelines 進行部署

如果你選擇 Power Platform Pipelines 作為推廣策略，該外掛會執行以下技能：

1. /ensure-pipelines-host 配置或偵測 Power Platform 管線的主機環境。 技能會選擇對租戶來說成本最低的選項：免費平台主機、現有環境中的 Pipelines 應用程式，或自訂主機。
2. /setup-pipeline 在 Dataverse 中註冊管線定義，配置你選擇的階段，並將每個階段綁定到目標環境。
3. /deploy-pipeline 會觸發某個階段的部署、透過 deploymentSettings.json 套用各階段的環境變數覆寫設定，並在部署台帳中追蹤狀態。

如果部署因目標環境已連結至其他 Power Platform 管線主機而失敗，則外掛程式可以執行 /force-link-environment 來重新指派該環境。 此行為需你明確同意，且可撤銷。

使用手動匯出和匯入進行部署

如果你選擇手動路徑，外掛會執行：

1. /export-solution 將解決方案匯出為受管理或非受管理的 ZIP，並在匯出前檢查完整性。
2. /import-solution 將 ZIP 匯入目標環境，先分階段驗證相依性或直接匯入。

啟用並驗證已部署的網站

在目標環境中成功部署後，外掛：

1. 執行 /activate-site 以在目標環境中配置公開 URL。
2. 執行 /test-site 以驗證部署。 該外掛使用瀏覽器來爬取代表性頁面、執行基於角色的存取檢查、驗證 /_api/ 通話，並從端點擷取回應形狀 /_api/serverlogics/ 。 此技能會將結果報告為 PASS、WARNINGS 或 FAIL，並從方案連結至各項檢查的詳細資料。

如果步驟失敗，該插件會執行 /diagnose-deployment。 該技能會將失敗與已知部署錯誤清單（如過時清單、缺少相依性、主機衝突、阻擋 JavaScript 或認證過期）進行比對，並提出具體的解決方案。 這個外掛在未經你同意的情況下絕不會套用修正。

訣竅和最佳做法

以下建議能幫助你在建立 Power Pages 網站時，充分發揮外掛和 AI 編碼代理的效能。

第一次運行時，請注意終端機輸出是否有缺少的工具

外掛提供技能和工作流程，但 AI 程式代理程式——GitHub Copilot CLI 或 Claude Code——會實際執行你的電腦指令。 當你第一次使用這些工具時，請仔細觀察終端輸出。 AI 程式代理在幕後執行指令和腳本，其中一些指令依賴可能未安裝在你電腦上的工具。 如果步驟失敗，終端機輸出通常會顯示找不到哪個工具或指令。

如果你看到像 command not found 或 這樣的 is not recognized錯誤，安裝缺少的工具並重新啟動工作流程。 AI 編碼代理在此工具可用後，會從中斷的地方繼續。

在核准前審查代理人提案

AI 編碼代理會先提出提案，例如資料模型架構師（Data Model Architect）和權限架構師（Permissions Architect）的提案，然後再進行修改。 AI 編碼代理生成的程式碼與設定可能不準確，因此在批准或部署前，務必審查、測試並驗證每一個提案及所有產生的程式碼。

• 資料模型提案：檢查資料表名稱、欄位類型與關聯是否符合您的業務需求。 調整提案比在資料已插入後重新命名欄位要容易得多。
• 權限提案：確認每個角色對每個資料表都有正確的存取權限（建立、讀取、更新、刪除）。 過於寬鬆的資料表權限是常見的安全風險。
• 產生的程式碼：先閱讀產生的程式碼，並在部署前在本地測試網站。 AI 生成的程式碼可能包含錯誤或安全問題。

直接貼上錯誤並附上上下文

當發生失敗時，無論是建置錯誤、部署失敗，或瀏覽器執行時例外，都要複製完整的錯誤輸出。 貼上去，並附上你當時的簡單說明。 你提供越多的背景，修正速度就越快。

範例：建置錯誤

I ran npm run build and got this error. Fix it.

error TS2339: Property 'jobTitle' does not exist on type 'JobPosting'.

  src/components/JobCard.tsx:24:31
    24   <Text>{posting.jobTitle}</Text>
                                 

分享 Web API 錯誤與完整請求 URL

部署後常見的問題是，當欄位未啟用 API 存取時，Power Pages Web API 會發出 403 錯誤。 遇到錯誤時，貼上 完整的 API URL 和 完整的 JSON 錯誤回應。 錯誤訊息會告訴你需要修正哪個表格和欄位，外掛也能幫你更新資料表權限的 YAML 和網站設定。

範例：Web API 未啟用資料行 (403)

I'm getting a 403 error when the documents page loads. Here's the API call and the response. Fix the issue so this API works.

URL:
https://my-site.powerappsportals.com/_api/crd50_documents?$select=crd50_documentid,crd50_name,crd50_documentcategory,crd50_filetype,crd50_filesize,crd50_updateddate,crd50_description,_crd50_propertyid_value

Response:
{
  "error": {
    "code": "90040101",
    "message": "Attribute _crd50_propertyid_value in table crd50_document is not enabled for Web Api.",
    "innererror": {
      "code": "90040101",
      "message": "Attribute _crd50_propertyid_value in table crd50_document is not enabled for Web Api.",
      "type": "AttributePermissionIsMissing"
    }
  }
}

這個錯誤AttributePermissionIsMissing（）表示查詢欄位 _crd50_propertyid_value 存在於 Dataverse 資料表中，但未列在 Web API 的資料表權限設定中。 外掛會透過將缺失欄位加入資料表權限 YAML .powerpages-site/table-permissions/ 並重新部署來解決此錯誤。

要具體說明你想要什麼

模糊的請求只會產生模糊的結果。 告訴外掛你需要什麼，包括版面偏好、資料欄位和行為。

對於視覺問題，請使用截圖

當網站在瀏覽器中看起來不對時，截圖直接貼到對話中，或提供檔案路徑。 視覺語境有助於辨識難以在文字中描述的版面、間距與樣式問題。

The header overlaps the hero section on mobile. Here's a screenshot:

[paste screenshot or provide path to screenshot file]

Fix the header so it doesn't overlap. It should be a fixed header with the content starting below it.

逐步迭代

與其在一個提示中描述整個網站，不如逐步建立。 先從結構和版面開始，然後一個一個地加入功能。 這種方法讓你有機會在每個步驟中檢視並修正方向。

Step 1: /create-site → Get the basic scaffold and layout right
Step 2: "Add a hero section to the home page with a search bar"
Step 3: "Add a job listings page with filter and sort"
Step 4: "Add a job detail page that shows full description"
Step 5: /setup-datamodel → Create tables now that you know the data shape
Step 6: /integrate-webapi → Wire up real data

在批准前請先詢問原因

當你對擬議的變更不確定時，特別是允許權限、資料模型修改或認證設定時，請要求外掛程式說明它計畫要做什麼以及原因，然後再批准。

Before you create the table permissions, explain what access each role will have and why. I want to understand the security implications.

獨立執行技能以從問題中復原

如果某個技能在過程中途失敗，你不需要重新開始。 每個技能獨立運作，可以從中斷的地方接續。 例如，如果 /integrate-webapi 對第三個資料表執行失敗，您可以重新執行，系統會偵測已完成的工作。

/integrate-webapi failed while processing the cr_applications table. Here's the error: [paste error]. Resume the integration from where it stopped.

相關內容

• 在 Power Pages 中建立並部署單頁應用程式
• 設定Power Pages網站的認證
• 伺服器邏輯概觀
• Power Pages Web API 說明
• 資料摘要 API 概述
• Power Pages 使用生成式 AI 搜尋
• PAC CLI 頁面指令參考
• GitHub Copilot CLI
• 克勞德密碼