feat(mcp)★★: 自动转发通道 —— relay/relay_key，并修掉一个从未生效的幂等文案

用户 2026-10-04：「不只是 Agent 主动回，还有自动转发 Agent 的最后一条消息」。

## 为什么 MCP 侧需要显式上报，而插件侧不用

  插件（pi / dsh / homeagent）有 `session.idle` 钩子：
    宿主进程在自己会话 idle 时读到最后一条回复 → 自动 send_mail(relay=…)
  MCP 宿主（Codex / Claude Desktop）**没有这个概念**：
    不知道「这一轮处理完了」，也不会主动调 send_mail。
    ⇒ 宿主必须显式上报，服务端才可能自动转发。

  所以新增 `send_mail(relay="summary", relay_key="<宿主消息 id>")`：
  relay=summary 免配额（服务端既有逻辑），relay_key 提供幂等。

## 顺带修掉一个从未生效的幂等文案（既有缺陷）

    MCP 侧读：str(payload, "duplicate_relay")
    服务端返：{"status": "duplicate_relay", "detail": "该上游消息已转发过…"}

  **字段名对不上 ⇒ 那段逻辑从来没生效过。**

  后果对 MCP 接入端尤其致命：它的自动转发正是靠 relay_key 幂等兜底，
  而宿主重试时看到的是「已发送」（无 mail_id、无任何异常），
  于是继续重试 —— 每一轮都在消耗一次往返。

  现在文案是：
    该上游消息（relay_key: xxx）已转发过，本次调用未产生新邮件 —— 不需要重试。

## 判据（3 格，2 个变异都转红）

- send_mail 暴露 relay / relay_key（去掉透传 → 转红）
- relay 非空而 relay_key 为空必须被拒
- 同一 relay_key 第二次转发报重复，且**只有一封真邮件**

## 判据自己错了两次

1. `TestRelayRequiresKey` 红着但**原因不对**：没建收件人，400 发生在
   「收件人不存在」那一步，掩盖了 parseRelay 的校验。
2. 幂等那格被我自己 `Skip` 了 —— `.relay-idem` 会话不存在，
   于是「幂等没被击穿」的假绿。改为 `.new` 并**禁止 Skip**：
   幂等是自动转发不重投的唯一保证，它绿着才敢让宿主上报。
   （判据不可达 = 描述的状态不存在。）

## 双向对齐判据立刻证明了价值

加了 relay/relay_key 却没登记，它当场红：

    ★ send_mail 的参数 "relay" 既不在插件版、也没登记为 MCP 额外

若它不存在，加了新参数就会静默通过，而「这个能力是有意加的还是漏登记的」
正是以后没人能回答的问题。relay 登记为「额外」而非「缺失」——
插件侧走 session.idle，不需要这条参数。

14 包全绿。

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)
+}

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{}

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()
 }

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)