AI执行与编排
DecisionQueuePanel
@mox-hub/patterns · AI · 执行与编排 · canonical
decision-queue-panel@mox-hub/patternsAI Executioncanonicalsrc/components/decision-queue-panel.tsx变体演示decision-queue-panel
该你了
阻断 1排队 1另有 1 项未显示(本次取出 2 / 共 3)
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| queue* | DecisionQueue | — | — |
| isPending* | boolean | — | — |
| isError* | boolean | — | — |
| sourceNote* | string | — | — |
| onAction* | (action: string, d: DecisionQueueItem, opts?: { reason?: string; answer?: string; }) => void | — | — |
| busyId* | string | — | — |
| readOnly* | boolean | false | — |
| readOnlyNote* | string | — | — |
| waitingNowMs* | number | — | — |
| renderDecision* | (decision: DecisionQueueItem, ctx: DecisionRenderContext) => ReactNode | — | — |
| labels* | Partial<DecisionQueuePanelLabels> | — | — |
源码
import { useState } from 'react';
import { ChevronDown, ChevronRight } from 'lucide-react';
import { cn } from '@mox-hub/ui';
import type { ReactNode } from 'react';
import { TONE_CLASS } from '@mox-hub/ui/components/tone';
import { usePatternLabels, usePatternTranslate } from '../lib/i18n';
import { createTranslator, type PatternTranslate } from '../lib/translate';
export interface DecisionQueuePanelLabels {
panel: string;
title: string;
statusError: string;
statusLoading: string;
blocking: string;
advisory: string;
blockingTitle: string;
advisoryTitle: string;
error: string;
loading: string;
empty: string;
hidden: (count: number, shown: number, total: number) => string;
createdAt: (value: string) => string;
}
const DEFAULT_LABELS: DecisionQueuePanelLabels = {
panel: '待你拍板',
title: '该你了',
statusError: '待办读取失败(不显示占位数据)',
statusLoading: '读取中',
blocking: '阻断',
advisory: '排队',
blockingTitle: '紧迫度 blocking:执行已暂停等待裁决',
advisoryTitle: '紧迫度 advisory:排队判断题,不挡其他工作推进',
error: '待你拍板的事项读取失败。不显示占位条目,以免被当成真实待办;请检查网络或稍后重试。',
loading: '正在读取待办…',
empty: '没有待你拍板的事项',
hidden: (count, shown, total) =>
`另有 ${count} 项未显示(本次取出 ${shown} / 共 ${total})`,
createdAt: (value) => `创建于 ${value}`,
};
/**
* 「该你了」待办区(ARCH-AISURFACE-001 §3.1 右栏 / §3.2 待拍板决策卡就地展开)。
*
* ## 纪律:不开第二个拍板入口
*
* 展开态直接复用 `DecisionCard`(= `DecisionCardShell` 五段式 + 各 kind 槽位),
* 决议经 `useResolveDecision` → **既有**端点(approval / acceptance / proposals
* 各自的原生写路径)。本组件**不**自建动作栏、**不**直连 api、**不**改决策语义——
* 「就地拍板」的增量价值只是**不跳页**,写路径必须与决策收件箱完全一致。
*
* ## 诚实粒度
*
* · 三类「空」分开说:读取中 / 读取失败 / 确实没有待你拍板的事;
* · 分页截断如实报(`另有 N 项未显示`),不假装列表就是全部;
* · 等待时长由真实 `createdAt` 推出,**不**编造"剩余时限"(无该字段)。
*/
/** 待决队列条目最小投影(与 ordo Decision 结构兼容)。 */
export interface DecisionQueueItem {
id: string;
kind: string;
title: string;
urgency?: string;
createdAt: string;
projectName?: string;
[key: string]: unknown;
}
export interface DecisionQueue {
items: DecisionQueueItem[];
total: number;
blocking: number;
advisory: number;
hiddenCount: number;
}
export interface DecisionRenderContext {
onAction: (action: string, d: DecisionQueueItem, opts?: { reason?: string; answer?: string }) => void;
busy: boolean;
readOnly: boolean;
readOnlyNote?: string;
}
/**
* 等待时长人话化;`createdAt` 不可解析时返回 null(→ 显示破折号,不猜)。
*
* 参考时刻缺省取当前时刻。**取默认值这件事刻意留在函数体里**:读时钟是个不纯操作,
* 而 React 的纯度规则禁止在渲染期直接调用(`react-hooks/purity` 会直接报错)。
* 调用方若要一个非"现在"的参考时刻(回放态取**剧本时钟**),必须显式传 `nowMs`。
*/
const WAITING_LABELS = {
justNow: '刚刚',
minutes: '{{count}} 分钟',
hours: '{{count}} 小时',
days: '{{count}} 天',
};
export function formatWaiting(
createdAt: string,
nowMs?: number,
t?: PatternTranslate,
): string | null {
const parsed = Date.parse(createdAt);
if (Number.isNaN(parsed)) return null;
const now = nowMs ?? Date.now();
const mins = Math.max(0, Math.floor((now - parsed) / 60000));
const tr = t ?? createTranslator(WAITING_LABELS);
if (mins < 1) return tr('justNow');
if (mins < 60) return tr('minutes', { count: mins });
const hours = Math.floor(mins / 60);
if (hours < 24) return tr('hours', { count: hours });
return tr('days', { count: Math.floor(hours / 24) });
}
/**
* 待办区的**渲染本体**:只吃 props,不碰任何 hook。
*
* 抽出它的是 S5 回放:回放要放**同一块待办区**,但数据来自剧本帧。理由同泳道
* (见 `pipeline-lane-strip.tsx`)——演示给新手看的那块界面,必须就是真实项目里
* 那一块,而不是"照着它另画的一块"。
*
* ## `readOnly`:回放里不能有能按的动作键
*
* 剧本里的决策是**已发生事实的复述**,其 `id` 在服务端并不存在。若照常渲染动作栏,
* 点下去的每一下都是"看起来批了、其实什么都没落"——正是 S2-e 删掉那个假「准入」
* 按钮时定下的同一类错误。故回放态**整条动作栏不渲染**,并在原处写明为什么。
*/
export function DecisionQueuePanelView({
queue,
isPending,
isError,
sourceNote,
onAction,
busyId,
readOnly = false,
readOnlyNote,
waitingNowMs,
renderDecision,
labels,
}: {
queue: DecisionQueue;
isPending: boolean;
isError: boolean;
/** 表头出处注脚。回放态必须写明数据不是从收件箱取的 */
sourceNote: string;
onAction: (action: string, d: DecisionQueueItem, opts?: { reason?: string; answer?: string }) => void;
/** 决策卡渲染器:主仓注入 DecisionCard,库内不依赖决策实现。 */
renderDecision: (decision: DecisionQueueItem, ctx: DecisionRenderContext) => ReactNode;
busyId: string | null;
/** 只读预览(回放):不渲染动作栏 */
readOnly?: boolean;
/** 只读时在原动作栏位置给出的说明(调用方给文案,避免为回放另起 i18n 管道) */
readOnlyNote?: string;
/**
* 「等待时长」的参考时刻,缺省取当前时刻。
*
* 回放态必须传**剧本时刻**:等待时长是 `createdAt` 与"现在"的差值,而在回放里
* 唯一有意义的时钟是剧本自己的时钟。若沿用墙上时间,一条剧本里刚出现的待办会
* 显示「等了 4 天」——一个精确、具体、而且与屏幕上其他每一处都矛盾的读数。
*/
waitingNowMs?: number;
labels?: Partial<DecisionQueuePanelLabels>;
}) {
const L = { ...DEFAULT_LABELS, ...labels };
const [expandedId, setExpandedId] = useState<string | null>(null);
// 表头状态是**出处/健康**注脚,正文才是内容态——两者措辞须不同,
// 否则同一句话在一屏里出现两遍(读起来像复读,也让人分不清是哪一层的状态)
const statusText = isError
? L.statusError
: isPending
? L.statusLoading
: sourceNote;
return (
<section
className="w-full"
data-ai-component="ai-surface.decision-queue"
data-ai-role="panel"
aria-label={L.panel}
>
<div className="mb-2 flex items-center justify-between px-1">
<div className="flex items-center gap-2">
<h2 className="text-xs font-semibold tracking-tight text-foreground">{L.title}</h2>
{!isPending && !isError && (
<span className="flex items-center gap-1 font-mono text-xs">
<span
className={cn(
'rounded-full px-1.5 py-0.5',
queue.blocking > 0 ? TONE_CLASS.danger.light : TONE_CLASS.success.light,
)}
title={L.blockingTitle}
>
{L.blocking} {queue.blocking}
</span>
<span
className={cn('rounded-full px-1.5 py-0.5', TONE_CLASS.default.light)}
title={L.advisoryTitle}
>
{L.advisory} {queue.advisory}
</span>
</span>
)}
</div>
<span className="font-mono text-xs text-muted-foreground">{statusText}</span>
</div>
{isError ? (
<p className="rounded-xl border border-foreground/10 bg-foreground/5 px-3 py-3 text-xs text-muted-foreground">
{L.error}
</p>
) : isPending ? (
<p className="rounded-xl border border-foreground/10 bg-foreground/5 px-3 py-3 text-xs text-muted-foreground">
{L.loading}
</p>
) : queue.items.length === 0 ? (
<p className="rounded-xl border border-foreground/10 bg-foreground/5 px-3 py-3 text-xs text-muted-foreground">
{L.empty}
</p>
) : (
<ul className="space-y-1.5">
{queue.items.map((decision) => (
<QueueRow
key={decision.id}
decision={decision}
expanded={expandedId === decision.id}
busy={busyId === decision.id}
renderDecision={renderDecision}
onToggle={() =>
setExpandedId((prev) => (prev === decision.id ? null : decision.id))
}
onAction={onAction}
readOnly={readOnly}
readOnlyNote={readOnlyNote}
waitingNowMs={waitingNowMs}
labels={L}
/>
))}
</ul>
)}
{queue.hiddenCount > 0 && (
<p className="mt-1.5 px-1 font-mono text-xs text-muted-foreground">
{L.hidden(queue.hiddenCount, queue.items.length, queue.total)}
</p>
)}
</section>
);
}
function QueueRow({
decision,
expanded,
busy,
onToggle,
onAction,
renderDecision,
readOnly,
readOnlyNote,
waitingNowMs,
labels,
}: {
decision: DecisionQueueItem;
expanded: boolean;
busy: boolean;
onToggle: () => void;
onAction: (action: string, d: DecisionQueueItem, opts?: { reason?: string; answer?: string }) => void;
renderDecision: (decision: DecisionQueueItem, ctx: DecisionRenderContext) => ReactNode;
readOnly: boolean;
readOnlyNote?: string;
waitingNowMs?: number;
labels: DecisionQueuePanelLabels;
}) {
const isBlocking = decision.urgency === 'blocking';
const translate = usePatternTranslate('decisionQueuePanel', WAITING_LABELS);
const waiting = formatWaiting(decision.createdAt, waitingNowMs, translate);
return (
<li
className={cn(
'overflow-hidden rounded-xl border border-foreground/10 bg-foreground/5',
isBlocking && 'border-s-2 border-s-accent-red',
)}
data-ai-component="ai-surface.decision-row"
data-decision-id={decision.id}
// 就地解释(CAP-C-07):行本身此前只有 `data-decision-id`,而 AISlot 读的是
// `data-ai-entity` 的 `kind:id`——**收起状态**下 Ctrl+左键无效(展开后是
// DecisionCardShell 带出来的同名属性,属另一条路径)。这里补的是"没展开也想问"
// 的那一半。注意前缀:决策卡壳的既有约定是 `decision:`,不能裸用 data-decision-id
data-ai-entity={`decision:${decision.id}`}
>
<button
type="button"
onClick={onToggle}
className="flex w-full cursor-pointer items-center gap-2 px-2.5 py-2 text-start transition-colors hover:bg-muted"
aria-expanded={expanded}
data-ai-action={`ai-surface.decision.${decision.kind}.toggle`}
>
{expanded ? (
<ChevronDown className="size-3 shrink-0 text-muted-foreground" />
) : (
<ChevronRight className="size-3 shrink-0 text-muted-foreground rtl:-scale-x-100" />
)}
<span
className={cn(
'shrink-0 rounded-full px-1.5 py-0.5 font-mono text-xs',
isBlocking ? TONE_CLASS.danger.light : TONE_CLASS.default.light,
)}
>
{decision.kind}
</span>
<span className="min-w-0 flex-1 truncate text-xs text-foreground">{decision.title}</span>
{decision.projectName ? (
<span className="shrink-0 font-mono text-xs text-muted-foreground">
{decision.projectName}
</span>
) : null}
{/* 等待时长由真实 createdAt 推出;不可解析时给破折号,不猜 */}
<span
className="shrink-0 font-mono text-xs text-muted-foreground"
title={labels.createdAt(decision.createdAt)}
>
{waiting ?? '—'}
</span>
</button>
{/* 就地展开:既有决策卡文法(五段式 + 各 kind 槽位),写路径同收件箱 */}
{expanded && (
<div className="px-2.5 pb-2.5">
{renderDecision(decision, { onAction, busy, readOnly, readOnlyNote })}
</div>
)}
</li>
);
}
/** 与原组件同名出口:props 驱动版本(数据/动作由消费方注入)。 */
export function DecisionQueuePanel(
props: Parameters<typeof DecisionQueuePanelView>[0],
) {
const D = usePatternLabels('decisionQueuePanel', DEFAULT_LABELS);
return (
<DecisionQueuePanelView
{...props}
labels={{ ...D, ...props.labels }}
/>
);
}
可访问性与 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。
用法说明
「该你了」待办区:queue 三态 + 阻断/排队计数 + 分页截断如实报;决策卡经 renderDecision 注入,动作走 onAction。