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 步收成一套