前言¶
DeepSeek Harness（DSH）里的 agent 跑长任务时，通常用 todo_write 维护一份任务清单。这份清单躺在会话面板里，没有提示、不显示进度，你得自己点开才知道它做到哪一步了。dsh-todo-progress-hud 把同一份清单提到输入框正上方，变成一条常驻的进度条，进度、当前步骤、每一项的状态全程可见。它由 heisedexiaoniukou-max 维护，MIT 协议，属于客户端类插件。
下面介绍这个插件的定位、安装与用法。
定位与数据来源¶
插件不产生任何数据，只读取会话投影 todos。所以它显示的内容始终和 agent 的 todo_write 一致，不需要额外配置或同步逻辑，也没有网络请求和持久化。没有 todo 的会话不会渲染任何内容。
它按访问输入框正上方的位置工作，挂载点是 conversation.input.dock，占用的正是 DSH 内置任务面板的同一个槽位，因此不会多出一条重复的任务信息。
核心功能¶
1、一条常驻任务条。头部始终可见，展开后是完整清单，点一下整条可以折叠，再点展开。折叠状态记在 localStorage。
2、实时进度。细进度条平滑过渡，计数（如 2/5）跟随变化，当前步骤自动轮换。
3、状态有色。完成转绿、进行中为靛蓝并带柔光环、失败转红、待办空心。
4、失败可见。节点内容以 ⚠ / ✗ / ❌ 开头即标记为失败，整条边框告警，进度不会假装正常。
5、外观跟随主题。只用 --dsw-alias-* 主题变量，无阴影、无浮层，宽度对齐输入框；暗色模式自动换成更亮的强调色，并尊重系统 prefers-reduced-motion。
环境要求¶
- DeepSeek Harness
>= 0.2.0（使用conversation.input.dock插槽） - 只适用于 Web / Desktop 页面，纯 headless 环境不渲染
安装¶
通过 GitHub 安装，跟随默认分支，永远拿到最新版：
dsh plugin --profile web add github:heisedexiaoniukou-max/dsh-todo-progress-hud
需要锁定版本时，在仓库地址后加 #v2.1.0：
dsh plugin --profile web add github:heisedexiaoniukou-max/dsh-todo-progress-hud#v2.1.0
本地目录安装（开发调试时使用）：
dsh plugin --profile web add /absolute/path/to/dsh-todo-progress-hud
也可以在 DSH 界面里通过 Settings → Plugins，或让 agent 调用 plugin_manager 的 install_bundle 完成安装。装好后刷新页面即可看到任务条。
典型用法¶
agent 正常调用 todo_write，任务条就会出现并按节点实时点亮。下面是节点失败时的约定写法，失败节点需要在内容里以 ⚠️ 开头：
todo_write([
{ content: "K1 定位问题", status: "completed" },
{ content: "⚠️ K3 联调（接口 500）", status: "in_progress" },
{ content: "K4 回归", status: "pending" }
])
行为对应关系：
| 场景 | 行为 |
|---|---|
agent 调用 todo_write |
任务条出现并按节点实时点亮 |
| 点击任务条 | 折叠 / 展开完整清单（状态会被记住） |
| 全部完成 | 计数显示「全部完成」，整条边框转绿 |
| 节点失败 | 红色边框 + 红色状态点，进度不会假装正常 |
权限与副作用¶
插件不需要任何工具权限、网络权限或 Host 服务。唯一的持久化数据是 localStorage 里的折叠偏好，另外可以用 todo-progress-hud:motion 强制在系统减少动画时开启动效。
插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证，确认是否满足自身环境要求。
实现要点¶
插件由两半组成：Host 半边的 index.js 和浏览器半边的 client.js。client.js 是唯一真正的实现，无依赖、不打包、无构建步骤，通过 window.__ModuleLoader__.load({ id, factory }) 注册，改完刷新页面即可生效。
有个细节值得说明：主机在每次 turn/start 会清空投影。插件按会话缓存上一份非空清单，避免换行时任务条闪烁。样式只用主题变量，尺寸用 em 与 --dsh-content-font-size 自适应。
在控制台执行 window.__TP_HUD 可以确认浏览器实际加载的版本。
卸载¶
dsh plugin --profile web remove dsh-todo-progress-hud
小结¶
它解决的是同一个问题：agent 的 todo 清单藏在会话面板里，长任务做到哪一步要靠人去点开看。现在这份清单直接显示在输入框上方，进度和失败节点一眼可见。适合用 DSH Web / Desktop 客户端跑多步任务、又不想被任务面板打断的人。
目录页：https://www.skillhub.cn/plugins/heisedexiaoniukou-max/dsh-todo-progress-hud
GitHub：https://github.com/heisedexiaoniukou-max/dsh-todo-progress-hud
