dsh-avatar-frame

dsh plugin --profile web add dsh-avatar-frame

角色头像框 · dsh-avatar-frame

[中文](#中文) · [English](#english)

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

插件不附带任何语音模型、参考音频或服务；音色由你自己运行的服务提供，接口见 [docs/tts-contract.md](docs/tts-contract.md)。

---

中文

功能

形象

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

朗读

• 点 ID 右侧的小喇叭，朗读这一条回复的正文（只读最终回答，不读思考过程和折叠的工具步骤）；
• 可打开「自动朗读新回复」，新一轮回答结束后自动念（历史轮次不会补念）；
• 两种引擎：系统语音（开箱即用，可选音色，按回复语言自动选中/英文音色、优先神经网络音色）或你自己的本地服务；
• 播放控制条：朗读时接在小喇叭右侧，可暂停/继续、上一句/下一句、五档语速（0.95× / 1.00× / 1.05× / 1.10× / 1.15×）、停止——两种引擎都支持；
• 音量滑块（0–100%，默认 50%）；
• 语气三档：平稳 / 自然 / 活泼，随请求发给你的服务；
• 试听：选「本地服务」时，设置页 / 插件详情页 / 头像弹窗里都有「试听一句」；选「系统语音」时，音色选择那一行自带试听；
• 失败提示：某句合成失败时，小喇叭旁出现红点，悬停可看原因；试听失败时按钮旁会直接显示简短原因；
• 长回复按句切分、提前两段预生成，句间不卡顿。

其他

• 设置 → 角色头像：头像、ID、字号、预设、朗读、引擎、语气、语速、服务地址、试听、诊断都在这页；
• 语音服务进程：一键启动 / 停止 / 重启你自己配置的服务进程，可勾选「DSH 启动时拉起语音服务」（设置页与插件详情页内容完全一致）；切到「系统语音」时整块自动隐藏，进程仍在跑或开着自启时例外；
• 状态跟着过程走：点启动后先显示「检测中 · 已等待 N 秒（模型加载通常 10–30 秒）」，连上即变「已连接」；超过 25 秒仍未连上才显示「未连接」，并给出简短原因（超时 / 连不上 / 服务返回 HTTP 码）；
• 诊断信息：服务状态与模型名、上一句合成耗时、播放进度、最近一次错误；
• 界面语言可切换：中文 / English 两个按钮，放在插件详情页、设置 → 角色头像、点头像弹出的面板三处；选择只记在本机，刷新/重启后保持；
• 所有数据只在本机 localStorage，不上传、不联网（除非你把服务地址指向远程）。

安装

1. 打开 DeepSeek Harness → 插件 → 添加插件 → 输入本插件的 包名（dsh-avatar-frame，从 npm 拉取，最省事）、GitHub 仓库地址（https://github.com/vioeveann/dsh-avatar-frame）或本地目录路径；

2. 重启一次 DSH（必须）。安装、升级后都算：插件的前端模块和服务启动都在 DSH 启动时加载，只刷新页面往往不够，会出现「装上了、显示运行中，但聊天区没变化」。

包名已发布到 npm：dsh-avatar-frame（国内可走 registry.npmmirror.com 镜像）。

装不上怎么办

• 用 GitHub 地址安装走的是 git，机器连不上 github.com 就会报 ERR_PNPM_GIT_RESOLVE_FAILED。先验证：git ls-remote https://github.com/vioeveann/dsh-avatar-frame；不通就配代理，或在 hosts 里给 github.com 指定一个可用 IP；
• 完全绕开 git 和 npm：直接下载 v0.11.5 源码 zip → 解压 → 添加插件时填解压后的本地目录（也可以走 Code → Download ZIP）；
• 用包名安装若提示找不到，先 npm config get registry 确认走的是官方源。

使用

1. 点任意一轮回复左侧的头像，或「已完成」那一行的 ID，打开设置面板；

2. 点「选择头像图片」上传图片，在裁切框里拖动、滚轮缩放，确定；

3. 在面板顶部的输入框里写 ID（角色名、代号都行），字号按需调；

4. 想留一套搭配就点「保存预设」，最多 8 套；

5. 需要朗读就把「朗读」打开，然后点回复旁边的小喇叭。

语音

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

默认地址 http://127.0.0.1:8123，可在面板、插件详情页或设置页修改，旁边会显示「已连接 / 未连接」的实时状态。服务不可用时会自动退回系统语音；状态点在离线时每 2.5 秒重试一次，连上后每 30 秒静默保活一次，中途挂掉也会自己变红。

系统语音怎么更好听

「系统语音」用的是浏览器能看到的系统音色，列表由系统和你用的客户端决定：

• Windows 10：基本只有老的 SAPI 音色（如「慧慧」），机械感明显，这是系统本身的限制；
• Windows 11：可以安装微软的自然音色（晓晓、云希等）。路径是 设置 → 时间和语言 → 语音 → 添加语音（部分版本在「讲述人」里有自然语音的下载项）。装好后重启一次 DSH，音色下拉框里会出现名字带 Natural 的项；
• 下拉框会自动把自然音色排在最前，不用手动找。

如果下拉框里只有老音色，说明系统里没有、或者当前客户端拿不到——这时候更实际的办法是用「本地服务」：要么跑下面那个示例（微软在线音色），要么接你自己训练的模型。

先用一个示例跑通：仓库里带了一个最小实现，用微软 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](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 均可）

需要允许 CORS（Access-Control-Allow-Origin: * 并响应 OPTIONS 预检）。tone 是建议值，不认识就忽略；speed 范围 0.7–1.3。

试听没声音时：插件会先直连你填的地址，1.5 秒内没有响应就自动改由 DSH 宿主进程转发（日志在 ~/.dsh/storages/dsh-avatar-frame/debug.log）。设置页的试听按钮旁会显示「试听中 n/m」或失败原因。

启动失败时先看这一条：设置页「启动配置」下面会显示进程退出前的输出。如果看到

PermissionError: [WinError 10013] 以一种访问权限不允许的方式做了一个访问套接字的尝试

说明端口被 Windows 的保留端口段占住了（Hyper-V / WinNAT 会在重启后划走若干段，用 netsh interface ipv4 show excludedportrange protocol=tcp 查看）。换一个不在保留段里的端口（例如 18124），服务端和插件地址一起改即可。

设置与数据

入口：设置 → 角色头像。所有设置都存在本机浏览器的 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 · 语速 / 语气

dsh-avatar-frame/lang/v1 · 界面语言（zh / en，不写则跟随 DSH）

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

已知限制

• 只支持 Web 平台的 DeepSeek Harness；
• 插件接管了「已完成，用时 …」这一行的渲染。停用或卸载插件后请刷新一次界面，否则这一行会显示「未知 surface 事件：turn-process」；
• 头像只在一轮结束后出现，流式输出过程中没有——那需要接管整个回答渲染器，代价太大；
• 与同样接管 turn-process 的其他插件会冲突；
• 朗读按句切分，某一句失败会跳过继续读；
• 插件的前端模块与「一键启动服务」的宿主端代码都在 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 由宿主提供），改完刷新即可；

…(truncated)