ZCode 中的 AI 执行计划组件 Plan：基于 ai-elements 的可折叠流式计划展示方案-育师

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

【免费下载链接】ZCode

ZCode 是 AI 编程工作台，提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI，以及 Agent CLI 与运行时源码。

Plan 是 ZCode 仓库引入的 ai-elements 组件库中用于展示 AI 生成执行计划的 React 组件，它以可折叠卡片的形式承载多步骤工作流、任务拆解与实施策略，并通过 Context 传递的isStreaming状态配合 Shimmer 微光动画呈现流式加载效果。本文将以 plan.md 为核心脉络，结合 plan.tsx 实现与仓库内的使用场景，完整讲解该组件的安装方式、全部 Props 定义、组合原理与源码级实现细节，帮助读者在自己的 AI 应用界面中快速落地同款计划展示交互。

Plan 组件是什么

Plan 是一个"可折叠的计划组件"，专门用于展示 AI 生成的执行计划，内置流式（streaming）支持与微光（shimmer）动画。它适合呈现：

多步骤工作流（multi-step workflows）
任务拆解（task breakdowns）
实施策略（implementation strategies）

其核心价值在于：AI 正在生成计划时，标题与描述区域会以 shimmer 动画提示"内容仍在产出中"；生成完成后，用户可以通过头部触发器折叠/展开完整计划正文，避免长计划占据过多界面空间。

该组件属于 ZCode 引入的 ai-elements 技能体系。SKILL.md 说明：ai-elements 是构建在 shadcn/ui 之上的组件库与自定义 registry，用于加速 AI 原生应用界面开发；ZCode 将其以本地化技能形式集成，组件源码位于 packages/ui/src/components/ai-elements/，来源与许可（Apache-2.0，版权归 Vercel, Inc.）记录在仓库根目录的 THIRD-PARTY-NOTICES.md。

安装与前置条件

参考 SKILL.md，使用 Plan 组件前需确认环境满足：

Node.js 18 或更高版本；
一个已安装AI SDK的Next.js项目；
项目内已安装shadcn/ui（若未安装，执行安装命令时会自动安装）。

安装 Plan 组件使用 AI Elements CLI：

npx ai-elements@latest add plan

根据项目的packageManager配置，也可以将npx替换为pnpm dlx或bunx --bun，效果一致。

CLI 会把组件代码下载并集成到项目目录（默认落在@/components/ai-elements/或你在 shadcn components 设置中配置的目录）。由于组件代码直接进入你的代码库而非隐藏的库依赖，安装后即可像普通 React 组件一样导入使用，也可以直接打开组件文件查看实现或做定制修改。

组件架构：一个复合组件家族

Plan 不是单一组件，而是一个由 8 个组件组成的复合家族，通过 PlanContext 共享isStreaming状态：

组件	基座	职责
`Plan`	`Collapsible`（radix-ui）包一层`Card`	根容器，创建 Context
`PlanHeader`	`CardHeader`	头部区域，标题/描述与触发器并排
`PlanTitle`	`CardTitle`	计划标题，流式时显示 shimmer
`PlanDescription`	`CardDescription`	计划描述，流式时显示 shimmer
`PlanTrigger`	`CollapsibleTrigger`内的`Button`	展开/折叠按钮，带 chevron 图标
`PlanContent`	`CollapsibleContent`内的`CardContent`	可折叠的正文区域
`PlanFooter`	`CardFooter`	底部操作区
`PlanAction`	`CardAction`	底部动作按钮位

从源码可以看到Plan的实现结构：

export const Plan = ({ className, isStreaming = false, children, ...props }: PlanProps) => { const contextValue = useMemo(() => ({ isStreaming }), [isStreaming]); return ( <PlanContext.Provider value={contextValue}> <Collapsible asChild>"use client"; import { Plan, PlanAction, PlanContent, PlanDescription, PlanFooter, PlanHeader, PlanTitle, PlanTrigger, } from "@/components/ai-elements/plan"; import { Button } from "@/components/ui/button"; import { FileText } from "lucide-react"; const Example = () => ( <Plan defaultOpen={false}> <PlanHeader> <div> <div className="mb-4 flex items-center gap-2"> <FileText className="size-4" /> <PlanTitle>Rewrite AI Elements to SolidJS</PlanTitle> </div> <PlanDescription> Rewrite the AI Elements component library from React to SolidJS while maintaining compatibility with existing React-based shadcn/ui components using solid-js/compat, updating all 29 components and their test suite. </PlanDescription> </div> <PlanTrigger /> </PlanHeader> <PlanContent> <div className="space-y-4 text-sm"> <div> <h3 className="mb-2 font-semibold">Overview</h3> <p> This plan outlines the migration strategy for converting the AI Elements library from React to SolidJS, ensuring compatibility and maintaining existing functionality. </p> </div> <div> <h3 className="mb-2 font-semibold">Key Steps</h3> <ul className="list-inside list-disc space-y-1"> <li>Set up SolidJS project structure</li> <li>Install solid-js/compat for React compatibility</li> <li>Migrate components one by one</li> <li>Update test suite for each component</li> <li>Verify compatibility with shadcn/ui</li> </ul> </div> </div> </PlanContent> <PlanFooter className="justify-end"> <PlanAction> <Button size="sm"> Build <kbd className="font-mono">⌘↩</kbd> </Button> </PlanAction> </PlanFooter> </Plan> ); export default Example;

组合要点：

Plan defaultOpen={false}让计划默认折叠，头部仅显示标题与描述摘要；
PlanHeader内先放标题/描述块，再放PlanTrigger，PlanHeader的样式（flex items-start justify-between）会保证两者左右对齐；
PlanContent放入完整计划正文，只有展开时才可见；
PlanFooter+PlanAction承载"执行计划"类操作按钮（如示例中的Build快捷键提示）。

若需要默认展开，将defaultOpen改为true即可。

源码级原理：流式状态、微光动画与折叠动画

Context 驱动的流式状态

isStreaming是整个流式体验的开关：PlanTitle 与 PlanDescription 均通过usePlan()读取该值。仓库内 ZCode 本地化的实现中，对应的<Shimmer>包裹逻辑被注释保留（见 plan.tsx 中的注释行），可直接取消注释恢复上游的 shimmer 效果。

Shimmer 微光动画

shimmer 效果由 shimmer.tsx 提供，其实现要点：

使用motion/react的motion组件，动画在backgroundPosition上从"100% center"过渡到"0% center"，ease: "linear"且repeat: Infinity无限循环；
通过background-clip: text+text-transparent让渐变只作用于文字本身；
dynamicSpread由(children?.length ?? 0) * spread计算（spread默认2，duration默认2秒），即光带宽度随文本长度自动缩放；
组件经memo包裹以减少不必要的重渲染；
动画所用的 motion 组件在模块级缓存（motionComponentCache），避免渲染期间反复创建。

值得注意的细节：ZCode 在本地化时处理了一个主题变量兼容问题——当前主题未定义 ai-elements 默认依赖的--color-muted-foreground，会导致 background-image 整条失效并配合text-transparent让文字完全不可见；修复方式是保留上游 token 作为第一优先级，同时回退到项目稳定存在的--color-foreground-subtle。

折叠动画与滚动性能

PlanContent依赖的 collapsible.tsx 实现了细粒度的动画控制：外层用animate-collapsible-down/up处理高度变化，内层 div 通过data-[state=open]:animate-in+fade-in-0处理透明度淡入，data-[state=closed]时配合animation-fill-mode: forwards保持结束状态。源码注释还记录了一次性能修复：大会话 trace 显示折叠动画层仅设置 duration/ease 时，浏览器会默认transition-property: all而动画化scrollbar-color，拖拽窗口时触发非合成动画，因此显式禁用 CSS transition，只保留 animate-in/out 关键帧动画——这说明折叠动画层针对长内容场景做了专门的滚动性能优化。

无障碍设计

PlanTrigger 渲染为size="icon"、variant="ghost"的Button，内置ChevronsUpDownIcon图标，并附带<span className="sr-only">Toggle plan</span>供屏幕阅读器读取，键盘导航与焦点管理由 radix-ui 的CollapsibleTrigger原生承担。组件还通过data-slot（如plan、plan-header、plan-title）暴露稳定的选择器钩子，便于测试与样式定位。

ZCode 中的实际应用场景

Plan 组件所属的 ai-elements 已被 ZCode 实际运用于 Agent 界面。仓库中 plan-guidance.tsx 展示了计划类信息如何与 ai-elements 家族组件（MessageResponse、ToolOutput、ToolLayout）组合渲染：该渲染器会从工具调用的output、input、raw等字段中递归提取计划指南的 Markdown 文本（依次尝试text/content/output键名），再通过MessageResponse以左边框引用的形式展示，作为 ZCode 中"计划模式/计划指南"工具调用的可视化载体。

此外，整个 ai-elements 技能（.agents/skills/ai-elements）与组件源码（packages/ui/src/components/ai-elements/）均注明派生自 vercel/ai-elements，版权归 Vercel, Inc.，遵循 Apache-2.0 许可，完整许可与来源记录见 THIRD-PARTY-NOTICES.md（其中列出了ai-elements (Apache-2.0)对应的组件目录与技能目录两条条目）。

自定义与常见问题

修改组件样式

安装后组件代码即属于你的项目，可像修改自己的代码一样调整 Tailwind 类。例如去掉 Card 的圆角，删除Plan外层Card的rounded-xl类即可；PlanTitle/PlanDescription的children必须为字符串（类型定义为string），这是 shimmer 按文本长度计算光带的前提。

组件未生效

确认当前工作目录是项目根目录（package.json所在处）；
确认components.json（shadcn 风格配置）设置正确；
使用最新版 CLI：npx ai-elements@latest。

组件无样式

项目需按 shadcn/ui（Tailwind 4）规范配置——globals.css需导入 Tailwind 并包含 shadcn/ui 基础样式。

主题切换失效（停留在浅色模式）

应用需使用与 shadcn/ui、ai-elements 一致的data-theme系统（默认在<html>上切换data-theme属性），并确保tailwind.config.js使用class或data-选择器。

"module not found"

确认组件文件存在，且tsconfig.json为@/配置了 paths 别名：

{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./*"] } } }

小结

Plan 组件以"Collapsible 折叠能力 + Card 卡片容器 + Context 流式状态 + Shimmer 微光动画"四层组合，为 AI 执行计划提供了完整的展示方案：折叠状态下保持界面清爽，流式状态下通过微光动画反馈生成进度，展开后呈现完整步骤。其全部 Props 均透传至底层 shadcn/ui 与 radix-ui 原语，既保持了开箱即用的体验，又保留了逐级定制的自由度。若要在自己的 AI 应用中实现同款计划展示，参照上文安装命令、示例脚本与组件源码即可快速落地。