# 外置人物使用说明

当前版本支持本地人物库。首次安装后重启 DSH；之后导入或切换人物不需要重启或重新打包。

## 添加和切换

1. 右键桌宠，打开「人物形象…」。
2. 点击「添加 GIF / PNG」，选择本机图片；或选择含 `character.json` 的角色目录。
3. 在预览中选择待机、思考、工作等状态检查动作。蓝点代表气泡应出现在头顶的位置，橙线代表脚底位置；可调整名称和标记位置。
4. 点击「导入并使用」。导入过程可取消，完成前当前桌宠继续工作。
5. 人物列表中选中已导入人物，点击「使用此人物」即时切换。「恢复默认」恢复内置形象；「移除人物」仅移除导入副本，不删除来源文件。

人物仅改变外观，不改变对话、模型或 Agent。单个 GIF 会在各状态中循环播放，真实状态由气泡即时显示；GIF 原有有限循环次数不影响状态循环。静态 PNG 不播放动画。

## 多状态目录

最简单的目录包含 `character.json` 和 `idle.gif`：

```json
{
  "characterFormatVersion": 1,
  "name": "我的人物",
  "statusAnchor": { "x": 0.5, "y": 0.12 },
  "baseline": 0.95,
  "actions": {
    "idle": { "type": "gif", "file": "idle.gif" }
  }
}
```

`idle` 必须存在。可以在 `actions` 中添加 `thinking`、`working`、`thinking-working`、`responding`、`waiting`、`question`、`success`、`error`、`disconnected`，缺少的状态使用本人物的 idle。每个动作选择以下一种形式：

```json
{ "type": "gif", "file": "working.gif" }
```

```json
{ "type": "png", "file": "working.png" }
```

```json
{
  "type": "png-sequence",
  "frames": ["working/001.png", "working/002.png"],
  "frameDurationMs": 100
}
```

文件名使用 ASCII 字母、数字、短横线或下划线，目录分隔符使用 `/`；不能使用绝对路径、网络路径、`..`、设备名或跨角色引用。同一角色所有动作的逻辑画布尺寸须相同，PNG 序列每帧同尺寸。外置首版每状态一段循环动作，不支持 enter/transition、多 Clip 编辑或 ZIP 导入。

## 素材限制

- 单文件最多 20 MiB，单角色输入合计最多 100 MiB；清单最多 64 KiB。
- 原图每边最多 2,048 像素；每动作最多 240 帧，每角色最多 1,024 帧，合计完整画布像素最多 2.56 亿。
- 导入时等比缩小至最长边 512 像素，底部对齐补齐方形透明画布，小图不放大。所有帧重新编码为 PNG，保留原有背景；不会自动抠图。
- GIF 保留不同帧的延迟，零/缺失延迟使用 100 ms，短于 20 ms 的延迟使用 20 ms，单帧长于 10 秒拒绝；PNG 序列固定间隔为 16–1,000 ms。
- 人物名称最多 40 字符；最多 50 个外置人物，人物库合计最多 1 GiB（含导入暂存），单角色生成文件最多 256 MiB。达到限制后须主动移除不需要的人物，不会自动删除已导入人物。
- 不支持网络盘、符号链接、目录联接、脚本或可执行素材。损坏或超限素材会给出固定错误提示，不显示来源路径。

## 存储与恢复

素材保存在 `%LOCALAPPDATA%\DshPngPet\Characters`，独立于源码、插件安装目录和 DSH 数据。原图、原路径和无关元数据不保存，只保留规范化 PNG、必要人物信息与选择 ID。不要手动编辑人物库内部清单；需要变更时重新导入来源素材。

插件升级不删除人物库。当前 Windows 用户的多个 Helper 共用人物库及最后一次保存的选择；运行中的其他 Helper 不主动同步外观，新启动时读取选择。人物选择不进入 DSH 网页设置或 stdin/stdout 协议。

切换失败时保留当前人物；运行中使用的人物损坏时恢复内置人物。未完成或取消导入时清理本次暂存目录；Helper 被强制结束可能留下 staging 暂存文件，计入总配额，不会被当作可用人物展示。