@roll-agent/browser-use-agent 0.13.0 → 0.14.0

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

@@ -35,6 +35,7 @@ export declare function rememberZhipinCandidateRefs(candidates: readonly ZhipinC
 export declare function rememberZhipinRecommendJobRefs(jobs: readonly ZhipinRecommendJobRefSource[]): ZhipinRecommendJobRefTarget[];
 export declare function clearZhipinCandidateRefsForTests(): void;
 export declare function clearZhipinRecommendJobRefsForTests(): void;
+export declare function runWithZhipinSemanticRefScopeForTests<T>(scope: string, run: () => T): T;
 export declare function resolveZhipinCandidateRefTarget(candidateRef: string): ZhipinCandidateRefTarget;
 export declare function resolveZhipinRecommendJobRefTarget(jobRef: string): ZhipinRecommendJobRefTarget;
 export declare function resolveZhipinCandidateTargets(input: {

package/dist/runtime-config.d.ts

@@ -1,2 +1,322 @@
 import type { BrowserRuntimeConfig } from "@roll-agent/browser";
+import { z } from "zod";
+export declare const BrowserInstanceConfigSchema: z.ZodEffects<z.ZodObject<{
+    platform: z.ZodOptional<z.ZodEnum<["zhipin", "yupao"]>>;
+    mode: z.ZodDefault<z.ZodEnum<["managed-cdp", "remote-cdp", "existing-session"]>>;
+    headless: z.ZodOptional<z.ZodBoolean>;
+    cdpUrl: z.ZodOptional<z.ZodString>;
+    cdpHost: z.ZodDefault<z.ZodString>;
+    cdpPort: z.ZodOptional<z.ZodNumber>;
+    channel: z.ZodDefault<z.ZodEnum<["chrome", "chromium", "msedge"]>>;
+    executablePath: z.ZodOptional<z.ZodString>;
+    userDataDir: z.ZodString;
+    sessionsDir: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    profileName: z.ZodOptional<z.ZodString>;
+    windowBounds: z.ZodOptional<z.ZodObject<{
+        x: z.ZodOptional<z.ZodNumber>;
+        y: z.ZodOptional<z.ZodNumber>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        x?: number | undefined;
+        y?: number | undefined;
+        width?: number | undefined;
+        height?: number | undefined;
+    }, {
+        x?: number | undefined;
+        y?: number | undefined;
+        width?: number | undefined;
+        height?: number | undefined;
+    }>>;
+    trackingAgentId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    mode: "managed-cdp" | "remote-cdp" | "existing-session";
+    cdpHost: string;
+    channel: "chrome" | "chromium" | "msedge";
+    userDataDir: string;
+    headless?: boolean | undefined;
+    profileName?: string | undefined;
+    cdpUrl?: string | undefined;
+    cdpPort?: number | undefined;
+    executablePath?: string | undefined;
+    args?: string[] | undefined;
+    windowBounds?: {
+        x?: number | undefined;
+        y?: number | undefined;
+        width?: number | undefined;
+        height?: number | undefined;
+    } | undefined;
+    sessionsDir?: string | undefined;
+    platform?: "zhipin" | "yupao" | undefined;
+    trackingAgentId?: string | undefined;
+}, {
+    userDataDir: string;
+    mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
+    headless?: boolean | undefined;
+    profileName?: string | undefined;
+    cdpUrl?: string | undefined;
+    cdpHost?: string | undefined;
+    cdpPort?: number | undefined;
+    channel?: "chrome" | "chromium" | "msedge" | undefined;
+    executablePath?: string | undefined;
+    args?: string[] | undefined;
+    windowBounds?: {
+        x?: number | undefined;
+        y?: number | undefined;
+        width?: number | undefined;
+        height?: number | undefined;
+    } | undefined;
+    sessionsDir?: string | undefined;
+    platform?: "zhipin" | "yupao" | undefined;
+    trackingAgentId?: string | undefined;
+}>, {
+    mode: "managed-cdp" | "remote-cdp" | "existing-session";
+    cdpHost: string;
+    channel: "chrome" | "chromium" | "msedge";
+    userDataDir: string;
+    headless?: boolean | undefined;
+    profileName?: string | undefined;
+    cdpUrl?: string | undefined;
+    cdpPort?: number | undefined;
+    executablePath?: string | undefined;
+    args?: string[] | undefined;
+    windowBounds?: {
+        x?: number | undefined;
+        y?: number | undefined;
+        width?: number | undefined;
+        height?: number | undefined;
+    } | undefined;
+    sessionsDir?: string | undefined;
+    platform?: "zhipin" | "yupao" | undefined;
+    trackingAgentId?: string | undefined;
+}, {
+    userDataDir: string;
+    mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
+    headless?: boolean | undefined;
+    profileName?: string | undefined;
+    cdpUrl?: string | undefined;
+    cdpHost?: string | undefined;
+    cdpPort?: number | undefined;
+    channel?: "chrome" | "chromium" | "msedge" | undefined;
+    executablePath?: string | undefined;
+    args?: string[] | undefined;
+    windowBounds?: {
+        x?: number | undefined;
+        y?: number | undefined;
+        width?: number | undefined;
+        height?: number | undefined;
+    } | undefined;
+    sessionsDir?: string | undefined;
+    platform?: "zhipin" | "yupao" | undefined;
+    trackingAgentId?: string | undefined;
+}>;
+export declare const BrowserInstancesConfigSchema: z.ZodEffects<z.ZodObject<{
+    defaultInstance: z.ZodOptional<z.ZodString>;
+    instances: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        platform: z.ZodOptional<z.ZodEnum<["zhipin", "yupao"]>>;
+        mode: z.ZodDefault<z.ZodEnum<["managed-cdp", "remote-cdp", "existing-session"]>>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+        cdpUrl: z.ZodOptional<z.ZodString>;
+        cdpHost: z.ZodDefault<z.ZodString>;
+        cdpPort: z.ZodOptional<z.ZodNumber>;
+        channel: z.ZodDefault<z.ZodEnum<["chrome", "chromium", "msedge"]>>;
+        executablePath: z.ZodOptional<z.ZodString>;
+        userDataDir: z.ZodString;
+        sessionsDir: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        profileName: z.ZodOptional<z.ZodString>;
+        windowBounds: z.ZodOptional<z.ZodObject<{
+            x: z.ZodOptional<z.ZodNumber>;
+            y: z.ZodOptional<z.ZodNumber>;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            x?: number | undefined;
+            y?: number | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }, {
+            x?: number | undefined;
+            y?: number | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        }>>;
+        trackingAgentId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "managed-cdp" | "remote-cdp" | "existing-session";
+        cdpHost: string;
+        channel: "chrome" | "chromium" | "msedge";
+        userDataDir: string;
+        headless?: boolean | undefined;
+        profileName?: string | undefined;
+        cdpUrl?: string | undefined;
+        cdpPort?: number | undefined;
+        executablePath?: string | undefined;
+        args?: string[] | undefined;
+        windowBounds?: {
+            x?: number | undefined;
+            y?: number | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        sessionsDir?: string | undefined;
+        platform?: "zhipin" | "yupao" | undefined;
+        trackingAgentId?: string | undefined;
+    }, {
+        userDataDir: string;
+        mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
+        headless?: boolean | undefined;
+        profileName?: string | undefined;
+        cdpUrl?: string | undefined;
+        cdpHost?: string | undefined;
+        cdpPort?: number | undefined;
+        channel?: "chrome" | "chromium" | "msedge" | undefined;
+        executablePath?: string | undefined;
+        args?: string[] | undefined;
+        windowBounds?: {
+            x?: number | undefined;
+            y?: number | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        sessionsDir?: string | undefined;
+        platform?: "zhipin" | "yupao" | undefined;
+        trackingAgentId?: string | undefined;
+    }>, {
+        mode: "managed-cdp" | "remote-cdp" | "existing-session";
+        cdpHost: string;
+        channel: "chrome" | "chromium" | "msedge";
+        userDataDir: string;
+        headless?: boolean | undefined;
+        profileName?: string | undefined;
+        cdpUrl?: string | undefined;
+        cdpPort?: number | undefined;
+        executablePath?: string | undefined;
+        args?: string[] | undefined;
+        windowBounds?: {
+            x?: number | undefined;
+            y?: number | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        sessionsDir?: string | undefined;
+        platform?: "zhipin" | "yupao" | undefined;
+        trackingAgentId?: string | undefined;
+    }, {
+        userDataDir: string;
+        mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
+        headless?: boolean | undefined;
+        profileName?: string | undefined;
+        cdpUrl?: string | undefined;
+        cdpHost?: string | undefined;
+        cdpPort?: number | undefined;
+        channel?: "chrome" | "chromium" | "msedge" | undefined;
+        executablePath?: string | undefined;
+        args?: string[] | undefined;
+        windowBounds?: {
+            x?: number | undefined;
+            y?: number | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        sessionsDir?: string | undefined;
+        platform?: "zhipin" | "yupao" | undefined;
+        trackingAgentId?: string | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    instances: Record<string, {
+        mode: "managed-cdp" | "remote-cdp" | "existing-session";
+        cdpHost: string;
+        channel: "chrome" | "chromium" | "msedge";
+        userDataDir: string;
+        headless?: boolean | undefined;
+        profileName?: string | undefined;
+        cdpUrl?: string | undefined;
+        cdpPort?: number | undefined;
+        executablePath?: string | undefined;
+        args?: string[] | undefined;
+        windowBounds?: {
+            x?: number | undefined;
+            y?: number | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        sessionsDir?: string | undefined;
+        platform?: "zhipin" | "yupao" | undefined;
+        trackingAgentId?: string | undefined;
+    }>;
+    defaultInstance?: string | undefined;
+}, {
+    instances?: Record<string, {
+        userDataDir: string;
+        mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
+        headless?: boolean | undefined;
+        profileName?: string | undefined;
+        cdpUrl?: string | undefined;
+        cdpHost?: string | undefined;
+        cdpPort?: number | undefined;
+        channel?: "chrome" | "chromium" | "msedge" | undefined;
+        executablePath?: string | undefined;
+        args?: string[] | undefined;
+        windowBounds?: {
+            x?: number | undefined;
+            y?: number | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        sessionsDir?: string | undefined;
+        platform?: "zhipin" | "yupao" | undefined;
+        trackingAgentId?: string | undefined;
+    }> | undefined;
+    defaultInstance?: string | undefined;
+}>, {
+    instances: Record<string, {
+        mode: "managed-cdp" | "remote-cdp" | "existing-session";
+        cdpHost: string;
+        channel: "chrome" | "chromium" | "msedge";
+        userDataDir: string;
+        headless?: boolean | undefined;
+        profileName?: string | undefined;
+        cdpUrl?: string | undefined;
+        cdpPort?: number | undefined;
+        executablePath?: string | undefined;
+        args?: string[] | undefined;
+        windowBounds?: {
+            x?: number | undefined;
+            y?: number | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        sessionsDir?: string | undefined;
+        platform?: "zhipin" | "yupao" | undefined;
+        trackingAgentId?: string | undefined;
+    }>;
+    defaultInstance?: string | undefined;
+}, {
+    instances?: Record<string, {
+        userDataDir: string;
+        mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
+        headless?: boolean | undefined;
+        profileName?: string | undefined;
+        cdpUrl?: string | undefined;
+        cdpHost?: string | undefined;
+        cdpPort?: number | undefined;
+        channel?: "chrome" | "chromium" | "msedge" | undefined;
+        executablePath?: string | undefined;
+        args?: string[] | undefined;
+        windowBounds?: {
+            x?: number | undefined;
+            y?: number | undefined;
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        sessionsDir?: string | undefined;
+        platform?: "zhipin" | "yupao" | undefined;
+        trackingAgentId?: string | undefined;
+    }> | undefined;
+    defaultInstance?: string | undefined;
+}>;
+export type BrowserInstancesConfig = z.infer<typeof BrowserInstancesConfigSchema>;
 export declare function loadRuntimeConfigFromEnv(env?: NodeJS.ProcessEnv): BrowserRuntimeConfig;
+export declare function loadBrowserInstancesConfigFromEnv(env?: NodeJS.ProcessEnv): BrowserInstancesConfig | undefined;

package/dist/runtime-holder.d.ts

@@ -1,14 +1,23 @@
 import { BrowserRuntime, BrowserContextManager, SessionStore } from "@roll-agent/browser";
 import type { BrowserRuntimeConfig } from "@roll-agent/browser";
-export declare function initRuntime(config: BrowserRuntimeConfig): Promise<void>;
+import { BrowserInstancePool, type BrowserRuntimeBundle } from "./browser-instance-pool.ts";
+import type { BrowserInstancesConfig } from "./runtime-config.ts";
+export declare function initRuntime(config: BrowserRuntimeConfig, instancesConfig?: BrowserInstancesConfig): Promise<void>;
 export declare function getRuntime(): BrowserRuntime;
 export declare function getContextManager(): BrowserContextManager;
 export declare function getSessionStore(): SessionStore;
 export declare function setReplyAuthorityKeysLoaded(loaded: boolean): void;
 export declare function getReplyAuthorityKeysLoaded(): boolean;
+export declare function getBrowserInstancePoolOrUndefined(): BrowserInstancePool | undefined;
+export declare function getBrowserInstancePool(): BrowserInstancePool;
+export declare function ensureCurrentBundleStarted(): Promise<void>;
+export declare function isConfiguredMultiBrowserInstancePool(): boolean;
+export declare function resolveRecruitmentTrackingAgentId(defaultAgentId?: string): string | undefined;
+export declare function getCurrentBrowserBundle(): BrowserRuntimeBundle;
 export declare function setRuntimeStateForTests(state: {
     readonly runtime?: BrowserRuntime;
     readonly contextManager?: BrowserContextManager;
     readonly sessionStore?: SessionStore;
+    readonly instancePool?: BrowserInstancePool;
 }): void;
 export declare function shutdownRuntime(): Promise<void>;

package/dist/tools/browser-instance-input.d.ts

@@ -0,0 +1,8 @@
+import type { AnyToolDefinition } from "@roll-agent/sdk";
+import type { Platform } from "@roll-agent/browser";
+export interface BrowserInstanceToolOptions {
+    readonly startRuntime?: boolean;
+    readonly expectedPlatform?: Platform;
+}
+export declare function inferExpectedPlatformFromToolName(toolName: string): Platform | undefined;
+export declare function withBrowserInstanceInput(tool: AnyToolDefinition, options?: BrowserInstanceToolOptions): AnyToolDefinition;

package/dist/tools/browser-instance-platform.d.ts

@@ -0,0 +1,3 @@
+import type { Platform } from "@roll-agent/browser";
+export declare function assertBrowserInstancePlatform(platform: Platform | undefined): void;
+export declare function readPlatformFromToolInput(input: unknown): Platform | undefined;

package/dist/tools/browser-ref-schemas.d.ts

@@ -11,22 +11,22 @@ export declare const BrowserElementRefTargetSchema: z.ZodObject<{
     frameId: z.ZodOptional<z.ZodString>;
     disabled: z.ZodBoolean;
 }, "strip", z.ZodTypeAny, {
+    x: number;
+    y: number;
     ref: string;
     role: string;
     name: string;
     disabled: boolean;
-    x: number;
-    y: number;
     resolvedBy: "backend_node_id" | "role_name_nth";
     backendNodeId?: number | undefined;
     frameId?: string | undefined;
 }, {
+    x: number;
+    y: number;
     ref: string;
     role: string;
     name: string;
     disabled: boolean;
-    x: number;
-    y: number;
     resolvedBy: "backend_node_id" | "role_name_nth";
     backendNodeId?: number | undefined;
     frameId?: string | undefined;
@@ -46,22 +46,22 @@ export declare const BrowserElementRefActionOutputSchema: z.ZodObject<{
         frameId: z.ZodOptional<z.ZodString>;
         disabled: z.ZodBoolean;
     }, "strip", z.ZodTypeAny, {
+        x: number;
+        y: number;
         ref: string;
         role: string;
         name: string;
         disabled: boolean;
-        x: number;
-        y: number;
         resolvedBy: "backend_node_id" | "role_name_nth";
         backendNodeId?: number | undefined;
         frameId?: string | undefined;
     }, {
+        x: number;
+        y: number;
         ref: string;
         role: string;
         name: string;
         disabled: boolean;
-        x: number;
-        y: number;
         resolvedBy: "backend_node_id" | "role_name_nth";
         backendNodeId?: number | undefined;
         frameId?: string | undefined;
@@ -69,12 +69,12 @@ export declare const BrowserElementRefActionOutputSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     ref: string;
     target: {
+        x: number;
+        y: number;
         ref: string;
         role: string;
         name: string;
         disabled: boolean;
-        x: number;
-        y: number;
         resolvedBy: "backend_node_id" | "role_name_nth";
         backendNodeId?: number | undefined;
         frameId?: string | undefined;
@@ -84,12 +84,12 @@ export declare const BrowserElementRefActionOutputSchema: z.ZodObject<{
 }, {
     ref: string;
     target: {
+        x: number;
+        y: number;
         ref: string;
         role: string;
         name: string;
         disabled: boolean;
-        x: number;
-        y: number;
         resolvedBy: "backend_node_id" | "role_name_nth";
         backendNodeId?: number | undefined;
         frameId?: string | undefined;

package/dist/tools/browser-status.d.ts

@@ -14,6 +14,7 @@ export declare const browserStatus: import("@roll-agent/sdk").ToolDefinition<{},
         pagesOpen: number;
         hasLoginState: boolean | null;
         loginStateSource: "snapshot" | "profile" | "none" | "unknown";
+        browserInstance?: string | undefined;
         currentUrl?: string | undefined;
     }[];
     replyAuthorityKeysLoaded: boolean;
@@ -33,4 +34,26 @@ export declare const browserStatus: import("@roll-agent/sdk").ToolDefinition<{},
         present: boolean;
         fingerprint?: string | undefined;
     }>;
+    defaultInstanceId?: string | undefined;
+    primaryInstanceId?: string | undefined;
+    instances?: {
+        id: string;
+        mode: "managed-cdp" | "remote-cdp" | "existing-session";
+        profile: {
+            exists: boolean;
+            writable: boolean;
+            userDataDir?: string | undefined;
+        };
+        cdp: {
+            endpoint: string;
+            versionReachable: boolean;
+            listReachable: boolean;
+            port?: number | undefined;
+        };
+        tracking: {
+            source: "instance" | "default-env" | "missing";
+            agentIdFingerprint?: string | undefined;
+        };
+        platform?: "zhipin" | "yupao" | undefined;
+    }[] | undefined;
 }>;

package/dist/tools/click-ref.d.ts

@@ -7,12 +7,12 @@ export declare const clickRef: import("@roll-agent/sdk").ToolDefinition<{
 }, {
     ref: string;
     target: {
+        x: number;
+        y: number;
         ref: string;
         role: string;
         name: string;
         disabled: boolean;
-        x: number;
-        y: number;
         resolvedBy: "backend_node_id" | "role_name_nth";
         backendNodeId?: number | undefined;
         frameId?: string | undefined;

package/dist/tools/type-ref.d.ts

@@ -9,12 +9,12 @@ export declare const typeRef: import("@roll-agent/sdk").ToolDefinition<{
 }, {
     ref: string;
     target: {
+        x: number;
+        y: number;
         ref: string;
         role: string;
         name: string;
         disabled: boolean;
-        x: number;
-        y: number;
         resolvedBy: "backend_node_id" | "role_name_nth";
         backendNodeId?: number | undefined;
         frameId?: string | undefined;

package/dist/tools/zhipin-get-username.d.ts

@@ -11,8 +11,8 @@ export declare function setZhipinGetUsernameDepsForTests(override: Partial<Zhipi
 export declare const zhipinGetUsername: import("@roll-agent/sdk").ToolDefinition<{}, {
     success: boolean;
     username: string;
-    error?: string | undefined;
     source?: string | undefined;
+    error?: string | undefined;
     usedSelector?: string | undefined;
     usedStrategy?: string | undefined;
 }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/browser-use-agent",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -47,7 +47,7 @@
     "zod": "^3.25.76",
     "@roll-agent/reply-authority-client": "0.1.2",
     "@roll-agent/sdk": "0.2.0",
-    "@roll-agent/browser": "0.6.0"
+    "@roll-agent/browser": "0.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"

package/references/env.yaml

@@ -9,7 +9,7 @@ required:
     purpose: Reply Authority Service 公钥分发端点；`zhipin_send_prepared_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；招聘事件默认启用，上报时必须用它做归因
+    purpose: 单 browser-use 实例 / 单 Boss 账号部署下的默认招聘业务 Agent ID；多 browser.instances 下仅作为实例缺少 trackingAgentId 时的 fallback；招聘事件默认启用，上报时必须有可解析归因
     example: zhipin-shanghai-kfc-001
   - name: RECRUITMENT_EVENTS_API_TOKEN
     purpose: 招聘事件 Open API Bearer token；公开 npm 包不内置兜底 token，必须由部署环境提供
@@ -31,6 +31,9 @@ optional:
     purpose: browser-use 工具级业务策略 JSON；可按 exact tool name 配置 log、deny、confirm
     default: '{"approvalTtlMs":300000,"tools":{}}'
     example: '{"approvalTtlMs":300000,"tools":{"zhipin_send_prepared_reply":{"policy":"confirm"}}}'
+  - name: BROWSER_INSTANCES_JSON
+    purpose: Roll core 注入的多浏览器实例声明 JSON；由 `browser.instances` 派生，包含每个实例的 profile、CDP 端口、session 目录、可选 profileName/windowBounds 和招聘事件归因 ID；orchestrator 不应手工拼接，手工配置时必须保持 cdpPort/userDataDir 唯一
+    example: '{"defaultInstance":"boss-a","instances":{"boss-a":{"platform":"zhipin","mode":"managed-cdp","cdpPort":9222,"userDataDir":"/tmp/roll-browser/profiles/boss-a","profileName":"boss-a","windowBounds":{"x":0,"y":0,"width":680,"height":1000},"trackingAgentId":"zhipin-boss-a"}}}'
   - name: BROWSER_VISUAL_CURSOR
     purpose: 在可见浏览器页面内显示 browser-use 的页内虚拟指针和点击波纹；默认开启，设为 `"false"` 可关闭
     default: "true"

package/references/zhipin-workflows.md

@@ -4,6 +4,29 @@
 
 `conversationId` / `candidateId` 是跨 tool 的稳定主键，`index` 只表示当前 DOM 快照。
 
+## 多账号 browserInstance 作用域
+
+多 Boss 账号托管时，`browserInstance` 是账号/profile 路由键。orchestrator 必须把它贯穿同一账号任务的所有 browser-use 调用。
+
+作用域规则：
+
+1. 同一个账号线程固定一个 `browserInstance`，例如 `boss-a`。
+2. 该线程中的 `zhipin_*`、`browser_snapshot`、`click_ref`、`type_ref`、`list_pages`、`select_page` 都显式传同一个 `browserInstance`。
+3. `conversationId` / `candidateId` 是业务主键，但不替代 `browserInstance`；同一个候选会话仍必须在正确账号 profile 中执行。
+4. `pageId`、`@eN`、`@cN`、`@jN`、`jobRef`、`candidateRef`、`preparedReplyId` 只在产生它们的 `browserInstance` 内有效。
+5. 多实例没有 `browser.defaultInstance` 时，不传 `browserInstance` 的调用会返回 `needs_input`。
+6. 不要把 `boss-a` 生成的 `preparedReplyId` 交给 `boss-b` 发送；发送工具会校验当前页面目标和招聘者绑定。
+
+示例：
+
+```json
+{
+  "browserInstance": "boss-a",
+  "conversationId": "610630074-0",
+  "maxMessages": 100
+}
+```
+
 ## BOSS 页面入口
 
 `navigate_active_tab(url)` 是通用 native CDP 导航工具，但不能直接跳转 BOSS `/web/chat/*` 后台路径。
@@ -25,10 +48,9 @@
 推荐做法：
 
 1. `zhipin_read_messages` 记录 `conversationId + candidateId + candidateName`。
-2. `zhipin_open_chat(conversationId)`。
-3. `zhipin_get_candidate_info(conversationId)`。
-4. `smart-reply-agent.generate_reply(..., target)`。
-5. `zhipin_send_reply(signedEnvelope)`。
+2. `zhipin_generate_reply_preview({ browserInstance, conversationId })`。
+3. `zhipin_send_prepared_reply({ browserInstance, preparedReplyId })`。
+4. 发送后用 `zhipin_read_messages({ browserInstance, onlyUnread:true })` 或目标会话读取做验证。
 
 ## 推荐岗位筛选
 
@@ -120,7 +142,7 @@ recommend-list  -> 推荐牛人列表，默认向下滚动，去重主键 candid
 
 ## Reply Authority
 
-`zhipin_send_reply` 只接受 Reply Authority Service 签发的 `signedEnvelope`。
+`zhipin_send_prepared_reply` 只接受 `zhipin_generate_reply_preview` 生成的 `preparedReplyId`，内部再取回 Reply Authority Service 签发的 envelope 并完成验签。
 
 发送前校验：
 
@@ -130,6 +152,7 @@ recommend-list  -> 推荐牛人列表，默认向下滚动，去重主键 candid
 4. replay `jti` 是否已消费。
 5. 当前选中聊天是否匹配 `conversationId + candidateId`。
 6. 当前登录招聘者是否匹配 `recruiterBinding`。
+7. 当前 `browserInstance` 是否仍是生成 `preparedReplyId` 的账号/profile 作用域。
 
 `generate_reply` 的 `target` 两种模式：