{
"sql": "ALTER TABLE tasks ADD COLUMN priority int;"
}AI审阅与决策
ApprovalGates
@mox-hub/patterns · AI · 审阅与决策 · canonical
approval-gates@mox-hub/patternsSemanticcanonicalsrc/components/approval-gates.tsx变体演示approval-gates
高风险工具调用
执行数据库迁移
低风险文件变更
写入 Login.tsx
diff --git a/Login.tsx b/Login.tsx
中风险Agent 委派
委派给测试 Agent
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| gates* | ApprovalGate[] | — | — |
| onDecide* | (id: string, decision: ApprovalResolvedState, gate: ApprovalGate) => void | Promise<void> | — | — |
| onDismiss* | (id: string, gate: ApprovalGate) => void | — | — |
| maxVisible* | number | 3 | — |
| renderPreview* | (gate: ApprovalGate) => ReactNode | — | — |
| labels* | Partial<ApprovalGatesLabels> | — | — |
| className* | string | — | — |
源码
import { useState, type ComponentProps, type ReactNode } from 'react';
import { Bot, FileText, MessageSquare, Wrench } from 'lucide-react';
import { cn } from '@mox-hub/ui';
import { Button } from '@mox-hub/ui/components/button';
import { usePatternLabels } from '../lib/i18n';
import {
ApprovalCard,
type ApprovalResolvedState,
} from './approval-card';
import type { ConfidenceSignal } from './ai-verdict-pill';
/**
* ApprovalGates —— 多道审批门的堆叠容器(执行平面)。
*
* affectUI 的 Approval Gates 契约(`kind: tool | file | agent | message`)在
* 本仓的落地方式:**组合** ApprovalCard,而不是重写一张卡。
*
* - 单一实现仍在 `approval-card`:风险档、快捷键、决后收场仪式、受控双模全部复用;
* - 本件只负责「多门排队 + 折叠超额 + kind 徽标 + payload 缺省预览」;
* - `decision-queue-panel` 继续服务「混合决策队列(approval/acceptance/proposal)」,
* 与本件不是同一层:队列管分页与紧迫度,本件管同一屏内的多门堆叠;
* - 超额门折叠为一行计数,展开后全量渲染;计数与展开都是真实数量,不伪造。
*/
export type ApprovalGateKind = 'tool' | 'file' | 'agent' | 'message';
export interface ApprovalGate {
id: string;
kind: ApprovalGateKind;
/** 请求标题(做什么) */
title: string;
/** 请求者节点(人员/Agent 头像等) */
requester?: ReactNode;
riskSignal?: ConfidenceSignal | null;
riskLabel?: ReactNode;
riskNote?: ReactNode;
/** 自定义预览;缺省按 kind 渲染 payload */
preview?: ReactNode;
/** kind 对应的主体:tool 参数 / 文件 diff / agent 计划 / 消息草稿 */
payload?: unknown;
busy?: boolean;
disabled?: boolean;
/** 受控已决态;undefined=非受控(本件自管收场仪式) */
resolved?: ApprovalResolvedState | null;
resolvedLabel?: ReactNode;
}
export interface ApprovalGatesLabels {
region: string;
kindTool: string;
kindFile: string;
kindAgent: string;
kindMessage: string;
more: (count: number) => string;
showAll: string;
empty: string;
}
export const APPROVAL_GATES_DEFAULT_LABELS: ApprovalGatesLabels = {
region: '待审批事项',
kindTool: '工具调用',
kindFile: '文件变更',
kindAgent: 'Agent 委派',
kindMessage: '消息发送',
more: (count) => `还有 ${count} 项待审批`,
showAll: '展开全部',
empty: '没有待审批事项',
};
const KIND_VISUAL = {
tool: { icon: Wrench, className: 'text-accent-blue' },
file: { icon: FileText, className: 'text-accent-orange' },
agent: { icon: Bot, className: 'text-accent-purple' },
message: { icon: MessageSquare, className: 'text-accent-green' },
} as const;
function payloadPreview(payload: unknown): ReactNode {
if (payload === undefined || payload === null) return null;
if (typeof payload === 'string') {
return (
<pre className="max-h-40 overflow-auto overscroll-contain rounded-md bg-content-bg-secondary p-2 font-mono text-2xs whitespace-pre-wrap break-words text-content-text-secondary">
{payload}
</pre>
);
}
try {
return (
<pre className="max-h-40 overflow-auto overscroll-contain rounded-md bg-content-bg-secondary p-2 font-mono text-2xs whitespace-pre-wrap break-words text-content-text-secondary">
{JSON.stringify(payload, null, 2)}
</pre>
);
} catch {
return (
<span className="text-2xs text-content-text-muted">
{String(payload)}
</span>
);
}
}
export interface ApprovalGatesProps
extends Omit<ComponentProps<'section'>, 'children'> {
gates: ApprovalGate[];
onDecide: (
id: string,
decision: ApprovalResolvedState,
gate: ApprovalGate,
) => void | Promise<void>;
onDismiss?: (id: string, gate: ApprovalGate) => void;
/** 收起态最多显示的完整卡数;默认 3 */
maxVisible?: number;
/** kind 预览渲染器;缺省渲染 payload */
renderPreview?: (gate: ApprovalGate) => ReactNode;
labels?: Partial<ApprovalGatesLabels>;
}
export function ApprovalGates({
gates,
onDecide,
onDismiss,
maxVisible = 3,
renderPreview,
labels,
className,
...props
}: ApprovalGatesProps) {
const D = usePatternLabels('approvalGates', APPROVAL_GATES_DEFAULT_LABELS);
const text: ApprovalGatesLabels = {
region: labels?.region ?? D.region,
kindTool: labels?.kindTool ?? D.kindTool,
kindFile: labels?.kindFile ?? D.kindFile,
kindAgent: labels?.kindAgent ?? D.kindAgent,
kindMessage: labels?.kindMessage ?? D.kindMessage,
more: labels?.more ?? D.more,
showAll: labels?.showAll ?? D.showAll,
empty: labels?.empty ?? D.empty,
};
const [expanded, setExpanded] = useState(false);
const visibleCount = expanded
? gates.length
: Math.min(Math.max(maxVisible, 1), gates.length);
const visible = gates.slice(0, visibleCount);
const hidden = gates.length - visibleCount;
const kindLabel: Record<ApprovalGateKind, string> = {
tool: text.kindTool,
file: text.kindFile,
agent: text.kindAgent,
message: text.kindMessage,
};
if (gates.length === 0) {
return (
<section
aria-label={text.region}
data-ai-component="approval.gates"
className={cn(
'rounded-lg border border-content-border bg-content-bg-secondary px-3 py-2 text-xs text-content-text-muted',
className,
)}
{...props}
>
{text.empty}
</section>
);
}
return (
<section
aria-label={text.region}
data-ai-component="approval.gates"
className={cn('space-y-2', className)}
{...props}
>
{visible.map((gate) => {
const visual = KIND_VISUAL[gate.kind];
const Icon = visual.icon;
const badge = (
<span
className={cn(
'inline-flex items-center gap-1 text-2xs text-content-text-muted',
)}
>
<Icon aria-hidden className={cn('size-3', visual.className)} />
{kindLabel[gate.kind]}
</span>
);
return (
<div key={gate.id} data-gate-kind={gate.kind}>
<ApprovalCard
title={gate.title}
requester={
gate.requester ? (
<span className="inline-flex items-center gap-2">
{badge}
{gate.requester}
</span>
) : (
badge
)
}
riskSignal={gate.riskSignal}
riskLabel={gate.riskLabel}
riskNote={gate.riskNote}
preview={
gate.preview ??
renderPreview?.(gate) ??
payloadPreview(gate.payload)
}
busy={gate.busy}
disabled={gate.disabled}
resolved={gate.resolved}
resolvedLabel={gate.resolvedLabel}
onResolve={(action) => onDecide(gate.id, action, gate)}
onDismiss={
onDismiss ? () => onDismiss(gate.id, gate) : undefined
}
/>
</div>
);
})}
{hidden > 0 ? (
<Button
type="button"
variant="ghost"
size="xs"
className="w-full justify-center text-content-text-muted"
onClick={() => setExpanded(true)}
>
{text.more(hidden)} · {text.showAll}
</Button>
) : null}
</section>
);
}
可访问性与 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。
用法说明
多道审批门堆叠:kind=tool|file|agent|message 徽标 + payload 缺省预览 + 超额折叠(真实计数);卡片实现复用 approval-card,本件只管排队与组合。