如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
Feb 4, 2026 Apps SDK

開發 ChatGPT 應用程式學到的 15 堂課

我們如何把這些經驗整理成 Codex 技能,讓你開發 ChatGPT 應用程式的速度提升至 10 倍。

作者: Nikolay Rodionov (Co-founder, Alpic)

開發 ChatGPT 應用程式學到的 15 堂課

在 Alpic,我們相信下一代產品與服務會以 AI 優先的互動體驗 為核心。在這樣的介面中,使用者可以與模型協作,不必按照傳統 UI 預先設定的流程一步步操作。

OpenAI 推出 Apps SDK 時,我們立刻開始用它開發應用程式。三個月內,我們為內部團隊以及 B2B 和 B2C 客戶開發了 24 個 ChatGPT 應用程式,涵蓋 旅遊、零售和 SaaS 等領域。

我們很快就發現,開發 ChatGPT 應用程式,和開發傳統網頁或行動應用程式有根本上的差異。在網頁上行之有效的做法,例如等到需要時才擷取資料、由 UI 驅動狀態,或要求使用者明確設定選項,到了智慧體環境中往往行不通,甚至會讓體驗變差。

本文整理了我們在實際開發 ChatGPT 應用程式時學到的 15 堂最重要的課,接著介紹我們如何把這些經驗融入為社群開發的開放原始碼框架 Skybridge 和一項 Codex 技能,幫助開發者大幅加快構思、開發、測試與推出應用程式的速度。

三體問題

傳統網頁應用程式的情況很單純,只需考慮 使用者 和 UI。在 ChatGPT 應用程式中,系統多了第三個角色:模型。

為 ChatGPT 開發應用程式,最難的課題之一就是管理這三者之間的資訊流。假設使用者點選小工具中的「選取」按鈕,畫面會隨之更新。但除非你明確提供這段上下文,主導對話的模型並不會知道畫面有了變化。這時,使用者如果接著問 「可以再詳細介紹這項商品嗎?」,模型根本不知道對方正在看哪項商品。

我們把這種現象稱為 上下文不對稱:三方各自掌握系統的一部分資訊,卻沒有任何一方看得到全貌。要打造好用的 ChatGPT 應用程式,不必時時同步所有資訊,而是要決定該分享 哪些資訊、何時分享,以及 誰需要看到。這些決定會直接影響使用者與智慧體互動時是否順暢。

1. 上下文需要有選擇地分享

起初,我們直覺認為「把所有資訊都分享給每一方就好了」。這成了我們最早犯的錯誤之一。

實際上,對於 ChatGPT 應用程式的同一個狀態,我們經常需要 刻意讓不同部分看到不同的資訊。為什麼?

  • 效能考量: UI 小工具需要的資料往往遠比模型多。以旅遊預訂應用程式為例,小工具可能需要圖片、不同方案的價格,以及預先載入的選項。把這些資料全都傳給模型,會增加 Token 用量、拉長等待時間,也會讓模型受到無關資訊干擾。
  • 邏輯考量: 有些資訊在設計上就必須只讓特定一方知道。我們早期開發的推理遊戲 Murder in the Valleys 就是如此:模型必須知道誰是兇手才能正確扮演角色,但 UI 和使用者都不能知道。在類似 Time’s Up 的猜詞遊戲裡,情況正好相反:UI 會讓使用者看到謎底,模型卻不能知道答案。

我們從中學到的不是「一律同步所有資訊」,而是 明確決定誰需要知道哪些事。我們利用不同的 工具輸出 欄位來落實這項原則:

欄位 用途 哪些角色可以看到
structuredContent 提供給小工具和模型的具型別資料 小工具和模型都可以看到(透過 toolOutput 和 callTool 函式)
_meta 回應的中繼資料 只有小工具可以看到,模型無法看到

例如,在 Time’s Up 遊戲中,我們透過 _meta 欄位,只將謎底傳給小工具,讓模型根據使用者給的提示猜詞。

2. 延遲載入不太適合 AI 應用程式

由於過去做的是網頁開發,我們習慣採用延遲載入:等使用者點選才擷取資料,需要時才載入詳細內容,盡量減少一開始要傳輸的資料量。

在 ChatGPT 中,情況正好相反。呼叫工具需要等待,由於工具在安全沙盒中執行,加上模型需要推理,一次呼叫往往得花上好幾秒。

實作後我們學會了盡量提前載入資料,在第一次工具回應中傳回盡可能多的資料,再透過 window.openai.toolOutput 將資料填入小工具。這樣做幾乎每次都能縮短等待時間,操作起來也更靈敏。

當然,如果小工具能安全地從公開 API 端點擷取資料,而且不需要與模型分享資訊,還是可以直接在小工具內使用傳統的 XHR 呼叫。不過,多數時候我們希望模型能自主呼叫工具,讓使用者透過對話就能繼續操作。

3. 模型需要知道使用者正在看什麼

使用者先操作小工具(例如選取清單中的某項商品),接著在對話中提問,這時會出現一個不易察覺卻很重要的問題。如果模型不知道使用者指的是 UI 的哪個部分,就無法正確回答。

為此,我們使用 window.openai.setWidgetState(state) 來儲存特定的狀態資料。使用者下次與模型互動時,這些資料就會加入模型的上下文。

隨著應用程式越來越複雜,我們發現,要讓模型跟得上使用者的瀏覽動線,就得在許多地方加上 setWidgetState。於是我們改用宣告式寫法來描述 UI 上下文。開發者不必在每次互動時逐一通知模型,只要直接在元件上加上 data-llm 屬性:

<div
  data-llm={
    selectedTab === "details"
      ? "User is viewing product details"
      : "User is viewing reviews"
  }
>
  Product details
</div>

為了讓這套機制在幕後運作,我們開發了一個 Vite 外掛程式,用來擷取這些屬性並自動更新 widgetState。模型會在需要時收到相關的 UI 上下文,開發者不必手動同步每一次互動。

我們為了與社群分享這些經驗而建立了開放原始碼框架。你可以在其中找到這個 Vite 外掛程式,以及本文提到的許多其他做法。

4. 不同互動需要不同的 API

在 ChatGPT 應用程式中,小工具、伺服器和模型之間有多條互動路徑。每條路徑都支援特定類型的互動,彼此無法替代。

開發 ChatGPT 應用程式的一項重要心得,就是要明確梳理這些通訊路徑,並仔細決定每個環節要由哪一種機制負責。

把這些路徑畫出來,大致如下:

小工具、伺服器和模型之間的各種互動路徑圖

以上幾堂課談的是 ChatGPT 應用程式的基礎:如何分享上下文、如何讓模型掌握畫面上的狀態,以及各種互動如何在系統中傳遞。接下來,我們看看這些基礎會如何影響 UI 設計。

為 AI 重新設計 UI

ChatGPT 應用程式提供了全新的互動環境。我們很快就學會放下過去對 UI 的既定想法,充分運用這個環境的新能力。本節分享為了設計出好用的應用程式,我們需要建立哪些介面設計觀念,又有哪些習慣得改掉。

5. UI 必須適應多種顯示模式及其限制

ChatGPT 應用程式沒有固定的版面配置。同一個小工具可以用三種模式顯示,取決於呼叫它的方式與時機。

應用程式可以 內嵌 在對話中,也能以 子母畫面(PiP) 浮在對話上方,需要更多空間時則可以切換為 全螢幕。子母畫面和全螢幕模式能呈現更豐富的介面,但畫面上也會出現小工具無法控制的覆疊元素。設計時務必考量各裝置的安全顯示區域,例如在行動裝置上為常駐的關閉按鈕預留空間,才能避免內容遭到裁切,讓操作更順手。

累積一段時間的經驗後,我們整理出各種顯示模式的特性與適用時機:

顯示方式 適用時機
內嵌 預設顯示模式。小工具會留在對話記錄中。 適合快速操作。
全螢幕 小工具佔滿整個螢幕,對話輸入列位於底部。 適合介面複雜、需要較大空間的小工具,例如地圖。
子母畫面 尺寸與內嵌模式相同,但小工具會一直浮在對話上方。 適合回應產生後,使用者在後續對話中仍會用到的小工具。

6. 嵌入既有介面時,UI 的一致性格外重要

剛開始時,我們拿不準 ChatGPT 應用程式的視覺設計可以有多少自由度。使用者第一次接觸這類介面,操作時仍應該有熟悉感。我們開發的各個應用程式之間,以及它們與周圍的 ChatGPT 介面之間,都需要維持一致。小工具和獨立產品不同,它嵌在既有介面中,視覺上稍有不協調就很顯眼。

幸好,OpenAI Apps SDK UI Kit 提供了明確的設計基準。

這套工具以 Tailwind CSS 為基礎,提供符合 ChatGPT 設計系統的現成元件、圖示和設計權杖。我們因此能加快開發速度,同時讓小工具在視覺上自然融入周圍的介面。即使是為了整合 Mapbox 而自行開發的元件,也能維持一致的外觀。

7. 優先讓使用者用自然語言篩選

傳統儀表板的側邊欄往往擺滿核取方塊和範圍滑桿。在智慧體介面裡,這種設計反而常讓體驗倒退。使用者明明可以用自然語言直接說出需求,例如「找歐洲天氣晴朗、費用低於 200 美元的目的地」,要求他們逐一操作多個 UI 控制項只會讓過程更麻煩。他們應該只要說出需求就好。

因此,我們在大多數應用程式裡採取了「不設篩選器」的做法。與其在側邊欄放上篩選和排序選項,我們直接把工具參數的 可用值清單(LOV) 提供給模型。

如此一來,模型就能直接把使用者的訊息當成輸入,不必「猜」有哪些選項可用。換句話說,它可以將自然語言直接對應到後端 API 要求的參數。使用者說「天氣晴朗」時,模型就知道要用 weather=“sunny” 呼叫工具。

8. 檔案能讓互動更豐富

隨著我們開發的應用程式越來越複雜,我們發現檔案不該只是輔助輸入。在 ChatGPT 應用程式中,檔案可以帶來新的互動方式。使用者不必先填表單或設定篩選條件,可以直接從手邊已有的檔案開始。

例如,在電商應用程式中,使用者可以把商品照片上傳到對話裡,請模型辨識商品,接著直接在小工具中尋找相符的商品或探索其他商品。

要做到這一點,系統兩端都必須能處理檔案。在模型端,工具可以透過 openai/fileParams 直接使用對話中上傳的檔案,讓模型根據圖片或使用者提供的其他素材進行推理。在 UI 端,小工具也能透過 window.openai.uploadFile 和 window.openai.getFileDownloadUrl 直接處理檔案,因此可以在操作流程中請使用者上傳檔案,或產生檔案讓使用者下載並重複使用。

從本機開發到正式上線

當應用程式走出本機開發環境,就需要從不同角度考量安全性、設定與開發工具。第三部分要談的就是這些經驗。

9. CSP 是新的 CORS

基於安全考量,OpenAI 會在雙層巢狀 iframe 中呈現應用程式。內容安全政策(CSP)是 iframe 原生的隔離機制,在這個環境中會嚴格執行。因此,開發者常會碰到「在本機運作正常,上線後卻出錯」的典型問題。

做傳統網頁開發時,政策設得寬鬆一點或許也能正常運作,但使用 Apps SDK 時就必須精確設定。

具體而言,你必須在應用程式的資訊清單中,仔細宣告每種互動允許使用哪些網域:

欄位 用途 範例 常見錯誤
connectDomains API 和 XHR 請求 https://api.weather.com 忘了預備環境和正式環境的 API 網域不同。
resourceDomains 圖片、字型和指令碼 https://cdn.jsdelivr.net 使用 delivr.net 等通用 CDN,卻沒有將其網域加入允許清單。
frameDomains 嵌入 iframe https://www.youtube.com 嵌入 YouTube 影片或 Mapbox 執行個體,卻沒有將其網域加入允許清單。
redirectDomains 開啟時不會出現警告的外部連結 https://app.alpic.ai 漏掉結帳頁面或 OAuth 回呼的網域。

我們從一開始就把 CSP 設定當成開發重點,後來省下了許多在正式環境中除錯的時間。

10. 小工具的幾個旗標就能大幅影響行為

除了 CSP,還有幾個小工具層級的設定,決定小工具、模型和主機環境各自能控制哪些行為。這些旗標很容易被忽略,卻界定了導覽、工具存取與發布的重要限制。

主機與導覽的限制

  • widgetDomain 是提交應用程式時的必填設定。它決定全螢幕模式下「在 <App> 中開啟」按鈕的預設目的地。由於小工具會在 <widgetDomain>.web-sandbox.oaiusercontent.com 下呈現,這項設定也會用於判定允許的來源。我們使用 setOpenInAppUrl,根據上下文將使用者導向適當的路徑。

模型與工具的限制

  • 工具註解 必須符合發布規範。readOnly、destructiveHint 和 openWorldHint 等旗標都必須設定,提交時也會驗證。
  • 工具的可見性 也很重要:凡是不應讓模型呼叫的工具,都必須明確標記為私有。

小工具的執行限制

  • widgetAccessible 控制小工具能否使用 callTool 自行呼叫工具。

這些設定個別看來都很小,合在一起卻決定了應用程式發布後能否正常運作。

加快反覆開發的速度

Apps SDK 持續快速演進,我們也很高興能一路跟著它開發應用程式。為了讓開發流程更順暢、更有效率,我們決定打造自己的開放原始碼框架,並與社群分享。以下幾項經驗,能幫助你避開我們剛開始開發時遇到的問題。

11. 快速反覆開發需要熱重載

我們最先著手改善的問題之一,就是每次修改後要等多久才能看到結果。ChatGPT 應用程式的資源快取有效期限(TTL)很長,資源又是透過 JSON-RPC 轉送,因此無法直接使用 Vite 或 Next.js 等工具提供的標準模組熱重載功能。

我們花了不少時間研究 Vite 的內部機制,然後開發出一個 Vite 外掛程式,讓小工具能直接在 ChatGPT 中即時重新載入。這個外掛程式會攔截送往 MCP 伺服器的資源請求,並將即時更新注入 ChatGPT 的 iframe。在 IDE 中做完修改,就能立刻在 ChatGPT 中看到效果,大幅縮短了取得回饋的時間。

12. 有些測試可以在 ChatGPT 之外完成

直接在 ChatGPT 中測試最可靠,但在開發初期,本機模擬器能讓你更快嘗試不同做法。尤其當你正在調整工具定義,每次變更都需要在 ChatGPT 中重新整理自訂 MCP 伺服器連線時,差異更為明顯。

為了加快初期開發,我們打造了一個輕量的本機模擬器,模擬 ChatGPT 主機環境,並提供除錯工具和應用程式專用記錄。這讓我們能在幾毫秒內看到調整 React 狀態和版面配置的結果,再到真正的 ChatGPT 環境驗證模型互動與邊界情況。

13. 行動裝置測試需要額外支援

行動裝置測試帶來了另一個挑戰:要在 ChatGPT 中測試,必須透過通道連到本機伺服器,但 Vite 預設使用 localhost,其他裝置無法透過同一個 URL 存取服務。

我們擴充了 Vite 外掛程式,讓它支援在通道連接埠上轉送網域請求。這讓我們得以在 iOS 和 Android 裝置上進行測試,並將行動裝置驗證納入日常開發流程。

14. 熟悉的抽象介面(例如 React Hooks)能加快前端開發

Apps SDK 功能強大,但主要透過較底層的 JavaScript API 提供這些能力。我們長期使用 React,希望能用自己熟悉的概念來開發。

於是我們引入了一些適合 React 的抽象介面,包括 useCallTool、useWidgetState 和 useLocale 等 Hook,也為複雜的資料流提供更進階的狀態管理工具,例如以 Zustand 建構的 createStore。重新採用熟悉的前端模式,減少了重複撰寫的樣板程式碼,也讓小工具的開發流程更接近現代網頁開發。

把開發經驗整理成 Codex 技能

15. 將經驗轉化為可重複使用的工具

相同的模式在多個應用程式中陸續出現後,我們發現,一再摸索相同的做法拖慢了開發速度。為了加快 ChatGPT 應用程式的開發速度,讓開發過程更可預期,我們決定把這些經驗直接融入工具,讓團隊和社群都能使用。

我們因此開發了兩項相輔相成的工具:

  1. Skybridge 框架: 這個開放原始碼 React 框架將本文介紹的許多模式封裝成可重複使用的元件,包括我們開發的 Hook(useCallTool、useToolInfo)、開發工具(HMR 和本機模擬器),以及 data-llm 屬性。
  2. chatgpt-apps-builder Codex 技能: 我們在框架之上打造了一項專用的 Codex 技能,支援應用程式的完整生命週期:
    • 構思: 一起探索如何讓應用程式發揮智慧體的能力,跳脫單純移植網頁版的做法。
    • 產生程式碼: 同時撰寫 React 前端與 MCP 伺服器後端的程式碼,並預先設定適合的 UX 和 UI 模式。
    • 本機測試: 啟動開發伺服器,將本機應用程式連到 ChatGPT,透過熱重載即時驗證每次修改。
    • 品質檢查與發布: 依照 OpenAI 的提交規範逐項檢查,包括驗證 CSP、確認安全顯示區域,以及在正式環境中測試。
    • 部署應用程式: 協助完成應用程式上線及後續改版所需的最後幾個步驟。

若要安裝並使用這項技能,只要執行以下指令:

npx skills add alpic-ai/skybridge

結語

開發 ChatGPT 應用程式,需要重新思考上下文如何傳遞、介面如何運作,以及使用者如何與模型協作。本文的許多經驗,都來自我們熟悉的網頁開發模式與智慧體系統實際運作方式之間的落差。

我們分享這些經驗,並將它們融入開放原始碼框架與 Codex 技能,希望能讓各個團隊少花時間重新摸索相同的問題,把更多時間留給探索這種新互動模式的可能性。最吸引人的 ChatGPT 應用程式不會只是既有產品的移植版本,而會從設計之初就以這種 AI 優先的互動體驗為核心。