前言¶
在 DSH 里跑重构、批量安装依赖或长时间工具链时，主 agent 往往连续调用工具却很久不向对话里写一句说明。你自己在输入框里问「进度怎么样了」，有时要等当前工具返回、有时消息落在上下文中间，模型还可能只回一句「好的，继续」就把计时需求挡掉。下面介绍社区插件 dsh-progress-tick：在任务运行且达到可配置间隔时，于下一次模型请求组装前注入一条 notice，要求主 agent 说明正在做什么、已完成什么、下一步是什么；并可选附带最近动作摘要、指数退避、卡住检测，以及 /progress 按需催报。
这是什么¶
dsh-progress-tick（维护者 ityyq777）归类为 DSH 社区目录中的工作流插件。一句话定位：Tell the DSH main agent to report progress every N minutes——仅针对主 agent（子 agent / 委派深度大于 0 的不催），监听 run/stop 与输出活动，在静默达到间隔后于 agent/pre-step 追加提醒，而不是依赖你在任意时刻插话。
为什么比手动问进度更稳¶
手动插话与插件提醒的差别，资料里归纳为四点：注入时机（插件只在请求组装前一刻注入）、请求内位置（提醒通常是最后一条）、次数（未检测到「有效汇报」会按退避继续催）、内容（带已运行时长、当前工具耗时、上次汇报时间等状态）。提醒形态为 notice，source.kind = 'progress-tick'，文案偏待办指令。
若某一步上下文里已有用户刚发的消息（source.kind === 'user'），插件会主动沉默并重锚计时器，避免和用户插话打架。代价是：你插话后模型若继续干活而不回答，自动提醒不会立刻补刀；需要即时汇报可用 /progress，或在工具刚返回、回复正在生成时再问。
核心功能¶
计时与「算已汇报」¶
| 情况 | 行为 |
|---|---|
| 运行开始（idle → running） | 从这里开始计时，本轮计数重置 |
| 间隔内无有效汇报 | 下一次请求前追加一条 notice |
| 模型给出有效汇报 | 计时重锚 |
| 运行结束前未到期 | 计时重置；下次 run 从零开始 |
| 运行中用户发消息 | 该 step 不催，计时重锚 |
| 子 agent | 不催 |
有效汇报需满足其一：自上次汇报以来可见文本不少于 minReportChars（默认 40），或包含 reportMarkers 中的关键词（如 完成、发现、下一步 等，可配置）。
escalation¶
- 退避：同一 turn 内提醒次数超过
backoffAfter（默认 3）后，有效间隔乘以backoffFactor（默认 2，上限 8 倍）。 - 卡住检测：同一工具与目标连续重复
stuckThreshold（默认 3）次时，文案从「请汇报进度」转为「是否卡住、已尝试什么」。 - 详细档：每
detailEvery次提醒可附带最近动作摘要（工具名、目标、失败标记）及子 agent 状态。
设置页¶
重启 dsh web 后，设置 → 进度播报 出现独立分区（官方 settings.section 槽）。表单覆盖全部配置项；保存经 remote.settings.mutate() 写入并对当前进程生效，无需重启；恢复默认 清除用户覆盖。语言字段支持 auto / zh / en。
常用配置默认值（完整表见仓库 README）：
| 键 | 默认 | 含义 |
|---|---|---|
enabled |
true |
总开关 |
intervalMinutes |
5 |
提醒间隔（分钟） |
minReportChars |
40 |
计为汇报的最小可见字符数 |
commandEnabled |
true |
是否注册 /progress |
stuckDetection |
true |
卡住检测 |
locale |
auto |
提醒文案语言 |
任务驾驶舱（Web）¶
0.5.0 起左侧栏一级入口「进度播报」；0.5.1 起单会话详情在会话视图的「进度」标签页（在「对话」「轨迹」之后）。能力包括：会话列表（时长、提醒次数、最近动作、倒计时、疑似卡住）、搜索与筛选、每次提醒的时间与原因、最近汇报正文条数可配、当前工具耗时走表、子 agent 树、立即催一次、本会话静音（仅挡自动提醒，/progress 与手动催仍有效，重启后静音清空）。
数据通道：GET /api/progress-tick/status、GET /api/progress-tick/events（SSE）、POST /api/progress-tick/nudge、POST /api/progress-tick/mute。页面优先 SSE，断线时约 5 秒轮询兜底。上述路由绕过 DSH 默认 /api 认证桥，插件自行限制为回环访问并带写操作校验与限流。
/progress 与状态文件¶
在会话中输入 /progress，可在不等待定时器的情况下排队一次提醒，于下一次 step 前注入（长工具运行期间仍适用）。
开启 statusFile（默认 true）时，每会话写入 ~/.dsh/progress-tick/status/<sessionId>.json（目录可由 statusDir 覆盖）。动作目标从工具参数解析并截断至 160 字符，完整参数（可能含凭证）不会落盘。
安装与启用¶
三种入口共用同一安装 spec。安装前请自行阅读仓库源码与 MIT 许可证；插件以当前 dsh 进程权限运行。
GUI¶
左上角 插件 → 安装，在「包名或地址」粘贴：
github:ityyq777/dsh-progress-tick
命令行¶
跟随 main 最新提交：
dsh plugin --profile web add github:ityyq777/dsh-progress-tick
锁定版本（tag，资料示例）：
dsh plugin --profile web add github:ityyq777/dsh-progress-tick#v0.5.6
或使用 Release 源码包：
dsh plugin --profile web add https://github.com/ityyq777/dsh-progress-tick/archive/refs/tags/v0.5.6.tar.gz
安装器解析包内 dsh.bundle.patch 后写入 profile 的 dsh.profile.bundles 并启用，重启 dsh web 后生效。package.json 声明 DSH 引擎 >=0.2.0-rc.1 <0.3.0。
本地开发可 dsh plugin --profile web add /absolute/path/to/dsh-progress-tick；npm 名 dsh-progress-tick 在发布后可用 dsh plugin --profile web add dsh-progress-tick。
典型用法¶
- 安装并重启
dsh web，在 设置 → 进度播报 将intervalMinutes设为符合任务长度的值（默认 5 分钟）。 - 让主 agent 执行预期会长时间静默的工具链；到期后应看到带进度要求的 notice，agent 回复需满足
minReportChars或关键词才算重置计时。 - 工具仍在跑、不想等间隔时，在同一会话输入
/progress。 - 需要总览多会话时，打开左侧 进度播报，对某会话使用「立即催一次」或查看「进度」标签页中的提醒历史与最近汇报正文。
适用场景与注意¶
适合：本地或 Web 上长时间单会话任务、希望主 agent 主动说明阶段进展而非完全静默、需要驾驶舱观察多会话提醒与疑似卡住。
注意：仅主 agent；子 agent 树只在提醒摘要或驾驶舱中展示，不会被插件直接催。用户刚发言的那一步不会自动催。社区目录 SkillHub 插件页 与 GitHub 为独立信息源，与 DeepSeek / 幻方无官方从属关系；DSH 生态主张「一切皆插件」，安装第三方包前请核对源码与权限边界。
结尾¶
dsh-progress-tick 把「定期进度播报」做成可配置的工作流：pre-step 注入、有效汇报判定、退避与卡住检测，再配合设置页、驾驶舱与 /progress。查阅详情与 issue：
