@tablestore/tablestore-agent-cli 0.2.10 → 0.2.11

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

@@ -209,6 +209,8 @@ export const messages = {
       deleteConfirm: '确定要删除记忆库 "{name}" 吗？此操作不可撤销。',
     },
     card: {
+      inputType: "输入",
+      storageStructure: "存储",
       longTerm: "长期",
       shortTerm: "短期",
       extract: "抽取",
@@ -235,6 +237,22 @@ export const messages = {
       nameDesc: "仅支持字母、数字和下划线，最多 32 个字符。",
       descriptionLabel: "描述",
       descriptionPlaceholder: "描述这个记忆库的用途...",
+      inputTypeSection: "输入类型",
+      inputTypeSectionDesc: "选择记忆如何进入记忆库。输入类型仅支持单选。",
+      shortTermInputLabel: "短期记忆",
+      shortTermInputDescription:
+        "接收对话产生的短期记忆，并按照所选存储结构进行持久化。",
+      fileInputLabel: "记忆文件",
+      fileInputDescription:
+        "直接读写记忆文件；选择后，存储结构固定为记忆文件。",
+      storageStructureSection: "记忆存储结构",
+      storageStructureSectionDesc:
+        "结构化记忆为短期记忆输入的必选项，可同时启用记忆文件。",
+      structuredStorageLabel: "结构化记忆",
+      structuredStorageDescription:
+        "以结构化条目保存，支持语义检索、记忆抽取和整理。",
+      fileStorageLabel: "记忆文件",
+      fileStorageDescription: "以文件树形式保存，并通过文件工作区访问。",
       storageModeSection: "存储模式",
       storageModeSectionDesc: "选择记忆库的存储后端。创建后不可修改。",
       extractSection: "记忆抽取指令",
@@ -249,15 +267,23 @@ export const messages = {
       nameMaxLength: "名称不能超过 32 个字符",
       namePattern: "只能包含字母、数字和下划线",
       descriptionMaxLength: "描述不超过 256 字",
+      storageStructureRequired: "请至少选择一种记忆存储结构",
+      storageStructureInvalid: "输入类型与记忆存储结构的组合不受支持",
       extractMaxLength: "抽取指令不超过 4096 字",
     },
     storageMode: {
       apiOnlyLabel: "仅 API 记忆",
       fileLabel: "支持文件记忆",
+      projectedFileLabel: "只读文件投影",
+      writableFileLabel: "可写文件记忆",
       apiOnlyDescription:
         "仅 Tablestore：通过 API 语义检索读写记忆，不生成文件投影。",
       fileDescription:
         "Tablestore + OSS 文件投影：记忆额外投影成 markdown 文件树，可在对话中以文件形式检索、在控制台与 CLI 浏览目录结构。",
+      projectedFileDescription:
+        "通过文件 API 浏览 file+ots 单向投影；服务端握手决定只读状态，不维护浏览器或服务端本地镜像。",
+      writableFileDescription:
+        "完整文件记忆：通过 JSON API 新建、编辑、重命名、删除并查看版本历史，可直接为对话提供文件上下文。",
     },
     settings: {
       basicInfo: "基本信息",
@@ -291,6 +317,7 @@ export const messages = {
       deleteStore: "删除记忆库",
       backToList: "返回列表",
       tabUnits: "长期记忆",
+      tabFiles: "文件工作区",
       tabSearch: "记忆检索",
       tabMessages: "短期记忆",
       tabTasks: "记忆抽取",
@@ -346,7 +373,9 @@ export const messages = {
       tableContent: "内容",
       tableType: "类型",
       tableVersion: "版本",
-      tableCreatedAt: "创建时间",
+      tableCreatedAt: "事件时间",
+      tableCreatedAtHint:
+        "记忆单元所描述的来源消息的事件时间，而不是写入时间。若引用的来源消息没有时间戳，则依次回退到单元自身时间、memcell 时间和服务端写入时间；Dream 产出的单元始终为服务端任务时间。updated_at 才是写入时间。",
       tableActions: "操作",
       disabledTitle: "当前记忆单元缺少精确范围或 ID，无法操作",
       view: "查看详情",
@@ -363,14 +392,61 @@ export const messages = {
       detailMetadata: "元数据",
     },
     files: {
+      scopeOnboardingTitle: "设置文件范围",
+      scopeOnboardingDescription:
+        "可读写文件记忆按精确 scope 隔离。此模式不提供服务端 scope 列表，请填写应用、租户、智能体和会话后进入文件工作区。",
+      recentScopes: "本浏览器最近使用的文件范围（最多 10 条）",
+      recentScopesLocalHint:
+        "这些范围只保存在当前浏览器中，不代表服务端已存在对应文件。",
+      scopeAllRequired: "四个范围字段都必须填写具体值，不能使用通配符 *",
+      scopeIsolationHint: "每个精确范围拥有独立的文件目录和版本历史。",
+      setScopeAndEnter: "设置范围并进入文件工作区",
       selectFile: "选择左侧文件查看内容",
       readFailed: "读取失败：{error}",
       fileCount: "共 {count} 个文件",
-      syncNow: "立即同步",
-      emptyHint: "暂无文件，点击「立即同步」拉取",
-      syncSuccess: "已同步：+{downloaded} -{deleted}，共 {total} 个文件",
-      syncFallback: "同步失败（沿用本地副本）：{error}",
-      syncFailed: "同步失败",
+      emptyHint: "当前范围暂无文件",
+      searchPlaceholder: "筛选文件路径…",
+      newFile: "新建文件",
+      rename: "重命名",
+      writableMode: "可读写",
+      readOnlyMode: "只读投影",
+      readOnlyGuidance:
+        "该记忆库返回了只读握手；你可以浏览和引用文件，但不能修改内容或查看版本历史。",
+      unsaved: "未保存",
+      byteCount: "{count} / {limit} 字节",
+      editorLabel: "文件内容编辑器",
+      editorPlaceholder: "在这里编辑 UTF-8 文本…",
+      shaConflict:
+        "文件已被其他会话更新。你的文本仍保留在编辑器中；请复制内容、刷新最新版本后再合并保存。",
+      discardChanges: "当前文件有未保存的修改，确定要放弃吗？",
+      saveSuccess: "文件已保存",
+      saveFailed: "保存文件失败",
+      createSuccess: "文件已创建",
+      renameSuccess: "文件已重命名",
+      deleteSuccess: "文件已删除",
+      createTitle: "新建记忆文件",
+      renameTitle: "重命名文件",
+      deleteTitle: "删除文件",
+      deleteDescription: "确定删除 {path}？历史版本将保留，但当前文件会消失。",
+      pathHelp: "路径使用 UTF-8 文本，最长 800 字节，并且不能包含 .. 段。",
+      pathLabel: "文件路径",
+      initialContent: "初始内容",
+      pathRequired: "请输入文件路径",
+      pathTraversal: "文件路径不能包含 .. 段",
+      pathTooLarge: "文件路径不能超过 800 个 UTF-8 字节",
+      contentTooLarge: "文件内容不能超过 100 KiB",
+      selectForDetails: "选择文件后查看元数据与版本历史",
+      details: "文件详情",
+      size: "内容大小",
+      latestVersion: "当前版本",
+      updatedAt: "更新时间",
+      versionHistory: "版本历史",
+      noVersions: "暂无历史版本",
+      loadMore: "加载更多",
+      contentUnavailable: "该版本没有可读取的内容",
+      restoreVersion: "恢复为此版本",
+      restoreSuccess: "历史版本已恢复为新版本",
+      restoreFailed: "恢复版本失败",
     },
     add: {
       title: "添加记忆",
@@ -408,7 +484,7 @@ export const messages = {
       scopeRequired: "请先在范围栏中设置「应用」和「租户」的具体值",
       scopeRequiredHint: "请先在范围栏中设置「应用」和「租户」的具体值。",
       queryRequired: "请输入检索内容",
-      topKRange: "Top K 必须在 0 到 50 之间",
+      topKRange: "Top K 必须在 1 到 50 之间",
       similarityRange: "相似度阈值必须在 0 到 1 之间",
       notSearchedTitle: "尚未搜索",
       notSearchedDescription:
@@ -420,7 +496,9 @@ export const messages = {
       relevance: "相关度 {value}",
       resultId: "ID：{id}",
       resultScope: "范围：{scope}",
-      resultCreatedAt: "创建时间：{time}",
+      resultCreatedAt: "事件时间：{time}",
+      resultCreatedAtHint:
+        "记忆单元所描述的来源消息的事件时间，而不是写入时间。若引用的来源消息没有时间戳，则依次回退到单元自身时间、memcell 时间和服务端写入时间；Dream 产出的单元始终为服务端任务时间。updated_at 才是写入时间。",
       resultVersion: "版本：{version}",
     },
     messages: {
@@ -429,6 +507,7 @@ export const messages = {
         "请在上方范围栏中为所有字段设置具体值以查询短期记忆",
       emptyRange: "该时间范围内暂无消息",
       empty: "当前范围下暂无消息记录",
+      loadFailed: "加载会话消息失败",
       loadEarlier: "加载更早的消息",
       allLoaded: "— 已加载全部消息 —",
       count: "共 {count} 条消息",
@@ -461,6 +540,7 @@ export const messages = {
       description:
         "每条 AddMemories 调用对应一个任务记录，展示从消息到记忆条目的处理状态",
       emptyTitle: "暂无任务",
+      loadFailed: "加载抽取任务失败",
       emptyAll:
         "该 scope 下还没有 AddMemories 调用产生的入库任务。可以在长期记忆 / 检索 Tab 触发记忆写入，或调用 CLI memory add 后回到这里查看进度。",
       emptyFiltered:
@@ -669,6 +749,14 @@ export const messages = {
       appIdRequired: "appId 必填",
       atLeastOneNonWildcard: "至少指定一个非通配符字段",
       atLeastOneScope: "至少一个 scope",
+      scopesLimit: "scope 最多 20 个",
+      instructionsLimit: "指令不能超过 4000 字节（UTF-8）",
+      maxSessionsRange: "最大会话数必须是 1 到 100 之间的整数",
+      maxMessagesRange: "最大消息数必须是 1 到 20000 之间的整数",
+      maxMemoriesRange: "最大记忆数必须是 1 到 5000 之间的整数",
+      thresholdRange: "置信度阈值必须在 0 到 1 之间",
+      timestampInvalid: "时间格式不正确",
+      timestampOrder: "最晚时间不能早于最早时间",
       actions: {
         allStatus: "全部状态",
         allTypes: "全部类型",
@@ -1152,10 +1240,11 @@ export const messages = {
       modeSearchTitle: "语义检索",
       modeSearchDesc: "每轮向量检索记忆库",
       modeLocalTitle: "文件记忆",
-      modeLocalDescEnabled: "同步投影文件后本地检索",
+      modeLocalDescEnabled: "通过文件 API 缓存后本地检索",
+      modeLocalDescWritable: "filemem 固定使用文件检索",
       modeLocalDescDisabled: "仅「支持文件记忆」的记忆库可用",
       localHint:
-        "记忆以 markdown 文件树投影到本地镜像目录；每轮对话前自动同步并在文件上检索。记忆按用户（应用 + 租户）粒度聚合，智能体 / 会话字段不影响文件内容。",
+        "每轮对话前，浏览器通过文件 API 分页列举并按 SHA 复用内容，在当前标签页做有界词法检索；不会启动 FUSE 或创建服务端本地镜像。",
       viewFiles: "查看记忆文件",
       viewFilesHint: "请先填写完整的应用 / 租户 / 智能体",
       emptyNoStoresTitle: "还没有任何记忆库",
@@ -1181,6 +1270,8 @@ export const messages = {
       agentField: "智能体 *",
       autoSave: "对话后自动写入记忆",
       autoSaveDesc: "自动归档：把本轮用户 / 助手消息写入当前范围",
+      autoSaveFilememDesc:
+        "智能提炼每轮对话中值得长期保存的内容，并追加到日期记忆文件",
       runIdLabel: "会话 ID",
       runIdTitle:
         "会话 ID 由当前对话自动生成并在整个对话内复用，用于串联同一会话的记忆",
@@ -1191,7 +1282,7 @@ export const messages = {
     },
     filesDialog: {
       title: "记忆文件",
-      description: "该范围的记忆文件镜像目录",
+      description: "通过文件 API 管理该精确范围的虚拟文件与版本",
     },
     history: {
       newChat: "新对话",
@@ -1248,6 +1339,11 @@ export const messages = {
       edit: "编辑",
       resend: "重新发送",
       regenerate: "重新生成",
+      saveToFile: "保存回复到文件记忆",
+      savePathPrompt: "请输入要保存到 filemem 的文件路径",
+      saveToFileInvalid: "路径无效，或回复内容超过 100 KiB",
+      savedToFile: "回复已保存到 {path}",
+      saveToFileFailed: "保存回复到文件记忆失败",
       summarizeSkill: "总结技能到知识库",
       extractProfile: "提取画像到知识库",
       delete: "删除",
@@ -1274,6 +1370,10 @@ export const messages = {
       generateFailed: "生成失败",
       elapsedSeconds: "用时 {seconds} 秒",
       elapsedMinutes: "用时 {minutes} 分 {seconds} 秒",
+      memorySaving: "正在提炼文件记忆…",
+      memorySaved: "已写入 {count} 条长期记忆",
+      memoryUnchanged: "本轮无需记录长期记忆",
+      memorySaveFailed: "文件记忆提炼失败：{error}",
     },
     chunks: {
       viewCitations: "查看 {count} 个引用",
@@ -1291,9 +1391,10 @@ export const messages = {
       referenceCount: "参考 {count} 条记忆",
       unnamedMemory: "未命名记忆",
       filesThisTurn: "本轮文件记忆 {count} 个文件",
-      syncFailed: "同步失败（沿用本地副本）：{error}",
-      syncSummary: "+{added} -{deleted} · 共 {total} 个",
-      emptyFiles: "该范围暂无记忆文件（尚未投影或未同步到）",
+      cacheFailed: "文件 API 缓存失败：{error}",
+      cacheSummary: "读取 {loaded} · SHA 复用 {reused} · 共 {total} 个",
+      cacheTruncated: "已达到 300 文件 / 3 MiB 检索上限",
+      emptyFiles: "该精确范围暂无可检索的记忆文件",
       fileSize: "{size} B",
     },
     panel: {

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

@@ -38,7 +38,15 @@ export function showApiError(
   }
   const message =
     error instanceof Error ? error.message : String(error ?? "未知错误");
-  toast.error(options.fallbackTitle ?? message);
+  if (options.fallbackTitle) {
+    if (message) {
+      toast.error(options.fallbackTitle, { description: message });
+    } else {
+      toast.error(options.fallbackTitle);
+    }
+    return;
+  }
+  toast.error(message);
 }
 
 /**

package/dist/dashboard-runtime/dashboard/src/lib/browser-file-memory.ts

@@ -0,0 +1,391 @@
+"use client";
+
+import type { ChatMemoryWriteScope } from "@/components/chat/chat-config-context";
+import {
+  listFileMemories as listFileMemoriesService,
+  readFileMemory as readFileMemoryService,
+} from "@/services/file-memory";
+import type { FileMemory, FileMemoryScope } from "@/types/file-memory";
+
+export const BROWSER_FILE_MEMORY_LABEL =
+  "标签页内容缓存 · 通过文件 API 按 SHA 复用";
+export const MAX_BROWSER_FILE_MEMORY_FILES = 300;
+export const MAX_BROWSER_FILE_MEMORY_BYTES = 3 * 1024 * 1024;
+export const MAX_BROWSER_FILE_MEMORY_SNAPSHOTS = 8;
+
+const LIST_PAGE_SIZE = 100;
+const READ_CONCURRENCY = 8;
+const MAX_LIST_PAGES = 1_000;
+const SNIPPET_LINES = 10;
+
+export interface BrowserFileMemoryEntry {
+  rel: string;
+  size: number;
+  sha256: string;
+}
+
+export interface BrowserFileMemoryHit {
+  text: string;
+  source: string;
+  score: number;
+}
+
+export interface BrowserFileMemoryCacheSummary {
+  ok: boolean;
+  listed: number;
+  loaded: number;
+  reused: number;
+  totalBytes: number;
+  truncated: boolean;
+  error?: string;
+}
+
+interface CachedFile extends BrowserFileMemoryEntry {
+  path: string;
+  memoryId: string;
+  text: string;
+}
+
+interface BrowserFileMemorySnapshot {
+  files: Map<string, CachedFile>;
+  updatedAt: number;
+}
+
+type ListFileMemories = typeof listFileMemoriesService;
+type ReadFileMemory = typeof readFileMemoryService;
+
+export interface LoadBrowserFileMemoryOptions {
+  dataScopeKey: string;
+  memoryStoreName: string;
+  scope: ChatMemoryWriteScope;
+  listFileMemories?: ListFileMemories;
+  readFileMemory?: ReadFileMemory;
+}
+
+export interface LoadBrowserFileMemoryResult {
+  key: string;
+  files: BrowserFileMemoryEntry[];
+  cache: BrowserFileMemoryCacheSummary;
+}
+
+const snapshots = new Map<string, BrowserFileMemorySnapshot>();
+const inflight = new Map<string, Promise<LoadBrowserFileMemoryResult>>();
+
+function readSnapshot(key: string): BrowserFileMemorySnapshot | undefined {
+  const snapshot = snapshots.get(key);
+  if (snapshot) {
+    snapshots.delete(key);
+    snapshots.set(key, snapshot);
+  }
+  return snapshot;
+}
+
+function storeSnapshot(key: string, snapshot: BrowserFileMemorySnapshot): void {
+  snapshots.delete(key);
+  snapshots.set(key, snapshot);
+  while (snapshots.size > MAX_BROWSER_FILE_MEMORY_SNAPSHOTS) {
+    const oldestKey = snapshots.keys().next().value;
+    if (oldestKey === undefined) break;
+    snapshots.delete(oldestKey);
+  }
+}
+
+function normalizeScope(scope: ChatMemoryWriteScope): FileMemoryScope {
+  const read = (value: string, field: string) => {
+    const normalized = value.trim();
+    if (!normalized || normalized === "*") {
+      throw new Error(`file memory requires an exact ${field}`);
+    }
+    return normalized;
+  };
+  return {
+    appId: read(scope.appId, "appId"),
+    tenantId: read(scope.tenantId, "tenantId"),
+    agentId: read(scope.agentId, "agentId"),
+    runId: read(scope.runId, "runId"),
+  };
+}
+
+export function browserFileMemoryKey(opts: {
+  dataScopeKey: string;
+  memoryStoreName: string;
+  scope: ChatMemoryWriteScope;
+}): string {
+  const scope = normalizeScope(opts.scope);
+  return JSON.stringify([
+    opts.dataScopeKey,
+    opts.memoryStoreName,
+    scope.appId,
+    scope.tenantId,
+    scope.agentId,
+    scope.runId,
+  ]);
+}
+
+function normalizePath(path: string): { path: string; rel: string } {
+  const absolute = `/${path.trim().replace(/^\/+/, "")}`;
+  const parts = absolute.slice(1).split("/");
+  if (
+    absolute === "/" ||
+    absolute.includes("\\") ||
+    parts.some((part) => !part || part === "." || part === "..")
+  ) {
+    throw new Error(`invalid file-memory path: ${path}`);
+  }
+  return { path: absolute, rel: parts.join("/") };
+}
+
+function validateMetadata(file: FileMemory): void {
+  normalizePath(file.path);
+  if (
+    !file.memoryId ||
+    !file.contentSha256 ||
+    !Number.isSafeInteger(file.contentSizeBytes) ||
+    file.contentSizeBytes < 0
+  ) {
+    throw new Error(`invalid file-memory metadata: ${file.path}`);
+  }
+}
+
+async function collectMetadata(
+  opts: LoadBrowserFileMemoryOptions,
+  scope: FileMemoryScope,
+): Promise<{ files: FileMemory[]; truncated: boolean }> {
+  const list = opts.listFileMemories ?? listFileMemoriesService;
+  const files = new Map<string, FileMemory>();
+  const tokens = new Set<string>();
+  let nextToken: string | undefined;
+  let truncated = false;
+
+  for (let page = 0; page < MAX_LIST_PAGES; page += 1) {
+    const response = await list(opts.memoryStoreName, {
+      scope,
+      limit: LIST_PAGE_SIZE,
+      ...(nextToken ? { nextToken } : {}),
+    });
+    for (const [index, file] of response.memories.entries()) {
+      validateMetadata(file);
+      const { path } = normalizePath(file.path);
+      if (!files.has(path)) files.set(path, { ...file, path });
+      if (files.size >= MAX_BROWSER_FILE_MEMORY_FILES) {
+        truncated =
+          index < response.memories.length - 1 || !!response.nextToken;
+        return { files: [...files.values()], truncated };
+      }
+    }
+    if (!response.nextToken) return { files: [...files.values()], truncated };
+    if (tokens.has(response.nextToken)) {
+      throw new Error("ListFileMemories repeated a pagination token");
+    }
+    tokens.add(response.nextToken);
+    nextToken = response.nextToken;
+  }
+  throw new Error("ListFileMemories exceeded the pagination limit");
+}
+
+async function mapConcurrent<T, TResult>(
+  items: T[],
+  concurrency: number,
+  worker: (item: T) => Promise<TResult>,
+): Promise<TResult[]> {
+  const results = new Array<TResult>(items.length);
+  let cursor = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+      while (cursor < items.length) {
+        const index = cursor;
+        cursor += 1;
+        results[index] = await worker(items[index]);
+      }
+    }),
+  );
+  return results;
+}
+
+function snapshotEntries(
+  snapshot: BrowserFileMemorySnapshot | undefined,
+): BrowserFileMemoryEntry[] {
+  if (!snapshot) return [];
+  return [...snapshot.files.values()]
+    .map(({ rel, size, sha256 }) => ({ rel, size, sha256 }))
+    .sort((a, b) => a.rel.localeCompare(b.rel));
+}
+
+async function performLoad(
+  opts: LoadBrowserFileMemoryOptions,
+  key: string,
+  scope: FileMemoryScope,
+): Promise<LoadBrowserFileMemoryResult> {
+  const previous = readSnapshot(key);
+  try {
+    const collected = await collectMetadata(opts, scope);
+    const selected: FileMemory[] = [];
+    let totalBytes = 0;
+    let truncated = collected.truncated;
+    for (const file of collected.files) {
+      if (totalBytes + file.contentSizeBytes > MAX_BROWSER_FILE_MEMORY_BYTES) {
+        truncated = true;
+        continue;
+      }
+      selected.push(file);
+      totalBytes += file.contentSizeBytes;
+    }
+
+    const candidate = new Map<string, CachedFile>();
+    const toRead: FileMemory[] = [];
+    let reused = 0;
+    for (const file of selected) {
+      const { rel } = normalizePath(file.path);
+      const cached = previous?.files.get(rel);
+      if (cached?.sha256 === file.contentSha256) {
+        candidate.set(rel, {
+          ...cached,
+          path: file.path,
+          memoryId: file.memoryId,
+          size: file.contentSizeBytes,
+        });
+        reused += 1;
+      } else {
+        toRead.push(file);
+      }
+    }
+
+    const read = opts.readFileMemory ?? readFileMemoryService;
+    const loaded = await mapConcurrent(
+      toRead,
+      READ_CONCURRENCY,
+      async (file) => {
+        const response = await read(opts.memoryStoreName, {
+          scope,
+          path: file.path,
+        });
+        if (response.content === undefined) {
+          throw new Error(`ReadFileMemory omitted content for ${file.path}`);
+        }
+        const { path, rel } = normalizePath(file.path);
+        return {
+          path,
+          rel,
+          memoryId: file.memoryId,
+          size: file.contentSizeBytes,
+          sha256: file.contentSha256,
+          text: response.content,
+        } satisfies CachedFile;
+      },
+    );
+    for (const file of loaded) candidate.set(file.rel, file);
+
+    const snapshot = { files: candidate, updatedAt: Date.now() };
+    storeSnapshot(key, snapshot);
+    return {
+      key,
+      files: snapshotEntries(snapshot),
+      cache: {
+        ok: true,
+        listed: collected.files.length,
+        loaded: loaded.length,
+        reused,
+        totalBytes,
+        truncated,
+      },
+    };
+  } catch (error) {
+    const files = snapshotEntries(previous);
+    return {
+      key,
+      files,
+      cache: {
+        ok: false,
+        listed: files.length,
+        loaded: 0,
+        reused: files.length,
+        totalBytes: files.reduce((sum, file) => sum + file.size, 0),
+        truncated: false,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}
+
+export function loadBrowserFileMemory(
+  opts: LoadBrowserFileMemoryOptions,
+): Promise<LoadBrowserFileMemoryResult> {
+  const scope = normalizeScope(opts.scope);
+  const key = browserFileMemoryKey({ ...opts, scope });
+  const existing = inflight.get(key);
+  if (existing) return existing;
+  const run = performLoad(opts, key, scope).finally(() => inflight.delete(key));
+  inflight.set(key, run);
+  return run;
+}
+
+export function readBrowserFileMemoryFile(key: string, rel: string): string {
+  const normalized = normalizePath(rel).rel;
+  const file = readSnapshot(key)?.files.get(normalized);
+  if (!file) throw new Error(`browser file-memory file not found: ${rel}`);
+  return file.text;
+}
+
+function tokenizeQuery(query: string): string[] {
+  const terms = new Set<string>();
+  for (const token of query.toLowerCase().match(/[a-z0-9]+/g) ?? []) {
+    if (token.length >= 2) terms.add(token);
+  }
+  for (const run of query.match(/[一-鿿㐀-䶿]+/g) ?? []) {
+    for (const char of run) terms.add(char);
+    for (let index = 0; index + 1 < run.length; index += 1) {
+      terms.add(run[index] + run[index + 1]);
+    }
+  }
+  return [...terms];
+}
+
+function scoreSnippet(
+  text: string,
+  terms: string[],
+  fullQuery: string,
+): number {
+  const lower = text.toLowerCase();
+  const matched = terms.reduce(
+    (count, term) => count + (lower.includes(term) ? 1 : 0),
+    0,
+  );
+  if (!matched) return 0;
+  const bonus =
+    fullQuery.length > 4 && lower.includes(fullQuery.toLowerCase()) ? 0.1 : 0;
+  return Math.min(1, matched / Math.max(1, terms.length) + bonus);
+}
+
+export function searchBrowserFileMemory(opts: {
+  key: string;
+  query: string;
+  topK: number;
+}): { results: BrowserFileMemoryHit[]; skipped?: boolean } {
+  const query = opts.query.trim();
+  const snapshot = readSnapshot(opts.key);
+  const terms = tokenizeQuery(query);
+  if (!query || !snapshot || terms.length === 0) {
+    return { results: [], skipped: true };
+  }
+  const hits: BrowserFileMemoryHit[] = [];
+  for (const file of snapshot.files.values()) {
+    const lines = file.text.split("\n");
+    for (let index = 0; index < lines.length; index += SNIPPET_LINES) {
+      const text = lines
+        .slice(index, index + SNIPPET_LINES)
+        .join("\n")
+        .trim();
+      if (!text) continue;
+      const score = scoreSnippet(text, terms, query);
+      if (score > 0) hits.push({ text, source: file.rel, score });
+    }
+  }
+  hits.sort((a, b) => b.score - a.score || a.source.localeCompare(b.source));
+  const topK = Math.max(1, Math.min(50, Math.trunc(opts.topK) || 1));
+  return { results: hits.slice(0, topK) };
+}
+
+export function clearBrowserFileMemoryForTests(): void {
+  snapshots.clear();
+  inflight.clear();
+}