AI执行与编排
ExecTree
@mox-hub/patterns · AI · 执行与编排 · canonical
exec-tree@mox-hub/patternsSemanticcanonicalsrc/components/exec-tree.tsx变体演示exec-tree
执行编排共 4 节点运行中 2需要你处理1总成本US$0.015480
发布编排器claude-sonnet-5-51m 05s—
把 v2.4.0 发布到 staging
检索发布上下文4.2sUS$0.001280
生成发布说明需要你处理59.8sUS$0.014200
运行冒烟测试56.4s—
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| root* | ExecTreeNode | — | — |
| collapsedIds* | string[] | — | — |
| defaultCollapsedIds* | string[] | — | — |
| onCollapsedChange* | (ids: string[]) => void | — | — |
| onSelect* | (node: ExecTreeNode) => void | — | — |
| onResolve* | (node: ExecTreeNode, action: ExecTreeResolveAction) => void | — | — |
| now* | number | — | — |
| title* | string | — | — |
| labels* | Partial<ExecTreeLabels> | — | — |
| className* | string | — | — |
源码
import {
createContext,
useContext,
useEffect,
useId,
useMemo,
useState,
type ComponentProps,
type KeyboardEvent as ReactKeyboardEvent,
} from 'react';
import {
AlertTriangle,
Ban,
CheckCircle2,
ChevronRight,
XCircle,
} from 'lucide-react';
import { cn } from '@mox-hub/ui';
import { usePatternLabels } from '../lib/i18n';
import { formatLiveDuration } from '@mox-hub/ui/format';
import { TONE_CLASS, type Tone } from '@mox-hub/ui/components/tone';
import { Button } from '@mox-hub/ui/components/button';
import { CostFigure } from './cost-figure';
/**
* ExecTree —— 执行编排树(semantic 层;组件规划账本 B1 · P0,宪法 §22.1/§22.2/§22.3)。
*
* 「一个编排者 + 多个子执行」的树形态视图:每卡状态 / 成本 / 耗时,成本沿分支汇总,
* 失败分支保留(§22.3),等人分支琥珀高亮且头部可计数(§22.1)。形态为**纵向缩进树**
* (根在上、子级缩进、左侧连线沿纵深走),适配详情弹窗窄宽度——刻意不做横向组织架构树。
* 交互语义参考 affectUI Agent Tree(只学 API 形状,样式体系为本仓 tone 链路)。
*
* ## 数据契约(给数据层与调用方的承诺)
* - `root` 每次全量传入;节点以 `id` 保位(展开面板等局部状态挂在行组件上,id 稳定即不丢)。
* - `cost` / `tokens` 只传**节点自身值**,分支与全树汇总由本组件遍历现算——禁传预汇总值
* (§22.2,两处口径必漂移)。汇总遍历全树、与折叠态无关:**折叠不隐账**。
* - 失败者保留:重试产生**新节点**(新 id)由数据层挂为 children,本组件只渲染、不做覆盖
* (§22.3——UI 层不得先于数据层抹掉失败故事)。
* - `now` 时钟注入:运行 / 等人计时以注入值为准(测试与跨组件时钟对齐用);缺省组件自跑
* 1s tick(仅存在 running 节点时启动)。
*
* ## 折叠实现裁决
* 折叠分支**条件渲染(卸载)**而非纯 CSS 隐藏:§22.5 要求折叠收起区禁焦点落入,卸载是比
* inert 更强的保证;深树全量常驻渲染违背 §21 渲染窗口精神;且 `display:none` 内容本就不可
* Ctrl+F / 读屏,「不卸载保搜索」前提不成立。折叠分支的账目由父卡「+N 子执行 · 分支合计」
* 行与头部汇总栏承载,不因折叠丢失。
*
* 受控纯展示件:…props 透传、ref 到根(§10.7);文案中文常量 + `labels` 覆写(§16);
* 动效仅 running 呼吸点(motion-safe:animate-pulse,§7 / §22.5)与 CostFigure running 态。
*/
// ── 类型 ──────────────────────────────────────────────────────────────
export type ExecTreeStatus =
| 'queued'
| 'running'
| 'waiting'
| 'done'
| 'failed'
| 'stopped';
/** waiting/failed 的处置动作(approve/reject/dismiss 对 waiting;retry 对 failed) */
export type ExecTreeResolveAction = 'approve' | 'reject' | 'retry' | 'dismiss';
export interface ExecTreeNode {
id: string;
/** 节点名(Agent 名 / 步骤名) */
name: string;
/** 一句话任务描述(截断展示) */
task?: string;
/** 执行模型(mono 小字) */
model?: string;
status: ExecTreeStatus;
/** waiting 语境:等人要决什么(卡上直显) */
statusLabel?: string;
/** failed 错误信息(展开显 mono 红字) */
error?: string;
/** 本节点自身成本(金额)——分支 / 全树汇总由组件现算,禁传预汇总值 */
cost?: number | null;
/** 本节点自身 token 数 */
tokens?: number | null;
/** 开始时间(epoch ms) */
startedAt?: number | null;
/** 结束时间(epoch ms;终态节点静态计时用) */
endedAt?: number | null;
children?: ExecTreeNode[];
}
/** 文案覆写槽(§16:组件内中文常量为默认,调用方按语境覆写) */
export interface ExecTreeLabels {
title: string;
/** 头部汇总:'共 {count} 节点' */
nodesTotal: string;
/** 头部汇总:'运行中 {count}' */
runningCount: string;
/** waiting 徽:'需要你处理'(§22.1 头部计数徽与卡上徽共用) */
waitingBadge: string;
/** 头部汇总:'失败 {count}' */
failedCount: string;
totalCost: string;
statusQueued: string;
statusRunning: string;
statusWaiting: string;
statusDone: string;
statusFailed: string;
statusStopped: string;
/** waiting 处置入口按钮 */
resolve: string;
approve: string;
reject: string;
dismiss: string;
retry: string;
/** failed 错误展开钮 */
errorToggle: string;
/** 折叠分支汇总:'+{count} 子执行' */
subtreeMore: string;
subtreeCost: string;
/** 折叠钮 aria-label:'展开 {name} 的 {count} 个子执行' */
expand: string;
collapse: string;
}
// onSelect 与 HTML 原生 select 事件处理器撞名,须从基类 Omit 后才能声明节点选中回调
export interface ExecTreeProps extends Omit<ComponentProps<'div'>, 'onSelect'> {
root: ExecTreeNode;
/** 受控折叠:集合内的节点 id = 其子级收起 */
collapsedIds?: string[];
/** 非受控折叠初值 */
defaultCollapsedIds?: string[];
onCollapsedChange?: (ids: string[]) => void;
/** 点卡片(打开详情)——树卡 / Enter 触发;卡内按钮各自 stopPropagation */
onSelect?: (node: ExecTreeNode) => void;
/** waiting(approve/reject/dismiss)与 failed(retry)的处置回调;缺省则不渲染处置入口 */
onResolve?: (node: ExecTreeNode, action: ExecTreeResolveAction) => void;
/** 时钟注入(epoch ms,运行 / 等人计时用);缺省组件自跑 1s tick */
now?: number;
/** 头部标题(默认「执行编排」) */
title?: string;
labels?: Partial<ExecTreeLabels>;
}
// ── 常量与纯函数 ──────────────────────────────────────────────────────
const DEFAULT_LABELS: ExecTreeLabels = {
title: '执行编排',
nodesTotal: '共 {count} 节点',
runningCount: '运行中 {count}',
waitingBadge: '需要你处理',
failedCount: '失败 {count}',
totalCost: '总成本',
statusQueued: '排队中',
statusRunning: '运行中',
statusWaiting: '需要你处理',
statusDone: '已完成',
statusFailed: '失败',
statusStopped: '已停止',
resolve: '处理',
approve: '批准',
reject: '拒绝',
dismiss: '忽略',
retry: '重试',
errorToggle: '错误详情',
subtreeMore: '+{count} 子执行',
subtreeCost: '分支合计',
expand: '展开 {name} 的 {count} 个子执行',
collapse: '折叠 {name} 的 {count} 个子执行',
};
const NO_IDS: string[] = [];
/** 六态视觉映射(tone 走 §19.5 唯一词表;running=呼吸点,done/failed/stopped=专属图标) */
const STATUS_META: Record<
ExecTreeStatus,
{
tone: Tone;
labelKey: keyof ExecTreeLabels;
visual:
| { kind: 'dot'; pulse?: boolean }
| { kind: 'icon'; icon: typeof Ban };
}
> = {
queued: { tone: 'default', labelKey: 'statusQueued', visual: { kind: 'dot' } },
running: { tone: 'info', labelKey: 'statusRunning', visual: { kind: 'dot', pulse: true } },
waiting: { tone: 'warning', labelKey: 'statusWaiting', visual: { kind: 'dot' } },
done: { tone: 'success', labelKey: 'statusDone', visual: { kind: 'icon', icon: CheckCircle2 } },
failed: { tone: 'danger', labelKey: 'statusFailed', visual: { kind: 'icon', icon: XCircle } },
stopped: { tone: 'default', labelKey: 'statusStopped', visual: { kind: 'icon', icon: Ban } },
};
/** 模板填充:'{count} 子执行' + {count: 2} → '+2 子执行' 的占位替换(未知占位原样保留) */
function tpl(template: string, vars: Record<string, string | number>): string {
return template.replace(/\{(\w+)\}/g, (raw, key: string) =>
key in vars ? String(vars[key]) : raw,
);
}
interface ExecTreeStats {
nodes: number;
running: number;
waiting: number;
failed: number;
/** 已知自身值之和(缺值不计入、不造 0) */
cost: number | null;
tokens: number | null;
}
function emptyStats(): ExecTreeStats {
return { nodes: 0, running: 0, waiting: 0, failed: 0, cost: null, tokens: null };
}
/** 缺席值不污染合计:null 跳过(诚实降级,不造 0) */
function addTo(base: number | null, value: number | null | undefined): number | null {
if (value == null || !Number.isFinite(value)) return base;
return (base ?? 0) + value;
}
/** 遍历节点含后代,汇总计数与自身值合计(§22.2:汇总=组件现算,与折叠态无关) */
function collectStats(node: ExecTreeNode, into: ExecTreeStats): ExecTreeStats {
into.nodes += 1;
if (node.status === 'running') into.running += 1;
if (node.status === 'waiting') into.waiting += 1;
if (node.status === 'failed') into.failed += 1;
into.cost = addTo(into.cost, node.cost);
into.tokens = addTo(into.tokens, node.tokens);
for (const child of node.children ?? []) collectStats(child, into);
return into;
}
/** 直接后代(含更深层)的分支统计(折叠父卡的「+N 子执行 · 分支合计」行用) */
function descendantStats(node: ExecTreeNode): ExecTreeStats {
const stats = emptyStats();
for (const child of node.children ?? []) collectStats(child, stats);
return stats;
}
/**
* 节点计时(渐进精度展示用原始 ms):
* running / waiting 为 live(now - startedAt,等人时长同样要可见);终态静态差值。
* 数据不完整(缺起点 / 终点早于起点)返回 null——不造 0、不显负数。
*/
function nodeDurationMs(node: ExecTreeNode, now: number): number | null {
const { startedAt, endedAt, status } = node;
if (startedAt == null || !Number.isFinite(startedAt)) return null;
if (status === 'running' || status === 'waiting') {
return Math.max(0, now - startedAt);
}
if (endedAt != null && Number.isFinite(endedAt) && endedAt >= startedAt) {
return endedAt - startedAt;
}
return null;
}
/**
* 树内时钟:`injected` 提供即直用(受控,零副作用);缺省自跑 1s tick——且仅当树内存在
* running 节点时启动(终态树不空转)。惰性初值取挂载时刻(渲染期禁 Date.now,run-timeline
* 同款先例)。
*/
function useTreeNow(injected: number | undefined, active: boolean): number {
const [tick, setTick] = useState(() => Date.now());
useEffect(() => {
if (injected !== undefined || !active) return;
const timer = window.setInterval(() => setTick(Date.now()), 1000);
return () => window.clearInterval(timer);
}, [injected, active]);
return injected ?? tick;
}
// ── 行内件 ────────────────────────────────────────────────────────────
/** 状态视觉槽:dot(queued/running/waiting)或专属图标(done/failed/stopped),颜色全走 tone 词表 */
function StatusVisual({ status }: { status: ExecTreeStatus }) {
const meta = STATUS_META[status];
if (meta.visual.kind === 'icon') {
const Icon = meta.visual.icon;
return (
<Icon
aria-hidden="true"
className={cn('size-3.5 shrink-0', TONE_CLASS[meta.tone].text)}
/>
);
}
return (
<span
aria-hidden="true"
className={cn(
'size-2 shrink-0 rounded-full',
TONE_CLASS[meta.tone].dot,
meta.visual.pulse && 'motion-safe:animate-pulse',
)}
/>
);
}
/**
* waiting 三键的 Button 形态(走 variant/tone 封闭轴,§19.2):
* approve=关键动作(primary 实底);reject=红字 ghost;dismiss=quiet 降权。
* success tone 零先例不立档(ui/button tone 轴裁决),approve 用 default 承重。
*/
const RESOLVE_BUTTON_PROPS: Record<
'approve' | 'reject' | 'dismiss',
{ variant: 'default' } | { variant: 'ghost'; tone: 'danger' } | { variant: 'quiet' }
> = {
approve: { variant: 'default' },
reject: { variant: 'ghost', tone: 'danger' },
dismiss: { variant: 'quiet' },
};
/** 树内 roving tabindex:同一时刻只有一个 treeitem 可 Tab 进入(审计 P1-09)。 */
const ExecTreeFocusContext = createContext<{
tabbableId: string;
setTabbableId: (id: string) => void;
}>({ tabbableId: '', setTabbableId: () => {} });
interface NodeRowProps {
node: ExecTreeNode;
/** 折叠判定(按节点 id 查当前折叠集合——每行只认自己的子级折叠态) */
isCollapsed: (node: ExecTreeNode) => boolean;
onToggleCollapse: (node: ExecTreeNode) => void;
onSelect?: (node: ExecTreeNode) => void;
onResolve?: (node: ExecTreeNode, action: ExecTreeResolveAction) => void;
now: number;
labels: ExecTreeLabels;
}
/**
* 单节点行(ARIA 组合树:外层 role=treeitem 承载焦点与 aria-expanded,内层 role=none
* 承载卡视觉;展开处置面板 / 错误面板为行内局部态,随 id 保位)。
*/
function ExecTreeNodeRow({
node,
isCollapsed,
onToggleCollapse,
onSelect,
onResolve,
now,
labels,
}: NodeRowProps) {
const meta = STATUS_META[node.status];
const statusText = labels[meta.labelKey];
const { tabbableId, setTabbableId } = useContext(ExecTreeFocusContext);
const groupId = useId();
const [actionsOpen, setActionsOpen] = useState(false);
const [errorOpen, setErrorOpen] = useState(false);
const children = node.children;
const hasChildren = !!children && children.length > 0;
const collapsed = isCollapsed(node);
const branch = useMemo(
() => (hasChildren ? descendantStats(node) : null),
[hasChildren, node],
);
const isRunning = node.status === 'running';
const isWaiting = node.status === 'waiting';
const isFailed = node.status === 'failed';
const durationMs = nodeDurationMs(node, now);
// 渐进精度时长走 ../lib/format 唯一口径(账本 G3 收编;数据不完整 → '' 不渲染)
const durationText = formatLiveDuration(durationMs);
return (
<div
role="treeitem"
aria-expanded={hasChildren ? !collapsed : undefined}
aria-selected={false}
aria-label={`${node.name},${statusText}`}
tabIndex={tabbableId === node.id ? 0 : -1}
data-slot="exec-tree-node"
data-node-id={node.id}
data-status={node.status}
onFocus={() => setTabbableId(node.id)}
onClick={() => {
setTabbableId(node.id);
onSelect?.(node);
}}
onKeyDown={(event) => {
// 内部按钮(折叠 / 处置 / 错误)自带 Enter 语义,只认树卡本体的 Enter/Space
if (event.target !== event.currentTarget) return;
if (event.key === 'Enter' || event.key === ' ') {
event.preventDefault();
onSelect?.(node);
}
}}
className="rounded-md focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-accent-blue"
>
<div
role="none"
className={cn(
// 所有线框一律圆角矩形:waiting 描边不得出现直角盒子
'cursor-pointer rounded-md border px-2 py-1.5 transition-colors',
isWaiting
? // §22.1:等人分支视觉权级最高——琥珀警示底 + 描边,禁 muted 降级
'border-accent-yellow/50 bg-accent-yellow-light/40 hover:bg-accent-yellow-light/60'
: 'border-transparent hover:bg-muted/40',
)}
>
{/* 第一行:折叠钮 + 状态 + 名称 + model + (waiting 徽)+ 计时 + 成本 + 错误钮 */}
<div className="flex min-w-0 items-center gap-1.5 text-xs leading-relaxed">
{hasChildren ? (
<Button
type="button"
variant="ghost"
size="icon-2xs"
aria-expanded={!collapsed}
aria-controls={!collapsed ? groupId : undefined}
aria-label={
collapsed
? tpl(labels.expand, { name: node.name, count: branch?.nodes ?? 0 })
: tpl(labels.collapse, { name: node.name, count: branch?.nodes ?? 0 })
}
onClick={(event) => {
event.stopPropagation();
onToggleCollapse(node);
}}
className="shrink-0"
>
<ChevronRight
aria-hidden="true"
className={cn(
'size-3 transition-transform rtl:-scale-x-100',
!collapsed && 'rotate-90',
)}
/>
</Button>
) : null}
<StatusVisual status={node.status} />
<span className="min-w-0 truncate font-medium text-content-text">
{node.name}
</span>
{node.model ? (
<span className="hidden min-w-0 truncate font-mono text-2xs text-content-text-muted sm:inline">
{node.model}
</span>
) : null}
{isWaiting ? (
<span className="inline-flex shrink-0 items-center gap-0.5 rounded-full bg-accent-yellow-light px-1.5 py-0.5 text-xs font-semibold text-accent-yellow">
<AlertTriangle aria-hidden="true" className="size-2.5" />
{labels.waitingBadge}
</span>
) : null}
<span className="ms-auto flex shrink-0 items-center gap-2">
{durationText ? (
<span
className={cn(
'font-mono text-2xs tabular-nums',
isRunning
? 'text-accent-blue'
: isWaiting
? 'text-accent-yellow'
: 'text-content-text-muted',
)}
>
{durationText}
</span>
) : null}
<CostFigure
size="xs"
amount={node.cost}
tokens={node.tokens}
running={isRunning}
className={isRunning ? 'text-accent-blue' : undefined}
/>
</span>
{isFailed ? (
<Button
type="button"
variant="ghost"
tone="danger"
size="xs"
padding="px-1.5 py-0.5"
aria-expanded={errorOpen}
onClick={(event) => {
event.stopPropagation();
setErrorOpen((open) => !open);
}}
className="shrink-0"
>
{labels.errorToggle}
</Button>
) : null}
</div>
{/* 第二行:任务一句话(截断) */}
{node.task ? (
<p className="mt-0.5 truncate ps-6 text-xs text-content-text-muted">{node.task}</p>
) : null}
{/* waiting 语境直显(§22.1:等人要决什么直接可见,不藏在展开区) */}
{isWaiting && node.statusLabel ? (
<p className="mt-0.5 truncate ps-6 text-xs text-accent-yellow">{node.statusLabel}</p>
) : null}
{/* waiting 处置:展开行 statusLabel + 三键(approve/reject/dismiss 走 onResolve) */}
{isWaiting && onResolve ? (
actionsOpen ? (
<div className="mt-1.5 flex min-w-0 items-center gap-1.5 ps-6">
{node.statusLabel ? (
<span className="min-w-0 flex-1 truncate text-xs text-accent-yellow">
{node.statusLabel}
</span>
) : null}
<span className="flex shrink-0 items-center gap-1">
{(['approve', 'reject', 'dismiss'] as const).map((action) => (
<Button
key={action}
type="button"
size="xs"
padding="px-1.5 py-0.5"
data-action={action}
{...RESOLVE_BUTTON_PROPS[action]}
onClick={(event) => {
event.stopPropagation();
onResolve(node, action);
setActionsOpen(false);
}}
>
{labels[action]}
</Button>
))}
</span>
</div>
) : (
// 节点主操作贴右下,不占左侧阅读起始位
<div className="mt-1 flex justify-end">
<Button
type="button"
variant="outline"
size="xs"
padding="px-1.5 py-0.5"
aria-expanded={false}
onClick={(event) => {
event.stopPropagation();
setActionsOpen(true);
}}
>
{labels.resolve}
</Button>
</div>
)
) : null}
{/* failed 错误面板(§22.3 失败叙事保留:mono 红字 + 重试入口;重试=数据层挂新子节点) */}
{isFailed && errorOpen ? (
<div className="mt-1.5 space-y-1.5 ps-6">
{node.error ? (
<pre className="max-h-32 overflow-auto overscroll-contain whitespace-pre-wrap break-all rounded-md bg-accent-red-light/50 p-1.5 font-mono text-2xs leading-relaxed text-accent-red">
{node.error}
</pre>
) : null}
{onResolve ? (
<div className="flex justify-end">
<Button
type="button"
variant="ghost"
tone="info"
size="xs"
padding="px-1.5 py-0.5"
data-action="retry"
onClick={(event) => {
event.stopPropagation();
onResolve(node, 'retry');
}}
>
{labels.retry}
</Button>
</div>
) : null}
</div>
) : null}
{/* 折叠分支汇总(§22.2:折叠不隐账——分支合计=后代自身值现算) */}
{hasChildren && collapsed && branch ? (
<p className="mt-1 flex min-w-0 items-center gap-1 ps-6 text-xs text-content-text-muted">
<span className="shrink-0 tabular-nums">
{tpl(labels.subtreeMore, { count: branch.nodes })}
</span>
{branch.cost != null || branch.tokens != null ? (
<>
<span aria-hidden="true">·</span>
<span className="shrink-0">{labels.subtreeCost}</span>
<CostFigure
size="xs"
amount={branch.cost}
tokens={branch.tokens}
className="text-content-text-muted"
/>
</>
) : null}
</p>
) : null}
</div>
{/* 子级(折叠即卸载,见文件头「折叠实现裁决」;连线颜色跟随子分支状态 tone,queued/stopped 天然 muted 降权) */}
{hasChildren && !collapsed && children ? (
<div role="group" id={groupId} data-slot="exec-tree-children" className="ms-2.5">
{children.map((child, index) => {
const isLast = index === children.length - 1;
const lineDot = TONE_CLASS[STATUS_META[child.status].tone].dot;
return (
<div key={child.id} className="relative ps-4">
{/* 纵向连线段:末枝止于肘部,其余贯穿整行 */}
<span
aria-hidden="true"
className={cn(
'absolute start-0 top-0 w-px opacity-30',
isLast ? 'h-4' : 'bottom-0',
lineDot,
)}
/>
{/* 肘部横线:对齐子卡首行中线 */}
<span
aria-hidden="true"
className={cn('absolute start-0 top-4 h-px w-3.5 opacity-30', lineDot)}
/>
<ExecTreeNodeRow
node={child}
isCollapsed={isCollapsed}
onToggleCollapse={onToggleCollapse}
onSelect={onSelect}
onResolve={onResolve}
now={now}
labels={labels}
/>
</div>
);
})}
</div>
) : null}
</div>
);
}
// ── 组件本体 ──────────────────────────────────────────────────────────
/**
* 执行编排树。全量受控 + …props 透传(§10.7);头部汇总栏全树现算(总节点 / 运行中 /
* 需要你处理(§22.1 琥珀计数徽,aria-live)/ 失败 / 总成本),成本沿分支汇总、折叠不隐账。
*/
export function ExecTree({
root,
collapsedIds,
defaultCollapsedIds,
onCollapsedChange,
onSelect,
onResolve,
now,
title,
labels: labelsOverride,
className,
...rest
}: ExecTreeProps) {
const providerLabels = usePatternLabels('execTree', DEFAULT_LABELS);
const labels = useMemo(
() => ({ ...providerLabels, ...labelsOverride }),
[providerLabels, labelsOverride],
);
// 折叠半受控模式:传 collapsedIds 即受控(状态归调用方),否则内部自持
const [innerCollapsed, setInnerCollapsed] = useState<string[]>(
defaultCollapsedIds ?? NO_IDS,
);
const isControlled = collapsedIds !== undefined;
const collapsedList = isControlled ? collapsedIds : innerCollapsed;
const collapsedSet = useMemo(() => new Set(collapsedList), [collapsedList]);
// 树内只有一个可 Tab 的 treeitem;方向键在可见节点间移动。
// 根 id 变化时用派生值回落到新根,避免在 effect 里同步 setState。
const [focusState, setFocusState] = useState({ rootId: root.id, id: root.id });
const tabbableId = focusState.rootId === root.id ? focusState.id : root.id;
const setTabbableId = (id: string) => setFocusState({ rootId: root.id, id });
const stats = useMemo(() => collectStats(root, emptyStats()), [root]);
const resolvedNow = useTreeNow(now, stats.running > 0);
const resolvedTitle = title !== undefined ? title : labels.title;
const toggleCollapse = (node: ExecTreeNode) => {
const next = collapsedSet.has(node.id)
? collapsedList.filter((id) => id !== node.id)
: [...collapsedList, node.id];
if (!isControlled) setInnerCollapsed(next);
setTabbableId(node.id);
onCollapsedChange?.(next);
};
const isCollapsedNode = (node: ExecTreeNode) => collapsedSet.has(node.id);
const handleTreeKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
const target = event.target as HTMLElement;
const current = target.closest<HTMLElement>('[role="treeitem"]');
// 只在 treeitem 本体聚焦时接管;内部按钮/输入保留自己的键盘语义。
if (!current || target !== current) return;
if (event.key === 'Enter' || event.key === ' ') return;
const items = Array.from(
event.currentTarget.querySelectorAll<HTMLElement>('[role="treeitem"]'),
);
const index = items.indexOf(current);
if (index === -1) return;
const focusAt = (nextIndex: number) => {
const next = items[nextIndex];
if (!next) return;
next.focus();
setTabbableId(next.dataset.nodeId ?? '');
};
const expanded = current.getAttribute('aria-expanded');
if (event.key === 'ArrowDown') {
event.preventDefault();
focusAt(index + 1);
} else if (event.key === 'ArrowUp') {
event.preventDefault();
focusAt(index - 1);
} else if (event.key === 'Home') {
event.preventDefault();
focusAt(0);
} else if (event.key === 'End') {
event.preventDefault();
focusAt(items.length - 1);
} else if (event.key === 'ArrowRight' && expanded !== null) {
event.preventDefault();
if (expanded === 'false') {
current.querySelector<HTMLButtonElement>('button[aria-expanded="false"]')?.click();
} else {
const firstChild = items[index + 1];
if (firstChild && current.contains(firstChild)) focusAt(index + 1);
}
} else if (event.key === 'ArrowLeft') {
event.preventDefault();
if (expanded === 'true') {
current.querySelector<HTMLButtonElement>('button[aria-expanded="true"]')?.click();
} else {
const parent = current.parentElement?.closest<HTMLElement>('[role="treeitem"]');
if (parent) {
parent.focus();
setTabbableId(parent.dataset.nodeId ?? '');
}
}
}
};
return (
<ExecTreeFocusContext.Provider value={{ tabbableId, setTabbableId }}>
<div
role="tree"
aria-label={resolvedTitle}
data-slot="exec-tree"
data-ai-component="exec-tree"
className={cn('min-w-0', className)}
onKeyDown={handleTreeKeyDown}
{...rest}
>
{/* 头部汇总栏(全部现算;waiting 琥珀计数徽 + aria-live,§22.1) */}
<div
data-slot="exec-tree-header"
className="mb-2 flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-content-text-muted"
>
<span className="text-xs font-semibold text-content-text">{resolvedTitle}</span>
<span className="tabular-nums">{tpl(labels.nodesTotal, { count: stats.nodes })}</span>
{stats.running > 0 ? (
<span className="tabular-nums text-accent-blue">
{tpl(labels.runningCount, { count: stats.running })}
</span>
) : null}
{stats.waiting > 0 ? (
<span aria-live="polite">
<span className="inline-flex items-center gap-0.5 rounded-full bg-accent-yellow-light px-1.5 py-0.5 font-semibold text-accent-yellow">
<AlertTriangle aria-hidden="true" className="size-2.5" />
{labels.waitingBadge}
<span className="tabular-nums">{stats.waiting}</span>
</span>
</span>
) : null}
{stats.failed > 0 ? (
<span className="tabular-nums text-accent-red">
{tpl(labels.failedCount, { count: stats.failed })}
</span>
) : null}
<span className="ms-auto flex items-center gap-1">
<span className="shrink-0">{labels.totalCost}</span>
<CostFigure
size="xs"
amount={stats.cost}
tokens={stats.tokens}
running={stats.running > 0}
/>
</span>
</div>
<ExecTreeNodeRow
node={root}
isCollapsed={isCollapsedNode}
onToggleCollapse={toggleCollapse}
onSelect={onSelect}
onResolve={onResolve}
now={resolvedNow}
labels={labels}
/>
</div>
</ExecTreeFocusContext.Provider>
);
}
可访问性与 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。
用法说明
执行编排树:节点以 id 保位,成本沿分支汇总且折叠不隐账;六态含 waiting 等人一等态;受控/非受控折叠双模,失败分支保留重试入口。