cortico-world-extra-actions 0.3.32 → 0.3.34

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.
package/README.md CHANGED
@@ -1,254 +1,265 @@
1
- # 深深与额外动作拓展(Coopanion 扩展)
2
-
3
- `cortico-world-extra-actions` · MIT · 作者:Daniele贤狼赫萝 & 奶糖_Net(丹尼尔 / Net-ang)
4
- 发布流程(打 tag、`npm publish`)写在仓库根目录的 `PUBLISH.md` 里,不随包分发。
5
-
6
- 把《深深 · 动作库》里的 105 段动作做成一张勾选表:勾中的动作写进形象包的
7
- `额外动作拓展/` 文件夹,桌宠照着做 —— 待机会轮播、点她会触发、重启后 bot 也能点名。
8
-
9
- 素材全是 **640×360 高清**:动作库一段一个 `anim.webp`(整段动图,加载快、不逐帧换图),
10
- 插件自带的示例形象包(4 段身体状态 + 3 段示例动作)也是同一套高清,新装的人第一眼就不糊。
11
-
12
- - 插件形态:Cortico World(`kind: world`, `api: 6`),面板在 Coopanion 的扩展页里;显示名 **深深与额外动作拓展**
13
- - 数据落点:`<形象包>/额外动作拓展/`(桌宠读的东西)+ `worlds.extra-actions.libraryDir`(走 `WorldContext.persist` 存进 config.json)
14
- - 不改播放器、不改形象包的其它文件;`figure.json` 只增删它自己管过的那几个词,第一次动之前留备份
15
-
16
- ## 零、协议与安全(先看这段)
17
-
18
- 这个包是 **Cortico World**,不是往主程序里塞代码。契约按安装目录里的源码
19
- (`resources/app/build/cortico/src/`)核对过:
20
-
21
- | 契约 | 要求 | 本包 |
22
- |---|---|---|
23
- | `package.json` → `cortico.kind` | `world` / `provider` / `bot` | `world` ✓ |
24
- | `cortico.api` | 必须**正好**是 `EXTENSION_API_VERSIONS.world = 6` | `6` ✓ |
25
- | `cortico.webUiClient` | 包内相对路径、不含 `\`、不以 `/` 开头、无 `..`、`.js/.mjs` | `dist/webui.js` ✓ |
26
- | `keywords` | 要有 `cortico-world` | ✓ |
27
- | 默认导出 | 有 `id` / `label` / `defaults()` / `create()` | ✓(`isWorldDefinition` 就查这四项) |
28
- | 实例 | `start(host)` / `stop()` / `envPromptVars()` / `tools()` | ✓(`tools()` 返回空数组:不给 bot 任何可调用的写入口) |
29
- | 面板 | `webUi(language)` 返回 `{ label, panels, invoke }`,客户端 `export default { panels: { picker } }` | ✓ |
30
- | 配置 | `WorldContext.cfg` 是活引用,改动走 `ctx.persist(patch)` | 动作库路径就是这么存的 |
31
- | 目录 | `WorldContext.botDir` 是部署目录,桌宠数据在它下面 `data/figures` | 优先用它定位,不再瞎猜 |
32
-
33
- 没有引入 `cortico/*` 任何模块,所以**不走宿主的 tsx 解析链**,纯 ESM 直接被 `import()` 加载;
34
- 整个包里没有 `eval` / `new Function` / 子进程 / 本地 HTTP 服务。
35
-
36
- **注入面**(写入是唯一碰磁盘的地方,`src/writer.js` 全部收紧):
37
-
38
- - 只写 `<pack>/额外动作拓展/`,写之前校验路径确实在那个包里(`isInside`,挡 `..`、盘符、越界);
39
- - 拷帧**只认清单里那 frames 张 `f_NNNN.webp`**,符号链接、非常规文件、>4 MB 的帧、>64 MB 的模块一律拒绝;
40
- 不做整目录递归拷贝 —— 动作库里多塞一个 `payload.js` 也不会进包;
41
- - `action.json` 不复制,按校验过的字段重写;
42
- - 生成的 `额外动作拓展/index.js` 是**数据**:所有字符串走 `JSON.stringify`,id/分类/路径先过
43
- `^[a-z0-9][a-z0-9-]{0,31}$` 白名单,名字去掉控制字符与行分隔符;
44
- - `figure.json` 只动 `vocab` 一个字段;
45
- - 面板侧对拿到的清单同样再筛一遍(id/分类/帧数/时长/缩略图前缀),不信任 invoker 传来的任何东西;
46
- - `invoke` 的参数当不可信输入:包 id 必须匹配 slug 正则,一次最多 300 个动作。
47
-
48
- ---
49
-
50
- ## 一、装
51
-
52
- ### 方式 A:npm 装(推荐)
53
-
54
- ```bat
55
- cd "<Coo 安装目录>\data\extensions"
56
- npm install cortico-world-extra-actions
57
- ```
58
-
59
- Coopanion 启动时会自己扫 `data\extensions\node_modules`,装完**重启 Coopanion** 就行,
60
- 不需要额外脚本(`install-extension.mjs` 只服务于下面这种方式)。
61
- 包里 `dependencies` 只有 `cortico-world-extra-actions` 这一条,不会动别的扩展。
62
-
63
- ### 方式 B:拿 zip / 源码目录(离线、要改代码时用)
64
-
65
- ```bat
66
- node tools/install-extension.mjs --extensions "<Coo 安装目录>\data\extensions"
67
- :: 或先设环境变量 COOPANION_EXTENSIONS
68
- ```
69
-
70
- 它会:把本目录拷到 `<extensions>\vendor\cortico-world-extra-actions\`,
71
- 在 `data\extensions\package.json` 里加一条 `link:` 依赖(先备份 `package.json.bak-extra-actions`),
72
- 再建一个 `node_modules` 联接。**然后重启 Coopanion**。
73
-
74
- 手动做同样三步:
75
-
76
- 1. 把整个文件夹拷到 `...\data\extensions\vendor\cortico-world-extra-actions\`
77
- 2. `data\extensions\package.json` 的 `dependencies` 里加一行:
78
- `"cortico-world-extra-actions": "link:vendor/cortico-world-extra-actions"`
79
- 3. 建联接(管理员不需要,junction 就行):
80
- `mklink /J "...\data\extensions\node_modules\cortico-world-extra-actions" "...\data\extensions\vendor\cortico-world-extra-actions"`
81
-
82
- 重启后,Coopanion 的扩展页里会出现「额外动作拓展」。
83
-
84
- > `tools/` 只随 npm 包和 zip 一起发,仓库里也有;`node tools/extra-actions-cli.mjs` 那套命令行
85
- > 两种装法都能用。
86
-
87
- ## 二、用
88
-
89
- 面板里:
90
-
91
- 1. 上方选一个**可写**的角色包(只有会读 `额外动作拓展/` 的播放器才列出来 —— 目前是
92
- 《深深 · 动作库》`shenshen-actions`,以及打了对应补丁的深深)。
93
- 2. 左下的分类芯片 + 搜索框筛动作;点一行就勾上/取消。
94
- 3. 右下「保存随机列表」。
95
-
96
- **列表永远是完整的一套固定目录(105 条)**,跟库里有没有素材无关:
97
-
98
- - 库里有的那几条正常显示、可以勾
99
- - 库里还没有的:缩略图发灰、标签写「库里没有 · 缺帧」、复选框点不动
100
- - 每一条鼠标悬停都会显示它的**固定目录**(`actions/<分类>/<id>`),方便你照着往库里补
101
- - 底部汇总:`清单 105 条:库里 N · 缺 M`
102
-
103
- 四个库/包相关的按钮:
104
-
105
- | 按钮 | 作用 |
106
- |---|---|
107
- | 选择动作库位置… | 手动指一个已有的动作库目录(路径会被记住) |
108
- | 用自带示例建库… | 在你会选的目录下建 `<你选的目录>\深深-动作库`(3 段示例)并设为当前库 |
109
- | 自动寻找动作库… | 把本机像动作库的目录扫出来列成候选,点一行就切过去 |
110
- | 建立空的角色包(选位置) | 建一个只有 4 段身体状态、词表空、没有额外动作的空角色包,放哪由你选 |
111
-
112
- 保存时它做的事:
113
-
114
- - 勾中的模块:从动作库把整段动画(高清单文件 `anim.webp`,或帧序列 `f_0001.webp…`)+
115
- `preview.webp` + `action.json` 拷进 `<包>/额外动作拓展/<分类>/<id>/`(已经拷过的不重复拷)
116
- - 取消勾选的:删掉对应目录
117
- - 重写 `额外动作拓展/index.js`(桌宠 import 的那份清单)、`index.json`、`README.md`
118
- - **把 `figure.json` 的动作词裁成你勾的这些**:勾中的加进去,没勾的动作词撤掉(表情、非动作条目一个字不动)。
119
- 第一次改之前备份 `figure.json.bak-额外动作拓展`,原始词表记在 `.managed.json` 里
120
- - **不碰桌宠**:插件只读桌宠的 /api/state、/api/figures。要让新动作立刻生效,去 Coopanion 的**装扮页**重新点一下这个形象
121
-
122
- 所以语义是 **勾选即全部**:勾了什么,桌宠就只做这些 —— 待机轮播、点击回应、bot 能说的动作词,
123
- 都收在这次勾选里。没勾的动作不会自己冒出来。
124
-
125
- **名词生效时机**:`figure.json` 是 Coopanion 启动时扫的,所以 bot 要**重启后**才会说
126
- `【吃饺子】`;在那之前动作已经在待机轮播和点击里了。
127
-
128
- 命令行(不用面板也能干同样的事):
129
-
130
- ```bat
131
- node tools\extra-actions-cli.mjs list
132
- node tools\extra-actions-cli.mjs state
133
- node tools\extra-actions-cli.mjs save --pack shenshen-actions --ids eat-dumplings,fireworks,cheer-wave
134
- node tools\extra-actions-cli.mjs clear --pack shenshen-actions
135
- ```
136
-
137
- ## 三、`额外动作拓展/` 长什么样
138
-
139
- ```
140
- <形象包>/额外动作拓展/
141
- ├─ index.js ← 桌宠读的就是这个
142
- ├─ index.json 同一份内容,给工具和人看
143
- ├─ README.md 这一份是谁写的、什么时候、勾了什么
144
- ├─ .managed.json 插件管过哪些动作、加过哪些词(取消勾选和恢复时用)
145
- └─ eat/eat-dumplings/
146
- ├─ anim.webp 640×360,24 fps,整段一个文件(推荐,高清)
147
- │ (或者 f_0001.webp … f_0241.webp 帧序列,老格式同样认)
148
- ├─ preview.webp
149
- └─ action.json
150
- ```
151
-
152
- `index.js`:
153
-
154
- ```js
155
- export default [
156
- { word: "eat-dumplings", clip: "额外动作拓展/eat/eat-dumplings", frames: 241, fps: 24,
157
- seconds: 10.042, name: "吃饺子", category: "eat", anim: true,
158
- noMirror: false, reaction: false, random: true },
159
- ];
160
- ```
161
-
162
- `anim: true` 告诉播放器「这个目录是一个整段动图」,它就直接挂一个 `<image>` 让浏览器自己循环,
163
- 不再逐帧换 `src`。没有这个字段也认:播放器会先探一下 `anim.webp` 在不在。
164
-
165
- 播放器把这一份并到 `actions/index.js` 后面(同名词以这份为准),`word` 不为空的登记进词表。
166
- 所以只要播放器认这个格式,**换一个形象包也能直接复用这个文件夹**。
167
-
168
- ## 四、限制与边界
169
-
170
- - **只支持帧序列播放器**:入口 `figure.js` 里得出现 `额外动作拓展` 或 `actions/index.js`
171
- (单文件 `anim.webp` 和帧序列两种模块都认)。
172
- 《深深 · 动作库》和本仓库配套的那个播放器可以;早先只认 `ext/clips.js` 的补丁、以及 horo /
173
- clawd 这些别的角色都不行(面板里不会列出来)。
174
- - **帧画的是深深**:这是整段画好的 640×360 立绘,不是分层部件。加进别的角色会穿帮,
175
- 也没法叠在别人的立绘上 —— 面板会提示。
176
- - **状态类动作不勾**:`state-idle / state-walk / state-drag / look-around` 是身体的待机、走路、
177
- 被拎起和转向,勾了没用(它们本来就在包里)。
178
- - **只写可写的包**:Coo / 鲸鱼这些内置包不会被列出来。
179
- - **可逆**:`figure.json` 只动插件自己加过的词;一键「清空随机动作列表」会删掉整个
180
- `额外动作拓展/` 并把词撤干净。改动前的原文在 `figure.json.bak-额外动作拓展`。
181
-
182
- ## 动作库放哪(固定,不用另外下载)
183
-
184
- 动作库就是**一个固定的文件夹**,结构固定:
185
-
186
- ```
187
- <动作库>/
188
- └─ actions/
189
- ├─ index.js 清单(可由 action.json 重建)
190
- └─ <分类>/<id>/ 分类与 id 都在白名单内
191
- ├─ action.json
192
- ├─ f_0001.webp …
193
- └─ preview.webp(可选)
194
- ```
195
-
196
- - 首次启用时插件把自带的示例库铺到 `<dataDir>\shenshen-library`,路径记在
197
- `config.json` 的 `worlds.extra-actions.libraryDir`,面板上直接显示
198
- - 想换位置或换一个库:点「自动寻找动作库…」让它自己扫出来,或用「选择动作库…」手动指
199
- - **不需要**去任何地方下载动作库;动作不够就点「添加更多动作…」自己收进来
200
-
201
- ## 五、添加更多动作
202
-
203
- 面板最下面有一个折叠的 **「添加更多动作…」**:选一个文件夹,里面是一整套
204
- `f_0001.webp`、`f_0002.webp`…(同尺寸),或者一个装着若干这种文件夹的父目录。
205
- 它会:
206
-
207
- 1. 把帧收进 `<动作库>/actions/<分类>/<id>/`(默认分类 `extra`,同名 id 自动加 `-2`);
208
- 2. 按「帧数 ÷ fps」算时长,写一个 `action.json`;
209
- 3. 往 `actions/index.js` 追加一行 —— 桌宠的播放器就认它。
210
-
211
- 收进来之后,这些动作和自带的 105 段一样出现在上面的列表里,可以勾选、保存随机列表。
212
- 可选在同目录放 `action.json` 指定 `{"id":"eat-burger","zh":"吃汉堡","category":"extra","fps":24}`;
213
- 不给就按目录名生成、24 fps。
214
-
215
- 安全上和写入层同一套:只拷贝 `f_NNNN.webp`(源目录里别的东西不会进库)、拒绝符号链接、
216
- 单帧 ≤4 MB / 单模块 ≤128 MB、id 与分类过白名单、`index.js` 里所有字符串走 `JSON.stringify`。
217
-
218
- 命令行同样能加:`node tools\extra-actions-cli.mjs add --dir <文件夹>`。
219
-
220
- ## 六、制作
221
-
222
- 面板最下面还有一个折叠的 **「制作」**,放着两位制作人的头像与分工(头像以 data URL 嵌在面板里,
223
- 不读本地文件、不发网络请求,默认折叠,不影响日常勾选):
224
-
225
- - **Daniele贤狼赫萝(丹尼尔)** —— 形象包机制与插件制作 · `1143669795@qq.com`
226
- - **奶糖_Net(Net-ang)** —— 制作 · 素材与实现 · `2967731401@qq.com`
227
-
228
- 形象包的 `figure.json` 里也记了这两条 `credits`。
229
-
230
- ## 七、文件
231
-
232
- | 路径 | 作用 |
233
- |---|---|
234
- | `src/index.js` | World 定义(`id` / `label` / `defaults` / `create` / `describe`) |
235
- | `src/world.js` | 面板方法、形象包发现、保存/清空、扫库清单、参数校验 |
236
- | `src/writer.js` | 纯落盘逻辑 + 注入面防护(面板和命令行共用) |
237
- | `src/importer.js` | 「添加更多动作」:校验一套帧、收进动作库、重建清单 |
238
- | `src/starter.js` | 自带素材落地 + 「建立空的角色包」 |
239
- | `src/pet.js` | 本地桌宠服务的**只读**客户端(`/api/state`、`/api/figures`) |
240
- | `dist/webui.js` | 面板(无 import 的纯 ESM,`export default { panels: { picker } }`) |
241
- | `assets/catalog.json` | 105 段动作的清单 + 缩略图 |
242
- | `assets/starter/` | 自带的形象包与示例动作库(首次启动落地) |
243
- | `assets/icon.webp` | 扩展封面(`cortico.icon`) |
244
- | `tools/install-extension.mjs` | 装到 Coopanion(拷包 + link 依赖 + junction),需要 `--extensions` |
245
- | `tools/extra-actions-cli.mjs` | 命令行:list / state / save / remove / clear / add / prune / reindex |
246
- | `tools/check-registered.mjs` | 自检:宿主能不能按 name 解析到这个包、config 里有没有它 |
247
- | `tools/verify_installed.mjs` | 对真机:装好的包是不是只做勾选的那些 |
248
- | `tools/test_writer.mjs` | 保存 / 删除 / 清空 / 瘦身的落盘语义 |
249
- | `tools/test_security.mjs` | 注入面:路径、白名单、符号链接 |
250
- | `tools/test_importer.mjs` | 「添加更多动作」 |
251
- | `tools/test_catalog.mjs` | 清单以磁盘为准、index 可重建 |
252
- | `tools/test_panel_guard.mjs` | 面板模板缺节点会当场报错 |
253
- | `tools/test_starter.mjs` | 自带素材的首次落地 |
254
- | `tools/test_restore.mjs` | 「建立空的角色包」与查重 |
1
+ # 深深与额外动作拓展(Coopanion 扩展)
2
+
3
+ `cortico-world-extra-actions` · MIT · 作者:Daniele贤狼赫萝 & 奶糖_Net(丹尼尔 / Net-ang)
4
+ 发布流程(打 tag、`npm publish`)写在仓库根目录的 `PUBLISH.md` 里,不随包分发。
5
+
6
+ 把《深深 · 动作库》里的 105 段动作做成一张勾选表:勾中的动作写进形象包的
7
+ `额外动作拓展/` 文件夹,桌宠照着做 —— 待机会轮播、点她会触发、重启后 bot 也能点名。
8
+
9
+ 素材全是 **640×360 高清**:动作库一段一个 `anim.webp`(整段动图,加载快、不逐帧换图),
10
+ 插件自带的示例形象包(4 段身体状态 + 3 段示例动作)也是同一套高清,新装的人第一眼就不糊。
11
+
12
+ - 插件形态:Cortico World(`kind: world`, `api: 6`),面板在 Coopanion 的扩展页里;显示名 **深深与额外动作拓展**
13
+ - 数据落点:`<形象包>/额外动作拓展/`(桌宠读的东西)+ `worlds.extra-actions.libraryDir`(走 `WorldContext.persist` 存进 config.json)
14
+ - 不改播放器、不改形象包的其它文件;`figure.json` 只增删它自己管过的那几个词,第一次动之前留备份
15
+
16
+ ## 零、协议与安全(先看这段)
17
+
18
+ 这个包是 **Cortico World**,不是往主程序里塞代码。契约按安装目录里的源码
19
+ (`resources/app/build/cortico/src/`)核对过:
20
+
21
+ | 契约 | 要求 | 本包 |
22
+ |---|---|---|
23
+ | `package.json` → `cortico.kind` | `world` / `provider` / `bot` | `world` ✓ |
24
+ | `cortico.api` | 必须**正好**是 `EXTENSION_API_VERSIONS.world = 6` | `6` ✓ |
25
+ | `cortico.webUiClient` | 包内相对路径、不含 `\`、不以 `/` 开头、无 `..`、`.js/.mjs` | `dist/webui.js` ✓ |
26
+ | `keywords` | 要有 `cortico-world` | ✓ |
27
+ | 默认导出 | 有 `id` / `label` / `defaults()` / `create()` | ✓(`isWorldDefinition` 就查这四项) |
28
+ | 实例 | `start(host)` / `stop()` / `envPromptVars()` / `tools()` | ✓(`tools()` 返回空数组:不给 bot 任何可调用的写入口) |
29
+ | 面板 | `webUi(language)` 返回 `{ label, panels, invoke }`,客户端 `export default { panels: { picker } }` | ✓ |
30
+ | 配置 | `WorldContext.cfg` 是活引用,改动走 `ctx.persist(patch)` | 动作库路径就是这么存的 |
31
+ | 目录 | `WorldContext.botDir` 是部署目录,桌宠数据在它下面 `data/figures` | 优先用它定位,不再瞎猜 |
32
+
33
+ 没有引入 `cortico/*` 任何模块,所以**不走宿主的 tsx 解析链**,纯 ESM 直接被 `import()` 加载;
34
+ 整个包里没有 `eval` / `new Function` / 子进程 / 本地 HTTP 服务。
35
+
36
+ **注入面**(写入是唯一碰磁盘的地方,`src/writer.js` 全部收紧):
37
+
38
+ - 只写 `<pack>/额外动作拓展/`,写之前校验路径确实在那个包里(`isInside`,挡 `..`、盘符、越界);
39
+ - 拷帧**只认清单里那 frames 张 `f_NNNN.webp`**,符号链接、非常规文件、>4 MB 的帧、>64 MB 的模块一律拒绝;
40
+ 不做整目录递归拷贝 —— 动作库里多塞一个 `payload.js` 也不会进包;
41
+ - `action.json` 不复制,按校验过的字段重写;
42
+ - 生成的 `额外动作拓展/index.js` 是**数据**:所有字符串走 `JSON.stringify`,id/分类/路径先过
43
+ `^[a-z0-9][a-z0-9-]{0,31}$` 白名单,名字去掉控制字符与行分隔符;
44
+ - `figure.json` 只动 `vocab` 一个字段;
45
+ - 面板侧对拿到的清单同样再筛一遍(id/分类/帧数/时长/缩略图前缀),不信任 invoker 传来的任何东西;
46
+ - `invoke` 的参数当不可信输入:包 id 必须匹配 slug 正则,一次最多 300 个动作。
47
+
48
+ ---
49
+
50
+ ## 一、装
51
+
52
+ ### 方式 A:npm 装(推荐)
53
+
54
+ ```bat
55
+ cd "<Coo 安装目录>\data\extensions"
56
+ npm install cortico-world-extra-actions
57
+ ```
58
+
59
+ Coopanion 启动时会自己扫 `data\extensions\node_modules`,装完**重启 Coopanion** 就行,
60
+ 不需要额外脚本(`install-extension.mjs` 只服务于下面这种方式)。
61
+ 包里 `dependencies` 只有 `cortico-world-extra-actions` 这一条,不会动别的扩展。
62
+
63
+ ### 方式 B:拿 zip / 源码目录(离线、要改代码时用)
64
+
65
+ ```bat
66
+ node tools/install-extension.mjs --extensions "<Coo 安装目录>\data\extensions"
67
+ :: 或先设环境变量 COOPANION_EXTENSIONS
68
+ ```
69
+
70
+ 它会:把本目录拷到 `<extensions>\vendor\cortico-world-extra-actions\`,
71
+ 在 `data\extensions\package.json` 里加一条 `link:` 依赖(先备份 `package.json.bak-extra-actions`),
72
+ 再建一个 `node_modules` 联接。**然后重启 Coopanion**。
73
+
74
+ 手动做同样三步:
75
+
76
+ 1. 把整个文件夹拷到 `...\data\extensions\vendor\cortico-world-extra-actions\`
77
+ 2. `data\extensions\package.json` 的 `dependencies` 里加一行:
78
+ `"cortico-world-extra-actions": "link:vendor/cortico-world-extra-actions"`
79
+ 3. 建联接(管理员不需要,junction 就行):
80
+ `mklink /J "...\data\extensions\node_modules\cortico-world-extra-actions" "...\data\extensions\vendor\cortico-world-extra-actions"`
81
+
82
+ 重启后,Coopanion 的扩展页里会出现「额外动作拓展」。
83
+
84
+ > `tools/` 只随 npm 包和 zip 一起发,仓库里也有;`node tools/extra-actions-cli.mjs` 那套命令行
85
+ > 两种装法都能用。
86
+
87
+ ## 二、用
88
+
89
+ 面板里:
90
+
91
+ 1. 上方选一个**可写**的角色包(只有会读 `额外动作拓展/` 的播放器才列出来 —— 目前是
92
+ 《深深 · 动作库》`shenshen-actions`,以及打了对应补丁的深深)。
93
+ 2. 左下的分类芯片 + 搜索框筛动作;点一行就勾上/取消。
94
+ 3. 右下「保存随机列表」。
95
+
96
+ **列表永远是完整的一套固定目录(105 条)**,跟库里有没有素材无关:
97
+
98
+ - 库里有的那几条正常显示、可以勾
99
+ - 库里还没有的:缩略图发灰、标签写「库里没有 · 缺帧」、复选框点不动
100
+ - 每一条鼠标悬停都会显示它的**固定目录**(`actions/<分类>/<id>`),方便你照着往库里补
101
+ - 底部汇总:`清单 105 条:库里 N · 缺 M`
102
+
103
+ 四个库/包相关的按钮:
104
+
105
+ | 按钮 | 作用 |
106
+ |---|---|
107
+ | 选择动作库位置… | 手动指一个已有的动作库目录(路径会被记住) |
108
+ | 用自带示例建库… | 在你会选的目录下建 `<你选的目录>\深深-动作库`(3 段示例)并设为当前库 |
109
+ | 自动寻找动作库… | 把本机像动作库的目录扫出来列成候选,点一行就切过去 |
110
+ | 建立空的角色包(选位置) | 建一个只有 4 段身体状态、词表空、没有额外动作的空角色包,放哪由你选 |
111
+
112
+ 保存时它做的事:
113
+
114
+ - 勾中的模块:从动作库把整段动画(高清单文件 `anim.webp`,或帧序列 `f_0001.webp…`)+
115
+ `preview.webp` + `action.json` 拷进 `<包>/额外动作拓展/<分类>/<id>/`(已经拷过的不重复拷)
116
+ - 取消勾选的:删掉对应目录
117
+ - 重写 `额外动作拓展/index.js`(桌宠 import 的那份清单)、`index.json`、`README.md`
118
+ - **把 `figure.json` 的动作词裁成你勾的这些**:勾中的加进去,没勾的动作词撤掉(表情、非动作条目一个字不动)。
119
+ 第一次改之前备份 `figure.json.bak-额外动作拓展`,原始词表记在 `.managed.json` 里
120
+ - **保存完自己让桌宠重载**(0.3.34 起):保存/删除/清空/瘦身之后,如果桌宠正在用这个形象,
121
+ 插件会把它**原样回填一次**(等价于装扮页重新点一下,幂等、不改任何设置),动作表立即生效 ——
122
+ 点击回应、拖动、待机轮播都算。桌宠没开、或者当前用的不是这个包,会如实提示没生效。
123
+ > 边界没变:插件不能换形象、不能改配色,回填的永远是 `/api/state` 里的现值。
124
+
125
+ 所以语义是 **勾选即全部**:勾了什么,桌宠就只做这些 —— 待机轮播、点击回应、bot 能说的动作词,
126
+ 都收在这次勾选里。没勾的动作不会自己冒出来。
127
+
128
+ **名词生效时机**:`figure.json` 是 Coopanion 启动时扫的,所以 bot 要**重启后**才会说
129
+ `【吃饺子】`;在那之前动作已经在待机轮播和点击里了(0.3.34 起不用再去装扮页点)。
130
+
131
+ 命令行(不用面板也能干同样的事):
132
+
133
+ ```bat
134
+ node tools\extra-actions-cli.mjs list
135
+ node tools\extra-actions-cli.mjs state
136
+ node tools\extra-actions-cli.mjs save --pack shenshen-actions --ids eat-dumplings,fireworks,cheer-wave
137
+ node tools\extra-actions-cli.mjs clear --pack shenshen-actions
138
+ ```
139
+
140
+ ## 三、`额外动作拓展/` 长什么样
141
+
142
+ ```
143
+ <形象包>/额外动作拓展/
144
+ ├─ index.js ← 桌宠读的就是这个
145
+ ├─ index.json 同一份内容,给工具和人看
146
+ ├─ README.md 这一份是谁写的、什么时候、勾了什么
147
+ ├─ .managed.json 插件管过哪些动作、加过哪些词(取消勾选和恢复时用)
148
+ └─ eat/eat-dumplings/
149
+ ├─ anim.webp 640×360,24 fps,整段一个文件(推荐,高清)
150
+ │ (或者 f_0001.webp … f_0241.webp 帧序列,老格式同样认)
151
+ ├─ preview.webp
152
+ └─ action.json
153
+ ```
154
+
155
+ `index.js`:
156
+
157
+ ```js
158
+ export default [
159
+ { word: "eat-dumplings", clip: "额外动作拓展/eat/eat-dumplings", frames: 241, fps: 24,
160
+ seconds: 10.042, name: "吃饺子", category: "eat", anim: true,
161
+ noMirror: false, reaction: false, random: true },
162
+ ];
163
+ ```
164
+
165
+ `anim: true` 告诉播放器「这个目录是一个整段动图」,它就直接挂一个 `<image>` 让浏览器自己循环,
166
+ 不再逐帧换 `src`。没有这个字段也认:播放器会先探一下 `anim.webp` 在不在。
167
+
168
+ 播放器把这一份并到 `actions/index.js` 后面(同名词以这份为准),`word` 不为空的登记进词表。
169
+ 所以只要播放器认这个格式,**换一个形象包也能直接复用这个文件夹**。
170
+
171
+ ## 四、限制与边界
172
+
173
+ - **只支持帧序列播放器**:入口 `figure.js` 里得出现 `额外动作拓展` 或 `actions/index.js`
174
+ (单文件 `anim.webp` 和帧序列两种模块都认)。
175
+ 《深深 · 动作库》和本仓库配套的那个播放器可以;早先只认 `ext/clips.js` 的补丁、以及 horo /
176
+ clawd 这些别的角色都不行(面板里不会列出来)。
177
+ - **帧画的是深深**:这是整段画好的 640×360 立绘,不是分层部件。加进别的角色会穿帮,
178
+ 也没法叠在别人的立绘上 —— 面板会提示。
179
+ - **状态类动作不勾**:`state-idle / state-walk / state-drag / look-around` 是身体的待机、走路、
180
+ 被拎起和转向,勾了没用(它们本来就在包里)。
181
+ - **只写可写的包**:Coo / 鲸鱼这些内置包不会被列出来。
182
+ - **可逆**:`figure.json` 只动插件自己加过的词;一键「清空随机动作列表」会删掉整个
183
+ `额外动作拓展/` 并把词撤干净。改动前的原文在 `figure.json.bak-额外动作拓展`。
184
+
185
+ ## 动作库放哪 / 两档下载
186
+
187
+ 动作库就是**一个固定的文件夹**,结构固定:
188
+
189
+ ```
190
+ <动作库>/
191
+ └─ actions/
192
+ ├─ index.js 清单(可由 action.json 重建)
193
+ └─ <分类>/<id>/ 分类与 id 都在白名单内
194
+ ├─ action.json
195
+ ├─ f_0001.webp …
196
+ └─ preview.webp(可选)
197
+ ```
198
+
199
+ - 首次启用时插件把自带的示例库铺到 `<dataDir>\shenshen-library`,路径记在
200
+ `config.json` 的 `worlds.extra-actions.libraryDir`,面板上直接显示
201
+ - 想换位置或换一个库:点「自动寻找动作库…」让它自己扫出来,或用「选择动作库…」手动指
202
+ - 面板里有**两档一键下载**(插件自己下、自己解压、自己装好):
203
+
204
+ | 档位 | 体积 | 编码 | Gitee 仓库 / tag |
205
+ |---|---|---|---|
206
+ | 轻版 | 约 370 MB(8 卷) | VP8 有损 | `shenshen-actions` / `library` |
207
+ | 完整版 | 约 1.19 GB(16 卷) | VP8L 无损 | `shenshen-actions` / `library-full`(lib-1..8)<br>`shenshen-actions-full` / `library-full`(lib-9..16) |
208
+
209
+ - 两档都是 105 段、id 完全一致;完整版只是每帧不再有 VP8 压缩痕迹,体积约 3.1 倍
210
+ - 单独补某一段:点那一行右侧的「↓ 下载」,走 `per-action/<id>.zip`
211
+
212
+ ## 五、添加更多动作
213
+
214
+ 面板最下面有一个折叠的 **「添加更多动作…」**:选一个文件夹,里面是一整套
215
+ `f_0001.webp`、`f_0002.webp`…(同尺寸),或者一个装着若干这种文件夹的父目录。
216
+ 它会:
217
+
218
+ 1. 把帧收进 `<动作库>/actions/<分类>/<id>/`(默认分类 `extra`,同名 id 自动加 `-2`);
219
+ 2. 按「帧数 ÷ fps」算时长,写一个 `action.json`;
220
+ 3. 往 `actions/index.js` 追加一行 —— 桌宠的播放器就认它。
221
+
222
+ 收进来之后,这些动作和自带的 105 段一样出现在上面的列表里,可以勾选、保存随机列表。
223
+ 可选在同目录放 `action.json` 指定 `{"id":"eat-burger","zh":"吃汉堡","category":"extra","fps":24}`;
224
+ 不给就按目录名生成、24 fps。
225
+
226
+ 安全上和写入层同一套:只拷贝 `f_NNNN.webp`(源目录里别的东西不会进库)、拒绝符号链接、
227
+ 单帧 ≤4 MB / 单模块 ≤128 MB、id 与分类过白名单、`index.js` 里所有字符串走 `JSON.stringify`。
228
+
229
+ 命令行同样能加:`node tools\extra-actions-cli.mjs add --dir <文件夹>`。
230
+
231
+ ## 六、制作
232
+
233
+ 面板最下面还有一个折叠的 **「制作」**,放着两位制作人的头像与分工(头像以 data URL 嵌在面板里,
234
+ 不读本地文件、不发网络请求,默认折叠,不影响日常勾选):
235
+
236
+ - **Daniele贤狼赫萝(丹尼尔)** —— 形象包机制与插件制作 · `1143669795@qq.com`
237
+ - **奶糖_Net(Net-ang)** —— 制作 · 素材与实现 · `2967731401@qq.com`
238
+
239
+ 形象包的 `figure.json` 里也记了这两条 `credits`。
240
+
241
+ ## 七、文件
242
+
243
+ | 路径 | 作用 |
244
+ |---|---|
245
+ | `src/index.js` | World 定义(`id` / `label` / `defaults` / `create` / `describe`) |
246
+ | `src/world.js` | 面板方法、形象包发现、保存/清空、扫库清单、参数校验 |
247
+ | `src/writer.js` | 纯落盘逻辑 + 注入面防护(面板和命令行共用) |
248
+ | `src/importer.js` | 「添加更多动作」:校验一套帧、收进动作库、重建清单 |
249
+ | `src/starter.js` | 自带素材落地 + 「建立空的角色包」 |
250
+ | `src/pet.js` | 本地桌宠服务的**只读**客户端(`/api/state`、`/api/figures`) |
251
+ | `dist/webui.js` | 面板(无 import 的纯 ESM,`export default { panels: { picker } }`) |
252
+ | `assets/catalog.json` | 105 段动作的清单 + 缩略图 |
253
+ | `assets/starter/` | 自带的形象包与示例动作库(首次启动落地) |
254
+ | `assets/icon.webp` | 扩展封面(`cortico.icon`) |
255
+ | `tools/install-extension.mjs` | 装到 Coopanion(拷包 + link 依赖 + junction),需要 `--extensions` |
256
+ | `tools/extra-actions-cli.mjs` | 命令行:list / state / save / remove / clear / add / prune / reindex |
257
+ | `tools/check-registered.mjs` | 自检:宿主能不能按 name 解析到这个包、config 里有没有它 |
258
+ | `tools/verify_installed.mjs` | 对真机:装好的包是不是只做勾选的那些 |
259
+ | `tools/test_writer.mjs` | 保存 / 删除 / 清空 / 瘦身的落盘语义 |
260
+ | `tools/test_security.mjs` | 注入面:路径、白名单、符号链接 |
261
+ | `tools/test_importer.mjs` | 「添加更多动作」 |
262
+ | `tools/test_catalog.mjs` | 清单以磁盘为准、index 可重建 |
263
+ | `tools/test_panel_guard.mjs` | 面板模板缺节点会当场报错 |
264
+ | `tools/test_starter.mjs` | 自带素材的首次落地 |
265
+ | `tools/test_restore.mjs` | 「建立空的角色包」与查重 |