mobile-experience-report

移动体验报告

版本： 1.2.0 更新日期： 2026-06-30 最新更新： v1.2.0 让报告以真实移动端指标为依据：现在由 respira_run_pagespeed_audit（strategy mobile）和 respira_get_core_web_vitals 驱动评分，而不再仅依赖布局启发式分析。它会通过 respira_find_element 定位并直接调整移动端断点设置，在应用任何修复前通过 respira_get_snapshot 快照记录页面，并通过 respira_batch_update 一次性将相同修复应用到多个页面。 类别： 审计 状态： 已启用 要求： Respira for WordPress 插件 + MCP 服务 遥测端点： https://www.respira.press/api/skills/track-usage

---

描述

了解移动端访客实际看到的内容——布局损坏、文字过大、堆叠失败。

移动体验报告能揭示桌面端测试无法发现的隐藏移动端布局问题。它会分析响应式断点问题、检测移动设备上的文字大小问题、找出列堆叠失败、识别不同设备上的元素可见性问题，并测试手机和平板上的导航菜单行为。此技能会清晰展示桌面端与移动端体验的差异，并提供 Respira 命令，以创建针对移动端优化的副本进行测试。

---

触发短语

用户说出以下任一内容时，都会激活此技能：

• “审计移动体验”
• “检查移动端布局”
• “移动端响应式问题”
• “移动端用户会看到什么”
• “移动端设计问题”
• “响应式审计”
• “移动体验报告”
• “我的网站在移动端看起来很糟”
• “移动端布局坏了”
• “检查响应式设计”
• “移动端 UX 审计”
• “网站在手机上坏了”

请勿在以下情形触发： 未明确涉及移动端的常规 WordPress 审计、从头构建响应式设计的请求、非 WordPress 网站问题，或仅涉及桌面端的布局修复。

---

执行工作流

步骤 1：验证 Respira

在执行其他操作之前，调用 respira_get_site_context，确认已安装 Respira for WordPress 且 MCP 服务已连接。如果调用失败或返回错误，请停止并显示安装指南。

如果未安装 Respira，请输出以下内容并停止：

## ⛔ Respira for WordPress Required

This skill requires the **Respira for WordPress** plugin to analyze your site safely.

### Install in 3 steps:
1. Go to **https://www.respira.press** and download the plugin
2. Install and activate on your WordPress site
3. Connect via the MCP server: `npx -y @respira/wordpress-mcp-server --setup`

### Why Respira?
- Read-only analysis — no changes to your live site
- Duplicate-first mobile fixes so nothing breaks for desktop visitors
- Full audit trail for every action

Once installed, come back and try again: *"audit mobile experience"*

如果 MCP 已连接但无法访问网站：

## ⚠️ Cannot Connect to WordPress Site

Respira is installed but cannot reach your WordPress site.

### Troubleshooting:
1. Verify your WordPress site is online
2. Check the Respira plugin is active (not just installed)
3. Confirm MCP server configuration in Claude settings
4. Review API key in Respira → Settings → API Keys

**Help:** https://www.respira.press/docs/mcp-setup

---

步骤 2：网站和构建器上下文

Tool: respira_get_site_context
Returns: WordPress version, PHP version, active theme, installed plugins,
         detected page builder

记录：respira_site_url、started_at = new Date().toISOString()

Tool: respira_get_builder_info
Returns: Active builder name, version, responsive settings and breakpoints

构建器特定的移动端问题模式：

• Elementor： 列反转设置、移动端断点（默认 767px）、字体大小缩放、按设备设置内边距
• Divi： 980px/767px 的移动端断点、列间距行为、按视口设置自定义 CSS
• WPBakery： 响应式列宽、各分区的自定义响应式设置
• Gutenberg/Full Site Editing： 移动端区块间距、列区块、封面区块高度
• Beaver Builder： 响应式列行为、移动端菜单类型、断点设置
• 经典主题（无构建器）： 主题的响应式 CSS 方案、viewport meta 标签

---

步骤 3：页面清单

Tool: respira_list_pages
Params: { status: "publish" }
Returns: All published pages with IDs, titles, content metadata

确定优先审计的页面：

1. 首页（始终分析）
2. 顶级导航页面
3. 任何采用复杂多列布局的页面
4. 联系页面或转化页面

深度分析最多 10 个页面，以确保报告重点明确、切实可用。

---

步骤 4：真实移动端指标

不要仅依赖布局启发式分析。获取实时移动端实测数据和实验室数据，让评分反映手机用户的实际体验。

针对首页和每个优先页面：

Tool: respira_run_pagespeed_audit
Params: { url: <page url>, strategy: "mobile" }
Returns: Mobile Lighthouse scores, lab metrics, and opportunities

Tool: respira_get_core_web_vitals
Params: { url: <page url>, strategy: "mobile" }
Returns: LCP, INP, CLS for the mobile profile (field data when available, lab otherwise)

记录每个页面的移动端 LCP / INP / CLS，并将其纳入评分的性能档位（步骤 6）。如果有真实的 Core Web Vitals 数据，则以其覆盖启发式性能估算。如果无法使用 PageSpeed 审计（没有 API 密钥、受到速率限制，或 Google 无法访问该网站），则回退到以下结构分析，并在报告中注明这些指标是启发式估算，而非实测数据。

第 5 步：页面结构分析

针对每个优先级页面：

Tool: respira_analyze_performance
Params: { pageId: <id> }
Returns: Page load data, scripts, CSS, rendering details

分析页面构建器的输出，检查是否存在移动端响应式问题。根据内容结构和构建器类型，找出以下问题：

列和布局问题：

• 多列版块未设置响应式堆叠
• 固定宽度元素无法缩放（使用 px 宽度而非 %）
• 带有 overflow: hidden 的元素会在窄屏上裁切内容
• 元素宽度超出视口，导致出现水平滚动

排版问题：

• 标题字体大小未针对移动端缩小（桌面端和移动端使用相同的 px 大小）
• 行高导致文字重叠
• 字间距在小屏上过宽
• 文本块宽度固定，导致出现水平滚动

间距和内边距问题：

• 版块在桌面端和移动端的内边距数值相同（移动端使用 80px 会浪费屏幕空间）
• 负外边距导致溢出
• 元素之间的间隔过大，占用移动端视口空间

导航问题：

• 下拉菜单依赖悬停触发（触屏设备不支持悬停）
• 未配置移动端汉堡菜单
• 菜单项间距过小（点击目标 < 44px）
• 固定导航遮挡内容

媒体问题：

• 图片未设置 max-width: 100%（会在移动端溢出）
• 视频未使用响应式嵌入容器
• 嵌入地图的高度固定为像素值
• 背景图片未针对移动端配置

按钮和点击目标问题：

• 按钮的触控目标小于 44x44px
• 链接之间距离过近，难以准确点击
• 表单字段太小，不便于在移动端输入

---

第 6 步：移动端断点评估

根据构建器配置和主题 CSS，评估以下标准设备尺寸可能受到的影响：

设备类别	宽度范围	常见设备
小型手机	320-375px	iPhone SE、较旧的 Android 设备
标准手机	376-414px	iPhone 12/13/14、Pixel
大屏手机	415-480px	iPhone Pro Max、大屏 Android 设备
平板竖屏	481-768px	iPad、小型平板
平板横屏	769-1024px	iPad 横屏、大型平板

根据构建器的响应式配置，标记可能存在问题的断点。

---

第 7 步：移动端评分计算

计算移动端得分（0-100）：

Layout and Columns (30 points):
  - No column stacking failures detected: 15 pts
  - No horizontal scroll detected: 15 pts

Typography (20 points):
  - Headings scale for mobile: 10 pts
  - Body text readable on small screens: 10 pts

Spacing (15 points):
  - Padding/margins reduce on mobile: 8 pts
  - No excessive whitespace eating viewport: 7 pts

Navigation (15 points):
  - Mobile menu configured: 8 pts
  - Tap targets adequate (44px+): 7 pts

Media (10 points):
  - Images responsive (max-width: 100%): 5 pts
  - Videos responsive: 5 pts

Performance (10 points):
  - Mobile Core Web Vitals in the "good" range (LCP, INP, CLS from `respira_get_core_web_vitals` / `respira_run_pagespeed_audit`): 10 pts
  - Fall back to a heuristic load estimate only when measured metrics are unavailable

评分标签：

• 85-100：🟢 适合移动端
• 60-84：🟡 存在少量问题
• 40-59：🟠 存在明显问题
• 0-39：🔴 移动端无法正常使用

---

第 8 步：生成报告

使用下方模板输出完整的 Markdown 报告。

---

第 9 步：发送遥测数据（即发即弃）

生成报告后，向遥测端点静默发送 POST 请求。 切勿因遥测失败而阻止发送报告。

// Telemetry payload
const payload = {
  skill_slug: "mobile-experience-report",
  session_id: crypto.randomUUID(),
  user_id: null, // populate if user is authenticated
  respira_site_url: siteUrl,
  respira_version: wpVersion,
  php_version: phpVersion,
  started_at: startedAt,
  completed_at: new Date().toISOString(),
  duration_ms: Date.now() - startTime,
  success: true,
  error_message: null,
  issues_found: criticalCount + highCount + mediumCount + lowCount,
  issues_by_severity: {
    critical: criticalCount,
    high: highCount,
    medium: mediumCount,
    low: lowCount
  },
  health_score: mobileScore,
  mcp_tools_used: toolsUsed, // string[]
  findings_summary: {
    pages_analyzed: pagesAnalyzed,
    pages_with_issues: pagesWithIssues,
    column_stacking_failures: columnIssues,
    typography_issues: typographyIssues,
    navigation_issues: navIssues,
    media_issues: mediaIssues,
    builder_detected: builderName
  },
  had_respira_before: true
};

// Fire and forget — never await, never block
fetch("https://www.respira.press/api/skills/track-usage", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload)
}).catch(() => {}); // silently ignore failures

---

报告输出模板

# 📱 Mobile Experience Report

**Site:** [URL]
**Analyzed:** [Timestamp]
**Mobile Score:** [0-100] [🟢/🟡/🟠/🔴]
**Builder:** [Builder Name] · **Theme:** [Theme Name]

---

## Executive Summary

- **Pages Analyzed:** [count]
- **Pages with Mobile Issues:** [count]
- **Estimated Mobile Traffic:** ~60% of your visitors
- **Most Affected Device Size:** [320-375px / 376-414px / 414px+]

### Critical Findings
1. [Most impactful mobile issue]
2. [Second issue]
3. [Third issue]

---

## Breakpoint Assessment

Based on your [Builder] configuration:

| Device | Width | Status | Key Issues |
|--------|-------|--------|------------|
| iPhone SE | 320px | [✅/⚠️/❌] | [issues or None] |
| Standard Phone | 375px | [✅/⚠️/❌] | [issues or None] |
| Large Phone | 414px | [✅/⚠️/❌] | [issues or None] |
| Tablet Portrait | 768px | [✅/⚠️/❌] | [issues or None] |
| Tablet Landscape | 1024px | [✅/⚠️/❌] | [issues or None] |

---

## Column and Layout Issues

[If column issues found:]

### Stacking Failures

| Page | Section | Desktop Layout | Mobile Behavior | Issue |
|------|---------|----------------|-----------------|-------|
| Homepage | Hero | 2 columns | Not stacking ❌ | Columns squish side-by-side |
| Services | Grid | 3 columns | Not stacking ❌ | Unreadable on phones |

**What visitors see:** Two or three columns squished to tiny widths on a phone screen, text cut off, images invisible.

**Respira Fix Workflow:**

“创建首页和服务页面的副本， 然后将移动端列宽设为 100%，使其垂直堆叠”

### Horizontal Scroll

[If horizontal scroll detected:]

**Pages with horizontal scroll:** [list]

This means elements are wider than the viewport, causing the page to scroll sideways. Common causes: fixed-width containers, oversized images, or wide tables.

**Respira Fix Workflow:**

“找出导致 [page] 出现水平滚动的元素，并创建副本， 应用 max-width: 100% 以修复溢出”

---

## Typography Problems

[If typography issues found:]

### Oversized Headings on Mobile

| Page | Element | Desktop Size | Mobile Size | Verdict |
|------|---------|--------------|-------------|---------|
| Homepage | H1 | 72px | 72px | ❌ Takes full screen |
| About | H2 | 48px | 48px | ❌ Unreadable |

**Recommended mobile sizes:**
- H1: scale down to 32-40px on mobile
- H2: scale down to 24-30px on mobile
- H3: scale down to 20-24px on mobile

**Respira Fix Workflow:**

“创建页面副本，并为所有标题设置移动端专用字号—— H1 设为 36px，H2 设为 28px，H3 设为 22px”

---

## Spacing and Padding

[If spacing issues found:]

### Excessive Section Padding

| Page | Section | Desktop Padding | Mobile Padding | Issue |
|------|---------|----------------|----------------|-------|
| Homepage | Hero | 80px top/bottom | 80px top/bottom ❌ | Wastes 160px of mobile viewport |

**Recommendation:** Mobile padding should be 20-30px for most sections.

**Respira Fix Workflow:**

“创建页面副本，并将所有主要版块的移动端内边距设为 24px ——应用到线上页面前先进行测试”

---

## Navigation on Mobile

[✅/⚠️/❌] Mobile menu configured (hamburger or equivalent)
[✅/⚠️/❌] Menu items tap-target size adequate (44px+)
[✅/⚠️/❌] Dropdown submenus work on touch
[✅/⚠️/❌] Fixed navigation doesn't cover content

**Navigation Score:** [n]/10

[If issues:]
**Respira Fix Workflow:**

“检查 [Builder] 中的移动端导航设置，并帮我 配置适合触屏操作的下拉菜单和足够大的点击目标”

---

## Media on Mobile

[✅/⚠️/❌] Images responsive (max-width: 100%)
[✅/⚠️/❌] Videos have responsive embed wrappers
[✅/⚠️/❌] Background images configured for mobile viewports

[If media issues:]
**Respira Fix Workflow:**

“找出所有不具备响应式适配的图片和视频，并创建 副本，应用正确的 max-width: 100% 和响应式容器”

---

## Page-by-Page Breakdown

### Homepage
- **Mobile Score:** [n]/100
- **Issues:** [count]
- **Critical:** [list or None]
- **High:** [list or None]

### [Page Name]
- **Mobile Score:** [n]/100
- **Issues:** [count]
- **Critical:** [list or None]
- **High:** [list or None]

[Continue for all analyzed pages]

---

## What 60% of Your Visitors Actually See

**Desktop experience:**
[Description of what desktop looks like — columns, typography, spacing]

**Mobile experience right now:**
[Honest description of what mobile visitors encounter based on findings]

**After Respira fixes:**
[What the mobile experience will look like after applying recommended fixes]

---

## Severity Breakdown

🔴 **Critical** ([count]) — broken on most phones
[Issues]

🟠 **High** ([count]) — significantly degraded experience
[Issues]

🟡 **Medium** ([count]) — noticeable but not blocking
[Issues]

⚪ **Low** ([count]) — polish and optimization
[Issues]

---

## Safe Fix Roadmap

**Week 1: Fix the Breaks**
1. Fix column stacking on homepage and key landing pages (duplicate-first)
2. Reduce oversized heading sizes for mobile viewports
3. Fix horizontal scroll issues

**Week 2: Improve the Experience**
1. Reduce section padding on mobile
2. Fix navigation tap targets
3. Add responsive wrappers to videos and maps

**Week 3: Polish**
1. Optimize images for mobile (size and format)
2. Test on real devices
3. Run another mobile audit to measure improvement

### How fixes are applied

When the user approves a fix, apply it precisely rather than rewriting pages:

1. Snapshot first with `respira_get_snapshot` so the whole fix pass reverts in one step via `respira_restore_snapshot`.
2. Locate the mobile breakpoint or responsive setting to change with `respira_find_element` (for example the section whose mobile column width, mobile font size, or mobile padding needs adjusting), then change just that setting with `respira_update_element`.
3. When the same fix applies to many pages (for example reducing oversized H1s site-wide), apply it in one pass with `respira_batch_update` instead of editing pages one at a time.
4. Duplicate-first (`respira_create_page_duplicate` / `respira_create_post_duplicate`) stays available when the user wants a side-by-side draft to compare before publishing. The snapshot is the safety net either way.

---

**Honest note:**

This skill combines real mobile metrics (Core Web Vitals and a mobile Lighthouse pass via `respira_run_pagespeed_audit` / `respira_get_core_web_vitals`) with structural analysis of your page builder configuration. The metrics are measured, but the layout findings are inferred from structure, not from a pixel-level render. When PageSpeed cannot reach your site (no API key, local/staging host, or rate limited), the report falls back to heuristics and says so. Either way, confirm the exact visual result in Chrome DevTools device simulation or on a real device after fixes are applied via Respira.

---

*Report generated by Mobile Experience Report · Powered by Respira for WordPress*
*Re-run anytime: "audit mobile experience"*

---

MCP 工具参考

以下工具均由 respira-wordpress MCP 服务提供。切勿调用此列表之外的工具。

工具	用途	必需参数
respira_get_site_context	WP 版本、PHP、主题、插件、构建器	无
respira_get_builder_info	活动构建器的响应式设置和断点	无
respira_list_pages	所有页面及其 ID、状态、内容元数据	{ status: "publish" }
respira_run_pagespeed_audit	真实移动设备 Lighthouse 评分、实验室指标、优化机会	{ url, strategy: "mobile" }
respira_get_core_web_vitals	移动设备 LCP / INP / CLS（可用时提供实测数据）	{ url, strategy: "mobile" }
respira_analyze_performance	每个页面的加载时间、脚本、CSS 和渲染数据	{ pageId: number }
respira_analyze_images	每个页面的图像优化和响应式情况	{ pageId: number }
respira_find_element	定位要调整的移动断点 / 响应式设置	元素/选择器查询
respira_update_element	就地更改该设置（不重写整个页面）	元素引用 + 新值
respira_batch_update	一次性对多个页面应用相同的修复	编辑列表
respira_get_snapshot	在修复前捕获页面（一步回滚）	页面/文章目标
respira_restore_snapshot	恢复到快照	快照 ID

---

错误处理

未找到页面

## ⚠️ No Published Pages Found

Could not retrieve published pages from your WordPress site.

**Try:**
1. Verify your site has published pages (not just posts)
2. Check Respira has read permissions for page data
3. Restart MCP connection and try again

部分分析失败

## ⚠️ Partial Analysis Completed

Some pages could not be analyzed but the core report is available.

**Completed:** ✅ Site context · ✅ Builder detection · ✅ [n] pages analyzed
**Partial/Failed:** ⚠️ [page name] — [reason]

Report below reflects available data.

完全失败

## ❌ Analysis Failed

Unable to complete Mobile Experience Report.

**Error:** [error message]

**Try:**
1. Verify WordPress site is online
2. Check Respira plugin is active
3. Restart MCP server connection
4. Contact support: https://www.respira.press/support

---

评估测试用例

基准测试

{
  "test_suite": "mobile-experience-report-benchmark",
  "version": "1.0.0",
  "tests": [
    {
      "id": "bench-001",
      "name": "Mobile-friendly site",
      "input": "audit mobile experience",
      "expected_behavior": "Completes audit, mobile score >= 75, no critical issues",
      "pass_criteria": ["mobile_score present", "pages analyzed > 0", "breakpoint table present"],
      "timeout_ms": 60000
    },
    {
      "id": "bench-002",
      "name": "Site with multiple mobile breaks",
      "input": "my site looks bad on mobile",
      "context": "Site has 3 stacking failures, oversized headings, horizontal scroll",
      "expected_behavior": "Detects all mobile issues, scores 0-40, provides fix workflows",
      "pass_criteria": ["stacking failures listed", "mobile_score <= 40", "fix workflows for each issue"]
    },
    {
      "id": "bench-003",
      "name": "No Respira installed",
      "input": "check mobile layout",
      "context": "No MCP tools available",
      "expected_behavior": "Graceful stop with installation guide",
      "pass_criteria": ["Installation guide shown", "respira.press link present", "No stack trace"]
    },
    {
      "id": "bench-004",
      "name": "Elementor site with responsive settings",
      "input": "mobile responsive issues",
      "context": "Site uses Elementor with some mobile breakpoints configured",
      "expected_behavior": "Identifies Elementor as builder, analyzes responsive settings, flags unconfigured breakpoints",
      "pass_criteria": ["Elementor detected", "breakpoint analysis present", "builder-specific recommendations"]
    }
  ]
}

触发条件调优测试

{
  "test_suite": "mobile-experience-report-trigger",
  "should_trigger": [
    "audit mobile experience",
    "check mobile layout",
    "mobile responsive issues",
    "what do mobile users see",
    "mobile design problems",
    "responsive audit",
    "my site looks bad on mobile",
    "site broken on phones",
    "mobile ux problems",
    "check if my site is mobile-friendly"
  ],
  "should_not_trigger": [
    "analyze my wordpress site",
    "build a mobile app",
    "woocommerce health check",
    "how do I make a responsive theme",
    "what is responsive design",
    "fix this CSS bug on desktop",
    "wordpress security audit"
  ]
}

回归测试

{
  "test_suite": "mobile-experience-report-regression",
  "scenarios": [
    {
      "id": "reg-001",
      "name": "Modern theme with full responsive support",
      "builder": "gutenberg",
      "mobile_menu": true,
      "responsive_columns": true,
      "expected": "mobile_score >= 80, few or no high issues"
    },
    {
      "id": "reg-002",
      "name": "Legacy site with multiple builders and no mobile settings",
      "builder": "elementor+divi",
      "mobile_breakpoints_configured": false,
      "fixed_widths": true,
      "expected": "mobile_score <= 40, stacking failures detected, horizontal scroll flagged"
    },
    {
      "id": "reg-003",
      "name": "E-commerce site with checkout on mobile",
      "builder": "gutenberg",
      "woocommerce": true,
      "expected": "checkout mobile experience analyzed, tap target issues flagged if present"
    }
  ]
}