dsh-eta-forecast

给 DeepSeek Harness 的 Web / 桌面界面加一个「这一轮大概几点做完」的小挂件。

它不是按字数、按步数拍脑袋外推的。真正被当成进度分母的是 todo 清单—— 模型被要求「开工前先列清单、做完就勾」；步数只用来估「一条 todo 平均要几步」， 是节奏修正项，不是进度本身。

它显示什么

位置	内容
大字	预计完成时刻（本地时钟，如 14:32）
副行	还剩多久 + 已经跑了多久
进度条	清单完成度（in_progress 按半条计）
左下	3/7 项，没有清单时退化为「第 N 步」
右下徽章	置信度：样本不足 / 粗略 / 中等 / 较准
第三行	正在做的那一条（正在做：…）

外观（缩放 / 壁纸）点标题行的 ⚙ 调，见下方「外观设置」。

三个刻意的设计选择

1. 等你的时间不算工期。 一轮里 ask_user_question 与 approval/asked 期间整个回合是挂起的。如果把这段算进「已用时长」，一次授权等待就能把 ETA 推到几小时之后，而且再也收不回来。所以挂起时长从 elapsed 里扣掉，挂起时 挂件上会显示 ⏸ 等你操作，这段时间不计入工期。

2. 没样本就说没样本。 一轮刚开始、清单一条都没勾时，任何数字都是编的。 这时大字显示 —，副行写「还看不出节奏」，而不是给一个两分钟后就会打脸的 时间点。置信度徽章也同步降级——先承认不知道，比给一个错的数字有用。

3. 平滑而不是重算。 每条事件都重算会让 ETA 抖动成随机数。剩余时长用 EWMA（α = 0.32）慢慢挪过去，用户看到的是一个在收敛的估计，不是一个乱跳的 读数。

估算来源

四个互相独立的估计，谁有样本用谁，按样本强度加权：

来源	公式	何时生效
progress	净工期 × 剩余条数 / 已完成条数	清单里已有条目被勾掉
pace	平均步时 × 剩余条数 × 每条目步数	本轮已有 ≥2 个步长样本
unit	跨轮单条平均耗时 × 剩余条数	本轮没有可外推进度，但历史有单条样本
history	整轮历史均值 − 已跑	连清单都没有，且历史 ≥2 轮

子代理会话（origin: 'subagent' / delegationDepth > 0）一律不显示—— 你要等的是主对话，不是某一路子代理跑完。

安装

# 本地开发（从目录链接，改完重启 DSH 即生效）
dsh plugin --profile desktop add link:<本目录绝对路径>

装完重启 DSH。挂件默认出现在右下角。

显示位置

设置面板里有「显示位置」，四选一（与 dsh-pet 同一套语义，不用记两套词）：

值	含义
仅网页	只显示 DSH 页面右下角的挂件
仅桌面	只显示桌面上的浮窗（置顶、透明、不占任务栏）
两者	两边都显示（默认）
都不	全部隐藏

桌面浮窗由宿主拉起一个 Electron 小窗（runtime/electron-helper/）。三点说明：

1. 复用现成的 Electron 运行时（$DSH_HOME/electron）。dsh-pet 已经下过那份 300MB， 不重复下载。找不到时不会替你静默下载 —— 那是个用户没同意的重操作，改为明确报错， 可用 DSH_ETA_ELECTRON_PATH 指定路径，或先装 dsh-pet 让它把运行时下好。
2. 默认整窗点击穿透，只有光标落在挂件上才可交互。否则一个置顶透明窗会把下层应用全挡住。
3. 拖动的是窗口，不是 DOM 元素。网页端拖元素、桌面端拖窗口，这是唯一需要分叉的地方； 渲染、缩放、壁纸、右键菜单、设置面板完全共用同一份 assets/eta-client.js。

配置存在宿主内存里（不是 localStorage）：换浏览器也应该一致。改配置走 POST /dsh-eta/config，只接受回环请求（判据是 socket 的 remoteAddress，不信任何请求头）—— 这是本插件唯一的写接口，局域网改不了。

操作

• 拖动：整张卡片都能拖 —— 按住左键或右键拖都行（不限于标题行）。 位置会记住，窗口变小会自动夹回屏幕内。
• 收起：标题行右边的 −。
• 设置：三种方式等价 —— 标题行的 ⚙、双击标题文字、右键原地轻点。
• 右键：按下后移动就是拖动卡片；按下后原地松开就直接打开设置面板。 两个动作靠「按下后有没有移动」区分（阈值 3px），不需要记两个手势。
• 这些偏好存在 localStorage（键 dsh-eta-forecast:v1）；显示位置是宿主级的，不在这里。

右键已经没有中间菜单了。 它原来会弹一个三项小菜单（收起 / 外观设置 / 回到右下角）， 多一层点击只增加摩擦。现在右键直开设置，而「回到右下角」挪进了设置面板底部 —— 那个兜底动作还在，只是不再占一个菜单位。

「隐藏挂件」已移除。 原来点 × 会把整张卡片收起来，只能靠双击右下角 一小块热区找回 —— 既难发现，也容易把自己锁在外面（尤其缩到 25% 之后）。 现在想让它不碍事：收起（只剩标题行）或者拖到角落。

外观设置

点 ⚙（或双击标题 / 右键轻点）打开一个独立的小面板（它不跟着卡片缩放—— 25% 时卡片只有 59px 宽，面板塞进去就没法用了）：

项	范围	说明
缩放	25% – 100%	整卡等比缩放，以右下角为锚点，缩小时不会飘到屏幕中间
壁纸	本地图片 / 图片链接	本地图会先缩到最长边 1024、转 JPEG 0.82 再存
模糊	0 – 24px	只作用于壁纸层
暗化	0 – 85%	壁纸压暗，保证浅色字也读得清
卡片不透明度	15% – 100%	卡片底色盖在壁纸上的程度，决定壁纸露出多少
显示位置	仅网页 / 仅桌面 / 两者 / 都不	桌面浮窗是否出现（见上一节）
隐藏菜单按钮	开 / 关	开启后标题行按钮全部隐藏，改由右键开设置
回到右下角	—	位置拖丢了时的兜底（原来在右键菜单里）
恢复默认	—	缩放、壁纸、位置、折叠、菜单按钮显隐一起还原

五个设计上的取舍：

1. 缩放用 transform，不用宽高。 transform: scale() 只影响绘制，不触发重排， 拖动时不会掉帧；代价是布局宽度仍是 236px，所以所有"盒子有多宽"的判断都必须读 getBoundingClientRect() 而不是 offsetWidth。

2. 卡片底色必须画在壁纸上面**。** 一开始把 background 设在根节点上，结果壁纸 图层整个盖住了它——「卡片不透明度」变成一个死滑块，深色壁纸上的深色文字也糊成 一片。现在改成四层：壁纸图 → 暗化 → 卡片底色（wash）→ 内容。

3. 壁纸单独存一个键。 dsh-eta-forecast:wallpaper 而不是塞进设置的那个 JSON： base64 图片动辄几百 KB，每拖一下滑块就重写整坨大字符串，主线程会卡，也更容易 撞 localStorage 配额。写失败（配额爆了）会明确提示，而不是静默丢掉。

4. 缩到很小要留一条逃生的路。 25% 时卡片只有 59px 宽，齿轮按钮的命中区约 4.5px——点不到。用户会把自己锁在一个打不开设置的小卡片里，唯一出路是手改 localStorage。所以缩放低于 60% 时，在卡片右下角贴一块 44px 的透明热区 （#dsh-eta-hotspot，不参与缩放），双击打开设置；放大回去时它自动消失。

5. 右键身兼两职，靠「有没有移动」区分。 用户要求「所有地方都能右键拖动」， 但右键同时也要能开设置。如果让右键纯粹等于拖动，设置就没入口了；如果让右键 纯粹等于设置，就不能拖。判据是按下后位移是否超过 3px：

• 右键按下 → 移动 ≥3px → 拖动卡片（松手不打开面板）
• 右键按下 → 原地松开 → 直接打开设置面板

面板挂在 body 上、不参与卡片缩放——否则 25% 时字号只剩 3px，等于把人锁死。 面板里的动作与按钮走同一份逻辑（toggleCollapsed / showPanel / resetPosition）， 不复制第二套行为。

默认值是渲染出来比对过的：0.3 时深色字压在深蓝壁纸上糊成一片，0.95 时壁纸 几乎看不见（等于没换）。0.65 不透明度 + 28% 暗化是折中值。

它不做什么

• 只开两个只读路由 + 一个回环写路由。 /dsh-eta/eta.js、/dsh-eta/state.json 只读； /dsh-eta/config 是唯一的写接口，而且只接受来自 127.0.0.1 / ::1 的 POST （判据是 socket 的 remoteAddress，不信任何可伪造的请求头）。局域网改不了显示设置。
• 不 import 宿主服务（webServer 除外，且用 ctx.inject 动态等待）。老宿主 少一个服务时，插件降级而不是整个不 apply。
• 不在页面里重算。 公式只存在于 lib/forecast.js 一处。前后端各写一遍是这类 小挂件最常见的坏味道：两边一改就悄悄不一致。
• 不替你下载 300MB。 桌面模式需要 Electron 运行时，找不到就报错并说清怎么装， 绝不静默下载。

结构

lib/forecast.js     纯估算核心（无 IO / 无 DOM，可 node --test）
lib/index.js        宿主半侧：订阅 session/event、注入页面、三个路由
lib/desktop.js      桌面窗口管理：找 Electron、拉起/关停 helper、崩溃退避重启
assets/eta-client.js 浏览器半侧：每 2 秒拉一次快照，只负责画 + 外观
runtime/electron-helper/  桌面浮窗（Electron 主进程 + 渲染页），复用同一份客户端脚本
test/forecast.test.js 20 个用例，全部在测「会算错的地方」
test/client.test.js  30 个用例，用最小 DOM 垫片把客户端脚本真跑起来
test/host.test.js    16 个用例，路由/注入/写接口栅栏
test/desktop.test.js  6 个用例，Electron 路径解析与「不静默下载」
test/visual-check.mjs 可选：真浏览器（Edge）跑 demo.html 并截图
demo.html           外观预览页，不参与插件运行
cordis.patch.yml    bundle 挂载声明

跑测试：

node --test "test/*.test.js"

想在重启 DSH 之前先看外观，开 demo.html（用任意静态服务器，直接双击 file:// 也行）。 test/visual-check.mjs 需要额外装 playwright，不是必跑项，只用来验证缩放/壁纸在 真浏览器里确实画得出来：

npm i -D playwright        # 一次性
node test/visual-check.mjs # 截图落在 shots/

已知边界

• ETA 依赖 todo 清单。模型这一轮没写清单时，只能退化到步长/历史兜底， 置信度会明显下降——这不是 bug，是「没有可观测进度」的诚实表现。
• 多会话并行时只显示「优先级最高」的那一条（运行中的优先，其次最近有事件的）。 完整快照在 /dsh-eta/state.json 里，最多 8 条。
• 桌面端的注入走 webserver/index-inject 的内联 script 行，并吞掉加载失败： 路由不在就静默降级，宿主永远不会因为本插件起不来。
• 壁纸存在 localStorage，所以只在这台浏览器、这个域下有效；换浏览器要重设。 图片链接跨域时只能当背景铺，不能读像素（也不该读）。
• 缩放到 25% 时字号约 3px，只是「看一眼还剩多久」，不是用来读文字的。