前言¶
用 DeepSeek Harness（dsh）跑 Agent 时，工具调用和模型轮次往往在后台连续进行。不点开会话、不翻事件流，很难回答四个具体问题：现在在干什么、这一轮第几步、已经跑了多久、待办清单推到哪一项。社区插件 dsh-agent-status（维护者 mdktelmdktel，分类：客户端）把上述信息折叠成标题栏里的「胶囊」状态条，并在 0.2.0 起可选屏幕右下角置顶 HUD，数据来自本机 HTTP API，零配置即可使用。
下面按定位、能力、安装与原理说明用法与注意点。插件以当前 dsh 进程权限运行；安装前请自行查看 GitHub 仓库 源码与 MIT 许可证。社区目录页见 skillhub.cn，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
dsh-agent-status 是 DSH 客户端插件：在会话标题栏实时显示 Agent 进度，并可选独立桌面窗口常驻显示同一套状态。
它要解决的是「进度可见性」——不用切换面板，一眼看到当前动作、步数、本轮耗时和待办进度。npm 上另有同名包 dsh-agent-status（作者 r2s，2026-10-20 发布，功能类似），不是本插件；请认准 github:mdktelmdktel/dsh-agent-status。
核心功能¶
标题栏胶囊¶
胶囊单行示例（来自 README）：
● 执行命令：pnpm test · 第 12 步 · 1:38 · 待办 3/7
● 修改文件：client.js · 第 8 步 · 0:42
✓ 上一轮完成 · 6 步 · 1:12 ← 空闲 9 秒后自动消失
含义约定：
- ● 蓝点脉冲：正在执行
- ✓ 绿点：刚结束的一轮
- ✗ 红点：最近一次工具调用失败
- 鼠标悬停：当前待办原文 + 最近 4 个动作（工具 / 目标 / 耗时 / 成败）
屏幕右下角 HUD（0.2.0）¶
除标题栏外，插件可拉起独立桌面窗口，钉在屏幕右下角、始终置顶；DSH 最小化或被其他窗口遮挡时仍可看到。窗口为无边框、圆角、半透明卡片，不在任务栏占位；可拖动，右键关闭本次窗口。数据与胶囊相同，轮询本机 /agent-status/api/state，端口自动发现。DSH 退出时窗口一并退出；重复启动会做单例检测。
脚本为 desktop-hud.ps1（Windows PowerShell 5.1 + WPF，零依赖），由插件宿主在启动时拉起。若不需要 HUD，设置环境变量：
DSH_AGENT_STATUS_HUD=0
显示字段¶
| 字段 | 含义 |
|---|---|
| 当前动作 | 工具名映射为可读文案（如 ops_bash → 执行命令，edit → 修改文件），并附参数摘要 |
| 第 N 步 | 本轮中第几次模型请求（每批工具调用算一步） |
| 本轮耗时 | 从 turn/start 到当前的实际时间 |
| 待办 x/y | Agent 调用 todo_write 时的清单进度与当前项 |
前两项回答「现在」，后两项回答「做到哪里」。
安装与启用¶
在 Plugin Manager 中安装下列 bundle，或在 profile 目录 ~/.dsh/profiles/<name> 手工等价配置：
github:mdktelmdktel/dsh-agent-status
手工步骤：
- 在
package.json的dependencies中加入"dsh-agent-status": "github:mdktelmdktel/dsh-agent-status" - 在
package.json的dsh.profile.bundles中加入"dsh-agent-status" - 执行
pnpm install，HMR 会激活新 bundle
装完后刷新页面（Ctrl+R）即可看到胶囊。若要关闭插件，在插件配置行设置 disabled: true。
运行要求（来自 package.json）：Node >=18，DSH >=0.1.0。
典型用法¶
安装并刷新后，打开任意 Agent 会话即可在标题栏看到胶囊随工具调用更新。Windows 用户默认还会看到右下角 HUD；关闭 HUD 见上文 DSH_AGENT_STATUS_HUD=0。
悬停胶囊可核对待办与最近动作，适合长时间跑测试、批量改文件时确认 Agent 是否卡在某一工具上。子 Agent 作为独立 session，同一套折叠逻辑会自动为其记账，无需额外配置。
原理与数据流¶
架构可以概括为：宿主折叠会话事件 → 暴露 JSON API → 客户端轮询渲染。
Host Client
session/event ──折叠──> per-session state 1.2s 轮询
turn/start { phase, tool, detail, │
tool/call step, turnMs, todo, ▼
tool/result recent } conversation.session.header.utilities
assistant/message │ → 胶囊组件
turn/end ▼
GET /agent-status/api/state
要点：
- 仅消费持久事件：
turn/start、tool/call、tool/result、assistant/message、turn/end，状态可重建，不依赖 per-agent 订阅 - 内存态、无落盘：会话 15 分钟无事件即回收，最多保留 48 个会话
- 默认零配置；若要改轮询间隔，修改
client.js中的POLL_MS
仓库主要文件：index.js（宿主：事件折叠 + API）、client.js（浏览器：胶囊组件）、cordis.patch.yml、desktop-hud.ps1、locale/{zh,en}.json。
适用场景与已知限制¶
适合：本地长时间跑 Agent、需要不点开会话就确认当前工具与步数；Windows 上需要置顶 HUD 盯进度。
注意：
- 胶囊显示的是宿主内存中的当前状态；若在某一 round 中途才打开页面，「第 N 步」从插件开始观察的位置计数，不会回溯该 round 更早的事件
- 修改宿主侧
index.js不会热更，需重启应用；修改client.js会经 client-hmr 下发 /agent-status/api/state仅监听回环地址、无鉴权，内容为工具名与参数摘要，请勿在不可信网络环境暴露
结尾¶
dsh-agent-status 把 Agent 的「现在在干什么、第几步、跑了多久、待办几项」收进标题栏胶囊，并在 Windows 上可选右下角置顶 HUD，安装 bundle 后刷新即可使用。
