jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 配额下沉到会话 + 窄屏覆盖式布局 + 工作列表卡片视图

Browse Source 
## 配额重构：废除 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 把插件测试也纳入部署前门禁
This commit is contained in:
JianFeeeee
2026-09-02 14:16:46 +08:00
parent 00ba69d899
commit 07e6b789b2
61 changed files with 3107 additions and 595 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
plugins/opencode-mail-bridge/index.js
View File

@ -3,6 +3,13 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync } from "no
import { randomBytes } from "node:crypto";
import { homedir } from "node:os";
import { join, dirname, basename } from "node:path";
// 自动转发去重的纯逻辑放在 lib/ 里：opencode 会把入口模块的每一个导出
// 都当成插件工厂，入口文件多导出一个东西就会 "Plugin export is not a function"。
import {
explicitSends,
noteExplicitSend,
shouldSkipAutoRelay,
} from "./lib/relay-dedup.js";
const GATEWAY_URL = process.env.AGENTMAIL_GATEWAY_URL || "http://127.0.0.1:8180";
const AGENT_NAME = process.env.AGENTMAIL_AGENT_NAME || "opencode";
@ -136,7 +143,9 @@ const sendMailTool = {
),
propose_reason: z.string().optional().describe("改名理由，一句话，展示给用户看"),
},
async execute(args) {
// context 带 sessionID：用它记下「模型这一轮亲手发过信」，
// 让 session.idle 的自动转发让位，避免同一件事发两封。
async execute(args, context) {
// 改名建议以 HTML 注释形式附在正文末尾，由网关解析后剥离。
// 选注释而不是自造标记：react-markdown 不解析 raw HTML，
// 万一网关没剥掉，它在页面上也只是一行不显眼的转义文本而非破版内容。
@ -156,23 +165,28 @@ const sendMailTool = {
session_alias: args.session_alias || "",
attachment_ids: args.attachment_ids || [],
});
// 发成功后才记：失败的调用不该压掉自动转发 ——
// 那种情况下模型的结论还没送出去，自动转发正是兜底
noteExplicitSend(context?.sessionID, args.to, args.reply_to);
const alias = result.session_alias
? `，会话别名 ${result.session_alias}（续谈可用 ${args.to.split(".")[0]}.${result.session_alias}）`
: "";
// 配额剩余必须回给模型：不然它只能撞到 403 才知道额度用完，
// 那时已经没有配额发最终总结了。
const quota =
typeof result.quota_remaining === "number"
? `\n发信配额剩余 ${result.quota_remaining}/${result.quota_max}。` +
(result.quota_remaining <= 1
? "配额即将用尽，请尽快向人类发送最终总结。"
// 本任务的剩余往返必须回给模型：不然它只能撞到 403 才知道额度用完。
// 注意这是【这条线索】的预算，不是 Agent 的终身额度 ——
// 换一个任务就是另一份预算。
const budget =
typeof result.budget_remaining === "number"
? `\n本任务剩余 ${result.budget_remaining}/${result.budget_max} 个来回。` +
(result.budget_remaining <= 1
? "预算即将用尽，请尽快给出结论；自动转发的总结不占预算。"
: "")
: "";
// 回传规范化后的别名：Agent 提的名字可能含非法字符被改写过
const proposed = result.rename_proposed
? `\n已向用户提议把会话改名为 ${result.rename_proposed}，等待其确认。`
: "";
return `已发送。Mail ID: ${result.mail_id}，Session: ${result.session_id}${alias}${quota}${proposed}`;
return `已发送。Mail ID: ${result.mail_id}，Session: ${result.session_id}${alias}${budget}${proposed}`;
},
};
@ -211,7 +225,7 @@ const readInboxTool = {
const limit = args.limit || 5;
const data = await apiGet(`/mail/inbox?status=${filter}&limit=${limit}`);
if (!data.mails || data.mails.length === 0) return "收件箱为空。";
return data.mails.map((m) => {
const listed = data.mails.map((m) => {
const lines = [
`[${m.status}] ${m.from_name}: ${m.subject}`,
`邮件 ID: ${m.mail_id}`,
@ -230,6 +244,24 @@ const readInboxTool = {
lines.push(`内容: ${(m.body_preview || m.body || "").substring(0, 200)}`);
return lines.join("\n");
}).join("\n\n");
// 读过就标掉。不标的话下次拉收件箱还是这一批，
// 处理过的信和新来的信混在一起，模型分不清哪封该回。
//
// 只标本次真正列出来的（而不是全部未读）：limit 之外的还没看过，
// 一并标掉等于让它们凭空消失。
if (args.filter !== "all") {
const ids = data.mails.map(m => m.mail_id).filter(Boolean);
if (ids.length) {
// 标记失败不该让 read_inbox 失败 —— 正文已经取到了，
// 代价只是下次会重复看到，比丢掉这次读取轻。
apiPost("/mail/read", { mail_ids: ids }).catch(e =>
console.error("[mail-bridge] 标记已读失败:", e?.message || e)
);
}
}
return listed;
},
};
@ -510,6 +542,21 @@ async function relaySummary(client, directory, sessionID) {
const ctx = mailContexts.get(mailSessionID);
if (!ctx?.replyTo) return null;
// 模型这一轮已经亲手回过这条线索 → 不再自动转发。
//
// 否则收件箱里会出现两封说同一件事的邮件（生产实测：311 字节与 342 字节各一封，
// 其中带附件的那封才是模型真正想发的）。判定看两点：
// - 收件人同名：它已经跟这个人说过了
// - reply_to 相同：它已经回过这封信了
// relay_key 的幂等管不了这个 —— 那个键保证「同一条消息不转两次」，
// 而这里是「模型已经自己发过了」。
if (shouldSkipAutoRelay(explicitSends.get(sessionID), ctx.replyTo, ctx.mailID)) {
explicitSends.delete(sessionID);
relayedSummaries.set(sessionID, last.id); // 记下这条已「处理」，别下次 idle 又转
console.error(`[mail-bridge] 本轮模型已主动回信 ${ctx.replyTo}，跳过自动转发`);
return null;
}
const res = await apiPost("/mail/send", {
to: ctx.replyTo,
subject: ctx.subject ? `Re: ${stripRe(ctx.subject)}` : "本轮工作总结",
@ -520,6 +567,7 @@ async function relaySummary(client, directory, sessionID) {
relay_key: last.id,
});
relayedSummaries.set(sessionID, last.id);
explicitSends.delete(sessionID); // 一轮结束，窗口关闭
return res;
}
@ -580,6 +628,10 @@ async function replyPermission(client, directory, data) {
async function deliverMail(client, directory, data, kind) {
const { sessionID, reused } = await resolveSessionForMail(client, directory, data, kind);
// 新一轮开始：清掉上一轮「模型主动发过信」的记录。
// 不清的话，上一轮亲手回过信会永久压掉这个会话之后所有的自动转发。
explicitSends.delete(sessionID);
// 记住这轮该回给谁：idle 时 relaySummary 靠它决定收件人与 reply_to。
// 一个会话里可能来过多封信，只保留最近那封 —— 回信要落回最新的线索。
if (kind === "mail" && data.session_id) {
@ -652,24 +704,11 @@ export default async function mailBridge(input) {
// 所以用一个闭包把 relaySummary 需要的两个参数固定下来。
relaySummaryRef = (sid) => relaySummary(client, directory, sid);
// 心跳。响应带回配额，配额将要用尽时留一条日志。
// 注意插件代劳的转发（权限询问、最终总结）不占配额，
// 所以这条警告只关系到模型主动调 send_mail 的次数。
let lastQuotaWarn = -1;
// 心跳。只保活与取待处理邮件数 ——
// 额度属于具体任务（会话），不属于 Agent，所以这里没有「剩余额度」可报。
// 剩余往返随每次发信响应的 budget_remaining 回传，在那里才有意义。
const heartbeat = setInterval(() => {
apiPost("/agent/heartbeat", {})
.then(res => {
const q = res?.quota;
if (!q || q.unlimited) return;
if (q.remaining <= 2 && q.remaining !== lastQuotaWarn) {
lastQuotaWarn = q.remaining;
console.error(
`[mail-bridge] 主动发信配额剩余 ${q.remaining}/${q.max_rounds}` +
`（自动转发的总结与权限询问不占配额）。`
);
}
})
.catch(() => {});
apiPost("/agent/heartbeat", {}).catch(() => {});
}, 30000);
startSSE((type, data) => {