dsh-eta-forecast

dsh-eta-forecast

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

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

它显示什么

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

超过预测之后（超时追踪）

预测总有失手的时候。之前跑过预测点之后，倒计时只会逼近 0 然后卡住 —— 「还有 1 秒」挂好几分钟，用户不知道这轮已经超时了。现在：

• 跑过预测终点（+ 90 秒宽容期）还在跑 → 大字换成已跑时长，副行「已超时 N 分」。
• 但只有实时估计也认同「就快完了」时才喊。 如果越过截止点之后实时估计算出的 总时长仍然是截止点的两倍以上，说明这轮只是比 6 样本时的预测大、活儿还在正常推进 —— 这时不喊超时，让倒计时继续站岗。判据与实测见下方「第三轮改造」。
• 超时后仍然给重估时间：「重估还要 M 分（HH:MM）」—— 按现有样本重新算的。 这一条是实测补上的：真实一轮跑了 97 分钟，旧版从第 11 分钟起就只喊「已超时」， 连续 88 分钟没给任何时间信息。现在同一轮全程都有可读的重估。
• 超时锚点用「成熟预测」（样本 ≥6 时给出的第一次预测），不用最早那次。 首预测只有 2~3 个样本，最乐观也最不准；拿它当锚点会在第 11 分钟就误报超时， 而同一时刻细化后的估计还说「还有 838 秒」。改用成熟锚点后，同一轮的超时 首次出现从 11 分钟推迟到 32 分钟。
• 超时会学进下一轮。 每次完整跑完的轮次若超出预测，记下「超出比例」； 之后这个会话的估计按最近超时记录的中位比例放大（封顶 1.6×）。 被中断/出错的轮次不算（锚点不可信），准时完成的也不记（不污染）。

估算准确性

第一轮改造（真机上那轮 97.2 分钟、22 步、没有 todo 清单的回放）

指标	改前	改后
超时首次出现	第 11.3 分钟	第 31.9 分钟
超时后「无任何时间信息」的时刻	11 / 15	0 / 15
末期误差（第 1 轮）	+23%	+15%
早期误差（第 2 轮 1.7 分钟处）	−86%	−60%
平均绝对误差（第 2 轮）	62%	42%

1. 整轮时长先验不再排在最后。 没有 todo 清单时，「这类一轮通常跑多久」 比「还剩几步 × 中位步时」稳得多 —— 步时受模型思考时长影响，实测一轮内中位步时 从 22 秒漂到 277 秒。以前它只在其它估计全空时兜底，等于把最好的先验排在最后。 现在它与步数证据一起加权（≥2 轮给 0.45，只有 1 轮给 0.25）。 单样本只用于修正已有估计，绝不由它单独给出数字 —— 那不是估计，是把上一轮硬套过来。

2. 平滑改为不对称：估短时跟得快（α=0.55），估长时跟得慢（α=0.22）。 用户对「说还要 20 分结果 5 分就好了」的容忍度，远高于「说还要 3 分又等了 20 分」。

3. 精度可度量。 每次完整跑完的轮次记一条「预测 vs 实际」，快照里给出：

   • accuracy.mape：最近几轮的中位绝对相对误差（0.18 = 典型偏 18%）
   • accuracy.bias：中位带符号误差（正 = 习惯估长，负 = 习惯估短）

   卡片上表现为副行末尾的「近几轮偏差约 18%」，置信度徽章的 tooltip 里还带偏向。 样本不足 2 轮时一律不显示 —— 不编数字。

第二轮改造：早期上界（把「刚跑 40 秒就报还有 6 分钟」压回去）

第一轮改造之后，把本机全部真实会话日志都回放了一遍，才发现坏名声几乎全来自 一个地方：轮次早期的高估。一小时以上的轮次其实早就偏低了，问题只在开头。

分桶（第一轮改造后）	MAE / 偏置
1–2 分钟	112% / +111%
2–5 分钟	53% / +31%
5–15 分钟	57% / +20%
15–30 分钟	44% / −26%
30–60 分钟	50% / −18%
60 分钟以上	103% / +12%

长轮早就偏低了，所以修法不是「统统砍掉」，而是

「已经跑了 T 秒，这一轮最多还能再跑 k(T)·T + 120 秒」，其中 k(T) = 2.42 + 1.98·log10(1 + T/120) —— 随 T 对数放松 （40 秒时 k≈2.7、10 分钟时 k≈4.0、一小时时 k≈5.4、两小时时 k≈6.0， 折算成「这一轮最多总长」分别是 3.8 / 42 / 324 / 717 分钟，长轮基本不再受约束）。

关键在于这条上界只作用于显示层。如果把它夹在平滑之前，超时锚点也会跟着变小， 实测会发现超时率明显升高 —— 更多轮次退化成「已超时、不给任何时间」， 那正是第一轮改造刚刚修好的、让挂件最没用的形态。放在 forecastSession 返回之前时， 超时判定与精度记录全都看未夹的估计，只有用户看到的那个数字被约束。 因此超时率一位小数都没变（同一批观测点上逐点完全一致）。

回放结果（同一批日志、同一批观测点，逐点对比）：

分组	MAE	偏置	灾难率
全部	61% → 52%	+12% → +8%	5% → 0%
2 分钟以上	56% → 47%	+2% → −1%	5% → 0%
5–30 分钟	51% → 45%	−1% → −3%	6% → 0%
30 分钟以上	64% → 50%	−10% → −17%	4% → 0%
60 分钟以上	103% → 76%	+12% → −8%	3% → 0%

「灾难率」= 非超时态下「显示还剩 ≤30 秒、但实际还剩 2 分钟以上」的观测点占比。 超时态不计入，因为那时卡片显示的是「已超时 M 分」，倒计时数字根本不在屏幕上 —— 把它算进去会得到一个漂亮但没意义的数字。这个指标比 MAE 更贴近体感： 它就是「这破倒计时到底准不准」和「嗯，差不多就是这么回事」之间的区别。

顺带一个反直觉的结论：夹太紧反而更差。上界前面那个 ×1.15 不是随手写的， 把这条缓冲扫了一遍（同一批 2118 个观测点）：

缓冲倍数	MAE	偏置	灾难率
1.00（直接把上界当结果）	49%	−3%	5%
1.15（采用）	52%	+8%	0%
1.30	56%	+18%	0%
1.60	67%	+36%	0%

1.00 的 MAE 确实更低，但它把误差整体压到偏低一侧，并且灾难率又回到 5% —— 也就是每二十个观测点就有一个「说还剩不到半分钟、实际还有好几分钟」。 这正是第一轮改造花力气消掉的那个形态，所以宁可多 3 个百分点 MAE 换回 0%。 再往右则纯亏：1.30 起 MAE 单调变差，灾难率也不会更低。

口径、分桶、灾难率的定义全部写死在回放脚本里，任何人都能在自己机器上复现：

node test/replay-all.mjs                        # 跑本机 ~/.dsh/sessions 的全部日志
node test/replay-all.mjs --before HEAD          # 与任意 git 版本逐点对比
node test/replay-all.mjs --variant path/to/x.mjs # 并排第三组（调参时必须并排看）

--variant 存在的意义：调超时/夹取这类参数时，改文件→跑→改回来这套流程里 任何一次忘记还原都会污染结论（本轮就被坑过一次，得拿 git show HEAD: 当基线重跑）。 给它一个实验副本路径，脚本会把它复制到临时目录再 import，不动工作树。

test/replay-accuracy.mjs 保留着，但它只回放单独一轮，适合讲故事、 不适合支撑「准确率提高了几个百分点」这种结论 —— 换一组参数就能翻盘。

第三轮改造：超时抑制（把「明明还在干活却一直喊已超时」压回去）

前两轮把全部 MAE 从 100% 压到五成上下，但用户的实际抱怨换了个方向：「经常超时」。 把所有真实日志按「超时态占多少墙钟时间」重新量一遍，问题很具体 —— 超时态占了 60% 的墙钟，最长的一轮连续喊了 195 分钟「已超时」。

根因是超时锚点（maturePredictedMs）的语义：它在样本刚够 6 个时冻结， 之后永不更新 —— 不冻结就永远判不出超时，所以这个冻结本身是对的。错的是 拿它当无条件判据：一轮跑到第 195 分钟，早就不该再拿「第 6 个样本时的预测」说事。

修法不是改锚点，而是加一条克制：

越过承诺截止点之后，如果实时估计的总时长仍然远超截止点（> 截止点 × 2）， 说明活儿还在正常推进、只是比 6 样本时的预测大 —— 这时不喊超时， 让倒计时继续站岗；只有实时估计也认同「就快做完了」时才切到超时态。

试过的错误路线先记一笔：把锚点做成棘轮（估计总时长超过锚点 1.5 倍就把锚点 抬到新估计）能把超时率压到 14%，但真超时也几乎不再触发 —— 棘轮每次把锚点 追到当前总时长，等于永远差一点、永远判不出超时。过度校正，放弃。

实测（同一批 28 会话 / 196 轮 / 2301 个观测点）：

指标	改前	改后
超时态占墙钟	60%	8%
最长连续超时	195 分钟	22 分钟
有超时段的轮次	45%	31%
真超时覆盖（实际还剩 >5 分时被标超时）	63%	8%
「离谱」占比（超时里卡片自己还说剩余 >2×真实且 >5 分）	13%	4%
MAE / 偏置 / ±2 倍 / 灾难率	51% / +5% / 92% / 0%	一位都没动

这个判据扫过一遍候选值（同一批观测点）：

抑制倍数	超时率	最长连续	真超时覆盖	离谱占比
1.5	2%	10.6 分钟	2%	6%
2.0（采用）	8%	22.1 分钟	8%	4%
3.0	18%	45.7 分钟	19%	4%
不抑制（1e9）	60%	195.2 分钟	63%	13%

1.5 会把真超时也一起压没了（覆盖率只剩 2%，等于这个功能名存实亡）；3.0 又回到 「动不动就喊超时」。2.0 是唯一同时把「最长连续」压到二十分钟级、又保住 8% 覆盖的档位。

代价写在明面上：抑制是有意识的少报。真正跑飞的轮次，卡片可能到很晚才承认 超时，期间一直显示一个偏大的倒计时。这个取舍是照着用户的真实抱怨选的 —— 「说还有 20 分结果 5 分钟就好了」的容忍度，远高于「一直在喊超时、可它明明还在干活」。

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

版本号

设置面板标题旁有一枚版本徽章（如 1.0.0）。它由宿主在下发客户端脚本时 从 package.json 注入（__DSH_ETA_VERSION__ 占位符替换）—— 浏览器里没有 文件系统，客户端自己读不到版本。state.json 也带 version 字段， 排查问题时和面板显示对得上。发新版本只改 package.json 的 version， 其余自动跟随。

三个刻意的设计选择

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。挂件默认出现在右下角。

从 npm 装（推荐：预构建，装得最快）

dsh plugin --profile desktop add dsh-eta-forecast

已经在装了、要换新版本时必须带上版本号——pnpm 不会因为一个裸包名就重新解析已有的依赖：

dsh plugin --profile desktop add dsh-eta-forecast@<版本号>     # 例如 dsh-eta-forecast@1.6.3

⚠️ 别用 @latest：pnpm 解析它用的是自己那份 registry 元数据缓存，刚发布的新版本常常还没进缓存， 结果是「已满足、什么都不做」——而且不报错，看起来像装成功了（实测踩过）。精确版本号没有这个问题。

不想用 npm（直接从 GitHub 源码装）

dsh plugin --profile desktop add github:qwq-wny/dsh-eta-forecast

本地开发（从目录链接，改完重启 DSH 即生效）

dsh plugin --profile desktop add link:<本目录绝对路径>

dsh plugin 只是把参数转发给 profile 目录里的 pnpm，所以 remove / why / update 同样能用。 --profile <名字> 换成你实际用的 profile（桌面版默认 desktop，网页版通常是 web）。

显示位置

设置面板里有「显示位置」，四选一（与 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，不信任何请求头）—— 这是本插件唯一的写接口，局域网改不了。

操作

• 拖动：整张卡片都能拖 —— 按住左键或右键拖都行（不限于标题行）。 位置会记住，窗口变小会自动夹回屏幕内。
• 收起：标题行右边的 −。折叠后只留一条进度条，不留文字 —— 折叠的意义就是「一眼看进度」，留一行「预计完成」占着地方却什么信息都没给。 卡片高度从 147px 压到 43px，进度条仍在走，会话胶囊、时钟、置信度徽章都收起。 没有进度可显示时（刚开局、还没有样本）折叠态退回标题文字 —— 否则就剩两个孤零零的按钮，认不出这是什么。
• 设置：三种方式等价 —— 标题行的 ⚙、双击标题文字、右键原地轻点。
• 右键：按下后移动就是拖动卡片；按下后原地松开就开关设置面板 —— 面板已经开着时再右键会把它关掉（同一个手势管开也管关，面板上右键同理）。 拖动与开关靠「按下后有没有移动」区分（阈值 3px），不需要记两个手势。
• 缩放：⚙ 里拖滑块。低于 70% 自动变脸 —— 说明文字整体让位， 只留「大号剩余时间 + 进度条」，卡片从 163px 掉到 42px 高。把缩放拖回 100% 一定恢复完整布局（缩扁是推导，不会改写你手动的折叠状态）。
• 切换会话：卡片左上方那排胶囊。点一下就换看哪条会话（见下）。
• 锁定：⚙ 里打开「锁定挂件」。锁定后整张卡片不接收鼠标（像音乐软件的 桌面歌词锁定）—— 点它、拖它、右键它全都不响应，鼠标直接穿过去落到下层的窗口。 唯一还能点的，是卡片右上角那颗 🔒：点一下即解锁。
• 这些偏好存在 localStorage（键 dsh-eta-forecast:v1）；显示位置是宿主级的，不在这里。

切换会话

同时开了多条会话时，卡片左上方会出现一排胶囊，一条会话一个：

• 运行中的会话前面有绿点，扫一眼就知道哪条在跑；
• 当前看的那条高亮；点别的胶囊立刻切过去（立刻重画，不等下一轮轮询—— 最多 2 秒的空窗会让人以为点错了）；
• 会话多了会横向滚动，选中的自动滚到可见区；
• 没标题的会话用 id 尾巴当文案（会话 abcd），而不是全叫「未命名」。

只有一条会话时整行收起 —— 没得切的东西不该占地方。

两个刻意的取舍：

1. 选择只存在内存里，不进 localStorage。 会话是临时的，宿主重启后 id 全换； 记住一个死 id 只会让挂件永远显示「会话不存在」。
2. 钉住的会话消失了就自动回落到默认（宿主排序的第一条），不会卡在空状态上。

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

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

外观设置

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

项	范围	说明
缩放	25% – 100%	整卡等比缩放，以右下角为锚点，缩小时不会飘到屏幕中间。低于 70% 自动切成「时间 + 进度条」，见下方取舍 6
壁纸	本地图片 / 图片链接	本地图会先缩到最长边 1024、转 JPEG 0.82 再存
模糊	0 – 24px	只作用于壁纸层
暗化	0 – 85%	壁纸压暗，保证浅色字也读得清
卡片不透明度	15% – 100%	卡片底色盖在壁纸上的程度，决定壁纸露出多少
显示位置	仅网页 / 仅桌面 / 两者 / 都不	桌面浮窗是否出现（见上一节）
记住我的设置	开 / 关（默认开）	记忆模式：显示位置与桌面浮窗位置落盘，重启原样恢复
隐藏菜单按钮	开 / 关	开启后标题行按钮全部隐藏，改由右键开设置
锁定挂件	开 / 关	整卡不接收鼠标，只剩右上角那颗 🔒 可点（见下方取舍 7）
回到右下角	—	位置拖丢了时的兜底（原来在右键菜单里）
恢复默认	—	缩放、壁纸、位置、折叠、菜单按钮显隐、锁定一起还原（记忆开时连显示位置与浮窗位置的记忆也清掉；不动记忆开关本身）

九个设计上的取舍：

0. 记忆模式分两层，因为「设置」根本存在两个地方。 外观（缩放 / 壁纸 / 折叠）在浏览器 localStorage —— 网页的天然行为，重启本来就保留， 不需要做任何事。真正会丢的是宿主级的：显示位置只活在宿主内存里（改一次重启就没）， 桌面浮窗每次都从右下角重新出现。记忆模式把这两样落盘到 <DSH 配置目录>/dsh-eta-forecast.json， 启动读回；浮窗位置由 helper 在窗口稳定 600ms 后回报、宿主记录。 开关本身也存进去 —— 不然「关掉记忆」这件事重启后记不住，又悄悄变回开了。

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

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

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

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

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

贴哪个角取决于折叠状态：展开态贴右下角；折叠态改贴左下角。 折叠卡片只有 42px 高（小缩放时视觉上仅 19px），贴右下角的话那块 22×22 的热区 会正好压住 + 和 ⚙（实测 45% 时热区 x116138、按钮 x114132）—— 点不动 + 就再也展不开了，逃生门反而成了牢门。左下角只有进度条，盖住无所谓。 折叠态同时把按钮不透明度从 .55 提到 .8：8px 的按钮在那个透明度下基本看不见。

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

• 右键按下 → 移动 ≥3px → 拖动卡片（松手不动面板）
• 右键按下 → 原地松开 → 开关设置面板（开着就关掉）

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

「开着就关掉」有一个必须处理的细节：右键开面板时，Chromium 在 pointerup 之后才派发 contextmenu，而那时面板已经出现在光标下 —— 面板自己的 「右键关闭」会接住同一次右键，把它立刻关掉，表现成「右键没反应」。 解法是记下开面板那一下的坐标，面板侧只忽略落点重合（2px 内）的那一个 contextmenu；别的右键都是真实的「关掉」意图。用坐标而不是时间窗，是因为 时间窗会把「开完马上又想关」的合法快速右键一起吞掉——真浏览器校验里翻过车。

6. 缩小到 70% 以下时，说明文字整体让位给进度条。 12px 的字缩到 70% 只剩 8px、缩到 45% 只剩 5px —— 读不出来，却还把卡片撑到 114px 高，缩放就失去了意义。既然读不了就别占地方：低于 70% 时自动只留 大号剩余时间 + 进度条，卡片高度从 163px 掉到 42px（65%）/29px（45%）。

这一档是由缩放值推出来的，不是新开关：用户拖滑块时想的是「我要它小」， 不是「我要它小、并且文字还在但读不出来」。多一个开关就是多一次需要他理解的设计 决策。缩扁只挂 class，不改写 collapsed 那个用户意图，所以把缩放拖回 100% 一定能展回完整布局。

「左右完成 · 还有 5 分 56 秒」这一句在缩扁态也一并藏掉：它在 165px 宽的卡里会折成 两行，7px 的字糊成一团比没有更难看；大号「14:59」已经说明了什么时候完事。

7. 锁定必须留一颗「点得到」的小锁，而且它不能画在卡片里。 锁定的语义是「鼠标碰不到它」，但一旦真的碰不到，解锁的入口也就跟着没了 —— 用户只能去手改 localStorage，这比不做这个功能更糟。所以：

• 网页端整卡 pointer-events:none；锁定时标题行按钮也一并隐藏（它们已经点不动了， 留着只会让人以为还能用）。
• 唯一例外是那颗 22px 的 #dsh-eta-lock，它挂在 body 上、不在卡片里 —— 挂在卡片内部的话会跟着 pointer-events:none 一起失效，等于把逃生门砌进墙里。 挂 body 还顺便躲开了 transform: scale()，缩到 25% 时它依然是 22px、依然点得中。
• 桌面端的穿透由渲染壳的命中判定管（geometry.hitTestPoint 多收一个 chip 矩形）。 锁定态下卡片与面板都当作「不命中」，只把小锁算进去 —— 否则窗口在卡片那一块仍会 抢走鼠标，下层的应用就点不到，「碰不到」只做了一半。
• 锁定时不贴那块 44px 的逃生热区（见取舍 4）：热区是「可点的」，留着等于给锁定 开了个后门。小锁本身就是逃生门，多一个只会互相打架。
• 锁定状态是客户端的事，存在 localStorage（和缩放、壁纸同级），不劳烦宿主 —— 它不影响估算，也没有跨浏览器的必要。渲染壳也不自己存一份状态，直接读 DOM 上的 data-locked：两边各存一份，迟早会出现「卡片说锁了、窗口还认它可点」。

8. 早期上界只准改「给人看的那一个数」，不准碰锚点。 同一个上界夹在平滑之前会更漂亮：全部 MAE 能从 57% 再降到 50%。但代价是 maturePredictedMs（超时判定的锚点）也跟着变小，实测超时率从 39% 涨到 54% —— 更多轮次退化成「已超时」、不再给任何时间。那正是上一轮改造刚刚修好的、 让这个挂件最没用的形态。所以在 forecastSession 里，超时判定、精度记录、 锚点写入全部用未夹的估计，只有最后 return 出去的那个 remainMs 被约束。 宁可精度少赚 7 个百分点，也不换回那个形态。

9. 超时锚点冻结，但「喊超时」这件事必须另设闸门。 锚点冻结是对的（不冻结就永远追着估计跑、永远判不出超时），可它单独用起来很糟： 一轮跑到第 195 分钟，还在拿第 6 个样本时的预测说「你已经超时了」。 真正的信息不是「超出了那个旧承诺」，而是「旧承诺本身已经不作数了」—— 所以越过截止点后先问一句：实时估计算出的总时长，是不是仍然远超截止点？ 是，就说明活儿还在正常推进，让倒计时继续站岗；不是，才承认超时。 把这两件事拆开，超时态占的墙钟从 60% 掉到 8%，MAE 一个百分点都没动。

它不做什么

• 只开两个只读路由 + 一个回环写路由。 /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 主进程 + 渲染页），复用同一份客户端脚本
                     其中的 geometry.js 是拖拽/尺寸/命中判定的纯函数，单测覆盖
test/forecast.test.js 43 个用例，全部在测「会算错的地方」
test/client.test.js  69 个用例，用最小 DOM 垫片把客户端脚本真跑起来
test/host.test.js    20 个用例，路由/注入/写接口栅栏
test/desktop.test.js  6 个用例，Electron 路径解析与「不静默下载」
test/geometry.test.js 20 个用例，桌面浮窗的拖动/尺寸/命中算式
test/replay-all.mjs  回放本机全部真实日志，逐点对比两个实现（准确性结论的唯一依据）
test/replay-accuracy.mjs 只回放单独一轮，适合讲故事，撑不起百分点结论（可单独跑）
test/visual-check.mjs 可选：真浏览器（Edge）跑 demo.html 并截图
test/desktop-smoke.mjs 可选：真起一个 Electron 浮窗，用 CDP 连进去点开面板
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/

桌面浮窗另有一个真机冒烟测试 test/desktop-smoke.mjs：它自建一个假宿主提供 state.json / eta.js，真拉起 Electron，再用 CDP 连进渲染页去点齿轮开面板， 断言窗口开得够大、开面板后能重算尺寸且右下角不动、面板在可交互区内、 没有 CSP 拦截或加载失败。

它很有必要：单元测试只能钉住 geometry 的算式，钉不住「Electron 里到底发生什么」—— 而窗口是透明的，出错时用户只看到「什么都没有」。这个测试第一次跑就抓到了 「面板按放大前的视口定位」这个次序问题。

node test/desktop-smoke.mjs   # 需要 Electron 与一块真实显示器

已知边界

• ETA 依赖 todo 清单。模型这一轮没写清单时，只能退化到步长/历史兜底， 置信度会明显下降——这不是 bug，是「没有可观测进度」的诚实表现。
• 多会话并行时只显示「优先级最高」的那一条（运行中的优先，其次最近有事件的）。 完整快照在 /dsh-eta/state.json 里，最多 8 条。
• 桌面端的注入走 webserver/index-inject 的内联 script 行，并吞掉加载失败： 路由不在就静默降级，宿主永远不会因为本插件起不来。
• 壁纸存在 localStorage，所以只在这台浏览器、这个域下有效；换浏览器要重设。 图片链接跨域时只能当背景铺，不能读像素（也不该读）。
• 缩放到 25% 时字号约 3px，只是「看一眼还剩多久」，不是用来读文字的。
• 锁定只挡鼠标。键盘（Tab 焦点）在网页端仍可能摸到卡片 —— 真要挡住，得让 卡片在锁定时不可聚焦；这一版没做，因为「桌面歌词锁定」本身就是鼠标语义。
• 锁定状态记在 localStorage，换浏览器要重新锁。
• 早期上界是显示层的约束，不是「真实预测变准了」。它做的事是「把显然不可能的 数字挡在屏幕外」，代价是长轮偶尔会被压得偏低一点（30–60 分钟档偏置 −22%）。 它救不了一个本来就信息不足的估计 —— 那种情况下卡片会老老实实显示「还看不出节奏」。
• 超时抑制是有意识的少报。确实跑飞的轮次，卡片可能到很晚才承认超时， 期间一直显示一个偏大的倒计时（实测真超时覆盖从 63% 降到 8%）。 这是照着「别一直喊超时、可它明明还在干活」的抱怨选的方向，见「第三轮改造」。