@roll-agent/smart-reply-agent 1.3.6 → 1.3.8

package/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: smart-reply-agent
-description: 招聘智能回复 Agent。根据候选人消息和上下文，向 Reply Authority Service 请求已签名回复。
+description: 根据显式提供的候选人消息和上下文向 Reply Authority Service 请求并透传已签名回复协议；不负责 BOSS 页面、发送、双稿 Judge 或 feedback。需要浏览器发送闭环时使用 browser-use-agent。
 metadata:
   roll-env-file: references/env.yaml
 ---
 
 # Smart Reply Agent
 
-招聘场景智能回复 Agent，负责把候选人消息转发到 Reply Authority Service，返回建议回复和带 Ed25519 签名的发送信封。
+招聘场景智能回复 Agent，负责把候选人消息转发到 Reply Authority Service，返回建议回复、带 Ed25519 签名的发送信封，以及服务端可选的双稿协议数据。
 
 npm 包名：`@roll-agent/smart-reply-agent`
 
@@ -22,18 +22,18 @@ npm 包名：`@roll-agent/smart-reply-agent`
 
 ## 能力边界
 
-本 Agent 只负责**向 Reply Authority Service 请求已签名回复**。
+本 Agent 只负责**向 Reply Authority Service 请求并透传已签名回复协议**。
 
-不会：打开聊天页面、读取候选人资料页面、抓取当前聊天记录、直接发送消息、交换微信、执行浏览器自动化。
+不会：打开聊天页面、读取候选人资料页面、抓取当前聊天记录、执行双稿 Judge、调用 `/reply-feedback`、维护 feedback outbox、直接发送消息、交换微信、执行浏览器自动化。
 
-如果任务需要页面操作或消息发送，应选择 `browser-use-agent`；如果只是基于已给定的 `candidateMessage`、`conversationHistory`、`candidateInfo` 和 `target` 获取已签名回复，应选择本 Agent。
+如果任务需要 BOSS 页面操作、消息发送或双稿闭环，应从生成阶段开始选择 `browser-use-agent`；如果只是基于已给定的 `candidateMessage`、`conversationHistory`、`candidateInfo` 和 `target` 获取协议响应，且调用方自行负责后续发送与 feedback 终态，才选择本 Agent。
 
 ## Tools
 
 完整 inputSchema 可通过 `roll agent tools smart-reply-agent`（或 `--json`）查询。
 
 - `generate_reply(candidateMessage, conversationHistory?, candidateInfo?, preferredBrand?, preferredBrandId?, channelType?, defaultWechatId?, industryVoiceId?, turnIndex?, modelConfig?, target)`
-  调用 Reply Authority Service 的 `POST /generate-signed-reply`，返回 `suggestedReply`、`signedEnvelope`、`envelopeExp`、`confidence`、`stage` 和可选 `diagnostics`。`target` 为必填，至少包含 `platform=zhipin`、`conversationId`、`candidateId`，以及以下两种 recruiter 绑定方式之一：
+  调用 Reply Authority Service 的 `POST /generate-signed-reply`，返回 `suggestedReply`、`signedEnvelope`、`envelopeExp`、`confidence`、`stage`、可选 `diagnostics`，以及服务端启用双稿时的 `replyVariants`。RFC V3 的 `replyVariants` 包含 `groupId`、`recommended`、`findings`、`items`、`rubricVersion` / `rubricHash`、服务端权威 `feedbackExpiresAt` 和两份已签名候选稿；`feedbackExpiresAt` 是 Unix 秒终态截止时间，本 Agent 不会据此建立 outbox 或自动回调。`target` 为必填，至少包含 `platform=zhipin`、`conversationId`、`candidateId`，以及以下两种 recruiter 绑定方式之一：
   1. 直接传完整绑定：`tenantId + recruiterBinding`
   2. 便利代理模式：`recruiterUsername`（smart-reply 会先调用 `POST /resolve-recruiter-binding` 解析出 `tenantId + recruiterBinding`）
 
@@ -116,7 +116,8 @@ npm 包名：`@roll-agent/smart-reply-agent`
 - 实际回复生成、reply-policy、FactGate、ReplyGate、年龄校验都在云端执行
 - `modelConfig.reasoning` 会透传给 Reply Authority Service；raw reasoning/thinking 文本不会作为业务输出返回
 - 返回的 `signedEnvelope` 为 v2 信封，已绑定 `tenantId + recruiterBinding + conversationId + candidateId`；浏览器发送主链路应优先使用 `browser-use-agent.zhipin_generate_reply_preview(...) -> zhipin_send_prepared_reply(preparedReplyId)`
-- 若服务端返回 `replyVariants`，`generate_reply` 只做协议透传；它不会隐藏 `signedEnvelope`，也不会执行 judge / `/reply-feedback`。需要双稿闭环时，主链路必须改用 `browser-use-agent.zhipin_generate_reply_preview(...) -> zhipin_judge_prepared_reply(...) -> zhipin_send_prepared_reply(...)`
+- 若服务端返回 `replyVariants`，`generate_reply` 只做协议透传；它不会隐藏 `signedEnvelope`，也不会执行 Judge、提交 `selected/not_learned`、调用 `/reply-feedback` 或维护 outbox。直接调用方必须自行发送且在 Unix 秒 `feedbackExpiresAt` 前关闭终态，不能只取顶层推荐稿后忽略 group
+- 在 Roll 的 BOSS 发送链路中，应在生成前就选择 `browser-use-agent.zhipin_generate_reply_preview(...) -> zhipin_send_prepared_reply(preparedReplyId, variantDecision?)`。send 缺少显式 `variantDecision` 时会内部执行并缓存默认 Judge；`zhipin_judge_prepared_reply(...)` 仅用于可选预览，不是默认必经步骤
 - 调用失败时抛 `ReplyAuthorityRequestError`，携带 `meta: {url, timeoutMs, requestId}` 与 `Error.cause` 链。通过 `roll run` 运行时 stderr 会展开 `cause: ...` 行用于定位；透传的 `x-request-id` 可跨服务端追踪
 - `diagnostics.brandResolutionSource="none"`、`diagnostics.resolvedBrand=""`、`diagnostics.ageGate.status="unknown"` 都是合法服务端结果，不代表 tool 调用失败。是否补问用户或转人工，是 orch 层策略，不是本 Agent 的重试条件
 
@@ -125,11 +126,13 @@ npm 包名：`@roll-agent/smart-reply-agent`
 机器可读的 env 契约见 `references/env.yaml`。如果你是上层编排 Agent，请优先读取它来生成/校验 `agents.env.smart-reply-agent` 配置。
 
 - `REPLY_AUTHORITY_URL` — Reply Authority Service 基础地址（必填）
-- `REPLY_AUTHORITY_BEARER_TOKEN` — 调用 `POST /generate-signed-reply` 的 Bearer token（必填）
-- `REPLY_AUTHORITY_TIMEOUT_MS` — Reply Authority Service HTTP 请求超时毫秒数（可选，默认 `30000`）。非正整数或非法值会被静默忽略并回落到默认值
+- `REPLY_AUTHORITY_BEARER_TOKEN` — 调用 `POST /generate-signed-reply`，以及代理模式下 `POST /resolve-recruiter-binding` 的 Bearer token（必填）；必须能访问目标 tenant。本 Agent 不使用它调用 rubric 或 `/reply-feedback`，因此自身不要求 `reply-feedback:write`；外部调用方若自行完成双稿 rubric/feedback，则须另行保证对应客户端/token 具备该 scope
+- `REPLY_AUTHORITY_TIMEOUT_MS` — Reply Authority Service HTTP 请求超时毫秒数（可选，客户端默认 `60000`）。非正整数或非法值会被静默忽略并回落到默认值；该默认值高于 RFC 当前 `50000ms` 的完整请求截止时间，让服务端能先返回带 phase 证据的 `504`。生产仍建议显式声明以便 `roll doctor` 核验
 
 ## 典型跨 Agent 工作流
 
+以下流程只适用于“获取协议响应但不由 Roll 直接发送”，或调用方已经自行实现双稿发送与 `/reply-feedback` 终态的场景。若最终要通过 BOSS 浏览器发送，应直接使用后面的 browser-use prepared-reply 主链路，不要先调用 `smart-reply-agent.generate_reply` 再丢弃其 `replyVariants` group。
+
 1. `browser-use-agent.zhipin_get_username()` → 获取当前 BOSS 账号 `username`
 2. `browser-use-agent` 读取候选人资料、聊天记录或当前页面上下文，并从 `zhipin_read_messages` / `zhipin_get_candidate_info` 获取 `conversationId + candidateId`
    - 一旦拿到这两个 ID，后续整个链路都应原样复用，不要再退回 `index`
@@ -143,7 +146,20 @@ npm 包名：`@roll-agent/smart-reply-agent`
    - 直接模式：传 `target.tenantId + target.recruiterBinding`
    - 代理模式：只传 `target.recruiterUsername=username`，由 smart-reply 代调用 `POST /resolve-recruiter-binding`
 5. `smart-reply-agent.generate_reply(..., target)` 获取 `suggestedReply + signedEnvelope`，并在服务端开启双稿时透传 `replyVariants`
-6. 若需要在 BOSS 浏览器中展示生成过程、隐藏 `signedEnvelope`、执行默认 judge 或回传 `/reply-feedback`，优先改用 `browser-use-agent.zhipin_generate_reply_preview(...) -> zhipin_judge_prepared_reply(...) -> zhipin_send_prepared_reply(preparedReplyId, variantDecision?)`，不要把 `signedEnvelope` 作为跨 Agent 编排参数传递
+6. 若返回 `replyVariants`，调用方必须自行发送并按 RFC V3 关闭终态；本 Agent 不提供该回传 tool：
+   - Judge 或 orchestrator 确定 A/B 选择：提交 `feedbackOutcome:"selected"`，`decisionSource:"judge"|"orchestrator"`，并按实际核实结果提供 `confirmedFindingCodes`
+   - rubric/Judge fallback 或显式 no-Judge：只发送服务推荐稿，提交 `feedbackOutcome:"not_learned"`，使用 `decisionSource:"service_recommended_fallback"|"explicit_no_judge"`，且不得携带 `confirmedFindingCodes`
+
+Roll 的 BOSS prepared-reply 主链路：
+
+```text
+browser-use-agent.zhipin_generate_reply_preview(...)
+  -> [可选预览] browser-use-agent.zhipin_judge_prepared_reply(preparedReplyId)
+  -> browser-use-agent.zhipin_send_prepared_reply(preparedReplyId, variantDecision?)
+     # 缺省时 send 内部 Judge；发送成功后自动持久化并回传 selected/not_learned
+```
+
+不要把 `signedEnvelope` 作为跨 Agent 编排参数传递，也不要为了修复 `feedbackStatus:"queued"|"failed"` 而重复发送候选人消息。
 
 ## Recommended roll.config.yaml
 
@@ -155,6 +171,6 @@ agents:
     smart-reply-agent:
       REPLY_AUTHORITY_URL: https://reply-authority.duliday.com
       REPLY_AUTHORITY_BEARER_TOKEN: ${REPLY_AUTHORITY_BEARER_TOKEN}
-      # 可选：自定义 HTTP 超时（毫秒，默认 30000）
-      # REPLY_AUTHORITY_TIMEOUT_MS: "45000"
+      # RFC 完整请求截止时间为 50000ms 时，调用方需保留响应缓冲
+      REPLY_AUTHORITY_TIMEOUT_MS: "60000"
 ```

package/dist/tools/generate-reply.d.ts

@@ -86,5 +86,6 @@ export declare const generateReply: import("@roll-agent/sdk").ToolDefinition<{
         }[];
         rubricVersion: string;
         rubricHash: string;
+        feedbackExpiresAt?: number | undefined;
     } | undefined;
 }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/smart-reply-agent",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "type": "module",
   "repository": {
     "type": "git",
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "zod": "^3.25.76",
-    "@roll-agent/reply-authority-client": "0.5.0",
+    "@roll-agent/reply-authority-client": "0.7.0",
     "@roll-agent/sdk": "0.3.0"
   },
   "devDependencies": {

package/references/env.yaml

@@ -6,12 +6,12 @@ required:
     example: https://reply-authority.duliday.com
   - name: REPLY_AUTHORITY_BEARER_TOKEN
     secret: true
-    purpose: Reply Authority Service Bearer token；服务端据此反查 clientId 并校验可访问的 tenantId
+    purpose: Reply Authority Service Bearer token；用于 generate-signed-reply，以及代理模式下 resolve-recruiter-binding；必须能访问目标 tenant。本 Agent 不调用 feedback rubric 或 /reply-feedback，因此自身不要求 reply-feedback:write
     example: ${REPLY_AUTHORITY_BEARER_TOKEN}
 optional:
   - name: REPLY_AUTHORITY_TIMEOUT_MS
     secret: false
     type: number
-    purpose: Reply Authority Service HTTP 请求超时（毫秒）。未设置或值无效时回落默认 30000
-    example: "30000"
-    default: "30000"
+    purpose: Reply Authority Service 调用方硬墙钟超时（毫秒）。未设置或值无效时回落客户端默认 60000，保持高于 RFC 当前 50000ms 的完整请求截止时间；生产仍建议显式声明以便 doctor 核验
+    example: "60000"
+    default: "60000"