卡顿守卫 1250589385/dsh-stall-guard

卡顿守卫 · 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/<owner>/<repo>.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 <owner>/<repo>
4. 如果只需要源码不需要提交历史，改用下载 tarball 通常更快：curl -L https://gh-proxy.com/https://codeload.github.com/<owner>/<repo>/tar.gz/refs/heads/main

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

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

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

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

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

覆盖哪些下载

| 渠道 | 认得出的命令 | 换源提示 |
| git | git clone git fetch git pull git submodule update git remote add | 代理前缀 / insteadOf / tarball |
| npm | pnpm install|add npm i|install yarn add bun | --registry https://registry.npmmirror.com |
| pip | pip install pip download uv sync | -i https://pypi.tuna.tsinghua.edu.cn/simple |
| cargo | cargo install|fetch|build | tsinghua / ustc crates 镜像 |
| go | go get go mod download | GOPROXY=https://goproxy.cn,direct |
| http | curl wget Invoke-WebRequest aria2c Start-BitsTransfer | 换主机 / gh-proxy / 断点续传 |

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

快速开始

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

不知道 profile 叫什么：

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

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

默认超时

| 类型 | 默认 | 卡住后 |
| 下载 | 30 秒 | 中止 + 给智能体换源提示 |
| 抓取 web_fetch | 15 秒 | 中止 + 改用搜索 |
| 搜索 web_search | 15 秒 | 中止 + 重试一次 |
| 读取 | 20 秒 | 只提示 |
| 写入 | 30 秒 | 只提示，不中止（防写坏文件） |
| 执行 | 30 秒 | 只提示（除非判定为下载） |
| 长任务 | 120 秒 | 只提示 |
| 其他 | 30 秒 | 只提示 |

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

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

| 操作 | 中止后的后果 | 策略 |
| git clone / curl | 留下半个文件/目录，删掉重来就行 | ✅ 中止 |
| write / edit 写文件 | 可能写坏用户的文件 | ❌ 绝不中止 |
| 普通 bash 命令 | 可能跑到一半改了状态 | ❌ 不中止 |

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

配置

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

{
"version": 1,
"enabled": true,
"watchDownloads": true,
"downloadSeconds": 30,
"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 —— 给单个工具单独设秒数。

监督员（次要功能）

三种形态，面板里切换：

| 形态 | 平时 | 卡住时 |
| dot | 状态栏 6px 半透明点 | 变红脉冲 |
| icon | 静止图标 | 弹跳 + 发光 |
| avatar | 闭眼圆鲸鱼 | 变红、尾鳍急摆、水花炸开 |

鱼缸（浮动模式）

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

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

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

提示什么时候消失

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

| 情况 | 结果 |
| 智能体继续下一步 | 立刻消失（主路径，不用你管） |
| 超过设定秒数（默认 30 秒） | 自动消失 |
| 你点气泡或「知道了」 | 稍作停留后消失 |

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

显示开关

| 开关 | 作用 |
| 显示监督员 | 关掉后不再画形象，但守卫照常工作。右下角留一个半透明小点，点它开回面板 |
| 卡顿时显示文字气泡 | 关掉仍会跳动提示有异常，但不显示那句文字 |

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

图标外观（仅本浏览器）

| 项目 | 范围 | 说明 |
| 大小 | 14–64px | 滑块，带数值回显 |
| 透明度 | 20%–100% | 下限 20% 是为了它仍然可见、可点 |
| 位置 | 标题栏 / 浮动 | 浮动模式下可以拖到任何地方，位置会记住 |

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

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

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

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

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

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

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

| 场景 | 什么时候用 |
| 下载 | git clone / pnpm install / curl 超时 |
| 抓取 | web_fetch 超时改搜索 |
| 搜索 | web_search 超时重试 |

占位符

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

| 占位符 | 含义 |
| {{label}} | 在下载什么（如 git repository github.com/a/b.git） |
| {{channel}} | 渠道（git/npm/pip/cargo/go/http） |
| {{target}} | 目标地址或仓库 |
| {{host}} | 主机名 |
| {{command}} | 原始命令（超 240 字会截断） |
| {{seconds}} | 超时阈值 |
| {{elapsed}} | 实际耗时 |
| {{hints}} | 内置的镜像候选清单（最省事的用法） |
| {{query}} / {{sources}} | 搜索词 / 结果数（抓取、搜索场景） |

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

例子

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

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

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

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

几个行为约定

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

Token 成本

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

| 行为 | 成本 |
| 守卫逻辑、计时、下载检测 | 0 |
| 每秒轮询 state.json | 0（本机 127.0.0.1 HTTP，不经模型） |
| 状态栏那句提示 | 0（内置文案表，写死的） |
| 换源提示（发给智能体） | 占上下文 ~195–325 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。

和类似插件的区别

| 插件 | 它做什么 |
| dsh-turn-doctor | 解释已失败的一轮是哪层杀的（事后） |
| dsh-llm-fallbacks | 模型请求失败换 provider（LLM 层） |
| dsh-repeat-tool-breaker | 拦重复调同一工具（防循环） |
| @lolkda/dsh-retry | 改 provider 重试参数 |
| 本插件 | 下载卡住 → 掐掉 → 把换源提示写给智能体（工具层，事中） |

开发

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

许可

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