Folder Icon

folder-icon Skill

为目录下的子文件夹批量生成并应用彩色图标。

支持两种方案：

设计原则：方案A的图标目录放在目标目录内部（如 .folder-icons/），整个结构自包含、可整体迁移。 方案B无单独图标目录，适合一次性设置或不想在目录中增加隐藏文件夹的场景。

目录结构

folder-icon/
├── SKILL.md              # 本文件
├── scripts/
│   ├── folder_icon.py    # 核心脚本——方案A（Tabler）
│   ├── folder_icon_mdi.py# 附加脚本——方案B（MDI）
│   └── icon_config.yaml  # 图标映射配置示例
├── references/
│   └── icon-mappings.md  # 内置图标映射表
└── examples/
    └── source-mapping.md # 示例映射表

---

方案A：Tabler（推荐用于复杂目录）

# 标准用法（图标目录默认 .folder-icons/，在目标目录内）
python skills/folder-icon/scripts/folder_icon.py "D:\目标目录"

# 仅预览
python skills/folder-icon/scripts/folder_icon.py "D:\目标目录" --dry-run

# 强制重新生成
python skills/folder-icon/scripts/folder_icon.py "D:\目标目录" --force

# 自定义图标目录名
python skills/folder-icon/scripts/folder_icon.py "D:\目标目录" --icon-dir "my-icons"

流程

1. 读取 scripts/icon_config.yaml（SVG 来源、文件夹→图标映射）
2. 图标输出目录默认为 目标目录/.folder-icons/（可通过 --icon-dir 覆盖目录名）
3. 遍历目标目录子文件夹，按映射生成彩色 .ico（从 Tabler CDN 下载 SVG → 着色 → 渲染）
4. 为子文件夹写入 desktop.ini（ANSI 编码，IconResource 为相对路径，从子文件夹指向目标目录内的图标目录）
5. 设置文件夹 +S 属性 + desktop.ini +S +H 属性
6. 完成后提示用户刷新 Explorer

配置映射

explicit_mappings:
  - folder: "文档"
    icon: "book-outline.ico"
    rgb: [33, 150, 243]
    color: "蓝"

依赖

pip install svglib reportlab Pillow PyYAML requests

---

方案B：MDI（适合简单扁平目录）

python skills/folder-icon/scripts/folder_icon_mdi.py "D:\目标目录"

核心区别

• 图标位置：每个子文件夹自己持有 folder.ico，desktop.ini 引用 folder.ico,0（同目录）
• 文件夹属性：使用 +R (ReadOnly) 而非 +S (System)，更符合资源管理器图标显示约定
• SVG来源：Material Design Icons（raw.githubusercontent.com）
• 背景色：彩色圆角方块 + 白色MDI图标，风格统一鲜明
• ICO 尺寸：7种（16-256），从 512x512 SVG 渲染，清晰度高
• 无依赖配置文件：图标映射直接写在 Python 字典中（适合一次性设置）

MDI 图标命名

MDI SVG 源 URL：https://raw.githubusercontent.com/Templarian/MaterialDesign/master/svg/{name}.svg

查询图标：https://pictogrammers.com/library/mdi/

依赖

pip install Pillow cairosvg

---

关键实现细节（通用）

• desktop.ini 编码：必须 encoding='ansi'，否则 Windows Explorer 无法读取
• IconResource 路径：方案A用相对路径（如 ..\.folder-icons\book-outline.ico）；方案B直接用 folder.ico,0
• attrib 命令：路径含空格时必须加引号（如 attrib +R "D:\My Games"）

文件夹属性设置要点

• 方案A：文件夹 +S + desktop.ini +S +H
• 方案B：文件夹 +R + desktop.ini +H +S
• 两种属性组合在 Windows 上都能使 desktop.ini 生效
• WSL 写入的文件会丢失 Windows 文件属性，务必用 VBScript 或 attrib（cmd.exe） 设置

VBScript 设置属性示例

Dim fso
Set fso = CreateObject("Scripting.FileSystemObject")

' 方案B：文件夹 +R，desktop.ini +H+S
Dim folder: Set folder = fso.GetFolder("D:\path\to\folder")
folder.Attributes = folder.Attributes Or 1  ' +R（ReadOnly）

Dim ini: Set ini = fso.GetFile(folder.Path & "\desktop.ini")
ini.Attributes = ini.Attributes Or 2 Or 4 ' +H +S（Hidden + System）

刷新图标缓存

taskkill /f /im explorer.exe
del /a /q "%localappdata%\Microsoft\Windows\Explorer\iconcache*"
del /a /q "%localappdata%\IconCache.db"
start explorer.exe

或按 F5 刷新。

---

图标列表

• 方案A图标映射见 references/icon-mappings.md（40+ 个常用 Tabler 图标）
• 方案B的示例映射见 examples/source-mapping.md

常见问题

Q: desktop.ini 无效，图标不显示？ → 确认：① desktop.ini 为 ANSI 编码；② IconResource 路径正确；③ 文件夹有 +S(方案A)或+R(方案B)属性；④ desktop.ini 有 +S +H 属性

Q: 图标颜色不对？ → 方案A的 svg_colorize() 仅替换 currentColor、stroke、fill，渐变（stop-color）和 stroke="none" 保留原样

Q: WSL 设置属性不生效？ → WSL 的 chmod/drvfs 无法设置 Windows 属性，必须用 Windows 本地的 attrib cmd.exe 或 VBScript 设置

Q: 图标显示模糊？ → 确认 ICO 包含至少 4 种尺寸（16/32/48/256）。方案B内置 7 种尺寸。重启 Explorer 清除缓存后重试