前言¶
在 DSH 里让智能体拉依赖、克隆仓库时，国内访问 GitHub 等源经常时通时不通。命令挂在那儿几分钟没有输出，智能体往往会一直等到超时或放弃，中间既浪费轮次，也容易误判成「命令写错了」而去改无关参数。
dsh-stall-guard（卡顿守卫）针对的是工具执行层：识别下载类命令，在独立超时预算内没有进展就中止，并把一段结构化、面向智能体的「换源重试」说明写进工具结果。提示来自内置文案或你在面板里配置的占位符模板，不调用任何模型。
这是什么¶
- 仓库： 1250589385/dsh-stall-guard
- 维护者：1250589385
- 分类：工作流（DeepSeek Harness 社区插件目录）
- 许可：MIT
一句话：下载卡住 → 掐掉 → 把换源提示写给智能体（事中处理），与事后解释失败原因的 dsh-turn-doctor、LLM 层换 provider 的 dsh-llm-fallbacks 等插件职责不同。
核心能力¶
下载检测与中止¶
插件监视 shell 里的下载类命令。超过 downloadSeconds（默认 30 秒）仍无完成迹象时中止命令，并在工具结果里写入说明，而不是仅返回干巴巴的 timeout。
提示里通常会包含：
- 卡在什么目标（例如
git repository github.com/...）、阈值与实际耗时。 - 说明更可能是到源的网络问题，而非命令语法错误。
- 按渠道给出的换源候选（镜像列为候选，文档明确未逐一验证可用性）。
- 被中止的
git clone可能留下半成品目录，重试前需删除或换空目录。 - 附上原始命令，便于智能体无需回翻上下文。
覆盖的渠道（节选）¶
| 渠道 | 认得出的命令示例 | 换源提示方向 |
|---|---|---|
| git | git clone、git fetch、git pull、git submodule update 等 |
代理前缀、insteadOf、tarball |
| npm 系 | pnpm install、npm i、yarn add、bun 等 |
--registry https://registry.npmmirror.com |
| pip | pip install、pip download、uv sync |
清华等 PyPI 镜像 |
| cargo / go | cargo install、go get 等 |
常见 crates / Go 代理 |
| http | curl、wget、aria2c 等 |
换主机、gh-proxy、断点续传 |
curl --version、git status、git log 等本地查询不会被当成下载，避免误报。
其他工具类型的超时策略¶
除下载外，插件还对 web_fetch、web_search、读写、执行等场景设默认秒数。下载使用独立预算，不占用普通 exec 的 30 秒。写入类操作超时只提示、不中止，避免写坏用户文件；普通 bash 非下载命令同样不强行中止。
默认阈值（可在配置中调整）：
| 类型 | 默认秒数 | 卡住后 |
|---|---|---|
| 下载 | 30 | 中止 + 换源提示给智能体 |
| web_fetch | 15 | 中止 + 建议改用搜索 |
| web_search | 15 | 中止 + 重试一次 |
| 读取 | 20 | 只提示 |
| 写入 | 30 | 只提示，不中止 |
| 执行 | 30 | 只提示（若判定为下载则按下载处理） |
| 长任务 | 120 | 只提示 |
Token 与模型¶
守卫逻辑、计时、本机轮询 state.json、状态栏文案均不调用模型。进入智能体上下文的主要是卡顿时的换源提示（文档估算约 195–325 token/次，仅在真卡住时产生）。插件不提供「用模型生成提示」选项。
监督员 UI（次要）¶
会话头可显示监督员形象（点、图标或圆鲸鱼 avatar），卡顿时有视觉反馈；可关显示但守卫仍工作。文案来自内置中英文表，切换界面语言时已在屏上的提示会跟着改。外观偏好存浏览器 localStorage，不同步到 Host 配置。
安装与启用¶
在已安装 DSH CLI 的环境下，对指定 profile 添加插件：
dsh plugin --profile <你的profile> add dsh-stall-guard
桌面版常见 profile 可通过环境变量查看：
$env:DSH_PROFILE # 桌面版一般是 desktop
安装后刷新页面即可，默认生效，无需额外配置。
配置¶
在面板中通过监督员形象打开设置，或编辑 $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：下载超时预算；源慢可调大，希望更快换源可调小。watchDownloads: false：关闭下载专项检测，下载命令按普通exec处理（只提示不中止）。overrides：为单个工具单独设秒数。
面板还支持为「下载 / 抓取 / 搜索」三个场景自定义发给智能体的原文，用 {{label}}、{{command}}、{{hints}} 等占位符替换；留空则使用内置文案。自定义预设仍会追加清理半成品目录的提醒。
典型用法与预期行为¶
智能体执行例如：
git clone https://github.com/nodejs/node.git
若 30 秒内未完成，工具结果中会收到类似下面的说明（节选，实际以运行环境为准）：
下载卡住了：git repository github.com/nodejs/node.git 在 30 秒内没完成（已经跑了 30 秒，已中止）。
这条命令被终止了。原因多半是到这个源的网络不通，而不是命令本身写错。
换一个源重试，不要用同一个源继续硬等：
1. 在 GitHub 地址前加代理前缀，例如 https://gh-proxy.com/https://github.com/<owner>/<repo>.git
...
智能体应换源或 tarball 等方式重试，并在重试前处理可能残留的目录。
用户侧状态栏可能出现简短中文提示，例如：「下载 30s 没完成，已中止，换源提示已交给智能体。」
适用场景与注意¶
适合：经常让智能体执行 git clone、pnpm install、pip install、curl 拉取资源，且网络到境外源不稳定的环境。
兼容性（据 README）：需要 tools/execute waterfall 和 webServer；无 webServer 时守卫仍工作，只是没有面板。不注册工具、不占工具名；使用 slot conversation.session.header.utilities。
安装前：插件随当前 DSH 进程权限执行，安装前应自行查看 GitHub 源码 与 MIT 许可证。社区目录 SkillHub 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系。
隐私（据 README）：配置写在本地 ~/.dsh；卡顿记录仅在内存、最多 10 条，重启清空。
结尾¶
dsh-stall-guard 把「下载挂死」从长时间空等变成可操作的换源指令，且全程不消耗模型 token。若你的工作流里智能体频繁拉 GitHub 或包管理器源，可以按上文命令装入对应 profile 试用。
