@tablestore/tablestore-agent-cli 0.2.1 → 0.2.4

package/dist/dashboard-runtime/dashboard/src/components/retrieval/retrieval-form.tsx

@@ -3,7 +3,7 @@
 import { useRef, useState } from "react";
 import { useForm } from "react-hook-form";
 import { zodResolver } from "@hookform/resolvers/zod";
-import { Check, Code2, Copy, Search } from "lucide-react";
+import { Check, Code2, Copy, ImageIcon, Search, Upload, X } from "lucide-react";
 import { toast } from "sonner";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
@@ -26,12 +26,13 @@ import {
   TooltipProvider,
   TooltipTrigger,
 } from "@/components/ui/tooltip";
+import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
 import { type FilterBuilderHandle } from "./filter-builder";
 import { RetrievalParamsFields } from "./retrieval-params-fields";
 import { assembleRetrievalConfiguration } from "./assemble-retrieval-configuration";
 import { retrievalSchema, type RetrievalInput } from "@/schemas/retrieval";
 import type { KnowledgeBase } from "@/types/knowledge-base";
-import type { RetrievalRequest } from "@/types/retrieval";
+import type { RetrievalQuery, RetrievalRequest } from "@/types/retrieval";
 
 interface RetrievalFormProps {
   knowledgeBaseName: string;
@@ -59,9 +60,18 @@ export function assembleRetrievalRequest(
   const config = assembleRetrievalConfiguration(v, undefined) ?? {};
   if (filter) config.filter = filter;
 
+  const retrievalQuery: RetrievalQuery =
+    v.queryType === "IMAGE" && v.imageInput
+      ? {
+          type: "IMAGE" as const,
+          imageBase64: v.imageInput,
+          ...(v.query ? { text: v.query } : {}),
+        }
+      : { type: "TEXT" as const, text: v.query ?? "" };
+
   const req: RetrievalRequest = {
     knowledgeBaseName,
-    retrievalQuery: { type: "TEXT", text: v.query ?? "" },
+    retrievalQuery,
   };
   if (v.subspace?.length) req.subspace = v.subspace;
   if (Object.keys(config).length > 0) req.retrievalConfiguration = config;
@@ -100,7 +110,9 @@ export function retrievalDefaultsFromKB(
 
   return {
     knowledgeBaseName,
+    queryType: "TEXT" as const,
     query: "",
+    imageInput: "",
     subspace: [],
     topK: kbRerankTopK,
     denseTopK: kbDenseTopK,
@@ -214,6 +226,9 @@ export function RetrievalForm({
   isLoading,
 }: RetrievalFormProps) {
   const filterRef = useRef<FilterBuilderHandle>(null);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [fileName, setFileName] = useState("");
+  const [isDragging, setIsDragging] = useState(false);
 
   const form = useForm<RetrievalInput>({
     resolver: zodResolver(retrievalSchema),
@@ -234,6 +249,12 @@ export function RetrievalForm({
     return assembleRetrievalRequest(knowledgeBaseName, values, filter) as unknown as Record<string, unknown>;
   };
 
+  const isMultimodal = knowledgeBase?.multimodal === true;
+  const queryType = form.watch("queryType") ?? "TEXT";
+
+  // Force TEXT mode for non-multimodal KBs
+  const effectiveQueryType = isMultimodal ? queryType : "TEXT";
+
   return (
     <Form {...form}>
       <form
@@ -245,27 +266,223 @@ export function RetrievalForm({
           <RequestPreviewButton buildRequestJson={buildRequestJson} />
         </div>
 
-        <FormField
-          control={form.control}
-          name="query"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>查询内容</FormLabel>
-              <FormControl>
-                <div className="relative">
-                  <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-[hsl(var(--muted-foreground))]" />
-                  <Input
-                    placeholder="输入检索查询..."
-                    className="pl-9"
-                    maxLength={128}
-                    {...field}
-                  />
-                </div>
-              </FormControl>
-              <FormMessage />
-            </FormItem>
-          )}
-        />
+        {isMultimodal && (
+          <FormField
+            control={form.control}
+            name="queryType"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>查询类型</FormLabel>
+                <FormControl>
+                  <ToggleGroup
+                    type="single"
+                    value={field.value ?? "TEXT"}
+                    onValueChange={(v) => {
+                      if (v && v !== field.value) {
+                        field.onChange(v);
+                        // Clear both inputs on type switch to avoid stale values
+                        form.setValue("query", "");
+                        form.setValue("imageInput", "");
+                      }
+                    }}
+                    className="grid w-full grid-cols-2 gap-0 overflow-hidden rounded-lg border border-border bg-[hsl(var(--muted)/0.4)] p-0 sm:max-w-md"
+                  >
+                    <ToggleGroupItem value="TEXT" className="h-9">
+                      TEXT
+                    </ToggleGroupItem>
+                    <ToggleGroupItem value="IMAGE" className="h-9">
+                      IMAGE
+                    </ToggleGroupItem>
+                  </ToggleGroup>
+                </FormControl>
+              </FormItem>
+            )}
+          />
+        )}
+
+        {effectiveQueryType === "TEXT" ? (
+          <FormField
+            control={form.control}
+            name="query"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>查询内容</FormLabel>
+                <FormControl>
+                  <div className="relative">
+                    <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-[hsl(var(--muted-foreground))]" />
+                    <Input
+                      placeholder="输入检索查询..."
+                      className="pl-9"
+                      maxLength={128}
+                      {...field}
+                    />
+                  </div>
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+        ) : (
+          <>
+            {/* Image file upload */}
+            <FormField
+              control={form.control}
+              name="imageInput"
+              render={({ field }) => {
+                const acceptedTypes = ["image/jpeg", "image/png", "image/webp", "image/bmp", "image/tiff"];
+
+                const handleFile = (file: File) => {
+                  if (!acceptedTypes.includes(file.type)) {
+                    toast.error("不支持的图片格式，请选择 JPG/PNG/WebP/BMP/TIFF 格式");
+                    return;
+                  }
+                  const reader = new FileReader();
+                  reader.onload = () => {
+                    field.onChange(reader.result as string);
+                    setFileName(file.name || "pasted-image");
+                  };
+                  reader.onerror = () => {
+                    toast.error("图片读取失败，请重试");
+                  };
+                  reader.readAsDataURL(file);
+                };
+
+                const handleRemove = () => {
+                  field.onChange("");
+                  setFileName("");
+                  if (fileInputRef.current) {
+                    fileInputRef.current.value = "";
+                  }
+                };
+
+                const handlePaste = (e: React.ClipboardEvent) => {
+                  const items = e.clipboardData?.items;
+                  if (!items) return;
+
+                  for (const item of Array.from(items)) {
+                    if (item.type.startsWith("image/")) {
+                      e.preventDefault();
+                      const file = item.getAsFile();
+                      if (file) handleFile(file);
+                      return;
+                    }
+                  }
+                };
+
+                return (
+                  <FormItem>
+                    <FormLabel>图片输入</FormLabel>
+                    <FormControl>
+                      <div
+                        key={queryType}
+                        onPaste={handlePaste}
+                        tabIndex={0}
+                        className="outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 rounded-md"
+                      >
+                        <input
+                          ref={fileInputRef}
+                          type="file"
+                          accept="image/jpeg,image/png,image/webp,image/bmp,image/tiff"
+                          className="hidden"
+                          onChange={(e) => {
+                            const file = e.target.files?.[0];
+                            if (file) handleFile(file);
+                          }}
+                        />
+
+                        {!field.value ? (
+                          <div
+                            onClick={() => fileInputRef.current?.click()}
+                            onDragOver={(e) => {
+                              e.preventDefault();
+                              setIsDragging(true);
+                            }}
+                            onDragLeave={() => setIsDragging(false)}
+                            onDrop={(e) => {
+                              e.preventDefault();
+                              setIsDragging(false);
+                              const file = e.dataTransfer.files[0];
+                              if (file) handleFile(file);
+                            }}
+                            className={`border-2 border-dashed rounded-lg p-8 flex flex-col items-center gap-3 cursor-pointer transition-colors ${
+                              isDragging
+                                ? "border-primary bg-accent/50"
+                                : "border-border hover:border-primary/50 hover:bg-accent/50"
+                            }`}
+                          >
+                            <Upload className="w-8 h-8 text-muted-foreground" />
+                            <p className="text-sm text-muted-foreground">
+                              点击、拖拽或粘贴图片到此处
+                            </p>
+                            <p className="text-xs text-muted-foreground/70">
+                              支持 JPG/PNG/WebP/BMP/TIFF
+                            </p>
+                          </div>
+                        ) : (
+                          /* 已选择态 - 悬停遮罩式 */
+                          <div className="group border border-border rounded-md overflow-hidden">
+                            {/* 图片预览区域 */}
+                            <div className="relative flex justify-center bg-muted/30 p-3">
+                              <img
+                                src={field.value}
+                                alt="已选择的图片预览"
+                                className="max-h-[200px] max-w-full rounded object-contain"
+                              />
+                              {/* 悬停遮罩 + 操作按钮 */}
+                              <div className="absolute inset-0 bg-black/40 opacity-0 group-hover:opacity-100 transition-opacity flex items-center justify-center gap-3">
+                                <button
+                                  type="button"
+                                  onClick={() => fileInputRef.current?.click()}
+                                  className="px-3 py-1.5 rounded bg-white/90 text-sm font-medium text-foreground hover:bg-white flex items-center gap-1.5"
+                                >
+                                  <Upload className="w-3.5 h-3.5" />
+                                  重新选择
+                                </button>
+                                <button
+                                  type="button"
+                                  onClick={handleRemove}
+                                  className="px-3 py-1.5 rounded bg-white/90 text-sm font-medium text-destructive hover:bg-white flex items-center gap-1.5"
+                                >
+                                  <X className="w-3.5 h-3.5" />
+                                  删除
+                                </button>
+                              </div>
+                            </div>
+                            {/* 底部文件信息栏 */}
+                            <div className="px-3 py-2 border-t border-border flex items-center gap-2 text-sm text-muted-foreground">
+                              <ImageIcon className="w-3.5 h-3.5" />
+                              <span className="truncate">{fileName}</span>
+                            </div>
+                          </div>
+                        )}
+                      </div>
+                    </FormControl>
+                    <FormMessage />
+                  </FormItem>
+                );
+              }}
+            />
+
+            {/* Supplementary text */}
+            <FormField
+              control={form.control}
+              name="query"
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel>补充文本（可选）</FormLabel>
+                  <FormControl>
+                    <Input
+                      placeholder="补充文本描述..."
+                      maxLength={128}
+                      {...field}
+                    />
+                  </FormControl>
+                  <FormMessage />
+                </FormItem>
+              )}
+            />
+          </>
+        )}
 
         <RetrievalParamsFields
           form={form}

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

@@ -175,6 +175,7 @@ const PROVIDER_OPTIONS: { value: string; label: string }[] = [
 const BAILIAN_MODEL_OPTIONS: { value: string; label: string }[] = [
   { value: "gte-rerank-v2", label: "gte-rerank-v2" },
   { value: "qwen3-rerank", label: "qwen3-rerank" },
+  { value: "qwen3-vl-rerank", label: "qwen3-vl-rerank (多模态)" },
 ];
 
 function ModelFields({ form }: { form: UseFormReturn<RetrievalInput> }) {

package/dist/dashboard-runtime/dashboard/src/components/retrieval/retrieval-result-card.tsx

@@ -1,6 +1,9 @@
+import { useState } from "react";
 import { Card, CardContent } from "@/components/ui/card";
 import { Badge } from "@/components/ui/badge";
+import { Dialog, DialogContent, DialogTitle } from "@/components/ui/dialog";
 import type { RetrievalResult } from "@/types/retrieval";
+import { IMAGE_FALLBACK_DATA_PREFIX } from "@/lib/constants";
 
 interface RetrievalResultCardProps {
   result: RetrievalResult;
@@ -8,12 +11,24 @@ interface RetrievalResultCardProps {
 }
 
 export function RetrievalResultCard({ result, rank }: RetrievalResultCardProps) {
+  const [zoomedImage, setZoomedImage] = useState<string | null>(null);
   const fileName = result.ossKey?.split("/").pop() || result.ossKey || "未知文件";
 
+  const isImageChunk = result.chunkType?.toLowerCase() === "image";
+  const chunkBadgeVariant = isImageChunk ? "default" : "secondary";
+
+  // 当后端只返回裸 base64（无 data URL 前缀）时，补充通用 MIME 兜底。
+  // 浏览器会按内容嗅探解码，这里只需是合法 image/* 类型以避免 CSP 拒绝渲染。
+  const imageSrc = result.imageBase64
+    ? result.imageBase64.startsWith("data:")
+      ? result.imageBase64
+      : `${IMAGE_FALLBACK_DATA_PREFIX}${result.imageBase64}`
+    : undefined;
+
   return (
     <Card className="transition-shadow hover:shadow-sm">
       <CardContent className="p-4 space-y-3">
-        {/* 头部: 排名 + Score */}
+        {/* 头部: 排名 + Score + chunkType */}
         <div className="flex items-center justify-between">
           <div className="flex items-center gap-2">
             <span className="flex h-6 w-6 items-center justify-center rounded-full bg-[hsl(var(--primary-50))] text-xs font-semibold text-primary">
@@ -22,6 +37,11 @@ export function RetrievalResultCard({ result, rank }: RetrievalResultCardProps)
             <Badge variant="outline" className="font-mono text-xs">
               {result.score.toFixed(4)}
             </Badge>
+            {result.chunkType && (
+              <Badge variant={chunkBadgeVariant} className="text-xs">
+                {result.chunkType.toUpperCase()}
+              </Badge>
+            )}
           </div>
           {result.subspace && (
             <Badge variant="secondary" className="text-xs">
@@ -37,9 +57,23 @@ export function RetrievalResultCard({ result, rank }: RetrievalResultCardProps)
         </div>
 
         {/* 内容片段 */}
-        <p className="text-sm leading-relaxed text-foreground/90 whitespace-pre-wrap line-clamp-6">
-          {result.content}
-        </p>
+        {isImageChunk && result.imageBase64 && imageSrc && (
+          <img
+            src={imageSrc}
+            alt="检索结果图片"
+            className="max-w-[200px] rounded-md cursor-pointer hover:opacity-80 transition-opacity"
+            onClick={() => setZoomedImage(imageSrc)}
+          />
+        )}
+        {result.content && (
+          <p
+            className={`leading-relaxed text-foreground/90 whitespace-pre-wrap ${
+              isImageChunk ? "text-xs" : "text-sm line-clamp-6"
+            }`}
+          >
+            {result.content}
+          </p>
+        )}
 
         {/* Metadata */}
         {result.metadata && Object.keys(result.metadata).length > 0 && (
@@ -56,6 +90,20 @@ export function RetrievalResultCard({ result, rank }: RetrievalResultCardProps)
           </div>
         )}
       </CardContent>
+
+      {/* 图片放大预览 */}
+      <Dialog open={!!zoomedImage} onOpenChange={() => setZoomedImage(null)}>
+        <DialogContent className="max-w-[90vw] max-h-[90vh] p-2 flex items-center justify-center border-none bg-black/90 data-[state=open]:animate-none data-[state=closed]:animate-none duration-0">
+          <DialogTitle className="sr-only">图片放大预览</DialogTitle>
+          {zoomedImage && (
+            <img
+              src={zoomedImage}
+              alt="放大预览"
+              className="max-w-full max-h-[85vh] object-contain"
+            />
+          )}
+        </DialogContent>
+      </Dialog>
     </Card>
   );
 }

package/dist/dashboard-runtime/dashboard/src/components/shared/metadata-field-input.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+import { Input } from "@/components/ui/input";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import type { MetadataField } from "@/types/knowledge-base";
+
+interface MetadataFieldInputProps {
+  field: MetadataField;
+  value: string;
+  onChange: (next: string) => void;
+}
+
+/**
+ * Controlled input for a single KB metadata schema field. Empty string means
+ * "field unset" — the parent form's converter skips empty values when
+ * building the request payload.
+ */
+export function MetadataFieldInput({
+  field,
+  value,
+  onChange,
+}: MetadataFieldInputProps) {
+  if (field.type === "boolean") {
+    return (
+      <Select value={value} onValueChange={onChange}>
+        <SelectTrigger>
+          <SelectValue placeholder="不设置" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="true">true</SelectItem>
+          <SelectItem value="false">false</SelectItem>
+        </SelectContent>
+      </Select>
+    );
+  }
+
+  const isList = field.type.endsWith("_list");
+  const isNumber = field.type === "long" || field.type === "double";
+
+  return (
+    <Input
+      type={isNumber ? "number" : field.type === "date" ? "date" : "text"}
+      placeholder={isList ? "值1, 值2, 值3" : isNumber ? "输入数字" : "输入值"}
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+    />
+  );
+}

package/dist/dashboard-runtime/dashboard/src/components/shared/status-badge.tsx

@@ -8,12 +8,17 @@ interface StatusBadgeProps {
   label?: string;
 }
 
+// Both `success` / `success-soft` (and friends) are registered in
+// tailwind.config.ts and back themselves with HSL CSS variables that
+// already swap inside the `.dark` selector in globals.css, so a single
+// utility class covers both themes. Adding a separate `dark:bg-*`
+// override here would actually clobber the soft token in dark mode.
 const STATUS_CLASS_MAP: Record<BadgeStatus, string> = {
-  completed: "bg-green-100 text-green-700 dark:bg-green-900/30 dark:text-green-400",
-  pending:   "bg-amber-100 text-amber-700 dark:bg-amber-900/30 dark:text-amber-400",
-  indexing:  "bg-blue-100 text-blue-700 dark:bg-blue-900/30 dark:text-blue-400",
-  failed:    "bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400",
-  deleting:  "bg-amber-100 text-amber-700 dark:bg-amber-900/30 dark:text-amber-400",
+  completed: "bg-success-soft text-success",
+  pending:   "bg-warning-soft text-warning",
+  indexing:  "bg-info-soft text-info",
+  failed:    "bg-danger-soft text-danger",
+  deleting:  "bg-warning-soft text-warning",
 };
 
 const STATUS_LABEL_MAP: Record<BadgeStatus, string> = {

package/dist/dashboard-runtime/dashboard/src/components/ui/nav-tab-bar.tsx

@@ -6,7 +6,7 @@ import { usePathname } from "next/navigation"
 
 import { cn } from "@/lib/utils"
 
-interface NavTabBarProps extends React.HTMLAttributes<HTMLDivElement> {}
+type NavTabBarProps = React.HTMLAttributes<HTMLDivElement>;
 
 export function NavTabBar({ className, children, ...props }: NavTabBarProps) {
   return (

package/dist/dashboard-runtime/dashboard/src/hooks/use-chat-history.ts

@@ -2,6 +2,7 @@
 
 import { useCallback, useMemo, useSyncExternalStore } from "react";
 
+import { newId } from "@/lib/random-id";
 import type { ChatMessage } from "@/types/llm-chat";
 
 /** Legacy global key kept for read-only migration. */
@@ -31,15 +32,17 @@ const TITLE_MAX_LENGTH = 24;
  * the exact retrieval setup the user had. Kept structural (not depending on
  * the context module) so this hook remains free of UI layer imports.
  *
- * NOTE: previous versions of this schema carried `retrievalConfiguration` and
- * `topK` on each mount; both fields were dropped in favour of a single
- * session-wide retrieval config, because per-mount scoring makes the global
- * aggregate ranking meaningless. The read path tolerates and migrates legacy
- * entries silently. */
+ * Per-KB `retrieval` / `topK` 为可选 override：留空则在请求组装阶段继承会话级
+ * 全局参数，单 KB 自定义并不会破坏跨 KB 排序——上层在合并前就已经按 KB 各自
+ * 的配置打分，再由聚合 topK 统一截断。 */
 export interface ChatSessionMount {
   id: string;
   knowledgeBaseName: string;
   subspace?: string[];
+  /** Per-mount retrieval override; falls back to session-wide config when omitted. */
+  retrieval?: ChatRetrievalConfig;
+  /** Per-mount per-KB topK override; falls back to session-wide perKbTopK when omitted. */
+  topK?: number;
 }
 
 /** Flat retrieval configuration that mirrors a subset of `RetrievalInput`.
@@ -57,6 +60,21 @@ export interface ChatRetrievalConfig {
   modelProvider?: string;
 }
 
+export interface ChatSessionMemoryScope {
+  appId: string;
+  tenantId: string;
+  agentId: string;
+  runId: string;
+}
+
+export interface ChatSessionMemoryBinding {
+  id: string;
+  memoryStoreName: string;
+  scope: ChatSessionMemoryScope;
+  topK?: number;
+  autoSave: boolean;
+}
+
 export interface ChatSessionConfig {
   providerId?: string;
   model?: string;
@@ -69,6 +87,7 @@ export interface ChatSessionConfig {
   /** Session-wide retrieval params shared by every mounted KB. */
   retrieval?: ChatRetrievalConfig;
   mounts: ChatSessionMount[];
+  memory?: ChatSessionMemoryBinding;
 }
 
 export interface ChatSession {
@@ -133,11 +152,47 @@ function sanitizeSessions(parsed: unknown): ChatSession[] {
         id: m.id,
         knowledgeBaseName: m.knowledgeBaseName,
         ...(m.subspace && m.subspace.length ? { subspace: m.subspace } : {}),
+        ...(m.retrieval ? { retrieval: m.retrieval } : {}),
+        ...(typeof m.topK === "number" ? { topK: m.topK } : {}),
       })),
+      memory: sanitizeMemoryBinding(s.config?.memory),
     },
   }));
 }
 
+function sanitizeMemoryBinding(
+  raw: unknown,
+): ChatSessionMemoryBinding | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const r = raw as Partial<ChatSessionMemoryBinding>;
+  if (typeof r.memoryStoreName !== "string" || !r.memoryStoreName) return undefined;
+  const s = r.scope;
+  if (
+    !s ||
+    typeof s.appId !== "string" ||
+    typeof s.tenantId !== "string" ||
+    typeof s.agentId !== "string" ||
+    typeof s.runId !== "string" ||
+    !s.appId ||
+    !s.tenantId ||
+    !s.agentId ||
+    !s.runId
+  ) {
+    return undefined;
+  }
+  return {
+    // 兜底分支只服务于"老快照 / 被手动改坏的数据"。正常路径的 binding 由 reducer
+    // 在 SET_MEMORY 时就铸了稳定 id；这里 newId() 每次重生属于可接受代价。
+    id: typeof r.id === "string" && r.id ? r.id : newId("memory"),
+    memoryStoreName: r.memoryStoreName,
+    scope: { appId: s.appId, tenantId: s.tenantId, agentId: s.agentId, runId: s.runId },
+    ...(Number.isInteger(r.topK) && (r.topK as number) > 0
+      ? { topK: r.topK as number }
+      : {}),
+    autoSave: r.autoSave !== false,
+  };
+}
+
 function readStorageKey(storageKey: string): ChatSession[] {
   if (typeof window === "undefined") return [];
   try {

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

@@ -0,0 +1,29 @@
+import { useQuery } from "@tanstack/react-query";
+import { getDocument } from "@/services/documents";
+import { queryKeys } from "@/lib/query-keys";
+import { useRuntimeContext } from "@/providers/runtime-context-provider";
+
+/**
+ * Fetch a single document via DescribeDocument. The list endpoint omits the
+ * `metadata` field, so anything that needs to render or edit metadata must
+ * use this hook rather than reading from the listDocuments cache.
+ */
+export function useDocument(
+  knowledgeBaseName: string,
+  docId: string | null | undefined,
+  options?: { subspace?: string; enabled?: boolean },
+) {
+  const { context, ready } = useRuntimeContext();
+  const { subspace, enabled = true } = options ?? {};
+  return useQuery({
+    queryKey: queryKeys.document(
+      context.dataScopeKey,
+      knowledgeBaseName,
+      docId,
+      subspace,
+    ),
+    queryFn: () => getDocument(knowledgeBaseName, docId as string, { subspace }),
+    enabled: ready && !!knowledgeBaseName && !!docId && enabled,
+    staleTime: 30_000,
+  });
+}