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 包全绿
This commit is contained in:
2026-09-04 23:52:52 +08:00
parent 375578cf9b
commit 784192d8c4
22 changed files with 1315 additions and 92 deletions

View File

@ -0,0 +1,120 @@
// 自动转发的**适用范围**,以及据此该给模型说什么话。
//
// 单独一个文件而不是放在入口里导出:**opencode 会把插件入口模块的每一个导出
// 都当成插件工厂**`Object.values(mod)` 逐个检查是不是函数),多导出一个函数
// 就会让整个插件加载失败。因此入口只 `export default`,判断逻辑一律搁在这里。
//
// # 为什么 Agent → Agent 不自动转发
//
// 自动转发存在的理由是「人不该等模型记得调 send_mail」人发一封信出去
// 模型把活干完、话说完,插件替它把结论搬进邮件。收件方是人时这是纯收益。
//
// 收件方是**另一个 Agent** 时这个理由不成立,而且有害:对方的插件同样会自动
// 回一封,于是两个模型都以为「我只要把话说完就行」,实际上在持续互相唤醒。
// 生产实测过一条完整的客套链pi 转发给 dshdsh 回确认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。**
// 插件不再代它开口 —— 该说话的时候它会说,没什么要说的时候就该安静。
//
// 副作用是好的:模型必须自己决定「这值得回一封信吗」,而那正是它该做的判断。
/** 取三维地址的名字段admin@root.alias -> admin */
export function addrName(addr) {
return String(addr || "").split("@")[0].trim();
}
/**
* 这一轮的结论该不该由插件自动转发出去。
*
* @param {object} ctx
* @param {boolean} ctx.fromHuman 来信方是人类用户SSE 的 `from_human`
* @param {string} [ctx.replyTo] 自动转发本来要发给谁
* @returns {{relay: boolean, reason: string}}
* reason 供日志用 —— 「本轮没有回信」必须能在日志里查到原因,
* 否则它与「模型没说话」「转发失败」三种情形长得一样。
*/
export function autoRelayDecision(ctx) {
const { fromHuman, replyTo } = ctx || {};
if (!replyTo) {
return { relay: false, reason: "不知道回给谁" };
}
if (!fromHuman) {
return {
relay: false,
reason: `来信方 ${addrName(replyTo)} 是 Agent按约定不自动转发Agent 间通信须由模型主动 send_mail`,
};
}
return { relay: true, reason: "" };
}
/**
* 提示词里关于「回信怎么发」的那句话。
*
* 必须与 `autoRelayDecision` 一致 —— 这是同一件事的两个出口,分开写必然分叉。
* 而分叉的代价是模型被骗:它以为插件会替它回信,于是把话说完就停手,
* 而实际上那封信永远不会发出去,发件方一直等着。
*
* @param {object} ctx
* @param {boolean} ctx.fromHuman
* @param {string} [ctx.replyAddress] 服务端算好的回信地址
* @returns {string[]} 若干行,直接拼进提示词
*/
export function replyInstruction(ctx) {
const { fromHuman, replyAddress } = ctx || {};
if (fromHuman) {
return [
"**回信不用你自己发**:把这一轮做完、把结论说出来就行,",
"插件会在这一轮结束时把你最后那段话作为回信发回去(不消耗你的发信配额)。",
"只有在需要主动联系其他人、或要带附件时才调用 send_mail。",
];
}
return [
"**这封信来自另一个 Agent插件不会替你回信。**",
"需要回复时你必须自己调用 send_mail" +
(replyAddress ? `(回信地址:${replyAddress}` : "") + "",
"把话说完并不会让对方收到任何东西。",
"也请先判断这封信是否真的需要回复 —— 单纯的「收到」「确认」会让两个 Agent",
"无休止地互相客套,那对谁都没有价值。有实质结论或有事要问时才回。",
];
}
/**
* 描述「进来的这封是什么」。
*
* 在此之前提示词一律说「你收到一封新邮件」,于是模型分不清三种处境:
* 有人派了新活、我上封信的回复到了、离线期间积压的补投。
* 第二种被当成第一种时,模型会把一句「已收到」当成待办再处理一遍。
*
* @param {object} ctx
* @param {string} [ctx.inReplyTo] 非空 = 这是对本方某封信的回复SSE 的 `in_reply_to`
* @param {boolean} ctx.fromHuman
* @param {boolean} [ctx.catchup] 离线期间积压后补投的
* @param {boolean} [ctx.reused] 投进一条已存在的会话(续谈)
* @returns {string} 提示词第一行
*/
export function inboundHeadline(ctx) {
const { inReplyTo, fromHuman, catchup, reused } = ctx || {};
const who = fromHuman ? "" : "(对方是一个 Agent";
if (inReplyTo) {
// 「回复到了」与「有人派活」是两种处境。说清楚它,模型才不会把
// 一句确认当成新任务 —— 那正是互相客套的起点。
return `你上一封信的**回复**到了${who}。这不是新任务。`;
}
if (catchup) {
return `你收到一封新邮件${who}。说明:这是插件离线期间积压的邮件,现在补投给你。`;
}
if (reused) {
return `本会话收到一封新邮件${who}`;
}
return `你收到一封新邮件${who}`;
}

View File

@ -8,6 +8,8 @@
* 校验),这里的东西是 pi 专属的消息形状、stopReason 语义),不参与那个约束。
*/
import { replyInstruction, inboundHeadline } from '../lib/relay-policy.js';
/** 去掉已有的 Re: 前缀,避免 Re: Re: Re: 叠加。 */
export function stripRe(subject) {
return String(subject ?? '').replace(/^(\s*Re:\s*)+/i, '');
@ -127,33 +129,41 @@ export function buildMailPrompt({ agentName, data, kind, reused }) {
].join('\n');
}
const head = reused
? '本会话收到一封新邮件AgentMail 续谈)。'
: '你收到一封新邮件AgentMail。';
// 发件方是人还是 Agent以及这封是不是回信 —— 两个信号都来自服务端。
// 旧版一律说「你收到一封新邮件」+「回信不用你自己发」,于是 Agent 之间
// 两边都以为插件会代它开口,把对方的一句「已收到」当成待办再处理一遍。
//
// `from_human` 缺失时保守当作「不是人」:宁可让模型多调一次 send_mail
// 也不能对它承诺一个不会发生的自动回信 —— 后者让发件方白等。
const fromHuman = data?.from_human === true;
const lines = [
head,
inboundHeadline({
inReplyTo: data?.in_reply_to,
fromHuman,
catchup: data?.catchup,
reused,
}),
'',
`发件人:${data?.from_name || 'unknown'}`,
`主题:${data?.subject || '(无主题)'}`,
`邮件 ID${data?.mail_id || 'unknown'}`,
];
if (data?.in_reply_to) {
lines.push(`回的是你那封:${data.in_reply_to}`);
}
if (!reused) lines.push(`身份:你是 ${agentName}`);
// 服务端算好的回信地址(`new_mail` 的 reply_address。带上它是因为模型
// **确实会**自己发信 —— 尤其是要抄送第三方、或分多封交代不同的事时。
// 让它自己拼三维地址的话,`.new` 会被拼进去,于是回信静默开出一条新会话,
// 原来的线索里再无下文。
if (data?.reply_address) {
lines.push(`回信地址:${data.reply_address}(如需自己发信,用这个地址)`);
}
if (data?.catchup) {
// 补投的邮件要说明,否则模型会以为这是刚到的、按「立即响应」的语气回
lines.push('说明:这是插件离线期间积压的邮件,现在补投给你。');
lines.push(`回信地址:${data.reply_address}`);
}
lines.push(
'',
'请先调用 read_inbox 读取完整正文(附带附件清单,如有附件可用 download_attachment 取回),',
'然后处理其中的请求。',
'回信不用你自己发:把这一轮做完、把结论说出来就行,插件会把你最后那段话作为回信发出去。',
...replyInstruction({ fromHuman, replyAddress: data?.reply_address }),
);
return lines.join('\n');
}

View File

@ -51,6 +51,7 @@ import { planNamingSync, planWriteBack } from './naming.mjs';
import { resolveWorkspaceCwd, ensureCwd } from '../lib/workspace.js';
import { modelAttemptOrder, renderFailureReport } from '../lib/model-scope.js';
import { explicitSends, shouldSkipAutoRelay } from '../lib/relay-dedup.js';
import { autoRelayDecision } from '../lib/relay-policy.js';
import { adoptedSessionID, adoptMissingMessage } from '../lib/adopt.js';
import { isApproval, isAlwaysDecision } from '../lib/permission-grants.js';
@ -324,10 +325,23 @@ async function relaySummary(session, sessionManager, adopted) {
.catch((e) => log(`命名同步失败: ${describeError(e)}`));
}
// **只给人类来信自动转发**(详见 lib/relay-policy.js
//
// 对方是 Agent 时它那边的插件也会自动回一封,于是两个模型都以为
// 「我只要把话说完就行」,实际在持续互相唤醒 —— 生产实测 pi 与 dsh
// 客套 6 轮直到撞上 hop 上限。这一步在取文本之前判:早退比白做一轮清楚。
const policy = autoRelayDecision({
fromHuman: job.data?.from_human === true,
replyTo: mailContext.replyTo,
});
if (!policy.relay) {
log(`本轮不自动转发:${policy.reason}`);
return;
}
// 只取 type==='text' 的块B-5.1 / N-6thinking 是思考过程,不是结论。
const text = lastAssistantText(session.messages);
if (!text) return; // 空文本不发空邮件B-5.4
if (!mailContext.replyTo) return; // 不知道回给谁
// 幂等键用 pi 会话 id + 会话树叶子 id两者都落盘重放也是同一个键。
const relayKey = relayKeyFor(piSessionId, sessionManager.getLeafId?.());

View File

@ -0,0 +1,131 @@
/**
* 自动转发适用范围的判定lib/relay-policy.js
*
* 三个函数是同一件事的三个出口,必须一起看:
* - autoRelayDecision 插件该不该替模型把结论发出去
* - replyInstruction 提示词里怎么跟模型说这件事
* - inboundHeadline 进来的这封是新活、是回复、还是补投
*
* 分开写必然分叉,而分叉的代价是模型被骗:以为插件会替它回信,于是把话说完
* 就停手,那封信却永远不会发出去。所以这里逐条钉住它们的一致性。
*/
import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
addrName,
autoRelayDecision,
replyInstruction,
inboundHeadline,
} from '../lib/relay-policy.js';
// ─── addrName ───
test('addrName 取三维地址的名字段', () => {
assert.equal(addrName('pi@/home/program/agentmail.某别名'), 'pi');
assert.equal(addrName('jianf'), 'jianf');
assert.equal(addrName(' dsh@/x '), 'dsh');
assert.equal(addrName(''), '');
assert.equal(addrName(undefined), '');
});
// ─── autoRelayDecision ───
test('人类来信 → 自动转发', () => {
const d = autoRelayDecision({ fromHuman: true, replyTo: 'jianf' });
assert.equal(d.relay, true);
});
test('Agent 来信 → 不自动转发', () => {
const d = autoRelayDecision({ fromHuman: false, replyTo: 'dsh' });
assert.equal(d.relay, false,
'Agent 间通信必须由模型主动 send_mail —— 两边都自动回会无休止互相唤醒');
assert.match(d.reason, /dsh/, '日志要说清是谁');
assert.match(d.reason, /Agent/);
});
test('不知道回给谁 → 不转发,且理由与「对方是 Agent」区分得开', () => {
const d = autoRelayDecision({ fromHuman: true, replyTo: '' });
assert.equal(d.relay, false);
assert.match(d.reason, /不知道回给谁/,
'「本轮没有回信」有三种原因,日志里必须能分辨');
});
test('replyTo 带三维地址时也能认出 Agent 名', () => {
const d = autoRelayDecision({ fromHuman: false, replyTo: 'opencode@/home/x.别名' });
assert.equal(d.relay, false);
assert.match(d.reason, /opencode/);
});
test('缺省参数不抛错(畸形事件不该弄死投递)', () => {
assert.equal(autoRelayDecision().relay, false);
assert.equal(autoRelayDecision({}).relay, false);
});
// ─── replyInstruction 与 autoRelayDecision 的一致性 ───
test('人类来信的提示词承诺「插件会替你发」,且这与决策一致', () => {
const lines = replyInstruction({ fromHuman: true });
const text = lines.join('\n');
assert.match(text, /回信不用你自己发/);
assert.equal(autoRelayDecision({ fromHuman: true, replyTo: 'jianf' }).relay, true,
'承诺了就必须真的做');
});
test('Agent 来信的提示词必须明说「插件不会替你回信」', () => {
const text = replyInstruction({ fromHuman: false }).join('\n');
assert.match(text, /不会替你回信/);
assert.match(text, /send_mail/, '必须给出唯一可行的做法');
assert.doesNotMatch(text, /回信不用你自己发/,
'这句话在 Agent → Agent 时是假的 —— 说了它模型就会把话说完然后停手');
});
test('Agent 来信的提示词要劝阻纯客套', () => {
const text = replyInstruction({ fromHuman: false }).join('\n');
assert.match(text, /收到|确认/, '要点名那种没有信息量的回复');
assert.match(text, /互相客套|无休止/, '要说清后果,否则模型不知道为什么被劝阻');
});
test('Agent 来信时把回信地址带进提示词(有就带)', () => {
const withAddr = replyInstruction({ fromHuman: false, replyAddress: 'dsh@/x.别名' }).join('\n');
assert.match(withAddr, /dsh@\/x\.别名/,
'要它自己发信却不给地址,它会拼一个 .new 出来 —— 那会静默开新会话');
const without = replyInstruction({ fromHuman: false }).join('\n');
assert.doesNotMatch(without, /(回信地址:)/, '没有地址时不该留一个空括号');
});
// ─── inboundHeadline ───
test('回复到了 → 明说「这不是新任务」', () => {
const h = inboundHeadline({ inReplyTo: 'm-1', fromHuman: false });
assert.match(h, /回复/);
assert.match(h, /不是新任务/,
'把回复当新任务处理正是互相客套的起点');
});
test('回复的标题优先于续谈/补投标记', () => {
const h = inboundHeadline({ inReplyTo: 'm-1', fromHuman: true, reused: true, catchup: true });
assert.match(h, /回复/, 'in_reply_to 是最强信号');
});
test('Agent 来信在标题里就标出来', () => {
assert.match(inboundHeadline({ fromHuman: false }), /Agent/);
assert.doesNotMatch(inboundHeadline({ fromHuman: true }), /Agent/,
'人类来信不该带这个括号 —— 那是噪音');
});
test('补投要说明,否则模型按「刚到的」语气回', () => {
const h = inboundHeadline({ fromHuman: true, catchup: true });
assert.match(h, /积压|补投/);
});
test('续谈与新会话的措辞不同', () => {
assert.match(inboundHeadline({ fromHuman: true, reused: true }), /本会话/);
assert.match(inboundHeadline({ fromHuman: true, reused: false }), /你收到/);
});
test('缺省参数不抛错', () => {
assert.equal(typeof inboundHeadline(), 'string');
assert.equal(typeof inboundHeadline({}), 'string');
});

View File

@ -177,15 +177,51 @@ const mailData = {
from_name: 'admin',
subject: '排查连接泄漏',
to_workspace: '/home/program/agentmail',
// 人类来信。**这一项不能省**:缺失时保守当作 Agent 来信,而两者的
// 提示词完全不同(人类才有自动转发)。
from_human: true,
};
test('不变量:提示词写明回信由桥自动发', () => {
test('不变量:人类来信的提示词写明回信由桥自动发', () => {
// 不说的话模型会自己调 send_mail而桥在轮次结束时也会转发一次 ——
// 同一件事两封邮件(生产里真实发生过)。
const p = buildMailPrompt({ agentName: 'pi', data: mailData, kind: 'mail', reused: false });
assert.match(p, /回信不用你自己发/);
});
test('不变量Agent 来信的提示词必须改口(插件不代它回信)', () => {
// Agent 之间两边都自动回信 = 无休止互相唤醒(实测 pi 与 dsh 客套 6 轮)。
const p = buildMailPrompt({
agentName: 'pi',
data: { ...mailData, from_name: 'dsh', from_human: false },
kind: 'mail',
reused: false,
});
assert.doesNotMatch(p, /回信不用你自己发/, '那句话在这里是假的');
assert.match(p, /不会替你回信/);
assert.match(p, /send_mail/);
});
test('不变量from_human 缺失时按 Agent 处理(不能承诺做不到的事)', () => {
const { from_human, ...noFlag } = mailData;
const p = buildMailPrompt({ agentName: 'pi', data: noFlag, kind: 'mail', reused: false });
assert.doesNotMatch(p, /回信不用你自己发/,
'宁可让它多调一次 send_mail也不能让发件方白等一个不会发生的自动回信');
});
test('不变量:回信到达时明说「不是新任务」', () => {
// 把回复当新任务处理正是互相客套的起点。
const p = buildMailPrompt({
agentName: 'pi',
data: { ...mailData, from_human: false, in_reply_to: 'm-0' },
kind: 'mail',
reused: true,
});
assert.match(p, /回复/);
assert.match(p, /不是新任务/);
assert.match(p, /m-0/, '要说出回的是哪封');
});
test('不变量:提示词带 mail_id 与 read_inbox 指引', () => {
// 事件里只有主题,正文和附件清单都在收件箱里;不给 mail_id 模型无法定位这一封
const p = buildMailPrompt({ agentName: 'pi', data: mailData, kind: 'mail', reused: false });
@ -198,7 +234,7 @@ test('首封带身份,续谈不重复带', () => {
const again = buildMailPrompt({ agentName: 'pi', data: mailData, kind: 'mail', reused: true });
assert.match(first, /你是 pi/);
assert.doesNotMatch(again, /你是 pi/);
assert.match(again, /续谈/);
assert.match(again, /本会话/, '续谈用「本会话」而不是「你收到」');
});
test('补投的邮件在提示词里说明来源', () => {