docs(dev): 📝 document snapshot attachment layers

Author: mcthesw

ROADMAP.md

@@ -15,7 +15,8 @@
 - [ ] **Archive-stream Hook trait**：在压缩/解压流内部插入自定义逻辑，与业务生命周期 hooks 分层
 - [x] **整体存档 hash 与恢复前校验**：可选生成 archive hash，并在恢复前阻止损坏存档被应用
 - [ ] **Unix 权限保存**：利用 ZIP 格式原生的 Unix 权限字段保存和恢复文件权限
-- [ ] **快照截图**：在创建快照时嵌入游戏截图
+- [x] **外部扩展附件目录**：为快照扩展保留 `save_data/<game>/extra_info/<extension>/` 路径边界，扩展目录自行维护 manifest，避免频繁读取 zip 或膨胀 `Backups.json`
+- [ ] **快照内嵌扩展数据**：对确实需要随 archive 原子迁移的附件，放入 `__rgsm__/` 或后续 archive-stream 扩展中
 
 ### 云同步大幅优化
 
@@ -45,5 +46,5 @@
 ## V3.0（远期展望）
 
 - [ ] 存档导入 / 导出
-- [ ] 高级插件系统
+- [ ] 高级插件系统：插件可接入 lifecycle hooks，并按读取频率选择附件层级：ZIP 内 `__rgsm__/`（随压缩包迁移、低频读取）、`Backups.json` 简短字段（如 hash/小型索引）、`extra_info/<extension>/` 外部扩展目录（截图等可独立读写的大对象；当前截图预览是 GUI 内置扩展）
 - [ ] 存档云共享平台（可能需要脚本系统支持存档适配）

doc/en/README.md

@@ -62,6 +62,16 @@ The software is divided into two main parts:
 - Do not construct OpenDAL operators in IPC handlers; call cloud-sync facade functions instead.
 - Put transfer logic in `cloud_sync/transfer.rs` and keep workflow orchestration in `cloud_sync/utils.rs`.
 
+### Snapshot Metadata and Attachment Layers
+
+Snapshots may need more than the zip archive itself: integrity data, generated indexes, and future plugin-generated context all have different access patterns. Keep extension data in one of three Snapshot-related layers:
+
+- **Inside the archive**: data that should travel with the Snapshot and is only read occasionally, usually during restore or inspection. Future archive extensions should use a reserved directory such as `__rgsm__/` so user Save Unit paths stay clean.
+- **Small `Backups.json` fields**: compact metadata that the app reads frequently, such as `archive_hash`, creation source, lightweight indexes, or fields needed for sorting and filtering. Do not put large objects or plugin-private payloads here.
+- **External attachment directories**: larger data that may be read or written independently from the archive. Use `save_data/<game>/extra_info/<extension>/`, with each extension owning its own `manifest.json`. Core only provides the safe path boundary for `extra_info/<extension>`; each extension owns its schema.
+
+When the future plugin system attaches to lifecycle hooks, plugins should choose one of these Snapshot-related layers based on how their data is read and migrated. GUI-built extension features should use the same boundaries instead of becoming core Snapshot fields. Plugin-owned configuration, caches, account state, and other non-Snapshot data are a separate concern and should get their own storage design later.
+
 ## Development Process
 
 To contribute to the Game-save-manager project, you need to:

doc/zh-CN/README.md

@@ -62,6 +62,16 @@
 - IPC 层不要直接构造 OpenDAL Operator，应调用 cloud-sync facade。
 - 传输逻辑放在 `cloud_sync/transfer.rs`，流程编排放在 `cloud_sync/utils.rs`。
 
+### Snapshot 相关数据与附件分层
+
+Snapshot 除了 zip 压缩包本身，还可能需要挂接校验信息、生成索引、未来插件生成的上下文等数据。为避免把不同读写频率的数据混在一起，扩展数据按访问模式分三层：
+
+- **压缩包内部**：适合随 Snapshot 一起迁移、低频读取、恢复时才需要的数据。未来扩展应使用 zip 内的保留目录（例如 `__rgsm__/`）存放，避免污染用户的 Save Unit 路径。
+- **`Backups.json` 简短字段**：适合高频读取的小型元数据，例如 `archive_hash`、创建来源、轻量索引或 UI 需要直接排序/筛选的字段。这里不应放大对象或插件私有大块数据。
+- **外部附件目录**：适合需要单独读写、可能频繁访问、体积较大的数据。当前约定放在 `save_data/<game>/extra_info/<extension>/` 下，并由扩展目录维护自己的 `manifest.json`。Core 只提供 `extra_info/<extension>` 的安全路径边界；具体 schema 由扩展自己维护。
+
+未来插件系统接入 lifecycle hooks 后，插件可以根据数据需求选择上述 Snapshot 相关层级。GUI 内置扩展功能也应复用这些边界，而不是扩张成 core 的 Snapshot 字段。插件自身的配置、缓存、账号状态等不属于 Snapshot 附件，后续应另行设计插件数据目录。
+
 ## 开发流程
 
 若要为 Game-save-manager 项目做出贡献，你需要：