dsh-web-icon-indicator

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

dsh-web-icon-indicator

📖 [English](README.md) · [中文文档](README.zh.md) · 📝 [更新记录](CHANGELOG.md) · Releases · 🎨 在线演示





⚠️ 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 会话状态——待机 / 运行中 / 提问 / 完成——让你在标签页置于后台时也能一眼看出是否有会话需要处理。

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

✨ 功能特性

• 标签页 favicon 实时反映会话状态 —— 浏览器标签页图标同步 idle / running / asking / done（聚合优先级：asking > running > done > idle），后台标签页也能一眼看清 agent 们在做什么——包括 ask_user_question 提问，以及审批 / 沙箱提权等待（这两种情况会把图标钉在 asking 态）。
• 单个 SVG，浏览器内上色与动画 —— 只内置一个鲸鱼模板（[icons/base.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](./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 那条鲸鱼真的在闪烁）：

<p align="center">

<img src="assets/states-default.svg" width="420" alt="默认状态：idle 深色鲸鱼、running 黄色、asking 红/黄闪烁、done 绿色">

</p>

状态 · 颜色（默认） · 特效（默认）

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 时恢复鲸鱼。

<p align="center">

<img src="assets/multi-agent-count.svg" width="576" alt="active=0 深色鲸鱼、active=1 黄色鲸鱼、active=2/3 黄色数字块、active=3 asking 红色块（闪烁）、active=100 显示 99+">

</p>

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](./demo/badge.html) 的「满幅数字」通道一致。

✨ 全部特效，动画演示

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

特效 · 效果 · 预览

static · 纯色单帧，无动画——使用 colors[0] · <img src="assets/effects/static.svg" width="56" alt="static 特效预览">

blink · 在 colors[0] ⇄ colors[1] 之间按 speed 切换（缺省时自动推导更深的第二色） · <img src="assets/effects/blink.svg" width="56" alt="blink 特效预览">

breath · 在 colors[0] 与 colors[1] 之间平滑呼吸过渡（缺省时推导） · <img src="assets/effects/breath.svg" width="56" alt="breath 特效预览">

rainbow · 以 colors[0] 为起始色相，在 speed 内绕色轮循环 · <img src="assets/effects/rainbow.svg" width="56" alt="rainbow 特效预览">

heartbeat · 在 speed 内做「lub-dub」式的尖锐缩放脉冲——颜色为 colors[0] · <img src="assets/effects/heartbeat.svg" width="56" alt="heartbeat 特效预览">

bounce · 鲸鱼在 speed 内上下跳动——颜色为 colors[0] · <img src="assets/effects/bounce.svg" width="56" alt="bounce 特效预览">

想改颜色并实时观察标签页 favicon 变化？打开自包含 demo（[demo/dynamic-color.html](./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 <路径或tarball>

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

ℹ️ 官方**插件页*

…(truncated)