dsh-wisp 1.42.0 → 1.48.0

package/lib/index.js

@@ -28,11 +28,200 @@
 // "npm first, GitHub as fallback" would read the stale npm number and claim you
 // were up to date.
 
+/* `node:url` / `node:module` are imported statically: this file is loaded by
+   the Loader as an ordinary ES module, and both are needed on the module's
+   first line of work (resolving the package's own asset directory). */
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+/* ---------------------------------------------------------------------------
+   MOTION CLIPS OVER HTTP (v1.47.0) — the delivery seam for the frame
+   animations.
+
+   WHY THIS EXISTS. Until 1.46.5 the animated WebPs were base64-inlined into
+   lib/client.js by build.mjs. Two 720p clips already cost 7.83 MB of base64;
+   the eight swimsuit clips would have added ~30 MB and taken the browser half
+   to roughly 45 MB. That is not a budget problem that can be squeezed — it is
+   the wrong place to put multi-megabyte video-ish assets.
+
+   HOW THE PACKAGE CAN STILL DELIVER THEM. A browser half that inlines nothing
+   has exactly two documented ways to reach bytes: `@deepseek-ai/dsh-client-
+   resources` (a `dsh-resource://` live-VALUE model for slot components — it
+   needs a React provider and yields values, not an image URL, so it is not an
+   asset route), and the platform's own HTTP carrier. `dsh-host-webserver` is
+   documented as "let the feature plugins claim their routes", `ctx.webServer`
+   and `ctx.fs` are both live Host services, and the Loader imports THIS file
+   as an ES module — so `import.meta.url` resolves the package directory. That
+   is a complete path from the package's own files to an `<img src>`:
+
+     <pkg>/assets/motion/<clip>.webp
+       -> GET <origin>/wisp-motion/<clip>.webp   (this route)
+       -> new URL('wisp-motion/<clip>.webp', document.baseURI)   (client half)
+
+   The browser half never calls `fetch` (it is a trapped global) and never
+   learns a filesystem path: it only asks the page's own origin for a URL.
+
+   WHAT HAPPENS WHEN IT IS NOT THERE. Every failure is silent and already
+   specified elsewhere in this plugin: an unregistered route (the Desktop
+   carrier serves the shell without an HTTP server), a 404, a decode error —
+   the `<img>` fires `error`, the client half hides the motion layer and hands
+   the picture back to the static sprite. Nothing throws, nothing is logged,
+   and there is still exactly one of her on screen. `__wisp.doctor().motion.
+   frame` reports it.
+
+   SCOPE. The handler is deliberately a closed list, not a file server: one
+   path segment, `<name>.webp`, no separators, no percent-decoding games,
+   nothing outside <pkg>/assets/motion/. Anything else is a 404.
+   --------------------------------------------------------------------------- */
+
+/** URL prefix the browser half asks for. Kept in sync with MOTION_ROUTE in lib/client.template.js. */
+export const MOTION_PATH = '/wisp-motion/'
+
+/** Only these names are servable. A clip name never contains a separator. */
+const MOTION_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*\.webp$/
+
+/** Refuse to serve anything larger than this even if it lands in assets/motion/. */
+export const MOTION_MAX_BYTES = 12 * 1024 * 1024
+
+/**
+ * Absolute path of one shipped clip, or null when the name is not servable.
+ *
+ * `import.meta.url` is the installed lib/index.js, so `../assets/motion/` is
+ * the package's own asset directory whether the profile installed this from
+ * npm or linked it from a checkout.
+ *
+ * @param name - the requested file name (already stripped of the route prefix).
+ * @returns the host path, or null when the name must not be served.
+ */
+export function motionFile(name) {
+  if (typeof name !== 'string' || !MOTION_NAME.test(name)) return null
+  try {
+    return fileURLToPath(new URL(`../assets/motion/${name}`, import.meta.url))
+  } catch (error) {
+    return null
+  }
+}
+
+/**
+ * Build the route handler. Split out from registration so the preflight can
+ * drive it with a fake request/response pair — the response shape is the part
+ * that must not drift from what the browser half expects.
+ *
+ * @param readBytes - `(absolutePath) => Uint8Array | null`, never throws.
+ * @returns a `node:http`-shaped handler.
+ */
+export function motionHandler(readBytes) {
+  return async function handleMotion(req, res) {
+    const send = (status, headers) => {
+      try { res.writeHead(status, headers) } catch (error) { /* headers already out */ }
+      try { res.end() } catch (error) { /* client vanished */ }
+    }
+    let pathname = '/'
+    try { pathname = new URL(String(req && req.url ? req.url : '/'), 'http://wisp.invalid').pathname } catch (error) { /* keep '/' */ }
+    if (pathname === MOTION_PATH.slice(0, -1) || pathname === MOTION_PATH) {
+      /* The bare prefix is not a list endpoint — there is nothing to enumerate. */
+      send(404, { 'content-type': 'text/plain; charset=utf-8' })
+      return
+    }
+    if (!pathname.startsWith(MOTION_PATH)) {
+      send(404, { 'content-type': 'text/plain; charset=utf-8' })
+      return
+    }
+    const file = motionFile(pathname.slice(MOTION_PATH.length))
+    if (file === null) {
+      send(404, { 'content-type': 'text/plain; charset=utf-8' })
+      return
+    }
+    const method = String((req && req.method) || 'GET').toUpperCase()
+    if (method !== 'GET' && method !== 'HEAD') {
+      send(405, { allow: 'GET, HEAD', 'content-type': 'text/plain; charset=utf-8' })
+      return
+    }
+    const bytes = readBytes(file)
+    if (bytes === null || bytes === undefined || bytes.byteLength === 0) {
+      send(404, { 'content-type': 'text/plain; charset=utf-8' })
+      return
+    }
+    if (bytes.byteLength > MOTION_MAX_BYTES) {
+      send(413, { 'content-type': 'text/plain; charset=utf-8' })
+      return
+    }
+    const headers = {
+      'content-type': 'image/webp',
+      'content-length': String(bytes.byteLength),
+      /* The clip name is the identity: a changed clip is a new file, not a new
+         body under the same URL. A day of cache keeps a reload cheap without
+         pinning a stale loop for the life of the page. */
+      'cache-control': 'public, max-age=86400',
+      'x-content-type-options': 'nosniff',
+    }
+    if (method === 'HEAD') { send(200, headers); return }
+    try {
+      res.writeHead(200, headers)
+      res.end(bytes)
+    } catch (error) {
+      try { res.destroy() } catch (e) { /* already gone */ }
+    }
+  }
+}
+
+/**
+ * Register the motion route on the platform's HTTP carrier.
+ *
+ * Optional on purpose: `webServer` does not exist under every carrier, and a
+ * missing route is the documented silent-degradation path, not a load failure.
+ * `node:fs` is reached lazily through `createRequire` so importing this module
+ * never depends on it.
+ *
+ * @param ctx - the plugin context.
+ * @returns `{ registered, why }` — never throws.
+ */
+export function registerMotionRoute(ctx, options = {}) {
+  const read = options.readBytes ?? defaultReadBytes
+  try {
+    if (!ctx || typeof ctx.inject !== 'function') return { registered: false, why: 'no-ctx-inject' }
+    const path = typeof options.path === 'string' ? options.path : MOTION_PATH
+    ctx.inject(['webServer'], (webCtx) => {
+      if (!webCtx || typeof webCtx.webServer?.register !== 'function') return
+      try {
+        webCtx.effect(
+          () => webCtx.webServer.register({ kind: 'prefix', path, handler: motionHandler(read) }),
+          'dsh-wisp: motion clips over the host HTTP carrier',
+        )
+      } catch (error) {
+        /* 注册失败（例如路由被占）不能让整个插件倒掉：这条路由是**可选**的，
+           没有它画面就是静态立绘。 */
+      }
+    })
+    return { registered: true, path }
+  } catch (error) {
+    return { registered: false, why: String(error && error.message ? error.message : error).slice(0, 120) }
+  }
+}
+
+/**
+ * Read one clip from disk. Returns null instead of throwing: every caller
+ * treats "cannot read" as "serve 404", which the browser half already turns
+ * into the static sprite.
+ *
+ * @param absolutePath - the clip's host path.
+ * @returns the bytes, or null.
+ */
+export function defaultReadBytes(absolutePath) {
+  try {
+    const require = createRequire(import.meta.url)
+    const fs = require('node:fs')
+    return new Uint8Array(fs.readFileSync(absolutePath))
+  } catch (error) {
+    return null
+  }
+}
+
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'wisp'
 
 /** Stamped into every balance request. Must match package.json — the preflight guards it. */
-export const VERSION = '1.42.0'
+export const VERSION = '1.48.0'
 
 /**
  * `web` and `deepseekAccount` are optional on purpose. A required inject that
@@ -50,8 +239,23 @@ export const DEFAULT_SOURCES = {
 /** How long ONE source may take before it is reported as a timeout. */
 const CHECK_TIMEOUT_MS = 8000
 
+/** 这个包自己的名字 —— 兜底通道（问插件管理器）按包名查。 */
+const UPDATE_PACKAGE_NAME = 'dsh-wisp'
+
+/** 一眼看懂一个"服务"到底是什么（诊断用；永远不抛）。 */
+function describeService(value) {
+  if (value === undefined) return 'undefined'
+  if (value === null) return 'null'
+  const type = typeof value
+  if (type !== 'object' && type !== 'function') return type
+  try {
+    const keys = Object.keys(value).slice(0, 6).join(',')
+    return type + '{' + keys + '}' + (typeof value.fetch === 'function' ? '+fetch' : '-fetch')
+  } catch (error) { return type + '(unreadable)' }
+}
+
 /**
- * Resolve the `web` service LATE, on every call.
+ * Resolve the `web` service LATE, on every call — and say HOW, and what was found.
  *
  * `inject.optional: ['web']` hands us `ctx.web`, but only when the service was
  * already provided at the moment this fiber materialized — and this half is
@@ -60,20 +264,75 @@ const CHECK_TIMEOUT_MS = 8000
  * which would disable the update check forever. `ctx.get('web')` looks the
  * service up at call time instead, so a startup race cannot wedge it.
  *
- * @returns the service, or undefined when this shell really has none.
+ * 真实运行里两种路都拿不到时，**必须能说清是哪一种**：`ctx.get` 有没有？
+ * 拿到的东西是什么形状？—— 没有这一层，"没有联网的通道"是一句无法追问的话。
+ *
+ * @returns `{ service, how, why }` — never throws.
+ *   how: 'ctx.get' | 'ctx.web' | 'none'   拿到了没有、从哪拿的
+ *   why: 一句话说明"看到了什么"（进了 doctor 与她的失败台词）
  */
 export function resolveWebService(ctx) {
+  let late
+  let getThrew = null
   try {
-    if (ctx && typeof ctx.get === 'function') {
-      const late = ctx.get('web')
-      if (late && typeof late.fetch === 'function') return late
-    }
-  } catch (error) { /* restricted context: fall through to the declared property */ }
+    if (ctx && typeof ctx.get === 'function') late = ctx.get('web')
+    else getThrew = 'ctx.get 不是函数（' + describeService(ctx && ctx.get) + '）'
+  } catch (error) { getThrew = 'ctx.get 抛错：' + String(error && error.message ? error.message : error).slice(0, 60) }
+  if (late && typeof late.fetch === 'function') {
+    return { service: late, how: 'ctx.get', why: 'ctx.get("web")→' + describeService(late) }
+  }
+  let declared
+  let webThrew = null
+  try { declared = ctx && ctx.web } catch (error) { webThrew = String(error && error.message ? error.message : error).slice(0, 60) }
+  if (declared && typeof declared.fetch === 'function') {
+    return { service: declared, how: 'ctx.web', why: 'ctx.web→' + describeService(declared) }
+  }
+  const parts = []
+  parts.push('ctx.get("web")→' + describeService(late))
+  if (getThrew) parts.push(getThrew)
+  parts.push('ctx.web→' + describeService(declared))
+  if (webThrew) parts.push('ctx.web 读取抛错：' + webThrew)
+  /* 拿到了对象但没有 fetch 也要如实说 —— "有服务但没这个方法"和"根本没有服务"是两件事 */
+  const service = (late && typeof late === 'object') ? late : ((declared && typeof declared === 'object') ? declared : undefined)
+  if (service) {
+    return { service, how: 'partial', why: parts.join('; ') + '（无 fetch）' }
+  }
+  return { service: undefined, how: 'none', why: parts.join('; ') }
+}
+
+/**
+ * 兜底通道：向插件管理器问"这个包现在是什么版本"。
+ *
+ * 它本来就是**去 registry 问这个包**的那个人（安装前先 inspect），所以这条路
+ * 走的是应用自己那条网络出口、且尊重用户配的镜像源 —— 比我们自己去抓 packument
+ * 更接近"安装时会装到哪一版"。`web` 服务拿不到时，这是唯一还活着的更新通道。
+ *
+ * @returns `{ ok, version, registry }` 或 `{ ok: false, reason, detail }` — never throws.
+ */
+export async function readManagedVersion(ctx, name, timeoutMs) {
+  let manager
+  try {
+    if (!ctx || typeof ctx.get !== 'function') return { ok: false, reason: 'no-ctx-get' }
+    manager = ctx.get('pluginManager')
+  } catch (error) {
+    return { ok: false, reason: 'manager-unreachable', detail: String(error && error.message ? error.message : error).slice(0, 80) }
+  }
+  if (!manager || typeof manager.inspect !== 'function') {
+    return { ok: false, reason: 'no-plugin-manager', detail: describeService(manager) }
+  }
   try {
-    const declared = ctx && ctx.web
-    if (declared && typeof declared.fetch === 'function') return declared
-  } catch (error) { /* no such property */ }
-  return undefined
+    const info = await withTimeout(manager.inspect(name), timeoutMs)
+    if (info && info.status === 'accepted' && typeof info.version === 'string') {
+      return { ok: true, version: info.version, registry: info.registry ?? null }
+    }
+    return {
+      ok: false,
+      reason: 'inspect-refused',
+      detail: info && info.reason ? String(info.reason).slice(0, 100) : describeService(info),
+    }
+  } catch (error) {
+    return { ok: false, reason: 'inspect-failed', detail: String(error && error.message ? error.message : error).slice(0, 100) }
+  }
 }
 
 /**
@@ -84,7 +343,10 @@ export function resolveWebService(ctx) {
  * @returns `{ ok, version }` or `{ ok: false, reason }` — never throws.
  */
 export async function readVersion(web, url, signal) {
-  if (!web || typeof web.fetch !== 'function') return { ok: false, reason: 'no-web-service' }
+  if (!web) return { ok: false, reason: 'no-web-service' }
+  /* "有服务但没有 fetch"和"根本没有服务"是两件事 —— 台词的下一步动作不同
+     （一个是应用/平台的问题，一个是插件注入的问题），所以别合并成一句。 */
+  if (typeof web.fetch !== 'function') return { ok: false, reason: 'web-has-no-fetch', detail: describeService(web) }
   try {
     const res = await web.fetch({ url }, signal)
     if (!res || typeof res.statusCode !== 'number') return { ok: false, reason: 'bad-result' }
@@ -305,9 +567,38 @@ export function registerHandlers(ctx, options = {}) {
   const dispose = seat.handle('checkUpdate', async (args) => {
     const current = args && typeof args.current === 'string' ? args.current : null
     /* 服务**在调用时**解析，不用闭包里那个可能早就定格的 ctx.web（见 resolveWebService）。 */
-    const web = resolveWebService(ctx)
-    const verdict = await readPublishedVersion(web, urls, undefined, CHECK_TIMEOUT_MS)
-    return { ...verdict, current, checkedAt: new Date().toISOString() }
+    const resolved = resolveWebService(ctx)
+    if (resolved.service) {
+      const verdict = await readPublishedVersion(resolved.service, urls, undefined, CHECK_TIMEOUT_MS)
+      return { ...verdict, current, diag: { via: 'web', how: resolved.how, why: resolved.why }, checkedAt: new Date().toISOString() }
+    }
+    /* 没有可用的 web 服务时的兜底：问插件管理器"这个包现在是什么版本"。
+       它走的是应用自己那条网络出口（安装前就要去 registry 问），所以这条路
+       是"安装时会装到哪一版"的权威答案 —— 而且不依赖插件能否拿到 web。 */
+    const managed = await readManagedVersion(ctx, UPDATE_PACKAGE_NAME, CHECK_TIMEOUT_MS)
+    const sources = { npm: managed.ok
+      ? { ok: true, version: managed.version }
+      : { ok: false, reason: managed.reason, detail: managed.detail } }
+    if (managed.ok) {
+      return {
+        ok: true,
+        latest: managed.version,
+        from: 'npm',
+        sources,
+        current,
+        diag: { via: 'pluginManager', how: resolved.how, why: resolved.why, registry: managed.registry ?? null },
+        checkedAt: new Date().toISOString(),
+      }
+    }
+    sources.github = { ok: false, reason: 'no-web-service', detail: resolved.why }
+    return {
+      ok: false,
+      reason: 'no-web-service',
+      sources,
+      current,
+      diag: { via: 'none', how: resolved.how, why: resolved.why, manager: managed.reason + (managed.detail ? '：' + managed.detail : '') },
+      checkedAt: new Date().toISOString(),
+    }
   })
   /* The balance handler. `ctx.deepseekAccount` is undefined unless the platform
      provides it — readBalance() turns that into `no-account-service` rather than
@@ -338,6 +629,10 @@ export function apply(ctx, config) {
       if (typeof result.dispose === 'function') result.dispose()
     }, 'dsh-wisp: host handlers')
   }
+  /* v1.47.0: the frame-animation clips are files in this package, served to
+     the page over the host HTTP carrier. Optional and silent — see the block
+     above MOTION_PATH. */
+  registerMotionRoute(ctx, config || {})
 }
 
 export default { name, inject, apply }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-wisp",
-  "version": "1.42.0",
+  "version": "1.48.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",

package/tools/CHARACTER-PROMPT.md

@@ -57,14 +57,14 @@
 
 【姿态】__按情绪替换，见下表__
 
-【画面完整性】画面中只有一个角色。头发必须是深蓝色超长双马尾，不要画成短发、不要盘发、不要白色头发；鲸尾必须可见且与身体连接；发尾干净完整；手指完整；五官清晰。
+【画面完整性】画面中只有一个角色。头发是深蓝色中长直发、自然披散，不要画成双马尾、不要马尾、不要盘发、不要白色头发；头顶的大圆环呆毛清楚可见、不能被省略；鲸尾必须可见且与身体连接；发尾干净完整；手指完整；五官清晰。
 
 【背景】纯绿色背景（绿幕）：整张背景是一整片均匀的纯绿色，没有任何渐变、纹理、阴影或其他物体；角色完全被纯绿色包围，不要在地面投下阴影。
 
 【构图】全身直立、脚底贴住画面底边、角色居中。
 ```
 
-## 【姿态】七选一（对应七个 sprite）
+## 【姿态】八选一（对应八个 sprite）
 
 | 文件 | 姿态 |
 |---|---|
@@ -75,6 +75,7 @@
 | `attn.png` | 身体微微前倾，一只手抬到胸前朝前方招了招，像是在叫对方过来；眉头微蹙、认真地直视前方，带着一点催促。 |
 | `proud.png` | 双手抱在胸前，下巴微微抬起，眼睛半闭着、嘴角上扬，神情带着一点不掩饰的得意；身体微微后仰，站得很稳。 |
 | `poked.png` | 身体明显往后一缩、双肩微微耸起，一只手抬到胸前摆出「等一下」的姿势（掌心朝前）；眼睛睁得比平时大、眉毛微挑，嘴巴小小地抿着，带着一点惊讶与抗议。 |
+| `eat.png` | 双手捧着一碗盛得冒尖的白米饭，捧在胸腹前，闭着眼睛开心地笑，脸颊微红。 |
 
 ---
 
@@ -115,8 +116,12 @@
 
 ## 第三套皮肤：宵蓝礼服（`night`）
 
-形象要素与旗舰那套**逐字相同**（深蓝超长双马尾、鲸尾、白色荷叶边女仆发箍、鲸鱼发夹、鳍耳饰、
-细蓝颈饰、成熟成年体型、画风段、画面完整性段、构图段），**只替换【服装】段**：
+形象要素与母版**逐字相同**（深蓝中长直发、大圆环呆毛、鲸鳍耳、白色荷叶边女仆发箍 + 蓝色鲸鱼发夹、
+鲸尾、细蓝颈饰、成年女性成熟身型、画风段、画面完整性段、构图段），**只替换【服装】段**：
+
+> 这一段原来写的是「超长双马尾」（这一套**最早**那批的身份）。1.24.0 把四套旧皮肤按新规格
+> **全部重出**之后，宵蓝礼服也是**直发 + 呆毛**那一版 —— 重出 `attn` 时按这个身份写，才对得上
+> 已发布的七张。**以母版为准。**
 
 ```
 【服装】单层深蓝色露肩礼服：一字露肩剪裁，低领口露出锁骨与肩线；裙身单层薄料、修身、裙摆及膝略短、
@@ -126,6 +131,17 @@
 五张姿态照第 49 行那张表，一张不改。实测键控质量 0.45%–0.61% 软边（与前两套同级），
 入包那档合计 821 KB。
 
+> **`attn` 重出过一次**：那一张画坏了 —— 头/高只有 **0.113**（同套其余七张 0.19–0.25）、
+> 举起的右手比脸还大、鲸鳍耳大得像一对翅膀，取景也只有 **93.0%**（其余七张 96.8%–99.7%），
+> 于是切到「她在叫你过来」时会先缩一圈。重出时把「取景占满 97% 以上」「约 6.5–7 头身、
+> 头不要画小」「抬起的手掌与脸相当、鳍耳约为头宽四分之一」写进末尾清单 → 新图头/高 **0.218**、
+> 取景 **98.6%**，与同套 `idle` 的 0.217 对齐。母版在 `masters/night/attn.png`；
+> 审计里 `night/attn.webp` 有一条重出记录（旧条目标为「已被取代」，不参与哈希比对）。
+
+> **整套八张随后又重出过一次**：这一套（和另外四套）原本**八张都没有鲸尾**。
+> 重出时把鲸尾写进末尾编号清单（见上面「写作技巧」那节的第二个例子），八张一次到位；
+> 实测键控 0.34%–0.48% 软边、取景 0%–27px 留白。母版在 `masters/night/`。
+
 > 三套皮肤的差别是"**同一件人之外的东西换了**"：换掉服装而不是换掉身份，所以三张站稳的图
 > 放在一起仍然认得出是同一个人。这是刻意的 —— 皮肤不是不同角色。
 
@@ -215,6 +231,37 @@
 | 服装 | 单层吊带短裙（本插件的风格） | **长袖全套女仆装 + 白袜 + 深蓝圆头皮鞋**（社区规范） |
 | 鲸鳍耳 | 有 | 有（同样向后下斜掠、双色、下缘锯齿） |
 
+## 第六套皮肤：碧海泳装（`swim`）
+
+形象要素与母版**逐字相同**（深蓝中长直发、大圆环呆毛、鲸鳍耳、白色荷叶边女仆发箍 + 蓝色鲸鱼发夹、
+鲸尾、细蓝颈饰、成年女性成熟身型、画风段、画面完整性段、构图段），**只替换【服装】段**：
+
+```
+【服装】性感的深蓝色比基尼泳装：上身为深蓝色三角比基尼，细系带绕过颈后与后背；下身同色系带式泳裤，
+两侧腰际各系一个深蓝色小蝴蝶结；外面披一件极薄的白色薄纱罩衫，前襟敞开、长度到大腿中部、
+随身体自然垂落；不穿长袜；脚穿白色细带高跟凉鞋；手腕戴一圈细蓝色腕饰。
+```
+
+八张姿态照上表，一张不改（`eat` 用表里补上的那一行）。实测键控 **0.33%–1.39%** 软边，
+入包那档合计 **990 KB**。
+
+参数与前面几套完全一致：`gpt` / `4K` / `2048x3072` / `2:3` / `high` / `thinking high` /
+**不传参考图、不图生图**，一张一次调用。九次调用（含一次重出）已按哈希链记入
+`audit/generation-audit.jsonl`，全部来自 `generate_image`。
+
+> **`happy` 出过三版，两次都是末尾清单救回来的**：
+> ① 第一版身材与泳装比其余七张瘦、上衣还画成了横条 → 补「⑧ 成熟丰满的成年女性身型：胸部曲线明显，
+>    不要画成瘦削」「⑨ 泳装必须清楚可辨：三角罩杯 + 颈后与后背的细系带」；
+> ② 第二版身材对了，但**取景偏小**：内容只占画布高度 **93.2%**（头顶留白 70px、脚底 35px），
+>    而其余七张是 96.7%–99.0% —— 切到「开心」时她会**明显缩一圈** → 再补「⑩ 取景必须与其余各张
+>    完全一致：占满画面高度 97% 以上，上下留白各不超过 2%」「⑪ 体型比例必须与其余各张一致：
+>    约 6.5–7 头身，头不要画小、腿与躯干不要拉长」；③ 第三版（入包版）占 **99.7%**。
+>
+> **教训**：举手、跳跃这类姿势最容易把人物画小，而「切表情时她缩了一下」只有把八张**并排量过**
+> 才看得出来 —— 单看一张永远是对的。三版母版都留着（`masters/swim/_happy_v1.png` / `_happy_v2.png`），
+> 审计日志里 `happy.webp` 有两条重出记录（旧条目标为「已被取代」，不参与哈希比对）。
+> **末尾清单这一招又一次生效**（同「呆毛」那次的教训：写在开头的会被忽略）。
+
 ## 两个工具的分工
 
 | 工具 | 输入 | 什么时候用 |
@@ -265,6 +312,14 @@
 
 清单里的每一条都要**可核对**：与其说"画得好看"，不如说"明显高出头发轮廓、是独立的一缕、不能被省略"。
 
+**第二个例子：鲸尾（1.46.x 才发现的）。** 六套皮肤里只有新做的 `swim` **每一格都有鲸尾**，
+其余五套的 39 张**一张都没有** —— 而「身后从腰部长出一条蓝色鲸尾，尾鳍自然向下，必须在画面中
+清楚可见」这句明明写在身份段里。差别只在末尾清单：新那套写成编号的
+「④ 从腰后长出来的蓝色鲸尾必须清楚可见：尾柄从腰侧或腰后伸出、尾鳍自然向下、尖端正对下方，
+在画面里是一块独立而明显的深蓝色到浅蓝渐变的形状，**不能被头发、裙摆或双腿挡住，不能被省略**」；
+旧那五套的清单里只有一句「鲸尾必须可见且与身体连接」。
+**同一个要求：写成编号、并且说清"不能被什么挡住"，才会被执行。**
+
 ## 三个踩过的坑
 
 ### 鲸鱼鳍 ≠ 鱼鳍（写"鳍"就会得到鱼鳍）
@@ -296,11 +351,12 @@
 ## 全流程
 
 ```bash
-# 1. 按上面的参数与提示词，为四个情绪各生成一张绿幕图，存成 <mood>.png
-# 2. 绿幕 -> 抠图 -> 四档素材，一步到位
-node tools/assets.mjs --from <绿幕母版目录>
-# 3. 把素材打进客户端半包
-node build.mjs --tier=hi        # hi 档 = 2048x3072，与母版同尺寸，仅重新编码
+# 1. 按上面的参数与提示词，为**八个**情绪各生成一张绿幕图，存成 <mood>.png
+#    一张一次调用，不要把多张塞进 batch —— 提示词不同，混着出会串味
+# 2. 绿幕 -> 抠图 -> 默认档素材（1024x1536 入包档），一步到位
+node tools/assets.mjs --from <绿幕母版目录> --skin <皮肤>
+# 3. 把素材打进客户端半包（默认档就是入包的那一档）
+node build.mjs
 # 4. 预检
 node verify-wisp.mjs
 ```

package/tools/audit-log.mjs

@@ -99,7 +99,14 @@ export function verifyAudit(root = here) {
     if (chainHash(e) !== e.hash) problems.push('第 ' + e.index + ' 条内容被改动（hash 不匹配）')
     prev = e.hash
   }
-  const assets = log.filter((e) => e.kind === 'confirm' && e.output && e.output.path)
+  /* 同一个入包文件被**重出**过时，日志里会有多条 confirm —— 历史必须留着（那正是这个日志
+     存在的意义），但要比对的是**最新**那一条：它才代表现在入包的东西。旧条目标为「已被取代」，
+     记录在案、不再参与哈希比对；否则任何一次重出都会让预检永久变红。 */
+  const confirms = log.filter((e) => e.kind === 'confirm' && e.output && e.output.path)
+  const latestOf = new Map()
+  for (const e of confirms) latestOf.set(e.output.path, e)
+  const assets = [...latestOf.values()]
+  const superseded = confirms.filter((e) => latestOf.get(e.output.path) !== e)
   for (const e of assets) {
     const p = resolve(root, e.output.path)
     if (!existsSync(p)) { problems.push(e.output.path + ' 不见了'); continue }
@@ -109,6 +116,7 @@ export function verifyAudit(root = here) {
   const declaredNone = log.filter((e) => e.kind === 'declare' && e.declared
     && Array.isArray(e.declared.reference_images) && e.declared.reference_images.length === 0)
   return { entries: log.length, assets, problems, img2img, declaredNone: declaredNone.length,
+    superseded: superseded.length,
     backfilled: log.filter((e) => e.source === 'registry-backfill').length }
 }
 
@@ -131,8 +139,9 @@ if (flag('--verify')) {
   }
   const img2img = log.filter((e) => e.registry && e.registry.tool === 'edit_image')
   const unknown = log.filter((e) => e.registry && e.registry.tool && !['generate_image', 'batch_generate_images', 'edit_image'].includes(e.registry.tool))
-  console.log(`  记录 ${log.length} 条（declare ${log.filter((e) => e.kind === 'declare').length} / confirm ${assets.length} / backfill ${log.filter((e) => e.source === 'registry-backfill').length}）`)
+  console.log(`  记录 ${log.length} 条（declare ${log.filter((e) => e.kind === 'declare').length} / confirm ${log.filter((e) => e.kind === 'confirm').length} / backfill ${log.filter((e) => e.source === 'registry-backfill').length}）`)
   console.log(`  覆盖入包素材 ${assets.length} 个，全部存在且哈希一致：${missing === 0 && bad === 0 ? '是' : '否'}`)
+  if (res.superseded > 0) console.log(`  另有 ${res.superseded} 条是同一文件的更早版本（重出记录：历史保留、不参与比对）`)
   console.log(`  代理登记表显示使用过 edit_image（图生图）的条目：${img2img.length}`)
   if (img2img.length > 0) for (const e of img2img) console.log(`    ⚠ ${e.name}  ${e.registry.createdAt}`)
   if (unknown.length > 0) console.log(`  ⚠ 未识别的工具名：${unknown.map((e) => e.registry.tool).join(', ')}`)