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

Name: uuhihj/task-progress-bar
Author: uuhihj

鲸程 —— 给你的 AI 装一块看得见的时间表。你发一句话，它就在屏幕角落浮出来：现在干到哪一步、已经花了多久、大概还要多久；干完了自己变成绿色的"✅ 已结束"。

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

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

✨ 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 自带，不用另装）
联网	不需要。全本地运行，不请求任何外部服务。
隐私	只在本机读写一个进度文件，不收集、不上传任何数据。

❓ 常见问题

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），收起成小圆点，空闲小灰点不碍事

⚙️ 工作原理

自动层（核心）：任务生命周期由 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。

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

鲸程 —— 给你的 AI 装一块看得见的时间表。你发一句话，它就在屏幕角落浮出来：现在干到哪一步、已经花了多久、大概还要多久；干完了自己变成绿色的"✅ 已结束"。

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

✨ 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 秒）

方式一 · 从 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

环境要求

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

❓ 常见问题

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

🖥️ 显示状态一览

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

🎯 为什么好用

特性	说明
全自动驱动	任务生命周期由 DSH 事件流判定，不依赖 agent 自觉上报——装上就有用
有逻辑的 ETA	预估时间 = 消息复杂度 × 项目类型 × 实际进展动态修正，不是乱填
智能阶段模板	按任务类型自动套阶段（修复=定位→实施→验证；分析=收集→分析→结论…），带"自动估计"标注
智能任务名	你的消息自动总结成短名，不再是一整句看不懂的原话
子任务不刷屏	子智能体任务默认折叠，「子 N ▸」按需展开；不再出现三个都叫"问题修复"的标签
防误杀	长步骤任务绝不误判过期；agent 忘了标完成也会自动恢复，不永久卡住
零侵入	独立 DOM 悬浮窗，不注入任何 DSH UI 槽位，不影响对话界面
可拖动可收起	位置记忆（localStorage），收起成小圆点，空闲小灰点不碍事

⚙️ 工作原理

自动层（核心）：任务生命周期由 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。

uuhihj/task-progress-bar

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

✨ 30 秒了解它做了什么

🚀 安装（30 秒）

环境要求

❓ 常见问题

🖥️ 显示状态一览

🎯 为什么好用

⚙️ 工作原理

📦 agent 上报协议（可选）

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

🖱️ 交互

🔌 接口

🧪 开发与测试

📄 License

Community comments

uuhihj/task-progress-bar

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

✨ 30 秒了解它做了什么

🚀 安装（30 秒）

环境要求

❓ 常见问题

🖥️ 显示状态一览

🎯 为什么好用

⚙️ 工作原理

📦 agent 上报协议（可选）

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

🖱️ 交互

🔌 接口

🧪 开发与测试

📄 License

Community comments