wpops 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,11 @@
 # wpops
 
-> 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.
+[![npm version](https://img.shields.io/npm/v/wpops.svg)](https://www.npmjs.com/package/wpops)
+[![npm downloads](https://img.shields.io/npm/dm/wpops.svg)](https://www.npmjs.com/package/wpops)
+[![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, navigation menus and plugins across one or many sites.
 
 WordPress REST 操作工具。只依赖 Node 内置能力(无第三方包),用应用密码通过
 `/wp-json/` 管理站点内容与插件。
@@ -33,7 +38,20 @@ cd wpops
 ./install.ps1          # Windows;macOS/Linux 用 sh install.sh(装 CLI + skill)
 ```
 
-不 clone 也行:`pnpm add -g github:qnnp-me/wpops`,再加
+不想 clone?一行流(脚本不在仓库内时会自动 `git clone`):
+
+```powershell
+iwr -useb https://raw.githubusercontent.com/qnnp-me/wpops/main/install.ps1 | iex   # Windows
+```
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/qnnp-me/wpops/main/install.sh | sh    # macOS/Linux
+```
+
+> 若 `raw.githubusercontent.com` 访问不了,可换 jsDelivr 镜像:
+> `https://cdn.jsdelivr.net/gh/qnnp-me/wpops@main/install.ps1`(或 `.sh`)。
+
+也可以直接用 git 依赖:`pnpm add -g github:qnnp-me/wpops`,再加
 `npx skills add qnnp-me/wpops --skill wpops -a opencode -g`。
 
 **发布(维护者)**
@@ -46,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/用户名/应用密码,自动写入并体检)。
@@ -83,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 关键词]
@@ -100,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>
 
@@ -120,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]
@@ -175,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 核心更新 | ❌ |
 | 备份 / 数据库优化 / 缓存清理 | ❌(需服务器侧) |
 
@@ -191,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. 全局命令(可选)