Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
perf(files): 统一远程文件缓存并后台检查更新
Dash83be7aaac344
diff --git a/apps/desktop/src/main/device-link/__tests__/fileAccess.test.ts b/apps/desktop/src/main/device-link/__tests__/fileAccess.test.tsindex ebf65af326..25da52d402 100644--- a/apps/desktop/src/main/device-link/__tests__/fileAccess.test.ts+++ b/apps/desktop/src/main/device-link/__tests__/fileAccess.test.ts@@ -1,7 +1,10 @@import { beforeEach, describe, expect, it, vi } from 'vitest';+import { promises as fs } from 'node:fs';const peer = vi.hoisted(() => vi.fn());const remove = vi.hoisted(() => vi.fn());const owner = vi.hoisted(() => ({ current: true }));+const cache = vi.hoisted(() => ({ get: vi.fn(), put: vi.fn(), invalidate: vi.fn() }));+vi.mock('../remoteFileVersionCache', () => ({ remoteFileVersionCache: () => cache }));vi.mock('../filePeer', () => ({ tryPeerFile: peer }));vi.mock('../mediaTransfer', () => ({ removeRemote: remove }));vi.mock('../broadcast-tap', () => ({@@ -16,6 +19,35 @@ beforeEach(() => {peer.mockResolvedValue(null);});describe('desktop shared file access', () => {+ it('returns cached HTML before a blocked host version check completes', async () => {+ const result = { ossKey: '', size: 3, mimeType: 'text/html', version: 'c'.repeat(64), inlineBase64: 'YWJj' };+ cache.get.mockResolvedValueOnce(null).mockResolvedValueOnce('/cache/instant');+ const read = vi.spyOn(fs, 'readFile').mockResolvedValueOnce(Buffer.from('abc'));+ const invoke = vi.fn(async (_device, _channel, [args]) => ({ ok: true, result: args.metadataOnly+ ? { ...result, inlineBase64: undefined, transferRequired: true } : result }));+ let reply!: (value: any) => void;+ try {+ await readRemoteDeviceFile('instant', 'xdt-file://open?path=/cached.html', invoke);+ invoke.mockImplementationOnce(() => new Promise(resolve => { reply = resolve; }));+ expect(await readRemoteDeviceFile('instant', 'xdt-file://open?path=/cached.html', invoke)).toEqual(result);+ expect(invoke).toHaveBeenCalledTimes(3);+ reply({ ok: true, result });+ } finally { read.mockRestore(); }+ });+ it('checks metadata then reads the same durable cache used by large files', async () => {+ const result = { ossKey: '', size: 3, mimeType: 'text/html', version: 'a'.repeat(64), inlineBase64: 'YWJj' };+ cache.get.mockResolvedValueOnce(null).mockResolvedValueOnce('/cache/html');+ const read = vi.spyOn(fs, 'readFile').mockResolvedValueOnce(Buffer.from('abc'));+ const invoke = vi.fn(async (_device, _channel, [args]) => ({ ok: true, result: args.metadataOnly+ ? { ...result, inlineBase64: undefined, transferRequired: true } : result }));+ try {+ expect(await readRemoteDeviceFile('d', 'xdt-file://open?path=/a.html', invoke)).toEqual(result);+ expect(cache.put).toHaveBeenCalledWith(Buffer.from('abc'));+ expect(await readRemoteDeviceFile('d', 'xdt-file://open?path=/a.html', invoke)).toEqual(result);+ expect(invoke).toHaveBeenCalledTimes(3);+ expect(peer).not.toHaveBeenCalled();+ } finally { read.mockRestore(); }+ });it.each(['abort', 'stop', 'owner'] as const)('keeps business requests cancelled while permitting owner-safe close (%s)', async reason => {const abort = new AbortController();const invoke = vi.fn(async () => ({ ok: true, result: { ossKey: '', size: 5, mimeType: 'text/plain', transferRequired: true } }));diff --git a/apps/desktop/src/main/device-link/__tests__/mediaFetch.test.ts b/apps/desktop/src/main/device-link/__tests__/mediaFetch.test.tsindex 880d5856a8..707b33f3c4 100644--- a/apps/desktop/src/main/device-link/__tests__/mediaFetch.test.ts+++ b/apps/desktop/src/main/device-link/__tests__/mediaFetch.test.ts@@ -170,6 +170,17 @@ describe('fetchLocalMediaToOss — scheme 路由', () => {expect(logDebug.mock.calls.flat().join('\n')).not.toMatch(/xdt-|path=|\/cache\//);},);+ it('returns only authorized metadata for small files when requested', async () => {+ const read = vi.fn(), close = vi.fn();+ openMock.mockResolvedValue({ stat: async () => ({ isFile: () => true, size: 5, mtimeMs: 1 }), read, close });+ imageResolve.mockReturnValue({ absPath: '/cache/a.png', mimeType: 'image/png' });+ const result = await fetchLocalMediaToOss({ url: 'xdt-image://sess/a.png', prepareOnly: true, metadataOnly: true });+ expect(result).toMatchObject({ size: 5, transferRequired: true, version: expect.stringMatching(/^[a-f0-9]{64}$/) });+ expect(result.inlineBase64).toBeUndefined();+ expect(read).not.toHaveBeenCalled();+ expect(uploadLocalFile).not.toHaveBeenCalled();+ expect(close).toHaveBeenCalledOnce();+ });it('revalidates source identity without reading/uploading bytes, including restored mtime', async () => {let ctimeMs = 1;const read = vi.fn();diff --git a/apps/desktop/src/main/device-link/__tests__/remoteMediaProtocol.test.ts b/apps/desktop/src/main/device-link/__tests__/remoteMediaProtocol.test.tsindex dee50ccd03..baa451df64 100644--- a/apps/desktop/src/main/device-link/__tests__/remoteMediaProtocol.test.ts+++ b/apps/desktop/src/main/device-link/__tests__/remoteMediaProtocol.test.ts@@ -290,7 +290,7 @@ describe('handleRemoteMedia', () => {});const r = await handleRemoteMedia(URL_BLOB, null);expect(remoteInvoke).toHaveBeenCalledWith('dev-1', 'device-link:media:fetch', [- { url: BLOB_URL, prepareOnly: true },+ { url: BLOB_URL, prepareOnly: true, metadataOnly: true },]);expect(r.status).toBe(200);});@@ -355,7 +355,7 @@ describe('handleRemoteMedia', () => {const r = await handleRemoteMedia(URL_IMG, null);expect(remoteInvoke).toHaveBeenCalledWith('dev-1', 'device-link:media:fetch', [- { url: 'xdt-image://s/a.png', prepareOnly: true },+ { url: 'xdt-image://s/a.png', prepareOnly: true, metadataOnly: true },]);expect(downloadToBuffer).toHaveBeenCalledWith('oss/k.png');expect(removeRemote).toHaveBeenCalledWith('oss/k.png'); // 用后删@@ -458,7 +458,7 @@ describe('handleRemoteMedia', () => {const r = await handleRemoteMedia(URL_IMG, null);expect(remoteInvoke).toHaveBeenNthCalledWith(1, 'dev-1', 'device-link:media:fetch', [- { url: 'xdt-image://s/a.png', prepareOnly: true },+ { url: 'xdt-image://s/a.png', prepareOnly: true, metadataOnly: true },]);expect(remoteInvoke).toHaveBeenNthCalledWith(2, 'dev-1', 'device-link:media:fetch', [{ url: 'xdt-image://s/a.png', skipCache: true },diff --git a/apps/desktop/src/main/device-link/fileAccess.ts b/apps/desktop/src/main/device-link/fileAccess.tsindex b125fd8770..625b00ba55 100644--- a/apps/desktop/src/main/device-link/fileAccess.ts+++ b/apps/desktop/src/main/device-link/fileAccess.ts@@ -3,16 +3,26 @@ import {DL_MEDIA_FETCH_CHANNEL,FILE_PEER_CHANNEL,FILE_PEER_MAX_BYTES,+ FILE_INLINE_MAX_BYTES,+ isSharedTaskPeer,+ validFileVersion,type DeviceFileResult,} from '@cindy/device-link';-import { tryPeerFile } from './filePeer';+import { promises as fs } from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { tryPeerFile, copyReceivedFile } from './filePeer';+import { activeOwnerScopeKey } from '../appSessionState';import { captureFilePeerScope } from './filePeerScope';-import { removeRemote } from './mediaTransfer';+import { downloadToFile, removeRemote } from './mediaTransfer';import { captureDataOwnerBroadcastScope, isDataOwnerBroadcastScopeCurrent } from './broadcast-tap';import { captureRemoteMediaCacheValidity } from './remoteMediaPersistentCache';type Invoke = Parameters<typeof tryPeerFile>[2];type LocalFileResult = DeviceFileResult & { path: string; dispose(): Promise<void> };+// Metadata only: bytes remain in the existing managed disk caches.+const latestFiles = new Map<string, { url: string; metadata: DeviceFileResult }>();+let latestOwner = '';/** Platform adapter; authorization stays in the controlled host's shared resolver. */export function readRemoteDeviceFile(device: string,@@ -35,6 +45,15 @@ export function readRemoteDeviceFile(const owner = captureDataOwnerBroadcastScope();const assertCacheCurrent = options.assertCacheCurrent ?? captureRemoteMediaCacheValidity();const isCurrent = captureFilePeerScope(device);+ const scope = activeOwnerScopeKey();+ if (latestOwner !== scope) { latestFiles.clear(); latestOwner = scope; }+ const cacheKey = JSON.stringify([scope, device, url, options.workdir, options.relPath]);+ let returnedCached = false;+ const remember = (result: DeviceFileResult) => {+ if (isCurrent() && validFileVersion(result.version))+ latestFiles.set(cacheKey, { url, metadata: { ossKey: '', size: result.size, mimeType: result.mimeType, version: result.version } });+ return result;+ };const invoke: Invoke = async (target, channel, args) => {// A connection can outlive this read, including an offer answered after cancellation.// Teardown may cross the read's cancellation boundary, never the account boundary.@@ -46,9 +65,9 @@ export function readRemoteDeviceFile(throw new Error('FILE_PEER_CANCELLED');return rawInvoke(target, channel, args);};- const fetch = async (prepareOnly: boolean): Promise<DeviceFileResult> => {+ const fetch = async (prepareOnly: boolean, metadataOnly = false): Promise<DeviceFileResult> => {const response = await invoke(device, DL_MEDIA_FETCH_CHANNEL, [- { url, prepareOnly, ...(options.skipCache ? { skipCache: true } : {}) },+ { url, prepareOnly, ...(metadataOnly ? { metadataOnly: true } : {}), ...(options.skipCache ? { skipCache: true } : {}) },]);if (!response.ok) {const error = (response as { error?: { code?: string; message?: string } }).error;@@ -57,6 +76,65 @@ export function readRemoteDeviceFile(return response.result as DeviceFileResult;};return readDeviceFile<LocalFileResult>({+ cacheFirst: options.skipCache || isSharedTaskPeer(device) ? undefined : {+ key: cacheKey,+ read: async () => {+ const previous = latestFiles.get(cacheKey);+ if (!previous || (options.stream && /^(audio|video)\//.test(previous.metadata.mimeType))) return null;+ const { remoteFileVersionCache } = await import('./remoteFileVersionCache');+ const path = await remoteFileVersionCache(device, previous.url, { ...previous.metadata, assertCacheCurrent })?.get();+ if (!path) return null;+ if (previous.metadata.size <= FILE_INLINE_MAX_BYTES) {+ const bytes = await fs.readFile(path);+ if (bytes.length !== previous.metadata.size) return null;+ url = previous.url;+ returnedCached = true;+ return { ...previous.metadata, inlineBase64: bytes.toString('base64') };+ }+ const copy = await copyReceivedFile({ ...previous.metadata, path, dispose: async () => {} });+ url = previous.url;+ returnedCached = true;+ return { ...copy, ossKey: '' };+ },+ retain: async (result) => {+ if (result.ossKey && validFileVersion(result.version)) {+ const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'cindy-file-peer-'));+ try {+ const file = path.join(directory, 'file');+ await downloadToFile(result.ossKey, file, undefined, undefined, options.signal);+ if (!isCurrent() || options.signal?.aborted) return;+ if ((await fs.stat(file)).size !== result.size) return;+ const { remoteFileVersionCache } = await import('./remoteFileVersionCache');+ await remoteFileVersionCache(device, url, { ...result, assertCacheCurrent })?.put(file);+ } finally { await fs.rm(directory, { recursive: true, force: true }); }+ }+ remember(result);+ },+ },+ inline: () => fetch(true),+ revalidate: () => fetch(true, true),+ inlineCache: {+ read: async (metadata) => {+ const { remoteFileVersionCache } = await import('./remoteFileVersionCache');+ const cache = remoteFileVersionCache(device, url, { ...metadata, assertCacheCurrent });+ if (options.skipCache) {+ await cache?.invalidate();+ return null;+ }+ const path = await cache?.get();+ if (!path) return null;+ const bytes = await fs.readFile(path);+ if (bytes.length !== metadata.size) return null;+ return { ossKey: '', size: bytes.length, mimeType: metadata.mimeType,+ version: metadata.version, inlineBase64: bytes.toString('base64') };+ },+ store: async (result) => {+ const { remoteFileVersionCache } = await import('./remoteFileVersionCache');+ if (options.signal?.aborted || !isCurrent()) return;+ await remoteFileVersionCache(device, url, { ...result, assertCacheCurrent })+ ?.put(Buffer.from(result.inlineBase64!, 'base64'));+ },+ },stream: options.stream,signal: options.signal,isCurrent,@@ -89,7 +167,7 @@ export function readRemoteDeviceFile(url = bounded.toString();}}- return fetch(true);+ return fetch(true, true);},peer: async (metadata) => {if (@@ -110,5 +188,5 @@ export function readRemoteDeviceFile(return result ? { ...result, ossKey: '' } : null;},fallback: options.fallback ?? (() => fetch(false)),- });+ }).then((result) => { if (!returnedCached) remember(result); return result; });}diff --git a/apps/desktop/src/main/device-link/filePeer.ts b/apps/desktop/src/main/device-link/filePeer.tsindex ced1c85fd6..08029401d9 100644--- a/apps/desktop/src/main/device-link/filePeer.ts+++ b/apps/desktop/src/main/device-link/filePeer.ts@@ -749,7 +749,7 @@ export function tryPeerFile(signal,);}-async function copyReceivedFile(source: ReceivedFile): Promise<ReceivedFile> {+export async function copyReceivedFile(source: ReceivedFile): Promise<ReceivedFile> {const directory = await fs.mkdtemp(path.join(app.getPath('temp'), 'cindy-file-peer-'));const destination = path.join(directory, 'file');const dispose = () => fs.rm(directory, { recursive: true, force: true });diff --git a/apps/desktop/src/main/device-link/mediaFetch.ts b/apps/desktop/src/main/device-link/mediaFetch.tsindex 670c2e4d41..464507ce58 100644--- a/apps/desktop/src/main/device-link/mediaFetch.ts+++ b/apps/desktop/src/main/device-link/mediaFetch.ts@@ -440,7 +440,7 @@ export async function resolveAuthorizedMedia(arg: unknown, maximumBytes?: numberexport async function fetchLocalMediaToOss(arg: unknown): Promise<MediaFetchResult> {const record =arg && typeof arg === 'object'- ? (arg as { url?: unknown; skipCache?: unknown; thumbnail?: unknown; prepareOnly?: unknown })+ ? (arg as { url?: unknown; skipCache?: unknown; thumbnail?: unknown; prepareOnly?: unknown; metadataOnly?: unknown }): {};const { absPath, mimeType, uploadExtHint, maxBytes, sourceVersion } = await resolveAuthorizedMedia(arg);const url = record.url as string;@@ -462,7 +462,7 @@ export async function fetchLocalMediaToOss(arg: unknown): Promise<MediaFetchResumimeType ??mimeOf((uploadExtHint ?? path.extname(absPath)).replace(/^\./, '').toLowerCase()),};- if (before.size > FILE_INLINE_MAX_BYTES) {+ if (record.metadataOnly === true || before.size > FILE_INLINE_MAX_BYTES) {log.debug(`media:fetch prepare → transfer size=${before.size} mime=${result.mimeType}`);return { ...result, transferRequired: true };}diff --git a/apps/desktop/src/main/device-link/remoteFileVersionCache.ts b/apps/desktop/src/main/device-link/remoteFileVersionCache.tsindex 9de797c993..aa0c942d1b 100644--- a/apps/desktop/src/main/device-link/remoteFileVersionCache.ts+++ b/apps/desktop/src/main/device-link/remoteFileVersionCache.ts@@ -27,7 +27,8 @@ export type FileVersionMetadata = Pick<DeviceFileResult, 'version' | 'size' | 'm};/** An adapter to the existing media warehouse / ordinary-file LRU, not another byte store.- * Authorization and stat happen on the host before this adapter is called, every time.+ * Versions originate from host authorization/stat; same-owner previews may reuse+ * the previous version while revalidating in the background.* Generations guard in-flight work; stable owner IDs key the durable cache across restarts. */export function remoteFileVersionCache(device: string,diff --git a/apps/desktop/src/main/file-browser/__tests__/html-preview-ipc.test.ts b/apps/desktop/src/main/file-browser/__tests__/html-preview-ipc.test.tsindex db4deeb3d9..6c95c00c18 100644--- a/apps/desktop/src/main/file-browser/__tests__/html-preview-ipc.test.ts+++ b/apps/desktop/src/main/file-browser/__tests__/html-preview-ipc.test.ts@@ -81,6 +81,30 @@ it('opens a preview before downloading even a large entry file', async () => {await expect(mocks.handle.mock.calls[0][1]({}, args)).resolves.toMatchObject({ ok: true });expect(read).not.toHaveBeenCalled();});+it('serves cached HTML while remote stat is blocked, then uses the changed file on the next open', async () => {+ const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'cindy-preview-swr-test-'));+ let reply!: (value: any) => void;+ const metadata = { relPath: 'index.html', type: 'file' as const, size: 3, mtimeMs: 1 };+ const stat = vi.fn(async () => metadata);+ const read = vi.fn(async () => path.join(dir, 'old.html'));+ try {+ await fs.writeFile(path.join(dir, 'old.html'), 'old');+ await fs.writeFile(path.join(dir, 'new.html'), 'new');+ registerHtmlPreviewIpc({ stat, read });+ const open = mocks.handle.mock.calls[0][1];+ const first = await open({}, args);+ expect(await (await readResource(first.url, '/index.html')).text()).toContain('old');+ stat.mockImplementationOnce(() => new Promise(resolve => { reply = resolve; }));+ const second = await open({}, args);+ expect(await (await readResource(second.url, '/index.html')).text()).toContain('old');+ expect(read).toHaveBeenCalledOnce();+ read.mockResolvedValueOnce(path.join(dir, 'new.html'));+ reply({ ...metadata, mtimeMs: 2 });+ await vi.waitFor(() => expect(read).toHaveBeenCalledTimes(2));+ const third = await open({}, args);+ expect(await (await readResource(third.url, '/index.html')).text()).toContain('new');+ } finally { await fs.rm(dir, { recursive: true, force: true }); }+});it('passes the captured owner guard through reference-free cache ingestion', async () => {const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'cindy-preview-owner-test-'));try {diff --git a/apps/desktop/src/main/file-browser/html-preview-ipc.ts b/apps/desktop/src/main/file-browser/html-preview-ipc.tsindex 4066067417..888785bb40 100644--- a/apps/desktop/src/main/file-browser/html-preview-ipc.ts+++ b/apps/desktop/src/main/file-browser/html-preview-ipc.ts@@ -19,6 +19,7 @@ import {} from '../device-link/broadcast-tap.js';import { getDbClient } from '../localDb/client/current.js';import { throwIpcError } from '../utils/ipcValidate.js';+import { isSharedTaskPeer } from '@cindy/device-link';const log = createLogger('html-preview');export const HTML_PREVIEW_CHANNEL = 'maker:html-preview:open';@@ -35,6 +36,11 @@ export async function disposeHtmlPreviews(): Promise<void> {await Promise.allSettled([...active].map((close) => close()));}export function registerHtmlPreviewIpc(remote: RemoteSource): void {+ // Keep only references to managed cache files, never another copy of their bytes.+ type CachedFile = { metadata: DirEntry; path: string };+ const files = new Map<string, CachedFile>();+ const refreshing = new Set<string>();+ let cacheOwner: string | undefined;ipcMain.handle(HTML_PREVIEW_CHANNEL, async (event, args: HtmlPreviewArgs) => {assertTrustedAppRendererEvent(event);if (shuttingDown || preparing >= 8)@@ -43,6 +49,11 @@ export function registerHtmlPreviewIpc(remote: RemoteSource): void {try {previewLocation(args);const scope = captureDataOwnerBroadcastScope();+ const ownerKey = scope.ownerScopeKey;+ const cacheable = !!ownerKey && !(args.origin.kind === 'device' && isSharedTaskPeer(args.origin.deviceId));+ if (cacheOwner !== ownerKey) { files.clear(); cacheOwner = ownerKey; }+ const keyOf = (root: string, rel: string) => JSON.stringify([ownerKey, args.origin, args.workdir, root, rel]);+ const selected = new Map<string, CachedFile>();const isCurrent = () => !shuttingDown && isDataOwnerBroadcastScopeCurrent(scope);const db = getDbClient().drizzle;// Finished snapshots are a bounded cache, not concurrent preparation slots.@@ -59,14 +70,32 @@ export function registerHtmlPreviewIpc(remote: RemoteSource): void {// Log status only: paths, signed URLs and page contents are not diagnostics.onResourceError: (status) => log.warn('Preview resource request failed', { status }),stat: async (root, rel) => {- if (args.origin.kind !== 'local') return remote.stat(args, root, rel);+ if (args.origin.kind !== 'local') {+ const key = keyOf(root, rel);+ const cached = cacheable ? files.get(key) : undefined;+ const stat = cached && await fs.stat(cached.path).catch(() => null);+ if (cached && stat?.isFile() && stat.size === cached.metadata.size) {+ selected.set(key, cached);+ return cached.metadata;+ }+ selected.delete(key);+ files.delete(key);+ return remote.stat(args, root, rel);+ }const real = await fs.realpath(path.join(root, rel));if (!isPathAllowedAgainst(real, getSensitiveMediaBlocklist()))throw new Error('BAD_ARGS');return statEntry(root, rel);},read: async (root, entry, signal) => {- if (args.origin.kind !== 'local') return remote.read(args, root, entry, signal);+ if (args.origin.kind !== 'local') {+ const key = keyOf(root, entry.relPath);+ const cached = selected.get(key);+ if (cached) return cached.path;+ const file = await remote.read(args, root, entry, signal);+ if (cacheable && isCurrent() && !signal?.aborted) files.set(key, { metadata: entry, path: file });+ return file;+ }const source = path.join(root, entry.relPath);const [rootReal, real] = await Promise.all([fs.realpath(root), fs.realpath(source)]);if (@@ -79,6 +108,22 @@ export function registerHtmlPreviewIpc(remote: RemoteSource): void {materialize: async (source, dest, expectedSize) => {// The temporary tree is a view of managed media, not another persistent media store.await copyPreviewFile(source, dest, expectedSize);+ // Start after copying: replacing the shared cache cannot invalidate this view.+ for (const [key, cached] of selected) {+ if (cached.path !== source || refreshing.has(key)) continue;+ refreshing.add(key);+ const [, , , root, rel] = JSON.parse(key) as string[];+ void (async () => {+ if (!isCurrent()) return;+ const metadata = await remote.stat(args, root, rel);+ if (!isCurrent() || metadata.type !== 'file') return;+ const entry = { ...metadata, name: cached.metadata.name };+ if (entry.size === cached.metadata.size && entry.mtimeMs === cached.metadata.mtimeMs) return;+ const file = await remote.read(args, root, entry);+ if (isCurrent()) files.set(key, { metadata: entry, path: file });+ })().catch(() => { /* Preserve the usable snapshot while offline. */ })+ .finally(() => refreshing.delete(key));+ }const file = await fs.open(dest, 'r');const probe = Buffer.alloc(8192);let mime: string | null;diff --git a/apps/mobile/app/files/[sessionId].tsx b/apps/mobile/app/files/[sessionId].tsxindex ff531928c1..1bada65123 100644--- a/apps/mobile/app/files/[sessionId].tsx+++ b/apps/mobile/app/files/[sessionId].tsx@@ -556,6 +556,11 @@ function RemoteFileBrowserContent() {deviceId,openLink,presignGet,+ deleteOssObject: (key) => {+ void auth.apiFetch('/api/device-link/media', {+ baseUrl: DEVICE_LINK_API_BASE_URL, method: 'DELETE', body: { key },+ }).catch(() => undefined);+ },isCancelled: () => unmountedRef.current || run.cancelled,},workdir,@@ -580,7 +585,7 @@ function RemoteFileBrowserContent() {}}})();- }, [absolutePathOf, deviceId, maker, openLink, presignGet, resolveFileMedia, showNotice, stopExportRun, t, workdir]);+ }, [absolutePathOf, auth, deviceId, maker, openLink, presignGet, resolveFileMedia, showNotice, stopExportRun, t, workdir]);/** lightbox 底部显式操作(与预览页底栏同构):复制路径 / 发送到会话。 */const lightboxActions = useMemo((): readonly ImageLightboxAction[] => [diff --git a/apps/mobile/app/files/preview/[sessionId].tsx b/apps/mobile/app/files/preview/[sessionId].tsxindex df00c4b29d..b5b67c02c9 100644--- a/apps/mobile/app/files/preview/[sessionId].tsx+++ b/apps/mobile/app/files/preview/[sessionId].tsx@@ -94,7 +94,7 @@ import { ImageLightbox } from '@/session/ImageLightbox';import { buildMediaPayload } from '@/session/messagePayload';import type { MobileMessageGalleryImage } from '@/session/messageGallery';import type { MobileRemoteMediaPresignResult } from '@/session/remoteMedia';-import { downloadRemoteMediaShareTemp } from '@/session/remoteMediaDiskCacheExpo';+import { downloadRemoteMediaShareTemp, retainRemoteFilePreview } from '@/session/remoteMediaDiskCacheExpo';import { remoteSessionStore, useRemoteSessions } from '@/session/remoteSessionStore';import { CindyMakeSessionGate } from '@/session/CindyMakeSessionGate';import { CINDY_MAKE_ENABLED, isCindyMakeSource } from '@cindy/maker-shared/cindy-make-feature';@@ -430,6 +430,19 @@ function RemoteFilePreviewContent() {});}, [auth]);+ /**+ * 回收资源取件产生的 OSS 对象(与会话页 deleteRemoteMediaObject 同一端点与语义)。+ * 空 ossKey(inline 缩略图 / 缓存命中)没有在世对象,跳过。+ */+ const deleteResourceOssObject = useCallback((ossKey: string) => {+ if (!ossKey) return;+ void auth.apiFetch('/api/device-link/media', {+ baseUrl: DEVICE_LINK_API_BASE_URL,+ method: 'DELETE',+ body: { key: ossKey },+ }).catch(() => undefined);+ }, [auth]);+/*** 两段式导出 → presign 下载地址(图片/PDF/音视频原件与「下载原文件」共用)。* 实现在 fileBrowserExport(与浏览页长按分享共用):path+mtime 缓存、@@ -443,7 +456,7 @@ function RemoteFilePreviewContent() {const isCancelled = () => unmountedRef.current || options?.isCancelled?.() === true;if (singleAbsPath) {return fetchRemoteAbsFileToUrl(- { maker, deviceId, openLink, presignGet, stream, isCancelled },+ { maker, deviceId, openLink, presignGet, stream, isCancelled, deleteOssObject: deleteResourceOssObject },singleAbsPath,);}@@ -456,28 +469,16 @@ function RemoteFilePreviewContent() {stream,isCancelled,onProgress: options?.onProgress,+ deleteOssObject: deleteResourceOssObject,},workdir,relPath,mtimeMs,);},- [deviceId, maker, openLink, presignGet, singleAbsPath, workdir],+ [deleteResourceOssObject, deviceId, maker, openLink, presignGet, singleAbsPath, workdir],);- /**- * 回收资源取件产生的 OSS 对象(与会话页 deleteRemoteMediaObject 同一端点与语义)。- * 空 ossKey(inline 缩略图 / 缓存命中)没有在世对象,跳过。- */- const deleteResourceOssObject = useCallback((ossKey: string) => {- if (!ossKey) return;- void auth.apiFetch('/api/device-link/media', {- baseUrl: DEVICE_LINK_API_BASE_URL,- method: 'DELETE',- body: { key: ossKey },- }).catch(() => undefined);- }, [auth]);-// SSH 远程工作区的取件上下文:三项必须同时给(被控端 parseSshMediaOrigin 会按// sessionId 反查会话库逐项比对);本机会话为 null,取件走被控桌面本机路径。const sshMediaContext = useMemo((): RemoteMediaSshContext | null => {@@ -1071,7 +1072,7 @@ function PdfPreviewPage({workdir,}: {active: boolean;- exportToUrl(relPath: string, mtimeMs: number): Promise<string>;+ exportToUrl(relPath: string, mtimeMs: number, options?: ExportToUrlOptions): Promise<string>;item: FileBrowserGridItem;onDownload(): void;recoveryEpoch: number;@@ -1108,7 +1109,7 @@ function PdfPreviewPage({requestedAtRecoveryEpochRef.current = latestRecoveryEpochRef.current;let cancelled = false;setFailure(null);- void exportToUrl(item.relPath, item.mtimeMs)+ void exportToUrl(item.relPath, item.mtimeMs, { stream: false }).then(preparePdfPreviewSource).then((source) => {if (cancelled) { source.release(); return; }@@ -1200,11 +1201,11 @@ function TextPreviewPage({const [browserNavigation, setBrowserNavigation] = useState<{preview: MobileHtmlPreview; state: WebViewNavigation;} | null>(null);- // absPath 单文件模式(item.relPath 为绝对路径)没有可靠 mtime(恒 0),- // 缓存键无法随文件覆写失效,读写一律跳过缓存。- const cacheable = !!workdir && !isAbsolutePathShape(item.relPath);+ // A cached preview renders immediately, including absolute paths without mtime.+ // The bounded text request below refreshes it in the background.+ const cacheable = !!workdir;const [state, setState] = useState<TextPreviewState>(() => {- // 内存缓存命中(mtime keyed)直接就绪:翻页/重进零等待、零重复拉取。+ // Cache identity includes the account, device, workdir and path.const cached = cacheable ? getCachedPreviewText(cacheScope, workdir, item.relPath, item.mtimeMs) : null;return cached? {@@ -1220,7 +1221,7 @@ function TextPreviewPage({// data-src-line 定位到覆盖目标行的块并闪高亮;切到源码态仍走精确行号跳转),// 可切源码;其余文本恒为源码态。const [richView, setRichView] = useState<'rendered' | 'source'>(richKind ? 'rendered' : 'source');- const loadedRef = useRef(state.status === 'ready');+ const loadedRef = useRef(false);const [textReloadEpoch, setTextReloadEpoch] = useState(0);const codeListRef = useRef<FlatList<string>>(null);const scrolledToTargetRef = useRef(false);@@ -1229,12 +1230,15 @@ function TextPreviewPage({if (!active || loadedRef.current || !workdir) return;loadedRef.current = true;let cancelled = false;+ const unavailable = (value: TextPreviewState) => setState((previous) =>+ previous.status === 'ready' ? previous : value);void readTextFile(item.relPath).then((res: FileBrowserReadFileResult) => {if (cancelled) return;if (!res.ok) {+ // A failed refresh must not hide the text the user is already reading.if (res.code === 'OVERSIZE') {- setState({+ unavailable({status: 'unavailable',oversize: true,reason: t('files.preview.oversize', {@@ -1242,9 +1246,9 @@ function TextPreviewPage({}),});} else if (res.code === 'BINARY_FILE') {- setState({ status: 'unavailable', reason: t('files.preview.binaryFile') });+ unavailable({ status: 'unavailable', reason: t('files.preview.binaryFile') });} else {- setState({ status: 'unavailable', reason: t('files.preview.readFailed'), retryable: true });+ unavailable({ status: 'unavailable', reason: t('files.preview.readFailed'), retryable: true });}return;}@@ -1265,10 +1269,12 @@ function TextPreviewPage({.catch((err) => {if (cancelled) return;loadedRef.current = false; // 传输层瞬断允许重进重试- setState({ status: 'unavailable', reason: t('files.preview.readFailed'), retryable: true });+ setState((previous) => previous.status === 'ready' ? previous+ : { status: 'unavailable', reason: t('files.preview.readFailed'), retryable: true });});return () => {cancelled = true;+ loadedRef.current = false;};}, [active, cacheable, cacheScope, item.relPath, richKind, readTextFile, t, workdir, textReloadEpoch]);@@ -1490,7 +1496,7 @@ function ImagePreviewPage({workdir,}: {active: boolean;- exportToUrl(relPath: string, mtimeMs: number): Promise<string>;+ exportToUrl(relPath: string, mtimeMs: number, options?: ExportToUrlOptions): Promise<string>;item: FileBrowserGridItem;maker: Pick<MobileMakerTransport, 'fileBrowser'>;onOpenLightbox(url: string): void;@@ -1512,15 +1518,21 @@ function ImagePreviewPage({const [failure, setFailure] = useState<string | null>(null);const [attempt, setAttempt] = useState(0);const requestedRef = useRef(false);+ const releaseSourceRef = useRef<(() => void) | undefined>(undefined);+ useEffect(() => () => releaseSourceRef.current?.(), []);useEffect(() => {if (!active || requestedRef.current || !workdir) return undefined;requestedRef.current = true;let cancelled = false;setFailure(null);- void exportToUrl(item.relPath, item.mtimeMs)- .then((url) => {- if (!cancelled) setFullUrl(url);+ void exportToUrl(item.relPath, item.mtimeMs, { stream: false })+ .then((url) => retainRemoteFilePreview(url, shareMimeForFileName(item.name), item.name))+ .then((source) => {+ if (cancelled) { source.release(); return; }+ releaseSourceRef.current?.();+ releaseSourceRef.current = source.release;+ setFullUrl(source.uri);}).catch((err) => {if (cancelled) return;@@ -1530,7 +1542,7 @@ function ImagePreviewPage({return () => {cancelled = true;};- }, [active, attempt, exportToUrl, item.mtimeMs, item.relPath, workdir]);+ }, [active, attempt, exportToUrl, item.mtimeMs, item.name, item.relPath, workdir]);const displayUri = fullUrl ?? thumbUri;return (diff --git a/apps/mobile/app/sessions/[sessionId].tsx b/apps/mobile/app/sessions/[sessionId].tsxindex c89cc3f98f..7651fad2f1 100644--- a/apps/mobile/app/sessions/[sessionId].tsx+++ b/apps/mobile/app/sessions/[sessionId].tsx@@ -9014,9 +9014,7 @@ function SessionScreenContent() {t,]);- /** chip 菜单「导出 / 分享」:两段式导出 → 系统分享单(与文件浏览器同链路);- * mtime 先列一拍父目录拿真实值(导出 URL 缓存 key 依赖),拿不到用当前时间- * 兜底——宁可多导出一次也不复用同路径被覆写前的旧文件。+ /** chip 菜单「导出 / 分享」:优先复用完整文件缓存,后台复验版本,再交给系统分享单。* workdir 外文件(relPath 为 null)改走被控端 media:fetch 绝对路径取件* (xdt-file://open?path=…,与文件浏览器 gallery / 预览页 absPath 模式同一通道)。 */const shareChipFile = useCallback(async (target: ChatFilePathTarget) => {@@ -9029,29 +9027,23 @@ function SessionScreenContent() {'/api/device-link/media/presign-get',{ baseUrl: DEVICE_LINK_API_BASE_URL, method: 'POST', body: { key: ossKey } },);+ const deleteOssObject = (key: string) => {+ void auth.apiFetch('/api/device-link/media', {+ baseUrl: DEVICE_LINK_API_BASE_URL, method: 'DELETE', body: { key },+ }).catch(() => undefined);+ };let url: string;if (target.relPath === null) {url = await fetchRemoteAbsFileToUrl(- { maker, deviceId, openLink, presignGet, stream: false },+ { maker, deviceId, openLink, presignGet, stream: false, deleteOssObject },target.absPath,);} else {- let mtimeMs = Date.now();- try {- const raw = await withTransientRemoteRetry(async () => {- await openLink(deviceId);- return maker.fileBrowser.listDir(workdir, parentRelPath(target.relPath ?? '') ?? '');- });- const entry = normalizeRemoteOpDirEntries(raw).find((item) => item.relPath === target.relPath);- if (entry) mtimeMs = entry.mtimeMs;- } catch {- /* 列目录失败不阻断分享,退当前时间 key */- }url = await exportRemoteFileToUrl(- { maker, deviceId, openLink, presignGet },+ { maker, deviceId, openLink, presignGet, deleteOssObject },workdir,target.relPath,- mtimeMs,+ 0,);}const mime = shareMimeForFileName(name);diff --git a/apps/mobile/src/__tests__/fileAccessCache.test.ts b/apps/mobile/src/__tests__/fileAccessCache.test.tsindex fa1398c22a..addae1c898 100644--- a/apps/mobile/src/__tests__/fileAccessCache.test.ts+++ b/apps/mobile/src/__tests__/fileAccessCache.test.ts@@ -36,6 +36,8 @@ describe("file cache identity", () => {expect(getCachedPreviewText("account-b/device-a", "/same", "a", 1),).toBeNull();+ // A changed listing mtime doesn't block rendering the previous bounded text.+ expect(getCachedPreviewText("account-a/device-a", "/same", "a", 2)?.lines).toEqual(['private']);});it("does not coalesce indexes on different devices and preserves the real RPC path", async () => {const make = (scope: string) => ({diff --git a/apps/mobile/src/__tests__/fileBrowserExportStreaming.test.ts b/apps/mobile/src/__tests__/fileBrowserExportStreaming.test.tsindex ff3d4c2f94..eefd75c283 100644--- a/apps/mobile/src/__tests__/fileBrowserExportStreaming.test.ts+++ b/apps/mobile/src/__tests__/fileBrowserExportStreaming.test.ts@@ -31,7 +31,7 @@ describe('file browser playback and download', () => {expect(await exportRemoteFileToUrl({ ...deps, stream }, '/p', 'media', 1)).toBe(stream ? 'https://example.test/stream' : local);}- expect(peer).toHaveBeenCalledOnce();+ expect(peer).toHaveBeenCalledTimes(2);expect(deps.presignGet).toHaveBeenCalledOnce();} finally { uninstall(); clearPeerMedia(); }}diff --git a/apps/mobile/src/__tests__/mobileMakerTransport.test.ts b/apps/mobile/src/__tests__/mobileMakerTransport.test.tsindex c46a3b8587..e821b3d118 100644--- a/apps/mobile/src/__tests__/mobileMakerTransport.test.ts+++ b/apps/mobile/src/__tests__/mobileMakerTransport.test.ts@@ -10,6 +10,8 @@ import {} from "@/device-link/mobileMakerTransport";import type { RemoteInvoke } from "@/device-link/mobileMakerTransport";import { installPeerFileDownload } from "@/device-link/peerFileRegistry";+const fileCache = vi.hoisted(() => ({ readLatest: vi.fn(), readInline: vi.fn(), storeInline: vi.fn(), invalidate: vi.fn(), download: vi.fn() }));+vi.mock('@/device-link/peerFileCache', () => ({ createPeerFileCache: async () => fileCache }));import { isDirectPreviewableMediaUrl, resolveMobileRemoteMedia } from "@/session/remoteMedia";import {setMobileAuthOwner,@@ -35,6 +37,41 @@ function harness() {}describe("mobile maker transport", () => {+ it('opens a cached file without waiting for connection or host metadata, then refreshes in background', async () => {+ setMobileAuthOwner('cache-first-owner');+ const cached = { ossKey: '', size: 3, mimeType: 'application/pdf', version: 'a'.repeat(64), inlineBase64: 'YWJj' };+ fileCache.readLatest.mockResolvedValueOnce(cached);+ let connect!: () => void;+ const beforeFetch = vi.fn(() => new Promise<void>(resolve => { connect = resolve; }));+ const invoke = vi.fn(async () => ({ ...cached, inlineBase64: undefined, transferRequired: true }));+ const maker = createMobileMakerTransport({ deviceId: 'cached-device', invoke: invoke as RemoteInvoke });+ try {+ expect(await maker.fetchRemoteMedia('xdt-file://open?path=/cached.pdf', { stream: false, beforeFetch })).toEqual(cached);+ expect(invoke).not.toHaveBeenCalled();+ expect(beforeFetch).toHaveBeenCalledOnce();+ connect();+ await vi.waitFor(() => expect(invoke).toHaveBeenCalledOnce());+ } finally { authOwnerTesting.reset(); vi.clearAllMocks(); }+ });+ it('checks the host version on every small-file read, reuses disk bytes, and honors forced refresh', async () => {+ setMobileAuthOwner('cache-owner');+ const result = { ossKey: '', size: 3, mimeType: 'text/html', version: 'a'.repeat(64), inlineBase64: 'YWJj' };+ let stored: typeof result | null = null;+ fileCache.readInline.mockImplementation(async () => stored);+ fileCache.storeInline.mockImplementation(async (_device, _url, value) => { stored = value; });+ fileCache.invalidate.mockImplementation(async () => { stored = null; });+ const invoke = vi.fn(async (_device, _channel, [args]) => args.metadataOnly+ ? { ...result, inlineBase64: undefined, transferRequired: true } : result);+ const maker = createMobileMakerTransport({ deviceId: 'd', invoke: invoke as RemoteInvoke });+ try {+ expect(await maker.fetchRemoteMedia('xdt-file://open?path=/a.html', { stream: false })).toEqual(result);+ expect(await maker.fetchRemoteMedia('xdt-file://open?path=/a.html', { stream: false })).toEqual(result);+ expect(invoke).toHaveBeenCalledTimes(3);+ await maker.fetchRemoteMedia('xdt-file://open?path=/a.html', { stream: false, skipCache: true });+ expect(fileCache.invalidate).toHaveBeenCalledWith('d', 'xdt-file://open?path=/a.html');+ expect(invoke).toHaveBeenCalledTimes(5);+ } finally { authOwnerTesting.reset(); vi.clearAllMocks(); }+ });describe.each([["video", "video/mp4", "mp4"],["audio", "audio/mpeg", "mp3"],@@ -815,7 +852,7 @@ describe("mobile maker transport", () => {],["device-link:media:fetch",- [{ url: "xdt-image://local/a.png", prepareOnly: true }],+ [{ url: "xdt-image://local/a.png", prepareOnly: true, metadataOnly: true }],],["device-link:voice:transcribe",diff --git a/apps/mobile/src/__tests__/pdfPreviewSource.test.ts b/apps/mobile/src/__tests__/pdfPreviewSource.test.tsindex bd88907253..992a3106ad 100644--- a/apps/mobile/src/__tests__/pdfPreviewSource.test.ts+++ b/apps/mobile/src/__tests__/pdfPreviewSource.test.ts@@ -1,13 +1,12 @@import { beforeEach, describe, expect, it, vi } from 'vitest';const { download, remove } = vi.hoisted(() => ({ download: vi.fn(), remove: vi.fn() }));-vi.mock('@/session/remoteMediaDiskCacheExpo', () => ({ downloadRemoteMediaShareTemp: download }));-vi.mock('expo-file-system', () => ({ File: class { exists = true; delete = remove; } }));+vi.mock('@/session/remoteMediaDiskCacheExpo', () => ({ retainRemoteFilePreview: download }));import { preparePdfPreviewSource } from '@/session/pdfPreviewSource';describe('PDF preview native source', () => {beforeEach(() => { vi.clearAllMocks(); });it('materializes inline PDF bytes and releases only its temporary file', async () => {- download.mockResolvedValue('file:///cache/preview.pdf');+ download.mockResolvedValue({ uri: 'file:///cache/preview.pdf', release: remove });const source = await preparePdfPreviewSource('data:application/pdf;base64,JVBERg==');expect(source.uri).toBe('file:///cache/preview.pdf');expect(download).toHaveBeenCalledWith('data:application/pdf;base64,JVBERg==', 'application/pdf', 'preview.pdf');@@ -15,16 +14,17 @@ describe('PDF preview native source', () => {source.release();expect(remove).toHaveBeenCalledOnce();});- it.each(['https://example.com/document.pdf', 'file:///existing/document.pdf'])('preserves existing source %s without owning its file', async uri => {+ it.each(['https://example.com/document.pdf', 'file:///existing/document.pdf'])('delegates source ownership for %s', async uri => {+ download.mockResolvedValue({ uri, release: remove });const source = await preparePdfPreviewSource(uri);expect(source.uri).toBe(uri);source.release();- expect(download).not.toHaveBeenCalled();- expect(remove).not.toHaveBeenCalled();+ expect(download).toHaveBeenCalledWith(uri, 'application/pdf', 'preview.pdf');+ expect(remove).toHaveBeenCalledOnce();});it('rejects unsupported sources and failed cache writes before reaching WebView', async () => {await expect(preparePdfPreviewSource('data:text/html;base64,AA==')).rejects.toThrow('INVALID_PDF_URL');- download.mockResolvedValue(null);- await expect(preparePdfPreviewSource('data:application/pdf;base64,JVBERg==')).rejects.toThrow('PDF_CACHE_FAILED');+ download.mockRejectedValue(new Error('PREVIEW_CACHE_FAILED'));+ await expect(preparePdfPreviewSource('data:application/pdf;base64,JVBERg==')).rejects.toThrow('PREVIEW_CACHE_FAILED');});});diff --git a/apps/mobile/src/__tests__/peerFileCache.test.ts b/apps/mobile/src/__tests__/peerFileCache.test.tsindex a9d2356f73..dcff3f2bae 100644--- a/apps/mobile/src/__tests__/peerFileCache.test.ts+++ b/apps/mobile/src/__tests__/peerFileCache.test.ts@@ -41,6 +41,7 @@ vi.mock("expo-file-system", () => ({delete() {disk.files.delete(this.uri);}+ async base64() { return Buffer.from(disk.files.get(this.uri)!).toString('base64'); }async copy(target: { uri: string }) {disk.copying = true;if (disk.gate) await disk.gate;@@ -53,6 +54,13 @@ vi.mock("expo-file-system", () => ({},}));vi.mock("@/session/remoteMediaDiskCacheExpo", () => ({+ downloadRemoteMediaShareTemp: async (url: string) => {+ const uri = `file:///download-${++disk.seq}`;+ const bytes = disk.files.get(url);+ if (!bytes) return null;+ disk.files.set(uri, bytes.slice());+ return uri;+ },createExpoRemoteMediaDiskCacheIO: (namespace: string) => {const uri = (name: string) => `file:///cache/${namespace}/${name}`;return {@@ -72,7 +80,7 @@ vi.mock("@/session/remoteMediaDiskCacheExpo", () => ({.filter((p) => p.startsWith(`file:///cache/${namespace}/`)).map((p) => p.split("/").at(-1)!),download: async (source: string, name: string) => {- const bytes = disk.files.get(source);+ const bytes = source.startsWith('data:') ? Buffer.from(source.split(',')[1], 'base64') : disk.files.get(source);if (!bytes) return null;disk.files.set(uri(name), bytes.slice());return bytes.length;@@ -94,6 +102,26 @@ afterEach(() => {disk.available = 10 * 1024 ** 3;});const metadata = { size: 5, mimeType: "text/html", version: "a".repeat(64) };+it('reuses completed OSS downloads through the same cache and does not retain changed-sized bytes', async () => {+ const cache = await createPeerFileCache('oss-owner');+ disk.files.set('https://oss/file', new Uint8Array(5));+ const result = await cache.download('device', 'url', metadata, 'https://oss/file', () => true);+ expect(result).not.toBeNull();+ releasePeerMedia(peerMediaUri(result!)!);+ expect(await cache.read('device', 'url', metadata, () => true)).not.toBeNull();+ expect(await cache.download('device', 'changed', { ...metadata, size: 6 }, 'https://oss/file', () => true)).toBeNull();+ expect(await cache.read('device', 'changed', metadata, () => true)).toBeNull();+});+it.each([0, 5])('shares %s-byte inline files with the durable version cache', async size => {+ const cache = await createPeerFileCache(`inline-${size}`);+ const result = { ossKey: '', ...metadata, size, inlineBase64: Buffer.alloc(size, 7).toString('base64') };+ await cache.storeInline('device', 'url', result);+ expect(await cache.readLatest('device', 'url', () => true)).toEqual(result);+ expect(await cache.readInline('device', 'url', result, () => true)).toEqual(result);+ expect(await cache.readInline('other-device', 'url', result, () => true)).toBeNull();+ expect(await cache.readInline('device', 'url', { ...result, version: 'b'.repeat(64) }, () => true)).toBeNull();+ expect(await cache.readLatest('device', 'url', () => true)).toEqual(result);+});async function seed(owner: string) {const cache = await createPeerFileCache(owner);const uri = `file:///received/${owner}`;diff --git a/apps/mobile/src/__tests__/remoteAbsFileFetch.test.ts b/apps/mobile/src/__tests__/remoteAbsFileFetch.test.tsindex af18ea7865..9439fd727c 100644--- a/apps/mobile/src/__tests__/remoteAbsFileFetch.test.ts+++ b/apps/mobile/src/__tests__/remoteAbsFileFetch.test.ts@@ -38,15 +38,15 @@ function makeDeps(overrides: Partial<{}describe('fetchRemoteAbsFileToUrl', () => {- it('separates streaming and complete-file cache entries in either order', async () => {+ it('revalidates complete files while retaining streaming URLs', async () => {for (const first of [true, false]) {const { deps, fetchRemoteMedia } = makeDeps();await fetchRemoteAbsFileToUrl({ ...deps, stream: first }, '/media.mp4');await fetchRemoteAbsFileToUrl({ ...deps, stream: !first }, '/media.mp4');await fetchRemoteAbsFileToUrl({ ...deps, stream: first }, '/media.mp4');- expect(fetchRemoteMedia).toHaveBeenCalledTimes(2);- expect(fetchRemoteMedia.mock.calls.map((call) => (call as unknown[])[1])).toEqual(- first ? [undefined, { stream: false }] : [{ stream: false }, undefined],+ expect(fetchRemoteMedia).toHaveBeenCalledTimes(first ? 2 : 3);+ expect(fetchRemoteMedia.mock.calls.map((call) => ((call as unknown[])[1] as { stream?: boolean }).stream)).toEqual(+ first ? [undefined, false] : [false, undefined, false],);}});@@ -78,7 +78,7 @@ describe('fetchRemoteAbsFileToUrl', () => {expect(url).toBe('https://oss.example/get/abc');expect(fetchRemoteMedia).toHaveBeenCalledWith(`xdt-file://open?path=${encodeURIComponent('/tmp/shot.png')}`,- undefined,+ expect.objectContaining({ beforeFetch: expect.any(Function) }),);expect(presignGet).toHaveBeenCalledWith('oss/abc');});@@ -134,7 +134,7 @@ describe('fetchRemoteAbsFileToUrl', () => {await fetchRemoteAbsFileToUrl(deps, 'C:\\tmp\\shot.png');expect(fetchRemoteMedia).toHaveBeenCalledWith(`xdt-file://open?path=${encodeURIComponent('C:\\tmp\\shot.png')}`,- undefined,+ expect.objectContaining({ beforeFetch: expect.any(Function) }),);});});diff --git a/apps/mobile/src/__tests__/remoteMedia.test.ts b/apps/mobile/src/__tests__/remoteMedia.test.tsindex 0b1d7adf6a..37d39ef774 100644--- a/apps/mobile/src/__tests__/remoteMedia.test.ts+++ b/apps/mobile/src/__tests__/remoteMedia.test.ts@@ -12,6 +12,42 @@ import {} from "@/session/remoteMedia";describe("mobile remote media", () => {+ it('retains a background fallback and releases its staging copy and cloud object', async () => {+ const { recordPeerMedia } = await import('@/device-link/peerFileRegistry');+ const local = { ossKey: '', mimeType: 'application/pdf', size: 3 };+ const dispose = vi.fn();+ recordPeerMedia(local, 'file:///background/pdf', dispose);+ let retain!: NonNullable<import('@/session/remoteMedia').MobileRemoteMediaFetchOptions['retainBackground']>;+ const discardBackgroundOssKey = vi.fn();+ await resolveMobileRemoteMedia({ kind: 'file', url: 'xdt-file://open?path=/a.pdf' }, {+ fetchRemoteMedia: async (_url, options) => {+ retain = options!.retainBackground!;+ return { ...local, inlineBase64: 'YWJj' };+ },+ presignGet: async () => ({ getUrl: 'https://oss/new', expiresAt: '2099-01-01T00:00:00Z' }),+ }, { stream: false, discardBackgroundOssKey });+ const cacheDownload = vi.fn(async () => local);+ await retain({ ...local, ossKey: 'oss/new', cacheDownload });+ expect(cacheDownload).toHaveBeenCalledWith('https://oss/new');+ expect(dispose).toHaveBeenCalledOnce();+ expect(discardBackgroundOssKey).toHaveBeenCalledWith('oss/new');+ });+ it('returns a completed fallback copy while preserving ownership of the OSS object', async () => {+ const { recordPeerMedia, releasePeerMedia } = await import('@/device-link/peerFileRegistry');+ const local = { ossKey: '', mimeType: 'application/pdf', size: 3 };+ recordPeerMedia(local, 'file:///cached/pdf', () => {});+ const cacheDownload = vi.fn(async () => local);+ const onOssKey = vi.fn();+ try {+ const result = await resolveMobileRemoteMedia({ kind: 'file', url: 'xdt-file://open?path=/a.pdf' }, {+ fetchRemoteMedia: async () => ({ ossKey: 'oss/file', size: 3, mimeType: local.mimeType, cacheDownload }),+ presignGet: async () => ({ getUrl: 'https://oss/file', expiresAt: '2099-01-01T00:00:00Z' }),+ }, { stream: false, onOssKey });+ expect(result).toMatchObject({ url: 'file:///cached/pdf', ossKey: 'oss/file' });+ expect(cacheDownload).toHaveBeenCalledWith('https://oss/file');+ expect(onOssKey).toHaveBeenCalledExactlyOnceWith('oss/file');+ } finally { releasePeerMedia('file:///cached/pdf'); }+ });it.each(['DEVICE_OFFLINE', 'NOT_CONNECTED', 'DEVICE_LINK_NOT_CONNECTED', 'PEER_OFFLINE'])('recognizes the structured %s code even when its message has no code', (code) => {expect(mediaLoadFailureKey(Object.assign(new Error('remote device is unavailable'), { code }))).toBe('message.lightbox.deviceOffline');diff --git a/apps/mobile/src/__tests__/remoteMediaDiskCache.test.ts b/apps/mobile/src/__tests__/remoteMediaDiskCache.test.tsindex 0047d2efa7..5093009f21 100644--- a/apps/mobile/src/__tests__/remoteMediaDiskCache.test.ts+++ b/apps/mobile/src/__tests__/remoteMediaDiskCache.test.ts@@ -36,6 +36,17 @@ const URL_B = 'xdt-image://cache/b.png';const URL_C = 'xdt-image://cache/c.png';describe('remoteMediaDiskCache', () => {+ it('keeps the previous version available until a changed download successfully commits', async () => {+ const { io } = memoryIO();+ const cache = createRemoteMediaDiskCache(io);+ await cache.store(URL_A, 'https://old', 'application/pdf', 1000, 'a'.repeat(64));+ expect(await cache.lookup(URL_A, 'b'.repeat(64))).toBeNull();+ vi.mocked(io.download).mockResolvedValueOnce(null);+ expect(await cache.store(URL_A, 'https://new', 'application/pdf', 1000, 'b'.repeat(64))).toBe(false);+ expect(await cache.lookup(URL_A)).toMatchObject({ version: 'a'.repeat(64), size: 1000 });+ await cache.store(URL_A, 'https://new', 'application/pdf', 1000, 'b'.repeat(64));+ expect(await cache.lookup(URL_A)).toMatchObject({ version: 'b'.repeat(64), size: 1000 });+ });it('protects the source of a pending copy while reclaiming other entries', async () => {const h = memoryIO();let capacity = 10_000;diff --git a/apps/mobile/src/__tests__/remoteMediaDiskCacheExpo.test.ts b/apps/mobile/src/__tests__/remoteMediaDiskCacheExpo.test.tsindex 632a7c39bb..9ef3d5a6aa 100644--- a/apps/mobile/src/__tests__/remoteMediaDiskCacheExpo.test.ts+++ b/apps/mobile/src/__tests__/remoteMediaDiskCacheExpo.test.ts@@ -3,6 +3,7 @@ import {downloadRemoteMediaAsDataUri,downloadRemoteMediaShareTemp,withDownloadedRemoteMediaFile,+ retainRemoteFilePreview,} from '@/session/remoteMediaDiskCacheExpo';const io = vi.hoisted(() => ({@@ -63,6 +64,18 @@ beforeEach(() => {});describe('bounded temporary media downloads', () => {+ it('keeps a preview copy alive after transport staging expires, until its owner releases it', async () => {+ const { recordPeerMedia, releasePeerMedia } = await import('@/device-link/peerFileRegistry');+ const dispose = vi.fn();+ recordPeerMedia({ ossKey: '', size: 5, mimeType: 'application/pdf' }, 'file:///peer/source', dispose);+ const retained = await retainRemoteFilePreview('file:///peer/source', 'application/pdf', 'preview.pdf');+ expect(io.copied.has(retained.uri)).toBe(true);+ expect(dispose).toHaveBeenCalledOnce();+ releasePeerMedia('file:///peer/source');+ expect(io.remove).not.toHaveBeenCalled();+ retained.release();+ expect(io.remove).toHaveBeenCalledExactlyOnceWith(retained.uri);+ });it('keeps the file until the asynchronous consumer finishes, then removes it', async () => {let finish!: (value: string) => void;const read = vi.fn(() => new Promise<string>((done) => { finish = done; }));diff --git a/apps/mobile/src/device-link/mobileMakerTransport.ts b/apps/mobile/src/device-link/mobileMakerTransport.tsindex 3e850e9c37..a63b6c578c 100644--- a/apps/mobile/src/device-link/mobileMakerTransport.ts+++ b/apps/mobile/src/device-link/mobileMakerTransport.ts@@ -4,6 +4,7 @@ import {releasePeerMedia,} from "./peerFileRegistry";import { withTransientRemoteRetry } from "./remoteRetry";+import { getActiveMobileSessionRealm } from '@/config/env';import { expandGhostCommand, parseGhostCommandWord, splitGhostDirective } from '@cindy/maker-shared/ghost-command';import { composerPluginListSchema, isComposerPluginCatalogUnsupportedError, type ComposerPlugin } from '@/session/remoteComposerPlugins';import type { OrcaWorkerAgentKind, OrcaWorkerPermissionMode } from "@cindy/maker-shared/orca-team";@@ -43,6 +44,7 @@ import {createDeviceFileOperations,exportDeviceFile,assertFileReadActive,+ validFileVersion,type DeviceFileResult,} from "@cindy/device-link";import { errorText, mediaExtOf, nextFileTrace } from "@/debug/fileDiagnostics";@@ -911,6 +913,7 @@ export interface MobileMakerTransport {beforeInvoke?: () => Promise<unknown>,options?: {stream?: boolean;+ retainBackground?: MobileRemoteMediaFetchOptions['retainBackground'];/** Upload progress while the computer stages the file in cloud storage. */onProgress?: (uploaded: number, total: number) => void;},@@ -1006,6 +1009,8 @@ export type SessionMetaPatch = Partial<>;export const MOBILE_MAKER_CHANNELS = MOBILE_REMOTE_INVOKE_CHANNELS;+const fileReferences = new Map<string, string>();+let fileReferencesOwner = '';export function createMobileMakerTransport({deviceId,@@ -1014,8 +1019,17 @@ export function createMobileMakerTransport({}: MobileMakerTransportDeps): MobileMakerTransport {const fileOwner = getMobileAuthOwner();const callerIsCurrent = isCurrent;- isCurrent = () =>+ const fileIsCurrent = () =>isMobileAuthOwnerCurrent(fileOwner) && callerIsCurrent?.() !== false;+ isCurrent = fileIsCurrent;+ const fileCacheOwner = JSON.stringify([getActiveMobileSessionRealm(), fileOwner.accountId]);+ const referenceOwner = JSON.stringify([fileOwner.accountKey, fileOwner.generation]);+ if (fileReferencesOwner !== referenceOwner) { fileReferences.clear(); fileReferencesOwner = referenceOwner; }+ const getFileCache = async () => {+ if (!fileOwner.accountId || !fileIsCurrent()) return null;+ const { createPeerFileCache } = await import('./peerFileCache');+ return createPeerFileCache(fileCacheOwner);+ };const call = <T>(channel: string, args: unknown[] = []): Promise<T> => {if (!deviceId)return Promise.reject(new Error("remote device id is required"));@@ -1054,15 +1068,35 @@ export function createMobileMakerTransport({fallback?: () => Promise<MobileRemoteMediaFetchResult>,stream = opts?.stream ?? true,) => {- const fetch = (prepareOnly: boolean) =>- call<MobileRemoteMediaFetchResult>(DEVICE_LINK_MEDIA_FETCH_CHANNEL, [+ const fetch = async (prepareOnly: boolean, metadataOnly = false) => {+ if (!fileIsCurrent() || opts?.signal?.aborted) throw new Error('FILE_PEER_CANCELLED');+ await opts?.beforeFetch?.();+ if (!fileIsCurrent() || opts?.signal?.aborted) throw new Error('FILE_PEER_CANCELLED');+ return call<MobileRemoteMediaFetchResult>(DEVICE_LINK_MEDIA_FETCH_CHANNEL, [{url,prepareOnly,+ ...(metadataOnly ? { metadataOnly: true } : {}),...(opts?.skipCache ? { skipCache: true } : {}),...(opts?.thumbnail ? { thumbnail: true } : {}),},]);+ };+ const withDownload = (result: MobileRemoteMediaFetchResult): MobileRemoteMediaFetchResult => {+ if (stream || opts?.thumbnail || !result.ossKey || !validFileVersion(result.version)) return result;+ return { ...result, cacheDownload: async (downloadUrl) => {+ const active = () => fileIsCurrent() && !opts?.signal?.aborted;+ if (!active()) throw new Error('FILE_PEER_CANCELLED');+ const cache = await getFileCache().catch(() => null);+ const local = await cache?.download(deviceId, url, result, downloadUrl, active, opts?.signal).catch(() => null);+ if (!active()) {+ const uri = local && peerMediaUri(local);+ if (uri) releasePeerMedia(uri);+ throw new Error('FILE_PEER_CANCELLED');+ }+ return local ?? null;+ } };+ };// Chat thumbnails are high-volume and already covered by the list; trace full-file reads only.const trace = opts?.thumbnail ? 0 : nextFileTrace();const stage = <T>(@@ -1107,7 +1141,28 @@ export function createMobileMakerTransport({"result",() =>readDeviceFile({+ cacheFirst: stream || opts?.skipCache || opts?.thumbnail || isSharedTaskPeer(deviceId) ? undefined : {+ key: JSON.stringify([fileOwner.accountKey, fileOwner.generation, deviceId, url]),+ read: async () => (await getFileCache())?.readLatest(deviceId, url, () => fileIsCurrent() && !opts?.signal?.aborted) ?? null,+ retain: async (result) => { await opts?.retainBackground?.(withDownload(result), fileIsCurrent); },+ },stream,+ inline: () => fetch(true),+ revalidate: () => fetch(true, true),+ inlineCache: opts?.thumbnail ? undefined : {+ read: async (metadata) => {+ const cache = await getFileCache();+ if (opts?.skipCache) {+ await cache?.invalidate(deviceId, url);+ return null;+ }+ return cache?.readInline(deviceId, url, metadata, () => isCurrent() && !opts?.signal?.aborted) ?? null;+ },+ store: async (result) => {+ const cache = await getFileCache();+ if (isCurrent() && !opts?.signal?.aborted) await cache?.storeInline(deviceId, url, result);+ },+ },peerResultIsTransient: true,isCurrent,discard: (result) => {@@ -1122,7 +1177,7 @@ export function createMobileMakerTransport({},signal: opts?.signal,prepare: () =>- stage("prepare", () => fetch(!opts?.thumbnail), describeResult),+ stage("prepare", () => fetch(!opts?.thumbnail, !opts?.thumbnail), describeResult),peer: (metadata) =>metadata.size <= FILE_PEER_MAX_BYTES? stage(@@ -1143,7 +1198,7 @@ export function createMobileMakerTransport({: "upload",size: result.size,}),- );+ ).then(withDownload);};return {@@ -1529,13 +1584,18 @@ export function createMobileMakerTransport({assertFileReadActive(signal);return fileOp<T>(args);});+ const referenceKey = JSON.stringify([referenceOwner, deviceId, workdir, relPath]);+ const knownUrl = fileReferences.get(referenceKey);+ const fallback = () =>+ exportDeviceFile(retryOp, workdir, relPath, signal, options?.onProgress);+ const fetchOptions = { signal, beforeFetch: beforeInvoke, retainBackground: options?.retainBackground };+ if (knownUrl && !isSharedTaskPeer(deviceId))+ return fetchMedia(knownUrl, fetchOptions, fallback, options?.stream ?? false);const caps = await retryOp<{ fileRead?: boolean }>({op: "caps",workdir,});assertFileReadActive(signal);- const fallback = () =>- exportDeviceFile(retryOp, workdir, relPath, signal, options?.onProgress);if (!caps.fileRead) {mobileDebugLog("debug", "files", "file export without direct read", {reason: "host-lacks-file-read",@@ -1550,7 +1610,8 @@ export function createMobileMakerTransport({assertFileReadActive(signal);if (!reference.ok)throw new Error(reference.message ?? "FILE_READ_FAILED");- return fetchMedia(reference.url, { signal }, fallback, options?.stream ?? false);+ if (fileIsCurrent()) fileReferences.set(referenceKey, reference.url);+ return fetchMedia(reference.url, fetchOptions, fallback, options?.stream ?? false);},caps: (workdir) =>call("file-browser:remote-op", [{ op: "caps", workdir }]),diff --git a/apps/mobile/src/device-link/peerFileCache.ts b/apps/mobile/src/device-link/peerFileCache.tsindex c1bf06d50e..16d93ce59a 100644--- a/apps/mobile/src/device-link/peerFileCache.ts+++ b/apps/mobile/src/device-link/peerFileCache.ts@@ -4,13 +4,14 @@ import {digestStringAsync,randomUUID,} from "expo-crypto";-import { validFileVersion, type DeviceFileResult } from "@cindy/device-link";+import { FILE_INLINE_MAX_BYTES, validFileVersion, type DeviceFileResult } from "@cindy/device-link";import { createRemoteMediaDiskCache } from "@/session/remoteMediaDiskCache";-import { createExpoRemoteMediaDiskCacheIO } from "@/session/remoteMediaDiskCacheExpo";+import { createExpoRemoteMediaDiskCacheIO, downloadRemoteMediaShareTemp } from "@/session/remoteMediaDiskCacheExpo";import {PEER_FILE_DISK_RESERVE_BYTES,recordPeerMedia,peerMediaUri,+ releasePeerMedia,type LocalPeerMedia,} from "./peerFileRegistry";@@ -39,7 +40,44 @@ async function openPeerFileCache(owner: string) {persistAccess: true,},);- return {+ const api = {+ async readLatest(device: string, url: string, active: () => boolean): Promise<DeviceFileResult | null> {+ const hit = await cache.lookup(JSON.stringify([device, url]));+ if (!active() || !hit || !validFileVersion(hit.version)) return null;+ const metadata = { size: hit.size, mimeType: hit.mimeType, version: hit.version };+ return hit.size <= FILE_INLINE_MAX_BYTES+ ? api.readInline(device, url, metadata, active)+ : api.read(device, url, metadata, active);+ },+ /** A completed OSS fallback joins the same version cache as direct downloads. */+ async download(device: string, url: string, metadata: Metadata, downloadUrl: string,+ active: () => boolean, signal?: AbortSignal): Promise<LocalPeerMedia | null> {+ if (!active() || !validFileVersion(metadata.version) || !(await cache.prune(2 * metadata.size))) return null;+ const uri = await downloadRemoteMediaShareTemp(downloadUrl, metadata.mimeType, undefined, signal);+ if (!uri) return null;+ const file = new File(uri);+ const dispose = () => { if (file.exists) file.delete(); };+ if (!active() || signal?.aborted || file.size !== metadata.size) { dispose(); return null; }+ const result = { ossKey: '', ...metadata };+ if (!recordPeerMedia(result, uri, dispose)) { dispose(); return null; }+ await api.store(device, url, metadata, result).catch(() => undefined);+ if (!active() || signal?.aborted) { releasePeerMedia(uri); return null; }+ return result;+ },+ async readInline(device: string, url: string, metadata: Metadata, active: () => boolean) {+ if (!validFileVersion(metadata.version) || metadata.size > FILE_INLINE_MAX_BYTES) return null;+ const hit = await cache.lookup(JSON.stringify([device, url]), metadata.version);+ if (!active() || !hit || hit.size !== metadata.size) return null;+ const inlineBase64 = await new File(hit.uri).base64();+ if (!active()) return null;+ return { ossKey: '', ...metadata, inlineBase64 };+ },+ async storeInline(device: string, url: string, result: DeviceFileResult) {+ if (!validFileVersion(result.version) || typeof result.inlineBase64 !== 'string'+ || result.size > FILE_INLINE_MAX_BYTES) return;+ await cache.store(JSON.stringify([device, url]),+ `data:${result.mimeType};base64,${result.inlineBase64}`, result.mimeType, result.size, result.version);+ },prune: (size: number) => cache.prune(2 * size),invalidate: (device: string, url: string) =>cache.remove(JSON.stringify([device, url])),@@ -105,4 +143,5 @@ async function openPeerFileCache(owner: string) {);},};+ return api;}diff --git a/apps/mobile/src/session/fileBrowserCache.ts b/apps/mobile/src/session/fileBrowserCache.tsindex f9a3a9d01d..22f3d8ff72 100644--- a/apps/mobile/src/session/fileBrowserCache.ts+++ b/apps/mobile/src/session/fileBrowserCache.ts@@ -261,10 +261,10 @@ export function getCachedPreviewText(scope: string,workdir: string,relPath: string,- mtimeMs: number,+ _mtimeMs: number,): CachedPreviewText | null {workdir = JSON.stringify([scope, workdir]);- const key = snippetKey(workdir, relPath, mtimeMs);+ const key = snippetKey(workdir, relPath, 0);const value = previewTextMemory.get(key);if (!value) return null;previewTextMemory.delete(key);@@ -276,11 +276,11 @@ export function storeCachedPreviewText(scope: string,workdir: string,relPath: string,- mtimeMs: number,+ _mtimeMs: number,value: CachedPreviewText,): void {workdir = JSON.stringify([scope, workdir]);- const key = snippetKey(workdir, relPath, mtimeMs);+ const key = snippetKey(workdir, relPath, 0);previewTextMemory.delete(key);previewTextMemory.set(key, value);while (previewTextMemory.size > PREVIEW_TEXT_MAX_ENTRIES) {diff --git a/apps/mobile/src/session/fileBrowserExport.ts b/apps/mobile/src/session/fileBrowserExport.tsindex ea5ff3ca94..7b1e5f23aa 100644--- a/apps/mobile/src/session/fileBrowserExport.ts+++ b/apps/mobile/src/session/fileBrowserExport.ts@@ -1,6 +1,6 @@/*** 浏览页与预览页共用文件读取接口,转换为分享/下载地址。- * 按账号、设备、path 和 mtime 缓存到地址过期;传输选择与瞬断重试由文件接口负责。+ * 完整文件由共用读取层优先返回本地缓存、后台复验;流式地址保留独立有效期。*/import { i18n } from "@/i18n";import type { MobileMakerTransport } from "@/device-link/mobileMakerTransport";@@ -9,7 +9,7 @@ import {storeCachedExportUrl,} from "@/session/fileBrowserCache";import type { MobileRemoteMediaPresignResult } from "@/session/remoteMedia";-import { peerMediaUri, peerMediaExpiry } from "@/device-link/peerFileRegistry";+import { peerMediaUri, releasePeerMedia } from "@/device-link/peerFileRegistry";import { errorText } from "@/debug/fileDiagnostics";import { mobileDebugLog } from "@/debug/mobileDebugLog";@@ -20,6 +20,7 @@ export interface ExportRemoteFileDeps {deviceId: string;openLink: (deviceId: string) => Promise<unknown>;presignGet: (ossKey: string) => Promise<MobileRemoteMediaPresignResult>;+ deleteOssObject?: (key: string) => void;/** 取消信号(如页面卸载),转成文件读取接口的 AbortSignal。 */isCancelled?: () => boolean;/** 电脑上传到云存储期间的真实字节进度(缓存命中与直连不回调)。 */@@ -34,7 +35,7 @@ export async function exportRemoteFileToUrl(): Promise<string> {const ownerScope = deps.maker.fileBrowser.cacheScope ?? deps.deviceId;const scope = JSON.stringify([ownerScope, deps.stream === true ? "stream" : "file"]);- const cached = getCachedExportUrl(scope, workdir, relPath, mtimeMs);+ const cached = deps.stream === true ? getCachedExportUrl(scope, workdir, relPath, mtimeMs) : null;if (cached) {mobileDebugLog("debug", "files", "file export cache hit", { stream: deps.stream === true });return cached;@@ -52,22 +53,22 @@ export async function exportRemoteFileToUrl(relPath,abort.signal,() => deps.openLink(deps.deviceId),- { stream: deps.stream === true, onProgress: deps.onProgress },+ { stream: deps.stream === true, onProgress: deps.onProgress,+ retainBackground: async (fresh, isCurrent) => {+ if (!fresh.ossKey || isCurrent?.() === false) return;+ try {+ const signed = await deps.presignGet(fresh.ossKey);+ const local = await fresh.cacheDownload?.(signed.getUrl);+ const uri = local && peerMediaUri(local);+ if (uri) releasePeerMedia(uri);+ } finally { if (isCurrent?.() !== false) deps.deleteOssObject?.(fresh.ossKey); }+ },+ },);check();if (abort.signal.aborted) throw new Error(i18n.t("files.export.leftPage"));const local = peerMediaUri(result);- if (local) {- storeCachedExportUrl(- scope,- workdir,- relPath,- mtimeMs,- local,- peerMediaExpiry(result)!,- );- return local;- }+ if (local) return local;if (result.inlineBase64 !== undefined)return `data:${result.mimeType};base64,${result.inlineBase64}`;const presignStartedAt = Date.now();@@ -78,13 +79,16 @@ export async function exportRemoteFileToUrl(});throw error;});+ const downloaded = await result.cacheDownload?.(signed.getUrl);+ const downloadedUri = downloaded && peerMediaUri(downloaded);+ if (downloadedUri) return downloadedUri;mobileDebugLog("debug", "files", "file export presigned", {ms: Date.now() - presignStartedAt,size: result.size,});check();if (abort.signal.aborted) throw new Error(i18n.t("files.export.leftPage"));- storeCachedExportUrl(+ if (deps.stream === true) storeCachedExportUrl(scope,workdir,relPath,diff --git a/apps/mobile/src/session/pdfPreviewSource.ts b/apps/mobile/src/session/pdfPreviewSource.tsindex 40f7b0c9c9..a362b4e744 100644--- a/apps/mobile/src/session/pdfPreviewSource.ts+++ b/apps/mobile/src/session/pdfPreviewSource.ts@@ -1,16 +1,8 @@-import { File } from 'expo-file-system';-import { downloadRemoteMediaShareTemp } from '@/session/remoteMediaDiskCacheExpo';+import { retainRemoteFilePreview } from '@/session/remoteMediaDiskCacheExpo';/** WKWebView cannot load a data URI through its native file-URL loader. */export async function preparePdfPreviewSource(url: string): Promise<{ uri: string; release(): void }> {- if (/^(https?:\/\/|file:\/\/)/i.test(url)) return { uri: url, release() {} };- if (!url.startsWith('data:application/pdf;base64,')) throw new Error('INVALID_PDF_URL');- const uri = await downloadRemoteMediaShareTemp(url, 'application/pdf', 'preview.pdf');- if (!uri) throw new Error('PDF_CACHE_FAILED');- return {- uri,- release() {- try { const file = new File(uri); if (file.exists) file.delete(); } catch { /* OS cache reclamation is the fallback. */ }- },- };+ if (!/^(https?:\/\/|file:\/\/)/i.test(url) && !url.startsWith('data:application/pdf;base64,'))+ throw new Error('INVALID_PDF_URL');+ return retainRemoteFilePreview(url, 'application/pdf', 'preview.pdf');}diff --git a/apps/mobile/src/session/remoteAbsFileFetch.ts b/apps/mobile/src/session/remoteAbsFileFetch.tsindex 865f9f2149..b1c504e3b0 100644--- a/apps/mobile/src/session/remoteAbsFileFetch.ts+++ b/apps/mobile/src/session/remoteAbsFileFetch.ts@@ -9,7 +9,8 @@* ——media:fetch 故意不限 workdir,靠 device-link 的三道 gate(被控开关 /* 撤销黑名单 / channel 白名单)保证「等同本地访问」的信任级。*- * 缓存策略(bot review 实捉后收紧):`xdt-file://` 不进被控端 mtime/size 感知+ * 完整文件进入共用读取层,优先使用持久字节缓存、后台复验,不复用下述临时 URL。+ * 流式地址缓存策略:`xdt-file://` 不进被控端 mtime/size 感知* 的上传去重缓存(那只对 `xdt-image://` 生效,见 desktop mediaFetch.ts),手机侧* 又没有 mtime 来源可验证文件是否被覆写——若按 presign 全期(约 1 小时)缓存,* 同路径文件被 agent 覆写后会一直吃到旧字节。因此这里只做**短 TTL** 缓存:@@ -43,6 +44,7 @@ export interface RemoteAbsFileFetchDeps {deviceId: string;openLink: (deviceId: string) => Promise<unknown>;presignGet: (ossKey: string) => Promise<MobileRemoteMediaPresignResult>;+ deleteOssObject?: (key: string) => void;/** 取消信号(如页面卸载、导出提示上的「取消」):中止取件,不再重试。 */isCancelled?: () => boolean;}@@ -101,7 +103,7 @@ export async function fetchRemoteAbsFileToUrl(? `${eff.sessionId}\u0000${eff.remoteHostId}\u0000${eff.workdir}`: '';const key = `${deps.deviceId}\u0000${absPath}\u0000${sshKey}\u0000${deps.stream === false ? 'file' : 'stream'}`;- const cached = lookupCache(key, Date.now());+ const cached = deps.stream === false ? null : lookupCache(key, Date.now());if (cached) return cached.url;// 与 exportRemoteFileToUrl 同一写法:轮询 isCancelled 转成取件的 AbortSignal。const abort = deps.isCancelled ? new AbortController() : null;@@ -115,12 +117,13 @@ export async function fetchRemoteAbsFileToUrl(const timer = abort ? setInterval(check, 100) : null;try {const fetchOpts = {+ beforeFetch: () => deps.openLink(deps.deviceId),+ ...(deps.deleteOssObject ? { discardBackgroundOssKey: deps.deleteOssObject } : {}),...(deps.stream === false ? { stream: false } : {}),...(abort ? { signal: abort.signal } : {}),};const resolved = await withTransientRemoteRetry(async () => {assertActive();- await deps.openLink(deps.deviceId);// kind 只影响结果的 previewable 标志(此处不消费),按 image 占位。return resolveMobileRemoteMedia({ kind: 'image', url: remoteFileMediaUrl(absPath, undefined, ssh) },@@ -128,7 +131,7 @@ export async function fetchRemoteAbsFileToUrl(Object.keys(fetchOpts).length ? fetchOpts : undefined,);});- rememberFetch(key, resolved, Date.now());+ if (deps.stream !== false) rememberFetch(key, resolved, Date.now());assertActive();return resolved.url;} finally {@@ -169,12 +172,12 @@ export async function fetchRemoteAbsFileOnce(signal?: AbortSignal,): Promise<MobileResolvedRemoteMedia> {return withTransientRemoteRetry(async () => {- await deps.openLink(deps.deviceId);// kind 只影响结果的 previewable 标志(此处不消费),按 image 占位。return resolveMobileRemoteMedia({ kind: 'image', url: remoteFileMediaUrl(absPath, undefined, ssh, constraints) },{ fetchRemoteMedia: deps.maker.fetchRemoteMedia, presignGet: deps.presignGet },- { onOssKey, signal, stream: false },+ { onOssKey, signal, stream: false, beforeFetch: () => deps.openLink(deps.deviceId),+ discardBackgroundOssKey: deps.deleteOssObject },);});}diff --git a/apps/mobile/src/session/remoteMedia.ts b/apps/mobile/src/session/remoteMedia.tsindex 85414bada1..eac26f5713 100644--- a/apps/mobile/src/session/remoteMedia.ts+++ b/apps/mobile/src/session/remoteMedia.ts@@ -1,4 +1,4 @@-import { peerMediaUri, peerMediaExpiry } from "@/device-link/peerFileRegistry";+import { peerMediaUri, peerMediaExpiry, releasePeerMedia } from "@/device-link/peerFileRegistry";import type { NormalizedToolMedia } from "@/session/messageNormalize";import {isPayloadDesktopLocalMediaUrl,@@ -22,6 +22,9 @@ export function mediaLoadFailureKey(error: unknown): 'message.lightbox.sourceMis}export interface MobileRemoteMediaFetchResult {+ version?: string;+ /** Local adapter only; never sent over device-link. Copies an OSS result into the shared file cache. */+ cacheDownload?: (downloadUrl: string) => Promise<MobileRemoteMediaFetchResult | null>;/** inline 缩略图回包(新被控端)时为空串。 */ossKey: string;mimeType: string;@@ -48,6 +51,9 @@ export interface MobileResolvedRemoteMedia {}export interface MobileRemoteMediaFetchOptions {+ /** Local callbacks: only connect on a cache miss or during background revalidation. */+ beforeFetch?: () => Promise<unknown>;+ retainBackground?: (result: MobileRemoteMediaFetchResult, isCurrent?: () => boolean) => Promise<void>;/** Local read intent only; false for consumers that copy complete bytes. */stream?: boolean;skipCache?: boolean;@@ -66,6 +72,8 @@ export interface MobileRemoteMediaResolverDeps {}export interface MobileRemoteMediaResolveOptions {+ beforeFetch?: () => Promise<unknown>;+ discardBackgroundOssKey?: (key: string) => void;stream?: boolean;signal?: AbortSignal;/** 强制被控端绕过上传去重缓存(上次的 ossKey 已悬空时的自愈路径)。 */@@ -180,6 +188,16 @@ export async function resolveMobileRemoteMedia(throw new Error(i18n.t("composer.attachments.notFetchableMedia"));}const fetchOpts = {+ ...(opts?.beforeFetch ? { beforeFetch: opts.beforeFetch } : {}),+ ...(opts?.stream === false ? { retainBackground: async (result: MobileRemoteMediaFetchResult, isCurrent?: () => boolean) => {+ if (!result.ossKey || isCurrent?.() === false) return;+ try {+ const signed = await deps.presignGet(result.ossKey);+ const copy = await result.cacheDownload?.(signed.getUrl);+ const uri = copy && peerMediaUri(copy);+ if (uri) releasePeerMedia(uri);+ } finally { if (isCurrent?.() !== false) opts.discardBackgroundOssKey?.(result.ossKey); }+ } } : {}),...(opts?.stream !== undefined ? { stream: opts.stream } : {}),...(opts?.onOssKey ? { onDiscardOssKey: opts.onOssKey } : {}),...(opts?.signal ? { signal: opts.signal } : {}),@@ -238,6 +256,13 @@ export async function resolveMobileRemoteMedia(mobileDebugLog("warn", "files", "remote media presign invalid", { kind: media.kind });throw new Error(i18n.t("composer.attachments.mediaUrlInvalid"));}+ const downloaded = await fetched.cacheDownload?.(signed.getUrl);+ const downloadedUri = downloaded && peerMediaUri(downloaded);+ if (downloadedUri) return {+ url: downloadedUri, ossKey: fetched.ossKey, mimeType: fetched.mimeType, size: fetched.size,+ expiresAt: peerMediaExpiry(downloaded!)!,+ previewable: canPreviewResolvedRemoteMedia(media.kind, fetched.mimeType),+ };if (media.kind !== "image")mobileDebugLog("debug", "files", "remote media presigned", {kind: media.kind,diff --git a/apps/mobile/src/session/remoteMediaDiskCache.ts b/apps/mobile/src/session/remoteMediaDiskCache.tsindex f7c3cf03f8..79df86e53e 100644--- a/apps/mobile/src/session/remoteMediaDiskCache.ts+++ b/apps/mobile/src/session/remoteMediaDiskCache.ts@@ -56,6 +56,7 @@ export interface RemoteMediaDiskCacheHit {uri: string;mimeType: string;size: number;+ version?: string;}export interface RemoteMediaDiskCache {@@ -140,7 +141,7 @@ export function createRemoteMediaDiskCache(* download / writeFileBase64 落位之后的共同收尾(两条写入路径同一套失败语义):* - size === null:写入失败(IO 契约保证原子落位、失败不动现有文件)——同名* 刷新场景下 name 就是现存条目的好文件,不能误删;只清理并非现存条目的半成品;- * - size <= 0:0 字节文件已落位顶替,文件与同名旧条目一并作废,下次 lookup 重取;+ * - size === 0:普通图片缓存视为失败;版本已确认的空文件(例如 CSS)正常保留;* - 成功:mime 变化换扩展名时删除不再被引用的旧文件,登记条目并做配额回收。* 返回 true 仅当本次确实登记了新写入的字节(见 store 返回值契约)。*/@@ -158,7 +159,7 @@ export function createRemoteMediaDiskCache(}return false;}- if (size <= 0 || !entries) {+ if (size < 0 || (size === 0 && !version) || !entries) {await Promise.resolve(io.deleteFile(name)).catch(() => undefined);if (prev && prev.name === name && entries) {entries.delete(key);@@ -230,9 +231,7 @@ export function createRemoteMediaDiskCache(const entry = entries?.get(key);if (!entry) return null;if (version !== undefined && entry.version !== version) {- await Promise.resolve(io.deleteFile(entry.name)).catch(() => undefined);- entries?.delete(key);- await persistIndex().catch(() => undefined);+ // Keep the last usable copy until its replacement commits successfully.return null;}const exists = await Promise.resolve(io.fileExists(entry.name)).catch(() => false);@@ -244,7 +243,8 @@ export function createRemoteMediaDiskCache(}entry.lastUsedAt = now();if (options.persistAccess) await persistIndex().catch(() => undefined);- return { uri: io.fileUri(entry.name), mimeType: entry.mimeType, size: entry.size };+ return { uri: io.fileUri(entry.name), mimeType: entry.mimeType, size: entry.size,+ ...(entry.version ? { version: entry.version } : {}) };},async store(sourceUrl, downloadUrl, mimeType, expectedSize, version) {@@ -262,6 +262,10 @@ export function createRemoteMediaDiskCache(const name = `${key}${version ? `-${version}` : ''}.${extOfMime(mimeType)}`;const prev = entries?.get(key);const size = await io.download(downloadUrl, name);+ if (size !== null && expectedSize !== undefined && size !== expectedSize) {+ await Promise.resolve(io.deleteFile(name)).catch(() => undefined);+ return false;+ }return commitWrittenFile(key, name, prev, size, mimeType, version);};const pending = downloading.get(key);diff --git a/apps/mobile/src/session/remoteMediaDiskCacheExpo.ts b/apps/mobile/src/session/remoteMediaDiskCacheExpo.tsindex 3a1a071638..bee7eca5fd 100644--- a/apps/mobile/src/session/remoteMediaDiskCacheExpo.ts+++ b/apps/mobile/src/session/remoteMediaDiskCacheExpo.ts@@ -7,6 +7,7 @@* JS 层引用,不影响 fingerprint(以 mobile:release:check 实测为准)。*/import { Directory, File, Paths } from "expo-file-system";+import { releasePeerMedia } from '@/device-link/peerFileRegistry';import {extOfMime,@@ -79,6 +80,21 @@ async function copyRemoteFile(return File.downloadFileAsync(url, target, { idempotent: true });}+/** A visible preview owns its copy; transport staging and cache eviction cannot expire it. */+export async function retainRemoteFilePreview(url: string, mimeType: string, fileName: string) {+ if (!url.startsWith('file://') && !url.startsWith('data:')) return { uri: url, release() {} };+ let uri: string | null;+ try { uri = await downloadRemoteMediaShareTemp(url, mimeType, fileName); }+ finally { if (url.startsWith('file://')) releasePeerMedia(url); }+ if (!uri) throw new Error('PREVIEW_CACHE_FAILED');+ return {+ uri,+ release() {+ try { const file = new File(uri); if (file.exists) file.delete(); } catch { /* OS reclaims cache files. */ }+ },+ };+}+/*** 一次性分享临时文件:超出磁盘缓存预算的对象走 store 会被 LRU 立即逐出,* lookup 拿不到 → 分享失败。这里绕开 LRU 直接下到独立临时目录,只服务本次@@ -220,7 +236,7 @@ export function createExpoRemoteMediaDiskCacheIO(namespace?: string): RemoteMediencoding: FileSystem.EncodingType.Base64,});const size = tmp.size ?? 0;- if (size <= 0) {+ if (size < 0) {if (tmp.exists) tmp.delete();return null;}diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.mdindex 36ceee229e..91185493f4 100644--- a/docs/dev-rules/protocol-compatibility.md+++ b/docs/dev-rules/protocol-compatibility.md@@ -842,8 +842,9 @@ dev/ino/size/mtime/ctime,连同解析后的路径生成不透明版本。SSH例外:由 materializer 用远端主机、工作目录、相对路径及远端 size/mtime 生成源版本,prepare/open 复用该源版本并校验副本大小,不使用带登录代次的本地路径或 LRU 时间。缓存仍按稳定账号隔离,原有代次取消校验保留;不把版本当作授权凭据。-新版控制端只有两次版本一致且传输成功才保留私有缓存副本;读取缓存前仍执行-prepare 授权与版本查询。缺失/非法版本的旧端不启用此缓存,旧控制端忽略新增字段。+新版控制端只有两次版本一致且传输成功才保留私有缓存副本。同账号文件预览优先显示+已有本地副本,prepare 授权与版本查询放到后台;共享任务仍先复验权限。+缺失/非法版本的旧端不启用此缓存,旧控制端忽略新增字段。缓存按稳定账号、目标设备、完整媒体 URL 隔离(含 SSH 与目录约束),跨重启保留,不设时间 TTL、16 MiB 单文件门槛或条目数门槛。账号代次用于拒绝迟到结果,不能进入持久缓存键。Desktop 图片等媒体复用 `cindy-media` 的 `integration-cache` 索引和@@ -855,10 +856,26 @@ HTML 等普通文件复用 `remote-file-cache` 的 4 GiB 总量上限、LRU 与Mobile 复用 `remote-media` 磁盘缓存,放入 realm/账号 SHA-256 命名空间;无固定容量门槛,仅在现有传输空间预留不足时按 LRU 清理(保留 256 MiB,并考虑下载与消费者副本)。-访问顺序落盘、版本不同删除旧条目;版本进入物理文件名,避免异步复制撞上覆盖写。+访问顺序落盘,新版本完整保存后再替换旧条目;版本进入物理文件名,避免异步复制撞上覆盖写。系统清掉目录后,下一次取件自动重建。两端消费者均拿独立副本,清缓存不删正在预览的副本。强制刷新只跳过旧副本的读取,成功后仍更新缓存,避免下次普通打开又命中损坏副本。-已有 OSS 和流式媒体缓存维持原生命周期;此缓存只保存已完成的 peer 整文件下载。+完整文件读取统一复用版本缓存,覆盖 inline 小文件、peer 下载及已经完成的 OSS 回退下载。+`device-link:media:fetch` 在 `prepareOnly: true` 时接受可选 `metadataOnly: true`:+仍先授权并从打开的文件句柄取版本,但小文件也只返回 `transferRequired: true` 与元数据。+两端共用读取策略:小文件先查同一版本缓存,未命中再以原 `prepareOnly` 请求取 inline 字节;+大文件沿用 peer/OSS 读取。旧 Host 忽略 `metadataOnly`,新控制端接收原 inline/OSS 结果;+旧控制端不传此字段,新 Host 保持原行为。两段式导出缺版本时,以导出前后主机版本和大小一致+作为登记条件,变化或无版本的结果不登记为长期有效。缓存失败不阻断正常读取。+Mobile 的 HTML 资源、文件浏览器原图、PDF、下载/分享使用完整文件路径,先取当前账号、设备、+完整 URL 对应的本地缓存,再后台检查版本;同源在途后台检查合并。连接恢复也放到缓存读取之后。+Desktop 完整文件与远程 HTML 预览复用已知元数据和现有磁盘副本,后台检查变化;进程重启后+尚无元数据索引时先查询版本,字节仍可从已有磁盘缓存复用。后台失败保留旧副本,更新完成后+后续打开使用新版;不强制重载正在操作的 HTML、图片或 PDF。预览持有自己的副本,关闭时仅释放这份副本,+不会删除可复用的源缓存。零字节 HTML 配套资源也可按版本缓存。+音视频播放继续用保留的流式地址,不为了缓存而预先下载整份媒体;完整下载仍按上述规则。+不可变聊天图片与目录维持已有专用缓存;Mobile 限量文本预览先显示缓存(包括绝对路径),+后台读取后更新当前文本,失败不遮住已有内容,文本不改为无界整文件下载。+不增加缓存目录、额度、通道、服务端改动或 Mobile 原生指纹;完整优化需要两端客户端更新。网络帧仍是旧版可读的 16 KiB,不增加 wire 通道。新版接收运行时仅在本地桥接声明批量写入时,把已到达帧合为至多 256 KiB 后串行写盘;仍按实际写入块数归还流控额度,diff --git a/packages/device-link/src/__tests__/fileAccess.test.ts b/packages/device-link/src/__tests__/fileAccess.test.tsindex 886bd532ca..1a7ce9028a 100644--- a/packages/device-link/src/__tests__/fileAccess.test.ts+++ b/packages/device-link/src/__tests__/fileAccess.test.ts@@ -1,5 +1,5 @@import { describe, expect, it, vi } from "vitest";-import { readDeviceFile } from "../fileAccess";+import { readDeviceFile, type DeviceFileResult } from "../fileAccess";const metadata = {ossKey: "",@@ -8,6 +8,99 @@ const metadata = {transferRequired: true,};describe("shared file read policy", () => {+ it('returns cached bytes while the host is pending, and merges background revalidation', async () => {+ const cached = { ...metadata, version: 'a'.repeat(64), inlineBase64: 'YQ==' };+ let reply!: (value: DeviceFileResult) => void;+ const prepare = vi.fn(() => new Promise<DeviceFileResult>(resolve => { reply = resolve; }));+ const retain = vi.fn(), discard = vi.fn(), peer = vi.fn();+ const options = { prepare, peer, fallback: vi.fn(), discard,+ cacheFirst: { key: 'cache-first-pending', read: async () => cached, retain } };+ expect(await readDeviceFile(options)).toBe(cached);+ expect(await readDeviceFile(options)).toBe(cached);+ expect(prepare).toHaveBeenCalledOnce();+ const fresh = { ...cached, version: 'b'.repeat(64), transferRequired: false, inlineBase64: 'Yg==' };+ reply(fresh);+ await vi.waitFor(() => expect(retain).toHaveBeenCalledWith(fresh));+ expect(discard).toHaveBeenCalledWith(fresh);+ expect(peer).not.toHaveBeenCalled();+ });+ it.each(['unchanged', 'offline'] as const)('keeps cached bytes on %s without transferring them again', async mode => {+ const cached = { ...metadata, version: 'a'.repeat(64), inlineBase64: 'YQ==' };+ const prepare = vi.fn(async () => {+ if (mode === 'offline') throw new Error('offline');+ return cached;+ });+ const peer = vi.fn(), fallback = vi.fn(), retain = vi.fn();+ expect(await readDeviceFile({ prepare, peer, fallback,+ cacheFirst: { key: mode, read: async () => cached, retain } })).toBe(cached);+ await vi.waitFor(() => expect(prepare).toHaveBeenCalledOnce());+ expect(peer).not.toHaveBeenCalled();+ expect(fallback).not.toHaveBeenCalled();+ expect(retain).not.toHaveBeenCalled();+ });+ it('disposes a cached consumer copy if its account changes during lookup', async () => {+ let current = true;+ const cached = { ...metadata, version: 'a'.repeat(64) };+ const discard = vi.fn(), prepare = vi.fn();+ await expect(readDeviceFile({ prepare, peer: vi.fn(), fallback: vi.fn(), discard,+ isCurrent: () => current, cacheFirst: { key: 'switched', read: async () => { current = false; return cached; } },+ })).rejects.toThrow('FILE_PEER_CANCELLED');+ expect(discard).toHaveBeenCalledWith(cached);+ expect(prepare).not.toHaveBeenCalled();+ });+ it.each([true, false])('only versions a completed fallback when its source is unchanged (%s)', async unchanged => {+ const version = 'a'.repeat(64);+ const prepared = { ...metadata, version };+ const result = await readDeviceFile({+ prepare: async () => prepared,+ peer: async () => null,+ fallback: async () => ({ ossKey: 'export/key', size: prepared.size, mimeType: 'application/octet-stream' }),+ revalidate: async () => ({ ...prepared, version: unchanged ? version : 'b'.repeat(64) }),+ });+ expect(result.version).toBe(unchanged ? version : undefined);+ expect(result.mimeType).toBe(unchanged ? metadata.mimeType : 'application/octet-stream');+ });+ it.each(['text/html', 'text/css', 'application/javascript', 'text/plain', 'application/pdf', 'image/png', 'application/zip'])(+ 'revalidates %s before reusing bytes and replaces changed versions', async (mimeType) => {+ let version = 'a'.repeat(64);+ let stored: DeviceFileResult | undefined;+ const prepare = vi.fn(async () => ({ ...metadata, size: 3, mimeType, version }));+ const inline = vi.fn(async () => ({ ossKey: '', size: 3, mimeType, version, inlineBase64: 'YWJj' }));+ const peer = vi.fn(), fallback = vi.fn();+ const inlineCache = {+ read: vi.fn(async (meta: DeviceFileResult) => stored?.version === meta.version ? stored! : null),+ store: vi.fn(async (result: DeviceFileResult) => { stored = result; }),+ };+ const options = { prepare, inline, peer, fallback, inlineCache };+ await readDeviceFile(options);+ await readDeviceFile(options);+ expect(prepare).toHaveBeenCalledTimes(2);+ expect(inline).toHaveBeenCalledOnce();+ version = 'b'.repeat(64);+ expect((await readDeviceFile(options)).version).toBe(version);+ expect(inline).toHaveBeenCalledTimes(2);+ prepare.mockRejectedValueOnce(new Error('DENIED'));+ await expect(readDeviceFile(options)).rejects.toThrow('DENIED');+ expect(inlineCache.read).toHaveBeenCalledTimes(3);+ expect(peer).not.toHaveBeenCalled();+ expect(fallback).not.toHaveBeenCalled();+ },+ );+ it('does not deliver a cache hit after cancellation or fail a read when the cache fails', async () => {+ const abort = new AbortController();+ const result = { ossKey: '', size: 3, mimeType: 'text/plain', version: 'a'.repeat(64), inlineBase64: 'YWJj' };+ const inline = vi.fn(async () => result);+ const options = {+ prepare: async () => ({ ...result, inlineBase64: undefined, transferRequired: true }),+ inline, peer: vi.fn(), fallback: vi.fn(), signal: abort.signal,+ inlineCache: { read: vi.fn(async () => { abort.abort(); return result; }), store: vi.fn() },+ };+ await expect(readDeviceFile(options)).rejects.toThrow('FILE_PEER_CANCELLED');+ expect(inline).not.toHaveBeenCalled();+ options.inlineCache.read.mockRejectedValueOnce(new Error('disk unavailable'));+ options.inlineCache.store.mockRejectedValueOnce(new Error('disk full'));+ expect(await readDeviceFile({ ...options, signal: undefined })).toBe(result);+ });it.each(["audio/mpeg", "video/mp4", "image/png", "application/pdf", "application/octet-stream"])("keeps retained %s previews on OSS but full-file reads on peer", async (mimeType) => {const prepared = { ...metadata, mimeType };const peer = vi.fn(async () => ({ ...prepared, transferRequired: false }));diff --git a/packages/device-link/src/fileAccess.ts b/packages/device-link/src/fileAccess.tsindex 96b3626c9b..8b88d64aa8 100644--- a/packages/device-link/src/fileAccess.ts+++ b/packages/device-link/src/fileAccess.ts@@ -1,5 +1,8 @@+import { validFileVersion } from './fileTransferPolicy';+/** Shared file read policy. UI entry points never choose a transport. */export const FILE_INLINE_MAX_BYTES = 64 * 1024;+const revalidatingFiles = new Map<string, Promise<void>>();export interface DeviceFileResult {ossKey: string;@@ -21,6 +24,22 @@ export async function readDeviceFile<T extends DeviceFileResult>(options: {prepare(): Promise<DeviceFileResult>;peer(metadata: DeviceFileResult): Promise<T | null>;fallback(): Promise<DeviceFileResult>;+ /** Metadata-only preparation is opt-in; old hosts may still return bytes. */+ inline?(): Promise<DeviceFileResult>;+ /** Recheck the source after two-stage export before retaining a reusable copy. */+ revalidate?(): Promise<DeviceFileResult>;+ /** Small files share the platform's versioned disk store with peer downloads. */+ inlineCache?: {+ read(metadata: DeviceFileResult): Promise<DeviceFileResult | null>;+ store(result: DeviceFileResult): Promise<void>;+ };+ /** Same-owner local bytes may render before the host responds. Explicit refresh omits this. */+ cacheFirst?: {+ key: string;+ read(): Promise<DeviceFileResult | T | null>;+ /** Finish retaining a changed fallback before disposing its temporary result. */+ retain?(result: DeviceFileResult | T): Promise<void>;+ };/** Retained preview/playback URL, rather than an immediate complete-file copy. */stream?: boolean;/** Adapter returns expiring staging URLs without copying them into consumer-owned storage. */@@ -42,9 +61,47 @@ export async function readDeviceFile<T extends DeviceFileResult>(options: {}};assertActive();- const prepared = await options.prepare();+ if (options.cacheFirst) {+ const cached = await options.cacheFirst.read().catch(() => null);+ if (!active()) return discardCancelled(cached ?? { ossKey: '', size: 0, mimeType: '' });+ if (cached) {+ const { key, retain } = options.cacheFirst;+ if (!revalidatingFiles.has(key)) {+ const refresh = Promise.resolve().then(async () => {+ assertActive();+ const metadata = await options.prepare();+ if (!active()) return discardCancelled(metadata);+ if (validFileVersion(cached.version) && metadata.version === cached.version && metadata.size === cached.size) {+ if (metadata.ossKey) await options.discard?.(metadata);+ return;+ }+ const fresh = await readDeviceFile({ ...options, cacheFirst: undefined, prepare: async () => metadata });+ try { await retain?.(fresh); }+ finally { await options.discard?.(fresh); }+ }).catch(() => { /* Background failure must not replace an already usable preview. */ })+ .finally(() => { if (revalidatingFiles.get(key) === refresh) revalidatingFiles.delete(key); });+ revalidatingFiles.set(key, refresh);+ }+ return cached;+ }+ }+ let prepared = await options.prepare();if (!active()) return discardCancelled(prepared);- const mediaStream = options.stream && /^(audio|video)\//i.test(prepared.mimeType);+ const isMediaStream = (file: DeviceFileResult) => options.stream && /^(audio|video)\//i.test(file.mimeType);+ if (!isMediaStream(prepared) && validFileVersion(prepared.version) && prepared.size <= FILE_INLINE_MAX_BYTES) {+ if (prepared.transferRequired === true && options.inline) {+ const cached = await options.inlineCache?.read(prepared).catch(() => null);+ if (!active()) return discardCancelled(cached ?? prepared);+ if (cached) return cached;+ prepared = await options.inline();+ if (!active()) return discardCancelled(prepared);+ }+ if (typeof prepared.inlineBase64 === 'string') {+ await options.inlineCache?.store(prepared).catch(() => undefined);+ if (!active()) return discardCancelled(prepared);+ }+ }+ const mediaStream = isMediaStream(prepared);// Small audio/video files arrive inline too, but playback still needs a retained// URL. Reuse the streaming path without re-uploading an old host's OSS result.const inlineMediaStream = mediaStream && !prepared.ossKey &&@@ -57,6 +114,14 @@ export async function readDeviceFile<T extends DeviceFileResult>(options: {if (direct) return direct;const result = await options.fallback();if (!active()) return discardCancelled(result);+ if (!mediaStream && !result.version && validFileVersion(prepared.version) && options.revalidate) {+ let after: DeviceFileResult;+ try { after = await options.revalidate(); }+ catch (error) { await options.discard?.(result); throw error; }+ if (!active()) return discardCancelled(result);+ if (after.version === prepared.version && after.size === prepared.size && result.size === prepared.size)+ return { ...result, version: prepared.version, mimeType: prepared.mimeType };+ }return result;}