@walkhi/code-relax 0.1.0-beta.1 → 0.1.0-beta.100

package/dist/src/dots-task-catalog.mjs

@@ -0,0 +1,433 @@
+import WebSocket from 'ws';
+import { HostedHistoryAppServer } from './hosted-history-app-server.mjs';
+import { createDotsAvatarReader } from './dots-avatar.mjs';
+import { readDotsCatalog } from './dots-profile.mjs';
+import { DotsRoomClient } from './dots-room-client.mjs';
+import { uploadTaskFiles, taskFilePrompt } from './dots-task-files.mjs';
+
+const hostedAppServerUrl = 'wss://codex-cloud-backend.chatgpt.com/';
+export const dotsTaskRevision = turn => turn ? JSON.stringify([turn.id, turn.status]) : '';
+
+// Dots delegated tasks live in Desktop's durable host. Reuse the app-server
+// protocol client; only the authenticated transport differs from the local host.
+export class DotsAppServer extends HostedHistoryAppServer {
+  constructor(localServer, readProfiles = async () => new Map(), historyCache = null, { uploadsRoot } = {}) {
+    super(localServer.url, historyCache);
+    this.historySource = 'aeon_child';
+    this.localServer = localServer;
+    this.uploadsRoot = uploadsRoot;
+    this.filesClient = new DotsRoomClient(this);
+    this.url = hostedAppServerUrl;
+    this.threadSources = new Map();
+    this.catalogWatches = new Map();
+    this.readProfiles = readProfiles;
+    this.readAvatar = createDotsAvatarReader(localServer);
+    this.profileNames = new Map();
+    this.liveProfiles = new Map();
+    this.liveRoots = new Map();
+    this.rootIdentity = null;
+    this.catalogPages = new Map();
+    this.profileRefresh = null;
+    this.profileAttemptAt = 0;
+    this.on('turn', ({ thread }) => {
+      thread.chatRevision = dotsTaskRevision(thread.turns.at(-1));
+      this.saveHistoryWindow(thread.id);
+    });
+    this.on('disconnected', () => {
+      this.filesClient.close();
+      this.profileIdentity = null;
+      this.catalogPages.clear(); this.profileRefresh = null; this.profileAttemptAt = 0;
+      this.catalogWatches.clear();
+    });
+  }
+
+  get historyIdentity() { return this.profileIdentity; }
+
+  async connect() {
+    if (this.resetting) await this.resetting;
+    if (this.connecting) return this.connecting;
+    return super.connect();
+  }
+
+  async open() {
+    await super.open();
+    const socket = this.socket, identity = this.profileIdentity;
+    // Load confirmed display metadata before chat snapshots can publish a name
+    // or avatar. This reads local state, not the slow live profile request.
+    await this.refreshProfiles().catch(error => this.emit('profile-error', error));
+    if (!this.ready || this.socket !== socket || this.profileIdentity !== identity) throw new Error('点点连接已变化，请重新连接。');
+    this.emit('connected');
+  }
+
+  setProfileIdentity(identity) {
+    const key = JSON.stringify([identity.accountId, identity.userId]);
+    if (this.rootIdentity !== key) {
+      this.liveRoots.clear(); this.profileNames.clear(); this.liveProfiles.clear();
+    }
+    this.profileIdentity = identity; this.rootIdentity = key;
+  }
+
+  async openSocket() {
+    await this.localServer.connect();
+    const auth = await this.localServer.request('getAuthStatus', { includeToken: true, refreshToken: false });
+    if (!['chatgpt', 'chatgptAuthTokens'].includes(auth.authMethod) || !auth.authToken) {
+      throw new Error('读取 Dots 任务需要 Codex 内核已登录 ChatGPT。');
+    }
+    const identity = JSON.parse(Buffer.from(auth.authToken.split('.')[1], 'base64url').toString('utf8'));
+    const accountId = identity['https://api.openai.com/auth']?.chatgpt_account_id;
+    if (!accountId) throw new Error('Codex 内核没有可用于读取 Dots 任务的 ChatGPT 账号身份。');
+    this.setProfileIdentity({ accountId, userId: identity['https://api.openai.com/auth']?.chatgpt_user_id });
+    // Credentials stay in this process and go only to the fixed official host.
+    return new WebSocket(hostedAppServerUrl,
+      ['codex-app-server', 'codex-client.desktop', `openai-bearer.${auth.authToken}`], {
+        headers: { 'ChatGPT-Account-Id': accountId, 'X-OpenAI-Product-Sku': 'codex' },
+        handshakeTimeout: 15000,
+      });
+  }
+
+  request(method, params, transform = value => value) {
+    return this.nativeRequest(method, params, value => {
+      if (method === 'thread/read' || method === 'thread/resume') {
+        if (value.thread.threadSource !== 'aeon_child') throw new Error('该会话不是 Dots 委派任务。');
+        value.thread = { ...value.thread, hostId: 'durable', cwd: dotsTaskCwd(value.thread) };
+        if (method === 'thread/resume') value.cwd = value.thread.cwd;
+      }
+      return transform(value);
+    });
+  }
+
+  nativeRequest(method, params, transform) {
+    const socket = this.socket;
+    return super.request(method, params, transform).catch(error => {
+      if (error.code === 'app_server_request_timeout' && !error.deliveryResult && this.ready && this.socket === socket && !this.resetting) {
+        // An OPEN hosted socket can stop answering RPCs while still delivering
+        // notifications. Invalidate it once; reconnect through the existing
+        // observer lifecycle, never replay the request whose outcome is unknown.
+        this.ready = false;
+        const resetting = new Promise(resolve => socket.once('close', resolve)).finally(() => {
+          if (this.resetting === resetting) this.resetting = null;
+        });
+        this.resetting = resetting;
+        console.warn(JSON.stringify({ time: new Date().toISOString(), event: 'dots-connection-reset',
+          reason: error.code, method, threadId: params?.threadId }));
+        socket.terminate();
+      }
+      throw error;
+    });
+  }
+
+  watchCatalogTask(threadId) {
+    return this.watchExecution(threadId, 'aeon_child');
+  }
+
+  watchExecution(threadId, expectedSource) {
+    const current = this.catalogWatches.get(threadId);
+    if (current) return current;
+    // Hosted thread/list does not subscribe to task notifications. Resume only
+    // metadata, with no settings overrides or history window, to register a watch.
+    // A slow background watch does not prove the shared socket has stalled.
+    // Keep foreground history/streams alive; this read reports its own failure.
+    const work = super.request('thread/resume', { threadId, excludeTurns: true }).then(result => {
+      if (result.thread.threadSource !== expectedSource) throw new Error('执行订阅返回了不同来源的对话。');
+    }).catch(error => {
+      if (this.catalogWatches.get(threadId) === work) this.catalogWatches.delete(threadId);
+      throw error;
+    });
+    this.catalogWatches.set(threadId, work);
+    return work;
+  }
+
+  async latestTaskState(threadId, refresh = false) {
+    const record = this.threads.get(threadId);
+    const epoch = this.epoch, sequence = record?.sequence;
+    let turn;
+    if (!refresh && record && !record.needsReload && !record.hydrating && !record.historyTrimmed) {
+      turn = record.thread.turns.at(-1);
+    } else {
+      const page = await this.initialTurnsPage(threadId);
+      if (epoch !== this.epoch) throw new Error('云端连接已变化，请重新核对任务状态。');
+      const current = this.threads.get(threadId);
+      // Live events received during the metadata read outrank its older result.
+      turn = current && current.sequence !== sequence ? current.thread.turns.at(-1) : page.data[0];
+      if (current && !current.hydrating && dotsTaskRevision(current.thread.turns.at(-1)) !== dotsTaskRevision(turn)) {
+        current.needsReload = true;
+      }
+    }
+    return { chatRevision: dotsTaskRevision(turn), lastTurnStatus: turn?.status || null };
+  }
+
+  async timeline(threadId, pageOptions = {}, knownSync) {
+    const result = await super.timeline(threadId, { ...pageOptions, maxTurns: 1 }, knownSync);
+    result.thread.chatRevision = dotsTaskRevision(this.threads.get(threadId)?.thread.turns.at(-1));
+    await this.saveHistoryWindow(threadId, true);
+    return result;
+  }
+
+  async source(threadId, expected) {
+    let source = this.threadSources.get(threadId);
+    if (!source) {
+      await this.connect();
+      const { thread } = await this.nativeRequest('thread/read', { threadId, includeTurns: false });
+      source = thread.threadSource; this.threadSources.set(threadId, source);
+    }
+    if (!['aeon', 'aeon_child'].includes(source) || expected && source !== expected) throw new Error('该会话不是对应的 Dots 对话。');
+    return source;
+  }
+
+  notification(method, params) {
+    if (['thread/started', 'thread/archived', 'thread/unarchived', 'thread/deleted',
+      'thread/name/updated', 'thread/status/changed', 'thread/project/updated', 'turn/started', 'turn/completed'].includes(method)) {
+      this.catalogPages.clear();
+    }
+    if (this.threadSources.get(params.threadId) === 'aeon') this.serverRequests.notification(method, params);
+    if (params.thread?.threadSource) this.threadSources.set(params.thread.id, params.thread.threadSource);
+    this.emit('host-notification', { method, params });
+    if (this.threadSources.get(params.threadId || params.thread?.id) !== 'aeon') {
+      this.invalidateHistory(method, params);
+      super.notification(method, params);
+    }
+  }
+
+  async unsubscribeThread() {
+    // Page interest is local; the hosted watch/window last until socket disconnect.
+    // Do not turn page closure into thread/stop or another execution command.
+  }
+
+  keepThreadLoaded(_threadId, record) {
+    // Hosted watches last for the socket, independently of phone snapshot tokens.
+    return this.ready && Boolean(record && !record.readOnly);
+  }
+
+  isThreadObserved(threadId, record) { return this.keepThreadLoaded(threadId, record); }
+
+  async resumeTimeline(threadId, apply, options = {}) {
+    // The hosted protocol loads history separately. Register the resumed thread
+    // before requesting its page so notifications can update the hydrating record.
+    const scope = this.historyScope(threadId), head = options.reconcileObserved ? null : await this.restoreHistoryHead(threadId);
+    return this.request('thread/resume', { threadId, excludeTurns: true }, value => {
+      if (scope !== this.historyScope(threadId)) throw new Error('云端账号连接已变化，请重新读取历史。');
+      this.diskHeads.set(threadId, { head, updatedAt: value.thread.updatedAt, scope });
+      return apply({ ...value, initialTurnsPage: { data: [], nextCursor: null } });
+    });
+  }
+
+  async history(threadId, cursor, options = {}) {
+    await this.connect(); await this.source(threadId, 'aeon_child');
+    return super.history(threadId, cursor, options);
+  }
+
+  initialTurnsPage(threadId) {
+    return this.request('thread/turns/list', {
+      threadId, limit: 1, sortDirection: 'desc', itemsView: 'notLoaded',
+    });
+  }
+
+  async models() {
+    await this.connect();
+    const models = []; let cursor;
+    do {
+      const result = await this.request('model/list', { limit: 100, ...(cursor ? { cursor } : {}) });
+      models.push(...result.data); cursor = result.nextCursor;
+    } while (cursor);
+    // Hosted app-server has model/list but no local config/read.
+    return { models: models.filter(model => !model.hidden), enabledReasoningEfforts: null };
+  }
+
+  async readContext(threadId, refreshSettings = false) {
+    if (refreshSettings) {
+      await this.connect();
+      const previous = this.settingsNotifications.get(threadId);
+      // Hosted thread/read can report stored defaults even after a turn override.
+      // Resume without overrides reads the live settings, as Desktop does.
+      const settings = await this.request('thread/resume', { threadId, excludeTurns: true });
+      if (settings.model && this.settingsNotifications.get(threadId) === previous) {
+        this.contexts.set(threadId, { ...this.contexts.get(threadId), model: settings.model,
+          thinking: settings.reasoningEffort, serviceTier: settings.serviceTier ?? null });
+      }
+    }
+    return this.context(threadId);
+  }
+
+  async send(args) {
+    const { uploadFiles = [], ...turnArgs } = args;
+    let assertCurrent;
+    try {
+      await this.connect();
+      const record = this.threads.get(args.threadId);
+      if (!record || record.needsReload) await this.timeline(args.threadId);
+      if (uploadFiles.length) {
+        this.requireWritable(args.threadId);
+        const epoch = this.epoch, identity = this.profileIdentity;
+        const current = () => {
+          if (epoch !== this.epoch || identity !== this.profileIdentity || !this.ready) throw new Error('云端连接已变化，请核对后发送。');
+        };
+        assertCurrent = current;
+        const references = await uploadTaskFiles(uploadFiles, { uploadsRoot: this.uploadsRoot, client: this.filesClient, current });
+        current();
+        const text = turnArgs.input.filter(item => item.type === 'text').map(item => item.text).join('\n');
+        turnArgs.input = [{ type: 'text', text: taskFilePrompt(text, references) }, ...turnArgs.input.filter(item => item.type !== 'text')];
+      }
+    } catch (error) { error.deliveryUnknown = false; throw error; }
+    return super.send(turnArgs, { assertCurrent, useGlobalPermissions: false });
+  }
+
+  async interrupt(threadId) {
+    await this.connect();
+    this.requireWritable(threadId);
+    const result = await this.request('thread/stop', { threadId });
+    const record = this.threads.get(threadId);
+    if (record) record.needsReload = true;
+    return result;
+  }
+
+  async taskCatalog(archived = false, refresh = false) {
+    await this.connect();
+    const cached = this.catalogPages.get(archived);
+    if (cached?.work) return cached.work;
+    if (!refresh && cached?.tasks && Date.now() - cached.at < 30000) return cached.tasks;
+    const identity = this.profileIdentity;
+    const entry = {};
+    const work = this.readTaskCatalog(archived).then(tasks => {
+      if (identity !== this.profileIdentity) throw new Error('点点账号已变化，请重新读取目录。');
+      entry.tasks = tasks; entry.at = Date.now();
+      return tasks;
+    }).finally(() => { entry.work = null; });
+    entry.work = work;
+    this.catalogPages.set(archived, entry);
+    return work;
+  }
+
+  async readTaskCatalog(archived) {
+    const tasks = [];
+    let cursor;
+    do {
+      const page = await this.request('thread/list', {
+        // Hosted recency_at can omit existing delegated threads with no cursor.
+        // Fetch by updated_at; the merged catalog still uses each thread's recency.
+        limit: 100, sortKey: 'updated_at', sortDirection: 'desc', archived,
+        ...(cursor ? { cursor } : {}),
+      });
+      for (const thread of page.data) this.threadSources.set(thread.id, thread.threadSource);
+      tasks.push(...page.data.filter(thread => ['aeon', 'aeon_child'].includes(thread.threadSource))
+        .map(thread => ({ ...thread, cwd: dotsTaskCwd(thread) })));
+      cursor = page.nextCursor;
+    } while (cursor);
+    return tasks;
+  }
+
+  async catalog(archived = false, refresh = false) {
+    const tasks = await this.taskCatalog(archived, refresh);
+    await this.refreshProfiles();
+    this.refreshLiveProfiles();
+    // Subscription failure must not discard an authoritative catalog snapshot.
+    // Watches continue independently; failed watches are retried by the next catalog read.
+    if (!archived) for (const thread of tasks.filter(thread => thread.threadSource === 'aeon_child')) {
+      void this.watchCatalogTask(thread.id).catch(error => {
+        console.error('Dots 任务订阅失败：', thread.id, error.message);
+      });
+    }
+    return [...tasks.filter(thread => thread.threadSource === 'aeon_child'),
+      ...(archived ? [] : this.liveRoots.values())].map(thread => thread.threadSource === 'aeon' ? { ...thread,
+      name: this.profileName(thread.id), avatar: this.profileAvatar(thread.id), color: this.profileColor(thread.id) } : thread);
+  }
+
+  async tasks(archived = false) { return (await this.taskCatalog(archived)).filter(thread => thread.threadSource === 'aeon_child'); }
+
+  async refreshProfiles() {
+    const identity = this.profileIdentity;
+    const names = identity ? await this.readProfiles(identity) : new Map();
+    if (identity !== this.profileIdentity) throw new Error('点点账号已变化，请重新读取目录。');
+    const byProfile = new Map([...this.liveProfiles.values()].map(profile => [profile.profileId, profile]));
+    for (const [id, profile] of names) {
+      if (byProfile.has(profile.profileId)) names.set(id, byProfile.get(profile.profileId));
+    }
+    for (const [id, profile] of this.liveProfiles) names.set(id, byProfile.get(profile.profileId));
+    for (const [id, profile] of names) {
+      const previous = this.profileNames.get(id);
+      if (previous?.avatar && previous.avatarFileId === profile.avatarFileId) profile.avatar = previous.avatar;
+    }
+    if (identity === this.profileIdentity) {
+      this.profileNames = names;
+      this.emit('profiles-changed');
+    }
+  }
+
+  refreshLiveProfiles() {
+    if (this.profileRefresh || Date.now() - this.profileAttemptAt < 60000) return;
+    const identity = this.profileIdentity;
+    this.profileAttemptAt = Date.now();
+    const snapshot = () => JSON.stringify([[...this.profileNames], [...this.liveRoots]]);
+    let published = snapshot();
+    const publish = () => {
+      const next = snapshot();
+      if (identity !== this.profileIdentity || published === next) return;
+      published = next;
+      this.emit('notification', { method: 'thread/name/updated', params: {} });
+    };
+    const work = (async () => {
+      try {
+        const { profiles: live, rootThreadIds } = await readDotsCatalog(this.localServer, identity);
+        if (identity !== this.profileIdentity) return;
+        const roots = new Map();
+        for (const threadId of rootThreadIds) {
+          const { thread } = await this.nativeRequest('thread/read', { threadId, includeTurns: false });
+          if (identity !== this.profileIdentity) return;
+          if (thread.id !== threadId || thread.threadSource !== 'aeon') throw new Error('点点目录返回了非主线程。');
+          roots.set(threadId, { ...thread, cwd: dotsTaskCwd(thread) });
+        }
+        if (identity !== this.profileIdentity) return;
+        this.liveProfiles = live;
+        this.liveRoots = roots;
+        for (const id of roots.keys()) this.threadSources.set(id, 'aeon');
+        await this.refreshProfiles();
+        publish();
+      } catch (error) {
+        if (identity !== this.profileIdentity) return;
+        this.emit('profile-error', error);
+      }
+      await Promise.all([...new Set(this.profileNames.values())].map(async profile => {
+        try { profile.avatar = await this.readAvatar(profile, identity); }
+        catch (error) { this.emit('profile-error', error); }
+      }));
+      publish();
+      if (identity === this.profileIdentity && this.liveProfiles.size) await this.readProfiles.save?.(identity, this.liveProfiles);
+    })().catch(error => this.emit('profile-error', error))
+      .finally(() => { if (this.profileRefresh === work) this.profileRefresh = null; });
+    this.profileRefresh = work;
+  }
+
+  profileName(threadId) { return this.profileNames.get(threadId)?.name || 'Dots'; }
+  profileAvatar(threadId) { return this.profileNames.get(threadId)?.avatar || ''; }
+  profileColor(threadId) { return this.profileNames.get(threadId)?.color || ''; }
+}
+
+function dotsTaskCwd(thread) {
+  return thread.environments?.[0]?.cwd || thread.cwd;
+}
+
+export async function readDotsTasks(localAppServerUrl) {
+  const local = new SharedAppServer(localAppServerUrl);
+  const cloud = new DotsAppServer(local);
+  try {
+    const tasks = await cloud.tasks();
+    const summaries = await Promise.all(tasks.map(async thread => {
+      const turns = await cloud.request('thread/turns/list', {
+        threadId: thread.id, limit: 1, sortDirection: 'desc', itemsView: 'notLoaded',
+      });
+      const latest = turns.data[0];
+      return {
+        id: thread.id, hostId: 'durable', threadSource: thread.threadSource,
+        title: thread.name || thread.preview || '', model: thread.model,
+        cwd: thread.environments?.[0]?.cwd || thread.cwd,
+        environments: thread.environments, createdAt: thread.createdAt, updatedAt: thread.updatedAt,
+        recencyAt: thread.recencyAt ?? thread.updatedAt, status: thread.status?.type,
+        latestTurn: latest ? { id: latest.id, status: latest.status,
+          startedAt: latest.startedAt, completedAt: latest.completedAt, error: latest.error } : null,
+      };
+    }));
+    return { source: 'codex-cloud-app-server', readAt: new Date().toISOString(), tasks: summaries };
+  } finally {
+    cloud.close();
+    local.close();
+  }
+}

package/dist/src/dots-task-files.mjs

@@ -0,0 +1,52 @@
+import { randomUUID } from 'node:crypto';
+import { readMessageUploads } from './message-upload-files.mjs';
+
+// Desktop 26.1007.9446.0 Dll/Uhn/pA: reserve, upload bytes, confirm,
+// then include an Uploaded file sediment pointer in the user message.
+export async function uploadTaskFiles(files, { uploadsRoot, client, current, fetchImpl = fetch }) {
+  const uploads = await readMessageUploads({ files }, uploadsRoot);
+  const references = [];
+  for (const file of uploads) {
+    current();
+    const reserved = await client.request('/files', { method: 'POST', body: {
+      file_name: file.name, file_size: file.bytes.size ?? file.bytes.length, mime_type: file.mimeType,
+      use_case: 'codex', store_in_library: false, timezone_offset_min: new Date().getTimezoneOffset(), reset_rate_limits: false,
+    } });
+    current();
+    if (reserved?.status === 'error' || !/^[A-Za-z0-9_-]{1,256}$/.test(reserved?.file_id || '')
+      || typeof reserved.upload_url !== 'string') throw new Error('云端文件上传地址未确认。');
+    const url = new URL(reserved.upload_url, 'https://chatgpt.com');
+    if (url.protocol !== 'https:' || url.username || url.password || url.port || url.hash) throw new Error('云端文件上传地址无效。');
+    if (url.origin === 'https://chatgpt.com' && url.pathname === '/backend-api/estuary/upload_content_bytes') {
+      const uploadUrl = url.searchParams.get('upload_url');
+      if (!uploadUrl) throw new Error('云端文件上传地址缺少参数。');
+      const boundary = `relax-${randomUUID()}`;
+      const name = file.name.replaceAll('"', '%22').replaceAll('\\', '%5C');
+      const body = new Blob([Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${name}"\r\nContent-Type: ${file.mimeType}\r\n\r\n`),
+        file.bytes, Buffer.from(`\r\n--${boundary}\r\nContent-Disposition: form-data; name="upload_url"\r\n\r\n${uploadUrl}\r\n--${boundary}--\r\n`)]);
+      await client.request(url.pathname.slice('/backend-api'.length) + url.search, {
+        method: 'POST', body, contentType: `multipart/form-data; boundary=${boundary}`, rawResponse: true,
+      });
+    } else {
+      if (!['.oaiusercontent.com', '.blob.core.windows.net', '.amazonaws.com'].some(suffix => url.hostname.endsWith(suffix))) {
+        throw new Error('云端文件上传地址不属于文件服务。');
+      }
+      const aws = [...url.searchParams.keys()].some(key => key.toLowerCase() === 'x-amz-algorithm');
+      const response = await fetchImpl(url, { method: 'PUT', body: file.bytes, redirect: 'error', signal: AbortSignal.timeout(60000),
+        headers: { 'Content-Type': file.mimeType, ...aws ? {} : { 'x-ms-blob-type': 'BlockBlob',
+          'x-ms-version': '2020-04-08', 'x-ms-blob-content-type': file.mimeType } } });
+      await response.body?.cancel();
+      if (!response.ok) throw new Error(`云端文件上传失败（${response.status}）。`);
+    }
+    current();
+    await client.request(`/files/${encodeURIComponent(reserved.file_id)}/uploaded`, { method: 'POST', body: {} });
+    current();
+    references.push({ pointer: `sediment://${reserved.file_id}`, fileName: file.name });
+  }
+  return references;
+}
+
+export function taskFilePrompt(text, references) {
+  if (!references.length) return text;
+  return `# Files mentioned by the user:\n${references.map(file => `\nUploaded file: ${JSON.stringify(file).replaceAll('#', '\\u0023')}\n`).join('')}\n## My request:\n${text || '请查看上述文件。'}`;
+}

package/dist/src/file-transfer-range.mjs

@@ -0,0 +1,22 @@
+export const FILE_READ_LIMIT = 20 * 1024 * 1024;
+export const FILE_PART_BYTES = 256 * 1024;
+export class FileRangeError extends Error {
+  constructor(statusCode, message) { super(message); this.statusCode = statusCode; }
+}
+
+export function fileRange(query, size, revision) {
+  const offset = Number(query.get('offset') || 0);
+  const length = Number(query.get('length') || FILE_PART_BYTES);
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset >= size ||
+      !Number.isSafeInteger(length) || length < 1 || length > FILE_PART_BYTES) {
+    throw new FileRangeError(400, '无效的文件读取范围。');
+  }
+  if ((offset && !query.get('revision')) || (query.has('revision') && query.get('revision') !== revision)) {
+    throw new FileRangeError(409, '文件已变化，请重新打开。');
+  }
+  return { offset, length: Math.min(length, size - offset) };
+}
+
+export function fileRevision(stat) {
+  return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+}

package/dist/src/file-upload-session.mjs

@@ -0,0 +1,151 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const MAX_FILE_BYTES = 20 * 1024 * 1024;
+export const MAX_FILE_COUNT = 4;
+export const MAX_TOTAL_BYTES = 40 * 1024 * 1024;
+export const FILE_CHUNK_BYTES = 256 * 1024;
+
+function validName(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 180 &&
+    value !== '.' && value !== '..' && !/[\\/:*?"<>|\x00-\x1f]/.test(value) && !/[. ]$/.test(value) &&
+    !/^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/i.test(value);
+}
+
+async function uniqueDestination(directory, name, partial) {
+  const dot = name.lastIndexOf('.');
+  const stem = dot > 0 ? name.slice(0, dot) : name;
+  const extension = dot > 0 ? name.slice(dot) : '';
+  for (let index = 0; ; index++) {
+    const suffix = index ? ` (${index})` : '';
+    const candidate = index ? `${stem.slice(0, 180 - extension.length - suffix.length)}${suffix}${extension}` : name;
+    if (!candidate || candidate.length > 180) throw new Error('同名文件过多，文件名无法继续编号');
+    const destination = path.join(directory, candidate);
+    try {
+      await fs.link(partial, destination);
+      await fs.unlink(partial);
+      return { name: candidate, path: destination };
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+    }
+  }
+}
+
+export function createFileUploadSession(root) {
+  let upload;
+  let committed = false;
+  const files = new Map();
+  const completed = new Map();
+  let completedBytes = 0;
+  const directory = path.join(root, 'incoming');
+  const clearActive = async () => {
+    const current = upload;
+    upload = undefined;
+    if (!current) return;
+    await current.handle.close().catch(() => {});
+    await fs.unlink(current.partial).catch(() => {});
+  };
+  const clear = async () => {
+    await clearActive();
+    if (committed) return;
+    for (const file of completed.values()) {
+      await fs.unlink(file.path).catch(() => {});
+      if (file.preview) await fs.unlink(file.preview.path).catch(() => {});
+    }
+    completed.clear(); files.clear(); completedBytes = 0;
+  };
+  return {
+    async receive(message, { relayed = false } = {}) {
+      if (!message || typeof message !== 'object') throw new Error('无效的文件上传请求');
+      if (message.type === 'cancel') { await clear(); return { type: 'cancelled' }; }
+      // Recheck the complete batch on every relayed request, including resume
+      // and commit after a direct connection has been replaced.
+      if (relayed) {
+        const originals = [...files.values()].filter(file => !file.previewOf);
+        if (originals.some(file => file.size > MAX_FILE_BYTES)) throw new Error('服务器转发仅支持单个文件不超过 20 MiB，请使用局域网或 RTC 直连');
+        if (originals.reduce((sum, file) => sum + file.size, 0) > MAX_TOTAL_BYTES) throw new Error('服务器转发仅支持每批合计不超过 40 MiB，请使用局域网或 RTC 直连');
+      }
+      if (message.type === 'commit') {
+        if (upload) throw new Error('文件尚未上传完成');
+        committed = true;
+        return { type: 'committed' };
+      }
+      if (message.type === 'remove') {
+        if (committed) throw new Error('文件批次已提交');
+        if (upload) throw new Error('请等待当前文件上传完成');
+        const file = completed.get(message.id);
+        if (!file) throw new Error('文件上传会话已失效');
+        await fs.unlink(file.path);
+        if (file.preview) await fs.unlink(file.preview.path);
+        completed.delete(message.id); completedBytes -= file.size;
+        for (const [key, value] of files) if (value.id === message.id || value.previewOf === message.id) files.delete(key);
+        return { type: 'removed', id: message.id };
+      }
+      if (message.type === 'start') {
+        if (typeof message.fileKey !== 'string' || !/^[0-9]+(?:-preview)?$/.test(message.fileKey)) throw new Error('文件批次编号无效');
+        const previous = files.get(message.fileKey);
+        if (previous) {
+          if (previous.originalName !== message.name || previous.size !== message.size ||
+              previous.previewOf !== message.previewOf) throw new Error('续传文件身份不一致');
+          return previous.result || { type: 'started', id: previous.id, offset: previous.offset, chunkBytes: FILE_CHUNK_BYTES };
+        }
+        if (committed) throw new Error('文件批次已提交');
+        if (upload) throw new Error('已有文件正在上传');
+        if (!validName(message.name)) throw new Error('文件名无效');
+        if (!Number.isSafeInteger(message.size) || message.size < 1) {
+          throw new Error('文件大小无效');
+        }
+        if (relayed && message.size > MAX_FILE_BYTES) throw new Error('服务器转发仅支持单个文件不超过 20 MiB，请使用局域网或 RTC 直连');
+        const parent = message.previewOf ? completed.get(message.previewOf) : null;
+        if (message.previewOf && (!parent || parent.preview || message.size > FILE_CHUNK_BYTES)) throw new Error('预览图关联无效或超过 256 KiB');
+        if (!parent && completed.size >= MAX_FILE_COUNT) throw new Error('每条消息最多 4 个文件');
+        if (!parent && relayed && completedBytes + message.size > MAX_TOTAL_BYTES) throw new Error('服务器转发仅支持每批合计不超过 40 MiB，请使用局域网或 RTC 直连');
+        const id = crypto.randomUUID();
+        await fs.mkdir(directory, { recursive: true });
+        const partial = path.join(directory, `.upload-${id}`);
+        const handle = await fs.open(partial, 'wx');
+        upload = { id, partial, handle, name: parent ? `${id}.preview.jpg` : message.name, size: message.size, parent,
+          originalName: message.name, previewOf: message.previewOf,
+          offset: 0 };
+        files.set(message.fileKey, upload);
+        return { type: 'started', id, offset: 0, chunkBytes: FILE_CHUNK_BYTES };
+      }
+      const current = upload;
+      if (!current || message.id !== current.id) throw new Error('文件上传会话已失效');
+      if (message.type === 'chunk') {
+        if (!Number.isSafeInteger(message.offset) || message.offset !== current.offset) {
+          return { type: 'offset', id: current.id, offset: current.offset };
+        }
+        if (!Buffer.isBuffer(message.data)) {
+          throw new Error('文件分片格式无效');
+        }
+        const bytes = message.data;
+        if (!bytes.length || bytes.length > FILE_CHUNK_BYTES || current.offset + bytes.length > current.size) {
+          throw new Error('文件分片大小无效');
+        }
+        await current.handle.writeFile(bytes);
+        current.offset += bytes.length;
+        return { type: 'offset', id: current.id, offset: current.offset };
+      }
+      if (message.type === 'finish') {
+        if (current.offset !== current.size) {
+          await clear(); throw new Error('文件大小不一致');
+        }
+        await current.handle.sync();
+        await current.handle.close();
+        upload = undefined;
+        let saved;
+        try { saved = await uniqueDestination(directory, current.name, current.partial); }
+        catch (error) { await fs.unlink(current.partial).catch(() => {}); throw error; }
+        const result = { type: 'completed', id: current.id, ...saved, size: current.size };
+        current.result = result;
+        if (current.parent) current.parent.preview = result;
+        else { completed.set(current.id, result); completedBytes += current.size; }
+        return result;
+      }
+      throw new Error('不支持的文件上传操作');
+    },
+    close: clear,
+  };
+}