xhqing VSCE Install — 干净安装/升级 VSCode 扩展
为什么需要这个 skill
VSCode 扩展升级时，旧版本目录常残留在 ~/.vscode/extensions/ 下（每个版本一个独立目录 <publisher>.<name>-<version>），VSCode 的 contribution manifest 缓存（CachedExtensionVSIXs）也可能没干净切换到新版本。
历史版本残留会污染新版解析：如果旧版把某个 view 声明成 tree view、新版改成了 webview view，升级后 VSCode 可能仍按旧的 tree view 解析，但运行时新代码注册的是 WebviewViewProvider，类型对不上 → 报 There is no data provider registered that can provide view data，点活动栏图标打不开面板。
所以每次安装/升级扩展，都必须先彻底清理历史残留，再装最新版，不能只覆盖安装。这是真实排查过的坑（Resource Monitor v0.2.1 升级后点图标无反应，根因就是 0.1.0/0.2.0/0.2.1 三个版本目录同时残留，0.1.0 的 tree view 声明污染了 view 类型解析）。
核心原则
- 默认装最新版：从对应仓库的 GitHub Release 取最新 tag 的 vsix（用户约定「发布/最新版默认指 GitHub Release」，不是 Marketplace / Open VSX，除非用户明确指定）。
- 强制走清理流程：哪怕用户只说「装一下」「升级一下」，也要执行下方的卸载 + 删残留 + 清缓存，不能直接覆盖装。
- reload 由用户做：清理重装后，
reload window/ 重启 VSCode 这一步必须在 GUI 里做，Agent 代不了，要明确提示用户。 - 装项目扩展前先核对版本号一致性：当装的是正在开发的项目扩展（Agent 手上有本地代码目录、能读
package.json）时，下载 Release vsix 前先比 GitHub Release 最新 tag 与本地package.json的version是否一致——一致才从 Release 装；不一致不盲目装，先排查（忘了发版 / 发版失败 / 本地版本号没跟上 / Release 与本地代码不同步）。装别人的扩展（无本地代码）不适用此条。
前置确认：先搞清四件事再动手
- publisher.name：从 vsix 内的
package.json读publisher+name（如xhqing.resource-monitor），或从 GitHub Release asset 名 / 仓库名推断。后续所有命令都要用这个 id。 - VSCode 变体：用户实际用哪个？
code/code-insiders/cursor/windsurf等，每个有独立的扩展目录和缓存路径。用which code code-insiders cursor windsurf 2>/dev/null+<cli> --list-extensions --show-versions | grep <name>确认扩展实际装在哪个变体里。对用户实际用的那个变体操作，别只对默认code操作。 - 平台：macOS / Linux / Windows 的扩展目录和缓存路径不同（见下方「平台/变体路径速查」）。
- 版本号一致性（仅装项目扩展时）：装正在开发的项目扩展（手上有本地代码目录），下载 vsix 前先比 GitHub Release 最新 tag 与本地
package.json的version是否一致。本地读项目根package.json的version；Release 取最新 tag 用gh release view -R <owner>/<repo> --json tagName -q .tagName（或gh release list），tag 前缀若有v，两边连前缀一起比、或都去掉v再比。两边相等才装；不等则停下排查（忘了发版 / 发版失败 / 本地版本号没跟上 / Release 与代码不同步），不直接装。
标准 4 步流程
以下以 macOS + 默认 code 为例（其它平台/变体替换路径和 CLI 名）。
第 1 步：卸载扩展（清 VSCode 注册）
code --uninstall-extension <publisher>.<name>
第 2 步：删除所有历史版本残留目录
--uninstall-extension 通常只清当前生效版本，旧版本目录要手动删。用 glob 删全部版本，确保无残留：
rm -rf ~/.vscode/extensions/<publisher>.<name>-*
执行后用 ls -d ~/.vscode/extensions/<publisher>.<name>-* 2>/dev/null 确认目录已清空（无输出 = 干净）。
第 3 步：清 contribution manifest 缓存（关键）
这是让 VSCode「忘掉」旧 view / 命令声明的关键一步，不做的话缓存可能仍按旧版本解析：
# macOS（默认 Code）
rm -rf ~/Library/Application\ Support/Code/CachedExtensionVSIXs/<publisher>.<name>*
第 4 步：重装最新版 vsix
若装的是项目扩展，下载 vsix 前先确认上方「版本号一致性」已核对通过（Release tag 与本地
package.jsonversion 两边相等），不等则停下排查，不进入本步。
code --install-extension <latest.vsix 路径> --force
--force 覆盖安装。vsix 从最新 GitHub Release 下载：
gh release download <latest-tag> -R <owner>/<repo> -p '*.vsix' -D tmp/vsix-check
或用用户指定的本地 vsix。
第 5 步（用户做）：reload window
提示用户在 VSCode 里执行命令面板 → Developer: Reload Window，或彻底重启 VSCode。这一步 Agent 代不了，必须用户操作。reload 后扩展才会用全新的 contribution 声明重新注册。
平台 / 变体路径速查
扩展目录与缓存路径按「平台 × 变体」组合：
| 平台 | 扩展目录 | contribution 缓存 |
|---|---|---|
| macOS | ~/.vscode/extensions |
~/Library/Application Support/Code/CachedExtensionVSIXs/ |
| Linux | ~/.vscode/extensions |
~/.config/Code/CachedExtensionVSIXs/ |
| Windows | %USERPROFILE%\.vscode\extensions |
%APPDATA%\Code\CachedExtensionVSIXs\ |
变体不同，缓存目录名也不同（把表中的 Code 换掉）：
- VSCode Insiders →
Code - Insiders，CLIcode-insiders - Cursor →
Cursor，CLIcursor - Windsurf →
Windsurf，CLIwindsurf
扩展目录同理：Insiders 是 ~/.vscode-insiders/extensions，Cursor 是 ~/.cursor/extensions，Windsurf 是 ~/.windsurf/extensions。
验证
装完 + 用户 reload 后，让用户点扩展的活动栏图标 / 执行扩展命令，确认功能正常。如果是 webview view，确认不再报 no data provider，面板能正常展开。
边界
- 只对用户明确要装/升级的扩展执行清理，不要顺手清理其它扩展。
- 删除的是扩展残留目录和缓存，重装即恢复，风险低；但执行前仍把命令列清楚。
- 如果扩展上架了 Marketplace / Open VSX 且用户明确要从那里装，按用户指定的来（
<cli> --install-extension <publisher>.<name>直接从市场装，但仍走清理流程）。 - 本 skill 是全局通用工具型 skill，放全局
~/.claude/skills/vsce-install/，不需要同步到项目副本。