AI上下文与成本
ContextUsage
@mox-hub/patterns · AI · 上下文与成本 · canonical
context-usage@mox-hub/patternsData Displaycanonicalsrc/components/context-usage.tsx变体演示context-usage
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| segments* | ContextSegment[] | — | — |
| limit* | number | — | — |
| compact* | boolean | false | — |
| onSegmentClick* | (key: string) => void | — | — |
| className* | string | — | — |
| labels* | Partial<ContextUsageLabels> | — | — |
源码
import { useMemo, useState } from 'react';
import { RawButton } from '@mox-hub/ui/components/raw/raw-button';
import { Tooltip, TooltipContent, TooltipTrigger } from '@mox-hub/ui/components/tooltip';
import { TONE_CLASS, type Tone } from '@mox-hub/ui/components/tone';
import { useFormatters } from '@mox-hub/ui/i18n';
import { cn } from '@mox-hub/ui';
import { usePatternLabels } from '../lib/i18n';
/**
* ContextUsage - [AI] 模型上下文占用格场(组件规划账本 B4 / 宪法 §22.5 活性可感知、§17.6 结论式 aria)。
*
* 「模型上下文快满了 / 还装得下多少」的透明化承载件:上下文窗口渲染为一排定量格子,
* 各分区(系统提示 / 工具定义 / 记忆 / 对话历史 / 文件)按 token 占比从左到右填充,
* 未占满的尾部格子渲染为虚框(free)。悬停分区点亮该段、其余降透明度,tooltip 给出
* 「分区名 · token 数 · 占比」。一期纯展示;compaction(压缩)动画二期再评估(占比
* 变化已可静态表达收敛)。
*
* - **格场分配**:总格数固定 24(compact 档 12),每格代表 limit/格数 的 token 量;
* 分区跨界格按占比四舍五入取整分配,取整溢出从尾部回收、误差落 free(见
* allocateContextSegments)。低于半格的分区不占格(格场分辨率限制),token 数仍
* 计入结论 aria-label 与汇总行的已用量——诚实不丢数。
* - **阈值语义色**:整体占用 <70% 中性 / 70-90% warning 琥珀 / >90% danger 红,
* 只落在汇总读数与 data-usage-level 上;格子恒用所在分区色(边缘格不参与阈值染色)。
* 阈值常量导出供测试(CONTEXT_USAGE_WARNING_THRESHOLD / CONTEXT_USAGE_DANGER_THRESHOLD)。
* - **防御归一**:tokens 负数 / NaN / Infinity 一律按 0 计;分区总和超过 limit 时
* 等比收缩到恰好铺满 100%——诚实渲染到满,不溢出不诈减(相对占比保留)。limit
* 非有限数或 ≤0 时无法得出任何诚实结论,整件不渲染(返回 null)。
* - **a11y 取舍**(二选一取后者):整体 role="img" + 单一结论 aria-label(§17.6,
* 如「上下文已用 62%,对话历史占最多」)+ 每分区 title 兜底;不给 24 格逐格发
* tabIndex(键盘 tab 风暴)。有 onSegmentClick 时分区升级为 <button>(§8.5 第 7 条,
* 禁 div onClick),容器改 role="group",焦点态与悬停态同样点亮。
* - **动效克制**:仅 hover/focus 的 opacity 过渡(duration-fast 120ms,§7.1 白名单);
* 无常驻动画。§7.4 reduced-motion 由全局规则接管。
*
* 受控纯展示件:…props 透传、ref 到根(§10.7)。文案中文硬编码(先例 activity-heatmap;
* i18n 收编随登记批)。数据源现状:前端尚无「窗口上限 limit」契约(execution 详情只有
* totalTokens 总量,assistant usage 是单次调用开销)——真实接线方案见
* .roadmap-handoff/context-usage-handoff.md,禁在消费方手造 limit 常量(§22.2 禁造假数)。
*/
/** 阈值语义色档(导出供测试) */
export type ContextUsageLevel = 'neutral' | 'warning' | 'danger';
/** 占用 <70% 中性(导出供测试) */
export const CONTEXT_USAGE_WARNING_THRESHOLD = 0.7;
/** 占用 >90% danger(70-90% 区间含端点为 warning;导出供测试) */
export const CONTEXT_USAGE_DANGER_THRESHOLD = 0.9;
/** 标准档总格数 */
export const CONTEXT_USAGE_CELLS = 24;
/** 紧凑档总格数(面板窄栏) */
export const CONTEXT_USAGE_CELLS_COMPACT = 12;
/** 分区色档(§5.3 语义色表达分类;red 留给超限强调与消费方覆写) */
export type ContextTone = 'neutral' | 'blue' | 'green' | 'yellow' | 'orange' | 'purple' | 'red';
export interface ContextSegment {
/** 分区标识:system / tools / memory / history / files(free 由组件派生,传入即忽略) */
key: string;
/** 分区名(中文,tooltip 与结论 aria 用) */
label: string;
/** 该分区 token 数(负数 / NaN / Infinity 防御归一为 0) */
tokens: number;
/** 可选色;缺省按 key 从内置档位表取(未知 key 按 fallback 色序轮转) */
tone?: ContextTone;
}
export interface ContextUsageLabels {
used: string;
overLimit: string;
free: string;
conclusionFree: (limit: string) => string;
conclusionOver: (pct: string, top: string) => string;
conclusionUsed: (pct: string, top: string) => string;
}
const DEFAULT_LABELS: ContextUsageLabels = {
used: '已用',
overLimit: '· 已超限',
free: '剩余空间',
conclusionFree: (limit) => `上下文全部空闲(0 / ${limit} tokens)`,
conclusionOver: (pct, top) => `上下文已满(${pct}),内容已超出窗口,${top}占最多`,
conclusionUsed: (pct, top) => `上下文已用 ${pct},${top}占最多`,
};
export interface ContextUsageProps extends React.ComponentProps<'div'> {
/** 各分区占用(顺序即渲染顺序) */
segments: ContextSegment[];
/** 上下文窗口总量(token);非有限数或 ≤0 时整件不渲染 */
limit: number;
/** 紧凑档:格数减半、隐藏汇总行(面板窄栏) */
compact?: boolean;
/** 点分区回调(如跳转记忆管理);提供时分区渲染为 button,容器 role 改 group */
onSegmentClick?: (key: string) => void;
labels?: Partial<ContextUsageLabels>;
}
export interface ContextAllocatedSegment {
key: string;
label: string;
/** 归一后的 token 数(超限时等比收缩过) */
tokens: number;
/** 分到的格数(0 = 低于半格,不占格但计入已用量) */
cells: number;
tone: ContextTone;
}
export interface ContextAllocation {
filled: ContextAllocatedSegment[];
/** 虚框格数(≥0) */
freeCells: number;
usedTokens: number;
freeTokens: number;
/** 0..1(超限时恰为 1) */
usedFraction: number;
/** 输入总和 > limit(已等比收缩渲染到 100%) */
overLimit: boolean;
}
/** 内置分区默认色档 */
const DEFAULT_TONE_BY_KEY: Record<string, ContextTone> = {
system: 'purple',
tools: 'blue',
memory: 'green',
history: 'orange',
files: 'yellow',
};
/** 未知 key 的 fallback 色序(按出现顺序轮转,避免同色相邻歧义) */
const FALLBACK_TONES: ContextTone[] = ['blue', 'purple', 'green', 'orange', 'yellow'];
/**
* 色档 → 语义 token 引用(SERIES_COLORS 同款惯例:内联 style 写 var() 引用,§5.1 禁字面色)。
* 分区色是「分类」语义(§5.3),非状态——不走 status tone 链;阈值档文字色才走 TONE_CLASS。
*/
const TONE_COLOR: Record<ContextTone, string> = {
neutral: 'hsl(var(--muted-foreground))',
purple: 'hsl(var(--accent-purple))',
blue: 'hsl(var(--accent-blue))',
green: 'hsl(var(--accent-green))',
yellow: 'hsl(var(--accent-yellow))',
orange: 'hsl(var(--accent-orange))',
red: 'hsl(var(--accent-red))',
};
/** 阈值档 → status tone(唯一视觉链路 §19.5:文字色经 TONE_CLASS 取值;neutral 无状态即 default) */
const LEVEL_TONE: Record<ContextUsageLevel, Tone> = {
neutral: 'default',
warning: 'warning',
danger: 'danger',
};
/**
* 占用比 → 阈值档:<70% neutral / 70-90%(含端点)warning / >90% danger。
* 纯函数,导出供测试。
*/
export function contextUsageLevel(usedFraction: number): ContextUsageLevel {
if (usedFraction > CONTEXT_USAGE_DANGER_THRESHOLD) return 'danger';
if (usedFraction >= CONTEXT_USAGE_WARNING_THRESHOLD) return 'warning';
return 'neutral';
}
/**
* 格场分配(纯函数,导出供测试):
* ① tokens 负数 / NaN / Infinity → 0(诚实归零,不诈减其他分区);
* ② 分区总和 > limit → 等比收缩到恰好铺满 100%(保留相对占比,误差不溢出);
* ③ 每分区按 tokens/(limit/格数) 四舍五入取格,总量以 round(占用比×格数) 封顶——
* 溢出从尾部回收,误差只落 free(格场永不多画);
* ④ limit / cellCount 非有限数或 ≤0 → null(无法诚实渲染)。
*/
export function allocateContextSegments(
segments: ContextSegment[],
limit: number,
cellCount: number,
): ContextAllocation | null {
if (!Number.isFinite(limit) || limit <= 0) return null;
if (!Number.isFinite(cellCount) || cellCount <= 0) return null;
// free 由组件派生,传入即忽略;负数 / 非有限数归一为 0
const safe = segments
.filter((s) => s.key !== 'free')
.map((s) => ({
...s,
tokens: Number.isFinite(s.tokens) && s.tokens > 0 ? s.tokens : 0,
}));
const rawSum = safe.reduce((acc, s) => acc + s.tokens, 0);
const overLimit = rawSum > limit;
const scale = overLimit && rawSum > 0 ? limit / rawSum : 1;
const usedTokens = overLimit ? limit : rawSum;
const cellTokens = limit / cellCount;
// 总格数上限 = round(真实占用比 × 格数):逐段四舍五入会系统性上偏(如 24 段各 0.6 格
// 全进位成满格),以真实占用封顶后格场永不多画——取整误差只落 free,不诈满
const maxFilled = Math.round((usedTokens / limit) * cellCount);
let cumulative = 0;
let fallbackIndex = 0;
const filled = safe.map((s) => {
const tokens = s.tokens * scale;
// 按占比取整分配;取整溢出从尾部回收(误差落 free)
const cells = Math.max(0, Math.min(Math.round(tokens / cellTokens), maxFilled - cumulative));
cumulative += cells;
const tone =
s.tone ?? DEFAULT_TONE_BY_KEY[s.key] ?? FALLBACK_TONES[fallbackIndex++ % FALLBACK_TONES.length];
return { key: s.key, label: s.label, tokens, cells, tone };
});
return {
filled,
freeCells: cellCount - cumulative,
usedTokens,
freeTokens: limit - usedTokens,
usedFraction: usedTokens / limit,
overLimit,
};
}
interface RenderGroup {
key: string;
label: string;
cells: number;
tone: ContextTone;
tokens: number;
free?: boolean;
}
export function ContextUsage({
segments,
limit,
compact = false,
onSegmentClick,
className,
labels,
...rest
}: ContextUsageProps) {
const D = usePatternLabels('contextUsage', DEFAULT_LABELS);
const F = useFormatters();
const percent = (value: number) => F.percent(value, { maximumFractionDigits: 1 });
const L = { ...D, ...labels };
const [activeKey, setActiveKey] = useState<string | null>(null);
const cellCount = compact ? CONTEXT_USAGE_CELLS_COMPACT : CONTEXT_USAGE_CELLS;
const allocation = useMemo(
() => allocateContextSegments(segments, limit, cellCount),
[segments, limit, cellCount],
);
// limit 非法:无诚实结论可下,整件不渲染(同 ProportionBar denom<=0 先例)
if (!allocation) return null;
const { filled, freeCells, usedTokens, freeTokens, usedFraction, overLimit } = allocation;
const interactive = typeof onSegmentClick === 'function';
const level = contextUsageLevel(usedFraction);
const pctText = percent(usedFraction);
// 结论式 aria(§17.6):占最多的分区点名,不依赖视觉传达
const top = filled.reduce<ContextAllocatedSegment | null>(
(best, s) => (best === null || s.tokens > best.tokens ? s : best),
null,
);
const topLabel = top?.label ?? '';
const conclusion =
usedTokens <= 0
? D.conclusionFree(F.compact(limit))
: overLimit
? D.conclusionOver(pctText, topLabel)
: D.conclusionUsed(pctText, topLabel);
const groups: RenderGroup[] = [
...filled
.filter((s) => s.cells > 0)
.map((s) => ({ key: s.key, label: s.label, cells: s.cells, tone: s.tone, tokens: s.tokens })),
...(freeCells > 0
? [{ key: 'free', label: D.free, cells: freeCells, tone: 'neutral' as const, tokens: freeTokens, free: true }]
: []),
];
return (
<div
data-slot="context-usage"
data-ai-component="context-usage"
data-usage-level={level}
data-compact={compact ? 'true' : undefined}
className={cn('space-y-1.5', className)}
{...rest}
>
{/* 格场行:role=img(只读)承载结论式 aria;interactive 时降为 group(img 内禁交互子元素) */}
<div
data-slot="context-usage-grid"
role={interactive ? 'group' : 'img'}
aria-label={conclusion}
className="flex w-full gap-0.5"
>
{groups.map((group) => {
const active = activeKey === group.key;
const dimmed = activeKey !== null && !active;
const share = group.tokens / limit;
const title = `${group.label} ${F.number(group.tokens)} tokens(${percent(share)})`;
const cells = Array.from({ length: group.cells }, (_, i) =>
group.free ? (
<div
key={i}
data-cell
data-free="true"
className="h-2.5 min-w-0 flex-1 rounded-xs border border-dashed border-border"
/>
) : (
<div
key={i}
data-cell
className="h-2.5 min-w-0 flex-1 rounded-xs"
style={{ backgroundColor: TONE_COLOR[group.tone] }}
/>
),
);
const groupProps = {
'data-segment-key': group.key,
'data-cells': group.cells,
'data-active': active || undefined,
'data-dimmed': dimmed || undefined,
className: cn(
'flex min-w-0 gap-0.5 transition-opacity duration-fast ease-standard',
dimmed && 'opacity-40',
),
style: { flexGrow: group.cells, flexBasis: 0 },
onMouseEnter: () => setActiveKey(group.key),
onMouseLeave: () => setActiveKey((k) => (k === group.key ? null : k)),
onFocus: () => setActiveKey(group.key),
onBlur: () => setActiveKey((k) => (k === group.key ? null : k)),
};
const tip = (
<TooltipContent side="top">
<span className="font-medium">{group.label}</span>
<span aria-hidden="true">·</span>
<span className="font-mono tabular-nums">{F.number(group.tokens)} tokens</span>
<span aria-hidden="true">·</span>
<span className="font-mono tabular-nums">{percent(share)}</span>
</TooltipContent>
);
return (
<div key={group.key} {...groupProps}>
<Tooltip>
<TooltipTrigger
render={
interactive ? (
// RawButton:分区热区是「可选中区域」非动作钮(原语层出口的既定用途),
// 形态(无 padding/无底色)完全由本件负责
<RawButton
aria-label={`${group.label},${F.number(group.tokens)} tokens,占 ${percent(share)}`}
title={title}
onClick={() => onSegmentClick(group.key)}
className="flex min-w-0 flex-1 gap-0.5 pointer-coarse:min-h-11"
>
{cells}
</RawButton>
) : (
<div title={title} className="flex min-w-0 flex-1 gap-0.5">
{cells}
</div>
)
}
/>
{tip}
</Tooltip>
</div>
);
})}
</div>
{/* 汇总行:视觉强化,结论已由 aria 承载故 aria-hidden;compact 窄栏省略 */}
{!compact && (
<div
aria-hidden="true"
data-slot="context-usage-summary"
className={cn('flex items-center gap-1.5 text-xs', TONE_CLASS[LEVEL_TONE[level]].text)}
>
<span>{L.used}</span>
<span className="font-mono tabular-nums">{pctText}</span>
<span className="text-content-text-muted">·</span>
<span className="font-mono tabular-nums text-content-text-muted">
{F.compact(usedTokens)} / {F.compact(limit)} tokens
</span>
{overLimit ? <span>{L.overLimit}</span> : null}
</div>
)}
</div>
);
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
模型上下文占用格场:segments + limit 双输入;阈值 70/90 派生 neutral/warning/danger;无窗口上限前禁传估算 limit。