dsh-deepsleep-progress
> 仓库：https://github.com/xyzYaeMiko/dsh-deepsleep-progress ｜ npm：dsh-deepsleep-progress（待发布）
DSH Web 插件：给「会阻塞等待」的工具调用在对话流里加一条 elapsed / budget 进度条。
进度条挂在对应工具卡正下方（同一 Chat 流内的独立一行），工具返回后自动收起。
- 后端没有进度通道（
defineTool()只有一次性的execute()），因此进度条表示的是
本地已等时长 ÷ 超时预算，不是真实完成度。 - 时间基准来自会话日志：
tool/call事件的time（epoch ms），不是插件加载时刻。 - 预算来源（优先级从高到低，
inferSleepBudget默认开启）：
1. 命令里字面sleep N/Start-Sleep …的时长（bash 与 pwsh；多个累加；
echo "sleep 5"这种不作为命中）；
2. 调用参数里的timeout_ms/timeoutMs/timeout（毫秒；比 sleep 更小则作为封顶）；
3.config.tools[工具名]里配置的预算；
4. 都不存在 → 预算未知（不画进度条，只保留左侧图片 + 文字）。 - 完成判定：
tool/result事件到达 → 该行隐藏（tool/result之前会一直显示）。 - 三态：进行中（蓝色填充，随 elapsed/预算前进）、超额（填充到 100% 转橙）、
预算未知（不画进度条，只保留左侧的图片与文字8.0s / —）。
展示
进行中的等待型工具调用会在卡片下方显示 deepsleeping 进度条：鲸鱼图片随填充移动，右侧是 elapsed / budget；工具返回后整行收起。
三态设计示意
进行中 / 超额转橙 / 预算未知（流动条）三种状态，以及「进度 = 本地已等时长 ÷ 预算」的说明：
运行时验证（早期版本截图）
以下截图来自开发期验证（当时标签文案为「已等待」、末端图片尚未加入；三态与白名单行为与当前一致）：
| 运行时：有预算 / 预算未知 / 非等待工具无进度条 | 完成态：进度条收起 |
|---|---|
工具白名单与默认预算
| 工具 | 默认预算 | 说明 |
|---|---|---|
wait_agent |
30000 | 工具默认 timeout_ms: 30000 |
job_output |
60000 | 估算值（waitDefault/waitCap 前端不可见）；显式传 timeout_ms 时以参数为准 |
bash |
null（不确定） |
命令是字面 sleep N 时按 N 走满（可关）；否则只有显式传 timeoutMs 才显示确定进度 |
ask_user_question |
null（不确定） |
隐式无限等待 |
不在 tools 里的工具永远不显示进度条。wait_agent 在没有活跃 teammate 时会
立即返回 noProgress，这时进度条可能来不及出现——这是正常现象
（showDelayMs 默认 350ms，短调用不会闪一下）。
自定义样式（Config）
样式全部来自插件 Config，用户在 profile 的 cordis.patch.yml 里覆盖同一行 id
即可。补丁会整体替换该行的 config；没写的键回落到插件内置默认值，所以可以只写
想改的键：
- id: deepsleep-progress # 覆盖 bundle 里插入的同一行
config:
# 白名单 + 预算（毫秒；null = 预算未知，显示流动条）
tools:
wait_agent: 120000
job_output: 90000
bash: 600000 # Linux/macOS
pwsh: 600000 # Windows
ask_user_question: null
# 外观
accent: 'rgb(77, 107, 254)' # 填充色（设置页用取色器/ RGB / 十六进制编辑）
overrunAccent: 'rgb(240, 169, 58)' # 超出预算的填充色
track: 'rgba(148, 158, 190, 0.22)' # 轨道底色
height: 4 # 轨道高度 px
radius: 2 # 圆角 px
inset: 22 # 距左缩进 px（与工具卡内容对齐）
gapTop: 2 # 与工具卡的间距 px
gapBottom: 6 # 与下一行的间距 px
fontSize: 11 # 文字大小 px
labelColor: 'var(--dsw-alias-label-tertiary)'
clockColor: 'var(--dsw-alias-label-tertiary)'
# 文案与时钟
label: deepsleeping # 前置标签（默认 deepsleeping）；显式空字符串 '' 可隐藏标签
# 末端图片（跟随进度条移动，支持 GIF/APNG 动图）
# headImage: 'https://example.com/head.gif' # 或 data URI；'' 关闭；默认内置测试图
headSize: 18 # 图片边长 px（轨道与行高会跟着变）
clockFormat: '{elapsed} / {budget}' # 支持 {elapsed} {budget} {remaining} {ratio}
unknownBudgetText: '—' # 预算未知时占位
# 行为
enabled: true
inferSleepBudget: true # 命令含字面 sleep N 时按 N 秒走满（启发式）
showDelayMs: 350 # 调用开始后多久才出现（防止短调用闪烁）
tickMs: 100 # 走字间隔
> Config 通过 Web 首页的 index 注入传到浏览器（window.__WAIT_PROGRESS_CONFIG__）。
> 首次安装后插件立即生效（HMR）；之后修改 Config 需要刷新页面才能读到新值。
> 容器与文字默认只用 --dsw-alias-* 主题 token，颜色字面值属于插件 artwork 范畴。
末端图片（可跟随移动，支持动图）
进度条填充的最前沿会挂一个图片，随进度一起移动（像浮标/小人骑在进度头上）：
- 默认：内置一张透明背景的「睡觉鲸鱼 + zzz」图（96px，data URI 内嵌在
client.js，无需联网）。 - 换成自己的图：
headImage填 http(s) URL 或 data URI；GIF / APNG / WebP 会自己动。 - 外链示例：
headImage: 'https://example.com/head.gif'（页面无 CSP 限制，外链需网络可达）。 - 本地 GIF 用 data URI（推荐，离线可用、无外链依赖）：
# Linux
base64 -w0 head.gif # 把输出接在 data:image/gif;base64, 后面
# macOS
base64 -i head.gif
- id: deepsleep-progress
config:
headImage: 'data:image/gif;base64,R0lGODlh...'
大 GIF 会让 profile 的 cordis.patch.yml 变大、每帧解码也有开销，建议 ≤ 200KB、边长 ≤ 128px。
- 位置：图片中心对准填充前沿，并在轨道内做 clamp，半张图不会溢出轨道两端。
- 未知预算：不画进度条，图片和文字（elapsed / —）停在左侧，只走时钟。
- 关闭：headImage: ''（行高会回落到 14px）。
- 替换默认图：把 plugin/assets/head-default.png 换掉并重新生成 data URI 贴到
client.js 的 DEFAULT_HEAD_IMAGE，或直接在 profile 的 patch 里用 headImage 覆盖（更简单）。
图形化设置页
DSH 设置 → 等待进度条（英文界面：Settings → Wait progress）是本插件贡献的独立设置页，
改动立即生效（聊天里正在显示的进度条会同步变），并带实时预览。
页面能力：
- 通用：总开关、前置文案、时钟格式（
{elapsed} {budget} {remaining} {ratio}）、
工具白名单与预算（每行工具名: 毫秒或工具名: unknown）。 - 末端图片：开/关、用内置图、恢复默认图、从本机选择图片（PNG/GIF/WebP，GIF 会动）、
填 URL 或 data URI、大小、未知预算时浮动与单程时长。 - 尺寸与间距：轨道高度、圆角、左缩进、上下间距、文字大小。
- 颜色与背景：填充、超额填充、轨道底色、文案颜色、时钟颜色。每个颜色有系统取色器色块 + RGB 输入框（
rgb(…)/#rrggbb都可；清空恢复默认）。 - 时序：出现延迟、走字间隔。
- 清空本机覆盖：一键回到插件 Config 的默认值。
持久化约定（重要）：
- 页面改动存在当前浏览器的
localStorage（键wait-progress:settings:v1），作为插件
Config 的本机覆盖；cordis.patch.yml里的 Config 仍然是默认值，两者叠加时本机覆盖优先。 - 因此设置不会跨浏览器/跨设备同步；换机器或清浏览器数据后会回到 Config 默认值。
- 图片用 data URI 存在本地存储里，单张限制 2 MB；超限会提示且不保存。
- UI 只写本地覆盖，不改 profile 文件、不写会话事件。
安装
发布到 npm 后（市场收录后可在插件市场一键安装）：
plugin_manager({ action: 'install_bundle', target: 'dsh-deepsleep-progress@0.1.0' })
本地开发（把包目录直接链进 profile）：
plugin_manager({
action: 'install_bundle',
target: '/absolute/path/to/this/repo', # 本仓库根目录（含 package.json）
})
> 市场（dshmarket）只允许安装精选索引 awesome-dsh-plugin
> 里列出的来源；未收录前可用上面的本地目录方式安装。
看返回的 application：applied 即已生效（HMR），restart-required 才需要重启。
实现要点（合规性）
- 挂载点：
conversation.chat.node（keyed slot，key =wait-progress）+ 用
ctx.uiConversation.events.register()注册同名kind的 Conversation Definition。
ChatNodeDataMap是 Harness 明确公开的 merge 扩展面，Chat 层自己负责行位置、分页与
增量装配。 - 不写组件外的 DOM、不 append 到
document.body、不读别的插件 DOM、不 require
Harness Client 包；只require('react')。 - 计时器全部在组件内用
useEffect创建/清理；Definition 注册用ctx.effect()绑定
插件生命周期。 - 数据只从会话事件派生，不追加任何会话事件、不写存储。
已知限制
- 进度 = 已等待 / 预算，不是真实完成度。
job_output的默认等待上限前端不可见，60s 是估算。- 首次安装后如果页面已打开，Config 的 global 要等下一次刷新才注入；插件本身仍会以
内置默认值立即渲染。 - 未做自动化浏览器截图（Web GUI 需要 token，外部脚本拿不到）；视觉需在页面上人工确认。
