docs(frame-animation): 补充共享 Sprite 与 Actor 接入文档

Docs/FrameAnimationActor接入说明.md

@@ -0,0 +1,47 @@
+# FrameAnimation Actor 接入说明
+
+帧动画角色通过 `ActorManager` 的显式 `FrameAnimation` 类型接入。旧的 `Sprite`、`Anima`、`AnimaEx` 行为不变。
+
+## 资源约定
+
+1. 为角色制作并校验 `FrameAnimationGraph`。
+2. 将 Graph 加入对应场景的 Addressable Group，地址必须是：
+
+   ```text
+   FrameAnimation/{actorName}
+   ```
+
+   例如角色名为 `测试角色`，Graph 地址就是 `FrameAnimation/测试角色`。
+3. 通用角色 Prefab 使用 `Prefab/FrameAnimationActor`，由框架持久化加载；角色 Graph 由当前场景的 `ResourceSystem` 加载并随场景释放。
+
+Graph 必须通过 `FrameAnimationGraphValidator` 校验。帧动画角色不会自动播放 `defaultPlayableId`，初始化后等待剧情或业务代码明确指定 playable。
+
+## Yarn 用法
+
+初始化时显式传入类型：
+
+```yarn
+<<init_actor 测试角色 clinic FrameAnimation>>
+<<change_actor_state Idle 测试角色>>
+```
+
+等待一次性动画播放完成：
+
+```yarn
+<<change_actor_state_async Intro 测试角色>>
+```
+
+`init_actor` 会等待 Prefab 和 Graph 加载完成，因此紧随其后的状态切换可以安全执行。Loop playable 的 Handle 不会自然完成，Loop 必须使用 `change_actor_state`，不要使用异步命令。
+
+## 存档行为
+
+帧动画角色复用 `sections["actor"]`，保存角色类型、名称、槽位、透明度和当前 playable id，不记录中途帧进度。
+
+读档时：
+
+- `HoldLastFrame`：直接显示最后一帧；
+- `Clear`：清空 Sprite；
+- `HideTarget`：禁用 SpriteRenderer；
+- `Loop`：从第一帧重新开始播放，且不会阻塞读档恢复流程。
+
+如果 Prefab、Graph 或 playable 缺失，该角色会被跳过并输出结构化错误日志，不会覆盖 ActorManager 中已有的同名有效角色，也不会阻断其他存档 Provider。

Docs/FrameAnimationActor接入说明.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 0e1fa1a6e25c4d24b548c9b9bcf54df8
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Docs/帧动画系统第一二阶段手动测试.md

@@ -296,6 +296,30 @@
 - rect/pivot 更新为 JSON 和 ImportSource 设置。
 - JSON 中消失的 frameName 对应旧 SpriteRect仍保留。
 
+### IMP-08A 合并帧共享 Sprite（P0）
+
+操作：
+
+1. 使用包含多个 SourceFrame 指向相同 `frame.x/y/w/h` 的 Aseprite JSON。
+2. 确认来源设置为 `manageSpriteSlicing = true`，点击 `Preview Source`。
+3. 检查来源摘要中的逻辑帧、SpriteSlot 和共享别名数量。
+4. 确认刷新后检查对应 Imported Clip 的帧表和 Sprite引用。
+5. 再次执行 Preview 和 Refresh。
+
+佩佩素材的预期统计：
+
+- 347 个逻辑 SourceFrame。
+- 205 个唯一 SpriteSlot。
+- 142 个共享别名。
+
+预期：
+
+- 相同 rect 只创建一个有效 SpriteRect。
+- 不同 SourceFrame仍保留各自的 frameName、sourceIndex、duration 和 Tag顺序。
+- 指向同一 rect 的 Clip Frame直接引用同一个 Unity Sprite。
+- 第二次 Preview 中 SpriteSlot 和 Clip均显示 Unchanged，Sprite ID保持稳定。
+- 原始 PNG 和 JSON不被修改。
+
 ### IMP-09 多写入所有者冲突（P0）
 
 操作：
@@ -409,6 +433,7 @@
 - 用户拥有字段不会被刷新覆盖。
 - 只读来源绝不修改 TextureImporter。
 - 自动切图为同名 frameName 保留稳定 Sprite ID。
+- 合并帧只创建唯一 SpriteSlot，同时保留全部逻辑帧时长与播放顺序。
 - 多写入所有者、素材错误和命名冲突能够阻断刷新。
 - 单来源和全部来源刷新都不产生部分 Graph/Clip 更新。
 - 保存、Undo/Redo 和重新打开 Unity 后资产引用保持稳定。