dsh-floating-window

dsh plugin --profile web add dsh-floating-window

dsh-floating-window · DSH 状态悬浮窗

**一块浮在桌面上的磨砂玻璃小窗，实时告诉你 DSH 正在干什么。

不做花哨皮肤，只从实用性出发，简单有时就是最好的。**

不切窗口、不打断手上在做的事 —— 抬头扫一眼就知道：

• 现在有几个任务在跑、每个任务跑到第几分钟、正在处理什么文件、

这个任务已经烧掉多少 Token

• 有没有等你审批的事（要执行删除、改系统之类操作时会停下来问你）
• 今天已经用掉多少 Token、距离「谷时」结束还有多久

（谷时是 DeepSeek 的低价时段，同样用量更便宜；

时间段是工作日的 9-12 点、14-18 点之外，加上周末和法定节假日全天，

插件会自己判断，节假日也从网上自动更新，不用你填）

⚠️ 只支持 Windows 10 / Windows 11。 在 Mac 和 Linux 上装得上、但卡片不会出现。

原因见下面「[先看这里：仅支持 Windows](#先看这里仅支持-windows)」。

不想让卡片占地方的时候，右键点「缩成细条」，它就变成一根细柱贴在屏幕边缘，

几乎不占位置；鼠标移上去才弹出气泡，看一眼就走。

---

先看这里：仅支持 Windows

这个插件只能在 Windows 10 / Windows 11 上工作。

窗口本体是用 PowerShell + WPF（Windows 自带的界面技术）画出来的真·磨砂玻璃窗口，

用到了只有 Windows 才有的系统能力。

在 macOS / Linux 上会发生什么：

• 插件本身会正常加载，不报错，DSH 看起来一切正常
• 但卡片永远不出现
• 插件日志里只有一句 两种启动策略都没成功。请手动跑 panel\run-panel.bat 看报错。

这句话对不熟悉的人完全没有帮助，所以在这里先写死：

看不到卡片，先确认你在 Windows 上。

---

这份说明怎么读

两类人看的东西不一样，可以只挑自己需要的：

想用这个插件的人（不需要懂代码）

1. [安装](#安装) —— 三条命令，选一条

2. [怎么用](#怎么用) —— 鼠标点什么、设置在哪、柱态怎么用

3. [卸载](#卸载) 和 [问题反馈](#问题反馈) —— 不用了怎么办、出问题找谁

想改这个插件的开发者（Node.js + PowerShell）

1. [为什么这样分工](#为什么这样分工) —— 整体架构，先看这个

2. [数据在哪](#数据在哪) / [state.json 字段](#statejson-字段) —— 插件和卡片的接口

3. [数据来源](#数据来源全部经实测验证) —— 每个字段来自哪个事件

4. [拉起策略](#拉起策略踩过的坑) —— 一堆踩坑记录，改代码前必看

5. [开发](#开发) —— 怎么跑测试、怎么检查语法

后面还写着 [配置](#配置)、[调试](#调试)、[开发状态](#开发状态)。

---

安装

已经发布到 npm 了：<https://www.npmjs.com/package/dsh-floating-window>

下面三种方式任选一种，效果一样。

<你的 profile> 是什么？

profile 就是"插件装到哪个配置夹里"的名字。

打开 DSH，侧栏点「插件」，页面上能看到当前 profile 的名字。

不确定就随便用一个你在用的名字，DSH 会在第一次使用时自动建好它。

方式一：命令行，从 npm 装（推荐）

dsh plugin --profile <你的 profile> add dsh-floating-window@0.10.13

⚠️ 这条命令里的版本号必须写精确的（@0.10.13 这种），不能只写包名。

原因：pnpm 11 有个「新版本等待期」机制（minimumReleaseAge，默认 1440 分钟 = 1 天）。

一个版本发布后不到这个时间，pnpm 会认为它"太新、还在观察期"而不去装它。

而你只写包名时，安装范围是"任意版本"，pnpm 就默默往下退到某个老版本，

而且退出码是 0 —— 命令行上看不出任何异常，看起来完全成功。

结果就是你装了、没报错，实际跑的是旧版，出问题能查很久。

写上精确版本号就没有"往下退"的空间了，只能装这一版（或者明确报错），

不会出现"看着成功其实装错"。

另一种办法：把包名加进 profile 的 pnpm-workspace.yaml 的

minimumReleaseAgeExclude 列表里，让它不受这个等待期限制。

那个文件里本来就有一串这样的例外（都是之前手加的），照着加一行

- dsh-floating-window 就行。

方式二：命令行，从 GitHub 装（不用 npm 的备选）

dsh plugin --profile <你的 profile> add github:Windpixy/dsh-floating-window

这条路装的是仓库里的最新代码，没有版本号概念。网络访问 GitHub 慢的时候可以优先用方式一。

方式三：在 DSH 图形界面里装

不想敲命令也可以：

1. 打开 DSH，左侧栏点 「插件」

2. 点 「添加插件」

3. 在输入框里填下面任意一种：

• 包名：dsh-floating-window@0.10.13 ← 推荐
• Git 地址：github:Windpixy/dsh-floating-window
• 打包好的压缩包路径
• 本地文件夹的绝对路径（自己改了代码想试效果时用这个）

装好后重启一次 DSH，卡片会自动出现在屏幕右侧（默认位置，之后它自己记住你拖动过的地方）。

装完之后你应该看到什么

• 屏幕右侧出现一块磨砂玻璃卡片（不是纯色方块 —— 能透出背后的壁纸）
• 有任务在跑时，卡片上按行列出任务名、已跑时间、正在做什么，

以及这个任务已经用掉的 Token（右下角小字，像 12.3k Token）

• 没有任务时，卡片缩成一行，轮流显示「今日 Token」和「谷时倒计时」

如果什么都没出现：先确认是 Windows，再打开插件日志

%USERPROFILE%\.dsh\desktop-card\plugin.log，最后的手段是手动双击

面板目录\panel\run-panel.bat，它会用控制台窗口启动卡片，报错能直接看到。

以后怎么更新

重跑一次安装命令就行（GitHub 方式会去拉最新代码，npm 方式把版本号换成新的）：

dsh plugin --profile <你的 profile> add github:Windpixy/dsh-floating-window

更新完重启 DSH。如果卡片还在屏幕上、没跟着更新，它会自己发现跑的是旧代码并重启一次

（机制见下面「改了代码，卡片会自动重启」），不用手动去关它。

如果命令提示"已经装过了"，先 remove 再 add：

dsh plugin --profile <你的 profile> remove dsh-floating-window
dsh plugin --profile <你的 profile> add github:Windpixy/dsh-floating-window

---

卸载

dsh plugin --profile <你的 profile> remove dsh-floating-window

⚠️ 卸载插件不会关掉已经开着的卡片窗口。

卡片是一个脱离了 DSH 进程树的独立常驻进程（这是故意的：这样你关掉 DSH，

卡片还能留着）。所以"删插件"和"关窗口"是两件事。

卸载之后请右键卡片 → 退出，否则那块窗口会一直飘在桌面上，

而且因为插件已经卸了，它读不到新数据，会一直停在最后一帧。

卸载只删程序，不删你的数据。想连设置和日志一起清掉，手动删这个文件夹：

%USERPROFILE%\.dsh\desktop-card\

---

怎么用

鼠标操作

操作 · 效果

单击卡片 · 跳回 DSH 主窗口

拖动卡片 · 移动位置，松手会记住；开着"贴边"时会自动吸附到屏幕边缘

右键卡片 · 打开菜单：设置… / 置顶 / 回到 DSH / 缩成细条 / 回到默认位置 / 重新读取设置 / 导出诊断包… / 退出

设置界面

右键卡片 → 设置…，打开的就是下面这个窗口。拖滑块 → 点「保存」，

卡片会在半秒内自己套用新设置，不用重启 DSH，也不用关掉卡片。

界面上能改的东西：

分组 · 项目 · 说明

外观 · 磨砂浓度（24~144） · 往左更透（看得见壁纸）、往右更奶白（字更清楚）

外观 · 轮播间隔（5~120 秒） · 空闲小扁条在「今日 Token」和「谷时倒计时」之间多久换一次

尺寸 · 卡片宽度（200~360） · 默认 260

尺寸 · 收起高度（72~160） · 空闲收缩后的高度，默认 96

行为 · 点卡片回到 DSH · 开关；关掉后点卡片没反应

行为 · 贴到屏幕边缘 · 开关；拖动松手自动吸附

行为 · 贴边留白（0~60 像素） · 只在上面那个开关开着时有效

审批 · 在悬浮窗上直接审批 · 默认关，安全原因见下面「[审批相关的两个开关](#审批相关的两个开关安全相关请看完再打开)」

审批 · 点「允许」前再确认一次 · 默认开，防止误点

峰谷 · （只读） · 显示当前是不是谷时、判断规则是什么，不用你填

状态 · （只读） · 卡片在不在跑、DSH 地址有没有同步成功，排查时看这一块

…(truncated)