前言¶
在 DeepSeek Harness（DSH）里长时间调试智能体时，默认会话区往往是「一列消息、无头像、无左右区分」，读长回复时很难一眼分清哪句是用户、哪句是助手。社区里壁纸引擎插件（dsh-plugin-wallpaper-engine）曾带「自定义会话头像」扩展，但会连同壁纸、字体、特效等一并装上。若你只想把会话改成类似好友聊天的布局——双方头像、消息左右分列、助手最终回复带气泡——维护者 lerwa2025-a11y 的 dsh-conversation-avatar（GitHub：https://github.com/lerwa2025-a11y/dsh-conversation-avatar）从该扩展移植而来，只保留头像与气泡相关能力。下面介绍它做什么、怎么装、怎么用，以及和壁纸引擎同时启用时的注意点。
这是什么¶
dsh-conversation-avatar 是 DSH 的客户端类插件（npm 包名 dsh-conversation-avatar，当前版本 1.0.0，MIT 协议）。它在会话里为 user / steering 与 assistant-step 等消息行注入头像，用户侧在右、助手侧在左；可选地为每轮 AI 最终回复 套气泡框，思考过程与工具区不套框。装饰层逻辑源自壁纸引擎的 avatar-layer.js，类名统一为 cav-*，数据与设置独立，避免与壁纸引擎冲突。原壁纸引擎作者 elysia395（https://github.com/elysia395/dsh-wallpaper-engine）在 README 中致谢。
插件以当前 DSH 进程权限运行；安装前建议自行查看仓库源码与 LICENSE，社区目录页：https://www.skillhub.cn/plugins/lerwa2025-a11y/dsh-conversation-avatar（与 DeepSeek / 幻方无官方从属，属社区生态）。
核心功能¶
会话布局与头像¶
- 每个消息行配头像：user / steering 在右侧，assistant-step 在左侧；展开「已完成，用时…」过程区时，区内各行同样各配一张。
- 头像跟随滚动（v1.0，默认开）：长回复向下滚动时，头像贴着滚动区顶部跟随；整段消息滚出视口后随行消失。关闭后头像只固定在消息开头，随内容一起滚走，不再吸顶。
- 吸顶下移：翻页时头像下移 N 个身位（默认 2），用于避开主题插件云母状态栏遮挡；关闭「头像跟随画面」后此项置灰不可调。
- 内置默认头像：未上传图片时用 SVG（我方人像、助手四角星），颜色跟随主题文字色。
AI 回复气泡框¶
- 仅包裹每轮最终回复；思考区、工具调用等过程内容不套框，可单独开关。
- 可调背景色、边框色（留空跟随主题）、圆角、不透明度、磨砂（0–30 px，默认 10；只模糊气泡背后壁纸，不影响文字）。
- v0.3.3 起对宽表格、长代码块、长 URL 等做了气泡内溢出兜底（内部横向滚动或断行），避免内容冲出边框。
字体与字色（精简移植）¶
自 v0.3.0 起附带自 dsh-fonttune 精简的字体能力：界面字体、正文字体覆盖、代码字体、正文字号 / 标题字号（独立调节）、行距、正文加粗等。正文字色与我的消息字色（v0.2.5）为两个独立变量，可分别设置；代码块、思考区、工具卡片等有意排除，避免破坏语法高亮与状态色语义。
安装与启用¶
任选一种方式安装后，都需要重启 DSH。
从 npm 安装（README 推荐省事方式）¶
将 desktop 换成你自己的 profile 名：
dsh plugin --profile desktop add dsh-conversation-avatar
从 GitHub 安装¶
在 DSH 界面：插件 → 添加插件，填入：
https://github.com/lerwa2025-a11y/dsh-conversation-avatar
公开仓库可由 DSH 自动拉取；私有仓库需先在其它环境登录 GitHub。
从本机文件夹加载（改代码即时生效）¶
界面：插件 → 添加插件 → 从本地/文件夹安装，指向插件目录。
或命令行：
dsh plugin --profile desktop add "本地文件夹的绝对路径"
安装后必做步骤¶
- 重启 DSH。
- 打开 设置 → 插件 → 已安装 → 点开「头像和气泡框」（v0.2.0 起设置入口在插件详情页，不再占设置页独立一节）。
- 上传 AI 头像与你的头像，调整大小（16–128 px）与圆角（0–100%），打开总开关「启用插件」。
头像与 settings.json 存在 $DSH_HOME/dsh-conversation-avatar/，不随插件代码迁移；换机需重新上传或拷贝整个数据目录。
卸载：在插件页停用或删除并重启 DSH；界面上的头像与气泡会移除，已上传图片与设置仍保留。
典型用法¶
最小可用配置¶
只做「聊天式布局 + 默认 SVG 头像」：安装并重启后，在插件详情设置里打开「启用插件」，不上传图片即可使用内置头像。
自定义头像与气泡¶
在设置卡片中：
- 分别上传 AI 头像 / 我的头像（自动缩至 512 px 内，存于
$DSH_HOME/dsh-conversation-avatar/avatars/）。 - 按需开启 AI 回复气泡框，调节磨砂与不透明度；若主题状态栏挡头像，将 头像吸顶下移 设为 1–6 个身位（默认 2）。
- 若希望头像不吸顶、只贴在消息开头，关闭 头像跟随画面。
HTTP 路由（供集成或排查）¶
插件暴露本地路由（README 原文）：
GET/POST/DELETE /dsh-conversation-avatar/avatar/<side>— 读写头像（side 为 user / ai 侧）GET/POST /dsh-conversation-avatar/settings— 读写设置
适用场景与注意¶
适合：希望在 DSH 里用 IM 式左右分列阅读对话、区分人机消息，又不需要壁纸引擎整套装饰的开发者；需要微调会话区字体、行距、气泡视觉但不打算装完整 fonttune 的用户。
务必注意：
- 不要同时启用本插件与壁纸引擎的「自定义会话头像」 — 两者都会向同一批
[data-chat-flow-kind]行插入头像，会出现双重头像。 - 插件在 DSH 客户端侧注入 UI，运行权限与 DSH 进程一致；从 npm 或 GitHub 安装前请核对仓库与 MIT 许可证。
- Node 引擎要求 >=20（见 package.json）。
结尾¶
dsh-conversation-avatar 把壁纸引擎里会话头像扩展单独拆出：双侧头像、可选滚动跟随与吸顶偏移、AI 最终回复气泡，以及可选的字体与字色微调。若你的目标只是「会话更像聊天窗口」，可按上文任选安装方式，在插件详情里打开总开关并上传头像即可。
