下载强制守卫BeiWay1145/dsh-download-guard

dsh-download-guard

把「下载必须走 aria2」从技能里的建议变成运行时的强制。

为什么需要它

aria2-download 技能把规则写在提示词里，而提示词只是建议。实际发生的是：

| | aria2 通道 | 绕过通道 |
|---|---|---|
| 引擎 | aria2-next (Motrix Next) | node 单连接 https |
| 实测速度 | 11.78 MB/s | 0.13 MB/s |
| Motrix 可见 | ✅ | ❌ |
| 断点续传 | ✅ | 部分 |

同一条 4.76 GB 的 Windows 11 镜像，两条路差了 约 90 倍。而 agent 手头只要有一个 download.cjs，就会顺手用它——因为在 shell 层面 node download.cjs 和 aria2-dl.js 长得一模一样，没有任何机制能区分。

本插件把这条规则搬到运行时：拦截工具调用，拒绝并给出正确的 aria2 命令。

工作原理

监听 cordis 的 tools/pre-execute 钩子（waterfall 模式），在工具真正执行之前裁决：

模型请求 pwsh("curl -o x.iso https://...")
↓
tools/pre-execute 钩子触发
↓
识别为下载 → 返回 { kind: 'deny', reason: '' }
↓
工具被拒绝，reason 原样呈现给模型（工具体从未执行）

为什么不用审批钩子

approval/request 在审批策略为 never 时会失效——ApprovalService.decide() 在派发 waterfall 之前就 return "rejected"：

if (this.effectivePolicy(session) === "never") return "rejected";  // ← 在这里返回
const answer = ... this.ctx.waterfall(..., "approval/request", ...)   // ← 永远走不到

而 tools/pre-execute 是独立的 waterfall，没有这个短路，所以任何策略下都有效。

拦截规则

判据来自技能本身：是否需要把字节写到磁盘，而不是 URL 长什么样、文件多大。

| 拦截 | 放行 |
|---|---|
| curl -o F / curl -O / curl --output F | curl https://api.x/status（只输出到 stdout） |
| wget （默认落盘） | wget -O - （显式输出到 stdout） |
| Invoke-WebRequest ... -OutFile F | Invoke-WebRequest https://api.x/status |
| Invoke-RestMethod ... -OutFile F | Invoke-RestMethod https://api.x/data |
| Start-BitsTransfer ... | — |

明确不拦（按设计）：

- pip install / npm install 等包管理器——不在本插件职责内
- git clone——git 自有传输层
- 注释行里的命令（shell 不会执行）
- 非 shell 工具（即使参数里含 curl -o 字样）
- 仅仅是提到某文件名（例如日志里打印 download.cjs）——曾有一条按文件名匹配的规则，因误伤已删除

检测刻意偏向漏判而非误判：拦截一条正常命令是可见的体验倒退，而漏掉一次下载只是现状。

拦截后模型看到什么

BLOCKED by dsh-download-guard: this command downloads a file to disk
(matched: curl-output), and downloads must go through the local aria2 engine
(Motrix Next) so they are multithreaded, resumable and visible in the download manager.

Use instead:
node "$env:USERPROFILE\.dsh\skills\aria2-download\scripts\aria2-dl.js" "" --out=

Options: --dir= for the destination, --header="K: V" for headers,
--no-wait to enqueue and return immediately (then query with --status ).
A blocked command is never partially executed.

Blocked command: curl -o Win11.iso https://.../y.iso

URL 会被自动提取并填进建议命令——被拒绝的一方不需要猜该怎么改。

随包分发的 forwarder

本插件自带 aria2 转发脚本：

scripts/aria2-dl.cjs

拦截提示里给出的路径，就是这个随包副本的绝对路径（由 import.meta.url 在运行期解析）。

为什么必须自带：早期版本的提示指向 ~/.dsh/skills/aria2-download/scripts/aria2-dl.js —— 那是一个机器私有路径。在没有该技能的机器上，守卫会拒绝下载、然后让用户去用一个根本不存在的文件。那比不拦更糟：既打断流程，又不给出路。

该脚本只走 JSON-RPC（不依赖 aria2c.exe），要求本机运行 aria2-next 引擎（Motrix Next 内置）。引擎未启动时会明确报错，而不是静默失败。

环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| ARIA2_RPC_PORT | 16800 | 引擎 RPC 端口 |
| ARIA2_RPC_TIMEOUT_MS | 15000 | RPC 超时 |
| ARIA2_DOWNLOAD_DIR | 用户 Downloads 目录 | 默认落盘目录（不硬编码盘符） |

直接使用

node scripts/aria2-dl.cjs  --out= [--dir=] [--no-wait]
node scripts/aria2-dl.cjs --status
node scripts/aria2-dl.cjs --list

安装

cd ~/.dsh && dsh plugin --profile  add "dsh-download-guard@github:BeiWay1145/dsh-download-guard"

安装后重启 DSH 生效。

已知边界

- 拦不住「命令内部的下载」：python script.py 里用 urllib 下载，钩子看到的是 python script.py，看不到它内部在做什么。彻底收口需要本地代理层，不在本插件范围。
- 拦不住非 DSH 发起的下载：在 DSH 之外的终端里 curl -o 不受影响。
- 依赖宿主提供 tools/pre-execute 钩子（已在 DSH 0.1.5-rc 系列上实测）。

开发

npm install
npm test          # 构建 + 检测器单测 + 真实 ToolRuntime 运行时测试
npm run typecheck

测试分两层：

- tests/detect.test.mjs — 纯函数检测规则（38 项，含大量「必须放行」的反例）
- tests/guard.runtime.mjs — 把构建产物装进真实 cordis + ToolRuntime，验证 deny 真的拦住了工具体

运行时测试会自行在本机寻找已安装的 DSH 树；找不到时跳过而非失败，这样裸克隆仓库也能通过。

许可

MIT