---
name: download-guard
slug: download-guard
version: "5.4.0"
description: >
  AI Agent download guard (Windows only). Auto-activates on: download, install, git clone,
  pip install, npm install -g, pnpm add -g, bun install -g, conda install,
  cargo install, go install, uv pip install, docker pull, ollama pull,
  huggingface-cli download, winget/choco/scoop install, curl/wget.
  Checks disk space, validates path availability, logs every download,
  prevents C-drive fill-up and broken-path fallback.
  Use when: user runs pip install, npm install -g, git clone, docker pull, ollama pull, cargo install, go install, or any download/install command. Also use when user asks "where did it download", "disk space", "download log", "scan cache", "migrate cache".
  NOT for: managing already-installed applications, uninstalling programs, or non-download file operations.
  Say "download guard" / "download guard status" / "where did it download" / "disk space" / "download guard version".
  当用户说"下载/安装/克隆/拉取模型/pull镜像/磁盘空间/下载到哪/下载版本"时自动激活。
author: nihaoljx
license: MIT-0
triggers:
  - download guard
  - download guard status
  - where did it download
  - disk space
  - download guard version
agent_created: true
tags: [download, disk-space, logging, guard, path-safety, windows]
platform: windows
metadata:
  openclaw:
    primaryEnv: ""
    requires:
      bins:
        - powershell
---

# Download Guard v5.4

> 下载位置透明 · 文件好管理 · 减少 C 盘垃圾 · 路径不可用时宁可阻止也不走 C 盘

**Platform**: Windows (PowerShell 5.1+)

---

## Core Rules

1. **Transparent**: Every download tells user where file goes and if environment is healthy
2. **Manageable**: Logs auto-clean; path changes have rules, not random questions
3. **No garbage**: C-drive guard, cache scanning, log auto-archive
4. **No silent fallback**: If DOWNLOAD_ROOT is unavailable, BLOCK — never silently fall back to C:

---

## Trigger Rules

### MUST trigger

- `curl / wget / Invoke-WebRequest / requests.get / urllib.request`
- `npm install -g` (NOT local `npm install` without -g)
- `pnpm add -g` (v5.4)
- `bun install -g` (v5.4)
- `pip install` (NOT inside active venv — check `VIRTUAL_ENV` env var first)
- `uv pip install` (v5.4 — same venv rule applies)
- `conda install / conda create / conda env update`
- `cargo install` (v5.4 — installs to `~/.cargo/bin`)
- `go install` (v5.4 — installs to `$GOPATH/bin`)
- `git clone`
- `huggingface-cli download / modelscope download / ollama pull`
- `docker pull`
- `winget install / choco install / scoop install`

### DO NOT trigger

- Writing source code files (.py .js .ts .json .md etc.)
- Read/search/grep operations
- Local `npm install` (writes to node_modules in cwd)
- `pip install -e .` (editable install)
- Files < 1MB (config/temp files)
- Paths in `EXEMPT_PATHS`

---

## Execution Protocol

### Step 0 — Read config + validate

```powershell
$configPath = "$env:USERPROFILE\.workbuddy\skills\download-guard\config.md"
$content = Get-Content $configPath -Raw -ErrorAction SilentlyContinue
$setupDone  = $content -match "SETUP_DONE:\s*true"
$downloadRoot = if ($content -match "DOWNLOAD_ROOT:\s*(.+)") { $Matches[1].Trim() } else { "" }
```

If `SETUP_DONE != true` or `DOWNLOAD_ROOT` empty → run **First-time Setup**.

**Config Integrity Check** (v5.4): After reading, verify:
- `DOWNLOAD_ROOT` value is non-empty and starts with a drive letter (e.g. `D:\`, `F:\`)
- `SETUP_DONE` is either `true` or `false` (not corrupted)
- If config appears broken → warn user and ask to re-configure

### Step 1 — Path type check

| Command | Type | Action |
|---------|------|--------|
| curl/wget/git clone/model download | C (safe) | Go to Step 2 |
| `pip install` (non-venv) | B2 | Check site-packages location |
| `pip install --user` (v5.4) | B2+ | Warn if site-packages on C: — suggest venv |
| `npm install -g` / `pnpm add -g` | B1 | Check prefix + PATH + spaces |
| `cargo install` / `go install` (v5.4) | B3 | Check binary dir in PATH |
| Change npm prefix / conda envs | B | Run PATH linkage check |

> Type A = cache (safe to move), Type B = install dir (must sync PATH), Type C = file storage (safe).
> Details: see [reference.md](reference.md)

### Step 2 — Duplicate check

Before downloading, check if file already exists in `DOWNLOAD_ROOT`:

```powershell
$today = Get-Date -Format "yyyy-MM-dd"
$existing = Get-ChildItem "$downloadRoot\$today" -Recurse -Filter "*$FileNamePart*" -ErrorAction SilentlyContinue
```

If found → inform user: `"⚠️ Similar file already exists: {path} ({size}). Download again? [y/N]"`

### Step 3 — Path availability + size awareness + space check

1. **Determine download subdirectory** (default structure):
   ```
   DOWNLOAD_ROOT\YYYY-MM-DD\{sanitized-task-name}\
   ```
   Rules for `{sanitized-task-name}`:
   - Use the task description or package name, lowercase, spaces → hyphens
   - Max 40 chars, no special characters
   - If no clear task name, use `general`
   - Example: `F:\AI-Downloads\2026-05-26\install-pandas\`

2. **Run `scripts/check-space.ps1`** — now includes:
   - Drive existence check (if drive missing → **exit 2 = BLOCK**, no C: fallback)
   - Path writability test (creates + deletes temp file)
   - Auto-creates download directory if not exists
   - If any check fails → **BLOCK** with clear error message

2. **If download size is known** (model cards, package metadata, etc.):
   - Compare against target disk free space
   - If size > 50% of free space → warn: `"This download ({X}GB) will use {Y}% of available space on {drive}:"`
   - If size > free space → BLOCK

3. **Output to user**:

```
[DOWNLOAD GUARD] 准备下载
文件     : {filename}
大小     : {known size / unknown}
写入至   : {DOWNLOAD_ROOT}\{YYYY-MM-DD}\{task-name}\
目标盘   : {X} GB 可用  [{OK/WARN/BLOCK}]
C 盘     : {X} GB 可用  [{OK/WARN}]
路径可用 : [{OK / DRIVE_MISSING / NOT_WRITABLE}]
继续执行...
```

| check-space exit code | Meaning | Action |
|----------------------|---------|--------|
| 0 | OK or WARN | Proceed |
| 1 | Space too low | Block, suggest cleanup |
| 2 (v5.4) | Path unavailable | **BLOCK — do NOT fall back to C:** |

### Step 4 — After download: verify + log + inform

1. **Verify** the download landed where expected:
   ```powershell
   Test-Path "{expected_path}"
   (Get-Item "{expected_path}").Length
   ```

2. Run `scripts/log-download.ps1` (includes auto-cleanup)

3. **Output to user**:
```
[DOWNLOAD GUARD] 完成
文件   : {filename}  ({size})
位置   : {full path}
已记录 : download-log.md
```

If verification fails → warn: `"⚠️ Downloaded file not found at expected path. Please check manually."`

---

## Config Protection (v5.4)

When the Agent writes to `config.md`, it MUST:

1. **Read-back verify**: After writing, re-read the file and confirm `DOWNLOAD_ROOT` and `SETUP_DONE` are present and valid
2. **No partial writes**: Write the complete file in one operation, never append/patch key fields
3. **Backup on change**: Before changing `DOWNLOAD_ROOT`, keep the previous value as a comment:
   ```
   # PREVIOUS: DOWNLOAD_ROOT: E:\old-path
   DOWNLOAD_ROOT: F:\new-path
   ```
4. **If config is corrupted**: The Agent should detect it (missing required fields, empty DOWNLOAD_ROOT, SETUP_DONE neither true nor false) and ask the user to re-configure

---

## First-time Setup (SETUP_DONE: false)

### Step 0 — Scan disks + recommend best option

```powershell
Get-PSDrive -PSProvider FileSystem |
  Where-Object { $_.Free -gt 0 } |
  Sort-Object Free -Descending |
  ForEach-Object {
    $tag = if ($_.Name -eq "C") { " [SYSTEM - NOT recommended]" } else { "" }
    "  {0}:  {1} GB free{2}" -f $_.Name, [math]::Round($_.Free/1GB,1), $tag
  }
```

Show user with **recommended default** (largest non-C drive):

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Download Guard · 首次配置
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

磁盘扫描结果：

  F:  132 GB 可用  ← 推荐（空间最大）
  E:   97 GB 可用
  D:   39 GB 可用
  C:   58 GB 可用  [系统盘 - 不推荐]

推荐：F:\AI-Downloads
确认？或输入其他路径：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Step 1 — User confirms, Agent writes config

1. Normalize input (drive letter only → `{letter}:\AI-Downloads`, full path → use as-is)
2. **Verify the path is writable** before accepting (v5.4)
3. Create directory if not exists
4. Write config.md: `SETUP_DONE: false` → `true`, `DOWNLOAD_ROOT:` → user choice
5. **Read-back verify** the config was written correctly (v5.4)
6. Run `scan-tool-cache.ps1`
7. If C-drive caches found, ask to migrate

### Step 2 — Output status card

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Download Guard · 环境就绪
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  下载目录 : {DOWNLOAD_ROOT}
  可用空间 : {X} GB  [{OK/WARN}]
  路径可写 : {YES/NO}
  C 盘     : {X} GB  [{OK/WARN}]

  npm cache  : {path}  [{OK/WARN}]
  pip cache  : {path}  [{OK/WARN}]
  npm prefix : {path}  [IN PATH: {YES/NO}]

  日志 : ~/.workbuddy/download-log.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
如有 [WARN]，说"帮我修复"即可。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Transparency Rules

### Per-download — Before: inform
### Per-download — After: verify + log + inform
(See Step 2-4 in Execution Protocol above)

### Daily first trigger — environment report

On the first trigger of each day, output an environment report. Implementation:

```powershell
# Track last report date in a temp file
$lastReportFile = "$env:TEMP\download-guard-last-report.txt"
$today = Get-Date -Format "yyyy-MM-dd"
$lastReport = if (Test-Path $lastReportFile) { Get-Content $lastReportFile -Raw } else { "" }
if ($lastReport -ne $today) {
    # This is the first trigger today — show environment report
    Set-Content -Path $lastReportFile -Value $today -Force
    # ... output report ...
}
```

Report format:

```
[DOWNLOAD GUARD] 今日首次 · 环境快报
下载目录   : {DOWNLOAD_ROOT}  ({X} GB 可用)
路径可用   : {OK / DRIVE_MISSING / NOT_WRITABLE}
C 盘       : {X} GB 可用  [{OK/WARN}]
工具缓存   : {all OK / N items on C: [WARN]}
日志条数   : {N} 条
```

If path unavailable → **immediately ask user to update config or reconnect drive**.

---

## Path Ask Strategy

| Scenario | Action |
|----------|--------|
| First setup | **Must ask** |
| Daily downloads | **Don't ask**, just inform |
| Target disk < MIN_FREE_GB | **Must inform** — suggest switching |
| DOWNLOAD_ROOT drive missing (v5.4) | **Must inform** — BLOCK until fixed |
| DOWNLOAD_ROOT not writable (v5.4) | **Must inform** — BLOCK until fixed |
| C-drive cache found | **Must inform** — offer to migrate |
| New disk appeared | **May inform** — optional |
| User asks "where to?" | **Answer** — show current config |

**Rule**: Only prompt on environment changes. Daily ops = inform only.
**Rule** (v5.4): Path unavailable = always BLOCK, never silently fall back to C:.

---

## Log Cleanup Rules

| Condition | Action |
|-----------|--------|
| Entry > `LOG_RETENTION_DAYS` old | Auto-archive |
| Archive > `LOG_ARCHIVE_MAX_MB` | Delete oldest archive |
| Log file > 5MB | Trigger archive rotation |

Archive naming: `~/.workbuddy/download-log-archive-{YYYY-MM-DD}.md`

Set `LOG_RETENTION_DAYS: 0` to disable cleanup.

---

## Natural Language Commands

| User says | Action |
|-----------|--------|
| "下载了什么" / "下载日志" / "download log" | Show last 20 entries |
| "缓存在哪" / "扫描缓存" / "scan cache" | Run `scan-tool-cache.ps1` |
| "迁移缓存" / "migrate cache" | Run `migrate-cache.ps1` |
| "磁盘空间" / "disk space" | Run `check-space.ps1` |
| "刚才下的在哪" / "where's my download" | Show last log entry path |
| "下载到哪" / "根目录在哪" | Show DOWNLOAD_ROOT |
| "npm 用不了" / "command not found" | Check npm prefix in PATH |
| "帮我修复" / "fix warnings" | Auto-fix all [WARN] items |
| "修改下载目录" / "change download dir" | Update config.md DOWNLOAD_ROOT |
| "清理日志" / "clean log" | Trigger log archive cleanup |
| "检查路径" / "check path" (v5.4) | Verify DOWNLOAD_ROOT exists, writable, disk healthy |
| "重置配置" / "reset config" (v5.4) | Set SETUP_DONE: false, re-run setup |
| "download guard version" / "下载版本" (v5.4) | Show current version: 5.4.0 |
| "卸载 download guard" / "uninstall download guard" | Show cleanup instructions (log files, archives, config) |

---

## Detailed Reference

For full details on path types, PATH fix templates, config params, scripts, and known limitations, see [reference.md](reference.md).