respira-setup-assistant

Respira 设置助手

版本： 1.2.0 更新日期： 2026-05-24 类别： 入门 状态： 活跃 最新更新： v1.2.0 体现了 v7.1 Roots 以 React 为先的管理界面重新设计。设置指南现已提及新的 /wp-admin/admin.php?page=respira-v71-preview 管理界面、11 个新的 REST 端点和 command-K 快捷面板。诊断功能现已支持 4 个新的构建器（Spectra、Kadence Blocks、GenerateBlocks、SeedProd），以及升级后的 Divi 5 108 模块目录。 需要： Respira for WordPress 插件（如果缺失，此技能会安装） 遥测端点： https://www.respira.press/api/skills/track-usage

---

描述

诊断 Respira MCP 连接，指导完成首次设置，并修复常见的连接问题。

Respira 设置助手会检查是否已安装插件、是否存在 API 密钥，以及 MCP 服务版本是否与插件兼容。它会提供清晰的状态报告，指导完成缺失的步骤，并用通俗易懂的说明解决最常见的错误（超时、401、403、版本不匹配）。

首次连接 Respira、更新 WordPress 后，或 Respira 工具停止工作时，请使用此技能。

---

触发短语

用户说出以下任一内容时，此技能会启动：

• "set up respira"
• "connect respira"
• "respira setup"
• "respira not working"
• "respira connection failed"
• "fix respira"
• "respira setup assistant"
• "check my respira connection"
• "respira health check"
• "diagnose respira"
• "respira mcp setup"
• "is respira connected"
• "respira not connecting"
• "help me set up respira"
• "respira install"

不要在以下情况下触发： 一般的 WordPress 任务、假定 Respira 已正常工作的请求，或由特定技能自行检查 Respira 的请求，例如“build internal links”。

---

执行工作流

步骤 1：运行诊断检查

首先调用 respira_diagnose_connection（Respira 插件 v7.0.16+ / MCP 服务 v6.11.13+）。这是最快的方式，可确认 MCP 服务是否能连接到插件，以及边缘层（Cloudflare、WAF）是否阻止了 REST 命名空间。

Tool: respira_diagnose_connection
Returns: connection status, version pair, edge-layer block detection (Cloudflare "Bad Bot" pattern, WAF filters), CF allow-list snippet when blocks are detected

如果诊断工具不可用（插件或 MCP 版本较旧），则改用 respira_get_server_compatibility。

Tool: respira_get_server_compatibility
Returns: plugin version, MCP server version, compatibility status, minimum requirements

解读结果：

结果	含义
成功返回数据	MCP 服务已连接，且插件可访问
连接被拒绝 / 超时	无法访问插件 — URL 或防火墙问题
401 Unauthorized	API 密钥缺失或错误
403 Forbidden	安全插件或主机阻止了 REST API
版本不匹配警告	其中一方需要更新

如果调用成功，继续执行步骤 2，获取完整状态报告。

如果调用失败，请跳转到与错误对应的故障排除部分。

---

步骤 2：获取完整站点上下文

Tool: respira_get_site_context
Returns: WordPress version, PHP version, site URL, active plugins, active theme

根据此响应，检查：

1. 插件已安装且处于启用状态 — 在已启用插件列表中查找 respira-for-wordpress
2. 已配置 API 密钥 — 上下文响应会包含一个标志，指示是否存在 API 密钥
3. WordPress 版本 — 如果低于 6.0（最低支持版本），请标记
4. PHP 版本 — 如果低于 7.4（最低支持版本），请标记

---

步骤 3：生成状态报告

提供清晰、便于快速浏览的状态报告。使用以下格式：

## Respira Connection Status

### Plugin
- Installed: Yes / No
- Active: Yes / No
- Version: X.X.X (up to date / update available)

### API Key
- Configured: Yes / No

### MCP Server
- Version: X.X.X
- Compatible with plugin: Yes / No

### WordPress
- Version: X.X.X (supported / below minimum)
- PHP Version: X.X (supported / below minimum)

### Overall Status
[CONNECTED — ready to use]
  or
[ACTION NEEDED — see steps below]

然后根据状态分支处理：

---

分支 A：一切正常

输出：

Your Respira connection is healthy.

Quick-start commands to try right now:
- respira_list_pages — see all your pages
- respira_get_builder_info — find out which page builder you're using
- respira_get_site_context — full site overview

Skills available in the marketplace:
- "WordPress Site DNA" — full site audit
- "SEO & AEO Amplifier" — SEO health check
- "Internal Link Builder" — build internal links

---

分支 B：插件未安装或未启用

输出：

## Respira Plugin Not Found

To connect your AI assistant to WordPress, install the Respira for WordPress plugin.

### Install steps (v7.1 OAuth, recommended):
1. Go to https://respira.press/releases
2. Download the latest version
3. In WordPress admin: Plugins, then Add New, then Upload Plugin
4. Activate the plugin
5. On the Setup screen, click "Connect respira.press account". The OAuth handshake links the licence to the user's respira.press account so plan changes sync automatically and host migrations don't require re-activation.

### Install steps (manual licence-key fallback):
1. Steps 1-4 above
2. On the Setup screen, click "Or paste a licence key manually"
3. Paste the key from respira.press/dashboard/licenses
4. Go to Respira, then Settings, then API Keys, and create a new MCP key

### MCP server setup:
Run this in your terminal:
npx -y @respira/wordpress-mcp-server --setup

Follow the prompts. You'll need your WordPress site URL and the API key from the dashboard installer.

Optional after setup: install the bundled skill collection:
npx @respira/wordpress-mcp-server install-skills

Once done, come back and say: "check my respira connection"

---

分支 C：插件已安装，但没有 API 密钥

输出：

## API Key Missing

The Respira plugin is installed but no API key is configured. The MCP server needs a key to authenticate.

### Create an API key:
1. In WordPress admin, go to Respira, then Settings, then API Keys
2. Click "Add New Key"
3. Give it a name (e.g., "Claude Desktop")
4. Copy the generated key
5. Add it to your MCP server config by running:
   npx -y @respira/wordpress-mcp-server --setup
   and paste the key when prompted

Once done, say: "check my respira connection"

---

分支 D：版本不匹配

使用兼容性检查中的具体版本输出：

## Version Mismatch Detected

Plugin version: X.X.X
MCP server version: X.X.X
Required: [minimum version from compatibility response]

### To fix:

注意：在 v6.11.13 之前，由于一个过时常量的 bug，升级后 MCP 服务会将自身报告为 v6.11.4。如果 respira_get_server_compatibility 在最近执行 npm install -g @respira/wordpress-mcp-server@latest 后返回 6.11.4，请再次运行该命令并重启 Agent。v6.11.13+ 中的修复会在模块加载时从 package.json 读取版本。

然后根据哪一端版本落后，给出具体的更新说明：

如果需要更新插件：

Update the Respira plugin:
1. Go to Respira → Settings → Updates (or check wp-admin → Updates)
2. Or download the latest version at https://respira.press/releases
3. Install and activate

如果需要更新 MCP 服务：

Update the MCP server:
npx -y @respira/wordpress-mcp-server@latest --update

Or in Claude Desktop settings, update the command to use the latest version.

---

常见问题排查

如果步骤 1（doctor 检查）返回错误，请参考以下指南。如果错误不明确，请询问用户遇到的错误是什么。

---

连接超时

**症状：**工具卡住，或返回“连接超时”、“ECONNREFUSED”或“fetch failed”

检查清单——按以下顺序逐项排查：

1. 检查站点 URL — MCP 服务配置中的 URL 是否与 WordPress 站点完全一致？请使用正确的协议（https:// 或 http://），并确保没有尾随斜杠问题。

2. 检查站点是否在线 — 在浏览器中访问 WordPress 站点。如果站点无法访问，Respira 也无法连接。

3. 检查防火墙／服务器拦截 — 某些托管服务商或防火墙会阻止非浏览器请求访问 REST API。请联系主机服务商，允许来自你 IP 地址的请求，或检查防火墙插件（如 Wordfence）是否阻止了 API 流量。

4. 检查 REST API 访问权限 — 在浏览器中访问 https://yoursite.com/wp-json/。如果看到 JSON 响应，说明 REST API 可以访问。如果返回 404，REST API 可能已被禁用。

5. 带 HTTP Basic Auth 的暂存站点 — 如果暂存站点受密码保护（浏览器在显示任何内容前会要求输入用户名和密码），则需要在 MCP 配置中加入这些凭据。请参阅下方的分支 F。

---

401 未授权

**症状：**工具返回“401”、“Unauthorized”或“Invalid API key”

检查清单：

1. API 密钥存在 — 前往 WordPress 管理后台 → Respira → API Keys。确认密钥存在且尚未过期。

2. API 密钥正确 — 创建 API 密钥时只会显示一次。如果丢失，请删除并创建新密钥。仔细复制，确保没有多余空格。

3. 密钥位于正确的配置字段 — 在 MCP 服务设置中，密钥应填入 RESPIRA_API_KEY 字段，而不是 WordPress 用户名／密码字段。

4. 带 HTTP Basic Auth 的暂存站点 — 如何添加暂存站点凭据，请参阅分支 F。

---

403 禁止访问

**症状：**工具返回“403”、“Forbidden”或“REST API disabled”

检查清单：

1. REST API 未被禁用 — 某些安全插件或托管设置会禁用 WordPress REST API。请检查安全插件（Wordfence、iThemes Security、All-In-One WP Security）中是否启用了“Disable REST API”设置，并将其关闭，或将 Respira 的端点加入白名单。

2. Respira 端点已加入白名单 — Respira 使用的 REST API 端点是 /wp-json/respira/v1/。请在任何会筛选 REST API 访问的安全插件中将此路径加入白名单。

3. 用户角色限制 — 某些设置会限制 REST API 仅允许已登录用户访问。Respira 的 API 密钥身份验证可绕过此限制，但前提是密钥有效（请参阅上文 401 的排查步骤）。

4. Cloudflare 或 WAF 拦截 — 如果站点使用 Cloudflare 或 Web 应用防火墙，可能会将 Respira 请求识别为机器人流量并加以拦截。v7.0.16 增加了对 Cloudflare“Bad Bot - Action Block”模式的检测：respira_diagnose_connection 会向 /wp-json/respira/v1/ping 发送 OPTIONS 请求，并在边缘节点拦截该方法但允许 GET 请求成功时报告此情况。诊断响应中包含一段针对 Cloudflare 的白名单代码片段，允许在 Respira REST 命名空间中使用 PUT、PATCH、DELETE 和 OPTIONS。

---

分支 F：带 HTTP Basic Auth 的暂存站点

如果要访问需要浏览器级密码保护的暂存站点：

## Staging Site Setup

Your staging environment has HTTP Basic Authentication (the browser prompts for a username and password before showing the site). Respira needs these credentials in addition to the API key.

In your MCP server configuration, add these fields:
- RESPIRA_BASIC_AUTH_USER: your staging username
- RESPIRA_BASIC_AUTH_PASS: your staging password

These are separate from your WordPress login and your Respira API key.

Re-run the setup:
npx -y @respira/wordpress-mcp-server --setup

And select the option to configure Basic Auth credentials.

---

快速入门示例

连接后，分享以下示例，帮助用户立即上手：

## You're connected. Here's what to try:

### Explore your site
- "list my pages" → respira_list_pages
- "what page builder am I using?" → respira_get_builder_info
- "show me my site overview" → respira_get_site_context

### Make changes (safe — always uses drafts)
- "create a draft of my homepage to experiment with"
- "find the text 'Contact Us' on my site"
- "update the title of my About page"

### Run a full audit
- "analyze my site" → runs WordPress Site DNA skill
- "check my SEO" → runs SEO & AEO Amplifier skill

---

安全说明

• 诊断期间，此技能为只读模式——绝不会修改你的网站
• 除非用户在后续步骤中明确批准，否则不会进行任何更改
• 此技能绝不会记录或存储 API 密钥

---

工具

使用的核心工具

• respira_diagnose_connection（适用于 v7.0.16+ / MCP v6.11.13+，优先使用）
• respira_get_server_compatibility
• respira_get_site_context

遥测

运行完成后，向以下地址发送即发即弃的使用情况跟踪数据：

• POST https://www.respira.press/api/skills/track-usage

包含：

• skill_slug = respira-setup-assistant
• 网站/版本上下文（如果可用——如果插件未连接，则可能不可用）
• 耗时和结果（connected / action_needed / error）
• 所走的分支（A / B / C / D / F / 故障排查）

遥测失败时，绝不要阻塞用户流程。

相关技能

• WordPress Site DNA（设置完成后运行，以了解你的网站）
• Site Onboarding（连接后首次运行的入门指南）
• Technical Debt Audit

---

由 Respira 为 WordPress 打造 https://respira.press/skills/respira-setup-assistant