Windows 应用管理 (win-app-manager)

面向 Windows 用户的「应用全生命周期管理」技能：装机、盘点、升级、卸载、换机还原。
agent 驱动交互 + 脚本执行——所有危险操作（安装/卸载/升级）都先让用户确认，并把安装偏好持续记录成「应用画像」，让换机一键还原。

🎯 一句话触发（用户怎么说你就响应）

> 只要用户提到以下任意一类需求，立即加载本 Skill 并进入对应流程：

触发关键词速查：装机 装软件 安装 卸载 删除软件 升级 更新 盘点 已装 换机 还原 重装 推荐 软件清单 应用管理 备份 网盘 云端

> 💡 判断技巧：只要用户意图涉及"Windows 桌面应用的增删查改"，就是本 Skill 的场景。浏览器插件、VS Code 扩展等子品类不算。

⚠️ 安全红线与常见误区（先读这一段）

做之前过一遍，能省掉 90% 的踩坑：

1. 危险操作必须二次确认：安装、卸载、还原都内置 ShouldProcess 确认（-Force 才能跳过，agent 也不会替你按 -Force）。卸载是真正的移除，确认前请看清应用名。
2. 应用画像默认存本地：data/manifest.json 是本地文件。只有连了任意「网盘 / 云存储」连接器时，agent 才会自动把画像上传云端同步；没连就只存本地，换机靠 export 手动拷（U盘 / 网盘网页端）。
3. winget 调用有超时保护：脚本里所有 winget 调用都包了 Run-Winget，单次默认 5 分钟超时，超时会被标记为 stalled/timeout 而非一直挂着。国内访问 winget 默认 Community 源偶尔会卡顿（见文末"国内网络环境"）。
4. 非 winget 应用不会自动下：标了 source: web 的（如剪映、Adobe、网易云音乐、金蝶），脚本只列出与记录，实际下载与安装由 agent 走联网兜底流程，且会先把链接和文件大小给你确认。
5. 绝不执行来源不明的 .exe：联网兜底只走官网 / GitHub Releases；遇到第三方下载站会警告并建议绕开。
6. 管理员权限：winget 安装通常会弹 UAC；脚本启动会提示当前是否管理员，非管理员也能用但部分软件会失败。
7. 脚本必须带 UTF-8 BOM：脚本含中文，PowerShell 5.1 加载无 BOM 的 .ps1 会按 ANSI 读，导致"字符串缺少终止符"。当前已带 BOM，编辑器重存请保留。

能力一览

目录结构

win-app-manager/
  scripts/app-manager.ps1     # 核心脚本（winget 封装 + 画像读写）
  references/profiles.json    # 多角色应用清单（数据驱动，可改）
  references/alternative-sources.md  # 非 winget 应用联网兜底流程
  data/manifest.json          # 应用画像（运行生成，默认本地）

触发场景（完整列表见上方 🎯 一句话触发表）

用户说以下任意一种即触发：装机、重装后装软件、批量安装、推荐装什么软件、升级应用、卸载应用、看看我装了哪些、换机还原环境、"帮我装 xx"、"管理一下我的应用"。

Agent 编排流程

不要一上来就跑脚本。 这个 skill 的价值在交互。

1. 识别意图

• 盘点 → list
• 推荐/安装 → 走"推荐流程"
• 升级 → upgrade
• 卸载 → uninstall（必须二次确认）
• 换机还原 → restore
• 记录当前环境 → capture

2. 推荐安装流程（重点）

用户要"推荐装什么"时：

1. 先问用户背景（multiSelect=true，可多选角色）：
   - 程序员 / 开发
   - 视频剪辑
   - 会计 / 财务
   - 设计 / 创意
   - 通用办公
2. 按所选角色从 references/profiles.json 取出对应清单，合并去重。
3. 展示清单让用户过目（分组显示：基础开发/云原生/通讯/浏览器…），并说明哪些是 winget 直装、哪些需要联网。
4. 用户确认后，分两批处理：
   - winget 项 → app-manager.ps1 -Action install -Profile <角色>
   - web 项 → 走"联网兜底"

> 直接指定软件（如"装 Chrome 和 VS Code"），跳过问背景，直接传 -Apps。

3. 安装 / 升级 / 卸载的确认机制

• 脚本对 install/uninstall/restore 已内置 ShouldProcess 二次确认。
• agent 层面：每批操作前先文字列出"将要执行的操作"，等用户拍板再跑。
• 升级默认只动画像里的（--scope manifest），避免误动用户不想动的应用。

4. 非 winget 应用联网兜底（半自动）

winget 搜不到的（如 PixPin、剪映、Adobe）在 profiles.json 里标 source:web。处理流程：

1. 用 WebSearch 查官方下载页（优先官网 / GitHub Releases，避开第三方下载站）。
2. 拿到下载直链后，先给用户看链接和文件大小，确认后再下载。
3. 下载到临时目录，尝试静默安装（Inno /VERYSILENT、NSIS /S、MSI /quiet）。
4. 安装后把该应用记入画像（source: web，附 url、installedAt）。

5. 应用画像持久化（换机不丢）

• 画像默认存 data/manifest.json（本地文件）。
• 两种跨机同步方式，优先云同步：
• ☁️ 云同步（推荐）：连了任意网盘/云存储连接器时，agent 会在 capture/export 后自动把画像推到云端固定路径，新机器 restore 前自动拉回，全程不用手动拷文件。详见下方「☁️ 云端同步（网盘 / 云存储连接器，通用）」。
• 💾 纯本地：没连网盘连接器时，退回 export/import 手动拷（U盘 / 网盘网页端）。
• 工作流（云）：旧机 capture → 自动上传云端 → 新机 agent 拉取 → restore。
• 工作流（本地）：旧机 capture → export 到 U盘 → 新机 import → restore。

如何运行脚本

脚本路径：scripts/app-manager.ps1（需 Windows + PowerShell 5.1+ + winget）。

# 盘点
powershell -ExecutionPolicy Bypass -File scripts/app-manager.ps1 -Action list

# 按角色安装（脚本内部会再确认）
powershell -ExecutionPolicy Bypass -File scripts/app-manager.ps1 -Action install -Profile developer

# 直接指定若干 ID
powershell -ExecutionPolicy Bypass -File scripts/app-manager.ps1 -Action install -Apps Git.Git,Google.Chrome

# 升级（仅画像内 / 全部）
powershell -ExecutionPolicy Bypass -File scripts/app-manager.ps1 -Action upgrade -Scope manifest
powershell -ExecutionPolicy Bypass -File scripts/app-manager.ps1 -Action upgrade -Scope all

# 卸载（必须确认）
powershell -ExecutionPolicy Bypass -File scripts/app-manager.ps1 -Action uninstall -Name "7zip.7zip"

# 记录当前环境 / 导出 / 导入 / 还原
powershell -ExecutionPolicy Bypass -File scripts/app-manager.ps1 -Action capture
powershell -ExecutionPolicy Bypass -File scripts/app-manager.ps1 -Action export -ExportPath D:\backup\manifest.json
powershell -ExecutionPolicy Bypass -File scripts/app-manager.ps1 -Action import -ImportPath D:\backup\manifest.json
powershell -ExecutionPolicy Bypass -File scripts/app-manager.ps1 -Action restore

> 加 -Force 可跳过脚本内确认（仅在你已替用户确认过时）。
> 加 -TimeoutSec 600 可放宽单次 winget 调用超时（默认 300 秒），网络慢时可延长。

扩展方式（全部走配置文件，不写死在脚本）

• 改/加应用清单：编辑 references/profiles.json，在对应角色的 apps 数组加项。字段：id(winget ID，可为 null)、name、cat(分组)、source(默认 winget，web 应用填 web)、search(id 为空时用来搜索的关键词)。
• 加非 winget 应用：见 references/alternative-sources.md 的"如何新增一条"。
• 新增角色：在 profiles.json 顶层加一个 key（如 "gamer": {...}），agent 询问背景时把它加进选项即可。

☁️ 云端同步（网盘 / 云存储连接器，通用）

换机还原最省事的方式是让画像跟着账号走。只要会话里连了任意一个「网盘 / 云存储」类连接器（例如百度网盘、微云、Dropbox、OneDrive、阿里云盘等），agent 就能自动把画像同步到云端，省去手动 export/import 拷贝。 没连任何云存储连接器就降级为纯本地。具体用哪家，由用户当前已连的连接器决定——本 skill 不绑定任何一家。

> 架构说明：云同步由 agent 通过已连接的网盘连接器完成（脚本保持本地职责，只管 data/manifest.json 的读写），不写死在 PowerShell 里——换哪家网盘都不用改脚本，也避免凭据外泄。

0. 先判断能不能用（每次涉及换机/备份/还原时先做）

扫一遍会话已连接的连接器，挑出任意一个具备「上传/下载文件」能力的网盘/云存储类连接器即可：

未连接时的标准话术（主动建议，但别替用户做决定）：

> "这个功能可以把软件清单备份到网盘，换机不用手动拷文件。你要不要现在去连一个网盘连接器？（左侧连接器里搜'网盘'看有哪些可选，比如百度网盘、微云、Dropbox 等）连上我就帮你开云同步；不连也能用，只是换机要自己拷 manifest.json 文件。"

1. 上传到云端（旧机器，capture/export 之后做）

本地 capture 生成 data/manifest.json 后，调用已连接网盘连接器的上传能力，把内容写到一个固定云端路径，例如：

WorkBuddy/win-app-manager/manifest.json

• 直接用该连接器提供的"上传文件 / 上传文本"能力（如各家的 file_upload / file_upload_by_content 接口），不用关心是哪家网盘。
• 同名覆盖即可，避免产生多份散乱备份。
• 完成后提示用户："已同步到 <连接器名> ✅"（动态填实际连接器名，而非写死某一家）。

2. 从云端拉回（新机器，restore 之前做）

新机器上：

1. 用同一个网盘连接器查云端是否有 WorkBuddy/win-app-manager/manifest.json。
2. 有 → 下载到本地 data/manifest.json，然后 restore 一键重装。
3. 没有 → 退回本地 import（手动拷来的文件），或提示用户先在旧机器跑一次同步。

> 如果用户只是想"先备份"，不必强制还原——上传成功即完成，下次换机再拉回即可。

3. 多机器 / 多网盘的注意事项

• 云端路径固定可覆盖，减少碎片；若用户有多台机器共用一份清单，单份即可；若想按机器分开，可加机器名后缀（如 manifest-DESKTOP-ABC.json）。
• 跨网盘不互通：旧机器用 A 网盘备份，新机器要用同一个连接器才能拉回；换网盘得重新传一次。
• 绝不假装同步成功：没连任何云存储连接器就不要说"已备份到云"，老实说"只存在本机"。

4. 安全

• manifest 不含敏感数据：只记录应用名/ID/来源/安装时间，不含账号密码，上云安全。

🌐 国内网络环境（可选优化）

winget 默认走官方 Community 源（https://winget.azureedge.net），国内偶发卡顿或超时。三种应对方法任选：

1. 默认 5 分钟超时已够用：脚本自带 Run-Winget 包装器，单条失败会被标 stalled/timeout 并继续下一项，不会让整批卡死。
2. 放宽单次容忍度（简单立即生效）：
   powershell powershell -ExecutionPolicy Bypass -File scripts/app-manager.ps1 -Action install -Profile developer -TimeoutSec 600
3. 替换 Community 源为镜像（适合稳定长期使用）：自行搜索当前可用的 winget 国内镜像（如部分高校镜像源）后用 winget source update --name winget --source <URL> 切换；URL 不在 skill 内固定写，避免后续失效。

🖼️ 运行效果示例

第一次接触时直接看示例，不用猜会输出什么。

list

[环境] Windows PowerShell 5.1.26100.9168 (兼容模式，推荐升级 PowerShell 7 获得更佳体验)

=== 本机已安装应用 (winget) ===
名称                 Id                            版本        可用更新
-----------------------------------------------------------  ---------  ---------
Git                  Git.Git                       2.45.2
Visual Studio Code   Microsoft.VisualStudioCode    1.95.0
Python 3.13          Python.Python.3.13            3.13.12
...

=== 与画像的差集 ===
  [已记录] Git (Git.Git) 来源=winget
  [已移除] 7-Zip (7-Zip.7-Zip) 来源=winget
  （画像为空，运行 capture 可记录当前应用）

install -Profile developer

=== 待安装 (winget, 共 10 项) ===
  - Git  [Git.Git]
  - VS Code  [Microsoft.VisualStudioCode]
  - Python 3.13  [Python.Python.3.13]
  - nvm (Node 版本管理)  [CoreyButler.NVMforWindows]
  ...

=== 需联网安装 (web, 共 0 项, 由 agent 处理) ===

确认安装以上 10 个应用?
[Y] 是(Y)  [A] 全是(A)  [N] 否(N)  [L] 全否(L)  [S] 暂停(S)  [?] 帮助(默认值为“Y”): Y
  [...] Git
  [OK]    Git
  [...] VS Code
  [跳过]  VS Code (已安装)
  [...] Python 3.13
  [OK]    Python 3.13
  ...

完成：成功 8 / 跳过 2 / 失败 0 / 待联网 0 / 超时 0

capture

记录当前已安装应用到画像...
已更新画像: C:\Users\you\.workbuddy\skills\win-app-manager\data\manifest.json
已记录 59 个应用。

restore

按画像还原安装...
winget 应用 (50)：
  - Git [Git.Git]
  - VS Code [Microsoft.VisualStudioCode]
  ...

确认还原 50 个应用?
[Y] 是(Y)  ...: Y
  [跳过] Git 已安装
  [...] VS Code
  [OK]    VS Code
  ...

还原结束。

卡顿场景（验证超时保护）

[...] DaVinci Resolve
[超时] DaVinci Resolve (winget 调用超过 300 秒未响应已强制终止)
[...] OBS Studio
[OK]    OBS Studio
...

完成：成功 4 / 跳过 2 / 失败 1 / 待联网 0 / 超时 1
提示：超时的应用可手动 winget install --id <ID> 重试，或加大 -TimeoutSec 重跑整批。

鲁棒性说明（部署须知）

• 脚本必须带 UTF-8 BOM：脚本含中文，PowerShell 5.1 加载无 BOM 的 .ps1 会按 ANSI 读中文，导致"字符串缺少终止符"的解析错误。文件当前已带 BOM；若用编辑器重存，务必保留 UTF-8 BOM（或把控制台信息改为纯英文）。
• 兼容 PowerShell 5.1：脚本未使用三元运算符、-AsHashtable 等 PS 6+ 专属语法，确保默认 Windows PowerShell 可运行。
• 启动环境预检：脚本开头会检查 PowerShell 版本与操作系统——低于 5.1 或非 Windows 直接退出并给出升级指引；5.1 提示"兼容模式，推荐升级 7"；7+ 正常运行。缺少 ConvertFrom-Json/ConvertTo-Json 也会被拦截。
• 依赖 winget：脚本启动时检测 winget，缺失会给出安装指引（Win11 装"应用安装程序"，Win10 从 GitHub 下载）。
• winget 超时保护（Run-Winget）：所有 winget 调用都通过 Run-Winget 包装，基于 Process.Start + WaitForExit(timeout) + Kill，单次默认 300 秒硬超时，超时返回 stalled/timeout 并继续下一项，不会让脚本卡死。卡顿时可在用户侧 Ctrl+C 安全中断，下次重跑会自动跳过已装的。
• capture 用 winget export：比解析 winget list 文本可靠，能拿到全部真实包 ID（含名字无点的应用）。
• 失败续跑：单个应用安装失败 / 超时不影响其他项，结尾给出成功/跳过/失败/待联网/超时 五项汇总。

❓ 常见问题（FAQ）

> 散落在各章节的注意事项集中在此处，遇到问题先查这里。

安装相关

Q: winget 下载卡住不动怎么办？
A: 脚本已内置 5 分钟超时保护，单条失败会自动标记 stalled/timeout 并继续下一项。如果频繁超时，可加 -TimeoutSec 600 延长容忍时间，或考虑切换 winget 国内镜像源。

Q: 安装时弹出 UAC（用户账户控制）提示正常吗？
A: 正常。winget 安装大部分软件需要管理员权限，脚本启动时会检测当前是否管理员，非管理员也能用但部分软件会失败。

Q: 为什么有些软件装不了 / 需要手动下载？
A: 标记为 source: web 的软件（如剪映、Adobe、网易云音乐、金蝶等）不在 winget 仓库中或 winget 包不可靠。脚本会列出这些应用，由 agent 走联网兜底流程——搜官方下载页 → 给你看链接和大小确认 → 下载到临时目录 → 尝试静默安装。

Q: 软件已经装了还会重装吗？
A: 不会。install 和 restore 都会先检查是否已安装，已装的自动跳过（显示 [跳过]），不会重复安装覆盖。

升级与还原

Q: 升级后画像会更新吗？
A: 会。从 v1.1 起，upgrade 成功后会自动更新 manifest.json 中的 upgradedAt 时间戳和 upgradeCount 计数器，方便后续追踪升级历史。

Q: 换机还原时软件版本会和旧机器一致吗？
A: 不一定。winget install 默认安装最新版。还原前脚本会提示哪些应用有过升级记录，提醒你可能版本不一致。如需锁定版本，可用 winget install --version <x.y.z> 手动指定。

Q: 换机还原的完整流程是什么？
A: 两种方式——① 云同步（连了任意网盘连接器）：旧机 capture 后 agent 自动上传云端，新机 restore 前自动拉回，不用手动拷；② 纯本地：旧机 capture → export 到 U盘 → 新机 import → restore。详见上方「☁️ 云端同步（网盘 / 云存储连接器，通用）」。

卸载相关

Q: 卸载能撤销吗？
A: 脚本本身不提供撤销，但卸载操作会记录在画像中（状态变为 removed + removedAt 时间戳）。重新安装只需再跑一次 install 即可。

Q: 卸载会删掉我的数据吗？
A: winget uninstall 只卸载程序本身，通常不会删除用户数据目录（如 %AppData% 中的配置）。但部分软件的卸载程序可能清理注册表或用户数据，重要数据请提前备份。

画像与数据

Q: 应用画像存哪里？安全吗？
A: 默认存 <skill目录>/data/manifest.json，纯本地 JSON 文件，包含你装过的应用列表、来源、安装时间等。不含敏感信息，但建议不要上传到公开仓库。

Q: 换机不想手动拷贝文件怎么办？
A: 连上一个「网盘 / 云存储」类连接器即可（如百度网盘、微云、Dropbox、OneDrive 等，哪家都行）。连接后 agent 会在 capture/export 时自动把 manifest.json 上传到云端固定路径（WorkBuddy/win-app-manager/manifest.json），新机器 restore 前自动拉回，全程无需手动拷。在会话左侧"连接器"里搜"网盘"看有哪些可选；没连就只能用 export/import 手动搬运。详见上方「☁️ 云端同步（网盘 / 云存储连接器，通用）」。

环境与兼容性

Q: 必须是 Windows 吗？macOS 能用吗？
A: 目前仅支持 Windows（依赖 winget + PowerShell）。macOS 可用 brew 替代 winget，但不在此 Skill 覆盖范围。

Q: PowerShell 版本有要求吗？
A: 需要 PowerShell 5.1+（Windows 10/11 自带）。推荐升级到 PowerShell 7 以获得更佳体验和更好的中文编码支持。脚本兼容 PS 5.1，未使用 PS 6+ 专属语法。

Q: 脚本报"字符串缺少终止符"怎么办？
A: 这是 PowerShell 5.1 加载无 BOM 编码的 .ps1 文件时的经典问题。脚本必须带 UTF-8 BOM。如果用编辑器修改过脚本，请确保保存时保留 UTF-8 BOM。

Q: 提示"未检测到 winget"怎么解决？
A: - Windows 11：在 Microsoft Store 搜索「应用安装程序 (App Installer)」安装
- Windows 10：同样在 Microsoft Store 安装，或从 GitHub Releases 下载

网络问题

Q: 国内访问 winget 源慢 / 超时怎么办？
A: 三种方案：
1. 默认就够用：脚本自带超时保护 + 失败续跑，偶尔慢不影响整体
2. 加长超时：命令加 -TimeoutSec 600
3. 换镜像源：用 winget source update --name winget --source <镜像URL> 切换（需自行搜索当前可用的国内镜像地址）

> 💡 以上 FAQ 未解决你的问题？把报错信息发给 agent，它会结合具体场景分析。