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/repo/quota_test.go

@@ -0,0 +1,173 @@
+package repo
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+
+	"github.com/agentmail/gateway/internal/db"
+)
+
+// setupTestDB 起一个临时 SQLite 库并建表，供配额测试使用。
+// 直接用真实的 SQLite 而非 mock：配额的正确性核心在于「判断与自增在同一条 UPDATE 里」，
+// 这正是只有真实数据库才能验证的部分。
+func setupTestDB(t *testing.T) {
+	t.Helper()
+
+	dir := t.TempDir()
+	if err := db.Connect(context.Background(), filepath.Join(dir, "test.db")); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	if err := db.Migrate(context.Background()); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	t.Cleanup(db.Close)
+}
+
+func seedAgent(t *testing.T, name string, max int) {
+	t.Helper()
+	_, err := db.DB.ExecContext(context.Background(),
+		`INSERT INTO agents (agent_name, secret, platform, max_rounds) VALUES ($1, 'x', 'test', $2)`,
+		name, max)
+	if err != nil {
+		t.Fatalf("seed agent: %v", err)
+	}
+}
+
+func TestConsumeQuotaCountsDown(t *testing.T) {
+	setupTestDB(t)
+	seedAgent(t, "bot", 3)
+	ctx := context.Background()
+
+	for i := 1; i <= 3; i++ {
+		q, err := ConsumeQuota(ctx, "bot")
+		if err != nil {
+			t.Fatalf("第 %d 次占用失败: %v", i, err)
+		}
+		if q.Used != i || q.Remaining != 3-i {
+			t.Errorf("第 %d 次: used=%d remaining=%d, want used=%d remaining=%d",
+				i, q.Used, q.Remaining, i, 3-i)
+		}
+	}
+
+	q, err := ConsumeQuota(ctx, "bot")
+	if !errors.Is(err, ErrQuotaExhausted) {
+		t.Fatalf("第 4 次应耗尽，得到 err=%v", err)
+	}
+	// 耗尽时仍要给出快照，调用方才能在错误文案里写清 used/max
+	if q.Used != 3 || q.Max != 3 {
+		t.Errorf("耗尽时快照不对: %+v", q)
+	}
+}
+
+func TestConsumeQuotaUnlimited(t *testing.T) {
+	setupTestDB(t)
+	seedAgent(t, "free", 0) // 0 = 不限
+	ctx := context.Background()
+
+	for i := 0; i < 5; i++ {
+		q, err := ConsumeQuota(ctx, "free")
+		if err != nil {
+			t.Fatalf("不限额时不应失败: %v", err)
+		}
+		if !q.Unlimited || q.Remaining != -1 {
+			t.Errorf("不限额快照不对: %+v", q)
+		}
+	}
+}
+
+// 配额的核心保证：并发发信不能把额度刷穿。
+// 判断与自增若分成两步（先 SELECT 再 UPDATE），并发下两个请求会双双通过检查。
+func TestConsumeQuotaConcurrentDoesNotOverdraw(t *testing.T) {
+	setupTestDB(t)
+	const limit = 10
+	seedAgent(t, "racer", limit)
+	ctx := context.Background()
+
+	const attempts = 40
+	var (
+		wg      sync.WaitGroup
+		mu      sync.Mutex
+		granted int
+	)
+	for i := 0; i < attempts; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			if _, err := ConsumeQuota(ctx, "racer"); err == nil {
+				mu.Lock()
+				granted++
+				mu.Unlock()
+			}
+		}()
+	}
+	wg.Wait()
+
+	if granted != limit {
+		t.Errorf("并发 %d 次请求在上限 %d 下放行了 %d 次", attempts, limit, granted)
+	}
+
+	q, err := GetQuota(ctx, "racer")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if q.Used != limit {
+		t.Errorf("used_rounds = %d，应恰好等于上限 %d（未刷穿也未少记）", q.Used, limit)
+	}
+}
+
+func TestSetAndResetQuota(t *testing.T) {
+	setupTestDB(t)
+	seedAgent(t, "bot", 2)
+	ctx := context.Background()
+
+	if _, err := ConsumeQuota(ctx, "bot"); err != nil {
+		t.Fatal(err)
+	}
+
+	q, err := SetQuota(ctx, "bot", 5)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// 调上限不应清掉已用次数
+	if q.Max != 5 || q.Used != 1 || q.Remaining != 4 {
+		t.Errorf("SetQuota 后 %+v，want max=5 used=1 remaining=4", q)
+	}
+
+	q, err = ResetQuota(ctx, "bot")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if q.Used != 0 || q.Remaining != 5 {
+		t.Errorf("ResetQuota 后 %+v，want used=0 remaining=5", q)
+	}
+
+	// 负数上限归一为 0（不限），而不是造出一个永远发不出信的 Agent
+	if q, err = SetQuota(ctx, "bot", -3); err != nil {
+		t.Fatal(err)
+	} else if !q.Unlimited {
+		t.Errorf("负数上限应视为不限，得到 %+v", q)
+	}
+}
+
+func TestQuotaUnknownAgent(t *testing.T) {
+	setupTestDB(t)
+	ctx := context.Background()
+
+	if _, err := GetQuota(ctx, "ghost"); err == nil {
+		t.Error("不存在的 Agent 应报错")
+	}
+	if _, err := ConsumeQuota(ctx, "ghost"); err == nil {
+		t.Error("不存在的 Agent 占用配额应报错")
+	}
+	if errors.Is(func() error { _, e := ConsumeQuota(ctx, "ghost"); return e }(), ErrQuotaExhausted) {
+		t.Error("不存在的 Agent 不该被报成「配额耗尽」")
+	}
+}
+
+func TestMain(m *testing.M) {
+	os.Exit(m.Run())
+}