dsh-browser-view 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,31 @@
+/** 录制存储目录($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;
+/** 删除磁盘上的录制文件;返回是否存在并删除。 */
+export declare function deleteRecordingFile(name: string): boolean;
+/** 录制列表(面板 / browser_record list 共用)。 */
+export declare function listRecordings(): Array<{
+    name: string;
+    steps: number;
+    savedAt: number;
+    preview: string;
+}>;
+/** 录制详情(面板展开查看步骤)。 */
+export declare function recordingDetail(name: string): {
+    name: string;
+    steps: {
+        tool: string;
+        args: any;
+    }[];
+} | undefined;
+/** 删除录制(内存 + 磁盘同步);返回是否存在并删除。 */
+export declare function deleteRecording(name: string): boolean;
+//# sourceMappingURL=recordings.d.ts.map

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

@@ -0,0 +1,4 @@
+import type { ReefContext } from "../lib/types.js";
+import type { BrowserConfig } from "./types.js";
+export declare function registerTools(ctx: ReefContext, config: BrowserConfig): void;
+//# sourceMappingURL=register.d.ts.map

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

@@ -0,0 +1,103 @@
+import type { Page } from "playwright-core";
+import type { BrowserConfig, ProfileState, DownloadEntry, FormField, NavEntry } from "./types.js";
+/** 当前活动 profile 名(默认 "default")。 */
+export declare let currentProfile: string;
+/** 多配置文件浏览器会话:name → 会话状态。 */
+export declare const profileStates: Map<string, ProfileState>;
+/** 已保存的表单回放:name → fields 数组。 */
+export declare const savedForms: Map<string, FormField[]>;
+/** 最近一次 browser_form 填充的字段(供 browser_form_save 无参保存)。 */
+export declare let lastFormFields: FormField[];
+/** 已保存的录制脚本:name → 步骤数组。 */
+export declare const savedRecordings: Map<string, {
+    steps: {
+        tool: string;
+        args: any;
+    }[];
+    savedAt: number;
+}>;
+/** 一次工具调用的记录(操作轨迹 / 录制 / 回放共用)。 */
+export interface TestCall {
+    tool: string;
+    args: Record<string, any>;
+    ok: boolean;
+    ms: number;
+    ts: number;
+    error?: string;
+}
+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;
+/** 操作轨迹(按时间倒序,最新在前)。 */
+export declare function testLogOf(): TestCall[];
+export declare function clearTestLog(): void;
+/** 网络请求/响应记录。 */
+export interface NetworkEntry {
+    url: string;
+    method: string;
+    resourceType: string;
+    status?: number;
+    ok?: boolean;
+    failed?: boolean;
+    error?: string;
+    startedAt: number;
+    durationMs?: number;
+    /** 请求体(截断,默认记录)。 */
+    postData?: string | null;
+    /** 响应体(截断,默认记录;SSE 与大响应跳过)。 */
+    body?: string | null;
+}
+export declare function networkEntries(name: string): NetworkEntry[];
+export declare function addNetworkEntry(profile: string, entry: NetworkEntry): void;
+export declare function clearNetwork(profile: string): void;
+export declare function profileConfig(config: BrowserConfig, name: string): BrowserConfig;
+export declare function getProfileState(name: string): ProfileState;
+export declare function downloadsOf(name: string): DownloadEntry[];
+/** 某 profile 的访问历史(按时间先后)。 */
+export declare function historyOf(name: string): NavEntry[];
+export declare function attachPage(page: Page, config: BrowserConfig): void;
+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;
+/** 新建一个页面(当前 profile 会话未启动时先启动)。 */
+export declare function newPage(config: BrowserConfig): Promise<Page>;
+/** 返回当前活动页面(没有则新建),并保证浏览器已启动。 */
+export declare function getPage(config: BrowserConfig): Promise<Page>;
+/** 活动页面(可能为 null,不触发启动)。 */
+export declare function activePage(): Page | null;
+/** 投影当前 profile 的标签列表。 */
+export declare function tabList(): Promise<{
+    id: number;
+    url: string;
+    title: string;
+}[]>;
+export declare function closeBrowser(): Promise<void>;
+/** Best-effort current page identity, safe when nothing is open. */
+export declare function pageIdentity(page: Page): Promise<{
+    url: string;
+    title: string;
+}>;
+/** 设置最近一次表单填充(供 browser_form_save 无参保存)。 */
+export declare function setLastFormFields(fields: FormField[]): void;
+/** 切换当前 profile。 */
+export declare function setCurrentProfile(name: string): void;
+/** 记录最近一次截图目录(截图工具调用时写入)。 */
+export declare function noteScreenshotDir(dir: string): void;
+/** 定时清扫入口:若已知截图目录则按当前配置清理。 */
+export declare function sweepScreenshotDir(opts: {
+    maxAgeDays?: number;
+    maxCount?: number;
+}): number;
+/**
+ * 清理截图目录里的 .png 文件:按修改时间保留最新的 maxCount 个,
+ * 并删除超过 maxAgeDays 天的旧文件。只处理目录直属文件,不递归;
+ * 单个文件删除失败(被占用等)静默跳过。返回删除数量。
+ */
+export declare function cleanupScreenshots(dir: string, opts: {
+    maxAgeDays?: number;
+    maxCount?: number;
+}): number;
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1,339 @@
+import type { Page } from "playwright-core";
+import type { ToolRunContext } from "../lib/types.js";
+import type { BrowserConfig } from "./types.js";
+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;
+    truncated: boolean;
+    links: {
+        text: string;
+        href: string;
+    }[];
+    inputs: number;
+    url: string;
+    title: string;
+}>;
+export declare function clickTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    clicked: string;
+}>;
+export declare function typeTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    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;
+    pressed: string;
+}>;
+export declare function evalTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    result: unknown;
+}>;
+export declare function screenshotTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
+    path: string;
+    bytes: number;
+    width: number;
+    height: number;
+}>;
+export declare function waitTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    waitedMs: number;
+}>;
+export declare function backTool(config: BrowserConfig): Promise<{
+    url: string;
+    title: string;
+}>;
+export declare function reloadTool(config: BrowserConfig): Promise<{
+    url: string;
+    title: string;
+}>;
+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 resolveTabId(args: Record<string, any>): number;
+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;
+}>;
+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 elementsTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    count: number;
+    elements: Record<string, unknown>[];
+}>;
+export declare function closeTool(): Promise<{
+    closed: boolean;
+}>;
+/**
+ * 条件检查引擎(测试原语共用)。
+ *
+ * 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;
+}>;
+/**
+ * 等待人工登录完成(配合 headless:false 使用):agent 打开登录页后调用本工具,
+ * 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。基于通用条件引擎:
+ * successSelector / successUrl 指定完成条件,两者都不给则以 URL 跳转视为完成。
+ * 超时返回 loggedIn:false(不抛错)。
+ */
+export declare function waitForLoginTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    loggedIn: boolean;
+}>;
+/** 断言:条件在 timeoutMs 内成立则通过,否则失败并自动截图存证据。 */
+export declare function assertTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
+    url: string;
+    title: string;
+    passed: boolean;
+}>;
+/** 网络记录查询:list / failed / wait / clear。 */
+export declare function networkTool(args: Record<string, any>): Promise<{
+    cleared: boolean;
+    entries: number;
+    matched?: undefined;
+    waitMs?: undefined;
+    failed?: undefined;
+} | {
+    matched: import("./session.js").NetworkEntry;
+    waitMs: number;
+    cleared?: undefined;
+    entries?: undefined;
+    failed?: undefined;
+} | {
+    failed: import("./session.js").NetworkEntry[];
+    cleared?: undefined;
+    entries?: undefined;
+    matched?: undefined;
+    waitMs?: undefined;
+} | {
+    entries: import("./session.js").NetworkEntry[];
+    cleared?: undefined;
+    matched?: undefined;
+    waitMs?: undefined;
+    failed?: undefined;
+}>;
+/** 录制管理: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;
+} | {
+    recording: boolean;
+    steps: number;
+    hint?: undefined;
+    saved?: undefined;
+    file?: undefined;
+    recordings?: undefined;
+    deleted?: undefined;
+    name?: undefined;
+} | {
+    saved: string;
+    steps: number;
+    file: string;
+    hint: string;
+    recording?: undefined;
+    recordings?: undefined;
+    deleted?: undefined;
+    name?: undefined;
+} | {
+    recordings: {
+        name: string;
+        steps: number;
+        savedAt: number;
+        preview: string;
+    }[];
+    recording?: undefined;
+    hint?: undefined;
+    steps?: undefined;
+    saved?: undefined;
+    file?: undefined;
+    deleted?: undefined;
+    name?: undefined;
+} | {
+    deleted: boolean;
+    name: string;
+    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<{
+    total: number;
+    passed: number;
+    failed: number;
+    stoppedAt: number | null;
+    results: any[];
+}>;
+/** 回放入口:name(已保存录制)或 steps(数组)二选一。 */
+export declare function replayTool(args: Record<string, any>, impls: Record<string, (args: any) => Promise<unknown>>): Promise<{
+    summary: string;
+    total: number;
+    passed: number;
+    failed: number;
+    stoppedAt: number | null;
+    results: any[];
+    source: string;
+}>;
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1,55 @@
+import type { Browser, BrowserContext, Page } from "playwright-core";
+export interface BrowserConfig {
+    enabled?: boolean;
+    channel?: string;
+    executablePath?: string;
+    headless?: boolean;
+    userDataDir?: string;
+    profiles?: Record<string, Partial<BrowserConfig>>;
+    screenshotDir?: string;
+    downloadDir?: string;
+    /** 截图保留天数(0 = 不按时间清理)。 */
+    screenshotMaxAgeDays?: number;
+    /** 截图保留数量上限(0 = 不按数量清理)。 */
+    screenshotMaxCount?: number;
+    /** 面板嵌入 + 实时画面 API 基路径。 */
+    basePath?: string;
+    /** 网络记录是否保存请求/响应体(默认 true,截断存储)。 */
+    recordBodies?: boolean;
+    maxTextChars?: number;
+    maxLinks?: number;
+    timeoutMs?: number;
+}
+/** 一个命名 profile 的会话状态。 */
+export interface ProfileState {
+    browser: Browser | null;
+    context: BrowserContext | null;
+    persistent: boolean;
+    pages: Map<number, Page>;
+    activeId: number | null;
+    counter: number;
+    channel?: string;
+}
+/** 一次页面下载的记录。 */
+export interface DownloadEntry {
+    download: {
+        saveAs(path: string): Promise<void>;
+        suggestedFilename(): string;
+        url(): string;
+    };
+    suggestedFilename: string;
+    at: number;
+}
+/** 一次页面访问(导航)的记录,供实时画面模态框展示访问历史。 */
+export interface NavEntry {
+    url: string;
+    title: string;
+    ts: number;
+}
+/** 表单字段(selector 或 label 二选一)。 */
+export interface FormField {
+    selector?: string;
+    label?: string;
+    value?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,4 @@
+import type { ReefContext } from "../lib/types.js";
+import type { BrowserConfig } from "./types.js";
+export declare function registerBrowserApi(ctx: ReefContext, config: BrowserConfig, base: string): void;
+//# sourceMappingURL=ui.d.ts.map

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

@@ -0,0 +1,26 @@
+/**
+ * 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 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/embed.d.ts

@@ -0,0 +1,7 @@
+import type { ReefContext, WebRoute } from "./lib/types.js";
+export declare function applyEmbed(ctx: ReefContext, webServer: {
+    register(route: WebRoute): () => void;
+    tapIndex(transform: (html: string) => string): () => void;
+    port?: number;
+}, base: string): () => void;
+//# sourceMappingURL=embed.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,5 @@
+import type { ReefContext } from "./lib/types.js";
+export declare const name = "dsh-browser-view";
+export declare const inject: string[];
+export declare function apply(ctx: ReefContext, rawConfig: Record<string, any>): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,17 @@
+export interface FieldSchema {
+    type: "string" | "number" | "boolean" | "array" | "object" | "string[]" | "any";
+    optional?: boolean;
+    default?: unknown;
+    enum?: string[];
+    items?: FieldSchema;
+    max?: number;
+    min?: number;
+}
+export type ConfigSchema = Record<string, FieldSchema>;
+declare const TYPES: string[];
+/** 校验配置;返回错误列表(空 = 通过)。 */
+export declare function validateConfig(schema: ConfigSchema, config: Record<string, any>): string[];
+/** 合并默认值 + 校验;抛错时带模块名前缀。 */
+export declare function resolveConfig(moduleName: string, schema: ConfigSchema, defaults: Record<string, any>, raw: Record<string, any> | undefined): Record<string, any>;
+export { TYPES };
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** Parse the request URL pathname (query strings are ignored). */
+export declare function urlPath(req: IncomingMessage): string;
+/** Read the request body as a UTF-8 string (bounded). */
+export declare function readRawBody(req: IncomingMessage, limitBytes?: number): Promise<string>;
+/** Read and parse a JSON request body; `undefined` when the body is empty. */
+export declare function readJsonBody(req: IncomingMessage, limitBytes?: number): Promise<unknown>;
+/** Send a JSON response. */
+export declare function sendJson(res: ServerResponse, status: number, value: unknown, extraHeaders?: Record<string, string>): void;
+/** Send a plain text response. */
+export declare function sendText(res: ServerResponse, status: number, text: string, headers?: Record<string, string>): void;
+//# sourceMappingURL=http.d.ts.map

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

@@ -0,0 +1,26 @@
+import type { PlainToolDefinition, ToolRunContext } from "./types.js";
+/**
+ * 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;
+/** definePlainTool 的输入选项。 */
+export interface PlainToolOptions {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    execute: (args: any, exec: ToolRunContext) => Promise<unknown> | unknown;
+    render?: (args: any, value: any) => string;
+    presentCall?: (args: any) => unknown;
+    concurrencySafe?: boolean;
+    timeoutMs?: number;
+}
+/**
+ * Build a plain ToolDefinition for `ctx.tools.register` without depending on
+ * any @deepseek-ai package (max version-alignment tolerance).
+ */
+export declare function definePlainTool(options: PlainToolOptions): PlainToolDefinition;
+/** Generic card view used by all dsh-browser tools. */
+export declare function genericCard(kind: string, title: string, rawInput: string): unknown;
+//# sourceMappingURL=tools.d.ts.map