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

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

@@ -1,28 +1,37 @@
+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 ZhipinGetCandidateInfoDeps = {
+    readonly openNativePagePort: typeof openZhipinNativePagePort;
+    readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;
+};
+export declare function setZhipinGetCandidateInfoDepsForTests(override: Partial<ZhipinGetCandidateInfoDeps> | undefined): void;
 export declare const zhipinGetCandidateInfo: import("@roll-agent/sdk").ToolDefinition<{
+    index?: number | undefined;
     conversationId?: string | undefined;
     candidateName?: string | undefined;
-    index?: number | undefined;
     maxMessages?: number | undefined;
 }, {
     success: boolean;
     conversationId: string;
     candidateId: string;
-    stats: {
-        totalMessages: number;
-        candidateMessages: number;
-        recruiterMessages: number;
-        systemMessages: number;
-    };
     candidateInfo: {
         name: string;
-        expectedLocation: string;
-        expectedPosition: string;
         age: string;
         experience: string;
         education: string;
-        communicationPosition: string;
+        expectedLocation: string;
+        expectedPosition: string;
         expectedSalary: string;
         tags: string[];
+        communicationPosition: string;
+    };
+    stats: {
+        totalMessages: number;
+        candidateMessages: number;
+        recruiterMessages: number;
+        systemMessages: number;
     };
     chatMessages: {
         time: string;
@@ -35,3 +44,4 @@ export declare const zhipinGetCandidateInfo: import("@roll-agent/sdk").ToolDefin
     error?: string | undefined;
     preferredBrand?: string | undefined;
 }>;
+export {};

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

@@ -1,13 +1,10 @@
-import { getRecommendTarget, waitForRecommendList } from "../pages/zhipin/recommend-list.ts";
-import { getContextManager } from "../runtime-holder.ts";
-import { VisualActivitySession } from "../visual-activity-session.ts";
-type RecommendTarget = ReturnType<typeof getRecommendTarget>;
-type VisualActivitySessionLike = Pick<VisualActivitySession, "begin" | "highlightSelector" | "succeed" | "fail" | "retarget">;
+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 ZhipinGetCandidateListDeps = {
-    readonly getContextManager: typeof getContextManager;
-    readonly getRecommendTarget: typeof getRecommendTarget;
-    readonly waitForRecommendList: typeof waitForRecommendList;
-    readonly createVisualActivitySession: (target: RecommendTarget) => VisualActivitySessionLike;
+    readonly openNativePagePort: typeof openZhipinNativePagePort;
+    readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;
 };
 export declare function setZhipinGetCandidateListDepsForTests(override: Partial<ZhipinGetCandidateListDeps> | undefined): void;
 export declare const zhipinGetCandidateList: import("@roll-agent/sdk").ToolDefinition<{
@@ -18,18 +15,18 @@ export declare const zhipinGetCandidateList: import("@roll-agent/sdk").ToolDefin
     success: boolean;
     candidates: {
         name: string;
-        candidateId: string;
         index: number;
-        expectedLocation: string;
-        expectedPosition: string;
+        candidateId: string;
         age: string;
         experience: string;
         education: string;
-        expectedSalary: string;
-        tags: string[];
         workStatus: string;
         company: string;
         currentPosition: string;
+        expectedLocation: string;
+        expectedPosition: string;
+        expectedSalary: string;
+        tags: string[];
         buttonText: string;
     }[];
     total: number;

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

@@ -1,13 +1,11 @@
-import type { Page } from "@roll-agent/browser";
-import { getCurrentZhipinRecruiterIdentity } from "../pages/zhipin/recruiter-identity.ts";
-import { findHeaderScope } from "../pages/zhipin/username.ts";
-import { getContextManager } from "../runtime-holder.ts";
-import { VisualActivitySession } from "../visual-activity-session.ts";
+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";
+import { pickBestUsername } from "../pages/zhipin/username.ts";
 type ZhipinGetUsernameDeps = {
-    readonly getContextManager: typeof getContextManager;
-    readonly findHeaderScope: typeof findHeaderScope;
-    readonly getCurrentZhipinRecruiterIdentity: typeof getCurrentZhipinRecruiterIdentity;
-    readonly createVisualActivitySession: (page: Page) => VisualActivitySession;
+    readonly openNativePagePort: typeof openZhipinNativePagePort;
+    readonly pickBestUsername: typeof pickBestUsername;
+    readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySession;
 };
 export declare function setZhipinGetUsernameDepsForTests(override: Partial<ZhipinGetUsernameDeps> | undefined): void;
 export declare const zhipinGetUsername: import("@roll-agent/sdk").ToolDefinition<{}, {

package/dist/tools/zhipin-locate-resume-canvas.d.ts

@@ -2,10 +2,10 @@ export declare const zhipinLocateResumeCanvas: import("@roll-agent/sdk").ToolDef
     success: boolean;
     error?: string | undefined;
     screenshotArea?: {
-        width: number;
-        height: number;
         x: number;
         y: number;
+        width: number;
+        height: number;
     } | undefined;
     canvasInfo?: {
         width: number;

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

@@ -1,21 +1,14 @@
-import type { Page } from "@roll-agent/browser";
-import { randomDelay } from "../pages/zhipin/anti-detection.ts";
-import { findZhipinSidebarSectionLink, isZhipinChatSurfaceOpen, waitForZhipinChatSurface } from "../pages/zhipin/sidebar-navigation.ts";
-import { toAttachedPageInfo } from "../page-info.ts";
+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";
 import { getContextManager } from "../runtime-holder.ts";
-import { VisualActivitySession } from "../visual-activity-session.ts";
-import { moveVisualCursorToLocator, showVisualClickOnLocator } from "../visual-cursor.ts";
-type VisualActivitySessionLike = Pick<VisualActivitySession, "begin" | "highlightSelector" | "succeed" | "fail">;
+type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "succeed" | "fail"> & {
+    readonly highlightPoint?: NativeVisualActivitySession["highlightPoint"];
+};
 type ZhipinOpenChatPageDeps = {
     readonly getContextManager: typeof getContextManager;
-    readonly findZhipinSidebarSectionLink: typeof findZhipinSidebarSectionLink;
-    readonly isZhipinChatSurfaceOpen: typeof isZhipinChatSurfaceOpen;
-    readonly waitForZhipinChatSurface: typeof waitForZhipinChatSurface;
-    readonly moveVisualCursorToLocator: typeof moveVisualCursorToLocator;
-    readonly showVisualClickOnLocator: typeof showVisualClickOnLocator;
-    readonly randomDelay: typeof randomDelay;
-    readonly toAttachedPageInfo: typeof toAttachedPageInfo;
-    readonly createVisualActivitySession: (page: Page) => VisualActivitySessionLike;
+    readonly openNativePagePort: typeof openZhipinNativePagePort;
+    readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;
 };
 export declare function setZhipinOpenChatPageDepsForTests(override: Partial<ZhipinOpenChatPageDeps> | undefined): void;
 export declare const zhipinOpenChatPage: import("@roll-agent/sdk").ToolDefinition<{}, {

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

@@ -1,17 +1,27 @@
+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 ZhipinOpenChatDeps = {
+    readonly openNativePagePort: typeof openZhipinNativePagePort;
+    readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;
+};
+export declare function setZhipinOpenChatDepsForTests(override: Partial<ZhipinOpenChatDeps> | undefined): void;
 export declare const zhipinOpenChat: import("@roll-agent/sdk").ToolDefinition<{
+    index?: number | undefined;
     conversationId?: string | undefined;
     candidateName?: string | undefined;
-    index?: number | undefined;
     preferUnread?: boolean | undefined;
 }, {
+    index: number;
     success: boolean;
     conversationId: string;
     candidateId: string;
     candidateName: string;
-    index: number;
     hasUnread: boolean;
     unreadCount: number;
     lastMessageTime: string;
     messagePreview: string;
     error?: string | undefined;
 }>;
+export {};

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

@@ -1,23 +1,14 @@
-import { randomDelay } from "../pages/zhipin/anti-detection.ts";
-import { getRecommendTarget } from "../pages/zhipin/recommend-list.ts";
-import { findZhipinSidebarSectionLink, isZhipinRecommendSurfaceOpen, waitForZhipinRecommendSurface } from "../pages/zhipin/sidebar-navigation.ts";
-import { toAttachedPageInfo } from "../page-info.ts";
+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";
 import { getContextManager } from "../runtime-holder.ts";
-import { VisualActivitySession } from "../visual-activity-session.ts";
-import { moveVisualCursorToLocator, showVisualClickOnLocator } from "../visual-cursor.ts";
-type RecommendTarget = ReturnType<typeof getRecommendTarget>;
-type VisualActivitySessionLike = Pick<VisualActivitySession, "begin" | "highlightSelector" | "retarget" | "succeed" | "fail">;
+type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "succeed" | "fail"> & {
+    readonly highlightPoint?: NativeVisualActivitySession["highlightPoint"];
+};
 type ZhipinOpenRecommendPageDeps = {
     readonly getContextManager: typeof getContextManager;
-    readonly getRecommendTarget: typeof getRecommendTarget;
-    readonly findZhipinSidebarSectionLink: typeof findZhipinSidebarSectionLink;
-    readonly isZhipinRecommendSurfaceOpen: typeof isZhipinRecommendSurfaceOpen;
-    readonly waitForZhipinRecommendSurface: typeof waitForZhipinRecommendSurface;
-    readonly moveVisualCursorToLocator: typeof moveVisualCursorToLocator;
-    readonly showVisualClickOnLocator: typeof showVisualClickOnLocator;
-    readonly randomDelay: typeof randomDelay;
-    readonly toAttachedPageInfo: typeof toAttachedPageInfo;
-    readonly createVisualActivitySession: (target: RecommendTarget) => VisualActivitySessionLike;
+    readonly openNativePagePort: typeof openZhipinNativePagePort;
+    readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;
 };
 export declare function setZhipinOpenRecommendPageDepsForTests(override: Partial<ZhipinOpenRecommendPageDeps> | undefined): void;
 export declare const zhipinOpenRecommendPage: import("@roll-agent/sdk").ToolDefinition<{}, {

package/dist/tools/zhipin-read-messages.d.ts

@@ -1,3 +1,11 @@
+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 ZhipinReadMessagesDeps = {
+    readonly openNativePagePort: typeof openZhipinNativePagePort;
+    readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySession;
+};
+export declare function setZhipinReadMessagesDepsForTests(override: Partial<ZhipinReadMessagesDeps> | undefined): void;
 export declare const zhipinReadMessages: import("@roll-agent/sdk").ToolDefinition<{
     limit?: number | undefined;
     onlyUnread?: boolean | undefined;
@@ -23,3 +31,4 @@ export declare const zhipinReadMessages: import("@roll-agent/sdk").ToolDefinitio
         withUnread: number;
     };
 }>;
+export {};

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

@@ -1,38 +1,28 @@
-import { getContextManager } from "../runtime-holder.ts";
-import { humanDelay, shouldAddRandomBehavior, performRandomScroll } from "../pages/zhipin/anti-detection.ts";
-import { getRecommendTarget, inspectRecommendCard, waitForRecommendList } from "../pages/zhipin/recommend-list.ts";
-import { VisualActivitySession } from "../visual-activity-session.ts";
-import { moveVisualCursorToLocator, showVisualClickOnLocator } from "../visual-cursor.ts";
-type RecommendTarget = ReturnType<typeof getRecommendTarget>;
-type VisualActivitySessionLike = Pick<VisualActivitySession, "begin" | "highlightSelector" | "highlightLocator" | "succeed" | "fail" | "retarget">;
+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 ZhipinSayHelloDeps = {
-    readonly getContextManager: typeof getContextManager;
-    readonly getRecommendTarget: typeof getRecommendTarget;
-    readonly waitForRecommendList: typeof waitForRecommendList;
-    readonly inspectRecommendCard: typeof inspectRecommendCard;
-    readonly moveVisualCursorToLocator: typeof moveVisualCursorToLocator;
-    readonly showVisualClickOnLocator: typeof showVisualClickOnLocator;
-    readonly humanDelay: typeof humanDelay;
-    readonly shouldAddRandomBehavior: typeof shouldAddRandomBehavior;
-    readonly performRandomScroll: typeof performRandomScroll;
-    readonly createVisualActivitySession: (target: RecommendTarget) => VisualActivitySessionLike;
+    readonly openNativePagePort: typeof openZhipinNativePagePort;
+    readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;
+    readonly sleep: (ms: number) => Promise<void>;
 };
 export declare function setZhipinSayHelloDepsForTests(override: Partial<ZhipinSayHelloDeps> | undefined): void;
 export declare const zhipinSayHello: import("@roll-agent/sdk").ToolDefinition<{
     indices: number[];
 }, {
-    summary: {
-        failed: number;
-        total: number;
-        succeeded: number;
-    };
     success: boolean;
     results: {
+        index: number;
         success: boolean;
         candidateId: string;
         candidateName: string;
-        index: number;
         error?: string | undefined;
     }[];
+    summary: {
+        total: number;
+        succeeded: number;
+        failed: number;
+    };
 }>;
 export {};

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

@@ -1,3 +1,12 @@
+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 ZhipinScrollViewDeps = {
+    readonly openNativePagePort: typeof openZhipinNativePagePort;
+    readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;
+};
+export declare function setZhipinScrollViewDepsForTests(override: Partial<ZhipinScrollViewDeps> | undefined): void;
 export declare const zhipinScrollView: import("@roll-agent/sdk").ToolDefinition<{
     surface: "chat-list" | "chat-history" | "recommend-list";
     direction?: "up" | "down" | undefined;
@@ -6,9 +15,6 @@ export declare const zhipinScrollView: import("@roll-agent/sdk").ToolDefinition<
     settleMs?: number | undefined;
 }, {
     success: boolean;
-    direction: "up" | "down";
-    stepsRequested: number;
-    stepsCompleted: number;
     before: {
         containerFound: boolean;
         containerLabel: string;
@@ -29,7 +35,11 @@ export declare const zhipinScrollView: import("@roll-agent/sdk").ToolDefinition<
         atEnd: boolean;
         itemCount: number;
     };
+    direction: "up" | "down";
+    stepsRequested: number;
+    stepsCompleted: number;
     reachedBoundary: boolean;
     surface: "chat-list" | "chat-history" | "recommend-list";
     error?: string | undefined;
 }>;
+export {};

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

@@ -1,13 +1,21 @@
+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";
+import { getReplyAuthorityKeysLoaded } from "../runtime-holder.ts";
+type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightPoint" | "succeed" | "fail">;
+type ZhipinSendReplyDeps = {
+    readonly getReplyAuthorityKeysLoaded: typeof getReplyAuthorityKeysLoaded;
+    readonly openNativePagePort: typeof openZhipinNativePagePort;
+    readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;
+};
+export declare function setZhipinSendReplyDepsForTests(override: Partial<ZhipinSendReplyDeps> | undefined): void;
 export declare const zhipinSendReply: import("@roll-agent/sdk").ToolDefinition<{
     signedEnvelope: string;
-    candidateName?: string | undefined;
     index?: number | undefined;
+    candidateName?: string | undefined;
 }, {
     success: boolean;
     sentMessage: string;
-    error: string | undefined;
-} | {
-    success: boolean;
-    sentMessage: string;
-    error?: never;
+    error?: string | undefined;
 }>;
+export {};

package/package.json

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

package/references/zhipin-diagnostics.md

@@ -0,0 +1,77 @@
+# BOSS直聘 CDP/风控诊断
+
+`zhipin_diagnose_browser_state` 用于把 BOSS 页面回退/风控触发点拆成可观测阶段。它不是业务读取工具，也不负责规避检测。
+
+## 触发场景
+
+- 调用 BOSS 工具后页面自动 `history.goBack()` 或回到上一页。
+- 某个账号或浏览器 profile 触发异常，其它账号不触发。
+- 需要判断异常来自 native CDP 连接、Playwright attach、`Runtime.evaluate`、DOM 读取、storage/cookie 读取还是网络上报。
+
+## 阶段模型
+
+```text
+低侵入:
+native -> native-watch
+
+native CDP page WebSocket:
+native -> native-ws-connect -> native-page-bring-front
+native -> native-ws-connect -> native-evaluate-url-no-runtime-enable
+native -> native-ws-connect -> native-dom-read-no-runtime-enable
+native -> native-ws-connect -> native-input-move-no-runtime-enable
+native -> native-ws-connect -> native-runtime-enable -> native-evaluate-url -> native-dom-read
+
+Playwright attach:
+native -> browser-attach -> browser-attach-watch -> page-attach -> network-watch
+native -> browser-attach -> browser-attach-watch -> page-attach -> page-evaluate -> detector-fingerprint -> storage-summary
+```
+
+## Phase 说明
+
+| `phase` | 动作 | 诊断问题 |
+| --- | --- | --- |
+| `native` | 只调用原生 CDP `/json/list` 枚举页面 | 当前有哪些 BOSS target；最低风险默认阶段。 |
+| `native-watch` | 不 attach，在 `watchMs` 内重复读取 URL/title | 不连接 Playwright 时页面是否自己跳转。 |
+| `native-ws-connect` | 连接目标页 `webSocketDebuggerUrl`，不调用 Playwright/Puppeteer | 仅建立 native page WebSocket 是否触发。 |
+| `native-page-bring-front` | 发送 `Page.bringToFront`，不调用 `Runtime.enable` | Page domain 前台切换是否触发。 |
+| `native-evaluate-url-no-runtime-enable` | 直接 `Runtime.evaluate` 读取 URL/title，不先 `Runtime.enable` | 是 `Runtime.enable` 独有触发，还是 evaluate 本身触发。 |
+| `native-dom-read-no-runtime-enable` | 直接 `DOM.getDocument`，不先 `Runtime.enable` / `DOM.enable` | DOM domain 最小读取是否触发。 |
+| `native-input-move-no-runtime-enable` | 直接 `Input.dispatchMouseEvent(mouseMoved)` | Input domain 最小事件是否触发。 |
+| `native-runtime-enable` | 发送 `Runtime.enable` | Runtime domain 是否触发。 |
+| `native-evaluate-url` | 读取 `location.href`、`document.title`、可见状态 | 最小页面 JS evaluate 是否触发。 |
+| `native-dom-read` | DOM 摘要读取，只返回数量/长度 | DOM 读取是否触发。 |
+| `browser-attach` | 执行 `runtime.getBrowser()` 并观察 native URL/title | Playwright Browser CDP 连接是否触发异步回退。 |
+| `page-attach` | 执行 `ctxManager.getPage("zhipin")` | 绑定具体页面/context 是否触发。 |
+| `network-watch` | 监听相关 request/response 和 frame navigation | attach 后是否出现 APM/security 上报或 URL 自动变化。 |
+| `page-evaluate` | Playwright 页面内最小 evaluate | 页面 JS evaluate 是否触发。 |
+| `detector-fingerprint` | 读取 `navigator.webdriver`、`window.cdc_*`、Playwright binding 标记 | 是否暴露自动化指纹。 |
+| `storage-summary` | 读取 storage/cookie 脱敏摘要 | storage/cookie 读取是否触发。 |
+
+## 推进规则
+
+1. 先调用 `zhipin_diagnose_browser_state()` 或 `phase="native"`。
+2. `nativePages` 只有一个 BOSS 页时可递进；多个 BOSS 页时后续必须传 `targetPageId`。
+3. 高风险账号先跑 `native-watch`。
+4. 验证 native CDP 时先跑 `native-ws-connect`，再跑 no-`Runtime.enable` 分支。
+5. 每次只推进一个阶段，并在每次调用后观察 `nativeTimeline`。
+6. `browser-attach` 失败，或 `browser-attach-watch` 出现 `urlChangedFromPrevious=true` 时，停止调用 Playwright-backed BOSS 工具。
+7. 任意 `native-*-watch` 快照出现 `urlChangedFromPrevious=true` 时，停止加深 native CDP 实验。
+8. 只有需要复现 `Runtime.enable` 红线时才跑 `native-runtime-enable`。
+9. 要验证网络上报，只在 `browser-attach` 未触发 URL 变化后继续跑 `page-attach` / `network-watch`。
+10. `storage-summary` 只返回脱敏摘要；禁止要求或传播 cookie/localStorage/sessionStorage 原始值。
+
+## 返回字段
+
+| 字段 | 含义 |
+| --- | --- |
+| `nativePages` | 原生 CDP 页面列表，`pageId` 可作为后续 `targetPageId`。 |
+| `targetPage` | 本次绑定或诊断的 BOSS 页面。 |
+| `browserAttached` / `pageAttached` | 是否进入 Playwright attach 阶段。 |
+| `nativeTimeline` | 每个阶段后的 native URL/title 快照；`urlChangedFromPrevious=true` 是关键触发证据。 |
+| `nativeCdp` | native CDP 探测摘要，不包含页面正文。 |
+| `networkEvents` | APM/security 请求摘要，不抓请求体。 |
+| `navigationEvents` | attach 后 frame URL 变化。 |
+| `detectorFingerprint` | 自动化相关公开标志。 |
+| `phases` | 阶段成功状态、耗时、错误。 |
+| `warnings` | 多页面、目标页缺失、URL 变化等边界提示。 |
+| `storage` | storage/cookie 脱敏形状、长度和计数器差分。 |

package/references/zhipin-workflows.md

@@ -0,0 +1,102 @@
+# BOSS直聘业务编排细节
+
+## 聊天主键
+
+`conversationId` / `candidateId` 是跨 tool 的稳定主键，`index` 只表示当前 DOM 快照。
+
+错误做法：
+
+- 把 `zhipin_read_messages` 返回数组里的 `index` 当作后续点击主键。
+- 手动滚动或列表重排后继续使用旧 `index`。
+- 用 `candidateName` 模糊匹配会话后，把历史 `candidateId` 假定为同一人。
+- 由 orchestrator 自己重建 `target.conversationId` / `target.candidateId`。
+
+推荐做法：
+
+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)`。
+
+## 动态列表
+
+BOSS 页面通常不是整页滚动，而是内部容器滚动：
+
+```text
+chat-list       -> 左侧消息列表，默认向下滚动，去重主键 conversationId
+chat-history    -> 右侧聊天记录，默认向上滚动，用于加载更早历史
+recommend-list  -> 推荐牛人列表，默认向下滚动，去重主键 candidateId/data-geek
+```
+
+规则：
+
+1. 业务读取优先用自带 `autoScroll` 的工具：`zhipin_read_messages`、`zhipin_get_candidate_list`。
+2. `zhipin_scroll_view` 只用于显式翻页、调试和补救。
+3. `onlyUnread=true` 时不要依赖 `limit` 提前停止；未读会话可能在首屏之后。
+4. `maxScrolls` 用于成本控制，需要更完整列表时显式调大。
+5. 推荐列表若 `total < maxResults`，先看 `scrollStats.stopReason`：
+   - `target-count`：已达到目标数量。
+   - `boundary`：触底并等待追加数据后仍无新增。
+   - `no-new-items`：连续滚动没有新去重项。
+   - `max-steps`：达到滚动步数上限。
+
+## preferredBrand
+
+`zhipin_get_candidate_info` 会从 `candidateInfo.communicationPosition` 中解析：
+
+- `expectedLocation`
+- `expectedPosition`
+- `preferredBrand`
+
+`preferredBrand` 规则：
+
+- 仅当 `communicationPosition` 含连字符类分隔符时输出：`-` / `－` / `—` / `–`。
+- 取分隔符前的第一段，例如 `肯德基-服务员` -> `preferredBrand: "肯德基"`。
+- 没有分隔符时不输出。
+- 禁止用通用岗位名或 `zhipin_get_candidate_list.company` 伪造品牌。
+
+## Reply Authority
+
+`zhipin_send_reply` 只接受 Reply Authority Service 签发的 `signedEnvelope`。
+
+发送前校验：
+
+1. 启动期公钥预加载状态：`browser_status.replyAuthorityKeysLoaded`。
+2. Ed25519 签名。
+3. envelope 过期时间。
+4. replay `jti` 是否已消费。
+5. 当前选中聊天是否匹配 `conversationId + candidateId`。
+6. 当前登录招聘者是否匹配 `recruiterBinding`。
+
+`generate_reply` 的 `target` 两种模式：
+
+```json
+{
+  "platform": "zhipin",
+  "tenantId": "tenant-001",
+  "conversationId": "conversation-1",
+  "candidateId": "candidate-1",
+  "recruiterBinding": { "platform": "zhipin", "username": "郭晓阳" }
+}
+```
+
+```json
+{
+  "platform": "zhipin",
+  "conversationId": "conversation-1",
+  "candidateId": "candidate-1",
+  "recruiterUsername": "郭晓阳"
+}
+```
+
+第二种代理模式由 `smart-reply-agent` 调用 Reply Authority resolver 解析 `tenantId + recruiterBinding`。
+
+## 推荐候选人链路
+
+1. `zhipin_open_recommend_page()`。
+2. `zhipin_filter_recommend_candidates(ageMin?, ageMax?, gender?, activity?)`。
+3. `zhipin_get_candidate_list(maxResults?, autoScroll=true, maxScrolls=4)`。
+4. `zhipin_say_hello(indices)`。
+
+`zhipin_say_hello(indices)` 的 `indices` 也是当前 DOM 快照索引；筛选、滚动或列表刷新后必须重新读取列表。