wpm：WinuxCmd 内建包管理器

为什么是 wpm

在 Windows 上给命令行装工具，通常意味着给系统再装一层包管理器及其运行时。 wpm 的取舍相反：包管理器住在命令集本体里，包的边界就是命令的边界—— 单 exe 工具平铺安装，带 DLL 的工具链自包含隔离。

核心特性

• 官方索引 281 包 wpm-source 仓维护的官方索引（schema:1）覆盖 ripgrep、fd、jq、fzf、bat、neovim、curl、wget、make、openssh、goawk、bsdtar 等便携 CLI。
• 三元组契约 每个构件必须带 sha256（64 位小写十六进制）、size（字节数）与 urls（多个则顺序尝试）——缺校验和的远程下载一律拒装。
• flat / shim 双布局 flat 单 exe 直接进 usr\bin\；shim 载荷自包含在 opt\<pkg>\，私有 DLL 不进 PATH，卸载即删目录。
• 硬链接入口 每个命令在 bin\ 下是「指向真二进制的硬链接」——同一文件，不是复制也不是转发进程，入口零启动开销。
• --json 契约 查询类子命令输出带 schema:1 版本字段的纯 JSON（list/search/installed/info/index status/links list/outdated/categories），供 GUI/TUI 与 agent 消费。
• 四源镜像与回退 内置 github-raw / jsdelivr / release-pinned / official-cn 四源按优先级自动回退；中国区 official-cn 经 gh.caomengxuan666.com 的 nginx 缓存代理，GitHub 源保底。
• 防投毒两道锁 索引文件内声明的 sources 永不并入候选（防被攻破的镜像持久注入下载位）；wpm index update 记录 last_index_sha256，非首选源送来内容不同的索引时告警。
• 自更新与回滚 wpm update winuxcmd 异步换镜像（等待占用进程退出后替换并重建全部链接）；.wpm\backup\ 自动保留最新两份回滚，wpm clean backup 回收。

安装与快速上手

wpm 没有单独的安装器——它随 WinuxCmd 一起落地。装好 WinuxCmd 后第一件事是刷新索引：

装包四连（每行注释即作用）：

wpm index update                 # 刷新官方索引
wpm install ripgrep fd jq        # 一次装多个包（rg / fd / jq 上 PATH）
wpm installed                    # 本机已装清单
wpm info ripgrep --json          # 完整包记录（机器可读）

首跑引导

wpm --help 看全部子命令（install/uninstall/update/list/search/info/installed/ export/restore/outdated/categories/index/source/links/clean/version）。索引不可达 （no reachable index source）时换源重试 wpm index update -s official-jsdelivr；需要代理时设 WPM_HTTPS_PROXY 等环境变量（WinHTTP 自动探测系统代理与 PAC）。 中国网络可直接切官方镜像源：

wpm source use official-cn

想清掉缓存/暂存/回滚目录：wpm clean [cache|staging|backup|all]； 重放一台机器的包清单：wpm export > profile.txt 与 wpm restore profile.txt。

深入：包模型与索引

索引是一个 JSON 文件（wpm-source/index.json）：顶层 schema:1、version（如 official-2026.10.17）、updated、 sources[]（可用镜像源）与 packages[]。包记录含 name/version/description/kind/category/license/commands[]（安装后暴露到 PATH 的命令名）与按平台分组的 artifacts（windows-x64 / windows-arm64）。

构件三元组与文件映射

每个构件必须携带 sha256（小写十六进制，缺失即拒绝远程安装）、 size（字节数）与 urls（多条则顺序尝试，首个成功者胜出）， 外加显式 files 映射（压缩包内路径 from → 安装目标 to）。下载先算校验和再解压；缓存键 <pkg>-<version>-<sha8> 双校验（WinuxCmd#1154/#1157）， 命中即跳过下载。写侧同样严格：映射指向构件已不再携带的文件时，安装以 「extracted path not found」失败，不猜。

flat 与 shim 双布局

flat（默认）把映射文件直接装入 usr\bin\，适合单 exe。 shim 把载荷（exe + 私有 DLL）自包含装到 <root>\opt\<pkg>\， usr\bin\<cmd>.exe 是转发入口——带 winuxcmd-shim.exe 的安装里是这个小转发器的硬链接（从 .wpm/shims.map 读载荷路径，分发跳数 24.5 ms → 12.1 ms）；否则硬链接 winuxcmd.exe 由分发器路由。DLL 与真 exe 同目录天然解析， 不进 PATH、无跨包冲突。无论哪种布局，bin\<command>.exe 都是 指向真二进制的硬链接——同一文件，零入口开销，且随 install/update/uninstall 同步。

--json 契约

查询类子命令的输出是纯 JSON、不混人类可读文本，顶层带 schema:1 版本字段（字段只增不改，语义不兼容时递增，前端应校验）： list/search 返回摘要包列表（含 installed/install_state/state 与摘要 artifact），info 返回完整 Package 记录 + wpm 运行期状态， index status 报 root/本地索引路径/版本/包数，links list 报 入口目录与命令名。变更类子命令（install/uninstall/update）暂无 --json：以退出码为准， 进度文本仅作展示。完整契约见 wpm-source/docs/index-schema.md。

镜像机制

源按优先级（数字小者优先）自动回退，wpm source use 可固定首选， wpm source add 加自建源。安全边界成文：候选源集合 = 内置注册表 + 用户手加源——索引文件内部声明的 sources 永不并入（被攻破的镜像 无法持久注入新下载位）；wpm index update 记录 last_success_source 与 last_index_sha256，非首选源送来 内容不同的索引时打印告警，毒镜像换索引无法静默。

wpm-artifacts 与工具链层

category: "toolchain" 的语言运行时与 SDK 有四条准入：自包含便携发布档 （rustup-init 式引导器出局）、可搬迁（在 opt\<pkg>\ 经 shim 布局运行、 无机器级安装）、官方发布或 unixwin/wpm-artifacts 上的 CI 构建镜像且 SHA-256 钉死、许可允许再分发。wpm-artifacts 是组织自托管的构件仓：官方上游不发 Windows 便携档（或需要重组）时的再分发通道——rust 的可搬迁 MSVC 束、git 的 MinGit 重组（仅暴露 git.exe、私有载荷留在 opt/git/）、protobuf 的 protoc 都走这条路。 GUI 应用、MSI/MSIX、服务驱动、生态包管理器（winget/scoop/choco 本身）明确出局。

实测数字

更新动态

wpm 无独立版本号——随 winuxcmd.exe 发布，条目记在 WinuxCmd 的 changelog 里。以下为最新 3 版中的 wpm 相关内容（changelogs.json，抓取 2026-10-19； 完整流水见 更新日志）：

• 1.1.20（WinuxCmd 发布线） WSL interop 路径：/mnt/X/… 操作数与 /X/…、X:\… 同形折叠（#1172）——所有走共享参数边界的工具（ls/du/sed/cp…）一次全收，wpm 装的 工具链同样受益。
• 1.1.19（2026-10-21） 新增 wpm links verify（逐路径报告不运行当前 winuxcmd.exe 的链接）与 winuxcmd-shim.exe 转发器（24.5 ms → 12.1 ms，旧安装经 wpm links rebuild --force 平滑切换）；修复 wpm update winuxcmd 把命令链接留在旧镜像的问题（删不掉的链接先 park 再换、换后校验重链）； 回滚副本保留最新两份自动修剪（单机曾积累 61.8 MB，wpm clean backup 回收）。
• 1.1.18（2026-10-20） 被运行中进程占用的文件以 rename-aside 升级：wpm install --force 在 28 个 fsmonitor--daemon 持有载荷的真实安装上成功且包完整；升级要么完成、要么原样不动 （失败的文件名与占用进程一并报告）；wpm clean staging/all 一并清理 parked 的 .wpm-old-<pid>。

相关链接