dsh-browser-verify 0.1.3 → 0.1.5

package/README.md

@@ -18,7 +18,7 @@ verification is just tool calls.
 ## Quick start
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.3
+dsh plugin --profile web add dsh-browser-verify@0.1.5
 ```
 
 1. **Install** with the command above (or see [Install](#install)).
@@ -52,6 +52,22 @@ state?"; add `browser_screenshot` when you need to see the layout, or
 Use `browser_assert` before `browser_screenshot`: an assertion is cheaper, and
 a screenshot is for when the rendering itself must be judged.
 
+## Real model experience
+
+> **"Pleasant to use, cleanly layered."** — a real model's verdict, after
+> putting the four tools to work on a real business page.
+
+- **A three-state verification in 4–5 tool calls, zero environment setup** —
+  the same job used to take ~20 manual script steps.
+- **Mock, then it reloads itself** — no more "same URL, screenshot unchanged"
+  traps.
+- **Screenshots land right in the model's context** — no file paths to chase.
+- **Structured asserts** (count / text / elapsed) that even warn you when the
+  page didn't actually refresh.
+- **Every open resets the world** — states never bleed into each other.
+
+Verification should be a few tool calls, not script choreography.
+
 ### Worked example — two states, six calls
 
 The typical verification (empty state + normal state) is 6 calls:
@@ -69,7 +85,7 @@ browser_screenshot
 ## Install
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.3
+dsh plugin --profile web add dsh-browser-verify@0.1.5
 ```
 
 The version is pinned on purpose: pnpm 11 holds back packages published in the
@@ -79,18 +95,23 @@ of this deployment — use your own profile name if it differs.
 
 Requires **dsh ≥ 0.1.2-alpha.1**.
 
-### Browser prerequisite (read this)
+### Browser prerequisite (usually none)
+
+The plugin does **not** download Chromium — it finds a browser on your machine:
+the playwright cache (any installed version), then system Chrome / Chromium /
+Edge on common install paths and `$PATH`. Most machines — anything that ever
+ran a playwright project, or has Chrome installed — work with zero setup.
 
-The plugin does **not** download Chromium — it finds a browser on your machine
-instead. Install it once with:
+Only when neither exists, install the browser once:
 
 ```sh
-npx playwright install chromium     # needs playwright-core@1.62.0
+npx playwright install chromium
 ```
 
 or point the plugin at an existing binary via `DSH_BROWSER_VERIFY_CHROMIUM`
-(see [Environment variables](#environment-variables)). Without either, the
-first `browser_open` fails with an actionable install hint.
+(see [Environment variables](#environment-variables)). A system browser is
+used as-is with an "unverified version" hint; without any browser, the first
+`browser_open` fails with an actionable install hint.
 
 ## Environment variables
 

package/README.zh.md

@@ -12,7 +12,7 @@
 ## 快速上手
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.3
+dsh plugin --profile web add dsh-browser-verify@0.1.5
 ```
 
 1. **安装**（更多方式见 [安装](#安装)）。
@@ -34,16 +34,29 @@ browser_assert  selector=".empty-wrap" text="暂无可用缴费服务"
 
 ## 它做什么
 
-| 工具                   | 用途                                                                                                                                                                                                                                                       |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `browser_open`       | 在全新场景中打开 URL（无头 Chromium，默认视口 390×844 @2x），返回 title / HTTP 状态 / 可见文本摘要 / console 错误。不传 `waitSelector` 时默认等待页面**渲染稳定**后再采样（连续两次相同可见文本即稳定，上限约 3s），不会采到启动骨架帧；`加载中...` 等加载态文案自动过滤。可选 `waitSelector` 等待关键元素出现后再返回；可选内联 `mocks` 在**首次导航前**拦截接口——用于一启动就依赖 mock 数据的页面。 |
-| `browser_mock`       | 注册 playwright glob 路由（如`**/api/*.do*`）返回指定 JSON，并自动 reload 页面展示 mock 状态——不碰后端最快验证空态/异常态。重复 pattern 会提示报错。                                                                                                   |
-| `browser_assert`     | 最省 token 也最精确的验证：等待 CSS 选择器出现，校验数量与包含文本，返回`{pass, count, actualText, elapsedMs}`。不满足时返回 `pass:false`（附差异），**绝不抛错**——失败是一等公民的结果，而不是要调试的异常。                                  |
-| `browser_screenshot` | 截取当前页面（视口或整页），**自动以 image block 投影到模型上下文**——模型直接"看见"版式，无需任何文件处理。返回尺寸、sha256；与上一张完全一致时 `identicalToPrevious:true`（疑似页面未刷新）。                                                   |
+| 工具                   | 用途                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `browser_open`       | 在全新场景中打开 URL（无头 Chromium，默认视口 390×844 @2x），返回 title / HTTP 状态 / 可见文本摘要 / console 错误。不传`waitSelector` 时默认等待页面**渲染稳定**后再采样（连续两次相同可见文本即稳定，上限约 3s），不会采到启动骨架帧；`加载中...` 等加载态文案自动过滤。可选 `waitSelector` 等待关键元素出现后再返回；可选内联 `mocks` 在**首次导航前**拦截接口——用于一启动就依赖 mock 数据的页面。 |
+| `browser_mock`       | 注册 playwright glob 路由（如`**/api/*.do*`）返回指定 JSON，并自动 reload 页面展示 mock 状态——不碰后端最快验证空态/异常态。重复 pattern 会提示报错。                                                                                                                                                                                                                                                                    |
+| `browser_assert`     | 最省 token 也最精确的验证：等待 CSS 选择器出现，校验数量与包含文本，返回`{pass, count, actualText, elapsedMs}`。不满足时返回 `pass:false`（附差异），**绝不抛错**——失败是一等公民的结果，而不是要调试的异常。                                                                                                                                                                                                   |
+| `browser_screenshot` | 截取当前页面（视口或整页），**自动以 image block 投影到模型上下文**——模型直接"看见"版式，无需任何文件处理。返回尺寸、sha256；与上一张完全一致时 `identicalToPrevious:true`（疑似页面未刷新）。                                                                                                                                                                                                                    |
 
 先 `browser_assert` 再 `browser_screenshot`：断言更便宜，截图留给必须判断
 渲染效果的时刻。
 
+## 真实模型使用体验
+
+> **"好用，层级分明。"** —— 一位真实使用过的大模型的评价：把四件套拿真实的
+> 业务页面轮了一遍。
+
+- **三态验证 4–5 次工具调用跑完，零环境搭建**——以前同样的事要 ~20 步手动脚本；
+- **mock 后自动 reload**——不会再踩"同 URL、截图不变"的坑；
+- **截图直接进模型上下文**——不用追文件路径；
+- **断言结构化**（count / text / 耗时），页面没真刷新还会主动提醒你；
+- **每次打开场景全新**——三态之间互不串扰。
+
+验证就该是几次工具调用，而不是脚本编排。
+
 ### 完整示例——两态六次调用
 
 典型验证（空态 + 正常态）只需 6 次调用：
@@ -61,7 +74,7 @@ browser_screenshot
 ## 安装
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.3
+dsh plugin --profile web add dsh-browser-verify@0.1.5
 ```
 
 版本故意钉死：pnpm 11 会暂缓 24 小时内新发布的包，裸写 `add dsh-browser-verify`（latest）会在发布当天装到上一个版本。`--profile web`
@@ -69,16 +82,21 @@ dsh plugin --profile web add dsh-browser-verify@0.1.3
 
 要求 **dsh ≥ 0.1.2-alpha.1**。
 
-### 浏览器前置（务必读）
+### 浏览器前置（通常无需）
+
+本插件**不自带 Chromium**——它在你机器上找浏览器：playwright 缓存（任意安装版本），
+然后是系统 Chrome / Chromium / Edge 的常见安装路径与 `$PATH`。多数机器——装过任何
+playwright 项目，或装有 Chrome——零配置直接可用。
 
-本插件**不自带 Chromium**——它在你机器上找浏览器。先装一次：
+两者都没有时才需要装一次：
 
 ```sh
-npx playwright install chromium     # 需要 playwright-core@1.62.0
+npx playwright install chromium
 ```
 
 或通过 `DSH_BROWSER_VERIFY_CHROMIUM` 指向已有二进制（见
-[环境变量](#环境变量)）。两者都没有时，第一次 `browser_open` 会给出可操作的安装提示。
+[环境变量](#环境变量)）。系统浏览器直接使用（附"未认证版本"提示）；一个浏览器
+都没有时，第一次 `browser_open` 会给出可操作的安装提示。
 
 ## 环境变量
 

package/lib/cli.js

@@ -1,4 +1,4 @@
-import { t as BrowserDriver } from "./driver-Dwuu4MgP.js";
+import { t as BrowserDriver } from "./driver-POR2-Czc.js";
 import { readFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";

package/lib/{driver-Dwuu4MgP.js → driver-POR2-Czc.js}

@@ -23,6 +23,48 @@ const LIST_PREFIXES = [{
 	kind: "chromium",
 	prefix: "chromium-"
 }];
+/** PATH command names probed as a last-resort system-browser fallback. */
+const SYSTEM_COMMANDS = [
+	"google-chrome",
+	"google-chrome-stable",
+	"chromium",
+	"chromium-browser",
+	"chrome",
+	"chrome.exe"
+];
+/** Common install locations for system Chromium-based browsers, per platform. */
+function systemBrowserCandidates(platform = process.platform, home = homedir()) {
+	if (platform === "win32") return [
+		"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+		"C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+		"C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe",
+		"C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"
+	];
+	if (platform === "linux") return [
+		"/usr/bin/google-chrome",
+		"/usr/bin/google-chrome-stable",
+		"/usr/bin/chromium",
+		"/usr/bin/chromium-browser",
+		"/usr/bin/chrome",
+		"/snap/bin/chromium",
+		"/snap/bin/google-chrome"
+	];
+	return [
+		"Google Chrome.app/Contents/MacOS/Google Chrome",
+		"Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+		"Chromium.app/Contents/MacOS/Chromium"
+	].flatMap((app) => [`/Applications/${app}`, join(home, "Applications", app)]);
+}
+/** Resolve a command name on $PATH using the injected exists probe (no exec). */
+function resolveCommandOnPath(command, pathEnv, exists, sep = process.platform === "win32" ? ";" : ":") {
+	if (pathEnv === void 0 || pathEnv === "") return null;
+	for (const dir of pathEnv.split(sep)) {
+		if (dir === "") continue;
+		const candidate = join(dir, command);
+		if (exists(candidate)) return candidate;
+	}
+	return null;
+}
 /** Default cache location on macOS. */
 function defaultCacheDir() {
 	return join(homedir(), "Library", "Caches", "ms-playwright");
@@ -62,8 +104,7 @@ function discoverBrowser(opts = {}) {
 	} catch {
 		list = null;
 	}
-	if (list === null) throw new Error(`browser-verify: 未找到浏览器缓存目录 ${cacheDir}。请先安装：npx playwright install chromium（需 playwright-core@1.62.0），或设置 DSH_BROWSER_VERIFY_CHROMIUM=<完整路径>。`);
-	for (const { kind, prefix } of LIST_PREFIXES) {
+	if (list !== null) for (const { kind, prefix } of LIST_PREFIXES) {
 		const revision = maxRevision(list, prefix);
 		if (revision === null) continue;
 		const executablePath = join(cacheDir, `${kind === "headless-shell" ? `chromium_headless_shell-${revision}` : `chromium-${revision}`}`, SUBDIRS[kind]);
@@ -77,7 +118,24 @@ function discoverBrowser(opts = {}) {
 			versionHint: known ? null : `浏览器 revision ${revision} 不在已认证表（playwright-core 1.62.0 认证 ${Object.keys(KNOWN_REVISIONS).join("/")}）；若协议异常，请安装匹配版本`
 		};
 	}
-	throw new Error(`browser-verify: 未找到浏览器二进制。请先安装：npx playwright install chromium（需 playwright-core@1.62.0），或设置 DSH_BROWSER_VERIFY_CHROMIUM=<完整路径>。`);
+	const system = findSystemBrowser(opts, exists);
+	if (system !== null) return system;
+	throw new Error(`browser-verify: 未找到可用的浏览器（已探测：playwright 缓存 ${cacheDir} 与系统 Chrome/Chromium/Edge 常见路径）。请执行一次 npx playwright install chromium 后重试，或用 DSH_BROWSER_VERIFY_CHROMIUM 指定已有二进制。`);
+}
+/** First existing system-browser candidate, or null. */
+function findSystemBrowser(opts, exists) {
+	const candidates = opts.systemCandidates ?? [...systemBrowserCandidates(), ...SYSTEM_COMMANDS.map((cmd) => resolveCommandOnPath(cmd, opts.pathEnv ?? process.env.PATH, exists)).filter((p) => p !== null)];
+	for (const candidate of candidates) {
+		if (!exists(candidate)) continue;
+		return {
+			executablePath: candidate,
+			kind: "system",
+			revision: 0,
+			known: false,
+			versionHint: `系统浏览器（未与插件认证版本 ${Object.keys(KNOWN_REVISIONS).join("/")} 对齐）；若渲染异常，请执行 npx playwright install chromium 安装匹配版本`
+		};
+	}
+	return null;
 }
 //#endregion
 //#region src/browser/scenario.ts

package/lib/index.js

@@ -1,4 +1,4 @@
-import { t as BrowserDriver } from "./driver-Dwuu4MgP.js";
+import { t as BrowserDriver } from "./driver-POR2-Czc.js";
 import { exec } from "node:child_process";
 import { readdir, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -29,6 +29,18 @@ function selectOrphanDirs(entries, nowMs, ageMs, prefix) {
 }
 //#endregion
 //#region src/attachments.ts
+/**
+* Formats a stored screenshot can carry: Playwright captures PNG, and the
+* attachment store re-encodes above its normalization budget (JPEG, or WebP
+* when the source keeps alpha). Every entry is a possible store fact — never
+* assume PNG.
+*/
+const SCREENSHOT_MEDIA_TYPES = [
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/gif"
+];
 function imageRefFromValue(image) {
 	return {
 		attachmentId: AttachmentId(image.attachmentId),
@@ -36,14 +48,44 @@ function imageRefFromValue(image) {
 		bytes: image.bytes,
 		width: image.width,
 		height: image.height,
-		...image.name === void 0 ? {} : { name: image.name }
+		...image.name === void 0 ? {} : { name: image.name },
+		...image.originalDimensions === void 0 ? {} : { originalDimensions: image.originalDimensions }
+	};
+}
+/**
+* Build the tool value from the store reference alone. Every fact — format,
+* byte length, dimensions — is copied from what the store actually published,
+* because the read path re-derives them from the stored bytes and rejects any
+* reference that disagrees. Restating a constant here (e.g. PNG for a capture
+* the store normalized to JPEG) writes a self-contradicting attachment
+* reference into immutable history, which fails every later model request.
+* @param ref - reference returned by `saveImage`.
+* @param sha256 - digest of the captured bytes.
+* @param identicalToPrevious - whether this capture repeated the previous one.
+* @returns the tool-facing value projected into the model context.
+*/
+function screenshotValueFrom(ref, sha256, identicalToPrevious) {
+	return {
+		image: {
+			attachmentId: String(ref.attachmentId),
+			mediaType: ref.mediaType,
+			bytes: ref.bytes,
+			width: ref.width,
+			height: ref.height,
+			...ref.name === void 0 ? {} : { name: ref.name },
+			...ref.originalDimensions === void 0 ? {} : { originalDimensions: ref.originalDimensions }
+		},
+		sha256,
+		identicalToPrevious
 	};
 }
 function renderScreenshotBlocks(value) {
 	const dup = value.identicalToPrevious ? "（与上一张截图哈希相同，疑似页面未刷新；请 browser_open 重开场景后重试）" : "";
+	const original = value.image.originalDimensions;
+	const scaled = original === void 0 ? "" : `（原图 ${original.width}x${original.height}，已按宿主预算缩放）`;
 	return [{
 		type: "text",
-		text: `<type>screenshot</type>\n<content>\n${value.image.mediaType}, ${value.image.width}x${value.image.height} px, ${value.image.bytes} bytes, sha256 ${value.sha256.slice(0, 12)}${dup}\n</content>`
+		text: `<type>screenshot</type>\n<content>\n${value.image.mediaType}, ${value.image.width}x${value.image.height} px${scaled}, ${value.image.bytes} bytes, sha256 ${value.sha256.slice(0, 12)}${dup}\n</content>`
 	}, {
 		type: "image",
 		attachment: imageRefFromValue(value.image)
@@ -380,7 +422,7 @@ function registerBrowserTools(ctx) {
 							},
 							mediaType: {
 								type: "string",
-								enum: ["image/png"],
+								enum: [...SCREENSHOT_MEDIA_TYPES],
 								required: true
 							},
 							bytes: {
@@ -395,7 +437,21 @@ function registerBrowserTools(ctx) {
 								type: "integer",
 								required: true
 							},
-							name: { type: "string" }
+							name: { type: "string" },
+							originalDimensions: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									width: {
+										type: "number",
+										required: true
+									},
+									height: {
+										type: "number",
+										required: true
+									}
+								}
+							}
 						}
 					},
 					sha256: {
@@ -414,19 +470,7 @@ function registerBrowserTools(ctx) {
 			await assertImageCapable(ctx, exec);
 			return driver.withScenario(async (scenario) => {
 				const shot = await scenario.screenshot({ fullPage: args.fullPage });
-				const ref = await saveScreenshot(ctx, shot.data, args.name);
-				return {
-					image: {
-						attachmentId: String(ref.attachmentId),
-						mediaType: "image/png",
-						bytes: ref.bytes,
-						width: ref.width,
-						height: ref.height,
-						...ref.name === void 0 ? {} : { name: ref.name }
-					},
-					sha256: shot.sha256,
-					identicalToPrevious: shot.identicalToPrevious
-				};
+				return screenshotValueFrom(await saveScreenshot(ctx, shot.data, args.name), shot.sha256, shot.identicalToPrevious);
 			});
 		}
 	}));

package/lib/types/attachments.d.ts

@@ -7,6 +7,13 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment';
 import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+/**
+ * Formats a stored screenshot can carry: Playwright captures PNG, and the
+ * attachment store re-encodes above its normalization budget (JPEG, or WebP
+ * when the source keeps alpha). Every entry is a possible store fact — never
+ * assume PNG.
+ */
+export declare const SCREENSHOT_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
 export interface ScreenshotImage {
     attachmentId: string;
     mediaType: ImageMediaType;
@@ -14,6 +21,11 @@ export interface ScreenshotImage {
     width: number;
     height: number;
     name?: string;
+    /** Present only when the store downscaled the capture; the pre-scaling pixels. */
+    originalDimensions?: {
+        width: number;
+        height: number;
+    };
 }
 export interface ScreenshotValue {
     image: ScreenshotImage;
@@ -21,6 +33,19 @@ export interface ScreenshotValue {
     identicalToPrevious: boolean;
 }
 export declare function imageRefFromValue(image: ScreenshotImage): ImageAttachmentRef;
+/**
+ * Build the tool value from the store reference alone. Every fact — format,
+ * byte length, dimensions — is copied from what the store actually published,
+ * because the read path re-derives them from the stored bytes and rejects any
+ * reference that disagrees. Restating a constant here (e.g. PNG for a capture
+ * the store normalized to JPEG) writes a self-contradicting attachment
+ * reference into immutable history, which fails every later model request.
+ * @param ref - reference returned by `saveImage`.
+ * @param sha256 - digest of the captured bytes.
+ * @param identicalToPrevious - whether this capture repeated the previous one.
+ * @returns the tool-facing value projected into the model context.
+ */
+export declare function screenshotValueFrom(ref: ImageAttachmentRef, sha256: string, identicalToPrevious: boolean): ScreenshotValue;
 export declare function renderScreenshotBlocks(value: ScreenshotValue): ContentBlock[];
 /** Persist screenshot bytes, mapping store refusals to actionable errors. */
 export declare function saveScreenshot(ctx: Context, data: Buffer, name: string | undefined): Promise<ImageAttachmentRef>;

package/lib/types/browser/discover.d.ts

@@ -3,7 +3,7 @@
  * filesystem probing is injected so every branch is unit-testable.
  * @module dsh-browser-verify/browser/discover
  */
-export type BrowserKind = 'headless-shell' | 'chromium' | 'custom';
+export type BrowserKind = 'headless-shell' | 'chromium' | 'custom' | 'system';
 /** Revision numbers verified against the matching playwright-core browsers.json. */
 export declare const KNOWN_REVISIONS: Readonly<Record<number, string>>;
 export interface DiscoveredBrowser {
@@ -19,7 +19,14 @@ export interface DiscoverOptions {
     exists?: (path: string) => boolean;
     /** Directory listing of cacheDir; defaults to readdirSync(cacheDir) (throws → treated as missing). */
     entries?: string[];
+    /** System-browser candidate paths; defaults to common install locations + PATH commands. */
+    systemCandidates?: string[];
+    pathEnv?: string;
 }
+/** Common install locations for system Chromium-based browsers, per platform. */
+export declare function systemBrowserCandidates(platform?: string, home?: string): string[];
+/** Resolve a command name on $PATH using the injected exists probe (no exec). */
+export declare function resolveCommandOnPath(command: string, pathEnv: string | undefined, exists: (path: string) => boolean, sep?: string): string | null;
 /** Default cache location on macOS. */
 export declare function defaultCacheDir(): string;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-browser-verify",
   "description": "Read-only browser verification tools for the DeepSeek Harness web GUI: browser_open / browser_mock / browser_assert / browser_screenshot — verify a page (H5/desktop) in ≤4 tool calls with mock interception, DOM assertions, and screenshots that auto-project into the model context.",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "packageManager": "pnpm@11.7.0",
   "engines": {

package/src/attachments.ts

@@ -10,6 +10,16 @@ import type { ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attach
 import { AttachmentError, AttachmentId } from '@deepseek-ai/dsh-attachment'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 
+/**
+ * Formats a stored screenshot can carry: Playwright captures PNG, and the
+ * attachment store re-encodes above its normalization budget (JPEG, or WebP
+ * when the source keeps alpha). Every entry is a possible store fact — never
+ * assume PNG.
+ */
+export const SCREENSHOT_MEDIA_TYPES = [
+  'image/png', 'image/jpeg', 'image/webp', 'image/gif',
+] as const satisfies readonly ImageMediaType[]
+
 export interface ScreenshotImage {
   attachmentId: string
   mediaType: ImageMediaType
@@ -17,6 +27,8 @@ export interface ScreenshotImage {
   width: number
   height: number
   name?: string
+  /** Present only when the store downscaled the capture; the pre-scaling pixels. */
+  originalDimensions?: { width: number; height: number }
 }
 
 export interface ScreenshotValue {
@@ -33,6 +45,39 @@ export function imageRefFromValue(image: ScreenshotImage): ImageAttachmentRef {
     width: image.width,
     height: image.height,
     ...image.name === undefined ? {} : { name: image.name },
+    ...image.originalDimensions === undefined ? {} : { originalDimensions: image.originalDimensions },
+  }
+}
+
+/**
+ * Build the tool value from the store reference alone. Every fact — format,
+ * byte length, dimensions — is copied from what the store actually published,
+ * because the read path re-derives them from the stored bytes and rejects any
+ * reference that disagrees. Restating a constant here (e.g. PNG for a capture
+ * the store normalized to JPEG) writes a self-contradicting attachment
+ * reference into immutable history, which fails every later model request.
+ * @param ref - reference returned by `saveImage`.
+ * @param sha256 - digest of the captured bytes.
+ * @param identicalToPrevious - whether this capture repeated the previous one.
+ * @returns the tool-facing value projected into the model context.
+ */
+export function screenshotValueFrom(
+  ref: ImageAttachmentRef,
+  sha256: string,
+  identicalToPrevious: boolean,
+): ScreenshotValue {
+  return {
+    image: {
+      attachmentId: String(ref.attachmentId),
+      mediaType: ref.mediaType,
+      bytes: ref.bytes,
+      width: ref.width,
+      height: ref.height,
+      ...ref.name === undefined ? {} : { name: ref.name },
+      ...ref.originalDimensions === undefined ? {} : { originalDimensions: ref.originalDimensions },
+    },
+    sha256,
+    identicalToPrevious,
   }
 }
 
@@ -40,10 +85,12 @@ export function renderScreenshotBlocks(value: ScreenshotValue): ContentBlock[] {
   const dup = value.identicalToPrevious
     ? '（与上一张截图哈希相同，疑似页面未刷新；请 browser_open 重开场景后重试）'
     : ''
+  const original = value.image.originalDimensions
+  const scaled = original === undefined ? '' : `（原图 ${original.width}x${original.height}，已按宿主预算缩放）`
   return [
     {
       type: 'text',
-      text: `<type>screenshot</type>\n<content>\n${value.image.mediaType}, ${value.image.width}x${value.image.height} px, ${value.image.bytes} bytes, sha256 ${value.sha256.slice(0, 12)}${dup}\n</content>`,
+      text: `<type>screenshot</type>\n<content>\n${value.image.mediaType}, ${value.image.width}x${value.image.height} px${scaled}, ${value.image.bytes} bytes, sha256 ${value.sha256.slice(0, 12)}${dup}\n</content>`,
     },
     { type: 'image', attachment: imageRefFromValue(value.image) },
   ]

package/src/browser/discover.ts

@@ -8,7 +8,7 @@ import { existsSync, readdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
-export type BrowserKind = 'headless-shell' | 'chromium' | 'custom'
+export type BrowserKind = 'headless-shell' | 'chromium' | 'custom' | 'system'
 
 /** Revision numbers verified against the matching playwright-core browsers.json. */
 export const KNOWN_REVISIONS: Readonly<Record<number, string>> = {
@@ -29,6 +29,9 @@ export interface DiscoverOptions {
   exists?: (path: string) => boolean
   /** Directory listing of cacheDir; defaults to readdirSync(cacheDir) (throws → treated as missing). */
   entries?: string[]
+  /** System-browser candidate paths; defaults to common install locations + PATH commands. */
+  systemCandidates?: string[]
+  pathEnv?: string
 }
 
 const SUBDIRS: Readonly<Record<'headless-shell' | 'chromium', string>> = {
@@ -41,6 +44,55 @@ const LIST_PREFIXES: Readonly<Array<{ kind: 'headless-shell' | 'chromium'; prefi
   { kind: 'chromium', prefix: 'chromium-' },
 ]
 
+/** PATH command names probed as a last-resort system-browser fallback. */
+const SYSTEM_COMMANDS = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome', 'chrome.exe']
+
+/** Common install locations for system Chromium-based browsers, per platform. */
+export function systemBrowserCandidates(platform: string = process.platform, home: string = homedir()): string[] {
+  if (platform === 'win32') {
+    return [
+      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+      'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+    ]
+  }
+  if (platform === 'linux') {
+    return [
+      '/usr/bin/google-chrome',
+      '/usr/bin/google-chrome-stable',
+      '/usr/bin/chromium',
+      '/usr/bin/chromium-browser',
+      '/usr/bin/chrome',
+      '/snap/bin/chromium',
+      '/snap/bin/google-chrome',
+    ]
+  }
+  // darwin (and anything else unix-like): app bundles in system + user Applications.
+  const apps = [
+    'Google Chrome.app/Contents/MacOS/Google Chrome',
+    'Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    'Chromium.app/Contents/MacOS/Chromium',
+  ]
+  return apps.flatMap(app => [`/Applications/${app}`, join(home, 'Applications', app)])
+}
+
+/** Resolve a command name on $PATH using the injected exists probe (no exec). */
+export function resolveCommandOnPath(
+  command: string,
+  pathEnv: string | undefined,
+  exists: (path: string) => boolean,
+  sep: string = process.platform === 'win32' ? ';' : ':',
+): string | null {
+  if (pathEnv === undefined || pathEnv === '') return null
+  for (const dir of pathEnv.split(sep)) {
+    if (dir === '') continue
+    const candidate = join(dir, command)
+    if (exists(candidate)) return candidate
+  }
+  return null
+}
+
 /** Default cache location on macOS. */
 export function defaultCacheDir(): string {
   return join(homedir(), 'Library', 'Caches', 'ms-playwright')
@@ -81,24 +133,45 @@ export function discoverBrowser(opts: DiscoverOptions = {}): DiscoveredBrowser {
       list = null
     }
   }
-  if (list === null) {
-    throw new Error(`browser-verify: 未找到浏览器缓存目录 ${cacheDir}。请先安装：npx playwright install chromium（需 playwright-core@1.62.0），或设置 DSH_BROWSER_VERIFY_CHROMIUM=<完整路径>。`)
-  }
-  for (const { kind, prefix } of LIST_PREFIXES) {
-    const revision = maxRevision(list, prefix)
-    if (revision === null) continue
-    const executablePath = join(cacheDir, `${kind === 'headless-shell' ? `chromium_headless_shell-${revision}` : `chromium-${revision}`}`, SUBDIRS[kind])
-    if (!exists(executablePath)) {
-      throw new Error(`browser-verify: 缓存目录存在 ${prefix}${revision} 但可执行文件缺失（${cacheDir}）。请删除该目录后重新执行 npx playwright install chromium。`)
+  if (list !== null) {
+    for (const { kind, prefix } of LIST_PREFIXES) {
+      const revision = maxRevision(list, prefix)
+      if (revision === null) continue
+      const executablePath = join(cacheDir, `${kind === 'headless-shell' ? `chromium_headless_shell-${revision}` : `chromium-${revision}`}`, SUBDIRS[kind])
+      if (!exists(executablePath)) {
+        throw new Error(`browser-verify: 缓存目录存在 ${prefix}${revision} 但可执行文件缺失（${cacheDir}）。请删除该目录后重新执行 npx playwright install chromium。`)
+      }
+      const known = KNOWN_REVISIONS[revision] !== undefined
+      return {
+        executablePath,
+        kind,
+        revision,
+        known,
+        versionHint: known ? null : `浏览器 revision ${revision} 不在已认证表（playwright-core 1.62.0 认证 ${Object.keys(KNOWN_REVISIONS).join('/')}）；若协议异常，请安装匹配版本`,
+      }
     }
-    const known = KNOWN_REVISIONS[revision] !== undefined
+  }
+  // Cache had nothing usable → last-resort system browser (zero download).
+  const system = findSystemBrowser(opts, exists)
+  if (system !== null) return system
+  throw new Error(`browser-verify: 未找到可用的浏览器（已探测：playwright 缓存 ${cacheDir} 与系统 Chrome/Chromium/Edge 常见路径）。请执行一次 npx playwright install chromium 后重试，或用 DSH_BROWSER_VERIFY_CHROMIUM 指定已有二进制。`)
+}
+
+/** First existing system-browser candidate, or null. */
+function findSystemBrowser(opts: DiscoverOptions, exists: (path: string) => boolean): DiscoveredBrowser | null {
+  const candidates = opts.systemCandidates ?? [
+    ...systemBrowserCandidates(),
+    ...SYSTEM_COMMANDS.map(cmd => resolveCommandOnPath(cmd, opts.pathEnv ?? process.env.PATH, exists)).filter((p): p is string => p !== null),
+  ]
+  for (const candidate of candidates) {
+    if (!exists(candidate)) continue
     return {
-      executablePath,
-      kind,
-      revision,
-      known,
-      versionHint: known ? null : `浏览器 revision ${revision} 不在已认证表（playwright-core 1.62.0 认证 ${Object.keys(KNOWN_REVISIONS).join('/')}）；若协议异常，请安装匹配版本`,
+      executablePath: candidate,
+      kind: 'system',
+      revision: 0,
+      known: false,
+      versionHint: `系统浏览器（未与插件认证版本 ${Object.keys(KNOWN_REVISIONS).join('/')} 对齐）；若渲染异常，请执行 npx playwright install chromium 安装匹配版本`,
     }
   }
-  throw new Error(`browser-verify: 未找到浏览器二进制。请先安装：npx playwright install chromium（需 playwright-core@1.62.0），或设置 DSH_BROWSER_VERIFY_CHROMIUM=<完整路径>。`)
+  return null
 }

package/src/tools/index.ts

@@ -7,7 +7,7 @@
 import type { Context } from '@deepseek-ai/cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { BrowserDriver } from '../browser/driver.ts'
-import { assertImageCapable, renderScreenshotBlocks, saveScreenshot } from '../attachments.ts'
+import { assertImageCapable, renderScreenshotBlocks, saveScreenshot, SCREENSHOT_MEDIA_TYPES, screenshotValueFrom } from '../attachments.ts'
 import { withTimeout } from './timeout.ts'
 
 /** Parse a positive-integer env var; NaN/zero/negative falls back to the default. */
@@ -150,11 +150,19 @@ export function registerBrowserTools(ctx: Context): void {
             required: true,
             properties: {
               attachmentId: { type: 'string', required: true },
-              mediaType: { type: 'string', enum: ['image/png'], required: true },
+              mediaType: { type: 'string', enum: [...SCREENSHOT_MEDIA_TYPES], required: true },
               bytes: { type: 'integer', required: true },
               width: { type: 'integer', required: true },
               height: { type: 'integer', required: true },
               name: { type: 'string' },
+              originalDimensions: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  width: { type: 'number', required: true },
+                  height: { type: 'number', required: true },
+                },
+              },
             },
           },
           sha256: { type: 'string', required: true },
@@ -168,18 +176,8 @@ export function registerBrowserTools(ctx: Context): void {
       return driver.withScenario(async scenario => {
         const shot = await scenario.screenshot({ fullPage: args.fullPage })
         const ref = await saveScreenshot(ctx, shot.data, args.name)
-        return {
-          image: {
-            attachmentId: String(ref.attachmentId),
-            mediaType: 'image/png' as const,
-            bytes: ref.bytes,
-            width: ref.width,
-            height: ref.height,
-            ...ref.name === undefined ? {} : { name: ref.name },
-          },
-          sha256: shot.sha256,
-          identicalToPrevious: shot.identicalToPrevious,
-        }
+        // Facts come from the store ref: a normalized capture is no longer a PNG.
+        return screenshotValueFrom(ref, shot.sha256, shot.identicalToPrevious)
       })
     },
   }))