前言¶

在 DeepSeek Harness（DSH）里跑复杂任务时，Agent 往往会连续调用大量工具，中间很少对用户说话。人只能盯着侧栏转圈，不知道是在推进还是卡在某一步；偶尔想催一句「汇报下进度」，又容易打断模型上下文。社区插件 kiru-progress-bar 把这件事做成可配置的规则：按步数或墙钟时间触发提醒，通过宿主认可的通道注入合成消息，让模型主动做简短汇报，同时在侧栏和聊天区把计数与提醒时刻可视化。

下面介绍插件的定位、能力、安装方式与使用上需要接受的约束。

这是什么¶

kiru-progress-bar 由维护者 Kiru-Sama 发布，归类为 DSH 工作流 类插件（GitHub 约 3 stars）。它解决的核心问题是：长回合中 Agent 缺少节奏感——用户看不见「已经跑了多少步、多久没汇报」，模型也缺少外部时钟来估算耗时。

插件零 npm 依赖，通过 tools/post-execute 的 additionalContexts 注入带 source.kind = 'progress-nudge' 的合成 user 消息，不污染真实用户提示词历史。除进度提醒外，附带余额低额监控（读宿主 deepseekAccount，不碰 API key）与 DeepSeek 官方峰谷计费时段指示。

生态上，DSH 奉行「一切皆插件」；SkillHub 目录页 是社区收录站点，与 DeepSeek / 幻方无官方从属关系。

核心功能¶

双触发器与共用计量¶

两个阈值在 cordis.patch.yml 中可调，侧栏面板里也可输入即生效（防抖约 350ms，改的是运行时覆盖，重启后回到文件默认值）：

任一命中即提醒一次，步数与时间计量一起归零，避免刚按步数提醒完、几秒后又按时间再弹一轮。

另有 minGapSeconds（默认 45）防连击、maxPerTurn（默认 20）限制单回合提醒上限。exclude 默认不计 todo_write、ask_user_question 等工具的步数。

时间与步数怎么计¶

时钟按墙钟走，是否推进由 running 状态决定。暂停（面板按钮）立刻冻结；回合结束（agent/turn-stopping）归零并停表；新回合或 turn 变化时归零并起表；Agent 向用户输出可见文本（text-delta）时归零并继续走表——这样长思考不会一直显示 0/10 · 0秒 却永远打不到时间阈值。不需要说话重置时可将 resetOnSpeech 设为 false。

界面¶

1. 侧栏按钮：实时显示「第 N/阈值 步 · 已过秒数」，暂停时显示「已暂停」；可常驻峰谷标签「梁文峰」（高峰）/「梁文谷」（低谷）。
2. 侧栏面板：两条进度条、步数/时间阈值输入、暂停/恢复/恢复默认、已提醒与已汇报次数、余额与时段说明。
3. 聊天区横幅：至少提醒过一次后，输入框上方常驻「上次提醒」时间（来自宿主 nudge.at）；新提醒高亮约 12 秒后回落。可点 × 隐藏至下次提醒。

提醒本身只有模型能看见；横幅用来确认「提醒是否已发出」。

余额与峰谷¶

余额轮询宿主 deepseekAccount.getBalance，默认按充值 + 赠送总额（balance.scope: total）与阈值 1.5 CNY 比较；低于阈值时在工具边界投递【余额不足】类提醒。未登录或服务不可用时不提醒、不崩溃。

峰谷按 DeepSeek 官方 API 文档：北京时间工作日 09:00–12:00、14:00–18:00 为高峰，其余（含周末）为低谷半价。法定节假日需手工配置 tariff.holidays，否则面板会提示仅按周末与时段判断。

安装与启用¶

DSH 插件是「一个包 + 在 profile 里登记两处」，没有 dsh plugin add 一类的一行命令；完整步骤见仓库 INSTALL.md。概要如下。

0. Profile 目录（默认）：

• Windows：%USERPROFILE%\.dsh\profiles\desktop
• macOS / Linux：~/.dsh/profiles/desktop

1. 将插件目录解压到固定位置（不要直接塞进 profile 的 node_modules，便于日后覆盖更新）。

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

{
  "dependencies": {
    "kiru-progress-bar": "link:/你的路径/kiru-progress-bar"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "kiru-progress-bar"
      ]
    }
  }
}

link: 路径使用正斜杠。

3. 在 profile 的 node_modules/ 下建立指向插件目录的链接，或直接复制整个文件夹为 node_modules/kiru-progress-bar。Linux / macOS 示例：

ln -s /你的路径/kiru-progress-bar \
      ~/.dsh/profiles/desktop/node_modules/kiru-progress-bar

4. 完全退出并重启 DeepSeek Harness（新增 bundle 不会热加载）。

5. 确认：侧栏底部出现类似 ● 0/10 · 0秒 与峰谷标签；展开面板可改阈值。若未出现，按 INSTALL.md 检查 node_modules 链接、bundles 拼写与启动日志中的 did not activate。

安装前请自行阅读 GitHub 源码 与 MIT 许可证；插件以当前 DSH 进程权限运行，与任何社区插件一样需要信任维护者。

典型用法与验证¶

默认配置即可使用：每 10 步或 120 秒提醒 Agent 用中文简短汇报，并附带系统时间、本回合已跑时长等，文案要求「汇报完继续执行」以控制字数。

持久化调参可改插件包内 cordis.patch.yml 后重启，例如：

stepThreshold: 15
timeThresholdSeconds: 180
locale: zh
balance:
  thresholdCny: 2.0
tariff:
  holidays: ["2026-01-01"]

仓库提供零依赖测试（Node 18+）：

node test/run.mjs

界面自测：刷新后侧栏应有进度按钮；触发提醒后聊天区输入框上方应出现横幅。

适用场景与注意¶

适合：长时间多工具调用的编码、调研、批处理任务，希望 Agent 定期对用户可见地同步进度，并顺带关注账户余额与是否处于 API 高峰计费段。

务必接受的硬约束：

1. 提醒只能在步骤边界投递——长命令执行期间模型循环阻塞，无法中途注入；越过时间阈值时会显示「已到期 N 秒 · 等当前步骤结束后提醒」。
2. 余额与峰谷分别依赖 DSH 登录态与官方计费口径；中转站、未配置节假日时的判断以文档说明为准。
3. INSTALL.md 写明目前主要在 Windows + DSH 桌面版实测；macOS / Linux 理论上可用 symlink 安装，未充分验证。
4. 同一 profile 不要重复注册相同插件配置，否则路由冲突可能导致插件树启动失败。

卸载时从 package.json 删掉依赖与 bundle 项，移除 node_modules/kiru-progress-bar 链接或目录，再重启即可。

结尾¶

kiru-progress-bar 把「多久该汇报一次」变成可观测、可配置的规则，并用横幅补上用户侧的可见性；余额与峰谷是同一面板上的附加信息，可按需关闭相关配置项。

• 社区目录：SkillHub - kiru-progress-bar
• 源码与文档：github.com/Kiru-Sama/kiru-progress-bar