@wwkit/opm 1.0.2 → 1.0.4

package/README.md

@@ -6,7 +6,7 @@
 
 - 合并读取：内置默认（`src/config.json5`）→ 用户文件 → `OPM_CONFIG_CONTENT` 环境变量注入层（最高优先级）；字符串中 `{env:XXX}` 占位符替换为环境变量
 - `proxy` — 代理预设 + `active`（当前激活代理；默认空 = 不使用代理，可改为预设 key 或完整 URL。命令行 `-p/--proxy` 传入时优先使用传入值）
-- `npm` / `pip` / `dnf` / `apt` / `brew` / `composer` / `bun` / `nvm` / `node` / `phpenv` / `php` / `python` 的 `registry` — 镜像预设 + `active`（当前激活镜像）
+- `npm` / `pip` / `dnf` / `apt` / `brew` / `composer` / `bun` / `nvm` / `node` / `phpenv` / `php` / `python` / `uv` / `docker` / `homebrew` 的 `registry` — 镜像预设 + `active`（当前激活镜像）
 
 `active` 可以是预设 key（如 `"taobao"`），也可以是完整 URL：
 
@@ -51,14 +51,24 @@ pnpm opm <command> [args] [options]
 | `brew <action>` | brew 包管理器（macOS / Homebrew） |
 | `composer <action>` | composer 包管理器（PHP） |
 | `bun <action>` | bun 包管理器（Bun runtime，npm 兼容源） |
+| `winget <action>` | winget 包管理器（Windows） |
 | `nvm <action>` | nvm 自身管理（安装/升级/卸载 nvm） |
 | `node <action>` | node 版本管理（基于 nvm 安装/切换/卸载 Node.js 版本） |
 | `phpenv <action>` | phpenv 自身管理（安装/升级/卸载 phpenv） |
 | `php <action>` | php 版本管理（基于 phpenv 安装/切换/卸载 PHP 版本） |
 | `uv <action>` | uv 自身管理（安装/升级/卸载 uv） |
 | `python <action>` | python 版本管理（基于 uv 安装/切换/卸载 Python 版本） |
+| `docker <action>` | Docker 自身管理（安装/升级/启停/open，含 daemon 状态） |
+| `homebrew <action>` | Homebrew 自身管理（安装/升级/卸载 brew） |
+| `wsl <action>` | WSL2 管理（安装/升级/列表/启停/打开发行版） |
+| `cft <action>` | Chrome for Testing 安装器（chrome + chromedriver） |
+| `git <action>` | git 安装/配置/diff 导出导入 |
+| `proc <action>` | 进程与系统信息管理（列表/搜索/终止/端口/进程树） |
+| `ftp <action>` | FTP 文件管理（上传/rsync/下载） |
+| `ensure <runtime> [version]` | 确保运行时已安装（node/php/python） |
+| `ping <host|proxy|registry>` | 验证主机、代理或所有 registry 的可访问性 |
 | `config [section]` | 查看常用配置（proxy + 各 registry 段，段名动态生成） |
-| `opencode <action>` | opencode 运维命令（clear 清理过期会话） |
+| `opencode <action>` | opencode 运维命令（安装/升级/清理/env/open） |
 
 ## Managers
 
@@ -75,7 +85,7 @@ pnpm opm <command> [args] [options]
 | `node` | node 版本管理（基于 nvm，install/use/uninstall Node.js 版本，镜像 via `NVM_NODEJS_ORG_MIRROR`） |
 | `phpenv` | phpenv 自身管理（安装/升级/卸载 phpenv + php-build 插件，git clone + shell profile） |
 | `php` | php 版本管理（基于 phpenv，install/global 切换 PHP 版本，镜像 via `PHP_BUILD_MIRROR_URL`） |
-| `uv` | uv 自身管理（安装/升级/卸载 uv，curl 安装 + `uv self update`） |
+| `uv` | uv 自身管理（安装/升级/卸载 uv，curl 安装脚本走 `uv.registry.active` + `uv self update`） |
 | `python` | python 版本管理（基于 uv，install/pin/uninstall Python 版本，镜像 via `UV_PYTHON_INSTALL_MIRROR`） |
 
 ## Actions
@@ -101,12 +111,23 @@ pnpm opm <command> [args] [options]
 
 | 命令 | 说明 |
 |------|------|
+| `opencode version` | 已安装版本 |
+| `opencode installed` | 检查是否已安装 |
+| `opencode install` | 安装（使用 opm npm 镜像 + proxy） |
+| `opencode uninstall` | 卸载 |
+| `opencode upgrade` | 升级（使用 opm npm 镜像 + proxy） |
+| `opencode config` | 显示配置文件内容 |
+| `opencode dir` | 显示 data/db/log/config 路径 |
+| `opencode env` | 显示环境变量（OPENCODE_CONFIG_DIR / CONTENT） |
+| `opencode open [-d <dir>]` | 在指定目录启动 TUI（默认 cwd），自动注入环境变量 |
 | `opencode clear` | 清理过期会话并 VACUUM 压缩数据库（缺省 `-d 1`，只保留今天） |
 | `opencode clear -d, --days <n>` | 保留最近 n 天（对齐本地零点，含今天） |
 | `opencode clear -h, --hours <n>` | 保留最近 n 小时（滚动窗口） |
 | `opencode clear -n, --num <n>` | 保留最新 n 个会话 |
 | `opencode clear --dry-run` | 仅预览，不修改任何数据 |
 | `opencode clear -y` | 跳过确认提示 |
+| `opencode clear --backup` | 删除前备份数据库 |
+| `opencode clear --db <path>` | 覆盖 opencode 数据库路径 |
 
 保留策略参数（`--days` / `--hours` / `--num`）三选一，互斥。
 
@@ -317,12 +338,40 @@ opm php upgrade                       # 安装最新版本
 
 ```bash
 opm uv version                        # 查看 uv 版本
-opm uv install                        # 安装 uv（curl 安装脚本）
+opm uv registry                       # 查询激活的安装脚本 URL
+opm uv registry set <url|preset>      # 设置安装脚本 URL（写 uv.registry.active）
+opm uv registry presets               # 列出可用镜像预设
+opm uv install                        # 安装 uv（curl 执行 active 脚本 URL）
 opm uv upgrade                        # 更新 uv（uv self update）
 opm uv view                           # 检查 uv 是否已安装
 opm uv uninstall                      # 卸载 uv
 ```
 
+### docker
+
+```bash
+opm docker version                    # 查看 Docker 版本
+opm docker registry                   # 查询激活的安装脚本 URL
+opm docker registry set <url|preset>  # 设置安装脚本 URL（写 docker.registry.active）
+opm docker install                    # 安装 Docker（Linux 用 active 便捷脚本）
+opm docker status                     # 查看 daemon 状态
+opm docker start / stop / restart     # 启停 daemon
+opm docker dir                        # 查看数据目录
+opm docker uninstall                  # 卸载 Docker
+```
+
+### homebrew
+
+```bash
+opm homebrew version                  # 查看 Homebrew 版本
+opm homebrew registry                 # 查询激活的安装脚本 URL
+opm homebrew registry set <url|preset># 设置安装脚本 URL（写 homebrew.registry.active）
+opm homebrew install                  # 安装 Homebrew（curl 执行 active 脚本 URL）
+opm homebrew upgrade                  # 更新（brew update）
+opm homebrew dir                      # 查看安装目录
+opm homebrew uninstall                # 卸载 Homebrew
+```
+
 ### python
 
 ```bash
@@ -340,6 +389,111 @@ opm python upgrade                    # 安装最新版本
 
 > `pip` 与 `python` 互不干扰：`opm pip` 直接调用 pip CLI；`opm python` 通过 uv 管版本；如需更快的 pip 替代，可直用 `uv pip`。
 
+### git
+
+```bash
+opm git version                         # 查看已安装版本
+opm git install                         # 安装 git（系统包管理器）
+opm git upgrade                         # 升级 git
+opm git init                            # 从 opm 配置初始化全局 git 配置
+opm git config                           # 列出全局配置
+opm git config pull.rebase true          # 设置配置项
+opm git user                             # 查看用户信息
+opm git export mark                      # 查看当前 diff 基准
+opm git export mark 0                    # 标记当前 HEAD 为 diff 基准
+opm git export mark 3af967b             # 标记指定 commit
+opm git export mark --unset             # 删除基准
+opm git export                           # 导出 diff（基准 -> HEAD）
+opm git export -f 2                     # 导出 diff（HEAD~2 -> HEAD）
+opm git import file.diff                # 导入 diff 文件
+```
+
+### proc
+
+```bash
+opm proc info                            # 系统信息（OS/CPU/内存/磁盘）
+opm proc list                            # Top 10 进程（按内存）
+opm proc list -n 20 -b cpu              # Top 20 按 CPU 排序
+opm proc search -n node                  # 搜索 node 进程
+opm proc port                            # 所有监听端口
+opm proc kill -i 1234                    # 终止 PID 1234
+opm proc kill -p 8080 -f -y             # 强制终止 8080 端口进程
+opm proc tree                            # 进程树
+opm proc detail 1234                     # PID 1234 详情
+```
+
+### wsl
+
+```bash
+opm wsl version                          # WSL 版本
+opm wsl installed                        # 检查是否已安装
+opm wsl install                          # 安装 WSL2
+opm wsl install Ubuntu                   # 安装指定发行版
+opm wsl list                             # 已安装发行版列表
+opm wsl available                        # 可用发行版列表
+opm wsl start Ubuntu                     # 启动发行版
+opm wsl stop Ubuntu                      # 停止发行版
+opm wsl open                             # 打开 WSL
+opm wsl status                           # WSL 状态
+```
+
+### docker
+
+```bash
+opm docker version                       # Docker 版本
+opm docker install                       # 安装 Docker
+opm docker upgrade                       # 升级 Docker
+opm docker status                        # daemon 状态
+opm docker start / stop / restart        # 启停 daemon
+opm docker dir                           # 数据目录
+opm docker uninstall                     # 卸载 Docker
+```
+
+### homebrew
+
+```bash
+opm homebrew version                     # Homebrew 版本
+opm homebrew install                     # 安装 Homebrew
+opm homebrew upgrade                     # 更新（brew update）
+opm homebrew dir                         # 安装目录
+opm homebrew uninstall                   # 卸载 Homebrew
+```
+
+### cft
+
+```bash
+opm cft version                          # 查看已安装版本
+opm cft install                          # 安装 Chrome for Testing
+opm cft status                           # 查看安装状态
+opm cft clear                            # 清理安装文件
+opm cft dir                              # 查看安装目录
+```
+
+### ftp
+
+```bash
+opm ftp connect                          # 测试 FTP 连接
+opm ftp upload ./img.png                 # 上传文件
+opm ftp upload ./img.png -n cover -s banner  # 上传并重命名到子目录
+opm ftp upload https://example.com/a.jpg -n cover.jpg  # 从 URL 上传
+opm ftp rsync ./webwork/                 # 递归上传目录
+opm ftp rsync ./webwork/ -s deploy -x "vendor/*"  # 排除模式
+opm ftp rsync ./webwork/ --dry-run       # 预览
+opm ftp rsync ./webwork/ --prune         # 删除远端多余文件
+opm ftp download 20260913/cover.jpg ./cover.jpg  # 下载文件
+opm ftp root                             # 远程根目录
+opm ftp config                           # FTP 配置
+```
+
+### ensure
+
+```bash
+opm ensure node                          # 确保 Node.js 已安装
+opm ensure node 22                       # 确保 Node.js 22 已安装
+opm ensure php 8.3                       # 确保 PHP 8.3 已安装
+opm ensure python 3.12                   # 确保 Python 3.12 已安装
+```
+
 ### config
 
 ```bash
@@ -356,20 +510,49 @@ opm config nvm.registry                  # 查看 nvm registry 预设 + active
 opm config node.registry                 # 查看 node registry 预设 + active
 opm config phpenv.registry               # 查看 phpenv registry 预设 + active
 opm config php.registry                  # 查看 php registry 预设 + active
-opm config python.registry               # 查看 python registry 预设 + active
+opm config python.registry                 # 查看 python registry 预设 + active
+opm config uv.registry                     # 查看 uv registry 预设 + active
+opm config docker.registry                 # 查看 docker registry 预设 + active
+opm config homebrew.registry               # 查看 homebrew registry 预设 + active
 ```
 
 > `opm config [section]` 的可用段名由合并配置动态生成（每个 top-level 段 + 含 `registry` 的 `.registry` 子段），`opm config <未知段>` 会列出全部可用段。
 
+### ping
+
+```bash
+opm ping 8.8.8.8                       # Ping 指定 IP（默认精简数组）
+opm ping proxyhm-hk.security.huawei.com # Ping 指定主机
+opm ping proxy                         # Ping 当前 active 代理的主机
+opm ping registry                      # Ping 所有工具 registry active 主机（并行）
+opm ping source                        # 打印示例系统命令（npm active registry）
+opm ping 8.8.8.8 -c 2                  # 发送 2 个包
+opm ping proxy -d                      # 输出完整 JSON
+opm ping registry -d                   # 输出完整 JSON 数组
+```
+
+> 默认输出精简数组 `[{tool, address, proxy, reachable}]`；`-d/--detail` 输出完整 JSON（含 `sent`/`received`/`loss`/`rtt`/`raw` 等）。
+> `opm ping proxy` 从 `proxy.active` 解析代理 URL，提取主机名后 ping。
+> `opm ping registry` 遍历所有含 `registry` 配置的工具，并行 ping 各 active 地址的主机。
+
 ### opencode
 
 ```bash
-opm opencode clear                       # 只保留今天创建的会话
-opm opencode clear -d 7                  # 保留最近 7 天会话
-opm opencode clear -h 24                 # 保留最近 24 小时会话
-opm opencode clear -n 10                 # 保留最新 10 个会话
-opm opencode clear --dry-run             # 仅预览
-opm opencode clear -y                    # 跳过确认直接执行
+opm opencode version                   # 查看已安装版本
+opm opencode installed                 # 检查是否已安装
+opm opencode install                   # 安装 opencode
+opm opencode upgrade                   # 升级到最新
+opm opencode config                    # 显示配置文件内容
+opm opencode dir                       # 查看数据/日志/DB路径
+opm opencode env                       # 查看环境变量
+opm opencode open                      # 在当前目录启动 TUI
+opm opencode open -d /path/to/project  # 在指定目录启动 TUI
+opm opencode clear                     # 只保留今天创建的会话
+opm opencode clear -d 7                # 保留最近 7 天会话
+opm opencode clear -h 24               # 保留最近 24 小时会话
+opm opencode clear -n 10               # 保留最新 10 个会话
+opm opencode clear --dry-run           # 仅预览
+opm opencode clear -y                  # 跳过确认直接执行
 ```
 
 ## npm scripts

package/bin/index.js

@@ -1,5 +1,28 @@
 #!/usr/bin/env node
 
+import fs from 'node:fs'
+import path from 'node:path'
+
+let dir = process.cwd()
+for (let i = 0; i < 10; i++) {
+  const envPath = path.join(dir, '.env')
+  if (fs.existsSync(envPath)) {
+    for (const line of fs.readFileSync(envPath, 'utf8').split('\n')) {
+      const trimmed = line.trim()
+      if (!trimmed || trimmed.startsWith('#')) continue
+      const eq = trimmed.indexOf('=')
+      if (eq === -1) continue
+      const key = trimmed.slice(0, eq).trim()
+      const val = trimmed.slice(eq + 1).trim()
+      if (!(key in process.env)) process.env[key] = val
+    }
+    break
+  }
+  const parent = path.dirname(dir)
+  if (parent === dir) break
+  dir = parent
+}
+
 import { CLI } from '../src/cli/index.js'
 
 const cli = new CLI()

package/docs/managers/git.md

@@ -0,0 +1,103 @@
+# git 命令对照
+
+`@wwkit/opm` 统一命令管理 git 安装与配置、diff 导出/导入。
+
+## 命令对照
+
+| 统一命令 | 原始命令 | 说明 |
+|---------|---------|------|
+| `opm git version` | `git --version` | 查看已安装版本和路径 |
+| `opm git install` | `dnf install -y git` / `apt-get install -y git` | 通过系统包管理器安装 git |
+| `opm git uninstall` | `dnf remove -y git` / `apt-get remove -y git` | 通过系统包管理器卸载 git |
+| `opm git upgrade` | `dnf upgrade -y git` / `apt-get install --only-upgrade -y git` | 通过系统包管理器升级 git |
+| `opm git init` | `git config --global ...` | 从 opm 配置一键初始化全局 git 配置（user/ssl/pull.rebase） |
+| `opm git config` | `git config --global --list` | 列出全局配置 |
+| `opm git config <key>` | `git config --global --get <key>` | 查询单个配置项 |
+| `opm git config <key> <value>` | `git config --global <key> <value>` | 设置配置项 |
+| `opm git config --unset <key>` | `git config --global --unset <key>` | 删除配置项 |
+| `opm git user` | `git config --global user.name` / `user.email` | 查看 user.name 和 user.email |
+| `opm git user -n <name> -e <email>` | `git config --global user.name <name>` | 设置用户信息 |
+| `opm git export mark` | `git rev-list -n 1 opm-diff-base` | 查看当前基准标记 |
+| `opm git export mark 0` \| `HEAD` | `git tag opm-diff-base HEAD` | 标记当前 HEAD 为 diff 基准 |
+| `opm git export mark <commit>` | `git tag opm-diff-base <commit>` | 标记指定 commit 为 diff 基准 |
+| `opm git export mark --unset` | `git tag -d opm-diff-base` | 删除基准标记 |
+| `opm git export` | `git diff <mark> HEAD` | 导出基准到 HEAD 的 diff（auto-commit 未提交变更） |
+| `opm git export -f <n>` | `git diff HEAD~n HEAD` | 覆盖基准为 HEAD~n |
+| `opm git export -f <ref>` | `git diff <ref> HEAD` | 覆盖基准为任意 ref |
+| `opm git import <file>` | `git apply --reject <file>` | 导入 diff 文件到工作树 |
+
+## 选项
+
+| 选项 | 说明 |
+|------|------|
+| `-d, --dir <dir>` | git 仓库目录（默认 cwd） |
+| `-p, --proxy <url>` | install/upgrade 时代理 |
+| `--scope <global\|local\|system>` | config 作用域（默认 global） |
+| `-n, --name <name>` | user: 用户名；export: diff 文件名 |
+| `-e, --email <email>` | user: 用户邮箱 |
+| `-o, --output <file>` | export: 输出文件路径 |
+| `-f, --from <n>\|<ref>` | export: 覆盖基准 ref（数字=HEAD~n，字符串=ref） |
+| `-f, --force` | init: 强制覆盖已有配置 |
+| `--unset <key>` | config: 删除配置项 |
+| `-h, --help` | 显示帮助 |
+
+## 配置预设
+
+opm 配置 `git` 段（`opm git init` 使用）：
+
+```json5
+{
+  git: {
+    sslVerify: false,      // http.sslVerify
+    user: { name: "", email: "" },  // user.name / user.email
+    pullRebase: false,     // pull.rebase
+  },
+}
+```
+
+## diff 导出/导入流程
+
+1. **修改前**：`opm git export mark 0` — 标记当前 HEAD 为基准
+2. **修改后**：`opm git export` — 自动 commit 未提交变更，导出基准到 HEAD 的 diff
+3. **传输**：将 diff 文件传到目标机器
+4. **导入**：`opm git import <file>` — 在目标仓库应用 diff
+
+默认输出文件：`<workdir>/.webwork/git/changes-<from-short>-to-<to-short>.diff`
+
+## 示例
+
+```bash
+# 安装/升级 git
+opm git version                     # 查看已安装版本
+opm git install                     # 安装 git
+opm git upgrade                     # 升级 git
+
+# 初始化配置
+opm git init                        # 从 opm 配置初始化全局 git 配置
+opm git init -f                     # 强制覆盖已有配置
+
+# 配置管理
+opm git config                       # 列出全局配置
+opm git config pull.rebase true      # 设置 pull.rebase
+opm git config --unset pull.rebase   # 删除配置项
+opm git config --scope local         # 操作本地配置
+
+# 用户信息
+opm git user                         # 查看当前用户信息
+opm git user -n "John" -e "john@example.com"  # 设置用户信息
+
+# diff 导出
+opm git export mark                  # 查看当前基准
+opm git export mark 0                # 标记当前 HEAD 为基准
+opm git export mark HEAD             # 标记当前 HEAD 为基准
+opm git export mark 3af967b         # 标记指定 commit 为基准
+opm git export mark --unset        # 删除基准
+opm git export                       # 导出 diff（基准 -> HEAD）
+opm git export -f 2                 # 导出 diff（HEAD~2 -> HEAD）
+opm git export -n feature          # 导出为 feature.diff
+opm git export -d /path/to/repo    # 指定仓库目录
+
+# diff 导入
+opm git import changes-abc-to-def.diff  # 导入 diff 文件
+opm git import file.diff -d /repo       # 导入到指定仓库
+```

package/docs/managers/proc.md

@@ -0,0 +1,77 @@
+# proc 命令对照
+
+`@wwkit/opm` 统一命令管理系统信息与进程管理。
+
+## 命令对照
+
+| 统一命令 | 原始命令 | 说明 |
+|---------|---------|------|
+| `opm proc info` | — | 显示系统信息（OS/CPU/内存/磁盘/运行时间） |
+| `opm proc list` | `ps aux --sort=-%mem` | 列出按内存排序的 Top N 进程（默认 10） |
+| `opm proc list -b cpu` | `ps aux --sort=-%cpu` | 列出按 CPU 排序的进程 |
+| `opm proc search -n <name>` | `ps aux \| grep <name>` | 按名称模糊搜索进程 |
+| `opm proc search -n <name> --exact` | — | 精确匹配进程名 |
+| `opm proc search -n <name> -p <port>` | — | 按名称 + 端口搜索 |
+| `opm proc port` | `netstat -tlnp` | 列出所有监听端口及对应进程 |
+| `opm proc port -p <port>` | `netstat -tlnp \| grep <port>` | 查询指定端口 |
+| `opm proc kill -i <pid>` | `kill <pid>` | 按 PID 终止进程（SIGTERM） |
+| `opm proc kill -p <port>` | — | 按端口终止进程 |
+| `opm proc kill -n <name>` | `pkill <name>` | 按名称终止进程 |
+| `opm proc kill -i <pid> -f` | `kill -9 <pid>` | 强制终止（SIGKILL） |
+| `opm proc tree` | `pstree` | 显示进程树（所有顶层进程） |
+| `opm proc tree <pid>` | `pstree -p <pid>` | 显示指定 PID 的进程树 |
+| `opm proc detail <pid>` | `ps -p <pid> -o ...` | 显示指定 PID 的详细信息 |
+
+## 选项
+
+| 选项 | 说明 |
+|------|------|
+| `-n, --count <n>` | list: 进程数量（默认 10） |
+| `-n, --name <name>` | search/kill: 进程名称模式（默认模糊匹配） |
+| `-b, --by <mem\|cpu>` | list: 排序方式（默认 mem） |
+| `-p, --port <port>` | search/kill/port: 端口号 |
+| `-i, --id <pid>` | kill: 进程 ID |
+| `--exact` | search: 精确匹配（默认模糊） |
+| `-f, --force` | kill: 使用 SIGKILL 替代 SIGTERM |
+| `-y, --yes` | kill: 跳过确认提示 |
+| `-h, --help` | 显示帮助 |
+
+## 实现说明
+
+- `src/managers/proc.js` — systeminformation 封装 + netstat 端口映射 + 进程操作
+- `src/cli/groups/proc.js` — ProcGroup 命令组路由
+- 端口映射优先使用 `systeminformation.networkConnections()`，回退 `netstat -tlnp`
+- 内存值从 KB 转换为 MB（`memRss / 1024`）
+
+## 示例
+
+```bash
+# 系统信息
+opm proc info                        # OS/CPU/内存/磁盘/运行时间
+
+# 进程列表
+opm proc list                         # Top 10 进程（按内存）
+opm proc list -n 20                   # Top 20 进程
+opm proc list -b cpu                  # 按 CPU 排序
+
+# 搜索
+opm proc search -n node               # 模糊搜索 node 进程
+opm proc search -n node --exact       # 精确匹配
+opm proc search -n node -p 3000       # 搜索 node 进程 + 端口 3000
+
+# 端口
+opm proc port                         # 所有监听端口
+opm proc port -p 8080                 # 查询 8080 端口
+
+# 终止
+opm proc kill -i 1234                 # 终止 PID 1234
+opm proc kill -p 8080 -f -y           # 强制终止 8080 端口的进程
+opm proc kill -n node -y              # 终止所有 node 进程
+
+# 进程树
+opm proc tree                         # 所有顶层进程树
+opm proc tree 1234                    # PID 1234 的进程树
+
+# 详情
+opm proc detail 1234                  # PID 1234 的详细信息
+```

package/docs/managers/uv.md

@@ -9,19 +9,25 @@ uv 是 Astral 出品的快速 Python 包/版本管理器（Rust 实现），替
 | 统一命令 | 原始命令 | 说明 |
 |---------|---------|------|
 | `opm uv version` | `uv --version` | 查看 uv 版本 |
-| `opm uv install` | `curl -LsSf https://astral.sh/uv/install.sh \| sh` | 安装 uv |
+| `opm uv registry` | 读 `~/.config/opm/config.json5` 的 `uv.registry.active` | 查询激活的安装脚本 URL |
+| `opm uv registry set <url\|preset>` | 写 `~/.config/opm/config.json5` 的 `uv.registry.active` | 设置激活安装脚本 URL（支持预设名） |
+| `opm uv registry presets` | — | 列出可用镜像预设 |
+| `opm uv install` | `curl -LsSf <active> \| sh` | 安装 uv（脚本 URL 来自 `uv.registry.active`） |
 | `opm uv upgrade` | `uv self update` | 更新 uv |
 | `opm uv uninstall` | `rm ~/.local/bin/uv` + `rm -rf ~/.local/share/uv` | 卸载 uv |
 | `opm uv dir` | 返回 uv 安装目录 |
 
-> uv 无镜像源，故无 registry action。
+> 安装脚本 URL 通过 `uv.registry.active` 配置（`opm uv registry set <url>`）；Windows 仍使用官方 `install.ps1`。
 
 ## 示例
 
 ```bash
 opm uv version
+opm uv registry
+opm uv registry presets
+opm uv registry set official
 opm uv install
 opm uv upgrade
 opm uv dir
 opm uv uninstall
-```
+```