jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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）
- 生产已部署
This commit is contained in:
JianFeeeee
2026-09-02 22:47:31 +08:00
parent 89356d4a9b
commit 9e5c557cdf
26 changed files with 953 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
gateway/internal/handler/agents.go
View File

@ -54,8 +54,7 @@ type heartbeatRequest struct {
// 2. body 里带 secret —— 旧方式，兼容保留。
func RegisterAgent(w http.ResponseWriter, r *http.Request) {
var req registerRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
if req.Name == "" {

18
gateway/internal/handler/auth.go
View File

@ -70,8 +70,7 @@ type setupRequest struct {
// POST /api/v1/setup/admin —— 公开，但仅在系统无任何用户时可用
func SetupAdmin(w http.ResponseWriter, r *http.Request) {
var req setupRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
if len(req.Password) < 8 {
@ -110,8 +109,7 @@ func SetupAdmin(w http.ResponseWriter, r *http.Request) {
// POST /api/v1/auth/login
func Login(w http.ResponseWriter, r *http.Request) {
var req loginRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
name := strings.ToLower(strings.TrimSpace(req.Username))
@ -192,8 +190,7 @@ func ChangePassword(w http.ResponseWriter, r *http.Request) {
}
var req changePasswordRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
if len(req.NewPassword) < 8 {
@ -240,8 +237,7 @@ type createUserRequest struct {
// POST /api/v1/admin/users
func AdminCreateUser(w http.ResponseWriter, r *http.Request) {
var req createUserRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
if len(req.Password) < 8 {
@ -280,8 +276,7 @@ func AdminUpdateUser(w http.ResponseWriter, r *http.Request) {
return
}
var req updateUserRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
@ -361,8 +356,7 @@ func AdminResetPassword(w http.ResponseWriter, r *http.Request) {
return
}
var req resetPasswordRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
if len(req.NewPassword) < 8 {

3
gateway/internal/handler/contacts.go
View File

@ -52,8 +52,7 @@ func ArchiveContact(w http.ResponseWriter, r *http.Request) {
}
var req archiveRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}

138
gateway/internal/handler/decode_test.go Normal file
View File

@ -0,0 +1,138 @@
package handler
import (
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
"github.com/agentmail/gateway/internal/models"
)
// 400 的信息必须指向具体字段。
//
// 起因：写跨主机验证脚本时把 workspaces 传成了字符串数组，
// 服务端回的是一句固定的 "Invalid JSON" —— 只能靠翻服务端结构体才发现是哪个字段。
// 第三方客户端没有这个条件。
func TestDecodeBodyErrorNamesTheField(t *testing.T) {
type body struct {
Name string `json:"name"`
Workspaces []models.Workspace `json:"workspaces"`
}
cases := []struct {
name string
payload string
wantHas []string
wantMiss []string
}{
{
name: "字段类型不对要说出字段名与期望类型",
payload: `{"name":"bot","workspaces":["/tmp/ws"]}`,
// 期望能看出：是 workspaces，要的是 object 数组，给的是 string
wantHas: []string{"workspaces", "object", "string"},
// 不该把 Go 类型名漏出去
wantMiss: []string{"models.Workspace", "[]models"},
},
{
name: "整个体的类型不对",
payload: `["not","an","object"]`,
wantHas: []string{"object"},
},
{
// 截断的 JSON 走的是 io.ErrUnexpectedEOF，不是 json.SyntaxError
name: "被截断的体要说明是截断",
payload: `{"name":`,
wantHas: []string{"语法", "结束"},
},
{
name: "非法字符要给出位置",
payload: `{"name":1x}`,
wantHas: []string{"语法", "字节"},
},
{
name: "空体单独说明",
payload: ``,
wantHas: []string{"为空"},
},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
r := httptest.NewRequest(http.MethodPost, "/x", strings.NewReader(c.payload))
w := httptest.NewRecorder()
var v body
if DecodeBody(w, r, &v) {
t.Fatal("这个体应当解析失败")
}
if w.Code != http.StatusBadRequest {
t.Fatalf("状态码应为 400，实际 %d", w.Code)
}
var resp map[string]string
if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
t.Fatalf("响应不是 JSON: %v", err)
}
msg := resp["error"]
if msg == "" {
t.Fatal("error 字段为空")
}
for _, want := range c.wantHas {
if !strings.Contains(msg, want) {
t.Errorf("信息里应含 %q，实际 %q", want, msg)
}
}
for _, miss := range c.wantMiss {
if strings.Contains(msg, miss) {
t.Errorf("信息里不该含 Go 类型名 %q：%q", miss, msg)
}
}
})
}
}
// 合法请求体不该被拦，也不该写任何响应 ——
// 写了的话调用方接着写自己的响应就成了两次 WriteHeader。
func TestDecodeBodyPassesValidPayload(t *testing.T) {
type body struct {
Name string `json:"name"`
Workspaces []models.Workspace `json:"workspaces"`
}
payload := `{"name":"bot","workspaces":[{"name":"demo","path":"/tmp/ws"}]}`
r := httptest.NewRequest(http.MethodPost, "/x", strings.NewReader(payload))
w := httptest.NewRecorder()
var v body
if !DecodeBody(w, r, &v) {
t.Fatalf("合法体被拒：%s", w.Body.String())
}
if w.Body.Len() != 0 {
t.Errorf("成功时不该写响应体，实际写了 %q", w.Body.String())
}
if v.Name != "bot" || len(v.Workspaces) != 1 || v.Workspaces[0].Path != "/tmp/ws" {
t.Errorf("解析结果不对：%+v", v)
}
}
// 空数组是合法的 —— 两个正式插件注册时都传 workspaces: []。
func TestDecodeBodyAcceptsEmptyWorkspaces(t *testing.T) {
type body struct {
Name string `json:"name"`
Workspaces []models.Workspace `json:"workspaces"`
}
r := httptest.NewRequest(http.MethodPost, "/x",
strings.NewReader(`{"name":"opencode","workspaces":[]}`))
w := httptest.NewRecorder()
var v body
if !DecodeBody(w, r, &v) {
t.Fatalf("空 workspaces 被拒：%s", w.Body.String())
}
if len(v.Workspaces) != 0 {
t.Errorf("应为空数组，实际 %+v", v.Workspaces)
}
}

6
gateway/internal/handler/forward.go
View File

@ -75,8 +75,7 @@ func forwardSubject(custom, original string) string {
// actor 是转发者名（Agent 名或用户名），fromWorkspace 仅 Agent 有。
func doForward(w http.ResponseWriter, r *http.Request, mailID uuid.UUID, actor, fromWorkspace string, isAgent bool) {
var req forwardRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
if strings.TrimSpace(req.To) == "" {
@ -247,8 +246,7 @@ func AdminSetQuota(w http.ResponseWriter, r *http.Request) {
}
var req setQuotaRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
n := req.DefaultRounds

73
gateway/internal/handler/helpers.go
View File

@ -3,7 +3,10 @@ package handler
import (
"encoding/json"
"errors"
"io"
"net/http"
"reflect"
"strconv"
"strings"
"unicode/utf8"
@ -27,6 +30,76 @@ func Decode(r *http.Request, v interface{}) error {
return json.NewDecoder(r.Body).Decode(v)
}
// DecodeBody 解析请求体，失败时直接写 400 并返回 false。
//
// 与直接用 Decode 的区别是错误信息**指向具体字段**。原先 22 处调用点
// 一律回一句固定的 "Invalid JSON"，客户端只知道「有问题」却不知道哪里有问题 ——
// 实测踩过一次：`workspaces` 要的是 `[{name, path}]`，传字符串数组得到的
// 就是那句固定文案，只能靠翻服务端结构体才发现。第三方客户端没有这个条件。
func DecodeBody(w http.ResponseWriter, r *http.Request, v interface{}) bool {
if err := Decode(r, v); err != nil {
Error(w, http.StatusBadRequest, decodeErrMsg(err))
return false
}
return true
}
// decodeErrMsg 把 json 解码错误翻成一句能照着改的话。
//
// 刻意不回显 json 包的原文：它带 Go 的类型名（如 models.Workspace），
// 那是本侧的实现细节，对调用方没有意义，也不该出现在公开 API 的响应里。
func decodeErrMsg(err error) string {
if errors.Is(err, io.EOF) {
return "请求体为空"
}
// 截断的 JSON 走的不是 SyntaxError 而是 ErrUnexpectedEOF ——
// 不单独处理的话会落到最后那句笼统的兜底文案里
if errors.Is(err, io.ErrUnexpectedEOF) {
return "JSON 语法错误：请求体在解析完成前就结束了（可能被截断）"
}
var typeErr *json.UnmarshalTypeError
if errors.As(err, &typeErr) {
if typeErr.Field != "" {
return "字段 \"" + typeErr.Field + "\" 类型不对：期望 " +
jsonKindName(typeErr.Type) + "，收到 " + typeErr.Value
}
return "请求体类型不对：期望 " + jsonKindName(typeErr.Type) + "，收到 " + typeErr.Value
}
var syntaxErr *json.SyntaxError
if errors.As(err, &syntaxErr) {
return "JSON 语法错误（第 " + strconv.FormatInt(syntaxErr.Offset, 10) + " 字节处）"
}
return "请求体不是合法 JSON"
}
// jsonKindName 把 Go 类型说成 JSON 的说法。
// 调用方写的是 JSON，用 []models.Workspace 去解释它要的是什么毫无帮助。
func jsonKindName(t reflect.Type) string {
if t == nil {
return "未知类型"
}
switch t.Kind() {
case reflect.Slice, reflect.Array:
return jsonKindName(t.Elem()) + " 数组"
case reflect.Map, reflect.Struct:
return "object"
case reflect.String:
return "string"
case reflect.Bool:
return "boolean"
case reflect.Ptr:
return jsonKindName(t.Elem())
default:
if k := t.Kind(); k >= reflect.Int && k <= reflect.Float64 {
return "number"
}
return t.Kind().String()
}
}
// httpError 携带 HTTP 状态码的错误
type httpError struct {
status int

9
gateway/internal/handler/keys.go
View File

@ -50,8 +50,7 @@ func CreateAgentKey(w http.ResponseWriter, r *http.Request) {
}
var req createKeyRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
@ -102,8 +101,7 @@ func BindAgentKey(w http.ResponseWriter, r *http.Request) {
return
}
var req bindKeyRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
name := strings.TrimSpace(req.AgentName)
@ -129,8 +127,7 @@ func CreateMyKey(w http.ResponseWriter, r *http.Request) {
}
var req createKeyRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}

6
gateway/internal/handler/mail.go
View File

@ -125,8 +125,7 @@ func SendMail(w http.ResponseWriter, r *http.Request) {
}
var req sendMailRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
if req.To == "" || req.Subject == "" || req.Body == "" {
@ -453,8 +452,7 @@ func MarkInboxRead(w http.ResponseWriter, r *http.Request) {
var req markReadRequest
// 允许空 body：`POST /mail/read` 不带任何内容 = 全部标掉
if r.ContentLength > 0 {
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
}

3
gateway/internal/handler/me.go
View File

@ -40,8 +40,7 @@ func MeSendMail(w http.ResponseWriter, r *http.Request) {
}
var req meSendMailRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
if req.To == "" || req.Subject == "" || req.Body == "" {

3
gateway/internal/handler/models_scope.go
View File

@ -83,8 +83,7 @@ func AdminSetAgentModels(w http.ResponseWriter, r *http.Request) {
var req struct {
Models []repo.ModelRef `json:"models"`
}
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
if len(req.Models) > maxAllowedModels {

6
gateway/internal/handler/permission.go
View File

@ -43,8 +43,7 @@ func RequestPermission(w http.ResponseWriter, r *http.Request) {
}
var req permissionRequestRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
if req.Question == "" {
@ -165,8 +164,7 @@ func DecidePermission(w http.ResponseWriter, r *http.Request) {
}
var req permissionDecideRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
if req.MailID == "" || req.Decision == "" {

9
gateway/internal/handler/sessions.go
View File

@ -107,8 +107,7 @@ func UpdateSessionAlias(w http.ResponseWriter, r *http.Request) {
}
var req updateAliasRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
alias := strings.TrimSpace(req.Alias)
@ -176,8 +175,7 @@ func SyncSession(w http.ResponseWriter, r *http.Request) {
}
var req syncSessionRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
@ -307,8 +305,7 @@ func UpdateSessionBudget(w http.ResponseWriter, r *http.Request) {
return
}
var req sessionBudgetRequest
if err := Decode(r, &req); err != nil {
Error(w, http.StatusBadRequest, "Invalid JSON")
if !DecodeBody(w, r, &req) {
return
}
if req.MaxRounds == nil && !req.Reset {