48 lines
4.7 KiB
Plaintext
48 lines
4.7 KiB
Plaintext
---
|
||
title: 画布 Agent 外观与 Live2D
|
||
description: 助手名称、文案、模型导入和运行库部署
|
||
---
|
||
|
||
# 画布 Agent 外观与 Live2D
|
||
|
||
管理员在「站点及外观 → 画布配置」设置助手名称、入口文字、面板标题、欢迎标题、欢迎说明和输入提示。助手名称独立于站点品牌，例如站点为“影策”、助手为“小鱼”。文案中的 `{agentName}` 会替换为助手名称，并作为普通文本渲染。
|
||
|
||
这些字段只改变展示，不改历史对话、模型提示词、AI 自我介绍、技能或工具权限。运行中插话提示保留原有操作说明。入口文字和欢迎说明允许留空。
|
||
|
||
## 模型来源与授权
|
||
|
||
导入的是已经制作、绑定并导出的 Cubism 运行时模型包，不是立绘图片、PSD 或编辑工程。可以使用自己制作或委托制作且获得授权的模型；项目不提供一键把图片生成 Live2D 的功能。
|
||
|
||
使用前分别确认模型素材和 Cubism Core 的使用、部署与分发授权。启用后浏览器需要取得模型资源，无法承诺防下载；不应上传需要保密的素材。
|
||
|
||
## 部署运行库
|
||
|
||
前端使用固定版本 `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 渲染适配器不支持新版离屏渲染对象；此类模型会明确报错，而不是忽略对象后显示不完整形象。
|
||
|
||
## ZIP 要求
|
||
|
||
- 压缩包不超过 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 的实际兼容性由预览确认。
|
||
|
||
ZIP 作为本地 `live2d` 资源保存，不解压到磁盘。草稿只有上传者可预览；当前配置引用的模型允许其他管理员预览。只有已启用模型的指定数据文件允许公开读取。启用时服务端重新检查并决定入口，不信任客户端提供的入口路径。
|
||
|
||
## 行为与清理
|
||
|
||
- 高度可设 120–360px，画布入口按视口缩小并限制拖拽边界，保留点击打开、鼠标拖动和方向键移动。
|
||
- 渲染上限为 30fps；后台标签页及不可见预览暂停更新，减少动态效果偏好下只渲染静态形象。首期不含口型、语音联动或点击表情交互。
|
||
- 选择默认球不会删除模型引用；清除引用并保存后，可到资源管理清理。放弃未保存导入的包也可在那里清理。
|
||
- 引用中的包受资源删除保护。恢复默认外观也会恢复画布配置，但不删除文件。
|
||
- 配置存于 `system_settings` 的 `appearance` JSON（合同版本 9），不新增表或数据库迁移。一起更新前后端；降级前备份设置及资源，不用旧后台覆盖新配置。
|