MailUI4Agents/plugins/zcode-mail-bridge/lib/relay-policy.js

// 自动转发的**适用范围**，以及据此该给模型说什么话。
//
// 单独一个文件而不是放在入口里导出：**opencode 会把插件入口模块的每一个导出
// 都当成插件工厂**（`Object.values(mod)` 逐个检查是不是函数），多导出一个函数
// 就会让整个插件加载失败。因此入口只 `export default`，判断逻辑一律搁在这里。
//
// # 为什么 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。**
// 插件不再代它开口 —— 该说话的时候它会说，没什么要说的时候就该安静。
//
// 副作用是好的：模型必须自己决定「这值得回一封信吗」，而那正是它该做的判断。

/** 取三维地址的名字段：admin@root.alias -> admin */
export function addrName(addr) {
  return String(addr || "").split("@")[0].trim();
}

/**
 * 这一轮的结论该不该由插件自动转发出去。
 *
 * @param {object} ctx
 * @param {string}  [ctx.parentFrom] 父邮件的发件人（服务端 parent_from）；空=非回信或未升级
 * @param {string}  [ctx.selfName]   本方名字（收件方自己），用于方向判据
 * @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 {string}  [ctx.parentFrom] 父邮件的发件人（服务端 parent_from）；空=非回信或未升级
 * @param {string}  [ctx.selfName]   本方名字（收件方自己），用于方向判据
 * @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 {string}  [ctx.parentFrom] 父邮件的发件人（服务端 parent_from）；空=非回信或未升级
 * @param {string}  [ctx.selfName]   本方名字（收件方自己），用于方向判据
 * @param {boolean} ctx.fromHuman
 * @param {boolean} [ctx.catchup]  离线期间积压后补投的
 * @param {boolean} [ctx.reused]   投进一条已存在的会话（续谈）
 * @returns {string} 提示词第一行
 */
export function inboundHeadline(ctx) {
  const { inReplyTo, parentFrom, selfName, fromHuman, catchup, reused } = ctx || {};
  const who = fromHuman ? "" : "（对方是一个 Agent）";
  if (inReplyTo) {
    // 「回复到了」与「有人派活」是两种处境。说清楚它，模型才不会把
    // 一句确认当成新任务 —— 那正是互相客套的起点。
    //
    // ★ 还必须有**方向**判据（2026-09-30 修，in-reply-to-ignores-direction）：
    // 只有 inReplyTo 时只能判断「这是回信」，分不清回的是**谁**的信。
    // 单向续信链（8 封全是 opencode → pi）同样满足「有父邮件」，曾被逐封
    // 宣称「回的是你那封」，把纯单向链读成双向对话。服务端现在在载荷里
    // 带父邮件发件人（parent_from）；`parentFrom === selfName` 才是
    // 「我上一封信的回复到了」，否则是多方线索里的他人续谈 —— 当新输入。
    // 服务端未升级（无 parent_from）时退回旧行为，不比原来更差。
    const mine = parentFrom != null && parentFrom !== "" && selfName != null && parentFrom === selfName;
    if (mine) {
      return `你上一封信的**回复**到了${who}。这不是新任务。`;
    }
    if (parentFrom != null && parentFrom !== "") {
      return `这是多方线索里的**续谈**（回的那封是 ${parentFrom} 发的，不是对你上一封信的回复）${who}。`;
    }
    // 服务端未升级（无 parent_from）时退回旧行为：含糊地说「回复到了」
    // 也强于让模型把一封真回复当新任务再处理一遍 —— 那是互相客套的起点。
    return `你上一封信的**回复**到了${who}。这不是新任务。`;
  }
  if (catchup) {
    return `你收到一封新邮件${who}。说明：这是插件离线期间积压的邮件，现在补投给你。`;
  }
  if (reused) {
    return `本会话收到一封新邮件${who}。`;
  }
  return `你收到一封新邮件${who}。`;
}