@steerable/agent-shell-web 0.6.36 → 0.6.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell-web",
-  "version": "0.6.36",
+  "version": "0.6.38",
   "type": "module",
   "description": "Steerable framework — product-neutral renderer SPA source for @steerable/agent-shell (React + Vite). Consumed by product web entry points via the `@/` alias (anchored at this package's src/) and the createProductViteConfig factory. Published as a source package (src/), plus the compiled vite.base config factory (vite.base.js + .d.ts) for Node-side config loading.",
   "license": "Apache-2.0",
@@ -43,8 +43,8 @@
     "react-router-dom": "^6.30.0",
     "rehype-raw": "^7.0.0",
     "remark-gfm": "^4.0.1",
-    "@steerable/agent-protocol": "0.6.36",
-    "@steerable/agent-ui": "0.6.36"
+    "@steerable/agent-protocol": "0.6.38",
+    "@steerable/agent-ui": "0.6.38"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.0",
@@ -57,7 +57,7 @@
     "typescript": "^5.8.3",
     "vite": "^5.4.21",
     "vitest": "^3.2.4",
-    "@steerable/pack-sdk": "0.6.36"
+    "@steerable/pack-sdk": "0.6.38"
   },
   "scripts": {
     "gen": "echo agent-shell-web",

package/src/components/AgentSidebar.tsx

@@ -115,7 +115,6 @@ import {
   type LocalProject,
 } from "@/lib/local-api";
 import type { UseChatsAndAgentsResult } from "@/hooks/useChatsAndAgents";
-import type { PackChatSlotContribution } from "@/packs/registry";
 import type { RightPanelState } from "@/layouts/AgentLayout";
 import { BrandLockup } from "@/components/BrandLockup";
 import { CreateProjectModal } from "@/components/CreateProjectModal";
@@ -272,8 +271,6 @@ interface AgentSidebarProps {
   rightPanel: RightPanelState;
   /** 切换右侧栏面板显隐——面板不是路由也不是独立窗口，只是布局里的一栏。 */
   onToggleRightPanel: (kind: string) => void;
-  /** 包注册的聊天页槽位（分段控件里每个槽位一个按钮）；空 = 只有终端。 */
-  chatSlots: readonly PackChatSlotContribution[];
   /** 收起侧边栏（AgentLayout 换成窄 rail，展开按钮在 rail 上）。 */
   onCollapse: () => void;
 }
@@ -282,7 +279,6 @@ export function AgentSidebar({
   data,
   rightPanel,
   onToggleRightPanel,
-  chatSlots,
   onCollapse,
 }: AgentSidebarProps) {
   const navigate = useNavigate();
@@ -1054,70 +1050,26 @@ export function AgentSidebar({
 
       {/* ───── Footer: 右侧面板切换（终端 | 包槽位）+ 设置 ───── */}
       <div className="flex-shrink-0 border-t border-agent-border/40 px-2.5 py-1.5">
-        {chatSlots.length === 0 ? (
-          showTerminalChrome ? (
-          <button
-            type="button"
-            onClick={() => onToggleRightPanel("terminal")}
-            className={[
-              "flex h-7 w-full items-center gap-1.5 rounded-full px-2.5 text-xs transition-colors",
-              rightPanel === "terminal"
-                ? "bg-agent-foreground/10 font-medium text-agent-foreground"
-                : "text-agent-muted-foreground hover:bg-agent-foreground/5 hover:text-foreground",
-            ].join(" ")}
-            title={`${rightPanel === "terminal" ? "关闭" : "打开"}终端面板 (${isMac ? "⌘T" : "Ctrl+T"})`}
-            data-testid="sidebar-terminal"
-          >
-            <LuTerminal className="h-3.5 w-3.5" />
-            <span>终端</span>
-            <span className="ml-auto text-[10px] text-agent-muted-foreground/70">
-              {isMac ? "⌘T" : "Ctrl+T"}
-            </span>
-          </button>
-          ) : null
-        ) : (
-          <div
-            role="group"
-            aria-label="右侧面板切换"
-            className="flex h-7 w-full items-center gap-0.5 rounded-full bg-agent-foreground/5 p-0.5"
-          >
-            {showTerminalChrome ? (
-            <button
-              type="button"
-              onClick={() => onToggleRightPanel("terminal")}
-              className={[
-                "flex h-7 flex-1 items-center justify-center gap-1.5 rounded-full text-xs font-medium transition-colors",
-                rightPanel === "terminal"
-                  ? "bg-agent-foreground/10 text-agent-foreground"
-                  : "text-agent-muted-foreground hover:bg-agent-foreground/5 hover:text-agent-foreground",
-              ].join(" ")}
-              title={`${rightPanel === "terminal" ? "关闭" : "打开"}终端面板`}
-              data-testid="sidebar-terminal"
-            >
-              <LuTerminal className="h-3.5 w-3.5" />
-              <span>终端</span>
-            </button>
-            ) : null}
-            {chatSlots.map((slot) => (
-              <button
-                key={slot.slotId}
-                type="button"
-                onClick={() => onToggleRightPanel(slot.slotId)}
-                className={[
-                  "flex h-7 flex-1 items-center justify-center gap-1.5 rounded-full text-xs font-medium transition-colors",
-                  rightPanel === slot.slotId
-                    ? "bg-agent-foreground/10 text-agent-foreground"
-                    : "text-agent-muted-foreground hover:bg-agent-foreground/5 hover:text-agent-foreground",
-                ].join(" ")}
-                title={`${rightPanel === slot.slotId ? "关闭" : "打开"}${slot.title}`}
-                data-testid={`sidebar-slot-${slot.slotId}`}
-              >
-                <slot.Icon className="h-3.5 w-3.5" />
-                <span>{slot.title}</span>
-              </button>
-            ))}
-          </div>
-        )}
+        {showTerminalChrome ? (
+        <button
+          type="button"
+          onClick={() => onToggleRightPanel("terminal")}
+          className={[
+            "flex h-7 w-full items-center gap-1.5 rounded-full px-2.5 text-xs transition-colors",
+            rightPanel === "terminal"
+              ? "bg-agent-foreground/10 font-medium text-agent-foreground"
+              : "text-agent-muted-foreground hover:bg-agent-foreground/5 hover:text-foreground",
+          ].join(" ")}
+          title={`${rightPanel === "terminal" ? "关闭" : "打开"}终端面板 (${isMac ? "⌘T" : "Ctrl+T"})`}
+          data-testid="sidebar-terminal"
+        >
+          <LuTerminal className="h-3.5 w-3.5" />
+          <span>终端</span>
+          <span className="ml-auto text-[10px] text-agent-muted-foreground/70">
+            {isMac ? "⌘T" : "Ctrl+T"}
+          </span>
+        </button>
+        ) : null}
         {hasGeneralSettingsChrome() && (
         <button
           type="button"

package/src/components/ChatHeader.tsx

@@ -10,6 +10,7 @@ import {
 import { SessionTreeModal } from './chat/SessionTreeModal';
 import { TaskPanelModal } from './chat/TaskPanelModal';
 import { actionableTasks, summarizeTasks, type ChatTaskSummary } from './chat/useChatTasks';
+import type { PackChatSlotContribution } from '@/packs/registry';
 
 interface ChatHeaderProps {
   chat: LocalChat | null;
@@ -23,6 +24,12 @@ interface ChatHeaderProps {
   onInspectTask?: (task: { id: string; chatId: string; title: string }) => void;
   /** 本对话的后台任务（AgentPage 的 `useChatTasks` 单一订阅源）。 */
   tasks?: LocalTask[];
+  /** 包注册的聊天页槽位（如「文档预览」）：入口放在本标题栏，按会话独立开关。 */
+  chatSlots?: readonly PackChatSlotContribution[];
+  /** 当前会话打开的右侧栏位（null = 都关着）。 */
+  rightPanel?: string | null;
+  /** 点击槽位入口：点已打开的关闭，点另一个直接切换。 */
+  onToggleChatSlot?: (slotId: string) => void;
 }
 
 /**
@@ -40,6 +47,9 @@ export function ChatHeader({
   onBranchSwitched,
   onInspectTask,
   tasks = [],
+  chatSlots = [],
+  rightPanel = null,
+  onToggleChatSlot,
 }: ChatHeaderProps) {
   const [branchMenuOpen, setBranchMenuOpen] = useState(false);
   const [treeModalOpen, setTreeModalOpen] = useState(false);
@@ -233,6 +243,30 @@ export function ChatHeader({
           {taskBadge && <span className="text-xs">{taskBadge.count}</span>}
         </button>
       )}
+      {chat &&
+        chatSlots.map((slot) => {
+          const open = rightPanel === slot.slotId;
+          return (
+            <button
+              key={slot.slotId}
+              type="button"
+              onClick={() => onToggleChatSlot?.(slot.slotId)}
+              className={`flex h-7 shrink-0 items-center gap-1 rounded-full px-2 text-xs font-medium transition-colors ${
+                open
+                  ? 'bg-agent-foreground/10 text-agent-foreground'
+                  : 'text-agent-muted-foreground hover:bg-agent-foreground/5 hover:text-agent-foreground'
+              }`}
+              title={`${open ? '关闭' : '打开'}${slot.title}`}
+              aria-label={slot.title}
+              aria-pressed={open}
+              data-action={`chat-slot-${slot.slotId}`}
+              data-testid={`header-slot-${slot.slotId}`}
+            >
+              <slot.Icon className="h-3.5 w-3.5" />
+              {slot.title}
+            </button>
+          );
+        })}
       {chat && taskPanelOpen && (
         <TaskPanelModal
           chatId={chat.id}

package/src/components/chat/LocalChatPanel.tsx

@@ -21,7 +21,9 @@ import type { LlmSpeedSnapshot } from './process-status';
 import { SessionTodoList } from './SessionTodoList';
 import { resolveLatestSessionTodos } from './todo-list-model';
 import {
-  composeAttachmentUserContent,
+  appendAttachmentRefs,
+  collectImageAttachments,
+  formatAttachmentFailures,
   saveChatAttachments,
   type AttachmentFile,
 } from '@/lib/attachments';
@@ -214,6 +216,7 @@ export function LocalChatPanel({
 }: LocalChatPanelProps) {
   const [inputValue, setInputValue] = useState('');
   const [files, setFiles] = useState<AttachmentFile[]>([]);
+  const [attachmentError, setAttachmentError] = useState<string | null>(null);
   const [mentionReferences, setMentionReferences] = useState<MentionReference[]>([]);
   const inputRef = useRef<ChatInputHandle>(null);
 
@@ -231,12 +234,32 @@ export function LocalChatPanel({
     if (!trimmed && files.length === 0) return;
 
     // 把上传的文件持久化到会话空间：成功项用落盘路径（稳定、可被 agent
-    // 读回），失败项退回原源路径。落地页（无 chatId）由调用方创建会话后
-    // 自行持久化，这里 chatId 为空时原样用源路径。
-    const resolvedFiles =
-      chatId && files.length > 0 ? await saveChatAttachments(chatId, files) : files;
-    const assembled = composeAttachmentUserContent(trimmed, resolvedFiles);
-    trimmed = assembled.content;
+    // 读回），失败项若在 Electron 下有源路径则退回源路径；浏览器模式下没有
+    // 任何可用路径的失败项会被剔除并上报，绝不把空路径写进正文。
+    // 没有文件就没有可持久化的东西，直接跳过 saveChatAttachments：它的 await
+    // 会让「无附件提交」多出一个微任务，打乱调用方基于 streaming 上升/下降沿的
+    // 判定（plan 模式操作条依赖该沿）。语义与 saveChatAttachments(chatId, [])
+    // 完全一致（后者原样返回空列表、无失败）。
+    const { files: resolvedFiles, failures } =
+      chatId && files.length > 0
+        ? await saveChatAttachments(chatId, files)
+        : { files, failures: [] };
+
+    if (failures.length > 0) {
+      // 本次消息至少保留可用的文件继续发送，但失败项必须让用户看到。
+      setAttachmentError(formatAttachmentFailures(failures));
+    } else {
+      setAttachmentError(null);
+    }
+
+    // Append file references to the user message content
+    const content = appendAttachmentRefs(trimmed, resolvedFiles);
+    if (resolvedFiles.length === 0 && !trimmed) {
+      // 唯一的文件全是失败项、又没有正文 —— 没有可发送的内容，保留输入框
+      // （含失败文件）让用户重试或移除。
+      return;
+    }
+    trimmed = content;
 
     const mentionedAgentIds = mentionReferences
       .filter((ref) => ref.type === 'agent')
@@ -247,13 +270,14 @@ export function LocalChatPanel({
     // W6-3: image attachments ride as metadata so the main process reads the
     // bytes into base64 ImageParts; the text path refs above stay so the
     // persisted record reflects that an image was attached.
+    const imageAttachments = collectImageAttachments(resolvedFiles);
     const metadata = {
       ...(mode === 'plan' ? { mode: 'plan' as const } : {}),
       ...(execPolicy === 'full' ? { execPolicy: 'full' as const } : {}),
       ...(selectedAgentId ? { agentId: selectedAgentId } : {}),
       ...(mentionedAgentIds.length > 0 ? { mentionedAgentIds } : {}),
       ...(referencedChatIds.length > 0 ? { referencedChatIds } : {}),
-      ...(assembled.images.length > 0 ? { images: assembled.images } : {}),
+      ...(imageAttachments.length > 0 ? { images: imageAttachments } : {}),
     };
 
     // Snapshot what we're about to clear so a failed submit can restore it —
@@ -261,8 +285,10 @@ export function LocalChatPanel({
     // (and any attachments/mentions) whenever the submit rejected.
     const submittedFiles = files;
     const submittedMentions = mentionReferences;
+    // 失败项留在输入框里，用户可以直接重试 / 移除；成功项随消息发出后清掉。
+    const failedFiles = failures.map((f) => f.file);
     setInputValue('');
-    setFiles([]);
+    setFiles(failedFiles);
     setMentionReferences([]);
     try {
       await onSubmit({
@@ -329,40 +355,55 @@ export function LocalChatPanel({
   }, [showEmptyHero]);
 
   const chatInputNode = (
-    <ChatInput
-      ref={inputRef}
-      value={inputValue}
-      onChange={setInputValue}
-      onSubmit={handleSubmit}
-      onCancel={onCancel}
-      onSteer={onSteer}
-      onFollowUp={onFollowUp}
-      pendingFollowUps={pendingFollowUps}
-      onRemoveFollowUp={onRemoveFollowUp}
-      isStreaming={isStreaming}
-      disabled={disabled}
-      placeholder={
-        mode === 'plan'
-          ? '描述你的目标，Agent 将先制定计划…'
-          : inputPlaceholder
-      }
-      currentAgent={currentAgent}
-      agents={agents}
-      chats={chats}
-      selectedAgentId={selectedAgentId}
-      onSelectAgent={onSelectAgent}
-      onOpenSettings={onOpenSettings}
-      toolbarExtras={inputToolbarExtras}
-      leadingChrome={inputLeadingChrome}
-      trailingChrome={sessionTodos ? <SessionTodoList todos={sessionTodos} /> : undefined}
-      mode={mode}
-      onModeChange={onModeChange}
-      execPolicy={execPolicy}
-      onExecPolicyChange={onExecPolicyChange}
-      files={files}
-      onFilesChange={setFiles}
-      onMentionReferencesChange={setMentionReferences}
-    />
+    <>
+      {attachmentError && (
+        <p
+          className="mx-3 mb-1 text-xs text-agent-destructive"
+          role="alert"
+          data-testid="attachment-error"
+        >
+          {attachmentError}
+        </p>
+      )}
+      <ChatInput
+        ref={inputRef}
+        value={inputValue}
+        onChange={setInputValue}
+        onSubmit={handleSubmit}
+        onCancel={onCancel}
+        onSteer={onSteer}
+        onFollowUp={onFollowUp}
+        pendingFollowUps={pendingFollowUps}
+        onRemoveFollowUp={onRemoveFollowUp}
+        isStreaming={isStreaming}
+        disabled={disabled}
+        placeholder={
+          mode === 'plan'
+            ? '描述你的目标，Agent 将先制定计划…'
+            : inputPlaceholder
+        }
+        currentAgent={currentAgent}
+        agents={agents}
+        chats={chats}
+        selectedAgentId={selectedAgentId}
+        onSelectAgent={onSelectAgent}
+        onOpenSettings={onOpenSettings}
+        toolbarExtras={inputToolbarExtras}
+        leadingChrome={inputLeadingChrome}
+        trailingChrome={sessionTodos ? <SessionTodoList todos={sessionTodos} /> : undefined}
+        mode={mode}
+        onModeChange={onModeChange}
+        execPolicy={execPolicy}
+        onExecPolicyChange={onExecPolicyChange}
+        files={files}
+        onFilesChange={(next) => {
+          setFiles(next);
+          // 用户手动增删文件后，上一次提交的失败提示已过期。
+          if (attachmentError) setAttachmentError(null);
+        }}
+        onMentionReferencesChange={setMentionReferences}
+      />
+    </>
   );
 
   return (

package/src/layouts/AgentLayout.tsx

@@ -10,7 +10,7 @@ import { InsightsConsentBanner } from '@/components/settings/InsightsSettingsPan
 import { trackBehavior } from '@/lib/insights';
 import { getElectronBridge, isElectron } from '@/lib/electron-bridge';
 import { deleteChatIfEmpty, pruneEmptyChats } from '@/lib/local-api';
-import { getPackChatSlots } from '@/packs/registry';
+import { getPackChatSlots, type PackChatSlotContribution } from '@/packs/registry';
 import {
   useChatsAndAgents,
   type UseChatsAndAgentsResult,
@@ -75,6 +75,46 @@ const MAX_TERMINAL_WIDTH = 960;
  */
 export type RightPanelState = string | null;
 
+/** 每个会话各自的右侧栏位状态：chatId → RightPanelState（null 不落盘）。 */
+export type RightPanelMap = Record<string, string>;
+
+/**
+ * 解析持久化的「会话 → 右侧栏位」映射。
+ *
+ * 兼容三种历史格式：
+ *   - 新格式：{"<chatId>": "terminal" | "<slotId>"}；
+ *   - 旧格式：整个值就是单个字符串（'' / 'terminal' / slotId）→ 迁到当前会话；
+ *   - 更老：只记录终端是否打开过的布尔 key。
+ * 无效的会话 / 栏位值会被丢弃，避免脏数据把某个会话卡在打不开的面板上。
+ */
+export function parseRightPanelMap(options: {
+  raw: string | null;
+  legacyTerminalOpen: string | null;
+  chatId: string | null;
+  isValidValue: (value: string) => boolean;
+}): RightPanelMap {
+  const { raw, legacyTerminalOpen, chatId, isValidValue } = options;
+  if (raw !== null) {
+    if (raw === '') return {};
+    try {
+      const parsed = JSON.parse(raw) as unknown;
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        const map: RightPanelMap = {};
+        for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+          if (typeof value === 'string' && isValidValue(value)) map[key] = value;
+        }
+        return map;
+      }
+    } catch {
+      // 旧格式：整个 key 就是单个值。
+      if (isValidValue(raw) && chatId) return { [chatId]: raw };
+    }
+    return {};
+  }
+  if (legacyTerminalOpen === '1' && chatId) return { [chatId]: 'terminal' };
+  return {};
+}
+
 /** 从聊天页外把一段内容作为普通用户消息发进当前会话（包槽位的 fallback 通道）。 */
 export type ChatMessageSender = (input: {
   content: string;
@@ -87,6 +127,12 @@ export type AgentOutletContext = UseChatsAndAgentsResult & {
   /** 发送普通用户消息到当前聊天；未注册时返回 false。 */
   sendChatMessage: ChatMessageSender;
   inspectTask: (task: InspectedTask) => void;
+  /** 包槽位（如文档预览）：入口渲染在 chat 标题栏，状态按会话隔离。 */
+  chatSlots: readonly PackChatSlotContribution[];
+  /** 当前会话打开的右侧栏位（null = 都关着）。 */
+  rightPanel: RightPanelState;
+  /** 顶栏入口：点已打开的关闭，点另一个直接切换。 */
+  onToggleChatSlot: (slotId: string) => void;
 };
 
 function AgentLayoutContent() {
@@ -269,48 +315,81 @@ function AgentLayoutContent() {
   // null | 'terminal' | <slotId>。持久化到新 key；老版本只持久化终端打开
   // 状态，首次读取时迁移。
   const packChatSlots = getPackChatSlots();
-  const [rightPanel, setRightPanelState] = useState<RightPanelState>(() => {
+
+  /**
+   * 右侧栏位状态按会话隔离：chatId → null | 'terminal' | <slotId>。
+   *
+   * 以前是单个全局值（localStorage 里存一个字符串），会话 1 打开预览会连带
+   * 影响会话 2。现在存成映射，每个会话独立；老的单值 key 读取时自动迁移到
+   * 当前会话。
+   */
+  const readRightPanelMap = useCallback((): RightPanelMap => {
+    const isValidValue = (value: string): boolean =>
+      value === 'terminal' || packChatSlots.some((s) => s.slotId === value);
     try {
-      const saved = window.localStorage.getItem(RIGHT_PANEL_KEY);
-      if (saved !== null) {
-        const raw =
-          saved === 'terminal' || packChatSlots.some((s) => s.slotId === saved)
-            ? saved
-            : null;
-        return sanitizeRightPanelKind(raw);
+      const map = parseRightPanelMap({
+        raw: window.localStorage.getItem(RIGHT_PANEL_KEY),
+        legacyTerminalOpen: window.localStorage.getItem(TERMINAL_OPEN_KEY),
+        chatId: chatId ?? null,
+        isValidValue,
+      });
+      const sanitized: RightPanelMap = {};
+      for (const [id, value] of Object.entries(map)) {
+        const next = sanitizeRightPanelKind(value);
+        if (next) sanitized[id] = next;
       }
-      // 新 key 不存在时才迁移老版本仅持久化终端的旧 key。
-      return sanitizeRightPanelKind(
-        window.localStorage.getItem(TERMINAL_OPEN_KEY) === '1' ? 'terminal' : null,
-      );
+      return sanitized;
     } catch {
-      return null;
+      return {};
     }
-  });
+  }, [chatId, packChatSlots]);
 
-  // 自动展开 / 手动切换回调是挂载时注册的，直接读 state 会拿到过期闭包，
-  // 所以用 ref 跟踪当前栏位状态（见下方同步 effect）。
-  const rightPanelRef = useRef(rightPanel);
+  const [rightPanelMap, setRightPanelMap] = useState<RightPanelMap>(() =>
+    readRightPanelMap(),
+  );
 
-  const persistRightPanel = useCallback((next: RightPanelState) => {
+  // 切换会话时重新读取映射（迁移老 key / 多窗口写入）。
+  useEffect(() => {
+    setRightPanelMap(readRightPanelMap());
+  }, [readRightPanelMap]);
+
+  const rightPanel: RightPanelState = chatId ? rightPanelMap[chatId] ?? null : null;
+
+  const persistRightPanelMap = useCallback((map: RightPanelMap) => {
     try {
-      window.localStorage.setItem(RIGHT_PANEL_KEY, next ?? '');
+      window.localStorage.setItem(RIGHT_PANEL_KEY, JSON.stringify(map));
     } catch {
       /* ignore */
     }
   }, []);
 
+  const setRightPanel = useCallback(
+    (next: RightPanelState) => {
+      if (!chatId) return;
+      setRightPanelMap((prev) => {
+        const map = { ...prev };
+        if (next === null) delete map[chatId];
+        else map[chatId] = next;
+        persistRightPanelMap(map);
+        return map;
+      });
+    },
+    [chatId, persistRightPanelMap],
+  );
+
+  // 自动展开 / 手动切换回调是挂载时注册的，直接读 state 会拿到过期闭包，
+  // 所以用 ref 跟踪当前栏位状态（见下方同步 effect）。
+  const rightPanelRef = useRef<RightPanelState>(rightPanel);
+
   useEffect(() => {
     rightPanelRef.current = rightPanel;
   }, [rightPanel]);
 
   const closeRightPanel = useCallback(() => {
-    rightPanelRef.current = null;
-    setRightPanelState(null);
-    persistRightPanel(null);
-  }, [persistRightPanel]);
+    setRightPanel(null);
+  }, [setRightPanel]);
 
-  /** 分段控件 / 快捷键入口：点已打开的按钮关闭；点另一个按钮直接切换。
+  /** 顶栏 / 快捷键入口：点已打开的按钮关闭；点另一个按钮直接切换。
       打开任一面板即离开任务 dock（栏位同一时刻只呈现一个内容）。 */
   const toggleRightPanel = useCallback(
     (kind: string) => {
@@ -318,11 +397,11 @@ function AgentLayoutContent() {
       const next = sanitizeRightPanelKind(raw);
       rightPanelRef.current = next;
       if (next !== null) setInspectedTask(null);
-      setRightPanelState(next);
-      persistRightPanel(next);
+      setRightPanel(next);
     },
-    [persistRightPanel],
+    [setRightPanel],
   );
+
   // dock 里当前显示的任务（null = 显示终端）。recentTask 在切回终端后仍
   // 保留，终端头部的「后台任务」按钮据此切回来——任务的挑选入口只有一个，
   // 就是 chat 头部的后台任务弹层。
@@ -369,10 +448,8 @@ function AgentLayoutContent() {
   const showTerminalFromTask = useCallback(() => {
     if (!hostToolChrome('terminal')) return;
     setInspectedTask(null);
-    rightPanelRef.current = 'terminal';
-    setRightPanelState('terminal');
-    persistRightPanel('terminal');
-  }, [persistRightPanel]);
+    setRightPanel('terminal');
+  }, [setRightPanel]);
 
   // 包槽位的自动展开（如文档包：后端在本轮产出新设计稿时广播包事件）。
   // 互斥规则：仅当栏位空闲（null）时 reveal 才生效；
@@ -384,8 +461,7 @@ function AgentLayoutContent() {
         reveal: () => {
           if (rightPanelRef.current !== null) return;
           rightPanelRef.current = slot.slotId;
-          setRightPanelState(slot.slotId);
-          persistRightPanel(slot.slotId);
+          setRightPanel(slot.slotId);
         },
         getCurrentChatId: () => chatId ?? null,
       });
@@ -396,7 +472,7 @@ function AgentLayoutContent() {
     };
     // packChatSlots 在 bootstrap 后稳定；chatId 经 getCurrentChatId 闭包读取。
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [chatId, persistRightPanel]);
+  }, [chatId, setRightPanel]);
 
   // Same drag ergonomics as the sidebar handle, mirrored: the terminal's
   // right edge is pinned to the window's right padding (p-1.5 = 6px), so the
@@ -475,7 +551,6 @@ function AgentLayoutContent() {
               data={data}
               rightPanel={rightPanel}
               onToggleRightPanel={toggleRightPanel}
-              chatSlots={packChatSlots}
               onCollapse={toggleSidebarCollapsed}
             />
           </div>
@@ -501,6 +576,9 @@ function AgentLayoutContent() {
                   registerChatMessageSender,
                   sendChatMessage,
                   inspectTask,
+                  chatSlots: packChatSlots,
+                  rightPanel,
+                  onToggleChatSlot: toggleRightPanel,
                 } satisfies AgentOutletContext}
               />
             </div>

package/src/lib/attachments.ts

@@ -39,43 +39,43 @@ export async function fileToBase64(file: File): Promise<string> {
   return btoa(binary);
 }
 
-/** 正文引用：优先落盘路径，浏览器未落盘时退回文件名（避免写成空的 ``）。 */
-export function attachmentRefLabel(file: AttachmentFile): string {
-  return file.path || file.name;
+/** 单个附件落盘失败的原因（附带原文件，调用方可保留在选择器里让用户重试）。 */
+export interface AttachmentSaveFailure {
+  name: string;
+  error: string;
+  /** 失败前的原始选择项；浏览器模式下 `file` 仍在，可重试。 */
+  file: AttachmentFile;
 }
 
-/**
- * 把附件写进用户消息：正文「关联文件」列表 + 图像 metadata。
- * 只收录有路径或文件名的项。
- */
-export function composeAttachmentUserContent(
-  text: string,
-  files: AttachmentFile[],
-): { content: string; images: Array<{ path: string; name: string }> } {
-  const usable = files.filter((file) => attachmentRefLabel(file));
-  let content = text.trim();
-  if (usable.length > 0) {
-    const fileRefs = usable.map((file) => `- \`${attachmentRefLabel(file)}\``).join('\n');
-    content = content ? `${content}\n\n---\n关联文件:\n${fileRefs}` : `关联文件:\n${fileRefs}`;
-  }
-  const images = usable
-    .filter((file) => isImageFile(file.path || file.name))
-    .map((file) => ({ path: attachmentRefLabel(file), name: file.name }));
-  return { content, images };
+export interface SaveChatAttachmentsResult {
+  /**
+   * 本条消息可用的附件：已落盘（返回落盘绝对路径）的项；Electron 下若落盘
+   * 失败但源路径仍在，也保留源路径。**不会**再出现浏览器模式那种
+   * `path: ''` 的空引用。
+   */
+  files: AttachmentFile[];
+  /** 无法持久化、也没有任何可用路径的文件——调用方必须让用户看到。 */
+  failures: AttachmentSaveFailure[];
 }
 
 /**
- * 把一批附件持久化到会话附件目录，返回「提交时应使用」的文件列表：
- * 成功项用落盘路径，失败项退回原文件（不让用户的选择因单个文件失败而丢失）。
- * 无 attachments 桥 / 空 chatId 时原样返回。
+ * 把一批附件持久化到会话附件目录，返回「提交时应使用」的文件列表 + 失败项：
+ *   - 成功项用落盘路径（稳定、可被 agent 的 local_read_file 读回）；
+ *   - 失败项：Electron 下源路径还可用就退回源路径；浏览器模式下文件没有
+ *     路径，落盘失败即不可用，从 `files` 剔除并进 `failures`（避免把
+ *     空路径写进消息、让模型以为「收到了文件」却什么都读不到）。
+ *
+ * 无 attachments 桥 / 空 chatId 时不做持久化，原样返回
+ * （`failures` 为空——此时是调用方自己决定不落盘，不算失败）。
+ * 浏览器模式只要桥在，仍把字节读成 base64 走 HTTP 落盘。
  */
 export async function saveChatAttachments(
   chatId: string | null | undefined,
   files: AttachmentFile[],
-): Promise<AttachmentFile[]> {
-  if (!chatId || files.length === 0) return files;
+): Promise<SaveChatAttachmentsResult> {
+  if (!chatId || files.length === 0) return { files, failures: [] };
   const bridge = getElectronBridge();
-  if (!bridge?.attachments?.save) return files;
+  if (!bridge?.attachments?.save) return { files, failures: [] };
   try {
     // 有真实路径走 path 拷贝（Electron）；没有则读字节走 data 上传（BS/browser）。
     const payloadFiles = await Promise.all(
@@ -88,15 +88,65 @@ export async function saveChatAttachments(
     const result = await bridge.attachments.save({ chatId, files: payloadFiles });
     const stored = Array.isArray(result?.files) ? result.files : [];
     // 服务端按输入顺序返回逐文件结果，这里按下标对齐回填。
-    return files.map((file, index) => {
+    const kept: AttachmentFile[] = [];
+    const failures: AttachmentSaveFailure[] = [];
+    files.forEach((file, index) => {
       const entry = stored[index];
       if (entry && entry.path && !entry.error) {
-        return { name: entry.name || file.name, path: entry.path };
+        kept.push({ name: entry.name || file.name, path: entry.path });
+        return;
+      }
+      if (file.path) {
+        // Electron 源路径仍可用，退回源路径（与旧行为一致）。
+        kept.push(file);
+        return;
       }
-      return file;
+      failures.push({ name: file.name, error: entry?.error || '上传失败', file });
     });
+    return { files: kept, failures };
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
     console.warn('[attachments] save failed, falling back to source paths', err);
-    return files;
+    const kept = files.filter((f) => Boolean(f.path));
+    const failures = files
+      .filter((f) => !f.path)
+      .map((f) => ({ name: f.name, error: message, file: f }));
+    return { files: kept, failures };
   }
 }
+
+/** 把失败项拼成一条给用户看的中文提示（供各提交入口复用）。 */
+export function formatAttachmentFailures(failures: AttachmentSaveFailure[]): string {
+  if (failures.length === 0) return '';
+  const detail = failures.map((f) => `${f.name}（${f.error}）`).join('；');
+  return failures.length === 1
+    ? `文件「${failures[0].name}」未能上传，本条消息未包含它：${failures[0].error}`
+    : `${failures.length} 个文件未能上传，本条消息未包含它们：${detail}`;
+}
+
+/**
+ * 把附件引用段落拼进用户消息正文。**所有文件**（docx / pdf / xlsx / 任意
+ * 二进制，不只是图片）都写落盘绝对路径，agent 用 `local_read_file` 读回；
+ * 图片的多模态通道是**额外**的，见 {@link collectImageAttachments}。
+ * 两个提交入口（会话内 / 落地页）共用本函数，避免装配规则再次分叉。
+ */
+export function appendAttachmentRefs(rawText: string, files: AttachmentFile[]): string {
+  if (files.length === 0) return rawText;
+  const refs = files.map((f) => `- \`${f.path}\``).join('\n');
+  return rawText
+    ? `${rawText}\n\n---\n关联文件:\n${refs}`
+    : `关联文件:\n${refs}`;
+}
+
+/**
+ * 图片附件的多模态元数据（`metadata.images`）。非图片文件不进这里——它们
+ * 已经通过 {@link appendAttachmentRefs} 的路径引用交给 agent 读取，不会被
+ * 图片逻辑过滤掉。
+ */
+export function collectImageAttachments(
+  files: AttachmentFile[],
+): Array<{ path: string; name: string }> {
+  return files
+    .filter((f) => isImageFile(f.path))
+    .map((f) => ({ path: f.path, name: f.name }));
+}

package/src/pages/AgentPage.tsx

@@ -61,11 +61,14 @@ import {
   setPendingFirstMessage,
   takePendingFirstMessage,
 } from "@/lib/pending-first-message";
+import { BRAND_NAME, pickDefaultAgentId } from "@/brand";
 import {
-  composeAttachmentUserContent,
+  appendAttachmentRefs,
+  collectImageAttachments,
+  formatAttachmentFailures,
   saveChatAttachments,
+  type AttachmentFile,
 } from "@/lib/attachments";
-import { BRAND_NAME, pickDefaultAgentId } from "@/brand";
 
 /**
  * `GET /api/v2/chats/:id/messages` returns rows in `createdAt DESC` (latest
@@ -672,6 +675,15 @@ function AgentChatView({
     // 是 fire-and-forget 的，所以这边不需要也不应该处理 chat_title_updated。
   }, []);
 
+  // 前端流式连接断开（浏览器/网络层）时，后端回合可能仍在运行。不要停在
+  // 「请求失败：network error」；立即 remount 做一次对账：
+  //   - 后端仍 active → 新 mount 从 /live-stream 快照继续展示；
+  //   - 后端已结束 → 新 mount 从 /messages 拉最终落库消息。
+  // 这样就不需要用户手动刷新页面。
+  const handleStreamError = useCallback(() => {
+    onBranchTick();
+  }, [onBranchTick]);
+
   const {
     messages,
     isStreaming,
@@ -687,6 +699,7 @@ function AgentChatView({
     transport,
     initialMessages,
     onUnknownEvent: handleUnknownEvent,
+    onStreamError: handleStreamError,
   });
 
   // ── 切回恢复：远端回合仍在跑，但本 mount 不是发起者 ──────────────────
@@ -1065,6 +1078,7 @@ function AgentChatView({
         </div>
       )}
       <LocalChatPanel
+        chatId={chatId}
         messages={effectiveMessages}
         isStreaming={effectiveIsStreaming}
         onSubmit={handleSubmit}
@@ -1074,7 +1088,6 @@ function AgentChatView({
         pendingFollowUps={pendingFollowUps.map((m) => m.content)}
         onRemoveFollowUp={removeFollowUp}
         className="flex-1"
-        chatId={chatId}
         emptyHero={{
           title: BRAND_NAME,
           subtitle: '输入消息，直接开始一段新对话。',
@@ -1085,6 +1098,9 @@ function AgentChatView({
             onBranchSwitched={isElectron() ? onBranchTick : undefined}
             onInspectTask={ctx.inspectTask}
             tasks={tasks}
+            chatSlots={ctx.chatSlots}
+            rightPanel={ctx.rightPanel}
+            onToggleChatSlot={ctx.onToggleChatSlot}
           />
         }
         onRegenerate={
@@ -1225,7 +1241,7 @@ function EmptyChatGate() {
   const [searchParams] = useSearchParams();
   const projectIdFromUrl = searchParams.get("projectId");
   const [inputValue, setInputValue] = useState("");
-  const [files, setFiles] = useState<{ name: string; path: string }[]>([]);
+  const [files, setFiles] = useState<AttachmentFile[]>([]);
   const [mentionReferences, setMentionReferences] = useState<
     MentionReference[]
   >([]);
@@ -1293,14 +1309,14 @@ function EmptyChatGate() {
 
   const handleSubmit = useCallback(async () => {
     if (isCreating) return;
-    let trimmed = inputValue.trim();
-    if (!trimmed && files.length === 0) return;
+    const rawText = inputValue.trim();
+    if (!rawText && files.length === 0) return;
     trackBehavior('composer_send', {
       empty: false,
       home: true,
       mode: mode === 'plan' ? 'plan' : 'agent',
       execPolicy,
-      length: trimmed.length,
+      length: rawText.length,
     });
 
     const mentionedAgentIds = mentionReferences
@@ -1309,6 +1325,18 @@ function EmptyChatGate() {
     const referencedChatIds = mentionReferences
       .filter((ref) => ref.type === "chat")
       .map((ref) => ref.id);
+    // 文件路径引用与图像元数据在会话建好、附件落盘之后再装配（见下）——
+    // 落地页提交时还没有 chatId，不能像旧代码那样直接用 `f.path`（浏览器
+    // 模式下它是空串，会把一条空引用写进正文，模型以为收到了文件却读不到）。
+    const baseMetadata = {
+      ...(mode === "plan" ? { mode: "plan" as const } : {}),
+      ...(execPolicy === "full" ? { execPolicy: "full" as const } : {}),
+      ...(ctx.selectedAgentId ? { agentId: ctx.selectedAgentId } : {}),
+      ...(mentionedAgentIds.length > 0 ? { mentionedAgentIds } : {}),
+      ...(referencedChatIds.length > 0 ? { referencedChatIds } : {}),
+      ...(modelOverride ? { model: modelOverride } : {}),
+      ...(effortOverride ? { reasoningEffort: effortOverride } : {}),
+    };
 
     setIsCreating(true);
     setCreateError(null);
@@ -1318,23 +1346,29 @@ function EmptyChatGate() {
         ...(ctx.selectedAgentId ? { agentId: ctx.selectedAgentId } : {}),
       });
       if (!id) throw new Error("创建对话失败，请重试");
-      // 落地页提交时还没有 chatId；先建会话再落盘，正文用落盘路径。
-      const resolvedFiles =
-        files.length > 0 ? await saveChatAttachments(id, files) : files;
-      const assembled = composeAttachmentUserContent(trimmed, resolvedFiles);
+      // 会话已建，把附件落进会话空间（与 LocalChatPanel 同一套语义）：
+      // 所有文件都写落盘路径引用（agent 用 local_read_file 读回）；仅图片
+      // 额外进 metadata.images 走多模态，非图片文件不会被图片逻辑吞掉。
+      const { files: resolvedFiles, failures } = await saveChatAttachments(id, files);
+      if (failures.length > 0) {
+        // 落地页一旦跳转就没法让用户重试了，所以这里宁可中止本次发送：
+        // 删掉刚建的空会话，保留输入框（含失败文件），把原因显示出来。
+        await ctx.deleteChat(id);
+        setCreateError(formatAttachmentFailures(failures));
+        setIsCreating(false);
+        return;
+      }
+
+      const content = appendAttachmentRefs(rawText, resolvedFiles);
+      const imageAttachments = collectImageAttachments(resolvedFiles);
       const metadata = {
-        ...(mode === "plan" ? { mode: "plan" as const } : {}),
-        ...(execPolicy === "full" ? { execPolicy: "full" as const } : {}),
-        ...(ctx.selectedAgentId ? { agentId: ctx.selectedAgentId } : {}),
-        ...(mentionedAgentIds.length > 0 ? { mentionedAgentIds } : {}),
-        ...(referencedChatIds.length > 0 ? { referencedChatIds } : {}),
-        ...(modelOverride ? { model: modelOverride } : {}),
-        ...(effortOverride ? { reasoningEffort: effortOverride } : {}),
-        ...(assembled.images.length > 0 ? { images: assembled.images } : {}),
+        ...baseMetadata,
+        ...(imageAttachments.length > 0 ? { images: imageAttachments } : {}),
       };
+
       setPendingFirstMessage({
         chatId: id,
-        content: assembled.content,
+        content,
         metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
       });
       navigate(`/agent/${id}`);