dsh-browser-view 0.4.0 → 0.7.0

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

@@ -0,0 +1,148 @@
+import type { ToolRunContext } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+import { targetLocator, resolveTargetLocator } from "../session.js";
+import { type FormFillResult } from "../primitives/index.js";
+export { targetLocator, resolveTargetLocator };
+export declare function isBotSensitiveUrl(url: string): boolean;
+export declare function clickTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
+    url: string;
+    title: string;
+    effectHint?: string | undefined;
+    clicked: string;
+    effect: {
+        switchedCandidate?: boolean | undefined;
+        newRequests?: {
+            status?: number | undefined;
+            url: string;
+            method: string;
+        }[] | undefined;
+        urlChanged: boolean;
+        mutations?: string[] | undefined;
+        domChanged: boolean;
+    };
+} | {
+    url: string;
+    title: string;
+    clicked: string;
+}>;
+export declare function typeTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    typed: boolean;
+    editor: boolean;
+    selector: string;
+} | {
+    url: string;
+    title: string;
+    typed: boolean;
+    selector: string;
+    submit: boolean;
+}>;
+export declare function pressTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    warning?: string | undefined;
+    pressed: string;
+}>;
+/**
+ * 下拉选择原语:委托给 UI 组件库下拉适配器(Native / AntDesign / ElementPlus / GenericARIA)。
+ * 各组件库特异性的展开机制、虚拟列表穿透与 0 宽度读屏傀儡节点过滤完全隔离在适配器中。
+ */
+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<{
+    scriptUnwrapped?: boolean | undefined;
+    result: unknown;
+}>;
+export declare function downloadTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
+    path: string;
+    filename: string;
+    url: string;
+    bytes: number;
+}>;
+export declare function uploadTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
+    url: string;
+    title: string;
+    uploaded: string;
+    bytes: number;
+}>;
+export declare function cookiesTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    cookies: {
+        name: string;
+        value: string;
+        domain: string;
+        path: string;
+        httpOnly: boolean;
+        secure: boolean;
+        sameSite: "Strict" | "Lax" | "None";
+        expires: number;
+    }[];
+    set?: undefined;
+    name?: undefined;
+    url?: undefined;
+    cleared?: undefined;
+} | {
+    set: boolean;
+    name: string;
+    url: any;
+    cookies?: undefined;
+    cleared?: undefined;
+} | {
+    cleared: boolean;
+    cookies?: undefined;
+    set?: undefined;
+    name?: undefined;
+    url?: undefined;
+}>;
+export declare function formTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    filled: ({
+        selector: any;
+        label?: undefined;
+    } | {
+        label: any;
+        selector?: undefined;
+    })[];
+    submit: boolean;
+}>;
+export declare function formSaveTool(args: Record<string, any>): Promise<{
+    saved: string;
+    fields: number;
+}>;
+export declare function formsTool(args: Record<string, any>): Promise<{
+    forms: {
+        name: string;
+        fields: number;
+        preview: string;
+    }[];
+    deleted?: undefined;
+    name?: undefined;
+} | {
+    deleted: boolean;
+    name: string;
+    forms?: undefined;
+}>;
+/**
+ * 智能批量表单填写: 一次调用自动识别并填充多个表单控件, 结合 UI 适配器自动处理输入/选择与弹层
+ */
+export declare function formFillTool(config: BrowserConfig, args: Record<string, any>): Promise<FormFillResult>;
+export declare function transferTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    transferred: boolean;
+    direction: string;
+    items: string[];
+}>;
+export declare function dragTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    dragged: boolean;
+    source: string;
+    target: string;
+}>;
+//# sourceMappingURL=interaction.d.ts.map

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

@@ -0,0 +1,126 @@
+import type { BrowserConfig } from "../types.js";
+export declare function openTool(configOrArgs: BrowserConfig | Record<string, any>, maybeArgs?: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    status: string;
+}>;
+export declare function backTool(config: BrowserConfig): Promise<{
+    url: string;
+    title: string;
+}>;
+export declare function reloadTool(config: BrowserConfig): Promise<{
+    url: string;
+    title: string;
+}>;
+/**
+ * 命名隔离上下文:同一浏览器进程内独立 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;
+}>;
+export declare function statusTool(): Promise<{
+    open: boolean;
+    profile: string;
+    channel: string;
+    tabs: number;
+    profiles: {
+        name: string;
+        open: boolean;
+        tabs: number;
+        channel: string;
+        persistent: boolean;
+    }[];
+} | {
+    url: string;
+    title: string;
+    open: boolean;
+    profile: string;
+    channel: string;
+    tabs: number;
+    profiles: {
+        name: string;
+        open: boolean;
+        tabs: number;
+        channel: string;
+        persistent: boolean;
+    }[];
+}>;
+export declare function tabsTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    action: any;
+    tabs: {
+        id: number;
+        url: string;
+        title: string;
+    }[];
+    activeId: number;
+    tab?: undefined;
+} | {
+    action: any;
+    tab: {
+        id: number;
+        url: string;
+        title: string;
+    };
+    tabs: {
+        id: number;
+        url: string;
+        title: string;
+    }[];
+    activeId: number;
+}>;
+export declare function profileTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    current: string;
+    profiles: {
+        name: string;
+        open: boolean;
+        tabs: number;
+        persistent: boolean;
+        userDataDir: string;
+    }[];
+}>;
+export declare function closeTool(): Promise<{
+    closed: boolean;
+}>;
+//# sourceMappingURL=navigation.d.ts.map

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

@@ -0,0 +1,236 @@
+import type { Page } from "playwright-core";
+import type { ToolRunContext } from "../../lib/types.js";
+import type { BrowserConfig, ReplayStep, SelectorHint } from "../types.js";
+import { type RunRecord } from "../reports.js";
+/** 使用 args.selector 定位的工具集合(自愈与录制指纹的作用范围)。 */
+export declare const SELECTOR_STEP_TOOLS: Set<string>;
+/**
+ * 采集选择器指向元素的指纹(页内 evaluate;找不到元素返回 null)。
+ * 指纹是回放自愈的降级候选来源:testid / role+name / text / id / tag+text。
+ * F5 收敛:元素描述(role/name/text)改用 walker 单一来源
+ * (describeElement),与 aria 快照/find/录制回声共用同一套语义;相比旧
+ * 内联副本,role 推断更完整(slider/spinbutton/searchbox/heading 等),
+ * name 补齐 labelledby/label[for]/title 兜底 —— 指纹只作自愈降级候选,
+ * 语义增强只会让自愈命中率更高,不改变任何主链路行为。
+ */
+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>, config?: BrowserConfig, exec?: ToolRunContext): Promise<{
+    recording: boolean;
+    hint: string;
+    steps?: undefined;
+    recordings?: undefined;
+    deleted?: undefined;
+    name?: undefined;
+    exported?: undefined;
+    format?: undefined;
+    path?: undefined;
+    code?: undefined;
+} | {
+    recording: boolean;
+    steps: number;
+    hint?: undefined;
+    recordings?: undefined;
+    deleted?: undefined;
+    name?: undefined;
+    exported?: undefined;
+    format?: undefined;
+    path?: undefined;
+    code?: undefined;
+} | {
+    hint: string;
+    warnings?: string[] | undefined;
+    varsApplied?: number | undefined;
+    skippedFailed?: number | undefined;
+    stripped?: number | undefined;
+    saved: string;
+    steps: number;
+    source: string;
+    file: string;
+    recording?: undefined;
+    recordings?: undefined;
+    deleted?: undefined;
+    name?: undefined;
+    exported?: undefined;
+    format?: undefined;
+    path?: undefined;
+    code?: undefined;
+} | {
+    recordings: {
+        name: string;
+        steps: number;
+        savedAt: number;
+        preview: string;
+    }[];
+    recording?: undefined;
+    hint?: undefined;
+    steps?: undefined;
+    deleted?: undefined;
+    name?: undefined;
+    exported?: undefined;
+    format?: undefined;
+    path?: undefined;
+    code?: undefined;
+} | {
+    deleted: boolean;
+    name: string;
+    recording?: undefined;
+    hint?: undefined;
+    steps?: undefined;
+    recordings?: undefined;
+    exported?: undefined;
+    format?: undefined;
+    path?: undefined;
+    code?: undefined;
+} | {
+    exported: boolean;
+    format: string;
+    path: string;
+    code: string;
+    recording?: undefined;
+    hint?: undefined;
+    steps?: undefined;
+    recordings?: undefined;
+    deleted?: undefined;
+    name?: undefined;
+} | {
+    exported: boolean;
+    format: string;
+    code: string;
+    recording?: undefined;
+    hint?: undefined;
+    steps?: undefined;
+    recordings?: undefined;
+    deleted?: undefined;
+    name?: undefined;
+    path?: undefined;
+}>;
+/** 回放选项(自愈开关与单次尝试超时,来自 config;retryFailed 为自动重试次数)。 */
+export interface ReplayOptions {
+    healing?: boolean;
+    healTimeoutMs?: number;
+    /** F2:步骤失败(含自愈链耗尽)后自动重试的次数,步骤间 500ms×n 线性退避。 */
+    retryFailed?: 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;
+    healedCount: number;
+    retries?: {
+        attempted: number;
+        recovered: number;
+    };
+    stoppedAt?: number;
+    results: any[];
+}>;
+/**
+ * 回归报告: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;
+    retries?: {
+        attempted: number;
+        recovered: 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;
+    healedCount: number;
+    retries?: {
+        attempted: number;
+        recovered: number;
+    };
+    stoppedAt?: number;
+    results: any[];
+    source: string;
+    rows?: undefined;
+    passedRows?: undefined;
+    failedRows?: undefined;
+    runs?: undefined;
+}>;
+/** 重跑请求:source 为已保存录制名,retryOf 为被重跑的原 runId(记录用)。 */
+export interface RerunRequest {
+    source: string;
+    retryOf?: string;
+}
+type RerunHandler = (req: RerunRequest) => Promise<unknown>;
+/** registerTools 注册重跑入口(stepImpls 同路径);web-only 进程保持 null。 */
+export declare function setRerunHandler(fn: RerunHandler): void;
+/** 当前可用的重跑入口(null = 本进程没有 tools 服务,无法重跑)。 */
+export declare function getRerunHandler(): RerunHandler | null;
+/** 重跑是否正在执行(端点互斥;导出供测试)。 */
+export declare function rerunBusy(): boolean;
+/** 执行一次面板重跑(busy 检查 + 互斥标记;返回 replayTool 结果)。 */
+export declare function runPanelRerun(req: RerunRequest): Promise<unknown>;
+export {};
+//# sourceMappingURL=recorder.d.ts.map

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

@@ -0,0 +1,94 @@
+import type { Page } from "playwright-core";
+import type { ToolRunContext } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+export declare function waitTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    waitedMs: number;
+}>;
+/**
+ * 条件检查引擎(测试原语共用)。
+ *
+ * cond 支持四类(每类内部互斥,取第一个存在的字段):
+ *   { selector: "#btn", state: "visible|hidden|attached|detached" }  元素状态(默认 visible)
+ *   { url: "正则字符串" }                                            当前 URL 匹配
+ *   { text: "子串" }                                                  body 可见文本包含
+ *   { count: { selector, op: "eq|gt|gte|lt|lte", value: n } }         元素数量比较
+ *   { eval: "JS 表达式" }                                            表达式求值 truthy
+ */
+export type TestCondition = Record<string, any>;
+/** 单次检查:返回 { ok, detail }。不抛错,失败时 detail 给出原因。 */
+export declare function checkOnce(page: Page, cond: TestCondition): Promise<{
+    ok: boolean;
+    detail?: string;
+}>;
+/** 轮询等待条件成立(intervalMs 步进),返回最后一次检查结果。 */
+export declare function pollCondition(page: Page, cond: TestCondition, timeoutMs: number, intervalMs?: number): Promise<{
+    ok: boolean;
+    detail?: string;
+}>;
+/** 通用显式等待:等待条件成立,超时抛错。 */
+export declare function waitForTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    met: boolean;
+}>;
+/** 断言:条件在 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。兼容 (args) 与 (config, args) 两种调用签名。 */
+export declare function networkTool(configOrArgs?: Record<string, any>, maybeArgs?: Record<string, any>): Promise<{
+    cleared: boolean;
+    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[];
+    cleared?: undefined;
+    entries?: undefined;
+    matched?: undefined;
+    waitMs?: undefined;
+    stats?: undefined;
+} | {
+    entries: import("../session.js").NetworkEntry[];
+    cleared?: undefined;
+    matched?: undefined;
+    waitMs?: undefined;
+    stats?: undefined;
+    failed?: undefined;
+}>;
+//# sourceMappingURL=testing.d.ts.map