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

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

@@ -76,6 +76,15 @@ 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;
 };
@@ -96,11 +105,13 @@ export type NativeRecommendJobSelectorState = {
     readonly options: readonly NativeRecommendJobOption[];
 };
 export type NativeRecommendJobSelectRequest = {
+    readonly jobRef?: string;
     readonly jobValue?: string;
     readonly jobName?: string;
     readonly index?: number;
     readonly searchKeyword?: string;
     readonly useSearch?: boolean;
+    readonly forceClick?: boolean;
 };
 export type NativeRecommendJobSelectResult = {
     readonly success: boolean;
@@ -112,6 +123,15 @@ export type NativeRecommendJobSelectResult = {
     readonly matchedCount: number;
     readonly error?: string;
 };
+export type NativeRecommendJobListResult = {
+    readonly success: boolean;
+    readonly status: "listed" | "recommend_not_ready" | "selector_not_found";
+    readonly current?: NativeRecommendJobOption;
+    readonly options: readonly NativeRecommendJobOption[];
+    readonly availableCount: number;
+    readonly canSwitch: boolean;
+    readonly error?: string;
+};
 export type NativeWechatExchangeResult = {
     readonly success: boolean;
     readonly exchanged: boolean;
@@ -173,7 +193,9 @@ export declare class ZhipinNativePagePort {
     private selectRecommendJobMatch;
     private getCurrentRecommendJobOption;
     private currentRecommendJobMatchesRequest;
+    private hasRecommendJobAlternative;
     private clickRecommendJobOption;
+    listRecommendJobs(options?: NativeClickOptions): Promise<NativeRecommendJobListResult>;
     selectRecommendJob(request: NativeRecommendJobSelectRequest, options?: NativeClickOptions): Promise<NativeRecommendJobSelectResult>;
     clickSidebarSection(section: "chat" | "recommend", options?: NativeClickOptions): Promise<boolean>;
     scrollSurface(surface: ZhipinListSurface, options?: {

package/dist/pages/zhipin/semantic-refs.d.ts

@@ -0,0 +1,48 @@
+export declare const ZHIPIN_CANDIDATE_REF_PREFIX: "@c";
+export declare const ZHIPIN_RECOMMEND_JOB_REF_PREFIX: "@j";
+export declare const ZHIPIN_CANDIDATE_REF_PATTERN: RegExp;
+export declare const ZHIPIN_RECOMMEND_JOB_REF_PATTERN: RegExp;
+export interface ZhipinCandidateRefSource {
+    readonly index: number;
+    readonly candidateId: string;
+    readonly name?: string;
+}
+export interface ZhipinCandidateRefTarget extends ZhipinCandidateRefSource {
+    readonly candidateRef: string;
+}
+export interface ZhipinRecommendJobRefSource {
+    readonly index: number;
+    readonly value: string;
+    readonly label: string;
+    readonly isCurrent: boolean;
+}
+export interface ZhipinRecommendJobRefTarget extends ZhipinRecommendJobRefSource {
+    readonly jobRef: string;
+}
+export declare function buildZhipinCandidateRef(index: number): string;
+export declare function buildZhipinRecommendJobRef(index: number): string;
+export declare function parseZhipinCandidateRef(ref: string): number | undefined;
+export declare function parseZhipinRecommendJobRef(ref: string): number | undefined;
+export declare function resolveZhipinCandidateIndex(input: {
+    readonly index?: number | undefined;
+    readonly candidateRef?: string | undefined;
+}): number;
+export declare function resolveZhipinCandidateIndices(input: {
+    readonly indices?: readonly number[] | undefined;
+    readonly candidateRefs?: readonly string[] | undefined;
+}): number[];
+export declare function rememberZhipinCandidateRefs(candidates: readonly ZhipinCandidateRefSource[]): ZhipinCandidateRefTarget[];
+export declare function rememberZhipinRecommendJobRefs(jobs: readonly ZhipinRecommendJobRefSource[]): ZhipinRecommendJobRefTarget[];
+export declare function clearZhipinCandidateRefsForTests(): void;
+export declare function clearZhipinRecommendJobRefsForTests(): void;
+export declare function resolveZhipinCandidateRefTarget(candidateRef: string): ZhipinCandidateRefTarget;
+export declare function resolveZhipinRecommendJobRefTarget(jobRef: string): ZhipinRecommendJobRefTarget;
+export declare function resolveZhipinCandidateTargets(input: {
+    readonly indices?: readonly number[] | undefined;
+    readonly candidateRefs?: readonly string[] | undefined;
+}): ZhipinCandidateRefTarget[];
+export declare function isZhipinCandidateTargetCurrent(target: ZhipinCandidateRefTarget, current: {
+    readonly found?: boolean;
+    readonly candidateId: string;
+    readonly name?: string;
+}): boolean;

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/navigate-active-tab.d.ts

@@ -1,13 +1,14 @@
-import { findTrackedPlatformPage } from "../pages/platform-page.ts";
-import { getContextManager } from "../runtime-holder.ts";
+import { setTimeout as delay } from "node:timers/promises";
+import { getContextManager, getRuntime } from "../runtime-holder.ts";
 import { detectPlatformFromUrl, matchesPlatformHost } from "../platforms.ts";
-import { toAttachedPageInfo } from "../page-info.ts";
+import { toNativePageInfo } from "../page-info.ts";
 type NavigateActiveTabDeps = {
     readonly getContextManager: typeof getContextManager;
+    readonly getRuntime: typeof getRuntime;
     readonly detectPlatformFromUrl: typeof detectPlatformFromUrl;
     readonly matchesPlatformHost: typeof matchesPlatformHost;
-    readonly findTrackedPlatformPage: typeof findTrackedPlatformPage;
-    readonly toAttachedPageInfo: typeof toAttachedPageInfo;
+    readonly toNativePageInfo: typeof toNativePageInfo;
+    readonly delay: typeof delay;
 };
 export declare function setNavigateActiveTabDepsForTests(override: Partial<NavigateActiveTabDeps> | undefined): void;
 export declare const navigateActiveTab: import("@roll-agent/sdk").ToolDefinition<{

package/dist/tools/zhipin-get-candidate-list.d.ts

@@ -28,6 +28,7 @@ export declare const zhipinGetCandidateList: import("@roll-agent/sdk").ToolDefin
         expectedSalary: string;
         tags: string[];
         buttonText: string;
+        candidateRef: string;
     }[];
     total: number;
     error?: string | undefined;

package/dist/tools/zhipin-list-recommend-jobs.d.ts

@@ -0,0 +1,31 @@
+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 ZhipinListRecommendJobsDeps = {
+    readonly openNativePagePort: typeof openZhipinNativePagePort;
+    readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;
+};
+export declare function setZhipinListRecommendJobsDepsForTests(override: Partial<ZhipinListRecommendJobsDeps> | undefined): void;
+export declare const zhipinListRecommendJobs: import("@roll-agent/sdk").ToolDefinition<{}, {
+    status: "recommend_not_ready" | "selector_not_found" | "listed";
+    success: boolean;
+    availableCount: number;
+    canSwitch: boolean;
+    jobs: {
+        value: string;
+        index: number;
+        label: string;
+        isCurrent: boolean;
+        jobRef?: string | undefined;
+    }[];
+    error?: string | undefined;
+    current?: {
+        value: string;
+        index: number;
+        label: string;
+        isCurrent: boolean;
+        jobRef?: string | undefined;
+    } | undefined;
+}>;
+export {};

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

@@ -1,8 +1,10 @@
 export declare const zhipinOpenResume: import("@roll-agent/sdk").ToolDefinition<{
-    index: number;
+    index?: number | undefined;
+    candidateRef?: string | undefined;
 }, {
     success: boolean;
     candidateId: string;
     candidateName: string;
     error?: string | undefined;
+    candidateRef?: string | undefined;
 }>;

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

@@ -9,7 +9,8 @@ type ZhipinSayHelloDeps = {
 };
 export declare function setZhipinSayHelloDepsForTests(override: Partial<ZhipinSayHelloDeps> | undefined): void;
 export declare const zhipinSayHello: import("@roll-agent/sdk").ToolDefinition<{
-    indices: number[];
+    indices?: number[] | undefined;
+    candidateRefs?: string[] | undefined;
 }, {
     success: boolean;
     results: {
@@ -17,6 +18,7 @@ export declare const zhipinSayHello: import("@roll-agent/sdk").ToolDefinition<{
         success: boolean;
         candidateId: string;
         candidateName: string;
+        candidateRef: string;
         error?: string | undefined;
     }[];
     summary: {

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

@@ -9,10 +9,12 @@ type ZhipinSelectRecommendJobDeps = {
 export declare function setZhipinSelectRecommendJobDepsForTests(override: Partial<ZhipinSelectRecommendJobDeps> | undefined): void;
 export declare const zhipinSelectRecommendJob: import("@roll-agent/sdk").ToolDefinition<{
     index?: number | undefined;
+    jobRef?: string | undefined;
     jobValue?: string | undefined;
     jobName?: string | undefined;
     searchKeyword?: string | undefined;
     useSearch?: boolean | undefined;
+    forceClick?: boolean | undefined;
 }, {
     options: {
         value: string;
@@ -24,10 +26,12 @@ export declare const zhipinSelectRecommendJob: import("@roll-agent/sdk").ToolDef
     success: boolean;
     requested: {
         index?: number | undefined;
+        jobRef?: string | undefined;
         jobValue?: string | undefined;
         jobName?: string | undefined;
         searchKeyword?: string | undefined;
         useSearch?: boolean | undefined;
+        forceClick?: boolean | undefined;
     };
     matchedCount: number;
     error?: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/browser-use-agent",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "zod": "^3.25.76",
-    "@roll-agent/browser": "0.3.0",
+    "@roll-agent/browser": "0.3.1",
     "@roll-agent/sdk": "0.1.6"
   },
   "devDependencies": {

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

@@ -4,6 +4,17 @@
 
 `conversationId` / `candidateId` 是跨 tool 的稳定主键，`index` 只表示当前 DOM 快照。
 
+## BOSS 页面入口
+
+`navigate_active_tab(url)` 是通用 native CDP 导航工具，但不能直接跳转 BOSS `/web/chat/*` 后台路径。
+
+页面切换规则：
+
+1. 进入聊天页：调用 `zhipin_open_chat_page()`，由工具点击站内「沟通」导航。
+2. 进入推荐牛人页：调用 `zhipin_open_recommend_page()`，由工具点击站内「推荐牛人」导航。
+3. 如果页面没有可用 BOSS 后台 target，不要用 `navigate_active_tab("https://www.zhipin.com/web/chat/recommend")` 补救；让用户先恢复登录后的 BOSS 页面或调用 `open_platform("zhipin")` 进入平台主页。
+4. `navigate_active_tab` 不触发 Playwright attach，也不调用 `Runtime.enable`，但它不替代 BOSS 业务语义导航工具。
+
 错误做法：
 
 - 把 `zhipin_read_messages` 返回数组里的 `index` 当作后续点击主键。
@@ -25,19 +36,50 @@
 
 优先级：
 
-1. 已知岗位 `value` 时，调用 `zhipin_select_recommend_job({ jobValue })`。
-2. 只知道标题时，调用 `zhipin_select_recommend_job({ jobName })`；工具会先匹配当前下拉项，未命中再使用下拉搜索框。
-3. `index` 只表示当前下拉快照顺序，筛选、搜索或岗位列表刷新后必须重新读取/选择，不要跨步骤长期保存。
+1. 先调用 `zhipin_list_recommend_jobs()` 读取当前岗位下拉，只读不切换。
+2. 如果 `canSwitch:false`，当前账号/页面没有可切换岗位，跳过岗位切换。
+3. 已知 `jobRef` 时，调用 `zhipin_select_recommend_job({ jobRef })`。
+4. 已知岗位 `value` 时，调用 `zhipin_select_recommend_job({ jobValue })`。
+5. 只知道标题时，调用 `zhipin_select_recommend_job({ jobName })`；工具会先匹配当前下拉项，未命中再使用下拉搜索框。
+6. `index` 只表示当前下拉快照顺序，筛选、搜索或岗位列表刷新后必须重新读取/选择，不要跨步骤长期保存。
+
+`jobRef` 规则：
+
+- `jobRef` 格式如 `@j1`，只来自 `zhipin_list_recommend_jobs()` 输出。
+- `jobRef` 只对最近一次岗位下拉快照有效；筛选、搜索、刷新或页面重开后必须重新读取。
+- orchestrator 不要自行构造 `jobRef`。
+- `jobRef` 不是安全边界，只是降低编排认知负担；真实 DOM 点击仍由工具解析到 `value` / `index` 后执行。
+- 默认不要传 `forceClick:true`；只有需要重新点击已选中的岗位项时才使用。
 
 推荐链路：
 
 ```text
 zhipin_open_recommend_page()
-  -> zhipin_select_recommend_job({ jobValue | jobName })
-  -> zhipin_filter_recommend_candidates(...)
+  -> zhipin_list_recommend_jobs()
+  -> zhipin_select_recommend_job({ jobRef | jobValue | jobName })  # 可选；canSwitch=false 时跳过
+  -> zhipin_filter_recommend_candidates(...)  # 可选；requires_vip 时跳过
   -> zhipin_get_candidate_list(...)
 ```
 
+## 推荐候选人筛选
+
+`zhipin_filter_recommend_candidates(ageMin?, ageMax?, gender?, activity?)` 只处理年龄、性别、活跃度三个维度。
+
+返回状态处理：
+
+| `status` | 含义 | 编排动作 |
+| --- | --- | --- |
+| `applied` | 筛选已提交 | 继续 `zhipin_get_candidate_list` |
+| `recommend_not_ready` | 推荐页未就绪 | 先调用 `zhipin_open_recommend_page()` |
+| `requires_vip` | 当前账号没有权限使用该筛选，页面触发 VIP 弹窗 | 不要反复尝试绕过；跳过筛选或调整业务策略 |
+| `error` | 操作失败 | 读取 `error` 后决定是否重试 |
+
+实操规则：
+
+1. `requires_vip` 是硬边界，不是暂态加载失败。
+2. 如果筛选不可用，直接读取当前推荐列表，再由 orchestrator 按 `age`、`buttonText`、岗位信号等字段做结果过滤。
+3. 列表字段过滤不能替代平台筛选的完整语义；它只用于降低明显不合适目标的后续操作风险。
+
 ## 动态列表
 
 BOSS 页面通常不是整页滚动，而是内部容器滚动：
@@ -115,8 +157,25 @@ recommend-list  -> 推荐牛人列表，默认向下滚动，去重主键 candid
 ## 推荐候选人链路
 
 1. `zhipin_open_recommend_page()`。
-2. `zhipin_filter_recommend_candidates(ageMin?, ageMax?, gender?, activity?)`。
+2. `zhipin_filter_recommend_candidates(ageMin?, ageMax?, gender?, activity?)`（可选；`requires_vip` 时跳过）。
 3. `zhipin_get_candidate_list(maxResults?, autoScroll=true, maxScrolls=4)`。
-4. `zhipin_say_hello(indices)`。
+4. orchestrator 过滤 `buttonText` / 年龄 / 业务资格。
+5. `zhipin_say_hello(candidateRefs)`。
+
+`zhipin_get_candidate_list` 会给每个候选人返回 `candidateRef`，例如 `@c1`。
+
+优先级：
+
+1. 上层 orchestrator 优先把 `candidateRef` 传给 `zhipin_say_hello({ candidateRefs })` 或 `zhipin_open_resume({ candidateRef })`。
+2. `indices` / `index` 只作为当前 DOM 快照兜底。
+3. 筛选、滚动加载、搜索、刷新或页面重开后必须重新调用 `zhipin_get_candidate_list`，不要复用旧 `candidateRef`。
+4. 不要由 orchestrator 自己构造 `@c1`；只使用 tool 输出中的 `candidateRef`。
+5. 聊天消息列表没有 `candidateRef`；聊天回复链路继续使用 `conversationId` / `candidateId`。
+6. 调 `zhipin_say_hello` 前先过滤 `buttonText:"打招呼"`；`buttonText` 为空通常表示已打过招呼，不应重复点击。
+7. 如果业务有年龄、资格或岗位匹配约束，先按 `age` / `expectedPosition` / `tags` 等字段过滤，不要把所有 `candidateRefs` 盲目提交。
+
+失效保护：
 
-`zhipin_say_hello(indices)` 的 `indices` 也是当前 DOM 快照索引；筛选、滚动或列表刷新后必须重新读取列表。
+- 如果 `candidateRef` 对应的 `candidateId` / `name` 与当前 DOM 不一致，工具会返回 `success:false` 并提示“候选人引用已过期”。
+- 收到过期提示后，重新执行推荐候选人链路的第 3 步，再提交新的 `candidateRefs`。
+- 同一快照内可以一次提交多个 `candidateRefs` 连续打招呼；如果 BOSS 在点击后重排列表，工具会拒绝过期 ref，orchestrator 应刷新列表后只重试剩余目标。