进度预估卡 omokom/dsh-progress-eta

@local/dsh-progress-eta

DSH（DeepSeek Harness）Web GUI 插件：任务执行中在输入框左侧显示预估进度与剩余时间。

适用 DSH 0.2.1-rc.2（desktop / web）。本仓库已包含构建产物 lib/，克隆后可直接 link: 安装；改源码后需 npm run build 再重启 DSH。

当前版本 1.0.3：在 v0.9（几何骨架）之上完成确定性估算器、区间/文案三态显示、详情浮层、校准落盘与 LLM 语义精修（宿主路由 + 客户端节流）；1.0.1 修复独立验收发现的缺陷（发布层进度限速、LLM 六态、低置信不单值、软失败 200、完成态文案、宿主派生任务上下文）；1.0.2 修复用户实测的两个缺陷——会话归属缺失（切到空闲会话仍显示旧任务的估算卡片）与出数太慢（预热 20s、数字最多 20s 不动、思考期永远「估算中」）；1.0.3 修复同一会话内「结束信号漏一次」导致的卡片卡死与计时跨轮次累加（多信号轮次判定 + 新一轮强制重置 + 双源 running）。

| 产物 | 说明 |
| lib/index.js | 宿主半（ESM/Cordis）：inject = ['sessions','llm','connection']；POST /api/progress-eta/refine（LLM 精修，含 deriveMessages() 任务上下文派生与软失败）+ GET /api/progress-eta/health |
| lib/client.js | 浏览器半（CJS，window.__ModuleLoader__ 信封）：conversation.input.overlay（id progress-eta-card，竖卡 + 详情浮层）与 conversation.input.left（id progress-eta-pill，窄屏药丸） |

估算器结构（纯函数，可 node --test 直接 import）

| 模块 | 职责 |
| src/client/eta/estimate.ts | 类型 + 证据层（todo/goal/step）、上下文百分比、进度融合 primitives |
| src/client/eta/fusion.ts | 三路 ETA 数学：挣得进度比值、步吞吐、条件残差先验、几何中位、γ_ctx、下限、log-EMA、P50/P90、限速 |
| src/client/eta/display.ts | 阶段机（idle/warming/running/stalled/waiting/compacting/done）、显示三态、置信度、显示节流、发布层进度限速 |
| src/client/eta/ownership.ts | 会话归属（v1.0.2）：running 源事件的 start/finish/ignore/noop 归约 + 两个 UI 共用的 showsCard 渲染门（published state 带 owner session） |
| src/client/eta/lifecycle.ts | 轮次生命周期（v1.0.3）：多信号结束判定（running=false / turnOutline 新轮 / 同轮 response 已提交 / sessionStats.turns 递增 / completionUnread）+ 新一轮强制重置（restart）+ 迟到的自身投影 reanchor；纯函数，可单测 |
| src/client/eta/state.ts | 每 tick 归约器：时钟（扣除审批等待）、上下文峰值、限速进度、EMA、冻结、checkpoint |
| src/client/eta/calibration.ts | 3 粗类启发式（关键词单通道）、FNV 哈希、n/(n+5) 收缩、:long 桶、衰减权重、P90 覆盖率/中位对数误差 |
| src/client/eta/llm.ts | LLM 触发与硬护栏（≤3 次/轮、60s 间隔、状态哈希、连续 2 败禁用、>3× 分歧不用）、请求/响应契约、六态派生 |
| src/host/derive.ts | 宿主侧任务上下文：deriveMessages() → goal / tools_recent / step 中位耗时（纯函数，可单测） |

隐私：浏览器只发 goal_hash/goal_len 与数值；任务原文由宿主从当前会话派生、只进 prompt，不进日志。localStorage: dsh.progress-eta.calibration.v1 只写数值 + 3 粗类 + goal_hash；~/.dsh/progress-eta/diag.ndjson 只写错误码/耗时/finishKind/hash/长度/计数。

开发

npm install
npm run build && npm run typecheck && npm test && npm run check:bundle

npm test 覆盖 171 个用例（冷启动、4s 先验区间、无 todo、todo 跃迁、发布层限速、回退、停滞冻结、等待批准扣除、压缩开销、区间变宽、EMA、5s 显示心跳、会话归属 A/B 场景、轮次生命周期 20 例（①②③④⑥：漏 false / 同轮 response / turns 递增 / 双源任一 false / 5 分钟安全网 / 跨轮重置与会话隔离、迟到的自身投影）、store 级 7 例（真实 store + 假时钟：漏 false 收尾与时钟归零、status 轮询独立收尾、completionUnread、owner 视图离开时的外部会话隔离、3s 尾巴卸载）、校准收缩 n=1/4/5、LLM 六态与低置信不单值、软失败契约、完成态文案、宿主派生、显示三态、状态机迁移、class 分类、几何/密度/详情高度）。
npm run check:bundle 还会额外断言 v1.0.2 的会话归属字段与首数时限常量（TIMING.warmMinS=4 / emitMinIntervalMs=5000 / emitEtaDeltaS=20 / doneTailMs=3000），以及 v1.0.3 的轮次生命周期（decideTurnLifecycle / startLifecycle / absorbTurnBump / readOutlineLast / readTurns / feedStatus / readStatusFallback / STATUS_FALSE_GUARD_MS=1000 / 结束与重开日志），防止以后被静默改回去。

安装

桌面端（推荐）：设置 → 插件 → 添加本地 link：

link:<本仓库克隆目录>\dsh-progress-eta

装完完全退出桌面端再重新打开一次（宿主半改动需要重启）。

沙箱 / 命令行：

& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd"
plugin --profile web add "link:<本仓库克隆目录>\dsh-progress-eta"

从源码构建：

npm install
npm run build # 产物写入 lib/

工作方式（摘要）

- 数据：全部读 DSH 现有实时投影——todos（执行进度）、sessionStats/消息（步数与耗时）、contextPressure（上下文，只做修正不做进度）、运行状态与 turn/start（执行时间）、最近人类消息（当前任务，由宿主 deriveMessages() 派生进 prompt）。
- 估算：三路确定性估算在 log 空间几何融合（挣得进度比 / 步吞吐 / 条件残差），可选 LLM 语义精修（≤3 次/轮、权重封顶 30%、失败静默降级），区间 P50/P90；显示三态（单值 / 区间 /「还需几分钟」），进度封顶 95% 且按发布层 ≤5 点/秒限速。
- 展示：宽屏 = 输入框左侧竖卡（与输入框同高、顶底对齐、可收起为 12px 竖条）；窄屏 = 输入框内左侧药丸；点击展开详情（区间、依据、置信度、校准样本、LLM 开关、清空校准）。
- 可靠性：运行态按会话归属隔离（切到空闲会话不显示别人的估算）；轮次结束用多信号判定（running=false / 新轮出现 / response 已提交 / turns 递增 / completionUnread），漏一次信号也不会卡死，新一轮强制重置计时。
- 隐私：校准只写 localStorage 数值 + 3 粗类 + goal_hash；诊断只写错误码/耗时/哈希/长度；任务原文不进日志。

验证记录

REPORT.md 包含实现记录与沙箱真机实测数值（几何对齐、出数时间、同会话跨轮次重置、LLM 调用计数、隐私检查等）。开发期完整验收证据（截图、逐轮 JSON、独立验收报告）保留在开发工作区，未纳入本仓库。

已知限制

- 停滞冻结、真实审批「允许→恢复」、inflight 瞬时态仅在单测覆盖（真机难稳定触发）。
- 完成任务瞬间进度会跳到 100%（事实值，不受估算限速）。
- 多会话并排仍按单活跃会话处理；隐藏会话若被宿主保留挂载，投影无会话标识时存在理论边界（卡片有 owner 门，不会串显示）。
- 依赖 DSH 未文档化的 slot / 投影契约，DSH 升级可能需适配。

License

MIT