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> | — | — |
源码
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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
AI 离散判定 + 四档置信信号胶囊;confidence 0-1 与 signal 0-3 双轨,signal 优先;弱信号必须显示低置信标注,判定仅辅助参考。