wpops 0.1.1 → 0.2.0

package/README.md

@@ -5,7 +5,7 @@
 [![license](https://img.shields.io/npm/l/wpops.svg)](LICENSE)
 [![node](https://img.shields.io/node/v/wpops.svg)](package.json)
 
-> WordPress REST operations toolkit — a zero-dependency CLI (plus agent skill) to manage posts, pages, media, comments, users and plugins across one or many sites.
+> WordPress REST operations toolkit — a zero-dependency CLI (plus agent skill) to manage posts, pages, media, comments, users, navigation menus and plugins across one or many sites.
 
 WordPress REST 操作工具。只依赖 Node 内置能力(无第三方包),用应用密码通过
 `/wp-json/` 管理站点内容与插件。
@@ -64,6 +64,14 @@ npm publish
 > 白名单不含 `sites/`。每台机器各自 `wpops setup`,工具与 skill 都不携带密钥。
 > `WPOPS_SKIP_SKILL=1 npm i -g wpops` 可跳过自动装 skill;`wpops install-skill` 可手动补装。
 
+### 本机(开发) vs 其他机器(使用)
+
+- **本机开发**:`pnpm add -g .` 会在 pnpm 全局建一个**指向本仓库的 Junction**,
+  于是命令行的 `wpops` 就是**源码实时版** —— 改代码立即生效,无需重装。
+  验证:`where.exe wpops`(应指向 `...\pnpm\bin`)。
+- **其他机器使用**:`npm i -g wpops`,装的是 **npm 上发布的版本**;升级用 `npm i -g wpops@latest`。
+- `npx wpops ...` 只在临时缓存里跑一次,不落 PATH。
+
 ## 1. 配置
 
 给每个站点建一个档案。**推荐用向导**:`wpops setup`(问 URL/用户名/应用密码,自动写入并体检)。
@@ -101,6 +109,11 @@ node bin/wpops.js doctor
 
 ## 3. 命令
 
+> **现查现用**:`wpops help <组>` 或 `wpops <组> --help` 看某组动作与参数;`wpops commands --json` 拿机器可读清单(全部组/动作/是否写操作)。
+> 帮助与清单都由 `lib/spec.js` 单一事实来源生成,不会和实现漂移。
+>
+> **退出码**:`0` 成功;`2` 用法/参数错误(stderr 打印错误 + 精简用法 + `--help` 提示);`1` 运行期错误(HTTP/网络/配置)。`--help` 始终走 stdout 且为 `0`。
+
 ```
 # 内容
 wpops posts  list [--per-page 10] [--page 2] [--status draft] [--search 关键词]
@@ -118,6 +131,8 @@ wpops me
 wpops media  list [--per-page 20] [--media-type image]
 wpops media  get <id>
 wpops media  upload ./pic.jpg [--title "标题"] [--alt "替代文本"]
+wpops media  sideload --url https://example.com/pic.jpg [--title "标题"]   # 从 URL 导入
+wpops media  edit-image <id> --rotation 90 [--crop] [--dest-width 800]     # 裁剪/旋转(缺 --src 自动取当前图)
 wpops media  update <id> [--alt "替代文本"] [--caption "说明"] [--post 123]
 wpops media  delete <id>
 
@@ -138,6 +153,68 @@ wpops users  update <id> --role editor
 wpops users  delete <id> --force [--reassign 1]   # 有内容的用户需指定内容转交人
 wpops users  me
 
+# 导航菜单(接口由插件提供;核心 REST 没有)
+wpops menus  list [--per-page 100]                # 列出菜单(id / name / slug / locations)
+wpops menus  get <id>
+wpops menu-items list [--menus 190] [--search 词] [--per-page 100] [--page 1]
+wpops menu-items get <id>
+wpops menu-items create --title "Projects" --url https://example.com/projects --menus 190 --menu-order 6
+wpops menu-items create --title "Projects" --menus 190 --type post_type --object page --object-id 4976
+wpops menu-items update <id> --menu-order 3 [--parent 4979] [--target _blank]
+wpops menu-items delete <id> --dry-run            # 预览不需要 --force
+wpops menu-items delete <id> --force              # 真正删除才必须 --force(不可撤销)
+wpops menus  create --name Header --locations header,mobile
+wpops menus  update 190 --locations header,mobile  # 位置分配靠更新菜单的 locations
+wpops menus  delete 190 --force
+
+# 搜索 / 站点设置 / 自省
+wpops search 关键词 [--type post] [--subtype post] [--per-page 10]
+wpops settings                                     # 查看站点设置
+wpops settings update --title "新标题" [--description "..."] [--timezone Asia/Shanghai] [--posts-per-page 10]
+wpops settings update --data '{"show_on_front":"page"}'
+wpops types list|get <type>                        # 已注册文章类型(含 rest_base)
+wpops taxonomies list|get <tax>                    # 已注册分类法
+wpops statuses                                     # 文章状态
+
+# 任意自定义类型(show_in_rest 的 CPT / 自定义分类)
+wpops content list books [--per-page 10]           # rest_base 直接当 type
+wpops content get  books 12
+wpops content create books --title "..." [--status draft]
+wpops content update books 12 --title "..."
+wpops content delete books 12 --force
+wpops terms list genres                            # 自定义分类法同理
+
+# 修订 / 区块 / 区块主题结构
+wpops revisions list <id> [--type posts|pages]
+wpops revisions get <id> <rev>
+wpops revisions restore <id> <rev>                 # 用旧修订覆盖正文
+wpops revisions delete <id> <rev> --force
+wpops blocks list|get|create|update|delete ...     # 可复用区块
+wpops navigation list|get|create|update|delete ... # 区块主题导航
+wpops templates list|get|update ...                # 模板(update --content/--from-file)
+wpops template-parts list|get|update ...
+wpops global-styles get <id> · global-styles update <id> --styles '{"...":...}'
+
+# 小工具 / 应用密码 / 插件能力
+wpops widgets list|get|create|update|delete ...    # --id --sidebar --instance JSON
+wpops sidebars list|get|update ...                 # update --widgets a,b,c
+wpops app-passwords list [--user me]               # 列出应用密码(不含明文)
+wpops app-passwords create --name ci-token [--user me]   # 明文密码只打印这一次
+wpops app-passwords delete <uuid> --force
+wpops abilities list|get|run <name> [--input JSON] # Abilities API(需插件)
+wpops health list · health <test>                  # 站点健康测试(需插件)
+wpops batch --requests '[{"method":"DELETE","path":"/wp/v2/menu-items/123"}]'  # 仅 POST/PUT/PATCH/DELETE
+
+# 输出与批量
+wpops posts list --all-pages                       # 自动翻完所有页
+wpops posts list --fields id,title,status --csv    # 字段投影 / CSV(--table 表格)
+wpops menus list --quiet                           # 只出错时输出
+wpops menus list --output menus.txt                # 写入文件
+wpops sites show qnnp.me                            # 查看站点配置(密码打码)
+wpops sites rm qnnp.me · sites rename 旧 新         # 管理站点档案(确认后再用)
+wpops completion bash                              # 输出补全脚本
+wpops help menus                                   # 某组用法
+
 # 插件 / 主题(见下方能力说明)
 wpops plugins list [--status active] [--search 关键词]
 wpops plugins install <wordpress.org 别名> [--activate]
@@ -193,10 +270,17 @@ wpops --all plugins list      # 巡检所有站的插件
 | 事项 | 核心 REST 能做到吗 |
 |---|---|
 | 文章 / 页面 / 媒体 / 分类 / 标签 / 评论 / 用户的增删改查 | ✅ 完整 |
+| 搜索、站点设置(site title/时区/…)、类型/分类/状态自省 | ✅ |
+| 自定义类型 / 自定义分类(`show_in_rest` 的 CPT) | ✅(`content` / `terms` 通用命令) |
+| 修订历史(列/看/删/恢复)、可复用区块、区块主题导航/模板/全局样式 | ✅ |
+| 小工具 / 边栏、用户应用密码 | ✅ |
+| 导航菜单 / 菜单项(列表、增删改) | ⚠️ 需站点装有暴露 `/menus`、`/menu-items` 的插件 |
 | 插件:列出、**安装**(按 wp.org 别名)、启用/停用、删除 | ✅ |
 | 插件:**更新已装插件代码** | ❌ 核心 REST 没有该端点 |
 | 主题:列出、切换 | ✅ |
 | 主题:安装 / 更新 | ❌ |
+| Abilities API(`abilities list/run`)、站点健康测试(`health`) | ⚠️ 需对应插件 |
+| 批量请求(`batch`) | ✅(仅 POST/PUT/PATCH/DELETE,核心限制) |
 | WordPress 核心更新 | ❌ |
 | 备份 / 数据库优化 / 缓存清理 | ❌(需服务器侧) |
 
@@ -209,16 +293,18 @@ wpops --all plugins list      # 巡检所有站的插件
 
 - `sites/*.env` 存放应用密码,等同于该账号登录凭据;专用账号 + 可随时在后台吊销。
 - 应用密码要求 HTTPS。
-- **写操作前先 `--dry-run` 预览**;破坏性操作(`delete --force`、分类/用户删除)另需 `--force`。
+- **写操作前先 `--dry-run` 预览**(`delete` 的预览不需要 `--force`);真正执行破坏性删除(`delete --force`、分类/用户/菜单项删除)才必须加 `--force`。
 - **`--all` 的写操作必须加 `--yes`**,否则直接拒绝,避免手滑波及全线。
 - 网络抖动/429/5xx 会自动重试(默认 2 次,幂等方法才重试网络错误)。
 - 这是本地脚本,不对外开端口。
 
-## 7. 与 WordPress skills 的关系
+## 7. 自洽执行器
+
+本项目是**执行器**(真正发请求),内置 agent skill(`skills/wpops/SKILL.md`)自洽、不依赖其他 skill:
+它只讲清**何时用、安全流程、能力索引、如何现查现用**(`wpops help` / `wpops commands --json` / `wpops raw`),
+精确的字段与枚举一律在运行时向 CLI 或站点查询,因此不会随文档过时。
 
-本项目是**执行器**(真正发请求);已安装的官方 skills
-(`wp-rest-api`、`wp-wpcli-and-ops`、`wp-performance`、`wordpress-router`)
-是**知识/规范**,指导"该怎么安全地做"。
+更广义的 WordPress 知识(主题/插件开发、WP-CLI 运维、性能等)属于其他领域,与本工具正交,按需另取即可。
 
 ## 8. 全局命令(可选)
 

package/bin/wpops.js

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
-import { loadEnv, listSites } from '../lib/env.js';
-import { buildConfig, createClient, WpError } from '../lib/client.js';
+import { existsSync, readFileSync, writeFileSync, rmSync, renameSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { loadEnv, listSites, configHome } from '../lib/env.js';
+import { WpError } from '../lib/client.js';
+import { UsageError } from '../lib/errors.js';
 import { parseArgs, isMutation } from '../lib/args.js';
 import { installSkill } from '../lib/skill.js';
-import * as cmd from '../lib/commands.js';
-
-function printJson(value) {
-  console.log(JSON.stringify(value, null, 2));
-}
+import { configureOutput } from '../lib/util.js';
+import { runOne } from '../lib/run.js';
+import { generalHelp, groupHelp, commandsJson, usageHint } from '../lib/help.js';
+import { completionWords, groupByName } from '../lib/spec.js';
+import { setup } from '../lib/commands.js';
 
 function version() {
   try {
@@ -18,68 +20,6 @@ function version() {
   }
 }
 
-function printHelp() {
-  console.log(`wpops —— WordPress REST 操作工具
-
-用法: wpops [--site 名字 | --all] <组> <动作> [参数] [--flags]
-
-  --version / -v                  显示版本
-
-  setup                           交互式配置一个站点(写入 sites/<名字>.env 并体检)
-  doctor                          连接与权限体检(先跑这个)
-  me                              当前用户与能力
-  sites                           列出已配置的站点
-  install-skill                   把内置 skill 装到 agent 发现目录
-
-  posts      list|get|create|update|delete ...
-  pages      list|get|create|update|delete ...
-  media      list|get|upload|update|delete ...
-  plugins    list|install|activate|deactivate ...
-  themes     list|activate ...
-  categories list|get|create|update|delete ...
-  tags       list|get|create|update|delete ...
-  comments   list|get|update|delete ...
-  users      list|get|create|update|delete|me ...
-  raw <METHOD> <path> [--data JSON]   任意端点兜底
-
-多站点:
-  --site <名字> / -s <名字>        对 sites/<名字>.env 执行
-  --all / -a                       对所有已配置站点批量执行(写操作需 --yes)
-
-安全:
-  --dry-run                       只预览不执行(写操作)
-  --yes / -y                      --all 写操作的确认开关
-
-常用参数:
-  --per-page N · --page N         分页(REST 上限 100)
-  --status <s>                    状态(posts/comments 等)
-  --search <s> · --orderby <f> · --order <asc|desc>
-  --categories 1,2 · --tags 3,4   分类/标签 ID(过滤或设置)
-  --author <id> · --after <日期> · --before <日期>
-  --title/--content/--from-file   标题/正文
-  --slug <s> · --excerpt <s>      别名 / 摘要
-  --featured-media <id>           特色图
-  --alt <文本> · --caption <文本> 媒体替代文本 / 说明
-  --name/--parent/--description   分类/标签字段
-  --username/--email/--role       用户字段
-  --force                         彻底删除 / 危险操作确认
-  --data <JSON>                   raw 的请求体
-  --json                          输出原始 JSON
-
-示例:
-  wpops doctor
-  wpops -s blog-a posts list --per-page 5 --orderby date --order desc
-  wpops posts list --categories 3,7
-  wpops posts update 12 --from-file ./post.md --status draft
-  wpops media update 44 --alt "配图"
-  wpops categories list
-  wpops comments list --status hold
-  wpops --all posts list
-  wpops --all plugins list
-  wpops --all posts delete 5 --dry-run
-  wpops plugins install wp-super-cache --activate`);
-}
-
 function printSites() {
   const sites = listSites();
   if (!sites.length) {
@@ -100,221 +40,210 @@ function printSites() {
   }
 }
 
-async function runOne(site, group, action, rest, flags, showHeader) {
-  const cfg = buildConfig(loadEnv(site));
-  const client = createClient(cfg);
+// ------------------------------------------------------------------ sites 管理
+
+const SENSITIVE = /PASSWORD|SECRET|TOKEN|KEY/i;
 
-  if (showHeader) {
-    console.log(`\n=== ${site || '(default)'} — ${cfg.url || '(未配置 WP_URL)'} ===`);
+function sitesCommand(action, rest) {
+  const dir = join(configHome(), 'sites');
+  switch (action) {
+    case undefined:
+    case 'list':
+      return printSites();
+    case 'show': {
+      const name = rest[0];
+      if (!name) throw new Error('sites show 需要站点名');
+      const env = loadEnv(name);
+      console.log(`站点 ${name}:`);
+      for (const [key, value] of Object.entries(env)) {
+        console.log(`  ${key}=${SENSITIVE.test(key) ? '***' : value}`);
+      }
+      return;
+    }
+    case 'rm': {
+      const name = rest[0];
+      if (!name) throw new Error('sites rm 需要站点名');
+      const file = join(dir, `${name}.env`);
+      if (!existsSync(file)) throw new Error(`找不到站点配置 ${file}`);
+      rmSync(file);
+      console.log(`✓ 已删除站点配置 ${name}`);
+      return;
+    }
+    case 'rename': {
+      const [from, to] = rest;
+      if (!from || !to) throw new Error('sites rename 需要 <旧名> <新名>');
+      const src = join(dir, `${from}.env`);
+      const dst = join(dir, `${to}.env`);
+      if (!existsSync(src)) throw new Error(`找不到站点配置 ${src}`);
+      if (existsSync(dst)) throw new Error(`目标已存在 ${dst}`);
+      renameSync(src, dst);
+      console.log(`✓ 已重命名站点 ${from} → ${to}`);
+      return;
+    }
+    default:
+      throw new Error(`sites 未知子命令:${action}(list|show|rm|rename)`);
   }
+}
 
-  const needFirst = (what) => {
-    const value = rest[0];
-    if (!value) throw new Error(`${what} 需要一个参数`);
-    return value;
-  };
+// ------------------------------------------------------------------ 输出包装
 
-  const content = async (type) => {
-    switch (action) {
-      case undefined:
-      case 'list':
-        return cmd.listContent(client, type, flags);
-      case 'get':
-        return cmd.getContent(client, type, needFirst('get'), flags);
-      case 'create':
-      case 'new':
-        return cmd.createContent(client, type, flags);
-      case 'update':
-      case 'edit':
-        return cmd.updateContent(client, type, needFirst('update'), flags);
-      case 'delete':
-      case 'rm':
-        return cmd.deleteContent(client, type, needFirst('delete'), flags);
-      default:
-        throw new Error(`${type} 未知子命令:${action}`);
+/** 统一处理 --quiet / --output:抑制或把命令的人类可读输出写入文件。 */
+async function withOutput(flags, fn) {
+  const lines = [];
+  const originalLog = console.log;
+  if (flags.quiet) console.log = () => {};
+  else if (flags.output) console.log = (...args) => lines.push(args.join(' '));
+  try {
+    return await fn();
+  } finally {
+    console.log = originalLog;
+    if (!flags.quiet && flags.output && lines.length) {
+      const file = resolve(String(flags.output));
+      writeFileSync(file, lines.join('\n') + '\n', 'utf8');
+      originalLog(`✓ 输出已写入 ${file}`);
     }
-  };
+  }
+}
 
-  const taxonomy = async (tax) => {
-    switch (action) {
-      case undefined:
-      case 'list':
-        return cmd.listTaxonomy(client, tax, flags);
-      case 'get':
-        return cmd.getTaxonomy(client, tax, needFirst('get'));
-      case 'create':
-      case 'new':
-        return cmd.createTaxonomy(client, tax, flags);
-      case 'update':
-      case 'edit':
-        return cmd.updateTaxonomy(client, tax, needFirst('update'), flags);
-      case 'delete':
-      case 'rm':
-        return cmd.deleteTaxonomy(client, tax, needFirst('delete'), flags);
-      default:
-        throw new Error(`${tax} 未知子命令:${action}`);
-    }
-  };
+// ------------------------------------------------------------------ 用法错误
 
-  switch (group) {
-    case 'doctor':
-      return cmd.doctor(client, cfg, flags);
-    case 'me':
-      return cmd.me(client, flags);
-    case 'posts':
-    case 'post':
-      return content('posts');
-    case 'pages':
-    case 'page':
-      return content('pages');
-    case 'media':
-      switch (action) {
-        case undefined:
-        case 'list':
-          return cmd.listMedia(client, flags);
-        case 'get':
-          return cmd.getMedia(client, needFirst('get'), flags);
-        case 'upload':
-          return cmd.uploadMedia(client, needFirst('upload 需要文件路径'), flags);
-        case 'update':
-        case 'edit':
-          return cmd.updateMedia(client, needFirst('update'), flags);
-        case 'delete':
-        case 'rm':
-          return cmd.deleteMedia(client, needFirst('delete'), flags);
-        default:
-          throw new Error(`media 未知子命令:${action}`);
-      }
-    case 'plugins':
-    case 'plugin':
-      switch (action) {
-        case undefined:
-        case 'list':
-          return cmd.listPlugins(client, flags);
-        case 'install':
-          if (!rest[0]) {
-            throw new Error('plugins install 需要 wordpress.org 插件别名,例如 wpops plugins install akismet');
-          }
-          return cmd.installPlugin(client, rest[0], flags);
-        case 'activate':
-          return cmd.setPluginStatus(client, needFirst('activate'), true, flags);
-        case 'deactivate':
-          return cmd.setPluginStatus(client, needFirst('deactivate'), false, flags);
-        default:
-          throw new Error(`plugins 未知子命令:${action}`);
-      }
-    case 'themes':
-    case 'theme':
-      switch (action) {
-        case undefined:
-        case 'list':
-          return cmd.listThemes(client, flags);
-        case 'activate':
-        case 'switch':
-          return cmd.activateTheme(client, needFirst('activate'), flags);
-        default:
-          throw new Error(`themes 未知子命令:${action}`);
-      }
-    case 'categories':
-    case 'category':
-      return taxonomy('categories');
-    case 'tags':
-    case 'tag':
-      return taxonomy('tags');
-    case 'comments':
-    case 'comment':
-      switch (action) {
-        case undefined:
-        case 'list':
-          return cmd.listComments(client, flags);
-        case 'get':
-          return cmd.getComment(client, needFirst('get'));
-        case 'update':
-        case 'edit':
-          return cmd.updateComment(client, needFirst('update'), flags);
-        case 'delete':
-        case 'rm':
-          return cmd.deleteComment(client, needFirst('delete'), flags);
-        default:
-          throw new Error(`comments 未知子命令:${action}`);
-      }
-    case 'users':
-    case 'user':
-      switch (action) {
-        case undefined:
-        case 'list':
-          return cmd.listUsers(client, flags);
-        case 'me':
-          return cmd.me(client, flags);
-        case 'get':
-          return cmd.getUser(client, needFirst('get'));
-        case 'create':
-        case 'new':
-          return cmd.createUser(client, flags);
-        case 'update':
-        case 'edit':
-          return cmd.updateUser(client, needFirst('update'), flags);
-        case 'delete':
-        case 'rm':
-          return cmd.deleteUser(client, needFirst('delete'), flags);
-        default:
-          throw new Error(`users 未知子命令:${action}`);
-      }
-    case 'raw':
-      if (!action || !rest[0]) throw new Error('raw 用法:wpops raw <METHOD> <path> [--data JSON]');
-      return cmd.raw(client, action, rest[0], flags);
+/** 用法错误:stderr 打印「消息 + 精简用法 + --help 提示」,退出码 2(与运行期错误的 1 区分)。 */
+function reportUsageError(err, group, action) {
+  console.error(`✗ ${err.message}`);
+  const lines = usageHint(group, action);
+  if (lines.length) {
+    console.error('用法:');
+    for (const line of lines) console.error(`  ${line}`);
+  }
+  if (group && groupByName(group)) {
+    console.error(`提示:wpops ${group} --help 查看完整用法`);
+  } else {
+    console.error('提示:wpops help 查看全部命令');
+  }
+  process.exitCode = 2;
+}
+
+// ------------------------------------------------------------------ completion
+
+function printCompletion(shell) {
+  const words = completionWords(['help']).join(' ');
+  switch (shell || 'bash') {
+    case 'bash':
+      console.log(`# wpops bash completion(用法:eval "$(wpops completion bash)")\n_wpops() {\n  local cur="\${COMP_WORDS[COMP_CWORD]}"\n  COMPREPLY=( $(compgen -W "${words}" -- "$cur") )\n}\ncomplete -F _wpops wpops`);
+      return;
+    case 'zsh':
+      console.log(`# wpops zsh completion(用法:eval "$(wpops completion zsh)")\n_wpops() { compadd ${words} }\ncompdef _wpops wpops`);
+      return;
+    case 'fish':
+      console.log(`# wpops fish completion(用法:wpops completion fish | source)\ncomplete -c wpops -f -a "${words}"`);
+      return;
+    case 'powershell':
+      console.log(`# wpops PowerShell completion(用法:wpops completion powershell | Out-String | Invoke-Expression)\nRegister-ArgumentCompleter -Native -CommandName wpops -ScriptBlock {\n  param($wordToComplete)\n  "${words}".Split(' ') | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }\n}`);
+      return;
     default:
-      throw new Error(`未知命令:${group}(运行 wpops help 查看用法)`);
+      throw new Error('completion 支持:bash|zsh|fish|powershell');
   }
 }
 
+// ------------------------------------------------------------------ main
+
 async function main() {
   const { positionals, flags } = parseArgs(process.argv.slice(2));
   const [group, action, ...rest] = positionals;
 
+  configureOutput(flags);
+  if (flags.paginate) flags['all-pages'] = true;
+  if (flags.csv || flags.table || flags.fields) flags.json = true;
+
   if (flags.version) {
     console.log(version());
     return;
   }
+
+  // help:wpops / wpops help [组] [动作] / wpops <组> [动作] --help
   if (!group || group === 'help' || flags.help) {
-    printHelp();
+    const helpGroup = group === 'help' ? action : group;
+    const helpAction = group === 'help' ? rest[0] : action;
+    if (helpGroup) {
+      const text = groupHelp(helpGroup, helpAction);
+      if (!text) {
+        console.error(`未知命令组:${helpGroup}(运行 wpops help 查看全部)`);
+        process.exitCode = 1;
+        return;
+      }
+      console.log(text);
+      return;
+    }
+    console.log(generalHelp(version()));
     return;
   }
+
   if (group === 'sites') {
-    printSites();
+    await withOutput(flags, () => sitesCommand(action, rest));
     return;
   }
   if (group === 'setup') {
-    await cmd.setup(flags);
+    await setup(flags);
     return;
   }
   if (group === 'install-skill') {
-    const dirs = installSkill();
-    if (!dirs.length) {
-      console.log('未安装 skill(可能已存在同名目录被跳过,或用 WPOPS_SKIP_SKILL 禁用)。');
-    } else {
-      for (const dir of dirs) console.log(`✓ skill 已安装到 ${dir}`);
-    }
+    await withOutput(flags, () => {
+      const dirs = installSkill();
+      if (!dirs.length) {
+        console.log('未安装 skill(可能已存在同名目录被跳过,或用 WPOPS_SKIP_SKILL 禁用)。');
+      } else {
+        for (const dir of dirs) console.log(`✓ skill 已安装到 ${dir}`);
+      }
+    });
+    return;
+  }
+  if (group === 'completion') {
+    await withOutput(flags, () => printCompletion(action));
     return;
   }
+  if (group === 'commands') {
+    await withOutput(flags, () => console.log(commandsJson(version())));
+    return;
+  }
+
+  const single = flags.site || process.env.WPOPS_SITE || null;
+  const named = flags.site && String(flags.site).includes(',')
+    ? String(flags.site).split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
 
-  const site = flags.site || process.env.WPOPS_SITE || null;
-  const mutating = isMutation(group, action);
+  let targets = null;
+  if (flags.all) targets = listSites();
+  else if (named.length) targets = named.map((name) => ({ name, label: name }));
 
-  if (flags.all) {
-    const targets = listSites();
+  if (targets) {
     if (!targets.length) throw new Error('还没有配置任何站点');
-    if (mutating && !flags.yes && !flags['dry-run']) {
-      throw new Error('--all 会作用于所有站点。写操作请加 --yes 确认,或先用 --dry-run 预览。');
+    if (isMutation(group, action) && !flags.yes && !flags['dry-run']) {
+      reportUsageError(
+        new UsageError('批量执行会作用于多个站点。写操作请加 --yes 确认,或先用 --dry-run 预览。', { group, action }),
+        group,
+        action,
+      );
+      return;
     }
     let failures = 0;
-    for (const target of targets) {
-      try {
-        await runOne(target.name, group, action, rest, flags, true);
-      } catch (err) {
-        failures++;
-        console.error(`✗ [${target.label}] ${err.message}`);
+    let usageError = null;
+    await withOutput(flags, async () => {
+      for (const target of targets) {
+        try {
+          await runOne(target.name, group, action, rest, flags, true);
+        } catch (err) {
+          if (err instanceof UsageError) {
+            usageError = err; // 用法与站点无关:立即中止,不逐站重复
+            return;
+          }
+          failures++;
+          console.error(`✗ [${target.label}] ${err.message}`);
+        }
       }
+    });
+    if (usageError) {
+      reportUsageError(usageError, usageError.group || group, usageError.action ?? action);
+      return;
     }
     if (failures) {
       console.error(`\n完成:${failures}/${targets.length} 个站点出错。`);
@@ -323,10 +252,23 @@ async function main() {
     return;
   }
 
-  await runOne(site, group, action, rest, flags, false);
+  try {
+    await withOutput(flags, () => runOne(single, group, action, rest, flags, false));
+  } catch (err) {
+    if (err instanceof UsageError) {
+      reportUsageError(err, err.group || group, err.action ?? action);
+      return;
+    }
+    throw err;
+  }
 }
 
 main().catch((err) => {
+  if (err instanceof UsageError) {
+    console.error(`✗ ${err.message}`);
+    console.error('提示:wpops help 查看全部命令');
+    process.exit(2);
+  }
   if (err instanceof WpError) {
     console.error(`✗ ${err.message}`);
     if (err.code) console.error(`  代码:${err.code}`);