dsh-progress-widget

Readme

# 🐳 task-progress-bar（dsh-progress-widget）

> **DeepSeek Harness 任务进度条**——你发消息，进度条立刻出现；它干到哪一步、用了多久、还要多久，一眼看清；干完自动告诉你"✅ 已结束"。

一个为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web 界面设计的小插件：在页面底部以悬浮条实时展示 agent 当前任务的**阶段进度、百分比、当前动作、已用时间、预计剩余时间**。

## ✨ 这是什么（30 秒看懂）

你在 DSH 里给 agent 派活时，它经常"闷头干"——你不知道它到哪一步了、还要等多久。这个插件让**任务全程可视化**：

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

- **你发消息** → 进度条立刻出现（任务名自动总结成短名：问题修复 / 功能开发 / 方案咨询…）；
- **干活时** → 阶段、步数、已用时间实时跳动，预估剩余时间有逻辑地推算；
- **干完时** → 变绿"✅ 已结束 · 用时 X"，30 秒后自动淡出；
- **多窗口同时干活** → 各自独立跟踪，显示最近活跃任务 + 橙色角标"N 个任务进行中"；
- **完全空闲** → 缩成半透明小灰点，不打扰。

## 🎯 为什么好用

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

## 🚀 安装

```bash
# 从 GitHub 安装（推荐）
dsh plugin --profile web add github:uuhihj/task-progress-bar

# 固定版本
dsh plugin --profile web add github:uuhihj/task-progress-bar#v0.1.0

# 或：DSH 设置页 → 插件市场 → 搜索 task-progress-bar 一键安装
```

本地开发：`dsh plugin --profile web add link:<本仓库绝对路径>`，改代码后重启 dsh 即生效。

安装后**重启 dsh web**，页面底部就会出现进度条。

## 🖥️ 显示状态一览

| 情况 | 显示 |
|---|---|
| 你发消息 | 立即出现任务条（标题自动总结成短名） |
| 任务进行中 | `~阶段 2/3 · 实施修复（自动估计）· 45% · 第 N 步 · 已用 X · 预计还需约 Y 分钟` |
| agent 上报了精确阶段 | 显示真实阶段（无 `~` 标注） |
| 任务完成 | 绿色"✅ 已结束 · 用时 X" → 30 秒自动淡出 |
| 多任务并发 | 最近活跃任务 + 橙色角标"N 个任务进行中" |
| 完全空闲 | 半透明小灰点（点击可展开说明） |

## ⚙️ 工作原理

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

```json
{
  "task": "任务名",
  "project": "项目名（可选）",
  "stages": ["调研", "方案", "实现", "验证", "收尾"],
  "current": 2,
  "pct": 55,
  "action": "正在编辑 lib/index.js",
  "etaMin": 8,
  "status": "running",
  "startedAt": 1788300000000,
  "updatedAt": 1788300000000
}
```

| 字段 | 说明 |
|---|---|
| `task` | 任务名（建议总结性短名） |
| `project` | 项目名（可选，显示为徽章） |
| `stages` | 阶段列表（1~7 个） |
| `current` | 当前阶段索引（0 起） |
| `pct` | 当前阶段内进度 0~100 |
| `action` | 当前动作（人类可读） |
| `etaMin` | 预计剩余分钟（每阶段完成重新估算） |
| `status` | `running` / `done` / `failed` / `cancelled`（failed 可加 `cause`） |
| `startedAt` / `updatedAt` | 毫秒时间戳 |

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

## 🖱️ 交互

- 按住拖动，位置自动记忆（localStorage），刷新不丢；
- 右上"–"收起为小圆点（显示阶段数/✓/!），点圆点展开；
- 点击与拖动自动区分（位移超过阈值才算拖动）。

## 🔌 接口

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

## 📄 License

MIT