Ordo UI
AI助手与对话

AssistantToolCard

@mox-hub/patterns · AI · 助手与对话 · canonical

assistant-tool-card@mox-hub/patternsAI Executioncanonicalsrc/components/assistant-tool-card.tsx
变体演示assistant-tool-card
查询任务 已完成

0 条结果

内联决策卡(由消费方注入)

Props API

Prop类型默认值说明
part*AssistantToolPart——
defaultOpen*booleanfalse—
open*boolean——
onOpenChange*(open: boolean) => void——
startedAt*number——
duration*number——
autoOpenOnError*booleantrue—
maxCodeHeight*number220—
className*string——
translator*PatternTranslate——
renderDecision*(output: unknown) => ReactNode——
resolveEntity*(entity: AssistantToolEntityInput) => AssistantToolEntityView——
toolPresentation*AssistantToolPresentation——

源码

packages/patterns/src/components/assistant-tool-card.tsx
/**
 * 工具调用卡 —— UIMessage tool-* part 的对话内渲染(对齐 zcode 工具块形态 + 宪法 §22)。
 * 折叠头 = 状态图标(调用中/完成/失败)+ 动作标签(动词×实体组合)+ 摘要 + 计时;
 * 展开体 = 输入参数 / 结果预览(JSON 高亮、高度封顶渐隐)/ 错误信息。
 * 实体类输出渲染实体行卡(图标+标题+状态+详情跳转);列表输出渲染结果数+样例;
 * propose_decision 输出内联决策卡(复用 DecisionCard 文法,决议走 useDecisionActions)。
 *
 * §22.5 活性可感知:运行中 live 计时(100ms tick,重试间歇累加);
 * 状态迁移经 role="status" aria-live="polite" 播报;折叠区 inert 防焦点落入。
 * AssistantToolGroup 把连续多卡汇总为一行(计数/用时/失败数从 parts 现算,§22.2);
 * 实体跳转不再内置业务路由,由 resolveEntity 注入,工具词表由 toolPresentation 注入。
 */
import {
  Children,
  Fragment,
  isValidElement,
  useId,
  useEffect,
  useLayoutEffect,
  useRef,
  useState,
  type ComponentProps,
  type ReactElement,
  type ReactNode,
} from 'react';
import {
  AlertCircle,
  Bug,
  CheckCircle2,
  ChevronDown,
  ChevronRight,
  FileText,
  Flag,
  FolderKanban,
  ListTodo,
  PauseCircle,
  Repeat,
  Tag,
  Target,
  Users,
  Wrench,
  XCircle,
  type LucideIcon,
} from 'lucide-react';
import { cn } from '@mox-hub/ui';
import { createTranslator, type PatternTranslate } from '../lib/translate';
import { usePatternTranslate } from '../lib/i18n';
import { asRecord, JsonPreview, toText } from '../lib/json-preview';
// 账本 G3 收编:渐进精度时长唯一口径在 @/lib/format,本地别名保留原私有函数名
import { formatLiveDuration as formatMs } from '@mox-hub/ui/format';
import { Spinner } from '@mox-hub/ui/components/spinner';

/** UIMessage tool-* part 的防御性形状(ai 包类型在 jsdom 测试里不便直接引用) */
export interface AssistantToolPart {
  type: string;
  toolName?: string;
  state?: string;
  input?: unknown;
  output?: unknown;
  errorText?: string;
}

/**
 * 工具名词表:动词/实体 token → 翻译 key(或字面文案,经 translator 原样返回)。
 * 缺省仅内置与业务无关的通用词表;未命中的 token 由 toolName 原样回退。
 */
export interface AssistantToolPresentation {
  verbs?: Record<string, string>;
  entities?: Record<string, string>;
}

/** resolveEntity 入参:命中的 ID 字段名、ID 值与原始输出对象 */
export interface AssistantToolEntityInput {
  idField: string;
  id: string;
  output: Record<string, unknown>;
}

/** resolveEntity 返回:href 由消费方注入;未给则不渲染跳转链接 */
export interface AssistantToolEntityView {
  href?: string;
  title?: string;
  icon?: LucideIcon;
  status?: string;
}

/** 单个工具调用的计时(供组行汇总;与 parts 索引对齐) */
export interface AssistantToolTiming {
  startedAt?: number;
  duration?: number;
}

/** 工具卡三态(§22.5:状态迁移必须可播报) */
export type ToolPartStatus = 'running' | 'success' | 'error';

/**
 * AI SDK 工具调用的七态(对齐 UI Message Stream 的 part.state)。
 *
 * 这里只做**归一**,不做语义推断:未知值一律落到 `input-available`
 * (最保守的「参数已就绪、尚未产出」态),保证旧消费方传任意字符串都能渲染。
 */
export type ToolPartPhase =
  | 'input-streaming'
  | 'input-available'
  | 'approval-requested'
  | 'approval-responded'
  | 'approval-denied'
  | 'output-available'
  | 'output-error'
  | 'output-denied';

export function toolPartPhase(part: AssistantToolPart): ToolPartPhase {
  switch (part.state) {
    case 'input-streaming':
    case 'input-available':
    case 'approval-requested':
    case 'approval-responded':
    case 'approval-denied':
    case 'output-available':
    case 'output-error':
    case 'output-denied':
      return part.state;
    default:
      return 'input-available';
  }
}

/** part 状态归一:output-error / output-denied → error;有产出无错 → success;其余 running */
export function toolPartStatus(part: AssistantToolPart): ToolPartStatus {
  if (part.state === 'output-error' || part.state === 'output-denied') return 'error';
  if (part.state === 'output-available') {
    return outputError(part.output) ? 'error' : 'success';
  }
  return 'running';
}

/**
 * 决策建议工具是否独立渲染:propose_decision 的产出是「等人裁决」的一等状态
 * (宪法 §22.1),始终独立成卡,绝不折叠进工具组。
 */
export function isDecisionToolPart(part: AssistantToolPart): boolean {
  return part.toolName === 'propose_decision';
}

export interface AssistantToolCardProps extends Omit<ComponentProps<'div'>, 'children' | 'part'> {
  // part 与 HTML 全局属性 part?: string 撞名,须从基类 Omit 后才能收窄为 AssistantToolPart
  part: AssistantToolPart;
  /** 非受控初始展开态 */
  defaultOpen?: boolean;
  /** 受控展开态(传入后失败自动展开/收起不再干预) */
  open?: boolean;
  onOpenChange?: (open: boolean) => void;
  /** 本次调用开始时间(服务端毫秒时间戳);缺省从挂载起算 */
  startedAt?: number;
  /** 最终耗时(ms),覆盖实测值;历史消息补不回计时时不传则不显示(不造假数) */
  duration?: number;
  /** 失败自动展开 / 恢复自动收起(默认开) */
  autoOpenOnError?: boolean;
  /** 参数/结果代码块封顶高度(px),超出渐隐 + 显示全部 */
  maxCodeHeight?: number;
  /** 文案覆写(主仓 i18n 适配层集中传入 t() 包装)。 */
  translator?: PatternTranslate;
  /** propose_decision 完整输出时的决策卡渲染器(主仓注入 DecisionCard)。 */
  renderDecision?: (output: unknown) => ReactNode;
  /**
   * 实体输出解析器:注入标题/图标/状态/跳转(href)。
   * 缺省只返回 { title, status },不生成任何业务路由;返回 null 时回退默认标题/图标。
   */
  resolveEntity?: (entity: AssistantToolEntityInput) => AssistantToolEntityView | null;
  /** 工具名词表;缺省仅通用词表(create/update/delete/list/get × task/project/...)。 */
  toolPresentation?: AssistantToolPresentation;
}

type TFunc = (key: string, options?: Record<string, unknown>) => string;

/** 组件内文案缺省(zh-CN;消费方经 translate 注入 i18n t 包装)。 */
const TOOL_CARD_LABELS: Record<string, string> = {
  'assistant.tool.input': '输入',
  'assistant.tool.output': '结果',
  'assistant.tool.error': '出错',
  'assistant.tool.resultCount': '{{count}} 条结果',
  'assistant.tool.view': '查看',
  'assistant.tool.showAll': '显示全部',
  'assistant.tool.collapse': '收起',
  'assistant.tool.running': '正在调用工具',
  'assistant.tool.runningEllipsis': '正在调用工具…',
  'assistant.tool.preparing': '准备参数中',
  'assistant.tool.approvalRequested': '等待批准',
  'assistant.tool.approvalResponded': '已批准',
  'assistant.tool.approvalDenied': '已拒绝',
  'assistant.tool.outputDenied': '调用被拒绝',
  'assistant.tool.used': '已用 {{count}} 个工具',
  'assistant.tool.usedWithFailures': '已用 {{count}} 个工具,{{failed}} 个失败',
  'assistant.tool.failedCount': '{{count}} 个失败',
  'assistant.tool.statusRunning': '{{action}} 运行中',
  'assistant.tool.statusSuccess': '{{action}} 已完成',
  'assistant.tool.statusError': '{{action}} 失败',
  'assistant.tool.deleted': '已删除',
  'assistant.tool.verb.create': '创建',
  'assistant.tool.verb.update': '更新',
  'assistant.tool.verb.delete': '删除',
  'assistant.tool.verb.list': '查询',
  'assistant.tool.verb.get': '查看',
  'assistant.tool.verb.resolve': '裁决',
  'assistant.tool.verb.archive': '归档',
  'assistant.tool.verb.deactivate': '停用',
  'assistant.tool.verb.propose': '提交',
  'assistant.tool.entity.task': '任务',
  'assistant.tool.entity.project': '项目',
  'assistant.tool.entity.projectOverview': '项目概览',
  'assistant.tool.entity.document': '文档',
  'assistant.tool.entity.member': '成员',
  'assistant.tool.entity.team': '团队',
  'assistant.tool.entity.iteration': '迭代',
  'assistant.tool.entity.milestone': '里程碑',
  'assistant.tool.entity.acceptance': '验收单',
  'assistant.tool.entity.decision': '决策建议',
  'assistant.tool.entity.projectTasks': '项目任务',
  'assistant.tool.entity.taskAcceptances': '任务验收单',
  'assistant.tool.entity.pendingDecisions': '待决提案',
  'assistant.tool.entity.projectStatuses': '状态定义',
  'assistant.tool.entity.projectRoles': '项目角色',
  'assistant.tool.entity.repositories': '仓库',
};

const defaultToolT = createTranslator(TOOL_CARD_LABELS);

/**
 * 通用词表:只覆盖与业务无关的常见动词/实体,不绑定任何 ordo 路由。
 * 消费方经 toolPresentation 覆盖或扩展;未命中组合一律回退 toolName 原文。
 */
const DEFAULT_VERB_KEYS: Record<string, string> = {
  create: 'assistant.tool.verb.create',
  update: 'assistant.tool.verb.update',
  delete: 'assistant.tool.verb.delete',
  list: 'assistant.tool.verb.list',
  get: 'assistant.tool.verb.get',
};

const DEFAULT_ENTITY_KEYS: Record<string, string> = {
  task: 'assistant.tool.entity.task',
  project: 'assistant.tool.entity.project',
  document: 'assistant.tool.entity.document',
  member: 'assistant.tool.entity.member',
  team: 'assistant.tool.entity.team',
};

/** 动词×实体组合显示名;未知工具回退原名(toolPresentation 覆盖通用词表) */
function toolActionLabel(
  toolName: string,
  t: TFunc,
  presentation?: AssistantToolPresentation,
): string {
  const sep = toolName.indexOf('_');
  if (sep > 0) {
    const verbs = { ...DEFAULT_VERB_KEYS, ...presentation?.verbs };
    const entities = { ...DEFAULT_ENTITY_KEYS, ...presentation?.entities };
    const verbKey = verbs[toolName.slice(0, sep)];
    const entityKey = entities[toolName.slice(sep + 1)];
    if (verbKey && entityKey) return `${t(verbKey)}${t(entityKey)}`;
  }
  return toolName;
}

const ENTITY_ICONS: Record<string, LucideIcon> = {
  task: ListTodo,
  project: FolderKanban,
  document: FileText,
  member: Users,
  team: Users,
  iteration: Repeat,
  milestone: Flag,
  label: Tag,
  acceptance: Target,
};

/** 输出里的实体 ID 字段(与工具返回形状一一对应) */
const ENTITY_ID_FIELDS = [
  'issueId',
  'projectId',
  'documentId',
  'memberId',
  'teamId',
  'iterationId',
  'milestoneId',
  'labelId',
  'acceptanceId',
] as const;

function outputError(output: unknown): string | null {
  const o = asRecord(output);
  const err = o?.error;
  return typeof err === 'string' && err ? err : null;
}

/** 实体默认标题:title / name / displayName 首个非空字符串,否则回退 ID */
function defaultEntityTitle(output: Record<string, unknown>, id: string): string {
  return (
    [output.title, output.name, output.displayName].find(
      (v): v is string => typeof v === 'string' && v.length > 0,
    ) ?? id
  );
}

/** 缺省实体解析:只给标题/状态,不生成任何业务路由 */
function defaultResolveEntity({
  id,
  output,
}: AssistantToolEntityInput): AssistantToolEntityView {
  return {
    title: defaultEntityTitle(output, id),
    status: typeof output.status === 'string' ? output.status : undefined,
  };
}

/** 缺省图标:bug 用 Bug,其余按 ID 字段名映射,未知回退 ListTodo */
function defaultEntityIcon(
  idField: string,
  output: Record<string, unknown>,
): LucideIcon {
  return idField === 'issueId' && output.type === 'bug'
    ? Bug
    : (ENTITY_ICONS[idField.replace(/Id$/, '')] ?? ListTodo);
}

type EntityView = {
  icon: LucideIcon;
  title: string;
  status?: string;
  href?: string;
};

/** 实体工具输出 → {icon, title, status, href};非实体输出返回 null */
function entityView(
  output: unknown,
  resolveEntity?: (entity: AssistantToolEntityInput) => AssistantToolEntityView | null,
): EntityView | null {
  const o = asRecord(output);
  if (!o) return null;
  let idField: string | null = null;
  let id = '';
  for (const field of ENTITY_ID_FIELDS) {
    if (typeof o[field] === 'string' && o[field]) {
      idField = field;
      id = o[field] as string;
      break;
    }
  }
  if (!idField) return null;
  const target: AssistantToolEntityInput = { idField, id, output: o };
  const resolved = resolveEntity ? resolveEntity(target) : null;
  // 注入解析器返回 null → 回退默认标题/图标(仍然不生成路由)
  const view = resolved ?? defaultResolveEntity(target);
  return {
    icon: view.icon ?? defaultEntityIcon(idField, o),
    title: view.title ?? defaultEntityTitle(o, id),
    status: view.status ?? (typeof o.status === 'string' ? o.status : undefined),
    // 删除态不保留跳转(沿用旧行为)
    href: o.deleted === true ? undefined : view.href,
  };
}

/** 列表型输出 → {count, samples};非列表返回 null */
function listView(output: unknown): { count: number; samples: string[] } | null {
  const o = asRecord(output);
  if (!o) return null;
  const arr = Object.values(o).find((v) => Array.isArray(v)) as unknown[] | undefined;
  if (!arr) return null;
  const samples = arr
    .slice(0, 3)
    .map((item) => {
      const rec = asRecord(item);
      const title = rec
        ? ([rec.title, rec.name, rec.displayName].find(
            (v): v is string => typeof v === 'string' && v.length > 0,
          ) ?? '')
        : '';
      return title;
    })
    .filter(Boolean);
  return { count: arr.length, samples };
}

/** 输入参数摘要:取第一个有业务含义的字符串字段 */
function inputSummary(input: unknown): string | null {
  const o = asRecord(input);
  if (!o) return null;
  for (const key of ['title', 'name', 'displayName', 'question', 'issueId', 'acceptanceId', 'documentId', 'projectId']) {
    const v = o[key];
    if (typeof v === 'string' && v) return v;
  }
  return null;
}

/* ---------- 计时(§22.2/§22.5 成本一等公民 · 活性可感知) ---------- */

/**
 * 运行段秒表:running 时 live 计时(100ms tick);暂停→重启多段累加(重试不从零重计)。
 * startedAt(服务端时间)仅在首段生效——重试段一律从当下起算,避免从旧起点重复计时;
 * 无任何实测数据时返回 null(历史消息诚实降级,不造假数)。
 */
function useStopwatch(running: boolean, startedAt?: number): number | null {
  const startRef = useRef<number | null>(null);
  const baseRef = useRef(0);
  const [ms, setMs] = useState<number | null>(null);
  useEffect(() => {
    if (!running) {
      if (startRef.current !== null) {
        baseRef.current += Math.max(0, Date.now() - startRef.current);
        startRef.current = null;
        setMs(baseRef.current);
      }
      return;
    }
    if (startRef.current === null) {
      const firstSegment = baseRef.current === 0;
      startRef.current =
        firstSegment && startedAt !== undefined ? startedAt : Date.now();
    }
    const tick = () =>
      setMs(
        Math.max(0, baseRef.current + Date.now() - (startRef.current ?? Date.now())),
      );
    tick();
    const timer = window.setInterval(tick, 100);
    return () => window.clearInterval(timer);
  }, [running, startedAt]);
  return ms;
}

/* ---------- 高度封顶三段式(防巨型卡片) ---------- */

const OPEN_MAX = 640;

const CODE_CLASS =
  'relative overflow-hidden rounded-md bg-content-bg-secondary px-2 py-1.5 font-mono text-2xs leading-relaxed break-all whitespace-pre-wrap text-content-text-secondary';

/**
 * 代码块三段式:自然高 > cap+24 → 底部渐隐 + 「显示全部」;
 * 展开后 > 640px → 改内部滚动(overscroll-contain 防滚动穿透)。
 * 自然高用 ResizeObserver 实测(内容流式增长时跟随重测)。
 */
function CappedCode({ text, json, cap }: { text: string; json: boolean; cap: number }) {
  const t = usePatternTranslate('assistantToolCard', TOOL_CARD_LABELS);
  const preRef = useRef<HTMLPreElement>(null);
  const [full, setFull] = useState(false);
  const [height, setHeight] = useState(0);
  useLayoutEffect(() => {
    const el = preRef.current;
    const inner = el?.firstElementChild;
    if (!el || !inner) return;
    const measure = () => setHeight(el.scrollHeight);
    measure();
    if (typeof ResizeObserver === 'undefined') return;
    const ro = new ResizeObserver(measure);
    ro.observe(inner);
    return () => ro.disconnect();
  }, [text]);
  const capped = height > cap + 24;
  const scroll = capped && full && height > OPEN_MAX;
  return (
    <div className="min-w-0">
      <pre
        ref={preRef}
        className={cn(CODE_CLASS, scroll && 'overflow-y-auto overscroll-contain')}
        data-capped={capped && !full ? '' : undefined}
        data-scroll={scroll ? '' : undefined}
        style={capped ? { maxHeight: full ? Math.min(height, OPEN_MAX) : cap } : undefined}
      >
        <code>
          <JsonPreview text={text} json={json} />
        </code>
        {capped && !full ? (
          <span
            aria-hidden
            className="pointer-events-none absolute inset-x-1 bottom-0 h-8 bg-gradient-to-t from-content-bg-secondary to-transparent"
          />
        ) : null}
      </pre>
      {capped ? (
        <button
          type="button"
          aria-expanded={full}
          onClick={() => setFull((v) => !v)}
          className="mt-0.5 rounded-sm px-1 py-0.5 text-2xs text-content-text-secondary transition-colors duration-fast hover:bg-muted hover:text-content-text focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring/50"
        >
          {full ? t('assistant.tool.collapse') : t('assistant.tool.showAll')}
        </button>
      ) : null}
    </div>
  );
}

/** 展开体:输入参数 pretty-print + JSON 高亮(非对象原样展示) */
function InputCode({ input, cap }: { input: unknown; cap: number }) {
  const o = asRecord(input);
  if (o && Object.keys(o).length === 0) return null;
  const { text, json } = toText(input);
  if (!text) return null;
  return <CappedCode text={text} json={json} cap={cap} />;
}

/** 展开体:兜底结果预览(无实体/列表语义时才展示) */
function OutputCode({ output, cap }: { output: unknown; cap: number }) {
  const { text, json } = toText(output);
  if (!text || text === '{}') return null;
  return <CappedCode text={text} json={json} cap={cap} />;
}

/* ---------- 结果行(常显) ---------- */

/** 结果行:可读错误(红色,常显) */
function ErrorLine({ message }: { message: string }) {
  return (
    <p className="flex items-start gap-1 break-all text-xs text-accent-red">
      <AlertCircle className="mt-0.5 size-3 shrink-0" />
      {message}
    </p>
  );
}

/** 结果行:实体卡(图标+标题+状态+详情跳转,常显) */
function EntityRow({
  entity,
  output,
  translator,
}: {
  entity: EntityView;
  output: unknown;
  translator?: PatternTranslate;
}) {
  const t = translator ?? defaultToolT;
  const Icon = entity.icon;
  return (
    <div className="flex items-center gap-1.5 rounded-md bg-content-bg-secondary/60 px-2 py-1 text-xs">
      <Icon className="size-3.5 shrink-0 text-accent-purple" />
      <span className="min-w-0 flex-1 truncate font-medium text-content-text">
        {asRecord(output)?.deleted === true
          ? t('assistant.tool.deleted')
          : entity.title}
      </span>
      {entity.status ? (
        <span className="shrink-0 rounded-full bg-accent-blue-light px-1.5 py-0.5 text-3xs text-accent-blue">
          {entity.status}
        </span>
      ) : null}
      {entity.href ? (
        <a
          href={entity.href}
          className="shrink-0 rounded-sm text-accent-blue underline-offset-2 hover:underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
        >
          {t('assistant.tool.view')}
        </a>
      ) : null}
    </div>
  );
}

/** 结果行:列表样例(结果数 + 前 3 条标题,常显) */
function ListSamples({
  output,
  translator,
}: {
  output: unknown;
  translator?: PatternTranslate;
}) {
  const t = translator ?? defaultToolT;
  const list = listView(output);
  if (!list) return null;
  return (
    <div className="space-y-0.5 text-xs text-content-text-secondary">
      <p>{t('assistant.tool.resultCount', { count: list.count })}</p>
      {list.samples.map((sample) => (
        <p key={sample} className="truncate ps-2 text-content-text-muted">
          · {sample}
        </p>
      ))}
    </div>
  );
}

/* ---------- 决策建议内联卡 ---------- */

/** propose_decision 完整输出 → 由消费方注入决策卡(库内不依赖决策实现)。 */
function ProposedDecisionInline({
  output,
  renderDecision,
}: {
  output: unknown;
  renderDecision: (output: unknown) => ReactNode;
}) {
  const o = asRecord(output) ?? {};
  const proposalId = typeof o.proposalId === 'string' ? o.proposalId : '';
  const kind = typeof o.kind === 'string' ? o.kind : '';
  const title = typeof o.title === 'string' ? o.title : '';
  if (!proposalId || !kind || !title) return null;
  return (
    <div className="w-full" data-ai-component="assistant.tool-decision">
      {renderDecision(output)}
    </div>
  );
}

/* ---------- 主组件 ---------- */

/** 折叠体三态样式:hover bg-accent + focus ring(§8.1),时长白名单 duration-fast(§7.1) */
const HEAD_INTERACTION_CLASS =
  'transition-colors duration-fast hover:bg-muted focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring/50';

/** 工具调用折叠卡(对齐 zcode:默认收起一行,点开看输入/输出;失败自动展开) */
export function AssistantToolCard({
  part,
  defaultOpen = false,
  open: openProp,
  onOpenChange,
  startedAt,
  duration,
  autoOpenOnError = true,
  maxCodeHeight = 220,
  className,
  translator,
  renderDecision,
  resolveEntity,
  toolPresentation,
  ...rootProps
}: AssistantToolCardProps) {
  const providerT = usePatternTranslate('assistantToolCard', TOOL_CARD_LABELS);
  const t = translator ?? providerT;
  const bodyId = useId();
  const [openState, setOpenState] = useState(defaultOpen);
  const open = openProp ?? openState;
  const setOpen = (next: boolean) => {
    if (openProp === undefined) setOpenState(next);
    onOpenChange?.(next);
  };

  const status = toolPartStatus(part);
  const phase = toolPartPhase(part);

  // 失败自动展开 / 恢复运行或成功自动收起:渲染期比对 prevStatus(§22.5)。
  // autoOpened 标记「当前展开来自自动干预」;用户手动切换过(userToggled)或受控 open 传入时不再自动干预。
  const [prevStatus, setPrevStatus] = useState(status);
  const [autoOpened, setAutoOpened] = useState(false);
  const [userToggled, setUserToggled] = useState(false);
  // 展开体懒挂载:首次展开才渲染内容(收起的卡不背隐藏 DOM 重量,§21 渲染期开销),收起后保留以便 inert 生效
  const [everOpened, setEverOpened] = useState(open);
  if (open && !everOpened) {
    setEverOpened(true);
  }
  if (status !== prevStatus) {
    setPrevStatus(status);
    if (openProp === undefined && autoOpenOnError) {
      if (status === 'error' && !userToggled && !openState) {
        setOpenState(true);
        setAutoOpened(true);
      } else if (prevStatus === 'error' && autoOpened && !userToggled) {
        setOpenState(false);
        setAutoOpened(false);
      }
    }
  }

  const elapsed = useStopwatch(status === 'running', startedAt);
  const ms = status === 'running' ? elapsed : (duration ?? elapsed);

  const toolName =
    typeof part.toolName === 'string' && part.toolName
      ? part.toolName
      : part.type.slice('tool-'.length);
  const state = phase;
  const error =
    phase === 'output-error' || phase === 'output-denied'
      ? part.errorText
      : outputError(part.output);
  const done = status === 'success';

  // 决策建议卡:完整输出 → 内联 DecisionCard;残缺输出走普通折叠卡
  const out = asRecord(part.output) ?? {};
  const canInlineDecision =
    toolName === 'propose_decision' &&
    done &&
    typeof out.proposalId === 'string' &&
    !!out.proposalId &&
    typeof out.kind === 'string' &&
    !!out.kind &&
    typeof out.title === 'string' &&
    !!out.title;
  if (canInlineDecision && renderDecision) {
    return (
      <ProposedDecisionInline output={part.output} renderDecision={renderDecision} />
    );
  }

  const actionLabel = toolActionLabel(toolName, t as unknown as TFunc, toolPresentation);
  const entity = done ? entityView(part.output, resolveEntity) : null;
  const list = done && !entity ? listView(part.output) : null;
  const summary = done
    ? (entity?.title ??
      (list ? t('assistant.tool.resultCount', { count: list.count }) : null))
    : inputSummary(part.input);
  const hasBody = part.input !== undefined || part.output !== undefined || !!error;
  const hasAlwaysVisible = !!error || !!entity || !!list;

  // 七态中需要额外文案的中间态(其余沿用三态播报)
  const phaseNote =
    phase === 'approval-requested'
      ? t('assistant.tool.approvalRequested')
      : phase === 'input-streaming'
        ? t('assistant.tool.preparing')
        : phase === 'output-denied' || phase === 'approval-denied'
          ? t('assistant.tool.outputDenied')
          : null;

  // §22.5:状态迁移经 live region 播报(中文,不带句号)
  const announce =
    phase === 'approval-requested'
      ? `${actionLabel} ${t('assistant.tool.approvalRequested')}`
      : phase === 'input-streaming'
        ? `${actionLabel} ${t('assistant.tool.preparing')}`
        : phase === 'output-denied' || phase === 'approval-denied'
          ? `${actionLabel} ${t('assistant.tool.outputDenied')}`
          : status === 'running'
            ? t('assistant.tool.statusRunning', { action: actionLabel })
            : status === 'success'
              ? t('assistant.tool.statusSuccess', { action: actionLabel })
              : t('assistant.tool.statusError', { action: actionLabel });

  return (
    <div
      {...rootProps}
      className={cn(
        'w-full overflow-hidden rounded-lg border border-border bg-background/40',
        className,
      )}
      data-ai-component="assistant.tool-card"
      data-tool-state={state}
      data-tool-status={status}
      data-open={open || undefined}
    >
      <span role="status" aria-live="polite" className="sr-only">
        {announce}
      </span>
      <button
        type="button"
        onClick={() => {
          if (!hasBody) return;
          // 手动接管:此后自动开合不再干预
          setUserToggled(true);
          setAutoOpened(false);
          setOpen(!open);
        }}
        className={cn(
          'flex w-full items-center gap-1.5 rounded-lg px-2.5 py-1.5 text-start text-xs',
          HEAD_INTERACTION_CLASS,
        )}
        aria-expanded={open}
        aria-controls={hasBody ? bodyId : undefined}
      >
        {done ? (
          <CheckCircle2 className="size-3.5 shrink-0 text-accent-green" />
        ) : error ? (
          <XCircle className="size-3.5 shrink-0 text-accent-red" />
        ) : phase === 'approval-requested' ? (
          <PauseCircle className="size-3.5 shrink-0 text-accent-yellow" />
        ) : (
          <Spinner size="sm" className="size-3.5 shrink-0 text-accent-blue" />
        )}
        <span className="shrink-0 font-medium text-content-text">{actionLabel}</span>
        {phaseNote ? (
          <span className="shrink-0 rounded-full bg-accent-yellow-light px-1.5 text-3xs text-accent-yellow">
            {phaseNote}
          </span>
        ) : null}
        {summary ? (
          <span className="min-w-0 flex-1 truncate text-content-text-muted">{summary}</span>
        ) : (
          <span className="min-w-0 flex-1" />
        )}
        {ms !== null ? (
          <span className="shrink-0 font-mono text-3xs tabular-nums text-content-text-muted">
            {formatMs(Math.max(0, ms))}
          </span>
        ) : null}
        {hasBody ? (
          open ? (
            <ChevronDown className="size-3 shrink-0 text-content-text-muted" />
          ) : (
            <ChevronRight className="size-3 shrink-0 text-content-text-muted rtl:-scale-x-100" />
          )
        ) : null}
      </button>
      {/* 结果常显(对齐 zcode:结果一眼可见,输入默认折叠) */}
      {error ? (
        <div className="px-2.5 pb-1.5">
          <ErrorLine message={error} />
        </div>
      ) : null}
      {entity ? (
        <div className="px-2.5 pb-1.5">
          <EntityRow entity={entity} output={part.output} translator={t} />
        </div>
      ) : null}
      {list ? (
        <div className="px-2.5 pb-1.5">
          <ListSamples output={part.output} translator={t} />
        </div>
      ) : null}
      {hasBody ? (
        // 折叠区 inert(§22.5:禁焦点落入不可见区),hidden 收起
        <div
          id={bodyId}
          inert={!open}
          hidden={!open}
          className="space-y-1.5 border-t border-border/60 px-2.5 py-1.5"
        >
          {everOpened && part.input !== undefined ? (
            <InputCode input={part.input} cap={maxCodeHeight} />
          ) : null}
          {everOpened && !hasAlwaysVisible && part.output !== undefined ? (
            <OutputCode output={part.output} cap={maxCodeHeight} />
          ) : null}
        </div>
      ) : null}
    </div>
  );
}

/* ---------- 多卡汇总(连续工具卡的组行) ---------- */

export interface AssistantToolGroupProps extends Omit<ComponentProps<'div'>, 'children'> {
  /**
   * 工具 part 列表(新契约)。提供后汇总行从 parts 现算(§22.2:成员只声明自身值,禁预汇总),
   * 每张卡由 renderTool 渲染,不再依赖子元素 props.part。
   */
  parts?: AssistantToolPart[];
  /** part 渲染器;缺省 AssistantToolCard。返回任意 ReactNode(无需携带 key/part)。 */
  renderTool?: (part: AssistantToolPart, index: number) => ReactNode;
  /** 与 parts 同序的计时信息(组行用时汇总用;缺省不显示用时)。 */
  timings?: Array<AssistantToolTiming | undefined>;
  /**
   * 旧契约:直接传入 AssistantToolCard 元素列表(从元素 props 现算汇总)。
   * parts 优先;保留以兼容既有消费方。
   */
  children?: ReactNode;
  defaultOpen?: boolean;
  open?: boolean;
  onOpenChange?: (open: boolean) => void;
}

/** 多卡汇总:一行「已用 N 个工具 · 用时 · M 失败」,点开得卡片列表(默认收起) */
export function AssistantToolGroup({
  parts,
  renderTool,
  timings,
  children,
  defaultOpen = false,
  open: openProp,
  onOpenChange,
  className,
  ...rootProps
}: AssistantToolGroupProps) {
  const bodyId = useId();
  const t = usePatternTranslate('assistantToolCard', TOOL_CARD_LABELS);
  const [openState, setOpenState] = useState(defaultOpen);
  const open = openProp ?? openState;
  const setOpen = (next: boolean) => {
    if (openProp === undefined) setOpenState(next);
    onOpenChange?.(next);
  };

  // 新契约:从 parts 现算;旧契约:退回子卡元素 props(兼容期,不做元素克隆注入)。
  const legacyProps =
    parts === undefined
      ? Children.toArray(children)
          .filter(isValidElement)
          .map((child) => (child as ReactElement<AssistantToolCardProps>).props)
          .filter((props) => !!props.part)
      : [];
  const groupParts: AssistantToolPart[] = parts ?? legacyProps.map((props) => props.part);
  const groupTimings: Array<AssistantToolTiming | undefined> =
    parts === undefined
      ? legacyProps.map((props) => ({ startedAt: props.startedAt, duration: props.duration }))
      : (timings ?? []);
  const statuses = groupParts.map(toolPartStatus);
  const running = statuses.some((s) => s === 'running');
  const failed = statuses.filter((s) => s === 'error').length;

  // 运行中:组秒表从最早起算的运行中 part 开始 live 计时;终态:全员有 duration 则现算求和
  const since = groupParts.reduce<number | undefined>((min, part, index) => {
    const startedAt = groupTimings[index]?.startedAt;
    if (
      toolPartStatus(part) === 'running' &&
      typeof startedAt === 'number' &&
      (min === undefined || startedAt < min)
    ) {
      return startedAt;
    }
    return min;
  }, undefined);
  const measured = useStopwatch(running, since);
  const allFinished =
    groupParts.length > 0 &&
    groupParts.every((_part, index) => typeof groupTimings[index]?.duration === 'number');
  const sum = allFinished
    ? groupParts.reduce(
        (total, _part, index) => total + (groupTimings[index]?.duration ?? 0),
        0,
      )
    : null;
  const ms = running ? measured : (sum ?? measured);

  if (groupParts.length === 0) return <>{children}</>;

  const rendered = parts
    ? groupParts.map((part, index) => (
        <Fragment key={index}>
          {renderTool ? renderTool(part, index) : <AssistantToolCard part={part} />}
        </Fragment>
      ))
    : children;

  return (
    <div
      {...rootProps}
      className={cn(
        'w-full overflow-hidden rounded-lg border border-border bg-background/40',
        className,
      )}
      data-ai-component="assistant.tool-group"
      data-open={open || undefined}
    >
      <span role="status" aria-live="polite" className="sr-only">
        {running
          ? t('assistant.tool.running')
          : failed > 0
            ? t('assistant.tool.usedWithFailures', { count: groupParts.length, failed })
            : t('assistant.tool.used', { count: groupParts.length })}
      </span>
      <button
        type="button"
        onClick={() => setOpen(!open)}
        aria-expanded={open}
        aria-controls={bodyId}
        className={cn(
          'flex w-full items-center gap-1.5 rounded-lg px-2.5 py-1.5 text-start text-xs',
          HEAD_INTERACTION_CLASS,
        )}
      >
        {running ? (
          <Spinner size="sm" className="size-3.5 shrink-0 text-accent-blue" />
        ) : (
          <Wrench className="size-3.5 shrink-0 text-content-text-muted" />
        )}
        <span className="min-w-0 flex-1 truncate text-content-text">
          {running ? t('assistant.tool.runningEllipsis') : t('assistant.tool.used', { count: groupParts.length })}
        </span>
        {failed > 0 ? (
          <span className="shrink-0 text-xs text-accent-red">{t('assistant.tool.failedCount', { count: failed })}</span>
        ) : null}
        {ms !== null ? (
          <span className="shrink-0 font-mono text-3xs tabular-nums text-content-text-muted">
            {formatMs(Math.max(0, ms))}
          </span>
        ) : null}
        {open ? (
          <ChevronDown className="size-3 shrink-0 text-content-text-muted" />
        ) : (
          <ChevronRight className="size-3 shrink-0 text-content-text-muted rtl:-scale-x-100" />
        )}
      </button>
      <div
        id={bodyId}
        inert={!open}
        hidden={!open}
        className="ms-3 space-y-1 border-s border-border/60 py-1 ps-2"
      >
        {rendered}
      </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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

工具调用折叠卡:状态三态 + 输入/输出/错误 + live 计时 + inert 折叠;propose_decision 经 renderDecision 注入决策卡。