我用《Raycast從零重寫跨平台》拆了一套AI原生遷移應用playbook
整理版優先睇
Raycast 2.0 跨平台重寫嘅架構決策同執行流程，可以當成 AI 原生遷移嘅教科書案例
呢篇文章係分析 Raycast 由 macOS 專屬重寫成跨平台（X-Ray 項目）嘅技術決策同執行過程。作者係技術博主，引用咗 Raycast 官方技術博客嘅內容，再加自己嘅觀察同實戰經驗，將成個遷移過程提煉成一套「AI 原生遷移」嘅 playbook。文章最想解決嘅問題係：點樣用 AI 工具（例如 Claude Code）有效率咁將舊應用遷移到跨平台，而且唔使拖慢開發速度。整體結論係：跨平台重寫唔一定需要兩倍人馬，但需要刻意將技術棧切成 AI 容易處理嘅四層，並喺原生邊界上死摳細節，先至可以發揮到人機協作嘅最大效益。
作者首先釐清咗「AI 原生遷移」同傳統遷移嘅分別——傳統係人讀代碼再重寫，AI 原生係用 AI 快速出可運行原型（HTML 單文件）反推架構，再逐層落地。佢跟住拆解咗 Raycast 點樣評估 Electron、Tauri 同混合棧，最終揀咗「系統 WebView + 原生殼」嘅路線，並將產品分為四層：Host（原生殼）、Web 前端（React + TypeScript）、Node 業務層、Rust 性能層。呢個架構嘅好處係層與層之間用統一口，各端自動生成類型化客戶端，令 AI 可以專注寫中間層。
然後文章詳細講咗用 Claude Code 遷移嘅五個階段，由先用舊代碼做 Web 試驗田，到原型驗證、定棧劃界、縱向切一條黃金路徑先 ship，再到原生細節清單審查。最後佢提醒咗三個常見陷阱（以為 W…
- AI 原生遷移嘅核心係人機分工重劃：將 AI 擅長嘅 React/Node 層交畀 AI，將原生邊界層留畀人，唔係全自動重寫。
- 四層架構（Host 殼、Web 前端、Node 業務、Rust 性能）係遷移嘅理想目標，層間接口集中定義，方便 AI 協作。
- 傳統遷移係人讀代碼再寫，AI 原生遷移係先用 AI 快速出可運行原型（HTML 單文件）反推架構，再逐層落地。
- 遷移唔好平行重寫所有功能，應該先縱向切一條「黃金路徑」ship 通，再逐步補全；同時要建立原生細節清單做 code review。
- 即刻喺現有應用入面揀一個獨立模塊（如設定頁、Notes），用 WebView + React 做試驗田，驗證 Web 手感，同時用 /goal 設定可驗證終態。
A Technical Deep Dive Into the New Raycast
Raycast 官方技術博客，詳細介紹咗 X-Ray 跨平台重寫嘅架構決策、時間線同技術細節。
AI 原生遷移 Brief 模板
將老應用從老棧遷移到四層架構嘅 AI 協作 brief 模板，包含 Host/Web 前端/Node/Rust 分層同埋 IPC 消息列表輸出要求。可複製到 Claude Code 使用。
傳統遷移 vs AI 原生遷移：核心分別
大部分團隊諗到跨平台遷移，第一反應係：「揾十個工程師，開分支，做兩年。」Raycast 走咗另一條路：由零開始，用 TypeScript、Swift、C#、Rust、Node、React 疊加嘅混合棧，兩年內搞掂 beta。官方自己話，最難嘅地方從來唔係「令應用跑得鬱」，而係「令佢感覺仲係 Raycast」。
- 傳統遷移：先定死技術棧再寫代碼；文檔寫完先開工；人扛全部跨層調試；遷移結束先統一風格。
- AI 原生遷移：用 AI 快速打原型，用原型反推棧是否合理；對話 + 可運行產物（HTML 原型）當「活文檔」；人定邊界，AI 填 React/Node/接口層；遷移過程中就用 Skill / CLAUDE.md 鎖規範。
四層架構：直接抄落你嘅遷移 Brief
Raycast 2.0 最終分咗四層：原生殼（macOS Swift/AppKit，Windows C#/WPF）、Web 前端（React + TypeScript，裝入 WKWebView / WebView2）、Node 常駐進程（數據庫、擴展運行時）、Rust 性能層（文件索引等）。層與層之間透過 統一接口 溝通，各端生成類型化客戶端，呢個設計對於 AI 協作極之重要——你可以叫 Claude Code 淨係改 contracts/ 下嘅 IDL，再自動生成樁代碼。
- 1 路線 A（混合棧）：最適合「要強原生 + 要跨平台」。AI 幫你寫 React 頁面、Node API、類型化 IPC 接口聲明、Rust 獨立模塊；你要自己啃熱鍵、窗口不搶焦點、WebKit 節流。
- 2 路線 B（Electron / Tauri）：最適合「先遷起來、團隊細」。幾乎整個應用邏輯 + UI 都可以交畀 AI，資料多模型最熟；代價係原生控制弱。
- 3 路線 C（純原生雙端）：AI 只能做助手，唔適合做主力。兩套 UI、兩套邏輯，好難維持同步。除非產品極簡，否則唔好選。
我們要把 [老應用名] 從 [老棧] 遷到四層架構：
1. Host 只負責 [列出必須原生的能力]
2. Web 前端負責全部可見 UI，單倉，入口：A/B/C
3. Node 負責 [業務列表]
4. Rust 僅負責 [性能模塊，若無則寫「暫無」]
請先輸出：各層目錄結構 + 層間 IPC 消息列表（JSON schema），不要寫實現。我確認後再分模塊實現。用 Claude Code 遷移嘅五個階段
- 1 階段 0——舊代碼入面做 Web 試驗田：挑一個相對獨立模塊（設定頁、報表頁），用 HTML/React 做一版，嵌進現有殼，驗證 Web 會唔會破壞整體手感。比個 prompt 畀 Claude Code：「喺現有 macOS/Win 應用入面新增一個 WebView 頁面，加載本地 React 構建產物，列出與原生殼嘅 postMessage 接口。」
- 2 階段 1——原型驗證「似唔似自家產品」：用 AI 出 可點擊嘅單文件 HTML 嚟驗證視覺同交互，比寫 Swift 快一個數量級。確認半透明、tooltip 疊喺 WebView 上呢類細節先至 all-in。
- 3 階段 2——定棧 + 劃界：用 AI 做決策備忘錄——畀曬產品需要嘅原生能力（全局熱鍵、系統託盤等），叫佢對比 Electron、Tauri、混合 WebView，從「AI 可維護面積」、「原生控制力」、「內存基線」、「招聘」四維打分，人嚟做最終選擇。
- 4 階段 3——縱向切一條黃金路徑先 ship：揀一條路徑（例如登錄→主列表→詳情→保存），用 /goal 令 Claude Code 跑通 E2E，附帶最小單測；Windows 暫緩實現，等多啲功能穩定先補。
- 5 階段 4——原生「露餡」清單審查：逐條檢查 Web 應用喺桌面會露出馬腳嘅細節——cursor: pointer 一股網頁味、Web 式 hover 高亮、popover 要超 WebView 邊界、窗口 show/hide 唔可以閃。呢啲位要逐條驗收，寫入 CLAUDE.md。
避坑指南同可執行結論
- 1 以為「搬到 Web」就等於「能跨平台」——擴展 API 設計時就要 平台無關，唔可以洩漏 NS* 或 Win32 到 SDK。
- 2 內存數字嚇親自己——v1 200–300 MB，v2 350–450 MB，但產品 ship 速度同雙端覆蓋係收益。
- 3 要求 AI 寫「感覺像原生」太模糊——要用可觀察行為嚟驗收，例如「冷啟動主窗口 < 300ms」呢類 可驗證終態。
如果你只係叫 AI 翻譯 UI，收益上限好低。要問自己：遷移係咪順便解決咗舊架構最痛嘅刺？例如編譯慢、無法跨平台、某 OS API 唔可用。Raycast 用 Rust 重寫文件索引，唔再依賴 Spotlight，就係因為呢個功能喺 Windows 上根本做唔到。
你想把應用從「只跑 macOS」遷到 Windows，或者從 Swift 單體遷到 React + 跨平台——第一反應往往是：找十個工程師，開分支，幹兩年。
Raycast 剛公開 beta 的 2.0 走了一條不一樣的路：2023 年底立項 X-Ray（跨平台 Raycast），從零重寫，技術棧變成 TypeScript、Swift、C#、Rust、Node、React 疊在一起。官方自己說，難點從來不是「讓應用跑起來」，而是 「讓它感覺還對」。
這篇文章不聊 Raycast 好不好用。我把它當成 「AI 時代怎麼做應用遷移」 的教科書案例——你正在用 Claude Code / Cursor 維護老項目、想跨平台、想換棧的人，能直接抄思路。
1、先分清：什麼叫「AI 原生遷移」？
傳統遷移：人讀代碼 → 人畫架構圖 → 人寫新代碼 → 人測。AI 頂多幫你補幾個函數。
AI 原生遷移 是另一套默認動作：
Raycast 沒寫「我們全程用 Claude 寫的」，但他們的流程和今天 Claude Code 用戶該做的 高度同構：
早期用 Web 技術驗證（Notes 就是 React 塞進 WebView 的試驗） 原型證明「看起來像、摸起來像」再 all-in（半透明窗口、原生 tooltip 疊在 WebView 上） 產品邏輯沉到可 AI 協作的層（React + TypeScript + Node 佔大部分工時） 只有 OS 咬合處留給人 + 原生工程師（熱鍵、窗口、WebKit 節流）
說白了：**把 AI 擅長寫的部分最大化，把 AI 寫不好的部分圈起來。 *
2、遷移第一步：別先選框架，先選「AI 能守住哪幾層」
Raycast 評估過 Electron、Tauri、自建混合棧（系統 WebView + 原生殼）。他們否了 Electron，核心就一句：我們要掌控每一層，需要時能退回原生。
對正在遷移的你，可以翻譯成 三條路線（按 AI 協作友好度排序）：
路線 A：混合棧（Raycast 選的）——最適合「要強原生 + 要跨平台」
原生殼：macOS Swift/AppKit，Windows C#/WPF UI：一套 React + TypeScript，裝進 WKWebView / WebView2 業務：Node 常駐進程，數據庫、擴展運行時 性能熱點：Rust（文件索引等）
AI 能幫你什麼：React 頁面、Node API、類型化的 IPC 接口聲明、Rust 裏相對獨立的模塊。 你必須自己啃：全局熱鍵、窗口不搶焦點、WebKit 節流、popover 超出窗口邊界。
路線 B：Electron / Tauri——最適合「先遷起來、團隊小」
官方原話：對多數公司，Electron 就是正確答案。VS Code、Linear 都證明了。
AI 能幫你什麼：幾乎整個應用邏輯 + UI，資料多，模型最熟。 代價：macOS 上多綁 Chromium、原生細控弱，和 Raycast 這類「啓動器級 OS 集成」產品不匹配。
路線 C：純原生雙端——AI 只能當助手，不適合當主力
兩套 UI、兩套邏輯。AI 可以寫單點功能，很難幫你維持「一個團隊、兩個平台、功能同步 ship」。
我的判斷：如果你用 Claude Code 做遷移，除非產品極簡，否則別選 C。Raycast 若選 C，Windows 版會晚兩年，招聘也會崩。
3、目標架構：四層模型（可直接畫進你的遷移 Brief）
Raycast 2.0 最終是 四塊。你可以把它當成 遷移目標的默認模板：
層與層之間：接口一處聲明，各端生成類型化客戶端（他們混用平台消息處理器 + stdio）。 這對 AI 協作極其重要——你可以讓 Claude Code 只改 contracts/ 下的 IDL，再生成 Swift/TS/Rust 樁代碼，減少「改一層漏一層」。
遷移時給 AI 的 Brief 模板（可複製）：
4、用 Claude Code 遷移的 5 個階段（對照 Raycast 時間線）
階段 0：在舊代碼裏做「Web 試驗田」（Raycast：Notes）
別一上來就重寫。Raycast 先在 v1 裏用 WebView + React 做 Notes，驗證：Web 塊會不會破壞整體手感。
你可以做：挑一個相對獨立模塊（設置頁、報表頁、編輯器），用 HTML/React 做一版，嵌進現有殼。 給 Claude Code 的 prompt 方向：
階段 1：原型驗證「像不像自家產品」（Raycast：X-Ray 早期）
Raycast 在 all-in 前問了三件事：半透明行不行？原生 tooltip 能不能疊在 WebView 上？看起來像不像 Raycast？ 這是 AI 最該燒 token 的階段——用 HTML 出視覺與交互原型，比寫 Swift 快一個數量級。你上一篇若已接受「讓 Agent 出 HTML 而不是 Markdown」，這裏正好用上：讓 Claude出可點擊的單文件 HTML，給產品/自己摸一遍。
階段 2：定棧 + 劃界（Raycast：否 Electron，選混合）
用 AI 做 決策備忘錄，而不是讓它替你拍板：
人來做最終選擇。Raycast 的結論是：混合棧 infra 成本高，但對他們值得；你是小工具，可能 Electron 就夠。
階段 3：縱向切一條「黃金路徑」先 ship（別平行重寫所有功能）
Raycast 團隊大部分時間泡在 Web 前端 + Node。功能在這兩層 只寫一次，兩平台同時有。
遷移時別讓 AI 平行重寫 47 個頁面。選一條路徑，例如：登錄 → 主列表 → 詳情 → 保存。 對Claude Code 用/goal（若你已升級 v2.1.139+）：
階段 4：原生「露餡」清單——必須人審，別讓 AI 自由發揮
Raycast 列過一堆 Web 應用在桌面會露餡 的細節，他們全部改掉了。這份清單你可以直接當 Code Review checklist：
控件不要用 cursor: pointer（一股網頁味） 列表項不要 Web 式 hover 高亮（macOS 慣例不同） 設置頁用 獨立原生窗口，不要模態網頁 Popover / tooltip 用 原生窗口，要能超出 WebView 邊界 窗口 show/hide 不能閃（WebKit 老毛病）
給 Claude Code：
WebKit 那些硬核 workaround（alphaValue = 0 騙過節流、WKWebView frame 常駐全尺寸等）——別指望 AI 一次寫對，要對照 Raycast 文裏案例 逐條驗收。
5、AI 遷移時，Raycast 替你踩過的 3 個坑
坑 1：以為「遷到 Web」就等於「能跨平台」
擴展 API 設計時就要 平台無關。Raycast 擴展從沒假定只在 macOS 跑，所以搬 Windows 時 商店裏一大批擴展能跟着走。 你若用 AI 生成插件 API，在 prompt 裏 寫死：禁止 NS* / Win32 泄漏到擴展 SDK。
坑 2：內存數字嚇退自己，但產品形態變了
v1 大約 200–300 MB，v2 大約 350–450 MB。Raycast 沒有粉飾，但解釋得很清楚：WebView + Node 有基線成本，原生殼反而很輕。 你用 AI 遷到混合棧，要預先跟用戶（或老闆）對齊：內存會漲，但 功能 ship 速度、雙端覆蓋 是收益。
坑 3：讓 AI 寫「感覺像原生」——太模糊
Raycast 的測試標準極其具體：不知道技術棧的用戶，會不會以為這是普通 Mac 應用？ 把你的驗收標準也改成 可觀察行為，寫進 CLAUDE.md：
AI 需要 可驗證終態，這和 /goal 是同一套哲學。
6、和「只重寫 UI」相比，AI 原生遷移多做了什麼？
很多人用 AI 做遷移，其實只是 把 Swift 界面翻譯成 React，業務邏輯還在老地方。
Raycast 級別做法是：
文件索引這種 OS 級能力 用 Rust 重寫（Windows 上讀 NTFS MFT），不再依賴 Spotlight——這是 遷移動機 之一（v1 文件搜索在 Windows 上不可能） 業務沉到 Node，擴展與主應用 同一套棧（擴展不用再單獨裝 Node） 開發體驗：熱重載 UI 不到一秒 vs 以前編 Swift 重啓——AI 迭代速度才能釋放出來
你若只讓 AI 翻譯 UI，收益上限很低。要問自己：遷移是否順便解決了舊架構裏最痛的那根刺？（編譯慢、無法跨平台、某 OS API 不可用）
7、我的判斷：AI 原生遷移 = 人機分工重劃，不是「全自動重寫」
Raycast 花了很久，因為他們 手感不對就不 ship。AI 能縮短的是 中間層代碼的生成與迭代；不能縮短的是「這個產品摸起來還是不是它自己」。
給你三條 可執行結論：
能放進 React + Node 的，儘量交給 AI（含接口生成、頁面、業務邏輯、測試腳手架） Host + WebView 生命週期 + 平台慣例，建一個「原生清單」文件，遷移全程只許人 + 資深工程師改 用 HTML 原型 + /goal 式驗收 貫穿遷移，別用「感覺差不多了」收工
Raycast 2.0 證明了一件事：跨平台重寫不一定需要兩倍人馬；但需要 刻意把棧切成 AI 好啃的四層，並在原生邊界上死摳細節。
你下一個要遷的項目，不妨先問：Notes 模塊能不能先上 WebView 做試驗田？ 能，再談 X-Ray 式的全面重寫。
參考連結
A Technical Deep Dive Into the New Raycast（英文原文）：https://www.raycast.com/blog/a-technical-deep-dive-into-the-new-raycast 本號相關：Claude Code別再輸出Markdown了——9 類HTML玩法（附Prompt模板） 本號相關：Claude Code 的 /goal：終於不用盯着它一行行寫了