task-progress-bar

🐳 鲸程 · 任务进度条（dsh-progress-widget）

鲸程 —— 给你的 AI 装一块看得见的时间表。

你发一句话，它就在屏幕角落浮出来：现在干到哪一步、已经花了多久、大概还要多久；干完了自己变成绿色的"✅ 已结束"。

名字取意：鲸潜进深海时你看不见它，隔一阵浮上来换一口气、报个位置；「程」既是进程，也是一程路。包名与仓库名保持 dsh-progress-widget / task-progress-bar 不变（改名会打断已装用户），鲸程 是它对外展示的名字。

给 DeepSeek Harness 用的小插件：在页面角落以悬浮条实时显示 agent 当前任务的阶段进度、百分比、当前动作、已用时间、预计剩余时间。

🆕 最近更新

v0.4.0 · 预计时间重做（2026-10-25）

• 不再"按你说了多少字猜"：实测旧算法平均估高 2–6 倍；改成按「已经跑到第几步」查真实分布（统计自 1481 个真实任务）。
• 有待办就看待办：我列了 TODO 时面板显示 3/7 项，剩余时间按"已完成项平均耗时 × 剩余项数"推算——这是唯一能提前知道"还剩几件事"的信号。
• 越用越准：任务结束时把"第 N 步时还剩多久"记到本机（$DSH_HOME/dsh-progress-stats.json，不联网），攒够 20 条就替掉内置值。
• 不再假装：超过这类任务的常见耗时才报橙色「已超预估」，短任务不会拖到 4 分钟才认栽。
• 测试改成跨机可跑（os.tmpdir()），任何人 clone 下来都能 npm test。

v0.3.0 · 可配置 + 少打扰（2026-10-25）

• 五个配置项：protocolHint / pollMs / doneHoldMs / doneKeepMs / maxTasks（见下方「配置」）。
• 协议注入可关：不想每轮吃 150 字提醒就设 protocolHint: false。
• 一键隐藏：面板右上 × 收成 12px 淡点，点一下恢复。
• 跟随皮肤：颜色改为读宿主 CSS 变量，浅色皮肤不再是块黑补丁。
• 进度条终于平滑：不再每秒重建 DOM，只更新数字与宽度。
• 修：多开窗口会误删正在跑的任务 / 进度文件写坏时任务条消失 / 英文任务没有短名。

✨ 30 秒了解它做了什么

你在 DSH 里派活时，agent 常常"闷头干"——你不知道它到哪一步了、还要等多久。装上鲸程，整个过程变成一条看得见的进度条：

┌────────────────────────────────────────────────────────────┐
│ 🔵 功能开发          [deepseek-harness]     2▾      [–]    │
│ ~阶段 2/3 · 实施修复（自动估计）                    47%    │
│ ▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░                               │
│ ⚙ 正在编辑 lib/index.js · 已用 3 分 12 秒 · 预计还需约 4 分钟 │
└────────────────────────────────────────────────────────────┘

   点一下右上角「2▾」，才会展开它派出去的 2 个子智能体（不点就不占地方）：

┌────────────────────────────────────────────────────────────┐
│   ↳ 审计 D 盘残留         已用 2 分 10 秒 · 预计还需 3 分钟 │
│   ↳ 跑一遍后端用例        已用 1 分 02 秒 · 预计还需 2 分钟 │
└────────────────────────────────────────────────────────────┘

• 你发消息 → 进度条立刻出现（任务名自动总结成短名：问题修复 / 功能开发 / 方案咨询…）；
• 干活时 → 阶段、步数、已用时间实时跳动，预计剩余时间会随实际进展修正；
• 干完时 → 变绿"✅ 已结束 · 用时 X"，30 秒后自动淡出；
• 多窗口同时干活 → 各自独立跟踪，显示最近活跃任务 + 橙色角标"N 个任务进行中"；
• 派了子智能体 → 主任务行多一个「子 N ▸」，默认折叠不刷屏，点开才看每个子任务的名字/已用/还需；
• 完全空闲 → 缩成半透明小灰点，不打扰。

🚀 安装（30 秒）

先确认一件事：--profile 后面填你正在用的那个 profile。桌面版一般是 desktop（目录 profiles\desktop），网页版/自建一般是 web。分不清就看端口：3081=desktop，3080=web。

方式一 · 从 npm 装（最省事，不用连 GitHub）

dsh plugin --profile desktop add dsh-progress-widget

方式二 · 从 GitHub 装（想跟最新代码）

# 固定版本（推荐，不会突然变）
dsh plugin --profile desktop add github:uuhihj/task-progress-bar#v0.2.0

# 跟随 main 分支
dsh plugin --profile desktop add github:uuhihj/task-progress-bar

方式三 · 本地目录（自己改代码，或朋友发你的压缩包解压后）

dsh plugin --profile desktop add link:D:\你的路径\dsh-progress-widget

三种写法本质都是往这个 profile 的目录里执行 pnpm add，所以 npm 包名、github:、link: 都认。装完重启 dsh（桌面版＝关掉重开），页面角落就会出现进度条。

环境要求

项 · 要求 DeepSeek Harness · 0.2.x（桌面版 / Web 版都行）。0.1.5 及更早未验证：面板本身能正常显示，但"每轮提醒 agent 上报真实阶段"依赖 0.2.x 的消息格式，老版本上可能静默失效——不会让 dsh 崩，只是少个精确阶段。 Node.js · ≥ 22.19（dsh 自带，不用另装） 联网 · 不需要。全本地运行，不请求任何外部服务。 隐私 · 只在本机读写一个进度文件，不收集、不上传任何数据。

⏱ 预计时间是怎么算的（0.4.0 起）

不再是"按你说了多少字猜"（实测那样会估高 2–6 倍），而是按已经跑到第几步查真实分布：

1. 待办清单最准：agent 列了待办（面板上显示 3/7 项）时，用"已完成项的平均耗时 × 剩余项数"推算；
2. 本机学习次之：插件会在你自己的机器上累积样本（存在 $DSH_HOME/dsh-progress-stats.json，只在本机、不联网），攒够 20 条就自动替掉内置值；
3. 内置经验兜底：全新安装时用内置分位数（来自 1481 个真实任务的实测统计）。

实话实说：这是概率估计，不是精确预测——同一个任务可能 1 分钟跑完，也可能跑 10 分钟。 所以这个数字只有两种状态是可信的：正常递减，或明确的橙色"已超预估"。不会假装还剩 30 秒却拖 5 分钟。

⚙️ 配置（可选）

在 profile 的 cordis.patch.yml 里按 id 覆盖即可，改完重启 dsh 生效：

- id: dsh-progress-widget
  config:
    protocolHint: true    # 每轮是否注入"维护进度文件"提醒（约 150 字）。嫌吃 token 就设 false
    pollMs: 1000          # 前端刷新间隔（毫秒），低于 200 会被忽略
    doneHoldMs: 30000     # 任务结束后在面板上停留多久
    doneKeepMs: 120000    # 结束任务在内存里保留多久
    maxTasks: 64          # 最多跟踪多少个会话，超出淘汰"最久没活动"的那个

不写这段就是默认值，行为与以前完全一致。

两个界面小操作：

• 面板右上角 × = 本次隐藏进度条（只留一个几乎看不见的小点，点它恢复）；
• – = 收成小圆点（常规收起）。

❓ 常见问题

Q：为什么阶段前面有个「~」，还写着"自动估计"？ A：那说明 agent 没上报真实阶段，插件在按任务类型猜阶段（修复=定位→实施→验证）。想变成精确阶段，让 agent 维护进度文件即可（见下方"agent 上报协议"）。

Q：为什么"预计还需"会变成橙色的"已超预估 3 分钟"？ A：那是诚实的表达。预估跑超了不会假装还剩时间，也不会停在那里装死——橙色只是提醒你"比你我想的久"。

Q：装完没看到进度条？ A：按顺序查三件事——①--profile 是不是你实际在跑的那个；②dsh 有没有真的重启；③页面刷新一次。插件是独立悬浮窗，不会影响 dsh 界面，报错也只会在浏览器控制台。

Q：会占我很多上下文/token 吗？ A：唯一开销是插件每轮给 agent 注入一段很短的进度上报提醒（约 150 字）；进度条本身的显示不花任何模型 token。

Q：多开几个窗口会互相打架吗？ A：不会。每个会话独立算一条任务，进度条顶部用标签页切换；同一个任务（agent 上报的那个）会精确合并成一条，不会显示两遍。

🖥️ 显示状态一览

情况 · 显示 你发消息 · 立即出现任务条（标题自动总结成短名） 任务进行中 · ~阶段 2/3 · 实施修复（自动估计）· 45% · 第 N 步 · 已用 X · 预计还需约 Y 分钟 agent 上报了精确阶段 · 显示真实阶段（无 ~ 标注） 任务完成 · 绿色"✅ 已结束 · 用时 X" → 30 秒自动淡出 多任务并发 · 最近活跃任务 + 橙色角标"N 个任务进行中" 派出了子智能体 · 主任务行出现「子 N ▸」按钮，子任务默认不展开、不占标签栏 看某个子任务 · 标「↳ 子任务」+「↰ 返回父任务」 完全空闲 · 半透明小灰点（点击可展开说明）

🎯 它能干什么（能力清单）

特性 · 说明 全自动驱动 · 任务生命周期由 DSH 事件流判定，不依赖 agent 自觉上报——装上就有用 有逻辑的 ETA · 预估时间 = 消息复杂度 × 项目类型 × 实际进展动态修正，不是乱填 智能阶段模板 · 按任务类型自动套阶段（修复=定位→实施→验证；分析=收集→分析→结论…），带"自动估计"标注 智能任务名 · 你的消息自动总结成短名，不再是一整句看不懂的原话 子任务不刷屏 · 子智能体任务默认折叠，「子 N ▸」按需展开；不再出现三个都叫"问题修复"的标签 防误杀 · 长步骤任务绝不误判过期；agent 忘了标完成也会自动恢复，不永久卡住 零侵入 · 独立 DOM 悬浮窗，不注入任何 DSH UI 槽位，不影响对话界面 可拖动可收起 · 位置记忆（localStorage），收起成小圆点，空闲小灰点不碍事 待办驱动进度 · agent 列了 TODO 就显示 3/7 项，时间按剩余项数推算（最准的一种） 可配置 · 刷新频率、结束停留时长、会话上限、是否注入提醒，都能在 profile 配置里改 一键隐藏 / 跟随皮肤 · 右上 × 收成淡点；配色读宿主变量，深色浅色都不违和 纯本地 · 只在本机读一个进度文件，不联网、不收集、不上传

⚙️ 工作原理

• 自动层（核心）：任务生命周期由 DSH 事件流自动判定——开始 = 用户消息后的 turn/start；进行 = step/start 自动计数；结束 = turn/end（每轮回复完成立即结束）。自动阶段模板按任务类型套用，标题用关键词映射成短名，ETA = 消息复杂度 × 项目基线 × 进展动态修正。
• 上报层（可选增强）：agent 可维护进度文件叠加语义——真实阶段名、精确百分比、当前动作、更准的 ETA。有上报显示真实阶段，无上报纯自动运行。
• 过期防误杀：agent 上报的 running 任务超过 max(2 分钟, 上报 ETA×1.5) 且系统无任何活跃任务时才判残留失效——长步骤任务绝不误杀，忘了标 done 也不会永久卡住。

📦 agent 上报协议（可选）

想让 agent 显示更精确的阶段/ETA，可让它维护进度文件 $DSH_HOME/dsh-progress.json（DSH_HOME 默认 ~/.dsh）：

{
  "task": "任务名",
  "session": "当前会话 id（插件每轮注入的协议里已给出，原样照抄）",
  "project": "项目名（可选）",
  "stages": ["调研", "方案", "实现", "验证", "收尾"],
  "current": 2,
  "pct": 55,
  "action": "正在编辑 lib/index.js",
  "etaMin": 8,
  "status": "running",
  "startedAt": 1788300000000,
  "updatedAt": 1788300000000
}

字段 · 说明 task · 任务名（建议总结性短名） session · 当前会话 id：插件据此把上报任务与本会话任务精确合并成一条（不写则作为独立任务显示，会出现"同一个任务两条"） project · 项目名（可选，显示为徽章） stages · 阶段列表（1~7 个） current · 当前阶段索引（0 起） pct · 当前阶段内进度 0~100 action · 当前动作（人类可读） etaMin · 预计剩余分钟（每阶段完成重新估算） status · running / done / failed / cancelled（failed 可加 cause） startedAt / updatedAt · 毫秒时间戳

agent 行为约定：开工第一步写 running；每阶段更新；任务真正结束标 done（最后一个动作）。

注：插件会每轮自动注入这段协议提醒，不需要你再手工往 AGENTS.md 里抄一遍。

🤖 子智能体任务（多智能体）

父智能体派出子智能体时，每个子会话都是一条独立任务。默认不把它们都摊在标签栏上（否则一排"问题修复"根本分不清谁在干什么）：

• 识别：会话头 delegationDepth > 0 即子智能体会话；父任务 id 取自 parentSession，拿不到就不猜（子任务单独成标签并标 ↳）。
• 命名：优先用派发描述（subagent/descriptor 的 label，例如"审计 D 盘散落残留"），没有才用第一条任务正文清洗后截前 24 字——不再套用"问题修复/功能开发"这类归类名，避免三个子任务同名。
• 显示：主任务行右侧多一个「子 N ▸」按钮，点开才是列表（每条：名字 / 已用 / 预计还需）；点某条进入子任务详情，右上「↰」返回父任务。
• 父任务结束后子任务仍在跑时，顶部会退到子任务显示，不会因为父任务结束就看不见。

🖱️ 交互

• 按住拖动，位置自动记忆（localStorage），刷新不丢；
• 右上"–"收起为小圆点（显示阶段数/✓/!），点圆点展开；点面板其它位置不会收起（防误触）；
• 多任务时顶部显示任务标签页，点标签即可切换并锁定查看（再点「跟随最新」恢复自动）；不会出现同一个任务两条；
• 有子智能体时，点「子 N ▸」展开/收起子任务列表（这个按钮只折叠列表，不会切换查看对象）；点子任务切进去看，点「↰」回父任务；
• 当前任务的详情显示 已用时长 / 预计还需（或已超预估）/ 开始时间；
• 点击与拖动自动区分（位移超过 8px 才算拖动）。

🔌 接口

GET /dsh-progress/status → { ok, task, tasks, live, activeCount }

🧪 开发与测试

npm test   # 后端 subagent-tasks + 前端 client-subagent（mock DOM）

📄 License

MIT

作者：uuhihj · 有问题欢迎提 issue。