ZCode 中的 AI 上下文使用可视化：Context 复合组件体系实战解析

ZCode 中的 AI 上下文使用可视化Context 复合组件体系实战解析【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode导读本文围绕 ZCode 开源仓库中 AI Elements 技能体系的核心组件Context展开系统讲解如何在一个基于 AI SDK 的 React 应用中展示模型上下文窗口占用率、token 消耗明细输入 / 输出 / 推理 / 缓存与实时成本估算。通过阅读本文你将掌握 Context 复合组件compound component的完整 API、React Context 数据流设计、基于Intl.NumberFormat的 token 智能格式化以及基于tokenlens的成本计算原理并看到该组件在 ZCode 产品界面中的真实集成方式。Context是一个用于展示 AI 模型上下文窗口使用情况的复合组件系统它通过交互式悬停卡片hover card呈现上下文窗口占用、token 消耗拆分与成本估算。组件源自 Vercel 的 ai-elements配套的可运行示例见 .agents/skills/ai-elements/scripts/context.tsx。安装与前置条件在项目中使用 Context 组件前请确认满足 AI Elements 技能体系的环境要求Node.js 18 及以上一个安装了AI SDK的 React / Next.js 项目已安装shadcn/ui若未安装执行安装命令时会自动引入。安装 Context 组件最直接的方式是使用 AI Elements 专用 CLI请根据项目的packageManager选择npx、pnpm dlx或bunx --bun作为包执行器npx ai-elementslatest add contextCLI 会把组件源码直接集成到项目的/components/ai-elements/目录或你在 shadcn 配置中指定的组件目录组件以源码形式存在于项目代码库中而非隐藏在第三方库内部因此你可以像使用普通 React 组件一样导入使用甚至直接打开文件查看实现或做定制修改。在 ZCode 仓库中该组件的本地实现已落地于 packages/ui/src/components/ai-elements/context.tsx其依赖的tokenlens版本为^1.3.1见 packages/ui/package.json。核心特性一览从参考文档与源码实现可以归纳出 Context 组件的以下能力复合组件架构Compound Component由根组件与多个子组件灵活组合按需拼装展示元素可视化进度指示SVG 圆形进度环直观显示上下文使用百分比Token 明细拆分输入、输出、推理、缓存四类 token 分别展示实时成本估算借助tokenlens库按模型定价实时计算费用智能格式化token 数量自动按 K / M / B 缩写交互式悬停卡片悬停触发详细信息的 HoverCard 弹层Context Provider 模式通过 React Context API 完成干净的数据流传递TypeScript 支持所有组件均带完整类型定义无障碍设计正确使用 ARIA 属性与语义化 HTML主题自适应进度指示使用currentColor随宿主主题自动适配。Props 全表以下完整继承自参考文档的 Props 定义并结合源码 packages/ui/src/components/ai-elements/context.tsx 补充了说明。Context /— 根 ProviderProp类型默认值说明maxTokensnumber-上下文窗口总大小token 数用于计算占用百分比源码中formatUsagePercent会在maxTokens 0时返回 0避免除零异常usedTokensnumber-当前已使用的 token 数usageLanguageModelUsage-来自 AI SDK 的详细 token 用量拆分input、output、reasoning、cached input tokens对应ContextSchema中的usage字段modelIdModelId即string-模型标识符用于成本计算例如openai:gpt-5...propsComponentPropsHoverCard-其余属性透传给底层 HoverCard 组件根组件在源码中通过useMemo缓存{ maxTokens, modelId, usage, usedTokens }形成 context 值并包裹HoverCardcloseDelay{0}、openDelay{0}即悬停零延迟开合。任何子组件在Context之外使用时都会抛出Context components must be used within Context错误见useContextValue的实现。ContextTrigger /— 触发按钮Prop类型默认值说明childrenReact.ReactNode-自定义触发元素未提供时渲染默认按钮带百分比进度环图标loadingbooleanfalseZCode 扩展属性为true时进度环图标替换为旋转的Loader2加载图标对应额度自动重置进行中状态源码注释注明为「正在重置」状态...propsComponentPropsButton-透传给默认按钮元素默认触发按钮使用variantghost、sizeicon-md样式内部通过HoverCardTrigger asChild包装以保证无障碍与聚焦行为。ContextContent /— 悬停卡片容器Prop类型默认值说明classNamestring-附加 CSS 类通过cn合并...propsComponentPropsHoverCardContent-透传给 HoverCardContent 组件源码中该容器固定宽度!w-64采用rounded-lg、bg-tooltip背景与text-tooltip-foreground前景色关闭默认阴影、圆环与外框shadow-none ring-0 outline-0。ContextContentHeader /— 头部Prop类型默认值说明childrenReact.ReactNode-自定义头部内容未提供时渲染百分比、token 数与进度条actionReact.ReactNode-ZCode 扩展属性头部右上角可选的行动作区域progressSegmentsreadonly { className?: string; id: string; percent: number }[]-ZCode 扩展属性分段进度条配置与 progress.tsx 的分段渲染能力配合...propsComponentPropsdiv-透传给头部 div 元素默认头部渲染 Context 标题、分隔线、百分比保留 1 位小数如40.0%、已用 / 总量的完整数字如40,000 / 128,000以及一个基于Progress组件的横向进度条value{usedPercent * 100}。ContextContentBody /— 主体Prop类型默认值说明childrenReact.ReactNode-主体内容通常放置各 Usage 拆分组件...propsComponentPropsdiv-透传给 body div 元素主体默认使用bg-menu背景与p-3内边距与头部、底部形成视觉分区。ContextContentFooter /— 底部Prop类型默认值说明childrenReact.ReactNode-自定义底部内容未提供且传入modelId时渲染总成本...propsComponentPropsdiv-透传给 footer div 元素底部通过border-t border-popover-border与bg-surface形成次级背景。默认渲染 Total cost 与格式化后的总费用未提供modelId时成本为$0.00。Usage 组件ContextInputUsage/ContextOutputUsage/ContextReasoningUsage/ContextCacheUsage四个用量组件共享相同的 Props 约定Prop类型默认值说明childrenReact.ReactNode-自定义内容未提供时渲染对应类型的 token 数与成本classNamestring-附加 CSS 类...propsComponentPropsdiv-透传给 div 元素源码中的行为细节值得注意输入Input读取usage.inputTokens成本按{ input: inputTokens, output: 0 }计算输出Output读取usage.outputTokens成本按{ input: 0, output: outputTokens }计算推理Reasoning读取usage.reasoningTokens成本以{ reasoningTokens }独立计算推理 token 通常有特殊定价缓存Cache读取usage.cachedInputTokens成本以{ cacheReads: cacheTokens, input: 0, output: 0 }计算缓存读取通常价格更低。每个组件在对应 token 数为 0 时返回null不渲染token 数未定义时显示占位符—成本文本通过• $X.XX形式附在 token 数之后。组件架构复合组件 React ContextContext 组件采用复合组件compound component模式配合 React Context 在多个展示组件间共享数据结构分层如下Context—— 根 Provider持有全部上下文数据usedTokens、maxTokens、usage、modelIdContextTrigger—— 交互式触发元素默认带百分比进度环的按钮ContextContent—— 悬停卡片内容容器ContextContentHeader—— 头部含进度可视化ContextContentBody—— 主体承载用量拆分ContextContentFooter—— 底部展示总成本Usage 组件—— Input / Output / Reasoning / Cache 四类独立用量展示。数据流方面根组件Context用useMemo构造 context 值并通过ContextContext.Provider下发所有子组件通过useContextValue()取用若脱离根组件使用则抛出运行时错误参见 packages/ui/src/components/ai-elements/context.tsx 中createContext与useContextValue的实现。底层交互依赖 shadcn/ui 风格的 hover-card.tsx基于 Radix UI 的HoverCard含 Portal、对齐与动画与 progress.tsx支持分段segments渲染。圆形进度环的实现细节默认触发按钮中的图标是一个纯 SVG 环形进度条源码ContextIcon常量定义ICON_RADIUS 10、ICON_VIEWBOX 24、ICON_CENTER 12、ICON_STROKE_WIDTH 4、PERCENT_MAX 100周长circumference 2π × 10根据使用比例usedPercent计算dashOffset circumference × (1 - usedPercent)底环opacity0.25表示空余容量进度弧opacity0.7且transform: rotate(-90deg)使进度从 12 点钟方向起始strokeLinecapround提供圆角端点颜色直接使用currentColor因此自动适配按钮前景色与宿主主题。Token 智能格式化组件对 token 数值的格式化遵循Intl.NumberFormat的 compact紧凑记法按数量级自动缩写 1,000显示精确数值如8421,000追加 K 后缀如32K1,000,000追加 M 后缀如1.5M1,000,000,000追加 B 后缀如2.1B。在 ZCode 实现中该逻辑被封装为独立的formatCompactTokenNumber工具函数位于 packages/ui/src/lib/tokenNumberFormat.ts。源码注释明确记录了本地化决策token 数值应走当前 locale 的 compact 记法中文环境显示万/亿英文环境显示 K/M/B避免此前「为修英文长单位而把所有 locale 强制成 K/M/B」的回归问题而模型列表的容量 badgeformatModelContextWindowLabel作为技术规格则固定使用en-US的 K/M/B 展示。数值非有限数!Number.isFinite时返回空字符串兜底。成本计算原理当传入modelId时组件通过tokenlens库自动完成成本估算packages/ui/src/components/ai-elements/context.tsx 中getUsage(...).costUSD?.totalUSD。成本构成如下输入 token按模型的输入定价计算输出 token按模型的输出定价计算推理 token针对支持推理reasoning的模型使用特殊定价缓存 token按缓存输入读取cache read的优惠价计算总成本各类 token 成本之和。成本最终使用Intl.NumberFormat以USD 货币格式输出如$0.42。值得说明的是页脚总成本仅以inputTokens与outputTokens两项调用getUsage而各 Usage 组件的单项成本分别独立计算推理与缓存成本在单项明细中体现。完整可运行示例参考文档指向的示例脚本 .agents/skills/ai-elements/scripts/context.tsx 演示了完整组合方式——以一个128,000token 的上下文窗口、已用40,000token、openai:gpt-5模型为数据组合全部 7 类子组件use client; import { Context, ContextCacheUsage, ContextContent, ContextContentBody, ContextContentFooter, ContextContentHeader, ContextInputUsage, ContextOutputUsage, ContextReasoningUsage, ContextTrigger, } from /components/ai-elements/context; const Example () ( div classNameflex items-center justify-center p-8 Context maxTokens{128_000} modelIdopenai:gpt-5 usage{{ cachedInputTokens: 0, inputTokens: 32_000, outputTokens: 8000, reasoningTokens: 0, totalTokens: 40_000, }} usedTokens{40_000} ContextTrigger / ContextContent ContextContentHeader / ContextContentBody ContextInputUsage / ContextOutputUsage / ContextReasoningUsage / ContextCacheUsage / /ContextContentBody ContextContentFooter / /ContextContent /Context /div ); export default Example;注意usage的字段名必须与 AI SDK 的LanguageModelUsage类型一致inputTokens、outputTokens、reasoningTokens、cachedInputTokens、totalTokens其中推理与缓存 token 为 0 时对应 Usage 组件会自动隐藏不会产生空行。在 ZCode 产品中的真实应用Context 组件并非仅供示例使用它在 ZCode 桌面端聊天输入工具栏中被实际集成packages/ui/src/chat-input-toolbar/contextUsage.tsx导入了Context、ContextContentBody、ContextContent、ContextTrigger等组件将 Context 窗口占用、Coding Plan 与 Start Plan 额度三段信息聚合在同一个上下文面板中展示源码头注说明该文件是「context 面板聚合 Context windows、Coding Plan 和 Start Plan 三段紧耦合展示」。该集成还展示了两个扩展点通过loading属性在额度自动重置期间替换进度环图标以及通过progressSegments传入多段进度条配置配合 progress.tsx 的分段能力。这说明 Context 复合组件通过...props透传与可选子节点约定可以低成本嵌入真实业务面板。样式与主题集成组件基于 Tailwind CSS 并遵循宿主设计系统shadcn/ui 语义 token进度指示使用currentColor自动适配主题与前景色悬停卡片宽度与内边距可定制默认!w-64p-3页脚使用次级背景bg-surface 顶部边框形成视觉分隔主体文本统一使用text-ui-base字号保持一致性次级信息使用 muted 前景色text-foreground-subtle/text-muted-foreground。由于组件代码以源码形式进入你的项目你可以直接修改 Tailwind 类名来调整外观例如去掉圆角、更换背景 token 等无需额外配置。延伸阅读组件完整实现packages/ui/src/components/ai-elements/context.tsx可运行示例.agents/skills/ai-elements/scripts/context.tsxToken 格式化工具packages/ui/src/lib/tokenNumberFormat.ts底层 UI 基元hover-card.tsx、progress.tsx产品内集成案例packages/ui/src/chat-input-toolbar/contextUsage.tsx技能体系总览与安装说明.agents/skills/ai-elements/SKILL.md【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考