@angelky7/dsh-browser-control 1.7.2 → 1.7.4

package/lib/types/audit.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 操作审计（v1.7.4）：插件这一侧到底发过哪些命令、被拒了几次、各自用了多久。
+ *
+ * 存在的理由不是「日志」，而是回答两个现实问题：出事后「刚才谁动了这个页面」，
+ * 以及做「会话恢复」之前先得有一份可靠的行为底账。所以：
+ *
+ *   - **记录在命令层**（controller.execute），不是工具层：模型看不到的内部重试、
+ *     browser_drag 一次拖拽打出的 N 次 cdp 往返，都在账上，不美化。
+ *   - **只存内存**（环形缓冲，200 条）：跨 dsh 重启的持久化是「会话恢复」那一版的事；
+ *     这一版先把账记对，别把磁盘格式写死。
+ *   - **参数摘要是脱敏后的**：输入框的值、cookie 的值、令牌类字段一律打码；
+ *     表达式截断。审计的用途是「做了什么」，不是「内容是什么」。
+ */
+export interface AuditEntry {
+    seq: number;
+    /** epoch 毫秒 */
+    t: number;
+    command: string;
+    tabId?: number;
+    /** 脱敏后的参数摘要（JSON 文本，已截断） */
+    params: string;
+    ok: boolean;
+    code?: string;
+    effectState?: string;
+    /** 失败描述，截断 */
+    error?: string;
+    durationMs: number;
+}
+export interface AuditFilter {
+    tabId?: number;
+    /** 命令名子串匹配（如 "nav" 命中 nav / browser.info? 不需要——命令名如 tabs.open） */
+    command?: string;
+    /** 只返回 seq 严格大于它的条目（分页） */
+    sinceSeq?: number;
+    /** 最多返回多少条（取最新的 N 条，按 seq 升序给出） */
+    limit?: number;
+}
+/** 环形缓冲上限。200 条足够覆盖一次排障现场，又不至于让内存跟着会话长度涨。 */
+export declare const AUDIT_MAX_ENTRIES = 200;
+/**
+ * 把一次调用的参数压成可审计的摘要：敏感键打码、特定命令的 value 打码、
+ * 长表达式截断、整体限长。返回 JSON 文本——审计工具原样把它交给模型。
+ */
+export declare function summarizeAuditParams(command: string, params: Record<string, unknown>): string;
+/** 记账器。一个桥（一个插件实例）一份；`record` 只追加，`list` 只读。 */
+export declare class AuditLog {
+    private readonly entries;
+    private nextSeq;
+    private readonly now;
+    constructor(now?: () => number);
+    /**
+     * 记一笔。
+     * @param input - 命令、摘要与结果；seq/t 由账本自己盖，durationMs 由调用方量。
+     */
+    record(input: {
+        command: string;
+        tabId?: number;
+        params: string;
+        ok: boolean;
+        code?: string;
+        effectState?: string;
+        error?: string;
+        durationMs: number;
+    }): AuditEntry;
+    /** 现有条目数（被挤掉的不算）。 */
+    size(): number;
+    /**
+     * 过滤并取最新的一批。
+     * @param filter - tabId / 命令子串 / sinceSeq / limit；返回按 seq 升序。
+     */
+    list(filter?: AuditFilter): AuditEntry[];
+}

package/lib/types/audit.js

@@ -0,0 +1,107 @@
+/** 环形缓冲上限。200 条足够覆盖一次排障现场，又不至于让内存跟着会话长度涨。 */
+export const AUDIT_MAX_ENTRIES = 200;
+/** 单条参数摘要上限：审计要的是形状，不是全文。 */
+const AUDIT_PARAMS_MAX_CHARS = 300;
+/** 失败描述上限。 */
+const AUDIT_ERROR_MAX_CHARS = 200;
+/** eval 表达式只留前 120 字符：里面可能有凭据。 */
+const AUDIT_EXPRESSION_MAX_CHARS = 120;
+/** 参数里这些键的值一律打码（大小写不敏感）。 */
+const SECRET_KEY = /^(token|authorization|password|passwd|secret|apikey|api_key|cookie)$/i;
+/**
+ * 哪个命令的 `value` 字段是敏感内容：`input` 是往页面里打的字（可能是密码），
+ * `cookies.set` 直接写凭据。其余命令的 value 字段（如果有）不动。
+ */
+const VALUE_REDACTED_COMMANDS = new Set(['input', 'cookies.set']);
+function redactValue(value) {
+    const length = typeof value === 'string' ? [...value].length : 0;
+    return `[redacted:${length} chars]`;
+}
+/**
+ * 把一次调用的参数压成可审计的摘要：敏感键打码、特定命令的 value 打码、
+ * 长表达式截断、整体限长。返回 JSON 文本——审计工具原样把它交给模型。
+ */
+export function summarizeAuditParams(command, params) {
+    let text;
+    try {
+        text = JSON.stringify(params, (key, value) => {
+            if (SECRET_KEY.test(key))
+                return '[redacted]';
+            if (key === 'value' && VALUE_REDACTED_COMMANDS.has(command))
+                return redactValue(value);
+            if (key === 'expression' && typeof value === 'string' && [...value].length > AUDIT_EXPRESSION_MAX_CHARS) {
+                return `${[...value].slice(0, AUDIT_EXPRESSION_MAX_CHARS).join('')}…[+${[...value].length - AUDIT_EXPRESSION_MAX_CHARS} chars]`;
+            }
+            return value;
+        }) ?? '{}';
+    }
+    catch {
+        text = '[unserializable params]';
+    }
+    return [...text].length > AUDIT_PARAMS_MAX_CHARS
+        ? `${[...text].slice(0, AUDIT_PARAMS_MAX_CHARS).join('')}…[+${[...text].length - AUDIT_PARAMS_MAX_CHARS} chars]`
+        : text;
+}
+/** 记账器。一个桥（一个插件实例）一份；`record` 只追加，`list` 只读。 */
+export class AuditLog {
+    entries = [];
+    nextSeq = 1;
+    now;
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /**
+     * 记一笔。
+     * @param input - 命令、摘要与结果；seq/t 由账本自己盖，durationMs 由调用方量。
+     */
+    record(input) {
+        const entry = {
+            seq: this.nextSeq++,
+            t: this.now(),
+            command: input.command,
+            params: input.params,
+            ok: input.ok,
+            durationMs: Math.max(0, Math.round(input.durationMs)),
+        };
+        if (input.tabId !== undefined)
+            entry.tabId = input.tabId;
+        if (input.code !== undefined)
+            entry.code = input.code;
+        if (input.effectState !== undefined)
+            entry.effectState = input.effectState;
+        if (input.error !== undefined) {
+            entry.error = [...input.error].length > AUDIT_ERROR_MAX_CHARS
+                ? `${[...input.error].slice(0, AUDIT_ERROR_MAX_CHARS).join('')}…`
+                : input.error;
+        }
+        this.entries.push(entry);
+        // 环形缓冲：超出上限从最旧的一端丢。seq 不回收——调用方拿 seq 分页时
+        // 「中间缺了号」本身就是「被挤掉了」的机器可读信号。
+        if (this.entries.length > AUDIT_MAX_ENTRIES)
+            this.entries.splice(0, this.entries.length - AUDIT_MAX_ENTRIES);
+        return entry;
+    }
+    /** 现有条目数（被挤掉的不算）。 */
+    size() {
+        return this.entries.length;
+    }
+    /**
+     * 过滤并取最新的一批。
+     * @param filter - tabId / 命令子串 / sinceSeq / limit；返回按 seq 升序。
+     */
+    list(filter = {}) {
+        let matched = this.entries;
+        if (filter.tabId !== undefined)
+            matched = matched.filter((e) => e.tabId === filter.tabId);
+        if (filter.command !== undefined && filter.command.length > 0) {
+            const needle = filter.command.toLowerCase();
+            matched = matched.filter((e) => e.command.toLowerCase().includes(needle));
+        }
+        if (filter.sinceSeq !== undefined) {
+            const floor = filter.sinceSeq;
+            matched = matched.filter((e) => e.seq > floor);
+        }
+        const limit = Math.min(AUDIT_MAX_ENTRIES, Math.max(1, Math.trunc(filter.limit ?? 50)));
+        return matched.slice(Math.max(0, matched.length - limit));
+    }
+}

package/lib/types/index.js

@@ -24,6 +24,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { BridgeServer, cleanupArtifacts } from "./server.js";
 import { BridgeError, classify } from "./errors.js";
 import { policyRefusal } from "./policy.js";
+import { AUDIT_MAX_ENTRIES, AuditLog, summarizeAuditParams } from "./audit.js";
 /** Navigation wait ceiling (same as browser_wait); the bridge gets this plus BRIDGE_MARGIN_MS. */
 const NAV_MAX_MS = 120_000;
 /**
@@ -116,6 +117,8 @@ class BridgeController {
     lastError;
     chain = Promise.resolve();
     current;
+    /** 操作审计账本（内存环形缓冲，200 条；命令层记录，见 audit.ts 顶部注释）。 */
+    audit = new AuditLog();
     constructor(log) {
         this.log = log;
     }
@@ -123,6 +126,14 @@ class BridgeController {
     get shotsDir() {
         return this.current === undefined ? undefined : path.resolve(this.current.shotsDir);
     }
+    /**
+     * Current policy flags. Tools that compose several commands (browser_drag
+     * runs `cdp`/`eval`) read this to refuse with a tool-level message; the
+     * per-command gate in execute() stays as the enforcement backstop.
+     */
+    get policy() {
+        return { readOnly: this.current?.readOnly === true, allowScript: this.current?.allowScript !== false };
+    }
     /** Version the connected extension reported in its hello frame, if any. */
     extensionVersion() {
         return this.server?.status.hello?.version;
@@ -153,6 +164,16 @@ class BridgeController {
     requireExtensionCommand(command, since) {
         if (this.hasExtensionCommand(command))
             return;
+        // 预检拒绝也要上账：这是「升级插件后模型发现功能不可用」的最常见现场。
+        this.audit.record({
+            command,
+            params: '',
+            ok: false,
+            code: 'extension_outdated',
+            effectState: 'not_started',
+            error: `connected extension v${this.extensionVersion() ?? '?'} lacks ${command} (added in ${since})`,
+            durationMs: 0,
+        });
         throw extensionOutdatedError(this.extensionVersion(), command, since);
     }
     /**
@@ -213,12 +234,34 @@ class BridgeController {
      * @returns the extension's result payload verbatim.
      */
     async execute(command, params, signal, timeoutMs) {
-        this.policyGate(command, params);
-        const server = this.server;
-        if (server === undefined) {
-            throw classify(command, new Error(this.lastError ?? '浏览器控制未启用 —— 在 profile 的 cordis.patch.yml 里给 browser-bridge 配 enabled: true（dsh 0.1.7+ 的宿主也会在设置 → 插件 自动列出本插件开关；0.1.2 及更早的宿主没有这张卡片，只能改配置文件）'));
+        const started = Date.now();
+        const summary = summarizeAuditParams(command, params);
+        const tabId = typeof params.tabId === 'number' ? params.tabId : undefined;
+        try {
+            this.policyGate(command, params);
+            const server = this.server;
+            if (server === undefined) {
+                throw classify(command, new Error(this.lastError ?? '浏览器控制未启用 —— 在 profile 的 cordis.patch.yml 里给 browser-bridge 配 enabled: true（dsh 0.1.7+ 的宿主也会在设置 → 插件 自动列出本插件开关；0.1.2 及更早的宿主没有这张卡片，只能改配置文件）'));
+            }
+            const result = await server.execute(command, params, timeoutMs === undefined ? { signal } : { signal, timeoutMs });
+            this.audit.record({ command, tabId, params: summary, ok: true, durationMs: Date.now() - started });
+            return result;
+        }
+        catch (error) {
+            const code = error.code;
+            const effectState = error.effectState;
+            this.audit.record({
+                command,
+                tabId,
+                params: summary,
+                ok: false,
+                code: typeof code === 'string' ? code : undefined,
+                effectState: typeof effectState === 'string' ? effectState : undefined,
+                error: errorMessage(error),
+                durationMs: Date.now() - started,
+            });
+            throw error;
         }
-        return server.execute(command, params, timeoutMs === undefined ? { signal } : { signal, timeoutMs });
     }
     /**
      * Refuse a command the local policy forbids, before anything is sent or deleted.
@@ -244,19 +287,38 @@ class BridgeController {
      * @returns counts and names of what was removed.
      */
     async cleanup() {
-        // cleanup() 不经过 execute()，所以它必须自己站一次闸门：否则只读档下
-        // 模型仍能用 browser_cleanup 删掉用户的整个截图目录。
-        this.policyGate('cleanup');
-        const dir = this.shotsDir;
-        if (dir === undefined)
-            throw classify('cleanup', new Error('browser-bridge is not configured yet —— 浏览器控制尚未加载配置，无法确定清理目录'));
+        const started = Date.now();
         try {
-            return await cleanupArtifacts({ shotsDir: dir });
+            // cleanup() 不经过 execute()，所以它必须自己站一次闸门：否则只读档下
+            // 模型仍能用 browser_cleanup 删掉用户的整个截图目录。
+            this.policyGate('cleanup');
+            const dir = this.shotsDir;
+            if (dir === undefined)
+                throw classify('cleanup', new Error('browser-bridge is not configured yet —— 浏览器控制尚未加载配置，无法确定清理目录'));
+            try {
+                const result = await cleanupArtifacts({ shotsDir: dir });
+                this.audit.record({ command: 'cleanup', params: '{}', ok: true, durationMs: Date.now() - started });
+                return result;
+            }
+            catch (error) {
+                // 删除是逐条进行的，中途失败时前面的文件已经没了；不包一层分类，
+                // 模型拿到的就是一句没有 code / effectState 的裸 fs 错误。
+                throw classify('cleanup', error);
+            }
         }
         catch (error) {
-            // 删除是逐条进行的，中途失败时前面的文件已经没了；不包一层分类，
-            // 模型拿到的就是一句没有 code / effectState 的裸 fs 错误。
-            throw classify('cleanup', error);
+            const code = error.code;
+            const effectState = error.effectState;
+            this.audit.record({
+                command: 'cleanup',
+                params: '{}',
+                ok: false,
+                code: typeof code === 'string' ? code : undefined,
+                effectState: typeof effectState === 'string' ? effectState : undefined,
+                error: errorMessage(error),
+                durationMs: Date.now() - started,
+            });
+            throw error;
         }
     }
     /** Stop the listener; safe to call repeatedly and during teardown. */
@@ -1683,6 +1745,338 @@ function applyBrowserTools(ctx, controller) {
             return await controller.execute('metrics', params, exec.signal);
         },
     }));
+    registerDragTool(ctx, controller);
+    registerAuditTool(ctx, controller);
+}
+/* ------------------- browser_drag: composed plugin-side over the cdp channel ------------------- */
+/** One CDP round-trip over the embedded `cdp` passthrough (extension v1.7.2+). */
+async function cdpCall(ctrl, tabId, method, params, signal) {
+    return await ctrl.execute('cdp', { method, params, tabId }, signal);
+}
+function dragTargetArgs(selector, x, y, side) {
+    const hasSel = typeof selector === 'string' && selector.length > 0;
+    const hasX = typeof x === 'number' && Number.isFinite(x);
+    const hasY = typeof y === 'number' && Number.isFinite(y);
+    if (hasSel && (hasX || hasY))
+        throw new Error(`${side}: give either "${side}" (CSS selector) or "${side}X"/"${side}Y" coordinates, not both`);
+    if (!hasSel && !(hasX && hasY))
+        throw new Error(`${side}: needs a CSS selector ("${side}") or both "${side}X" and "${side}Y" coordinates`);
+    if (hasSel)
+        return { selector };
+    return { x, y };
+}
+/**
+ * Resolve a drag endpoint. Selector endpoints become viewport coordinates via
+ * the CDP DOM domain — no page JavaScript, so mouse mode also works with
+ * `allowScript: false`. Top document only; cross-origin iframes are a later
+ * iteration.
+ */
+async function resolveDragPoint(ctrl, tabId, target, signal) {
+    if (target.selector === undefined)
+        return { x: target.x, y: target.y };
+    const selector = target.selector;
+    const doc = await cdpCall(ctrl, tabId, 'DOM.getDocument', { depth: 0 }, signal);
+    const rootId = doc?.root?.nodeId;
+    if (typeof rootId !== 'number')
+        throw new Error('DOM.getDocument returned no root node');
+    const found = await cdpCall(ctrl, tabId, 'DOM.querySelector', { nodeId: rootId, selector }, signal);
+    const nodeId = found?.nodeId ?? 0;
+    if (nodeId === 0)
+        throw new Error(`no element matches selector ${JSON.stringify(selector)} (top document only)`);
+    await cdpCall(ctrl, tabId, 'DOM.scrollIntoViewIfNeeded', { nodeId }, signal);
+    let box;
+    try {
+        box = await cdpCall(ctrl, tabId, 'DOM.getBoxModel', { nodeId }, signal);
+    }
+    catch (error) {
+        throw new Error(`cannot measure ${JSON.stringify(selector)} — hidden, zero-size or detached? (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const q = box?.model?.content;
+    if (!Array.isArray(q) || q.length < 8)
+        throw new Error(`DOM.getBoxModel returned no quad for ${JSON.stringify(selector)}`);
+    const x = (q[0] + q[2] + q[4] + q[6]) / 4;
+    const y = (q[1] + q[3] + q[5] + q[7]) / 4;
+    const width = typeof box?.model?.width === 'number' ? box.model.width : Math.hypot(q[2] - q[0], q[3] - q[1]);
+    const height = typeof box?.model?.height === 'number' ? box.model.height : Math.hypot(q[4] - q[2], q[5] - q[3]);
+    return { selector, x, y, width, height, nodeId };
+}
+/** Whether the source declares the native HTML5 `draggable` attribute. */
+async function sourceIsDraggable(ctrl, tabId, nodeId, signal) {
+    const attrs = await cdpCall(ctrl, tabId, 'DOM.getAttributes', { nodeId }, signal);
+    const list = Array.isArray(attrs?.attributes) ? attrs.attributes.map(String) : [];
+    const at = list.indexOf('draggable');
+    return at >= 0 && list[at + 1] === 'true';
+}
+/**
+ * Synthesize a native-order HTML5 drag in the page: dragstart on the source,
+ * dragenter/dragover on the target, drop only when dragover was prevented
+ * (the browser's own rule), dragend on the source, all sharing one DataTransfer.
+ * Untrusted events — pages that gate on `event.isTrusted` will ignore them,
+ * which the tool description states instead of pretending otherwise.
+ */
+function html5DragExpression(fromSelector, to) {
+    const toExpr = to.selector !== undefined
+        ? `document.querySelector(${JSON.stringify(to.selector)})`
+        : `document.elementFromPoint(${to.x}, ${to.y})`;
+    return `(() => {
+  const src = document.querySelector(${JSON.stringify(fromSelector)});
+  if (!src) return { error: 'no element matches from selector ' + ${JSON.stringify(fromSelector)} };
+  const dst = ${toExpr};
+  if (!dst) return { error: 'target element not found' };
+  const dt = new DataTransfer();
+  const log = [];
+  const sr = src.getBoundingClientRect();
+  const dr = dst.getBoundingClientRect();
+  const sx = sr.left + sr.width / 2, sy = sr.top + sr.height / 2;
+  const tx = dr.left + dr.width / 2, ty = dr.top + dr.height / 2;
+  const fire = (type, target, cx, cy) => {
+    const ev = new DragEvent(type, { bubbles: true, cancelable: true, composed: true, dataTransfer: dt, clientX: cx, clientY: cy });
+    target.dispatchEvent(ev);
+    log.push({ type, defaultPrevented: ev.defaultPrevented });
+    return ev.defaultPrevented;
+  };
+  const startCancelled = fire('dragstart', src, sx, sy);
+  let dragenterDefaultPrevented = false, overPrevented = false, dropFired = false, dropPrevented = false;
+  if (!startCancelled) {
+    dragenterDefaultPrevented = fire('dragenter', dst, tx, ty);
+    overPrevented = fire('dragover', dst, tx, ty);
+    if (overPrevented) {
+      dropFired = true;
+      dropPrevented = fire('drop', dst, tx, ty);
+    }
+  }
+  fire('dragend', src, sx, sy);
+  return { startCancelled, dragenterDefaultPrevented, overPrevented, dropFired, dropPrevented, events: log.length, log };
+})()`;
+}
+function roundDragPoint(p) {
+    const out = {
+        x: Math.round(p.x * 100) / 100,
+        y: Math.round(p.y * 100) / 100,
+    };
+    if (p.selector !== undefined)
+        out.selector = p.selector;
+    if (p.width !== undefined)
+        out.width = Math.round(p.width * 100) / 100;
+    if (p.height !== undefined)
+        out.height = Math.round(p.height * 100) / 100;
+    return out;
+}
+function registerDragTool(ctx, controller) {
+    ctx.tools.register(defineTool({
+        name: 'browser_drag',
+        description: 'Drag a page element or point onto another with real input. mode "mouse" sends trusted press→moves→release input via CDP (canvas, sliders, sortable widgets); mode "html5" synthesizes dragstart/dragover/drop in the page for [draggable] elements and needs page scripting; "auto" (default) picks html5 only when the source declares draggable="true". Endpoints are CSS selectors (top document) or fromX/fromY + toX/toY viewport coordinates. Needs browser extension v1.7.2+ (embedded cdp channel).',
+        parameters: {
+            from: { type: 'string', description: 'CSS selector of the drag source; use fromX/fromY instead for raw coordinates.' },
+            to: { type: 'string', description: 'CSS selector of the drop target; use toX/toY instead for raw coordinates.' },
+            fromX: { type: 'number', description: 'Viewport x of the drag start point (with fromY).' },
+            fromY: { type: 'number', description: 'Viewport y of the drag start point (with fromX).' },
+            toX: { type: 'number', description: 'Viewport x of the drop point (with toY).' },
+            toY: { type: 'number', description: 'Viewport y of the drop point (with toX).' },
+            tabId: { type: 'number', description: 'Target tab; defaults to the active tab.' },
+            mode: { type: 'string', description: '"auto" (default), "mouse" or "html5" — see the tool description.' },
+            steps: { type: 'number', description: 'Intermediate mouse moves in mouse mode, 1–50 (default 12).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    tabId: { type: 'number', required: true },
+                    mode: { type: 'string', required: true },
+                    from: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            selector: { type: 'string' },
+                            x: { type: 'number' },
+                            y: { type: 'number' },
+                            width: { type: 'number' },
+                            height: { type: 'number' },
+                        },
+                    },
+                    to: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            selector: { type: 'string' },
+                            x: { type: 'number' },
+                            y: { type: 'number' },
+                            width: { type: 'number' },
+                            height: { type: 'number' },
+                        },
+                    },
+                    steps: { type: 'number' },
+                    dispatched: { type: 'number' },
+                    startCancelled: { type: 'boolean' },
+                    dragenterDefaultPrevented: { type: 'boolean' },
+                    overPrevented: { type: 'boolean' },
+                    dropFired: { type: 'boolean' },
+                    dropPrevented: { type: 'boolean' },
+                    events: { type: 'number' },
+                    elapsedMs: { type: 'number', required: true },
+                },
+            },
+            render: (_args, value) => {
+                const v = value;
+                const d = (p) => p?.selector !== undefined ? p.selector : `(${p?.x ?? '?'},${p?.y ?? '?'})`;
+                if (v.mode === 'mouse') {
+                    return [{ type: 'text', text: `Tab ${v.tabId}: dragged ${d(v.from)} → ${d(v.to)} with mouse input (${v.steps} steps, ${v.dispatched} dispatches, ${v.elapsedMs}ms)` }];
+                }
+                const verdict = v.startCancelled === true
+                    ? 'dragstart was cancelled by the page — nothing dropped'
+                    : v.overPrevented === true
+                        ? (v.dropPrevented === true ? 'drop fired and was handled' : 'drop fired but no drop handler ran')
+                        : 'target did not accept the drop (no dragover preventDefault)';
+                return [{ type: 'text', text: `Tab ${v.tabId}: dragged ${d(v.from)} → ${d(v.to)} with html5 events (${v.events} events, ${v.elapsedMs}ms) — ${verdict}` }];
+            },
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: `Drag ${args.from ?? `(${args.fromX},${args.fromY})`} → ${args.to ?? `(${args.toX},${args.toY})`}`,
+            kind: 'other',
+        }),
+        async execute(args, exec) {
+            const mode = args.mode === undefined ? 'auto' : args.mode;
+            if (mode !== 'auto' && mode !== 'mouse' && mode !== 'html5')
+                throw new Error(`mode must be "auto", "mouse" or "html5" — got ${JSON.stringify(mode)}`);
+            const from = dragTargetArgs(args.from, args.fromX, args.fromY, 'from');
+            const to = dragTargetArgs(args.to, args.toX, args.toY, 'to');
+            controller.requireExtensionCommand('cdp', '1.7.2');
+            if (controller.policy.readOnly)
+                throw new Error('browser_drag changes page state and read-only mode is on — turn readOnly off in the browser-bridge config to drag');
+            let tabId = args.tabId;
+            if (tabId === undefined) {
+                const listing = await controller.execute('tabs.list', {}, exec.signal);
+                if (typeof listing?.activeTabId !== 'number')
+                    throw new Error('could not resolve the active tab — pass tabId explicitly');
+                tabId = listing.activeTabId;
+            }
+            const started = Date.now();
+            let resolvedMode = mode === 'auto' ? 'mouse' : mode;
+            let source;
+            if (mode !== 'html5')
+                source = await resolveDragPoint(controller, tabId, from, exec.signal);
+            if (mode === 'auto' && source?.nodeId !== undefined && await sourceIsDraggable(controller, tabId, source.nodeId, exec.signal)) {
+                resolvedMode = 'html5';
+            }
+            if (resolvedMode === 'mouse') {
+                const target = await resolveDragPoint(controller, tabId, to, exec.signal);
+                const steps = Math.min(50, Math.max(1, Math.trunc(typeof args.steps === 'number' ? args.steps : 12)));
+                const sx = source.x, sy = source.y, tx = target.x, ty = target.y;
+                const dispatch = async (params) => {
+                    await cdpCall(controller, tabId, 'Input.dispatchMouseEvent', params, exec.signal);
+                };
+                await dispatch({ type: 'mouseMoved', x: sx, y: sy, button: 'none', buttons: 0 });
+                await dispatch({ type: 'mousePressed', x: sx, y: sy, button: 'left', buttons: 1, clickCount: 1 });
+                for (let i = 1; i <= steps; i++) {
+                    const f = i / steps;
+                    await dispatch({ type: 'mouseMoved', x: sx + (tx - sx) * f, y: sy + (ty - sy) * f, button: 'left', buttons: 1 });
+                }
+                await dispatch({ type: 'mouseReleased', x: tx, y: ty, button: 'left', buttons: 0, clickCount: 1 });
+                await dispatch({ type: 'mouseMoved', x: tx, y: ty, button: 'none', buttons: 0 });
+                const receipt = {
+                    tabId,
+                    mode: 'mouse',
+                    from: roundDragPoint(source),
+                    to: roundDragPoint(target),
+                    steps,
+                    dispatched: steps + 4,
+                    elapsedMs: Date.now() - started,
+                };
+                return receipt;
+            }
+            if (from.selector === undefined)
+                throw new Error('html5 mode needs a CSS selector for "from" (a point has no draggable element)');
+            if (!controller.policy.allowScript)
+                throw new Error('html5 drag synthesizes DOM events and needs page scripting — allowScript is off; use mode:"mouse" or re-enable the script switch');
+            const raw = await controller.execute('eval', { expression: html5DragExpression(from.selector, to), tabId }, exec.signal);
+            const outcome = raw?.value;
+            if (outcome === undefined || typeof outcome !== 'object')
+                throw new Error('html5 drag expression returned no outcome — page may have navigated mid-drag');
+            if (typeof outcome.error === 'string')
+                throw new Error(outcome.error);
+            const receipt = {
+                tabId: typeof raw?.tabId === 'number' ? raw.tabId : tabId,
+                mode: 'html5',
+                from: from.selector !== undefined ? { selector: from.selector } : roundDragPoint(from),
+                to: to.selector !== undefined ? { selector: to.selector } : { x: to.x, y: to.y },
+                startCancelled: outcome.startCancelled === true,
+                dragenterDefaultPrevented: outcome.dragenterDefaultPrevented === true,
+                overPrevented: outcome.overPrevented === true,
+                dropFired: outcome.dropFired === true,
+                dropPrevented: outcome.dropPrevented === true,
+                events: typeof outcome.events === 'number' ? outcome.events : 0,
+                elapsedMs: Date.now() - started,
+            };
+            return receipt;
+        },
+    }));
+}
+function registerAuditTool(ctx, controller) {
+    ctx.tools.register(defineTool({
+        name: 'browser_audit',
+        description: 'Read this plugin session\'s in-memory audit trail: every command sent to the browser extension (and every policy/gate refusal), with redacted params, outcome code and duration. Newest last; capped at 200 entries and wiped when dsh restarts. Values typed into pages and cookie values are redacted; eval expressions are truncated. Plugin-local read — works in read-only mode.',
+        parameters: {
+            command: { type: 'string', description: 'Only entries whose command contains this substring (e.g. "nav", "cookies", "tabs").' },
+            tabId: { type: 'number', description: 'Only entries that carried this tabId.' },
+            sinceSeq: { type: 'number', description: 'Only entries with seq greater than this (paging).' },
+            limit: { type: 'number', description: `Max entries to return (newest last), 1–${AUDIT_MAX_ENTRIES}; default 50.` },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    total: { type: 'number', required: true },
+                    shown: { type: 'number', required: true },
+                    entries: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                seq: { type: 'number', required: true },
+                                t: { type: 'number', required: true },
+                                command: { type: 'string', required: true },
+                                tabId: { type: 'number' },
+                                params: { type: 'string', required: true },
+                                ok: { type: 'boolean', required: true },
+                                code: { type: 'string' },
+                                effectState: { type: 'string' },
+                                error: { type: 'string' },
+                                durationMs: { type: 'number', required: true },
+                            },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => {
+                const v = value;
+                if (v.entries.length === 0) {
+                    return [{ type: 'text', text: `Audit: ${v.total} entries, none match — the trail starts when a command is executed.` }];
+                }
+                const lines = v.entries.map((e) => {
+                    const tab = e.tabId === undefined ? '' : ` tab ${e.tabId}`;
+                    const outcome = e.ok ? 'ok' : `FAIL ${e.code ?? 'error'}${e.effectState ? `/${e.effectState}` : ''}`;
+                    const err = e.ok || e.error === undefined ? '' : ` — ${e.error}`;
+                    return `#${e.seq} ${formatClock(e.t)} ${e.command}${tab} ${outcome} ${e.durationMs}ms ${e.params}${err}`;
+                });
+                return [{ type: 'text', text: clampRendered(`Audit: ${v.total} entries (showing ${v.shown})\n${lines.join('\n')}`) }];
+            },
+        },
+        presentCall: () => ({ card: 'generic', title: 'Browser audit', kind: 'other' }),
+        async execute(args) {
+            const entries = controller.audit.list({
+                tabId: args.tabId,
+                command: args.command,
+                sinceSeq: args.sinceSeq,
+                limit: args.limit,
+            });
+            return { total: controller.audit.size(), shown: entries.length, entries };
+        },
+    }));
 }
 /** Cordis plugin entry: wire the settings-driven lifecycle plus the model-facing tools. */
 export function apply(ctx, config) {

package/llms.txt

@@ -42,7 +42,7 @@ Chrome 浏览器扩展 + DeepSeek Harness 插件，让 AI Agent 通过 CDP 驱
 
 ## 关键文件
 
-- `src/index.ts` - 25 个 `browser_*` 工具注册 + settings 接线的版本兼容分支
+- `src/index.ts` - 27 个 `browser_*` 工具注册 + settings 接线的版本兼容分支
 - `src/policy.ts` - 三张互不相同的表：只读白名单、脚本命令、插件本地破坏性命令（`browser_cleanup` 不经过 `execute()`，必须自己站闸门）
 - `src/server.ts` - WebSocket 服务 + HTTP 面（鉴权、来源校验、状态页）
 - `src/ws.ts` - RFC 6455 帧编解码