ZCode 中的 AI Elements Tool 组件：为 AI 聊天界面构建可折叠的工具调用展示

ZCode 中的 AI Elements Tool 组件为 AI 聊天界面构建可折叠的工具调用展示【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCodeTool是 ZCode 仓库内集成的 AI Elements 的真实源码实现与.agents/skills/ai-elements/scripts/下的系列示例脚本完整讲解该组件的安装、在 AI SDK 中的实战用法、全部 Props 与状态系统让你能直接在自己的 AI 应用中复现同款可折叠工具调用卡片。组件定位与设计思路Tool组件是一个可折叠Collapsible容器用于在 AI 聊天界面中展示/隐藏工具调用的详细信息。它被设计为直接接收 AI SDK 的ToolUIPart类型数据并将其渲染成一个可折叠的交互界面——用户点击头部即可展开或收起参数、结果等内容。在 ZCode 仓库中该组件及其文档源自 vercel/ai-elementsApache-2.0 许可由 ZCode 做了本地集成与格式化适配参见仓库根目录 THIRD-PARTY-NOTICES.md。与黑盒库不同AI Elements 的组件代码会直接写入你的项目默认位于components/ai-elements/目录因此你可以像阅读自己写的代码一样查看、修改其实现这为深度定制工具调用展示提供了极大自由度。安装在已配置好 Node.js 18、Next.js 与 AI SDK 的工程中使用项目对应的包管理器运行npx ai-elementslatest add tool注意请使用项目packageManager对应的运行器例如pnpm dlx ai-elementslatest或bunx --bun ai-elementslatest。命令会下载组件源码并集成到/components/ai-elements/目录或你在 shadcn 配置中指定的 components 目录。若项目尚未安装 shadcn/ui执行安装命令时会自动一并安装。组件安装后无需额外配置Tailwind 样式与脚本已随代码落盘开箱即用。AI SDK 实战一个完整的天气应用示例原文档提供了一个端到端示例构建一个有状态stateful的天气应用通过useChat在 UI 中渲染消息中的工具调用。以下代码完整复刻自原文档你可以直接复制运行。前端渲染工具调用app/page.tsxuse client; import { useChat } from ai-sdk/react; import { DefaultChatTransport, type ToolUIPart } from ai; import { Button } from /components/ui/button; import { MessageResponse } from /components/ai-elements/message; import { Tool, ToolContent, ToolHeader, ToolInput, ToolOutput, } from /components/ai-elements/tool; type WeatherToolInput { location: string; units: celsius | fahrenheit; }; type WeatherToolOutput { location: string; temperature: string; conditions: string; humidity: string; windSpeed: string; lastUpdated: string; }; type WeatherToolUIPart ToolUIPart{ fetch_weather_data: { input: WeatherToolInput; output: WeatherToolOutput; }; }; const Example () { const { messages, sendMessage, status } useChat({ transport: new DefaultChatTransport({ api: /api/weather, }), }); const handleWeatherClick () { sendMessage({ text: Get weather data for San Francisco in fahrenheit }); }; const latestMessage messages[messages.length - 1]; const weatherTool latestMessage?.parts?.find( (part) part.type tool-fetch_weather_data, ) as WeatherToolUIPart | undefined; return ( div classNamemax-w-4xl mx-auto p-6 relative size-full rounded-lg border h-[600px] div classNameflex flex-col h-full div classNamespace-y-4 Button onClick{handleWeatherClick} disabled{status ! ready} Get Weather for San Francisco /Button {weatherTool ( Tool defaultOpen{true} ToolHeader typetool-fetch_weather_data state{weatherTool.state} / ToolContent ToolInput input{weatherTool.input} / ToolOutput output{ MessageResponse{formatWeatherResult(weatherTool.output)}/MessageResponse } errorText{weatherTool.errorText} / /ToolContent /Tool )} /div /div /div ); }; function formatWeatherResult(result: WeatherToolOutput): string { return **Weather for ${result.location}** **Temperature:** ${result.temperature} **Conditions:** ${result.conditions} **Humidity:** ${result.humidity} **Wind Speed:** ${result.windSpeed} *Last updated: ${result.lastUpdated}*; } export default Example;要点拆解类型契约WeatherToolUIPart通过泛型把fetch_weather_data工具的input/output类型绑定到ToolUIPart上前端即可获得完整的类型提示。查找工具 partAI SDK 会把工具调用编码为type: tool-fetch_weather_data的 message part用parts.find()取出。组合式布局Tool负责折叠容器ToolHeader渲染头部工具名 状态徽章ToolContent包裹展开区ToolInput展示参数 JSONToolOutput展示结果或错误。默认展开defaultOpen{true}让已完成completed的工具默认展开用户无需点击即可看到结果。后端定义工具并流式返回app/api/weather/route.tsximport { streamText, UIMessage, convertToModelMessages } from ai; import { z } from zod; // Allow streaming responses up to 30 seconds export const maxDuration 30; export async function POST(req: Request) { const { messages }: { messages: UIMessage[] } await req.json(); const result streamText({ model: openai/gpt-4o, messages: await convertToModelMessages(messages), tools: { fetch_weather_data: { description: Fetch weather information for a specific location, parameters: z.object({ location: z.string().describe(The city or location to get weather for), units: z.enum([celsius, fahrenheit]).default(celsius).describe(Temperature units), }), inputSchema: z.object({ location: z.string(), units: z.enum([celsius, fahrenheit]).default(celsius), }), execute: async ({ location, units }) { await new Promise((resolve) setTimeout(resolve, 1500)); const temp units celsius ? Math.floor(Math.random() * 35) 5 : Math.floor(Math.random() * 63) 41; return { location, temperature: ${temp}°${units celsius ? C : F}, conditions: Sunny, humidity: 12%, windSpeed: 35 ${units celsius ? km/h : mph}, lastUpdated: new Date().toLocaleString(), }; }, }, }, }); return result.toUIMessageStreamResponse(); }后端通过streamText定义工具的 Zod 参数校验与execute实现并用toUIMessageStreamResponse()将流式响应直接交给前端DefaultChatTransport消费。inputSchema与parameters分别约束模型看到的 schema与工具接收的 schema这是 AI SDK 工具链路的推荐写法。组件 API 与 Props 详解Tool /PropTypeDefaultDescription...propsReact.ComponentPropstypeof Collapsible-其余所有 props 透传spread给根 Collapsible 组件。Tool本身是薄封装继承 Collapsible 的全部能力因此defaultOpen、open、onOpenChange等属性均可用。在 ZCode 源码 tool.tsx 中其根节点带有group not-prose mb-4 w-full rounded-md border样式保证在 Markdown/富文本场景下不串样式。ToolHeader /PropTypeDefaultDescriptiontitlestring-自定义标题不传时使用从工具类型派生的名称。typeToolUIPart[type]必填工具的类型/名称如tool-database_query。stateToolUIPart[state]必填工具当前状态input-streaming、input-available、output-available、output-error等。toolNamestring-当type为dynamic-tool时必填。classNamestring-附加到头部的 CSS 类。...propsReact.ComponentPropstypeof CollapsibleTrigger-其余 props 透传给 CollapsibleTrigger。源码中的标题派生逻辑tool.tsxconst derivedName type dynamic-tool ? toolName : type.split(-).slice(1).join(-);即静态工具tool-fetch_weather_data会自动显示为fetch_weather_data动态工具如 MCP 动态注册的工具则必须显式传入toolName。ToolContent /PropTypeDefaultDescription...propsReact.ComponentPropstypeof CollapsibleContent-其余 props 透传给 CollapsibleContent。展开/收起时带有淡出与滑动动画见 tool.tsx内容区使用space-y-4 p-4排版。ToolInput /PropTypeDefaultDescriptioninputToolUIPart[input]-传给工具的参数以格式化 JSON 展示。...propsReact.ComponentPropsdiv-其余 props 透传给底层 div。参数区标题固定为Parameters内部通过CodeBlock渲染JSON.stringify(input, null, 2)并带max-h-60 overflow-auto的滚动约束tool.tsx超长参数不会撑爆布局。ToolOutput /PropTypeDefaultDescriptionoutputReact.ReactNode-工具执行结果。errorTextToolUIPart[errorText]-工具执行失败时的错误信息。...propsReact.ComponentPropsdiv-其余 props 透传给底层 div。源码中的输出渲染策略tool.tsx值得重点关注若output与errorText都为空组件直接返回null无错误时字符串输出以json语言的 CodeBlock 展示纯对象输出自动JSON.stringify后入 CodeBlockReact 元素如MessageResponse则原样渲染有错误时只渲染可读的错误文本errorText不再把无效的结构化数据渲染出来——源码注释明确指出这是为避免报错被参数淹没的视觉问题错误态使用bg-destructive/10 text-destructive语义色成功态使用bg-muted/50 text-foreground。状态系统与getStatusBadgeTool组件通过头部徽章Badge可视化工具的 7 种执行状态。原文档提供的getStatusBadge工具函数import { getStatusBadge } from /components/ai-elements/tool; // Returns a Badge with appropriate icon and label const badge getStatusBadge(output-available);源码中的完整状态映射tool.tsx状态徽章标签图标图标颜色input-streamingPendingCircleIcon默认input-availableRunningClockIconanimate-pulse脉冲动画默认approval-requestedAwaiting ApprovalClockIcon黄色approval-respondedRespondedCheckCircleIcon蓝色output-availableCompletedCheckCircleIcon绿色output-deniedDeniedXCircleIcon橙色output-errorErrorXCircleIcon红色可以看到状态徽章不仅是文字标签还配对了语义图标与颜色运行中带脉冲动画、成功为绿色对勾、失败为红色叉号用户无需读文字即可快速感知工具当前所处阶段。四个典型场景示例.agents/skills/ai-elements/scripts/目录提供了 4 个可直接运行的场景脚本分别对应工具生命周期的不同阶段1. 输入流式传输中Pending— tool-input-streaming.tsx模拟web_search工具在参数仍在流式处理时的初始态state: input-streaming、output: undefined此时仅渲染ToolInput展示部分到达的参数如include_snippets、max_results、query。2. 输入就绪、执行中Running— tool-input-available.tsx模拟image_generation工具已收到完整参数prompt、quality、resolution、style并正在执行头部徽章显示 Running。3. 输出可用Completed— tool-output-available.tsx模拟database_query工具执行成功并返回 JSON 结果数组。脚本展示了文档中提到的用法当输出是 JSON 对象时直接用CodeBlock组件以json语言高亮展示参见 tool-output-available.tsx。默认展开以便用户直接看到结果。4. 输出错误Error— tool-output-error.tsx模拟api_request工具因Connection timeout失败state: output-error传入errorText与output: undefined组件默认展开并高亮展示错误信息。综合示例数据库查询工具的完整状态流.agents/skills/ai-elements/scripts/tool.tsx是覆盖面最全的综合演示脚本在一个页面内依次渲染了 7 种状态下的同一个database_query工具input-streamingPending、approval-requestedAwaiting Approval、approval-respondedResponded、input-availableRunning、output-availableCompleted、output-errorError、output-deniedDenied。其中审批相关状态还组合了Confirmation系列组件Confirmation 的ConfirmationTitle、ConfirmationActions等用于渲染允许工具在生产数据库上执行查询这类需要用户确认/拒绝的场景——这正是 Agent 类应用中工具调用权限治理的典型 UI 形态。你可以参考该脚本快速预览组件在各生命周期阶段的表现再针对自己的工具类型逐一适配。类型导出ToolPart同时覆盖静态与动态两种工具 UI part 的联合类型type ToolPart ToolUIPart | DynamicToolUIPart;静态工具AI SDK 预定义的 tools 配置对应ToolUIPart而由 MCP、动态注册机制产生的工具对应DynamicToolUIPart后者需要在ToolHeader上额外提供toolName。该类型同时驱动了statusLabels与statusIcons两张映射表tool.tsx保证任意合法状态都有对应的徽章文案与图标。特性清单与最佳实践综合原文档与源码实现Tool组件具备以下特性可折叠界面一键展开/收起工具调用细节控制对话流中的信息密度状态可视化7 种状态均有专属图标 标签徽章运行中带脉冲动画参数格式化JSON 语法高亮展示输入参数滚动区域防溢出结果与错误分离处理成功态渲染结构化结果失败态只展示可读错误文本可组合结构Tool/ToolHeader/ToolContent/ToolInput/ToolOutput自由组合可灵活嵌入MessageResponse、CodeBlock、Confirmation等组件无障碍与交互基于 CollapsibleTrigger/CollapsibleContent 构建支持键盘导航与屏幕阅读器样式一致使用语义色与cn合并 className天然匹配 shadcn/ui 设计体系默认展开已完成工具completed / error 状态默认展开结果立即可见提升 UX。实践建议在 ZCode 这类 Agent 场景中工具调用的成败与中间态频繁出现建议将Tool与 AI SDK 的useChat结合使用——前端按part.type过滤出工具 part按state渲染对应阶段后端配合streamText与 Zod schema 保证输入/输出类型契约一致。由于组件代码就在/components/ai-elements/tool.tsx中你还可以按需调整折叠动画、徽章配色或输出渲染逻辑将工具调用展示深度定制为符合产品气质的形态。延伸阅读完整安装与排查指南见 SKILL.md含 shadcn/ui 样式未生效、/路径别名缺失等常见问题的解决办法其他可组合组件如Confirmation、Message、CodeBlock的文档位于 references 目录组件完整实现见 packages/ui/src/components/ai-elements/tool.tsx。【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考