dsh-wisp 0.6.0 → 1.25.0

package/lib/index.js

@@ -1,19 +1,122 @@
-// Host half of @local/dsh-wisp.
+// Host half of dsh-wisp.
 //
-// This plugin deliberately does nothing on the host side. Everything the wisp
-// needs is already available in the browser: the client builtins provide React,
-// a package-owned stylesheet inserter, and the live Slot tree. Keeping the host
-// half empty means the plugin needs no peer dependencies at all, so it loads on
-// a stock DSH desktop install whose profile has an empty `dependencies` map.
+// Two jobs, both small:
 //
-// If you later want the wisp to react to host-side facts (model, token usage,
-// job state), add a `host.call` handler here and a matching `host.call(...)`
-// from lib/client.js.
+//   1. Answer the browser half's `host.call('checkUpdate')` — the ONE thing the
+//      companion cannot do on its own: the browser half's `fetch` is a teaching
+//      trap, and this half runs in a vm sandbox whose Node APIs are trapped too.
+//      The platform's answer to that is a *service*: `ctx.web.fetch(...)`, the
+//      same seam DSH's own `web_fetch` tool uses. Services are the sanctioned way
+//      for a sandboxed half to reach a real capability, so the update check goes
+//      through it — nothing is bypassed.
+//
+//   2. Nothing else. `web` is declared as an OPTIONAL inject on purpose: a
+//      required inject that nothing provides would leave this fiber `waiting`
+//      forever, and the companion would simply disappear from the UI.
 
+/** Cordis plugin name used by loader diagnostics. */
 export const name = 'wisp'
 
-export function apply() {
-  // Intentionally empty — see the note above.
+/**
+ * `web` is optional on purpose. A required inject that nothing provides keeps
+ * the fiber in `waiting` forever, and the user's companion would vanish.
+ */
+export const inject = { required: [], optional: ['web'] }
+
+/** Where the check reads the published version from. Overridable per install. */
+export const DEFAULT_UPDATE_URL = 'https://raw.githubusercontent.com/969246694/dsh-wisp/main/package.json'
+
+/** How long a check may take before it is reported as a timeout. */
+const CHECK_TIMEOUT_MS = 8000
+
+/**
+ * Fetch the published package.json and pull `version` out of it.
+ * @param web - the `web` service, or undefined when it is not loaded.
+ * @param url - the manifest URL.
+ * @param signal - optional cancellation signal.
+ * @returns a plain, JSON-serializable verdict (this crosses the sandbox boundary).
+ */
+export async function readPublishedVersion(web, url, signal) {
+  if (!web || typeof web.fetch !== 'function') {
+    return { ok: false, reason: 'no-web-service', url }
+  }
+  try {
+    const res = await web.fetch({ url }, signal)
+    if (!res || typeof res.statusCode !== 'number') return { ok: false, reason: 'bad-result', url }
+    /* Per the service contract a non-2xx response is a RESULT, not a throw —
+       so the status must be checked here instead of caught below. */
+    if (res.statusCode !== 200) return { ok: false, reason: 'http-' + res.statusCode, url }
+    const text = res.body && typeof res.body.content === 'string' ? res.body.content : ''
+    let latest = null
+    try {
+      const parsed = JSON.parse(text)
+      if (parsed && typeof parsed.version === 'string') latest = parsed.version
+    } catch (error) {
+      return { ok: false, reason: 'not-json', url }
+    }
+    if (latest === null) return { ok: false, reason: 'no-version-field', url }
+    return { ok: true, url, latest }
+  } catch (error) {
+    const detail = error && error.message ? String(error.message) : String(error)
+    return { ok: false, reason: 'fetch-failed', detail, url }
+  }
+}
+
+/** Compare two dotted versions. Returns -1 / 0 / 1; non-numeric parts count as 0. */
+export function compareVersions(a, b) {
+  const parse = (v) => String(v).split('-')[0].split('.').map((n) => {
+    const x = Number.parseInt(n, 10)
+    return Number.isFinite(x) ? x : 0
+  })
+  const left = parse(a)
+  const right = parse(b)
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    const l = left[i] ?? 0
+    const r = right[i] ?? 0
+    if (l !== r) return l < r ? -1 : 1
+  }
+  return 0
+}
+
+/** Register the handler the browser half reaches through `host.call`. */
+export function registerHandlers(ctx, options = {}) {
+  const url = typeof options.updateUrl === 'string' && options.updateUrl !== ''
+    ? options.updateUrl
+    : DEFAULT_UPDATE_URL
+  /* `harness` is a sandbox global: the host half is evaluated inside a vm whose
+     context carries it. Guard the reference so this module also loads — and is
+     testable — outside that sandbox. */
+  const seat = typeof harness === 'undefined' ? undefined : harness
+  if (!seat || typeof seat.handle !== 'function') {
+    return { registered: false, reason: 'no-harness-seat' }
+  }
+  const dispose = seat.handle('checkUpdate', async (args) => {
+    const current = args && typeof args.current === 'string' ? args.current : null
+    const canAbort = typeof AbortController === 'function'
+    const controller = canAbort ? new AbortController() : null
+    let timer = null
+    if (controller && typeof setTimeout === 'function') {
+      timer = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS)
+    }
+    try {
+      const verdict = await readPublishedVersion(ctx && ctx.web, url, controller ? controller.signal : undefined)
+      return { ...verdict, current, checkedAt: new Date().toISOString() }
+    } finally {
+      if (timer !== null && typeof clearTimeout === 'function') clearTimeout(timer)
+    }
+  })
+  return { registered: true, dispose, url }
+}
+
+export function apply(ctx, config) {
+  /* The body stays tiny: register the handler, and keep its disposer on the
+     fiber so unloading the package takes the handler with it. */
+  const result = registerHandlers(ctx, config || {})
+  if (result.registered && typeof ctx.effect === 'function') {
+    ctx.effect(() => () => {
+      if (typeof result.dispose === 'function') result.dispose()
+    }, 'dsh-wisp: checkUpdate handler')
+  }
 }
 
-export default { name, apply }
+export default { name, inject, apply }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-wisp",
-  "version": "0.6.0",
+  "version": "1.25.0",
   "description": "DeepSeek娘 — an unofficial floating desktop companion for the DeepSeek Harness UI. Zero dependencies; sprites inlined as data URIs; schedules on the Client timer service instead of the trapped browser timer globals.",
   "type": "module",
   "main": "lib/index.js",
@@ -30,8 +30,15 @@
     "cordis.patch.yml",
     "build.mjs",
     "verify-wisp.mjs",
+    "tools/smoke.mjs",
     "tools/keyout.mjs",
     "tools/assets.mjs",
+    "tools/tiers.mjs",
+    "tools/perf.mjs",
+    "tools/pack-check.mjs",
+    "tools/bundle-cost.mjs",
+    "tools/audit-log.mjs",
+    "audit/",
     "tools/CHARACTER-PROMPT.md",
     "assets/",
     "README.md",

package/tools/CHARACTER-PROMPT.md

@@ -25,11 +25,29 @@
 ## 提示词正文（逐字复制）
 
 ```
-一位留着深蓝色超长双马尾的成年女性：两条深蓝色马尾又长又粗、从头顶两侧一直垂到大腿两侧，必须完整画出来；发梢渐变为浅蓝；齐刘海，两侧鬓发垂到肩下。
+一位留着**深蓝色中长直发**的女性：头发**自然披散**下来、长及腰际，**没有扎成马尾、没有双马尾、没有盘发**；
+发梢由深蓝**渐变到浅蓝**；额前是**齐刘海**，两侧鬓发垂到肩下。
+**头顶正中有一缕呆毛**：向上立起、向前上方弯成一个大圆环，高出头顶轮廓（社区标识之一）。
 
 身后从腰部长出一条蓝色鲸尾，尾鳍自然向下，必须在画面中清楚可见。
 
-宝蓝色大眼睛；头顶戴白色荷叶边女仆发箍，发箍上别一枚蓝色鲸鱼造型发夹，耳侧有鲸鱼鳍造型耳饰；颈部一条细蓝色颈饰。
+宝蓝色大眼睛；头顶戴白色荷叶边女仆发箍，发箍上别一枚蓝色鲸鱼造型发夹。
+
+**她的耳朵不是人类耳朵，而是一对鲸鱼胸鳍（社区规范的「鲸鳍耳」）**：
+① **朝向最重要**：长在头两侧、**向后下方斜掠、几乎贴着头发向后伸展**，不是朝上竖立、不是向两侧平伸。
+   （第一版做成了向上外张的大翅膀 —— 用户说"太大了"，实测**问题在朝向不在长度**。）
+② **狭长**：根部略宽，向后逐渐收窄成一个**尖梢**，外缘一道平滑弧线，有一点厚度感；
+③ **配色是关键**：**上表面深蓝色、下缘与内侧白色或很浅的蓝白**，深浅分界清楚 ——
+   这是座头鲸胸鳍正反两面的配色，也是最显眼的识别点；
+④ **尺寸小巧**：每片长度约为**头宽的四分之一**，**不要超过三分之一**，绝不要画成翅膀那样大 ——
+   耳朵是配角，不该比头还显眼；
+⑤ **没有人类耳朵，没有耳环耳坠耳钉，也没有任何挂在耳朵上的饰物。**
+
+**头顶要有一根呆毛**（社区标识之一）：一小缕头发从发箍上方的头顶竖起、顶端向前弯成一个小圆环
+（像钩子或小问号），**明显高出头发轮廓、是独立的一缕**。
+**这一条必须写进提示词末尾的「画面完整性，逐条核对」清单** —— 只写在开头会被模型省略（实测过）。
+
+颈部一条细蓝色颈饰。
 
 【体型】成年女性的成熟身型：高挑、长腿、细腰，肩颈与锁骨线条优美，曲线明显但不夸张。
 
@@ -46,7 +64,7 @@
 【构图】全身直立、脚底贴住画面底边、角色居中。
 ```
 
-## 【姿态】四选一（对应四个 sprite）
+## 【姿态】七选一（对应七个 sprite）
 
 | 文件 | 姿态 |
 |---|---|
@@ -54,9 +72,160 @@
 | `happy.png` | 双手举在身体两侧欢呼，闭着眼睛开心大笑，脸颊微红，身体微微后仰。 |
 | `sleepy.png` | 怀里抱着一只蓝色鲸鱼抱枕，抱在胸腹前；半闭着眼睛打盹，困倦地微微低头。 |
 | `work.png` | 一手托着一台打开的笔记本电脑，另一手在键盘上打字，认真专注地看着屏幕。 |
+| `attn.png` | 身体微微前倾，一只手抬到胸前朝前方招了招，像是在叫对方过来；眉头微蹙、认真地直视前方，带着一点催促。 |
+| `proud.png` | 双手抱在胸前，下巴微微抬起，眼睛半闭着、嘴角上扬，神情带着一点不掩饰的得意；身体微微后仰，站得很稳。 |
+| `poked.png` | 身体明显往后一缩、双肩微微耸起，一只手抬到胸前摆出「等一下」的姿势（掌心朝前）；眼睛睁得比平时大、眉毛微挑，嘴巴小小地抿着，带着一点惊讶与抗议。 |
 
 ---
 
+## 第二套皮肤：初版女仆（`classic`）
+
+包里有两套皮肤，但上面写的是**旗舰那套（`deepsea`）**的规格。第二套的规格不同，而且它的
+绿幕原图已经不在 Maker 项目目录里（只有抠好的透明 PNG 与本仓库已发布的 WebP），所以规格
+必须记在这里，否则不可复现。
+
+差异只在两处：**没有【体型】段**（用画风里的"少女体型"约束），以及**服装更保守**。
+
+  一位留着深蓝色超长双马尾的少女：两条深蓝色马尾又长又粗、从头顶两侧一直垂到大腿两侧，
+  必须完整画出来；发梢渐变为浅蓝；齐刘海，两侧鬓发垂到肩下。
+
+  身后从腰部长出一条蓝色鲸尾，尾鳍自然向下，必须在画面中清楚可见。
+
+  宝蓝色大眼睛；头顶戴白色荷叶边女仆发箍，发箍上别一枚蓝色鲸鱼造型发夹。
+
+  **她的耳朵不是人类耳朵，而是一对鲸鱼胸鳍（社区规范的「鲸鳍耳」）**：
+  ① 长在头两侧、**向后上方斜掠张开**（像一对后掠的小翅膀），不是朝上竖立、不是朝前伸；
+  ② **狭长**：根部略宽，向后逐渐收窄成一个**尖梢**，外缘一道平滑弧线，有一点厚度感；
+  ③ **配色是关键**：**上表面深蓝色、下缘与内侧白色或很浅的蓝白**，深浅分界清楚 ——
+     这是座头鲸胸鳍正反两面的配色，也是最显眼的识别点；
+  ④ **尺寸小巧**：每片长度约为**头宽的四分之一**，**不要超过三分之一**，绝不要画成翅膀那样大 ——
+   耳朵是配角，不该比头还显眼；
+  ⑤ **没有人类耳朵，没有耳环耳坠耳钉，也没有任何挂在耳朵上的饰物。**
+
+  颈部一条细蓝色颈饰。
+
+  【服装】单薄女仆装：深蓝色细吊带连衣短裙，单层，方领，领口不高不低、不要露胸沟；身前罩
+  一件单层白色半身围裙，围裙的荷叶边是深蓝色，围裙带在腰后系成一个深蓝色蝴蝶结；裙摆很短、
+  单层、自然垂落；不穿长袜，直接露出腿；脚穿白色细带平底鞋。
+
+  【画风】干净的动漫赛璐璐上色，平涂色块加简单明暗，日系动画角色设定图风格，人物为少女体型，
+  不要写实、不要韩系半写实、不要成熟化。
+
+  【姿态】见上表。【画面完整性】【背景】【构图】与旗舰那套完全一致。
+
+## 第三套皮肤：宵蓝礼服（`night`）
+
+形象要素与旗舰那套**逐字相同**（深蓝超长双马尾、鲸尾、白色荷叶边女仆发箍、鲸鱼发夹、鳍耳饰、
+细蓝颈饰、成熟成年体型、画风段、画面完整性段、构图段），**只替换【服装】段**：
+
+```
+【服装】单层深蓝色露肩礼服：一字露肩剪裁，低领口露出锁骨与肩线；裙身单层薄料、修身、裙摆及膝略短、
+侧边开一道长衩露出一条腿；腰间一条同色细腰带；不穿长袜，直接露出双腿；脚穿白色细带高跟鞋。
+```
+
+五张姿态照第 49 行那张表，一张不改。实测键控质量 0.45%–0.61% 软边（与前两套同级），
+入包那档合计 821 KB。
+
+> 三套皮肤的差别是"**同一件人之外的东西换了**"：换掉服装而不是换掉身份，所以三张站稳的图
+> 放在一起仍然认得出是同一个人。这是刻意的 —— 皮肤不是不同角色。
+
+## 第四套皮肤：宵眠睡衣（`pajama`）
+
+形象要素与旗舰那套**逐字相同**，只替换【服装】段：
+
+```
+【服装】宽松的深蓝色长袖睡衣：上衣宽大柔软、领口有一圈白色鲸鱼刺绣、下摆盖住臀部；
+下身同色宽松睡裤、裤脚有白色鲸鱼图案；脚穿一双毛绒鲸鱼拖鞋；不穿袜子。
+```
+
+五张姿态照第 49 行那张表，一张不改。实测键控 0.48%–0.56% 软边。
+
+> 这一套的用意是**剪影差异**：前三套都是"贴身 + 露腿"，睡衣是"宽松 + 包住腿 + 毛绒拖鞋"，
+> 一眼就能分辨她在穿什么。它也让 `sleepy`（抱着鲸鱼抱枕打盹）变得贴切 —— 那是这套里最好的一格。
+
+## 社区规范：她长什么样是有共识的
+
+社区为此专门做了一个开源角色规范项目（**非官方**）：[Neko3000/deepseek-whalechan](https://github.com/Neko3000/deepseek-whalechan)
+（[中文 README](https://github.com/Neko3000/deepseek-whalechan/blob/main/README.zh.md)）。它把"鲸鱼娘"的识别点锁定为：
+
+> 精准锁定**发色渐变、鲸鳍耳、呆毛、鲸尾**与女仆装等核心标识
+
+| 锁定标识 | 本插件 | 说明 |
+|---|---|---|
+| 发色渐变 | ✓ | 深蓝 → 发梢浅蓝 |
+| **鲸鳍耳** | ✓（1.16.0 起） | 耳朵本身就是一对鲸鱼胸鳍；此前误做成"耳侧挂鳍形耳饰" |
+| **呆毛** | ✗ **尚未实现** | 头顶那缕绕成小圈的头发，社区标识之一 |
+| 鲸尾 | ✓ | 腰后一条鲸尾 |
+| 女仆装 | 部分 | 社区是长袖全套女仆装 + 白袜皮鞋；本插件是单层吊带短裙（刻意的风格选择） |
+
+**教训**：先去看社区共识，再动手画。我一开始把"鲸"理解成"加一点鲸鱼元素"，于是给她挂了鳍形耳坠、
+还把"鳍"写成"鲸鱼鳍造型"——结果出来的是鱼鳍、直板、水滴宝石，绕了三轮。**社区早就把答案写在规范里了。**
+
+**出处与许可**（据该仓库 README）：规范文档与提示词模板采用 **CC-BY-NC-SA 4.0**，代码工具链采用 MIT；
+角色形象属于社区共创，已知原始素材著作权归 B 站 **ZipZipPipe** 与 **上善无形** 等作者；
+**欢迎非商业二创**（建议注明出处 `DeepSeek Whale-chan Project`），**商业使用需获得原始著作权人书面授权**。
+本插件是非商业的个人项目；若将来要分发或商用，需要遵守上述条款。
+
+## 第五套皮肤：原版女仆（`canon`）—— 对齐社区规范
+
+这一套的目标**不是原创，而是复刻社区共识**。生成参数与前面几套完全一致，提示词如下（逐字复制）。
+
+```
+【背景要求，最重要】整张图必须是纯绿色背景（严格是鲜艳的纯绿 rgb(0,255,0)），从头到脚均匀铺满、没有任何渐变、纹理、暗角、阴影或其他物体，角色完全被这块纯绿色包围，角色四周留出一圈纯绿色空隙。绝对不要黑色背景、不要深色背景、不要白色背景、不要渐变背景。
+
+【发型，注意不是双马尾】一位留着**深蓝色中长直发**的少女：头发**自然披散**下来、长及腰际，**没有扎成马尾、没有双马尾、没有盘发**；发梢由深蓝**渐变到浅蓝**；额前是**齐刘海**，两侧鬓发自然垂到肩下。
+
+【头部特征，逐条画出来】
+① **呆毛**：头顶正中有一缕头发**向上立起、向前上方弯成一个明显的大圆环**（像一个圈），它高出头顶轮廓很多，是独立的一缕，非常醒目；
+② **发箍**：戴一条**白色荷叶边女仆发箍**，发箍**右侧**别着一个**蓝色小蝴蝶结**；
+【耳部，按顺序照画】耳朵不是人类耳朵，是两片鲸鱼胸鳍，长在头部两侧、眼睛稍下的位置。
+每一片的形状是一片**细长、光滑、末端圆钝的鳍**，像一片长叶子：
+① 方向与位置（最关键）：从头部侧面**贴着头发、向外并向下约 35 度**伸出去，**紧贴头侧的头发**、
+   往后掠；**不是向上竖立、不是向两侧平伸、不是像翅膀张开**；
+② 长度：**较长**，伸出的长度**约等于头的宽度**，明显超出头发轮廓；
+③ 宽度：根部略宽、向末端收窄，最宽处约为长度的三分之一，整片是**扁平的**；
+④ 轮廓：上缘是一条光滑的弧线，下缘也是一条**光滑连续的弧线**，只有极轻微的自然起伏；
+   整片**柔软、圆润**，末梢是**圆钝的小尖**并微微向下弯；
+⑤ 颜色：**外表面深蓝色**（与头发同色、边缘一圈深色描边）；**下缘与内侧有一条白色到银灰色的宽带**
+   （约占鳍宽的一半），像翻开的内衬 —— **这是最显眼的识别点**；
+⑥ 两片左右基本对称。没有人类耳朵，没有耳环、耳坠、耳钉，没有任何挂在耳侧的饰物。
+
+【眼睛】宝蓝色的大眼睛，多层高光与渐变瞳孔，睫毛分明。
+
+【服装】深蓝色长袖女仆连衣裙：立领，胸前有一排白色荷叶边饰边，领口系一个深蓝色蝴蝶结并别一枚蓝宝石胸针；袖口有金色纹样镶边；腰间系一条白色半身围裙、带荷叶边；裙摆及膝、多层荷叶边，裙摆边缘有金色细纹样；腿上穿**白色长袜**；脚穿**深蓝色圆头皮鞋、带金色小搭扣**。
+
+【体型】少女体型：比例舒展、四肢自然修长、身形纤细，头身比约 4 头身。
+
+【画风】高质量的现代二次元插画，商业级插画精度：精细的线稿，高密度分明的发丝刻画，眼睛有多层高光与渐变瞳孔，皮肤与布料用柔和细腻的多层过渡阴影与通透的配色，光影层次丰富。保持二次元的动漫面部与身体比例。不要照片写实、不要三维渲染感、不要粗糙平涂、不要塑料感。
+
+【姿态】站立，双手在身前轻轻交叠、微微侧身看向镜头，安静而温柔地微笑。
+
+【画面完整性，逐条核对】画面中只有一个角色。① 头发是**深蓝色中长直发、自然披散**，**不是双马尾、不是马尾、不是盘发**；② 头顶的**大圆环呆毛清楚可见**；③ 头两侧的**鲸鱼胸鳍状耳朵向后下方斜掠**、可见蓝色上表面与白色下表面、下缘有锯齿缺口；④ 发尾干净完整、渐变到浅蓝；⑤ 手指完整；⑥ 五官清晰。
+
+【构图】全身直立、脚底贴住画面底边、角色居中。
+```
+
+与前面几套的差别（都是社区规范要求的，不是随便改的）：
+
+| 项 | 前面几套（deepsea / classic / night / pajama） | 原版（`canon`） |
+|---|---|---|
+| 发型 | **超长双马尾**（本插件的原创设计） | **中长直发披散**（社区规范） |
+| 呆毛 | 无 | **有**（大圆环） |
+| 发箍 | 白色荷叶边 + 鲸鱼发夹 | 白色荷叶边 + **右侧蓝色蝴蝶结** |
+| 服装 | 单层吊带短裙（本插件的风格） | **长袖全套女仆装 + 白袜 + 深蓝圆头皮鞋**（社区规范） |
+| 鲸鳍耳 | 有 | 有（同样向后下斜掠、双色、下缘锯齿） |
+
+## 两个工具的分工
+
+| 工具 | 输入 | 什么时候用 |
+|---|---|---|
+| `tools/assets.mjs` | **绿幕母版**（纯绿底 PNG） | 刚出完图，抠图 + 分档一次做完 |
+| `tools/tiers.mjs` | **已经抠好的透明 PNG** | 手上只有成品，或绿幕原图已不在 |
+
+**不要把已经抠过的图再喂给 `assets.mjs`** —— 那是二次抠图，结果依赖"透明像素里是否还残留
+绿色"。抠图在这里是幂等的**假象**，不是保证。两个工具都会拒绝明显不对的输入：
+`assets.mjs` 在"键控几乎无效"时退出，`tiers.mjs` 在"没有 alpha 通道"时退出。
+
 ## 为什么不用透明背景
 
 服务端的 `transparent: true` **会把不该抠的抠掉**：角色是深蓝/浅蓝/白配色，浅蓝渐变的**发梢**与
@@ -66,6 +235,55 @@
 所以：**出图用绿幕，抠图自己做**（`node tools/assets.mjs`），只有 0.4%–0.7% 的边缘像素需要处理，
 发丝一根不丢。
 
+## 耳部写法：两个实测出来的坑（都能复现）
+
+**坑一：不要提"缺口"或"锯齿"** —— 哪怕是用来说"不要锯齿"。
+
+社区的鳍耳下缘确实有极轻微的波浪，我一开始把它当成最重要的识别点写（"下缘有 3 个半圆缺口，像被剪了三刀"），
+结果**三份不同写法全都画成了锋利的尖牙/锯子边**（A / B / C 三个版本一次全中）。
+更糟的是往里写"不要尖锐的锯齿、不要像锯子"也没用 —— **负面词同样会招来那个形状**。
+
+正确写法：只说**正面**的形状语言 —— "上缘是一条光滑的弧线，下缘也是一条光滑连续的弧线，
+只有极轻微的自然起伏"，把"缺口"整个不提。实测这样出来的边缘是干净的（E / F）。
+
+**坑二：尺寸不是主要问题，朝向才是。**
+
+用户反馈"耳朵太大了"时，我把长度从"头宽的三分之一"一路缩到"三分之一"，结果**又缩过头**（E 太小）。
+放大社区立绘逐像素核对后发现：社区的鳍其实**很长（约等于头宽）**，问题是它**贴着头发向后下方掠**，
+而我做成了**朝上外张的翅膀**。正确写法是把"朝向"写成第①条、并明确否定三种错误朝向
+（向上竖、向两侧平伸、像翅膀张开），长度反而要写"约等于头宽"。
+
+**结论**：这几轮下来，纯文生图能做到的是"**同一个设计、一眼认出是同一个角色**"；
+做不到**像素级复刻** —— 社区自己的角色一致性工具也是一套训练过的 LoRA（见其 Civitai 模型页），
+而不是靠纯提示词。要求像素级一致时，纯文生图这条路是走不通的。
+
+## 写作技巧：要求要放在末尾的清单里
+
+同一个要求写在提示词**开头**会被忽略，写在末尾的**【画面完整性，逐条核对】**里才会被认真执行 ——
+**呆毛**就是这么拿到的：第一版写在开头，模型直接省略；写进清单（还编了号）之后一次就有了。
+双马尾、鲸尾、发尾完整这些一直生效的项，本来就都在那个清单里。
+
+清单里的每一条都要**可核对**：与其说"画得好看"，不如说"明显高出头发轮廓、是独立的一缕、不能被省略"。
+
+## 三个踩过的坑
+
+### 鲸鱼鳍 ≠ 鱼鳍（写"鳍"就会得到鱼鳍）
+
+原稿写的是「耳侧有鲸鱼鳍造型耳饰」。出来的是一对**带棘刺、有放射状鳍条、边缘锯形**的鱼鳍 ——
+那是热带鱼的鳍，不是鲸的。
+
+改了两轮才拿准措辞：
+
+| 措辞 | 结果 |
+|---|---|
+| 鲸鱼鳍造型耳饰 | ✗ 鱼鳍（带鳍条、棘刺） |
+| 细长圆润、像叶片 | ✗ 平滑了，但末端分叉，像羽毛 |
+| 柳叶、末端圆钝 | ✗✗ **跑偏成水滴形宝石耳坠**（"水滴/圆钝"把模型带去了宝石） |
+| **扁平的长条板、两端磨圆、宽度一致、边缘连续光滑；并显式排除"水滴、宝石、吊坠、羽毛"** | ✓ 扁平的圆头桨板 |
+
+教训：**形状类的要求要写成几何描述（扁平、等宽、圆头、边缘连续），而不是比喻**；比喻会各自联想，
+而且负面清单必须列全 —— 光说"不要鱼鳍"不够，还得说清"不是什么"。
+
 ## 三个踩过的坑
 
 1. **绿幕要求必须写在第一段**，否则模型可能改画黑底 —— 四角实测 `rgb(0,0,0)`，抠图直接失效。

package/tools/assets.mjs

@@ -16,8 +16,9 @@
      node tools/assets.mjs --from ./绿幕母版 --out ./assets
    ========================================================================== */
 
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync } from 'node:fs'
 import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -38,33 +39,41 @@ function loadSharp() {
 }
 
 const argv = process.argv.slice(2)
+/* 默认只写第一档（会进包的那一档）；--all-tiers 才写全部四档。 */
+const allTiers = argv.includes('--all-tiers')
 const flag = (name, fallback) => {
   const at = argv.indexOf(name)
   return at >= 0 && argv[at + 1] !== undefined ? argv[at + 1] : fallback
 }
-const MOODS = ['idle', 'happy', 'sleepy', 'work']
+const MOODS = ['idle', 'happy', 'sleepy', 'work', 'attn', 'poked', 'proud']
 const srcDir = resolve(here, flag('--from', 'masters'))
-const outDir = resolve(here, flag('--out', 'assets'))
+/* 皮肤 = assets/ 下的一个子目录。--skin 决定输出到哪一套。
+   注意 build.mjs 会把每个子目录当成一套皮肤打进包里，所以皮肤越多包越大。 */
+const skin = flag('--skin', '')
+const outDir = resolve(here, flag('--out', skin === '' ? 'assets' : join('assets', skin)))
 
 const T0 = 14
 const T1 = 96
-const TIERS = [
+/* 只有第一档会被 build.mjs 打进 JS 包并真正显示；其余三档运行时**从不读取**
+   （_hi 也测不出画质差别：DPR 2 差 0.3%，DPR 1/3 反而低 4~5%）。
+   所以默认只写第一档 —— 不让 9.9 MB 死重悄悄长回包里。
+   确实要用别的档重打包时：加 --all-tiers。 */
+const ALL_TIERS = [
   { suffix: '', w: 1024, q: 84 },
   { suffix: '_md', w: 512, q: 82 },
   { suffix: '_sm', w: 256, q: 80 },
   { suffix: '_hi', w: 2048, q: 86 },
 ]
+/* 选择语句必须**在数组定义之后**：放在前面会踩 TDZ（Cannot access before initialization）。 */
+const TIERS = allTiers ? ALL_TIERS : ALL_TIERS.slice(0, 1)
 
 if (!existsSync(srcDir)) {
   console.error(`母版目录不存在: ${srcDir}`)
   process.exit(1)
 }
-for (const mood of MOODS) {
-  if (!existsSync(join(srcDir, `${mood}.png`))) {
-    console.error(`缺少母版: ${join(srcDir, `${mood}.png`)}`)
-    process.exit(1)
-  }
-}
+/* 这里**不**要求每个情绪都有母版：给已有皮肤补一个新情绪（例如后来加的 poked）时，
+   别的母版早就没了。缺哪个由下面的循环逐条打印，最后用"一张都没处理"兜底 ——
+   既不因为缺一张就整条停下，也不会把"文件名写错"静默吞掉。 */
 mkdirSync(outDir, { recursive: true })
 
 const sharp = loadSharp()
@@ -102,9 +111,20 @@ async function key(srcPath, outPath) {
 
 console.log(`母版: ${srcDir}\n出图: ${outDir}\n`)
 console.log('mood    键控(不透明/边缘)      档位      尺寸         体积')
+let processed = 0
 for (const mood of MOODS) {
   const src = join(srcDir, `${mood}.png`)
-  const keyed = join(outDir, `.${mood}.keyed.png`)
+  /* 缺某个情绪的母版**不是错误**：给已有皮肤补一个新情绪（例如新加的 poked）时，
+     别的母版早就没了，只有这一张。以前这里会直接中止，于是"补一个情绪"必须先凑齐全部母版。
+     但也不能静默跳过 —— 打出来，好让"文件名写错"和"本来就没有"分得清。 */
+  if (!existsSync(src)) {
+    console.log(`  ${mood.padEnd(7)} 跳过（这个目录里没有 ${mood}.png）`)
+    continue
+  }
+  /* 抠图后的全尺寸 PNG 是**中间产物**，写到系统临时目录而不是 outDir：
+     以前它写在发布目录里、最后再删，删除一旦失败就在 assets/ 里留下 0 字节的隐藏残骸
+     （实测 classic 4 个、night 5 个，而且会随包发布）。中间产物根本不该出现在发布目录。 */
+  const keyed = join(tmpdir(), `wisp-key-${skin || 'default'}-${mood}-${process.pid}.png`)
   let meta
   try {
     meta = await key(src, keyed)
@@ -120,20 +140,23 @@ for (const mood of MOODS) {
       .webp({ quality: tier.q, alphaQuality: 92, effort: 6 })
       .toFile(out)
   }
+  processed++
   console.log(
     `  ${mood.padEnd(7)} ${(meta.opaque * 100).toFixed(1)}% / ${(meta.soft * 100).toFixed(2)}%`.padEnd(30),
     (TIERS[0].suffix || '默认').padEnd(8),
     `${Math.round(meta.w / 2)}x${Math.round(meta.h / 2)}`.padEnd(13),
     kb(statSync(join(outDir, `${mood}.webp`)).size),
   )
-  // 中间产物不留：它是全尺寸 PNG，四张能占几十 MB
-  writeFileSync(keyed, '')
-  const { rmSync } = await import('node:fs')
-  rmSync(keyed, { force: true })
+  // 中间产物在系统临时目录里，删不掉也只是临时目录的事，不会污染发布内容
+  try { rmSync(keyed, { force: true }) } catch (e) { /* 临时目录的残留无害 */ }
 }
 
+if (processed === 0) {
+  console.error('\n这个目录里一张母版都没找到 —— 检查 --from 是否指对了目录。')
+  process.exit(1)
+}
 if (failed > 0) {
   console.error(`\n${failed} 张母版抠图失败 —— 素材未更新，请检查这些图是否是干净的纯绿背景。`)
   process.exit(1)
 }
-console.log('\n完成。接着跑 `node build.mjs`（默认就用 <mood>.webp 那一档，要用 4K 档加 --tier=hi）。')
+console.log('\n完成。接着跑 `node build.mjs`（默认就用 <mood>.webp 那一档，要出别的档位加 --all-tiers）。')