企业官网建设流程全解析

• 人工智能
• 大模型
• 代码智能体
• AI Agent
• 桌面应用
• 后端
• 前端
• CLI

导读

本文围绕 ZCode 仓库内.agents/skills/ai-elements/references/task.md文档，深入讲解Task组件——一个用于展示 AI 工作流进度的可折叠任务列表组件。它由主容器Task、可点击的TaskTrigger头部与可折叠的TaskContent内容区组成，配合TaskItem、TaskItemFile可完整渲染任务进度、状态与关联文件。读完本文，你将掌握如何通过npx ai-elements@latest add task安装组件，如何用 AI SDK 的experimental_generateObject/streamObject驱动结构化任务数据流，以及每个子组件的 Props 语义与扩展方式，并看到 ZCode 仓库中的本地化实现源码。

背景：AI Elements 与 ZCode 的集成方式

SKILL.md 说明，AI Elements 是构建在 shadcn/ui 之上的组件库与自定义 registry，用于快速搭建 AI 原生应用界面。ZCode 仓库将其以“技能 + 本地组件”的形式集成：

• 技能文档位于.agents/skills/ai-elements/，其中references/task.md是Task组件的官方参考文档；
• 对应示例代码位于 scripts/task.tsx；
• 本地化后的组件实现在 packages/ui/src/components/ai-elements/task.tsx；
• 出处与许可信息记录在根目录 THIRD-PARTY-NOTICES.md，确认ai-elements采用 Apache-2.0 许可。

注意：SKILL.md 明确指出，references/ 中出现的scripts/路径是指向本技能目录（.agents/skills/ai-elements/scripts/）内的示例文件，而非仓库根目录的scripts/，它们只是组件示例，不是已安装的应用功能。

Task 组件是什么

Task是一个可折叠的任务列表组件，用于展示 AI 工作流进度，带状态指示器和可选描述。它由以下部分组成：

• Task：主容器，负责折叠状态管理；
• TaskTrigger：可点击的头部区域，展示任务标题；
• TaskContent：可折叠的内容区，承载任务明细；
• TaskItem：内容区内的单项任务行；
• TaskItemFile：文件类型的单项展示，通常配合图标与文件名使用。

本地实现剖析

ZCode 的 packages/ui/src/components/ai-elements/task.tsx 给出了全部源码：

export const Task = ({ defaultOpen = true, className, ...props }: TaskProps) => ( <Collapsible className={cn("flex flex-col gap-1", className)} defaultOpen={defaultOpen} {...props} /> );

• Task基于 shadcn/ui 的Collapsible实现，默认defaultOpen=true；
• TaskTrigger使用CollapsibleTrigger asChild将触发行为挂载到自定义标题行上，标题行包含搜索图标、标题文本与旋转箭头（展开时rotate-180）；
• TaskContent使用CollapsibleContent，内层通过左边框竖线与缩进呈现层级关系；
• TaskItem、TaskItemFile均为普通div扩展（ComponentProps<"div">），TaskItemFile带有边框与bg-secondary的胶囊样式。

底层的 collapsible.tsx 基于radix-ui的Collapsible原语封装，TaskContent的展开/收起动画由data-[state=open]/data-[state=closed]驱动的关键帧动画实现，并显式禁用 CSS transition 以避免拖拽窗口时的非合成动画问题。

安装

与 AI Elements 其它组件一致，通过 CLI 添加到项目：

npx ai-elements@latest add task

安装前确保满足前置条件（源自 SKILL.md）：

• Node.js 18 或更高版本；
• 已安装 AI SDK 的 Next.js 项目；
• 已安装 shadcn/ui（未安装时 CLI 会自动安装）；
• 推荐使用pnpm dlx ai-elements@latest或bunx --bun ai-elements@latest等与项目packageManager匹配的包管理器 runner。

安装后组件代码位于@/components/ai-elements/目录（或你在 components.json 中配置的目录），可直接当作普通 React 组件使用，代码完全属于你的项目，可自由定制。

与 AI SDK 结合：构建 Mock 异步编程 Agent

task.md给出了一个完整示例：用 AI SDK 的experimental_generateObject/useObject构建一个“Mock 异步编程 Agent”，实时生成并展示开发任务工作流。

前端组件

在app/page.tsx中添加如下组件（完整代码见 task.md）：

"use client"; import { experimental_useObject as useObject } from "@ai-sdk/react"; import { Task, TaskItem, TaskItemFile, TaskTrigger, TaskContent, } from "@/components/ai-elements/task"; import { tasksSchema } from "@/app/api/task/route";

关键点：

• 通过useObject({ api: "/api/agent", schema: tasksSchema })建立与后端的结构化对象流连接，返回object、submit与isLoading；
• iconMap将react、typescript、javascript、css、html、json、markdown等文件类型映射到@icons-pack/react-simple-icons的图标组件及对应品牌色；
• renderTaskItem根据item.type === "file"决定渲染普通文本还是带文件图标与文件名的TaskItemFile；
• 每个任务用<Task defaultOpen={taskIndex === 0}>渲染——第一个任务默认展开，后续任务默认收起；<TaskTrigger title={task.title || "Loading..."} />展示标题；<TaskContent>内渲染TaskItem列表；
• 加载态处理：isLoading && !object时显示 "Generating tasks..." 占位文本。

后端路由

在app/api/agent.ts中添加如下路由（完整代码见 task.md）：

import { streamObject } from "ai"; import { z } from "zod"; export const taskItemSchema = z.object({ type: z.enum(["text", "file"]), text: z.string(), file: z.object({ name: z.string(), icon: z.string(), color: z.string().optional(), }).optional(), }); export const taskSchema = z.object({ title: z.string(), items: z.array(taskItemSchema), status: z.enum(["pending", "in_progress", "completed"]), }); export const tasksSchema = z.object({ tasks: z.array(taskSchema), }); export const maxDuration = 30; export async function POST(req: Request) { const { prompt } = await req.json(); const result = streamObject({ model: "openai/gpt-4o", schema: tasksSchema, prompt: `You are an AI assistant that generates realistic development task workflows. ...`, }); return result.toTextStreamResponse(); }

要点说明：

• 三段 Zod Schema 定义了数据契约：任务项（文本或文件）、任务（标题 + 明细 + 状态）、任务列表；
• status字段预留了pending/in_progress/completed三种状态，对应组件的状态指示器能力；
• streamObject将模型输出按 schema 约束流式解析，toTextStreamResponse()把结构化流以文本流响应返回前端；
• maxDuration = 30表示允许流式响应最长 30 秒（Vercel 平台的约定）；
• prompt 中要求生成 3-4 个任务、每个任务 4-6 个明细项，且状态从 pending 到 in_progress 再到 completed 递进，确保输出符合组件展示形态。

Features 一览

task.md 列出的功能特性：

• 提供 pending、in-progress、completed、error 四种状态的可视图标；
• 可展开的任务内容区，用于承载任务描述与补充信息；
• 内置进度计数器，展示已完成与总任务数对比；
• 支持带自定义时序的可选渐进式任务揭示（progressive reveal）；
• 任务项内支持自定义内容（如文件、链接等）；
• 完整的 TypeScript 类型定义，全链路类型安全；
• 支持键盘导航与屏幕阅读器（基于 radix-ui 的无障碍语义）。

Props 参考

以下是task.md中给出的全部 Props 表（可结合 task.tsx 源码验证）。

<Task />

<TaskTrigger />

<TaskContent />

<TaskItem />

<TaskItemFile />

说明：TaskItem与TaskItemFile在本地源码中类型定义为ComponentProps<"div">，即完全等价于普通 div 的 props，因此可自由追加className、onClick、data-*等任意属性。

完整示例：scripts/task.tsx

仓库内的 scripts/task.tsx 是一个无需后端即可运行的静态示例，展示如何用TaskItemFile内嵌文件图标：

"use client"; import { SiReact } from "@icons-pack/react-simple-icons"; import { Task, TaskContent, TaskItem, TaskItemFile, TaskTrigger } from "@/components/ai-elements/task"; import { nanoid } from "nanoid"; import type { ReactNode } from "react"; const Example = () => { const tasks: { key: string; value: ReactNode }[] = [ { key: nanoid(), value: 'Searching "app/page.tsx, components structure"' }, { key: nanoid(), value: ( <span className="inline-flex items-center gap-1" key="read-page-tsx"> Read <TaskItemFile> <SiReact className="size-4" color="#149ECA" /> <span>page.tsx</span> </TaskItemFile> </span> ), }, { key: nanoid(), value: "Scanning 52 files" }, // ... ]; return ( <div style={{ height: "200px" }}> <Task className="w-full"> <TaskTrigger title="Found project files" /> <TaskContent> {tasks.map((task) => ( <TaskItem key={task.key}>{task.value}</TaskItem> ))} </TaskContent> </Task> </div> ); }; export default Example;

这个示例展示了几个实用模式：

• Task上直接传className="w-full"控制宽度；
• TaskTrigger只传title即可，本地源码会在无children时渲染默认的“图标 + 标题 + 箭头”行；
• TaskItem的 children 可以是任意 ReactNode，包括带TaskItemFile的混合内容；
• 使用nanoid()生成稳定的 React key。

扩展与定制建议

由于所有组件代码安装后都属于你的项目（而非隐藏在库中），你可以：

• 改样式：直接编辑components/ai-elements/task.tsx中的 Tailwind 类，例如调整TaskItemFile的圆角、边框或背景色；
• 加状态指示：根据taskSchema.status字段（pending/in_progress/completed）给TaskTrigger行前置对应的状态图标；
• 加进度计数：在TaskContent内自行统计 items 数量，或对tasksSchema.tasks做“已完成/总数”汇总后展示；
• 渐进式揭示：结合useObject的流式更新特性，在object?.tasks到达时按序渲染，实现任务逐条出现的渐进效果；
• 无障碍：无需额外处理，CollapsibleTrigger/CollapsibleContent已继承 radix-ui 的键盘交互与 ARIA 语义。

常见问题排查

• 组件无样式：确认项目已正确配置 shadcn/ui（Tailwind 4 下globals.css需导入 Tailwind 与 shadcn 基础样式）；
• CLI 未添加文件：确认当前目录是项目根目录（含package.json）、components.json配置正确，并确保使用最新版 CLI（npx ai-elements@latest）；
• 模块找不到：确认tsconfig.json已配置@/*路径别名指向项目根目录；
• AI 助手无法访问组件：检查配置文件为合法 JSON、路径正确，并重启编辑器。

结语

Task组件是 AI 原生界面中“过程可视化”的关键一环——把模型正在执行的多步骤工作流，以可折叠、带状态、可内嵌文件引用的形式实时呈现给用户。通过useObject+streamObject的结构化流式通道，前端与后端共享同一份 Zod Schema 契约，既保证了类型安全，也让任务进度可以随 token 流逐步“生长”。如果你想在 ZCode 的 UI 体系内复刻这类交互，可以直接以 packages/ui/src/components/ai-elements/task.tsx 为起点，结合 scripts/task.tsx 的示例快速落地。

• 人工智能
• 大模型
• 代码智能体
• AI Agent
• 桌面应用
• 后端
• 前端
• CLI