AlexMaghen/wp-dev

wp-dev：在本地开发线上 WordPress 站点

以 ${CLAUDE_PLUGIN_ROOT}/bin/wpsync 运行 wpsync（下称 wpsync）。开发者通常不是项目的创建者，因此请用通俗语言解释每一步，并说明哪些步骤需要他们操作。

首先阅读 ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/guiding.md。 该文件说明了如何显示进度（以清单形式展示当前阶段的步骤）、如何提问（对每个决策和每次等待使用问题对话框），以及在应用本身不提供这些功能时应如何处理。下面提到的询问行指代要使用的对话框。

原则： 在做出任何更改之前先检查一切，并立即报告每个问题及其修复方法。每个步骤都可以安全地重复执行，因此中断后开发者可以说“继续我的 wp-dev 项目”，你就会从停止的地方继续。

开始之前：wpsync 能否运行？

wpsync 运行在 Bun 上，因此在尚未安装 Bun 的 Mac 上，每个 wpsync 命令（包括 status、init 和 doctor）都会失败并显示“wpsync 需要 Bun”（退出代码 127）。在任何 wpsync 命令之前，请先检查此项：

1. 运行 ${CLAUDE_PLUGIN_ROOT}/bin/wpsync --version。如果能打印出版本号，则继续执行“我们在哪？”步骤。
2. 如果提示 wpsync 需要 Bun，请找到 Homebrew：command -v brew || ls /opt/homebrew/bin/brew /usr/local/bin/brew。
   • 找到 Homebrew → brew install oven-sh/bun/bun（如果 brew 不在 PATH 中，请使用完整路径），然后再次运行 wpsync --version。
   • 未找到 Homebrew → 需要开发者操作（将要求输入 Mac 密码）。解释 wpsync 和其他工具都通过 Homebrew 安装，打开一个包含 https://brew.sh 安装命令的终端选项卡（见 guiding.md），然后等待，使用“完成，检查”对话框。之后使 Homebrew 可用（见步骤 2 中的“安装 Homebrew 后立即处理”），并按上述步骤安装 Bun。

如果 wpsync 运行成功，则不再提及，继续下一步。只有在你必须安装 Bun 时，才用一行告诉开发者这是第一个先决条件，并且 wpsync doctor --local 将在步骤 2 中检查其余部分。

我们在哪？

在当前文件夹中运行 wpsync status --json，根据其 phase 执行：

阶段	执行操作
no-project	从步骤 1 开始阶段 1（起始门）
start-gate（之前会话已创建文件夹）	从步骤 2 开始阶段 1
connect、pull	从步骤 2 开始阶段 1（跳过已完成的部分）
work	阶段 2：更改使用 wp-work 技能，刷新使用 wp-pull，上线使用 wp-publish
publish-pending	上次发布正在等待完成或回滚：见 wp-publish

无论处于哪个阶段：如果 status 包含 wordfence 字段，则该站点的 Wordfence 必须在 wpsync 工作期间关闭，并在之后重新打开。请遵循 ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md。

在阶段 1 中，开始（或恢复时，再次显示）来自 guiding.md 的设置清单，已完成步骤标记为勾选，并开始一个“设置”章节。

阶段 1：设置本地副本

1. 起始门：正确的文件夹，然后是地址

会话的文件夹在开始时固定，因此开发者在本地副本应放置的文件夹中启动会话。然后所有操作都在此会话中完成。

此会话是否在可用的文件夹中？ 查看当前文件夹（ls -A）：

• 空文件夹（或仅包含 .DS_Store 或 .claude）：是该站点的新文件夹。继续下面操作。

• 其他任何位置（桌面、主文件夹、另一个项目）：不要在此设置。发送以下内容并停止：

  要设置站点，请在要放置本地副本的文件夹中启动新的 Claude Code 会话：一个新的空文件夹，例如 ~/wp-sites/example.com。

  启动一个新会话，选择（或创建）该文件夹，并将权限模式设置为 绕过权限，如果您不希望批准每个步骤。（发布到线上站点始终会等待您在对话框中输入其域名。）然后在该文件夹中说 “新建 wp-dev 项目”。

在新文件夹中， 用一行简短询问线上站点的地址：

线上站点的地址是什么？例如 https://example.com。

如果文件夹名称包含域名（例如 example.com-local），则改为提示：“线上站点的地址是什么？从文件夹名称我猜是 https://example.com。”

然后在此创建项目：wpsync init <site-url> --dir .。它会写入文件夹的 CLAUDE.md、.claude/settings.json（预批准 ddev、git、brew 和只读的 wpsync 命令；发布仍需询问）和标记为待定的 .wpsync.json。它不会联系任何外部服务。直接进入步骤 2。这些设置将从在该文件夹中的下一个会话开始生效；如果你未处于绕过权限模式，此会话在此期间可能会稍微频繁地询问。你无法检测权限模式，也无需检测。

2. 检查此 Mac

wpsync doctor --local 同时列出所有内容。以 guiding.md 中的结果表格形式显示。按以下顺序安装缺少的内容：

• 你可以执行： brew install ddev/ddev/ddev、brew install oven-sh/bun/bun 和 Docker。如果未安装任何 Docker 应用，询问“应在该 Mac 上安装哪个 Docker 应用程序？”：OrbStack（推荐：在 Mac 上更轻量快速，个人使用免费）或 Docker Desktop（标准版本；个人和中小企业免费）。然后执行 brew install --cask orbstack 或 brew install --cask docker。 Docker 已安装但“未运行”： 自行启动（open -a OrbStack 或 open -a Docker），等待最多一分钟，直到 docker info 成功。只有首次启动（条款、密码）需要开发者介入；如果一分钟后 docker info 仍失败，说明有首次启动对话框正在等待他们操作。
• 需要开发者操作（密码或点击，你永远不会代劳）：Xcode 命令行工具（xcode-select --install）、Homebrew（来自 https://brew.sh）、OrbStack 或 Docker Desktop 的首次启动，以及 mkcert -install。打开一个已准备好命令的终端选项卡（见 guiding.md），并使用“完成，检查”对话框等待。当多个项缺失时，在一条消息中全部列出并等待一次，而不是每项等待一次。

mkcert 是必需的（doctor 报告为 FIX，直到设置完成）。本地副本的地址是 https://…ddev.site。没有 mkcert -install，Chrome 会拒绝该地址，而通过纯 HTTP 加载页面时样式或图像会丢失（WordPress 通过 HTTPS 链接它们）。这看起来像步骤 7 中的一个损坏副本。因此请在此处、在首次拉取之前执行此操作：说明它将要求输入 Mac 的 密码，在终端选项卡中运行 mkcert -install，然后等待。如果在 DDEV 启动后才安装（恢复较旧的设置），DDEV 仍在使用其不受信任的证书：在站点文件夹中运行 ddev poweroff && ddev start，然后要求他们重新加载页面。

再次运行 wpsync doctor --local 直到没有报告 FIX。Notes 可以忽略，但请说明其含义。

安装 Homebrew 后立即处理： 在 Apple Silicon Mac 上，Homebrew 安装到 /opt/homebrew，该路径在运行安装程序的“下一步”行之前不在 PATH 中。doctor 会报告为“已安装到 /opt/homebrew/bin/brew，但尚未在 PATH 中”，并附上需要添加到 ~/.zprofile 的行；绝不要让他们重新安装。你自己的 shell 不会加载 ~/.zprofile，因此在此会话中，请在命令前添加 eval "$(/opt/homebrew/bin/brew shellenv)" &&。

3. 检查站点

wpsync doctor <site-url>（只读）。在连接之前，它会检查站点是否为 WordPress 且 REST API 可用，以及是否启用了应用密码。（主机是否传递 Authorization 标头只能用真实密钥测试，因此将在 wpsync 连接时检查。）显示结果表格。在继续之前修复或解释每个 FIX；大多数是托管或安全插件设置，开发者必须询问其他人：使用 guiding.md 中的“当检查需要他人操作时”对话框。

Wordfence： 如果报告应用密码“已关闭，很可能由 Wordfence 导致”，请遵循 ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md（“之前”）：开发者在 wp-admin 中关闭一个设置，你使用“完成，检查”对话框等待，直到 doctor 确认。你将在步骤 8 中提醒他们重新打开。

4. 连接

wp-connect 技能。之后再次运行 wpsync doctor <site-url>：现在它还会检查 Authorization 标头、多站点、文件权限、版本、本 Mac 和服务器上的磁盘空间。

（wpsync new <site-url> 一步到位执行步骤 2 到 7，并在第一个需要开发者介入的地方停止；适合恢复使用。逐步操作如本说明所述，会沿途解释更多。）

5. 拉取

wp-pull 技能（首次拉取：wpsync pull <site-url> --dir .）。它会在 https://<project>.ddev.site 创建 DDEV 项目，无需修改 hosts 文件。大型站点需要一些时间：以长时间任务运行（guiding.md）。

6. 使副本安全运行

副本包含线上数据库：真实客户的电子邮件、可能的线上支付或 API 密钥、计划任务。DDEV 会捕获所有外发邮件（通过 ddev mailpit 查看），wpsync 设置 WP_ENVIRONMENT_TYPE=local。查看 CLAUDE.md 中的活动插件。如果存在任何支付、物流、CRM、新闻通讯或 webhook 插件，请列出它们并询问“这些插件在 <域名> 的本地副本上可能仍会与真实服务通信。我们应该怎么做？”：带我配置测试模式（推荐：你指导他们进入每个插件的测试或沙箱设置），或 保持原样（他们接受本地副本可以访问那些服务）。

如果没有此类活动插件，则不要询问：用一行说明（指出任何仅发送电子邮件的插件，DDEV 会捕获），然后继续。

7. 验证

wpsync verify 检查页面、wp-admin、固定链接、遗留的线上地址、图像以及插件和主题是否与线上一致。显示结果表格。

在调查失败的页面检查之前， 亲自测试一次该页面：curl -s -o /dev/null -w '%{http_code}' <localUrl>/。如果返回 200，则该检查可能在 DDEV 仍在启动时运行（在 ddev start 后会短暂返回 502）：在深入日志之前再运行一次 wpsync verify。

然后亲自查看：在 Chrome 中并排打开线上和本地副本（Claude 在 Chrome 中），首页和几个内页，进行比较。不要在内置浏览器窗格中判断副本：它会阻止 *.ddev.site 页面的样式、脚本和图像（ERR_BLOCKED_BY_CLIENT），因此即使是完美的副本在那里看起来也是坏的。如果 Chrome 不可用，请使用 curl 检查页面，并要求开发者查看。如果发现无法解释的差异，描述它并询问：立即修复（推荐），或 没问题，继续。

本地登录：副本包含线上用户，因此开发者使用其线上密码登录本地 wp-admin。

8. 移交

现在阅读站点的 CLAUDE.md，以便其规则从此处开始适用。

首先，如果此站点使用 Wordfence（wpsync status --json 显示 "wordfence": "switched-off"）：设置不再需要线上站点，因此请遵循 ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md（“wpsync 完成时”），让开发者重新打开 Wordfence 的保护，等待，并使用 wpsync status 确认。在移交说明之前执行此操作，使开发者的最后一步是开始工作，而不是另一个杂务。

然后在 Chrome 中打开本地站点并完成清单。以完全以下内容结束设置，加粗，独占一行，作为消息中的最后一项（之后无其他内容；任何其他说明，例如登录，放在前面）：

站点本地副本已就绪，地址为 https://{本地站点域名}。检查后告诉我您想开始进行哪些更改。

其中 https://{本地站点域名} 替换为 .wpsync.json 中的 localUrl。在此行之前，用一行说明登录：本地 wp-admin 使用他们的线上用户名和密码。