前言¶

在 DeepSeek Harness（DSH）里跑一轮智能体，常会拖很久：装依赖、拉模型、批量改文件。网页端默认只在当前会话里滚动输出；切到别的对话，就看不到刚才那轮走到第几步、还剩多少。社区插件 dsh-agent-progress（维护者 Autodog875）针对的是这块缺口：在网页端加一条可拖动的常驻进度条，并聚合「当前对话」与「所有对话」里正在进行的任务。分类为客户端插件；仓库在 GitHub 上星标为 0，许可证 MIT。

下面介绍它做什么、怎么装、怎么用，以及百分比从哪里来。

这是什么¶

dsh-agent-progress 是给 DSH 网页端用的零依赖纯 JS 插件：一条扁平进度条，无卡通元素、无悬浮球、无表情；没有任务时显示「无任务」，条不会消失。百分比来自真实数据（todo 清单、done/total、任务自报进度、会话历史步数与耗时），不是来回滑动的加载动画。后台命令、子代理等脱离单回合运行的任务也会出现在列表里，含其他对话中的任务。插件只读本地文件与宿主任务注册表，不写宿主状态、不依赖第三方包。

• 目录页：https://www.skillhub.cn/plugins/Autodog875/dsh-agent-progress
• 源码与说明：https://github.com/Autodog875/dsh-agent-progress

核心功能¶

兼容性（README 写明）：DSH 0.2.x 桌面端/网页端；Node.js ≥ 20（CLI）；peer 含 @deepseek-ai/cordis ^4.0.1 等。

安装与启用¶

DSH 生态里常见做法是通过插件市场或把包装进 profile。本插件 README 给出三种方式，任选其一。

方式一：插件市场

在 DSH 网页端打开「插件市场 → 已安装」，安装并启用 dsh-agent-progress，刷新页面即可。

方式二：从 GitHub 源码包安装（README 示例为 tag v0.1.1）

pnpm add "https://github.com/Autodog875/dsh-agent-progress/archive/refs/tags/v0.1.1.tar.gz" --dir <DSH_HOME>/profiles/desktop

装完后在插件市场用开关启用（市场会写 bundles 并热加载），再刷新页面。更新时需把 URL 中的版本号一并改掉。

方式三：本地 link（开发用）

pnpm add "link:D:/path/to/dsh-agent-progress" --dir <DSH_HOME>/profiles/desktop

同样在插件市场打开 dsh-agent-progress。README 提醒：手改 package.json 的 bundles 可能被 .dsh-market/state.json 反推覆盖，应走市场开关。

安装前建议自行查看仓库源码与 MIT 许可证。插件在 DSH 进程权限下读 <DSH_HOME> 本地数据，不联网、不上报；仍以你对本机环境的信任与审计为准。

典型用法¶

网页端自动展示¶

启用后无需额外配置，进度条会按轮询刷新（有任务约 0.8s、空闲约 4s）拉取 agentProgress/state。

用 CLI 写精确进度¶

需要某条任务显示确定百分比时，可用附带的 ap（bin/ap.mjs）：

# 开始一个 500 个文件的任务
node bin/ap.mjs set --key download --label "下载视频" --total 500 --done 0 --unit 个

# 推进（可反复调用，只需给变化的部分）
node bin/ap.mjs set --key download --done 137 --speed 3.2 --eta 120

# 结束 / 失败
node bin/ap.mjs done --key download
node bin/ap.mjs fail --key download --note "sha256 mismatch"

# 长任务保活（每 5 秒续一次心跳，直到超时）
node bin/ap.mjs hold --key download --seconds 600

# 清掉已结束的记录
node bin/ap.mjs clear

# 看记录目录
node bin/ap.mjs dir

记录写在 <DSH_HOME>/agent-progress/<sessionId>/<key>.json，默认镜像到所有会话目录（--local 只写当前会话）。status 为 running / done / failed；running 若 15 秒无心跳会被判中断，结束记录保留 60 秒（界面再留 6 秒）。

字段示例：

{
  "key": "download",
  "label": "下载视频",
  "status": "running",
  "done": 137,
  "total": 500,
  "unit": "个",
  "speed": 3.2,
  "eta": 120,
  "phase": "加密校验",
  "note": "",
  "startedAt": 1792572000000,
  "updatedAt": 1792572060000
}

百分比怎么算¶

按优先级：

1. 记录里 total > 0 → done / total。
2. 会话有 todo 清单 → 已完成条数 / 总条数。
3. 后台任务发布了进度行（如 7/10 files、42%）→ 直接采用。
4. 都没有 → 用该会话历史估算：时间维与步数维取较大值，夹在 1%–99%；回合结束由宿主状态变化收起。后台任务无数据时按已用时间单调上升，封顶 95%，真正结束才 100%。

第 4 种是估算，不是精确值；进度条随真实推进增长，不会空转。

工作原理（简述）¶

网页端 lib/client.js 在槽位 conversation.session.header.actions 注册组件，通过 RPC 调用 agentProgress/state（可带 global: true）。宿主侧 AgentProgressService（lib/index.js）读取 agent-progress 下的 JSON、订阅 ctx.jobs.events、扫描会话投影判断「正在工作」的会话，再合并去重。cordis.patch.yml 以 agent-progress 插入 profile 插件图。

适用场景与注意¶

适合谁：经常在 DSH 网页端开多对话、跑长回合或后台命令，希望一眼看到「当前在干什么、全机还有哪些任务」的开发者。

已知边界（README）：

• 折叠「总进度」为加权平均；多任务并行或新任务刚出现时，数字可能短暂回退；新任务前 2 秒不参与加权。
• ctx.jobs 在插件加载后注册的任务必然可见；加载前已在跑的会靠 jobs.list 补种；注册表进程内，重启后清空。
• 无 todo、无 total、任务也未自报进度时，百分比为估算。
• 诊断文件 <DSH_HOME>/agent-progress/.host-status.json 仅记录本插件状态。

社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系；DSH 侧仍是「一切皆插件」的扩展方式。

结尾¶

dsh-agent-progress 把「当前对话 + 全对话」的任务进度收成一条常驻、可展开的进度条，并用 CLI 支持脚本侧写入确定进度。需要安装步骤与字段说明时，以仓库 README 为准：

• https://www.skillhub.cn/plugins/Autodog875/dsh-agent-progress
• https://github.com/Autodog875/dsh-agent-progress