会话头像气泡 lerwa2025-a11y/dsh-conversation-avatar

头像和气泡框（dsh-conversation-avatar）

给 DSH 会话双方各配一张头像，消息左右分列（像好友聊天），并给 AI 的最终回复加气泡框。

从 壁纸引擎插件（dsh-plugin-wallpaper-engine） 的「自定义会话头像」扩展移植而来， 只保留头像扩展本身 —— 不带壁纸、液态玻璃、字体、点击特效、拖尾、吉祥物等任何其它功能。

仓库地址：<https://github.com/lerwa2025-a11y/dsh-conversation-avatar> 原作者：elysia395（仓库 <https://github.com/elysia395/dsh-wallpaper-engine>），MIT 协议，特此致谢。

安装

方式一：让 DSH 从本机文件夹加载（推荐，改代码即时生效）

在 DSH 界面里：插件 → 添加插件 → 选择"从本地/文件夹安装"，指向本文件夹即可。
安装后重启 DSH。

或在命令行执行（desktop 换成你自己的 profile 名）：

dsh plugin --profile desktop add "本地文件夹的绝对路径"

方式二：从 npm 安装（最省事，不用克隆仓库）

dsh plugin --profile desktop add dsh-conversation-avatar

或打包下载：

npm pack dsh-conversation-avatar

安装后重启 DSH。

方式三：从 GitHub 直接安装

在 DSH 界面里：插件 → 添加插件，填入下面这个地址即可：

https://github.com/lerwa2025-a11y/dsh-conversation-avatar

因为仓库是公开的，DSH 会自动拉取源码装上。安装后重启 DSH。
注意：仓库必须公开才能这么装；私有仓库需要先在另一台电脑上登录 GitHub 账号。

方式四：打包成压缩包给别人

把本文件夹打包成 ZIP 发给对方，对方在 DSH 界面里用「导入」功能选择该 ZIP 即可。
导入后同样需要重启 DSH。

安装后

1. 重启 DSH
2. 打开 设置 → 头像和气泡框（即本插件的设置节）
3. 上传 AI 头像和你的头像，调好大小和圆角，把总开关打开

注意：头像图片和设置存在 $DSH_HOME 下（见「存储」），不随插件代码走。
换电脑安装后需要重新上传头像；或把旧机器上的整个数据目录拷到新机器的同一位置。

卸载

在 插件 页面里停用或删除本插件，重启 DSH。
停用后会移除界面上全部头像与气泡框，但你上传的图片和设置会保留。

功能

- 每个消息行都配头像：user / steering 行在右侧，assistant-step 行在左侧。
（与壁纸引擎一致；展开「已完成，用时…」过程区时里面的行也会各配一张。）
- 头像跟随滚动：长回复往下滚时，头像贴着滚动区顶部跟着走；整条消息滚出去才随行消失。
可关（v1.0）：关掉后头像只固定在消息开头，往下翻时随行一起滚走，不跟着滑动。
- 吸顶下移：翻页时头像下滑 N 个身位（默认 2），避开主题插件云母状态栏的遮挡。跟随关掉时此项置灰不可调。
- AI 回复气泡框：只给每轮最终回复套框；思考过程 / 工具区不套。可开关。
- 内置默认头像：没导入图片时画 SVG（我方人像、助手四角星），跟随主题文字色。

设置

入口：设置 → 插件 → 已安装 → 点开「头像和气泡框」这个插件，设置卡片就在它详情页的「描述」和「组件列表」之间（槽位 plugins.bundle.config，按包名 keyed）。

以前它占「设置」页里独立的一节（settings.section），v0.2.0 起改到插件自己的详情页，设置页列表不再多出这一项。设置内容和存储位置都没变，只是入口搬家。

| 项 | 说明 |
| AI 头像 / 我的头像 | 上传、替换、清除（图片自动缩到 512px 内，存本机） |
| 头像大小 | 16–128 px |
| 圆角强度 | 0（直角）–100（正圆）% |
| AI 回复气泡框 | 开关，默认开 |
| 气泡背景色 / 边框色 | 留空 = 跟随主题 |
| 气泡圆角 | 0–40 px |
| 气泡不透明度 | 0–100%，默认 100 |
| 气泡磨砂 | 0–30 px，默认 10；0 = 关闭。只模糊气泡背后的壁纸，不影响文字 |
| 正文字色 | 留空 = 跟随主题。只改 AI 回复的正文，代码/思考/工具调用不变 |
| 我的消息字色 | 留空 = 跟随主题。只改你自己发出的消息文本（v0.2.5） |
| 界面字体 | 微软雅黑 / Noto Sans SC / 宋体 / 黑体 / 楷体 / 仿宋（v0.3.0） |
| 正文字体 | 覆盖界面字体，只作用于正文（v0.3.1） |
| 代码字体 | Consolas / JetBrains Mono / 系统等宽 |
| 正文字号 | −4…+8 px，相对主题，0 = 不变 |
| 标题字号 | −6…+12 px，独立于正文 |
| 行距 | −20…+60 %，相对主题 |
| 正文加粗 | 0 = 跟随主题；只加粗段落，不动标题层次 |
| 头像跟随画面 | 开关，默认开（v1.0）。关掉后头像只固定在消息开头，不跟着滑动 |
| 头像吸顶下移 | 0–6 个头像身位，默认 2。跟随关掉时置灰 |
| 启用插件 | 总开关；关掉后移除全部头像与气泡，设置保留 |

字体结构：界面 + 正文覆盖（v0.3.2）

正文字体（bodyFont） ← 覆盖层：不填就跟随界面字体 ↑ 覆盖界面字体（fontFamily） ← 打底，整站生效（含侧边栏标题）

| 界面 | 正文 | 结果 |
| 雅黑 | 空 | 整站雅黑 |
| 雅黑 | 宋体 | 正文宋体，其余（含侧边栏标题）仍是雅黑 |

为什么没有「标题字体」这一项（v0.3.2 去掉的）：

查 app.asar 逐条核对，三条链路最终取的是同一个 --dsw-font-family：

| 位置 | font-family 来源 |
| markdown 正文 | var(--dsw-font-family) |
| markdown 标题 h1–h6 | var(--dsw-font-family) |
| 侧边栏标题 | 无自己的声明，继承 body → 也是 --dsw-font-family |

所以「标题字体」和「界面字体」是同一个变量。再做一个开关不会有任何区别于界面字体的效果，等于把同一件事卖两次 —— 故去掉。代码里 headingFont 字段仍保留（老配置读进来不会报错），万一以后 DSH 拆出独立标题令牌可以直接用上。

实现要点：

- 正文不穷举标签（p/li/td 会漏），而是给 markdown 容器设字体，让内部所有元素继承 —— 这样任何层级都吃到正文字体。
- 正文规则需要 !important：容器自身有 font:var(--dsw-font-markdown-base) 简写，里面已含 family，不加 flag 压不过去。
- 用户消息不是 markdown 渲染，所以正文字体会额外覆盖到你自己的气泡（限定 [data-cav-row] 内，不误伤别处）。
- 覆盖层规则不加 !important 到父容器：子元素自身声明本就优先于 body 的继承值。

气泡为什么包不住所有内容（v0.3.3 修）

症状：输出宽表格、长代码块、长 URL 时，内容跑到气泡边框外面。

第一版修错了方向：只盯着宽表格 —— 宿主给宽表格加的 .md-table-wide 确实是「故意比正文更宽」（width: calc(100% + lead + spare) + 负 margin-left），压回去之后还有别的东西在溢出：长代码块（white-space:pre 不换行）、长 URL / 长路径（不可断词）、数学公式、宽图片。所以「加了表格规则还是盖不住」。

最终方案是「通用兜底」，不猜类名：

| 作用对象 | 规则 | 为什么 |
| 气泡内所有直接子元素 | max-width:100%; min-width:0 | min-width:0 是关键 —— flex 子项默认 min-width:auto，会被「最小内容宽度」顶大 |
| pre / table / 公式 / 代码块容器 | max-width:100%; min-width:0; overflow-x:auto | 长行在自己内部横向滚，不往外长 |
| img / video / svg / canvas | max-width:100%; height:auto | 等比缩小而不是滚动 |
| table 本体 | width:100% | 宿主是 width:max-content，只盖 max-width 压不住 width |
| 气泡本体 | overflow-wrap:anywhere | 长 URL 强制断行，实在放不下才断 |

为什么不给 .cav-bubbled 本体加 max-width：气泡和头像同处一个 flex 行，在行级加宽度约束会把头像一起撑大（2026-10-25 踩过，表现为「头像变成一个巨大的方块」）。
约束只能加在气泡内部的元素上。

字体功能（v0.3.0，移植自 dsh-fonttune 的精简版）

原版是 573KB 的令牌改写引擎，为了做到「字重轴 + 行高 + 字体三轴全联动」，要逐个改写 DSH 的 40 多个 font 令牌。这里只需要四件事，所以走了一条短得多的路。

字号为什么能分开调（查 app.asar 得到 DSH 的体系）：

正文 --dsw-font-markdown-base = var(--dsh-content-font-size, 14px) / ... 标题 --dsw-font-markdown-h1..h3 = calc(N px + var(--dsh-content-font-delta))

正文挂在 --dsh-content-font-size，标题挂在 --dsh-content-font-delta。
两个变量天生不同，所以「正文 +2px、标题 −3px」这种组合可以直接生效，互不影响。

字体清单只列本机装了的：原版清单有 22 项，含 PingFang SC、Sarasa Gothic、 Hiragino 等 macOS/第三方字体。本机没有的字体选中后会静默回退，看起来像「功能没生效」。
这里只列 2026-10-25 实测安装过的 6 种中文字体，每项都带 generic family 兜底。

必须 !important：DSH 主题把 --dsh-content-font-size 内联写在 body 上，内联声明优先级高于普通样式表规则，不加 !important 完全改不动。

字体值做了注入过滤：这个值会被拼进 CSS，所以只放行字母数字、空格、中文、连字符、下划线、引号、逗号；; { } ( ) 一律拒绝，防止逃出声明边界。

两个字色互不干扰（v0.2.5）

「正文字色」和「我的消息字色」是两个独立的变量：

| 设置项 | CSS 变量 | 作用行 |
| 正文字色 | --cav-text-color | [data-cav-row="ai"] |
| 我的消息字色 | --cav-user-text-color | [data-cav-row="user"]（含 steering） |

可以分别设成不同颜色，也可以只设一边。都不设 = 完全跟随主题。

用户消息用的是 DSH 另一套渲染（conversation.user.text，不是 markdown），但排除清单照样有：头像、行内代码、以及各自有颜色语义的元素都不参与变字色。

正文字色管到哪儿、不管哪儿（v0.2.2 加）

管：AI 回复里的段落、标题、列表、粗体、斜体 —— 所有靠继承取颜色的文字。

不管（有意排除，不是遗漏）：

| 排除对象 | 为什么 |
| 代码块 pre / 行内 code | 宿主用 shiki 做语法高亮，每个 token 自带颜色。底色和默认前景若被用户色污染，深色代码块上会出现看不清的暗字 |
| 思考区 [data-chat-group-part="reasoning"] | 与头像的判定同一套标记（isProcessRow），两处必须一致 |
| 工具调用 [data-chat-flow-kind="turn-process"]、[data-chat-call-id] | 工具卡片有自己的状态色，改字色会让「红=错误」这类约定失效 |
| 用户自己的消息 | 需求原话是「只改对话字体」，指 AI 回复；用户消息保持主题色 |

实现上不是逐元素点 color，而是给正文容器设 color: var(--cav-text-color, inherit)：变量由 JS 写入 <body>，留空就移除变量、整条规则失效。这样不会像 * { color } 那样连图标、边框、按钮一起改。

不做对比度校验：选什么颜色是用户的选择，面板只提示一句当前状态。

气泡为什么「拉高不透明度就看不见字」（v0.2.1 修）

旧写法把底色放在伪元素上并给 z-index: 0，再把直接子元素抬到 z-index: 1：

.cav-bubbled::before { z-index: 0; } /* 底色层 /
.cav-bubbled > { z-index: 1; } /* 只抬直接子元素 ← 坑在这 /

管不到更深层的节点。气泡里的文字一旦被宿主包在嵌套层里，就停在 z-index: auto，被 z-index: 0 的底色整片盖住——不透明度越高盖得越死，拉到 100% 就是彻底看不见。

现在改成不依赖内容结构：

.cav-bubbled { isolation: isolate; } /* 自建层叠上下文 /
.cav-bubbled::before { z-index: -1; } / 压在所有后代之下 /

isolation 把 -1 关在气泡内部不漏到外层，-1 则保证任何深度的文字都在底色之上。

磨砂（backdrop-filter）加在同一个伪元素上，绝不加在 .cav-bubbled 本身——加在元素上会让它成为包含块、改变定位上下文（历史上因此整段会话不渲染）。

存储

$DSH_HOME/dsh-conversation-avatar/
├── settings.json
└── avatars/
├── user-<stamp>.<ext>
└── ai-<stamp>.<ext>

路由

- GET /dsh-conversation-avatar/avatar/<side> → 头像字节（未导入 404）
- POST /dsh-conversation-avatar/avatar/<side> → 导入
- DELETE /dsh-conversation-avatar/avatar/<side> → 清除
- GET/POST /dsh-conversation-avatar/settings → 读写设置

移植说明

装饰层逻辑（行选择器、注入标记、MutationObserver 早退、就地更新）取自壁纸引擎的 src/avatar-layer.js；默认头像 SVG 零件表取自同处。类名统一改为 cav- 前缀，数据目录与设置独立，避免与壁纸引擎冲突。

注意：不要同时启用本插件与壁纸引擎的「自定义会话头像」——两者都会往同一批 [data-chat-flow-kind] 行里插头像，会出现双重头像。

更新日志

| 版本 | 改了什么 |
| 1.0.0 | 「头像跟随画面」开关：可以关掉，关掉后头像只固定在消息开头、不跟着滑动（默认仍跟随）。跟随关闭时「吸顶下移」置灰。版本号从 0.3.x 正式转到 1.0 |
| 0.3.3 | 修气泡包不住宽内容（宽表格改为表格自己横向滚，不再冲出气泡） |
| 0.3.2 | 去掉「标题字体」（侧边栏标题就是界面字体，留着是误导），正文字体成为界面字体的覆盖层 |
| 0.3.1 | 正文字体覆盖层；字色扩展到用户消息 |
| 0.3.0 | 字体功能：界面字体 / 代码字体 / 正文字号 / 标题字号 / 行距 / 加粗（移植自 dsh-fonttune 的精简版） |
| 0.2.5 | 用户消息字色，与 AI 正文字色互不干扰 |
| 0.2.2 | AI 正文字色（只作用于正文，代码 / 思考 / 工具调用不变） |
| 0.2.1 | 修「拉高气泡不透明度后看不见字」（isolation + z-index:-1）；气泡磨砂 |
| 0.2.0 | 设置从「设置页独立一节」搬到插件自己的详情页 |
| 0.1.x | 会话头像 + AI 气泡框首版（移植自壁纸引擎的头像扩展） |