dsh-live2d-companion` 本插件声明了 `dsh.bundle` 清单，`dsh plugin add` 会自动登记为 profile 组合层，无需手动接线。 2.（可选）调整开关默认网页挂件开、桌宠关。要改就在 `$env:USERPROFILE\.dsh\profiles\web\cordis.patch.yml` 追加同 id 覆盖行： `yaml - insert: - id: live2d-companion name: 'dsh-live2d-companion' config: widget: false # 关闭网页挂件 pet: true # 桌面桌宠随 DSH 自启` patch 文件热重载，保存即生效。开发者路径：`git clone` 后 junction 到 `\profiles\web

ode_modules\dsh-live2d-companion，再按上方注册 patch 行。 **3. 放入模型** ``` public/model/<模型名>/xxx.model3.json ← 连同贴图、 motions、expressions 整目录放入 ``` 然后在 patch config 里指认：model: '<模型名>/xxx.model3.json'（默认 nori/ARGNori.model3.json）。 > 📦 **模型获取**：本仓库不分发任何模型文件。默认适配的 Nori 模型请前往 **I_NORI 群（1041616195）** 群文件自行获取；其他任何 Cubism 4/5 模型也可直接放入使用。 **4. 下载 Cubism Core（许可要求，仓库不含）** 从 Live2D 官方下载并放入： ``` public/vendor/live2dcubismcore.min.js # 官方地址：https://cubism.live2d.com/sdk-web/cubismcore/live2dcubismcore.min.js ``` **5.（桌宠）安装 Electron** ```powershell cd pet npm.cmd install ``` 重启 DSH Web（或下次启动时），桌宠自动出现。 ## 配置 ### patch config（cordis.patch.yml） | 键 | 默认 | 说明 | |---|---|---| | model|nori/ARGNori.model3.json| 模型路径（相对public/model/） | | widget|true| 是否向 DSH 页面注入网页挂件 | |pet|false| 是否随 DSH 自动拉起桌面桌宠 | |petDir|./pet| Electron 壳目录 | ### quips.json（官方默认）+ 台词预设（用户自定义）台词分两层，**官方默认永远只读**，用户自定义永不与上游更新冲突： | 文件 | git | 说明 | |---|---|---| |public/quips.json | ✅ 跟踪 | 官方默认台词库（pools+rotation+behavior） | | public/quips.local.json| ❌ 忽略 | 活跃指针{ "active": "预设名" }，决定哪份预设生效 | | public/quips-presets/<名>.json | ❌ 忽略 | 用户台词集，可「另存为」任意多份（如不同模型各一份人设） | 运行时合并：官方默认 ← 生效预设**逐池胜出**；预设未覆盖的池继续跟随上游默认（上游润色台词你照收）。「词」按钮（齿轮与「?」之间）打开台词池编辑器：预设下拉切换生效集、逐池编辑（每行一句）、·自定义标记与官方不同的池、「恢复默认」让单池回落官方、「另存为」冻结当前内容为新预设。保存写入预设文件并**立即生效**（不等 30 秒轮询）。 | 区 | 说明 | |---|---| |rotation | 台词节奏：holdMs（单句停留）/ intervalMs（轮换间隔）/ doneHoldMs| |behavior | 行为阈值：sleepAfterMs（闲置入睡）/ seriousAfterMs（加班严肃脸）/ overtimeAfterMs（加班焦虑） | | pools | 15 个台词池：thinking/working/done/waiting/error/overtime/sleeping/click/pat/drag/greet/greet_morning/greet_night/idle/busy| 模型切换也可以不改配置：URL 加?model=<模型名>/xxx.model3.json临时指定。 ## 自带模型与绑定层本插件**与模型解耦**：状态机驱动的是「语义槽位」，模型素材通过两级机制绑定到槽位上—— ### 第一级：自动嗅探（零配置）启动时前端会拉取模型的.model3.json，解析 FileReferences里的表情/动作清单，按关键词模糊匹配槽位（如文件名含shy/害羞→ 害羞位，含nod→ 点头位）。任何命名规范的 Cubism 模型丢进来即可获得完整情绪表现；匹配不到的槽位**静默跳过**，不会报错。 > 🌐 **生态惯例兼容**：自动呼吸依赖官方示例框架的Idle组惯例（绝大多数模型遵守）；点击反应池优先取官方示例惯例的Tap*/Reaction/Touch组并自动剔除生气动作。Live2D 官方并不规定动作组/表情的语义命名，故无标配模型一律可用下方编辑器手动绑定。 ### 第二级：profile.json 精确覆盖（可选）在模型目录放profile.json（model/<模型名>/profile.json，随模型一起走），逐槽位钉死映射；写了的槽位覆盖嗅探结果，没写的继续走嗅探。 **表情槽位**（值为模型里的表情名）： | 槽位 | 用途 | |---|---| | default/happy/excited| 常态 / 完成 / 工作兴奋 | |shy| 摸头、被拖动 | |doubt| 思考、待确认 | |troubled/serious| 报错、加班焦虑 / 加班严肃 | |surprised| 睡醒惊醒 | |dark/sleep| 离线 / 打瞌睡 | **动作槽位**（值为[动作组名, 组内序号]）： | 槽位 | 用途 | |---|---| | think/excited/shake| 思考姿势 / 工作动作 / 摇头求确认 | |dizzy/nod| 报错转圈 / 完成点头 | |sleep/glitch| 打瞌睡循环 / 报错特效 | |clickPool | 点击反应随机池，二维数组 | 示例（Nori 模型的实际 profile）： ```json { "expressions": { "default": "00_Default", "happy": "13_Happy", "excited": "01_KiraKira", "shy": "04_Shy", "doubt": "10_Doubt", "troubled": "09_Troubled", "serious": "12_Serious", "surprised": "14_Surprised", "dark": "05_Dark", "sleep": "Sleep" }, "motions": { "think": ["Poses", 1], "excited": ["Reactions", 2], "shake": ["Reactions", 1], "dizzy": ["Reactions", 5], "nod": ["Reactions", 0], "sleep": ["Idle", 1], "glitch": ["Effects", 0], "clickPool": [["Reactions", 0], ["Reactions", 1], ["Reactions", 2]] } } ``` 调试时可在控制台看解析结果：window.__l2d.binding。 ## 模型面板挂件/桌宠右上角有一个悬浮齿轮按钮，鼠标不悬停时约 1.2 秒后自动隐藏；悬停模型区域或打开面板时重新出现。齿轮下方依次是「词」台词编辑器（自定义每个状态的随机台词，保存即生效）和「?」说明按钮（同显隐节奏，点开是基本操作速查卡）： - 自动扫描 public/model/下全部.model3.json` - 点击列表项即时切换当前挂件模型，无需刷新页面 - 每个模型右侧「查看」按钮，弹窗内嵌 Live2D 预览（隔离实例：不接 SSE/交互，状态由按钮手动驱动，8 态点哪个看哪个） - 预览弹窗顶部「绑定」打开*状态直通绑定编辑器：点上方状态按钮选目标（工作/闲置…），下方列出全部表情/动作素材按钮——点素材即在预览里试穿并记入草稿（角标「→ 工作」标出素材服役状态），「保存绑定」才写入模型目录 profile.json 并热生效到主窗；「恢复自动嗅探」删除档案回退。闲置/离线无动作位、共享脸槽（思考/等待）等情况界面会明确提示 - 「导入模型」选择模型文件夹（Chrome/Edge 支持目录选择；其他浏览器可多选文件后输入模型名），按文件逐个上传并自动切到导入后的 .model3.json - 「恢复默认」清除面板选择，回到 cordis.patch.yml 里的 model - 面板底部「帧率」下拉：满血（60/30/12）/ 均衡（30/12/6，默认）/ 省电（15/8/4）三档预设，常态/睡眠/离线帧率联动切换，立即生效并持久化到本机 - 面板选择保存在仓库根目录 model-selection.json（已 gitignore），下次启动 DSH 仍生效；该文件优先于 patch 默认值面板和选择接口： - GET /live2d/models：{ current, defaultModel, models: [{ path, dir, file }] } - POST /live2d/model：body { "model": "<相对 model/ 的 .model3.json 路径>" } - POST /live2d/model：body { "reset": true } 恢复 patch 默认模型 - POST /live2d/import?model=<文件夹名>&path=<相对文件路径>：body 为原始文件字节，单文件上限 128 MiB；路径经过校验，无法写出 model/ 目录 - POST /live2d/profile：body { "dir": "<模型文件夹>", "profile": {...} } 写绑定档案；{ "dir": "...", "reset": true } 删除档案恢复自动嗅探。档案经白名单形状清洗，写入范围锁死在 model/<dir>/profile.json - POST /live2d/quips：台词预设三动作——{ "save": "<预设名>", "data": {pools…} } 新建/覆盖预设并设为生效；{ "activate": "<预设名>" | null } 仅切换生效预设；{ "delete": "<预设名>" } 删除预设。池数据逐池白名单校验，写入范围锁死在 quips-presets/ 与 quips.local.json - GET /live2d/quips-config：{ active, presets: [...] } 预设清单与生效指针 > 🔒 四个变更类路由（/model /import /profile /quips）仅允许本机来源（127.0.0.1/::1）。若把 DSH web 绑定到局域网，远端写入会被 403 拒绝。 > 🛟 模型加载自带兜底链：配置模型加载失败自动回退默认模型；默认也失败时挂件内显示可见错误提示（首次使用未放模型/缺 cubismcore 时不再是一团空气）。 ## 扩展开发（贡献者向）无需改核心代码即可拓展功能：public/extensions/ 下放一个 ES Module，在 index.json 清单里登记文件名，启动时自动加载。 js // public/extensions/my-feature.js export default function apply(api) { api.on('enter', (next, prev) => { /* 状态切换钩子 */ }) api.showBubble('咱的扩展上线啦', 3000) } json // public/extensions/index.json ["hourly-chime.js", "my-feature.js"] 公共 API（api，即控制台里的 window.__l2d）： | 成员 | 说明 | |---|---| | enter(state) / showBubble(text, ms) | 切状态 / 冒气泡 | | on(event, fn) | 订阅事件，返回退订函数 | | registerState(name, def) | 注册/覆盖状态行为（expr/motion/pool/rotate/remotionMs/transientMs） | | registerLamp(name, spec) | 注册/覆盖状态灯（color/label/anim；自定义动画需自注入 @keyframes） | | quip(pool) | 从台词池抽一句 | | setModel(path) / refreshModels() | 热切换模型 / 重新扫描模型列表 | | openModelPanel() / closeModelPanel() | 打开 / 关闭模型面板 | | openModelViewer(path) / importModels(files) | 预览模型 / 导入文件列表 | | state / binding / model / modelPath / modelList / bounds / gaze | 实时只读状态 | | ctx | 完整共享上下文（实验性，结构可能随版本调整） | 事件：enter（状态切换，(next, prev)）、raw（宿主原始会话事件，(ev)）、model（模型热切换，(modelPath)）、ready（初始化完成，(api)）。 隔离保证：单个扩展加载或钩子抛错只会打出一条 console.error，不影响本体与其他扩展。自带示例 hourly-chime.js（整点报时），从清单删名即停用。 ## 状态 → 表现映射 | 状态 | 触发事件 | 表情/动作 | 台词池 | |---|---|---|---| | thinking | turn/start / assistant/chunk | 疑惑 + 思考姿势循环 | thinking | | working | tool/call 等 | 兴奋 + 定期重放动作 | working | | waiting | approval/asked | 疑惑 + 摇头求确认 | waiting | | error | llm/retry-started | 困扰 + 转圈/概率 Glitch | error | | done | turn/end（6 秒后回 idle） | 开心 + 点头 | done | | sleeping | 空闲超时（前端计时） | Sleep + 打瞌睡循环 | sleeping | | —（加班中） | working 超时升级 | 严肃脸 → 困扰脸 | overtime | ## 调试 - 桌宠 DevTools：L2D_DEBUG=1 启动后 --remote-debugging-port 9222，配合 pet/cdp-probe.mjs（CDP 注入探针） - 页面控制台句柄：window.__l2d（model / 当前状态 / bounds / 手动 enter） - 桌宠环境变量：L2D_URL（目标页面）、L2D_MODEL（临时模型）、L2D_SOFT=1（软渲染模式：GPU 光栅化路径异常的逃生门，代价是渲染吃 CPU；对拖动闪烁无效，见下方拖拽架构） ### 桌宠架构：全屏覆盖层（overlay-pet）桌宠窗口铺满主屏、永不移动、默认指针穿透（仅模型与 UI 按钮区域拦截输入，随光标位置实时切换）。拖拽 = 模型在画布内 1:1 跟随——没有锚定、没有接力、没有活动范围限制，松手即定位，位置以模型中心画布坐标记忆，重启复原。 穿透策略（自动 + 手动）：全屏窗口从「穿透」切到「交互」的瞬间会参与 DWM 合成，可能拆解浏览器视频的硬件覆盖层（MPO）导致视频黑屏卡帧。为此模型区域默认自动穿透：指针路过不算数，停留约 0.6 秒（位移 <24px）才放行交互，离开包围盒即回收——看片时鼠标扫过糯糯不再触发黑屏；⚙/🔒/菜单/卡片等 UI 控件不受等待限制，即时可点。⚙ 左侧的「🔒」钮是**手动强制穿透**：按下后模型完全不响应鼠标（UI 保留可点，再按恢复自动），状态持久化。设计动机（Windows 透明窗拖动闪烁的根因，实测证据矩阵）：呈现层（DirectComposition/DWM）丢帧**只在「按住鼠标的物理消息流 × 窗口移动」并发时触发**——模型瞬间消失、无白/黑闪；纯程序滑移不闪、悬停不闪、按住不动不闪、渲染帧缓冲移动全程实测完好（无 WebGL 上下文丢失、无 rAF 卡顿），与指针捕获/窗口激活态/光标可见性/GPU 或软渲染/RDP 或直插/刷新率**均无关**。全屏覆盖层让窗口从启动到退出零移动，触发条件在架构上不存在；拖拽手感同时达到像素级 1:1（游戏浮层/RTSS 同款架构）。已知边界：窗口仅覆盖主屏（多显示器待扩展）；独占全屏应用（如部分游戏）会盖住桌宠。 > 看视频时鼠标经过模型导致视频黑屏/卡顿：本版本起由自动穿透（停留等待）天然规避；若个别播放器仍敏感，点一下 ⚙ 左侧的「🔒」钮强制全穿透即可。 > 「CPU 渲染模式」（面板勾选，或 L2D_SOFT=1 临时测试）仅对 GPU 光栅化路径类异常有效，对上述呈现层丢帧无效——拖动闪烁请直接升级到此版本。 ## 许可 - 本仓库代码：MIT（见 LICENSE） - 不包含 Live2D 模型与 live2dcubismcore.min.js：模型请自备并遵守其原许可（Nori 模型见上方「模型获取」，请遵守群文件的原始发布条款）；Cubism Core 受 Live2D 专有协议约束，请从官方渠道下载 - 依赖：pixi.js（MIT）、pixi-live2d-display（MIT）、Electron（MIT）

Live2d Companion

精选

为什么选中它

它能做什么

适合谁

风险提示

确认后再安装

仓库信息

这个插件涵盖什么

GitHub Topics

声明支持的平台

README 摘要

人工精选

@dshwork/config-dashboard

DSH-Plan-Graph

dsh-crew