前言¶
在 DeepSeek Harness (dsh) Web GUI 中，聊天界面默认没有头像显示。默认情况下，用户只能看到消息气泡，缺少视觉标识。对于习惯在会话中快速识别身份的开发者来说，这会增加阅读负担。dsh-chat-avatars 插件通过在用户消息右侧、AI 消息左侧添加头像，解决了这一问题。
插件定位¶
dsh-chat-avatars 是一个为 DeepSeek Harness (dsh) Web GUI 提供头像功能的插件。由维护者 BlackRasion 开发，当前版本 0.1.3，采用 MIT 许可证。插件通过本地浏览器存储管理头像与设置，不依赖远程服务。
核心功能¶
用户/AI 头像显示¶
默认在用户消息右侧、AI 消息左侧显示头像。支持调整头像尺寸（24–60px）、选择圆形或圆角形状、分别控制两侧头像的显示与隐藏。
全局默认 + 工作区覆盖¶
支持设置全局默认头像，同时可以为每个工作区单独覆盖头像。未设置工作区头像时，会继承全局默认值。
上传前交互裁剪¶
上传头像时支持交互式裁剪。支持的图片格式包括 PNG/JPEG/WebP，文件大小限制 2 MB。提供拖拽、缩放和键盘操作，预览效果即为最终输出。静态头像输出为 256×256。
动图头像¶
支持 GIF/APNG/动图 WebP（≤6 MB）。插件在本地解码动图，自适应采样 8–96 帧，并烘焙为雪碧图，使用 CSS steps() 播放。开启 prefers-reduced-motion 时会冻结首帧。
大图预览与更换¶
在聊天中单击头像，会打开居中大图预览。预览界面中可以直接更换头像。
拍一拍效果¶
双击头像触发纯本地效果，包括行抖动、气泡提示和 WebAudio 合成音效。效果不写会话事件、不联网、不通知对方。支持配置用户侧/AI 侧的拍一拍文案组（最多 8 条），每次随机选择且避免连续重复。
数据管理¶
支持导出/导入 JSON 格式的设置与头像数据。提供清除全部数据功能和清理未使用的工作区头像功能。多标签页会自动同步数据。
安全降级¶
插件会检测 dsh 版本是否在支持区间（>=0.2.1-rc.2 <0.3.0）以及宿主契约是否匹配。不匹配时会自动暂停并回退到原生界面，不阻断 GUI 启动。
安装与启用¶
方式 1：GitHub Release tarball（当前推荐）¶
- 打开 Releases 页面，下载最新
.tgz文件（当前为dsh-chat-avatars-0.1.3.tgz）。 - 在终端执行安装命令（把路径和 profile 换成你的实际值）：
dsh plugin --profile <profile> add /path/to/dsh-chat-avatars-0.1.3.tgz
例如 dsh 的 Web profile 常用 --profile web。
3. 刷新 dsh Web GUI；若未立即生效，重启 dsh 后再打开。
安装/启用会写入你的 dsh profile，属于本机配置变更；请确认路径与来源可信后再执行。
方式 2：npm（发布准备中）¶
包名 dsh-chat-avatars。npm 发布完成后可直接：
dsh plugin --profile <profile> add dsh-chat-avatars
当前请先使用上面的 tarball 方式。
使用方法¶
- 打开 设置 → 聊天头像（Account menu → Settings → Chat avatars）。
- 在 Appearance 中启用头像、调整尺寸/形状/显示范围。
- 在 Global defaults 中上传全局默认头像；需要时在 Workspace overrides 里为单个工作区覆盖。
- 在聊天中：
- 单击头像 → 大图预览（可在预览内更换头像）；
- 双击头像 → 拍一拍（气泡 + 音效）；
- 连续双击会重新弹出气泡（视觉冷却 300ms）；音效 900ms 内只响一次。 - 动图头像支持 GIF/APNG/动图 WebP；上传后会按裁剪区域逐帧生成。开启
prefers-reduced-motion时冻结首帧。
拍一拍的文案组（可添加多条，每次随机）、音效开关与音量在设置页 Interaction 卡片中配置。
升级与卸载¶
# 升级：下载新的 release tarball 后再次 add 即可；设置与头像保留
dsh plugin --profile <profile> add /path/to/dsh-chat-avatars-<new>.tgz
# 卸载
dsh plugin --profile <profile> remove dsh-chat-avatars
兼容性与注意事项¶
- 需要 dsh 版本
>=0.2.1-rc.2 <0.3.0。超出范围时插件会自动暂停并回退到原生界面。 - 零运行时依赖，不需要
npm install；不修改 dsh 源码，不写document.body、不写会话事件、不联网。 - 动图播放依赖浏览器
ImageDecoder（需要http://127.0.0.1或 https 等安全上下文）；不可用时只拒绝动图，静态头像仍可用。 - 窄屏（<520px）下头像会按设计隐藏。
- 数据只保存在当前浏览器的
localStorage（key：dsh.chat-avatars.v1），不上传、不联网、不读取消息正文。 - 卸载插件不会自动删除 localStorage；如需彻底清理，请在设置页使用「清除全部数据」，或在浏览器 DevTools 删除对应 key。
适用场景¶
适合需要在 dsh Web GUI 中为用户和 AI 添加头像标识的开发者。适合希望在工作区级别自定义头像、使用动图头像、或需要本地化拍一拍效果的场景。
总结¶
dsh-chat-avatars 通过在聊天界面添加用户/AI 头像、支持全局默认与工作区覆盖、交互式裁剪、动图头像、大图预览与拍一拍等功能，提升了 dsh Web GUI 的视觉体验。插件采用零运行时依赖、纯本地数据存储的设计，数据安全可控。当前版本 0.1.3，支持 dsh 0.2.1-rc.2 至 0.3.0 之间的版本。
- 插件目录页：https://www.skillhub.cn/plugins/BlackRasion/dsh-chat-avatars
- GitHub 仓库：https://github.com/BlackRasion/dsh-chat-avatars
