@tablestore/tablestore-agent-cli 0.2.3 → 0.2.4

package/dist/dashboard-runtime/dashboard/src/components/chat/mount-retrieval-dialog.tsx

@@ -0,0 +1,360 @@
+"use client";
+
+import { useEffect, useMemo, useRef } from "react";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { Info, RotateCcw, Pencil } from "lucide-react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Form } from "@/components/ui/form";
+import type { FilterBuilderHandle } from "@/components/retrieval/filter-builder";
+import { RetrievalParamsFields } from "@/components/retrieval/retrieval-params-fields";
+import { retrievalSchema, type RetrievalInput } from "@/schemas/retrieval";
+import {
+  DEFAULT_PER_KB_TOP_K,
+  useChatConfig,
+  type MountItem,
+} from "@/components/chat/chat-config-context";
+import type { ChatRetrievalConfig } from "@/hooks/use-chat-history";
+import type { KnowledgeBase } from "@/types/knowledge-base";
+
+/* -------------------------------------------------------------------------- */
+/* Pure helpers (also unit-tested in __tests__/mount-retrieval-dialog.test.tsx)
+/* -------------------------------------------------------------------------- */
+
+/** A mount is in "inherit-from-global" mode iff it has no per-KB override at all. */
+export function isInheritMode(mount: MountItem): boolean {
+  return mount.retrieval === undefined && mount.topK === undefined;
+}
+
+/**
+ * Compute the initial form snapshot when the user explicitly switches the
+ * mount from inherit-mode to custom-mode. Mount-local override (when present)
+ * wins over the global session defaults; otherwise the global defaults are
+ * shallow-copied so subsequent form mutation cannot leak back into the
+ * shared `cfg.retrieval` reference.
+ */
+export function deriveCustomDefaults(
+  mount: MountItem,
+  globalRetrieval: ChatRetrievalConfig,
+  globalPerKbTopK: number,
+): { retrieval: ChatRetrievalConfig; topK: number } {
+  return {
+    retrieval: mount.retrieval ?? { ...globalRetrieval },
+    topK: mount.topK ?? globalPerKbTopK,
+  };
+}
+
+/**
+ * Multimodal KBs only have one supported MODEL-rerank model: `qwen3-vl-rerank`
+ * served by the Bailian provider. RRF / WEIGHT remain unrestricted because
+ * they don't load a rerank model at all.
+ */
+export function lockMultimodalRerank(
+  retrieval: ChatRetrievalConfig,
+  isMultimodal: boolean,
+): ChatRetrievalConfig {
+  if (!isMultimodal) return retrieval;
+  if (retrieval.rerankType !== "MODEL") return retrieval;
+  return {
+    ...retrieval,
+    modelProvider: "bailian",
+    modelName: "qwen3-vl-rerank",
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Component                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/** Subset of `RetrievalInput` keys persisted back to a `ChatRetrievalConfig`. */
+const RETRIEVAL_CFG_KEYS = [
+  "searchType",
+  "rerankType",
+  "rrfK",
+  "rrfDenseWeight",
+  "rrfFullTextWeight",
+  "weightDense",
+  "weightFullText",
+  "modelName",
+  "modelProvider",
+] as const satisfies readonly (keyof RetrievalInput &
+  keyof ChatRetrievalConfig)[];
+
+export interface MountRetrievalDialogProps {
+  mount: MountItem;
+  knowledgeBase: KnowledgeBase;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+/**
+ * Per-KB retrieval parameter editor. Opens from the gear icon on a `MountRow`.
+ *
+ * Behavior contract:
+ *   - When `mount.retrieval` and `mount.topK` are both undefined the form
+ *     renders read-only and the header advertises 「当前：继承全局默认」.
+ *     Switching to custom-mode requires an explicit click on
+ *     「使用自定义配置」 — no implicit drift.
+ *   - In custom-mode, the form is seeded from the current global defaults
+ *     (or the existing override) and auto-commits on field blur via
+ *     `cfg.updateMount(...)`.
+ *   - Multimodal KBs lock the MODEL rerank to `qwen3-vl-rerank` via
+ *     `lockMultimodalRerank`; the rest of the form is unconstrained.
+ *   - Metadata FilterBuilder is *not* rendered here (we deliberately skip
+ *     `knowledgeBase` to `RetrievalParamsFields` to suppress it).
+ */
+export function MountRetrievalDialog({
+  mount,
+  knowledgeBase,
+  open,
+  onOpenChange,
+}: MountRetrievalDialogProps) {
+  const cfg = useChatConfig();
+  const inherit = isInheritMode(mount);
+  const isMultimodal = !!knowledgeBase.multimodal;
+
+  // FilterBuilder is structurally required by RetrievalParamsFields' API even
+  // though we don't render it here.
+  const filterRef = useRef<FilterBuilderHandle | null>(null);
+
+  // Effective values used to populate the form: mount override falls back to
+  // the global session defaults so the UI shows what would actually be sent
+  // for this KB even in inherit-mode.
+  const effective = useMemo(
+    () => deriveCustomDefaults(mount, cfg.retrieval, cfg.perKbTopK),
+    [mount, cfg.retrieval, cfg.perKbTopK],
+  );
+
+  const form = useForm<RetrievalInput>({
+    resolver: zodResolver(retrievalSchema),
+    defaultValues: {
+      knowledgeBaseName: knowledgeBase.knowledgeBaseName,
+      queryType: "TEXT" as const,
+      query: "__mount_dialog_placeholder__",
+      subspace: [],
+      topK: effective.topK,
+      searchType: effective.retrieval.searchType ?? ["DENSE_VECTOR", "FULL_TEXT"],
+      rerankType: effective.retrieval.rerankType,
+      rrfK: effective.retrieval.rrfK,
+      rrfDenseWeight: effective.retrieval.rrfDenseWeight,
+      rrfFullTextWeight: effective.retrieval.rrfFullTextWeight,
+      weightDense: effective.retrieval.weightDense,
+      weightFullText: effective.retrieval.weightFullText,
+      modelName: effective.retrieval.modelName,
+      modelProvider: effective.retrieval.modelProvider,
+    },
+  });
+
+  // RHF does not observe defaultValues after mount; mirror context updates
+  // and inherit/custom transitions through reset() so the form always
+  // reflects what would actually be sent.
+  useEffect(() => {
+    form.reset({
+      knowledgeBaseName: knowledgeBase.knowledgeBaseName,
+      queryType: "TEXT" as const,
+      query: "__mount_dialog_placeholder__",
+      subspace: [],
+      topK: effective.topK,
+      searchType: effective.retrieval.searchType ?? ["DENSE_VECTOR", "FULL_TEXT"],
+      rerankType: effective.retrieval.rerankType,
+      rrfK: effective.retrieval.rrfK,
+      rrfDenseWeight: effective.retrieval.rrfDenseWeight,
+      rrfFullTextWeight: effective.retrieval.rrfFullTextWeight,
+      weightDense: effective.retrieval.weightDense,
+      weightFullText: effective.retrieval.weightFullText,
+      modelName: effective.retrieval.modelName,
+      modelProvider: effective.retrieval.modelProvider,
+    });
+    // form is stable; we want this to fire whenever the effective payload
+    // changes, including when the user toggles inherit -> custom.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [effective, knowledgeBase.knowledgeBaseName]);
+
+  // Persist the current form snapshot back to the mount as a custom override.
+  // No-op while we're still in inherit-mode (the form is read-only then).
+  const commit = () => {
+    if (inherit) return;
+    const values = form.getValues();
+    let next: ChatRetrievalConfig = {};
+    for (const k of RETRIEVAL_CFG_KEYS) {
+      const v = values[k];
+      if (v !== undefined && !(Array.isArray(v) && v.length === 0)) {
+        (next as Record<string, unknown>)[k] = v;
+      }
+    }
+    next = lockMultimodalRerank(next, isMultimodal);
+    cfg.updateMount(mount.id, {
+      retrieval: next,
+      topK:
+        typeof values.topK === "number" && values.topK >= 0
+          ? values.topK
+          : DEFAULT_PER_KB_TOP_K,
+    });
+  };
+
+  // When the user switches to MODEL on a multimodal KB, immediately lock the
+  // provider/model. Mirrors the unified-section auto-fill but with the
+  // multimodal constraint applied.
+  const watchedRerank = form.watch("rerankType");
+  useEffect(() => {
+    if (inherit) return;
+    if (watchedRerank !== "MODEL") return;
+    let touched = false;
+    if (isMultimodal) {
+      if (form.getValues("modelProvider") !== "bailian") {
+        form.setValue("modelProvider", "bailian");
+        touched = true;
+      }
+      if (form.getValues("modelName") !== "qwen3-vl-rerank") {
+        form.setValue("modelName", "qwen3-vl-rerank");
+        touched = true;
+      }
+    } else {
+      if (!form.getValues("modelProvider")) {
+        form.setValue("modelProvider", "bailian");
+        touched = true;
+      }
+      if (!form.getValues("modelName")) {
+        form.setValue("modelName", "gte-rerank-v2");
+        touched = true;
+      }
+    }
+    if (touched) commit();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [watchedRerank, isMultimodal, inherit]);
+
+  const handleSwitchToCustom = () => {
+    const seeds = deriveCustomDefaults(mount, cfg.retrieval, cfg.perKbTopK);
+    const sealed = lockMultimodalRerank(seeds.retrieval, isMultimodal);
+    cfg.updateMount(mount.id, { retrieval: sealed, topK: seeds.topK });
+  };
+
+  const handleResetToDefault = () => {
+    cfg.resetMountRetrieval(mount.id);
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent
+        // 项目规范：所有 Dialog 必须禁用全部动画，做到即时显示/隐藏。
+        className="sm:max-w-[560px] max-h-[85vh] overflow-y-auto data-[state=open]:animate-none data-[state=closed]:animate-none duration-0"
+      >
+        <DialogHeader>
+          <DialogTitle className="pr-8">检索参数</DialogTitle>
+          <DialogDescription className="break-all">
+            {knowledgeBase.knowledgeBaseName}
+            {isMultimodal ? (
+              <span className="ml-2 inline-flex items-center rounded bg-[hsl(var(--secondary))] px-1.5 py-0.5 text-[10px] font-medium tracking-wide text-[hsl(var(--secondary-foreground))]">
+                多模态
+              </span>
+            ) : null}
+          </DialogDescription>
+        </DialogHeader>
+
+        <div
+          className={
+            "flex items-start gap-2 rounded-md px-3 py-2 text-xs " +
+            (inherit
+              ? "border border-dashed border-[hsl(var(--border))] bg-[hsl(var(--muted)/0.4)] text-muted-foreground"
+              : "border border-[hsl(var(--primary)/0.3)] bg-[hsl(var(--primary)/0.06)] text-[hsl(var(--foreground))]")
+          }
+        >
+          <Info className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+          <div className="flex-1 leading-relaxed">
+            {inherit ? (
+              <span>
+                当前：<span className="font-medium">继承全局默认</span>
+                ；下方为只读预览。如需偏离全局配置，请点击「使用自定义配置」。
+              </span>
+            ) : (
+              <span>
+                当前：<span className="font-medium">使用自定义配置</span>
+                ；字段失焦后自动保存。
+              </span>
+            )}
+          </div>
+        </div>
+
+        {isMultimodal && !inherit && form.watch("rerankType") === "MODEL" ? (
+          <div className="flex items-start gap-2 rounded-md border border-[hsl(var(--border))] bg-[hsl(var(--muted)/0.5)] px-3 py-2 text-xs text-muted-foreground">
+            <Info className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+            <span>
+              多模态知识库的 Model Rerank 已锁定为{" "}
+              <span className="font-medium text-[hsl(var(--foreground))]">
+                qwen3-vl-rerank
+              </span>
+              （Provider：bailian），暂不支持其他模型。
+            </span>
+          </div>
+        ) : null}
+
+        <Form {...form}>
+          <form
+            onSubmit={(e) => e.preventDefault()}
+            onBlur={commit}
+            // 继承模式：整个表单只读 + 灰态预览。
+            className={
+              "space-y-4 " +
+              (inherit ? "pointer-events-none select-none opacity-60" : "")
+            }
+            aria-disabled={inherit}
+          >
+            <fieldset disabled={inherit} className="space-y-4 contents">
+              <RetrievalParamsFields
+                form={form}
+                // 故意不传 knowledgeBase，避免触发 FilterBuilder。
+                filterRef={filterRef}
+                topKLabel="TopK"
+                topKHint="检索返回条数，不设置则继承全局默认"
+                topKMode="single"
+              />
+            </fieldset>
+          </form>
+        </Form>
+
+        <DialogFooter className="sm:justify-between">
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            onClick={handleResetToDefault}
+            disabled={inherit}
+            className="gap-1.5"
+          >
+            <RotateCcw className="h-3.5 w-3.5" />
+            重置为默认
+          </Button>
+          {inherit ? (
+            <Button
+              type="button"
+              size="sm"
+              onClick={handleSwitchToCustom}
+              className="gap-1.5"
+            >
+              <Pencil className="h-3.5 w-3.5" />
+              使用自定义配置
+            </Button>
+          ) : (
+            <Button
+              type="button"
+              variant="secondary"
+              size="sm"
+              onClick={() => onOpenChange(false)}
+            >
+              完成
+            </Button>
+          )}
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/dist/dashboard-runtime/dashboard/src/components/chat/mount-row.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useState } from "react";
-import { Trash2 } from "lucide-react";
+import { Settings2, Trash2 } from "lucide-react";
 
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
@@ -9,17 +9,25 @@ import {
   useChatConfig,
   type MountItem,
 } from "@/components/chat/chat-config-context";
+import { MountRetrievalDialog } from "./mount-retrieval-dialog";
+import type { KnowledgeBase } from "@/types/knowledge-base";
 
 interface MountRowProps {
   mount: MountItem;
   subspaceEnabled: boolean;
+  /**
+   * 该挂载行对应的 KnowledgeBase 详情。仅用于透传给
+   * `MountRetrievalDialog`，由父组件按需注入；缺省时设置入口被禁用，
+   * 因为 Dialog 渲染依赖 `KnowledgeBase` 上的 `multimodal` / 名称等字段。
+   */
+  knowledgeBase?: KnowledgeBase;
 }
 
 /**
  * Single-line representation of a mounted KB: name + (optional) subspace
- * editor + remove. Retrieval parameters live in the session-wide
- * `UnifiedRetrievalSection`, so this row intentionally has no RHF / rerank
- * knobs.
+ * editor + per-KB retrieval settings + remove. The session-wide defaults
+ * still live in `UnifiedRetrievalSection`; this row exposes the per-KB
+ * override entry via the gear icon (opens `MountRetrievalDialog`).
  *
  * `subspaceEnabled` controls whether the subspace input is shown; when the
  * KB was created without subspace support we hide the input entirely so the
@@ -27,12 +35,21 @@ interface MountRowProps {
  * Any residual `mount.subspace` from prior sessions is left untouched — if
  * it's a non-empty array it still gets sent; in practice this path is cold
  * because a KB's subspace flag is immutable post-creation.
+ *
+ * 当 `mount.retrieval` 存在（即该 KB 已切换为自定义配置）时，齿轮按钮
+ * 右上角显示一个小色点作为视觉提示，便于用户在不打开 Dialog 的情况下
+ * 区分继承全局 / 自定义配置。
  */
-export function MountRow({ mount, subspaceEnabled }: MountRowProps) {
+export function MountRow({
+  mount,
+  subspaceEnabled,
+  knowledgeBase,
+}: MountRowProps) {
   const cfg = useChatConfig();
   const [subspaceText, setSubspaceText] = useState(
     (mount.subspace ?? []).join(", "),
   );
+  const [dialogOpen, setDialogOpen] = useState<boolean>(false);
 
   const commitSubspace = () => {
     const next = subspaceText
@@ -70,6 +87,25 @@ export function MountRow({ mount, subspaceEnabled }: MountRowProps) {
           className="h-8 w-44 text-xs"
         />
       ) : null}
+      <div className="relative">
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          className="h-7 w-7"
+          onClick={() => setDialogOpen(true)}
+          disabled={!knowledgeBase}
+          title={knowledgeBase ? "检索参数" : "知识库信息加载中"}
+        >
+          <Settings2 className="h-3.5 w-3.5 text-muted-foreground" />
+        </Button>
+        {mount.retrieval ? (
+          <span
+            aria-hidden
+            className="pointer-events-none absolute -top-0.5 -right-0.5 h-2 w-2 rounded-full bg-primary"
+          />
+        ) : null}
+      </div>
       <Button
         type="button"
         variant="ghost"
@@ -80,6 +116,14 @@ export function MountRow({ mount, subspaceEnabled }: MountRowProps) {
       >
         <Trash2 className="h-3.5 w-3.5 text-muted-foreground" />
       </Button>
+      {knowledgeBase ? (
+        <MountRetrievalDialog
+          mount={mount}
+          knowledgeBase={knowledgeBase}
+          open={dialogOpen}
+          onOpenChange={setDialogOpen}
+        />
+      ) : null}
     </div>
   );
 }

package/dist/dashboard-runtime/dashboard/src/components/chat/unified-retrieval-section.tsx

@@ -1,10 +1,15 @@
 "use client";
 
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useState } from "react";
 import { useForm } from "react-hook-form";
 import { zodResolver } from "@hookform/resolvers/zod";
-import { Info } from "lucide-react";
+import { ChevronDown, Info } from "lucide-react";
 
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible";
 import { Form } from "@/components/ui/form";
 import { Label } from "@/components/ui/label";
 import type { FilterBuilderHandle } from "@/components/retrieval/filter-builder";
@@ -60,6 +65,7 @@ export function UnifiedRetrievalSection({
       // `knowledgeBaseName` is structurally required by the schema but unused
       // here; a placeholder keeps Zod quiet without leaking into persistence.
       knowledgeBaseName: singleKb?.knowledgeBaseName ?? "__unified__",
+      queryType: "TEXT" as const,
       query: "__unified_placeholder__",
       subspace: [],
       topK: cfg.perKbTopK,
@@ -81,6 +87,7 @@ export function UnifiedRetrievalSection({
   useEffect(() => {
     form.reset({
       knowledgeBaseName: singleKb?.knowledgeBaseName ?? "__unified__",
+      queryType: "TEXT" as const,
       query: "__unified_placeholder__",
       subspace: [],
       topK: cfg.perKbTopK,
@@ -141,44 +148,72 @@ export function UnifiedRetrievalSection({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [rerankType]);
 
+  // 默认折叠：现在的角色从“统一应用”降格为“默认 fallback”，绝大部分
+  // 用户在 KB 自定义参数后无需展开此区域。disabled 状态下隐藏触发器，
+  // 避免用户在没有挂载 KB 时点开一个内容为空的折叠区。
+  const [open, setOpen] = useState(false);
+
   return (
-    <div
+    <Collapsible
+      open={disabled ? false : open}
+      onOpenChange={(next) => {
+        if (disabled) return;
+        setOpen(next);
+      }}
       className={
         "space-y-3 border-t border-[hsl(var(--border))] pt-4" +
         (disabled ? " pointer-events-none opacity-50" : "")
       }
       aria-disabled={disabled}
     >
-      <div>
-        <Label className="text-sm font-medium">统一检索参数</Label>
-        <p className="mt-0.5 text-xs text-muted-foreground">
-          应用到所有挂载 KB 的统一查询配置，保证分数可比；每 KB 单独检索后合并重排
-        </p>
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <Label className="text-sm font-medium">全局默认检索参数</Label>
+          <p className="mt-0.5 text-xs text-muted-foreground">
+            未单独配置的知识库将使用此默认参数
+          </p>
+        </div>
+        {!disabled && (
+          <CollapsibleTrigger
+            type="button"
+            aria-label={open ? "收起全局默认检索参数" : "展开全局默认检索参数"}
+            className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-[hsl(var(--accent))] hover:text-[hsl(var(--accent-foreground))]"
+          >
+            <ChevronDown
+              className={
+                "h-4 w-4 transition-transform duration-150" +
+                (open ? " rotate-180" : "")
+              }
+            />
+          </CollapsibleTrigger>
+        )}
       </div>
 
       {disabled ? (
         <div className="flex items-start gap-2 rounded-md border border-dashed border-[hsl(var(--border))] bg-[hsl(var(--muted)/0.4)] px-3 py-3 text-xs text-muted-foreground">
           <Info className="mt-0.5 h-3.5 w-3.5 shrink-0" />
-          <span>挂载至少一个知识库后即可配置统一检索参数</span>
+          <span>挂载至少一个知识库后即可配置全局默认检索参数</span>
         </div>
       ) : (
-        <Form {...form}>
-          <form
-            onSubmit={(e) => e.preventDefault()}
-            onBlur={commit}
-            className="space-y-4"
-          >
-            <RetrievalParamsFields
-              form={form}
-              knowledgeBase={singleKb}
-              filterRef={filterRef}
-              topKLabel="每 KB topK"
-              topKHint="单库检索条数，默认 20"
-              topKMode="single"
-            />
-          </form>
-        </Form>
+        <CollapsibleContent>
+          <Form {...form}>
+            <form
+              onSubmit={(e) => e.preventDefault()}
+              onBlur={commit}
+              className="space-y-4"
+            >
+              <RetrievalParamsFields
+                form={form}
+                knowledgeBase={singleKb}
+                filterRef={filterRef}
+                topKLabel="TopK"
+                topKHint="单库检索条数，默认 20"
+                topKMode="single"
+              />
+            </form>
+          </Form>
+        </CollapsibleContent>
       )}
-    </div>
+    </Collapsible>
   );
 }