diff --git a/server/internal/mcp/relay_test.go b/server/internal/mcp/relay_test.go new file mode 100644 index 0000000..055cbfa --- /dev/null +++ b/server/internal/mcp/relay_test.go @@ -0,0 +1,124 @@ +package mcp + +/* +MCP 自动转发通道的判据(2026-10-04)。 + +★ 用户要的:「不只是 Agent 主动回,还有自动转发 Agent 的最后一条消息」。 + +## 为什么 MCP 侧需要显式上报,而插件侧不用 + + 插件(pi / dsh / homeagent)有 `session.idle` 钩子: + 宿主进程在自己的会话里 idle 时读到最后一条回复 → 自动调 send_mail(relay=…) + MCP 宿主(Codex / Claude Desktop)**没有这个概念**: + 它不知道「这一轮处理完了」,也不会主动调 send_mail。 + ⇒ 宿主必须显式上报,服务端才可能自动转发。 + +## 幂等靠什么 + + `relay_key` 由**宿主**生成(模型伪造不出),服务端 `relayed_mails` + 有唯一约束 ⇒ 同一 id 只能转发一次,重试拿 duplicate_relay 而不重复投递。 + 与各桥的 relay 幂等语义一致(见 handler/mail.go 的注释)。 +*/ + +import ( + "context" + + "github.com/agentmail/gateway/internal/db" + "strings" + "testing" +) + +func TestSendMailExposesRelayParams(t *testing.T) { + s := NewServer(nil) + NewTools().RegisterAll(s) + props, _ := s.tools["send_mail"].Schema().InputSchema["properties"].(map[string]any) + for _, k := range []string{"relay", "relay_key"} { + if _, has := props[k]; !has { + t.Errorf("★ send_mail 缺参数 %q —— MCP 接入端无法走免配额转发通道,"+ + "「自动转发最后一条」在这条路上不成立", k) + } + } +} + +// relay 非空时必须带 relay_key,否则幂等无从谈起。 +func TestRelayRequiresKey(t *testing.T) { + setupDB(t) + // ★ 收件人必须是真实用户。 + // 初版没建 gui-lab,于是请求在「收件人不存在」那一步就 400 了, + // 而 parseRelay 的 400 也被算成 200 分支之外 —— 判据红着但原因不对。 + // 修正后仍红,才说明「relay 缺 key 没被拒」是真的。 + if _, err := mustSeedHuman(t, "gui-lab"); err != nil { + t.Fatalf("建收件人: %v", err) + } + s := newTestServer() + // 无 relay_key 就该被服务端拒(400),而不是静默当成普通发信 + code, msg := call(t, s, "pi", "send_mail", map[string]any{ + "to": "gui-lab@/tmp.new", "subject": "缺 relay_key", "body": "x", + "relay": "summary", + }) + txt, _ := toolText(t, msg) + if !strings.Contains(strings.ToLower(txt), "relay_key") && + !strings.Contains(strings.ToLower(txt), "relay key") { + t.Errorf("★ relay 非空而 relay_key 为空,服务端应明确报错;实际 %d %q", code, txt) + } +} + +// relay_key 幂等:同一 key 转发两次,第二次必须是 duplicate 而非新邮件。 +func TestRelayKeyIsIdempotent(t *testing.T) { + setupDB(t) + if _, err := mustSeedHuman(t, "gui-lab"); err != nil { + t.Fatalf("建收件人: %v", err) + } + s := newTestServer() + const key = "mcp-relay-idem-1" + + _, first := call(t, s, "pi", "send_mail", map[string]any{ + "to": "gui-lab@/tmp.new", "subject": "转给人类", "body": "本轮总结", + "relay": "summary", "relay_key": key, + }) + txt1, _ := toolText(t, first) + if strings.Contains(txt1, "执行失败") { + // ★ 不许 Skip。Skip 会让这一格在 CI 上悄悄消失,而幂等是 + // 「自动转发」不重投的唯一保证 —— 它绿着才敢让宿主上报。 + // (初版这里 Skip 过一轮:.relay-idem 会话不存在 ⇒ + // 「幂等没被击穿」的假绿。判据不可达 = 描述的状态不存在。) + t.Fatalf("relay 转发不该失败:%s", txt1) + } + + _, second := call(t, s, "pi", "send_mail", map[string]any{ + "to": "gui-lab@/tmp.new", "subject": "转给人类", "body": "本轮总结", + "relay": "summary", "relay_key": key, + }) + txt2, _ := toolText(t, second) + if !strings.Contains(txt2, "duplicate") && !strings.Contains(txt2, "已转发") { + t.Errorf("★ 同一 relay_key 第二次转发应报重复,实际:%s", txt2) + } + + // ★ 只有一封真邮件(否则是重复投递,而那正是要防的)。 + // 按**收件人**计数,不按会话别名 —— `.new` 每次会建新会话, + // 按别名查会得到 0,那与「幂等被击穿」是两回事,不能混。 + var n int + if err := dbCountMailsTo(t, "gui-lab", &n); err != nil { + t.Fatalf("计数: %v", err) + } + if n != 1 { + t.Errorf("★ 幂等被击穿:同一 relay_key 发给同一收件人产生了 %d 封邮件", n) + } + _ = context.Background() +} + +// mustSeedHuman 建一个真实人类用户(relay 免配额的条件是收件人是人)。 +func mustSeedHuman(t *testing.T, username string) (bool, error) { + t.Helper() + _, err := db.DB.ExecContext(context.Background(), + `INSERT INTO users (username, password_hash, role) VALUES ($1,'x','user') + ON CONFLICT (username) DO NOTHING`, username) + return true, err +} + +// dbCountMailsTo 数发给某收件人的邮件数。 +func dbCountMailsTo(t *testing.T, to string, n *int) error { + t.Helper() + return db.DB.QueryRowContext(context.Background(), + `SELECT COUNT(*) FROM mails WHERE to_name = $1`, to).Scan(n) +} diff --git a/server/internal/mcp/rename_proposal_test.go b/server/internal/mcp/rename_proposal_test.go index dbaeb8a..e893f8f 100644 --- a/server/internal/mcp/rename_proposal_test.go +++ b/server/internal/mcp/rename_proposal_test.go @@ -206,11 +206,12 @@ func TestToolsAlignWithPluginBridgeBidirectionally(t *testing.T) { // 反向:MCP 独有的参数必须显式登记 mcpExtra := map[string][]string{ - "forward_mail": {"session_id"}, - "read_inbox": {"session_id", "workspace"}, - "read_mail": {"session_id"}, - "read_thread": {"session_id"}, - "send_mail": {"attachment_ids", "propose_alias", "propose_reason"}, + "forward_mail": {"session_id"}, + "read_inbox": {"session_id", "workspace"}, + "read_mail": {"session_id"}, + "read_thread": {"session_id"}, + "send_mail": {"attachment_ids", "propose_alias", "propose_reason", + "relay", "relay_key"}, "suggest_address": {"flatten"}, } seen := map[string]bool{} diff --git a/server/internal/mcp/support.go b/server/internal/mcp/support.go index f450be7..d470464 100644 --- a/server/internal/mcp/support.go +++ b/server/internal/mcp/support.go @@ -210,8 +210,25 @@ func summarizeSend(payload map[string]any) string { if sid != "" { fmt.Fprintf(&b, ",落在会话 %s", sid) } - if relay := str(payload, "duplicate_relay"); relay != "" { - fmt.Fprintf(&b, "。注意:%s", relay) + // ★ 幂等重放(2026-10-04 修)。 + // + // 这里原本读 `payload["duplicate_relay"]` —— 而服务端(handler/mail.go + // 的 ClaimRelay 分支)返回的是 **`status: "duplicate_relay"`**。 + // 字段名对不上 ⇒ 这段逻辑从来没生效过 ⇒ 宿主重试拿到的是 + // 「已发送」而没有 mail_id,看起来像投递成功,于是继续重试。 + // + // 对 MCP 接入端这条尤其致命:它的「自动转发」正是靠 relay_key 幂等 + // 兜底的,而宿主看到「已发送」就不会改参数 —— 于是同一条上游消息 + // 被反复转发(服务端不会真的重复建信,但每一轮都在消耗一次往返)。 + if st := str(payload, "status"); st == "duplicate_relay" { + b.Reset() + key := str(payload, "relay_key") + if key != "" { + fmt.Fprintf(&b, "该上游消息(relay_key: %s)已转发过,本次调用未产生新邮件 —— ", key) + } else { + b.WriteString("该上游消息已转发过,本次调用未产生新邮件 —— ") + } + b.WriteString("不需要重试。") } return b.String() } diff --git a/server/internal/mcp/tool_impls.go b/server/internal/mcp/tool_impls.go index 9443e69..2fc1794 100644 --- a/server/internal/mcp/tool_impls.go +++ b/server/internal/mcp/tool_impls.go @@ -120,6 +120,11 @@ func (t *Tools) SendMail() Tool { "propose_alias": strProp("可选。建议把当前会话改名成这个别名 —— 这只是建议," + "别名是人的寻址入口,实际改名由用户在界面上确认。不可含 . / @ 空白,不可为 new"), "propose_reason": strProp("改名理由,一句话,展示给用户看"), + "relay": strProp("免配额转发标记。\"\" | \"permission\" | \"summary\"。\n" + + " 本轮处理完时把最终结果转给人类请填 summary —— 它不扣配额。\n" + + " 人类回信后本轮已完成,不填才是正常发信(要扣配额)。"), + "relay_key": strProp("relay 非空时必填:上游那条消息的稳定标识(宿主侧的消息 id)。\n" + + " 同一 id 只能转发一次(服务端有唯一约束),用于重试时不重复投递。"), }, "to"), }, run: func(ctx context.Context, args map[string]any) (string, error) { @@ -151,6 +156,22 @@ func (t *Tools) SendMail() Tool { if ids := argStrList(args, "attachment_ids"); len(ids) > 0 { body["attachment_ids"] = ids } + // relay / relay_key:MCP 接入端的「本轮总结自动转给人类」通道(2026-10-04)。 + // + // ★ 为什么 MCP 侧需要它而插件侧不用: + // 插件(pi/dsh/…)有 session.idle 钩子,能在宿主侧读到最后一条回复 + // 并自动转发;MCP 宿主(Codex/Claude Desktop)**没有这个概念**, + // 不知道「这一轮处理完了」,也不会主动调 send_mail。 + // ⇒ 宿主必须显式上报,服务端才可能自动转发。 + // + // relay_key 由宿主生成(模型伪造不出),服务端有唯一约束, + // 所以重试不会重复投递 —— 与各桥的 relay 幂等语义一致。 + if v := argStr(args, "relay"); v != "" { + body["relay"] = v + } + if v := argStr(args, "relay_key"); v != "" { + body["relay_key"] = v + } code, payload, raw := invoke(ctx, handler.SendMail, newRequest(ctx, http.MethodPost, "/api/v1/mail/send", body)) if code < 200 || code >= 300 { return render("send_mail", code, payload, raw)