dsh-browser-view 0.2.0 → 0.3.0

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

@@ -1,4 +1,4 @@
-import type { Page } from "playwright-core";
+import type { BrowserContext, Page } from "playwright-core";
 import type { BrowserConfig, ProfileState, DownloadEntry, FormField, NavEntry, RefEntry, ReplayStep, SelectorHint } from "./types.js";
 /** 当前活动 profile 名(默认 "default")。 */
 export declare let currentProfile: string;
@@ -14,6 +14,15 @@ export declare function setPageRefs(page: Page, refs: Map<string, RefEntry>): vo
 export declare function pageRef(page: Page, ref: string): RefEntry | undefined;
 /** 清空页面的 ref 表(导航/新快照时调用)。 */
 export declare function clearPageRefs(page: Page): void;
+/** 取页面当前完整 ref 表(browser_find 增量续号合并用;无则空 Map)。 */
+export declare function pageRefsOf(page: Page): Map<string, RefEntry>;
+export interface SnapshotCache {
+    version: number;
+    text: string;
+    aria: string;
+}
+export declare function snapshotCacheOf(page: Page): SnapshotCache | undefined;
+export declare function setSnapshotCache(page: Page, cache: SnapshotCache): void;
 /** 已保存的录制脚本:name → 步骤数组。 */
 export declare const savedRecordings: Map<string, {
     steps: ReplayStep[];
@@ -30,7 +39,10 @@ export interface TestCall {
     /** 录制时采集的选择器指纹(回放自愈用;register 包装层异步补齐)。 */
     meta?: {
         hint?: SelectorHint;
+        source?: "human";
     };
+    /** source: "human" 表示这条来自用户在浏览器中的手动操作(混合录制)。 */
+    source?: "human";
 }
 export declare function isRecording(): boolean;
 export declare function startRecording(): void;
@@ -41,7 +53,52 @@ export declare function lastRecordingOf(): TestCall[] | null;
 export declare function recordCall(call: TestCall): TestCall;
 /** 操作轨迹(按时间倒序,最新在前)。 */
 export declare function testLogOf(): TestCall[];
+export declare function setPauseInstruction(instruction: string): void;
+export declare function clearPauseInstruction(): void;
+export declare function currentPause(): {
+    instruction: string;
+    startedAt: number;
+} | null;
+/** 一次待审批的敏感操作(browser_confirm 等待期间供面板展示与提交决策)。 */
+export interface PendingConfirm {
+    id: string;
+    reason: string;
+    tool?: string;
+    args?: Record<string, any>;
+    startedAt: number;
+    decision?: "allowed" | "denied";
+}
+export declare function setPendingConfirm(entry: PendingConfirm): void;
+export declare function getPendingConfirm(): PendingConfirm | null;
+export declare function clearPendingConfirm(): void;
+/** 面板提交审批决策;id 不匹配(已被新审批取代/超时清理)时返回 false。 */
+export declare function resolveConfirm(id: string, decision: "allowed" | "denied"): boolean;
 export declare function clearTestLog(): void;
+/** window 上的回传 binding 名(须为合法 JS 标识符)。 */
+export declare const HUMAN_BINDING = "__dshBrowserHumanEvent";
+/** agent 即将/刚刚执行了 DOM 操作(register 包装层调用);1.5s 内的页内事件视为工具回声。 */
+export declare function noteAgentAction(): void;
+/** 导出供测试:距上次 agent 操作是否在去重窗口内。 */
+export declare function agentActionRecent(now?: number, windowMs?: number): boolean;
+/**
+ * 页内人工操作事件 → 录制步骤(纯函数,导出供测试)。
+ * payload 由 installHumanRecorder 生成:{ kind, selector, value?, testid?, role?, name?, id?, text?, tag? }。
+ * 无法映射(缺 selector / 未知 kind / 空输入)返回 null。
+ */
+export declare function humanEventToStep(payload: unknown): {
+    tool: string;
+    args: Record<string, any>;
+    meta: {
+        hint: SelectorHint;
+        source: "human";
+    };
+} | null;
+/**
+ * 页内注入的人工操作监听(addInitScript 序列化;每次导航自动重装)。
+ * 监听常驻但 node 侧只在录制中生效,关闭录制等价于"移除"。
+ * 只上报可交互元素上的 click 与表单控件的 change,避免逐键噪音。
+ */
+export declare function installHumanRecorder(): void;
 /** 网络请求/响应记录。 */
 export interface NetworkEntry {
     url: string;
@@ -71,6 +128,14 @@ export declare function loadPlaywright(): Promise<typeof import("playwright-core
 export declare function launchProfile(name: string, config: BrowserConfig): Promise<void>;
 /** 当前 profile 状态(未启动时创建空状态)。 */
 export declare function stateOf(): ProfileState;
+export interface NamedContext {
+    context: BrowserContext;
+    pageIds: Set<number>;
+    createdAt: number;
+}
+export declare function namedContextsOf(): Map<string, NamedContext>;
+/** 把一个已 attach 的页面注册进 profile 标签表并激活,返回分配的 tab id。 */
+export declare function registerTabPage(state: ProfileState, page: Page): number;
 /** 新建一个页面(当前 profile 会话未启动时先启动)。 */
 export declare function newPage(config: BrowserConfig): Promise<Page>;
 /** 返回当前活动页面(没有则新建),并保证浏览器已启动。 */

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

@@ -1,6 +1,6 @@
 import type { Locator, Page } from "playwright-core";
 import type { ToolRunContext } from "../lib/types.js";
-import type { BrowserConfig, ReplayStep, SelectorHint } 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): {
@@ -32,27 +32,94 @@ export declare function openTool(config: BrowserConfig, args: Record<string, any
  * 只折叠完全相同的相邻行,不重排、不删改非重复内容。
  */
 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;
+};
+/**
+ * 语义元素定位:按名称(或 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[];
+    }[];
+}>;
+/**
+ * 行级 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;
-    tree: string;
+    scope?: string | undefined;
+    unchanged: boolean;
+    contentVersion: number;
+} | {
+    url: string;
+    title: string;
     truncated: boolean;
-    refs: number;
-    text?: undefined;
-    links?: undefined;
-    inputs?: undefined;
+    scope?: string | undefined;
+    diff: boolean;
+    contentVersion: number;
+    changedFrom: number | undefined;
+    removed: number | undefined;
 } | {
     url: string;
     title: string;
-    text: string;
     truncated: boolean;
-    links: {
-        text: string;
-        href: string;
-    }[];
-    inputs: number;
-    tree?: undefined;
-    refs?: undefined;
+    scope?: string | undefined;
+    stale?: boolean | undefined;
+    contentVersion: number;
 }>;
 /**
  * 解析点击/输入目标为 Locator:selector 直译;ref 走注册表——
@@ -117,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;
@@ -293,6 +449,42 @@ export declare function waitForLoginTool(config: BrowserConfig, args: Record<str
     title: string;
     loggedIn: boolean;
 }>;
+/**
+ * 人工接管等待(通用版 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;

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

@@ -31,6 +31,18 @@ export interface BrowserConfig {
     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 {
@@ -86,6 +98,7 @@ export interface ReplayStep {
     args: any;
     meta?: {
         hint?: SelectorHint;
+        source?: "human";
     };
 }
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-browser-view",
-  "version": "0.2.0",
-  "description": "DSH 插件:共享 Playwright 浏览器自动化(31 个 browser_* 工具,含 ARIA ref 交互、批处理、视觉回归、选择器自愈、参数化回放、结构化抽取与回归报告)+ 原生界面实时画面面板 + 官方设置弹窗内的浏览器录制管理。仅依赖 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",