AI执行与编排
TaskPlan
@mox-hub/patterns · AI · 执行与编排 · canonical
task-plan@mox-hub/patternsAI Executioncanonicalsrc/components/task-plan.tsx变体演示task-plan
- 确认登录页现状已完成
- 拆解验收标准小码执行中
- 生成测试用例待执行
- 运行冒烟测试失败
端口占用
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| items* | TaskPlanItem[] | — | — |
| title* | string | — | — |
| collapsible* | boolean | true | — |
| defaultOpen* | boolean | true | — |
| open* | boolean | — | — |
| onOpenChange* | (open: boolean) => void | — | — |
| onItemClick* | (item: TaskPlanItem) => void | — | — |
| renderItemExtra* | (item: TaskPlanItem) => ReactNode | — | — |
| labels* | Partial<TaskPlanLabels> | — | — |
| className* | string | — | — |
源码
import { useId, useState, type ComponentProps, type ReactNode } from 'react';
import {
CheckCircle2,
ChevronDown,
Circle,
MinusCircle,
XCircle,
} from 'lucide-react';
import { cn } from '@mox-hub/ui';
import {
Collapsible,
CollapsibleContent,
CollapsibleTrigger,
} from '@mox-hub/ui/components/collapsible';
import { Spinner } from '@mox-hub/ui/components/spinner';
import { usePatternLabels } from '../lib/i18n';
/**
* TaskPlan —— 计划执行清单(执行平面 / 对话平面共用)。
*
* 把 agent 的 plan(todos)实时打勾:
* - 五态:pending / in_progress / completed / failed / skipped;
* - 进度条与计数从 items 现算,不接收预汇总值(两处口径必漂移);
* - 折叠只隐藏行,计数与进度仍按全量计算(折叠不隐账);
* - 状态变化经 `role="status"` 汇总行播报,单行状态另有文本标签,不只靠颜色。
*/
export type TaskPlanStatus =
| 'pending'
| 'in_progress'
| 'completed'
| 'failed'
| 'skipped';
export interface TaskPlanItem {
id: string;
title: string;
description?: string;
status: TaskPlanStatus;
/** 归属 agent(多 agent 场景显示) */
agentName?: string;
/** 结果 / 错误摘要 */
result?: string;
}
export interface TaskPlanLabels {
/** 无障碍名 */
region: string;
progress: (done: number, total: number) => string;
expand: string;
collapse: string;
pending: string;
inProgress: string;
completed: string;
failed: string;
skipped: string;
empty: string;
}
export const TASK_PLAN_DEFAULT_LABELS: TaskPlanLabels = {
region: '执行计划',
progress: (done, total) => `${done}/${total} 已完成`,
expand: '展开计划',
collapse: '收起计划',
pending: '待执行',
inProgress: '执行中',
completed: '已完成',
failed: '失败',
skipped: '已跳过',
empty: '暂无计划',
};
const STATUS_ICON = {
pending: Circle,
completed: CheckCircle2,
failed: XCircle,
skipped: MinusCircle,
} as const;
const STATUS_TEXT_CLASS: Record<TaskPlanStatus, string> = {
pending: 'text-content-text-muted',
in_progress: 'text-accent-blue',
completed: 'text-accent-green',
failed: 'text-accent-red',
skipped: 'text-content-text-muted',
};
export interface TaskPlanProps extends Omit<ComponentProps<'div'>, 'children'> {
items: TaskPlanItem[];
/** 标题;不传则不渲染头部 */
title?: string;
/** 可折叠;默认 true */
collapsible?: boolean;
/** 非受控初始展开态;默认展开 */
defaultOpen?: boolean;
/** 受控展开态 */
open?: boolean;
onOpenChange?: (open: boolean) => void;
/** 单行点击 */
onItemClick?: (item: TaskPlanItem) => void;
/** 行尾附加内容 */
renderItemExtra?: (item: TaskPlanItem) => ReactNode;
labels?: Partial<TaskPlanLabels>;
}
export function TaskPlan({
items,
title,
collapsible = true,
defaultOpen = true,
open,
onOpenChange,
onItemClick,
renderItemExtra,
labels,
className,
...props
}: TaskPlanProps) {
const D = usePatternLabels('taskPlan', TASK_PLAN_DEFAULT_LABELS);
const text: TaskPlanLabels = {
region: labels?.region ?? D.region,
progress: labels?.progress ?? D.progress,
expand: labels?.expand ?? D.expand,
collapse: labels?.collapse ?? D.collapse,
pending: labels?.pending ?? D.pending,
inProgress: labels?.inProgress ?? D.inProgress,
completed: labels?.completed ?? D.completed,
failed: labels?.failed ?? D.failed,
skipped: labels?.skipped ?? D.skipped,
empty: labels?.empty ?? D.empty,
};
const statusLabel: Record<TaskPlanStatus, string> = {
pending: text.pending,
in_progress: text.inProgress,
completed: text.completed,
failed: text.failed,
skipped: text.skipped,
};
const controlled = open !== undefined;
const [innerOpen, setInnerOpen] = useState(defaultOpen);
const currentOpen = controlled ? open : innerOpen;
const panelId = useId();
const total = items.length;
const done = items.filter((item) => item.status === 'completed').length;
const ratio = total > 0 ? done / total : 0;
const handleOpenChange = (next: boolean) => {
if (!controlled) setInnerOpen(next);
onOpenChange?.(next);
};
const list = (
<ol className="space-y-1.5">
{items.map((item) => {
const running = item.status === 'in_progress';
const Icon = running ? null : STATUS_ICON[item.status];
return (
<li
key={item.id}
data-ai-component="task-plan.item"
data-status={item.status}
className="flex items-start gap-2"
>
<span
className={cn(
'mt-0.5 flex size-4 shrink-0 items-center justify-center',
STATUS_TEXT_CLASS[item.status],
)}
aria-hidden
>
{running ? (
<Spinner size="sm" className="size-3.5" />
) : Icon ? (
<Icon className="size-3.5" />
) : (
<Circle className="size-3.5" />
)}
</span>
<div className="min-w-0 flex-1">
{onItemClick ? (
<button
type="button"
className="block w-full cursor-pointer rounded-md text-start text-xs text-content-text outline-none transition-colors duration-fast hover:text-accent-blue focus-visible:ring-2 focus-visible:ring-ring/50"
onClick={() => onItemClick(item)}
>
{item.title}
</button>
) : (
<span
className={cn(
'block text-xs',
item.status === 'completed'
? 'text-content-text-secondary line-through'
: item.status === 'skipped'
? 'text-content-text-muted line-through'
: 'text-content-text',
)}
>
{item.title}
</span>
)}
{item.description ? (
<p className="mt-0.5 text-2xs text-content-text-muted">
{item.description}
</p>
) : null}
{item.result ? (
<p
className={cn(
'mt-0.5 break-words text-2xs',
item.status === 'failed'
? 'text-accent-red'
: 'text-content-text-secondary',
)}
>
{item.result}
</p>
) : null}
</div>
{item.agentName ? (
<span className="shrink-0 text-2xs text-content-text-muted">
{item.agentName}
</span>
) : null}
<span className="shrink-0 text-2xs text-content-text-muted">
{statusLabel[item.status]}
</span>
{renderItemExtra ? renderItemExtra(item) : null}
</li>
);
})}
</ol>
);
const summary = (
<div className="flex min-w-0 flex-1 items-center gap-2">
{title ? (
<span className="truncate text-xs font-semibold text-content-text">
{title}
</span>
) : null}
<span
role="status"
aria-live="polite"
className="shrink-0 text-2xs tabular-nums text-content-text-muted"
>
{text.progress(done, total)}
</span>
<span className="relative h-1 min-w-8 flex-1 overflow-hidden rounded-full bg-muted">
<span
className="absolute inset-y-0 start-0 rounded-full bg-accent-green transition-[width] duration-normal"
style={{ width: `${Math.round(ratio * 100)}%` }}
aria-hidden
/>
</span>
</div>
);
if (total === 0) {
return (
<div
data-ai-component="task-plan"
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}
</div>
);
}
if (!collapsible) {
return (
<div
role="region"
aria-label={text.region}
data-ai-component="task-plan"
className={cn(
'rounded-lg border border-content-border bg-content-bg p-3',
className,
)}
{...props}
>
<div className="mb-2 flex items-center">{summary}</div>
{list}
</div>
);
}
return (
<div
role="region"
aria-label={text.region}
data-ai-component="task-plan"
className={cn(
'rounded-lg border border-content-border bg-content-bg',
className,
)}
{...props}
>
<Collapsible open={currentOpen} onOpenChange={handleOpenChange}>
<CollapsibleTrigger
className="flex w-full items-center gap-2 rounded-lg px-3 py-2 text-start outline-none transition-colors duration-fast hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring/50"
aria-controls={panelId}
aria-label={currentOpen ? text.collapse : text.expand}
>
{summary}
<ChevronDown
aria-hidden
className={cn(
'size-3.5 shrink-0 text-content-text-muted transition-transform duration-fast',
currentOpen && 'rotate-180',
)}
/>
</CollapsibleTrigger>
<CollapsibleContent
id={panelId}
className="border-t border-content-border px-3 py-2"
>
{list}
</CollapsibleContent>
</Collapsible>
</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。
用法说明
计划执行清单:五态 pending/in_progress/completed/failed/skipped;进度从 items 现算,折叠不隐账;状态有文本标签,不只靠颜色。