前言¶

在 DSH（DeepSeek Harness）里跑长任务时，界面往往只有「正在执行」一类状态，缺少可读的进度和剩余时间。开发者只能盯着 todo 列表或日志猜还要多久，切会话时还容易把上一轮的估算误当成当前会话的。

dsh-progress-eta 是社区维护的客户端插件，在任务执行过程中于输入框左侧展示预估进度与剩余时间，估算以三路融合的确定性数学为主，并可选用宿主路由的 LLM 做语义精修。下面介绍它的定位、能力与安装方式。

这是什么¶

• 名称：@local/dsh-progress-eta（目录与仓库名：omokom/dsh-progress-eta）
• 维护者：omokom
• 分类：客户端（Web GUI）
• 当前版本：1.0.3（package.json）
• 适用宿主：DSH 0.2.1-rc.2（desktop / web）；engines.dsh 为 ^0.2.1-rc.1
• 许可证：MIT

插件不替代 DSH 自带的执行逻辑，而是读取宿主已有的实时投影（todos、sessionStats、contextPressure、运行状态与轮次等），在浏览器侧做融合估算与展示；宿主半提供 LLM 精修接口与从当前会话派生任务上下文的能力。

核心功能¶

展示位置与形态¶

• 宽屏：conversation.input.overlay，竖卡（id progress-eta-card），与输入框同高、顶底对齐，可收起为 12px 竖条。
• 窄屏：conversation.input.left，输入框内左侧药丸（id progress-eta-pill）。
• 点击可展开详情浮层：区间、依据、置信度、校准样本、LLM 开关、清空校准等。

估算与显示¶

估算器为纯函数结构，主要模块包括证据与融合（estimate.ts、fusion.ts）、阶段机与显示三态（display.ts）、每 tick 状态归约（state.ts）、本地校准（calibration.ts）以及可选 LLM 精修（llm.ts）。

工作方式摘要（来自 README）：

1. 数据：读 todos（执行进度）、sessionStats/消息（步数与耗时）、contextPressure（仅作修正）、运行状态与 turn/start、最近人类消息（任务上下文由宿主 deriveMessages() 派生）。
2. 估算：三路确定性估算在 log 空间几何融合（挣得进度比、步吞吐、条件残差）；可选 LLM 语义精修（每轮 ≤3 次、60s 间隔、权重封顶 30%、失败静默降级）；区间 P50/P90；显示三态为单值、区间或「还需几分钟」；进度封顶 95%，发布层进度限速 ≤5 点/秒。
3. 可靠性（1.0.2 / 1.0.3）：会话归属——切到空闲会话不显示其他会话的估算卡片；轮次生命周期——用多信号判定结束（running=false、新轮、同轮 response 已提交、sessionStats.turns 递增、completionUnread 等），漏一次结束信号也不卡死，新一轮强制重置计时。

宿主半 API¶

构建产物 lib/index.js 注入 sessions、llm、connection，提供：

• POST /api/progress-eta/refine：LLM 精修（含 deriveMessages() 与软失败）
• GET /api/progress-eta/health

浏览器半为 lib/client.js（CJS，window.__ModuleLoader__ 信封）。

隐私与本地数据¶

• 浏览器侧请求只带 goal_hash/goal_len 与数值；任务原文由宿主从当前会话派生、只进 prompt，不进日志。
• 校准：localStorage 键 dsh.progress-eta.calibration.v1，仅存数值、3 粗类与 goal_hash。
• 诊断：~/.dsh/progress-eta/diag.ndjson，仅错误码、耗时、finishKind、hash、长度、计数等。

安装与启用¶

仓库 README 写明：本仓库已包含构建产物 lib/，克隆后可直接 link: 安装；改源码后需 npm run build 再重启 DSH。

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

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

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

沙箱 / 命令行（Windows PowerShell 示例）：

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

从源码构建（Node >=22.19.0）：

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

说明：社区目录页为 skillhub.cn 上的 omokom/dsh-progress-eta，与 DeepSeek / 幻方无官方从属关系；安装命令以 README 为准，勿凭插件名自行拼接 dsh plugin add github:...。

典型用法¶

安装并重启 DSH 后，插件随 Web 客户端加载（dsh.client.immediately: true）。任务进入执行态时，输入框左侧会出现进度与 ETA；无需额外配置文件即可使用默认估算。

若需 LLM 精修，在详情浮层中打开 LLM 相关开关（具体 UI 文案以当前版本为准）。精修受每轮次数、间隔与置信度护栏约束，失败时回退到纯确定性估算。

本地校准会在任务完成后根据启发式类别与 goal_hash 逐步收缩区间；可在详情中清空校准数据。

开发侧完整校验：

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

README 称 npm test 覆盖 171 个用例，含会话归属、轮次生命周期、LLM 六态与 bundle 常量断言等。

适用场景与注意¶

适合：经常在 DSH Web / 桌面端跑多步智能体任务、希望在不离开对话界面的前提下看到进度与大致剩余时间的用户。

注意：

1. 插件以当前 DSH 进程权限运行，安装前请阅读 GitHub 仓库 源码与 MIT 许可证。
2. 依赖 DSH 未完全文档化的 slot / 投影契约，宿主升级后可能需要适配。
3. README 列出的已知限制包括：完成任务瞬间进度会跳到 100%（事实值，不受估算限速）；多会话并排仍按单活跃会话处理；停滞冻结、审批恢复等部分边界主要在单测覆盖。
4. LLM 精修会经宿主路由调用模型，请结合自己的模型与路由策略评估成本与隐私。

结尾¶

dsh-progress-eta 把 DSH 已有的 todo、步耗时与运行态投影成输入框旁的进度与 ETA，用三路融合与可选 LLM 精修提高可读性，并用会话归属与多信号轮次生命周期减少错显与卡死。在 DSH「一切皆插件」的生态里，它属于客户端体验增强类插件。

• 目录页：https://www.skillhub.cn/plugins/omokom/dsh-progress-eta
• 源码与说明：https://github.com/omokom/dsh-progress-eta