fix: relay 死循环防护 + DSH 工作区注册修复 + homeagent 工具集补齐 + 三插件 connect_to_server

## relay 死循环防护（两道防线） ### 主防线：免配额只给发往人类的 relay（handler/mail.go）原设计：relay 走免配额通道（harness 搬运不该算模型自主发信）。问题：收件方是另一个同样会自动转发的 Agent 时，整个回路里没有任何一处在计数——生产上跑出过 41 封（会话 f3d824ce），间隔从 15 分钟缩到 5 秒，且用了 37 封才烧掉 4/20 预算。改为：repo.IsHumanUser(to.Name) 判定。Agent→Agent 的 relay 照样扣预算。顺带修次序问题：原来是「先占幂等键再扣预算」，预算耗尽时幂等键已被占用，加了额度也无法重发。现在预算失败会 ReleaseRelay 还回去。 ### 兜底：hop_limit 列接通（repo/relayhops.go） schema 里早有 hop_limit INT DEFAULT 5，从未有代码读它。 CountTrailingRelayHops 从最新邮件往前扫，遇到第一封非 relay 邮件即停（中间有一封自主发信或人类插话就归零）。 5 测试：空会话 / 只数 relay / 自主发信打断归零 / 达到上限 / 按会话独立 ## DSH 工作区注册修复问题：上一轮加的 workspaceRegistry.create(cwd) 用了兜底值 cwd（来自 resolveWorkspaceCwd，可能是 ~/.dsh/mail-sessions/mail-<uuid>），而不是会话 header 里的真实 cwd。两者不一致时 attachSession 拒绝，且 create 已先执行，每封邮件都往注册表里塞一条空的垃圾 workspace。修复：读 handle.agent.session.header.cwd —— create 路径下是 meta.cwd， resume 路径下是持久化 header 里那个。 ## homeagent 插件：11 工具齐平 opencode tools.go 新增：read_mail / forward_mail / suggest_address / list_contacts / session_participants / read_thread / connect_to_server + handleConnectToServer（注册到 Gateway 前先用候选坐标试注册，成功才写回 p.gwURL/p.key，失败不破坏原配置）关键修：Plugin.name（插件名，homed 注册用）与 Plugin.agentName （AgentMail 身份，Gateway 密钥绑定用）是两个命名空间。它们混淆会导致 403：「该密钥已绑定到 Agent 'homeagent'，不能用于注册 'homeagent-mail-bridge'」。现已分开，并在 systemd drop-in 里显式设 AGENTMAIL_AGENT_NAME=homeagent。 ## 三插件补齐 connect_to_server 之前只有 opencode 有。后果：Gateway 换地址或密钥需要重新登记时， opencode 里的模型能自己修好，其他平台只能干等环境变量被人改。 DSH 版：从 GatewayClient 内部调 register()，成功后写回 client.baseURL 与 client.agentKey 当场生效。 pi 版：新导出 KEY_FILE / saveLocalKey（从 gateway.mjs），connect 工具直接用。 # 测试 relayhops_test.go 5 例 opencode 172 / dsh 188 / pi 214 全绿 check-shared-libs.sh 三方同源（rename-proposal 已纳入校验）
2026-09-03 15:01:52 +08:00
parent fc33087982
commit f321380fa3
19 changed files with 1909 additions and 75 deletions
--- a/plugins/opencode-mail-bridge/index.js
+++ b/plugins/opencode-mail-bridge/index.js
@ -33,6 +33,7 @@ import {
  noteExplicitSend,
  shouldSkipAutoRelay,
 } from "./lib/relay-dedup.js";
+import { appendRenameProposal, renameProposalNote } from "./lib/rename-proposal.js";

 const GATEWAY_URL = process.env.AGENTMAIL_GATEWAY_URL || "http://127.0.0.1:8180";
 const AGENT_NAME = process.env.AGENTMAIL_AGENT_NAME || "opencode";
@ -170,14 +171,11 @@ const sendMailTool = {
  // 让 session.idle 的自动转发让位，避免同一件事发两封。
  async execute(args, context) {
    // 改名建议以 HTML 注释形式附在正文末尾，由网关解析后剥离。
-    // 选注释而不是自造标记：react-markdown 不解析 raw HTML，
-    // 万一网关没剥掉，它在页面上也只是一行不显眼的转义文本而非破版内容。
-    let body = args.body;
-    if (args.propose_alias) {
-      const esc = (v) => String(v).replace(/"/g, "");  // 双引号是标记的定界符
-      const reason = args.propose_reason ? ` reason="${esc(args.propose_reason)}"` : "";
-      body += `\n\n<!-- agentmail:rename-session alias="${esc(args.propose_alias)}"${reason} -->`;
-    }
+    // 标记格式是服务端正则的镜像，因此拼接收在 lib/rename-proposal.js
+    // （三平台共用）—— 各写一遍的话少个空格就静默失效：邮件照常发出，
+    // 提议凭空消失，而模型以为自己提过了。
+    const { body, proposed } = appendRenameProposal(
+      args.body, args.propose_alias, args.propose_reason);

    const result = await apiPost("/mail/send", {
      to: args.to,
@ -205,11 +203,11 @@ const sendMailTool = {
            ? "预算即将用尽，请尽快给出结论；自动转发的总结不占预算。"
            : "")
        : "";
-    // 回传规范化后的别名：Agent 提的名字可能含非法字符被改写过
-    const proposed = result.rename_proposed
-      ? `\n已向用户提议把会话改名为 ${result.rename_proposed}，等待其确认。`
-      : "";
-    return `已发送。Mail ID: ${result.mail_id}，Session: ${result.session_id}${alias}${budget}${proposed}`;
+    // 别名取服务端回的 rename_proposed：它跑过 normalizeAlias，
+    // 回显本地值会让模型记住一个不存在的名字
+    const note = renameProposalNote(result.rename_proposed, args.propose_alias, proposed);
+    return `已发送。Mail ID: ${result.mail_id}，Session: ${result.session_id}${alias}${budget}` +
+      (note ? `\n${note}` : "");
  },
 };

--- a/plugins/opencode-mail-bridge/lib/rename-proposal.js
+++ b/plugins/opencode-mail-bridge/lib/rename-proposal.js
@ -0,0 +1,130 @@
+/**
+ * 会话改名提议 —— 所有平台插件共用。
+ *
+ * # 这是什么
+ *
+ * 模型干完活后可能觉得当前别名不贴切：会话建立时叫 `witty-planet`（平台随机 slug）
+ * 或 `排查登录问题`（人写的邮件主题），摸清问题后它知道这其实是
+ * `fix-session-cookie-leak`。改名提议就是让它把这个判断说出来。
+ *
+ * # 为什么是「提议」而不是直接改
+ *
+ * 别名是**人**的寻址入口 —— `name@path.<别名>` 里那一段。Agent 干到一半自己改掉，
+ * 人上一秒记住的地址下一秒就 404（`session` 位三态语义要求指向不存在的会话直接报
+ * 「无法送达」，不会静默新建）。所以提议入库、由人在界面上点「接受」才真正生效。
+ *
+ * 这与平台命名自动同步（`POST /sessions/{id}/sync`）互补，两者不冲突：
+ *
+ * | | 谁发起 | 何时 | 是否打扰人 |
+ * |---|---|---|---|
+ * | 自动同步 | 平台的命名机制 | 每轮结束 | 不，后台静默生效 |
+ * | 改名提议 | 模型的主动判断 | 它认为有必要时 | 是，界面上出提示条 |
+ *
+ * # 为什么载体是 HTML 注释
+ *
+ * `/mail/send` 没有 `propose_alias` 字段 —— 提议**搭在正文里**发出去，
+ * 服务端用正则摘出来再把标记从入库正文中剥掉。选 HTML 注释的三个理由：
+ *
+ *   - react-markdown 默认不解析 raw HTML，万一服务端没剥掉，它在页面上也只是
+ *     一行不显眼的转义文本，不会破版
+ *   - 纯文本邮件客户端里是一行不碍事的注释，不像自造标记那样显眼
+ *   - 不与 Markdown 语法冲突，格式化工具不会改写它
+ *
+ * # 为什么必须共用
+ *
+ * 标记格式是**服务端正则的镜像**（`gateway/internal/handler/rename_proposal.go`）。
+ * 各平台各写一遍拼接，某一处少个空格或把双引号写成单引号，服务端匹配不上 ——
+ * 而失败是静默的：邮件照常发出，提议凭空消失，模型以为自己提过了。
+ */
+
+/**
+ * 服务端能识别的别名字符集。
+ *
+ * 与 `validateSessionAlias` 一致：`. 空白 / @` 会与三维地址解析冲突，
+ * `new` 是寻址保留字。这里**不做规范化**（不把非法字符替换成 `-`）——
+ * 规范化是服务端 `normalizeAlias` 的职责，插件擅自改写会让模型看到的
+ * 「我提议的名字」与实际入库的不一致。
+ *
+ * @param {string} alias
+ * @returns {boolean}
+ */
+export function isProposableAlias(alias) {
+  const a = String(alias ?? '').trim();
+  if (!a) return false;
+  if (a === 'new') return false;
+  // 双引号是标记本身的定界符，含它会截断标记
+  if (/[.\s/@"]/.test(a)) return false;
+  // 服务端 VARCHAR(128)，按字节算
+  if (Buffer.byteLength(a, 'utf8') > 128) return false;
+  return true;
+}
+
+/**
+ * 把改名提议标记追加到正文末尾。
+ *
+ * 格式必须与服务端正则逐字符对应：
+ * `<!-- agentmail:rename-session alias="x" reason="y" -->`
+ * reason 可选，为空时**整个属性都不写**（写成 `reason=""` 服务端会存一个空理由，
+ * 界面上的提示条就少了那句解释）。
+ *
+ * 别名不合法时**原样返回正文**，不追加标记：与其发一个服务端匹配得上却
+ * 被 `validateSessionAlias` 拒掉的标记，不如当它没提 —— 调用方据此告诉模型。
+ *
+ * @param {string} body 原始正文
+ * @param {string} [alias] 提议的别名
+ * @param {string} [reason] 提议理由，一句话
+ * @returns {{body: string, proposed: boolean}} proposed=false 表示别名不合法，未追加
+ */
+export function appendRenameProposal(body, alias, reason) {
+  const text = String(body ?? '');
+  if (!isProposableAlias(alias)) return { body: text, proposed: false };
+
+  const a = String(alias).trim();
+  // 理由里的双引号会截断标记，去掉而不是转义：HTML 注释里没有转义机制
+  const r = String(reason ?? '').replace(/"/g, '').trim();
+  const reasonAttr = r ? ` reason="${r}"` : '';
+
+  return {
+    body: `${text}\n\n<!-- agentmail:rename-session alias="${a}"${reasonAttr} -->`,
+    proposed: true,
+  };
+}
+
+/**
+ * 提议提交后回给模型的那句话。
+ *
+ * **别名取服务端回的 `rename_proposed`，不是本地提议的那个。** 服务端会跑
+ * `normalizeAlias` —— 非法字符换成 `-`、`new` 变 `session-new`、超长按 UTF-8
+ * 边界截断。回显本地值会让模型记住一个不存在的名字，之后拿它寻址就 404。
+ *
+ * 必须说明「等人确认」。不说的话模型会以为改名已经生效，接着在后续邮件里
+ * 用新别名当地址发信 —— 而那个别名此刻还不存在，投递会失败。
+ *
+ * @param {string} [serverAlias] 服务端 `/mail/send` 响应里的 `rename_proposed`
+ * @param {string} [requestedAlias] 本地提议的别名，仅用于「未提交」时的说明
+ * @param {boolean} [proposed] appendRenameProposal 的返回值
+ * @returns {string} 空串表示没有需要追加的说明
+ */
+export function renameProposalNote(serverAlias, requestedAlias, proposed) {
+  const server = String(serverAlias ?? '').trim();
+  const wanted = String(requestedAlias ?? '').trim();
+
+  // 服务端确认收到了：用它给的最终值
+  if (server) {
+    const changed = wanted && wanted !== server
+      ? `（你提的 "${wanted}" 被规范化成了这个）`
+      : '';
+    return `已附上改名提议 "${server}"${changed}，等用户在界面上确认后生效 —— ` +
+      `在那之前继续用原别名寻址。`;
+  }
+
+  if (!wanted) return '';
+
+  // 本地就判定不合法，标记没发出去
+  if (!proposed) {
+    return `（改名提议 "${wanted}" 未提交：别名不可为 new，不可含 . 空白 / @ 或双引号。）`;
+  }
+
+  // 标记发出去了但服务端没回 rename_proposed：它那侧的校验也拒了
+  return `（改名提议 "${wanted}" 未被服务端接受，会话别名不变。）`;
+}
--- a/plugins/opencode-mail-bridge/test/rename-proposal.test.mjs
+++ b/plugins/opencode-mail-bridge/test/rename-proposal.test.mjs
@ -0,0 +1,136 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  isProposableAlias,
+  appendRenameProposal,
+  renameProposalNote,
+} from '../lib/rename-proposal.js';
+
+// 这一组测试钉住的是「插件拼的标记与服务端正则逐字符对应」。
+// 服务端那条正则在 gateway/internal/handler/rename_proposal.go：
+//   <!--\s*agentmail:rename-session\s+alias="([^"]*)"(?:\s+reason="([^"]*)")?\s*-->
+// 拼错不会报错 —— 邮件照常发出，提议凭空消失。
+
+/** 服务端正则的等价实现，用来验证我们拼出来的标记真的能被摘出来。 */
+const SERVER_RE =
+  /<!--\s*agentmail:rename-session\s+alias="([^"]*)"(?:\s+reason="([^"]*)")?\s*-->/s;
+
+test('isProposableAlias: 合法别名', () => {
+  assert.equal(isProposableAlias('fix-login-leak'), true);
+  assert.equal(isProposableAlias('修复登录态泄漏'), true, '中文别名合法');
+  assert.equal(isProposableAlias('v2_migration'), true);
+});
+
+test('isProposableAlias: new 是寻址保留字', () => {
+  // `.new` 是「强制新建会话」的动作，别名叫 new 会让地址无从解释
+  assert.equal(isProposableAlias('new'), false);
+});
+
+test('isProposableAlias: 拒绝与三维地址冲突的字符', () => {
+  // 这四个字符都会让 name@path.session 的切分产生歧义
+  assert.equal(isProposableAlias('a.b'), false, '. 是 session 位分隔符');
+  assert.equal(isProposableAlias('a/b'), false, '/ 出现在 path 位');
+  assert.equal(isProposableAlias('a@b'), false, '@ 是 name/path 分隔符');
+  assert.equal(isProposableAlias('a b'), false, '空白');
+  assert.equal(isProposableAlias('a\tb'), false, '制表符也算空白');
+});
+
+test('isProposableAlias: 拒绝双引号', () => {
+  // 双引号是标记自身的定界符，含它会把标记截断成非法形式
+  assert.equal(isProposableAlias('say"hi'), false);
+});
+
+test('isProposableAlias: 空与空白视为没提', () => {
+  assert.equal(isProposableAlias(''), false);
+  assert.equal(isProposableAlias('   '), false);
+  assert.equal(isProposableAlias(undefined), false);
+  assert.equal(isProposableAlias(null), false);
+});
+
+test('isProposableAlias: 超过 128 字节按字节算', () => {
+  // 服务端是 VARCHAR(128)。中文一个字 3 字节，43 字 = 129 字节
+  assert.equal(isProposableAlias('a'.repeat(128)), true);
+  assert.equal(isProposableAlias('a'.repeat(129)), false);
+  assert.equal(isProposableAlias('汉'.repeat(42)), true, '126 字节');
+  assert.equal(isProposableAlias('汉'.repeat(43)), false, '129 字节');
+});
+
+test('标记能被服务端正则摘出来', () => {
+  const { body, proposed } = appendRenameProposal('已定位到问题。', 'fix-login-leak', '登录态泄漏');
+  assert.equal(proposed, true);
+  const m = SERVER_RE.exec(body);
+  assert.ok(m, '服务端正则必须匹配得上');
+  assert.equal(m[1], 'fix-login-leak');
+  assert.equal(m[2], '登录态泄漏');
+});
+
+test('没有理由时整个 reason 属性都不写', () => {
+  // 写成 reason="" 会让服务端存一个空理由，界面提示条就少了那句解释
+  const { body } = appendRenameProposal('正文', 'fix-leak');
+  assert.doesNotMatch(body, /reason=/);
+  const m = SERVER_RE.exec(body);
+  assert.equal(m[1], 'fix-leak');
+  assert.equal(m[2], undefined);
+});
+
+test('理由里的双引号被去掉而不是转义', () => {
+  // HTML 注释里没有转义机制，留着会截断标记
+  const { body } = appendRenameProposal('正文', 'fix-leak', '他说"这是泄漏"');
+  const m = SERVER_RE.exec(body);
+  assert.ok(m);
+  assert.equal(m[2], '他说这是泄漏');
+});
+
+test('原正文完整保留在标记之前', () => {
+  const original = '第一行\n\n第二行';
+  const { body } = appendRenameProposal(original, 'fix-leak');
+  assert.ok(body.startsWith(original), '正文不得被改写');
+});
+
+test('别名不合法时原样返回，不追加标记', () => {
+  const { body, proposed } = appendRenameProposal('正文', 'a.b');
+  assert.equal(proposed, false);
+  assert.equal(body, '正文');
+  assert.doesNotMatch(body, /agentmail:rename-session/);
+});
+
+test('不给别名时正文完全不变', () => {
+  const { body, proposed } = appendRenameProposal('正文', '');
+  assert.equal(proposed, false);
+  assert.equal(body, '正文');
+});
+
+test('renameProposalNote: 用服务端回的别名，不是本地提议的', () => {
+  // 服务端跑 normalizeAlias：非法字符换 -、new 变 session-new、超长截断。
+  // 回显本地值会让模型记住一个不存在的名字，之后拿它寻址就 404。
+  const note = renameProposalNote('fix-login-leak', 'fix.login.leak', true);
+  assert.match(note, /fix-login-leak/);
+  assert.match(note, /规范化/, '要告诉模型名字被改写过');
+  assert.match(note, /确认/);
+  assert.match(note, /原别名/, '要明确说在那之前用哪个');
+});
+
+test('renameProposalNote: 服务端别名与提议一致时不提规范化', () => {
+  const note = renameProposalNote('fix-leak', 'fix-leak', true);
+  assert.match(note, /fix-leak/);
+  assert.doesNotMatch(note, /规范化/);
+});
+
+test('renameProposalNote: 本地判非法时说清为什么', () => {
+  const note = renameProposalNote('', 'a.b', false);
+  assert.match(note, /未提交/);
+  assert.match(note, /a\.b/);
+});
+
+test('renameProposalNote: 标记发出但服务端没接受', () => {
+  // 本地校验比服务端宽的情况（例如服务端加了新约束）——
+  // 不能沉默，否则模型以为提议成功了
+  const note = renameProposalNote('', 'somealias', true);
+  assert.match(note, /未被服务端接受/);
+  assert.match(note, /somealias/);
+});
+
+test('renameProposalNote: 没提议时不产生噪音', () => {
+  assert.equal(renameProposalNote('', '', false), '');
+  assert.equal(renameProposalNote(undefined, undefined, false), '');
+});