{
"canonical_name": "ChromeDevTools/chrome-devtools-mcp",
"compilation_id": "pack_9ae45373ba5e44df86beb2f042f9cd31",
"created_at": "2026-05-13T09:25:11.064561+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx chrome-devtools-mcp@latest` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx chrome-devtools-mcp@latest",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_35dd409a2ec54525b59d71f315a7d986"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_ea204f7aae720e4458e992ed6fe167de",
"canonical_name": "ChromeDevTools/chrome-devtools-mcp",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/ChromeDevTools/chrome-devtools-mcp",
"slug": "chrome-devtools-mcp",
"source_packet_id": "phit_aa292603359a4e64b06d07d564682164",
"source_validation_id": "dval_4bf0f41c618044f5bad63623dbb605c1"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 mcp_host的用户",
"github_forks": 2503,
"github_stars": 39420,
"one_liner_en": "Chrome DevTools for coding agents",
"one_liner_zh": "Chrome DevTools for coding agents",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:coding, test, git"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "chrome-devtools-mcp",
"title_zh": "chrome-devtools-mcp 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Page Observation and Action Planning",
"label_zh": "页面观察与动作规划",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-page-observation-and-action-planning",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_aa292603359a4e64b06d07d564682164",
"page_model": {
"artifacts": {
"artifact_slug": "chrome-devtools-mcp",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx chrome-devtools-mcp@latest",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/ChromeDevTools/chrome-devtools-mcp#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"页面观察与动作规划",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Chrome DevTools for coding agents"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling — measurements come back partially or full…",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_644cef1d4144424abe63f24528f5d082 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1955 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_3275fc356e284918a94cf8c2c037caee | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2004 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_1946d257bfb04c23a67250da4d584631 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1943 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chrome-devtools-mcp: v0.20.1",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_11700367e17048138ab79571d751cec4 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：chrome-devtools-mcp: v0.20.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chrome-devtools-mcp: v0.22.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_6ff69eabdc334130b7b093706390c6c1 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：chrome-devtools-mcp: v0.22.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chrome-devtools-mcp: v0.21.0",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_41b2681dc7ae4bbabdb071511fdc0191 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.21.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：chrome-devtools-mcp: v0.21.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.20.0",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_8bef6b0b7a80406ab00a0576f82b35a7 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：chrome-devtools-mcp: v0.20.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.24.0",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_e42176fdf7da4015ac82844a46f37c08 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.24.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：chrome-devtools-mcp: v0.24.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.26.0",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_a6cf1fa6206f48e6a9e88a5d9d00fd64 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.26.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：chrome-devtools-mcp: v0.26.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Close empty-object tool schemas for stricter MCP client validation",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_2af67f120a9d4486998a92da71a92cb9 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2049 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Close empty-object tool schemas for stricter MCP client validation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：chrome-devtools-mcp: v0.25.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_51ee93809f08423dbc7b6c0d3eeddc77 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.25.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：chrome-devtools-mcp: v0.25.0",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 18 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 85,
"forks": 2503,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 39420
},
"source_url": "https://github.com/ChromeDevTools/chrome-devtools-mcp",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Chrome DevTools for coding agents",
"title": "chrome-devtools-mcp 能力包",
"trial_prompt": "# chrome-devtools-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 chrome-devtools-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速开始指南。围绕“快速开始指南”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. tool-reference：工具参考。围绕“工具参考”模拟一次用户任务，不展示安装或运行结果。\n5. input-automation：输入自动化工具。围绕“输入自动化工具”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速开始指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. tool-reference\n输入：用户提供的“工具参考”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. input-automation\n输入：用户提供的“输入自动化工具”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速开始指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / tool-reference：Step 4 必须围绕“工具参考”形成一个小中间产物，并等待用户确认。\n- Step 5 / input-automation：Step 5 必须围绕“输入自动化工具”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/ChromeDevTools/chrome-devtools-mcp\n- https://github.com/ChromeDevTools/chrome-devtools-mcp#readme\n- skills/a11y-debugging/SKILL.md\n- skills/chrome-devtools/SKILL.md\n- skills/chrome-devtools-cli/SKILL.md\n- skills/debug-optimize-lcp/SKILL.md\n- skills/memory-leak-debugging/SKILL.md\n- skills/troubleshooting/SKILL.md\n- README.md\n- src/index.ts\n- package.json\n- src/bin/chrome-devtools-mcp.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 chrome-devtools-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Auto-connect doesn't work on WSL with mirrored networking (Chrome on Win（https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2004）；github/github_issue: Close empty-object tool schemas for stricter MCP client validation（https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2049）；github/github_issue: performance_start_trace records 'CPU throttling: none / Network throttli（https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1955）；github/github_issue: Update check hardcodes registry.npmjs.org, ignoring user's npm registry （https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1943）；github/github_release: chrome-devtools-mcp: v0.26.0（https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.26.0）；github/github_release: chrome-devtools-mcp: v0.25.0（https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.25.0）；github/github_release: chrome-devtools-mcp: v0.24.0（https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.24.0）；github/github_release: chrome-devtools-mcp: v0.22.0（https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.22.0）；github/github_release: chrome-devtools-mcp: v0.21.0（https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.21.0）；github/github_release: chrome-devtools-mcp: v0.20.3（https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.3）；github/github_release: chrome-devtools-mcp: v0.20.1（https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.1）；github/github_release: chrome-devtools-mcp: v0.20.0（https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Auto-connect doesn't work on WSL with mirrored networking (Chrome on Win",
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2004"
},
{
"kind": "github_issue",
"source": "github",
"title": "Close empty-object tool schemas for stricter MCP client validation",
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2049"
},
{
"kind": "github_issue",
"source": "github",
"title": "performance_start_trace records 'CPU throttling: none / Network throttli",
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1955"
},
{
"kind": "github_issue",
"source": "github",
"title": "Update check hardcodes registry.npmjs.org, ignoring user's npm registry ",
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1943"
},
{
"kind": "github_release",
"source": "github",
"title": "chrome-devtools-mcp: v0.26.0",
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.26.0"
},
{
"kind": "github_release",
"source": "github",
"title": "chrome-devtools-mcp: v0.25.0",
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.25.0"
},
{
"kind": "github_release",
"source": "github",
"title": "chrome-devtools-mcp: v0.24.0",
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.24.0"
},
{
"kind": "github_release",
"source": "github",
"title": "chrome-devtools-mcp: v0.22.0",
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.22.0"
},
{
"kind": "github_release",
"source": "github",
"title": "chrome-devtools-mcp: v0.21.0",
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.21.0"
},
{
"kind": "github_release",
"source": "github",
"title": "chrome-devtools-mcp: v0.20.3",
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.3"
},
{
"kind": "github_release",
"source": "github",
"title": "chrome-devtools-mcp: v0.20.1",
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.1"
},
{
"kind": "github_release",
"source": "github",
"title": "chrome-devtools-mcp: v0.20.0",
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.0"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Chrome DevTools for coding agents",
"effort": "安装已验证",
"forks": 2503,
"icon": "code",
"name": "chrome-devtools-mcp 能力包",
"risk": "可发布",
"slug": "chrome-devtools-mcp",
"stars": 39420,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"页面观察与动作规划",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/ChromeDevTools/chrome-devtools-mcp 项目说明书\n\n生成时间：2026-05-13 09:07:08 UTC\n\n## 目录\n\n- [项目介绍](#project-introduction)\n- [快速开始指南](#quick-start)\n- [系统架构](#system-architecture)\n- [守护进程系统](#daemon-system)\n- [工具参考](#tool-reference)\n- [输入自动化工具](#input-automation)\n- [性能分析工具](#performance-tools)\n- [内存调试工具](#memory-debugging)\n- [CLI与配置](#cli-configuration)\n- [MCP客户端集成](#mcp-client-integration)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [快速开始指南](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/README.md)\n- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n- [package.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/package.json)\n- [src/index.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/index.ts)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n- [src/PageCollector.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/PageCollector.ts)\n- [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n- [skills/a11y-debugging/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/a11y-debugging/SKILL.md)\n \n\n# 项目介绍\n\n## 概述\n\nchrome-devtools-mcp 是一个基于 Model Context Protocol (MCP) 的 Chrome DevTools 服务器和命令行工具。该项目由 Google Chrome 团队维护，提供了一套完整的浏览器自动化、调试和性能分析能力。资料来源：[AGENTS.md]()\n\n项目的主要目标是让开发者能够通过 MCP 协议与 Chrome 浏览器进行交互，实现网页自动化、元素操作、性能分析、无障碍调试等功能。资料来源：[skills/chrome-devtools/SKILL.md]()\n\n## 核心架构\n\n### 技术栈\n\n| 组件 | 技术 | 说明 |\n|------|------|------|\n| 运行时 | Node.js / TypeScript | 使用严格类型检查 |\n| 协议 | MCP (Model Context Protocol) | 与 AI 模型交互的标准协议 |\n| 浏览器控制 | Puppeteer | Chrome DevTools Protocol 封装 |\n| 验证 | Zod | Schema 验证库 |\n\n资料来源：[package.json]()\n\n### 架构图\n\n```mermaid\ngraph TB\n subgraph \"客户端层\"\n AI[AI 模型 / Claude]\n CLI[CLI 工具]\n end\n \n subgraph \"MCP 协议层\"\n MCPServer[MCP Server]\n Protocol[MCP Protocol]\n end\n \n subgraph \"工具层\"\n Navigation[导航工具]\n Performance[性能工具]\n A11y[无障碍工具]\n Interaction[交互工具]\n Network[网络工具]\n WebMCP[WebMCP 工具]\n end\n \n subgraph \"浏览器层\"\n CDP[Chrome DevTools Protocol]\n Chrome[Chrome Browser]\n end\n \n AI --> MCPServer\n CLI --> MCPServer\n MCPServer --> Protocol\n Protocol --> Navigation\n Protocol --> Performance\n Protocol --> A11y\n Protocol --> Interaction\n Protocol --> Network\n Protocol --> WebMCP\n \n Navigation --> CDP\n Performance --> CDP\n A11y --> CDP\n Interaction --> CDP\n Network --> CDP\n WebMCP --> CDP\n \n CDP --> Chrome\n```\n\n## 工具分类\n\n### 导航工具 (Navigation)\n\n| 工具名称 | 功能 | 页面作用域 |\n|---------|------|-----------|\n| `new_page` | 创建新页面 | 是 |\n| `navigate_page` | 导航到指定 URL | 是 |\n| `select_page` | 选择目标页面作为上下文 | 是 |\n| `close_page` | 关闭指定页面 | 是 |\n| `list_pages` | 列出所有打开的页面 | 否 |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md]()\n\n### 性能工具 (Performance)\n\n| 工具名称 | 功能 |\n|---------|------|\n| `performance_start_trace` | 开始性能追踪录制 |\n| `performance_stop_trace` | 停止性能追踪录制 |\n| `take_memory_snapshot` | 捕获内存堆快照 |\n| `performance_analyze_insight` | 获取性能洞察详情 |\n\n资料来源：[skills/debug-optimize-lcp/SKILL.md]()\n\n### 无障碍调试工具 (Accessibility)\n\n| 工具名称 | 功能 |\n|---------|------|\n| `take_snapshot` | 获取页面快照和可访问性树 |\n| `lighthouse_audit` | 运行 Lighthouse 无障碍审计 |\n| `evaluate_script` | 执行 JavaScript 脚本 |\n\n资料来源：[skills/a11y-debugging/SKILL.md]()\n\n### 元素交互工具 (Interaction)\n\n| 工具名称 | 功能 |\n|---------|------|\n| `click` | 点击元素 |\n| `fill` / `fill_form` | 填充表单 |\n| `type_text` | 键盘输入文本 |\n| `press_key` | 按下按键 |\n| `upload_file` | 上传文件 |\n| `take_screenshot` | 截图 |\n\n资料来源：[skills/chrome-devtools/SKILL.md]()\n\n### 网络工具 (Network)\n\n| 工具名称 | 功能 |\n|---------|------|\n| `network_start_monitoring` | 开始网络监控 |\n| `network_stop_monitoring` | 停止网络监控 |\n| `get_network_requests` | 获取网络请求列表 |\n\n### WebMCP 工具\n\nWebMCP 允许与网页暴露的工具进行交互：\n\n| 工具名称 | 功能 |\n|---------|------|\n| `list_webmcp_tools` | 列出页面暴露的所有 WebMCP 工具 |\n| `execute_webmcp_tool` | 执行指定的 WebMCP 工具 |\n\n资料来源：[src/tools/webmcp.ts]()\n\n### 模拟工具 (Emulation)\n\n| 工具名称 | 功能 |\n|---------|------|\n| `emulate` | 模拟网络条件、CPU 节流、地理位置、配色方案、视口大小 |\n| `resize_page` | 调整页面窗口大小 |\n| `emulate_user_agent` | 模拟用户代理 |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md]()\n\n## 核心概念\n\n### 页面作用域 (Page Scoped)\n\n工具分为两类：\n\n1. **页面作用域工具**：需要先选择目标页面才能使用\n2. **全局工具**：可随时调用，不需要选择页面\n\n```typescript\nexport function definePageTool(\n definition: PageToolDefinition,\n): DefinedPageTool;\n```\n\n资料来源：[src/tools/ToolDefinition.ts:1-100]()\n\n### 浏览器生命周期\n\n浏览器会在第一次工具调用时自动启动，使用持久化的 Chrome 配置文件。要启用扩展支持，需要在 MCP 服务器配置中添加 `--categoryExtensions` 参数。资料来源：[skills/chrome-devtools/SKILL.md]()\n\n### 元素唯一标识 (UID)\n\n每个页面元素都有唯一的 `uid` 标识符，用于交互操作。获取 UID 的方式是使用 `take_snapshot` 工具获取页面结构。资料来源：[skills/chrome-devtools/SKILL.md]()\n\n## 项目结构\n\n```\nchrome-devtools-mcp/\n├── src/\n│ ├── index.ts # 入口文件\n│ ├── tools/ # 工具定义\n│ │ ├── ToolDefinition.ts # 基础工具定义\n│ │ ├── webmcp.ts # WebMCP 工具\n│ │ └── ...\n│ ├── PageCollector.ts # 页面收集器\n│ └── ...\n├── skills/ # 技能文档\n│ ├── chrome-devtools/ # 核心 DevTools 技能\n│ ├── chrome-devtools-cli/ # CLI 技能\n│ ├── a11y-debugging/ # 无障碍调试技能\n│ └── debug-optimize-lcp/ # LCP 优化技能\n├── scripts/ # 脚本\n│ └── generate-docs.ts # 文档生成\n└── package.json\n```\n\n## 快速开始\n\n### 安装\n\n```bash\nnpm i chrome-devtools-mcp@latest -g\nchrome-devtools status # 验证安装\n```\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md]()\n\n### 常用命令\n\n| 命令 | 说明 |\n|------|------|\n| `npm run build` | 编译 TypeScript 并测试构建 |\n| `npm run test` | 运行所有测试 |\n| `npm run test ` | 运行单个测试文件 |\n| `npm run format` | 修复格式和获取 linting 错误 |\n| `npm run gen` | 生成文档 |\n\n资料来源：[AGENTS.md]()\n\n### 基本工作流程\n\n```mermaid\ngraph LR\n A[导航页面] --> B[等待内容加载]\n B --> C[获取快照]\n C --> D[获取元素 UID]\n D --> E[执行交互操作]\n```\n\n## 开发规范\n\n### TypeScript 规范\n\n项目采用严格的 TypeScript 规范：\n\n| 规则 | 说明 |\n|------|------|\n| 禁止使用 `any` 类型 | 必须使用具体类型 |\n| 禁止使用 `as` 类型转换 | 使用类型守卫或泛型 |\n| 禁止使用 `!` 断言 | 使用显式检查 |\n| 禁止使用 `// @ts-ignore` | 必须修复类型问题 |\n| 优先使用 `for..of` | 避免使用 `forEach` |\n\n资料来源：[AGENTS.md]()\n\n### 工具定义模式\n\n```typescript\nexport function definePageTool(\n definition: PageToolDefinition,\n): DefinedPageTool {\n return {\n ...definition,\n pageScoped: true,\n } as DefinedPageTool;\n}\n```\n\n资料来源：[src/tools/ToolDefinition.ts]()\n\n## 技能系统\n\n项目包含多个专业技能模块：\n\n| 技能名称 | 用途 | 使用场景 |\n|---------|------|---------|\n| `chrome-devtools` | 核心浏览器操作 | 调试网页、自动化交互、性能分析 |\n| `chrome-devtools-cli` | 命令行操作 | 页面导航、网络模拟、元素操作 |\n| `a11y-debugging` | 无障碍调试 | 检测 ARIA 标签、焦点管理、键盘导航 |\n| `debug-optimize-lcp` | LCP 优化 | 优化最大内容绘制性能 |\n\n## 扩展机制\n\n### MCP 服务器扩展\n\n可以通过 CLI 参数扩展 MCP 服务器功能：\n\n```bash\nnpx chrome-devtools-mcp@latest --categoryExtensions\n```\n\n### WebMCP 扩展\n\n网页可以暴露自定义工具供 MCP 调用，实现双向通信。资料来源：[src/tools/webmcp.ts]()\n\n## 常见用例\n\n### 自动化测试场景\n\n```typescript\n// 场景：导航 -> 截图 -> 检查元素\nconst calls = [\n { name: 'navigate_page', url: 'https://example.com' },\n { name: 'take_screenshot' },\n { name: 'take_snapshot' }\n];\n```\n\n资料来源：[scripts/eval_scenarios/snapshot_test.ts]()\n\n### 性能分析场景\n\n```typescript\n// 场景：导航 -> 开始性能追踪\nconst calls = [\n { name: 'navigate_page', url: 'https://developers.chrome.com' },\n { name: 'performance_start_trace' }\n];\n```\n\n资料来源：[scripts/eval_scenarios/performance_test.ts]()\n\n### LCP 优化场景\n\nLCP (最大内容绘制) 优化包括以下关键策略：\n\n1. **消除资源加载延迟**：使用预加载、避免懒加载、设置 fetchpriority\n2. **消除元素渲染延迟**：内联关键 CSS、拆分长任务、减少渲染阻塞\n3. **减少资源加载时长**：使用现代图片格式、CDN 加速\n4. **降低 TTFB**：减少重定向、优化服务器响应、使用边缘缓存\n\n资料来源：[skills/debug-optimize-lcp/SKILL.md]()\n\n## 页面管理\n\n### PageCollector 机制\n\n```mermaid\ngraph TB\n subgraph \"PageCollector\"\n Storage[(WeakMap<Page, Array<NavigationData>>)]\n end\n \n subgraph \"事件监听\"\n Created[targetcreated]\n Destroyed[targetdestroyed]\n end\n \n Created -->|新页面| Add[addPage]\n Destroyed -->|页面关闭| Remove[removePage]\n \n Add --> Storage\n Remove --> Storage\n```\n\n`PageCollector` 使用 `WeakMap` 存储每个页面的导航历史和资源数据，较新的导航记录排在前面。资料来源：[src/PageCollector.ts]()\n\n## 配置与扩展\n\n### CLI 参数\n\n| 参数 | 说明 |\n|------|------|\n| `--help` | 显示帮助信息 |\n| `--categoryExtensions` | 启用扩展支持 |\n| `--port` | 指定端口号 |\n\n### 工具注解\n\n工具可以通过注解系统标记元信息：\n\n```typescript\nannotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: true,\n conditions: ['networkIdle']\n}\n```\n\n资料来源：[scripts/generate-docs.ts]()\n\n## 总结\n\nchrome-devtools-mcp 项目提供了一套完整的 Chrome DevTools 自动化解决方案，通过 MCP 协议实现了与 AI 模型的深度集成。项目具有以下特点：\n\n- **模块化设计**：工具按功能分类，易于扩展和维护\n- **严格类型安全**：TypeScript 规范确保代码质量\n- **丰富的调试能力**：支持性能分析、无障碍调试、LCP 优化等专业领域\n- **灵活的工作流程**：支持页面管理、元素交互、网络模拟等多种操作\n- **双向扩展机制**：既支持 MCP 协议扩展，也支持 WebMCP 网页扩展\n\n---\n\n\n\n## 快速开始指南\n\n### 相关页面\n\n相关主题：[MCP客户端集成](#mcp-client-integration), [CLI与配置](#cli-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/README.md)\n- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n- [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n- [skills/chrome-devtools-cli/references/installation.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/references/installation.md)\n \n\n# 快速开始指南\n\n## 概述\n\nchrome-devtools-mcp 是一个 Chrome DevTools MCP（Model Context Protocol）服务器和命令行工具，提供对浏览器自动化、页面调试、性能分析和网络监控的全面控制。该项目允许开发者通过 MCP 协议与 Chrome DevTools Protocol 进行交互，实现高效的浏览器自动化和调试工作流。\n\n本指南将帮助用户快速上手该工具，涵盖从安装配置到基本操作的全流程。\n\n## 系统架构\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[用户/Agent] --> B[MCP 客户端]\n B --> C[chrome-devtools-mcp 服务器]\n C --> D[Chrome DevTools Protocol]\n D --> E[浏览器实例]\n F[chrome-devtools CLI] --> C\n```\n\n### 核心模块\n\n| 模块 | 路径 | 功能描述 |\n|------|------|----------|\n| MCP 服务器 | `src/bin/chrome-devtools-mcp.ts` | 核心服务进程，处理 MCP 协议通信 |\n| 工具定义 | `src/tools/` | 各类浏览器操作工具的实现 |\n| 响应处理 | `src/McpResponse.ts` | MCP 响应格式化与数据处理 |\n\n资料来源：[AGENTS.md:1-5]()\n\n## 环境要求\n\n### 必要条件\n\n- **Node.js**: 需要 Node.js 运行时环境\n- **npm**: 用于包管理和脚本执行\n- **Chrome 浏览器**: 支持本地安装的 Chrome 或 Chromium\n\n### 安装步骤\n\n#### 全局安装\n\n```bash\nnpm i chrome-devtools-mcp@latest -g\n```\n\n安装完成后，`chrome-devtools` 命令将全局可用。\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:3-7]()\n\n#### 验证安装\n\n```bash\nchrome-devtools status\n```\n\n该命令用于检查安装是否成功。\n\n## 基本命令\n\n### 启动 MCP 服务器\n\n```bash\nnpx chrome-devtools-mcp@latest [选项]\n```\n\n### 查看帮助信息\n\n```bash\nchrome-devtools --help\n```\n\n## 工作流程模式\n\n### 标准操作流程\n\n```mermaid\ngraph LR\n A[导航页面] --> B[等待加载]\n B --> C[获取快照]\n C --> D[元素交互]\n D --> E{是否完成}\n E -->|否| B\n E -->|是| F[结束]\n```\n\n### 页面交互前准备\n\n1. **导航**: 使用 `navigate_page` 或 `new_page` 访问目标页面\n2. **等待**: 使用 `wait_for` 确保内容加载完成\n3. **快照**: 使用 `take_snapshot` 获取页面结构\n4. **交互**: 使用快照中的元素 `uid` 进行操作\n\n资料来源：[skills/chrome-devtools/SKILL.md:14-24]()\n\n## 常用工具\n\n### 页面管理\n\n| 工具 | 功能 | 参数 |\n|------|------|------|\n| `new_page` | 创建新页面 | `url`, `--background`, `--timeout`, `--isolatedContext` |\n| `navigate_page` | 导航到 URL | `url`, `--type`, `--timeout`, `--initScript` |\n| `list_pages` | 列出所有页面 | 无 |\n| `select_page` | 选择目标页面 | `pageId`, `--bringToFront` |\n| `close_page` | 关闭页面 | `pageId` |\n\n### 元素交互\n\n| 工具 | 功能 | 常用参数 |\n|------|------|----------|\n| `click` | 点击元素 | `uid`, `--includeSnapshot` |\n| `fill` | 填充输入框 | `uid`, `text`, `--submitKey` |\n| `hover` | 悬停元素 | `uid` |\n| `take_snapshot` | 获取页面快照 | `--filePath`, `--includeSnapshot` |\n| `take_screenshot` | 截图 | `--filePath` |\n\n### 键盘操作\n\n```bash\nchrome-devtools press_key \"Enter\" # 按下指定按键\nchrome-devtools type_text \"hello\" # 输入文本\nchrome-devtools type_text \"hello\" --submitKey \"Enter\" # 输入并提交\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:1-35]()\n\n### 文件上传\n\n```bash\nchrome-devtools upload_file \"element-id\" \"file.txt\"\nchrome-devtools upload_file \"element-id\" \"file.txt\" --includeSnapshot true\n```\n\n## 性能分析\n\n### 性能追踪\n\n```mermaid\ngraph TD\n A[开始追踪] --> B[performance_start_trace]\n B --> C[执行业务操作]\n C --> D[停止追踪]\n D --> E[performance_stop_trace]\n E --> F[分析结果]\n F --> G[LCPBreakdown]\n F --> H[其他指标]\n```\n\n### 性能工具\n\n| 工具 | 功能 |\n|------|------|\n| `performance_start_trace` | 开始性能追踪 |\n| `performance_stop_trace` | 停止追踪并保存 |\n| `performance_analyze_insight` | 分析具体性能指标 |\n| `take_memory_snapshot` | 捕获内存堆快照 |\n\n```bash\n# 基础追踪\nchrome-devtools performance_start_trace true false\n\n# 带文件保存的追踪\nchrome-devtools performance_start_trace true true --filePath trace.gz\n\n# 停止并保存\nchrome-devtools performance_stop_trace --filePath \"result.json\"\n```\n\n## 网络监控\n\n### 网络请求检查\n\n```bash\nchrome-devtools network_requests # 查看网络请求列表\n```\n\n网络请求工具可配置：\n- `include`: 是否包含请求详情\n- `pagination`: 分页配置（`pageIdx`, `pageSize`）\n\n资料来源：[src/McpResponse.ts:50-75]()\n\n## 模拟与测试\n\n### 网络模拟\n\n```bash\nchrome-devtools emulate --networkConditions \"Offline\"\nchrome-devtools emulate --cpuThrottlingRate 4\n```\n\n### 设备模拟\n\n| 参数 | 功能 | 示例值 |\n|------|------|--------|\n| `--colorScheme` | 颜色方案 | `dark`, `light` |\n| `--viewport` | 视口尺寸 | `1920x1080` |\n| `--userAgent` | 用户代理字符串 | 自定义 UA |\n| `--geolocation` | 地理位置 | `0x0` |\n\n```bash\n# 模拟暗黑模式和全高清视口\nchrome-devtools emulate --colorScheme \"dark\" --viewport \"1920x1080\"\n\n# 重置页面尺寸\nchrome-devtools resize_page 1920 1080\n```\n\n## 开发与测试\n\n### 构建项目\n\n```bash\nnpm run build\n```\n\n该命令执行 TypeScript 编译并测试构建结果。\n\n### 运行测试\n\n```bash\nnpm run test # 运行所有测试\nnpm run test path-to-test.ts # 运行单个测试文件\n```\n\n### 代码格式化\n\n```bash\nnpm run format\n```\n\n该命令自动修复格式化问题并显示 linting 错误。\n\n## TypeScript 开发规范\n\n项目制定了严格的 TypeScript 开发规范：\n\n| 规范 | 说明 |\n|------|------|\n| 禁用 `any` 类型 | 必须使用具体类型 |\n| 禁用 `as` 类型转换 | 使用类型守卫或泛型 |\n| 禁用 `!` 断言 | 使用显式类型检查 |\n| 禁用 `// @ts-ignore` | 必须修复类型问题 |\n| 优先使用 `for..of` | 避免使用 `forEach` |\n\n资料来源：[AGENTS.md:15-25]()\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 命令未识别 | 确保全局 npm `bin` 目录在 PATH 中 |\n| 权限错误 | 避免使用 `sudo`，使用 nvm 管理 Node.js |\n| 旧版本运行 | 运行 `chrome-devtools stop && npm uninstall -g chrome-devtools-mcp` |\n\n### 重启终端\n\n安装后可能需要重启终端或 source 配置文件（`.bashrc`、`.zshrc`）以使命令生效。\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:10-18]()\n\n## 扩展功能\n\n### 扩展支持\n\n如需使用浏览器扩展功能，在 MCP 服务器配置中添加 `--categoryExtensions` 参数：\n\n```bash\nnpx chrome-devtools-mcp@latest --categoryExtensions\n```\n\n### WebMCP 工具\n\n页面可暴露自定义 WebMCP 工具：\n\n| 工具 | 功能 |\n|------|------|\n| `list_webmcp_tools` | 列出页面暴露的所有 WebMCP 工具 |\n| `execute_webmcp_tool` | 执行指定的 WebMCP 工具 |\n\n```bash\nchrome-devtools list_webmcp_tools\nchrome-devtools execute_webmcp_tool \"toolName\" --input '{\"key\": \"value\"}'\n```\n\n资料来源：[src/tools/webmcp.ts:10-40]()\n\n## 下一步\n\n- 阅读完整的[工具参考文档](./tool-reference.md)\n- 查看 [LCP 优化指南](./debug-optimize-lcp/index.md)\n- 学习[无障碍调试](./a11y-debugging/index.md)技巧\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[守护进程系统](#daemon-system), [工具参考](#tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/index.ts)\n- [src/McpPage.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpPage.ts)\n- [src/McpContext.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpContext.ts)\n- [src/ToolHandler.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/ToolHandler.ts)\n- [src/browser.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts)\n \n\n# 系统架构\n\n## 1. 概述\n\nchrome-devtools-mcp 是一个基于 Model Context Protocol (MCP) 的服务器实现，通过 Chrome DevTools Protocol 与 Chrome 浏览器进行交互。该项目为 AI 助手提供了一套完整的浏览器自动化工具集，涵盖页面导航、快照采集、性能分析、网络监控、无障碍审计等功能。\n\n核心设计理念是将复杂的 CDP 操作封装为声明式的工具定义，并支持按需启用或禁用特定工具类别。\n\n资料来源：[skills/chrome-devtools/SKILL.md]()\n\n## 2. 架构层次\n\n项目采用分层架构，从底层到顶层依次为：\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B[MCP 服务器层
src/index.ts]\n B --> C[工具路由层
src/ToolHandler.ts]\n C --> D[页面管理层
src/McpPage.ts
src/McpContext.ts]\n D --> E[浏览器抽象层
src/browser.ts]\n E --> F[Puppeteer]\n F --> G[Chrome DevTools Protocol]\n G --> H[Chrome 浏览器]\n \n I[PageCollector] -.->|事件收集| D\n I -.->|依赖| E\n```\n\n### 2.1 MCP 服务器层 (src/index.ts)\n\n作为整个系统的入口点，负责初始化 MCP 服务器并注册所有可用工具。该层处理 MCP 协议的请求/响应生命周期。\n\n### 2.2 工具路由层 (src/ToolHandler.ts)\n\n负责将 MCP 请求路由到对应的工具处理器，维护工具注册表并处理工具执行的生命周期。\n\n### 2.3 页面管理层 (src/McpPage.ts, src/McpContext.ts)\n\n管理多页面上下文，包括页面创建、销毁、切换，以及页面作用域内工具的隔离执行。\n\n### 2.4 浏览器抽象层 (src/browser.ts)\n\n封装 Puppeteer API，提供浏览器启动、页面管理、连接复用等底层能力。\n\n## 3. 核心组件\n\n### 3.1 工具定义系统\n\n工具通过 `defineTool` 和 `definePageTool` 工厂函数声明式定义，支持条件化生成和参数化扩展：\n\n```typescript\nexport function defineTool<\n Schema extends zod.ZodRawShape,\n Args extends ParsedArguments = ParsedArguments,\n>(\n definition:\n | ToolDefinition\n | ((args?: Args) => ToolDefinition),\n) {\n if (typeof definition === 'function') {\n const factory = definition;\n return (args: Args) => {\n return factory(args);\n };\n }\n return definition;\n}\n```\n\n资料来源：[src/tools/ToolDefinition.ts:1-20]()\n\n| 组件 | 作用 |\n|------|------|\n| `ToolDefinition` | 工具的基础定义接口 |\n| `defineTool` | 创建全局工具的工厂函数 |\n| `definePageTool` | 创建页面作用域工具的工厂函数 |\n| `pageIdSchema` | 提供可选的页面 ID 参数 |\n| `timeoutSchema` | 提供可选的超时配置 |\n\n### 3.2 工具定义结构\n\n每个工具定义包含以下关键字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `name` | string | 工具唯一标识符 |\n| `description` | string | 工具功能描述 |\n| `schema` | ZodSchema | 输入参数校验 schema |\n| `handler` | Function | 实际执行的处理函数 |\n| `pageScoped` | boolean | 是否为页面作用域工具 |\n| `blockedByDialog` | boolean | 是否被对话框阻塞 |\n| `annotations` | ToolAnnotations | 工具元数据（分类、只读提示等）|\n\n```typescript\ninterface ToolDefinition<\n Schema extends zod.ZodRawShape = zod.ZodRawShape,\n> extends BaseToolDefinition {\n handler: (\n request: Request,\n response: Response,\n context: Context,\n ) => Promise;\n}\n```\n\n资料来源：[src/tools/ToolDefinition.ts:1-20]()\n\n### 3.3 页面上下文管理\n\n页面上下文通过 `McpContext` 管理，支持多页面并发操作：\n\n```mermaid\ngraph TD\n A[McpContext] -->|管理| B[McpPage 1]\n A -->|管理| C[McpPage 2]\n A -->|管理| D[McpPage N]\n B -->|操作| E[CDP Session 1]\n C -->|操作| F[CDP Session 2]\n D -->|操作| G[CDP Session N]\n```\n\n`McpPage` 封装了单个页面的 CDP 操作，提供统一的工具调用接口。\n\n资料来源：[src/McpPage.ts]()\n\n### 3.4 浏览器生命周期\n\n```mermaid\ngraph LR\n A[启动 Chrome] --> B[建立 CDP 连接]\n B --> C[初始化页面]\n C --> D[注册事件监听]\n D --> E[PageCollector 收集数据]\n E --> F[等待工具调用]\n F --> G[执行工具]\n G --> H[返回结果]\n H -->|继续| F\n```\n\n资料来源：[src/browser.ts]()\n\n## 4. 工具分类体系\n\n工具按功能分类，通过 `ToolCategory` 枚举定义：\n\n| 分类 | 说明 | 示例工具 |\n|------|------|----------|\n| `NAVIGATION` | 页面导航与控制 | navigate_page, new_page, close_page |\n| `INSPECTION` | 页面状态检查 | take_snapshot, take_screenshot |\n| `INTERACTION` | 用户交互模拟 | click, fill_form, press_key |\n| `PERFORMANCE` | 性能分析与追踪 | performance_start_trace, take_memory_snapshot |\n| `NETWORK` | 网络请求监控 | network_intercept_request |\n| `EMULATION` | 环境模拟 | emulate, resize_page |\n| `ACCESSIBILITY` | 无障碍审计 | run_lighthouse |\n| `WEBMCP` | 页面暴露的工具 | list_webmcp_tools, execute_webmcp_tool |\n\n资料来源：[src/tools/categories.ts]()、[src/tools/webmcp.ts]()\n\n## 5. 页面收集器 (PageCollector)\n\n`PageCollector` 是一个通用的事件收集器，用于监听浏览器目标事件：\n\n```typescript\nexport class PageCollector {\n #browser: Browser;\n #listenersInitializer: (\n collector: (item: T) => void,\n ) => ListenerMap;\n protected storage = new WeakMap>>>();\n \n async init(pages: Page[]) { /* ... */ }\n dispose() { /* ... */ }\n}\n```\n\n资料来源：[src/PageCollector.ts:1-30]()\n\n### 5.1 事件流\n\n```mermaid\ngraph TD\n A[targetcreated 事件] --> B{获取 Page}\n B -->|成功| C[addPage]\n B -->|失败| D[记录日志]\n C --> E[targetdestroyed 事件]\n E --> F[removePage]\n \n G[页面事件] --> H[触发监听器]\n H --> I[收集数据到 storage]\n I --> J[WeakMap 存储]\n```\n\n## 6. WebMCP 工具机制\n\nWebMCP 允许页面主动暴露自定义工具，实现双向通信：\n\n```typescript\nexport const listWebMcpTools = definePageTool({\n name: 'list_webmcp_tools',\n description: `Lists all WebMCP tools the page exposes.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: true,\n },\n schema: {},\n blockedByDialog: false,\n handler: async (_request, response, _context) => {\n response.setListWebMcpTools();\n },\n});\n\nexport const executeWebMcpTool = definePageTool({\n name: 'execute_webmcp_tool',\n description: `Executes a WebMCP tool exposed by the page.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: false,\n },\n schema: {\n toolName: zod.string().describe('The name of the WebMCP tool to execute'),\n input: zod.string().optional().describe('The JSON-stringified parameters'),\n },\n blockedByDialog: false,\n handler: async (request, response) => {\n const toolName = request.params.toolName;\n let input: Record = {};\n if (request.params.input) {\n const parsed = JSON.parse(request.params.input);\n // ...\n }\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts:1-50]()\n\n## 7. 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as MCP 服务器\n participant Handler as ToolHandler\n participant Context as McpContext\n participant Page as McpPage\n participant CDP as Chrome CDP\n\n Client->>Server: 工具调用请求\n Server->>Handler: 路由到对应工具\n Handler->>Context: 获取当前页面上下文\n Context->>Page: 执行页面操作\n Page->>CDP: 发送 CDP 命令\n CDP-->>Page: 返回执行结果\n Page-->>Context: 返回结果\n Context-->>Handler: 格式化响应\n Handler-->>Server: 返回工具响应\n Server-->>Client: MCP 响应\n```\n\n## 8. 工具依赖关系\n\n部分工具需要特定的前置条件，例如对话框阻塞：\n\n| 工具类型 | blockedByDialog | 说明 |\n|----------|-----------------|------|\n| 导航工具 | false | 通常允许在对话框存在时执行 |\n| 检查工具 | false | 快照和截图不受对话框影响 |\n| 交互工具 | true | 点击、表单填写需等待对话框关闭 |\n\n```typescript\nexport const CLOSE_PAGE_ERROR =\n 'The last open page cannot be closed. It is fine to keep it open.';\n```\n\n资料来源：[src/tools/ToolDefinition.ts:30-32]()\n\n## 9. 扩展性设计\n\n### 9.1 新增工具类别\n\n在 `src/tools/categories.ts` 中扩展 `ToolCategory` 枚举，然后在对应的文件中使用 `defineTool` 或 `definePageTool` 注册工具。\n\n### 9.2 条件化工具生成\n\n工具支持函数式定义，可根据参数动态生成：\n\n```typescript\nexport function definePageTool<\n Schema extends zod.ZodRawShape,\n Args extends ParsedArguments = ParsedArguments,\n>(\n definition: (args?: Args) => PageToolDefinition,\n): (args?: Args) => DefinedPageTool {\n return (args?: Args): DefinedPageTool => {\n const tool = definition(args);\n return {\n ...tool,\n pageScoped: true,\n };\n };\n}\n```\n\n资料来源：[src/tools/ToolDefinition.ts:40-60]()\n\n## 10. 总结\n\nchrome-devtools-mcp 的架构设计体现了以下原则：\n\n1. **分层解耦**：通过明确的层次划分，实现关注点分离\n2. **声明式定义**：工具通过结构化的 schema 声明，简化了注册流程\n3. **页面隔离**：每个页面维护独立的上下文，保证并发安全\n4. **事件驱动**：通过 PageCollector 实现灵活的事件收集机制\n5. **双向通信**：WebMCP 机制支持页面主动暴露能力，拓展了应用边界\n\n---\n\n\n\n## 守护进程系统\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/daemon/daemon.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/daemon/daemon.ts)\n- [src/daemon/client.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/daemon/client.ts)\n- [src/daemon/types.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/daemon/types.ts)\n- [src/daemon/utils.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/daemon/utils.ts)\n \n\n# 守护进程系统\n\n## 概述\n\n守护进程系统（Daemon System）是 chrome-devtools-mcp 项目中负责管理和维护 Chrome DevTools 协议通信后端服务的核心模块。该系统确保 MCP 服务器与浏览器实例之间的长期稳定连接，并提供进程生命周期管理、状态监控和资源清理等功能。\n\n在 chrome-devtools-mcp 架构中，守护进程扮演着后台服务的角色，使得客户端能够通过 MCP 协议与浏览器进行交互，而无需关心底层连接管理的复杂性。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A[MCP 客户端]\n B[CLI 工具
chrome-devtools]\n end\n \n subgraph 守护进程层\n C[Daemon Manager]\n D[Chrome Browser
实例]\n end\n \n subgraph 协议层\n E[CDP 协议
Chrome DevTools Protocol]\n end\n \n A --> C\n B --> C\n C <--> E\n E <--> D\n \n style C fill:#e1f5fe\n style D fill:#fff3e0\n```\n\n### 核心组件\n\n| 组件名称 | 文件位置 | 职责描述 |\n|---------|---------|---------|\n| Daemon Manager | `daemon.ts` | 进程生命周期管理、启动/停止控制 |\n| Daemon Client | `client.ts` | 客户端通信接口、命令发送与接收 |\n| 类型定义 | `types.ts` | 共享类型、接口、枚举定义 |\n| 工具函数 | `utils.ts` | 通用工具函数、日志、错误处理 |\n\n## 守护进程管理器\n\n### 进程启动流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Daemon as Daemon Manager\n participant Chrome as Chrome 实例\n participant CDP as CDP Protocol\n \n Client->>Daemon: 启动请求\n Daemon->>Chrome: 启动 Chrome 进程\n Chrome-->>Daemon: 进程已启动\n Daemon->>CDP: 建立 WebSocket 连接\n CDP-->>Daemon: 连接就绪\n Daemon-->>Client: 启动成功/状态就绪\n```\n\n### 核心功能\n\n#### 1. 进程生命周期管理\n\n守护进程管理器负责 Chrome 浏览器实例的完整生命周期：\n\n- **启动**：初始化 Chrome 进程并建立调试连接\n- **运行**：维护活跃的 CDP 会话\n- **停止**：优雅关闭进程并清理资源\n- **重启**：在故障时自动恢复服务\n\n#### 2. 配置管理\n\n守护进程支持多种启动配置参数：\n\n| 参数名称 | 类型 | 默认值 | 说明 |\n|---------|------|-------|------|\n| port | number | 9222 | Chrome 调试端口 |\n| userDataDir | string | - | 用户数据目录路径 |\n| headless | boolean | true | 是否以无头模式运行 |\n| startupTimeout | number | 30000 | 启动超时时间(毫秒) |\n\n## 客户端通信接口\n\n### 连接建立\n\n```mermaid\ngraph LR\n A[CLI 命令] --> B[Client.connect]\n B --> C{连接状态}\n C -->|成功| D[返回连接句柄]\n C -->|失败| E[错误处理]\n D --> F[发送 CDP 命令]\n F --> G[接收响应]\n```\n\n### API 接口\n\n守护进程客户端提供以下核心方法：\n\n```typescript\ninterface DaemonClient {\n // 建立连接\n connect(options: ConnectOptions): Promise;\n \n // 断开连接\n disconnect(): Promise;\n \n // 发送命令\n sendCommand(method: string, params?: object): Promise;\n \n // 获取状态\n getStatus(): DaemonStatus;\n}\n```\n\n## 类型系统\n\n### 核心类型定义\n\n```typescript\n// 守护进程状态枚举\nenum DaemonState {\n STOPPED = 'stopped',\n STARTING = 'starting',\n RUNNING = 'running',\n STOPPING = 'stopping',\n ERROR = 'error'\n}\n\n// 连接配置\ninterface ConnectOptions {\n port?: number;\n autoReconnect?: boolean;\n timeout?: number;\n}\n\n// 守护进程状态\ninterface DaemonStatus {\n state: DaemonState;\n uptime: number;\n browserVersion?: string;\n error?: string;\n}\n```\n\n### 类型安全\n\n守护进程系统采用 TypeScript 严格类型检查策略：\n\n- 禁止使用 `any` 类型\n- 禁止使用类型断言 `as` 关键字\n- 禁止使用非空断言 `!` 操作符\n- 优先使用 `for...of` 循环替代 `forEach`\n\n## 工具模块\n\n### 错误处理\n\n工具模块提供统一的错误处理机制：\n\n```typescript\n// 自定义错误类型\nclass DaemonError extends Error {\n constructor(\n message: string,\n public code: DaemonErrorCode,\n public details?: object\n ) {\n super(message);\n }\n}\n```\n\n### 日志记录\n\n```typescript\ninterface LogOptions {\n level: 'debug' | 'info' | 'warn' | 'error';\n timestamp?: boolean;\n prefix?: string;\n}\n```\n\n## 状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> STOPPED: 初始化\n STOPPED --> STARTING: 启动请求\n STARTING --> RUNNING: 连接成功\n STARTING --> ERROR: 连接失败\n RUNNING --> STOPPING: 停止请求\n RUNNING --> ERROR: 连接断开\n STOPPING --> STOPPED: 进程已关闭\n ERROR --> STARTING: 重试\n ERROR --> STOPPED: 放弃\n STOPPED --> [*]: 销毁\n```\n\n## 使用场景\n\n### 1. MCP 服务器集成\n\n守护进程系统被 MCP 服务器直接使用：\n\n```typescript\nimport { DaemonManager } from './daemon/daemon';\n\nconst daemon = new DaemonManager({\n port: 9222,\n headless: true\n});\n\nawait daemon.start();\n```\n\n### 2. CLI 工具调用\n\n命令行工具通过守护进程客户端与服务交互：\n\n```bash\nchrome-devtools start\nchrome-devtools status\nchrome-devtools stop\n```\n\n### 3. 测试环境\n\n在测试场景中，守护进程提供隔离的浏览器环境：\n\n```typescript\nconst testDaemon = new DaemonManager({\n userDataDir: '/tmp/test-profile',\n headless: true\n});\n```\n\n## 配置与调试\n\n### 环境变量\n\n| 变量名称 | 说明 |\n|---------|------|\n| `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` | 禁用使用统计 |\n| `DEBUG` | 调试日志类别控制 |\n| `LOG_FILE` | 日志输出文件路径 |\n\n### 日志级别\n\n```bash\n# 启用所有调试日志\nDEBUG=* chrome-devtools start\n\n# 输出到文件\nnpx chrome-devtools-mcp@latest --log-file=/tmp/daemon.log\n```\n\n## 最佳实践\n\n1. **启动顺序**：先启动守护进程，再建立客户端连接\n2. **资源清理**：使用完毕及时调用 `stop()` 方法释放资源\n3. **超时处理**：设置合理的 `startupTimeout` 避免无限等待\n4. **错误恢复**：实现重连机制处理临时性网络故障\n5. **端口管理**：确保调试端口未被其他进程占用\n\n## 相关文档\n\n- [安装指南](../skills/chrome-devtools-cli/references/installation.md)\n- [故障排除](../skills/troubleshooting/SKILL.md)\n- [工具参考](../src/tools/ToolDefinition.ts)\n\n---\n\n\n\n## 工具参考\n\n### 相关页面\n\n相关主题：[输入自动化工具](#input-automation), [性能分析工具](#performance-tools), [内存调试工具](#memory-debugging)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/tools.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/tools.ts)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [src/tools/categories.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts)\n- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n- [src/McpResponse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)\n- [scripts/generate-docs.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)\n \n\n# 工具参考\n\n本页面详细描述 chrome-devtools-mcp 项目中的工具（Tool）系统架构、定义方式、分类体系以及运行时行为。\n\n## 概述\n\n工具系统是 chrome-devtools-mcp 的核心组件，它将 Chrome DevTools Protocol (CDP) 的能力封装为可通过 MCP (Model Context Protocol) 调用的接口。该系统支持两类工具：\n\n- **全局工具 (Tool)**：不依赖于特定页面的工具，如浏览器管理、网络控制等\n- **页面作用域工具 (PageTool)**：需要绑定到特定页面的工具，如元素交互、表单填充等\n\n资料来源：[src/tools/ToolDefinition.ts:1-50]()\n\n## 工具架构\n\n### 类型层级\n\n工具系统采用 TypeScript 类型安全的设计，通过泛型约束确保工具定义的正确性。\n\n```mermaid\ngraph TD\n A[BaseToolDefinition] --> B[ToolDefinition]\n A --> C[PageToolDefinition]\n B --> D[DefinedTool]\n C --> E[DefinedPageTool]\n```\n\n| 类型名称 | 作用域 | 描述 |\n|---------|--------|------|\n| `BaseToolDefinition` | 基础 | 所有工具定义的基类 |\n| `ToolDefinition` | 全局 | 不依赖页面的工具定义 |\n| `PageToolDefinition` | 页面 | 依赖页面上下文工具定义 |\n| `DefinedTool` | 全局 | 已解析的工具定义 |\n| `DefinedPageTool` | 页面 | 已解析的页面作用域工具定义 |\n\n资料来源：[src/tools/ToolDefinition.ts:50-80]()\n\n### 工具结构\n\n每个工具定义包含以下核心字段：\n\n| 字段 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `name` | `string` | 是 | 工具唯一标识名称 |\n| `description` | `string` | 是 | 工具功能描述，用于 AI 理解用途 |\n| `schema` | `zod.ZodRawShape` | 是 | 输入参数 schema 定义 |\n| `handler` | `Function` | 是 | 工具执行逻辑 |\n| `annotations` | `ToolAnnotations` | 否 | 工具元数据注解 |\n| `blockedByDialog` | `boolean` | 否 | 是否被对话框阻塞 |\n| `pageScoped` | `boolean` | 否 | 是否为页面作用域工具 |\n\n资料来源：[src/tools/ToolDefinition.ts:80-120]()\n\n## 工具定义函数\n\n### defineTool - 全局工具定义\n\n`defineTool` 用于定义不依赖特定页面的工具，如浏览器管理、性能分析等。\n\n```typescript\nexport function defineTool(\n definition: ToolDefinition,\n): DefinedTool;\n```\n\n**使用示例**：\n\n```typescript\nexport const myGlobalTool = defineTool({\n name: 'my_global_tool',\n description: 'A global tool that works without page context',\n schema: {\n param1: zod.string().describe('First parameter'),\n },\n annotations: {\n category: ToolCategory.BROWSER,\n readOnlyHint: true,\n },\n blockedByDialog: false,\n handler: async (request, response, context) => {\n // 工具执行逻辑\n },\n});\n```\n\n资料来源：[src/tools/ToolDefinition.ts:140-180]()\n\n### definePageTool - 页面作用域工具定义\n\n`definePageTool` 用于定义需要页面上下文的工具，handler 函数会自动接收 `page: ContextPage` 参数。\n\n```typescript\nexport function definePageTool(\n definition: PageToolDefinition,\n): DefinedPageTool;\n```\n\n**使用示例**：\n\n```typescript\nexport const clickTool = definePageTool({\n name: 'click',\n description: 'Clicks on an element identified by uid',\n schema: {\n uid: zod.string().describe('The uid of the element to click'),\n },\n annotations: {\n category: ToolCategory.INPUT,\n readOnlyHint: false,\n },\n blockedByDialog: true,\n handler: async (request, response, context) => {\n // request 包含 { page: ContextPage, params: { uid: string } }\n },\n});\n```\n\n资料来源：[src/tools/ToolDefinition.ts:180-220]()\n\n### 工厂模式支持\n\n两个定义函数都支持传入工厂函数，用于动态生成工具定义：\n\n```typescript\nexport function definePageTool<\n Schema extends zod.ZodRawShape,\n Args extends ParsedArguments = ParsedArguments,\n>(\n definition: (args?: Args) => PageToolDefinition,\n): (args?: Args) => DefinedPageTool;\n```\n\n这允许工具定义根据传入参数进行条件性配置。\n\n资料来源：[src/tools/ToolDefinition.ts:220-240]()\n\n## 工具分类体系\n\n### 分类枚举\n\n工具按功能域划分为多个分类，便于管理和文档生成：\n\n| 分类标识 | 显示名称 | 描述 |\n|---------|----------|------|\n| `NAVIGATION` | Navigation | 页面导航相关工具 |\n| `INPUT` | Input Automation | 用户输入和交互工具 |\n| `INSPECTION` | Inspection | 页面元素检查和快照工具 |\n| `EMULATION` | Emulation | 环境模拟工具 |\n| `PERFORMANCE` | Performance | 性能分析工具 |\n| `NETWORK` | Network | 网络请求相关工具 |\n| `BROWSER` | Browser | 浏览器管理工具 |\n| `EXTENSION` | Extensions | Chrome 扩展管理工具 |\n| `WEBMCP` | WebMCP | WebMCP 协议工具 |\n| `EXPERIMENTAL` | Experimental | 实验性功能工具 |\n\n资料来源：[src/tools/categories.ts]()\n\n### 分类标签映射\n\n文档生成系统使用标签映射将分类标识转换为可读名称：\n\n```typescript\nconst labels: Record = {\n [ToolCategory.NAVIGATION]: 'Navigation',\n [ToolCategory.INPUT]: 'Input Automation',\n [ToolCategory.INSPECTION]: 'Inspection',\n // ...\n};\n```\n\n资料来源：[scripts/generate-docs.ts:30-50]()\n\n## 工具注解系统\n\n### 注解结构\n\n`annotations` 字段提供工具的额外元数据：\n\n```typescript\ninterface ToolAnnotations {\n category: ToolCategory; // 工具所属分类\n readOnlyHint?: boolean; // 是否为只读操作\n conditions?: string[]; // 需要的实验性标志\n docsLink?: string; // 文档链接\n}\n```\n\n| 注解字段 | 类型 | 描述 |\n|---------|------|------|\n| `category` | `ToolCategory` | **必填** 工具分类 |\n| `readOnlyHint` | `boolean` | 提示是否为只读操作，帮助 AI 决策是否需要确认 |\n| `conditions` | `string[]` | 激活工具所需的实验性标志列表 |\n| `docsLink` | `string` | 相关文档链接 |\n\n资料来源：[src/tools/ToolDefinition.ts:40-48]()\n\n### 条件激活机制\n\n某些工具需要特定标志才能使用，条件在 `conditions` 数组中声明：\n\n```typescript\nconst experimentalTool = definePageTool({\n name: 'screencast_start',\n description: 'Starts a screencast recording',\n annotations: {\n category: ToolCategory.EXPERIMENTAL,\n conditions: ['experimentalScreencast'], // 需要 --experimentalScreencast=true\n },\n schema: {},\n blockedByDialog: false,\n handler: async (request, response, context) => {\n // 处理屏幕录制\n },\n});\n```\n\n资料来源：[scripts/generate-docs.ts:60-80]()\n\n## Schema 定义规范\n\n### Zod Schema 结构\n\n工具参数通过 Zod 进行类型安全的 schema 定义：\n\n```typescript\nschema: {\n paramName: zod.string().describe('Parameter description'),\n optionalParam: zod.number().optional().describe('Optional parameter'),\n enumParam: zod.enum(['option1', 'option2']).describe('Enum parameter'),\n}\n```\n\n### 常用 Schema 组件\n\n| Schema 类型 | 用途 | 示例 |\n|------------|------|------|\n| `zod.string()` | 字符串参数 | 用户名、URL |\n| `zod.number()` | 数字参数 | 坐标、超时值 |\n| `zod.boolean()` | 布尔参数 | 开关选项 |\n| `zod.enum()` | 枚举参数 | 类型选择 |\n| `zod.array()` | 数组参数 | 多个值 |\n| `zod.optional()` | 可选参数 | 标记为可选 |\n\n### 预定义 Schema\n\n系统提供常用 schema 组件：\n\n```typescript\nexport const pageIdSchema = {\n pageId: zod.number().optional().describe('Targets a specific page by ID.'),\n};\n\nexport const timeoutSchema = {\n timeout: zod\n .number()\n .int()\n .optional()\n .describe('Maximum wait time in milliseconds.'),\n};\n```\n\n资料来源：[src/tools/ToolDefinition.ts:55-70]()\n\n## 请求处理流程\n\n### Handler 函数签名\n\n**全局工具 Handler**：\n```typescript\nhandler: (\n request: Request & { page?: ContextPage },\n response: Response,\n context: Context,\n) => Promise\n```\n\n**页面作用域工具 Handler**：\n```typescript\nhandler: (\n request: Request & { page: ContextPage },\n response: Response,\n context: Context,\n) => Promise\n```\n\n### 请求生命周期\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Server as MCP Server\n participant Tool as Tool Handler\n participant CDP as Chrome DevTools\n \n Client->>Server: 工具调用请求\n Server->>Tool: 解析参数 + 验证 Schema\n alt 页面作用域工具\n Tool->>Tool: 验证页面上下文\n end\n Tool->>CDP: CDP 协议命令\n CDP-->>Tool: 执行结果\n Tool->>Server: 格式化响应\n Server-->>Client: MCP 响应\n```\n\n## MCP 响应集成\n\n### 响应格式化\n\n工具执行结果通过 `McpResponse` 类进行格式化，支持多种输出格式：\n\n```typescript\nresponse.setListWebMcpTools(); // 设置 WebMCP 工具列表\nresponse.setText(content: string); // 设置文本内容\nresponse.setScreenshot(filePath: string); // 设置截图路径\nresponse.setSnapshot(snapshot: string); // 设置快照内容\n```\n\n### 响应数据结构\n\n```typescript\ninterface ToolResponse {\n content: ContentBlock[]; // 内容块列表\n structuredContent?: { // 结构化内容\n webmcpTools?: WebMcpTool[]; // WebMCP 工具信息\n networkRequests?: NetworkRequest[];\n pagination?: PaginationData;\n };\n}\n```\n\n资料来源：[src/McpResponse.ts:1-50]()\n\n## 工具注册与发现\n\n### 工具列表生成\n\n文档生成脚本自动扫描所有工具定义并生成参考文档：\n\n```mermaid\ngraph LR\n A[工具源文件] --> B[generate-docs.ts]\n B --> C[工具分类]\n C --> D[Markdown 文档]\n D --> E[docs/tool-reference.md]\n B --> F[README TOC]\n```\n\n生成过程包括：\n1. 扫描所有 `src/tools/` 目录下的工具定义\n2. 按 `ToolCategory` 分组\n3. 生成参数表格和描述\n4. 输出到 `docs/tool-reference.md`\n\n资料来源：[scripts/generate-docs.ts:100-150]()\n\n### 工具列表输出格式\n\n```markdown\n## WebMCP tools\n\nname=\"list_webmcp_tools\", description=\"Lists all WebMCP tools...\", inputSchema={}\nname=\"execute_webmcp_tool\", description=\"Executes a WebMCP tool...\", inputSchema={\"toolName\": {...}, \"input\": {...}}\n```\n\n资料来源：[src/McpResponse.ts:60-80]()\n\n## WebMCP 特殊工具\n\n### list_webmcp_tools\n\n列出页面暴露的所有 WebMCP 工具：\n\n```typescript\nexport const listWebMcpTools = definePageTool({\n name: 'list_webmcp_tools',\n description: `Lists all WebMCP tools the page exposes.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: true,\n },\n schema: {},\n blockedByDialog: false,\n handler: async (_request, response, _context) => {\n response.setListWebMcpTools();\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts:15-30]()\n\n### execute_webmcp_tool\n\n执行页面暴露的 WebMCP 工具：\n\n```typescript\nexport const executeWebMcpTool = definePageTool({\n name: 'execute_webmcp_tool',\n description: `Executes a WebMCP tool exposed by the page.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: false,\n },\n schema: {\n toolName: zod.string().describe('The name of the WebMCP tool to execute'),\n input: zod.string().optional().describe('The JSON-stringified parameters'),\n },\n blockedByDialog: false,\n handler: async (request, response) => {\n // 解析输入并执行工具\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts:32-60]()\n\n## 类型安全约束\n\n项目对 TypeScript 使用有严格的类型安全要求：\n\n| 规则 | 说明 | 违规处理 |\n|------|------|----------|\n| 禁止 `any` | 不允许使用 any 类型 | 使用具体类型替代 |\n| 禁止 `as` | 不允许类型断言 | 使用类型守卫或验证 |\n| 禁止 `!` | 不允许非空断言 | 使用显式检查 |\n| 禁止 `@ts-ignore` | 不允许忽略类型检查 | 修复类型问题 |\n| 推荐 `for..of` | 替代 `forEach` | 提高可读性 |\n\n资料来源：[AGENTS.md:20-35]()\n\n## 总结\n\n工具系统是 chrome-devtools-mcp 实现浏览器自动化和调试能力的基础架构。通过：\n\n- **类型安全的工具定义**：利用 TypeScript 泛型和 Zod schema 确保编译期和运行期类型正确\n- **分层架构**：区分全局工具和页面作用域工具，适配不同的使用场景\n- **注解驱动**：通过 annotations 提供元数据，支持文档生成和 AI 决策\n- **统一处理流程**：标准化工具的注册、调用、响应流程\n\n开发者可以基于 `defineTool` 和 `definePageTool` 快速扩展新的工具能力，同时保持代码的一致性和可维护性。\n\n---\n\n\n\n## 输入自动化工具\n\n### 相关页面\n\n相关主题：[工具参考](#tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/input.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/input.ts)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n- [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n \n\n# 输入自动化工具\n\n## 概述\n\n输入自动化工具是 chrome-devtools-mcp 项目的核心功能模块之一，提供了通过 Chrome DevTools Protocol 对网页进行自动化交互的能力。该模块允许通过 MCP（Model Context Protocol）协议向浏览器发送命令，实现模拟用户输入、元素交互和文件上传等操作。\n\n这些工具位于 `src/tools/input.ts` 中，属于页面作用域工具（page-scoped tools），需要先选择一个活跃的页面上下文才能执行。工具集涵盖了从简单的按键操作到复杂的文本输入和文件上传等常见用户交互场景。\n\n## 架构设计\n\n### 工具定义模式\n\n输入自动化工具采用统一的工厂函数模式进行定义，使用 TypeScript 和 Zod 进行类型安全和参数校验。核心工具通过 `definePageTool` 函数注册，该函数来源于 `ToolDefinition.ts` 模块。资料来源：[src/tools/ToolDefinition.ts:43-68]()\n\n```mermaid\ngraph TD\n A[用户请求] --> B[参数校验层 Zod Schema]\n B --> C[Handler 处理函数]\n C --> D[Playwright Page API]\n D --> E[浏览器页面执行]\n E --> F[响应构建]\n F --> G[MCP 响应]\n```\n\n### 页面上下文依赖\n\n所有输入自动化工具均为页面作用域工具，需要通过 `select_page` 选择目标页面后才能执行。这种设计确保了操作的上下文隔离性和安全性。资料来源：[src/tools/ToolDefinition.ts:55-67]()\n\n## 工具分类\n\n输入自动化工具按功能可分为以下三类：\n\n| 类别 | 工具名称 | 功能描述 |\n|------|----------|----------|\n| 键盘操作 | `press_key` | 按下键盘按键或组合键 |\n| 键盘操作 | `type_text` | 向聚焦的输入框输入文本 |\n| 元素交互 | `click` | 点击指定元素 |\n| 元素交互 | `drag` | 拖拽元素到目标位置 |\n| 元素交互 | `fill` | 填充输入框或选择选项 |\n| 元素交互 | `hover` | 鼠标悬停在元素上 |\n| 文件操作 | `upload_file` | 通过文件输入元素上传文件 |\n\n## 键盘操作工具\n\n### press_key 工具\n\n`press_key` 工具用于模拟键盘按键操作，支持单键、修饰键组合以及特殊键序列。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `key` | string | 是 | 按键名称，支持组合键格式如 \"Control+A\"、\"Control+Shift+R\" |\n| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |\n\n**支持的修饰键：**\n\n- `Control`\n- `Shift`\n- `Alt`\n- `Meta`\n\n**特殊键示例：**\n\n- `Enter` - 回车键\n- `Tab` - 制表符\n- `Escape` - 退出键\n- `ArrowUp` / `ArrowDown` - 方向键\n- `Control++` - Ctrl 加号（缩放）\n- `Control+Shift+R` - 强制刷新\n\n**实现原理：**\n\n该工具使用 `parseKey` 函数解析按键字符串，将修饰键与主键分离。执行时按照修饰键按下 → 主键按下 → 修饰键释放的顺序进行操作，确保组合键的正确性。资料来源：[src/tools/input.ts:1-100]()\n\n```typescript\nconst result = await page.waitForEventsAfterAction(async () => {\n for (const modifier of modifiers) {\n await page.pptrPage.keyboard.down(modifier);\n }\n await page.pptrPage.keyboard.press(key);\n for (const modifier of modifiers.toReversed()) {\n await page.pptrPage.keyboard.up(modifier);\n }\n});\n```\n\n### type_text 工具\n\n`type_text` 工具用于向当前聚焦的输入元素输入文本内容。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `text` | string | 是 | 要输入的文本内容 |\n| `submitKey` | string | 否 | 输入完成后自动按下的提交键，如 \"Enter\" |\n| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |\n\n**使用场景：**\n\n- 在文本框中输入搜索关键词\n- 填写表单字段\n- 在富文本编辑器中输入内容\n\n**执行流程：**\n\n```mermaid\ngraph LR\n A[聚焦输入框] --> B[逐字符输入文本]\n B --> C{指定了 submitKey?}\n C -->|是| D[按下提交键]\n C -->|否| E[操作完成]\n D --> E\n```\n\n## 元素交互工具\n\n### click 工具\n\n`click` 工具通过元素 ID 执行点击操作，支持单击和双击模式。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `id` | string | 是 | 目标元素的 UID（从快照获取） |\n| `dblClick` | boolean | 否 | 是否执行双击，默认为 false |\n| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |\n\n### hover 工具\n\n`hover` 工具将鼠标移动到指定元素上方，常用于触发 CSS 悬浮效果或显示下拉菜单。\n\n### drag 工具\n\n`drag` 工具执行拖拽操作，将源元素拖拽到目标元素位置。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `src` | string | 是 | 源元素 ID |\n| `dst` | string | 是 | 目标元素 ID |\n| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |\n\n### fill 工具\n\n`fill` 工具用于快速填充表单输入框或选择下拉选项，相比 `type_text` 更加高效。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `id` | string | 是 | 目标输入框或选择框的 ID |\n| `text` | string | 是 | 要填充的文本或选项值 |\n| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |\n\n## 文件上传工具\n\n### upload_file 工具\n\n`upload_file` 工具通过已存在的文件输入元素（``）上传本地文件。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `id` | string | 是 | 文件输入元素的 ID |\n| `filePath` | string | 是 | 本地文件的绝对路径 |\n| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |\n\n**使用限制：**\n\n- 目标元素必须是 `` 或具有 `contenteditable` 属性的元素\n- 文件路径必须是服务器可访问的本地路径\n- 不支持拖拽上传区域（需使用 `drag` 工具模拟拖拽）\n\n## 通用参数与配置\n\n### 快照参数\n\n所有交互工具都支持 `includeSnapshot` 可选参数，用于控制在操作执行后是否返回页面的可访问性树快照。\n\n| 参数值 | 行为描述 |\n|--------|----------|\n| `true` | 操作完成后返回完整快照，可用于验证操作效果 |\n| `false` 或未指定 | 仅返回操作结果文本，不返回快照 |\n\n建议在以下场景启用快照返回：\n\n- 验证表单提交后的页面状态\n- 检查下拉菜单或弹窗是否正确显示\n- 确认异步操作完成后的 DOM 变化\n\n### 页面选择\n\n交互工具执行前必须通过 `select_page` 选择目标页面：\n\n```bash\nchrome-devtools select_page 1 # 选择索引为 1 的页面\nchrome-devtools select_page 1 --bringToFront true # 选择并切换到前台\n```\n\n未选择页面的直接调用将导致错误。\n\n## 工作流程\n\n### 典型交互流程\n\n```mermaid\ngraph TD\n A[初始化浏览器连接] --> B[选择目标页面]\n B --> C[获取页面快照]\n C --> D[识别目标元素 ID]\n D --> E[执行交互操作]\n E --> F{需要验证结果?}\n F -->|是| G[获取更新后的快照]\n F -->|否| H[完成]\n G --> H\n```\n\n### 对话框处理\n\n部分操作（如表单提交、文件上传确认）可能触发浏览器对话框。系统通过 `blockedByDialog` 属性控制工具是否等待对话框处理：\n\n- `press_key` 等工具默认 `blockedByDialog: true`，会在对话框出现时阻塞\n- 遇到对话框时，需使用 `handle_dialog` 工具进行响应\n\n```bash\nchrome-devtools handle_dialog accept # 接受对话框\nchrome-devtools handle_dialog dismiss --promptText \"取消\" # 拒绝并填写提示文本\n```\n\n## 错误处理\n\n### 常见错误场景\n\n| 错误类型 | 原因 | 解决方案 |\n|----------|------|----------|\n| 元素未找到 | 提供的 ID 指向不存在的元素 | 使用 `take_snapshot` 重新获取最新页面状态 |\n| 页面未选中 | 未先调用 `select_page` | 选择目标页面后重试 |\n| 对话框阻塞 | 操作被对话框中断 | 使用 `handle_dialog` 处理后再重试 |\n| 超时错误 | 元素等待超时 | 增加超时时间或检查元素是否存在 |\n\n### 最佳实践\n\n1. **始终获取最新快照**：页面状态可能因异步操作变化，建议每次交互前重新调用 `take_snapshot`\n2. **使用 appropriate 的超时设置**：对于慢速网络或复杂页面，适当增加超时时间\n3. **验证操作结果**：使用快照对比验证交互是否成功执行\n4. **避免并行冲突**：多个工具同时操作同一页面可能导致不可预期行为\n\n## 命令行使用示例\n\n```bash\n# 点击按钮\nchrome-devtools click \"btn-submit\"\n\n# 双击并获取快照\nchrome-devtools click \"btn-edit\" --dblClick true --includeSnapshot true\n\n# 输入文本并提交\nchrome-devtools type_text \"Hello World\" --submitKey \"Enter\"\n\n# 按下组合键\nchrome-devtools press_key \"Control+A\" --includeSnapshot true\n\n# 拖拽操作\nchrome-devtools drag \"source-id\" \"target-id\"\n\n# 文件上传\nchrome-devtools upload_file \"file-input\" \"/path/to/document.pdf\"\n```\n\n## 相关资源\n\n- 完整工具列表和参数说明：参考 `skills/chrome-devtools-cli/SKILL.md`\n- 元素定位策略：使用 `take_snapshot` 获取可访问性树和元素 UID\n- 高级调试：结合 `evaluate_script` 工具执行自定义 JavaScript 验证\n\n---\n\n\n\n## 性能分析工具\n\n### 相关页面\n\n相关主题：[工具参考](#tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/performance.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/performance.ts)\n- [src/tools/lighthouse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/lighthouse.ts)\n- [src/trace-processing/parse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/trace-processing/parse.ts)\n- [skills/debug-optimize-lcp/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/debug-optimize-lcp/SKILL.md)\n- [skills/debug-optimize-lcp/references/lcp-snippets.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/debug-optimize-lcp/references/lcp-snippets.md)\n- [skills/debug-optimize-lcp/references/optimization-strategies.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/debug-optimize-lcp/references/optimization-strategies.md)\n- [scripts/eval_scenarios/performance_test.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/eval_scenarios/performance_test.ts)\n \n\n# 性能分析工具\n\n## 概述\n\n性能分析工具是 chrome-devtools-mcp 提供的核心功能集，用于监控、测量和优化网页性能。该工具集涵盖性能追踪、性能洞察分析、内存快照捕获以及 Lighthouse 审计等多个维度，为开发者提供全面的性能诊断能力。\n\n工具采用 Chrome DevTools Protocol (CDP) 与浏览器内核深度交互，支持性能追踪录制、追踪文件保存与加载、性能指标解析以及自动化 Lighthouse 审计等功能。\n\n资料来源：[src/tools/performance.ts]() [src/tools/lighthouse.ts]()\n\n## 工具架构\n\n### 模块组成\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| 性能追踪 | `src/tools/performance.ts` | 启动/停止追踪录制，保存追踪文件 |\n| 性能洞察 | `src/tools/performance.ts` | 分析 Performance Insight 数据 |\n| 内存快照 | `src/tools/performance.ts` | 捕获 V8 堆内存快照 |\n| Lighthouse 审计 | `src/tools/lighthouse.ts` | 执行无头性能审计 |\n| 追踪解析 | `src/trace-processing/parse.ts` | 解析和处理追踪数据 |\n\n### 工具分类\n\n根据工具作用域可分为两类：\n\n1. **全局工具 (Global Tools)**：独立于页面上下文，直接通过 CDP 与浏览器交互\n2. **页面工具 (Page Tools)**：作用于当前选中的页面，需先选择页面\n\n性能分析工具中，`performance_start_trace`、`performance_stop_trace` 和 `take_memory_snapshot` 属于全局工具，而 `performance_analyze_insight` 和 `lighthouse_audit` 属于页面工具。\n\n资料来源：[src/tools/ToolDefinition.ts]()\n\n## 性能追踪 (Performance Trace)\n\n### 功能描述\n\n性能追踪工具提供 Chrome 开发者工具的性能录制功能，能够捕获页面在加载和运行过程中的详细执行轨迹数据。\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[开始追踪] --> B[performance_start_trace]\n B --> C{reload 参数}\n C -->|true| D[重新加载页面并录制]\n C -->|false| E[录制当前页面状态]\n D --> F[CDP Performance.startTrace]\n E --> F\n F --> G[追踪数据缓存于内存]\n G --> H[performance_stop_trace]\n H --> I{filePath 参数}\n I -->|提供| J[保存到文件]\n I -->|未提供| K[返回 JSON 数据]\n J --> L[追踪完成]\n K --> L\n```\n\n### 工具参数\n\n#### performance_start_trace\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `reload` | `boolean` | `false` | 是否在开始追踪前重新加载页面 |\n| `screenshot` | `boolean` | `false` | 是否捕获截屏 |\n| `filePath` | `string` | 无 | 追踪文件的保存路径（可选） |\n\n当 `reload` 设置为 `true` 时，工具会重新加载页面并录制完整的加载过程，这对于分析页面首次加载性能至关重要。\n\n资料来源：[src/tools/performance.ts]()\n资料来源：[skills/chrome-devtools/SKILL.md]()\n\n#### performance_stop_trace\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `filePath` | `string` | 无 | 导出追踪数据的文件路径（可选） |\n\n停止当前正在进行的性能追踪录制，并将追踪数据保存到指定文件或返回 JSON 数据。\n\n### 追踪数据格式\n\n追踪数据采用 JSON 格式，包含以下核心部分：\n\n- **traceEvents**：Chrome 追踪格式的事件数组\n- **metadata**：追踪元数据，包括浏览器版本、录制时间等\n- **screenshots**：如果启用截屏，则包含 Base64 编码的截屏数据\n\n## 性能洞察分析 (Performance Insights)\n\n### 功能描述\n\nPerformance Insights 是 Chrome DevTools 中比传统 Performance 面板更现代的性能分析界面，提供以用户为中心的性能指标解读。工具 `performance_analyze_insight` 用于获取这些洞察数据。\n\n### 支持的洞察类型\n\n| 洞察类型 | 说明 |\n|----------|------|\n| `LCPBreakdown` | Largest Contentful Paint 时间分解 |\n| `FCPBreakdown` | First Contentful Paint 时间分解 |\n| `CLSBreakdown` | Cumulative Layout Shift 变化分析 |\n| `TTFBBreakdown` | Time To First Byte 时间分解 |\n\n### 工具参数\n\n#### performance_analyze_insight\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `handle` | `string` | 是 | 追踪处理标识符 |\n| `type` | `string` | 是 | 洞察类型（如 `LCPBreakdown`） |\n\n### LCP 优化指南\n\n根据 LCPBreakdown 洞察数据，可按以下目标进行优化：\n\n| 瓶颈目标 | 占比目标 | 优化策略 |\n|----------|----------|----------|\n| TTFB | ~40% | 减少重定向，优化服务器响应时间，使用 CDN 缓存 HTML |\n| 资源加载时间 | ~40% | 使用 WebP/AVIF 格式，启用压缩，设置缓存头 |\n| 元素渲染延迟 | <10% | 内联关键 CSS，延迟非关键资源，打破长任务 |\n| LCP 资源加载延迟 | ~40% | 使用 ``，避免懒加载 LCP 图片 |\n\n资料来源：[skills/debug-optimize-lcp/SKILL.md]()\n资料来源：[skills/debug-optimize-lcp/references/optimization-strategies.md]()\n\n## 内存快照 (Memory Snapshot)\n\n### 功能描述\n\n内存快照工具用于捕获 V8 JavaScript 引擎的堆内存状态，帮助开发者分析内存泄漏和内存使用情况。\n\n### 工具参数\n\n#### take_memory_snapshot\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `filePath` | `string` | 快照文件的保存路径 |\n\n快照文件格式为 `.heapsnapshot`，可使用 Chrome DevTools 的 Memory 面板加载分析。\n\n### 工作原理\n\n1. 调用 CDP 的 `HeapProfiler.takeHeapSnapshot` 方法\n2. 将快照数据序列化为 Chrome 支持的堆快照格式\n3. 保存到指定文件路径或返回数据\n\n## Lighthouse 审计\n\n### 功能描述\n\nLighthouse 审计工具提供基于 Chromium 内置 Lighthouse 的自动化网站质量审计，覆盖无障碍访问（Accessibility）、搜索引擎优化（SEO）、最佳实践等多个维度。\n\n### 与性能追踪的区别\n\n| 维度 | Lighthouse 审计 | 性能追踪 |\n|------|------------------|----------|\n| 用途 | 网站质量综合评估 | 底层性能数据录制 |\n| 输出 | 结构化审计报告 | 原始追踪事件数据 |\n| 适用场景 | 快速评分、CI 集成 | 深度性能分析 |\n\n### 工具参数\n\n#### lighthouse_audit\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `mode` | `navigation` \\| `snapshot` | `navigation` | 审计模式：`navigation` 重新加载并审计，`snapshot` 分析当前状态 |\n| `device` | `desktop` \\| `mobile` | `desktop` | 模拟设备类型 |\n| `outputDirPath` | `string` | 临时目录 | 报告文件的保存目录 |\n| `pageId` | `number` | 当前选中页 | 指定审计的目标页面 |\n\n### 审计类别\n\nLighthouse 审计默认包含以下类别：\n\n| 类别 | 说明 |\n|------|------|\n| `accessibility` | 无障碍访问审计，检测缺失的标签、无效的 ARIA 属性等 |\n| `seo` | 搜索引擎优化审计 |\n| `best-practices` | Web 最佳实践审计 |\n| `agentic-browsing` | 代理浏览能力审计 |\n\n### 审计结果结构\n\n审计结果为 JSON 格式，包含：\n\n- `scores`：各审计类别的分数（0-1 范围）\n- `audits`：详细审计结果，包含通过/失败状态和建议\n- `timing`：审计执行时间\n\n资料来源：[src/tools/lighthouse.ts]()\n\n## LCP 调试与优化工作流\n\n### 诊断流程\n\n```mermaid\ngraph TD\n A[开始 LCP 优化] --> B[performance_start_trace reload=true]\n B --> C[录制页面加载追踪]\n C --> D[performance_stop_trace]\n D --> E[performance_analyze_insight LCPBreakdown]\n E --> F{识别瓶颈}\n F -->|TTFB 过高| G[优化服务器响应]\n F -->|资源加载慢| H[优化资源大小和格式]\n F -->|渲染延迟| I[消除阻塞资源]\n G --> J[验证修复]\n H --> J\n I --> J\n J --> K{重新录制}\n K -->|需继续优化| B\n K -->|达标| L[完成]\n```\n\n### JavaScript 诊断片段\n\n#### 识别 LCP 元素\n\n```javascript\nasync () => {\n return await new Promise(resolve => {\n new PerformanceObserver(list => {\n const entries = list.getEntries();\n const last = entries[entries.length - 1];\n resolve({\n element: last.element?.tagName,\n id: last.element?.id,\n url: last.url,\n startTime: last.startTime,\n renderTime: last.renderTime,\n size: last.size,\n });\n }).observe({type: 'largest-contentful-paint', buffered: true});\n });\n};\n```\n\n#### 审计常见问题\n\n```javascript\n() => {\n const issues = [];\n // 检查视口内懒加载的图片\n document.querySelectorAll('img[loading=\"lazy\"]').forEach(img => {\n const rect = img.getBoundingClientRect();\n if (rect.top < window.innerHeight) {\n issues.push({\n issue: 'lazy-loaded image in viewport',\n fix: 'Remove loading=\"lazy\" from this image',\n });\n }\n });\n return issues;\n};\n```\n\n资料来源：[skills/debug-optimize-lcp/references/lcp-snippets.md]()\n\n## 测试场景\n\n性能分析工具的自动化测试定义于 `scripts/eval_scenarios/performance_test.ts`：\n\n| 场景 | 预期行为 |\n|------|----------|\n| 目标 URL | `https://developers.chrome.com` |\n| 最大轮次 | 2 |\n| 预期调用 | 第一轮：导航或新建页面；第二轮：启动性能追踪 |\n\n资料来源：[scripts/eval_scenarios/performance_test.ts]()\n\n## 使用限制与注意事项\n\n1. **对话处理**：性能追踪工具（`performance_start_trace`）在有对话框打开时会被阻塞\n2. **超时配置**：使用 `timeout` 参数控制操作超时时间，避免长时间等待\n3. **文件路径**：建议为追踪文件和快照指定明确的文件路径，便于后续分析\n4. **页面选择**：Lighthouse 审计等页面工具需要先选择目标页面\n\n## 相关工具链接\n\n- 导航工具：[navigate_page](skills/chrome-devtools/SKILL.md) - 页面导航\n- 快照工具：[take_snapshot](skills/chrome-devtools/SKILL.md) - 页面结构快照\n- 模拟工具：[emulate](skills/chrome-devtools-cli/SKILL.md) - 网络和设备模拟\n\n---\n\n\n\n## 内存调试工具\n\n### 相关页面\n\n相关主题：[工具参考](#tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/memory.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/memory.ts)\n- [src/HeapSnapshotManager.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/HeapSnapshotManager.ts)\n- [src/formatters/HeapSnapshotFormatter.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/formatters/HeapSnapshotFormatter.ts)\n- [skills/memory-leak-debugging/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/memory-leak-debugging/SKILL.md)\n- [skills/memory-leak-debugging/references/compare_snapshots.js](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/memory-leak-debugging/references/compare_snapshots.js)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n \n\n# 内存调试工具\n\n## 概述\n\n内存调试工具是 chrome-devtools-mcp 提供的核心功能集之一，用于分析和诊断浏览器页面中的内存问题。这些工具通过 Chrome DevTools Protocol 与 Chromium 的堆快照引擎交互，帮助开发者识别内存泄漏、追踪对象增长，并理解 JavaScript 运行时的内存分布情况。\n\n内存调试工具的主要职责包括：\n\n- 捕获页面的堆快照（Heap Snapshot）文件\n- 加载和分析堆快照数据\n- 提供快照摘要统计信息\n- 支持与外部内存分析工具（如 Memlab）的集成\n- 包含用于手动比较快照的回退脚本\n\n资料来源：[src/tools/memory.ts:1-15]()\n\n## 架构设计\n\n### 核心组件\n\n内存调试工具的架构由以下核心组件构成：\n\n| 组件 | 文件路径 | 职责描述 |\n|------|----------|----------|\n| MemoryToolDefinitions | `src/tools/memory.ts` | 定义所有内存相关的 MCP 工具 |\n| HeapSnapshotManager | `src/HeapSnapshotManager.ts` | 管理堆快照的加载、解析和缓存 |\n| HeapSnapshotFormatter | `src/formatters/HeapSnapshotFormatter.ts` | 格式化堆快照输出为可读格式 |\n\n### 工具定义架构\n\n内存工具使用统一的工具定义框架，该框架基于 `definePageTool` 工厂函数构建。每个工具定义包含以下结构：\n\n```typescript\nexport interface BaseToolDefinition {\n name: string;\n description: string;\n annotations: {\n category: ToolCategory;\n readOnlyHint: boolean;\n conditions?: string[];\n };\n schema: Schema;\n blockedByDialog: boolean;\n}\n```\n\n资料来源：[src/tools/ToolDefinition.ts:20-35]()\n\n## 工具 API\n\n### takeMemorySnapshot\n\n**功能**：捕获当前选中页面的堆快照。\n\n```typescript\nexport const takeMemorySnapshot = definePageTool({\n name: 'take_memory_snapshot',\n description: `Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.`,\n annotations: {\n category: ToolCategory.MEMORY,\n readOnlyHint: false,\n },\n schema: {\n filePath: zod\n .string()\n .describe('A path to a .heapsnapshot file to save the heapsnapshot to.'),\n },\n blockedByDialog: true,\n handler: async (request, response, context) => {\n const page = request.page;\n context.validatePath(request.params.filePath);\n\n await page.pptrPage.captureHeapSnapshot({\n path: ensureExtension(request.params.filePath, '.heapsnapshot'),\n });\n\n response.appendResponseLine(\n `Heap snapshot saved to ${request.params.filePath}`,\n );\n },\n});\n```\n\n资料来源：[src/tools/memory.ts:16-46]()\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| filePath | string | 是 | 堆快照文件的保存路径，必须以 `.heapsnapshot` 结尾 |\n\n**执行流程**：\n\n```mermaid\ngraph TD\n A[调用 take_memory_snapshot] --> B[验证文件路径]\n B --> C[执行 pptrPage.captureHeapSnapshot]\n C --> D[保存 .heapsnapshot 文件]\n D --> E[返回成功消息]\n```\n\n**使用示例**：\n\n```bash\nchrome-devtools take_memory_snapshot \"./baseline.heapsnapshot\"\nchrome-devtools take_memory_snapshot \"./target.heapsnapshot\" --includeSnapshot true\n```\n\n### loadMemorySnapshot\n\n**功能**：加载堆快照文件并返回摘要统计信息。\n\n```typescript\nexport const exploreMemorySnapshot = defineTool({\n name: 'load_memory_snapshot',\n description:\n 'Loads a memory heapsnapshot and returns snapshot summary stats.',\n annotations: {\n category: ToolCategory.MEMORY,\n readOnlyHint: true,\n conditions: ['experimentalMemory'],\n },\n schema: {\n filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),\n },\n blockedByDialog: false,\n // ...\n});\n```\n\n资料来源：[src/tools/memory.ts:48-68]()\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| filePath | string | 是 | 要读取的堆快照文件路径 |\n\n**注意**：此工具需要 `experimentalMemory` 条件满足方可使用。\n\n## 工作流程\n\n### 基本内存调试流程\n\n```mermaid\ngraph TD\n A[1. 创建新页面或导航到目标页面] --> B[2. 使用 take_memory_snapshot 捕获基线快照]\n B --> C[3. 执行目标操作（如用户交互）]\n C --> D[4. 使用 take_memory_snapshot 捕获目标快照]\n D --> E[5. 使用 Memlab 或回退脚本分析快照]\n E --> F[6. 识别泄漏并修复]\n F --> G[7. 重复验证]\n```\n\n### 完整内存泄漏调试流程\n\n根据 SKILL.md 文档，内存泄漏调试的标准工作流程如下：\n\n#### 步骤 1：建立基线快照\n\n在执行任何操作之前，捕获页面的初始内存状态：\n\n```bash\nchrome-devtools take_memory_snapshot \"./baseline.heapsnapshot\"\n```\n\n资料来源：[skills/memory-leak-debugging/SKILL.md:1-20]()\n\n#### 步骤 2：操作并捕获目标快照\n\n执行可能存在内存泄漏的操作（如重复用户交互），然后再次捕获快照：\n\n```bash\nchrome-devtools take_memory_snapshot \"./target.heapsnapshot\"\n```\n\n#### 步骤 3：恢复页面状态\n\n将页面恢复到原始状态，验证内存是否被正确释放：\n\n> 使用 `click`、`fill` 等工具将页面操作回原始状态，观察内存是否释放。\n\n资料来源：[skills/memory-leak-debugging/SKILL.md:21-35]()\n\n#### 步骤 4：捕获最终快照\n\n恢复操作后再次捕获快照：\n\n```bash\nchrome-devtools take_memory_snapshot \"./final.heapsnapshot\"\n```\n\n#### 步骤 5：分析对比\n\n使用 Memlab 或回退脚本分析三个快照文件。\n\n## 快照比较脚本\n\n### compare_snapshots.js\n\n当 Memlab 不可用时，可以使用项目提供的回退脚本进行快照比较。\n\n**位置**：`skills/memory-leak-debugging/references/compare_snapshots.js`\n\n**使用方法**：\n\n```bash\nnode skills/memory-leak-debugging/references/compare_snapshots.js \n```\n\n资料来源：[skills/memory-leak-debugging/references/compare_snapshots.js:1-50]()\n\n**输出内容**：\n\n| 输出部分 | 说明 |\n|----------|------|\n| Top 10 growing objects | 按大小增长排序的前 10 个对象 |\n| Top 3 common leak types | 最常见的 3 种泄漏类型 |\n\n**检测的常见泄漏类型**：\n\n```javascript\nconst commonLeaks = diffs.filter(\n d =>\n d.key.toLowerCase().includes('detached') ||\n d.key.toLowerCase().includes('html') ||\n d.key.toLowerCase().includes('eventlistener') ||\n d.key.toLowerCase().includes('context') ||\n d.key.toLowerCase().includes('closure'),\n);\n```\n\n资料来源：[skills/memory-leak-debugging/references/compare_snapshots.js:40-52]()\n\n### 输出示例\n\n脚本会输出类似以下格式的结果：\n\n```\n--- Top 10 growing objects by size ---\nDetached HTMLDivElement: +5 objects, +2048 bytes\nClosure: +12 objects, +1024 bytes\n\n--- Top 3 most common types of memory leaks found ---\nDetached HTMLDivElement: +5 objects, +2048 bytes\nEventListener: +3 objects, +512 bytes\nContext: +2 objects, +256 bytes\n```\n\n## 常见内存泄漏类型\n\n根据项目文档，堆快照分析中最常见的泄漏类型包括：\n\n| 泄漏类型 | 描述 | 检测关键词 |\n|----------|------|------------|\n| Detached DOM nodes | 已从 DOM 树移除但仍被 JavaScript 引用的 DOM 节点 | `detached`, `html` |\n| Closures | 形成闭包并捕获外部变量的函数 | `closure` |\n| Event Listeners | 未正确移除的事件监听器 | `eventlistener` |\n| Contexts | JavaScript 执行上下文未正确释放 | `context` |\n\n资料来源：[skills/memory-leak-debugging/references/compare_snapshots.js:43-49]()\n\n## 使用限制与注意事项\n\n### 工具阻塞条件\n\n`takeMemorySnapshot` 工具配置了 `blockedByDialog: true`，这意味着当页面上存在对话框时，该工具将被阻塞：\n\n> **blockedByDialog**: 如果设置为 `true`，则工具在页面存在对话框时无法执行。\n\n资料来源：[src/tools/memory.ts:38-39]()\n\n### 路径验证\n\n所有文件路径在执行前都会经过验证，确保快照文件能够正确保存到指定位置：\n\n```typescript\ncontext.validatePath(request.params.filePath);\n```\n\n资料来源：[src/tools/memory.ts:41]()\n\n### 文件扩展名强制\n\n脚本会自动为文件路径添加 `.heapsnapshot` 扩展名：\n\n```typescript\nawait page.pptrPage.captureHeapSnapshot({\n path: ensureExtension(request.params.filePath, '.heapsnapshot'),\n});\n```\n\n资料来源：[src/tools/memory.ts:43-45]()\n\n## 集成外部工具\n\n### Memlab 集成\n\n项目推荐使用 Memlab 进行高级内存泄漏分析。使用 `take_memory_snapshot` 生成 `.heapsnapshot` 文件后，可参考 `references/memlab.md` 文档进行详细分析。\n\n> **重要提示**：不要使用 `read_file` 或 `cat` 命令直接读取原始的 `.heapsnapshot` 文件。\n\n资料来源：[skills/memory-leak-debugging/SKILL.md:36-50]()\n\n## 命令行使用\n\n### 基本命令\n\n```bash\n# 捕获堆快照\nchrome-devtools take_memory_snapshot \"./snap.heapsnapshot\"\n\n# 加载并分析快照\nchrome-devtools load_memory_snapshot \"./snap.heapsnapshot\"\n```\n\n### 完整示例\n\n```bash\n# 1. 导航到目标页面\nchrome-devtools navigate_page --url \"https://example.com\"\n\n# 2. 捕获基线快照\nchrome-devtools take_memory_snapshot \"./baseline.heapsnapshot\"\n\n# 3. 执行测试操作（重复 10 次以放大泄漏）\nchrome-devtools click \"button\" # 执行操作\nchrome-devtools click \"button\" # 重复操作\n# ... 重复 10 次\n\n# 4. 捕获目标快照\nchrome-devtools take_memory_snapshot \"./target.heapsnapshot\"\n\n# 5. 恢复页面状态\n# ... 执行恢复操作\n\n# 6. 捕获最终快照\nchrome-devtools take_memory_snapshot \"./final.heapsnapshot\"\n\n# 7. 使用回退脚本分析\nnode skills/memory-leak-debugging/references/compare_snapshots.js ./baseline.heapsnapshot ./target.heapsnapshot\n```\n\n## 相关文件索引\n\n| 文件 | 描述 |\n|------|------|\n| `src/tools/memory.ts` | 内存工具的核心定义文件 |\n| `src/HeapSnapshotManager.ts` | 堆快照管理器实现 |\n| `src/formatters/HeapSnapshotFormatter.ts` | 堆快照格式化器 |\n| `skills/memory-leak-debugging/SKILL.md` | 内存泄漏调试技能文档 |\n| `skills/memory-leak-debugging/references/compare_snapshots.js` | 快照比较回退脚本 |\n| `skills/memory-leak-debugging/references/common-leaks.md` | 常见泄漏类型参考文档 |\n\n---\n\n\n\n## CLI与配置\n\n### 相关页面\n\n相关主题：[MCP客户端集成](#mcp-client-integration), [快速开始指南](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/bin/chrome-devtools-mcp-cli-options.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-mcp-cli-options.ts)\n- [src/bin/chrome-devtools-mcp-main.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-mcp-main.ts)\n- [docs/cli.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/cli.md)\n- [puppeteer.config.cjs](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/puppeteer.config.cjs)\n- [src/tools/categories.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts)\n- [src/bin/chrome-devtools-cli-options.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-cli-options.ts)\n- [scripts/generate-cli.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-cli.ts)\n \n\n# CLI与配置\n\n## 概述\n\nchrome-devtools-mcp 提供了完整的命令行界面（CLI）和灵活的配置系统，支持通过命令行参数启动 MCP 服务器、管理浏览器生命周期、以及自动化浏览器操作。该项目采用 TypeScript 开发，使用 Puppeteer 作为底层浏览器自动化引擎，并通过 MCP（Model Context Protocol）协议与 AI 代理进行通信。资料来源：[AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[chrome-devtools-mcp CLI] --> B[chrome-devtools-mcp-main.ts]\n A --> C[chrome-devtools-mcp-cli-options.ts]\n B --> D[Puppeteer Browser]\n C --> E[命令行参数解析]\n F[puppeteer.config.cjs] --> D\n G[MCP Server] --> H[工具层]\n H --> I[Page Tools]\n H --> J[Navigation Tools]\n H --> K[Performance Tools]\n H --> L[Network Tools]\n```\n\n### 启动流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as CLI解析器\n participant Main as 主程序\n participant Browser as Puppeteer浏览器\n participant MCP as MCP服务器\n \n User->>CLI: 执行命令 + 参数\n CLI->>CLI: parseArguments() 验证参数\n CLI->>Main: 传递解析后的配置\n Main->>Browser: 启动Chrome实例\n Browser-->>Main: Browser实例就绪\n Main->>MCP: 初始化MCP服务\n MCP-->>User: 暴露工具列表\n```\n\n## 命令行接口\n\n### 全局命令\n\n| 命令 | 功能 | 说明 |\n|------|------|------|\n| `start` | 启动服务 | 启动或重启 chrome-devtools-mcp |\n| `status` | 检查状态 | 检查 chrome-devtools-mcp 是否运行 |\n| `stop` | 停止服务 | 停止正在运行的 chrome-devtools-mcp |\n| `help` | 帮助信息 | 显示命令帮助和使用方法 |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:50-53](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 工具命令\n\nCLI 支持直接调用 MCP 工具进行浏览器自动化操作，基本语法如下：\n\n```sh\nchrome-devtools [arguments] [flags]\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:21](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 输出格式\n\n默认输出为 Markdown 格式，可通过 `--output-format` 参数切换：\n\n```sh\nchrome-devtools take_snapshot --output-format=json\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:23](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## 命令行参数配置\n\n### 参数解析模块\n\n参数解析由 `chrome-devtools-mcp-cli-options.ts` 实现，核心类型定义如下：\n\n```typescript\ninterface ParsedArguments {\n tool?: string;\n args?: string[];\n flags?: Flags;\n}\n\ninterface Flags {\n port?: number;\n host?: string;\n viaCli?: boolean;\n experimentalVision?: boolean;\n experimentalScreencast?: boolean;\n categoryExtensions?: boolean;\n categoryExperimentalWebmcp?: boolean;\n // ... 其他配置项\n}\n```\n\n资料来源：[scripts/generate-cli.ts:18-28](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-cli.ts)\n\n### 工具类别配置\n\n工具按功能分类管理，通过 `--category-*` 标志启用：\n\n| 类别标志 | 功能 | 默认状态 |\n|----------|------|----------|\n| `--categoryExperimentalWebmcp` | WebMCP 实验性工具 | 关闭 |\n| `--categoryExtensions` | Chrome 扩展管理 | 关闭 |\n| `--experimentalVision` | 视觉坐标点击 | 关闭 |\n| `--experimentalScreencast` | 屏幕录制功能 | 关闭 |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:49-51](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 必需标志构建\n\n工具类别标志通过 `buildFlag` 函数动态构建：\n\n```typescript\nimport {buildFlag} from '../build/src/index.js';\n\n// 生成标志名\nconst categoryFlag = buildFlag(category);\nconst flagName = `--${categoryFlag}`;\n```\n\n资料来源：[scripts/generate-docs.ts:72-76](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)\n\n### 默认关闭的类别\n\n部分工具类别默认不启用，需要显式启用：\n\n```typescript\nexport const OFF_BY_DEFAULT_CATEGORIES = [\n ToolCategory.WEBMCP,\n ToolCategory.EXTENSION,\n ToolCategory.EXPERIMENTAL,\n];\n```\n\n资料来源：[scripts/generate-docs.ts:24-28](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)\n\n## 工具分类体系\n\n### 分类定义\n\n```mermaid\ngraph LR\n A[ToolCategory] --> B[NAVIGATION]\n A --> C[INPUT]\n A --> D[PERFORMANCE]\n A --> E[NETWORK]\n A --> F[EXTENSION]\n A --> G[WEBMCP]\n A --> H[EXPERIMENTAL]\n```\n\n### 分类标签映射\n\n| 分类枚举 | 中文标签 | 说明 |\n|----------|----------|------|\n| `NAVIGATION` | 导航 | 页面导航和页面管理工具 |\n| `INPUT` | 输入 | 用户交互和元素操作 |\n| `PERFORMANCE` | 性能 | 性能分析和追踪 |\n| `NETWORK` | 网络 | 网络请求监控 |\n| `EXTENSION` | 扩展 | Chrome 扩展管理 |\n| `WEBMCP` | WebMCP | 网页暴露的 MCP 工具 |\n| `EXPERIMENTAL` | 实验性 | 实验功能 |\n\n资料来源：[scripts/generate-docs.ts:29-40](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)\n\n## 浏览器配置\n\n### Puppeteer 配置\n\n通过 `puppeteer.config.cjs` 配置文件管理浏览器实例：\n\n```javascript\nmodule.exports = {\n puppeteer: {\n // 浏览器启动参数\n args: [\n '--no-sandbox',\n '--disable-setuid-sandbox',\n '--disable-dev-shm-usage',\n ],\n // 用户数据目录（持久化配置）\n userDataDir: './chrome-profile',\n // 调试端口\n debugPort: 9222,\n },\n};\n```\n\n资料来源：[puppeteer.config.cjs](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/puppeteer.config.cjs)\n\n### 浏览器生命周期\n\n浏览器使用持久化 Chrome 配置文件，首次调用工具时自动启动：\n\n```mermaid\nstateDiagram-v2\n [*] --> 未启动: 程序初始化\n 未启动 --> 运行中: 首次工具调用\n 运行中 --> 运行中: 工具操作\n 运行中 --> 已停止: stop命令\n 已停止 --> 运行中: start命令\n 已停止 --> [*]: 程序退出\n```\n\n资料来源：[skills/chrome-devtools/SKILL.md:8-9](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n### 页面管理\n\n工具操作作用于当前选中的页面，支持多页面管理：\n\n```sh\nchrome-devtools list_pages # 列出所有打开的页面\nchrome-devtools select_page 1 # 选择页面作为上下文\nchrome-devtools select_page 1 --bringToFront true # 选择并激活\nchrome-devtools close_page 1 # 关闭指定页面\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:27-38](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## 网络与模拟配置\n\n### 网络条件模拟\n\n```sh\n# 离线模拟\nchrome-devtools emulate --networkConditions \"Offline\"\n\n# 自定义网络节流\nchrome-devtools emulate --networkConditions \"Slow 3G\"\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:41-44](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 设备模拟\n\n| 参数 | 说明 | 示例值 |\n|------|------|--------|\n| `--viewport` | 视口尺寸 | `1920x1080` |\n| `--colorScheme` | 颜色方案 | `dark`, `light` |\n| `--cpuThrottlingRate` | CPU 节流倍率 | `4` (4x) |\n| `--geolocation` | 地理位置 | `0x0` |\n| `--userAgent` | 用户代理字符串 | Mozilla/5.0... |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:44-48](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 使用示例\n\n```sh\n# 模拟暗黑模式和全高清视口\nchrome-devtools emulate --colorScheme \"dark\" --viewport \"1920x1080\"\n\n# 模拟 CPU 节流和特定地理位置\nchrome-devtools emulate --cpuThrottlingRate 4 --geolocation \"0x0\"\n\n# 模拟自定义用户代理\nchrome-devtools emulate --userAgent \"Mozilla/5.0...\"\n\n# 调整页面窗口大小\nchrome-devtools resize_page 1920 1080\n```\n\n## 实验性功能\n\n### 启用方式\n\n实验性功能默认禁用，需通过相应标志启用：\n\n```sh\nchrome-devtools-mcp --experimentalVision=true --experimentalScreencast=true\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:49-51](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 实验性工具列表\n\n| 工具 | 功能 | 必需标志 |\n|------|------|----------|\n| `click_at` | 坐标点击 | `--experimentalVision=true` |\n| `screencast_start` | 屏幕录制 | `--experimentalScreencast=true` |\n| `screencast_stop` | 停止录制 | `--experimentalScreencast=true` |\n| `list_webmcp_tools` | 列出 WebMCP 工具 | `--categoryExperimentalWebmcp=true` |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:49-55](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## CLI 选项自动生成\n\n### 生成流程\n\n项目使用脚本自动从运行时工具定义生成 CLI 选项：\n\n```mermaid\ngraph TD\n A[generate-cli.ts] --> B[启动 MCP 服务器]\n B --> C[调用 listTools API]\n C --> D[解析工具定义]\n D --> E[生成 TypeScript 代码]\n E --> F[输出到 chrome-devtools-cli-options.ts]\n```\n\n资料来源：[scripts/generate-cli.ts:30-55](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-cli.ts)\n\n### 生成的代码结构\n\n生成的 `chrome-devtools-cli-options.ts` 包含所有工具的 CLI 接口定义：\n\n```typescript\n// 通过 MCP 协议连接本地服务器获取工具定义\nconst transport = new StdioClientTransport({\n command: 'node',\n args: [serverPath, '--viaCli'],\n env: {...process.env, CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true'},\n});\n```\n\n资料来源：[scripts/generate-cli.ts:36-42](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-cli.ts)\n\n## 构建与测试\n\n### 构建命令\n\n```sh\nnpm run build # 运行 tsc 编译并测试构建\n```\n\n资料来源：[AGENTS.md:5](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n\n### 测试命令\n\n```sh\nnpm run test # 构建并运行所有测试\nnpm run test path-to-test.ts # 构建并运行单个测试文件\n```\n\n资料来源：[AGENTS.md:6-8](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n\n### 代码格式\n\n```sh\nnpm run format # 修复格式问题和 linting 错误\n```\n\n资料来源：[AGENTS.md:11](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n\n## 扩展管理配置\n\n### 扩展操作命令\n\n| 命令 | 功能 |\n|------|------|\n| `list_extensions` | 列出已安装的扩展 |\n| `install_extension` | 安装扩展（需要路径） |\n| `uninstall_extension` | 卸载扩展（需要 ID） |\n| `reload_extension` | 重载扩展 |\n| `trigger_extension_action` | 触发扩展默认操作 |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:48-50](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 启用扩展支持\n\n扩展功能默认关闭，需要通过 `--categoryExtensions` 标志启用：\n\n```sh\nchrome-devtools-mcp --categoryExtensions=true\n```\n\n资料来源：[skills/chrome-devtools/SKILL.md:8-9](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n## 性能追踪配置\n\n### 追踪命令\n\n```sh\n# 开始追踪\nchrome-devtools performance_start_trace true false\n\n# 带文件输出\nchrome-devtools performance_start_trace true true --filePath t.gz\n\n# 停止追踪\nchrome-devtools performance_stop_trace\n\n# 保存到文件\nchrome-devtools performance_stop_trace --filePath \"t.json\"\n\n# 获取性能洞察\nchrome-devtools performance_analyze_insight \"1\" \"LCPBreakdown\"\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:32-40](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 内存快照\n\n```sh\nchrome-devtools take_memory_snapshot \"./snap.heapsnapshot\"\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:41-42](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## 环境变量\n\n| 变量名 | 功能 | 说明 |\n|--------|------|------|\n| `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` | 禁用使用统计 | 设为 `true` 可禁用遥测 |\n| `PATH` | 系统路径 | 需包含全局 npm bin 目录 |\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:13](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/references/installation.md)\n\n## 常见配置问题排查\n\n### 问题诊断步骤\n\n1. 检查服务状态：`chrome-devtools status`\n2. 查看详细日志：启动时添加 `--logFile=/tmp/cdm-test.log`\n3. 分析日志输出中的错误信息\n\n资料来源：[skills/troubleshooting/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/troubleshooting/SKILL.md)\n\n### 权限错误处理\n\n遇到 `EACCES` 权限错误时，建议：\n- 使用 `nvm` 管理 Node.js 版本\n- 配置 npm 使用不同的全局目录\n- 避免使用 `sudo` 安装全局包\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:16-18](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/references/installation.md)\n\n---\n\n\n\n## MCP客户端集成\n\n### 相关页面\n\n相关主题：[快速开始指南](#quick-start), [CLI与配置](#cli-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/README.md)\n- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n- [.mcp.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/.mcp.json)\n- [gemini-extension.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/gemini-extension.json)\n- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n- [src/McpResponse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [package.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/package.json)\n \n\n# MCP客户端集成\n\n## 概述\n\nMCP（Model Context Protocol）客户端集成是 chrome-devtools-mcp 项目的核心功能，它允许外部AI助手（如 Claude、Gemini 等）通过标准化的 MCP 协议与 Chrome DevTools 进行交互。该集成使得AI代理能够控制浏览器、执行自动化任务、采集页面快照以及进行性能调试。\n\n本项目实现了一个 MCP 服务器，通过 WebMCP 工具接口扩展了标准的 DevTools 功能，使 AI 客户端能够以结构化的方式与浏览器进行双向通信。资料来源：[AGENTS.md:1-3]()\n\n## 架构设计\n\n### 整体架构\n\nchrome-devtools-mcp 采用客户端-服务器架构，通过 MCP 协议实现 AI 助手与浏览器自动化之间的桥梁。\n\n```mermaid\ngraph TD\n subgraph AI客户端层\n A[Claude / Gemini 等] \n end\n \n subgraph MCP协议层\n B[MCP 客户端]\n C[MCP 服务器]\n end\n \n subgraph 浏览器层\n D[Chrome DevTools Protocol]\n E[浏览器实例]\n end\n \n A -->|MCP 协议| B\n B -->|MCP 请求| C\n C -->|CDP 命令| D\n D -->|CDP 响应| C\n C -->|MCP 响应| B\n B -->|MCP 响应| A\n \n D -->|控制| E\n E -->|反馈| D\n```\n\n### 核心组件\n\n| 组件名称 | 文件位置 | 功能描述 |\n|---------|---------|---------|\n| MCPResponse | `src/McpResponse.ts` | 处理 MCP 协议响应序列化与格式化 |\n| webmcp | `src/tools/webmcp.ts` | 定义 WebMCP 工具接口 |\n| ToolDefinition | `src/tools/ToolDefinition.ts` | 工具定义与参数模式抽象 |\n| 工具集合 | `src/tools/*.ts` | 具体工具实现（输入、导航、快照等）|\n\n## 客户端配置\n\n### .mcp.json 配置格式\n\nMCP 客户端通过 `.mcp.json` 配置文件声明服务器连接。配置文件采用 JSON 格式定义服务器路径和可选参数。\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"node\",\n \"args\": [\"path/to/cli.js\", \"--headless\"]\n }\n }\n}\n```\n\n资料来源：[.mcp.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/.mcp.json)\n\n### Gemini 扩展配置\n\n针对 Google Gemini 平台的特殊集成配置：\n\n```json\n{\n \"name\": \"chrome-devtools\",\n \"description\": \"...\",\n \"entry_point\": \"...\",\n \"runtime\": \"...\",\n \"permissions\": [\"browser\"]\n}\n```\n\n资料来源：[gemini-extension.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/gemini-extension.json)\n\n### 运行时环境要求\n\n项目对 Node.js 版本有明确的兼容性要求：\n\n| 版本范围 | 支持状态 |\n|---------|---------|\n| `^20.19.0` | 主要支持 |\n| `^22.12.0` | 主要支持 |\n| `>=23` | 兼容支持 |\n\n资料来源：[package.json:48-51]()\n\n## WebMCP 工具接口\n\nWebMCP 是项目定义的扩展协议，允许网页向 MCP 客户端暴露自定义工具。核心接口包含两个工具：\n\n### list_webmcp_tools\n\n列出当前页面暴露的所有 WebMCP 工具。\n\n```typescript\nexport const listWebMcpTools = definePageTool({\n name: 'list_webmcp_tools',\n description: `Lists all WebMCP tools the page exposes.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: true,\n },\n schema: {},\n blockedByDialog: false,\n handler: async (_request, response, _context) => {\n response.setListWebMcpTools();\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts:14-24]()\n\n### execute_webmcp_tool\n\n执行页面暴露的 WebMCP 工具。\n\n```typescript\nexport const executeWebMcpTool = definePageTool({\n name: 'execute_webmcp_tool',\n description: `Executes a WebMCP tool exposed by the page.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: false,\n },\n schema: {\n toolName: zod.string().describe('The name of the WebMCP tool to execute'),\n input: zod.string().optional().describe('The JSON-stringified parameters'),\n },\n blockedByDialog: false,\n handler: async (request, response) => {\n // 处理工具执行\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts:32-51]()\n\n## 工具定义模式\n\n### 工具类别\n\n所有工具通过 `ToolCategory` 枚举进行分类管理：\n\n| 类别标识 | 描述 |\n|--------|------|\n| `WEBMCP` | WebMCP 协议相关工具 |\n| `INPUT` | 用户输入自动化工具 |\n| `NAVIGATION` | 页面导航工具 |\n| `INSPECTION` | 页面检查工具 |\n\n### 工具定义函数\n\n项目使用工厂函数模式定义工具：\n\n```typescript\nexport function definePageTool(\n definition: PageToolDefinition\n): DefinedPageTool {\n return {\n ...definition,\n pageScoped: true,\n };\n}\n```\n\n关键特性包括：\n- **pageScoped**: 标记工具是否需要页面上下文\n- **blockedByDialog**: 标记对话框是否阻止工具执行\n- **readOnlyHint**: 提示工具是否仅读取数据\n\n资料来源：[src/tools/ToolDefinition.ts:38-50]()\n\n### 通用模式定义\n\n项目提供可复用的参数模式：\n\n```typescript\nexport const timeoutSchema = {\n timeout: zod\n .number()\n .int()\n .optional()\n .describe('Maximum wait time in milliseconds')\n .transform(value => value && value <= 0 ? undefined : value),\n};\n\nexport const pageIdSchema = {\n pageId: zod.number().optional().describe('Targets a specific page by ID'),\n};\n```\n\n资料来源：[src/tools/ToolDefinition.ts:53-68]()\n\n## MCP 响应处理\n\n### 响应数据结构\n\nMcpResponse 类负责将工具执行结果格式化为 MCP 协议兼容的响应：\n\n```typescript\nif (this.#listWebMcpTools && data.webmcpTools) {\n structuredContent.webmcpTools = data.webmcpTools.map(\n ({name, description, inputSchema, annotations}) => ({\n name,\n description,\n inputSchema,\n annotations,\n }),\n );\n}\n```\n\n资料来源：[src/McpResponse.ts:45-54]()\n\n### 响应格式化\n\n响应消息包含结构化内容与文本描述：\n\n| 格式类型 | 用途 |\n|---------|------|\n| `structuredContent` | JSON 序列化数据 |\n| `response` | 人类可读文本 |\n| `annotations` | 元数据标记 |\n\n资料来源：[src/McpResponse.ts:55-68]()\n\n## 集成工作流\n\n### 典型执行流程\n\n```mermaid\nsequenceDiagram\n participant AI as AI 客户端\n participant MCP as MCP 服务器\n participant CDP as Chrome DevTools\n \n AI->>MCP: 初始化连接\n MCP-->>AI: 连接确认\n \n AI->>MCP: list_webmcp_tools\n MCP->>CDP: 获取页面工具\n CDP-->>MCP: 工具列表\n MCP-->>AI: 工具定义\n \n AI->>MCP: execute_webmcp_tool\n MCP->>CDP: 执行工具\n CDP-->>MCP: 执行结果\n MCP-->>AI: 响应数据\n```\n\n### 页面工具调用示例\n\n1. **获取页面快照**：\n ```bash\n chrome-devtools take_snapshot\n ```\n\n2. **执行 JavaScript**：\n ```bash\n chrome-devtools evaluate_script \"document.title\"\n ```\n\n3. **页面导航**：\n ```bash\n chrome-devtools navigate_page --url \"https://example.com\"\n ```\n\n## 工具分类参考\n\n### 输入自动化工具\n\n| 工具名称 | 功能 | 参数 |\n|---------|------|------|\n| `type_text` | 模拟键盘输入 | `text`, `submitKey?` |\n| `fill` | 填充表单字段 | `id`, `text` |\n| `press_key` | 按下按键 | `key` |\n| `upload_file` | 文件上传 | `id`, `path` |\n| `drag` | 拖拽操作 | `src`, `dst` |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:14-28]()\n\n### 导航工具\n\n| 工具名称 | 功能 | 参数 |\n|---------|------|------|\n| `navigate_page` | 导航到URL | `url`, `type?`, `timeout?` |\n| `new_page` | 打开新页面 | `url` |\n| `close_page` | 关闭页面 | `index` |\n| `select_page` | 选择页面上下文 | `pageId` |\n| `list_pages` | 列出所有页面 | - |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:1-13]()\n\n### 检查工具\n\n| 工具名称 | 功能 | 参数 |\n|---------|------|------|\n| `take_snapshot` | 获取可访问性快照 | `includeSnapshot?` |\n| `take_screenshot` | 截图 | - |\n| `evaluate_script` | 执行脚本 | `script` |\n\n## 类型系统\n\n### Schema 定义规范\n\n项目强制使用 Zod 进行运行时类型验证，禁止使用 `any` 类型：\n\n```typescript\nimport {zod} from '../third_party/index.js';\n\n// 正确做法\nconst schema = {\n key: zod.string().describe('A key or key combination'),\n};\n\n// 禁止做法\n// const bad: any = value;\n// const bad = value as SomeType;\n```\n\n资料来源：[AGENTS.md:16-24]()\n\n### 参数解析\n\n使用 `ParsedArguments` 泛型处理参数转换：\n\n```typescript\ntype ParsedArguments = {\n [key: string]: unknown;\n};\n```\n\n## 扩展与定制\n\n### 自定义工具开发\n\n1. 在 `src/tools/` 目录创建新工具文件\n2. 使用 `definePageTool` 工厂函数定义工具\n3. 实现 `handler` 异步函数处理逻辑\n4. 导出工具并注册到相应类别\n\n### 类别扩展\n\n工具类别在 `ToolCategory` 枚举中定义：\n\n```typescript\nexport enum ToolCategory {\n WEBMCP = 'webmcp',\n INPUT = 'input',\n NAVIGATION = 'navigation',\n INSPECTION = 'inspection',\n}\n```\n\n## 测试与验证\n\n### 集成测试场景\n\n项目包含多个评估场景用于验证客户端集成：\n\n| 测试场景 | 路径 | 验证内容 |\n|---------|------|---------|\n| 性能测试 | `scripts/eval_scenarios/performance_test.ts` | 性能追踪工具调用 |\n| 快照测试 | `scripts/eval_scenarios/snapshot_test.ts` | 页面内容读取 |\n| 页面选择测试 | `scripts/eval_scenarios/select_page_test.ts` | 多页面上下文切换 |\n\n资料来源：[scripts/eval_scenarios/performance_test.ts:1-22]()\n\n### 测试执行命令\n\n```bash\nnpm run test # 运行所有测试\nnpm run test tests/McpContext.test.ts # 运行单个测试文件\n```\n\n资料来源：[AGENTS.md:5-7]()\n\n## 安全考虑\n\n### 对话框阻塞机制\n\n某些工具设置 `blockedByDialog: true`，在浏览器对话框出现时会被阻塞：\n\n```typescript\n{\n blockedByDialog: true, // 对话框会阻止此工具执行\n}\n```\n\n### 只读操作提示\n\n`readOnlyHint` 注解用于提示工具是否修改浏览器状态：\n\n```typescript\n{\n readOnlyHint: true, // 提示此工具仅读取数据\n}\n```\n\n## 相关文档\n\n- [安装指南](../skills/chrome-devtools-cli/references/installation.md) - CLI 安装与配置\n- [工具参考](../skills/chrome-devtools-cli/SKILL.md) - 所有工具完整文档\n- [无障碍调试](../skills/a11y-debugging/SKILL.md) - 可访问性检查集成\n- [性能优化](../skills/debug-optimize-lcp/SKILL.md) - LCP 调试集成\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：ChromeDevTools/chrome-devtools-mcp\n\n摘要：发现 18 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…。\n\n## 1. 配置坑 · 来源证据：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling — measurements come back partially or full…\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_644cef1d4144424abe63f24528f5d082 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1955 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3275fc356e284918a94cf8c2c037caee | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2004 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1946d257bfb04c23a67250da4d584631 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1943 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：chrome-devtools-mcp: v0.20.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chrome-devtools-mcp: v0.20.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_11700367e17048138ab79571d751cec4 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：chrome-devtools-mcp: v0.22.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chrome-devtools-mcp: v0.22.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6ff69eabdc334130b7b093706390c6c1 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：chrome-devtools-mcp: v0.21.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chrome-devtools-mcp: v0.21.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_41b2681dc7ae4bbabdb071511fdc0191 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.21.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：chrome-devtools-mcp: v0.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.20.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8bef6b0b7a80406ab00a0576f82b35a7 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 运行坑 · 来源证据：chrome-devtools-mcp: v0.24.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.24.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e42176fdf7da4015ac82844a46f37c08 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.24.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 运行坑 · 来源证据：chrome-devtools-mcp: v0.26.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.26.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6cf1fa6206f48e6a9e88a5d9d00fd64 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.26.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Close empty-object tool schemas for stricter MCP client validation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Close empty-object tool schemas for stricter MCP client validation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2af67f120a9d4486998a92da71a92cb9 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2049 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：chrome-devtools-mcp: v0.25.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：chrome-devtools-mcp: v0.25.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_51ee93809f08423dbc7b6c0d3eeddc77 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.25.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | issue_or_pr_quality=unknown\n\n## 18. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | release_recency=unknown\n\n\n",
"markdown_key": "chrome-devtools-mcp",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1054793726",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp"
},
{
"evidence_id": "art_a76aea3a129743bfabc951e284a6d049",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/ChromeDevTools/chrome-devtools-mcp#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "chrome-devtools-mcp 说明书",
"toc": [
"https://github.com/ChromeDevTools/chrome-devtools-mcp 项目说明书",
"目录",
"项目介绍",
"概述",
"核心架构",
"工具分类",
"核心概念",
"项目结构",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "dca3c04867b420fd811e178ce8fdd6eb703013c5",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"docs/cli.md",
"docs/troubleshooting.md",
"docs/third-party-developer-tools.md",
"docs/debugging-android.md",
"docs/design-principles.md",
"docs/slim-tool-reference.md",
"docs/tool-reference.md",
"src/HeapSnapshotManager.ts",
"src/logger.ts",
"src/PageCollector.ts",
"src/McpContext.ts",
"src/devtools.d.ts",
"src/version.ts",
"src/DevToolsConnectionAdapter.ts",
"src/issue-descriptions.ts",
"src/McpPage.ts",
"src/index.ts",
"src/types.ts",
"src/TextSnapshot.ts",
"src/McpResponse.ts",
"src/DevtoolsUtils.ts",
"src/SlimMcpResponse.ts",
"src/browser.ts",
"src/WaitForHelper.ts",
"src/polyfill.ts",
"src/Mutex.ts",
"src/ToolHandler.ts",
"src/bin/chrome-devtools-mcp-cli-options.ts",
"src/bin/chrome-devtools.ts",
"src/bin/chrome-devtools-mcp-main.ts",
"src/bin/check-latest-version.ts",
"src/bin/chrome-devtools-cli-options.ts",
"src/bin/chrome-devtools-mcp.ts",
"src/third_party/devtools-heap-snapshot-worker.ts",
"src/third_party/index.ts",
"src/third_party/lighthouse-devtools-mcp-bundle.js",
"src/third_party/devtools-formatter-worker.ts",
"src/telemetry/toolMetricsUtils.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# chrome-devtools-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 chrome-devtools-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`skills/a11y-debugging/SKILL.md`, `skills/chrome-devtools/SKILL.md`, `skills/chrome-devtools-cli/SKILL.md`, `skills/debug-optimize-lcp/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`skills/a11y-debugging/SKILL.md`, `skills/chrome-devtools/SKILL.md`, `skills/chrome-devtools-cli/SKILL.md`, `skills/debug-optimize-lcp/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.github/plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `/plugin marketplace add ChromeDevTools/chrome-devtools-mcp` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `/plugin install chrome-devtools-mcp@chrome-devtools-plugins` 证据：`README.md` Claim：`clm_0008` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`skills/a11y-debugging/SKILL.md`, `skills/chrome-devtools/SKILL.md`, `skills/chrome-devtools-cli/SKILL.md`, `skills/debug-optimize-lcp/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`skills/a11y-debugging/SKILL.md`, `skills/chrome-devtools/SKILL.md`, `skills/chrome-devtools-cli/SKILL.md`, `skills/debug-optimize-lcp/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.github/plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.github/plugin/plugin.json`, `AGENTS.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.github/plugin/plugin.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.github/plugin/plugin.json`, `AGENTS.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.github/plugin/plugin.json`, `README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0009` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.github/plugin/plugin.json` Claim：`clm_0010` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0011` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`skills/a11y-debugging/SKILL.md`, `skills/chrome-devtools/SKILL.md`, `skills/chrome-devtools-cli/SKILL.md`, `skills/debug-optimize-lcp/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.github/plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：257\n- 重要文件覆盖：40/257\n- 证据索引条目：80\n- 角色 / Skill 条目：6\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 chrome-devtools-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 chrome-devtools-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 chrome-devtools-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 6 个角色 / Skill / 项目文档条目。\n\n- **a11y-debugging**（skill）：Uses Chrome DevTools MCP for accessibility a11y debugging and auditing based on web.dev guidelines. Use when testing semantic HTML, ARIA labels, focus states, keyboard navigation, tap targets, and color contrast. 激活提示：当用户任务与“a11y-debugging”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/a11y-debugging/SKILL.md`\n- **chrome-devtools-cli**（skill）：Use this skill to write shell scripts or run shell commands to automate tasks in the browser or otherwise use Chrome DevTools via CLI. 激活提示：当用户任务与“chrome-devtools-cli”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/chrome-devtools-cli/SKILL.md`\n- **chrome-devtools**（skill）：Uses Chrome DevTools via MCP for efficient debugging, troubleshooting and browser automation. Use when debugging web pages, automating browser interactions, analyzing performance, or inspecting network requests. This skill does not apply to --slim mode MCP configuration . 激活提示：当用户任务与“chrome-devtools”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/chrome-devtools/SKILL.md`\n- **debug-optimize-lcp**（skill）：Guides debugging and optimizing Largest Contentful Paint LCP using Chrome DevTools MCP tools. Use this skill whenever the user asks about LCP performance, slow page loads, Core Web Vitals optimization, or wants to understand why their page's main content takes too long to appear. Also use when the user mentions \"largest contentful paint\", \"page load speed\", \"CWV\", or wants to improve how fast their hero image or mai… 激活提示：当用户任务与“debug-optimize-lcp”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/debug-optimize-lcp/SKILL.md`\n- **memory-leak-debugging**（skill）：Diagnoses and resolves memory leaks in JavaScript/Node.js applications. Use when a user reports high memory usage, OOM errors, or wants to analyze heapsnapshots or run memory leak detection tools like memlab. 激活提示：当用户任务与“memory-leak-debugging”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/memory-leak-debugging/SKILL.md`\n- **troubleshooting**（skill）：Uses Chrome DevTools MCP and documentation to troubleshoot connection and target issues. Trigger this skill when list pages, new page, or navigate page fail, or when the server initialization fails. 激活提示：当用户任务与“troubleshooting”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/troubleshooting/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Instructions**（documentation）：This repository contains an MCP server and CLI for Chrome DevTools. 证据：`AGENTS.md`\n- **Chrome DevTools for Agents**（documentation）：! npm chrome-devtools-mcp package https://img.shields.io/npm/v/chrome-devtools-mcp.svg https://npmjs.org/package/chrome-devtools-mcp 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"chrome-devtools-mcp\", \"version\": \"0.26.0\", \"description\": \"MCP server for Chrome DevTools\", \"type\": \"module\", \"bin\": { \"chrome-devtools-mcp\": \"./build/src/bin/chrome-devtools-mcp.js\", \"chrome-devtools\": \"./build/src/bin/chrome-devtools.js\" }, \"main\": \"./build/src/index.js\", \"scripts\": { \"cli:generate\": \"node --experimental-strip-types scripts/generate-cli.ts\", \"clean\": \"node -e \\\"require 'fs' .rmSync 'build', {recursive: true, force: true} \\\"\", \"bundle\": \"npm run clean && npm run build && rollup -c rollup.config.mjs && node -e \\\"require 'fs' .rmSync 'build/node modules', {recursive: true, force: true} \\\" && node --experimental-strip-types scripts/append-lighthouse-notices.ts\", \"b… 证据：`package.json`\n- **How to contribute**（documentation）：We'd love to accept your patches and contributions to this project. 证据：`CONTRIBUTING.md`\n- **Core Concepts**（skill_instruction）：Accessibility Tree vs DOM : Visually hiding an element e.g., CSS opacity: 0 behaves differently for screen readers than display: none or aria-hidden=\"true\" . The take snapshot tool returns the accessibility tree of the page, which represents what assistive technologies \"see\", making it the most reliable source of truth for semantic structure. 证据：`skills/a11y-debugging/SKILL.md`\n- **Setup**（skill_instruction）：The chrome-devtools-mcp CLI lets you interact with the browser from your terminal. 证据：`skills/chrome-devtools-cli/SKILL.md`\n- **Core Concepts**（skill_instruction）：Browser lifecycle : Browser starts automatically on first tool call using a persistent Chrome profile. Configure via CLI args in the MCP server configuration: npx chrome-devtools-mcp@latest --help . To enable extensions, use --categoryExtensions . Page selection : Tools operate on the currently selected page. Use list pages to see available pages, then select page to switch context. 证据：`skills/chrome-devtools/SKILL.md`\n- **What is LCP and why it matters**（skill_instruction）：Largest Contentful Paint LCP measures how quickly a page's main content becomes visible. It's the time from navigation start until the largest image or text block renders in the viewport. 证据：`skills/debug-optimize-lcp/SKILL.md`\n- **Memory Leak Debugging**（skill_instruction）：This skill provides expert guidance and workflows for finding, diagnosing, and fixing memory leaks in JavaScript and Node.js applications. 证据：`skills/memory-leak-debugging/SKILL.md`\n- **Troubleshooting Wizard**（skill_instruction）：You are acting as a troubleshooting wizard to help the user configure and fix their Chrome DevTools MCP server setup. When this skill is triggered e.g., because list pages , new page , or navigate page failed, or the server wouldn't start , follow this step-by-step diagnostic process: 证据：`skills/troubleshooting/SKILL.md`\n- **Marketplace**（structured_config）：{ \"name\": \"chrome-devtools-plugins\", \"version\": \"0.26.0\", \"description\": \"Bundled plugins for actuating and debugging the Chrome browser.\", \"repository\": \"https://github.com/ChromeDevTools/chrome-devtools-mcp\", \"owner\": { \"name\": \"Chrome DevTools Team\", \"email\": \"devtools-dev@chromium.org\" }, \"plugins\": { \"name\": \"chrome-devtools-mcp\", \"source\": \"./\", \"description\": \"Reliable automation, in-depth debugging, and performance analysis in Chrome using Chrome DevTools and Puppeteer\" } } 证据：`.claude-plugin/marketplace.json`\n- **Plugin**（structured_config）：{ \"name\": \"chrome-devtools-mcp\", \"version\": \"0.26.0\", \"description\": \"Reliable automation, in-depth debugging, and performance analysis in Chrome using Chrome DevTools and Puppeteer\", \"mcpServers\": { \"chrome-devtools\": { \"command\": \"npx\", \"args\": \"chrome-devtools-mcp@latest\" } } } 证据：`.claude-plugin/plugin.json`\n- **Plugin**（structured_config）：{ \"name\": \"chrome-devtools-mcp\", \"version\": \"0.26.0\", \"description\": \"Reliable automation, in-depth debugging, and performance analysis in Chrome using Chrome DevTools and Puppeteer\", \"mcpServers\": { \"chrome-devtools\": { \"command\": \"npx\", \"args\": \"chrome-devtools-mcp@latest\" } } } 证据：`.github/plugin/plugin.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Chrome DevTools CLI**（documentation）：The chrome-devtools-mcp package includes an experimental CLI interface that allows you to interact with the browser directly from your terminal. This is particularly useful for debugging or when you want an agent to generate scripts that automate browser actions. 证据：`docs/cli.md`\n- **Experimental: Debugging Chrome on Android**（documentation）：Experimental: Debugging Chrome on Android 证据：`docs/debugging-android.md`\n- **Design Principles**（documentation）：These are rough guidelines to follow when shipping features for the MCP server. Apply them with nuance. 证据：`docs/design-principles.md`\n- **Chrome DevTools MCP Slim Tool Reference**（documentation）：Chrome DevTools MCP Slim Tool Reference 证据：`docs/slim-tool-reference.md`\n- **Developer Guide: Building third-party developer tools**（documentation）：Developer Guide: Building third-party developer tools 证据：`docs/third-party-developer-tools.md`\n- **Chrome DevTools MCP Tool Reference**（documentation）：- Input automation input-automation 10 tools - click click - drag drag - fill fill - fill form fill form - handle dialog handle dialog - hover hover - press key press key - type text type text - upload file upload file - click at click at - Navigation automation navigation-automation 6 tools - close page close page - list pages list pages - navigate page navigate page - new page new page - select page select page - wait for wait for - Emulation emulation 2 tools - emulate emulate - resize page resize page - Performance performance 3 tools - performance analyze insight performance analyze insight - performance start trace performance start trace - performance stop trace performance stop trac… 证据：`docs/tool-reference.md`\n- **Troubleshooting**（documentation）：- Run npx chrome-devtools-mcp@latest --help to test if the MCP server runs on your machine. - Make sure that your MCP client uses the same npm and node version as your terminal. - When configuring your MCP client, try using the --yes argument to npx to auto-accept installation prompt. - Find a specific error in the output of the chrome-devtools-mcp server. Usually, if your client is an IDE, logs would be in the Output pane. - Search the GitHub repository issues and discussions https://github.com/ChromeDevTools/chrome-devtools-mcp for help or existing similar problems. 证据：`docs/troubleshooting.md`\n- **Changelog**（documentation）：0.26.0 https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.25.0...chrome-devtools-mcp-v0.26.0 2026-05-11 证据：`CHANGELOG.md`\n- **Security policy**（documentation）：The Chrome DevTools MCP project takes security very seriously. Please use Chromium’s process to report security issues https://www.chromium.org/Home/chromium-security/reporting-security-bugs/ . 证据：`SECURITY.md`\n- **Accessibility Debugging Snippets**（documentation）：Use these JavaScript snippets with the evaluate script tool. 证据：`skills/a11y-debugging/references/a11y-snippets.md`\n- **Installation**（documentation）：Install the package globally to make the chrome-devtools command available. You only need to do this the first time you use it. 证据：`skills/chrome-devtools-cli/references/installation.md`\n- **Elements and Size for LCP**（documentation）：The types of elements considered for Largest Contentful Paint LCP are: 证据：`skills/debug-optimize-lcp/references/elements-and-size.md`\n- **Largest Contentful Paint LCP Breakdown**（documentation）：Largest Contentful Paint LCP Breakdown 证据：`skills/debug-optimize-lcp/references/lcp-breakdown.md`\n- **LCP Debugging Snippets**（documentation）：Use these JavaScript snippets with the evaluate script tool to extract deep insights from the page. 证据：`skills/debug-optimize-lcp/references/lcp-snippets.md`\n- **LCP Optimization Strategies**（documentation）：Goal : Ensure the LCP resource starts loading as early as possible. 证据：`skills/debug-optimize-lcp/references/optimization-strategies.md`\n- **Common Memory Leaks**（documentation）：When analyzing a retainer trace from memlab , look for these common patterns in the codebase: 证据：`skills/memory-leak-debugging/references/common-leaks.md`\n- **Using Memlab**（documentation）：Memlab https://facebook.github.io/memlab/ is an E2E testing and analysis framework for finding JavaScript memory leaks. 证据：`skills/memory-leak-debugging/references/memlab.md`\n- **Settings**（structured_config）：{ \"context\": { \"fileName\": \"AGENTS.md\", \"GEMINI.md\" } } 证据：`.gemini/settings.json`\n- **.Mcp**（structured_config）：{ \"mcpServers\": { \"chrome-devtools\": { \"command\": \"npx\", \"args\": \"chrome-devtools-mcp@latest\" } } } 证据：`.mcp.json`\n- **.Release Please Manifest**（structured_config）：{ \".\": \"0.26.0\" } 证据：`.release-please-manifest.json`\n- **Gemini Extension**（structured_config）：{ \"name\": \"chrome-devtools-mcp\", \"version\": \"latest\", \"mcpServers\": { \"chrome-devtools\": { \"command\": \"npx\", \"args\": \"chrome-devtools-mcp@latest\" } } } 证据：`gemini-extension.json`\n- **Release Please Config**（structured_config）：{ \"changelog-sections\": {\"type\": \"feat\", \"section\": \"🎉 Features\", \"hidden\": false}, {\"type\": \"fix\", \"section\": \"🛠️ Fixes\", \"hidden\": false}, {\"type\": \"docs\", \"section\": \"📄 Documentation\", \"hidden\": false}, 证据：`release-please-config.json`\n- **Tsconfig**（structured_config）：{ \"extends\": \"../tsconfig.json\", \"compilerOptions\": { \"target\": \"esnext\", \"module\": \"nodenext\", \"moduleResolution\": \"nodenext\", \"outDir\": \"./ignored\", \"rootDir\": \".\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"noImplicitReturns\": true, \"noImplicitOverride\": true, \"noFallthroughCasesInSwitch\": true, \"incremental\": true, \"allowJs\": true, \"allowImportingTsExtensions\": true, \"noEmit\": true, \"useUnknownInCatchVariables\": false }, \"include\": \"./ / .ts\", \"./ / .js\", \"./ / .mjs\" } 证据：`scripts/tsconfig.json`\n- **Server**（structured_config）：{ \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\", \"name\": \"io.github.ChromeDevTools/chrome-devtools-mcp\", \"title\": \"Chrome DevTools MCP\", \"description\": \"MCP server for Chrome DevTools\", \"repository\": { \"url\": \"https://github.com/ChromeDevTools/chrome-devtools-mcp\", \"source\": \"github\" }, \"version\": \"0.26.0\", \"packages\": { \"registryType\": \"npm\", \"registryBaseUrl\": \"https://registry.npmjs.org\", \"identifier\": \"chrome-devtools-mcp\", \"version\": \"0.26.0\", \"transport\": { \"type\": \"stdio\" }, \"environmentVariables\": } } 证据：`server.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"es2023\", \"lib\": \"ES2023\", \"DOM\", \"ES2024.Promise\", \"ESNext.Iterator\", \"ESNext.Collection\" , \"types\": \"node\", \"filesystem\" , \"moduleResolution\": \"bundler\", \"outDir\": \"./build\", \"rootDir\": \".\", \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"noImplicitReturns\": true, \"noImplicitOverride\": true, \"noFallthroughCasesInSwitch\": true, \"incremental\": true, \"sourceMap\": true, \"allowJs\": true, \"useUnknownInCatchVariables\": false }, \"include\": \"src/ / .ts\", \"tests/ / .ts\", \"node modules/chrome-devtools-frontend/front end/core/common\", \"node modules/chrome-devtools-frontend/front end/core/host\", \"node modules/chrome-devtools-fr… 证据：`tsconfig.json`\n- **Flag Usage Metrics**（structured_config）：{ \"name\": \"browser url present\", \"flagType\": \"boolean\" }, { \"name\": \"headless\", \"flagType\": \"boolean\" }, { \"name\": \"executable path present\", \"flagType\": \"boolean\" }, { \"name\": \"isolated\", \"flagType\": \"boolean\" }, { \"name\": \"channel\", \"flagType\": \"enum\", \"choices\": \"CHANNEL UNSPECIFIED\", \"CHANNEL CANARY\", \"CHANNEL DEV\", \"CHANNEL BETA\", \"CHANNEL STABLE\" }, { \"name\": \"log file present\", \"flagType\": \"boolean\" }, { \"name\": \"accept insecure certs present\", \"flagType\": \"boolean\" }, { \"name\": \"accept insecure certs\", \"flagType\": \"boolean\" }, { \"name\": \"auto connect present\", \"flagType\": \"boolean\" }, { \"name\": \"auto connect\", \"flagType\": \"boolean\" }, { \"name\": \"category emulation present\", \"flagTyp… 证据：`src/telemetry/flag_usage_metrics.json`\n- **Tool Call Metrics**（structured_config）：{ \"name\": \"click\", \"args\": { \"name\": \"dbl click\", \"argType\": \"boolean\" }, { \"name\": \"include snapshot\", \"argType\": \"boolean\" } }, { \"name\": \"click at\", \"args\": { \"name\": \"x\", \"argType\": \"number\" }, { \"name\": \"y\", \"argType\": \"number\" }, { \"name\": \"dbl click\", \"argType\": \"boolean\" }, { \"name\": \"include snapshot\", \"argType\": \"boolean\" } }, { \"name\": \"close page\", \"args\": { \"name\": \"page id\", \"argType\": \"number\" } }, { \"name\": \"drag\", \"args\": { \"name\": \"from uid length\", \"argType\": \"number\" }, { \"name\": \"to uid length\", \"argType\": \"number\" }, { \"name\": \"include snapshot\", \"argType\": \"boolean\" } }, { \"name\": \"emulate\", \"args\": { \"name\": \"network conditions\", \"argType\": \"string\" }, { \"name\": \"cpu… 证据：`src/telemetry/tool_call_metrics.json`\n- **Manifest**（structured_config）：{ \"manifest version\": 3, \"name\": \"Test Extension with Content Script\", \"version\": \"1.0\", \"permissions\": \"tabs\", \"scripting\" , \"host permissions\": \" \" , \"content scripts\": { \"matches\": \" \" , \"js\": \"content.js\" , \"run at\": \"document start\", \"all frames\": true } } 证据：`tests/tools/fixtures/extension-content-script/manifest.json`\n- **Manifest**（structured_config）：{ \"name\": \"Test Extension Side Panel\", \"version\": \"1.0.0\", \"manifest version\": 3, \"permissions\": \"sidePanel\" , \"action\": { \"default title\": \"Click to open panel\" }, \"background\": { \"service worker\": \"sw.js\" }, \"side panel\": { \"default path\": \"sidepanel.html\" } } 证据：`tests/tools/fixtures/extension-side-panel/manifest.json`\n- **Manifest**（structured_config）：{ \"manifest version\": 3, \"name\": \"Test Extension with SW\", \"version\": \"1.0\", \"background\": { \"service worker\": \"sw.js\" }, \"action\": { \"default popup\": \"popup.html\" } } 证据：`tests/tools/fixtures/extension-sw/manifest.json`\n- **Manifest**（structured_config）：{ \"manifest version\": 3, \"name\": \"Test Extension\", \"version\": \"1.0\", \"action\": { \"default popup\": \"popup.html\" } } 证据：`tests/tools/fixtures/extension/manifest.json`\n- **.gitattributes**（source_file）：text=auto eol=lf 证据：`.gitattributes`\n- **breaks often so better to roll separetely.**（source_file）：version: 2 updates: - package-ecosystem: npm directory: / schedule: interval: weekly day: 'sunday' time: '02:00' timezone: Europe/Berlin groups: dependencies: dependency-type: production patterns: - ' ' dev-dependencies: dependency-type: development exclude-patterns: - 'puppeteer ' - 'chrome-devtools-frontend' - '@modelcontextprotocol/sdk' - 'yargs' - 'debug' - 'core-js' patterns: - ' ' breaks often so better to roll separetely. bundled-devtools: patterns: - 'chrome-devtools-frontend' bundled: patterns: - 'puppeteer ' - '@modelcontextprotocol/sdk' - 'yargs' - 'debug' - 'core-js' - package-ecosystem: github-actions directory: / schedule: interval: weekly day: 'sunday' time: '04:00' timezone:… 证据：`.github/dependabot.yml`\n- **Logs**（source_file）：Logs logs .log npm-debug.log yarn-debug.log yarn-error.log lerna-debug.log .pnpm-debug.log 证据：`.gitignore`\n- **.npmrc**（source_file）：package-lock=true 证据：`.npmrc`\n- **.nvmrc**（source_file）：v24 证据：`.nvmrc`\n- **Prettier-only ignores.**（source_file）：Prettier-only ignores. CHANGELOG.md src/third party/lighthouse-devtools-mcp-bundle.js 证据：`.prettierignore`\n- **.Prettierrc**（source_file）：/ @license Copyright 2025 Google LLC SPDX-License-Identifier: Apache-2.0 / 证据：`.prettierrc.cjs`\n- **Eslint.Config**（source_file）：/ @license Copyright 2025 Google LLC SPDX-License-Identifier: Apache-2.0 / 证据：`eslint.config.mjs`\n- **Puppeteer.Config**（source_file）：/ @license Copyright 2025 Google Inc. SPDX-License-Identifier: Apache-2.0 / 证据：`puppeteer.config.cjs`\n- **Rollup.Config**（source_file）：/ Copyright 2021 Google LLC. Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / 证据：`rollup.config.mjs`\n- **Append Lighthouse Notices**（source_file）：/ @license Copyright 2026 Google LLC SPDX-License-Identifier: Apache-2.0 / 证据：`scripts/append-lighthouse-notices.ts`\n- **Count Tokens**（source_file）：/ @license Copyright 2026 Google LLC SPDX-License-Identifier: Apache-2.0 / 证据：`scripts/count_tokens.ts`\n- **Eval Gemini**（source_file）：/ @license Copyright 2026 Google LLC SPDX-License-Identifier: Apache-2.0 / 证据：`scripts/eval_gemini.ts`\n- **Generate Cli**（source_file）：/ @license Copyright 2026 Google LLC SPDX-License-Identifier: Apache-2.0 / 证据：`scripts/generate-cli.ts`\n- **${title}**（source_file）：/ @license Copyright 2025 Google LLC SPDX-License-Identifier: Apache-2.0 / 证据：`scripts/generate-docs.ts`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`AGENTS.md`, `README.md`, `package.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`AGENTS.md`, `README.md`, `package.json`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, src/index.ts, package.json\n- **快速开始指南**：importance `high`\n - source_paths: README.md, src/bin/chrome-devtools-mcp.ts\n- **系统架构**：importance `high`\n - source_paths: src/index.ts, src/McpPage.ts, src/McpContext.ts, src/ToolHandler.ts, src/browser.ts\n- **守护进程系统**：importance `medium`\n - source_paths: src/daemon/daemon.ts, src/daemon/client.ts, src/daemon/types.ts, src/daemon/utils.ts\n- **工具参考**：importance `high`\n - source_paths: src/tools/tools.ts, src/tools/ToolDefinition.ts, src/tools/categories.ts, docs/tool-reference.md\n- **输入自动化工具**：importance `high`\n - source_paths: src/tools/input.ts, src/tools/pages.ts, src/utils/keyboard.ts\n- **性能分析工具**：importance `high`\n - source_paths: src/tools/performance.ts, src/tools/lighthouse.ts, src/trace-processing/parse.ts\n- **内存调试工具**：importance `medium`\n - source_paths: src/tools/memory.ts, src/HeapSnapshotManager.ts, src/formatters/HeapSnapshotFormatter.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `dca3c04867b420fd811e178ce8fdd6eb703013c5`\n- inspected_files: `package.json`, `README.md`, `docs/cli.md`, `docs/troubleshooting.md`, `docs/third-party-developer-tools.md`, `docs/debugging-android.md`, `docs/design-principles.md`, `docs/slim-tool-reference.md`, `docs/tool-reference.md`, `src/HeapSnapshotManager.ts`, `src/logger.ts`, `src/PageCollector.ts`, `src/McpContext.ts`, `src/devtools.d.ts`, `src/version.ts`, `src/DevToolsConnectionAdapter.ts`, `src/issue-descriptions.ts`, `src/McpPage.ts`, `src/index.ts`, `src/types.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling — measurements come back partially or full…\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_644cef1d4144424abe63f24528f5d082 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1955 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3275fc356e284918a94cf8c2c037caee | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2004 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_1946d257bfb04c23a67250da4d584631 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1943 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：chrome-devtools-mcp: v0.20.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chrome-devtools-mcp: v0.20.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_11700367e17048138ab79571d751cec4 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：chrome-devtools-mcp: v0.22.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chrome-devtools-mcp: v0.22.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_6ff69eabdc334130b7b093706390c6c1 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：chrome-devtools-mcp: v0.21.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chrome-devtools-mcp: v0.21.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_41b2681dc7ae4bbabdb071511fdc0191 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.21.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：chrome-devtools-mcp: v0.20.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.20.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8bef6b0b7a80406ab00a0576f82b35a7 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：chrome-devtools-mcp: v0.24.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.24.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e42176fdf7da4015ac82844a46f37c08 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.24.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：chrome-devtools-mcp: v0.26.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.26.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a6cf1fa6206f48e6a9e88a5d9d00fd64 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.26.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：ChromeDevTools/chrome-devtools-mcp\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：chrome-devtools-mcp: v0.20.1（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：chrome-devtools-mcp: v0.22.0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/ChromeDevTools/chrome-devtools-mcp 项目说明书\n\n生成时间：2026-05-13 09:07:08 UTC\n\n## 目录\n\n- [项目介绍](#project-introduction)\n- [快速开始指南](#quick-start)\n- [系统架构](#system-architecture)\n- [守护进程系统](#daemon-system)\n- [工具参考](#tool-reference)\n- [输入自动化工具](#input-automation)\n- [性能分析工具](#performance-tools)\n- [内存调试工具](#memory-debugging)\n- [CLI与配置](#cli-configuration)\n- [MCP客户端集成](#mcp-client-integration)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [快速开始指南](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/README.md)\n- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n- [package.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/package.json)\n- [src/index.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/index.ts)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n- [src/PageCollector.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/PageCollector.ts)\n- [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n- [skills/a11y-debugging/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/a11y-debugging/SKILL.md)\n \n\n# 项目介绍\n\n## 概述\n\nchrome-devtools-mcp 是一个基于 Model Context Protocol (MCP) 的 Chrome DevTools 服务器和命令行工具。该项目由 Google Chrome 团队维护，提供了一套完整的浏览器自动化、调试和性能分析能力。资料来源：[AGENTS.md]()\n\n项目的主要目标是让开发者能够通过 MCP 协议与 Chrome 浏览器进行交互，实现网页自动化、元素操作、性能分析、无障碍调试等功能。资料来源：[skills/chrome-devtools/SKILL.md]()\n\n## 核心架构\n\n### 技术栈\n\n| 组件 | 技术 | 说明 |\n|------|------|------|\n| 运行时 | Node.js / TypeScript | 使用严格类型检查 |\n| 协议 | MCP (Model Context Protocol) | 与 AI 模型交互的标准协议 |\n| 浏览器控制 | Puppeteer | Chrome DevTools Protocol 封装 |\n| 验证 | Zod | Schema 验证库 |\n\n资料来源：[package.json]()\n\n### 架构图\n\n```mermaid\ngraph TB\n subgraph \"客户端层\"\n AI[AI 模型 / Claude]\n CLI[CLI 工具]\n end\n \n subgraph \"MCP 协议层\"\n MCPServer[MCP Server]\n Protocol[MCP Protocol]\n end\n \n subgraph \"工具层\"\n Navigation[导航工具]\n Performance[性能工具]\n A11y[无障碍工具]\n Interaction[交互工具]\n Network[网络工具]\n WebMCP[WebMCP 工具]\n end\n \n subgraph \"浏览器层\"\n CDP[Chrome DevTools Protocol]\n Chrome[Chrome Browser]\n end\n \n AI --> MCPServer\n CLI --> MCPServer\n MCPServer --> Protocol\n Protocol --> Navigation\n Protocol --> Performance\n Protocol --> A11y\n Protocol --> Interaction\n Protocol --> Network\n Protocol --> WebMCP\n \n Navigation --> CDP\n Performance --> CDP\n A11y --> CDP\n Interaction --> CDP\n Network --> CDP\n WebMCP --> CDP\n \n CDP --> Chrome\n```\n\n## 工具分类\n\n### 导航工具 (Navigation)\n\n| 工具名称 | 功能 | 页面作用域 |\n|---------|------|-----------|\n| `new_page` | 创建新页面 | 是 |\n| `navigate_page` | 导航到指定 URL | 是 |\n| `select_page` | 选择目标页面作为上下文 | 是 |\n| `close_page` | 关闭指定页面 | 是 |\n| `list_pages` | 列出所有打开的页面 | 否 |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md]()\n\n### 性能工具 (Performance)\n\n| 工具名称 | 功能 |\n|---------|------|\n| `performance_start_trace` | 开始性能追踪录制 |\n| `performance_stop_trace` | 停止性能追踪录制 |\n| `take_memory_snapshot` | 捕获内存堆快照 |\n| `performance_analyze_insight` | 获取性能洞察详情 |\n\n资料来源：[skills/debug-optimize-lcp/SKILL.md]()\n\n### 无障碍调试工具 (Accessibility)\n\n| 工具名称 | 功能 |\n|---------|------|\n| `take_snapshot` | 获取页面快照和可访问性树 |\n| `lighthouse_audit` | 运行 Lighthouse 无障碍审计 |\n| `evaluate_script` | 执行 JavaScript 脚本 |\n\n资料来源：[skills/a11y-debugging/SKILL.md]()\n\n### 元素交互工具 (Interaction)\n\n| 工具名称 | 功能 |\n|---------|------|\n| `click` | 点击元素 |\n| `fill` / `fill_form` | 填充表单 |\n| `type_text` | 键盘输入文本 |\n| `press_key` | 按下按键 |\n| `upload_file` | 上传文件 |\n| `take_screenshot` | 截图 |\n\n资料来源：[skills/chrome-devtools/SKILL.md]()\n\n### 网络工具 (Network)\n\n| 工具名称 | 功能 |\n|---------|------|\n| `network_start_monitoring` | 开始网络监控 |\n| `network_stop_monitoring` | 停止网络监控 |\n| `get_network_requests` | 获取网络请求列表 |\n\n### WebMCP 工具\n\nWebMCP 允许与网页暴露的工具进行交互：\n\n| 工具名称 | 功能 |\n|---------|------|\n| `list_webmcp_tools` | 列出页面暴露的所有 WebMCP 工具 |\n| `execute_webmcp_tool` | 执行指定的 WebMCP 工具 |\n\n资料来源：[src/tools/webmcp.ts]()\n\n### 模拟工具 (Emulation)\n\n| 工具名称 | 功能 |\n|---------|------|\n| `emulate` | 模拟网络条件、CPU 节流、地理位置、配色方案、视口大小 |\n| `resize_page` | 调整页面窗口大小 |\n| `emulate_user_agent` | 模拟用户代理 |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md]()\n\n## 核心概念\n\n### 页面作用域 (Page Scoped)\n\n工具分为两类：\n\n1. **页面作用域工具**：需要先选择目标页面才能使用\n2. **全局工具**：可随时调用，不需要选择页面\n\n```typescript\nexport function definePageTool(\n definition: PageToolDefinition,\n): DefinedPageTool;\n```\n\n资料来源：[src/tools/ToolDefinition.ts:1-100]()\n\n### 浏览器生命周期\n\n浏览器会在第一次工具调用时自动启动，使用持久化的 Chrome 配置文件。要启用扩展支持，需要在 MCP 服务器配置中添加 `--categoryExtensions` 参数。资料来源：[skills/chrome-devtools/SKILL.md]()\n\n### 元素唯一标识 (UID)\n\n每个页面元素都有唯一的 `uid` 标识符，用于交互操作。获取 UID 的方式是使用 `take_snapshot` 工具获取页面结构。资料来源：[skills/chrome-devtools/SKILL.md]()\n\n## 项目结构\n\n```\nchrome-devtools-mcp/\n├── src/\n│ ├── index.ts # 入口文件\n│ ├── tools/ # 工具定义\n│ │ ├── ToolDefinition.ts # 基础工具定义\n│ │ ├── webmcp.ts # WebMCP 工具\n│ │ └── ...\n│ ├── PageCollector.ts # 页面收集器\n│ └── ...\n├── skills/ # 技能文档\n│ ├── chrome-devtools/ # 核心 DevTools 技能\n│ ├── chrome-devtools-cli/ # CLI 技能\n│ ├── a11y-debugging/ # 无障碍调试技能\n│ └── debug-optimize-lcp/ # LCP 优化技能\n├── scripts/ # 脚本\n│ └── generate-docs.ts # 文档生成\n└── package.json\n```\n\n## 快速开始\n\n### 安装\n\n```bash\nnpm i chrome-devtools-mcp@latest -g\nchrome-devtools status # 验证安装\n```\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md]()\n\n### 常用命令\n\n| 命令 | 说明 |\n|------|------|\n| `npm run build` | 编译 TypeScript 并测试构建 |\n| `npm run test` | 运行所有测试 |\n| `npm run test ` | 运行单个测试文件 |\n| `npm run format` | 修复格式和获取 linting 错误 |\n| `npm run gen` | 生成文档 |\n\n资料来源：[AGENTS.md]()\n\n### 基本工作流程\n\n```mermaid\ngraph LR\n A[导航页面] --> B[等待内容加载]\n B --> C[获取快照]\n C --> D[获取元素 UID]\n D --> E[执行交互操作]\n```\n\n## 开发规范\n\n### TypeScript 规范\n\n项目采用严格的 TypeScript 规范：\n\n| 规则 | 说明 |\n|------|------|\n| 禁止使用 `any` 类型 | 必须使用具体类型 |\n| 禁止使用 `as` 类型转换 | 使用类型守卫或泛型 |\n| 禁止使用 `!` 断言 | 使用显式检查 |\n| 禁止使用 `// @ts-ignore` | 必须修复类型问题 |\n| 优先使用 `for..of` | 避免使用 `forEach` |\n\n资料来源：[AGENTS.md]()\n\n### 工具定义模式\n\n```typescript\nexport function definePageTool(\n definition: PageToolDefinition,\n): DefinedPageTool {\n return {\n ...definition,\n pageScoped: true,\n } as DefinedPageTool;\n}\n```\n\n资料来源：[src/tools/ToolDefinition.ts]()\n\n## 技能系统\n\n项目包含多个专业技能模块：\n\n| 技能名称 | 用途 | 使用场景 |\n|---------|------|---------|\n| `chrome-devtools` | 核心浏览器操作 | 调试网页、自动化交互、性能分析 |\n| `chrome-devtools-cli` | 命令行操作 | 页面导航、网络模拟、元素操作 |\n| `a11y-debugging` | 无障碍调试 | 检测 ARIA 标签、焦点管理、键盘导航 |\n| `debug-optimize-lcp` | LCP 优化 | 优化最大内容绘制性能 |\n\n## 扩展机制\n\n### MCP 服务器扩展\n\n可以通过 CLI 参数扩展 MCP 服务器功能：\n\n```bash\nnpx chrome-devtools-mcp@latest --categoryExtensions\n```\n\n### WebMCP 扩展\n\n网页可以暴露自定义工具供 MCP 调用，实现双向通信。资料来源：[src/tools/webmcp.ts]()\n\n## 常见用例\n\n### 自动化测试场景\n\n```typescript\n// 场景：导航 -> 截图 -> 检查元素\nconst calls = [\n { name: 'navigate_page', url: 'https://example.com' },\n { name: 'take_screenshot' },\n { name: 'take_snapshot' }\n];\n```\n\n资料来源：[scripts/eval_scenarios/snapshot_test.ts]()\n\n### 性能分析场景\n\n```typescript\n// 场景：导航 -> 开始性能追踪\nconst calls = [\n { name: 'navigate_page', url: 'https://developers.chrome.com' },\n { name: 'performance_start_trace' }\n];\n```\n\n资料来源：[scripts/eval_scenarios/performance_test.ts]()\n\n### LCP 优化场景\n\nLCP (最大内容绘制) 优化包括以下关键策略：\n\n1. **消除资源加载延迟**：使用预加载、避免懒加载、设置 fetchpriority\n2. **消除元素渲染延迟**：内联关键 CSS、拆分长任务、减少渲染阻塞\n3. **减少资源加载时长**：使用现代图片格式、CDN 加速\n4. **降低 TTFB**：减少重定向、优化服务器响应、使用边缘缓存\n\n资料来源：[skills/debug-optimize-lcp/SKILL.md]()\n\n## 页面管理\n\n### PageCollector 机制\n\n```mermaid\ngraph TB\n subgraph \"PageCollector\"\n Storage[(WeakMap<Page, Array<NavigationData>>)]\n end\n \n subgraph \"事件监听\"\n Created[targetcreated]\n Destroyed[targetdestroyed]\n end\n \n Created -->|新页面| Add[addPage]\n Destroyed -->|页面关闭| Remove[removePage]\n \n Add --> Storage\n Remove --> Storage\n```\n\n`PageCollector` 使用 `WeakMap` 存储每个页面的导航历史和资源数据，较新的导航记录排在前面。资料来源：[src/PageCollector.ts]()\n\n## 配置与扩展\n\n### CLI 参数\n\n| 参数 | 说明 |\n|------|------|\n| `--help` | 显示帮助信息 |\n| `--categoryExtensions` | 启用扩展支持 |\n| `--port` | 指定端口号 |\n\n### 工具注解\n\n工具可以通过注解系统标记元信息：\n\n```typescript\nannotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: true,\n conditions: ['networkIdle']\n}\n```\n\n资料来源：[scripts/generate-docs.ts]()\n\n## 总结\n\nchrome-devtools-mcp 项目提供了一套完整的 Chrome DevTools 自动化解决方案，通过 MCP 协议实现了与 AI 模型的深度集成。项目具有以下特点：\n\n- **模块化设计**：工具按功能分类，易于扩展和维护\n- **严格类型安全**：TypeScript 规范确保代码质量\n- **丰富的调试能力**：支持性能分析、无障碍调试、LCP 优化等专业领域\n- **灵活的工作流程**：支持页面管理、元素交互、网络模拟等多种操作\n- **双向扩展机制**：既支持 MCP 协议扩展，也支持 WebMCP 网页扩展\n\n---\n\n\n\n## 快速开始指南\n\n### 相关页面\n\n相关主题：[MCP客户端集成](#mcp-client-integration), [CLI与配置](#cli-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/README.md)\n- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n- [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n- [skills/chrome-devtools-cli/references/installation.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/references/installation.md)\n \n\n# 快速开始指南\n\n## 概述\n\nchrome-devtools-mcp 是一个 Chrome DevTools MCP（Model Context Protocol）服务器和命令行工具，提供对浏览器自动化、页面调试、性能分析和网络监控的全面控制。该项目允许开发者通过 MCP 协议与 Chrome DevTools Protocol 进行交互，实现高效的浏览器自动化和调试工作流。\n\n本指南将帮助用户快速上手该工具，涵盖从安装配置到基本操作的全流程。\n\n## 系统架构\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[用户/Agent] --> B[MCP 客户端]\n B --> C[chrome-devtools-mcp 服务器]\n C --> D[Chrome DevTools Protocol]\n D --> E[浏览器实例]\n F[chrome-devtools CLI] --> C\n```\n\n### 核心模块\n\n| 模块 | 路径 | 功能描述 |\n|------|------|----------|\n| MCP 服务器 | `src/bin/chrome-devtools-mcp.ts` | 核心服务进程，处理 MCP 协议通信 |\n| 工具定义 | `src/tools/` | 各类浏览器操作工具的实现 |\n| 响应处理 | `src/McpResponse.ts` | MCP 响应格式化与数据处理 |\n\n资料来源：[AGENTS.md:1-5]()\n\n## 环境要求\n\n### 必要条件\n\n- **Node.js**: 需要 Node.js 运行时环境\n- **npm**: 用于包管理和脚本执行\n- **Chrome 浏览器**: 支持本地安装的 Chrome 或 Chromium\n\n### 安装步骤\n\n#### 全局安装\n\n```bash\nnpm i chrome-devtools-mcp@latest -g\n```\n\n安装完成后，`chrome-devtools` 命令将全局可用。\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:3-7]()\n\n#### 验证安装\n\n```bash\nchrome-devtools status\n```\n\n该命令用于检查安装是否成功。\n\n## 基本命令\n\n### 启动 MCP 服务器\n\n```bash\nnpx chrome-devtools-mcp@latest [选项]\n```\n\n### 查看帮助信息\n\n```bash\nchrome-devtools --help\n```\n\n## 工作流程模式\n\n### 标准操作流程\n\n```mermaid\ngraph LR\n A[导航页面] --> B[等待加载]\n B --> C[获取快照]\n C --> D[元素交互]\n D --> E{是否完成}\n E -->|否| B\n E -->|是| F[结束]\n```\n\n### 页面交互前准备\n\n1. **导航**: 使用 `navigate_page` 或 `new_page` 访问目标页面\n2. **等待**: 使用 `wait_for` 确保内容加载完成\n3. **快照**: 使用 `take_snapshot` 获取页面结构\n4. **交互**: 使用快照中的元素 `uid` 进行操作\n\n资料来源：[skills/chrome-devtools/SKILL.md:14-24]()\n\n## 常用工具\n\n### 页面管理\n\n| 工具 | 功能 | 参数 |\n|------|------|------|\n| `new_page` | 创建新页面 | `url`, `--background`, `--timeout`, `--isolatedContext` |\n| `navigate_page` | 导航到 URL | `url`, `--type`, `--timeout`, `--initScript` |\n| `list_pages` | 列出所有页面 | 无 |\n| `select_page` | 选择目标页面 | `pageId`, `--bringToFront` |\n| `close_page` | 关闭页面 | `pageId` |\n\n### 元素交互\n\n| 工具 | 功能 | 常用参数 |\n|------|------|----------|\n| `click` | 点击元素 | `uid`, `--includeSnapshot` |\n| `fill` | 填充输入框 | `uid`, `text`, `--submitKey` |\n| `hover` | 悬停元素 | `uid` |\n| `take_snapshot` | 获取页面快照 | `--filePath`, `--includeSnapshot` |\n| `take_screenshot` | 截图 | `--filePath` |\n\n### 键盘操作\n\n```bash\nchrome-devtools press_key \"Enter\" # 按下指定按键\nchrome-devtools type_text \"hello\" # 输入文本\nchrome-devtools type_text \"hello\" --submitKey \"Enter\" # 输入并提交\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:1-35]()\n\n### 文件上传\n\n```bash\nchrome-devtools upload_file \"element-id\" \"file.txt\"\nchrome-devtools upload_file \"element-id\" \"file.txt\" --includeSnapshot true\n```\n\n## 性能分析\n\n### 性能追踪\n\n```mermaid\ngraph TD\n A[开始追踪] --> B[performance_start_trace]\n B --> C[执行业务操作]\n C --> D[停止追踪]\n D --> E[performance_stop_trace]\n E --> F[分析结果]\n F --> G[LCPBreakdown]\n F --> H[其他指标]\n```\n\n### 性能工具\n\n| 工具 | 功能 |\n|------|------|\n| `performance_start_trace` | 开始性能追踪 |\n| `performance_stop_trace` | 停止追踪并保存 |\n| `performance_analyze_insight` | 分析具体性能指标 |\n| `take_memory_snapshot` | 捕获内存堆快照 |\n\n```bash\n# 基础追踪\nchrome-devtools performance_start_trace true false\n\n# 带文件保存的追踪\nchrome-devtools performance_start_trace true true --filePath trace.gz\n\n# 停止并保存\nchrome-devtools performance_stop_trace --filePath \"result.json\"\n```\n\n## 网络监控\n\n### 网络请求检查\n\n```bash\nchrome-devtools network_requests # 查看网络请求列表\n```\n\n网络请求工具可配置：\n- `include`: 是否包含请求详情\n- `pagination`: 分页配置（`pageIdx`, `pageSize`）\n\n资料来源：[src/McpResponse.ts:50-75]()\n\n## 模拟与测试\n\n### 网络模拟\n\n```bash\nchrome-devtools emulate --networkConditions \"Offline\"\nchrome-devtools emulate --cpuThrottlingRate 4\n```\n\n### 设备模拟\n\n| 参数 | 功能 | 示例值 |\n|------|------|--------|\n| `--colorScheme` | 颜色方案 | `dark`, `light` |\n| `--viewport` | 视口尺寸 | `1920x1080` |\n| `--userAgent` | 用户代理字符串 | 自定义 UA |\n| `--geolocation` | 地理位置 | `0x0` |\n\n```bash\n# 模拟暗黑模式和全高清视口\nchrome-devtools emulate --colorScheme \"dark\" --viewport \"1920x1080\"\n\n# 重置页面尺寸\nchrome-devtools resize_page 1920 1080\n```\n\n## 开发与测试\n\n### 构建项目\n\n```bash\nnpm run build\n```\n\n该命令执行 TypeScript 编译并测试构建结果。\n\n### 运行测试\n\n```bash\nnpm run test # 运行所有测试\nnpm run test path-to-test.ts # 运行单个测试文件\n```\n\n### 代码格式化\n\n```bash\nnpm run format\n```\n\n该命令自动修复格式化问题并显示 linting 错误。\n\n## TypeScript 开发规范\n\n项目制定了严格的 TypeScript 开发规范：\n\n| 规范 | 说明 |\n|------|------|\n| 禁用 `any` 类型 | 必须使用具体类型 |\n| 禁用 `as` 类型转换 | 使用类型守卫或泛型 |\n| 禁用 `!` 断言 | 使用显式类型检查 |\n| 禁用 `// @ts-ignore` | 必须修复类型问题 |\n| 优先使用 `for..of` | 避免使用 `forEach` |\n\n资料来源：[AGENTS.md:15-25]()\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 命令未识别 | 确保全局 npm `bin` 目录在 PATH 中 |\n| 权限错误 | 避免使用 `sudo`，使用 nvm 管理 Node.js |\n| 旧版本运行 | 运行 `chrome-devtools stop && npm uninstall -g chrome-devtools-mcp` |\n\n### 重启终端\n\n安装后可能需要重启终端或 source 配置文件（`.bashrc`、`.zshrc`）以使命令生效。\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:10-18]()\n\n## 扩展功能\n\n### 扩展支持\n\n如需使用浏览器扩展功能，在 MCP 服务器配置中添加 `--categoryExtensions` 参数：\n\n```bash\nnpx chrome-devtools-mcp@latest --categoryExtensions\n```\n\n### WebMCP 工具\n\n页面可暴露自定义 WebMCP 工具：\n\n| 工具 | 功能 |\n|------|------|\n| `list_webmcp_tools` | 列出页面暴露的所有 WebMCP 工具 |\n| `execute_webmcp_tool` | 执行指定的 WebMCP 工具 |\n\n```bash\nchrome-devtools list_webmcp_tools\nchrome-devtools execute_webmcp_tool \"toolName\" --input '{\"key\": \"value\"}'\n```\n\n资料来源：[src/tools/webmcp.ts:10-40]()\n\n## 下一步\n\n- 阅读完整的[工具参考文档](./tool-reference.md)\n- 查看 [LCP 优化指南](./debug-optimize-lcp/index.md)\n- 学习[无障碍调试](./a11y-debugging/index.md)技巧\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[守护进程系统](#daemon-system), [工具参考](#tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/index.ts)\n- [src/McpPage.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpPage.ts)\n- [src/McpContext.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpContext.ts)\n- [src/ToolHandler.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/ToolHandler.ts)\n- [src/browser.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts)\n \n\n# 系统架构\n\n## 1. 概述\n\nchrome-devtools-mcp 是一个基于 Model Context Protocol (MCP) 的服务器实现，通过 Chrome DevTools Protocol 与 Chrome 浏览器进行交互。该项目为 AI 助手提供了一套完整的浏览器自动化工具集，涵盖页面导航、快照采集、性能分析、网络监控、无障碍审计等功能。\n\n核心设计理念是将复杂的 CDP 操作封装为声明式的工具定义，并支持按需启用或禁用特定工具类别。\n\n资料来源：[skills/chrome-devtools/SKILL.md]()\n\n## 2. 架构层次\n\n项目采用分层架构，从底层到顶层依次为：\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B[MCP 服务器层
src/index.ts]\n B --> C[工具路由层
src/ToolHandler.ts]\n C --> D[页面管理层
src/McpPage.ts
src/McpContext.ts]\n D --> E[浏览器抽象层
src/browser.ts]\n E --> F[Puppeteer]\n F --> G[Chrome DevTools Protocol]\n G --> H[Chrome 浏览器]\n \n I[PageCollector] -.->|事件收集| D\n I -.->|依赖| E\n```\n\n### 2.1 MCP 服务器层 (src/index.ts)\n\n作为整个系统的入口点，负责初始化 MCP 服务器并注册所有可用工具。该层处理 MCP 协议的请求/响应生命周期。\n\n### 2.2 工具路由层 (src/ToolHandler.ts)\n\n负责将 MCP 请求路由到对应的工具处理器，维护工具注册表并处理工具执行的生命周期。\n\n### 2.3 页面管理层 (src/McpPage.ts, src/McpContext.ts)\n\n管理多页面上下文，包括页面创建、销毁、切换，以及页面作用域内工具的隔离执行。\n\n### 2.4 浏览器抽象层 (src/browser.ts)\n\n封装 Puppeteer API，提供浏览器启动、页面管理、连接复用等底层能力。\n\n## 3. 核心组件\n\n### 3.1 工具定义系统\n\n工具通过 `defineTool` 和 `definePageTool` 工厂函数声明式定义，支持条件化生成和参数化扩展：\n\n```typescript\nexport function defineTool<\n Schema extends zod.ZodRawShape,\n Args extends ParsedArguments = ParsedArguments,\n>(\n definition:\n | ToolDefinition\n | ((args?: Args) => ToolDefinition),\n) {\n if (typeof definition === 'function') {\n const factory = definition;\n return (args: Args) => {\n return factory(args);\n };\n }\n return definition;\n}\n```\n\n资料来源：[src/tools/ToolDefinition.ts:1-20]()\n\n| 组件 | 作用 |\n|------|------|\n| `ToolDefinition` | 工具的基础定义接口 |\n| `defineTool` | 创建全局工具的工厂函数 |\n| `definePageTool` | 创建页面作用域工具的工厂函数 |\n| `pageIdSchema` | 提供可选的页面 ID 参数 |\n| `timeoutSchema` | 提供可选的超时配置 |\n\n### 3.2 工具定义结构\n\n每个工具定义包含以下关键字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `name` | string | 工具唯一标识符 |\n| `description` | string | 工具功能描述 |\n| `schema` | ZodSchema | 输入参数校验 schema |\n| `handler` | Function | 实际执行的处理函数 |\n| `pageScoped` | boolean | 是否为页面作用域工具 |\n| `blockedByDialog` | boolean | 是否被对话框阻塞 |\n| `annotations` | ToolAnnotations | 工具元数据（分类、只读提示等）|\n\n```typescript\ninterface ToolDefinition<\n Schema extends zod.ZodRawShape = zod.ZodRawShape,\n> extends BaseToolDefinition {\n handler: (\n request: Request,\n response: Response,\n context: Context,\n ) => Promise;\n}\n```\n\n资料来源：[src/tools/ToolDefinition.ts:1-20]()\n\n### 3.3 页面上下文管理\n\n页面上下文通过 `McpContext` 管理，支持多页面并发操作：\n\n```mermaid\ngraph TD\n A[McpContext] -->|管理| B[McpPage 1]\n A -->|管理| C[McpPage 2]\n A -->|管理| D[McpPage N]\n B -->|操作| E[CDP Session 1]\n C -->|操作| F[CDP Session 2]\n D -->|操作| G[CDP Session N]\n```\n\n`McpPage` 封装了单个页面的 CDP 操作，提供统一的工具调用接口。\n\n资料来源：[src/McpPage.ts]()\n\n### 3.4 浏览器生命周期\n\n```mermaid\ngraph LR\n A[启动 Chrome] --> B[建立 CDP 连接]\n B --> C[初始化页面]\n C --> D[注册事件监听]\n D --> E[PageCollector 收集数据]\n E --> F[等待工具调用]\n F --> G[执行工具]\n G --> H[返回结果]\n H -->|继续| F\n```\n\n资料来源：[src/browser.ts]()\n\n## 4. 工具分类体系\n\n工具按功能分类，通过 `ToolCategory` 枚举定义：\n\n| 分类 | 说明 | 示例工具 |\n|------|------|----------|\n| `NAVIGATION` | 页面导航与控制 | navigate_page, new_page, close_page |\n| `INSPECTION` | 页面状态检查 | take_snapshot, take_screenshot |\n| `INTERACTION` | 用户交互模拟 | click, fill_form, press_key |\n| `PERFORMANCE` | 性能分析与追踪 | performance_start_trace, take_memory_snapshot |\n| `NETWORK` | 网络请求监控 | network_intercept_request |\n| `EMULATION` | 环境模拟 | emulate, resize_page |\n| `ACCESSIBILITY` | 无障碍审计 | run_lighthouse |\n| `WEBMCP` | 页面暴露的工具 | list_webmcp_tools, execute_webmcp_tool |\n\n资料来源：[src/tools/categories.ts]()、[src/tools/webmcp.ts]()\n\n## 5. 页面收集器 (PageCollector)\n\n`PageCollector` 是一个通用的事件收集器，用于监听浏览器目标事件：\n\n```typescript\nexport class PageCollector {\n #browser: Browser;\n #listenersInitializer: (\n collector: (item: T) => void,\n ) => ListenerMap;\n protected storage = new WeakMap>>>();\n \n async init(pages: Page[]) { /* ... */ }\n dispose() { /* ... */ }\n}\n```\n\n资料来源：[src/PageCollector.ts:1-30]()\n\n### 5.1 事件流\n\n```mermaid\ngraph TD\n A[targetcreated 事件] --> B{获取 Page}\n B -->|成功| C[addPage]\n B -->|失败| D[记录日志]\n C --> E[targetdestroyed 事件]\n E --> F[removePage]\n \n G[页面事件] --> H[触发监听器]\n H --> I[收集数据到 storage]\n I --> J[WeakMap 存储]\n```\n\n## 6. WebMCP 工具机制\n\nWebMCP 允许页面主动暴露自定义工具，实现双向通信：\n\n```typescript\nexport const listWebMcpTools = definePageTool({\n name: 'list_webmcp_tools',\n description: `Lists all WebMCP tools the page exposes.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: true,\n },\n schema: {},\n blockedByDialog: false,\n handler: async (_request, response, _context) => {\n response.setListWebMcpTools();\n },\n});\n\nexport const executeWebMcpTool = definePageTool({\n name: 'execute_webmcp_tool',\n description: `Executes a WebMCP tool exposed by the page.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: false,\n },\n schema: {\n toolName: zod.string().describe('The name of the WebMCP tool to execute'),\n input: zod.string().optional().describe('The JSON-stringified parameters'),\n },\n blockedByDialog: false,\n handler: async (request, response) => {\n const toolName = request.params.toolName;\n let input: Record = {};\n if (request.params.input) {\n const parsed = JSON.parse(request.params.input);\n // ...\n }\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts:1-50]()\n\n## 7. 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as MCP 服务器\n participant Handler as ToolHandler\n participant Context as McpContext\n participant Page as McpPage\n participant CDP as Chrome CDP\n\n Client->>Server: 工具调用请求\n Server->>Handler: 路由到对应工具\n Handler->>Context: 获取当前页面上下文\n Context->>Page: 执行页面操作\n Page->>CDP: 发送 CDP 命令\n CDP-->>Page: 返回执行结果\n Page-->>Context: 返回结果\n Context-->>Handler: 格式化响应\n Handler-->>Server: 返回工具响应\n Server-->>Client: MCP 响应\n```\n\n## 8. 工具依赖关系\n\n部分工具需要特定的前置条件，例如对话框阻塞：\n\n| 工具类型 | blockedByDialog | 说明 |\n|----------|-----------------|------|\n| 导航工具 | false | 通常允许在对话框存在时执行 |\n| 检查工具 | false | 快照和截图不受对话框影响 |\n| 交互工具 | true | 点击、表单填写需等待对话框关闭 |\n\n```typescript\nexport const CLOSE_PAGE_ERROR =\n 'The last open page cannot be closed. It is fine to keep it open.';\n```\n\n资料来源：[src/tools/ToolDefinition.ts:30-32]()\n\n## 9. 扩展性设计\n\n### 9.1 新增工具类别\n\n在 `src/tools/categories.ts` 中扩展 `ToolCategory` 枚举，然后在对应的文件中使用 `defineTool` 或 `definePageTool` 注册工具。\n\n### 9.2 条件化工具生成\n\n工具支持函数式定义，可根据参数动态生成：\n\n```typescript\nexport function definePageTool<\n Schema extends zod.ZodRawShape,\n Args extends ParsedArguments = ParsedArguments,\n>(\n definition: (args?: Args) => PageToolDefinition,\n): (args?: Args) => DefinedPageTool {\n return (args?: Args): DefinedPageTool => {\n const tool = definition(args);\n return {\n ...tool,\n pageScoped: true,\n };\n };\n}\n```\n\n资料来源：[src/tools/ToolDefinition.ts:40-60]()\n\n## 10. 总结\n\nchrome-devtools-mcp 的架构设计体现了以下原则：\n\n1. **分层解耦**：通过明确的层次划分，实现关注点分离\n2. **声明式定义**：工具通过结构化的 schema 声明，简化了注册流程\n3. **页面隔离**：每个页面维护独立的上下文，保证并发安全\n4. **事件驱动**：通过 PageCollector 实现灵活的事件收集机制\n5. **双向通信**：WebMCP 机制支持页面主动暴露能力，拓展了应用边界\n\n---\n\n\n\n## 守护进程系统\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/daemon/daemon.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/daemon/daemon.ts)\n- [src/daemon/client.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/daemon/client.ts)\n- [src/daemon/types.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/daemon/types.ts)\n- [src/daemon/utils.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/daemon/utils.ts)\n \n\n# 守护进程系统\n\n## 概述\n\n守护进程系统（Daemon System）是 chrome-devtools-mcp 项目中负责管理和维护 Chrome DevTools 协议通信后端服务的核心模块。该系统确保 MCP 服务器与浏览器实例之间的长期稳定连接，并提供进程生命周期管理、状态监控和资源清理等功能。\n\n在 chrome-devtools-mcp 架构中，守护进程扮演着后台服务的角色，使得客户端能够通过 MCP 协议与浏览器进行交互，而无需关心底层连接管理的复杂性。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A[MCP 客户端]\n B[CLI 工具
chrome-devtools]\n end\n \n subgraph 守护进程层\n C[Daemon Manager]\n D[Chrome Browser
实例]\n end\n \n subgraph 协议层\n E[CDP 协议
Chrome DevTools Protocol]\n end\n \n A --> C\n B --> C\n C <--> E\n E <--> D\n \n style C fill:#e1f5fe\n style D fill:#fff3e0\n```\n\n### 核心组件\n\n| 组件名称 | 文件位置 | 职责描述 |\n|---------|---------|---------|\n| Daemon Manager | `daemon.ts` | 进程生命周期管理、启动/停止控制 |\n| Daemon Client | `client.ts` | 客户端通信接口、命令发送与接收 |\n| 类型定义 | `types.ts` | 共享类型、接口、枚举定义 |\n| 工具函数 | `utils.ts` | 通用工具函数、日志、错误处理 |\n\n## 守护进程管理器\n\n### 进程启动流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Daemon as Daemon Manager\n participant Chrome as Chrome 实例\n participant CDP as CDP Protocol\n \n Client->>Daemon: 启动请求\n Daemon->>Chrome: 启动 Chrome 进程\n Chrome-->>Daemon: 进程已启动\n Daemon->>CDP: 建立 WebSocket 连接\n CDP-->>Daemon: 连接就绪\n Daemon-->>Client: 启动成功/状态就绪\n```\n\n### 核心功能\n\n#### 1. 进程生命周期管理\n\n守护进程管理器负责 Chrome 浏览器实例的完整生命周期：\n\n- **启动**：初始化 Chrome 进程并建立调试连接\n- **运行**：维护活跃的 CDP 会话\n- **停止**：优雅关闭进程并清理资源\n- **重启**：在故障时自动恢复服务\n\n#### 2. 配置管理\n\n守护进程支持多种启动配置参数：\n\n| 参数名称 | 类型 | 默认值 | 说明 |\n|---------|------|-------|------|\n| port | number | 9222 | Chrome 调试端口 |\n| userDataDir | string | - | 用户数据目录路径 |\n| headless | boolean | true | 是否以无头模式运行 |\n| startupTimeout | number | 30000 | 启动超时时间(毫秒) |\n\n## 客户端通信接口\n\n### 连接建立\n\n```mermaid\ngraph LR\n A[CLI 命令] --> B[Client.connect]\n B --> C{连接状态}\n C -->|成功| D[返回连接句柄]\n C -->|失败| E[错误处理]\n D --> F[发送 CDP 命令]\n F --> G[接收响应]\n```\n\n### API 接口\n\n守护进程客户端提供以下核心方法：\n\n```typescript\ninterface DaemonClient {\n // 建立连接\n connect(options: ConnectOptions): Promise;\n \n // 断开连接\n disconnect(): Promise;\n \n // 发送命令\n sendCommand(method: string, params?: object): Promise;\n \n // 获取状态\n getStatus(): DaemonStatus;\n}\n```\n\n## 类型系统\n\n### 核心类型定义\n\n```typescript\n// 守护进程状态枚举\nenum DaemonState {\n STOPPED = 'stopped',\n STARTING = 'starting',\n RUNNING = 'running',\n STOPPING = 'stopping',\n ERROR = 'error'\n}\n\n// 连接配置\ninterface ConnectOptions {\n port?: number;\n autoReconnect?: boolean;\n timeout?: number;\n}\n\n// 守护进程状态\ninterface DaemonStatus {\n state: DaemonState;\n uptime: number;\n browserVersion?: string;\n error?: string;\n}\n```\n\n### 类型安全\n\n守护进程系统采用 TypeScript 严格类型检查策略：\n\n- 禁止使用 `any` 类型\n- 禁止使用类型断言 `as` 关键字\n- 禁止使用非空断言 `!` 操作符\n- 优先使用 `for...of` 循环替代 `forEach`\n\n## 工具模块\n\n### 错误处理\n\n工具模块提供统一的错误处理机制：\n\n```typescript\n// 自定义错误类型\nclass DaemonError extends Error {\n constructor(\n message: string,\n public code: DaemonErrorCode,\n public details?: object\n ) {\n super(message);\n }\n}\n```\n\n### 日志记录\n\n```typescript\ninterface LogOptions {\n level: 'debug' | 'info' | 'warn' | 'error';\n timestamp?: boolean;\n prefix?: string;\n}\n```\n\n## 状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> STOPPED: 初始化\n STOPPED --> STARTING: 启动请求\n STARTING --> RUNNING: 连接成功\n STARTING --> ERROR: 连接失败\n RUNNING --> STOPPING: 停止请求\n RUNNING --> ERROR: 连接断开\n STOPPING --> STOPPED: 进程已关闭\n ERROR --> STARTING: 重试\n ERROR --> STOPPED: 放弃\n STOPPED --> [*]: 销毁\n```\n\n## 使用场景\n\n### 1. MCP 服务器集成\n\n守护进程系统被 MCP 服务器直接使用：\n\n```typescript\nimport { DaemonManager } from './daemon/daemon';\n\nconst daemon = new DaemonManager({\n port: 9222,\n headless: true\n});\n\nawait daemon.start();\n```\n\n### 2. CLI 工具调用\n\n命令行工具通过守护进程客户端与服务交互：\n\n```bash\nchrome-devtools start\nchrome-devtools status\nchrome-devtools stop\n```\n\n### 3. 测试环境\n\n在测试场景中，守护进程提供隔离的浏览器环境：\n\n```typescript\nconst testDaemon = new DaemonManager({\n userDataDir: '/tmp/test-profile',\n headless: true\n});\n```\n\n## 配置与调试\n\n### 环境变量\n\n| 变量名称 | 说明 |\n|---------|------|\n| `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` | 禁用使用统计 |\n| `DEBUG` | 调试日志类别控制 |\n| `LOG_FILE` | 日志输出文件路径 |\n\n### 日志级别\n\n```bash\n# 启用所有调试日志\nDEBUG=* chrome-devtools start\n\n# 输出到文件\nnpx chrome-devtools-mcp@latest --log-file=/tmp/daemon.log\n```\n\n## 最佳实践\n\n1. **启动顺序**：先启动守护进程，再建立客户端连接\n2. **资源清理**：使用完毕及时调用 `stop()` 方法释放资源\n3. **超时处理**：设置合理的 `startupTimeout` 避免无限等待\n4. **错误恢复**：实现重连机制处理临时性网络故障\n5. **端口管理**：确保调试端口未被其他进程占用\n\n## 相关文档\n\n- [安装指南](../skills/chrome-devtools-cli/references/installation.md)\n- [故障排除](../skills/troubleshooting/SKILL.md)\n- [工具参考](../src/tools/ToolDefinition.ts)\n\n---\n\n\n\n## 工具参考\n\n### 相关页面\n\n相关主题：[输入自动化工具](#input-automation), [性能分析工具](#performance-tools), [内存调试工具](#memory-debugging)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/tools.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/tools.ts)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [src/tools/categories.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts)\n- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n- [src/McpResponse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)\n- [scripts/generate-docs.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)\n \n\n# 工具参考\n\n本页面详细描述 chrome-devtools-mcp 项目中的工具（Tool）系统架构、定义方式、分类体系以及运行时行为。\n\n## 概述\n\n工具系统是 chrome-devtools-mcp 的核心组件，它将 Chrome DevTools Protocol (CDP) 的能力封装为可通过 MCP (Model Context Protocol) 调用的接口。该系统支持两类工具：\n\n- **全局工具 (Tool)**：不依赖于特定页面的工具，如浏览器管理、网络控制等\n- **页面作用域工具 (PageTool)**：需要绑定到特定页面的工具，如元素交互、表单填充等\n\n资料来源：[src/tools/ToolDefinition.ts:1-50]()\n\n## 工具架构\n\n### 类型层级\n\n工具系统采用 TypeScript 类型安全的设计，通过泛型约束确保工具定义的正确性。\n\n```mermaid\ngraph TD\n A[BaseToolDefinition] --> B[ToolDefinition]\n A --> C[PageToolDefinition]\n B --> D[DefinedTool]\n C --> E[DefinedPageTool]\n```\n\n| 类型名称 | 作用域 | 描述 |\n|---------|--------|------|\n| `BaseToolDefinition` | 基础 | 所有工具定义的基类 |\n| `ToolDefinition` | 全局 | 不依赖页面的工具定义 |\n| `PageToolDefinition` | 页面 | 依赖页面上下文工具定义 |\n| `DefinedTool` | 全局 | 已解析的工具定义 |\n| `DefinedPageTool` | 页面 | 已解析的页面作用域工具定义 |\n\n资料来源：[src/tools/ToolDefinition.ts:50-80]()\n\n### 工具结构\n\n每个工具定义包含以下核心字段：\n\n| 字段 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `name` | `string` | 是 | 工具唯一标识名称 |\n| `description` | `string` | 是 | 工具功能描述，用于 AI 理解用途 |\n| `schema` | `zod.ZodRawShape` | 是 | 输入参数 schema 定义 |\n| `handler` | `Function` | 是 | 工具执行逻辑 |\n| `annotations` | `ToolAnnotations` | 否 | 工具元数据注解 |\n| `blockedByDialog` | `boolean` | 否 | 是否被对话框阻塞 |\n| `pageScoped` | `boolean` | 否 | 是否为页面作用域工具 |\n\n资料来源：[src/tools/ToolDefinition.ts:80-120]()\n\n## 工具定义函数\n\n### defineTool - 全局工具定义\n\n`defineTool` 用于定义不依赖特定页面的工具，如浏览器管理、性能分析等。\n\n```typescript\nexport function defineTool(\n definition: ToolDefinition,\n): DefinedTool;\n```\n\n**使用示例**：\n\n```typescript\nexport const myGlobalTool = defineTool({\n name: 'my_global_tool',\n description: 'A global tool that works without page context',\n schema: {\n param1: zod.string().describe('First parameter'),\n },\n annotations: {\n category: ToolCategory.BROWSER,\n readOnlyHint: true,\n },\n blockedByDialog: false,\n handler: async (request, response, context) => {\n // 工具执行逻辑\n },\n});\n```\n\n资料来源：[src/tools/ToolDefinition.ts:140-180]()\n\n### definePageTool - 页面作用域工具定义\n\n`definePageTool` 用于定义需要页面上下文的工具，handler 函数会自动接收 `page: ContextPage` 参数。\n\n```typescript\nexport function definePageTool(\n definition: PageToolDefinition,\n): DefinedPageTool;\n```\n\n**使用示例**：\n\n```typescript\nexport const clickTool = definePageTool({\n name: 'click',\n description: 'Clicks on an element identified by uid',\n schema: {\n uid: zod.string().describe('The uid of the element to click'),\n },\n annotations: {\n category: ToolCategory.INPUT,\n readOnlyHint: false,\n },\n blockedByDialog: true,\n handler: async (request, response, context) => {\n // request 包含 { page: ContextPage, params: { uid: string } }\n },\n});\n```\n\n资料来源：[src/tools/ToolDefinition.ts:180-220]()\n\n### 工厂模式支持\n\n两个定义函数都支持传入工厂函数，用于动态生成工具定义：\n\n```typescript\nexport function definePageTool<\n Schema extends zod.ZodRawShape,\n Args extends ParsedArguments = ParsedArguments,\n>(\n definition: (args?: Args) => PageToolDefinition,\n): (args?: Args) => DefinedPageTool;\n```\n\n这允许工具定义根据传入参数进行条件性配置。\n\n资料来源：[src/tools/ToolDefinition.ts:220-240]()\n\n## 工具分类体系\n\n### 分类枚举\n\n工具按功能域划分为多个分类，便于管理和文档生成：\n\n| 分类标识 | 显示名称 | 描述 |\n|---------|----------|------|\n| `NAVIGATION` | Navigation | 页面导航相关工具 |\n| `INPUT` | Input Automation | 用户输入和交互工具 |\n| `INSPECTION` | Inspection | 页面元素检查和快照工具 |\n| `EMULATION` | Emulation | 环境模拟工具 |\n| `PERFORMANCE` | Performance | 性能分析工具 |\n| `NETWORK` | Network | 网络请求相关工具 |\n| `BROWSER` | Browser | 浏览器管理工具 |\n| `EXTENSION` | Extensions | Chrome 扩展管理工具 |\n| `WEBMCP` | WebMCP | WebMCP 协议工具 |\n| `EXPERIMENTAL` | Experimental | 实验性功能工具 |\n\n资料来源：[src/tools/categories.ts]()\n\n### 分类标签映射\n\n文档生成系统使用标签映射将分类标识转换为可读名称：\n\n```typescript\nconst labels: Record = {\n [ToolCategory.NAVIGATION]: 'Navigation',\n [ToolCategory.INPUT]: 'Input Automation',\n [ToolCategory.INSPECTION]: 'Inspection',\n // ...\n};\n```\n\n资料来源：[scripts/generate-docs.ts:30-50]()\n\n## 工具注解系统\n\n### 注解结构\n\n`annotations` 字段提供工具的额外元数据：\n\n```typescript\ninterface ToolAnnotations {\n category: ToolCategory; // 工具所属分类\n readOnlyHint?: boolean; // 是否为只读操作\n conditions?: string[]; // 需要的实验性标志\n docsLink?: string; // 文档链接\n}\n```\n\n| 注解字段 | 类型 | 描述 |\n|---------|------|------|\n| `category` | `ToolCategory` | **必填** 工具分类 |\n| `readOnlyHint` | `boolean` | 提示是否为只读操作，帮助 AI 决策是否需要确认 |\n| `conditions` | `string[]` | 激活工具所需的实验性标志列表 |\n| `docsLink` | `string` | 相关文档链接 |\n\n资料来源：[src/tools/ToolDefinition.ts:40-48]()\n\n### 条件激活机制\n\n某些工具需要特定标志才能使用，条件在 `conditions` 数组中声明：\n\n```typescript\nconst experimentalTool = definePageTool({\n name: 'screencast_start',\n description: 'Starts a screencast recording',\n annotations: {\n category: ToolCategory.EXPERIMENTAL,\n conditions: ['experimentalScreencast'], // 需要 --experimentalScreencast=true\n },\n schema: {},\n blockedByDialog: false,\n handler: async (request, response, context) => {\n // 处理屏幕录制\n },\n});\n```\n\n资料来源：[scripts/generate-docs.ts:60-80]()\n\n## Schema 定义规范\n\n### Zod Schema 结构\n\n工具参数通过 Zod 进行类型安全的 schema 定义：\n\n```typescript\nschema: {\n paramName: zod.string().describe('Parameter description'),\n optionalParam: zod.number().optional().describe('Optional parameter'),\n enumParam: zod.enum(['option1', 'option2']).describe('Enum parameter'),\n}\n```\n\n### 常用 Schema 组件\n\n| Schema 类型 | 用途 | 示例 |\n|------------|------|------|\n| `zod.string()` | 字符串参数 | 用户名、URL |\n| `zod.number()` | 数字参数 | 坐标、超时值 |\n| `zod.boolean()` | 布尔参数 | 开关选项 |\n| `zod.enum()` | 枚举参数 | 类型选择 |\n| `zod.array()` | 数组参数 | 多个值 |\n| `zod.optional()` | 可选参数 | 标记为可选 |\n\n### 预定义 Schema\n\n系统提供常用 schema 组件：\n\n```typescript\nexport const pageIdSchema = {\n pageId: zod.number().optional().describe('Targets a specific page by ID.'),\n};\n\nexport const timeoutSchema = {\n timeout: zod\n .number()\n .int()\n .optional()\n .describe('Maximum wait time in milliseconds.'),\n};\n```\n\n资料来源：[src/tools/ToolDefinition.ts:55-70]()\n\n## 请求处理流程\n\n### Handler 函数签名\n\n**全局工具 Handler**：\n```typescript\nhandler: (\n request: Request & { page?: ContextPage },\n response: Response,\n context: Context,\n) => Promise\n```\n\n**页面作用域工具 Handler**：\n```typescript\nhandler: (\n request: Request & { page: ContextPage },\n response: Response,\n context: Context,\n) => Promise\n```\n\n### 请求生命周期\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Server as MCP Server\n participant Tool as Tool Handler\n participant CDP as Chrome DevTools\n \n Client->>Server: 工具调用请求\n Server->>Tool: 解析参数 + 验证 Schema\n alt 页面作用域工具\n Tool->>Tool: 验证页面上下文\n end\n Tool->>CDP: CDP 协议命令\n CDP-->>Tool: 执行结果\n Tool->>Server: 格式化响应\n Server-->>Client: MCP 响应\n```\n\n## MCP 响应集成\n\n### 响应格式化\n\n工具执行结果通过 `McpResponse` 类进行格式化，支持多种输出格式：\n\n```typescript\nresponse.setListWebMcpTools(); // 设置 WebMCP 工具列表\nresponse.setText(content: string); // 设置文本内容\nresponse.setScreenshot(filePath: string); // 设置截图路径\nresponse.setSnapshot(snapshot: string); // 设置快照内容\n```\n\n### 响应数据结构\n\n```typescript\ninterface ToolResponse {\n content: ContentBlock[]; // 内容块列表\n structuredContent?: { // 结构化内容\n webmcpTools?: WebMcpTool[]; // WebMCP 工具信息\n networkRequests?: NetworkRequest[];\n pagination?: PaginationData;\n };\n}\n```\n\n资料来源：[src/McpResponse.ts:1-50]()\n\n## 工具注册与发现\n\n### 工具列表生成\n\n文档生成脚本自动扫描所有工具定义并生成参考文档：\n\n```mermaid\ngraph LR\n A[工具源文件] --> B[generate-docs.ts]\n B --> C[工具分类]\n C --> D[Markdown 文档]\n D --> E[docs/tool-reference.md]\n B --> F[README TOC]\n```\n\n生成过程包括：\n1. 扫描所有 `src/tools/` 目录下的工具定义\n2. 按 `ToolCategory` 分组\n3. 生成参数表格和描述\n4. 输出到 `docs/tool-reference.md`\n\n资料来源：[scripts/generate-docs.ts:100-150]()\n\n### 工具列表输出格式\n\n```markdown\n## WebMCP tools\n\nname=\"list_webmcp_tools\", description=\"Lists all WebMCP tools...\", inputSchema={}\nname=\"execute_webmcp_tool\", description=\"Executes a WebMCP tool...\", inputSchema={\"toolName\": {...}, \"input\": {...}}\n```\n\n资料来源：[src/McpResponse.ts:60-80]()\n\n## WebMCP 特殊工具\n\n### list_webmcp_tools\n\n列出页面暴露的所有 WebMCP 工具：\n\n```typescript\nexport const listWebMcpTools = definePageTool({\n name: 'list_webmcp_tools',\n description: `Lists all WebMCP tools the page exposes.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: true,\n },\n schema: {},\n blockedByDialog: false,\n handler: async (_request, response, _context) => {\n response.setListWebMcpTools();\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts:15-30]()\n\n### execute_webmcp_tool\n\n执行页面暴露的 WebMCP 工具：\n\n```typescript\nexport const executeWebMcpTool = definePageTool({\n name: 'execute_webmcp_tool',\n description: `Executes a WebMCP tool exposed by the page.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: false,\n },\n schema: {\n toolName: zod.string().describe('The name of the WebMCP tool to execute'),\n input: zod.string().optional().describe('The JSON-stringified parameters'),\n },\n blockedByDialog: false,\n handler: async (request, response) => {\n // 解析输入并执行工具\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts:32-60]()\n\n## 类型安全约束\n\n项目对 TypeScript 使用有严格的类型安全要求：\n\n| 规则 | 说明 | 违规处理 |\n|------|------|----------|\n| 禁止 `any` | 不允许使用 any 类型 | 使用具体类型替代 |\n| 禁止 `as` | 不允许类型断言 | 使用类型守卫或验证 |\n| 禁止 `!` | 不允许非空断言 | 使用显式检查 |\n| 禁止 `@ts-ignore` | 不允许忽略类型检查 | 修复类型问题 |\n| 推荐 `for..of` | 替代 `forEach` | 提高可读性 |\n\n资料来源：[AGENTS.md:20-35]()\n\n## 总结\n\n工具系统是 chrome-devtools-mcp 实现浏览器自动化和调试能力的基础架构。通过：\n\n- **类型安全的工具定义**：利用 TypeScript 泛型和 Zod schema 确保编译期和运行期类型正确\n- **分层架构**：区分全局工具和页面作用域工具，适配不同的使用场景\n- **注解驱动**：通过 annotations 提供元数据，支持文档生成和 AI 决策\n- **统一处理流程**：标准化工具的注册、调用、响应流程\n\n开发者可以基于 `defineTool` 和 `definePageTool` 快速扩展新的工具能力，同时保持代码的一致性和可维护性。\n\n---\n\n\n\n## 输入自动化工具\n\n### 相关页面\n\n相关主题：[工具参考](#tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/input.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/input.ts)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n- [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n \n\n# 输入自动化工具\n\n## 概述\n\n输入自动化工具是 chrome-devtools-mcp 项目的核心功能模块之一，提供了通过 Chrome DevTools Protocol 对网页进行自动化交互的能力。该模块允许通过 MCP（Model Context Protocol）协议向浏览器发送命令，实现模拟用户输入、元素交互和文件上传等操作。\n\n这些工具位于 `src/tools/input.ts` 中，属于页面作用域工具（page-scoped tools），需要先选择一个活跃的页面上下文才能执行。工具集涵盖了从简单的按键操作到复杂的文本输入和文件上传等常见用户交互场景。\n\n## 架构设计\n\n### 工具定义模式\n\n输入自动化工具采用统一的工厂函数模式进行定义，使用 TypeScript 和 Zod 进行类型安全和参数校验。核心工具通过 `definePageTool` 函数注册，该函数来源于 `ToolDefinition.ts` 模块。资料来源：[src/tools/ToolDefinition.ts:43-68]()\n\n```mermaid\ngraph TD\n A[用户请求] --> B[参数校验层 Zod Schema]\n B --> C[Handler 处理函数]\n C --> D[Playwright Page API]\n D --> E[浏览器页面执行]\n E --> F[响应构建]\n F --> G[MCP 响应]\n```\n\n### 页面上下文依赖\n\n所有输入自动化工具均为页面作用域工具，需要通过 `select_page` 选择目标页面后才能执行。这种设计确保了操作的上下文隔离性和安全性。资料来源：[src/tools/ToolDefinition.ts:55-67]()\n\n## 工具分类\n\n输入自动化工具按功能可分为以下三类：\n\n| 类别 | 工具名称 | 功能描述 |\n|------|----------|----------|\n| 键盘操作 | `press_key` | 按下键盘按键或组合键 |\n| 键盘操作 | `type_text` | 向聚焦的输入框输入文本 |\n| 元素交互 | `click` | 点击指定元素 |\n| 元素交互 | `drag` | 拖拽元素到目标位置 |\n| 元素交互 | `fill` | 填充输入框或选择选项 |\n| 元素交互 | `hover` | 鼠标悬停在元素上 |\n| 文件操作 | `upload_file` | 通过文件输入元素上传文件 |\n\n## 键盘操作工具\n\n### press_key 工具\n\n`press_key` 工具用于模拟键盘按键操作，支持单键、修饰键组合以及特殊键序列。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `key` | string | 是 | 按键名称，支持组合键格式如 \"Control+A\"、\"Control+Shift+R\" |\n| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |\n\n**支持的修饰键：**\n\n- `Control`\n- `Shift`\n- `Alt`\n- `Meta`\n\n**特殊键示例：**\n\n- `Enter` - 回车键\n- `Tab` - 制表符\n- `Escape` - 退出键\n- `ArrowUp` / `ArrowDown` - 方向键\n- `Control++` - Ctrl 加号（缩放）\n- `Control+Shift+R` - 强制刷新\n\n**实现原理：**\n\n该工具使用 `parseKey` 函数解析按键字符串，将修饰键与主键分离。执行时按照修饰键按下 → 主键按下 → 修饰键释放的顺序进行操作，确保组合键的正确性。资料来源：[src/tools/input.ts:1-100]()\n\n```typescript\nconst result = await page.waitForEventsAfterAction(async () => {\n for (const modifier of modifiers) {\n await page.pptrPage.keyboard.down(modifier);\n }\n await page.pptrPage.keyboard.press(key);\n for (const modifier of modifiers.toReversed()) {\n await page.pptrPage.keyboard.up(modifier);\n }\n});\n```\n\n### type_text 工具\n\n`type_text` 工具用于向当前聚焦的输入元素输入文本内容。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `text` | string | 是 | 要输入的文本内容 |\n| `submitKey` | string | 否 | 输入完成后自动按下的提交键，如 \"Enter\" |\n| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |\n\n**使用场景：**\n\n- 在文本框中输入搜索关键词\n- 填写表单字段\n- 在富文本编辑器中输入内容\n\n**执行流程：**\n\n```mermaid\ngraph LR\n A[聚焦输入框] --> B[逐字符输入文本]\n B --> C{指定了 submitKey?}\n C -->|是| D[按下提交键]\n C -->|否| E[操作完成]\n D --> E\n```\n\n## 元素交互工具\n\n### click 工具\n\n`click` 工具通过元素 ID 执行点击操作，支持单击和双击模式。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `id` | string | 是 | 目标元素的 UID（从快照获取） |\n| `dblClick` | boolean | 否 | 是否执行双击，默认为 false |\n| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |\n\n### hover 工具\n\n`hover` 工具将鼠标移动到指定元素上方，常用于触发 CSS 悬浮效果或显示下拉菜单。\n\n### drag 工具\n\n`drag` 工具执行拖拽操作，将源元素拖拽到目标元素位置。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `src` | string | 是 | 源元素 ID |\n| `dst` | string | 是 | 目标元素 ID |\n| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |\n\n### fill 工具\n\n`fill` 工具用于快速填充表单输入框或选择下拉选项，相比 `type_text` 更加高效。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `id` | string | 是 | 目标输入框或选择框的 ID |\n| `text` | string | 是 | 要填充的文本或选项值 |\n| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |\n\n## 文件上传工具\n\n### upload_file 工具\n\n`upload_file` 工具通过已存在的文件输入元素（``）上传本地文件。\n\n**参数定义：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `id` | string | 是 | 文件输入元素的 ID |\n| `filePath` | string | 是 | 本地文件的绝对路径 |\n| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |\n\n**使用限制：**\n\n- 目标元素必须是 `` 或具有 `contenteditable` 属性的元素\n- 文件路径必须是服务器可访问的本地路径\n- 不支持拖拽上传区域（需使用 `drag` 工具模拟拖拽）\n\n## 通用参数与配置\n\n### 快照参数\n\n所有交互工具都支持 `includeSnapshot` 可选参数，用于控制在操作执行后是否返回页面的可访问性树快照。\n\n| 参数值 | 行为描述 |\n|--------|----------|\n| `true` | 操作完成后返回完整快照，可用于验证操作效果 |\n| `false` 或未指定 | 仅返回操作结果文本，不返回快照 |\n\n建议在以下场景启用快照返回：\n\n- 验证表单提交后的页面状态\n- 检查下拉菜单或弹窗是否正确显示\n- 确认异步操作完成后的 DOM 变化\n\n### 页面选择\n\n交互工具执行前必须通过 `select_page` 选择目标页面：\n\n```bash\nchrome-devtools select_page 1 # 选择索引为 1 的页面\nchrome-devtools select_page 1 --bringToFront true # 选择并切换到前台\n```\n\n未选择页面的直接调用将导致错误。\n\n## 工作流程\n\n### 典型交互流程\n\n```mermaid\ngraph TD\n A[初始化浏览器连接] --> B[选择目标页面]\n B --> C[获取页面快照]\n C --> D[识别目标元素 ID]\n D --> E[执行交互操作]\n E --> F{需要验证结果?}\n F -->|是| G[获取更新后的快照]\n F -->|否| H[完成]\n G --> H\n```\n\n### 对话框处理\n\n部分操作（如表单提交、文件上传确认）可能触发浏览器对话框。系统通过 `blockedByDialog` 属性控制工具是否等待对话框处理：\n\n- `press_key` 等工具默认 `blockedByDialog: true`，会在对话框出现时阻塞\n- 遇到对话框时，需使用 `handle_dialog` 工具进行响应\n\n```bash\nchrome-devtools handle_dialog accept # 接受对话框\nchrome-devtools handle_dialog dismiss --promptText \"取消\" # 拒绝并填写提示文本\n```\n\n## 错误处理\n\n### 常见错误场景\n\n| 错误类型 | 原因 | 解决方案 |\n|----------|------|----------|\n| 元素未找到 | 提供的 ID 指向不存在的元素 | 使用 `take_snapshot` 重新获取最新页面状态 |\n| 页面未选中 | 未先调用 `select_page` | 选择目标页面后重试 |\n| 对话框阻塞 | 操作被对话框中断 | 使用 `handle_dialog` 处理后再重试 |\n| 超时错误 | 元素等待超时 | 增加超时时间或检查元素是否存在 |\n\n### 最佳实践\n\n1. **始终获取最新快照**：页面状态可能因异步操作变化，建议每次交互前重新调用 `take_snapshot`\n2. **使用 appropriate 的超时设置**：对于慢速网络或复杂页面，适当增加超时时间\n3. **验证操作结果**：使用快照对比验证交互是否成功执行\n4. **避免并行冲突**：多个工具同时操作同一页面可能导致不可预期行为\n\n## 命令行使用示例\n\n```bash\n# 点击按钮\nchrome-devtools click \"btn-submit\"\n\n# 双击并获取快照\nchrome-devtools click \"btn-edit\" --dblClick true --includeSnapshot true\n\n# 输入文本并提交\nchrome-devtools type_text \"Hello World\" --submitKey \"Enter\"\n\n# 按下组合键\nchrome-devtools press_key \"Control+A\" --includeSnapshot true\n\n# 拖拽操作\nchrome-devtools drag \"source-id\" \"target-id\"\n\n# 文件上传\nchrome-devtools upload_file \"file-input\" \"/path/to/document.pdf\"\n```\n\n## 相关资源\n\n- 完整工具列表和参数说明：参考 `skills/chrome-devtools-cli/SKILL.md`\n- 元素定位策略：使用 `take_snapshot` 获取可访问性树和元素 UID\n- 高级调试：结合 `evaluate_script` 工具执行自定义 JavaScript 验证\n\n---\n\n\n\n## 性能分析工具\n\n### 相关页面\n\n相关主题：[工具参考](#tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/performance.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/performance.ts)\n- [src/tools/lighthouse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/lighthouse.ts)\n- [src/trace-processing/parse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/trace-processing/parse.ts)\n- [skills/debug-optimize-lcp/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/debug-optimize-lcp/SKILL.md)\n- [skills/debug-optimize-lcp/references/lcp-snippets.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/debug-optimize-lcp/references/lcp-snippets.md)\n- [skills/debug-optimize-lcp/references/optimization-strategies.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/debug-optimize-lcp/references/optimization-strategies.md)\n- [scripts/eval_scenarios/performance_test.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/eval_scenarios/performance_test.ts)\n \n\n# 性能分析工具\n\n## 概述\n\n性能分析工具是 chrome-devtools-mcp 提供的核心功能集，用于监控、测量和优化网页性能。该工具集涵盖性能追踪、性能洞察分析、内存快照捕获以及 Lighthouse 审计等多个维度，为开发者提供全面的性能诊断能力。\n\n工具采用 Chrome DevTools Protocol (CDP) 与浏览器内核深度交互，支持性能追踪录制、追踪文件保存与加载、性能指标解析以及自动化 Lighthouse 审计等功能。\n\n资料来源：[src/tools/performance.ts]() [src/tools/lighthouse.ts]()\n\n## 工具架构\n\n### 模块组成\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| 性能追踪 | `src/tools/performance.ts` | 启动/停止追踪录制，保存追踪文件 |\n| 性能洞察 | `src/tools/performance.ts` | 分析 Performance Insight 数据 |\n| 内存快照 | `src/tools/performance.ts` | 捕获 V8 堆内存快照 |\n| Lighthouse 审计 | `src/tools/lighthouse.ts` | 执行无头性能审计 |\n| 追踪解析 | `src/trace-processing/parse.ts` | 解析和处理追踪数据 |\n\n### 工具分类\n\n根据工具作用域可分为两类：\n\n1. **全局工具 (Global Tools)**：独立于页面上下文，直接通过 CDP 与浏览器交互\n2. **页面工具 (Page Tools)**：作用于当前选中的页面，需先选择页面\n\n性能分析工具中，`performance_start_trace`、`performance_stop_trace` 和 `take_memory_snapshot` 属于全局工具，而 `performance_analyze_insight` 和 `lighthouse_audit` 属于页面工具。\n\n资料来源：[src/tools/ToolDefinition.ts]()\n\n## 性能追踪 (Performance Trace)\n\n### 功能描述\n\n性能追踪工具提供 Chrome 开发者工具的性能录制功能，能够捕获页面在加载和运行过程中的详细执行轨迹数据。\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[开始追踪] --> B[performance_start_trace]\n B --> C{reload 参数}\n C -->|true| D[重新加载页面并录制]\n C -->|false| E[录制当前页面状态]\n D --> F[CDP Performance.startTrace]\n E --> F\n F --> G[追踪数据缓存于内存]\n G --> H[performance_stop_trace]\n H --> I{filePath 参数}\n I -->|提供| J[保存到文件]\n I -->|未提供| K[返回 JSON 数据]\n J --> L[追踪完成]\n K --> L\n```\n\n### 工具参数\n\n#### performance_start_trace\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `reload` | `boolean` | `false` | 是否在开始追踪前重新加载页面 |\n| `screenshot` | `boolean` | `false` | 是否捕获截屏 |\n| `filePath` | `string` | 无 | 追踪文件的保存路径（可选） |\n\n当 `reload` 设置为 `true` 时，工具会重新加载页面并录制完整的加载过程，这对于分析页面首次加载性能至关重要。\n\n资料来源：[src/tools/performance.ts]()\n资料来源：[skills/chrome-devtools/SKILL.md]()\n\n#### performance_stop_trace\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `filePath` | `string` | 无 | 导出追踪数据的文件路径（可选） |\n\n停止当前正在进行的性能追踪录制，并将追踪数据保存到指定文件或返回 JSON 数据。\n\n### 追踪数据格式\n\n追踪数据采用 JSON 格式，包含以下核心部分：\n\n- **traceEvents**：Chrome 追踪格式的事件数组\n- **metadata**：追踪元数据，包括浏览器版本、录制时间等\n- **screenshots**：如果启用截屏，则包含 Base64 编码的截屏数据\n\n## 性能洞察分析 (Performance Insights)\n\n### 功能描述\n\nPerformance Insights 是 Chrome DevTools 中比传统 Performance 面板更现代的性能分析界面，提供以用户为中心的性能指标解读。工具 `performance_analyze_insight` 用于获取这些洞察数据。\n\n### 支持的洞察类型\n\n| 洞察类型 | 说明 |\n|----------|------|\n| `LCPBreakdown` | Largest Contentful Paint 时间分解 |\n| `FCPBreakdown` | First Contentful Paint 时间分解 |\n| `CLSBreakdown` | Cumulative Layout Shift 变化分析 |\n| `TTFBBreakdown` | Time To First Byte 时间分解 |\n\n### 工具参数\n\n#### performance_analyze_insight\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `handle` | `string` | 是 | 追踪处理标识符 |\n| `type` | `string` | 是 | 洞察类型（如 `LCPBreakdown`） |\n\n### LCP 优化指南\n\n根据 LCPBreakdown 洞察数据，可按以下目标进行优化：\n\n| 瓶颈目标 | 占比目标 | 优化策略 |\n|----------|----------|----------|\n| TTFB | ~40% | 减少重定向，优化服务器响应时间，使用 CDN 缓存 HTML |\n| 资源加载时间 | ~40% | 使用 WebP/AVIF 格式，启用压缩，设置缓存头 |\n| 元素渲染延迟 | <10% | 内联关键 CSS，延迟非关键资源，打破长任务 |\n| LCP 资源加载延迟 | ~40% | 使用 ``，避免懒加载 LCP 图片 |\n\n资料来源：[skills/debug-optimize-lcp/SKILL.md]()\n资料来源：[skills/debug-optimize-lcp/references/optimization-strategies.md]()\n\n## 内存快照 (Memory Snapshot)\n\n### 功能描述\n\n内存快照工具用于捕获 V8 JavaScript 引擎的堆内存状态，帮助开发者分析内存泄漏和内存使用情况。\n\n### 工具参数\n\n#### take_memory_snapshot\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `filePath` | `string` | 快照文件的保存路径 |\n\n快照文件格式为 `.heapsnapshot`，可使用 Chrome DevTools 的 Memory 面板加载分析。\n\n### 工作原理\n\n1. 调用 CDP 的 `HeapProfiler.takeHeapSnapshot` 方法\n2. 将快照数据序列化为 Chrome 支持的堆快照格式\n3. 保存到指定文件路径或返回数据\n\n## Lighthouse 审计\n\n### 功能描述\n\nLighthouse 审计工具提供基于 Chromium 内置 Lighthouse 的自动化网站质量审计，覆盖无障碍访问（Accessibility）、搜索引擎优化（SEO）、最佳实践等多个维度。\n\n### 与性能追踪的区别\n\n| 维度 | Lighthouse 审计 | 性能追踪 |\n|------|------------------|----------|\n| 用途 | 网站质量综合评估 | 底层性能数据录制 |\n| 输出 | 结构化审计报告 | 原始追踪事件数据 |\n| 适用场景 | 快速评分、CI 集成 | 深度性能分析 |\n\n### 工具参数\n\n#### lighthouse_audit\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `mode` | `navigation` \\| `snapshot` | `navigation` | 审计模式：`navigation` 重新加载并审计，`snapshot` 分析当前状态 |\n| `device` | `desktop` \\| `mobile` | `desktop` | 模拟设备类型 |\n| `outputDirPath` | `string` | 临时目录 | 报告文件的保存目录 |\n| `pageId` | `number` | 当前选中页 | 指定审计的目标页面 |\n\n### 审计类别\n\nLighthouse 审计默认包含以下类别：\n\n| 类别 | 说明 |\n|------|------|\n| `accessibility` | 无障碍访问审计，检测缺失的标签、无效的 ARIA 属性等 |\n| `seo` | 搜索引擎优化审计 |\n| `best-practices` | Web 最佳实践审计 |\n| `agentic-browsing` | 代理浏览能力审计 |\n\n### 审计结果结构\n\n审计结果为 JSON 格式，包含：\n\n- `scores`：各审计类别的分数（0-1 范围）\n- `audits`：详细审计结果，包含通过/失败状态和建议\n- `timing`：审计执行时间\n\n资料来源：[src/tools/lighthouse.ts]()\n\n## LCP 调试与优化工作流\n\n### 诊断流程\n\n```mermaid\ngraph TD\n A[开始 LCP 优化] --> B[performance_start_trace reload=true]\n B --> C[录制页面加载追踪]\n C --> D[performance_stop_trace]\n D --> E[performance_analyze_insight LCPBreakdown]\n E --> F{识别瓶颈}\n F -->|TTFB 过高| G[优化服务器响应]\n F -->|资源加载慢| H[优化资源大小和格式]\n F -->|渲染延迟| I[消除阻塞资源]\n G --> J[验证修复]\n H --> J\n I --> J\n J --> K{重新录制}\n K -->|需继续优化| B\n K -->|达标| L[完成]\n```\n\n### JavaScript 诊断片段\n\n#### 识别 LCP 元素\n\n```javascript\nasync () => {\n return await new Promise(resolve => {\n new PerformanceObserver(list => {\n const entries = list.getEntries();\n const last = entries[entries.length - 1];\n resolve({\n element: last.element?.tagName,\n id: last.element?.id,\n url: last.url,\n startTime: last.startTime,\n renderTime: last.renderTime,\n size: last.size,\n });\n }).observe({type: 'largest-contentful-paint', buffered: true});\n });\n};\n```\n\n#### 审计常见问题\n\n```javascript\n() => {\n const issues = [];\n // 检查视口内懒加载的图片\n document.querySelectorAll('img[loading=\"lazy\"]').forEach(img => {\n const rect = img.getBoundingClientRect();\n if (rect.top < window.innerHeight) {\n issues.push({\n issue: 'lazy-loaded image in viewport',\n fix: 'Remove loading=\"lazy\" from this image',\n });\n }\n });\n return issues;\n};\n```\n\n资料来源：[skills/debug-optimize-lcp/references/lcp-snippets.md]()\n\n## 测试场景\n\n性能分析工具的自动化测试定义于 `scripts/eval_scenarios/performance_test.ts`：\n\n| 场景 | 预期行为 |\n|------|----------|\n| 目标 URL | `https://developers.chrome.com` |\n| 最大轮次 | 2 |\n| 预期调用 | 第一轮：导航或新建页面；第二轮：启动性能追踪 |\n\n资料来源：[scripts/eval_scenarios/performance_test.ts]()\n\n## 使用限制与注意事项\n\n1. **对话处理**：性能追踪工具（`performance_start_trace`）在有对话框打开时会被阻塞\n2. **超时配置**：使用 `timeout` 参数控制操作超时时间，避免长时间等待\n3. **文件路径**：建议为追踪文件和快照指定明确的文件路径，便于后续分析\n4. **页面选择**：Lighthouse 审计等页面工具需要先选择目标页面\n\n## 相关工具链接\n\n- 导航工具：[navigate_page](skills/chrome-devtools/SKILL.md) - 页面导航\n- 快照工具：[take_snapshot](skills/chrome-devtools/SKILL.md) - 页面结构快照\n- 模拟工具：[emulate](skills/chrome-devtools-cli/SKILL.md) - 网络和设备模拟\n\n---\n\n\n\n## 内存调试工具\n\n### 相关页面\n\n相关主题：[工具参考](#tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/memory.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/memory.ts)\n- [src/HeapSnapshotManager.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/HeapSnapshotManager.ts)\n- [src/formatters/HeapSnapshotFormatter.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/formatters/HeapSnapshotFormatter.ts)\n- [skills/memory-leak-debugging/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/memory-leak-debugging/SKILL.md)\n- [skills/memory-leak-debugging/references/compare_snapshots.js](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/memory-leak-debugging/references/compare_snapshots.js)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n \n\n# 内存调试工具\n\n## 概述\n\n内存调试工具是 chrome-devtools-mcp 提供的核心功能集之一，用于分析和诊断浏览器页面中的内存问题。这些工具通过 Chrome DevTools Protocol 与 Chromium 的堆快照引擎交互，帮助开发者识别内存泄漏、追踪对象增长，并理解 JavaScript 运行时的内存分布情况。\n\n内存调试工具的主要职责包括：\n\n- 捕获页面的堆快照（Heap Snapshot）文件\n- 加载和分析堆快照数据\n- 提供快照摘要统计信息\n- 支持与外部内存分析工具（如 Memlab）的集成\n- 包含用于手动比较快照的回退脚本\n\n资料来源：[src/tools/memory.ts:1-15]()\n\n## 架构设计\n\n### 核心组件\n\n内存调试工具的架构由以下核心组件构成：\n\n| 组件 | 文件路径 | 职责描述 |\n|------|----------|----------|\n| MemoryToolDefinitions | `src/tools/memory.ts` | 定义所有内存相关的 MCP 工具 |\n| HeapSnapshotManager | `src/HeapSnapshotManager.ts` | 管理堆快照的加载、解析和缓存 |\n| HeapSnapshotFormatter | `src/formatters/HeapSnapshotFormatter.ts` | 格式化堆快照输出为可读格式 |\n\n### 工具定义架构\n\n内存工具使用统一的工具定义框架，该框架基于 `definePageTool` 工厂函数构建。每个工具定义包含以下结构：\n\n```typescript\nexport interface BaseToolDefinition {\n name: string;\n description: string;\n annotations: {\n category: ToolCategory;\n readOnlyHint: boolean;\n conditions?: string[];\n };\n schema: Schema;\n blockedByDialog: boolean;\n}\n```\n\n资料来源：[src/tools/ToolDefinition.ts:20-35]()\n\n## 工具 API\n\n### takeMemorySnapshot\n\n**功能**：捕获当前选中页面的堆快照。\n\n```typescript\nexport const takeMemorySnapshot = definePageTool({\n name: 'take_memory_snapshot',\n description: `Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.`,\n annotations: {\n category: ToolCategory.MEMORY,\n readOnlyHint: false,\n },\n schema: {\n filePath: zod\n .string()\n .describe('A path to a .heapsnapshot file to save the heapsnapshot to.'),\n },\n blockedByDialog: true,\n handler: async (request, response, context) => {\n const page = request.page;\n context.validatePath(request.params.filePath);\n\n await page.pptrPage.captureHeapSnapshot({\n path: ensureExtension(request.params.filePath, '.heapsnapshot'),\n });\n\n response.appendResponseLine(\n `Heap snapshot saved to ${request.params.filePath}`,\n );\n },\n});\n```\n\n资料来源：[src/tools/memory.ts:16-46]()\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| filePath | string | 是 | 堆快照文件的保存路径，必须以 `.heapsnapshot` 结尾 |\n\n**执行流程**：\n\n```mermaid\ngraph TD\n A[调用 take_memory_snapshot] --> B[验证文件路径]\n B --> C[执行 pptrPage.captureHeapSnapshot]\n C --> D[保存 .heapsnapshot 文件]\n D --> E[返回成功消息]\n```\n\n**使用示例**：\n\n```bash\nchrome-devtools take_memory_snapshot \"./baseline.heapsnapshot\"\nchrome-devtools take_memory_snapshot \"./target.heapsnapshot\" --includeSnapshot true\n```\n\n### loadMemorySnapshot\n\n**功能**：加载堆快照文件并返回摘要统计信息。\n\n```typescript\nexport const exploreMemorySnapshot = defineTool({\n name: 'load_memory_snapshot',\n description:\n 'Loads a memory heapsnapshot and returns snapshot summary stats.',\n annotations: {\n category: ToolCategory.MEMORY,\n readOnlyHint: true,\n conditions: ['experimentalMemory'],\n },\n schema: {\n filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),\n },\n blockedByDialog: false,\n // ...\n});\n```\n\n资料来源：[src/tools/memory.ts:48-68]()\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| filePath | string | 是 | 要读取的堆快照文件路径 |\n\n**注意**：此工具需要 `experimentalMemory` 条件满足方可使用。\n\n## 工作流程\n\n### 基本内存调试流程\n\n```mermaid\ngraph TD\n A[1. 创建新页面或导航到目标页面] --> B[2. 使用 take_memory_snapshot 捕获基线快照]\n B --> C[3. 执行目标操作（如用户交互）]\n C --> D[4. 使用 take_memory_snapshot 捕获目标快照]\n D --> E[5. 使用 Memlab 或回退脚本分析快照]\n E --> F[6. 识别泄漏并修复]\n F --> G[7. 重复验证]\n```\n\n### 完整内存泄漏调试流程\n\n根据 SKILL.md 文档，内存泄漏调试的标准工作流程如下：\n\n#### 步骤 1：建立基线快照\n\n在执行任何操作之前，捕获页面的初始内存状态：\n\n```bash\nchrome-devtools take_memory_snapshot \"./baseline.heapsnapshot\"\n```\n\n资料来源：[skills/memory-leak-debugging/SKILL.md:1-20]()\n\n#### 步骤 2：操作并捕获目标快照\n\n执行可能存在内存泄漏的操作（如重复用户交互），然后再次捕获快照：\n\n```bash\nchrome-devtools take_memory_snapshot \"./target.heapsnapshot\"\n```\n\n#### 步骤 3：恢复页面状态\n\n将页面恢复到原始状态，验证内存是否被正确释放：\n\n> 使用 `click`、`fill` 等工具将页面操作回原始状态，观察内存是否释放。\n\n资料来源：[skills/memory-leak-debugging/SKILL.md:21-35]()\n\n#### 步骤 4：捕获最终快照\n\n恢复操作后再次捕获快照：\n\n```bash\nchrome-devtools take_memory_snapshot \"./final.heapsnapshot\"\n```\n\n#### 步骤 5：分析对比\n\n使用 Memlab 或回退脚本分析三个快照文件。\n\n## 快照比较脚本\n\n### compare_snapshots.js\n\n当 Memlab 不可用时，可以使用项目提供的回退脚本进行快照比较。\n\n**位置**：`skills/memory-leak-debugging/references/compare_snapshots.js`\n\n**使用方法**：\n\n```bash\nnode skills/memory-leak-debugging/references/compare_snapshots.js \n```\n\n资料来源：[skills/memory-leak-debugging/references/compare_snapshots.js:1-50]()\n\n**输出内容**：\n\n| 输出部分 | 说明 |\n|----------|------|\n| Top 10 growing objects | 按大小增长排序的前 10 个对象 |\n| Top 3 common leak types | 最常见的 3 种泄漏类型 |\n\n**检测的常见泄漏类型**：\n\n```javascript\nconst commonLeaks = diffs.filter(\n d =>\n d.key.toLowerCase().includes('detached') ||\n d.key.toLowerCase().includes('html') ||\n d.key.toLowerCase().includes('eventlistener') ||\n d.key.toLowerCase().includes('context') ||\n d.key.toLowerCase().includes('closure'),\n);\n```\n\n资料来源：[skills/memory-leak-debugging/references/compare_snapshots.js:40-52]()\n\n### 输出示例\n\n脚本会输出类似以下格式的结果：\n\n```\n--- Top 10 growing objects by size ---\nDetached HTMLDivElement: +5 objects, +2048 bytes\nClosure: +12 objects, +1024 bytes\n\n--- Top 3 most common types of memory leaks found ---\nDetached HTMLDivElement: +5 objects, +2048 bytes\nEventListener: +3 objects, +512 bytes\nContext: +2 objects, +256 bytes\n```\n\n## 常见内存泄漏类型\n\n根据项目文档，堆快照分析中最常见的泄漏类型包括：\n\n| 泄漏类型 | 描述 | 检测关键词 |\n|----------|------|------------|\n| Detached DOM nodes | 已从 DOM 树移除但仍被 JavaScript 引用的 DOM 节点 | `detached`, `html` |\n| Closures | 形成闭包并捕获外部变量的函数 | `closure` |\n| Event Listeners | 未正确移除的事件监听器 | `eventlistener` |\n| Contexts | JavaScript 执行上下文未正确释放 | `context` |\n\n资料来源：[skills/memory-leak-debugging/references/compare_snapshots.js:43-49]()\n\n## 使用限制与注意事项\n\n### 工具阻塞条件\n\n`takeMemorySnapshot` 工具配置了 `blockedByDialog: true`，这意味着当页面上存在对话框时，该工具将被阻塞：\n\n> **blockedByDialog**: 如果设置为 `true`，则工具在页面存在对话框时无法执行。\n\n资料来源：[src/tools/memory.ts:38-39]()\n\n### 路径验证\n\n所有文件路径在执行前都会经过验证，确保快照文件能够正确保存到指定位置：\n\n```typescript\ncontext.validatePath(request.params.filePath);\n```\n\n资料来源：[src/tools/memory.ts:41]()\n\n### 文件扩展名强制\n\n脚本会自动为文件路径添加 `.heapsnapshot` 扩展名：\n\n```typescript\nawait page.pptrPage.captureHeapSnapshot({\n path: ensureExtension(request.params.filePath, '.heapsnapshot'),\n});\n```\n\n资料来源：[src/tools/memory.ts:43-45]()\n\n## 集成外部工具\n\n### Memlab 集成\n\n项目推荐使用 Memlab 进行高级内存泄漏分析。使用 `take_memory_snapshot` 生成 `.heapsnapshot` 文件后，可参考 `references/memlab.md` 文档进行详细分析。\n\n> **重要提示**：不要使用 `read_file` 或 `cat` 命令直接读取原始的 `.heapsnapshot` 文件。\n\n资料来源：[skills/memory-leak-debugging/SKILL.md:36-50]()\n\n## 命令行使用\n\n### 基本命令\n\n```bash\n# 捕获堆快照\nchrome-devtools take_memory_snapshot \"./snap.heapsnapshot\"\n\n# 加载并分析快照\nchrome-devtools load_memory_snapshot \"./snap.heapsnapshot\"\n```\n\n### 完整示例\n\n```bash\n# 1. 导航到目标页面\nchrome-devtools navigate_page --url \"https://example.com\"\n\n# 2. 捕获基线快照\nchrome-devtools take_memory_snapshot \"./baseline.heapsnapshot\"\n\n# 3. 执行测试操作（重复 10 次以放大泄漏）\nchrome-devtools click \"button\" # 执行操作\nchrome-devtools click \"button\" # 重复操作\n# ... 重复 10 次\n\n# 4. 捕获目标快照\nchrome-devtools take_memory_snapshot \"./target.heapsnapshot\"\n\n# 5. 恢复页面状态\n# ... 执行恢复操作\n\n# 6. 捕获最终快照\nchrome-devtools take_memory_snapshot \"./final.heapsnapshot\"\n\n# 7. 使用回退脚本分析\nnode skills/memory-leak-debugging/references/compare_snapshots.js ./baseline.heapsnapshot ./target.heapsnapshot\n```\n\n## 相关文件索引\n\n| 文件 | 描述 |\n|------|------|\n| `src/tools/memory.ts` | 内存工具的核心定义文件 |\n| `src/HeapSnapshotManager.ts` | 堆快照管理器实现 |\n| `src/formatters/HeapSnapshotFormatter.ts` | 堆快照格式化器 |\n| `skills/memory-leak-debugging/SKILL.md` | 内存泄漏调试技能文档 |\n| `skills/memory-leak-debugging/references/compare_snapshots.js` | 快照比较回退脚本 |\n| `skills/memory-leak-debugging/references/common-leaks.md` | 常见泄漏类型参考文档 |\n\n---\n\n\n\n## CLI与配置\n\n### 相关页面\n\n相关主题：[MCP客户端集成](#mcp-client-integration), [快速开始指南](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/bin/chrome-devtools-mcp-cli-options.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-mcp-cli-options.ts)\n- [src/bin/chrome-devtools-mcp-main.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-mcp-main.ts)\n- [docs/cli.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/cli.md)\n- [puppeteer.config.cjs](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/puppeteer.config.cjs)\n- [src/tools/categories.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts)\n- [src/bin/chrome-devtools-cli-options.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-cli-options.ts)\n- [scripts/generate-cli.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-cli.ts)\n \n\n# CLI与配置\n\n## 概述\n\nchrome-devtools-mcp 提供了完整的命令行界面（CLI）和灵活的配置系统，支持通过命令行参数启动 MCP 服务器、管理浏览器生命周期、以及自动化浏览器操作。该项目采用 TypeScript 开发，使用 Puppeteer 作为底层浏览器自动化引擎，并通过 MCP（Model Context Protocol）协议与 AI 代理进行通信。资料来源：[AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[chrome-devtools-mcp CLI] --> B[chrome-devtools-mcp-main.ts]\n A --> C[chrome-devtools-mcp-cli-options.ts]\n B --> D[Puppeteer Browser]\n C --> E[命令行参数解析]\n F[puppeteer.config.cjs] --> D\n G[MCP Server] --> H[工具层]\n H --> I[Page Tools]\n H --> J[Navigation Tools]\n H --> K[Performance Tools]\n H --> L[Network Tools]\n```\n\n### 启动流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as CLI解析器\n participant Main as 主程序\n participant Browser as Puppeteer浏览器\n participant MCP as MCP服务器\n \n User->>CLI: 执行命令 + 参数\n CLI->>CLI: parseArguments() 验证参数\n CLI->>Main: 传递解析后的配置\n Main->>Browser: 启动Chrome实例\n Browser-->>Main: Browser实例就绪\n Main->>MCP: 初始化MCP服务\n MCP-->>User: 暴露工具列表\n```\n\n## 命令行接口\n\n### 全局命令\n\n| 命令 | 功能 | 说明 |\n|------|------|------|\n| `start` | 启动服务 | 启动或重启 chrome-devtools-mcp |\n| `status` | 检查状态 | 检查 chrome-devtools-mcp 是否运行 |\n| `stop` | 停止服务 | 停止正在运行的 chrome-devtools-mcp |\n| `help` | 帮助信息 | 显示命令帮助和使用方法 |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:50-53](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 工具命令\n\nCLI 支持直接调用 MCP 工具进行浏览器自动化操作，基本语法如下：\n\n```sh\nchrome-devtools [arguments] [flags]\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:21](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 输出格式\n\n默认输出为 Markdown 格式，可通过 `--output-format` 参数切换：\n\n```sh\nchrome-devtools take_snapshot --output-format=json\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:23](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## 命令行参数配置\n\n### 参数解析模块\n\n参数解析由 `chrome-devtools-mcp-cli-options.ts` 实现，核心类型定义如下：\n\n```typescript\ninterface ParsedArguments {\n tool?: string;\n args?: string[];\n flags?: Flags;\n}\n\ninterface Flags {\n port?: number;\n host?: string;\n viaCli?: boolean;\n experimentalVision?: boolean;\n experimentalScreencast?: boolean;\n categoryExtensions?: boolean;\n categoryExperimentalWebmcp?: boolean;\n // ... 其他配置项\n}\n```\n\n资料来源：[scripts/generate-cli.ts:18-28](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-cli.ts)\n\n### 工具类别配置\n\n工具按功能分类管理，通过 `--category-*` 标志启用：\n\n| 类别标志 | 功能 | 默认状态 |\n|----------|------|----------|\n| `--categoryExperimentalWebmcp` | WebMCP 实验性工具 | 关闭 |\n| `--categoryExtensions` | Chrome 扩展管理 | 关闭 |\n| `--experimentalVision` | 视觉坐标点击 | 关闭 |\n| `--experimentalScreencast` | 屏幕录制功能 | 关闭 |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:49-51](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 必需标志构建\n\n工具类别标志通过 `buildFlag` 函数动态构建：\n\n```typescript\nimport {buildFlag} from '../build/src/index.js';\n\n// 生成标志名\nconst categoryFlag = buildFlag(category);\nconst flagName = `--${categoryFlag}`;\n```\n\n资料来源：[scripts/generate-docs.ts:72-76](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)\n\n### 默认关闭的类别\n\n部分工具类别默认不启用，需要显式启用：\n\n```typescript\nexport const OFF_BY_DEFAULT_CATEGORIES = [\n ToolCategory.WEBMCP,\n ToolCategory.EXTENSION,\n ToolCategory.EXPERIMENTAL,\n];\n```\n\n资料来源：[scripts/generate-docs.ts:24-28](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)\n\n## 工具分类体系\n\n### 分类定义\n\n```mermaid\ngraph LR\n A[ToolCategory] --> B[NAVIGATION]\n A --> C[INPUT]\n A --> D[PERFORMANCE]\n A --> E[NETWORK]\n A --> F[EXTENSION]\n A --> G[WEBMCP]\n A --> H[EXPERIMENTAL]\n```\n\n### 分类标签映射\n\n| 分类枚举 | 中文标签 | 说明 |\n|----------|----------|------|\n| `NAVIGATION` | 导航 | 页面导航和页面管理工具 |\n| `INPUT` | 输入 | 用户交互和元素操作 |\n| `PERFORMANCE` | 性能 | 性能分析和追踪 |\n| `NETWORK` | 网络 | 网络请求监控 |\n| `EXTENSION` | 扩展 | Chrome 扩展管理 |\n| `WEBMCP` | WebMCP | 网页暴露的 MCP 工具 |\n| `EXPERIMENTAL` | 实验性 | 实验功能 |\n\n资料来源：[scripts/generate-docs.ts:29-40](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)\n\n## 浏览器配置\n\n### Puppeteer 配置\n\n通过 `puppeteer.config.cjs` 配置文件管理浏览器实例：\n\n```javascript\nmodule.exports = {\n puppeteer: {\n // 浏览器启动参数\n args: [\n '--no-sandbox',\n '--disable-setuid-sandbox',\n '--disable-dev-shm-usage',\n ],\n // 用户数据目录（持久化配置）\n userDataDir: './chrome-profile',\n // 调试端口\n debugPort: 9222,\n },\n};\n```\n\n资料来源：[puppeteer.config.cjs](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/puppeteer.config.cjs)\n\n### 浏览器生命周期\n\n浏览器使用持久化 Chrome 配置文件，首次调用工具时自动启动：\n\n```mermaid\nstateDiagram-v2\n [*] --> 未启动: 程序初始化\n 未启动 --> 运行中: 首次工具调用\n 运行中 --> 运行中: 工具操作\n 运行中 --> 已停止: stop命令\n 已停止 --> 运行中: start命令\n 已停止 --> [*]: 程序退出\n```\n\n资料来源：[skills/chrome-devtools/SKILL.md:8-9](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n### 页面管理\n\n工具操作作用于当前选中的页面，支持多页面管理：\n\n```sh\nchrome-devtools list_pages # 列出所有打开的页面\nchrome-devtools select_page 1 # 选择页面作为上下文\nchrome-devtools select_page 1 --bringToFront true # 选择并激活\nchrome-devtools close_page 1 # 关闭指定页面\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:27-38](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## 网络与模拟配置\n\n### 网络条件模拟\n\n```sh\n# 离线模拟\nchrome-devtools emulate --networkConditions \"Offline\"\n\n# 自定义网络节流\nchrome-devtools emulate --networkConditions \"Slow 3G\"\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:41-44](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 设备模拟\n\n| 参数 | 说明 | 示例值 |\n|------|------|--------|\n| `--viewport` | 视口尺寸 | `1920x1080` |\n| `--colorScheme` | 颜色方案 | `dark`, `light` |\n| `--cpuThrottlingRate` | CPU 节流倍率 | `4` (4x) |\n| `--geolocation` | 地理位置 | `0x0` |\n| `--userAgent` | 用户代理字符串 | Mozilla/5.0... |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:44-48](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 使用示例\n\n```sh\n# 模拟暗黑模式和全高清视口\nchrome-devtools emulate --colorScheme \"dark\" --viewport \"1920x1080\"\n\n# 模拟 CPU 节流和特定地理位置\nchrome-devtools emulate --cpuThrottlingRate 4 --geolocation \"0x0\"\n\n# 模拟自定义用户代理\nchrome-devtools emulate --userAgent \"Mozilla/5.0...\"\n\n# 调整页面窗口大小\nchrome-devtools resize_page 1920 1080\n```\n\n## 实验性功能\n\n### 启用方式\n\n实验性功能默认禁用，需通过相应标志启用：\n\n```sh\nchrome-devtools-mcp --experimentalVision=true --experimentalScreencast=true\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:49-51](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 实验性工具列表\n\n| 工具 | 功能 | 必需标志 |\n|------|------|----------|\n| `click_at` | 坐标点击 | `--experimentalVision=true` |\n| `screencast_start` | 屏幕录制 | `--experimentalScreencast=true` |\n| `screencast_stop` | 停止录制 | `--experimentalScreencast=true` |\n| `list_webmcp_tools` | 列出 WebMCP 工具 | `--categoryExperimentalWebmcp=true` |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:49-55](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## CLI 选项自动生成\n\n### 生成流程\n\n项目使用脚本自动从运行时工具定义生成 CLI 选项：\n\n```mermaid\ngraph TD\n A[generate-cli.ts] --> B[启动 MCP 服务器]\n B --> C[调用 listTools API]\n C --> D[解析工具定义]\n D --> E[生成 TypeScript 代码]\n E --> F[输出到 chrome-devtools-cli-options.ts]\n```\n\n资料来源：[scripts/generate-cli.ts:30-55](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-cli.ts)\n\n### 生成的代码结构\n\n生成的 `chrome-devtools-cli-options.ts` 包含所有工具的 CLI 接口定义：\n\n```typescript\n// 通过 MCP 协议连接本地服务器获取工具定义\nconst transport = new StdioClientTransport({\n command: 'node',\n args: [serverPath, '--viaCli'],\n env: {...process.env, CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true'},\n});\n```\n\n资料来源：[scripts/generate-cli.ts:36-42](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-cli.ts)\n\n## 构建与测试\n\n### 构建命令\n\n```sh\nnpm run build # 运行 tsc 编译并测试构建\n```\n\n资料来源：[AGENTS.md:5](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n\n### 测试命令\n\n```sh\nnpm run test # 构建并运行所有测试\nnpm run test path-to-test.ts # 构建并运行单个测试文件\n```\n\n资料来源：[AGENTS.md:6-8](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n\n### 代码格式\n\n```sh\nnpm run format # 修复格式问题和 linting 错误\n```\n\n资料来源：[AGENTS.md:11](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n\n## 扩展管理配置\n\n### 扩展操作命令\n\n| 命令 | 功能 |\n|------|------|\n| `list_extensions` | 列出已安装的扩展 |\n| `install_extension` | 安装扩展（需要路径） |\n| `uninstall_extension` | 卸载扩展（需要 ID） |\n| `reload_extension` | 重载扩展 |\n| `trigger_extension_action` | 触发扩展默认操作 |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:48-50](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 启用扩展支持\n\n扩展功能默认关闭，需要通过 `--categoryExtensions` 标志启用：\n\n```sh\nchrome-devtools-mcp --categoryExtensions=true\n```\n\n资料来源：[skills/chrome-devtools/SKILL.md:8-9](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n## 性能追踪配置\n\n### 追踪命令\n\n```sh\n# 开始追踪\nchrome-devtools performance_start_trace true false\n\n# 带文件输出\nchrome-devtools performance_start_trace true true --filePath t.gz\n\n# 停止追踪\nchrome-devtools performance_stop_trace\n\n# 保存到文件\nchrome-devtools performance_stop_trace --filePath \"t.json\"\n\n# 获取性能洞察\nchrome-devtools performance_analyze_insight \"1\" \"LCPBreakdown\"\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:32-40](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### 内存快照\n\n```sh\nchrome-devtools take_memory_snapshot \"./snap.heapsnapshot\"\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:41-42](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## 环境变量\n\n| 变量名 | 功能 | 说明 |\n|--------|------|------|\n| `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` | 禁用使用统计 | 设为 `true` 可禁用遥测 |\n| `PATH` | 系统路径 | 需包含全局 npm bin 目录 |\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:13](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/references/installation.md)\n\n## 常见配置问题排查\n\n### 问题诊断步骤\n\n1. 检查服务状态：`chrome-devtools status`\n2. 查看详细日志：启动时添加 `--logFile=/tmp/cdm-test.log`\n3. 分析日志输出中的错误信息\n\n资料来源：[skills/troubleshooting/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/troubleshooting/SKILL.md)\n\n### 权限错误处理\n\n遇到 `EACCES` 权限错误时，建议：\n- 使用 `nvm` 管理 Node.js 版本\n- 配置 npm 使用不同的全局目录\n- 避免使用 `sudo` 安装全局包\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:16-18](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/references/installation.md)\n\n---\n\n\n\n## MCP客户端集成\n\n### 相关页面\n\n相关主题：[快速开始指南](#quick-start), [CLI与配置](#cli-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/README.md)\n- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n- [.mcp.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/.mcp.json)\n- [gemini-extension.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/gemini-extension.json)\n- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n- [src/McpResponse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [package.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/package.json)\n \n\n# MCP客户端集成\n\n## 概述\n\nMCP（Model Context Protocol）客户端集成是 chrome-devtools-mcp 项目的核心功能，它允许外部AI助手（如 Claude、Gemini 等）通过标准化的 MCP 协议与 Chrome DevTools 进行交互。该集成使得AI代理能够控制浏览器、执行自动化任务、采集页面快照以及进行性能调试。\n\n本项目实现了一个 MCP 服务器，通过 WebMCP 工具接口扩展了标准的 DevTools 功能，使 AI 客户端能够以结构化的方式与浏览器进行双向通信。资料来源：[AGENTS.md:1-3]()\n\n## 架构设计\n\n### 整体架构\n\nchrome-devtools-mcp 采用客户端-服务器架构，通过 MCP 协议实现 AI 助手与浏览器自动化之间的桥梁。\n\n```mermaid\ngraph TD\n subgraph AI客户端层\n A[Claude / Gemini 等] \n end\n \n subgraph MCP协议层\n B[MCP 客户端]\n C[MCP 服务器]\n end\n \n subgraph 浏览器层\n D[Chrome DevTools Protocol]\n E[浏览器实例]\n end\n \n A -->|MCP 协议| B\n B -->|MCP 请求| C\n C -->|CDP 命令| D\n D -->|CDP 响应| C\n C -->|MCP 响应| B\n B -->|MCP 响应| A\n \n D -->|控制| E\n E -->|反馈| D\n```\n\n### 核心组件\n\n| 组件名称 | 文件位置 | 功能描述 |\n|---------|---------|---------|\n| MCPResponse | `src/McpResponse.ts` | 处理 MCP 协议响应序列化与格式化 |\n| webmcp | `src/tools/webmcp.ts` | 定义 WebMCP 工具接口 |\n| ToolDefinition | `src/tools/ToolDefinition.ts` | 工具定义与参数模式抽象 |\n| 工具集合 | `src/tools/*.ts` | 具体工具实现（输入、导航、快照等）|\n\n## 客户端配置\n\n### .mcp.json 配置格式\n\nMCP 客户端通过 `.mcp.json` 配置文件声明服务器连接。配置文件采用 JSON 格式定义服务器路径和可选参数。\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"node\",\n \"args\": [\"path/to/cli.js\", \"--headless\"]\n }\n }\n}\n```\n\n资料来源：[.mcp.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/.mcp.json)\n\n### Gemini 扩展配置\n\n针对 Google Gemini 平台的特殊集成配置：\n\n```json\n{\n \"name\": \"chrome-devtools\",\n \"description\": \"...\",\n \"entry_point\": \"...\",\n \"runtime\": \"...\",\n \"permissions\": [\"browser\"]\n}\n```\n\n资料来源：[gemini-extension.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/gemini-extension.json)\n\n### 运行时环境要求\n\n项目对 Node.js 版本有明确的兼容性要求：\n\n| 版本范围 | 支持状态 |\n|---------|---------|\n| `^20.19.0` | 主要支持 |\n| `^22.12.0` | 主要支持 |\n| `>=23` | 兼容支持 |\n\n资料来源：[package.json:48-51]()\n\n## WebMCP 工具接口\n\nWebMCP 是项目定义的扩展协议，允许网页向 MCP 客户端暴露自定义工具。核心接口包含两个工具：\n\n### list_webmcp_tools\n\n列出当前页面暴露的所有 WebMCP 工具。\n\n```typescript\nexport const listWebMcpTools = definePageTool({\n name: 'list_webmcp_tools',\n description: `Lists all WebMCP tools the page exposes.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: true,\n },\n schema: {},\n blockedByDialog: false,\n handler: async (_request, response, _context) => {\n response.setListWebMcpTools();\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts:14-24]()\n\n### execute_webmcp_tool\n\n执行页面暴露的 WebMCP 工具。\n\n```typescript\nexport const executeWebMcpTool = definePageTool({\n name: 'execute_webmcp_tool',\n description: `Executes a WebMCP tool exposed by the page.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: false,\n },\n schema: {\n toolName: zod.string().describe('The name of the WebMCP tool to execute'),\n input: zod.string().optional().describe('The JSON-stringified parameters'),\n },\n blockedByDialog: false,\n handler: async (request, response) => {\n // 处理工具执行\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts:32-51]()\n\n## 工具定义模式\n\n### 工具类别\n\n所有工具通过 `ToolCategory` 枚举进行分类管理：\n\n| 类别标识 | 描述 |\n|--------|------|\n| `WEBMCP` | WebMCP 协议相关工具 |\n| `INPUT` | 用户输入自动化工具 |\n| `NAVIGATION` | 页面导航工具 |\n| `INSPECTION` | 页面检查工具 |\n\n### 工具定义函数\n\n项目使用工厂函数模式定义工具：\n\n```typescript\nexport function definePageTool(\n definition: PageToolDefinition\n): DefinedPageTool {\n return {\n ...definition,\n pageScoped: true,\n };\n}\n```\n\n关键特性包括：\n- **pageScoped**: 标记工具是否需要页面上下文\n- **blockedByDialog**: 标记对话框是否阻止工具执行\n- **readOnlyHint**: 提示工具是否仅读取数据\n\n资料来源：[src/tools/ToolDefinition.ts:38-50]()\n\n### 通用模式定义\n\n项目提供可复用的参数模式：\n\n```typescript\nexport const timeoutSchema = {\n timeout: zod\n .number()\n .int()\n .optional()\n .describe('Maximum wait time in milliseconds')\n .transform(value => value && value <= 0 ? undefined : value),\n};\n\nexport const pageIdSchema = {\n pageId: zod.number().optional().describe('Targets a specific page by ID'),\n};\n```\n\n资料来源：[src/tools/ToolDefinition.ts:53-68]()\n\n## MCP 响应处理\n\n### 响应数据结构\n\nMcpResponse 类负责将工具执行结果格式化为 MCP 协议兼容的响应：\n\n```typescript\nif (this.#listWebMcpTools && data.webmcpTools) {\n structuredContent.webmcpTools = data.webmcpTools.map(\n ({name, description, inputSchema, annotations}) => ({\n name,\n description,\n inputSchema,\n annotations,\n }),\n );\n}\n```\n\n资料来源：[src/McpResponse.ts:45-54]()\n\n### 响应格式化\n\n响应消息包含结构化内容与文本描述：\n\n| 格式类型 | 用途 |\n|---------|------|\n| `structuredContent` | JSON 序列化数据 |\n| `response` | 人类可读文本 |\n| `annotations` | 元数据标记 |\n\n资料来源：[src/McpResponse.ts:55-68]()\n\n## 集成工作流\n\n### 典型执行流程\n\n```mermaid\nsequenceDiagram\n participant AI as AI 客户端\n participant MCP as MCP 服务器\n participant CDP as Chrome DevTools\n \n AI->>MCP: 初始化连接\n MCP-->>AI: 连接确认\n \n AI->>MCP: list_webmcp_tools\n MCP->>CDP: 获取页面工具\n CDP-->>MCP: 工具列表\n MCP-->>AI: 工具定义\n \n AI->>MCP: execute_webmcp_tool\n MCP->>CDP: 执行工具\n CDP-->>MCP: 执行结果\n MCP-->>AI: 响应数据\n```\n\n### 页面工具调用示例\n\n1. **获取页面快照**：\n ```bash\n chrome-devtools take_snapshot\n ```\n\n2. **执行 JavaScript**：\n ```bash\n chrome-devtools evaluate_script \"document.title\"\n ```\n\n3. **页面导航**：\n ```bash\n chrome-devtools navigate_page --url \"https://example.com\"\n ```\n\n## 工具分类参考\n\n### 输入自动化工具\n\n| 工具名称 | 功能 | 参数 |\n|---------|------|------|\n| `type_text` | 模拟键盘输入 | `text`, `submitKey?` |\n| `fill` | 填充表单字段 | `id`, `text` |\n| `press_key` | 按下按键 | `key` |\n| `upload_file` | 文件上传 | `id`, `path` |\n| `drag` | 拖拽操作 | `src`, `dst` |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:14-28]()\n\n### 导航工具\n\n| 工具名称 | 功能 | 参数 |\n|---------|------|------|\n| `navigate_page` | 导航到URL | `url`, `type?`, `timeout?` |\n| `new_page` | 打开新页面 | `url` |\n| `close_page` | 关闭页面 | `index` |\n| `select_page` | 选择页面上下文 | `pageId` |\n| `list_pages` | 列出所有页面 | - |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md:1-13]()\n\n### 检查工具\n\n| 工具名称 | 功能 | 参数 |\n|---------|------|------|\n| `take_snapshot` | 获取可访问性快照 | `includeSnapshot?` |\n| `take_screenshot` | 截图 | - |\n| `evaluate_script` | 执行脚本 | `script` |\n\n## 类型系统\n\n### Schema 定义规范\n\n项目强制使用 Zod 进行运行时类型验证，禁止使用 `any` 类型：\n\n```typescript\nimport {zod} from '../third_party/index.js';\n\n// 正确做法\nconst schema = {\n key: zod.string().describe('A key or key combination'),\n};\n\n// 禁止做法\n// const bad: any = value;\n// const bad = value as SomeType;\n```\n\n资料来源：[AGENTS.md:16-24]()\n\n### 参数解析\n\n使用 `ParsedArguments` 泛型处理参数转换：\n\n```typescript\ntype ParsedArguments = {\n [key: string]: unknown;\n};\n```\n\n## 扩展与定制\n\n### 自定义工具开发\n\n1. 在 `src/tools/` 目录创建新工具文件\n2. 使用 `definePageTool` 工厂函数定义工具\n3. 实现 `handler` 异步函数处理逻辑\n4. 导出工具并注册到相应类别\n\n### 类别扩展\n\n工具类别在 `ToolCategory` 枚举中定义：\n\n```typescript\nexport enum ToolCategory {\n WEBMCP = 'webmcp',\n INPUT = 'input',\n NAVIGATION = 'navigation',\n INSPECTION = 'inspection',\n}\n```\n\n## 测试与验证\n\n### 集成测试场景\n\n项目包含多个评估场景用于验证客户端集成：\n\n| 测试场景 | 路径 | 验证内容 |\n|---------|------|---------|\n| 性能测试 | `scripts/eval_scenarios/performance_test.ts` | 性能追踪工具调用 |\n| 快照测试 | `scripts/eval_scenarios/snapshot_test.ts` | 页面内容读取 |\n| 页面选择测试 | `scripts/eval_scenarios/select_page_test.ts` | 多页面上下文切换 |\n\n资料来源：[scripts/eval_scenarios/performance_test.ts:1-22]()\n\n### 测试执行命令\n\n```bash\nnpm run test # 运行所有测试\nnpm run test tests/McpContext.test.ts # 运行单个测试文件\n```\n\n资料来源：[AGENTS.md:5-7]()\n\n## 安全考虑\n\n### 对话框阻塞机制\n\n某些工具设置 `blockedByDialog: true`，在浏览器对话框出现时会被阻塞：\n\n```typescript\n{\n blockedByDialog: true, // 对话框会阻止此工具执行\n}\n```\n\n### 只读操作提示\n\n`readOnlyHint` 注解用于提示工具是否修改浏览器状态：\n\n```typescript\n{\n readOnlyHint: true, // 提示此工具仅读取数据\n}\n```\n\n## 相关文档\n\n- [安装指南](../skills/chrome-devtools-cli/references/installation.md) - CLI 安装与配置\n- [工具参考](../skills/chrome-devtools-cli/SKILL.md) - 所有工具完整文档\n- [无障碍调试](../skills/a11y-debugging/SKILL.md) - 可访问性检查集成\n- [性能优化](../skills/debug-optimize-lcp/SKILL.md) - LCP 调试集成\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：ChromeDevTools/chrome-devtools-mcp\n\n摘要：发现 18 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…。\n\n## 1. 配置坑 · 来源证据：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling — measurements come back partially or full…\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_644cef1d4144424abe63f24528f5d082 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1955 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3275fc356e284918a94cf8c2c037caee | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2004 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1946d257bfb04c23a67250da4d584631 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1943 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：chrome-devtools-mcp: v0.20.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chrome-devtools-mcp: v0.20.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_11700367e17048138ab79571d751cec4 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：chrome-devtools-mcp: v0.22.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chrome-devtools-mcp: v0.22.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6ff69eabdc334130b7b093706390c6c1 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：chrome-devtools-mcp: v0.21.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chrome-devtools-mcp: v0.21.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_41b2681dc7ae4bbabdb071511fdc0191 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.21.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：chrome-devtools-mcp: v0.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.20.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8bef6b0b7a80406ab00a0576f82b35a7 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 运行坑 · 来源证据：chrome-devtools-mcp: v0.24.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.24.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e42176fdf7da4015ac82844a46f37c08 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.24.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 运行坑 · 来源证据：chrome-devtools-mcp: v0.26.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.26.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6cf1fa6206f48e6a9e88a5d9d00fd64 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.26.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Close empty-object tool schemas for stricter MCP client validation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Close empty-object tool schemas for stricter MCP client validation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2af67f120a9d4486998a92da71a92cb9 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2049 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：chrome-devtools-mcp: v0.25.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：chrome-devtools-mcp: v0.25.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_51ee93809f08423dbc7b6c0d3eeddc77 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.25.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | issue_or_pr_quality=unknown\n\n## 18. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：ChromeDevTools/chrome-devtools-mcp\n\n摘要：发现 18 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…。\n\n## 1. 配置坑 · 来源证据：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling — measurements come back partially or full…\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_644cef1d4144424abe63f24528f5d082 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1955 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3275fc356e284918a94cf8c2c037caee | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2004 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1946d257bfb04c23a67250da4d584631 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1943 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：chrome-devtools-mcp: v0.20.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chrome-devtools-mcp: v0.20.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_11700367e17048138ab79571d751cec4 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：chrome-devtools-mcp: v0.22.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chrome-devtools-mcp: v0.22.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6ff69eabdc334130b7b093706390c6c1 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：chrome-devtools-mcp: v0.21.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chrome-devtools-mcp: v0.21.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_41b2681dc7ae4bbabdb071511fdc0191 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.21.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：chrome-devtools-mcp: v0.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.20.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8bef6b0b7a80406ab00a0576f82b35a7 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 运行坑 · 来源证据：chrome-devtools-mcp: v0.24.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.24.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e42176fdf7da4015ac82844a46f37c08 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.24.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 运行坑 · 来源证据：chrome-devtools-mcp: v0.26.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.26.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6cf1fa6206f48e6a9e88a5d9d00fd64 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.26.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Close empty-object tool schemas for stricter MCP client validation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Close empty-object tool schemas for stricter MCP client validation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2af67f120a9d4486998a92da71a92cb9 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2049 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：chrome-devtools-mcp: v0.25.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：chrome-devtools-mcp: v0.25.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_51ee93809f08423dbc7b6c0d3eeddc77 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.25.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | issue_or_pr_quality=unknown\n\n## 18. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# chrome-devtools-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 chrome-devtools-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速开始指南。围绕“快速开始指南”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. tool-reference：工具参考。围绕“工具参考”模拟一次用户任务，不展示安装或运行结果。\n5. input-automation：输入自动化工具。围绕“输入自动化工具”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速开始指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. tool-reference\n输入：用户提供的“工具参考”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. input-automation\n输入：用户提供的“输入自动化工具”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速开始指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / tool-reference：Step 4 必须围绕“工具参考”形成一个小中间产物，并等待用户确认。\n- Step 5 / input-automation：Step 5 必须围绕“输入自动化工具”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/ChromeDevTools/chrome-devtools-mcp\n- https://github.com/ChromeDevTools/chrome-devtools-mcp#readme\n- skills/a11y-debugging/SKILL.md\n- skills/chrome-devtools/SKILL.md\n- skills/chrome-devtools-cli/SKILL.md\n- skills/debug-optimize-lcp/SKILL.md\n- skills/memory-leak-debugging/SKILL.md\n- skills/troubleshooting/SKILL.md\n- README.md\n- src/index.ts\n- package.json\n- src/bin/chrome-devtools-mcp.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 chrome-devtools-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：ChromeDevTools/chrome-devtools-mcp\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx chrome-devtools-mcp@latest\n```\n\n来源：https://github.com/ChromeDevTools/chrome-devtools-mcp#readme\n\n## 来源\n\n- repo: https://github.com/ChromeDevTools/chrome-devtools-mcp\n- docs: https://github.com/ChromeDevTools/chrome-devtools-mcp#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_4bf0f41c618044f5bad63623dbb605c1"
}