{"id":"a49246cf-d69a-47eb-9644-373da48c6c0d","entityType":"agent","slug":"clawhub-yicko-playwright-browser-use","name":"playwright-browser-use","canonicalUrl":"https://www.xpersona.co/agent/clawhub-yicko-playwright-browser-use","canonicalPath":"/agent/clawhub-yicko-playwright-browser-use","generatedAt":"2026-10-10T14:43:24.597Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T12:29:31.512Z","emptyReason":null},"description":"浏览器自动化 CLI（Playwright 版，纯 Node.js 实现）。除常规自动化（打开网页/截图/点击/填表/翻页）外，提供三类能力：(1) 会话凭证读写原语 —— `cookies` / `storage` 命令可**无需代码执行**即列出/导出/导入/清除/设置 cookie 与 localStorage，直接提取或注入登录态与会话令牌（此路径独立于代码执行；自 v1.3.2 起 `PW_BROWSER_SAFE_MODE=1` 会将其与代码执行一并禁用）；(2) `eval` 在页面上下文执行任意 JavaScript（可读 cookie/存储、发起带凭证请求）；(3) `run Skill: playwright-browser-use Owner: yicko Summary: 浏览器自动化 CLI（Playwright 版，纯 Node.js 实现）。除常规自动化（打开网页/截图/点击/填表/翻页）外，提供三类能力：(1) 会话凭证读写原语 —— cookies / storage 命令可**无需代码执行**即列出/导出/导入/清除/设置 cookie 与 localStorage，直接提取或注入登录态与会话令牌（此路径独立于代码执行；自 v1.3.2 起 PW_BROWSER_SAFE_MODE=1 会将其与代码执行一并禁用）；(2) eval 在页面上下文执行任意 JavaScript（可读 cookie/存储、发起带凭证请求）；(3) run Tags: latest:1.0.16 Version history: v1.0.16 | 2026-08-01T16:07:30.572Z | us","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.4K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s171gt9hm8qq7y2qtg3p5f639n84y0tw:playwright-browser-use","sourceUrl":"https://clawhub.ai/yicko/playwright-browser-use","homepage":"https://clawhub.ai/yicko/skills/playwright-browser-use","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/yicko/playwright-browser-use","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/yicko/skills/playwright-browser-use","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"浏览器自动化 CLI（Playwright 版，纯 Node.js 实现）。除常规自动化（打开网页/截图/点击/填表/翻页）外，提供三类能力：(1) 会话凭证读写原语 —— `cookies` / `storage` 命令可**无需代码执行**即列出/导出/导入/清除/设置 cookie 与 localStorage，"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T12:29:31.512Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T12:29:31.512Z","emptyReason":null},"stars":null,"forks":null,"downloads":1432,"packageName":null,"latestVersion":"1.0.16","tractionLabel":"1.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T12:29:31.444Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T12:29:31.512Z","lastCrawledAt":"2026-10-10T12:29:31.444Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T12:29:31.444Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.16","createdAt":"2026-08-01T16:07:30.572Z","changelog":"## playwright-browser-use 1.0.16 Changelog - Removed redundant documentation file: `skill-card.md` - No functional changes; all core features and behaviors remain unchanged.","fileCount":19,"zipByteSize":77782},{"version":"1.0.15","createdAt":"2026-07-30T14:14:57.405Z","changelog":"- skill-card.md 文件已移除，不再随版本分发。 - 无其他变更。","fileCount":19,"zipByteSize":83945},{"version":"1.0.14","createdAt":"2026-07-28T01:32:26.248Z","changelog":"- 删除 skill-card.md 文件。 - 无功能变化，本更新仅为移除多余文档文件，未影响核心功能或稳定性。","fileCount":19,"zipByteSize":65819},{"version":"1.0.13","createdAt":"2026-07-27T03:44:55.921Z","changelog":"- Removed the sample file skill-card.md. - No functional or behavioral changes to the skill itself. - Documentation and core usage remain unchanged.","fileCount":19,"zipByteSize":62256},{"version":"1.0.12","createdAt":"2026-07-26T20:42:39.000Z","changelog":"- Switched dependency from Playwright full to playwright-core; no browser download required, now uses system Chrome/Edge only. - Added English documentation files: README.en.md and QUICKSTART.en.md for non-Chinese users. - Added CHANGELOG.md and MANIFEST.txt for versioning and packaging clarity. - Removed obsolete skill-card.md, consolidating documentation. - Updated SKILL.md to clarify dependency, browser detection, and availability of English docs.","fileCount":19,"zipByteSize":59837},{"version":"1.0.11","createdAt":"2026-07-25T16:37:00.884Z","changelog":"## Playwright-browser-use 1.0.11 Changelog - Added `package-lock.json` to the repository. - Removed `skill-card.md` file. - SKILL.md: Documented new `capabilities` section outlining supported features. - No core logic or runtime changes; updates are for documentation and repository metadata only.","fileCount":14,"zipByteSize":31583},{"version":"1.0.10","createdAt":"2026-07-25T05:38:34.896Z","changelog":"- 添加全面的安全声明：详细说明 `eval`（页面 JS 执行）与 `run-code`（Node/Playwright 沙箱代码执行）能力、攻击面、token 认证机制，以及通过 `PW_BROWSER_SAFE_MODE=1` 可强制禁用代码执行 - 更新 skill 描述，突出代码执行特性、守护进程架构、token 认证保护及安全模式 - 明确命令认证措施和适用边界，提示所有命令均需随机 token 验证，默认仅本地可信进程可用 - 新增「文档语言与本地化说明」小节，提示命令用法与可见文本的多语言适配问题 - 移除无关 skill-card.md，保持文档精简","fileCount":13,"zipByteSize":30395},{"version":"1.0.9","createdAt":"2026-07-25T05:00:24.371Z","changelog":"- 移除了 skill-card.md 文件，无功能性代码变更 - SKILL.md 描述大幅升级：强调 `eval`、`run-code` 两项代码执行能力、token 认证、`PW_BROWSER_SAFE_MODE` 安全选项和页面/节点隔离边界 - 明确说明 eval/run-code 的攻击面、认证机制和环境变量隔离，提升安全警示与用法风险提示 - 文档新增“文档语言与本地化说明”与多语言适配建议 - 其余交互规范、命令速查和恢复指南未更动，仅补充和强化原安全声明及适用场景","fileCount":13,"zipByteSize":30387}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171gt9hm8qq7y2qtg3p5f639n84y0tw:playwright-browser-use","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yicko-playwright-browser-use/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yicko-playwright-browser-use/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yicko-playwright-browser-use/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yicko-playwright-browser-use/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yicko-playwright-browser-use/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yicko-playwright-browser-use/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T14:43:24.591Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yicko-playwright-browser-use/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yicko-playwright-browser-use/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yicko-playwright-browser-use/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yicko-playwright-browser-use/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T12:29:31.512Z","emptyReason":null},"readme":"Skill: playwright-browser-use\n\nOwner: yicko\n\nSummary: 浏览器自动化 CLI（Playwright 版，纯 Node.js 实现）。除常规自动化（打开网页/截图/点击/填表/翻页）外，提供三类能力：(1) 会话凭证读写原语 —— `cookies` / `storage` 命令可**无需代码执行**即列出/导出/导入/清除/设置 cookie 与 localStorage，直接提取或注入登录态与会话令牌（此路径独立于代码执行；自 v1.3.2 起 `PW_BROWSER_SAFE_MODE=1` 会将其与代码执行一并禁用）；(2) `eval` 在页面上下文执行任意 JavaScript（可读 cookie/存储、发起带凭证请求）；(3) `run\n\nTags: latest:1.0.16\n\nVersion history:\n\nv1.0.16 | 2026-08-01T16:07:30.572Z | user\n\n## playwright-browser-use 1.0.16 Changelog\n\n- Removed redundant documentation file: `skill-card.md`\n- No functional changes; all core features and behaviors remain unchanged.\n\nv1.0.15 | 2026-07-30T14:14:57.405Z | user\n\n- skill-card.md 文件已移除，不再随版本分发。\n- 无其他变更。\n\nv1.0.14 | 2026-07-28T01:32:26.248Z | user\n\n- 删除 skill-card.md 文件。\n- 无功能变化，本更新仅为移除多余文档文件，未影响核心功能或稳定性。\n\nv1.0.13 | 2026-07-27T03:44:55.921Z | user\n\n- Removed the sample file skill-card.md.\n- No functional or behavioral changes to the skill itself.\n- Documentation and core usage remain unchanged.\n\nv1.0.12 | 2026-07-26T20:42:39.000Z | user\n\n- Switched dependency from Playwright full to playwright-core; no browser download required, now uses system Chrome/Edge only.\n- Added English documentation files: README.en.md and QUICKSTART.en.md for non-Chinese users.\n- Added CHANGELOG.md and MANIFEST.txt for versioning and packaging clarity.\n- Removed obsolete skill-card.md, consolidating documentation.\n- Updated SKILL.md to clarify dependency, browser detection, and availability of English docs.\n\nv1.0.11 | 2026-07-25T16:37:00.884Z | user\n\n## Playwright-browser-use 1.0.11 Changelog\n\n- Added `package-lock.json` to the repository.\n- Removed `skill-card.md` file.\n- SKILL.md: Documented new `capabilities` section outlining supported features.\n- No core logic or runtime changes; updates are for documentation and repository metadata only.\n\nv1.0.10 | 2026-07-25T05:38:34.896Z | user\n\n- 添加全面的安全声明：详细说明 `eval`（页面 JS 执行）与 `run-code`（Node/Playwright 沙箱代码执行）能力、攻击面、token 认证机制，以及通过 `PW_BROWSER_SAFE_MODE=1` 可强制禁用代码执行\n- 更新 skill 描述，突出代码执行特性、守护进程架构、token 认证保护及安全模式\n- 明确命令认证措施和适用边界，提示所有命令均需随机 token 验证，默认仅本地可信进程可用\n- 新增「文档语言与本地化说明」小节，提示命令用法与可见文本的多语言适配问题\n- 移除无关 skill-card.md，保持文档精简\n\nv1.0.9 | 2026-07-25T05:00:24.371Z | user\n\n- 移除了 skill-card.md 文件，无功能性代码变更\n- SKILL.md 描述大幅升级：强调 `eval`、`run-code` 两项代码执行能力、token 认证、`PW_BROWSER_SAFE_MODE` 安全选项和页面/节点隔离边界\n- 明确说明 eval/run-code 的攻击面、认证机制和环境变量隔离，提升安全警示与用法风险提示\n- 文档新增“文档语言与本地化说明”与多语言适配建议\n- 其余交互规范、命令速查和恢复指南未更动，仅补充和强化原安全声明及适用场景\n\nv1.0.8 | 2026-07-24T07:01:36.359Z | user\n\n- Removed the sample skill-card.md file.\n- No changes to functionality or user experience.\n\nv1.0.7 | 2026-07-23T19:35:13.520Z | user\n\nVersion 1.0.6\n\n- Added LICENSE file for clear licensing information.\n- Added README.md to provide usage instructions and documentation.\n\nv1.0.6 | 2026-07-23T19:19:38.684Z | user\n\n- Removed sample file `skill-card.md` from the project.\n- No changes to code or runtime behavior.\n- Documentation and usage remain the same.\n\nv1.0.5 | 2026-07-23T18:53:44.102Z | user\n\n- Removed the sample file skill-card.md.\n- No functional or interface changes to the skill itself.\n- Documentation (SKILL.md) was unchanged, aside from unrelated descriptive or formatting edits.\n\nv1.0.4 | 2026-07-23T18:05:01.282Z | user\n\nNo user-facing changes detected in this version.\n\n- No file changes were detected.\n- Behavior and documentation remain unchanged from the previous version.\n\nv1.0.3 | 2026-07-23T17:53:08.375Z | user\n\n## playwright-browser-use 1.0.3 — Changelog\n\n- **Major documentation update:** SKILL.md has been completely rewritten and expanded.\n- Skill documentation now includes explicit safety boundaries and security scenarios section, clarifying what environments are considered safe for use.\n- Login and human-in-the-loop verification workflows are fully documented, with step-by-step instructions for both users and agent.\n- All usage, workflow, and command examples updated to reflect absolute path conventions and local security measures.\n- Internal metadata file (skill-card.md) has been removed.\n\nv1.0.2 | 2026-07-23T06:06:40.326Z | user\n\n- Removed the file: skill-card.md\n- No changes to functionality, only documentation file cleanup.\n\nv1.0.1 | 2026-07-23T02:00:44.640Z | user\n\nInitial release: Playwright-based browser automation skill, fully independent of DuMate.\n\n- Provides a CLI tool (`pw-browser`) for browser automation using Playwright with Node.js, supporting all key actions like navigation, snap, click, fill, scroll, and tab management.\n- No DuMate agent or extension required—runs standalone, using system-installed Chrome or Edge (via Playwright channel).\n- Includes robust session/daemon management for persistent browser/browser state across commands.\n- Detailed semantic rules and workflow best practices are documented, ensuring reliable usage patterns.\n- Command overview and advanced strategies (wait, snap, run-code, pagination, SPA handling) included.\n\nv1.0.0 | 2026-07-23T01:46:46.164Z | auto\n\nInitial release — brings full Playwright-based browser automation with a standalone Node.js CLI.\n\n- Provides browser automation (open web pages, screenshots, clicks, form filling, navigation, and more) using Playwright, no DuMate environment required.\n- Uses a persistent local daemon for browser state, communicating over HTTP; supports Chrome/Edge via Playwright’s channel mechanism.\n- Exposes a CLI tool (`pw-browser`) with a wide range of commands for page interaction, advanced scripting, tab management, and automation of common patterns like paging and login handling.\n- Offers detailed workflow guidelines, robust error/daemon recovery procedures, and extensive documentation for CLI commands and operational rules.\n\nArchive index:\n\nArchive v1.0.16: 19 files, 77782 bytes\n\nFiles: .clawhubignore (44b), .gitignore (39b), CHANGELOG.md (2514b), LICENSE (1062b), MANIFEST.txt (458b), package-lock.json (749b), package.json (1123b), pw-browser (266b), pw-browser.js (77857b), QUICKSTART.en.md (9139b), QUICKSTART.md (8662b), README.en.md (16514b), README.md (15399b), references/pagination.md (3377b), references/rich-text-editor.md (3295b), references/running-code.md (5570b), skill-card.md (2905b), SKILL.md (42369b), _meta.json (142b)\n\nFile v1.0.16:SKILL.md\n\n---\nname: playwright-browser-use\ndescription: 浏览器自动化 CLI（Playwright 版，纯 Node.js 实现）。除常规自动化（打开网页/截图/点击/填表/翻页）外，提供三类能力：(1) 会话凭证读写原语 —— `cookies` / `storage` 命令可**无需代码执行**即列出/导出/导入/清除/设置 cookie 与 localStorage，直接提取或注入登录态与会话令牌（此路径独立于代码执行；自 v1.3.2 起 `PW_BROWSER_SAFE_MODE=1` 会将其与代码执行一并禁用）；(2) `eval` 在页面上下文执行任意 JavaScript（可读 cookie/存储、发起带凭证请求）；(3) `run-code` 在守护进程上下文执行 Playwright/Node 代码（vm 沙箱隔离）。全部经持久化本地守护进程（127.0.0.1:19223，浏览器状态跨命令保持）控制，受随机 token 认证保护；`PW_BROWSER_SAFE_MODE=1` 可彻底禁用代码执行与 cookies/storage 凭证读写（v1.3.2+）。仅在可信、用户可见的本地环境中授权使用；会话凭证落盘须遵循后文安全警告。\nallowed-tools: Bash(node:*), Bash(pw-browser:*), Bash(curl:*)\ncapabilities:\n - \"code-execution: page-context (eval — arbitrary JS in current page)\"\n - \"code-execution: daemon-vm (run-code — null-prototype VM sandbox, no host fs/process)\"\n - \"network: arbitrary via browser/page context (credentialed requests possible)\"\n - \"browser-state: persistent credentialed session across commands\"\n - \"credential-access: direct read/export/import/clear/set of cookies & localStorage (session tokens) — no code execution needed; gated by daemon token, and fully DISABLED by PW_BROWSER_SAFE_MODE=1 (v1.3.2+)\"\n - \"file: write to local disk (run-code can trigger downloads; cookies/storage export writes credential files)\"\n# --- Formal permission model (machine-readable) -------------------------\n# NOTE: This skill has NO built-in fine-grained permission system. The\n# fields below are declarative metadata for orchestrators/reviewers, NOT\n# an enforcement boundary. Real constraints come only from:\n# - daemon token auth (gates NETWORK reachability, not per-capability)\n# - PW_BROWSER_SAFE_MODE=1 (disables code-exec + credential primitives)\n# - export/import path confinement to ~/.pw-browser (v1.3.1+); since v1.3.8\n# the caller-supplied --unsafe flag alone can NOT lift it — the operator\n# must also start the daemon with PW_BROWSER_ALLOW_UNSAFE_CRED_PATH=1\n# - PW_BROWSER_CRED_PERSIST=off (v1.3.9) removes credential persistence only\n# (export/import), keeping in-memory cookie/storage automation usable\n# \"capabilities\" lists the MINIMUM attack surface, not a maximum; the skill\n# can additionally drive any site the browser can reach, including ones where\n# the user is already authenticated. Least privilege is achieved at the\n# orchestration layer via deploy mode (safe mode + sandbox) + scoped ops.\npermissions:\n model: \"none-formal\" # no built-in RBAC / capability-dropping\n enforcement:\n - \"daemon-token\" # gates network reachability to 127.0.0.1:19223\n - \"safe-mode-env\" # PW_BROWSER_SAFE_MODE=1 disables code-exec + creds\n - \"path-confinement\" # cookies/storage IO limited to ~/.pw-browser\n - \"operator-gated-override\" # lifting confinement needs daemon env, not a caller flag\n - \"cred-persist-killswitch\" # PW_BROWSER_CRED_PERSIST=off blocks export/import only\n - \"secret-file-permissions\" # daemon token + credential dumps written 0600, dir 0700\n - \"download-name-sanitised\" # page-supplied download filename forced to a basename inside --path\n least-privilege:\n default-mode: \"full\" # full power; requires trusted, user-visible, local\n scoped-mode: \"cred-persist-off\" # PW_BROWSER_CRED_PERSIST=off — keeps automation,\n # removes the privilege-persistence primitive\n reduced-mode: \"safe-mode\" # PW_BROWSER_SAFE_MODE=1 — for not-fully-trusted agents\n untrusted-mode: \"safe-mode+sandbox\" # add network isolation for untrusted input\n metadata-is: \"attack-surface-description\" # NOT a grant, NOT a sandbox boundary\ndisable: false\n---\n\n# 浏览器自动化 — Playwright 版（`pw-browser`）\n\n> `pw-browser` 是基于 playwright-core（Playwright 核心库）的浏览器自动化 CLI，仅依赖 Node.js 和 playwright-core，无需下载任何浏览器。\n>\n> ⚠️ **完整能力（含代码执行）**：本工具**不只是\"点开网页\"**——它包含 `eval`（页面上下文**任意 JavaScript** 执行）与 `run-code`（守护进程上下文执行 Playwright/Node 代码）两项代码执行能力，并通过**持久化本地守护进程**控制浏览器状态（状态跨命令保持）。所有代码执行均受 daemon token 认证保护，可用 `PW_BROWSER_SAFE_MODE=1` 彻底禁用。请先阅读下方「⚠️ 安全边界与使用场景」了解完整攻击面与适用边界，再决定是否授权。\n\n## ⚠️ 安全边界与使用场景\n\n本工具为 **本地 AI 助手对话环境**设计，运行在用户完全可视、可中断的场景中。\n\n| 场景 | 风险 | 说明 |\n|------|------|------|\n| AI 助手对话交互（推荐） | 🟡 低 | 用户全程可见浏览器操作，可随时中断 |\n| 本地开发/测试 | 🟡 低 | 在受控环境中操作测试页面 |\n| 手动触发的数据采集 | 🟡 低 | 用户明确指定的页面和操作 |\n\n以下场景 **不推荐**直接使用，需要额外安全措施：\n\n| 场景 | 风险 | 需要的额外措施 |\n|------|------|-------------|\n| 被不可信 agent 调用 | 🔴 高 | 已内置 daemon token 认证 + 可选 `PW_BROWSER_SAFE_MODE` 禁用代码执行与 cookies/storage 凭证原语（v1.3.2+）；若来源仍不可信，应进一步沙箱隔离 |\n| 作为公开 API 服务 | 🔴 极高 | 必须加认证 + 操作白名单 |\n| CI/CD 自动化流水线 | 🟡 中 | 需限定操作范围，禁止生产环境 |\n\n**核心能力声明：**\n- `eval`：在**浏览器上下文**（`page.evaluate`）执行**任意 JavaScript**——即完整的页面级代码执行能力。它无法访问 Node.js API（`require`/`fs`/`process`），作用域仅限于当前页面；但正因如此，它能读取 `document.cookie`/`localStorage`/`sessionStorage`、发起**带页面凭证的 `fetch` 请求**、操控 DOM 并触发页面内动作（点击、提交等）。**这是与 `run-code` 同级的\"代码执行\"能力，仅场景不同（页面 vs Node）**：同样受 daemon token 认证保护，同样在 `PW_BROWSER_SAFE_MODE=1` 下被禁用；只在用户明确指定、且页面可信时使用，不对高权限/来源不明页面执行\n- `run-code`：在 daemon 进程的**受限沙箱**（`vm` 模块）中执行 Playwright 代码，仅暴露 `page` 和安全 JS 全局；**无法直接调用** `fs`/`child_process`/`process`/`require`。但浏览器上下文可经 `download.saveAs`/`setInputFiles` 在本地磁盘读写文件、能发起任意网络请求（沙箱不阻止）。它仍拥有完整浏览器控制权（导航、读写存储、下载、提交表单、改页面内容），**仅限本地信任环境使用**\n- `cookies` / `storage`：**独立的会话凭证读写原语**，无需任何代码执行即可对 cookie 与 `localStorage` 做 `list` / `export` / `import` / `clear` / `set`。它可直接**提取**当前登录态（含 `HttpOnly` cookie、会话/Bearer 令牌、CSRF token），也可**注入**任意攻击者控制的状态，是凭据盗窃与账户接管的**独立高危面**——**不依赖** `eval` / `run-code`。普通模式下仅由 daemon token 认证保护；自 v1.3.2 起 `PW_BROWSER_SAFE_MODE=1` 会**整体禁用**全部 `cookies` / `storage` 子命令（与 eval/run-code 同级拦截）。落盘会话文件的处置见下方「会话持久化风险（Rogue Agent）」块：务必用完即删、不跨环境/账号复用。`export`/`import` 默认**限制在 `~/.pw-browser/` 目录内**以防凭证散落或加载外部攻击者构造文件；自 v1.3.8 起该限制**不可由调用方自行解除**——越界需**同时**满足「操作者以 `PW_BROWSER_ALLOW_UNSAFE_CRED_PATH=1` 启动 daemon」+「调用方显式传 `--unsafe`」，否则返回 `UnsafeOverrideNotPermitted`\n- daemon：监听 `127.0.0.1:19223`，仅本机可访问，不暴露到公网；**所有命令（除 `/health` 存活探针）均要求随机 `token` 认证**，token 在 daemon 启动时生成并写入 `~/.pw-browser/daemon.json`（默认仅当前用户可读），CLI 自动携带，外部进程无法在未读取该文件的情况下调用\n- 安全模式：设置环境变量 `PW_BROWSER_SAFE_MODE=1` 启动 daemon 可**彻底禁用** `run-code` / `eval` **以及全部 `cookies` / `storage` 凭证原语**（v1.3.2+），仅保留 snap/click/fill 等白名单命令，适合不需要自定义代码、也不该触碰会话凭证的场景（如接入来源不完全可信的 agent）\n- 非 headless 模式：浏览器窗口始终可见，用户可直接监控所有操作\n- 文件下载：通过 `run-code` 触发页面下载（`download.saveAs`）会写入本地磁盘，注意目标路径\n- 下载文件名消毒（v1.3.10+）：`download` 命令的建议文件名由**被自动化的网页**决定而非操作者。当 `--path` 指向**目录**时，该名字会被强制取 `basename` 并校验解析后仍位于该目录内，越界返回 `PathTraversal`；恶意站点无法再用 `../../.bashrc` 之类的名字把文件写到目录之外。若 `--path` 显式指向一个**文件路径**，则按操作者意图原样使用\n\n## 🔐 权限模型与最低特权（形式化说明）\n\n> **关键澄清：`capabilities` 是攻击面描述，不是权限授予，也不是沙箱边界。**\n> frontmatter 里的 `capabilities` / `allowed-tools` 是给编排者与审核者的**自由文本元数据**：\n> - `capabilities` 列出的是本技能**能够做什么**（即真实攻击面的最小集合），**不代表**它被限制在这些能力内、也**不代表**它已获授权——拥有某项能力意味着技能*可以*行使它，而非*只能*行使它。\n> - `allowed-tools` 仅声明技能可调用哪些宿主工具（如 `Bash(node:*)`），**不构成**对技能行为的强制限制；真正的行为约束来自下方\"实际执行边界\"。\n> 审核时请以\"攻击面下限\"而非\"能力上限\"来读 `capabilities`：技能还可驱动浏览器能抵达的**任意站点**，包括用户**已登录**的站点，从而读取/操作该站点的认证状态。\n\n### 分级部署矩阵（最低特权选择）\n\n| 部署模式 | 代码执行 (`eval`/`run-code`) | 凭证原语 (`cookies`/`storage`) | 网络 | 适用场景 | 残余风险 |\n|----------|------------------------------|-------------------------------|------|----------|----------|\n| **全能力（默认）** | ✅ 开启 | ✅ 开启 | 经浏览器（含带凭证请求） | 可信本地、用户全程可见、临时/演示会话 | 高：可导出/注入会话、可发带凭证请求 |\n| **禁凭证落盘** `PW_BROWSER_CRED_PERSIST=off` | ✅ 开启 | ⚠️ 仅内存态（`export`/`import` 返回 `CredentialPersistenceDisabled`） | 经浏览器 | 需要完整自动化能力、但不允许会话状态跨运行留存的长驻 agent | 中高：仍可读取会话内容，但无法把它变成可复用的凭证文件 |\n| **安全模式** `PW_BROWSER_SAFE_MODE=1` | ⛔ 禁用 (返回 `Disabled`) | ⛔ 禁用 (返回 `Disabled`) | 仅 `snap`/`click`/`fill` 等白名单命令，不主动发请求 | 接入来源不完全可信的 agent、CI 只读巡检 | 中：仍可访问已打开页面的 DOM/可见内容 |\n| **沙箱 + 安全模式** | ⛔ 禁用 | ⛔ 禁用 | 额外做**网络隔离**（禁止出网 / 仅内网白名单） | 完全不可信或第三方输入驱动的自动化 | 低：沙箱逃逸前无法外联或触碰凭证 |\n\n**最低特权原则**：默认按\"全能力\"部署仅当满足——① 用户全程可见可中断；② 操作对象为用户明确指定的页面；③ 不在已登录高权限账户（银行/邮箱/工单系统）上执行未确认动作。否则应**优先启用安全模式**，并对不可信来源**进一步沙箱隔离**。\n\n### 实际执行边界（技能到底受什么约束）\n\n1. **daemon token 认证**：仅限制*谁能通过网络抵达 daemon*（须持有启动时生成的随机 token）。一旦本地进程持有 token，**所有能力全部可用**——token 是\"门禁\"而非\"按能力细分的权限\"。\n2. **安全模式（v1.3.2+）**：本技能**唯一内建的能力开关**，整体禁用代码执行与 `cookies`/`storage` 凭证原语；它是降低攻击面的主开关，但不是沙箱。\n3. **路径限制 + 操作者门禁（v1.3.1 / v1.3.8）**：`cookies`/`storage` 的 `export`/`import` 默认被限制在 `~/.pw-browser/` 内（符号链接经 realpath 解析，无法用软链逃逸）。**解除权归属操作者而非调用方**：越界须同时满足「daemon 以 `PW_BROWSER_ALLOW_UNSAFE_CRED_PATH=1` 启动」+「调用方显式 `--unsafe`」；仅传 `--unsafe` 会被拒（`UnsafeOverrideNotPermitted`），因为调用方不能修改 daemon 进程的环境变量。这只约束落盘位置，不约束浏览器内的读/写行为。每次凭证路径访问都会写入 daemon stderr 审计行。\n4. **凭证持久化开关（v1.3.9）**：`PW_BROWSER_CRED_PERSIST=off` 启动 daemon 可**单独禁用** `cookies`/`storage` 的 `export`/`import`（返回 `CredentialPersistenceDisabled`），而 `list`/`get`/`set`/`clear` 等内存态操作照常可用。它比安全模式**粒度更细**：只切断\"会话状态落盘\"这一条特权持久化路径，保留正常自动化能力。同样是进程环境变量，调用方无法解除。\n5. **落盘文件权限（v1.3.9）**：`~/.pw-browser/` 以 `0700` 创建，daemon 认证 token（`daemon.json`）与导出的凭证文件均以 `0600` 写入（已存在的旧文件会被 chmod 收紧）。这防止**同机其他本地用户**读走 token 接管浏览器、或直接读取导出的会话。注意：POSIX 权限位在 Windows 上不由操作系统强制执行，Windows 下依赖用户目录的 ACL 继承。\n6. **宿主工具策略**：`allowed-tools` 由宿主平台在*调用层*决定是否放行技能发起的工具调用；它依赖平台实现，**不保证**能限制技能在已获准工具内的具体行为（例如在 `Bash(node:*)` 内仍可执行任意 Node 代码）。\n\n> 结论：本技能**没有**独立于上述六点的\"形式化权限系统\"。任何\"最小权限\"诉求都必须通过**部署模式选择（安全模式/沙箱）+ 操作范围约定**在编排层落实，而非依赖技能元数据自证安全。\n\n## 📝 文档语言与本地化说明\n\n- **文档语言**：本技能文档为**简体中文**。若你或下游 agent 的默认语言非中文，请以代码块中的命令、URL、CSS 选择器与 `snap` 返回的 `ref` 为准——这些是**与语言无关**的自动化锚点。\n- **界面文本匹配是启发式的**：识别分页 / 按钮类型时，文档列出的中文、英文关键词（如\"下一页\"/\"Next\"、\"更新\"/\"保存\"/\"发布\"）只是**识别信号示例，并非穷举**；非中文页面的实际文案会不同。\n- **优先用 DOM 锚点，而非可见文字**：跨语言页面请尽量用 `snap` 得到的 `ref` 或 CSS 选择器（`page.locator('.xxx')`）定位元素，避免依赖本地化后的可见文本，以防因文案不同导致误点 / 误操作。\n- **适用区域**：技能本身不限定网站区域；文档示例与中文 UI 关键词面向中文环境，各\"识别信号\"表已并列给出英文界面关键词。\n- **英文文档**：面向非中文 agent/用户，提供 [`README.en.md`](./README.en.md)（英文 README）与 [`QUICKSTART.en.md`](./QUICKSTART.en.md)（英文端到端示例）。`SKILL.md` 本身保持中文，但其内的命令、URL、CSS 选择器、`snap` 返回的 `ref` 均为语言无关锚点，非中文 agent 可直接据此执行。\n\n## 前置条件（首次使用）\n\n本 Skill 所在目录需已执行 `npm install`（将安装 `playwright-core`）。**无需单独下载浏览器** — daemon 启动时自动检测并使用系统的 Chrome 或 Edge。\n\n> 下文所有命令中的 `{SKILL_DIR}` 请替换为实际的 skill 安装目录路径。\n\n## 架构\n\n`pw-browser` 采用 daemon + client 架构：\n\n```\n┌──────────────┐ HTTP (localhost:19223) ┌──────────────┐\n│ pw-browser │ ──────────────────────────────→│ Daemon │\n│ (CLI 客户端) │ │ (浏览器进程) │\n└──────────────┘ └──────┬───────┘\n │\n ├─ Playwright\n ├─ Chromium 浏览器\n └─ 页面状态持久化\n```\n\n**daemon 启动后持续运行**，浏览器和页面状态跨命令保持。CLI 每次通过 HTTP 调用 daemon。\n\n## 启动 Daemon\n\n**每次会话开始前**，在后台启动 daemon。以下命令使用 Skill 所在目录的绝对路径和 shim 脚本：\n\n```bash\nSKILL_DIR=\"{SKILL_DIR}\"\nNODE_PATH=\"${SKILL_DIR}/node_modules\" node \"${SKILL_DIR}/pw-browser.js\" daemon &\nsleep 4\n```\n\n> daemon 会在 `127.0.0.1:19223` 监听，首次启动会用 Playwright 的 `channel: 'chrome'` 自动连接系统 Chrome 浏览器（如已安装了 Edge 也会尝试）。无需下载额外的 Chromium。\n\n验证 daemon 可用：\n\n```bash\nSKILL_DIR=\"{SKILL_DIR}\"\nNODE_PATH=\"${SKILL_DIR}/node_modules\" node \"${SKILL_DIR}/pw-browser.js\" init\n```\n\n**关闭 daemon：**\n\n```bash\npw-browser close --all\n```\n\n## 核心工作流\n\n> **注意**：下面所有 `pw-browser` 命令都需要设置 `NODE_PATH`。Agent 执行时应使用完整形式：\n> ```bash\n> SKILL_DIR=\"{SKILL_DIR}\"\n> NODE_PATH=\"${SKILL_DIR}/node_modules\" node \"${SKILL_DIR}/pw-browser.js\" [args] [--json]\n> ```\n> 为简洁起见，下文示例省略前缀，用 `pw-browser` 表示。\n\n```bash\n# 1. 启动 daemon（会话开始一次）\npw-browser daemon &\n\n# 2. 打开页面\npw-browser open https://www.baidu.com\n\n# 3. 获取页面快照（必须！每次交互前都要 snap）\npw-browser snap\n\n# 4. 交互 — 基于快照中的 e0, e1, e2... ref 引用\npw-browser click e8 # 点击 ref=e8 的元素\npw-browser fill e5 \"hello\" # 在 ref=e5 的输入框填入文本\npw-browser press Enter # 键盘按键\n\n# 5. 等待\npw-browser wait-for \"text=加载完成\" --timeout 8000\npw-browser wait-for \"url:https://example.com/*\"\npw-browser wait-for \"state:networkidle\"\n\n# 6. Tab 管理\npw-browser tab list\npw-browser tab select 1\npw-browser tab close 0\n\n# 7. 关闭\npw-browser close # 关闭当前页面\npw-browser close --all # 关闭浏览器 + daemon\n```\n\n## 语义规则（必须遵守）\n\n### 规则 1：先观察再操作\n\nCLI **不会**在 open/click 后自动获取快照。**以下情况必须执行 `pw-browser snap`**：\n\n- **每次 `open` / `goto` / `go-back` / `go-forward` / `reload` 之后**（页面已变更）\n- **每次点击可能触发导航的元素之后**（链接、提交按钮等）\n- **首次进入陌生页面时**\n\n**同一页面内连续操作**（click → fill → press → click）可复用已获取的 ref，无需每步 snap。\n\n```\n正确: pw-browser open URL → pw-browser snap → pw-browser click e5 → pw-browser fill e8 \"text\"\n错误: pw-browser open URL → pw-browser click e5（open 后缺 snap）\n正确: pw-browser snap → pw-browser click e5 → pw-browser click e7（同一页面连续操作，ref 稳定）\n错误: pw-browser snap → pw-browser click e5 → pw-browser snap → pw-browser click e5（同一页面内多余 snap）\n```\n\n> ⚠️ **何时必须重新 snap：** 页面发生导航（URL 变化、新页面打开）、或 `act` 命令返回了 `interrupted`（DOM 已被修改）。此时旧 ref 可能指向错误元素，必须 re-snap 获取最新快照。\n\n### 规则 2：点击链接后处理导航\n\n点击可能触发导航的链接（`` 标签、按钮等）后：\n1. `pw-browser snap` — 检查页面是否已变化\n2. 如有新 tab → `pw-browser tab list` → `pw-browser tab select `\n3. `pw-browser snap` — 获取新页面内容\n\n### 规则 3：页面内容不全\n\n如果快照中元素不全（列表不完整等）：\n- `pw-browser mousewheel 0 500` 滚动\n- 或点击\"加载更多\"/\"下一页\"\n- 重新 `pw-browser snap`\n\n### 规则 4：登录与验证码（人机协作）\n\npw-browser 使用非 headless 模式打开实体 Chrome 窗口，用户可直接看到并操作浏览器。遇到需要人工介入的认证场景时，**不要用 `fill`/`click` 盲目尝试**，应按以下流程交接：\n\n#### 触发条件\n\n从 `snap` 中发现以下任一信号时，启动人工协作流程：\n\n- 页面 title 为「登录」/「Login」/「Sign In」\n- 页面 `url` 包含 `/login`、`/auth`、`/signin`\n- 快照中出现「登录」按钮 + 用户名/密码输入框\n- 快照中出现「验证码」「短信验证」「扫码登录」「滑块验证」等关键字\n- `open` 后自动跳转到登录页（URL 变化）\n\n#### 协作流程\n\n```\n第1步：通报用户\n 告知当前页面需要登录/验证，简明描述页面内容（输入框、验证码类型等）\n\n第2步：询问凭据（可选）\n 如果用户无凭据 → 跳过，直接等用户操作\n 如果用户提供凭据 → 用 fill/click 填入账号密码，点击登录按钮\n\n第3步：等待用户完成验证\n 明确告诉用户\"请在浏览器中完成验证码/二次验证\"\n 用户说\"好了\"\"完成了\"\"继续\"之后才继续\n\n第4步：验证登录状态\n 执行 pw-browser snap\n 检查是否进入目标页面 → 如果还是登录页，询问用户是否还需要操作\n 如果已进入 → 继续自动化流程\n```\n\n#### 示例对话\n\n```\nAgent: 页面跳转到了登录页 (https://xxx.com/login)，页面上有：\n 用户名输入框、密码输入框、登录按钮、滑块验证码。\n 需要我帮你填入账号密码吗？还是你在浏览器里自己操作？\n\nUser: 我来操作\n\nAgent: 好的，Chrome 窗口已打开 — 请完成登录后告诉我。\n\nUser: 好了\n\nAgent: [执行 snap]\n 登录成功！当前是「工作台」页面，左侧菜单有...\n```\n\n#### 重要约束\n\n- **不猜测凭据**：永远不要尝试默认密码或遍历登录\n- **不绕过验证码**：遇到验证码/滑块/短信验证时，立即交给用户\n- **不过度等待**：用户说继续后立即 snap，不额外 sleep\n- **登录失败回环**：snap 后发现仍在登录页 → 告知用户\"看起来还没登录成功，密码错误或验证未通过，请再试试\"\n\n### 规则 5：不要主动新建 tab\n\n点击导致新 tab 时用 `tab list/select/close` 处理。没有 `tab new` 命令。\n\n### 规则 6：翻页前读取策略\n\n涉及翻页、统计、收集、遍历时，参考下面的\"分页策略\"章节。\n\n### 规则 7：不手动读取快照文件\n\n快照通过 `pw-browser snap` 命令获取，不要直接读 `~/.pw-browser/snap.yml`。\n\n### 规则 8：SPA / 富文本编辑器\n\n遇到知识库、文档系统、CMS 等 SPA 页面，参考下面的\"SPA 与富文本编辑器\"章节。\n\n### 规则 9：daemon 故障恢复\n\n如果 CLI 返回连接错误：\n\n```bash\n# 删除旧的 daemon 状态文件\nrm -rf ~/.pw-browser/daemon.json\n```\n\n**杀掉占用端口 19223 的旧进程：**\n\n```bash\n# Windows (PowerShell)\npowershell -Command \"Get-NetTCPConnection -LocalPort 19223 -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id \\$_.OwningProcess -Force }\"\n\n# macOS / Linux\nlsof -ti:19223 | xargs kill -9 2>/dev/null\n# 或: fuser -k 19223/tcp 2>/dev/null\n```\n\n**重新启动：**\n\n```bash\nSKILL_DIR=\"{SKILL_DIR}\"\nNODE_PATH=\"${SKILL_DIR}/node_modules\" node \"${SKILL_DIR}/pw-browser.js\" daemon &\nsleep 4\n```\n\n---\n\n## 命令速查\n\n### 生命周期\n| 命令 | 说明 |\n|------|------|\n| `pw-browser init` | 连接 daemon，确认浏览器可用 |\n| `pw-browser open ` | 导航到 URL |\n| `pw-browser close` | 关闭当前页面 |\n| `pw-browser close --all` | 关闭浏览器 + daemon |\n| `pw-browser recover` | 重启浏览器连接 |\n\n### 状态感知\n| 命令 | 说明 |\n|------|------|\n| `pw-browser snap` | 获取页面快照（含 ref 引用）。**ref 在同一页面会话内保持稳定**（同一逻辑元素同 ref）；**每次导航后（新 URL / 新页面）必须重新 snap**，不可复用旧 ref |\n| `pw-browser wait-for [--timeout ms]` | 等待条件满足 |\n\n> **Shadow DOM / iframe 支持**：快照会递归进入 **open shadow root** 与 **同源 iframe**，这些元素同样出现在 ref 表中并可直接 `click`/`fill`/`upload`/`drag`。`snap` 输出的 ref 信息带 `inShadow: true`（shadow 内）或 `frameChain`（iframe 链）标记；定位由 `css >>>` 穿透 + `frameLocator` 自动完成，外部 agent 无需关心。`--annotate` 截图仅标注主文档元素（shadow/iframe 元素无法用 xpath 定位标注，但文本快照中仍可点）。跨域 iframe 不可访问，自动跳过。\n\n> **超大页面快照保护**：对元素极多的页面（数万节点），`snap` 默认最多收集 **3000** 个可交互元素，超出即停止收集并在输出标记 `⚠ snapshot truncated`，JSON 返回 `truncated: true`。这是为防止超大型 DOM 拖慢/撑爆快照的兜底；可用环境变量 `PW_BROWSER_SNAP_LIMIT=` 调大上限（设为 `0` 关闭上限，但仍会遍历整棵树），或先交互缩小页面范围再 `snap`。\n\n### 交互\n| 命令 | 说明 |\n|------|------|\n| `pw-browser click ` | 点击元素 |\n| `pw-browser fill \"text\"` | 填入文本 |\n| `pw-browser type \"text\"` | 键盘输入 |\n| `pw-browser press ` | 按下按键（Enter, Escape, Tab 等） |\n| `pw-browser hover ` | 悬停 |\n| `pw-browser select ` 标签、按钮等）后：\n1. `pw-browser snap` — 检查页面是否已变化\n2. 如有新 tab → `pw-browser tab list` → `pw-browser tab select `\n3. `pw-browser snap` — 获取新页面内容\n\n### 规则 3：页面内容不全\n\n如果快照中元素不全（列表不完整等）：\n- `pw-browser mousewheel 0 500` 滚动\n- 或点击\"加载更多\"/\"下一页\"\n- 重新 `pw-browser snap`\n\n### 规则 4：登录与验证码（人机协作）\n\npw-browser 使用非 headless 模式打开实体 Chrome 窗口，用户可直接看到并操作浏览器。遇到需要人工介入的认证场景时，**不要用 `fill`/`click` 盲目尝试**，应按以下流程交接：\n\n#### 触发条件\n\n从 `snap` 中发现以下任一信号时，启动人工协作流程：\n\n- 页面 title 为「登录」/「Login」/「Sign In」\n- 页面 `url` 包含 `/login`、`/auth`、`/signin`\n- 快照中出现「登录」按钮 + 用户名/密码输入框\n- 快照中出现「验证码」「短信验证」「扫码登录」「滑块验证」等关键字\n- `open` 后自动跳转到登录页（URL 变化）\n\n#### 协作流程\n\n```\n第1步：通报用户\n 告知当前页面需要登录/验证，简明描述页面内容（输入框、验证码类型等）\n\n第2步：询问凭据（可选）\n 如果用户无凭据 → 跳过，直接等用户操作\n 如果用户提供凭据 → 用 fill/click 填入账号密码，点击登录按钮\n\n第3步：等待用户完成验证\n 明确告诉用户\"请在浏览器中完成验证码/二次验证\"\n 用户说\"好了\"\"完成了\"\"继续\"之后才继续\n\n第4步：验证登录状态\n 执行 pw-browser snap\n 检查是否进入目标页面 → 如果还是登录页，询问用户是否还需要操作\n 如果已进入 → 继续自动化流程\n```\n\n#### 示例对话\n\n```\nAgent: 页面跳转到了登录页 (https://xxx.com/login)，页面上有：\n 用户名输入框、密码输入框、登录按钮、滑块验证码。\n 需要我帮你填入账号密码吗？还是你在浏览器里自己操作？\n\nUser: 我来操作\n\nAgent: 好的，Chrome 窗口已打开 — 请完成登录后告诉我。\n\nUser: 好了\n\nAgent: [执行 snap]\n 登录成功！当前是「工作台」页面，左侧菜单有...\n```\n\n#### 重要约束\n\n- **不猜测凭据**：永远不要尝试默认密码或遍历登录\n- **不绕过验证码**：遇到验证码/滑块/短信验证时，立即交给用户\n- **不过度等待**：用户说继续后立即 snap，不额外 sleep\n- **登录失败回环**：snap 后发现仍在登录页 → 告知用户\"看起来还没登录成功，密码错误或验证未通过，请再试试\"\n\n### 规则 5：不要主动新建 tab\n\n点击导致新 tab 时用 `tab list/select/close` 处理。没有 `tab new` 命令。\n\n### 规则 6：翻页前读取策略\n\n涉及翻页、统计、收集、遍历时，参考下面的\"分页策略\"章节。\n\n### 规则 7：不手动读取快照文件\n\n快照通过 `pw-browser snap` 命令获取，不要直接读 `~/.pw-browser/snap.yml`。\n\n### 规则 8：SPA / 富文本编辑器\n\n遇到知识库、文档系统、CMS 等 SPA 页面，参考下面的\"SPA 与富文本编辑器\"章节。\n\n### 规则 9：daemon 故障恢复\n\n如果 CLI 返回连接错误：\n\n```bash\n# 删除旧的 daemon 状态文件\nrm -rf ~/.pw-browser/daemon.json\n```\n\n**杀掉占用端口 19223 的旧进程：**\n\n```bash\n# Windows (PowerShell)\npowershell -Command \"Get-NetTCPConnection -LocalPort 19223 -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id \\$_.OwningProcess -Force }\"\n\n# macOS / Linux\nlsof -ti:19223 | xargs kill -9 2>/dev/null\n# 或: fuser -k 19223/tcp 2>/dev/null\n```\n\n**重新启动：**\n\n```bash\nSKILL_DIR=\"{SKILL_DIR}\"\nNODE_PATH=\"${SKILL_DIR}/node_modules\" node \"${SKILL_DIR}/pw-browser.js\" daemon &\nsleep 4\n```\n\n---\n\n## 命令速查\n\n### 生命周期\n| 命令 | 说明 |\n|------|------|\n| `pw-browser init` | 连接 daemon，确认浏览器可用 |\n| `pw-browser open ` | 导航到 URL |\n| `pw-browser close` | 关闭当前页面 |\n| `pw-browser close --all` | 关闭浏览器 + daemon |\n| `pw-browser recover` | 重启浏览器连接 |\n\n### 状态感知\n| 命令 | 说明 |\n|------|------|\n| `pw-browser snap` | 获取页面快照（含 ref 引用）。**ref 跨多次 snap 保持稳定**（同一逻辑元素同 ref），外部 agent 不必每步重新 snap |\n| `pw-browser wait-for [--timeout ms]` | 等待条件满足 |\n\n> **Shadow DOM / iframe 支持**：快照会递归进入 **open shadow root** 与 **同源 iframe**，这些元素同样出现在 ref 表中并可直接 `click`/`fill`/`upload`/`drag`。`snap` 输出的 ref 信息带 `inShadow: true`（shadow 内）或 `frameChain`（iframe 链）标记；定位由 `css >>>` 穿透 + `frameLocator` 自动完成，外部 agent 无需关心。`--annotate` 截图仅标注主文档元素（shadow/iframe 元素无法用 xpath 定位标注，但文本快照中仍可点）。跨域 iframe 不可访问，自动跳过。\n\n> **超大页面快照保护**：对元素极多的页面（数万节点），`snap` 默认最多收集 **3000** 个可交互元素，超出即停止收集并在输出标记 `⚠ snapshot truncated`，JSON 返回 `truncated: true`。这是为防止超大型 DOM 拖慢/撑爆快照的兜底；可用环境变量 `PW_BROWSER_SNAP_LIMIT=` 调大上限（设为 `0` 关闭上限，但仍会遍历整棵树），或先交互缩小页面范围再 `snap`。\n\n### 交互\n| 命令 | 说明 |\n|------|------|\n| `pw-browser click ` | 点击元素 |\n| `pw-browser fill \"text\"` | 填入文本 |\n| `pw-browser type \"text\"` | 键盘输入 |\n| `pw-browser press ` | 按下按键（Enter, Escape, Tab 等） |\n| `pw-browser hover ` | 悬停 |\n| `pw-browser select