角色头像朗读框 vioeveann/dsh-avatar-frame

角色头像框 · dsh-avatar-frame

DeepSeek Harness 的界面插件：在每轮 AI 回复左侧显示角色头像和可编辑的 ID，还能把回复朗读出来——用系统语音，或者调用你自己跑的本地 TTS 服务；也可以在设置里一键启动、停止那个服务进程。

这是 DeepSeek Harness 的头像框与朗读插件。它不附带语音模型，不附带参考音频，也不附带服务：想要克隆音色，你得自己跑一个 TTS 端点，再把插件指向它（插件可以替你拉起那个进程）。

头像与 ID 在每轮回复左侧

功能

形象

- 每轮 AI 回复左侧显示圆形头像，右边是可点击编辑的 ID，与「已完成，用时 …」那一行对齐；
- 上传图片 → 拖动/缩放裁切 → 应用到所有轮次；
- ID 字号可调（10–20px）；
- 预设：最多 8 套「头像 + ID + 字号」，一键切换；预设图压缩成 JPEG，不占空间。

朗读

- 点 ID 右侧的小喇叭，朗读这一条回复的正文（只读最终回答，不读思考过程和折叠的工具步骤）；
- 两种引擎：系统语音（开箱即用）或你自己的本地服务；
- 播放控制条：朗读时接在小喇叭右侧，可暂停/继续、上一句/下一句、五档语速（0.95× / 1.00× / 1.05× / 1.10× / 1.15×）、停止；
- 语气三档：平稳 / 自然 / 活泼，随请求发给你的服务；
- 试听：不用回到聊天，在设置里直接试一句；
- 失败提示：某句合成失败时，小喇叭旁出现红点，悬停可看原因；
- 长回复按句切分、提前两段预生成，句间不卡顿。

朗读时小喇叭右侧的控制条

其他

- 设置 → 角色头像：头像、ID、字号、预设、朗读、引擎、语气、语速、服务地址、试听、诊断都在这页；
- 语音服务进程：一键启动/停止你自己配置的服务进程，可勾选「随 DSH 启动」（设置页与插件详情页都能操作）；
- 诊断信息：服务状态与模型名、上一句合成耗时、播放进度、最近一次错误；
- 中文 / English 双语文案；
- 所有数据只在本机 localStorage，不上传、不联网（除非你把服务地址指向远程）。

安装

从本地目录安装

1. 把本仓库放到任意目录；
2. 打开 DeepSeek Harness → 插件管理 → 安装外部 bundle，指向这个目录（含 package.json 与 cordis.patch.yml）；
3. 打开一次界面；插件的前端模块在页面加载时注入，必要时刷新（Ctrl+R）；
4. 「启动服务」那一块跑在宿主端，首次安装、以及每次升级这个插件后，需要重启一次 DSH 才生效。

从 GitHub 安装

git clone https://github.com/vioeveann/dsh-avatar-frame.git

然后同上，把插件管理指向克隆下来的目录。

插件详情页

使用

1. 点任意一轮回复左侧的头像，或「已完成」那一行的 ID，打开设置面板；
2. 点「选择头像图片」上传图片，在裁切框里拖动、滚轮缩放，确定；
3. 在面板顶部的输入框里写 ID（角色名、代号都行），字号按需调；
4. 想留一套搭配就点「保存预设」，最多 8 套；
5. 需要朗读就把「朗读」打开，然后点回复旁边的小喇叭。

设置面板

语音

插件本身不下载模型、不附带参考音频、不启动任何服务。它只做两件事：用系统语音读，或者调用你给的 HTTP 服务。

默认地址 http://127.0.0.1:8123，可在面板、插件详情页或设置页修改，旁边会显示「已连接 / 未连接」的实时状态。服务不可用时会自动退回系统语音。

状态点每 8 秒自动重试一次，所以先启动服务、再看那一点变绿即可，不用刷新界面。

先用一个示例跑通

仓库里带了一个最小实现，用微软 Edge 的在线语音，够你确认整条链路：

pip install edge-tts
python examples/simple_tts.py # 监听 127.0.0.1:8123

然后把插件里的服务地址填成 http://127.0.0.1:8123，点小喇叭。想要自己的音色，把示例里的 synthesize() 换成你的引擎即可。

一键启动服务（可选）

插件的宿主端可以替你启动那个服务进程，入口有两处、内容一致：设置 → 角色头像 → 语音服务，以及插件详情页的同名区块。

- 「启动服务 / 停止服务」：执行你填的那条命令；
- 「随 DSH 启动」：DSH 启动时自动把它拉起来（不是开机自启）；
- 「启动配置」里填：启动命令、工作目录、环境变量（每行 KEY=VALUE）。

例如：

启动命令 "F:\tts\python.exe" server.py 工作目录 F:\tts 环境变量 HF_HOME=F:\tts\hf-cache

想直接用仓库里的示例服务试这个功能：

启动命令 python examples/simple_tts.py 工作目录 <本仓库所在目录>

几点要说清楚：

- 命令是你自己填的，插件不附带任何服务；它只是替你执行、托管这个子进程。
- 进程的生命周期跟随 DSH：DSH 退出时它会被一起收掉；「随 DSH 启动」只在 DSH 启动时执行一次。
- 端口上已经有服务在跑时（比如你手动开的），插件会显示「端口上已有服务（非本插件启动）」，不会重复启动。
- 宿主端代码在 DSH 启动时加载，所以安装或升级插件后要重启一次 DSH，这一块才可用；界面会提示「宿主端未加载」。

接口契约

完整说明见 docs/tts-contract.md。核心是三个请求：

GET /health
-> 200 {"ok": true, "model": "任意字符串"}

POST /tts
{"text": "要读的文本", "speed": 1.05, "tone": "normal"} 返回 200，Content-Type 为音频（audio/wav、audio/mpeg 均可），body 为音频数据

另外需要允许 CORS（Access-Control-Allow-Origin: *，并响应 OPTIONS 预检），因为插件在网页里请求它。

tone 是建议值，服务端不认识就忽略；speed 范围 0.7–1.3。

设置与数据

入口：设置 → 角色头像。所有设置都存在本机浏览器的 localStorage：

| 键 | 内容 |
| dsh-avatar-frame/image/v1 | 头像图片（data URL） |
| dsh-avatar-frame/id/v1 | ID 文本 |
| dsh-avatar-frame/size/v1 | ID 字号 |
| dsh-avatar-frame/presets/v1 | 预设列表 |
| dsh-avatar-frame/speech/v1 | 朗读开关 |
| dsh-avatar-frame/engine/v1 | 引擎（system / clone） |
| dsh-avatar-frame/endpoint/v1 | 服务地址 |
| dsh-avatar-frame/rate/v1 / tone/v1 | 语速 / 语气 |

同一个浏览器的多个窗口之间会同步。换电脑、清缓存会丢，插件没有云同步。

设置 → 角色头像

已知限制

- 只支持 Web 平台的 DeepSeek Harness；
- 插件接管了「已完成，用时 …」这一行的渲染，用来把头像放进左侧留白。停用或卸载插件后请刷新一次界面，否则这一行会显示「未知 surface 事件：turn-process」；
- 头像只在一轮结束后出现，流式输出过程中没有——那需要接管整个回答渲染器，代价太大；
- 与同样接管 turn-process 的其他插件会冲突；
- 朗读是按句切分的，句子之间靠播放器衔接；如果某一句失败，会跳过该句继续读后面的；
- 「一键启动服务」的宿主端代码在 DSH 启动时加载，升级插件后要重启一次 DSH；
- 该功能会按你填写的命令执行本机程序，请只填你自己的服务；路由走 DSH 本机同源请求，没有额外鉴权，别把 DSH 暴露到公网。

目录结构

.
├── package.json # bundle 元信息与前端入口声明 ├── cordis.patch.yml # 插件装配 ├── index.js # 宿主端：语音服务的启动/停止与配置（同源路由） ├── client.js # 前端：界面、播放、设置页（单文件、无构建） ├── locale/ # zh / en 文案与插件描述 ├── icon.svg ├── README.md ├── CHANGELOG.md ├── LICENSE ├── docs/ # 接口契约、截图、发布步骤 └── examples/simple_tts.py

client.js 是单文件、无构建、无依赖（除 React 由宿主提供）：改完刷新界面即可生效。
index.js 只在 DSH 启动时加载：改动它需要重启 DSH。

发布新版本的流程见 docs/releasing.md。

许可

代码以 MIT 发布。

插件不包含任何语音模型、参考音频或音色文件。你用到的模型、参考音频、第三方语音服务的许可与版权，需要你自行确认与遵守；请勿把他人声音素材随本插件分发。