@tablestore/tablestore-agent-cli 0.2.7 → 0.2.9

package/dist/dashboard-runtime/dashboard/src/app/api/v1/llm/chat/file-memory-helpers.ts

@@ -0,0 +1,93 @@
+import {
+  defaultFileMemoryRoot,
+  listLocalMemoryFiles,
+  searchLocalMemories,
+  syncMemoryMount,
+  type LocalMemoryHit,
+  type MountScope,
+} from "@tablestore/tablestore-agent-sdk";
+import type { MemoryClient } from "@tablestore/tablestore-agent-sdk";
+
+import type { MemoryFilesSyncSummary } from "@/types/llm-chat";
+
+/**
+ * 文件记忆（openclaw local 模式同款）的单轮检索结果。
+ * `hits` 供注入与 memory.done 事件；`files`/`sync` 供 memory.files 事件。
+ */
+export interface FileMemoryTurnResult {
+  hits: LocalMemoryHit[];
+  scopeDir: string;
+  files: Array<{ rel: string; size: number }>;
+  sync: MemoryFilesSyncSummary;
+}
+
+/**
+ * 一轮对话的文件记忆链路：AuthorizeMemoryMount（STS）→ OSS 增量同步到本地
+ * 镜像目录 → 本地词法检索 → 收集文件树。同步失败不抛错——继续用本地
+ * 旧副本检索（openclaw 同款降级行为）。
+ */
+export async function runFileMemoryRetrieval(opts: {
+  memoryClient: MemoryClient;
+  otsInstanceName: string;
+  memoryStoreName: string;
+  scope: MountScope;
+  query: string;
+  topK: number;
+}): Promise<FileMemoryTurnResult> {
+  const localRoot = defaultFileMemoryRoot(
+    opts.otsInstanceName,
+    opts.memoryStoreName,
+  );
+  const sync = await syncMemoryMount({
+    authorizeMount: (request) =>
+      opts.memoryClient.authorizeMemoryMount(request),
+    memoryStoreName: opts.memoryStoreName,
+    scope: opts.scope,
+    localRoot,
+  });
+  const search = searchLocalMemories({
+    scopeDir: sync.scopeDir,
+    query: opts.query,
+    topK: opts.topK,
+  });
+  const files = listLocalMemoryFiles(sync.scopeDir).map((f) => ({
+    rel: f.rel,
+    size: f.size,
+  }));
+  return {
+    hits: search.results,
+    scopeDir: sync.scopeDir,
+    files,
+    sync: {
+      ok: sync.ok,
+      downloaded: sync.downloaded,
+      deleted: sync.deleted,
+      total: sync.total,
+      ...(sync.error ? { error: sync.error } : {}),
+    },
+  };
+}
+
+/**
+ * 文件记忆注入块（openclaw 同款）：固定的目录挂载通知 +（有命中时）
+ * `## TableStore Memory` 编号片段列表。返回值以 `\n\n` 开头，供
+ * `buildFinalMessages` 直接拼接到 system message 末尾。
+ */
+export function formatFileMemoryBlock(
+  scopeDir: string,
+  hits: LocalMemoryHit[],
+): string {
+  const dirNotice = [
+    "## TableStore File Memory",
+    `This conversation's long-term memory tree is mounted read-only at: ${scopeDir}`,
+    "(start at index.md; do NOT read sibling directories — they belong to other scopes)",
+  ].join("\n");
+  if (!hits.length) return `\n\n${dirNotice}`;
+  const lines = ["## TableStore Memory"];
+  hits.forEach((hit, index) => {
+    lines.push(
+      `${index + 1}. ${hit.unit.text} [score=${hit.score.toFixed(3)}, source=${hit.unit.source}]`,
+    );
+  });
+  return `\n\n${dirNotice}\n\n${lines.join("\n")}`;
+}

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

@@ -1,6 +1,10 @@
 import { type NextRequest } from "next/server";
 
-import { chatCompletionStream, type LLMMessageContent, type ContentPart } 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 {
@@ -26,6 +30,10 @@ import {
   formatMemoryBlock,
   type MemoryWriteScope,
 } from "./memory-helpers";
+import {
+  formatFileMemoryBlock,
+  runFileMemoryRetrieval,
+} from "./file-memory-helpers";
 
 // Default aggregate cap when the client omits `rag.topK`.
 const DEFAULT_AGGREGATE_TOP_K = 20;
@@ -49,6 +57,7 @@ export const dynamic = "force-dynamic";
 function buildDefaultPreamble(opts: {
   hasRag: boolean;
   hasMemory: boolean;
+  isFileMemory?: boolean;
 }): string {
   const parts: string[] = [
     "你是一个智能助手，请基于下方提供的上下文（如有）回答用户的问题。",
@@ -59,7 +68,14 @@ function buildDefaultPreamble(opts: {
         "对于直接援引检索结果的事实性陈述，可在句末用 [1][2] 标注来源；通用性陈述无需逐句标注。",
     );
   }
-  if (opts.hasMemory) {
+  if (opts.hasMemory && opts.isFileMemory) {
+    parts.push(
+      "下方的「TableStore File Memory / TableStore Memory」段来自该用户/场景的" +
+        "长期记忆文件（记忆以 markdown 文件树投影，片段末尾的 source 标注了" +
+        "所属文件）。请将这些记忆作为已知的用户偏好或上下文自然融入回答；" +
+        "无需显式引用编号，也不要因为某条记忆未涉及就拒绝回答。",
+    );
+  } else if (opts.hasMemory) {
     parts.push(
       "下方还会给出「相关历史记忆」，记录了你与该用户/场景过往的对话沉淀。" +
         "请将这些记忆作为已知的用户偏好或上下文自然融入回答；" +
@@ -180,22 +196,14 @@ export async function POST(request: NextRequest) {
   if (body.rag) {
     const projectContext = validateChatProjectContext(
       request,
-      activeInstanceProvided ? body.activeInstance ?? null : undefined,
+      activeInstanceProvided ? (body.activeInstance ?? null) : undefined,
     );
     if (!projectContext.ok) {
-      return jsonError(
-        409,
-        "PROJECT_CONTEXT_CHANGED",
-        projectContext.message,
-      );
+      return jsonError(409, "PROJECT_CONTEXT_CHANGED", projectContext.message);
     }
     kbClient = await resolveKbClient(request);
     if (!kbClient.ok) {
-      return jsonError(
-        kbClient.status,
-        kbClient.code,
-        kbClient.message,
-      );
+      return jsonError(kbClient.status, kbClient.code, kbClient.message);
     }
   }
 
@@ -207,15 +215,23 @@ export async function POST(request: NextRequest) {
     if (!body.rag) {
       const projectContext = validateChatProjectContext(
         request,
-        activeInstanceProvided ? body.activeInstance ?? null : undefined,
+        activeInstanceProvided ? (body.activeInstance ?? null) : undefined,
       );
       if (!projectContext.ok) {
-        return jsonError(409, "PROJECT_CONTEXT_CHANGED", projectContext.message);
+        return jsonError(
+          409,
+          "PROJECT_CONTEXT_CHANGED",
+          projectContext.message,
+        );
       }
     }
     memoryClient = await resolveMemoryClient(request);
     if (!memoryClient.ok) {
-      return jsonError(memoryClient.status, memoryClient.code, memoryClient.message);
+      return jsonError(
+        memoryClient.status,
+        memoryClient.code,
+        memoryClient.message,
+      );
     }
   }
 
@@ -237,7 +253,9 @@ export async function POST(request: NextRequest) {
       const startedAt = Date.now();
       const logContext = getApiLogContext();
       const emit = (event: ChatStreamEvent) => {
-        controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
+        controller.enqueue(
+          encoder.encode(`data: ${JSON.stringify(event)}\n\n`),
+        );
       };
 
       let closed = false;
@@ -319,38 +337,80 @@ export async function POST(request: NextRequest) {
 
         // ---- Memory 检索 ----
         let memoryHits: MemorySearchHit[] = [];
+        let memoryBlock = "";
+        const isFileMemory = body.memory?.retrievalMode === "local";
         if (body.memory && memoryClient?.ok) {
           // 仅当 RAG 实际命中（chunks 非空）时才复用其 rewrite 后的 query；否则回退到原始用户输入，
           // 避免在无召回时把 rewriter 的猜测当成记忆检索的输入。
-          const memoryQuery = chunks.length > 0 ? queryForMemory : lastUser.content;
+          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 {
+          if (isFileMemory) {
+            // 文件记忆（openclaw local 模式同款）：挂载同步 → 本地词法检索。
+            // 同步失败在 runFileMemoryRetrieval 内部降级为「用本地旧副本」，
+            // 只有意外异常才落到 catch —— 与语义检索一样不阻塞主流。
+            try {
+              const fm = await runFileMemoryRetrieval({
+                memoryClient: memoryClient.client,
+                otsInstanceName: memoryClient.otsInstanceName,
+                memoryStoreName: body.memory.memoryStoreName,
+                scope: body.memory.scope as MemoryWriteScope,
+                query: memoryQuery,
+                topK: body.memory.topK ?? 5,
+              });
+              emit({
+                type: "memory.files",
+                scopeDir: fm.scopeDir,
+                files: fm.files,
+                sync: fm.sync,
+              });
+              memoryHits = fm.hits.map((h) => ({
+                unit: { text: h.unit.text },
+                score: h.score,
+                source: h.unit.source,
+              }));
+              memoryBlock = formatFileMemoryBlock(fm.scopeDir, fm.hits);
+            } catch (err) {
               chatLogger.warn({
-                event: "api.memory.search_failed",
-                message: resp.message ?? "searchMemories returned non-SUCCESS",
-                details: { code: resp.code },
+                event: "api.memory.file_memory_exception",
+                message: err instanceof Error ? err.message : String(err),
+                error: err,
               });
             }
-          } catch (err) {
-            chatLogger.warn({
-              event: "api.memory.search_exception",
-              message: err instanceof Error ? err.message : String(err),
-              error: err,
-            });
+          } else {
+            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,
+              });
+            }
+            memoryBlock = formatMemoryBlock(memoryHits);
           }
           emit({ type: "memory.done", hits: memoryHits });
         }
@@ -360,8 +420,9 @@ export async function POST(request: NextRequest) {
           body.systemPrompt ?? "",
           chunks,
           groupsForPrompt,
-          formatMemoryBlock(memoryHits),
+          memoryBlock,
           body.messages,
+          { isFileMemory },
         );
 
         // ---- Stream upstream completion ----
@@ -511,7 +572,10 @@ function jsonError(status: number, code: string, message: string): Response {
  * decide whether to fail the whole request or only skip RAG.
  */
 async function resolveKbClient(request: NextRequest): Promise<
-  | { ok: true; client: import("@tablestore/tablestore-agent-sdk").KnowledgeBaseClient }
+  | {
+      ok: true;
+      client: import("@tablestore/tablestore-agent-sdk").KnowledgeBaseClient;
+    }
   | { ok: false; status: number; code: string; message: string }
 > {
   const resolved = requireClients(request);
@@ -536,7 +600,12 @@ async function resolveKbClient(request: NextRequest): Promise<
  * error descriptor instead of returning the Response directly.
  */
 async function resolveMemoryClient(request: NextRequest): Promise<
-  | { ok: true; client: import("@tablestore/tablestore-agent-sdk").MemoryClient }
+  | {
+      ok: true;
+      client: import("@tablestore/tablestore-agent-sdk").MemoryClient;
+      /** 文件记忆的本地镜像目录按 OTS 实例名分层，随凭据一起解析出来。 */
+      otsInstanceName: string;
+    }
   | { ok: false; status: number; code: string; message: string }
 > {
   const resolved = requireClients(request);
@@ -549,7 +618,11 @@ async function resolveMemoryClient(request: NextRequest): Promise<
       message: body?.message ?? "Failed to resolve credentials",
     };
   }
-  return { ok: true, client: resolved.memory };
+  return {
+    ok: true,
+    client: resolved.memory,
+    otsInstanceName: resolved.config?.ots_instance_name ?? "",
+  };
 }
 
 /** @internal Exported for unit testing multimodal message construction. */
@@ -559,12 +632,14 @@ export function buildFinalMessages(
   groups: RetrievalGroup[],
   memoryBlock: string,
   history: Array<{ role: ChatRole; content: string }>,
+  opts?: { isFileMemory?: boolean },
 ): Array<{ role: ChatRole; content: LLMMessageContent }> {
   const preamble =
     userSystemPrompt.trim() ||
     buildDefaultPreamble({
       hasRag: chunks.length > 0,
       hasMemory: memoryBlock.length > 0,
+      isFileMemory: opts?.isFileMemory,
     });
 
   // ---- 分离文本 chunk 与图片 chunk ----
@@ -572,8 +647,10 @@ export function buildFinalMessages(
   // IMAGE chunk 移至 user message 与 image_url 紧邻，避免跨 message 关联。
   // 例外：IMAGE chunk 无 imageBase64 时无法在 user message 中展示，降级到
   // system message 作为文本条目。
-  const textChunks: Array<{ chunk: RetrievedChunk; originalIndex: number }> = [];
-  const imageChunks: Array<{ chunk: RetrievedChunk; originalIndex: number }> = [];
+  const textChunks: Array<{ chunk: RetrievedChunk; originalIndex: number }> =
+    [];
+  const imageChunks: Array<{ chunk: RetrievedChunk; originalIndex: number }> =
+    [];
   chunks.forEach((c, i) => {
     if (isImageChunk(c) && c.imageBase64) {
       imageChunks.push({ chunk: c, originalIndex: i });
@@ -649,10 +726,10 @@ export function buildFinalMessages(
         { type: "text", text: lastMessage.content },
         ...imageContentParts,
       ];
-      messages.push(
-        ...clipped.slice(0, lastIndex),
-        { role: "user" as const, content: multimodalContent },
-      );
+      messages.push(...clipped.slice(0, lastIndex), {
+        role: "user" as const,
+        content: multimodalContent,
+      });
     } else {
       // 最后一条不是 user（罕见），追加合成 user message 承载图片
       chatLogger.warn({
@@ -666,13 +743,10 @@ export function buildFinalMessages(
           historyLength: clipped.length,
         },
       });
-      messages.push(
-        ...clipped,
-        {
-          role: "user" as const,
-          content: imageContentParts,
-        },
-      );
+      messages.push(...clipped, {
+        role: "user" as const,
+        content: imageContentParts,
+      });
     }
   } else {
     // 无历史记录 — 新建 user message
@@ -727,7 +801,10 @@ async function retrieveFromAllKbs(
   const groups: RetrievalGroup[] = settled.map((outcome, idx) => {
     const mount = mounts[idx];
     if (outcome.status === "fulfilled") {
-      return { knowledgeBaseName: mount.knowledgeBaseName, chunks: outcome.value };
+      return {
+        knowledgeBaseName: mount.knowledgeBaseName,
+        chunks: outcome.value,
+      };
     }
     const reason = outcome.reason;
     return {
@@ -753,11 +830,22 @@ async function retrieveFromAllKbs(
 function buildKbRetrievalConfiguration(
   mount: ChatRagKnowledgeBase,
 ): Record<string, unknown> | undefined {
-  const cfg: Record<string, unknown> = { ...(mount.retrievalConfiguration ?? {}) };
+  const cfg: Record<string, unknown> = {
+    ...(mount.retrievalConfiguration ?? {}),
+  };
   if (typeof mount.topK === "number") {
-    const dense = (cfg.denseVectorSearchConfiguration ?? {}) as Record<string, unknown>;
-    const fulltext = (cfg.fullTextSearchConfiguration ?? {}) as Record<string, unknown>;
-    const rerank = (cfg.rerankingConfiguration ?? {}) as Record<string, unknown>;
+    const dense = (cfg.denseVectorSearchConfiguration ?? {}) as Record<
+      string,
+      unknown
+    >;
+    const fulltext = (cfg.fullTextSearchConfiguration ?? {}) as Record<
+      string,
+      unknown
+    >;
+    const rerank = (cfg.rerankingConfiguration ?? {}) as Record<
+      string,
+      unknown
+    >;
     cfg.denseVectorSearchConfiguration = {
       numberOfResults: mount.topK,
       ...dense,

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

@@ -9,10 +9,7 @@ import {
   handleApiError,
   successResponse,
 } from "@/lib/server/api-helpers";
-import {
-  createProvider,
-  listProviders,
-} from "@/lib/server/llm-provider-store";
+import { createProvider, listProviders } from "@/lib/server/llm-provider-store";
 import { createLLMProviderSchema } from "@/schemas/llm-provider";
 
 /**

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

@@ -18,34 +18,51 @@ export async function POST(request: NextRequest) {
 
   const length = Number(request.headers.get("content-length") ?? "0");
   if (Number.isFinite(length) && length > MAX_CLIENT_LOG_BYTES) {
-    return errorResponse("BAD_REQUEST", "Client log payload is too large", 400, {
-      errorSource: "browser",
-    });
+    return errorResponse(
+      "BAD_REQUEST",
+      "Client log payload is too large",
+      400,
+      {
+        errorSource: "browser",
+      },
+    );
   }
 
   const raw = await request.text();
   if (Buffer.byteLength(raw, "utf8") > MAX_CLIENT_LOG_BYTES) {
-    return errorResponse("BAD_REQUEST", "Client log payload is too large", 400, {
-      errorSource: "browser",
-    });
+    return errorResponse(
+      "BAD_REQUEST",
+      "Client log payload is too large",
+      400,
+      {
+        errorSource: "browser",
+      },
+    );
   }
 
   let body: Record<string, unknown>;
   try {
     const parsed = JSON.parse(raw) as unknown;
-    body = parsed && typeof parsed === "object" && !Array.isArray(parsed)
-      ? (parsed as Record<string, unknown>)
-      : {};
+    body =
+      parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>)
+        : {};
   } catch {
-    return errorResponse("BAD_REQUEST", "Client log payload must be JSON", 400, {
-      errorSource: "browser",
-    });
+    return errorResponse(
+      "BAD_REQUEST",
+      "Client log payload must be JSON",
+      400,
+      {
+        errorSource: "browser",
+      },
+    );
   }
 
   const event = typeof body.event === "string" ? body.event : "browser.error";
   const message =
     typeof body.message === "string" ? body.message : "Browser error captured";
-  const level = body.level === "warn" || body.level === "info" ? body.level : "error";
+  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;

package/dist/dashboard-runtime/dashboard/src/app/api/v1/memory/stores/[store]/dream-kb-sync/route.ts

@@ -0,0 +1,78 @@
+// dashboard/src/app/api/v1/memory/stores/[store]/dream-kb-sync/route.ts
+import { type NextRequest } from "next/server";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+import {
+  errorResponse,
+  handleApiError,
+  requireClients,
+  successResponse,
+} from "@/lib/server/api-helpers";
+import { depositDreamTaskToKb } from "@/lib/server/dream-kb-sync";
+import type { DreamKind } from "@/lib/dream-kb/types";
+
+interface RouteContext {
+  params: Promise<{ store: string }>;
+}
+
+const ALL_KINDS: DreamKind[] = ["skill", "profile"];
+
+/**
+ * POST /api/v1/memory/stores/[store]/dream-kb-sync
+ *
+ * 会话内沉淀：把某个 dream 抽取任务（dreamId）的产出按会话落到目标知识库。
+ * body: { dreamId, knowledgeBaseName, kinds? }
+ */
+export async function POST(request: NextRequest, context: RouteContext) {
+  try {
+    const { store } = await context.params;
+    const auth = requireClients(request);
+    if (!("memory" in auth)) return auth;
+    const { memory, kb, config } = auth;
+
+    let body: Record<string, unknown>;
+    try {
+      body = (await request.json()) as Record<string, unknown>;
+    } catch {
+      return errorResponse("BAD_REQUEST", "Request body must be JSON", 400);
+    }
+
+    // 沉淀走 OSS 上传，需要 AK/SK；纯 API Key 不支持。
+    if (!config.access_key_id || !config.access_key_secret) {
+      return errorResponse(
+        "OSS_CREDENTIALS_REQUIRED",
+        "沉淀功能需要配置 AK/SK 与 OSS，纯 API Key 不支持。",
+        400,
+      );
+    }
+
+    const dreamId = typeof body.dreamId === "string" ? body.dreamId : "";
+    if (!dreamId) {
+      return errorResponse("BAD_REQUEST", "dreamId is required", 400);
+    }
+    const knowledgeBaseName =
+      typeof body.knowledgeBaseName === "string" ? body.knowledgeBaseName : "";
+    if (!knowledgeBaseName) {
+      return errorResponse("BAD_REQUEST", "knowledgeBaseName is required", 400);
+    }
+    const kinds: DreamKind[] = Array.isArray(body.kinds)
+      ? body.kinds.filter(
+          (k): k is DreamKind => k === "skill" || k === "profile",
+        )
+      : ALL_KINDS;
+
+    const result = await depositDreamTaskToKb({
+      memory,
+      kb,
+      memoryStoreName: store,
+      dreamId,
+      knowledgeBaseName,
+      kinds,
+    });
+    return successResponse(result);
+  } catch (error) {
+    return handleApiError(error);
+  }
+}

package/dist/dashboard-runtime/dashboard/src/app/api/v1/memory/stores/[store]/dream-tasks/[dreamId]/actions/route.ts

@@ -92,7 +92,8 @@ export async function GET(request: NextRequest, context: RouteContext) {
     return successResponse({
       items,
       totalCount: items.length,
-      nextToken: typeof data.nextToken === "string" ? data.nextToken : undefined,
+      nextToken:
+        typeof data.nextToken === "string" ? data.nextToken : undefined,
       memoryStoreName: store,
       dreamId,
     });

package/dist/dashboard-runtime/dashboard/src/app/api/v1/memory/stores/[store]/dream-tasks/route.ts

@@ -63,7 +63,8 @@ export async function GET(request: NextRequest, context: RouteContext) {
     return successResponse({
       items,
       totalCount: items.length,
-      nextToken: typeof data.nextToken === "string" ? data.nextToken : undefined,
+      nextToken:
+        typeof data.nextToken === "string" ? data.nextToken : undefined,
       scope: data.scope ?? scope,
       memoryStoreName: store,
     });

package/dist/dashboard-runtime/dashboard/src/app/api/v1/memory/stores/[store]/file-memory/_helpers.ts

@@ -0,0 +1,42 @@
+import {
+  defaultFileMemoryRoot,
+  fileMemoryScopeDir,
+  normalizeMountScope,
+  type MountScope,
+} from "@tablestore/tablestore-agent-sdk";
+
+/**
+ * 从 query / body 里读出文件记忆挂载 scope。appId 必填；其余空字段由
+ * normalizeMountScope 归一化成 `__default__`（openclaw 同款，禁通配符）。
+ * appId 缺失时返回 null，调用方回 400。
+ */
+export function readMountScope(
+  raw: Record<string, unknown> | URLSearchParams | null | undefined,
+): MountScope | null {
+  const get = (key: string): string => {
+    if (raw instanceof URLSearchParams) {
+      return raw.get(key) ?? "";
+    }
+    const value = raw?.[key];
+    return typeof value === "string" ? value : "";
+  };
+  const appId = get("appId").trim();
+  if (!appId || appId === "*") return null;
+  return normalizeMountScope({
+    appId,
+    tenantId: get("tenantId"),
+    agentId: get("agentId"),
+    runId: get("runId"),
+  });
+}
+
+/** store + 实例名 + scope → 本地镜像 scope 目录（与 CLI 共享的约定）。
+ *  目录按 user 粒度聚合，同一用户不同会话共享同一路径。 */
+export function resolveScopeDir(
+  otsInstanceName: string,
+  store: string,
+  scope: MountScope,
+): { localRoot: string; scopeDir: string } {
+  const localRoot = defaultFileMemoryRoot(otsInstanceName, store);
+  return { localRoot, scopeDir: fileMemoryScopeDir(localRoot, scope) };
+}