# 2026-08-31 动态主题色 + 头像图片化

## 嵌入方用法
- 品牌色:`<script src=".../static/widget.js" data-color="#1a73e8">`(3/6 位 hex,`#` 可选;缺省=默认橙 #f08a31)
- **注意**:独立聊天页用 URL 参数时 `#` 必须编码为 `%23`,如 `/?color=%231a73e8`——`?color=#1a73e8` 会在 `#` 处截断而静默回退默认橙
- 自定义头像:`data-avatar="https://.../logo.png"`(完整 URL)或 `data-avatar="/static/xxx.png"`(本服务路径,自动拼挂件源);缺省=内置客服头像 kefu-small.png
- 非法/畸形色值:console.warn + 回退默认橙,页面功能不受影响
- 已知限制:极浅品牌色(亮度>65)配白字对比度低

## 实现要点
- 单品牌色 HSL 派生 7 语义槽位(primary/primary-rgb/gradient-end/deep-text/caption-text/soft-bg/border-soft),CSS 变量注入(widget Shadow DOM `:host` / 独立页 `:root`)
- 派生函数两份(theme.js + widget.js 内联,pytest 源码级同步强制);亮度钳制保证任意色相可读
- 4 层兜底:属性缺失→默认 / 非法→warn+默认 / 派生异常→静态色板 / 结构性(:root 字面量+同字符串注入)
- 头像:图片绝对定位覆盖 + emoji 底层兜底(load 隐藏 emoji/error 移除);断线重连加 host.isConnected 守卫
- 默认视觉:与改造前一致(肉眼不可辨级),唯一可见变化=Send/Start 按钮渐变统一为近纯色(spec §9.1 已批准)
- 回归网:tests/test_theme_static.py 12 项(槽位完整/橙残留/双份同步/跨域头像/:root↔DEFAULT_PALETTE 一致/横幅/独立页槽位)
- 测试页:/static/widget-test.html(换色预览+断言面板)