在 AI 应用中构建 Stack Trace 错误展示组件：ai-elements StackTrace 组件实战指南

后端前端CRM人工智能AI Agent【免费下载链接】crmComp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.项目地址https://gitcode.com/gh_mirrors/crm48/crm点击查看免费下载本篇文章聚焦 Comp AI CRM 仓库中.agents/skills/ai-elements技能集提供的StackTrace组件讲解如何将 JavaScript/Node.js 错误堆栈格式化为带有语法高亮、可折叠帧、可点击文件路径的 React 展示组件并完整演示其在 AI SDK 工具调用场景下的接入方式。读完本文你将掌握该组件的安装、前后端集成、全部 Props 契约以及通过showInternalFrames、defaultOpen等参数定制错误展示体验的实战方法。组件概览为 AI 生成代码的错误可视化而生StackTrace组件是 ai-elements 组件库中专门用于错误展示的组件它的核心能力是接收一段原始的 JavaScript/Node.js 错误堆栈字符串将其解析并渲染为结构化的可视化界面。它通常与Sandbox、CodeBlock等组件配合使用——当 AI 生成代码执行失败时把Error.stack呈现给用户帮助开发者快速定位问题。从仓库的技能文档描述来看StackTrace具备以下关键能力见 .agents/skills/ai-elements/references/stack-trace.md解析标准 JavaScript/Node.js 堆栈跟踪格式以红色高亮错误类型error type淡化内部帧node_modules、node:路径可折叠内容并带有平滑动画一键复制完整堆栈到剪贴板可点击的文件路径并携带行号/列号。在 ai-elements 的组件体系中StackTrace是错误展示的标准件。仓库中的 Sandbox 组件文档 明确说明其设计意图是与CodeBlock配合展示代码、与StackTrace配合展示错误这印证了它在 AI 沙箱执行、代码生成工具等场景中的典型定位。安装StackTrace是 ai-elements 组件库的一部分通过 ai-elements CLI 一键安装。ai-elements 是基于 shadcn/ui 构建的组件库与自定义 registry安装命令会把组件源码直接集成到你的项目代码中默认路径为/components/ai-elements/而非封装为不可见的库依赖——这意味着你可以像阅读自己的代码一样查看它的实现细节。在项目根目录package.json所在目录执行npx ai-elementslatest add stack-trace根据 .agents/skills/ai-elements/SKILL.md 的说明如果你的项目使用 pnpm 或 bun 作为包管理器请使用对应的 runner# pnpm pnpm dlx ai-elementslatest add stack-trace # bun bunx --bun ai-elementslatest add stack-trace安装前提条件Node.js 18 或更高版本已安装 AI SDK 的 Next.js 项目已安装 shadcn/ui若未安装CLI 会自动安装项目中tsconfig.json配置了/*路径别名如/*: [./*]否则会出现 module not found 导入错误。安装完成后组件会出现在/components/ai-elements/stack-trace路径下Tailwind CSS 样式已自动集成无需额外配置即可使用。与 AI SDK 集成完整的前后端示例StackTrace组件的典型应用场景是AI 通过工具调用执行代码当代码执行失败时把捕获的Error.stack返回给前端由StackTrace组件格式化展示。下面展示 stack-trace.md 文档中的完整接入流程。前端通过 useChat 渲染工具错误在app/page.tsx中使用 AI SDK 的useChathook 获取消息流从message.parts中筛选tool-invocation类型的部分当工具名为runCode且结果中包含error时渲染StackTraceuse client; import { useChat } from ai-sdk/react; import { StackTrace, StackTraceHeader, StackTraceError, StackTraceErrorType, StackTraceErrorMessage, StackTraceActions, StackTraceCopyButton, StackTraceExpandButton, StackTraceContent, StackTraceFrames, } from /components/ai-elements/stack-trace; export default function Page() { const { messages } useChat({ api: /api/run-code, }); return ( div classNamemax-w-4xl mx-auto p-6 {messages.map((message) { const toolInvocations message.parts?.filter( (part) part.type tool-invocation ); return toolInvocations?.map((tool) { if (tool.toolName runCode tool.result?.error) { return ( StackTrace key{tool.toolCallId} trace{tool.result.error} defaultOpen StackTraceHeader StackTraceError StackTraceErrorType / StackTraceErrorMessage / /StackTraceError StackTraceActions StackTraceCopyButton / StackTraceExpandButton / /StackTraceActions /StackTraceHeader StackTraceContent StackTraceFrames / /StackTraceContent /StackTrace ); } return null; }); })} /div ); }这段代码展示了StackTrace的复合组件compound component设计外层StackTrace接收原始堆栈字符串内部由Header → ErrorErrorType ErrorMessage→ ActionsCopyButton ExpandButton→ Content → Frames逐层组合。这种结构与 ai-elements 其他组件如Message、Tool、Sandbox保持一致既保证了布局灵活性也便于按需增删子元素。后端工具执行并返回堆栈在api/run-code/route.ts中使用 Vercel AI SDK 定义runCode工具通过eval执行代码捕获异常后返回error.stackimport { streamText, tool } from ai; import { z } from zod; export async function POST(req: Request) { const { messages } await req.json(); const result streamText({ model: openai/gpt-4o, messages, tools: { runCode: tool({ description: Execute JavaScript code and return any errors, parameters: z.object({ code: z.string(), }), execute: async ({ code }) { try { // Execute code in sandbox eval(code); return { success: true }; } catch (error) { return { error: (error as Error).stack }; } }, }), }, }); return result.toDataStreamResponse(); }关键点在于execute函数中捕获异常后返回的是(error as Error).stack——这正是StackTrace组件的traceprop 期望的输入格式。前端通过tool.result?.error拿到这段堆栈字符串并交给组件解析渲染从而形成AI 写代码 → 沙箱执行 → 失败堆栈 → 格式化展示的完整闭环。说明示例中的eval仅为演示组件用法生产环境应将代码执行放入隔离沙箱可参考仓库中 Sandbox 组件文档 的设计思路它正是为AI 生成代码 执行输出场景准备的容器组件。三个实战示例从默认展开到隐藏内部帧仓库的scripts/目录提供了三个可直接运行的示例文件覆盖了StackTrace最常用的三种展示形态可作为接入时的参照模板。示例一默认展开 文件路径点击回调scripts/stack-trace.tsx 演示了defaultOpen与onFilePathClick的配合使用。示例中的样本堆栈是一个典型的 React 运行时错误TypeError: Cannot read properties of undefined (reading map) at UserList (/app/components/UserList.tsx:15:23) at renderWithHooks (node_modules/react-dom/cjs/react-dom.development.js:14985:18) ...实现要点onFilePathClick回调接收(path: string, line: number, col: number)三个参数可用于在 IDE 中打开对应文件示例中通过console.log打印定位信息onCopy回调在复制成功后触发可用于埋点或 Toast 提示const handleCopy () { console.log(Stack trace copied); };组件包裹结构为StackTrace(defaultOpen, onFilePathClick, trace) → Header → Error → Actions → Content → Frames与上文的工具调用示例完全一致。示例二默认折叠scripts/stack-trace-collapsed.tsx 演示了折叠态通过defaultOpen{false}让组件默认收起用户点击 Header 区域后再展开帧列表。这在错误信息较长、不想抢占页面主视觉时非常有用——Header 中仍然会显示错误类型与错误消息用户可以根据摘要决定是否展开完整堆栈。示例三隐藏内部帧scripts/stack-trace-no-internal.tsx 演示了StackTraceFrames的showInternalFrames{false}用法StackTraceContent StackTraceFrames showInternalFrames{false} / /StackTraceContent当设置为false时来自node_modules与node:路径的内部帧会被过滤掉只保留业务代码帧如/app/src/App.tsx:42:5帮助开发者快速聚焦到真正的问题代码避免被 React 运行时内部调用栈淹没。组件 Props 完整参考StackTrace采用复合组件结构每个子组件都有独立的 Props 契约。以下为 stack-trace.md 文档中完整的 Props 表格StackTrace /根组件Prop类型默认值说明tracestring-待解析和展示的原始堆栈字符串openboolean-受控展开状态defaultOpenbooleanfalse内容是否默认展开onOpenChange(open: boolean) void-展开状态变化时的回调onFilePathClick(path: string, line?: number, column?: number) void-点击文件路径时的回调接收文件路径、行号和列号childrenReact.ReactNode-子元素StackTraceHeader、StackTraceContent 等classNamestring-附加 CSS 类名...propsReact.HTMLAttributesHTMLDivElement-其余属性透传到根 divStackTraceHeader /Prop类型默认值说明childrenReact.ReactNode-头部内容通常为 StackTraceError 与 StackTraceActionsclassNamestring-附加 CSS 类名...propsReact.ComponentPropstypeof CollapsibleTrigger-其余属性透传到 CollapsibleTriggerStackTraceError /Prop类型默认值说明childrenReact.ReactNode-错误内容通常为 StackTraceErrorType 与 StackTraceErrorMessageclassNamestring-附加 CSS 类名...propsReact.HTMLAttributesHTMLDivElement-其余属性透传到容器 divStackTraceErrorType /Prop类型默认值说明childrenReact.ReactNode-自定义内容默认显示解析出的错误类型如TypeErrorclassNamestring-附加 CSS 类名...propsReact.HTMLAttributesHTMLSpanElement-其余属性透传到 span 元素StackTraceErrorMessage /Prop类型默认值说明childrenReact.ReactNode-自定义内容默认显示解析出的错误消息classNamestring-附加 CSS 类名...propsReact.HTMLAttributesHTMLSpanElement-其余属性透传到 span 元素StackTraceActions /Prop类型默认值说明childrenReact.ReactNode-操作按钮通常为 StackTraceCopyButton 与 StackTraceExpandButtonclassNamestring-附加 CSS 类名...propsReact.HTMLAttributesHTMLDivElement-其余属性透传到容器 divStackTraceCopyButton /Prop类型默认值说明onCopy() void-复制成功后触发的回调onError(error: Error) void-复制失败时触发的回调timeoutnumber2000复制成功状态的展示时长毫秒childrenReact.ReactNode-按钮自定义内容默认为复制/勾选图标classNamestring-附加 CSS 类名...propsReact.ComponentPropstypeof Button-其余属性透传到底层 shadcn/ui Button 组件StackTraceExpandButton /Prop类型默认值说明classNamestring-附加 CSS 类名...propsReact.HTMLAttributesHTMLDivElement-其余属性透传到容器 divStackTraceContent /Prop类型默认值说明maxHeightnumber400内容区域最大高度px超出后启用滚动childrenReact.ReactNode-展示内容通常为 StackTraceFramesclassNamestring-附加 CSS 类名...propsReact.ComponentPropstypeof CollapsibleContent-其余属性透传到 CollapsibleContentStackTraceFrames /Prop类型默认值说明showInternalFramesbooleantrue是否显示内部帧node_modules、node:路径classNamestring-附加 CSS 类名...propsReact.HTMLAttributesHTMLDivElement-其余属性透传到容器 div设计要点与扩展建议从 Props 契约可以提炼出几个值得关注的设计特征完全可控的展开状态open/defaultOpen/onOpenChange三件套同时支持受控与非受控两种用法默认折叠defaultOpenfalse符合错误摘要优先的交互直觉而在工具执行失败的场景如示例一则常配合defaultOpen直接展开让用户第一时间看到错误详情。基于 Radix Collapsible 的可访问性StackTraceHeader透传CollapsibleTrigger属性、StackTraceContent透传CollapsibleContent属性这意味着折叠交互天然继承 Radix 的键盘导航与屏幕阅读器支持无需额外实现。组件代码即源码由于 ai-elements 采用代码复制进项目的分发模式安装后的components/ai-elements/stack-trace.tsx是可以直接打开阅读和修改的。如果想调整内部帧的判定规则例如额外过滤webpack帧、更换复制成功图标或改变红色高亮的样式直接修改该文件即可这正是 shadcn 生态以源码为组件理念的体现参见 SKILL.md 中关于组件作为代码库一部分、可打开查看或自定义修改的说明。与错误生态的衔接trace输入的是标准 Node.jsError.stack字符串因此不仅适用于 AI 工具调用场景任何前端捕获的异常堆栈如 React 错误边界、异步请求错误都可以直接传入复用让全站错误展示风格统一。小结StackTrace是 ai-elements 面向AI 生成代码场景的标准错误展示组件与Sandbox代码与输出容器、CodeBlock语法高亮代码块形成完整配套。通过本文的安装命令、前后端完整示例、三个示例脚本以及全部 Props 契约你可以快速在 AI 应用中落地一个具备语法高亮、帧折叠、一键复制、路径跳转能力的错误堆栈展示模块并依据项目需要自由定制其行为与样式。更详细的组件清单与安装指引可继续查阅 .agents/skills/ai-elements/SKILL.md 及其references/目录下的各组件文档。赞分享后端前端CRM人工智能AI Agent【免费下载链接】crmComp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.项目地址https://gitcode.com/gh_mirrors/crm48/crm点击查看免费下载相关推荐在 ZCode 的 ai-elements 技能中构建 StackTrace 错误堆栈展示组件基于 AI SDK 的完整集成指南在 ZCode 的 ai elements 技能中构建 StackTrace 错误堆栈展示组件基于 AI SDK 的完整集成指南 导读 本文围绕 ZCodeZCode 集成 AI Elements Agent 组件在 React 应用中构建可组合的 AI Agent 配置展示界面ZCode 集成 AI Elements Agent 组件在 React 应用中构建可组合的 AI Agent 配置展示界面 导读 本指南以 ZCode 仓库Beekeeper Studio 完全指南基于 Electron 与 Vue.js 的开源跨平台 SQL 编辑器与数据库管理工具Beekeeper Studio 完全指南基于 Electron 与 Vue.js 的开源跨平台 SQL 编辑器与数据库管理工具 Beekeeper Stud后端前端CRM人工智能AI Agent上一篇掌握WinUI 3与C/WinRT构建现代化硬盘监测工具DiskInfo的实战指南下一篇Rhino.Inside® Revit颠覆BIM参数化设计的终极解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考