dsh-conversation-aurora 0.1.0 → 0.2.1

package/README.md

@@ -1,11 +1,8 @@
 # dsh-conversation-aurora
 
-给 DSH 对话区加动效背景。两套预设，可随时切换：
+给 DSH 对话区加一层**整屏动效背景**：把整块画布当背景，用 Canvas 画星空、代码雨、电路、小猫、小女生、赛车、飘雪、肥皂泡；正文列用一层按列宽计算的纱罩住，保证可读。
 
-- **预设 A `edge`（默认）**：两侧边缘光 + HUD 骨架，严格避开正文列。
-- **预设 B `stage`**：把整块画布当背景，全屏 Canvas 动画。内置 8 个主题：`星空跃迁` `代码雨` `电路脉冲` `小猫散步` `小女生` `赛车` `飘雪` `肥皂泡`，中间用一条按列宽计算的纱罩住文字，保证可读。
-
-- 包名：`dsh-conversation-aurora`（npm 上发布）
+- 包名：`dsh-conversation-aurora`
 - 插件目录：`conversation-aurora/`
 - patch 行 id：`dsh-conversation-aurora`
 - Client 工厂 id：`dsh-conversation-aurora`（必须与包名一致）
@@ -13,220 +10,96 @@
 
 ---
 
-## 切换与快捷键
-
-| 快捷键 | 作用 |
-| --- | --- |
-| `Alt+M` | 在「边缘光 / 整屏背景」两套预设之间切换（记住选择） |
-| `Alt+T` | 换下一个背景主题（记住选择） |
-| `Alt+B` | 循环强度：标准 / 安静 / 关闭 |
-| `Alt+D` | 浅色 / 深色主题互换（走宿主 `theme.setTheme`，与「设置 → 外观」同步） |
-
-选择存在 `localStorage`：`dsh.conversation-aurora.preset`、`dsh.conversation-aurora.theme`。
-
-## 预设 B：整屏背景
-
-- 每个会话默认分配**不同主题**（按 `data-conversation-session` 哈希，切会话就换一张）。
-- 只在“我在干活”时播放：空闲 / 切会话 / 窗口隐藏都会立刻停掉，`requestAnimationFrame` 归零，不占 CPU。
-- 文字可读性靠 `.dsh-stage__veil`：一条按 `--dsh-chat-content-width` 计算的横向白纱（深色主题是深色纱），文字列内 84% 遮盖、两侧放开。
-- **浅色主题用 `multiply`（正片叠底）**，配色换成更饱和的"墨色"——效果像印在白纸上，而不是给白色蒙一层；**深色主题用 `lighter`（加色）**，才会有发光感。两套都由 `stagePalette()` 里的 `blend` 字段控制。
-- 加一种新背景：在 `client.js` 的 `themeXxx(g)` 旁边写一个函数，返回 `{ resize(), step(dt) }`，再往 `STAGE_THEMES` 数组里加 `{ id, name, create }` 一行即可。`g` 提供 `{ ctx, w, h, pal }`。
-
----
-
-## 它是什么
+## 安装
 
-一句话：**4 种手势 + 2 个全局调制，共用同一条「列边光纤」，外面套一层常驻的 HUD 骨架**。
+**从 npm 安装（推荐）**
 
-背景层的任务是气氛，不是状态栏——中间的工具行已经写清楚在干什么了，那么两侧只负责「这台机器现在是什么状态」。
+插件页 → **添加插件** → 输入包名 `dsh-conversation-aurora` → 安装源选 **npm 官方** → 安装 → **立即启用**。
 
-| 状态 | 触发信号 | 你看到的 |
-| --- | --- | --- |
-| `idle` | 没有运行中的工具、没有输出 | **整层淡出，两侧回到普通白纸**（不留任何装饰） |
-| `think` | `[data-chat-running]` 或 `[data-streaming]` | 同上，呼吸从 9s 加快到 3s |
-| `read` | 检索 / 读文件类工具 | 光纤上的亮段**向下流动**，像扫描头经过（左主右辅） |
-| `web` | 联网 / 子代理 / 工作流类工具 | 光纤心跳 + 一圈光**向外扩散**（右主左辅） |
-| `write` | 写文件 / 跑命令类工具 | 光纤**自下而上**逐段点亮（左主右辅）+ 数据柱上流 |
-| `wait` | `ask_user_question` 正在等你 | 全体降到 ~2%、转灰蓝、缓慢向列内推 |
-| `error` | 最近有工具 `data-state=error/stopped` | 红色泛光 1.3s，之后留一点暗红到下一次动作 |
+> 国内镜像（`registry.npmmirror.com`）同步有延迟；刚发布时请先用官方源。
 
-两侧还有一层常驻的 **HUD 骨架**（`--hud-opacity` 统一控制）：取景角标框住正文列、竖排遥测小字（状态 / 工具名 / 滚动十六进制读数 + 光标）、扫描纹与 96px 竖向刻度网格、持续下落的数据柱、以及每 3.4s 一趟的扫描光带。状态切换时角标会轻微位移一次，并伴随一次 130ms 的 glitch（光纤青/品红分离 + HUD 错位）；活动期间每 6s 左右也会自发一次。
+**从本地目录安装（开发用）**
 
-**浅色主题走"墨线 + 纸面"**：两侧空白带是极淡的冷灰蓝渐变（越靠窗口边越深，到正文列边界归白），网格、角标、遥测用近黑墨色，只有活动信号（光纤、扫描段、数据柱）是蓝色的。深色主题换成发光蓝紫青 —— 同一套结构，两种材质。
+插件页 → 添加插件 → 填本目录的绝对路径 → 安装 → 立即启用。
 
-> 试过把两侧做成**纯黑面板**，在白页面里会变成"黑白三明治"，很丑，已回退。想让整块画布都变暗，正确做法是切换 DSH 的深色主题（文字颜色才会一起变），而不是只把两侧涂黑。
-
-这是「手势」不是「语义标签」：三件事靠**运动方向**（下流 / 外扩 / 上长）区分，不靠三种不同的装饰。主侧只改强度和 0.7s 相位，不承载含义，所以不用学任何约定。
+**卸载**：插件页 → 卸载。效果随插件 context 一起回收，页面恢复原样。
 
 ---
 
-## 装进 DSH
-
-1. 打开 Web UI → 左侧 **插件** → **添加插件**。
-2. 填这个目录的绝对路径，例如 `D:\project\DSH-Plugs\conversation-aurora`。
-3. 安装后点 **立即启用**（只关闭对话框的话包已装好但没选中）。
-4. 打开任意会话，两侧出现效果；左侧插件页该行应为 `active`。
+## 用它
 
-**生效方式**
-
-| 改了什么 | 怎么生效 |
+| 快捷键 | 作用 |
 | --- | --- |
-| `client.js`（几乎所有改动） | 刷新页面（仍是旧代码就重启 Desktop） |
-| `package.json` / `locale` / `icon.svg` | 插件页把该 bundle 关一下再开，或重启 Desktop |
-| `cordis.patch.yml` | 同上 |
-
-**卸载**：插件页 → 卸载。效果随插件 context 一起回收，页面恢复原样。
-想临时关掉而不卸载：`Alt+B` 循环「标准 → 安静 → 关闭」。
+| `Alt+T` | 换下一个背景（8 个循环，选择会记住） |
+| `Alt+D` | 浅色 / 深色主题互换（走宿主 `theme.setTheme`，与「设置 → 外观」同步） |
 
----
+**它只在"你干活"的时候出现**：任何工具在跑、或回合进行中，背景才播放；空闲、切会话、窗口隐藏时立刻停掉 `requestAnimationFrame` 并淡出，两侧恢复普通白纸。
 
-## 调参
-
-视觉参数全部集中在 `client.js` 里 CSS 字符串开头的 `.dsh-aurora{...}` 块，改一处就够：
-
-| 变量 | 默认（浅色 / 深色） | 含义 |
-| --- | --- | --- |
-| `--glow-opacity` | `.22` / `.3` | 两侧柔光强度。**调亮或调淡**就动它 |
-| `--wash-color` | `78,98,150` / `40,62,110` | 底光色：浅色下是低饱和冷灰蓝 |
-| `--hud-ink` | `15,17,21` / `190,214,255` | HUD 墨色：角标 / 网格 / 遥测 / 扫描光带 / 数据柱都用它 |
-| `--hud-opacity` | `1` | HUD 层总开关。**觉得太吵就调到 `.4`** |
-| `--fiber-opacity` | `.16` / `.22` | 静息光纤亮度（呼吸的基准） |
-| `--gesture-opacity` | `.5` / `.56` | 检索亮段 / 写码生长条的亮度 |
-| `--pulse-opacity` | `.4` / `.46` | 联网时向外扩散那圈光的峰值 |
-| `--fiber-width` | `1.5px` | 光纤粗细 |
-| `--drift-slow` / `--drift-fast` | `40s` / `52s` | 两团柔光漂移周期。**想更慢**就同时加大 |
-| 柔光团尺寸 | `150% × 62%` 色带 | 在 `.dsh-aurora__blob`，按色带自身宽高算，画布再高也不会只剩两个角 |
-| `--secondary-strength` | `.6` | 副侧强度 |
-| `--crossfade` | `700ms` | 状态切换的淡入淡出 |
-| 光纤离正文列的距离 | `20px` | 在 `.dsh-aurora__fiber` 的 `left/right:20px`。**想更靠边**就加大 |
-| 角标大小 / 离列距离 | `16px` / `20px` | `.dsh-aurora__corner` |
-| 遥测字号 / 透明度 | `9px` / `rgba(…,.55)` | `.dsh-aurora__telemetry` |
-| 柔光的可用宽度 | `(100% - 列宽)/2` | 由 `.dsh-aurora__wing` 的宽度决定，自动跟随正文列宽 |
-
-时序参数在文件顶部的 `TUNE`：
-
-| 键 | 默认 | 含义 |
-| --- | --- | --- |
-| `minDwellMs` | `600` | 状态最短驻留；短于它的切换会被忽略，防止连续调工具时闪 |
-| `pulseMs` / `pulseRise` | `420` / `.16` | 状态切换时那次单次亮脉冲 |
-| `errorHoldMs` | `1300` | 红光保持多久后转入残留 |
-| `seedRows` | `24` | 首次挂载只回看最近多少行（避免历史失败行触发红光） |
-| `maxTracked` | `48` | 最多跟踪多少工具行（长会话也不拖慢） |
-| `intensity` | `[1, .55, 0]` | `Alt+B` 循环的三档 |
-| `keyCode` | `'b'` | 快捷键字母 |
-
-工具 → 手势的映射在 `TOOL_MODE`（按工具名）和 `VARIANT_MODE`（按 `data-variant` 兜底）。新增工具时加一行即可。
+**每次开始干活随机换一个主题**（8 个里随机，且不会连着重复）。按过 `Alt+T` 之后会变成全局固定主题；想恢复"每会话自动"，删掉 `localStorage` 里的 `dsh.conversation-aurora.theme` 即可。
 
 ---
 
-## 怎么知道我在干什么
-
-全部读宿主**已有的语义属性**，不读哈希类名、不读别的插件的 DOM 结构：
-
-- `[data-tool="web_search"][data-state="running"]` —— 工具行与状态（`preparing / running / ok / error / stopped`）
-- `[data-chat-running]` —— 回合进行中的指示器（“正在深潜”）
-- `[data-streaming]` —— 正在流式输出
+## 8 个背景
 
-工具行的收集不是每次全量查询：用 `MutationObserver` 增量收集、只保留尾部 48 个，变更用 48ms 定时器合并（不用 rAF——窗口被遮挡/无头环境里 rAF 会被节流，状态会卡住）。
+| 主题 | 内容 |
+| --- | --- |
+| 星空跃迁 | 星点从中心向外飞出，长条纹 |
+| 代码雨 | 竖列字符下落，带拖尾 |
+| 电路脉冲 | 直角走线 + 沿线跑的光点 |
+| 小猫散步 | 矢量剪影小猫走路、尾巴摆动、留下爪印 |
+| 小女生 | 连衣裙剪影 + 马尾 + 牵着气球，一路小跑掉小心心 |
+| 赛车 | 横向速度线 + 小车剪影 |
+| 飘雪 | 雪花慢落 + 摇摆 |
+| 肥皂泡 | 径向渐变薄膜 + 高光，缓缓升起 |
 
-**切换会话时会静默 700ms**：切会话的瞬间，上一轮的工具行可能还挂在 DOM 上，历史里的失败行也会被当成新事件——不处理的话会看到几秒钟的假特效再自己消失。所以检测到 `data-conversation-session` 变化（或画布被换掉）时，会清空跟踪表、重置错误基线、强制回到空闲，等新会话挂载稳定再重新判断。
+**加一种新背景**：在 `client.js` 里写一个 `themeXxx(g)`，返回 `{ resize(), step(dt) }`，再往 `STAGE_THEMES` 数组加一行 `{ id, name, create }`。`g` 提供 `{ ctx, w, h, pal }`。
 
 ---
 
-## 验证
-
-**看效果**：双击 `preview.html`（离线单文件）。它不复制样式，而是用一个最小模块加载器替身**直接加载 `client.js`**，所以看到的就是真实实现。
-面板里可以切 7 个状态、切明暗、拖正文列宽、点「几何检查」看列与光纤的实际坐标（会把透明度临时拉高并画出边界）。
-
-**减少动态效果**：
-- Windows：设置 → 辅助功能 → 视觉效果 → 关闭「动画效果」；或
-- DevTools → Rendering → Emulate CSS media feature `prefers-reduced-motion: reduce`；
-- 预览面板底部会显示当前检测结果。
+## 可读性怎么保证
 
-开启后所有动画停止，只保留每个状态的静态色与亮度（`client.js` 末尾的 `@media (prefers-reduced-motion: reduce)` 块）。
-
-**装机后检查清单**
-
-- [ ] 插件页该行是 `active`。
-- [ ] 浅色 / 深色主题各看一次，正文没有任何亮度或位置变化。
-- [ ] 发一条会触发工具的指令：检索时左主、联网时右主、写码时从下往上。
-- [ ] 快速连续调工具时不闪（`minDwellMs` 生效）。
-- [ ] 拖正文列宽，光纤跟着列一起移动。
-- [ ] 关掉插件后页面完全恢复（没有残留 `<style>`、没有 `dsh-aurora-host` 类）。
-- [ ] 切到别的会话再切回来，效果还在。
-- [ ] 窗口最小化再恢复，动画继续（`document.hidden` 暂停）。
+- `.dsh-stage__veil` 是一条**按 `--dsh-chat-content-width` 计算**的横向纱：正文列内 84% 遮盖，列外 110px 内快速放开，两侧完全透明。
+- 浅色主题用 **`multiply`（正片叠底）+ 墨色**（靛蓝 / 紫 / 青），像印在白纸上；深色主题用 **`lighter`（加色）+ 亮色**，才有发光感。见 `stagePalette()`。
+- 背景层是 `z-index:-1`，永远在正文之下，`pointer-events:none`，不挡任何交互。
 
 ---
 
-## 已知限制 / 设计取舍
-
-1. **挂载点不是插槽。** DSH 目前没有「背景层」插槽，所以这层动效挂在对话画布元素内部（`[data-conversation-content]`，找不到时退回「从输入框往上找不透明背景」）。
-   这与工作区 README「UI 只能注册进 slot」的约定有出入，属于**刻意**的例外：效果必须画在正文下面、画布背景之上，slot 里没有任何位置满足。
-   代价是它依赖宿主 DOM 的稳定性。缓解措施：优先用语义属性；`MutationObserver` 检测重挂载；10 次/2 秒的反复摘挂保护（超过就放弃，宁可没有效果也不抖）；全程 `try/catch`，找不到画布就静默不做事。
-
-2. **DSH 升级可能改属性名。** 若 `data-tool` / `data-state` / `data-conversation-content` 被重命名，效果会退化成「只剩 idle 的柔光」，不会报错、不会遮挡交互。
-
-3. **正文列有约 0–8px 的居中偏移**，来自滚动条与 2px 外边距。插件会量出滚动条宽度补成 `--aurora-shift`，让左右光纤到列的距离一致；量不到就按 0 处理。
-
-4. **窗口很窄时两侧空白带会收窄甚至消失**，效果随之变细（最小约 88px，光纤仍固定在列外 20px），不会侵入正文。
-
-5. **右侧空白带里有 DSH 自己的「回合导航」刻度条**（28px，窄窗自动隐藏）。联网的扩散光会从它底下经过，两者都是低对比元素，视觉上不冲突。
-
-6. **动效层在 `z-index:8`**：输入区自带一条 sticky 的「渐变为白」遮罩，会盖住窗口最底部两侧的空白带；把层提到它上面，空白带才能一直铺到窗口底边。正文列和输入框都在列宽范围内，动效层的翼也止于列边界，所以不会盖到任何内容（输入框那 16px 外扩落在翼的遮罩尾部，透明度已接近 0）。
-   代价：正文列两侧的拖宽手柄被这一层盖住**看不见了**，但 `pointer-events:none` 让它仍然可以拖。
-
-6. **`wait` 只认 `ask_user_question`**；审批卡片、plan 待确认目前不单独触发（它们仍会有 `think`/`idle` 的基础呼吸）。
+## 调参
 
-7. **`Alt+B` 的强度选择不持久化**，刷新回到标准档（避免往 localStorage 写东西）。
+视觉参数集中在 `client.js` 顶部：
 
-8. **不做设置项**：v1 没有「设置 → 通用」里的行，调参靠改 `client.js` 里的常量（改完刷新页面）。
+| 位置 | 含义 |
+| --- | --- |
+| `TUNE.holdIdleMs` | 工具停下后多久淡出（默认 420ms，防抖） |
+| `TUNE.switchQuietMs` | 切会话后的静默期（默认 600ms） |
+| `stagePalette()` | 浅色/深色两套墨色 + 混合模式 |
+| `THEMES` 里各主题的常量 | 数量、速度、尺寸 |
+| `.dsh-stage__veil` 的 `.84` | 文字列遮盖强度，调高更护眼、调低更炫 |
 
-9. **性能**：常驻只有 4 个柔光 + 2 条光纤 + HUD；动画只碰 `transform` / `opacity`；不使用 `filter: blur()` 与 `backdrop-filter`；页面隐藏时 `animation-play-state: paused`；关掉（`Alt+B` 第三档）时 `display:none`，不再合成。
+改完 `client.js` 后**刷新页面**即可（`Ctrl+R`）。
 
 ---
 
-## 发布到 registry（给别人用）
-
-DSH 的「添加插件」支持三种来源：包名（走 npm registry）、Git 地址、本地目录。走 registry 时，安装的人只要填**包名**，并选下载源（npm 官方 / 国内镜像 / 自定义地址）。
-
-**1. 改成可发布的包名**
+## 已知限制
 
-包名同时出现在三个地方，必须一致，用脚本一次改完：
+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. **不做设置项**：没有「设置」里的面板，调参靠改常量。
 
-```powershell
-cd conversation-aurora
-node tools/rename.mjs dsh-conversation-aurora
-# 或带 scope： node tools/rename.mjs @your-name/dsh-conversation-aurora
-```
-
-脚本会改 `package.json` 的 `name`、`client.js` 的 `__ModuleLoader__` id、`cordis.patch.yml` 的 `name`，并去掉 `private`。`@local/...` 是本地占位名，公共 registry 不接受。
-
-**2. 检查产物**
-
-```powershell
-npm pack --dry-run
-```
-
-应该只有 10 个文件、约 33 kB：`LICENSE` `README.md` `client.js` `cordis.patch.yml` `icon.svg` `index.js` `locale/*.json` `package.json` `preview.html`（`tools/` 不会被打包）。
+---
 
-**3. 发布**
+## 开发
 
 ```powershell
-npm login
-npm publish                    # 带 @scope 的包要加 --access public
-# 私有 registry：
-npm publish --registry https://your-registry.example.com/
+node --check client.js                 # 语法
+node tools/rename.mjs <新包名>          # 三处 id 一起改（发布前用）
+npm pack --dry-run                     # 看会发出去哪些文件
 ```
 
-**4. 别人安装**
-
-插件页 → 添加插件 → 填包名 → 源：
-- 发的公共 npm → 选「npm 官方」（刚发布的包国内镜像有几小时同步延迟，第一天建议先选官方）
-- 发的私有 registry → 选「自定义地址」填 registry URL（凭据写在使用者本机的 `~/.npmrc`）
-
-**注意**：改完包名后，旧的那份要卸载重装——DSH 是按包名认插件的，改名后旧的引用会失效。升级时改 `version` 再发一次即可，用户重装或等插件页提示。
-
----
+发布：`npm version patch` → `npm publish`（需要 2FA 验证码）。
 
 ## 文件
 
@@ -235,10 +108,12 @@ conversation-aurora/
 ├─ package.json        dsh.bundle.patch + dsh.client
 ├─ cordis.patch.yml    插入一行
 ├─ index.js            Host 半区（空）
-├─ client.js           Client 半区：全部实现 + 可调常量
+├─ client.js           Client 半区：状态机 + 8 个背景主题
 ├─ locale/zh.json      插件页标题与描述
 ├─ locale/en.json
 ├─ icon.svg
 ├─ preview.html        离线预览（直接加载 client.js）
+├─ tools/rename.mjs    发布前改名脚本
+├─ LICENSE
 └─ README.md
 ```