wp-bootstrap

WordPress 项目引导程序

只需一条命令，即可将 WordPress 项目（单个插件、区块主题或包含多个软件包的单仓库）接入完整的 wp-agent-kit 系统：本地 Playground 开发、WP Engine 部署环境、由 Composer 管理的 PHP 依赖、CI 门禁和 Git 钩子。

适用场景

• 从头搭建新的 WordPress 插件、主题或区块主题。
• 为现有代码库接入完整的 Agent 工具包。
• 配置单仓库（一个仓库中包含多个插件/主题和 JS 软件包），例如 wp-agent-os 模式：wpaos/ + wpaos-blocks/ + wpaos-theme/ + JS 软件包。
• 为 WordPress 项目添加 Composer（WPackagist + 可选的 SatisPress）。
• 配置 WP Engine 开发/暂存/生产环境和 GitHub Actions CI/CD。

设置内容

组件	内容	位置
Agent 工具包	技能、Agent、指令	.agents/skills/ + .github/
PHP 工具	PHPCS + PHPStan + Pest	composer.json + phpcs.xml.dist + phpstan.neon.dist
JS 工具	Biome（检查+格式化）	biome.json
Git 钩子	推送前门禁	.githooks/pre-push
一键设置	tools/setup.sh	tools/setup.sh
WP-CLI 别名	本地路径 + WPE SSH	wp-cli.yml
Playground	多挂载交互式运行 + 无头验证	tools/playground/
WP Engine CI/CD	由分支控制的部署工作流	.github/workflows/
插件打包	构建并压缩为 zip 以供上传	tools/package-wp.sh
Composer	WPackagist + 可选的 SatisPress	composer.json + auth.json
配置	单仓库布局声明	wp-bootstrap.config.json

---

流程

1) 探测仓库（始终首先执行）

运行结构检测器。它会识别 WP 软件包、JS 工作区、现有工具、WP Engine 远程项、GitHub CLI 状态、现有机密和分支保护。

node {baseDir}/scripts/detect-structure.mjs --pretty

输出中的关键字段：

字段	说明
isMonorepo	是否包含多个 WP 软件包或 JS 工作区
wpPackages[]	插件/主题目录、slug 和版本
wpRoot	WP 核心所在位置（null = 仅使用 Playground）
wpeRemotes[]	现有 WP Engine Git 远程项
php.hasPhpcs	是否已配置 PHPCS
js.hasBiome	是否已配置 Biome
playground.hasPlayground	是否已存在 Playground 脚本/蓝图
hasAgentKit	是否已安装 wp-agent-kit
github.ghInstalled	gh CLI 是否可用
github.authenticated	gh auth status 是否通过
github.existingSecrets[]	已设置的 GitHub Actions 机密
github.missingSecrets[]	尚未设置的必需 WPE 机密
github.branchProtection	各分支的保护状态

JSON 输出（适用于脚本/CI）：

node {baseDir}/scripts/detect-structure.mjs

阅读：references/monorepo-patterns.md，将检测到的结构与已知模式匹配。

---

2) 询问探测无法确定的信息

探测后，如果以下任一项仍未知，请先询问用户再继续：

问题	询问时机
WP Engine 安装 slug（生产/暂存/开发）？	wpeRemotes 为空
WP 根目录路径（或仅使用 Playground）？	wpRoot 为 null 且找到 WP 软件包
生成的软件包使用什么构建命令？	存在生成的 *-blocks 或 *-theme 软件包
SatisPress URL + API 密钥？	用户有需要管理的高级插件
对软件包管理器有何偏好？	packageManager 为 null
单仓库的部署策略？	存在多个 WP 软件包且没有 WPE 远程项
是否已安装并通过身份验证的 gh CLI？	检查 github.ghInstalled 和 github.authenticated

---

3) 安装 Agent 工具包

wp-agent-kit install . --platform github

或者用于 Pi：

wp-agent-kit install . --platform pi

这会安装 .agents/skills/、.github/agents/、.github/instructions/ 和 AGENTS.md。

---

4) 设置 PHP 工具

如果 php.hasComposer 为 false 或 php.hasPhpcs 为 false：

# Create root composer.json (dev tooling — not shipped)
# See references/composer-setup.md for the full template
composer init --no-interaction
composer require --dev squizlabs/php_codesniffer wp-coding-standards/wpcs \
  phpcompatibility/phpcompatibility-wp dealerdirect/phpcodesniffer-composer-installer \
  szepeviktor/phpstan-wordpress

# Register WordPress standards
composer run register-standards

要添加插件级测试（Pest），请在每个插件目录中运行：

cd <plugin-dir>
composer require --dev pestphp/pest

阅读：references/composer-setup.md，查看 phpcs.xml.dist 和 phpstan.neon.dist 模板。

---

5) 设置 Composer 仓库

WPackagist（免费，适用于 wordpress.org 插件／主题）：

composer config repositories.wpackagist composer https://wpackagist.org
composer require composer/installers

SatisPress（可选，适用于高级插件）：

composer config repositories.satispress composer https://<your-satispress-site>/satispress/
composer config http-basic.<your-satispress-site> <API_KEY> satispress

阅读：references/composer-setup.md，了解 auth.json 和完整设置。

---

6) 设置 JS 工具（Biome）

如果 js.hasBiome 为 false：

npm install --save-dev @biomejs/biome
npx biome init

更新 biome.json，以匹配项目风格。参考：wp-agent-os 使用：

• indentStyle: "space"、indentWidth: 2（适用于包含 JS 包的单体仓库）
• indentStyle: "tab"（适用于仅包含 TS/JS 的项目，例如 wp-agent-kit 本身）
• 排除：wpaos-blocks/、wpaos-theme/（生成的文件）、dist/、vendor/

---

7) 设置 git 钩子

创建 .githooks/pre-push（不依赖 Husky，适用于所有配置）：

mkdir -p .githooks
# See ci-gate.md in wp-wpengine skill for the full template
cat > .githooks/pre-push << 'HOOK'
#!/usr/bin/env bash
set -uo pipefail
root="$(git rev-parse --show-toplevel)"
cd "$root"
bash .agents/skills/wp-bootstrap/scripts/ci-gate.sh || exit 1
HOOK
chmod +x .githooks/pre-push

# Activate
git config core.hooksPath .githooks

或者运行引导脚本来完成所有这些设置：

bash {baseDir}/scripts/bootstrap.sh

---

8) 创建 wp-cli.yml

# wp-cli.yml — WP-CLI targeting. Commit to repo.

# Local (if WP is in this repo)
# path: ./web     # Bedrock style
# path: .         # WP at root

@production:
  ssh: <install>@<install>.ssh.wpengine.net
  path: /home/wpe-user/sites/<install>

@staging:
  ssh: <install>stg@<install>stg.ssh.wpengine.net
  path: /home/wpe-user/sites/<install>stg

@development:
  ssh: <install>dev@<install>dev.ssh.wpengine.net
  path: /home/wpe-user/sites/<install>dev

---

9) 设置 WordPress Playground

启动交互式 Playground，并挂载所有本地插件／主题：

bash {baseDir}/scripts/playground-start.sh

运行无头验证（无需浏览器）：

bash {baseDir}/scripts/playground-verify.sh

打包插件，以便上传到线上站点：

bash {baseDir}/scripts/package-wp.sh

阅读：references/monorepo-patterns.md，了解多挂载配置。

---

10) 使用 gh CLI 设置 GitHub 仓库

如果 github.ghInstalled 为 true，使用 GitHub 设置脚本来：

• 验证身份验证状态和仓库访问权限
• 检查哪些必需的密钥已设置
• 交互式设置缺少的密钥（SSH 密钥、已知主机、WPE 安装别名、API 凭据）
• 为 main、staging 和 develop 配置分支保护

# Check-only first (no changes)
bash {baseDir}/scripts/setup-github.sh --check-only

# Set missing secrets interactively
bash {baseDir}/scripts/setup-github.sh --set-secrets

# Configure branch protection
bash {baseDir}/scripts/setup-github.sh --set-protection

# Do everything at once
bash {baseDir}/scripts/setup-github.sh --set-all

# Pass WPE slugs to skip those prompts
bash {baseDir}/scripts/setup-github.sh --set-all \
  --wpe-prod=mysite --wpe-staging=mysitestg --wpe-dev=mysitedev

该脚本通过 ssh-keyscan 自动处理 WPE_SSH_KNOWN_HOSTS，并在 ~/.ssh/wpengine_ed25519 存在时读取 WPE_SSH_KEY（或通过 op read 从 1Password 读取）。

如果未安装 gh：运行 brew install gh（macOS），或访问 https://cli.github.com。 安装后：运行 gh auth login。

---

11) 设置 WP Engine GitHub Actions CI/CD

阅读 wp-wpengine 技能：

• references/ci-gate.md — 使用 PHP + JS 并行任务的 CI 门禁，以及 no-verify 策略
• references/github-actions-deploy.md — 用于开发／预发布／生产环境的部署工作流

必需的 GitHub 密钥：

WPE_SSH_KEY              — private key for WP Engine SSH
WPE_SSH_KNOWN_HOSTS      — output of ssh-keyscan for git.wpengine.com
WPE_PROD_INSTALL         — production install slug
WPE_PROD_GIT_URL         — exact URL from WPE portal (git_push page)
WPE_STAGING_INSTALL / WPE_STAGING_GIT_URL
WPE_DEV_INSTALL / WPE_DEV_GIT_URL
WPE_API_USER / WPE_API_PASSWORD  — for pre-deploy DB backups

---

Agent 脚本

脚本	用途	用法
scripts/detect-structure.mjs	探测仓库结构和 GitHub 状态 → JSON	node {baseDir}/scripts/detect-structure.mjs [--pretty]
scripts/bootstrap.sh	一键设置（钩子 + PHP + JS 依赖）	bash {baseDir}/scripts/bootstrap.sh
scripts/setup-github.sh	通过 gh 检查／设置 GitHub 密钥和分支保护	bash {baseDir}/scripts/setup-github.sh [--set-all]
scripts/package-wp.sh	构建并打包 WP 插件／主题	bash {baseDir}/scripts/package-wp.sh [--dry-run]
scripts/playground-start.sh	启动交互式 Playground	bash {baseDir}/scripts/playground-start.sh
scripts/playground-verify.sh	无头 WP 验证	bash {baseDir}/scripts/playground-verify.sh

---

参考资料

• references/monorepo-patterns.md — WordPress 单体仓库结构模式
• references/composer-setup.md — Composer、WPackagist、SatisPress 设置
• wp-wpengine 技能 → references/ci-gate.md — PHP + JS CI 门禁、no-verify 策略
• wp-wpengine 技能 → references/github-actions-deploy.md — 部署工作流
• wp-playground 技能 — Playground CLI、蓝图、PHPUnit、Playwright E2E
• wp-phpstan 技能 — WordPress 的 PHPStan 配置