@anweat/dsh-browser 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# 更新记录
+
+[返回 README](README.md)
+
+`@anweat/dsh-browser` 的版本记录，最新的在最前。每个版本写三件事：**兼容的 DSH 版本**、**改了什么**、**怎么升级**。日期是 git tag 的日期；没有 tag 的预发布版本不写日期。
+
+当前版本的兼容性一览在 [README](README.md#兼容性)；peer 范围的写法与取舍见 [docs/dev/host-compat.md](docs/dev/host-compat.md)。
+
+升级的通用步骤：
+
+```bash
+dsh plugin --profile <name> add @anweat/dsh-browser@<版本>
+# 然后完整重启 profile（Web profile 关闭了 HMR；只刷新网页不会重新加载插件服务）
+```
+
+DSH Desktop 上的升级方式见 [README 的 Desktop 安装](README.md#安装)。
+
+## 未发布
+
+## 0.2.3（2026-11-09）
+
+**摘要**：0.2.3 让插件能在 DSH 0.2.2-rc.1（cordis 4.1）上完整使用，并补上 0.2.1-rc.5 的支持：peer 范围加了 0.2.2 线，设置卡片的 RPC 通道在 cordis 4.1 宿主上能正常挂载（此前卡片能渲染，但所有数据请求返回 405）。另有此前未发布的文档整理。**谁应该升级**：所有在 DSH 0.2.2-rc.1 上的用户，包括 Desktop（已发布的 `0.2.2` 的 peer 范围不含 0.2.2-rc.1，会被拒绝安装）；0.2.0 / 0.2.1 线宿主上功能不变，可按需升级。感谢 [#48](https://github.com/anweat/dsh-browser/pull/48)（@snailium）和 [#49](https://github.com/anweat/dsh-browser/issues/49)（@shuaigekda）。**已知限制**：0.2.2 正式版靠 rc.1 的验证放行，没有在真实宿主上跑过；没有在 Electron Desktop 上实测，也没有和模型会话一起测过。
+
+**兼容**：新增实测 `dsh-v0.2.2-rc.1`（npm `@deepseek-ai/dsh@0.2.2-rc.1`，dist-tag `next`，cordis 4.1.0、schemastery 3.19.0，2026-11-05 验证）和 `dsh-v0.2.1-rc.5`（2026-10-30 验证）。peer 范围加第三段：DSH 包 `>=0.2.0-rc.2 <0.2.1-0 || >=0.2.1-rc.2 <0.2.2-0 || >=0.2.2-rc.1 <0.2.3-0`，Cordis `~4.0.4 || ~4.1.0`；`devDependencies` 升到 `0.2.2-rc.1` / cordis 4.1.0。起点是外部贡献 [#48](https://github.com/anweat/dsh-browser/pull/48)（@snailium，peer 与 devDependencies 改动原样保留作者署名）。**上界是 `<0.2.3-0`，所以 0.2.2 正式版也被放行，它靠 rc.1 的验证放行，没有在真实宿主上跑过。**
+
+**修复**：设置卡片的 RPC 通道 `/dsh-browser-assets` 在 cordis 4.1 宿主（DSH 0.2.2-rc.1）上没有挂上。根因在宿主：`connection.rpc.handle` 内部读 `owner.webServer`（`rpc-host.ts`），owner 没有注入它，4.1 的检查会抛 `cannot get property "webServer" without inject`；异常出在 `ctx.inject` 回调里没有被报告，结果卡片能渲染，但提示词、策略、资产、运行状态的每个 `/dsh-browser-assets/*` 请求都返回 HTTP 405，页面上只显示“暂时读不到…”。现在改为经一个派生 Context 读 `connection` 服务：`connectionCtx.extend({ webServer: connectionCtx.get('webServer') })`，把已注入的 `webServer` 作为自有属性带上，再调 `rpc.handle`，`owner.webServer` 就能解析。**不依赖宿主的私有方法**，所有宿主（0.2.0 / 0.2.1 / 0.2.2 线）走同一条路径；挂载失败时仍在控制台警告并写明通道与原因。做法由 [#49](https://github.com/anweat/dsh-browser/issues/49)（@shuaigekda）提出并在 0.2.2-rc.1 上验证，这里在三个宿主上复验。PR #48 只验证到“激活、设置命名空间存在”，没有跑到这一步。细节见 [docs/dev/host-compat.md](docs/dev/host-compat.md#资产-rpc-通道dsh-browser-assets)。
+
+**验证**：三个宿主（0.2.0-rc.2、0.2.1-rc.5、0.2.2-rc.1）上用 `pnpm pack` 的 tgz 走 `dsh plugin add file:` 安装闸门，没有配置的 entry 与有配置的 entry 各跑一次完整工具调用（`target.open` 本地页面、`observe.read`、`observe.screenshot`，以及一次 volatile 编辑后 `prompts` 立即生效且页面 session 不重启）；0.2.2-rc.1 的 Web 设置卡片渲染、保存一项、`cordis.patch.yml` 落盘与恢复，控制台 0 错误。`pnpm run verify`（464 项单测）与 `pnpm run test:e2e`（96 项）通过。记录见 [docs/validation/2026-11-09-dsh-0.2.2-public-api.md](docs/validation/2026-11-09-dsh-0.2.2-public-api.md)（公开 API 方案在三个宿主上的复验）、[docs/validation/2026-11-05-dsh-0.2.2.md](docs/validation/2026-11-05-dsh-0.2.2.md) 与 [docs/validation/2026-10-30-dsh-rc5.md](docs/validation/2026-10-30-dsh-rc5.md)。
+
+**升级**：从 `0.2.2` 升级到 `0.2.3` 即可；0.2.2-rc.1 宿主不需要其他配置。
+
+## 0.2.2（2026-10-28）
+
+**兼容**：`dsh-v0.2.0-rc.2`，`dsh-v0.2.1-rc.2` / `rc.3` / `rc.4`。同时支持两条线：受管 peer `>=0.2.0-rc.2 <0.2.1-0 || >=0.2.1-rc.2 <0.2.2-0`，Cordis peer `~4.0.4`，`devDependencies` 锁在 `0.2.1-rc.3`，schemastery 3.18.5。**源码不为任何一个宿主版本改动**：在真实安装的 0.2.0-rc.2、0.2.1-rc.3、0.2.1-rc.4 宿主上都完成了干净安装、Web 设置卡片渲染与保存、skill 注册、资产 RPC、`tools/pre-execute` 审批钩子的验证（见 [docs/validation/2026-10-28-compat-dist.md](docs/validation/2026-10-28-compat-dist.md)）。0.2.0 线宿主此前只能用 `0.2.1`，现在也可以装 `0.2.2`。验证：typecheck、构建、peer 双解析模式检查、单测、真实 Chromium e2e 与 client bundle 检查全绿，三个宿主版本上分别做了干净安装与设置卡片保存。
+
+**升级**：行为、配置键与审批规则与 `0.2.1` 相同；从 `0.2.1` 直接升级即可，不配置新键时行为不变（除下面的安装行为变化）。
+
+- **设置界面重做**（用户反馈“文字和框体太多，不知道怎么配，没有注释”）：状态摘要 + 九个可折叠分组（默认只展开“常用”）+ 一直在视野里的保存条（“N 项未保存 / 放弃 / 保存”）；下拉、开关、数字加单位、chips、列表和弹窗取代了整页文本框。登录 profile、提示词、自动化资产都是“列表 + 编辑弹窗”，提示词弹窗左右对照“默认文本｜我的覆盖”。每个键都有注释：字段旁一句话 + `?` 里的长说明，properties 文本模式每个键前一行注释，示例配置与导出的提示词默认文本（新的带注释 YAML）同样如此。保存结构、`Config` schema 与运行时行为不变（`authProfiles` 现在也能在卡片里改，它在 schema 里本来就可写）。详见 [设置卡片](docs/guide/settings-card.md) 与 [配置参考](docs/guide/configuration.md)。
+- **干净安装不再失败：OpenCLI 不再是依赖，改为可选并单独安装。** 旧版本把 `@jackwener/opencli` 列为 `dependencies`，它的 install 脚本（只做 shell 补全和清理测试文件）在新用户的 profile 里被 pnpm 11 拦下，`dsh plugin add` 以 `ERR_PNPM_IGNORED_BUILDS` 失败；更糟的是宿主只在“新增的依赖”上把插件加入 bundles，那次失败之后再 `add` 也不会补上，插件从来没有被启用。改成 `optionalDependencies` 没用（pnpm 11 仍然拦）。现在：包里没有 OpenCLI；`opencli.*` 动作在找到 OpenCLI 时照常工作（`PATH`、全局 npm 目录、nvm / fnm / Volta、profile 里自己装的、`DSH_BROWSER_OPENCLI`），找不到时返回带 `npm i -g @jackwener/opencli` 的说明；`runtime.status` 多了 `opencliSource` 与 `opencliInstallHint`，未安装不再是 `runtimeWarnings`。**已经在用内置 OpenCLI 的人**：升级后它会从 profile 里消失，如果你需要它，`npm i -g @jackwener/opencli` 并重启即可（已经全局装过的不用做任何事）。Web Search Pro 优先使用独立的 `opencli`，它的 `browser-opencli` 后备后端同样依赖这份安装。详见 [登录态复用与 OpenCLI](docs/guide/login-and-opencli.md)。
+- **新用户第一次使用不再卡在“没有 Chromium”：** 默认 `channel: chromium` 在 Playwright 的 Chromium 没有下载过时，自动改用本机的 Google Chrome 或 Microsoft Edge（macOS、Windows、Linux 的常见安装位置；不下载、不联网）；都没有时，`runtime.status` 的 `browser.ready` 为 `false`，`browser.installAdvice`、启动失败的错误信息、`browser_index` 根视图、设置卡片的状态摘要都给出同一组可照做的选项（装 Chrome / Edge、`runtime.install`、终端命令、`executablePath`）。`runtime.status` 新增 `browser`（`ready`、`source`、`path`、`note`、`installAdvice`）与 `systemBrowsers`；`chromiumInstalled` 与 `chromiumExecutablePath` 照旧。显式配置的 `executablePath` / `channel` 永远照你写的用，不会被悄悄替换，写错了会点名是哪个设置错了。详见 [内核与依赖](docs/guide/runtime-and-dependencies.md)。
+- 新增 context 创建期选项：配置键 `viewportMode` / `viewportWidth` / `viewportHeight` / `userAgent` / `locale` / `timezoneId` / `proxyServer` / `proxyBypass`，以及 `target.open` 的按次参数 `viewport` / `userAgent` / `locale` / `timezoneId` / `proxyServer`（见 [下载与上下文选项](docs/guide/downloads-and-context.md)）。
+- 新增 `target.download` 与 `inspect.downloads`，以及配置 `downloadDir`、`downloadMaxBytes`（见同一篇）。新增 `target.download` / `inspect.downloads` 使动作总数从 34 变为 36。
+- **嵌套写法不再被静默忽略**：配置里写 `viewport: {width, height}`、`proxy: {...}`、`contextOptions`、`download(s)` 会被忽略，并在 `runtime.status` 的 `runtimeWarnings` 里说明应使用哪些扁平键。**配置错误不会让插件加载失败**（否则设置卡片也会一起消失）：无效的值回退到默认并同样出现在 `runtimeWarnings`。
+- 带 `proxyServer` 或 `userAgent` 的 `target.open` 在 `standard` / `autonomous` 下需要审批，`read-only` 拒绝，`unrestricted` 放行；`target.download` 与 `act.upload` 同档。
+- 新增“策略覆盖层”：agent 可经 `inspect.policy` 与 `runtime.set_auth_profile` / `remove_auth_profile` / `set_usage_policy` / `reset_policy` 编辑限制类设置（authProfile 的域名、新建/删除，usagePolicy 限流项），不必用户手填。**`unrestricted` 下 agent 可自行放宽限制**，见 [策略覆盖层与风险](docs/guide/policy-overlay.md)。动作总数 36 变 41；新增配置 `allowPrivateHosts`（默认关）。
+
+## 0.2.1（2026-10-05）
+
+**兼容**：`dsh-v0.2.0-rc.2`（不变）。相对 `0.2.0` 的补丁版，DSH 基线与 peer 范围（`>=0.2.0-rc.2 <0.2.1-0`）不变，只含两项：
+
+1. 参数无效的调用不再先弹审批：审批钩子先判断动作是否被当前 `automationMode` 禁用（禁用仍直接拒绝），再用与 `runAction` 相同的校验检查参数，无效则不询问，执行层再校验一次并返回带精简 schema 的 `INVALID_ARGS`，不执行任何页面动作；参数有效时的审批规则与理由不变。
+2. “探索转草稿”（`draft_from_journal`）的指导文本补充。
+
+不改动作、参数 schema 与审批规则。在 `0.2.0-rc.2` 上完成 337 项测试与 66 项真实浏览器 e2e。
+
+**升级**：
+
+- 从 `0.2.0` 直接升级即可，DSH 基线、peer 范围、动作、参数 schema、面向模型的文本与审批规则都没有变化，已保存的资产、配置与提示文本覆盖照常使用。
+- 唯一的行为变化：参数无效的调用（例如 `act.select` 把 `values` 写成 `value`）不再先弹审批、等用户点“允许”之后才返回 `INVALID_ARGS`；现在直接返回 `INVALID_ARGS`（带精简 schema），页面没有任何改动，模型改对后只会询问一次。被当前 `automationMode` 禁用的动作仍直接拒绝。
+
+## 0.2.0（2026-10-04）
+
+**兼容**：`dsh-v0.2.0-rc.2`。第一个面向 DSH 桌面版 0.2.0 线的正式版，也是后续开发的基底。**只支持 `dsh-v0.2.0-rc.2` 这一条线**（peer `>=0.2.0-rc.2 <0.2.1-0`）：去掉为更旧宿主保留的兼容分支（`settings.register` 的 live scope 回退等），并去掉对 `settings` 服务的必需依赖（只声明 `inject: ['tools']`，没有 Settings 服务的组合里也能启动）；不改工具、动作、schema、文本与审批规则。在 `0.2.0-rc.2` 上完成 327 项测试、64 项真实浏览器 e2e 与 peer 双解析模式检查。旧宿主（0.1.7 线，`dsh-v0.1.7-rc.2`）继续使用 `0.1.17`。
+
+**升级**（承接 `0.2.0-rc.1` 的体系变更，从 `0.1.x` 升上来的人一并阅读）：
+
+- 旧的 `browser_open`、`browser_click` 等工具名不再注册。模型通过 `browser_index` 查看动作目录，再用 `browser_call` 执行，例如 `{"action":"act.click","args":{...}}`。需要一次性看到全部动作时，把 `toolSurface` 设为 `flat`。
+- 其他插件或自定义提示词里如果写了旧工具名，需要同步修改。Web Search Pro 请使用提示词已更新的版本。
+- 已保存的 recipe 和 userscript 资产照常可读、可运行；升级到 v2 用 `automation.develop` 的 `convert`，它只生成新草稿，不改原资产。
+- 激活资产现在要求当前版本有通过的测试记录。旧资产加载时会自动补一条“旧版”记录。
+- **声明了输入的资产，激活门槛提高了。** 新增策略项 `automationAssets.minInputSetsForActivation`（默认 2，范围 1–5）：带 `inputSchema` 或 `inputNames` 的资产，当前版本的通过凭据必须覆盖至少这么多组不同输入（`automation.develop` 的 `test` 传 `inputSets`；设置面板的“测试输入 JSON”填 2 到 5 个对象的数组），否则激活被拒绝，错误里写明原因。只用一组输入测试通过的 recipe 可能把那组输入写死，换一组就失败。没有输入的资产不受影响；升级前已通过测试的旧资产带“旧版”凭据，视为满足，不会因升级而无法激活。要恢复旧行为，把它设为 `1`。
+- `BrowserService` 上供其他插件调用的方法（`render`、`snapshot`、`searchResults`、`opencli`、`close`）签名不变。
+- **依赖范围收窄到 DSH 0.2.0 线。** peer 范围为 `>=0.2.0-rc.2 <0.2.1-0`（插件自身不再覆盖 `0.1.7-rc.2` 与 `0.2.0-rc.1`）。
+- 先确认宿主是 `dsh-v0.2.0-rc.2`。宿主更旧时，`dsh plugin add` 会因 peer 不满足而拒绝，或在组装期点名报 `incompatible`；这类宿主继续使用 `0.1.17`。
+- 工具、动作、参数 schema、文本与审批规则相对 `0.2.0-rc.1` 都没有变化，已保存的资产、配置与提示文本覆盖照常使用。
+- 设置的保存与重启生效路径不变：在设置卡片保存后重启 profile 生效。
+- 不再要求宿主提供 `settings` 服务：插件只声明 `inject: ['tools']`；有 Settings 服务时设置卡片照常显示，没有时按配置默认值运行。
+
+## 0.2.0-rc.1（2026-10-04，预发布，仅作历史记录）
+
+**兼容**：`dsh-v0.1.7-rc.2` ~ `dsh-v0.2.0-rc.2`。预发布通道 `@next` 不再用于安装。
+
+**破坏性变更**：30 个 `browser_*` 工具改为 `browser_index` / `browser_call` 两个入口加动作目录（常驻约 325 token，原约 8.8k）；随包提供 `dsh-browser` skill；recipe v2、资产版本与激活保护、结构化观察、探索记录生成草稿、提示文本可配置。并入按 session 隔离浏览器状态（#36）与 dialog 竞态修复（#30）。在 `0.2.0-rc.2` 上完成 325 项测试、64 项真实浏览器 e2e 与真实 Web profile 验证。迁移说明见上面的 0.2.0。
+
+## 0.1.17（2026-10-03）
+
+**兼容**：`dsh-v0.1.7-rc.2` ~ `dsh-v0.2.0-rc.2`。peer 收口为“实测过的两条线”（上界 `<0.2.1-0`），DSH 运行时依赖由精确锁定改为范围声明（`^0.1.7-rc.2 || >=0.2.0-rc.1 <0.2.1-0`），使同一份包可装在 `0.1.7-rc.2` 与 `0.2.0-rc.2` 两代宿主上。在 `0.2.0-rc.2` 上完成 typecheck、构建、52 项测试与真实挂载验证；补充浏览器缓存路径配置说明，并新增 peer 双解析模式检查。旧的 `browser_*` 工具体系，**0.1.7 线宿主（`dsh-v0.1.7-rc.2`）请固定使用这一版**。
+
+**升级**：Web Search Pro 与浏览器插件应同步升级；面向 `dsh-v0.1.7-rc.2` 不要混用仍声明旧 peer 的 Browser `0.1.15-alpha.2`；两者都升到 `0.1.17` 即可。
+
+```bash
+dsh plugin --profile web add @anweat/dsh-browser@0.1.17 dsh-web-search-pro@0.1.17
+```
+
+升级后完整停止并重启 Web profile，再调用 `runtime.status`、`opencli.status` 和 `web_backend_status`；仅刷新网页不会重新加载插件服务或 Web Search Pro 配置面板。尤其不要只升级 Web Search Pro：新的工具目录、Patchright 运行时和调用缓冲都来自浏览器插件。
+
+## 0.1.15（2026-09-27）
+
+**兼容**：`dsh-v0.1.7-rc.2`，精确锁定该宿主版本；组合安装、真实 Web profile 与设置持久化已验证。使用 DSH 新客户端分包：状态存储来自 `dsh-client-store`，设置契约来自 `dsh-client-ui-settings`，客户端 Context 来自 Cordis。npm 上 `0.1.15-alpha.2` 仍声明旧版 DSH peer，不能与本版混用。
+
+## 0.1.12 及更早（2026-08-29 ~ 2026-09-09）
+
+**兼容**：`dsh-v0.1.1-rc.2` 至 `dsh-v0.1.2-rc.1`。旧基线的维护版本；不与新插件混装。

package/README.en.md

@@ -0,0 +1,153 @@
+# dsh-browser
+
+English | [中文](https://github.com/anweat/dsh-browser/blob/master/README.md)
+
+A browser runtime plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). It lets the model open web pages, read them, operate them, take screenshots and download files, and it provides the `browser` service that `dsh-web-search-pro` builds on. The plugin ships the Playwright and Patchright drivers; **it does not download a browser**: if Google Chrome or Microsoft Edge is installed, it uses that.
+
+> The detailed guides under `docs/guide/` are written in Chinese. This README covers everything you need to install, configure and try the plugin in English.
+
+## Highlights
+
+- **Two always-on tools**: `browser_index` (browse the catalog) and `browser_call` (run an action). About 325 tokens of resident context; 41 actions in 9 groups, with the schema of one action shown on demand.
+- **No browser download needed**: the system Chrome or Edge is detected automatically; Playwright's Chromium is installed (`runtime.install`) only when neither exists. Patchright is an optional engine.
+- **Strict locators and structured observation**: semantic locators (`role` / `name` / `label` / `text` / `testId`); a locator that matches several elements does nothing and lists the candidates. `observe.read` returns controls, links and tables with locators you can pass straight to `act.*`.
+- **Per-session isolation and four automation modes**: every session gets its own browser context. `read-only`, `standard`, `autonomous` and `unrestricted` decide what is possible and what goes through DSH's native approval.
+- **Login state, downloads and rate limits**: domain-scoped `authProfile`s, downloads saved with a sha256, `usagePolicy` caps for concurrency and bursts. The model can tighten these through policy actions, or loosen them with approval.
+- **Reusable automation (experimental)**: recipe and UserScript assets that are recorded, searched, tested and activated by hand. OpenCLI site adapters are optional.
+
+Security boundaries and the September 2026 review are in [AUDIT.md](https://github.com/anweat/dsh-browser/blob/master/AUDIT.md) (written against 0.1.12, partly outdated; in Chinese). Note that `allowedDomains` only limits which login state is loaded. It is not a network firewall or an agent isolation boundary.
+
+## Compatibility
+
+| Plugin | DSH | Peer ranges |
+|---|---|---|
+| `0.2.3` (current) | `0.2.0-rc.2`, `0.2.1-rc.2` to `rc.5`, and the 0.2.2 line from `0.2.2-rc.1` (tested on 0.2.0-rc.2, 0.2.1-rc.3, 0.2.1-rc.4, 0.2.1-rc.5, 0.2.2-rc.1; the 0.2.2 and 0.2.3 final releases are admitted on the strength of rc.1 and has not been run) | DSH packages `>=0.2.0-rc.2 <0.2.1-0 \|\| >=0.2.1-rc.2 <0.2.2-0 \|\| >=0.2.2-rc.1 <0.2.3-0`; `@deepseek-ai/cordis` `~4.0.4 \|\| ~4.1.0` |
+| `0.1.17` (pin this on 0.1.7-line hosts) | `dsh-v0.1.7-rc.2` | the older `browser_*` tool set |
+
+Host versions outside these ranges are not verified. Older versions and upgrade notes are in the [CHANGELOG](https://github.com/anweat/dsh-browser/blob/master/CHANGELOG.md) (Chinese). Why the peer range has two segments is explained in [docs/dev/host-compat.md](https://github.com/anweat/dsh-browser/blob/master/docs/dev/host-compat.md) (Chinese).
+
+## Installation
+
+**DSH CLI** (using the `web` profile as an example):
+
+```bash
+dsh plugin --profile web add @anweat/dsh-browser@0.2.3
+# On a host of the 0.1.7 line (dsh-v0.1.7-rc.2), pin 0.1.17 instead:
+dsh plugin --profile web add @anweat/dsh-browser@0.1.17
+# Restart the profile after installing (the web profile runs without HMR):
+dsh --profile web
+```
+
+**DSH Desktop**: the Desktop profile is owned by the application, and the CLI refuses it (`profile "desktop" is managed exclusively by the Electron application`). Install from inside the app:
+
+1. Open the **Plugins** page and click **Add plugin**.
+2. Enter the package name, optionally with a version: the same text that follows `dsh plugin add`, for example `@anweat/dsh-browser@0.2.3`.
+3. The dialog also lets you choose a **Registry**. A mirror (for example npmmirror in China) can lag the official registry by minutes to hours; if the new version cannot be found, switch the Registry to `https://registry.npmjs.org`.
+4. Click **Install**, then restart when the app asks.
+
+Upgrading a third-party plugin means uninstalling it and installing it again.
+
+**Local directory or tarball** (for development):
+
+```bash
+dsh plugin --profile web add ./dsh-browser            # a local checkout
+pnpm pack && dsh plugin --profile web add ./anweat-dsh-browser-0.2.3.tgz
+```
+
+A local source checkout may carry a different version number than the published one; align the versions in the profile's `pnpm-workspace.yaml` and install again. With pnpm 11, `dsh plugin add` should succeed with exit code 0; editing the profile's `package.json` by hand is only a troubleshooting step.
+
+## First use
+
+1. **Find the settings card after the restart.** In the settings page, open Plugins; the card of `@anweat/dsh-browser` is titled "Browser automation" (the Chinese UI says 浏览器自动化). The **status summary** at its top describes the environment:
+   - a red "no usable browser" badge: click "details" for steps you can follow;
+   - "Browser: system Chrome / Edge": the normal state, nothing to do;
+   - "OpenCLI not installed": a hint, not a warning.
+2. **Confirm the browser.** Ask the model to call `browser_call({action:"runtime.status"})` (or read the status summary); `browser.ready` should be `true`.
+   - Chrome or Edge present: used automatically, nothing is downloaded. Once Playwright's Chromium has been downloaded, it takes precedence. With `executablePath` set, or `channel` set to `chrome` / `msedge`, exactly that browser is used and a missing one is an error.
+   - Neither present: install Chrome or Edge; or have the model call `runtime.install` (about 190 MB, asks for approval); or set `executablePath`. All options are in [runtime and dependencies](https://github.com/anweat/dsh-browser/blob/master/docs/guide/runtime-and-dependencies.md) (Chinese).
+3. **Optional dependencies.**
+   - **OpenCLI** is used only by the `opencli.*` actions and by Web Search Pro's `browser-opencli` backend. Run `npm i -g @jackwener/opencli`, restart, then call `opencli.status`. Without it everything else works, and `dsh plugin add` does not fail. The lookup order and troubleshooting are in [login state and OpenCLI](https://github.com/anweat/dsh-browser/blob/master/docs/guide/login-and-opencli.md) (Chinese).
+   - **dsh-web-search-pro** reads this plugin's `browser` service at run time for page snapshots, `playwright` fetches and search-page platforms. The two install independently, but those browser-based features need this plugin present.
+
+## Quick examples
+
+**A local development server** (for example a Vite app on `http://127.0.0.1:5173`). First set this in the settings card, or in the profile configuration:
+
+```yaml
+- insert:
+    - id: browser
+      name: '@anweat/dsh-browser'
+      config:
+        channel: chrome            # always use the local Chrome; omit for automatic choice
+        headless: true             # the default: no window
+        automationMode: autonomous # needed when the session's approval policy is "never", see below
+```
+
+Save, restart the profile, then the model calls `browser_call` in turn:
+
+```text
+# each line is the arguments of one browser_call
+{"action":"target.open","args":{"url":"http://127.0.0.1:5173"}}
+{"action":"observe.read","args":{"sections":["controls","tables"]}}
+{"action":"act.click","args":{"locator":{"role":"columnheader","name":"Name"}}}
+{"action":"observe.screenshot","args":{"filename":"dev-home.png"}}     → result.path
+# then call the host's read_image tool
+read_image({"file_path":"<the path returned by the previous step>"})
+```
+
+- `target.open` on a loopback address needs no extra permission and no auth profile.
+- **Approval**: under `standard` (the default) `act.*` goes through DSH approval. When the session's approval policy is `never`, every action that would ask is rejected automatically; set `automationMode` to `autonomous` and page interactions run directly. `script.evaluate` and `act.upload` still ask under `autonomous`; only `unrestricted` skips them.
+- **Login state**: to use a login state on a local address, configure `authProfiles` with `allowedDomains: [127.0.0.1]` (the state file must exist). If you want the agent to write such a loopback or private-network domain itself through `runtime.set_auth_profile`, `allowPrivateHosts: true` is required (off by default). Loosening is rejected when the approval policy is `never`, so put it in the configuration yourself.
+- **Screenshots**: `observe.screenshot` saves into `snapshotDir` (default `$DSH_HOME/data/browser/snapshots`) and returns `path`; pass it to the host's `read_image` tool (parameter `file_path`) to see the image. `read_image` belongs to the host, not to this plugin. The result of `target.open` also carries a full-page screenshot path.
+- A fixed viewport (a phone size, say): the `viewport` argument of `target.open`, or the `viewportMode` setting; see [downloads and context options](https://github.com/anweat/dsh-browser/blob/master/docs/guide/downloads-and-context.md) (Chinese).
+
+**A public page**: `target.open`, then `observe.read` for the text and `observe.screenshot` for an image. Forms use `act.fill` and `act.click`, which ask once per call under `standard`.
+
+## Tools and actions at a glance
+
+The model first looks at the catalog with `browser_index` (no arguments: groups and environment state; `{group}`: the actions of a group; `{action}`: the full parameter schema; `{query}`: keyword search), then runs `browser_call({action, args})`. Every action returns the same envelope, `{ok, action, executionStatus, result | error{code,message,hint}}`. Setting `toolSurface` to `flat` registers one tool per action instead (about 17.4k tokens resident; for comparison and debugging only).
+
+| Group | Purpose |
+|---|---|
+| `runtime` | runtime status, Chromium install, policy overlay for auth profiles and usage limits |
+| `target` | open / close / list / switch pages, download files |
+| `observe` | read page text, structured observation (controls / links / tables), screenshots |
+| `act` | click, fill, type, clear, press, select, check, hover, scroll, upload, wait |
+| `inspect` | console and failed requests, download records, the effective policy |
+| `script` | page JavaScript, built-in read-only scripts, UserScripts |
+| `automation` | search and run reusable assets, develop drafts, inline recipes |
+| `crawl` | bounded multi-page crawl |
+| `opencli` | OpenCLI site adapters |
+
+The full action catalog, error codes, strict locators and approval rules are in [tools and actions](https://github.com/anweat/dsh-browser/blob/master/docs/guide/tools-and-actions.md) and [automation modes and approval](https://github.com/anweat/dsh-browser/blob/master/docs/guide/automation-modes.md) (Chinese). The package ships a `dsh-browser` skill that teaches the model to reuse first, locate carefully and handle failures by error code.
+
+Callers and operators are responsible for judging, under the target site's rules and the applicable requirements, whether any page access, interaction, script, cookie use, upload or download is allowed. The plugin only performs the browser operations that were requested or approved; it does not judge whether a purpose is authorized by a site.
+
+## Common settings
+
+Change them in the settings card, or in the profile configuration (a fully commented example is in the [configuration reference](https://github.com/anweat/dsh-browser/blob/master/docs/guide/configuration.md), in Chinese). **A saved change needs a profile restart to take effect** (only prompt text overrides are read on every call).
+
+| Key | Default | Meaning |
+|---|---|---|
+| `automationMode` | `standard` | `read-only` \| `standard` (writes ask each time) \| `autonomous` (page interaction runs directly) \| `unrestricted` (no approval at all; isolated environments only) |
+| `toolSurface` | `indexed` | `indexed`: two resident tools; `flat`: one tool per action |
+| `channel` | `chromium` | `chromium` (Playwright's Chromium, falling back to system Chrome / Edge when not installed) \| `chrome` \| `msedge` (pinned) |
+| `headless` | `true` | `false` shows the browser window |
+| `executablePath` | empty | absolute path of a custom browser executable |
+| `browserRuntime` | `playwright` | `patchright`: Chromium only, friendlier to automation detection |
+| `opencliEnabled` | `true` | master switch for OpenCLI; without OpenCLI installed it only makes `opencli.*` unavailable |
+| `authProfiles` / `defaultAuthProfile` | empty | domain-scoped login states (`allowedDomains`, `storageStatePath`, `persistState`) |
+| `allowPrivateHosts` | `false` | lets the agent put localhost and private-network addresses into login domains |
+| `downloadDir` / `downloadMaxBytes` | `$DSH_HOME/data/browser/downloads` / 100 MiB | download directory and per-file cap |
+
+Also available: viewport, `userAgent`, `locale`, `timezoneId` and proxy (`viewportMode`, `proxyServer`, ...), `usagePolicy` rate limits, `automationAssets` and `prompts`; see the configuration reference.
+
+## Documentation
+
+- User guides (Chinese): the [documentation index](https://github.com/anweat/dsh-browser/blob/master/docs/README.md) lists every file under `docs/guide/`: configuration reference, settings card, tools and actions, Playwright recipes, automation assets, approval, policy overlay, usage policy, downloads and context options, login state and OpenCLI, runtime and dependencies, prompt text, UserScripts, the `browser` service.
+- [CHANGELOG](https://github.com/anweat/dsh-browser/blob/master/CHANGELOG.md): compatibility and upgrade notes per version (Chinese).
+- Developer docs: [docs/dev/](https://github.com/anweat/dsh-browser/blob/master/docs/dev/build-and-release.md) (build and release, host compatibility) and [docs/validation/](https://github.com/anweat/dsh-browser/tree/master/docs/validation) (validation records).
+
+## License
+
+MIT