快速使用与适用情形

安装并重启后，模型通过 browser_index 查看能力目录、用 browser_call 执行动作（runtime.status 可查看运行时状态），再按任务选择动作。默认 automationMode: standard：读取直接执行，点击、输入、按键、选择、勾选、悬停、文件上传及页面写操作走 DSH 原生一次性审批。页面脚本和本地文件上传在 autonomous 下仍需审批，只有 unrestricted 会跳过确认。

情形	推荐方式	关键边界
公开网页读取、截图	`target.open` → `observe.read` / `observe.screenshot`	不需要登录态
表单、分页、懒加载	`act.click` / `act.fill` / `act.type` / `act.clear` / `act.press` / `act.select` / `act.check` / `act.scroll`	CSS 或 role/text/label/testId 语义定位，默认严格唯一；`standard` 下审批
SPA 条件等待	`act.wait`	支持 locator、URL glob、networkidle 或最多 10 秒固定等待
悬停菜单与提示	`act.hover`	与直接页面交互使用相同审批策略
文件上传	`act.upload`	只接受现有绝对文件路径；最多 20 个、合计 512 MiB；除 `unrestricted` 外审批会显示路径
页面脚本表达式	`script.evaluate`	使用当前页面来源和登录态；可访问 DOM、非 HttpOnly Cookie、Web Storage 和浏览器允许的网络 API
页面故障排查	`target.open(capture=[console,network])` → `inspect.console` / `inspect.requests`	只在内存保留最多 200 条；网络仅记录失败及 4xx/5xx，不记录 body/header
登录后站点	`authProfile`	必须配置 `allowedDomains`；默认不回写 Cookie
固定站点增强	`rulePack`	只允许有界步骤；本地 init script 必须 SHA-256 固定且 ≤64KB
模型生成的多步操作	`automation.run_recipe`	声明式步骤；审批策略由 `automationMode` 决定
默认只读脚本	`script.catalog` → `script.run_builtin`	内置 article/links/JSON-LD/forms，不执行外来代码
外部模型生成 UserScript	`script.validate` → `script.run_userscript`	必须 `@match` + `@grant none`；除 `unrestricted` 外执行前审批
有限站点遍历	`crawl.crawl`	页数、深度、并发、突发与退避始终受 `usagePolicy` 约束
Reddit/小红书等 OpenCLI 平台	`opencli.status` → `opencli.catalog` → `opencli.run`	先发现精确 adapter；通用调用除 `unrestricted` 外需审批
普通站点兼容性不佳	`browserRuntime: patchright`	Chromium-only；建议专用 Chrome profile，不与指纹注入库叠加

所有网页访问、交互、脚本、Cookie 使用、上传和下载都必须由调用方或操作者根据目标网站规则及适用要求判断并使用。插件只执行被请求或批准的浏览器操作，不判断具体用途是否获得网站授权，也不承担调用方的合规责任。限流、审批、域名和文件边界用于约束执行面，不能替代目标网站规则。

DSH 会话示例：

先调用 browser_call({action:"runtime.status"})；然后用 target.open 打开目标页。
若页面需要登录，使用 authProfile=forum；不要把 Cookie 放进工具参数。

使用策略：防止过度调用的缓冲

usagePolicy 是资源与站点压力保护，不是审批系统。所有模式共用同一个进程内 Governor：

maxConcurrency 限制同时发起的导航，超出后排队；burst + minDelayMs 限制单站点短时突发。
OpenCLI adapter / Browser Bridge 调度也占用同一全局并发与 burst 缓冲，不会因绕过 Playwright 而失去节流。
站点返回 429、502、503、504 时，按 Retry-After 或指数退避进入站点级冷却，最多重试 retryLimit 次。
crawl.crawl 还受 maxPagesPerRun 和 maxDepth 硬上限约束；调用参数只能收紧，不能突破配置。
泛爬取默认使用匿名 context，不继承全局 storageStatePath 或 defaultAuthProfile；登录后读取仍使用显式限域的单页/Recipe 工具。
runtime.status 显示累计运行、排队、等待和 backoff 次数，便于判断是否调用过密。
泛爬取能力本身不隐藏，但调用方仍应遵守目标站点条款、robots 指令、版权、隐私和适用法律；工具每次返回该警告。

配置（cordis.yml / patch config）

- insert:
    - id: browser
      name: '@anweat/dsh-browser'
      config:
        automationMode: standard # read-only | standard | autonomous | unrestricted
        toolSurface: indexed     # indexed（默认，browser_index + browser_call）| flat（每个动作一个工具）
        browserRuntime: playwright # playwright | patchright
        channel: chromium        # 'chromium'（打包内核）| 'msedge'（系统 Edge）
        headless: true
        opencliEnabled: true
        usagePolicy:             # 所有模式都生效；无审批模式也不会绕过
          minDelayMs: 750
          maxConcurrency: 2
          burst: 3
          maxPagesPerRun: 20
          maxDepth: 2
          retryLimit: 2
          backoffBaseMs: 1000
          cooldownMs: 30000
        automationAssets:
          enabled: true
          persistenceMode: suggest # off | manual | suggest | auto-draft
          activationMode: manual   # 当前推荐值；不会因静态校验自动激活
          minSuccessfulRuns: 3
          minDistinctSessions: 2
          successWindowDays: 14
          minSuccessRate: 0.8
          maxCandidates: 20
          candidateTtlDays: 14
          maxSuggestionsPerDay: 2
          maxDrafts: 10
          maxActiveAssets: 50
          retrievalTopK: 5
          catalogTokenBudget: 800
          modelDevelopmentEnabled: true
          maxModelDraftWritesPerSession: 3
          maxTestCredentials: 5     # 每个资产保留最近 N 条测试凭据（激活只认绑定当前 revision 与内容哈希的 passed 凭据）
          minInputSetsForActivation: 2  # 声明了输入的资产，激活要求当前版本的通过凭据至少覆盖 N 组输入（1–5）；无输入的资产不受影响
        maxSessions: 8           # 同时持有 context+page 的 session 上限，超出淘汰最久未使用者
        storageStatePath: ''     # Playwright 登录态 JSON（复用已登录会话）
        authProfiles:
          forum:
            storageStatePath: 'D:/secrets/forum.json'
            allowedDomains: [example.com]
            persistState: false  # 默认只读；true 才会原子回写刷新后的状态
        rulePacks:
          forum-enhanced:
            matches: [example.com]
            initScriptPath: 'D:/dsh/rules/forum.js'
            initScriptSha256: ''
            steps:
              - { type: waitFor, selector: '#results', timeoutMs: 10000 }
              - { type: scroll, deltaY: 1600, repeat: 2, waitMs: 300 }
        autoInstall: false       # 缺内核时是否自动 install chromium
        verbose: false

这些字段同时进入 Host settings 命名空间和专用可视化卡片：打开 设置 → 插件 → 插件配置 → 浏览器自动化，可调整工具自由度、Playwright/Patchright、OpenCLI、usagePolicy、自动化资产策略与限域登录态；同一卡片包含候选提示、脚本列表、JSON 编辑器、测试、激活和归档操作。

卡片覆盖全部公开配置字段：maxSessions（会话上限）和 args（Chromium 启动参数，JSON 字符串数组）在“浏览器运行时”分区；authProfiles、rulePacks 结构较复杂，卡片里不提供表单，只列出名称并注明“在配置文件中编辑”。“调用缓冲 JSON”和“自动化资产策略 JSON”的提示由代码生成，列出全部可用键名。
测试输入 JSON 填一个对象是在当前页面运行一次；填 2 到 5 个对象组成的数组是逐组在全新上下文中回放（等价于 inputSets）。卡片逐组显示结果和 PARAMETERIZATION_SUSPECT 警告；声明了输入的资产在通过凭据覆盖的输入组数不足 minInputSetsForActivation 时，“激活”按钮旁给出说明并保持禁用。
新建 recipe 从 v2 模板开始（带 schemaVersion: 2、locator 步骤、inputSchema 和 postconditions 占位），模板本身可以直接保存。v1 recipe 有“转换为 v2”按钮：生成新草稿并选中，显示仍取第一个匹配的步骤数（pendingDisambiguation），原资产不变；有未保存修改时会先确认。
“提示文本”分区的“导出默认文本”按钮在只读文本框里显示全部默认值（与 pnpm prompts:dump 相同的 JSON），复制后按需改写。
估算的常驻 L0 token 数与 node scripts/measure-tool-surface.mjs 使用同一个估算函数和同一份工具定义，两处数字一致。保存运行时配置后需要重启 profile；资产 CRUD 通过 loopback-only Host RPC 即时落盘。若没有看到卡片，先确认浏览器插件已同步升级并完整重启，而不是只刷新 Web Search Pro 页面。

Patchright 可选内核

Patchright 是 Playwright-compatible 的 Chromium 驱动，适合普通 Playwright 在搜索页遇到自动化检测时显式启用：

browserRuntime: patchright
channel: chrome
headless: false

channel: chrome + headless: false 是更贴近其推荐的兼容配置；CI/无人值守也可使用 headless，但 runtime.status.runtimeWarnings 会如实提示差异。Patchright 会禁用 Playwright console API，因此依赖控制台监听的 Recipe/脚本不应切换到它。不要再叠加自定义 User-Agent、额外请求头或指纹注入器；这类组合更容易形成自相矛盾的指纹。

Camoufox 当前没有硬集成：截至本版，其 JS 包要求 Node 22 且 peer 约束为 playwright-core <1.61，与本插件验证的 Playwright/Patchright 1.62.1 不兼容，并需要独立下载 Firefox 内核。后续等版本边界对齐后再作为第三 provider 接入，避免安装后才发生依赖漂移。

Install

README

快速使用与适用情形

使用策略：防止过度调用的缓冲

配置（cordis.yml / patch config）

Patchright 可选内核