【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址https://gitcode.com/gh_mirrors/zco/ZCode点击查看免费下载本文围绕 ZCode 仓库内置的 AI Elements 技能库中的Sandbox组件展开讲解如何在 AI 聊天界面中以可折叠容器 状态徽章 Code/Output 双标签页的结构展示 AI 生成的代码及其执行结果。读者将掌握 Sandbox 及其子组件的完整组合方式、与 AI SDKToolUIPart工具状态的无缝对接、与CodeBlock、StackTrace的协作模式以及每个组件的 Props 契约与底层实现细节。Sandbox 是什么Sandbox是一个可折叠的容器组件专门用于在聊天界面中展示 AI 生成的代码与对应的执行输出。它解决了 AI 编程场景中的一个典型展示难题一段由模型生成的代码、它在沙箱环境中的运行结果日志或报错堆栈往往体积较大直接平铺在对话流中既占空间又难以阅读。它的核心设计是一个外壳 头部状态 双视图标签页可折叠外壳整体基于 shadcn/ui 的Collapsible支持平滑展开/收起动画状态徽章头部展示当前执行状态Pending、Running、Completed、Error 等让用户一眼判断进度双标签页Code代码视图与Output输出视图之间一键切换协作组件代码视图配合CodeBlock实现语法高亮与复制输出视图配合StackTrace展示格式化错误堆栈。在 ZCode 仓库中该组件源自 vercel/ai-elements 项目经 ZCode 本地化集成与格式适配后落地为真实可用的源码组件实现位于 packages/ui/src/components/ai-elements/sandbox.tsx配套示例见 .agents/skills/ai-elements/scripts/sandbox.tsx本文所依据的参考文档位于 .agents/skills/ai-elements/references/sandbox.md。安装Sandbox 组件通过 ai-elements 的组件注册表按需添加npx ai-elementslatest add sandbox运行后组件源码会被下载并集成到项目配置的组件目录默认/components/ai-elements/下。由于 Sandbox 依赖 shadcn/ui 的Collapsible与Tabs原语安装命令会一并解析并加入这些依赖。若项目尚未安装 shadcn/uiCLI 也会自动补齐。注意根据项目的包管理器选择对应的执行器例如使用 pnpm 的项目可替换为pnpm dlx ai-elementslatest使用 Bun 的项目可替换为bunx --bun ai-elementslatest。核心功能Sandbox 组件提供以下开箱即用的能力可折叠容器展开/收起带平滑动画状态徽章展示执行状态Pending、Running、Completed、ErrorCode 与 Output 双标签页视图基于CodeBlock的语法高亮代码展示一键复制按钮便于分享代码与 AI SDK 工具状态tool state模式天然集成。与 AI SDK 的集成用法Sandbox 直接消费 AI SDK 的ToolUIPart类型。在流式工具调用场景中toolPart.state会随执行进度变化如input-streaming→input-available→output-availableSandbox 头部据此自动切换状态徽章toolPart.input提供待展示的代码toolPart.output提供执行输出日志。以下是一个完整的CodeSandbox组件示例源自原文档的components/code-sandbox.tsxuse client; import type { ToolUIPart } from ai; import { Sandbox, SandboxContent, SandboxHeader, SandboxTabContent, SandboxTabs, SandboxTabsBar, SandboxTabsList, SandboxTabsTrigger, } from /components/ai-elements/sandbox; import { CodeBlock } from /components/ai-elements/code-block; type CodeSandboxProps { toolPart: ToolUIPart; }; export const CodeSandbox ({ toolPart }: CodeSandboxProps) { const code toolPart.input?.code ?? ; const output toolPart.output?.logs ?? ; return ( Sandbox SandboxHeader state{toolPart.state} title{toolPart.input?.filename ?? code.tsx} / SandboxContent SandboxTabs defaultValuecode SandboxTabsBar SandboxTabsList SandboxTabsTrigger valuecodeCode/SandboxTabsTrigger SandboxTabsTrigger valueoutputOutput/SandboxTabsTrigger /SandboxTabsList /SandboxTabsBar SandboxTabContent valuecode CodeBlock code{code} languagetsx / /SandboxTabContent SandboxTabContent valueoutput CodeBlock code{output} languagelog / /SandboxTabContent /SandboxTabs /SandboxContent /Sandbox ); };关键点解读状态驱动SandboxHeader的state属性直接绑定toolPart.state无需手动维护 UI 状态组合式结构外壳、头部、内容、标签页四层组件按固定层级嵌套符合可组合、可替换的设计哲学默认激活标签SandboxTabs通过defaultValuecode指定默认展示代码视图。源码级实现分析在 ZCode 仓库中Sandbox 的实现位于 packages/ui/src/components/ai-elements/sandbox.tsx。从源码结构可以梳理出以下几个关键设计基于 Collapsible 的可折叠外壳Sandbox根组件直接包装 shadcn/ui 的Collapsible并通过cn()合并样式类export const Sandbox ({ className, ...props }: SandboxRootProps) ( Collapsible className{cn(not-prose group mb-4 w-full overflow-hidden rounded-md border, className)} defaultOpen {...props} / );值得注意的细节默认设置了defaultOpen默认展开、group供子元素使用 group 状态选择器、not-prose避免与 Markdown 排版样式冲突以及圆角边框的外观。头部状态徽章 折叠触发器SandboxHeader内部是一个CollapsibleTrigger左侧依次为代码图标lucide 的Code、标题文本和状态徽章右侧为随展开状态旋转 180° 的ChevronDownIconexport const SandboxHeader ({ className, title, state, ...props }: SandboxHeaderProps) ( CollapsibleTrigger className{cn(flex w-full items-center justify-between gap-4 p-3, className)} {...props} div classNameflex items-center gap-2 Code classNamesize-4 text-muted-foreground / span classNamefont-medium text-ui-base{title}/span {getStatusBadge(state)} /div ChevronDownIcon classNamesize-4 text-muted-foreground transition-transform group-data-[stateopen]:rotate-180 / /CollapsibleTrigger );状态徽章的真实映射getStatusBadge并非 Sandbox 自身实现而是从 packages/ui/src/components/ai-elements/tool.tsx 中导入的共享工具函数sandbox.tsx 第 16 行。它内部维护了两张映射表状态ToolUIPart[state]徽章文案图标lucide-reactinput-streamingPendingCircleIconinput-availableRunningClockIcon带animate-pulse脉冲动画output-availableCompletedCheckCircleIcon绿色output-errorErrorXCircleIcon红色approval-requestedAwaiting ApprovalClockIcon黄色approval-respondedRespondedCheckCircleIcon蓝色output-deniedDeniedXCircleIcon橙色从源码结构可以推断Sandbox 复用了工具调用的状态语义Pending表示模型仍在生成输入代码Running表示代码已就绪、执行中Completed表示执行成功并产出输出Error表示执行抛出异常。因此原文档提到的状态徽章展示执行状态Pending、Running、Completed、Error本质上就是ToolUIPart状态机在 UI 层的直接映射。内容区与标签页的样式细节SandboxContent包装CollapsibleContent通过 Tailwind 动画类实现展开/收起时的淡出、滑动过渡SandboxTabs包装 shadcn/ui 的Tabs并移除间隙gap-0SandboxTabsBar是一个带上下边框的 flex 容器SandboxTabsList去掉默认圆角与背景实现与代码块无缝衔接的极简标签栏SandboxTabsTrigger采用底部边框高亮border-b-2指示激活态激活时文本切换为前景色SandboxTabContent清除顶部外边距并统一字号。组件 Props 契约以下表格完整继承自参考文档 .agents/skills/ai-elements/references/sandbox.md并对照 packages/ui/src/components/ai-elements/sandbox.tsx 源码核实。Sandbox /Prop类型默认值说明...propsReact.ComponentPropstypeof Collapsible-其余任意 props 透传给底层 Collapsible 组件。源码默认设置defaultOpen、not-prose、group、圆角边框样式。SandboxHeader /Prop类型默认值说明titlestringundefined头部显示的标题如文件名。stateToolUIPart[state]必填当前执行状态用于展示对应的状态徽章。classNamestring-追加到头部的 CSS 类。SandboxContent /Prop类型默认值说明...propsReact.ComponentPropstypeof CollapsibleContent-其余任意 props 透传给 CollapsibleContent内含展开/收起动画样式。SandboxTabs /Prop类型默认值说明...propsReact.ComponentPropstypeof Tabs-其余任意 props 透传给底层 Tabs 组件如defaultValue、value、onValueChange。SandboxTabsBar /Prop类型默认值说明...propsReact.HTMLAttributesHTMLDivElement-其余任意 props 透传给容器 div默认带上下边框。SandboxTabsList /Prop类型默认值说明...propsReact.ComponentPropstypeof TabsList-其余任意 props 透传给底层 TabsList默认去除圆角、背景与内边距。SandboxTabsTrigger /Prop类型默认值说明...propsReact.ComponentPropstypeof TabsTrigger-其余任意 props 透传给底层 TabsTrigger激活态以底部 2px 主色边框标识。SandboxTabContent /Prop类型默认值说明...propsReact.ComponentPropstypeof TabsContent-其余任意 props 透传给底层 TabsContent默认清除顶部外边距。整体来看所有 Sandbox 子组件都遵循尽可能透传原生属性的扩展策略——它们不屏蔽底层组件能力而是作为薄封装层这与 ai-elements 技能库的整体可扩展性设计见 .agents/skills/ai-elements/SKILL.md保持一致。输出视图的两种形态日志与错误堆栈Sandbox 的 Output 标签页内容由调用方决定。参考文档将其设计为与CodeBlock搭配展示日志而与StackTrace搭配展示错误。仓库配套示例 .agents/skills/ai-elements/scripts/sandbox.tsx 演示了完整的四态切换当状态为output-error时渲染StackTrace含错误类型、错误信息、复制按钮、展开按钮与堆栈帧列表其余状态渲染CodeBlock。相关协作组件的独立参考文档同样收录在本技能库中.agents/skills/ai-elements/references/code-block.mdCodeBlock提供 Shiki 语法高亮、可选行号、复制到剪贴板、深浅主题自动切换与语言选择器其CodeBlockCopyButton支持onCopy、onError回调和timeout默认 2000ms的复制状态时长.agents/skills/ai-elements/references/stack-trace.mdStackTrace解析标准 JavaScript/Node.js 堆栈格式红色高亮错误类型、淡化node_modules与node:内部帧、支持可点击的文件路径携带行号/列号回调与默认折叠/展开控制。一个典型的渲染分支写法如下结构示意SandboxTabContent valueoutput {state output-error ? ( StackTrace trace{errorTrace} defaultOpen {/* StackTraceHeader / StackTraceError / StackTraceFrames 等 */} /StackTrace ) : ( CodeBlock code{logs} languagelog CodeBlockCopyButton / /CodeBlock )} /SandboxTabContent从示例脚本的数据结构可以推断output-available状态对应正常日志如程序打印的质数列表output-error状态对应带堆栈帧的异常字符串——Sandbox 因此能够在同一个容器内平滑地从成功结果切换到失败详情无需跳转视图。完整示例四态演示沙箱仓库中的 .agents/skills/ai-elements/scripts/sandbox.tsx 是一个可直接运行的交互式演示页面它内置了一段 Python 质数筛法代码calculate_primes并为input-streaming、input-available、output-available、output-error四种状态分别准备了展示内容生成中的占位文本、真实代码、成功日志、TypeError堆栈页面顶部提供一组状态切换按钮点击即可观察 Sandbox 在完整生命周期中的渲染变化。该示例还演示了两个实用的细节流式生成占位input-streaming状态下代码视图显示# Generating code...模拟模型生成过程中的骨架占位空输出兜底outputs映射表中input-available与input-streaming的输出为undefined渲染时以空字符串兜底避免空白视图报错。小结Sandbox是 AI 聊天界面中代码生成 → 执行 → 输出闭环的标准展示容器。通过本文的拆解可以看到它的价值不仅在于可折叠与双标签页的交互形态更在于与 AI SDKToolUIPart状态机的深度绑定——状态徽章、流式占位、错误堆栈切换全部由工具状态驱动无需额外状态管理。在 ZCode 中它的真实实现packages/ui/src/components/ai-elements/sandbox.tsx完整保留了 ai-elements 的组合式架构并通过共享的getStatusBadge与工具调用展示体系保持一致是构建 AI Agent 对话界面时可复用的高质量基础组件。赞分享【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址https://gitcode.com/gh_mirrors/zco/ZCode点击查看免费下载相关推荐ZCode 集成 ai-elements Snippet 组件终端命令与短代码的内联展示及复制实战ZCode 集成 ai elements Snippet 组件终端命令与短代码的内联展示及复制实战 Snippet 是 ZCode 内置 ai element从安装到源码用 ZCode 的 ai-elements Message 组件套件构建 AI 聊天界面从安装到源码用 ZCode 的 ai elements Message 组件套件构建 AI 聊天界面 导读 Message 是 ZCode 仓库内嵌的 aiZotero插件安全管理通过zotero-addons验证与安装可信扩展Zotero插件安全管理通过zotero addons验证与安装可信扩展 Zotero作为一款强大的文献管理工具其扩展性很大程度上依赖于各类插件。然而随意插件系统桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考