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

7 Commits

Author SHA1 Message Date
JianFeeeee
bf32369ebd docs/API.md: 补权限档位端点与字段（dsh 反馈的文档缺口） 
dsh 在鸿蒙计划反馈中指出 API.md 未收录权限档位相关：
- PUT /sessions/{id}/permission 端点
- GET /sessions/{id} 返回的 permission_mode/permission_enforcement
- 发信请求体的 permission_mode 字段
- new_mail SSE 事件的档位字段

补：
- 会话端点清单加 PUT /sessions/{id}/permission
- 会话对象字段表（permission_mode 三档 + permission_enforcement native/advisory）
- 新增「权限档位」节：三档语义、新建/续谈均可设定、Agent 继承约束
- 发信请求体 JSON 示例加 permission_mode + 说明（两种情形都生效）
- new_mail SSE payload 示例补档位字段（含 from_human/to_human/in_reply_to）

注：后端只有 PUT 没有 GET /sessions/{id}/permission，文档已注明读取走会话详情。
 2026-09-07 07:32:00 +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
9e5c557cdf feat: 跨主机 Agent 验证 + 离线邮件补投 + 400 指向具体字段 
7.8「跨主机 Agent 发现」原计划（Gateway + Registry 拆分、etcd/Consul 注册）
取消，改为验证现有协议已经够用。验证过程暴露两个真实缺陷，一并修掉。

## 为什么不做注册中心

它要解决「Gateway 怎么找到 Agent」，而这个问题在本架构里不存在：
连接方向是单向的 —— Agent 主动连 Gateway，Gateway 从不外呼。
远端 Agent 只需要一个公网 URL 加一把密钥，被叫方自己会打进来。
注册中心要解决的「被叫方在哪」根本没出现过。

同一个理由此前已经决定了平台会话同步走插件上报而不是 Gateway 拉取。

## 验证方式：一个纯标准库脚本

`deploy/remote-agent-demo.py` 在另一台主机（192.168.2.106）上跑，
不装 AgentMail 的任何代码。注册 / 心跳（带模型目录）/ SSE 长连 /
收件箱 / 标记已读 / 发信全通，Gateway 侧 status=online 且 last_seen 随心跳推进。
完整一轮往返跑通：admin 发给 remotebot@/tmp/remotebot-ws，脚本回信入库。

「协议层面已支持」的含义就是这个：跨主机不需要新组件，只需要三个环境变量。

## 缺陷一：SSE 只推连上之后的事件，没人补拉积压

写那个脚本时第一版只挂了 SSE，启动前发的邮件永远不会被处理。
查了才发现**两个正式插件也有这个洞** —— 原以为它们做了补拉，实际没有。
后果比明确的失败更难排查：邮件躺在收件箱里，而发件人以为 Agent 收到了。

新增共用模块 `lib/catchup.js`，两插件在首个成功心跳后补投一次。五条约束
都对应一种具体的坏行为：

- 只在**首个**心跳后补 —— 每轮都补会把「模型正在处理中、尚未标已读」的
  邮件重复投递
- 串行、一次最多 5 封 —— 每封都要起一轮模型，并发放出去等于对上游打 N 个
  并发请求，且最后几封要等前面全部跑完
- 与 SSE 共用 deliveredMails 去重 —— 心跳与 SSE 建连之间有个窗口，
  那期间到的邮件两条路都会到
- 按时间**正序**投（收件箱倒序返回）—— 倒着塞进去同一会话的上下文是乱的
- permission 类不补投 —— 原来的工具调用早随进程没了，没有可恢复的上下文

端到端两平台各验一次：停插件 → 发信 → 启插件 → 日志「补投 1 封离线期间的
邮件」→ 回信入库；随后在线再发一封确认只回一次。

## 缺陷二：400 只说 "Invalid JSON"，不说是哪个字段

脚本把 `workspaces` 传成字符串数组（它要 `[{name, path}]`），
得到的只是一句固定文案，只能靠翻服务端结构体才能发现。
两个官方插件都传 `workspaces: []`，所以这个洞一直没暴露；
第三方客户端没有「翻服务端源码」这个条件。

新增 `handler.DecodeBody`，22 处 `Decode` + 固定文案的调用点全部换过去：

    {"error": "字段 \"workspaces\" 类型不对：期望 object，收到 string"}
    {"error": "JSON 语法错误（第 8 字节处）"}
    {"error": "请求体为空"}

刻意不回显 encoding/json 的原文 —— 它带 Go 类型名（models.Workspace），
那是本侧的实现细节，不该出现在公开 API 的响应里。期望类型用 JSON 的说法。
截断的 JSON 走 io.ErrUnexpectedEOF 而不是 json.SyntaxError，单独一条分支，
否则会落到笼统的兜底文案里（写测试时才发现）。

## 验证

- Go：13 个新测试（decode_test.go 含「不得泄漏 Go 类型名」断言）
- 插件：两侧各 10 个补投测试，共 200 个
- 共用模块同源校验通过（catchup 已纳入 check-shared-libs.sh）
- 生产已部署
 2026-09-02 22:47:31 +08:00
JianFeeeee
89356d4a9b feat: 每平台可用模型范围 + 降级尝试 + 失败回报 
配置页为每个 Agent 平台划定「邮件场景下可用的模型」，插件按顺序逐个尝试，
全部失败把原因封装成邮件回复。目录由插件上报、管理员只做勾选 —— 手打模型名
会打错，而打错的后果要到真发邮件时才暴露成一次失败。

## 目录上报走心跳，不另设端点

模型清单会在运行中变（换 provider 配置、上游上下线、换 API key）。
只在注册时报一次的话目录会静静变陈，管理员在配置页选中一个平台其实调不到的
模型。心跳本来就是 30 秒一次的现成通道；另设一个 POST 等于给「目录是谁写的」
留两个答案，排查时要同时看两处。

心跳响应回传 `allowed_models`，因此管理员改了范围后最多一个周期生效，
不必重启插件。

与 platform_sessions 同一约定：拉不到目录时**省略字段**（保留现有目录），
传空数组会把配置页清成空白。

## 目录与选择分两张表

模型会从平台目录里消失（上游临时下线、换了 provider 配置）。合成一张带
allowed 标记的表时，整行被删就连带把管理员的选择也删了，模型回来还得重配一遍。
分开存之后「选了什么」是持久的，目录只决定「这一项现在是否可用」；
已选但不在目录里的标为 stale 显示出来 —— 不显示会让人以为自己没选过它。

## 最难的一点：模型失败不是同步抛出的

两个平台都踩了。`promptAsync()` 立即返回、`ctx.agents.create()` 不校验模型，
只包 try/catch 的话第二个模型永远不会被试到 —— 第一个无效模型会被判成成功。

必须等异步结论：
- opencode → `session.error` 事件（event 钩子在 deliverMail 之外，
  因此用 turnWatchers 表把两者接起来）
- DSH → `turn/end` 的 `reason.kind === 'error'`

DSH 还有个陷阱：**`assistant/chunk` 不能当成功信号**，它的 `finish` 子类型
也带错误 —— `{chunk:{type:'finish',reason:{kind:'error',failure:{code:'NO_ADAPTER'}}}}`。
实测「无效 provider 却判成功」正是因为把任意 chunk 当成了走通。判据要落在
chunk 的类型上：finish 看 reason，其余才意味着模型真的在产出。

超时按成功处理（60 秒窗口）：模型可能只是很慢，把慢当成失败会在换模型的同时
把已经在跑的那一轮丢掉。

DSH 换模型要换会话 id（`<原 id>-r1`）并 dispose 失败那个 agent：复用同一个 id
会让重试接在一条已经出错的会话后面，不 dispose 则 agent/status 还会为那个
死会话触发一次自动转发。

## 其他决策

- **范围优先于环境变量**：范围是运行时可改的策略，`AGENTMAIL_REPLY_*` 是部署时
  的兜底。反过来的话管理员在配置页改了却不生效，得去改 service 文件重启
- **范围为空返回 `[undefined]` 而非 `[]`**：空数组会让调用方一次都不试，
  而「管理员没配」的正确含义是不限定，不是「一个都不许用」
- **上限 10 个**：降级是串行的，选 50 个意味着最坏情况下一封邮件要等 50 次超时
- 前端 key 按**第一个** `/` 切分 provider/model：model id 可能含 `/`
  （如 `org/model-name`），按最后一个切会把 provider 切错
- 保存后用服务端返回的结果刷新界面而非回显入参：repo 层会跳过重复与空字段

## 验证

- Go 10 个新测试（含「模型从目录消失后选择必须留存」的直接回归）
- 两插件各 18 个模型范围测试，共 180 个
- 端到端四轮：正常路由 → 全部无效（收到失败回报邮件，used_rounds 保持 0
  确认走了免配额通道）→ DSH 降级（fake-a 失败 → llmsproxy/AUTO 成功）→
  opencode 降级（nonexistent/bad 失败 → AUTO 成功，日志确认「前 1 个失败」）
- 生产已部署，前端「模型范围」页可用
 2026-09-02 21:34:55 +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
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