Save Desktop Layout / 保存桌面图标布局

Backs up Windows desktop icon positions by exporting the relevant registry keys, and generates a one-click restore script.
通过导出注册表键值来备份 Windows 桌面图标位置，并生成一键恢复脚本。

Workflow / 备份流程

Step 1: Ask where to save / 第一步：询问保存位置

Use AskUserQuestion to let the user choose a backup destination folder. Offer these options:
使用 AskUserQuestion 让用户选择备份目标文件夹，提供以下选项：

• Desktop / 桌面 — save to ~/Desktop/DesktopLayoutBackup
• Documents / 文档 — save to ~/Documents/DesktopLayoutBackup
• Custom path / 自定义路径 — let the user specify

Step 2: Collect system info / 第二步：收集系统信息

Gather metadata by writing a small .ps1 script and running it (avoids $_ being eaten by bash):
通过编写并运行一个小型 .ps1 脚本来收集元数据（避免 $_ 被 bash 吞掉）：

# Write to a temp file, then run: / 写入临时文件后运行：
$controllers = Get-CimInstance Win32_VideoController
foreach ($c in $controllers) {
    if ($c.CurrentHorizontalResolution -gt 0) {
        Write-Host "$($c.CurrentHorizontalResolution)x$($c.CurrentVerticalResolution)"
        break
    }
}

# Icon size (safe to run inline) / 图标大小（可安全内联运行）
Get-ItemProperty 'HKCU:\Software\Microsoft\Windows\Shell\Bags\1\Desktop' -Name 'IconSize' -ErrorAction SilentlyContinue | Select-Object -ExpandProperty IconSize

# Current timestamp / 当前时间戳
Get-Date -Format 'yyyy-MM-dd HH:mm:ss'

IMPORTANT / 重要提示: Do NOT use $_ in inline PowerShell commands passed through bash — it gets stripped. Always use .ps1 script files for commands involving $_.
不要在通过 bash 传递的内联 PowerShell 命令中使用 $_——它会被吞掉。涉及 $_ 的命令必须写入 .ps1 脚本文件再执行。

Step 3: Export registry / 第三步：导出注册表

Run the export script bundled with this skill:
运行技能自带的导出脚本：

powershell -ExecutionPolicy Bypass -File "scripts/export_layout.ps1" -OutputDir "<chosen_directory>"

The script exports HKCU\Software\Microsoft\Windows\Shell\Bags\1\Desktop to desktop_icon_layout.reg using reg.exe export.
该脚本使用 reg.exe export 将注册表键导出为 desktop_icon_layout.reg 文件。

If the script is not found or fails, fall back to running directly:
如果脚本未找到或执行失败，回退到直接运行：

$dir = "<chosen_directory>"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
reg.exe export "HKCU\Software\Microsoft\Windows\Shell\Bags\1\Desktop" "$dir\desktop_icon_layout.reg" /y

Verify the .reg file exists and has non-zero size after export.
导出后验证 .reg 文件存在且大小不为零。

Step 4: Generate restore script / 第四步：生成恢复脚本

Create a file named restore_desktop_layout.bat in the backup directory. Use the template from scripts/restore_template.bat bundled with this skill — read it, then write it to the target directory.
在备份目录中创建 恢复桌面图标布局.bat 文件。读取技能自带的 scripts/restore_template.bat 模板，然后写入目标目录。

The .bat calls scripts/restore_layout.ps1 (bundled with this skill) which performs a reliable restore:
该 .bat 文件会调用技能自带的 scripts/restore_layout.ps1，执行可靠的恢复操作：

1. Parses the .reg file and extracts all registry values (dword, binary, string) / 解析 .reg 文件，提取所有注册表值
2. Force-kills explorer via Stop-Process + taskkill /f fallback (prevents explorer from overwriting layout on shutdown) / 通过 Stop-Process + taskkill /f 强制终止资源管理器（防止其在退出时覆盖布局数据）
3. Deletes the current Desktop bag registry key to clear stale data / 删除当前的 Desktop bag 注册表键以清除过期数据
4. Writes backup values directly via Set-ItemProperty (more reliable than reg.exe import) / 通过 Set-ItemProperty 直接写入备份值（比 reg.exe import 更可靠）
5. Restarts explorer / 重启资源管理器

Step 5: Write backup info / 第五步：写入备份信息

Create a backup_info.txt in the backup directory containing:
在备份目录中创建 backup_info.txt，包含以下内容：

• Backup timestamp / 备份时间
• Screen resolution (width x height) / 屏幕分辨率（宽 x 高）
• Icon size in pixels / 图标大小（像素）
• File descriptions / 文件说明
• Restore instructions (run the .bat as admin) / 恢复说明（以管理员身份运行 .bat）

Step 6: Verify and present / 第六步：验证并呈现

1. List all files in the backup directory and confirm sizes > 0 / 列出备份目录中的所有文件并确认大小 > 0
2. Present the backup directory to the user with present_files / 使用 present_files 向用户呈现备份文件
3. Remind the user: restore works best when screen resolution matches the backup resolution / 提醒用户：恢复时屏幕分辨率应与备份时一致

Restore Workflow / 恢复流程

If the user asks to restore a previously saved layout:
如果用户要求恢复之前保存的布局：

1. Search for backup in common locations (~/Documents/DesktopLayoutBackup, ~/Desktop/DesktopLayoutBackup):
   在常见位置搜索备份文件：
   powershell Test-Path 'C:\Users\<user>\Documents\DesktopLayoutBackup\desktop_icon_layout.reg' Test-Path 'C:\Users\<user>\Desktop\DesktopLayoutBackup\desktop_icon_layout.reg'
2. Run the restore script bundled with this skill:
   运行技能自带的恢复脚本：
   bash powershell -ExecutionPolicy Bypass -File "scripts/restore_layout.ps1" -RegFile "<path_to_reg_file>"
3. If the layout doesn't take effect, advise the user to sign out and sign back in.
   如果布局未生效，建议用户注销并重新登录。

Pitfalls (learned from testing) / 踩坑记录（来自实测）

• reg.exe import alone is unreliable / 单独使用 reg.exe import 不可靠 — explorer may overwrite the imported data on shutdown. Must force-kill explorer so it cannot write back. / 资源管理器在退出时可能将当前布局写回注册表，覆盖导入的数据。必须强制终止 explorer。
• Stop-Process may not kill explorer / Stop-Process 可能无法终止 explorer — use taskkill /f /pid <pid> as a fallback. The script handles both. / 使用 taskkill /f /pid <pid> 作为备用方案。脚本已处理这两种情况。
• $pid is read-only in PowerShell / $pid 在 PowerShell 中是只读变量 — never use it as a loop variable. Use $proc or $p instead. / 切勿用作循环变量，应使用 $proc 或 $p。
• $_ is stripped by bash / $_ 会被 bash 吞掉 — write PowerShell commands that use $_ to .ps1 files, not inline. / 涉及 $_ 的 PowerShell 命令必须写入 .ps1 文件，不能内联执行。

Notes / 备注

• Only works on Windows (tested on Windows 10/11) / 仅适用于 Windows（已在 Windows 10/11 上测试）
• Registry path / 注册表路径: HKCU\Software\Microsoft\Windows\Shell\Bags\1\Desktop
• The IconLayouts binary value stores per-icon positions / IconLayouts 二进制值存储每个图标的位置
• FFLAGS bit 0x1 indicates auto-arrange — if enabled, custom positions are ignored / FFLAGS 的第 0x1 位表示自动排列——启用时自定义位置会被忽略
• Always verify the export succeeded before telling the user the backup is complete / 在告知用户备份完成之前，务必验证导出是否成功