Agent 寫的界面各長各的？Astryx 用 4 步收成一套

作者注：Astryx 是 Meta 開源、現在仍是 Beta 的 React 設計系統。它把組件、主題和給 Agent 讀的文檔放在一起。它不是模型，也不自帶大模型接口。

用 Claude Code、Cursor 或 Codex等 Agent 改 React 界面時，常見的情況是：這一頁的按鈕帶圓角，下一頁沒有；彈層有的能點遮罩關閉，有的不能；間距一會兒是 12px，一會兒是 14px。原因不在模型能力，而在 Agent 手裏沒有一份可以查詢的設計系統。它只能憑記憶猜組件名和 props。Astryx 的做法是讓人和 Agent 讀同一份組件參考：人看文檔站，Agent 通過 CLI、AGENTS.md 或 MCP 取同一份內容。

本文不是安裝命令的複述。 下面會說明哪些信息是 Meta 官方自報，哪些是第三方作者的單次試驗，哪些是截至 2026-11-10 可以複覈但會變化的計數，並單獨列出現在不適合遷移的項目。

核心價值：讀完本文，你可以判斷 Astryx 是否適合自己的 React 項目，並用 4 步把它接到人和 Agent 共用的同一條路徑上。

上圖是 Astryx 官方公開的橫幅圖。實際界面可以在以下三個官方入口查看，本文不另做截圖：

文檔站：astryx.atmeta.com
組件瀏覽（Storybook）：astryx.atmeta.com/storybook/
在線試用（Sandbox）：astryx.atmeta.com/sandbox/

Astryx 核心要點：它是什麼、不是什麼

先把邊界講清楚。官方倉庫對 Astryx 的描述是：一套開源設計系統，外觀可以完全自定義，並且按照「人和 Agent 一起工作」的方式設計。許可證爲 MIT，主要語言是 TypeScript，README 標註爲 Currently in Beta，還沒有到 1.0。

要點	說明	對你的意義
技術底座	官方寫明基於 React 19+ 和 StyleX	React 18 項目不在支持範圍內
組件規模	官方口徑爲 150+ 個無障礙組件，帶 TypeScript 類型	常見頁面零件基本都有
外觀來源	七個現成主題，在 token 層修改顏色、字體、圓角、動效	換風格時改主題，不改每個組件
Agent 入口	CLI、生成的 `AGENTS.md`、遠程 MCP	Agent 查文檔，而不是憑記憶寫
模型接口	不提供，需要編碼工具自己接模型，例如通過 API易 apiyi.com	組件渲染本身不需要模型

Astryx 的來歷：哪些是官方自報

以下說法都出自 README 和 2026-06-18 的官方介紹文（作者欄爲 Astryx team），屬於官方自報，沒有獨立審計：Astryx 在 Meta 內部發展了八年，是公司內使用最廣、規模最大的設計系統，支撐 13,000+ 個應用。介紹文裏還有一個判斷：過去設計系統是寫給人讀的，現在越來越多代碼由 Agent 編寫，所以 Astryx 從一開始就按 AI 可以操作來設計，不是先做好再補一層 Agent 支持。

時間線有兩個日期，不要混在一起。官方介紹文發佈於 2026-06-18；@astryxdesign/core 第一次出現在 npm 是 2026-06-24。另外，GitHub 倉庫創建於 2026-01-09，那是倉庫建立的時間，不是對外發布日。

Astryx 和整包換皮、複製粘貼的區別

官方介紹文對比了兩種常見做法。下表只轉述官方定位，不涉及跑分：

做法	官方描述的問題	Astryx 的分工
整包換皮：直接用大公司整套設計系統	應用會帶上那家公司的品牌感	系統負責行爲、無障礙和質量
複製粘貼：組件代碼各項目 fork 一份	沒有統一升級，無障礙要使用者自己保證	主題負責外觀，在 token 層修改
Astryx：裝包，再用主題換外觀	仍是 Beta，處於 0.x 版本	需要時用 swizzle 把單個組件源碼彈出

README 還列了四個差異點。一是內部開放：組件可以在任意層級組合，常用零件直接導出，swizzle 能把某個組件的完整源碼彈進你的項目，之後由你維護。二是樣式不鎖定：可以用 className 覆蓋，搭配 Tailwind、CSS modules 或普通 CSS 都可以。三是不用包一層就能定製：主題本質上是一組 CSS 自定義屬性覆蓋。四是 API、文檔、CLI 一起設計，人和 AI 助手讀同一份參考。

第三方單例：一位作者的換主題試驗

LogRocket 在 2026-08-13 發表過一篇文章，作者 Chizaram Ken 把 Claude Code 接到 Astryx，做了三個界面，又用 shadcn/ui 做了同樣的三個。據作者自述，把主題從 neutral 換到 gothic 時，他改了兩個文件、四行代碼，沒有動任何組件文件。

這是作者自己的一次試驗，不是基準測試，也不是本文的測試結果。試驗時間早於當前的 0.7.11，當時的版本和現在不同。可以把它當作「主題和組件分開」這一設計的一個例證，但不能當作性能結論。

Astryx 快速上手：4 步把人和 Agent 接到同一條路徑

下面 4 步對應官方 Getting Started 和 Working with AI 兩篇文檔。每一步寫明要在終端或文件裏做什麼，以及看到什麼結果就算完成。以下是按官方文檔整理的步驟，本文沒有在這裏實際運行安裝。

第 1 步：安裝 Astryx 的四個包

終端運行：npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
再運行：npm install -D @astryxdesign/cli
pnpm、yarn 有對應寫法，包名不變。
完成標準：package.json 裏能看到這四個包名，並且 react、react-dom 都是 19 或更高版本。

StyleX 必須安裝，因爲它是 core 的 peer 依賴。不過官方也說明，Astryx 用 StyleX 寫樣式這件事對使用者是透明的，你的項目不需要改用 StyleX。只有在你主動使用 StyleX 時，組件纔會通過 xstyle 接收樣式。

第 2 步：用 init 生成給 Agent 讀的文檔

終端運行：npx @astryxdesign/cli init
這個命令不需要交互，人、CI、腳本和 Agent 都可以直接運行。
完成標準：項目根目錄出現 AGENTS.md。如果項目原本就有 CLAUDE.md，同一段說明也會寫進那個文件。

之所以要寫進 CLAUDE.md，是因爲官方說明 Claude Code 在項目已有 CLAUDE.md 時會跳過 AGENTS.md。如果需要指定工具，可以加參數，例如 --agent claude、--agent cursor、--agent codex 或 --agent all。Gemini CLI 只讀 GEMINI.md，init 會在那裏加一行，引用 AGENTS.md。

文件裏標記之間的 Astryx 區塊由 Astryx 管理，init 和 upgrade 只會改這一塊，不影響你自己寫的其他內容。官方還提到 Agent 經常猜錯 CLI 的路徑，建議在 package.json 里加一個腳本別名：

腳本名：astryx
腳本值：node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs
調用方式：npm run astryx -- component --list

第 3 步：引入 CSS，用 neutral 主題包住應用

在全局 CSS 中引入 @astryxdesign/core/reset.css
再引入 @astryxdesign/core/astryx.css
終端運行 npx @astryxdesign/cli theme add neutral，生成應用側的主題模塊。
從 @astryxdesign/core/theme 引入 Theme，把 themes[defaultThemeSlug] 傳進去，包住整個應用。
從 @astryxdesign/core/Button 引入 Button，官方示例使用 label 和 onClick 兩個 props。
完成標準：頁面上出現一個 Astryx 樣式的 Button，而不是瀏覽器默認按鈕。

這條路徑不需要構建插件，也不需要配置 PostCSS 或 Babel。有一點要提前注意：reset 放在 @layer reset，組件樣式放在 @layer astryx-base。如果項目裏已經有全局 CSS、舊的 reset 或 Tailwind，需要自己聲明 layer 順序，因爲未分層的樣式會覆蓋 astryx-base，而且和選擇器優先級無關。官方建議在開始做頁面之前，先讀 npx @astryxdesign/cli docs migration/migration-setup 裏的兩節。

七個現成主題的官方描述如下，沒有特別偏好時官方建議先用 neutral：

主題包	官方描述	適合用作
`theme-neutral`	低飽和、極簡	默認起點
`theme-butter`	暖金色，帶藍色點綴	偏溫暖的產品
`theme-chocolate`	巧克力色與焦糖色	偏復古的風格
`theme-gothic`	只有深色，墨水與 noir 風格	純暗色界面
`theme-matcha`	草木綠	偏自然的風格
`theme-stone`	砂岩一類的暖中性色	偏穩重的後臺
`theme-y2k`	2000 年前後的活潑風格	活動頁、趣味產品

第 4 步：讓 Agent 按官方三步寫 UI，必要時接入 MCP

init 生成的規則要求 Agent 在寫 UI 之前按以下順序操作：

npx @astryxdesign/cli build "<想法>"：返回一個最接近的頁面模板（至少會有一個應用外殼）、兩個備選模板，以及還缺哪些塊和組件。
npx @astryxdesign/cli template <名字> <路徑>：把模板放進項目，保留原有框架和間距，只替換內容。
npx @astryxdesign/cli component <組件名>：查看每個要用到的組件的 props 和示例。
規則裏還寫了幾條禁止項：每個頁面都從模板開始；不用裸 div；不寫 style={{}}；使用 token，不寫魔術數字。
完成標準：Agent 引用的組件名和 props 都來自 CLI 的輸出，而不是它自己編的。

可以用官方建議的三個問題來檢驗：Button 的正確引入路徑是什麼；Dialog 怎麼設置成不能隨手關閉；Selector 用哪個 prop 傳入 items。如果 Agent 答不上來，就先運行 init。正確答案以你本機 CLI 的輸出爲準。

需要遠程查詢時，可以接入官方 MCP，地址是 https://astryx.atmeta.com/mcp。它提供兩個工具：search(query) 用於查找組件、文檔和模板，get(name) 用於獲取完整文檔。不同客戶端的配置寫法不一樣：

客戶端	配置方式	注意點
Claude Code	終端運行 `claude mcp add --transport http astryx https://astryx.atmeta.com/mcp`	服務名爲 astryx
Cursor	`.cursor/mcp.json` 中只寫 url	遠程服務不寫 type
Cline	transport 寫 `streamableHttp`	不是 `http`
Claude Desktop	設置中 Connectors → Add custom connector，粘貼 URL	配置文件只放本機 stdio
其他通用客戶端	type 寫 `http`，加上 url	無法識別的 transport 會被跳過，表現爲已連接但沒有工具

官方沒有說明這個遠程地址的 SLA，也沒有寫服務不可用時如何處理。CLI 是同一套文檔的本地入口，MCP 連不上時可以繼續用 CLI。

編碼 Agent 的模型從哪裏來

設計系統負責組件和文檔，但編碼 Agent 真正生成代碼時，還需要單獨接入一個模型。如果團隊要自己爲 Claude Code、Cursor 這類工具提供模型，可以使用 API易 apiyi.com 的 OpenAI 兼容接口，base_url 填 https://api.apiyi.com/v1，模型名按當天模型列表中的名稱配置。型號與價格以 API易平臺型號列表爲準；API易會按列表提供可用模型。

需要說明的是，組件在瀏覽器裏渲染，不需要任何模型接口。是否使用 API易，不影響 Astryx 的安裝和運行。

🚀 快速開始建議：可以先按上面 4 步在一個新分支上搭一個模板頁，再讓 Agent 用同一個模型分別在有 AGENTS.md 和沒有 AGENTS.md 的情況下各寫一次，比較兩次輸出的組件名和 props。新用戶可以在 API易 apiyi.com 獲取免費測試額度，用於這類對比。

Astryx 的風險與不適合遷移的情況

Astryx 產品本身的風險

Astryx 仍處於 Beta，版本號是 0.x。截至 2026-11-10，npm 的 latest 是 0.7.11（發佈於 2026-11-07），上一個穩定版 0.7.10 發佈於 2026-11-06，穩定版幾乎每天都在更新。升級時，項目用到的所有 @astryxdesign/* 包必須升到同一個版本，然後運行 npx @astryxdesign/cli upgrade --from <舊的 core 版本> --apply。每個主題都聲明瞭對應的 core 版本，如果漏升主題，主題和 core 會不匹配。如果包管理器按發佈時間延遲安裝新版本，需要把整個 @astryxdesign/* 範圍排除，pnpm 的寫法是在 minimumReleaseAgeExclude 中加入 @astryxdesign/*。

圖表方面，@astryxdesign/vega 和 @astryxdesign/charts 只在 npm 的 canary 標籤下發布，沒有穩定版。截至 2026-11-10，canary 是 0.7.12-canary.dfd75a6，版本號雖然比 latest 新，但不應該作爲生產依賴使用。

通過 API易接入模型的風險

這部分只涉及編碼 Agent 的模型調用。請求會經過 API易的網關，API Key 和費用由調用方自己管理，模型的實際表現以你選擇的型號和網關的實際返回爲準。這不是登錄 Meta 賬號，也不是號池。

暫時不建議遷移的項目

項目還在使用 React 18：core 的 peer 依賴要求 react 和 react-dom 都是 19.0.0 及以上。
現在就需要 1.0 的穩定性承諾：官方目前標註爲 Beta，沒有給出這一承諾。
現在就需要穩定版圖表：圖表包只有 canary 版本。
希望從第一天起每個組件的源碼都在自己的倉庫裏：這屬於複製粘貼的做法。Astryx 默認是安裝包，swizzle 是之後按需把單個組件的源碼彈出來。

Astryx 熱度與版本：截至 2026-11-10 的計數

以下數字截至 2026-11-10，之後會變化，不應當作固定事實：

指標	數值	出處
GitHub stars	20,217	GitHub API `meta/astryx`
forks	1,536	GitHub API
未關閉的 issue / PR	297 / 373	GitHub Search API（合計 670，不等於 670 個 bug）
core 周下載量	661,968 次（2026-11-02 至 11-08）	npm 下載 API，統計的是下載次數，不是用戶數
core 近 30 天下載量	1,725,492 次（2026-10-10 至 11-08）	npm 下載 API

常見問題 FAQ

Q1：Astryx 是一個 Tailwind 組件庫嗎？

不是。官方寫明它基於 React 19+ 和 StyleX，併發布預編譯的 CSS。它可以和 Tailwind 一起使用：外觀可以用 className 覆蓋，倉庫 `apps/` 目錄下也有 example-vite-tailwind、example-nextjs-tailwind 兩個示例。混用時需要注意前面提到的 CSS layer 順序。

Q2：React 18 項目能用 Astryx 嗎？

不能。0.7.11 的 core 包要求 `react` 和 `react-dom` 都在 19.0.0 及以上，React 18 不滿足這一條件。需要先把項目升級到 React 19。

Q3：不接 MCP，Agent 還能用上 Astryx 的文檔嗎？

可以。init 生成的 `AGENTS.md` 加上本地 CLI，就能完成 build、template、component 三步，MCP 只是用於遠程查詢的另一個入口。如果要把內容貼進網頁版對話，可以加 `–detail brief`、`–detail compact` 或 `–dense` 來縮短輸出。

Q4：facebook/astryx 和 meta/astryx 是兩個倉庫嗎？

是同一個倉庫。截至 2026-11-10，訪問 `github.com/facebook/astryx` 會返回 301，跳轉到 `github.com/meta/astryx`，後者是正式倉庫地址。舊文章裏寫的 facebook/astryx 指的就是它。

Q5：Astryx 的圖表組件能用於生產環境嗎？

目前不建議。`@astryxdesign/vega` 和 `@astryxdesign/charts` 只在 canary 標籤下發布，README 也寫明沒有穩定版。生產項目可以先繼續用現有的圖表方案。

Q6：升級時只升級 core 可以嗎？

不可以。官方要求把項目用到的所有 `@astryxdesign/*` 包都升到同一個版本，否則主題會和 core 不匹配。升級完成後運行 `upgrade –from <舊版本> –apply`，它還會刷新 `AGENTS.md` 裏已經過期的 Astryx 區塊。

Q7：使用 Astryx 需要模型 API 嗎？和 API易是什麼關係？

組件渲染不需要模型 API。只有在讓編碼 Agent 寫代碼時才需要接入模型，這一步由 Claude Code、Cursor 等工具負責。如果團隊要自己提供模型，可以在 API易 apiyi.com 用一個 Key 調用多個主流模型。API易與 Meta 或 Astryx 之間不存在合作關係。

Q8：能把某個組件的源碼複製到自己的倉庫裏改嗎？

可以，但這不是默認做法。swizzle 會把單個組件的完整源碼彈進你的項目，之後這份代碼由你維護，後續升級也需要你自己處理。`theme eject` 官方也建議只在明確需要獨立源碼分支時使用。

Astryx 核心要點 Key Takeaways

定位：Meta 開源的 React 設計系統，MIT 許可證，目前仍是 Beta 和 0.x 版本。
分工：系統負責行爲和無障礙，主題負責外觀，換主題不需要改組件文件。
硬性條件：需要 React 19 或更高版本，StyleX 作爲 peer 依賴必須安裝。
Agent 路徑：先 init 生成 AGENTS.md，再按 build → template → component 的順序寫頁面。
MCP 可選：遠程地址是 https://astryx.atmeta.com/mcp，本地 CLI 是同一套文檔的入口。
升級規則：所有 @astryxdesign/* 包一起升到同一版本，圖表包只有 canary。
模型另接：編碼 Agent 需要的模型可以通過 API易 apiyi.com 統一接入。

總結：Astryx 能否讓 Agent 寫出統一的界面

Agent 寫的界面不統一，根源在於它只能猜組件名和 props。Astryx 的思路是把組件、主題和給 Agent 讀的文檔放進同一個系統：

4 步接入：安裝四個包，運行 init，引入 CSS 並用 Theme 包住應用，讓 Agent 按三步查詢後再寫。
區分事實來源：13,000+ 應用、內部使用八年屬於官方自報；換主題只改四行是第三方作者的一次試驗；星標和下載量是截至 2026-11-10 的計數。
先確認是否適合：如果項目還在 React 18、需要穩定版圖表或 1.0 承諾，可以暫緩遷移。

如果你的項目已經是 React 19，並且希望 Agent 少編造 props，可以先在一個分支上試一個模板頁。編碼 Agent 需要的模型可以通過 API易 apiyi.com 接入，用免費測試額度比較不同模型在同一份 AGENTS.md 下生成的代碼。

📚 參考資料

Astryx GitHub 倉庫：README、包列表、主題清單與原則說明
鏈接：github.com/meta/astryx
說明：官方自報信息的主要來源，facebook/astryx 會跳轉到這裏
Astryx 官方介紹文：2026-06-18 發佈的設計理念說明
鏈接：astryx.atmeta.com/blog/introducing-astryx
說明：與整包換皮、複製粘貼兩種做法的對比出自這裏
Getting Started 與 Working with AI 文檔：安裝、主題、init 與 MCP 配置
鏈接：astryx.atmeta.com/docs/getting-started、astryx.atmeta.com/docs/working-with-ai
說明：本文 4 步的官方依據
Astryx v0.7.11 發佈說明：當前穩定版與升級方法
鏈接：github.com/meta/astryx/releases/tag/v0.7.11
說明：要求所有包統一版本的原文出處
LogRocket 對比文章：2026-08-13，作者 Chizaram Ken
鏈接：blog.logrocket.com/astryx-vs-shadcn-meta-ai-react-claude
說明：第三方單次試驗，版本早於 0.7.11

作者：APIYI 技術團隊
技術交流：如有編碼 Agent 接入模型的問題，歡迎通過 API易官網首頁聯繫我們。

Agent 寫的界面各長各的？Astryx 用 4 步收成一套