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 时转发本轮总结）
2026-09-02 10:29:26 +08:00
commit 0e754617a4
95 changed files with 23219 additions and 0 deletions
--- a/gateway/internal/handler/keys.go
+++ b/gateway/internal/handler/keys.go
@ -0,0 +1,179 @@
+package handler
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/agentmail/gateway/internal/middleware"
+	"github.com/agentmail/gateway/internal/models"
+	"github.com/agentmail/gateway/internal/repo"
+)
+
+// ---------- 密钥管理 ----------
+//
+// 两套接口，权限边界不同：
+//   /admin/agent-keys —— 管理员签发 Agent 接入密钥
+//   /me/keys          —— 用户自助签发客户端连接密钥（不能注册 Agent）
+//
+// 密钥全文只在创建响应里出现一次，列表接口只给前 8 位 hint。
+
+type createKeyRequest struct {
+	// AgentName 仅 Agent 密钥使用；留空表示「待绑定」，首次注册时按注册请求的 name 落定
+	AgentName string `json:"agent_name"`
+	// Label 人类可读备注（如「我的笔记本」「CI 机器」）
+	Label string `json:"label"`
+	// KeyType permanent / one_time / timed
+	KeyType string `json:"key_type"`
+	// ExpiresHours 仅 timed 使用，必须为正
+	ExpiresHours int `json:"expires_hours"`
+	// KeyToken 仅 Agent 密钥使用：登记一把客户端已在本地生成的密钥。
+	// 插件首次安装时自己生成密钥并打印出来，管理员把它填到这里完成登记，
+	// 密钥全文因此不需要从服务器往客户端传。留空则由服务器生成。
+	KeyToken string `json:"key_token"`
+}
+
+// normalizeKeyType 默认给 permanent，避免调用方漏填时落到非法值
+func normalizeKeyType(t string) string {
+	t = strings.TrimSpace(t)
+	if t == "" {
+		return models.KeyPermanent
+	}
+	return t
+}
+
+// POST /api/v1/admin/agent-keys
+func CreateAgentKey(w http.ResponseWriter, r *http.Request) {
+	admin := middleware.GetUser(r)
+	if admin == nil {
+		Error(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+
+	var req createKeyRequest
+	if err := Decode(r, &req); err != nil {
+		Error(w, http.StatusBadRequest, "Invalid JSON")
+		return
+	}
+
+	key, err := repo.CreateAgentKey(r.Context(),
+		strings.TrimSpace(req.AgentName), normalizeKeyType(req.KeyType),
+		strings.TrimSpace(req.Label), req.ExpiresHours, admin.ID,
+		strings.TrimSpace(req.KeyToken))
+	if err != nil {
+		writeKeyErr(w, err)
+		return
+	}
+
+	// 唯一一次回传全文
+	JSON(w, http.StatusOK, map[string]any{"key": key})
+}
+
+// GET /api/v1/admin/agent-keys?agent_name=xxx
+func ListAgentKeys(w http.ResponseWriter, r *http.Request) {
+	keys, err := repo.ListAgentKeys(r.Context(), r.URL.Query().Get("agent_name"))
+	if err != nil {
+		Error(w, http.StatusInternalServerError, "Failed to list keys")
+		return
+	}
+	JSON(w, http.StatusOK, map[string]any{"keys": keys})
+}
+
+// DELETE /api/v1/admin/agent-keys/{id}
+func DeleteAgentKey(w http.ResponseWriter, r *http.Request) {
+	id, ok := pathUUID(w, r, "id")
+	if !ok {
+		return
+	}
+	if err := repo.DeleteAgentKey(r.Context(), id); err != nil {
+		writeKeyErr(w, err)
+		return
+	}
+	JSON(w, http.StatusOK, map[string]string{"status": "deleted"})
+}
+
+type bindKeyRequest struct {
+	AgentName string `json:"agent_name"`
+}
+
+// POST /api/v1/admin/agent-keys/{id}/bind
+func BindAgentKey(w http.ResponseWriter, r *http.Request) {
+	id, ok := pathUUID(w, r, "id")
+	if !ok {
+		return
+	}
+	var req bindKeyRequest
+	if err := Decode(r, &req); err != nil {
+		Error(w, http.StatusBadRequest, "Invalid JSON")
+		return
+	}
+	name := strings.TrimSpace(req.AgentName)
+	if name == "" {
+		Error(w, http.StatusBadRequest, "Missing agent_name")
+		return
+	}
+	if err := repo.BindAgentKey(r.Context(), id, name); err != nil {
+		writeKeyErr(w, err)
+		return
+	}
+	JSON(w, http.StatusOK, map[string]string{"status": "bound", "agent_name": name})
+}
+
+// ---------- 用户连接密钥 ----------
+
+// POST /api/v1/me/keys
+func CreateMyKey(w http.ResponseWriter, r *http.Request) {
+	user := middleware.GetUser(r)
+	if user == nil {
+		Error(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+
+	var req createKeyRequest
+	if err := Decode(r, &req); err != nil {
+		Error(w, http.StatusBadRequest, "Invalid JSON")
+		return
+	}
+
+	key, err := repo.CreateUserKey(r.Context(), user.ID,
+		strings.TrimSpace(req.Label), normalizeKeyType(req.KeyType), req.ExpiresHours)
+	if err != nil {
+		writeKeyErr(w, err)
+		return
+	}
+	JSON(w, http.StatusOK, map[string]any{"key": key})
+}
+
+// GET /api/v1/me/keys
+func ListMyKeys(w http.ResponseWriter, r *http.Request) {
+	user := middleware.GetUser(r)
+	if user == nil {
+		Error(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	keys, err := repo.ListUserKeys(r.Context(), user.ID)
+	if err != nil {
+		Error(w, http.StatusInternalServerError, "Failed to list keys")
+		return
+	}
+	JSON(w, http.StatusOK, map[string]any{"keys": keys})
+}
+
+// DELETE /api/v1/me/keys/{id}
+func DeleteMyKey(w http.ResponseWriter, r *http.Request) {
+	user := middleware.GetUser(r)
+	if user == nil {
+		Error(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	id, ok := pathUUID(w, r, "id")
+	if !ok {
+		return
+	}
+	// repo 层带 user_id 条件，删不到就是不属于自己或不存在，统一 404
+	if err := repo.DeleteUserKey(r.Context(), user.ID, id); err != nil {
+		writeKeyErr(w, err)
+		return
+	}
+	JSON(w, http.StatusOK, map[string]string{"status": "deleted"})
+}
+