0 条结果
AI助手与对话
AssistantToolCard
@mox-hub/patterns · AI · 助手与对话 · canonical
assistant-tool-card@mox-hub/patternsAI Executioncanonicalsrc/components/assistant-tool-card.tsx变体演示assistant-tool-card
查询任务 已完成
内联决策卡(由消费方注入)
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| part* | AssistantToolPart | — | — |
| defaultOpen* | boolean | false | — |
| open* | boolean | — | — |
| onOpenChange* | (open: boolean) => void | — | — |
| startedAt* | number | — | — |
| duration* | number | — | — |
| autoOpenOnError* | boolean | true | — |
| maxCodeHeight* | number | 220 | — |
| className* | string | — | — |
| translator* | PatternTranslate | — | — |
| renderDecision* | (output: unknown) => ReactNode | — | — |
| resolveEntity* | (entity: AssistantToolEntityInput) => AssistantToolEntityView | — | — |
| toolPresentation* | AssistantToolPresentation | — | — |
源码
/**
* 工具调用卡 —— 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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
工具调用折叠卡:状态三态 + 输入/输出/错误 + live 计时 + inert 折叠;propose_decision 经 renderDecision 注入决策卡。