Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

34.9 KB
Raw Blame
/**
 * useMobileLocalAttachments.ts — 本机附件(相册 / 拍照 / 文件)乐观上传 hook。
 * ---------------------------------------------------------------------------
 * 会话页与新建会话页共用(与 MobileComposerInputRow 同精神,改一处两页生效)。
 * 职责:权限 + ImagePicker / DocumentPicker 拉起、candidate 构造,然后交给
 * mobileLocalAttachmentUpload 控制器做「立即进托盘 + 后台(降采样)上传」;
 * attachments / previews / error 等真相 state 仍由页面持有,经回调写入。
 *
 * 页面接线要点:
 *   - 托盘渲染 pendingUploads(图片=上传中缩略卡,文件=上传中 chip),X 走
 *     removePendingUpload;
 *   - 发送前 await waitForPendingUploads(),failedCount > 0 时中止发送;
 *   - 附件限额计算要把 pendingUploads.length 算进去;
 *   - 页面卸载时 hook 自动 dispose(在途上传完成后回收 OSS 中转对象)。
 */
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { parseSharedTaskPeer } from '@cindy/device-link';
import { useTranslation } from 'react-i18next';
import { Platform } from 'react-native';
import * as DocumentPicker from 'expo-document-picker';
import * as FileSystem from 'expo-file-system/legacy';
import { retainComposerAttachmentFile } from './durableOutboxFiles';
import * as ImagePicker from 'expo-image-picker';
import { formatRemoteError } from '@/device-link/remoteStatus';
import { canBrowsePhotoLibraryDirectly } from '@/session/photoLibraryPolicy';
import { pickDeferredLibraryPhotos } from '@/session/deferredPhotoLibrary';
import {
  MOBILE_MAX_ATTACHMENTS,
  assertMobileDocumentSize,
} from '@/session/attachments';
import { assertMobileImageSize, buildMobileImageAttachmentCandidate } from '@/session/mobileImageAttachment';
import { preprocessMobileImageForUpload } from '@/session/mobileImagePreprocess';
import {
  createMobileLocalAttachmentUploadController,
  isCameraUnavailableOnSimulator,
  type MobileLocalAttachmentUploadCandidate,
  type MobileLocalAttachmentUploadController,
  type MobileLocalAttachmentUploadDeps,
  type PendingLocalAttachmentUpload,
} from '@/session/mobileLocalAttachmentUpload';
import {
  discardMobileUploadedAttachment,
  statMobileAttachmentFileSize,
  uploadMobileAttachmentFromFile,
} from '@/session/mobileAttachmentUpload';
import {
  buildPastedImageFileName,
  classifyPastedImageUri,
  isComposerPastedImageUri,
  mimeTypeForPastedImageExt,
  resolvePastedImageAsset,
} from '@/session/pastedImageAttachment';
import {
  getSentAttachmentThumbUri,
} from '@/session/sentAttachmentThumbStore';
import type { RemoteSerializedAttachment } from '@/session/types';

export interface UseMobileLocalAttachmentsOptions {
  /** Fixed for this composer's lifetime; defaults to the existing computer upload. */
  upload?: MobileLocalAttachmentUploadDeps['upload'];
  /**
   * composer 附件作用域。已建任务页传 sessionId;作用域换代后,旧 picker / 粘贴 /
   * 标注异步入口与上传完成结果不得写入新作用域。省略时保持旧的单作用域行为。
   */
  attachmentScopeKey?: string;
  deviceId?: string;
  getAccessToken: () => Promise<string | null>;
  /** 当前已入列附件数(限额用;pending 由 hook 自己计入)。 */
  getAttachmentCount: () => number;
  /** 单个上传成功:页面把 attachment 入列;图片按 candidate.uri 记预览映射,
   *  candidate.sourceId(相册资产 id)供面板勾选态映射。localId 供已 claim
   *  (随乐观消息先发出)任务的产物路由——页面据此把附件填回对应消息而非托盘。 */
  onUploaded: (
    attachment: RemoteSerializedAttachment,
    candidate: MobileLocalAttachmentUploadCandidate,
    localId: string,
  ) => void;
  /** 错误文案(null = 清除);uploadLocalId = 触发失败的上传任务(已 claim 任务的
   *  失败由页面路由给对应乐观消息,不该落进 composer 错误条)。 */
  onError: (message: string | null, context?: { uploadLocalId?: string }) => void;
  /** picker 确认选图 / 拍下照片 / 选中文件后触发(页面用来关 Context 面板)。 */
  onPicked?: () => void;
}

/**
 * 粘贴占位卡的超时兜底:images-loading 之后原生层若一直不兑现(进程内异常、
 * 事件丢失),占位不能永远转圈。跨设备剪贴板(Mac 复制 → iPhone 粘贴)要等
 * 系统走网络拉数据,慢网下几十秒是真实场景,超时给足余量。
 */
const PASTE_PLACEHOLDER_TIMEOUT_MS = 60_000;

async function deleteLocalUris(uris: readonly string[]): Promise<void> {
  await Promise.all(uris.map((uri) => (
    FileSystem.deleteAsync(uri, { idempotent: true }).catch(() => undefined)
  )));
}

export interface UseMobileLocalAttachmentsResult {
  beginOutboxAttachmentHandoff: () => Promise<ReturnType<MobileLocalAttachmentUploadController['beginHandoff']>>;
  insertUploadedAttachment: (current: RemoteSerializedAttachment[], attachment: RemoteSerializedAttachment) => RemoteSerializedAttachment[];
  getUploadedSource: (id: string) => MobileLocalAttachmentUploadCandidate | undefined;
  /** Resolve a tray upload to its delivered attachment without retaining temporary URIs. */
  getUploadedAttachmentId: (localId: string) => string | undefined;
  releaseUploadedSources: (ids: readonly string[]) => void;
  /** 上传中的附件(托盘渲染 pending 卡)。 */
  pendingUploads: readonly PendingLocalAttachmentUpload[];
  /**
   * 粘贴占位卡数量:原生层已检测到图片粘贴、数据还在后台读取 / 写盘的窗口里,
   * 托盘先画 N 张无图转圈占位卡;onPasteImages 兑现或失败 / 超时后归零。
   */
  pastePlaceholderCount: number;
  /** Changes only for newly selected image batches, not upload progress or paste materialization. */
  imageSelectionRevision: number;
  /** 原生 images-loading 事件:立刻竖起 count 张粘贴占位卡。 */
  beginPastePlaceholders: (count: number) => void;
  /** 原生 images-load-failed 事件:撤掉占位卡并提示。 */
  failPastePlaceholders: () => void;
  /** 拉起相册 / 相机。 */
  addImages: (source: 'library' | 'camera') => Promise<void>;
  /** 拉起系统文件选择器。 */
  addDocument: () => Promise<void>;
  /** 输入框 Paste 粘贴剪贴板图片(ComposerRichInput 落盘的 file:// 临时文件)。 */
  addPastedImages: (uris: string[]) => Promise<void>;
  /** 直接入队已构造好的 candidates(Context 面板批量提交用,调用方自备 token,可传 Promise)。 */
  enqueueUploads: (
    candidates: readonly MobileLocalAttachmentUploadCandidate[],
    opts: { token: string | Promise<string | null> },
  ) => void;
  /** 托盘 X 一个上传中的附件。 */
  removePendingUpload: (localId: string) => void;
  /** 重试一个失败态的上传卡(自动取新鲜 token 重跑完整管线)。 */
  retryPendingUpload: (localId: string) => void;
  /**
   * 丢弃 composer 域的全部在途上传与粘贴占位(切换任务 / 目标电脑等草稿整体
   * 作废场景;完成后回收 OSS 中转对象)。
   */
  discardAllPendingUploads: () => void;
  /** 切换 attachmentScopeKey 前封住旧作用域;迟到 picker / 粘贴结果也会被拒绝。 */
  discardAllPendingUploadsForScopeChange: () => void;
  /**
   * 等全部在途上传落定;返回期间失败个数(>0 时调用方应中止发送)。
   * abandoned:等待期间 composer 已卸载、在途上传已被丢弃,调用方必须放弃发送。
   */
  waitForPendingUploads: () => Promise<{ failedCount: number; abandoned: boolean }>;
  /**
   * 把当前全部未 claim 上传任务(active + 失败卡)划归一条乐观消息并返回快照
   * (顺序 = 入队序):任务离开托盘 / 限额 / waitForPendingUploads,产物经
   * onUploaded / onError 的 localId 路由。快照与 claim 同一同步段完成,无竞态窗。
   */
  claimActiveUploads: () => ReturnType<MobileLocalAttachmentUploadController['claimableTasks']>;
  /**
   * claimActiveUploads 的逆操作:把一批已划归乐观消息的上传任务交还托盘。
   *
   * 乐观消息被收回成草稿时用(创建失败交还待发消息):任务继续跑,落定后宿主的
   * outbox 路由找不到归属条目、产物回落托盘。取消重传是错的——用户已经等过一次
   * 上传,粘贴来源的本地文件此时可能已被回收,重选都做不到(review P1)。
   */
  releaseClaimedUploads: (localIds: readonly string[]) => void;
  /** 只等粘贴占位落定(兑现任务已入队 / 失败 / 超时),不等上传完成;详见实现处注释。 */
  waitForPastePlaceholdersSettled: () => Promise<void>;
  /** 是否有粘贴占位在途(同步真源):占位兑现前任务尚未入队、无法 claim。 */
  hasPastePlaceholders: () => boolean;
  /**
   * 限额口径的在途占坑数**同步真源**(非 React state):上传中任务(controller
   * 内部计数)+ 粘贴占位批次总数。所有附件槽位校验(标注信箱串行 drain、
   * context-sheet 选图、handleSend 剩余槽位)必须读这里,两个理由:
   * (1) `pendingUploads` state 的 commit 走 macrotask,连续提交间读 state 会拿到
   * 「入队前」旧值,绕过 MOBILE_MAX_ATTACHMENTS(review P1);
   * (2) 粘贴占位窗口(原生还在读剪贴板)任务未入 controller 队列,不含占位的
   * 计数会放行超额选图 / 标注,占位兑现时轮到粘贴图自己撞上限被丢(review P2)。
   */
  getPendingUploadCount: () => number;
  /** Synchronous picker, upload and paste activity, including before the first slot exists. */
  hasAttachmentInput: () => boolean;
}

export function useMobileLocalAttachments(
  options: UseMobileLocalAttachmentsOptions,
): UseMobileLocalAttachmentsResult {
  const { t } = useTranslation();
  const [pendingUploads, setPendingUploads] = useState<readonly PendingLocalAttachmentUpload[]>([]);
  const pickerBusyRef = useRef(false);
  const disposedRef = useRef(false);
  /** 本 hook 拥有的 WebView 粘贴缓存;注册持久缩略图后或卸载时统一回收。 */
  const pastedImageLocalUrisRef = useRef(new Set<string>());
  const cleanupPastedImageLocalUris = async (uris: readonly string[]): Promise<void> => {
    await deleteLocalUris(uris);
    for (const uri of uris) pastedImageLocalUrisRef.current.delete(uri);
  };
  // 粘贴占位卡:按「批次」FIFO 记账(ref 数组是同步真源,state 只存总数供渲染
  // ——与 pendingCount 同理,限额校验不能读滞后一拍的 state)。原生事件不带批次
  // id,但两端的媒体处理都是串行队列(iOS mediaProcessingQueue / Android 单线程
  // executor),完成顺序 = 开始顺序,所以 images / images-load-failed 到达时按
  // FIFO 出列第一批即可——连续两次粘贴时,第一批先兑现只清自己的占位,第二批
  // 仍在原生处理中的占位继续转圈(review P2)。超时定时器兜底事件丢失,超时属
  // 异常兜底,一次清全部不做批次精度。
  const [pastePlaceholderCount, setPastePlaceholderCount] = useState(0);
  const [imageSelectionRevision, setImageSelectionRevision] = useState(0);
  const pastePlaceholderBatchesRef = useRef<number[]>([]);
  const pastePlaceholderTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  // 占位窗口的发送等待者:waitForPendingUploads 必须把占位当在途工作等待——
  // images-loading 到 images 兑现之间(跨设备剪贴板 / 大图可达数十秒)任务还没
  // 进 controller 队列,只等 waitForIdle 会让发送 / 创建把刚粘贴的图漏掉
  //(review P2)。占位全部落定(兑现 / 失败 / 超时归零)时统一放行。
  const pastePlaceholderWaitersRef = useRef<(() => void)[]>([]);
  // 回调经 ref 转发,controller 单例化的同时始终调到最新一次 render 的闭包。
  const optionsRef = useRef(options);
  optionsRef.current = options;
  // scope-change discard 与普通 removeAll 不同:除了清当前队列,还要让旧 render
  // 持有的 picker / 粘贴 / 标注闭包永久过期。不能只比 sessionId:A → B → A 时
  // 最早 A 的超慢异步结果仍是同 id,必须靠单调 generation 区分两次进入。
  const attachmentScopeGenerationRef = useRef(0);
  const attachmentScopeKey = options.attachmentScopeKey;
  const attachmentScopeGeneration = attachmentScopeGenerationRef.current;
  const isAttachmentScopeActive = () => attachmentScopeKey == null || (
    optionsRef.current.attachmentScopeKey === attachmentScopeKey
    && attachmentScopeGenerationRef.current === attachmentScopeGeneration
  );

  const getPastePlaceholderTotal = () =>
    pastePlaceholderBatchesRef.current.reduce((sum, n) => sum + n, 0);

  const flushPastePlaceholderWaiters = () => {
    const waiters = pastePlaceholderWaitersRef.current;
    pastePlaceholderWaitersRef.current = [];
    for (const resolve of waiters) resolve();
  };

  /** 批次数组变更后的统一收尾:同步 state 总数 + 重置超时兜底定时器 + 放行等待者。 */
  const syncPastePlaceholders = () => {
    const total = getPastePlaceholderTotal();
    setPastePlaceholderCount(total);
    if (pastePlaceholderTimerRef.current) {
      clearTimeout(pastePlaceholderTimerRef.current);
      pastePlaceholderTimerRef.current = null;
    }
    if (total > 0) {
      pastePlaceholderTimerRef.current = setTimeout(() => {
        pastePlaceholderTimerRef.current = null;
        pastePlaceholderBatchesRef.current = [];
        setPastePlaceholderCount(0);
        flushPastePlaceholderWaiters();
        optionsRef.current.onError(t('composer.upload.pasteTimeout'));
      }, PASTE_PLACEHOLDER_TIMEOUT_MS);
    } else {
      flushPastePlaceholderWaiters();
    }
  };

  /**
   * 等全部粘贴占位落定。放行时机安全性:兑现路径 shiftPastePlaceholderBatch 与
   * controller.enqueue 在 addPastedImages 的同一同步段里,waiter 的 promise 恢复
   * 是微任务,必然晚于该同步段结束——放行后紧接的 waitForIdle 一定能看到刚入队
   * 的上传任务,不存在"占位清了、任务还没入队"的空隙。
   */
  const waitForPastePlaceholders = (): Promise<void> => {
    if (getPastePlaceholderTotal() === 0) return Promise.resolve();
    return new Promise<void>((resolve) => {
      pastePlaceholderWaitersRef.current.push(resolve);
    });
  };

  const beginPastePlaceholders = (count: number) => {
    if (count <= 0 || !isAttachmentScopeActive()) return;
    pastePlaceholderBatchesRef.current.push(count);
    setImageSelectionRevision((revision) => revision + 1);
    syncPastePlaceholders();
  };

  /** 兑现 / 失败按 FIFO 出列一批(见上方串行队列不变量)。 */
  const shiftPastePlaceholderBatch = () => {
    if (pastePlaceholderBatchesRef.current.length === 0) return;
    pastePlaceholderBatchesRef.current.shift();
    syncPastePlaceholders();
  };

  const failPastePlaceholders = () => {
    if (!isAttachmentScopeActive()) return;
    if (pastePlaceholderBatchesRef.current.length === 0) return;
    shiftPastePlaceholderBatch();
    optionsRef.current.onError(t('composer.upload.clipboardReadFailed'));
  };

  const uploadedSourcesRef = useRef(new Map<string, MobileLocalAttachmentUploadCandidate & { localId: string }>());
  const stagingUrisRef = useRef(new Set<string>());
  const stagingOwnerRef = useRef(`${Date.now()}-${Math.random().toString(36).slice(2)}`);
  const controller = useMemo(() => createMobileLocalAttachmentUploadController({
    preprocess: preprocessMobileImageForUpload,
    statSize: statMobileAttachmentFileSize,
    assertSize: (size, candidate) => {
      if (candidate.kind === 'image') assertMobileImageSize(size);
      else assertMobileDocumentSize(size);
    },
    upload: options.upload ?? ((candidate, fileUri, opts) => uploadMobileAttachmentFromFile(candidate, fileUri, { ...opts, sharedTaskId: candidate.sharedTaskId, deviceId: candidate.deviceId })),
    discard: (attachment, token) => discardMobileUploadedAttachment(attachment, {
      getToken: () => token === undefined ? optionsRef.current.getAccessToken() : Promise.resolve(token),
    }),
    onPendingChange: setPendingUploads,
    onUploaded: async (attachment, candidate, uploadedUri, localId, localUris, isActive) => {
      const candidateScopeKey = candidate.attachmentScopeKey;
      if (candidateScopeKey != null && (
        optionsRef.current.attachmentScopeKey !== candidateScopeKey
        || candidate.attachmentScopeGeneration !== attachmentScopeGenerationRef.current
      )) {
        // 防御性代际闸:正常抽屉路径会先 removeAll,把任务标 discarded;若完成结果
        // 已越过 controller 的最后取消检查点,这里仍按 candidate 的原 owner 拒收。
        // task 已被 removeAll 标记时由 controller 统一回收,避免这里重复 DELETE。
        if (!isActive()) return;
        discardMobileUploadedAttachment(attachment, {
          getToken: () => optionsRef.current.getAccessToken(),
        });
        if (candidate.cleanupLocalUris) void candidate.cleanupLocalUris(localUris).catch(() => undefined);
        // 结果被拒收 = 任务被放弃:让自行生成输入文件的调用方回收(见 onAbandoned)。
        try { candidate.onAbandoned?.(); } catch { /* 回收失败不影响管线 */ }
        return;
      }
      // The upload entry already retained the exact snapshot with its owner/cancellation
      // fence. Do not register again here under a potentially newer account.
      let deliveredCandidate = candidate;
      if (candidate.kind === 'image' && candidate.cleanupLocalUris) {
        const ossRef = attachment.url ?? attachment.path;
        const durablePreviewUri = ossRef ? getSentAttachmentThumbUri(ossRef) : null;
        if (durablePreviewUri) deliveredCandidate = { ...candidate, uri: durablePreviewUri };
      }
      if (candidate.cleanupLocalUris) {
        for (const uri of localUris) {
          if (uri.startsWith('file://')) pastedImageLocalUrisRef.current.add(uri);
        }
      }
      if (!isActive()) return;
      // Keep the actual PUT bytes for all file kinds until the composer hands them off.
      // Thumbnail caches are evictable and cannot be the only source of an unsent attachment.
      const stageUri = await retainComposerAttachmentFile(stagingOwnerRef.current, attachment.id, uploadedUri, attachment.size);
      stagingUrisRef.current.add(stageUri);
      if (!isActive()) {
        await FileSystem.deleteAsync(stageUri, { idempotent: true });
        stagingUrisRef.current.delete(stageUri);
        return;
      }
      uploadedSourcesRef.current.set(attachment.id, {
        ...candidate, localId, uri: stageUri, name: attachment.name, mimeType: attachment.mimeType,
        size: attachment.size, resolve: undefined, skipPreprocess: true, cleanupLocalUris: undefined,
        onAbandoned: undefined, onConsumed: undefined,
      });
      optionsRef.current.onUploaded(attachment, deliveredCandidate, localId);
      if (candidate.cleanupLocalUris && (candidate.kind === 'file' || deliveredCandidate.uri !== candidate.uri)) {
        // Staging owns retry/send bytes. Images additionally require a replacement
        // preview before deleting their source; ordinary files have no URI preview.
        void candidate.cleanupLocalUris(localUris).catch(() => undefined);
      }
    },
    onFailed: (err, localId, candidate) => {
      const candidateScopeKey = candidate.attachmentScopeKey;
      if (candidateScopeKey != null && (
        optionsRef.current.attachmentScopeKey !== candidateScopeKey
        || candidate.attachmentScopeGeneration !== attachmentScopeGenerationRef.current
      )) return;
      optionsRef.current.onError(formatRemoteError(err), { uploadLocalId: localId });
    },
  }), []);

  const discardAllPendingUploads = useCallback(() => {
    controller.removeAll();
    // 粘贴占位尚未进入 controller 队列,但同样属于当前 composer 草稿。任务 / 设备
    // 换代时若只清 controller,旧占位会继续显示在新目标,且 waitForPendingUploads
    // 的等待者会一直挂到旧粘贴事件落定或超时。
    pastePlaceholderBatchesRef.current = [];
    setPastePlaceholderCount(0);
    if (pastePlaceholderTimerRef.current) {
      clearTimeout(pastePlaceholderTimerRef.current);
      pastePlaceholderTimerRef.current = null;
    }
    const waiters = pastePlaceholderWaitersRef.current;
    pastePlaceholderWaitersRef.current = [];
    for (const resolve of waiters) resolve();
  }, [controller]);

  const discardAllPendingUploadsForScopeChange = useCallback(() => {
    // 同一旧 render 的抽屉同步封口 + effect cleanup 会各调用一次;只有仍是本代时
    // 才递增,保证新 session render 捕获的 generation 不被旧 cleanup 再作废。
    if (
      attachmentScopeKey != null
      && attachmentScopeGenerationRef.current === attachmentScopeGeneration
    ) attachmentScopeGenerationRef.current += 1;
    discardAllPendingUploads();
  }, [attachmentScopeGeneration, attachmentScopeKey, discardAllPendingUploads]);

  const enqueueUploads = (
    candidates: readonly MobileLocalAttachmentUploadCandidate[],
    opts: { token: string | Promise<string | null> },
    replacesPastePlaceholder = false,
  ) => {
    if (!isAttachmentScopeActive()) {
      // 作用域已失效,任务不会入队:视同放弃,让自行生成输入文件的调用方回收。
      for (const candidate of candidates) {
        try { candidate.onAbandoned?.(); } catch { /* 回收失败不影响管线 */ }
      }
      return;
    }
    controller.enqueue(
      candidates.map((candidate) => ({
            ...candidate,
            ...(attachmentScopeKey == null ? {} : { attachmentScopeGeneration, attachmentScopeKey }),
            sharedTaskId: parseSharedTaskPeer(optionsRef.current.deviceId ?? '')?.sharedTaskId,
            deviceId: optionsRef.current.deviceId,
          })),
      opts,
    );
    if (!replacesPastePlaceholder && candidates.some((candidate) => candidate.kind === 'image')) {
      setImageSelectionRevision((revision) => revision + 1);
    }
  };

  useEffect(() => () => {
    disposedRef.current = true;
    controller.dispose();
    const pastedUris = [...pastedImageLocalUrisRef.current].filter((uri) => !controller.isRetainingUri(uri));
    void deleteLocalUris([...stagingUrisRef.current]);
    stagingUrisRef.current.clear();
    uploadedSourcesRef.current.clear();
    pastedImageLocalUrisRef.current.clear();
    if (pastedUris.length > 0) void deleteLocalUris(pastedUris);
    if (pastePlaceholderTimerRef.current) {
      clearTimeout(pastePlaceholderTimerRef.current);
      pastePlaceholderTimerRef.current = null;
    }
    // 卸载放行滞留的发送等待者,防 waitForPendingUploads 永久悬挂。
    flushPastePlaceholderWaiters();
  }, [controller]);

  const waitForPendingUploadsInScope = async (): Promise<{ failedCount: number }> => {
    if (!isAttachmentScopeActive()) return { failedCount: 0 };
    await waitForPastePlaceholders();
    if (!isAttachmentScopeActive()) return { failedCount: 0 };
    const result = await controller.waitForIdle();
    return isAttachmentScopeActive() ? result : { failedCount: 0 };
  };

  /** 限额口径的在途占坑数(见接口 doc):上传中任务 + 粘贴占位。 */
  const getPendingSlotCount = () => controller.pendingCount() + getPastePlaceholderTotal();

  /** 限额检查 + 防重入的公共前奏;返回 null 表示不能继续。 */
  const beginPick = (): { remainingSlots: number } | null => {
    if (!isAttachmentScopeActive()) return null;
    if (pickerBusyRef.current) return null;
    // 占坑数读同步真源 getPendingSlotCount(上传中 + 粘贴占位),不读 React state:
    // 连续入队场景不受 state commit 滞后影响(review P1);占位期间从相册再加图
    // 不能超限,addPastedImages 自己会在进本函数前出列本批占位,不会双扣。
    const remainingSlots = MOBILE_MAX_ATTACHMENTS
      - optionsRef.current.getAttachmentCount()
      - getPendingSlotCount();
    if (remainingSlots <= 0) {
      optionsRef.current.onError(t('composer.upload.maxAttachments', { count: MOBILE_MAX_ATTACHMENTS }));
      return null;
    }
    pickerBusyRef.current = true;
    optionsRef.current.onError(null);
    return { remainingSlots };
  };

  const addImages = async (source: 'library' | 'camera'): Promise<void> => {
    const begun = beginPick();
    if (!begun) return;
    try {
      // iOS 模拟器无相机:不拦截会在原生层直接崩进程(见 isCameraUnavailableOnSimulator)。
      if (source === 'camera'
        && isCameraUnavailableOnSimulator(Platform.OS, FileSystem.documentDirectory)) {
        optionsRef.current.onError(t('composer.upload.simulatorNoCamera'));
        return;
      }
      if (source === 'camera' || canBrowsePhotoLibraryDirectly(Platform.OS)) {
        const permission = source === 'camera'
          ? await ImagePicker.requestCameraPermissionsAsync()
          : await ImagePicker.requestMediaLibraryPermissionsAsync(false);
        if (!isAttachmentScopeActive()) return;
        if (!permission.granted) {
          optionsRef.current.onError(source === 'camera'
            ? t('composer.upload.cameraPermission')
            : t('composer.upload.photoPermission'));
          return;
        }
      }

      if (source === 'library' && Platform.OS === 'ios') {
        const candidates = await pickDeferredLibraryPhotos(begun.remainingSlots);
        if (candidates !== null) {
          if (!isAttachmentScopeActive()) {
            for (const candidate of candidates) candidate.onAbandoned?.();
            return;
          }
          // 原图尚未从 iCloud 取回也能立即入队、claim 到乐观消息。
          // 读取与上传共用既有取消/重试/作用域生命周期,不另建下载队列。
          for (const candidate of candidates.slice(begun.remainingSlots)) candidate.onAbandoned?.();
          const accepted = candidates.slice(0, begun.remainingSlots);
          if (accepted.length === 0) return;
          enqueueUploads(accepted, { token: optionsRef.current.getAccessToken() });
          optionsRef.current.onPicked?.();
          return;
        }
      }

      const picked = source === 'camera'
        ? await ImagePicker.launchCameraAsync({
          mediaTypes: ['images'],
          quality: 1,
        })
        : await ImagePicker.launchImageLibraryAsync({
          allowsMultipleSelection: true,
          mediaTypes: ['images'],
          orderedSelection: true,
          quality: 1,
          selectionLimit: begun.remainingSlots,
        });
      if (!isAttachmentScopeActive()) return;
      if (picked.canceled) return;

      const candidates: MobileLocalAttachmentUploadCandidate[] = picked.assets
        .slice(0, begun.remainingSlots)
        .map((asset, index) => ({ kind: 'image', ...buildMobileImageAttachmentCandidate(asset, index) }));
      if (candidates.length === 0 || !isAttachmentScopeActive()) return;
      // 立即入 pending 托盘(不先 await token):token 等待窗里任务已可被 waitForIdle 看到,
      // composer 抢发会等它落定而不是丢图;token 由任务开跑时自行等待(拿不到→该任务失败报错)。
      enqueueUploads(candidates, { token: optionsRef.current.getAccessToken() });
      optionsRef.current.onPicked?.();
    } catch (err) {
      if (isAttachmentScopeActive()) optionsRef.current.onError(formatRemoteError(err));
    } finally {
      pickerBusyRef.current = false;
    }
  };

  const addDocument = async (): Promise<void> => {
    const begun = beginPick();
    if (!begun) return;
    try {
      const picked = await DocumentPicker.getDocumentAsync({
        copyToCacheDirectory: true,
        multiple: false,
      });
      if (!isAttachmentScopeActive()) return;
      if (picked.canceled) return;

      const asset = picked.assets?.[0];
      const uri = asset?.uri?.trim();
      const name = asset?.name?.trim();
      if (!asset || !uri || !name) {
        optionsRef.current.onError(t('composer.upload.noFileRead'));
        return;
      }
      const size = typeof asset.size === 'number' && Number.isFinite(asset.size) && asset.size > 0
        ? asset.size
        : 0;
      if (!isAttachmentScopeActive()) return;
      // 立即入 pending 托盘(带文件名 chip,不先 await token,同 addImages):大 PDF 不再卡住托盘。
      enqueueUploads([{
        kind: 'file',
        uri,
        name,
        size,
        mimeType: asset.mimeType || undefined,
      }], { token: optionsRef.current.getAccessToken() });
      optionsRef.current.onPicked?.();
    } catch (err) {
      if (isAttachmentScopeActive()) optionsRef.current.onError(formatRemoteError(err));
    } finally {
      pickerBusyRef.current = false;
    }
  };

  /**
   * 输入框长按 Paste 粘贴剪贴板图片:与相册 / 拍照同一条乐观管线——粘贴落盘的
   * 临时文件立刻做托盘预览,重命名 / HEIC 转码(resolve 钩子)+ 降采样 + 上传
   * 全部在后台任务里跑(取代 #589 的阻塞式上传 + attachmentBusy 门)。
   */
  const addPastedImages = async (uris: string[]): Promise<void> => {
    if (uris.length === 0) return;
    const ownedUris = uris.filter(isComposerPastedImageUri);
    if (!isAttachmentScopeActive()) {
      if (ownedUris.length > 0) void deleteLocalUris(ownedUris);
      return;
    }
    for (const uri of ownedUris) pastedImageLocalUrisRef.current.add(uri);
    // 本批 uris 就是最早一批占位卡的兑现:先按 FIFO 出列本批再做限额检查
    //(否则这批会被自己的占位双扣槽位)。出列与下方 enqueue 的 pending 上屏在
    // 同一同步段,React 批处理保证占位卡 → pending 卡之间没有空帧。
    const replacesPastePlaceholder = getPastePlaceholderTotal() > 0;
    shiftPastePlaceholderBatch();
    const begun = beginPick();
    if (!begun) {
      void cleanupPastedImageLocalUris(ownedUris);
      return;
    }
    try {
      // 同步段就入队,绝不先 await token:粘贴没有 picker modal 遮挡,token 走网络 refresh
      // 的等待窗里用户可直接点发送——任务不在队里的话 waitForIdle 立即返回,刚粘贴的图
      // 会被静默丢弃(#589 用 attachmentBusy 门堵的就是这个,乐观管线用「先入队」替代)。
      const acceptedUris = uris.slice(0, begun.remainingSlots);
      const rejectedUris = uris.slice(begun.remainingSlots).filter(isComposerPastedImageUri);
      if (rejectedUris.length > 0) void cleanupPastedImageLocalUris(rejectedUris);
      enqueueUploads(acceptedUris.map((uri, index) => {
        const classified = classifyPastedImageUri(uri);
        const ownsLocalFile = isComposerPastedImageUri(uri);
        return {
          kind: 'image' as const,
          uri,
          name: buildPastedImageFileName(index, classified.ext),
          size: 0,
          // mimeType 必须从入队起就有值:缺失时预签名不锁 Content-Type,原生直传层
          // 自动补 application/octet-stream,签名不一致 → OSS 403(2026-07 实撞)。
          mimeType: mimeTypeForPastedImageExt(classified.ext),
          resolve: async () => {
            const resolved = await resolvePastedImageAsset(uri, index);
            return { uri: resolved.uri, name: resolved.fileName, mimeType: resolved.mimeType };
          },
          cleanupLocalUris: ownsLocalFile ? cleanupPastedImageLocalUris : undefined,
        };
      }), { token: optionsRef.current.getAccessToken() }, replacesPastePlaceholder);
    } catch (err) {
      if (isAttachmentScopeActive()) optionsRef.current.onError(formatRemoteError(err));
    } finally {
      pickerBusyRef.current = false;
    }
  };

  return {
    beginOutboxAttachmentHandoff: async () => {
      for (;;) {
        await controller.waitForDelivering();
        try { return controller.beginHandoff(); }
        catch (error) {
          if (!(error instanceof Error) || error.message !== 'ATTACHMENT_DELIVERING') throw error;
        }
      }
    },
    insertUploadedAttachment: (current, attachment) => {
      const order = uploadedSourcesRef.current.get(attachment.id)?.incomingShareOrder;
      if (!order) return [...current, attachment];
      let position = current.length;
      for (let i = 0; i < current.length; i++) {
        const other = uploadedSourcesRef.current.get(current[i].id)?.incomingShareOrder;
        if (other?.batchId !== order.batchId) continue;
        position = i + 1;
        if (other.index > order.index) { position = i; break; }
      }
      return [...current.slice(0, position), attachment, ...current.slice(position)];
    },
    getUploadedSource: (id) => uploadedSourcesRef.current.get(id),
    getUploadedAttachmentId: (localId) => [...uploadedSourcesRef.current].find(([, source]) => source.localId === localId)?.[0],
    releaseUploadedSources: (ids) => {
      for (const id of ids) {
        const source = uploadedSourcesRef.current.get(id);
        if (!source) continue;
        uploadedSourcesRef.current.delete(id);
        stagingUrisRef.current.delete(source.uri);
        void deleteLocalUris([source.uri]);
      }
    },
    pendingUploads,
    pastePlaceholderCount,
    imageSelectionRevision,
    beginPastePlaceholders,
    failPastePlaceholders,
    addImages,
    addDocument,
    addPastedImages,
    enqueueUploads,
    removePendingUpload: controller.remove,
    retryPendingUpload: (localId) => {
      if (!isAttachmentScopeActive()) return;
      // 重试前清掉上一次失败的错误文案;token 取新鲜值(失败卡可能停留很久)。
      optionsRef.current.onError(null);
      controller.retry(localId, { token: optionsRef.current.getAccessToken() });
    },
    discardAllPendingUploads,
    discardAllPendingUploadsForScopeChange,
    // 先等粘贴占位落定(images 兑现会把任务同步入队 / 失败与超时直接归零),
    // 再等 controller 队列——否则占位窗口内抢发会把刚粘贴的图漏在消息外
    //(review P2)。占位失败不计入 failedCount:那张图从未成为附件,语义等同
    // 用户手动移除,不应中止发送。
    // 卸载会把在途任务标记丢弃,waitForIdle 不把丢弃计入失败;必须单独报出 abandoned,
    // 否则调用方会带着缺图的附件列表照常发送(上传中点返回,发出无图消息)。
    waitForPendingUploads: async () => ({
      ...await waitForPendingUploadsInScope(),
      abandoned: disposedRef.current,
    }),
    claimActiveUploads: () => {
      if (!isAttachmentScopeActive()) return [];
      const snapshot = controller.claimableTasks();
      controller.claim(snapshot.map((task) => task.localId));
      return snapshot;
    },
    releaseClaimedUploads: controller.unclaim,
    // 只等粘贴占位落定(兑现的同步段任务已入 controller 队列),不等上传本身:
    // 乐观发送(outbox)在占位窗口内需要它把「尚未入队、无法划归」的粘贴图等成
    // 可划归任务,再做同步 claim——不能用 waitForPendingUploads(那会退化回
    // 等整个上传完成)。失败 / 超时同样放行(60s 兜底,错误 toast 已由占位路径给出)。
    waitForPastePlaceholdersSettled: () => (
      isAttachmentScopeActive() ? waitForPastePlaceholders() : Promise.resolve()
    ),
    hasPastePlaceholders: () => isAttachmentScopeActive() && getPastePlaceholderTotal() > 0,
    getPendingUploadCount: () => (isAttachmentScopeActive() ? getPendingSlotCount() : 0),
    hasAttachmentInput: () => isAttachmentScopeActive() && (pickerBusyRef.current || getPendingSlotCount() > 0),
  };
}