feat: 跨主机 Agent 验证 + 离线邮件补投 + 400 指向具体字段

7.8「跨主机 Agent 发现」原计划（Gateway + Registry 拆分、etcd/Consul 注册）
取消，改为验证现有协议已经够用。验证过程暴露两个真实缺陷，一并修掉。

## 为什么不做注册中心

它要解决「Gateway 怎么找到 Agent」，而这个问题在本架构里不存在：
连接方向是单向的 —— Agent 主动连 Gateway，Gateway 从不外呼。
远端 Agent 只需要一个公网 URL 加一把密钥，被叫方自己会打进来。
注册中心要解决的「被叫方在哪」根本没出现过。

同一个理由此前已经决定了平台会话同步走插件上报而不是 Gateway 拉取。

## 验证方式：一个纯标准库脚本

`deploy/remote-agent-demo.py` 在另一台主机（192.168.2.106）上跑，
不装 AgentMail 的任何代码。注册 / 心跳（带模型目录）/ SSE 长连 /
收件箱 / 标记已读 / 发信全通，Gateway 侧 status=online 且 last_seen 随心跳推进。
完整一轮往返跑通：admin 发给 remotebot@/tmp/remotebot-ws，脚本回信入库。

「协议层面已支持」的含义就是这个：跨主机不需要新组件，只需要三个环境变量。

## 缺陷一：SSE 只推连上之后的事件，没人补拉积压

写那个脚本时第一版只挂了 SSE，启动前发的邮件永远不会被处理。
查了才发现**两个正式插件也有这个洞** —— 原以为它们做了补拉，实际没有。
后果比明确的失败更难排查：邮件躺在收件箱里，而发件人以为 Agent 收到了。

新增共用模块 `lib/catchup.js`，两插件在首个成功心跳后补投一次。五条约束
都对应一种具体的坏行为：

- 只在**首个**心跳后补 —— 每轮都补会把「模型正在处理中、尚未标已读」的
  邮件重复投递
- 串行、一次最多 5 封 —— 每封都要起一轮模型，并发放出去等于对上游打 N 个
  并发请求，且最后几封要等前面全部跑完
- 与 SSE 共用 deliveredMails 去重 —— 心跳与 SSE 建连之间有个窗口，
  那期间到的邮件两条路都会到
- 按时间**正序**投（收件箱倒序返回）—— 倒着塞进去同一会话的上下文是乱的
- permission 类不补投 —— 原来的工具调用早随进程没了，没有可恢复的上下文

端到端两平台各验一次：停插件 → 发信 → 启插件 → 日志「补投 1 封离线期间的
邮件」→ 回信入库；随后在线再发一封确认只回一次。

## 缺陷二：400 只说 "Invalid JSON"，不说是哪个字段

脚本把 `workspaces` 传成字符串数组（它要 `[{name, path}]`），
得到的只是一句固定文案，只能靠翻服务端结构体才能发现。
两个官方插件都传 `workspaces: []`，所以这个洞一直没暴露；
第三方客户端没有「翻服务端源码」这个条件。

新增 `handler.DecodeBody`，22 处 `Decode` + 固定文案的调用点全部换过去：

    {"error": "字段 \"workspaces\" 类型不对：期望 object，收到 string"}
    {"error": "JSON 语法错误（第 8 字节处）"}
    {"error": "请求体为空"}

刻意不回显 encoding/json 的原文 —— 它带 Go 类型名（models.Workspace），
那是本侧的实现细节，不该出现在公开 API 的响应里。期望类型用 JSON 的说法。
截断的 JSON 走 io.ErrUnexpectedEOF 而不是 json.SyntaxError，单独一条分支，
否则会落到笼统的兜底文案里（写测试时才发现）。

## 验证

- Go：13 个新测试（decode_test.go 含「不得泄漏 Go 类型名」断言）
- 插件：两侧各 10 个补投测试，共 200 个
- 共用模块同源校验通过（catchup 已纳入 check-shared-libs.sh）
- 生产已部署

plugins/dsh-mail-bridge/src/index.ts

@@ -34,6 +34,7 @@ import {
   renderFailureReport,
 } from '../lib/model-scope.js';
 import { resolveWorkspaceCwd, ensureCwd, mailSessionFallback } from '../lib/workspace.js';
+import { selectCatchup } from '../lib/catchup.js';
 import {
   renderInbox,
   idsToMarkRead,
@@ -267,6 +268,40 @@ export function apply(ctx: any, config: PluginConfig): void {
     }
   }
 
+  // 已经投过的 mail_id。心跳与 SSE 建连之间有个窗口：那期间到的邮件
+  // 既在 pending_mails 里、也会被 SSE 推一次 —— 不去重就会投两遍。
+  const deliveredMails = new Set<string>();
+  let caughtUp = false;
+
+  /**
+   * 补投离线期间积压的未读邮件。
+   *
+   * SSE 只推连上之后的事件，插件重启前发来的邮件不会再推一次。
+   * 不补的话那封邮件永远躺在收件箱里，而发件人以为 Agent 收到了。
+   */
+  async function catchUp(pending: unknown): Promise<void> {
+    if (!pending) return;
+    try {
+      const box = await client.get('/mail/inbox?status=unread&limit=20');
+      const tasks = selectCatchup(box?.mails ?? box, deliveredMails);
+      if (tasks.length === 0) return;
+      console.error(`[dsh-mail-bridge] 补投 ${tasks.length} 封离线期间的邮件（共 ${pending} 封未读）`);
+      // 串行：每封都要起一轮模型，并发放出去等于对上游打 N 个并发请求
+      for (const ev of tasks) {
+        // 逐封再查一次：拉收件箱和逐封投递之间 SSE 可能已经投过其中某封
+        if (deliveredMails.has(ev.mail_id)) continue;
+        deliveredMails.add(ev.mail_id);
+        try {
+          await deliverMail(ev, 'mail');
+        } catch (e: any) {
+          ctx.logger.error(`[dsh-mail-bridge] 补投 ${ev.mail_id} 失败: ${e?.message || e}`);
+        }
+      }
+    } catch (e: any) {
+      ctx.logger.error(`[dsh-mail-bridge] 补投失败: ${e?.message || e}`);
+    }
+  }
+
   async function beat(): Promise<void> {
     const body: Record<string, unknown> = {};
     const [entries, models] = await Promise.all([collectSessions(), collectModels()]);
@@ -279,6 +314,12 @@ export function apply(ctx: any, config: PluginConfig): void {
       // 生效的模型范围随心跳响应回传：管理员在配置页改了范围后，
       // 插件最多一个周期（30 秒）就能看到新值，不需要重启。
       if (Array.isArray(res?.allowed_models)) allowedModels = res.allowed_models;
+      // 只在首个成功的心跳后补投一次：之后的积压都由 SSE 覆盖，
+      // 每轮心跳都补的话会把「模型正在处理中、尚未标已读」的邮件重复投递。
+      if (!caughtUp) {
+        caughtUp = true;
+        await catchUp(res?.pending_mails);
+      }
     } catch {
       // 心跳失败不报错：网络抖动很常见，下一轮会补上。
       // 真的持续连不上时 Gateway 会把它判成离线，那才是可见的信号。
@@ -858,6 +899,7 @@ export function apply(ctx: any, config: PluginConfig): void {
     startSSE((type, data) => {
       switch (type) {
         case 'new_mail':
+          if (data?.mail_id) deliveredMails.add(data.mail_id);
           deliverMail(data, 'mail')
             .then(({ sessionID, reused }) => {
               console.error(`[dsh-mail-bridge] ${type} -> ${reused ? '续谈' : '新会话'} ${sessionID}`);