标签页状态图标 waknow/dsh-web-icon-indicator

dsh-web-icon-indicator

📖 English · 中文文档 · 📝 更新记录 · Releases · 🎨 在线演示

awesome · DSH plugin
npm version
npm downloads
License: MIT

⚠️ DSH 版本支持 —— 需要 DSH ≥ 0.1.2-rc.1。同一份插件同时兼容两代 settings 契约：新一代（≥ 0.1.7-alpha.1：导出 Config schema + configForms + plugins.bundle.config）与旧一代（≤ 0.1.6-alpha.1：settings.installSection + settingsScope + settings.plugin.item）。已在 DSH 0.1.5-rc.3 与 DSH 0.1.7-alpha.1 上验证；更早的宿主上 favicon 仍可用，只是配置页可能不可达。

浏览器标签页 favicon 实时反映 DSH 会话状态——待机 / 运行中 / 提问 / 完成——让你在标签页置于后台时也能一眼看出是否有会话需要处理。

🎨 在线演示 — · 在浏览器里直接体验四种状态、多 Agent 计数与全部特效，无需安装。试玩间还能驱动演示页自身标签页的真实 favicon——正如插件在 DSH 页面里做的那样。

✨ 功能特性

- 标签页 favicon 实时反映会话状态 —— 浏览器标签页图标同步 idle / running / asking / done（聚合优先级：asking > running > done > idle），后台标签页也能一眼看清 agent 们在做什么——包括 ask_user_question 提问，以及审批 / 沙箱提权等待（这两种情况会把图标钉在 asking 态）。
- 单个 SVG，浏览器内上色与动画 —— 只内置一个鲸鱼模板（icons/base.svg）；每个状态、颜色、每一帧都在客户端渲染为 data:image/svg+xml URI，不再有按颜色拆分的图标文件。
- 六种内置特效 —— static（静止）、blink（闪烁）、breath（呼吸）、rainbow（彩虹）、heartbeat（心跳）、bounce（跳动），全部由 JavaScript 驱动（favicon 不会播放 SVG CSS 动画）。
- 完全可配置、即时生效 —— 每个状态的颜色、特效、周期，以及提问 / 完成驻留时长，改动约 1 秒内同步到已打开的标签页——无需刷新、无需重启。
- 内置配置 UI，无需手写 YAML —— 标签页图标指示器 页面可编辑整套配置，带实时色块预览并自动持久化（新宿主：profile patch；旧宿主：profile settings.yaml，路径见下）。
- 后台标签页与重启抗性 —— 隐藏标签页中 requestAnimationFrame 被暂停时，动画态会按墙钟时间补帧；状态轮询还能扛住 host 重启、后端停止：故障期间标签页图标绝不丢失（还原启动时缓存的原始图标 data:-URI 副本，或保留最后一帧插件图标），端点恢复后自动回到实时状态。切回前台时会立刻触发一次状态拉取并重绘——后台标签页的定时器会被浏览器节流，轮询可能滞后，所以回到标签页的瞬间就刷新最新状态（比如 done 保持期在隐藏期间过期、图标应退回 idle 的情况）。
- 多 agent 一目了然 —— 当同时有超过一个活动 agent（非待机：asking / running / done）时，favicon 从鲸鱼切换为占满整帧的数字块，实时显示活动数（上限 99+），颜色与动画和该状态下鲸鱼完全一致；活动数回到 0–1 时恢复鲸鱼。（视觉与 demo/badge.html 的「满幅数字」通道一致。）

🛠 配置界面——怎么找到它

| # | 步骤 |
| 1 | 打开 DSH Web GUI，进入 设置 → 插件。 |
| 2 | ≥ 0.1.7：展开 dsh-web-icon-indicator bundle，在其 dsh-web-icon-indicator 行上点击 配置；≤ 0.1.6-alpha.1：在该选项卡里打开 插件配置。 |
| 3 | 打开 标签页图标指示器（Favicon indicator） 配置页。 |
| 4 | 先用 默认图标颜色 设置待机鲸鱼的颜色（这是待机唯一的设置项——待机只画一种颜色、不做动画），再展开状态行（running / asking / done）编辑 特效、颜色（每个色块即原生取色器），以及周期（毫秒）——仅动画状态显示，静态状态无周期；用 提问驻留 / 完成驻留 调整两个时长。 |

改动会通过 settings 传输层持久化到 profile patch，约 1 秒内应用到已打开的标签页——无需刷新、无需重启。完整键说明见 配置。

🐳 插件页会显示本插件自己的图标 —— DSH ≥ 0.1.7 的 设置 → 插件 页面会为每个 bundle 卡片画一个 48px 图标（每一行 40px），来源是 package.json → icon。本仓库声明了 "icon": "icons/plugin.svg"，所以卡片显示的是鲸鱼而不是通用占位图。图标由宿主读取（readPluginMeta → iconOf），并以 base64 data: URL 传给浏览器；图标缺失或不合规不会把卡片变空——而是点亮该插件的 meta.error，卡片上出现「问题」标签，所以路径必须相对、必须在包内、且 ≤ 256 KiB。加这个字段不需要任何配置、代码或宿主重启，只需重新安装或发一个新版本；详见插件页图标。

🎬 默认配置，可视化

四个默认状态在浏览器标签页中的实际效果（asking 那条鲸鱼真的在闪烁）：

| 状态 | 颜色（默认） | 特效（默认） |
| idle 待机 | #1a1a1a——深色鲸鱼（可用 defaultColor 替换） | static |
| running 运行中 | #FACC15——黄色 | static |
| asking 提问 | #E5484D ⇄ #FACC15——红/黄 | blink（400ms） |
| done 完成 | #22A06B——绿色 | static，保持 doneHoldMs 后回到 idle |

多 agent 可视化

当多个 agent 同时运行时，favicon 本身就是计数器：只要活动 agent 超过一个（非待机：asking / running / done，含短暂的 done 保持期），鲸鱼就换成占满整帧的数字块——实时显示 active 计数，底色取聚合状态色、特效与鲸鱼完全同源（照常闪烁 / 呼吸 / 彩虹）；活动数回到 0–1 时恢复鲸鱼。

| active（非待机 agent 数） | favicon |
| 0 | 深色 idle 鲸鱼 |
| 1 | 对应状态的鲸鱼（running 黄色，…） |
| 2–99 | 占满整帧的数字块，数字高度约占图标的 31%–52%（1 位 26、2 位 20、3+ 位 15.5）——16px 与固定标签页都可读 |
| 100+ | 99+ |

状态优先级不变：asking 仍以红 ⇄ 黄 400ms 闪烁接管（闪烁的是数字块）， done 按其颜色驻留 doneHoldMs，计数随状态轮询实时刷新（约 1 秒）。
视觉与 demo/badge.html 的「满幅数字」通道一致。

✨ 全部特效，动画演示

下面每个预览都是真实的鲸鱼路径，按插件实际渲染方式做动画（预览是自包含的动画 SVG，在浏览器里直接播放）：

| 特效 | 效果 | 预览 |
| static | 纯色单帧，无动画——使用 colors[0] | |
| blink | 在 colors[0] ⇄ colors[1] 之间按 speed 切换（缺省时自动推导更深的第二色） | |
| breath | 在 colors[0] 与 colors[1] 之间平滑呼吸过渡（缺省时推导） | |
| rainbow | 以 colors[0] 为起始色相，在 speed 内绕色轮循环 | |
| heartbeat | 在 speed 内做「lub-dub」式的尖锐缩放脉冲——颜色为 colors[0] | |
| bounce | 鲸鱼在 speed 内上下跳动——颜色为 colors[0] | |

想改颜色并实时观察标签页 favicon 变化？打开自包含 demo（demo/dynamic-color.html）——选择状态 + 特效并实时改色，favicon 即时更新（无构建、无依赖）。

安装

这是一个标准 DSH bundle 插件。安装到 web profile（GUI/TUI profile 会自动通过 cordis patch 层加载）：

从 npm 安装（推荐）：

dsh plugin --profile web add dsh-web-icon-indicator@latest

从 Git 源码安装：

dsh plugin --profile web add github:waknow/dsh-web-icon-indicator

或从本地目录 / tarball 安装：

dsh plugin --profile web add

或将目录放进 ~/.dsh/profiles/web/node_modules//，并附带与包内一致的 cordis.patch.yml。

ℹ️ 官方插件页的图标读取的是已安装包的 package.json.icon，因此只有在安装（或发布新版本）之后才会出现——已经打开的插件页会一直显示上一次的快照，直到你刷新。
详见插件页图标。

配置

所有键均可选，默认值如下。statusPath 与 iconPathPrefix 是注册期键：只能在合成条目（composition entry）里设置——它们在插件挂载时就被烘进路由表与注入脚本，因此刻意不进入配置页的实时表单（它们是 Config 字段，但非 .volatile()）。

| 键 | 默认值 | 含义 |
| iconsDir | /icons/ | 单个 base.svg 所在目录 |
| statusPath | /dsh-web-icon-status.json | JSON 状态端点 —— 注册期（仅合成条目） |
| iconPathPrefix | /dsh-web-icon-indicator | base.svg 的 URL 前缀 —— 注册期（仅合成条目） |
| askingHoldMs | 3500 | 提问状态的最小保持时长 |
| doneHoldMs | 5000 | 完成状态保持时长，随后回到 idle |
| defaultColor | （未设置） | 默认图标颜色（待机鲸鱼的主色）—— 用于区分多个 DSH 实例；与其它状态颜色过于接近时会告警 |
| states | 见下 | 每个状态的视觉配置 |

插件页的图标不是配置键——它来自 package.json.icon （见插件页图标）。iconsDir 只告诉 favicon 路由去哪里取 base.svg。

states 中每个状态是一个对象：{ effect, colors[], speed? }：

config:
states:
idle: { effect: static, colors: ['#1a1a1a'] }
running: { effect: static, colors: ['#FACC15'] }
asking: { effect: blink, colors: ['#E5484D', '#FACC15'], speed: 400 }
done: { effect: static, colors: ['#22A06B'] }

- effect — 取 static | blink | breath | rainbow | heartbeat | bounce 之一。
- colors — 数组，多个 hex 颜色（#rgb / #rrggbb；非法项会被逐项忽略，全部无效时才回退到该状态的内置颜色）。colors[0] 为主色。多色特效读取更多项：blink 用 colors[0]⇄colors[1]，breath 在 colors[0]⇄colors[1] 间过渡（缺省时自动推导更深的第二色），rainbow 仅用 colors[0] 作起始色相。
- speed — 可选，该状态的周期（ms），也是 blink 的切换间隔。默认 1200。

idle 比较特殊：它的颜色就是 defaultColor 键，设置卡片不为它提供状态条目（一种颜色、不做动画、也没有周期）。若 states.idle 来自合成条目或手写的设置文档的用户层，仍然会被沿用——这属于向后兼容，只是无法在配置页里编辑。

每个状态条目会在默认值之上做浅合并，因此只需覆盖少量状态。示例：

- id: dsh-web-icon-indicator
name: 'dsh-web-icon-indicator'
config:
states:
running: { effect: breath, colors: ['#FF9900', '#FFD9A0'], speed: 900 }
asking: { effect: rainbow, colors: ['#FF0000'] }
done: { effect: heartbeat, colors: ['#2ECC71'] }

区分多个实例（defaultColor）

同时开多个 DSH 实例（不同项目 / profile / 端口）时，给每个实例设一个自己的默认图标颜色，浏览器标签页就能一眼区分，不必去改整套状态配色：

- id: dsh-web-icon-indicator
name: 'dsh-web-icon-indicator'
config:
defaultColor: '#5B8DEF'

- defaultColor 就是待机鲸鱼的主色。它会被折叠进 states.idle.colors[0]，因此 idle 仍保留自己配置的特效与第二色，其它状态的颜色语义（黄=运行、红/黄=提问、绿=完成）不受影响；不设置（默认）即等于「沿用 idle 自己的颜色」，行为与之前完全一致。
- 这是按 DSH 实例生效的设置，不是按标签页：同一实例的所有标签页共用它；另一个实例（自己的 profile，例如 dsh web --port 3081）可以用另一种颜色。
- 恢复默认会把你的覆盖清回合成条目。当颜色本来就来自合成条目（base 层，用户层的 unset 触及不到）时，卡片改为写入 idle 自己的颜色——这样「恢复默认」真的能让图标回到朴素的鲸鱼色，而合成条目里配置的值仍可通过「清除覆盖」一键取回。
- 相似度告警：当默认颜色与其它状态颜色在感知上过于接近时，你会收到告警 —— 设置卡片里实时显示（保存前即可见）、host 日志里记录、状态端点 warnings 中返回 —— 但该颜色仍然会被应用（告警绝不阻断保存）。度量方式是 CIELAB 中的 CIE76 ΔE：ΔE /cordis.patch.yml）中 dsh-web-icon-indicator 行的 config: 段；≤ 0.1.6-alpha.1 写入 ~/.dsh/settings.yaml 的 web-icon-indicator: 段。两者都保持合成条目为 base 层；解析顺序为 schema 默认值 → 合成条目 → 用户层。
- 无需重启服务器、无需刷新标签页即可让配置页的修改生效：≥ 0.1.7 时实时写入直接提交到运行中插件的配置引用（loader/volatile-update——loader 不会重启插件）；旧一代则由 settings 服务回调注册的 onChange。两种情况 askingHoldMs / doneHoldMs 都在主机侧即时生效；各状态的视觉配置（特效 / 颜色 / 周期）会随状态轮询同步进正在运行的标签页，约 1 秒内生效。只有改 lib/index.js 里的代码级默认值才需要重载标签页（或重新构建 DSH Web）。
- 路由路径不是实时设置项。 statusPath / iconPathPrefix 由 Config 校验，但刻意不加 .volatile()，因此不出现在实时表单里：它们已被烘进路由表与注入脚本，在那里生效只会让浏览器去请求服务器根本没有提供的路径。它们只存在于合成条目（见上方表格），改动会重新挂载插件。
- 因此实时设置面覆盖 askingHoldMs、doneHoldMs、iconsDir、defaultColor 与 states。iconsDir 没有 schema 默认值，用户未设置时不会出现在解析后的表单中。
- 浏览器半区是手写的 lib/client.js（ModuleLoader factory 格式——无构建步骤、无额外运行期依赖，仅用 shell 自带的 react）。它按宿主实际声明的插槽注册（≥ 0.1.7 用 plugins.bundle.config，这样插件列表的卡片点开即见表单；否则退回 plugins.row.config——两者都按「Host 是否提供该命名空间」门控；另有旧的 settings.plugin.item），并在渲染时按宿主实际提供的服务解析表单（configForms 或 settingsScope），因此两者都不是模块的硬依赖。DSH 客户端扫描器会在下次启动 profile 时识别新的 dsh.client 声明。
- 未组合 settings 服务的部署不受影响：插件继续使用挂载时的合成条目 + schema 默认值。

插件页图标

DSH ≥ 0.1.7 会在官方插件页为每个插件渲染图标：bundle 卡片 48px、每一行 40px（@deepseek-ai/dsh-client-ui-plugin-manager 的 PackageArtwork，未声明时回退到通用占位图）。图标直接来自包清单，所以给出它纯粹是元数据——不需要改代码、不需要配置、不需要重启宿主：

// package.json
{
"name": "dsh-web-icon-indicator",
"icon": "icons/plugin.svg" // 相对 package.json，且必须留在包内 }

宿主在不执行任何插件代码的前提下读取它（@deepseek-ai/dsh-app-boot 的 readPluginMeta → iconOf）：

| 规则 | 取值 |
| 字段 | 顶层 package.json.icon（与 name/version 同级，不是放在 dsh 下） |
| 路径形式 | 相对清单所在目录；绝对路径、Windows 盘符（C:\…）与 URL 都会被拒绝 |
| 包含关系 | 经 realpath 解析后必须仍在清单目录内（.. 越界会被拒绝） |
| 格式 | .svg → image/svg+xml，.png → image/png，.jpg / .jpeg → image/jpeg，.webp → image/webp |
| 大小 | ≤ 256 KiB（stat 与实际读到的字节数各校验一次） |
| 传输 | 读成字节后以 base64 data: URL 随元数据下发（PluginLocalizedMeta.icon） |

⚠️ 坏的图标比没有图标更糟。 任何不合规都不是静默回退，而是元数据错误：读取器返回 meta.error，宿主把它暴露出来，卡片上会给这个插件打上问题标签。
所以文件要留在包内（files 里已包含 icons/），并且必须是独立可用的 SVG——直接用 icons/base.svg 是无效的，因为它里面的 #p { fill: __COLOR__ } 占位符并不是颜色。本仓库因此提供预填好的 icons/plugin.svg（即 base.svg 把 __COLOR__ 换成 #1a1a1a），并在 test/verify.js 里把整套约束都断言下来（F62–F65）。

由于图标是从已安装的包读取的，本地改动只有在重新安装插件（dsh plugin --profile web add ）或发布新版本之后才会生效。

实现原理

- Host 插件 + 一个小型浏览器半区：在现有 webServer 上注册路由——状态 JSON 端点、静态 /dsh-web-icon-indicator/base.svg（鲸鱼模板），以及一个 tapIndex 向每个 index.html 注入小段浏览器脚本。整套配置就是插件导出的 Config schema，DSH settings 服务按 dsh-web-icon-indicator entry id 把它投射为实时配置页（见上）。
- 状态按 agents.list() 聚合，优先级 asking > running > done > idle。每次请求都会执行一次 reconcile() 检测 running → idle 的转换，因为 agent/status 的 idle 事件在回合结束时并不保证送达。状态端点还会上报 active——非待机 agent 数——当该数 > 1 时，注入脚本改为渲染占满整帧的数字块（demo/badge.html 的「满幅数字」通道：圆角色块，填充色与鲸鱼同源的逐帧状态色/特效，白色粗体数字约占图标高度 31%–52%，上限 99+），而不是鲸鱼，这样即使在 16px 的固定标签页里也能一眼看出同时有几个 agent 在忙。
- ask_user_question 工具调用（通过 tools/pre-execute / tools/result）把会话置为 asking，带可配置的最小保持时长，即使你立刻回答，图标也会保持可见。
- 权限 / 沙箱拦截等待同样会显示为 asking：当 agent 命中沙箱拒绝并请求提权（sandbox_permissions + justification），或其他工具需要征得同意时，审批服务会先写入一条 approval/asked 会话事件并阻塞 agent，直到你做出决定。插件监听 session/event（并以实时会话日志的权威折叠作为兜底）在整个等待期间将会话置为 asking 状态，收到 approval/decided 后清除。
- 浏览器脚本每秒轮询 /dsh-web-icon-status.json（轮询间隔在注入脚本里固定为 1000 ms，不是配置项），首次获取 base.svg，然后每个 requestAnimationFrame 周期把 favicon 重建为 data:image/svg+xml,… URI——把 __COLOR__ 占位符替换为状态配置的颜色，并应用该状态配置的特效。状态响应还会携带当前的每状态视觉配置，因此设置保存后约 1 秒内（下一个轮询 tick）即同步到已打开的标签页，无需刷新。浏览器不会播放 SVG favicon 的 CSS 动画，所以一切动画都由 JS 驱动。由于浏览器在隐藏（后台）标签页会暂停 requestAnimationFrame，轮询还会为动画态补绘一帧按墙钟时间计算的画面——后台标签页保持粗粒度动画（约每 1 秒）而不会冻结，切回前台后恢复满速动画。回到前台时还会通过 visibilitychange 立即触发一次状态拉取并重绘——后台定时器会被节流，轮询可能滞后，所以切回标签页的瞬间就能看到最新状态（例如隐藏期间 done 保持期已过、图标应退回 idle）。轮询还能扛住 host 重启 / 后端停止：启动时会把原始 favicon 缓存为离线安全的 data:-URI 副本，请求失败时还原该副本（副本未取到则保留最后一帧插件图标）——绝不写回原始的服务端 URL（后端停止时它恰恰不可达，写回正是「图标丢失」的根因）；每个 tick 持续重试，端点恢复后第一个成功轮询即换回实时图标（SPA 原地重连，无需手动刷新）。

浏览器支持与已知限制

favicon 本质是一张图片，浏览器不会在标签页 UI 里运行 SVG 自带的 CSS/JS 动画——每一帧都在本插件里由 JavaScript 生成。

| 浏览器 | SVG favicon | 逐帧换色 / 换特效 | 说明 |
| Chrome / Edge | ✅ | ✅ 顺滑 | 实时重读 ；data: URI 的 SVG 可用。 |
| Firefox | ✅ | ✅ 顺滑 | 对 SVG favicon 支持良好（且会响应其 prefers-color-scheme，本插件未使用）。 |
| Safari（macOS） | ✅ 渲染为静态图 | ⚠️ 尽力而为 | 忽略 SVG 内嵌 CSS；favicon 缓存激进。 |
| Safari（iOS） | ✅ 渲染为静态图 | ⚠️ 基本不刷 | 通常需重新访问标签页才刷新。 |

已知限制（截至 Safari 26.3）：

- favicon 有专属缓存。 Chrome 用 favicon 数据库、Firefox 用 favicons.sqlite、Safari 用系统级图标缓存——清普通缓存都清不掉，WebKit 甚至会把「无图标」这一状态也缓存起来。这就是改了图标后，已打开的标签页还可能显示旧图标的原因。本插件已通过「给 base.svg 与状态端点设置 Cache-Control: no-store、请求携带 freshness 参数（?t=Date.now()）、每次切换状态时重建 节点」来缓解。
- 必须先折叠「按主题配对」的两个 favicon link（DSH ≥ 0.1.7）。 宿主的 index.html 里有两个 rel=icon——favicon-dark.svg 对应 prefers-color-scheme: dark、favicon.svg 对应浅色（0.1.6-alpha.2 及更早只有一个）。浏览器取的是最后一个 media 命中的已连接 link，所以只重绘第一个的话，无论会话状态怎么变，标签页始终显示宿主自己的图标。插件现在会在首次绘制前把这一组规范成唯一一个不带 media 的 link（保留你当前配色方案对应的那个）。如果你用的是 0.5.2 之前的版本、且标签页图标完全不变化，原因就在这里。
- Safari 渲染 SVG favicon，但忽略其内部 CSS——不支持 @media、prefers-color-scheme、CSS 动画。所以所有上色必须烘焙进每一帧的标记（本插件正是这么做的），而不能依赖 CSS 变量。
- data: URI 的 SVG favicon 在 Safari 不可靠（WebKit bug 236616，仍未关闭；Safari 17.6 复现）。本插件当前每帧都生成 data:image/svg+xml URI，因此在 Safari 上标签页图标可能完全不显示——这是最大的已知缺口。
- Safari 的动态 JS 更新为 hit-or-miss，可能需要刷新一次；Safari 会「锁定」它首次看到的图标。目前没有保证可靠的、符合规范的手段能在 Safari 中实时更换 favicon。
- 固定标签页图标（）使用独立缓存，与普通 favicon 分开；它是靠 color 属性着色的单色剪影——仅 macOS + 固定标签页、页面加载时读取一次、并非实时。

完整机制与来源（WebKit bugs、Stack Overflow、浏览器工程博客）以及让 Safari 更顺滑变色/切换的推荐路径见 docs/safari-favicon-research.md。

已知限制

- favicon 的 SVG CSS 动画在浏览器标签页 UI 中不会运行——所有特效都由 JavaScript 每帧重建 data-URI 实现，这是零依赖设计的刻意取舍。（本文档中的动画预览只是演示素材——真实 favicon 的动画始终由 JS 驱动。）
- favicon 行为因浏览器而异，其中 Safari 限制最多——见 浏览器支持与已知限制。
- base.svg 模板必须保留 #p { fill: … } 规则中的 __COLOR__ 占位符；浏览器会替换该标记为每帧上色。
- 插件运行在 host 平面，必须挂载进 profile 的组合配置，不能作为会话级 agent preset。
- 文件读取走 fs 服务，以配置的 iconsDir 为 cwd。请确保该路径在部署环境的沙箱策略下可读。

许可

MIT