dsh-browser-view 0.1.2 → 0.3.0

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

@@ -1,22 +1,132 @@
-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, RefEntry, 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;
 }>;
-export declare function snapshotTool(config: BrowserConfig, args: Record<string, any>): Promise<{
-    text: string;
+/**
+ * 快照文本压缩(导出供测试):
+ *   - 去掉首尾空白行;
+ *   - 连续空白行折叠为 1 行;
+ *   - 连续重复的非空行(表格空单元格/占位行产生的噪音)折叠为「首行 + …(重复 N 行)」。
+ * 只折叠完全相同的相邻行,不重排、不删改非重复内容。
+ */
+export declare function compressText(text: string): string;
+/** 最长公共子串长度(小写比较;零依赖,导出供测试)。 */
+export declare function lcsScore(a: string, b: string): number;
+/** 零命中时按相似度挑 top5 候选(导出供测试)。 */
+export declare function topSuggestions(query: string, candidates: {
+    role: string;
+    name: string;
+}[], count?: number): {
+    role: string;
+    name: string;
+    score: number;
+}[];
+/**
+ * 为命中元素增量分配 ref:沿用既有注册表的编号继续(不与上次快照冲突),
+ * 合并写回;返回带 ref 的命中列表(上限 maxRefs,超出标 truncated)。
+ * 导出供测试(纯逻辑,不依赖浏览器)。
+ */
+export declare function assignRefs(existing: Map<string, RefEntry>, matches: {
+    role: string;
+    name: string;
+    selector: string;
+    ancestors: string[];
+}[], maxRefs: number): {
+    withRefs: {
+        ref: string;
+        role: string;
+        name: string;
+        selector: string;
+        ancestors: string[];
+    }[];
+    merged: Map<string, RefEntry>;
     truncated: boolean;
-    links: {
-        text: string;
-        href: string;
+};
+/**
+ * 语义元素定位:按名称(或 id/data-testid)在可交互元素中查找,只返回命中的
+ * ref + 区域上下文,不输出全量 aria 树 —— 大页面定位单个目标时 token 开销
+ * 远小于 browser_snapshot { mode: "aria" }。返回的 ref 可直接用于
+ * click/type/select/press。零命中不抛错,附最相近候选供二次定位。
+ */
+export declare function findTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    scanned: number;
+    url: string;
+    title: string;
+    truncated?: true | undefined;
+    suggestions?: {
+        role: string;
+        name: string;
+        score: number;
+    }[] | undefined;
+    found: number;
+    matches: {
+        ref: string;
+        role: string;
+        name: string;
+        ancestors: string[];
     }[];
-    inputs: number;
+}>;
+/**
+ * 行级 diff:掐掉公共前缀/后缀,返回变化区。导出供测试。
+ * 全等返回 { unchanged: true };否则 changedFrom 为新文本中变化区首行(1 起)。
+ */
+export declare function diffLines(oldText: string, newText: string): {
+    unchanged: boolean;
+    changedFrom?: number;
+    lines?: string[];
+    removed?: number;
+};
+export declare function snapshotTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     url: string;
     title: string;
+    scope?: string | undefined;
+    unchanged: boolean;
+    contentVersion: number;
+} | {
+    url: string;
+    title: string;
+    truncated: boolean;
+    scope?: string | undefined;
+    diff: boolean;
+    contentVersion: number;
+    changedFrom: number | undefined;
+    removed: number | undefined;
+} | {
+    url: string;
+    title: string;
+    truncated: boolean;
+    scope?: string | undefined;
+    stale?: boolean | undefined;
+    contentVersion: number;
 }>;
+/**
+ * 解析点击/输入目标为 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 +144,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 +163,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;
@@ -56,6 +184,95 @@ export declare function reloadTool(config: BrowserConfig): Promise<{
     url: string;
     title: string;
 }>;
+/** 一项诊断结果(ok=false 时附 advice 修复建议)。导出供测试。 */
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+    advice?: string;
+}
+export declare function setDoctorProbe(fn: ((basePath: string) => Promise<{
+    ok: boolean;
+    detail: string;
+    advice?: string;
+}>) | null): void;
+/** 目录可写性检查(mkdir + 写探针文件 + 删除)。导出供测试。 */
+export declare function checkWritableDir(dir: string): {
+    ok: boolean;
+    detail: string;
+};
+/** 可执行文件存在性检查(executablePath 显式配置用)。导出供测试。 */
+export declare function checkExecutable(path: string): DoctorCheck;
+/**
+ * 命名隔离上下文:同一浏览器进程内独立 cookies/storage 的"标签组"。
+ * 页注册进 profile 标签表(所有既有工具直接可用),context 只做归属记录:
+ * list / new(name?, url?) / switch(激活该组的一页,没有则新开) / close(整组关闭)。
+ * 持久模式(userDataDir)浏览器只有单一 context,不支持本工具(用 profiles 替代)。
+ */
+export declare function contextTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    contexts: {
+        name: string;
+        pages: number;
+        active: boolean;
+        createdAt: number;
+    }[];
+    profile: string;
+    closed?: undefined;
+    remainingTabs?: undefined;
+} | {
+    url: string;
+    title: string;
+    navigated?: string | undefined;
+    created: string;
+    contexts?: undefined;
+    profile?: undefined;
+    closed?: undefined;
+    remainingTabs?: undefined;
+} | {
+    url: string;
+    title: string;
+    switched: string;
+    contexts?: undefined;
+    profile?: undefined;
+    closed?: undefined;
+    remainingTabs?: undefined;
+} | {
+    url: string;
+    title: string;
+    switched: string;
+    pages: number;
+    contexts?: undefined;
+    profile?: undefined;
+    closed?: undefined;
+    remainingTabs?: undefined;
+} | {
+    closed: string;
+    remainingTabs: number;
+    contexts?: undefined;
+    profile?: undefined;
+}>;
+/**
+ * 页内拾取器(evaluate 注入):一次性 click 捕获 —— 点击任意元素时阻止默认行为,
+ * 计算稳定 CSS 路径 + 元素信息存 window.__dshPickResult(面板轮询读取后自清)。
+ * 与 aria walker 的 cssPath 同一套语义(#id → [data-testid] → nth-of-type 链)。
+ */
+export declare function pickElementInjector(): void;
+/** 读取并清空拾取结果(ui.ts /pick GET 调用;无结果返回 null)。 */
+export declare function takePickResult(page: Page): Promise<Record<string, unknown> | null>;
+/**
+ * 操作预告高亮:agent 即将 click/type/select/press 的元素在页面上琥珀色描边
+ * ~1.5 秒。异步不阻塞(fire-and-forget,任何失败静默),不影响操作时序。
+ */
+export declare function previewHighlight(page: Page | null, selector: string, label: string): void;
+/** 一次性健康诊断:不启动浏览器,只做静态/本地检查。 */
+export declare function doctorTool(config: BrowserConfig, _args: Record<string, any>, exec?: ToolRunContext): Promise<{
+    checks: DoctorCheck[];
+    summary: {
+        ok: boolean;
+        passed: number;
+        failed: number;
+    };
+}>;
 export declare function statusTool(): Promise<{
     open: boolean;
     profile: string;
@@ -189,6 +406,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 +449,84 @@ export declare function waitForLoginTool(config: BrowserConfig, args: Record<str
     title: string;
     loggedIn: boolean;
 }>;
-/** 断言:条件在 timeoutMs 内成立则通过,否则失败并自动截图存证据。 */
+/**
+ * 人工接管等待(通用版 wait_for_login):agent 把控制权交还给用户(验证码 /
+ * 二次确认 / 人工复核等)。instruction 会显示在实时画面面板;完成条件三选一:
+ * successSelector(元素出现)/ successUrl(URL 正则)/ 两者都不给则以
+ * URL 变化或页面内容签名变化视为完成。轮询间隔 2 秒,超时返回 completed:false
+ * (不抛错)。导出 runPauseOnPage 供测试注入 fake page。
+ */
+export declare function runPauseOnPage(page: Page, args: Record<string, any>): Promise<{
+    completed: boolean;
+    waitedMs: number;
+    detail: string;
+}>;
+/** 人工接管等待工具入口(缺 instruction 在启动浏览器前即校验,失败更快)。 */
+export declare function pauseForHumanTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    completed: boolean;
+    status: "completed" | "timedOut";
+    instruction: string;
+    detail: string;
+    waitedMs: number;
+}>;
+/**
+ * 敏感操作审批:agent 在执行提交/删除/支付类动作前调用,把审批请求推到实时
+ * 画面面板,挂起等待用户点「允许/拒绝」。超时视为拒绝(fail-closed)。
+ * 用户允许时返回 { decision: "allowed", ... };拒绝/超时**抛错**(消息含原因),
+ * 使 live 调用与 replay/batch 步骤统一按失败处理,agent 不应继续敏感动作。
+ * 决策通过 session.resolveConfirm(面板 POST)写入。
+ */
+export declare function confirmTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    decision: "allowed";
+    id: string;
+    reason: string;
+    waitedMs: number;
+    detail: string;
+}>;
+/** 断言:条件在 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 +534,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 +567,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 +593,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 +601,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,28 @@ 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;
+    /**
+     * 敏感操作审批模式:off(默认,行为与 v0.2 一致,工具仍可手动调用)|
+     * manual(systemPrompt 指示 agent 在提交/删除/支付类动作前调用 browser_confirm)。
+     */
+    confirmMode?: "off" | "manual";
+    /** browser_confirm 等待人工决策的默认超时毫秒(默认 60000)。 */
+    confirmTimeoutMs?: number;
+    /**
+     * 工具集:all(默认,全部工具)| core(只注册高频核心集,低频的
+     * 录制/回放/报告/抽取/profile 等不注册,降 systemPrompt 常驻 token)。
+     */
+    toolset?: "core" | "all";
 }
 /** 一个命名 profile 的会话状态。 */
 export interface ProfileState {
@@ -52,4 +76,29 @@ 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;
+        source?: "human";
+    };
+}
 //# sourceMappingURL=types.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.2",
-  "description": "DSH 插件:共享 Playwright 浏览器自动化(27 个 browser_* 工具)+ 原生界面实时画面面板 + 官方设置弹窗内的浏览器录制管理。仅依赖 playwright-core,不依赖任何 @deepseek-ai 运行时包。",
+  "version": "0.3.0",
+  "description": "DSH 插件:共享 Playwright 浏览器自动化(36 个 browser_* 工具,含语义元素查找、批处理、视觉回归、选择器自愈、参数化回放、结构化抽取、回归报告与隔离 context)+ 人机协作(人工接管等待、敏感操作审批、人机混合录制、面板双向化:点选元素/操作预告高亮/内嵌报告)+ 实时画面面板与录制管理。仅依赖 playwright-core,不依赖任何 @deepseek-ai 运行时包。",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/types/index.d.ts",