@xgspz/cli-ui 0.0.0-stage → 0.6.15

package/src/msglist/CliMsgList.tsx

@@ -0,0 +1,422 @@
+// cli-msglist：消息对话列表。界面取自 Operator 的任务栏（TasksColumn 的列表视图，不做看板），
+// 一张卡片是 center 里的一个对话任务（mode=conversation）。对话任务里开了几个对话时，卡片下面按对话展开，
+// 点哪个对话选哪个（选中值是对话键 "job#task"）；卡片上的「+」在这个对话任务里新开一个对话（同一个工作区）。
+import { useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type CSSProperties } from "react";
+import { CliErrorBoundary } from "../ui/ErrorBoundary";
+import type { CliEvent, JobEntry } from "../core/store";
+import type { CliStoreOptions, CliStore } from "../core/store";
+import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider, type ResultHandlers } from "../core/provider";
+import { convKey, NEW_TASK, parseConvKey, TERMINAL_JOB } from "../core/conversation";
+import type { ConversationInfo } from "../core/types";
+import { Icon } from "../ui/icons";
+import { agentLabel, relTime, toMs } from "../ui/format";
+import { AgentBadge, ErrNote, Skel, StatusDot, type DotCls } from "../ui/shared";
+import { resolveMsgListConfig, type CliMsgListConfig, type ResolvedMsgListConfig } from "../core/config";
+import { useBoardVisibility } from "../board/useBoardVisibility";
+
+/** onTurnEnd / onConversationEnd：浏览器里从实时流算出的结果通知，不依赖 center 的 callback.url。 */
+export interface CliMsgListProps extends CliStoreOptions, ResultHandlers {
+  /**
+   * 列表显示哪些对话（center 的 job_id），由宿主按自己的用户 / 业务给。
+   * 不给就是空列表（只显示本页新建的对话）：组件不会去 center 列出这个产品线令牌下的全部对话。
+   */
+  jobIds?: string[];
+  /** 受控的选中项（对话键：job_id，或 "job_id#task_id"）；不给就用共享仓库里的选中（和 cli-chat 联动）。 */
+  selectedId?: string | null;
+  /**
+   * 选了一个对话。id 是对话键：只有一个对话的对话任务是 job_id；对话任务里的某个对话是 "job_id#task_id"；
+   * 点了「+」是 "job_id#new"（在这个对话任务里新开对话）。ref 是拆开的 jobId / taskId（新开时 taskId 为 "new"）。
+   */
+  onSelect?: (id: string, ref: { jobId: string; taskId: string | null }) => void;
+  /** 点「新对话」：缺省清空选中，cli-chat 会显示空白的新对话。 */
+  onNew?: () => void;
+  /** 顶部名称与色块（如业务 / 项目名）。 */
+  title?: string;
+  color?: string;
+  /**
+   * 顶部的项目说明（只显示）。要让智能体读到，创建时用 newConversation.workspace.context，之后用 store.appendContext；
+   * onEditContext 给了就可以点开（宿主自己做编辑框）。
+   */
+  context?: string;
+  onEditContext?: () => void;
+  onCollapse?: () => void;
+  /**
+   * @deprecated 0.6.14 起列表不再定时轮询，此参数仅保留兼容、不再安排定时请求。
+   * 打开着的对话由实时流驱动；其余未结束的对话在页面回到前台、窗口重新获得焦点、网络恢复时重新拉取，也可用 store.refreshAll()。
+   */
+  pollMs?: number;
+  theme?: "light" | "dark";
+  className?: string;
+  style?: CSSProperties;
+  width?: number | string;
+  /** 界面配置：顶部栏、搜索、卡片内容、分组标题与空状态文案，见 core/config.ts。 */
+  config?: CliMsgListConfig;
+  onEvent?: (event: CliEvent) => void;
+
+  store?: CliStore;
+}
+
+export function CliMsgList(props: CliMsgListProps) {
+  const ctx = useCliStoreContext();
+  return <CliErrorBoundary component="cli-msglist" theme={props.theme}>{withOwnProvider(props, <MsgListInner {...props} inProvider={!!ctx} />, !!ctx)}</CliErrorBoundary>;
+}
+
+const SEARCH_MIN = 6;
+const BATCH_ACTIVE = new Set(["dispatching", "running", "verifying"]);
+// An orphaned task can retain a fresh, authoritative human-wait observation
+// while the center is reconciling its execution state. Do not call it running.
+const BATCH_AWAITING = new Set([...BATCH_ACTIVE, "orphaned"]);
+
+interface CardView {
+  id: string;
+  title: string;
+  desc: string;
+  cls: DotCls;
+  label: string;
+  running: boolean;
+  awaiting: boolean;
+  group: "needs" | "active" | "done" | "cancelled";
+  /** 带状态的活动（打开 card.status 时显示）。 */
+  activity: string;
+  /** 只有时间（缺省显示这个）。 */
+  when: string;
+  agent: string | null;
+  turns: number;
+  updatedAt: number;
+  /** 一次性任务（含续派，宿主把它的 job_id 放进了列表）：只能查看，不能在里面新开对话。 */
+  batch: boolean;
+  loading: boolean;
+  error: string | null;
+}
+
+export function cardView(id: string, entry: JobEntry | undefined): CardView {
+  const job = entry?.job;
+  const conv = job?.conversation;
+  const updatedAt = toMs(conv?.last_activity_at) ?? 0;
+  const batch = !!job && job.mode !== "conversation";
+  const base = { id, title: job?.title ?? id, desc: entry?.firstInput ?? "", when: updatedAt ? relTime(updatedAt) : "", agent: job?.tasks?.[0]?.agent ?? conv?.last_turn?.agent ?? null, turns: conv?.turns ?? 0, updatedAt, batch, loading: !job && !entry?.error, error: entry?.error ?? null };
+  const status = job?.status ?? "queued";
+  if (TERMINAL_JOB.has(status)) {
+    const cancelled = status === "cancelled";
+    const failed = status === "failed";
+    const label = cancelled ? "已取消" : failed ? "已失败" : "已完成";
+    return { ...base, cls: cancelled || failed ? "x" : "g", label, running: false, awaiting: false, group: cancelled ? "cancelled" : "done", activity: updatedAt ? `${label} · ${relTime(updatedAt)}` : label };
+  }
+  // A browser handoff/input card keeps its turn running while requiring a human.
+  if (batch) {
+    const running = (job?.tasks ?? []).some((task) => BATCH_ACTIVE.has(task.status));
+    const awaiting = (job?.tasks ?? []).some((task) => BATCH_AWAITING.has(task.status) && task.awaiting_input === true);
+    if (awaiting) return { ...base, cls: "a", label: "需要你处理", running, awaiting, group: "needs", activity: "等你处理" };
+    return { ...base, cls: "a", label: "进行中", running, awaiting: false, group: "active", activity: running ? "运行中 · 工作中" : status === "queued" ? "等待执行节点" : "进行中" };
+  }
+  // 开了几个对话：任何一个在跑就算在跑，任何一个停在提问上就要你处理（关掉的对话不算）。
+  const open = (conv?.conversations ?? []).filter((c) => !c.closed);
+  const many = (conv?.conversations?.length ?? 0) > 1;
+  const running = many ? open.some((c) => c.running_turn) : !!conv?.running_turn;
+  // 上一轮以提问结束、后面没有新消息：等你回答。
+  const awaiting = many ? open.some((c) => c.awaiting_input === true || (!c.running_turn && !c.queued_turns && !!c.last_turn?.asked)) : conv?.awaiting_input === true || (!running && !conv?.queued_turns && !!conv?.last_turn?.asked);
+  if (awaiting) return { ...base, cls: "a", label: "需要你处理", running, awaiting, group: "needs", activity: updatedAt ? `等你处理 · ${relTime(updatedAt)}` : "等你处理" };
+  if (running) return { ...base, cls: "a", label: "进行中", running, awaiting, group: "active", activity: "运行中 · 工作中" };
+  const waiting = conv?.queued_turns ? `${conv.queued_turns} 条排队中` : status === "queued" ? "等待执行节点" : updatedAt ? relTime(updatedAt) : "未开始";
+  return { ...base, cls: "a", label: "进行中", running, awaiting, group: "active", activity: waiting };
+}
+
+/** 对话任务里的一个对话（对话任务开了几个对话时，卡片下面的一行）。 */
+interface ConvRowView {
+  key: string;
+  title: string;
+  cls: DotCls;
+  label: string;
+  running: boolean;
+  awaiting: boolean;
+  activity: string;
+  turns: number;
+}
+
+/** 一次性任务里子任务的状态 → 行的样子。 */
+const BATCH_ROW: Record<string, { cls: DotCls; label: string; running?: boolean }> = {
+  blocked: { cls: "r", label: "等待前置" }, queued: { cls: "r", label: "排队中" },
+  dispatching: { cls: "a", label: "运行中", running: true }, running: { cls: "a", label: "运行中", running: true }, verifying: { cls: "a", label: "核对中", running: true },
+  orphaned: { cls: "a", label: "等待节点" }, stalled: { cls: "a", label: "等待节点" }, paused: { cls: "r", label: "已暂停" },
+  succeeded: { cls: "g", label: "已完成" }, failed: { cls: "x", label: "失败" }, cancelled: { cls: "x", label: "已取消" },
+};
+
+/**
+ * 卡片下面的行：对话任务里的对话（只有一个时返回 []，整张卡片就是它）；
+ * 一次性任务（宿主把它的 job_id 放进了列表）有几个子任务时，每个子任务一行——点哪行，对话和看板就看那个子任务。
+ */
+export function convRows(jobId: string, entry: JobEntry | undefined): ConvRowView[] {
+  const job = entry?.job;
+  if (job && job.mode !== "conversation") {
+    const tasks = [...(job.tasks ?? [])].sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+    if (tasks.length <= 1) return [];
+    return tasks.map((t) => {
+      const look = BATCH_ROW[t.status] ?? { cls: "a" as DotCls, label: t.status };
+      if (BATCH_AWAITING.has(t.status) && t.awaiting_input === true) return { key: convKey(jobId, t.id), title: t.title, cls: "a" as DotCls, label: "需要你处理", running: !!look.running, awaiting: true, activity: "等你处理", turns: 0 };
+      return { key: convKey(jobId, t.id), title: t.title, cls: look.cls, label: look.label, running: !!look.running, awaiting: false, activity: look.label, turns: 0 };
+    });
+  }
+  const list = entry?.job?.conversation?.conversations ?? [];
+  if (list.length <= 1) return [];
+  const jobEnded = TERMINAL_JOB.has(entry?.job?.status ?? "");
+  return list.map((c: ConversationInfo) => {
+    const base = { key: convKey(jobId, c.task_id), title: c.title, turns: c.turns };
+    if (c.closed || jobEnded) return { ...base, cls: "g" as DotCls, label: "已结束", running: false, awaiting: false, activity: "已结束" };
+    const running = c.running_turn;
+    const awaiting = c.awaiting_input === true || (!running && !c.queued_turns && !!c.last_turn?.asked);
+    if (awaiting) return { ...base, cls: "a" as DotCls, label: "需要你处理", running, awaiting, activity: "等你处理" };
+    if (running) return { ...base, cls: "a" as DotCls, label: "进行中", running, awaiting, activity: "运行中" };
+    return { ...base, cls: "a" as DotCls, label: "进行中", running, awaiting, activity: c.queued_turns ? `${c.queued_turns} 条排队中` : "空闲" };
+  });
+}
+
+function MsgCard({ v, selected, onSelect, show, onNewInJob }: { v: CardView; selected: boolean; onSelect: () => void; show: ResolvedMsgListConfig["card"]; onNewInJob?: () => void }) {
+  if (v.loading) return <CardSkeleton i={v.id.length} />;
+  const activity = show.status ? v.activity : v.when;
+  const foot = (show.activity && !!activity) || (show.turns && v.turns > 0);
+  const card = (
+    <button className={`task ${selected ? "sel" : ""} ${v.awaiting && show.status ? "awaiting" : ""}`} onClick={onSelect} title={v.error ?? undefined}>
+      <div className="task-top">
+        {show.status && <StatusDot cls={v.cls} running={v.running} awaiting={v.awaiting} title={v.label} />}
+        <span className="ttitle">{v.title}</span>
+        {show.status && <span className={`slabel ${v.awaiting ? "await" : ""}`}>{v.label}</span>}
+        {show.agent && v.agent && <AgentBadge label={agentLabel(v.agent)} />}
+      </div>
+      {show.description && v.desc && <div className="tdesc">{v.desc}</div>}
+      {v.error && <div className="blocked-chip">{Icon.x()} {v.error}</div>}
+      {foot && <div className="task-foot">
+        {show.activity && activity && <span className="activity">{show.status && (v.awaiting ? <span style={{ color: "var(--blue)" }}>●</span> : v.running ? <span style={{ color: "var(--amber)" }}>●</span> : null)}{activity}</span>}
+        <span className="spacer" />
+        {show.turns && v.turns > 0 && <span className="activity">{v.turns} 条消息</span>}
+      </div>}
+    </button>
+  );
+  if (!onNewInJob) return card;
+  // 「+」不能放进卡片按钮里（按钮不能嵌套）：叠在卡片右下角。
+  return (
+    <div className="cli-job-card">
+      {card}
+      <button className="icon-btn cli-new-in-job" onClick={onNewInJob} title="在这个任务里新开一个对话（共用同一个工作区）" aria-label="在这个任务里新开一个对话">{Icon.plus()}</button>
+    </div>
+  );
+}
+
+function ConvRow({ v, selected, following, onSelect, show }: { v: ConvRowView; selected: boolean; following?: boolean; onSelect: () => void; show: ResolvedMsgListConfig["card"] }) {
+  return (
+    <button className={`cli-conv-row ${selected ? "sel" : ""} ${following ? "following" : ""} ${v.awaiting && show.status ? "awaiting" : ""}`} onClick={onSelect}
+      title={following ? "对话和看板正在看这个子任务（跟着最近开始执行的子任务）" : undefined}>
+      {show.status && <StatusDot cls={v.cls} running={v.running} awaiting={v.awaiting} title={v.label} />}
+      <span className="cli-conv-title">{v.title}</span>
+      {show.activity && show.status && <span className="cli-conv-act">{v.activity}</span>}
+      {show.turns && v.turns > 0 && <span className="cli-conv-act">{v.turns} 条</span>}
+    </button>
+  );
+}
+
+function CardSkeleton({ i = 0 }: { i?: number }) {
+  const widths = [58, 42, 66, 38];
+  return (
+    <div className="task" style={{ cursor: "default" }} aria-hidden>
+      <div className="task-top"><Skel w={9} h={9} r="50%" /><Skel w={`${widths[i % widths.length]}%`} h={12} /><span style={{ flex: 1 }} /><Skel w={34} h={10} /></div>
+      <div className="task-foot"><Skel w={120} h={9} /></div>
+    </div>
+  );
+}
+
+type GroupProps = {
+  label: string | false; cards: CardView[]; selected: string | null; onSelect: (id: string) => void; show: ResolvedMsgListConfig["card"];
+  rows: Record<string, ConvRowView[]>; firstTask: Record<string, string | undefined>; onNewInJob?: (jobId: string) => void;
+  /** 选中一次性任务（不指定子任务）时，对话和看板实际在看的子任务：那一行标出来，三个组件看的是哪个一眼对得上。 */
+  following?: string | null;
+  accent?: boolean; collapsible?: boolean; collapsed?: boolean; onToggle?: () => void;
+  /** 不分组：只有卡片，没有组标题。 */
+  plain?: boolean;
+};
+
+function Group({ label, cards, selected, onSelect, show, rows, firstTask, onNewInJob, accent, collapsible, collapsed, onToggle, plain, following }: GroupProps) {
+  if (!cards.length || label === false) return null;
+  const sel = selected ? parseConvKey(selected) : null;
+  const list = cards.map((v) => {
+    const convs = rows[v.id] ?? [];
+    // 选中的是这个对话任务：只有 job_id 指它的第一个对话。
+    // 一次性任务：只有 job_id = 跟着最近开始执行的子任务（卡片本身选中），不落在哪一行上。
+    const selectedKey = sel?.jobId === v.id ? (v.batch ? (sel.taskId ? convKey(v.id, sel.taskId) : null) : convKey(v.id, sel.taskId ?? firstTask[v.id])) : null;
+    const newing = sel?.jobId === v.id && sel.taskId === NEW_TASK;
+    const card = (
+      <MsgCard
+        key={v.id} v={v} show={show}
+        // 只有一个对话：整张卡片就是它；有几个对话：卡片是标题，选中落在下面的行上。
+        selected={(!convs.length || v.batch) && !newing && sel?.jobId === v.id && (!v.batch || !sel?.taskId)}
+        onSelect={() => onSelect(convs.length && !v.batch ? convs.find((c) => c.key === selectedKey)?.key ?? convs[0].key : v.id)}
+        onNewInJob={onNewInJob && !v.batch && v.group !== "done" && v.group !== "cancelled" ? () => onNewInJob(v.id) : undefined}
+      />
+    );
+    if (!convs.length && !newing) return card;
+    return (
+      <div key={v.id} className="cli-job-group">
+        {card}
+        <div className="cli-conv-rows">
+          {convs.map((c) => <ConvRow key={c.key} v={c} selected={c.key === selectedKey} following={!selectedKey && v.batch && sel?.jobId === v.id && c.key === (following ? convKey(v.id, following) : null)} onSelect={() => onSelect(c.key)} show={show} />)}
+          {newing && <div className="cli-conv-row sel"><span className="cli-conv-title">新对话 · 发第一条消息后开始</span></div>}
+        </div>
+      </div>
+    );
+  });
+  if (plain) return <>{list}</>;
+  if (collapsible) {
+    return (
+      <>
+        <button className={`task-group-h tgh-btn ${collapsed ? "is-collapsed" : ""}`} onClick={onToggle} title={`${collapsed ? "展开" : "折叠"}「${label}」`}>
+          {Icon.chevDown({ className: "tgh-chev" })}
+          {label} <span className="gcount">{cards.length}</span><span className="gline" />
+        </button>
+        {!collapsed && list}
+      </>
+    );
+  }
+  return (
+    <>
+      <div className={`task-group-h ${accent ? "needs-you" : ""}`}>{label} <span className="gcount">{cards.length}</span><span className="gline" /></div>
+      {list}
+    </>
+  );
+}
+
+/** 回到前台 / 获得焦点 / 网络恢复时重新拉列表，相邻这么久以内只拉一次。 */
+const LIST_REFRESH_GAP_MS = 5_000;
+
+function MsgListInner({ jobIds, selectedId, onSelect, onNew, title = "对话", color = "#b8613f", context, onEditContext, onCollapse, config, theme = "light", className, style, width, onEvent, onTurnEnd, onConversationEnd, onCallback, inProvider }: CliMsgListProps & { inProvider: boolean }) {
+  useComponentEvents(onEvent, { onTurnEnd, onConversationEnd, onCallback }, inProvider);
+  const configKey = JSON.stringify(config ?? {});
+  const cfg = useMemo(() => resolveMsgListConfig(config), [configKey]); // eslint-disable-line react-hooks/exhaustive-deps
+  const h = cfg.header;
+  const store = useCliStore();
+  const rootRef = useRef<HTMLDivElement>(null);
+  const owner = useId();
+  const visible = useBoardVisibility(rootRef, true);
+  const expanded = visible && !className?.split(/\s+/).includes("collapsed");
+  useLayoutEffect(() => { store.reportListPresence(owner, expanded); }, [store, owner, expanded]);
+  useLayoutEffect(() => () => { store.reportListPresence(owner, false); }, [store, owner]);
+  const ids = useCliState((s) => s.jobIds);
+  const jobs = useCliState((s) => s.jobs);
+  const shared = useCliState((s) => s.selected);
+  const listLoading = useCliState((s) => s.listLoading);
+  const listError = useCliState((s) => s.listError);
+  const selected = selectedId !== undefined ? selectedId : shared;
+  const following = useCliState((s) => (selected && !parseConvKey(selected).taskId ? s.convs[selected]?.task?.id ?? null : null));
+  const [query, setQuery] = useState("");
+  const [doneCollapsed, setDoneCollapsed] = useState(false);
+  const [cancelledCollapsed, setCancelledCollapsed] = useState(true);
+  const [discovered, setDiscovered] = useState(false);
+
+  const idsKey = jobIds?.join("\n");
+  useEffect(() => { if (jobIds) store.setJobIds(jobIds); }, [store, idsKey]); // eslint-disable-line react-hooks/exhaustive-deps
+  // 宿主选中了列表里还没有的对话（例如旁边独立的 cli-chat 刚新建出来的）：加进列表，不用两个组件共享任何东西。
+  // 放在 setJobIds 之后，宿主的 jobIds 更新后也会再补一次。
+  useEffect(() => {
+    const jobId = selected ? parseConvKey(selected).jobId : null;
+    if (jobId && !ids.includes(jobId)) store.addJob(jobId);
+  }, [selected, ids, store]);
+
+  // 首次：拉一遍列表里已有的（宿主给的 jobIds）。
+  useEffect(() => {
+    void store.refreshAll({ all: true }).finally(() => setDiscovered(true));
+  }, [store]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // 不定时轮询：打开着的对话由实时流更新卡片（store 的 noticeTransitions）；其余未结束的，
+  // 在页面回到前台、窗口重新获得焦点、网络恢复时重新拉一遍（相邻 5 秒内的合并为一次）。
+  useEffect(() => {
+    let last = Date.now();
+    const refresh = () => {
+      if (document.visibilityState === "hidden" || Date.now() - last < LIST_REFRESH_GAP_MS) return;
+      last = Date.now();
+      void store.refreshAll();
+    };
+    const onVisibility = () => { if (document.visibilityState === "visible") refresh(); };
+    document.addEventListener("visibilitychange", onVisibility);
+    window.addEventListener("focus", refresh);
+    window.addEventListener("online", refresh);
+    return () => {
+      document.removeEventListener("visibilitychange", onVisibility);
+      window.removeEventListener("focus", refresh);
+      window.removeEventListener("online", refresh);
+    };
+  }, [store]);
+
+  // 新加进来的对话（别的组件新建的 / 接续出来的）还没数据：补拉一次。
+  useEffect(() => { for (const id of ids) if (!jobs[id]) void store.refreshJob(id); }, [ids, jobs, store]);
+
+  const cards = useMemo(() => ids.map((id) => cardView(id, jobs[id])), [ids, jobs]);
+  const q = query.trim().toLowerCase();
+  const shown = q ? cards.filter((c) => c.title.toLowerCase().includes(q) || c.desc.toLowerCase().includes(q)
+    || (jobs[c.id]?.job?.conversation?.conversations ?? []).some((conv) => conv.title.toLowerCase().includes(q))) : cards;
+  const byRecent = (a: CardView, b: CardView) => b.updatedAt - a.updatedAt;
+  const groups = {
+    needs: shown.filter((c) => c.group === "needs").sort(byRecent),
+    active: shown.filter((c) => c.group === "active").sort(byRecent),
+    done: shown.filter((c) => c.group === "done").sort(byRecent),
+    cancelled: shown.filter((c) => c.group === "cancelled").sort(byRecent),
+  };
+  const select = (id: string) => { if (selectedId === undefined) store.select(id); onSelect?.(id, parseConvKey(id)); };
+  const newInJob = cfg.card.newInJob ? (jobId: string) => select(convKey(jobId, NEW_TASK)) : undefined;
+  const rows = useMemo(() => Object.fromEntries(ids.map((id) => [id, convRows(id, jobs[id])])), [ids, jobs]);
+  const firstTask = useMemo(() => Object.fromEntries(ids.map((id) => [id, jobs[id]?.job?.conversation?.conversations?.[0]?.task_id ?? jobs[id]?.job?.tasks?.[0]?.id])), [ids, jobs]);
+  const groupProps = { selected, onSelect: select, show: cfg.card, rows, firstTask, onNewInJob: newInJob, following };
+  const startNew = () => { if (onNew) onNew(); else store.select(null); };
+  const firstLoad = !discovered && !cards.length;
+  const showRow = h.show && (h.title || h.newButton || h.refresh || !!onCollapse);
+  // 只显示：有文字、或者宿主给了编辑入口时才出现（发给智能体的项目背景见 newConversation.workspace.context 和 store.appendContext）。
+  const showContext = h.show && h.context && (!!context || !!onEditContext);
+  const showBanner = showRow || showContext;
+
+  return (
+    <div ref={rootRef} className={`cli-ui cli-msglist ${className ?? ""}`} data-theme={theme} style={{ ...style, ...(width !== undefined ? { width } : null) }}>
+      <div className="col col-tasks">
+        {showBanner && <div className="proj-banner">
+          {showRow && <div className="pb-row">
+            {h.title ? (
+              <span className="pb-home" style={{ cursor: "default" }}>
+                <span className="pb-pic" style={{ background: color }}>{title[0]}</span>
+                <span className="pb-name">{title}</span>
+              </span>
+            ) : <span style={{ flex: 1 }} />}
+            {h.newButton && <button className="btn btn-line btn-sm" onClick={startNew}>{Icon.plus()} {h.newButtonText}</button>}
+            {h.refresh && <button className="icon-btn" onClick={() => void store.refreshAll({ all: true })} title="刷新列表" aria-label="刷新列表" disabled={listLoading}>{Icon.restore()}</button>}
+            {onCollapse && <button className="icon-btn" onClick={onCollapse} title="隐藏对话列表">{Icon.chevRight({ style: { transform: "rotate(180deg)" } })}</button>}
+          </div>}
+          {showContext && (
+            <button className="pb-ctx" onClick={onEditContext} style={onEditContext ? undefined : { cursor: "default" }}>
+              <div className={`ctx-txt ${context ? "" : "empty-ctx"}`}>{context || "添加项目背景 —— 简介、范围与规范"}</div>
+              {onEditContext && <div className="ctx-edit">{Icon.edit()} 上下文</div>}
+            </button>
+          )}
+        </div>}
+        {(cfg.search === true || (cfg.search === "auto" && cards.length >= SEARCH_MIN)) && (
+          <div className="search-bar">
+            <span className="search-ic">{Icon.search()}</span>
+            <input className="search-input" value={query}  placeholder={cfg.searchPlaceholder} spellCheck={false} onChange={(e) => setQuery(e.target.value)} onKeyDown={(e) => { if (e.key === "Escape") setQuery(""); }} />
+            {query && <button className="search-clear" title="清除搜索" onClick={() => setQuery("")}>{Icon.x()}</button>}
+          </div>
+        )}
+        <div className="scroll">
+          <div className="task-scroll">
+            {listError && <ErrNote onRetry={() => void store.refreshAll({ all: true })}>{listError}</ErrNote>}
+            {firstLoad ? [0, 1, 2].map((i) => <CardSkeleton key={i} i={i} />) : (
+              <>
+                {cards.length === 0 && <div className="empty" style={{ padding: "30px 16px" }}><div className="e-t">{cfg.emptyTitle}</div>{cfg.emptyDescription && <div className="e-s">{cfg.emptyDescription}</div>}</div>}
+                {q && shown.length === 0 && <div className="search-empty">没有匹配“{query.trim()}”的对话。</div>}
+                {!cfg.grouped && <Group label="" cards={[...shown].sort(byRecent)} {...groupProps} plain />}
+                {cfg.grouped && <>
+                <Group label={cfg.groups.needs} cards={groups.needs} {...groupProps} accent />
+                <Group label={cfg.groups.active} cards={groups.active} {...groupProps} />
+                <Group label={cfg.groups.done} cards={groups.done} {...groupProps} collapsible collapsed={doneCollapsed && !q} onToggle={() => setDoneCollapsed((c) => !c)} />
+                <Group label={cfg.groups.cancelled} cards={groups.cancelled} {...groupProps} collapsible collapsed={cancelledCollapsed && !q} onToggle={() => setCancelledCollapsed((c) => !c)} />
+                </>}
+              </>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/operator/branchFlow.ts

@@ -0,0 +1,35 @@
+import type { Msg } from "../core/types";
+export interface BranchTask { id: string; project_id: string; title: string; agent: string; status: string; created_at?: number; updated_at?: number; parent_task_id?: string | null; fork_group_id?: string | null; fork_commit?: string | null; fork_source_title?: string | null; fork_context?: string | null; work_branch?: string; running?: number }
+
+
+export type BranchStep<T extends BranchTask = BranchTask> = { source: T | null; child: T };
+
+/** The selected path, oldest source first. Missing/deleted sources keep a boundary. */
+export function branchAncestry<T extends BranchTask>(task: T, tasks: T[]): BranchStep<T>[] {
+  const byId = new Map(tasks.filter((t) => t.project_id === task.project_id).map((t) => [t.id, t]));
+  const visited = new Set([task.id]);
+  const steps: BranchStep<T>[] = [];
+  let child = task;
+  while (child.parent_task_id && !visited.has(child.parent_task_id)) {
+    visited.add(child.parent_task_id);
+    const source = byId.get(child.parent_task_id) ?? null;
+    steps.unshift({ source, child });
+    if (!source) break;
+    child = source;
+  }
+  return steps;
+}
+
+/** Outgoing paths only; a source is never presented as its own child branch. */
+export function branchOptions<T extends BranchTask>(sourceId: string, projectId: string, tasks: T[], selected?: T): T[] {
+  const local = tasks.filter((t) => t.project_id === projectId);
+  const direct = local.filter((t) => t.parent_task_id === sourceId);
+  const groups = new Set([...direct, ...(selected ? [selected] : [])].map((t) => t.fork_group_id).filter(Boolean));
+  return local.filter((t) => t.id !== sourceId && (t.parent_task_id === sourceId || !!t.fork_group_id && groups.has(t.fork_group_id)));
+}
+
+// A parent may have been resumed since the fork. Its later messages belong to
+// that parent, not above the historical point where this child branched off.
+export function messagesAtFork(messages: Msg[], child: BranchTask): Msg[] {
+  return messages.filter((m) => m.role !== "queued" && (!child.created_at || !m.ts || m.ts <= child.created_at));
+}

package/src/operator/index.ts

@@ -0,0 +1,9 @@
+export { default as OperatorWorkspace } from "./node/Orchestrator";
+export type { TaskRow, ProjectRow, AgentsBundle } from "./node/types";
+
+export { default as OperatorFilePage } from "./node/ViewFile";
+export { default as OperatorBrowserPage } from "./node/BrowserPopup";
+
+export type { OperatorBoardOptions, OperatorBoardTab } from "./node/boardInteraction";
+
+export { createOperatorWorkspace } from "./node/boardWorkspace";

package/src/operator/liveStream.ts

@@ -0,0 +1 @@
+export * from "./node/liveStream";