feat: AgentMail —— 以邮件为统一范式的多智能体协作平台

Go 单二进制网关 + React 前端 + opencode 桥接插件。部署产物是
「一个二进制加一个 .db 文件」：前端经 go:embed 打进二进制，
数据库默认内置 SQLite，systemd 托管。

核心设计
- 三维寻址 name@path.session，按最后一个 . 切分；session 位三态：
  省略=默认会话 / new=强制新建 / 具体别名=必须已存在（否则 404 无法送达）
- 会话别名默认复用 Agent 平台自己的命名机制（opencode 的 slug 与模型生成的
  标题），不在本侧另造一套；人显式定过的别名不被平台同步覆盖
- 对话树不建 tree_nodes 表：parent_mail_id 已完整编码树结构，
  再维护一张表就是第二份真相。用递归 CTE 查，按方向分块加载
- 附件内容存磁盘、按 sha256 内容寻址，数据库只存元数据；天然去重，
  且路径与用户 filename 无关，杜绝 ../ 穿越
- 配额约束的是模型的自主发信，不是 harness 的转发：插件代劳的权限询问与
  最终总结走免配额通道，靠上游消息 id 做幂等键而非计数
- 往返预算下沉到会话（写信时给、对话页里改）+ Agent 全局配额，两层都要过

后端 gateway/
- models/repo/handler/middleware/sse/blob 分层；两方言（SQLite/PostgreSQL）
  共用一份 repo 层 SQL，差异集中在 internal/db
- 多用户认证（bcrypt cost12、登录限速、会话隔离、权限边界）
- 密钥体系：Agent 密钥与用户密钥分表，三种生命周期；登记式密钥让全文
  只从客户端流向服务器一次
- 所有「判断 + 自增」都在同一条 UPDATE 里（配额、预算、one_time 密钥、
  附件挂载），并发下不会刷穿

前端 web/
- 三栏布局、三段式地址补全、权限卡片、密钥面板、配额面板、对话树、附件
- 全站纯 SVG 图标，不使用 emoji
- api/ 即可复用的客户端 SDK：基地址与凭证集中在 api/config.ts

插件 plugins/opencode-mail-bridge/
- 六个工具 + 两类自动转发（permission.ask 钩子接管平台原生权限询问、
  session.idle 时转发本轮总结）

gateway/internal/handler/agents.go

@@ -0,0 +1,142 @@
+package handler
+
+import (
+	"net/http"
+
+	"github.com/agentmail/gateway/internal/middleware"
+	"github.com/agentmail/gateway/internal/models"
+	"github.com/agentmail/gateway/internal/repo"
+)
+
+// ---------- Agent ----------
+
+type registerRequest struct {
+	Name       string            `json:"name"`
+	Secret     string            `json:"secret"`
+	Workspaces []models.Workspace `json:"workspaces"`
+	Platform   string            `json:"platform"`
+}
+
+// POST /api/v1/agent/register
+//
+// 两种认证方式：
+//   1. Authorization: Bearer <agent_key_token> —— 密钥认证（推荐）。
+//      密钥未绑定时用本请求的 name 落定；已绑定时 name 必须与之一致，
+//      否则等于拿别人的密钥冒充新身份。
+//   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")
+		return
+	}
+	if req.Name == "" {
+		Error(w, http.StatusBadRequest, "Missing name")
+		return
+	}
+
+	keyToken := middleware.BearerToken(r)
+	if keyToken == "" && req.Secret == "" {
+		Error(w, http.StatusBadRequest, "需要 Authorization: Bearer <密钥> 或 body 里的 secret")
+		return
+	}
+
+	if keyToken != "" {
+		bound, err := repo.VerifyAgentKey(r.Context(), keyToken)
+		if err != nil {
+			writeKeyErr(w, err)
+			return
+		}
+		if bound != "" && bound != req.Name {
+			Error(w, http.StatusForbidden,
+				"该密钥已绑定到 Agent \""+bound+"\"，不能用于注册 \""+req.Name+"\"")
+			return
+		}
+	}
+
+	if req.Platform == "" {
+		req.Platform = "pi"
+	}
+
+	// 三维地址的 name 位与人类用户名共用命名空间，不得重名
+	if ok, err := repo.AgentNameAvailable(r.Context(), req.Name); err != nil {
+		Error(w, http.StatusInternalServerError, "Failed to validate agent name")
+		return
+	} else if !ok {
+		Error(w, http.StatusConflict, "该名称已被人类用户占用")
+		return
+	}
+	if req.Name == "human" {
+		Error(w, http.StatusBadRequest, "human 是保留别名，不能作为 Agent 名")
+		return
+	}
+
+	// 密钥认证时不需要 secret，但 agents.secret 非空约束仍在；
+	// 存密钥本身作占位，旧的 name/secret 路径不受影响。
+	secret := req.Secret
+	if secret == "" {
+		secret = keyToken
+	}
+
+	if err := repo.CreateOrUpdateAgent(r.Context(), req.Name, secret, req.Platform, req.Workspaces); err != nil {
+		Error(w, http.StatusInternalServerError, "Failed to register agent")
+		return
+	}
+
+	// 待绑定密钥在首次注册成功后落定到该 Agent
+	if keyToken != "" {
+		if err := repo.ClaimAgentKey(r.Context(), keyToken, req.Name); err != nil {
+			Error(w, http.StatusInternalServerError, "Failed to bind key")
+			return
+		}
+	}
+
+	JSON(w, http.StatusOK, map[string]string{
+		"status":     "registered",
+		"agent_name": req.Name,
+	})
+}
+
+// POST /api/v1/agent/heartbeat
+func HeartbeatAgent(w http.ResponseWriter, r *http.Request) {
+	agentName := middleware.GetAgentName(r)
+	if agentName == "" {
+		Error(w, http.StatusUnauthorized, "Unauthorized")
+		return
+	}
+
+	pending, err := repo.HeartbeatAgent(r.Context(), agentName)
+	if err != nil {
+		Error(w, http.StatusInternalServerError, "Failed to heartbeat")
+		return
+	}
+
+	// 心跳回传配额：插件据此把剩余次数注入 Agent 上下文，
+	// 让它在配额耗尽前主动发总结，而不是撞到 403 才发现。
+	quota, qErr := repo.GetQuota(r.Context(), agentName)
+	if qErr != nil {
+		// 配额读不到不影响心跳本身，降级为不限额
+		quota = repo.Quota{AgentName: agentName, Unlimited: true, Remaining: -1}
+	}
+
+	JSON(w, http.StatusOK, map[string]interface{}{
+		"status":        "ok",
+		"pending_mails": pending,
+		"quota":         quota,
+	})
+}
+
+// GET /api/v1/agents
+func ListAgents(w http.ResponseWriter, r *http.Request) {
+	statusFilter := r.URL.Query().Get("status")
+
+	agents, err := repo.ListAgents(r.Context(), statusFilter)
+	if err != nil {
+		Error(w, http.StatusInternalServerError, "Failed to list agents")
+		return
+	}
+
+	JSON(w, http.StatusOK, map[string]interface{}{
+		"agents": emptySlice(agents),
+	})
+}