dsh-happy 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-happy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-happy
+
+给 DSH 对话区加一层**整屏动效背景**：把整块画布当背景，用 Canvas 画星空、代码雨、电路、华山论剑、小猫、小女生、飞机大战、赛车、飘雪、肥皂泡；正文列用一层按列宽计算的纱罩住，保证可读。
+
+- 包名：`dsh-happy`（曾用名 `dsh-conversation-aurora`）
+- 插件目录：`dsh-happy/`（曾用名 `conversation-aurora/`）
+- patch 行 id：`happy`（内部行标识，不跟包名走）
+- Client 工厂 id：`dsh-happy`（必须与包名一致）
+- 预留名：`dsh-haowan`（仅占位，见 `reserved/dsh-haowan/`）
+- 宿主半区：`index.js`，空的（只需要一行可加载）
+- 仓库：<https://github.com/18383337799/dsh-happy>
+- 官网：<https://happy.yimeng.life/>
+
+---
+
+## 安装
+
+**从 npm 安装（推荐）**
+
+插件页 → **添加插件** → 输入包名 `dsh-happy` → 安装源选 **npm 官方** → 安装 → **立即启用**。
+
+> 国内镜像（`registry.npmmirror.com`）同步有延迟；刚发布时请先用官方源。
+
+**从本地目录安装（开发用）**
+
+插件页 → 添加插件 → 填本目录的绝对路径 → 安装 → 立即启用。
+
+**卸载**：插件页 → 卸载。效果随插件 context 一起回收，页面恢复原样。
+
+---
+
+## 用它
+
+| 快捷键 | 作用 |
+| --- | --- |
+| `Alt+T` | 换到下一个背景，并**固定**住（10 个循环，选择会记住） |
+| `Alt+R` | 回到**随机**，并立刻换一个（清掉固定值） |
+| `Alt+D` | 浅色 / 深色主题互换（走宿主 `theme.setTheme`，与「设置 → 外观」同步） |
+
+**它只在"你干活"的时候出现**：任何工具在跑、或回合进行中，背景才播放；空闲、切会话、窗口隐藏时立刻停掉 `requestAnimationFrame` 并淡出，两侧恢复普通白纸。
+
+**每个回合随机一个主题**：你发一条消息、我把这一轮做完 = 一个回合；回合内背景不变（中间停顿多久都不换），下一个回合重新随机，且不会和上一个重复。`Alt+T` 固定某个主题，`Alt+R` 回到随机并换一个。固定值存在 `localStorage` 的 `dsh.happy.theme`（0.4.0 之前是 `dsh.conversation-aurora.theme`，首次启动会自动搬过去）。
+
+---
+
+## 10 个背景
+
+| 主题 | 内容 |
+| --- | --- |
+| 星空跃迁 | 星点从中心向外飞出，长条纹 |
+| 代码雨 | 竖列字符下落，带拖尾 |
+| 电路脉冲 | 直角走线 + 沿线跑的光点 |
+| 华山论剑 | 三层远山视差 + 冷月 + 云岚 + 偶尔一道剑气 + 落叶（没有人物、没有招式名，只有山水与光） |
+| 小猫散步 | 矢量剪影小猫走路、尾巴摆动、留下爪印 |
+| 小女生 | 连衣裙剪影 + 马尾 + 牵着气球，一路小跑掉小心心 |
+| 飞机大战 | 我方战机从画面下方飞入、左右巡航连续开火，敌机从上方成批压下来，击中炸成火星 |
+| 赛车 | 横向速度线 + 小车剪影 |
+| 飘雪 | 雪花慢落 + 摇摆 |
+| 肥皂泡 | 径向渐变薄膜 + 高光，缓缓升起 |
+
+**加一种新背景**：在 `client.js` 里写一个 `themeXxx(g)`，返回 `{ resize(), step(dt) }`，再往 `STAGE_THEMES` 数组加一行 `{ id, name, create }`。`g` 提供 `{ ctx, w, h, pal }`。
+
+---
+
+## 可读性怎么保证
+
+- `.dsh-stage__veil` 是一条**按 `--dsh-chat-content-width` 计算**的横向纱：正文列内 84% 遮盖，列外 110px 内快速放开，两侧完全透明。
+- 浅色主题用 **`multiply`（正片叠底）+ 墨色**（靛蓝 / 紫 / 青），像印在白纸上；深色主题用 **`lighter`（加色）+ 亮色**，才有发光感。见 `stagePalette()`。
+- 背景层是 `z-index:-1`，永远在正文之下，`pointer-events:none`，不挡任何交互。
+
+---
+
+## 调参
+
+视觉参数集中在 `client.js` 顶部：
+
+| 位置 | 含义 |
+| --- | --- |
+| `TUNE.holdIdleMs` | 工具停下后多久淡出（默认 420ms，防抖） |
+| `TUNE.switchQuietMs` | 切会话后的静默期（默认 600ms） |
+| `stagePalette()` | 浅色/深色两套墨色 + 混合模式 |
+| `THEMES` 里各主题的常量 | 数量、速度、尺寸 |
+| `.dsh-stage__veil` 的 `.84` | 文字列遮盖强度，调高更护眼、调低更炫 |
+
+改完 `client.js` 后**刷新页面**即可（`Ctrl+R`）。
+
+---
+
+## 已知限制
+
+1. **依赖宿主的 DOM 语义属性**：`[data-conversation-content]` / `[data-tool][data-state]` / `[data-chat-running]` / `[data-streaming]`。DSH 大版本升级后如果这些改名，插件会安静地什么都不做（不会报错、不会挡交互）。
+2. **没有"背景层"插槽**：DSH 目前没有这个扩展点，所以背景层是挂在对话画布元素内部的（`z-index:-1`）。这是刻意偏离「只能注册进 slot」的地方，随插件停用一起消失。
+3. **切会话会静默 600ms**：避免把上一轮残留的工具行当成"正在工作"，看到几秒特效。
+4. **减少动态效果**：系统开启后只画一帧静止画面，不跑 `requestAnimationFrame`。
+5. **性能**：只有一张 canvas；每帧只做绘制，无 `filter`/`backdrop-filter`；空闲时 rAF 归零。
+6. **不做设置项**：没有「设置」里的面板，调参靠改常量。
+
+---
+
+## 官网
+
+在线：<https://happy.yimeng.life/>
+
+部署在 `aliyun99` 的 `/opt/myself/www/`（容器 `myself-web`，nginx 只读挂载 `./www`），这个子域名整站就是官网，根路径即首页；上传命令与校验见 [`site/README.md`](site/README.md) 的「部署」一节。
+
+官网只有一套，在 `site/index.html`：深空星野 + 紫/蜜桃柔光。左边一句「让 AI 对话，充满乐趣」，右边一块更大的玻璃对话面板；顶部 `DSH 插件` 胶囊，十个氛围名字排在面板下，点击切换；1440/1024 桌面完整一屏，不滚动。
+
+直接双击打开即可，不需要构建。也可以：
+
+```powershell
+python -m http.server 8806 --bind 127.0.0.1 --directory site
+```
+
+详见 [`site/README.md`](site/README.md)。
+
+---
+
+## 开发
+
+```powershell
+node --check client.js                 # 语法
+node tools/rename.mjs <新包名>          # 包名 + Client id 一起改（发布前用）
+npm pack --dry-run                     # 看会发出去哪些文件
+```
+
+发布：`npm version patch` → `npm publish`（需要 2FA 验证码）。新包名是 `dsh-happy`；旧包 `dsh-conversation-aurora` 用 `npm deprecate` 指向新名，不要 unpublish。
+
+占位包单独发布一次即可（`reserved/dsh-haowan/`，不随插件发布）：
+
+```powershell
+cd reserved/dsh-haowan
+npm publish            # 只要占名，0.0.1
+```
+
+## 文件
+
+```text
+dsh-happy/
+├─ package.json        dsh.bundle.patch + dsh.client
+├─ cordis.patch.yml    插入一行
+├─ index.js            Host 半区（空）
+├─ client.js           Client 半区：状态机 + 10 个背景主题
+├─ locale/zh.json      插件页标题与描述
+├─ locale/en.json
+├─ icon.svg
+├─ preview.html        离线预览（直接加载 client.js）
+├─ site/               官网站（另有 README）
+├─ reserved/dsh-haowan/ 占位包：只占名，发布到 npm 不含代码
+├─ tools/rename.mjs    发布前改名脚本
+├─ LICENSE
+└─ README.md
+```