dsh-badge
aa-zza1/dsh-badge
桌面 agent 的 Windows 状态角标:置顶卡片显示当前动作、步骤计数与状态色,默认点击穿透且不进截图,可开取消按钮(点了会写一个标记文件供 agent 轮询)。提供 badge_show、badge_update、badge_cancelled、badge_hide 四个工具。
安装
dsh plugin --profile web add github:aa-zza1/dsh-badgeREADME
dsh-badge
给桌面 agent 用的「正在操作」角标。一个贴在屏幕角落的小窗口,告诉人:AI 现在正在动你的电脑,它在干什么,还剩几步。

已收录进 DSH 插件市场:awesome-dsh-plugin · dsh-badge(分类 notify)
为什么需要
agent 操作桌面时,鼠标会自己动、窗口会自己弹。人看不见提示,就会以为卡死了、或者以为已经做完了,然后去打断它。
系统通知的问题是不持久(几秒就消失);托盘气泡的问题是会被折叠。这个角标是常驻的,只要 agent 还在干,它就在右下角亮着;心跳一断,它自己消失。
特性
- 点击穿透:默认不挡鼠标,角标下面照常能点
- 不进截图:
WDA_EXCLUDEFROMCAPTURE,录屏和截图里都不会出现,只有人眼能看到(自检时用-Captureable关掉) - 状态可变:写一个 JSON 文件,标题、说明、步骤、颜色实时更新,不用重启
- 心跳自灭:调用方持续 touch 心跳文件,静默超过阈值就自己消失,不会留下幽灵窗口
- 可取消:加
-Clickable就会出现 × 按钮,点了写一个标记文件,agent 读到就停手 - 能定位:四角 + 底部居中、多显示器、透明度、主题色
快速开始
# 最简单
powershell -ExecutionPolicy Bypass -File .\dsh-badge.ps1 -Text "正在操作电脑" -Seconds 60
# 带副标题和步骤
powershell -ExecutionPolicy Bypass -File .\dsh-badge.ps1 -Text "正在抓取网页" -Detail "第 2 个来源" -Seconds 120
# 心跳模式:agent 每 30 秒 touch 一次,静默 90 秒就消失
powershell -ExecutionPolicy Bypass -File .\dsh-badge.ps1 -Heartbeat "$env:TEMP\dsh-badge.hb" -Seconds 90
# 停止
powershell -ExecutionPolicy Bypass -File .\dsh-badge.ps1 -Stop
装成 DSH 插件(推荐)
仓库同时是一个 DSH bundle,装进 profile 后会多出四个工具,agent 用工具就能控制角标:
dsh plugin --profile desktop add github:aa-zza1/dsh-badge
| 工具 | 作用 |
|---|---|
badge_show | 显示角标。参数 title 必填,另有 detail / step / total / seconds / anchor / monitor / opacity / accent / lang / clickable |
badge_update | 改标题、说明、进度、状态色(busy / waiting / error / done),不重启角标 |
badge_cancelled | 查用户有没有点 ×(只有 clickable: true 时才有意义) |
badge_hide | 收起角标 |
典型对话里 agent 会这么用:开始操作前 badge_show,每完成一步 badge_update,结束后 badge_hide。
不装插件也能用,下面就是直接跑脚本的方式。
状态文件(多步任务用这个)
角标每 400ms 轮询一次状态文件,随便覆写,立即生效:
$state = @{ title = "正在改脚本"; detail = "写入 README"; step = 2; total = 5; tone = "busy" }
$state | ConvertTo-Json | Set-Content "$env:TEMP\badge.json" -Encoding UTF8
powershell -ExecutionPolicy Bypass -File .\dsh-badge.ps1 -StateFile "$env:TEMP\badge.json" -Heartbeat "$env:TEMP\badge.hb" -Seconds 90
字段都是可选的:
| 字段 | 说明 |
|---|---|
title | 标题行 |
detail | 第二行,建议一句话说明当前动作 |
step / total | 显示「第 2 / 5 步」并画进度条 |
tone | busy(蓝)/ waiting(橙)/ error(红)/ done(绿) |
done 之后建议留几秒再停角标,让人看见结果是绿的。
参数
| 参数 | 默认 | 说明 |
|---|---|---|
-Text | DSH 正在操作电脑 | 标题 |
-Detail | 空 | 副标题 |
-Seconds | 180 | 自动隐藏秒数;心跳模式下是「静默多久算死」 |
-Heartbeat | 空 | 心跳文件路径 |
-StateFile | 空 | 状态 JSON 路径,给了才轮询 |
-CancelFile | 空 | 配合 -Clickable,点 × 时写入这个文件 |
-Clickable | 关 | 关掉点击穿透,整个角标可点 |
-Stop | — | 停掉已在跑的角标 |
-Captureable | 关 | 允许出现在截图和录屏里(只用于自检) |
-Anchor | BottomRight | BottomRight / BottomLeft / TopRight / TopLeft / BottomCenter |
-Monitor | 0 | 显示器序号,0 是主屏 |
-Opacity | 0.92 | 整体不透明度 |
-Accent | #00D4FF | 主色(标题点、进度条、边框) |
-Lang | zh | zh / en |
取消
powershell -ExecutionPolicy Bypass -File .\dsh-badge.ps1 -Clickable -CancelFile "$env:TEMP\badge.cancel" -Seconds 600
点了 × 之后,badge.cancel 会出现。agent 在每个步骤边界检查这个文件,发现就停手并清理。
注意:-Clickable 会关掉点击穿透,那 392×96 的小区域会挡住下面的点击。默认不加。
坑
- 文件要 UTF-8 BOM,否则 Windows PowerShell 5.1 读中文会乱码。
- 进程用 pid 文件(
%TEMP%\dsh-badge.pid)记录,不扫命令行。早期版本靠命令行匹配,结果会把「用 Start-Process 拉起角标」的启动器一起杀掉;现在只杀 pid 文件里那个、且命令行确实对得上的进程。pid 文件丢了就手动Get-Process powershell清一下。 - 高 DPI 缩放下窗口会被系统再乘一次缩放。这个脚本已经按
GetDpiForWindow反算,150% 缩放下位置正确;自己改定位逻辑时记得处理这一层,不然角标会跑到屏幕外。 - 默认不进截图是有意的。要自检画面加
-Captureable。 - 依赖 .NET Framework 的 WPF,Windows 10 / 11 自带,不需要额外安装。
英文说明 / English
A tiny always-on-top status badge for desktop agents on Windows. It tells the person what the agent is doing right now, so they don't mistake a working agent for a stuck one.
- Click-through by default, excluded from screenshots/recordings by default
- Live-updating state from a JSON file (title, detail, step counter, tone)
- Heartbeat mode: disappears by itself when the agent stops touching the heartbeat file
- Optional cancel button that writes a marker file the agent can poll
Requirements: Windows 10/11, Windows PowerShell 5.1 (WPF). MIT licensed.
Listed in
awesome-dsh-plugin — category notify.
License
MIT