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 \x3C 1MB (config/temp files)
• Paths in EXEMPT_PATHS

Execution Protocol

Step 0 — Read config + validate

$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

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

Step 2 — Duplicate check

Before downloading, check if file already exists in DOWNLOAD_ROOT:

$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

3. 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

4. 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}]
继续执行...

Step 4 — After download: verify + log + inform

1. Verify the download landed where expected:

   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:\
   

ew-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:

# 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

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

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

Set LOG_RETENTION_DAYS: 0 to disable cleanup.

Natural Language Commands

Detailed Reference

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