@steerable/agent-shell-web 0.6.64 → 0.6.66

package/src/layouts/RightPanelTabBar.tsx

@@ -0,0 +1,214 @@
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+import { LuPlus, LuTerminal, LuX } from 'react-icons/lu';
+import type { PackChatSlotContribution } from '@/packs/registry';
+import { t } from '@/i18n';
+import { PanelToggleButton } from '@/layouts/PanelToggleButton';
+import type { RightPanelTabRecord } from '@/layouts/right-panel-tabs';
+
+/**
+ * 右侧栏位的标签条。打开的文档、终端都留在这一行，点标签切换，点 × 关掉那一个。
+ * 还没打开的栏位从行尾的加号加进去。最右边的按钮收起整栏。
+ */
+export function RightPanelTabBar({
+  tabs,
+  activeTabId,
+  slots,
+  showTerminal,
+  onActivate,
+  onClose,
+  onOpen,
+  onCollapse,
+}: {
+  tabs: readonly RightPanelTabRecord[];
+  activeTabId: string;
+  slots: readonly PackChatSlotContribution[];
+  showTerminal: boolean;
+  onActivate: (tabId: string) => void;
+  onClose: (tabId: string) => void;
+  onOpen: (kind: string) => void;
+  onCollapse: () => void;
+}) {
+  const addable = unopenedPanels(tabs, slots, showTerminal);
+  return (
+    <div className="flex h-10 shrink-0 items-center gap-1 border-b border-agent-border bg-agent-canvas px-2">
+      <div
+        role="tablist"
+        aria-label={t('Panels')}
+        data-testid="right-panel-tabs"
+        className="flex min-w-0 flex-1 items-center gap-1 overflow-x-auto"
+      >
+        {tabs.map((tab) => {
+          const slot = slots.find((item) => item.slotId === tab.kind);
+          const Icon = slot?.Icon ?? (tab.kind === 'terminal' ? LuTerminal : null);
+          const selected = tab.id === activeTabId;
+          return (
+            <div
+              key={tab.id}
+              role="tab"
+              aria-selected={selected}
+              data-testid={`right-panel-tab-${tab.id}`}
+              className={`flex h-7 max-w-[11rem] shrink-0 items-center rounded-md pl-1.5 text-xs ${
+                selected
+                  ? 'bg-agent-foreground/10 font-medium text-agent-foreground'
+                  : 'text-agent-muted-foreground hover:bg-agent-foreground/5 hover:text-agent-foreground'
+              }`}
+            >
+              <button
+                type="button"
+                onClick={() => onActivate(tab.id)}
+                className="flex min-w-0 items-center gap-1 px-0.5"
+                title={tab.title}
+              >
+                {Icon ? <Icon className="h-3.5 w-3.5 shrink-0" /> : null}
+                <span className="truncate">{tab.title}</span>
+              </button>
+              <button
+                type="button"
+                onClick={() => onClose(tab.id)}
+                className="flex h-5 w-5 shrink-0 items-center justify-center rounded text-agent-muted-foreground hover:bg-agent-foreground/10 hover:text-agent-foreground"
+                aria-label={t('Close {name}', { name: tab.title })}
+                title={t('Close {name}', { name: tab.title })}
+              >
+                <LuX className="h-3 w-3" />
+              </button>
+            </div>
+          );
+        })}
+        {addable.length > 0 && <AddPanelButton entries={addable} onOpen={onOpen} />}
+      </div>
+      <PanelToggleButton pressed onClick={onCollapse} />
+    </div>
+  );
+}
+
+function AddPanelButton({
+  entries,
+  onOpen,
+}: {
+  entries: readonly AddPanelEntry[];
+  onOpen: (id: string) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const [box, setBox] = useState<{ top: number; left: number } | null>(null);
+  const buttonRef = useRef<HTMLButtonElement | null>(null);
+  const menuRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    const button = buttonRef.current;
+    if (!open || !button) {
+      setBox(null);
+      return;
+    }
+    const update = () => {
+      const rect = button.getBoundingClientRect();
+      const width = 168;
+      const left = Math.min(Math.max(8, rect.left), window.innerWidth - width - 8);
+      setBox({ top: rect.bottom + 4, left });
+    };
+    update();
+    window.addEventListener('resize', update);
+    window.addEventListener('scroll', update, true);
+    return () => {
+      window.removeEventListener('resize', update);
+      window.removeEventListener('scroll', update, true);
+    };
+  }, [open]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onPointerDown = (event: MouseEvent) => {
+      const target = event.target as Node;
+      if (buttonRef.current?.contains(target) || menuRef.current?.contains(target)) return;
+      setOpen(false);
+    };
+    document.addEventListener('mousedown', onPointerDown);
+    return () => document.removeEventListener('mousedown', onPointerDown);
+  }, [open]);
+
+  return (
+    <>
+      <button
+        ref={buttonRef}
+        type="button"
+        onClick={() => setOpen((current) => !current)}
+        className="flex h-7 w-7 shrink-0 items-center justify-center rounded-full text-agent-muted-foreground transition-colors hover:bg-agent-foreground/5 hover:text-agent-foreground"
+        title={t('Open {name}', { name: t('Panels') })}
+        aria-label={t('Open {name}', { name: t('Panels') })}
+        aria-expanded={open}
+        data-testid="right-panel-add"
+      >
+        <LuPlus className="h-3.5 w-3.5" />
+      </button>
+      {open &&
+        box &&
+        createPortal(
+          <div
+            ref={menuRef}
+            className="fixed z-[80] w-[168px] rounded-lg border border-agent-border bg-agent-canvas p-1 shadow-lg"
+            style={{ top: box.top, left: box.left }}
+            data-testid="right-panel-add-menu"
+          >
+            {entries.map((entry) => (
+              <button
+                key={entry.id}
+                type="button"
+                onClick={() => {
+                  onOpen(entry.id);
+                  setOpen(false);
+                }}
+                className="flex w-full items-center gap-2 rounded px-2.5 py-1.5 text-left text-xs text-agent-muted-foreground transition-colors hover:bg-agent-foreground/5 hover:text-agent-foreground"
+                title={entry.detail ?? t('Open {name}', { name: entry.title })}
+                aria-label={entry.id === 'terminal' ? t('Terminal') : entry.title}
+                data-testid={entry.testId}
+              >
+                {entry.icon}
+                <span className="min-w-0 flex-1 truncate">{entry.title}</span>
+              </button>
+            ))}
+          </div>,
+          document.body,
+        )}
+    </>
+  );
+}
+
+interface AddPanelEntry {
+  id: string;
+  title: string;
+  testId: string;
+  icon: ReactNode;
+  detail?: string;
+}
+
+function unopenedPanels(
+  tabs: readonly RightPanelTabRecord[],
+  slots: readonly PackChatSlotContribution[],
+  showTerminal: boolean,
+): AddPanelEntry[] {
+  const entries: AddPanelEntry[] = [];
+  for (const slot of slots) {
+    if (!slot.multiple && tabs.some((tab) => tab.kind === slot.slotId)) continue;
+    const Icon = slot.Icon;
+    entries.push({
+      id: slot.slotId,
+      title: slot.title,
+      testId: `header-slot-${slot.slotId}`,
+      icon: <Icon className="h-3.5 w-3.5 shrink-0" />,
+    });
+  }
+  if (showTerminal && !tabs.some((tab) => tab.kind === 'terminal')) {
+    const shortcut =
+      typeof navigator !== 'undefined' && /Mac|iPod|iPhone|iPad/.test(navigator.platform)
+        ? '⌘T'
+        : 'Ctrl+T';
+    entries.push({
+      id: 'terminal',
+      title: t('Terminal'),
+      testId: 'header-terminal',
+      icon: <LuTerminal className="h-3.5 w-3.5 shrink-0" />,
+      detail: t('Open terminal panel ({shortcut})', { shortcut }),
+    });
+  }
+  return entries;
+}

package/src/layouts/conversation-preview.ts

@@ -0,0 +1,87 @@
+/**
+ * 右侧预览跟着当前对话走，按会话分开，不共用一条全局路径。
+ *
+ * 停在对话底部时显示最近一轮能预览的文件；往上翻时换成看着的那一轮。
+ * 点了某一份文件就先钉住它，直到翻到别的回合。
+ */
+
+export interface ConversationPreviewTarget {
+  chatId: string;
+  messageId: string;
+  path: string;
+}
+
+const targets = new Map<string, ConversationPreviewTarget>();
+const pins = new Map<string, { messageId: string; path: string }>();
+const listeners = new Set<(target: ConversationPreviewTarget) => void>();
+
+function emit(target: ConversationPreviewTarget): void {
+  const previous = targets.get(target.chatId);
+  targets.set(target.chatId, target);
+  if (
+    previous
+    && previous.messageId === target.messageId
+    && previous.path === target.path
+  ) {
+    return;
+  }
+  for (const listener of listeners) listener(target);
+}
+
+/** 从 `#/agent/<chatId>` 取出当前会话。点文件时布局还没把 id 传进来。 */
+export function chatIdFromHash(hash: string): string | null {
+  const match = /#\/agent\/([^/?#]+)/.exec(hash);
+  if (!match?.[1]) return null;
+  try {
+    return decodeURIComponent(match[1]);
+  } catch {
+    return match[1];
+  }
+}
+
+export function peekConversationPreview(chatId: string): ConversationPreviewTarget | null {
+  return targets.get(chatId) ?? null;
+}
+
+export function publishConversationPreview(target: ConversationPreviewTarget): void {
+  if (!target.chatId || !target.path) return;
+  const pin = pins.get(target.chatId);
+  if (!pin) {
+    emit(target);
+    return;
+  }
+  if (pin.messageId === '' || pin.messageId === target.messageId) {
+    if (pin.messageId === '') {
+      pins.set(target.chatId, { messageId: target.messageId, path: pin.path });
+    }
+    emit({ ...target, path: pin.path });
+    return;
+  }
+  pins.delete(target.chatId);
+  emit(target);
+}
+
+/** 点开的文件先于「这一轮的主文件」。翻到别的回合后钉自动松开。 */
+export function pinConversationPreview(
+  chatId: string,
+  path: string,
+  messageId = '',
+): void {
+  if (!chatId || !path) return;
+  pins.set(chatId, { messageId, path });
+  emit({ chatId, messageId, path });
+}
+
+export function subscribeConversationPreview(
+  listener: (target: ConversationPreviewTarget) => void,
+): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function resetConversationPreviewForTests(): void {
+  targets.clear();
+  pins.clear();
+}

package/src/layouts/request-chat-slot.ts

@@ -0,0 +1,65 @@
+/**
+ * 让对话里的文件点击打开右侧栏位。
+ *
+ * 直接通知布局：没有这个标签就打开，已经打开就切过去。整栏收着时一并展开。
+ */
+
+const LEGACY_RESOURCE_SEPARATOR = ':resource:';
+
+export interface ChatSlotRequest {
+  kind: string;
+  contentId?: string;
+  title?: string;
+}
+
+const listeners = new Set<(request: ChatSlotRequest) => void>();
+const followListeners = new Set<(request: ChatSlotRequest) => void>();
+
+/** 只用于读取 v1 持久化的 `slotId:resource:<encoded path>`。 */
+export function parseLegacyChatSlotTabId(value: string): ChatSlotRequest {
+  const separator = value.indexOf(LEGACY_RESOURCE_SEPARATOR);
+  if (separator < 0) return { kind: value };
+  const kind = value.slice(0, separator);
+  const encoded = value.slice(separator + LEGACY_RESOURCE_SEPARATOR.length);
+  if (!kind || !encoded) return { kind: value };
+  try {
+    return { kind, contentId: decodeURIComponent(encoded) };
+  } catch {
+    return { kind: value };
+  }
+}
+
+/** 打开并聚焦这个栏位。 */
+export function requestChatSlot(kind: string, options: Omit<ChatSlotRequest, 'kind'> = {}): void {
+  const request = { kind, ...options };
+  for (const listener of listeners) listener(request);
+}
+
+/** 布局挂上后接收请求。返回取消订阅。 */
+export function subscribeChatSlotRequests(
+  listener: (request: ChatSlotRequest) => void,
+): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * 对话滚动或新产物把右侧内容换到这个栏位。
+ * 和点击不同：栏位关着时不弹出，正在看终端时也不抢走。
+ */
+export function followChatSlot(kind: string, options: Omit<ChatSlotRequest, 'kind'> = {}): void {
+  const request = { kind, ...options };
+  for (const listener of followListeners) listener(request);
+}
+
+/** 布局接收「跟着对话换栏位」的请求。返回取消订阅。 */
+export function subscribeChatSlotFollows(
+  listener: (request: ChatSlotRequest) => void,
+): () => void {
+  followListeners.add(listener);
+  return () => {
+    followListeners.delete(listener);
+  };
+}

package/src/layouts/right-panel-tabs.ts

@@ -0,0 +1,309 @@
+/**
+ * 右侧栏位的多标签状态。
+ *
+ * 同一会话可以同时打开终端和若干包槽位。`activeTabId` 是当前看见的那一个。
+ * `collapsed` 表示整栏收起：标签还留着，右侧不显示，再打开时恢复。
+ * 标签实例 id、内容身份和显示标题分开保存；持久化兼容旧字符串格式。
+ */
+
+export type RightPanelTabRecord = {
+  id: string;
+  kind: string;
+  contentId: string;
+  title: string;
+};
+
+export type RightPanelTabs = {
+  tabs: RightPanelTabRecord[];
+  activeTabId: string;
+  collapsed?: boolean;
+};
+
+/** 每个会话各自的标签：chatId → 打开的标签（没有标签时不落盘）。 */
+export type RightPanelMap = Record<string, RightPanelTabs>;
+
+export type RightPanelTabTarget = Omit<RightPanelTabRecord, 'id'>;
+
+export const RIGHT_PANEL_PERSISTENCE_VERSION = 2;
+
+let fallbackTabSequence = 0;
+
+/** 新建一次标签实例。内容相同的标签是否复用由打开策略决定。 */
+export function createRightPanelTab(
+  target: RightPanelTabTarget,
+  id?: string,
+): RightPanelTabRecord {
+  const generated = globalThis.crypto?.randomUUID?.()
+    ?? `tab-${Date.now().toString(36)}-${(++fallbackTabSequence).toString(36)}`;
+  return { id: id ?? generated, ...target };
+}
+
+function contentKey(tab: Pick<RightPanelTabRecord, 'kind' | 'contentId'>): string {
+  return `${tab.kind}\0${tab.contentId}`;
+}
+
+/** 查找已打开的同一内容。 */
+export function findRightPanelContentTab(
+  current: RightPanelTabs | null,
+  target: Pick<RightPanelTabRecord, 'kind' | 'contentId'>,
+): RightPanelTabRecord | null {
+  return current?.tabs.find((tab) =>
+    tab.kind === target.kind && tab.contentId === target.contentId) ?? null;
+}
+
+/** 非当前标签只在类型声明需要保活时继续挂载。 */
+export function shouldMountRightPanelTab(
+  tabId: string,
+  activeTabId: string,
+  keepMounted: boolean,
+): boolean {
+  return tabId === activeTabId || keepMounted;
+}
+
+function normalizeTabRecord(
+  value: unknown,
+  isValidKind: (kind: string) => boolean,
+): RightPanelTabRecord | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const record = value as Partial<Record<keyof RightPanelTabRecord, unknown>>;
+  if (
+    typeof record.id !== 'string'
+    || !record.id
+    || typeof record.kind !== 'string'
+    || !isValidKind(record.kind)
+    || typeof record.contentId !== 'string'
+    || !record.contentId
+    || typeof record.title !== 'string'
+    || !record.title
+  ) {
+    return null;
+  }
+  return {
+    id: record.id,
+    kind: record.kind,
+    contentId: record.contentId,
+    title: record.title,
+  };
+}
+
+export function normalizeRightPanelEntry(
+  value: unknown,
+  isValidKind: (kind: string) => boolean,
+  resolveLegacyTab: (value: string) => RightPanelTabTarget | null,
+): RightPanelTabs | null {
+  if (typeof value === 'string') {
+    const target = resolveLegacyTab(value);
+    if (!target || !isValidKind(target.kind)) return null;
+    const tab = createRightPanelTab(target, `legacy:${encodeURIComponent(value)}`);
+    return { tabs: [tab], activeTabId: tab.id };
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const record = value as {
+    tabs?: unknown;
+    active?: unknown;
+    activeTabId?: unknown;
+    collapsed?: unknown;
+  };
+  const seenIds = new Set<string>();
+  const seenContent = new Set<string>();
+  const tabs: RightPanelTabRecord[] = [];
+  if (Array.isArray(record.tabs)) {
+    for (const item of record.tabs) {
+      const tab = typeof item === 'string'
+        ? (() => {
+          const target = resolveLegacyTab(item);
+          return target && isValidKind(target.kind)
+            ? createRightPanelTab(target, `legacy:${encodeURIComponent(item)}`)
+            : null;
+        })()
+        : normalizeTabRecord(item, isValidKind);
+      if (!tab || seenIds.has(tab.id) || seenContent.has(contentKey(tab))) continue;
+      seenIds.add(tab.id);
+      seenContent.add(contentKey(tab));
+      tabs.push(tab);
+    }
+  }
+  if (tabs.length === 0) return null;
+  const requestedActive = typeof record.activeTabId === 'string'
+    ? record.activeTabId
+    : typeof record.active === 'string'
+      ? record.active
+      : '';
+  const activeTabId = tabs.some((tab) => tab.id === requestedActive)
+    ? requestedActive
+    : tabs.find((tab) => tab.id === `legacy:${encodeURIComponent(requestedActive)}`)?.id
+      ?? tabs[0]!.id;
+  return record.collapsed === true
+    ? { tabs, activeTabId, collapsed: true }
+    : { tabs, activeTabId };
+}
+
+/**
+ * 解析持久化的「会话 → 右侧标签」映射。
+ *
+ * 兼容这些历史格式：
+ *   - v2：{"version":2,"sessions":{"<chatId>":{"tabs":[...],"activeTabId":"..."}}}；
+ *   - 旧多标签：{"<chatId>": { "tabs": ["ppt", "terminal"], "active": "ppt" }}；
+ *   - 单值映射：{"<chatId>": "terminal" | "<slotId>"} → 一个标签；
+ *   - 整个值就是单个字符串 → 迁到当前会话；
+ *   - 更老：只记录终端是否打开过的布尔 key。
+ * 无效的会话 / 栏位值会被丢弃。
+ */
+export function parseRightPanelMap(options: {
+  raw: string | null;
+  legacyTerminalOpen: string | null;
+  chatId: string | null;
+  isValidKind: (kind: string) => boolean;
+  resolveLegacyTab: (value: string) => RightPanelTabTarget | null;
+}): RightPanelMap {
+  const { raw, legacyTerminalOpen, chatId, isValidKind, resolveLegacyTab } = options;
+  if (raw !== null) {
+    if (raw === '') return {};
+    try {
+      const parsed = JSON.parse(raw) as unknown;
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        const root = parsed as { version?: unknown; sessions?: unknown };
+        const source = root.version === RIGHT_PANEL_PERSISTENCE_VERSION
+          && root.sessions
+          && typeof root.sessions === 'object'
+          && !Array.isArray(root.sessions)
+          ? root.sessions as Record<string, unknown>
+          : parsed as Record<string, unknown>;
+        const map: RightPanelMap = {};
+        for (const [key, value] of Object.entries(source)) {
+          const entry = normalizeRightPanelEntry(value, isValidKind, resolveLegacyTab);
+          if (entry) map[key] = entry;
+        }
+        return map;
+      }
+    } catch {
+      const entry = normalizeRightPanelEntry(raw, isValidKind, resolveLegacyTab);
+      if (entry && chatId) return { [chatId]: entry };
+    }
+    return {};
+  }
+  if (legacyTerminalOpen === '1' && chatId && isValidKind('terminal')) {
+    const tab = createRightPanelTab(
+      { kind: 'terminal', contentId: 'terminal', title: 'Terminal' },
+      'legacy:terminal',
+    );
+    return { [chatId]: { tabs: [tab], activeTabId: tab.id } };
+  }
+  return {};
+}
+
+/** 把运行时状态写成带版本的持久化载荷。 */
+export function serializeRightPanelMap(map: RightPanelMap): string {
+  return JSON.stringify({ version: RIGHT_PANEL_PERSISTENCE_VERSION, sessions: map });
+}
+
+/** 快捷键：整栏收着时打开并显示这一项；没开就追加并显示；已开但不是当前就切过去；当前这个就关掉。 */
+export function toggleRightPanelEntry(
+  current: RightPanelTabs | null,
+  requested: RightPanelTabRecord,
+): RightPanelTabs | null {
+  const existing = findRightPanelContentTab(current, requested);
+  const tab = existing ?? requested;
+  if (current?.collapsed) {
+    const tabs = existing ? current.tabs : [...current.tabs, tab];
+    return { tabs, activeTabId: tab.id };
+  }
+  if (!current || !existing) {
+    return {
+      tabs: current ? [...current.tabs, tab] : [tab],
+      activeTabId: tab.id,
+    };
+  }
+  if (current.activeTabId !== tab.id) {
+    return { tabs: current.tabs, activeTabId: tab.id };
+  }
+  return closeRightPanelTab(current, tab.id);
+}
+
+/** 收起整栏。标签保留，下次展开还是这些。 */
+export function collapseRightPanel(current: RightPanelTabs): RightPanelTabs {
+  return { tabs: current.tabs, activeTabId: current.activeTabId, collapsed: true };
+}
+
+/** 展开整栏，回到收起前正在看的标签。 */
+export function expandRightPanel(current: RightPanelTabs): RightPanelTabs {
+  return { tabs: current.tabs, activeTabId: current.activeTabId };
+}
+
+/** 关掉一个标签。关掉的是当前标签时，改看相邻的那一个。 */
+export function closeRightPanelTab(
+  current: RightPanelTabs,
+  tabId: string,
+): RightPanelTabs | null {
+  const tabs = current.tabs.filter((tab) => tab.id !== tabId);
+  if (tabs.length === 0) return null;
+  if (current.activeTabId !== tabId) return { tabs, activeTabId: current.activeTabId };
+  const index = current.tabs.findIndex((tab) => tab.id === tabId);
+  const active = tabs[Math.min(index, tabs.length - 1)] ?? tabs[0]!;
+  return { tabs, activeTabId: active.id };
+}
+
+/**
+ * 自动展开：栏位空着时打开并显示；已经有别的标签时只把这个加进去，不抢走当前标签。
+ * 这个标签已经开着则保持原样。
+ */
+export function revealRightPanelTab(
+  current: RightPanelTabs | null,
+  requested: RightPanelTabRecord,
+): RightPanelTabs {
+  if (!current) return { tabs: [requested], activeTabId: requested.id };
+  const existing = findRightPanelContentTab(current, requested);
+  const tab = existing ?? requested;
+  if (current.collapsed) {
+    const tabs = existing ? current.tabs : [...current.tabs, tab];
+    return { tabs, activeTabId: tab.id };
+  }
+  if (existing) return current;
+  return { tabs: [...current.tabs, tab], activeTabId: current.activeTabId };
+}
+
+function sameRightPanelTabs(
+  tabs: readonly RightPanelTabRecord[],
+  next: readonly RightPanelTabRecord[],
+): boolean {
+  return tabs.length === next.length && tabs.every((tab, index) => tab.id === next[index]?.id);
+}
+
+/**
+ * 对话里的预览跟着当前回合换文件。
+ * 栏位关着时不重新打开。正在看终端时只把文档标签留在后面，不抢走终端。
+ * 已经开着文档时，切到这一轮对应的标签。
+ */
+export function followRightPanelTab(
+  current: RightPanelTabs | null,
+  requested: RightPanelTabRecord,
+): RightPanelTabs | null {
+  if (!current) return null;
+  const existing = findRightPanelContentTab(current, requested);
+  const tab = existing ?? requested;
+  const tabs = existing ? current.tabs : [...current.tabs, tab];
+  const activeTab = current.tabs.find((item) => item.id === current.activeTabId);
+  const activeTabId = activeTab?.kind === 'terminal' ? activeTab.id : tab.id;
+  const next: RightPanelTabs = current.collapsed
+    ? { tabs, activeTabId, collapsed: true }
+    : { tabs, activeTabId };
+  if (
+    current.activeTabId === next.activeTabId
+    && current.collapsed === next.collapsed
+    && sameRightPanelTabs(current.tabs, next.tabs)
+  ) {
+    return current;
+  }
+  return next;
+}
+
+/** 打开并显示。已经开着时只切换当前标签。 */
+export function openRightPanelTab(
+  current: RightPanelTabs | null,
+  requested: RightPanelTabRecord,
+): RightPanelTabs {
+  if (!current) return { tabs: [requested], activeTabId: requested.id };
+  const existing = findRightPanelContentTab(current, requested);
+  if (existing) return { tabs: current.tabs, activeTabId: existing.id };
+  return { tabs: [...current.tabs, requested], activeTabId: requested.id };
+}

package/src/lib/local-api.ts

@@ -445,6 +445,8 @@ export interface LocalProject {
   sourceFolders?: string[];
   /** W6-5: 信任后该项目目录里的规则文件才会注入模型上下文。缺省 false。 */
   trusted?: boolean;
+  /** 侧边栏顺序，越小越靠前。缺省时列表顺序由服务端决定。 */
+  sortOrder?: number;
   createdAt: string;
   updatedAt: string;
 }
@@ -570,6 +572,15 @@ export async function updateProject(
   });
 }
 
+/** 按 id 顺序保存侧栏项目排序。服务端忽略未知 id，没提到的项目接在后面。 */
+export async function reorderProjects(orderedIds: string[]) {
+  return bridge().localBackend.request<{ success: boolean; projects: LocalProject[] }>({
+    method: 'PUT',
+    path: '/api/v2/projects/order',
+    body: { orderedIds },
+  });
+}
+
 export async function deleteProject(projectId: string) {
   return bridge().localBackend.request<{ success: boolean; detachedChats: number }>({
     method: 'DELETE',