dsh-browser-view 0.1.1 → 0.2.0

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

@@ -0,0 +1,13 @@
+export declare function toCsv(rows: Record<string, unknown>[]): string;
+export declare function toJsonl(rows: Record<string, unknown>[]): string;
+export declare function toMarkdownTable(rows: Record<string, unknown>[]): string;
+/** 按格式序列化抽取结果(json 为 pretty JSON 字符串)。 */
+export declare function serializeRows(rows: Record<string, unknown>[], format: string): string;
+/** 由文件扩展名推断序列化格式(显式 format 优先)。 */
+export declare function formatFromFile(file: string): string | null;
+/**
+ * 解析 CSV 文本为行对象数组(首行为表头;支持引号包裹、双引号转义、
+ * 逗号/换行内嵌)。供 browser_replay 的 dataFile 使用。
+ */
+export declare function parseCsv(text: string): Record<string, string>[];
+//# sourceMappingURL=extract.d.ts.map

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

@@ -1,14 +1,12 @@
+import type { ReplayStep } from "./types.js";
 /** 录制存储目录($DSH_HOME/.dsh-browser/recordings)。 */
 export declare function recordingsDir(): string;
 /** 名字安全化:只保留字母数字 . _ -,连续点压成下划线防路径穿越。 */
 export declare function safeName(name: string): string;
 /** 加载目录下所有 .json 录制进内存表;返回加载数量。坏文件静默跳过。 */
 export declare function loadRecordings(): number;
-/** 写一个录制到磁盘(原子替换);返回文件路径。 */
-export declare function saveRecordingFile(name: string, steps: {
-    tool: string;
-    args: any;
-}[]): string;
+/** 写一个录制到磁盘(原子替换);返回文件路径。formatVersion 2 起步骤可带 meta(选择器指纹)与 {{var}} 占位符。 */
+export declare function saveRecordingFile(name: string, steps: ReplayStep[]): string;
 /** 删除磁盘上的录制文件;返回是否存在并删除。 */
 export declare function deleteRecordingFile(name: string): boolean;
 /** 录制列表(面板 / browser_record list 共用)。 */
@@ -21,10 +19,7 @@ export declare function listRecordings(): Array<{
 /** 录制详情(面板展开查看步骤)。 */
 export declare function recordingDetail(name: string): {
     name: string;
-    steps: {
-        tool: string;
-        args: any;
-    }[];
+    steps: ReplayStep[];
 } | undefined;
 /** 删除录制(内存 + 磁盘同步);返回是否存在并删除。 */
 export declare function deleteRecording(name: string): boolean;

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

@@ -0,0 +1,42 @@
+/** 一步的执行结果(与 runReplay results 条目同形,外加自愈标记)。 */
+export interface RunStepResult {
+    index: number;
+    tool: string;
+    ok: boolean;
+    error?: string;
+    healed?: boolean;
+    via?: string;
+    resolved?: string;
+}
+/** 一次 replay/batch 的运行记录。 */
+export interface RunRecord {
+    runId: string;
+    ts: number;
+    kind: "replay" | "batch";
+    source: string;
+    total: number;
+    passed: number;
+    failed: number;
+    healedCount: number;
+    durationMs: number;
+    /** data 数据集模式时的行号(单次运行为 undefined)。 */
+    row?: number;
+    results: RunStepResult[];
+}
+/** 报告存储目录($DSH_HOME/.dsh-browser/reports)。 */
+export declare function reportsDir(): string;
+/** 生成 runId:YYYYMMDD-HHmmss-随机4位。 */
+export declare function makeRunId(ts: number): string;
+/** 追加一条运行记录;超限时截断旧行(原子替换)。 */
+export declare function appendRun(record: RunRecord): void;
+/** 读取全部运行记录(按时间倒序);坏行静默跳过。 */
+export declare function listRuns(limit?: number): RunRecord[];
+/** 最近一次运行(无记录返回 null)。 */
+export declare function latestRun(): RunRecord | null;
+/** 按 runId 取单条记录。 */
+export declare function getRun(runId: string): RunRecord | null;
+/** 生成 Markdown 回归报告。 */
+export declare function renderMarkdownReport(runs: RunRecord[], source?: string): string;
+/** 生成自包含 HTML 回归报告(内联样式,无外部资源)。 */
+export declare function renderHtmlReport(runs: RunRecord[], source?: string): string;
+//# sourceMappingURL=reports.d.ts.map

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

@@ -1,5 +1,5 @@
 import type { Page } from "playwright-core";
-import type { BrowserConfig, ProfileState, DownloadEntry, FormField, NavEntry } from "./types.js";
+import type { BrowserConfig, ProfileState, DownloadEntry, FormField, NavEntry, RefEntry, ReplayStep, SelectorHint } from "./types.js";
 /** 当前活动 profile 名(默认 "default")。 */
 export declare let currentProfile: string;
 /** 多配置文件浏览器会话:name → 会话状态。 */
@@ -8,12 +8,15 @@ export declare const profileStates: Map<string, ProfileState>;
 export declare const savedForms: Map<string, FormField[]>;
 /** 最近一次 browser_form 填充的字段(供 browser_form_save 无参保存)。 */
 export declare let lastFormFields: FormField[];
+/** 记录一次 aria 快照分配的 ref(整表替换)。 */
+export declare function setPageRefs(page: Page, refs: Map<string, RefEntry>): void;
+/** 查询某个 ref 的定位信息;未注册返回 undefined。 */
+export declare function pageRef(page: Page, ref: string): RefEntry | undefined;
+/** 清空页面的 ref 表(导航/新快照时调用)。 */
+export declare function clearPageRefs(page: Page): void;
 /** 已保存的录制脚本:name → 步骤数组。 */
 export declare const savedRecordings: Map<string, {
-    steps: {
-        tool: string;
-        args: any;
-    }[];
+    steps: ReplayStep[];
     savedAt: number;
 }>;
 /** 一次工具调用的记录(操作轨迹 / 录制 / 回放共用)。 */
@@ -24,12 +27,18 @@ export interface TestCall {
     ms: number;
     ts: number;
     error?: string;
+    /** 录制时采集的选择器指纹(回放自愈用;register 包装层异步补齐)。 */
+    meta?: {
+        hint?: SelectorHint;
+    };
 }
 export declare function isRecording(): boolean;
 export declare function startRecording(): void;
 export declare function stopRecording(): TestCall[];
-/** 操作轨迹追加(同时写入录制 buffer,排除 record/replay 自身)。 */
-export declare function recordCall(call: TestCall): void;
+/** 最近一次完整录制(start→stop)的 buffer;从未录制过返回 null。 */
+export declare function lastRecordingOf(): TestCall[] | null;
+/** 操作轨迹追加(同时写入录制 buffer,排除 record/replay 自身)。返回存入的调用对象(供调用方补 meta)。 */
+export declare function recordCall(call: TestCall): TestCall;
 /** 操作轨迹(按时间倒序,最新在前)。 */
 export declare function testLogOf(): TestCall[];
 export declare function clearTestLog(): void;

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

@@ -1,12 +1,49 @@
-import type { Page } from "playwright-core";
+import type { Locator, Page } from "playwright-core";
 import type { ToolRunContext } from "../lib/types.js";
-import type { BrowserConfig } from "./types.js";
+import type { BrowserConfig, ReplayStep, SelectorHint } from "./types.js";
+import { type RunRecord } from "./reports.js";
+/** 读取 PNG 文件头(IHDR)中的宽高,不解码像素(导出供测试)。 */
+export declare function pngSize(buf: Buffer): {
+    width: number;
+    height: number;
+};
+/** 按缩放比例换算 mask 矩形(导出供测试;与页内比对共用同一套坐标语义)。 */
+export declare function scaleRects(rects: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}[], scale: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}[];
 export declare function openTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     url: string;
     title: string;
     status: string;
 }>;
+/**
+ * 快照文本压缩(导出供测试):
+ *   - 去掉首尾空白行;
+ *   - 连续空白行折叠为 1 行;
+ *   - 连续重复的非空行(表格空单元格/占位行产生的噪音)折叠为「首行 + …(重复 N 行)」。
+ * 只折叠完全相同的相邻行,不重排、不删改非重复内容。
+ */
+export declare function compressText(text: string): string;
 export declare function snapshotTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    tree: string;
+    truncated: boolean;
+    refs: number;
+    text?: undefined;
+    links?: undefined;
+    inputs?: undefined;
+} | {
+    url: string;
+    title: string;
     text: string;
     truncated: boolean;
     links: {
@@ -14,9 +51,15 @@ export declare function snapshotTool(config: BrowserConfig, args: Record<string,
         href: string;
     }[];
     inputs: number;
-    url: string;
-    title: string;
+    tree?: undefined;
+    refs?: undefined;
 }>;
+/**
+ * 解析点击/输入目标为 Locator:selector 直译;ref 走注册表——
+ * 先试快照时的 CSS 路径并校验 role/name 仍一致(防 ref 漂移误点),
+ * 不一致则降级 getByRole(role, {name}),均失败报「ref 已失效」。
+ */
+export declare function targetLocator(page: Page, args: Record<string, any>): Promise<Locator>;
 export declare function clickTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     url: string;
     title: string;
@@ -34,6 +77,17 @@ export declare function pressTool(config: BrowserConfig, args: Record<string, an
     title: string;
     pressed: string;
 }>;
+/**
+ * 下拉选择原语:原生 <select> 走 selectOption;组件库下拉(antd/element/listbox)
+ * 走「点击触发框 → 等待可见选项 → 按文本点击」。找不到选项时抛出错误并附当前可见
+ * 选项清单,agent 可直接据此修正,无需再手写 eval 探查。
+ */
+export declare function selectTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    selected: string;
+    selector: string;
+}>;
 export declare function evalTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     result: unknown;
 }>;
@@ -42,6 +96,13 @@ export declare function screenshotTool(config: BrowserConfig, args: Record<strin
     bytes: number;
     width: number;
     height: number;
+    baseline: string;
+} | {
+    path: string;
+    bytes: number;
+    width: number;
+    height: number;
+    baseline?: undefined;
 }>;
 export declare function waitTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     url: string;
@@ -189,6 +250,7 @@ export declare function profileTool(config: BrowserConfig, args: Record<string,
 export declare function elementsTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     count: number;
     elements: Record<string, unknown>[];
+    dropdownOptions: string[];
 }>;
 export declare function closeTool(): Promise<{
     closed: boolean;
@@ -231,24 +293,48 @@ export declare function waitForLoginTool(config: BrowserConfig, args: Record<str
     title: string;
     loggedIn: boolean;
 }>;
-/** 断言:条件在 timeoutMs 内成立则通过,否则失败并自动截图存证据。 */
+/** 断言:条件在 timeoutMs 内成立则通过,否则失败并自动截图存证据。visual 断言走像素比对。 */
 export declare function assertTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
     url: string;
     title: string;
     passed: boolean;
+    visual: {
+        baseline: string;
+        diffRatio: number;
+        diffPixels: number;
+    };
+} | {
+    url: string;
+    title: string;
+    passed: boolean;
 }>;
 /** 网络记录查询:list / failed / wait / clear。 */
 export declare function networkTool(args: Record<string, any>): Promise<{
     cleared: boolean;
-    entries: number;
+    entries: never[];
     matched?: undefined;
     waitMs?: undefined;
+    stats?: undefined;
     failed?: undefined;
 } | {
     matched: import("./session.js").NetworkEntry;
     waitMs: number;
     cleared?: undefined;
     entries?: undefined;
+    stats?: undefined;
+    failed?: undefined;
+} | {
+    stats: {
+        host: string;
+        total: number;
+        failed: number;
+        avgMs: number | null;
+        byStatus: Record<string, number>;
+    }[];
+    cleared?: undefined;
+    entries?: undefined;
+    matched?: undefined;
+    waitMs?: undefined;
     failed?: undefined;
 } | {
     failed: import("./session.js").NetworkEntry[];
@@ -256,20 +342,32 @@ export declare function networkTool(args: Record<string, any>): Promise<{
     entries?: undefined;
     matched?: undefined;
     waitMs?: undefined;
+    stats?: undefined;
 } | {
     entries: import("./session.js").NetworkEntry[];
     cleared?: undefined;
     matched?: undefined;
     waitMs?: undefined;
+    stats?: undefined;
     failed?: undefined;
 }>;
+/** 使用 args.selector 定位的工具集合(自愈与录制指纹的作用范围)。 */
+export declare const SELECTOR_STEP_TOOLS: Set<string>;
+/**
+ * 采集选择器指向元素的指纹(页内 evaluate;找不到元素返回 null)。
+ * 指纹是回放自愈的降级候选来源:testid / role+name / text / id / tag+text。
+ */
+export declare function captureSelectorHint(page: Page, selector: string): Promise<SelectorHint | null>;
+/** 由指纹生成自愈降级候选(按优先级排序;导出供测试)。 */
+export declare function healCandidates(hint: SelectorHint): {
+    via: string;
+    selector: string;
+}[];
 /** 录制管理:start / stop / save / list / delete。 */
 export declare function recordTool(args: Record<string, any>): Promise<{
     recording: boolean;
     hint: string;
     steps?: undefined;
-    saved?: undefined;
-    file?: undefined;
     recordings?: undefined;
     deleted?: undefined;
     name?: undefined;
@@ -277,16 +375,18 @@ export declare function recordTool(args: Record<string, any>): Promise<{
     recording: boolean;
     steps: number;
     hint?: undefined;
-    saved?: undefined;
-    file?: undefined;
     recordings?: undefined;
     deleted?: undefined;
     name?: undefined;
 } | {
+    hint: string;
+    warnings?: string[] | undefined;
+    varsApplied?: number | undefined;
+    stripped?: number | undefined;
     saved: string;
     steps: number;
+    source: string;
     file: string;
-    hint: string;
     recording?: undefined;
     recordings?: undefined;
     deleted?: undefined;
@@ -301,8 +401,6 @@ export declare function recordTool(args: Record<string, any>): Promise<{
     recording?: undefined;
     hint?: undefined;
     steps?: undefined;
-    saved?: undefined;
-    file?: undefined;
     deleted?: undefined;
     name?: undefined;
 } | {
@@ -311,29 +409,129 @@ export declare function recordTool(args: Record<string, any>): Promise<{
     recording?: undefined;
     hint?: undefined;
     steps?: undefined;
-    saved?: undefined;
-    file?: undefined;
     recordings?: undefined;
 }>;
-/** 回放执行器(步骤 → 工具调用),由 register.ts 注入实现 map。 */
-export declare function runReplay(steps: {
-    tool: string;
-    args: any;
-}[], impls: Record<string, (args: any) => Promise<unknown>>, failFast: boolean): Promise<{
+/** 回放选项(自愈开关与单次尝试超时,来自 config)。 */
+export interface ReplayOptions {
+    healing?: boolean;
+    healTimeoutMs?: number;
+}
+/** 回放执行器(步骤 → 工具调用),由 register.ts 注入实现 map。支持选择器自愈。 */
+export declare function runReplay(steps: ReplayStep[], impls: Record<string, (args: any) => Promise<unknown>>, failFast: boolean, opts?: ReplayOptions): Promise<{
     total: number;
     passed: number;
     failed: number;
-    stoppedAt: number | null;
+    healedCount: number;
+    stoppedAt?: number;
     results: any[];
 }>;
-/** 回放入口:name(已保存录制)或 steps(数组)二选一。 */
-export declare function replayTool(args: Record<string, any>, impls: Record<string, (args: any) => Promise<unknown>>): Promise<{
+export interface ExtractField {
+    name: string;
+    selector: string;
+    attr?: string;
+    multiple?: boolean;
+    fields?: ExtractField[];
+}
+/**
+ * 把单页抽取结果规整为行数组:恰好一个顶层 multiple 字段时,其数组即行
+ * (行内嵌套对象为行,标量包装成 { [name]: value });否则整页算一行。
+ */
+export declare function rowsOfExtract(result: Record<string, any>, fields: ExtractField[]): Record<string, any>[];
+/** 工作区内落盘路径解析(拒绝穿越到工作区之外)。 */
+export declare function workspaceFilePath(cwd: string, file: string): string;
+/**
+ * 规则化抽取:fields 定义抽取结构,next 选择器驱动翻页(maxPages 上限),
+ * 行数超 maxRows 截断;format/file 控制序列化与落盘(json/csv/jsonl/markdown)。
+ */
+export declare function extractTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
+    url: string;
+    title: string;
+    file?: string | undefined;
+    bytes?: number | undefined;
+    truncated: boolean;
+    rows: Record<string, any>[];
+    count: number;
+    pages: number;
+    format: string;
+}>;
+/**
+ * 回归报告:list 列出最近运行,show 看单条详情,
+ * export 聚合生成 Markdown/HTML 报告落盘工作区。
+ */
+export declare function reportTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
+    runs: {
+        row?: number | undefined;
+        runId: string;
+        ts: number;
+        kind: "replay" | "batch";
+        source: string;
+        total: number;
+        passed: number;
+        failed: number;
+        healedCount: number;
+        durationMs: number;
+    }[];
+    run?: undefined;
+    file?: undefined;
+    bytes?: undefined;
+    format?: undefined;
+} | {
+    run: RunRecord;
+    runs?: undefined;
+    file?: undefined;
+    bytes?: undefined;
+    format?: undefined;
+} | {
+    file: string;
+    bytes: number;
+    runs: number;
+    format: string;
+    run?: undefined;
+}>;
+/**
+ * 动作批处理:一次调用顺序执行多个浏览器步骤(内核复用 runReplay),
+ * 减少「点击→等待→输入」类固定小序列的工具往返。步骤内禁止嵌套
+ * batch/replay/record;批整体在操作轨迹里记为一条 browser_batch。
+ */
+export declare function batchTool(args: Record<string, any>, impls: Record<string, (args: any) => Promise<unknown>>, config?: BrowserConfig): Promise<{
+    summary: string;
+    total: number;
+    passed: number;
+    failed: number;
+    healedCount: number;
+    stoppedAt?: number;
+    results: any[];
+}>;
+/** 收集步骤中所有 {{var}} 占位符名(导出供测试)。 */
+export declare function findPlaceholders(steps: ReplayStep[]): string[];
+/**
+ * 深拷贝步骤并替换字符串叶子里的 {{var}} 占位符(导出供测试)。
+ * vars 缺失的占位符保留原样(由调用方先 findPlaceholders 校验)。
+ */
+export declare function substituteVars(steps: ReplayStep[], vars: Record<string, unknown>): ReplayStep[];
+/**
+ * 回放入口:name(已保存录制)或 steps(数组)二选一。
+ * vars 注入 {{占位符}};data/dataFile 数据集模式逐行运行并聚合。
+ */
+export declare function replayTool(args: Record<string, any>, impls: Record<string, (args: any) => Promise<unknown>>, config?: BrowserConfig, exec?: ToolRunContext): Promise<{
+    source: string;
+    rows: number;
+    passedRows: number;
+    failedRows: number;
+    runs: any[];
+    summary: string;
+} | {
     summary: string;
     total: number;
     passed: number;
     failed: number;
-    stoppedAt: number | null;
+    healedCount: number;
+    stoppedAt?: number;
     results: any[];
     source: string;
+    rows?: undefined;
+    passedRows?: undefined;
+    failedRows?: undefined;
+    runs?: undefined;
 }>;
 //# sourceMappingURL=tools.d.ts.map

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

@@ -8,6 +8,8 @@ export interface BrowserConfig {
     profiles?: Record<string, Partial<BrowserConfig>>;
     screenshotDir?: string;
     downloadDir?: string;
+    /** 截图/下载/上传的落盘基准目录(默认探测会话 cwd;显式指定后优先)。 */
+    workspaceDir?: string;
     /** 截图保留天数(0 = 不按时间清理)。 */
     screenshotMaxAgeDays?: number;
     /** 截图保留数量上限(0 = 不按数量清理)。 */
@@ -19,6 +21,16 @@ export interface BrowserConfig {
     maxTextChars?: number;
     maxLinks?: number;
     timeoutMs?: number;
+    /** 视觉回归基线截图目录(默认 .dsh-browser/baselines,不受截图清理策略约束)。 */
+    baselineDir?: string;
+    /** 回放/批处理时的选择器自愈(默认 true;只作用于失败路径,live 工具不受影响)。 */
+    selectorHealing?: boolean;
+    /** 自愈时单次尝试的超时毫秒(默认 3000,避免等满全局超时)。 */
+    healTimeoutMs?: number;
+    /** ARIA 快照每次分配的最大 ref 数(默认 200)。 */
+    maxRefs?: number;
+    /** browser_extract 单次最多聚合的行数(默认 1000)。 */
+    maxRows?: number;
 }
 /** 一个命名 profile 的会话状态。 */
 export interface ProfileState {
@@ -52,4 +64,28 @@ export interface FormField {
     label?: string;
     value?: string;
 }
+/** ARIA 快照分配的 ref 注册项(ref → 定位信息)。 */
+export interface RefEntry {
+    role: string;
+    name: string;
+    /** 生成快照时计算的稳定 CSS 路径(优先 #id / [data-testid] / nth-of-type 链)。 */
+    selector: string;
+}
+/** 录制时采集的选择器指纹(回放自愈的降级候选来源)。 */
+export interface SelectorHint {
+    testid?: string;
+    role?: string;
+    name?: string;
+    id?: string;
+    text?: string;
+    tag?: string;
+}
+/** 录制/回放的一步(formatVersion 2 起支持 meta.hint 选择器指纹)。 */
+export interface ReplayStep {
+    tool: string;
+    args: any;
+    meta?: {
+        hint?: SelectorHint;
+    };
+}
 //# sourceMappingURL=types.d.ts.map

package/lib/types/client/index.d.ts

@@ -1,16 +1,26 @@
 /**
- * dsh-browser browser half: a "浏览器" page in the official dsh settings
- * dialog (settings.section seat) that manages saved browser recordings —
- * list, expand steps, delete. Data flows to the node half through the
- * plugin's own same-origin HTTP endpoints (base path discovered from
- * /__dsh-browser__/config).
+ * dsh-browser-view client half:
+ * 1. "settings.section" -> A "🌐 浏览器" page in the official dsh settings
+ *    dialog managing saved browser recordings with polished header & icon.
+ * 2. "shell.overlay" -> Universal floating widget (FAB + live screenshot
+ *    thumbnail panel + full-size inspection modal) rendered natively in both
+ *    Electron desktop and web client.
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        'shell.overlay': {
+            kind: 'list';
+            scope: 'root';
+        };
+    }
+}
 /** Required services (cordis fiber inject). */
 export declare const inject: string[];
 /**
- * Register the "浏览器" settings page: nav entry + recordings management.
- * @param ctx - the browser plugin context.
+ * Register the browser extension components:
+ * 1. settings.section -> "🌐 浏览器" page in settings
+ * 2. shell.overlay -> Universal floating live screenshot widget (Desktop & Web)
  */
 export declare function apply(ctx: ClientContext): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/lib/tools.d.ts

@@ -1,9 +1,20 @@
 import type { PlainToolDefinition, ToolRunContext } from "./types.js";
+/** 注入日志函数(插件 apply 时调用一次)。 */
+export declare function setToolsLogger(fn: ((message: string) => void) | null): void;
 /**
  * Resolve the workspace working directory for one tool execution.
  * Prefers the calling agent's session cwd; falls back to the host process cwd.
  */
 export declare function workspaceCwd(exec: ToolRunContext | undefined): string;
+/**
+ * 截图/下载/上传等文件的落盘基准目录:
+ *   1. config.workspaceDir 显式指定(相对路径按 process.cwd() 解析)——最高优先;
+ *   2. 会话 cwd 探测链(workspaceCwd);
+ * 首次解析打一次日志,记录来源,便于诊断「文件落错位置」类问题。
+ */
+export declare function workspaceBaseDir(config: {
+    workspaceDir?: string;
+}, exec: ToolRunContext | undefined): string;
 /** definePlainTool 的输入选项。 */
 export interface PlainToolOptions {
     name: string;

package/lib/types/lib/types.d.ts

@@ -29,6 +29,8 @@ export interface ToolRunContext {
             };
         };
     };
+    /** 部分宿主直接给执行上下文挂 cwd(次于 session.meta.cwd 的候选)。 */
+    cwd?: string;
     callId?: string;
 }
 /** 规范化工具输出契约。 */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-browser-view",
-  "version": "0.1.1",
-  "description": "DSH 插件:共享 Playwright 浏览器自动化(27 个 browser_* 工具)+ 原生界面实时画面面板 + 官方设置弹窗内的浏览器录制管理。仅依赖 playwright-core,不依赖任何 @deepseek-ai 运行时包。",
+  "version": "0.2.0",
+  "description": "DSH 插件:共享 Playwright 浏览器自动化(31 个 browser_* 工具,含 ARIA ref 交互、批处理、视觉回归、选择器自愈、参数化回放、结构化抽取与回归报告)+ 原生界面实时画面面板 + 官方设置弹窗内的浏览器录制管理。仅依赖 playwright-core,不依赖任何 @deepseek-ai 运行时包。",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/types/index.d.ts",