{
"canonical_name": "puppeteer/puppeteer",
"compilation_id": "pack_6748aa030b2047dab4eeaf04c91eef5f",
"created_at": "2026-05-16T06:24:57.625693+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, 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 `npm i puppeteer` 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": "npm i puppeteer",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_625faaf7f5c646308f213780b0cd0dff"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_3c1d56b2b886ac2b018813fa8a8a6f63",
"canonical_name": "puppeteer/puppeteer",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/puppeteer/puppeteer",
"slug": "puppeteer",
"source_packet_id": "phit_32eb41d0731945eebf9159709047c71b",
"source_validation_id": "dval_25fd9b42e7524484a309f55c8d5afd29"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 9416,
"github_stars": 94330,
"one_liner_en": "JavaScript API for Chrome and Firefox",
"one_liner_zh": "JavaScript API for Chrome and Firefox",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "puppeteer",
"title_zh": "puppeteer 能力包",
"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": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"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_32eb41d0731945eebf9159709047c71b",
"page_model": {
"artifacts": {
"artifact_slug": "puppeteer",
"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": "npm i puppeteer",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/puppeteer/puppeteer#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"节点式流程编排",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "JavaScript API for Chrome and Firefox"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Chrome Canary/Firefox Nightly test results",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_1aabe120a9df47a2adbd293381b50a64 | https://github.com/puppeteer/puppeteer/issues/12379 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Chrome Canary/Firefox Nightly test results",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Puppeteer v25",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_050f65ceff2a455da4a3538895a7538b | https://github.com/puppeteer/puppeteer/issues/14342 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Puppeteer v25",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: GHSA issued a false malicious package alert for puppeteer",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_55588dfbd41442fdb8a2f4f1be57e4c9 | https://github.com/puppeteer/puppeteer/issues/14986 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Bug]: GHSA issued a false malicious package alert for puppeteer",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stderr`",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_9b1ef7c38ed14c41b3e4ce786adcdf26 | https://github.com/puppeteer/puppeteer/issues/14774 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stderr`",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 (extract-zip 2.0.1)",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_5d1f448d8768460a806ab32e8d4f6997 | https://github.com/puppeteer/puppeteer/issues/14957 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 (extract-zip 2.0.1)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: `setViewport` crashes on Firefox if uncaught",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_75bddb8a74194cf7a8978853f19db23a | https://github.com/puppeteer/puppeteer/issues/14989 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Bug]: `setViewport` crashes on Firefox if uncaught",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: chrome binary is not present when installing latest chrome",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_1e85cdab2b684dda8e5c83f55b8ff7b6 | https://github.com/puppeteer/puppeteer/issues/14988 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Bug]: chrome binary is not present when installing latest chrome",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Make proxy-agent dependency optional",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_195c51e4a5e84edda14a2a79b456821c | https://github.com/puppeteer/puppeteer/issues/13775 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Feature]: Make proxy-agent dependency optional",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：browsers: v3.0.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_bf2d83568c54447fbfd3047d24be0c48 | https://github.com/puppeteer/puppeteer/releases/tag/browsers-v3.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：browsers: v3.0.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：browsers: v3.0.2",
"category": "能力坑",
"evidence": [
"community_evidence:github | cevd_c9f08632e7ee4e9485d27b864a21e462 | https://github.com/puppeteer/puppeteer/releases/tag/browsers-v3.0.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：browsers: v3.0.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：puppeteer-core: v25.0.2",
"category": "能力坑",
"evidence": [
"community_evidence:github | cevd_3a8b10a5263e4d6488e16972c8249a38 | https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v25.0.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：puppeteer-core: v25.0.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:90796663 | https://github.com/puppeteer/puppeteer | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：ng-schematics: v0.8.0",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_4e7ee6a70b1d4fb6879ab4670099d205 | https://github.com/puppeteer/puppeteer/releases/tag/ng-schematics-v0.8.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：ng-schematics: v0.8.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：puppeteer-core: v25.0.0",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_3e6a5770b15146ddab5249f1aa687cae | https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v25.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：puppeteer-core: v25.0.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：puppeteer: v25.0.0",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_9294fdbab95d446887bdb54a11df66d2 | https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-v25.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：puppeteer: v25.0.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:90796663 | https://github.com/puppeteer/puppeteer | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Chrome Canary/Firefox Nightly test results。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 553,
"forks": 9416,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 94330
},
"source_url": "https://github.com/puppeteer/puppeteer",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "JavaScript API for Chrome and Firefox",
"title": "puppeteer 能力包",
"trial_prompt": "# puppeteer - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for puppeteer/puppeteer.\n\nProject:\n- Name: puppeteer\n- Repository: https://github.com/puppeteer/puppeteer\n- Summary: JavaScript API for Chrome and Firefox\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: JavaScript API for Chrome and Firefox\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: JavaScript API for Chrome and Firefox\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n2. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. cdp-implementation: CDP Implementation. Produce one small intermediate artifact and wait for confirmation.\n4. page-api: Page API. Produce one small intermediate artifact and wait for confirmation.\n5. locators: Locators and Element Handles. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/puppeteer/puppeteer\n- https://github.com/puppeteer/puppeteer#readme\n- README.md\n- packages/puppeteer/package.json\n- packages/puppeteer/install.mjs\n- docs/guides/getting-started.md\n- packages/puppeteer-core/src/index.ts\n- packages/puppeteer-core/src/api/api.ts\n- packages/puppeteer-core/src/cdp/cdp.ts\n- packages/puppeteer-core/src/bidi/bidi.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [Bug]: GHSA issued a false malicious package alert for puppeteer（https://github.com/puppeteer/puppeteer/issues/14986）；github/github_issue: Chrome Canary/Firefox Nightly test results（https://github.com/puppeteer/puppeteer/issues/12379）；github/github_issue: [Bug]: `setViewport` crashes on Firefox if uncaught（https://github.com/puppeteer/puppeteer/issues/14989）；github/github_issue: [Bug]: chrome binary is not present when installing latest chrome（https://github.com/puppeteer/puppeteer/issues/14988）；github/github_issue: [Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 （https://github.com/puppeteer/puppeteer/issues/14957）；github/github_issue: [Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stde（https://github.com/puppeteer/puppeteer/issues/14774）；github/github_issue: [Feature]: Reducing dependencies（https://github.com/puppeteer/puppeteer/issues/13552）；github/github_issue: [Feature]: Make proxy-agent dependency optional（https://github.com/puppeteer/puppeteer/issues/13775）；github/github_issue: Puppeteer v25（https://github.com/puppeteer/puppeteer/issues/14342）；github/github_release: puppeteer-core: v25.0.2（https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v25.0.2）；github/github_release: browsers: v3.0.2（https://github.com/puppeteer/puppeteer/releases/tag/browsers-v3.0.2）；github/github_release: puppeteer-core: v25.0.1（https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v25.0.1）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: GHSA issued a false malicious package alert for puppeteer",
"url": "https://github.com/puppeteer/puppeteer/issues/14986"
},
{
"kind": "github_issue",
"source": "github",
"title": "Chrome Canary/Firefox Nightly test results",
"url": "https://github.com/puppeteer/puppeteer/issues/12379"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: `setViewport` crashes on Firefox if uncaught",
"url": "https://github.com/puppeteer/puppeteer/issues/14989"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: chrome binary is not present when installing latest chrome",
"url": "https://github.com/puppeteer/puppeteer/issues/14988"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 ",
"url": "https://github.com/puppeteer/puppeteer/issues/14957"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stde",
"url": "https://github.com/puppeteer/puppeteer/issues/14774"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature]: Reducing dependencies",
"url": "https://github.com/puppeteer/puppeteer/issues/13552"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature]: Make proxy-agent dependency optional",
"url": "https://github.com/puppeteer/puppeteer/issues/13775"
},
{
"kind": "github_issue",
"source": "github",
"title": "Puppeteer v25",
"url": "https://github.com/puppeteer/puppeteer/issues/14342"
},
{
"kind": "github_release",
"source": "github",
"title": "puppeteer-core: v25.0.2",
"url": "https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v25.0.2"
},
{
"kind": "github_release",
"source": "github",
"title": "browsers: v3.0.2",
"url": "https://github.com/puppeteer/puppeteer/releases/tag/browsers-v3.0.2"
},
{
"kind": "github_release",
"source": "github",
"title": "puppeteer-core: v25.0.1",
"url": "https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v25.0.1"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "JavaScript API for Chrome and Firefox",
"effort": "安装已验证",
"forks": 9416,
"icon": "code",
"name": "puppeteer 能力包",
"risk": "可发布",
"slug": "puppeteer",
"stars": 94330,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/puppeteer/puppeteer 项目说明书\n\n生成时间：2026-05-16 05:21:34 UTC\n\n## 目录\n\n- [Getting Started](#getting-started)\n- [System Architecture](#architecture)\n- [Package Structure](#packages)\n- [Protocol Implementations](#protocols)\n- [CDP Implementation](#cdp-implementation)\n- [WebDriver BiDi Implementation](#bidi-implementation)\n- [Page API](#page-api)\n- [Locators and Element Handles](#locators)\n- [Input Handling](#input-handling)\n- [Browser Launching](#browser-launch)\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/puppeteer/puppeteer/blob/main/README.md)\n- [packages/browsers/README.md](https://github.com/puppeteer/puppeteer/blob/main/packages/browsers/README.md)\n- [docker/README.md](https://github.com/puppeteer/puppeteer/blob/main/docker/README.md)\n- [website/README.md](https://github.com/puppeteer/puppeteer/blob/main/website/README.md)\n- [packages/puppeteer-core/src/common/Debug.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/Debug.ts)\n \n\n# Getting Started\n\n## Overview\n\nPuppeteer is a Node.js library that provides a high-level API to control Chrome, Firefox, or other browsers via the DevTools Protocol and WebDriver BiDi. It enables developers to automate browser tasks programmatically, including web scraping, page interactions, performance monitoring, and automated testing.\n\nThis guide covers the essential steps to install, configure, and run your first Puppeteer script.\n\n## Installation\n\n### Prerequisites\n\n| Requirement | Details |\n|-------------|---------|\n| Node.js | Compatible version specified in `package.json` `engines` field |\n| Package Manager | npm, yarn, or pnpm |\n| System Dependencies | OS-specific tools (see below) |\n\n### System Requirements by Browser\n\n**For Firefox downloads:**\n- Linux builds: `xz` and `bzip2` utilities required for `.tar.gz` and `.tar.bz2` archives\n- MacOS builds: `hdiutil` required for `.dmg` archives\n\n**For Chrome downloads:**\n- Linux/MacOS: `unzip`\n- Windows: `tar.exe`\n\n### Installing Puppeteer\n\nThere are two primary packages available:\n\n```bash\n# Full package - downloads compatible Chrome during installation\nnpm i puppeteer\n\n# Core package - library only, without downloading Chrome\nnpm i puppeteer-core\n```\n\nWhen installing `puppeteer`, the installation script (`install.mjs`) automatically downloads a compatible Chrome binary for your platform. The `puppeteer-core` package is designed for scenarios where you already have a browser installation or want to use a custom browser path.\n\n### Using Alternative Package Managers\n\nPuppeteer supports installation via different package managers:\n\n```bash\n# Using npm\nnpm i puppeteer\n\n# Using yarn\nyarn add puppeteer\n\n# Using pnpm\npnpm add puppeteer\n```\n\n## Quick Start Example\n\nThe following example demonstrates a complete workflow: launching a browser, navigating to a page, interacting with elements, and extracting data.\n\n```typescript\nimport puppeteer from 'puppeteer';\n// Or import puppeteer from 'puppeteer-core';\n\n// Launch the browser and open a new blank page\nconst browser = await puppeteer.launch();\nconst page = await browser.newPage();\n\n// Navigate the page to a URL\nawait page.goto('https://developer.chrome.com/');\n\n// Set the screen size\nawait page.setViewport({width: 1080, height: 1024});\n\n// Open the search menu using the keyboard\nawait page.keyboard.press('/');\n\n// Type into search box using accessible input name\nawait page.locator('::-p-aria(Search)').fill('automate beyond recorder');\n\n// Wait and click on first result\nawait page.locator('.devsite-result-item-link').click();\n\n// Locate the full title with a unique string\nconst textSelector = await page\n .locator('::-p-text(Customize and automate)')\n .waitHandle();\nconst fullTitle = await textSelector?.evaluate(el => el.textContent);\n\n// Print the full title\nconsole.log('The title of this blog post is \"%s\".', fullTitle);\n\nawait browser.close();\n```\n\n资料来源：[README.md:1-40]()\n\n## Browser Launch Configuration\n\n### Basic Launch Options\n\nThe `puppeteer.launch()` method accepts a configuration object:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `headless` | `boolean \\| 'new'` | `true` | Run browser in headless mode |\n| `executablePath` | `string` | auto-detected | Path to browser executable |\n| `args` | `string[]` | `[]` | Additional CLI arguments |\n| `protocolTimeout` | `number` | `30000` | Protocol timeout in ms |\n\n### Common Launch Arguments\n\n```typescript\nconst browser = await puppeteer.launch({\n headless: false,\n args: [\n '--no-sandbox', // Required for some container environments\n '--disable-setuid-sandbox',\n '--disable-dev-shm-usage'\n ]\n});\n```\n\n## Core Concepts\n\n### Page Navigation\n\nThe `page.goto()` method navigates to a specified URL:\n\n```typescript\nawait page.goto('https://example.com', {\n waitUntil: 'networkidle2' // Wait until network is idle\n});\n```\n\n### Viewport Configuration\n\nControl the visible area of the page:\n\n```typescript\nawait page.setViewport({\n width: 1920,\n height: 1080,\n deviceScaleFactor: 2 // For high-DPI screenshots\n});\n```\n\n### Locators\n\nPuppeteer provides a locator-based API for waiting and interacting with elements:\n\n| Selector Type | Example | Description |\n|---------------|---------|-------------|\n| CSS | `'div.class-name'` | Standard CSS selector |\n| Text | `'::-p-text(Content)'` | Match by visible text |\n| ARIA | `'::-p-aria(Role)'` | Accessible ARIA selector |\n| XPath | `'::-p-xpath(//div)'` | XPath expression |\n| Shadow DOM | Combined selectors | Query across shadow roots |\n\n资料来源：[packages/puppeteer-core/src/api/locators/locators.ts:1-50]()\n\n### Evaluating JavaScript in Page Context\n\nExecute code within the browser environment:\n\n```typescript\n// Simple evaluation\nconst title = await page.evaluate(() => document.title);\n\n// With arguments\nconst links = await page.evaluate(\n (maxCount) => {\n return Array.from(document.querySelectorAll('a'))\n .slice(0, maxCount)\n .map(a => a.href);\n },\n 10 // maxCount argument\n);\n\n// Handle evaluation for complex objects\nconst handle = await page.evaluateHandle(() => document.body);\n```\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1-60]()\n\n### Exposing Functions to the Page\n\nExpose Node.js functions to be called from browser context:\n\n```typescript\nimport fs from 'node:fs';\n\nawait page.exposeFunction('readfile', async filePath => {\n return new Promise((resolve, reject) => {\n fs.readFile(filePath, 'utf8', (err, text) => {\n if (err) reject(err);\n else resolve(text);\n });\n });\n});\n\n// Now callable from page context\nawait page.evaluate(async () => {\n const content = await window.readfile('/etc/hosts');\n console.log(content);\n});\n```\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1-35]()\n\n## Workflow Diagram\n\n```mermaid\ngraph TD\n A[Start] --> B[Install Puppeteer]\n B --> C[puppeteer.launch]\n C --> D[Create Page]\n D --> E[Configure Viewport]\n E --> F[Navigate to URL]\n F --> G{Interact with Page}\n G -->|Click| H[Locate Element]\n G -->|Type| I[Fill Input]\n G -->|Extract| J[Evaluate JavaScript]\n H --> K[Perform Action]\n I --> K\n J --> L[Extract Data]\n K --> M{More Actions?}\n M -->|Yes| G\n M -->|No| N[Close Browser]\n L --> N\n```\n\n## Media Emulation\n\n### Emulate Media Types\n\nTest how pages render under different media conditions:\n\n```typescript\nawait page.emulateMediaType('print');\n\n// Now matchMedia queries return print styles\nawait page.evaluate(() => matchMedia('print').matches); // true\n\n// Reset to default\nawait page.emulateMediaType(null);\n```\n\n### Emulate CSS Media Features\n\n```typescript\nawait page.emulateMediaFeatures([\n {name: 'prefers-color-scheme', value: 'dark'},\n {name: 'prefers-color-scheme', value: 'light'}\n]);\n```\n\n### CPU Throttling\n\nEmulate slow devices for performance testing:\n\n```typescript\n// 2x slowdown\nawait page.emulateCPUThrottling(2);\n\n// Disable throttling\nawait page.emulateCPUThrottling(null);\n```\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1-30]()\n\n## Browser Management CLI\n\nThe `@puppeteer/browsers` package provides CLI tools for managing browser installations:\n\n```bash\n# List installed browsers\nnpx @puppeteer/browsers list\n\n# Clear all installed browsers\nnpx @puppeteer/browsers clear\n\n# Install specific versions\nnpx @puppeteer/browsers install chrome@stable\nnpx @puppeteer/browsers install chromedriver@116\n\n# Install specific milestone\nnpx @puppeteer/browsers install chrome@117\n```\n\n资料来源：[packages/browsers/README.md:1-50]()\n\n## Docker Usage\n\nPuppeteer can be containerized for CI/CD environments:\n\n### Building the Image\n\n```bash\ndocker build -t puppeteer-chrome-linux .\n```\n\n### Running with Docker\n\n```bash\ndocker run -i --init --rm \\\n --cap-add=SYS_ADMIN \\\n --name puppeteer-chrome \\\n puppeteer-chrome-linux \\\n node -e \"`cat test/smoke-test.js`\"\n```\n\n**Note:** The `--cap-add=SYS_ADMIN` capability enables Chrome sandbox for enhanced security. Alternatively, start with `--no-sandbox` flag.\n\n资料来源：[docker/README.md:1-30]()\n\n## Debugging\n\nEnable debug logging to troubleshoot issues:\n\n```javascript\n// Enable specific channel\nwindow.__PUPPETEER_DEBUG='Page';\n\n// Enable all channels\nwindow.__PUPPETEER_DEBUG='*';\n\n// Enable pattern matching\nwindow.__PUPPETEER_DEBUG='foo*'; // Matches 'foo', 'foobar', etc.\n```\n\nIn Node.js environment:\n\n```typescript\nimport {debug} from './common/Debug.js';\n\nconst log = debug('Page');\nlog('new page created');\n// Output: \"Page: new page created\"\n```\n\n资料来源：[packages/puppeteer-core/src/common/Debug.ts:1-50]()\n\n## MCP Integration\n\nPuppeteer supports the Model Context Protocol for AI-assisted browser automation:\n\n### Installation\n\n```bash\nnpm install chrome-devtools-mcp\n```\n\n### WebMCP Support\n\nPuppeteer also includes experimental support for the WebMCP API, enabling AI agents to interact with browser automation:\n\n资料来源：[README.md:1-25]()\n\n## Next Steps\n\n| Topic | Description |\n|-------|-------------|\n| [Locators](https://pptr.dev/guides/locators) | Advanced element location strategies |\n| [Selectors](https://pptr.dev/guides/selectors) | CSS, text, ARIA, and XPath selectors |\n| [Page Interactions](https://pptr.dev/guides/page-interactions) | Clicking, typing, scrolling |\n| [BiDi Protocol](https://pptr.dev/guides/bi-di) | WebDriver BiDi support |\n| [Chrome Extensions](https://pptr.dev/guides/chrome-extensions) | Extension automation |\n| [API Reference](https://pptr.dev/api) | Complete API documentation |\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Package Structure](#packages), [CDP Implementation](#cdp-implementation), [WebDriver BiDi Implementation](#bidi-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/index.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/index.ts)\n- [packages/puppeteer-core/src/api/api.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/api.ts)\n- [packages/puppeteer-core/src/cdp/cdp.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/cdp.ts)\n- [packages/puppeteer-core/src/bidi/bidi.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/bidi.ts)\n- [packages/puppeteer-core/src/api/Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)\n- [packages/puppeteer-core/src/cdp/ExecutionContext.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/ExecutionContext.ts)\n- [packages/puppeteer-core/src/bidi/Realm.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Realm.ts)\n- [packages/puppeteer-core/src/api/locators/locators.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/locators/locators.ts)\n \n\n# System Architecture\n\nPuppeteer is a high-level API that provides a programmatic interface for controlling Chrome/Chromium browsers. The system architecture is designed to abstract browser automation complexities while supporting multiple protocol backends.\n\n## Architecture Overview\n\nPuppeteer uses a dual-protocol architecture that supports both Chrome DevTools Protocol (CDP) and WebDriver BiDi (BiDirectional) protocols. This design enables flexibility in browser automation while maintaining a consistent high-level API for users.\n\n```mermaid\ngraph TD\n subgraph \"User Layer\"\n User[\"User Code\"]\n end\n \n subgraph \"Public API Layer\"\n Puppeteer[\"puppeteer/puppeteer-core\"]\n Page[\"Page API\"]\n Browser[\"Browser API\"]\n end\n \n subgraph \"Protocol Abstraction Layer\"\n CDP[\"CDP Implementation\"]\n BiDi[\"BiDi Implementation\"]\n end\n \n subgraph \"Protocol Communication\"\n CDP_Protocol[\"Chrome DevTools Protocol\"]\n WebDriver_BiDi[\"WebDriver BiDi\"]\n end\n \n subgraph \"Browser Layer\"\n Chrome[\"Chrome/Chromium\"]\n Firefox[\"Firefox\"]\n end\n \n User --> Puppeteer\n Puppeteer --> Page\n Puppeteer --> Browser\n Page --> CDP\n Page --> BiDi\n CDP --> CDP_Protocol\n BiDi --> WebDriver_BiDi\n CDP_Protocol --> Chrome\n WebDriver_BiDi --> Chrome\n WebDriver_BiDi --> Firefox\n```\n\n## Core Entry Points\n\nThe main entry point for Puppeteer is defined in `index.ts`, which exports all public APIs and types. The system provides two primary packages:\n\n| Package | Purpose | Browser Download |\n|---------|---------|------------------|\n| `puppeteer` | Full package with bundled Chrome | Yes (automatic) |\n| `puppeteer-core` | Library-only, no browser download | No |\n\n资料来源：[packages/puppeteer-core/src/index.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/index.ts)\n\n## Protocol Implementations\n\n### Chrome DevTools Protocol (CDP)\n\nCDP is the native Chrome debugging protocol. The CDP implementation provides direct access to Chrome's debugging features through the `CDPSession` interface.\n\n**Key Components:**\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `CDPPuppeteer` | `cdp.ts` | Main entry point for CDP-based browser control |\n| `CDPExecutionContext` | `ExecutionContext.ts` | Executes JavaScript in page context |\n| `CDPBrowserContext` | `cdp.ts` | Manages browser contexts via CDP |\n| `CDPPage` | `cdp.ts` | Page implementation using CDP |\n\n资料来源：[packages/puppeteer-core/src/cdp/cdp.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/cdp.ts)\n\n**CDP Execution Flow:**\n\n```mermaid\nsequenceDiagram\n participant User as User Code\n participant Page as CDP Page\n participant Context as CDP ExecutionContext\n participant Client as CDPSession\n participant Chrome as Chrome Browser\n \n User->>Page: evaluate(pageFunction)\n Page->>Context: evaluate(pageFunction)\n Context->>Client: send(Runtime.evaluate)\n Client->>Chrome: Runtime.evaluate\n Chrome-->>Client: result\n Client-->>Context: result\n Context-->>Page: HandleFor\n Page-->>User: Awaited>\n```\n\nThe CDP implementation evaluates page functions by stringifying them and sending them via `Runtime.evaluate` or `Runtime.callFunctionOn` CDP commands. The source URL comment is injected for better debugging support.\n\n资料来源：[packages/puppeteer-core/src/cdp/ExecutionContext.ts:1-50](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/ExecutionContext.ts)\n\n### WebDriver BiDi Protocol\n\nWebDriver BiDi is a cross-browser protocol specification that provides a standardized bidirectional communication interface.\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `BiDiPuppeteer` | `bidi.ts` | Main entry point for BiDi-based browser control |\n| `Realm` | `Realm.ts` | BiDi execution environment |\n| `BiDiBrowserContext` | `bidi.ts` | Manages browser contexts via BiDi |\n| `BiDiPage` | `bidi.ts` | Page implementation using BiDi |\n\n资料来源：[packages/puppeteer-core/src/bidi/bidi.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/bidi.ts)\n\n**BiDi Realm Architecture:**\n\nThe `Realm` class provides the execution context for BiDi-based browser automation. It includes a lazy-loaded `puppeteerUtil` that handles internal Puppeteer operations:\n\n```typescript\nclass Realm {\n internalPuppeteerUtil?: Promise>;\n \n get puppeteerUtil(): Promise> {\n // Lazy initialization with caching\n }\n \n async evaluateHandle(pageFunction, ...args): Promise>;\n async evaluate(pageFunction, ...args): Promise>;\n}\n```\n\n资料来源：[packages/puppeteer-core/src/bidi/Realm.ts:1-60](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Realm.ts)\n\n## Abstract API Layer\n\nThe API layer defines abstract interfaces that both protocol implementations must fulfill.\n\n### Page Abstraction\n\nThe `Page` class is the central abstraction for browser tabs/pages:\n\n```mermaid\nclassDiagram\n class Page {\n <>\n +exposeFunction(name, pptrFunction)\n +$$eval(selector, pageFunction)\n +emulateMediaType(type)\n +emulateCPUThrottling(factor)\n +locator(selector) Locator\n -_isDragging: boolean\n -_timeoutSettings: TimeoutSettings\n }\n \n class CDPPage {\n +exposeFunction(name, pptrFunction)\n +$$eval(selector, pageFunction)\n }\n \n class BiDiPage {\n +exposeFunction(name, pptrFunction)\n +$$eval(selector, pageFunction)\n }\n \n Page <|-- CDPPage\n Page <|-- BiDiPage\n```\n\nKey Page features:\n\n| Feature | Description | Source |\n|---------|-------------|--------|\n| `exposeFunction` | Exposes a function to the page's JavaScript context | [Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts) |\n| `$$eval` | Evaluates a function on matching elements | [Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts) |\n| `emulateMediaType` | Emulates CSS media type | [Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts) |\n| `emulateCPUThrottling` | Simulates slow CPUs | [Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts) |\n\n## Locator System\n\nThe Locator API provides a modern, promise-based approach to element finding with automatic retry logic.\n\n```mermaid\ngraph TD\n Locator[\"Locator\"]\n FunctionLocator[\"FunctionLocator\"]\n DelegatedLocator[\"DelegatedLocator\"]\n Page[\"Page\"]\n Frame[\"Frame\"]\n \n Page --> Locator\n Frame --> Locator\n Locator <|-- FunctionLocator\n Locator <|-- DelegatedLocator\n DelegatedLocator --> Locator\n \n FunctionLocator: \"_func: () => Awaitable\"\n DelegatedLocator: \"#delegate: Locator\"\n```\n\n**Locator Types:**\n\n| Type | Purpose | Key Methods |\n|------|---------|-------------|\n| `Locator` | Base locator class | `wait()`, `map()`, `filter()` |\n| `FunctionLocator` | Locates elements using a predicate function | Uses `waitForFunction` internally |\n| `DelegatedLocator` | Wraps another locator with transformation | Delegates to another locator |\n\n资料来源：[packages/puppeteer-core/src/api/locators/locators.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/locators/locators.ts)\n\n## Event System\n\nPuppeteer uses an event-driven architecture based on `EventEmitter`:\n\n```mermaid\ngraph LR\n Page[\"Page (EventEmitter)\"]\n Request[\"Request Event\"]\n Response[\"Response Event\"]\n Console[\"Console Event\"]\n \n Page --> |emit| Request\n Page --> |emit| Response\n Page --> |emit| Console\n \n User1[\"page.on('request', handler)\"]\n User2[\"page.on('response', handler)\"]\n User3[\"page.on('console', handler)\"]\n \n Request --> User1\n Response --> User2\n Console --> User3\n```\n\nThe `Page` class extends `EventEmitter` and emits events documented in the `PageEvent` enum:\n\n```typescript\npage.once('load', () => console.log('Page loaded!'));\npage.on('request', logRequest);\npage.off('request', logRequest);\n```\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1-100](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)\n\n## Lazy Evaluation (LazyArg)\n\nThe `LazyArg` system enables deferred argument evaluation within page context:\n\n```mermaid\ngraph TD\n User[\"User Code\"]\n Lazy[\"LazyArg.create(callback)\"]\n Context[\"PuppeteerUtilWrapper\"]\n Eval[\"evaluate()\"]\n \n User --> Lazy\n Lazy --> Eval\n Eval --> Context\n Context --> |get| Lazy\n```\n\n```typescript\nclass LazyArg {\n static create = (\n get: (context: PuppeteerUtilWrapper) => Promise | T\n ): T => {\n return new LazyArg(get) as unknown as T;\n };\n \n async get(context: Context): Promise {\n return await this.#get(context);\n }\n}\n```\n\n资料来源：[packages/puppeteer-core/src/common/LazyArg.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/LazyArg.ts)\n\n## Device Emulation\n\nPuppeteer provides pre-configured device profiles for emulation:\n\n```typescript\nimport {KnownDevices} from 'puppeteer';\nconst iPhone = KnownDevices['iPhone 15 Pro'];\n\nconst page = await browser.newPage();\nawait page.emulate(iPhone);\n```\n\n| Category | Devices Included |\n|----------|------------------|\n| iPhone | iPhone 4, 5, 6, 7, 8, X, 11, 12, 13, 14, 15 series |\n| iPad | Various iPad models |\n| Android | Nexus, Pixel devices |\n| Desktop | Chrome, Firefox, Safari viewports |\n\n资料来源：[packages/puppeteer-core/src/common/Device.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/Device.ts)\n\n## Debug System\n\nThe debug module provides channel-based logging:\n\n```typescript\nconst log = debug('Page');\nlog('new page created');\n// Output: \"Page: new page created\"\n```\n\n**Configuration:**\n\n| Environment Variable | Effect |\n|---------------------|--------|\n| `window.__PUPPETEER_DEBUG='*'` | Enable all logging |\n| `window.__PUPPETEER_DEBUG='foo'` | Log only 'foo' channel |\n| `window.__PUPPETEER_DEBUG='foo*'` | Log all channels starting with 'foo' |\n\n资料来源：[packages/puppeteer-core/src/common/Debug.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/Debug.ts)\n\n## Architecture Summary\n\n```mermaid\ngraph TD\n subgraph \"User Applications\"\n Scripts[\"Automation Scripts\"]\n Tests[\"Test Frameworks\"]\n Scrapers[\"Web Scrapers\"]\n end\n \n subgraph \"puppeteer/puppeteer-core\"\n API[\"Public API (Page, Browser, Frame)\"]\n Locator[\"Locator API\"]\n Event[\"Event System\"]\n end\n \n subgraph \"Protocol Adapters\"\n CDP[\"CDP Adapter\"]\n BiDi[\"BiDi Adapter\"]\n end\n \n subgraph \"Browser Runtimes\"\n Chrome[\"Chrome/Chromium\"]\n Firefox[\"Firefox\"]\n Edge[\"Edge\"]\n end\n \n Scripts --> API\n Tests --> API\n Scrapers --> API\n \n API --> Locator\n API --> Event\n \n API --> CDP\n API --> BiDi\n \n CDP --> Chrome\n CDP --> Edge\n BiDi --> Chrome\n BiDi --> Firefox\n BiDi --> Edge\n```\n\n## Key Design Principles\n\n1. **Protocol Abstraction**: Both CDP and BiDi provide equivalent functionality through a unified API\n2. **Lazy Evaluation**: Arguments are evaluated only when needed within the browser context\n3. **Event-Driven**: Asynchronous operations use observable patterns for extensibility\n4. **Device Emulation**: Built-in device profiles ensure consistent cross-device testing\n5. **Debugging Support**: Channel-based logging enables granular troubleshooting\n\n---\n\n\n\n## Package Structure\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Browser Launching](#browser-launch)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/package.json](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/package.json)\n- [packages/puppeteer-core/src/puppeteer-core.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/puppeteer-core.ts)\n- [packages/puppeteer-core/src/puppeteer-core-browser.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/puppeteer-core-browser.ts)\n- [packages/browsers/src/main.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/browsers/src/main.ts)\n- [packages/ng-schematics/package.json](https://github.com/puppeteer/puppeteer/blob/main/packages/ng-schematics/package.json)\n \n\n# Package Structure\n\nPuppeteer is a comprehensive Node.js library that provides a high-level API to control Chrome, Firefox, and other browsers via the DevTools Protocol. The project is organized as a monorepo containing multiple packages that serve distinct purposes while maintaining a cohesive architecture.\n\n## Overview\n\nThe Puppeteer repository follows a multi-package architecture designed to separate concerns between browser automation logic, browser launching utilities, and framework-specific integrations.\n\n```mermaid\ngraph TD\n A[Puppeteer Core] --> B[Browser Launchers]\n A --> C[Page API]\n A --> D[Locator API]\n B --> E[Chrome Driver]\n B --> F[Firefox Driver]\n C --> G[CDP Execution]\n D --> H[Locator Implementations]\n```\n\n## Package Organization\n\nThe repository contains the following primary packages located in the `packages/` directory:\n\n| Package | Purpose | Entry Point |\n|---------|---------|-------------|\n| `puppeteer` | Full Puppeteer distribution with bundled Chrome | Main npm package |\n| `puppeteer-core` | Core library without browser binaries | `src/puppeteer-core.ts` |\n| `@puppeteer/browsers` | Browser management CLI and API | `packages/browsers/src/main.ts` |\n| `ng-schematics` | Angular schematics for Puppeteer | Angular integration |\n\n### puppeteer-core\n\nThe `puppeteer-core` package serves as the foundation for all browser automation functionality. It provides the complete API surface for launching browsers, creating pages, and executing automation tasks.\n\n**Location:** `packages/puppeteer-core/`\n\n**Key Characteristics:**\n\n- Does not download browser binaries during installation\n- Compatible with any browser implementation that supports DevTools Protocol\n- Requires explicit `executablePath` configuration when not using bundled browsers\n\n**Source Files:**\n\n| File | Purpose |\n|------|---------|\n| `src/puppeteer-core.ts` | Main entry point, exports primary API |\n| `src/puppeteer-core-browser.ts` | Browser class implementation |\n| `src/api/Page.ts` | Abstract Page class definition |\n| `src/api/locators/locators.ts` | Locator implementations |\n| `src/common/Configuration.ts` | Configuration interfaces |\n| `src/cdp/ExecutionContext.ts` | CDP execution context |\n\nThe package exports key classes including `Browser`, `Page`, `Frame`, `Locator`, and various configuration types that enable programmatic browser control.\n\n### Browser Launchers (`@puppeteer/browsers`)\n\nThe `@puppeteer/browsers` package provides both a CLI interface and programmatic API for managing browser installations. It handles downloading, caching, and launching of browser binaries.\n\n**CLI Commands:**\n\n| Command | Description |\n|---------|-------------|\n| `npx @puppeteer/browsers install` | Download browser binaries |\n| `npx @puppeteer/browsers clear` | Remove installed browsers |\n| `npx @puppeteer/browsers list` | Display installed browsers |\n| `npx @puppeteer/browsers launch` | Launch a specific browser |\n\n**Supported Browsers:**\n\n- Chrome for Testing (Stable, Beta, Dev, Canary)\n- ChromeDriver (matching versions)\n- Firefox\n\n**Installation Examples:**\n\n```bash\n# Install latest stable Chrome\nnpx @puppeteer/browsers install chrome@stable\n\n# Install specific version\nnpx @puppeteer/browsers install chrome@116.0.5793.0\n\n# Install latest ChromeDriver for Canary\nnpx @puppeteer/browsers install chromedriver@canary\n```\n\n### Angular Schematics (`ng-schematics`)\n\nThe `ng-schematics` package provides Angular-specific tooling for integrating Puppeteer into Angular projects through the Angular CLI.\n\n**Location:** `packages/ng-schematics/package.json`\n\nThis package enables Angular developers to scaffold and configure Puppeteer within their applications using standard Angular CLI commands.\n\n## Module Architecture\n\n### Core API Structure\n\nThe Puppeteer Core API is organized hierarchically with clear separation between different functional areas:\n\n```mermaid\ngraph BT\n A[Browser] --> B[Page]\n A --> C[Target]\n B --> D[Frame]\n B --> E[Locator]\n D --> F[ExecutionContext]\n F --> G[JSHandle]\n```\n\n### Key Entry Points\n\nThe main entry point `packages/puppeteer-core/src/puppeteer-core.ts` exports all public APIs:\n\n- `puppeteer.launch()` - Launch a browser instance\n- `puppeteer.connect()` - Connect to an existing browser\n- `Browser` class - Represents a browser instance\n- `Page` class - Represents a single page or tab\n- `Frame` class - Represents an iframe within a page\n- `Locator` classes - Fluent locator implementations for element queries\n\nThe browser-specific entry point `packages/puppeteer-core/src/puppeteer-core-browser.ts` provides implementation details for browser lifecycle management.\n\n### Common Utilities\n\nSeveral utility modules support the core functionality:\n\n| Module | Location | Purpose |\n|--------|----------|---------|\n| `LazyArg` | `src/common/LazyArg.ts` | Deferred argument evaluation for page functions |\n| `Device` | `src/common/Device.ts` | Predefined device descriptors for emulation |\n| `Debug` | `src/common/Debug.ts` | Debug logging infrastructure |\n| `Configuration` | `src/common/Configuration.ts` | Global and per-browser configuration |\n\n### Launch Options\n\nBrowser launch behavior is configured through `LaunchOptions` interface in `packages/puppeteer-core/src/node/LaunchOptions.ts`:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `executablePath` | `string` | bundled | Path to browser executable |\n| `ignoreDefaultArgs` | `boolean \\| string[]` | `false` | Skip default arguments |\n| `enableExtensions` | `boolean \\| string[]` | - | Enable browser extensions |\n| `handleSIGINT` | `boolean` | `true` | Close on Ctrl+C |\n| `handleSIGTERM` | `boolean` | `true` | Close on SIGTERM |\n| `handleSIGHUP` | `boolean` | `true` | Close on SIGHUP |\n| `timeout` | `number` | `30000` | Startup timeout in ms |\n\n## Directory Structure\n\n```\npuppeteer/\n├── packages/\n│ ├── puppeteer-core/\n│ │ ├── src/\n│ │ │ ├── api/ # Public API definitions\n│ │ │ │ ├── Page.ts\n│ │ │ │ └── locators/\n│ │ │ ├── cdp/ # CDP-specific implementations\n│ │ │ ├── common/ # Shared utilities\n│ │ │ ├── injected/ # Injected scripts\n│ │ │ └── node/ # Node.js specific code\n│ │ └── package.json\n│ ├── browsers/\n│ │ ├── src/\n│ │ │ └── main.ts # CLI entry point\n│ │ └── README.md\n│ └── ng-schematics/\n├── examples/ # Official usage examples\n├── website/ # Documentation site\n├── docker/ # Docker configuration\n└── tools/ # Development tools\n```\n\n## Configuration System\n\n### Global Configuration\n\nConfiguration is defined through `ChromeSettings`, `FirefoxSettings`, and related interfaces in `Configuration.ts`:\n\n```typescript\ninterface ChromeSettings {\n skipDownload?: boolean;\n // URL prefix for browser downloads\n}\n```\n\n### Environment Variable Overrides\n\n| Variable | Configuration Property |\n|----------|------------------------|\n| `PUPPETEER_SKIP_DOWNLOAD` | `skipDownload` |\n| `PUPPETEER_TMP_DIR` | `temporaryDirectory` |\n| `PUPPETEER_CHROME_SKIP_DOWNLOAD` | `chrome.skipDownload` |\n| `PUPPETEER_CHROME_DOWNLOAD_BASE_URL` | `chrome.downloadBaseUrl` |\n\n## Integration Patterns\n\n### Direct Usage (puppeteer-core)\n\n```typescript\nimport puppeteer from 'puppeteer-core';\n\nconst browser = await puppeteer.launch({\n executablePath: '/path/to/browser'\n});\n```\n\n### Full Distribution (puppeteer)\n\n```typescript\nimport puppeteer from 'puppeteer';\n// Automatically downloads and uses bundled Chrome\nconst browser = await puppeteer.launch();\n```\n\n## Debug Support\n\nPuppeteer includes a debug logging system controlled via the `__PUPPETEER_DEBUG` environment variable:\n\n```bash\n# Enable all debug channels\nwindow.__PUPPETEER_DEBUG='*'\n\n# Enable specific channel\nwindow.__PUPPETEER_DEBUG='Page'\n\n# Enable channel prefix matching\nwindow.__PUPPETEER_DEBUG='Page*'\n```\n\nThe debug utility is implemented in `packages/puppeteer-core/src/common/Debug.ts`.\n\n## Browser Support Matrix\n\n| Browser | Protocol | Package Support |\n|---------|----------|----------------|\n| Chrome | CDP | Full |\n| Chromium | CDP | Full |\n| Firefox | CDP | Experimental |\n| Edge | CDP | Via Chrome compatibility |\n\n## Additional Resources\n\nThe repository also includes:\n\n- **Examples** (`examples/`): Working code samples demonstrating various Puppeteer features\n- **Website** (`website/`): Documentation site built with Docusaurus 3\n- **Docker** (`docker/`): Containerization support for browser execution\n- **ESLint Tools** (`tools/eslint/`): Custom ESLint rules for code quality\n\n## Version Compatibility\n\nPuppeteer maintains backward compatibility within major versions. The `puppeteer-core` package is guaranteed to work with any browser that implements the required DevTools Protocol capabilities, though optimal compatibility is achieved with bundled browser versions.\n\n---\n\n\n\n## Protocol Implementations\n\n### 相关页面\n\n相关主题：[CDP Implementation](#cdp-implementation), [WebDriver BiDi Implementation](#bidi-implementation)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/cdp/ExecutionContext.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/ExecutionContext.ts)\n- [packages/puppeteer-core/src/bidi/Realm.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Realm.ts)\n- [packages/puppeteer-core/src/common/ScriptInjector.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/ScriptInjector.ts)\n- [packages/puppeteer-core/src/common/LazyArg.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/LazyArg.ts)\n- [packages/puppeteer-core/src/api/Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)\n- [packages/puppeteer-core/src/bidi/core/README.md](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/core/README.md)\n \n\n# Protocol Implementations\n\nPuppeteer provides abstraction layers over two browser automation protocols: the **Chrome DevTools Protocol (CDP)** and **WebDriver BiDi**. These protocol implementations form the foundation of how Puppeteer communicates with browsers, enabling code execution, DOM manipulation, and browser control.\n\n## Architecture Overview\n\nPuppeteer's protocol layer sits between the high-level API (Page, Frame, etc.) and the underlying browser connections. The architecture uses a dual-protocol approach where both CDP and BiDi implementations share common interfaces while providing protocol-specific behaviors.\n\n```mermaid\ngraph TD\n subgraph \"High-Level API\"\n Page[Page.ts]\n Frame[Frame.ts]\n end\n \n subgraph \"Protocol Abstraction Layer\"\n ExecutionContext[ExecutionContext.ts
CDP]\n Realm[Realm.ts
BiDi]\n end\n \n subgraph \"Connection Layer\"\n CDP_Conn[CDP Connection]\n BiDi_Conn[BiDi Connection]\n end\n \n subgraph \"Browser\"\n Chrome[Chrome/Chromium]\n Firefox[Firefox]\n WebKit[WebKit]\n end\n \n Page --> ExecutionContext\n Page --> Realm\n ExecutionContext --> CDP_Conn\n Realm --> BiDi_Conn\n CDP_Conn --> Chrome\n BiDi_Conn --> Firefox\n BiDi_Conn --> WebKit\n```\n\n## Chrome DevTools Protocol (CDP) Implementation\n\nThe CDP implementation is located in `packages/puppeteer-core/src/cdp/` and provides deep integration with Chrome/Chromium browsers. CDP offers rich capabilities including precise execution context management, detailed debugging features, and direct access to browser internals.\n\n### CDP Execution Context\n\nThe `ExecutionContext` class in `packages/puppeteer-core/src/cdp/ExecutionContext.ts` handles code evaluation within browser contexts:\n\n```typescript\n// Simplified from ExecutionContext.ts\nasync evaluate(\n returnByValue: boolean,\n pageFunction: Func | string,\n ...args: Params\n): Promise>> | Awaited>> {\n const sourceUrlComment = getSourceUrlComment(\n getSourcePuppeteerURLIfAvailable(pageFunction)?.toString() ??\n PuppeteerURL.INTERNAL_URL,\n );\n\n if (isString(pageFunction)) {\n const contextId = this.#id;\n const expression = pageFunction;\n const expressionWithSourceUrl = SOURCE_URL_REGEX.test(expression)\n ? expression\n : `${expression}\\n${sourceUrlComment}\\n`;\n\n const {exceptionDetails, result: remoteObject} = await this.#client\n .send('Runtime.evaluate', {\n expression: expressionWithSourceUrl,\n contextId,\n returnByValue,\n awaitPromise: true,\n userGesture: true,\n })\n .catch(rewriteError);\n\n if (exceptionDetails) {\n throw createEvaluationError(exceptionDetails);\n }\n // ...\n }\n}\n```\n\n**资料来源：** [packages/puppeteer-core/src/cdp/ExecutionContext.ts:1-50](packages/puppeteer-core/src/cdp/ExecutionContext.ts)\n\n### CDP Connection\n\nThe CDP Connection manages the WebSocket-based communication channel to the browser's DevTools endpoint. This implementation handles message routing, callback management, and protocol event distribution.\n\n## WebDriver BiDi Implementation\n\nThe BiDi implementation follows the WebDriver BiDi specification and is organized into two layers:\n\n1. **`packages/puppeteer-core/src/bidi/`** - Puppeteer's BiDi abstractions\n2. **`packages/puppeteer-core/src/bidi/core/`** - Spec-compliant WebDriver BiDi core\n\n### BiDi Design Principles\n\nAccording to `packages/puppeteer-core/src/bidi/core/README.md`:\n\n- `bidi/core` attempts to implement WebDriver BiDi comprehensively, but minimally\n- All objects and events in WebDriver BiDi are implemented as a graph where objects are nodes and events are edges\n- The implementation always follows the spec and never Puppeteer's specific needs\n- This ensures that bugs can be precisely identified as either spec issues or Puppeteer workarounds\n\n**资料来源：** [packages/puppeteer-core/src/bidi/core/README.md:1-30](packages/puppeteer-core/src/bidi/core/README.md)\n\n### BiDi Realm\n\nThe BiDi `Realm` class in `packages/puppeteer-core/src/bidi/Realm.ts` provides the execution environment for BiDi-based evaluations:\n\n```typescript\n// Simplified from Realm.ts\nclass Realm extends EventEmitter {\n internalPuppeteerUtil?: Promise>;\n \n get puppeteerUtil(): Promise> {\n const promise = Promise.resolve() as Promise;\n scriptInjector.inject(script => {\n if (this.internalPuppeteerUtil) {\n void this.internalPuppeteerUtil.then(handle => {\n void handle.dispose();\n });\n }\n this.internalPuppeteerUtil = promise.then(() => {\n return this.evaluateHandle(script) as Promise<\n BidiJSHandle\n >;\n });\n }, !this.internalPuppeteerUtil);\n return this.internalPuppeteerUtil as Promise<\n BidiJSHandle\n >;\n }\n}\n```\n\n**资料来源：** [packages/puppeteer-core/src/bidi/Realm.ts:1-40](packages/puppeteer-core/src/bidi/Realm.ts)\n\n## Script Injection System\n\nThe `ScriptInjector` class (`packages/puppeteer-core/src/common/ScriptInjector.ts`) handles the injection of utility scripts required by both protocol implementations. It maintains a set of amendments that get applied to the injected script:\n\n```typescript\nexport class ScriptInjector {\n #updated = false;\n #amendments = new Set();\n\n append(statement: string): void {\n this.#update(() => {\n this.#amendments.add(statement);\n });\n }\n\n inject(inject: (script: string) => void, force = false): void {\n if (this.#updated || force) {\n inject(this.#get());\n }\n this.#updated = false;\n }\n\n #get(): string {\n return `(() => {\n const module = {};\n ${injectedSource}\n ${[...this.#amendments]\n .map(statement => {\n return `(${statement})(module.exports.default);`;\n })\n .join('')}\n return module.exports.default;\n })()`;\n }\n}\n\nexport const scriptInjector = new ScriptInjector();\n```\n\n**资料来源：** [packages/puppeteer-core/src/common/ScriptInjector.ts:1-50](packages/puppeteer-core/src/common/ScriptInjector.ts)\n\n## LazyArg Pattern\n\nThe `LazyArg` class provides a mechanism for lazy evaluation of arguments passed to page functions. This is essential for protocol implementations as it defers the resolution of context-dependent values:\n\n```typescript\nexport class LazyArg {\n static create = (\n get: (context: PuppeteerUtilWrapper) => Promise | T,\n ): T => {\n return new LazyArg(get) as unknown as T;\n };\n\n #get: (context: Context) => Promise | T;\n private constructor(get: (context: Context) => Promise | T) {\n this.#get = get;\n }\n\n async get(context: Context): Promise {\n return await this.#get(context);\n }\n}\n```\n\n**资料来源：** [packages/puppeteer-core/src/common/LazyArg.ts:1-30](packages/puppeteer-core/src/common/LazyArg.ts)\n\n## Protocol Selection and Configuration\n\nThe protocol implementation is selected based on browser type and configuration. The `Page` class in `packages/puppeteer-core/src/api/Page.ts` defines the abstract interface that both protocol implementations satisfy:\n\n```typescript\nexport abstract class Page extends EventEmitter {\n _isDragging = false;\n _timeoutSettings = new TimeoutSettings();\n _tabId = '';\n \n #requestHandlers = new WeakMap, Handler>();\n}\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:100-130](packages/puppeteer-core/src/api/Page.ts)\n\n## Key Differences Between Protocols\n\n| Feature | CDP | BiDi |\n|---------|-----|------|\n| **Browser Support** | Chrome, Chromium | Firefox, WebKit, Chrome |\n| **Architecture** | WebSocket-based | WebSocket + JSON commands |\n| **Spec Compliance** | Chrome-specific | Cross-browser standard |\n| **Execution Model** | Direct context switching | Realm-based isolation |\n| **Debugging** | Deep DevTools integration | Standard WebDriver interface |\n\n## Event Flow Comparison\n\n```mermaid\ngraph LR\n subgraph \"CDP Flow\"\n CDP1[Page Event] --> CDP2[Emulation Context]\n CDP2 --> CDP3[Request Handler]\n end\n \n subgraph \"BiDi Flow\"\n BiDi1[Page Event] --> BiDi2[Realm]\n BiDi2 --> BiDi3[Script Injector]\n BiDi3 --> BiDi4[BiDi Command]\n end\n```\n\n## Summary\n\nPuppeteer's protocol implementations provide a unified abstraction over CDP and WebDriver BiDi:\n\n1. **CDP Implementation** offers deep Chrome integration with precise context management\n2. **BiDi Implementation** provides cross-browser compatibility following the WebDriver BiDi specification\n3. **ScriptInjector** manages utility script injection for both protocols\n4. **LazyArg** enables lazy evaluation of protocol-dependent arguments\n5. The dual-protocol architecture allows Puppeteer to target different browsers while maintaining a consistent high-level API\n\n---\n\n\n\n## CDP Implementation\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Page API](#page-api)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/cdp/Connection.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/Connection.ts)\n- [packages/puppeteer-core/src/cdp/Browser.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/Browser.ts)\n- [packages/puppeteer-core/src/cdp/Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/Page.ts)\n- [packages/puppeteer-core/src/cdp/NetworkManager.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/NetworkManager.ts)\n- [packages/puppeteer-core/src/cdp/FrameManager.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/FrameManager.ts)\n- [packages/puppeteer-core/src/cdp/CdpSession.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/CdpSession.ts)\n \n\n# CDP Implementation\n\n## Overview\n\nThe Chrome DevTools Protocol (CDP) is the core communication mechanism that enables Puppeteer to interact with Chromium-based browsers. The CDP Implementation in Puppeteer provides a comprehensive abstraction layer over the raw CDP protocol, enabling high-level browser automation operations such as page navigation, JavaScript execution, network interception, and device emulation.\n\nPuppeteer's CDP implementation is located in `packages/puppeteer-core/src/cdp/` and consists of multiple interconnected modules that handle different aspects of browser automation.\n\n资料来源：[packages/puppeteer-core/src/cdp/Connection.ts:1-50]()\n\n## Architecture\n\n### High-Level Component Architecture\n\n```mermaid\ngraph TD\n subgraph \"CDP Implementation Layer\"\n Connection[CdpConnection]\n Session[CdpSession]\n Browser[CdpBrowser]\n Page[CdpPage]\n NetworkManager[NetworkManager]\n FrameManager[FrameManager]\n end\n \n subgraph \"Core CDP Components\"\n BrowserConnector[BrowserConnector]\n Target[CDPTarget]\n Accessibility[Accessibility]\n Input[Input]\n end\n \n subgraph \"Protocol Layer\"\n ProtocolCommands[CDP Protocol Commands]\n EventEmitters[Event Emitters]\n MessageHandlers[Message Handlers]\n end\n \n Connection --> Session\n Session --> Browser\n Browser --> Page\n Browser --> NetworkManager\n Browser --> FrameManager\n Session --> Target\n Connection --> BrowserConnector\n```\n\n### Module Responsibilities\n\n| Module | Purpose | Key Responsibilities |\n|--------|---------|---------------------|\n| `Connection.ts` | WebSocket communication | Establishes/manages WebSocket connection, routes messages, handles reconnection |\n| `CdpSession.ts` | CDP session management | Creates/sends CDP commands, receives events, manages message IDs |\n| `Browser.ts` | Browser lifecycle | Manages browser process, targets, pages, contexts |\n| `Page.ts` | Page automation | Navigation, frame management, viewport, emulation |\n| `NetworkManager.ts` | Network interception | Request/response interception, authentication handling |\n| `FrameManager.ts` | Frame hierarchy | Main frame, child frames, navigation tracking |\n| `ExecutionContext.ts` | JS execution | Evaluates JavaScript, manages handles |\n\n资料来源：[packages/puppeteer-core/src/cdp/Browser.ts:1-100]()\n\n## Connection Management\n\n### WebSocket-Based Communication\n\nThe `CdpConnection` class establishes a WebSocket connection to the browser's DevTools endpoint. This is the foundational transport layer for all CDP communication.\n\n```mermaid\nsequenceDiagram\n participant Puppeteer as Puppeteer Client\n participant WS as WebSocket\n participant Browser as Chrome/Chromium\n \n Puppeteer->>WS: Connect to DevTools URL\n WS->>Puppeteer: Connection established\n Puppeteer->>Browser: CDP Command (method, params, id)\n Browser->>Puppeteer: CDP Response (id, result)\n Browser->>Puppeteer: CDP Event (method, params)\n```\n\n### Connection Lifecycle\n\nThe connection management follows a defined lifecycle:\n\n1. **Initialization**: Establish WebSocket connection to the browser's remote debugging URL\n2. **Session Creation**: Create `CdpSession` instances for different targets\n3. **Message Routing**: Route CDP commands and events between client and browser\n4. **Disconnection Handling**: Gracefully handle disconnection and cleanup\n5. **Reconnection**: Support for reconnection scenarios\n\n资料来源：[packages/puppeteer-core/src/cdp/Connection.ts:50-150]()\n\n## Session Management\n\n### CdpSession Implementation\n\nThe `CdpSession` class represents an active CDP session bound to a specific browser target. It handles:\n\n- **Command Dispatch**: Sending CDP method calls with parameters\n- **Event Subscription**: Listening for CDP events from the browser\n- **Message Correlation**: Matching responses to requests using message IDs\n- **Session Lifecycle**: Creating and disposing sessions\n\n```typescript\n// Simplified session structure\nclass CdpSession {\n #connection: CdpConnection;\n #sessionId: string;\n #messageHandlers: Map;\n \n async send(method: string, params?: object): Promise;\n on(event: string, handler: Function): void;\n off(event: string, handler: Function): void;\n detach(): Promise;\n}\n```\n\n### Message Flow\n\n```mermaid\ngraph LR\n subgraph \"Client Side\"\n CMD[CDP Command]\n RES[CDP Response]\n EVT[CDP Event]\n end\n \n subgraph \"Transport\"\n WS[WebSocket]\n end\n \n subgraph \"Browser Side\"\n CDP[CDP Runtime]\n TGT[Target]\n end\n \n CMD -->|send method| WS\n WS -->|route| CDP\n CDP -->|response id| WS\n WS -->|response| RES\n TGT -->|emit event| CDP\n CDP -->|event| WS\n WS -->|event| EVT\n```\n\n资料来源：[packages/puppeteer-core/src/cdp/CdpSession.ts:1-80]()\n\n## Browser Implementation\n\n### CdpBrowser Class\n\nThe `CdpBrowser` class provides the high-level browser interface, implementing the `Browser` interface defined in the API layer. It coordinates multiple CDP sessions and manages browser targets.\n\n```mermaid\nclassDiagram\n class CdpBrowser {\n +connection_: CdpConnection\n +browserContext_: BrowserContext\n +_targets: Map~string, CdpTarget~\n +_ignoreHTTPSErrors: boolean\n +_defaultViewport: Viewport | null\n +newPage(): Promise~CdpPage~\n +createIncognitoBrowserContext(): BrowserContext\n +disconnect(): void\n +wsEndpoint(): string\n }\n \n class CdpTarget {\n +_browserContext: BrowserContext\n +_session: CdpSession\n +_initialized: Promise~void~\n +_closeCallback: Function\n +initialize(): Promise~void~\n }\n \n CdpBrowser --> CdpTarget\n CdpTarget --> CdpSession\n```\n\n### Target Management\n\nBrowser targets represent different browsing contexts managed by Chromium:\n\n| Target Type | Description | Creation Method |\n|-------------|-------------|-----------------|\n| Browser Target | Main browser process | Auto-created on connection |\n| Page Target | Single page/tab | `Target.createTarget` |\n| Service Worker | Background script | Auto-created for SWs |\n| BrowserContext | Isolated profile | `Browser.createIncognitoContext` |\n\n资料来源：[packages/puppeteer-core/src/cdp/Browser.ts:100-250]()\n\n## Page Implementation\n\n### CdpPage Class\n\nThe `CdpPage` class extends the abstract `Page` class and implements page-specific CDP operations. It provides methods for:\n\n- **Navigation**: `goto()`, `goBack()`, `goForward()`, `reload()`\n- **Content Operations**: `setContent()`, `content()`\n- **Viewport Management**: `setViewport()`, viewport settings\n- **Frame Access**: `mainFrame()`, `frames()`, `frame()`\n- **Device Emulation**: `emulate()`, `emulateMediaType()`, `emulateTimezone()`\n\n```mermaid\ngraph TD\n subgraph \"CdpPage\"\n PageAPI[Page Interface]\n Navigation[Navigation Manager]\n Emulation[Emulation Manager]\n Screenshot[Screenshot Handler]\n end\n \n subgraph \"CDP Sessions\"\n PageSession[Page Target Session]\n FrameSession[Frame Session]\n end\n \n PageAPI --> Navigation\n PageAPI --> Emulation\n PageAPI --> Screenshot\n Navigation --> PageSession\n Emulation --> PageSession\n FrameSession --> FrameManager\n```\n\n### Page Lifecycle Events\n\n| Event | Trigger | Use Case |\n|-------|---------|----------|\n| `load` | Page load complete | Wait for full page |\n| `domcontentloaded` | DOM ready | Early interaction |\n| `networkidle` | No network for 500ms | Wait for API calls |\n| `framenavigated` | Frame navigation complete | Frame sync |\n| `request/requestfailed/response` | Network events | Intercept/modify requests |\n\n资料来源：[packages/puppeteer-core/src/cdp/Page.ts:1-150]()\n\n## Network Management\n\n### NetworkManager Class\n\nThe `NetworkManager` handles all network-related CDP events and provides the interception infrastructure for `page.setRequestInterception()`.\n\n```mermaid\ngraph TD\n subgraph \"NetworkManager\"\n RequestInterceptor[Request Interceptor]\n AuthHandler[Auth Handler]\n CacheManager[Cache Manager]\n end\n \n subgraph \"CDP Events\"\n REQ[Network.requestWillBeSent]\n RES[Network.responseReceived]\n ERR[Network.requestFailed]\n CMPL[Network.loadingFinished]\n end\n \n subgraph \"Public API\"\n Interception[setRequestInterception]\n Auth[authenticate]\n Offline[setOfflineMode]\n end\n \n REQ --> RequestInterceptor\n RequestInterceptor --> Interception\n Auth --> AuthHandler\n AuthHandler --> REQ\n```\n\n### Request Interception Flow\n\n```mermaid\nsequenceDiagram\n participant Browser as Browser\n participant NM as NetworkManager\n participant Interceptor as User Interceptor\n participant CDP as CDP Session\n \n Browser->>NM: requestWillBeSent\n NM->>Interceptor: intercept callback\n Interceptor->>NM: continue/abort/respond\n NM->>CDP: Network.continueRequest\n NM->>CDP: Network.failRequest\n NM->>CDP: Network.fulfillRequest\n```\n\n### Authentication Handler\n\nThe `NetworkManager` includes authentication handling for HTTP Basic/Digest auth:\n\n```typescript\ninterface AuthCredentials {\n username: string;\n password: string;\n}\n\nclass NetworkManager {\n #authCredentials?: AuthCredentials;\n #pendingAuthRequests: Map;\n \n setAuthCredentials(credentials: AuthCredentials): void;\n clearAuthCredentials(): void;\n}\n```\n\n资料来源：[packages/puppeteer-core/src/cdp/NetworkManager.ts:1-200]()\n\n## Frame Management\n\n### FrameManager Class\n\nThe `FrameManager` maintains the frame hierarchy and tracks frame lifecycle events. It handles:\n\n- **Frame Tree Construction**: Building and maintaining the document frame hierarchy\n- **Navigation Tracking**: Tracking frame-level navigation events\n- **Detached Frame Cleanup**: Cleaning up frames when their documents unload\n- **Frame Communication**: Managing frame-specific CDP sessions\n\n```mermaid\ngraph TD\n subgraph \"FrameManager\"\n FT[Frame Tree]\n EH[Event Handler]\n NC[Navigation Checker]\n end\n \n subgraph \"Frame Types\"\n MF[Main Frame]\n IF[iframe]\n SF[Shadow Frame]\n end\n \n FT --> MF\n FT --> IF\n FT --> SF\n EH -->|events| FT\n NC -->|nav events| FT\n```\n\n### Frame Hierarchy\n\n| Frame Type | CDP Target | Session | Characteristics |\n|------------|------------|---------|-----------------|\n| Main Frame | Page target | Primary session | Top-level document |\n| Subframe | Auto-created | Linked to parent | Cross-origin isolation |\n| Worker | ServiceWorker target | Separate session | No DOM access |\n\n资料来源：[packages/puppeteer-core/src/cdp/FrameManager.ts:1-180]()\n\n## Execution Context\n\n### CdpExecutionContext\n\nThe execution context in CDP is the JavaScript execution environment within a frame. The `ExecutionContext` class provides:\n\n- **JavaScript Evaluation**: `evaluate()` and `evaluateHandle()` methods\n- **Handle Management**: Creating and managing JSHandle instances\n- **Remote Object Conversion**: Converting CDP RemoteObjects to JSHandles\n\n```mermaid\ngraph LR\n subgraph \"User Code\"\n FN[Function/Expression]\n end\n \n subgraph \"Puppeteer\"\n EVAL[evaluate]\n LAZY[LazyArg]\n HANDLE[JsHandle]\n end\n \n subgraph \"CDP\"\n RTE[Runtime.evaluate]\n CALL[Runtime.callFunctionOn]\n RO[RemoteObject]\n end\n \n FN --> EVAL\n EVAL --> RTE\n EVAL --> CALL\n CALL --> LAZY\n RTE --> RO\n CALL --> RO\n RO --> HANDLE\n```\n\n### Source URL Handling\n\nPuppeteer injects source URL comments into evaluated code for better debugging:\n\n```typescript\nconst SOURCE_URL_COMMENT = '//# sourceURL=__puppeteer_evaluation_script__';\n```\n\nThis enables:\n- Proper stack traces in console errors\n- Source map resolution in DevTools\n- Better debugging experience for evaluated code\n\n资料来源：[packages/puppeteer-core/src/cdp/ExecutionContext.ts:30-120]()\n\n## Key CDP Methods Used\n\n### Browser-Level Methods\n\n| Method | Category | Purpose |\n|--------|----------|---------|\n| `Target.createTarget` | Target | Create new page/tab |\n| `Target.attachToTarget` | Target | Attach to existing target |\n| `Browser.close` | Browser | Close browser |\n| `Browser.getVersion` | Browser | Get browser info |\n\n### Page-Level Methods\n\n| Method | Category | Purpose |\n|--------|----------|---------|\n| `Page.navigate` | Navigation | Navigate to URL |\n| `Page.setDocumentContent` | Content | Set HTML content |\n| `Page.captureScreenshot` | Screenshot | Take screenshot |\n| `Page.setViewport` | Emulation | Set viewport dimensions |\n\n### Network Methods\n\n| Method | Category | Purpose |\n|--------|----------|---------|\n| `Network.setRequestInterception` | Interception | Enable request interception |\n| `Network.continueRequest` | Interception | Continue intercepted request |\n| `Network.fulfillRequest` | Interception | Respond with custom data |\n| `Network.getResponseBody` | Response | Get response body |\n\n### Runtime Methods\n\n| Method | Category | Purpose |\n|--------|----------|---------|\n| `Runtime.evaluate` | Evaluation | Execute expression |\n| `Runtime.callFunctionOn` | Evaluation | Call function on object |\n| `Runtime.queryObjects` | Inspection | Query JS objects |\n\n资料来源：[packages/puppeteer-core/src/cdp/Page.ts:200-350]()\n\n## Event Flow Architecture\n\n```mermaid\ngraph TD\n subgraph \"Browser Events\"\n NE[Navigation Event]\n RE[Resource Event]\n EE[Execution Event]\n end\n \n subgraph \"CDP Events\"\n CDP_NE[Page.frameNavigated]\n CDP_RE[Network.requestWillBeSent]\n CDP_EE[Runtime.executionContextCreated]\n end\n \n subgraph \"Puppeteer Events\"\n P_E[page.on Event]\n CB[Event Callback]\n end\n \n NE -->|triggers| CDP_NE\n RE -->|triggers| CDP_RE\n EE -->|triggers| CDP_EE\n CDP_NE -->|emitted| P_E\n CDP_RE -->|emitted| P_E\n CDP_EE -->|emitted| P_E\n P_E -->|invokes| CB\n```\n\n## Error Handling\n\n### Error Rewriting\n\nPuppeteer rewrites CDP errors to provide more meaningful error messages:\n\n```typescript\nfunction rewriteError(error: Error, message: string): never {\n throw new Error(`${message}: ${error.message}`);\n}\n```\n\n### Evaluation Errors\n\nJavaScript evaluation errors are converted to `Error` instances with detailed information:\n\n```typescript\nfunction createEvaluationError(exceptionDetails: ExceptionDetails): Error {\n const error = new Error();\n error.name = exceptionDetails.exception?.className ?? 'Error';\n error.message = exceptionDetails.exception?.description \n ?? exceptionDetails.text;\n return error;\n}\n```\n\n资料来源：[packages/puppeteer-core/src/cdp/ExecutionContext.ts:60-90]()\n\n## Configuration Options\n\n### Launch Options Related to CDP\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `executablePath` | `string` | bundled browser | Path to browser executable |\n| `channel` | `ChromeReleaseChannel` | auto | Chrome update channel |\n| `browser` | `SupportedBrowser` | chrome | Browser to use |\n| `timeout` | `number` | 30000 | Browser launch timeout |\n| `protocolTimeout` | `number` | undefined | CDP protocol timeout |\n\n### Browser Configuration\n\n| Setting | Environment Variable | Description |\n|---------|---------------------|-------------|\n| `defaultBrowser` | `PUPPETEER_DEFAULT_BROWSER` | Default browser to use |\n| `temporaryDirectory` | `PUPPETEER_TMP_DIR` | Temp directory for downloads |\n| `skipDownload` | `PUPPETEER_SKIP_DOWNLOAD` | Skip browser download |\n| `logLevel` | `PUPPETEER_LOG_LEVEL` | Logging level |\n\n资料来源：[packages/puppeteer-core/src/node/LaunchOptions.ts:1-100]()\n\n## See Also\n\n- [Puppeteer Core API Documentation](https://pptr.dev/api/)\n- [Chrome DevTools Protocol Documentation](https://chromedevtools.github.io/devtools-protocol/)\n- [Page Implementation](./Page.md)\n- [Browser Implementation](./Browser.md)\n\n---\n\n\n\n## WebDriver BiDi Implementation\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Protocol Implementations](#protocols)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/node/BrowserLauncher.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/node/BrowserLauncher.ts)\n- [packages/puppeteer-core/src/bidi/core/README.md](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/core/README.md)\n- [packages/puppeteer-core/src/bidi/Target.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Target.ts)\n- [packages/puppeteer-core/src/bidi/util.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/util.ts)\n- [packages/puppeteer-core/src/common/ConnectOptions.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/ConnectOptions.ts)\n \n\n# WebDriver BiDi Implementation\n\n## Overview\n\nWebDriver BiDi (Bidirectional Protocol) is a W3C-standardized protocol that enables bidirectional communication between browser automation tools and web browsers. Puppeteer's WebDriver BiDi implementation provides a modern, cross-browser automation interface built on the WebDriver protocol specification.\n\nThe implementation exists as a first-class protocol option alongside CDP (Chrome DevTools Protocol), with deep integration into Puppeteer's core architecture.\n\n## Architecture Principles\n\nThe `bidi/core` module follows specific architectural guidelines that distinguish it from higher-level Puppeteer abstractions:\n\n| Principle | Description |\n|-----------|-------------|\n| **Spec Compliance** | `bidi/core` always follows the WebDriver BiDi specification, never Puppeteer's needs |\n| **No Workarounds** | Spec deviations are never masked; instead, workarounds belong in upper layers |\n| **Comprehensive Minimalism** | All required nodes and edges in the protocol graph are implemented fully |\n| **Event Integrity** | Events are never composed or duplicated; navigation flows must follow the correct event sequence |\n\n资料来源：[packages/puppeteer-core/src/bidi/core/README.md]()\n\n### Event Flow Integrity\n\nA critical principle is that events must follow proper WebDriver BiDi semantics. For navigation events:\n\n- Fragment navigations must emit events through the complete chain: `fragment navigation → navigation → browsing context`\n- Direct emission to browsing context without intermediate events is prohibited\n- This ensures that consumers receive semantically correct event sequences matching the protocol specification\n\n## Protocol Connection Architecture\n\n```mermaid\ngraph TD\n A[Puppeteer Application] --> B[BrowserLauncher]\n B --> C{PUPPETEER_WEBDRIVER_BIDI_ONLY}\n C -->|true| D[BiDi Only Mode]\n C -->|false| E[CDP + BiDi Hybrid Mode]\n D --> F[BiDi.connectBidiOverCdp]\n E --> G[CDP Connection]\n G --> H[BiDi.connectBidiOverCdp]\n F --> I[BidiBrowser Instance]\n H --> I\n```\n\n### BiDi over CDP Bridge\n\nWhen using WebDriver BiDi with browsers that primarily support CDP (like Chrome), Puppeteer establishes a CDP connection and wraps it with BiDi protocol support:\n\n```typescript\nconst bidiOnly = process.env['PUPPETEER_WEBDRIVER_BIDI_ONLY'] === 'true';\nconst BiDi = await import('../bidi/bidi.js');\nconst bidiConnection = await BiDi.connectBidiOverCdp(cdpConnection);\nreturn await BiDi.BidiBrowser.create({\n connection: bidiConnection,\n // Do not provide CDP connection to Browser if BiDi-only mode is enabled\n cdpConnection: bidiOnly ? undefined : cdpConnection,\n closeCallback,\n process: browserProcess.nodeProcess,\n defaultViewport: opts.defaultViewport,\n acceptInsecureCerts: opts.acceptInsecureCerts,\n networkEnabled: opts.networkEnabled,\n issuesEnabled: opts.issuesEnabled,\n});\n```\n\n资料来源：[packages/puppeteer-core/src/node/BrowserLauncher.ts:1-28]()\n\n### WebDriver BiDi Capabilities\n\nWhen connecting with WebDriver BiDi protocol, capabilities can be specified:\n\n```typescript\ninterface SupportedWebDriverCapabilities {\n webDriverBiDi?: {\n // BiDi-specific capabilities passed to session.new\n };\n}\n```\n\nThe `capabilities` option allows passing WebDriver BiDi capabilities during connection establishment:\n\n> Headers to use for the web socket connection. Only works in the Node.js environment.\n>\n> WebDriver BiDi capabilities passed to BiDi `session.new`. Only works for `protocol=\"webDriverBiDi\"` and `Puppeteer.connect`.\n\n资料来源：[packages/puppeteer-core/src/common/ConnectOptions.ts:1-50]()\n\n## Target Model\n\nPuppeteer's BiDi implementation extends the abstract `Target` class with browser-specific target types:\n\n### BidiBrowserTarget\n\nRepresents the browser-level target in WebDriver BiDi context:\n\n```typescript\nexport class BidiBrowserTarget extends Target {\n #browser: BidiBrowser;\n\n override type(): TargetType {\n return TargetType.BROWSER;\n }\n\n override browser(): BidiBrowser {\n return this.#browser;\n }\n\n override browserContext(): BidiBrowserContext {\n return this.#browser.defaultBrowserContext();\n }\n}\n```\n\nUnsupported operations throw `UnsupportedOperation`:\n\n- `asPage()` - Not supported at browser target level\n- `createCDPSession()` - CDP sessions not available in BiDi-only targets\n- `opener()` - Not applicable to browser targets\n\n资料来源：[packages/puppeteer-core/src/bidi/Target.ts:1-50]()\n\n### BidiPageTarget\n\nRepresents individual page targets within the browser context. Extends the base `Target` with page-specific behavior through composition with `BidiPage`.\n\n## Console Message Handling\n\nWebDriver BiDi requires conversion between BiDi console event levels and Puppeteer's internal representation:\n\n```typescript\nexport function convertConsoleMessageLevel(method: string): ConsoleMessageType {\n switch (method) {\n case 'group':\n return 'startGroup';\n case 'groupCollapsed':\n return 'startGroupCollapsed';\n case 'groupEnd':\n return 'endGroup';\n default:\n return method as ConsoleMessageType;\n }\n}\n```\n\nThis mapping ensures that BiDi's console event semantics align with Puppeteer's console message types.\n\n资料来源：[packages/puppeteer-core/src/bidi/util.ts:1-40]()\n\n### Stack Trace Extraction\n\nConsole messages can include stack trace information extracted from BiDi protocol responses:\n\n```typescript\nexport function getStackTraceLocations(\n stackTrace?: Bidi.Script.StackTrace,\n): ConsoleMessageLocation[] {\n const stackTraceLocations: ConsoleMessageLocation[] = [];\n if (stackTrace) {\n for (const callFrame of stackTrace.callFrames) {\n stackTraceLocations.push({\n url: callFrame.url,\n lineNumber: callFrame.lineNumber,\n columnNumber: callFrame.columnNumber,\n });\n }\n }\n return stackTraceLocations;\n}\n```\n\n## Firefox-Specific Configuration\n\nFirefox has native WebDriver BiDi support and provides specific preferences configuration:\n\n| Preference | Value | Purpose |\n|------------|-------|---------|\n| `fission.bfcacheInParent` | `undefined` | BFCache behavior |\n| `fission.webContentIsolationStrategy` | `0` | Process isolation strategy |\n\n### Blocklist and Allowlist\n\nFirefox's WebDriver BiDi implementation supports blocklist/allowlist configuration through preferences. However, these are **only supported with the CDP protocol**:\n\n```typescript\nit('should reject blocklist for the default Firefox WebDriver BiDi protocol', async () => {\n const launcher = new FirefoxLauncher({} as PuppeteerNode);\n\n await expect(\n launcher.launch({\n blocklist: ['https://example.com/*'],\n }),\n ).rejects.toThrow(\n 'blocklist and allowlist are only supported with the CDP protocol',\n );\n});\n```\n\n资料来源：[packages/puppeteer-core/src/node/FirefoxLauncher.test.ts:1-40]()\n\n## Core Components\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| Browser | `bidi/Browser.ts` | Main browser instance management |\n| BrowsingContext | `bidi/core/BrowsingContext.ts` | Tab/window context handling |\n| Navigation | `bidi/core/Navigation.ts` | Navigation event handling |\n| Page | `bidi/Page.ts` | Page-level operations |\n| Realm | `bidi/Realm.ts` | JavaScript execution contexts |\n\n## Protocol Modes\n\nPuppeteer supports three protocol configuration modes:\n\n```mermaid\ngraph LR\n A[Default] --> B[CDP + BiDi]\n C[PUPPETEER_WEBDRIVER_BIDI_ONLY=true] --> D[BiDi Only]\n E[protocol=webDriverBiDi] --> D\n```\n\n| Mode | CDP Available | BiDi Available | Use Case |\n|------|---------------|----------------|----------|\n| Default | Yes | Yes (via bridge) | Chrome automation |\n| BiDi Only | No | Yes | Pure spec compliance |\n| WebDriver BiDi | No | Native | Firefox automation |\n\n## Summary\n\nThe WebDriver BiDi implementation in Puppeteer provides:\n\n1. **Standards-compliant protocol support** through the `bidi/core` module following W3C WebDriver BiDi specification\n2. **Flexible connection architecture** supporting CDP bridge and native BiDi modes\n3. **Browser-agnostic target model** with proper abstraction layers\n4. **Event integrity** ensuring semantically correct event sequences per protocol spec\n5. **Cross-browser compatibility** with native Firefox BiDi support and Chrome CDP bridging\n\n---\n\n\n\n## Page API\n\n### 相关页面\n\n相关主题：[Locators and Element Handles](#locators), [Input Handling](#input-handling)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/api/Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)\n- [packages/puppeteer-core/src/cdp/ExecutionContext.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/ExecutionContext.ts)\n- [packages/puppeteer-core/src/api/locators/locators.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/locators/locators.ts)\n- [packages/puppeteer-core/src/common/Device.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/Device.ts)\n- [packages/puppeteer-core/src/common/LazyArg.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/LazyArg.ts)\n \n\n# Page API\n\nThe Page API is the core interface in Puppeteer for interacting with browser pages and tabs. It provides methods for navigating pages, interacting with DOM elements, evaluating JavaScript, handling events, and emulating various browser environments and device characteristics.\n\n## Overview\n\nThe Page API serves as the primary abstraction for browser page operations in Puppeteer. A Page instance represents a single tab or window within a browser instance, offering a comprehensive set of methods to control page behavior, extract data, and automate interactions.\n\n```mermaid\ngraph TD\n A[Browser Instance] --> B[Page API]\n B --> C[Navigation]\n B --> D[DOM Interaction]\n B --> E[JavaScript Evaluation]\n B --> F[Event Handling]\n B --> G[Device Emulation]\n \n C --> C1[goto, back, forward, reload]\n D --> D1[$, $$, locator]\n E --> E1[evaluate, exposeFunction]\n F --> F1[on, once, off]\n G --> G1[emulateMediaType, emulate]\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:1-50]()\n\n## Core Architecture\n\n### Class Hierarchy\n\nThe Page class extends EventEmitter and serves as an abstract base class implemented by both CDP (Chrome DevTools Protocol) and WebDriver BiDi backends:\n\n```mermaid\nclassDiagram\n class EventEmitter~PageEvents~ {\n <>\n }\n class Page {\n <>\n +_isDragging: boolean\n +_timeoutSettings: TimeoutSettings\n +_tabId: string\n +exposeFunction()\n +metrics()\n +captureHeapSnapshot()\n +emulateMediaType()\n +emulateCPUThrottling()\n +emulateMediaFeatures()\n }\n class CDPPage {\n +implementation\n }\n class BiDiPage {\n +implementation\n }\n \n EventEmitter <|-- Page\n Page <|-- CDPPage\n Page <|-- BiDiPage\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:200-230]()\n\n### Internal State Management\n\nThe Page class maintains several internal state properties:\n\n| Property | Type | Purpose |\n|----------|------|---------|\n| `_isDragging` | `boolean` | Tracks drag state for mouse interactions |\n| `_timeoutSettings` | `TimeoutSettings` | Manages timeout configuration for operations |\n| `_tabId` | `string` | Browser-specific tab identifier |\n| `#inflight$` | `ReplaySubject` | Tracks in-flight request count |\n| `#requestHandlers` | `WeakMap` | Maps request handlers for monitoring |\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:200-215]()\n\n## Navigation API\n\n### Basic Navigation Methods\n\nThe Page API provides fundamental navigation methods for controlling page loading:\n\n- `goto(url)` - Navigate to a URL\n- `reload()` - Reload the current page\n- `goBack()` - Navigate to the previous page in history\n- `goForward()` - Navigate to the next page in history\n- `close()` - Close the page\n\n### URL Property\n\nThe `url()` method returns the current page URL as a shortcut for `page.mainFrame().url()`:\n\n```typescript\nconst currentUrl = await page.url();\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:280-295]()\n\n## JavaScript Evaluation\n\n### evaluate Method\n\nThe `evaluate` method executes JavaScript code in the page context. It supports both string expressions and function-based evaluation.\n\n**资料来源：** [packages/puppeteer-core/src/cdp/ExecutionContext.ts:30-60]()\n\n### evaluate with Parameters\n\nWhen passing arguments to page functions, Puppeteer serializes them using a specialized mechanism:\n\n```typescript\nawait page.evaluate(\n (text, inputValue) => {\n document.querySelector(text).value = inputValue;\n },\n 'selector',\n 'value'\n);\n```\n\n**资料来源：** [packages/puppeteer-core/src/cdp/ExecutionContext.ts:45-55]()\n\n### Source URL Comment Injection\n\nPuppeteer automatically injects source URL comments into evaluated code to enable better debugging and source map support:\n\n```typescript\nconst sourceUrlComment = getSourceUrlComment(\n getSourcePuppeteerURLIfAvailable(pageFunction)?.toString() ??\n PuppeteerURL.INTERNAL_URL,\n);\n```\n\nThe injection follows this pattern:\n1. Check if the expression already contains a source URL\n2. If not, append the source URL comment to the expression\n3. Include this comment in the CDP `Runtime.evaluate` call\n\n**资料来源：** [packages/puppeteer-core/src/cdp/ExecutionContext.ts:35-45]()\n\n## exposeFunction API\n\nThe `exposeFunction` method allows exposing Node.js functions to the page's JavaScript context as `window[name]`:\n\n### Signature\n\n```typescript\nabstract exposeFunction(\n name: string,\n pptrFunction: Function | {default: Function}\n): Promise;\n```\n\n### Usage Example\n\n```typescript\nconst browser = await puppeteer.launch();\nconst page = await browser.newPage();\n\npage.on('console', msg => console.log(msg.text()));\nawait page.exposeFunction('readfile', async filePath => {\n return fs.readFileSync(filePath, 'utf8');\n});\n\nawait page.evaluate(async () => {\n const content = await window.readfile('/etc/hosts');\n console.log(content);\n});\n\nawait browser.close();\n```\n\n### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `name` | `string` | Name of the function on the window object |\n| `pptrFunction` | `Function \\| {default: Function}` | Callback function executed in Puppeteer's Node.js context |\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:140-175]()\n\n## Device Emulation\n\n### Emulate Media Type\n\nThe `emulateMediaType` method emulates CSS media type on the page:\n\n```typescript\nawait page.emulateMediaType('print');\nawait page.evaluate(() => matchMedia('print').matches); // true\nawait page.emulateMediaType(null); // Reset to default\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:320-345]()\n\n### Emulate Media Features\n\nThe `emulateMediaFeatures` method emulates CSS media features:\n\n```typescript\nawait page.emulateMediaFeatures([\n { name: 'prefers-color-scheme', value: 'dark' },\n]);\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:345-360]()\n\n### Known Devices\n\nPuppeteer provides a predefined set of device descriptors via `KnownDevices`:\n\n```typescript\nimport { KnownDevices } from 'puppeteer';\nconst iPhone = KnownDevices['iPhone 15 Pro'];\n\nawait page.emulate(iPhone);\n```\n\n**资料来源：** [packages/puppeteer-core/src/common/Device.ts:1-30]()\n\n## CPU Throttling\n\nThe `emulateCPUThrottling` method enables CPU throttling to simulate slow CPUs:\n\n```typescript\n// No throttling (1x speed)\nawait page.emulateCPUThrottling(1);\n\n// 2x slowdown\nawait page.emulateCPUThrottling(2);\n\n// Disable throttling\nawait page.emulateCPUThrottling(null);\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:355-360]()\n\n## Metrics API\n\nThe `metrics()` method returns performance metrics from the browser:\n\n### Returned Metrics\n\n| Metric | Description |\n|--------|-------------|\n| `Timestamp` | Monotonic timestamp when sample was taken |\n| `Documents` | Number of documents in the page |\n| `Frames` | Number of frames in the page |\n| `JSEventListeners` | Number of JavaScript event listeners |\n| `Nodes` | Number of DOM nodes |\n| `LayoutCount` | Total full or partial page layouts |\n| `RecalcStyleCount` | Total style recalculations |\n| `LayoutDuration` | Combined layout duration |\n| `RecalcStyleDuration` | Combined style recalculation duration |\n| `ScriptDuration` | Combined JavaScript execution duration |\n| `TaskDuration` | Combined browser task duration |\n| `JSHeapUsedSize` | Used JavaScript heap size |\n| `JSHeapTotalSize` | Total JavaScript heap size |\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:260-280]()\n\n## Heap Snapshot\n\nThe `captureHeapSnapshot` method captures a snapshot of the JavaScript heap:\n\n```typescript\nawait page.captureHeapSnapshot({ path: 'screenshot.png' });\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:285-290]()\n\n## Locator API\n\nThe Page API integrates with Puppeteer's Locator API for reliable element interactions:\n\n### Available Locator Methods\n\n```typescript\n// Query elements using various selector types\nconst element = page.locator('button.submit');\nconst elements = page.locator('.item');\n\n// ARIA selectors\nconst searchInput = page.locator('::-p-aria(Search)');\n\n// Text selectors\nconst title = page.locator('::-p-text(Customize and automate)');\n\n// XPath selectors\nconst para = page.locator('::-p-xpath(//p[@class=\"intro\"])');\n\n// CSS with pierce (shadow DOM)\nconst shadowElement = page.locator(':scope >>> .shadow-content');\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/locators/locators.ts:1-50]()\n\n## LazyArg System\n\nThe LazyArg system provides lazy evaluation of arguments passed to page functions:\n\n```typescript\nexport class LazyArg {\n static create = (\n get: (context: PuppeteerUtilWrapper) => Promise | T\n ): T => {\n return new LazyArg(get) as unknown as T;\n };\n\n async get(context: Context): Promise {\n return await this.#get(context);\n }\n}\n```\n\nThis allows arguments to be evaluated on-demand in the browser context, avoiding serialization issues with complex objects.\n\n**资料来源：** [packages/puppeteer-core/src/common/LazyArg.ts:1-40]()\n\n## Event Handling\n\nThe Page class extends EventEmitter and emits various events documented in the `PageEvent` enum:\n\n### Basic Event Usage\n\n```typescript\n// Listen for a single event\npage.once('load', () => console.log('Page loaded!'));\n\n// Listen for ongoing events\npage.on('request', request => {\n console.log('Request:', request.url());\n});\n\n// Unsubscribe from events\nfunction logRequest(request) {\n console.log('A request was made:', request.url());\n}\npage.on('request', logRequest);\npage.off('request', logRequest);\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:180-200]()\n\n## Error Handling\n\n### Evaluation Errors\n\nWhen JavaScript evaluation fails, Puppeteer throws a descriptive error:\n\n```typescript\nconst { exceptionDetails, result } = await this.#client.send(\n 'Runtime.evaluate',\n {\n expression: expressionWithSourceUrl,\n contextId,\n returnByValue,\n awaitPromise: true,\n userGesture: true,\n }\n).catch(rewriteError);\n\nif (exceptionDetails) {\n throw createEvaluationError(exceptionDetails);\n}\n```\n\n**资料来源：** [packages/puppeteer-core/src/cdp/ExecutionContext.ts:50-65]()\n\n## Implementation Backends\n\n### CDP (Chrome DevTools Protocol) Backend\n\nThe CDP implementation uses Chrome's native DevTools Protocol for communication:\n\n- Located in `packages/puppeteer-core/src/cdp/Page.ts`\n- Direct protocol-level control\n- Lower-level access to browser features\n\n### WebDriver BiDi Backend\n\nThe BiDi implementation provides cross-browser compatibility:\n\n- Located in `packages/puppeteer-core/src/bidi/Page.ts`\n- Standardized WebDriver protocol\n- Broader browser support\n\n## Summary\n\nThe Page API provides a comprehensive abstraction layer for browser page automation in Puppeteer. Key capabilities include:\n\n| Category | Features |\n|----------|----------|\n| **Navigation** | URL access, goto, reload, back, forward |\n| **JavaScript** | evaluate, exposeFunction, handle serialization |\n| **Emulation** | Media types, media features, CPU throttling, device profiles |\n| **Metrics** | Performance metrics, heap snapshots |\n| **Interaction** | Locators, event handling, drag simulation |\n| **State** | Timeout settings, tab identification, request tracking |\n\nThe abstract Page class is implemented by both CDP and BiDi backends, ensuring flexibility and cross-browser compatibility while maintaining a consistent API surface for users.\n\n---\n\n\n\n## Locators and Element Handles\n\n### 相关页面\n\n相关主题：[Page API](#page-api), [Input Handling](#input-handling)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/api/ElementHandle.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/ElementHandle.ts)\n- [packages/puppeteer-core/src/api/Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)\n- [packages/puppeteer-core/src/api/Frame.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Frame.ts)\n- [packages/puppeteer-core/src/common/CSSQueryHandler.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/CSSQueryHandler.ts)\n- [packages/puppeteer-core/src/common/AriaQueryHandler.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/AriaQueryHandler.ts)\n- [packages/puppeteer-core/src/common/CustomQueryHandler.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/CustomQueryHandler.ts)\n- [packages/puppeteer-core/src/injected/PQuerySelector.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/injected/PQuerySelector.ts)\n- [tools/eslint/src/use-using.ts](https://github.com/puppeteer/puppeteer/blob/main/tools/eslint/src/use-using.ts)\n \n\n# Locators and Element Handles\n\n## Overview\n\nPuppeteer provides two complementary mechanisms for interacting with DOM elements in a browser page: **Locators** and **Element Handles**. Both serve the purpose of referencing and manipulating elements, but they differ significantly in their design philosophy, retry behavior, and use cases.\n\n- **Element Handles** provide direct, immediate references to DOM elements. They are point-in-time references that do not automatically retry if elements become stale or unavailable.\n- **Locators** are designed for reliability and resilience. They automatically retry actions until the element is in the correct state, making them ideal for modern web applications with dynamic content.\n\n资料来源：[packages/puppeteer-core/src/api/ElementHandle.ts:1-50]()\n\n```mermaid\ngraph TD\n A[User Code] --> B{Choose Strategy}\n B --> C[ElementHandle]\n B --> D[Locator]\n C --> E[Direct DOM Reference]\n C --> F[No Auto-Retry]\n D --> G[Query Strategy + Retry Logic]\n D --> H[State Awareness]\n D --> I[Action Chaining]\n```\n\n## Element Handles\n\n### Purpose and Scope\n\nElement Handles are direct references to DOM elements obtained through query methods like `page.$()` or `page.$$()`. They provide low-level access to elements but require manual management of element lifecycle.\n\n资料来源：[packages/puppeteer-core/src/api/ElementHandle.ts:40-60]()\n\n### Class Definition\n\n```typescript\nexport abstract class ElementHandle<\n ElementType extends Node = Element,\n> extends JSHandle {\n /**\n * @internal\n */\n declare [_isElementHandle]: boolean;\n\n /**\n * @internal\n * Cached isolatedHandle to prevent\n * trying to adopt it multiple times\n */\n isolatedHandle?: typeof this;\n\n /**\n * @internal\n */\n protected readonly handle;\n}\n```\n\n资料来源：[packages/puppeteer-core/src/api/ElementHandle.ts:40-58]()\n\n### Key Characteristics\n\n| Characteristic | Description |\n|----------------|-------------|\n| **Lifecycle** | Auto-disposed when frame navigates or context is destroyed |\n| **Garbage Collection** | Prevents GC while handle exists unless explicitly disposed |\n| **Type Safety** | Generic type parameter for element type (e.g., `ElementHandle`) |\n| **Usage** | Used as arguments in `Page.$eval` and `Page.evaluate` |\n\n### Query Methods\n\nElement Handles can be created using the following Page/Frame methods:\n\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `page.$(selector)` | `ElementHandle \\| null` | First element matching selector |\n| `page.$$(selector)` | `ElementHandle[]` | All elements matching selector |\n| `frame.$(selector)` | `ElementHandle \\| null` | First element in frame |\n| `frame.$$(selector)` | `ElementHandle[]` | All elements in frame |\n\n资料来源：[packages/puppeteer-core/src/api/Frame.ts:100-130]()\n\n### Memory Management with `using`\n\nPuppeteer provides an ESLint rule to enforce proper disposal of Element Handles using the `using` keyword. This ensures handles are automatically cleaned up when they go out of scope.\n\n```typescript\nimport puppeteer from 'puppeteer';\n\nconst browser = await puppeteer.launch();\nconst page = await browser.newPage();\nawait page.goto('https://example.com');\n\n// Using 'using' ensures proper cleanup\nusing element = await page.$('a');\nawait element.click();\n```\n\n资料来源：[tools/eslint/src/use-using.ts:1-50]()\n\n```typescript\nconst usingSymbols = ['ElementHandle', 'JSHandle'];\n```\n\n资料来源：[tools/eslint/src/use-using.ts:12]()\n\n## Locators\n\n### Purpose and Design Philosophy\n\nLocators are Puppeteer's recommended approach for element interaction. They encapsulate both the query strategy and retry logic, providing a robust way to handle flaky tests in modern web applications where elements may appear, disappear, or change state dynamically.\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1-100]()\n\n### Locator API\n\nLocators are created through the `locator()` method on Page or Frame:\n\n```typescript\nlocator(\n selector: Selector,\n): Locator>;\n\nlocator(func: () => Awaitable): Locator;\n```\n\n### Supported Selector Types\n\nPuppeteer supports multiple selector types that can be used with both Element Handles and Locators:\n\n| Selector Type | Syntax | Description |\n|---------------|--------|-------------|\n| CSS | `''` | Standard CSS selectors |\n| Text | `::-p-text()` | Elements containing text |\n| ARIA | `::-p-aria([name])` | Accessibility-based selection |\n| XPath | `xpath=` | XPath expressions |\n| Pierce | `>>> ` | Cross-shadow-DOM queries |\n| Custom | Custom prefix | User-defined query handlers |\n\n资料来源：[packages/puppeteer-core/src/common/CSSQueryHandler.ts]()\n\n### Query Handlers Architecture\n\nQuery handlers are the pluggable components that process different selector types.\n\n```mermaid\nclassDiagram\n class QueryHandler {\n <>\n +query(page, selector)\n +queryAll(page, selector)\n }\n class CSSQueryHandler {\n +query(page, selector)\n +queryAll(page, selector)\n }\n class AriaQueryHandler {\n +query(page, selector)\n +queryAll(page, selector)\n }\n class CustomQueryHandler {\n +query(page, selector)\n +queryAll(page, selector)\n }\n class XPathQueryHandler {\n +query(page, selector)\n +queryAll(page, selector)\n }\n \n QueryHandler <|.. CSSQueryHandler\n QueryHandler <|.. AriaQueryHandler\n QueryHandler <|.. CustomQueryHandler\n QueryHandler <|.. XPathQueryHandler\n```\n\n### CSS Query Handler\n\nThe CSS Query Handler processes standard CSS selectors and is the default handler for selectors without a prefix.\n\n```typescript\n// Internal implementation delegates to injected PQuerySelector\nexport class CSSQueryHandler extends QueryHandler {\n #pquerySelector: PQuerySelector;\n // Uses PuppeteerInjectedScript for DOM queries\n}\n```\n\n资料来源：[packages/puppeteer-core/src/common/CSSQueryHandler.ts]()\n\n### Aria Query Handler\n\nThe ARIA Query Handler enables selection based on accessibility attributes:\n\n```typescript\n// Select by role and optional name\nawait page.locator('::-p-aria(Search)').fill('query');\nawait page.locator('::-p-aria(Submit button[name])').click();\n```\n\n资料来源：[packages/puppeteer-core/src/common/AriaQueryHandler.ts]()\n\n### Custom Query Handlers\n\nPuppeteer allows registration of custom query handlers for domain-specific selectors:\n\n```typescript\npage.customQueryHandlers.set('mySelector', {\n queryOne: (self, selector) => { /* ... */ },\n queryAll: (self, selector) => { /* ... */ },\n});\n```\n\n## Comparison: Locators vs Element Handles\n\n| Aspect | Element Handles | Locators |\n|--------|-----------------|----------|\n| **Retry Behavior** | None - immediate result | Automatic retry until element ready |\n| **State Awareness** | None | Tracks element state |\n| **Flakiness Handling** | Manual | Built-in |\n| **Performance** | Faster for single operation | Slight overhead for retry logic |\n| **Use Case** | Simple scripts, single operations | Dynamic applications, tests |\n| **Stale Element Handling** | Manual detection and re-query | Automatic re-query |\n\n```mermaid\ngraph LR\n A[Action Request] --> B{Locator}\n B --> C{Element visible?}\n C -->|No| D[Wait & Retry]\n D --> C\n C -->|Yes| E[Perform Action]\n \n F[Action Request] --> G{ElementHandle}\n G --> H[Immediate Result]\n H --> I[Perform Action]\n I --> J{Still valid?}\n J -->|No| K[StaleElementReference Error]\n```\n\n## Best Practices\n\n### When to Use Locators\n\n- **Recommended** for most use cases\n- Testing modern web applications with dynamic content\n- When element availability timing is uncertain\n- Building resilient automation scripts\n\n### When to Use Element Handles\n\n- Quick scripts with predictable DOM\n- When performance is critical\n- Low-level DOM manipulation\n- Integration with other libraries expecting handles\n\n### Memory Management\n\nAlways dispose of handles to prevent memory leaks:\n\n```typescript\n// Using async disposal\nconst handle = await page.$('div');\ntry {\n // Work with handle\n} finally {\n await handle.dispose();\n}\n\n// Or use 'using' keyword where supported\nusing element = await page.$('a');\n```\n\n### ESLint Integration\n\nEnable the `use-using` rule to enforce proper handle disposal:\n\n```json\n{\n \"rules\": {\n \"@puppeteer/use-using\": \"error\"\n }\n}\n```\n\n资料来源：[tools/eslint/src/use-using.ts:20-60]()\n\n## Examples\n\n### Basic Element Handle Usage\n\n```typescript\nimport puppeteer from 'puppeteer';\n\nconst browser = await puppeteer.launch();\nconst page = await browser.newPage();\nawait page.goto('https://example.com');\n\n// Single element\nconst hrefElement = await page.$('a');\nawait hrefElement.click();\n\n// Multiple elements\nconst links = await page.$$('a');\nfor (const link of links) {\n const text = await link.evaluate(el => el.textContent);\n console.log(text);\n}\n\nawait browser.close();\n```\n\n资料来源：[packages/puppeteer-core/src/api/ElementHandle.ts:10-30]()\n\n### Locator with Action Chaining\n\n```typescript\nimport puppeteer from 'puppeteer';\n\nconst browser = await puppeteer.launch();\nconst page = await browser.newPage();\n\nawait page.goto('https://example.com');\n\n// Chain actions on locator\nawait page.locator('::-p-aria(Search)').fill('query');\nawait page.locator('.devsite-result-item-link').click();\n\n// Wait for element with locator\nconst textSelector = await page\n .locator('::-p-text(Customize and automate)')\n .waitHandle();\n\nawait browser.close();\n```\n\n### Using $$eval for Batch Operations\n\n```typescript\nconst allInputValues = await page.$$eval('input', elements =>\n elements.map(e => e.textContent),\n);\n```\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1-50]()\n\n## Architecture Summary\n\n```mermaid\ngraph TD\n subgraph \"User Layer\"\n A[page.$()]\n B[page.locator()]\n C[frame.$$()]\n end\n \n subgraph \"Query Handler Layer\"\n D[CSSQueryHandler]\n E[AriaQueryHandler]\n F[CustomQueryHandler]\n G[XPathQueryHandler]\n end\n \n subgraph \"Execution Layer\"\n H[CDP Protocol]\n I[BiDi Protocol]\n end\n \n A --> D\n B --> D\n B --> E\n C --> F\n \n D --> H\n D --> I\n E --> H\n F --> H\n \n style A fill:#e1f5fe\n style B fill:#e8f5e8\n style D fill:#fff3e0\n style E fill:#fff3e0\n```\n\n## See Also\n\n- [Page API Documentation](https://pptr.dev/api/puppeteer.page)\n- [Frame API Documentation](https://pptr.dev/api/puppeteer.frame)\n- [ElementHandle API Documentation](https://pptr.dev/api/puppeteer.elementhandle)\n- [Locator API Documentation](https://pptr.dev/api/puppeteer.locator)\n\n---\n\n\n\n## Input Handling\n\n### 相关页面\n\n相关主题：[Locators and Element Handles](#locators), [Page API](#page-api)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this documentation:\n\n- [packages/puppeteer-core/src/api/Input.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Input.ts)\n- [packages/puppeteer-core/src/common/USKeyboardLayout.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/USKeyboardLayout.ts)\n- [packages/puppeteer-core/src/api/Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)\n- [packages/puppeteer-core/src/api/ElementHandle.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/ElementHandle.ts)\n- [packages/puppeteer-core/src/cdp/ExecutionContext.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/ExecutionContext.ts)\n \n\n# Input Handling\n\nInput Handling in Puppeteer provides a unified API for simulating user interactions with web pages, including keyboard input, mouse operations, touch gestures, and drag-and-drop actions. The system abstracts away protocol-level differences between Chrome DevTools Protocol (CDP) and WebDriver BiDi, providing developers with a consistent interface for browser automation.\n\n## Architecture Overview\n\nPuppeteer's Input Handling system follows a layered architecture:\n\n```mermaid\ngraph TD\n A[User Code] --> B[Page API / ElementHandle API]\n B --> C[Protocol-Agnostic Input Interface]\n C --> D[CDP Implementation
packages/puppeteer-core/src/cdp/Input.ts]\n C --> E[BiDi Implementation
packages/puppeteer-core/src/bidi/Input.ts]\n D --> F[Chrome DevTools Protocol]\n E --> G[WebDriver BiDi Protocol]\n F --> H[Browser Instance]\n G --> H\n```\n\nThe system is organized around three core input interfaces defined in the abstract layer:\n\n| Interface | Purpose |\n|-----------|---------|\n| `Keyboard` | Simulates keyboard input including key presses, typing, and modifier keys |\n| `Mouse` | Controls mouse movement, clicking, and wheel scrolling |\n| `Touch` | Simulates touch-based interactions on mobile devices |\n| `DragAndDrop` | Manages drag source and drop target operations |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:1-200]()\n\n## Keyboard Input\n\n### Keyboard Interface Methods\n\nThe `Keyboard` interface provides four primary methods for simulating keyboard input:\n\n| Method | Description |\n|--------|-------------|\n| `down(key, options?)` | Presses a key down without releasing it |\n| `up(key)` | Releases a pressed key |\n| `type(text, options?)` | Types text character by character |\n| `press(key, options?)` | Combines down + up (with optional delay) |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:47-75]()\n\n### Key Input Values\n\nPuppeteer uses the `KeyInput` enum to define all supported keyboard keys. Common values include:\n\n- **Modifier Keys**: `Alt`, `Control`, `Meta`, `Shift`\n- **Arrow Keys**: `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`\n- **Function Keys**: `F1` through `F12`\n- **Special Keys**: `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `Space`\n- **Alpha-Numeric**: Standard letter and number keys (e.g., `a`, `A`, `1`)\n\n### Type vs Press\n\nThe `type()` method sends `keydown`, `keypress/input`, and `keyup` events for each character in the text. Unlike `press()`, modifier keys do not affect `type()` - holding Shift will not type uppercase characters.\n\n```typescript\nawait page.keyboard.type('Hello'); // Types instantly\nawait page.keyboard.type('World', {delay: 100}); // Types with 100ms between each key\n```\n\nThe `press()` method is a shortcut combining `down()` and `up()`. If the key is a single character with no modifiers besides Shift, a `keypress/input` event is also generated.\n\n```typescript\nawait page.keyboard.press('Enter');\nawait page.keyboard.press('Control', {delay: 100});\nawait page.keyboard.press('KeyA', {text: 'a'});\n```\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:35-75]()\n\n### Keyboard Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `delay` | `number` | Time in milliseconds between `keydown` and `keyup` (default: `0`) |\n| `text` | `string` | Forces an input event with this text |\n| `commands` | `string[]` | Browser command names for keyboard shortcuts |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:26-33]()\n\n## Mouse Input\n\n### Mouse Interface Methods\n\nThe `Mouse` interface provides precise control over cursor movement and clicking:\n\n| Method | Description |\n|--------|-------------|\n| `move(x, y, options?)` | Moves the mouse to the specified coordinates |\n| `down(options?)` | Presses the mouse button |\n| `up(options?)` | Releases the mouse button |\n| `click(x, y, options?)` | Performs a full click (down + up) at coordinates |\n| `wheel(options?)` | Scrolls the page |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:92-132]()\n\n### Mouse Click Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `button` | `MouseButton` | `'left'` | Which button to click |\n| `clickCount` | `number` | `1` | Number of clicks (for double-click) |\n| `delay` | `number` | `0` | Delay between mousedown and mouseup in ms |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:135-155]()\n\n### Mouse Move Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `steps` | `number` | `1` | Number of intermediate mouse moves for smooth transitions |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:157-170]()\n\n### Mouse Wheel Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `deltaX` | `number` | `0` | Horizontal scroll amount |\n| `deltaY` | `number` | `0` | Vertical scroll amount |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:172-187]()\n\n### Click Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Mouse as Mouse Interface\n participant Page as Page\n \n User->>Mouse: click(x, y, {button: 'left', clickCount: 2})\n Mouse->>Page: mouseMoved(x, y)\n Mouse->>Page: mousePressed(x, y, button: 'left', clickCount: 1)\n Mouse->>Page: mouseReleased(x, y, button: 'left', clickCount: 1)\n Mouse->>Page: mousePressed(x, y, button: 'left', clickCount: 2)\n Mouse->>Page: mouseReleased(x, y, button: 'left', clickCount: 2)\n```\n\n## Touch Input\n\nThe `Touch` interface simulates touch interactions for mobile device testing:\n\n| Method | Description |\n|--------|-------------|\n| `tap(x, y)` | Performs a tap at the specified coordinates |\n| `touchStart(x, y)` | Starts a touch at the coordinates |\n| `touchMove(x, y)` | Moves the touch to new coordinates |\n| `touchEnd()` | Ends the current touch sequence |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:194-210]()\n\n## Drag and Drop\n\nThe `DragAndDrop` interface handles drag interactions:\n\n| Method | Description |\n|--------|-------------|\n| `drag(source, destination)` | Drags from source to destination, returns drag data |\n| `drop(x, y, data)` | Drops data at the specified coordinates |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:212-220]()\n\n## High-Level Element Interactions\n\nFor common use cases, Puppeteer provides convenience methods on `Page` and `ElementHandle` that handle input internally.\n\n### Page-Level Input\n\nThe `Page` class exposes input methods that operate on the main frame:\n\n```typescript\n// Type text into an element\nawait page.type('#mytextarea', 'Hello');\nawait page.type('#mytextarea', 'World', {delay: 100});\n\n// Press a special key\nawait page.keyboard.press('Enter');\nawait page.keyboard.press('ArrowDown');\n```\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1800-1820]()\n\n### ElementHandle Input\n\n`ElementHandle` provides element-specific input methods:\n\n```typescript\nconst element = await page.$('#input-field');\n\n// Focus the element and type\nawait element.type('Hello');\n\n// Focus the element and press a key\nawait element.press('Enter');\n```\n\nBoth methods automatically focus the element before performing the input action:\n\n```typescript\nasync type(\n text: string,\n options?: Readonly,\n): Promise {\n await this.focus();\n await this.frame.page().keyboard.type(text, options);\n}\n\nasync press(\n key: KeyInput,\n options?: Readonly,\n): Promise {\n await this.focus();\n await this.frame.page().keyboard.press(key, options);\n}\n```\n\n资料来源：[packages/puppeteer-core/src/api/ElementHandle.ts:620-640]()\n\n## Implementation Strategies\n\n### CDP Implementation\n\nThe Chrome DevTools Protocol implementation translates abstract input calls into CDP commands:\n\n- `Input.dispatchMouseEvent` for mouse operations\n- `Input.dispatchKeyEvent` for keyboard operations\n- Direct touch event dispatching\n\nThe CDP implementation handles the translation of keyboard codes using US keyboard layout definitions.\n\n### BiDi Implementation\n\nThe WebDriver BiDi implementation uses the BiDi specification's `input` module:\n\n- Maps to BiDi `input.performActions` command\n- Handles serialization of input actions across the protocol wire\n\n### US Keyboard Layout\n\nThe `USKeyboardLayout` module provides key code mappings for US keyboards:\n\n```typescript\nexport const USKeyboardLayout: Map = new Map([\n ['a', 0x61],\n ['A', 0x41],\n ['b', 0x62],\n // ... additional mappings\n]);\n```\n\n资料来源：[packages/puppeteer-core/src/common/USKeyboardLayout.ts:1-100]()\n\n## Best Practices\n\n1. **Use `press()` for special keys**: Instead of `type()` for special characters, use `press()` with key names like `Enter`, `Tab`, or `Escape`.\n\n2. **Add delays for realistic simulation**: When testing UI behavior that depends on timing, use the `delay` option:\n\n ```typescript\n await page.type('#search', 'query', {delay: 100});\n ```\n\n3. **Focus elements before typing**: When using `ElementHandle` input methods, the element is automatically focused. For direct keyboard access, ensure the target is focused first.\n\n4. **Use `click()` over `down()/up()`**: The `click()` method handles the complete click lifecycle and is less error-prone.\n\n5. **Consider `Locator` API for reliability**: For improved reliability in element interactions, consider using Puppeteer's experimental [Locators API](https://pptr.dev/guides/page-interactions#locators).\n\n## Related Components\n\n| Component | Purpose |\n|-----------|---------|\n| `Page` | Exposes input methods on the main frame |\n| `ElementHandle` | Element-specific keyboard input |\n| `Frame` | Frame-level input access |\n| `Keyboard` | Low-level keyboard simulation |\n| `Mouse` | Low-level mouse control |\n| `Touch` | Touch interaction simulation |\n| `DragAndDrop` | Drag and drop operations |\n\n---\n\n\n\n## Browser Launching\n\n### 相关页面\n\n相关主题：[Package Structure](#packages)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/node/BrowserLauncher.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/node/BrowserLauncher.ts)\n- [packages/puppeteer-core/src/node/ChromeLauncher.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/node/ChromeLauncher.ts)\n- [packages/puppeteer-core/src/node/FirefoxLauncher.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/node/FirefoxLauncher.ts)\n- [packages/puppeteer-core/src/node/LaunchOptions.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/node/LaunchOptions.ts)\n- [packages/browsers/src/CLI.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/browsers/src/CLI.ts)\n- [packages/browsers/src/install.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/browsers/src/install.ts)\n \n\n# Browser Launching\n\n## Overview\n\nBrowser launching is a core system in Puppeteer that handles the initialization and lifecycle management of browser instances. This system provides a unified interface for launching different browser types (Chrome, Firefox) while abstracting platform-specific details and managing process signals, timeouts, and executable paths.\n\nThe browser launching subsystem consists of several key components:\n\n- **BrowserLauncher**: Abstract base class defining the launching interface\n- **ChromeLauncher**: Implementation for Chrome/Chromium-based browsers\n- **FirefoxLauncher**: Implementation for Firefox\n- **@puppeteer/browsers**: Standalone package for programmatic browser management\n\n## Architecture\n\n### Class Hierarchy\n\n```mermaid\ngraph TD\n A[BrowserLauncher] --> B[ChromeLauncher]\n A --> C[FirefoxLauncher]\n D[launch.ts] --> E[Browser Process]\n F[install.ts] --> G[Browser Binaries]\n \n style A fill:#e1f5fe\n style B fill:#e8f5e8\n style C fill:#fff3e0\n```\n\n### Browser Launch Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Puppeteer\n participant BrowserLauncher\n participant BrowserProcess\n participant CDP\n \n User->>Puppeteer: puppeteer.launch(options)\n Puppeteer->>BrowserLauncher: createLauncher(options)\n BrowserLauncher->>BrowserLauncher: resolveExecutablePath()\n BrowserLauncher->>BrowserLauncher: buildArguments()\n BrowserLauncher->>BrowserProcess: spawn(executable, args)\n BrowserProcess-->>BrowserLauncher: process started\n BrowserLauncher->>BrowserLauncher: setupSignalHandlers()\n BrowserLauncher->>CDP: connect(wsEndpoint)\n CDP-->>Puppeteer: Browser instance\n User->>Puppeteer: browser operations\n User->>Puppeteer: browser.close()\n Puppeteer->>BrowserProcess: terminate()\n```\n\n## Launch Options\n\nThe `LaunchOptions` interface defines all configuration parameters available when launching a browser. These options control executable selection, argument passing, signal handling, and timeout behavior.\n\n### Core Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `executablePath` | `string` | bundled browser | Path to a specific browser executable. When using this, Puppeteer cannot guarantee compatibility. |\n| `ignoreDefaultArgs` | `boolean \\| string[]` | `false` | Controls whether default arguments are passed to the browser. Array mode filters specific args. |\n| `enableExtensions` | `boolean \\| string[]` | `false` | Enables browser extensions. String array loads extensions from paths. |\n\n### Signal Handling\n\nPuppeteer manages browser process lifecycle through POSIX signal handling:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `handleSIGINT` | `boolean` | `true` | Close browser on `Ctrl+C` (SIGINT) |\n| `handleSIGTERM` | `boolean` | `true` | Close browser on termination signal (SIGTERM) |\n| `handleSIGHUP` | `boolean` | `true` | Close browser on terminal hangup (SIGHUP) |\n\n### Timeout Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `timeout` | `number` | `30,000` (30 seconds) | Maximum time in milliseconds to wait for browser startup. Pass `0` to disable timeout. |\n\n## Browser Installation\n\n### CLI Installation\n\nThe `@puppeteer/browsers` package provides command-line tools for downloading and managing browser binaries:\n\n```bash\n# Download latest stable Chrome\nnpx @puppeteer/browsers install chrome@stable\n\n# Download specific version\nnpx @puppeteer/browsers install chrome@116.0.5793.0\n\n# Download by milestone\nnpx @puppeteer/browsers install chrome@117\n\n# Download ChromeDriver\nnpx @puppeteer/browsers install chromedriver@canary\n\n# List installed browsers\nnpx @puppeteer/browsers list\n\n# Clear all browsers\nnpx @puppeteer/browsers clear\n```\n\n### Configuration Options\n\nThe `Configuration` interface controls download behavior:\n\n| Option | Environment Variable | Default | Description |\n|--------|---------------------|---------|-------------|\n| `skipDownload` | `PUPPETEER_SKIP_DOWNLOAD` | `false` | Skip browser download during installation |\n| `temporaryDirectory` | `PUPPETEER_TMP_DIR` | `os.tmpdir()` | Directory for temporary files |\n| `logLevel` | - | `warn` | Logging level: `silent`, `error`, `warn` |\n\n### Browser-Specific Settings\n\nEach browser type supports independent configuration:\n\n| Browser | Skip Download Env Var | Download Base URL Env Var | Version Env Var |\n|---------|----------------------|---------------------------|-----------------|\n| Chrome | `PUPPETEER_CHROME_SKIP_DOWNLOAD` | `PUPPETEER_CHROME_DOWNLOAD_BASE_URL` | `PUPPETEER_CHROME_VERSION` |\n| Chrome Headless Shell | `PUPPETEER_CHROME_HEADLESS_SHELL_SKIP_DOWNLOAD` | `PUPPETEER_CHROME_HEADLESS_SHELL_DOWNLOAD_BASE_URL` | - |\n| Firefox | `PUPPETEER_FIREFOX_SKIP_DOWNLOAD` | `PUPPETEER_FIREFOX_DOWNLOAD_BASE_URL` | `PUPPETEER_FIREFOX_VERSION` |\n\n### Download Base URLs\n\n| Browser | Default URL |\n|---------|-------------|\n| Chrome | `https://storage.googleapis.com/chrome-for-testing-public` |\n| Firefox | `https://archive.mozilla.org/pub/firefox/releases` |\n\n## Chrome Launcher\n\nThe `ChromeLauncher` handles launching Chrome and Chromium-based browsers. It manages the Chrome DevTools Protocol (CDP) connection and applies Chrome-specific default arguments.\n\n### Key Responsibilities\n\n1. **Executable Resolution**: Locates the Chrome executable based on platform and configuration\n2. **Argument Construction**: Builds the complete argument list including default Chrome flags\n3. **Profile Management**: Creates temporary user data directories for isolated browser contexts\n4. **CDP Connection**: Establishes WebSocket connection to the browser's DevTools interface\n\n### Default Arguments\n\nChrome Launcher automatically includes secure defaults:\n- `--no-sandbox` (when not running as root on Linux)\n- `--disable-dev-shm-usage` (prevents crashes in Docker environments)\n- Remote debugging port selection\n\n## Firefox Launcher\n\nThe `FirefoxLauncher` provides Firefox-specific launching capabilities with support for Mozilla's remote debugging protocol.\n\n### Differences from Chrome\n\n- Uses Firefox's built-in DevTools protocol instead of CDP\n- Handles Firefox-specific argument syntax\n- Manages Firefox profile creation and cleanup\n\n## Browser Management\n\n### Programmatic Browser Management\n\nThe `@puppeteer/browsers` package allows programmatic browser control:\n\n```typescript\nimport {install, launch, clear, Browser} from '@puppeteer/browsers';\n\nasync function setupBrowser() {\n // Install browser\n const installOpts = {\n browser: Browser.CHROME,\n buildId: 'stable',\n cacheDir: './browser-cache'\n };\n \n await install(installOpts);\n \n // Launch browser\n const launchOpts = {\n executablePath: await getExecutablePath(installOpts),\n args: ['--no-sandbox']\n };\n \n const browserProcess = await launch(launchOpts);\n return browserProcess;\n}\n```\n\n### Browser Cleanup\n\nBrowsers installed by Puppeteer can be automatically cleaned up during version updates:\n\n```mermaid\ngraph TD\n A[Puppeteer Launch] --> B[Load Installed Browsers]\n B --> C{Is Browser Current?}\n C -->|Yes| D[Keep Browser]\n C -->|No| E[Uninstall Old Build]\n F[New Version Available] --> C\n```\n\nThe cleanup process:\n1. Compares installed browser versions against Puppeteer's pinned versions\n2. Identifies browsers no longer managed by current Puppeteer\n3. Removes outdated browser builds using `uninstall()` with `buildId` and `platform`\n\n## Signal Handling Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Launching: launch()\n Launching --> Running: Browser Started\n Running --> Closing: close() / SIGINT / SIGTERM / SIGHUP\n Closing --> [*]: Process Terminated\n \n Running --> Running: New Page Created\n```\n\n### Signal Handler Configuration\n\n| Signal | Default | Purpose |\n|--------|---------|---------|\n| `SIGINT` | Enabled | `Ctrl+C` interruption |\n| `SIGTERM` | Enabled | Process termination |\n| `SIGHUP` | Enabled | Terminal disconnect |\n\nDisabling signal handlers is possible but not recommended as it may leave orphaned browser processes:\n\n```typescript\nconst browser = await puppeteer.launch({\n handleSIGINT: false,\n handleSIGTERM: false,\n handleSIGHUP: false\n});\n```\n\n## Timeout Behavior\n\n```mermaid\ngraph LR\n A[launch()] --> B{timeout > 0?}\n B -->|Yes| C[Wait ms]\n B -->|No| D[No Timeout]\n C --> E{Browser Ready?}\n E -->|Yes| F[Return Browser]\n E -->|No| G[Throw Timeout Error]\n D --> F\n```\n\nTimeout of `0` disables the startup timeout entirely, useful for:\n- Debugging launch issues\n- Slow systems with many browser dependencies\n- Long initialization sequences\n\n## Best Practices\n\n1. **Always use `await browser.close()`** to properly terminate browser processes\n2. **Set reasonable timeouts** for production environments\n3. **Use bundled browsers** for guaranteed compatibility\n4. **Enable signal handlers** (default) for clean shutdowns\n5. **Use `--no-sandbox`** only when necessary for containerized environments\n\n## Related Components\n\n| Component | Purpose |\n|-----------|---------|\n| `Page` | Browser page/tab abstraction |\n| `BrowserContext` | Isolated browser sessions |\n| `HTTPRequest/HTTPResponse` | Network request handling |\n| `TimeoutSettings` | Configurable timeout management |\n\n## Source References\n\n- Launch options definition: `packages/puppeteer-core/src/node/LaunchOptions.ts:1-50`\n- Browser launcher base: `packages/puppeteer-core/src/node/BrowserLauncher.ts`\n- Chrome-specific launch: `packages/puppeteer-core/src/node/ChromeLauncher.ts`\n- Firefox-specific launch: `packages/puppeteer-core/src/node/FirefoxLauncher.ts`\n- Browser installation: `packages/browsers/src/install.ts`\n- Browser launch process: `packages/browsers/src/launch.ts`\n- CLI definitions: `packages/browsers/src/CLI.ts:1-60`\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：puppeteer/puppeteer\n\n摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Chrome Canary/Firefox Nightly test results。\n\n## 1. 安装坑 · 来源证据：Chrome Canary/Firefox Nightly test results\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Chrome Canary/Firefox Nightly test results\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1aabe120a9df47a2adbd293381b50a64 | https://github.com/puppeteer/puppeteer/issues/12379 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Puppeteer v25\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Puppeteer v25\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_050f65ceff2a455da4a3538895a7538b | https://github.com/puppeteer/puppeteer/issues/14342 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：[Bug]: GHSA issued a false malicious package alert for puppeteer\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: GHSA issued a false malicious package alert for puppeteer\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_55588dfbd41442fdb8a2f4f1be57e4c9 | https://github.com/puppeteer/puppeteer/issues/14986 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：[Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stderr`\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stderr`\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9b1ef7c38ed14c41b3e4ce786adcdf26 | https://github.com/puppeteer/puppeteer/issues/14774 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：[Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 (extract-zip 2.0.1)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 (extract-zip 2.0.1)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5d1f448d8768460a806ab32e8d4f6997 | https://github.com/puppeteer/puppeteer/issues/14957 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[Bug]: `setViewport` crashes on Firefox if uncaught\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: `setViewport` crashes on Firefox if uncaught\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_75bddb8a74194cf7a8978853f19db23a | https://github.com/puppeteer/puppeteer/issues/14989 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：[Bug]: chrome binary is not present when installing latest chrome\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: chrome binary is not present when installing latest chrome\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1e85cdab2b684dda8e5c83f55b8ff7b6 | https://github.com/puppeteer/puppeteer/issues/14988 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：[Feature]: Make proxy-agent dependency optional\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Make proxy-agent dependency optional\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_195c51e4a5e84edda14a2a79b456821c | https://github.com/puppeteer/puppeteer/issues/13775 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：browsers: v3.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：browsers: v3.0.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bf2d83568c54447fbfd3047d24be0c48 | https://github.com/puppeteer/puppeteer/releases/tag/browsers-v3.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 来源证据：browsers: v3.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：browsers: v3.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c9f08632e7ee4e9485d27b864a21e462 | https://github.com/puppeteer/puppeteer/releases/tag/browsers-v3.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 能力坑 · 来源证据：puppeteer-core: v25.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：puppeteer-core: v25.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3a8b10a5263e4d6488e16972c8249a38 | https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v25.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\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:90796663 | https://github.com/puppeteer/puppeteer | README/documentation is current enough for a first validation pass.\n\n## 13. 维护坑 · 来源证据：ng-schematics: v0.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：ng-schematics: v0.8.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e7ee6a70b1d4fb6879ab4670099d205 | https://github.com/puppeteer/puppeteer/releases/tag/ng-schematics-v0.8.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 来源证据：puppeteer-core: v25.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：puppeteer-core: v25.0.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3e6a5770b15146ddab5249f1aa687cae | https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v25.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 维护坑 · 来源证据：puppeteer: v25.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：puppeteer: v25.0.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9294fdbab95d446887bdb54a11df66d2 | https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-v25.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:90796663 | https://github.com/puppeteer/puppeteer | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:90796663 | https://github.com/puppeteer/puppeteer | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:90796663 | https://github.com/puppeteer/puppeteer | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 来源证据：[Feature]: Reducing dependencies\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: Reducing dependencies\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cb21a546ebb04ca39b334255b205c9da | https://github.com/puppeteer/puppeteer/issues/13552 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · 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:90796663 | https://github.com/puppeteer/puppeteer | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:90796663 | https://github.com/puppeteer/puppeteer | release_recency=unknown\n\n\n",
"markdown_key": "puppeteer",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:90796663",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/puppeteer/puppeteer"
},
{
"evidence_id": "art_98bdc3ac95604419bbb62b7ca1e325c0",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/puppeteer/puppeteer#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "puppeteer 说明书",
"toc": [
"https://github.com/puppeteer/puppeteer 项目说明书",
"目录",
"Getting Started",
"Overview",
"Installation",
"Full package - downloads compatible Chrome during installation",
"Core package - library only, without downloading Chrome",
"Using npm",
"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": "3aadc38c533caa8df87f381868291ede870883e2",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"docs/contributing.md",
"docs/index.md",
"docs/troubleshooting.md",
"docs/webdriver-bidi.md",
"docs/examples.md",
"docs/faq.md",
"docs/supported-browsers.md",
"docs/CHANGELOG.md",
"docs/api/puppeteer.page.emulate.md",
"docs/api/puppeteer.locatorevents.md",
"docs/api/puppeteer.page.windowid.md",
"docs/api/puppeteer.page.evaluatehandle.md",
"docs/api/puppeteer.page.bringtofront.md",
"docs/api/puppeteer.commoneventemitter.removealllisteners.md",
"docs/api/puppeteer.quad.md",
"docs/api/puppeteer.page.setuseragent.md",
"docs/api/puppeteer.browser.setcookie.md",
"docs/api/puppeteer.permissionstate_2.md",
"docs/api/puppeteer.puppeteernode.trimcache.md",
"docs/api/puppeteer.httprequest.postdata.md",
"docs/api/puppeteer.mouse.drop.md",
"docs/api/puppeteer.page.setrequestinterception.md",
"docs/api/puppeteer.customqueryhandler.md",
"docs/api/puppeteer.puppeteernode.defaultargs.md",
"docs/api/puppeteer.browser.wsendpoint.md",
"docs/api/puppeteer.page.browser.md",
"docs/api/puppeteer.networkconditions.md",
"docs/api/puppeteer.executablepath.md",
"docs/api/puppeteer.downloadpolicy.md",
"docs/api/puppeteer.offset.md",
"docs/api/puppeteer.resourcetype.md",
"docs/api/puppeteer.devicerequestprompt.cancel.md",
"docs/api/puppeteer.jshandle.getproperties.md",
"docs/api/puppeteer.predicate.md",
"docs/api/puppeteer.coverage.md",
"docs/api/puppeteer.evaluatefuncwith.md",
"docs/api/puppeteer.touchscreen.tap.md",
"docs/api/puppeteer.pageevent.md"
],
"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": "# puppeteer-repo - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 puppeteer-repo 编译的 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- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `packages/browsers/README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm i puppeteer # Downloads compatible Chrome during installation.` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `npm i puppeteer-core # Alternatively, install as a library, without downloading Chrome.` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npx @puppeteer/browsers --help` 证据：`packages/browsers/README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86\n- `npx @puppeteer/browsers --help # help for all commands` 证据：`packages/browsers/README.md` Claim：`clm_0006` supported 0.86\n- `npx @puppeteer/browsers install --help # help for the install command` 证据：`packages/browsers/README.md` Claim：`clm_0007` supported 0.86\n- `npx @puppeteer/browsers launch --help # help for the launch command` 证据：`packages/browsers/README.md` Claim：`clm_0008` supported 0.86\n- `npx @puppeteer/browsers clear --help # help for the clear command` 证据：`packages/browsers/README.md` Claim：`clm_0009` supported 0.86\n- `npx @puppeteer/browsers list --help # help for the list command` 证据：`packages/browsers/README.md` Claim：`clm_0010` supported 0.86\n- `npx @puppeteer/browsers@latest --help` 证据：`packages/browsers/README.md` Claim：`clm_0011` supported 0.86\n- `npx @puppeteer/browsers@2.4.1 --help` 证据：`packages/browsers/README.md` Claim：`clm_0012` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `packages/browsers/README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `packages/browsers/README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `packages/browsers/README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`package.json`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\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_0023` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `packages/browsers/README.md` Claim：`clm_0024` 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- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `packages/browsers/README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：2105\n- 重要文件覆盖：40/2105\n- 证据索引条目：80\n- 角色 / Skill 条目：63\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请基于 puppeteer-repo 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 puppeteer-repo 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 puppeteer-repo 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 63 个角色 / Skill / 项目文档条目。\n\n- **Contributing**（project_doc）：First of all, thank you for your interest in Puppeteer! We'd love to accept your patches and contributions! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/contributing.md`\n- **Puppeteer**（project_doc）：! build https://github.com/puppeteer/puppeteer/actions/workflows/ci.yml/badge.svg?branch=main https://github.com/puppeteer/puppeteer/actions/workflows/ci.yml ! npm puppeteer package https://img.shields.io/npm/v/puppeteer.svg https://npmjs.org/package/puppeteer 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Dockerfile for Puppeteer**（project_doc）：This directory contains files needed to containerize Puppeteer. The major problem that this is solving is the problem of providing all dependencies required to run a browser instance. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docker/README.md`\n- **Puppeteer: Examples**（project_doc）：This is the official set of Puppeteer examples. For a list of curated examples and use-cases, including third-party ones, see pptr.dev/examples https://pptr.dev/examples . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/README.md`\n- **Puppeteer tests**（project_doc）：Unit tests in Puppeteer are written using Mocha as the test runner and Expect as the assertions library. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`test/README.md`\n- **Website**（project_doc）：This website is built using Docusaurus 3 https://docusaurus.io/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`website/README.md`\n- **@puppeteer/browsers**（project_doc）：Manage and launch browsers/drivers from a CLI or programmatically. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/browsers/README.md`\n- **Puppeteer Angular Schematic**（project_doc）：Adds Puppeteer-based e2e tests to your Angular project. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/ng-schematics/README.md`\n- **bidi/core**（project_doc）：bidi/core is a low-level layer that sits above the WebDriver BiDi transport to provide a structured API to WebDriver BiDi's flat API. In particular, bidi/core provides object-oriented semantics around WebDriver BiDi resources and automatically carries out the correct order of events in WebDriver BiDi through the use of events. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/puppeteer-core/src/bidi/core/README.md`\n- **Injected**（project_doc）：This folder contains code that is injected into every Puppeteer execution context. Each file is transpiled using esbuild into a script in src/generated which is then imported into server code. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/puppeteer-core/src/injected/README.md`\n- **Templated Artifacts**（project_doc）：These files are generated as TypeScript files in the src/generated folder. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/puppeteer-core/src/templates/README.md`\n- **third party**（project_doc）：This folder contains code that interacts with third party node modules that will be vendored with puppeteer during publishing. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/puppeteer-core/third_party/README.md`\n- **Mocha Runner**（project_doc）：Mocha Runner is a test runner on top of mocha. It uses /test/TestSuites.json and /test/TestExpectations.json files to run mocha tests in multiple configurations and interpret results. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tools/mocha-runner/README.md`\n- **Contributing**（project_doc）：First of all, thank you for your interest in Puppeteer! We'd love to accept your patches and contributions! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`website/versioned_docs/version-25.0.2/contributing.md`\n- **TestServer**（project_doc）：This test server is used internally by Puppeteer to test Puppeteer itself. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/testserver/README.md`\n- **Changelog**（project_doc）：Combined changelog for puppeteer and puppeteer-core. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CHANGELOG.md`\n- **Examples & Use cases**（project_doc）：The Puppeteer repository https://github.com/puppeteer/puppeteer/tree/main/examples includes a small number of examples maintained by the Puppeteer team. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples.md`\n- **FAQ**（project_doc）：The Chrome Browser Automation team maintains the library, but we'd love your help and expertise on the project! See our contributing guide https://pptr.dev/contributing . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/faq.md`\n- **Puppeteer**（project_doc）：! build https://github.com/puppeteer/puppeteer/actions/workflows/ci.yml/badge.svg?branch=main https://github.com/puppeteer/puppeteer/actions/workflows/ci.yml ! npm puppeteer package https://img.shields.io/npm/v/puppeteer.svg https://npmjs.org/package/puppeteer 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`\n- **Supported browsers**（project_doc）：Starting with v20.0.0 Puppeteer downloads and works with Chrome for Testing https://github.com/GoogleChromeLabs/chrome-for-testing?tab=readme-ov-file what-is-chrome-for-testing , which supports both headless and headful modes sharing the same code path in the browser. The old headless mode is now a separate program called chrome-headless-shell https://developer.chrome.com/blog/chrome-headless-shell use headless: 'sh… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/supported-browsers.md`\n- **Troubleshooting**（project_doc）：To keep this page up-to-date we largely rely on community contributions. Please send a PR if you notice something is no longer up-to-date. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/troubleshooting.md`\n- **WebDriver BiDi support**（project_doc）：WebDriver BiDi https://w3c.github.io/webdriver-bidi/ is a new cross-browser automation protocol currently under development, aiming to combine the best of both WebDriver “Classic” and CDP. WebDriver BiDi enables bi-directional communication, making it fast by default, and it comes packed with low-level control. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/webdriver-bidi.md`\n- **API Reference**（project_doc）：Accessibility ./puppeteer.accessibility.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/index.md`\n- **Accessibility class**（project_doc）：The Accessibility class provides methods for inspecting the browser's accessibility tree. The accessibility tree is used by assistive technology such as screen readers https://en.wikipedia.org/wiki/Screen reader or switches https://en.wikipedia.org/wiki/Switch access . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.accessibility.md`\n- **Accessibility.snapshot method**（project_doc）：Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.accessibility.snapshot.md`\n- **ActionOptions interface**（project_doc）：A signal to abort the locator action. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.actionoptions.md`\n- **ActionResult type**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.actionresult.md`\n- **AdapterState type**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.adapterstate.md`\n- **AddScreenParams interface**（project_doc）：WorkAreaInsets ./puppeteer.workareainsets.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.addscreenparams.md`\n- **AutofillAddressField enum**（project_doc）：Supported autofill address field names. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.autofilladdressfield.md`\n- **AutofillData type**（project_doc）：References: AutofillAddressField ./puppeteer.autofilladdressfield.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.autofilldata.md`\n- **Awaitable type**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.awaitable.md`\n- **AwaitableIterable type**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.awaitableiterable.md`\n- **AwaitablePredicate type**（project_doc）：References: Awaitable ./puppeteer.awaitable.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.awaitablepredicate.md`\n- **AwaitedLocator type**（project_doc）：References: Locator ./puppeteer.locator.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.awaitedlocator.md`\n- **BluetoothEmulation.disableEmulation method**（project_doc）：BluetoothEmulation.disableEmulation method 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.bluetoothemulation.disableemulation.md`\n- **BluetoothEmulation.emulateAdapter method**（project_doc）：BluetoothEmulation.emulateAdapter method 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.bluetoothemulation.emulateadapter.md`\n- **BluetoothEmulation interface**（project_doc）：Exposes the bluetooth emulation abilities. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.bluetoothemulation.md`\n- **BluetoothEmulation.simulatePreconnectedPeripheral method**（project_doc）：BluetoothEmulation.simulatePreconnectedPeripheral method 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.bluetoothemulation.simulatepreconnectedperipheral.md`\n- **BluetoothManufacturerData interface**（project_doc）：BluetoothManufacturerData interface 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.bluetoothmanufacturerdata.md`\n- **BoundingBox interface**（project_doc）：Extends: Point ./puppeteer.point.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.boundingbox.md`\n- **BoxModel interface**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.boxmodel.md`\n- **Browser.addScreen method**（project_doc）：Adds a new screen, returns the added screen information object ./puppeteer.screeninfo.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.addscreen.md`\n- **Browser.browserContexts method**（project_doc）：Gets a list of open browser contexts ./puppeteer.browsercontext.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.browsercontexts.md`\n- **Browser.close method**（project_doc）：Closes this browser ./puppeteer.browser.md and all associated pages ./puppeteer.page.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.close.md`\n- **Browser.cookies method**（project_doc）：Returns all cookies in the default BrowserContext ./puppeteer.browsercontext.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.cookies.md`\n- **Browser.createBrowserContext method**（project_doc）：Browser.createBrowserContext method 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.createbrowsercontext.md`\n- **Browser.defaultBrowserContext method**（project_doc）：Browser.defaultBrowserContext method 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.defaultbrowsercontext.md`\n- **Browser.deleteCookie method**（project_doc）：Removes cookies from the default BrowserContext ./puppeteer.browsercontext.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.deletecookie.md`\n- **Browser.deleteMatchingCookies method**（project_doc）：Browser.deleteMatchingCookies method 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.deletematchingcookies.md`\n- **Browser.disconnect method**（project_doc）：Disconnects Puppeteer from this browser ./puppeteer.browser.md , but leaves the process running. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.disconnect.md`\n- **Browser.extensions method**（project_doc）：Retrieves a map of all extensions installed in the browser, where the keys are extension IDs and the values are the corresponding Extension ./puppeteer.extension.md instances. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.extensions.md`\n- **Browser.getWindowBounds method**（project_doc）：Gets the specified window bounds ./puppeteer.windowbounds.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.getwindowbounds.md`\n- **Browser.installExtension method**（project_doc）：Installs an extension and returns the ID. In Chrome, this is only available if the browser was created using pipe: true and the --enable-unsafe-extension-debugging flag is set. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.installextension.md`\n- **Browser class**（project_doc）：Browser ./puppeteer.browser.md represents a browser instance that is either: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.md`\n- **Browser.newPage method**（project_doc）：Creates a new page ./puppeteer.page.md in the default browser context ./puppeteer.browser.defaultbrowsercontext.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.newpage.md`\n- **Browser.pages method**（project_doc）：Gets a list of all open pages ./puppeteer.page.md inside this Browser ./puppeteer.browser.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.pages.md`\n- **Browser.process method**（project_doc）：Gets the associated ChildProcess https://nodejs.org/api/child process.html class-childprocess . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.process.md`\n- **Browser.removeScreen method**（project_doc）：Only supported in headless mode. Fails if the primary screen id is specified. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.removescreen.md`\n- **Browser.screens method**（project_doc）：Gets a list of screen information objects ./puppeteer.screeninfo.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.screens.md`\n- **Browser.setCookie method**（project_doc）：Sets cookies in the default BrowserContext ./puppeteer.browsercontext.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.setcookie.md`\n- **Browser.setPermission method**（project_doc）：Sets the permission for a specific origin in the default BrowserContext ./puppeteer.browsercontext.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.setpermission.md`\n- **Browser.setWindowBounds method**（project_doc）：Sets the specified window bounds ./puppeteer.windowbounds.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/puppeteer.browser.setwindowbounds.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Contributing**（documentation）：First of all, thank you for your interest in Puppeteer! We'd love to accept your patches and contributions! 证据：`docs/contributing.md`\n- **Puppeteer**（documentation）：! build https://github.com/puppeteer/puppeteer/actions/workflows/ci.yml/badge.svg?branch=main https://github.com/puppeteer/puppeteer/actions/workflows/ci.yml ! npm puppeteer package https://img.shields.io/npm/v/puppeteer.svg https://npmjs.org/package/puppeteer 证据：`README.md`\n- **Dockerfile for Puppeteer**（documentation）：This directory contains files needed to containerize Puppeteer. The major problem that this is solving is the problem of providing all dependencies required to run a browser instance. 证据：`docker/README.md`\n- **Puppeteer: Examples**（documentation）：This is the official set of Puppeteer examples. For a list of curated examples and use-cases, including third-party ones, see pptr.dev/examples https://pptr.dev/examples . 证据：`examples/README.md`\n- **Puppeteer tests**（documentation）：Unit tests in Puppeteer are written using Mocha as the test runner and Expect as the assertions library. 证据：`test/README.md`\n- **Website**（documentation）：This website is built using Docusaurus 3 https://docusaurus.io/ . 证据：`website/README.md`\n- **@puppeteer/browsers**（documentation）：Manage and launch browsers/drivers from a CLI or programmatically. 证据：`packages/browsers/README.md`\n- **Puppeteer Angular Schematic**（documentation）：Adds Puppeteer-based e2e tests to your Angular project. 证据：`packages/ng-schematics/README.md`\n- **bidi/core**（documentation）：bidi/core is a low-level layer that sits above the WebDriver BiDi transport to provide a structured API to WebDriver BiDi's flat API. In particular, bidi/core provides object-oriented semantics around WebDriver BiDi resources and automatically carries out the correct order of events in WebDriver BiDi through the use of events. 证据：`packages/puppeteer-core/src/bidi/core/README.md`\n- **Injected**（documentation）：This folder contains code that is injected into every Puppeteer execution context. Each file is transpiled using esbuild into a script in src/generated which is then imported into server code. 证据：`packages/puppeteer-core/src/injected/README.md`\n- **Templated Artifacts**（documentation）：These files are generated as TypeScript files in the src/generated folder. 证据：`packages/puppeteer-core/src/templates/README.md`\n- **third party**（documentation）：This folder contains code that interacts with third party node modules that will be vendored with puppeteer during publishing. 证据：`packages/puppeteer-core/third_party/README.md`\n- **Mocha Runner**（documentation）：Mocha Runner is a test runner on top of mocha. It uses /test/TestSuites.json and /test/TestExpectations.json files to run mocha tests in multiple configurations and interpret results. 证据：`tools/mocha-runner/README.md`\n- **Package**（package_manifest）：{ \"name\": \"puppeteer-repo\", \"private\": true, \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/puppeteer/puppeteer\" }, \"type\": \"module\", \"scripts\": { \"build\": \"wireit\", \"build:tools\": \"wireit\", \"check\": \"npm run check --workspaces --if-present\", \"clean\": \"npm run clean --workspaces --if-present\", \"debug\": \"mocha --inspect-brk\", \"docs\": \"wireit\", \"doctest\": \"wireit\", \"format\": \"wireit\", \"format:eslint\": \"wireit\", \"format:expectations\": \"node tools/sort-test-expectations.mjs\", \"format:prettier\": \"prettier --write --cache . \", \"lint\": \"wireit\", \"lint:eslint\": \"wireit\", \"lint:prettier\": \"prettier --check --cache .\", \"lint:expectations\": \"node tools/sort-test-expectations.mjs --lint\", \"p… 证据：`package.json`\n- **Package**（package_manifest）：{ \"name\": \"@puppeteer-test/test\", \"version\": \"latest\", \"private\": true, \"type\": \"module\", \"scripts\": { \"build\": \"wireit\", \"clean\": \"../tools/clean.mjs\" }, \"wireit\": { \"build\": { \"command\": \"tsc -b\", \"clean\": \"if-file-deleted\", \"dependencies\": \"../packages/puppeteer:build\", \"../packages/testserver:build\" , \"files\": \"src/ \" , \"output\": \"build/ \", \"tsconfig.tsbuildinfo\" } }, \"dependencies\": { \"diff\": \"9.0.0\", \"mime\": \"4.1.0\", \"jpeg-js\": \"0.4.4\", \"pixelmatch\": \"7.1.0\", \"pngjs\": \"7.0.0\" }, \"devDependencies\": { \"@types/pngjs\": \"6.0.5\" } } 证据：`test/package.json`\n- **Package**（package_manifest）：{ \"name\": \"website\", \"version\": \"0.0.0\", \"private\": true, \"scripts\": { \"docusaurus\": \"docusaurus\", \"start\": \"docusaurus start\", \"build\": \"docusaurus build\", \"swizzle\": \"docusaurus swizzle\", \"deploy\": \"docusaurus deploy\", \"clear\": \"docusaurus clear\", \"serve\": \"docusaurus serve\", \"write-translations\": \"docusaurus write-translations\", \"write-heading-ids\": \"docusaurus write-heading-ids\", \"archive\": \"node archive.js\" }, \"dependencies\": { \"@docsearch/react\": \"4.6.3\", \"@docusaurus/core\": \"3.10.1\", \"@docusaurus/plugin-client-redirects\": \"3.10.1\", \"@docusaurus/plugin-content-docs\": \"3.10.1\", \"@docusaurus/preset-classic\": \"3.10.1\", \"@docusaurus/remark-plugin-npm2yarn\": \"3.10.1\", \"@docusaurus/theme-co… 证据：`website/package.json`\n- **Package**（package_manifest）：{ \"name\": \"puppeteer-in-browser\", \"version\": \"1.0.0\", \"description\": \"\", \"main\": \"index.js\", \"scripts\": { \"build\": \"rm -rf out && rollup -c && terser out/main.js --compress --mangle --output out/main.min.js && gzip -k --best -r -f out\" }, \"keywords\": , \"author\": \"\", \"license\": \"MIT\", \"devDependencies\": { \"@rollup/plugin-node-resolve\": \"^15.2.3\", \"rollup\": \"^4.59.0\", \"terser\": \"^5.30.4\" } } 证据：`examples/puppeteer-in-browser/package.json`\n- **Package**（package_manifest）：{ \"name\": \"puppeteer-in-extension\", \"version\": \"1.0.0\", \"description\": \"\", \"main\": \"index.js\", \"scripts\": { \"build\": \"rollup -c && cp manifest.json out/\" }, \"keywords\": , \"author\": \"\", \"license\": \"MIT\", \"devDependencies\": { \"@rollup/plugin-node-resolve\": \"^15.2.3\", \"rollup\": \"^4.59.0\" } } 证据：`examples/puppeteer-in-extension/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@puppeteer/browsers\", \"version\": \"3.0.2\", \"description\": \"Download and launch browsers\", \"scripts\": { \"build:docs\": \"wireit\", \"build\": \"wireit\", \"build:test\": \"wireit\", \"clean\": \"../../tools/clean.mjs\", \"test\": \"wireit\" }, \"type\": \"module\", \"bin\": \"lib/main-cli.js\", \"main\": \"./lib/main.js\", \"module\": \"./lib/main.js\", \"wireit\": { \"build\": { \"command\": \"tsc -b && node --experimental-strip-types ../../tools/chmod.ts 755 lib/main-cli.js\", \"files\": \"src/ / .ts\", \"tsconfig.json\" , \"clean\": \"if-file-deleted\", \"output\": \"lib/ \" }, \"build:docs\": { \"command\": \"api-extractor run --local --config \\\"./api-extractor.docs.json\\\"\", \"files\": \"api-extractor.docs.json\", \"lib/main.d.ts\", \"tsconfig.j… 证据：`packages/browsers/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@puppeteer/ng-schematics\", \"version\": \"0.8.0\", \"description\": \"Puppeteer Angular schematics\", \"type\": \"module\", \"scripts\": { \"build\": \"wireit\", \"clean\": \"../../tools/clean.mjs\", \"dev:test\": \"npm run test --watch\", \"dev\": \"npm run build --watch\", \"unit\": \"wireit\" }, \"wireit\": { \"build\": { \"command\": \"tsc -b && node tools/copySchemaFiles.mjs\", \"clean\": \"if-file-deleted\", \"files\": \"tsconfig.json\", \"tsconfig.test.json\", \"src/ \", \"test/src/ \" , \"output\": \"lib/ \", \"test/build/ \", \" .tsbuildinfo\" }, \"build:test\": { \"command\": \"tsc -b test/tsconfig.json\" }, \"unit\": { \"command\": \"node --test --test-reporter=spec \\\"test/build/ / .test.js\\\"\", \"dependencies\": \"build\", \"build:test\" } }, \"keyw… 证据：`packages/ng-schematics/package.json`\n- **Package**（package_manifest）：{ \"name\": \"puppeteer-core\", \"version\": \"25.0.2\", \"description\": \"A high-level API to control headless Chrome over the DevTools Protocol\", \"keywords\": \"puppeteer\", \"chrome\", \"headless\", \"automation\" , \"type\": \"module\", \"main\": \"./lib/puppeteer/puppeteer-core.js\", \"browser\": \"./lib/puppeteer/puppeteer-core-browser.js\", \"module\": \"./lib/puppeteer/puppeteer-core.js\", \"types\": \"./lib/types.d.ts\", \"exports\": { \".\": { \"types\": \"./lib/types.d.ts\", \"import\": \"./lib/puppeteer/puppeteer-core.js\", \"require\": \"./lib/puppeteer/puppeteer-core.js\" }, \"./internal/ \": { \"import\": \"./lib/puppeteer/ \", \"require\": \"./lib/puppeteer/ \" }, \"./ \": { \"import\": \"./ \", \"require\": \"./ \" } }, \"repository\": { \"type\": \"gi… 证据：`packages/puppeteer-core/package.json`\n- **Package**（package_manifest）：{ \"type\": \"module\" } 证据：`packages/puppeteer-core/third_party/parsel-js/package.json`\n- **Package**（package_manifest）：{ \"name\": \"puppeteer\", \"version\": \"25.0.2\", \"description\": \"A high-level API to control headless Chrome over the DevTools Protocol\", \"keywords\": \"puppeteer\", \"chrome\", \"headless\", \"automation\" , \"type\": \"module\", \"bin\": \"./lib/puppeteer/node/cli.js\", \"main\": \"./lib/puppeteer/puppeteer.js\", \"module\": \"./lib/puppeteer/puppeteer.js\", \"types\": \"./lib/types.d.ts\", \"exports\": { \".\": { \"types\": \"./lib/types.d.ts\", \"import\": \"./lib/puppeteer/puppeteer.js\", \"require\": \"./lib/puppeteer/puppeteer.js\" }, \"./internal/ \": { \"import\": \"./lib/puppeteer/ \", \"require\": \"./lib/puppeteer/ \" }, \"./ \": { \"import\": \"./ \", \"require\": \"./ \" } }, \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/puppeteer/pu… 证据：`packages/puppeteer/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@puppeteer-test/installation\", \"version\": \"latest\", \"type\": \"module\", \"private\": true, \"scripts\": { \"build\": \"wireit\", \"clean\": \"../../tools/clean.mjs\", \"test\": \"wireit\", \"test-ci\": \"mocha\" }, \"wireit\": { \"build\": { \"command\": \"tsc -b\", \"clean\": \"if-file-deleted\", \"dependencies\": \"build:packages\" , \"files\": \"tsconfig.json\", \"src/ \" , \"output\": \"build/ \", \"tsconfig.tsbuildinfo\" }, \"build:packages\": { \"command\": \"npm pack --quiet --workspace puppeteer --workspace puppeteer-core --workspace @puppeteer/browsers\", \"dependencies\": \"../../packages/puppeteer:build\", \"../../packages/puppeteer-core:build\", \"../../packages/browsers:build\", \"../../packages/testserver:build\" , \"files\": , \"out… 证据：`test/installation/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@puppeteer/docgen\", \"version\": \"0.1.0\", \"type\": \"module\", \"private\": true, \"main\": \"./lib/docgen.js\", \"description\": \"Documentation generator for Puppeteer\", \"license\": \"Apache-2.0\", \"scripts\": { \"build\": \"wireit\", \"clean\": \"../clean.mjs\" }, \"wireit\": { \"build\": { \"command\": \"tsc -b\", \"clean\": \"if-file-deleted\", \"files\": \"src/ \" , \"output\": \"lib/ \", \"tsconfig.tsbuildinfo\" } }, \"devDependencies\": { \"@microsoft/api-documenter\": \"7.30.5\", \"@microsoft/api-extractor-model\": \"7.33.8\", \"@microsoft/tsdoc\": \"0.16.0\", \"@rushstack/node-core-library\": \"5.22.0\" } } 证据：`tools/docgen/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@puppeteer/doctest\", \"version\": \"0.1.0\", \"type\": \"module\", \"private\": true, \"bin\": \"./bin/doctest.js\", \"description\": \"Tests JSDoc @example code within a file.\", \"license\": \"Apache-2.0\", \"scripts\": { \"build\": \"wireit\", \"clean\": \"../clean.mjs\" }, \"wireit\": { \"build\": { \"command\": \"tsc -b && node --experimental-strip-types ../../tools/chmod.ts 755 ./bin/doctest.js\", \"clean\": \"if-file-deleted\", \"files\": \"src/ \" , \"output\": \"bin/ \", \"tsconfig.tsbuildinfo\" } }, \"devDependencies\": { \"@swc/core\": \"1.15.33\", \"@types/doctrine\": \"0.0.9\", \"@types/source-map-support\": \"0.5.10\", \"@types/yargs\": \"17.0.33\", \"acorn\": \"8.16.0\", \"doctrine\": \"3.0.0\", \"glob\": \"13.0.6\", \"package-directory\": \"8.2.0\",… 证据：`tools/doctest/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@puppeteer/eslint\", \"version\": \"0.1.0\", \"private\": true, \"type\": \"module\", \"main\": \"./lib/plugin.js\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/puppeteer/puppeteer/tree/main/tools/eslint\" }, \"scripts\": { \"build\": \"wireit\", \"prepare\": \"wireit\" }, \"wireit\": { \"build\": { \"command\": \"tsc -b\", \"clean\": \"if-file-deleted\", \"files\": \"src/ \" , \"output\": \"lib/ \", \"tsconfig.tsbuildinfo\" }, \"prepare\": { \"dependencies\": \"build\" } }, \"author\": \"The Chromium Authors\", \"license\": \"Apache-2.0\", \"devDependencies\": { \"@prettier/sync\": \"0.6.1\", \"@typescript-eslint/utils\": \"8.26.1\" } } 证据：`tools/eslint/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@puppeteer/mocha-runner\", \"version\": \"0.1.0\", \"type\": \"module\", \"private\": true, \"bin\": \"./bin/mocha-runner.js\", \"description\": \"Mocha runner for Puppeteer\", \"license\": \"Apache-2.0\", \"scripts\": { \"build\": \"wireit\", \"test\": \"wireit\", \"clean\": \"../clean.mjs\" }, \"wireit\": { \"build\": { \"command\": \"tsc -b && node --experimental-strip-types ../../tools/chmod.ts 755 ./bin/mocha-runner.js\", \"clean\": \"if-file-deleted\", \"files\": \"src/ \" , \"output\": \"bin/ \", \"tsconfig.tsbuildinfo\" , \"dependencies\": \"../../packages/puppeteer-core:build\" }, \"test\": { \"command\": \"c8 node ./bin/test.js\", \"dependencies\": \"build\" } }, \"devDependencies\": { \"@types/yargs\": \"17.0.33\", \"c8\": \"11.0.0\", \"glob\": \"13.0.6… 证据：`tools/mocha-runner/package.json`\n- **Contributing**（documentation）：First of all, thank you for your interest in Puppeteer! We'd love to accept your patches and contributions! 证据：`website/versioned_docs/version-25.0.2/contributing.md`\n- **TestServer**（documentation）：This test server is used internally by Puppeteer to test Puppeteer itself. 证据：`packages/testserver/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@pptr/testserver\", \"version\": \"0.6.1\", \"description\": \"testing server\", \"type\": \"module\", \"main\": \"lib/index.js\", \"scripts\": { \"build\": \"wireit\", \"clean\": \"../../tools/clean.mjs\" }, \"wireit\": { \"build\": { \"command\": \"tsc -b\", \"clean\": \"if-file-deleted\", \"files\": \"src/ \" , \"output\": \"lib/ \", \"tsconfig.tsbuildinfo\" } }, \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/puppeteer/puppeteer/tree/main/packages/testserver\" }, \"author\": \"The Chromium Authors\", \"license\": \"Apache-2.0\", \"dependencies\": { \"mime\": \"4.1.0\", \"ws\": \"8.20.0\" }, \"devDependencies\": { \"@types/ws\": \"8.18.1\" } } 证据：`packages/testserver/package.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 https://www.apache.org/licenses/ 证据：`LICENSE`\n- **Changelog**（documentation）：Combined changelog for puppeteer and puppeteer-core. 证据：`docs/CHANGELOG.md`\n- **Examples & Use cases**（documentation）：The Puppeteer repository https://github.com/puppeteer/puppeteer/tree/main/examples includes a small number of examples maintained by the Puppeteer team. 证据：`docs/examples.md`\n- **FAQ**（documentation）：The Chrome Browser Automation team maintains the library, but we'd love your help and expertise on the project! See our contributing guide https://pptr.dev/contributing . 证据：`docs/faq.md`\n- **Puppeteer**（documentation）：! build https://github.com/puppeteer/puppeteer/actions/workflows/ci.yml/badge.svg?branch=main https://github.com/puppeteer/puppeteer/actions/workflows/ci.yml ! npm puppeteer package https://img.shields.io/npm/v/puppeteer.svg https://npmjs.org/package/puppeteer 证据：`docs/index.md`\n- **Supported browsers**（documentation）：Starting with v20.0.0 Puppeteer downloads and works with Chrome for Testing https://github.com/GoogleChromeLabs/chrome-for-testing?tab=readme-ov-file what-is-chrome-for-testing , which supports both headless and headful modes sharing the same code path in the browser. The old headless mode is now a separate program called chrome-headless-shell https://developer.chrome.com/blog/chrome-headless-shell use headless: 'shell' with Puppeteer . 证据：`docs/supported-browsers.md`\n- **Troubleshooting**（documentation）：To keep this page up-to-date we largely rely on community contributions. Please send a PR if you notice something is no longer up-to-date. 证据：`docs/troubleshooting.md`\n- **WebDriver BiDi support**（documentation）：WebDriver BiDi https://w3c.github.io/webdriver-bidi/ is a new cross-browser automation protocol currently under development, aiming to combine the best of both WebDriver “Classic” and CDP. WebDriver BiDi enables bi-directional communication, making it fast by default, and it comes packed with low-level control. 证据：`docs/webdriver-bidi.md`\n- **API Reference**（documentation）：Accessibility ./puppeteer.accessibility.md 证据：`docs/api/index.md`\n- **Accessibility class**（documentation）：The Accessibility class provides methods for inspecting the browser's accessibility tree. The accessibility tree is used by assistive technology such as screen readers https://en.wikipedia.org/wiki/Screen reader or switches https://en.wikipedia.org/wiki/Switch access . 证据：`docs/api/puppeteer.accessibility.md`\n- **Accessibility.snapshot method**（documentation）：Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page. 证据：`docs/api/puppeteer.accessibility.snapshot.md`\n- **ActionOptions interface**（documentation）：A signal to abort the locator action. 证据：`docs/api/puppeteer.actionoptions.md`\n- **ActionResult type**（documentation）：--- sidebar label: ActionResult --- ActionResult type Signature 证据：`docs/api/puppeteer.actionresult.md`\n- **AdapterState type**（documentation）：--- sidebar label: AdapterState --- AdapterState type Emulated bluetooth adapter state. Signature 证据：`docs/api/puppeteer.adapterstate.md`\n- **AddScreenParams interface**（documentation）：WorkAreaInsets ./puppeteer.workareainsets.md 证据：`docs/api/puppeteer.addscreenparams.md`\n- **AutofillAddressField enum**（documentation）：Supported autofill address field names. 证据：`docs/api/puppeteer.autofilladdressfield.md`\n- **AutofillData type**（documentation）：References: AutofillAddressField ./puppeteer.autofilladdressfield.md 证据：`docs/api/puppeteer.autofilldata.md`\n- **Awaitable type**（documentation）：--- sidebar label: Awaitable --- Awaitable type Signature 证据：`docs/api/puppeteer.awaitable.md`\n- **AwaitableIterable type**（documentation）：--- sidebar label: AwaitableIterable --- AwaitableIterable type Signature 证据：`docs/api/puppeteer.awaitableiterable.md`\n- **AwaitablePredicate type**（documentation）：References: Awaitable ./puppeteer.awaitable.md 证据：`docs/api/puppeteer.awaitablepredicate.md`\n- **AwaitedLocator type**（documentation）：References: Locator ./puppeteer.locator.md 证据：`docs/api/puppeteer.awaitedlocator.md`\n- **BluetoothEmulation.disableEmulation method**（documentation）：BluetoothEmulation.disableEmulation method 证据：`docs/api/puppeteer.bluetoothemulation.disableemulation.md`\n- **BluetoothEmulation.emulateAdapter method**（documentation）：BluetoothEmulation.emulateAdapter method 证据：`docs/api/puppeteer.bluetoothemulation.emulateadapter.md`\n- **BluetoothEmulation interface**（documentation）：Exposes the bluetooth emulation abilities. 证据：`docs/api/puppeteer.bluetoothemulation.md`\n- **BluetoothEmulation.simulatePreconnectedPeripheral method**（documentation）：BluetoothEmulation.simulatePreconnectedPeripheral method 证据：`docs/api/puppeteer.bluetoothemulation.simulatepreconnectedperipheral.md`\n- **BluetoothManufacturerData interface**（documentation）：BluetoothManufacturerData interface 证据：`docs/api/puppeteer.bluetoothmanufacturerdata.md`\n- **BoundingBox interface**（documentation）：Extends: Point ./puppeteer.point.md 证据：`docs/api/puppeteer.boundingbox.md`\n- **BoxModel interface**（documentation）：--- sidebar label: BoxModel --- BoxModel interface Signature Properties Property Modifiers Type Description Default border Quad ./puppeteer.quad.md content Quad ./puppeteer.quad.md height number margin Quad ./puppeteer.quad.md padding Quad ./puppeteer.quad.md width number 证据：`docs/api/puppeteer.boxmodel.md`\n- **Browser.addScreen method**（documentation）：Adds a new screen, returns the added screen information object ./puppeteer.screeninfo.md . 证据：`docs/api/puppeteer.browser.addscreen.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/contributing.md`, `README.md`, `docker/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/contributing.md`, `README.md`, `docker/README.md`\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- **Getting Started**：importance `high`\n - source_paths: README.md, packages/puppeteer/package.json, packages/puppeteer/install.mjs, docs/guides/getting-started.md\n- **System Architecture**：importance `high`\n - source_paths: packages/puppeteer-core/src/index.ts, packages/puppeteer-core/src/api/api.ts, packages/puppeteer-core/src/cdp/cdp.ts, packages/puppeteer-core/src/bidi/bidi.ts\n- **Package Structure**：importance `medium`\n - source_paths: packages/puppeteer-core/package.json, packages/puppeteer-core/src/puppeteer-core.ts, packages/puppeteer-core/src/puppeteer-core-browser.ts, packages/browsers/src/main.ts, packages/ng-schematics/package.json\n- **Protocol Implementations**：importance `medium`\n - source_paths: packages/puppeteer-core/src/cdp/Connection.ts, packages/puppeteer-core/src/bidi/Connection.ts, packages/puppeteer-core/src/bidi/core/Connection.ts\n- **CDP Implementation**：importance `high`\n - source_paths: packages/puppeteer-core/src/cdp/Connection.ts, packages/puppeteer-core/src/cdp/Browser.ts, packages/puppeteer-core/src/cdp/Page.ts, packages/puppeteer-core/src/cdp/NetworkManager.ts, packages/puppeteer-core/src/cdp/FrameManager.ts\n- **WebDriver BiDi Implementation**：importance `medium`\n - source_paths: packages/puppeteer-core/src/bidi/Browser.ts, packages/puppeteer-core/src/bidi/core/BrowsingContext.ts, packages/puppeteer-core/src/bidi/core/Navigation.ts, packages/puppeteer-core/src/bidi/Page.ts, packages/puppeteer-core/src/bidi/Realm.ts\n- **Page API**：importance `high`\n - source_paths: packages/puppeteer-core/src/api/Page.ts, packages/puppeteer-core/src/cdp/Page.ts, packages/puppeteer-core/src/bidi/Page.ts, packages/puppeteer-core/src/api/Frame.ts, packages/puppeteer-core/src/api/JSHandle.ts\n- **Locators and Element Handles**：importance `high`\n - source_paths: packages/puppeteer-core/src/api/ElementHandle.ts, packages/puppeteer-core/src/api/locators/locators.ts, packages/puppeteer-core/src/common/AriaQueryHandler.ts, packages/puppeteer-core/src/common/CSSQueryHandler.ts, packages/puppeteer-core/src/common/CustomQueryHandler.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `3aadc38c533caa8df87f381868291ede870883e2`\n- inspected_files: `package.json`, `README.md`, `docs/contributing.md`, `docs/index.md`, `docs/troubleshooting.md`, `docs/webdriver-bidi.md`, `docs/examples.md`, `docs/faq.md`, `docs/supported-browsers.md`, `docs/CHANGELOG.md`, `docs/api/puppeteer.page.emulate.md`, `docs/api/puppeteer.locatorevents.md`, `docs/api/puppeteer.page.windowid.md`, `docs/api/puppeteer.page.evaluatehandle.md`, `docs/api/puppeteer.page.bringtofront.md`, `docs/api/puppeteer.commoneventemitter.removealllisteners.md`, `docs/api/puppeteer.quad.md`, `docs/api/puppeteer.page.setuseragent.md`, `docs/api/puppeteer.browser.setcookie.md`, `docs/api/puppeteer.permissionstate_2.md`\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: 来源证据：Chrome Canary/Firefox Nightly test results\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Chrome Canary/Firefox Nightly test results\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1aabe120a9df47a2adbd293381b50a64 | https://github.com/puppeteer/puppeteer/issues/12379 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Puppeteer v25\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Puppeteer v25\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_050f65ceff2a455da4a3538895a7538b | https://github.com/puppeteer/puppeteer/issues/14342 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[Bug]: GHSA issued a false malicious package alert for puppeteer\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: GHSA issued a false malicious package alert for puppeteer\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_55588dfbd41442fdb8a2f4f1be57e4c9 | https://github.com/puppeteer/puppeteer/issues/14986 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stderr`\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stderr`\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_9b1ef7c38ed14c41b3e4ce786adcdf26 | https://github.com/puppeteer/puppeteer/issues/14774 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：[Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 (extract-zip 2.0.1)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 (extract-zip 2.0.1)\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_5d1f448d8768460a806ab32e8d4f6997 | https://github.com/puppeteer/puppeteer/issues/14957 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：[Bug]: `setViewport` crashes on Firefox if uncaught\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: `setViewport` crashes on Firefox if uncaught\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_75bddb8a74194cf7a8978853f19db23a | https://github.com/puppeteer/puppeteer/issues/14989 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：[Bug]: chrome binary is not present when installing latest chrome\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: chrome binary is not present when installing latest chrome\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1e85cdab2b684dda8e5c83f55b8ff7b6 | https://github.com/puppeteer/puppeteer/issues/14988 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：[Feature]: Make proxy-agent dependency optional\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Make proxy-agent dependency optional\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_195c51e4a5e84edda14a2a79b456821c | https://github.com/puppeteer/puppeteer/issues/13775 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：browsers: v3.0.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：browsers: v3.0.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_bf2d83568c54447fbfd3047d24be0c48 | https://github.com/puppeteer/puppeteer/releases/tag/browsers-v3.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：browsers: v3.0.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：browsers: v3.0.2\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_c9f08632e7ee4e9485d27b864a21e462 | https://github.com/puppeteer/puppeteer/releases/tag/browsers-v3.0.2 | 来源类型 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项目：puppeteer/puppeteer\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 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Chrome Canary/Firefox Nightly test results（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Puppeteer v25（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]: GHSA issued a false malicious package alert for puppeteer（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stderr`（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 (extract-zip 2.0.1)（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/puppeteer/puppeteer 项目说明书\n\n生成时间：2026-05-16 05:21:34 UTC\n\n## 目录\n\n- [Getting Started](#getting-started)\n- [System Architecture](#architecture)\n- [Package Structure](#packages)\n- [Protocol Implementations](#protocols)\n- [CDP Implementation](#cdp-implementation)\n- [WebDriver BiDi Implementation](#bidi-implementation)\n- [Page API](#page-api)\n- [Locators and Element Handles](#locators)\n- [Input Handling](#input-handling)\n- [Browser Launching](#browser-launch)\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/puppeteer/puppeteer/blob/main/README.md)\n- [packages/browsers/README.md](https://github.com/puppeteer/puppeteer/blob/main/packages/browsers/README.md)\n- [docker/README.md](https://github.com/puppeteer/puppeteer/blob/main/docker/README.md)\n- [website/README.md](https://github.com/puppeteer/puppeteer/blob/main/website/README.md)\n- [packages/puppeteer-core/src/common/Debug.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/Debug.ts)\n \n\n# Getting Started\n\n## Overview\n\nPuppeteer is a Node.js library that provides a high-level API to control Chrome, Firefox, or other browsers via the DevTools Protocol and WebDriver BiDi. It enables developers to automate browser tasks programmatically, including web scraping, page interactions, performance monitoring, and automated testing.\n\nThis guide covers the essential steps to install, configure, and run your first Puppeteer script.\n\n## Installation\n\n### Prerequisites\n\n| Requirement | Details |\n|-------------|---------|\n| Node.js | Compatible version specified in `package.json` `engines` field |\n| Package Manager | npm, yarn, or pnpm |\n| System Dependencies | OS-specific tools (see below) |\n\n### System Requirements by Browser\n\n**For Firefox downloads:**\n- Linux builds: `xz` and `bzip2` utilities required for `.tar.gz` and `.tar.bz2` archives\n- MacOS builds: `hdiutil` required for `.dmg` archives\n\n**For Chrome downloads:**\n- Linux/MacOS: `unzip`\n- Windows: `tar.exe`\n\n### Installing Puppeteer\n\nThere are two primary packages available:\n\n```bash\n# Full package - downloads compatible Chrome during installation\nnpm i puppeteer\n\n# Core package - library only, without downloading Chrome\nnpm i puppeteer-core\n```\n\nWhen installing `puppeteer`, the installation script (`install.mjs`) automatically downloads a compatible Chrome binary for your platform. The `puppeteer-core` package is designed for scenarios where you already have a browser installation or want to use a custom browser path.\n\n### Using Alternative Package Managers\n\nPuppeteer supports installation via different package managers:\n\n```bash\n# Using npm\nnpm i puppeteer\n\n# Using yarn\nyarn add puppeteer\n\n# Using pnpm\npnpm add puppeteer\n```\n\n## Quick Start Example\n\nThe following example demonstrates a complete workflow: launching a browser, navigating to a page, interacting with elements, and extracting data.\n\n```typescript\nimport puppeteer from 'puppeteer';\n// Or import puppeteer from 'puppeteer-core';\n\n// Launch the browser and open a new blank page\nconst browser = await puppeteer.launch();\nconst page = await browser.newPage();\n\n// Navigate the page to a URL\nawait page.goto('https://developer.chrome.com/');\n\n// Set the screen size\nawait page.setViewport({width: 1080, height: 1024});\n\n// Open the search menu using the keyboard\nawait page.keyboard.press('/');\n\n// Type into search box using accessible input name\nawait page.locator('::-p-aria(Search)').fill('automate beyond recorder');\n\n// Wait and click on first result\nawait page.locator('.devsite-result-item-link').click();\n\n// Locate the full title with a unique string\nconst textSelector = await page\n .locator('::-p-text(Customize and automate)')\n .waitHandle();\nconst fullTitle = await textSelector?.evaluate(el => el.textContent);\n\n// Print the full title\nconsole.log('The title of this blog post is \"%s\".', fullTitle);\n\nawait browser.close();\n```\n\n资料来源：[README.md:1-40]()\n\n## Browser Launch Configuration\n\n### Basic Launch Options\n\nThe `puppeteer.launch()` method accepts a configuration object:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `headless` | `boolean \\| 'new'` | `true` | Run browser in headless mode |\n| `executablePath` | `string` | auto-detected | Path to browser executable |\n| `args` | `string[]` | `[]` | Additional CLI arguments |\n| `protocolTimeout` | `number` | `30000` | Protocol timeout in ms |\n\n### Common Launch Arguments\n\n```typescript\nconst browser = await puppeteer.launch({\n headless: false,\n args: [\n '--no-sandbox', // Required for some container environments\n '--disable-setuid-sandbox',\n '--disable-dev-shm-usage'\n ]\n});\n```\n\n## Core Concepts\n\n### Page Navigation\n\nThe `page.goto()` method navigates to a specified URL:\n\n```typescript\nawait page.goto('https://example.com', {\n waitUntil: 'networkidle2' // Wait until network is idle\n});\n```\n\n### Viewport Configuration\n\nControl the visible area of the page:\n\n```typescript\nawait page.setViewport({\n width: 1920,\n height: 1080,\n deviceScaleFactor: 2 // For high-DPI screenshots\n});\n```\n\n### Locators\n\nPuppeteer provides a locator-based API for waiting and interacting with elements:\n\n| Selector Type | Example | Description |\n|---------------|---------|-------------|\n| CSS | `'div.class-name'` | Standard CSS selector |\n| Text | `'::-p-text(Content)'` | Match by visible text |\n| ARIA | `'::-p-aria(Role)'` | Accessible ARIA selector |\n| XPath | `'::-p-xpath(//div)'` | XPath expression |\n| Shadow DOM | Combined selectors | Query across shadow roots |\n\n资料来源：[packages/puppeteer-core/src/api/locators/locators.ts:1-50]()\n\n### Evaluating JavaScript in Page Context\n\nExecute code within the browser environment:\n\n```typescript\n// Simple evaluation\nconst title = await page.evaluate(() => document.title);\n\n// With arguments\nconst links = await page.evaluate(\n (maxCount) => {\n return Array.from(document.querySelectorAll('a'))\n .slice(0, maxCount)\n .map(a => a.href);\n },\n 10 // maxCount argument\n);\n\n// Handle evaluation for complex objects\nconst handle = await page.evaluateHandle(() => document.body);\n```\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1-60]()\n\n### Exposing Functions to the Page\n\nExpose Node.js functions to be called from browser context:\n\n```typescript\nimport fs from 'node:fs';\n\nawait page.exposeFunction('readfile', async filePath => {\n return new Promise((resolve, reject) => {\n fs.readFile(filePath, 'utf8', (err, text) => {\n if (err) reject(err);\n else resolve(text);\n });\n });\n});\n\n// Now callable from page context\nawait page.evaluate(async () => {\n const content = await window.readfile('/etc/hosts');\n console.log(content);\n});\n```\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1-35]()\n\n## Workflow Diagram\n\n```mermaid\ngraph TD\n A[Start] --> B[Install Puppeteer]\n B --> C[puppeteer.launch]\n C --> D[Create Page]\n D --> E[Configure Viewport]\n E --> F[Navigate to URL]\n F --> G{Interact with Page}\n G -->|Click| H[Locate Element]\n G -->|Type| I[Fill Input]\n G -->|Extract| J[Evaluate JavaScript]\n H --> K[Perform Action]\n I --> K\n J --> L[Extract Data]\n K --> M{More Actions?}\n M -->|Yes| G\n M -->|No| N[Close Browser]\n L --> N\n```\n\n## Media Emulation\n\n### Emulate Media Types\n\nTest how pages render under different media conditions:\n\n```typescript\nawait page.emulateMediaType('print');\n\n// Now matchMedia queries return print styles\nawait page.evaluate(() => matchMedia('print').matches); // true\n\n// Reset to default\nawait page.emulateMediaType(null);\n```\n\n### Emulate CSS Media Features\n\n```typescript\nawait page.emulateMediaFeatures([\n {name: 'prefers-color-scheme', value: 'dark'},\n {name: 'prefers-color-scheme', value: 'light'}\n]);\n```\n\n### CPU Throttling\n\nEmulate slow devices for performance testing:\n\n```typescript\n// 2x slowdown\nawait page.emulateCPUThrottling(2);\n\n// Disable throttling\nawait page.emulateCPUThrottling(null);\n```\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1-30]()\n\n## Browser Management CLI\n\nThe `@puppeteer/browsers` package provides CLI tools for managing browser installations:\n\n```bash\n# List installed browsers\nnpx @puppeteer/browsers list\n\n# Clear all installed browsers\nnpx @puppeteer/browsers clear\n\n# Install specific versions\nnpx @puppeteer/browsers install chrome@stable\nnpx @puppeteer/browsers install chromedriver@116\n\n# Install specific milestone\nnpx @puppeteer/browsers install chrome@117\n```\n\n资料来源：[packages/browsers/README.md:1-50]()\n\n## Docker Usage\n\nPuppeteer can be containerized for CI/CD environments:\n\n### Building the Image\n\n```bash\ndocker build -t puppeteer-chrome-linux .\n```\n\n### Running with Docker\n\n```bash\ndocker run -i --init --rm \\\n --cap-add=SYS_ADMIN \\\n --name puppeteer-chrome \\\n puppeteer-chrome-linux \\\n node -e \"`cat test/smoke-test.js`\"\n```\n\n**Note:** The `--cap-add=SYS_ADMIN` capability enables Chrome sandbox for enhanced security. Alternatively, start with `--no-sandbox` flag.\n\n资料来源：[docker/README.md:1-30]()\n\n## Debugging\n\nEnable debug logging to troubleshoot issues:\n\n```javascript\n// Enable specific channel\nwindow.__PUPPETEER_DEBUG='Page';\n\n// Enable all channels\nwindow.__PUPPETEER_DEBUG='*';\n\n// Enable pattern matching\nwindow.__PUPPETEER_DEBUG='foo*'; // Matches 'foo', 'foobar', etc.\n```\n\nIn Node.js environment:\n\n```typescript\nimport {debug} from './common/Debug.js';\n\nconst log = debug('Page');\nlog('new page created');\n// Output: \"Page: new page created\"\n```\n\n资料来源：[packages/puppeteer-core/src/common/Debug.ts:1-50]()\n\n## MCP Integration\n\nPuppeteer supports the Model Context Protocol for AI-assisted browser automation:\n\n### Installation\n\n```bash\nnpm install chrome-devtools-mcp\n```\n\n### WebMCP Support\n\nPuppeteer also includes experimental support for the WebMCP API, enabling AI agents to interact with browser automation:\n\n资料来源：[README.md:1-25]()\n\n## Next Steps\n\n| Topic | Description |\n|-------|-------------|\n| [Locators](https://pptr.dev/guides/locators) | Advanced element location strategies |\n| [Selectors](https://pptr.dev/guides/selectors) | CSS, text, ARIA, and XPath selectors |\n| [Page Interactions](https://pptr.dev/guides/page-interactions) | Clicking, typing, scrolling |\n| [BiDi Protocol](https://pptr.dev/guides/bi-di) | WebDriver BiDi support |\n| [Chrome Extensions](https://pptr.dev/guides/chrome-extensions) | Extension automation |\n| [API Reference](https://pptr.dev/api) | Complete API documentation |\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Package Structure](#packages), [CDP Implementation](#cdp-implementation), [WebDriver BiDi Implementation](#bidi-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/index.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/index.ts)\n- [packages/puppeteer-core/src/api/api.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/api.ts)\n- [packages/puppeteer-core/src/cdp/cdp.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/cdp.ts)\n- [packages/puppeteer-core/src/bidi/bidi.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/bidi.ts)\n- [packages/puppeteer-core/src/api/Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)\n- [packages/puppeteer-core/src/cdp/ExecutionContext.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/ExecutionContext.ts)\n- [packages/puppeteer-core/src/bidi/Realm.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Realm.ts)\n- [packages/puppeteer-core/src/api/locators/locators.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/locators/locators.ts)\n \n\n# System Architecture\n\nPuppeteer is a high-level API that provides a programmatic interface for controlling Chrome/Chromium browsers. The system architecture is designed to abstract browser automation complexities while supporting multiple protocol backends.\n\n## Architecture Overview\n\nPuppeteer uses a dual-protocol architecture that supports both Chrome DevTools Protocol (CDP) and WebDriver BiDi (BiDirectional) protocols. This design enables flexibility in browser automation while maintaining a consistent high-level API for users.\n\n```mermaid\ngraph TD\n subgraph \"User Layer\"\n User[\"User Code\"]\n end\n \n subgraph \"Public API Layer\"\n Puppeteer[\"puppeteer/puppeteer-core\"]\n Page[\"Page API\"]\n Browser[\"Browser API\"]\n end\n \n subgraph \"Protocol Abstraction Layer\"\n CDP[\"CDP Implementation\"]\n BiDi[\"BiDi Implementation\"]\n end\n \n subgraph \"Protocol Communication\"\n CDP_Protocol[\"Chrome DevTools Protocol\"]\n WebDriver_BiDi[\"WebDriver BiDi\"]\n end\n \n subgraph \"Browser Layer\"\n Chrome[\"Chrome/Chromium\"]\n Firefox[\"Firefox\"]\n end\n \n User --> Puppeteer\n Puppeteer --> Page\n Puppeteer --> Browser\n Page --> CDP\n Page --> BiDi\n CDP --> CDP_Protocol\n BiDi --> WebDriver_BiDi\n CDP_Protocol --> Chrome\n WebDriver_BiDi --> Chrome\n WebDriver_BiDi --> Firefox\n```\n\n## Core Entry Points\n\nThe main entry point for Puppeteer is defined in `index.ts`, which exports all public APIs and types. The system provides two primary packages:\n\n| Package | Purpose | Browser Download |\n|---------|---------|------------------|\n| `puppeteer` | Full package with bundled Chrome | Yes (automatic) |\n| `puppeteer-core` | Library-only, no browser download | No |\n\n资料来源：[packages/puppeteer-core/src/index.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/index.ts)\n\n## Protocol Implementations\n\n### Chrome DevTools Protocol (CDP)\n\nCDP is the native Chrome debugging protocol. The CDP implementation provides direct access to Chrome's debugging features through the `CDPSession` interface.\n\n**Key Components:**\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `CDPPuppeteer` | `cdp.ts` | Main entry point for CDP-based browser control |\n| `CDPExecutionContext` | `ExecutionContext.ts` | Executes JavaScript in page context |\n| `CDPBrowserContext` | `cdp.ts` | Manages browser contexts via CDP |\n| `CDPPage` | `cdp.ts` | Page implementation using CDP |\n\n资料来源：[packages/puppeteer-core/src/cdp/cdp.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/cdp.ts)\n\n**CDP Execution Flow:**\n\n```mermaid\nsequenceDiagram\n participant User as User Code\n participant Page as CDP Page\n participant Context as CDP ExecutionContext\n participant Client as CDPSession\n participant Chrome as Chrome Browser\n \n User->>Page: evaluate(pageFunction)\n Page->>Context: evaluate(pageFunction)\n Context->>Client: send(Runtime.evaluate)\n Client->>Chrome: Runtime.evaluate\n Chrome-->>Client: result\n Client-->>Context: result\n Context-->>Page: HandleFor\n Page-->>User: Awaited>\n```\n\nThe CDP implementation evaluates page functions by stringifying them and sending them via `Runtime.evaluate` or `Runtime.callFunctionOn` CDP commands. The source URL comment is injected for better debugging support.\n\n资料来源：[packages/puppeteer-core/src/cdp/ExecutionContext.ts:1-50](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/ExecutionContext.ts)\n\n### WebDriver BiDi Protocol\n\nWebDriver BiDi is a cross-browser protocol specification that provides a standardized bidirectional communication interface.\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `BiDiPuppeteer` | `bidi.ts` | Main entry point for BiDi-based browser control |\n| `Realm` | `Realm.ts` | BiDi execution environment |\n| `BiDiBrowserContext` | `bidi.ts` | Manages browser contexts via BiDi |\n| `BiDiPage` | `bidi.ts` | Page implementation using BiDi |\n\n资料来源：[packages/puppeteer-core/src/bidi/bidi.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/bidi.ts)\n\n**BiDi Realm Architecture:**\n\nThe `Realm` class provides the execution context for BiDi-based browser automation. It includes a lazy-loaded `puppeteerUtil` that handles internal Puppeteer operations:\n\n```typescript\nclass Realm {\n internalPuppeteerUtil?: Promise>;\n \n get puppeteerUtil(): Promise> {\n // Lazy initialization with caching\n }\n \n async evaluateHandle(pageFunction, ...args): Promise>;\n async evaluate(pageFunction, ...args): Promise>;\n}\n```\n\n资料来源：[packages/puppeteer-core/src/bidi/Realm.ts:1-60](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Realm.ts)\n\n## Abstract API Layer\n\nThe API layer defines abstract interfaces that both protocol implementations must fulfill.\n\n### Page Abstraction\n\nThe `Page` class is the central abstraction for browser tabs/pages:\n\n```mermaid\nclassDiagram\n class Page {\n <>\n +exposeFunction(name, pptrFunction)\n +$$eval(selector, pageFunction)\n +emulateMediaType(type)\n +emulateCPUThrottling(factor)\n +locator(selector) Locator\n -_isDragging: boolean\n -_timeoutSettings: TimeoutSettings\n }\n \n class CDPPage {\n +exposeFunction(name, pptrFunction)\n +$$eval(selector, pageFunction)\n }\n \n class BiDiPage {\n +exposeFunction(name, pptrFunction)\n +$$eval(selector, pageFunction)\n }\n \n Page <|-- CDPPage\n Page <|-- BiDiPage\n```\n\nKey Page features:\n\n| Feature | Description | Source |\n|---------|-------------|--------|\n| `exposeFunction` | Exposes a function to the page's JavaScript context | [Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts) |\n| `$$eval` | Evaluates a function on matching elements | [Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts) |\n| `emulateMediaType` | Emulates CSS media type | [Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts) |\n| `emulateCPUThrottling` | Simulates slow CPUs | [Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts) |\n\n## Locator System\n\nThe Locator API provides a modern, promise-based approach to element finding with automatic retry logic.\n\n```mermaid\ngraph TD\n Locator[\"Locator\"]\n FunctionLocator[\"FunctionLocator\"]\n DelegatedLocator[\"DelegatedLocator\"]\n Page[\"Page\"]\n Frame[\"Frame\"]\n \n Page --> Locator\n Frame --> Locator\n Locator <|-- FunctionLocator\n Locator <|-- DelegatedLocator\n DelegatedLocator --> Locator\n \n FunctionLocator: \"_func: () => Awaitable\"\n DelegatedLocator: \"#delegate: Locator\"\n```\n\n**Locator Types:**\n\n| Type | Purpose | Key Methods |\n|------|---------|-------------|\n| `Locator` | Base locator class | `wait()`, `map()`, `filter()` |\n| `FunctionLocator` | Locates elements using a predicate function | Uses `waitForFunction` internally |\n| `DelegatedLocator` | Wraps another locator with transformation | Delegates to another locator |\n\n资料来源：[packages/puppeteer-core/src/api/locators/locators.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/locators/locators.ts)\n\n## Event System\n\nPuppeteer uses an event-driven architecture based on `EventEmitter`:\n\n```mermaid\ngraph LR\n Page[\"Page (EventEmitter)\"]\n Request[\"Request Event\"]\n Response[\"Response Event\"]\n Console[\"Console Event\"]\n \n Page --> |emit| Request\n Page --> |emit| Response\n Page --> |emit| Console\n \n User1[\"page.on('request', handler)\"]\n User2[\"page.on('response', handler)\"]\n User3[\"page.on('console', handler)\"]\n \n Request --> User1\n Response --> User2\n Console --> User3\n```\n\nThe `Page` class extends `EventEmitter` and emits events documented in the `PageEvent` enum:\n\n```typescript\npage.once('load', () => console.log('Page loaded!'));\npage.on('request', logRequest);\npage.off('request', logRequest);\n```\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1-100](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)\n\n## Lazy Evaluation (LazyArg)\n\nThe `LazyArg` system enables deferred argument evaluation within page context:\n\n```mermaid\ngraph TD\n User[\"User Code\"]\n Lazy[\"LazyArg.create(callback)\"]\n Context[\"PuppeteerUtilWrapper\"]\n Eval[\"evaluate()\"]\n \n User --> Lazy\n Lazy --> Eval\n Eval --> Context\n Context --> |get| Lazy\n```\n\n```typescript\nclass LazyArg {\n static create = (\n get: (context: PuppeteerUtilWrapper) => Promise | T\n ): T => {\n return new LazyArg(get) as unknown as T;\n };\n \n async get(context: Context): Promise {\n return await this.#get(context);\n }\n}\n```\n\n资料来源：[packages/puppeteer-core/src/common/LazyArg.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/LazyArg.ts)\n\n## Device Emulation\n\nPuppeteer provides pre-configured device profiles for emulation:\n\n```typescript\nimport {KnownDevices} from 'puppeteer';\nconst iPhone = KnownDevices['iPhone 15 Pro'];\n\nconst page = await browser.newPage();\nawait page.emulate(iPhone);\n```\n\n| Category | Devices Included |\n|----------|------------------|\n| iPhone | iPhone 4, 5, 6, 7, 8, X, 11, 12, 13, 14, 15 series |\n| iPad | Various iPad models |\n| Android | Nexus, Pixel devices |\n| Desktop | Chrome, Firefox, Safari viewports |\n\n资料来源：[packages/puppeteer-core/src/common/Device.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/Device.ts)\n\n## Debug System\n\nThe debug module provides channel-based logging:\n\n```typescript\nconst log = debug('Page');\nlog('new page created');\n// Output: \"Page: new page created\"\n```\n\n**Configuration:**\n\n| Environment Variable | Effect |\n|---------------------|--------|\n| `window.__PUPPETEER_DEBUG='*'` | Enable all logging |\n| `window.__PUPPETEER_DEBUG='foo'` | Log only 'foo' channel |\n| `window.__PUPPETEER_DEBUG='foo*'` | Log all channels starting with 'foo' |\n\n资料来源：[packages/puppeteer-core/src/common/Debug.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/Debug.ts)\n\n## Architecture Summary\n\n```mermaid\ngraph TD\n subgraph \"User Applications\"\n Scripts[\"Automation Scripts\"]\n Tests[\"Test Frameworks\"]\n Scrapers[\"Web Scrapers\"]\n end\n \n subgraph \"puppeteer/puppeteer-core\"\n API[\"Public API (Page, Browser, Frame)\"]\n Locator[\"Locator API\"]\n Event[\"Event System\"]\n end\n \n subgraph \"Protocol Adapters\"\n CDP[\"CDP Adapter\"]\n BiDi[\"BiDi Adapter\"]\n end\n \n subgraph \"Browser Runtimes\"\n Chrome[\"Chrome/Chromium\"]\n Firefox[\"Firefox\"]\n Edge[\"Edge\"]\n end\n \n Scripts --> API\n Tests --> API\n Scrapers --> API\n \n API --> Locator\n API --> Event\n \n API --> CDP\n API --> BiDi\n \n CDP --> Chrome\n CDP --> Edge\n BiDi --> Chrome\n BiDi --> Firefox\n BiDi --> Edge\n```\n\n## Key Design Principles\n\n1. **Protocol Abstraction**: Both CDP and BiDi provide equivalent functionality through a unified API\n2. **Lazy Evaluation**: Arguments are evaluated only when needed within the browser context\n3. **Event-Driven**: Asynchronous operations use observable patterns for extensibility\n4. **Device Emulation**: Built-in device profiles ensure consistent cross-device testing\n5. **Debugging Support**: Channel-based logging enables granular troubleshooting\n\n---\n\n\n\n## Package Structure\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Browser Launching](#browser-launch)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/package.json](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/package.json)\n- [packages/puppeteer-core/src/puppeteer-core.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/puppeteer-core.ts)\n- [packages/puppeteer-core/src/puppeteer-core-browser.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/puppeteer-core-browser.ts)\n- [packages/browsers/src/main.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/browsers/src/main.ts)\n- [packages/ng-schematics/package.json](https://github.com/puppeteer/puppeteer/blob/main/packages/ng-schematics/package.json)\n \n\n# Package Structure\n\nPuppeteer is a comprehensive Node.js library that provides a high-level API to control Chrome, Firefox, and other browsers via the DevTools Protocol. The project is organized as a monorepo containing multiple packages that serve distinct purposes while maintaining a cohesive architecture.\n\n## Overview\n\nThe Puppeteer repository follows a multi-package architecture designed to separate concerns between browser automation logic, browser launching utilities, and framework-specific integrations.\n\n```mermaid\ngraph TD\n A[Puppeteer Core] --> B[Browser Launchers]\n A --> C[Page API]\n A --> D[Locator API]\n B --> E[Chrome Driver]\n B --> F[Firefox Driver]\n C --> G[CDP Execution]\n D --> H[Locator Implementations]\n```\n\n## Package Organization\n\nThe repository contains the following primary packages located in the `packages/` directory:\n\n| Package | Purpose | Entry Point |\n|---------|---------|-------------|\n| `puppeteer` | Full Puppeteer distribution with bundled Chrome | Main npm package |\n| `puppeteer-core` | Core library without browser binaries | `src/puppeteer-core.ts` |\n| `@puppeteer/browsers` | Browser management CLI and API | `packages/browsers/src/main.ts` |\n| `ng-schematics` | Angular schematics for Puppeteer | Angular integration |\n\n### puppeteer-core\n\nThe `puppeteer-core` package serves as the foundation for all browser automation functionality. It provides the complete API surface for launching browsers, creating pages, and executing automation tasks.\n\n**Location:** `packages/puppeteer-core/`\n\n**Key Characteristics:**\n\n- Does not download browser binaries during installation\n- Compatible with any browser implementation that supports DevTools Protocol\n- Requires explicit `executablePath` configuration when not using bundled browsers\n\n**Source Files:**\n\n| File | Purpose |\n|------|---------|\n| `src/puppeteer-core.ts` | Main entry point, exports primary API |\n| `src/puppeteer-core-browser.ts` | Browser class implementation |\n| `src/api/Page.ts` | Abstract Page class definition |\n| `src/api/locators/locators.ts` | Locator implementations |\n| `src/common/Configuration.ts` | Configuration interfaces |\n| `src/cdp/ExecutionContext.ts` | CDP execution context |\n\nThe package exports key classes including `Browser`, `Page`, `Frame`, `Locator`, and various configuration types that enable programmatic browser control.\n\n### Browser Launchers (`@puppeteer/browsers`)\n\nThe `@puppeteer/browsers` package provides both a CLI interface and programmatic API for managing browser installations. It handles downloading, caching, and launching of browser binaries.\n\n**CLI Commands:**\n\n| Command | Description |\n|---------|-------------|\n| `npx @puppeteer/browsers install` | Download browser binaries |\n| `npx @puppeteer/browsers clear` | Remove installed browsers |\n| `npx @puppeteer/browsers list` | Display installed browsers |\n| `npx @puppeteer/browsers launch` | Launch a specific browser |\n\n**Supported Browsers:**\n\n- Chrome for Testing (Stable, Beta, Dev, Canary)\n- ChromeDriver (matching versions)\n- Firefox\n\n**Installation Examples:**\n\n```bash\n# Install latest stable Chrome\nnpx @puppeteer/browsers install chrome@stable\n\n# Install specific version\nnpx @puppeteer/browsers install chrome@116.0.5793.0\n\n# Install latest ChromeDriver for Canary\nnpx @puppeteer/browsers install chromedriver@canary\n```\n\n### Angular Schematics (`ng-schematics`)\n\nThe `ng-schematics` package provides Angular-specific tooling for integrating Puppeteer into Angular projects through the Angular CLI.\n\n**Location:** `packages/ng-schematics/package.json`\n\nThis package enables Angular developers to scaffold and configure Puppeteer within their applications using standard Angular CLI commands.\n\n## Module Architecture\n\n### Core API Structure\n\nThe Puppeteer Core API is organized hierarchically with clear separation between different functional areas:\n\n```mermaid\ngraph BT\n A[Browser] --> B[Page]\n A --> C[Target]\n B --> D[Frame]\n B --> E[Locator]\n D --> F[ExecutionContext]\n F --> G[JSHandle]\n```\n\n### Key Entry Points\n\nThe main entry point `packages/puppeteer-core/src/puppeteer-core.ts` exports all public APIs:\n\n- `puppeteer.launch()` - Launch a browser instance\n- `puppeteer.connect()` - Connect to an existing browser\n- `Browser` class - Represents a browser instance\n- `Page` class - Represents a single page or tab\n- `Frame` class - Represents an iframe within a page\n- `Locator` classes - Fluent locator implementations for element queries\n\nThe browser-specific entry point `packages/puppeteer-core/src/puppeteer-core-browser.ts` provides implementation details for browser lifecycle management.\n\n### Common Utilities\n\nSeveral utility modules support the core functionality:\n\n| Module | Location | Purpose |\n|--------|----------|---------|\n| `LazyArg` | `src/common/LazyArg.ts` | Deferred argument evaluation for page functions |\n| `Device` | `src/common/Device.ts` | Predefined device descriptors for emulation |\n| `Debug` | `src/common/Debug.ts` | Debug logging infrastructure |\n| `Configuration` | `src/common/Configuration.ts` | Global and per-browser configuration |\n\n### Launch Options\n\nBrowser launch behavior is configured through `LaunchOptions` interface in `packages/puppeteer-core/src/node/LaunchOptions.ts`:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `executablePath` | `string` | bundled | Path to browser executable |\n| `ignoreDefaultArgs` | `boolean \\| string[]` | `false` | Skip default arguments |\n| `enableExtensions` | `boolean \\| string[]` | - | Enable browser extensions |\n| `handleSIGINT` | `boolean` | `true` | Close on Ctrl+C |\n| `handleSIGTERM` | `boolean` | `true` | Close on SIGTERM |\n| `handleSIGHUP` | `boolean` | `true` | Close on SIGHUP |\n| `timeout` | `number` | `30000` | Startup timeout in ms |\n\n## Directory Structure\n\n```\npuppeteer/\n├── packages/\n│ ├── puppeteer-core/\n│ │ ├── src/\n│ │ │ ├── api/ # Public API definitions\n│ │ │ │ ├── Page.ts\n│ │ │ │ └── locators/\n│ │ │ ├── cdp/ # CDP-specific implementations\n│ │ │ ├── common/ # Shared utilities\n│ │ │ ├── injected/ # Injected scripts\n│ │ │ └── node/ # Node.js specific code\n│ │ └── package.json\n│ ├── browsers/\n│ │ ├── src/\n│ │ │ └── main.ts # CLI entry point\n│ │ └── README.md\n│ └── ng-schematics/\n├── examples/ # Official usage examples\n├── website/ # Documentation site\n├── docker/ # Docker configuration\n└── tools/ # Development tools\n```\n\n## Configuration System\n\n### Global Configuration\n\nConfiguration is defined through `ChromeSettings`, `FirefoxSettings`, and related interfaces in `Configuration.ts`:\n\n```typescript\ninterface ChromeSettings {\n skipDownload?: boolean;\n // URL prefix for browser downloads\n}\n```\n\n### Environment Variable Overrides\n\n| Variable | Configuration Property |\n|----------|------------------------|\n| `PUPPETEER_SKIP_DOWNLOAD` | `skipDownload` |\n| `PUPPETEER_TMP_DIR` | `temporaryDirectory` |\n| `PUPPETEER_CHROME_SKIP_DOWNLOAD` | `chrome.skipDownload` |\n| `PUPPETEER_CHROME_DOWNLOAD_BASE_URL` | `chrome.downloadBaseUrl` |\n\n## Integration Patterns\n\n### Direct Usage (puppeteer-core)\n\n```typescript\nimport puppeteer from 'puppeteer-core';\n\nconst browser = await puppeteer.launch({\n executablePath: '/path/to/browser'\n});\n```\n\n### Full Distribution (puppeteer)\n\n```typescript\nimport puppeteer from 'puppeteer';\n// Automatically downloads and uses bundled Chrome\nconst browser = await puppeteer.launch();\n```\n\n## Debug Support\n\nPuppeteer includes a debug logging system controlled via the `__PUPPETEER_DEBUG` environment variable:\n\n```bash\n# Enable all debug channels\nwindow.__PUPPETEER_DEBUG='*'\n\n# Enable specific channel\nwindow.__PUPPETEER_DEBUG='Page'\n\n# Enable channel prefix matching\nwindow.__PUPPETEER_DEBUG='Page*'\n```\n\nThe debug utility is implemented in `packages/puppeteer-core/src/common/Debug.ts`.\n\n## Browser Support Matrix\n\n| Browser | Protocol | Package Support |\n|---------|----------|----------------|\n| Chrome | CDP | Full |\n| Chromium | CDP | Full |\n| Firefox | CDP | Experimental |\n| Edge | CDP | Via Chrome compatibility |\n\n## Additional Resources\n\nThe repository also includes:\n\n- **Examples** (`examples/`): Working code samples demonstrating various Puppeteer features\n- **Website** (`website/`): Documentation site built with Docusaurus 3\n- **Docker** (`docker/`): Containerization support for browser execution\n- **ESLint Tools** (`tools/eslint/`): Custom ESLint rules for code quality\n\n## Version Compatibility\n\nPuppeteer maintains backward compatibility within major versions. The `puppeteer-core` package is guaranteed to work with any browser that implements the required DevTools Protocol capabilities, though optimal compatibility is achieved with bundled browser versions.\n\n---\n\n\n\n## Protocol Implementations\n\n### 相关页面\n\n相关主题：[CDP Implementation](#cdp-implementation), [WebDriver BiDi Implementation](#bidi-implementation)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/cdp/ExecutionContext.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/ExecutionContext.ts)\n- [packages/puppeteer-core/src/bidi/Realm.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Realm.ts)\n- [packages/puppeteer-core/src/common/ScriptInjector.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/ScriptInjector.ts)\n- [packages/puppeteer-core/src/common/LazyArg.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/LazyArg.ts)\n- [packages/puppeteer-core/src/api/Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)\n- [packages/puppeteer-core/src/bidi/core/README.md](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/core/README.md)\n \n\n# Protocol Implementations\n\nPuppeteer provides abstraction layers over two browser automation protocols: the **Chrome DevTools Protocol (CDP)** and **WebDriver BiDi**. These protocol implementations form the foundation of how Puppeteer communicates with browsers, enabling code execution, DOM manipulation, and browser control.\n\n## Architecture Overview\n\nPuppeteer's protocol layer sits between the high-level API (Page, Frame, etc.) and the underlying browser connections. The architecture uses a dual-protocol approach where both CDP and BiDi implementations share common interfaces while providing protocol-specific behaviors.\n\n```mermaid\ngraph TD\n subgraph \"High-Level API\"\n Page[Page.ts]\n Frame[Frame.ts]\n end\n \n subgraph \"Protocol Abstraction Layer\"\n ExecutionContext[ExecutionContext.ts
CDP]\n Realm[Realm.ts
BiDi]\n end\n \n subgraph \"Connection Layer\"\n CDP_Conn[CDP Connection]\n BiDi_Conn[BiDi Connection]\n end\n \n subgraph \"Browser\"\n Chrome[Chrome/Chromium]\n Firefox[Firefox]\n WebKit[WebKit]\n end\n \n Page --> ExecutionContext\n Page --> Realm\n ExecutionContext --> CDP_Conn\n Realm --> BiDi_Conn\n CDP_Conn --> Chrome\n BiDi_Conn --> Firefox\n BiDi_Conn --> WebKit\n```\n\n## Chrome DevTools Protocol (CDP) Implementation\n\nThe CDP implementation is located in `packages/puppeteer-core/src/cdp/` and provides deep integration with Chrome/Chromium browsers. CDP offers rich capabilities including precise execution context management, detailed debugging features, and direct access to browser internals.\n\n### CDP Execution Context\n\nThe `ExecutionContext` class in `packages/puppeteer-core/src/cdp/ExecutionContext.ts` handles code evaluation within browser contexts:\n\n```typescript\n// Simplified from ExecutionContext.ts\nasync evaluate(\n returnByValue: boolean,\n pageFunction: Func | string,\n ...args: Params\n): Promise>> | Awaited>> {\n const sourceUrlComment = getSourceUrlComment(\n getSourcePuppeteerURLIfAvailable(pageFunction)?.toString() ??\n PuppeteerURL.INTERNAL_URL,\n );\n\n if (isString(pageFunction)) {\n const contextId = this.#id;\n const expression = pageFunction;\n const expressionWithSourceUrl = SOURCE_URL_REGEX.test(expression)\n ? expression\n : `${expression}\\n${sourceUrlComment}\\n`;\n\n const {exceptionDetails, result: remoteObject} = await this.#client\n .send('Runtime.evaluate', {\n expression: expressionWithSourceUrl,\n contextId,\n returnByValue,\n awaitPromise: true,\n userGesture: true,\n })\n .catch(rewriteError);\n\n if (exceptionDetails) {\n throw createEvaluationError(exceptionDetails);\n }\n // ...\n }\n}\n```\n\n**资料来源：** [packages/puppeteer-core/src/cdp/ExecutionContext.ts:1-50](packages/puppeteer-core/src/cdp/ExecutionContext.ts)\n\n### CDP Connection\n\nThe CDP Connection manages the WebSocket-based communication channel to the browser's DevTools endpoint. This implementation handles message routing, callback management, and protocol event distribution.\n\n## WebDriver BiDi Implementation\n\nThe BiDi implementation follows the WebDriver BiDi specification and is organized into two layers:\n\n1. **`packages/puppeteer-core/src/bidi/`** - Puppeteer's BiDi abstractions\n2. **`packages/puppeteer-core/src/bidi/core/`** - Spec-compliant WebDriver BiDi core\n\n### BiDi Design Principles\n\nAccording to `packages/puppeteer-core/src/bidi/core/README.md`:\n\n- `bidi/core` attempts to implement WebDriver BiDi comprehensively, but minimally\n- All objects and events in WebDriver BiDi are implemented as a graph where objects are nodes and events are edges\n- The implementation always follows the spec and never Puppeteer's specific needs\n- This ensures that bugs can be precisely identified as either spec issues or Puppeteer workarounds\n\n**资料来源：** [packages/puppeteer-core/src/bidi/core/README.md:1-30](packages/puppeteer-core/src/bidi/core/README.md)\n\n### BiDi Realm\n\nThe BiDi `Realm` class in `packages/puppeteer-core/src/bidi/Realm.ts` provides the execution environment for BiDi-based evaluations:\n\n```typescript\n// Simplified from Realm.ts\nclass Realm extends EventEmitter {\n internalPuppeteerUtil?: Promise>;\n \n get puppeteerUtil(): Promise> {\n const promise = Promise.resolve() as Promise;\n scriptInjector.inject(script => {\n if (this.internalPuppeteerUtil) {\n void this.internalPuppeteerUtil.then(handle => {\n void handle.dispose();\n });\n }\n this.internalPuppeteerUtil = promise.then(() => {\n return this.evaluateHandle(script) as Promise<\n BidiJSHandle\n >;\n });\n }, !this.internalPuppeteerUtil);\n return this.internalPuppeteerUtil as Promise<\n BidiJSHandle\n >;\n }\n}\n```\n\n**资料来源：** [packages/puppeteer-core/src/bidi/Realm.ts:1-40](packages/puppeteer-core/src/bidi/Realm.ts)\n\n## Script Injection System\n\nThe `ScriptInjector` class (`packages/puppeteer-core/src/common/ScriptInjector.ts`) handles the injection of utility scripts required by both protocol implementations. It maintains a set of amendments that get applied to the injected script:\n\n```typescript\nexport class ScriptInjector {\n #updated = false;\n #amendments = new Set();\n\n append(statement: string): void {\n this.#update(() => {\n this.#amendments.add(statement);\n });\n }\n\n inject(inject: (script: string) => void, force = false): void {\n if (this.#updated || force) {\n inject(this.#get());\n }\n this.#updated = false;\n }\n\n #get(): string {\n return `(() => {\n const module = {};\n ${injectedSource}\n ${[...this.#amendments]\n .map(statement => {\n return `(${statement})(module.exports.default);`;\n })\n .join('')}\n return module.exports.default;\n })()`;\n }\n}\n\nexport const scriptInjector = new ScriptInjector();\n```\n\n**资料来源：** [packages/puppeteer-core/src/common/ScriptInjector.ts:1-50](packages/puppeteer-core/src/common/ScriptInjector.ts)\n\n## LazyArg Pattern\n\nThe `LazyArg` class provides a mechanism for lazy evaluation of arguments passed to page functions. This is essential for protocol implementations as it defers the resolution of context-dependent values:\n\n```typescript\nexport class LazyArg {\n static create = (\n get: (context: PuppeteerUtilWrapper) => Promise | T,\n ): T => {\n return new LazyArg(get) as unknown as T;\n };\n\n #get: (context: Context) => Promise | T;\n private constructor(get: (context: Context) => Promise | T) {\n this.#get = get;\n }\n\n async get(context: Context): Promise {\n return await this.#get(context);\n }\n}\n```\n\n**资料来源：** [packages/puppeteer-core/src/common/LazyArg.ts:1-30](packages/puppeteer-core/src/common/LazyArg.ts)\n\n## Protocol Selection and Configuration\n\nThe protocol implementation is selected based on browser type and configuration. The `Page` class in `packages/puppeteer-core/src/api/Page.ts` defines the abstract interface that both protocol implementations satisfy:\n\n```typescript\nexport abstract class Page extends EventEmitter {\n _isDragging = false;\n _timeoutSettings = new TimeoutSettings();\n _tabId = '';\n \n #requestHandlers = new WeakMap, Handler>();\n}\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:100-130](packages/puppeteer-core/src/api/Page.ts)\n\n## Key Differences Between Protocols\n\n| Feature | CDP | BiDi |\n|---------|-----|------|\n| **Browser Support** | Chrome, Chromium | Firefox, WebKit, Chrome |\n| **Architecture** | WebSocket-based | WebSocket + JSON commands |\n| **Spec Compliance** | Chrome-specific | Cross-browser standard |\n| **Execution Model** | Direct context switching | Realm-based isolation |\n| **Debugging** | Deep DevTools integration | Standard WebDriver interface |\n\n## Event Flow Comparison\n\n```mermaid\ngraph LR\n subgraph \"CDP Flow\"\n CDP1[Page Event] --> CDP2[Emulation Context]\n CDP2 --> CDP3[Request Handler]\n end\n \n subgraph \"BiDi Flow\"\n BiDi1[Page Event] --> BiDi2[Realm]\n BiDi2 --> BiDi3[Script Injector]\n BiDi3 --> BiDi4[BiDi Command]\n end\n```\n\n## Summary\n\nPuppeteer's protocol implementations provide a unified abstraction over CDP and WebDriver BiDi:\n\n1. **CDP Implementation** offers deep Chrome integration with precise context management\n2. **BiDi Implementation** provides cross-browser compatibility following the WebDriver BiDi specification\n3. **ScriptInjector** manages utility script injection for both protocols\n4. **LazyArg** enables lazy evaluation of protocol-dependent arguments\n5. The dual-protocol architecture allows Puppeteer to target different browsers while maintaining a consistent high-level API\n\n---\n\n\n\n## CDP Implementation\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Page API](#page-api)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/cdp/Connection.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/Connection.ts)\n- [packages/puppeteer-core/src/cdp/Browser.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/Browser.ts)\n- [packages/puppeteer-core/src/cdp/Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/Page.ts)\n- [packages/puppeteer-core/src/cdp/NetworkManager.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/NetworkManager.ts)\n- [packages/puppeteer-core/src/cdp/FrameManager.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/FrameManager.ts)\n- [packages/puppeteer-core/src/cdp/CdpSession.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/CdpSession.ts)\n \n\n# CDP Implementation\n\n## Overview\n\nThe Chrome DevTools Protocol (CDP) is the core communication mechanism that enables Puppeteer to interact with Chromium-based browsers. The CDP Implementation in Puppeteer provides a comprehensive abstraction layer over the raw CDP protocol, enabling high-level browser automation operations such as page navigation, JavaScript execution, network interception, and device emulation.\n\nPuppeteer's CDP implementation is located in `packages/puppeteer-core/src/cdp/` and consists of multiple interconnected modules that handle different aspects of browser automation.\n\n资料来源：[packages/puppeteer-core/src/cdp/Connection.ts:1-50]()\n\n## Architecture\n\n### High-Level Component Architecture\n\n```mermaid\ngraph TD\n subgraph \"CDP Implementation Layer\"\n Connection[CdpConnection]\n Session[CdpSession]\n Browser[CdpBrowser]\n Page[CdpPage]\n NetworkManager[NetworkManager]\n FrameManager[FrameManager]\n end\n \n subgraph \"Core CDP Components\"\n BrowserConnector[BrowserConnector]\n Target[CDPTarget]\n Accessibility[Accessibility]\n Input[Input]\n end\n \n subgraph \"Protocol Layer\"\n ProtocolCommands[CDP Protocol Commands]\n EventEmitters[Event Emitters]\n MessageHandlers[Message Handlers]\n end\n \n Connection --> Session\n Session --> Browser\n Browser --> Page\n Browser --> NetworkManager\n Browser --> FrameManager\n Session --> Target\n Connection --> BrowserConnector\n```\n\n### Module Responsibilities\n\n| Module | Purpose | Key Responsibilities |\n|--------|---------|---------------------|\n| `Connection.ts` | WebSocket communication | Establishes/manages WebSocket connection, routes messages, handles reconnection |\n| `CdpSession.ts` | CDP session management | Creates/sends CDP commands, receives events, manages message IDs |\n| `Browser.ts` | Browser lifecycle | Manages browser process, targets, pages, contexts |\n| `Page.ts` | Page automation | Navigation, frame management, viewport, emulation |\n| `NetworkManager.ts` | Network interception | Request/response interception, authentication handling |\n| `FrameManager.ts` | Frame hierarchy | Main frame, child frames, navigation tracking |\n| `ExecutionContext.ts` | JS execution | Evaluates JavaScript, manages handles |\n\n资料来源：[packages/puppeteer-core/src/cdp/Browser.ts:1-100]()\n\n## Connection Management\n\n### WebSocket-Based Communication\n\nThe `CdpConnection` class establishes a WebSocket connection to the browser's DevTools endpoint. This is the foundational transport layer for all CDP communication.\n\n```mermaid\nsequenceDiagram\n participant Puppeteer as Puppeteer Client\n participant WS as WebSocket\n participant Browser as Chrome/Chromium\n \n Puppeteer->>WS: Connect to DevTools URL\n WS->>Puppeteer: Connection established\n Puppeteer->>Browser: CDP Command (method, params, id)\n Browser->>Puppeteer: CDP Response (id, result)\n Browser->>Puppeteer: CDP Event (method, params)\n```\n\n### Connection Lifecycle\n\nThe connection management follows a defined lifecycle:\n\n1. **Initialization**: Establish WebSocket connection to the browser's remote debugging URL\n2. **Session Creation**: Create `CdpSession` instances for different targets\n3. **Message Routing**: Route CDP commands and events between client and browser\n4. **Disconnection Handling**: Gracefully handle disconnection and cleanup\n5. **Reconnection**: Support for reconnection scenarios\n\n资料来源：[packages/puppeteer-core/src/cdp/Connection.ts:50-150]()\n\n## Session Management\n\n### CdpSession Implementation\n\nThe `CdpSession` class represents an active CDP session bound to a specific browser target. It handles:\n\n- **Command Dispatch**: Sending CDP method calls with parameters\n- **Event Subscription**: Listening for CDP events from the browser\n- **Message Correlation**: Matching responses to requests using message IDs\n- **Session Lifecycle**: Creating and disposing sessions\n\n```typescript\n// Simplified session structure\nclass CdpSession {\n #connection: CdpConnection;\n #sessionId: string;\n #messageHandlers: Map;\n \n async send(method: string, params?: object): Promise;\n on(event: string, handler: Function): void;\n off(event: string, handler: Function): void;\n detach(): Promise;\n}\n```\n\n### Message Flow\n\n```mermaid\ngraph LR\n subgraph \"Client Side\"\n CMD[CDP Command]\n RES[CDP Response]\n EVT[CDP Event]\n end\n \n subgraph \"Transport\"\n WS[WebSocket]\n end\n \n subgraph \"Browser Side\"\n CDP[CDP Runtime]\n TGT[Target]\n end\n \n CMD -->|send method| WS\n WS -->|route| CDP\n CDP -->|response id| WS\n WS -->|response| RES\n TGT -->|emit event| CDP\n CDP -->|event| WS\n WS -->|event| EVT\n```\n\n资料来源：[packages/puppeteer-core/src/cdp/CdpSession.ts:1-80]()\n\n## Browser Implementation\n\n### CdpBrowser Class\n\nThe `CdpBrowser` class provides the high-level browser interface, implementing the `Browser` interface defined in the API layer. It coordinates multiple CDP sessions and manages browser targets.\n\n```mermaid\nclassDiagram\n class CdpBrowser {\n +connection_: CdpConnection\n +browserContext_: BrowserContext\n +_targets: Map~string, CdpTarget~\n +_ignoreHTTPSErrors: boolean\n +_defaultViewport: Viewport | null\n +newPage(): Promise~CdpPage~\n +createIncognitoBrowserContext(): BrowserContext\n +disconnect(): void\n +wsEndpoint(): string\n }\n \n class CdpTarget {\n +_browserContext: BrowserContext\n +_session: CdpSession\n +_initialized: Promise~void~\n +_closeCallback: Function\n +initialize(): Promise~void~\n }\n \n CdpBrowser --> CdpTarget\n CdpTarget --> CdpSession\n```\n\n### Target Management\n\nBrowser targets represent different browsing contexts managed by Chromium:\n\n| Target Type | Description | Creation Method |\n|-------------|-------------|-----------------|\n| Browser Target | Main browser process | Auto-created on connection |\n| Page Target | Single page/tab | `Target.createTarget` |\n| Service Worker | Background script | Auto-created for SWs |\n| BrowserContext | Isolated profile | `Browser.createIncognitoContext` |\n\n资料来源：[packages/puppeteer-core/src/cdp/Browser.ts:100-250]()\n\n## Page Implementation\n\n### CdpPage Class\n\nThe `CdpPage` class extends the abstract `Page` class and implements page-specific CDP operations. It provides methods for:\n\n- **Navigation**: `goto()`, `goBack()`, `goForward()`, `reload()`\n- **Content Operations**: `setContent()`, `content()`\n- **Viewport Management**: `setViewport()`, viewport settings\n- **Frame Access**: `mainFrame()`, `frames()`, `frame()`\n- **Device Emulation**: `emulate()`, `emulateMediaType()`, `emulateTimezone()`\n\n```mermaid\ngraph TD\n subgraph \"CdpPage\"\n PageAPI[Page Interface]\n Navigation[Navigation Manager]\n Emulation[Emulation Manager]\n Screenshot[Screenshot Handler]\n end\n \n subgraph \"CDP Sessions\"\n PageSession[Page Target Session]\n FrameSession[Frame Session]\n end\n \n PageAPI --> Navigation\n PageAPI --> Emulation\n PageAPI --> Screenshot\n Navigation --> PageSession\n Emulation --> PageSession\n FrameSession --> FrameManager\n```\n\n### Page Lifecycle Events\n\n| Event | Trigger | Use Case |\n|-------|---------|----------|\n| `load` | Page load complete | Wait for full page |\n| `domcontentloaded` | DOM ready | Early interaction |\n| `networkidle` | No network for 500ms | Wait for API calls |\n| `framenavigated` | Frame navigation complete | Frame sync |\n| `request/requestfailed/response` | Network events | Intercept/modify requests |\n\n资料来源：[packages/puppeteer-core/src/cdp/Page.ts:1-150]()\n\n## Network Management\n\n### NetworkManager Class\n\nThe `NetworkManager` handles all network-related CDP events and provides the interception infrastructure for `page.setRequestInterception()`.\n\n```mermaid\ngraph TD\n subgraph \"NetworkManager\"\n RequestInterceptor[Request Interceptor]\n AuthHandler[Auth Handler]\n CacheManager[Cache Manager]\n end\n \n subgraph \"CDP Events\"\n REQ[Network.requestWillBeSent]\n RES[Network.responseReceived]\n ERR[Network.requestFailed]\n CMPL[Network.loadingFinished]\n end\n \n subgraph \"Public API\"\n Interception[setRequestInterception]\n Auth[authenticate]\n Offline[setOfflineMode]\n end\n \n REQ --> RequestInterceptor\n RequestInterceptor --> Interception\n Auth --> AuthHandler\n AuthHandler --> REQ\n```\n\n### Request Interception Flow\n\n```mermaid\nsequenceDiagram\n participant Browser as Browser\n participant NM as NetworkManager\n participant Interceptor as User Interceptor\n participant CDP as CDP Session\n \n Browser->>NM: requestWillBeSent\n NM->>Interceptor: intercept callback\n Interceptor->>NM: continue/abort/respond\n NM->>CDP: Network.continueRequest\n NM->>CDP: Network.failRequest\n NM->>CDP: Network.fulfillRequest\n```\n\n### Authentication Handler\n\nThe `NetworkManager` includes authentication handling for HTTP Basic/Digest auth:\n\n```typescript\ninterface AuthCredentials {\n username: string;\n password: string;\n}\n\nclass NetworkManager {\n #authCredentials?: AuthCredentials;\n #pendingAuthRequests: Map;\n \n setAuthCredentials(credentials: AuthCredentials): void;\n clearAuthCredentials(): void;\n}\n```\n\n资料来源：[packages/puppeteer-core/src/cdp/NetworkManager.ts:1-200]()\n\n## Frame Management\n\n### FrameManager Class\n\nThe `FrameManager` maintains the frame hierarchy and tracks frame lifecycle events. It handles:\n\n- **Frame Tree Construction**: Building and maintaining the document frame hierarchy\n- **Navigation Tracking**: Tracking frame-level navigation events\n- **Detached Frame Cleanup**: Cleaning up frames when their documents unload\n- **Frame Communication**: Managing frame-specific CDP sessions\n\n```mermaid\ngraph TD\n subgraph \"FrameManager\"\n FT[Frame Tree]\n EH[Event Handler]\n NC[Navigation Checker]\n end\n \n subgraph \"Frame Types\"\n MF[Main Frame]\n IF[iframe]\n SF[Shadow Frame]\n end\n \n FT --> MF\n FT --> IF\n FT --> SF\n EH -->|events| FT\n NC -->|nav events| FT\n```\n\n### Frame Hierarchy\n\n| Frame Type | CDP Target | Session | Characteristics |\n|------------|------------|---------|-----------------|\n| Main Frame | Page target | Primary session | Top-level document |\n| Subframe | Auto-created | Linked to parent | Cross-origin isolation |\n| Worker | ServiceWorker target | Separate session | No DOM access |\n\n资料来源：[packages/puppeteer-core/src/cdp/FrameManager.ts:1-180]()\n\n## Execution Context\n\n### CdpExecutionContext\n\nThe execution context in CDP is the JavaScript execution environment within a frame. The `ExecutionContext` class provides:\n\n- **JavaScript Evaluation**: `evaluate()` and `evaluateHandle()` methods\n- **Handle Management**: Creating and managing JSHandle instances\n- **Remote Object Conversion**: Converting CDP RemoteObjects to JSHandles\n\n```mermaid\ngraph LR\n subgraph \"User Code\"\n FN[Function/Expression]\n end\n \n subgraph \"Puppeteer\"\n EVAL[evaluate]\n LAZY[LazyArg]\n HANDLE[JsHandle]\n end\n \n subgraph \"CDP\"\n RTE[Runtime.evaluate]\n CALL[Runtime.callFunctionOn]\n RO[RemoteObject]\n end\n \n FN --> EVAL\n EVAL --> RTE\n EVAL --> CALL\n CALL --> LAZY\n RTE --> RO\n CALL --> RO\n RO --> HANDLE\n```\n\n### Source URL Handling\n\nPuppeteer injects source URL comments into evaluated code for better debugging:\n\n```typescript\nconst SOURCE_URL_COMMENT = '//# sourceURL=__puppeteer_evaluation_script__';\n```\n\nThis enables:\n- Proper stack traces in console errors\n- Source map resolution in DevTools\n- Better debugging experience for evaluated code\n\n资料来源：[packages/puppeteer-core/src/cdp/ExecutionContext.ts:30-120]()\n\n## Key CDP Methods Used\n\n### Browser-Level Methods\n\n| Method | Category | Purpose |\n|--------|----------|---------|\n| `Target.createTarget` | Target | Create new page/tab |\n| `Target.attachToTarget` | Target | Attach to existing target |\n| `Browser.close` | Browser | Close browser |\n| `Browser.getVersion` | Browser | Get browser info |\n\n### Page-Level Methods\n\n| Method | Category | Purpose |\n|--------|----------|---------|\n| `Page.navigate` | Navigation | Navigate to URL |\n| `Page.setDocumentContent` | Content | Set HTML content |\n| `Page.captureScreenshot` | Screenshot | Take screenshot |\n| `Page.setViewport` | Emulation | Set viewport dimensions |\n\n### Network Methods\n\n| Method | Category | Purpose |\n|--------|----------|---------|\n| `Network.setRequestInterception` | Interception | Enable request interception |\n| `Network.continueRequest` | Interception | Continue intercepted request |\n| `Network.fulfillRequest` | Interception | Respond with custom data |\n| `Network.getResponseBody` | Response | Get response body |\n\n### Runtime Methods\n\n| Method | Category | Purpose |\n|--------|----------|---------|\n| `Runtime.evaluate` | Evaluation | Execute expression |\n| `Runtime.callFunctionOn` | Evaluation | Call function on object |\n| `Runtime.queryObjects` | Inspection | Query JS objects |\n\n资料来源：[packages/puppeteer-core/src/cdp/Page.ts:200-350]()\n\n## Event Flow Architecture\n\n```mermaid\ngraph TD\n subgraph \"Browser Events\"\n NE[Navigation Event]\n RE[Resource Event]\n EE[Execution Event]\n end\n \n subgraph \"CDP Events\"\n CDP_NE[Page.frameNavigated]\n CDP_RE[Network.requestWillBeSent]\n CDP_EE[Runtime.executionContextCreated]\n end\n \n subgraph \"Puppeteer Events\"\n P_E[page.on Event]\n CB[Event Callback]\n end\n \n NE -->|triggers| CDP_NE\n RE -->|triggers| CDP_RE\n EE -->|triggers| CDP_EE\n CDP_NE -->|emitted| P_E\n CDP_RE -->|emitted| P_E\n CDP_EE -->|emitted| P_E\n P_E -->|invokes| CB\n```\n\n## Error Handling\n\n### Error Rewriting\n\nPuppeteer rewrites CDP errors to provide more meaningful error messages:\n\n```typescript\nfunction rewriteError(error: Error, message: string): never {\n throw new Error(`${message}: ${error.message}`);\n}\n```\n\n### Evaluation Errors\n\nJavaScript evaluation errors are converted to `Error` instances with detailed information:\n\n```typescript\nfunction createEvaluationError(exceptionDetails: ExceptionDetails): Error {\n const error = new Error();\n error.name = exceptionDetails.exception?.className ?? 'Error';\n error.message = exceptionDetails.exception?.description \n ?? exceptionDetails.text;\n return error;\n}\n```\n\n资料来源：[packages/puppeteer-core/src/cdp/ExecutionContext.ts:60-90]()\n\n## Configuration Options\n\n### Launch Options Related to CDP\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `executablePath` | `string` | bundled browser | Path to browser executable |\n| `channel` | `ChromeReleaseChannel` | auto | Chrome update channel |\n| `browser` | `SupportedBrowser` | chrome | Browser to use |\n| `timeout` | `number` | 30000 | Browser launch timeout |\n| `protocolTimeout` | `number` | undefined | CDP protocol timeout |\n\n### Browser Configuration\n\n| Setting | Environment Variable | Description |\n|---------|---------------------|-------------|\n| `defaultBrowser` | `PUPPETEER_DEFAULT_BROWSER` | Default browser to use |\n| `temporaryDirectory` | `PUPPETEER_TMP_DIR` | Temp directory for downloads |\n| `skipDownload` | `PUPPETEER_SKIP_DOWNLOAD` | Skip browser download |\n| `logLevel` | `PUPPETEER_LOG_LEVEL` | Logging level |\n\n资料来源：[packages/puppeteer-core/src/node/LaunchOptions.ts:1-100]()\n\n## See Also\n\n- [Puppeteer Core API Documentation](https://pptr.dev/api/)\n- [Chrome DevTools Protocol Documentation](https://chromedevtools.github.io/devtools-protocol/)\n- [Page Implementation](./Page.md)\n- [Browser Implementation](./Browser.md)\n\n---\n\n\n\n## WebDriver BiDi Implementation\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Protocol Implementations](#protocols)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/node/BrowserLauncher.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/node/BrowserLauncher.ts)\n- [packages/puppeteer-core/src/bidi/core/README.md](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/core/README.md)\n- [packages/puppeteer-core/src/bidi/Target.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/Target.ts)\n- [packages/puppeteer-core/src/bidi/util.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/bidi/util.ts)\n- [packages/puppeteer-core/src/common/ConnectOptions.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/ConnectOptions.ts)\n \n\n# WebDriver BiDi Implementation\n\n## Overview\n\nWebDriver BiDi (Bidirectional Protocol) is a W3C-standardized protocol that enables bidirectional communication between browser automation tools and web browsers. Puppeteer's WebDriver BiDi implementation provides a modern, cross-browser automation interface built on the WebDriver protocol specification.\n\nThe implementation exists as a first-class protocol option alongside CDP (Chrome DevTools Protocol), with deep integration into Puppeteer's core architecture.\n\n## Architecture Principles\n\nThe `bidi/core` module follows specific architectural guidelines that distinguish it from higher-level Puppeteer abstractions:\n\n| Principle | Description |\n|-----------|-------------|\n| **Spec Compliance** | `bidi/core` always follows the WebDriver BiDi specification, never Puppeteer's needs |\n| **No Workarounds** | Spec deviations are never masked; instead, workarounds belong in upper layers |\n| **Comprehensive Minimalism** | All required nodes and edges in the protocol graph are implemented fully |\n| **Event Integrity** | Events are never composed or duplicated; navigation flows must follow the correct event sequence |\n\n资料来源：[packages/puppeteer-core/src/bidi/core/README.md]()\n\n### Event Flow Integrity\n\nA critical principle is that events must follow proper WebDriver BiDi semantics. For navigation events:\n\n- Fragment navigations must emit events through the complete chain: `fragment navigation → navigation → browsing context`\n- Direct emission to browsing context without intermediate events is prohibited\n- This ensures that consumers receive semantically correct event sequences matching the protocol specification\n\n## Protocol Connection Architecture\n\n```mermaid\ngraph TD\n A[Puppeteer Application] --> B[BrowserLauncher]\n B --> C{PUPPETEER_WEBDRIVER_BIDI_ONLY}\n C -->|true| D[BiDi Only Mode]\n C -->|false| E[CDP + BiDi Hybrid Mode]\n D --> F[BiDi.connectBidiOverCdp]\n E --> G[CDP Connection]\n G --> H[BiDi.connectBidiOverCdp]\n F --> I[BidiBrowser Instance]\n H --> I\n```\n\n### BiDi over CDP Bridge\n\nWhen using WebDriver BiDi with browsers that primarily support CDP (like Chrome), Puppeteer establishes a CDP connection and wraps it with BiDi protocol support:\n\n```typescript\nconst bidiOnly = process.env['PUPPETEER_WEBDRIVER_BIDI_ONLY'] === 'true';\nconst BiDi = await import('../bidi/bidi.js');\nconst bidiConnection = await BiDi.connectBidiOverCdp(cdpConnection);\nreturn await BiDi.BidiBrowser.create({\n connection: bidiConnection,\n // Do not provide CDP connection to Browser if BiDi-only mode is enabled\n cdpConnection: bidiOnly ? undefined : cdpConnection,\n closeCallback,\n process: browserProcess.nodeProcess,\n defaultViewport: opts.defaultViewport,\n acceptInsecureCerts: opts.acceptInsecureCerts,\n networkEnabled: opts.networkEnabled,\n issuesEnabled: opts.issuesEnabled,\n});\n```\n\n资料来源：[packages/puppeteer-core/src/node/BrowserLauncher.ts:1-28]()\n\n### WebDriver BiDi Capabilities\n\nWhen connecting with WebDriver BiDi protocol, capabilities can be specified:\n\n```typescript\ninterface SupportedWebDriverCapabilities {\n webDriverBiDi?: {\n // BiDi-specific capabilities passed to session.new\n };\n}\n```\n\nThe `capabilities` option allows passing WebDriver BiDi capabilities during connection establishment:\n\n> Headers to use for the web socket connection. Only works in the Node.js environment.\n>\n> WebDriver BiDi capabilities passed to BiDi `session.new`. Only works for `protocol=\"webDriverBiDi\"` and `Puppeteer.connect`.\n\n资料来源：[packages/puppeteer-core/src/common/ConnectOptions.ts:1-50]()\n\n## Target Model\n\nPuppeteer's BiDi implementation extends the abstract `Target` class with browser-specific target types:\n\n### BidiBrowserTarget\n\nRepresents the browser-level target in WebDriver BiDi context:\n\n```typescript\nexport class BidiBrowserTarget extends Target {\n #browser: BidiBrowser;\n\n override type(): TargetType {\n return TargetType.BROWSER;\n }\n\n override browser(): BidiBrowser {\n return this.#browser;\n }\n\n override browserContext(): BidiBrowserContext {\n return this.#browser.defaultBrowserContext();\n }\n}\n```\n\nUnsupported operations throw `UnsupportedOperation`:\n\n- `asPage()` - Not supported at browser target level\n- `createCDPSession()` - CDP sessions not available in BiDi-only targets\n- `opener()` - Not applicable to browser targets\n\n资料来源：[packages/puppeteer-core/src/bidi/Target.ts:1-50]()\n\n### BidiPageTarget\n\nRepresents individual page targets within the browser context. Extends the base `Target` with page-specific behavior through composition with `BidiPage`.\n\n## Console Message Handling\n\nWebDriver BiDi requires conversion between BiDi console event levels and Puppeteer's internal representation:\n\n```typescript\nexport function convertConsoleMessageLevel(method: string): ConsoleMessageType {\n switch (method) {\n case 'group':\n return 'startGroup';\n case 'groupCollapsed':\n return 'startGroupCollapsed';\n case 'groupEnd':\n return 'endGroup';\n default:\n return method as ConsoleMessageType;\n }\n}\n```\n\nThis mapping ensures that BiDi's console event semantics align with Puppeteer's console message types.\n\n资料来源：[packages/puppeteer-core/src/bidi/util.ts:1-40]()\n\n### Stack Trace Extraction\n\nConsole messages can include stack trace information extracted from BiDi protocol responses:\n\n```typescript\nexport function getStackTraceLocations(\n stackTrace?: Bidi.Script.StackTrace,\n): ConsoleMessageLocation[] {\n const stackTraceLocations: ConsoleMessageLocation[] = [];\n if (stackTrace) {\n for (const callFrame of stackTrace.callFrames) {\n stackTraceLocations.push({\n url: callFrame.url,\n lineNumber: callFrame.lineNumber,\n columnNumber: callFrame.columnNumber,\n });\n }\n }\n return stackTraceLocations;\n}\n```\n\n## Firefox-Specific Configuration\n\nFirefox has native WebDriver BiDi support and provides specific preferences configuration:\n\n| Preference | Value | Purpose |\n|------------|-------|---------|\n| `fission.bfcacheInParent` | `undefined` | BFCache behavior |\n| `fission.webContentIsolationStrategy` | `0` | Process isolation strategy |\n\n### Blocklist and Allowlist\n\nFirefox's WebDriver BiDi implementation supports blocklist/allowlist configuration through preferences. However, these are **only supported with the CDP protocol**:\n\n```typescript\nit('should reject blocklist for the default Firefox WebDriver BiDi protocol', async () => {\n const launcher = new FirefoxLauncher({} as PuppeteerNode);\n\n await expect(\n launcher.launch({\n blocklist: ['https://example.com/*'],\n }),\n ).rejects.toThrow(\n 'blocklist and allowlist are only supported with the CDP protocol',\n );\n});\n```\n\n资料来源：[packages/puppeteer-core/src/node/FirefoxLauncher.test.ts:1-40]()\n\n## Core Components\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| Browser | `bidi/Browser.ts` | Main browser instance management |\n| BrowsingContext | `bidi/core/BrowsingContext.ts` | Tab/window context handling |\n| Navigation | `bidi/core/Navigation.ts` | Navigation event handling |\n| Page | `bidi/Page.ts` | Page-level operations |\n| Realm | `bidi/Realm.ts` | JavaScript execution contexts |\n\n## Protocol Modes\n\nPuppeteer supports three protocol configuration modes:\n\n```mermaid\ngraph LR\n A[Default] --> B[CDP + BiDi]\n C[PUPPETEER_WEBDRIVER_BIDI_ONLY=true] --> D[BiDi Only]\n E[protocol=webDriverBiDi] --> D\n```\n\n| Mode | CDP Available | BiDi Available | Use Case |\n|------|---------------|----------------|----------|\n| Default | Yes | Yes (via bridge) | Chrome automation |\n| BiDi Only | No | Yes | Pure spec compliance |\n| WebDriver BiDi | No | Native | Firefox automation |\n\n## Summary\n\nThe WebDriver BiDi implementation in Puppeteer provides:\n\n1. **Standards-compliant protocol support** through the `bidi/core` module following W3C WebDriver BiDi specification\n2. **Flexible connection architecture** supporting CDP bridge and native BiDi modes\n3. **Browser-agnostic target model** with proper abstraction layers\n4. **Event integrity** ensuring semantically correct event sequences per protocol spec\n5. **Cross-browser compatibility** with native Firefox BiDi support and Chrome CDP bridging\n\n---\n\n\n\n## Page API\n\n### 相关页面\n\n相关主题：[Locators and Element Handles](#locators), [Input Handling](#input-handling)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/api/Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)\n- [packages/puppeteer-core/src/cdp/ExecutionContext.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/ExecutionContext.ts)\n- [packages/puppeteer-core/src/api/locators/locators.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/locators/locators.ts)\n- [packages/puppeteer-core/src/common/Device.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/Device.ts)\n- [packages/puppeteer-core/src/common/LazyArg.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/LazyArg.ts)\n \n\n# Page API\n\nThe Page API is the core interface in Puppeteer for interacting with browser pages and tabs. It provides methods for navigating pages, interacting with DOM elements, evaluating JavaScript, handling events, and emulating various browser environments and device characteristics.\n\n## Overview\n\nThe Page API serves as the primary abstraction for browser page operations in Puppeteer. A Page instance represents a single tab or window within a browser instance, offering a comprehensive set of methods to control page behavior, extract data, and automate interactions.\n\n```mermaid\ngraph TD\n A[Browser Instance] --> B[Page API]\n B --> C[Navigation]\n B --> D[DOM Interaction]\n B --> E[JavaScript Evaluation]\n B --> F[Event Handling]\n B --> G[Device Emulation]\n \n C --> C1[goto, back, forward, reload]\n D --> D1[$, $$, locator]\n E --> E1[evaluate, exposeFunction]\n F --> F1[on, once, off]\n G --> G1[emulateMediaType, emulate]\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:1-50]()\n\n## Core Architecture\n\n### Class Hierarchy\n\nThe Page class extends EventEmitter and serves as an abstract base class implemented by both CDP (Chrome DevTools Protocol) and WebDriver BiDi backends:\n\n```mermaid\nclassDiagram\n class EventEmitter~PageEvents~ {\n <>\n }\n class Page {\n <>\n +_isDragging: boolean\n +_timeoutSettings: TimeoutSettings\n +_tabId: string\n +exposeFunction()\n +metrics()\n +captureHeapSnapshot()\n +emulateMediaType()\n +emulateCPUThrottling()\n +emulateMediaFeatures()\n }\n class CDPPage {\n +implementation\n }\n class BiDiPage {\n +implementation\n }\n \n EventEmitter <|-- Page\n Page <|-- CDPPage\n Page <|-- BiDiPage\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:200-230]()\n\n### Internal State Management\n\nThe Page class maintains several internal state properties:\n\n| Property | Type | Purpose |\n|----------|------|---------|\n| `_isDragging` | `boolean` | Tracks drag state for mouse interactions |\n| `_timeoutSettings` | `TimeoutSettings` | Manages timeout configuration for operations |\n| `_tabId` | `string` | Browser-specific tab identifier |\n| `#inflight$` | `ReplaySubject` | Tracks in-flight request count |\n| `#requestHandlers` | `WeakMap` | Maps request handlers for monitoring |\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:200-215]()\n\n## Navigation API\n\n### Basic Navigation Methods\n\nThe Page API provides fundamental navigation methods for controlling page loading:\n\n- `goto(url)` - Navigate to a URL\n- `reload()` - Reload the current page\n- `goBack()` - Navigate to the previous page in history\n- `goForward()` - Navigate to the next page in history\n- `close()` - Close the page\n\n### URL Property\n\nThe `url()` method returns the current page URL as a shortcut for `page.mainFrame().url()`:\n\n```typescript\nconst currentUrl = await page.url();\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:280-295]()\n\n## JavaScript Evaluation\n\n### evaluate Method\n\nThe `evaluate` method executes JavaScript code in the page context. It supports both string expressions and function-based evaluation.\n\n**资料来源：** [packages/puppeteer-core/src/cdp/ExecutionContext.ts:30-60]()\n\n### evaluate with Parameters\n\nWhen passing arguments to page functions, Puppeteer serializes them using a specialized mechanism:\n\n```typescript\nawait page.evaluate(\n (text, inputValue) => {\n document.querySelector(text).value = inputValue;\n },\n 'selector',\n 'value'\n);\n```\n\n**资料来源：** [packages/puppeteer-core/src/cdp/ExecutionContext.ts:45-55]()\n\n### Source URL Comment Injection\n\nPuppeteer automatically injects source URL comments into evaluated code to enable better debugging and source map support:\n\n```typescript\nconst sourceUrlComment = getSourceUrlComment(\n getSourcePuppeteerURLIfAvailable(pageFunction)?.toString() ??\n PuppeteerURL.INTERNAL_URL,\n);\n```\n\nThe injection follows this pattern:\n1. Check if the expression already contains a source URL\n2. If not, append the source URL comment to the expression\n3. Include this comment in the CDP `Runtime.evaluate` call\n\n**资料来源：** [packages/puppeteer-core/src/cdp/ExecutionContext.ts:35-45]()\n\n## exposeFunction API\n\nThe `exposeFunction` method allows exposing Node.js functions to the page's JavaScript context as `window[name]`:\n\n### Signature\n\n```typescript\nabstract exposeFunction(\n name: string,\n pptrFunction: Function | {default: Function}\n): Promise;\n```\n\n### Usage Example\n\n```typescript\nconst browser = await puppeteer.launch();\nconst page = await browser.newPage();\n\npage.on('console', msg => console.log(msg.text()));\nawait page.exposeFunction('readfile', async filePath => {\n return fs.readFileSync(filePath, 'utf8');\n});\n\nawait page.evaluate(async () => {\n const content = await window.readfile('/etc/hosts');\n console.log(content);\n});\n\nawait browser.close();\n```\n\n### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `name` | `string` | Name of the function on the window object |\n| `pptrFunction` | `Function \\| {default: Function}` | Callback function executed in Puppeteer's Node.js context |\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:140-175]()\n\n## Device Emulation\n\n### Emulate Media Type\n\nThe `emulateMediaType` method emulates CSS media type on the page:\n\n```typescript\nawait page.emulateMediaType('print');\nawait page.evaluate(() => matchMedia('print').matches); // true\nawait page.emulateMediaType(null); // Reset to default\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:320-345]()\n\n### Emulate Media Features\n\nThe `emulateMediaFeatures` method emulates CSS media features:\n\n```typescript\nawait page.emulateMediaFeatures([\n { name: 'prefers-color-scheme', value: 'dark' },\n]);\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:345-360]()\n\n### Known Devices\n\nPuppeteer provides a predefined set of device descriptors via `KnownDevices`:\n\n```typescript\nimport { KnownDevices } from 'puppeteer';\nconst iPhone = KnownDevices['iPhone 15 Pro'];\n\nawait page.emulate(iPhone);\n```\n\n**资料来源：** [packages/puppeteer-core/src/common/Device.ts:1-30]()\n\n## CPU Throttling\n\nThe `emulateCPUThrottling` method enables CPU throttling to simulate slow CPUs:\n\n```typescript\n// No throttling (1x speed)\nawait page.emulateCPUThrottling(1);\n\n// 2x slowdown\nawait page.emulateCPUThrottling(2);\n\n// Disable throttling\nawait page.emulateCPUThrottling(null);\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:355-360]()\n\n## Metrics API\n\nThe `metrics()` method returns performance metrics from the browser:\n\n### Returned Metrics\n\n| Metric | Description |\n|--------|-------------|\n| `Timestamp` | Monotonic timestamp when sample was taken |\n| `Documents` | Number of documents in the page |\n| `Frames` | Number of frames in the page |\n| `JSEventListeners` | Number of JavaScript event listeners |\n| `Nodes` | Number of DOM nodes |\n| `LayoutCount` | Total full or partial page layouts |\n| `RecalcStyleCount` | Total style recalculations |\n| `LayoutDuration` | Combined layout duration |\n| `RecalcStyleDuration` | Combined style recalculation duration |\n| `ScriptDuration` | Combined JavaScript execution duration |\n| `TaskDuration` | Combined browser task duration |\n| `JSHeapUsedSize` | Used JavaScript heap size |\n| `JSHeapTotalSize` | Total JavaScript heap size |\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:260-280]()\n\n## Heap Snapshot\n\nThe `captureHeapSnapshot` method captures a snapshot of the JavaScript heap:\n\n```typescript\nawait page.captureHeapSnapshot({ path: 'screenshot.png' });\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:285-290]()\n\n## Locator API\n\nThe Page API integrates with Puppeteer's Locator API for reliable element interactions:\n\n### Available Locator Methods\n\n```typescript\n// Query elements using various selector types\nconst element = page.locator('button.submit');\nconst elements = page.locator('.item');\n\n// ARIA selectors\nconst searchInput = page.locator('::-p-aria(Search)');\n\n// Text selectors\nconst title = page.locator('::-p-text(Customize and automate)');\n\n// XPath selectors\nconst para = page.locator('::-p-xpath(//p[@class=\"intro\"])');\n\n// CSS with pierce (shadow DOM)\nconst shadowElement = page.locator(':scope >>> .shadow-content');\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/locators/locators.ts:1-50]()\n\n## LazyArg System\n\nThe LazyArg system provides lazy evaluation of arguments passed to page functions:\n\n```typescript\nexport class LazyArg {\n static create = (\n get: (context: PuppeteerUtilWrapper) => Promise | T\n ): T => {\n return new LazyArg(get) as unknown as T;\n };\n\n async get(context: Context): Promise {\n return await this.#get(context);\n }\n}\n```\n\nThis allows arguments to be evaluated on-demand in the browser context, avoiding serialization issues with complex objects.\n\n**资料来源：** [packages/puppeteer-core/src/common/LazyArg.ts:1-40]()\n\n## Event Handling\n\nThe Page class extends EventEmitter and emits various events documented in the `PageEvent` enum:\n\n### Basic Event Usage\n\n```typescript\n// Listen for a single event\npage.once('load', () => console.log('Page loaded!'));\n\n// Listen for ongoing events\npage.on('request', request => {\n console.log('Request:', request.url());\n});\n\n// Unsubscribe from events\nfunction logRequest(request) {\n console.log('A request was made:', request.url());\n}\npage.on('request', logRequest);\npage.off('request', logRequest);\n```\n\n**资料来源：** [packages/puppeteer-core/src/api/Page.ts:180-200]()\n\n## Error Handling\n\n### Evaluation Errors\n\nWhen JavaScript evaluation fails, Puppeteer throws a descriptive error:\n\n```typescript\nconst { exceptionDetails, result } = await this.#client.send(\n 'Runtime.evaluate',\n {\n expression: expressionWithSourceUrl,\n contextId,\n returnByValue,\n awaitPromise: true,\n userGesture: true,\n }\n).catch(rewriteError);\n\nif (exceptionDetails) {\n throw createEvaluationError(exceptionDetails);\n}\n```\n\n**资料来源：** [packages/puppeteer-core/src/cdp/ExecutionContext.ts:50-65]()\n\n## Implementation Backends\n\n### CDP (Chrome DevTools Protocol) Backend\n\nThe CDP implementation uses Chrome's native DevTools Protocol for communication:\n\n- Located in `packages/puppeteer-core/src/cdp/Page.ts`\n- Direct protocol-level control\n- Lower-level access to browser features\n\n### WebDriver BiDi Backend\n\nThe BiDi implementation provides cross-browser compatibility:\n\n- Located in `packages/puppeteer-core/src/bidi/Page.ts`\n- Standardized WebDriver protocol\n- Broader browser support\n\n## Summary\n\nThe Page API provides a comprehensive abstraction layer for browser page automation in Puppeteer. Key capabilities include:\n\n| Category | Features |\n|----------|----------|\n| **Navigation** | URL access, goto, reload, back, forward |\n| **JavaScript** | evaluate, exposeFunction, handle serialization |\n| **Emulation** | Media types, media features, CPU throttling, device profiles |\n| **Metrics** | Performance metrics, heap snapshots |\n| **Interaction** | Locators, event handling, drag simulation |\n| **State** | Timeout settings, tab identification, request tracking |\n\nThe abstract Page class is implemented by both CDP and BiDi backends, ensuring flexibility and cross-browser compatibility while maintaining a consistent API surface for users.\n\n---\n\n\n\n## Locators and Element Handles\n\n### 相关页面\n\n相关主题：[Page API](#page-api), [Input Handling](#input-handling)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/api/ElementHandle.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/ElementHandle.ts)\n- [packages/puppeteer-core/src/api/Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)\n- [packages/puppeteer-core/src/api/Frame.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Frame.ts)\n- [packages/puppeteer-core/src/common/CSSQueryHandler.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/CSSQueryHandler.ts)\n- [packages/puppeteer-core/src/common/AriaQueryHandler.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/AriaQueryHandler.ts)\n- [packages/puppeteer-core/src/common/CustomQueryHandler.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/CustomQueryHandler.ts)\n- [packages/puppeteer-core/src/injected/PQuerySelector.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/injected/PQuerySelector.ts)\n- [tools/eslint/src/use-using.ts](https://github.com/puppeteer/puppeteer/blob/main/tools/eslint/src/use-using.ts)\n \n\n# Locators and Element Handles\n\n## Overview\n\nPuppeteer provides two complementary mechanisms for interacting with DOM elements in a browser page: **Locators** and **Element Handles**. Both serve the purpose of referencing and manipulating elements, but they differ significantly in their design philosophy, retry behavior, and use cases.\n\n- **Element Handles** provide direct, immediate references to DOM elements. They are point-in-time references that do not automatically retry if elements become stale or unavailable.\n- **Locators** are designed for reliability and resilience. They automatically retry actions until the element is in the correct state, making them ideal for modern web applications with dynamic content.\n\n资料来源：[packages/puppeteer-core/src/api/ElementHandle.ts:1-50]()\n\n```mermaid\ngraph TD\n A[User Code] --> B{Choose Strategy}\n B --> C[ElementHandle]\n B --> D[Locator]\n C --> E[Direct DOM Reference]\n C --> F[No Auto-Retry]\n D --> G[Query Strategy + Retry Logic]\n D --> H[State Awareness]\n D --> I[Action Chaining]\n```\n\n## Element Handles\n\n### Purpose and Scope\n\nElement Handles are direct references to DOM elements obtained through query methods like `page.$()` or `page.$$()`. They provide low-level access to elements but require manual management of element lifecycle.\n\n资料来源：[packages/puppeteer-core/src/api/ElementHandle.ts:40-60]()\n\n### Class Definition\n\n```typescript\nexport abstract class ElementHandle<\n ElementType extends Node = Element,\n> extends JSHandle {\n /**\n * @internal\n */\n declare [_isElementHandle]: boolean;\n\n /**\n * @internal\n * Cached isolatedHandle to prevent\n * trying to adopt it multiple times\n */\n isolatedHandle?: typeof this;\n\n /**\n * @internal\n */\n protected readonly handle;\n}\n```\n\n资料来源：[packages/puppeteer-core/src/api/ElementHandle.ts:40-58]()\n\n### Key Characteristics\n\n| Characteristic | Description |\n|----------------|-------------|\n| **Lifecycle** | Auto-disposed when frame navigates or context is destroyed |\n| **Garbage Collection** | Prevents GC while handle exists unless explicitly disposed |\n| **Type Safety** | Generic type parameter for element type (e.g., `ElementHandle`) |\n| **Usage** | Used as arguments in `Page.$eval` and `Page.evaluate` |\n\n### Query Methods\n\nElement Handles can be created using the following Page/Frame methods:\n\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `page.$(selector)` | `ElementHandle \\| null` | First element matching selector |\n| `page.$$(selector)` | `ElementHandle[]` | All elements matching selector |\n| `frame.$(selector)` | `ElementHandle \\| null` | First element in frame |\n| `frame.$$(selector)` | `ElementHandle[]` | All elements in frame |\n\n资料来源：[packages/puppeteer-core/src/api/Frame.ts:100-130]()\n\n### Memory Management with `using`\n\nPuppeteer provides an ESLint rule to enforce proper disposal of Element Handles using the `using` keyword. This ensures handles are automatically cleaned up when they go out of scope.\n\n```typescript\nimport puppeteer from 'puppeteer';\n\nconst browser = await puppeteer.launch();\nconst page = await browser.newPage();\nawait page.goto('https://example.com');\n\n// Using 'using' ensures proper cleanup\nusing element = await page.$('a');\nawait element.click();\n```\n\n资料来源：[tools/eslint/src/use-using.ts:1-50]()\n\n```typescript\nconst usingSymbols = ['ElementHandle', 'JSHandle'];\n```\n\n资料来源：[tools/eslint/src/use-using.ts:12]()\n\n## Locators\n\n### Purpose and Design Philosophy\n\nLocators are Puppeteer's recommended approach for element interaction. They encapsulate both the query strategy and retry logic, providing a robust way to handle flaky tests in modern web applications where elements may appear, disappear, or change state dynamically.\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1-100]()\n\n### Locator API\n\nLocators are created through the `locator()` method on Page or Frame:\n\n```typescript\nlocator(\n selector: Selector,\n): Locator>;\n\nlocator(func: () => Awaitable): Locator;\n```\n\n### Supported Selector Types\n\nPuppeteer supports multiple selector types that can be used with both Element Handles and Locators:\n\n| Selector Type | Syntax | Description |\n|---------------|--------|-------------|\n| CSS | `''` | Standard CSS selectors |\n| Text | `::-p-text()` | Elements containing text |\n| ARIA | `::-p-aria([name])` | Accessibility-based selection |\n| XPath | `xpath=` | XPath expressions |\n| Pierce | `>>> ` | Cross-shadow-DOM queries |\n| Custom | Custom prefix | User-defined query handlers |\n\n资料来源：[packages/puppeteer-core/src/common/CSSQueryHandler.ts]()\n\n### Query Handlers Architecture\n\nQuery handlers are the pluggable components that process different selector types.\n\n```mermaid\nclassDiagram\n class QueryHandler {\n <>\n +query(page, selector)\n +queryAll(page, selector)\n }\n class CSSQueryHandler {\n +query(page, selector)\n +queryAll(page, selector)\n }\n class AriaQueryHandler {\n +query(page, selector)\n +queryAll(page, selector)\n }\n class CustomQueryHandler {\n +query(page, selector)\n +queryAll(page, selector)\n }\n class XPathQueryHandler {\n +query(page, selector)\n +queryAll(page, selector)\n }\n \n QueryHandler <|.. CSSQueryHandler\n QueryHandler <|.. AriaQueryHandler\n QueryHandler <|.. CustomQueryHandler\n QueryHandler <|.. XPathQueryHandler\n```\n\n### CSS Query Handler\n\nThe CSS Query Handler processes standard CSS selectors and is the default handler for selectors without a prefix.\n\n```typescript\n// Internal implementation delegates to injected PQuerySelector\nexport class CSSQueryHandler extends QueryHandler {\n #pquerySelector: PQuerySelector;\n // Uses PuppeteerInjectedScript for DOM queries\n}\n```\n\n资料来源：[packages/puppeteer-core/src/common/CSSQueryHandler.ts]()\n\n### Aria Query Handler\n\nThe ARIA Query Handler enables selection based on accessibility attributes:\n\n```typescript\n// Select by role and optional name\nawait page.locator('::-p-aria(Search)').fill('query');\nawait page.locator('::-p-aria(Submit button[name])').click();\n```\n\n资料来源：[packages/puppeteer-core/src/common/AriaQueryHandler.ts]()\n\n### Custom Query Handlers\n\nPuppeteer allows registration of custom query handlers for domain-specific selectors:\n\n```typescript\npage.customQueryHandlers.set('mySelector', {\n queryOne: (self, selector) => { /* ... */ },\n queryAll: (self, selector) => { /* ... */ },\n});\n```\n\n## Comparison: Locators vs Element Handles\n\n| Aspect | Element Handles | Locators |\n|--------|-----------------|----------|\n| **Retry Behavior** | None - immediate result | Automatic retry until element ready |\n| **State Awareness** | None | Tracks element state |\n| **Flakiness Handling** | Manual | Built-in |\n| **Performance** | Faster for single operation | Slight overhead for retry logic |\n| **Use Case** | Simple scripts, single operations | Dynamic applications, tests |\n| **Stale Element Handling** | Manual detection and re-query | Automatic re-query |\n\n```mermaid\ngraph LR\n A[Action Request] --> B{Locator}\n B --> C{Element visible?}\n C -->|No| D[Wait & Retry]\n D --> C\n C -->|Yes| E[Perform Action]\n \n F[Action Request] --> G{ElementHandle}\n G --> H[Immediate Result]\n H --> I[Perform Action]\n I --> J{Still valid?}\n J -->|No| K[StaleElementReference Error]\n```\n\n## Best Practices\n\n### When to Use Locators\n\n- **Recommended** for most use cases\n- Testing modern web applications with dynamic content\n- When element availability timing is uncertain\n- Building resilient automation scripts\n\n### When to Use Element Handles\n\n- Quick scripts with predictable DOM\n- When performance is critical\n- Low-level DOM manipulation\n- Integration with other libraries expecting handles\n\n### Memory Management\n\nAlways dispose of handles to prevent memory leaks:\n\n```typescript\n// Using async disposal\nconst handle = await page.$('div');\ntry {\n // Work with handle\n} finally {\n await handle.dispose();\n}\n\n// Or use 'using' keyword where supported\nusing element = await page.$('a');\n```\n\n### ESLint Integration\n\nEnable the `use-using` rule to enforce proper handle disposal:\n\n```json\n{\n \"rules\": {\n \"@puppeteer/use-using\": \"error\"\n }\n}\n```\n\n资料来源：[tools/eslint/src/use-using.ts:20-60]()\n\n## Examples\n\n### Basic Element Handle Usage\n\n```typescript\nimport puppeteer from 'puppeteer';\n\nconst browser = await puppeteer.launch();\nconst page = await browser.newPage();\nawait page.goto('https://example.com');\n\n// Single element\nconst hrefElement = await page.$('a');\nawait hrefElement.click();\n\n// Multiple elements\nconst links = await page.$$('a');\nfor (const link of links) {\n const text = await link.evaluate(el => el.textContent);\n console.log(text);\n}\n\nawait browser.close();\n```\n\n资料来源：[packages/puppeteer-core/src/api/ElementHandle.ts:10-30]()\n\n### Locator with Action Chaining\n\n```typescript\nimport puppeteer from 'puppeteer';\n\nconst browser = await puppeteer.launch();\nconst page = await browser.newPage();\n\nawait page.goto('https://example.com');\n\n// Chain actions on locator\nawait page.locator('::-p-aria(Search)').fill('query');\nawait page.locator('.devsite-result-item-link').click();\n\n// Wait for element with locator\nconst textSelector = await page\n .locator('::-p-text(Customize and automate)')\n .waitHandle();\n\nawait browser.close();\n```\n\n### Using $$eval for Batch Operations\n\n```typescript\nconst allInputValues = await page.$$eval('input', elements =>\n elements.map(e => e.textContent),\n);\n```\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1-50]()\n\n## Architecture Summary\n\n```mermaid\ngraph TD\n subgraph \"User Layer\"\n A[page.$()]\n B[page.locator()]\n C[frame.$$()]\n end\n \n subgraph \"Query Handler Layer\"\n D[CSSQueryHandler]\n E[AriaQueryHandler]\n F[CustomQueryHandler]\n G[XPathQueryHandler]\n end\n \n subgraph \"Execution Layer\"\n H[CDP Protocol]\n I[BiDi Protocol]\n end\n \n A --> D\n B --> D\n B --> E\n C --> F\n \n D --> H\n D --> I\n E --> H\n F --> H\n \n style A fill:#e1f5fe\n style B fill:#e8f5e8\n style D fill:#fff3e0\n style E fill:#fff3e0\n```\n\n## See Also\n\n- [Page API Documentation](https://pptr.dev/api/puppeteer.page)\n- [Frame API Documentation](https://pptr.dev/api/puppeteer.frame)\n- [ElementHandle API Documentation](https://pptr.dev/api/puppeteer.elementhandle)\n- [Locator API Documentation](https://pptr.dev/api/puppeteer.locator)\n\n---\n\n\n\n## Input Handling\n\n### 相关页面\n\n相关主题：[Locators and Element Handles](#locators), [Page API](#page-api)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this documentation:\n\n- [packages/puppeteer-core/src/api/Input.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Input.ts)\n- [packages/puppeteer-core/src/common/USKeyboardLayout.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/USKeyboardLayout.ts)\n- [packages/puppeteer-core/src/api/Page.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/Page.ts)\n- [packages/puppeteer-core/src/api/ElementHandle.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/api/ElementHandle.ts)\n- [packages/puppeteer-core/src/cdp/ExecutionContext.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/cdp/ExecutionContext.ts)\n \n\n# Input Handling\n\nInput Handling in Puppeteer provides a unified API for simulating user interactions with web pages, including keyboard input, mouse operations, touch gestures, and drag-and-drop actions. The system abstracts away protocol-level differences between Chrome DevTools Protocol (CDP) and WebDriver BiDi, providing developers with a consistent interface for browser automation.\n\n## Architecture Overview\n\nPuppeteer's Input Handling system follows a layered architecture:\n\n```mermaid\ngraph TD\n A[User Code] --> B[Page API / ElementHandle API]\n B --> C[Protocol-Agnostic Input Interface]\n C --> D[CDP Implementation
packages/puppeteer-core/src/cdp/Input.ts]\n C --> E[BiDi Implementation
packages/puppeteer-core/src/bidi/Input.ts]\n D --> F[Chrome DevTools Protocol]\n E --> G[WebDriver BiDi Protocol]\n F --> H[Browser Instance]\n G --> H\n```\n\nThe system is organized around three core input interfaces defined in the abstract layer:\n\n| Interface | Purpose |\n|-----------|---------|\n| `Keyboard` | Simulates keyboard input including key presses, typing, and modifier keys |\n| `Mouse` | Controls mouse movement, clicking, and wheel scrolling |\n| `Touch` | Simulates touch-based interactions on mobile devices |\n| `DragAndDrop` | Manages drag source and drop target operations |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:1-200]()\n\n## Keyboard Input\n\n### Keyboard Interface Methods\n\nThe `Keyboard` interface provides four primary methods for simulating keyboard input:\n\n| Method | Description |\n|--------|-------------|\n| `down(key, options?)` | Presses a key down without releasing it |\n| `up(key)` | Releases a pressed key |\n| `type(text, options?)` | Types text character by character |\n| `press(key, options?)` | Combines down + up (with optional delay) |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:47-75]()\n\n### Key Input Values\n\nPuppeteer uses the `KeyInput` enum to define all supported keyboard keys. Common values include:\n\n- **Modifier Keys**: `Alt`, `Control`, `Meta`, `Shift`\n- **Arrow Keys**: `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`\n- **Function Keys**: `F1` through `F12`\n- **Special Keys**: `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `Space`\n- **Alpha-Numeric**: Standard letter and number keys (e.g., `a`, `A`, `1`)\n\n### Type vs Press\n\nThe `type()` method sends `keydown`, `keypress/input`, and `keyup` events for each character in the text. Unlike `press()`, modifier keys do not affect `type()` - holding Shift will not type uppercase characters.\n\n```typescript\nawait page.keyboard.type('Hello'); // Types instantly\nawait page.keyboard.type('World', {delay: 100}); // Types with 100ms between each key\n```\n\nThe `press()` method is a shortcut combining `down()` and `up()`. If the key is a single character with no modifiers besides Shift, a `keypress/input` event is also generated.\n\n```typescript\nawait page.keyboard.press('Enter');\nawait page.keyboard.press('Control', {delay: 100});\nawait page.keyboard.press('KeyA', {text: 'a'});\n```\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:35-75]()\n\n### Keyboard Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `delay` | `number` | Time in milliseconds between `keydown` and `keyup` (default: `0`) |\n| `text` | `string` | Forces an input event with this text |\n| `commands` | `string[]` | Browser command names for keyboard shortcuts |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:26-33]()\n\n## Mouse Input\n\n### Mouse Interface Methods\n\nThe `Mouse` interface provides precise control over cursor movement and clicking:\n\n| Method | Description |\n|--------|-------------|\n| `move(x, y, options?)` | Moves the mouse to the specified coordinates |\n| `down(options?)` | Presses the mouse button |\n| `up(options?)` | Releases the mouse button |\n| `click(x, y, options?)` | Performs a full click (down + up) at coordinates |\n| `wheel(options?)` | Scrolls the page |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:92-132]()\n\n### Mouse Click Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `button` | `MouseButton` | `'left'` | Which button to click |\n| `clickCount` | `number` | `1` | Number of clicks (for double-click) |\n| `delay` | `number` | `0` | Delay between mousedown and mouseup in ms |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:135-155]()\n\n### Mouse Move Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `steps` | `number` | `1` | Number of intermediate mouse moves for smooth transitions |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:157-170]()\n\n### Mouse Wheel Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `deltaX` | `number` | `0` | Horizontal scroll amount |\n| `deltaY` | `number` | `0` | Vertical scroll amount |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:172-187]()\n\n### Click Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Mouse as Mouse Interface\n participant Page as Page\n \n User->>Mouse: click(x, y, {button: 'left', clickCount: 2})\n Mouse->>Page: mouseMoved(x, y)\n Mouse->>Page: mousePressed(x, y, button: 'left', clickCount: 1)\n Mouse->>Page: mouseReleased(x, y, button: 'left', clickCount: 1)\n Mouse->>Page: mousePressed(x, y, button: 'left', clickCount: 2)\n Mouse->>Page: mouseReleased(x, y, button: 'left', clickCount: 2)\n```\n\n## Touch Input\n\nThe `Touch` interface simulates touch interactions for mobile device testing:\n\n| Method | Description |\n|--------|-------------|\n| `tap(x, y)` | Performs a tap at the specified coordinates |\n| `touchStart(x, y)` | Starts a touch at the coordinates |\n| `touchMove(x, y)` | Moves the touch to new coordinates |\n| `touchEnd()` | Ends the current touch sequence |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:194-210]()\n\n## Drag and Drop\n\nThe `DragAndDrop` interface handles drag interactions:\n\n| Method | Description |\n|--------|-------------|\n| `drag(source, destination)` | Drags from source to destination, returns drag data |\n| `drop(x, y, data)` | Drops data at the specified coordinates |\n\n资料来源：[packages/puppeteer-core/src/api/Input.ts:212-220]()\n\n## High-Level Element Interactions\n\nFor common use cases, Puppeteer provides convenience methods on `Page` and `ElementHandle` that handle input internally.\n\n### Page-Level Input\n\nThe `Page` class exposes input methods that operate on the main frame:\n\n```typescript\n// Type text into an element\nawait page.type('#mytextarea', 'Hello');\nawait page.type('#mytextarea', 'World', {delay: 100});\n\n// Press a special key\nawait page.keyboard.press('Enter');\nawait page.keyboard.press('ArrowDown');\n```\n\n资料来源：[packages/puppeteer-core/src/api/Page.ts:1800-1820]()\n\n### ElementHandle Input\n\n`ElementHandle` provides element-specific input methods:\n\n```typescript\nconst element = await page.$('#input-field');\n\n// Focus the element and type\nawait element.type('Hello');\n\n// Focus the element and press a key\nawait element.press('Enter');\n```\n\nBoth methods automatically focus the element before performing the input action:\n\n```typescript\nasync type(\n text: string,\n options?: Readonly,\n): Promise {\n await this.focus();\n await this.frame.page().keyboard.type(text, options);\n}\n\nasync press(\n key: KeyInput,\n options?: Readonly,\n): Promise {\n await this.focus();\n await this.frame.page().keyboard.press(key, options);\n}\n```\n\n资料来源：[packages/puppeteer-core/src/api/ElementHandle.ts:620-640]()\n\n## Implementation Strategies\n\n### CDP Implementation\n\nThe Chrome DevTools Protocol implementation translates abstract input calls into CDP commands:\n\n- `Input.dispatchMouseEvent` for mouse operations\n- `Input.dispatchKeyEvent` for keyboard operations\n- Direct touch event dispatching\n\nThe CDP implementation handles the translation of keyboard codes using US keyboard layout definitions.\n\n### BiDi Implementation\n\nThe WebDriver BiDi implementation uses the BiDi specification's `input` module:\n\n- Maps to BiDi `input.performActions` command\n- Handles serialization of input actions across the protocol wire\n\n### US Keyboard Layout\n\nThe `USKeyboardLayout` module provides key code mappings for US keyboards:\n\n```typescript\nexport const USKeyboardLayout: Map = new Map([\n ['a', 0x61],\n ['A', 0x41],\n ['b', 0x62],\n // ... additional mappings\n]);\n```\n\n资料来源：[packages/puppeteer-core/src/common/USKeyboardLayout.ts:1-100]()\n\n## Best Practices\n\n1. **Use `press()` for special keys**: Instead of `type()` for special characters, use `press()` with key names like `Enter`, `Tab`, or `Escape`.\n\n2. **Add delays for realistic simulation**: When testing UI behavior that depends on timing, use the `delay` option:\n\n ```typescript\n await page.type('#search', 'query', {delay: 100});\n ```\n\n3. **Focus elements before typing**: When using `ElementHandle` input methods, the element is automatically focused. For direct keyboard access, ensure the target is focused first.\n\n4. **Use `click()` over `down()/up()`**: The `click()` method handles the complete click lifecycle and is less error-prone.\n\n5. **Consider `Locator` API for reliability**: For improved reliability in element interactions, consider using Puppeteer's experimental [Locators API](https://pptr.dev/guides/page-interactions#locators).\n\n## Related Components\n\n| Component | Purpose |\n|-----------|---------|\n| `Page` | Exposes input methods on the main frame |\n| `ElementHandle` | Element-specific keyboard input |\n| `Frame` | Frame-level input access |\n| `Keyboard` | Low-level keyboard simulation |\n| `Mouse` | Low-level mouse control |\n| `Touch` | Touch interaction simulation |\n| `DragAndDrop` | Drag and drop operations |\n\n---\n\n\n\n## Browser Launching\n\n### 相关页面\n\n相关主题：[Package Structure](#packages)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/puppeteer-core/src/node/BrowserLauncher.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/node/BrowserLauncher.ts)\n- [packages/puppeteer-core/src/node/ChromeLauncher.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/node/ChromeLauncher.ts)\n- [packages/puppeteer-core/src/node/FirefoxLauncher.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/node/FirefoxLauncher.ts)\n- [packages/puppeteer-core/src/node/LaunchOptions.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/node/LaunchOptions.ts)\n- [packages/browsers/src/CLI.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/browsers/src/CLI.ts)\n- [packages/browsers/src/install.ts](https://github.com/puppeteer/puppeteer/blob/main/packages/browsers/src/install.ts)\n \n\n# Browser Launching\n\n## Overview\n\nBrowser launching is a core system in Puppeteer that handles the initialization and lifecycle management of browser instances. This system provides a unified interface for launching different browser types (Chrome, Firefox) while abstracting platform-specific details and managing process signals, timeouts, and executable paths.\n\nThe browser launching subsystem consists of several key components:\n\n- **BrowserLauncher**: Abstract base class defining the launching interface\n- **ChromeLauncher**: Implementation for Chrome/Chromium-based browsers\n- **FirefoxLauncher**: Implementation for Firefox\n- **@puppeteer/browsers**: Standalone package for programmatic browser management\n\n## Architecture\n\n### Class Hierarchy\n\n```mermaid\ngraph TD\n A[BrowserLauncher] --> B[ChromeLauncher]\n A --> C[FirefoxLauncher]\n D[launch.ts] --> E[Browser Process]\n F[install.ts] --> G[Browser Binaries]\n \n style A fill:#e1f5fe\n style B fill:#e8f5e8\n style C fill:#fff3e0\n```\n\n### Browser Launch Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Puppeteer\n participant BrowserLauncher\n participant BrowserProcess\n participant CDP\n \n User->>Puppeteer: puppeteer.launch(options)\n Puppeteer->>BrowserLauncher: createLauncher(options)\n BrowserLauncher->>BrowserLauncher: resolveExecutablePath()\n BrowserLauncher->>BrowserLauncher: buildArguments()\n BrowserLauncher->>BrowserProcess: spawn(executable, args)\n BrowserProcess-->>BrowserLauncher: process started\n BrowserLauncher->>BrowserLauncher: setupSignalHandlers()\n BrowserLauncher->>CDP: connect(wsEndpoint)\n CDP-->>Puppeteer: Browser instance\n User->>Puppeteer: browser operations\n User->>Puppeteer: browser.close()\n Puppeteer->>BrowserProcess: terminate()\n```\n\n## Launch Options\n\nThe `LaunchOptions` interface defines all configuration parameters available when launching a browser. These options control executable selection, argument passing, signal handling, and timeout behavior.\n\n### Core Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `executablePath` | `string` | bundled browser | Path to a specific browser executable. When using this, Puppeteer cannot guarantee compatibility. |\n| `ignoreDefaultArgs` | `boolean \\| string[]` | `false` | Controls whether default arguments are passed to the browser. Array mode filters specific args. |\n| `enableExtensions` | `boolean \\| string[]` | `false` | Enables browser extensions. String array loads extensions from paths. |\n\n### Signal Handling\n\nPuppeteer manages browser process lifecycle through POSIX signal handling:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `handleSIGINT` | `boolean` | `true` | Close browser on `Ctrl+C` (SIGINT) |\n| `handleSIGTERM` | `boolean` | `true` | Close browser on termination signal (SIGTERM) |\n| `handleSIGHUP` | `boolean` | `true` | Close browser on terminal hangup (SIGHUP) |\n\n### Timeout Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `timeout` | `number` | `30,000` (30 seconds) | Maximum time in milliseconds to wait for browser startup. Pass `0` to disable timeout. |\n\n## Browser Installation\n\n### CLI Installation\n\nThe `@puppeteer/browsers` package provides command-line tools for downloading and managing browser binaries:\n\n```bash\n# Download latest stable Chrome\nnpx @puppeteer/browsers install chrome@stable\n\n# Download specific version\nnpx @puppeteer/browsers install chrome@116.0.5793.0\n\n# Download by milestone\nnpx @puppeteer/browsers install chrome@117\n\n# Download ChromeDriver\nnpx @puppeteer/browsers install chromedriver@canary\n\n# List installed browsers\nnpx @puppeteer/browsers list\n\n# Clear all browsers\nnpx @puppeteer/browsers clear\n```\n\n### Configuration Options\n\nThe `Configuration` interface controls download behavior:\n\n| Option | Environment Variable | Default | Description |\n|--------|---------------------|---------|-------------|\n| `skipDownload` | `PUPPETEER_SKIP_DOWNLOAD` | `false` | Skip browser download during installation |\n| `temporaryDirectory` | `PUPPETEER_TMP_DIR` | `os.tmpdir()` | Directory for temporary files |\n| `logLevel` | - | `warn` | Logging level: `silent`, `error`, `warn` |\n\n### Browser-Specific Settings\n\nEach browser type supports independent configuration:\n\n| Browser | Skip Download Env Var | Download Base URL Env Var | Version Env Var |\n|---------|----------------------|---------------------------|-----------------|\n| Chrome | `PUPPETEER_CHROME_SKIP_DOWNLOAD` | `PUPPETEER_CHROME_DOWNLOAD_BASE_URL` | `PUPPETEER_CHROME_VERSION` |\n| Chrome Headless Shell | `PUPPETEER_CHROME_HEADLESS_SHELL_SKIP_DOWNLOAD` | `PUPPETEER_CHROME_HEADLESS_SHELL_DOWNLOAD_BASE_URL` | - |\n| Firefox | `PUPPETEER_FIREFOX_SKIP_DOWNLOAD` | `PUPPETEER_FIREFOX_DOWNLOAD_BASE_URL` | `PUPPETEER_FIREFOX_VERSION` |\n\n### Download Base URLs\n\n| Browser | Default URL |\n|---------|-------------|\n| Chrome | `https://storage.googleapis.com/chrome-for-testing-public` |\n| Firefox | `https://archive.mozilla.org/pub/firefox/releases` |\n\n## Chrome Launcher\n\nThe `ChromeLauncher` handles launching Chrome and Chromium-based browsers. It manages the Chrome DevTools Protocol (CDP) connection and applies Chrome-specific default arguments.\n\n### Key Responsibilities\n\n1. **Executable Resolution**: Locates the Chrome executable based on platform and configuration\n2. **Argument Construction**: Builds the complete argument list including default Chrome flags\n3. **Profile Management**: Creates temporary user data directories for isolated browser contexts\n4. **CDP Connection**: Establishes WebSocket connection to the browser's DevTools interface\n\n### Default Arguments\n\nChrome Launcher automatically includes secure defaults:\n- `--no-sandbox` (when not running as root on Linux)\n- `--disable-dev-shm-usage` (prevents crashes in Docker environments)\n- Remote debugging port selection\n\n## Firefox Launcher\n\nThe `FirefoxLauncher` provides Firefox-specific launching capabilities with support for Mozilla's remote debugging protocol.\n\n### Differences from Chrome\n\n- Uses Firefox's built-in DevTools protocol instead of CDP\n- Handles Firefox-specific argument syntax\n- Manages Firefox profile creation and cleanup\n\n## Browser Management\n\n### Programmatic Browser Management\n\nThe `@puppeteer/browsers` package allows programmatic browser control:\n\n```typescript\nimport {install, launch, clear, Browser} from '@puppeteer/browsers';\n\nasync function setupBrowser() {\n // Install browser\n const installOpts = {\n browser: Browser.CHROME,\n buildId: 'stable',\n cacheDir: './browser-cache'\n };\n \n await install(installOpts);\n \n // Launch browser\n const launchOpts = {\n executablePath: await getExecutablePath(installOpts),\n args: ['--no-sandbox']\n };\n \n const browserProcess = await launch(launchOpts);\n return browserProcess;\n}\n```\n\n### Browser Cleanup\n\nBrowsers installed by Puppeteer can be automatically cleaned up during version updates:\n\n```mermaid\ngraph TD\n A[Puppeteer Launch] --> B[Load Installed Browsers]\n B --> C{Is Browser Current?}\n C -->|Yes| D[Keep Browser]\n C -->|No| E[Uninstall Old Build]\n F[New Version Available] --> C\n```\n\nThe cleanup process:\n1. Compares installed browser versions against Puppeteer's pinned versions\n2. Identifies browsers no longer managed by current Puppeteer\n3. Removes outdated browser builds using `uninstall()` with `buildId` and `platform`\n\n## Signal Handling Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Launching: launch()\n Launching --> Running: Browser Started\n Running --> Closing: close() / SIGINT / SIGTERM / SIGHUP\n Closing --> [*]: Process Terminated\n \n Running --> Running: New Page Created\n```\n\n### Signal Handler Configuration\n\n| Signal | Default | Purpose |\n|--------|---------|---------|\n| `SIGINT` | Enabled | `Ctrl+C` interruption |\n| `SIGTERM` | Enabled | Process termination |\n| `SIGHUP` | Enabled | Terminal disconnect |\n\nDisabling signal handlers is possible but not recommended as it may leave orphaned browser processes:\n\n```typescript\nconst browser = await puppeteer.launch({\n handleSIGINT: false,\n handleSIGTERM: false,\n handleSIGHUP: false\n});\n```\n\n## Timeout Behavior\n\n```mermaid\ngraph LR\n A[launch()] --> B{timeout > 0?}\n B -->|Yes| C[Wait ms]\n B -->|No| D[No Timeout]\n C --> E{Browser Ready?}\n E -->|Yes| F[Return Browser]\n E -->|No| G[Throw Timeout Error]\n D --> F\n```\n\nTimeout of `0` disables the startup timeout entirely, useful for:\n- Debugging launch issues\n- Slow systems with many browser dependencies\n- Long initialization sequences\n\n## Best Practices\n\n1. **Always use `await browser.close()`** to properly terminate browser processes\n2. **Set reasonable timeouts** for production environments\n3. **Use bundled browsers** for guaranteed compatibility\n4. **Enable signal handlers** (default) for clean shutdowns\n5. **Use `--no-sandbox`** only when necessary for containerized environments\n\n## Related Components\n\n| Component | Purpose |\n|-----------|---------|\n| `Page` | Browser page/tab abstraction |\n| `BrowserContext` | Isolated browser sessions |\n| `HTTPRequest/HTTPResponse` | Network request handling |\n| `TimeoutSettings` | Configurable timeout management |\n\n## Source References\n\n- Launch options definition: `packages/puppeteer-core/src/node/LaunchOptions.ts:1-50`\n- Browser launcher base: `packages/puppeteer-core/src/node/BrowserLauncher.ts`\n- Chrome-specific launch: `packages/puppeteer-core/src/node/ChromeLauncher.ts`\n- Firefox-specific launch: `packages/puppeteer-core/src/node/FirefoxLauncher.ts`\n- Browser installation: `packages/browsers/src/install.ts`\n- Browser launch process: `packages/browsers/src/launch.ts`\n- CLI definitions: `packages/browsers/src/CLI.ts:1-60`\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：puppeteer/puppeteer\n\n摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Chrome Canary/Firefox Nightly test results。\n\n## 1. 安装坑 · 来源证据：Chrome Canary/Firefox Nightly test results\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Chrome Canary/Firefox Nightly test results\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1aabe120a9df47a2adbd293381b50a64 | https://github.com/puppeteer/puppeteer/issues/12379 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Puppeteer v25\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Puppeteer v25\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_050f65ceff2a455da4a3538895a7538b | https://github.com/puppeteer/puppeteer/issues/14342 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：[Bug]: GHSA issued a false malicious package alert for puppeteer\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: GHSA issued a false malicious package alert for puppeteer\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_55588dfbd41442fdb8a2f4f1be57e4c9 | https://github.com/puppeteer/puppeteer/issues/14986 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：[Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stderr`\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stderr`\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9b1ef7c38ed14c41b3e4ce786adcdf26 | https://github.com/puppeteer/puppeteer/issues/14774 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：[Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 (extract-zip 2.0.1)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 (extract-zip 2.0.1)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5d1f448d8768460a806ab32e8d4f6997 | https://github.com/puppeteer/puppeteer/issues/14957 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[Bug]: `setViewport` crashes on Firefox if uncaught\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: `setViewport` crashes on Firefox if uncaught\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_75bddb8a74194cf7a8978853f19db23a | https://github.com/puppeteer/puppeteer/issues/14989 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：[Bug]: chrome binary is not present when installing latest chrome\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: chrome binary is not present when installing latest chrome\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1e85cdab2b684dda8e5c83f55b8ff7b6 | https://github.com/puppeteer/puppeteer/issues/14988 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：[Feature]: Make proxy-agent dependency optional\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Make proxy-agent dependency optional\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_195c51e4a5e84edda14a2a79b456821c | https://github.com/puppeteer/puppeteer/issues/13775 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：browsers: v3.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：browsers: v3.0.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bf2d83568c54447fbfd3047d24be0c48 | https://github.com/puppeteer/puppeteer/releases/tag/browsers-v3.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 来源证据：browsers: v3.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：browsers: v3.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c9f08632e7ee4e9485d27b864a21e462 | https://github.com/puppeteer/puppeteer/releases/tag/browsers-v3.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 能力坑 · 来源证据：puppeteer-core: v25.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：puppeteer-core: v25.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3a8b10a5263e4d6488e16972c8249a38 | https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v25.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\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:90796663 | https://github.com/puppeteer/puppeteer | README/documentation is current enough for a first validation pass.\n\n## 13. 维护坑 · 来源证据：ng-schematics: v0.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：ng-schematics: v0.8.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e7ee6a70b1d4fb6879ab4670099d205 | https://github.com/puppeteer/puppeteer/releases/tag/ng-schematics-v0.8.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 来源证据：puppeteer-core: v25.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：puppeteer-core: v25.0.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3e6a5770b15146ddab5249f1aa687cae | https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v25.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 维护坑 · 来源证据：puppeteer: v25.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：puppeteer: v25.0.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9294fdbab95d446887bdb54a11df66d2 | https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-v25.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:90796663 | https://github.com/puppeteer/puppeteer | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:90796663 | https://github.com/puppeteer/puppeteer | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:90796663 | https://github.com/puppeteer/puppeteer | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 来源证据：[Feature]: Reducing dependencies\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: Reducing dependencies\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cb21a546ebb04ca39b334255b205c9da | https://github.com/puppeteer/puppeteer/issues/13552 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · 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:90796663 | https://github.com/puppeteer/puppeteer | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:90796663 | https://github.com/puppeteer/puppeteer | 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项目：puppeteer/puppeteer\n\n摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Chrome Canary/Firefox Nightly test results。\n\n## 1. 安装坑 · 来源证据：Chrome Canary/Firefox Nightly test results\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Chrome Canary/Firefox Nightly test results\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1aabe120a9df47a2adbd293381b50a64 | https://github.com/puppeteer/puppeteer/issues/12379 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Puppeteer v25\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Puppeteer v25\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_050f65ceff2a455da4a3538895a7538b | https://github.com/puppeteer/puppeteer/issues/14342 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：[Bug]: GHSA issued a false malicious package alert for puppeteer\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: GHSA issued a false malicious package alert for puppeteer\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_55588dfbd41442fdb8a2f4f1be57e4c9 | https://github.com/puppeteer/puppeteer/issues/14986 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：[Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stderr`\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Task]: Flaky `[fixtures.spec] Fixtures should dump browser process stderr`\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9b1ef7c38ed14c41b3e4ce786adcdf26 | https://github.com/puppeteer/puppeteer/issues/14774 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：[Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 (extract-zip 2.0.1)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: @puppeteer/browsers silently corrupts Chrome cache on Node.js 26 (extract-zip 2.0.1)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5d1f448d8768460a806ab32e8d4f6997 | https://github.com/puppeteer/puppeteer/issues/14957 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[Bug]: `setViewport` crashes on Firefox if uncaught\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: `setViewport` crashes on Firefox if uncaught\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_75bddb8a74194cf7a8978853f19db23a | https://github.com/puppeteer/puppeteer/issues/14989 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：[Bug]: chrome binary is not present when installing latest chrome\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: chrome binary is not present when installing latest chrome\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1e85cdab2b684dda8e5c83f55b8ff7b6 | https://github.com/puppeteer/puppeteer/issues/14988 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：[Feature]: Make proxy-agent dependency optional\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Make proxy-agent dependency optional\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_195c51e4a5e84edda14a2a79b456821c | https://github.com/puppeteer/puppeteer/issues/13775 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：browsers: v3.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：browsers: v3.0.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bf2d83568c54447fbfd3047d24be0c48 | https://github.com/puppeteer/puppeteer/releases/tag/browsers-v3.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 来源证据：browsers: v3.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：browsers: v3.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c9f08632e7ee4e9485d27b864a21e462 | https://github.com/puppeteer/puppeteer/releases/tag/browsers-v3.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 能力坑 · 来源证据：puppeteer-core: v25.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：puppeteer-core: v25.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3a8b10a5263e4d6488e16972c8249a38 | https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v25.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\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:90796663 | https://github.com/puppeteer/puppeteer | README/documentation is current enough for a first validation pass.\n\n## 13. 维护坑 · 来源证据：ng-schematics: v0.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：ng-schematics: v0.8.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e7ee6a70b1d4fb6879ab4670099d205 | https://github.com/puppeteer/puppeteer/releases/tag/ng-schematics-v0.8.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 来源证据：puppeteer-core: v25.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：puppeteer-core: v25.0.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3e6a5770b15146ddab5249f1aa687cae | https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-core-v25.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 维护坑 · 来源证据：puppeteer: v25.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：puppeteer: v25.0.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9294fdbab95d446887bdb54a11df66d2 | https://github.com/puppeteer/puppeteer/releases/tag/puppeteer-v25.0.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:90796663 | https://github.com/puppeteer/puppeteer | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:90796663 | https://github.com/puppeteer/puppeteer | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:90796663 | https://github.com/puppeteer/puppeteer | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 来源证据：[Feature]: Reducing dependencies\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: Reducing dependencies\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cb21a546ebb04ca39b334255b205c9da | https://github.com/puppeteer/puppeteer/issues/13552 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · 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:90796663 | https://github.com/puppeteer/puppeteer | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:90796663 | https://github.com/puppeteer/puppeteer | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# puppeteer - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for puppeteer/puppeteer.\n\nProject:\n- Name: puppeteer\n- Repository: https://github.com/puppeteer/puppeteer\n- Summary: JavaScript API for Chrome and Firefox\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: JavaScript API for Chrome and Firefox\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: JavaScript API for Chrome and Firefox\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n2. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. cdp-implementation: CDP Implementation. Produce one small intermediate artifact and wait for confirmation.\n4. page-api: Page API. Produce one small intermediate artifact and wait for confirmation.\n5. locators: Locators and Element Handles. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/puppeteer/puppeteer\n- https://github.com/puppeteer/puppeteer#readme\n- README.md\n- packages/puppeteer/package.json\n- packages/puppeteer/install.mjs\n- docs/guides/getting-started.md\n- packages/puppeteer-core/src/index.ts\n- packages/puppeteer-core/src/api/api.ts\n- packages/puppeteer-core/src/cdp/cdp.ts\n- packages/puppeteer-core/src/bidi/bidi.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：puppeteer/puppeteer\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm i puppeteer\n```\n\n来源：https://github.com/puppeteer/puppeteer#readme\n\n## 来源\n\n- repo: https://github.com/puppeteer/puppeteer\n- docs: https://github.com/puppeteer/puppeteer#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_25fd9b42e7524484a309f55c8d5afd29"
}