dsh-conversation-aurora 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 conversation-aurora 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,244 @@
-# Temporary Holding Version
+# dsh-conversation-aurora
 
-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 对话区加动效背景。两套预设，可随时切换：
+
+- **预设 A `edge`（默认）**：两侧边缘光 + HUD 骨架，严格避开正文列。
+- **预设 B `stage`**：把整块画布当背景，全屏 Canvas 动画。内置 8 个主题：`星空跃迁` `代码雨` `电路脉冲` `小猫散步` `小女生` `赛车` `飘雪` `肥皂泡`，中间用一条按列宽计算的纱罩住文字，保证可读。
+
+- 包名：`dsh-conversation-aurora`（npm 上发布）
+- 插件目录：`conversation-aurora/`
+- patch 行 id：`dsh-conversation-aurora`
+- Client 工厂 id：`dsh-conversation-aurora`（必须与包名一致）
+- 宿主半区：`index.js`，空的（只需要一行可加载）
+
+---
+
+## 切换与快捷键
+
+| 快捷键 | 作用 |
+| --- | --- |
+| `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 骨架**。
+
+背景层的任务是气氛，不是状态栏——中间的工具行已经写清楚在干什么了，那么两侧只负责「这台机器现在是什么状态」。
+
+| 状态 | 触发信号 | 你看到的 |
+| --- | --- | --- |
+| `idle` | 没有运行中的工具、没有输出 | **整层淡出，两侧回到普通白纸**（不留任何装饰） |
+| `think` | `[data-chat-running]` 或 `[data-streaming]` | 同上，呼吸从 9s 加快到 3s |
+| `read` | 检索 / 读文件类工具 | 光纤上的亮段**向下流动**，像扫描头经过（左主右辅） |
+| `web` | 联网 / 子代理 / 工作流类工具 | 光纤心跳 + 一圈光**向外扩散**（右主左辅） |
+| `write` | 写文件 / 跑命令类工具 | 光纤**自下而上**逐段点亮（左主右辅）+ 数据柱上流 |
+| `wait` | `ask_user_question` 正在等你 | 全体降到 ~2%、转灰蓝、缓慢向列内推 |
+| `error` | 最近有工具 `data-state=error/stopped` | 红色泛光 1.3s，之后留一点暗红到下一次动作 |
+
+两侧还有一层常驻的 **HUD 骨架**（`--hud-opacity` 统一控制）：取景角标框住正文列、竖排遥测小字（状态 / 工具名 / 滚动十六进制读数 + 光标）、扫描纹与 96px 竖向刻度网格、持续下落的数据柱、以及每 3.4s 一趟的扫描光带。状态切换时角标会轻微位移一次，并伴随一次 130ms 的 glitch（光纤青/品红分离 + HUD 错位）；活动期间每 6s 左右也会自发一次。
+
+**浅色主题走"墨线 + 纸面"**：两侧空白带是极淡的冷灰蓝渐变（越靠窗口边越深，到正文列边界归白），网格、角标、遥测用近黑墨色，只有活动信号（光纤、扫描段、数据柱）是蓝色的。深色主题换成发光蓝紫青 —— 同一套结构，两种材质。
+
+> 试过把两侧做成**纯黑面板**，在白页面里会变成"黑白三明治"，很丑，已回退。想让整块画布都变暗，正确做法是切换 DSH 的深色主题（文字颜色才会一起变），而不是只把两侧涂黑。
+
+这是「手势」不是「语义标签」：三件事靠**运动方向**（下流 / 外扩 / 上长）区分，不靠三种不同的装饰。主侧只改强度和 0.7s 相位，不承载含义，所以不用学任何约定。
+
+---
+
+## 装进 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` 循环「标准 → 安静 → 关闭」。
+
+---
+
+## 调参
+
+视觉参数全部集中在 `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` 兜底）。新增工具时加一行即可。
+
+---
+
+## 怎么知道我在干什么
+
+全部读宿主**已有的语义属性**，不读哈希类名、不读别的插件的 DOM 结构：
+
+- `[data-tool="web_search"][data-state="running"]` —— 工具行与状态（`preparing / running / ok / error / stopped`）
+- `[data-chat-running]` —— 回合进行中的指示器（“正在深潜”）
+- `[data-streaming]` —— 正在流式输出
+
+工具行的收集不是每次全量查询：用 `MutationObserver` 增量收集、只保留尾部 48 个，变更用 48ms 定时器合并（不用 rAF——窗口被遮挡/无头环境里 rAF 会被节流，状态会卡住）。
+
+**切换会话时会静默 700ms**：切会话的瞬间，上一轮的工具行可能还挂在 DOM 上，历史里的失败行也会被当成新事件——不处理的话会看到几秒钟的假特效再自己消失。所以检测到 `data-conversation-session` 变化（或画布被换掉）时，会清空跟踪表、重置错误基线、强制回到空闲，等新会话挂载稳定再重新判断。
+
+---
+
+## 验证
+
+**看效果**：双击 `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` 暂停）。
+
+---
+
+## 已知限制 / 设计取舍
+
+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 写东西）。
+
+8. **不做设置项**：v1 没有「设置 → 通用」里的行，调参靠改 `client.js` 里的常量（改完刷新页面）。
+
+9. **性能**：常驻只有 4 个柔光 + 2 条光纤 + HUD；动画只碰 `transform` / `opacity`；不使用 `filter: blur()` 与 `backdrop-filter`；页面隐藏时 `animation-play-state: paused`；关掉（`Alt+B` 第三档）时 `display:none`，不再合成。
+
+---
+
+## 发布到 registry（给别人用）
+
+DSH 的「添加插件」支持三种来源：包名（走 npm registry）、Git 地址、本地目录。走 registry 时，安装的人只要填**包名**，并选下载源（npm 官方 / 国内镜像 / 自定义地址）。
+
+**1. 改成可发布的包名**
+
+包名同时出现在三个地方，必须一致，用脚本一次改完：
+
+```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/
+```
+
+**4. 别人安装**
+
+插件页 → 添加插件 → 填包名 → 源：
+- 发的公共 npm → 选「npm 官方」（刚发布的包国内镜像有几小时同步延迟，第一天建议先选官方）
+- 发的私有 registry → 选「自定义地址」填 registry URL（凭据写在使用者本机的 `~/.npmrc`）
+
+**注意**：改完包名后，旧的那份要卸载重装——DSH 是按包名认插件的，改名后旧的引用会失效。升级时改 `version` 再发一次即可，用户重装或等插件页提示。
+
+---
+
+## 文件
+
+```text
+conversation-aurora/
+├─ package.json        dsh.bundle.patch + dsh.client
+├─ cordis.patch.yml    插入一行
+├─ index.js            Host 半区（空）
+├─ client.js           Client 半区：全部实现 + 可调常量
+├─ locale/zh.json      插件页标题与描述
+├─ locale/en.json
+├─ icon.svg
+├─ preview.html        离线预览（直接加载 client.js）
+└─ README.md
+```