前言¶
DeepSeek Harness（DSH）的对话流里，当调用 wait_agent、job_output、bash 这类会阻塞等待的工具时，对话框会长时间保持空白，用户无法知道当前在做什么。这种「黑盒等待」容易让使用者产生焦虑，也缺少对超时风险的直观感知。
dsh-deepsleep-progress 是 DSH Web 插件，在阻塞工具卡正下方挂一条 elapsed / budget 进度条，随时间推进更新进度，并在预算用尽或返回结果时自动收起。进度条仅反映本地等待时长与超时预算的比值，不是真实完成度，但能让等待过程变得可见、可控。
这是什么¶
dsh-deepsleep-progress 是一个客户端插件，由维护者 xyzYaeMiko 开发，分类为「客户端」。它为 DSH Web 中会阻塞的工具调用提供可视化的进度条，并附带一个图形化的设置页面，允许用户自定义样式、预算、末端图片与时钟格式。
核心价值是：在 DSH 对话流中为长时间等待的操作提供「可见的等待」，让开发者与使用者都能更清晰地掌握当前任务进度与超时风险。
核心功能¶
进度条显示¶
插件在对话流中，为符合条件的工具调用（wait_agent、job_output、bash、ask_user_question）在工具卡正下方插入一行进度条。该行在 tool/result 事件到达前一直显示，返回后自动隐藏。
进度条内容为 {elapsed} / {budget}，其中 elapsed 来自会话日志中 tool/call 事件的 time（epoch ms），时间基准是工具调用开始时刻，不是插件加载时刻。
预算来源¶
预算（budget）有四个优先级，按顺序判断：
- 命令字面量：命令中包含
sleep N（bash）或Start-Sleep …（pwsh）的时长，多个累加。echo "sleep 5"这种不作为命中。 - 调用参数：参数中的
timeout_ms、timeoutMs或timeout（毫秒）。如果参数值小于预算，则作为封顶。 - 配置项：
config.tools[工具名]里配置的预算（毫秒）。 - 都不存在 → 预算未知，不画进度条，只保留左侧图片与文字
elapsed / —。
默认预算（白名单）：
| 工具 | 默认预算 | 说明 |
|---|---|---|
wait_agent |
30000 | 工具默认 timeout_ms: 30000 |
job_output |
60000 | 估算值；显式传 timeout_ms 时以参数为准 |
bash |
null |
命令字面 sleep N 时按 N 走满；否则只有显式传 timeoutMs 才显示确定进度 |
ask_user_question |
null |
隐式无限等待 |
不在白名单里的工具永远不显示进度条。
三态显示¶
进度条根据预算与 elapsed 的关系呈现三种状态：
- 进行中：蓝色填充，随 elapsed/预算前进。
- 超额：填充到 100% 转为橙色。
- 预算未知：不画进度条，只保留左侧图片与文字（如
8.0s / —）。
末端图片¶
进度条填充的最前沿会挂一个图片，随进度一起移动（类似浮标/小人骑在进度头上）。
- 默认：内置一张透明背景的「睡觉鲸鱼 + zzz」图（96px），data URI 嵌入
client.js，无需联网。 - 自定义：通过配置
headImage指定 http(s) URL 或 data URI。GIF / APNG / WebP 会自动播放动画。 - 位置：图片中心对准填充前沿，并在轨道内 clamp，半张图不会溢出轨道两端。
- 未知预算：不画进度条，图片和文字停在左侧，只走时钟。
- 关闭：
headImage: ''，行高回落到 14px。
建议图片大小 ≤ 200KB、边长 ≤ 128px，避免影响存储与解码性能。
图形化设置页¶
DSH 设置 → 等待进度条（英文界面：Settings → Wait progress）是本插件贡献的独立设置页。页面改动立即生效，当前显示的进度条会同步更新。
设置页能力包括：
- 通用：总开关、前置文案（默认
deepsleeping）、时钟格式（{elapsed} {budget} {remaining} {ratio}）、工具白名单与预算。 - 末端图片：开关、内置图、恢复默认图、从本机选择图片（PNG/GIF/WebP）、URL 或 data URI、大小、未知预算时的显示。
- 尺寸与间距：轨道高度、圆角、左缩进、上下间距、文字大小。
- 颜色与背景：填充色、超额填充色、轨道底色、文案颜色、时钟颜色。每个颜色有系统取色器 + RGB / 十六进制输入框。
- 时序：出现延迟（默认 350ms）、走字间隔（默认 100ms）。
- 清空本机覆盖：一键回到插件 Config 的默认值。
持久化约定：页面改动存在当前浏览器的 localStorage（键 wait-progress:settings:v1），作为插件 Config 的本机覆盖。cordis.patch.yml 里的 Config 仍是默认值，两者叠加时本机覆盖优先。因此设置不会跨浏览器/跨设备同步；换机器或清浏览器数据后会回到 Config 默认值。
安装与启用¶
npm 安装（市场收录后可用）¶
plugin_manager({ action: 'install_bundle', target: 'dsh-deepsleep-progress@0.1.0' })
本地开发安装¶
plugin_manager({
action: 'install_bundle',
target: '/absolute/path/to/this/repo',
})
安装后查看返回的 application：applied 即已生效（HMR），restart-required 才需要重启。
首次安装后插件立即生效（HMR）；之后修改 Config 需要刷新页面才能读到新值。
典型用法¶
在 profile 的 cordis.patch.yml 中配置插件，覆盖默认预算与样式：
- id: deepsleep-progress
config:
# 白名单 + 预算（毫秒；null = 预算未知）
tools:
wait_agent: 120000
job_output: 90000
bash: 600000
pwsh: 600000
ask_user_question: null
# 外观
accent: 'rgb(77, 107, 254)'
overrunAccent: 'rgb(240, 169, 58)'
track: 'rgba(148, 158, 190, 0.22)'
height: 4
radius: 2
inset: 22
gapTop: 2
gapBottom: 6
fontSize: 11
label: deepsleeping
# 末端图片
headSize: 18
clockFormat: '{elapsed} / {budget}'
unknownBudgetText: '—'
# 行为
enabled: true
inferSleepBudget: true
showDelayMs: 350
tickMs: 100
在 DSH 设置 → 等待进度条里，通过图形化界面调整上述配置，或从本机选择图片作为末端浮标。
适用场景与注意¶
适合需要调用长时间运行工具（如等待外部服务响应、执行耗时 bash 命令、轮询 job_output）的场景。进度条能帮助用户感知等待时长与超时风险，减少对「卡死」的误判。
注意事项：
- 进度条表示的是「本地等待时长 ÷ 超时预算」，不是真实任务完成度。预算未知时不会画进度条。
job_output的默认 60s 上限是估算值，前端不可见；显式传timeout_ms时以参数为准。- 首次安装后，如果页面已打开，Config 的 global 要等刷新才注入；插件本身仍会以内置默认值立即渲染。
- 设置页的改动仅保存在当前浏览器的 localStorage，不跨设备同步；图片用 data URI 存在本地，单张限制 2MB。
- 容器与文字默认使用主题 token（
--dsw-alias-*），颜色字面值属于插件 artwork 范畴。
插件以当前 DSH 进程权限运行，安装前应检查源码与许可证（MIT）。
短结尾¶
dsh-deepsleep-progress 为 DSH 对话流中的等待操作提供可视化的 elapsed / budget 进度条与图形化设置页，适合需要处理长时间工具调用的场景。更多细节与源码可访问插件目录页与 GitHub 仓库。
