头像和气泡框（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 气泡框首版（移植自壁纸引擎的头像扩展）