Ordo UI
AI审阅与决策

ApprovalGates

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

approval-gates@mox-hub/patternsSemanticcanonicalsrc/components/approval-gates.tsx
变体演示approval-gates
高风险工具调用

执行数据库迁移

{
  "sql": "ALTER TABLE tasks ADD COLUMN priority int;"
}
低风险文件变更

写入 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*number3—
renderPreview*(gate: ApprovalGate) => ReactNode——
labels*Partial<ApprovalGatesLabels>——
className*string——

源码

packages/patterns/src/components/approval-gates.tsx
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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

多道审批门堆叠:kind=tool|file|agent|message 徽标 + payload 缺省预览 + 超额折叠(真实计数);卡片实现复用 approval-card,本件只管排队与组合。