@roll-agent/browser-use-agent 0.7.6 → 0.8.0

package/dist/native-mouse-motion.d.ts

@@ -0,0 +1,55 @@
+import type { NativeCdpController, NativeCdpMouseEventInput } from "@roll-agent/browser";
+export type NativeMousePoint = {
+    readonly x: number;
+    readonly y: number;
+};
+export type NativeMouseMotionPreview = {
+    readonly points: readonly NativeMousePoint[];
+    readonly durationMs: number;
+};
+export type NativeMouseClickPreview = {
+    readonly point: NativeMousePoint;
+    readonly durationMs: number;
+};
+export type NativeMouseMotionObserver = {
+    previewMouseMotion(preview: NativeMouseMotionPreview): Promise<void>;
+    previewMouseClick?(preview: NativeMouseClickPreview): Promise<void>;
+};
+export type NativeMouseMotionControllerOptions = {
+    readonly sleep?: (ms: number) => Promise<void>;
+    readonly stepDelayMs?: number;
+};
+export type NativeMouseMoveOptions = {
+    readonly button?: NativeCdpMouseEventInput["button"];
+    readonly buttons?: number;
+    readonly motionObserver?: NativeMouseMotionObserver;
+    readonly stepDelayMs?: number;
+};
+export type NativeMouseClickOptions = {
+    readonly button?: NativeCdpMouseEventInput["button"];
+    readonly clickCount?: number;
+    readonly motionObserver?: NativeMouseMotionObserver;
+    readonly preClickDelayMs?: number;
+    readonly pressDurationMs?: number;
+    readonly settleMs?: number;
+};
+export type NativeMouseDragOptions = {
+    readonly motionObserver?: NativeMouseMotionObserver;
+    readonly pressDurationMs?: number;
+    readonly stepDelayMs?: number;
+};
+type NativeMouseDispatcher = Pick<NativeCdpController, "dispatchMouseEvent">;
+export declare function createNativeMousePath(currentPoint: NativeMousePoint | undefined, targetPoint: NativeMousePoint): readonly NativeMousePoint[];
+export declare class NativeMouseMotionController {
+    private readonly dispatcher;
+    private readonly sleep;
+    private readonly defaultStepDelayMs;
+    private lastPoint;
+    constructor(dispatcher: NativeMouseDispatcher, options?: NativeMouseMotionControllerOptions);
+    reset(point?: NativeMousePoint): void;
+    moveTo(targetPoint: NativeMousePoint, options?: NativeMouseMoveOptions): Promise<NativeMouseMotionPreview>;
+    click(targetPoint: NativeMousePoint, options?: NativeMouseClickOptions): Promise<void>;
+    drag(fromPoint: NativeMousePoint, toPoint: NativeMousePoint, options?: NativeMouseDragOptions): Promise<void>;
+    private delayIfPositive;
+}
+export {};

package/dist/native-visual-activity-session.d.ts

@@ -1,4 +1,5 @@
 import type { VisualActivityTone } from "./visual-activity.ts";
+import type { NativeMouseClickPreview, NativeMouseMotionObserver, NativeMouseMotionPreview } from "./native-mouse-motion.ts";
 type NativeVisualTarget = {
     evaluateJson<T = unknown>(expression: string): Promise<T>;
 };
@@ -7,15 +8,13 @@ type NativeVisualHighlightOptions = {
     readonly padding?: number;
     readonly tone?: VisualActivityTone;
 };
-type NativeVisualPointOptions = {
-    readonly durationMs?: number;
-};
-export declare class NativeVisualActivitySession {
+export declare class NativeVisualActivitySession implements NativeMouseMotionObserver {
     private readonly target;
     constructor(target: NativeVisualTarget);
     begin(label: string, tone?: VisualActivityTone): Promise<boolean>;
     highlightSelector(selector: string, options?: NativeVisualHighlightOptions): Promise<boolean>;
-    highlightPoint(x: number, y: number, options?: NativeVisualPointOptions): Promise<boolean>;
+    previewMouseMotion(preview: NativeMouseMotionPreview): Promise<void>;
+    previewMouseClick(preview: NativeMouseClickPreview): Promise<void>;
     succeed(label: string, lingerMs?: number): Promise<boolean>;
     fail(label: string, lingerMs?: number): Promise<boolean>;
     clear(): Promise<boolean>;

package/dist/pages/zhipin/native-page.d.ts

@@ -1,4 +1,5 @@
 import type { BrowserContextManager, BrowserInspectablePage, BrowserRuntime, NativeCdpController } from "@roll-agent/browser";
+import { type NativeMouseMotionObserver } from "../../native-mouse-motion.ts";
 import type { DynamicListCollectionStopReason, DynamicListScrollResult, ScrollDirection } from "../shared/dynamic-list-scroller.ts";
 import { type ChatListItem, type ChatTarget, type OpenChatResult } from "./chat-navigation.ts";
 import { type ZhipinListSurface } from "./list-surfaces.ts";
@@ -37,6 +38,7 @@ export type ReadNativeRecommendCandidatesOptions = {
 export type OpenNativeChatOptions = ChatTarget & {
     readonly preferUnread?: boolean;
     readonly maxScrolls?: number;
+    readonly motionObserver?: NativeMouseMotionObserver;
 };
 export type NativeChatMessage = {
     readonly index: number;
@@ -80,6 +82,36 @@ export type NativeRecommendCardInspection = {
 export type NativeRecommendGreetResult = NativeRecommendCardInspection & {
     readonly clicked: boolean;
 };
+export type NativeRecommendJobOption = {
+    readonly index: number;
+    readonly value: string;
+    readonly label: string;
+    readonly isCurrent: boolean;
+};
+export type NativeRecommendJobSelectorState = {
+    readonly found: boolean;
+    readonly isOpen: boolean;
+    readonly currentLabel: string;
+    readonly currentValue: string;
+    readonly options: readonly NativeRecommendJobOption[];
+};
+export type NativeRecommendJobSelectRequest = {
+    readonly jobValue?: string;
+    readonly jobName?: string;
+    readonly index?: number;
+    readonly searchKeyword?: string;
+    readonly useSearch?: boolean;
+};
+export type NativeRecommendJobSelectResult = {
+    readonly success: boolean;
+    readonly status: "selected" | "already_selected" | "not_found" | "recommend_not_ready" | "selector_not_found";
+    readonly requested: NativeRecommendJobSelectRequest;
+    readonly current?: NativeRecommendJobOption;
+    readonly selected?: NativeRecommendJobOption;
+    readonly options: readonly NativeRecommendJobOption[];
+    readonly matchedCount: number;
+    readonly error?: string;
+};
 export type NativeWechatExchangeResult = {
     readonly success: boolean;
     readonly exchanged: boolean;
@@ -97,13 +129,8 @@ export type NativeDynamicListCollectionResult<TItem> = DynamicListScrollResult &
     readonly noNewRounds: number;
     readonly stopReason: DynamicListCollectionStopReason;
 };
-type NativeClickTarget = {
-    readonly found: boolean;
-    readonly x: number;
-    readonly y: number;
-};
 type NativeClickOptions = {
-    readonly onTargetResolved?: (target: NativeClickTarget) => Promise<void>;
+    readonly motionObserver?: NativeMouseMotionObserver;
     readonly preClickDelayMs?: number;
     readonly pressDurationMs?: number;
     readonly settleMs?: number;
@@ -118,6 +145,7 @@ export declare function openZhipinNativePagePort(options?: NativePageResolutionO
 export declare class ZhipinNativePagePort {
     private readonly target;
     private readonly controller;
+    private readonly mouse;
     private recommendFrameContextId;
     private recommendFrameContextFrameId;
     constructor(options: ZhipinNativePagePortOptions);
@@ -139,6 +167,14 @@ export declare class ZhipinNativePagePort {
     private dispatchNativeClick;
     hasRecommendList(): Promise<boolean>;
     waitForRecommendList(timeoutMs?: number): Promise<boolean>;
+    readRecommendJobSelectorState(): Promise<NativeRecommendJobSelectorState>;
+    private openRecommendJobSelector;
+    private setRecommendJobSearch;
+    private selectRecommendJobMatch;
+    private getCurrentRecommendJobOption;
+    private currentRecommendJobMatchesRequest;
+    private clickRecommendJobOption;
+    selectRecommendJob(request: NativeRecommendJobSelectRequest, options?: NativeClickOptions): Promise<NativeRecommendJobSelectResult>;
     clickSidebarSection(section: "chat" | "recommend", options?: NativeClickOptions): Promise<boolean>;
     scrollSurface(surface: ZhipinListSurface, options?: {
         readonly direction?: ScrollDirection;

package/dist/tools/zhipin-exchange-wechat.d.ts

@@ -1,7 +1,7 @@
 import { NativeVisualActivitySession } from "../native-visual-activity-session.ts";
 import { openZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
 import type { ZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
-type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightPoint" | "succeed" | "fail">;
+type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "previewMouseMotion" | "succeed" | "fail">;
 type ZhipinExchangeWechatDeps = {
     readonly openNativePagePort: typeof openZhipinNativePagePort;
     readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;

package/dist/tools/zhipin-filter-recommend-candidates.d.ts

@@ -1,7 +1,7 @@
 import { NativeVisualActivitySession } from "../native-visual-activity-session.ts";
 import { openZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
 import type { ZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
-type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "highlightPoint" | "succeed" | "fail">;
+type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "previewMouseMotion" | "succeed" | "fail">;
 type ZhipinFilterRecommendCandidatesDeps = {
     readonly openNativePagePort: typeof openZhipinNativePagePort;
     readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;

package/dist/tools/zhipin-open-chat-page.d.ts

@@ -2,9 +2,7 @@ import { NativeVisualActivitySession } from "../native-visual-activity-session.t
 import { openZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
 import type { ZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
 import { getContextManager } from "../runtime-holder.ts";
-type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "succeed" | "fail"> & {
-    readonly highlightPoint?: NativeVisualActivitySession["highlightPoint"];
-};
+type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "previewMouseMotion" | "succeed" | "fail">;
 type ZhipinOpenChatPageDeps = {
     readonly getContextManager: typeof getContextManager;
     readonly openNativePagePort: typeof openZhipinNativePagePort;

package/dist/tools/zhipin-open-chat.d.ts

@@ -1,7 +1,7 @@
 import { NativeVisualActivitySession } from "../native-visual-activity-session.ts";
 import { openZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
 import type { ZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
-type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "succeed" | "fail">;
+type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "previewMouseMotion" | "succeed" | "fail">;
 type ZhipinOpenChatDeps = {
     readonly openNativePagePort: typeof openZhipinNativePagePort;
     readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;

package/dist/tools/zhipin-open-recommend-page.d.ts

@@ -2,9 +2,7 @@ import { NativeVisualActivitySession } from "../native-visual-activity-session.t
 import { openZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
 import type { ZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
 import { getContextManager } from "../runtime-holder.ts";
-type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "succeed" | "fail"> & {
-    readonly highlightPoint?: NativeVisualActivitySession["highlightPoint"];
-};
+type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "previewMouseMotion" | "succeed" | "fail">;
 type ZhipinOpenRecommendPageDeps = {
     readonly getContextManager: typeof getContextManager;
     readonly openNativePagePort: typeof openZhipinNativePagePort;

package/dist/tools/zhipin-say-hello.d.ts

@@ -1,7 +1,7 @@
 import { NativeVisualActivitySession } from "../native-visual-activity-session.ts";
 import { openZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
 import type { ZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
-type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "highlightPoint" | "succeed" | "fail">;
+type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "previewMouseMotion" | "succeed" | "fail">;
 type ZhipinSayHelloDeps = {
     readonly openNativePagePort: typeof openZhipinNativePagePort;
     readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;

package/dist/tools/zhipin-scroll-view.d.ts

@@ -35,11 +35,16 @@ export declare const zhipinScrollView: import("@roll-agent/sdk").ToolDefinition<
         atEnd: boolean;
         itemCount: number;
     };
+    position: "unknown" | "middle" | "top" | "bottom" | "only-page";
     direction: "up" | "down";
     stepsRequested: number;
     stepsCompleted: number;
     reachedBoundary: boolean;
     surface: "chat-list" | "chat-history" | "recommend-list";
+    atTop: boolean;
+    atBottom: boolean;
+    canScrollUp: boolean;
+    canScrollDown: boolean;
     error?: string | undefined;
 }>;
 export {};

package/dist/tools/zhipin-select-recommend-job.d.ts

@@ -0,0 +1,47 @@
+import { NativeVisualActivitySession } from "../native-visual-activity-session.ts";
+import { openZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
+import type { ZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
+type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "previewMouseMotion" | "succeed" | "fail">;
+type ZhipinSelectRecommendJobDeps = {
+    readonly openNativePagePort: typeof openZhipinNativePagePort;
+    readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;
+};
+export declare function setZhipinSelectRecommendJobDepsForTests(override: Partial<ZhipinSelectRecommendJobDeps> | undefined): void;
+export declare const zhipinSelectRecommendJob: import("@roll-agent/sdk").ToolDefinition<{
+    index?: number | undefined;
+    jobValue?: string | undefined;
+    jobName?: string | undefined;
+    searchKeyword?: string | undefined;
+    useSearch?: boolean | undefined;
+}, {
+    options: {
+        value: string;
+        index: number;
+        label: string;
+        isCurrent: boolean;
+    }[];
+    status: "not_found" | "recommend_not_ready" | "selected" | "already_selected" | "selector_not_found";
+    success: boolean;
+    requested: {
+        index?: number | undefined;
+        jobValue?: string | undefined;
+        jobName?: string | undefined;
+        searchKeyword?: string | undefined;
+        useSearch?: boolean | undefined;
+    };
+    matchedCount: number;
+    error?: string | undefined;
+    current?: {
+        value: string;
+        index: number;
+        label: string;
+        isCurrent: boolean;
+    } | undefined;
+    selected?: {
+        value: string;
+        index: number;
+        label: string;
+        isCurrent: boolean;
+    } | undefined;
+}>;
+export {};

package/dist/tools/zhipin-send-reply.d.ts

@@ -2,7 +2,7 @@ import { NativeVisualActivitySession } from "../native-visual-activity-session.t
 import { openZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
 import type { ZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
 import { getReplyAuthorityKeysLoaded } from "../runtime-holder.ts";
-type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightPoint" | "succeed" | "fail">;
+type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "previewMouseMotion" | "succeed" | "fail">;
 type ZhipinSendReplyDeps = {
     readonly getReplyAuthorityKeysLoaded: typeof getReplyAuthorityKeysLoaded;
     readonly openNativePagePort: typeof openZhipinNativePagePort;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/browser-use-agent",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -45,8 +45,8 @@
   },
   "dependencies": {
     "zod": "^3.25.76",
-    "@roll-agent/sdk": "0.1.6",
-    "@roll-agent/browser": "0.3.0"
+    "@roll-agent/browser": "0.3.0",
+    "@roll-agent/sdk": "0.1.6"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"

package/references/zhipin-workflows.md

@@ -19,6 +19,25 @@
 4. `smart-reply-agent.generate_reply(..., target)`。
 5. `zhipin_send_reply(signedEnvelope)`。
 
+## 推荐岗位筛选
+
+推荐牛人页顶部岗位下拉的稳定主键是 `.job-list .job-item[value]`。
+
+优先级：
+
+1. 已知岗位 `value` 时，调用 `zhipin_select_recommend_job({ jobValue })`。
+2. 只知道标题时，调用 `zhipin_select_recommend_job({ jobName })`；工具会先匹配当前下拉项，未命中再使用下拉搜索框。
+3. `index` 只表示当前下拉快照顺序，筛选、搜索或岗位列表刷新后必须重新读取/选择，不要跨步骤长期保存。
+
+推荐链路：
+
+```text
+zhipin_open_recommend_page()
+  -> zhipin_select_recommend_job({ jobValue | jobName })
+  -> zhipin_filter_recommend_candidates(...)
+  -> zhipin_get_candidate_list(...)
+```
+
 ## 动态列表
 
 BOSS 页面通常不是整页滚动，而是内部容器滚动：
@@ -33,9 +52,10 @@ recommend-list  -> 推荐牛人列表，默认向下滚动，去重主键 candid
 
 1. 业务读取优先用自带 `autoScroll` 的工具：`zhipin_read_messages`、`zhipin_get_candidate_list`。
 2. `zhipin_scroll_view` 只用于显式翻页、调试和补救。
-3. `onlyUnread=true` 时不要依赖 `limit` 提前停止；未读会话可能在首屏之后。
-4. `maxScrolls` 用于成本控制，需要更完整列表时显式调大。
-5. 推荐列表若 `total < maxResults`，先看 `scrollStats.stopReason`：
+3. 只想检查聊天列表是否到顶/到底时调用 `zhipin_scroll_view({ surface: "chat-list", steps: 0 })`，读取顶层 `atTop` / `atBottom` / `canScrollUp` / `canScrollDown` / `position`。
+4. `onlyUnread=true` 时不要依赖 `limit` 提前停止；未读会话可能在首屏之后。
+5. `maxScrolls` 用于成本控制，需要更完整列表时显式调大。
+6. 推荐列表若 `total < maxResults`，先看 `scrollStats.stopReason`：
    - `target-count`：已达到目标数量。
    - `boundary`：触底并等待追加数据后仍无新增。
    - `no-new-items`：连续滚动没有新去重项。