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（不包含无 -g 参数的本地 npm install）
• pnpm add -g（v5.4）
• bun install -g（v5.4）
• pip install（不包含处于激活 venv 中的安装——需先检查 VIRTUAL_ENV 环境变量）
• uv pip install（v5.4 —— 同样适用 venv 规则）
• 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.workbuddyskillsdownload-guardconfig.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

步骤 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_ROOTYYYY-MM-DD{sanitized-task-name}
   

   {sanitized-task-name} 命名规则：

   • 采用任务描述或包名，转为小写，空格替换为短横线（-）
   • 最长 40 字符，禁止特殊字符
   • 若无明确任务名，统一使用 general
   • 示例：F:AI-Downloads2026-05-26install-pandas

2. 执行 scripts/check-space.ps1 —— 新增以下能力：

   • 盘符存在性检查（若盘符缺失 → 退出码 2 = BLOCK，不回退至 C:）
   • 路径可写性测试（创建并删除临时文件）
   • 若下载目录不存在则自动创建
   • 任一检查失败 → 立即阻断，并输出清晰错误信息

3. 若已知下载尺寸（模型卡片、包元数据等）：

   • 对比目标磁盘剩余空间
   • 若下载体积 > 剩余空间的 50% → 提示："本次下载（{X}GB）将占用 {drive}: 盘 {Y}% 可用空间"
   • 若下载体积 > 剩余空间 → 阻断

4. 向用户输出摘要：

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

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

1. 校验下载文件是否落于预期路径：

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

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

3. 向用户输出完成摘要：

[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
   

4. 配置损坏处理：Agent 需主动识别损坏情形（如缺失必填字段、DOWNLOAD_ROOT 为空、SETUP_DONE 非 true/false），并提示用户重新配置

首次配置流程（SETUP_DONE: false）

步骤 0 —— 扫描磁盘 + 推荐最优选项

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 —— 用户确认，Agent 写入配置

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 盘缓存，提示迁移

步骤 2 —— 输出状态卡片

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