@wwkit/opm 1.0.1

package/README.md

@@ -0,0 +1,381 @@
+# opm CLI 命令
+
+## 用户配置
+
+安装后自动生成 `~/.config/opm/config.json5`（或 `$XDG_CONFIG_HOME/opm/config.json5`），用户可直接编辑：
+
+- 合并读取：内置默认（`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`（当前激活镜像）
+
+`active` 可以是预设 key（如 `"taobao"`），也可以是完整 URL：
+
+```json5
+{
+  npm: {
+    registry: {
+      official: "https://registry.npmjs.org/",
+      taobao: "https://registry.npmmirror.com/",
+      active: "taobao",   // 预设 key，或直接写 URL
+    },
+  },
+}
+```
+
+- `opm config` 显示合并后的配置文件（不读系统配置；可用段名由配置动态生成，`opm config <段>` 可查看任意段）
+- `opm <manager> registry set <key|url>` 更新配置文件中的 `active`
+- `install` / `upgrade` 默认使用配置中的 active 镜像（npm 传 `--registry`，pip 传 `--index-url`；dnf/apt 通过 `registry set` 同步写入系统 repo 文件；brew 传 `HOMEBREW_API_DOMAIN` / `HOMEBREW_BOTTLE_DOMAIN`，不改系统配置；node 传 `NVM_NODEJS_ORG_MIRROR`；php 传 `PHP_BUILD_MIRROR_URL`；python 传 `UV_PYTHON_INSTALL_MIRROR`；bun 传 `BUN_CONFIG_REGISTRY`）
+
+## 用法
+
+```bash
+# 开发阶段（项目内直接运行）
+node bin <command> [args] [options]
+node bin config [section]
+
+# 全局安装后
+opm <command> [args] [options]
+
+# 从 monorepo 根目录
+pnpm opm <command> [args] [options]
+```
+
+## Commands
+
+| Command | 说明 |
+|---------|------|
+| `npm <action>` | npm 包管理器 |
+| `pip <action>` | pip 包管理器 |
+| `dnf <action>` | dnf 包管理器（Fedora / RHEL / EulerOS 等 rpm 系） |
+| `apt <action>` | apt 包管理器（Debian / Ubuntu 等 dpkg 系） |
+| `brew <action>` | brew 包管理器（macOS / Homebrew） |
+| `composer <action>` | composer 包管理器（PHP） |
+| `bun <action>` | bun 包管理器（Bun runtime，npm 兼容源） |
+| `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 版本） |
+| `config [section]` | 查看常用配置（proxy + 各 registry 段，段名动态生成） |
+| `opencode <action>` | opencode 运维命令（clear 清理过期会话） |
+
+## Managers
+
+| Manager | 说明 |
+|---------|------|
+| `npm` | npm 包管理器（registry 镜像，global/local 概念） |
+| `pip` | pip 包管理器（index-url 镜像，global 为系统 Python） |
+| `dnf` | dnf 包管理器（系统级，所有操作作用于系统，无全局/local 概念） |
+| `apt` | apt 包管理器（系统级，所有操作作用于系统，无全局/local 概念） |
+| `brew` | brew 包管理器（macOS，系统级，所有操作作用于系统，无全局/local 概念） |
+| `composer` | composer 包管理器（PHP，项目级，install/upgrade 作用于当前项目 composer.json） |
+| `bun` | bun 包管理器（Bun runtime，使用 npm 兼容 registry，global/local 概念） |
+| `nvm` | nvm 自身管理（安装/升级/卸载 nvm，git clone + shell profile） |
+| `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`） |
+| `python` | python 版本管理（基于 uv，install/pin/uninstall Python 版本，镜像 via `UV_PYTHON_INSTALL_MIRROR`） |
+
+## Actions
+
+| Action | 说明 |
+|--------|------|
+| `version` | 查看管理器本身版本 |
+| `registry` | 查询当前镜像地址 |
+| `registry set <url\|preset>` | 设置镜像地址（支持预设名） |
+| `registry presets` | 列出可用镜像预设 |
+| `search <name> [version]` | 查询包在源是否可用 |
+| `view <name>` | 查询包是否已安装 |
+| `info <name>` | 查询包详情 |
+| `versions <name>` | 列出所有可用版本 |
+| `list` | 列出所有已安装包 |
+| `outdated` | 列出过期包 |
+| `install <name> [version]` | 安装包 |
+| `uninstall <name>` | 卸载包 |
+| `upgrade <name>` | 升级包 |
+| `cache clean` | 清理缓存 |
+
+## Opencode 运维
+
+| 命令 | 说明 |
+|------|------|
+| `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` | 跳过确认提示 |
+
+保留策略参数（`--days` / `--hours` / `--num`）三选一，互斥。
+
+## 选项
+
+| 选项 | 说明 |
+|------|------|
+| `-g, --global` | 全局操作（npm: global node_modules; pip: system Python） |
+| `-p, --proxy <url>` | 代理地址（search/info/versions/outdated/install/upgrade）；未传时默认使用配置 `proxy.active`（为空则不启用代理） |
+| `-h, --help` | 显示帮助 |
+
+> 所有命令默认以 JSON 格式输出。
+
+## 示例
+
+### npm
+
+```bash
+opm npm registry                         # 查看配置中的激活 registry
+opm npm registry set taobao              # 设置激活镜像为 taobao（写入 opm 配置）
+opm npm registry presets                 # 列出可用镜像预设
+opm npm search axios                     # 查询 axios 是否可用
+opm npm search axios 1.7.9               # 查询指定版本
+opm npm view axios                       # 查询是否已安装
+opm npm info axios                       # 包详情
+opm npm versions axios                   # 所有版本
+opm npm list                             # 已安装列表
+opm npm outdated                         # 过期包
+opm npm install axios                    # 安装
+opm npm install axios 1.7.9             # 安装指定版本
+opm npm install -g typescript            # 全局安装
+opm npm uninstall axios                  # 卸载
+opm npm upgrade axios                    # 升级
+opm npm cache clean                      # 清理缓存
+```
+
+### pip
+
+```bash
+opm pip registry                         # 查看当前 index-url
+opm pip registry set tsinghua            # 设置为清华镜像
+opm pip search requests                  # 查询 requests 是否可用
+opm pip view requests                    # 查询是否已安装
+opm pip info requests                    # 包详情
+opm pip versions requests                # 所有版本
+opm pip list                             # 已安装列表
+opm pip install requests                 # 安装
+opm pip install requests 2.31.0          # 安装指定版本
+opm pip uninstall requests               # 卸载
+opm pip upgrade requests                 # 升级
+opm pip cache clean                      # 清理缓存
+```
+
+### dnf
+
+```bash
+opm dnf version                          # 查看 dnf 版本
+opm dnf registry                         # 查看当前启用仓库
+opm dnf registry set hce-updates         # 写入 opm.repo 指向 hce-updates 镜像
+opm dnf registry presets                 # 列出可用镜像预设
+opm dnf search vim-enhanced              # 查询包在源是否可用
+opm dnf view vim-enhanced                # 查询是否已安装
+opm dnf info vim-enhanced                # 包详情
+opm dnf versions vim-enhanced            # 所有可用版本
+opm dnf list                             # 已安装包列表
+opm dnf outdated                         # 过期包
+opm dnf install htop                     # 安装
+opm dnf install vim-enhanced 9.0         # 安装指定版本
+opm dnf uninstall htop                   # 卸载
+opm dnf upgrade htop                     # 升级
+opm dnf cache clean                      # 清理缓存
+```
+
+### apt
+
+```bash
+opm apt version                         # 查看 apt 版本
+opm apt registry                        # 查看当前启用源
+opm apt registry set ubuntu-tsinghua    # 写入 /etc/apt/sources.list.d/opm.list
+opm apt registry presets                # 列出可用镜像预设
+opm apt search curl                     # 查询包在源是否可用
+opm apt view curl                       # 查询是否已安装
+opm apt info curl                       # 包详情
+opm apt versions curl                   # 所有可用版本
+opm apt list                            # 已安装包列表
+opm apt outdated                        # 过期包
+opm apt install htop                    # 安装
+opm apt install curl 7.68.0-1ubuntu2.7  # 安装指定版本
+opm apt uninstall htop                  # 卸载
+opm apt upgrade htop                    # 升级
+opm apt cache clean                     # 清理缓存
+```
+
+### brew
+
+```bash
+opm brew version                       # 查看 brew 版本
+opm brew registry                      # 查看配置中的激活镜像
+opm brew registry set tsinghua         # 设置为清华镜像（install/upgrade 传 HOMEBREW_*_DOMAIN）
+opm brew registry presets              # 列出可用镜像预设
+opm brew search wget                   # 查询 wget 是否可用
+opm brew view wget                     # 查询是否已安装
+opm brew info wget                     # 包详情
+opm brew versions wget                 # 所有可用版本
+opm brew list                          # 已安装列表
+opm brew outdated                      # 过期包
+opm brew install wget                  # 安装
+opm brew install python 3.12           # 安装指定版本（versioned formula）
+opm brew uninstall wget                # 卸载
+opm brew upgrade wget                  # 升级
+opm brew cache clean                   # 清理缓存
+```
+
+### composer
+
+```bash
+opm composer version                    # 查看 composer 版本
+opm composer registry                   # 查看配置中的激活镜像
+opm composer registry set aliyun        # 设置为阿里云镜像
+opm composer registry presets           # 列出可用镜像预设
+opm composer search monolog/monolog     # 查询包是否可用
+opm composer search monolog/monolog 3.9.0  # 查询指定版本
+opm composer view monolog/monolog       # 查询是否已安装
+opm composer info monolog/monolog       # 包详情
+opm composer versions monolog/monolog   # 所有可用版本
+opm composer list                       # 已安装列表
+opm composer outdated                   # 过期包
+opm composer install monolog/monolog    # 安装（composer require）
+opm composer install monolog/monolog ^3.0  # 安装指定版本约束
+opm composer uninstall monolog/monolog  # 卸载（composer remove）
+opm composer upgrade monolog/monolog    # 升级（composer update）
+opm composer cache clean                # 清理缓存
+```
+
+### bun
+
+```bash
+opm bun version                       # 查看 bun 版本
+opm bun registry                      # 查看配置中的激活 registry
+opm bun registry set taobao           # 设置为 taobao 镜像（传 BUN_CONFIG_REGISTRY）
+opm bun search axios                  # 查询 axios 是否可用
+opm bun view axios                    # 查询是否已安装
+opm bun info axios                    # 包详情
+opm bun versions axios                # 所有可用版本
+opm bun list                          # 已安装列表
+opm bun outdated                      # 过期包
+opm bun install axios                 # 安装（bun add）
+opm bun uninstall axios               # 卸载（bun remove）
+opm bun upgrade axios                 # 升级（bun update）
+opm bun cache clean                   # 清理缓存（bun pm cache rm）
+```
+
+### nvm
+
+```bash
+opm nvm version                       # 查看 nvm 版本
+opm nvm registry set gitee            # 设置 nvm git 镜像为 gitee
+opm nvm install                       # 安装 nvm（git clone + shell profile）
+opm nvm upgrade                       # 更新 nvm（git pull）
+opm nvm view                          # 检查 nvm 是否已安装
+opm nvm uninstall                     # 卸载 nvm
+```
+
+### node
+
+```bash
+opm node current                      # 当前 Node.js 版本
+opm node version                      # 同上
+opm node list                         # 已安装版本列表
+opm node versions                     # 所有可用版本
+opm node install 20                   # 安装 Node.js 20
+opm node install --lts                # 安装最新 LTS
+opm node use 20                       # 切换到 Node.js 20
+opm node default 20                   # 设置默认版本
+opm node search v20.20.2              # 查询版本是否可下载
+opm node view v20.20.2                # 查询版本是否已安装
+opm node uninstall 18                 # 卸载 Node.js 18
+opm node upgrade                      # 安装最新 LTS
+```
+
+### phpenv
+
+```bash
+opm phpenv version                    # 查看 phpenv 版本
+opm phpenv registry set gitee         # 设置 phpenv git 镜像为 gitee
+opm phpenv install                    # 安装 phpenv（git clone + php-build 插件 + shell profile）
+opm phpenv upgrade                    # 更新 phpenv + php-build 插件
+opm phpenv view                       # 检查 phpenv 是否已安装
+opm phpenv uninstall                  # 卸载 phpenv
+```
+
+### php
+
+```bash
+opm php current                       # 当前 PHP 版本
+opm php list                          # 已安装版本列表
+opm php versions                      # 所有可用版本
+opm php install 8.3                   # 安装 PHP 8.3
+opm php use 8.3                       # 切换全局版本（phpenv global）
+opm php default 8.3                   # 设置默认版本
+opm php search 8.3.13                 # 查询版本是否可下载
+opm php view 8.3.13                   # 查询版本是否已安装
+opm php uninstall 8.2                 # 卸载 PHP 8.2
+opm php upgrade                       # 安装最新版本
+```
+
+### uv
+
+```bash
+opm uv version                        # 查看 uv 版本
+opm uv install                        # 安装 uv（curl 安装脚本）
+opm uv upgrade                        # 更新 uv（uv self update）
+opm uv view                           # 检查 uv 是否已安装
+opm uv uninstall                      # 卸载 uv
+```
+
+### python
+
+```bash
+opm python current                    # 当前 Python 版本
+opm python list                       # 已安装版本列表
+opm python versions                   # 所有可用版本
+opm python install 3.12               # 安装 Python 3.12
+opm python use 3.12                   # 固定当前目录版本（uv python pin）
+opm python default 3.12               # 设置默认版本（写 ~/.python-version）
+opm python search 3.12.4              # 查询版本是否可下载
+opm python view 3.12.4                # 查询版本是否已安装
+opm python uninstall 3.11             # 卸载 Python 3.11
+opm python upgrade                    # 安装最新版本
+```
+
+> `pip` 与 `python` 互不干扰：`opm pip` 直接调用 pip CLI；`opm python` 通过 uv 管版本；如需更快的 pip 替代，可直用 `uv pip`。
+
+### config
+
+```bash
+opm config                               # 查看合并后的用户配置（proxy + registries）
+opm config proxy                         # 查看代理预设 + active（空 = 不使用代理）
+opm config npm.registry                  # 查看 npm registry 预设 + active
+opm config pip.registry                  # 查看 pip registry 预设 + active
+opm config dnf.registry                  # 查看 dnf registry 预设 + active
+opm config apt.registry                  # 查看 apt registry 预设 + active
+opm config brew.registry                 # 查看 brew registry 预设 + active
+opm config composer.registry             # 查看 composer registry 预设 + active
+opm config bun.registry                  # 查看 bun registry 预设 + active
+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 [section]` 的可用段名由合并配置动态生成（每个 top-level 段 + 含 `registry` 的 `.registry` 子段），`opm config <未知段>` 会列出全部可用段。
+
+### 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                    # 跳过确认直接执行
+```
+
+## npm scripts
+
+| 命令 | 说明 |
+|------|------|
+| `npm run check` | 语法检查（`node --check bin/index.js`） |
+| `npm run test` | 运行测试 |
+| `npm run release` | 发布（复用 @wwkit/shared 的单包发布） |

package/bin/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { CLI } from '../src/cli/index.js'
+
+const cli = new CLI()
+cli.run(process.argv.slice(2)).catch((err) => {
+  console.error(`[opm] Error: ${err.message}`)
+  process.exit(1)
+})

package/docs/managers/apt.md

@@ -0,0 +1,45 @@
+# apt 命令对照表
+
+`@wwkit/opm` 统一命令管理 apt 包（Debian / Ubuntu 等 dpkg 系，系统级）。
+
+## 命令对照
+
+| 统一命令 | 原始命令 | 说明 |
+|---------|---------|------|
+| `opm apt version` | `apt --version` | 查看 apt 版本 |
+| `opm apt registry` | 读 `/etc/apt/sources.list.d/opm.list` | 查询当前启用源 |
+| `opm apt registry set <url\|preset>` | 写 `/etc/apt/sources.list.d/opm.list` + `apt update` | 设置镜像源 |
+| `opm apt registry presets` | — | 列出可用镜像预设 |
+| `opm apt search <name>` | `apt-cache search` | 查询包在源是否可用 |
+| `opm apt view <name>` | `dpkg -l` / `apt list --installed` | 查询包是否已安装 |
+| `opm apt info <name>` | `apt-cache show` | 包详情 |
+| `opm apt versions <name>` | `apt-cache madison` / `policy` | 所有可用版本 |
+| `opm apt list` | `apt list --installed` | 已安装包列表 |
+| `opm apt outdated` | `apt list --upgradable` | 过期包 |
+| `opm apt install <name>` | `apt install` | 安装 |
+| `opm apt uninstall <name>` | `apt remove` | 卸载 |
+| `opm apt upgrade <name>` | `apt upgrade` | 升级 |
+| `opm apt cache clean` | `apt clean` | 清理缓存 |
+
+## 镜像预设
+
+| 预设名 | 地址 |
+|--------|------|
+| `ubuntu-tsinghua` | `deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal main restricted universe multiverse` |
+| `ubuntu-huawei` | `deb https://mirrors.huaweicloud.com/ubuntu/ focal main restricted universe multiverse` |
+| `ubuntu-aliyun` | `deb http://mirrors.aliyun.com/ubuntu/ focal main restricted universe multiverse` |
+| `debian-official` | `deb http://deb.debian.org/debian/ bookworm main` |
+| `debian-tsinghua` | `deb https://mirrors.tuna.tsinghua.edu.cn/debian/ bookworm main` |
+
+## 示例
+
+```bash
+opm apt version
+opm apt registry set ubuntu-tsinghua
+opm apt search curl
+opm apt info curl
+opm apt install htop
+opm apt uninstall htop
+opm apt upgrade htop
+opm apt cache clean
+```

package/docs/managers/brew.md

@@ -0,0 +1,92 @@
+# brew 命令对照表
+
+`@wwkit/opm` 统一命令与 Homebrew 原始命令的映射关系（macOS）。
+
+## 命令对照
+
+| 统一命令 | 原始命令 | 说明 |
+|---------|---------|------|
+| `opm brew version` | `brew --version` | 查看 brew 本身版本 |
+| `opm brew registry` | 读 `~/.config/opm/config.json5` 的 `brew.registry.active` | 查询配置中的激活镜像（不读系统配置） |
+| `opm brew registry set <url\|preset>` | 写 `~/.config/opm/config.json5` 的 `brew.registry.active` | 设置激活镜像（支持预设名，install/upgrade 自动传 `HOMEBREW_API_DOMAIN` / `HOMEBREW_BOTTLE_DOMAIN`；仅作用于本工具发起的命令，不改系统 brew 配置） |
+| `opm brew registry presets` | — | 列出可用镜像预设 |
+| `opm brew search <name>` | `brew info --json=v2 <name>` | 查询包在源是否可用（返回最新版本 + 版本列表） |
+| `opm brew search <name> <version>` | `brew info --json=v2 <name>` | 查询指定版本是否可用 |
+| `opm brew view <name>` | `brew list --versions <name>` | 查询包是否已安装 |
+| `opm brew info <name>` | `brew info --json=v2 <name>` | 查询包详情（描述/主页/许可证/仓库等） |
+| `opm brew versions <name>` | `brew info --json=v2 <name>` | 列出所有可用版本 |
+| `opm brew list` | `brew list --versions` | 列出所有已安装包（formulae + casks） |
+| `opm brew outdated` | `brew outdated --json=v2` | 列出过期包 |
+| `opm brew install <name>` | `brew install <name>` | 安装包（formula / cask 均可） |
+| `opm brew install <name> <version>` | `brew install <name>@<version>` | 安装指定版本（versioned formula） |
+| `opm brew uninstall <name>` | `brew uninstall <name>` | 卸载包 |
+| `opm brew upgrade <name>` | `brew upgrade <name>` | 升级包到最新版本 |
+| `opm brew cache clean` | `brew cleanup -s --prune=all` | 清理缓存 |
+| `opm brew help` | — | 显示 brew 命令清单 |
+
+## 镜像预设
+
+| 预设名 | 地址 |
+|--------|------|
+| `official` | `https://ghcr.io/v2/homebrew` |
+| `tsinghua` | `https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles` |
+| `ustc` | `https://mirrors.ustc.edu.cn/homebrew-bottles` |
+
+> 镜像预设记录的是 bottle 域名；使用非 official 镜像时，`HOMEBREW_API_DOMAIN` 取 `${bottle}/api`，`HOMEBREW_BOTTLE_DOMAIN` 取 bottle 域名本身。
+
+## 选项
+
+| 选项 | 说明 |
+|------|------|
+| `-h, --help` | 显示帮助 |
+
+> 所有命令默认以 JSON 格式输出。
+
+## 示例
+
+```bash
+# 查看 brew 版本
+opm brew version
+
+# 查询当前镜像
+opm brew registry
+
+# 切换到清华镜像
+opm brew registry set tsinghua
+
+# 查询 wget 是否在源中可用
+opm brew search wget
+
+# 查看 wget 是否已安装
+opm brew view wget
+
+# 查看 wget 详情
+opm brew info wget
+
+# 列出 wget 所有可用版本
+opm brew versions wget
+
+# 列出所有已安装包
+opm brew list
+
+# 列出过期包
+opm brew outdated
+
+# 安装 wget
+opm brew install wget
+
+# 安装指定版本（versioned formula，如 python@3.12）
+opm brew install python 3.12
+
+# 卸载 wget
+opm brew uninstall wget
+
+# 升级 wget
+opm brew upgrade wget
+
+# 清理缓存
+opm brew cache clean
+
+# 显示帮助
+opm brew help
+```

package/docs/managers/bun.md

@@ -0,0 +1,50 @@
+# bun 命令对照表
+
+`@wwkit/opm` 统一命令管理 Bun 包。
+
+Bun 是全栈 JS 工具链（runtime + 包管理器 + 打包器），包管理与 npm 兼容。
+
+## 命令对照
+
+| 统一命令 | 原始命令 | 说明 |
+|---------|---------|------|
+| `opm bun version` | `bun --version` | 查看 bun 版本 |
+| `opm bun registry` | 读 `~/.config/opm/config.json5` 的 `bun.registry.active` | 查询 bun registry 镜像 |
+| `opm bun registry set <url\|preset>` | 写 `~/.config/opm/config.json5` | 设置 bun registry 镜像（传给 `BUN_CONFIG_REGISTRY`） |
+| `opm bun registry presets` | — | 列出可用镜像预设 |
+| `opm bun search <name> [version]` | HTTP 查 npm registry | 查询包是否可用 |
+| `opm bun view <name> [-g]` | 查 `node_modules/<name>/package.json` | 查询包是否已安装 |
+| `opm bun info <name>` | HTTP 查 npm registry | 显示包详情 |
+| `opm bun versions <name>` | HTTP 查 npm registry | 列出所有可用版本 |
+| `opm bun list [-g]` | `bun pm ls` | 列出已安装包 |
+| `opm bun outdated [-g]` | `bun outdated` | 列出过期包 |
+| `opm bun install <name> [version]` | `bun add <name>@<version>` | 安装包 |
+| `opm bun uninstall <name>` | `bun remove <name>` | 卸载包 |
+| `opm bun upgrade <name>` | `bun update <name>` | 升级包 |
+| `opm bun cache clean` | `bun pm cache rm` | 清理缓存 |
+
+## 镜像预设
+
+| 预设名 | 地址 |
+|--------|------|
+| `official` | `https://registry.npmjs.org/` |
+| `taobao` | `https://registry.npmmirror.com/` |
+| `huawei` | `https://cmc.centralrepo.rnd.huawei.com/artifactory/api/npm/npm-central-repo/` |
+
+> 镜像通过 `BUN_CONFIG_REGISTRY` 环境变量传递给 bun 命令。
+
+## 示例
+
+```bash
+opm bun version
+opm bun registry set taobao
+opm bun search axios
+opm bun info react
+opm bun list
+opm bun outdated
+opm bun install axios
+opm bun install react@18
+opm bun upgrade axios
+opm bun uninstall axios
+opm bun cache clean
+```

package/docs/managers/cft.md

@@ -0,0 +1,57 @@
+# cft 命令对照表
+
+`@wwkit/opm` 统一命令管理 Chrome for Testing 二进制工具（chrome + chromedriver）的下载、解压、多版本安装。
+
+## 命令对照
+
+| 统一命令 | 说明 |
+|---------|------|
+| `opm cft version` | 查看当前激活版本 |
+| `opm cft installed` | 查看是否已安装（列出本地版本） |
+| `opm cft dir` | 查看激活版本安装目录 + chrome/chromedriver 路径（供外部消费） |
+| `opm cft versions` | 列出远程可用版本（known-good-versions-with-downloads.json） |
+| `opm cft list` | 列出本地已安装版本 |
+| `opm cft install [version]` | 安装指定版本（缺省 = `config.cft.version`）；同版本已装跳过；设为 active |
+| `opm cft status [version]` | 查看版本安装状态/二进制文件校验（缺省 = 全部） |
+| `opm cft clear [version]` | 删除指定版本安装产物；不传 = 清理所有版本 |
+| `opm cft registry` | 查询激活镜像（读 `~/.config/opm/config.json5` 的 `cft.registry.active`） |
+| `opm cft registry set <url\|preset>` | 设置激活镜像 |
+| `opm cft registry presets` | 列出可用镜像预设 |
+
+## 镜像预设
+
+| 预设名 | 地址 |
+|--------|------|
+| `official` | `https://googlechromelabs.github.io/chrome-for-testing` |
+| `npmmirror` | `https://npmmirror.com/mirrors/chrome-for-testing` |
+
+默认 `active` = `npmmirror`（镜像，非 official）。
+
+## 安装目录
+
+`~/.config/opm/cft/<version>/`（尊重 `OPM_CONFIG_DIR`）
+
+```
+~/.config/opm/cft/
+  manifest.json              { active: "141.0.7390.54" }
+  <version>/
+    chrome-<os>/
+    chromedriver-<os>/
+    installed.json
+```
+
+## 示例
+
+```bash
+opm cft version
+opm cft dir
+  opm cft list
+opm cft versions
+opm cft install
+opm cft install 141.0.7390.54
+opm cft status
+opm cft status 141.0.7390.54
+opm cft clear 141.0.7390.54
+opm cft clear
+opm cft registry set official
+```