# 交互

[English](./interaction.md) | [中文](./interaction.zh-CN.md)


所有可触达的部分：浮动控制球、悬停暂停、点击详情、手发弹幕、热度条，以及小庆祝效果。

## 浮动控制球（拖球）

对话区上方有一个可拖动小球（默认右上）。它是常驻快捷控制：

- **拖动**重新定位——位置存 `localStorage`（`dsh-danmaku-ball-pos`），按浏览器持久。
- **点击**弹出快捷菜单：开关弹幕、暂停/继续、打开设置、发消息。
- **空闲**态显小圆点；**活跃**态（近期有触发）显更活泼的弹出。

弹幕完全关闭时拖球隐藏，重新开启时复现。

### 位置持久化与窗口尺寸变化

持久化的是**相对整个视口的比例**（`rx`/`ry`，0–1）加上推导它的像素值（`x`/`y`/`vw`/`vh`），锚点是 `window.innerWidth` / `innerHeight`。窗口尺寸变化时悬浮球按比例重定位：贴右边缘的球最大化后仍在右边缘。

换算遵循两条规则：

- **钳制优先于比例**：按比例算出的像素位置仍要过统一钳制函数，球始终可达。窗口缩小时允许偏离比例——保证球在屏内比保证比例更重要。
- **旧像素记录一次性迁移**：旧版本只写了 `x`/`y`（无 `rx`/`ry`）的记录，先按当前视口钳制一次，再立即换算成比例持久化。老用户无需先拖一次就能获得窗口跟随。视口尺寸为 0 或换算结果非有限时**不写**比例，避免下次被吸到角落。

拖曳、恢复、resize 三条路径统一走同一个钳制函数。

### 桌面端标题栏禁区

桌面端悬浮球不能停在窗口顶部的 Windows 标题栏条带内，条带高度取自 `--dsh-windows-titlebar-height`（Windows 为 40px）。拖曳、恢复、resize 三条路径都遵守这个下界，球不会藏进标题栏。

### 已知问题：弹出菜单越界

球跟随比例后可以贴近底/右边缘，而弹出菜单按 `top: 球y + 48` / `left: min(球x, innerWidth - 250)` 定位，未做视口适配。1440×900 下实测菜单越出视口（`top: 748`、`bottom: 1125`、`right: 1446`，视口 1440×900——下越 225px、右越 6px）。此问题已登记为已知问题，本版本有意不修。

## 悬停暂停

`hoverPause: true`（默认）时，悬停任意弹幕即冻结便于阅读，移开即恢复滚动。纯客户端，无服务往返，无卡顿。

**暂停的弹幕不会消失**（对齐 B 站）：只要仍处于暂停（悬停或详情锁定），就一直留在画面上；只有恢复滚动并滚出画面范围、切换会话或关闭 dsh 才会移除。

## 点击详情

点击弹幕打开详情浮层，显示文本与来源徽章。**只暂停被点击的那一条**，其余弹幕继续滚动；关闭详情后该条恢复（若仍悬停则保持悬停暂停）。

| 来源徽章 | 含义 |
|---|---|
| 📺 | 预设包 |
| 🤖 | LLM 生成 |
| 💬 | 用户手发 |

浮层内可**复制**文本、**屏蔽**内容（加入 `blockedWords`）、或从会话池**删除**（若是池条目）。

## 手发弹幕

`userSend: true`（默认）在快捷菜单（或拖球）启用文本输入。输入短消息发送——以 `source: 'user'` 飘过，加入会话池，可被历史回放与点赞加权。同样受 `styleMaxChars` / `blockedWords` 约束。

## 热度条

`showHeat: true`（默认）渲染细热度指示，反映当前会话繁忙度。Host 由近期触发计算热度（`/api/danmaku/heat`）：

| 事件 | 分值 |
|---|---|
| `tool_call` | 1.5 |
| `tool_error` | 2.5 |
| `user_message` | 2.0 |
| `reply_complete` | 2.0 |
| `task_done` | 4.0 |
| 其他 | 0.5 |

分值在可配 `window`（默认 30s）上归一为 0–1。高热度让覆盖层亮过空闲透明度；低热度让它暗下来。覆盖层随活动"呼吸"。

## 庆祝与环境效果

绑定事件的小可切花絮：

| 效果 | 配置 | 作用 |
|---|---|---|
| 入场欢迎 | `welcomeOnEnter`（默认 true） | 进入/切换会话时短促欢迎突发 |
| 任务完成刷屏 | `taskDoneRain`（默认 true） | 任务完成时彩纸式弹幕雨 |
| 工具出错吐槽 | `toolErrorSc`（默认 true） | 工具调用出错时吐槽突发 |
| 允许 emoji | `allowEmoji`（默认 true） | 弹幕内容可含 emoji |

## 调试来源徽章

`debugSource: true` 给每条上屏弹幕加来源 emoji 前缀（📺/🤖/💬），调参时一眼看出评论来源。正常使用时关。