封面小强

概述

给 Windows 文件夹安装随文件夹便携、且客户解压后无法修改的封面图标。

何时使用

• 用户要求给文件夹加封面 / 自定义图标 / 公司 Logo 图标
• 用户反馈文件夹图标压缩发送后丢失、解压后变回默认黄色
• 用户要求封面"不可修改 / 防改 / 防删"
• 需要验证封面在压缩往返后是否存活

工具

统一使用 scripts/folder_cover.py（依赖 Pillow），三个子命令：

# 1. Logo 图片 -> 圆角多尺寸 .ico（居中裁方、256/128/64/48/32/16）
python scripts/folder_cover.py make-ico <logo图片> <输出.ico>

# 2. 安装封面到文件夹（复制 ico 进文件夹 + 写 desktop.ini + 属性防护 + 刷新缓存 + 像素级验证）
python scripts/folder_cover.py apply <目标文件夹> --ico <图标.ico>

# 3. 模拟"资源管理器压缩 -> 客户解压"完整往返，验证封面存活 + 防改测试
python scripts/folder_cover.py roundtrip <文件夹> --zip <输出.zip>

标准工作流

1. 用户给 Logo 图片时先用 make-ico 生成 ico；已有现成 ico 则跳过。
2. 用 apply 安装封面。脚本会自动完成：ico 复制进文件夹内部、desktop.ini 写相对路径、设置防护属性、刷新图标缓存、读取 shell 实际渲染像素与目标 Logo 对比。
3. 涉及"发给客户"时，必须跑 roundtrip 做端到端验证，并把生成的 zip 作为可发送成品。
4. 向用户汇报验证结果（渲染 RGB 均值对比 + 属性状态 + 防改测试）。

核心原理（必读）

• 相对路径：desktop.ini 必须写 IconResource=.folder_icon.ico,0。绝对路径是"发给客户后封面丢失"的根本原因——客户机器上没有那个路径。
• desktop.ini 编码：UTF-16LE + BOM（xffxfe）+ CRLF 换行，否则中文系统下可能不生效。
• 属性防护（zip 场景的上限）：
  • 文件夹：只读（desktop.ini 生效的前提，期望属性 0x11）
  • desktop.ini：只读+隐藏+系统（0x7）→ 改内容被系统拒绝、默认不可见
  • folder_icon.ico：只读+隐藏（0x3）→ 防换图标
  • 属性位随 zip 的 external_attr 传递，Windows 资源管理器 / 7-Zip 解压时自动还原
• zip 打包：用 Python zipfile 把 DOS 属性写入 external_attr（详见 references/技术要点.md），等价于资源管理器行为；沙箱环境禁用 Shell COM，不要用 New-Object -ComObject Shell.Application。
• 验证必须看实际渲染：用 SHGetFileInfoW 取 shell 显示的图标 → GetDIBits 取像素 → 16×16 均值 RGB 与目标 Logo 对比（容差 12）。默认黄文件夹约 RGB(98,88,53)，不能只看文件是否存在。
• 渲染验证依赖交互式桌面会话（explorer.exe 必须在运行）；不可用时工具自动降级为结构化验证（desktop.ini 编码/内容、ico 完整性、属性、zip 属性往返），并在输出中注明，此时提醒用户在资源管理器中目视确认。
• 刷新缓存：SHChangeNotify(SHCNE_ASSOCCHANGED) + ie4uinit.exe -show。

限制（需向用户说明）

• NTFS ACL 权限无法随 zip 传递，属性级防护已是"发 zip"场景的物理上限；Explorer 对只读文件删除时会弹确认框，确认后仍可删。
• 封面显示依赖客户用资源管理器/7-Zip/WinRAR 等会还原属性的解压工具；个别简易解压工具可能丢属性导致封面丢失。
• 封面仅在 Windows 资源管理器中可见（macOS/网页打包预览不显示）。

详细技术细节与踩坑记录见 references/技术要点.md。