JianFeeeee
07e6b789b2
## 配额重构：废除 Agent 终身额度
原实现在 agents 上放一个 max_rounds/used_rounds 计数器，used_rounds 单调递增、
永不重置 —— 跑满就要管理员手工重置才能再干活。那是把一次性资源模型套在长期
在线的服务上，且并行任务互相抢额度。
改为：
- 唯一被强制的预算是【会话】的往返预算（sessions.max_rounds/used_rounds），
写信时给、对话页里随时改 —— 配额的语义是「这件事值得多少个来回」，
那是任务的属性而不是 Agent 的属性
- agents.default_rounds 只作为「派给这个 Agent 的新任务」的默认值（默认 20）
- agents.used_rounds 降级为纯统计
- 新建会话速率限制（1h/20 条）堵住用 .new 开一串新会话绕过预算；
人类不受限（agentLimiterKey 返回空串即不计量）
## 窄屏适配（用户反馈「窄屏基本不可用」）
原先只有三栏并排：60(导航)+320(列表)+详情，375px 屏上详情被挤到 0。
第一版做成「一次只显示一栏」，用户纠正应当是新页面覆盖老页面并带动画，
于是重做为覆盖式：
- NarrowStack：底层列表始终挂载，详情绝对定位盖在上面。两个好处 ——
列表滚动位置与选中态天然保留；退出动画有东西可播（直接卸载再渲染另一个
组件的话，没有任何一帧能让旧页面往右滑出去）
- 因此必须区分「逻辑上是否打开」与「是否还在 DOM 里」：关闭时先播 200ms
滑出，动画结束才卸载
- 入场用双层 requestAnimationFrame：必须让浏览器至少绘制一帧「在右侧之外」
的状态，否则挂载与 translate-x-0 在同一帧内完成，transition 不触发
- 窄屏专属控件用 useIsNarrow() 条件渲染而非 md:hidden —— 后者只是视觉隐藏，
宽屏用户按 Tab 会聚焦到看不见的返回按钮
- 底部导航 + 抽屉侧栏 + env(safe-area-inset-bottom)
## 工作列表卡片视图（Phase 7.1 最后一项）
中间栏可切列表/卡片。列表答「跟谁在聊」，卡片答「在聊什么、进展如何」：
主题 + 最新一封的发件人与摘要 + 往返预算徽标。
- 两种视图共用同一份数据与同一套动作；归档确认框也共用 —— 归档是破坏性操作，
换个视图就换套确认 UI 只会让人对「自己点了什么」更没底
- 预算徽标在「不限」时不显示（对每张卡片都成立的「0/0」是纯噪声）
- 数据一次取回，不让卡片为每条会话再打一次库
## 修掉的缺陷
- GET /me/sessions 一直 500：ListSessionsFor 的 SELECT 加了预算两列却没加进
Scan，列数不匹配。联系人栏一条数据都拉不到，而错误只是「Failed to list sessions」
- GET /sessions/{id} 忘了填充附件：前端会话视图走的是这个端点，于是 Agent
回信里的附件在 UI 上完全不存在（另一个端点填了但没人调用）
- 插件曾完全没在加载：为了可测在 index.js 里 export 了辅助函数与一个 Map，
而 opencode 把入口模块的每一个导出都当成插件工厂逐个检查，多导出一个 Map
就 "Plugin export is not a function"，插件静默失效、邮件全投不进去。
逻辑挪到 lib/relay-dedup.js，并加断言钉住「入口只有 default 导出」
- 同一件事发两封邮件：模型带附件主动回信后，session.idle 又把它最后那段话
自动转了一遍（生产实测 311 与 342 字节各一封）。explicitSends 记录本轮
主动发信，自动转发据此让位；relay_key 幂等管不了这个 —— 那个键保证的是
「同一条消息不转两次」
- SQLite 时间戳只有秒精度：同秒插入的多封邮件排序不确定（实测同秒插 5 封，
顺序由随机 UUID 决定）。「会话里最早那封」（决定联系人身份）与「最后那封」
（决定最新进展）都会取错。NOW() 升到微秒 + mails 的 INSERT 显式传它
（改 schema 默认值只对新库生效，SQLite 没有 ALTER COLUMN）+ 所有
ORDER BY created_at 补 mail_id 兜底
- fillAttachments 从逐封查询改成一次 IN(...)：原来是 N+1，200 封的会话打开
要打 200 次库
- repo 层 5 处 rows.Next() 循环补 rows.Err()：没有它，读到一半连接断掉会
静默返回部分结果，UI 上表现为「邮件凭空少了几封」
- go:embed 占位页改名 placeholder.html：叫 index.html 会被 Vite 产物覆盖并
提交进去，而它引用的 assets/ 是被忽略的 —— 新克隆打开是白屏
## 回复/转发栏
- 两处都加抄送（可折叠）；原邮件带抄送时多一个「回复全部」，回填用
cc_list[].raw 而非重拼 name@path（后者会丢掉会话段）
- 会话视图每张卡片加转发入口：转发之前只存在于单封邮件视图，而人多数时间
待在会话视图里，等于功能在 UI 上找不到
- ReplyBar 的错误从 console.error 改为显示出来：预算耗尽、地址不存在、
速率限制都走这条路，之前点发送毫无反应
## 测试
- repo: 列顺序（三个 SQL 分支）、卡片字段、previewRunes 边界、时间戳亚秒精度、
批量附件查询、速率限制（80 goroutine 断言恰好 20 条通过）
- web: 窄屏布局 16 条结构性断言（覆盖而非分栏、延迟卸载、双层 rAF、
条件渲染而非 md:hidden）
- 插件: 自动转发去重 17 条（含「入口只有 default 导出」不变量）
- install.sh 把插件测试也纳入部署前门禁
255 lines
11 KiB
Markdown
255 lines
11 KiB
Markdown
# 邮件驱动·多智能体协作平台 (AgentMail)
|
||
|
||
> 以「邮件交互」为统一范式的多 Agent 调度系统
|
||
|
||
人给 Agent 发邮件派活，Agent 之间互相发邮件协作，需要人拍板时发一封「权限请求」邮件等回复。
|
||
所有交互都是邮件，所以协作过程天然可读、可追溯、可归档。
|
||
|
||
## 核心概念：三维寻址
|
||
|
||
收件人地址形如 `name@path.session`：
|
||
|
||
| 地址 | 含义 |
|
||
|------|------|
|
||
| `pi@root` | 投递到 `pi` 在 `root` 工作区的**默认会话**（从未通信过则建立） |
|
||
| `pi@root.new` | **强制新建**一个会话 |
|
||
| `pi@root.fix-leak` | 投递到别名为 `fix-leak` 的**已有会话**；不存在则报「无法送达」，不会静默新建 |
|
||
| `jianf@.new` | 人类用户也是 name 位的一等公民（path 可空） |
|
||
|
||
`path` 内可以含 `/` 和 `.`，解析时按**最后一个 `.`** 切分 session 位。
|
||
|
||
会话别名负责寻址，因此全局唯一。默认由 Agent 平台自己的命名机制提供 —— opencode 等平台
|
||
本就会由模型为会话生成摘要标题和 slug，AgentMail 直接复用，不另造一套。
|
||
|
||
## 快速开始
|
||
|
||
### 开发
|
||
|
||
```bash
|
||
# 后端：默认用内置 SQLite，无需任何外部依赖
|
||
cd gateway
|
||
ADMIN_USER=admin ADMIN_PASSWORD=你的密码 go run ./cmd/server
|
||
# → http://localhost:8180
|
||
|
||
# 前端（另开一个终端）
|
||
cd web
|
||
npm install
|
||
npm run dev # → http://localhost:5173，自动代理到 8180
|
||
```
|
||
|
||
### 部署
|
||
|
||
```bash
|
||
sudo ./deploy/install.sh
|
||
```
|
||
|
||
该脚本装依赖 → 跑类型检查与测试 → 构建前端 → 嵌入后端 → 构建二进制 → 装成 systemd 服务。
|
||
产物是**一个二进制加一个 .db 文件**：前端经 `go:embed` 打进二进制，数据库默认是 SQLite。
|
||
首次运行会在 `/etc/agentmail/gateway.env` 生成随机管理员密码。
|
||
|
||
### 构建期依赖
|
||
|
||
npm 只在构建期用到：Node ≥ 18（`npm run build`）与 Go ≥ 1.22。
|
||
`web/dist` 会被复制进 `gateway/internal/static/static/` 再由 `go:embed` 编入二进制，
|
||
**部署机上不需要 node**。
|
||
|
||
`web/node_modules`、`web/dist`、`gateway/internal/static/static/` 的内容与编译出的二进制
|
||
都是构建产物，不进版本库（见 `.gitignore`）。
|
||
|
||
新克隆**可以直接 `go build` / `go test`**：`static/` 目录里留了一个占位 index.html
|
||
（`go:embed` 要求目标目录存在，否则编译失败——只改后端的人不该被迫先装 node）。
|
||
此时打开网页看到的是「前端未构建」提示页，API 照常可用。要真正的界面就跑
|
||
`deploy/install.sh`，或手工：
|
||
|
||
```bash
|
||
cd web && npm ci && npm run build
|
||
rm -rf ../gateway/internal/static/static && cp -r dist ../gateway/internal/static/static
|
||
cd ../gateway && go build ./cmd/server
|
||
```
|
||
|
||
### 数据库
|
||
|
||
默认 SQLite，落在 `$AGENTMAIL_DATA_DIR/agentmail.db`（默认 `./data/`）。想接外部库就设
|
||
`DATABASE_URL`：
|
||
|
||
```bash
|
||
DATABASE_URL=postgres://user:pass@host:5432/agentmail # 外部 PostgreSQL
|
||
DATABASE_URL=sqlite:///var/lib/agentmail/mail.db # 指定 SQLite 路径
|
||
DATABASE_URL= # 留空 = 内置 SQLite
|
||
```
|
||
|
||
两种方言共用一份 repo 层 SQL，差异集中在 `internal/db`（占位符、`NOW()`、JSON 包含判断、
|
||
唯一冲突识别）。SQLite 开了 WAL，读写不互斥。
|
||
|
||
### 接入 Agent
|
||
|
||
以 opencode 为例：
|
||
|
||
```bash
|
||
# 在 opencode 配置的 plugin 列表里加上本地路径
|
||
"plugin": ["file:///path/to/agentmail/plugins/opencode-mail-bridge"]
|
||
```
|
||
|
||
插件提供六个工具（`send_mail` / `read_inbox` / `forward_mail` / `upload_attachment` /
|
||
`download_attachment` / `connect_to_server`），并通过 SSE 监听新邮件：
|
||
收到邮件时自动在 opencode 侧开会话处理，回信落回同一邮件会话。
|
||
|
||
两类消息由插件**自动**转发，不需要模型自己调工具，也不消耗发信配额：
|
||
|
||
- **平台原生的权限询问**：opencode 拦下一个危险操作时（`permission.ask`），
|
||
插件把它转成邮件问人，人在网页上点「同意/一直同意/拒绝」，插件再回复 opencode 让它继续。
|
||
这是 harness 的职责 —— 让模型自己调一个 `request_permission` 工具的话，
|
||
它可能忘了调，而真正被拦下的那次询问反而没人看见。
|
||
- **本轮的最终总结**：一轮跑完（`session.idle`）时把最后那段话作为回信发回去。
|
||
模型已经把话说完了，插件只是搬运。
|
||
|
||
配额约束的是**模型的自主发信**，不是 harness 的转发 —— 否则配额用尽时 Agent 连交代都做不了。
|
||
|
||
`read_inbox` 读完会自动把本次列出的邮件标为已读，所以下次拉收件箱只会看到新来的。
|
||
|
||
**首次接入**：插件启动时在 `~/.agentmail/agent.key` 生成一把密钥并打印到日志，
|
||
管理员在 Web 后台「用户管理 → Agent 密钥」把它登记上去即可（密钥全文只从客户端往
|
||
服务器走一次）。也可以反过来：先在后台签发，再把密钥填进 `AGENTMAIL_AGENT_KEY`。
|
||
|
||
密钥分两类，权限边界不同：
|
||
|
||
| | 签发方 | 用途 | 不能做什么 |
|
||
|---|---|---|---|
|
||
| Agent 密钥 | 管理员 | 注册、收发邮件、订阅 SSE | 读不了人类邮箱 |
|
||
| 用户密钥 | 用户自助 | 第三方客户端访问自己的邮箱 | 注册不了 Agent |
|
||
|
||
三种生命周期：`permanent`（长期）/ `one_time`（首次使用后失效）/ `timed`（限时）。
|
||
|
||
环境变量见 `deploy/install.sh` 生成的 `/etc/agentmail/opencode.env`。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
agentmail/
|
||
├── docs/
|
||
│ ├── PLAN.md # 分阶段实施计划
|
||
│ └── MVP-SPEC.md # MVP 技术规格书
|
||
├── gateway/ # 后端（Go，单二进制）
|
||
│ ├── cmd/server/ # 入口与路由表
|
||
│ └── internal/
|
||
│ ├── db/ # 连接 + 方言适配 + 内嵌迁移
|
||
│ ├── models/ # 三维地址解析、领域模型
|
||
│ ├── repo/ # 数据访问
|
||
│ ├── handler/ # HTTP 处理
|
||
│ ├── middleware/ # Agent / 用户双认证
|
||
│ ├── sse/ # 事件推送（按收件人分流）
|
||
│ └── static/ # go:embed 的前端产物
|
||
├── plugins/
|
||
│ └── opencode-mail-bridge/ # opencode 桥接插件
|
||
├── web/ # 前端（React + Vite + Tailwind）
|
||
└── deploy/ # systemd 单元 + 安装脚本
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 技术 |
|
||
|------|------|
|
||
| 后端 | Go + chi |
|
||
| 数据库 | SQLite（默认，零依赖）/ PostgreSQL（可选） |
|
||
| 前端 | React 18 + TypeScript + Vite + TailwindCSS |
|
||
| 通信 | HTTP REST + SSE |
|
||
| 认证 | 人类 bcrypt + Cookie；密钥认证（Agent / 用户两类，Bearer） |
|
||
| 附件 | 内容寻址磁盘存储（sha256），元数据入库 |
|
||
| 对话树 | parent_mail_id 递归 CTE，按方向分块加载 |
|
||
| 部署 | 单二进制 + SQLite 文件，systemd 托管 |
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
cd gateway && go build ./... && go test ./... # 后端
|
||
cd web && npm run typecheck && npm test # 前端（含 Markdown XSS 回归测试）
|
||
```
|
||
|
||
## WebAPI
|
||
|
||
WebUI 调用的就是这套公开 API，没有「仅前端可用」的私有通道 —— 第三方客户端拿一把用户密钥
|
||
即可获得与网页完全相同的能力：
|
||
|
||
```bash
|
||
# 在网页「账号 → 客户端连接密钥」创建密钥，然后
|
||
curl {host}/api/v1/me/mail/inbox -H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
`src/api/` 本身就是可复用的客户端 SDK，基地址与凭证集中在 `src/api/config.ts`，
|
||
同一份构建产物可通过 `window.__AGENTMAIL_API_BASE__` 指向不同后端。
|
||
|
||
完整接口见 [WebAPI 文档](docs/API.md)。
|
||
|
||
## 工作列表卡片视图
|
||
|
||
中间栏可在**列表**与**卡片**之间切换（右上角图标，偏好存 localStorage）。
|
||
分工：列表答「跟谁在聊」，卡片答「在聊什么、进展如何」——
|
||
卡片显示会话主题、最新一封的发件人与摘要、往返预算徽标。
|
||
|
||
预算徽标在「不限」时不显示（一个对每张卡片都成立的「0/0」是纯噪声），
|
||
剩 1 个来回转橙、用尽转红 —— 那是需要人介入的时刻。
|
||
|
||
## 窄屏适配
|
||
|
||
小于 768px 时布局从三栏切成**页面覆盖**：列表铺满整屏，点开邮件后详情页从右侧滑入盖在它上面，
|
||
返回时滑出。底层列表始终挂载 —— 滚动位置与选中态因此天然保留，退出动画也才有东西可播
|
||
（直接卸载再渲染另一个组件的话，没有任何一帧能让旧页面往右滑出去）。
|
||
|
||
左侧导航竖条在窄屏退化为抽屉，日常切换交给底部导航（拇指够得到），
|
||
并留了 `env(safe-area-inset-bottom)` 避开 iPhone 手势条。
|
||
|
||
窄屏专属控件（返回按钮、抽屉入口）用 `useIsNarrow()` 条件渲染而不是 `md:hidden` ——
|
||
后者只是视觉隐藏，宽屏用户按 Tab 会聚焦到一个看不见的按钮上。
|
||
动画尊重 `prefers-reduced-motion`。
|
||
|
||
## 往返预算
|
||
|
||
配额的语义是「这件事值得多少个来回」—— 那是**任务**的属性，不是 Agent 的属性。
|
||
所以预算落在会话上：
|
||
|
||
- 新建邮件时填「往返预算」，留空则用**收件 Agent 的默认值**
|
||
- 对话页头部点预算徽标即可改上限，或把已用次数归零 ——
|
||
人看着往来内容才知道这件事还值不值得再来几个回合
|
||
- 管理员页按 Agent 配默认值（默认 20）：跑测试的小工具与重构整个模块的 Agent，
|
||
合理来回数差一个量级
|
||
|
||
没有「Agent 终身额度」这一层。那种额度跑满后要管理员手工重置才能再干活，
|
||
而 Agent 是长期在线的 —— 它是把一次性资源的模型套在长期服务上。
|
||
Agent 用 `.new` 开一串新会话绕过预算，靠**新建会话速率限制**堵
|
||
（1 小时 20 条，超出 429，过一个窗口自动恢复；人类不受此限）。
|
||
|
||
插件自动转发的权限询问与最终总结**不占预算**：配额约束的是模型的自主发信，
|
||
不是 harness 的搬运。
|
||
|
||
## 会话别名
|
||
|
||
会话别名是寻址的第三维（`name@path.别名`）。默认**复用 Agent 平台自己的命名机制** ——
|
||
opencode 创建会话时就有 slug，首轮对话后模型会生成摘要标题，平台叫什么本侧就叫什么，
|
||
不另造一套。
|
||
|
||
Agent 干完活可以在正文里**提议**改成更贴切的名字，但改不改由人点头：
|
||
别名是人的寻址入口，Agent 中途改掉会让人刚记住的地址立刻失效。
|
||
|
||
## 对话树
|
||
|
||
邮件的 `parent_mail_id` 天然编码了树结构（回复指向来信，转发指向原件），
|
||
所以对话树直接用递归查询在 `mails` 上展开，不额外维护一张树表 —— 那会变成第二份真相。
|
||
|
||
树可以跨会话：转发把线索引到新会话，却仍属同一条线索。邮件详情页点「对话树」查看，
|
||
首屏只加载当前屏幕附近的节点，上滑逐步补齐更早的往来。
|
||
|
||
## 附件
|
||
|
||
支持给邮件附加文件。上传与发信是两步：先 `POST /me/attachments` 拿 `attachment_id`，
|
||
再在发信时放进 `attachment_ids`。
|
||
|
||
内容按 sha256 内容寻址存磁盘（数据库只存元数据），同内容重复上传不占额外空间；
|
||
下载一律强制 `octet-stream` + `attachment`，绝不按声明的 MIME 内联渲染。
|
||
单个默认上限 25MB，未随邮件发出的附件 24 小时后自动清理。
|
||
|
||
## 文档
|
||
|
||
- [WebAPI](docs/API.md) — 接口清单、认证方式、错误约定
|
||
- [实施计划](docs/PLAN.md) — 分阶段任务与验收标准
|
||
- [MVP 技术规格书](docs/MVP-SPEC.md) — 数据模型与接口细节
|