feat: 灵动岛支持本地自定义动画角色包（兼容 Codex / Petdex 格式）

## 使用场景 / Use case

Cindy 灵动岛目前提供多个内置角色皮肤。这些角色由 Desktop 内置素材和原生渲染配置共同维护，新增角色需要随 Cindy 版本一起发布。

Codex / Petdex 已经形成了相对稳定的动画宠物包格式：

- `pet.json`
- `spritesheet.webp` 或 `spritesheet.png`

Petdex 也已经积累了较多角色素材和配套创作工具。如果灵动岛能够兼容这种本地角色包，用户可以复用已有宠物与创作生态，Cindy 也不必重新定义和维护另一套宠物素材格式、CLI 与分发系统。

相关资料：

- [Petdex 项目与宠物包格式](https://github.com/crafter-station/petdex)
- [Petdex manifest](https://petdex.crafter.run/api/manifest)

## 当前问题 / Current limitation

当前灵动岛角色是宿主内置的固定集合，外部动画角色包不能进入现有 Agent Island 渲染路径。

如果 Cindy 自己重新建设宠物格式、素材市场、安装 CLI 和创作工具，会与已经存在的 Codex / Petdex 生态重复；但直接嵌入 Petdex Desktop 或它的 Agent sidecar，又会产生第二个悬浮宠物窗口，并模糊 Cindy 对会话状态和权限语义的所有权。

## 期望方案 / Proposed solution

想先确认一个产品方向：

> 灵动岛是否愿意开放“本地自定义动画角色包”能力，并优先兼容 Codex / Petdex 的宠物包格式？

这里建议复用的是宠物包格式和素材生态，而不是把 Petdex Desktop 或它的 Agent sidecar 嵌入 Cindy。

Cindy 继续掌握会话状态、权限提醒和完成状态等产品语义；外部宠物包只提供角色素材与动画，不参与 Agent 状态判断，也不能控制 Cindy。

### 第一阶段建议范围

第一阶段只考虑本地、用户主动触发的导入路径：

- 用户在设置中手动选择一个本地宠物包；
- Desktop Main 进程负责校验 `pet.json`、真实图片类型、尺寸、容量和图集结构；
- 通过校验的素材进入 Cindy 受控的本地媒体存储；
- macOS Agent Island helper 负责加载和渲染动画图集；
- 当前 `SpriteMascotView` 不是逐帧图集播放器，不能直接用于 Petdex；原生 helper 需要新增独立 atlas renderer，同时保留现有内置角色渲染路径；
- 同一个图集只解码一次，并由宿主控制动画帧率和缓存生命周期；
- 宠物包损坏、缺失或被删除时，确定性回退到内置角色；
- 已有内置角色、默认角色和用户设置保持兼容。

初步状态映射可以考虑：

| Cindy 灵动岛状态 | Codex / Petdex 动画 |
|---|---|
| `idle` | `idle` |
| `working` | `run` |
| `waitingApproval` | `review` |
| `completed` | `wave` |

具体映射可以在产品方向认可后再结合实际动画效果确认，不必在本 Issue 中定死。

### 复用边界

可以直接复用：

- Codex / Petdex 宠物包格式；
- 已有宠物素材与创作者生态；
- Hatch Pet 等现有创作工具；
- 用户本机已经拥有的兼容宠物包。

Cindy 仍需负责：

- 本地文件和图片安全校验；
- 受控存储与删除生命周期；
- Cindy 状态到动画状态的映射；
- macOS 原生 SwiftUI / sprite atlas 渲染；
- 小尺寸可读性、性能与异常回退；
- 默认角色和历史设置的向后兼容。

这样可以避免重复实现已有的素材规格、宠物市场、安装 CLI 和创作工具，同时保持灵动岛的宿主安全边界。

### 相关适配经验

我在自己的 AI Agent 桌宠项目 **Octobao 八宝**中，已经实践过本地 Petdex 角色包适配，包括：

- 声明式发现本地宠物包；
- 将宿主 Agent 状态映射到宠物动画；
- 动画状态缺失时确定性回退；
- 用户选择持久化；
- 本地包变化后的实时刷新；
- 不同角色素材的显示尺寸校准。

这段实践让我更倾向于复用已有宠物包协议和素材生态。对 Cindy 而言，这仍是一项独立的宿主能力：需要新增受控导入、包生命周期、持久化和真正的 atlas renderer，不能简化为把外部文件接入现有 skin 列表。

- 项目介绍与发布：[Octobao GitHub](https://github.com/jiajiayao/Octobao)
- 产品网站：[Octobao 官方网站](https://octopus-agent-companion.jiajiayaoabc.chatgpt.site/)

Octobao 的 Android、Windows/macOS 渲染实现不能直接移植到 Cindy 的原生 Agent Island helper；这里可以复用的是实际适配经验、状态映射方法和异常回退边界。

Octobao 当前公开的 Early Preview 早于上述 Petdex 适配；相关适配仍处于开发及许可/打包验收阶段，因此这里不把它描述为已经公开交付的功能。

## 已考虑的替代方案 / Alternatives considered

### 1. 在 Cindy 中重新建设完整宠物平台

不建议。它会重复建设宠物格式、素材市场、安装 CLI 和创作工具，并扩大长期维护范围。

### 2. 直接运行 Petdex Desktop sidecar

不建议作为灵动岛集成。它会产生独立悬浮窗口，并让同一 Agent 状态出现两套展示和生命周期。

### 3. 第一阶段直接接入 Petdex 在线图库

暂不建议。远程图库会立即引入网络访问、版权声明、下架、缓存、离线、更新和地域可用性问题。更适合作为本地包能力稳定后的独立后续讨论。

### 第一阶段明确不包含

- Petdex 在线图库或搜索界面；
- Petdex 账号、登录或投稿；
- 自动下载、自动更新和远程素材热加载；
- Petdex CLI 的重新实现；
- Petdex Desktop sidecar 或第二个悬浮宠物窗口；
- 允许宠物包执行代码、脚本或网络请求；
- 改变 Cindy 现有会话状态机；
- 改变默认灵动岛角色；
- Mobile 或 Windows 上的灵动岛能力。

宠物素材的版权仍归各自提交者或权利人。第一阶段只处理用户主动导入的本地文件，不把 Petdex 图库素材直接打包或重新分发到 Cindy 安装包中。

## 希望确认

在进一步设计或提交代码前，想先确认：

1. 是否认可灵动岛支持本地自定义动画角色包这个产品方向？
2. 是否可以把 Codex / Petdex 包格式作为第一个兼容格式？
3. 第一阶段是否应保持“仅本地手动导入”，暂不接远程图库？
4. 如果产品方向认可，下一步先做兼容性 spike，基于真实 8×9、8×11、PNG/WebP 样例确认行顺序、帧数、循环时长、状态回退和失败测试矩阵，再决定功能 PR 的拆分方式。

@dashhuang 想先请你确认一下产品方向，不着急实现。

No repository files or tests are named. After product direction is approved, start by inspecting Desktop Main, SpriteMascotView, and the macOS Agent Island helper, then run a compatibility spike with real 8×9 and 8×11 PNG/WebP samples. Done means the import scope, atlas format, state fallbacks, and failure-test matrix are agreed before splitting implementation work.

Written by the indexing model from the issue text.