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

• 后端
• 前端
• CRM
• 人工智能
• AI Agent

本篇文章聚焦 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-elements@latest add stack-trace

根据 .agents/skills/ai-elements/SKILL.md 的说明，如果你的项目使用 pnpm 或 bun 作为包管理器，请使用对应的 runner：

# pnpm pnpm dlx ai-elements@latest add stack-trace # bun bunx --bun ai-elements@latest 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时渲染StackTrace：

"use 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 className="max-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 → Error（ErrorType + ErrorMessage）→ Actions（CopyButton + ExpandButton）→ Content → Frames逐层组合。这种结构与 ai-elements 其他组件（如Message、Tool、Sandbox）保持一致，既保证了布局灵活性，也便于按需增删子元素。

后端：工具执行并返回堆栈

在api/run-code/route.ts中，使用 Vercel AI SDK 定义runCode工具，通过eval执行代码，捕获异常后返回error.stack：

import { 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 />（根组件）

<StackTraceHeader />

<StackTraceError />

<StackTraceErrorType />

<StackTraceErrorMessage />

<StackTraceActions />

<StackTraceCopyButton />

<StackTraceExpandButton />

<StackTraceContent />

<StackTraceFrames />

设计要点与扩展建议

从 Props 契约可以提炼出几个值得关注的设计特征：

1. 完全可控的展开状态：open/defaultOpen/onOpenChange三件套同时支持受控与非受控两种用法，默认折叠（defaultOpen=false）符合"错误摘要优先"的交互直觉，而在工具执行失败的场景（如示例一）则常配合defaultOpen直接展开，让用户第一时间看到错误详情。

2. 基于 Radix Collapsible 的可访问性：StackTraceHeader透传CollapsibleTrigger属性、StackTraceContent透传CollapsibleContent属性，这意味着折叠交互天然继承 Radix 的键盘导航与屏幕阅读器支持，无需额外实现。

3. 组件代码即源码：由于 ai-elements 采用"代码复制进项目"的分发模式，安装后的components/ai-elements/stack-trace.tsx是可以直接打开阅读和修改的。如果想调整内部帧的判定规则（例如额外过滤webpack帧）、更换复制成功图标或改变红色高亮的样式，直接修改该文件即可，这正是 shadcn 生态"以源码为组件"理念的体现（参见 SKILL.md 中关于"组件作为代码库一部分、可打开查看或自定义修改"的说明）。

4. 与错误生态的衔接：trace输入的是标准 Node.jsError.stack字符串，因此不仅适用于 AI 工具调用场景，任何前端捕获的异常堆栈（如 React 错误边界、异步请求错误）都可以直接传入复用，让全站错误展示风格统一。

小结

StackTrace是 ai-elements 面向"AI 生成代码"场景的标准错误展示组件，与Sandbox（代码与输出容器）、CodeBlock（语法高亮代码块）形成完整配套。通过本文的安装命令、前后端完整示例、三个示例脚本以及全部 Props 契约，你可以快速在 AI 应用中落地一个具备语法高亮、帧折叠、一键复制、路径跳转能力的错误堆栈展示模块，并依据项目需要自由定制其行为与样式。更详细的组件清单与安装指引可继续查阅 .agents/skills/ai-elements/SKILL.md 及其references/目录下的各组件文档。

• 后端
• 前端
• CRM
• 人工智能
• AI Agent