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）
- 生产已部署

docs/API.md

@@ -308,6 +308,15 @@ POST /attachments              上传附件
 GET  /attachments/{id}         下载附件
 POST /sessions/{id}/sync       回写平台侧生成的会话标题/slug
 GET  /agent/models/allowed     读当前生效的模型范围（通常不需要——心跳已回传）
+
+注册体的 `workspaces` 是**对象数组**，不是字符串数组：
+
+```json
+{"name":"mybot","platform":"stdlib","workspaces":[{"name":"demo","path":"/tmp/ws"}]}
+```
+
+两个官方插件都传 `workspaces: []`（工作目录由每封邮件的地址 path 位决定，
+见「心跳与平台会话快照」一节的 `to_workspace`）。
 ```
 
 发信与转发扣**本任务（会话）的往返预算**。
@@ -484,6 +493,21 @@ curl -N {host}/api/v1/events/stream -H "Authorization: Bearer $TOKEN"
 
 ## 六、错误约定
 
+### 400 的信息指向具体字段
+
+请求体解析失败时不再回一句笼统的 `Invalid JSON`，而是说出是哪个字段、
+期望什么、收到什么：
+
+```json
+{"error": "字段 \"workspaces\" 类型不对：期望 object，收到 string"}
+{"error": "JSON 语法错误（第 8 字节处）"}
+{"error": "请求体为空"}
+```
+
+期望类型用 JSON 的说法（`object` / `string` / `number` / `boolean` / `... 数组`），
+不回显 Go 类型名——那是本侧的实现细节。
+
+
 失败响应统一为 `{"error": "中文可操作描述"}`，状态码：
 
 | 码 | 含义 |

docs/PHASE7-REMAINING.md

@@ -2,12 +2,84 @@
 
 7.7 DSH 插件已完成（见 `docs/PLUGIN-GUIDE.md` 与 PLAN.md §7.7）。
 
-## 无法立即推进（缺基础设施）
+## 7.8 跨主机 Agent —— 协议层面已支持
 
-### 7.8 跨主机 Agent 发现
-- Gateway + Registry 拆分为独立服务
-- etcd / Consul 服务注册与发现
-- Agent 跨主机路由
+**原计划**（Gateway + Registry 拆分、etcd/Consul 服务注册、跨主机路由）**不做**。
+它解决的是「Gateway 怎么找到 Agent」，而这个方向从一开始就不成立：
+
+**连接方向是单向的 —— Agent 主动连 Gateway，Gateway 从不外呼。**
+因此「发现」不是 Gateway 的问题，是 Agent 的配置问题：它只需要知道一个
+公网 URL 加一把密钥。注册中心要解决的「被叫方在哪」在这个架构里不存在
+—— 被叫方自己会打进来。
+
+同一个理由让平台会话同步走插件上报（见 PLUGIN-GUIDE §4）：
+Gateway 不外呼，就不需要知道任何 Agent 的地址。
+
+### 已验证可用（2026-09-02，从 192.168.2.106 打到公网）
+
+完整一轮往返跑通了：`admin` 在本机发信给 `remotebot@/tmp/remotebot-ws`，
+`.106` 上的脚本收到并回信入库。
+
+| 能力 | 结果 |
+|---|---|
+| 注册（`POST /agent/register`） | 通，`workspaces` 落库为 `[{"name":"demo","path":"/tmp/remotebot-ws"}]` |
+| 心跳（`POST /agent/heartbeat`） | 通，`models_synced: 1`、回传 `allowed_models` 与 `models_unrestricted` |
+| SSE 长连（`GET /events/stream` + Bearer） | 通，收到 `connected` |
+| 收件箱 + 标记已读 | 通 |
+| 发信（`POST /mail/send` 带 `reply_to`） | 通，`from_workspace` 正确 |
+| Gateway 侧在线状态 | `status=online`，`last_seen` 随心跳推进 |
+
+验证用的是一个**只依赖 python 标准库的脚本**（`deploy/remote-agent-demo.py`），
+它没装 AgentMail 的任何代码。这就是「协议层面已支持」的含义：
+跨主机不需要新组件，只需要三个环境变量。
+
+### 写这个脚本时踩的两个坑（新平台接入会重复踩）
+
+**`workspaces` 是对象数组 `[{name, path}]`，不是字符串数组。**
+传字符串原先只得到一句固定的 400 `Invalid JSON` —— 完全没指向是哪个字段，
+只能靠翻服务端结构体才能发现。两个正式插件都传 `workspaces: []`，
+所以这个坑一直没暴露过；第三方客户端没有「翻服务端源码」这个条件。
+
+**已修**：新增 `handler.DecodeBody`，22 处 `Decode` + 固定文案的调用点全部换过去。
+现在同样的请求回：
+
+```json
+{"error": "字段 \"workspaces\" 类型不对：期望 object，收到 string"}
+```
+
+刻意不回显 `encoding/json` 的原文——它带 Go 类型名（`models.Workspace`），
+那是本侧的实现细节，不该出现在公开 API 的响应里。
+`internal/handler/decode_test.go` 钉住这一点（含「不得泄漏 Go 类型名」的断言）。
+
+**SSE 只推连上之后的事件，离线期间的邮件要靠心跳的 `pending_mails` 补拉。**
+第一版脚本只挂了 SSE，于是启动前发的那封邮件永远不会被处理 ——
+日志里 `pending=1` 明明写着有一封未读，却没人去拉。
+
+**这个坑两个正式插件也有**（原以为它们做了补拉，查了才发现没有）。已修：
+新增共用模块 `lib/catchup.js`，两插件在首个成功心跳后补投一次。
+
+- 只在**首个**心跳后补，不是每轮：每轮都补会把「模型正在处理中、尚未标已读」
+  的邮件重复投递
+- 串行投递、一次最多 5 封：每封都要起一轮模型，并发放出去等于对上游打 N 个
+  并发请求，且最后那几封要等前面全部跑完
+- 与 SSE 共用 `deliveredMails` 去重：心跳与 SSE 建连之间有个窗口，
+  那期间到的邮件既在 `pending_mails` 里也会被 SSE 推一次
+- 按时间**正序**补投（收件箱是倒序返回的）：同一会话里的多封邮件倒着塞进去，
+  上下文顺序是乱的
+- `permission` 类邮件不补投：原来的工具调用早随进程一起没了，
+  投过去模型没有可恢复的上下文
+
+端到端验证（两平台各一次）：停插件 → 发邮件 → 启插件 → 日志出现
+「补投 1 封离线期间的邮件」→ 回信入库。随后在线状态再发一封确认只回一次。
+
+### 剩下的确实是运维便利，不是能力缺失
+
+- [ ] 一条命令为远端主机建密钥并打印那三个环境变量（现在要手工调 admin API）
+- [ ] 密钥轮换（现在换密钥要重启远端 agent）
+- [ ] Agent 列表显示来源主机（`agents.host_url` 列已存在但没人写，
+      要写的话应当由心跳带上自报的地址 —— 仍然不是 Gateway 去探测）
+
+这三项都不阻塞跨主机使用，因此不再归入 Phase 7。
 
 ## 可以立即推进的生产缺陷
 

docs/PLAN.md

@@ -1120,11 +1120,21 @@ execute: {
       与第三方客户端），新增同序的 `candidates`；过滤时标题也参与匹配 ——
       人记得的是「缓存选型」而不是 `brisk-harbor` 这种随机短名
 
-### 7.8 跨主机 Agent 发现
+### 7.8 跨主机 Agent（协议层面已支持，注册中心不做）
 
-- [ ] Gateway + Registry 拆分为独立服务
-- [ ] etcd / Consul 服务注册
-- [ ] Agent 跨主机路由
+原计划的 Gateway + Registry 拆分与 etcd/Consul 注册**取消**。
+它要解决「Gateway 怎么找到 Agent」，而这个问题在本架构里不存在：
+**连接方向是单向的 —— Agent 主动连 Gateway，Gateway 从不外呼。**
+远端 Agent 只需要一个公网 URL 加一把密钥，被叫方自己会打进来。
+
+- [x] Agent 从另一台主机经公网完成注册 / 心跳 / 收件箱 / SSE 长连
+      （2026-09-02 用 `deploy/remote-agent-demo.py` 验证，纯标准库 60 行）
+- [x] 心跳带模型目录与平台会话快照同样跨主机可用
+- [ ] （运维便利，不阻塞）一条命令为远端主机建密钥并打印环境变量
+- [ ] （运维便利，不阻塞）密钥轮换
+- [ ] （运维便利，不阻塞）`agents.host_url` 由心跳自报填充
+
+细节见 `docs/PHASE7-REMAINING.md` 的「7.8 跨主机 Agent」一节。
 
 ### 7.9 插件自动转发 + 会话往返预算（已完成）
 

docs/PLUGIN-GUIDE.md

@@ -432,6 +432,23 @@ opencode 还有个额外问题：**插件是懒加载的**，进程起来了插
 
 ---
 
+### `workspaces` 是对象数组
+
+注册体的 `workspaces` 要 `[{name, path}]`。传字符串数组会 400。
+两个官方插件都传 `[]`（工作目录由每封邮件的 `to_workspace` 决定），
+所以照抄它们不会踩；自己从 API 文档写起就会。
+
+### 启动时要主动拉一次收件箱
+
+SSE 只推连上之后的事件。插件重启前发来的邮件不会再推一次 ——
+心跳响应的 `pending_mails` 是唯一线索。不补拉的后果：
+那封邮件永远躺在收件箱里，发件人以为 Agent 收到了。
+
+共用实现 `lib/catchup.js` 的 `selectCatchup(mails, seen, max)`。四条约束：
+只在**首个**心跳后补（每轮都补会重复投递正在处理中的邮件）、串行且一次最多 5 封
+（每封都要起一轮模型）、与 SSE 共用一个 `deliveredMails` 集合去重
+（建连窗口期的邮件两条路都会到）、按时间**正序**投（收件箱是倒序返回的）。
+
 ## 八、新平台适配清单
 
 ```
@@ -470,6 +487,8 @@ opencode 还有个额外问题：**插件是懒加载的**，进程起来了插
       [ ] **等异步结论**再判成功／失败（失败不是同步抛的！）
       [ ] 全部失败 → renderFailureReport + relay:'summary' 发信
 
+[ ] 6.5 启动补拉：心跳 pending_mails > 0 时先处理存量未读
+
 [ ] 7. 命名与快照
       [ ] alias/title 回写 POST /sessions/{id}/sync
       [ ] slug 去掉 . @ / 等寻址分隔符
@@ -496,6 +515,7 @@ opencode 还有个额外问题：**插件是懒加载的**，进程起来了插
 | `session-snapshot.js` | 平台会话快照整理（含 subagent 过滤、slug 派生） |
 | `workspace.js` | 寻址 path 位 → 可用的 cwd |
 | `model-scope.js` | 模型目录整理 + 降级顺序 + 失败报告 |
+| `catchup.js` | 离线期间积压邮件的补投选择 |
 | `message.js` | DSH 的消息构造与会话日志读取（DSH 专用） |
 
 `test/` 下对应的测试文件同样逐字节共用。