chrome-devtools

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会改写旧版 Claude /skill-name 引用。
• 任务跟踪要求：执行任何工作流或技能步骤之前，必须先为所有步骤创建或更新任务跟踪，并随着进度变化保持同步。
• 需要向用户提问时，表示在 Codex 中直接询问用户。
• 遇到 Claude 专属的模式切换指令时，请忽略。
• 严格执行约定：用户明确调用某项技能时，必须按原样执行该技能协议。
• 子 Agent 授权：用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，该技能的启用即授权为该任务使用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，必须明确执行每个列出的子技能步骤，并逐步报告证据。
• 如果在此环境中无法执行某个必要步骤或工具，请停止并在调整方案前询问用户。

Codex 项目参考文档加载（无钩子）

Codex 不会通过基于 Claude 钩子的方式注入文档。 进行编码、规划、调试、测试或审查时，请按照以下路由显式打开项目文档。

始终阅读：

• docs/project-config.json（项目专用路径、命令、模块和工作流/测试设置）
• docs/project-reference/docs-index-reference.md（指向完整 docs/project-reference/* 目录的路由）
• docs/project-reference/lessons.md（始终适用的护栏和反模式）

根据情况阅读的文档：

• 后端/CQRS/API/领域/实体变更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• 前端/UI/样式/设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 规范/测试用例规划或 TC 映射：feature-docs-reference.md
• 集成测试的实现/审查：integration-test-reference.md
• E2E 测试的实现/审查：e2e-test-reference.md
• 代码审查/审计工作：code-review-rules.md，以及根据变更文件选择上述领域文档

不要不加区分地阅读所有文档。请从 docs-index-reference.md 入手，然后只打开与任务相关的文件。

快速摘要

目标： 使用带持久会话的 Puppeteer CLI 脚本，实现浏览器交互、调试和性能分析自动化。

工作流：

1. 发现结构 — 使用 aria-snapshot.js 获取未知页面的 ARIA 树
2. 按 Ref 交互 — 使用 select-ref.js 通过稳定的引用点击、填充和悬停元素
3. 收集证据 — 截取屏幕截图、收集控制台日志、监控网络流量
4. 分析 — 性能分析、无障碍审计、视觉回归检查

关键规则：

• Windows/macOS 上使用有头模式；仅在 Linux/WSL/CI 上使用无头模式
• 所有脚本都以 JSON 格式输出，便于结构化处理
• 将快照以时间戳命名，存储在 .claude/chrome-devtools/snapshots/ 中

保持审慎。运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，并给出置信度百分比（Idea 应高于 80%）。

Chrome DevTools Agent 技能

通过带持久会话的 Puppeteer 脚本实现浏览器自动化。所有脚本都输出 JSON。

技能位置

技能可以位于项目范围或用户范围。优先级：项目范围 > 用户范围。

# Detect skill location
SKILL_DIR=""
if [ -d ".claude/skills/chrome-devtools/scripts" ]; then
  SKILL_DIR=".claude/skills/chrome-devtools/scripts"
elif [ -d "$HOME/.claude/skills/chrome-devtools/scripts" ]; then
  SKILL_DIR="$HOME/.claude/skills/chrome-devtools/scripts"
fi
cd "$SKILL_DIR"

选择方法

场景	方法
可查看源代码的网站	先读取源代码，直接编写选择器
未知布局	使用 aria-snapshot.js 进行语义发现
视觉检查	截取屏幕截图以验证渲染效果
调试问题	收集控制台日志，使用会话存储进行分析
无障碍审计	使用 ARIA 快照分析语义结构

自动化浏览运行模式

• 检测当前操作系统，仅在 Linux、WSL 或 CI 环境中以无头模式启动浏览器。
• 在 macOS/Windows 上，浏览器始终以有头模式运行，以便更好地调试。
• 并行运行多个脚本/会话，以模拟真实用户交互。
• 并行运行多个脚本/会话，以模拟不同设备类型（手机、平板、桌面设备）。
• 技能可以存在于项目范围或用户范围。优先级：项目范围 > 用户范围。

ARIA 快照（元素发现）

当页面结构未知时，使用 aria-snapshot.js 获取 YAML 格式的无障碍树，其中包含语义角色、无障碍名称、状态和稳定的元素引用。

获取 ARIA 快照

# Generate ARIA snapshot and output to stdout
node aria-snapshot.js --url https://example.com

# Save to file in snapshots directory
node aria-snapshot.js --url https://example.com --output ./.claude/chrome-devtools/snapshots/page.yaml

YAML 输出示例

- banner:
  - link "Hacker News" [ref=e1]
    /url: https://news.ycombinator.com
  - navigation:
    - link "new" [ref=e2]
    - link "past" [ref=e3]
    - link "comments" [ref=e4]
- main:
  - list:
    - listitem:
      - link "Show HN: My new project" [ref=e8]
      - text: "128 points by user 3 hours ago"
- contentinfo:
  - textbox [ref=e10]
    /placeholder: "Search"

解读 ARIA 表示法

表示法	含义
[ref=eN]	交互元素的稳定标识符
[checked]	复选框/单选框已选中
[disabled]	元素处于非活动状态
[expanded]	手风琴菜单/下拉菜单已展开
[level=N]	标题层级（1-6）
/url:	链接目标
/placeholder:	输入框占位文本
/value:	当前输入值

按引用交互

技能可以存在于项目范围或用户范围。优先级：项目范围 > 用户范围。 使用 select-ref.js 按元素的 ref 进行交互：

# Click element with ref e5
node select-ref.js --ref e5 --action click

# Fill input with ref e10
node select-ref.js --ref e10 --action fill --value "search query"

# Get text content
node select-ref.js --ref e8 --action text

# Screenshot specific element
node select-ref.js --ref e1 --action screenshot --output ./logo.png

# Focus element
node select-ref.js --ref e10 --action focus

# Hover over element
node select-ref.js --ref e5 --action hover

存储快照

技能可以存在于项目范围或用户范围。优先级：项目范围 > 用户范围。 将快照存储在 <project>/.claude/chrome-devtools/snapshots/ 中以供分析：

# Create snapshots directory
mkdir -p .claude/chrome-devtools/snapshots

# Capture and store with timestamp
SESSION="$(date +%Y%m%d-%H%M%S)"
node aria-snapshot.js --url https://example.com --output .claude/chrome-devtools/snapshots/$SESSION.yaml

工作流：未知页面结构

1. 获取快照以发现元素：

   node aria-snapshot.js --url https://example.com
   

2. 从 YAML 输出中识别目标（例如，按钮对应 [ref=e5]）

3. 按引用交互：

   node select-ref.js --ref e5 --action click
   

4. 使用屏幕截图或新快照验证结果：

   node screenshot.js --output ./result.png
   

本地 HTML 文件

技能可以存在于项目范围或用户范围。优先级：项目范围 > 用户范围。 重要：切勿通过 file:// 协议浏览本地 HTML 文件。务必通过本地服务提供文件： 原因：file:// 协议会阻止许多浏览器功能（CORS、ES 模块、fetch API、服务工作线程）。本地服务可确保正常的 HTTP 行为。

# Option 1: npx serve (recommended)
npx serve ./dist -p 3000 &
node navigate.js --url http://localhost:3000

# Option 2: Python http.server
python -m http.server 3000 --directory ./dist &
node navigate.js --url http://localhost:3000

注意：当端口 3000 被占用时，使用 lsof -i:3000 查找可用端口，并改用其他端口。

快速开始

# Install dependencies
cd .claude/skills/chrome-devtools/scripts
npm install  # Installs puppeteer, sharp, debug, yargs

# Test (browser stays running for session reuse)
node navigate.js --url https://example.com
# Output: {"success": true, "url": "...", "title": "..."}

仅限 Linux/WSL：先运行 ./install-deps.sh 以安装 Chrome 系统库。

会话持久化

浏览器状态会通过 WebSocket 端点文件（.browser-session.json）在脚本执行之间持久保存。

默认行为：脚本会断开连接，但浏览器会继续运行，以便在后续会话中复用。

# First script: launches browser, navigates, disconnects (browser stays running)
node navigate.js --url https://example.com/login

# Subsequent scripts: connect to existing browser, reuse page state
node fill.js --selector "#email" --value "[email protected]"
node fill.js --selector "#password" --value "secret"
node click.js --selector "button[type=submit]"

# Close browser when done
node navigate.js --url about:blank --close true

会话管理：

• --close true：关闭浏览器并清除会话
• 默认（不带标志）：保持浏览器运行，以供下一个脚本使用

可用脚本

技能可以是项目级或用户级。优先级：项目级 > 用户级。 所有脚本均位于 .claude/skills/chrome-devtools/scripts/：

脚本	用途
navigate.js	导航至 URL
screenshot.js	捕获屏幕截图（超过 5MB 时通过 Sharp 自动压缩）
click.js	点击元素
fill.js	填写表单字段
evaluate.js	在页面上下文中执行 JS
snapshot.js	提取交互元素（JSON 格式）
aria-snapshot.js	获取 ARIA 无障碍树（带引用的 YAML 格式）
select-ref.js	按 ARIA 快照中的引用与元素交互
console.js	监控控制台消息/错误
network.js	跟踪 HTTP 请求/响应
performance.js	测量 Core Web Vitals

工作流循环

1. 执行用于单一任务的专用脚本
2. 观察 JSON 输出
3. 评估完成状态
4. 决定下一步操作
5. 重复直到完成

编写自定义测试脚本

技能可以是项目级或用户级。优先级：项目级 > 用户级。 对于复杂的自动化任务，将脚本写入 <project>/.claude/chrome-devtools/tmp/：

# Create tmp directory for test scripts
mkdir -p $SKILL_DIR/.claude/chrome-devtools/tmp

# Write a test script
cat > $SKILL_DIR/.claude/chrome-devtools/tmp/login-test.js << 'EOF'
import { getBrowser, getPage, disconnectBrowser, outputJSON } from '../scripts/lib/browser.js';

async function loginTest() {
  const browser = await getBrowser();
  const page = await getPage(browser);

  await page.goto('https://example.com/login');
  await page.type('#email', '[email protected]');
  await page.type('#password', 'secret');
  await page.click('button[type=submit]');
  await page.waitForNavigation();

  outputJSON({
    success: true,
    url: page.url(),
    title: await page.title()
  });

  await disconnectBrowser();
}

loginTest();
EOF

# Run the test
node $SKILL_DIR/.claude/chrome-devtools/tmp/login-test.js

自定义脚本的关键原则：

• 单一用途：一个脚本，一个任务
• 始终在末尾调用 disconnectBrowser()（保持浏览器运行）
• 仅在完全结束会话时使用 closeBrowser()
• 输出 JSON，便于解析
• page.evaluate() 回调中仅使用纯 JavaScript

屏幕截图

技能可以是项目级或用户级。优先级：项目级 > 用户级。 将用于分析的屏幕截图存储在 <project>/.claude/chrome-devtools/screenshots/：

# Basic screenshot
node screenshot.js --url https://example.com --output ./.claude/chrome-devtools/screenshots/page.png

# Full page
node screenshot.js --url https://example.com --output ./.claude/chrome-devtools/screenshots/page.png --full-page true

# Specific element
node screenshot.js --url https://example.com --selector ".main-content" --output ./.claude/chrome-devtools/screenshots/element.png

自动压缩（Sharp）

超过 5MB 的屏幕截图会使用 Sharp 自动压缩（速度比 ImageMagick 快 4-5 倍）：

# Default: compress if >5MB
node screenshot.js --url https://example.com --output ./.claude/chrome-devtools/screenshots/page.png

# Custom threshold (3MB)
node screenshot.js --url https://example.com --output ./.claude/chrome-devtools/screenshots/page.png --max-size 3

# Disable compression
node screenshot.js --url https://example.com --output ./.claude/chrome-devtools/screenshots/page.png --no-compress

将用于分析的屏幕截图存储在 <project>/.claude/chrome-devtools/screenshots/。

控制台日志收集与分析

技能可以是项目级或用户级。优先级：项目级 > 用户级。

捕获日志

# Capture all logs for 10 seconds
node console.js --url https://example.com --duration 10000

# Filter by type
node console.js --url https://example.com --types error,warn --duration 5000

会话存储模式

将用于分析的日志存储在 <project>/.claude/chrome-devtools/logs/<session>/：

# Create session directory
SESSION="$(date +%Y%m%d-%H%M%S)"
mkdir -p .claude/chrome-devtools/logs/$SESSION

# Capture and store
node console.js --url https://example.com --duration 10000 > .claude/chrome-devtools/logs/$SESSION/console.json
node network.js --url https://example.com > .claude/chrome-devtools/logs/$SESSION/network.json

# View errors
jq '.messages[] | select(.type=="error")' .claude/chrome-devtools/logs/$SESSION/console.json

根因分析

# 1. Check for JavaScript errors
node console.js --url https://example.com --types error,pageerror --duration 5000 | jq '.messages'

# 2. Correlate with network failures
node network.js --url https://example.com | jq '.requests[] | select(.response.status >= 400)'

# 3. Check specific error stack traces
node console.js --url https://example.com --types error --duration 5000 | jq '.messages[].stack'

查找元素

技能可以是项目级或用户级。优先级：项目级 > 用户级。 交互前，使用 snapshot.js 查找选择器：

# Get all interactive elements
node snapshot.js --url https://example.com | jq '.elements[] | {tagName, text, selector}'

# Find buttons
node snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="button")'

# Find by text content
node snapshot.js --url https://example.com | jq '.elements[] | select(.text | contains("Submit"))'

错误恢复

技能可以是项目级或用户级。优先级：项目级 > 用户级。 如果脚本失败：

# 1. Capture current state (without navigating to preserve state)
node screenshot.js --output ./.claude/skills/chrome-devtools/screenshots/debug.png

# 2. Get console errors
node console.js --url about:blank --types error --duration 1000

# 3. Discover correct selector
node snapshot.js | jq '.elements[] | select(.text | contains("Submit"))'

# 4. Try XPath if CSS fails
node click.js --selector "//button[contains(text(),'Submit')]"

常见模式

网页抓取

node evaluate.js --url https://example.com --script "
  Array.from(document.querySelectorAll('.item')).map(el => ({
    title: el.querySelector('h2')?.textContent,
    link: el.querySelector('a')?.href
  }))
" | jq '.result'

表单自动化

node navigate.js --url https://example.com/form
node fill.js --selector "#search" --value "query"
node click.js --selector "button[type=submit]"

性能测试

node performance.js --url https://example.com | jq '.vitals'

脚本选项

所有脚本均支持：

• --headless false - 显示浏览器窗口
• --close true - 完全关闭浏览器（默认：保持运行）
• --timeout 30000 - 设置超时时间（毫秒）
• --wait-until networkidle2 - 等待策略 技能可以是项目级或用户级。优先级：项目级 > 用户级。

故障排除

技能可分为项目级或用户级。优先级：项目级 > 用户级。

错误	解决方案
Cannot find package 'puppeteer'	在脚本目录中运行 npm install
libnss3.so 缺失（Linux）	运行 ./install-deps.sh
未找到元素	使用 snapshot.js 查找正确的选择器
脚本卡住	使用 --timeout 60000 或 --wait-until load
截图 >5MB	会自动压缩；使用 --max-size 3 降低大小
会话过期	删除 .browser-session.json 并重试

截图分析：缺少图像

如果截图中没有显示图像，它们可能正在等待动画触发：

1. 滚动触发的动画：先将元素滚动到可视区域

   node evaluate.js --script "document.querySelector('.lazy-image').scrollIntoView()"
   # 等待动画
   node evaluate.js --script "await new Promise(r => setTimeout(r, 1000))"
   node screenshot.js --output ./result.png
   

2. 顺序动画队列：等待更长时间后重试

   # 首次尝试
   node screenshot.js --url http://localhost:3000 --output ./attempt1.png
   
   # 等待动画完成
   node evaluate.js --script "await new Promise(r => setTimeout(r, 2000))"
   
   # 重试截图
   node screenshot.js --output ./attempt2.png
   

3. Intersection Observer 动画：通过滚动浏览页面触发

   node evaluate.js --script "window.scrollTo(0, document.body.scrollHeight)"
   node evaluate.js --script "await new Promise(r => setTimeout(r, 1500))"
   node evaluate.js --script "window.scrollTo(0, 0)"
   node screenshot.js --output ./full-loaded.png --full-page true
   

参考文档

• ./references/cdp-domains.md - Chrome DevTools Protocol 域
• ./references/puppeteer-reference.md - Puppeteer API 模式
• ./references/performance-guide.md - Core Web Vitals 优化
• ./scripts/README.md - 脚本选项详解

---

[IMPORTANT] 开始前，必须使用任务跟踪将所有工作拆分为小任务——包括为每个要读取的文件创建任务。这可以防止因文件过长而丢失上下文。对于简单任务，AI 必须注意询问用户是否跳过。

避免 AI 出错 — 每项任务都要避免以下失败模式：

删除前检查下游引用。 删除组件会引发文档和代码过时的连锁问题。删除前先梳理所有引用该组件的文件。 根据实际代码核实 AI 生成的内容。 AI 会臆造 API、类名和方法签名。记录或引用前，务必使用 grep 确认它们确实存在。 编辑后追踪完整依赖链。 修改定义时，容易遗漏由此派生的下游变量和使用方。务必追踪完整链路。 验证正确性时追踪所有代码路径。 确认代码存在，不等于确认代码会执行。务必检查提前退出、错误分支和条件跳过，而不只是正常路径。 调试时，修复前先问“谁负责？”。 追踪 bug 是出在调用方（数据错误）还是被调用方（处理错误）。在负有责任的层级修复，切勿只修补症状所在的位置。 假设现有值是有意设置的——修改前先问为什么。 修改任何常量、限制、标志或模式前：阅读注释，检查 git blame，并查看周边代码。 核实所有受影响的输出，而不只是第一个。 涉及多个技术栈的更改，需要核实每一个输出。一个检查通过，不代表全部检查都通过。 整体优先的调试方式——避免只关注最近线索的陷阱。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、DI 注册、数据前置条件），再逐项根据证据核实，然后再提出任何代码层面的假设。 精准修改——执行差异测试。 修复 bug 时，每一处改动都必须能直接对应到该 bug。不要顺便重排格式或改进相邻代码。增强任务：实现改进，并明确说明。 编码前揭示歧义——不要默默自行选择。 如果请求有多种理解方式，请列出每种方式及其工作量预估并询问用户。切勿默认采用全部记录、基于文件或更复杂的路径。

批判性思维 — 运用批判性思维和顺序思维。每项断言都需要可追溯的证据，置信度 >80% 才能采取行动。 防止幻觉： 切勿把猜测说成事实——每项断言都要引用来源，坦诚承认不确定性，自行检查输出是否有误，通过独立交叉引用核实，并对自己的确信程度保持怀疑——没有证据的确定性是一切幻觉的根源。

务必注意运用批判性思维——每项断言都需要可追溯的证据，置信度 >80% 才能采取行动。防止幻觉：切勿把猜测说成事实。

务必注意遵循 AI 防错要求——整体优先调试，在负有责任的层级修复，编码前揭示歧义，并在压缩上下文后重新阅读文件。

收尾提醒

• 强制要求：开始前务必注意将工作拆分为小型待办任务，并使用任务跟踪
• 强制要求：创建新代码前，务必注意在代码库中搜索 3 个或更多类似模式
• 强制要求：每项断言都务必注意引用 file:line 证据（置信度 >80% 才能采取行动）
• 强制要求：务必注意添加最终审查待办任务，以核实工作质量

[TASK-PLANNING] 开始前，分析任务范围，并使用任务跟踪系统地将工作拆分为小型待办任务和子任务。

无钩子提示词协议镜像（自动同步）

来源：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制、重要、必须、关键。无论出于何种原因，都不得跳过。

通用可移植性边界： 可复用的技能和协议文本应与项目无关；从 docs/project-config.json 和 docs/project-reference/ 中查找项目特定约定。应用 shared/sdd-artifact-contract.md 中的共享 AI-SDD。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。只要具备此共享上下文和本地文档，任何受支持的 AI 工具都可以执行。

1. 检测： 将提示词与工作流目录进行匹配
2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
3. 询问（必需格式）： 直接向用户提问，采用以下结构；除非用户明确调用了某个工作流／技能，且本地协议将明确调用视为确认：
   • 问题："你想启用哪个工作流？"
   • 选项 1："启用 [最佳匹配工作流]（推荐）"
   • 选项 2："启用自定义工作流：[步骤 1 → 步骤 2 → ...]"（附上一句话说明理由）
4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；自定义步骤按顺序手动执行
5. 创建任务： 跟踪工作流的所有步骤
6. 执行： 按顺序遵循每个步骤 [CRITICAL-THINKING-MINDSET] 运用批判性思维和顺序思维。每项声明都必须有可追溯的证据；置信度超过 80% 才能采取行动。 反幻觉原则： 切勿将猜测当作事实；每项声明都要引用来源；坦率承认不确定性；自行检查输出是否有误；独立交叉核对；对自己的判断保持怀疑——没有证据的确信是所有幻觉的根源。 AI 注意力原则（首因－近因效应）： 对于较长的提示词／协议，将最关键的 3 条规则同时放在开头和结尾，以确保指令在较长上下文窗口中仍能得到遵循。 目标驱动执行： 先定义成功标准，循环执行直至验证通过，并且只有在可观察的检查均通过后才停止。 测试验证意图： 测试必须保护业务规则／不变量，并在受保护的意图被破坏时失败，而不能只照搬当前行为。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — 强制执行。不得跳过。

开始前将工作拆分为小任务并进行跟踪。添加最终任务："分析 AI 错误与经验教训"。

提取经验教训——仅限根本原因，不处理表面症状：

1. 指明失败模式（推理／假设失误），而非症状——例如“未阅读源代码就假设 API 存在”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境／代码库？如果不适用，就再抽象一层。
3. 将其写成通用规则——去除项目特定的名称／路径／类。该规则应适用于任何代码库。
4. 合并：多个错误若有相同的失败模式 → 总结为一条经验教训。
5. 重复发生检查：“如果没有这条提醒，未来会话中还会发生这种情况吗？”——不会 → 跳过 $learn。
6. 自动修复检查：“$code-review／$code-simplifier／$security／$lint 能否发现此问题？”——能 → 改进相应的审查技能。
7. 两项检查均通过 → 请用户运行 $learn。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；然后随着每个步骤开始／完成，持续同步任务状态。