Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* mobileLocalAttachmentUpload.ts — 本机附件(图片 / 文件)乐观上传控制器
* (会话页 / 新建会话页共用)。
* ---------------------------------------------------------------------------
* 旧链路是「压缩 + presign + PUT 全部完成后附件才进托盘」,拍照 / 选大文件后要
* 盯着空托盘等数秒到十几秒。本控制器把链路改成乐观模式:
*
* - picker 一返回,附件立刻以 pending 卡(图片=本地缩略图,文件=文件名 chip)
* 进托盘;
* - 预处理(图片降采样;文件跳过)+ 上传转后台,并发上限 2(手机上行带宽是
* 瓶颈,和 remoteMediaResolveQueue 同精神),成功后由宿主把正式 attachment 入列;
* - pending 期间可被 X 掉:未开跑的直接移除;已 in-flight 的任其完成,完成后
* 经 deps.discard 回收 OSS 中转对象(上传已经发生,不回收就是孤儿);
* - 发送前 waitForIdle():等全部任务落定并返回期间失败数,宿主据此决定
* 「失败了就不发、让用户看到错误」;
* - dispose():退屏兜底,把仍在天上的任务全部标记丢弃(完成后回收)。
*
* 纯逻辑模块,依赖注入(preprocess / upload / discard / 校验),node 可单测。
*/
import { i18n } from '@/i18n';
import type { RemoteSerializedAttachment } from '@/session/types';
import type { MobileImagePreprocessInput, MobileImagePreprocessOutput } from '@/session/mobileImagePreprocess';
import type { AnnotationStroke } from '@/session/imageAnnotationModel';
export type MobileLocalAttachmentKind = 'image' | 'file';
/** picker 产出的待上传本机附件(图片的 uri 同时用作托盘即时预览)。 */
export interface MobileLocalAttachmentUploadCandidate {
kind: MobileLocalAttachmentKind;
uri: string;
name: string;
/** 发起上传的 composer 作用域(sessionId 等);仅供宿主隔离迟到异步结果。 */
attachmentScopeKey?: string;
/** Destination captured when enqueued, never read from a later active task. */
sharedTaskId?: string;
deviceId?: string;
/** 同一作用域重复进入时也会递增的代际;避免 A → B → A 后接回最早 A 的旧结果。 */
attachmentScopeGeneration?: number;
mimeType?: string;
/** 原文件字节数,0 = 未知(上传前由 statSize 兜底)。 */
size: number;
width?: number | null;
height?: number | null;
/**
* 任务真正开跑时的异步就位钩子(相册 ph:// → file:// 换址、HEIC 转码缩边等重活)。
* 返回的字段覆盖到 candidate 上再进后续管线;入队时先显示缩略图,就位后
* 立即切换预览地址,无需等待压缩和上传结束。重活全在后台。
*/
resolve?: (signal?: AbortSignal) => Promise<Partial<Pick<
MobileLocalAttachmentUploadCandidate,
'uri' | 'name' | 'mimeType' | 'size' | 'width' | 'height' | 'skipPreprocess'
>>>;
/** resolve 阶段已完成优化编码(如 HEIC 转码+缩边),跳过 preprocess 防二次有损。 */
skipPreprocess?: boolean;
/**
* 仅由明确拥有输入文件的调用方提供(当前是 WebView 粘贴落盘与 iOS Share
* Extension 复制进 App Group 的文件):
* controller 会把 resolve / preprocess 生成的同任务临时 uri 一并交回清理。
* 系统相册、相机与文件选择器的 uri 不设置此钩子,避免误删宿主管理的文件。
*/
cleanupLocalUris?: (uris: readonly string[]) => Promise<void>;
/** 宿主侧溯源 id(相册 asset.id → attachment 映射用),管线不消费。 */
sourceId?: string;
/** Source position within one external share; retained across retries. */
incomingShareOrder?: { batchId: string; index: number };
/**
* 圈点标注元数据(uri 已是烧录产物时携带;管线不消费,onUploaded 原样回传,
* 宿主据此给附件打 annotated 标并记录「矢量笔迹 + 原图」的再编辑真相)。
*/
annotation?: {
strokes: AnnotationStroke[];
sourceUri: string;
sourceMimeType: string;
/** sourceUri 本身已是带笔迹的烧录图(再编辑真相丢失后的再编辑):无新笔迹也仍是标注图。 */
baseAnnotated?: boolean;
};
/**
* 再编辑保存的替换语义:本 candidate 上传**成功后**宿主才移除该旧附件
* (管线不消费)。不能在入队时就删——上传可能因 token / 网络 / 超限失败,
* 提前删会让用户新旧两头空(review P1)。
*/
replacesAttachmentId?: string;
/**
* 任务被**确定放弃**时回调(至多一次):托盘 / outbox 移除、整体丢弃、退屏、
* 交接给持久发件箱后,或入队时作用域已失效。上传失败**不**回调——失败卡仍在
* 托盘可重试,重试会重新读取 candidate.uri。上传成功走 onUploaded,也不回调。
* 供自行生成了输入文件的调用方(标注烧录图等)按生命周期回收;管线不消费。
*/
onAbandoned?: () => void;
/** 上传已交付后释放原生选图句柄;失败仍保留,供原地重试。 */
onConsumed?: () => void;
}
/** 托盘 pending 卡的渲染数据(image → 缩略卡;file → 文件名 chip)。 */
export interface PendingLocalAttachmentUpload {
localId: string;
kind: MobileLocalAttachmentKind;
previewUri: string;
name: string;
/** 已知字节数(chip 显示「名称 · 大小」用;0 = 未知)。 */
size: number;
/** 宿主侧溯源 id(相册来源才有):面板重开时据此把上传中的资产格标 busy 禁点。 */
sourceId?: string;
/**
* 上传失败(弱网 / 超时 / token 失效):卡片保留为「失败 · 可重试」态,而不是
* 从托盘消失只留一条 toast——弱网下让用户原地重试,不用重新找图重选。
*/
failed?: boolean;
}
export interface MobileLocalAttachmentUploadDeps {
/** 图片上传前降采样(preprocessMobileImageForUpload);file 类任务不会调到。 */
preprocess(input: MobileImagePreprocessInput): Promise<MobileImagePreprocessOutput>;
/** size 未知时读本地文件字节数。 */
statSize(uri: string): Promise<number>;
/** 校验最终上传体积,超限时 throw;candidate 供按 kind 区分文案。 */
assertSize(size: number, candidate: MobileLocalAttachmentUploadCandidate): void;
/** 真正的 presign + PUT(uploadMobileAttachmentFromFile);signal 中止时应尽快断掉传输。 */
upload(
candidate: { name: string; size: number; mimeType?: string; sharedTaskId?: string; deviceId?: string },
fileUri: string,
opts: { token: string; signal?: AbortSignal },
): Promise<RemoteSerializedAttachment>;
/** 已上传但不再被引用的对象回收(discardMobileUploadedAttachment,best-effort)。 */
discard(attachment: RemoteSerializedAttachment, token?: string | null): void;
/** pending 列表变化(宿主 setState 驱动托盘;已 claim 的任务不在其中)。 */
onPendingChange(pending: readonly PendingLocalAttachmentUpload[]): void;
/**
* 单个上传成功(宿主把 attachment 入列、图片记录 previewUri 映射)。
* uploadedUri = 实际 PUT 的本地文件(降采样产物;plan 为 null / 回退时等于
* candidate.uri)——发送后气泡的本地缩略图兜底用它(比原图小一个量级)。
* localId = 任务 id,宿主用它把已 claim 任务的产物路由给对应的乐观消息。
*/
onUploaded(
attachment: RemoteSerializedAttachment,
candidate: MobileLocalAttachmentUploadCandidate,
uploadedUri: string,
localId: string,
localUris: readonly string[],
isActive: () => boolean,
): void | Promise<void>;
/** 单个失败(宿主展示错误文案);已被移除 / 丢弃的任务不会回调。localId 语义同 onUploaded。 */
onFailed(error: unknown, localId: string, candidate: MobileLocalAttachmentUploadCandidate): void;
}
export interface PreparedOutboxAttachment {
localId: string;
source: MobileLocalAttachmentUploadCandidate;
}
export interface MobileAttachmentHandoff {
prepare(): Promise<PreparedOutboxAttachment[]>;
/** Commit cancels the old PUT; its late result is discarded by this controller. */
release(commit: boolean): void;
}
export interface MobileLocalAttachmentUploadController {
beginHandoff(): MobileAttachmentHandoff;
isRetainingUri(uri: string): boolean;
waitForDelivering(): Promise<void>;
/**
* 把 picker 产出批量入队并立即出现在 pending 列表;后台按并发上限上传。
* token 允许传 Promise:调用方**不要**先 await getAccessToken() 再 enqueue——那个等待窗
* 里任务尚未入队,composer 抢发时 waitForIdle 立即返回、刚选的附件被静默丢弃(粘贴路径
* 没有 picker modal 遮挡,窗口真实可踩)。同步段就 enqueue,token 由任务开跑时自行等待。
*/
enqueue(
candidates: readonly MobileLocalAttachmentUploadCandidate[],
opts: { token: string | Promise<string | null> },
): void;
/** 托盘 X:移除一个 pending;已 in-flight 的完成后自动回收 OSS 对象。 */
remove(localId: string): void;
/**
* 重试一个失败态任务:重新入队跑完整管线(就位钩子 / 降采样 / presign / PUT)。
* token 必传新鲜值——失败可能停留了很久,旧凭证大概率已过期。非失败态任务 no-op。
*/
retry(localId: string, opts: { token: string | Promise<string | null> }): void;
/**
* 丢弃当前全部任务(语义同逐个 remove),controller 继续可用。
* 场景:新建会话页切换目标电脑——上一台电脑期间发起的在途上传不能在完成后
* 经 onUploaded 混进新电脑的草稿附件。
*/
removeAll(): void;
/** 等全部任务落定;返回等待期间(含此刻已 in-flight)的失败个数。 */
waitForIdle(): Promise<{ failedCount: number }>;
/** 当前是否还有未落定任务。 */
hasPending(): boolean;
/**
* 当前未落定(非 discarded、非 claimed)任务数——**同步真源**。附件槽位校验必须读这里
* 而不是 onPendingChange 驱动的 React state:state commit 走 macrotask,信箱
* 串行 drain 的 await 只隔 microtask,读 state 会拿到「入队前」的旧值,多条
* 投递仍可绕过 MOBILE_MAX_ATTACHMENTS(review P1)。
*/
pendingCount(): number;
/**
* 把任务划归一条已发送的乐观消息(outbox):claimed 任务离开 composer 域——
* 不再出现在 onPendingChange 托盘、不计入 pendingCount 限额、waitForIdle 不等它;
* 任务本身照跑,产物经 onUploaded/onFailed 的 localId 由宿主路由给对应消息。
* remove / retry 对 claimed 任务照常可用(outbox 条目的删除与重试复用它们)。
*/
claim(localIds: readonly string[]): void;
/**
* claim 的逆操作:任务交还 composer 域(重回托盘、重新计入限额)。
*
* 乐观消息被收回成草稿时用(创建失败把待发消息交还输入框):任务本身继续跑,
* 落定后宿主的 outbox 路由找不到归属条目,产物自然回落到托盘。取消再重传是错的
* ——用户已经等过一次上传,且粘贴来源的本地文件可能已被回收(review P1)。
*/
unclaim(localIds: readonly string[]): void;
/**
* 未 claim 且未丢弃任务的同步快照(顺序 = 入队序):发送时刻用它决定「这条消息
* 要带走哪些在途上传」。failed = 已失败结算的卡(claim 后随消息进失败态);
* kind / previewUri 供乐观消息气泡直接渲染本地缩略图(图片 = candidate.uri)。
*/
claimableTasks(): Array<{ localId: string; failed: boolean; kind: MobileLocalAttachmentKind; previewUri: string; name: string }>;
/** 退屏兜底:全部标记丢弃(不再回调 onUploaded/onFailed,完成后回收 OSS)。 */
dispose(): void;
}
const MAX_CONCURRENT_UPLOADS = 2;
/**
* iOS 模拟器没有相机:expo-image-picker 原生层不做 isSourceTypeAvailable 防护,
* 直接 `setSourceType(.camera)` 会抛 NSInvalidArgumentException 崩掉整个进程
* (实测崩栈:UIImagePickerController.setSourceType ← launchLegacyImagePicker)。
* 检测走沙盒路径:模拟器 app 的 documentDirectory 必含 `/CoreSimulator/`
* (`~/Library/Developer/CoreSimulator/Devices/...`),真机是 `/var/mobile/...`。
* 不用 expo-constants 的 platform.ios.platform——SDK 56 原生层已只返回 buildNumber,
* 该字段恒 undefined(类型声明滞后,实测踩过)。Android 模拟器有虚拟相机,不拦。
*/
export function isCameraUnavailableOnSimulator(
platformOs: string,
documentDirectory: string | null | undefined,
): boolean {
if (platformOs !== 'ios') return false;
return (documentDirectory ?? '').includes('/CoreSimulator/');
}
type TaskOutcome = 'uploaded' | 'failed' | 'discarded';
interface UploadTask {
localId: string;
candidate: MobileLocalAttachmentUploadCandidate;
/** 上传凭证;Promise 形态 = enqueue 时 token 仍在获取中,runTask 开跑时等它就位。 */
token: string | Promise<string | null>;
/** failed = 上传失败但卡片保留在托盘(可 retry / remove),任务已结算不占并发位。 */
state: 'queued' | 'running' | 'failed';
discarded: boolean;
/** 已划归乐观消息(outbox 域):离开托盘 / 限额 / waitForIdle,任务本身照跑。 */
claimed: boolean;
/** in-flight 取消通道:remove / removeAll / dispose 时 abort,真正断掉 PUT 传输。 */
abort: AbortController;
/** 本任务已接触的自有临时 uri;无 cleanupLocalUris 时只记账、不做删除。 */
localUris: Set<string>;
prepared?: Promise<MobileLocalAttachmentUploadCandidate>;
handoff?: { promise: Promise<void>; resolve(): void };
delivering?: boolean;
/** onAbandoned 已回调(保证至多一次)。 */
abandonNotified?: boolean;
resolvedSource?: MobileLocalAttachmentUploadCandidate;
outcome: Promise<TaskOutcome>;
resolveOutcome: (outcome: TaskOutcome) => void;
}
function createOutcome(): { outcome: Promise<TaskOutcome>; resolveOutcome: (outcome: TaskOutcome) => void } {
let resolveOutcome!: (outcome: TaskOutcome) => void;
const outcome = new Promise<TaskOutcome>((resolve) => {
resolveOutcome = resolve;
});
return { outcome, resolveOutcome };
}
export function createMobileLocalAttachmentUploadController(
deps: MobileLocalAttachmentUploadDeps,
): MobileLocalAttachmentUploadController {
const tasks = new Map<string, UploadTask>();
let seq = 0;
let runningCount = 0;
let disposed = false;
function notifyPending(): void {
const pending: PendingLocalAttachmentUpload[] = [];
for (const task of tasks.values()) {
if (task.discarded || task.claimed) continue;
pending.push({
localId: task.localId,
kind: task.candidate.kind,
previewUri: task.resolvedSource?.uri || task.candidate.uri,
name: task.candidate.name,
size: task.candidate.size,
sourceId: task.candidate.sourceId,
failed: task.state === 'failed' || undefined,
});
}
deps.onPendingChange(pending);
}
function pump(): void {
if (runningCount >= MAX_CONCURRENT_UPLOADS) return;
for (const task of tasks.values()) {
if (task.state !== 'queued') continue;
task.state = 'running';
runningCount += 1;
void runTask(task);
if (runningCount >= MAX_CONCURRENT_UPLOADS) return;
}
}
function notifyAbandoned(task: UploadTask): void {
if (task.abandonNotified) return;
task.abandonNotified = true;
try {
task.candidate.onAbandoned?.();
} catch {
// 调用方的回收失败不能影响管线。
}
}
function cleanupTaskLocalUris(task: UploadTask, keepOriginal: boolean): void {
if (task.handoff) {
void task.handoff.promise.then(() => cleanupTaskLocalUris(task, keepOriginal));
return;
}
// keepOriginal=false 只出现在任务被放弃的路径(remove / removeAll / dispose /
// 交接提交 / 丢弃结算);失败保留卡片走 keepOriginal=true,不算放弃。
if (!keepOriginal) notifyAbandoned(task);
if (keepOriginal) task.prepared = undefined;
const cleanup = task.candidate.cleanupLocalUris;
if (!cleanup) return;
// Failed uploads retain the picker thumbnail, but recycle resolved originals.
task.resolvedSource = undefined;
const originalUri = task.candidate.uri;
const uris = [...task.localUris].filter((uri) => !keepOriginal || uri !== originalUri);
task.localUris = keepOriginal ? new Set([originalUri]) : new Set();
if (uris.length > 0) void cleanup(uris).catch(() => undefined);
}
function prepareTaskSource(task: UploadTask): Promise<MobileLocalAttachmentUploadCandidate> {
if (task.prepared) return task.prepared;
// Preparation is shared with a durable handoff, which can run before token refresh.
// Give that owner the same bounded wait; a late result never mutates a newer retry.
let expired = false;
let preparation!: Promise<MobileLocalAttachmentUploadCandidate>;
let rejectTimeout!: (error: Error) => void;
const timeout = new Promise<never>((_resolve, reject) => { rejectTimeout = reject; });
const timer = setTimeout(() => {
expired = true;
rejectTimeout(new Error(i18n.t('composer.upload.timeout')));
}, 180_000);
const step = <T>(value: Promise<T>): Promise<T> => Promise.race([
value.then((result) => {
if (expired || task.prepared !== preparation || (task.discarded && !task.handoff)) {
const uri = (result as { uri?: string })?.uri;
if (uri && uri !== task.candidate.uri) void task.candidate.cleanupLocalUris?.([uri]).catch(() => undefined);
throw new Error(i18n.t('composer.upload.cancelled'));
}
return result;
}), timeout,
]);
preparation = (async () => {
try {
// 先跑 candidate 自带的就位钩子(相册换址 / HEIC 转码),结果覆盖进管线输入。
let source = task.candidate;
if (source.resolve) {
source = { ...source, ...(await step(source.resolve(task.abort.signal))) };
}
task.resolvedSource = source;
task.localUris.add(source.uri);
if (!disposed && !task.discarded && source.uri !== task.candidate.uri) notifyPending();
// 只有图片需要降采样;文件(pdf / office / 文本)与已优化产物原样直传。
const prepared = source.kind === 'image' && !source.skipPreprocess
? await step(deps.preprocess({
uri: source.uri,
name: source.name,
mimeType: source.mimeType,
size: source.size,
width: source.width,
height: source.height,
}))
: {
uri: source.uri,
name: source.name,
mimeType: source.mimeType,
size: source.size,
};
task.localUris.add(prepared.uri);
const size = prepared.size > 0 ? prepared.size : await step(deps.statSize(prepared.uri));
deps.assertSize(size, task.candidate);
return { ...source, ...prepared, size, resolve: undefined, skipPreprocess: true };
} finally { clearTimeout(timer); }
})();
task.prepared = preparation;
return preparation;
}
async function runTask(task: UploadTask): Promise<void> {
// 先让出一拍:保证任务至少异步落定——pending 帧可见、waitForIdle 统计口径一致,
// 同步 throw(如已知 size 的超限校验)不会在 enqueue 调用栈里就把任务清掉。
await Promise.resolve();
let outcome: TaskOutcome = 'failed';
// 覆盖 token、相册读取、预处理和上传后的缩略图落盘,不能只给 HTTP 配超时。
// 捕获本轮 signal:失败卡重试会换 controller,迟到结果仍属于旧轮。
const signal = task.abort.signal;
let rejectWait!: (error: Error) => void;
let timedOut = false;
const interrupted = new Promise<never>((_resolve, reject) => { rejectWait = reject; });
const onAbort = () => rejectWait(new Error(i18n.t(timedOut ? 'composer.upload.timeout' : 'composer.upload.cancelled')));
signal.addEventListener('abort', onAbort);
let timer: ReturnType<typeof setTimeout> | undefined;
const armTimeout = () => {
clearTimeout(timer);
timer = setTimeout(() => {
timedOut = true;
task.abort.abort();
}, 180_000);
};
armTimeout();
const step = <T>(value: T | Promise<T>, late?: (result: T) => void): Promise<T> => Promise.race([
Promise.resolve(value).then((result) => {
if (signal.aborted) late?.(result);
return result;
}),
interrupted,
]);
let uploadedAttachment: RemoteSerializedAttachment | undefined;
let uploadToken: string | null = null;
try {
if (signal.aborted) onAbort();
// token 先就位(可能仍在网络 refresh):拿不到就快速失败,不浪费后面的转码/降采样。
const token = uploadToken = await step(task.token);
if (!token) {
throw new Error(task.candidate.kind === 'image'
? i18n.t('composer.upload.sessionExpiredImage')
: i18n.t('composer.upload.sessionExpiredFile'));
}
// 取消检查点 1:token 等待期间被 X 掉的任务在这里短路,跳过后面的换址/转码/降采样。
if (task.discarded) {
outcome = 'discarded';
return;
}
const prepared = await step(prepareTaskSource(task));
const source = task.resolvedSource ?? prepared;
const size = prepared.size;
// 取消检查点 2:资产就位 / 降采样(大图慢路径)期间被 X 掉的任务在发起 PUT 前短路
// ——PUT 一旦开始便不可中止,只能事后 best-effort 删除,这里拦住就不产生 OSS 孤儿风险。
if (task.discarded) {
outcome = 'discarded';
return;
}
// 上传阶段不受总时限约束:附件不限大小,传输层各自按无进度/单次请求判超时
//(OSS 60 秒无进度、直连逐请求超时、presign 12 秒),用户取消仍即时生效。
clearTimeout(timer);
const attachment = uploadedAttachment = await step(deps.upload(
{ name: prepared.name, size, mimeType: prepared.mimeType || undefined, ...(source.sharedTaskId ? { sharedTaskId: source.sharedTaskId } : {}), ...(source.deviceId ? { deviceId: source.deviceId } : {}) },
prepared.uri,
{ token, signal },
), (late) => deps.discard(late, token));
armTimeout();
if (task.handoff) await task.handoff.promise;
task.delivering = true;
if (task.discarded) {
// 上传成功但用户已 X 掉 / 页面已退出:回收中转对象,不回调宿主。
deps.discard(attachment, token);
outcome = 'discarded';
} else {
// 回传就位后的 candidate(kind / sourceId 随 spread 保留):resolve 型任务
// (相册 ph:// 换址、HEIC / 粘贴转码)实际上传的是 source.uri,宿主的预览
// 映射要指向这个仍然在世的 file://,而不是可能被系统回收的原始临时文件。
await step(Promise.resolve(deps.onUploaded(
attachment,
source,
prepared.uri,
task.localId,
[...task.localUris],
() => !disposed && !task.discarded && !signal.aborted,
)), () => deps.discard(attachment, token));
if (disposed || task.discarded) {
// onUploaded 可能为粘贴图片等待持久缩略图;等待期间退屏 / removeAll
// 时不能再把附件写回旧页面,且已经上传的 OSS 对象仍须回收。
deps.discard(attachment, token);
outcome = 'discarded';
} else {
outcome = 'uploaded';
try { task.candidate.onConsumed?.(); } catch { /* 回收不改变交付结果 */ }
}
}
} catch (err) {
if (uploadedAttachment) deps.discard(uploadedAttachment, uploadToken);
if (task.handoff) await task.handoff.promise;
if (task.discarded) {
outcome = 'discarded';
} else {
deps.onFailed(err, task.localId, task.candidate);
outcome = 'failed';
}
} finally {
clearTimeout(timer);
signal.removeEventListener('abort', onAbort);
if (task.handoff) await task.handoff.promise;
task.delivering = false;
if (outcome === 'failed' && !disposed) {
// 失败卡保留在托盘(state=failed,可 retry / remove),不再从 map 删除——
// 弱网下「图直接消失 + 一条 toast」逼用户重新找图重选,原地重试才是对的。
// 只保留原始粘贴文件供 retry;本轮 resolve / preprocess 中间产物立即回收。
cleanupTaskLocalUris(task, true);
task.state = 'failed';
} else {
// uploaded 的成功路径由 onUploaded 在把预览换成持久缩略图后清理;
// discarded(以及退屏后才失败、不再保留失败卡的任务)在这里回收全部
// 自有临时文件并回调 onAbandoned。
if (outcome !== 'uploaded') cleanupTaskLocalUris(task, false);
tasks.delete(task.localId);
}
runningCount -= 1;
task.resolveOutcome(outcome);
if (!disposed && !task.discarded) notifyPending();
pump();
}
}
return {
async waitForDelivering() {
await Promise.all([...tasks.values()].filter((task) => task.delivering).map((task) => task.outcome));
},
isRetainingUri(uri) {
return [...tasks.values()].some((task) => task.handoff && task.localUris.has(uri));
},
beginHandoff() {
if ([...tasks.values()].some((task) => task.delivering)) throw new Error('ATTACHMENT_DELIVERING');
const captured = [...tasks.values()].filter((task) => !task.discarded && !task.claimed && !task.delivering);
for (const task of captured) {
if (task.handoff) throw new Error('ATTACHMENT_HANDOFF_BUSY');
let resolve!: () => void;
const promise = new Promise<void>((done) => { resolve = done; });
task.handoff = { promise, resolve };
}
let released = false;
return {
prepare: () => Promise.all(captured.map(async (task) => ({ localId: task.localId, source: await prepareTaskSource(task) }))),
release(commit) {
if (released) return;
released = true;
for (const task of captured) {
const handoff = task.handoff;
if (commit) {
task.discarded = true;
task.abort.abort();
if (task.state !== 'running') {
tasks.delete(task.localId);
task.resolveOutcome('discarded');
}
}
task.handoff = undefined;
handoff?.resolve();
if (commit) cleanupTaskLocalUris(task, false);
}
notifyPending();
},
};
},
enqueue(candidates, opts) {
if (disposed) {
for (const candidate of candidates) {
try { candidate.onAbandoned?.(); } catch { /* 调用方回收失败不影响管线 */ }
}
return;
}
if (candidates.length === 0) return;
for (const candidate of candidates) {
seq += 1;
const localId = `local-attachment-upload-${seq}`;
tasks.set(localId, {
localId,
candidate,
token: opts.token,
state: 'queued',
discarded: false,
claimed: false,
abort: new AbortController(),
localUris: new Set([candidate.uri]),
...createOutcome(),
});
}
notifyPending();
pump();
},
remove(localId) {
const task = tasks.get(localId);
if (!task || task.discarded) return;
if (task.state === 'queued' || task.state === 'failed') {
// 还没开跑 / 已失败结算:直接出队;自有粘贴临时文件同步进入回收队列。
tasks.delete(task.localId);
cleanupTaskLocalUris(task, false);
task.resolveOutcome('discarded');
} else {
// 已 in-flight:标记丢弃 + abort 真正断掉传输(PUT 层监听 signal 走
// UploadTask.cancelAsync),不再让被取消的上传白跑流量;abort 到达前
// 已完成的场景由 runTask 末段回收 OSS 对象兜底。
// outcome 提前落定为 discarded:waitForIdle 已快照进 Promise.all 的等待立即解除
// ——弱网发送转圈时点 X,send() 不该继续陪被取消的上传等到 OS 超时(codex
// review R16)。Promise 重复 resolve 幂等,runTask finally 的二次落定是 no-op。
task.discarded = true;
task.abort.abort();
task.resolveOutcome('discarded');
}
notifyPending();
},
retry(localId, opts) {
const task = tasks.get(localId);
if (!task || task.discarded || task.state !== 'failed') return;
// 重新入队跑完整管线;outcome 换新的一份(旧的已落定为 failed,不可复用),
// abort 通道同理换新(上一轮超时已把旧 signal 打成 aborted),
// token 用调用方给的新鲜值(失败卡可能停留很久,旧凭证大概率已过期)。
const renewed = createOutcome();
task.state = 'queued';
task.delivering = false;
task.token = opts.token;
task.abort = new AbortController();
task.outcome = renewed.outcome;
task.resolveOutcome = renewed.resolveOutcome;
notifyPending();
pump();
},
removeAll() {
// 与 dispose 同一套丢弃语义,但不置 disposed:之后仍可正常 enqueue 新批次。
// 只清 composer 域(未 claim)的任务:removeAll 的调用方语义都是「丢弃托盘
// 在途上传」(切换目标电脑 / 排队编辑退出),已 claim 给 outbox 消息的任务
// 不归它管——误丢会让 discarded 任务不再回调,对应消息永远卡在「上传中」。
for (const task of tasks.values()) {
if (task.claimed) continue;
if (task.state === 'queued' || task.state === 'failed') {
tasks.delete(task.localId);
cleanupTaskLocalUris(task, false);
} else {
task.discarded = true;
task.abort.abort();
}
// in-flight 同样提前落定(见 remove 的说明),解除 waitForIdle 的既有等待。
task.resolveOutcome('discarded');
}
notifyPending();
},
async waitForIdle() {
// 等待期间可能有新任务入队(用户连拍),循环直到没有活跃(queued / running)
// 任务。已丢弃任务不进快照:被 X 掉的在途上传不会再影响 attachments,发送没
// 必要等它跑完(它的 OSS 回收由 runTask 末段自理)。已 claim 任务同理不进——
// 它们属于先前发出的乐观消息,本次发送没理由等别人的附件。失败态任务已结算、
// 不再变化,不能进等待快照(它们的 outcome 恒已落定,会造成忙等死循环);以「结算
// 时刻托盘里仍挂着的失败卡数」作为失败口径——有失败卡就不该放行发送。
for (;;) {
const snapshot = [...tasks.values()]
.filter((task) => !task.discarded && !task.claimed && task.state !== 'failed')
.map((task) => task.outcome);
if (snapshot.length === 0) {
let failedCount = 0;
for (const task of tasks.values()) {
if (!task.discarded && !task.claimed && task.state === 'failed') failedCount += 1;
}
return { failedCount };
}
await Promise.all(snapshot);
}
},
hasPending() {
for (const task of tasks.values()) {
if (!task.discarded && !task.claimed) return true;
}
return false;
},
pendingCount() {
let count = 0;
for (const task of tasks.values()) {
if (!task.discarded && !task.claimed) count += 1;
}
return count;
},
claim(localIds) {
let changed = false;
for (const localId of localIds) {
const task = tasks.get(localId);
if (!task || task.discarded || task.claimed) continue;
task.claimed = true;
changed = true;
}
// claimed 任务离开托盘,同步刷一次 pending 列表。
if (changed) notifyPending();
},
unclaim(localIds) {
let changed = false;
for (const localId of localIds) {
const task = tasks.get(localId);
if (!task || task.discarded || !task.claimed) continue;
task.claimed = false;
changed = true;
}
// 任务回到托盘域,同步刷一次 pending 列表(失败卡也会重新出现,可 retry / X)。
if (changed) notifyPending();
},
claimableTasks() {
const out: Array<{
localId: string;
failed: boolean;
kind: MobileLocalAttachmentKind;
previewUri: string;
name: string;
}> = [];
for (const task of tasks.values()) {
if (task.discarded || task.claimed) continue;
out.push({
localId: task.localId,
failed: task.state === 'failed',
kind: task.candidate.kind,
previewUri: task.candidate.uri,
name: task.candidate.name,
});
}
return out;
},
dispose() {
disposed = true;
for (const task of tasks.values()) {
if (task.state === 'queued' || task.state === 'failed') {
tasks.delete(task.localId);
cleanupTaskLocalUris(task, false);
} else {
task.discarded = true;
task.abort.abort();
}
// 同 remove / removeAll:提前落定,退屏时不让任何 waitForIdle 等待者挂死。
task.resolveOutcome('discarded');
}
},
};
}
/** Reorder only members of the same share, preserving all unrelated slot positions. */
export function incomingShareSlotOrder(orders: readonly (MobileLocalAttachmentUploadCandidate['incomingShareOrder'] | undefined)[]): number[] {
const result = orders.map((_, index) => index);
const groups = new Map<string, number[]>();
orders.forEach((order, index) => {
if (!order) return;
const group = groups.get(order.batchId) ?? [];
group.push(index); groups.set(order.batchId, group);
});
for (const positions of groups.values()) {
const sorted = [...positions].sort((a, b) => orders[a]!.index - orders[b]!.index);
positions.forEach((position, i) => { result[position] = sorted[i]; });
}
return result;
}