@spzxg/cli-ui 0.4.0 → 0.6.1

package/src/layout/split.ts

@@ -0,0 +1,214 @@
+/**
+ * 可拖动分栏：把一个容器里横向排的几栏（列表 / 对话 / 看板，或宿主自己的栏）之间加上拖动条，左右拖改宽度。
+ * 不依赖 React：React 版 CliSplit 和 Web Component 版 <cli-split> 都用它。
+ *
+ *   attachSplit(container, { panes: [{ size: 300, min: 220, max: 480 }, { min: 360 }, { size: "42%", min: 320 }], storageKey: "strategy" })
+ *
+ * 规则：
+ *   · 写了 size 的栏是定宽（px 或百分比，百分比按容器宽度换算成 px）；没写 size 的栏占剩下的宽度（只能有一个，没有就是最后一栏）。
+ *   · 拖动条改它旁边定宽的那一栏；任何一栏都不会小于自己的 min，占剩余宽度的那栏也一样。
+ *   · 双击拖动条：那一栏回到初始宽度。键盘：拖动条能聚焦，←/→ 每次 16px（按住 Shift 64px）。
+ *   · 子元素根节点带 collapsed 类（cli-board 收起时）：那一栏变成 40px 窄条（--cli-split-collapsed），旁边的拖动条隐藏；展开后回到原来的宽度。
+ *   · 写了 storageKey：拖好的宽度记在 localStorage（cli-ui:split:<storageKey>），下次打开还是这个宽度。
+ *   · 窗口变窄时定宽栏按比例让出宽度，保证占剩余宽度的那栏不小于它的 min。
+ */
+export type SplitPane = { size?: number | `${number}%`; min?: number; max?: number };
+export type SplitOptions = {
+  panes?: SplitPane[];
+  storageKey?: string;
+  /** 拖完（松手 / 键盘 / 双击）后的各栏宽度，占剩余宽度的那栏是 null。 */
+  onResize?: (sizes: (number | null)[]) => void;
+};
+export type SplitHandle = { update: (options: SplitOptions) => void; reset: () => void; destroy: () => void };
+
+const DEFAULT_MIN = 160;
+const STEP = 16;
+
+export function attachSplit(container: HTMLElement, initial: SplitOptions = {}): SplitHandle {
+  let options = initial;
+  let sizes: (number | null)[] = [];
+  let gutters: HTMLElement[] = [];
+  let panes: HTMLElement[] = [];
+  let dragging = false;
+
+  container.classList.add("cli-split");
+
+  const key = () => (options.storageKey ? `cli-ui:split:${options.storageKey}` : null);
+  const load = (): (number | null)[] | null => {
+    const k = key();
+    if (!k) return null;
+    try { const v = JSON.parse(localStorage.getItem(k) ?? "null"); return Array.isArray(v) ? v : null; } catch { return null; }
+  };
+  const save = () => {
+    const k = key();
+    if (k) try { localStorage.setItem(k, JSON.stringify(sizes)); } catch { /* 存不下就不记 */ }
+  };
+
+  const spec = (i: number): SplitPane => options.panes?.[i] ?? {};
+  const flexIndex = () => {
+    const i = panes.findIndex((_, n) => spec(n).size === undefined);
+    return i >= 0 ? i : panes.length - 1;
+  };
+  const minOf = (i: number) => spec(i).min ?? DEFAULT_MIN;
+  const initialSize = (i: number): number | null => {
+    if (i === flexIndex()) return null;
+    const s = spec(i).size;
+    if (typeof s === "string") return Math.round((parseFloat(s) / 100) * (container.clientWidth || 1200));
+    return s ?? 320;
+  };
+  const isCollapsed = (pane: HTMLElement) => !!pane.firstElementChild?.classList.contains("collapsed");
+  const clamp = (i: number, w: number) => Math.round(Math.min(spec(i).max ?? Infinity, Math.max(minOf(i), w)));
+
+  /** 定宽栏放进容器：总宽超了就按比例收，给占剩余宽度的那栏留出它的 min。 */
+  function fitted(): (number | null)[] {
+    const total = container.clientWidth;
+    const flex = flexIndex();
+    const fixed = sizes.map((s, i) => (i === flex || isCollapsed(panes[i]) ? 0 : s ?? 0));
+    const collapsedW = panes.reduce((sum, p, i) => sum + (i !== flex && isCollapsed(p) ? p.getBoundingClientRect().width : 0), 0);
+    const room = total - minOf(flex) - collapsedW;
+    const sum = fixed.reduce((a, b) => a + b, 0);
+    if (!total || sum <= room) return sizes;
+    const ratio = Math.max(0, room) / sum;
+    return sizes.map((s, i) => (i === flex || s === null ? null : Math.max(minOf(i), Math.floor(s * ratio))));
+  }
+
+  function apply() {
+    const flex = flexIndex();
+    const shown = fitted();
+    panes.forEach((pane, i) => {
+      pane.classList.add("cli-split-pane");
+      if (i === flex) { pane.style.flex = "1 1 0"; pane.style.width = ""; pane.style.minWidth = `${minOf(i)}px`; return; }
+      // 收起的栏（cli-board 的窄条宽度是 100%，没有自身宽度）：固定窄条宽，宿主可用 --cli-split-collapsed 改。
+      if (isCollapsed(pane)) { pane.style.flex = "0 0 var(--cli-split-collapsed, 40px)"; pane.style.width = ""; pane.style.minWidth = ""; return; }
+      pane.style.flex = `0 0 ${shown[i]}px`;
+      pane.style.width = `${shown[i]}px`;
+      pane.style.minWidth = "0";
+    });
+    gutters.forEach((g, i) => {
+      const hidden = isCollapsed(panes[i]) || isCollapsed(panes[i + 1]);
+      g.hidden = hidden;
+      g.setAttribute("aria-valuenow", String(Math.round(panes[sideOf(i)]?.getBoundingClientRect().width ?? 0)));
+    });
+  }
+
+  /** 拖动条 i（在第 i 栏和第 i+1 栏之间）改的是哪一栏：左边定宽改左边，否则改右边。 */
+  const sideOf = (gutter: number) => (gutter === flexIndex() ? gutter + 1 : gutter);
+
+  function resize(gutter: number, dx: number) {
+    const target = sideOf(gutter);
+    const sign = target === gutter ? 1 : -1;
+    const flex = flexIndex();
+    const current = panes[target].getBoundingClientRect().width;
+    // 占剩余宽度的那栏不能被挤到 min 以下。
+    const flexW = panes[flex].getBoundingClientRect().width;
+    const grow = Math.min(sign * dx, flexW - minOf(flex));
+    sizes[target] = clamp(target, current + grow);
+    apply();
+  }
+
+  function finish() { save(); options.onResize?.([...sizes]); }
+
+  function makeGutter(index: number) {
+    const g = document.createElement("div");
+    g.className = "cli-split-gutter";
+    g.tabIndex = 0;
+    g.setAttribute("role", "separator");
+    g.setAttribute("aria-orientation", "vertical");
+    g.setAttribute("aria-label", "拖动调整宽度");
+    g.title = "拖动调整宽度，双击恢复";
+    g.addEventListener("pointerdown", (e) => {
+      if (e.button !== 0) return;
+      e.preventDefault();
+      g.setPointerCapture(e.pointerId);
+      dragging = true;
+      container.classList.add("cli-split-dragging");
+      let last = e.clientX;
+      const move = (ev: PointerEvent) => { const dx = ev.clientX - last; if (!dx) return; last = ev.clientX; resize(index, dx); };
+      const up = () => {
+        dragging = false;
+        container.classList.remove("cli-split-dragging");
+        g.removeEventListener("pointermove", move);
+        g.removeEventListener("pointerup", up);
+        g.removeEventListener("pointercancel", up);
+        finish();
+      };
+      g.addEventListener("pointermove", move);
+      g.addEventListener("pointerup", up);
+      g.addEventListener("pointercancel", up);
+    });
+    g.addEventListener("dblclick", () => {
+      const target = sideOf(index);
+      sizes[target] = initialSize(target);
+      apply();
+      finish();
+    });
+    g.addEventListener("keydown", (e) => {
+      if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
+      e.preventDefault();
+      resize(index, (e.key === "ArrowLeft" ? -1 : 1) * (e.shiftKey ? STEP * 4 : STEP));
+      finish();
+    });
+    return g;
+  }
+
+  /** 子元素变了（宿主增删栏）：重新找栏、重新插拖动条。 */
+  function rebuild() {
+    for (const g of gutters) g.remove();
+    panes = [...container.children].filter((c): c is HTMLElement => c instanceof HTMLElement && !c.classList.contains("cli-split-gutter"));
+    const saved = load();
+    const flex = flexIndex();
+    sizes = panes.map((_, i) => {
+      if (i === flex) return null;
+      const keep = sizes[i];
+      if (typeof keep === "number") return keep;
+      const s = saved && saved.length === panes.length ? saved[i] : null;
+      return typeof s === "number" ? clamp(i, s) : initialSize(i);
+    });
+    gutters = panes.slice(0, -1).map((_, i) => makeGutter(i));
+    gutters.forEach((g, i) => panes[i].after(g));
+    apply();
+  }
+
+  // 只看栏的增删、栏的根节点换了、根节点的 class 变了（收起 / 展开）；栏里面的内容（流式输出）不看，不然每个字都要重排。
+  const observer = new MutationObserver((records) => {
+    if (dragging) return;
+    const structural = records.some((r) => r.type === "childList" && r.target === container
+      && [...r.addedNodes, ...r.removedNodes].some((n) => !(n instanceof HTMLElement && n.classList.contains("cli-split-gutter"))));
+    observer.disconnect();
+    if (structural) rebuild(); else apply();
+    observe();
+  });
+  const observe = () => {
+    observer.observe(container, { childList: true });
+    for (const p of panes) {
+      observer.observe(p, { childList: true });
+      if (p.firstElementChild) observer.observe(p.firstElementChild, { attributes: true, attributeFilter: ["class"] });
+    }
+  };
+  const ro = typeof ResizeObserver !== "undefined" ? new ResizeObserver(() => { if (!dragging) apply(); }) : null;
+
+  rebuild();
+  observe();
+  ro?.observe(container);
+
+  return {
+    update(next) {
+      const keyChanged = next.storageKey !== options.storageKey;
+      options = next;
+      if (keyChanged) sizes = [];
+      observer.disconnect(); rebuild(); observe();
+    },
+    reset() {
+      sizes = panes.map((_, i) => initialSize(i));
+      apply();
+      finish();
+    },
+    destroy() {
+      observer.disconnect();
+      ro?.disconnect();
+      for (const g of gutters) g.remove();
+      for (const p of panes) { p.style.flex = ""; p.style.width = ""; p.style.minWidth = ""; p.classList.remove("cli-split-pane"); }
+      container.classList.remove("cli-split", "cli-split-dragging");
+    },
+  };
+}

package/src/msglist/CliMsgList.tsx

@@ -2,6 +2,7 @@
 // 一张卡片是 center 里的一个对话任务（mode=conversation）。对话任务里开了几个对话时，卡片下面按对话展开，
 // 点哪个对话选哪个（选中值是对话键 "job#task"）；卡片上的「+」在这个对话任务里新开一个对话（同一个工作区）。
 import { useEffect, useMemo, useState, type CSSProperties } from "react";
+import { CliErrorBoundary } from "../ui/ErrorBoundary.js";
 import type { CliEvent, JobEntry } from "../core/store.js";
 import type { CliStoreOptions, CliStore } from "../core/store.js";
 import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider, type ResultHandlers } from "../core/provider.js";
@@ -14,10 +15,11 @@ import { resolveMsgListConfig, type CliMsgListConfig, type ResolvedMsgListConfig
 
 /** onTurnEnd / onConversationEnd：浏览器里从实时流算出的结果通知，不依赖 center 的 callback.url。 */
 export interface CliMsgListProps extends CliStoreOptions, ResultHandlers {
-  /** 列表显示哪些对话（center 的 job_id）。不给就用本地记住的 + （discover 时）从 center 发现的。 */
+  /**
+   * 列表显示哪些对话（center 的 job_id），由宿主按自己的用户 / 业务给。
+   * 不给就是空列表（只显示本页新建的对话）：组件不会去 center 列出这个产品线令牌下的全部对话。
+   */
   jobIds?: string[];
-  /** 没给 jobIds 时，挂载后从 center 发现本产品线的对话。缺省 true。 */
-  discover?: boolean;
   /** 受控的选中项（对话键：job_id，或 "job_id#task_id"）；不给就用共享仓库里的选中（和 cli-chat 联动）。 */
   selectedId?: string | null;
   /**
@@ -30,7 +32,10 @@ export interface CliMsgListProps extends CliStoreOptions, ResultHandlers {
   /** 顶部名称与色块（如业务 / 项目名）。 */
   title?: string;
   color?: string;
-  /** 顶部的说明文字（对应 Operator 的项目上下文）。 */
+  /**
+   * 顶部的项目说明（只显示）。要让智能体读到，创建时用 newConversation.workspace.context，之后用 store.appendContext；
+   * onEditContext 给了就可以点开（宿主自己做编辑框）。
+   */
   context?: string;
   onEditContext?: () => void;
   onCollapse?: () => void;
@@ -49,7 +54,7 @@ export interface CliMsgListProps extends CliStoreOptions, ResultHandlers {
 
 export function CliMsgList(props: CliMsgListProps) {
   const ctx = useCliStoreContext();
-  return withOwnProvider(props, <MsgListInner {...props} inProvider={!!ctx} />, !!ctx);
+  return <CliErrorBoundary component="cli-msglist" theme={props.theme}>{withOwnProvider(props, <MsgListInner {...props} inProvider={!!ctx} />, !!ctx)}</CliErrorBoundary>;
 }
 
 const SEARCH_MIN = 6;
@@ -119,8 +124,28 @@ interface ConvRowView {
   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 };
+      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 ?? "");
@@ -166,9 +191,10 @@ function MsgCard({ v, selected, onSelect, show, onNewInJob }: { v: CardView; sel
   );
 }
 
-function ConvRow({ v, selected, onSelect, show }: { v: ConvRowView; selected: boolean; onSelect: () => void; show: ResolvedMsgListConfig["card"] }) {
+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" : ""} ${v.awaiting && show.status ? "awaiting" : ""}`} onClick={onSelect}>
+    <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>}
@@ -190,25 +216,28 @@ function CardSkeleton({ i = 0 }: { i?: number }) {
 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 }: GroupProps) {
+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 指它的第一个对话。
-    const selectedKey = sel?.jobId === v.id ? convKey(v.id, sel.taskId ?? firstTask[v.id]) : null;
+    // 一次性任务：只有 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 && !newing && sel?.jobId === v.id}
-        onSelect={() => onSelect(convs.length ? convs.find((c) => c.key === selectedKey)?.key ?? convs[0].key : v.id)}
+        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}
       />
     );
@@ -217,7 +246,7 @@ function Group({ label, cards, selected, onSelect, show, rows, firstTask, onNewI
       <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} onSelect={() => onSelect(c.key)} show={show} />)}
+          {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>
@@ -243,7 +272,7 @@ function Group({ label, cards, selected, onSelect, show, rows, firstTask, onNewI
   );
 }
 
-function MsgListInner({ jobIds, discover = true, selectedId, onSelect, onNew, title = "对话", color = "#b8613f", context, onEditContext, onCollapse, pollMs = 10_000, config, theme = "light", className, style, width, onEvent, onTurnEnd, onConversationEnd, onCallback, inProvider }: CliMsgListProps & { inProvider: boolean }) {
+function MsgListInner({ jobIds, selectedId, onSelect, onNew, title = "对话", color = "#b8613f", context, onEditContext, onCollapse, pollMs = 10_000, 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
@@ -255,6 +284,7 @@ function MsgListInner({ jobIds, discover = true, selectedId, onSelect, onNew, ti
   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);
@@ -269,12 +299,9 @@ function MsgListInner({ jobIds, discover = true, selectedId, onSelect, onNew, ti
     if (jobId && !ids.includes(jobId)) store.addJob(jobId);
   }, [selected, ids, store]);
 
-  // 首次：刷新已知的；没给 jobIds 时再去 center 发现。
+  // 首次：拉一遍列表里已有的（宿主给的 jobIds）。
   useEffect(() => {
-    void store.refreshAll({ all: true }).then(() => {
-      if (!jobIds && discover) return store.discover().finally(() => setDiscovered(true));
-      setDiscovered(true);
-    });
+    void store.refreshAll({ all: true }).finally(() => setDiscovered(true));
   }, [store]); // eslint-disable-line react-hooks/exhaustive-deps
 
   useEffect(() => {
@@ -301,11 +328,12 @@ function MsgListInner({ jobIds, discover = true, selectedId, onSelect, onNew, ti
   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 };
+  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);
-  const showContext = h.show && h.context && (context !== undefined || !!onEditContext);
+  // 只显示：有文字、或者宿主给了编辑入口时才出现（发给智能体的项目背景见 newConversation.workspace.context 和 store.appendContext）。
+  const showContext = h.show && h.context && (!!context || !!onEditContext);
   const showBanner = showRow || showContext;
 
   return (
@@ -325,7 +353,7 @@ function MsgListInner({ jobIds, discover = true, selectedId, onSelect, onNew, ti
           </div>}
           {showContext && (
             <button className="pb-ctx" onClick={onEditContext} style={onEditContext ? undefined : { cursor: "default" }}>
-              <div className={`ctx-txt ${context ? "" : "empty-ctx"}`}>{context || "添加上下文 —— 简介、背景与规范，会附加到每个对话前。"}</div>
+              <div className={`ctx-txt ${context ? "" : "empty-ctx"}`}>{context || "添加项目背景 —— 简介、范围与规范"}</div>
               {onEditContext && <div className="ctx-edit">{Icon.edit()} 上下文</div>}
             </button>
           )}

package/src/styles.css

@@ -124,6 +124,12 @@
 .cli-ui .cli-fv-csv th{position:sticky;top:0;background:var(--surface-2);font-weight:600;}
 .cli-ui .cli-fv-note{padding:18px 16px;font-size:13px;color:var(--ink-3);line-height:1.7;}
 .cli-ui .cli-fv-note.err{color:var(--red);}
+.cli-ui .cli-zip-bar{display:flex;flex-wrap:wrap;align-items:center;gap:6px 8px;}
+.cli-ui .cli-zip-meter{flex:1 1 100%;height:3px;border-radius:2px;background:var(--line-2);overflow:hidden;}
+.cli-ui .cli-zip-meter>span{display:block;height:100%;background:var(--accent);transition:width .2s;}
+.cli-ui .cli-fv-trunc.cli-files-err{color:var(--red);}
+.cli-ui .cli-fv-slow{margin-top:6px;font-size:12px;color:var(--ink-3);}
+.cli-ui .cli-fv-img-err{display:flex;flex-direction:column;align-items:center;gap:8px;padding:32px 16px;color:var(--red);font-size:13px;}
 .cli-ui .cli-fv-trunc{padding:6px 14px;font-size:12px;color:var(--amber);background:var(--surface-2);border-bottom:1px solid var(--line-2);}
 
 /* 对话里弹窗打开的文件 / 浏览器 */
@@ -139,8 +145,20 @@
 /* 键盘 / 输入法接收框：不放到屏幕外（focus 时会把宿主的滚动容器拖过去），透明盖在左上角，不挡点击。 */
 .cli-ui .bp-keys{position:absolute;left:0;top:0;width:1px;height:1px;opacity:0;pointer-events:none;resize:none;border:0;padding:0;}
 
+/* 网页弹出的 alert / confirm / prompt：画面里看不到，盖在画面上处理 */
+.cli-ui .bp-dialog{position:absolute;inset:0;display:grid;place-items:center;background:rgba(0,0,0,.28);z-index:2;}
+.cli-ui .bp-dialog-box{width:min(360px,calc(100% - 24px));background:var(--panel);color:var(--ink);border:1px solid var(--line);border-radius:var(--r);box-shadow:var(--sh-2);padding:14px 16px;display:flex;flex-direction:column;gap:10px;}
+.cli-ui .bp-dialog-t{font-size:12px;color:var(--ink-3);}
+.cli-ui .bp-dialog-m{font-size:13.5px;line-height:1.6;white-space:pre-wrap;word-break:break-word;max-height:40vh;overflow:auto;}
+.cli-ui .bp-dialog-in{width:100%;padding:6px 8px;border:1px solid var(--line);border-radius:6px;background:var(--surface);color:var(--ink);font:inherit;}
+.cli-ui .bp-dialog-hint{font-size:12px;color:var(--amber);}
+.cli-ui .bp-dialog-a{display:flex;justify-content:flex-end;gap:8px;}
+
 /* ── 窄容器（手机、很窄的侧栏）：预览工具栏换行，次要信息收起 ── */
 .cli-ui .cli-fv{container-type:inline-size;}
+.cli-ui .cli-fv{position:relative;}
+.cli-ui .cli-fv-selq{position:absolute;z-index:5;transform:translate(-50%,calc(-100% - 6px));display:inline-flex;align-items:center;gap:4px;padding:4px 10px;border-radius:999px;font-size:12px;white-space:nowrap;color:#fff;background:var(--ink);box-shadow:var(--sh-2, 0 4px 14px rgba(0,0,0,.18));}
+.cli-ui .cli-fv-selq svg{width:12px;height:12px;}
 .cli-ui .cli-fv-h{flex-wrap:wrap;row-gap:4px;}
 @container (max-width:380px){
   .cli-ui .cli-fv-meta{display:none;}
@@ -172,3 +190,86 @@
 .cli-ui .cli-conv-row.awaiting{box-shadow:inset 2px 0 0 var(--blue);}
 .cli-ui .cli-conv-title{flex:1;min-width:0;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
 .cli-ui .cli-conv-act{font-family:var(--mono);font-size:10px;color:var(--ink-3);white-space:nowrap;}
+
+/* 组件出错时只影响自己那一块 */
+.cli-ui.cli-error{display:flex;flex-direction:column;align-items:flex-start;gap:8px;padding:16px;height:100%;background:var(--panel);color:var(--ink-2);font-size:13px;}
+.cli-ui .cli-error-t{font-weight:600;color:var(--ink);}
+.cli-ui .cli-error-m{color:var(--ink-3);font-family:var(--mono);font-size:11.5px;word-break:break-all;}
+
+/* ── 可拖动分栏（CliSplit / <cli-split>，见 layout/split.ts） ── */
+.cli-split{display:flex;align-items:stretch;width:100%;height:100%;min-height:0;overflow:hidden;}
+.cli-split > .cli-split-pane{min-height:0;height:100%;overflow:hidden;}
+.cli-split > .cli-split-pane > *{height:100%;}
+/* 拖动条不占宽度：9px 的手柄压在两栏的分界线上，中间 1px 的线悬停 / 聚焦 / 拖动时变色 */
+.cli-split > .cli-split-gutter{flex:0 0 9px;margin:0 -4px;position:relative;z-index:6;cursor:col-resize;touch-action:none;outline:none;}
+.cli-split > .cli-split-gutter[hidden]{display:none;}
+.cli-split > .cli-split-gutter::after{content:"";position:absolute;top:0;bottom:0;left:4px;width:1px;background:transparent;transition:background .12s,width .12s,left .12s;}
+.cli-split > .cli-split-gutter:hover::after,
+.cli-split > .cli-split-gutter:focus-visible::after,
+.cli-split.cli-split-dragging > .cli-split-gutter:active::after{left:3px;width:3px;background:#b8613f;}
+.cli-split.cli-split-dragging{cursor:col-resize;user-select:none;}
+/* 拖动时 iframe（HTML / PDF 预览）不吃指针事件，否则拖过它就断了 */
+.cli-split.cli-split-dragging iframe{pointer-events:none;}
+cli-split{display:block;}
+
+/* 工具卡片的预览：窄栏里按行换行，不出横向滚动条（diff 保持原样对齐） */
+.cli-ui .tpeek-pre:not(.diff){white-space:pre-wrap;overflow-wrap:anywhere;overflow-x:hidden;}
+/* 一次性任务整体选中时，对话和看板正在跟的那个子任务 */
+.cli-ui .cli-conv-row.following{border-color:var(--accent);border-style:dashed;background:var(--surface);}
+
+/* 浏览器放大：盖住页面，画面按窗口大小显示（接管后登录、填验证码） */
+.cli-ui.bp-backdrop{position:fixed;inset:0;background:rgba(20,23,28,.45);z-index:999;}
+.cli-ui .bp.bp-big{position:fixed;inset:20px;z-index:1000;display:flex;flex-direction:column;gap:10px;background:var(--panel);border-radius:12px;box-shadow:0 20px 60px rgba(0,0,0,.3);overflow:auto;--cli-browser-max-h:calc(100vh - 230px);}
+.cli-ui .bp.bp-big .bp-viewer{flex:1 1 auto;min-height:0;}
+.cli-ui .bp-head .bp-zoom{white-space:nowrap;}
+
+/* 续等浏览器那边的人：收成一行 */
+.cli-ui .cli-wait-fold{display:flex;align-items:center;gap:8px;width:100%;margin:6px 0;padding:7px 12px;border:1px dashed var(--line-strong);border-radius:var(--r);background:var(--surface-2);color:var(--ink-3);font-size:12.5px;text-align:left;cursor:pointer;}
+.cli-ui .cli-wait-fold:hover{color:var(--ink-2);border-color:var(--accent);}
+.cli-ui .cli-wait-more{margin-left:auto;font-size:11.5px;color:var(--accent);}
+
+/* 文件预览放大：盖住页面 */
+.cli-ui.cli-fv-backdrop{position:fixed;inset:0;background:rgba(20,23,28,.45);z-index:999;}
+.cli-ui .cli-fv.cli-fv-big{position:fixed;inset:20px;z-index:1000;border-radius:12px;box-shadow:0 20px 60px rgba(0,0,0,.3);overflow:hidden;}
+.cli-ui .cli-fv-zoom{font-size:14px;line-height:1;}
+/* 图片缩放 */
+.cli-ui .cli-fv-imgwrap{display:flex;flex-direction:column;min-height:100%;}
+.cli-ui .cli-fv-imgbar{display:flex;align-items:center;gap:4px;padding:6px 10px;border-bottom:1px solid var(--line);background:var(--surface);position:sticky;top:0;z-index:1;}
+.cli-ui .cli-fv-imgpct{font-family:var(--mono);font-size:11px;color:var(--ink-3);min-width:44px;text-align:center;}
+.cli-ui .cli-fv-imgwrap .cli-fv-img{flex:1;}
+.cli-ui .cli-fv-img.zoomed{display:block;overflow:auto;}
+.cli-ui .cli-fv-img.zoomed img{display:block;margin:0 auto;}
+
+/* 看板引用到对话：输入框上方的小卡片 */
+.cli-ui .cli-refs{display:flex;flex-wrap:wrap;align-items:center;gap:6px;padding:8px 16px 0;font-size:12px;}
+.cli-ui .cli-refs-t{display:inline-flex;align-items:center;gap:4px;color:var(--ink-3);}
+.cli-ui .cli-refs-t svg{width:13px;height:13px;}
+.cli-ui .cli-ref{display:inline-flex;align-items:center;gap:4px;max-width:260px;padding:3px 4px 3px 9px;border:1px solid var(--line-strong);border-radius:999px;background:var(--surface);}
+.cli-ui .cli-ref-l{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+.cli-ui .cli-ref-x{display:inline-grid;place-items:center;width:18px;height:18px;border-radius:50%;color:var(--ink-3);}
+.cli-ui .cli-ref-x:hover{background:var(--surface-2);color:var(--ink);}
+.cli-ui .cli-ref-x svg{width:10px;height:10px;}
+.cli-ui .cli-ref.auto{border-style:dashed;background:transparent;}
+.cli-ui .cli-ref-k{color:var(--ink-3);flex:none;}
+.cli-ui .cli-ref.sel .cli-ref-l::before{content:"“";}
+
+/* 看板页签：文件可以开多个（可关），页签多了横向滚动，刷新 / 收起按钮固定在右边。 */
+.cli-ui .cli-board .rail-tabs{align-items:stretch;}
+.cli-ui .rail-tabs-scroll{flex:1 1 auto;min-width:0;display:flex;gap:2px;overflow-x:auto;scrollbar-width:none;}
+.cli-ui .rail-tabs-scroll::-webkit-scrollbar{display:none;}
+.cli-ui .rail-tabs-scroll .rail-tab{flex:none;}
+.cli-ui .rail-ftab{display:inline-flex;align-items:center;gap:2px;max-width:180px;padding-right:4px;letter-spacing:0;font-family:inherit;font-size:12px;}
+.cli-ui .rail-ftab-l{display:inline-flex;align-items:center;gap:4px;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:inherit;background:none;border:0;padding:0;cursor:pointer;font:inherit;}
+.cli-ui .rail-ftab-l svg{width:12px;height:12px;flex:none;}
+.cli-ui .rail-ftab-x{display:inline-grid;place-items:center;flex:none;width:16px;height:16px;border-radius:4px;border:0;background:none;color:var(--ink-4);cursor:pointer;opacity:.6;}
+.cli-ui .rail-ftab:hover .rail-ftab-x,.cli-ui .rail-ftab.on .rail-ftab-x{opacity:1;}
+.cli-ui .rail-ftab-x:hover{background:var(--surface-2);color:var(--ink);}
+.cli-ui .rail-ftab-x svg{width:9px;height:9px;}
+.cli-ui .bp-toast-btn{margin-left:8px;padding:1px 8px;border-radius:999px;border:1px solid rgba(255,255,255,.5);background:transparent;color:inherit;font-size:12px;cursor:pointer;}
+.cli-ui .bp-toast-btn:hover{background:rgba(255,255,255,.15);}
+.cli-ui .bp-toast{max-width:calc(100% - 24px);white-space:normal;text-align:center;}
+/* 预览里的长链接、长单词（报告里常见的超长搜索地址）换行，不撑出看板。 */
+.cli-ui .cli-fv-md{overflow-wrap:anywhere;}
+.cli-ui .cli-fv-md pre,.cli-ui .cli-fv-md table{overflow-wrap:normal;}
+.cli-ui .cli-refs.cli-ctxs+.cli-refs{padding-top:4px;}
+.cli-ui .cli-ref.ctx{padding-right:9px;background:var(--surface-2);border-color:var(--line-2);}

package/src/ui/ErrorBoundary.tsx

@@ -0,0 +1,38 @@
+// 组件嵌在业务方的页面里：组件自己渲染出错时只影响它自己那一块（显示「出错了，重试」），不能把宿主整个页面带白屏。
+// 出错时在 window 上发一个 "cli-ui-error" 事件（detail: { component, error }），宿主可以接到自己的监控里。
+import { Component, type ReactNode } from "react";
+
+interface Props { component: string; theme?: "light" | "dark"; children: ReactNode }
+interface State { error: Error | null; attempt: number }
+
+export class CliErrorBoundary extends Component<Props, State> {
+  state: State = { error: null, attempt: 0 };
+
+  static getDerivedStateFromError(error: unknown): Partial<State> {
+    return { error: error instanceof Error ? error : new Error(String(error)) };
+  }
+
+  componentDidCatch(error: unknown) {
+    console.error(`[@spzxg/cli-ui] <${this.props.component}> 渲染出错`, error);
+    try {
+      window.dispatchEvent(new CustomEvent("cli-ui-error", { detail: { component: this.props.component, error } }));
+    } catch { /* 没有 window（服务端渲染）就不发 */ }
+  }
+
+  render() {
+    const { error, attempt } = this.state;
+    if (!error) return <ErrorKey key={attempt}>{this.props.children}</ErrorKey>;
+    return (
+      <div className="cli-ui cli-error" data-theme={this.props.theme ?? "light"} role="alert">
+        <div className="cli-error-t">这一块暂时显示不了</div>
+        <div className="cli-error-m">{error.message || "未知错误"}</div>
+        <button className="btn btn-line btn-sm" onClick={() => this.setState((s) => ({ error: null, attempt: s.attempt + 1 }))}>重试</button>
+      </div>
+    );
+  }
+}
+
+/** 重试时换 key：子树整个重建，不带着出错前的状态。 */
+function ErrorKey({ children }: { children: ReactNode }) {
+  return <>{children}</>;
+}

package/src/ui/TextBlock.tsx

@@ -22,7 +22,7 @@ export const TextBlockCard = memo(function TextBlockCard({ block, onRemove }: {
   return (
     <div className={`cli-block ${open ? "open" : ""}`}>
       <div className="cli-block-h">
-        <span className="cli-block-ic">{block.kind === "file" ? Icon.doc() : Icon.clip()}</span>
+        <span className="cli-block-ic">{block.kind === "file" ? Icon.doc() : block.kind === "context" || block.kind === "viewing" ? Icon.board() : block.kind === "background" ? Icon.flag() : Icon.clip()}</span>
         <span className="cli-block-name" title={block.name}>{block.name}</span>
         <span className="cli-block-meta">{fmtCount(chars)} 字 · {fmtCount(lines)} 行</span>
         <span className="cli-block-sp" />

package/src/ui/Transcript.tsx

@@ -283,9 +283,10 @@ function AttachmentStrip({ items, attachmentUrl }: { items: MsgAttachment[]; att
 }
 
 /** 用户消息正文：普通文字按 markdown 渲染，附件 / 长粘贴是可折叠卡片，很长的纯文字也折叠。 */
-function UserBody({ content, attachmentUrl }: { content: string; attachmentUrl?: (a: MsgAttachment) => string | null }) {
+function UserBody({ content, attachmentUrl, viewing = true }: { content: string; attachmentUrl?: (a: MsgAttachment) => string | null; viewing?: boolean }) {
   const { text, attachments } = splitAttachments(content);
-  const parts = text ? splitMessage(text) : [];
+  // 看板上正在看的东西（缺省随消息带上的那块）：配置成不显示时转录里也不显示。
+  const parts = (text ? splitMessage(text) : []).filter((p) => viewing || p.kind !== "block" || p.block.kind !== "viewing");
   return (
     <>
       {parts.map((part, i) => part.kind === "block"
@@ -310,7 +311,11 @@ function LongText({ text }: { text: string }) {
 }
 
 /** 消息行的显示选项（来自组件配置）。要引用稳定，否则 memo 失效。 */
-export interface MessageViewOptions { timestamps: boolean; initialBadge: boolean; userLabel: string; agentName: string }
+export interface MessageViewOptions {
+  timestamps: boolean; initialBadge: boolean; userLabel: string; agentName: string;
+  /** 用户消息里「看板正在看」那块显示成卡片；false = 不显示（照样发给了智能体）。缺省显示。 */
+  viewingBlock?: boolean;
+}
 const DEFAULT_VIEW: MessageViewOptions = { timestamps: true, initialBadge: true, userLabel: "你", agentName: "智能体" };
 
 export interface MessageHandlers {
@@ -340,7 +345,7 @@ export const MessageView = memo(function MessageView({ m, initial: isInitial, hi
       <div className="msg user queued">
         <div className="who"><Avatar who="user" /> {view.userLabel}<span className="badge queued-badge">排队中</span>{time}</div>
         <div className="msg-body">
-          <UserBody content={m.content} attachmentUrl={handlers.attachmentUrl} />
+          <UserBody content={m.content} attachmentUrl={handlers.attachmentUrl} viewing={view.viewingBlock} />
           {m.note && <div className="cli-queued-note">⏳ {m.note}</div>}
           {handlers.onCancelQueued && <button className="queued-x" title="从队列中移除" aria-label="从队列中移除" onClick={() => handlers.onCancelQueued!(m)}>{Icon.x()}</button>}
         </div>
@@ -388,7 +393,7 @@ export const MessageView = memo(function MessageView({ m, initial: isInitial, hi
       )}
       <div className="msg-body">
         {initial && <div className="initial-tag">{Icon.spark()} 已随项目上下文发送</div>}
-        {isUser ? <UserBody content={m.content} attachmentUrl={handlers.attachmentUrl} /> : m.content && <Markdown>{m.content}</Markdown>}
+        {isUser ? <UserBody content={m.content} attachmentUrl={handlers.attachmentUrl} viewing={view.viewingBlock} /> : m.content && <Markdown>{m.content}</Markdown>}
       </div>
     </div>
   );