@tablestore/tablestore-agent-cli 0.2.11 → 0.4.0

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

@@ -5,19 +5,30 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import { useI18n } from "@/i18n/i18n-context";
 
 import { streamChat } from "@/services/llm-chat";
-import {
-  loadBrowserFileMemory,
-  searchBrowserFileMemory,
-} from "@/lib/browser-file-memory";
 import { FILEMEM_DEFAULT_RUN_ID } from "@/lib/memory-storage-mode";
 import { newId } from "@/lib/random-id";
 import { devFlag } from "@/lib/dev-flags";
+import {
+  clampWikiEvidence,
+  clampWikiRetrievalError,
+  clampWikiRetrievalGroup,
+  MAX_WIKI_ERRORS,
+  MAX_WIKI_EVIDENCE,
+  MAX_WIKI_GROUPS,
+  MAX_WIKI_SOURCES,
+  normalizeRequiredWikiMetadata,
+} from "@/lib/wiki-metadata-limits";
 import {
   removeAt,
   removePair,
   truncateUpToAndIncluding,
 } from "@/lib/chat-message-ops";
 import type { ChatMessage, ChatRequestBody, ChatRole } from "@/types/llm-chat";
+import type {
+  WikiEvidence,
+  WikiRetrievalError,
+  WikiRetrievalGroup,
+} from "@/types/llm-chat";
 
 /**
  * Token deltas can arrive faster than React can profitably re-render
@@ -60,6 +71,8 @@ export interface UseQaChatOptions {
   rag?: ChatRequestBody["rag"];
   /** 绑定的记忆库写 scope（完整四字段）。undefined ⇒ 该轮不开启记忆。 */
   memory?: ChatRequestBody["memory"];
+  /** 当前 Memory store/scope 下选中的 Wiki。undefined ⇒ 该轮不开启 Wiki 检索。 */
+  wiki?: ChatRequestBody["wiki"];
   /**
    * Invoked after each streaming turn settles (done / error / abort) with the
    * final message list. The chat homepage uses this to upsert the session
@@ -71,22 +84,95 @@ export interface UseQaChatOptions {
 function normalizeMemoryForRequest(
   memory: ChatRequestBody["memory"],
 ): ChatRequestBody["memory"] {
-  if (memory?.storageMode !== "filemem") return memory;
-  return {
+  if (!memory) return undefined;
+  const snapshot = {
     ...memory,
-    scope: { ...memory.scope, runId: FILEMEM_DEFAULT_RUN_ID },
+    scope: {
+      appId: memory.scope.appId,
+      tenantId: memory.scope.tenantId,
+      agentId: memory.scope.agentId,
+      runId: memory.scope.runId,
+    },
+  };
+  if (snapshot.storageMode !== "filemem") return snapshot;
+  return {
+    ...snapshot,
+    scope: { ...snapshot.scope, runId: FILEMEM_DEFAULT_RUN_ID },
     retrievalMode: "local",
   };
 }
 
-/**
- * Compose the wire body sent to `/api/v1/llm/chat` for one turn. Pulled out
- * of `_runAssistantTurn` so it can be unit-tested without spinning up React
- * (the dashboard's vitest config runs in node env, so renderHook is not
- * available). The function MUST stay pure — no refs, no state, no closures
- * over hook-local mutables.
- */
-export function buildChatRequestBody(
+function snapshotWikiBinding(
+  wiki: ChatRequestBody["wiki"],
+): ChatRequestBody["wiki"] {
+  if (!wiki) return undefined;
+  return {
+    memoryStoreName: wiki.memoryStoreName,
+    scope: {
+      appId: wiki.scope.appId,
+      tenantId: wiki.scope.tenantId,
+      agentId: wiki.scope.agentId,
+      runId: wiki.scope.runId,
+    },
+    topK: wiki.topK,
+  };
+}
+
+function memoryWikiIdentityMatches(
+  memory: ChatRequestBody["memory"],
+  wiki: ChatRequestBody["wiki"],
+): boolean {
+  if (!memory || !wiki) return false;
+  return (
+    memory.memoryStoreName === wiki.memoryStoreName &&
+    memory.scope.appId === wiki.scope.appId &&
+    memory.scope.tenantId === wiki.scope.tenantId &&
+    memory.scope.agentId === wiki.scope.agentId &&
+    memory.scope.runId === wiki.scope.runId
+  );
+}
+
+function snapshotRequestBindings(
+  rawMemory: ChatRequestBody["memory"],
+  rawWiki: ChatRequestBody["wiki"],
+) {
+  const rawIdentityMatches = memoryWikiIdentityMatches(rawMemory, rawWiki);
+  const normalizedMemory = normalizeMemoryForRequest(rawMemory);
+  const rawMemorySnapshot = rawMemory
+    ? {
+        ...rawMemory,
+        scope: {
+          appId: rawMemory.scope.appId,
+          tenantId: rawMemory.scope.tenantId,
+          agentId: rawMemory.scope.agentId,
+          runId: rawMemory.scope.runId,
+        },
+      }
+    : undefined;
+  const wireMemory =
+    rawMemory?.storageMode === "filemem" && rawWiki && !rawIdentityMatches
+      ? rawMemorySnapshot
+      : normalizedMemory;
+  const wikiSnapshot = snapshotWikiBinding(rawWiki);
+  const wireWiki =
+    wikiSnapshot &&
+    normalizedMemory?.storageMode === "filemem" &&
+    rawIdentityMatches
+      ? {
+          ...wikiSnapshot,
+          memoryStoreName: normalizedMemory.memoryStoreName,
+          scope: {
+            appId: normalizedMemory.scope.appId,
+            tenantId: normalizedMemory.scope.tenantId,
+            agentId: normalizedMemory.scope.agentId,
+            runId: normalizedMemory.scope.runId,
+          },
+        }
+      : wikiSnapshot;
+  return { normalizedMemory, wireMemory, wireWiki };
+}
+
+function composeChatRequestBody(
   opts: Pick<
     UseQaChatOptions,
     | "activeInstance"
@@ -95,18 +181,13 @@ export function buildChatRequestBody(
     | "systemPrompt"
     | "temperature"
     | "rag"
-    | "memory"
   >,
   historyToSend: Array<{ role: ChatRole; content: string }>,
   turnId: string,
+  memory: ChatRequestBody["memory"],
+  wiki: ChatRequestBody["wiki"],
 ): ChatRequestBody {
-  const normalizedMemory = normalizeMemoryForRequest(opts.memory);
-  const memory = normalizedMemory
-    ? {
-        ...normalizedMemory,
-        turnId,
-      }
-    : undefined;
+  const memoryWithTurn = memory ? { ...memory, turnId } : undefined;
   return {
     activeInstance: opts.activeInstance,
     providerId: opts.providerId,
@@ -115,10 +196,46 @@ export function buildChatRequestBody(
     systemPrompt: opts.systemPrompt,
     temperature: opts.temperature,
     rag: opts.rag,
-    ...(memory ? { memory } : {}),
+    ...(memoryWithTurn ? { memory: memoryWithTurn } : {}),
+    ...(wiki ? { wiki } : {}),
   };
 }
 
+/**
+ * Compose the wire body sent to `/api/v1/llm/chat` for one turn. Pulled out
+ * of `_runAssistantTurn` so it can be unit-tested without spinning up React
+ * (the dashboard's vitest config runs in node env, so renderHook is not
+ * available). The function MUST stay pure — no refs, no state, no closures
+ * over hook-local mutables.
+ */
+export function buildChatRequestBody(
+  opts: Pick<
+    UseQaChatOptions,
+    | "activeInstance"
+    | "providerId"
+    | "model"
+    | "systemPrompt"
+    | "temperature"
+    | "rag"
+    | "memory"
+    | "wiki"
+  >,
+  historyToSend: Array<{ role: ChatRole; content: string }>,
+  turnId: string,
+): ChatRequestBody {
+  const { wireMemory, wireWiki } = snapshotRequestBindings(
+    opts.memory,
+    opts.wiki,
+  );
+  return composeChatRequestBody(
+    opts,
+    historyToSend,
+    turnId,
+    wireMemory,
+    wireWiki,
+  );
+}
+
 type PrepareChatRequestOptions = Pick<
   UseQaChatOptions,
   | "dataScopeKey"
@@ -129,83 +246,191 @@ type PrepareChatRequestOptions = Pick<
   | "temperature"
   | "rag"
   | "memory"
+  | "wiki"
 >;
 
-/** Add browser-only file-memory evidence immediately before opening the SSE. */
-export async function prepareChatRequestBody(
-  opts: PrepareChatRequestOptions,
-  historyToSend: Array<{ role: ChatRole; content: string }>,
-  turnId: string,
-  deps: {
-    loadFileMemory?: typeof loadBrowserFileMemory;
-    searchFileMemory?: typeof searchBrowserFileMemory;
-  } = {},
-): Promise<ChatRequestBody> {
-  const memory = normalizeMemoryForRequest(opts.memory);
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function sanitizeStreamWikiEvidence(raw: unknown): WikiEvidence | null {
+  if (!isRecord(raw)) return null;
+  const value = raw;
+  const wikiName = normalizeRequiredWikiMetadata(value.wikiName);
+  const path = normalizeRequiredWikiMetadata(value.path);
   if (
-    !memory ||
-    (memory.retrievalMode !== "local" && memory.storageMode !== "filemem")
+    typeof value.reference !== "string" ||
+    !/^W[1-6]$/.test(value.reference) ||
+    !wikiName ||
+    !path ||
+    typeof value.truncated !== "boolean" ||
+    !Number.isInteger(value.injectedChars) ||
+    (value.injectedChars as number) < 0 ||
+    (value.injectedChars as number) > 8_000
   ) {
-    return buildChatRequestBody(opts, historyToSend, turnId);
+    return null;
   }
-  const loadFileMemory = deps.loadFileMemory ?? loadBrowserFileMemory;
-  const searchFileMemory = deps.searchFileMemory ?? searchBrowserFileMemory;
-  const loaded = await loadFileMemory({
-    dataScopeKey: opts.dataScopeKey,
-    memoryStoreName: memory.memoryStoreName,
-    scope: memory.scope,
+  return clampWikiEvidence({
+    reference: value.reference as `W${number}`,
+    wikiName,
+    path,
+    ...(typeof value.title === "string" ? { title: value.title } : {}),
+    ...(typeof value.type === "string" ? { type: value.type } : {}),
+    ...(typeof value.description === "string"
+      ? { description: value.description }
+      : {}),
+    ...(typeof value.score === "number" && Number.isFinite(value.score)
+      ? { score: value.score }
+      : {}),
+    ...(Array.isArray(value.sources)
+      ? {
+          sources: value.sources
+            .slice(0, MAX_WIKI_SOURCES)
+            .filter((source): source is string => typeof source === "string"),
+        }
+      : {}),
+    truncated: value.truncated,
+    injectedChars: value.injectedChars as number,
+  });
+}
+
+function sanitizeStreamWikiError(raw: unknown): WikiRetrievalError | null {
+  if (!isRecord(raw)) return null;
+  const value = raw;
+  const code = normalizeRequiredWikiMetadata(value.code);
+  const message = normalizeRequiredWikiMetadata(value.message);
+  if (
+    !code ||
+    !message ||
+    (value.stage !== "validate" &&
+      value.stage !== "search" &&
+      value.stage !== "read" &&
+      value.stage !== "budget")
+  ) {
+    return null;
+  }
+  return clampWikiRetrievalError({
+    code,
+    message,
+    ...(typeof value.requestId === "string"
+      ? { requestId: value.requestId }
+      : {}),
+    ...(typeof value.httpStatus === "number" &&
+    Number.isFinite(value.httpStatus) &&
+    Number.isInteger(value.httpStatus)
+      ? { httpStatus: value.httpStatus }
+      : {}),
+    stage: value.stage,
+    ...(typeof value.path === "string" ? { path: value.path } : {}),
   });
-  const lastUser = [...historyToSend]
-    .reverse()
-    .find((message) => message.role === "user");
-  const search = searchFileMemory({
-    key: loaded.key,
-    query: lastUser?.content ?? "",
-    topK: memory.topK ?? 5,
+}
+
+function sanitizeStreamWikiGroup(raw: unknown): WikiRetrievalGroup | null {
+  if (!isRecord(raw)) return null;
+  const value = raw;
+  const wikiName = normalizeRequiredWikiMetadata(value.wikiName);
+  if (!wikiName || !Array.isArray(value.pages)) {
+    return null;
+  }
+  return clampWikiRetrievalGroup({
+    wikiName,
+    pages: value.pages
+      .slice(0, MAX_WIKI_EVIDENCE)
+      .map(sanitizeStreamWikiEvidence)
+      .filter((page): page is WikiEvidence => page !== null),
+    ...(Array.isArray(value.errors)
+      ? {
+          errors: value.errors
+            .slice(0, MAX_WIKI_ERRORS)
+            .map(sanitizeStreamWikiError)
+            .filter((error): error is WikiRetrievalError => error !== null),
+        }
+      : {}),
   });
-  const files = loaded.files
-    .filter(
-      (file) =>
-        file.rel.length > 0 &&
-        file.rel.length <= 512 &&
-        Number.isSafeInteger(file.size) &&
-        file.size >= 0,
-    )
-    .slice(0, 300);
-  const hits = search.results
-    .filter(
-      (hit) =>
-        hit.text.length > 0 &&
-        hit.source.length > 0 &&
-        hit.source.length <= 512 &&
-        Number.isFinite(hit.score),
-    )
-    .slice(0, 50)
-    .map((hit) => ({
-      ...hit,
-      text: hit.text.slice(0, 4_000),
-      score: Math.max(0, Math.min(1, hit.score)),
-    }));
-  const cacheSummary = {
-    ...loaded.cache,
-    ...(loaded.cache.error
-      ? { error: loaded.cache.error.slice(0, 4_000) }
+}
+
+function sanitizeWikiStartPatch(raw: unknown): Partial<ChatMessage> | null {
+  if (
+    !isRecord(raw) ||
+    raw.type !== "wiki.start" ||
+    typeof raw.query !== "string" ||
+    !Number.isInteger(raw.wikiCount) ||
+    (raw.wikiCount as number) < 1 ||
+    (raw.wikiCount as number) > 10
+  ) {
+    return null;
+  }
+  // Request validation enables exactly one scope-owned Wiki, so zero is not a
+  // legal runtime count even though it would be harmless as display metadata.
+  return {
+    wikiQuery: raw.query,
+    wikiCount: raw.wikiCount as number,
+    wikiRetrievalDone: false,
+  };
+}
+
+function sanitizeWikiDonePatch(
+  raw: unknown,
+  wikiBinding: ChatRequestBody["wiki"],
+): Partial<ChatMessage> | null {
+  if (
+    !isRecord(raw) ||
+    raw.type !== "wiki.done" ||
+    typeof raw.query !== "string" ||
+    !Number.isInteger(raw.totalContextChars) ||
+    (raw.totalContextChars as number) < 0 ||
+    (raw.totalContextChars as number) > 24_000 ||
+    !Array.isArray(raw.pages) ||
+    !Array.isArray(raw.byWiki)
+  ) {
+    return null;
+  }
+  return {
+    wikiQuery: raw.query,
+    wikiRetrievalDone: true,
+    wikiEvidence: raw.pages
+      .slice(0, MAX_WIKI_EVIDENCE)
+      .map(sanitizeStreamWikiEvidence)
+      .filter((page): page is WikiEvidence => page !== null),
+    wikiRetrievalGroups: raw.byWiki
+      .slice(0, MAX_WIKI_GROUPS)
+      .map(sanitizeStreamWikiGroup)
+      .filter((group): group is WikiRetrievalGroup => group !== null),
+    wikiTotalContextChars: raw.totalContextChars as number,
+    ...(wikiBinding
+      ? {
+          wikiMemoryStoreName: wikiBinding.memoryStoreName,
+          wikiScope: {
+            appId: wikiBinding.scope.appId,
+            tenantId: wikiBinding.scope.tenantId,
+            agentId: wikiBinding.scope.agentId,
+            runId: wikiBinding.scope.runId,
+          },
+        }
       : {}),
   };
-  return buildChatRequestBody(
-    {
-      ...opts,
-      memory: {
-        ...memory,
-        fileContext: {
-          files,
-          hits,
-          cache: cacheSummary,
-        },
-      },
-    },
+}
+
+/** Snapshot bindings immediately before opening the SSE. */
+export async function prepareChatRequestBody(
+  opts: PrepareChatRequestOptions,
+  historyToSend: Array<{ role: ChatRole; content: string }>,
+  turnId: string,
+  _deps: {
+    loadFileMemory?: unknown;
+    searchFileMemory?: unknown;
+  } = {},
+): Promise<ChatRequestBody> {
+  const { wireMemory, wireWiki } = snapshotRequestBindings(
+    opts.memory,
+    opts.wiki,
+  );
+  return composeChatRequestBody(
+    opts,
     historyToSend,
     turnId,
+    wireMemory,
+    wireWiki,
   );
 }
 
@@ -363,6 +588,7 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
       turnId: string,
     ) => {
       const opts = optionsRef.current;
+      const wikiBinding = snapshotWikiBinding(opts.wiki);
       const controller = new AbortController();
       abortRef.current = controller;
 
@@ -397,6 +623,7 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
         }
 
         for await (const event of streamChat(body, controller.signal)) {
+          if (!isRecord(event)) continue;
           if (event.type === "query.rewritten") {
             updateAssistant({
               retrievalQuery: event.query,
@@ -417,6 +644,12 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
               retrievedChunks: event.chunks,
               retrievalGroups: event.byKnowledgeBase,
             });
+          } else if (event.type === "wiki.start") {
+            const patch = sanitizeWikiStartPatch(event);
+            if (patch) updateAssistant(patch);
+          } else if (event.type === "wiki.done") {
+            const patch = sanitizeWikiDonePatch(event, wikiBinding);
+            if (patch) updateAssistant(patch);
           } else if (event.type === "memory.start") {
             // 把服务端真正发起的 SearchMemories query 落到当前 message 上：
             //  - chunks 命中时，服务端复用 rewriter 重写后的 query；
@@ -430,8 +663,8 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
             // 「想看为什么没召回」时 message 上没有信号可查。
             updateAssistant({ memoryHits: event.hits });
           } else if (event.type === "memory.files") {
-            // 文件记忆模式专属：把浏览器标签页中的文件树与缓存统计落到
-            // assistant message 上，供气泡展示「本轮文件记忆」摘要。
+            // 文件记忆模式专属：把 Chat BFF 返回的文件树与有界缓存统计
+            // 落到 assistant message 上，供气泡展示「本轮文件记忆」摘要。
             updateAssistant({
               memoryFiles: event.files,
               memoryFilesCache: event.cache,
@@ -573,7 +806,8 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
       // pre-stream labels (intent extraction → retrieval → thinking) instead
       // of a single generic "正在思考" that sits unchanged for several
       // seconds while the server runs the rewriter and KB queries.
-      const usingRag = (opts.rag?.knowledgeBases?.length ?? 0) > 0;
+      const usingRag =
+        (opts.rag?.knowledgeBases?.length ?? 0) > 0 || Boolean(opts.wiki);
       const assistantMsg: ChatMessage = {
         id: assistantId,
         role: "assistant",
@@ -640,7 +874,8 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
       setError(null);
 
       const assistantId = newId();
-      const usingRag = (opts.rag?.knowledgeBases?.length ?? 0) > 0;
+      const usingRag =
+        (opts.rag?.knowledgeBases?.length ?? 0) > 0 || Boolean(opts.wiki);
       const assistantMsg: ChatMessage = {
         id: assistantId,
         role: "assistant",