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
parent 00ba69d899
commit 07e6b789b2
61 changed files with 3107 additions and 595 deletions
--- a/plugins/opencode-mail-bridge/index.js
+++ b/plugins/opencode-mail-bridge/index.js
@ -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) => {
--- a/plugins/opencode-mail-bridge/lib/relay-dedup.js
+++ b/plugins/opencode-mail-bridge/lib/relay-dedup.js
@ -0,0 +1,58 @@
+// 自动转发去重的纯逻辑。
+//
+// 单独一个文件而不是放在 index.js 里导出：**opencode 会把插件入口模块的
+// 每一个导出都当成插件工厂**（`Object.values(mod)` 逐个检查是不是函数），
+// 多导出一个 Map 就会让整个插件加载失败：
+//   ERROR message="failed to load plugin" error="Plugin export is not a function"
+// 实测踩过 —— 插件静默不加载，邮件全都投不进去。
+// 因此入口文件只能 `export default`，其余东西一律搁在这里。
+
+/** 取三维地址的名字段：admin@root.alias -> admin */
+export function addrName(addr) {
+  return String(addr || "").split("@")[0].trim();
+}
+
+/**
+ * 本轮内模型**自己调 send_mail** 发出去的信（按 opencode 会话）。
+ *
+ * session.idle 的自动转发要据此让位：模型已经亲手回过这条线索了，
+ * 再把它最后那段话转一遍，收件箱里就是两封内容几乎一样的邮件。
+ * 生产实测过这个后果 —— 同一轮里 311 字节和 342 字节各一封，
+ * 说的是同一件事，其中带附件的那封才是模型真正想发的。
+ *
+ * 为什么不靠 relay_key 幂等：那个键是 assistant message id，
+ * 保证的是「同一条消息不被转两次」，管不了「模型已经自己发过了」。
+ *
+ * 窗口是「一轮」：deliverMail 投递新邮件时清空（新一轮开始），
+ * relaySummary 用完即清。
+ */
+export const explicitSends = new Map(); // opencode session id -> { names:Set, replyTos:Set }
+
+/** 记下模型这一轮主动发了信，给谁、回的哪封。 */
+export function noteExplicitSend(sessionID, to, replyTo) {
+  if (!sessionID) return;
+  let rec = explicitSends.get(sessionID);
+  if (!rec) {
+    rec = { names: new Set(), replyTos: new Set() };
+    explicitSends.set(sessionID, rec);
+  }
+  const name = addrName(to);
+  if (name) rec.names.add(name);
+  if (replyTo) rec.replyTos.add(String(replyTo));
+}
+
+/**
+ * 本轮是否该跳过自动转发。
+ *
+ * @param sent    该会话本轮的主动发信记录 { names:Set, replyTos:Set }，可为空
+ * @param replyTo 自动转发本来要发给谁（三维地址或纯名字）
+ * @param mailID  自动转发本来要 reply_to 的邮件 id
+ */
+export function shouldSkipAutoRelay(sent, replyTo, mailID) {
+  if (!sent) return false;
+  // 收件人同名：模型已经跟这个人说过了
+  if (sent.names.has(addrName(replyTo))) return true;
+  // 同一封信已被回过：即使收件人写法不同（别名/路径不同）也算回过
+  if (mailID && sent.replyTos.has(String(mailID))) return true;
+  return false;
+}
--- a/plugins/opencode-mail-bridge/package.json
+++ b/plugins/opencode-mail-bridge/package.json
@ -9,5 +9,8 @@
  },
  "peerDependencies": {
    "@opencode-ai/plugin": ">=1.15.0"
+  },
+  "scripts": {
+    "test": "node test/auto-relay.test.mjs"
  }
 }
--- a/plugins/opencode-mail-bridge/test/auto-relay.test.mjs
+++ b/plugins/opencode-mail-bridge/test/auto-relay.test.mjs
@ -0,0 +1,108 @@
+// 自动转发去重的回归测试。
+//
+// 这个 bug 是生产里真实发生的：模型带附件主动回了一封（311 字节），
+// session.idle 又把它最后那段话自动转了一封（342 字节），
+// 收件箱里两封说同一件事，其中只有一封能下载附件。
+//
+// 逻辑放在 lib/relay-dedup.js 而不是 index.js：opencode 把入口模块的每一个
+// 导出都当成插件工厂，入口多导出一个 Map 就会让整个插件加载失败
+// （实测 "Plugin export is not a function"，插件静默不加载，邮件全投不进去）。
+import {
+  shouldSkipAutoRelay,
+  noteExplicitSend,
+  explicitSends,
+  addrName,
+} from '../lib/relay-dedup.js';
+
+let failed = 0;
+const check = (name, cond, detail = '') => {
+  if (cond) console.log(`  通过  ${name}`);
+  else {
+    console.error(`  失败  ${name}${detail ? ' — ' + detail : ''}`);
+    failed++;
+  }
+};
+
+console.log('自动转发去重：');
+
+// ---- addrName ----
+check('三维地址取名字段', addrName('admin@root.tidy-tiger') === 'admin');
+check('纯名字原样返回', addrName('admin') === 'admin');
+check('空值不炸', addrName(undefined) === '' && addrName(null) === '');
+check('去空白', addrName('  admin  @root') === 'admin');
+
+// ---- 没有主动发信记录 → 照常自动转发 ----
+check(
+  '本轮没主动发信 → 不跳过（自动转发是默认行为）',
+  shouldSkipAutoRelay(undefined, 'admin', 'mail-1') === false
+);
+
+// ---- 收件人同名 → 跳过 ----
+explicitSends.clear();
+noteExplicitSend('ses-1', 'admin@root.tidy-tiger', 'mail-1');
+check(
+  '模型已回给同一个人 → 跳过',
+  shouldSkipAutoRelay(explicitSends.get('ses-1'), 'admin', 'mail-1') === true
+);
+check(
+  '收件人写法不同但同名 → 仍跳过（地址带路径/会话段）',
+  shouldSkipAutoRelay(explicitSends.get('ses-1'), 'admin@root', 'mail-1') === true
+);
+
+// ---- 发给别人 → 不跳过 ----
+explicitSends.clear();
+noteExplicitSend('ses-2', 'ops@root.new', 'mail-9');
+check(
+  '模型主动联系了第三方，但本轮的来信还没回 → 不跳过',
+  shouldSkipAutoRelay(explicitSends.get('ses-2'), 'admin', 'mail-1') === false
+);
+
+// ---- reply_to 相同 → 跳过（即使收件人名字对不上）----
+explicitSends.clear();
+noteExplicitSend('ses-3', 'someone-else@root', 'mail-1');
+check(
+  '已回过同一封信 → 跳过（reply_to 命中，收件人名字不同也算）',
+  shouldSkipAutoRelay(explicitSends.get('ses-3'), 'admin', 'mail-1') === true
+);
+
+// ---- 一轮里发了多封 ----
+explicitSends.clear();
+noteExplicitSend('ses-4', 'ops@root', 'mail-8');
+noteExplicitSend('ses-4', 'admin@root', 'mail-1');
+const rec4 = explicitSends.get('ses-4');
+check('一轮多封都记下', rec4.names.size === 2 && rec4.replyTos.size === 2);
+check('其中任一命中即跳过', shouldSkipAutoRelay(rec4, 'admin', 'mail-1') === true);
+check('都不命中则不跳过', shouldSkipAutoRelay(rec4, 'someone', 'mail-99') === false);
+
+// ---- 无 sessionID 不记录（防止污染一个 undefined 键）----
+explicitSends.clear();
+noteExplicitSend(undefined, 'admin@root', 'mail-1');
+check('没有 sessionID 时不记录', explicitSends.size === 0);
+
+// ---- 空 mailID 不该让 replyTos 命中 ----
+explicitSends.clear();
+noteExplicitSend('ses-5', 'ops@root', '');
+const rec5 = explicitSends.get('ses-5');
+check('空 reply_to 不入集合', rec5.replyTos.size === 0);
+check(
+  '本来要转的邮件没有 id 时只看收件人',
+  shouldSkipAutoRelay(rec5, 'admin', '') === false
+);
+
+// ---- 不变量：插件入口只能有 default 导出 ----
+//
+// opencode 用 Object.values(mod) 逐个检查每个导出是不是函数，
+// 多导出一个 Map/常量就抛 "Plugin export is not a function"，
+// 整个插件静默不加载 —— 邮件全都投不进去。实测踩过这个坑。
+import { readFileSync } from 'node:fs';
+const entry = readFileSync(new URL('../index.js', import.meta.url), 'utf8');
+const exports_ = entry.match(/^export\s+(?!default\b).*/gm) || [];
+check(
+  '入口 index.js 只有 default 导出',
+  exports_.length === 0,
+  exports_.length ? `多出：${exports_.map(l => l.slice(0, 50)).join(' | ')}` : ''
+);
+check('入口确实有 default 导出', /^export default /m.test(entry));
+
+console.log(failed === 0 ? '\n自动转发去重：全部通过' : `\n自动转发去重：${failed} 项失败`);
+process.exit(failed === 0 ? 0 : 1);