# dsh-oled-guard 使用指南

适用于 DSH 桌面版 / Web GUI。插件是纯客户端实现，不改 DSH 源码，也不联网。

## 1. 它做什么

闲置 4 秒后，自动隐藏以下静态像素：

- 底部输入区（composer）
- 右下角鲸鱼组件
- 其他固定/粘性 UI：侧边栏、顶栏、用量环、徽章、通知、浮层按钮等

鼠标移动、键盘输入、点击输入框时立即恢复。新建会话时居中的输入框不会隐藏。

## 2. 默认热键

| 热键 | 作用 |
|---|---|
| `Alt+Shift+O` | 总开关：开启/关闭全部防烧屏 |
| `Alt+Shift+P` | 只开关“固定浮层保护”（输入框/鲸鱼不受影响） |
| `Alt+Shift+K` | 打开设置面板 |

热键全部可改，见第 4 节。

## 3. 打开设置面板

按 `Alt+Shift+K`，屏幕中央会出现「防烧屏设置」：

- **启用防烧屏**：总开关
- **隐藏固定浮层**：只控制侧边栏/顶栏/徽章等
- 三个快捷键输入框
- **保存**：写入本机并立即生效
- **恢复默认**：把输入框填回默认值（仍需点保存）
- **关闭**：关闭面板（也可以按 `Esc`）

## 4. 修改快捷键

1. 按 `Alt+Shift+K` 打开设置
2. 点击要修改的快捷键输入框
3. 直接按下新组合键（例如 `Ctrl+Alt+O`）
4. 点 **保存**

规则：

- 字母/数字键必须带 `Ctrl`、`Alt`、`Shift` 或 `Meta` 修饰
- `F1`–`F12` 可以单独使用
- 三个快捷键不能重复
- 保存后立即生效，状态保存在本机 `localStorage`

## 5. 固定浮层的识别规则

插件会扫描页面里 `position: fixed` 或 `position: sticky` 的元素，满足以下条件才会隐藏：

- 可见
- 面积小于视口 60%
- 不包含当前焦点
- 不是菜单/对话框/提示框
- 不在输入区或鲸鱼内部
- 没有 `data-dsh-oled-keep` 属性

**不会隐藏**：全屏背景、壁纸、遮罩、菜单、对话框、日期选择器等弹层。

## 6. 自定义哪些元素要隐藏

如果某个元素不是 `fixed/sticky`，但你也想让它淡出：

```js
// 强制包含
localStorage.setItem("dsh-oled-guard-extra", JSON.stringify([".my-sidebar", "#my-badge"]));
// 强制排除
localStorage.setItem("dsh-oled-guard-exclude", JSON.stringify([".keep-visible"]));
```

改完刷新 DSH 窗口生效。

也可以直接给元素加属性保护：

```html
<div data-dsh-oled-keep>这个区域永远不隐藏</div>
```

## 7. 忘记自定义热键怎么办

任选一种：

1. 在 DSH 开发者工具控制台执行：

```js
window.__dshOledGuard.openSettings()
```

2. 清掉本机热键配置后刷新窗口：

```js
localStorage.removeItem("dsh-oled-guard-hotkeys");
location.reload();
```

3. 清掉全部插件配置：

```js
localStorage.removeItem("dsh-oled-guard");
localStorage.removeItem("dsh-oled-guard-overlays");
localStorage.removeItem("dsh-oled-guard-hotkeys");
location.reload();
```

## 8. 常见问题

**侧边栏/顶栏没有淡出？**

它们可能不是 `fixed/sticky`。按第 6 节用 `dsh-oled-guard-extra` 指定选择器；或把元素特征告诉我。

**侧边栏也被藏了，不习惯？**

按 `Alt+Shift+P` 关闭浮层保护；或在 `dsh-oled-guard-exclude` 里排除对应选择器。

**热键没反应？**

- 确认没有和 DSH、输入法、显卡驱动等全局快捷键冲突
- 确认字母键带了修饰键
- 打开设置面板重新录制一次
- 打开控制台看是否有 `[dsh-oled-guard]` 日志

**设置面板打不开？**

用第 7 节的 `window.__dshOledGuard.openSettings()`。

**DSH 更新后失效？**

插件采用 fail-open：找不到 DOM 钩子时不会破坏界面，只是不隐藏。等待插件更新即可。

## 9. 兼容性和安全

- 纯本地，无网络请求、无遥测
- 只改 CSS 和客户端 DOM class，不修改 DSH 源码
- 状态只写本机 `localStorage`
- 插件异常时自动放行，不会卡住界面