firefox-debug

Firefox DevTools 集成技能

用途

此技能可通过 mcporter 无缝集成 Firefox 远程调试协议（RDP），用于开发工作流。它会配置 Firefox，以接受远程调试连接，并提供支持 Agent 驱动的浏览器交互和调试的工具。

前置条件 [CRITICAL]

mise x node@20 -- mcporter call 'firefox-devtools.getVersion'

应返回 Firefox 版本信息（JSON）。如果失败，说明 Firefox 未在端口 6000 上监听。

核心概念

Firefox 远程调试协议（RDP）

Firefox 默认通过端口 6000 上的 WebSocket 连接使用 RDP，并通过 mcporter 提供给 Agent 使用。

主要功能：

• 检查器：操作和检查 DOM
• 调试器：设置 JavaScript 断点并逐步执行
• 控制台：执行脚本并查看日志
• 网络：监控和拦截请求
• 性能：分析运行时性能
• 存储：访问 cookies、localStorage、sessionStorage

可用工具

• firefox-devtools.getVersion [no args]
• firefox-devtools.getTabs [no args]
• firefox-devtools.navigateToUrl [url]
• firefox-devtools.takeScreenshot [tabId]
• firefox-devtools.clickElement [tabId, selector]
• firefox-devtools.fillFormField [tabId, selector, value]
• firefox-devtools.getPageContent [tabId]
• firefox-devtools.evaluateScript [tabId, script]
• firefox-devtools.getConsoleOutput [tabId]
• firefox-devtools.getStorage [tabId, storageType]

常见工作流

1. 检查 Web 应用状态

You: "Navigate to http://localhost:3000 and take a screenshot"
Agent uses Firefox Remote Debugging Protocol → Takes screenshot → Returns visual state

2. 调试 JavaScript 错误

You: "Open DevTools console and read the error messages"
Agent uses Firefox Remote Debugging Protocol → Reads console → Explains errors

3. 自动化测试/验证

You: "Fill the form with test data and submit it"
Agent uses Firefox Remote Debugging Protocol → Automates interaction → Reports results

4. 检查 DOM 和访问存储

You: "Check localStorage for the auth token"
Agent uses Firefox Remote Debugging Protocol → Inspects storage → Returns values

快速参考

任务	mcporter 调用
检查 Firefox 是否正在监听	mise x node@20 -- mcporter call 'firefox-devtools.getVersion'
列出浏览器标签页	mise x node@20 -- mcporter call 'firefox-devtools.getTabs'
截取屏幕截图	mise x node@20 -- mcporter call 'firefox-devtools.takeScreenshot(tabId: "<id>")'
点击元素	mise x node@20 -- mcporter call 'firefox-devtools.clickElement(tabId: "<id>", selector: "#login")'
填写表单字段	mise x node@20 -- mcporter call 'firefox-devtools.fillFormField(tabId: "<id>", selector: "#email", value: "[email protected]")'
获取页面内容	mise x node@20 -- mcporter call 'firefox-devtools.getPageContent(tabId: "<id>")'
导航到 URL	mise x node@20 -- mcporter call 'firefox-devtools.navigateToUrl(tabId: "<id>", url: "http://localhost:3000")'
运行 JavaScript	mise x node@20 -- mcporter call 'firefox-devtools.evaluateScript(tabId: "<id>", script: "document.title")'
读取控制台	mise x node@20 -- mcporter call 'firefox-devtools.getConsoleOutput(tabId: "<id>")'
访问存储	mise x node@20 -- mcporter call 'firefox-devtools.getStorage(tabId: "<id>", storageType: "localStorage")'

详细示例

示例 1：表单测试与存储验证

填写并提交表单，然后验证 localStorage 是否已更新：

TAB_ID=$(mise x node@20 -- mcporter call 'firefox-devtools.getTabs' | jq -r '.[0].id')

# Navigate to form page
mise x node@20 -- mcporter call 'firefox-devtools.navigateToUrl(tabId: "'$TAB_ID'", url: "http://localhost:3000/form")'

sleep 2

# Fill and submit form
mise x node@20 -- mcporter call 'firefox-devtools.fillFormField(tabId: "'$TAB_ID'", selector: "#email", value: "[email protected]")'

mise x node@20 -- mcporter call 'firefox-devtools.fillFormField(tabId: "'$TAB_ID'", selector: "#password", value: "testpass123")'

mise x node@20 -- mcporter call 'firefox-devtools.clickElement(tabId: "'$TAB_ID'", selector: "#submit")'

sleep 1

# Check localStorage for auth token
STORAGE=$(mise x node@20 -- mcporter call 'firefox-devtools.getStorage(tabId: "'$TAB_ID'", storageType: "localStorage")')

echo "$STORAGE" | jq '.auth_token'

示例 2：JavaScript 测量与悬停交互

测量元素属性并模拟悬停状态：

TAB_ID=$(mise x node@20 -- mcporter call 'firefox-devtools.getTabs' | jq -r '.[0].id')

# Navigate to page with interactive elements
mise x node@20 -- mcporter call 'firefox-devtools.navigateToUrl(tabId: "'$TAB_ID'", url: "http://localhost:3000/interactive")'

sleep 2

# Measure element dimensions and trigger hover
MEASUREMENTS=$(mise x node@20 -- mcporter call 'firefox-devtools.evaluateScript(tabId: "'$TAB_ID'", script: "const el = document.querySelector(\".interactive-button\"); const bounds = el.getBoundingClientRect(); el.dispatchEvent(new MouseEvent(\"mouseenter\", { bubbles: true })); setTimeout(() => { const computed = window.getComputedStyle(el); console.log(JSON.stringify({ bounds: { x: bounds.x, y: bounds.y, width: bounds.width, height: bounds.height }, backgroundColor: computed.backgroundColor, transform: computed.transform, opacity: computed.opacity })); }, 300);")')

echo "$MEASUREMENTS" | jq '.'

示例 3：使用连续屏幕截图进行性能测试

测量页面加载性能并捕捉视觉变化过程：

TAB_ID=$(mise x node@20 -- mcporter call 'firefox-devtools.getTabs' | jq -r '.[0].id')
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
SCREENSHOT_DIR="./firefox-screenshots/$TIMESTAMP"
mkdir -p "$SCREENSHOT_DIR"

# Clear and start fresh
mise x node@20 -- mcporter call 'firefox-devtools.evaluateScript(tabId: "'$TAB_ID'", script: "performance.mark(\"test-start\");")'

# Navigate and capture
mise x node@20 -- mcporter call 'firefox-devtools.navigateToUrl(tabId: "'$TAB_ID'", url: "http://localhost:3000/dashboard")'

# Screenshot at different stages
sleep 1
mise x node@20 -- mcporter call 'firefox-devtools.takeScreenshot(tabId: "'$TAB_ID'")' > "$SCREENSHOT_DIR/01-load-complete.png"

sleep 2
mise x node@20 -- mcporter call 'firefox-devtools.takeScreenshot(tabId: "'$TAB_ID'")' > "$SCREENSHOT_DIR/02-render-complete.png"

# Measure performance metrics
PERF=$(mise x node@20 -- mcporter call 'firefox-devtools.evaluateScript(tabId: "'$TAB_ID'", script: "const perf = performance.getEntriesByType(\"navigation\")[0]; { pageLoadTime: perf.loadEventEnd - perf.fetchStart, domContentLoaded: perf.domContentLoadedEventEnd - perf.fetchStart, firstPaint: performance.getEntriesByName(\"first-paint\")[0]?.startTime || null }")')

echo "$PERF" | jq '.' > "$SCREENSHOT_DIR/perf-metrics.json"
echo "Test complete. Results in: $SCREENSHOT_DIR"

故障排除

连接被拒绝

# Verify Firefox is running with debugging enabled
ps aux | grep firefox.*6000
# Or explicitly launch with port
firefox --remote-debugging-port 6000 &

端口已被占用

# Use custom port
firefox --remote-debugging-port 7000 &
# Then update mcporter config or pass port parameter

性能注意事项

1. RDP 开销：远程调试只会带来极小的开销
2. 端口绑定：使用较高编号的端口（>6000）以避免冲突
3. 内存：启用调试功能的 Firefox 会多使用约 10-15% 的内存

实际影响

将 Firefox Remote Debugging Protocol 集成到 mcporter 后，可以：

• 在 Agent 对话过程中实时调试浏览器
• 自动化测试和验证表单
• 直观查看应用行为的反馈
• 收集和分析性能指标
• 检查存储内容，以调试身份验证和会话问题

若没有此集成，调试 Firefox 应用时需要在浏览器和 Agent 之间切换上下文。

参考资料

• Mozilla Remote Debugging Protocol
• Firefox WebDriver
• DevTools Server

相关技能

• devtools/chrome-debug - Chrome 的同类工具
• superpowers/systematic-debugging - 通用调试方法
• experts/quality-security/debugger - 调试专家指导
• superpowers/frontend-developer - 前端开发背景知识

技能元数据

• 类别：DevTools 集成
• 复杂度：中级
• 领域：浏览器调试、开发工具
• 平台：Linux、macOS、Windows
• 最后更新：2025-12-15