media-images-and-files

用途

本技能用于在 React Native（Expo SDK 57）应用中规范地展示、选择、拍摄、存储和分享图片与文件。它提供一套架构规则、模板代码和检查工具，帮助开发者避免常见的内存、权限、缓存和文件管理问题。

主要能力与规则

• 图片展示：所有内容图片必须使用 expo-image 并包裹在有尺寸的容器中，使用 contentFit 而非 resizeMode；为图片添加无障碍名称或标记为装饰性；在回收列表中设置 recyclingKey；根据图片来源选择合适的缓存策略（存储文件用 memory，公开远程图片用磁盘缓存，私有图片仅内存或登出时清除）。
• 选图与拍摄：只能通过用户按压触发，且通过 MediaPickerPort 进行；仅接受图片，不使用 base64，不保留 EXIF；相机打开前必须经过权限门（permissions 模块），仅在 src/services/permissions/ 中请求权限；应用配置中只声明实际使用的权限，避免多余权限。
• 存储与处理：每张选中的图片在存储前统一缩小并重新编码一次（长边 2048px，JPEG 质量 0.8），逐张处理，图片字节不进入 JS 堆。文件保存在 media store（Paths.document/media/）中，记录中保存 MediaRef（纯文件名），渲染时通过 uriOf(ref) 解析。绝不覆盖已有文件，更改图片生成新文件。删除时先删除记录再删除文件，启动后及恢复后执行孤儿文件清扫。
• 分享与传输：图片仅通过端口离开设备，且由用户按压触发：分享面板（ShareSheetPort）、保存到相册（PhotoSaverPort）、上传下载（FileTransferPort）。上传使用 src/api 中的 URL 和会话头。

使用方式

1. 阅读参考文档：displaying-images.md、picking-and-capturing.md、files-and-storage.md、sharing-and-transfer.md、testing-and-checker.md。
2. 安装依赖：npx expo install expo-image-picker expo-image-manipulator expo-file-system expo-device expo-crypto（SDK 57 版本已在资料中列出）。
3. 复制模板：templates/src/core/media/、templates/src/services/{media-picker,media-store,image-resizer}/、templates/src/data/media/、templates/src/ui/media/。
4. 在 app.config.ts 中设置 picker 插件选项，仅声明实际使用的权限。
5. 组合适配器：在 createDeviceServices 中配置三个适配器，使用 isCameraAllowed 和 isCameraPresent 检查相机权限与设备；创建 createMediaImporter。
6. 启动时先 await importer.importPendingPick()，再执行 sweepMedia(...)，恢复后再清扫一次。
7. 使用 MediaRef 字段存储引用，通过迁移添加 *_ref TEXT 列。
8. 参考示例实现功能：examples/src/features/tasks/ 中的 model hook、jobs 和 photo strip。
9. 运行测试：npx jest src/core/media src/services/media-picker src/services/media-store src/services/image-resizer src/data/media src/ui/media --ci 和 npm run typecheck。
10. 运行检查脚本：node ${CLAUDE_SKILL_DIR}/scripts/check-media.mjs .，修复所有 FAIL 直至输出 RESULT: PASS。

适用场景

适用于 Expo React Native 应用中需要处理图片、头像、附件、上传、保存到相册等功能的场景，尤其需要保证权限合规、内存安全、文件一致性和隐私保护的项目。

限制与注意事项

• 仅使用 SDK 57 的新 API（File/Directory/Paths 和 expo-media-library 对象 API），不使用旧版主入口函数或 /legacy 条目，因为旧函数在 SDK 57 中运行时抛出异常。
• 不存储 asset.uri（缓存文件会被系统清除且路径可能变化），不将图片转为 base64，不在 useEffect 中打开选择器，不在屏幕中直接请求相机权限，不覆盖已存储文件，不先删文件再删记录，不分享原始图片（含 GPS 信息），不在列表中使用 allowDownscaling={false} 或 contentFit="none"。
• 如果应用没有媒体代码，检查脚本会输出 NOT APPLICABLE；在 app.config.ts 创建前可能输出 SKIP。
• 适配器更改后需在 iOS 模拟器和 Android 模拟器上运行媒体演练，否则需在报告中说明待完成。
• 部分细节（如性能预算的具体数值、设备测试步骤）需参考关联技能或文档，本资料未完全展开。