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。

30.4 KB
Raw Blame
/**
 * useComposerImageAnnotations.ts — 圈点标注与 composer 附件管线的接线 hook
 * (会话页 / 新建会话页共用)。
 * ---------------------------------------------------------------------------
 * 职责(桌面 PR #792 的手机版对应物,按乐观上传管线重排了烧录时机):
 *   - 聊天 lightbox「发送到对话」:历史图(可带圈点)→ 烧录 → 进 composer 托盘
 *     上传;无笔迹时等价转发原图。
 *   - 托盘再编辑:标注附件保留「矢量笔迹 + 原图」真相(metaRef),点开托盘图
 *     显示原图 + 可撤销笔迹,保存后替换附件重新烧录上传;笔迹撤光 = 恢复原图。
 *   - annotated wire 标:烧录产物上传成功后给 RemoteSerializedAttachment 打
 *     annotated,被控端桌面(buildMakerUserMessage)据此注入「红色笔迹是用户
 *     标注」说明。
 *
 * 与桌面的差异:桌面托盘期零烧录、发送时刻才物化;手机附件是「入托盘即上传」
 * 的乐观管线,烧录提前到保存时刻(uri 即烧录图,托盘缩略图天然带笔迹)。矢量
 * 笔迹仍是唯一事实源——原图 + 笔迹在本地保留,再编辑时重放,重存时重新烧录。
 *
 * 源文件寿命:标注/转发的源图统一复制进本 hook 私有的 annotation-src 缓存目录
 * (聊天图的磁盘缓存受 LRU 管辖,直接引用会在再编辑窗口内被清理)。生成文件的
 * 回收跟随上传生命周期:上传成功后挂到附件名下,随附件移除 / 发送清空 / 被替换
 * 删除;上传失败时失败卡仍在托盘、可重试,文件原样保留;只有任务被确定放弃
 * (失败卡 / 在途卡被移除、整体丢弃、退屏、交接给发件箱)才删除。
 */
import { useCallback, useMemo, useRef } from 'react';
import { useTranslation } from 'react-i18next';
import { Alert, Platform } from 'react-native';
import * as FileSystem from 'expo-file-system/legacy';
import { summarizeAnnotationRegions } from '@cindy/maker-shared/image-annotation';
import { useAnnotationBurnIn } from '@/session/AnnotationBurnInWebView';
import {
  annotationBurnedFileName,
  imageMimeForUriFallback,
  isAnnotationBurnSourceResultUsable,
  isDirectSendableImageMime,
  planAnnotationBurnSource,
  sniffImageMimeFromBase64,
  type AnnotationBurnSourcePlan,
  type AnnotationStroke,
} from '@/session/imageAnnotationModel';
import { MOBILE_MAX_ATTACHMENTS } from '@/session/attachments';
import type { ImageLightboxAnnotationConfig } from '@/session/ImageLightbox';
import type {
  MobileLocalAttachmentUploadCandidate,
} from '@/session/mobileLocalAttachmentUpload';
import type { RemoteSerializedAttachment } from '@/session/types';

/**
 * 标注烧录要把整张图 base64 读进 JS 内存,这是防 OOM 的上限,与附件本身的发送上限无关
 *(附件与桌面一致只受传输通道限制)。
 */
const ANNOTATION_SOURCE_MAX_BYTES = 30 * 1024 * 1024;

/** 标注附件的再编辑真相(attachmentId → 矢量笔迹 + 原图)。 */
interface AnnotationEditMeta {
  strokes: AnnotationStroke[];
  /** 未烧录原图(annotation-src 私有副本,不受磁盘缓存 LRU 影响)。 */
  sourceUri: string;
  sourceMimeType: string;
  /** sourceUri 本身已是带笔迹的烧录图(见 candidate.annotation.baseAnnotated)。 */
  baseAnnotated?: boolean;
}

export interface UseComposerImageAnnotationsOptions {
  getAccessToken: () => Promise<string | null>;
  /** 乐观上传入队(useMobileLocalAttachments 的 enqueueUploads)。 */
  enqueueUploads: (
    candidates: readonly MobileLocalAttachmentUploadCandidate[],
    opts: { token: string | Promise<string | null> },
  ) => void;
  /** 再编辑保存时移除被替换的旧附件(页面的 remove,含 OSS 回收 + previews 清理)。 */
  removeAttachment: (attachmentId: string) => void;
  /**
   * 剩余附件槽位(MOBILE_MAX_ATTACHMENTS − 已入列 − pending):新增类提交
   * (聊天直发 / 文件浏览器投递)入队前校验,超限拒绝——picker 路径有
   * beginPick 挡,lightbox 路径不能绕过同一限额(review P2)。再编辑替换
   * 不占新槽位,不检查。
   */
  getRemainingAttachmentSlots: () => number;
  /**
   * 按 id 读取托盘里的已上传附件(同步真源)。再编辑时据此判断替换目标是否仍在
   * 托盘、以及底图本身是否已是标注烧录图(再编辑真相丢失时保住 annotated 标)。
   */
  getAttachment?: (attachmentId: string) => RemoteSerializedAttachment | undefined;
}

/** lightbox 已解码的源图尺寸(可选提示,仅用于烧录前预缩决策)。 */
export interface AnnotationSourceSizeHint {
  naturalWidth?: number;
  naturalHeight?: number;
}

export interface UseComposerImageAnnotationsResult {
  /** 烧录 WebView host:挂到页面任意稳定位置(无任务时为 null)。 */
  host: ReturnType<typeof useAnnotationBurnIn>['host'];
  /**
   * onUploaded 接线:标注类 candidate → 记录再编辑真相并返回打了 annotated 标
   * 的附件;其余原样返回。
   */
  decorateUploadedAttachment: (
    attachment: RemoteSerializedAttachment,
    candidate: MobileLocalAttachmentUploadCandidate,
  ) => RemoteSerializedAttachment;
  /** 聊天 lightbox 标注配置(发送到对话语义;新建会话页无聊天场景不用)。 */
  chatAnnotation: ImageLightboxAnnotationConfig;
  /** composer 托盘 lightbox 标注配置(保存 / 替换附件语义,image.key = attachmentId)。 */
  trayAnnotation: ImageLightboxAnnotationConfig;
  /** 托盘 lightbox 图源:标注附件点开显示原图(叠矢量笔迹可撤销),其余用预览。 */
  trayImageSourceUri: (attachmentId: string, previewUri: string) => string;
  /** 信箱消费入口(文件浏览器投递的标注提交):烧录 + 上传进托盘。 */
  submitExternalAnnotation: (
    displayUri: string,
    strokes: AnnotationStroke[],
    mimeType?: string,
    sizeHint?: AnnotationSourceSizeHint,
  ) => Promise<void>;
  /** 附件被移除时清理再编辑真相与源图副本。 */
  forgetAttachment: (attachmentId: string) => void;
  /** 发送成功 / 草稿整体作废时清空全部再编辑真相。 */
  forgetAllAttachments: () => void;
}

/** hook 私有源图副本目录(cache 域,系统可回收;逐附件跟随清理)。 */
const ANNOTATION_SRC_DIR = 'annotation-src';
/** 烧录产物落盘目录。 */
const ANNOTATION_BURNED_DIR = 'annotation-burned';

/** 入队后尚未落定的上传登记(candidate.uri → 本次生成的文件)。 */
interface PendingUploadRegistration {
  files: string[];
  /** 再编辑替换的目标附件:登记存在期间该附件不可再次编辑(防双重替换)。 */
  replacesAttachmentId?: string;
}

/**
 * 烧录前的源图预处理(expo-image-manipulator,已是本 App 既有原生依赖):
 * 按 plan 转码 / 预缩并落盘。动态 import 保证 node 单测可导入本模块。
 */
async function runAnnotationBurnSourcePlan(
  uri: string,
  plan: AnnotationBurnSourcePlan,
): Promise<{ uri: string; width: number; height: number }> {
  const { ImageManipulator, SaveFormat } = await import('expo-image-manipulator');
  const context = ImageManipulator.manipulate(uri);
  if (plan.resize) context.resize(plan.resize);
  const rendered = await context.renderAsync();
  try {
    const saved = await rendered.saveAsync({
      compress: plan.compress,
      format: plan.format === 'jpeg' ? SaveFormat.JPEG : SaveFormat.PNG,
    });
    return { uri: saved.uri, width: saved.width, height: saved.height };
  } finally {
    // render 结果持有原生纹理,显式释放(与 mobileImagePreprocess 同模式)。
    rendered.release();
    context.release();
  }
}

function positiveHintDimension(value: number | undefined): number | undefined {
  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.round(value) : undefined;
}

/**
 * 给模型的标注区域(与桌面同一归纳算法)。底图本身已是烧录图(再编辑真相丢失)时,
 * 旧红线的位置不可知,只描述新笔迹会让说明与图上红线不符——此时不带区域,
 * 退回固定说明。
 */
export function annotationRegionsForUpload(
  annotation: { strokes: readonly AnnotationStroke[]; baseAnnotated?: boolean } | undefined,
): Pick<RemoteSerializedAttachment, 'annotationRegions'> {
  if (!annotation || annotation.baseAnnotated) return {};
  const regions = summarizeAnnotationRegions(annotation.strokes);
  return regions.length > 0 ? { annotationRegions: regions } : {};
}

function extForMime(mimeType: string): string {
  const lower = mimeType.toLowerCase();
  if (lower === 'image/png') return 'png';
  if (lower === 'image/gif') return 'gif';
  if (lower === 'image/webp') return 'webp';
  return 'jpg';
}


async function ensureDir(dir: string): Promise<void> {
  await FileSystem.makeDirectoryAsync(dir, { intermediates: true }).catch(() => undefined);
}

export function useComposerImageAnnotations(
  options: UseComposerImageAnnotationsOptions,
): UseComposerImageAnnotationsResult {
  const { t } = useTranslation();
  const { burnIn, acquireWarm, host } = useAnnotationBurnIn();
  const metaRef = useRef<Map<string, AnnotationEditMeta>>(new Map());
  /**
   * attachmentId → 本 hook 为该附件生成的缓存文件(烧录图 / 源图副本)。
   * 附件离场(移除 / 发送 / 替换)时据此删除:截图私有副本不遗留在 app cache
   * (review P2);再编辑替换的新旧附件会共享源副本,删除前做引用检查。
   */
  const generatedFilesRef = useRef<Map<string, string[]>>(new Map());
  /**
   * candidate.uri → 已入队、尚未上传成功的生成文件登记。上传成功时迁到
   * attachment.id 名下;失败时原样保留(失败卡可重试,重试读的就是这些文件);
   * 只有上传控制器确认任务被放弃(onAbandoned)才删除。
   */
  const pendingUploadsRef = useRef<Map<string, PendingUploadRegistration>>(new Map());
  // 回调经 ref 转发:config 对象保持稳定引用,lightbox 打开期间不重建。
  const optionsRef = useRef(options);
  optionsRef.current = options;

  const srcDir = `${FileSystem.cacheDirectory}${ANNOTATION_SRC_DIR}/`;
  const burnedDir = `${FileSystem.cacheDirectory}${ANNOTATION_BURNED_DIR}/`;

  /**
   * 生成文件名用的强唯一 token:同一 hook 实例内严格递增,规避并发提交在同一
   * 毫秒内撞名互相覆盖(review P1——文件浏览器一次 focus drain 多条投递时,
   * 裸 Date.now() 存在同毫秒风险)。仍以时间戳为主体,只是叠加递增位保证唯一。
   */
  const fileSeqRef = useRef(0);
  const nextFileTag = useCallback(() => {
    fileSeqRef.current += 1;
    return Date.now() * 1000 + fileSeqRef.current;
  }, []);

  /** 是否本 hook 的私有缓存产物(只删自己生成的,绝不碰外部 file://)。 */
  const isHookGeneratedFile = useCallback(
    (uri: string) => uri.startsWith(srcDir) || uri.startsWith(burnedDir),
    [srcDir, burnedDir],
  );

  /**
   * 删除不再被任何登记(附件名下 / 在途上传 / extraKeep)引用的生成文件
   * (best-effort)。在途上传(含失败待重试)仍引用的文件绝不删除。
   */
  const deleteUnreferencedFiles = useCallback((
    files: readonly string[],
    extraKeep: readonly string[] = [],
  ) => {
    for (const file of files) {
      let referenced = extraKeep.includes(file);
      if (!referenced) {
        for (const list of generatedFilesRef.current.values()) {
          if (list.includes(file)) {
            referenced = true;
            break;
          }
        }
      }
      if (!referenced) {
        for (const registration of pendingUploadsRef.current.values()) {
          if (registration.files.includes(file)) {
            referenced = true;
            break;
          }
        }
      }
      if (!referenced) void FileSystem.deleteAsync(file, { idempotent: true }).catch(() => undefined);
    }
  }, []);

  /** 该附件是否有尚未落定的再编辑替换(上传中或失败待重试)。 */
  const hasPendingReplacement = useCallback((attachmentId: string) => {
    for (const registration of pendingUploadsRef.current.values()) {
      if (registration.replacesAttachmentId === attachmentId) return true;
    }
    return false;
  }, []);

  /**
   * 烧录源准备:Android WebView 解不了的格式先转码、已知超大图先按上传口径预缩
   * (见 planAnnotationBurnSource)。manipulator 失败、产物与提示尺寸对不上或
   * 体积超过源图上限(烧录要全量 base64 进 JS 内存)时回退原图(即既有路径)。
   * tempUri = 仅供本次烧录的中间产物,烧完即删。
   */
  const prepareBurnSource = useCallback(async (
    source: { fileUri: string; mimeType: string },
    sizeHint: AnnotationSourceSizeHint | undefined,
  ): Promise<{
    fileUri: string;
    mimeType: string;
    strokeSpace?: { width: number; height: number };
    tempUri?: string;
  }> => {
    const original = { fileUri: source.fileUri, mimeType: source.mimeType };
    const hint = {
      width: positiveHintDimension(sizeHint?.naturalWidth),
      height: positiveHintDimension(sizeHint?.naturalHeight),
    };
    const plan = planAnnotationBurnSource({
      mimeType: source.mimeType,
      platformOS: Platform.OS,
      naturalWidth: hint.width,
      naturalHeight: hint.height,
    });
    if (!plan) return original;
    try {
      const result = await runAnnotationBurnSourcePlan(source.fileUri, plan);
      const info = await FileSystem.getInfoAsync(result.uri).catch(() => null);
      const resultSize = info?.exists && typeof info.size === 'number' && Number.isFinite(info.size)
        ? info.size
        : 0;
      if (
        !isAnnotationBurnSourceResultUsable(plan, result, hint)
        || !(resultSize > 0)
        || resultSize > ANNOTATION_SOURCE_MAX_BYTES
      ) {
        void FileSystem.deleteAsync(result.uri, { idempotent: true }).catch(() => undefined);
        return original;
      }
      return {
        fileUri: result.uri,
        mimeType: plan.format === 'jpeg' ? 'image/jpeg' : 'image/png',
        ...(plan.strokeSpace ? { strokeSpace: plan.strokeSpace } : {}),
        tempUri: result.uri,
      };
    } catch {
      return original;
    }
  }, []);

  /**
   * 源副本收尾(全部来源统一过):
   * - mime 以字节魔数为准(png/jpeg/gif/webp),扩展名 / Content-Type / hint 都
   *   可能缺失或说谎——presign URL 常无扩展名,JPEG 字节标成 .png 会造成扩展
   *   名与内容不符(对齐桌面 sniffImageMime,PR #792 review P2);嗅探不出时
   *   保留 fallback,由后续「非直传格式走光栅化」兜底。
   * - 体积超附件上限直接拒绝:烧录要全量 base64 进 JS 内存,不做钳制会 OOM
   *   (上传层同口径校验只护住了直传路径)。
   */
  const finalizeSource = useCallback(async (
    fileUri: string,
    fallbackMime: string,
  ): Promise<{ fileUri: string; mimeType: string; size: number }> => {
    const info = await FileSystem.getInfoAsync(fileUri);
    const size = info.exists && typeof info.size === 'number' && Number.isFinite(info.size)
      ? info.size
      : 0;
    if (size > ANNOTATION_SOURCE_MAX_BYTES) {
      throw new Error(t('composer.upload.imageTooLargeSend', { size: Math.round(ANNOTATION_SOURCE_MAX_BYTES / 1024 / 1024) }));
    }
    const head = await FileSystem.readAsStringAsync(fileUri, {
      encoding: FileSystem.EncodingType.Base64,
      length: 16,
      position: 0,
    }).catch(() => '');
    return { fileUri, mimeType: sniffImageMimeFromBase64(head) ?? fallbackMime, size };
  }, [t]);

  /**
   * 把标注/转发源图物化成本 hook 私有的 file:// 副本。
   * data: 解析写盘;http(s) 下载;file:// 复制(已在私有目录的原样复用)。
   */
  const materializeSource = useCallback(async (
    displayUri: string,
    mimeTypeHint: string | undefined,
  ): Promise<{ fileUri: string; mimeType: string; size: number }> => {
    const dataMatch = /^data:(image\/[a-z0-9+.-]+);base64,(.+)$/i.exec(displayUri);
    if (dataMatch) {
      const mimeType = dataMatch[1].toLowerCase();
      await ensureDir(srcDir);
      const fileUri = `${srcDir}src-${nextFileTag()}.${extForMime(mimeType)}`;
      await FileSystem.writeAsStringAsync(fileUri, dataMatch[2], {
        encoding: FileSystem.EncodingType.Base64,
      });
      return finalizeSource(fileUri, mimeType);
    }
    const mimeType = (mimeTypeHint?.toLowerCase().startsWith('image/') ? mimeTypeHint.toLowerCase() : null)
      ?? imageMimeForUriFallback(displayUri);
    if (displayUri.startsWith('file://')) {
      if (displayUri.startsWith(srcDir)) return finalizeSource(displayUri, mimeType);
      await ensureDir(srcDir);
      const fileUri = `${srcDir}src-${nextFileTag()}.${extForMime(mimeType)}`;
      await FileSystem.copyAsync({ from: displayUri, to: fileUri });
      return finalizeSource(fileUri, mimeType);
    }
    if (/^https?:\/\//i.test(displayUri)) {
      await ensureDir(srcDir);
      const fileUri = `${srcDir}src-${nextFileTag()}.${extForMime(mimeType)}`;
      const result = await FileSystem.downloadAsync(displayUri, fileUri);
      if (result.status < 200 || result.status >= 300) {
        throw new Error(t('composer.attachments.downloadOriginalFailed', { status: result.status }));
      }
      return finalizeSource(fileUri, mimeType);
    }
    throw new Error(t('composer.attachments.imageNotAnnotatable'));
  }, [srcDir, finalizeSource, nextFileTag, t]);

  /**
   * 标注提交主流程(聊天发送到对话 / 托盘再编辑保存共用):
   * 有笔迹 → 烧录成位图入托盘上传(candidate 带 annotation 元数据);
   * 无笔迹 → 原图直接入托盘(聊天=转发;再编辑=撤光恢复原图)。
   * 替换语义(replaceAttachmentId)经 candidate.replacesAttachmentId 延迟到
   * 上传**成功后**(decorateUploadedAttachment)才移除旧附件——上传可能因
   * token / 网络 / 超限失败,提前删会让用户新旧两头空(review P1)。
   */
  const submitAnnotation = useCallback(async (
    displayUri: string,
    strokes: AnnotationStroke[],
    mimeTypeHint: string | undefined,
    replaceAttachmentId: string | null,
    sizeHint?: AnnotationSourceSizeHint,
  ): Promise<void> => {
    const opts = optionsRef.current;
    /** 本次提交新生成、尚未交给上传管线的文件:提交失败时回收。 */
    const createdFiles: string[] = [];
    let handedToUpload = false;
    try {
      let replaceId = replaceAttachmentId;
      if (replaceId && hasPendingReplacement(replaceId)) {
        // 同一附件已有未落定的替换(上传中 / 失败待重试):再替换一次会让两份
        // 新图都留在托盘(第二次替换找不到旧附件可删)并越过附件上限。
        throw new Error(t('composer.attachments.replacementPending'));
      }
      const replacedAttachment = replaceId && opts.getAttachment ? opts.getAttachment(replaceId) : undefined;
      if (replaceId && opts.getAttachment && !replacedAttachment) {
        // 替换目标已不在托盘:按新增处理(占新槽位,受上限约束)。
        replaceId = null;
      }
      if (!replaceId && opts.getRemainingAttachmentSlots() <= 0) {
        throw new Error(t('composer.upload.maxAttachments', { count: MOBILE_MAX_ATTACHMENTS }));
      }
      const replacedMeta = replaceId ? metaRef.current.get(replaceId) : undefined;
      // 再编辑真相丢失(恢复草稿 / 排队编辑载入等)时底图本身就是带红线的烧录图:
      // 即使本次没有新笔迹,产物仍是标注图,annotated 标不能丢(之后再次编辑同样)。
      const baseIsAnnotatedBurn = !!replaceId && (replacedMeta
        ? replacedMeta.baseAnnotated === true
        : replacedAttachment?.annotated === true);
      const sourceInputUri = replacedMeta?.sourceUri ?? displayUri;
      const source = await materializeSource(
        sourceInputUri,
        replacedMeta?.sourceMimeType ?? mimeTypeHint,
      );
      if (source.fileUri !== sourceInputUri) createdFiles.push(source.fileUri);
      const annotation = strokes.length > 0 || baseIsAnnotatedBurn
        ? {
          strokes: strokes.map((s) => ({ points: [...s.points] })),
          sourceUri: source.fileUri,
          sourceMimeType: source.mimeType,
          ...(baseIsAnnotatedBurn ? { baseAnnotated: true } : {}),
        }
        : undefined;
      let candidate: MobileLocalAttachmentUploadCandidate;
      // 非直传白名单(bmp / heic 等能显示但管线不收的格式):即使无笔迹也走
      // 烧录通道——空笔迹烧录 = 光栅化为 PNG,对齐桌面「字节可达 + 发送时
      // 光栅化」模型(PR #792),否则这类图转发会被上传层类型白名单拒收。
      const mustRasterize = !isDirectSendableImageMime(source.mimeType);
      if (strokes.length > 0 || mustRasterize) {
        const burnSource = await prepareBurnSource(source, sizeHint);
        let burned;
        try {
          const base64 = await FileSystem.readAsStringAsync(burnSource.fileUri, {
            encoding: FileSystem.EncodingType.Base64,
          });
          burned = await burnIn({
            base64,
            mimeType: burnSource.mimeType,
            strokes,
            ...(burnSource.strokeSpace ? { strokeSpace: burnSource.strokeSpace } : {}),
          });
        } finally {
          if (burnSource.tempUri) {
            void FileSystem.deleteAsync(burnSource.tempUri, { idempotent: true }).catch(() => undefined);
          }
        }
        await ensureDir(burnedDir);
        const name = strokes.length > 0
          ? annotationBurnedFileName(burned.mimeType, nextFileTag())
          : `image-${nextFileTag()}.${burned.mimeType === 'image/jpeg' ? 'jpg' : 'png'}`;
        const burnedUri = `${burnedDir}${name}`;
        await FileSystem.writeAsStringAsync(burnedUri, burned.base64, {
          encoding: FileSystem.EncodingType.Base64,
        });
        createdFiles.push(burnedUri);
        const burnedInfo = await FileSystem.getInfoAsync(burnedUri).catch(() => null);
        candidate = {
          kind: 'image',
          uri: burnedUri,
          name,
          // 尺寸 / 字节数必须带上:preprocess 只在已知长边超限时才降采样到 2048,
          // 缺失会让 4096 烧录 PNG 原样直传(review P2)。
          size: burnedInfo?.exists && typeof burnedInfo.size === 'number' ? burnedInfo.size : 0,
          width: burned.width > 0 ? burned.width : undefined,
          height: burned.height > 0 ? burned.height : undefined,
          mimeType: burned.mimeType,
          // 纯光栅化(无笔迹)不带标注元数据:托盘不显示画笔角标、不打 annotated 标。
          ...(annotation ? { annotation } : {}),
        };
      } else {
        const ext = extForMime(source.mimeType);
        candidate = {
          kind: 'image',
          uri: source.fileUri,
          name: `image-${nextFileTag()}.${ext}`,
          // 直传源无解码尺寸,至少带上真实字节数让 preprocess 的重编码判断生效。
          // (lightbox 尺寸提示只用于烧录预缩,不改变直传转发的分辨率。)
          size: source.size,
          mimeType: source.mimeType,
          ...(annotation ? { annotation } : {}),
        };
      }
      if (replaceId) candidate.replacesAttachmentId = replaceId;
      // 入队前先按 candidate.uri(强唯一)登记本次生成的文件:上传成功后
      // decorateUploadedAttachment 把登记迁到 attachment.id 下;上传失败时失败卡
      // 仍可重试,登记与文件原样保留;任务被确定放弃时由上传控制器回调
      // onAbandoned 删除(替换场景与旧附件共享的源副本经引用检查保留)。
      const ownedFiles = [...new Set([candidate.uri, candidate.annotation?.sourceUri]
        .filter((uri): uri is string => !!uri && isHookGeneratedFile(uri)))];
      const registration: PendingUploadRegistration = {
        files: ownedFiles,
        ...(replaceId ? { replacesAttachmentId: replaceId } : {}),
      };
      const registrationKey = candidate.uri;
      pendingUploadsRef.current.set(registrationKey, registration);
      candidate.onAbandoned = () => {
        if (pendingUploadsRef.current.get(registrationKey) !== registration) return;
        pendingUploadsRef.current.delete(registrationKey);
        deleteUnreferencedFiles(registration.files);
      };
      handedToUpload = true;
      opts.enqueueUploads([candidate], { token: opts.getAccessToken() });
      // 旧附件此刻不动:替换在上传成功回调(decorateUploadedAttachment)里执行,
      // 失败时旧附件与其再编辑真相原样保留,用户可重试。
    } catch (err) {
      // 系统 Alert 能盖过全屏 lightbox Modal(composer 错误条此刻被遮挡不可见);
      // lightbox 停留在标注模式,用户可重试或放弃。
      Alert.alert(t('composer.attachments.annotationSaveFailed'), err instanceof Error && err.message ? err.message : t('composer.attachments.tryAgain'));
      throw err;
    } finally {
      // 未交给上传管线就失败:本次新建的副本 / 烧录图无人引用,立即回收
      // (与既有附件共享的源副本经引用检查保留)。
      if (!handedToUpload && createdFiles.length > 0) deleteUnreferencedFiles(createdFiles);
    }
  }, [
    materializeSource,
    prepareBurnSource,
    burnIn,
    burnedDir,
    nextFileTag,
    isHookGeneratedFile,
    deleteUnreferencedFiles,
    hasPendingReplacement,
    t,
  ]);

  const decorateUploadedAttachment = useCallback((
    attachment: RemoteSerializedAttachment,
    candidate: MobileLocalAttachmentUploadCandidate,
  ): RemoteSerializedAttachment => {
    // 接手 submitAnnotation 入队前按 candidate.uri 登记的生成文件:上传成功了,
    // 把在途登记迁到 attachment.id 下。查不到登记(非本 hook 的上传)才重新计算。
    const pending = pendingUploadsRef.current.get(candidate.uri);
    pendingUploadsRef.current.delete(candidate.uri);
    const ownedFiles = pending?.files ?? [candidate.uri, candidate.annotation?.sourceUri]
      .filter((uri): uri is string => !!uri && isHookGeneratedFile(uri));
    if (candidate.replacesAttachmentId) {
      // 再编辑替换:新图上传成功,此刻才移除旧附件(见 candidate 字段注释)。
      // 顺序敏感——先把旧 meta / 旧文件登记摘掉再 removeAttachment:新旧附件
      // 共享同一个 sourceUri 副本(materializeSource 对 srcDir 内的源原样复用),
      // 若让 forgetAttachment 按旧登记清理会误删新附件仍引用的文件;旧文件中
      // 不被新附件引用的(如上一版烧录图)此刻删除。
      const oldId = candidate.replacesAttachmentId;
      const oldFiles = generatedFilesRef.current.get(oldId) ?? [];
      generatedFilesRef.current.delete(oldId);
      metaRef.current.delete(oldId);
      optionsRef.current.removeAttachment(oldId);
      deleteUnreferencedFiles(oldFiles, ownedFiles);
    }
    if (ownedFiles.length > 0) generatedFilesRef.current.set(attachment.id, ownedFiles);
    if (!candidate.annotation) return attachment;
    metaRef.current.set(attachment.id, {
      strokes: candidate.annotation.strokes,
      sourceUri: candidate.annotation.sourceUri,
      sourceMimeType: candidate.annotation.sourceMimeType,
      ...(candidate.annotation.baseAnnotated ? { baseAnnotated: true } : {}),
    });
    return { ...attachment, annotated: true, ...annotationRegionsForUpload(candidate.annotation) };
  }, [isHookGeneratedFile, deleteUnreferencedFiles]);

  const chatAnnotation = useMemo<ImageLightboxAnnotationConfig>(() => ({
    submitLabel: t('composer.attachments.sendToChat'),
    // 一级直发按钮(对齐桌面):不画笔迹也能把历史图转发进 composer 托盘。
    allowDirectSubmit: true,
    prewarm: acquireWarm,
    onSubmit: (_image, displayUri, strokes, context) =>
      submitAnnotation(displayUri, strokes, context.mimeType, null, context),
  }), [submitAnnotation, acquireWarm, t]);

  const trayAnnotation = useMemo<ImageLightboxAnnotationConfig>(() => ({
    submitLabel: t('composer.attachments.save'),
    initialStrokesFor: (image) => metaRef.current.get(image.key)?.strokes,
    // 替换上传未落定(上传中 / 失败待重试)的附件不可再编辑,防双重替换;
    // 画笔置灰,点按说明原因。
    annotationBlockedReason: (image) => (
      hasPendingReplacement(image.key) ? t('composer.attachments.replacementPending') : undefined
    ),
    prewarm: acquireWarm,
    onSubmit: (image, displayUri, strokes, context) =>
      submitAnnotation(displayUri, strokes, context.mimeType, image.key, context),
  }), [submitAnnotation, hasPendingReplacement, acquireWarm, t]);

  /**
   * 信箱消费入口:其它路由(文件浏览器 lightbox 画笔)投递的标注提交,由
   * 会话页在 focus 时逐条交给本方法——与聊天 lightbox 的直发共用同一条
   * 烧录 / 上传 / annotated 链路。
   */
  const submitExternalAnnotation = useCallback(
    (displayUri: string, strokes: AnnotationStroke[], mimeType?: string, sizeHint?: AnnotationSourceSizeHint) =>
      submitAnnotation(displayUri, strokes, mimeType, null, sizeHint),
    [submitAnnotation],
  );

  const trayImageSourceUri = useCallback((attachmentId: string, previewUri: string): string => {
    return metaRef.current.get(attachmentId)?.sourceUri ?? previewUri;
  }, []);

  const forgetAttachment = useCallback((attachmentId: string) => {
    metaRef.current.delete(attachmentId);
    // 生成文件(烧录图 / 源图副本)随附件退场(best-effort;cache 域系统兜底);
    // 先摘登记再做引用检查,替换场景共享的源副本不会被误删。
    const files = generatedFilesRef.current.get(attachmentId);
    if (!files) return;
    generatedFilesRef.current.delete(attachmentId);
    deleteUnreferencedFiles(files);
  }, [deleteUnreferencedFiles]);

  const forgetAllAttachments = useCallback(() => {
    // 只清附件名下的文件;在途上传(含失败待重试)的文件由上传生命周期回收
    // (放弃时 onAbandoned),这里删会让仍在跑 / 可重试的任务读不到源文件。
    const allFiles = [...generatedFilesRef.current.values()].flat();
    generatedFilesRef.current.clear();
    metaRef.current.clear();
    deleteUnreferencedFiles(allFiles);
  }, [deleteUnreferencedFiles]);

  // 返回对象必须引用稳定(全部成员都是 useCallback / useMemo 产物):页面把它
  // 放进 composerGalleryImages 等 useMemo 的依赖里,每 render 新对象会让托盘
  // lightbox 的 images 每帧重建、进而重置用户正在画的笔迹(review P1)。
  return useMemo(() => ({
    host,
    decorateUploadedAttachment,
    chatAnnotation,
    trayAnnotation,
    trayImageSourceUri,
    submitExternalAnnotation,
    forgetAttachment,
    forgetAllAttachments,
  }), [
    host,
    decorateUploadedAttachment,
    chatAnnotation,
    trayAnnotation,
    trayImageSourceUri,
    submitExternalAnnotation,
    forgetAttachment,
    forgetAllAttachments,
  ]);
}