@spzxg/cli-ui 0.3.1 → 0.6.0

package/src/chat/CliChat.tsx

@@ -2,9 +2,11 @@
 // 数据来自 center 的对话任务（mode=conversation）：实时流里的节点转录按 Operator 的规则渲染，
 // 每条消息是中枢的一轮，排队 / 执行 / 结束都跟 center 保持一致。
 import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type CSSProperties } from "react";
+import { CliErrorBoundary } from "../ui/ErrorBoundary.js";
 import type { CliEvent, CliStore, CliStoreOptions } from "../core/store.js";
 import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider, type ResultHandlers } from "../core/provider.js";
-import { convKey, emptyConv, isNewInJob, isRunning, parseConvKey, runningTurn, TERMINAL_JOB, viewMessages } from "../core/conversation.js";
+import { boardContextBlock, serializeBlock } from "../core/blocks.js";
+import { convKey, emptyConv, isChatTask, isNewInJob, isRunning, parseConvKey, runningTurn, TERMINAL_JOB, viewMessages } from "../core/conversation.js";
 import type { AskAnswers, AskQuestion, Msg } from "../core/types.js";
 import { Icon } from "../ui/icons.js";
 import { agentLabel as labelOf, fmtTokens, formatAnswersText, modelLabel } from "../ui/format.js";
@@ -66,7 +68,7 @@ export interface CliChatProps extends CliStoreOptions, ResultHandlers {
 
 export function CliChat(props: CliChatProps) {
   const ctx = useCliStoreContext();
-  return withOwnProvider(props, <ChatInner {...props} inProvider={!!ctx} />, !!ctx);
+  return <CliErrorBoundary component="cli-chat" theme={props.theme}>{withOwnProvider(props, <ChatInner {...props} inProvider={!!ctx} />, !!ctx)}</CliErrorBoundary>;
 }
 
 // 不能再发消息的结束原因（调用方关闭 / 取消）。其余原因（过期、换线、节点丢失）再发会自动开新对话。
@@ -76,6 +78,9 @@ const REASON_TEXT: Record<string, string> = {
   node_reassigned: "执行机器换到了别的产品线", node_lost: "执行节点长时间连不上",
 };
 
+/** 子任务结束了的状态：可以接着它聊。 */
+const SETTLED_TASK = new Set(["succeeded", "failed", "cancelled"]);
+
 // 一次性任务（含续派）的子任务状态（center TaskStatus）。
 const BATCH_STATUS: Record<string, { dotCls: DotCls; statusText: string }> = {
   succeeded: { dotCls: "g", statusText: "子任务已完成" }, failed: { dotCls: "x", statusText: "子任务失败" }, cancelled: { dotCls: "x", statusText: "子任务已取消" },
@@ -170,8 +175,16 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
   const running = conv ? isRunning(conv) : false;
   const job = entry?.job;
   // 一次性任务（含续派，不是对话任务）：只读查看其中一个子任务——没有轮次，不能发消息、结束、回答。
+  // 例外是对话式子任务（续派时 mode=conversation）：当对话用，随时能接着发（= 续派一条接着它），不显示子任务状态。
   const batch = !!conv?.batch || (!!job && job.mode !== "conversation");
-  const readOnly = !!readOnlyProp || !cfg.composer.show || batch;
+  const chat = !!taskId && isChatTask(conv);
+  // 普通子任务结束后（完成 / 失败 / 取消）也能接着聊：发出去 = 续派一条接着它的对话式子任务（同一个 Agent 会话、同一个工作区）。
+  // 还在跑的时候输入框照样显示、但不能发，提示结束后再接着聊（需要登录、验证码时在看板的浏览器里接管）。
+  const batchTaskStatus = batch ? conv?.batchTask?.status ?? job?.tasks?.find((t) => t.id === (taskId ?? conv?.task?.id))?.status ?? null : null;
+  const batchSettled = batch && !chat && !!batchTaskStatus && SETTLED_TASK.has(batchTaskStatus) && !!store.client.continueTask;
+  const readOnly = !!readOnlyProp || !cfg.composer.show || (batch && !chat && !batchSettled);
+  // 一次性任务的子任务没结束、不能发时，输入框也露出来（禁用 + 说明），别让人以为没有输入框。
+  const showComposer = !readOnly || (batch && !readOnlyProp && cfg.composer.show);
   // 这个对话对应的子任务：指定了就是它，否则对话任务的第一个（「新开」时借用第一个的智能体显示）；
   // 一次性任务没指定时是实时流挑的那个（最近一个派发过的）。
   const shownTaskId = taskId ?? (batch ? conv?.task?.id : undefined);
@@ -180,9 +193,11 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
   const agent = task?.agent ?? conv?.turns[conv.turns.length - 1]?.agent ?? null;
   const agentText = labelOf(agent);
   const jobStatus = conv?.job?.status ?? job?.status ?? null;
-  const jobEnded = !!jobStatus && TERMINAL_JOB.has(jobStatus);
+  // 对话式子任务没有「结束」：大任务结束了，再发一条会重新打开它。
+  // 普通子任务结束后能接着聊的（batchSettled）同理：大任务结束不挡输入框。
+  const jobEnded = !chat && !batchSettled && !!jobStatus && TERMINAL_JOB.has(jobStatus);
   // 只关掉了这一个对话（对话任务还开着）：按「这个对话已结束」显示，不能再发消息。
-  const convClosed = !jobEnded && !!(conv?.task?.closed ?? info?.closed);
+  const convClosed = !jobEnded && !batchSettled && !!(conv?.task?.closed ?? info?.closed);
   const status = convClosed ? "succeeded" : jobStatus;
   const closedReason = convClosed ? "conversation_closed" : conv?.job?.closed_reason ?? job?.conversation?.closed_reason ?? null;
   const ended = jobEnded || convClosed;
@@ -194,7 +209,8 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
   const jobTitle = job?.title ?? conv?.job?.title;
   // 对话任务里有几个对话时，标题是「对话任务 / 这个对话」。
   const manyConvs = (batch ? job?.tasks?.length ?? 0 : job?.conversation?.conversations?.length ?? 0) > 1;
-  const convName = conv?.task?.title ?? info?.title ?? task?.title;
+  // 对话式子任务：流里的是这个对话最新的那条消息，名称取打开的那个子任务。
+  const convName = chat ? task?.title ?? conv?.task?.title : conv?.task?.title ?? info?.title ?? task?.title;
   const convTitle = isNew ? `${jobTitle ? `${jobTitle} / ` : ""}新对话`
     : (taskId || batch) && manyConvs && convName && convName !== jobTitle ? `${jobTitle ?? "对话"} / ${convName}`
       : jobTitle ?? (key ? "对话" : "新对话");
@@ -213,13 +229,13 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
 
   const { dotCls, statusText } = useMemo((): { dotCls: DotCls; statusText: string } => {
     if (!key || isNew) return { dotCls: "r", statusText: "未开始" };
-    if (batch) return batchStatusView(batchStatus, jobStatus);
+    if (batch && !chat) return batchStatusView(batchStatus, jobStatus);
     if (ended) return { dotCls: status === "succeeded" ? "g" : "x", statusText: REASON_TEXT[closedReason ?? ""] ?? (status === "succeeded" ? "已结束" : status === "cancelled" ? "已取消" : "已失败") };
     if (awaiting) return { dotCls: "a", statusText: "需要你处理" };
     if (running) return { dotCls: "a", statusText: "运行中" };
     if (status === "queued") return { dotCls: "a", statusText: "等待执行节点" };
     return { dotCls: "a", statusText: "进行中" };
-  }, [key, isNew, batch, batchStatus, jobStatus, ended, status, closedReason, awaiting, running]);
+  }, [key, isNew, batch, chat, batchStatus, jobStatus, ended, status, closedReason, awaiting, running]);
 
   // ── 处理器（引用稳定，MessageView 的 memo 才有效） ──
   // 输入框之外的操作（回答提问、撤回排队、结束对话、停止）失败时在顶部提示，不静默吞掉。
@@ -235,16 +251,38 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
       throw error;
     }
   }, []);
-  const latest = useRef({ key, messages, conv });
-  latest.current = { key, messages, conv };
+  // 操作这次运行（回答提问、填浏览器输入卡片、交还浏览器）落在哪个子任务上：一次性任务没指定子任务时是正在看的那个
+  // （几个子任务同时跑时，卡片属于它，不是中枢缺省的那个）。和能不能发消息无关。
+  const runKey = batch && !taskId && conv?.task?.id && jobId ? convKey(jobId, conv.task.id) : key;
+  const latest = useRef({ key, messages, conv, runKey });
+  latest.current = { key, messages, conv, runKey };
   // 本组件的新建参数随每次发送带上：放进共享 Provider 时也用自己的，不依赖仓库是谁建的。
   const sendOpts = useRef({ newConversation, createConversation, businessIdFor, select: !controlled });
   sendOpts.current = { newConversation, createConversation, businessIdFor, select: !controlled };
   const send = useCallback(async (text: string) => {
-    const id = latest.current.key;
-    const target = await store.send(id ?? null, text, sendOpts.current);
+    // 一次性任务：发给正在看的那个子任务（接着它聊）。
+    const id = latest.current.conv?.batch ? latest.current.runKey : latest.current.key;
+    // 看板里引用到这个对话的东西：合成一个「看板上下文」块跟着这条消息发出去；发失败就放回去。
+    // 看板上正在看的文件缺省也带上一次（已经明确引用了的不重复）。
+    const refKey = latest.current.key;
+    const refs = refKey ? store.takeRefs(refKey) : [];
+    const viewing = refKey ? store.takeViewing(refKey) : null;
+    const lines = [...(viewing && !refs.some((r) => r.id === viewing.id) ? [viewing.text] : []), ...refs.map((r) => r.text)];
+    const full = lines.length ? `${text}\n\n${serializeBlock(boardContextBlock(lines))}` : text;
+    let target: string;
+    try {
+      target = await store.send(id ?? null, full, sendOpts.current);
+    } catch (error) {
+      if (refKey) { store.restoreRefs(refKey, refs); store.restoreViewing(refKey, viewing); }
+      throw error;
+    }
     if (target !== id) go(target);
   }, [store, go]);
+  const refs = useCliState((s) => (key ? s.refs[key] : undefined));
+  const viewingState = useCliState((s) => (key ? s.viewing[key] : undefined));
+  const viewing = viewingState && !viewingState.off && !refs?.some((r) => r.id === viewingState.ref.id) ? viewingState.ref : null;
+  // 业务方补充的背景（store.appendContext）：随下一条消息带上，输入框上方显示出来，让用户知道会带上什么。
+  const contextItems = useCliState((s) => s.context[key ?? ""]);
   // AI 把浏览器交给用户（实时新来的「🖐 …」行）：同一 Provider 里有看板在看这个对话，就把看板切到浏览器（收起的会请宿主展开）。
   // 打开对话时已有的交接行不算（先记下已有的再开始比较）；没有看板时不弹窗打扰，行里有「查看浏览器」按钮。
   const handoffSeen = useRef<{ key: string | null; ids: Set<string> | null }>({ key: null, ids: null });
@@ -271,24 +309,26 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
   }, [popup]);
   const handlers = useMemo<MessageHandlers>(() => ({
     // 与 Operator 的 answerQuestion 一致：先把卡片标成已答，再把回答发出去（center 已结束提问那一轮，回答就是下一条消息）。
-    onAnswer: readOnly ? undefined : async (askId: string, questions: AskQuestion[], answers: AskAnswers) => {
+    onAnswer: readOnlyProp || (readOnly && !(batch && store.client.answerAsk)) ? undefined : async (askId: string, questions: AskQuestion[], answers: AskAnswers) => {
       const id = latest.current.key;
       if (!id) return;
+      // 一次性任务：提问时回合开着等，答案直接交给节点；不能改发消息。
+      if (batch && !chat) { await report(store.answerAsk(latest.current.runKey ?? id, askId, questions, answers, { fallback: false }).then(() => undefined), "回答没有送到"); return; }
       const sent = askId
         ? store.answerAsk(id, askId, questions, answers, sendOpts.current).then((target) => { if (target !== id) go(target); })
         : send(formatAnswersText(questions, answers));
       await report(sent, "回答没有发出去");
     },
-    onCancelQueued: readOnly ? undefined : (m: Msg) => { const id = latest.current.key; if (id && m.turnId) void report(store.cancelTurn(id, m.turnId), "撤回失败").catch(() => undefined); },
+    onCancelQueued: readOnly || batch ? undefined : (m: Msg) => { const id = latest.current.key; if (id && m.turnId) void report(store.cancelTurn(id, m.turnId), "撤回失败").catch(() => undefined); },
     // 后端能直接处理的浏览器动作（Operator 后端）才给；center 不提供，卡片按 Operator「没有浏览器能力」时的样子显示。
-    onInput: readOnly || !store.client.submitInput ? undefined : async (inputId: string, values: string[]) => {
-      const id = latest.current.key;
+    onInput: readOnlyProp || !store.client.submitInput ? undefined : async (inputId: string, values: string[]) => {
+      const id = latest.current.runKey;
       if (!id) return "对话还没开始";
       try { return await store.client.submitInput!(id, inputId, values); } catch (error) { return error instanceof Error ? error.message : String(error); }
     },
     // 交还浏览器：后端自己的 handback（Operator 后端），没有就走看板接口（center 转发到节点）。
-    onHandback: readOnly || !(store.client.handback || store.client.board) ? undefined : async () => {
-      const id = latest.current.key;
+    onHandback: readOnlyProp || !(store.client.handback || store.client.board) ? undefined : async () => {
+      const id = latest.current.runKey;
       if (!id) return "对话还没开始";
       try {
         if (store.client.handback) return await store.client.handback(id);
@@ -307,7 +347,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
       const at = list.findIndex((m) => m.id === msgId);
       for (let j = (at === -1 ? list.length : at) - 1; j >= 0; j--) if (list[j].role === "user") { void report(send(list[j].content), "重试没有发出去").catch(() => undefined); return; }
     },
-  }), [readOnly, send, store, go, report, fileOpen]);
+  }), [readOnly, readOnlyProp, batch, chat, send, store, go, report, fileOpen]);
   const stop = useCallback(async () => {
     const { key: id, conv: c } = latest.current;
     const turn = c ? runningTurn(c) : null;
@@ -334,7 +374,14 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
   const [atBottom, setAtBottom] = useState(true);
   const committed = useMemo(() => messages.filter((m) => m.role !== "queued"), [messages]);
   const queued = useMemo(() => messages.filter((m) => m.role === "queued"), [messages]);
-  const items = useMemo(() => buildTranscriptItems(committed), [committed]);
+  // 节点转录比手里更早、还没取的条数（实时流只给最新一段，往上翻时分页取，和 Operator 一样）。
+  const older = conv?.older ?? 0;
+  const [loadingOlder, setLoadingOlder] = useState(false);
+  const olderRef = useRef(older); olderRef.current = older;
+  const keyRef2 = useRef(key); keyRef2.current = key;
+  const items = useMemo(() => buildTranscriptItems(committed, older > 0), [committed, older]);
+  // 展开了的「续等」折叠行（按折叠行的 key）。
+  const [openFolds, setOpenFolds] = useState<Set<string>>(() => new Set());
   const [win, setWin] = useState<{ start: string | null; end: string | null }>({ start: null, end: null });
   const { startIdx, endIdx } = useMemo(() => {
     const find = (key: string | null) => (key ? items.findIndex((it) => it.key === key) : -1);
@@ -369,10 +416,17 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
   }, []);
   const revealEarlier = useCallback(() => {
     const { startIdx: s, endIdx: e } = rangeRef.current;
-    if (s <= 0) return;
+    if (s <= 0) {
+      // 手里的都显示了，节点上还有更早的：取一页接在前面，再往上展开（窗口按原来的那一行定位，不跳）。
+      const k = keyRef2.current;
+      if (!k || olderRef.current <= 0) return;
+      setLoadingOlder(true);
+      void store.loadOlder(k).then((ok) => { if (ok) requestAnimationFrame(() => revealRef.current.earlier()); }).finally(() => setLoadingOlder(false));
+      return;
+    }
     const ns = Math.max(0, s - RENDER_STEP);
     setRange(ns, Math.min(e, ns + RENDER_MAX - 1), measure());
-  }, [measure, setRange]);
+  }, [measure, setRange, store]);
   const revealLater = useCallback(() => {
     const its = itemsRef.current;
     const { startIdx: s, endIdx: e } = rangeRef.current;
@@ -400,7 +454,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
 
   const topSentinelRef = useRef<HTMLDivElement>(null);
   const bottomSentinelRef = useRef<HTMLDivElement>(null);
-  const hasAbove = hiddenAbove > 0;
+  const hasAbove = hiddenAbove > 0 || older > 0;
   const hasBelow = hiddenBelow > 0;
   useEffect(() => {
     const root = scrollRef.current;
@@ -479,7 +533,13 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
     fileUpload: cfg.composer.fileUpload, fileButtonText: cfg.composer.fileButtonText, queue: cfg.composer.queue,
   }), [cfg]);
   const composerDisabled = !!readOnly || finalEnd || conv?.stream === "error";
-  const disabledHint = readOnly ? "只读" : finalEnd ? "对话已结束，不能再发消息" : conv?.streamError ?? undefined;
+  const disabledHint = readOnly
+    ? batch && !readOnlyProp && cfg.composer.show
+      ? (batchTaskStatus && SETTLED_TASK.has(batchTaskStatus) ? "只读（当前中枢不支持接着子任务聊）"
+        : batchTaskStatus === "blocked" || batchTaskStatus === "queued" ? "子任务还没开始，开始并结束后可以接着它聊"
+        : "子任务运行中，结束后可以接着它继续聊；需要登录等操作请在右侧浏览器里接管")
+      : "只读"
+    : finalEnd ? "对话已结束，不能再发消息" : conv?.streamError ?? undefined;
 
   const fileUrlRef = useRef(fileUrl);
   fileUrlRef.current = fileUrl;
@@ -537,7 +597,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
               <StatusDot cls={dotCls} running={running} awaiting={awaiting} title={statusText} />
               <span className="cv">{statusText}</span>
             </span>}
-            {h.close && key && !isNew && allowClose && !readOnly && !ended && (
+            {h.close && key && !isNew && allowClose && !readOnly && !ended && !batch && (
               <button className="btn btn-line btn-sm" onClick={() => setClosing("confirm")} disabled={closing === "busy"} title={taskId ? "只结束这个对话：之后它不再接收消息，正在跑的一轮会被中止；同一任务里的其他对话不受影响" : "结束这个对话：之后不再接收消息，正在跑的一轮会被中止"}>{Icon.stop()} 结束对话</button>
             )}
           </div>
@@ -561,7 +621,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
               {(!key || isNew) && cfg.empty.show && (
                 <div className="hero cli-hero">
                   <div className="h-ic">{Icon.bolt()}</div>
-                  <div className="h-status"><StatusDot cls="r" /> 新对话 · 尚未开始</div>
+                  {cfg.transcript.status && <div className="h-status"><StatusDot cls="r" /> 新对话 · 尚未开始</div>}
                   <h2>{cfg.empty.title}</h2>
                   {isNew && <p className="h-desc">在「{jobTitle ?? "这个任务"}」里新开一个对话：和任务里的其他对话共用同一个工作区（能看到彼此产出的文件），对话内容各自独立。</p>}
                   {cfg.empty.description && <p className="h-desc">{cfg.empty.description}</p>}
@@ -588,7 +648,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
               )}
               {hasAbove && (
                 <div ref={topSentinelRef} className="load-older">
-                  <button className="btn btn-ghost btn-sm" onClick={revealEarlier}>加载更早的消息（还有 {hiddenAbove} 条）</button>
+                  <button className="btn btn-ghost btn-sm" onClick={revealEarlier} disabled={loadingOlder}>{loadingOlder ? "正在加载更早的消息…" : `加载更早的消息（还有 ${hiddenAbove + older} 条）`}</button>
                 </div>
               )}
               {shown.map((it) =>
@@ -596,6 +656,15 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
                   cfg.transcript.sessionLabel ? <div key={it.key} data-tkey={it.key} className="session-label"><span className="ln" />第 {it.n} 次会话{it.current ? " · 当前" : ""}<span className="ln" /></div> : null
                 ) : it.kind === "break" ? (
                   <div key={it.key} data-tkey={it.key}><SessionBreak summary={it.summary} /></div>
+                ) : it.kind === "fold" ? (
+                  <div key={it.key} data-tkey={it.key} data-msg="">
+                    <button className="cli-wait-fold" onClick={() => setOpenFolds((o) => { const n = new Set(o); if (n.has(it.key)) n.delete(it.key); else n.add(it.key); return n; })} aria-expanded={openFolds.has(it.key)}>
+                      <span className="cli-wait-ic">⏳</span>
+                      <span>等你在浏览器里操作 · AI 已续等 {it.waits} 次</span>
+                      <span className="cli-wait-more">{openFolds.has(it.key) ? "收起" : "展开"}</span>
+                    </button>
+                    {openFolds.has(it.key) && it.msgs.map((m) => <MessageView key={m.id} m={m} initial={false} hideWho running={running} agent={agent} agentLabel={agentText} handlers={handlers} view={view} />)}
+                  </div>
                 ) : (
                   <div key={it.key} data-tkey={it.key} data-msg="">
                     <MessageView m={it.m} initial={it.initial} hideWho={it.hideWho} running={running} agent={agent} agentLabel={agentText} handlers={handlers} view={view} />
@@ -610,7 +679,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
               )}
               {cfg.transcript.runningIndicator && running && !awaitingAnswer && !hasBelow && <RunningIndicator agent={agent} agentName={cfg.labels.agent} startedAt={turnStartedAt} lastActivityRef={lastActivityRef} />}
               {!hasBelow && queued.map((m) => <MessageView key={m.id} m={m} initial={false} hideWho={false} handlers={handlers} view={view} />)}
-              {ended && (
+              {ended && cfg.transcript.status && (
                 <div className="session-label"><span className="ln" />{batch ? statusText : <>{REASON_TEXT[closedReason ?? ""] ?? "对话已结束"}{!finalEnd ? " · 再发消息会开一个新对话接着聊" : ""}</>}<span className="ln" /></div>
               )}
               {continuedBy && (
@@ -624,7 +693,35 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
             {!atBottom && <button className="msg-nav-btn" onClick={() => scrollToBottom()} title="跳到最新" aria-label="跳到最新">{Icon.toBottom()}</button>}
           </div>}
         </div>
-        {!readOnly && (
+        {showComposer && !!contextItems?.length && (
+          <div className="cli-refs cli-ctxs" aria-label="补充背景，下一条消息会带上">
+            <span className="cli-refs-t">{Icon.flag()} 补充背景</span>
+            {contextItems.map((c) => (
+              <span key={c.id} className="cli-ref ctx" title={`${c.text.slice(0, 500)}${c.text.length > 500 ? "…" : ""}\n（下一条消息会带上）`}>
+                <span className="cli-ref-l">{c.title || c.text.replace(/\s+/g, " ").slice(0, 20)}</span>
+              </span>
+            ))}
+          </div>
+        )}
+        {showComposer && (!!refs?.length || !!viewing) && (
+          <div className="cli-refs" aria-label="引用自看板，下一条消息会带上">
+            <span className="cli-refs-t">{Icon.board()} 引用自看板</span>
+            {viewing && (
+              <span className="cli-ref auto" title={`${viewing.text}\n（看板上正在看，下一条消息缺省带上；点 × 这次不带）`}>
+                <span className="cli-ref-k">正在看</span>
+                <span className="cli-ref-l">{viewing.label}</span>
+                <button className="cli-ref-x" onClick={() => key && store.dismissViewing(key)} title="这次不带上" aria-label={`不带上 ${viewing.label}`}>{Icon.x()}</button>
+              </span>
+            )}
+            {(refs ?? []).map((r) => (
+              <span key={r.id} className={`cli-ref ${r.kind === "selection" ? "sel" : ""}`} title={r.text}>
+                <span className="cli-ref-l">{r.label}</span>
+                <button className="cli-ref-x" onClick={() => key && store.removeRef(key, r.id)} title="不带上" aria-label={`不带上 ${r.label}`}>{Icon.x()}</button>
+              </span>
+            ))}
+          </div>
+        )}
+        {showComposer && (
           <Composer
             key={key ?? "new"}
             draft={key ?? `new:${instanceId}`}

package/src/core/blocks.ts

@@ -16,7 +16,26 @@ export interface TextBlock {
   /** 显示名：文件名，粘贴的文字为「粘贴的文本」。 */
   name: string;
   text: string;
-  kind: "file" | "paste";
+  kind: "file" | "paste" | "context" | "background";
+}
+
+/** 看板引用合成的块的名字（转录里按它认出来，显示成「看板上下文」卡片）。 */
+export const BOARD_CONTEXT_NAME = "看板上下文";
+
+/** 看板引用 → 发给智能体的块。 */
+export function boardContextBlock(lines: string[]): TextBlock {
+  return { name: BOARD_CONTEXT_NAME, kind: "context", text: ["用户在右侧看板里引用了下面这些，供这条消息参考：", ...lines.map((l) => `- ${l}`)].join("\n") };
+}
+
+/** 补充背景合成的块的名字（转录里显示成「补充背景」卡片）。 */
+export const BACKGROUND_NAME = "补充背景";
+
+/** 补充背景（store.appendContext）→ 发给智能体的块。每条有标题时写成「【标题】」。 */
+export function backgroundBlock(items: Array<{ title?: string; text: string }>): TextBlock {
+  // 内容里碰巧有附件分隔行时错开一个空格，免得把块提前截断。
+  const safe = (t: string) => t.replace(/^(----- 附件)/gm, " $1");
+  const body = items.map((i) => (i.title ? `【${i.title}】\n${safe(i.text)}` : safe(i.text))).join("\n\n");
+  return { name: BACKGROUND_NAME, kind: "background", text: `以下是补充的项目背景信息，请在这次及之后的工作中一并参考：\n\n${body}` };
 }
 
 /** 支持的文件：只有 TXT、Markdown、Word（.docx）。 */
@@ -63,7 +82,7 @@ export function splitMessage(content: string): MessagePart[] {
     if (!open || end === -1) { text.push(lines[i]); continue; }
     flush();
     const name = open[1];
-    parts.push({ kind: "block", block: { name, text: lines.slice(i + 1, end).join("\n"), kind: name === PASTE_NAME ? "paste" : "file" } });
+    parts.push({ kind: "block", block: { name, text: lines.slice(i + 1, end).join("\n"), kind: name === PASTE_NAME ? "paste" : name === BOARD_CONTEXT_NAME ? "context" : name === BACKGROUND_NAME ? "background" : "file" } });
     i = end;
   }
   flush();