Agent→Agent 不自动转发 + 提示词区分新活/回复/补投

## 设计规则：Agent 之间不自动转发自动转发存在的理由是「人不该等模型记得调 send_mail」—— 收件方是人时这是纯收益。**收件方是另一个 Agent 时这个理由不成立，而且有害**：双方的插件都会自动回一封，于是两个模型都以为「我只要把话说完就行」，实际在持续互相唤醒。生产实测 pi 与 dsh 客套 6 轮直到撞上连续 relay 跳数上限。规则现在写死在共用模块 `lib/relay-policy.js`（三平台逐字节相同）： - `autoRelayDecision` — 插件该不该替模型开口 - `replyInstruction` — 提示词怎么跟模型说（人类 vs Agent 各一套措辞） - `inboundHeadline` — 进来的是新活、回复、还是补投 `from_human` 缺失时保守按 Agent 处理：宁可让模型多调一次 send_mail，也不能承诺一个不会发生的自动回信让发件方白等。 ## Gateway 侧：`in_reply_to` + `from_human` - `notify.Mail` 新增 `ParentMailID`（非空 = 这是对收件方某封信的回复） - `notify.Mail` 新增 `FromHuman`（走 `repo.IsHumanUser`） - SSE payload 里叫 `in_reply_to` / `from_human` - 四个调用点全部传入：handler/mail（转发后产出的邮件，parentMailID 从 resolveTarget 取）、handler/me（同理）、handler/forward（传空串，因为对收件方而言那封原邮件不在它的线索里）、scheduler/calendar（传空串） - `ListInbox` 的 SELECT 加 `EXISTS (SELECT 1 FROM users u WHERE u.username = m.from_name)` → `models.Mail.FromHuman`，让补拉路径也有这个信号 ## 提示词分流三种处境各一套标题： - 新活（人类）：「你收到一封新邮件」+ 「回信不用你自己发：…」 - 新活（Agent）：「你收到一封新邮件（对方是一个 Agent）」+ 「插件不会替你回信。需要回复时你必须自己调 send_mail…请先判断是否真的需要回复」 - 回复到了：「你上一封信的回复到了。**这不是新任务**。」 - 补投：在标题里说明「离线期间积压」 ## homeagent 特殊处理 Go 插件不能直接 `import('../lib/relay-policy.js')`，因此新增 `relay_policy.go` （Go 对应物）+ `relay_policy_test.go`（11 例，逐条对齐 Node 侧判据）。 `sseLoop` / `catchUp` 两条路径都接上。 ## `mailEvent` 命名类型 homeagent 的 SSE 事件解析 / handleNewMail / handlePermissionDecision 三处原来各写一遍匿名 struct（字段列表几乎相同），加 `from_human` / `in_reply_to` 时漏改一处 → 编译报错但错误信息是两串几乎相同的字段列表，极难定位。提成 `mailEvent` 命名类型：一处改、三处跟着走。 ## 测试 - `lib/relay-policy.test.mjs`（Node）16 例：含「replyInstruction 与 autoRelayDecision 不得互相矛盾」「Agent 来信的标题要点名且回复要明确反对」 - `relay_policy_test.go`（Go）11 例：逐条对齐 Node 侧 - `turn.test.mjs` +3 例：from_human 缺失时按 Agent 处理 / Agent 来信时改口 / 回复到了说「不是新任务」；删掉两条旧的「必定自动转发」断言 - 共用脚本 `check-shared-libs.sh` +1 个文件（relay-policy） - pi 288 / dsh 241 / opencode 217 / homeagent 14 / gateway 8 包全绿
2026-09-04 23:52:52 +08:00
parent 375578cf9b
commit 784192d8c4
22 changed files with 1315 additions and 92 deletions
--- a/plugins/homeagent-mail-bridge/plugin.go
+++ b/plugins/homeagent-mail-bridge/plugin.go
@ -530,6 +530,12 @@ func (p *Plugin) catchUp(pending int) {
 			Subject  string `json:"subject"`
 			MailType string `json:"mail_type"`
 			ReplyTo  string `json:"reply_to"`
+			// 补拉路径也必须知道发件方是人还是 Agent：Agent 之间不自动回信。
+			// 缺了它补投的邮件会被保守当成 Agent 来信，于是人发的那封失去自动回复。
+			FromHuman bool `json:"from_human"`
+			// parent_mail_id 非空 = 这封是回信。收件箱返回的字段名是它，
+			// 而 SSE 事件里叫 in_reply_to —— 两个名字指同一件事。
+			ParentMailID string `json:"parent_mail_id"`
 		} `json:"mails"`
 	}
 	url := fmt.Sprintf("%s/api/v1/mail/inbox?status=unread&limit=%d", p.gwURL, limit)
@ -586,14 +592,18 @@ func (p *Plugin) catchUp(pending int) {
 		if resumed {
 			prefix = resumeNote(m.MailID)
 		}
+		replyLine := ""
+		if m.ParentMailID != "" {
+			replyLine = fmt.Sprintf("回的是你那封：%s\n", m.ParentMailID)
+		}
 		prompt := prefix + fmt.Sprintf(
-			"你收到一封新邮件（AgentMail）。\n\n"+
-				"发件人：%s\n主题：%s\n邮件 ID：%s\n身份：你是 %s\n\n"+
+			"%s\n\n"+
+				"发件人：%s\n主题：%s\n邮件 ID：%s\n%s身份：你是 %s\n\n"+
 				"请先调用 read_inbox 读取完整正文，然后处理其中的请求。\n\n"+
-				"**回信不用你自己发**：你把结论说出来就行，\n"+
-				"插件会在这一轮结束时自动把你最后那段话作为回信发回给 %s（不消耗你的发信配额）。\n"+
-				"只有在需要主动联系其他人、或要带附件时才调用 send_mail。",
-			m.FromName, m.Subject, m.MailID, p.agentName, m.FromName,
+				"%s",
+			inboundHeadline(m.ParentMailID, m.FromHuman, true),
+			m.FromName, m.Subject, m.MailID, replyLine, p.agentName,
+			replyInstruction(m.FromHuman, ""),
 		)

 		reply := p.sdk.InjectInputSync(p.name, p.name, prompt)
@ -615,6 +625,16 @@ func (p *Plugin) catchUp(pending int) {
 			continue
 		}

+		// **只给人类来信自动转发**（见 relay_policy.go）。
+		// 与 SSE 路径同一取舍 —— 两条路径行为不一致的话，同一封邮件“走 SSE 还是
+		// 走补投”就能決定发件方有没有回信，而那取决于重启时机。
+		if d := autoRelayDecision(m.FromHuman, m.FromName); !d.relay {
+			log.Printf("[homeagent-mail-bridge] 补投 %s 不自动转发：%s",
+				shortID(m.MailID), d.reason)
+			p.ledger.complete(m.MailID)
+			continue
+		}
+
 		// B-5.2：自动回信带 relay:"summary" —— 搬运不算模型自主发信，不扣配额
 		if err := p.sendMailRelay(m.FromName, "Re: "+m.Subject, reply, m.MailID, rk); err != nil {
 			// 回信没发出去 —— 不标完成，下次重启重试。
@ -627,6 +647,30 @@ func (p *Plugin) catchUp(pending int) {

 // ─── SSE ───

+// mailEvent 是 SSE 事件里与邮件有关的字段。
+//
+// 提成命名类型而不是三处各写一遍匿名 struct：加字段时必须三处同时改，
+// 而漏改一处的表现是「类型不匹配」编译错误里塞满两串几乎相同的字段列表 ——
+// 本轮加 from_human / in_reply_to 时就踩了一次。
+type mailEvent struct {
+	MailID    string `json:"mail_id"`
+	SessionID string `json:"session_id"`
+	FromName  string `json:"from_name"`
+	Subject   string `json:"subject"`
+	MailType  string `json:"mail_type"`
+	Role      string `json:"role"`
+	Workspace string `json:"to_workspace"`
+	Alias     string `json:"session_alias"`
+	ReplyAddr string `json:"reply_address"`
+	// FromHuman 决定要不要自动回信：Agent 之间不自动回（见 relay_policy.go）。
+	FromHuman bool `json:"from_human"`
+	// InReplyTo 非空 = 这封是对本方某封信的回复，不是新派的活。
+	InReplyTo string `json:"in_reply_to"`
+	// Decision / DecidedBy 只在 permission_decision 事件上有值。
+	Decision  string `json:"decision"`
+	DecidedBy string `json:"decided_by"`
+}
+
 func (p *Plugin) sseLoop() {
 	for {
 		select {
@ -733,17 +777,7 @@ func (p *Plugin) parseSSELine(line string) {
 		return
 	}

-	var evt struct {
-		MailID    string `json:"mail_id"`
-		SessionID string `json:"session_id"`
-		FromName  string `json:"from_name"`
-		Subject   string `json:"subject"`
-		MailType  string `json:"mail_type"`
-		Role      string `json:"role"`
-		Workspace string `json:"to_workspace"`
-		Alias     string `json:"session_alias"`
-		ReplyAddr string `json:"reply_address"`
-	}
+	var evt mailEvent
 	if err := json.Unmarshal([]byte(raw), &evt); err != nil {
 		return
 	}
@ -882,17 +916,7 @@ func (p *Plugin) sendFailureReply(to, subject, replyTo, reason string) {

 // ─── 新邮件处理 ───

-func (p *Plugin) handleNewMail(evt struct {
-	MailID    string `json:"mail_id"`
-	SessionID string `json:"session_id"`
-	FromName  string `json:"from_name"`
-	Subject   string `json:"subject"`
-	MailType  string `json:"mail_type"`
-	Role      string `json:"role"`
-	Workspace string `json:"to_workspace"`
-	Alias     string `json:"session_alias"`
-	ReplyAddr string `json:"reply_address"`
-}, resumed bool) {
+func (p *Plugin) handleNewMail(evt mailEvent, resumed bool) {
 	// resumed = 上一个进程注入过这封但那一轮被中断了。
 	//
 	// 必须把这件事告诉模型：不说的话它在上下文里看到两段几乎相同的指令，
@ -903,14 +927,22 @@ func (p *Plugin) handleNewMail(evt struct {
 		log.Printf("[homeagent-mail-bridge] 邮件 %s 重投（上一轮被中断）", shortID(evt.MailID))
 	}

+	replyLine := ""
+	if evt.InReplyTo != "" {
+		replyLine = fmt.Sprintf("回的是你那封：%s\n", evt.InReplyTo)
+	}
+	addrLine := ""
+	if evt.ReplyAddr != "" {
+		addrLine = fmt.Sprintf("回信地址：%s\n", evt.ReplyAddr)
+	}
 	prompt := prefix + fmt.Sprintf(
-		"你收到一封新邮件（AgentMail）。\n\n"+
-			"发件人：%s\n主题：%s\n邮件 ID：%s\n身份：你是 %s\n\n"+
+		"%s\n\n"+
+			"发件人：%s\n主题：%s\n邮件 ID：%s\n%s身份：你是 %s\n%s\n"+
 			"请先调用 read_inbox 读取完整正文，然后处理其中的请求。\n\n"+
-			"**回信不用你自己发**：你把本轮工作做完、把结论说出来就行，\n"+
-			"插件会在这一轮结束时自动把你最后那段话作为回信发回给 %s（不消耗你的发信配额）。\n"+
-			"只有在需要主动联系其他人、或要带附件时才调用 send_mail。",
-		evt.FromName, evt.Subject, evt.MailID, p.agentName, evt.FromName,
+			"%s",
+		inboundHeadline(evt.InReplyTo, evt.FromHuman, false),
+		evt.FromName, evt.Subject, evt.MailID, replyLine, p.agentName, addrLine,
+		replyInstruction(evt.FromHuman, evt.ReplyAddr),
 	)

 	// InjectInputSync 阻塞等待 agent 处理完毕，返回最终回复文本。
@ -944,6 +976,18 @@ func (p *Plugin) handleNewMail(evt struct {
 		return
 	}

+	// **只给人类来信自动转发**（见 relay_policy.go）。
+	//
+	// 对方是 Agent 时它那边的插件也会自动回一封，两个模型都以为「我只要把话
+	// 说完就行」，实际在持续互相唤醒 —— 生产实测 pi 与 dsh 客套 6 轮。
+	// 此时这一封算处理完：模型已经看过并做完了活，没有回信是设计意图而不是失败。
+	if d := autoRelayDecision(evt.FromHuman, evt.FromName); !d.relay {
+		log.Printf("[homeagent-mail-bridge] 邮件 %s 本轮不自动转发：%s",
+			shortID(evt.MailID), d.reason)
+		p.ledger.complete(evt.MailID)
+		return
+	}
+
 	// B-5.2：自动回信带 relay:"summary" + relay_key
 	if err := p.sendMailRelay(evt.FromName, "Re: "+evt.Subject, reply, evt.MailID, rk); err != nil {
 		// 回信没发出去 —— **不标完成**，让下次重启能重试。
@ -966,17 +1010,7 @@ func (p *Plugin) handleNewMail(evt struct {

 // ─── 权限决策 ───

-func (p *Plugin) handlePermissionDecision(evt struct {
-	MailID    string `json:"mail_id"`
-	SessionID string `json:"session_id"`
-	FromName  string `json:"from_name"`
-	Subject   string `json:"subject"`
-	MailType  string `json:"mail_type"`
-	Role      string `json:"role"`
-	Workspace string `json:"to_workspace"`
-	Alias     string `json:"session_alias"`
-	ReplyAddr string `json:"reply_address"`
-}) {
+func (p *Plugin) handlePermissionDecision(evt mailEvent) {
 	prompt := fmt.Sprintf(
 		"你之前发起的权限请求已有结论：%s（决策人：%s）。请据此继续。",
 		evt.Subject, evt.FromName,
--- a/plugins/homeagent-mail-bridge/relay_policy.go
+++ b/plugins/homeagent-mail-bridge/relay_policy.go
@ -0,0 +1,96 @@
+package main
+
+// 自动转发的适用范围，以及据此该给模型说什么话。
+//
+// 这是三个 Node 插件里 `lib/relay-policy.js` 的 Go 对应物。**不能共用那个文件**
+// （homeagent 是 Go 子进程插件），但语义必须一致 —— 因此这里把那边的注释与判据
+// 原样搬过来，`relay_policy_test.go` 逐条钉住。
+//
+// # 为什么 Agent → Agent 不自动转发
+//
+// 自动转发存在的理由是「人不该等模型记得调 send_mail」：人发一封信出去，
+// 模型把活干完、话说完，插件替它把结论搬进邮件。收件方是人时这是纯收益。
+//
+// 收件方是**另一个 Agent** 时这个理由不成立，而且有害：对方的插件同样会自动
+// 回一封，于是两个模型都以为「我只要把话说完就行」，实际上在持续互相唤醒。
+// 生产实测过一条完整的客套链（pi 转发给 dsh，dsh 回确认，pi 又确认那个确认，
+// 一直到第 6 封撞上连续 relay 跳数上限才停）：
+//
+//	pi→dsh   parent=24be32e5   转发
+//	dsh→pi   parent=bf79f8fe   已收到转发
+//	pi→dsh   parent=2700bd0a   收到你的确认
+//	dsh→pi   parent=34127884   确认闭环
+//	pi→dsh   parent=34058c13   …
+//	dsh→pi   parent=9590bf16   ← 被 hop 上限拦下
+//
+// 每一封都不是错的，每一封都没有新信息。跳数上限是最后一道闸，不是设计意图。
+//
+// 因此规则是：**Agent 之间通信必须由模型主动调 send_mail。**
+
+import "fmt"
+
+// relayDecision 是「这一轮的结论该不该由插件自动转发出去」的判定结果。
+type relayDecision struct {
+	relay bool
+	// reason 供日志用 —— 「本轮没有回信」必须能在日志里查到原因，
+	// 否则它与「模型没说话」「转发失败」三种情形长得一样。
+	reason string
+}
+
+// autoRelayDecision 判定要不要自动转发。
+//
+// fromHuman 来自 SSE 的 `from_human`；replyTo 是本来要回给谁。
+func autoRelayDecision(fromHuman bool, replyTo string) relayDecision {
+	if replyTo == "" {
+		return relayDecision{false, "不知道回给谁"}
+	}
+	if !fromHuman {
+		return relayDecision{false, fmt.Sprintf(
+			"来信方 %s 是 Agent，按约定不自动转发（Agent 间通信须由模型主动 send_mail）",
+			replyTo)}
+	}
+	return relayDecision{true, ""}
+}
+
+// replyInstruction 是提示词里关于「回信怎么发」的那几句话。
+//
+// 必须与 autoRelayDecision 一致 —— 这是同一件事的两个出口，分开写必然分叉。
+// 而分叉的代价是模型被骗：它以为插件会替它回信，于是把话说完就停手，
+// 而实际上那封信永远不会发出去，发件方一直等着。
+func replyInstruction(fromHuman bool, replyAddress string) string {
+	if fromHuman {
+		return "**回信不用你自己发**：你把本轮工作做完、把结论说出来就行，\n" +
+			"插件会在这一轮结束时自动把你最后那段话作为回信发回去（不消耗你的发信配额）。\n" +
+			"只有在需要主动联系其他人、或要带附件时才调用 send_mail。"
+	}
+	addr := ""
+	if replyAddress != "" {
+		addr = fmt.Sprintf("（回信地址：%s）", replyAddress)
+	}
+	return "**这封信来自另一个 Agent，插件不会替你回信。**\n" +
+		fmt.Sprintf("需要回复时你必须自己调用 send_mail%s；\n", addr) +
+		"把话说完并不会让对方收到任何东西。\n" +
+		"也请先判断这封信是否真的需要回复 —— 单纯的「收到」「确认」会让两个 Agent\n" +
+		"无休止地互相客套，那对谁都没有价值。有实质结论或有事要问时才回。"
+}
+
+// inboundHeadline 描述「进来的这封是什么」。
+//
+// 在此之前提示词一律说「你收到一封新邮件」，于是模型分不清三种处境：
+// 有人派了新活、我上封信的回复到了、离线期间积压的补投。
+// 第二种被当成第一种时，模型会把一句「已收到」当成待办再处理一遍。
+func inboundHeadline(inReplyTo string, fromHuman, catchup bool) string {
+	who := ""
+	if !fromHuman {
+		who = "（对方是一个 Agent）"
+	}
+	if inReplyTo != "" {
+		// 「回复到了」与「有人派活」是两种处境。说清楚它，模型才不会把
+		// 一句确认当成新任务 —— 那正是互相客套的起点。
+		return fmt.Sprintf("你上一封信的**回复**到了%s。这不是新任务。", who)
+	}
+	if catchup {
+		return fmt.Sprintf("你收到一封新邮件%s。说明：这是插件离线期间积压的邮件，现在补投给你。", who)
+	}
+	return fmt.Sprintf("你收到一封新邮件%s。", who)
+}
--- a/plugins/homeagent-mail-bridge/relay_policy_test.go
+++ b/plugins/homeagent-mail-bridge/relay_policy_test.go
@ -0,0 +1,122 @@
+package main
+
+// relay_policy.go 的单元测试。
+//
+// 这三个函数是 Node 侧 lib/relay-policy.js 的 Go 对应物，**语义必须一致** ——
+// 一个平台自动回信、另一个不回，同一条 Agent 链的行为就取决于对方是谁，
+// 那是无法排查的。所以这里的判据与那边的 relay-policy.test.mjs 逐条对齐。
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestAutoRelay_HumanSenderRelays(t *testing.T) {
+	d := autoRelayDecision(true, "jianf")
+	if !d.relay {
+		t.Fatalf("人类来信必须自动转发，got reason=%q", d.reason)
+	}
+}
+
+func TestAutoRelay_AgentSenderDoesNot(t *testing.T) {
+	d := autoRelayDecision(false, "dsh")
+	if d.relay {
+		t.Fatal("Agent 间通信必须由模型主动 send_mail —— 两边都自动回会无休止互相唤醒")
+	}
+	if !strings.Contains(d.reason, "dsh") {
+		t.Errorf("日志要说清是谁，got %q", d.reason)
+	}
+	if !strings.Contains(d.reason, "Agent") {
+		t.Errorf("理由要点明这是 Agent 来信，got %q", d.reason)
+	}
+}
+
+// 「本轮没有回信」有三种原因，日志里必须能分辨。
+func TestAutoRelay_NoRecipientHasDistinctReason(t *testing.T) {
+	d := autoRelayDecision(true, "")
+	if d.relay {
+		t.Fatal("不知道回给谁时不该发")
+	}
+	if !strings.Contains(d.reason, "不知道回给谁") {
+		t.Errorf("理由必须与「对方是 Agent」区分得开，got %q", d.reason)
+	}
+}
+
+func TestReplyInstruction_HumanPromisesAutoRelay(t *testing.T) {
+	s := replyInstruction(true, "")
+	if !strings.Contains(s, "回信不用你自己发") {
+		t.Errorf("人类来信要告诉模型插件会代劳，got %q", s)
+	}
+	// 承诺了就必须真的做
+	if !autoRelayDecision(true, "jianf").relay {
+		t.Error("提示词与决策不一致 —— 承诺了自动转发却不转")
+	}
+}
+
+func TestReplyInstruction_AgentSaysPluginWontReply(t *testing.T) {
+	s := replyInstruction(false, "")
+	if strings.Contains(s, "回信不用你自己发") {
+		t.Error("这句话在 Agent → Agent 时是假的 —— 说了它模型就会把话说完然后停手")
+	}
+	if !strings.Contains(s, "不会替你回信") {
+		t.Errorf("必须明说插件不代劳，got %q", s)
+	}
+	if !strings.Contains(s, "send_mail") {
+		t.Errorf("必须给出唯一可行的做法，got %q", s)
+	}
+}
+
+func TestReplyInstruction_AgentDiscouragesEmptyCourtesy(t *testing.T) {
+	s := replyInstruction(false, "")
+	if !strings.Contains(s, "收到") || !strings.Contains(s, "确认") {
+		t.Errorf("要点名那种没有信息量的回复，got %q", s)
+	}
+	if !strings.Contains(s, "互相客套") {
+		t.Errorf("要说清后果，否则模型不知道为什么被劝阻，got %q", s)
+	}
+}
+
+func TestReplyInstruction_CarriesReplyAddress(t *testing.T) {
+	with := replyInstruction(false, "dsh@/x.别名")
+	if !strings.Contains(with, "dsh@/x.别名") {
+		t.Error("要它自己发信却不给地址，它会拼一个 .new 出来 —— 那会静默开新会话")
+	}
+	without := replyInstruction(false, "")
+	if strings.Contains(without, "（回信地址：）") {
+		t.Error("没有地址时不该留一个空括号")
+	}
+}
+
+func TestInboundHeadline_ReplyIsNotNewWork(t *testing.T) {
+	h := inboundHeadline("m-1", false, false)
+	if !strings.Contains(h, "回复") {
+		t.Errorf("要说清这是回复，got %q", h)
+	}
+	if !strings.Contains(h, "不是新任务") {
+		t.Errorf("把回复当新任务处理正是互相客套的起点，got %q", h)
+	}
+}
+
+// in_reply_to 是最强信号：它同时出现时压过补投标记。
+func TestInboundHeadline_ReplyBeatsCatchup(t *testing.T) {
+	h := inboundHeadline("m-1", true, true)
+	if !strings.Contains(h, "回复") {
+		t.Errorf("in_reply_to 优先，got %q", h)
+	}
+}
+
+func TestInboundHeadline_MarksAgentSender(t *testing.T) {
+	if !strings.Contains(inboundHeadline("", false, false), "Agent") {
+		t.Error("Agent 来信要在标题里标出来")
+	}
+	if strings.Contains(inboundHeadline("", true, false), "Agent") {
+		t.Error("人类来信不该带这个括号 —— 那是噪音")
+	}
+}
+
+func TestInboundHeadline_CatchupExplained(t *testing.T) {
+	h := inboundHeadline("", true, true)
+	if !strings.Contains(h, "积压") {
+		t.Errorf("补投要说明，否则模型按「刚到的」语气回，got %q", h)
+	}
+}