folder-icon Skill 快速创建指南

本文档说明如何从零创建 folder-icon Skill，使 OpenClaw 能识别并使用它。

📁 Skill 目录结构

skills/folder-icon/
├── SKILL.md          # 必需：Skill 元数据（触发词、描述、输入、流程）
├── folder_icon.py    # 必需：核心脚本（SVG → .ico + desktop.ini）
├── icon_config.yaml  # 必需：文件夹→图标→颜色 映射配置
├── README.md         # 可选：用户使用说明
└── SETUP.md          # 本文档

关键约束：Skill 必须放在 OpenClaw 的 skills 加载目录：

Step 1 — 创建目录和 SKILL.md

# 1. 创建 skill 目录（放在 skills/ 下，不是 workspace/skills/）
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.openclaw\skills\folder-icon"
 
# 2. 创建 SKILL.md（触发词是核心，决定何时唤起此 Skill）
@'
# folder-icon Skill
 
为指定目录下的子文件夹批量生成并应用彩色图标。
 
## 触发词
 
`文件夹图标`、`批量设置图标`、`设置文件夹 icon`、`apply folder icons`、`为目录设置图标`
 
## 输入
 
- **目标目录**：任意包含子文件夹的目录路径
- **图标目录**：`--icon-dir` 参数指定（覆盖配置文件）
- **配置文件**：`icon_config.yaml`（位于 Skill 目录）
 
## 流程
 
1. 读取 `icon_config.yaml`（图标目录、SVG 来源、配色映射）
2. 遍历目标目录下所有子文件夹
3. 根据映射生成彩色 .ico 图标
   - SVG 来源（`svg_source`）：
     - `"tabler"`：从 CDN 下载（来源 pictogrammers.com / @tabler/icons）
     - `"local"`：从本地 SVG 目录读取
   - 配色逻辑：将 SVG 中 `currentColor`、`stroke`、`fill` 替换为主题色
4. 为子文件夹写入 `desktop.ini`（IconResource 指向图标路径）
5. 设置文件夹 `+S` System 属性 + desktop.ini `+S +H` 属性
6. 刷新 Explorer 显示图标
 
## CLI 选项
 
```bash
python folder_icon.py "D:\目标目录"                    # 标准用法
python folder_icon.py "D:\目标目录" --icon-dir "folder-icon-dir" # 自定义图标目录名（默认 .folder-icons）
python folder_icon.py ".\目标目录" --dry-run           # 仅预览
python folder_icon.py ".\目标目录" --force             # 强制重新生成图标

依赖

pip install svglib reportlab Pillow PyYAML

’@ | Set-Content “$env:USERPROFILE.openclaw\skills\folder-icon\SKILL.md” -Encoding UTF8


**触发词设计原则**：
- 包含中文 + 英文，覆盖不同输入习惯
- 包含动词短语（`批量设置`、`apply`）让语义明确

---

## Step 2 — 创建 icon_config.yaml

这是最核心的配置，决定每个文件夹对应什么图标和颜色：

```powershell
@'
# icon_config.yaml
# 使用方式: python folder_icon.py "D:\目标目录"
# 图标目录默认在目标目录内：`.folder-icons/`（相对路径，脚本自动处理）

# ① 图标输出目录（相对于目标目录，可选，默认 .folder-icons）
icon_dir: '.folder-icons'

# ② SVG 来源: tabler（CDN）或 local（本地）
svg_source: tabler

# ③ 文件夹名 → 图标文件名 → RGB 三元组
# 图标文件名说明：
#   "图标名.ico" → Tabler SVG 名（去掉 .ico，后缀 -outline 等对应同名 SVG）
#   例如: account-search-outline.ico → https://pictogrammers.com/library/icon/user-search
explicit_mappings:
  - folder: "文件夹A"        # 必须与目标目录下子文件夹名完全一致
    icon: "book-outline.ico" # 必须是已注册的图标名（见下表）
    rgb: [33, 150, 243]      # RGB 三元组
    color: "蓝"              # 描述（仅日志用）

  - folder: "文件夹B"
    icon: "folder-text-outline.ico"
    rgb: [76, 175, 80]
    color: "绿"
'@ | Set-Content "$env:USERPROFILE\.openclaw\skills\folder-icon\icon_config.yaml" -Encoding UTF8

内置图标映射表

图标文件名	对应 Tabler SVG	说明
`account-search-outline.ico`	`user-search`	背调/用户搜索
`alert-outline.ico`	`alert-circle`	告警/重要
`book-outline.ico`	`book`	文档/书籍
`cactus.ico`	`cactus`	仙人掌
`cloud-download-outline.ico`	`cloud-download`	云下载
`database-search-outline.ico`	`database`	数据库
`file-document-outline.ico`	`file-description`	文档
`file-word-outline.ico`	`file-text`	文本/Word
`folder-text-outline.ico`	`folder`	文件夹
`image-outline.ico`	`photo`	图片/设计
`notebook-outline.ico`	`notes`	笔记
`school-outline.ico`	`school`	学习
`shield-check-outline.ico`	`shield-check`	安全/验证
……	……	……

根据文件夹名在图库中查找适合的 Icon 图标。

完整 Tabler Icons 图库：https://pictogrammers.com/library/icon/

命名规范

<功能>-<风格>.ico

风格：-outline（线框风格）/ 无后缀（填充风格）
示例：book-outline.ico、shield-check-outline.ico、cactus.ico
避免过长的复合名（如 account-search-outline 已是上限），同一概念尽量用最少的词表达

图标文件名须与 folder_icon.py 中 ICON_TO_TABLER 字典的 key 一致。

扩展图标：在 ICON_TO_TABLER 中添加映射："my-icon.ico": "tabler-icon-name"，然后在 icon_config.yaml 中使用。

Step 3 — 创建 folder_icon.py

核心脚本。完整代码如下（直接复制使用）：

# 下载完整脚本
# 地址: $env:USERPROFILE\.openclaw\skills\folder-icon\folder_icon.py
# 或从 GitHub 维护一份源文件
 
# 最小验证：检查脚本是否存在
Test-Path "$env:USERPROFILE\.openclaw\skills\folder-icon\folder_icon.py"

脚本逻辑说明：

函数	作用
`get_svg()`	从 CDN 下载 Tabler SVG（或从本地读取）
`svg_colorize()`	将 SVG 中 `currentColor` / `stroke` / `fill` 替换为目标 RGB 色
`render_svg()`	将 SVG 渲染为 PNG（多尺寸：16/32/48/256px）
`build_ico()`	将多尺寸 PNG 打包为 Windows `.ico` 文件
`make_icon()`	组合以上步骤生成单个 .ico
`write_desktop_ini()`	写入 `desktop.ini`（必须 ANSI 编码），IconResource 须为相对路径（如 `.folder-icons\book-outline.ico`），从子文件夹出发指向目标目录内的图标目录，设置 `+S +H` 属性
`set_folder_system_attr()`	设置文件夹 `+S` System 属性（含空格路径必须加引号）

Step 4 — 安装依赖

pip install svglib reportlab Pillow PyYAML

验证：

python -c "import svglib, reportlab, PIL, yaml; print('OK')"

Step 5 — 测试

# 1. Dry-run（预览，不实际修改）
python "$env:USERPROFILE\.openclaw\skills\folder-icon\folder_icon.py" "D:\目标目录" --dry-run
 
# 2. 正式执行
python "$env:USERPROFILE\.openclaw\skills\folder-icon\folder_icon.py" "D:\目标目录"
 
# 3. 强制重新生成（修改配置后）
python "$env:USERPROFILE\.openclaw\skills\folder-icon\folder_icon.py" "D:\目标目录" --force
 
# 4. 自定义图标目录名（默认 .folder-icons）
python "$env:USERPROFILE\.openclaw\skills\folder-icon\folder_icon.py" "D:\目标目录" --icon-dir "my-icons"

验证结果：按 F5 刷新 Explorer，查看文件夹图标是否显示。

常见问题

Q: Skill 触发词不生效？

原因：Skill 放错目录了。必须放在 $env:USERPROFILE\.openclaw\skills\ 下，不是 workspace/skills/。

# 正确位置
ls "$env:USERPROFILE\.openclaw\skills\folder-icon"
 
# 错误位置（OpenClaw 不会从这里加载）
ls "$env:USERPROFILE\.openclaw\workspace\skills\folder-icon"

Q: desktop.ini 无效，图标不显示？

确认编码：Windows 要求 desktop.ini 必须为 ANSI 编码（非 UTF-8），Python 写入时须显式指定：
```
with open(desktop_ini_path, 'w', encoding='ansi') as f:
    f.write(content)
```
若用 encoding='utf-8' 可能导致 Explorer 无法读取，图标不显示。
确认路径为相对路径：IconResource 须用相对路径而非绝对路径，例如：
```
IconResource=.folder-icons\book-outline.ico
```
路径为从子文件夹出发指向目标目录内图标目录的相对路径。绝对路径（如 D:\Icon\...）在目录移动或跨分区时失效，且不便于整体迁移。
确认文件夹有 +S 属性：attrib +S "D:\目标目录\文件夹名"
确认 desktop.ini 有 +S +H 属性：attrib +S +H "D:\目标目录\文件夹名\desktop.ini"
尝试手动刷新：powershell -Command "Rundll32 user32.dll,UpdatePerUserSystemParameters"

Q: 图标颜色不对？

配色逻辑仅替换 currentColor、stroke、fill，保留 stop-color（渐变）和 stroke="none"（透明）。某些 SVG 可能包含不受支持的额外颜色属性，需要调整 svg_colorize() 函数。

Q: 想要更多图标？

访问 https://pictogrammers.com/library/icon/ 选择图标
记下图标名（如 chart-bar）
在 folder_icon.py 的 ICON_TO_TABLER 中添加映射："chart-bar-outline.ico": "chart-bar"
在 icon_config.yaml 中使用该图标

更新配置工作流

1. 修改 icon_config.yaml（添加/修改映射）
2. python folder_icon.py "D:\目标目录" --dry-run   # 预览
3. python folder_icon.py "D:\目标目录" --force      # 执行
4. F5 刷新 Explorer

📁 最终目标目录结构示例：

D:\目标目录\
├── .folder-icons\
│   ├── book-outline.ico      # 蓝色
│   ├── folder-text-outline.ico # 绿色
│   └── ...
├── 文件夹A\
│   ├── desktop.ini           # IconResource=.folder-icons\book-outline.ico
│   └── (内容...)
└── 文件夹B\
    ├── desktop.ini           # IconResource=.folder-icons\folder-text-outline.ico
    └── (内容...)

图标目录在目标内部，可整体移动目录，路径始终有效。

文件清单

创建完成后，目录应包含：

%USERPROFILE%\.openclaw\skills\folder-icon\
├── SKILL.md          # Skill 元数据
├── folder_icon.py    # 核心脚本
├── icon_config.yaml  # 映射配置
└── README.md         # 用户说明（可选）

确认 OpenClaw 能加载：

openclaw skills list 2>&1 | findstr "folder-icon"

输出应显示 folder-icon 对应 ✅ ready。

小M-Quartz

探索

Folder_Icon_SETUP