用途：在 AdonisJS 应用中管理文件上传，并基于命名转换器生成派生变体（缩略图、预览、格式转换）。上传由 @jrmc/adonis-attachment 处理，存储走 Drive（本地 fs，生产可用 S3 系列），由 DRIVE_DISK 环境变量选择磁盘。
主要能力：在 Lucid 模型上用 @attachment({ preComputeUrl: false, variants: [...] }) 声明附件字段并标注为 Attachment 类型；转换器定义在 config/attachment.ts 的键值记录中，声明 resize、format 等选项，variants 名称引用这些键；通过 declare module '@jrmc/adonis-attachment' 做声明合并，使 TypeScript 识别变体键。
使用方式：用 VineJS 校验上传，如 avatar: vine.file({ extnames: ['png','jpg','jpeg','gif'], size: 1 * 1024 * 1024 }).nullable()；在 action 中接收 MultipartFile 并调用 attachmentManager.createFromFile(file) 赋值；迁移中为附件元数据添加 JSON 列，如 table.json('cover').nullable()；序列化前调用模型静态方法 preComputeUrls(rows) 预计算 URL，再交给 Transformer；Transformer 通常用 variant.url ?? this.resource.<remoteUrl> 提供回退 URL。
适用场景：需要上传文件并生成多种尺寸或格式变体的 AdonisJS 项目，配合 Inertia 前端渲染。
限制与注意：preComputeUrl: false 保持模型读取轻量，URL 按需计算；若跳过 preComputeUrls 直接序列化，变体 URL 会返回 undefined。修改 config/attachment.ts 后已有上传不会自动重新处理，需手动重跑。避免在 React 组件中直接读取 user.avatar.url，应通过 Transformer 辅助方法；不要绕过 attachmentManager.createFromFile 直接赋值；校验器必须设置大小限制以防超大上传。测试可用真实小 PNG 夹具配合 API 客户端的 .file(...)，并用 drive.fake() 与 disk.assertExists(...) 断言。
参考：包 README https://github.com/batosai/adonis-attachment ；AdonisJS Drive https://docs.adonisjs.com/guides/digging-deeper/drive ；VineJS 文件校验 https://vinejs.dev/docs/types/file 。