@tablestore/tablestore-agent-cli 0.1.4 → 0.1.6

package/dist/dashboard-runtime/dashboard/src/components/documents/doc-upload-dialog.tsx

@@ -29,6 +29,7 @@ import type { MetadataField } from "@/types/knowledge-base";
 interface DocUploadDialogProps {
   knowledgeBaseName: string;
   metadataFields?: MetadataField[];
+  defaultSubspace?: string;
   open: boolean;
   onOpenChange: (open: boolean) => void;
 }
@@ -116,12 +117,13 @@ function filterFolderFiles(list: File[], opts: FolderFilterOptions): File[] {
 export function DocUploadDialog({
   knowledgeBaseName,
   metadataFields,
+  defaultSubspace,
   open,
   onOpenChange,
 }: DocUploadDialogProps) {
   const [mode, setMode] = useState<UploadMode>("file");
   const [files, setFiles] = useState<File[]>([]);
-  const [subspace, setSubspace] = useState("");
+  const [subspace, setSubspace] = useState(defaultSubspace ?? "");
   const [metadataJson, setMetadataJson] = useState("");
   const [metadataValues, setMetadataValues] = useState<Record<string, string>>({});
   const [isDragOver, setIsDragOver] = useState(false);
@@ -202,11 +204,11 @@ export function DocUploadDialog({
     setIncludeInput("");
     setExcludeInput("");
     setRecursive(true);
-    setSubspace("");
+    setSubspace(defaultSubspace ?? "");
     setMetadataJson("");
     setMetadataValues({});
     setJsonPreviewOpen(false);
-  }, []);
+  }, [defaultSubspace]);
 
   const handleModeChange = useCallback((next: string) => {
     const nextMode = next as UploadMode;
@@ -464,12 +466,24 @@ export function DocUploadDialog({
 
           {/* 子空间 */}
           <div className="space-y-2">
-            <Label>子空间（可选）</Label>
+            <Label className="flex items-center gap-2">
+              子空间（可选）
+              {defaultSubspace && (
+                <span className="text-xs font-normal text-muted-foreground">
+                  默认：{defaultSubspace}
+                </span>
+              )}
+            </Label>
             <Input
-              placeholder="输入子空间名称"
+              placeholder={defaultSubspace ? "当前子空间" : "输入子空间名称"}
               value={subspace}
               onChange={(event) => setSubspace(event.target.value)}
             />
+            {defaultSubspace && subspace !== defaultSubspace && (
+              <p className="text-xs text-muted-foreground">
+                提示：将上传到子空间 &quot;{subspace || "（空）"}&quot;，与当前作用域 &quot;{defaultSubspace}&quot; 不同
+              </p>
+            )}
           </div>
 
           {/* Metadata */}

package/dist/dashboard-runtime/dashboard/src/components/knowledge-base/kb-header.tsx

@@ -4,6 +4,7 @@ import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Trash2 } from "lucide-react";
 import { RelativeTime } from "@/components/shared/relative-time";
+import { SubspaceSwitcher } from "@/components/knowledge-base/subspace-switcher";
 import type { KnowledgeBase } from "@/types/knowledge-base";
 
 interface KBHeaderProps {
@@ -67,6 +68,7 @@ export function KBHeader({ knowledgeBase, onDelete }: KBHeaderProps) {
             已开启子空间隔离
           </span>
         )}
+        <SubspaceSwitcher />
         <span>
           创建于 <RelativeTime timestamp={createdAt} />
         </span>

package/dist/dashboard-runtime/dashboard/src/components/knowledge-base/kb-tab-nav.tsx

@@ -1,8 +1,9 @@
 'use client';
 
 import Link from "next/link";
-import { usePathname } from "next/navigation";
+import { usePathname, useSearchParams } from "next/navigation";
 import { cn } from "@/lib/utils";
+import { useSubspaceOptional } from "@/contexts/subspace-context";
 
 interface KBTabNavProps {
   knowledgeBaseName: string;
@@ -17,13 +18,23 @@ const TABS = [
 
 export function KBTabNav({ knowledgeBaseName }: KBTabNavProps) {
   const pathname = usePathname();
+  const searchParams = useSearchParams();
   const basePath = `/knowledge-base/${encodeURIComponent(knowledgeBaseName)}`;
+  // Inline active subspace into tab hrefs to keep middle-click / copy-link
+  // consistent with the SubspaceProvider router.replace fallback.
+  const activeSubspace = useSubspaceOptional()?.subspace ?? null;
+  const params = new URLSearchParams(searchParams.toString());
+  if (activeSubspace) params.set("subspace", activeSubspace);
+  else params.delete("subspace");
+  const qs = params.toString();
+  const querySuffix = qs ? `?${qs}` : "";
 
   return (
     <nav className="flex gap-1 border-b border-[hsl(var(--border))]">
       {TABS.map((tab) => {
-        const href = `${basePath}/${tab.segment}`;
-        const isActive = pathname.startsWith(href);
+        const tabPath = `${basePath}/${tab.segment}`;
+        const href = `${tabPath}${querySuffix}`;
+        const isActive = pathname.startsWith(tabPath);
 
         return (
           <Link

package/dist/dashboard-runtime/dashboard/src/components/knowledge-base/subspace-gate.tsx

@@ -0,0 +1,75 @@
+'use client';
+
+import { useState, type KeyboardEvent } from "react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { useSubspace } from "@/contexts/subspace-context";
+
+export function SubspaceGate() {
+  const { setSubspace, history } = useSubspace();
+  const [inputValue, setInputValue] = useState("");
+
+  const handleSubmit = () => {
+    const trimmed = inputValue.trim();
+    if (!trimmed) return;
+    setSubspace(trimmed);
+    setInputValue("");
+  };
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === "Enter") {
+      e.preventDefault();
+      handleSubmit();
+    }
+  };
+
+  return (
+    <div className="flex flex-col items-center justify-center min-h-[400px] gap-6 px-4">
+      <h2 className="text-2xl font-semibold">请选择子空间</h2>
+      <p className="text-sm text-muted-foreground max-w-[500px] text-center">
+        此知识库已启用子空间隔离，文档按子空间分组存储。请输入您要访问的子空间名称以查看对应文档。
+      </p>
+
+      {history.length > 0 && (
+        <div className="flex flex-col items-center gap-2">
+          <span className="text-xs font-semibold text-muted-foreground">
+            最近使用
+          </span>
+          <div className="flex gap-2 flex-wrap justify-center max-w-[600px]">
+            {history.map((s, idx) => (
+              <button
+                key={s}
+                type="button"
+                onClick={() => setSubspace(s)}
+                className={
+                  idx === 0
+                    ? "px-3 py-1.5 rounded-md text-sm cursor-pointer transition-colors bg-primary/10 border border-primary/30 text-primary hover:bg-primary/20"
+                    : "px-3 py-1.5 rounded-md text-sm cursor-pointer transition-colors bg-muted border border-border hover:bg-primary/10 hover:border-primary/30"
+                }
+              >
+                {s}
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+
+      <div className="flex gap-2 w-full max-w-[480px]">
+        <Input
+          placeholder="输入子空间名称..."
+          value={inputValue}
+          onChange={(e) => setInputValue(e.target.value)}
+          onKeyDown={handleKeyDown}
+          className="text-base"
+        />
+        <Button onClick={handleSubmit} disabled={!inputValue.trim()}>
+          进入
+        </Button>
+      </div>
+
+      <p className="text-xs text-muted-foreground">
+        提示：子空间名称由创建者自定义，如 &quot;team-alpha&quot;、&quot;docs-v2&quot; 等
+      </p>
+    </div>
+  );
+}

package/dist/dashboard-runtime/dashboard/src/components/knowledge-base/subspace-switcher.tsx

@@ -0,0 +1,144 @@
+'use client';
+
+import { useState, type KeyboardEvent } from "react";
+import { Check, ChevronDown, X } from "lucide-react";
+import { toast } from "sonner";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Separator } from "@/components/ui/separator";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { useSubspaceOptional } from "@/contexts/subspace-context";
+
+/**
+ * Inline subspace switcher rendered in KBHeader. Mirrors the UX of GitHub
+ * repo / Linear workspace switchers and keeps a placeholder trigger after
+ * a clear so the user can immediately pick another scope.
+ */
+export function SubspaceSwitcher() {
+  const ctx = useSubspaceOptional();
+  const [open, setOpen] = useState(false);
+  const [inputValue, setInputValue] = useState("");
+
+  // No provider mounted (e.g. KB list page).
+  if (!ctx) return null;
+
+  const { subspace, history, setSubspace, clearSubspace } = ctx;
+  const hasActive = subspace !== null;
+
+  const handleSubmit = () => {
+    const trimmed = inputValue.trim();
+    if (!trimmed || trimmed === subspace) {
+      setInputValue("");
+      setOpen(false);
+      return;
+    }
+    setSubspace(trimmed);
+    setInputValue("");
+    setOpen(false);
+  };
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === "Enter") {
+      e.preventDefault();
+      handleSubmit();
+    }
+  };
+
+  const handlePick = (s: string) => {
+    if (s !== subspace) setSubspace(s);
+    setOpen(false);
+  };
+
+  const handleClear = () => {
+    clearSubspace();
+    setOpen(false);
+    toast.success("已清除子空间作用域，请重新选择");
+  };
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className="inline-flex items-center gap-1 px-2 py-0.5 rounded-md bg-primary/10 text-primary text-xs font-medium hover:bg-primary/15 transition-colors cursor-pointer"
+        >
+          {hasActive ? `子空间: ${subspace}` : "选择子空间…"}
+          <ChevronDown className="h-3 w-3 opacity-70" />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent
+        align="start"
+        sideOffset={6}
+        className="w-72 p-3 space-y-3"
+      >
+        <div className="space-y-1">
+          <label className="text-xs font-medium text-muted-foreground">
+            {hasActive ? "切换到其他子空间" : "进入子空间"}
+          </label>
+          <div className="flex gap-1.5">
+            <Input
+              autoFocus
+              placeholder="输入子空间名称..."
+              value={inputValue}
+              onChange={(e) => setInputValue(e.target.value)}
+              onKeyDown={handleKeyDown}
+              className="h-8 text-sm"
+            />
+            <Button
+              size="sm"
+              className="h-8 px-2.5"
+              onClick={handleSubmit}
+              disabled={!inputValue.trim() || inputValue.trim() === subspace}
+            >
+              进入
+            </Button>
+          </div>
+        </div>
+
+        {history.length > 0 && (
+          <div className="space-y-1">
+            <span className="text-xs font-medium text-muted-foreground">
+              最近使用
+            </span>
+            <div className="flex flex-col gap-0.5 max-h-[180px] overflow-y-auto">
+              {history.map((s) => {
+                const active = hasActive && s === subspace;
+                return (
+                  <button
+                    key={s}
+                    type="button"
+                    onClick={() => handlePick(s)}
+                    className="flex items-center justify-between rounded-sm px-2 py-1.5 text-sm text-left hover:bg-[hsl(var(--accent))] transition-colors"
+                  >
+                    <span className="truncate">{s}</span>
+                    {active && (
+                      <Check className="h-3.5 w-3.5 text-primary shrink-0 ml-2" />
+                    )}
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+        )}
+
+        {hasActive && (
+          <>
+            <Separator />
+            <button
+              type="button"
+              onClick={handleClear}
+              className="flex items-center gap-1.5 text-xs text-muted-foreground hover:text-destructive transition-colors w-full"
+            >
+              <X className="h-3 w-3" />
+              清除选择（返回子空间选择页）
+            </button>
+          </>
+        )}
+      </PopoverContent>
+    </Popover>
+  );
+}

package/dist/dashboard-runtime/dashboard/src/components/layout/breadcrumb-bar.tsx

@@ -5,6 +5,7 @@ import { usePathname } from "next/navigation";
 import { ChevronRight, HelpCircle } from "lucide-react";
 import { cn } from "@/lib/utils";
 import { InstanceSwitcher } from "./instance-switcher";
+import { ThemeToggle } from "./theme-toggle";
 import { Separator } from "@/components/ui/separator";
 
 const HELP_URL_KB = "https://help.aliyun.com/zh/tablestore/knowledge-base-rag/";
@@ -98,6 +99,7 @@ export function BreadcrumbBar() {
       <div className="flex items-center gap-2">
         <InstanceSwitcher />
         <Separator orientation="vertical" className="h-5" />
+        <ThemeToggle />
         <a
           href={helpUrl}
           target="_blank"

package/dist/dashboard-runtime/dashboard/src/components/layout/theme-toggle.tsx

@@ -0,0 +1,63 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Moon, Sun } from "lucide-react";
+import { useTheme } from "@/providers/theme-provider";
+import { cn } from "@/lib/utils";
+
+/**
+ * iOS-style light/dark switch. The thumb carries the icon of the currently
+ * active mode (sun = light, moon = dark) and slides between the two ends.
+ * Initial state follows the OS preference; once the user toggles it the
+ * choice is persisted by next-themes and overrides the system setting.
+ */
+export function ThemeToggle() {
+  const { setTheme, resolvedTheme } = useTheme();
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => setMounted(true), []);
+
+  // Reserve the same footprint during SSR to avoid layout shift and the
+  // classic next-themes hydration warning.
+  if (!mounted) {
+    return <div className="h-6 w-11" aria-hidden />;
+  }
+
+  const isDark = resolvedTheme === "dark";
+
+  return (
+    <button
+      type="button"
+      role="switch"
+      aria-checked={isDark}
+      aria-label={isDark ? "切换到亮色模式" : "切换到暗色模式"}
+      title={isDark ? "切换到亮色模式" : "切换到暗色模式"}
+      data-state={isDark ? "checked" : "unchecked"}
+      onClick={() => setTheme(isDark ? "light" : "dark")}
+      className={cn(
+        "peer relative inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full transition-colors duration-200",
+        "shadow-[inset_0_0_0_1px_rgba(0,0,0,0.04),inset_0_1px_2px_rgba(0,0,0,0.06)]",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+        isDark
+          ? "bg-slate-700 hover:bg-slate-600"
+          : "bg-sky-200 hover:bg-sky-300",
+      )}
+    >
+      <span
+        aria-hidden
+        className={cn(
+          "pointer-events-none flex h-5 w-5 items-center justify-center rounded-full bg-white transition-transform duration-200",
+          "shadow-[0_1px_2px_rgba(0,0,0,0.1),0_2px_6px_rgba(0,0,0,0.15)] ring-1 ring-black/5",
+          "ease-[cubic-bezier(0.34,1.56,0.64,1)]",
+          isDark ? "translate-x-5" : "translate-x-0.5",
+        )}
+      >
+        {isDark ? (
+          <Moon className="h-3 w-3 text-slate-700" />
+        ) : (
+          <Sun className="h-3 w-3 text-amber-500" />
+        )}
+      </span>
+    </button>
+  );
+}

package/dist/dashboard-runtime/dashboard/src/components/retrieval/retrieval-params-fields.tsx

@@ -1,10 +1,12 @@
 "use client";
 
+import { useEffect, useRef } from "react";
 import type { UseFormReturn } from "react-hook-form";
 import { Check, ChevronDown, HelpCircle, Info } from "lucide-react";
 
 import { Input } from "@/components/ui/input";
 import { Button } from "@/components/ui/button";
+import { useSubspaceOptional } from "@/contexts/subspace-context";
 import {
   FormControl,
   FormField,
@@ -71,6 +73,21 @@ export function RetrievalParamsFields({
     !!currentSearchType?.includes("FULL_TEXT");
   const metadataFields = knowledgeBase?.metadata ?? [];
 
+  // Pre-fill the subspace field with the active scope, but only once per
+  // distinct activeSubspace value so that an intentional user clear sticks.
+  const activeSubspace = useSubspaceOptional()?.subspace ?? null;
+  const prefilledForRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!knowledgeBase?.subspace || !activeSubspace) return;
+    if (prefilledForRef.current === activeSubspace) return;
+    const current = (form.getValues("subspace") as string[] | undefined) ?? [];
+    if (current.length === 0) {
+      form.setValue("subspace", [activeSubspace], { shouldDirty: false });
+    }
+    prefilledForRef.current = activeSubspace;
+  }, [activeSubspace, knowledgeBase?.subspace, form]);
+
   return (
     <>
       {/* Subspace: only meaningful for KBs that opted into subspace isolation. */}

package/dist/dashboard-runtime/dashboard/src/contexts/subspace-context.tsx

@@ -0,0 +1,128 @@
+'use client';
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  type ReactNode,
+} from "react";
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import {
+  clearActiveSubspace,
+  getActiveSubspace,
+  setActiveSubspace,
+  useSubspaceHistory,
+} from "@/hooks/use-subspace-history";
+
+export interface SubspaceContextValue {
+  subspace: string | null;
+  setSubspace: (subspace: string) => void;
+  clearSubspace: () => void;
+  history: string[];
+  addToHistory: (subspace: string) => void;
+}
+
+export const SubspaceContext = createContext<SubspaceContextValue | null>(null);
+
+/**
+ * Strict accessor — throws when called outside of a SubspaceProvider. Use this
+ * inside subtrees that always sit under the provider (e.g. DocumentsClient).
+ */
+export function useSubspace(): SubspaceContextValue {
+  const context = useContext(SubspaceContext);
+  if (!context) {
+    throw new Error("useSubspace must be used within a SubspaceProvider");
+  }
+  return context;
+}
+
+/**
+ * Optional accessor — returns null when no SubspaceProvider is mounted. Use
+ * this in components that may render both inside and outside the KB detail
+ * layout (e.g. KBHeader, which is also used on the KB list page).
+ */
+export function useSubspaceOptional(): SubspaceContextValue | null {
+  return useContext(SubspaceContext);
+}
+
+interface SubspaceProviderProps {
+  knowledgeBaseName: string;
+  children: ReactNode;
+}
+
+/**
+ * Subspace state container backed by the URL as the single source of truth.
+ * The `?subspace=` query parameter drives every read; writes only call
+ * router.replace and let the URL change propagate. A per-tab sessionStorage
+ * preference is replayed into the URL once on mount so revisiting the page
+ * without a query string still lands on the previously chosen scope.
+ */
+export function SubspaceProvider({
+  knowledgeBaseName,
+  children,
+}: SubspaceProviderProps) {
+  const searchParams = useSearchParams();
+  const searchParamsKey = searchParams.toString();
+  const pathname = usePathname();
+  const router = useRouter();
+  const { history, addToHistory } = useSubspaceHistory(knowledgeBaseName);
+
+  // URL is the single source of truth — derive directly, no local state.
+  const subspace = searchParams.get("subspace");
+
+  // One-shot mount-time sticky hydration: when arriving without a query
+  // param but a per-tab session preference exists, replay it into the URL.
+  // After this single redirect every read flows through URL again, so a
+  // later clearSubspace() cannot be undone by re-running this effect.
+  const hydratedRef = useRef(false);
+  useEffect(() => {
+    if (hydratedRef.current) return;
+    hydratedRef.current = true;
+    if (subspace) return;
+    const stored = getActiveSubspace(knowledgeBaseName);
+    if (!stored) return;
+    const params = new URLSearchParams(searchParamsKey);
+    params.set("subspace", stored);
+    router.replace(`${pathname}?${params.toString()}`);
+  }, [knowledgeBaseName, subspace, searchParamsKey, pathname, router]);
+
+  // Side effects follow the URL: persist to sessionStorage and history
+  // whenever the active scope changes. Centralising the writes here means
+  // setSubspace / clearSubspace stay tiny and free of race conditions.
+  useEffect(() => {
+    if (!subspace) {
+      clearActiveSubspace(knowledgeBaseName);
+      return;
+    }
+    setActiveSubspace(knowledgeBaseName, subspace);
+    addToHistory(subspace);
+  }, [subspace, knowledgeBaseName, addToHistory]);
+
+  const setSubspace = useCallback(
+    (next: string) => {
+      const trimmed = next.trim();
+      if (!trimmed) return;
+      const params = new URLSearchParams(searchParamsKey);
+      params.set("subspace", trimmed);
+      router.replace(`${pathname}?${params.toString()}`);
+    },
+    [searchParamsKey, pathname, router],
+  );
+
+  const clearSubspace = useCallback(() => {
+    const params = new URLSearchParams(searchParamsKey);
+    params.delete("subspace");
+    const query = params.toString();
+    router.replace(query ? `${pathname}?${query}` : pathname);
+  }, [searchParamsKey, pathname, router]);
+
+  return (
+    <SubspaceContext.Provider
+      value={{ subspace, setSubspace, clearSubspace, history, addToHistory }}
+    >
+      {children}
+    </SubspaceContext.Provider>
+  );
+}

package/dist/dashboard-runtime/dashboard/src/hooks/use-documents.ts

@@ -1,11 +1,27 @@
 import { useQuery } from "@tanstack/react-query";
 import { listDocuments } from "@/services/documents";
 
-export function useDocuments(knowledgeBaseName: string, nextToken?: string, maxResults: number = 20) {
+export function useDocuments(
+  knowledgeBaseName: string,
+  options?: {
+    nextToken?: string;
+    maxResults?: number;
+    subspace?: string;
+    enabled?: boolean;
+  },
+) {
+  const { nextToken, maxResults = 20, subspace, enabled = true } = options ?? {};
   return useQuery({
-    queryKey: ["knowledge-bases", knowledgeBaseName, "documents", nextToken, maxResults],
-    queryFn: () => listDocuments(knowledgeBaseName, { maxResults, nextToken }),
-    enabled: !!knowledgeBaseName,
+    queryKey: [
+      "knowledge-bases",
+      knowledgeBaseName,
+      "documents",
+      nextToken,
+      maxResults,
+      subspace,
+    ],
+    queryFn: () => listDocuments(knowledgeBaseName, { maxResults, nextToken, subspace }),
+    enabled: !!knowledgeBaseName && enabled,
     staleTime: 30_000,
   });
 }