前言¶

在 DeepSeek Harness（DSH）里跑复杂任务时，Agent 常会连续调用工具、长时间不面向用户说话。你很难判断它是在推进还是在空转，也不知道该不该打断。自己盯着步数或计时器又分散注意力。

dsh-progress-bar 是社区维护者 Kiru-Sama 发布的工作流类 DSH 插件（GitHub 仓库 Kiru-Sama/dsh-progress-bar，目录页 SkillHub）。它在累计步数或墙钟时间达到阈值时，通过宿主规定的通道提醒 Agent 简短汇报；同时在侧栏显示实时计数，在聊天区用横幅标明「上次提醒是什么时候」。插件零 npm 依赖，当前 package 版本为 2.0.0，MIT 许可证。

下面介绍它的定位、能力、安装方式与使用时的硬约束。

这是什么¶

一句话：累计每 N 步或每 N 秒，提醒 Agent 汇报一次进度；侧栏实时显示计数，阈值可在面板里改；附带余额低额提醒与 DeepSeek 官方峰谷时段指示。

提醒不是弹窗，而是通过 tools/post-execute 决策的 additionalContexts 注入一条合成 user 消息——这是模型能真正看见并照做的通道。消息带 source.kind = 'progress-nudge'，不会被当成用户提示词污染历史。

核心功能¶

双触发器与共用计量¶

两个触发器，阈值均可调；任一命中就提醒一次，然后两个计量一起归零，避免步数刚提醒完、几秒后时间阈值又连击刷屏。

侧栏按钮显示「第 N/阈值 步 · 已过秒数」；展开面板有两条进度条、步数/时间阈值输入框、暂停/恢复、恢复默认，以及已提醒与已汇报次数。阈值输入防抖 350ms 后写入运行时配置，输入即生效、不写 profile、重启后回落默认值。

另有 minGapSeconds（默认 45）作两次提醒最小间隔，maxPerTurn（默认 20）作单回合提醒上限。默认不计步的工具包括 todo_write、ask_user_question。

计量与停表规则¶

时钟按墙钟推进，是否走表由 running 决定。暂停（面板暂停按钮）立刻冻结；回合结束（agent/turn-stopping）归零并停表；新用户消息（turn 编号变化）归零并起表；Agent 向用户输出可见文本（agent/assistant-stream 的 text-delta）归零并继续走表——思考（reasoning-delta）、工具调用增量、空白文本不会重置。不需要说话重置时，可在 cordis.patch.yml 将 resetOnSpeech 设为 false。

聊天区横幅¶

提醒对用户侧原本不可见（只有模型能看到注入消息）。插件在输入框上方用横幅补可见性：至少提醒过一次后常驻显示「上次提醒」时间（来自宿主 nudge.at，与服务器时钟一致）；新提醒到达时高亮约 12 秒，显示步数与序号。越过阈值但仍在等当前工具步骤结束时，会显示「已到期 N 秒 · 等当前步骤结束后提醒」，而不是对着越界的进度条干猜。

余额监控¶

插件不自行调用外部 API，而是读取宿主 deepseekAccount 服务的余额（与设置页「账号与余额」同源，不碰你的 API key）。充值与赠送分开显示；默认按两者之和（balance.scope: total）判定是否低于 balance.thresholdCny（默认 1.5 元），避免赠金仍充足时误报。低额时在工具边界投递提醒，余额恢复时也会通知模型「不要再催充值」。未登录或服务不可用时静默，不编造数字。

峰谷时段¶

侧栏常驻显示 DeepSeek 官方 API 计费口径换算后的北京时间高峰/低谷：工作日 09:00–12:00、14:00–18:00 为高峰（界面标签「梁文峰」），其余含周末为低谷半价（「梁文谷」）。中国法定节假日无法离线判断，需在 tariff.holidays 手工填写 YYYY-MM-DD，否则面板会提示仅按周末与时段判断。走第三方中转站时是否适用以对方说明为准，不需要可关闭 tariff.enabled。

增强提醒（自适应退避）¶

侧栏「增强提醒」默认开启：若模型连续多次提醒仍只调工具不对用户说话，会逐步提高步数/时间阈值，并加强文案要求先输出文字再调工具，避免提高频率变成噪音。

安装与启用¶

DSH 插件是「一个包 + 在 profile 里登记两处」，全程不需要安装 npm 依赖。没有 dsh plugin add github:… 一类的一行命令；请按仓库 INSTALL.md 操作。

1、找到 profile 目录（Linux/macOS 默认 ~/.dsh/profiles/desktop；Windows 为 %USERPROFILE%\.dsh\profiles\desktop）。不确定时可在 DSH 设置页「打开配置文件」定位。

2、将插件目录解压到固定位置（例如 ~/Documents/dsh-progress-bar），目录内应直接可见 package.json、index.js、client.js。不要只丢进 profile 的 node_modules 而不登记 bundle。

3、编辑 profile 的 package.json，增加依赖与 bundle：

{
  "dependencies": {
    "dsh-progress-bar": "link:/Users/你/Documents/dsh-progress-bar"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-progress-bar"
      ]
    }
  }
}

link: 路径使用正斜杠。

4、在 profile 的 node_modules 下建立指向插件目录的符号链接（或整目录复制到 node_modules/dsh-progress-bar）：

ln -s /Users/你/Documents/dsh-progress-bar \
      ~/.dsh/profiles/desktop/node_modules/dsh-progress-bar

5、完全退出并重启 DeepSeek Harness（不是只关窗口）。侧栏底部应出现类似 0/10 · 0秒 与峰谷标签；点开展开面板即表示加载成功。

持久化配置改插件包内的 cordis.patch.yml 后需重启；步数、秒数、余额阈值也可在侧栏面板直接改，无需重启。

典型用法¶

默认即可使用：Agent 每累计 10 次工具调用或距上次计量起点 120 秒，会在下一次工具执行结束后的步骤边界收到进度汇报提醒。

需要更长间隔时，在侧栏面板修改步数/时间阈值，或编辑 cordis.patch.yml，例如：

stepThreshold: 15
timeThresholdSeconds: 180
locale: zh
balance:
  enabled: true
  thresholdCny: 1.5
  scope: total
tariff:
  enabled: true
  holidays:
    - "2026-10-01"
    - "2026-10-02"

非法配置在插件激活时会直接抛错，不会静默回退。同一 profile 内不要重复注册两份相同插件配置，否则会冲突 /progress-nudge/api 路由导致插件树启动失败。

适用场景与注意¶

适合：长回合编码、调研、多步工具链任务，希望 Agent 定期用简短文字说明进展，而不是长时间 silent tool loop。

务必知晓的约束：

• 提醒只能在 tools/post-execute 步骤边界投递；长时间运行的单条 shell 命令期间，时间阈值可能早已到期，提醒必须等命令返回。这是宿主 agent 循环机制决定的，不是插件能绕过的。
• 插件以当前 DSH 进程权限运行；安装前应阅读源码与 MIT 许可证，确认可接受其行为（读账户余额、注入合成消息等）。
• INSTALL.md 写明目前主要在 Windows + DSH 桌面版实测；macOS/Linux 理论上可用 symlink 安装，多 profile 场景未充分验证。
• SkillHub 为社区插件目录站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-progress-bar 把「该汇报了」这件事交给可调的步数/时间阈值和宿主认可的注入通道，并用侧栏计数、聊天横幅和 pending 状态把提醒是否发出、是否在等步骤结束说清楚；余额与峰谷指示是同一面板上的附加信息，可按需关闭。

• 目录页：https://www.skillhub.cn/plugins/Kiru-Sama/dsh-progress-bar
• GitHub：https://github.com/Kiru-Sama/dsh-progress-bar