@tablestore/tablestore-agent-cli 0.2.1 → 0.2.4

package/dist/dashboard-runtime/dashboard/src/hooks/use-oss-list.ts

@@ -1,5 +1,6 @@
 import { useInfiniteQuery } from "@tanstack/react-query";
 
+import { ApiClientError } from "@/services/api-client";
 import {
   listOssObjects,
   type OssListFile,
@@ -23,6 +24,8 @@ export interface UseOssListResult {
   fetchNextPage: () => void;
   refetch: () => void;
   error: Error | null;
+  /** Cast back to ApiClientError when present, so the UI can read displayMessage / upstream details. */
+  apiError: ApiClientError | null;
   /** Forwarded so the UI can render the "OSS_FORBIDDEN / NOT_CONFIGURED" state. */
   errorCode: string | null;
 }
@@ -65,11 +68,9 @@ export function useOssList(options: UseOssListOptions): UseOssListResult {
     files.push(...page.files);
   }
 
-  // Surface error code from the standard envelope so the UI can switch on it.
-  const errorCode =
-    query.error && typeof query.error === "object" && "code" in query.error
-      ? String((query.error as { code: unknown }).code ?? "")
-      : null;
+  const apiError =
+    query.error instanceof ApiClientError ? query.error : null;
+  const errorCode = apiError ? apiError.code : null;
 
   return {
     folders,
@@ -84,6 +85,7 @@ export function useOssList(options: UseOssListOptions): UseOssListResult {
       void query.refetch();
     },
     error: query.error ?? null,
+    apiError,
     errorCode,
   };
 }

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

@@ -29,6 +29,8 @@ export interface UseQaChatOptions {
   systemPrompt: string;
   temperature?: number;
   rag?: ChatRequestBody["rag"];
+  /** 绑定的记忆库写 scope（完整四字段）。undefined ⇒ 该轮不开启记忆。 */
+  memory?: ChatRequestBody["memory"];
   /**
    * Invoked after each streaming turn settles (done / error / abort) with the
    * final message list. The chat homepage uses this to upsert the session
@@ -37,6 +39,39 @@ export interface UseQaChatOptions {
   onPersist?: (messages: ChatMessage[]) => void;
 }
 
+/**
+ * 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"
+  >,
+  historyToSend: Array<{ role: ChatRole; content: string }>,
+  turnId: string,
+): ChatRequestBody {
+  return {
+    activeInstance: opts.activeInstance,
+    providerId: opts.providerId,
+    model: opts.model,
+    messages: historyToSend,
+    systemPrompt: opts.systemPrompt,
+    temperature: opts.temperature,
+    rag: opts.rag,
+    ...(opts.memory ? { memory: { ...opts.memory, turnId } } : {}),
+  };
+}
+
 export interface UseQaChatResult {
   messages: ChatMessage[];
   isStreaming: boolean;
@@ -184,6 +219,7 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
     async (
       assistantId: string,
       historyToSend: Array<{ role: ChatRole; content: string }>,
+      turnId: string,
     ) => {
       const opts = optionsRef.current;
       const controller = new AbortController();
@@ -203,15 +239,7 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
       };
 
       try {
-        const body: ChatRequestBody = {
-          activeInstance: opts.activeInstance,
-          providerId: opts.providerId,
-          model: opts.model,
-          messages: historyToSend,
-          systemPrompt: opts.systemPrompt,
-          temperature: opts.temperature,
-          rag: opts.rag,
-        };
+        const body = buildChatRequestBody(opts, historyToSend, turnId);
 
         if (devFlag("logChatRequest")) {
           // Diagnostic surface for the cross-session bleed investigation.
@@ -246,6 +274,21 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
               retrievedChunks: event.chunks,
               retrievalGroups: event.byKnowledgeBase,
             });
+          } else if (event.type === "memory.start") {
+            // 把服务端真正发起的 SearchMemories query 落到当前 message 上：
+            //  - chunks 命中时，服务端复用 rewriter 重写后的 query；
+            //  - chunks 为空时，回退到原始用户输入。
+            // 渲染层把它放在「参考 N 条记忆」触发栏的副标题位置，便于
+            // 用户/调试者一眼看出「服务端到底拿什么去搜的记忆」。
+            updateAssistant({ memoryQuery: event.query });
+          } else if (event.type === "memory.done") {
+            // 永远写一次，即便是空数组——零命中由 MemoryHitsBlock 内部
+            // 的 `length > 0` 守卫吞掉，不在 hook 这层做条件分支，避免
+            // 「想看为什么没召回」时 message 上没有信号可查。
+            updateAssistant({ memoryHits: event.hits });
+          } else if (event.type === "memory.save.skipped") {
+            // 写回失败不打断对话流，留给 logger 处理。
+            console.warn("[chat] memory.save.skipped:", event.reason);
           } else if (event.type === "reasoning.delta") {
             const buf = pendingDeltasRef.current.get(assistantId) ?? {};
             buf.reasoning = (buf.reasoning ?? "") + event.delta;
@@ -339,12 +382,14 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
       }
 
       setError(null);
+      const turnId = newId("turn");
       const userMsg: ChatMessage = {
         id: newId(),
         role: "user",
         content: trimmed,
         createdAt: Date.now(),
         status: "done",
+        turnId,
       };
       const assistantId = newId();
       // Snapshot whether this turn is RAG-enabled. The pill uses this to pick
@@ -376,7 +421,7 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
       setMessages(nextMessages);
       setIsStreaming(true);
 
-      await _runAssistantTurn(assistantId, historyToSend);
+      await _runAssistantTurn(assistantId, historyToSend, turnId);
     },
     [_runAssistantTurn],
   );
@@ -406,6 +451,15 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
       const anchor = truncated[truncated.length - 1];
       if (!anchor || anchor.role !== "user") return;
 
+      // 复用 anchor 用户消息原有的 turnId；老消息（Task 10 之前持久化的）
+      // 没有 turnId 时退回新生成。把新生成的 turnId 回写到 anchor 上，
+      // 这样后续再次 reissueTurn 仍能复用同一个值（避免每次重发都触发新写入）。
+      const turnId = anchor.turnId ?? newId("turn");
+      if (!anchor.turnId) {
+        const idx = truncated.length - 1;
+        truncated[idx] = { ...anchor, turnId };
+      }
+
       setError(null);
 
       const assistantId = newId();
@@ -430,7 +484,7 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
       setMessages(nextMessages);
       setIsStreaming(true);
 
-      await _runAssistantTurn(assistantId, historyToSend);
+      await _runAssistantTurn(assistantId, historyToSend, turnId);
     },
     [_runAssistantTurn],
   );

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

@@ -0,0 +1,15 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { updateDocument, type UpdateDocumentRequest } from "@/services/documents";
+
+export function useUpdateDocument() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (request: UpdateDocumentRequest) => updateDocument(request),
+    // Returning the invalidate promise makes `mutateAsync` await the refetch,
+    // so callers see fresh data the moment `await mutate(...)` resolves
+    // instead of a brief flash of pre-update state.
+    onSuccess: () =>
+      queryClient.invalidateQueries({ queryKey: ["knowledge-bases"] }),
+  });
+}

package/dist/dashboard-runtime/dashboard/src/lib/api-error-toast.ts

@@ -0,0 +1,62 @@
+"use client";
+
+import { toast } from "sonner";
+
+import { ApiClientError } from "@/services/api-client";
+
+interface ShowApiErrorOptions {
+  /**
+   * Used as the toast title when the error has no actionable code (e.g. a
+   * raw `Error` from a non-API path). Ignored for `ApiClientError`, which
+   * always shows `[CODE] message` so codes stay grep-able.
+   */
+  fallbackTitle?: string;
+}
+
+/**
+ * Standard error toast for any API failure.
+ *
+ * - `ApiClientError`: title is `[upstreamCode || code] message` so the user
+ *   sees `[SignatureDoesNotMatch]` instead of just "Access denied", and
+ *   the diagnostic context (trace id, upstream request id) lands in the
+ *   description for support attachments.
+ * - Other errors: title is `fallbackTitle` if provided, otherwise the
+ *   error's `message`.
+ */
+export function showApiError(
+  error: unknown,
+  options: ShowApiErrorOptions = {},
+): void {
+  if (error instanceof ApiClientError) {
+    const description = formatErrorContext(error);
+    if (description) {
+      toast.error(error.displayMessage, { description });
+    } else {
+      toast.error(error.displayMessage);
+    }
+    return;
+  }
+  const message = error instanceof Error ? error.message : String(error ?? "未知错误");
+  toast.error(options.fallbackTitle ?? message);
+}
+
+/**
+ * Compact one-line context block shown beneath the main error message
+ * (toast description or EmptyState subtitle). Each part is short enough
+ * that the line stays readable but informative enough for a support agent
+ * to find the corresponding log entry.
+ */
+export function formatErrorContext(error: ApiClientError): string {
+  const parts: string[] = [];
+  const upstreamReq = error.details?.upstreamRequestId;
+  if (upstreamReq) parts.push(`OSS RequestId: ${upstreamReq}`);
+  if (error.traceId) parts.push(`Trace: ${shortId(error.traceId)}`);
+  if (error.requestId && error.requestId !== upstreamReq) {
+    parts.push(`Req: ${shortId(error.requestId)}`);
+  }
+  return parts.join(" · ");
+}
+
+function shortId(id: string): string {
+  return id.length > 8 ? `${id.slice(0, 8)}…` : id;
+}

package/dist/dashboard-runtime/dashboard/src/lib/constants.ts

@@ -20,3 +20,11 @@ export const METADATA_TYPES = [
 ] as const;
 
 export type MetadataType = (typeof METADATA_TYPES)[number];
+
+/**
+ * 当后端返回裸 base64（无 data URL 前缀）时，补充的 MIME 类型兜底值。
+ * 浏览器会根据实际内容嗅探真实格式，此处只需保证是合法的 image/* 类型
+ * 以避免 CSP 拒绝渲染。选用 image/jpeg 是因为知识库文档处理产出的图片
+ * 绝大多数为 JPEG 格式。
+ */
+export const IMAGE_FALLBACK_DATA_PREFIX = "data:image/jpeg;base64,";

package/dist/dashboard-runtime/dashboard/src/lib/metadata-form.ts

@@ -0,0 +1,88 @@
+import type { MetadataField } from "@/types/knowledge-base";
+
+/**
+ * Convert a record of string form values into the typed shape the backend
+ * expects, driven by the KB metadata schema.
+ *
+ * Empty / undefined inputs are SKIPPED — the resulting object simply does
+ * not contain that key. Combined with the backend's overwrite semantics,
+ * this is how "clear a field" works at the form layer.
+ */
+export function convertMetadataValues(
+  values: Record<string, string>,
+  fields: MetadataField[],
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const field of fields) {
+    const raw = values[field.name];
+    if (raw === undefined || raw === "") continue;
+    switch (field.type) {
+      case "long":
+        result[field.name] = parseInt(raw, 10);
+        break;
+      case "double":
+        result[field.name] = parseFloat(raw);
+        break;
+      case "boolean":
+        result[field.name] = raw === "true";
+        break;
+      case "string_list":
+      case "long_list":
+      case "double_list":
+      case "boolean_list":
+      case "date_list": {
+        const parts = raw.split(",").map((s) => s.trim()).filter(Boolean);
+        if (field.type === "long_list")
+          result[field.name] = parts.map((p) => parseInt(p, 10));
+        else if (field.type === "double_list")
+          result[field.name] = parts.map((p) => parseFloat(p));
+        else if (field.type === "boolean_list")
+          result[field.name] = parts.map((p) => p === "true");
+        else result[field.name] = parts;
+        break;
+      }
+      default:
+        result[field.name] = raw;
+    }
+  }
+  return result;
+}
+
+/**
+ * Reverse direction of {@link convertMetadataValues} — flatten a typed
+ * metadata object into the string-form Record used by the edit form.
+ *
+ * Missing fields → empty string (so the input renders blank). Lists are
+ * joined with ", ". Booleans become "true" / "false" to match the boolean
+ * Select options.
+ */
+export function metadataToFormValues(
+  metadata: Record<string, unknown> | undefined | null,
+  fields: MetadataField[],
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const field of fields) {
+    const v = metadata?.[field.name];
+    if (v === undefined || v === null) {
+      result[field.name] = "";
+      continue;
+    }
+    switch (field.type) {
+      case "boolean":
+        result[field.name] = v ? "true" : "false";
+        break;
+      case "string_list":
+      case "long_list":
+      case "double_list":
+      case "boolean_list":
+      case "date_list":
+        result[field.name] = Array.isArray(v)
+          ? v.map((item) => String(item)).join(", ")
+          : "";
+        break;
+      default:
+        result[field.name] = String(v);
+    }
+  }
+  return result;
+}

package/dist/dashboard-runtime/dashboard/src/lib/query-keys.ts

@@ -27,6 +27,20 @@ export const queryKeys = {
       maxResults,
       subspace,
     ] as const,
+  document: (
+    scope: string,
+    knowledgeBaseName: string,
+    docId: string | null | undefined,
+    subspace?: string,
+  ) =>
+    [
+      "knowledge-bases",
+      scope,
+      knowledgeBaseName,
+      "document",
+      docId,
+      subspace,
+    ] as const,
   chunks: (
     scope: string,
     knowledgeBaseName: string,

package/dist/dashboard-runtime/dashboard/src/lib/server/api-helpers.ts

@@ -86,12 +86,21 @@ export function successResponse<T>(data: T, status = 200): NextResponse {
 
 /**
  * Build a standard error envelope response.
+ *
+ * `details` is forwarded both into the response body and into the server log
+ * record (merged under `details.*`). Use it to carry upstream diagnostics
+ * (e.g. `upstreamCode`, `upstreamRequestId`) that the UI can prefix to the
+ * displayed message and that support agents can grep the JSONL logs for.
  */
 export function errorResponse(
   code: string,
   message: string,
   status?: number,
-  options: { log?: boolean; errorSource?: "local" | "network" | "service" | "browser" } = {},
+  options: {
+    log?: boolean;
+    errorSource?: "local" | "network" | "service" | "browser";
+    details?: Record<string, unknown>;
+  } = {},
 ): NextResponse {
   const responseStatus = status ?? httpStatusFor(code);
   if (options.log !== false) {
@@ -102,12 +111,14 @@ export function errorResponse(
       responseStatus,
       undefined,
       options.errorSource ?? "local",
+      options.details,
     );
   }
-  const response = NextResponse.json(
-    { code, message, data: null },
-    { status: responseStatus },
-  );
+  const body: Record<string, unknown> = { code, message, data: null };
+  if (options.details && Object.keys(options.details).length > 0) {
+    body.details = options.details;
+  }
+  const response = NextResponse.json(body, { status: responseStatus });
   attachNoStoreHeader(response);
   attachTraceHeader(response);
   return response;
@@ -309,6 +320,7 @@ function logApiResponse(
   status: number,
   requestId?: string,
   errorSource?: "local" | "network" | "service" | "browser",
+  extraDetails?: Record<string, unknown>,
 ): void {
   const context = apiContext.getStore();
   if (status < 400 && !shouldLogApiSuccess(context?.path)) return;
@@ -329,6 +341,7 @@ function logApiResponse(
       status,
       code,
       errorSource,
+      ...extraDetails,
     },
   });
 }

package/dist/dashboard-runtime/dashboard/src/lib/server/llm-client.ts

@@ -8,6 +8,24 @@ import type {
   ModelListItem,
 } from "@/types/llm-provider";
 
+// ---------------------------------------------------------------------------
+// Multimodal content types (OpenAI-compatible)
+// ---------------------------------------------------------------------------
+
+/**
+ * OpenAI-compatible content part for multimodal messages.
+ * Supports text and image_url parts.
+ */
+export type ContentPart =
+  | { type: "text"; text: string }
+  | { type: "image_url"; image_url: { url: string; detail?: "low" | "high" | "auto" } };
+
+/**
+ * Message content can be either a plain string (text-only) or an array of
+ * content parts (multimodal). Supports text and image_url parts.
+ */
+export type LLMMessageContent = string | ContentPart[];
+
 // ---------------------------------------------------------------------------
 // OpenAI-compatible transport
 // ---------------------------------------------------------------------------
@@ -86,7 +104,7 @@ export async function testConnectivity(
 
 export interface ChatCompletionStreamParams {
   model: string;
-  messages: Array<{ role: ChatRole; content: string }>;
+  messages: Array<{ role: ChatRole; content: LLMMessageContent }>;
   temperature?: number;
   signal?: AbortSignal;
 }

package/dist/dashboard-runtime/dashboard/src/lib/server/oss-client.ts

@@ -32,34 +32,63 @@ export function getOssClient(config: AppConfig): OSS | null {
   });
 }
 
-/**
- * Translate an error from ali-oss (or anywhere else in the OSS path) into
- * the dashboard's canonical `{ code, httpStatus, message }` triple. The
- * route handlers feed this directly into `forwardResponse`.
- */
-export function mapOssError(error: unknown): {
+export interface OssErrorDetails {
+  upstreamCode?: string;
+  upstreamRequestId?: string;
+  upstreamHostId?: string;
+  upstreamStatus?: number;
+  [key: string]: unknown;
+}
+
+export interface MappedOssError {
   code: string;
   httpStatus: number;
   message: string;
-} {
-  // ali-oss attaches a string `code` on every operational error; lean on it.
-  const ossCode =
-    error && typeof error === "object" && "code" in error
-      ? String((error as { code: unknown }).code ?? "")
-      : "";
+  details: OssErrorDetails;
+}
+
+/**
+ * Translate an error from ali-oss (or anywhere else in the OSS path) into
+ * the dashboard's canonical `{ code, httpStatus, message, details }` shape.
+ * Upstream identifiers (`code`, `requestId`, `hostId`, HTTP status) are
+ * preserved on `details` so the UI can prefix `[SignatureDoesNotMatch]` and
+ * support agents can match the request against OSS-side logs.
+ */
+export function mapOssError(error: unknown): MappedOssError {
+  const record =
+    error && typeof error === "object"
+      ? (error as Record<string, unknown>)
+      : {};
+  const ossCode = typeof record.code === "string" ? record.code : "";
+  const requestId =
+    typeof record.requestId === "string" ? record.requestId : undefined;
+  const hostId = typeof record.hostId === "string" ? record.hostId : undefined;
+  const status =
+    typeof record.status === "number"
+      ? record.status
+      : typeof record.statusCode === "number"
+        ? record.statusCode
+        : undefined;
   const message =
     error instanceof Error ? error.message : String(error ?? "Unknown OSS error");
 
+  const details: OssErrorDetails = {
+    upstreamCode: ossCode || undefined,
+    upstreamRequestId: requestId,
+    upstreamHostId: hostId,
+    upstreamStatus: status,
+  };
+
   switch (ossCode) {
     case "AccessDenied":
     case "InvalidAccessKeyId":
     case "SignatureDoesNotMatch":
-      return { code: "OSS_FORBIDDEN", httpStatus: 403, message };
+      return { code: "OSS_FORBIDDEN", httpStatus: 403, message, details };
     case "NoSuchBucket":
-      return { code: "OSS_BUCKET_NOT_FOUND", httpStatus: 404, message };
+      return { code: "OSS_BUCKET_NOT_FOUND", httpStatus: 404, message, details };
     case "InvalidArgument":
-      return { code: "BAD_REQUEST", httpStatus: 400, message };
+      return { code: "BAD_REQUEST", httpStatus: 400, message, details };
     default:
-      return { code: "OSS_UPSTREAM_ERROR", httpStatus: 502, message };
+      return { code: "OSS_UPSTREAM_ERROR", httpStatus: 502, message, details };
   }
 }

package/dist/dashboard-runtime/dashboard/src/schemas/knowledge-base.ts

@@ -80,6 +80,12 @@ export const createKBSchema = z.object({
   metadata: z.array(metadataFieldSchema).max(200).optional(),
   embeddingConfiguration: embeddingConfigSchema.optional(),
   retrievalConfiguration: retrievalConfigSchema.optional(),
+  multimodal: z.boolean().optional(),
+  ingestConfiguration: z
+    .object({
+      enableTableFormulaCaption: z.boolean().optional(),
+    })
+    .optional(),
 });
 
 export const updateKBSchema = z.object({

package/dist/dashboard-runtime/dashboard/src/schemas/llm-chat.ts

@@ -19,6 +19,25 @@ export const chatRagSchema = z.object({
   topK: z.number().int().min(1).max(200).optional(),
 });
 
+// 写 scope 的四个字段必须为非空、非通配符字符串。
+// 客户端不允许显式发 `*`——通配符仅由服务端在 SearchMemories 调用前注入。
+const nonWildcardId = z.string().min(1).refine((v) => v !== "*", {
+  message: "wildcard '*' is not allowed on the wire; the server applies it",
+});
+
+export const chatMemorySchema = z.object({
+  memoryStoreName: z.string().min(1),
+  scope: z.object({
+    appId: nonWildcardId,
+    tenantId: nonWildcardId,
+    agentId: nonWildcardId,
+    runId: nonWildcardId,
+  }),
+  topK: z.number().int().min(1).max(50).optional(),
+  autoSave: z.boolean().optional(),
+  turnId: z.string().min(1).optional(),
+});
+
 /**
  * Server-side validation for the chat endpoint payload. The last message must
  * be from the user; this rule is enforced in the route handler rather than
@@ -32,6 +51,7 @@ export const chatRequestSchema = z.object({
   systemPrompt: z.string().max(8_000).optional(),
   temperature: z.number().min(0).max(2).optional(),
   rag: chatRagSchema.optional(),
+  memory: chatMemorySchema.optional(),
 });
 
 export type ChatRequestInput = z.infer<typeof chatRequestSchema>;