fix(gateway): 已读改为**按读者**记录 —— 修掉"别人读掉,我就看不到"

用户报的那句 dsh 自述("收件箱列表未展示它,直接按 mail_id 读取成功")不是插件问题,
是网关的已读模型:`mails.status` 是**邮件级**的一个列,任何收件人读掉,对所有收件人
(含抄送)都变成已读 —— 全库没有任何按人记录已读的表,我查过 schema 与迁移文件。

实测复现(两个人类用户、一封共享邮件,排除 Agent 干扰):
  gui-lab 读掉 → gui-lab 未读清空(应当)→ **jianf 的未读也没了**(错误)
  而 jianf 的 `status=all` 里仍在 ⇒ 是已读语义问题,不是送达问题。
线上那封信正是这个形状:`jianf → dsh` 抄送 pi/opencode/zcode/homeagent,**pi 最先
回复(= 它读过了)** ⇒ 这封对 dsh 也变成 read ⇒ dsh 的 `read_inbox`(默认 unread)
返回空 ⇒ 它只能按提示词里的 mail_id 兜。

三个受害面:① Agent 的 `read_inbox` 拿不到信(换一个不兜的模型就变成"正文是空的");
② 人类的未读被抄送的 Agent 读掉;③ ★ 桥的补投判据 `pending_mails = CountUnread` 归零
⇒ SSE 漏过或进程重启时那封信**不再补投**(静默丢信)。

改动:
- 新表 `mail_reads(mail_id, reader_name, read_at)`,未读 = 这张表里没有该读者的行。
- 判据收敛到一处(repo 的 `unreadFor` / `readStateFor`),六处读写点全部改用它:
  单封已读、批量标已读、权限决策(只记**决策人**)、`ListInbox`(过滤 + 返回的
  status 都按读者算)、`CountUnread`、`CountUnreadInSession`、会话列表未读计数。
- 一次性回填补历史:`mails.status='read'` 记到**主收件人**名下(唯一可用的推断),
  用 `app_meta` 里的标记守住 —— 不能每次启动都跑,那会把"某抄送方读过"按主收件人
  写成已读,正是这次要修的错。实测:`done rows=207`。
- `mails.status` 保留为"有人读过 / 已归档"的冗余列,**不再是判据**。

★ 顺带挖出并修掉一个真 bug:`CountUnreadInSession` 用的是 PG 专有语法
(`cc_list @> $3::jsonb`),而线上是 SQLite ⇒ 那条 SQL **语法错误**
(`unrecognized token: "@"`),调用点又是 `unread, _ :=`(吞错)⇒
**会话列表的未读数一直是 0**。现已改用仓库既有的方言助手 `db.CCHas`。
实测:happy-pixel 会话现在 `unread_count=5`(修复前恒 0)。

判据:新增 `internal/repo/readstate_test.go`(5 条:按读者未读、会话内计数、
批量标已读、归档对所有人可见性、权限决策只记决策人)。
**扰动验证**:把 `unreadFor` 退回旧语义 → 4 条判据全红;恢复 → 绿。
全量 server 10 包全绿。文档同步:API.md 的「标记已读」段 + PLUGIN-CONTRACT 的 T-1.4。

线上复验:同一受控实验 —— gui-lab 读掉后,**jianf 的未读仍在且 status=unread** ✅
This commit is contained in:
2026-09-13 14:25:44 +08:00
parent 49ec22f916
commit 1619399470
10 changed files with 432 additions and 17 deletions

View File

@ -52,7 +52,7 @@ func TestPermissionDeadlineVisibleOnEveryReadPath(t *testing.T) {
"读取配置", []string{"同意", "拒绝"}, "cat cfg", "permission", false); err != nil {
t.Fatal(err)
}
if _, err := DecidePermission(ctx, settledID, "同意"); err != nil {
if _, err := DecidePermission(ctx, settledID, "alice", "同意"); err != nil {
t.Fatal(err)
}

View File

@ -0,0 +1,212 @@
package repo
import (
"context"
"testing"
"github.com/agentmail/gateway/internal/db"
"github.com/google/uuid"
)
/*
已读语义:**按读者**记录,而不是邮件行上的一个全局列。
2026-09-13 线上实测:`jianf → dsh` 那封打了招呼、抄送 pi/opencode/zcode/homeagent 的
邮件里,pi 最先回复 ⇒ 它读过了 ⇒ 这封对 dsh 也变成 `read` ⇒ dsh 的
`read_inbox`(默认 unread)返回空,它只能按提示词里的 mail_id 直接读,并在回信里
写下"收件箱列表未展示它,直接按 mail_id 读取成功"。
同一封邮件**对每个读者各自算未读**,是这一组判据要钉住的不变量。
*/
// unreadList 返回 ListInbox 在 unread 过滤下给出的邮件 id。
func unreadList(t *testing.T, reader string) []uuid.UUID {
t.Helper()
mails, err := ListInbox(context.Background(), reader, "unread", 50)
if err != nil {
t.Fatal(err)
}
out := []uuid.UUID{}
for _, m := range mails {
out = append(out, m.ID)
}
return out
}
func hasID(list []uuid.UUID, id uuid.UUID) bool {
for _, x := range list {
if x == id {
return true
}
}
return false
}
// statusSeenBy 返回 ListInbox 在 all 过滤下、某个读者看到的那封邮件的 status。
func statusSeenBy(t *testing.T, reader string, id uuid.UUID) string {
t.Helper()
mails, err := ListInbox(context.Background(), reader, "all", 50)
if err != nil {
t.Fatal(err)
}
for _, m := range mails {
if m.ID == id {
return m.Status
}
}
t.Fatalf("读者 %s 的收件箱里没有 %s", reader, id)
return ""
}
func TestReadStateIsPerRecipient(t *testing.T) {
setupTestDB(t)
ctx := context.Background()
// 一封主收件人 alice、抄送 bob 的邮件 —— 正是线上那封信的形状
id := seedMailTo(t, "alice", "bob")
// 初始:两边都未读
if n, _ := CountUnread(ctx, "alice"); n != 1 {
t.Fatalf("alice 初始未读 = %d,期望 1", n)
}
if n, _ := CountUnread(ctx, "bob"); n != 1 {
t.Fatalf("bob 初始未读 = %d,期望 1", n)
}
// alice 读掉它
if err := MarkMailRead(ctx, id, "alice"); err != nil {
t.Fatal(err)
}
// ★ 核心判据:alice 的未读清了,bob 的**必须还在**
if n, _ := CountUnread(ctx, "alice"); n != 0 {
t.Fatalf("alice 读过后未读 = %d,期望 0", n)
}
if n, _ := CountUnread(ctx, "bob"); n != 1 {
t.Fatalf("★ bob 没读,未读却变成了 %d —— 这正是要修的缺陷(任一收件人读掉,所有人变已读)", n)
}
if !hasID(unreadList(t, "bob"), id) {
t.Fatal("★ bob 的 unread 收件箱里必须还能看到这封信")
}
if hasID(unreadList(t, "alice"), id) {
t.Fatal("alice 自己读过了,unread 收件箱不该再有它")
}
// 同一封邮件,两个读者看到的状态不同 —— 这就是"按读者"的直接证据
if got := statusSeenBy(t, "alice", id); got != "read" {
t.Fatalf("alice 看到的 status = %q,期望 read", got)
}
if got := statusSeenBy(t, "bob", id); got != "unread" {
t.Fatalf("★ bob 看到的 status = %q,期望 unread(同一封邮件,按读者算)", got)
}
// 反向对照:bob 也读掉 → 两边都清
if err := MarkMailRead(ctx, id, "bob"); err != nil {
t.Fatal(err)
}
if n, _ := CountUnread(ctx, "bob"); n != 0 {
t.Fatalf("bob 读过后未读 = %d,期望 0", n)
}
}
// CountUnreadInSession 是会话列表徽标用的,同样必须按读者算。
func TestCountUnreadInSessionIsPerRecipient(t *testing.T) {
setupTestDB(t)
ctx := context.Background()
id := seedMailTo(t, "alice", "bob")
var sid uuid.UUID
if err := db.DB.QueryRowContext(ctx, `SELECT session_id FROM mails WHERE mail_id = $1`, id).Scan(&sid); err != nil {
t.Fatal(err)
}
if err := MarkMailRead(ctx, id, "alice"); err != nil {
t.Fatal(err)
}
if n, _ := CountUnreadInSession(ctx, "alice", sid); n != 0 {
t.Fatalf("alice 会话内未读 = %d,期望 0", n)
}
if n, _ := CountUnreadInSession(ctx, "bob", sid); n != 1 {
t.Fatalf("★ bob 会话内未读 = %d,期望 1(徽标不能因为别人读过就归零)", n)
}
}
// 批量标已读(Agent 的 /mail/read)同样只影响调用者自己。
func TestBulkMarkReadOnlyAffectsCaller(t *testing.T) {
setupTestDB(t)
ctx := context.Background()
id := seedMailTo(t, "alice", "bob")
if _, err := MarkMailsReadFor(ctx, "alice", []uuid.UUID{id}); err != nil {
t.Fatal(err)
}
if n, _ := CountUnread(ctx, "bob"); n != 1 {
t.Fatalf("★ 批量标已读后 bob 未读 = %d,期望 1", n)
}
// 全部标已读(不带 id)也只能标自己收件箱里的
if _, err := MarkAllInboxReadFor(ctx, "alice"); err != nil {
t.Fatal(err)
}
if n, _ := CountUnread(ctx, "bob"); n != 1 {
t.Fatalf("★ 全标已读后 bob 未读 = %d,期望 1", n)
}
}
// 归档是**会话级**的全局状态:归档后对所有人都不可见(unread 与 all 都不给),
// 而且不能因为"没人读过"就把它算成未读。
func TestArchivedStaysArchivedForEveryone(t *testing.T) {
setupTestDB(t)
ctx := context.Background()
id := seedMailTo(t, "alice", "bob")
var sid uuid.UUID
if err := db.DB.QueryRowContext(ctx, `SELECT session_id FROM mails WHERE mail_id = $1`, id).Scan(&sid); err != nil {
t.Fatal(err)
}
if err := ArchiveSession(ctx, sid); err != nil {
t.Fatal(err)
}
if n, _ := CountUnread(ctx, "bob"); n != 0 {
t.Fatalf("归档会话里的邮件不该计入未读,实际 %d", n)
}
if hasID(unreadList(t, "bob"), id) {
t.Fatal("归档邮件的 status 是 archived,不该出现在 unread 收件箱")
}
// ListInbox 会整体排除归档会话(`s.status <> 'archived'`),所以它在
// `all` 里也不出现 —— 归档是"从收件箱拿走",不是"标成已读"。
mails, err := ListInbox(ctx, "bob", "all", 50)
if err != nil {
t.Fatal(err)
}
for _, m := range mails {
if m.ID == id {
t.Fatal("归档会话里的邮件不该出现在收件箱列表(all 也不该有)")
}
}
}
// 权限决策把邮件记成**决策人**已读:同一条线索上其他收件人不受影响。
func TestPermissionDecisionMarksOnlyDecider(t *testing.T) {
setupTestDB(t)
ctx := context.Background()
// 一封 alice 收、bob 抄送的权限邮件
id := seedMailTo(t, "alice", "bob")
if _, err := db.DB.ExecContext(ctx,
`INSERT INTO permission_requests (mail_id, session_id, agent_name, question, options, kind)
SELECT mail_id, session_id, 'bot', 'q', '["同意","拒绝"]', 'permission' FROM mails WHERE mail_id = $1`,
id); err != nil {
t.Fatal(err)
}
if _, err := DecidePermission(ctx, id, "alice", "同意"); err != nil {
t.Fatal(err)
}
if n, _ := CountUnread(ctx, "alice"); n != 0 {
t.Fatalf("决策人 alice 未读 = %d,期望 0", n)
}
if n, _ := CountUnread(ctx, "bob"); n != 1 {
t.Fatalf("★ bob 未读 = %d,期望 1(决策是 alice 做的,不该替他标记已读)", n)
}
}

View File

@ -444,7 +444,58 @@ func GetMailByID(ctx context.Context, id uuid.UUID) (*models.Mail, error) {
return &m, nil
}
func MarkMailRead(ctx context.Context, id uuid.UUID) error {
/*
─── 已读语义:按**读者**记录,而不是邮件行上的一个全局列 ───────────────
2026-09-13 实测缺陷:`mails.status` 是邮件级的,任何收件人读掉,对所有收件人
(含抄送)都变成已读。后果:Agent 的 read_inbox(默认 unread)拿不到信(dsh 明确
回报"收件箱列表未展示它,直接按 mail_id 读取成功");人类的未读被抄送的 Agent
读掉;桥的补投判据 CountUnread 归零 ⇒ 那封信不再补投(静默丢信)。
现在的判据:**对某个读者未读 = mail_reads 里没有 (mail_id, reader_name) 这一行。**
`mails.status` 保留为"有人读过 / 已归档"的冗余,不再作为未读判据。
下列两个片段把这件事收在一处,避免每条 SQL 各写一遍判据(写岔了就是又一次语义漂移)。
*/
// unreadFor 返回"$n 这个读者看这封邮件是未读"的谓词;`m` 必须是 mails 的别名。
func unreadFor(arg string) string {
return `(m.status <> 'archived' AND NOT EXISTS (
SELECT 1 FROM mail_reads r WHERE r.mail_id = m.mail_id AND r.reader_name = ` + arg + `))`
}
// readStateFor 返回给前端的 status 值(archived 是全局的,read/unread 按读者算)。
func readStateFor(arg string) string {
return `CASE WHEN m.status = 'archived' THEN 'archived'
WHEN EXISTS (SELECT 1 FROM mail_reads r WHERE r.mail_id = m.mail_id AND r.reader_name = ` + arg + `)
THEN 'read' ELSE 'unread' END`
}
// markReadFor 批量记下"某个读者读过哪些邮件"。
//
// `where` 是**只用于 INSERT 的**筛选片段,里面可以(也应当)用 `m.` 前缀引用 mails ——
// 调用方各自负责随后刷新 mails.status 那列冗余(那个语句没有 `m` 别名)。
// 之前我把同一个 where 复用到 UPDATE 上,直接 SQL 报 "no such column: m.mail_id"
// (测试当场抓到)。
func markReadFor(ctx context.Context, reader string, where string, args ...any) error {
_, err := db.DB.ExecContext(ctx,
`INSERT INTO mail_reads (mail_id, reader_name)
SELECT m.mail_id, $1 FROM mails m
WHERE `+where+`
AND NOT EXISTS (SELECT 1 FROM mail_reads r WHERE r.mail_id = m.mail_id AND r.reader_name = $1)`,
append([]any{reader}, args...)...)
return err
}
// MarkMailRead 记下**这个读者**读过这封邮件(人类端点)。
func MarkMailRead(ctx context.Context, id uuid.UUID, reader string) error {
if _, err := db.DB.ExecContext(ctx,
`INSERT INTO mail_reads (mail_id, reader_name)
SELECT $1, $2
WHERE NOT EXISTS (SELECT 1 FROM mail_reads WHERE mail_id = $1 AND reader_name = $2)`,
id, reader); err != nil {
return err
}
_, err := db.DB.ExecContext(ctx, `UPDATE mails SET status = 'read' WHERE mail_id = $1`, id)
return err
}
@ -455,7 +506,7 @@ func ListInbox(ctx context.Context, agentName, status string, limit int) ([]mode
m.cc_list, m.subject, m.body, m.mail_type, COALESCE(m.permission_result,'') AS permission_result,
COALESCE(m.permission_kind,'') AS permission_kind,
COALESCE(m.permission_multi_select,0) AS permission_multi_select,
m.status, m.created_at, s.session_alias, s.workspace,
` + readStateFor("$1") + ` AS status, m.created_at, s.session_alias, s.workspace,
EXISTS (SELECT 1 FROM users u WHERE u.username = m.from_name) AS from_human,
EXISTS (SELECT 1 FROM users u WHERE u.username = m.to_name) AS to_human,
COALESCE(NULLIF(s.permission_mode, ''), 'workspace') AS permission_mode,
@ -466,8 +517,16 @@ func ListInbox(ctx context.Context, agentName, status string, limit int) ([]mode
AND s.status <> 'archived'`
args := []any{agentName}
if status != "" && status != "all" {
q += ` AND m.status = $2`
args = append(args, status)
// 未读/已读都按**这个读者**算(原先直接比 m.status,于是被抄送方读掉
// 别人的未读也跟着变 —— 这就是要修的那条)
if status == "unread" {
q += ` AND ` + unreadFor("$1")
} else if status == "read" {
q += ` AND NOT ` + unreadFor("$1") + ` AND m.status <> 'archived'`
} else {
q += ` AND m.status = $2`
args = append(args, status)
}
}
q += ` ORDER BY m.created_at DESC, m.mail_id DESC`
if limit > 0 {
@ -521,7 +580,7 @@ func CountUnread(ctx context.Context, agentName string) (int, error) {
FROM mails m
JOIN sessions s ON m.session_id = s.session_id
WHERE (m.to_name = $1 OR `+db.CCHas("m.cc_list", 1)+`)
AND m.status = 'unread'
AND `+unreadFor("$1")+`
AND s.status <> 'archived'
`, agentName).Scan(&count)
return count, err
@ -614,7 +673,9 @@ func AttachPermissionDeadlines(mails []models.Mail) {
}
}
func DecidePermission(ctx context.Context, mailID uuid.UUID, decision string) (*models.PermissionRequest, error) {
// decider 是**做出决策的人**(用户名):权限邮件对他也应当变成已读 —— 但只对他一个人,
// 而不是像原先那样把邮件行的全局 status 一改(抄送的其他 Agent 会因此看不到它)。
func DecidePermission(ctx context.Context, mailID uuid.UUID, decider, decision string) (*models.PermissionRequest, error) {
var pr models.PermissionRequest
var optsJSON []byte
@ -634,6 +695,14 @@ func DecidePermission(ctx context.Context, mailID uuid.UUID, decision string) (*
_, _ = db.DB.ExecContext(context.Background(),
`UPDATE mails SET permission_result = $1, status = 'read' WHERE mail_id = $2`,
decision, mailID)
if decider != "" {
// 记到决策人名下(按读者记,见 repo.markReadFor)
_, _ = db.DB.ExecContext(context.Background(),
`INSERT INTO mail_reads (mail_id, reader_name)
SELECT $1, $2
WHERE NOT EXISTS (SELECT 1 FROM mail_reads WHERE mail_id = $1 AND reader_name = $2)`,
mailID, decider)
}
return &pr, nil
}
@ -1037,7 +1106,9 @@ func ListContactsFor(ctx context.Context, forUser string, archived bool) ([]Cont
COALESCE(s.session_alias, '') AS alias,
s.status,
(SELECT COUNT(*) FROM mails x WHERE x.session_id = s.session_id),
(SELECT COUNT(*) FROM mails x WHERE x.session_id = s.session_id AND x.status = 'unread'),
(SELECT COUNT(*) FROM mails x WHERE x.session_id = s.session_id
AND x.status <> 'archived'
AND NOT EXISTS (SELECT 1 FROM mail_reads r WHERE r.mail_id = x.mail_id AND r.reader_name = $1)),
s.updated_at,
s.subject,
COALESCE(s.max_rounds, 0),
@ -1359,14 +1430,17 @@ func ListSessionsFor(ctx context.Context, forUser string, limit int) ([]models.S
// CountUnreadInSession 统计某人在某会话内的未读数(含被抄送)
func CountUnreadInSession(ctx context.Context, name string, sessionID uuid.UUID) (int, error) {
ccProbe, _ := json.Marshal([]map[string]string{{"name": name}})
var n int
// 抄送判定必须走 db.CCHas:这条路原先写的是 PG 专有的 `cc_list @> $3::jsonb`,
// 而**线上是 SQLite** —— 那条 SQL 直接语法错误(unrecognized token: "@"),
// 调用点又是 `unread, _ :=`(吞错),于是会话列表的未读数一直显示 0。
// 用的是与 CountUnread 同一个助手,两种方言都正确。
err := db.DB.QueryRowContext(ctx, `
SELECT COUNT(*) FROM mails
WHERE session_id = $1
AND status = 'unread'
AND (to_name = $2 OR cc_list @> $3::jsonb)
`, sessionID, name, string(ccProbe)).Scan(&n)
SELECT COUNT(*) FROM mails m
WHERE m.session_id = $1
AND `+unreadFor("$2")+`
AND (m.to_name = $2 OR `+db.CCHas("m.cc_list", 2)+`)
`, sessionID, name).Scan(&n)
return n, err
}
@ -1460,6 +1534,14 @@ func MarkMailsReadFor(ctx context.Context, recipient string, ids []uuid.UUID) (i
args = append(args, id)
}
if err := markReadFor(ctx, recipient,
`m.mail_id IN (`+strings.Join(ph, ",")+`) AND (m.to_name = $1 OR `+db.CCHas("m.cc_list", 1)+`)`,
args...); err != nil {
return 0, err
}
// 冗余列:mails.status 只表示"有人读过 / 已归档",**不再作为未读判据**
// (判据是 mail_reads,见 unreadFor)。保留它是为了兼容仍在读这一列的老路径,
// 以及让 SQL 层面"邮件是否被任何人读过"仍可一眼看出。
res, err := db.DB.ExecContext(ctx, `
UPDATE mails SET status = 'read'
WHERE mail_id IN (`+strings.Join(ph, ",")+`)
@ -1478,6 +1560,13 @@ func MarkMailsReadFor(ctx context.Context, recipient string, ids []uuid.UUID) (i
// 排除已归档会话:那些邮件在收件箱里根本看不到,
// 标掉它们只会让「标记了 N 封」这个数字与用户看到的对不上。
func MarkAllInboxReadFor(ctx context.Context, recipient string) (int, error) {
if err := markReadFor(ctx, recipient,
`(m.to_name = $1 OR `+db.CCHas("m.cc_list", 1)+`)
AND m.session_id IN (SELECT session_id FROM sessions WHERE status <> 'archived')`,
recipient); err != nil {
return 0, err
}
// 同上:刷新冗余列,未读判据在 mail_reads
res, err := db.DB.ExecContext(ctx, `
UPDATE mails SET status = 'read'
WHERE status = 'unread'