@wwkit/opm 1.0.9 → 1.0.10

package/README.md

@@ -52,11 +52,11 @@ pnpm opm <command> [args] [options]
 | `composer <action>` | composer 包管理器（PHP） |
 | `bun <action>` | bun 包管理器（Bun runtime，npm 兼容源） |
 | `winget <action>` | winget 包管理器（Windows） |
-| `nvm <action>` | nvm 自身管理（安装/升级/卸载 nvm） |
+| `nvm <action>` | nvm 自身管理（安装/升级/卸载 nvm；list 列出已安装 Node.js 版本） |
 | `node <action>` | node 版本管理（基于 nvm 安装/切换/卸载 Node.js 版本） |
-| `phpenv <action>` | phpenv 自身管理（安装/升级/卸载 phpenv） |
+| `phpenv <action>` | phpenv 自身管理（安装/升级/卸载 phpenv；list 列出已安装 PHP 版本） |
 | `php <action>` | php 版本管理（基于 phpenv 安装/切换/卸载 PHP 版本） |
-| `uv <action>` | uv 自身管理（安装/升级/卸载 uv） |
+| `uv <action>` | uv 自身管理（安装/升级/卸载 uv；list 列出已安装 Python 版本） |
 | `python <action>` | python 版本管理（基于 uv 安装/切换/卸载 Python 版本） |
 | `docker <action>` | Docker 自身管理（安装/升级/启停/open，含 daemon 状态） |
 | `homebrew <action>` | Homebrew 自身管理（安装/升级/卸载 brew） |
@@ -69,6 +69,7 @@ pnpm opm <command> [args] [options]
 | `ping <host|proxy|registry>` | 验证主机、代理或所有 registry 的可访问性 |
 | `config [section]` | 查看常用配置（proxy + 各 registry 段，段名动态生成） |
 | `opencode <action>` | opencode 运维命令（安装/升级/清理/env/open） |
+| `harness <action>` | @wwkit/harness 插件管理（安装/升级/list/status/env/dir） |
 
 ## Managers
 
@@ -100,7 +101,7 @@ pnpm opm <command> [args] [options]
 | `view <name>` | 查询包在全局与项目作用域的安装信息（仅包管理器；运行时查询版本是否已安装） |
 | `info <name>` | 查询包详情 |
 | `versions <name>` | 列出所有可用版本 |
-| `list` | 列出所有已安装包（仅 node/php/python 运行时） |
+| `list` | 列出所有已安装包（仅运行时 node/php/python 与工具组 nvm/phpenv/uv 支持） |
 | `outdated` | 列出过期包 |
 | `install <name> [version]` | 安装包 |
 | `uninstall <name>` | 卸载包 |
@@ -280,6 +281,7 @@ 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 list                          # 列出已安装 Node.js 版本
 opm nvm view                          # 检查 nvm 是否已安装
 opm nvm uninstall                     # 卸载 nvm
 ```
@@ -308,6 +310,7 @@ 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 list                       # 列出已安装 PHP 版本
 opm phpenv view                       # 检查 phpenv 是否已安装
 opm phpenv uninstall                  # 卸载 phpenv
 ```
@@ -336,6 +339,7 @@ opm uv registry set <url|preset>      # 设置安装脚本 URL（写 uv.registry
 opm uv registry presets               # 列出可用镜像预设
 opm uv install                        # 安装 uv（curl 执行 active 脚本 URL）
 opm uv upgrade                        # 更新 uv（uv self update）
+opm uv list                           # 列出已安装 Python 版本
 opm uv view                           # 检查 uv 是否已安装
 opm uv uninstall                      # 卸载 uv
 ```
@@ -548,6 +552,19 @@ opm opencode clear --dry-run           # 仅预览
 opm opencode clear -y                  # 跳过确认直接执行
 ```
 
+### harness
+
+```bash
+opm harness version                    # 查看已安装版本
+opm harness installed                  # 检查是否已安装
+opm harness install                    # 安装（使用 opm npm 镜像 + proxy）
+opm harness upgrade                    # 升级到最新
+opm harness dir                        # 查看安装路径 + skills/agents/commands 目录
+opm harness list                       # 列出包提供的 skills/agents/commands
+opm harness status                     # 健康检查（安装 + env + 内容完整性）
+opm harness env                        # 查看环境变量（OPENCODE_CONFIG_DIR 等）
+```
+
 ## npm scripts
 
 | 命令 | 说明 |

package/docs/managers/nvm.md

@@ -14,6 +14,7 @@
 | `opm nvm upgrade` | `cd ~/.nvm && git pull --tags` | 更新 nvm |
 | `opm nvm uninstall` | `rm -rf ~/.nvm` | 卸载 nvm |
 | `opm nvm dir` | 返回 `~/.nvm` 安装目录 |
+| `opm nvm list` | `nvm ls --no-colors` | 列出已安装 Node.js 版本 |
 
 ## 镜像预设
 
@@ -29,6 +30,7 @@ opm nvm version
 opm nvm registry set gitee
 opm nvm install
 opm nvm upgrade
+opm nvm list
 opm nvm dir
 opm nvm uninstall
 ```

package/docs/managers/phpenv.md

@@ -14,6 +14,7 @@
 | `opm phpenv upgrade` | `cd ~/.phpenv && git pull` + `cd plugins/php-build && git pull` | 更新 phpenv + php-build |
 | `opm phpenv uninstall` | `rm -rf ~/.phpenv` | 卸载 phpenv |
 | `opm phpenv dir` | 返回 `~/.phpenv` 安装目录 |
+| `opm phpenv list` | `phpenv versions` | 列出已安装 PHP 版本 |
 
 ## 镜像预设
 
@@ -29,6 +30,7 @@ opm phpenv version
 opm phpenv registry set gitee
 opm phpenv install
 opm phpenv upgrade
+opm phpenv list
 opm phpenv dir
 opm phpenv uninstall
 ```

package/docs/managers/uv.md

@@ -16,6 +16,7 @@ uv 是 Astral 出品的快速 Python 包/版本管理器（Rust 实现），替
 | `opm uv upgrade` | `uv self update` | 更新 uv |
 | `opm uv uninstall` | `rm ~/.local/bin/uv` + `rm -rf ~/.local/share/uv` | 卸载 uv |
 | `opm uv dir` | 返回 uv 安装目录 |
+| `opm uv list` | `uv python list --only-installed` | 列出已安装 Python 版本 |
 
 > 安装脚本 URL 通过 `uv.registry.active` 配置（`opm uv registry set <url>`）；Windows 仍使用官方 `install.ps1`。
 
@@ -28,6 +29,7 @@ opm uv registry presets
 opm uv registry set official
 opm uv install
 opm uv upgrade
+opm uv list
 opm uv dir
 opm uv uninstall
 ```

package/docs/opm.html

@@ -450,7 +450,7 @@ opm npm help</code></pre></div>
 <div id="managers_nvm" class="doc-content" style="display:none;"><h1>nvm 命令对照表</h1>
 <p><code>@wwkit/opm</code> 统一命令管理 nvm 自身（安装/升级/卸载）。</p>
 <h2>命令对照</h2>
-<table><thead><tr><th>统一命令</th><th>原始命令</th><th>说明</th></tr></thead><tbody><tr><td><code>opm nvm version</code></td><td><code>nvm --version</code></td><td>查看 nvm 版本</td></tr><tr><td><code>opm nvm registry</code></td><td>读 <code>~/.config/opm/config.json5</code> 的 <code>nvm.registry.active</code></td><td>查询 nvm git 镜像</td></tr><tr><td><code>opm nvm registry set &lt;url|preset&gt;</code></td><td>写 <code>~/.config/opm/config.json5</code></td><td>设置 nvm git 镜像</td></tr><tr><td><code>opm nvm registry presets</code></td><td>—</td><td>列出可用镜像预设</td></tr><tr><td><code>opm nvm install</code></td><td><code>git clone &lt;mirror&gt; ~/.nvm</code> + 写 shell profile</td><td>安装 nvm</td></tr><tr><td><code>opm nvm upgrade</code></td><td><code>cd ~/.nvm &amp;&amp; git pull --tags</code></td><td>更新 nvm</td></tr><tr><td><code>opm nvm uninstall</code></td><td><code>rm -rf ~/.nvm</code></td><td>卸载 nvm</td></tr><tr><td><code>opm nvm dir</code></td><td>返回 <code>~/.nvm</code> 安装目录</td></tr></tbody></table>
+<table><thead><tr><th>统一命令</th><th>原始命令</th><th>说明</th></tr></thead><tbody><tr><td><code>opm nvm version</code></td><td><code>nvm --version</code></td><td>查看 nvm 版本</td></tr><tr><td><code>opm nvm registry</code></td><td>读 <code>~/.config/opm/config.json5</code> 的 <code>nvm.registry.active</code></td><td>查询 nvm git 镜像</td></tr><tr><td><code>opm nvm registry set &lt;url|preset&gt;</code></td><td>写 <code>~/.config/opm/config.json5</code></td><td>设置 nvm git 镜像</td></tr><tr><td><code>opm nvm registry presets</code></td><td>—</td><td>列出可用镜像预设</td></tr><tr><td><code>opm nvm install</code></td><td><code>git clone &lt;mirror&gt; ~/.nvm</code> + 写 shell profile</td><td>安装 nvm</td></tr><tr><td><code>opm nvm upgrade</code></td><td><code>cd ~/.nvm &amp;&amp; git pull --tags</code></td><td>更新 nvm</td></tr><tr><td><code>opm nvm uninstall</code></td><td><code>rm -rf ~/.nvm</code></td><td>卸载 nvm</td></tr><tr><td><code>opm nvm dir</code></td><td>返回 <code>~/.nvm</code> 安装目录</td></tr><tr><td><code>opm nvm list</code></td><td><code>nvm ls --no-colors</code></td><td>列出已安装 Node.js 版本</td></tr></tbody></table>
 <h2>镜像预设</h2>
 <table><thead><tr><th>预设名</th><th>地址</th></tr></thead><tbody><tr><td><code>official</code></td><td><code>https://github.com/nvm-sh/nvm.git</code></td></tr><tr><td><code>gitee</code></td><td><code>https://gitee.com/mirrors/nvm.git</code></td></tr></tbody></table>
 <h2>示例</h2>
@@ -458,6 +458,7 @@ opm npm help</code></pre></div>
 opm nvm registry set gitee
 opm nvm install
 opm nvm upgrade
+opm nvm list
 opm nvm dir
 opm nvm uninstall</code></pre></div>
 <div id="managers_php" class="doc-content" style="display:none;"><h1>php 命令对照表</h1>
@@ -482,7 +483,7 @@ opm php upgrade</code></pre></div>
 <div id="managers_phpenv" class="doc-content" style="display:none;"><h1>phpenv 命令对照表</h1>
 <p><code>@wwkit/opm</code> 统一命令管理 phpenv 自身（安装/升级/卸载）。</p>
 <h2>命令对照</h2>
-<table><thead><tr><th>统一命令</th><th>原始命令</th><th>说明</th></tr></thead><tbody><tr><td><code>opm phpenv version</code></td><td><code>phpenv --version</code></td><td>查看 phpenv 版本</td></tr><tr><td><code>opm phpenv registry</code></td><td>读 <code>~/.config/opm/config.json5</code> 的 <code>phpenv.registry.active</code></td><td>查询 phpenv git 镜像</td></tr><tr><td><code>opm phpenv registry set &lt;url|preset&gt;</code></td><td>写 <code>~/.config/opm/config.json5</code></td><td>设置 phpenv git 镜像</td></tr><tr><td><code>opm phpenv registry presets</code></td><td>—</td><td>列出可用镜像预设</td></tr><tr><td><code>opm phpenv install</code></td><td><code>git clone &lt;mirror&gt; ~/.phpenv</code> + <code>git clone php-build</code> + 写 shell profile</td><td>安装 phpenv + php-build 插件</td></tr><tr><td><code>opm phpenv upgrade</code></td><td><code>cd ~/.phpenv &amp;&amp; git pull</code> + <code>cd plugins/php-build &amp;&amp; git pull</code></td><td>更新 phpenv + php-build</td></tr><tr><td><code>opm phpenv uninstall</code></td><td><code>rm -rf ~/.phpenv</code></td><td>卸载 phpenv</td></tr><tr><td><code>opm phpenv dir</code></td><td>返回 <code>~/.phpenv</code> 安装目录</td></tr></tbody></table>
+<table><thead><tr><th>统一命令</th><th>原始命令</th><th>说明</th></tr></thead><tbody><tr><td><code>opm phpenv version</code></td><td><code>phpenv --version</code></td><td>查看 phpenv 版本</td></tr><tr><td><code>opm phpenv registry</code></td><td>读 <code>~/.config/opm/config.json5</code> 的 <code>phpenv.registry.active</code></td><td>查询 phpenv git 镜像</td></tr><tr><td><code>opm phpenv registry set &lt;url|preset&gt;</code></td><td>写 <code>~/.config/opm/config.json5</code></td><td>设置 phpenv git 镜像</td></tr><tr><td><code>opm phpenv registry presets</code></td><td>—</td><td>列出可用镜像预设</td></tr><tr><td><code>opm phpenv install</code></td><td><code>git clone &lt;mirror&gt; ~/.phpenv</code> + <code>git clone php-build</code> + 写 shell profile</td><td>安装 phpenv + php-build 插件</td></tr><tr><td><code>opm phpenv upgrade</code></td><td><code>cd ~/.phpenv &amp;&amp; git pull</code> + <code>cd plugins/php-build &amp;&amp; git pull</code></td><td>更新 phpenv + php-build</td></tr><tr><td><code>opm phpenv uninstall</code></td><td><code>rm -rf ~/.phpenv</code></td><td>卸载 phpenv</td></tr><tr><td><code>opm phpenv dir</code></td><td>返回 <code>~/.phpenv</code> 安装目录</td></tr><tr><td><code>opm phpenv list</code></td><td><code>phpenv versions</code></td><td>列出已安装 PHP 版本</td></tr></tbody></table>
 <h2>镜像预设</h2>
 <table><thead><tr><th>预设名</th><th>地址</th></tr></thead><tbody><tr><td><code>official</code></td><td><code>https://github.com/phpenv/phpenv.git</code></td></tr><tr><td><code>gitee</code></td><td><code>https://gitee.com/mirrors/phpenv.git</code></td></tr></tbody></table>
 <h2>示例</h2>
@@ -490,6 +491,7 @@ opm php upgrade</code></pre></div>
 opm phpenv registry set gitee
 opm phpenv install
 opm phpenv upgrade
+opm phpenv list
 opm phpenv dir
 opm phpenv uninstall</code></pre></div>
 <div id="managers_pip" class="doc-content" style="display:none;"><h1>pip 命令对照表</h1>
@@ -610,7 +612,7 @@ opm python upgrade</code></pre></div>
 <p><code>@wwkit/opm</code> 统一命令管理 uv 自身（安装/升级/卸载）。</p>
 <p>uv 是 Astral 出品的快速 Python 包/版本管理器（Rust 实现），替代 pyenv + pip。</p>
 <h2>命令对照</h2>
-<table><thead><tr><th>统一命令</th><th>原始命令</th><th>说明</th></tr></thead><tbody><tr><td><code>opm uv version</code></td><td><code>uv --version</code></td><td>查看 uv 版本</td></tr><tr><td><code>opm uv registry</code></td><td>读 <code>~/.config/opm/config.json5</code> 的 <code>uv.registry.active</code></td><td>查询激活的安装脚本 URL</td></tr><tr><td><code>opm uv registry set &lt;url|preset&gt;</code></td><td>写 <code>~/.config/opm/config.json5</code> 的 <code>uv.registry.active</code></td><td>设置激活安装脚本 URL（支持预设名）</td></tr><tr><td><code>opm uv registry presets</code></td><td>—</td><td>列出可用镜像预设</td></tr><tr><td><code>opm uv install</code></td><td><code>curl -LsSf &lt;active&gt; | sh</code></td><td>安装 uv（脚本 URL 来自 <code>uv.registry.active</code>）</td></tr><tr><td><code>opm uv upgrade</code></td><td><code>uv self update</code></td><td>更新 uv</td></tr><tr><td><code>opm uv uninstall</code></td><td><code>rm ~/.local/bin/uv</code> + <code>rm -rf ~/.local/share/uv</code></td><td>卸载 uv</td></tr><tr><td><code>opm uv dir</code></td><td>返回 uv 安装目录</td></tr></tbody></table>
+<table><thead><tr><th>统一命令</th><th>原始命令</th><th>说明</th></tr></thead><tbody><tr><td><code>opm uv version</code></td><td><code>uv --version</code></td><td>查看 uv 版本</td></tr><tr><td><code>opm uv registry</code></td><td>读 <code>~/.config/opm/config.json5</code> 的 <code>uv.registry.active</code></td><td>查询激活的安装脚本 URL</td></tr><tr><td><code>opm uv registry set &lt;url|preset&gt;</code></td><td>写 <code>~/.config/opm/config.json5</code> 的 <code>uv.registry.active</code></td><td>设置激活安装脚本 URL（支持预设名）</td></tr><tr><td><code>opm uv registry presets</code></td><td>—</td><td>列出可用镜像预设</td></tr><tr><td><code>opm uv install</code></td><td><code>curl -LsSf &lt;active&gt; | sh</code></td><td>安装 uv（脚本 URL 来自 <code>uv.registry.active</code>）</td></tr><tr><td><code>opm uv upgrade</code></td><td><code>uv self update</code></td><td>更新 uv</td></tr><tr><td><code>opm uv uninstall</code></td><td><code>rm ~/.local/bin/uv</code> + <code>rm -rf ~/.local/share/uv</code></td><td>卸载 uv</td></tr><tr><td><code>opm uv dir</code></td><td>返回 uv 安装目录</td></tr><tr><td><code>opm uv list</code></td><td><code>uv python list --only-installed</code></td><td>列出已安装 Python 版本</td></tr></tbody></table>
 <blockquote>安装脚本 URL 通过 <code>uv.registry.active</code> 配置（<code>opm uv registry set &lt;url&gt;</code>）；Windows 仍使用官方 <code>install.ps1</code>。</blockquote>
 <h2>示例</h2>
 <pre><code class="lang-bash">opm uv version
@@ -619,6 +621,7 @@ opm uv registry presets
 opm uv registry set official
 opm uv install
 opm uv upgrade
+opm uv list
 opm uv dir
 opm uv uninstall</code></pre></div>
 <div id="packages_opencode" class="doc-content" style="display:none;"><h1>opencode 命令对照</h1>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwkit/opm",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "author": "bluesliu <langcai163@163.com>",
   "description": "Unified CLI — package management (npm/pip/dnf/apt) + config view + opencode maintenance",
   "type": "module",
@@ -35,8 +35,8 @@
     "basic-ftp": "^6.2.1",
     "extract-zip": "^2.0.1",
     "systeminformation": "^5.23.0",
-    "@wwkit/harness": "1.0.18",
-    "@wwkit/shared": "1.0.12"
+    "@wwkit/harness": "1.0.19",
+    "@wwkit/shared": "1.0.14"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/src/cli/groups/ensure.js

@@ -21,6 +21,18 @@ const RUNTIMES = {
   python: () => new PythonManager(),
 }
 
+/**
+ * 按前缀（x 或 x.y）匹配已安装版本列表，返回完整版本号
+ * @param {{ version: string }[]} items
+ * @param {string} version
+ * @returns {string}
+ */
+export function resolveVersion(items, version) {
+  const v = version.replace(/^v/, '')
+  const hit = items.find((i) => i.version.replace(/^v/, '').startsWith(v))
+  return hit ? hit.version : ''
+}
+
 export class EnsureGroup {
   constructor() {
     this.name = 'ensure'
@@ -47,11 +59,18 @@ export class EnsureGroup {
 
     let satisfied = false
     let currentVersion = ''
+    let installVersion = ''
 
     if (version) {
-      const result = await manager.isInstalled(version)
-      satisfied = result.installed
-      if (satisfied) currentVersion = result.version || version
+      // 支持 x / x.y 简写：按前缀匹配已安装版本
+      const installed = await manager.listInstalled()
+      const full = resolveVersion(installed, version)
+      if (full) {
+        satisfied = true
+        currentVersion = full
+      } else {
+        installVersion = version
+      }
     } else {
       const result = await manager.getVersion()
       satisfied = result.installed
@@ -63,7 +82,9 @@ export class EnsureGroup {
       return
     }
 
-    const installVersion = version || (manager.getDefaultVersion ? manager.getDefaultVersion() : '')
+    if (!installVersion) {
+      installVersion = manager.getDefaultVersion ? manager.getDefaultVersion() : ''
+    }
     if (!installVersion) {
       console.error(`No version specified and no defaultVersion configured for ${runtime}`)
       process.exit(1)

package/src/cli/groups/nvm.js

@@ -13,7 +13,7 @@ import os from 'node:os'
 import { ToolManagerGroup } from './version-manager.js'
 import { Shell } from '@wwkit/shared'
 import { getActiveRegistry } from '../../config.js'
-import { installNvm } from '../../managers/node.js'
+import { installNvm, parseNvmInstalled } from '../../managers/node.js'
 
 const shell = new Shell()
 
@@ -35,6 +35,8 @@ export class NvmGroup extends ToolManagerGroup {
       getPath: () => getNvmDir(),
       versionCmd: () => `source "${path.join(getNvmDir(), 'nvm.sh')}" && nvm --version`,
       parseVersion: (out) => out.trim(),
+      listCmd: () => `source "${path.join(getNvmDir(), 'nvm.sh')}" && nvm ls --no-colors`,
+      parseList: parseNvmInstalled,
       install: (proxy) => installNvm(proxy),
       upgrade: () => {
         const nvmDir = getNvmDir()
@@ -62,6 +64,7 @@ export class NvmGroup extends ToolManagerGroup {
         ['upgrade', 'Update nvm (git pull)'],
         ['uninstall', 'Remove nvm (~/.nvm)'],
         ['dir', 'Show nvm install directory'],
+        ['list', 'List installed Node.js versions (nvm ls --no-colors)'],
         ['help', 'Show this help'],
       ],
       examples: [
@@ -71,6 +74,7 @@ export class NvmGroup extends ToolManagerGroup {
         'opm nvm install',
         'opm nvm upgrade',
         'opm nvm dir',
+        'opm nvm list',
       ],
     })
   }

package/src/cli/groups/phpenv.js

@@ -14,7 +14,7 @@ import os from 'node:os'
 import { ToolManagerGroup } from './version-manager.js'
 import { Shell } from '@wwkit/shared'
 import { getActiveRegistry } from '../../config.js'
-import { installPhpenv } from '../../managers/php.js'
+import { installPhpenv, parsePhpenvInstalled } from '../../managers/php.js'
 
 const shell = new Shell()
 
@@ -47,6 +47,8 @@ export class PhpenvGroup extends ToolManagerGroup {
         const m = out.trim().match(/phpenv\s+([\d.]+)/)
         return m ? m[1] : out.trim()
       },
+      listCmd: () => `${getPhpenvBin()} versions`,
+      parseList: parsePhpenvInstalled,
       install: () => installPhpenv(),
       upgrade: () => {
         execSync(`cd "${getPhpenvRoot()}" && git remote set-url origin "${getActiveRegistry('phpenv')}" && git pull --tags`, {
@@ -74,6 +76,7 @@ export class PhpenvGroup extends ToolManagerGroup {
         ['upgrade', 'Update phpenv and php-build plugin (git pull)'],
         ['uninstall', 'Remove phpenv (~/.phpenv)'],
         ['dir', 'Show phpenv install directory'],
+        ['list', 'List installed PHP versions (phpenv versions)'],
         ['help', 'Show this help'],
       ],
       examples: [
@@ -83,6 +86,7 @@ export class PhpenvGroup extends ToolManagerGroup {
         'opm phpenv install',
         'opm phpenv upgrade',
         'opm phpenv dir',
+        'opm phpenv list',
       ],
     })
   }

package/src/cli/groups/uv.js

@@ -11,7 +11,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
 import { ToolManagerGroup } from './version-manager.js'
-import { installUv, getUvBin } from '../../managers/python.js'
+import { installUv, getUvBin, parseUvInstalled } from '../../managers/python.js'
 
 export class UvGroup extends ToolManagerGroup {
   constructor() {
@@ -29,6 +29,8 @@ export class UvGroup extends ToolManagerGroup {
       getPath: () => getUvBin(),
       versionCmd: () => `${getUvBin()} --version`,
       parseVersion: (out) => out.trim(),
+      listCmd: () => `${getUvBin()} python list --only-installed`,
+      parseList: parseUvInstalled,
       install: (proxy) => installUv(proxy),
       upgrade: () => {
         execSync(`${getUvBin()} self update`, { stdio: 'inherit' })
@@ -56,6 +58,7 @@ export class UvGroup extends ToolManagerGroup {
         ['upgrade', 'Update uv (uv self update)'],
         ['uninstall', 'Remove uv (~/.local/bin/uv + ~/.local/share/uv)'],
         ['dir', 'Show uv install directory'],
+        ['list', 'List installed Python versions (uv python list --only-installed)'],
         ['help', 'Show this help'],
       ],
       examples: [
@@ -67,6 +70,7 @@ export class UvGroup extends ToolManagerGroup {
         'opm uv install',
         'opm uv upgrade',
         'opm uv dir',
+        'opm uv list',
         'opm uv uninstall',
       ],
     })

package/src/cli/groups/version-manager.js

@@ -25,6 +25,8 @@ const shell = new Shell()
  * @property {() => string} getPath - view 展示的安装路径
  * @property {() => string} versionCmd - 返回查询版本的 shell 命令
  * @property {(out: string) => string} [parseVersion] - 解析版本输出
+ * @property {() => string} [listCmd] - 返回列出已安装版本的 shell 命令（缺省则 list 输出空列表）
+ * @property {(out: string) => { name: string, version: string, current: boolean }[]} [parseList] - 解析 list 输出
  * @property {(proxy?: string) => Object} install - 安装并返回结果字段（失败时 throw）
  * @property {() => Object} upgrade - 升级并返回结果字段（失败时 throw）
  * @property {() => Object} uninstall - 卸载并返回结果字段（失败时 throw）
@@ -81,6 +83,8 @@ export class ToolManagerGroup {
         return this._uninstall(parsed)
       case 'dir':
         return this._dir()
+      case 'list':
+        return this._list()
       default:
         console.error(`Unknown action: ${action}`)
         this.printHelp()
@@ -193,6 +197,29 @@ const out = execSync(this.cfg.versionCmd(), { encoding: 'utf8', shell: shell.she
     output(result)
   }
 
+  /**
+   * 列出工具已安装的版本
+   * @returns {void}
+   * @private
+   */
+  _list() {
+    if (!this.cfg.isInstalled()) {
+      output({ name: this.name, installed: false, hint: `Run \`opm ${this.name} install\` first` })
+      return
+    }
+    if (!this.cfg.listCmd) {
+      output({ name: this.name, count: 0, versions: [] })
+      return
+    }
+    try {
+      const out = execSync(this.cfg.listCmd(), { encoding: 'utf8', shell: shell.shellForExec(this.cfg.needsBash) })
+      const versions = this.cfg.parseList ? this.cfg.parseList(out) : []
+      output({ name: this.name, count: versions.length, versions })
+    } catch {
+      output({ name: this.name, count: 0, versions: [] })
+    }
+  }
+
   printHelp() {
     const actionLines = this.cfg.actions.map(([sig, desc]) => `  ${sig.padEnd(34)} ${desc}`).join('\n')
     const exampleLines = this.cfg.examples.map((e) => `  ${e}`).join('\n')

package/src/cli/index.js

@@ -27,6 +27,7 @@ import { ShareGroup } from '../tools/share/index.js'
 import { WebworkGroup } from '../tools/webwork/index.js'
 import { HarnessGroup } from '../harnesses/base.js'
 import { opencodeHarness } from '../harnesses/opencode/index.js'
+import { harnessCfg } from '../harnesses/harness/index.js'
 import { CftGroup } from '../binaries/cft/index.js'
 import { generateDocHtml } from './doc.js'
 
@@ -59,6 +60,7 @@ const GROUPS = {
   uv: new UvGroup(),
   config: new ConfigGroup(),
   opencode: new HarnessGroup(opencodeHarness),
+  harness: new HarnessGroup(harnessCfg),
   cft: new CftGroup(),
   ensure: new EnsureGroup(),
   ping: new PingGroup(),

package/src/harnesses/base.js

@@ -2,7 +2,12 @@
  * AI harness 统一命令组基类
  *
  * 各 harness（opencode / claude / …）共享同一套命令：
- *   version / installed / install / uninstall / upgrade / config / clear / dir
+ *   version / installed / install / uninstall / upgrade / config / clear / dir / env
+ * 内容型 harness（harness/@wwkit/harness 插件）额外提供：
+ *   list（列出 skills/agents/commands） / status（安装 + env 健康检查）
+ *
+ * 支持的动作按 cfg 能力动态裁剪（_supportedActions）：只有 cfg 提供了对应的
+ * 实现（list/status/clear/getConfigFile/getEnvVars）时才出现在帮助与路由中。
  *
  * install/uninstall/upgrade 委托 NpmManager（global），自动使用 opm 配置的
  * npm registry 镜像与 proxy，而非裸 npm。
@@ -25,7 +30,9 @@ const ACTIONS = {
   upgrade:    { desc: 'Upgrade to latest via npm -g (uses opm npm registry + proxy)' },
   config:     { desc: 'Show config file content' },
   clear:      { desc: 'Clear sessions / data' },
-  dir:        { desc: 'Show data / db / log / config paths' },
+  dir:        { desc: 'Show install / data / db / log / config paths' },
+  list:       { desc: 'List installed content (skills/agents/commands)' },
+  status:     { desc: 'Show install status + environment health' },
   env:        { desc: 'Show harness environment variables' },
   help:       { desc: 'Show this help' },
 }
@@ -35,12 +42,15 @@ const ACTIONS = {
  * @property {string} name - harness 名（命令名）
  * @property {string} desc - 描述
  * @property {string} npmPackage - npm 全局包名
- * @property {() => string|null} getConfigFile - 配置文件路径
- * @property {() => string} getDataDir - 数据目录
- * @property {() => string} getDbPath - DB 路径
- * @property {() => string} getLogPath - 日志路径
- * @property {(argv: string[]) => Promise<void>} clear - 清理实现
+ * @property {() => string|null} [getConfigFile] - 配置文件路径
+ * @property {() => string} [getDataDir] - 数据目录
+ * @property {() => string} [getDbPath] - DB 路径
+ * @property {() => string} [getLogPath] - 日志路径
+ * @property {(argv: string[]) => Promise<void>} [clear] - 清理实现
  * @property {string[][]} [clearOptions] - clear 子选项帮助 [flag, desc]
+ * @property {() => Promise<Object>} [list] - 列出包内容（skills/agents/commands）
+ * @property {() => Promise<Object>} [status] - 安装/环境健康检查
+ * @property {() => Promise<Object>} [dirInfo] - 自定义 dir 输出（覆盖默认 npm install 路径）
  */
 
 export class HarnessGroup {
@@ -62,9 +72,19 @@ export class HarnessGroup {
     }
 
     if (!action || !ACTIONS[action]) {
+      if (!this.cfg.open) {
+        this.printHelp()
+        return
+      }
       return this._open(argv)
     }
 
+    if (!this._supportedActions().includes(action)) {
+      console.error(`Action "${action}" is not supported for ${this.cfg.name}`)
+      this.printHelp()
+      process.exit(1)
+    }
+
     switch (action) {
       case 'version':
         return this._version()
@@ -82,6 +102,10 @@ export class HarnessGroup {
         return this._clear(rest)
       case 'dir':
         return this._dir()
+      case 'list':
+        return this._list()
+      case 'status':
+        return this._status()
       case 'env':
         return this._env()
       default:
@@ -91,6 +115,23 @@ export class HarnessGroup {
     }
   }
 
+  /**
+   * 本 harness 支持的动作列表（按 cfg 能力动态裁剪）
+   * @returns {string[]}
+   * @private
+   */
+  _supportedActions() {
+    return Object.keys(ACTIONS).filter((sig) => {
+      if (sig === 'help') return true
+      if (sig === 'list') return Boolean(this.cfg.list)
+      if (sig === 'status') return Boolean(this.cfg.status)
+      if (sig === 'clear') return Boolean(this.cfg.clear)
+      if (sig === 'config') return Boolean(this.cfg.getConfigFile)
+      if (sig === 'env') return Boolean(this.cfg.getEnvVars)
+      return true
+    })
+  }
+
   /**
    * 解析 proxy（-p/--proxy 优先，否则回退配置 active proxy）
    * @param {string[]} argv
@@ -152,6 +193,22 @@ export class HarnessGroup {
     output({ file, content })
   }
 
+  async _list() {
+    if (!this.cfg.list) {
+      output({ name: this.cfg.name, error: 'list not supported for this harness' })
+      return
+    }
+    output(await this.cfg.list())
+  }
+
+  async _status() {
+    if (!this.cfg.status) {
+      output({ name: this.cfg.name, error: 'status not supported for this harness' })
+      return
+    }
+    output(await this.cfg.status())
+  }
+
   async _clear(rest) {
     const parsed = parseFlags(rest)
     if (parsed.flags.help === 'true') {
@@ -162,6 +219,10 @@ export class HarnessGroup {
   }
 
   async _dir() {
+    if (this.cfg.dirInfo) {
+      output(await this.cfg.dirInfo())
+      return
+    }
     const npm = new NpmManager()
     const npmResult = await npm.isInstalled(this.cfg.npmPackage, { global: true })
     const configFile = this.cfg.getConfigFile()
@@ -218,18 +279,34 @@ export class HarnessGroup {
   }
 
   printHelp() {
-    const actionLines = Object.entries(ACTIONS)
-      .map(([sig, { desc }]) => `  ${sig.padEnd(12)} ${desc}`)
+    const actionLines = this._supportedActions()
+      .map((sig) => `  ${sig.padEnd(12)} ${ACTIONS[sig].desc}`)
       .join('\n')
 
     let clearSection = ''
-    if (this.cfg.clearOptions && this.cfg.clearOptions.length > 0) {
+    if (this._supportedActions().includes('clear') && this.cfg.clearOptions && this.cfg.clearOptions.length > 0) {
       const optLines = this.cfg.clearOptions
         .map(([flag, desc]) => `  ${flag.padEnd(20)} ${desc}`)
         .join('\n')
       clearSection = `\nClear options:\n${optLines}\n`
     }
 
+    const supported = this._supportedActions()
+    const examples = [
+      '  opm ' + this.cfg.name + ' version',
+      '  opm ' + this.cfg.name + ' install',
+      '  opm ' + this.cfg.name + ' upgrade',
+      ...(supported.includes('list') ? [`  opm ${this.cfg.name} list`] : []),
+      ...(supported.includes('status') ? [`  opm ${this.cfg.name} status`] : []),
+      ...(supported.includes('env') ? [`  opm ${this.cfg.name} env`] : []),
+      ...(supported.includes('dir') ? [`  opm ${this.cfg.name} dir`] : []),
+    ]
+    if (this.cfg.open) {
+      examples.push(`  opm ${this.cfg.name}                           Launch TUI in current directory`)
+      examples.push(`  opm ${this.cfg.name} -d /path/to/project`)
+      examples.push(`  opm ${this.cfg.name} -c config --agent work    Pass through args to opencode`)
+    }
+
     console.log(`
 Usage: opm ${this.cfg.name} <action> [options]
 
@@ -242,16 +319,7 @@ Options:
   -h, --help          Show this help
 
 Examples:
-  opm ${this.cfg.name} version
-  opm ${this.cfg.name} install
-  opm ${this.cfg.name} upgrade
-  opm ${this.cfg.name} config
-  opm ${this.cfg.name} clear
-  opm ${this.cfg.name} dir
-  opm ${this.cfg.name} env
-  opm ${this.cfg.name}                           Launch TUI in current directory
-  opm ${this.cfg.name} -d /path/to/project
-  opm ${this.cfg.name} -c config --agent work    Pass through args to opencode
+${examples.join('\n')}
 `)
   }
 }