@tablestore/tablestore-agent-cli 0.2.10 → 0.2.11

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

@@ -5,6 +5,11 @@ 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 {
@@ -24,7 +29,29 @@ import type { ChatMessage, ChatRequestBody, ChatRole } from "@/types/llm-chat";
  */
 type StreamPatch = { content?: string; reasoning?: string };
 
+/** Remove a curation state that never received a terminal server event. */
+export function settlePendingMemorySave(
+  messages: ChatMessage[],
+  assistantId: string,
+): ChatMessage[] {
+  let changed = false;
+  const settled = messages.map((message) => {
+    if (message.id !== assistantId || message.memorySaveStatus !== "saving") {
+      return message;
+    }
+    changed = true;
+    const next = { ...message };
+    delete next.memorySaveStatus;
+    delete next.memorySavePath;
+    delete next.memorySaveCount;
+    delete next.memorySaveError;
+    return next;
+  });
+  return changed ? settled : messages;
+}
+
 export interface UseQaChatOptions {
+  dataScopeKey: string;
   activeInstance: string | null;
   providerId: string;
   model: string;
@@ -41,6 +68,17 @@ export interface UseQaChatOptions {
   onPersist?: (messages: ChatMessage[]) => void;
 }
 
+function normalizeMemoryForRequest(
+  memory: ChatRequestBody["memory"],
+): ChatRequestBody["memory"] {
+  if (memory?.storageMode !== "filemem") return memory;
+  return {
+    ...memory,
+    scope: { ...memory.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
@@ -62,6 +100,13 @@ export function buildChatRequestBody(
   historyToSend: Array<{ role: ChatRole; content: string }>,
   turnId: string,
 ): ChatRequestBody {
+  const normalizedMemory = normalizeMemoryForRequest(opts.memory);
+  const memory = normalizedMemory
+    ? {
+        ...normalizedMemory,
+        turnId,
+      }
+    : undefined;
   return {
     activeInstance: opts.activeInstance,
     providerId: opts.providerId,
@@ -70,10 +115,100 @@ export function buildChatRequestBody(
     systemPrompt: opts.systemPrompt,
     temperature: opts.temperature,
     rag: opts.rag,
-    ...(opts.memory ? { memory: { ...opts.memory, turnId } } : {}),
+    ...(memory ? { memory } : {}),
   };
 }
 
+type PrepareChatRequestOptions = Pick<
+  UseQaChatOptions,
+  | "dataScopeKey"
+  | "activeInstance"
+  | "providerId"
+  | "model"
+  | "systemPrompt"
+  | "temperature"
+  | "rag"
+  | "memory"
+>;
+
+/** 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);
+  if (
+    !memory ||
+    (memory.retrievalMode !== "local" && memory.storageMode !== "filemem")
+  ) {
+    return buildChatRequestBody(opts, historyToSend, turnId);
+  }
+  const loadFileMemory = deps.loadFileMemory ?? loadBrowserFileMemory;
+  const searchFileMemory = deps.searchFileMemory ?? searchBrowserFileMemory;
+  const loaded = await loadFileMemory({
+    dataScopeKey: opts.dataScopeKey,
+    memoryStoreName: memory.memoryStoreName,
+    scope: memory.scope,
+  });
+  const lastUser = [...historyToSend]
+    .reverse()
+    .find((message) => message.role === "user");
+  const search = searchFileMemory({
+    key: loaded.key,
+    query: lastUser?.content ?? "",
+    topK: memory.topK ?? 5,
+  });
+  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) }
+      : {}),
+  };
+  return buildChatRequestBody(
+    {
+      ...opts,
+      memory: {
+        ...memory,
+        fileContext: {
+          files,
+          hits,
+          cache: cacheSummary,
+        },
+      },
+    },
+    historyToSend,
+    turnId,
+  );
+}
+
 export interface UseQaChatResult {
   messages: ChatMessage[];
   isStreaming: boolean;
@@ -144,19 +279,19 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
     if (pending.size === 0) return;
     const snapshot = new Map(pending);
     pending.clear();
-    setMessages((prev) =>
-      prev.map((m) => {
-        const patch = snapshot.get(m.id);
-        if (!patch) return m;
-        return {
-          ...m,
-          ...(patch.content ? { content: m.content + patch.content } : null),
-          ...(patch.reasoning
-            ? { reasoning: (m.reasoning ?? "") + patch.reasoning }
-            : null),
-        };
-      }),
-    );
+    const nextMessages = messagesRef.current.map((m) => {
+      const patch = snapshot.get(m.id);
+      if (!patch) return m;
+      return {
+        ...m,
+        ...(patch.content ? { content: m.content + patch.content } : null),
+        ...(patch.reasoning
+          ? { reasoning: (m.reasoning ?? "") + patch.reasoning }
+          : null),
+      };
+    });
+    messagesRef.current = nextMessages;
+    setMessages(nextMessages);
   }, []);
 
   const scheduleFlush = useCallback(() => {
@@ -239,13 +374,15 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
       const reasoningCompletedRef = { current: false };
 
       const updateAssistant = (patch: Partial<ChatMessage>) => {
-        setMessages((prev) =>
-          prev.map((m) => (m.id === assistantId ? { ...m, ...patch } : m)),
+        const nextMessages = messagesRef.current.map((m) =>
+          m.id === assistantId ? { ...m, ...patch } : m,
         );
+        messagesRef.current = nextMessages;
+        setMessages(nextMessages);
       };
 
       try {
-        const body = buildChatRequestBody(opts, historyToSend, turnId);
+        const body = await prepareChatRequestBody(opts, historyToSend, turnId);
 
         if (devFlag("logChatRequest")) {
           // Diagnostic surface for the cross-session bleed investigation.
@@ -293,15 +430,35 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
             // 「想看为什么没召回」时 message 上没有信号可查。
             updateAssistant({ memoryHits: event.hits });
           } else if (event.type === "memory.files") {
-            // 文件记忆模式专属：把本轮同步的镜像目录、文件树与同步统计
-            // 落到 assistant message 上，供气泡展示「本轮文件记忆」摘要。
+            // 文件记忆模式专属：把浏览器标签页中的文件树与缓存统计落到
+            // assistant message 上，供气泡展示「本轮文件记忆」摘要。
             updateAssistant({
-              memoryFilesScopeDir: event.scopeDir,
               memoryFiles: event.files,
-              memoryFilesSync: event.sync,
+              memoryFilesCache: event.cache,
+              memoryFilesStoreName: event.memoryStoreName,
+              memoryFilesWritable: event.writable,
+              memoryFilesScope: event.scope,
+            });
+          } else if (event.type === "memory.save.start") {
+            updateAssistant({
+              memorySaveStatus: "saving",
+              memorySavePath: undefined,
+              memorySaveCount: undefined,
+              memorySaveError: undefined,
+            });
+          } else if (event.type === "memory.save.done") {
+            updateAssistant({
+              memorySaveStatus: event.status,
+              memorySavePath: event.path,
+              memorySaveCount: event.count,
+              memorySaveError: undefined,
             });
           } else if (event.type === "memory.save.skipped") {
-            // 写回失败不打断对话流，留给 logger 处理。
+            updateAssistant({
+              memorySaveStatus: "error",
+              memorySaveError: event.reason,
+            });
+            // 写回失败不打断对话流，同时保留控制台诊断。
             console.warn("[chat] memory.save.skipped:", event.reason);
           } else if (event.type === "reasoning.delta") {
             const buf = pendingDeltasRef.current.get(assistantId) ?? {};
@@ -369,6 +526,14 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
           updateAssistant({ status: "done", ...closeReasoning });
         }
       } finally {
+        cancelScheduledFlush();
+        flushDeltas();
+        const settledMessages = settlePendingMemorySave(
+          messagesRef.current,
+          assistantId,
+        );
+        messagesRef.current = settledMessages;
+        setMessages(settledMessages);
         setIsStreaming(false);
         abortRef.current = null;
         // Flush the latest snapshot to the persist handler.
@@ -376,7 +541,7 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
         // calling side effects during React's render phase.
         const persist = onPersistRef.current;
         if (persist) {
-          persist(messagesRef.current);
+          persist(settledMessages);
         }
       }
     },

package/dist/dashboard-runtime/dashboard/src/i18n/locales/en.ts

@@ -209,6 +209,8 @@ export const messages: Messages = {
         'Are you sure you want to delete memory store "{name}"? This action cannot be undone.',
     },
     card: {
+      inputType: "Input",
+      storageStructure: "Storage",
       longTerm: "Long-term",
       shortTerm: "Short-term",
       extract: "Extract",
@@ -236,6 +238,24 @@ export const messages: Messages = {
         "Only letters, digits, and underscores are allowed, up to 32 characters.",
       descriptionLabel: "Description",
       descriptionPlaceholder: "Describe what this memory store is for...",
+      inputTypeSection: "Input Type",
+      inputTypeSectionDesc:
+        "Choose how memory enters the memory store. Select one input type.",
+      shortTermInputLabel: "Short-term Memory",
+      shortTermInputDescription:
+        "Accept short-term memory from conversations and persist it using the selected storage structure.",
+      fileInputLabel: "Memory Files",
+      fileInputDescription:
+        "Read and write memory files directly. This input fixes the storage structure to memory files.",
+      storageStructureSection: "Memory Storage Structure",
+      storageStructureSectionDesc:
+        "Structured memory is required for short-term input; memory files can be enabled alongside it.",
+      structuredStorageLabel: "Structured Memory",
+      structuredStorageDescription:
+        "Store structured entries with semantic search, extraction, and consolidation.",
+      fileStorageLabel: "Memory Files",
+      fileStorageDescription:
+        "Store a file tree and access it through the file workspace.",
       storageModeSection: "Storage Mode",
       storageModeSectionDesc:
         "Choose the storage backend for the memory store. Cannot be changed after creation.",
@@ -252,15 +272,24 @@ export const messages: Messages = {
       nameMaxLength: "Name cannot exceed 32 characters",
       namePattern: "Only letters, digits, and underscores are allowed",
       descriptionMaxLength: "Description cannot exceed 256 characters",
+      storageStructureRequired: "Select at least one memory storage structure",
+      storageStructureInvalid:
+        "This input type and memory storage structure combination is not supported",
       extractMaxLength: "Extraction instructions cannot exceed 4096 characters",
     },
     storageMode: {
       apiOnlyLabel: "API-only Memory",
       fileLabel: "File Memory",
+      projectedFileLabel: "Read-only File Projection",
+      writableFileLabel: "Writable File Memory",
       apiOnlyDescription:
         "Tablestore only: read and write memory via API semantic retrieval, no file projection.",
       fileDescription:
         "Tablestore + OSS file projection: memory is additionally projected into a markdown file tree, retrievable as files in conversations and browsable in the console and CLI.",
+      projectedFileDescription:
+        "Browse a one-way file+ots projection through the file API. The service handshake controls read-only access; no browser or server-local mirror is maintained.",
+      writableFileDescription:
+        "Full file memory with JSON API create, edit, rename, delete, and version history, directly usable as conversation context.",
     },
     settings: {
       basicInfo: "Basic Information",
@@ -295,6 +324,7 @@ export const messages: Messages = {
       deleteStore: "Delete Memory Store",
       backToList: "Back to list",
       tabUnits: "Long-term Memory",
+      tabFiles: "File Workspace",
       tabSearch: "Memory Search",
       tabMessages: "Short-term Memory",
       tabTasks: "Memory Extraction",
@@ -354,7 +384,9 @@ export const messages: Messages = {
       tableContent: "Content",
       tableType: "Type",
       tableVersion: "Version",
-      tableCreatedAt: "Created At",
+      tableCreatedAt: "Event Time",
+      tableCreatedAtHint:
+        "Event time of the source message this memory describes, not the write time. Falls back to the unit's own stamp, the memcell time, then the server write time when the cited source message has no timestamp; Dream-produced units always carry the server task time. updated_at is the write time.",
       tableActions: "Actions",
       disabledTitle:
         "The current memory unit lacks a precise scope or ID and cannot be operated on",
@@ -372,14 +404,65 @@ export const messages: Messages = {
       detailMetadata: "Metadata",
     },
     files: {
+      scopeOnboardingTitle: "Set a file scope",
+      scopeOnboardingDescription:
+        "Writable file memory is isolated by exact scope. This mode has no server-side scope listing, so enter App, Tenant, Agent, and Run to open the workspace.",
+      recentScopes: "Recently used in this browser (up to 10)",
+      recentScopesLocalHint:
+        "These scopes are stored only in this browser and do not imply that files already exist on the server.",
+      scopeAllRequired:
+        "All four scope fields require concrete values; wildcard * is not allowed",
+      scopeIsolationHint:
+        "Each exact scope has an independent file tree and version history.",
+      setScopeAndEnter: "Set scope and enter file workspace",
       selectFile: "Select a file on the left to view its content",
       readFailed: "Read failed: {error}",
       fileCount: "{count} files",
-      syncNow: "Sync now",
-      emptyHint: "No files yet. Click Sync now to fetch.",
-      syncSuccess: "Synced: +{downloaded} -{deleted}, {total} files total",
-      syncFallback: "Sync failed (using local copy): {error}",
-      syncFailed: "Sync failed",
+      emptyHint: "No files in this scope",
+      searchPlaceholder: "Filter file paths…",
+      newFile: "New file",
+      rename: "Rename",
+      writableMode: "Writable",
+      readOnlyMode: "Read-only projection",
+      readOnlyGuidance:
+        "This store returned a read-only handshake. You can browse and cite files, but cannot modify content or inspect version history.",
+      unsaved: "Unsaved",
+      byteCount: "{count} / {limit} bytes",
+      editorLabel: "File content editor",
+      editorPlaceholder: "Edit UTF-8 text here…",
+      shaConflict:
+        "Another session updated this file. Your text is preserved in the editor; copy it, refresh the latest version, then merge and save again.",
+      discardChanges: "This file has unsaved changes. Discard them?",
+      saveSuccess: "File saved",
+      saveFailed: "Failed to save file",
+      createSuccess: "File created",
+      renameSuccess: "File renamed",
+      deleteSuccess: "File deleted",
+      createTitle: "Create memory file",
+      renameTitle: "Rename file",
+      deleteTitle: "Delete file",
+      deleteDescription:
+        "Delete {path}? Version history is retained, but the current file will disappear.",
+      pathHelp:
+        "Paths use UTF-8 text, are limited to 800 bytes, and cannot contain .. segments.",
+      pathLabel: "File path",
+      initialContent: "Initial content",
+      pathRequired: "Enter a file path",
+      pathTraversal: "File paths cannot contain .. segments",
+      pathTooLarge: "File paths cannot exceed 800 UTF-8 bytes",
+      contentTooLarge: "File content cannot exceed 100 KiB",
+      selectForDetails: "Select a file to inspect metadata and version history",
+      details: "File details",
+      size: "Content size",
+      latestVersion: "Current version",
+      updatedAt: "Updated",
+      versionHistory: "Version history",
+      noVersions: "No previous versions",
+      loadMore: "Load more",
+      contentUnavailable: "This version has no readable content",
+      restoreVersion: "Restore this version",
+      restoreSuccess: "Historical content restored as a new version",
+      restoreFailed: "Failed to restore version",
     },
     add: {
       title: "Add Memory",
@@ -419,7 +502,7 @@ export const messages: Messages = {
       scopeRequiredHint:
         "Set specific values for App and Tenant in the scope bar first.",
       queryRequired: "Please enter a search query",
-      topKRange: "Top K must be between 0 and 50",
+      topKRange: "Top K must be between 1 and 50",
       similarityRange: "Similarity threshold must be between 0 and 1",
       notSearchedTitle: "Not searched yet",
       notSearchedDescription:
@@ -432,7 +515,9 @@ export const messages: Messages = {
       relevance: "Relevance {value}",
       resultId: "ID: {id}",
       resultScope: "Scope: {scope}",
-      resultCreatedAt: "Created: {time}",
+      resultCreatedAt: "Event time: {time}",
+      resultCreatedAtHint:
+        "Event time of the source message this memory describes, not the write time. Falls back to the unit's own stamp, the memcell time, then the server write time when the cited source message has no timestamp; Dream-produced units always carry the server task time. updated_at is the write time.",
       resultVersion: "Version: {version}",
     },
     messages: {
@@ -441,6 +526,7 @@ export const messages: Messages = {
         "Set specific values for all fields in the scope bar above to query short-term memory",
       emptyRange: "No messages in this time range",
       empty: "No message records in the current scope",
+      loadFailed: "Failed to load session messages",
       loadEarlier: "Load earlier messages",
       allLoaded: "— All messages loaded —",
       count: "{count} messages",
@@ -473,6 +559,7 @@ export const messages: Messages = {
       description:
         "Each AddMemories call maps to a task record, showing the processing state from messages to memory entries",
       emptyTitle: "No tasks yet",
+      loadFailed: "Failed to load extraction tasks",
       emptyAll:
         "No ingestion tasks from AddMemories calls under this scope yet. You can trigger memory writes from the Long-term Memory / Search tabs, or run CLI memory add and come back here to check progress.",
       emptyFiltered:
@@ -691,6 +778,14 @@ export const messages: Messages = {
       appIdRequired: "appId is required",
       atLeastOneNonWildcard: "Specify at least one non-wildcard field",
       atLeastOneScope: "At least one scope",
+      scopesLimit: "No more than 20 scopes are allowed",
+      instructionsLimit: "Instructions cannot exceed 4000 UTF-8 bytes",
+      maxSessionsRange: "Max sessions must be an integer between 1 and 100",
+      maxMessagesRange: "Max messages must be an integer between 1 and 20000",
+      maxMemoriesRange: "Max memories must be an integer between 1 and 5000",
+      thresholdRange: "Confidence threshold must be between 0 and 1",
+      timestampInvalid: "Invalid timestamp format",
+      timestampOrder: "Latest time cannot be earlier than earliest time",
       actions: {
         allStatus: "All statuses",
         allTypes: "All types",
@@ -1209,11 +1304,12 @@ export const messages: Messages = {
       modeSearchTitle: "Semantic Search",
       modeSearchDesc: "Vector-search the memory store each turn",
       modeLocalTitle: "File Memory",
-      modeLocalDescEnabled: "Local search after syncing projected files",
+      modeLocalDescEnabled: "Local search after caching through the file API",
+      modeLocalDescWritable: "filemem always uses file retrieval",
       modeLocalDescDisabled:
         "Only available for memory stores that support file memory",
       localHint:
-        "Memory is projected into a local mirror directory as a markdown file tree; synced before each turn and searched on the files. Memory is aggregated per user (app + tenant); agent / run fields do not affect file content.",
+        "Before each turn, the browser paginates the file API, reuses bodies by SHA, and performs bounded lexical retrieval in this tab. No FUSE process or server-local mirror is created.",
       viewFiles: "View memory files",
       viewFilesHint: "Please fill in the complete app / tenant / agent first",
       emptyNoStoresTitle: "No memory stores yet",
@@ -1242,6 +1338,8 @@ export const messages: Messages = {
       autoSave: "Auto-write memory after the conversation",
       autoSaveDesc:
         "Auto-archive: write this turn's user / assistant messages to the current scope",
+      autoSaveFilememDesc:
+        "Extract durable memories from each turn and append them to a dated memory file",
       runIdLabel: "Run ID",
       runIdTitle:
         "The run ID is generated automatically for the current conversation and reused throughout it to link memory of the same session",
@@ -1252,7 +1350,8 @@ export const messages: Messages = {
     },
     filesDialog: {
       title: "Memory Files",
-      description: "Mirror directory of memory files for this scope",
+      description:
+        "Manage virtual files and versions for this exact scope through the file API",
     },
     history: {
       newChat: "New Chat",
@@ -1317,6 +1416,11 @@ export const messages: Messages = {
       edit: "Edit",
       resend: "Resend",
       regenerate: "Regenerate",
+      saveToFile: "Save response to file memory",
+      savePathPrompt: "Enter a file path in filemem",
+      saveToFileInvalid: "The path is invalid or the response exceeds 100 KiB",
+      savedToFile: "Response saved to {path}",
+      saveToFileFailed: "Failed to save response to file memory",
       summarizeSkill: "Summarize skill to knowledge base",
       extractProfile: "Extract profile to knowledge base",
       delete: "Delete",
@@ -1346,6 +1450,10 @@ export const messages: Messages = {
       generateFailed: "Generation failed",
       elapsedSeconds: "Took {seconds}s",
       elapsedMinutes: "Took {minutes}m {seconds}s",
+      memorySaving: "Extracting file memory…",
+      memorySaved: "Saved {count} durable memories",
+      memoryUnchanged: "No durable memory needed for this turn",
+      memorySaveFailed: "File-memory extraction failed: {error}",
     },
     chunks: {
       viewCitations: "View {count} citations",
@@ -1363,9 +1471,10 @@ export const messages: Messages = {
       referenceCount: "Referenced {count} memory entries",
       unnamedMemory: "Unnamed memory",
       filesThisTurn: "{count} memory files this turn",
-      syncFailed: "Sync failed (using local copy): {error}",
-      syncSummary: "+{added} -{deleted} · {total} total",
-      emptyFiles: "No memory files in this scope (not projected or synced yet)",
+      cacheFailed: "File API cache failed: {error}",
+      cacheSummary: "Read {loaded} · SHA reused {reused} · {total} total",
+      cacheTruncated: "Reached the 300-file / 3-MiB retrieval limit",
+      emptyFiles: "No retrievable memory files in this exact scope",
       fileSize: "{size} B",
     },
     panel: {