PanelUI 是一个面向 React Native（Expo）的开源 UI 组件库，提供 141 个组件模块与 6 套主题。这篇文章介绍如何用 Skills 与 MCP 让 Claude Code、Cursor 等 AI 编码智能体写出"零幻觉"的 React Native 组件代码——智能体不再凭记忆猜 API，而是先读真实的组件文档和源码，再动手写。

一、为什么 AI 写 React Native 组件总"翻车"？

如果你试过让编码智能体直接写 PanelUI 界面，大概遇到过这些情况：

• 幻觉 props：智能体"记得"一个variant="dark"，但组件根本没有这个属性，编译报错或静默失效；
• 导入路径猜错：PanelUI 支持"装包"和"复制源码"两种用法，智能体经常写错 import 路径；
• 主题写法踩坑：写了dark:bg-neutral-900这样的覆盖类，结果在 6 套主题里有 4 套不生效，而且不报任何错误；
• 弹层永远不出现：漏掉根组件PanelUIProvider，Dialog、BottomSheet 挂载了却渲染不出来。

根本原因：智能体依赖训练数据里的记忆，而组件库的 API 是持续演进的。解决办法不是换更强的模型，而是给智能体两样东西：

1. 📚一份随库更新的本地知识库（Skills）——离线可读的组件手册 + 编码规则；
2. 🔌一条实时查询通道（MCP 服务器）——让智能体按需搜索组件、读真实源码、获取安装命令。

PanelUI 把这两样东西都内置在了仓库里，这也是本文的重点。

二、PanelUI Skills：装进智能体的"活组件手册"

打开仓库的 skills/panelui/ 目录，你会看到一套完整的 Skill 文件夹（主入口是 SKILL.md），它专为编码智能体设计，可以放进 Claude Code、Cursor 等支持 Agent Skills 的环境。它的核心设计是四条原则（SKILL.md）：

几个值得注意的细节：

• rules/ 目录是"避坑手册"。rules/styling.md、rules/composition.md 等文件全部用"错误写法 vs 正确写法"的成对示例描述规则，智能体最容易照着模仿；
• setup.md 专治"屏幕一片空白"。skills/panelui/setup.md 把"装了但没样式"这种无报错故障拆成 6 步排查清单——元凶绝大多数是metro.config.js里的路径写错；
• 全程离线。组件文档就放在本地文件夹里，智能体读文档不需要任何网络请求。

这套 Skill 的价值在于：智能体拿到的是与库版本一致的 API，而不是训练语料里的旧记忆。

三、PanelUI MCP 服务器：一条命令让智能体"读源码"

Skills 解决"本地手册"，MCP 解决"实时查询"。PanelUI 的 CLI 内置了一个零依赖的 MCP 服务器（实现在 packages/cli/src/mcp.mjs），基于组件注册表构建，智能体看到的源码就是add命令会装进项目的源码。

3.1 一键接入

在项目里运行一条命令即可启动服务器，再用mcp init自动写入编辑器配置（会合并而非覆盖已有配置，详见 skills/panelui/mcp.md）：

npx panelui-cli@latest mcp npx panelui-cli@latest mcp init # 为 Claude Code 写入 .mcp.json npx panelui-cli@latest mcp init cursor # 写入 .cursor/mcp.json npx panelui-cli@latest mcp init vscode # 写入 .vscode/mcp.json

手动配置时只需这几行 JSON（来自 skills/panelui/mcp.md）：

{ "mcpServers": { "panelui": { "command": "npx", "args": ["-y", "panelui-cli@latest", "mcp"] } } }

3.2 六个工具，各司其职

MCP 服务器暴露了 6 个工具（定义见 packages/cli/src/mcp.mjs）：

四、完整工作流：从"我要一个筛选面板"到正确代码

接入之后，智能体处理需求的标准流程是五步：

1. 先摸清项目：调用panelui_get_project_info。这一步决定了代码里写import { ... } from 'panelui-native'还是import { ... } from '@/components/ui/...'——两种用法都完全支持，但不能假设，得查；
2. 搜索而非臆造：用panelui_search_components搜"filter"，发现现成的BottomSheet+ToggleButtonGroup+Slider，不用自己拼一个"自定义面板"；
3. 读真实文档：对要用的组件调panelui_get_component_docs，拿到由 TypeScript 生成的 props 表——包括默认值、变体、复合部件（如BottomSheet.Trigger必须包在BottomSheet里）；
4. 按需取源码：走"复制源码"路线时调panelui_get_add_command，拿到形如npx panelui-cli@latest add bottom-sheet的命令，依赖会被自动解析；
5. 按规则写码：Skills 里的 recipes（recipes.md 的"底部弹层筛选"一节）给出组合方式，rules 目录兜底细节——弹层必须用open+onOpenChange控制，不要靠条件渲染关闭它，否则退出动画来不及播放。

这套流程的效果：智能体写出的代码，props 来自真实源码，规则来自项目内置手册，而不是模型脑补。

五、生成效果：整屏组件组合一览

下面的界面全部由 Skills 中的配方组合而成，也是智能体照着文档能直接复刻出的典型场景：

聊天界面——MessageScroller（虚拟化滚动 + 吸底）+Message（单条消息），是 recipes.md 里的标准配方：

表单界面——Form+Field+Input的组合，Field负责把标签与控件关联起来（屏幕阅读器可正确读出），这是"裸 View 套 Text"做不到的：

卡片界面——复合 API 的直观体现：Card.Header、Card.Content按标记的读法组合，AI 写起来像写文案一样顺：

主题切换——6 套主题、3 个主题家族（Panel / Moon / Grass），每套家族还自带独立的圆角比例；智能体读到 theming.md 就知道该用 token 而非dark:覆盖类：

六、常见问题（FAQ）

Q：智能体需要联网吗？Skills 完全本地：组件文档就在skills/panelui/components/下，读文档零网络请求。MCP 服务器查询的注册表也是公开免认证的，断网时 Skills 依然能兜底。

Q：没有 MCP 的环境能用吗？可以。Skills 单独使用就是完整的组件手册 + 规则集，智能体读本地 md 文件即可。MCP 是"加分项"，提供搜索和读源码的能力。

Q：--overwrite能放心用吗？不能。skills/panelui/cli.md 明确警告：复制源码的意义就是本地修改，--overwrite会覆盖本地改动。升级组件时先跑add <name> --dry-run看会动哪些文件，再逐个决定。

Q：AI 写完代码屏幕是空白的怎么办？这是最典型的"无报错故障"。让智能体按 skills/panelui/setup.md 的清单排查，元凶几乎都是metro.config.js不在项目根目录、withUniwindConfig没包住配置、或cssEntryFile路径指错。

Q：新项目怎么起步？

npx create-panelui-app@latest

Metro 配置、CSS 入口、Provider、主题和示例页面全部就绪（详见 README.md）。

七、相关资源速查

一句话总结：Skills 让智能体"带着手册写代码"，MCP 让它"随手可查真实源码"。两者都是纯本地、随库版本更新、零额外配置——这就是 AI 精准写出 React Native 组件代码的最短路径。 🚀