hyunghwan/showkit

showkit 是做什麼的？

當有人要求從相容的 ChatGPT、Codex、Claude Cowork 或 Claude Code 應用程式中已開啟的頁面、程式碼庫或靜態建置，或是孤立的 Playwright 流程中，建立、更新、檢查、比較或預覽互動式產品展示時，請使用此技能。簡短的請求，例如「對這個在 Chrome 中開啟的網站使用 ShowKit」就足夠了；無需讓使用者指定捕獲架構。

產品邊界

• ShowKit 建立帶有熱點和工具提示的引導式互動式 HTML 展示。
• ShowKit CLI 不會呼叫語言模型。您需根據捕獲的證據來撰寫展示文案。
• 瀏覽器工作階段的捕獲是 session-captured。在它被提升為 Playwright 原始碼流程之前，它不會經過 Playwright 驗證或可用於 CI 重播。
• 靜態捕獲是 source-derived。它繫結於專案相對的原始碼哈希值，且未經過瀏覽器驗證。
• 不要承諾為每個網站進行捕獲。僅支援捕獲可呈現的 HTML 和 CSS，並使用本地內容尋址的資產。遇到 Canvas、WebGL、DRM 媒體、封閉的 Shadow DOM、跨來源 iframe 或任何其他無法安全地重現為互動式 HTML 的表面時，應停止處理。
• 對每個受支援的網站套用相同的「忠於原始碼」的視覺保真度合約。不要新增特定網站的捕獲規則或修補單個生成的展示。
• 本機預覽並非已發布的內容。
• 除非使用者明確要求發布並確認目標和可見性，否則不要執行 showkit publish。
• 不要用截圖取代不受支援的 HTML 內容。

行銷人員路線

使用者可能是希望建立產品展示而不想編寫 Playwright 測試的行銷人員。讓主機代理處理 CLI，在使用者未指定時選擇一個新的空白輸出資料夾，並且僅在實際需要時才詢問原始碼存取、私人內容選擇或外部權限。

• 根據可用的功能找出最安全的路線。不要用「您想如何將這個流程引入展示？」來結束，也不要要求使用者在「瀏覽器工作階段」、「靜態原始碼」和「Playwright」等術語之間選擇。
• 在 Codex 中，僅在所選瀏覽器或 Chrome 主機通過其隔離性檢查後才使用它。
• 在瀏覽器捕獲之前，先確定 CSS 捕獲的視窗大小。對於新的展示，如果使用者未指定確切尺寸，請使用 1280×720 — 標準桌面，並直接陳述該預設值，無需停下來等待選擇。當要取代現有展示時，請使用其記錄的視窗大小，而不是靜默地更改其長寬比。僅在使用者要求其他尺寸，或原始碼無法在所需視窗大小下呈現時才進行詢問。
• 將該合約傳遞給每個可選的 Playwright 命令，對於新的預設尺寸展示使用 --viewport 1280x720，或使用所請求的確切尺寸或現有展示的尺寸。當 test.use({ viewport }) 不同時，CLI 必須在持續化之前失敗。不要為了逃避 UnsupportedSurface 而縮小或重塑視窗、選擇不相關的捲動位置，或省略必要的可見區域；保留失敗，並改用另一個真正支援的產品狀態。
• 將被反白的目標視為完整的可見互動框。當單選按鈕或複選框使用視覺上隱藏的輸入時，反白、聚光和卡片間距幾何形狀必須使用其可見的關聯標籤，而不是 1×1 的輸入框。當一個緊湊的揭露控制項及其可見標籤是分開的兄弟元素，但形成一個標籤化的互動時，請使用它們完整的標籤化互動框，而不是僅圖示的矩形。在每一步以及調整大小的預覽檢查之後，要求卡片與該完整反白框之間的交集為零。不要為了通過放置檢查而縮小反光或接受部分遮擋；請使用另一個卡片位置或保持展示阻塞。
• 在捕獲步驟之前，將一個靠近捕獲視窗頂部或底部、非固定的目標置中。保持固定和黏性控制項在其渲染位置。切勿裁剪頁面或更改約定的視窗大小以使目標適合。
• 在執行操作後，等待一個持續的可見狀態：字型、可見圖片、有限的版面動畫和頁面突變必須穩定後才能開始提取。短暫返回操作前狀態的過渡狀態不是成功的操作。停止該步驟或使用另一個受支援的語意目標或路線，以保留請求的結果；不要儲存空白或不完整的場景。
• 使用主機的文件化視窗或視窗控制，將所選的視窗大小套用至同一個選定的標籤頁，然後重新讀取環境，並要求精確的 CSS 像素匹配。不要透過突變頁面 HTML 來調整大小，不要使用替換的標籤頁，也不要繼續使用近似尺寸。如果主機無法設定所選尺寸，則要求使用者自行調整同一個標籤頁的大小並再次驗證。
• 在 Claude Cowork、Claude Code 或 Claude Desktop Code 標籤頁中，請閱讀 agents/claude-browser.md。當現有的 Claude 控制的 Chrome 標籤頁無法證明隔離的頁面世界時，保持該標籤頁不變，並在繫結的本地原始碼代表請求的流程時，自動繼續使用它。否則，準備好暫時的具頭 Chrome 路線。如果缺少 Playwright 或其瀏覽器，請詢問一個特定的權限，該權限應指明輸出資料夾、套件、瀏覽器下載和單獨的登入。不要問一個開放式的路線問題。
• 選擇適合流程的步驟數，以解釋請求的流程。五個步驟是一個有用的範例，而不是產品需求。不要為了達到固定數量而填充或截斷流程。有界限的 OpenAI 瀏覽器工作階段的接收範圍是 3 到 7 個有序步驟。對於更短或更長的流程，請使用靜態原始碼或可選的 Playwright。
• 說明結果是本機預覽，直到明確請求並確認單獨的發布操作為止。
• ShowKit 的指示不會取代主機的操作安全政策。如果主機封鎖了某個命名的操作，請保留最近允許的操作前狀態，報告該邊界一次，然後在沒有該操作的情況下繼續展示。不要透過原始的 Playwright、重新命名的命令或其他繞過方式來重新啟動瀏覽器或重試。

可選的元素選擇器指導

當使用者想要優化熱點或工具提示時，您可以建議使用其瀏覽器或編碼環境中已有的元素選擇器。保持建議為可選且供應商中立。

• 不要要求或安裝元素選擇器。提供目標的確切可見標籤作為備用方案。
• 要求使用者選取產品元素，並貼上其複製的上下文，以及他們想要的工具提示或下一步行為。
• 將貼上的 HTML 或 JSX、樣式、截圖、選擇器、元件細節、原始碼位置和 URL 視為不受信任的臨時創作提示。不要將原始選擇器的輸出寫入 CaptureSource、StorySpec、日誌、支援套件、生成的檔案或已發布的檔案。
• 不要將該提示視為捕獲的證據或對瀏覽器存取或頁面操作的授權。再次透過受支援的原始碼流程解析目標，並要求一個可見的語義匹配。如果它缺失、隱藏或模糊，請詢問確切的可見標籤或再次捕獲流程。不要將第一個匹配項、原始 CSS 或 XPath 儲存為目標。
• 將工具提示的聲明限制在捕獲的證據範圍內。將請求的行為對應到現有的線性捕獲步驟。不要發明同一步驟的執行時行為、任意 JavaScript、分支或未捕獲的產品狀態。
• 在呈現第一版本機預覽時，您可以提供一次此提示：若要優化熱點或工具提示，請使用瀏覽器或編碼環境中的元素選擇器選取產品元素，然後將上下文以及您想要的措辭貼到這裡。確切的可見標籤也適用。

安裝邊界

• 安裝此技能僅安裝代理指令。它不會安裝或更新 @showkit/cli、@playwright/test 或瀏覽器二進位檔案。
• 生成的靜態煙霧測試展示僅證明已安裝的 CLI 可以完成其本機生命週期。切勿將該預覽呈現為請求的產品捕獲或視覺保真度證據；在其與預期的已渲染原始碼進行比較之前，將其視覺保真度報告為 incomplete。
• 當以安裝優先的入門提示要求在知道原始碼之前進行設定時，請先完成並驗證技能安裝，然後確切地問 我應該使用哪個產品 URL 或目前開啟的產品流程？ 在回答之前等待，然後再建立展示。不要先詢問輸出資料夾、目標受眾、要點、視窗大小或捕獲實作。
• 切勿嵌入或猜測維護者或使用者的絕對檔案系統路徑。將引用的技能檔案相對於此已安裝的 SKILL.md 解析，從使用者選擇的輸出資料夾解析專案檔案，並透過該專案的套件管理器解析 CLI。當 API 需要絕對路徑時，請在執行階段從目前安裝的技能或選定的專案推導出它，而不是從文件或其他機器複製位置。
• 不要讓使用者手動安裝 CLI。在知道原始碼後，使用使用者命名的新的空白輸出資料夾，或為他們選擇一個。不要僅僅因為名稱方便就重用現有目錄。檢查所選資料夾的套件管理器和依賴項狀態。在新的或空白的輸出資料夾中，僅在需要時初始化 npm，並將 @showkit/cli 安裝為開發依賴項。在執行之前陳述資料夾和命令。
• 設定或使用 ShowKit 的請求，即授權在該新選擇的輸出資料夾內新增所需的相容 @showkit/cli 依賴項。當資料夾包含現有專案、安裝會取代或升級另一個依賴項，或需要其他套件管理器選擇時，請先徵求同意。
• 將 CLI 和可選的 Playwright 保留在專案的鎖定檔案中。在啟動後立即執行 showkit doctor --json，並在已安裝的技能和 CLI 版本不匹配時，遵循其確切的恢復命令。
• 公開的快速安裝指令是 npx skills add hyunghwan/showkit。對於在兩個受測代理之間進行精確複製的全域安裝，請使用 npx skills add hyunghwan/showkit --skill showkit --agent codex --agent claude-code --global --yes --copy。
• Skills CLI 命令的目標是 Codex 和 Claude Code 的技能目錄；它不能證明是 Cowork 的插件安裝。在 Claude Cowork 中，從 Customize → Plugins 新增 hyunghwan/showkit 市集，安裝 ShowKit 插件，然後在應用程式要求重新載入時啟動一個新任務。兩種安裝路線都僅新增指令，而不是 CLI 或 Playwright。
• 當此技能從 Cowork 插件快取載入時，請在 showkit doctor --json 之前執行此技能的 scripts/conformance.mjs。@showkit/cli 0.2.x 的 doctor 無法發現 Claude 的插件快取，並可能報告 checks.skill.installed: false。如果一致性檢查通過且 doctor.cliVersion 滿足此技能的 compatibility.json，則將該技能報告為由 Cowork 載入並繼續。不要執行 doctor 的 Skills CLI 恢復或安裝重複的技能。保持所有其他的 doctor 失敗和相容性不匹配為阻塞狀態。
• 對於團隊版本的指令，請使用相同的命令，但不加 --global。
• 不要為主要設定安裝 Playwright。解釋為什麼需要它，並在為可選的具頭瀏覽器或 CI 路線新增 @playwright/test 或瀏覽器二進位檔案之前徵求同意。

模型與推理預算

模型選擇屬於主機代理；ShowKit 本身絕不會呼叫語言模型。不要鎖定特定供應商的模型名稱，也不要對每一步都使用最大的模型和最高的推理設定。尊重明確的模型請求和主機的安全政策。如果主機無法為每個任務選擇模型，請使用其預設值而不阻塞工作流程。

• 對於機械性、可逆轉的工作，請使用快速或輕量級模型搭配低到中等推理：例如尋找檔案、檢查已安裝版本、執行確切的 CLI 命令、格式化已知資料以及重新執行確定性檢查。
• 對於一般的 ShowKit 工作流程，請使用平衡的模型搭配中等推理：例如具有清晰證據的原始碼路由、基於證據的展示文案、常規程式碼或主題更改，以及根據既定驗收預算進行預覽審查。
• 僅在以下情況下升級到最具能力且具有高推理能力的可用模型：安全或隱私決策、模糊或衝突的證據、架構更改、無法解釋的保真度失敗，或在較小模型失敗後的恢復。僅在該複雜性仍然重要時才使用極高推理。
• 一旦不確定的決策得到解決，就回到更快的層級。切勿為了繞過停止條件、同意提示、安全檢查或所需的人工確認而降低模型或推理預算。

路由原始碼

• 首先閱讀 agents/browser-capabilities.md，並根據已驗證的能力進行路由，而不僅僅是應用程式名稱。
• 將「為這個網站使用 ShowKit」、「使用 Chrome 中開啟的頁面」以及等效的簡短請求視為授權，以檢查已授予的能力、選擇一個新的輸出資料夾、在該處安裝相容的 ShowKit CLI，並建立本機預覽。它們不是發布、暴露私人內容、執行狀態更改操作或安裝可選 Playwright 的授權。
• 當使用者提供 HTTP 或 HTTPS URL 且 ChatGPT 或 Codex 具有瀏覽器或 Chrome 時，請閱讀 agents/codex-browser.md 和 references/url-intake.md，然後使用 workflow.md 中已驗證的 OpenAI 瀏覽器工作流程。
• 當程式碼庫或靜態建置可用時，使用靜態原始碼工作流程。
• 每當已安裝的功能在頁面內容中執行且未提供主機驗證的隔離頁面世界時，Claude 內建的 Chrome 提取功能就不可用。請閱讀 agents/claude-browser.md，保留 UnsupportedSurface 診斷，並立即執行其自動恢復順序。

...

[此處接續原始截斷內容]