Ordo UI
AI审阅与决策

AiVerdictPill

@mox-hub/patterns · AI · 审阅与决策 · canonical

ai-verdict-pill@mox-hub/patternsSemanticcanonicalsrc/components/ai-verdict-pill.tsx
变体演示ai-verdict-pill
建议批准92%建议复核52%低置信证据不足倾向拒绝低置信直传良信号

Props API

Prop类型默认值说明
label*string——
confidence*number——
signal*ConfidenceSignal——
size*"xs" | "sm""sm"—
className*string——
labels*Partial<AiVerdictPillLabels>——

源码

packages/patterns/src/components/ai-verdict-pill.tsx
import {
  SignalHigh,
  SignalLow,
  SignalMedium,
  SignalZero,
  Sparkles,
} from "lucide-react";
import type { LucideIcon } from "lucide-react";
import { cn } from "@mox-hub/ui";
import { usePatternLabels } from "../lib/i18n";

/**
 * 四档置信信号枚举(宪法 §22 / 组件规划账本 A4,CAP-A-27 JEV):
 * 0=无信号 · 1=弱信号 · 2=良信号 · 3=强信号。
 * AI 置信度本就是模糊量——四档枚举比伪精度小数诚实,且对脏数据免疫。
 */
export type ConfidenceSignal = 0 | 1 | 2 | 3;

/**
 * 数值置信度 → 档位折算口径(**集中定义处**,ai-verdict-pill / confidence-bar 两件共用,
 * 供后续统一调整):0-1 口径下 ≥0.85 → 强 / ≥0.60 → 良 / ≥0.30 → 弱 / 其余 → 无信号。
 * 后端 0-100 概率等价 ≥85 / ≥60 / ≥30——调用方先 /100 再传入。
 */
export const CONFIDENCE_SIGNAL_THRESHOLDS = {
  strong: 0.85,
  fair: 0.6,
  weak: 0.3,
} as const;

/**
 * 防御性归一:任何输入收敛到合法档(0-3)。
 * Number() 转换(字符串数字可救)→ NaN/Infinity → 0(无信号)→ round + clamp。
 */
export function normalizeConfidenceSignal(input: unknown): ConfidenceSignal {
  const n = Number(input);
  if (!Number.isFinite(n)) return 0;
  return Math.min(3, Math.max(0, Math.round(n))) as ConfidenceSignal;
}

/**
 * 0-1 数值置信度 → 档位(轨 A 兼容折算,阈值见 {@link CONFIDENCE_SIGNAL_THRESHOLDS})。
 * null/undefined = 「无置信度」缺席语义,返回 null(区别于「有值但收敛到无信号」的 0)。
 */
export function confidenceToSignal(
  value: number | null | undefined,
): ConfidenceSignal | null {
  if (value === null || value === undefined) return null;
  const n = Number(value);
  if (!Number.isFinite(n) || n <= 0) return 0;
  if (n >= CONFIDENCE_SIGNAL_THRESHOLDS.strong) return 3;
  if (n >= CONFIDENCE_SIGNAL_THRESHOLDS.fair) return 2;
  if (n >= CONFIDENCE_SIGNAL_THRESHOLDS.weak) return 1;
  return 0;
}

/** 档位 → 胶囊视觉(§5.3 语义色表状态:无=中性灰 · 弱=黄 · 良=蓝 · 强=绿)。 */
const TIER_PILL_VISUALS: Record<ConfidenceSignal, string> = {
  0: "border-border bg-muted/40 text-content-text-muted",
  1: "border-accent-yellow/30 bg-accent-yellow-light/40 text-accent-yellow",
  2: "border-accent-blue/30 bg-accent-blue-light/40 text-accent-blue",
  3: "border-accent-green/30 bg-accent-green-light/40 text-accent-green",
};

/** 档位 → 信号图标(§8.5 第 4 条:档位不得只靠颜色传达——图标格数即档位)。 */
const TIER_SIGNAL_ICON: Record<ConfidenceSignal, LucideIcon> = {
  0: SignalZero,
  1: SignalLow,
  2: SignalMedium,
  3: SignalHigh,
};

/** 组件内文案缺省(中文常量;消费方经 labels 覆写接入 i18n)。 */
export interface AiVerdictPillLabels {
  /** tooltip:AI 判定仅辅助参考 */
  advisory: string;
  /** 弱信号低置信标注 */
  lowConfidence: string;
}

export const AI_VERDICT_PILL_DEFAULT_LABELS: AiVerdictPillLabels = {
  advisory: "AI 快速判断 · 仅辅助参考,不改变判定权",
  lowConfidence: "低置信",
};

export interface AiVerdictPillProps {
  /** 判定文案(调用方按场景翻译结论,如「建议批准」「benign」) */
  label: string;
  /** [轨 A·兼容] 置信度 0-1;内部按 A4 口径折算档位渲染,有限值照常显示百分比。
   *  null/undefined = 无置信度(不渲染百分比)。 */
  confidence?: number | null;
  /** [轨 B·新增] 四档信号直传(0=无/1=弱/2=良/3=强),优先于 confidence;
   *  直传态以信号图标呈现(不渲染百分比)。运行时经 normalizeConfidenceSignal 防御性归一。 */
  signal?: ConfidenceSignal | null;
  size?: "xs" | "sm";
  className?: string;
  /** 文案覆写(默认 zh-CN;主仓 i18n 适配层集中传入 t() 结果)。 */
  labels?: Partial<AiVerdictPillLabels>;
}

/**
 * AiVerdictPill —— [AI] JEV 快速判断徽注(四档置信信号)。
 *
 * 离散判定 + 四档置信信号的统一呈现;tooltip 恒挂「仅辅助参考」advisory 声明。
 * 视觉四档:无信号=中性灰 · 弱=黄(标低置信)· 良=蓝 · 强=绿。
 * 双轨入参:confidence(0-1 数值,展示层折算)或 signal(档位直传),signal 优先。
 * 无判定时由调用方整块隐藏——本组件不渲染「AI 失败」噪音。
 */
export function AiVerdictPill({
  label,
  confidence,
  signal,
  size = "sm",
  className,
  labels,
}: AiVerdictPillProps) {
  const D = usePatternLabels("aiVerdictPill", AI_VERDICT_PILL_DEFAULT_LABELS);
  const advisory = labels?.advisory ?? D.advisory;
  const lowConfidence = labels?.lowConfidence ?? D.lowConfidence;
  const direct = signal !== null && signal !== undefined;
  const tier: ConfidenceSignal | null = direct
    ? normalizeConfidenceSignal(signal)
    : confidenceToSignal(confidence);
  const hasConfidence = tier !== null;
  const level: ConfidenceSignal = tier ?? 0;
  // 轨 A 数值态:有限置信度照常显示百分比(NaN/直传档不显示)
  const numeric =
    !direct && hasConfidence && confidence != null && Number.isFinite(confidence);
  const SignalIcon = TIER_SIGNAL_ICON[level];
  return (
    <span
      title={advisory}
      data-ai-component="ai-verdict-pill"
      data-confidence={numeric ? confidence : undefined}
      data-confidence-signal={hasConfidence ? level : undefined}
      className={cn(
        "inline-flex max-w-full shrink-0 items-center gap-1 rounded-full border px-1.5 py-0.5 font-medium",
        TIER_PILL_VISUALS[level],
        size === "xs" ? "text-2xs" : "text-xs",
        className,
      )}
    >
      <Sparkles className={cn("shrink-0", size === "xs" ? "size-2.5" : "size-3")} />
      <span className="truncate">{label}</span>
      {numeric && (
        <span className="font-mono tabular-nums opacity-80">
          {Math.round((confidence as number) * 100)}%
        </span>
      )}
      {direct && (
        <SignalIcon
          aria-hidden
          className={cn("shrink-0", size === "xs" ? "size-2.5" : "size-3")}
        />
      )}
      {level === 1 && (
        <span className="shrink-0 text-2xs opacity-90">{lowConfidence}</span>
      )}
    </span>
  );
}

可访问性与 RTL

  • 键盘:交互件保留:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。
  • RTL:间距、对齐与方向性图标使用逻辑属性 (ms-* /text-start /rtl:-scale-x-100);通过 ThemeProvider 或I18nProvider 的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。
  • 文案:优先用组件labels /translate /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

AI 离散判定 + 四档置信信号胶囊;confidence 0-1 与 signal 0-3 双轨,signal 优先;弱信号必须显示低置信标注,判定仅辅助参考。