Download Guard v5.4

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

Platform: Windows (PowerShell 5.1+)

核心规则

1. 透明性：每次下载都会告知用户文件将保存的位置，以及当前环境是否健康
2. 可管理性：日志自动清理；路径变更有明确规则，不会随机询问
3. 无垃圾：C 盘保护、缓存扫描、日志自动归档
4. 无静默回退：若 DOWNLOAD_ROOT 不可用，则阻止执行 —— 永不静默降级到 C 盘

触发规则

必须触发

• curl / wget / Invoke-WebRequest / requests.get / urllib.request
• npm install -g（非本地 npm install，不带 -g）
• pnpm add -g（v5.4）
• bun install -g（v5.4）
• pip install（不在活跃虚拟环境中 —— 首先检查 VIRTUAL_ENV 环境变量）
• uv pip install（v5.4 —— 同样适用虚拟环境规则）
• conda install / conda create / conda env update
• cargo install（v5.4 —— 安装至 ~/.cargo/bin）
• go install（v5.4 —— 安装至 $GOPATH/bin）
• git clone
• huggingface-cli download / modelscope download / ollama pull
• docker pull
• winget install / choco install / scoop install

不应触发

• 编写源代码文件（.py .js .ts .json .md 等）
• 读取/搜索/查找操作（如 grep）
• 本地 npm install（写入当前目录的 node_modules）
• pip install -e .（可编辑安装）
• 文件大小小于 1MB（配置文件或临时文件）
• 路径位于 EXEMPT_PATHS 列表中

执行流程

步骤 0 — 读取配置并验证

$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 { "" }

如果 SETUP_DONE != true 或 DOWNLOAD_ROOT 为空 → 执行 首次设置。

配置完整性检查（v5.4）：读取后需验证：

• DOWNLOAD_ROOT 值非空且以盘符开头（如 D:\、F:\）
• SETUP_DONE 为 true 或 false（不能损坏）
• 若配置疑似损坏 → 提醒用户并要求重新配置

步骤 1 — 路径类型判断

类型 A = 缓存（可移动），类型 B = 安装目录（必须同步 PATH），类型 C = 文件存储（安全）。

详细说明请参见 [reference.md](reference.md)

步骤 2 — 重复文件检查

下载前检查 DOWNLOAD_ROOT 中是否已存在同名文件：

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

若发现 → 提示用户：

⚠️ 已存在相似文件：{path} ({size})。是否重新下载？[y/N]

步骤 3 — 路径可用性 + 大小感知 + 空间检查

1. 确定下载子目录（默认结构）：

   DOWNLOAD_ROOT\YYYY-MM-DD\{sanitized-task-name}\

{sanitized-task-name} 规则：

- 使用任务描述或包名，小写，空格替换为短横线

- 最大 40 字符，不含特殊字符

- 若无明确任务名称，使用 general

- 示例：F:\AI-Downloads\2026-05-26\install-pandas\

1. **运行 scripts/check-space.ps1** —— 新增功能包括：

- 盘符是否存在检查（若盘符缺失 → 退出码 2 = 阻止，不降级到 C 盘）

- 路径可写性测试（创建并删除临时文件）

- 自动创建下载目录（如不存在）

- 任一检查失败 → 阻止执行，并显示清晰错误信息

1. 若已知下载大小（如模型卡片、包元数据等）：

- 与目标磁盘剩余空间对比

- 若大小 > 可用空间的 50% → 警告：此下载（{X}GB）将占用 {Y}% 的可用空间于 {drive}：

- 若大小 > 剩余空间 → 阻止

1. 向用户输出信息：

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

步骤 4 — 下载完成后：验证 + 记录 + 通知

1. 验证下载文件是否落在预期位置：

   Test-Path "{expected_path}"
   (Get-Item "{expected_path}").Length

1. 执行 scripts/log-download.ps1（含自动清理）

1. 向用户输出信息：

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

若验证失败 → 警告：⚠️ 下载文件未在预期路径找到，请手动检查。

配置保护（v5.4）

当 Agent 写入 config.md 时，必须满足以下要求：

1. 读取后验证：写入后重新读取文件，确认 DOWNLOAD_ROOT 和 SETUP_DONE 存在且有效
2. 禁止部分写入：一次性完整写入文件，不得追加或修改关键字段
3. 变更前备份：更改 DOWNLOAD_ROOT 前，保留旧值作为注释：

   # PREVIOUS: DOWNLOAD_ROOT: E:\old-path
   DOWNLOAD_ROOT: F:\new-path

1. 配置损坏处理：若检测到配置损坏（缺少必填字段、DOWNLOAD_ROOT 为空、SETUP_DONE 非 true 或 false），应提示用户重新配置

首次设置（SETUP_DONE: false）

步骤 0 — 扫描磁盘并推荐最佳选项

markdown

Skill: download-guard

Version: 5.4.0

Chunk: 2/2

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
  }

显示用户推荐的默认路径（空间最大的非 C 盘）：

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

磁盘扫描结果：

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

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

第一步 — 用户确认，代理写入配置

1. 标准化输入（仅驱动器字母 → {letter}:\AI-Downloads，完整路径 → 直接使用）
2. 在接收前验证路径可写（v5.4 版本）
3. 若目录不存在则创建
4. 写入 config.md：SETUP_DONE: false → true，DOWNLOAD_ROOT: → 用户选择
5. 读取回写内容以验证配置正确性（v5.4 版本）
6. 运行 scan-tool-cache.ps1
7. 若发现 C 盘缓存，询问是否迁移

第二步 — 输出状态卡片

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  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]，说"帮我修复"即可。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

透明性规则

每次下载前 — 提前告知

每次下载后 — 验证 + 记录日志 + 告知结果

（详见执行协议中的步骤 2–4）

每日首次触发 — 环境报告

每天第一次触发时输出环境报告。实现方式：

# 在临时文件中记录上次报告日期
$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) {
    # 今日首次触发 — 显示环境报告
    Set-Content -Path $lastReportFile -Value $today -Force
    # ... 输出报告 ...
}

报告格式：

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

若路径不可用 → 立即提示用户更新配置或重新连接磁盘。

路径询问策略

规则：仅在环境变化时提示。日常操作 = 仅告知。

规则（v5.4）：路径不可用 = 始终阻塞，绝不静默降级至 C 盘。

日志清理规则

归档命名：~/.workbuddy/download-log-archive-{YYYY-MM-DD}.md

将 LOG_RETENTION_DAYS: 0 设置为禁用清理。

自然语言命令

详细参考

关于路径类型、PATH 修复模板、配置参数、脚本说明及已知限制的完整信息，请参阅 [reference.md](reference.md)。