@tablestore/tablestore-agent-cli 0.2.1 → 0.2.4

package/dist/dashboard-runtime/dashboard/src/app/api/v1/llm/chat/route.ts

@@ -1,6 +1,6 @@
 import { type NextRequest } from "next/server";
 
-import { chatCompletionStream } from "@/lib/server/llm-client";
+import { chatCompletionStream, type LLMMessageContent, type ContentPart } from "@/lib/server/llm-client";
 import { getProviderWithSecret } from "@/lib/server/llm-provider-store";
 import { rewriteQuery } from "@/lib/server/query-rewriter";
 import {
@@ -19,7 +19,13 @@ import type {
   RetrievedChunk,
   RetrievalGroup,
 } from "@/types/llm-chat";
+import type { MemorySearchHit } from "@/types/memory";
 import type { RetrievalResult } from "@/types/retrieval";
+import {
+  deriveReadScope,
+  formatMemoryBlock,
+  type MemoryWriteScope,
+} from "./memory-helpers";
 
 // Default aggregate cap when the client omits `rag.topK`.
 const DEFAULT_AGGREGATE_TOP_K = 20;
@@ -29,15 +35,80 @@ const DEFAULT_AGGREGATE_TOP_K = 20;
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
-const DEFAULT_RAG_SYSTEM_PROMPT =
-  "你是一个基于知识库检索结果回答问题的助手。请严格参考下面的「检索结果」回答用户问题；若检索结果未涵盖相关信息，请如实说明未在知识库中找到，不要编造。回答时可以在末尾用 `[1]` `[2]` 等编号标注引用来源。";
+/**
+ * 默认 system preamble。仅在调用方没有自填 `systemPrompt` 时兜底。
+ *
+ * 之前是一段固定的「你是 RAG 助手」字符串，问题在于：
+ * 1. memory 在场时，prompt 里不会告诉模型「相关历史记忆」是什么、要怎么用；
+ * 2. 「若检索结果未涵盖请说明未在知识库中找到」这一句会把视野收敛到 KB，
+ *    哪怕记忆段已注入，模型也容易因为「不在 KB」=「无法回答」而忽略记忆。
+ *
+ * 现在按本轮请求实际拼出来的上下文段落（chunks / memoryBlock）动态分支，
+ * 让模型清楚地知道这次有哪些信源、各自该如何使用。
+ */
+function buildDefaultPreamble(opts: {
+  hasRag: boolean;
+  hasMemory: boolean;
+}): string {
+  const parts: string[] = [
+    "你是一个智能助手，请基于下方提供的上下文（如有）回答用户的问题。",
+  ];
+  if (opts.hasRag) {
+    parts.push(
+      "下方会给出从知识库检索出的「检索结果」，请优先参考其中内容回答；" +
+        "若检索结果未涵盖相关信息，请如实说明知识库中未找到，不要编造。" +
+        "引用时可在末尾用 `[1]` `[2]` 等编号标注来源。",
+    );
+  }
+  if (opts.hasMemory) {
+    parts.push(
+      "下方还会给出「相关历史记忆」，记录了你与该用户/场景过往的对话沉淀。" +
+        "请将这些记忆作为已知的用户偏好或上下文自然融入回答；" +
+        "无需显式引用编号，也不要因为某条记忆未涉及就拒绝回答。",
+    );
+  }
+  return parts.join("\n\n");
+}
 
 // Maximum number of history messages (excluding system) forwarded to the LLM.
 // Matches the plan's simple "keep last 20 turns" policy; token-based trimming
 // can land later when we wire up `tiktoken`.
 const MAX_HISTORY_MESSAGES = 20;
+/**
+ * 单个检索 chunk 拼入 system message 时的最大显示字符数。
+ * 用于控制 system 提示总长度，避免单个超长 chunk 把模型上下文挤爆。
+ */
+const MAX_CHUNK_DISPLAY_LENGTH = 1200;
 const chatLogger = createLogger("dashboard.api.llm");
 
+/**
+ * 判断一个检索 chunk 是否为图片类型。
+ *
+ * 服务端契约下 chunkType 共 4 种取值：text | table | formula | image。
+ * 大小写不敏感地比较，以兼容后端契约可能出现的大小写漂移。除 image 外的
+ * 3 种类型都按文本走 contextBlock 拼接，不进入多模态 image_url 部分。
+ */
+function isImageChunk(chunk: { chunkType?: string }): boolean {
+  return chunk.chunkType?.toUpperCase() === "IMAGE";
+}
+
+// turnId 去重：客户端每个「逻辑轮次」生成一次 turnId（regenerate / edit-resend
+// 复用同一个值）。我们仅在内存里维护一个 ~10 分钟过期的 set；不要求扛过进程重启。
+const TURN_DEDUP_TTL_MS = 10 * 60 * 1000;
+const seenTurnIds = new Map<string, number>();
+
+function shouldSkipDuplicateTurn(turnId: string | undefined): boolean {
+  if (!turnId) return false;
+  const now = Date.now();
+  // 顺手清理过期键，避免无限增长。
+  for (const [key, expiry] of seenTurnIds) {
+    if (expiry <= now) seenTurnIds.delete(key);
+  }
+  if (seenTurnIds.has(turnId)) return true;
+  seenTurnIds.set(turnId, now + TURN_DEDUP_TTL_MS);
+  return false;
+}
+
 /**
  * POST /api/v1/llm/chat
  *
@@ -118,6 +189,26 @@ export async function POST(request: NextRequest) {
     }
   }
 
+  type ResolvedMemoryClient = Awaited<ReturnType<typeof resolveMemoryClient>>;
+  let memoryClient: ResolvedMemoryClient | null = null;
+  if (body.memory) {
+    // memory 与 rag 都依赖同一份 Tablestore 凭据；如果 RAG 已经做过 project
+    // 上下文校验，这里就不再重复（同一个请求共享一份 cookie）。
+    if (!body.rag) {
+      const projectContext = validateChatProjectContext(
+        request,
+        activeInstanceProvided ? body.activeInstance ?? null : undefined,
+      );
+      if (!projectContext.ok) {
+        return jsonError(409, "PROJECT_CONTEXT_CHANGED", projectContext.message);
+      }
+    }
+    memoryClient = await resolveMemoryClient(request);
+    if (!memoryClient.ok) {
+      return jsonError(memoryClient.status, memoryClient.code, memoryClient.message);
+    }
+  }
+
   const upstreamAbort = new AbortController();
   const cleanup = () => {
     try {
@@ -155,6 +246,7 @@ export async function POST(request: NextRequest) {
         // ---- RAG retrieval ----
         let chunks: RetrievedChunk[] = [];
         let groupsForPrompt: RetrievalGroup[] = [];
+        let queryForMemory = lastUser.content;
         if (body.rag && kbClient?.ok) {
           // Decide retrieval query: on multi-turn (>=2 non-system messages),
           // condense the history into a standalone question; otherwise keep
@@ -196,6 +288,7 @@ export async function POST(request: NextRequest) {
             query: retrievalQuery,
             original: lastUser.content,
           });
+          queryForMemory = retrievalQuery;
           void rewritten;
 
           emit({ type: "retrieval.start" });
@@ -214,11 +307,50 @@ export async function POST(request: NextRequest) {
           });
         }
 
+        // ---- Memory 检索 ----
+        let memoryHits: MemorySearchHit[] = [];
+        if (body.memory && memoryClient?.ok) {
+          // 仅当 RAG 实际命中（chunks 非空）时才复用其 rewrite 后的 query；否则回退到原始用户输入，
+          // 避免在无召回时把 rewriter 的猜测当成记忆检索的输入。
+          const memoryQuery = chunks.length > 0 ? queryForMemory : lastUser.content;
+          emit({ type: "memory.start", query: memoryQuery });
+          const readScope = deriveReadScope(body.memory.scope as MemoryWriteScope);
+          try {
+            const resp = await memoryClient.client.searchMemories({
+              memoryStoreName: body.memory.memoryStoreName,
+              scope: readScope,
+              query: memoryQuery,
+              topK: body.memory.topK ?? 5,
+            });
+            if (resp.code === "SUCCESS") {
+              // SDK 真实字段名是 `results`（见 @tablestore/agent-storage 的
+              // SearchMemoriesResponse 类型）；早期版本误读成 `hits` 会让
+              // memoryHits 永远为空，导致召回的记忆无法注入 system prompt。
+              const data = resp.data as { results?: MemorySearchHit[] } | undefined;
+              memoryHits = data?.results ?? [];
+            } else {
+              chatLogger.warn({
+                event: "api.memory.search_failed",
+                message: resp.message ?? "searchMemories returned non-SUCCESS",
+                details: { code: resp.code },
+              });
+            }
+          } catch (err) {
+            chatLogger.warn({
+              event: "api.memory.search_exception",
+              message: err instanceof Error ? err.message : String(err),
+              error: err,
+            });
+          }
+          emit({ type: "memory.done", hits: memoryHits });
+        }
+
         // ---- Build final messages ----
         const finalMessages = buildFinalMessages(
           body.systemPrompt ?? "",
           chunks,
           groupsForPrompt,
+          formatMemoryBlock(memoryHits),
           body.messages,
         );
 
@@ -231,14 +363,74 @@ export async function POST(request: NextRequest) {
         });
 
         const reader = upstream.getReader();
+        let assistantContent = "";
         while (true) {
           const { value, done } = await reader.read();
           if (done) break;
+          if (value.type === "content.delta") {
+            assistantContent += value.delta;
+          }
           emit(value);
           if (value.type === "done" || value.type === "error") {
             break;
           }
         }
+        // ---- Fire-and-forget 写回 ----
+        // 必须放在 close() 之前 schedule，但执行可以晚于 close()：
+        // 我们用一个不 await 的 IIFE 让它脱离 SSE controller 的生命周期。
+        if (
+          body.memory &&
+          memoryClient?.ok &&
+          body.memory.autoSave !== false &&
+          assistantContent.length > 0 &&
+          !shouldSkipDuplicateTurn(body.memory.turnId)
+        ) {
+          const writeScope = body.memory.scope as MemoryWriteScope;
+          const storeName = body.memory.memoryStoreName;
+          const userText = lastUser.content;
+          const assistantText = assistantContent;
+          const client = memoryClient.client;
+          // 不 await：如果写回早于 close() 完成，就把 skip 原因 emit 回前端；
+          // 否则只走 chatLogger.warn 落盘 —— 因为此时 SSE 流已结束。
+          (async () => {
+            try {
+              const resp = await client.addMemories({
+                memoryStoreName: storeName,
+                scope: writeScope,
+                messages: [
+                  { role: "user", content: userText },
+                  { role: "assistant", content: assistantText },
+                ],
+                sync: false,
+              });
+              if (resp.code !== "SUCCESS") {
+                if (!closed) {
+                  emit({
+                    type: "memory.save.skipped",
+                    reason: resp.message ?? `addMemories returned ${resp.code}`,
+                  });
+                }
+                chatLogger.warn({
+                  event: "api.memory.save_failed",
+                  message: resp.message ?? "addMemories returned non-SUCCESS",
+                  details: { code: resp.code },
+                });
+              }
+            } catch (err) {
+              if (!closed) {
+                emit({
+                  type: "memory.save.skipped",
+                  reason: err instanceof Error ? err.message : String(err),
+                });
+              }
+              chatLogger.warn({
+                event: "api.memory.save_exception",
+                message: err instanceof Error ? err.message : String(err),
+                error: err,
+              });
+            }
+          })();
+        }
         chatLogger.info({
           event: "api.stream_response",
           message: "LLM chat stream completed",
@@ -250,6 +442,7 @@ export async function POST(request: NextRequest) {
             status: 200,
             code: "SUCCESS",
             ragEnabled: Boolean(body.rag),
+            memoryEnabled: Boolean(body.memory),
           },
         });
         close();
@@ -265,6 +458,7 @@ export async function POST(request: NextRequest) {
             path: logContext?.path,
             code: "INTERNAL_SERVER_ERROR",
             ragEnabled: Boolean(body.rag),
+            memoryEnabled: Boolean(body.memory),
           },
         });
         emit({
@@ -325,6 +519,29 @@ async function resolveKbClient(request: NextRequest): Promise<
   return { ok: true, client: resolved.kb };
 }
 
+/**
+ * Mirror of {@link resolveKbClient} but yielding the MemoryClient.
+ * Memory + RAG share the same Tablestore credential layer, so unwrap any
+ * NextResponse from `requireClients` the same way and surface a structured
+ * error descriptor instead of returning the Response directly.
+ */
+async function resolveMemoryClient(request: NextRequest): Promise<
+  | { ok: true; client: import("@tablestore/tablestore-agent-sdk").MemoryClient }
+  | { ok: false; status: number; code: string; message: string }
+> {
+  const resolved = requireClients(request);
+  if (resolved instanceof Response) {
+    const body = await resolved.json().catch(() => null);
+    return {
+      ok: false,
+      status: resolved.status,
+      code: body?.code ?? "UNAUTHORIZED",
+      message: body?.message ?? "Failed to resolve credentials",
+    };
+  }
+  return { ok: true, client: resolved.memory };
+}
+
 /**
  * Compose the system prompt and cap the history window. The retrieval chunks
  * are appended *after* the user-supplied prompt so user instructions take
@@ -332,37 +549,138 @@ async function resolveKbClient(request: NextRequest): Promise<
  * cite back. The header mentions the KB count when multiple KBs were queried
  * so the model can reason about source diversity.
  */
-function buildFinalMessages(
+/** @internal Exported for unit testing multimodal message construction. */
+export function buildFinalMessages(
   userSystemPrompt: string,
   chunks: RetrievedChunk[],
   groups: RetrievalGroup[],
+  memoryBlock: string,
   history: Array<{ role: ChatRole; content: string }>,
-): Array<{ role: ChatRole; content: string }> {
-  const preamble = userSystemPrompt.trim() || DEFAULT_RAG_SYSTEM_PROMPT;
+): Array<{ role: ChatRole; content: LLMMessageContent }> {
+  const preamble =
+    userSystemPrompt.trim() ||
+    buildDefaultPreamble({
+      hasRag: chunks.length > 0,
+      hasMemory: memoryBlock.length > 0,
+    });
   const successfulKbCount = groups.filter((g) => !g.error).length;
   const header = successfulKbCount > 1
     ? `检索结果（共 ${chunks.length} 条，来自 ${successfulKbCount} 个知识库）：`
     : `检索结果（共 ${chunks.length} 条）：`;
+
+  // Strip any `system` messages the client sent — we own the system turn.
+  const nonSystem = history.filter((m) => m.role !== "system");
+  const clipped =
+    nonSystem.length > MAX_HISTORY_MESSAGES
+      ? nonSystem.slice(-MAX_HISTORY_MESSAGES)
+      : nonSystem;
+
+  // Collect image parts with numbered labels to preserve chunk order.
+  //
+  // ChunkType 服务端契约共 4 种：text | table | formula | image。
+  // 这 4 种里只有 image 需要走 `image_url` 部分注入到 user message；其他全部
+  // 作为文本，由下面的 `contextBlock` 直接以 chunk.content 形式拼进 system
+  // message。这里大小写不敏感地匹配 IMAGE，使后端 chunkType 字段大小写漂移
+  // 不会破坏多模态注入。
+  const imageParts: ContentPart[] = [];
+  chunks.forEach((c, i) => {
+    if (isImageChunk(c) && c.imageBase64) {
+      // Add numbered label so the model can correlate with system message [N].
+      // 编号 `i + 1` 与下方 contextBlock 中的 `[N]` 保持同源，确保模型能把
+      // 「检索图片 2」对应到 system 提示里的 `[2]` 引用。
+      imageParts.push({
+        type: "text",
+        text: `[检索图片 ${i + 1}]：`,
+      });
+      imageParts.push({
+        type: "image_url",
+        image_url: { url: c.imageBase64 },
+      });
+    }
+  });
+
+  // System message is always a plain string (works with all providers).
+  // Chunks 在 system 中按检索返回顺序展开，并保持与 imageParts 同一编号系统。
   const contextBlock = chunks.length
     ? `\n\n${header}\n${chunks
         .map((c, i) => {
           const src = c.knowledgeBaseName ? ` (${c.knowledgeBaseName})` : "";
-          return `[${i + 1}]${src} ${truncate(c.content, 1200)}`;
+          // 仅在 IMAGE 且没有 caption/content 时用 "(图片)" 占位；其余 chunk
+          // 类型（text / table / formula）一律直接展开 content。
+          const body = truncate(
+            c.content || (isImageChunk(c) ? "(图片)" : ""),
+            MAX_CHUNK_DISPLAY_LENGTH,
+          );
+          return `[${i + 1}]${src} ${body}`;
         })
         .join("\n\n")}`
     : "";
 
-  // Strip any `system` messages the client sent — we own the system turn.
-  const nonSystem = history.filter((m) => m.role !== "system");
-  const clipped =
-    nonSystem.length > MAX_HISTORY_MESSAGES
-      ? nonSystem.slice(-MAX_HISTORY_MESSAGES)
-      : nonSystem;
+  const systemMessage = {
+    role: "system" as const,
+    content: preamble + contextBlock + memoryBlock,
+  };
 
-  return [
-    { role: "system", content: preamble + contextBlock },
-    ...clipped,
+  // If no images, return plain text messages (backward compatible)
+  if (imageParts.length === 0) {
+    return [systemMessage, ...clipped];
+  }
+
+  // Enrich the last user message with image parts
+  const messages: Array<{ role: ChatRole; content: LLMMessageContent }> = [
+    systemMessage,
   ];
+
+  const imageFallbackMessage = {
+    role: "user" as const,
+    content: [
+      ...imageParts,
+      { type: "text" as const, text: "请根据以上图片回答。" },
+    ],
+  };
+
+  if (clipped.length > 0) {
+    const lastIndex = clipped.length - 1;
+    const lastMessage = clipped[lastIndex];
+
+    if (lastMessage.role === "user") {
+      // Replace last user message with multimodal version
+      messages.push(
+        ...clipped.slice(0, lastIndex),
+        {
+          role: "user",
+          content: [
+            ...imageParts,
+            { type: "text", text: lastMessage.content },
+          ],
+        }
+      );
+    } else {
+      // Last message isn't a plain-text user message (e.g. assistant) — append
+      // a synthetic user turn carrying the images. This path is rare in
+      // production (clients normally end on a user turn) but can happen if the
+      // upstream injected a trailing assistant message or replayed history.
+      // Log a warning so we can spot it in observability rather than silently
+      // produce a "user said: 请根据以上图片回答。" turn the user never typed.
+      chatLogger.warn({
+        event: "api.chat.multimodal_fallback_user_turn",
+        message:
+          "last history message is not a user turn; appending synthetic " +
+          "user message to carry retrieved images",
+        details: {
+          lastRole: lastMessage.role,
+          imageCount: imageParts.length / 2,
+          historyLength: clipped.length,
+        },
+      });
+      messages.push(...clipped, imageFallbackMessage);
+    }
+  } else {
+    // No history — create a user message with images
+    messages.push(imageFallbackMessage);
+  }
+
+  return messages;
 }
 
 function truncate(text: string, max: number): string {

package/dist/dashboard-runtime/dashboard/src/app/api/v1/logs/client/route.ts

@@ -47,6 +47,15 @@ export async function POST(request: NextRequest) {
     typeof body.message === "string" ? body.message : "Browser error captured";
   const level = body.level === "warn" || body.level === "info" ? body.level : "error";
 
+  const code = typeof body.code === "string" ? body.code : undefined;
+  const status = typeof body.status === "number" ? body.status : undefined;
+  const upstreamCode =
+    typeof body.upstreamCode === "string" ? body.upstreamCode : undefined;
+  const upstreamRequestId =
+    typeof body.upstreamRequestId === "string"
+      ? body.upstreamRequestId
+      : undefined;
+
   browserLogger.log({
     level,
     event,
@@ -63,6 +72,10 @@ export async function POST(request: NextRequest) {
       url: typeof body.url === "string" ? body.url : undefined,
       userAgent: request.headers.get("user-agent") ?? undefined,
       digest: typeof body.digest === "string" ? body.digest : undefined,
+      code,
+      status,
+      upstreamCode,
+      upstreamRequestId,
     },
   });
 

package/dist/dashboard-runtime/dashboard/src/app/api/v1/oss/list/route.ts

@@ -79,6 +79,7 @@ export async function GET(request: NextRequest | Request) {
       const mapped = mapOssError(error);
       return errorResponse(mapped.code, mapped.message, mapped.httpStatus, {
         errorSource: "service",
+        details: mapped.details,
       });
     }
 

package/dist/dashboard-runtime/dashboard/src/app/globals.css

@@ -1,6 +1,25 @@
 @import "tailwindcss";
 @import "katex/dist/katex.min.css";
 
+/*
+ * Bridge the legacy Tailwind v3 style config (tailwind.config.ts) into
+ * Tailwind v4. Without @config, the JS config file is silently ignored,
+ * which means:
+ *   1. Theme tokens (success/warning/danger/info/purple) are never
+ *      registered, so utilities like `bg-success-soft` don't exist.
+ *   2. `darkMode: ["class", ".dark"]` is not applied, so `dark:` falls
+ *      back to `prefers-color-scheme`, which fights with next-themes'
+ *      class-based toggle and bleeds dark styles into light mode.
+ */
+@config "../../tailwind.config.ts";
+
+/*
+ * Belt-and-suspenders: ensure `dark:` always resolves through the
+ * `.dark` class that next-themes toggles on <html>, regardless of OS
+ * preference. This must agree with the darkMode setting above.
+ */
+@custom-variant dark (&:where(.dark, .dark *));
+
 @layer base {
   :root {
     /* Brand primary: webUI blue (hue 221, #2563eb) */
@@ -77,6 +96,8 @@
     --warning-soft: 48 100% 96%;
     --danger: 0 84% 60%;
     --danger-soft: 0 86% 97%;
+    --info: 217 91% 60%;
+    --info-soft: 214 100% 97%;
     --purple: 262 84% 58%;
     --purple-soft: 258 100% 97%;
 
@@ -174,6 +195,8 @@
     --warning-soft: 38 30% 18%;
     --danger: 0 84% 65%;
     --danger-soft: 0 30% 20%;
+    --info: 217 91% 70%;
+    --info-soft: 217 30% 18%;
     --purple: 262 84% 65%;
     --purple-soft: 262 30% 22%;
   }