@tablestore/tablestore-agent-cli 0.1.7 → 0.1.9

package/dist/dashboard-runtime/dashboard/src/app/(dashboard)/chat/loading.tsx

@@ -0,0 +1,29 @@
+import { Skeleton } from "@/components/ui/skeleton";
+
+/**
+ * Initial loading state for the `/chat` route. The chat shell needs the
+ * sidebar list, the active session messages and the LLM provider list
+ * before it can hydrate, so we render a two-column placeholder that
+ * preserves the eventual layout to avoid layout shift.
+ */
+export default function ChatLoading() {
+  return (
+    <div
+      className="grid grid-cols-1 gap-4 md:grid-cols-[260px_1fr]"
+      aria-busy="true"
+      aria-live="polite"
+    >
+      <div className="space-y-3">
+        <Skeleton className="h-9 w-full rounded-md" />
+        {Array.from({ length: 6 }).map((_, idx) => (
+          <Skeleton key={idx} className="h-12 w-full rounded-md" />
+        ))}
+      </div>
+      <div className="space-y-3">
+        <Skeleton className="h-10 w-1/2 rounded-md" />
+        <Skeleton className="h-[60vh] w-full rounded-lg" />
+        <Skeleton className="h-12 w-full rounded-md" />
+      </div>
+    </div>
+  );
+}

package/dist/dashboard-runtime/dashboard/src/app/(dashboard)/chat/page.tsx

@@ -0,0 +1,372 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Settings2 } from "lucide-react";
+
+import { Button } from "@/components/ui/button";
+import { QaChatPanel } from "@/components/qa/qa-chat-panel";
+import { ChatHistorySidebar } from "@/components/chat/chat-history-sidebar";
+import { ChatMountConfig } from "@/components/chat/chat-mount-config";
+import {
+  ChatConfigProvider,
+  DEFAULT_AGGREGATE_TOP_K,
+  DEFAULT_PER_KB_TOP_K,
+  buildRagFromMounts,
+  useChatConfig,
+} from "@/components/chat/chat-config-context";
+import {
+  useChatHistory,
+  deriveSessionTitle,
+  type ChatSession,
+} from "@/hooks/use-chat-history";
+import { useQaChat } from "@/hooks/use-qa-chat";
+import {
+  readLastConfig,
+  writeLastConfig,
+} from "@/hooks/use-chat-last-config";
+import {
+  useActiveInstance,
+  type ActiveInstanceState,
+} from "@/hooks/use-active-instance";
+import { newId } from "@/lib/random-id";
+import { findUserAnchorAbove } from "@/lib/chat-message-ops";
+import { PENDING_DATA_SCOPE_KEY } from "@/lib/query-keys";
+import type { ChatMessage } from "@/types/llm-chat";
+
+/** Next.js page entry for the chat homepage. Wraps the UI tree with the
+ *  shared config context so mount/prompt/model state survives across
+ *  renders and session switches. */
+export default function ChatPage() {
+  return (
+    <ChatConfigProvider>
+      <ChatHomepage />
+    </ChatConfigProvider>
+  );
+}
+
+function ChatHomepage() {
+  const cfg = useChatConfig();
+  const activeInstanceState = useActiveInstance();
+  const activeInstance = activeInstanceState.activeInstance;
+  const history = useChatHistory(activeInstanceState);
+
+  const [activeSessionId, setActiveSessionId] = useState<string | null>(null);
+  const [sheetOpen, setSheetOpen] = useState(false);
+  // Guard to skip persistence on the very first render of a blank session;
+  // otherwise we'd spam localStorage with empty rows whenever the user just
+  // opens the page.
+  const hasSentRef = useRef(false);
+
+  /**
+   * Unified session snapshot helper used by both the stream-end auto-save
+   * (`persistSession`) and the manual "save config" CTA (`handleSaveConfig`).
+   *
+   * The two call sites were previously ~95% identical — only the `title`
+   * fallback and the `hasSentRef` guard differed. Folding them into a
+   * single function eliminates the drift risk flagged in CR round 2
+   * (N-L3) while preserving the distinct intents through the flags:
+   *   - `requireSent`: skip persistence when `hasSentRef` is false
+   *     (used by auto-save to avoid spamming empty sessions).
+   *   - `preserveTitle`: keep the existing stored title instead of
+   *     re-deriving from the possibly-empty message list (used by the
+   *     manual save path where the user may click "save config" before
+   *     sending a single message).
+   */
+  const saveChatSession = useCallback(
+    (
+      messages: ChatMessage[],
+      opts: { requireSent: boolean; preserveTitle: boolean },
+    ) => {
+      if (!activeInstanceState.ready) return;
+      if (opts.requireSent && !hasSentRef.current) return;
+      const id = activeSessionId ?? newId("session");
+      if (!activeSessionId) setActiveSessionId(id);
+      const existing = opts.preserveTitle ? history.get(id) : null;
+      const title = existing?.title ?? deriveSessionTitle(messages);
+      const session: ChatSession = {
+        id,
+        title,
+        updatedAt: Date.now(),
+        activeInstance,
+        config: cfg.toSessionConfig(),
+        messages,
+      };
+      history.upsert(session);
+      // Remember this instance's last-used provider/model so the next new
+      // chat on this instance auto-fills the same pair.
+      if (cfg.providerId) {
+        writeLastConfig(activeInstance, {
+          providerId: cfg.providerId,
+          model: cfg.model,
+        });
+      }
+    },
+    [activeSessionId, cfg, history, activeInstance, activeInstanceState.ready],
+  );
+
+  const persistSession = useCallback(
+    (messages: ChatMessage[]) => {
+      saveChatSession(messages, { requireSent: true, preserveTitle: false });
+    },
+    [saveChatSession],
+  );
+
+  // Build the RAG slice from the current mount list on every send so mid-session
+  // mount edits take effect on the next turn without requiring a restart.
+  const rag = useMemo(() => buildRagFromMounts(cfg), [cfg]);
+
+  const chat = useQaChat({
+    activeInstance,
+    providerId: cfg.providerId,
+    model: cfg.model,
+    systemPrompt: cfg.systemPrompt,
+    temperature: cfg.temperature,
+    rag,
+    onPersist: persistSession,
+  });
+
+  // Load an existing session from localStorage into the chat + config state.
+  const loadSession = useCallback(
+    (id: string) => {
+      if (!activeInstanceState.ready) return;
+      const session = history.get(id);
+      if (!session) return;
+      if ((session.activeInstance ?? null) !== activeInstance) return;
+      setActiveSessionId(id);
+      hasSentRef.current = session.messages.length > 0;
+      chat.setMessages(session.messages);
+      cfg.hydrate({
+        providerId: session.config.providerId ?? "",
+        model: session.config.model ?? "",
+        systemPrompt: session.config.systemPrompt ?? "",
+        temperature: session.config.temperature,
+        aggregateTopK: session.config.aggregateTopK ?? DEFAULT_AGGREGATE_TOP_K,
+        perKbTopK: session.config.perKbTopK ?? DEFAULT_PER_KB_TOP_K,
+        retrieval: session.config.retrieval ?? {},
+        mounts: session.config.mounts ?? [],
+      });
+    },
+    // `chat.setMessages` and `cfg.hydrate` are stable references; depend on
+    // the ids instead of the full objects to avoid reload loops.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [history, chat.setMessages, cfg.hydrate, activeInstance, activeInstanceState.ready],
+  );
+
+  const newSession = useCallback(() => {
+    setActiveSessionId(null);
+    hasSentRef.current = false;
+    chat.clear();
+    // Preserve mounts/prompt/temperature/retrieval so rapid-fire "new chat"
+    // doesn't force users to remount KBs; only refresh provider/model from
+    // this instance's remembered pair.
+    const last = readLastConfig(activeInstance);
+    cfg.setProvider(last.providerId ?? "", last.model ?? "");
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [chat.clear, activeInstance, cfg.setProvider]);
+
+  const deleteSession = useCallback(
+    (id: string) => {
+      history.remove(id);
+      if (activeSessionId === id) {
+        setActiveSessionId(null);
+        hasSentRef.current = false;
+        chat.clear();
+      }
+    },
+    [history, activeSessionId, chat],
+  );
+
+  const clearAll = useCallback(() => {
+    history.clear();
+    setActiveSessionId(null);
+    hasSentRef.current = false;
+    chat.clear();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [history, chat.clear]);
+
+  const handleSend = useCallback(
+    (text: string) => {
+      hasSentRef.current = true;
+      void chat.send(text);
+    },
+    [chat],
+  );
+
+  // Edit-and-resend: rewrite the user message in place, then rerun the
+  // assistant pipeline against the new content.
+  const handleEditSave = useCallback(
+    (userId: string, nextContent: string) => {
+      hasSentRef.current = true;
+      chat.editUserMessage(userId, nextContent);
+      void chat.reissueTurn(userId);
+    },
+    [chat],
+  );
+
+  // Regenerate-from-assistant: walk back to the user message above and
+  // reissue. The truncate happens inside reissueTurn, so callers don't need
+  // to pre-trim — passing the user anchor id is enough.
+  const handleRegenerate = useCallback(
+    (assistantId: string) => {
+      const anchor = findUserAnchorAbove(chat.messages, assistantId);
+      if (!anchor) return;
+      hasSentRef.current = true;
+      void chat.reissueTurn(anchor.id);
+    },
+    [chat],
+  );
+
+  // Snapshot the current config to localStorage on demand. Unlike
+  // `persistSession`, this path runs even when no message has been sent yet
+  // so users can lock in their setup before chatting; the resulting session
+  // simply carries an empty message list until the first turn.
+  const handleSaveConfig = useCallback(() => {
+    hasSentRef.current = chat.messages.length > 0 || hasSentRef.current;
+    saveChatSession(chat.messages, {
+      requireSent: false,
+      preserveTitle: true,
+    });
+  }, [chat.messages, saveChatSession]);
+
+  // Cross-tab / CLI config-change fallback. The runtime context poller and
+  // focus refetch update this scope when the active project or current
+  // project's underlying credentials change. Without this guard the chat page
+  // would keep showing the previous scope's mounted KBs and unsent draft.
+  const lastInstanceRef = useRef<ActiveInstanceState>({
+    activeInstance: null,
+    ready: false,
+    dataScopeKey: PENDING_DATA_SCOPE_KEY,
+    configRevision: "",
+  });
+  useEffect(() => {
+    const prev = lastInstanceRef.current;
+    // Only act after runtime context has produced a stable scope. The first
+    // loading -> ready transition must not wipe a freshly-opened blank chat.
+    if (
+      prev.ready &&
+      activeInstanceState.ready &&
+      prev.dataScopeKey !== activeInstanceState.dataScopeKey
+    ) {
+      cfg.reset();
+      setActiveSessionId(null);
+      hasSentRef.current = false;
+      chat.clear();
+    }
+    if (activeInstanceState.ready) {
+      lastInstanceRef.current = activeInstanceState;
+    }
+    // `cfg.reset` and `chat.clear` are stable; tracking the primitive scope
+    // key keeps this to one purge per runtime context change.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [activeInstanceState.dataScopeKey, activeInstanceState.ready]);
+
+  // Auto-fill provider/model with the pair remembered for the current
+  // instance on first mount, and whenever the active instance changes
+  // (instance switcher / cross-tab focus). Only runs while no existing
+  // session is loaded and the context is still in its blank slate, so we
+  // never clobber a session the user just opened.
+  useEffect(() => {
+    if (activeSessionId) return;
+    if (cfg.providerId) return;
+    const last = readLastConfig(activeInstance);
+    if (last.providerId) {
+      cfg.setProvider(last.providerId, last.model ?? "");
+    }
+    // `cfg.setProvider` is stable from the reducer; depending on the
+    // primitive instance name keeps this to one fill per instance change.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [activeInstance, activeSessionId, cfg.providerId]);
+
+  const activeSession = activeSessionId ? history.get(activeSessionId) : null;
+  const canSend = activeInstanceState.ready && Boolean(cfg.providerId && cfg.model);
+  const headerTitle = activeSession?.title ?? "新对话";
+  const mountCount = cfg.mounts.length;
+
+  // Hint surfaced in the empty-state copy when the user just clicked
+  // 「新对话」 and inherited mounts from the previous session. Addresses
+  // the cognitive bias of "this fresh session feels like it remembers
+  // things" — that perception is mostly RAG retrieving similar chunks,
+  // and showing the carry-over count makes the cause visible.
+  const mountsCarryover =
+    !activeSessionId && cfg.mounts.length > 0
+      ? `已沿用上一会话的 ${cfg.mounts.length} 个知识库挂载，按右上角齿轮可调整。`
+      : null;
+
+  return (
+    <div className="flex h-[calc(100vh-8rem)] overflow-hidden rounded-lg border border-[hsl(var(--border))] bg-[hsl(var(--surface))]">
+      <ChatHistorySidebar
+        sessions={history.sessions}
+        activeSessionId={activeSessionId}
+        onNewSession={newSession}
+        onSelectSession={loadSession}
+        onDeleteSession={deleteSession}
+        onClearAll={clearAll}
+      />
+
+      <div className="flex min-w-0 flex-1 flex-col">
+        <header className="flex items-center justify-between border-b border-[hsl(var(--border))] bg-[hsl(var(--surface))] px-4 py-3">
+          <div className="min-w-0">
+            <h1 className="truncate text-sm font-semibold">{headerTitle}</h1>
+            <p className="mt-0.5 text-xs text-muted-foreground">
+              {cfg.providerId && cfg.model ? (
+                <>
+                  {cfg.model} · {mountCount} 个知识库 · 聚合 {cfg.aggregateTopK}
+                </>
+              ) : (
+                "点击右上角设置挂载模型与知识库"
+              )}
+            </p>
+          </div>
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            onClick={() => setSheetOpen(true)}
+            title="对话配置"
+          >
+            <Settings2 className="h-4 w-4" />
+          </Button>
+        </header>
+
+        <div className="flex-1 overflow-hidden p-4">
+          {/*
+            The composer is always rendered (even on a fresh session) so
+            users can start typing immediately. Empty-state copy + a CTA
+            into the config drawer surface inside the panel; this matches
+            the ChatGPT / Claude convention of a sticky composer at the
+            bottom and contextual guidance above it.
+          */}
+          <QaChatPanel
+            messages={chat.messages}
+            isStreaming={chat.isStreaming}
+            canSend={canSend}
+            error={chat.error}
+            onSend={handleSend}
+            onStop={chat.stop}
+            onDelete={chat.deleteMessage}
+            onResend={chat.reissueTurn}
+            onRegenerate={handleRegenerate}
+            onEditSave={handleEditSave}
+            emptyState={{
+              title: canSend ? "可以开始对话了" : "开始对话",
+              description: mountsCarryover
+                ? `${mountsCarryover} 直接在下方输入你的问题。`
+                : canSend
+                ? "直接在下方输入你的问题；随时可以通过右上角齿轮调整模型或挂载的知识库"
+                : "点击右上角齿轮，选择模型并挂载知识库，即可开始问答",
+              actionLabel: "打开配置",
+              onAction: () => setSheetOpen(true),
+            }}
+            disabledPlaceholder="请先点击右上角齿轮配置模型与知识库"
+          />
+        </div>
+      </div>
+
+      <ChatMountConfig
+        open={sheetOpen}
+        onOpenChange={setSheetOpen}
+        onSave={handleSaveConfig}
+      />
+    </div>
+  );
+}

package/dist/dashboard-runtime/dashboard/src/app/(dashboard)/error.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+import { useEffect } from "react";
+import { AlertTriangle, RefreshCw } from "lucide-react";
+
+import { Button } from "@/components/ui/button";
+import { reportClientError } from "@/components/logging/client-error-reporter";
+
+/**
+ * Route-segment error boundary for every page rendered under
+ * `(dashboard)/layout.tsx`. Next.js mounts this component when a page
+ * (or any of its children) throws during render, replacing the page
+ * tree but keeping the surrounding sidebar / breadcrumb shell intact.
+ *
+ * The top-level `app/error.tsx` already catches truly catastrophic
+ * failures; this dashboard-scoped boundary keeps the failure local so
+ * users can navigate away via the sidebar without a full reload.
+ */
+export default function DashboardError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  useEffect(() => {
+    // Surface the error to the browser console so engineers can copy the
+    // stack trace; the digest field links the client-side message to the
+    // server-side log line emitted by Next.js.
+    console.error("Dashboard route error:", error);
+    reportClientError({
+      event: "browser.error_boundary.dashboard",
+      message: error.message,
+      name: error.name,
+      stack: error.stack,
+      digest: error.digest,
+    });
+  }, [error]);
+
+  return (
+    <div className="flex min-h-[60vh] flex-col items-center justify-center gap-6 px-4 text-center">
+      <div className="flex h-14 w-14 items-center justify-center rounded-full bg-destructive/10 text-destructive">
+        <AlertTriangle className="h-7 w-7" aria-hidden="true" />
+      </div>
+      <div className="space-y-2 max-w-md">
+        <h2 className="font-display text-2xl font-semibold tracking-tight text-foreground">
+          页面出错了
+        </h2>
+        <p className="text-sm text-muted-foreground break-words">
+          {error.message || "发生了未知错误，请稍后重试。"}
+        </p>
+        {error.digest ? (
+          <p className="text-xs text-muted-foreground/70">
+            错误编号：<code className="font-mono">{error.digest}</code>
+          </p>
+        ) : null}
+      </div>
+      <div className="flex gap-3">
+        <Button onClick={reset} variant="default">
+          <RefreshCw className="mr-2 h-4 w-4" aria-hidden="true" />
+          重试
+        </Button>
+        <Button asChild variant="outline">
+          <a href="/">返回首页</a>
+        </Button>
+      </div>
+    </div>
+  );
+}

package/dist/dashboard-runtime/dashboard/src/app/(dashboard)/knowledge-base/[name]/documents/documents-client.tsx

@@ -106,9 +106,11 @@ export default function DocumentsClient() {
     async (document: Document) => {
       try {
         await deleteDocuments.mutateAsync({
-          knowledgeBaseName,
-          subspace: effectiveSubspace,
-          documents: [{ docId: document.docId }],
+          request: {
+            knowledgeBaseName,
+            subspace: effectiveSubspace,
+            documents: [{ docId: document.docId }],
+          },
         });
         toast.success("文档已删除");
         setDeleteTarget(null);
@@ -123,19 +125,26 @@ export default function DocumentsClient() {
   );
 
   const handleBatchDelete = useCallback(async () => {
+    const total = selectedDocuments.length;
+    const toastId = toast.loading(`正在删除 0/${total} 个文档...`);
     try {
       await deleteDocuments.mutateAsync({
-        knowledgeBaseName,
-        subspace: effectiveSubspace,
-        documents: selectedDocuments.map((doc) => ({ docId: doc.docId })),
+        request: {
+          knowledgeBaseName,
+          subspace: effectiveSubspace,
+          documents: selectedDocuments.map((doc) => ({ docId: doc.docId })),
+        },
+        onProgress: (completed, all) => {
+          toast.loading(`正在删除 ${completed}/${all} 个文档...`, { id: toastId });
+        },
       });
-      toast.success(`成功删除 ${selectedDocuments.length} 个文档`);
+      toast.success(`成功删除 ${total} 个文档`, { id: toastId });
       setSelectedDocuments([]);
       setShowBatchDeleteConfirm(false);
     } catch (error) {
       const message =
         error instanceof Error ? error.message : "批量删除失败";
-      toast.error(message);
+      toast.error(message, { id: toastId });
     }
   }, [knowledgeBaseName, selectedDocuments, deleteDocuments, effectiveSubspace]);
 
@@ -164,8 +173,8 @@ export default function DocumentsClient() {
   }
 
   const titleText = isSubspaceEnabled
-    ? `文档 (${filteredDocuments.length}) — ${subspace}`
-    : `文档 (${filteredDocuments.length})`;
+    ? `文档 — ${subspace}`
+    : "文档";
 
   // Empty subspace — show a friendly upload CTA but keep the subspace active.
   const isEmptySubspace =
@@ -244,7 +253,9 @@ export default function DocumentsClient() {
 
       {/* 分页控件 */}
       <div className="flex items-center justify-between py-2">
-        <div className="flex items-center gap-2 text-sm text-[hsl(var(--muted-foreground))]">
+        <div className="flex items-center gap-3 text-sm text-[hsl(var(--muted-foreground))]">
+          <span>本页 <span className="font-medium text-[hsl(var(--foreground))]">{filteredDocuments.length}</span> 条</span>
+          <span className="text-[hsl(var(--border))]">|</span>
           <span>每页</span>
           <select
             className="rounded-md border border-[hsl(var(--border))] bg-[hsl(var(--background))] px-2 py-1 text-sm"

package/dist/dashboard-runtime/dashboard/src/app/(dashboard)/knowledge-base/[name]/qa/page.tsx

@@ -1,11 +1,13 @@
 "use client";
 
-import { use, useState } from "react";
+import { use, useCallback, useState } from "react";
 
 import { QaChatPanel } from "@/components/qa/qa-chat-panel";
 import { QaForm, type QaFormState } from "@/components/qa/qa-form";
 import { useKnowledgeBase } from "@/hooks/use-knowledge-base";
+import { useActiveInstance } from "@/hooks/use-active-instance";
 import { useQaChat } from "@/hooks/use-qa-chat";
+import { findUserAnchorAbove } from "@/lib/chat-message-ops";
 
 interface PageProps {
   params: Promise<{ name: string }>;
@@ -15,10 +17,12 @@ export default function QaPlaygroundPage({ params }: PageProps) {
   const { name: rawName } = use(params);
   const knowledgeBaseName = decodeURIComponent(rawName);
   const { data: knowledgeBase } = useKnowledgeBase(knowledgeBaseName);
+  const activeInstanceState = useActiveInstance();
 
   const [formState, setFormState] = useState<QaFormState | null>(null);
 
   const chat = useQaChat({
+    activeInstance: activeInstanceState.activeInstance,
     providerId: formState?.providerId ?? "",
     model: formState?.model ?? "",
     systemPrompt: formState?.systemPrompt ?? "",
@@ -26,7 +30,25 @@ export default function QaPlaygroundPage({ params }: PageProps) {
     rag: formState?.rag,
   });
 
-  const canSend = Boolean(formState?.providerId && formState?.model);
+  const canSend =
+    activeInstanceState.ready && Boolean(formState?.providerId && formState?.model);
+
+  const handleEditSave = useCallback(
+    (userId: string, nextContent: string) => {
+      chat.editUserMessage(userId, nextContent);
+      void chat.reissueTurn(userId);
+    },
+    [chat],
+  );
+
+  const handleRegenerate = useCallback(
+    (assistantId: string) => {
+      const anchor = findUserAnchorAbove(chat.messages, assistantId);
+      if (!anchor) return;
+      void chat.reissueTurn(anchor.id);
+    },
+    [chat],
+  );
 
   return (
     <div className="grid gap-6 lg:grid-cols-[360px_1fr]">
@@ -48,6 +70,10 @@ export default function QaPlaygroundPage({ params }: PageProps) {
           error={chat.error}
           onSend={chat.send}
           onStop={chat.stop}
+          onDelete={chat.deleteMessage}
+          onResend={chat.reissueTurn}
+          onRegenerate={handleRegenerate}
+          onEditSave={handleEditSave}
         />
       </section>
     </div>

package/dist/dashboard-runtime/dashboard/src/app/(dashboard)/layout.tsx

@@ -0,0 +1,75 @@
+import { redirect } from 'next/navigation';
+
+import { listInstances } from '@tablestore/tablestore-agent-shared';
+
+import { BreadcrumbBar } from '@/components/layout/breadcrumb-bar';
+import { Sidebar } from '@/components/layout/sidebar';
+import { SidebarMobile } from '@/components/layout/sidebar-mobile';
+import { SidebarOffset } from '@/components/layout/sidebar-offset';
+
+// The layout reads runtime state (TOML config, env vars) to decide whether
+// to redirect to onboarding. Must opt out of static rendering so the check
+// runs on every request rather than being cached from build time.
+export const dynamic = "force-dynamic";
+
+/**
+ * Whether any credential source (env vars, legacy [default] TOML section, or
+ * a named instance) exists. When nothing is configured we redirect to the
+ * onboarding flow so first-time users see the welcome card instead of a
+ * broken dashboard.
+ */
+function hasUsableCredentials(): boolean {
+  const envConfigured =
+    !!process.env.TABLESTORE_ACCESS_KEY_ID &&
+    !!process.env.TABLESTORE_ACCESS_KEY_SECRET &&
+    !!process.env.TABLESTORE_ENDPOINT &&
+    !!process.env.TABLESTORE_INSTANCE_NAME;
+  if (envConfigured) return true;
+
+  try {
+    const rows = listInstances();
+    // Named instances or the legacy [default] section both count.
+    return rows.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+export default function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  if (!hasUsableCredentials()) {
+    redirect('/onboarding');
+  }
+
+  return (
+    <div className="min-h-screen">
+      {/*
+        Skip-to-content link: visually hidden until focused. Keyboard users
+        can press Tab once on the page to jump straight to the main region,
+        bypassing the sidebar / breadcrumb on every navigation.
+      */}
+      <a
+        href="#main-content"
+        className="sr-only focus:not-sr-only focus:fixed focus:left-4 focus:top-4 focus:z-50 focus:rounded-md focus:bg-primary focus:px-3 focus:py-2 focus:text-sm focus:font-medium focus:text-primary-foreground focus:shadow-md"
+      >
+        跳转到主内容
+      </a>
+      <Sidebar />
+      <SidebarOffset>
+        <SidebarMobile />
+        <BreadcrumbBar />
+        <main
+          id="main-content"
+          tabIndex={-1}
+          aria-label="主内容"
+          className="mx-auto max-w-350 px-8 py-8 max-md:px-4 animate-in fade-in duration-300"
+        >
+          {children}
+        </main>
+      </SidebarOffset>
+    </div>
+  );
+}