jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
76 Commits 1 Branch 0 Tags
f9d757b5e5f5b7962e2c004ca5ced30b812c1335
Commit Graph

8 Commits

Author SHA1 Message Date
JianFeeeee
f9d757b5e5 chore: directory migration - gateway→server, web→client/electron 2026-09-08 19:16:35 +08:00
JianFeeeee
a101c2fada 停用/恢复文案说清密钥不会自动回来 + 原子部署脚本 
## 起因

本会话踩到一次：浏览器测试点了 opencode 的「停用」按钮验证确认流程，
停用连带撤销全部密钥。插件从此拿着已撤销的密钥重试了 18 小时
（gateway 日志 2690 次 401），而 UI 只说了「已停用」。

恢复时同样没提示「密钥不会自动回来」，点完恢复以为就完事了。

## 文案

后端 `AdminSetAgentStatus`：
- 停用 detail 补一句「停用期间别人发信给它会收到 409」
- 恢复 detail 改成「停用时撤销的密钥不会自动回来 —— 必须在密钥面板
  重新签发一把并写进该插件的配置，否则它会一直拿旧密钥重试并被拒（401）」
- 恢复响应加 `needs_new_key: true` 字段，前端可据此做更强的提示

前端 QuotaPanel：恢复成功的 notice 不再是「已恢复」四个字，
把重新签发这一步说全；面板说明与按钮 title 同步。

## AdminDeleteAgent 两处修正

- 硬编码 `name == "jianf"` 改成按 `repo.IsHumanUser` 判定 —— 换管理员时
  硬编码会失效，而人类账号不该走 Agent 删除端点
- detail 原来说「日历事件已保留」，实际 `DeleteAgent` 把 active 事件置为
  cancelled（留着会由调度器一直触发，而发信人已不存在）。文案改成实际行为

## deploy/redeploy-gateway.sh（新）

日常改后端不必重跑 install.sh（它重装 npm 依赖、重写 systemd 单元、
重新生成 env）。这个脚本做手工 `stop → cp → start` 不做的四件事：

- `sqlite3 .backup` 备份数据库 + 立即 `PRAGMA integrity_check` 复核。
  不用 cp：WAL 模式下 cp 会拿到主库与 -wal 不同步的快照
- `install -m 0755` 原子替换二进制。install 本质是 rename，要么完整
  换掉要么原样不动；cp 是就地写入，中途失败会留下半截文件且旧的已被覆盖
- 旧二进制留档并打印可直接粘贴的回滚命令
- 后置验证清单：服务 active / /health 可达 / 近 2 分钟无 panic /
  SSE 重连计数。任一项不过**自动回滚**，不「先上着再修」

`--dry-run` 只打印动作，`--skip-tests` 急救用，`--skip-web` 跳过前端同步。
纪律来自 git-release-discipline skill 第五章。

## 验证

- 脚本 dry-run + 真实跑通一次：备份 integrity_check=ok、原子替换、
  9 个 SSE 客户端重连、验证四项全绿
- 停用/恢复文案线上实测；`DELETE /admin/agents/jianf` → 403「是人类用户」
- 端到端：jianf → opencode「部署脚本验收」→ 回信「部署验收 OK」
- 全量测试：gateway 全包 / web 176 / opencode 217 / pi 288 / dsh 241 /
  homeagent go ok；三方共用模块同源检查通过
 2026-09-05 10:10:13 +08:00
JianFeeeee
e6fd2fafdc feat: agent 邮件寻址能力全面补齐 + .new 别名替换 
## 别名替换（让 .new 邮件可寻址）

repo/autoalias.go: AutoAliasFor + EnsureSessionAlias
- .new 建完会话立刻给别名（形如 dsh-重构导入路径）
- 名字与主题都要：只用主题跨 Agent 撞名，只用名字看不出聊什么
- sanitizeAliasPart 只留 unicode.IsLetter/IsDigit，其余折 -
- 撞名追加 -2/-3，全占用退 session-<uuid前8位>
- 不复用 SyncSessionAlias：那个假定已存在且跳过 manual
- 条件写入 WHERE alias IS NULL OR ''，并发安全
- resolveTarget 的 .new 与默认会话两条路径都调

notifyRecipients 加三个字段（每个收件方拿到自己那个地址的版本）：
- session_alias / reply_address / self_address
- 别名为空时退回省略 session 位，绝不写 new

FormatAddress(name,path,session) 空 path 也必须留 @ 与 .

## Agent 侧寻址发现（五个只读端点）

handler/agent_discovery.go:
- /agent/contacts + /agent/contacts/suggest（三段式补全）
- /agent/mail/{id} + /agent/mail/{id}/thread
- /agent/sessions/{id}/participants
- 不复用人类路由：scope 不同、审计需求不同
- 一律只读：归档/改名/权限决策仍只有人能做

repo/participants.go: SessionParticipants 逐封扫 from/to/cc
- Roles 用集合、MailCount 只数发信（0=还没开口的人）
- 发件人 path 不取 from_workspace（那列存的是 Agent 名）

repo.SuggestPaths 重写：mails.to_workspace（按 MAX(created_at) 倒序）
+ agents.workspaces 并集。原只读 workspaces，官方插件传 [] 永远空

## 共用模块（三插件逐字节相同）

lib/addressing.js: formatAddress/roleOf/replyAddressFor/selfAddressFor/participantsOfMail
lib/discovery.js: renderNameSuggestions/renderPathSuggestions/renderSessionSuggestions/
                  renderParticipants/renderContacts/renderThread

lib/inbox-format.js: renderMail 新增收件人/身份/可投递地址三段
  - selfName 参数（兼容旧调用不传的情况）

check-shared-libs.sh 纳入 addressing + discovery

## 插件侧

opencode: suggest_address + list_contacts + session_participants + read_thread + read_mail
dsh: 同上 + forward_mail（此前只有 opencode 有）+ upload_attachment 改真 multipart
pi: 同上（createMailTools 加 agentName 参数）

dsh: ctx.agents.create id collision 改为 readSession 探测后 resume
dsh: 关键路径日志改 console.error（ctx.logger 不进 journalctl）

## 测试

repo: autoalias_test.go 11 + participants_test.go 7 = 18 例
plugins: addressing.test 17 + discovery.test 23 + inbox-format.test 31 = 71 例
go test ./... + npm test（opencode 155 + dsh 173 + pi 199）全绿
端到端验证：admin 发 dsh@....new 抄送 opencode@....new
  → dsh 用 session_participants 取到地址 → send_mail 给 opencode
  → 地址取自工具返回值（.crisp-planet），未手工拼写
 2026-09-03 12:09:12 +08:00
JianFeeeee
289f37f7fb docs: PLUGIN-GUIDE 重写为 PLUGIN-CONTRACT（可核对的插件规格） 
原 PLUGIN-GUIDE 是叙事式的「怎么做 + 踩过的坑」，读者要自己从散文里推断
「我到底必须做什么」。接第三个平台时这不够用 —— 尤其当照着实现的是一个代理。

改为规格式，编号可引用、强度明确标注、每条尽量给出可机械核对的判据。
旧文档的内容全部保留（迁进第八、九节），另补上原先没有的四类：

## 一、能力矩阵（新增）

回答「这个平台能不能接」。七项必需能力（C-1..C-7）加七项可选（C-8..C-14），
每项给出判据。附一个七问自检 —— 任何一问答不出来就先别写代码。

其中 C-4「轮次结束信号必须能区分成功与出错」在两次适配里都被漏掉过，
两次都造成「无效模型被判成成功」，所以单独标了出来。

## 二、行为约定（重写）

原先散在各节的要求收拢成一个状态机，按事件逐条规定：B-1 启动 / B-2 心跳 /
B-3 new_mail / B-4 permission_decision / B-5 轮次结束 / B-6 无法处理时回信 /
B-7 启动补拉 / B-8 权限询问 / B-9 关停。

## 四、降级语义（新增）

平台缺某项能力时的确切退化路径（D-1..D-7）。原文档只说了「可选」，
没说缺了之后该怎么办 —— 于是「不支持权限钩子」很容易被实现成
「提供 request_permission 工具补偿」，而那正是 I-1 反对的模式。

## 六、不变量与禁止事项（新增）

12 条 MUST NOT，每条附「违反会怎样」。这些是测试全绿、跑起来也不报错，
但行为就是错的那类问题 —— 例如拉取失败时传 [] 而非省略字段会清空服务端目录。

## 七、验收清单（新增）

八组可勾选项，每条给出具体命令：grep 自查禁止事项、sqlite3 查在线状态与
配额未被消耗、停插件发信再启动看补投日志。

## 核对过的事实

写完逐项核对了代码，不是凭记忆：
- 12 个端点全部在 main.go 里存在且方法一致
- 发信 9 个字段名与 sendMailRequest 的 json tag 一致
- 心跳响应 12 个字段名与 handler 一致
- 九个数字（30s 心跳 / 25MB 附件 / 20 次每小时 / 补投 5 封 / 快照 200 条 /
  模型上限 10 / 目录上限 300 / 降级超时 60s / inbox 默认 5）都能在代码里找到出处
- 验收清单里的六条 sqlite 查询都在生产库上跑通
- 38 个编号无重复，18 处交叉引用全部有定义

引用同步：PLAN.md、PHASE7-REMAINING.md、API.md、README.md、
install.sh、check-shared-libs.sh。
 2026-09-03 08:09:54 +08:00
JianFeeeee
7c9be9fd58 docs: 插件适配指南 + 共用模块提取（为接入更多平台做准备） 
两次适配（opencode、DeepSeek Harness）里的方法与坑此前散落在提交信息和
代码注释里，接第三个平台时要重新翻。这次固化成文档，并把与平台 SDK 无关的
逻辑提到共用模块。

## docs/PLUGIN-GUIDE.md

八节：职责边界、必须实现的六件事、会话命名回写、平台会话快照上报、
平台差异对照表、踩过的坑（按排查成本降序）、新平台适配清单、共用模块清单。

三条设计原则贯穿全文，后面每一节都是它们的推论：

1. **平台原生信号才是真相来源**，不要求模型「记得」调工具 —— 因此不提供
   request_permission（改挂权限钩子）、不要求模型主动回信（改在「一轮结束」
   的平台信号上自动转发）
2. **插件代劳的转发不消耗配额** —— 因此这两类转发带 relay + relay_key
3. **平台命名优先** —— 因此创建会话时不传占位标题（那会掐掉平台自己的命名机制）

「踩过的坑」一节按排查成本排序，头一条是花了一下午的 followup() 参数形状。

## 共用模块提取

`lib/inbox-format.js`（新）：收件箱渲染与已读策略。三条规则各对应一次错误行为，
而它们与平台 SDK 无关：

- 附件必须带 attachment_id（只说「有附件」模型无从下载）
- 抄送人要显示（不显示模型以为是私信，回信时漏掉其他参与方）
- 只标本次列出的、status=all 时不标（limit 之外的还没看过；把历史邮件标成已读
  会让下一轮的新邮件混在里面认不出来）

顺带修好两处不一致：DSH 的 read_inbox 此前**完全没有标记已读**（每轮重复捞同一批），
且默认 status=all（同上）；附件大小两边一个显示字节数一个显示 KB/MB。

`lib/workspace.js`：提到两侧共用。签名从 (workspace, fallbackKey) 改为
(workspace, fallback) —— 各平台的兜底不同：opencode 有插件启动时的 directory，
DSH 只能落到 ~/.dsh/mail-sessions/<会话>（mailSessionFallback）。
opencode 侧此前是内联的三行判断，没有「目录不存在时不创建」与「拒绝相对路径」
这两条保护。

## deploy/check-shared-libs.sh

`lib/` 与 `test/` 下的共用文件必须逐字节相同，纳入 install.sh 门禁。

一侧改了另一侧没改，两个平台的行为就会悄悄分叉：同一封邮件在 opencode 那边
标了已读、在 DSH 那边没标，而两处代码看起来都「对」。这类分叉没有测试能发现，
只能靠 diff。

## 文档同步

- PLAN.md §7.7 从「待做」改为已完成，补 7.7.1（工作目录归属）与
  7.7.2（平台会话快照）两节，记录根因而非只记改法
- API.md 加「心跳与平台会话快照」章节；SSE 章节补 new_mail 与
  permission_decision 的 payload 说明（to_workspace 的语义、relay_key 的用途）
- PHASE7-REMAINING.md 移除已完成的 7.7，新增「每平台可用模型范围」的进展
  （repo 层已就绪，handler/插件/前端待做）
- README 文档索引与项目结构

验证：两插件共 136 个测试通过，同源校验通过，Go/前端全绿；
端到端发信 → DSH 用新的 read_inbox 渲染读取 → 自动回信 213 字节。
 2026-09-02 20:28:19 +08:00
JianFeeeee
ca64d12057 feat: 工作区归属修复 + 平台会话同步 + 对话树整树展开 + DSH 插件 
四个各自独立的生产缺陷，共同的根源都是「本该属于会话的属性没有存在会话上」。

## 1. dsh 指定工作目录完全失效（所有会话落进「未分组」）

插件建会话时用的 cwd 是自己拼的 `~/.dsh/mail-sessions/mail-<uuid>` ——
每封邮件一个全新的空目录。DSH 与 opencode 都按 cwd 给会话分组，于是所有
邮件会话既不属于任何项目、彼此也不同组。

而 Gateway 从来没把地址里的 path 位发给插件：`notifyRecipients` 的 payload
只有 mail_id/session_id/from_name/subject，`to_workspace` 虽然入库了却不在
SSE 事件里，插件即使想用也拿不到。

- SSE `new_mail` 事件加 `to_workspace`。**每个收件方拿到自己那个地址的 path**，
  不是主收件人的 —— 抄送给 opencode@/a 与主发给 dsh@/b 是两个工作区
- 两个插件的 cwd 都改为取寻址的 path 位；不存在的目录**不创建**而是回退到
  兜底目录（一个笔误不该在磁盘上落下真目录，Agent 会在里面一无所获地干活）
- 拒绝相对路径：cwd 的相对基准是 harness 进程的启动目录，systemd 下通常是 `/`

## 2. 会话别名列不出工作区下的历史会话（无法选择）

workspace 只存在于 `mails.to_workspace` 上，「这个工作区下有哪些会话」必须
JOIN mails 再从收发双方的 workspace 里猜。而 Agent 回信时 from_workspace
填的是 **Agent 名**而不是路径，旧条件 `to_workspace = $p OR from_workspace = $p`
在只剩 Agent 回信可匹配时两边都对不上。

- `sessions.workspace` 新列，`CreateSession` 从地址的 path 位带入
- `SuggestSessionCandidates` 取代 `SuggestSessionsFor`：以会话自己的 workspace
  为权威，历史会话（该列为空）回退到 mails 反推 —— 升级后老会话不该消失
- `FindOrCreateDefaultSession` 同步改用会话的 workspace

## 3. 平台侧会话在补全里根本不存在

人直接在 opencode/DSH 界面上开的会话，Gateway 一无所知。

新增 `agent_platform_sessions` 镜像表，插件在心跳里上报快照。
**上报而非 Gateway 反向拉取**：当前架构是单向的（Agent 持密钥主动连 Gateway，
Gateway 从不外呼），反向拉取需要它保存各平台的地址与凭证，那是另一套信任模型。

- 与 sessions 表分开存：镜像里是别人家的会话，id 属于平台的 id 空间，没有
  本侧的 owner/预算/邮件。混进 sessions 会让每一处「按会话鉴权」都要先判断
  这条到底是不是真的本侧会话
- **整表替换而非增量合并**：平台侧删掉的会话必须从候选里消失 —— session 位是
  三态语义，指向不存在的会话直接 404
- **nil 与空数组语义不同**：插件拉不到列表时省略该字段（保留镜像），
  而不是传空数组把镜像抹掉
- **subagent 子会话不上报**：实测 DSH 的 list 里混着 49 条子会话，标题就是
  派活的提示词前缀（九条都叫 "You are auditing ONE file"），slug 全撞名；
  它们是父 agent 内部的工作单元，人往里发邮件毫无意义
- **slug 撞名只留最近那条**：服务端只能取其中一条，上报同名项只会让补全里
  出现几个点哪个都不确定的候选
- DSH 插件此前**完全没有心跳** —— Gateway 靠 last_seen 判在线，一直靠注册撑着

补全候选带标题与来源：`suggestions` 保留纯字符串数组（不打破已部署的前端与
第三方客户端），新增同序的 `candidates`。过滤时标题也参与匹配 —— 人记得的是
「缓存选型」而不是 brisk-harbor 这种随机短名。

## 4. 对话树看不见抄送与转发产生的分支

旧实现从锚点分「祖先链 + 子树」两路展开，而**兄弟节点既不是锚点的祖先也不是
它的子孙**：一封抄送给两个 Agent 的邮件收到两个回复，从其中一个看树永远看不到
另一个；挂在原件上的转发分支同理。

改为先 `ThreadRootOf` 上溯到线索根，再从根整树 BFS。只剩一个加载方向，
因此不再需要滚动位置补偿。前端补上抄送人列表与转发标记 —— 树上两个兄弟节点
为什么并列，唯一的解释就是父邮件抄送给了两个人。

## 5. DSH 插件（Phase 7.7）

卡了一下午的 `Cannot read properties of undefined (reading 'kind')` 根因是
`followup()` 的参数形状：DSH 要完整的 UserMessage（content + source），
而我照抄了 opencode 的 parts 数组。错误抛在 agent-loop 内部，不指向调用点。

- `agent/status` → idle 时自动转发最后一条 assistant 消息（对应 opencode 的
  session.idle），复用 relay-dedup 让位于模型的主动回信，走免配额通道
- `approval/request` 权限询问转邮件问人。与 opencode 的差异：那边的
  permission.ask 是同步钩子只能立即返回 ask，DSH 这边是异步 waterfall，
  可以真的等人 —— 拆插件时未决询问一律 fail closed，否则 await 永不返回
- 会话别名由模型标题派生（保留中文，去掉 `.` `@` `/` 等寻址分隔符 ——
  留在别名里会让它自己被解析器切开）
- 逻辑放 lib/ 下的纯函数并加测试：三类约定都是「错了不当场报错、只在深处
  炸一个无关错误」

## 其他

- `deploy/reset-demo.sh`：清空演示邮件数据，保留账号与密钥。备份用 `.backup`
  而非 cp（WAL 下 cp 拿到的是缺尾巴的库）；手工按依赖顺序删（SQLite 的
  foreign_keys 默认关，声明了 REFERENCES 也不级联）；只在目标是默认库时才碰
  systemd（演练时误停过一次生产服务）
- 插件 dist/ 不进版本库，install.sh 负责构建
- `permission_decision` 事件补 session_id：插件重启丢了待决映射时要靠它定位会话
 2026-09-02 20:05:51 +08:00
JianFeeeee
07e6b789b2 feat: 配额下沉到会话 + 窄屏覆盖式布局 + 工作列表卡片视图 
## 配额重构：废除 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 把插件测试也纳入部署前门禁
 2026-09-02 14:16:46 +08:00
JianFeeeee
0e754617a4 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