dsh-theme-gallery 0.4.1 → 0.5.0

package/README.md

@@ -11,7 +11,7 @@
 | 自己做皮肤（或让 AI 做） | 在 `lib/themes/` 加 JSON 后重跑 `npm run embed-themes`，或装 `dsh-theme-skin-author` 技能让 AI 生成 |
 | 贡献一个皮肤给所有人 | 在 `lib/themes/` 放一个 JSON，提 PR |
 
-已随 **0.4.1** 发布 **7 套**皮肤：四套复刻自**蜂链商城**电商新零售系统管理后台
+已随 **0.5.0** 发布 **7 套**皮肤：四套复刻自**蜂链商城**电商新零售系统管理后台
 （[`renjie2026/fenglianshop-open`](https://github.com/renjie2026/fenglianshop-open) 的
 `admin-modular/src/utils/themes.js`），两套是本插件**原创**的宠物主题（同一套造色方法，色相取自中国传统色库），
 另有一套是**「纯色/拼色」配色选择器**卡片（15 个可点色值，见下）。
@@ -26,10 +26,14 @@
 | `hu-zi-a-huang` | **虎子阿黄**（原创） | `#896C39` 秋色（按钮/边框族） | `#F0C239` 缃色（中国传统色） |
 | `shi-liu-jin` | **纯色/拼色**（配色选择器） | `#F20C00` 石榴红（默认那套「石榴金」） | `#9D2933` 胭脂（按钮族） |
 
-面板里另有**两张内置外观卡**（`浅色` / `深色`）：它们**不是皮肤**，作用是把配色切回官方的浅色 / 深色
-（与「设置 → 通用 → 外观」同一套），所以**不计入上面这 7 套**。我们在官方浅色/深色上加了一点**小惊喜**
+面板里另有**两张内置外观卡**（`浅色` / `深色`）、**一张宠物挂件卡**（`宠物挂件 · 七只小伙伴`）
+和**一张心情问候卡**（`心情问候`）：它们**都不是皮肤**，所以**不计入上面这 7 套**。
+内置卡把配色切回官方的浅色 / 深色（与「设置 → 通用 → 外观」同一套），我们在官方浅色/深色上加了一点**小惊喜**
 —— 见 [效果预览](#效果预览) 最后一行。官方外观里的「跟随系统」**不出卡**：它就是浅色/深色二选一，
-再占一张卡只是重复。
+再占一张卡只是重复。宠物挂件卡则完全**不碰主题**：点头像换宠物、点卡身开关挂件，
+与任何皮肤都能同时开启（见 [宠物挂件](#宠物挂件七只小伙伴)）。
+心情问候卡同样**不碰主题**：它控制标题栏上一条滚动的问候语，默认开启、35 分钟换一条，
+可调速度 / 方向 / 位置区域（见 [心情问候语](#心情问候语)）。
 
 工作区里另有三套复刻皮肤仍在打磨，**尚未发布**：江畔冬云 `jiang-pan-dong-yun`、
 徐山军月 `xu-shan-jun-yue`、光彩凤晨 `guang-cai-feng-chen`。
@@ -510,7 +514,11 @@ if (active === void 0) throw new Error(`theme registry lost "${resolvedId}"`)
   **在此感谢作者 tristan 的整理与开源。**
 - 七套**复刻**皮肤的场景与配色复刻自**蜂链商城**电商新零售系统管理后台的主题：
   <https://github.com/renjie2026/fenglianshop-open>（该项目的开发者就是本插件的作者）。
-- 两套宠物主题（琥珀猫咪、虎子阿黄）与内置浅色/深色的卡片文案是本插件原创。
+- 两套宠物主题（琥珀猫咪、虎子阿黄）、内置浅色/深色与**宠物挂件家族（七只小宠物）**的美术、台词与实现是本插件原创。
+- **宠物挂件的「活性」设计**（宠物对工作状态的反应、闲聊的节奏控制）受社区插件
+  **`@linxin666/dsh-pet`**（作者 [@linxin666](https://www.npmjs.com/~linxin666) 及其上游资产作者）启发，
+  一期挂件的位置持久化也借鉴了它的思路，**在此感谢**。本插件的实现是独立的：
+  不注入任何额外服务，「模型生成中」的检测走的是 composer 按钮的无哈希 aria-label（DOM 信号）。
 
 如果你是要**转载或再分发**本插件：色值本身请按上面那条一并保留出处与致谢；
 复刻皮肤的场景素材请遵循蜂链商城仓库的许可。
@@ -565,6 +573,95 @@ document.body.setAttribute('data-dsh-theme-reading', reading.colorScheme)
 
 > **这是未公开的 DOM 契约。** 官方 UI 大改后可能失效。届时行为是**降级为始终空对话态外观**（主题继续覆盖整屏，只是不再变浅），不会把界面弄坏。要改判定逻辑，只动 `transcriptHasContent()` 一个函数。
 
+---
+
+## 宠物挂件（七只小伙伴）
+
+面板里还有一张 **`宠物挂件 · 七只小伙伴`** 卡（序号 74，压轴）。它**不是主题，也不是皮肤**：
+卡内是一行 **7 颗头像**（点哪只出哪只）+ 当前宠物与它道具的图案 + 开关徽标；
+挂件本体住在自己的固定层里，锚定**对话输入框**（地面线 = 输入框下缘）。
+
+- **点头像 = 换宠物**（挂件关着时顺路打开），**点卡身空白处 = 仅开关**；
+- 完全不碰主题服务 —— 与**任何皮肤**同时开启（包括山青婷彩 / 梦海游鱼），不消耗主题写入预算，
+  官方「设置 → 通用 → 外观」不会多出这一项，"N 款皮肤"的计数也不含它；
+- 它**不配 `ambient`**，侧栏素材区一个元素都不加。
+
+### 家族成员
+
+| 名字 | 物种 | 性格 | 道具 | 步态 |
+|---|---|---|---|---|
+| 斑斑 | 小奶狗 | 忠诚跟班 | 毛线团 | 跑 |
+| 大橘 | 橘猫 | 慵懒监工，嘴硬心软 | 小鱼干 | 跑（快些） |
+| 雪球 | 垂耳兔 | 软萌治愈系 | 胡萝卜 | **蹦跳** |
+| 波波 | 小企鹅 | 冷静靠谱的行动派 | 小银鱼 | **摇摆步** |
+| 糯米 | 仓鼠 | 干饭小能手 | 瓜子 | 跑（小步快跑） |
+| 阿赤 | 小狐狸 | 机敏小军师 | 松果 | 跑（最优雅） |
+| 团团 | 熊猫 | 淡定干饭哲人 | 竹笋 | **摇摆步**（慢摇） |
+
+每只都有自己的**名字记忆**（改名按宠物各自保存）、**戳一下的口头禅**（转身面对你说两句）、
+**脚印形状**、**闲聊台词**与**加油 / 完成台词**。全体共享：眨眼、待机微动画
+（尾巴 / 耳朵 / 翅膀 / 肚皮呼吸）、`prefers-reduced-motion` 时全部动画关闭。
+
+### 玩法
+
+| 交互 | 怎么玩 |
+|---|---|
+| 开关 / 换宠 | 点挂件卡：**头像 = 换一只并放它出场**，卡身空白处 = 仅开关。状态记在 `localStorage`（`theme-gallery:pet`），重启后还记得 |
+| 戳一下 | 移到宠物身上（头顶名牌出现）→「戳一下」：它转过身**面对你说两句口头禅** |
+| 改名 | 名牌上「改名」→ 输入新名字 → 回车保存（最长 10 字；**每只宠物各自记住自己的名字**） |
+| 拖动 | 宠物和道具都能拖到**屏幕任意位置**，位置按视口边缘记住（缩放后自愈）；松手后它**跑/蹦/摇**着去找自己的道具 |
+| 朝向 | 头始终朝向道具；缺省摆位里道具在宠物**左侧**，所以它们面朝左 |
+| 脚印 | 跑动时沿路留下**随物种变化的小脚印**（爪印 / 蹼印 / 米粒点 / 大掌印…），约 3.5 秒淡出 |
+
+### 它还知道你在干活（活性机制）
+
+- **悄悄话**：待机超过两分钟，它可能冒一句自己的闲聊（每只 4 句；你一逗它就重新计时，绝不吵）；
+- **打字回头**：你在输入框里敲字，它会转过头看着输入框、精神一下（15 秒节流）；
+- **为你加油**：模型生成回答时（桌面端输入框会变成「停止生成」按钮），它原地小跳 + 喊加油；
+  回答完成时再庆祝一句。检测不到该信号就安静待机，不影响任何其他功能。
+
+几条刻意的安全设计（与侧栏素材同一套纪律）：
+
+- 舞台容器 `pointer-events:none`，**只有宠物和道具本身可以交互** —— 绝不挡输入框的点击与输入；
+- 移动循环复用插件的单帧助手，**只在跑动中自续**，停下即断；脚印与气泡都有**数量上限**与超时回收，
+  闲聊是单个可取消的定时器，拆台即清 —— 不会无界堆积（跑飞的事故见 [开发](#开发) 一节的背景）；
+- 名字等文本一律以 `textContent` 写入，**不进任何 HTML 字符串**；
+- 急停开关与侧栏素材同源：`cordis.patch.yml` 里 `config: { ambient: false }` 会把挂件一并停掉；
+- 挂件状态（开关 / 当前宠物 / 名字表 / 位置偏移）**只存 `localStorage`**，绝不写 `ui-theme.preference`；
+  一期「小狗斑斑」的旧数据（名字 / 摆位）升级时**自动迁移**，不用重新设置。
+
+---
+
+## 心情问候语
+
+面板里还有一张 **`心情问候`** 卡（序号 73，挂在挂件卡之后）。它**不是主题，也不是皮肤**：
+它控制**标题栏顶部**（应用/编辑菜单右侧、窗口按钮左侧那条空拖拽带）的一条滚动问候语，
+比如「早安，愿你所遇皆温柔，所行皆坦途」。
+
+- **默认开启**；卡面上的**胶囊开关**（或点卡身）随时开/关，状态记在 `localStorage`（`theme-gallery:mood`）；
+- **每 35 分钟换一条**，同一句在两次换条之间**无缝循环滚动**（文字再短也不停）；
+- 语料是插件**内置**的正向短句库（61 条，五类：早安 / 白天 / 夜深 / 通用 / 节假日）：
+  按时段选池（05–11 早安、11–22 白天、22–次日 05 夜深），**节日池优先**（国庆 / 春节 / 端午等，
+  区间写成 `MM-DD` 每年复用）；同一天同池顺序稳定、跨天洗牌不同 —— "每天不重样"是本地实现的，
+  断网 / 离线一个字不少；
+- **三组设置**（卡面上的 chips，点哪组哪组亮）：
+  - 速度：慢速 / **中速** / 快速；
+  - 方向：**自左至右** / 自右至左；
+  - 位置区域：标题栏减去左侧菜单后的水平段**分成 5 等份**——左靠齐占第 1–4 等份、
+    **居中占满**、左右缩进占中间 3 等份、右靠齐左侧留 1 等份。留空的位置是给
+    将来可能安装的其他插件的；
+- 系统**减少动态效果**时静止显示（超长省略号截断），35 分钟换条照常 —— 功能保留、只停动画；
+- 文字是纯展示（`pointer-events:none`），不挡标题栏拖拽，也不可点；
+- 语料红线：**只有正向明亮的句子**。建期校验（`npm run embed-themes`）里有负面/敏感词黑名单，
+  命中即构建失败 —— 坏语料进不了包。语料来源是作者自己的「更新管理平台」站点
+  （装修管理 → 心情问候语，40 条种子），另有 21 条为插件新增。
+
+几条刻意的安全设计（与宠物挂件同一套纪律）：文字一律 `textContent`（不进任何 HTML 字符串）；
+有界工作 —— 一个 35 分钟的链式 `setTimeout` + 一个 `resize` 监听，没有轮询；
+状态只存 `localStorage`，绝不写 `ui-theme.preference`；问候条是否真的建出来，
+面板诊断区有一行自检读数（警告无条件显示，例行读数走 debug 开关）。
+
+
 ---
 
 ## 加自己的皮肤
@@ -697,7 +794,7 @@ dsh-theme-gallery/
 │   ├── build-panel-preview.mjs   # 生成面板卡片顺序/文案预览页
 │   ├── lib/card-rows.mjs         # 卡片色块（card.rows）的校验（建期与测试共用）
 │   └── serve-bench.mjs           # 启动调参台
-├── tests/                # 20 组校验（一个 *.mjs 文件一组；lib/ 是共用解析器）
+├── tests/                # 22 组校验（一个 *.mjs 文件一组；lib/ 是共用解析器）
 ├── types/                # 契约校验源（不参与运行）
 └── lib/
     ├── index.js          # 宿主：注册 theme-gallery settings 命名空间（预留扩展点，当前无人读取）
@@ -715,17 +812,17 @@ dsh-theme-gallery/
 
 ```sh
 pnpm install
-pnpm run check     # tsc + npm test 的 20 组校验 + 内联皮肤 + 重建两个预览页
+pnpm run check     # tsc + npm test 的 22 组校验 + 内联皮肤 + 重建两个预览页
 pnpm run bench     # 调参台
 ```
 
-`pnpm run check` = `typecheck && test && embed-themes && preview:ambient && preview:panel`；`npm test` 的 **20 组**按职责分六类：
+`pnpm run check` = `typecheck && test && embed-themes && preview:ambient && preview:panel`；`npm test` 的 **22 组**按职责分六类：
 
 1. **`tsc`（exit 0）**：`types/*.ts` 用官方发布的真实类型包校验插槽注册契约、`defineStore` 座位形状、主题注册与 token 契约。
 2. **契约与桩**：`check-schema`（真实 schemastery 解析 + **10 个反向用例**，含缺 `label`、缺 `description`、`reading.alpha` 越界）、`smoke-host`（**真机加载** `lib/index.js` 跑 `apply`，并守住 `inject` 清单与插槽门控）、`check-store-contract`（`handle.create()` 每次返回新实例）、`check-client-module`（bundle 形状、挂载失败必须可见）。
 3. **启动安全与端到端引导**：`check-boot-safety`（`inject` 清单、无 `modifies` 环）、`check-boot-timing`、`check-boot-path`（桩里跑完整引导：上色确认、默认皮肤、点内置卡不被弹回、切内置主题后素材保留 —— 每条都带**反证**）。
 4. **静态审计（含自检与变异反证）**：`check-declaration-order`、`check-tdz-order` + `check-tdz-logic`、`check-scope-reach` + `check-scope-reach-logic`、`check-undefined-calls`、`check-bounded-work`（有界工作量：指纹守卫、单一路径渲染、循环有截止）、`check-self-emit-guard` + `check-self-emit-guard-logic`（数出**全部**主题服务写入点）。
-5. **主题与皮肤**：`check-theme-contribution`（贡献逻辑与幂等，并断言**注册的 token 必须是字符串**——成对对象会变成 `[object Object]`）、`check-card-order`（卡片顺序、内置卡文案、默认皮肤、色块排版 `card.rows`，含 **17 处变异反证**）、`check-ambient-render`（场景标记与关键帧）。
+5. **主题与皮肤**：`check-theme-contribution`（贡献逻辑与幂等，并断言**注册的 token 必须是字符串**——成对对象会变成 `[object Object]`）、`check-card-order`（卡片顺序、内置卡文案、默认皮肤、色块排版 `card.rows`，含 **17 处变异反证**）、`check-pet-registry`（宠物家族注册表：七只齐全、美术四件套、动画锚点与 PET_CSS 对得上、台词与步态参数在界内、斑斑一期资产指纹、预览页七只都在，含 **4 处变异反证**）、`check-ambient-render`（场景标记与关键帧）、`check-mood`（心情问候语：语料红线黑名单、时段/节日/洗牌轮换、5 等份区域几何、默认开与胶囊开关、shell.overlay 座位与有界性，含 **10 处变异反证**）。
 6. **介绍文字不落后于实际**：`check-copy-consistency-logic` —— 核对 README 的皮肤清单 / 数量 / 版本 / 入口说法、面板与预览页的计数口径、README 里写的校验组数，与 `lib/themes`、`package.json`、`lib/client.js` 一致（**10 处变异反证 + 1 个"正式发布一套皮肤必须全过"的对照组**）。发布自检 `npm run publish:check` 用同一份实现，所以"改了皮肤忘了改文案"会在发布前被拦住。
 
 `scripts/embed-themes.mjs` 校验每套皮肤（形状 / id 唯一 / 双配色 / 12 必需 token / `reading`）后内联进 `lib/client.js`，幂等；两个预览页随后重建。