affectUI：给 AI 智能体造一套「像样」的界面

想象一个场景：你花了三周把一个多智能体编排系统跑通了，Claude Code 帮你写完了 80% 的业务代码，你兴冲冲地把前端接上去，结果发现——聊天框还是气泡加输入框，工具调用只能打成一行 JSON 塞在消息里，智能体之间谁调度谁完全看不见，用户点一下要等 3 秒屏幕纹丝不动，主打一个「AI 味儿的 demo」。

这正是 affectUI 要解决的问题。

一、它是什么

affectUI 是作者 Flo（flohoeller）做的一套 React 组件库，但定位不是「又一个 shadcn/ui」，而是专门给 AI 产品和 Agent 产品用的界面零件。截至 2026 年 11 月 3 日，GitHub 438 星、22 fork、MIT 协议，仓库创建于 2026 年 10 月 3 日——一个月的项目冲到 400+ 星，增长速度相当生猛。

它最有辨识度的设计原则是「一个文件就是一切」：每个组件都是一个独立的 .tsx 文件，样式直接写在文件内部，不依赖 Tailwind、不需要配置 CSS、不引入任何动画库。抄进你的项目就能用，代码版权属于你。

二、核心功能：把「智能体在干什么」变成可视界面

这是它和普通 UI 库最大的区别。仓库 components/ 目录下共 34 个组件文件（17 组组件 × Classic/Clean 两种风格），其中真正面向 Agent 场景的有这么几个：

Agent Tree（智能体树）——展示多智能体的层级与委派关系：谁是编排器、谁调度了谁，每张卡片带状态、耗时、成本，费用能按分支向上汇总，折叠后收成一行。

Tool Call Card（工具调用卡）——把一次工具调用压缩成一行：实时计时器、状态、摘要；点开展开是高亮的入参和返回结果，带复制按钮；出错时可直接重试；同组调用还能汇总统计。这一个组件直接解决了「JSON 糊在脸上」的经典痛点。

Trace Waterfall（追踪瀑布流）——按步骤展示执行链路和每步成本。

Thinking Loader（思考加载器）——8 条光线的旋转指示器加流动高光标签，标签会依次走过「Thinking → 搜索网页 → 读取来源 → 编写回答」等阶段，旧的卷起模糊、新的卷入，整个胶囊同步改变宽度；完成后旋转变为对勾，标签落定为「Thought for 6s」。这个细节做得很到位——把「模型在思考」这种最反直觉的等待状态，变成了一段有节奏的叙事。

Decision Inbox（决策收件箱）——需要人工审批的动作排成队列，每个决策给两个快捷选项，处理完自动折叠消失。

此外还有 Chat Composer、Email Draft（智能体起草的邮件，支持换收件人/语气、行内编辑、撤销发送）、Smart Recommendation（带置信度信号的推荐卡）、Comment Thread（智能体汇报工作并回答 @ 提及）、Agent Handoff、Context Map 等。另有 illustrations/ 下 17 张手绘风 SVG 插画（region-dach.tsx 单独就有 163KB）、motion/ 下 4 个动效（网格背景、滚动数字、微光骨架屏、逐字显现）、blocks/ 下 2 个页面区块（Logo 走马灯、用户证言墙）。

三、类比：它更像「文案」而不是「积木」

shadcn/ui 给的是积木——按钮、弹窗、输入框，样式靠 Tailwind 类名，你得自己搭配出成品。affectUI 给的是已经写好的文案：按钮、弹窗这些通用零件还是用 shadcn，但「智能体调用了搜索工具」「智能体正在等待审批」「这个回答花了 2 分 15 秒」这些 AI 独有的状态，它已经替你想好了长什么样、怎么动、怎么折叠、怎么降级。

官方在对比页里说得很直白：两者不竞争，affectUI 就是一个 shadcn registry，CLI 装完直接落在同一个 components/ui 目录里。

四、上手门槛：两条路都算低

# 方式一：shadcn CLI，逐个装
npx shadcn@latest add https://www.affectui.com/r/tool-call-card.json

# 方式二：注册命名空间后用短名
npx shadcn@latest add @affectui/tool-call-card

也可以直接去 GitHub 仓库对应目录复制 .tsx 文件粘进项目。

硬性要求只有一条：React 19（TypeScript 可选）。Next.js、Vite、Remix、纯 React 都能用。

更有意思的是它对 AI 编程工具的适配——官方提供了 MCP server，Claude Code / Cursor / VS Code / Codex 可以直接搜索组件、读文档、帮你装：

claude mcp add --transport http affectui https://www.affectui.com/api/mcp

不用 MCP 的话，也可以把 llms.txt 或 llms-full.txt 指给 AI 助手。这在 2026 年的组件库里算是标配了，但实现得比较彻底。

需要注意的是：这些组件是纯 UI，只接收普通 props。接 Vercel AI SDK、LangChain 还是自家 API，都由你自己在中间层做适配。

五、争议与局限

要说清楚几件事：

1. 开源只是「冰山一角」。官网总计 132 个组件/区块/插画/动效，其中只有 40 个免费开源（就是本仓库里的这些），剩下 92 个包括最核心的 Agent Tree、Agent Inbox、Trace Waterfall、Context Map、Agent Handoff 全部收在 affectUI Pro 里，一次性付费 199 美元起，源码不在本仓库。所以严格说，这个 GitHub 仓库更像是产品的一部分，不是完整的开源项目。评估依赖时要意识到这一点。

2. 仓库内容是「生成物」。CONTRIBUTING.md 明确写着：这里的文件是从 affectUI 源码库同步过来的，直接提 PR 会被下次同步覆盖，修 bug 只能走 issue。这对贡献者不友好，也意味着 GitHub 上的代码不一定是最新状态。

3. 组件体量偏大。单个组件动辄 700-950 行（tool-call-card.tsx 943 行、message-actions.tsx 729 行、email-draft.tsx 803 行），因为动画逻辑和样式全部内联在一个文件里。代码质量上做得扎实——检查了几个组件，没有 dangerouslySetInnerHTML、eval、动态 innerHTML 这类注入风险点，纯 CSS 变量 + prefers-reduced-motion 适配，但单文件体积对项目整体负担不小。

4. 必须先想清楚版本兼容。React 19 是硬门槛，React 18 的存量项目接入会有摩擦。

5. 商业模型风险。开源部分与 Pro 部分同源，作者后续若调整策略，免费部分的定位可能被稀释。

六、代码与工程质量

技术栈非常纯粹：TypeScript + React 19，零构建依赖、零运行时依赖、零 Tailwind 要求。目录组织清晰：components/（34 个组件文件）、illustrations/（17 个）、motion/（4 个）、blocks/（2 个）、.github/（issue 模板 + showcase 截图）。没有测试目录、没有 CI 配置、没有 package.json——因为它本来就不是个 npm 包，而是一堆「拿去抄」的文件。

组件内部工程质量相当高：真实的 <button> 元素、完整的键盘支持、恰当的 aria-live 区域、容器查询做响应式（而非只跟随视口宽度）、暗色模式通过祖先的 dark 类或 data-theme="dark" 切换、全部尊重 prefers-reduced-motion。这些「看不见但要花时间做」的部分，恰好是很多开源组件库会糊弄过去的。

对一个纯展示型组件库来说，这套自律程度属于上乘。

七、行业意义

affectUI 折射出一个明确趋势：AI 产品的竞争已经从「模型能力」转向「交互表达」。当所有产品都用着差不多的 LLM 和差不多的编排框架时，差异往往就落在「用户能不能看懂智能体在干什么」这件看起来很虚的事上。而这块体验，目前几乎没有成熟的开源方案——shadcn/ui 完全不覆盖，主流组件库也只停在「消息气泡 + 输入框」。

它的做法值得注意：不卷框架、不卷运行时，直接把「源码即交付物」的 shadcn 模式推到极致——你抄走的就是全部，没有黑盒、没有依赖地狱。同时把 MCP、llms.txt 这套 AI 原生接入方式做进产品，把 AI 编程助手当成第一等公民用户。

从 2026 年 10 月 3 日创建到 10 月底突破 400 星，团队走的是「开源 40 个引流 + Pro 92 个变现」的经典打法，README 里点名的使用方包括 Teamworks、RedNote、Cloudforce、Moonshot AI、美图等团队。

一句话结论：如果你在做一个有智能体、有工具调用、有人工审批环节的 AI 产品，affectUI 的开源那 40 个组件值得直接抄进项目，能省下至少几天的动效和交互打磨；但如果你的核心界面就是 Agent Tree 和 Trace Waterfall，那 199 美元才是这个项目的真实成本。