dsh-plugin-internet-meme

Readme

# DeepSeek Harness：互联网热梗字幕插件

给 [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) Web 页面添加一层轻量的“热梗弹幕”字幕：Agent 思考、调用工具、工具返回和本轮结束时，右侧会显示向上漂移的短句提示。

这是可被 DeepSeek Harness profile 安装的 **Bundle**，不是 Harness 源码内部包，也不是 Vite 演示。插件只增强浏览器界面，不会改变模型对话、工具调用或会话记录。

## 适合谁使用

- 想在 DSH Web 中更直观地感知 Agent 执行节奏的用户。
- 想自定义字幕主题、颜色、密度与文案，但不希望把内容写进会话的用户。
- 希望提示音只在本地播放，并且不上传会话文本的用户。

## 功能一览

| 功能 | 说明 |
| --- | --- |
| 事件字幕 | 覆盖思考、工具调用、工具结果和本轮结束五类生命周期事件。 |
| 本地设置 | 在 DSH 设置中提供独立的“热梗字幕”页面，刷新后保留在当前浏览器。 |
| 可定制外观 | 四套主题、自定义文案、密度、字号、配色、图标、透明度、模糊和同屏上限。 |
| 预览链路 | “预览弹幕”使用 Host → SSE → 浏览器的真实渲染路径，并提供成功或失败反馈。 |
| 本地声音 | 可选合成提示音和固定状态朗读；默认关闭，不下载外部音频。 |
| 隐私边界 | 不读取或传输回答正文、推理内容、工具参数和工具结果正文。 |

## 快速安装

### 前提条件

- 已能在本机正常运行 DeepSeek Harness Web profile。
- 已安装 Git、Node.js、pnpm 和 `dsh` CLI。

### 方式一：通过 DSH 直接安装

这是普通用户推荐的安装方式，无需手动克隆源码：

```powershell
dsh plugin --profile web add github:zhaoxuejie/dsh-plugin-internet-meme#v0.4.4
dsh --profile web --dump-config
```

该命令会将 GitHub 上的 `v0.4.4` 标签作为 DSH Web profile 的插件依赖安装。配置输出中应同时出现 `# == dsh-plugin-internet-meme` 与 `internet-meme-subtitles`；完成后，请自行重启对应的 DSH Web profile。

首次从 Git 安装时，pnpm 可能提示需要允许本包执行 `prepare` 构建脚本。请按 CLI 对当前 profile 给出的提示授权构建，再重新执行上述安装命令。

### 方式二：克隆源码后安装

适合希望阅读源码、修改主题文案或参与开发的用户。在任意本地工作目录执行：

```powershell
git clone https://github.com/zhaoxuejie/dsh-plugin-internet-meme.git
cd dsh-plugin-internet-meme
pnpm install
pnpm run build
dsh plugin --profile web add link:.
dsh --profile web --dump-config
```

配置输出中应同时出现 `# == dsh-plugin-internet-meme` 与 `internet-meme-subtitles`。完成安装后，请自行重启对应的 DSH Web profile。

`link:.` 使 profile 直接使用当前本地目录，适合从源码安装和后续更新；请保留这个项目目录。若你更希望安装一份独立副本，也可以将该命令改为 `dsh plugin --profile web add file:.`。

### 启用与试听

![DSH 中的热梗字幕配置页面](docs/settings.png)

1. 打开或刷新 DSH Web 页面，进入“设置”。
2. 在左侧选择“热梗字幕”。
3. 保持“显示字幕”开启，点击“预览弹幕”确认字幕出现。
4. 需要声音时，开启“提示音”并调高音量；再次点击“预览弹幕”会立即试听一次提示音。

提示音默认关闭。页面失焦、系统开启“减少动态效果”、字幕关闭或音量为 0 时不会播放。

## 更新

通过 DSH 直接安装时，指定目标版本并重新安装：

```powershell
dsh plugin --profile web add github:zhaoxuejie/dsh-plugin-internet-meme#v0.4.4
```

从本仓库克隆源码安装时，更新流程如下：

```powershell
git pull
pnpm install
pnpm run build
```

之后请自行重启 DSH Web profile。使用 `link:.` 安装时无需重复执行 `dsh plugin add`；使用 `file:.` 安装时，请重新执行一次安装命令。

## 常见问题

### 设置里没有“热梗字幕”

执行 `dsh --profile web --dump-config`，确认输出包含插件名和 `internet-meme-subtitles`。若没有，请在项目根目录重新运行安装命令，并在完成后重启对应 profile。

### 点击预览没有字幕

确认页面已刷新、字幕开关已开启，并查看预览按钮下方的状态说明。预览会检查 HTTP 请求、SSE 事件和可见字幕三个环节；若提示超时，重启 profile 后重试。

### 点击预览没有声音

确认“提示音”已经开启、音量大于 0、浏览器标签页处于前台，并检查系统输出设备和浏览器静音状态。提示音是浏览器本地合成音，不依赖网络资源。

```text
src/index.ts       # Host 事件白名单 + 静态脚本/SSE 路由
src/bridge.ts      # 独立浏览器字幕层，不依赖 dsh.client 解析
cordis.patch.yml   # dsh.bundle 激活层
package.json       # 标准 dsh.bundle 外部包声明
```

## 开发环境安装

如果你已克隆本仓库并希望从源码开发，可在本插件根目录构建后安装到 Web profile：

```powershell
pnpm install
pnpm run build
dsh plugin --profile web add link:.
dsh --profile web --dump-config
```

`--dump-config` 输出中应出现 `# == dsh-plugin-internet-meme` 与 `internet-meme-subtitles`。安装或更新 Bundle 后需自行重启 Web profile。

从 Git 安装时，`prepare` 会构建 `lib/`；pnpm 10+ 可能要求在该 profile 的 `pnpm-workspace.yaml` 为本包显式设置 `allowBuilds: true`，然后重新执行 add。

插件通过标准 Bundle 的 Host 入口观察 `turn/start`、`step/start`、`tool/call`、`tool/result` 和 `turn/end`，仅把事件种类、时间、工具名、调用 ID、错误标志经 SSE 投影到浏览器。浏览器脚本独立渲染侧边字幕，因此能兼容无法从 profile 解析 `dsh.client` 的 DSH 版本。它不会改写会话、不会注册模型 Provider/Tool，也不读取回答正文、思维链、工具参数或工具结果正文。

## 使用

打开 DSH Web 页面后，页面不会再有控制卡片。发送一条消息或让 Agent 调用工具时，右侧字幕会从底部向上漂移，在顶部逐渐淡出和模糊。字幕使用三条独立轨道和发射间隔调度，避免多条信息堆叠遮挡；文案直接显示为短句，不含方括号或“弹幕”前缀。

在 DSH 的“设置”左侧导航中会新增“热梗字幕”。点击它后，右侧会单独显示本插件的设置项，不会混在通用设置或插件配置列表中：

- 显示开关、弹幕密度、最大同屏条数、字号、透明度、顶部淡出模糊与诊断开关。
- 预览弹幕：不调用模型，走 Host → SSE → 浏览器渲染链路；只有 HTTP 请求成功、收到对应预览事件且字幕可见时才提示成功。请求失败或 12 秒内未完成验证时明确提示，可重新尝试。
- 按事件配色与图标：思考、工具调用、工具结果和完成状态各有独立的柔和颜色和图标；也可切换为克制单色或关闭图标。
- 四套内置主题：经典热梗、职场摸鱼、二次元燃系、赛博终端。
- 自定义文案池：每行一条，可使用 `{tool}` 自动代入工具名；最多 100 条、每条 200 字符。失败及未知工具结果使用固定提示，避免自定义文案误报成功。

这些设置只保存在当前浏览器的 `localStorage`，不写入 DSH 会话，也不进入模型消息流。读取时会校验类型和取值范围；存储写入失败时保留本页效果并提示无法保存。透明度拖动即时生效，结束拖动后保存，不重建正在操作的控件。

工具失败显示独立警示图标与文案，结果状态未知时使用中性提示，内置的回合结束文案不承诺任务成功。不同工具或不同调用 ID 不合并；队列过载时优先保留失败与结束事件，但仍受 8 项容量上限约束。

提示音默认关闭。开启后使用浏览器本地合成的短音提示事件，不下载或播放外部音频；页面失焦、关闭字幕或系统启用“减少动态效果”时不播放。可选“完成与失败时朗读”只播报固定状态短语，不朗读热梗、工具名、会话回答或工具内容；连续事件最少间隔 2.2 秒。

## 当前边界

- 有：纯 UI 字幕、三轨防重叠调度、右侧上浮淡出动画、事件配色和图标、原生设置内配置、三档密度/字号、最大同屏数、透明度/模糊度、四套主题、自定义文案池、诊断开关、工具结果名称回填、过期自动清理、历史事件不回放。
- 没有：BGM 播放、联网热梗生成、将字幕写回会话、读取任何回答/推理/参数正文。

后续 BGM 应作为单独的、用户明确开启的客户端音频模块加入，不能默认自动播放。

## 开发验证

```powershell
pnpm run test
pnpm run typecheck:client
git diff --check
```

- `test` 会先构建，再用 Node.js 内置测试运行器验证异常设置、队列合并/容量、预览协议及 Host 事件字段白名单；无需额外测试依赖。
- `typecheck:client` 对浏览器入口及其导入模块执行严格类型检查，不代表 Host API 兼容性验证。
- 浏览器验收：设置 → 热梗字幕 → 预览弹幕；检查成功提示、字幕可见、滑块可连续拖动、切回原生设置正常。错误配置、存储拒绝、HTTP 错误、无对应 SSE 事件等分支也应覆盖。
- 必须同时更新 Host 与浏览器构建并重启 Web profile；旧 Host 不回传预览标识时，新浏览器脚本会提示验证超时。
- 当前真实事件仍全局广播，会话隔离、完整调度优化与窄屏宿主布局适配留待后续批次。带标识的预览事件仅由发起请求的新版页面显示，但 Host 广播本身尚未隔离。

开发前基线：Git tag `baseline-v0.4.3`。可通过 `git show baseline-v0.4.3:src/bridge.ts` 查看基线代码，或使用 `git diff baseline-v0.4.3 -- src` 检查后续修改。