@roll-agent/browser-use-agent 0.23.0 → 0.24.0

package/SKILL.md

@@ -22,7 +22,7 @@ metadata:
 - 实例级关闭使用 `roll browser stop <browserInstance...>` 或 `roll browser stop --all`；它只关闭当前 `browser-use-agent` 托管的浏览器 runtime，不停止 agent 服务进程，也不删除 `userDataDir` / `sessionsDir` 数据。停止整个服务仍使用 `roll agent stop browser-use-agent`。
 - `browser_status` 是无副作用诊断工具；它不会为了查询状态而启动尚未启动的 Chrome。需要启动某个实例时，调用带 `browserInstance` 的业务工具，例如 `open_platform({ browserInstance, platform:"zhipin" })`。
 - `browser_status.primaryInstanceId` 表示顶层 `running/headless/mode/security` 所采用的 primary bundle；多实例详情请看 `instances[]`。
-- `REPLY_AUTHORITY_URL` / `REPLY_AUTHORITY_BEARER_TOKEN` 是生成智能回复预览、读取冻结 rubric 和回传双稿终态的必填环境变量；调用方 token 必须能访问目标租户并具备 `reply-feedback:write`。`REPLY_AUTHORITY_KEYS_URL` 是发送预备回复前验签的必填环境变量。`roll doctor` 会通过 `references/env.yaml` 和 `browser_status.effectiveEnvSources` 检查它们是否声明并在运行态生效。
+- `REPLY_AUTHORITY_URL` / `REPLY_AUTHORITY_BEARER_TOKEN` 是生成智能回复预览、读取冻结 rubric 和回传双稿终态的必填环境变量；调用方 token 必须能访问目标租户并具备 `reply-feedback:write`。`REPLY_AUTHORITY_KEYS_URL` 是发送预备回复前验签的必填环境变量。客户端默认 `REPLY_AUTHORITY_TIMEOUT_MS=60000`，保持大于 RFC 的完整请求截止时间；生产仍建议显式声明，`roll doctor` 会通过 `references/env.yaml` 和 `browser_status.effectiveEnvSources` 检查配置是否在运行态生效。
 - 当前双稿闭环要求 Reply Authority RFC V3（支持 `feedbackOutcome`、`decisionSource`、`feedbackExpiresAt`）；部署顺序必须是 **Reply Authority V3 → 新版 browser-use-agent**，不要将新版 agent 连接到旧服务。
 - 双稿 feedback outbox 默认写入 `~/.roll-agent/browser/reply-feedback-outbox.sqlite`，默认保留 7 天、每 30 秒刷新；可用 `REPLY_FEEDBACK_OUTBOX_DB_PATH`、`REPLY_FEEDBACK_OUTBOX_RETENTION_SECONDS`、`REPLY_FEEDBACK_OUTBOX_FLUSH_INTERVAL_MS` 覆盖。实际重试截止时间取服务端 `feedbackExpiresAt` 与本地 retention 的较早值。
 - `BROWSER_SECURITY_JSON` 可选配置浏览器硬安全策略；`browser_status.security` 会返回实际加载后的 `domainAllowlist`、`maxPageContentBytes`、`maxSnapshotNodes`、`actionPolicy` 和 `foregroundPolicy`。`foregroundPolicy` 默认 `when-minimized`，普通后台窗口不抢桌面焦点；仅需要旧行为时才显式设为 `always`。
@@ -219,7 +219,7 @@ click_ref(@eN) 或 type_ref(@eN, text, clear?)
 | `zhipin_open_chat_page(forceReload?, expectedConversationId?, browserActionApproval?)` | native CDP | 点击左侧导航切回「沟通」；`forceReload:true` 时只对当前沟通页执行 `Page.reload`，先等待 document swap，再等待实际聊天列表 DOM 就绪；传 `expectedConversationId` 时会按需滚动列表并等待该会话行恢复。若实时页面已不是沟通页，会跳过 reload 并返回 `reloadSkippedReason`。 |
 | `zhipin_open_chat(conversationId?, candidateName?, index?, preferUnread?)` | native CDP | 打开目标聊天；匹配优先级为 `conversationId` > `candidateName` > `index`。 |
 | `zhipin_get_candidate_info(conversationId?, candidateName?, index?, maxMessages?)` | native CDP | 提取候选人资料、聊天记录、`conversationId`、`candidateId` 和页面职位信号；候选人顶部资料会把 `25年应届生` / `28年应届生` 归一为 `应届生`，避免误当工作年限；成功后自动触发 Reply Authority 回复上下文预热（fire-and-forget，失败静默）。输出中的 `locationSignals` 已废弃，恒为空数组。 |
-| `zhipin_generate_reply_preview(conversationId?, candidateName?, index?, maxMessages?, reasoning?)` | native CDP | 读取聊天上下文并透传给 Reply Authority SSE 流式生成回复；地点证据由服务端 turn_planning 合并提取并经 `location.resolved` 事件回显；浏览器内展示阶段、临时草稿与时延摘要（含预热命中标记）。服务端双稿且 rubric 可用时额外返回中性的 `replyVariantSelection.options[].option`（`option_1`/`option_2`）和文本，不暴露 `signedEnvelope` / `draft` / `revised`；rubric 拉取、hash 或双稿结构异常时不展示 A/B，但会保留 group 生命周期元数据，待发送推荐稿成功后由 send/outbox 提交 `not_learned` 并关闭 Pending。若 Reply Authority 拒签/超时/服务端异常，失败输出带 `errorKind:"rejected"|"timeout"|"server_error"`。 |
+| `zhipin_generate_reply_preview(conversationId?, candidateName?, index?, maxMessages?, reasoning?)` | native CDP | 读取聊天上下文并透传给 Reply Authority SSE 流式生成回复；地点证据由服务端 turn_planning 合并提取并经 `location.resolved` 事件回显；浏览器内展示阶段、临时草稿与时延摘要（含预热命中标记）。服务端双稿且 rubric 可用时额外返回中性的 `replyVariantSelection.options[].option`（`option_1`/`option_2`）和文本，不暴露 `signedEnvelope` / `draft` / `revised`；rubric 拉取、hash 或双稿结构异常时不展示 A/B，但会保留 group 生命周期元数据，待发送推荐稿成功后由 send/outbox 提交 `not_learned` 并关闭 Pending。若 Reply Authority 拒签/超时/服务端异常，失败输出带 `errorKind:"rejected"|"timeout"|"server_error"`，并保留脱敏的 `requestId`、`elapsedMs`、客户端硬墙钟预算 `clientTimeoutMs`、`lastStartedPhase` / `activePhase` 与已完成 `phaseLatencies`。 |
 | `zhipin_judge_prepared_reply(preparedReplyId, judgeModel?)` | MCP Sampling | 独立预览双稿判断；Judge 会结合候选人当前问题、最近对话、脱敏资料和 frozen rubric，返回带具体 `reason` 的 `variantDecision`，并缓存供发送复用。失败时返回 `fallback:true`、`decisionSource:"service_recommended_fallback"` 和稳定安全原因码；原始 provider/解析错误只写本地日志。发送阶段会回传 `not_learned` 终态，但不产生学习样本。 |
 | `zhipin_send_prepared_reply(preparedReplyId, variantDecision?, skipVariantJudge?, toolActionApproval?, browserActionApproval?)` | native CDP | 发送预备回复。双稿缺少 `variantDecision` 时工具内部必定执行并缓存默认 Judge，避免 `roll chat` 编排遗漏；预览阶段已降级的 group 则直接发送顶层推荐稿，不再调用 Judge。成功发送后先将 `selected` 或 `not_learned` 终态落到 agent-global SQLite outbox，再 POST `/reply-feedback`。`accepted/duplicate` 表示终态已闭合；`queued` 表示候选人消息已发送、outbox 将只重试 feedback；`failed` 表示消息已发送但 feedback 仍有缺口。后两种状态都禁止重调 send 修复 feedback，避免重复发送候选人消息。Judge fallback 和 `skipVariantJudge:true` 都发送推荐稿、回传来源并关闭服务端 Pending，但不进入 Beta 学习；`feedbackExpected:false` 只表示不进入学习，不表示无需回传终态。重试截止时间不会晚于服务端 `feedbackExpiresAt`；确认策略与原 approval 重试流程保持不变。 |
 | `zhipin_exchange_wechat(conversationId?, candidateName?, index?)` | native CDP | 点击「换微信」和确认弹窗，优先按 `conversationId` 定位聊天。 |
@@ -278,7 +278,7 @@ click_ref(@eN) 或 type_ref(@eN, text, clear?)
 3. 调 `zhipin_open_chat`、`zhipin_get_candidate_info`、`zhipin_exchange_wechat` 时优先传 `conversationId`。
 4. 生成聊天回复优先调用 `zhipin_generate_reply_preview(conversationId)`；它会打开目标聊天、在浏览器内展示 Reply Authority SSE 的阶段、工具执行状态和临时草稿，不需要先额外调用 `zhipin_open_chat`。
 5. `draft.delta` 只能展示，不能发送；真正可发送内容只来自 Reply Authority `final` 事件生成的内部签名结果。
-6. 若 `zhipin_generate_reply_preview` 失败且 `errorKind="rejected"`，这是服务端事实核验/业务拒签，不要当成系统崩溃；`errorKind="timeout"` 才提示重试或降低推理预算；`errorKind="server_error"` 作为服务端异常处理。
+6. 若 `zhipin_generate_reply_preview` 失败且 `errorKind="rejected"`，这是服务端事实核验/业务拒签，不要当成系统崩溃；`errorKind="timeout"` 才提示重试或降低推理预算；`errorKind="server_error"` 作为服务端异常处理。排障时优先关联 `requestId`，并用 `activePhase`、`lastStartedPhase` 和 `phaseLatencies` 区分客户端墙钟超时与 RFC 具体阶段失败。
 7. `zhipin_judge_prepared_reply(preparedReplyId)` 只用于提前查看/展示判断；即使 orchestrator 遗漏这一步，`zhipin_send_prepared_reply` 也会对双稿自动 Judge。不要仅凭文本长短自行选择 option。
 8. 发送回复只能调用 `zhipin_send_prepared_reply(preparedReplyId, variantDecision?, skipVariantJudge?, toolActionApproval?, browserActionApproval?)`；主输入只能使用 `preparedReplyId`，确认重试时可原样带回 `needs_confirmation` 返回的 approval；不要构造裸文本发送路径，也不要保存或传递 `signedEnvelope`。不得为了节省延迟自行设置 `skipVariantJudge:true`。
 9. `feedbackStatus="queued"` 或 `"failed"` 时，候选人消息已经发送；不得再次调用 `zhipin_send_prepared_reply` 修 feedback。`queued` 由 outbox 仅重试 feedback POST；`failed` 应修复 token、服务或 outbox 后单独处理反馈缺口。

package/dist/diagnostics/effective-env.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export declare const BROWSER_USE_DECLARED_ENV_KEYS: readonly ["REPLY_AUTHORITY_URL", "REPLY_AUTHORITY_BEARER_TOKEN", "REPLY_AUTHORITY_KEYS_URL", "RECRUITMENT_EVENTS_ENABLED", "RECRUITMENT_EVENTS_API_BASE_URL", "RECRUITMENT_EVENTS_API_TOKEN", "RECRUITMENT_EVENTS_DEFAULT_AGENT_ID", "BROWSER_SECURITY_JSON", "BROWSER_INSTANCES_JSON", "BROWSER_USE_POLICY_JSON", "BROWSER_VISUAL_CURSOR", "BROWSER_VISUAL_ACTIVITY"];
+export declare const BROWSER_USE_DECLARED_ENV_KEYS: readonly ["REPLY_AUTHORITY_URL", "REPLY_AUTHORITY_BEARER_TOKEN", "REPLY_AUTHORITY_TIMEOUT_MS", "REPLY_AUTHORITY_KEYS_URL", "RECRUITMENT_EVENTS_ENABLED", "RECRUITMENT_EVENTS_API_BASE_URL", "RECRUITMENT_EVENTS_API_TOKEN", "RECRUITMENT_EVENTS_DEFAULT_AGENT_ID", "BROWSER_SECURITY_JSON", "BROWSER_INSTANCES_JSON", "BROWSER_USE_POLICY_JSON", "BROWSER_VISUAL_CURSOR", "BROWSER_VISUAL_ACTIVITY"];
 export declare const EffectiveEnvSourceSchema: z.ZodObject<{
     present: z.ZodBoolean;
     fingerprint: z.ZodOptional<z.ZodString>;