feat(*): 画布助手 - 新增 Live2D 配置导入与模型渲染支持
This commit is contained in:
ddCat
@@ -5,6 +5,12 @@ description: 影策后端核心持久化表与状态边界
|
||||
|
||||
# 后端数据库
|
||||
|
||||
## 画布 Agent 外观配置
|
||||
|
||||
`system_settings` 的 `appearance` JSON 合同版本 9 新增 `canvas`：助手名称、入口标签、面板标题、欢迎文案、输入提示、`avatarType`（`orb|live2d`）、`avatarHeight`（120–360）、`live2dResourceId` 和服务端确认的 `live2dEntry`。独立于站点品牌；缺失时读取内置画布默认值。不新增数据库结构迁移，不改变全局 schema 版本。
|
||||
|
||||
模型包复用 `resources` 表，`kind=live2d`、`provider=local`，ZIP 不解压到磁盘。该 kind 仅由验证后的管理员导入路径保留，普通上传不能声明它。外观配置中的模型 ID 参与删除引用检查；清除引用不删除资源。默认球仍可保留模型引用，便于切换。
|
||||
|
||||
后端通过 GORM 管理 SQLite 与 PostgreSQL 表结构。结构变化由 `migrate-schema` 按版本顺序执行并写入 `schema_migrations`；受管生产部署在 Backend 启动前运行独立迁移服务，Backend 只校验当前 Schema 是否与二进制兼容。业务写路径必须通过 service 和 repository 的状态约束，不能直接依赖前端状态。
|
||||
|
||||
## 结构迁移与版本
|
||||
|
||||
47
docs/content/docs/backend/canvas-agent-appearance.mdx
Normal file
47
docs/content/docs/backend/canvas-agent-appearance.mdx
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
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 不包含在仓库中，不从第三方 CDN 加载，也不接受模型 ZIP 中的脚本。
|
||||
|
||||
1. 部署者从 Live2D 官方获取具有相应授权、与模型版本兼容的 Cubism SDK for Web。
|
||||
2. 将 Core 文件 `live2dcubismcore.min.js` 放到前端 `web/public/live2d/` 后重新构建；静态镜像部署也可将文件只读挂载到 `/usr/share/nginx/html/live2d/live2dcubismcore.min.js`。该文件已被 Git 忽略，不提交到本仓库。
|
||||
3. 确认同源 `/live2d/live2dcubismcore.min.js` 返回 JavaScript 而非 SPA 页面。非根路径部署跟随前端构建 BASE_URL。
|
||||
4. 后台导入并预览，成功后选择 Live2D，点击顶部「保存修改」。导入本身不启用；失败不更改当前形象。
|
||||
|
||||
没有 Core、模型不兼容、网络超时或 WebGL 上下文丢失时，入口回退默认动态球，仍可点击打开 Agent。后台显示错误并提供重试。未提供授权 Core 和真实模型时，不能仅凭构建成功认定播放验收通过。
|
||||
|
||||
接入层支持旧版 `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），不新增表或数据库迁移。一起更新前后端；降级前备份设置及资源，不用旧后台覆盖新配置。
|
||||
@@ -5,6 +5,13 @@ description: 从产品功能快速定位主要代码入口
|
||||
|
||||
# 代码功能地图
|
||||
|
||||
## 画布 Agent 配置与 Live2D
|
||||
|
||||
- 后台入口：`web/src/pages/admin/settings/appearance-settings-page.tsx` 与 `components/canvas-appearance-editor.tsx`。
|
||||
- 公共配置及文案：`web/src/stores/use-appearance-store.ts`、`web/src/lib/canvas/agent-appearance.ts`。
|
||||
- 画布形象：`web/src/components/canvas/live2d-avatar.tsx`、`canvas-cloud-agent-panel.tsx`；受限资源加载：`web/src/services/live2d-loader.ts`。
|
||||
- 服务端：`backend/internal/app/appearance_canvas.go` 校验配置，`appearance_live2d.go` 验证 ZIP、导入及资源访问；`backend/internal/handler/appearance_live2d.go` 为 HTTP 边界。已有外观设置和资源引用链路负责持久化及删除保护。
|
||||
|
||||
这是一张入口地图，不罗列所有文件。先找到功能所属层，再沿调用关系阅读。
|
||||
|
||||
## 前端页面
|
||||
|
||||
@@ -13,6 +13,18 @@ description: 信封、错误码与 OpenAPI
|
||||
|
||||
## 站点皮肤主按钮
|
||||
|
||||
### 画布配置与 Live2D（外观合同版本 9）
|
||||
|
||||
`GET /public/appearance` 和管理员 `GET /admin/settings/appearance` 返回 `canvas`；管理员通过 `PATCH /admin/settings/appearance` 随外观配置统一保存。字段为 `agentName`（1–24 字）、`launcherLabel`（0–24 字）、`panelTitle`（1–40 字）、`welcomeTitle`（1–100 字）、`welcomeDescription`（0–200 字）、`inputPlaceholder`（1–160 字）、`avatarType`（`orb|live2d`）、`avatarHeight`（120–360 整数）、`live2dResourceId`、`live2dEntry`。入口由服务端核验覆盖；Live2D 无有效资源时拒绝启用。配置不修改 Agent 系统提示词。
|
||||
|
||||
- `POST /admin/settings/appearance/live2d`：管理员 multipart `file` 上传，受上传频率和配额限制。成功信封的 `data.model` 为 `{ resourceId, entry }`，上传不会发布。ZIP 限 128 MiB、256 条目、解压合计 384 MiB、单文件 128 MiB；只接收 model3/MOC3/PNG/JSON，拒绝路径穿越、脚本和外部资源。
|
||||
- `GET /admin/settings/appearance/live2d/:id/*file`：管理员预览，校验资源归属；其他管理员仅能查看当前外观已引用模型。
|
||||
- `GET /public/appearance/live2d/:id/*file`：仅提供当前启用模型的数据文件。停用或更换后旧模型拒绝公开访问。成功为文件内容，失败为错误信封；响应带 `nosniff` 和私有、需重新验证的缓存策略。
|
||||
|
||||
管理员资源列表增加 `kind=live2d` 筛选；引用中的模型禁止删除，清除外观引用后按既有资源删除流程清理。
|
||||
|
||||
部署要求与更详细的文件限制见 [画布 Agent 外观与 Live2D](/docs/backend/canvas-agent-appearance)。
|
||||
|
||||
`GET /public/appearance` 返回当前 `activeSkin`；管理员通过 `GET/PUT /admin/settings/appearance` 读取、保存完整主题库。外观合同版本 8 新增 `tokens.buttons.light/dark`，字段为 `mode`（`solid|gradient`）、整数 `angle`（0–360）、HEX 色值 `start/end`、`hoverStart/hoverEnd`、`activeStart/activeEnd`、`foreground`。纯色模式使用既有主操作颜色，渐变仅用于主按钮。非法模式、角度、色值或修改锁定经典主题均拒绝保存；整块缺失的旧配置按主题身份补齐。此变更不增加数据表迁移。
|
||||
|
||||
## 模型规格报价
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
"defaultOpen": true,
|
||||
"pages": [
|
||||
"local-development",
|
||||
"canvas-agent-appearance",
|
||||
"http-api",
|
||||
"code-map",
|
||||
"backend-database",
|
||||
|
||||
@@ -5,6 +5,10 @@ description: 当前项目已实现的核心工作台能力与使用入口
|
||||
|
||||
# 功能清单
|
||||
|
||||
## 画布 Agent 名称、文案与形象
|
||||
|
||||
「站点及外观 → 画布配置」提供独立助手名称、入口文字、面板标题和欢迎/输入文案。支持导入授权的 Live2D Cubism 3/4 运行时 ZIP，预览后保存启用、调整高度、切回默认动态球。加载失败保留可点击的默认入口，上传和资源访问具有管理员校验和引用保护。Cubism Core 由部署者提供，真实播放待验收；不含图片自动建模或 AI 自我介绍同步。详见 [画布 Agent 外观与 Live2D](/docs/backend/canvas-agent-appearance)。
|
||||
|
||||
## 素材库分类与画布媒体链路
|
||||
|
||||
素材库支持用户手动新增、重命名和删除分类，也可以按分类或“未分类”筛选素材，并批量移动素材。删除分类不会删除素材，分类内素材会回到“未分类”。
|
||||
|
||||
@@ -5,6 +5,16 @@ description: 当前项目已实现功能的手工验证清单与未确认边界
|
||||
|
||||
# 待测试
|
||||
|
||||
## 画布 Agent 配置与 Live2D
|
||||
|
||||
- [ ] 使用约 50 MiB 的真实模型 ZIP 验收上传和预览；ZIP 上限 128 MiB，解压累计 384 MiB、单文件 128 MiB，超限须拒绝。
|
||||
- [ ] 站点仍叫“影策”，助手改为“小鱼”；保存、刷新、撤销和恢复默认后入口、面板、欢迎及输入文案正确，历史对话不改写。
|
||||
- [ ] 使用授权 Core 和真实 Cubism 3/4 模型完成预览、保存、画布播放验收。没有 Core、模型不兼容、网络超时或 WebGL 丢失时显示错误/默认球，不阻止打开对话。
|
||||
- [ ] 导入不自动启用；上传期间不可保存/刷新/恢复默认；离开未保存配置不影响线上形象；其他管理员不能预览或启用未发布草稿。
|
||||
- [ ] 未启用包不能匿名访问；启用后模型资源正常读取，切回默认球停止公开服务；引用中包无法删除，清除引用并保存后可清理。
|
||||
- [ ] 验收大模型、多次切换/打开/关闭、后台标签页、隐藏后台标签、减少动态效果、跨域 API Cookie、明暗主题、窄屏拖动和键盘移动；观察 GPU/内存释放。
|
||||
- 已用用户提供的 Shizuku 运行包和 Cubism SDK for Web 5-r.5 Core，在现有开发服务的真实 `Live2DAvatar` 组件中复现并修复绘制顺序接口异常，浏览器首帧渲染就绪。模型请求由测试拦截提供本地文件，不代表后台上传、权限、保存和画布全链路已验收；首期不含口型、语音联动、点击表情或 AI 自我介绍同步。
|
||||
|
||||
## 系统渠道模型展示标签
|
||||
|
||||
- [ ] 在系统渠道的模型编辑中添加多个标签（如“限时特价”“官方1折”），选择不同颜色，保存并重新打开后文字、颜色及顺序保持一致；删除全部标签后前台不再显示。
|
||||
|
||||
Reference in New Issue
Block a user