1831 lines
105 KiB
Markdown
1831 lines
105 KiB
Markdown
# AgentMail 实施计划
|
||
|
||
> 邮件驱动·多智能体协作平台 — Go 后端 + React 前端 + Pi 插件
|
||
> 版本：v0.1 | 日期：2026-09-01
|
||
|
||
---
|
||
|
||
## 总览
|
||
|
||
```
|
||
Phase 1 (Week 1-2) 后端核心 — Go Gateway + SQLite（默认）/PostgreSQL（可选）+ SSE
|
||
Phase 2 (Week 2-3) Pi Agent 插件 — 两个工具 + 三个钩子拦截器 + SSE 监听
|
||
Phase 3 (Week 3-4) 前端 — React 三栏 UI + 三段式补全 + 权限卡片
|
||
Phase 4 (Week 4) 多用户与鉴权 — 人类多账号 + 会话隔离 + 登录页
|
||
Phase 5 (Week 5) 联调 + 部署 — 端到端闭环 + Docker + 公网反代
|
||
Phase 6 (Week 6+) 进阶功能 — 对话树 / 转发 / 配额 / DSH 插件
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 1：后端核心（Go Gateway）
|
||
|
||
### 1.1 项目初始化 ✅
|
||
|
||
- [x] 创建项目目录 `server/`
|
||
- [x] `go mod init github.com/agentmail/gateway`
|
||
- [x] 目录结构规划：
|
||
|
||
```
|
||
server/
|
||
├── cmd/
|
||
│ └── server/
|
||
│ └── main.go # 入口，启动 HTTP 服务
|
||
├── internal/
|
||
│ ├── config/
|
||
│ │ └── config.go # 环境变量配置
|
||
│ ├── db/
|
||
│ │ ├── db.go # 连接池
|
||
│ │ ├── migrate.go # 迁移执行
|
||
│ │ └── migrations/
|
||
│ │ └── init.sql # 建表 SQL
|
||
│ ├── models/
|
||
│ │ └── models.go # 数据结构
|
||
│ ├── repo/
|
||
│ │ └── repo.go # 数据库操作层
|
||
│ ├── sse/
|
||
│ │ └── manager.go # SSE 连接管理
|
||
│ └── middleware/
|
||
│ └── auth.go # Agent 认证中间件
|
||
├── go.mod
|
||
├── go.sum
|
||
├── Dockerfile
|
||
└── Makefile
|
||
```
|
||
|
||
### 1.2 配置管理
|
||
|
||
- [x] `internal/config/config.go`
|
||
- 数据库连接串、端口、CORS 配置等
|
||
- 从环境变量读取，提供默认值
|
||
- 结构体单例 + `Load()` 函数
|
||
|
||
### 1.3 数据库层
|
||
|
||
- [x] `internal/db/db.go` — database/sql 连接 + 方言适配（SQLite 默认 / PostgreSQL 可选）
|
||
- [x] `internal/db/migrate.go` — embed SQL + 按方言执行迁移
|
||
- [x] `internal/db/migrations/init.sql` + `init_sqlite.sql` — 6 张表
|
||
（users/user_sessions/agents/sessions/mails/permission_requests）
|
||
- [x] `internal/repo/repo.go` — 全部数据库操作函数（方言差异走 db.CCHas / db.JSONCast）
|
||
|
||
**repo 函数清单：**
|
||
|
||
| 函数 | 用途 |
|
||
|------|------|
|
||
| `CreateOrUpdateAgent` | 注册/更新 Agent |
|
||
| `VerifyAgent` | 验证 Agent 名+密钥 |
|
||
| `HeartbeatAgent` | 更新心跳 + 返回未读数 |
|
||
| `ListAgents` | 列出 Agent（@补全用） |
|
||
| `CreateSession` | 创建新会话 |
|
||
| `GetSessionByID` | 查会话详情 |
|
||
| `ListSessions` | 列出会话 |
|
||
| `TouchSession` | 更新会话时间戳 |
|
||
| `UpdateSessionAlias` | 更新会话别名（校验唯一 + 保留字 new + 禁含 . / @ 空白） |
|
||
| `FindSessionByAlias` | 按别名查会话（唯一命名空间） |
|
||
| `FindNamedSessionFor` | 按 name@path.<别名> 严格寻址；不存在 → 无法送达 |
|
||
| `FindOrCreateDefaultSession` | session 位省略时的默认会话（复用最近活跃，无则建） |
|
||
| `SyncSessionAlias` | 回写平台侧 slug 为本侧别名，撞名自动追加 -2/-3 |
|
||
| `SyncSessionTitle` | 回写平台侧模型生成的摘要标题 |
|
||
| `AgentCanAccessSession` | Agent 只能同步自己参与过的会话 |
|
||
| `CreateMail` | 创建普通邮件 |
|
||
| `CreatePermissionMail` | 创建权限请求邮件 |
|
||
| `CreateDecisionMail` | 创建人类决策邮件 |
|
||
| `GetMailByID` | 查邮件详情 |
|
||
| `ListInbox` | 查收件箱 |
|
||
| `MarkMailRead` | 标记已读 |
|
||
| `CountUnread` | 统计未读数 |
|
||
| `GetSessionMails` | 查会话全部邮件 |
|
||
| `CreatePermissionRequest` | 创建权限请求记录 |
|
||
| `DecidePermission` | 执行权限决策 |
|
||
| `ListPendingPermissions` | 列出待决权限 |
|
||
| `GetPermissionByMailID` | 按邮件查权限请求 |
|
||
|
||
### 1.4 SSE 连接管理
|
||
|
||
- [x] `internal/sse/manager.go`
|
||
|
||
**功能：**
|
||
- 管理所有 SSE 客户端连接（Agent 侧 + 前端）
|
||
- 按 `agentName` 路由推送（Agent 只收自己的邮件通知，前端收所有）
|
||
- 心跳保活（每 30s 发 `: heartbeat`）
|
||
- 客户端断开自动清理
|
||
|
||
**数据结构：**
|
||
```go
|
||
type Client struct {
|
||
ID string
|
||
AgentName string // 空 = 前端客户端
|
||
Res http.ResponseWriter
|
||
Flusher http.Flusher
|
||
}
|
||
|
||
type Manager struct {
|
||
mu sync.RWMutex
|
||
clients map[string]*Client
|
||
}
|
||
```
|
||
|
||
**方法：**
|
||
- `AddClient(id, agentName, res, flusher)`
|
||
- `RemoveClient(id)`
|
||
- `SendToAgent(agentName, eventType, data)`
|
||
- `SendToFrontend(eventType, data)`
|
||
- `Broadcast(eventType, data)`
|
||
- `ClientCount() int`
|
||
|
||
### 1.5 中间件
|
||
|
||
- [x] `internal/middleware/auth.go`
|
||
|
||
**逻辑：**
|
||
1. 从 header 读 `X-Agent-Name` + `X-Agent-Secret`
|
||
2. 调 `repo.VerifyAgent` 验证
|
||
3. 验证通过 → 更新 `last_seen`，把 `agentName` 注入 context
|
||
4. 失败 → 返回 401
|
||
|
||
**注意：** 这个中间件只用于 Agent 侧的 API。前端 API 用另一个认证（MVP 阶段可先不实现前端认证）。
|
||
|
||
### 1.6 HTTP 路由
|
||
|
||
- [x] `cmd/server/main.go`
|
||
|
||
**路由表：**
|
||
|
||
```
|
||
GET /health → 健康检查
|
||
POST /api/v1/agent/register → Agent 注册
|
||
POST /api/v1/agent/heartbeat → Agent 心跳（需认证）
|
||
GET /api/v1/agents → 在线 Agent 列表
|
||
|
||
POST /api/v1/mail/send → 发送邮件（需认证）
|
||
GET /api/v1/mail/inbox → 收件箱（需认证）
|
||
GET /api/v1/mail/:id → 邮件详情（需认证）
|
||
POST /api/v1/mail/:id/read → 标记已读（需认证）
|
||
|
||
POST /api/v1/permission/request → Agent 请求权限（需认证）
|
||
POST /api/v1/permission/decide → 人类决策（无需认证）
|
||
GET /api/v1/permission/pending → 待决权限列表（无需认证）
|
||
|
||
GET /api/v1/sessions → 会话列表
|
||
GET /api/v1/sessions/:id → 会话详情 + 邮件
|
||
GET /api/v1/sessions/:id/mails → 会话内邮件列表
|
||
PUT /api/v1/sessions/:id/alias → 更新会话别名（人类显式命名）
|
||
POST /api/v1/sessions/:id/sync → Agent 回写平台侧生成的标题/slug（需 Agent 认证）
|
||
|
||
POST /api/v1/admin/agent-keys → 签发/登记 Agent 接入密钥（管理员）
|
||
GET /api/v1/admin/agent-keys → Agent 密钥列表（只给 token_hint）
|
||
DELETE /api/v1/admin/agent-keys/{id} → 吊销
|
||
POST /api/v1/admin/agent-keys/{id}/bind → 绑定到 Agent
|
||
|
||
POST /api/v1/me/keys → 签发客户端连接密钥（用户自助）
|
||
GET /api/v1/me/keys → 我的密钥列表
|
||
DELETE /api/v1/me/keys/{id} → 吊销
|
||
|
||
GET /api/v1/events/stream → SSE 端点
|
||
GET /api/v1/events/status → SSE 连接状态
|
||
```
|
||
|
||
**实现顺序：**
|
||
1. 健康检查 + 静态路由
|
||
2. Agent 注册/心跳
|
||
3. 邮件发送/收件箱
|
||
4. 权限请求/决策
|
||
5. 会话管理
|
||
6. SSE 端点
|
||
|
||
### 1.7 Go 编译验证
|
||
|
||
- [x] `go build ./cmd/server` 编译通过
|
||
- [x] 启动服务（默认内置 SQLite，无需外部依赖）
|
||
- [x] curl 手动测试每个 API 端点
|
||
|
||
### 1.8 数据库后端：SQLite 默认 + 外部库可选
|
||
|
||
**决策**：默认 SQLite，`DATABASE_URL` 非空时切外部 PostgreSQL。
|
||
前端已 go:embed 进二进制，数据库再挂 Docker 就自相矛盾；部署产物应当是「一个二进制 + 一个 .db」。
|
||
|
||
- [x] `internal/db` 收拢方言差异，repo 层只写一份 SQL：
|
||
- 占位符：SQLite 也支持 `$1/$2`，无需改写
|
||
- `NOW()` / `gen_random_uuid()`：SQLite 侧注册同名函数补齐
|
||
- JSON 包含判断：`db.CCHas(col, argN)` —— PG 用 `jsonb_build_array`，SQLite 用 `json_each`
|
||
- 唯一冲突：`db.IsUniqueViolation` 同时识别 PG `23505` 与 SQLite `2067/1555`
|
||
- `JOIN LATERAL`：SQLite 无此语法，联系人聚合改用关联子查询
|
||
- [x] 两份 schema：`migrations/init.sql`（PG）与 `migrations/init_sqlite.sql`
|
||
- [x] `DATABASE_URL` 识别 `postgres://`、`sqlite://`、`file:`、裸 `.db` 路径；空值 = 内置 SQLite
|
||
- [x] SQLite 连接开 `WAL` + `busy_timeout=5000` + `foreign_keys=ON`，连接池限 1（单写者）
|
||
- [x] 删除 `docker-compose.yml` 与重复的 `server/migrations/`
|
||
|
||
### 1.9 部署：systemd 单元
|
||
|
||
- [x] `deploy/agentmail-gateway.service` — 含 `ProtectSystem=strict` 与 `ReadWritePaths=data/`
|
||
- [x] `deploy/opencode-serve.service` — 托管 opencode headless（mail-bridge 宿主）
|
||
- [x] `deploy/install.sh` — 构建前端 → 嵌入 → 装服务；首装生成随机管理员密码与 Agent secret
|
||
- [x] `OPENCODE_SERVER_PASSWORD` 由安装脚本随机生成（此前裸奔，同机任何进程都能开会话）
|
||
|
||
---
|
||
|
||
## Phase 2：Agent 邮件桥接插件
|
||
|
||
> 计划书原本按 Pi Agent 设计，**实际第一个接入的平台是 opencode**（`plugins/opencode-mail-bridge/`）。
|
||
> 结构也从「按文件拆 tools/transport/hooks」收敛为单文件 `index.js` ——
|
||
> opencode 的插件契约是一个默认导出函数返回 hooks 对象，拆成多文件只会增加跳转成本而无收益。
|
||
|
||
### 2.1 插件结构（已落地）
|
||
|
||
```
|
||
plugins/opencode-mail-bridge/
|
||
├── package.json
|
||
└── index.js # 凭证层 + HTTP + SSE + 四个工具 + event 钩子
|
||
```
|
||
|
||
- [x] 单文件实现，无需 transport/tools 分层
|
||
- [x] 凭证层：密钥优先级 `AGENTMAIL_AGENT_KEY` > `~/.agentmail/agent.key` > 旧 secret > 本地生成
|
||
|
||
### 2.2 HTTP 传输层（已落地）
|
||
|
||
- [x] `apiGet` / `apiPost` 封装 `fetch`，认证头由 `authHeaders()` 统一给出
|
||
（有密钥走 `Authorization: Bearer`，否则退回 `X-Agent-Name` + `X-Agent-Secret`）
|
||
- [x] 错误处理：非 2xx 抛出服务端 `error` 文案，调用方能看到「密钥无效」这类可操作信息
|
||
|
||
### 2.3 SSE 客户端（已落地）
|
||
|
||
- [x] 用 `fetch` + `ReadableStream` 手工解析 SSE 帧（Node 原生 EventSource 不支持自定义请求头，
|
||
而认证头是必需的）
|
||
- [x] 连接 `/api/v1/events/stream`；断流 3s、出错 5s 后重连；`AbortController` 支持优雅停止
|
||
- [x] 事件分发：`new_mail` / `permission_decision` → `deliverMail()`
|
||
|
||
### 2.4 工具实现（已落地，四个）
|
||
|
||
- [x] `send_mail` — 参数 `to` / `subject` / `body` / `cc?` / `reply_to?` / `session_alias?`；
|
||
地址解析在网关侧完成（三维寻址是网关的职责，插件不该各自实现一份解析）
|
||
- [x] `read_inbox` — 参数 `filter?`（unread/all）/ `limit?`；返回带预览的列表
|
||
- [x] `request_permission` — 参数 `question` / `options?` / `context?`
|
||
- [x] `connect_to_server` — 参数 `gateway_url?` / `key_token?`；登记密钥并完成注册，
|
||
失败时直接把待登记的密钥全文打出来，省一轮来回
|
||
|
||
**与原计划的偏差**：原设想「权限请求 / 提问 / 最终总结」三种行为由钩子自动拦截，
|
||
Agent 不需要手动调工具。opencode 的插件契约没有提供拦截这三类行为的钩子
|
||
（`chat.message` 只能观察不能冻结会话），因此改为：
|
||
`request_permission` 作为显式工具暴露给 Agent；「提问」与「最终总结」由 Agent 自行用
|
||
`send_mail` 表达。这不影响协作语义 —— 邮件本身就是提问与总结的载体。
|
||
|
||
### 2.5 插件入口（已落地）
|
||
|
||
- [x] 启动时读凭证 → `POST /agent/register` → 启动 SSE → 30s 心跳定时器
|
||
- [x] `new_mail` 事件：**不注入正文**，只给发件人/主题/mail_id 与「先调 read_inbox」的指示；
|
||
按 `session_id` 查 `sessionMap` 决定续谈已有 opencode 会话还是新开一个
|
||
（网关已按 session 位判好复用/新建，插件只忠实映射）
|
||
- [x] `permission_decision` 事件：把决策结论作为新一轮 prompt 投给对应会话
|
||
- [x] `session.updated` 钩子：把 opencode 侧模型生成的会话标题与 slug 回写为 AgentMail 的会话命名
|
||
|
||
### 2.6 测试（已实测）
|
||
|
||
- [x] 工具注册：四个工具出现在模型的工具列表中（用 `llmsproxy/AUTO` 实测）
|
||
- [x] 端到端收发：人 → Agent → 人 回信闭环，`reply_to` 使回信落回同一会话
|
||
- [x] 会话记忆：第一封「记住 42」→ 第二封（省略 session 位）问「刚才的数字」→ 回「42」，
|
||
证明续谈映射正确
|
||
- [x] 密钥流程：首装本地生成（0600）→ 管理员登记 → 重启注册成功 → 收发邮件与 SSE 全通
|
||
- [x] 权限闭环：`request_permission` → `/permission/pending` 可查 → 人类决策 → 插件收到并开会话
|
||
|
||
**排查记录（两个真实缺陷）**：
|
||
1. 「工具没注册」是假象 —— opencode 免费模型限流后连工具清单都不吐；换 `llmsproxy/AUTO` 后正常。
|
||
顺带修了 provider 配置里 `baseURL` 缺 `//` 的拼写错误。
|
||
2. 「发邮件没回复」是真 bug —— SSE 回调调的 `client.session.message.send(...)` 在 opencode SDK 里
|
||
**不存在**（`session.message` 是读消息的 getter），Promise reject 又被空 `.catch(() => {})` 吞掉，
|
||
于是邮件到了、SSE 收到了、却没建任何会话也没报错。
|
||
正确 API 是 `session.create` + `session.promptAsync`。**教训：跨 SDK 调用不要写空 catch。**
|
||
|
||
---
|
||
|
||
## Phase 3：前端（React）
|
||
|
||
> 实际实现比原计划**收敛**：组件拆分粒度更粗（MailItem/MailBody/ReplyEditor/PermissionCard
|
||
> 都并入了 MailView，因为它们只在这一处使用，独立文件只增加跳转成本），
|
||
> 且「新建邮件」按用户要求做成右侧整页而非弹窗。
|
||
|
||
### 3.1 项目初始化
|
||
|
||
- [x] `client/electron/` 目录，Vite + React + TypeScript + TailwindCSS
|
||
|
||
### 3.2 目录结构（已落地）
|
||
|
||
```
|
||
client/electron/src/
|
||
├── api/ client.ts（HTTP）/ sse.ts（EventSource + 指数退避重连）
|
||
├── stores/ mail / session / contact / ui / auth（Zustand）
|
||
├── components/ Sidebar / MailList / MailView / ComposePage / ContactPanel
|
||
│ AddressInput / LoginPage / SetupPage / AccountPage
|
||
│ AdminUsersPage / KeyPanel / icons
|
||
├── types/index.ts
|
||
└── App.tsx
|
||
```
|
||
|
||
### 3.3 类型定义
|
||
|
||
- [x] `types/index.ts` — Mail / Session / Contact / User / Agent / AdminScopes 等
|
||
|
||
### 3.4 API 客户端
|
||
|
||
- [x] `api/client.ts` — 统一 `request()`，`credentials: 'include'`，401 统一跳登录；
|
||
覆盖邮件/会话/联系人/权限/用户管理/密钥全部端点
|
||
|
||
### 3.5 SSE
|
||
|
||
- [x] `api/sse.ts` — 单例 EventSource + 多订阅者；断线指数退避 1s→15s 上限
|
||
（没有单独做 `useSSE` hook：订阅者是 store 而非组件，hook 反而多一层）
|
||
|
||
### 3.6 状态管理
|
||
|
||
- [x] `stores/mailStore.ts` / `sessionStore.ts` / `contactStore.ts` / `uiStore.ts` / `authStore.ts`
|
||
|
||
### 3.7 核心组件（已落地）
|
||
|
||
- [x] **App.tsx** — 三栏容器：60px 图标栏 / 320px 列表 / 右侧自适应（替代原计划的 Layout.tsx）
|
||
- [x] **Sidebar.tsx** — 图标栏（收件/发件/联系人 + 新建 + 账号/管理员入口 + 退出），**纯 SVG 无 emoji**
|
||
- [x] **MailList.tsx** — 邮件列表，未读蓝色粗体、权限橙色标签、CC 标记
|
||
- [x] **MailView.tsx** — 邮件正文（react-markdown）+ 权限卡片 + 回复区，三者合一
|
||
- [x] **ComposePage.tsx** — 右侧**整页**写信（非弹窗，用户明确要求），含编辑/预览切换、
|
||
会话别名输入（仅地址以 `.new` 结尾时出现）
|
||
- [x] **AddressInput.tsx** — 三段式补全，接 `/contacts/suggest`，支持方向键
|
||
- [x] **ContactPanel.tsx** — 联系人（= 一条 `name@path.session` 三维地址）+ 归档
|
||
- [x] **LoginPage / SetupPage / AccountPage / AdminUsersPage / KeyPanel**
|
||
- [x] **icons.tsx** — 20+ 纯 SVG 图标，全站零 emoji
|
||
|
||
### 3.8 样式
|
||
|
||
- [x] TailwindCSS 配置
|
||
- [x] 浅色主题（深色留待后续）
|
||
- [x] 列表 hover/selected 状态
|
||
- [x] 权限请求卡片橙色高亮
|
||
- [x] 未读蓝色粗体
|
||
- [x] 加载/空状态
|
||
|
||
### 3.9 开发环境
|
||
|
||
- [x] Vite proxy：`/api` → `http://localhost:8180`（与 Gateway 默认 PORT 一致）
|
||
- [x] `npm run typecheck`（tsc --noEmit）与 `npm test`（Markdown XSS 回归）
|
||
|
||
---
|
||
|
||
## Phase 4：多用户与鉴权（人类账号体系）
|
||
|
||
> 背景：人类不是单一的 `human`，而是**多用户**，各自账号密码登录，拥有独立收件箱与会话。
|
||
> 寻址上人类用户同样是三维地址的 name 位：`jianf@.new`、`alice@.deploy-review`。
|
||
|
||
### 4.1 数据模型
|
||
|
||
- [x] `users` 表
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS users (
|
||
user_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
username VARCHAR(64) NOT NULL UNIQUE, -- 即寻址的 name 位
|
||
display_name VARCHAR(128) NOT NULL DEFAULT '',
|
||
password_hash VARCHAR(255) NOT NULL, -- bcrypt
|
||
role VARCHAR(16) NOT NULL DEFAULT 'user', -- admin / user
|
||
status VARCHAR(16) NOT NULL DEFAULT 'active', -- active / disabled
|
||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||
last_login TIMESTAMPTZ
|
||
);
|
||
|
||
CREATE TABLE IF NOT EXISTS user_sessions (
|
||
token VARCHAR(64) PRIMARY KEY, -- 随机 token，存 Cookie
|
||
user_id UUID NOT NULL REFERENCES users(user_id) ON DELETE CASCADE,
|
||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||
expires_at TIMESTAMPTZ NOT NULL,
|
||
user_agent VARCHAR(256) DEFAULT ''
|
||
);
|
||
CREATE INDEX IF NOT EXISTS idx_user_sessions_user ON user_sessions(user_id);
|
||
CREATE INDEX IF NOT EXISTS idx_user_sessions_exp ON user_sessions(expires_at);
|
||
```
|
||
|
||
**关键决策**：`username` 与 `agents.agent_name` **共一个命名空间**（注册时互斥校验），
|
||
因为二者都出现在三维地址的 name 位，同名会导致路由歧义。
|
||
|
||
### 4.2 历史数据迁移
|
||
|
||
- [x] 现有邮件里的字面量 `'human'` 迁移到默认管理员账号
|
||
- 创建 `admin` 用户（首次启动时从环境变量 `ADMIN_USER` / `ADMIN_PASSWORD` 读取）
|
||
- `UPDATE mails SET from_name = 'admin' WHERE from_name = 'human'`（to_name 同理）
|
||
- 保留 `human` 作为**兼容别名**：Agent 仍可 `send_mail to="human@"`，网关解析为“当前会话的发起人类用户”
|
||
|
||
### 4.3 认证 API
|
||
|
||
```
|
||
POST /api/v1/auth/login { username, password } → Set-Cookie: am_session
|
||
POST /api/v1/auth/logout → 销毁 token
|
||
GET /api/v1/auth/me → { user_id, username, display_name, role }
|
||
POST /api/v1/auth/password { old_password, new_password }
|
||
```
|
||
|
||
管理员专用：
|
||
|
||
```
|
||
GET /api/v1/admin/users → 用户列表
|
||
POST /api/v1/admin/users { username, password, display_name, role }
|
||
PUT /api/v1/admin/users/{id} { display_name, role, status }
|
||
DELETE /api/v1/admin/users/{id} → 禁用（不物理删除，保留邮件历史）
|
||
POST /api/v1/admin/users/{id}/reset { new_password }
|
||
```
|
||
|
||
- [x] 密码用 `golang.org/x/crypto/bcrypt`，cost 12
|
||
- [x] token 用 `crypto/rand` 32 字节 hex，有效期 7 天，每次请求滞后续期
|
||
- [x] Cookie：`HttpOnly` + `SameSite=Lax` + 生产环境 `Secure`
|
||
- [x] 登录失败限速：同一 username 连续 5 次失败锁 5 分钟（内存计数，MVP 阶段够用）
|
||
|
||
### 4.4 中间件与会话隔离
|
||
|
||
- [x] `middleware.UserAuth` —— 从 Cookie 取 token → 查 `user_sessions` → 注入 `username` 到 context
|
||
- [x] `middleware.AdminOnly` —— 叠在 UserAuth 之后，校验 `role = 'admin'`
|
||
- [x] **所有 `/human/*` 路由改为 `/me/*` 并强制鉴权**，当前写死的 `"human"` 全部换成登录用户名：
|
||
- `HumanGetInbox` → `MeGetInbox`：`ListInbox(ctx, username, ...)`
|
||
- `HumanGetSent` → `MeGetSent`：`ListSentBy(ctx, username, ...)`
|
||
- `HumanSendMail` → `MeSendMail`：from_name = username
|
||
- `ListContacts`、`SuggestAddress`、`ArchiveContact` 同样按当前用户过滤
|
||
- [x] 权限决策 `POST /permission/decide` 鉴权：只有**该会话的参与人类**或 admin 可决策
|
||
- [x] SSE `/events/stream` 鉴权：前端连接按登录用户分流，不再广播给全部前端
|
||
- `sse.Manager` 新增 `UserName` 字段，`SendToUser(username, ...)` 取代 `SendToFrontend`
|
||
|
||
### 4.5 会话归属
|
||
|
||
- [x] `sessions` 表新增 `owner_user_id UUID REFERENCES users(user_id)`
|
||
- [x] 人类发起的会话归属于该用户；Agent 发起的会话归属于它寄信的人类
|
||
- [x] `ListContacts` 只列当前用户参与的会话（owner 或 在 to/cc/from 中出现）
|
||
- [x] 归档鉴权：非 owner 且非 admin 不得归档别人的会话
|
||
|
||
### 4.6 Agent 侧寻址适配
|
||
|
||
- [x] Agent 给人类发信时可写具体用户名：`send_mail to="jianf@.new"`
|
||
- [x] 保留 `human@` 兼容写法 → 解析为当前会话的 owner 用户
|
||
- [x] `SuggestAddress` 的 name 层候选同时包含 **在线 Agent + 已启用人类用户**
|
||
|
||
### 4.7 前端
|
||
|
||
- [x] `LoginPage.tsx` —— 账号密码表单，失败提示，回车提交
|
||
- [x] `authStore.ts` —— `me` / `login` / `logout`；应用启动先拉 `/auth/me` 判断登录态
|
||
- [x] `App.tsx` —— 未登录渲染 `LoginPage`，已登录渲染主界面
|
||
- [x] `api/client.ts` —— 所有请求带 `credentials: 'include'`；401 统一跳登录
|
||
- [x] 侧边栏底部显示当前用户 + 退出按钮（纯 SVG 图标，不用 emoji）
|
||
- [x] 管理员页：用户列表 / 新建 / 禁用 / 重置密码
|
||
|
||
### 4.8 验证
|
||
|
||
- [x] 单测：bcrypt 校验、token 过期、跨用户访问被拒（403）
|
||
- [x] 两个人类账号互不可见对方收件箱与联系人
|
||
- [x] Agent 寄信给 `jianf@.new` 仅 jianf 收到，SSE 不泄露给其他登录会话
|
||
|
||
---
|
||
|
||
## Phase 5：密钥认证体系（Agent-插件-Gateway 鉴权）
|
||
|
||
> 背景：当前 Agent 注册只需 name+secret 明文，无密钥机制，无法安全接入公网。
|
||
> 本 Phase 引入密钥（token）体系，分为两类：**Agent 密钥**（管理员为 Agent 生成，用于注册+通信）
|
||
> 和 **用户密钥**（用户自己生成，仅用于客户端连接 Gateway，不可注册 Agent）。
|
||
> 插件侧首次安装时本地生成密钥对，通过 `connect_to_server` 工具完成握手。
|
||
|
||
### 5.1 数据模型（已落地）
|
||
|
||
> 两方言各一份：`internal/db/migrations/init.sql` 与 `init_sqlite.sql`。
|
||
> 下方 DDL 为 PostgreSQL 方言；SQLite 侧 `UUID→TEXT`、`TIMESTAMPTZ→DATETIME`。
|
||
|
||
#### agent_keys 表（Agent 注册密钥）
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS agent_keys (
|
||
key_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
key_token VARCHAR(128) NOT NULL UNIQUE, -- 密钥令牌（随机 hex）
|
||
agent_name VARCHAR(64), -- 绑定到的 Agent 名（可为空=未绑定）
|
||
key_type VARCHAR(16) NOT NULL, -- permanent / one_time / timed
|
||
expires_at TIMESTAMPTZ, -- timed 类型的过期时间；permanent/one_time 为 NULL
|
||
used_at TIMESTAMPTZ, -- one_time 类型：首次使用时间（已用=失效）
|
||
created_by UUID REFERENCES users(user_id), -- 创建者（管理员）
|
||
created_at TIMESTAMPTZ DEFAULT NOW()
|
||
);
|
||
CREATE INDEX IF NOT EXISTS idx_agent_keys_token ON agent_keys(key_token);
|
||
CREATE INDEX IF NOT EXISTS idx_agent_keys_agent ON agent_keys(agent_name);
|
||
```
|
||
|
||
#### user_keys 表（用户连接密钥）
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS user_keys (
|
||
key_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
key_token VARCHAR(128) NOT NULL UNIQUE,
|
||
user_id UUID NOT NULL REFERENCES users(user_id) ON DELETE CASCADE,
|
||
label VARCHAR(128) NOT NULL DEFAULT '', -- 用户自定义标签（如 "我的笔记本"
|
||
key_type VARCHAR(16) NOT NULL DEFAULT 'permanent', -- permanent / one_time / timed
|
||
expires_at TIMESTAMPTZ,
|
||
used_at TIMESTAMPTZ,
|
||
created_at TIMESTAMPTZ DEFAULT NOW()
|
||
);
|
||
CREATE INDEX IF NOT EXISTS idx_user_keys_user ON user_keys(user_id);
|
||
CREATE INDEX IF NOT EXISTS idx_user_keys_token ON user_keys(key_token);
|
||
```
|
||
|
||
#### 关键约束
|
||
|
||
- `agent_keys.key_token` 与 `user_keys.key_token` 共享一个全局唯一命名空间（验证时先查 agent_keys，再查 user_keys）
|
||
- `user_keys` 的密钥 **不能** 用于 `POST /agent/register`（注册时校验来源表）
|
||
- `agent_keys` 的密钥 **不能** 用于 `/me/*` 人类邮箱接口（agent_auth 中间件与 user_auth 中间件分离）
|
||
|
||
### 5.2 Gateway API
|
||
|
||
#### 管理员：Agent 密钥管理
|
||
|
||
```
|
||
POST /api/v1/admin/agent-keys { agent_name?, key_type, label?, expires_hours?, key_token? }
|
||
GET /api/v1/admin/agent-keys ?agent_name=xxx
|
||
DELETE /api/v1/admin/agent-keys/{id}
|
||
POST /api/v1/admin/agent-keys/{id}/bind { agent_name } -- 绑定到 Agent
|
||
```
|
||
|
||
`key_token` 用于**登记客户端已在本地生成的密钥**（插件首装场景）：这样密钥全文只从客户端
|
||
流向服务器一次，不必反方向传递。留空则由服务器生成（32 字节随机 hex）。
|
||
|
||
密钥类型：
|
||
- `permanent`：永不过期，可重复使用，适合正式部署的 Agent
|
||
- `one_time`：一次性使用，首次验证后标记 `used_at`，再用即 403
|
||
- `timed`：创建时指定 `expires_hours`（如 24h），过期后失效
|
||
|
||
#### 用户：连接密钥管理
|
||
|
||
```
|
||
POST /api/v1/me/keys { label, key_type, expires_hours? }
|
||
GET /api/v1/me/keys → 我的密钥列表（只给 token_hint）
|
||
DELETE /api/v1/me/keys/{id} → 删除密钥（带 user_id 条件，删不到即 404）
|
||
```
|
||
|
||
用户密钥的 `key_type` 同样支持 permanent / one_time / timed，但只能用于 `/me/*` 接口。
|
||
|
||
#### Agent 注册（改用密钥认证）
|
||
|
||
```
|
||
POST /api/v1/agent/register
|
||
Header: Authorization: Bearer <agent_key_token>
|
||
Body: { name, workspaces, platform }
|
||
|
||
→ Gateway 验证密钥：
|
||
1. 查 agent_keys WHERE key_token = token
|
||
2. 不存在 → 401
|
||
3. one_time 类型且 used_at 非空 → 401（已用过）
|
||
4. timed 类型且 expires_at < now() → 401（已过期）
|
||
5. 验证通过 → 更新 used_at（one_time）→ 继续注册逻辑
|
||
```
|
||
|
||
#### Agent 心跳（改用密钥认证）
|
||
|
||
```
|
||
POST /api/v1/agent/heartbeat
|
||
Header: Authorization: Bearer <agent_key_token>
|
||
```
|
||
|
||
#### SSE 连接（改用密钥认证）
|
||
|
||
```
|
||
GET /api/v1/events/stream
|
||
Header: Authorization: Bearer <agent_key_token>
|
||
→ Agent 侧 SSE：密钥验证后绑定到对应 Agent
|
||
→ 前端 SSE：仍用 Cookie 认证（不变）
|
||
```
|
||
|
||
### 5.3 插件侧改动
|
||
|
||
#### 首次安装：本地生成密钥
|
||
|
||
```
|
||
~/.agentmail/
|
||
├── config.json # { "gateway_url": "...", "key_token": "...", "agent_name": "..." }
|
||
└── agent.key # 本地密钥文件（JSON，含 key_token + created_at）
|
||
```
|
||
|
||
插件启动时：
|
||
1. 检查 `~/.agentmail/agent.key` 是否存在
|
||
2. 不存在 → 生成随机 32 字节 hex 作为 `key_token`，写入文件（0600）并打印到 stderr
|
||
3. 存在 → 读取 key_token
|
||
4. 自动调 `/agent/register`；密钥未登记时提示管理员把打印出的密钥填进后台
|
||
|
||
#### connect_to_server 工具
|
||
|
||
```javascript
|
||
args: {
|
||
gateway_url: z.string().describe("Gateway 地址，如 http://mail.example.com:8080"),
|
||
key_token: z.string().optional().describe("密钥令牌（可选，也可从本地配置读取）")
|
||
}
|
||
|
||
execute: {
|
||
1. 读取本地 key_token（参数优先，否则从 ~/.agentmail/agent.key 读取）
|
||
2. 调 POST /api/v1/agent/register（带 Authorization: Bearer key_token）
|
||
3. 将 gateway_url 和 key_token 保存到 ~/.agentmail/config.json
|
||
4. 启动 SSE 监听
|
||
5. 返回连接结果
|
||
}
|
||
```
|
||
|
||
#### 心跳认证改动
|
||
|
||
心跳与所有 Agent 接口统一携带 `Authorization: Bearer <key_token>`。
|
||
旧的 `X-Agent-Name / X-Agent-Secret` **保留兼容**（见 5.7 最后一条）。
|
||
|
||
#### 密钥来源优先级（已落地）
|
||
|
||
1. `AGENTMAIL_AGENT_KEY` 环境变量 —— systemd 部署走这条
|
||
2. `~/.agentmail/agent.key`（`AGENTMAIL_CONFIG_DIR` 可改目录）
|
||
3. 都没有时退回 `AGENTMAIL_AGENT_SECRET` 的旧路径；连 secret 也没有才本地生成新密钥
|
||
|
||
文件权限：`agent.key` 与 `config.json` 均 0600，目录 0700。
|
||
|
||
### 5.4 密钥验证中间件（Gateway，已落地）
|
||
|
||
`middleware.AgentAuth` 同时承担密钥与旧凭证两条路径：
|
||
|
||
```
|
||
有 Authorization: Bearer <token>：
|
||
→ repo.VerifyAgentKey：查 agent_keys
|
||
→ 不存在 → 401 "密钥无效"
|
||
→ one_time 已用 → 401 "密钥已使用（一次性密钥只能用一次）"
|
||
→ timed 已过期 → 401 "密钥已过期"
|
||
→ 通过：one_time 写 used_at（WHERE used_at IS NULL，并发下只有一个请求能标记成功）
|
||
→ agent_name 为空（待绑定）→ 403，提示先调 /agent/register
|
||
→ 注入 agent_name 到 context，刷新 last_seen
|
||
|
||
无 Bearer：走 X-Agent-Name + X-Agent-Secret 旧路径
|
||
```
|
||
|
||
`middleware.UserAuth` 同理支持 Cookie 与 `Bearer <user_key_token>`。两类密钥各查自己的表，
|
||
因此 Agent 密钥读不了人类邮箱，用户密钥也注册不了 Agent。
|
||
|
||
`/agent/register` 不经中间件（注册时 Agent 还没身份），自行取 Bearer 校验：
|
||
密钥已绑定且与请求 name 不符 → 403，防止拿别人的密钥冒充新身份；未绑定则注册成功后落定。
|
||
|
||
### 5.5 管理员前端
|
||
|
||
- [x] 管理员页面拆成「用户管理 / Agent 密钥」两个 tab（`AdminUsersPage.tsx`）
|
||
- [x] 创建密钥：选类型（长期/一次性/限时）+ 可选绑定 Agent + 限时可填小时数
|
||
- [x] **登记客户端已生成的密钥**：插件首装在本地生成密钥并打印，管理员把它填进「登记」框即可，
|
||
密钥全文只从客户端流向服务器一次，不需要反方向传递
|
||
- [x] 密钥列表：只显示 `token_hint`（前 8 位），全文仅在创建响应里出现一次，
|
||
前端用一次性横幅提示「关闭后无法再次查看」
|
||
- [x] 绑定 Agent / 吊销密钥
|
||
|
||
### 5.6 用户前端
|
||
|
||
- [x] 个人中心新增「客户端连接密钥」区（`AccountPage.tsx`，与管理员面板共用 `KeyPanel.tsx`）
|
||
- [x] 创建密钥：填备注 + 选类型；限时可填小时数
|
||
- [x] 密钥列表 + 吊销；状态标注「可用 / 已使用 / 已过期」
|
||
|
||
### 5.7 验证（已实测）
|
||
|
||
- [x] permanent 密钥 → 注册成功，重复使用仍成功
|
||
- [x] one_time 密钥 → 首次成功；再用 401「密钥已使用（一次性密钥只能用一次）」
|
||
- [x] timed 密钥（24h）→ 注册成功；手动把 `expires_at` 改到过去 → 401「密钥已过期」
|
||
- [x] timed 缺 `expires_hours` → 400；非法 key_type → 400
|
||
- [x] 用户密钥 → `/me/mail/send` 正常；→ `/agent/register` 401「密钥无效」
|
||
- [x] Agent 密钥 → `/me/mail/inbox` 401（两类密钥各查自己的表，不会串门）
|
||
- [x] 待绑定密钥首次注册落定为该 Agent；同一密钥改注册别的 name → 403
|
||
- [x] 登记重复密钥 → 409；登记过短密钥（<32 位）→ 400
|
||
- [x] 密钥列表接口不回传 `key_token` 全文（实测 `回传全文: False`）
|
||
- [x] **SSE 鉴权加固**：原先只凭 `X-Agent-Name` 就分流，等于任何人报个名字就能读走别人的
|
||
新邮件通知。现在必须通过 Bearer 密钥或 name+secret 验证；仅报名字 / 错 secret / 匿名一律 401
|
||
- [x] 插件密钥流程端到端：首装本地生成密钥（0600，目录 0700）并打印 → 管理员登记 →
|
||
插件重启注册成功 → 用该密钥收发邮件与订阅 SSE 全通
|
||
- [x] 旧的 X-Agent-Name/Secret 方式**保留兼容**（与原计划「向后不兼容」不同：
|
||
已部署的 Agent 不该因为引入密钥就集体失联，两条路径并存成本很低）
|
||
|
||
---
|
||
|
||
## Phase 6：联调 + 部署
|
||
|
||
### 6.1 端到端闭环测试
|
||
|
||
- [x] 启动 Gateway（`go run ./cmd/server`，SQLite 自动建库，无需外部数据库）
|
||
- [x] 启动前端（`npm run dev`）
|
||
- [x] 启动 opencode serve + mail-bridge 插件
|
||
|
||
**测试场景（均已在 systemd 部署态实测）：**
|
||
|
||
| # | 步骤 | 结果 |
|
||
|---|------|------|
|
||
| 1 | 人类登录后新建邮件，抄送第二个收件人 | session + mail 落库，cc_list 入库 ✅ |
|
||
| 2 | Agent 收到 SSE 通知 | 插件只注入通知（发件人/主题/mail_id），不注入正文 ✅ |
|
||
| 3 | Agent 调 read_inbox | 返回邮件详情，含被抄送的那封 ✅ |
|
||
| 4 | Agent 调 send_mail 回复人类 | 发起任务的用户收到，`reply_to` 使回信落回同一会话 ✅ |
|
||
| 5 | request_permission | 权限请求邮件入库，`/permission/pending` 可查 ✅ |
|
||
| 6 | 人类决策 | `/permission/decide` 生成决策邮件，Agent 侧收到 ✅ |
|
||
| 7 | 归档 name@path.session | 会话与邮件均标记 archived，归档后该别名不可寻址（404）✅ |
|
||
|
||
**session 位三态实测：** 省略 → 复用默认会话；`.new` → 每次新建；具名别名 → 命中已有，
|
||
不存在则 404「无法送达」；跨收件人借用别名同样 404。
|
||
|
||
**平台命名同步实测：** 发信不指定别名 → opencode 侧 slug 回写为 `calm-meadow`，
|
||
模型生成的摘要标题「生产环境联调邮件回复」回写为 subject；
|
||
再用 `opencode@/root.calm-meadow` 续谈，Agent 正确引用上一封内容。
|
||
|
||
### 6.2 部署编排（改为 systemd，不用容器）
|
||
|
||
原计划的 docker-compose 已作废：数据库换成内置 SQLite 后，部署产物就是「一个二进制 + 一个 .db」，
|
||
再套一层容器编排只是徒增运维层级。见 1.9。
|
||
|
||
- [x] `deploy/install.sh` 一键安装（构建 → 嵌入 → systemd）
|
||
- [x] `deploy/*.service` 两个单元：gateway 与 opencode-serve
|
||
- [x] 删除 `docker-compose.yml`
|
||
|
||
### 6.3 一键启动脚本
|
||
|
||
- [x] `deploy/install.sh` 覆盖构建 + 安装 + 启动
|
||
- [x] 开发态无需脚本：`go run ./cmd/server` 即起（SQLite 自动建库），前端 `npm run dev` 代理到 8180
|
||
|
||
### 6.4 错误处理与边界
|
||
|
||
- [x] Agent 离线时邮件投递：邮件先入库，Agent 心跳响应回传未读数，上线后 `read_inbox` 补齐
|
||
- [x] Gateway 重启后 SSE 客户端重连：前端 `api/sse.ts` 指数退避（1s→15s 上限），
|
||
插件侧 `startSSE` 断流 3s / 出错 5s 后重连
|
||
- [x] 无效 Agent 名/密钥处理：错密钥与不存在的 Agent 统一回 `Invalid credentials`（不区分，避免探测账号存在性）；
|
||
缺头回 `Missing X-Agent-Name or X-Agent-Secret header`
|
||
- [x] 畸形三维地址：缺 name 位、空 to、别名不存在均有明确错误文案
|
||
- [x] 邮件内容 XSS 防护：react-markdown 默认不解析 raw HTML 且清空非 http(s)/mailto 协议 URL，
|
||
新增回归测试 `client/electron/test/markdown-xss.test.mjs`（`npm test`）守住这两个前提，
|
||
防止日后为「支持 HTML 邮件」加上 rehype-raw 而无声开口子
|
||
- [x] 并发安全：`sse.Manager` 用 `sync.RWMutex`；`go build -race` 通过；
|
||
实测 10 客户端并发连接（断开后计数归零）+ 20 封并发发信全部成功（SQLite WAL + busy_timeout）
|
||
|
||
### 6.5 公网反代（已完成）
|
||
|
||
- [x] `mail.jianfgit.xyz` → portal-nginx(.106:3080) → `.60:8180`
|
||
- [x] 列入 portal 认证豁免名单（应用自带账号体系，不叠 portal 登录）
|
||
|
||
---
|
||
|
||
## Phase 7：进阶功能（MVP 后迭代）
|
||
|
||
### 7.1 对话树（已完成）
|
||
|
||
**不建 `tree_nodes` 表**（偏离原计划）：`mails.parent_mail_id` 已经完整编码了树结构 ——
|
||
回复指向来信，转发指向被转发的原件。再维护一张 tree_nodes 就是第二份真相，
|
||
两处不一致时无法判断谁对。直接用递归 CTE 在 mails 上查（`idx_mails_parent` 已有）。
|
||
|
||
- [x] `repo/thread.go`：`AncestorsRaw`（向上）/ `DescendantsRaw`（向下）两个方向的递归 CTE
|
||
- [x] `GET /mail/{id}/thread?dir=around|up|down&offset=N&limit=N`
|
||
- [x] **树可跨会话**：转发把线索引到新会话，但 parent 仍指向原件。
|
||
这正是树视图比会话内平铺更有价值的地方 —— 能看出线索分叉去了哪里
|
||
- [x] **按会话逐个鉴权**：A 转发给 B 之后，B 与 C 在新会话里的往来不能回流给 A。
|
||
被过滤的节点计入 `hidden`，鉴权结果按会话缓存（一条线索里同一会话通常有多封）
|
||
- [x] `detached` / `parent_hidden` 两个标记：前者表示父不在当前已加载集合里，
|
||
后者区分「无权查看」（永久）与「尚未加载」（随上滑补齐）。
|
||
不能因为找不到父节点就把子节点悄悄丢掉
|
||
- [x] 前端 `ThreadView.tsx`：缩进 + 连接线，不引图形库
|
||
（邮件树又浅又窄，一条主链加几个转发分支，缩进足够表达层级，
|
||
省掉渲染 SVG 的依赖与它带来的布局/缩放问题）
|
||
|
||
**分块加载（用户要求：展示完整节点，首屏只加载当前屏幕，上滑逐步补齐）**：
|
||
|
||
原先实现是深度上限 100 直接截断，超长线索看不到全貌。改为按方向分页：
|
||
|
||
- [x] 首屏 `dir=around` 取锚点附近一块（limit 在两个方向各分一半）；
|
||
`dir=up|down` + `offset` 增量加载，两端各自带 `has_more_*` 与 `next_*`
|
||
- [x] **游标用「相对锚点的层号/节点偏移」而不是 mail_id**：
|
||
偏移量每次从锚点重走一遍，无状态、不可伪造；
|
||
用 mail_id 做游标就必须允许传入**不可见**的邮件（不可见的中间段要穿过去），
|
||
那还得单独证明它确实是锚点的祖先，反而更绕。
|
||
祖先方向的层号天然稳定 —— 新邮件只会追加成叶子，不会插进已有链条中间
|
||
- [x] `depth` 改为**相对锚点**（0 = 锚点，负 = 祖先，正 = 子孙）：
|
||
分块加载时根可能还没取到，绝对深度无从得知
|
||
- [x] repo 层**不做可见性过滤**：不可见的中间段必须能穿过（转发把线索引进别人的会话，
|
||
再往上却可能仍是自己参与的往来）。过滤放在 handler 层，那里才知道调用者是谁
|
||
- [x] 前端 `IntersectionObserver` 双哨兵（rootMargin 200px 提前触发）+
|
||
**向上加载的滚动位置补偿**（顶部插入内容后按 scrollHeight 增量修正 scrollTop，
|
||
否则视线会被内容顶走）+ `busy` ref 防两个哨兵同时触发并发请求
|
||
（`setState` 异步，读 state 会双双看到 false）
|
||
- [x] 实测 251 封长链：7 页取完，depth 连续无缺口，取到真正的根；
|
||
311 封（含 60 个转发分支）9 页取完，`depth=1` 恰为 61 个
|
||
- [x] `limit` 夹到 [1,200]，非法值回落默认 40（分页参数不该因笔误让整个请求失败）；
|
||
`limit=1` 时两方向各保底 1，否则算出 `downLimit=0` 连锚点自己都不返回
|
||
|
||
**工作列表卡片视图（已完成）**：
|
||
|
||
中间栏原先只有一种呈现 —— 紧凑列表行，三行显示 `agent / path / .alias` 与「N 封 · 时间」。
|
||
它答得了「跟谁在聊」，答不了「在聊什么、进展如何」：一条线索是一件正在进行的工作，
|
||
而工作的状态在列表上完全看不见，必须逐条点开。
|
||
|
||
- [x] `WorkCard.tsx`：主题（平台模型生成的摘要）+ 最新一封的发件人与摘要 + 往返预算徽标
|
||
- [x] **两种视图共用同一份数据与同一套动作**（打开/写信/归档），只有单项渲染不同；
|
||
容器（滚动/空态/归档确认）留在 `ContactPanel`
|
||
- [x] **归档确认框抽成 `ArchiveConfirm` 两视图共用**：归档是破坏性操作，
|
||
换个视图就换套确认 UI 只会让人对「自己点了什么」更没底
|
||
- [x] 视图偏好存 `localStorage`：纯展示偏好不值得建表加 API，
|
||
而每次刷新退回默认视图会让人反复点同一个按钮；读写都容错（隐私模式会抛异常）
|
||
- [x] 卡片视图把中间栏从 320px 放宽到 400px（两行摘要 + 预算条挤不下）；
|
||
窄屏仍是 `w-full`
|
||
- [x] 预算徽标在「不限」（max=0）时**不显示**：一个对每张卡片都成立的「0/0」是纯噪声。
|
||
剩 1 个来回转橙、用尽转红 —— 那是需要人介入的时刻
|
||
- [x] 数据一次取回（`ListContactsFor` 增补 `subject`/`max_rounds`/`used_rounds`/
|
||
`last_from`/`last_preview`），不让卡片为每条会话再打一次库；
|
||
摘要**按 rune 截断**（中文一字三字节，裸切会留 U+FFFD）
|
||
|
||
**顺带修掉的时间戳精度问题**：卡片的「最新进展」要取会话里最后一封邮件，
|
||
而 SQLite 的 `CURRENT_TIMESTAMP` 只有**秒**精度 —— 同一秒内插入的多封邮件
|
||
按 `created_at` 排序结果不确定（实测同秒插 5 封，顺序是乱的，由随机 UUID 决定）。
|
||
「最早那封」（决定联系人身份）同样会取错。
|
||
|
||
- [x] `db.NOW()` 升到**微秒**（毫秒不够：一次插入只要几十到几百微秒，
|
||
循环里连插几封会落在同一毫秒）。实测确认驱动能原样扫回 `time.Time`
|
||
- [x] `mails` 的三条 INSERT **显式传 `NOW()`**：改 schema 默认值只对新库生效 ——
|
||
`CREATE TABLE IF NOT EXISTS` 不改已存在的表，而 SQLite 没有 `ALTER COLUMN`
|
||
- [x] 所有 `ORDER BY created_at` 补 `mail_id` 兜底：老数据仍是秒精度，
|
||
没有第二排序键时同秒行的顺序由存储引擎决定，翻页会重复或漏行
|
||
- [x] 测试用**显式发号的时钟**而非挂钟：测试在循环里连插几封很可能落在同一微秒，
|
||
而生产里两封邮件之间至少隔着一次模型推理
|
||
|
||
### 7.2 抄送（已完成）/ 转发
|
||
|
||
- [x] `cc_list JSONB` 字段加入 mails 表
|
||
- [x] 发送时支持抄送多个三维地址
|
||
- [x] 前端邮件详情显示抄送列表
|
||
- [x] 收件箱检索覆盖被抄送邮件（`to_name = $1 OR cc_list @> ...`）
|
||
- [x] 转发功能（引用原文 + 新收件人 + 附件随行）
|
||
- `POST /mail/{id}/forward`（Agent）与 `POST /me/mail/{id}/forward`（人类）
|
||
- 与「回复」的区别：回复落回原会话，转发按目标地址另行寻址 —— 它是一条新线索
|
||
- 只能转发自己参与过的邮件（发件/收件/被抄送之一），否则 403
|
||
- 引用块逐行加 `> ` 前缀：原文含代码块或列表时，只有逐行前缀才保持引用语义
|
||
- `Fwd:` 前缀不叠加；`parent_mail_id` 指向原邮件以便回溯
|
||
- 附件一同带过去（内容寻址下只新增元数据，不拷磁盘文件）
|
||
|
||
### 7.3 配额机制（已完成；语义经两轮修正）
|
||
|
||
**最终形态：额度只有一层 —— 本任务（会话）的往返预算。**
|
||
|
||
第一版做的是 `agents.max_rounds` 终身额度，用户两次纠正后才对齐到正确模型：
|
||
|
||
1. 「配额应当是在新建邮件、以及邮件对话页面是可编辑的」→ 预算下沉到会话
|
||
2. 「为什么会有全局配额？不是每次单独配置配额，然后有一个默认配额吗？」→
|
||
终身额度整个是错的工具
|
||
|
||
**为什么终身额度是错的**：它跑满后要管理员手工重置才能再干活，
|
||
而 Agent 是长期在线的 —— 那是把一次性资源的模型套在长期服务上。
|
||
而且一个全局计数器让并行任务互相抢额度：给紧急任务留的份被另一条线索吃掉。
|
||
|
||
- [x] `sessions.max_rounds` / `used_rounds`：真正的额度，每条会话独立计数
|
||
- [x] `agents.default_rounds`（默认 20）：派给该 Agent 的**新任务**默认几个来回。
|
||
按 Agent 配而不是全站一个数 —— 跑测试的小工具与重构整个模块的 Agent，
|
||
合理来回数差一个量级
|
||
- [x] 写信不给 `max_rounds` 时取收件 Agent 的默认值；写信页把它显示为
|
||
输入框 placeholder（人该看得到「不填会是多少」，否则得先去管理员页查）
|
||
- [x] `agents.used_rounds` **降级为纯统计**：只累加、不拦请求。
|
||
保留是因为「这个 Agent 一共发了多少信」有观测价值；
|
||
`BumpSentCount` 连 error 都不返回 —— 统计写失败不该让邮件发不出去
|
||
- [x] 管理员页 tab 从「发信配额」改名「默认预算」，列出
|
||
默认来回数 + 进行中任务数 + 累计发信数；不再有「重置」按钮
|
||
（累计数是历史，归零它只会销毁信息）
|
||
- [x] `PUT /admin/quotas/{name}` 兼容旧字段名 `max_rounds`：
|
||
已部署的前端与脚本不该因为改名就难以察觉地失效
|
||
- [x] 心跳不再回传额度（额度不属于 Agent）；剩余往返随发信响应的
|
||
`budget_remaining` 回传，在那里才有意义
|
||
|
||
**新建会话速率限制**（替代终身额度的防滥用手段）：
|
||
|
||
预算按会话计，Agent 就可以用 `.new` 开一串新会话，每条都是全新预算。
|
||
|
||
- [x] `repo/sessionrate.go`：滑动窗口，同一 Agent 1 小时最多新建 20 条，超出 429
|
||
- [x] **判断与记账在同一把锁里**：分开的话并发请求会双双通过检查把上限刷穿 ——
|
||
与配额那条 UPDATE 同样的道理。单测用 80 并发验证恰好放行 20 次
|
||
- [x] 建会话失败时 `ReleaseNewSession` 归还名额（那次新建实际上没发生）
|
||
- [x] 用 429 而不是 403：前者表示「稍后再来」，后者表示「你没这个权限」，
|
||
客户端据此决定重试还是放弃
|
||
- [x] 被限速的 Agent **仍可在已有会话里回信** —— 不是全面封杀；
|
||
也不禁止 Agent 主动开新会话，那会堵死 Agent 之间的主动协作
|
||
- [x] 人类不受此限：手工点「新建邮件」的频率天然受限，
|
||
加限制只会在批量派活时误伤（实测人类连开 25 条会话全通）
|
||
- [x] 省略 session 位的「默认会话」不计入：一个 `name@path` 只有一条，
|
||
不构成暴开手段
|
||
- [x] 已知取舍：进程内内存计数，与登录限速同一取舍。多实例部署时各自计数，
|
||
等效上限变成 N 倍
|
||
|
||
**实测 11 组**：新注册默认 20 / 按 Agent 分别设（tiny=5）/ 派活自动取默认值 /
|
||
显式值优先 / 22 封连发确认终身额度不再拦（第 21 封被会话预算拦下）/
|
||
对话页调高后可继续 / 暴开 24 条会话恰好放行 20 / 人类连开 25 条全通 /
|
||
被限速仍能回信 / 默认会话不计入 / 老库补 default_rounds 且旧统计不丢。
|
||
|
||
### 7.4 会话别名动态更新（已完成）
|
||
|
||
会话别名的**基础能力已在 Phase 1 落地**（见「三维寻址 session 位三态」）：
|
||
- [x] 发信时用 `session_alias` 为 `.new` 新建的会话命名，响应回传 `session_alias`
|
||
- [x] `PUT /sessions/:id/alias` 事后改名，唯一性冲突返回 409
|
||
- [x] 别名全局唯一（`idx_sessions_alias_uniq` 部分唯一索引，NULL 不受约束）
|
||
- [x] 保留字与字符校验：不可为 `new`，不可含 `.` `/` `@` 与空白（否则地址切分歧义）
|
||
- [x] 前端 ComposePage 在地址以 `.new` 结尾时才显示「会话别名」输入框
|
||
|
||
**别名/标题的默认来源 = Agent 平台自己的命名机制**（不在本侧另造一套）：
|
||
- [x] `POST /sessions/:id/sync`（Agent 认证）接收平台侧 `alias` + `title`
|
||
- [x] opencode 插件建会话时**不传 title**，让平台按首轮对话由模型生成摘要标题；
|
||
创建即拿到的 slug（如 `witty-planet`）立即回写为寻址别名，标题随 `session.updated` 事件回写
|
||
- [x] 平台 slug 不保证全局唯一，本侧别名必须唯一 → `SyncSessionAlias` 撞名自动追加 `-2`/`-3`，同步永不失败
|
||
- [x] `normalizeAlias` 把平台命名改写为合法寻址别名（非法字符换 `-`、压缩连续 `-`、避开保留字 `new`、按 UTF-8 边界截断 128 字节）
|
||
- [x] 手工命名（发信 `session_alias` / `PUT alias`）仍可覆盖平台命名，属显式优先
|
||
|
||
**由 Agent 在邮件正文里主动提议改名**（已完成，与上面的自动同步互补）：
|
||
|
||
两者分工：自动同步 = 平台起的名字，后台静默生效不打扰人；
|
||
正文提议 = Agent 干完活觉得该换个更贴切的名字，需要人点头。
|
||
|
||
**为什么要人点头而不是让 Agent 直接调 `PUT alias`**：
|
||
别名是**人**的寻址入口（`name@path.别名`）。Agent 干到一半自己改掉，
|
||
人上一秒记住的地址下一秒就失效。提议 + 人确认，既让 Agent 表达意图，
|
||
又保证寻址稳定性由人掌握。
|
||
|
||
- [x] 载体是 HTML 注释 `<!-- agentmail:rename-session alias="x" reason="y" -->`
|
||
- react-markdown 默认不解析 raw HTML，注释在页面上不可见
|
||
- 纯文本客户端里是一行不碍事的注释，不像自造标记那样显眼
|
||
- 不与 Markdown 语法冲突，不会被格式化工具改写
|
||
- **实测它会被转义成可见文本节点而不是被丢弃**，所以必须从入库正文里主动剥掉
|
||
- [x] `handler/rename_proposal.go`：`extractRenameProposal` 解析 + 剥标记
|
||
- 只认**最后一条**：Agent 在长回复里可能反复修正措辞，最后写下的才是结论
|
||
- 别名过 `normalizeAlias` + `validateSessionAlias`，非法的视为无提议但标记仍剥掉
|
||
（与其在正文里留一行乱码，不如当它没提）
|
||
- 理由截断到 200 字节（按 UTF-8 边界），否则提示条被撑破
|
||
- 人类发信同样剥标记但不产生提议 —— 人有改名按钮，用不着向自己提议
|
||
- [x] 存在**邮件**上（`mails.rename_alias/rename_reason`）而非会话上：
|
||
邮件是不可篡改的历史记录，「谁在哪一封里提了什么」应当留痕
|
||
- [x] `sessions.rename_dismissed` 记下被驳回的建议，提示条不再反复弹同一个
|
||
- [x] `GET /sessions/:id/rename-proposal` 取最新**未处理**提议
|
||
（既不是当前别名 = 未接受，也不在驳回记录里）
|
||
- [x] `POST /sessions/:id/rename-proposal/dismiss` 驳回；无待处理时返回 `no_pending`（幂等）
|
||
- [x] **接受走已有的 `PUT /sessions/:id/alias`**，不另开端点：
|
||
那条路径已有唯一性校验与 409，复制一遍只会多一个出错的地方。
|
||
实测提议的名字被别的会话占用时接受返回 409，而不是默默造出重名
|
||
- [x] 插件 `send_mail` 加 `propose_alias` / `propose_reason` 参数，自动拼注释标记；
|
||
发信响应回传**规范化后**的别名（Agent 提的名字可能被改写过）
|
||
- [x] 前端 `RenameProposalBar`（会话顶部）：显示 旧别名 → 新别名 + 理由 +
|
||
「改名后旧别名立即失效」的后果提示；接受/忽略两个按钮。
|
||
`new_mail` 事件触发重新拉取（新来信可能带新建议）
|
||
- [x] **SQLite 老库补列**：`CREATE TABLE IF NOT EXISTS` 不会给已存在的表加列，
|
||
而 SQLite 没有 `ADD COLUMN IF NOT EXISTS`。`db.addMissingColumns` 查
|
||
`pragma_table_info` 后按需 ALTER，实测老库补列成功、旧数据不丢、二次启动不重复补
|
||
|
||
**`sessions.alias_source` —— 生产实测发现的隐患**：
|
||
|
||
用户接受改名后，opencode 下一次 `session.updated` 事件会带着平台 slug 再同步一次，
|
||
把人刚定的名字冲掉 —— 人上一秒记住的寻址地址下一秒失效。实测确认了这个行为
|
||
（`fix-cache-penetration` 被 `stellar-engine` 覆盖）。
|
||
|
||
- [x] `sessions.alias_source`：`platform`（平台自动同步，可被后续同步覆盖）/
|
||
`manual`（人显式指定，平台同步不得覆盖）
|
||
- [x] `UpdateSessionAlias` 与「发信时显式给 `session_alias`」都标 `manual`
|
||
- [x] `SyncSessionAlias` 遇到 `manual` 直接返回当前别名，不写入；
|
||
**条件放进 `WHERE alias_source <> 'manual'` 并检查 RowsAffected** ——
|
||
并发下用户可能刚好在检查与写入之间接受了提议，分两步会把它冲掉
|
||
- [x] **标题不受此保护**：`subject` 只用于展示，被平台的摘要标题刷新是好事；
|
||
受保护的只有承担寻址职责的别名
|
||
- [x] 老库补列默认 `platform`：无从得知历史别名是人定的还是平台定的，
|
||
而 `platform` 只影响「平台同步能否覆盖」，人随时可手工改名转成 `manual`
|
||
- [x] 四个场景实测：platform 可反复覆盖 / 用户改名后平台同步无效 /
|
||
发信显式命名即受保护 / 全流程（平台命名 → Agent 提议 → 用户接受 → 平台再同步不覆盖）
|
||
|
||
### 7.5 附件（已完成）
|
||
|
||
**内容存磁盘、元数据入库**：附件是「写一次读多次」的冷数据，塞进 SQLite 的 BLOB 只会让
|
||
`.db` 膨胀、WAL 变大、备份变慢，换不来任何好处。
|
||
|
||
- [x] `attachments` 表（两方言各一份）；`mail_id` 允许为 NULL 表示「已上传未挂载」
|
||
- [x] `internal/blob`：内容寻址存储，路径由 sha256 派生（`ab/cd/abcd…`）
|
||
- 相同内容天然去重，重复上传不占额外空间
|
||
- 路径与用户给的 filename 完全无关，杜绝 `../` 穿越
|
||
- 先写临时文件再按内容哈希 rename：中途崩溃不会留下「哈希对不上内容」的文件
|
||
- 超限即中止并清理临时文件；恰好等于上限放行（边界不误杀）
|
||
- [x] **上传与发信两步**：`POST /attachments` 拿 id → 发信时放进 `attachment_ids`。
|
||
Agent 侧工具走 JSON 无法带 multipart，人类侧也需要「写正文前先传文件」
|
||
- [x] 挂载校验：`WHERE mail_id IS NULL AND uploader = ?` 一条 UPDATE 完成判断与写入，
|
||
避免并发下把同一附件挂到两封邮件上；不属于自己 403，已挂载 409
|
||
- [x] 下载鉴权：已挂载的看邮件所属会话的参与关系，未挂载的只有上传者本人能看
|
||
- [x] **下载一律 `octet-stream` + `attachment` + `nosniff`**：绝不按声明的 MIME 内联渲染，
|
||
否则上传一个 `.html`/`.svg` 就能在本站域下执行脚本
|
||
- [x] `Content-Disposition` 双写：`filename*` 承载 UTF-8，`filename=` 兜底且转义引号与控制字符
|
||
- [x] 删除：只允许删自己上传且未挂载的；内容被其他记录共享时不删磁盘文件
|
||
- [x] GC：启动时 + 每小时扫一遍，清理超过 24h 未挂载的记录与无引用文件
|
||
- [x] 单个上限 25MB（`AGENTMAIL_MAX_ATTACHMENT_BYTES`）；
|
||
双层限制：`MaxBytesReader` 卡整个请求体，`blob.Put` 卡单文件内容
|
||
- [x] 插件工具 `upload_attachment` / `download_attachment`；`read_inbox` 列出附件清单含 id
|
||
- [x] 前端 `Attachments.tsx`：写信/回复的选择器（XHR 上传进度）+ 邮件详情的下载清单 +
|
||
列表页附件徽标
|
||
|
||
### 7.6 WebAPI 化（已完成）
|
||
|
||
**WebUI 调用的就是公开 API，没有仅前端可用的私有通道** —— 第三方客户端拿一把用户密钥
|
||
即可获得与网页完全相同的能力。
|
||
|
||
- [x] 实测前端用到的每个端点都能用 `Authorization: Bearer <user_key>` 调通
|
||
（读、写、上传、下载、转发、管理员接口、SSE）
|
||
- [x] 两处例外补齐 `?access_token=`：SSE（`EventSource` 不能带自定义头）与
|
||
附件下载（`<a download>` 由浏览器直接发起）。
|
||
**只有这两个端点接受 query 令牌**，其余一律 401 —— URL 里的令牌会进访问日志与 Referer；
|
||
附件下载因此单独挂在 `UserAuthAllowQueryToken` 中间件下
|
||
- [x] CORS 暴露 `Content-Disposition` 与 `Content-Length`（前者是取文件名所必需）
|
||
- [x] `client/electron/src/api/config.ts` 集中基地址与令牌：
|
||
`VITE_API_BASE` 构建期注入、`window.__AGENTMAIL_API_BASE__` 运行时覆盖、`setToken()` 切凭证。
|
||
业务代码不感知 Cookie 与密钥的差异，`src/api/` 可整体抽成 SDK
|
||
- [x] `docs/API.md`：完整接口清单、三类调用者的认证边界、错误码约定
|
||
|
||
### 7.7 DeepSeek Harness 插件（已完成）
|
||
|
||
`plugins/dsh-mail-bridge/`，Cordis 插件框架 + TypeScript。
|
||
适配方法与踩坑记录已固化为 **[`docs/PLUGIN-CONTRACT.md`](PLUGIN-CONTRACT.md)**，
|
||
后续接入新平台按那份清单走。
|
||
|
||
- [x] Cordis 插件骨架：`export const inject` + `export const name` + `apply(ctx, config)`
|
||
- 没有 `inject` 时 `ctx.tools` / `ctx.agents` 根本不存在
|
||
（报 `cannot get property "tools" without inject`）
|
||
- 但**可选服务不能写进 `inject`** —— 那是硬依赖，服务没挂载时整个插件不启动。
|
||
`sessionQuery` 用 `ctx.get()` 取：会话上报只是补全体验，
|
||
不该能把邮件投递整体拘死
|
||
- [x] 四个工具经 `defineTool` 注册（`send_mail` / `read_inbox` /
|
||
`upload_attachment` / `download_attachment`）
|
||
- 直接给 `ctx.tools.register` 原始对象会报
|
||
`parameters must be lossless JSON before schema projection`
|
||
- 还必须声明 `output: { schema, render }`
|
||
- [x] `ctx.agents.create()` 建会话 + `agent.followup()` 投递消息
|
||
- **`followup()` 要完整的 `UserMessage`（`content` + `source`）**，
|
||
不是 opencode 那种 parts 数组。传错不当场报错，而是在 agent-loop 的
|
||
`preStep` 里抛 `Cannot read properties of undefined (reading 'kind')` ——
|
||
错误落在框架内部，不指向调用点，turn 一 start 就 end、模型请求根本不发出去。
|
||
这个坑花了一下午，已用 `lib/message.js` + 测试钉住
|
||
- `setup` 留空：base bundle 已注册 agent-loop / llm / tools，
|
||
`agentOptions: { provider, model }` 就够了；挂 preset 反而多余
|
||
- [x] `agent/status` → `idle` 时自动转发最后一条 assistant 消息
|
||
（对应 opencode 的 `session.idle`），复用 `lib/relay-dedup.js` 让位于
|
||
模型的主动回信，带 `relay: 'summary'` 走免配额通道
|
||
- [x] `approval/request` 钩子把权限询问转成邮件问人
|
||
- 与 opencode 的关键差异：那边的 `permission.ask` 是**同步**钩子，
|
||
卡住会挂死整个请求，只能「转出去 + 立即返回 ask」；
|
||
DSH 这边是**异步 waterfall**，返回 `Promise<ApprovalOutcome>`，可以真的等人
|
||
- 拆插件时未决询问一律 fail closed（`unavailable`），
|
||
否则 DSH 侧那些 `await` 永不返回
|
||
- DSH 不给询问发 id，用 `会话:工具:callId` 作幂等键
|
||
- [x] 会话别名由**模型生成的标题**派生（与「别名复用平台命名」的既定决策一致）
|
||
- `slugFromTitle` 保留中文（转拼音后既不好读也不好打，
|
||
而三维地址按最后一个 `.` 切分，中文不影响解析）
|
||
- 但必须去掉 `.` `@` `/` 等寻址分隔符 —— 留在别名里会让它自己被解析器切开
|
||
- fallback 占位标题不派生别名：DSH 在模型生成真标题前会先落一个
|
||
内容是「用户第一句话截断」的标题，而那句话是插件自己拼的提示词
|
||
- [x] **补上心跳** —— 之前完全没有，Gateway 靠 `last_seen` 判在线，
|
||
一直靠注册那一次撑着
|
||
- [x] 与 opencode 插件共用 `lib/` 下的纯函数模块（逐字节相同）
|
||
|
||
### 7.7.1 工作目录归属（修复）
|
||
|
||
**症状**：dsh 指定工作目录完全失效，所有会话落进「未分组」。
|
||
|
||
**根因两层**：
|
||
|
||
1. 插件建会话时的 cwd 是自己拼的 `~/.dsh/mail-sessions/mail-<uuid>` ——
|
||
每封邮件一个全新的空目录。平台按 cwd 给会话分组，于是所有邮件会话
|
||
既不属于任何项目、彼此也不同组
|
||
2. Gateway 从来没把地址的 path 位发给插件：`notifyRecipients` 的 payload
|
||
只有 `mail_id`/`session_id`/`from_name`/`subject`，`to_workspace` 虽然入库了
|
||
却不在 SSE 事件里 —— 插件即使想用也拿不到
|
||
|
||
- [x] SSE `new_mail` 事件加 `to_workspace`。**每个收件方拿到自己那个地址的 path**，
|
||
不是主收件人的 —— 抄送给 `opencode@/a` 与主发给 `dsh@/b` 是两个工作区
|
||
- [x] 两个插件的 cwd 都改为取寻址的 path 位（共用 `lib/workspace.js`）
|
||
- [x] 不存在的目录**不创建**而是回退到兜底目录：一个笔误
|
||
（`/home/porgram/x`）不该在磁盘上落下真目录，Agent 会在里面一无所获地干活
|
||
- [x] 拒绝相对路径：cwd 的相对基准是 harness 进程的启动目录，systemd 下通常是 `/`
|
||
|
||
### 7.7.2 平台会话快照上报（新增）
|
||
|
||
**症状**：会话别名列不出工作区下的历史会话，无法选择。
|
||
|
||
人直接在平台界面上开的会话，Gateway 一无所知；而邮件驱动的那些也因为
|
||
`workspace` 没存在会话上（只在 `mails.to_workspace`，且 Agent 回信的
|
||
`from_workspace` 填的是 Agent 名而不是路径）而匹配不上。
|
||
|
||
- [x] `sessions.workspace` 新列，`CreateSession` 从地址的 path 位带入
|
||
- [x] `agent_platform_sessions` 镜像表 + 心跳携带 `platform_sessions`
|
||
- [x] **插件上报而非 Gateway 反向拉取**：当前架构是单向的（Agent 持密钥主动连
|
||
Gateway，Gateway 从不外呼），反向拉取需要它保存各平台的地址与凭证，
|
||
那是另一套信任模型
|
||
- [x] 与 `sessions` 表**分开存**：镜像里是别人家的会话，id 属于平台的 id 空间，
|
||
没有本侧的 owner/预算/邮件。混进 `sessions` 会让每一处「按会话鉴权」
|
||
都要先判断这条到底是不是真的本侧会话
|
||
- [x] **整表替换而非增量合并**：平台侧删掉的会话必须从候选里消失 ——
|
||
session 位是三态语义，指向不存在的会话直接 404
|
||
- [x] **`platform_sessions` 省略与传空数组语义不同**：拉不到列表时省略该字段
|
||
（保留镜像），传空数组的语义是「平台侧确实一条会话都没有」
|
||
- [x] **subagent 子会话不上报**：实测 DSH 一次列出 49 条子会话，标题就是派活的
|
||
提示词前缀（九条都叫 `You are auditing ONE file`），slug 全撞名；
|
||
它们是父 agent 内部的工作单元，人往里发邮件毫无意义
|
||
- [x] **slug 撞名只留最近那条**：服务端只能取其中一条，上报同名项只会让补全里
|
||
出现几个点哪个都不确定的候选
|
||
- [x] `SuggestSessionCandidates` 取代 `SuggestSessionsFor`：以会话自己的
|
||
`workspace` 为权威，历史会话（该列为空）回退到 mails 反推 ——
|
||
升级后老会话不该从候选列表里消失
|
||
- [x] 补全候选带标题与来源：`suggestions` 保留纯字符串数组（不打破已部署的前端
|
||
与第三方客户端），新增同序的 `candidates`；过滤时标题也参与匹配 ——
|
||
人记得的是「缓存选型」而不是 `brisk-harbor` 这种随机短名
|
||
|
||
### 7.8 跨主机 Agent（协议层面已支持，注册中心不做）
|
||
|
||
原计划的 Gateway + Registry 拆分与 etcd/Consul 注册**取消**。
|
||
它要解决「Gateway 怎么找到 Agent」，而这个问题在本架构里不存在：
|
||
**连接方向是单向的 —— Agent 主动连 Gateway，Gateway 从不外呼。**
|
||
远端 Agent 只需要一个公网 URL 加一把密钥，被叫方自己会打进来。
|
||
|
||
- [x] Agent 从另一台主机经公网完成注册 / 心跳 / 收件箱 / SSE 长连
|
||
（2026-09-02 用 `deploy/remote-agent-demo.py` 验证，纯标准库 60 行）
|
||
- [x] 心跳带模型目录与平台会话快照同样跨主机可用
|
||
- [ ] （运维便利，不阻塞）一条命令为远端主机建密钥并打印环境变量
|
||
- [ ] （运维便利，不阻塞）密钥轮换
|
||
- [ ] （运维便利，不阻塞）`agents.host_url` 由心跳自报填充
|
||
|
||
细节见 `docs/PHASE7-REMAINING.md` 的「7.8 跨主机 Agent」一节。
|
||
|
||
### 7.9 插件自动转发 + 会话往返预算（已完成）
|
||
|
||
用户提出的三条原则，逐条落地：
|
||
|
||
**原则一：插件应当自动转发 Agent 平台原生的问询与权限请求，而不是让模型自己调工具。**
|
||
|
||
原实现有个 `request_permission` 工具让模型主动调 —— 这是把 harness 的职责推给模型：
|
||
它可能忘了调，也可能在不需要时乱调，而**真正被 opencode 拦下的那次询问反而没人看见**。
|
||
|
||
- [x] 删掉 `request_permission` 工具，改用 `permission.ask` 钩子接管
|
||
- [x] 钩子里只记下待决策项并转出邮件，`output.status` 保持 `"ask"` ——
|
||
不在钩子里阻塞等人回复：那是同步钩子，卡住会把整个 opencode 请求挂死
|
||
- [x] opencode 的三态权限映射成人话：同意 = `once`、一直同意 = `always`、拒绝 = `reject`
|
||
- [x] 人类决策后走 SSE 回来，用 `client.postSessionIdPermissionsPermissionId` 回复原生 permission，
|
||
让 opencode 自己恢复原来的工具调用 —— 不再往会话里塞「你的请求已批准」的文字干扰它
|
||
- [x] 转发失败时不接管（保持 `ask`），让本地 TUI 弹窗兜底，而不是让 Agent 干等
|
||
- [x] `permission.replied` 事件清理待决策记录，避免邮件决策回来又去回复一条已结案的 permission
|
||
|
||
**原则二：插件应当自动转发 Agent 最后一条总结性消息，且不消耗配额。**
|
||
|
||
- [x] 触发点选 `session.idle`（一轮跑完）而不是 `message.updated`：
|
||
后者在流式生成中反复触发，转出去是半截话
|
||
- [x] 只取 `time.completed` 非空的 assistant 消息：未完成/被中断的不转
|
||
- [x] `mailContexts` 记住该会话最近一封来信的发件人与 mail_id，
|
||
总结回给它并带 `reply_to`，回信才落回同一线索
|
||
- [x] 提示语相应改写：告诉模型「回信不用你自己发，把话说完就行」，
|
||
只在需要主动联系他人或带附件时才调 `send_mail`
|
||
|
||
**原则三（基本原则）：插件自动转发的邮件不消耗配额。**
|
||
|
||
配额存在的意义是防止 Agent 无限自我循环。harness 代劳的搬运不属于此列 ——
|
||
对它收费会导致配额用尽时 Agent 连交代都做不了，而那正是最需要它说话的时刻。
|
||
|
||
- [x] `mails.relay` + `relay_key` 参数；`relayKinds` 白名单只有 `permission` / `summary`
|
||
（不是任意字符串，否则 `relay:"anything"` 就是绕过配额的后门）
|
||
- [x] **防滥用不靠计数，靠幂等键**：`relayed_mails(agent_name, relay_key)` 主键唯一。
|
||
relay_key 是上游那条消息的稳定 id（permission id / assistant message id），
|
||
由平台生成、模型伪造不出来。于是插件重试与 SSE 重放不产生第二封，
|
||
想多转就得拿出不同的上游消息 id
|
||
- [x] 判断与占用在同一条 INSERT 里（靠唯一约束）：分成「先查再插」两步的话，
|
||
插件的两次重试会双双通过检查各插一条
|
||
- [x] 建邮件失败时 `ReleaseRelay` 归还名额，否则那条上游消息永远转不出来了
|
||
- [x] 重复转发返回 `200 {"status":"duplicate_relay"}` 而非报错 ——
|
||
重复是插件重试的正常结果，不是故障
|
||
- [x] 响应带 `quota_charged: false`，免得插件看到额度没变以为数据错了
|
||
- [x] `permission_decision` 事件回传 `relay_key` + `relay_kind`：
|
||
两边 id 空间不同，插件要拿上游 id 才能回复 opencode；
|
||
**这个映射必须服务端持久化**，插件重启后内存映射就没了
|
||
|
||
**配额下沉到会话（用户：配额应当在新建邮件、以及邮件对话页面是可编辑的）**
|
||
|
||
配额的真实语义是「这件事值得多少个来回」—— 那是**任务**的属性，不是 Agent 的属性。
|
||
只有 `agents.max_rounds` 一个全局计数器时有两个问题：并行任务互相抢额度；
|
||
`used_rounds` 单调递增，跑满就得管理员手工重置才能再干活。
|
||
|
||
- [x] `sessions.max_rounds` / `used_rounds`（0 = 本会话不限）
|
||
- [x] 写信时给：`POST /me/mail/send` 的 `max_rounds`，仅新建会话时生效 ——
|
||
续谈也接受的话，每封新信都会悄悄改掉对方正在遵守的预算
|
||
- [x] 对话页里改：`GET/PUT /sessions/{id}/budget`，`max_rounds` 与 `reset` 可同时给
|
||
（「加到 20 并从头算」是一次很自然的操作，拆两个请求只多一次往返）
|
||
- [x] 额度只有这一层（后续修正）：原先叠了一层 Agent 终身额度，
|
||
但那种额度跑满要人工重置才能再干活，已降级为纯统计。见 7.3
|
||
- [x] 绕过手段（Agent 用 `.new` 开一串会话）由新建会话速率限制堵住，见 7.3
|
||
- [x] 判断与自增在同一条 UPDATE（`WHERE used_rounds < max_rounds`），
|
||
40 并发 vs 上限 10 的单测覆盖，`-race` 通过
|
||
- [x] 允许把上限调到低于已用次数：那表示「就到这里为止」，是人的合法意图
|
||
- [x] 前端：ComposePage 的「往返预算」输入框 + MailView 会话头部的 `BudgetEditor`
|
||
（点徽标就地编辑，可改上限/重置/取消）；预算变更广播 `session_update`
|
||
- [x] 老库补列默认 0（不限）：引入预算不该把已在进行的会话卡死
|
||
|
||
**Agent 侧标记已读（这一轮顺带修的真实缺陷）**
|
||
|
||
原实现 Agent 只能读收件箱，没有任何办法把邮件标掉 —— 生产库里 `opencode` 名下
|
||
积了 31 封未读，每次 `read_inbox` 都把同一批旧邮件重新捞出来，
|
||
处理过的信和新来的信混在一起，模型分不清哪封该回；心跳里的未读数也只增不减。
|
||
|
||
- [x] `POST /mail/read`（Agent 认证）：给 `mail_ids` 标指定几封，不给则全部标掉
|
||
- [x] **鉴权写进 `UPDATE` 的 `WHERE`**（`to_name = $1 OR cc 含 $1`）而不是先查后改：
|
||
不是发给自己的邮件根本改不动，既省一次查询，也没有「查完到改之间邮件被转走」的窗口
|
||
- [x] 别人的 id 混在批次里不报错，只是不被标掉 —— 报错会让整批失败，
|
||
而 Agent 通常把上一轮列出的 id 原样传回，其中可能混着已读的（幂等）
|
||
- [x] 「全部标掉」排除已归档会话：那些邮件在收件箱里看不到，
|
||
标了只会让「标记了 N 封」与用户看到的对不上
|
||
- [x] 一批上限 200；畸形 id 一律 400（不静默跳过，那会让调用方以为标成功了）
|
||
- [x] 插件 `read_inbox` 读完自动标掉**本次列出的那些**（不是全部未读 ——
|
||
limit 之外的还没看过，一并标掉等于让它们凭空消失）；
|
||
标记失败不让 `read_inbox` 失败，代价只是下次重复看到
|
||
- [x] `markread_test.go` 5 个用例 + 端到端 10 组（含抄送、归档、跨 Agent 越权）
|
||
|
||
**验证**：单测 `relay_test.go`（10 个用例，含「免配额类型恰好两种」的防扩散断言）+
|
||
`budget_test.go`（6 个，含 40 并发不刷穿）。端到端 8 组：
|
||
自主发信扣额 → 用尽后 relay 照样发出且不扣 → 同 key 幂等 → 换 key 可再转 →
|
||
参数校验 4 项 → 权限询问幂等 + 决策回传 relay_key → 对话页调预算 →
|
||
两层独立且全局拦下时会话退回 → 老库补列不丢数据。
|
||
|
||
---
|
||
|
||
## 里程碑时间线
|
||
|
||
| 时间 | 里程碑 | 验收标准 |
|
||
|------|--------|----------|
|
||
| Week 1 末 | 后端核心完成 | Gateway 启动 + 所有 API curl 可通 |
|
||
| Week 2 末 | 插件完成 | opencode 可收发邮件 + 钩子自动转邮件 |
|
||
| Week 3 末 | 前端完成 | 三栏 UI + 三段式补全 + SSE 实时更新 |
|
||
| Week 4 末 | 多用户完成 | 两个人类账号互不可见对方邮件，登录鉴权生效 |
|
||
| Week 5 末 | 密钥体系完成 | Agent 用密钥注册、用户密钥与 Agent 密钥隔离 |
|
||
| Week 6 末 | MVP 闭环 | 人→Agent→人 完整工作流可演示 |
|
||
| Week 7+ | 进阶功能 | 对话树 / 转发 / 配额 / DSH 插件 |
|
||
|
||
**实际状态**：Phase 1-6 全部完成，已 systemd 部署并端到端验证（含密钥认证、
|
||
session 三态语义、平台命名同步、权限闭环、并发与鉴权边界）。剩余仅 Phase 7。
|
||
|
||
---
|
||
|
||
## 当前进度
|
||
|
||
### 已完成
|
||
|
||
**后端（Go）**
|
||
- [x] 项目结构与 MVP 技术规格书
|
||
- [x] schema 两方言各一份（users / user_sessions / agents / sessions / mails / permission_requests）
|
||
- [x] 数据模型 + 连接池 + 内嵌迁移器
|
||
- [x] Repository 层（含联系人聚合、归档、三段式补全查询）
|
||
- [x] 三维寻址 `name@path.session` 解析器 + 单测（`internal/models/address.go`）
|
||
- [x] **session 位三态语义**：省略 → 默认会话（复用最近活跃，无则建）；`new` → 强制新建；
|
||
具体别名 → 必须已存在且该收件人参与过，否则 404「无法送达」（不静默新建）
|
||
- [x] **会话别名**：`.new` 发信时可传 `session_alias` 命名，`PUT /sessions/:id/alias` 事后改名；
|
||
全局唯一（部分唯一索引），保留字 `new` 与 `.` `/` `@` 空白一律拒绝
|
||
- [x] **别名默认来自 Agent 平台自己的命名机制**：`POST /sessions/:id/sync` 接收平台 slug + 模型生成的摘要标题；
|
||
插件不传占位 title，让平台正常生成；撞名自动追加 -2/-3，同步永不失败
|
||
- [x] 抄送 `cc_list JSONB` + GIN 索引 + 收件箱抄送可见
|
||
- [x] SSE 管理器（按 agent 分流推送 + 心跳保活）
|
||
- [x] Agent 认证中间件 + 注册/心跳
|
||
- [x] 邮件收发 / 权限请求与决策 / 会话 / 联系人 / 归档 API
|
||
- [x] 静态资源 go:embed，单二进制内含前端
|
||
- [x] 密钥认证体系（agent_keys / user_keys）+ 三种生命周期 + SSE 鉴权加固
|
||
- [x] SQLite 默认后端 + DATABASE_URL 切外部 PostgreSQL，方言差异收在 internal/db
|
||
- [x] systemd 部署（deploy/install.sh），opencode serve 加访问密码
|
||
|
||
**前端（React）**
|
||
- [x] 三栏布局：60px 图标栏 / 320px 列表 / 右侧主区
|
||
- [x] 新建邮件为右侧**整页**（非弹窗）
|
||
- [x] 三段式地址补全（接 `/contacts/suggest`，支持方向键）
|
||
- [x] 联系人面板 + 归档（二次确认）
|
||
- [x] 邮件详情 / 会话线程 / 权限卡片 / 回复栏
|
||
- [x] 全站纯 SVG 图标，**不使用 emoji**
|
||
- [x] SSE 自动重连（指数退避）+ `session_archived` 即时移除
|
||
|
||
**部署**
|
||
- [x] 公网 `mail.jianfgit.xyz` 可访问（portal-nginx → `.60:8180`）
|
||
|
||
### 下一步
|
||
|
||
MVP 计划（Phase 1-6）已全部落地并在 systemd 部署态实测通过。剩余工作都在 **Phase 7 进阶功能**：
|
||
|
||
- [x] 对话树（不建 tree_nodes 表，用 `parent_mail_id` 递归 CTE + 按方向分块加载）
|
||
- [x] 转发（引用原文 + 附件随行；抄送早已完成）
|
||
- [x] 配额机制（只限发信不限收信，判断与自增在同一条 UPDATE）
|
||
- [x] 附件（内容寻址磁盘存储，上传与发信两步）
|
||
- [x] WebAPI 化（WebUI 与第三方客户端同一套 API）
|
||
- [x] Agent 在邮件正文里主动提议改会话别名（平台命名自动同步已完成）
|
||
- [x] 插件自动转发平台原生权限询问与最终总结（不消耗配额）
|
||
- [x] 配额下沉到会话：写信时给、对话页里随时改
|
||
- [x] 工作列表卡片视图（中间栏，与列表视图切换）
|
||
- [x] DeepSeek Harness 插件（`dsh-mail-bridge`）
|
||
- [x] 平台会话快照同步：工作区下的历史会话可在写信时选中
|
||
- [x] 插件适配方法固化为 `docs/PLUGIN-CONTRACT.md`（能力矩阵 / 行为约定 /
|
||
降级语义 / 线协议 / 不变量 / 验收清单）
|
||
- [ ] 跨主机 Agent 发现（Gateway + Registry 拆分）
|
||
|
||
### 7.10 窄屏适配（已完成）
|
||
|
||
原实现只有三栏并排：60（导航）+ 320（列表）+ 详情，在 375px 屏上详情栏被挤到
|
||
不足 0 —— 用户反馈「窄屏基本不可用」。
|
||
|
||
第一版我做成了「窄屏一次只显示一栏」（分栏切换），用户纠正应当是
|
||
**新页面覆盖老页面并带动画**，于是重做为覆盖式。
|
||
|
||
- [x] `useIsNarrow()`：`matchMedia('(max-width: 767px)')`。
|
||
用 matchMedia 而不是监听 resize —— 后者每变化一像素都触发还得自己节流，
|
||
前者只在跨过阈值时回调一次
|
||
- [x] `NarrowStack`：底层（列表）**始终挂载**，覆盖层（详情）绝对定位盖在上面。
|
||
两个实际好处：列表滚动位置与选中态天然保留；退出动画有东西可播 ——
|
||
直接卸载再渲染另一个组件的话，没有任何一帧能让旧页面往右滑出去
|
||
- [x] 因此必须区分「逻辑上是否打开」与「是否还在 DOM 里」：
|
||
关闭时先播 200ms 滑出，动画结束才卸载
|
||
- [x] **入场用双层 requestAnimationFrame**：必须让浏览器至少绘制一帧
|
||
「在右侧之外」的状态，否则挂载与 `translate-x-0` 在同一帧内完成，
|
||
transition 根本不触发（单层 rAF 在 Safari 上偶尔仍被合帧）
|
||
- [x] `motion-reduce:transition-none` 尊重 `prefers-reduced-motion`
|
||
- [x] 打开覆盖层时底层 `aria-hidden`，否则屏幕阅读器会读到两层内容
|
||
- [x] 导航：竖条在窄屏让位给底部 `NarrowNav`（60px 在手机上白占一成宽度，
|
||
而底部横排拇指够得到）。**曾经还有一个抽屉式侧栏，后来删掉了 —— 见 7.10.1**
|
||
- [x] `env(safe-area-inset-bottom)`：iPhone 手势条会盖住最后一排
|
||
- [x] **窄屏专属控件用条件渲染而非 `md:hidden`**：后者只是视觉隐藏，
|
||
元素仍在 DOM 与 tab 序列里，宽屏用户按 Tab 会聚焦到看不见的返回按钮上。
|
||
为此抽了 `NarrowOnly` / `BackButton` 两个组件
|
||
（原先还有 `NavToggle`，随抽屉一起删除）
|
||
- [x] 列表栏 `w-full md:w-[320px]`；各页横向内边距 `px-4 md:px-6`
|
||
（px-6 在 375px 屏上白吃 48px）
|
||
- [x] 管理页的 3/4 列 grid 改响应式；列表行 `flex-wrap`
|
||
（宁可占两行，不要把每列挤成看不清的窄条）
|
||
- [x] 详情页与写信页都有返回出口 —— 否则窄屏进去就出不来。
|
||
写信页用 `cancelCompose` 而不是 `showList`：写信态要一起结束，
|
||
只滑走覆盖层的话下次进列表又会弹回来
|
||
- [x] `narrowPane` 在宽屏下**也维护**：否则从窄屏拖宽再拖回来，
|
||
用户会发现自己回到了列表，刚打开的邮件不见了
|
||
- [x] `client/electron/test/narrow-layout.test.mjs`：结构性断言（现 28 条），
|
||
钉住「覆盖而非分栏」「延迟卸载」「双层 rAF」「条件渲染而非 md:hidden」
|
||
「无裸 px-6」等不变量。不做像素级视觉快照 —— 字体差异下极脆
|
||
|
||
### 7.10.1 真机尺寸实测与修复（2026-09-02）
|
||
|
||
上面那些都是「照着规则写对」，实际用 playwright 连本机共享 Chromium
|
||
在 390px（iPhone 14 Pro）与 320px（iPhone SE）量了一遍，**发现一个功能性 bug
|
||
加五处可用性问题**。详细记录见 `docs/PHASE7-REMAINING.md`。
|
||
|
||
- [x] **删掉抽屉式侧栏**。它是 `fixed ... z-50` 且铺满视口高度，把底部导航
|
||
最左那一项盖住点不到（`elementFromPoint` 命中抽屉里的 SVG）。
|
||
修法不是给导航加 z-index 而是删掉抽屉：它装的六项与底部导航完全重复，
|
||
唯一独有的是退出登录 —— 为一个按钮维护一套 fixed 层级 + 遮罩不划算，
|
||
而它还附带了「Esc 关不掉」「底层未锁滚」两个毛病
|
||
- [x] 退出登录移到「我的」页：与密码、密钥同属「账号自身」，
|
||
而那页此前**根本没有退出入口**
|
||
- [x] **`.tap` 工具类**：44x44 触摸命中区，用居中的透明伪元素实现，
|
||
视觉尺寸一像素不动。实测详情页工具按钮只有 15-16px 高
|
||
（「抄送」20x15），直接加 padding 会把头部撑散、320px 下换行。
|
||
只在 `max-width: 767px` 生效 —— 桌面精度足够，且扩大后的命中区
|
||
在密排工具栏里会互相重叠
|
||
- [x] **`.reveal` 工具类**：`opacity-0 group-hover:opacity-100` 在没有 hover
|
||
的设备上永远透明**却仍然接收点击** —— 一个看不见却按得动的「归档」
|
||
比没有按钮更糟。改为默认可见，只在
|
||
`(hover: hover) and (pointer: fine)` 时隐藏（单看 hover 会把带触摸板的
|
||
平板算进去）
|
||
- [x] 对话树缩进随屏宽自适应：固定「每级 20px、上限 8 级」在 320px 下
|
||
把卡片压到 110px 可用宽度，发件人一行直接被 truncate 吃掉。
|
||
窄屏改为每级 10px、上限 5 级
|
||
- [x] 对话树补返回出口：原先只有「关闭」，而两者语义不同 ——
|
||
返回退出整个详情栏，关闭只收起树留在这封邮件上
|
||
- [x] **`AccountPage` 根本没有滚动容器**（用户反馈「我的页进去后无法滑动」）。
|
||
窄屏外壳是 `h-full flex flex-col overflow-hidden`、页面是
|
||
`flex-1 flex flex-col`，中间没有一层 `overflow-y-auto` ——
|
||
内容超出的部分**直接被裁**，滚不到也点不到。
|
||
实测 390px 下内容需 860px、容器 795px，「退出登录」连同下面 65px 一起消失；
|
||
1280x800 的桌面上同样看不到。其余六个页面级组件都有这一层，只有它漏了
|
||
- [x] 登录页与初始化页在**矮屏**（横屏手机、软键盘弹出后）滚不到底：
|
||
卡片高约 371px，而 `h-full flex items-center` 在内容超高时让它上下**同时**
|
||
溢出，溢出到顶部那段滚不到（`scrollTop` 最小是 0）。实测 568x280 下
|
||
「登录」按钮完全在视口外。改用卡片自己的 `my-auto` —— auto margin 在
|
||
空间不足时自动退化为 0，于是矮屏变成正常的顶对齐可滚布局，
|
||
而高屏仍然垂直居中（390x844 与 1280x800 实测 centered=true）
|
||
|
||
验证：`client/electron/test/manual/`（`npm run test:narrow` / `test:wide`）
|
||
窄屏 18 项 + 宽屏 5 项全通过；结构性断言从 20 条扩到 37 条，
|
||
把每一条修复都钉住。
|
||
|
||
滚动那一项两边都加了检查：结构断言查「七个页面级组件都含 overflow-y-auto」，
|
||
实测脚本的 `scrollHealth()` 查「每页都有滚动容器且没有内容被 overflow-hidden
|
||
的父级裁掉」。判据刻意是「**有**滚动容器」而不是「当前正在滚动」——
|
||
内容暂时不够高时后者为假，但页面是健康的。
|
||
|
||
那套脚本刻意留在仓库里而不是用完就删：结构性断言守不住「按钮实际多大、
|
||
点下去命中谁」，而这次最严重的 bug 恰好只有 `elementFromPoint` 能发现。
|
||
它不进 `npm test` —— 要一个跑着的浏览器加一个活的 Gateway。
|
||
|
||
### 7.11 权限档位（plan / workspace / full）
|
||
|
||
人在派活时声明「这条任务允许 Agent 动手到什么程度」，插件把它翻译成平台原生的
|
||
沙箱/审批配置。三档：
|
||
|
||
| 档位 | 语义 | 权限询问 |
|
||
|---|---|---|
|
||
| `plan` | 只读：查资料、读代码、出方案，一个字都不许写 | **不产生** —— 直接拒绝，模型该把方案写在回信里 |
|
||
| `workspace` | 本目录内可动手，越界要问人（**默认档**） | 越界时产生 |
|
||
| `full` | 自动放行 | **不产生** —— 已声明全权，再问是噪音 |
|
||
|
||
#### 为什么需要它
|
||
|
||
此前根本没有权限模型：能不能跑 bash 完全由各平台自己的本地配置决定
|
||
（dsh 的 `settings.yaml`、opencode 的 `opencode.jsonc`、pi 硬编码守卫三个工具名）。
|
||
发件人对此毫无控制也毫不知情 —— 派一件「只是看一下」的活，对方可能直接改文件。
|
||
|
||
#### 架构：AgentMail 声明，平台执行，插件只翻译
|
||
|
||
**不让插件按工具名自己猜着拦**：那会同时违反 `I-1`（平台原生信号是唯一真相来源）
|
||
与 `I-4`（插件只搬运不决策），而且四个插件对「workspace 到底管什么」必然各猜一套 ——
|
||
同一封 workspace 档的邮件在 A 平台被拦、在 B 平台放行。
|
||
|
||
平台原生能力调研（决定了整个架构）：
|
||
|
||
| 平台 | 原生机制 | 能否只读 | 能否管目录边界 |
|
||
|---|---|---|---|
|
||
| dsh | `setSandboxMode(session, mode)`，三档写死 | 能（真沙箱） | 能（真沙箱） |
|
||
| opencode | `session.create({permission:[…]})`，action ∈ allow/ask/deny | 能 | 能（glob） |
|
||
| pi | 只有 `tool_call` 钩子 `{block:true}` | 能（按工具名） | write/edit 能查 `input.path`，**bash 不能** |
|
||
| homeagent | **无任何拦截点** | 不能 | 不能 |
|
||
|
||
dsh 原生三档（`read-only` / `workspace-write` / `danger-full-access`）与
|
||
plan/workspace/full **一一对应** —— 不是巧合，是同一个问题的同一个答案。
|
||
|
||
#### 五条设计决定
|
||
|
||
1. **档位挂 `sessions.permission_mode`，不挂每封邮件**。与配额同理：它是**任务**的
|
||
属性。续谈的信若也能带档位，每封新信都会悄悄改掉对方正在遵守的规则 ——
|
||
而 plan 档的会话里模型已被告知「只许看」，第二封信改成 full 是在一段已有
|
||
上下文里换规则。新建时设，续谈忽略，对话页里显式编辑。
|
||
2. **Agent 不能自己指定档位，新会话从父会话继承**（`ModeAtMost(父档, 请求档)`）。
|
||
否则发一封 `mode=full` 的信就自我提权了。继承保证 plan 档派不出 full 档子任务 ——
|
||
与 `hop_limit` 同形：约束必须沿链条传递。
|
||
3. **平台表达不出精确档位时向更严取整，并如实上报实际强制力**。pi 的 bash 在
|
||
workspace 档只能退回「每条都问人」。不定这条规则，四个插件会朝不同方向取整，
|
||
而往宽松取整是静默失效（人以为收紧了，实际没有）。
|
||
4. **`agents.mode_enforcement`（心跳自报 native/advisory）**。homeagent 是 advisory ——
|
||
发件人以为 plan 档管住了它，实际管不住。两个字段（要求档位 / 实际强制力）都要
|
||
上界面，差异可见才符合 `I-5`。
|
||
5. **只有 workspace 档需要人**，这一条直接决定「找不到人类时怎么办」：plan 档当场
|
||
拒绝、full 档自动放行，两者都不问人，所以只有 workspace 档会走到「这条链上有没有
|
||
人类」，找不到就是 409。
|
||
|
||
#### 顺带修掉的两处死代码
|
||
|
||
- **`permission.go` 的管理员兜底吃掉了 409 分支**。原顺序是 `req.To → 会话 owner →
|
||
第一个 active admin → 判 IsHuman`，第三步让第四步永远为真，`NearestHumanInThread`
|
||
与那段 409 从未被执行。实测确认：pi 给自己新开会话派活跑 bash，权限邮件
|
||
`to_name=jianf`，点同意后真跑了。而那段 409 的注释本身就在论证兜底是错的
|
||
（「管理员对这条 Agent 链的上下文一无所知」）—— 两条策略互相矛盾，先执行的那条
|
||
把后写的那条变成了死代码。删掉兜底后 `repo.FirstAdminUsername` 也随之失去唯一
|
||
调用点，一并删除。
|
||
- **`repo.ListSessions` 从初始提交就是坏的**：SELECT 9 列、`Scan` 11 个参数，零调用点。
|
||
与 `ListSessionsFor` 当年真出过的事故同一个坑（加了预算两列没加进 Scan，
|
||
`/me/sessions` 整个 500）。留着就得给它也加档位两列，等于维护一个坏且没人用的
|
||
东西，删掉更诚实。
|
||
|
||
#### 实测发现（opencode 的六条，不实测就会做出「看起来对但管不住」的东西）
|
||
|
||
`session.create({permission:[…]})` 确实生效，但：
|
||
|
||
1. **规则是 `findLast` 胜出** → **deny 必须放前面、allow 放后面**。反了的话连
|
||
本该允许的路径也被拒（第一版就写反了，模型自己报「按规则本该通过但实际被拒」）。
|
||
2. **pattern 匹配 worktree 相对路径**（`patterns:[relative(y.worktree, file)]`）→
|
||
写 `/tmp/**` 这种绝对 pattern **永远匹配不上**。这条最隐蔽：配置看着对，全不生效。
|
||
3. **write / edit / patch 共用 `edit` 一个权限名**。
|
||
4. **全 deny 让工具从模型清单里消失**（模型自述「I don't have a bash tool available
|
||
in this session」），部分 deny 则工具保留、越界调用才报错。plan 档用前者更好：
|
||
模型不会浪费轮次去试。
|
||
5. **task（子代理）能绕过父会话权限** —— 实测中模型发现自己没 write，**主动委派给
|
||
一个带 write 的子代理写成了**。plan/workspace 必须 `task deny *`。
|
||
6. **bash 能绕过 edit 的路径限制** —— 模型用 shell 重定向写成了本该被 deny 的文件。
|
||
所以 workspace 档必须同时管 bash，只管 edit 没用。
|
||
|
||
另：opencode 原生有 `plan_enter` / `plan_exit` 权限项，与我们的 plan 档**撞名但语义
|
||
不同**（那是它自己的计划模式开关），不碰。
|
||
|
||
附带收益：dsh 本机配的是 `danger-full-access` → `approval: "never"`，而
|
||
`ApprovalService.decide()` 里 `if (effectivePolicy === "never") return "rejected"`
|
||
**在 waterfall 之前短路** —— 所以整个「权限转邮件」链路在 dsh 上从未真正跑起来过。
|
||
按档位下发 `sandbox/mode` 后，workspace 档的会话才会拿到 `approval: ask`。
|
||
|
||
#### 已完成
|
||
|
||
- [x] `models/permission_mode.go`：三档常量、`NormalizePermissionMode`（非法值
|
||
fail-closed 到默认档而非 full）、`ModeAtMost`（继承与取整共用一个判据）、
|
||
`ModeNeedsHuman`、native/advisory 强制力。12 例测试 + 2 组负向对照
|
||
- [x] schema 三处同步：`sessions.permission_mode`（旧库默认 workspace，不追授全权）、
|
||
`sessions.permission_enforcement`（旧库默认 advisory，不替没自报的插件宣称
|
||
「档位在这里是被强制的」）、`agents.mode_enforcement`
|
||
- [x] `repo/permission_mode.go`：读写 + `InheritedMode` 继承 + `AgentModeEnforcement`
|
||
- [x] 读路径三处加列：`GetSessionByID` / `ListSessionsFor` / `ListContactsFor`
|
||
- [x] `me.go` 人发信可指定档位（人是权限的源头）；非法值报 400 而不是静默用默认档
|
||
—— 他以为给了 plan 实际拿到 workspace，比报错更坏
|
||
- [x] `permission.go` 按档位决定这次询问该不该存在；删管理员兜底，409 恢复可达
|
||
- [x] 日历会话给人类创建者设 owner（否则删掉兜底后，人建的提醒触发时 Agent 的
|
||
权限询问会因发件人是 `calendar` 而在线索上找不到人类 → 误伤成 409）
|
||
- [x] SSE 与补拉路径下发 `permission_mode` / `permission_enforcement`
|
||
（补拉路径必须有：否则 plan 档的任务在插件重启后悄悄变成 workspace 档）
|
||
- [x] `lib/permission-mode.js` 四平台翻译表（三方逐字节相同，已纳入
|
||
`check-shared-libs.sh`）。32 例测试 + 4 组负向对照，六条实测结论逐条钉死
|
||
|
||
#### P0：判据错误（不修则以上代码失效）
|
||
|
||
- [ ] **`parentMailID == nil` 不等于「新建会话」** —— 省略 session 位复用默认会话时
|
||
它也是 nil。实测：第一封 `max_rounds=7` → 第二封省略该字段 → **预算被冲成 20**。
|
||
这是**预存 bug**（配额那段注释正在论证这不该发生，守卫写错了），而我的
|
||
`permission_mode` 抄了同一个守卫 —— 第二封信会静默把 plan 档改成 workspace。
|
||
修法：`resolveTarget` 返回 `created bool`，只有真新建才设预算与档位
|
||
- [ ] **四个插件 `send_mail` 补传 `from_session_id`** —— 否则 `InheritedMode` 永远走
|
||
回落分支，继承是假的。这是唯一可靠来源：一个 Agent 可同时有多条活跃会话，
|
||
服务端猜不出它此刻属于哪条
|
||
|
||
#### P1：三条建会话路径漏设档位
|
||
|
||
- [x] `forward.go` 转发 —— `LoadForwardSource` 已返回源邮件（含 `SessionID`），
|
||
用 `InheritedMode(&src.SessionID, 默认档)`。不修则 plan 档转发出去就升到 workspace
|
||
- [x] `calendar_events` 加列 `permission_mode`（schema 三处同步）+ 日历投递接线：
|
||
- 人建日程可指定；**Agent 建日程用它当时所处会话的档位定死，不许自选**
|
||
- 投递时新建会话 → 用事件档位；**复用会话 → `ModeAtMost(会话现档, 事件档)`**
|
||
取更严，不能因复用而提权
|
||
- 堵住提权路径：plan 档的 Agent 建一个日程，触发时新会话拿默认档 workspace ——
|
||
它绕过 plan 档去写文件了，只是延迟了几分钟
|
||
- [x] adopt 接管平台会话 —— 无父会话，用默认档，在 `AdoptPlatformSession` 内显式写入
|
||
而不是靠 DB 默认值
|
||
|
||
#### P2：数据出不去
|
||
|
||
- [x] `GetSessionMails`（会话视图）与 `ListSentBy`（发件箱）的 `models.Mail` 补两列 ——
|
||
只改了 `ListInbox`，前端要显示档位徽标时这两条路径拿不到值
|
||
- [x] `PUT /sessions/{id}/permission` 端点 —— 已在 `me.go` 注释里引用但未实现，
|
||
对话页要靠它改档
|
||
|
||
#### P3：测试
|
||
|
||
- [x] `repo/permission_mode_test.go`：继承、取更严、脏值回落
|
||
- [x] handler 档位判定 + 409 可达性（负向对照：恢复管理员兜底 → 用例必须失败）
|
||
- [x] `notify` 两个新字段（挂真实 SSE 客户端读帧，沿用 `notify_test.go` 现有手法）
|
||
- [x] 预算不被冲的回归用例（钉住 P0 第一项）
|
||
|
||
#### P4：插件接线
|
||
|
||
- [x] dsh：`presets.mount` 注册工具 + `applyPermissionMode`（sandbox/mode + approval/policy）
|
||
+ 心跳报 `native`（af61a37）
|
||
- [x] opencode：`session.create({permission})` 按六条实测结论下发 + 心跳报 `native`（3bb419f）
|
||
- [x] pi：tool_call hook 按档位判定（plan 直接 block / workspace 问人 / full 放行）
|
||
+ 心跳报 `native`（0c98fab）
|
||
- [x] homeagent：`permission_mode.go` + advisory 提示词 + 心跳报 `advisory`（ed37032）
|
||
|
||
#### L5 实测结果（2026-09-06）
|
||
|
||
12 格矩阵已完成 8 格实测。关键发现：
|
||
|
||
| 平台 | plan | workspace | full | enforcement |
|
||
|---|---|---|---|---|
|
||
| **pi** | ✅ bash block（无权限询问） | ✅ bash 一律问人（无法静态判路径） | ✅ bash 直接执行 | native |
|
||
| **opencode** | ✅ briefing 生效，模型自愿遵守 | ✅ briefing 生效 | ✅ briefing 生效 | advisory |
|
||
| **dsh** | ✅ 写文件真被拦（read-only 沙箱；echo 命令仍可跑） | ✅ 目录内可写；/tmp 属允许临时目录不询问 | ✅ danger-full-access | native |
|
||
| **homeagent** | ⚠️ 只在提示词告知，模型不遵守 | ⚠️ 只在提示词告知 | ⚠️ 只在提示词告知 | advisory |
|
||
|
||
*opencode session.create 1.18.29 不支持 permission 参数，改为提示词 advisory 路径，模型自愿遵守（plan 档回信说明被拒）。dsh Landlock ABI 版本旧导致 partial enforcement。
|
||
|
||
结论：**pi 是唯一 100% 平台级强制**。opencode advisory 路径模型自愿遵守。dsh 有真沙箱但内核 ABI 限制了完整性。
|
||
|
||
#### P5：前端与文档
|
||
|
||
- [x] types / API / 卡片档位徽标 / 对话页档位选择器 / 新建邮件档位选择
|
||
（两个字段成对显示：要求档位 + 实际强制力）（be61724）
|
||
- [x] `docs/PLUGIN-CONTRACT.md` 新章节 + 平台差异表补一行（已有）
|
||
|
||
|
||
---
|
||
|
||
已知取舍，尚未处理：
|
||
|
||
- 前端有 Markdown XSS 与窄屏结构性回归，但没有**渲染组件跑断言**的测试
|
||
- 深色主题未做
|
||
- 窄屏实测脚本已入库（`client/electron/test/manual/`），但没进 CI ——
|
||
要一个 headless 环境加一个测试用 Gateway 实例
|
||
- 登录限速与新建会话限速已改为 DB 事务（rate_limits 表），多实例部署不再各自计数
|
||
- SQLite 抄送查询走 `json_each` 全表展开，无索引；单机量级下够用，
|
||
百万级邮件时需要加物化列或换回 PostgreSQL
|
||
|
||
---
|
||
|
||
### 7.12 全面修正：让平台真正可用（本轮）
|
||
|
||
本轮起因是排查附件链路，结果连带挖出四类问题。它们的共同形状是**静默成功** ——
|
||
请求返回 200、日志干净、界面看着正常，而实际的事没有发生。这类 bug 能活很久，
|
||
因为没人会去核对一个成功的请求。
|
||
|
||
#### A. 附件链路
|
||
|
||
| # | 问题 | 状态 |
|
||
|---|---|---|
|
||
| A-1 | homeagent 按**顶层** `attachment_id` 解上传响应，而服务端返回 `{"attachment":{…}}` → 三个字段全零值，模型看到 `id= filename= size=0KB` | 已修 |
|
||
| A-2 | homeagent 的 `send_mail` **根本没声明** `attachment_ids` 参数，提示词还教模型传 `attachments:[{…}]` | 已修 |
|
||
| A-3 | `size/1024` 让 800 字节的附件显示成 `0KB` | 已修（`formatSize`） |
|
||
| A-4 | 挂载失败（403/409）时**邮件已入库、已通知、预算已扣** —— 收件方收到一封没有附件的邮件，发件方收到 4xx 以为没发出去 | 本轮修 |
|
||
| A-5 | 磁盘上 7 个 blob 没有任何库记录指向，GC 永远扫不到（它只按库记录走） | 本轮修 |
|
||
|
||
A-1 + A-2 叠起来意味着 **homeagent 的附件发送从来没成功过一次**。
|
||
没有任何一层报错：HTTP 200、文件落盘、库里登记，只是那个 id 是空串，
|
||
24 小时后 GC 把没人引用的文件清掉，现场不留痕迹。
|
||
|
||
#### B. 请求解析：未知字段必须报错
|
||
|
||
A-2 之所以能活那么久，根因在服务端：`json.Decoder` 默认**忽略未知字段**。
|
||
|
||
```
|
||
$ curl -X POST /mail/send -d '{…,"attachments":[{"attachment_id":"598f100e…"}]}'
|
||
HTTP 200 {"mail_id":"2a64fdc8…", …}
|
||
$ sqlite3 "SELECT COUNT(*) FROM attachments WHERE mail_id='2a64fdc8…'"
|
||
0
|
||
```
|
||
|
||
这是 `I-5`（失败必须当场可见）在请求解析层的落点。改法：`Decode` 打开
|
||
`DisallowUnknownFields`，并把**本端点接受的字段一并列出来** —— 只说「不认识 x」
|
||
的话，调用方仍要去翻服务端源码才知道对的拼法，而拼错字段名恰恰是最容易犯、
|
||
最难自查的错。
|
||
|
||
心跳是唯一的例外（`DecodeLenient`）：那条路径的职责是「我还活着」，插件比服务端新、
|
||
多带一个字段时，代价不该是整个心跳体（含会话快照与模型目录）被丢掉。但**必须在
|
||
响应里回报** `unknown_fields`，否则又变成一次静默忽略。
|
||
|
||
严格化的爆炸半径已逐个核对（前端 30 个写端点 + 四桥所有 payload + demo 脚本 +
|
||
三种嵌套结构），只有一处真的会被打破：**日历创建端点缺 `status` 字段**，
|
||
而前端 `CalendarEventEditor` 无条件发它。顺带把 `status` 的取值也校验上 ——
|
||
此前 update 端点接受任意字符串，写进库就成了一个调度器不认识的状态。
|
||
|
||
#### C. 人 / Agent 的区分在读路径上缺失
|
||
|
||
`addr-verify` 报的两项失败追下去是**数据完整性问题而非显示问题**：
|
||
|
||
前端用 `mail.to_workspace ? ws : ''` 当「这一方是不是 Agent」的判据。
|
||
而 `to_workspace` 为空的 Agent 收件人有 **25/118 封**（人给 homeagent 发信、
|
||
权限决策回信、Agent 间转发…都不带 path 位），于是 `pi` 被渲染成裸名字、
|
||
会话别名跟到了人身上。
|
||
|
||
判据本身选错了。服务端早就有 `IsHumanUser`，也已经在收件箱列表路径上算过
|
||
`from_human`，但另外**四个读路径**（单封读、会话读、发件箱、会话内单封读）都没带。
|
||
补 `from_human` + 新增 `to_human`，前端改用它。
|
||
|
||
> 不能用 `session.from_agent` 代替：它的语义是「谁发起了这条会话」，
|
||
> 实测有 45 封邮件的收件 Agent 不等于 `from_agent`。
|
||
|
||
#### D. 「Agent 间不自动转发」没有写进契约
|
||
|
||
代码四桥齐全（`lib/relay-policy.js` + `relay_policy.go`），但 `docs/PLUGIN-CONTRACT.md`
|
||
里**只有共用模块表的一句括注**，没有规范条款。更糟的是 `B-3.4` 仍无条件写着
|
||
「提示词里写明回信由插件自动发」—— 与规则直接矛盾。照文档实现的新插件会做错。
|
||
|
||
连带三处：
|
||
|
||
- SSE `new_mail` 的字段表缺 `from_human` / `in_reply_to` /
|
||
`permission_mode` / `permission_enforcement`（四个都已在下发，文档没跟上）
|
||
- `deploy/remote-agent-demo.py` **无条件回信**，两个这样的 demo 对上就是
|
||
ping-pong，只有会话预算能刹住
|
||
- 该脚本指向的 `docs/PLUGIN-GUIDE.md` 已在 `289f37f` 删除
|
||
|
||
#### 验收
|
||
|
||
- [ ] A-4：附件挂载失败时邮件**不入库**（回滚），预算不扣，`relay_key` 归还
|
||
- [ ] A-5：`blob.Store` 可枚举 + GC 反向扫盘，一次跑掉 7 个孤儿
|
||
- [ ] B：`attachments` 这类拼错字段名返回 400 且列出正确字段；日历创建带 `status` 仍 200
|
||
- [ ] C：`GET /mail/{id}` 返回 `from_human` / `to_human`；`addr-verify` 两项转绿
|
||
- [ ] D：契约文档有 `B-5.6` 条款；demo 按 `from_human` 决定是否回信
|
||
|
||
### 7.14 DSH 主动询问邮件桥接（严重阻塞缺口）
|
||
|
||
本轮生产问题：DSH 邮件会话调用 `ask_user_question` 后一直停在询问状态，AgentMail
|
||
里没有任何待处理邮件。根因不是 SSE 或 Gateway 丢信，而是桥只监听了
|
||
`approval/request`（危险工具的审批 seam），没有接管 `ask_user_question` 使用的
|
||
`ctx.userQuestions` seam。DSH Web UI 是后者唯一 provider；邮件驱动会话没有人在 DSH
|
||
页面作答，所以工具 Promise 永远不返回。
|
||
|
||
修复边界：
|
||
|
||
1. 在 DSH 的 `tools/execute` around-dispatch 中只拦截**邮件驱动会话**的
|
||
`ask_user_question`，不替换全局 `userQuestions` provider（该服务只允许一个 provider，
|
||
强行注册会与 Web UI 冲突）。
|
||
2. 每个问题按原始 `id/question/options/multi_select` 生成一封 Gateway 待处理邮件；
|
||
单选保留选项原文，自由文本与多选用备注输入承载。多问题按顺序询问，全部回答后
|
||
还原 DSH 要求的 `{answers:[{id,selected,custom?}]}` 工具结果。
|
||
3. Gateway 的权限请求端点增加 `kind=question`：复用现有决策人追溯、幂等 relay_key、
|
||
待办列表与 SSE 回传，但**不套权限档位判定**（plan/full 也可能需要补充信息）。
|
||
`kind=permission` 保持原行为。
|
||
4. 待决映射必须在发 HTTP 请求前登记，堵住“人快速作答、SSE 先于 map 写入”的竞态；
|
||
abort、插件卸载、永久 HTTP 失败均 fail closed，不留下悬挂 Promise。
|
||
5. 前端把询问类待办显示为“等待回答”，自由文本/多选回答未填写时禁止提交；仍复用
|
||
现有待处理入口，避免再造第二套不可见队列。
|
||
|
||
验收：
|
||
|
||
- [ ] 单选询问经邮件选择后，DSH 工具拿到原始选项标签并继续运行
|
||
- [ ] 无选项询问要求填写文本，空回答不能提交
|
||
- [ ] 多选询问可提交多个原始标签，未知标签不被伪造为有效选择
|
||
- [ ] 两个问题按顺序往返，最终答案数组保持原始 question id 与顺序
|
||
- [ ] plan/workspace/full 三档中的主动询问均可送达；危险工具审批仍只在 workspace 产生
|
||
- [ ] 非邮件驱动 DSH 会话继续使用 Web UI provider，不受桥影响
|
||
|
||
### 7.13 桥进程异常上报与可靠重试
|
||
|
||
本轮起因：桥进程意外终止只留在 journal，用户邮箱没有任何提示；同时“自动重连”
|
||
与“处理中任务重试”被混为一谈。现状其实已有两层：systemd 对进程做指数退避重启，
|
||
四桥 SSE 断线后自动重连；但它们不能回答“刚才正在处理的那封邮件怎么办”。
|
||
|
||
按三层修复，职责不能混：
|
||
|
||
1. **进程层由 systemd 自愈**：保留 `Restart=` + `RestartSteps=6` +
|
||
`RestartMaxDelaySec=5min`。插件不在进程内部造第二个 supervisor。
|
||
2. **异常退出必须发邮件**：共用 `deploy/service-failure-notify.mjs` 挂到
|
||
`ExecStopPost`，读取 systemd 的 `SERVICE_RESULT/EXIT_CODE/EXIT_STATUS`；正常停止不报，
|
||
exit-code/signal/oom-kill/timeout/watchdog 才报。Gateway 暂不可达时落本地 spool，
|
||
下次 `ExecStartPost --flush` 补发。通知用稳定 `relay_key` 幂等，避免即时发送与补发重复。
|
||
3. **处理中任务必须重试**：pi worker 无 `done` 就按 1s/2s 有界重投，最多 3 次；
|
||
`done(ok=false)` 属于已经给出明确失败结论，不盲目重跑。重试耗尽后给原发件人一封
|
||
故障邮件。整进程重启后仍由未读补拉兜底；homeagent 已有落盘 ledger，保留现状。
|
||
4. **网络层继续重连**：SSE 3–5 秒重连、心跳下一周期再试，不把短暂网络抖动升级成
|
||
进程重启。
|
||
|
||
验收：
|
||
|
||
- [ ] notifier dry-run 能区分正常停止与异常退出，敏感密钥不进入正文/日志
|
||
- [ ] Gateway 暂不可达时报告落盘，`--flush` 后只发一次
|
||
- [ ] pi worker 首次异常退出后自动重投，同一会话仍串行
|
||
- [ ] 连续三次异常后停止重试并调用失败回报，不形成无限崩溃循环
|
||
- [ ] 四个桥宿主服务保留指数退避重启；正常 `systemctl restart` 不产生误报警邮件
|
||
|
||
---
|
||
|
||
## 文件清单（完整）
|
||
|
||
```
|
||
agentmail/
|
||
├── docs/
|
||
│ ├── MVP-SPEC.md # MVP 技术规格书
|
||
│ └── PLAN.md # 本文件
|
||
├── server/
|
||
│ ├── cmd/server/main.go # 入口 + 路由编排
|
||
│ ├── internal/
|
||
│ │ ├── config/config.go
|
||
│ │ ├── db/
|
||
│ │ │ ├── db.go # 连接 + 方言适配（SQLite / PostgreSQL）
|
||
│ │ │ ├── migrate.go
|
||
│ │ │ └── migrations/
|
||
│ │ │ ├── init.sql # PostgreSQL schema
|
||
│ │ │ └── init_sqlite.sql # SQLite schema（默认）
|
||
│ │ ├── models/
|
||
│ │ │ ├── models.go
|
||
│ │ │ ├── address.go # name@path.session 解析
|
||
│ │ │ └── address_test.go
|
||
│ │ ├── repo/
|
||
│ │ │ ├── repo.go
|
||
│ │ │ ├── users.go
|
||
│ │ │ └── keys.go # agent_keys / user_keys
|
||
│ │ ├── handler/
|
||
│ │ │ ├── helpers.go # 错误映射 + 别名规范化
|
||
│ │ │ ├── alias_test.go
|
||
│ │ │ ├── agents.go
|
||
│ │ │ ├── mail.go
|
||
│ │ │ ├── me.go # 人类自己的邮箱（原 human.go）
|
||
│ │ │ ├── contacts.go
|
||
│ │ │ ├── permission.go
|
||
│ │ │ ├── sessions.go # 含 POST /sessions/:id/sync
|
||
│ │ │ ├── events.go # SSE（鉴权后分流）
|
||
│ │ │ ├── keys.go # 密钥管理
|
||
│ │ │ ├── ratelimit.go # 登录失败限速
|
||
│ │ │ └── auth.go
|
||
│ │ ├── sse/manager.go
|
||
│ │ ├── static/static.go # go:embed 前端产物
|
||
│ │ └── middleware/
|
||
│ │ ├── auth.go # Agent 鉴权
|
||
│ │ └── user.go # 人类用户鉴权
|
||
│ └── go.mod / go.sum
|
||
├── plugins/
|
||
│ └── opencode-mail-bridge/ # 第一个接入平台
|
||
│ ├── package.json
|
||
│ └── index.js # 凭证 + HTTP + SSE + 四个工具 + event 钩子
|
||
├── client/electron/
|
||
│ ├── src/
|
||
│ │ ├── api/
|
||
│ │ │ ├── client.ts
|
||
│ │ │ └── sse.ts
|
||
│ │ ├── stores/
|
||
│ │ │ ├── mailStore.ts
|
||
│ │ │ ├── sessionStore.ts
|
||
│ │ │ ├── contactStore.ts
|
||
│ │ │ ├── uiStore.ts
|
||
│ │ │ └── authStore.ts
|
||
│ │ ├── components/
|
||
│ │ │ ├── icons.tsx # 纯 SVG，无 emoji
|
||
│ │ │ ├── Sidebar.tsx
|
||
│ │ │ ├── MailList.tsx
|
||
│ │ │ ├── ContactPanel.tsx
|
||
│ │ │ ├── MailView.tsx
|
||
│ │ │ ├── ComposePage.tsx # 右侧整页写信
|
||
│ │ │ ├── AddressInput.tsx # 三段式补全
|
||
│ │ │ ├── LoginPage.tsx
|
||
│ │ │ ├── SetupPage.tsx # 首启初始化向导
|
||
│ │ │ ├── AccountPage.tsx # 个人中心 + 连接密钥
|
||
│ │ │ ├── AdminUsersPage.tsx # 用户管理 / Agent 密钥
|
||
│ │ │ └── KeyPanel.tsx # 两处共用的密钥面板
|
||
│ │ ├── types/index.ts
|
||
│ │ ├── App.tsx
|
||
│ │ └── main.tsx
|
||
│ ├── test/markdown-xss.test.mjs # XSS 回归（npm test）
|
||
│ ├── index.html
|
||
│ ├── package.json
|
||
│ └── vite.config.ts
|
||
├── deploy/
|
||
│ ├── agentmail-gateway.service
|
||
│ ├── opencode-serve.service
|
||
│ └── install.sh # 构建 + 嵌入 + systemd 一键装
|
||
└── README.md
|
||
```
|