画布 Agent 外观与形象Copy Anchor Link

管理员在「站点及外观 → 画布配置」设置助手名称、入口文字、面板标题、欢迎标题、欢迎说明和输入提示。助手名称独立于站点品牌，例如站点为“微昕·砚”、助手为“小鱼”。文案中的 {agentName} 会替换为助手名称，并作为普通文本渲染。

助手名称同时用于界面文案和 AI 自我介绍。服务端在每个新回合从同一份外观配置读取名称，将其作为 JSON 名称数据加入内置身份规则；站点品牌、模型供应商、个人设定和历史回复中的旧名称不覆盖它，也不将名称解释为行为指令。

保存后当前页面立即更新，其他已打开页面在重新获得焦点、切回前台或刷新时读取最新配置；刷新失败保留已有名称。新对话和已有对话的后续回合使用新名称，正在执行的回合保留创建时的身份快照，历史消息不重写。其他文案字段仍只改变展示，技能和工具权限不变。运行中插话提示保留原有操作说明。入口文字和欢迎说明允许留空。

模型来源与授权Copy Anchor Link

画布入口支持默认动态球、状态动画包和 Live2D。默认状态动画包来自 web/public/doll/avatar.json 与其中引用的 MP4；管理页为 Agent 的待命、排队中、运行中、等待审批、已完成、异常、已停止和已拒绝 8 个运行状态分别配置动画，且每项都可选择包内任一 clip。公开视频使用 manifest 的宽高比，客户端对 MP4 逐帧去除绿色背景，活动状态循环播放，终态动画播放一次后停在末帧。媒体层不拦截入口拖动。

动画包在「站点及外观 → 画布配置」导入。ZIP 须在根目录提供 avatar.json 和 manifest 引用的 MP4。JSON 使用 version、width、height 与 clips 字段；clips 的键是动画名，值是根目录 MP4 文件名。导入只创建资源草稿，不自动启用；保存 avatarBundleResourceId 和 avatarClipStates 后才公开播放。未启用包只允许上传者预览，当前配置引用的包可供管理员预览；配置引用的动画包受资源删除保护。恢复内置动画包或切换动态球不会删除已上传文件，解除配置引用后可按资源管理流程清理。

导入的是已经制作、绑定并导出的 Cubism 运行时模型包，不是立绘图片、PSD 或编辑工程。可以使用自己制作或委托制作且获得授权的模型；项目不提供一键把图片生成 Live2D 的功能。

使用前分别确认模型素材和 Cubism Core 的使用、部署与分发授权。启用后浏览器需要取得模型资源，无法承诺防下载；不应上传需要保密的素材。

部署运行库Copy Anchor Link

前端使用固定版本 pixi.js@6.5.10 和 pixi-live2d-display@0.4.0，按需加载 Cubism 3/4 渲染适配器。Cubism Core 已纳入仓库的 web/public/live2d/live2dcubismcore.min.js，随前端构建及静态镜像发布，无需部署者另行安装。不从第三方 CDN 加载，也不接受模型 ZIP 中的脚本。Core 保留原始版权与许可声明，不适用本项目的 MIT 许可证；参见同目录 NOTICE.txt。

1. 使用前确认 Live2D SDK 及模型素材的适用授权；内置运行库不代替部署者对使用场景的授权确认。
2. 拉取包含运行库的提交并重新构建前端，或部署由该提交构建的新镜像。Vite 将 Core 复制到 dist/live2d/live2dcubismcore.min.js，Docker 镜像中对应 /usr/share/nginx/html/live2d/live2dcubismcore.min.js。旧镜像不会因拉取源码自动更新；已有同路径挂载时应检查是否遮蔽内置文件。
3. 确认同源 /live2d/live2dcubismcore.min.js 返回 JavaScript 而非 SPA 页面。非根路径部署跟随前端构建 BASE_URL。
4. 后台导入并预览，成功后选择 Live2D，点击顶部「保存修改」。导入本身不启用；失败不更改当前形象。

部署产物遗漏 Core、模型不兼容、网络超时或 WebGL 上下文丢失时，入口回退默认动态球，仍可点击打开 Agent。后台显示错误并提供重试。未使用具有适用授权的真实模型验证时，不能仅凭构建成功认定播放验收通过。

接入层支持旧版 drawables.renderOrders 和新版 Core 的 Model.getRenderOrders() 绘制顺序接口，不修改 Core 文件。当前 Cubism 4 渲染适配器不支持新版离屏渲染对象；此类模型会明确报错，而不是忽略对象后显示不完整形象。

状态动画 ZIPCopy Anchor Link

• 压缩包最大 128 MiB，解压总量最大 384 MiB，最多 128 个条目；单个 MP4 最大 64 MiB，JSON 最大 2 MiB，最多 64 个 clip。
• avatar.json 须位于根目录，结构示例：

{
  "version": 1,
  "width": 480,
  "height": 432,
  "clips": {
    "idle": "mascot-idle.mp4",
    "working_loop": "mascot-working-loop.mp4",
    "think": "mascot-think.mp4",
    "wave": "mascot-wave.mp4",
    "wipe_sweat": "mascot-wipe-sweat.mp4"
  }
}

• width 和 height 范围为 1–4096；动画名只能包含英文字母、数字、下划线和连字符。每个 clip 必须引用唯一的根目录 MP4，ZIP 中不允许未引用视频或其他用户文件。.DS_Store 与 macOS __MACOSX 元数据会忽略。
• 不允许路径穿越、嵌套文件、软链接、重复或大小写冲突的文件名。后端会检查 manifest、ZIP 边界和 MP4 文件头；实际画面和动作映射应在管理页预览确认。

ZIP 保存在本地资源目录，不解压到磁盘；浏览器只可读取当前启用包中的 manifest 和 MP4，支持 MP4 Range 请求。

Live2D ZIP 要求Copy Anchor Link

• 压缩包不超过 128 MiB，解压累计不超过 384 MiB，最多 256 个条目；单文件不超过 128 MiB，JSON 不超过 2 MiB。
• 只能有一个 *.model3.json，Version 为 3，所有引用必须位于 ZIP 内且使用规范相对路径。
• 包含 .moc3 和 1–8 张 PNG 纹理；单张不超过 4096 × 4096，包内纹理总像素不超过 32 Mi 像素。
• 可带动作、表情、物理、姿势等 JSON；不支持 Cubism 2、音频引用、脚本和编辑工程。请移除 README、缩略 JPEG、系统隐藏文件等无关文件后打包。
• 不允许外部 URL、路径穿越、软链接或大小写冲突的路径。后端验证结构和边界；MOC3 与 Core 的实际兼容性由预览确认。

Live2D ZIP 作为本地 live2d 资源保存，不解压到磁盘。草稿只有上传者可预览；当前配置引用的模型允许其他管理员预览。只有已启用模型的指定数据文件允许公开读取。启用时服务端重新检查并决定入口，不信任客户端提供的入口路径。

行为与清理Copy Anchor Link

• 高度可设 120–360px，画布入口按视口缩小并限制拖拽边界，保留点击打开、鼠标拖动和方向键移动。
• 渲染上限为 30fps；后台标签页及不可见预览暂停更新，减少动态效果偏好下只渲染静态形象。首期不含口型、语音联动或点击表情交互。
• 选择默认球不会删除模型引用；清除引用并保存后，可到资源管理清理。放弃未保存导入的包也可在那里清理。
• 引用中的包受资源删除保护。恢复默认外观也会恢复画布配置，但不删除文件。
• 配置存于 system_settings 的 appearance JSON（合同版本 11），不新增表或数据库迁移。一起更新前后端；降级前备份设置及资源，不用旧后台覆盖新配置。