dsh-plugin-wallpaper-engine-mascot-avatar 0.0.0-stage → 1.4.0
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/cordis.patch.yml +14 -0
- package/icon.png +0 -0
- package/lib/index.js +147 -0
- package/lib/routes/avatar.js +137 -0
- package/lib/routes/mascot.js +124 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +27 -4
- package/README.md +0 -3
package/cordis.patch.yml
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# cordis.patch.yml — 「吉祥物 / 会话头像」子包自己的行(ADR-0014 S4.1 / S4.2 / S4.4)。
|
|
2
|
+
#
|
|
3
|
+
# ⚠️ 一次安装形态(主包 patch 用 name 引用子包,ADR-0014 S4.1)下,这一行由**主包**的
|
|
4
|
+
# cordis.patch.yml 插入;只有把这个子包自己当成独立 bundle 时
|
|
5
|
+
# (各自 dsh.bundle.patch + 各自进 dsh.profile.bundles,**不采纳**)本文件才生效。
|
|
6
|
+
# 两处同时插同一个 id 会撞车 ⇒ 接线时以主包那份为准,本文件保持与它逐字一致(ADR-0014 S4.2)。
|
|
7
|
+
#
|
|
8
|
+
# 行名 = 真实包名(裸真名):本版 DSH 不传 bareModuleBaseUrl ⇒ 行名一律从 <profile>/cordis.yml
|
|
9
|
+
# 旁起算,裸名 → <profile>/node_modules/<name>;开发期靠 scripts/dev-link-subpackages.mjs 建的
|
|
10
|
+
# junction 让这个名字出现在 profile/node_modules 里(ADR-0014 S4.4),发布期靠传递依赖 hoist。
|
|
11
|
+
# id 一旦定下不再改(ADR-0014 S4.3)。
|
|
12
|
+
- insert:
|
|
13
|
+
- id: wallpaper-engine-mascot-avatar
|
|
14
|
+
name: 'dsh-plugin-wallpaper-engine-mascot-avatar'
|
package/icon.png
ADDED
|
Binary file
|
package/lib/index.js
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `mascot-avatar` 子包宿主入口(P-F 第二格:`lib/components/mascot-avatar/` → `packages/mascot-avatar/`)。
|
|
3
|
+
*
|
|
4
|
+
* 为什么这两族合成**一格**出户:它们是同一套形态的两条腿(POST 导入 raw body + MIME 白名单 /
|
|
5
|
+
* GET·HEAD 查看 / DELETE 清除,见本包 `lib/routes/avatar.js` 与 `lib/routes/mascot.js` 的文件头),
|
|
6
|
+
* 共用同一批内核服务层符号(目录 / 上限 / 原子落盘 / 请求收尾)与同一条用户资产语义。拆成两行
|
|
7
|
+
* 只会让"头像两个 side + 立绘只有一张"这套不变量散在两处。
|
|
8
|
+
*
|
|
9
|
+
* 两处加载路径共用同一份实现(照抄 dsh-ops 的组件真形):
|
|
10
|
+
* ① 宿主把 patch 行的 `name` 当**独立 plugin** 加载 ⇒ `apply(ctx, config)` 是入口;
|
|
11
|
+
* ② 门面的 `applyComponent(root, rawConfig, 'mascot-avatar')` 是"按组件加载"入口。
|
|
12
|
+
* P-F 之后两条路径的 deps **不再是两份各写各的字面量**:门面与入口都从
|
|
13
|
+
* `lib/subpackage-boot.js` 的 `subpackageKeys('mascot-avatar', ctx)` 取**同一份冻结键视图**
|
|
14
|
+
* ⇒ 两条路径不可能漂移(对账面 = `test/verify-inject-contracts.mjs` ② 的叶子冻结表逐键对账)。
|
|
15
|
+
*
|
|
16
|
+
* ⚠️ **跨包纪律(ADR-0014 S5.1 / S5.2,判据 `test/verify-subpackage-purity.mjs`)**:本模块
|
|
17
|
+
* **零主包说明符、零相对路径逃出本包** —— 只 import 本包内的路由族。宿主能力一律经
|
|
18
|
+
* `ctx.wallpaperEngineHost` 的键视图(`host.keys('mascot-avatar', ctx)`)取。这不是风格问题:
|
|
19
|
+
* 相对 import 主包文件、或 import 主包名,都是该判据的硬红。
|
|
20
|
+
*
|
|
21
|
+
* ⚠️ **取服务姿势**:`inject` 必须先声明(`webServer` + `wallpaperEngineHost`)再读
|
|
22
|
+
* `ctx.<服务>`。cordis 的 reflect `get` 对「未声明 inject 就取的服务属性」当场抛
|
|
23
|
+
* `cannot get property "webServer" without inject at applyImpl`(真机原文),随后的早退分支
|
|
24
|
+
* 永远执行不到(死代码),两条装载路径双双失败、该组件的路由全 404。声明 inject 后由 Loader
|
|
25
|
+
* 保证「服务就绪才激活」,下面的早退分支只兜「服务在、但路由表还没挂上」这一种情况。
|
|
26
|
+
* 依据:主行 `lib/index.js` 的 `inject` 声明 早就 `export const inject = ['webServer']`,即整包本来
|
|
27
|
+
* 就硬依赖 web 服务(没有 webServer 的 profile 里裸行自身就 pending)⇒ 组件行补同一句**不引入
|
|
28
|
+
* 任何新假设**;反过来「缺服务就软失败」是个假前提,会把「没挂上」伪装成「激活成功」。
|
|
29
|
+
* 对应判据:`test/verify-bundle-rows.mjs` ⑧(入口读的每个 `ctx.<服务>` 都必须在其 inject 里)。
|
|
30
|
+
*
|
|
31
|
+
* ⚠️ **teardown 得交两份(关掉再打开子组件会撞 `duplicate … route`)**:本模块导出的 `apply`
|
|
32
|
+
* 是**函数声明**(有 `prototype`)⇒ cordis 的 loader 走 `new apply(ctx, config)` 分支、
|
|
33
|
+
* **返回值被丢弃** ⇒ 只 `return keys.runComponent(…)` 的话 fiber 卸载时没人撤路由(旧注册留在
|
|
34
|
+
* 宿主路由表里),下一次启用立刻撞「重复路由」。所以返回值一律走 `keys.handOffTeardown(ctx, …)`:
|
|
35
|
+
* 同一份 disposer 也交给 `ctx.effect`(cordis 的显式清理通道)并做幂等包装。见 `lib/host-boot.js`;
|
|
36
|
+
* 判据 `test/verify-bundle-rows.mjs` ⑧c。
|
|
37
|
+
*
|
|
38
|
+
* ⚠️ **模块作用域纪律(P2-1b 定,P-F 后仍适用)**:模块作用域(顶层、任何函数体之外)只许放
|
|
39
|
+
* 声明/常量 —— 不得在模块求值期去读别的模块的绑定并调用它,否则那一刻对方可能还没求值完,抛
|
|
40
|
+
* `ReferenceError: Cannot access '…' before initialization`(P2-1b NC1 实测报错原文)。
|
|
41
|
+
* 对应判据:`test/verify-bundle-rows.mjs` ⑥(结构判据 + 模块作用域文本兜底,双向)。
|
|
42
|
+
*
|
|
43
|
+
* 与主行的**有意不对称**(同 about-notice):本组件**不** `acquireKernelLease`。租约护的是
|
|
44
|
+
* `transcodeKit` 这类内核共享可变资源,而本组件只用两条静态图片的读写族,没有可释放的共享资源
|
|
45
|
+
* ⇒ 不 acquire 也就不 release。
|
|
46
|
+
*
|
|
47
|
+
* 形态:**自建最小出站套件**,不复用 `createHostSession` —— 后者会写
|
|
48
|
+
* `build-stamp.json` 并再排一次 3s 启动清扫,三行(裸行 + 两个组件行)同时加载等于把这两件事做三遍。
|
|
49
|
+
* P2-7B 起这一份"迷你会话"住在内核侧(`createComponentSession()`,teardown 只有一份),组件只消费
|
|
50
|
+
* **内核导出的组件视图**(键集 = 内核 `COMPONENT_VIEW_KEYS` 里这一格声明的那几个)⇒ 不再从整个
|
|
51
|
+
* `hostKernel` 解构(M9 的现状);serve 套件的入参(`SESSION_SERVE_KEYS`)由会话从视图取。
|
|
52
|
+
*/
|
|
53
|
+
import { registerMascotRoutes } from './routes/mascot.js';
|
|
54
|
+
import { registerAvatarRoutes } from './routes/avatar.js';
|
|
55
|
+
|
|
56
|
+
/** patch 行 slug(`cordis.patch.yml` 里该行 `name` 的完整值,两处逐字相等)。 */
|
|
57
|
+
export const name = 'dsh-plugin-wallpaper-engine-mascot-avatar';
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* 硬依赖 web 服务 + 主包宿主服务:与主行 `lib/index.js` 的 `inject` 同一套语义。
|
|
61
|
+
* 子包行走 patch 行加载时,Loader 靠这两句保证「服务就绪才激活」,`ctx.webServer` /
|
|
62
|
+
* `ctx.wallpaperEngineHost` 才读得到。
|
|
63
|
+
*/
|
|
64
|
+
export const inject = ['webServer', 'wallpaperEngineHost'];
|
|
65
|
+
|
|
66
|
+
/** 独立 plugin 入口:宿主按 patch 行加载本子包时走这里,转调本模块的实现(不经门面)。 */
|
|
67
|
+
export function apply(ctx, config) {
|
|
68
|
+
// ⚠️ 这个字面形态是**承重**的:`test/verify-inject-contracts.mjs` 的 `tableBindingNames()` 按
|
|
69
|
+
// `const <host> = ctx.<服务名>` 认「本文件里的冻结表绑定」(`recvRe`),再据此把下面调用点的
|
|
70
|
+
// `...keys` 展开成叶子冻结表。写成 `ctx && ctx.<服务名>` 守卫就认不出表 ⇒ 整包调用点判 dynamic
|
|
71
|
+
// 而红(nc-sub7 钉的就是这条:接收者必须源自 `ctx.<服务名>`)。
|
|
72
|
+
const host = ctx.wallpaperEngineHost;
|
|
73
|
+
// 拿不到服务名就大声失败:静默 `undefined` 会让下面每一步都在 undefined 上取属性(半死态)。
|
|
74
|
+
if (!host) {
|
|
75
|
+
throw new Error('[wallpaper-engine] mascot-avatar 没拿到 wallpaperEngineHost 服务'
|
|
76
|
+
+ '(inject 声明与宿主装载顺序不匹配)');
|
|
77
|
+
}
|
|
78
|
+
// 键视图 = `lib/subpackage-boot.js` 的 SUBPACKAGE_KEY_TABLE 里本包那一行(值全部来自主包模块级绑定)。
|
|
79
|
+
// 记账 / 错误留证 / 「失败仍原样抛」三件事都在 `keys.runComponent()`(门面 `applyComponent`
|
|
80
|
+
// 走的是同一个函数)⇒ 两条装载路径共用一份语义,不可能一条记了、另一条忘了。
|
|
81
|
+
const keys = host.keys('mascot-avatar', ctx);
|
|
82
|
+
// `http` 面(`sendJson` / `bodyReader`)不在冻结键表里,与 `packages/fonts` 同款:按需显式带上。
|
|
83
|
+
const deps = Object.freeze({ ...keys, http: host.http });
|
|
84
|
+
return keys.handOffTeardown(ctx, keys.runComponent('mascot-avatar', ctx, config, deps, applyImpl));
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* 组件实现。第三个形参名取 `c`(与 `lib/kernel/host-session.js` 同一约定):
|
|
89
|
+
* `test/tools/host-route-index.mjs --deps` 按 `const { … } = c;` 现抽契约;路由族调用点的
|
|
90
|
+
* `...keys` 展开则由 `test/verify-inject-contracts.mjs` 按冻结表认(`keys` 与 `apply()` 里那个
|
|
91
|
+
* 绑定同名 ⇒ 两边指的是同一份键视图)。
|
|
92
|
+
*/
|
|
93
|
+
export function applyImpl(root, _rawConfig, c) {
|
|
94
|
+
const keys = c;
|
|
95
|
+
const { base, pluginName, componentViewFrom, createComponentSession } = c;
|
|
96
|
+
// 两条装载路径都能这么读:① 子包行自己声明了 `inject = ['webServer', 'wallpaperEngineHost']`;
|
|
97
|
+
// ② 门面路径的 `root` 就是门面的 ctx,而门面同样声明了 `inject = ['webServer']`(主行
|
|
98
|
+
// `lib/index.js` 的 `inject` 声明)。
|
|
99
|
+
const webServer = root && root.webServer;
|
|
100
|
+
// 与门面 `apply()` 同款早退:服务在、但 register 面还没挂上(或换成了别的 webServer 实现)。
|
|
101
|
+
if (!webServer || typeof webServer.register !== 'function') return () => {};
|
|
102
|
+
|
|
103
|
+
// P2-7B 注入面收窄:从内核取**本组件声明的视图**(`COMPONENT_VIEW_KEYS['mascot-avatar']`),
|
|
104
|
+
// 不再 `const { … } = hostKernel` 现解构 —— 后者等于把整个内核(键数与分级由
|
|
105
|
+
// `test/verify-component-face.mjs` 现算)当成注入面(M9 的现状)。视图缺键即抛,不静默 `undefined`。
|
|
106
|
+
const view = componentViewFrom('mascot-avatar');
|
|
107
|
+
// 迷你会话(disposers / activeStreams / mediaMap / log / serveFile / 同序 teardown)收在内核侧:
|
|
108
|
+
// serve 套件的入参(`SESSION_SERVE_KEYS`)由会话从视图取,本组件只取下面两条路由族要的键。
|
|
109
|
+
const { disposers, serveFile, teardown } = createComponentSession(root, { base, pluginName }, view);
|
|
110
|
+
// 服务层符号(目录 / 上限 / 原子落盘 / 请求收尾)继续由内核持有 —— 主包的 settings-schema、
|
|
111
|
+
// presets、startup-sweep 与门面本身都还按同一套目录语义读写它们(见 lib/media/media-dirs.js)。
|
|
112
|
+
const {
|
|
113
|
+
mascotDir, mascotPath, MASCOT_EXT, MASCOT_MAX_BYTES,
|
|
114
|
+
avatarDir, avatarPath, AVATAR_SIDES, AVATAR_EXT, AVATAR_MAX_BYTES,
|
|
115
|
+
atomicWriteFileP, armBodyIdleTimeout, lingerClose,
|
|
116
|
+
} = view;
|
|
117
|
+
|
|
118
|
+
// ⚠️ **注册期必须包 try**(P2-4):本实现要注册**两条**路由族,第 N 条抛错时前面 N-1 条已经
|
|
119
|
+
// 把 disposer 推进了 `disposers`。若不在这里收尾就往外抛,`teardown` 永远交不回宿主
|
|
120
|
+
// (`runComponent()` 只在 impl 正常返回时拿到它)⇒ 残留路由让下一次启用撞
|
|
121
|
+
// `webserver: duplicate … route`。teardown 自己吞异常,原错照抛(装载失败必须仍然是红的)。
|
|
122
|
+
try {
|
|
123
|
+
// 6f. 「系统」页签的自定义吉祥物立绘 → lib/routes/mascot.js。POST 导入(raw body + MIME 白名单)/
|
|
124
|
+
// GET·HEAD 查看 / DELETE 清除,只认一张:导入前先清同族旧文件("下一次导入覆盖上一次")。
|
|
125
|
+
registerMascotRoutes(webServer, {
|
|
126
|
+
...keys, disposers, base, serveFile, http: keys.http,
|
|
127
|
+
mascotDir, mascotPath, MASCOT_EXT, MASCOT_MAX_BYTES,
|
|
128
|
+
atomicWriteFileP, armBodyIdleTimeout, lingerClose,
|
|
129
|
+
});
|
|
130
|
+
|
|
131
|
+
// 6e. 「扩展」页签第一个模块(自定义会话头像)的两张图 → lib/routes/avatar.js。一条 prefix 注册
|
|
132
|
+
// 覆盖三个端点;图落在插件数据目录的 `avatars/` 下(不进 overrides,也不进 uploads)。
|
|
133
|
+
registerAvatarRoutes(webServer, {
|
|
134
|
+
...keys, disposers, base, serveFile, http: keys.http,
|
|
135
|
+
avatarDir, avatarPath, AVATAR_SIDES, AVATAR_EXT, AVATAR_MAX_BYTES,
|
|
136
|
+
atomicWriteFileP, armBodyIdleTimeout, lingerClose,
|
|
137
|
+
});
|
|
138
|
+
} catch (error) {
|
|
139
|
+
teardown();
|
|
140
|
+
throw error;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
// 本组件自己的收尾(会话的 teardown,见 lib/kernel/component-session.js):与 host-session 的
|
|
144
|
+
// teardown 同序(逐个 disposer → destroy 在途流 → 清两个容器),但**没有** releaseKernelLease
|
|
145
|
+
// —— 见文件头那条有意不对称。
|
|
146
|
+
return teardown;
|
|
147
|
+
}
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* packages/mascot-avatar/lib/routes/avatar.js — **会话头像族**路由:导入(POST)/ 查看(GET、HEAD)/ 清除(DELETE)两张头像图。
|
|
3
|
+
*
|
|
4
|
+
* 为什么值得独立成文件:这三条是**唯一**会动头像目录的一组,而它们共用同一套
|
|
5
|
+
* "谁是合法的一方 / 文件名长什么样 / 换图怎么清兄弟"的规则 —— 收在一处才能一次读完。
|
|
6
|
+
* 依赖写在签名上(`c`)。
|
|
7
|
+
*
|
|
8
|
+
* 契约:`registerAvatarRoutes(webServer, c)`;`c` 里是这一族**用到但不属于它**的东西。
|
|
9
|
+
* 头像目录的**服务层**(`avatarDir` / `avatarPath` / `AVATAR_SIDES` / `AVATAR_EXT` /
|
|
10
|
+
* `AVATAR_MAX_BYTES`)住在 `lib/media/media-dirs.js`:`AVATAR_EXT` 是 `test/verify-contracts.mjs`
|
|
11
|
+
* 读取的**跨半边契约表**,且目录归属与配置目录同处一源。它们的归属是那条依赖。
|
|
12
|
+
* · `disposers` / `base` ← 清理句柄数组与路径前缀
|
|
13
|
+
* · `serveFile` ← 静态发送(带 Range / 条件 GET)
|
|
14
|
+
* · `avatarDir` / `avatarPath` ← 头像目录与"当前那张"的定位
|
|
15
|
+
* · `AVATAR_SIDES` / `AVATAR_EXT` / `AVATAR_MAX_BYTES`
|
|
16
|
+
* · `bodyReader` ← 收 body 的**唯一**实现(上限 + 收完一次性解码,见 lib/http-body.js)
|
|
17
|
+
* · `atomicWriteFileP` ← 原子落盘(`.tmp` + rename,半写的图会被当成有效头像服务出去)
|
|
18
|
+
* · `armBodyIdleTimeout` / `lingerClose` ← 请求体 idle 超时与"写应答后再断"的收尾
|
|
19
|
+
*
|
|
20
|
+
* 不变量:
|
|
21
|
+
* · **只认两个 side**(`user` / `ai`):路径段当白名单查,不是拼进文件名 ——
|
|
22
|
+
* 路径穿越在这一步就不可能(`../` 与分隔符根本不在表里)。
|
|
23
|
+
* · **收 body 走共享读体器,不走第三个流式豁免**:上限只有 8 MB(客户端导入前已按
|
|
24
|
+
* 512px 缩过一轮),缓冲在内存里完全够用;内联流式落盘是给 512 MB / 30 MB 那两条腿留的
|
|
25
|
+
* 结构性豁免(见 test/verify-body-caps.mjs 的棘轮:内联收集器只许**减**、共享读体器只许**增**)
|
|
26
|
+
* ⇒ 这一条走 `bodyReader` + `atomicWriteFileP`,两边棘轮都朝收敛方向动。
|
|
27
|
+
* · **换图即清兄弟**:同一 side 的旧文件(可能换了扩展名、也可能换了时间戳)先删 ——
|
|
28
|
+
* 读取侧 `avatarPath` 是按前缀扫目录取第一个命中的,留着旧文件就是
|
|
29
|
+
* "新图导进去了、屏上还是旧图"(名字每次都变,所以这里按前缀清而不是按同名清)。
|
|
30
|
+
* · **Cache-Control 由文件名担保**:URL 上带的是文件名(`?v=<name>`),换图即换名 ⇒
|
|
31
|
+
* 这一条可以给出长缓存(一屏头像会渲染多份 `<img>`,不给缓存就是每个气泡一次请求)。
|
|
32
|
+
* 未导入 ⇒ 404 + `no-store`(错误响应绝不能被缓存,否则导入后仍显示上次的 404)。
|
|
33
|
+
* · 注册返回值必须推进 `c.disposers`,否则卸载 / HMR 后路由仍挂着已释放的处理器。
|
|
34
|
+
*/
|
|
35
|
+
|
|
36
|
+
import { readdirSync, unlinkSync } from 'node:fs';
|
|
37
|
+
import { join } from 'node:path';
|
|
38
|
+
|
|
39
|
+
/** 文件名里那段时间戳(`Date.now()` 的 36 进制 + 4 位随机 —— 形状见 `AVATAR_FILE_RE`):换图即换名。 */
|
|
40
|
+
function avatarStamp() {
|
|
41
|
+
return Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** 注入契约(P2-7A / ADR-0013 D12):本族从 `c` 消费的**必需**键 —— 门面/组件行调用点必须逐键给到(判据 test/verify-inject-contracts.mjs 双向对账)。 */
|
|
45
|
+
export const DEPS = ['disposers', 'base', 'serveFile', 'avatarDir', 'avatarPath', 'AVATAR_SIDES', 'AVATAR_EXT', 'AVATAR_MAX_BYTES', 'atomicWriteFileP', 'armBodyIdleTimeout', 'lingerClose', 'http'];
|
|
46
|
+
|
|
47
|
+
export function registerAvatarRoutes(webServer, c) {
|
|
48
|
+
const {
|
|
49
|
+
disposers, base: BASE, serveFile, http,
|
|
50
|
+
avatarDir, avatarPath, AVATAR_SIDES, AVATAR_EXT, AVATAR_MAX_BYTES,
|
|
51
|
+
atomicWriteFileP, armBodyIdleTimeout, lingerClose,
|
|
52
|
+
} = c;
|
|
53
|
+
|
|
54
|
+
disposers.push(webServer.register({
|
|
55
|
+
kind: 'prefix',
|
|
56
|
+
path: `${BASE}/avatar`,
|
|
57
|
+
handler: (req, res) => {
|
|
58
|
+
const method = (req.method || 'GET').toUpperCase();
|
|
59
|
+
const pathname = new URL(req.url || '/', 'http://x').pathname;
|
|
60
|
+
const side = decodeURIComponent(pathname.slice(`${BASE}/avatar/`.length)).replace(/\/+$/, '');
|
|
61
|
+
// 薄别名:保留调用点写法,实现收敛到主包的 lib/json-response.js(默认带 no-store),
|
|
62
|
+
// 经注入面 `http` 送达(本包零主包说明符)。
|
|
63
|
+
const json = (code, payload) => http.sendJson(res, code, payload);
|
|
64
|
+
// 只认两个 side(不变量 ①):非法的一方连目录都不碰。
|
|
65
|
+
if (!AVATAR_SIDES.includes(side)) { json(400, { error: 'bad-side' }); return; }
|
|
66
|
+
|
|
67
|
+
if (method === 'GET' || method === 'HEAD') {
|
|
68
|
+
const p = avatarPath(side);
|
|
69
|
+
if (!p) { json(404, { error: 'not-set' }); return; }
|
|
70
|
+
// 名字在 URL 上 ⇒ 可以长缓存(不变量 ④)。serveFile 只在错误路径写 no-store,
|
|
71
|
+
// 成功路径不会覆盖这里已经写下的头;HEAD 只做磁盘探测、绝不生成。
|
|
72
|
+
res.setHeader('Cache-Control', 'private, max-age=31536000, immutable');
|
|
73
|
+
serveFile(p, req, res, method === 'HEAD');
|
|
74
|
+
return;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
if (method === 'DELETE') {
|
|
78
|
+
const p = avatarPath(side);
|
|
79
|
+
let removed = false;
|
|
80
|
+
if (p) {
|
|
81
|
+
try { unlinkSync(p); removed = true; } catch { /* ignore */ }
|
|
82
|
+
}
|
|
83
|
+
json(200, { ok: true, side, removed });
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
if (method !== 'POST') { json(405, { error: 'method not allowed' }); return; }
|
|
88
|
+
|
|
89
|
+
const ctype = String(req.headers['content-type'] || '').split(';')[0].trim().toLowerCase();
|
|
90
|
+
const ext = AVATAR_EXT[ctype];
|
|
91
|
+
if (!ext) {
|
|
92
|
+
json(415, { error: '不支持的格式:' + ctype + '(仅支持 JPG / PNG / WebP)' });
|
|
93
|
+
return;
|
|
94
|
+
}
|
|
95
|
+
const dir = avatarDir();
|
|
96
|
+
let timedOut = false;
|
|
97
|
+
let tooLarge = false;
|
|
98
|
+
armBodyIdleTimeout(req, () => {
|
|
99
|
+
timedOut = true;
|
|
100
|
+
json(408, { error: 'request timeout' });
|
|
101
|
+
});
|
|
102
|
+
// 上限 + 收完一次性解码 —— 唯一实现见主包 lib/http-body.js(经注入面 `http`)。
|
|
103
|
+
const reader = http.bodyReader(req, {
|
|
104
|
+
maxBytes: AVATAR_MAX_BYTES,
|
|
105
|
+
shouldStop: () => timedOut || tooLarge,
|
|
106
|
+
onOverflow: () => {
|
|
107
|
+
tooLarge = true;
|
|
108
|
+
json(413, { error: '图片过大(上限 8MB)' });
|
|
109
|
+
},
|
|
110
|
+
});
|
|
111
|
+
req.on('data', reader.onData);
|
|
112
|
+
req.on('end', () => {
|
|
113
|
+
if (timedOut || tooLarge) return;
|
|
114
|
+
const body = reader.buf();
|
|
115
|
+
// 空体当失败:一次 0 字节的导入只会让 `<img>` 静默裂开,不如当场报错。
|
|
116
|
+
if (!body.length) { json(400, { error: 'empty body' }); return; }
|
|
117
|
+
// 换图即清兄弟(不变量 ③):同 side 的旧正式文件与陈旧 `.tmp` 一并清掉,
|
|
118
|
+
// 再写这次的新名字 —— 读取侧只取第一个命中的正式文件。
|
|
119
|
+
try {
|
|
120
|
+
for (const name of readdirSync(dir)) {
|
|
121
|
+
if (name.slice(0, side.length + 1) !== side + '-') continue;
|
|
122
|
+
try { unlinkSync(join(dir, name)); } catch { /* ignore */ }
|
|
123
|
+
}
|
|
124
|
+
} catch { /* 空目录 */ }
|
|
125
|
+
const name = side + '-' + avatarStamp() + '.' + ext;
|
|
126
|
+
atomicWriteFileP(join(dir, name), body).then(
|
|
127
|
+
() => json(200, { ok: true, side, name, bytes: body.length }),
|
|
128
|
+
() => {
|
|
129
|
+
json(500, { error: 'write failed' });
|
|
130
|
+
lingerClose(req, res);
|
|
131
|
+
},
|
|
132
|
+
);
|
|
133
|
+
});
|
|
134
|
+
req.on('error', () => { if (!timedOut && !tooLarge) json(400, { error: 'request error' }); });
|
|
135
|
+
},
|
|
136
|
+
}));
|
|
137
|
+
}
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* packages/mascot-avatar/lib/routes/mascot.js — **自定义吉祥物立绘族**路由:导入(POST)/ 查看(GET、HEAD)/ 清除(DELETE)。
|
|
3
|
+
*
|
|
4
|
+
* 为什么独立成族(而不是复用头像那族的第三个 side):头像按"一方一张"(`user` / `ai`),
|
|
5
|
+
* 立绘**只有一张**且语义完全不同(它不是会话里的脸,而是主页面那只吉祥物的替身)——
|
|
6
|
+
* 混进同一族会让"两个 side"这条不变量变成一句需要解释的话。两族共用同一套**形状**:
|
|
7
|
+
* 一条 prefix 注册覆盖三个方法、raw body + MIME 白名单、原子落盘、换图清兄弟。
|
|
8
|
+
*
|
|
9
|
+
* 契约:`registerMascotRoutes(webServer, c)`;`c` 里是这一族**用到但不属于它**的东西。
|
|
10
|
+
* 目录与上限的**服务层**(`mascotDir` / `mascotPath` / `MASCOT_EXT` / `MASCOT_MAX_BYTES`)
|
|
11
|
+
* 住在 `lib/media/media-dirs.js`:`MASCOT_EXT` 与 `MASCOT_MAX_BYTES` 是 `test/verify-contracts.mjs`
|
|
12
|
+
* 读取的**跨半边契约表**,且目录归属与配置目录同处一源。
|
|
13
|
+
* · `disposers` / `base` ← 清理句柄数组与路径前缀
|
|
14
|
+
* · `serveFile` ← 静态发送(带 Range / 条件 GET)
|
|
15
|
+
* · `mascotDir` / `mascotPath`
|
|
16
|
+
* · `MASCOT_EXT` / `MASCOT_MAX_BYTES`
|
|
17
|
+
* · `bodyReader` ← 收 body 的**唯一**实现(上限 + 收完一次性解码)
|
|
18
|
+
* · `atomicWriteFileP` ← 原子落盘(`.tmp` + rename)
|
|
19
|
+
* · `armBodyIdleTimeout` / `lingerClose`
|
|
20
|
+
*
|
|
21
|
+
* 不变量:
|
|
22
|
+
* · **只有一张**:导入前先清同族旧文件(正式文件与陈旧 `.tmp`)—— "下一次导入覆盖上一次"
|
|
23
|
+
* 是用户明说的口径,也是读取侧 `mascotPath()` 的语义(它只认 `<前缀>-<stamp>.<ext>`
|
|
24
|
+
* 且返回第一个命中的文件;留着旧图就是"新图导进去了、屏上还是旧图")。
|
|
25
|
+
* · **收体走共享读体器 + 原子落盘**:上限 8MB(客户端导入前已按 512px 缩过一轮),
|
|
26
|
+
* 不新增流式豁免(见 test/verify-body-caps.mjs 的两条棘轮)。
|
|
27
|
+
* · **Cache-Control 由文件名担保**:URL 上带的是文件名(`?v=<name>`),换图即换名 ⇒
|
|
28
|
+
* 可以给长缓存;未导入 ⇒ 404 + `no-store`(否则导入后仍会看到上次的 404)。
|
|
29
|
+
* · 注册返回值必须推进 `c.disposers`,否则卸载 / HMR 后路由仍挂着已释放的处理器。
|
|
30
|
+
*/
|
|
31
|
+
|
|
32
|
+
import { readdirSync, unlinkSync } from 'node:fs';
|
|
33
|
+
import { join } from 'node:path';
|
|
34
|
+
|
|
35
|
+
/** 文件名里那段时间戳(`Date.now()` 的 36 进制 + 4 位随机 —— 形状见 `MASCOT_FILE_RE`):换图即换名。 */
|
|
36
|
+
function mascotStamp() {
|
|
37
|
+
return Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** 注入契约(P2-7A / ADR-0013 D12):本族从 `c` 消费的**必需**键 —— 门面/组件行调用点必须逐键给到(判据 test/verify-inject-contracts.mjs 双向对账)。 */
|
|
41
|
+
export const DEPS = ['disposers', 'base', 'serveFile', 'mascotDir', 'mascotPath', 'MASCOT_EXT', 'MASCOT_MAX_BYTES', 'atomicWriteFileP', 'armBodyIdleTimeout', 'lingerClose', 'http'];
|
|
42
|
+
|
|
43
|
+
export function registerMascotRoutes(webServer, c) {
|
|
44
|
+
const {
|
|
45
|
+
disposers, base: BASE, serveFile, http,
|
|
46
|
+
mascotDir, mascotPath, MASCOT_EXT, MASCOT_MAX_BYTES,
|
|
47
|
+
atomicWriteFileP, armBodyIdleTimeout, lingerClose,
|
|
48
|
+
} = c;
|
|
49
|
+
|
|
50
|
+
disposers.push(webServer.register({
|
|
51
|
+
kind: 'prefix',
|
|
52
|
+
path: `${BASE}/mascot`,
|
|
53
|
+
handler: (req, res) => {
|
|
54
|
+
const method = (req.method || 'GET').toUpperCase();
|
|
55
|
+
// 薄别名:保留调用点写法,实现收敛到主包的 lib/json-response.js(默认带 no-store),
|
|
56
|
+
// 经注入面 `http` 送达(本包零主包说明符)。
|
|
57
|
+
const json = (code, payload) => http.sendJson(res, code, payload);
|
|
58
|
+
|
|
59
|
+
if (method === 'GET' || method === 'HEAD') {
|
|
60
|
+
const p = mascotPath();
|
|
61
|
+
if (!p) { json(404, { error: 'not-set' }); return; }
|
|
62
|
+
// 名字在 URL 上 ⇒ 可以长缓存;serveFile 只在错误路径写 no-store,成功路径不覆盖。
|
|
63
|
+
res.setHeader('Cache-Control', 'private, max-age=31536000, immutable');
|
|
64
|
+
serveFile(p, req, res, method === 'HEAD');
|
|
65
|
+
return;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
if (method === 'DELETE') {
|
|
69
|
+
const p = mascotPath();
|
|
70
|
+
let removed = false;
|
|
71
|
+
if (p) {
|
|
72
|
+
try { unlinkSync(p); removed = true; } catch { /* ignore */ }
|
|
73
|
+
}
|
|
74
|
+
json(200, { ok: true, removed });
|
|
75
|
+
return;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
if (method !== 'POST') { json(405, { error: 'method not allowed' }); return; }
|
|
79
|
+
|
|
80
|
+
const ctype = String(req.headers['content-type'] || '').split(';')[0].trim().toLowerCase();
|
|
81
|
+
const ext = MASCOT_EXT[ctype];
|
|
82
|
+
if (!ext) {
|
|
83
|
+
json(415, { error: '不支持的格式:' + ctype + '(仅支持 JPG / PNG / WebP)' });
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
const dir = mascotDir();
|
|
87
|
+
let timedOut = false;
|
|
88
|
+
let tooLarge = false;
|
|
89
|
+
armBodyIdleTimeout(req, () => {
|
|
90
|
+
timedOut = true;
|
|
91
|
+
json(408, { error: 'request timeout' });
|
|
92
|
+
});
|
|
93
|
+
// 上限 + 收完一次性解码 —— 唯一实现见主包 lib/http-body.js(经注入面 `http`)。
|
|
94
|
+
const reader = http.bodyReader(req, {
|
|
95
|
+
maxBytes: MASCOT_MAX_BYTES,
|
|
96
|
+
shouldStop: () => timedOut || tooLarge,
|
|
97
|
+
onOverflow: () => {
|
|
98
|
+
tooLarge = true;
|
|
99
|
+
json(413, { error: '图片过大(上限 8MB)' });
|
|
100
|
+
},
|
|
101
|
+
});
|
|
102
|
+
req.on('data', reader.onData);
|
|
103
|
+
req.on('end', () => {
|
|
104
|
+
if (timedOut || tooLarge) return;
|
|
105
|
+
const body = reader.buf();
|
|
106
|
+
// 空体当失败:一次 0 字节的导入只会让 `<img>` 静默裂开,不如当场报错。
|
|
107
|
+
if (!body.length) { json(400, { error: 'empty body' }); return; }
|
|
108
|
+
// 只有一张:同族的旧正式文件与陈旧 `.tmp` 一并清掉,再写这次的新名字。
|
|
109
|
+
try {
|
|
110
|
+
for (const name of readdirSync(dir)) {
|
|
111
|
+
if (name.slice(0, 'mascot-'.length) !== 'mascot-') continue;
|
|
112
|
+
try { unlinkSync(join(dir, name)); } catch { /* ignore */ }
|
|
113
|
+
}
|
|
114
|
+
} catch { /* 空目录 */ }
|
|
115
|
+
const name = 'mascot-' + mascotStamp() + '.' + ext;
|
|
116
|
+
atomicWriteFileP(join(dir, name), body).then(
|
|
117
|
+
() => json(200, { ok: true, name, bytes: body.length }),
|
|
118
|
+
() => { json(500, { error: 'write failed' }); lingerClose(req, res); },
|
|
119
|
+
);
|
|
120
|
+
});
|
|
121
|
+
req.on('error', () => { if (!timedOut && !tooLarge) json(400, { error: 'request error' }); });
|
|
122
|
+
},
|
|
123
|
+
}));
|
|
124
|
+
}
|
package/locale/en.json
ADDED
package/locale/zh.json
ADDED
package/package.json
CHANGED
|
@@ -1,6 +1,29 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-plugin-wallpaper-engine-mascot-avatar",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.4.0",
|
|
4
|
+
"description": "Mascot & avatar host half: the custom mascot image (/mascot) and the two session avatars (/avatar/<side>).",
|
|
5
|
+
"icon": "./icon.png",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"main": "./lib/index.js",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": "./lib/index.js",
|
|
10
|
+
"./package.json": "./package.json",
|
|
11
|
+
"./locale/*.json": "./locale/*.json",
|
|
12
|
+
"./cordis.patch.yml": "./cordis.patch.yml"
|
|
13
|
+
},
|
|
14
|
+
"dsh": {
|
|
15
|
+
"bundle": {
|
|
16
|
+
"patch": "./cordis.patch.yml"
|
|
17
|
+
}
|
|
18
|
+
},
|
|
19
|
+
"files": ["lib/", "cordis.patch.yml", "locale/", "icon.png", "package.json"],
|
|
20
|
+
"peerDependencies": {
|
|
21
|
+
"@deepseek-ai/dsh-host-webserver": ">=0.1.5-rc.1"
|
|
22
|
+
},
|
|
23
|
+
"peerDependenciesMeta": {
|
|
24
|
+
"@deepseek-ai/dsh-host-webserver": {
|
|
25
|
+
"optional": true
|
|
26
|
+
}
|
|
27
|
+
},
|
|
28
|
+
"license": "MIT"
|
|
29
|
+
}
|
package/README.md
DELETED