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#

CommandTypeActioncurl/wget/git clone/model downloadC (safe)Go to Step 2pip install (non-venv)B2Check site-packages locationpip install --user (v5.4)B2+Warn if site-packages on C: — suggest venvnpm install -g / pnpm add -gB1Check prefix + PATH + spacescargo install / go install (v5.4)B3Check binary dir in PATHChange npm prefix / conda envsBRun 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

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): text

   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:

text

[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 codeMeaningAction0OK or WARNProceed1Space too lowBlock, suggest cleanup2 (v5.4)Path unavailableBLOCK — 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:

text

[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: text

   # 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):

text

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  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#

text

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

text

[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#

ScenarioActionFirst setupMust askDaily downloadsDon't ask, just informTarget disk < MIN_FREE_GBMust inform — suggest switchingDOWNLOAD_ROOT drive missing (v5.4)Must inform — BLOCK until fixedDOWNLOAD_ROOT not writable (v5.4)Must inform — BLOCK until fixedC-drive cache foundMust inform — offer to migrateNew disk appearedMay inform — optionalUser 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#

ConditionActionEntry > LOG_RETENTION_DAYS oldAuto-archiveArchive > LOG_ARCHIVE_MAX_MBDelete oldest archiveLog file > 5MBTrigger archive rotation

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

Set LOG_RETENTION_DAYS: 0 to disable cleanup.

---

Natural Language Commands#

User saysAction"下载了什么" / "下载日志" / "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.