dsh-live2dwaifu 0.8.1 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +336 -173
  2. package/assets/viewer.html +92 -80
  3. package/docs/ui-preview.html +144 -0
  4. package/docs/ui.png +0 -0
  5. package/lib/client.js +36 -23
  6. package/lib/index.js +820 -834
  7. package/package.json +1 -1
package/README.md CHANGED
@@ -1,173 +1,336 @@
1
- # dsh-live2dwaifu
2
-
3
- 把 **Live2D（Cubism 3 / 4）** 模型请进 DSH 网页的右下角。她会眨眼、会呼吸、头发会被风吹，说话时嘴一张一合，心情变了眉毛跟着动。
4
-
5
- 模型**不是内置的**——谁装谁放自己的。点卡片上的 ⚙，把模型文件夹整个选进去就行，文件留在这台机器上（`~/.dsh/dsh-live2d/models/`），一根网线都没往外走。
6
-
7
- > 给它一个模型，它给你一个会呼吸的角落。
8
-
9
- ![两种状态](docs/preview.png)
10
-
11
- | 样子 | 说明 |
12
- |---|---|
13
- | 展开 | 一张小卡片，上半身，底下一条气泡装台词 |
14
- | 收起 | 缩成一条，只剩名字和一个 ⌃ |
15
-
16
- 按住标题栏能把她拖到屏幕任何地方，右下角那个小三角拖的是大小；标题栏的 **◐** 一键换背景（透明 / 深色 / 浅色 / 纸质）。位置、大小、背景、开合状态都记在本机，下次还是这样。
17
-
18
- **她会看你**：鼠标在窗口里走，眼珠跟着转，脑袋也偏一点。
19
-
20
- **能戳**：点她的头会害羞，戳身上会瞪你，点底下就应你一声。
21
-
22
- **会自己动**：模型里带 `.motion3.json` 的，隔十几秒自己播一个动作。气泡能拖着挪地方，说完过一阵自己淡下去。
23
-
24
- **会出声**：一个字一声很短的电音，标点停一拍，句尾沉一下——不是朗读，是“哔哔”那种。标题栏的 **♪** 打开调音页，放个真模型在旁边，边调边听；每只模型各存一份音色，换人换声。音量拉到 0 就安静，只剩气泡和口型。
25
-
26
- **她也会甩图（测试功能）**：⚙ 里有一根滑轴，四档——不使用 / 只使用自带 / 均开启 / 只用 dsh-meme。自带那套是夏铃自己的 Q 版贴纸，二十张，随插件分发，版权归本插件；dsh-meme 那套只是借用你本机已经装的图库。默认关着，功能还在试。
27
-
28
- **她还会问你要选项**：话说到了需要你挑的地方，气泡下面会冒出两三个按钮，点一个就等于你回了她。
29
-
30
- **开关都在 ⚙ 里**：抽屉底下分两栏——「这台机器上」管眼睛跟随、点她、自己播动作、出声、跟着聊天念；「她那边」管没人理就自己开口、甩表情包、给选项、记性。前几项存本机，后几项存 `~/.dsh/dsh-live2d/config.json`。
31
-
32
- **跟着聊**：她挂在聊天流上（`conversation.chat.node` 插槽），助手每说一句她就念一句，情绪按话里的词换。
33
-
34
- **也能直接跟她说**：卡片底下有个小框，打一句回车，她回你。这条线**不进你的聊天记录**——后台直接问模型，往来只存在 `models/<id>/chat.json` 里。她说的话按人设卡现场写，不是复读；人设卡就是 `models/<id>/meta.json` 里的 `persona` 字段，没写就用默认那份（若妍）。
35
-
36
- **她记得住，而且分两层记**：一层是最近二十来句原文，一层是攒出来的「关于你的事实」——名字、作息、口味、忌讳、答应过的事，聊得越久越攒得住，不用你重新讲一遍。攒满三十句就把前面压成小结，不丢。
37
-
38
- **她说的话会过一道筛子**：套话会被删掉——“好的”“我理解你的感受”“希望帮到你”“还有什么需要”这些，出来就没。最多留两三句，允许她只回两个字。
39
-
40
- **她知道几点、也知道自己此刻在干什么**：提示词里会让她按人设推断这个时间点的处境——早上在实验室、半夜还没睡——话里自然带着那个味道，不用你提醒。
41
-
42
- **手机上一页就够**：手机连同一个地址，打开 `/dsh-live2d/chat`，就是她的脸加一个输入框，不用看整个 DSH。
43
-
44
- **她会自己开口**：十几分钟没人理她，她就找个话头说一句。嫌吵就把 `~/.dsh/dsh-live2d/config.json` 里的 `proactive` 设成 `false`。
45
-
46
- **给别人留的口子**：im 机器人、别的插件、随手写的脚本，都能让她说话。
47
-
48
- ```bash
49
- # 她说一句（image 可省，传了就在气泡里贴出来）
50
- curl -X POST http://127.0.0.1:<端口>/dsh-live2d/api/push \
51
- -H 'content-type: application/json' \
52
- -d '{"text":"锅里有汤。","mood":"平静","from":"im"}'
53
-
54
- # 她说一句并要回话
55
- curl -X POST http://127.0.0.1:<端口>/dsh-live2d/api/chat \
56
- -H 'content-type: application/json' -d '{"text":"今天累不累"}'
57
- ```
58
-
59
- 卡片每 2.5 秒拉一次 `/dsh-live2d/api/poll`，所以外面推进来的话，几秒内就演出来。
60
-
61
- ## 三十秒上手
62
-
63
- ```bash
64
- dsh plugin --profile desktop add dsh-live2dwaifu
65
- ```
66
-
67
- 重启 DSH，右下角出现一张小卡片 → 点 ⚙ → 点「导入模型」→ 选那个装着 `.model3.json` 的文件夹 → 完事。
68
-
69
- 导入的时候浏览器会一个一个把文件搬进去，模型大点就多等几秒，进度在底下会说话。
70
-
71
- ## 放自己的模型
72
-
73
- 1. 卡片右上角 ⚙ → 「导入模型」
74
- 2. 选**整个文件夹**（里面要有 `.model3.json`、`.moc3`、贴图，最好还有 `.physics3.json`）
75
- 3. 读完它会自己认出哪个是模型，并切过去
76
-
77
- 想放好几个也行，列表里点「用这个」换人，「删」送走。
78
-
79
- **能吃什么**：Cubism 3 / 4（`.model3.json` + `.moc3`）。
80
- **吃不了什么**：Cubism 2 的老格式（`.model.json` + `.moc`）。
81
-
82
- **自定义表情**：模型文件夹里带 `.exp3.json` 的，导入后在 ⚙ 面板里会列出来，点一下就叠上去（Add / Multiply / Overwrite 三种混合照原样执行）。Cubism 4 的 `.exp3.json` 直接从原画软件导出即可。
83
-
84
- **没有动作文件也能活**：眨眼靠 EyeBlink 参数组，嘴动靠 `ParamMouthOpenY`，头发晃动是 `physics3.json` 自带的物理；表情是本插件拿标准参数（`ParamEyeLSmile`、`ParamMouthForm`、`ParamBrow*`、`ParamAngle*`）现摆的，一共七种：平静、开心、委屈、生气、害羞、无语、困。
85
-
86
- ## 让它说点什么
87
-
88
- 卡片里是个 iframe（`/dsh-live2d/viewer`）。别的插件、脚本、控制台都能指挥它：
89
-
90
- ```js
91
- const frame = document.querySelector('iframe.dsh-l2d-body');
92
-
93
- // 说话：逐字蹦出来，嘴跟着动
94
- frame.contentWindow.postMessage({ type: 'dsh-live2d/say', text: '窗台那盆番茄红了。', mood: '开心' }, '*');
95
-
96
- // 只换脸
97
- frame.contentWindow.postMessage({ type: 'dsh-live2d/mood', mood: '委屈' }, '*');
98
-
99
- // 打开模型管理
100
- frame.contentWindow.postMessage({ type: 'dsh-live2d/manage' }, '*');
101
- ```
102
-
103
- 同源的 HTTP 接口，给不服 iframe 的人：
104
-
105
- | 方法 | 路径 | 作用 |
106
- |---|---|---|
107
- | GET | `/dsh-live2d/api/models` | 列出模型和当前选中的那只 |
108
- | POST | `/dsh-live2d/api/select` | `{id}` 换人 |
109
- | POST | `/dsh-live2d/api/import?model=<id>&path=<相对路径>` | 请求体就是文件字节 |
110
- | POST | `/dsh-live2d/api/commit` | `{id,name}` 扫一遍 model3 并选中 |
111
- | POST | `/dsh-live2d/api/delete` | `{id}` 删掉 |
112
-
113
- ## 写人设卡，请写细一点
114
-
115
- 她回得像不像人，全看那段字。别只写“一个可爱的女孩”——那样只会得到一段没味道的话。
116
-
117
- 值得写进去的：她是谁、几岁、做什么的、说话什么调子（短句还是长句、用不用标点）、有没有口头禅、怕什么、喜欢什么、跟你是什么关系、平时怎么称呼你、这个时间点通常在干嘛。
118
-
119
- `models/<id>/meta.json` 里的 `persona` 想写多长写多长，写不写都行，不写就是默认那份。也可以点标题栏的 **✎** 在网页里改。
120
-
121
- ## 把她的表情包给 dsh-meme 用
122
-
123
- 自带那二十张是标准图库格式，导一次就能丢给 `dsh-meme`：
124
-
125
- ```bash
126
- python tools/export-dsh-meme.py
127
- ```
128
-
129
- 产物在 `dsh-live2d/dsh-meme-pack/xialing-001/`（含 `manifest.json`、`memes/<tag>/`、`index.db`）。整个目录丢进 `~/.dsh/profiles/desktop/node_modules/dsh-meme/memes/` 下面就认了。
130
-
131
- ## 东西都放哪了
132
-
133
- ```
134
- ~/.dsh/dsh-live2d/
135
- config.json # 现在轮到谁上场
136
- models/<id>/ # 模型文件，相对结构原样保留
137
- meta.json # { name, model3 }
138
- ```
139
-
140
- ## 一些常见的小脾气
141
-
142
- **右下角什么都没有？**
143
- 先重启一次 DSH。还不来，看 profile 的 `package.json`：`dsh.profile.bundles` 里得有 `dsh-live2dwaifu`，`dependencies` 里也得有。用 `dsh plugin add` 装的会自动写进去；手动解压到 `node_modules` 的不会——DSH 只加载列在 `bundles` 里的包，名字漏了就当没装，`/dsh-live2d/api/models` 也会 404。
144
-
145
- **导入了却不认得？**
146
- 多半是文件夹选得太靠上或太靠下，`.model3.json` 就在里面那一层，选它隔壁那层。
147
-
148
- **她只有半张脸？**
149
- 这个模型的画布比例跟面板不一样。面板是竖的，太宽或太扁的模型会被裁两边。
150
-
151
- **能放动作吗？**
152
- 暂时不能编排 `.motion3.json`，表情是固定的七种。想要更多情绪，给它发 `mood`，等以后的版本。
153
-
154
- ## 关于别人的插件
155
-
156
- 她的图、她的耳朵，都是从你**已经装好的**插件里读的。这个包里不带任何第三方素材，也一行没改别人的代码：
157
-
158
- - **表情图**：从 `dsh-meme` 的图库目录里挑一张，只在本机显示，不上传、不分发。没装 `dsh-meme` 就没有图，其它照常。
159
- - **麦克风**：交给 `dsh-ears`，本插件不碰录音，只是把转写好的字送进对话。
160
- - **对话**：走 DSH 自己的模型接口（`ctx.llm`），不经过任何人的会话，也不写你的聊天记录。
161
-
162
- 不喜欢这些联动，⚙ 里都能单独关掉。
163
-
164
- ## 已知限制
165
-
166
- - 只支持 Cubism 3 / 4（表情只认 `.exp3.json`，不认 `.motion3.json` 里的表情轨）
167
- - 面板是浮层（`shell.overlay`），不是聊天区分栏；会盖住右下角，能收起
168
- - 内置七种情绪；自定义表情靠模型自带的 `.exp3.json`，一次只能叠一个
169
- - 内置的 Cubism Core 是 Live2D Inc. 的 Redistributable Code，随包分发，使用受其 EULA 约束
170
-
171
- ---
172
-
173
- MIT © LFR · npm: [`dsh-live2dwaifu`](https://www.npmjs.com/package/dsh-live2dwaifu)
1
+ # dsh-live2dwaifu
2
+
3
+ 把一只 **Live2D（Cubism 3 / 4）** 角色请进 DSH 网页的右下角。她会眨眼、会呼吸、头发会被风吹，说话时嘴一张一合，眼珠跟着鼠标走，心情变了眉毛跟着动。
4
+
5
+ 她还能跟你说话——不用经过聊天框，不用进聊天记录。有自己的记忆、自己的作息、自己的声音（那种“哔哔”的电子音），高兴了甩你一张贴图。
6
+
7
+ 模型**不是内置的**：谁装谁放自己的。文件全留在这台机器上，一根网线都不往外走。
8
+
9
+ > 给她一个模型，她给你一个会呼吸的角落。
10
+
11
+ ![界面](docs/ui.png)
12
+
13
+ | 状态 | 说明 |
14
+ |---|---|
15
+ | 展开 | 一张竖卡片：上半身、气泡、底下一个输入框 |
16
+ | 收起 | 缩成一条，只剩名字和一个 ⌃ |
17
+
18
+ ---
19
+
20
+ ## 装
21
+
22
+ ```bash
23
+ dsh plugin --profile desktop add dsh-live2dwaifu
24
+ ```
25
+
26
+ 重启 DSH。右下角出现一张小卡片 → 点 ⚙ → 「导入模型」→ 选装着 `.model3.json` 的那个文件夹 → 完事。
27
+
28
+ 桌面端也可以在**设置 → 插件**里搜名字安装。
29
+
30
+ **别手动解压到 `node_modules`。** DSH 只加载列在 profile `package.json` 的 `dsh.profile.bundles` 里的包。手动扔进去的名字不会自动登记，表现就是“装了但右下角什么都没有”，`/dsh-live2d/api/models` 也返回 404。真遇到了，把 `dsh-live2dwaifu` 补进 `bundles` 和 `dependencies` 再重启。
31
+
32
+ ---
33
+
34
+ ## 卡片
35
+
36
+ ### 位置和大小
37
+
38
+ 按住**标题栏**能拖到屏幕任何地方；右下角那个小斜纹拖的是大小（宽 200–720，高 220–视口高−80）。位置、大小、背景、开合状态都记在本机，下次打开还是这样。
39
+
40
+ 拖到一半跑到屏幕外了？关掉重开一次就回到默认位置。
41
+
42
+ ### 标题栏按钮
43
+
44
+ | 按钮 | 干什么 |
45
+ |---|---|
46
+ | **⚙** | 抽屉：模型列表、自定义表情、全部开关 |
47
+ | **◐** | 换背景：透明 / 深色 / 浅色 / 纸质 |
48
+ | **♪** | 音色调色页（每只模型各存一份音色） |
49
+ | **✎** | 人设卡编辑页 |
50
+ | **↻** | 重载 iframe（模型卡住时点这个） |
51
+ | **⌄ / ⌃** | 收起 / 展开 |
52
+
53
+ ---
54
+
55
+ ## 放自己的模型
56
+
57
+ 1. ⚙ → 「导入模型」
58
+ 2. 选**整个文件夹**，里面要有 `.model3.json`、`.moc3`、贴图，最好带 `.physics3.json`
59
+ 3. 读完它自己认出模型并切过去
60
+
61
+ 想放好几个也行：列表里「用这个」换人，「删」送走。
62
+
63
+ **吃**：Cubism 3 / 4（`.model3.json` + `.moc3`）。
64
+ **不吃**：Cubism 2 老格式（`.model.json` + `.moc`）。
65
+
66
+ **模型自带的动作**：有 `.motion3.json` 的，隔十几秒自己播一个；没有也能活——眨眼靠 EyeBlink 参数组，嘴动靠 `ParamMouthOpenY`，头发晃动是 `physics3.json` 的物理。
67
+
68
+ **模型自带的表情**：带 `.exp3.json` 的会在抽屉里列出来，点一下叠上去（Add / Multiply / Overwrite 照原样执行）。没带的话，内置七种：平静、开心、委屈、生气、害羞、无语、困。
69
+
70
+ **导入卡住或只导入一半**：模型大（贴图 4K）时浏览器要一张张传，慢是正常的，进度在抽屉底下显示。传一半断了就再来一次，同名文件会覆盖。
71
+
72
+ ---
73
+
74
+ ## 她是谁：人设卡
75
+
76
+ 她说话像不像人，全看这一段字。别只写“一个可爱的女孩”——那样只会得到一段没味道的话。
77
+
78
+ 人设卡存在 `~/.dsh/dsh-live2d/models/<id>/meta.json` 的 `persona` 字段里，也可以点标题栏 **✎** 在网页里改，改完她一重载就按新的说。
79
+
80
+ **值得写进去的**：
81
+
82
+ - 她是谁、几岁、做什么工作的
83
+ - 说话什么调子：短句还是长句、用不用标点、爱不爱反问
84
+ - 口头禅、习惯性的小动作、称呼你什么
85
+ - 怕什么、喜欢什么、有什么毛病
86
+ - 跟你是什么关系、你们在哪儿过日子
87
+ - 这个时间点她通常在干嘛
88
+
89
+ 写得越具体越像人，写一句“性格开朗”没什么用。写完可以自己念一遍，像不像一个人在发消息。
90
+
91
+ **世界隔离**（人设卡页底下一个开关）：开着的时候，她不知道什么是程序、界面、插件、模型，问起来就当你在她身边；关掉她就老老实实承认自己是插件里的角色。默认开。
92
+
93
+ 不写 `persona` 也行，会用默认那份（若妍）。
94
+
95
+ ---
96
+
97
+ ## 跟她说话
98
+
99
+ ### 三条路
100
+
101
+ **一、卡片底下的输入框**：打一句、回车。这条线**不进你的聊天记录**，往来只存在她自己的 `chat.json` 里。
102
+
103
+ **二、手机**：手机连同一个地址，打开 `/dsh-live2d/chat`，全屏就她的脸加一个输入框，不用看整个 DSH。
104
+
105
+ > 端口每次启动可能不一样。在 DSH 设置里能看到当前地址，把它换成 `/dsh-live2d/chat` 就行。手机和电脑得在同一个局域网。
106
+
107
+ **三、别的插件推**（见下面「给别的插件用」）。
108
+
109
+ ### 她记得住
110
+
111
+ 记忆分两层：
112
+
113
+ - **最近二十来句**：原话，最近说了什么都在。
114
+ - **关于你的事实**：名字、作息、口味、忌讳、答应过的事——从对话里攒出来的，长期挂着。聊天时只挑跟你这句话对得上的几条带上，不会一股脑塞进提示词。
115
+
116
+ 攒满三十句，前面二十句会压成小结，不丢。嫌费 token，就在 ⚙ 里把「记住之前说的」关掉。
117
+
118
+ ### 她说的话会过一道筛子
119
+
120
+ 模型写出来的东西先过一遍：套话会被删掉——“好的”“我理解你的感受”“希望帮到你”“还有什么需要我帮忙的吗”这些，出来就没有。最多留两三句，也允许她只回两个字。
121
+
122
+ 提示词里还会明确禁止：不总结、不分点、不讲道理、不解释心情、你没问就不给建议。
123
+
124
+ > 还是觉得哪句像 AI？记下来告诉作者，往规则里加。
125
+
126
+ ### 她偶尔给你选项
127
+
128
+ 话说到需要你挑的地方，她会在气泡上方冒出两三个按钮，点一个就等于你回了她。
129
+
130
+ **她不给就没有**——要不要给是她自己决定的，不是每次都有。通用短答试过，效果不好，撤掉了。
131
+
132
+ ### 她知道现在几点，也知道自己该在干嘛
133
+
134
+ 提示词里会让她按人设推断这个时间点的处境——早上在实验室、半夜还没睡——话里自然带着那个味道。不用你提醒，也不用写死时间表。
135
+
136
+ ### 她偶尔自己开口
137
+
138
+ 十几分钟没人理她，她就找个话头说一句，通过卡片的气泡冒出来。嫌吵：⚙ 里关掉「没人理就自己开口」。
139
+
140
+ **开了却从不出现**？她只在页面开着的时候说，而且说出来到显示有几秒延迟（卡片每 2.5 秒拉一次）——等一会。
141
+
142
+ ---
143
+
144
+ ## 声音
145
+
146
+ 她说话时一个字一声很短的电音，标点停一拍，句尾沉一下。不是朗读，是“哔哔”那种。
147
+
148
+ **调色**：标题栏 **♪** 打开调音页，左边是这只模型真身，右边四个预设（柔和 / 清脆 / 机械 / 游戏）加五个滑块（基频、抖动、长度、音量、语速）。边调边听，满意了点「存到这只模型」。**每只模型各存一份**，换人换声。
149
+
150
+ **安静**：⚙ 里关掉「出声」，或把音色调到音量 0。关掉之后只剩气泡和口型。
151
+
152
+ **第一次没有声音**？浏览器要求用户先点一下页面才允许出声。点她一下，或者点一下调音页的按钮，再试。
153
+
154
+ ---
155
+
156
+ ## 表情包（测试功能）
157
+
158
+ 她说话时可能甩一张贴图，贴在气泡里。
159
+
160
+ ⚙ 里有一根四档滑轴：
161
+
162
+ | 档位 | 意思 |
163
+ |---|---|
164
+ | 不使用 | 不说话配图 |
165
+ | 只使用自带 | 只用插件自带的那套 |
166
+ | 均开启 | 自带和 dsh-meme 混着来 |
167
+ | 只用 dsh-meme | 只借你本机已装的 dsh-meme 图库 |
168
+
169
+ **自带那套**是作者 OC 的 Q 版贴纸（效果不是很好其实）。
170
+
171
+ **怎么挑图**：她点名叫哪张就用哪张（提示词里给了名字清单）；没点名的话，按她这句话的情绪随机抽一张，大约三成概率。
172
+
173
+ **给 dsh-meme 用**：自带那二十张是标准图库格式，导一次就能丢给它。
174
+
175
+ ```bash
176
+ python tools/export-dsh-meme.py
177
+ ```
178
+
179
+ 产物在 `dsh-live2d/dsh-meme-pack/xialing-001/`，整个目录丢进 `~/.dsh/profiles/desktop/node_modules/dsh-meme/memes/` 下面就认。
180
+
181
+ **图不贴题**？这功能还在试。滑到「不用」最干净。
182
+
183
+ ---
184
+
185
+ ## 全部开关
186
+
187
+ ⚙ 抽屉底下分两栏。「这台机器上」存 localStorage，只管这一台浏览器；「她那边」存 `~/.dsh/dsh-live2d/config.json`，跟着插件走。
188
+
189
+ | 开关 | 位置 | 默认 | 说明 |
190
+ |---|---|---|---|
191
+ | 眼睛跟着鼠标 | 本机 | 开 | 关掉她就不看鼠标了 |
192
+ | 点她有反应 | 本机 | 开 | 摸头害羞、戳身上瞪你 |
193
+ | 自己播动作 | 本机 | 开 | 有动作文件的模型才会动 |
194
+ | 出声 | 本机 | 开 | 电子音 |
195
+ | 跟着聊天念 | 本机 | 开 | 助手每说一句她念一句 |
196
+ | 没人理就自己开口 | 她那边 | 开 | 十几分钟没人说话她说一句 |
197
+ | 给选项让他挑 | 她那边 | 开 | 气泡上方冒出可点的按钮 |
198
+ | 记住之前说的 | 她那边 | 开 | 关掉就不带记忆、不压缩 |
199
+ | 表情包（四档） | 她那边 | 不使用 | 测试功能，见上 |
200
+
201
+ ---
202
+
203
+ ## 给别的插件用
204
+
205
+ 卡片里是个 iframe（`/dsh-live2d/viewer`）。同源脚本可以直接指挥它：
206
+
207
+ ```js
208
+ const frame = document.querySelector('iframe.dsh-l2d-body');
209
+
210
+ // 说话：逐字蹦出来，嘴跟着动，可选配图
211
+ frame.contentWindow.postMessage({
212
+ type: 'dsh-live2d/say',
213
+ text: '窗台那盆番茄红了。',
214
+ mood: '开心',
215
+ image: '/dsh-live2d/ownmeme/deyi.jpg',
216
+ }, '*');
217
+
218
+ // 只换脸
219
+ frame.contentWindow.postMessage({ type: 'dsh-live2d/mood', mood: '委屈' }, '*');
220
+
221
+ // 打开模型抽屉
222
+ frame.contentWindow.postMessage({ type: 'dsh-live2d/manage' }, '*');
223
+ ```
224
+
225
+ HTTP 接口，给不想碰 iframe 的：
226
+
227
+ | 方法 | 路径 | 作用 |
228
+ |---|---|---|
229
+ | GET | `/dsh-live2d/api/models` | 模型列表 + 当前选中 + 每只的音色 |
230
+ | POST | `/dsh-live2d/api/select` | `{id}` 换人 |
231
+ | POST | `/dsh-live2d/api/import?model=<id>&path=<相对路径>` | 请求体是文件字节 |
232
+ | POST | `/dsh-live2d/api/commit` | `{id,name}` 扫一遍并选中 |
233
+ | POST | `/dsh-live2d/api/delete` | `{id}` 删掉 |
234
+ | GET | `/dsh-live2d/api/voice?id=` | 读这只模型的音色 |
235
+ | POST | `/dsh-live2d/api/voice` | `{id,voice}` 存音色 |
236
+ | GET/POST | `/dsh-live2d/api/persona` | 读 / 存人设卡 |
237
+ | GET/POST | `/dsh-live2d/api/settings` | 读 / 存开关 |
238
+ | POST | `/dsh-live2d/api/chat` | `{text}` 跟她说一句，返回 `{reply,image,choices}` |
239
+ | POST | `/dsh-live2d/api/push` | `{text,image,mood}` 让她说一句（外部推送口） |
240
+ | GET | `/dsh-live2d/api/poll?since=` | 卡片每 2.5 秒拉一次，取待播的话 |
241
+
242
+ im 机器人接进来就一句话：
243
+
244
+ ```bash
245
+ curl -X POST http://127.0.0.1:<端口>/dsh-live2d/api/push \
246
+ -H 'content-type: application/json' \
247
+ -d '{"text":"锅里有汤。","mood":"平静","from":"im"}'
248
+ ```
249
+
250
+ ---
251
+
252
+ ## 数据存在哪
253
+
254
+ ```
255
+ ~/.dsh/dsh-live2d/
256
+ config.json 现在轮到谁上场 + 各项开关
257
+ models/<id>/
258
+ meta.json { name, model3, persona, isolation, voice }
259
+ chat.json { messages, summary, facts } 跟她私聊的记录和记忆
260
+ <模型文件…>
261
+ ```
262
+
263
+ 插件自己的文件在 `~/.dsh/profiles/desktop/node_modules/dsh-live2dwaifu/`，自带的二十张贴图在 `assets/memes/`。
264
+
265
+ **想清空她对你记的事**：删掉对应模型的 `chat.json`。**想彻底重来**：整个 `~/.dsh/dsh-live2d/` 删掉，模型得重新导入。
266
+
267
+ ---
268
+
269
+ ## 常见问题
270
+
271
+ **右下角什么都没有**
272
+ 先重启。还不来，看 profile 的 `package.json`：`dsh.profile.bundles` 和 `dependencies` 里都得有 `dsh-live2dwaifu`。手动拷进 `node_modules` 的不会自动登记。
273
+
274
+ **她只有半张脸 / 位置偏上**
275
+ 模型画布比例跟卡片不一样。卡片是竖的，太宽或太扁的模型会被裁两边。拖右下角改形状试试。
276
+
277
+ **导入了却不认得**
278
+ `.model3.json` 的层级选错了。选它隔壁那一层。
279
+
280
+ **她不动、不眨眼**
281
+ 点一次 **↻** 重载。还不行就看浏览器控制台——多半是模型缺 `.moc3` 或缺贴图。
282
+
283
+ **跟她说话没反应**
284
+ - 确认 ⚙ 里「记住之前说的」不是全关（不影响回复，只影响记忆）
285
+ - 后台直接调 DSH 的模型接口，所以 DSH 自己得能正常对话
286
+ - 报“模型接口不可用”就是当前没有可用模型，去设置里选一个
287
+
288
+ **她说的话还是像 AI**
289
+ 规则在 `lib/index.js` 的 `AI_WORDS` 和提示词那段。可以自己加词，改完重启。
290
+
291
+ **手机打不开 `/dsh-live2d/chat`**
292
+ 手机和电脑得在同一个局域网；端口用 DSH 设置里显示的那个（每次启动会变）；防火墙可能挡了局域网访问。
293
+
294
+ **表情包一直不出现**
295
+ 滑轴滑到「不使用」了，或者她是随机三成概率——多聊几句。只使用自带的话，确认 `assets/memes/` 里有那二十张。
296
+
297
+ **动作播得很怪 / 抽搐**
298
+ 有些模型的 motion 会覆盖插件在算的参数。⚙ 里关掉「自己播动作」。
299
+
300
+ **她记得太多了 / 词太占 token**
301
+ ⚙ 里关掉「记住之前说的」。或者删 `chat.json` 里不要的条目。
302
+
303
+ ---
304
+
305
+ ## 已知限制
306
+
307
+ - 只支持 Cubism 3 / 4，不吃 Cubism 2
308
+ - 表情只认 `.exp3.json`，不认 `.motion3.json` 里的表情轨
309
+ - 卡片是浮层（`shell.overlay`），不是聊天区分栏，会盖住右下角——能拖走、能收起
310
+ - 内置七种情绪；自定义表情一次只能叠一个
311
+ - 跟她的对话不经过 DSH 会话，所以没有工具调用、不能上网、不读文件，只说话
312
+ - 内置的 Cubism Core 是 Live2D Inc. 的 Redistributable Code，随包分发，使用受其 EULA 约束
313
+
314
+ ---
315
+
316
+ ## 关于别人的插件
317
+
318
+ 她的图、她的耳朵，都是从你**已经装好的**插件里读的。这个包里不带任何第三方素材，也一行没改别人的代码：
319
+
320
+ - **表情图**：从 `dsh-meme` 的图库目录里挑一张，只在本机显示，不上传、不分发。没装就没有图，其它照常。
321
+ - **麦克风**：交给 `dsh-ears`，本插件不碰录音，只是把转写好的字送进对话。
322
+ - **对话**：走 DSH 自己的模型接口（`ctx.llm`），不经过任何人的会话，也不写你的聊天记录。
323
+
324
+ 不喜欢这些联动，⚙ 里都能单独关掉。
325
+
326
+ ---
327
+
328
+ ## 致谢
329
+
330
+ - Live2D Cubism Core © Live2D Inc.
331
+ - `pixi-live2d-display` 与 `pixi.js`
332
+ - DeepSeek Harness 大肥鱼
333
+
334
+ ---
335
+
336
+ MIT © LFR · npm: [`dsh-live2dwaifu`](https://www.npmjs.com/package/dsh-live2dwaifu) · [GitHub](https://github.com/FujiwaraReisen/dsh-live2dwaifu)