卡顿守卫 · dsh-stall-guard

下载卡住了？自动掐掉，然后告诉智能体「换个源重试」。

GitHub 在国内时通时不通，git clone 挂在那儿几分钟不动，智能体就一直干等。
这个插件盯着下载类命令，超过阈值直接中止，并把一句智能体能读懂的换源提示写进工具结果里。

> 注意：这是给智能体看的，不是给人看的。你看到的 UI（监督员形象）只是顺便。

它到底做了什么

一条命令超时后，智能体收到的不是一句干巴巴的 timeout，而是：

下载卡住了：git repository github.com/nodejs/node.git 在 30 秒内没完成（已经跑了 30 秒，已中止）。

这条命令被终止了。原因多半是到这个源的网络不通，而不是命令本身写错。
换一个源重试，不要用同一个源继续硬等：
1. 在 GitHub 地址前加代理前缀，例如 https://gh-proxy.com/https://github.com//.git
2. 备选前缀：https://ghfast.top/  https://kkgithub.com/  https://gitclone.com/github.com/
3. 不改全局配置的一次性写法：git -c url."https://gh-proxy.com/https://github.com/".insteadOf="https://github.com/" clone /
4. 如果只需要源码不需要提交历史，改用下载 tarball 通常更快：curl -L https://gh-proxy.com/https://codeload.github.com///tar.gz/refs/heads/main

上面这些镜像只是候选，没有验证过能不能用 —— 一个不行就换下一个。

注意：被中止的 git clone 可能留下半成品目录，重试前先删掉它（或在新的空目录里重试）。

卡住的命令：git clone https://github.com/nodejs/node.git

四个关键点，每个都有用：

1. 说明了是「网络到源不通」，不是命令写错 —— 否则智能体会去改命令，白费时间。
2. 给了候选源 —— 但明确说是没验证过的候选。镜像可用性每小时都在变，写一份「已验证可用」的清单只会骗到智能体。
3. 提醒清理半成品 —— 被掐掉的 git clone 会留下半个目录，直接重试会报 already exists 然后卡第二轮。
4. 附上原始命令 —— 智能体不用回翻上下文找它刚才跑的是什么。

覆盖哪些下载

不误报：curl --version、wget --help、git status、git log、ls、node -v 都不会被当成下载。

快速开始

dsh plugin --profile <你的profile> add dsh-stall-guard

不知道 profile 叫什么：

$env:DSH_PROFILE   # 桌面版一般是 desktop

装完刷新页面即可。默认就生效，不用额外配置。

默认超时

每个场景的「是否动手」可独立设置

三个场景（下载 / 抓取 / 搜索）各有两个独立开关：

因此可以组合成任意搭配，例如「下载自动换源、抓取只提示」：

"scenes": {
"download": { "enabled": true, "autoSwitch": true,  "seconds": 30 },
"fetch":    { "enabled": true, "autoSwitch": false, "seconds": 15 },
"search":   { "enabled": true, "autoSwitch": true,  "seconds": 15 }
}

下载有独立预算（scenes.download.seconds，默认 20 秒），不占用 exec 的 30 秒。
原因很直接：等一个死掉的镜像 30 秒和等一个慢编译 30 秒，代价完全不同。

为什么只掐下载，不掐写文件

中止下载是安全的，因为它没有副作用——重新下就是了。写文件不是。

配置

面板里点监督员形象打开，或直接编辑 $DSH_HOME/stall-guard/config.json：

{
"version": 1,
"enabled": true,
"watchDownloads": true,
"downloadSeconds": 20,
"timers": { "fetch": 15, "search": 15, "read": 20, "write": 30, "exec": 30, "long": 120, "other": 30 },
"overrides": { "web_fetch": 45 },
"autoSwitch": true,
"scenes": {
"download": { "enabled": true, "seconds": 30 },
"fetch": { "enabled": true, "seconds": 15 },
"search": { "enabled": true, "seconds": 15 }
},
"supervisor": { "show": true, "display": "avatar" }
}

• downloadSeconds —— 下载预算。GitHub 慢就调大，急着换源就调小。
• watchDownloads: false —— 完全关掉下载检测，下载命令就按 exec 类处理（只提示不中止）。
• overrides —— 给单个工具单独设秒数。

监督员（次要功能）

三种形态，面板里切换：

鱼缸（浮动模式）

把图标设为「浮动」后，它外面会套一个鱼缸：

• 半透明蓝色水体、顶部水面亮线（呼吸）、缓慢左右摆的波光、向下扫的波纹
• 5 颗按比例缩放的上浮水泡
• 卡顿时一圈水花炸开 + 5 滴水珠飞散，播一次就停，不循环闪

全部是 CSS 关键帧，空闲时不跑 JavaScript；系统开启「减少动态效果」时自动停止。
图标本身也有动作：尾鳍闲置慢摆、监视中小幅、卡顿急摆。

提示什么时候消失

一直在监视，但提示不会一直亮着。三条退出路径：

面板可改秒数（0–3600），填 0 = 一直等到你点掉。

显示开关

点图标或点气泡都能打开面板。

图标外观（仅本浏览器）

外观存在 localStorage（键 dsh-stall-guard.appearance.v1），不写进 Host 配置：
这是"这个浏览器上我喜欢多大"的个人偏好，不该同步给所有人，也省掉一次往返。
拖动位置会自动夹在视口内，窗口变小也不会跑到屏幕外。

那句提示来自内置的中英文案表，不调用模型，零 token。

例如：下载 30s 没完成，已中止，换源提示已交给智能体。

文案按工具类型、动作、结果三个维度挑选，中英双语，切换界面语言时已在屏幕上的提示也会跟着改写。

自定义预设（完全不碰模型）

面板里可以直接写你要发给智能体看的原文，插件只做占位符替换，一个模型都不叫。

三个场景各一份，中英各一份：

占位符

写进文本框，发送时自动替换：

面板里每个占位符都是一个可点的按钮，点一下追加到末尾。

例子

最简写法（完全自己控制）：

{{label}} 卡了 {{seconds}} 秒。换源，别重试同一个地址。

想保留内置的镜像清单但换掉措辞：

下载超时了（{{seconds}}s），源：{{host}}
请从下面挑一个换：
{{hints}}

几个行为约定

• 空着 = 用内置文案。不会变成"什么都不发"——清空不会让插件失声。
• "用内置文案"按钮等同于清空；"恢复默认"会把内置全文填进文本框供你改。
• 占位符拼错会原样保留（比如写成 {{labl}}），不会静默变成空字符串——否则你永远发现不了。
• 上限 4000 字，超了截断并提示。
• 预设是唯一的文案来源：这个插件从不调用模型，所以预设就是发给智能体的最终文本。
• 清理半成品的那句提醒会始终追加（即使是自定义预设），因为少了它重试会撞上 already exists。
• 占位符不是代码，${...} 之类原样输出，不执行任何东西。

Token 成本

这个插件在任何情况下都不调用模型。

唯一进入智能体上下文的是换源提示，平均约 240 token/次卡顿。平顺时是 0。

这笔通常还是省钱的——它替代了「智能体干等几分钟后放弃、再乱猜源」。

为什么没有「用模型生成提示」这个选项

之前有过，已删除。理由是它不该存在：
- 提示要传达的事实（哪个工具、跑了多久、阈值多少、做了什么）守卫已经完全知道；
- 模型只能换个说法，不能更准，却每次卡顿都要花约 300 token；
- 而且那句提示是给你看的，不是给智能体看的——花钱美化给人看的一句话，不值。

内置文案已经足够具体，例如：

下载卡住了：git repository github.com/nodejs/node.git 在 30 秒内没完成（已经跑了 30 秒，已中止）。

隐私

• 除了监督模型那一次调用，不联网。
• 卡顿记录只在内存，最多 10 条，重启清空。
• 配置只写在你自己 ~/.dsh 下。

兼容性

• 需要 tools/execute waterfall 和 webServer；没有 webServer 的组合照常工作，只是没面板。
• 不注册任何工具，不占用工具名。
• 只用一个 slot：conversation.session.header.utilities。

和类似插件的区别

开发

node --test test/*.test.mjs        # 182 个用例

许可

MIT，见 LICENSE。素材来源见 PROVENANCE.md。