AgnosticUI Local (v2)：把 UI 组件源码直接"抄"进你项目的 AI 原生组件库

一、一个真实的开发场景

想象这样一个日常：你正在用 Cursor 或 Claude Code 写一个后台管理界面，需要一个带分页的表格。你让 AI 生成，AI 给你输出一段看起来合理但 API 完全对不上的代码——因为它根本看不见你用的组件库长什么样，只能"编"。

AgnosticUI Local 提出的解法朴素得有点反直觉：别把组件藏进 node_modules，直接抄到你自己的代码库里。组件源码、类型定义、Token 变量、测试文件全部躺在你的 src/components/ag/ 目录下，AI 打开项目就能读到全部真相。库里提供 ag context 命令，一键生成一份 CLAUDE.md，把每个组件的精确路径、prop 类型、导入写法全部喂给 AI 助手，AI 从"猜 API"变成"照抄 API"。

二、项目起源与定位

AgnosticUI 由独立开发者 Rob Levin 于 2020 年创建，最初是一套基于 Lit Web Components 的"框架无关"组件库——同一份实现可以运行在 React、Vue、Svelte、Lit 等任意框架上，核心卖点是"一套组件，多端可用"。

2026 年 v2 是一次范式转向：从"依赖库"变成"参考库（reference library）"。CLI 在初始化时把整个库作为参考拷进项目，之后 ag add button 这样的命令才是把具体组件的源码"弹出（eject）"到你的业务代码里。这样做的直接后果是：组件归你所有，改成什么样都行；升级时参考库单独 ag sync，你改过的组件绝不会被覆盖。

三、类比：组件库的三种活法

• 传统方式：像租房子。npm 装的是"别人家的房子"，你只能在框架允许的缝隙里改装修，改不动结构。
• shadcn/ui 方式：像买房并自己装修。源码在你手里，但框架绑定死，换 React 到 Vue 就得重来。
• AgnosticUI 方式：像买地自己盖房。核心用 Web Components 标准件（Lit 编写），盖好后在 CLI 里按框架"翻译"成 React/Vue/Svelte 版本，一次编写，处处落地，且盖房子时 AI 能看到每一块砖。

四、核心功能与技术细节

1. 框架无关的 Lit 核心：v2/lib 是核心库，组件以 Web Components 形式编写，同时提供 React/Vue 包装层，package.json 的 exports 字段为每个组件暴露 ./button、./button/react、./button/vue 三条路径。运行时零依赖是它最大的技术卖点——弹出后组件不再依赖 agnosticui-core。

2. CLI 工具链：v2/cli 用 Commander 构建，提供 init / add / list / sync / playbook / context 六组命令。init --framework react 生成参考库，add 按需弹出组件，sync 更新参考库但绝不触碰已改动的组件，context 生成给 AI 用的上下文文件。

3. AI Playbooks（智能体可复用的界面蓝图）：v2/playbooks 目录内置 login、onboarding、dashboard、support、grid、blog、landing 等 8 个完整界面蓝图，每个都是可直接 npm install && npm run dev 跑的 Vite 项目。官方把这些 Playbook 当作"给智能体的技能"——让 Agent 按蓝图直接生成登录页、多步引导流程、数据看板这类复杂界面，而不是每次从零设计。

4. SDUI 声明式渲染层：这是 v2 最有前瞻性的部分。v2/sdui 是一套 schema 驱动的节点图（node graph）渲染体系，配有 playbook-sdui.schema.json JSON Schema、llm-prompt-guide.md（可直接粘贴的提示词模板 + few-shot 示例）、sdui-architecture.md（代码生成管线、CI 门禁）。核心逻辑是：LLM 不直接吐 HTML，而是吐一棵 AgNode[] 结构化节点树，由各框架渲染器（React/Vue/Lit）消费。同一份结构化输出可校验、可测试、可在 CI 中做一致性门禁——这是把"生成 UI"从玄学拉回工程化的尝试。

5. 无障碍与主题：仓库内附 A11Y_OPEN_ISSUES.md 跟踪无障碍待修项，v2/skins 提供多套皮肤，Token 体系以 CSS 变量输出，支持明暗双主题。

五、上手门槛

CLI 用户：门槛极低，但要注意版本——CLI 仍处于 alpha 阶段（2.0.0-alpha.25），必须带 @alpha tag 安装（npx agnosticui-cli@alpha init），且要求 Node.js ≥ 18。初始化后 ag add 弹出组件、ag context 生成 AI 上下文，两条命令即可跑通主流程。

纯前端库用户：核心包 agnosticui-core（2.0.0-alpha.30）同样处于 alpha，可通过 npm 引入，适合想直接用 Lit 核心而不走 CLI 弹出流程的场景。

SDUI 使用者：门槛最高。schema、节点图模型、渲染器三套概念需要通读 v2/docs 下的四份架构文档才敢动手，属于典型的"文档先行"型子系统。

六、争议与局限

版本成熟度：v2 全部处于 alpha 阶段，README 中"Zero runtime dependency"这类承诺建立在 alpha 的实现上，生产环境需自行验证。仓库有 13150 个文件，其中大量是 node_modules 被误提交进 Git（v2/theme-registry/node_modules/ 清晰可见），说明仓库卫生不佳。

源码弹出的双刃剑：组件归你所有，但同时也意味着"升级红利"要靠自己维护。几百个组件复制进项目后，安全补丁、bugfix 都要手工合入——ag sync 只更新参考库，不帮你合并到已改代码。这是典型的"copy-paste 依赖地狱"，只是换了个更体面的说法。

SDUI 的实用性存疑：节点图 + 渲染器 + schema 的组合理论上优雅，但 LLM 真正稳定输出合法 AgNode[] 的能力仍在爬坡期。仓库里 schema-coverage.md 明确记录了各组件的 SDUI 覆盖情况与"遗漏原因"，说明覆盖并不完整。

生态规模：832 star、47 fork，规模远小于 MUI、Ant Design。对团队而言，引入它意味着要自己承担组件质量、无障碍和长期维护责任。

七、行业意义

AgnosticUI 抓住的是一条正在成型的趋势线：AI 编程工具正在把"代码上下文"变成新的稀缺资源。当 Claude Code、Cursor、Copilot 成为主要代码生产者，组件库的价值衡量标准就从"运行时 API 好不好用"转向"AI 能不能准确读懂并复用"。AgnosticUI 把组件源码搬到本地仓库，本质是把组件库从"运行时依赖"降维成"上下文资产"。

同时，"Playbook 作为智能体技能"这个思路也有意思：它承认了 AI 生成复杂界面时需要预置蓝图，而不是每次自由发挥。与 SDUI 的声明式渲染结合，构成了一条从"提示词生成 HTML"到"结构化节点图渲染"的进化路径。

从 2020 年的普通组件库到 2026 年的"AI-native UI kit"，AgnosticUI 用了六年时间完成了这次转身。星星数不高，但方向押得很准。