@roll-agent/browser-use-agent 0.7.7 → 0.9.0

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

@@ -76,12 +76,51 @@ export type NativeRecommendCardInspection = {
     readonly cardSelector: string;
     readonly candidateId: string;
     readonly name: string;
+    readonly age?: string;
+    readonly experience?: string;
+    readonly education?: string;
+    readonly workStatus?: string;
+    readonly company?: string;
+    readonly currentPosition?: string;
+    readonly expectedLocation?: string;
+    readonly expectedPosition?: string;
+    readonly expectedSalary?: string;
     readonly hasGreetButton: boolean;
     readonly error?: string;
 };
 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;
@@ -137,6 +176,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/recruitment-events/client.d.ts

@@ -0,0 +1,41 @@
+import type { AgentLogger } from "@roll-agent/sdk";
+export declare const RECRUITMENT_EVENT_TYPES: readonly ["message_received", "message_sent", "candidate_contacted", "wechat_exchanged"];
+type RecruitmentEventType = (typeof RECRUITMENT_EVENT_TYPES)[number];
+type RecruitmentCandidate = {
+    readonly name: string;
+    readonly position: string;
+    readonly age?: string;
+    readonly gender?: string;
+    readonly education?: string;
+    readonly expectedSalary?: string;
+    readonly expectedLocation?: string;
+};
+type RecruitmentJob = {
+    readonly jobId?: number;
+    readonly jobName?: string;
+};
+type RecruitmentEventDetails = Readonly<Record<string, string | number | boolean | undefined>>;
+export type RecruitmentEventPayload = {
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly sourcePlatform: "zhipin";
+    readonly dataSource: "api_callback";
+    readonly eventType: RecruitmentEventType;
+    readonly eventTime: string;
+    readonly candidate: RecruitmentCandidate;
+    readonly job?: RecruitmentJob;
+    readonly details: RecruitmentEventDetails;
+};
+export type RecruitmentEventDraft = Omit<RecruitmentEventPayload, "agentId" | "eventTime"> & {
+    readonly eventTime?: string;
+};
+type RecruitmentEventPostDeps = {
+    readonly fetch: typeof fetch;
+    readonly env: NodeJS.ProcessEnv;
+};
+type RecruitmentEventRecorder = (event: RecruitmentEventDraft, logger: AgentLogger) => Promise<void> | void;
+export declare function buildRecruitmentIdempotencyKey(prefix: string, parts: ReadonlyArray<string | number | boolean | undefined>): string;
+export declare function recordRecruitmentEventAsync(event: RecruitmentEventDraft, logger: AgentLogger): void;
+export declare function setRecruitmentEventRecorderForTests(recorder: RecruitmentEventRecorder | undefined): void;
+export declare function setRecruitmentEventPostDepsForTests(deps: Partial<RecruitmentEventPostDeps> | undefined): void;
+export {};

package/dist/recruitment-events/zhipin-events.d.ts

@@ -0,0 +1,34 @@
+import type { AgentLogger } from "@roll-agent/sdk";
+import type { NativeCandidateChatDetails, NativeRecommendGreetResult } from "../pages/zhipin/native-page.ts";
+type ZhipinUnreadCandidate = {
+    readonly conversationId: string;
+    readonly candidateId: string;
+    readonly name: string;
+    readonly position: string;
+    readonly preview: string;
+    readonly unreadCount: number;
+    readonly hasUnread: boolean;
+};
+type ZhipinMessageSentInput = {
+    readonly conversationId: string;
+    readonly candidateId: string;
+    readonly replyId: string;
+    readonly candidateName: string;
+    readonly message: string;
+    readonly unreadCountBeforeReply: number;
+    readonly candidateDetails?: NativeCandidateChatDetails;
+};
+type ZhipinWechatRequestedInput = {
+    readonly conversationId: string;
+    readonly candidateId: string;
+    readonly candidateName: string;
+    readonly exchangeType?: "requested" | "accepted";
+    readonly wechatNumber?: string;
+    readonly candidateDetails?: NativeCandidateChatDetails;
+};
+export declare function recordZhipinMessageReceivedEvents(candidates: ReadonlyArray<ZhipinUnreadCandidate>, logger: AgentLogger): void;
+export declare function recordZhipinMessageSentEvent(input: ZhipinMessageSentInput, logger: AgentLogger): void;
+export declare function recordZhipinCandidateContactedEvent(result: NativeRecommendGreetResult, logger: AgentLogger): void;
+export declare function recordZhipinWechatRequestedEvent(input: ZhipinWechatRequestedInput, logger: AgentLogger): void;
+export declare function recordZhipinWechatCompletedEvents(details: NativeCandidateChatDetails, conversationId: string, candidateId: string, logger: AgentLogger): void;
+export {};

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/browser-use-agent",
-  "version": "0.7.7",
+  "version": "0.9.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/env.yaml

@@ -2,7 +2,21 @@ required:
   - name: REPLY_AUTHORITY_KEYS_URL
     purpose: Reply Authority Service 公钥分发端点；`zhipin_send_reply` 启动预热和本地 Ed25519 验签都依赖它
     example: https://reply-authority.duliday.com/.well-known/reply-authority-keys
+  - name: RECRUITMENT_EVENTS_DEFAULT_AGENT_ID
+    purpose: 单 browser-use 实例 / 单 Boss 账号部署下的默认招聘业务 Agent ID；招聘事件默认启用，上报时必须用它做归因
+    example: zhipin-shanghai-kfc-001
+  - name: RECRUITMENT_EVENTS_API_TOKEN
+    purpose: 招聘事件 Open API Bearer token；公开 npm 包不内置兜底 token，必须由部署环境提供
+    example: token_xxx
 optional:
+  - name: RECRUITMENT_EVENTS_ENABLED
+    purpose: 是否启用招聘事件埋点上报；未设置时默认启用，设为 `"false"` 可关闭
+    default: "true"
+    example: "false"
+  - name: RECRUITMENT_EVENTS_API_BASE_URL
+    purpose: 招聘事件 Open API base URL；工具成功后会调用 `/api/v1/recruitment-events`
+    default: https://huajune.duliday.com
+    example: https://example.com
   - name: BROWSER_VISUAL_CURSOR
     purpose: 在可见浏览器页面内显示 browser-use 的页内虚拟指针和点击波纹；默认开启，设为 `"false"` 可关闭
     default: "true"

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`：连续滚动没有新去重项。