ai-cleaner

---
name: ai-cleaner
description: AI清理工 — 把 Windows 或 macOS 电脑（新电脑或"感觉很难用"的旧电脑）整顿成整洁、少打扰、适合用 AI 工具写代码的环境：体检、系统设置优化、开发工具安装、Git/镜像源配置、管理员设置、系统升级与复查。用户说"AI清理工"、"优化电脑设置"、"电脑好难用"、"新电脑初始化"、"配置成开发/AI 写代码环境"时使用。
---

# AI清理工

目标：让电脑**整洁、少打扰、适合用 AI 工具写代码**。原则：

- **先体检后动手**：第 0 步只读；体检报告给用户确认一次后，常规项自动执行，**有风险或因人而异的项单独问**（关闭某个自启项、Defender 排除、系统升级、删除东西）。
- **改前记录原值，改后逐项验证**：退出码 0 ≠ 生效，必须回读注册表 / `defaults` / 版本号。
- **最后给一张表**：改了什么、没完成什么、怎么改回去。

先判断平台：Windows 走「Windows 流程」，macOS 走「macOS 流程」。脚本都在本 skill 目录下（下文用 `<skill>` 表示本文件所在目录）。

---

## Windows 流程

脚本在 `<skill>/windows/`。运行方式：`powershell -NoProfile -ExecutionPolicy Bypass -File <脚本> [参数]`。

### 0. 体检（只读）
运行 `diagnose.ps1`。输出：CPU/内存/硬盘健康、**各分区剩余空间**、开机自启、内存大户、电源计划、开机时长、系统版本与激活、Win11 硬件条件（TPM/UEFI）、已装开发工具、是否管理员。
给用户一份简短报告：硬件好不好、问题在哪、准备改什么。

### 1. 问用户（用 AskUserQuestion，一次问完）
1. 在不在国内 / 要不要按国内配置（决定是否换镜像源）。用户说"不在国内但按国内处理"就照做，但提醒国外用国内镜像可能更慢、可以改回。
2. 代码目录放哪个盘：**默认推荐剩余空间最大的盘**，建 `X:\code`。路径不能有中文/空格，不能放在桌面/文档（OneDrive 会同步，node_modules 会搞崩同步）。
3. Git 名字和邮箱（可跳过，以后 `gh auth login` 后再设）。
4. 要装哪些软件（多选，默认全选，见第 3 步）。
5. 体检里发现的不常用自启项（如 GameViewer）要不要关。

### 2. 普通权限设置
运行 `user-setup.ps1 -CodeDir X:\code`，它会：
- 删除 Edge 开机自启（`HKCU\...\Run\MicrosoftEdgeAutoLaunch_*`）
- 电源计划切到"高性能"（笔记本常隐藏，从模板 `8c5e7fda-...` 复制恢复）— 告诉用户用电池时也是高性能，出门可切回"平衡"
- 资源管理器：显示扩展名、显示隐藏文件、打开"此电脑"、标题栏完整路径、导航栏展开到当前文件夹。**不要**打开"显示受保护的系统文件"（满屏 desktop.ini，没用）
- Win11：恢复完整右键菜单
- 打开剪贴板历史（Win+V），关掉必应搜索、提示和建议、推广内容
- 当前用户执行策略设为 RemoteSigned（若提示被更具体的作用域覆盖，属正常，已保存）
- 创建代码目录，重启资源管理器（会闪一下任务栏，先告诉用户）

其他自启项只在用户同意后从 `HKCU\...\Run` 删除。

### 3. 安装工具（winget，后台运行）
运行 `install-tools.ps1`（`run_in_background`，耗时可能超过 10 分钟）。默认清单：
- **必装**：Git.Git、OpenJS.NodeJS.LTS、Python.Python.3.12、astral-sh.uv、GitHub.cli
- **推荐**：Microsoft.PowerShell、voidtools.Everything、liule.Snipaste、7zip.7zip、Microsoft.PowerToys
- **按需**（不主动装）：Docker、WSL 发行版

用 `-Ids` 参数传用户选中的包。安装开始前**提醒用户留意管理员确认窗口（可能在任务栏闪烁）**；Node 等 MSI 会卡在那里等确认。装完刷新 PATH 再验证版本。

### 4. 开发配置
运行 `dev-config.ps1 [-China] [-GitName ...] [-GitEmail ...]`：
- Git：core.longpaths、core.autocrlf true、init.defaultBranch main、core.quotepath false、pull.rebase false、core.editor（检测到 Cursor 用 `cursor --wait`，否则 VS Code `code --wait`）
- `-China`：npm → npmmirror；pip、uv → 清华源（uv 写 `%APPDATA%\uv\uv.toml`）

### 5. 管理员设置
`admin-setup.ps1 -CodeDir X:\code`：长路径、开发者模式、Defender 排除代码目录、关闭搜索框网页建议（这个在 HKCU\Software\Policies 下，**也需要管理员**）。

Defender 排除前要说明取舍：该目录不再被扫描，只放自己信任的项目。

运行方式（带日志）：
```powershell
$cmd = "Start-Transcript -Path $env:TEMP\ai-cleaner-admin.log -Force; & '<skill>\windows\admin-setup.ps1' -CodeDir 'X:\code'; Stop-Transcript"
Start-Process powershell -Verb RunAs -Wait -ArgumentList '-NoProfile','-ExecutionPolicy','Bypass','-Command',$cmd
```
弹窗前提醒用户看任务栏。**连续两次被"用户取消"就别再弹**，改成让用户右键开始菜单 →「终端（管理员）」自己粘贴命令运行。之后读日志 + 回读注册表确认。

### 6. 系统升级（可选，问用户）
- 仍是 Win10 且 TPM 2.0 + UEFI + 支持的 CPU → 推荐升级（Win10 已于 2025-10 停止安全更新）。
- 教育版/批量授权（MAK、KMS）：Windows 更新通常**不会推送** Win11，要手动升级；提醒升级后**可能需要重新激活**。
- 下载官方安装助手 `https://go.microsoft.com/fwlink/?linkid=2171764` 到 `Downloads\Win11Upgrade\`，用 `Get-AuthenticodeSignature` 确认是 Microsoft 有效签名，**让用户自己双击运行**（从这边启动需要提权，弹窗常被取消）。若提示版本不支持，改用媒体创建工具。
- 升级约 1 小时、多次重启，插电进行，文件和软件保留。

### 7. 复查与总结
运行 `verify.ps1 -CodeDir X:\code`，逐项打勾。**升级后一定要复查**：激活状态、Edge 自启（升级会加回来）、之前的设置。
`C:\Windows.old` 占几十 GB，10 天后自动删，留着可以回退 —— 解释清楚是为什么空间变少，不要说成"空间不够"。
最后给总结表，建议重启，告诉用户代码以后放哪里、新项目先 `git init`，让 AI 每完成一步就 commit。

---

## macOS 流程

脚本在 `<skill>/mac/`，用 `bash <脚本>` 运行。**说明：macOS 部分未在真机验证过，首次使用时逐步运行、逐项核对输出。**

### 0. 体检（只读）
`diagnose.sh`：芯片（Apple Silicon / Intel）、内存、磁盘剩余、macOS 版本、登录项、内存大户、已装工具（Xcode CLT、Homebrew、git/node/python/uv/gh）、iCloud 是否同步桌面与文稿。

### 1. 问用户
同 Windows：国内配置？代码目录（默认 `~/code`，**不要放在 iCloud 同步的桌面/文稿里**）、Git 身份、装哪些软件、登录项要不要关。

### 2. 系统设置
`setup.sh`（会先把相关 `defaults` 备份到 `~/.ai-cleaner-backup/`）：
- Finder：显示扩展名、显示隐藏文件、路径栏、状态栏、标题栏完整路径、新窗口打开主目录、搜索默认当前文件夹、改扩展名不警告、网络盘/U 盘不写 .DS_Store
- 键盘：关闭智能引号、智能破折号、自动纠错、自动大写、双空格句号（**这些会把代码里的引号改坏**）；加快按键重复，关闭长按出重音菜单
- 截图存到 `~/Screenshots`，不再堆满桌面
- 重启 Finder / SystemUIServer。按键重复类设置要注销后才完全生效。
登录项：在「系统设置 → 通用 → 登录项」里让用户关，或用 osascript 删除（先问）。

### 3. 安装工具
- **Xcode Command Line Tools**：`xcode-select --install`（弹窗，让用户点安装），自带 git。
- **Homebrew**：安装需要 sudo 密码，Claude 无法代输 → 让用户用 `! <命令>` 在会话里运行。国内先设置清华镜像环境变量（`install-tools.sh` 会打印完整命令）。Apple Silicon 记得把 `eval "$(/opt/homebrew/bin/brew shellenv)"` 写进 `~/.zprofile`。
- 有 brew 后运行 `install-tools.sh`：
  - 必装：git node python@3.12 uv gh
  - 推荐（对应 Windows 那套）：raycast（≈ Everything + 启动器）、rectangle（窗口分屏 ≈ PowerToys）、snipaste（截图贴图）、the-unarchiver（≈ 7-Zip）、maccy（剪贴板历史 ≈ Win+V）

### 4. 开发配置
`dev-config.sh [--china] [--git-name ..] [--git-email ..]`：Git 同 Windows，但 `core.autocrlf input`；国内镜像：npm、pip、uv、Homebrew 瓶子源（写进 `~/.zprofile`）。

### 5. 系统升级
`softwareupdate -l` 查看；有大版本更新建议用户去「系统设置 → 通用 → 软件更新」自己点。

### 6. 复查与总结
`verify.sh`，然后同 Windows 第 7 步。

---

## 踩过的坑（必须遵守）

1. **Windows PowerShell 5.1 脚本只能用纯 ASCII**。不带 BOM 的 UTF-8 会被按 GBK 读，中文注释乱码后会把后面的命令吞掉 —— 脚本"成功"退出但什么都没改。本 skill 的 .ps1 全是英文，修改时保持这一点；要输出中文就放在对话里说，不要写进脚本。
2. **退出码 0 不代表成功**：管理员脚本用 Transcript 记录日志，跑完回读注册表确认。
3. **从 Claude 这边弹的 UAC 窗口经常被"取消"**（被挡住或超时）。提醒用户看任务栏；两次失败就改成用户手动运行。
4. **HKCU\Software\Policies 也需要管理员**，放进管理员脚本。
5. **大版本升级会把 Edge 自启加回来**，升级后复查。
6. **WindowsApps 里的 `python.exe` 是 Microsoft Store 占位入口**，`--version` 没输出就等于没装。
7. winget 装完要刷新 PATH（`$env:Path = Machine + User`）才能找到新命令；告诉用户把已开的终端/编辑器关掉重开。
8. 有的 winget 安装（MSI）会等管理员确认，超过 10 分钟的命令会转到后台 —— 直接用 `run_in_background`。
9. 改设置前读出原值并告诉用户，方便改回；不删用户没同意删的东西。
10. 用户说的"空间不够"指的是哪块盘要确认清楚，按**实际剩余空间**推荐代码盘。
11. **GitHub 登录（`gh auth login --web`）报 `unexpected EOF`**：网页能开但轮询连接被掐断。先查本地代理（`HKCU\...\Internet Settings` 的 ProxyServer，Clash Verge 常见端口 7897/7890，用 `Get-NetTCPConnection -LocalPort <port> -State Listen` 确认在跑），然后带 `$env:HTTPS_PROXY='http://127.0.0.1:<port>'` 在后台重跑登录，读出一次性验证码告诉用户，并打开 `https://github.com/login/device`。用户找不到填码的地方时：页面标题是 "Device Activation"，要先点绿色 **Continue**，8 个方框才出现。
12. 登录后：`gh auth setup-git`；Git 身份用 `gh api user` 的 name 和 `<id>+<login>@users.noreply.github.com`（不暴露真实邮箱）；需要代理时只给 GitHub 设 `git config --global http.https://github.com.proxy`，不要设全局 HTTPS_PROXY（代理软件一关所有工具都会断）。