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

feat: 权限档位体系（三档 plan/workspace/full + 四桥 from_session_id）

Browse Source 
L2 核心改动：sessions 表补 permission_mode / permission_enforcement 两列
（sqlite + pg 同步），三桥 lib/permission-mode.js 翻译档位到平台原生配置，
homeagent advisory 模式提示词告知模型实际强制力。四桥全部携带 from_session_id
供 relay 去重与会话回溯。

FromHuman / ToHuman 判据已加入心跳 payload 与 notify/mail.go。
This commit is contained in:
JianFeeeee
2026-09-06 15:16:49 +08:00
parent 13fcb00acc
commit a44fd6949b
32 changed files with 3462 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
gateway/internal/handler/mail.go
View File

@ -37,6 +37,16 @@ type sendMailRequest struct {
// 它由平台生成，模型伪造不出，而唯一约束保证同一条上游消息只能免费转一次。
Relay string `json:"relay"` // "" | "permission" | "summary"
RelayKey string `json:"relay_key"` // 上游消息 id；relay 非空时必填
// FromSessionID 是发信时模型所处的邮件会话 id（即「这活是谁派给我的」）。
//
// **只用于权限档位继承**：Agent 新开一条会话时，新会话不得比它所在
// 的那条会话更宽松。注意这里**没有** permission_mode 字段 —— 那是有意的：
// 让 Agent 自己指定档位等于发一封 mode=full 的信就能提权。
//
// 省略时回落到默认档（不是 full）。插件担不担得起传这个值不影响安全下限：
// 没传 = 拿默认档，不会因此拿到更大的权限。
FromSessionID string `json:"from_session_id"`
}
// resolveTarget 根据三维地址 name@path.session 决定投递的会话。
@ -52,18 +62,28 @@ type sendMailRequest struct {
// byAgent 非空时表示这是 Agent 发起的投递，新建会话要过速率限制：
// 往返预算按会话计，Agent 用 .new 开一串会话就等于绕过预算。
// 人类不受此限（手工点「新建邮件」的频率天然受限，加限制只会在批量派活时误伤）。
func resolveTarget(r *http.Request, addr models.Address, replyTo, fromAgent, subject, alias string, byAgent string) (uuid.UUID, *uuid.UUID, error) {
// resolveTarget 依据地址的 session 位定位（或新建）会话。
//
// 返回值：会话 id / 父邮件 id（仅 reply_to 路径非 nil）/ **created** / 错误。
//
// created 为真**仅**表示这次调用真的新建了一条会话。它存在的理由是：
// `parentMailID == nil` 曾被当作「新建会话」的判据，而那是错的 ——
// 省略 session 位复用默认会话时 parentMailID 也是 nil。实测后果：
// 第一封信 `max_rounds=7`，第二封信省略该字段，会话预算被静默改成 20。
// 「只在新建时生效」的字段（往返预算、权限档位）必须靠这个返回值判断，
// 否则每封新信都在改写对方正在遵守的规则。
func resolveTarget(r *http.Request, addr models.Address, replyTo, fromAgent, subject, alias string, byAgent string) (uuid.UUID, *uuid.UUID, bool, error) {
if replyTo != "" {
replyID, err := uuid.Parse(replyTo)
if err != nil {
return uuid.Nil, nil, errBadRequest("Invalid reply_to UUID")
return uuid.Nil, nil, false, errBadRequest("Invalid reply_to UUID")
}
mail, err := repo.GetMailByID(r.Context(), replyID)
if err != nil {
return uuid.Nil, nil, errNotFound("Parent mail not found")
return uuid.Nil, nil, false, errNotFound("Parent mail not found")
}
repo.TouchSession(r.Context(), mail.SessionID)
return mail.SessionID, &replyID, nil
return mail.SessionID, &replyID, false, nil
}
switch addr.Mode() {
@ -73,17 +93,17 @@ func resolveTarget(r *http.Request, addr models.Address, replyTo, fromAgent, sub
var aliasPtr *string
if a := strings.TrimSpace(alias); a != "" {
if err := validateSessionAlias(a); err != nil {
return uuid.Nil, nil, err
return uuid.Nil, nil, false, err
}
if _, err := repo.FindSessionByAlias(r.Context(), a); err == nil {
return uuid.Nil, nil, errConflict(fmt.Sprintf(
return uuid.Nil, nil, false, errConflict(fmt.Sprintf(
"会话别名 %q 已被占用；若要接着该会话谈请用 %s@%s.%s", a, addr.Name, addr.Path, a))
}
aliasPtr = &a
}
// Agent 主动开新线索要过速率限制
if ok, retry := repo.AllowNewSession(r.Context(), byAgent); !ok {
return uuid.Nil, nil, errRateLimited(fmt.Sprintf(
return uuid.Nil, nil, false, errRateLimited(fmt.Sprintf(
"新建会话过于频繁（1 小时内已开 %d 条）。请在已有会话里继续，或 %d 秒后再试。",
repo.SessionRateLimit(), retry))
}
@ -93,7 +113,7 @@ func resolveTarget(r *http.Request, addr models.Address, replyTo, fromAgent, sub
if err != nil {
// 建失败要把名额还回去：那次新建实际上没有发生
repo.ReleaseNewSession(r.Context(), byAgent)
return id, nil, err
return id, nil, false, err
}
// `.new` 是一次性动作：它建完会话就用完了，之后要再投进这条会话只能靠
// `name@path.<别名>`。未命名会话既查不到（FindNamedSessionFor 的
@ -105,29 +125,32 @@ func resolveTarget(r *http.Request, addr models.Address, replyTo, fromAgent, sub
// 只能用 reply_to 续谈，比整封退回轻。
_, _ = repo.EnsureSessionAlias(r.Context(), id, repo.AutoAliasFor(addr.Name, subject))
}
return id, nil, nil
return id, nil, true, nil
case models.SessionDefault:
// 默认会话「从未通信则建立」也会产生新会话，但一个 name@path 只有一条，
// 不构成暴开的手段，因此不计入速率限制。
id, err := repo.FindOrCreateDefaultSession(r.Context(), addr.Name, addr.Path, fromAgent, subject)
//
// created 必须区分「这次建了」与「复用了既有的那条」：两者在这里都返回
// parentMailID == nil，靠它判断会把续谈误当新建（预算与档位被静默改写）。
id, created, err := repo.FindOrCreateDefaultSessionCreated(r.Context(), addr.Name, addr.Path, fromAgent, subject)
if err != nil {
return id, nil, err
return id, nil, false, err
}
// 默认会话同样需要可寻址的别名：省略 session 位能投进来，但要**指名**
// 投进这一条（而不是「该 name@path 当前的默认会话」）仍然只能靠别名。
// 已有别名时 EnsureSessionAlias 直接返回，复用旧会话不会被改名。
_, _ = repo.EnsureSessionAlias(r.Context(), id, repo.AutoAliasFor(addr.Name, subject))
return id, nil, nil
return id, nil, created, nil
default: // models.SessionNamed
id, err := repo.FindNamedSessionFor(r.Context(), addr.Name, addr.Path, addr.Session)
if err == nil {
repo.TouchSession(r.Context(), id)
return id, nil, nil
return id, nil, false, nil
}
if !errors.Is(err, repo.ErrSessionNotFound) {
return uuid.Nil, nil, err
return uuid.Nil, nil, false, err
}
// 本侧没有这条别名 —— 再看平台会话镜像。
@ -138,13 +161,15 @@ func resolveTarget(r *http.Request, addr models.Address, replyTo, fromAgent, sub
//
// 命中就**接管**它：本侧建一条会话并绑定 platform_id，插件收到投递
// 事件时据此 resume 那条平台会话而不是新建。
// 接管**是**新建本侧会话（绑定了 platform_id 的那条），
// 所以 created 为真：它此前没有档位与预算，需要按这次投递定下来。
if adopted, aErr := adoptFromPlatform(r, addr, fromAgent, subject, byAgent); aErr == nil {
return adopted, nil, nil
return adopted, nil, true, nil
} else if !errors.Is(aErr, repo.ErrSessionNotFound) {
return uuid.Nil, nil, aErr
return uuid.Nil, nil, false, aErr
}
return uuid.Nil, nil, errNotFound(fmt.Sprintf(
return uuid.Nil, nil, false, errNotFound(fmt.Sprintf(
"无法送达：会话 %q 不存在于 %s@%s。若要新建会话请用 %s@%s.new，投递默认会话请省略 session 位",
addr.Session, addr.Name, addr.Path, addr.Name, addr.Path))
}
@ -236,18 +261,56 @@ func SendMail(w http.ResponseWriter, r *http.Request) {
return
}
// 附件可挂性必须在**建邮件之前**校验。
//
// 原先只在 CreateMail 之后调 attachAll，于是附件不合法时返回 403/409，
// 但那封邮件已入库、已通知收件人、已扣预算（生产实测两封探针邮件均如此）。
// 发件方看到 4xx 会重试，收件方于是收到两封。
if !checkAttachable(w, r, attachIDs, agentName) {
return
}
// 可达性：收件人必须存在且未停用。Agent 侧同样要查 ——
// 模型拿到 200 就会当作「话已传到」并停手等对方，而那封信永远不会有人读。
if !checkDeliverable(w, r, append([]models.Address{to}, ccList...)) {
return
}
sessionID, parentMailID, err := resolveTarget(r, to, req.ReplyTo, agentName, req.Subject, req.SessionAlias, agentName)
sessionID, parentMailID, created, err := resolveTarget(r, to, req.ReplyTo, agentName, req.Subject, req.SessionAlias, agentName)
if err != nil {
writeErr(w, err, "Failed to resolve session")
return
}
// Agent 新开的会话继承权限档位，**不得自行抬档**。
//
// req 里根本没有 permission_mode 字段 —— 这是有意的：Agent 能指定档位
// 就等于发一封 mode=full 的信给自己提权。档位由发信方当前所处的会话
// （也就是「这活是谁派给我的」）推导，且只能同档或更严。
//
// 这保证 plan 档的任务派不出 full 档的子任务 —— 与 hop_limit 防自激同形：
// 约束必须沿着链条传递下去，否则一跳之后就失效了。
// 判据是 `created`：省略 session 位复用默认会话时 parentMailID 也是 nil，
// 用后者会让每一封续谈的信重新“继承”一次 —— 而那条会话的档位可能已经
// 被人在对话页里改过，重继承等于把人的修改静默回滚。
if created {
// 发信方自己那条会话的档位是上限。插件没传 from_session_id 时
// 回落到默认档 —— 不会因为没传而拿到更大的权限。
var parent *uuid.UUID
if req.FromSessionID != "" {
if pid, pErr := uuid.Parse(req.FromSessionID); pErr == nil {
parent = &pid
}
}
mode := repo.InheritedMode(r.Context(), parent, models.DefaultPermissionMode)
if _, sErr := repo.SetSessionPermissionMode(r.Context(), sessionID, mode); sErr != nil {
Error(w, http.StatusInternalServerError, "Failed to set permission mode")
return
}
_ = repo.SetSessionEnforcement(r.Context(), sessionID,
repo.AgentModeEnforcement(r.Context(), to.Name))
}
// 配额在建邮件之前扣：否则邮件已入库再报 403，收件方会看到一封发件方以为发失败的邮件。
// 只限制主动发信，不限制收信（卡住收信只会让邮件凭空消失）。
//
@ -373,6 +436,19 @@ func SendMail(w http.ResponseWriter, r *http.Request) {
}
if !attachAll(w, r, mailID, attachIDs, agentName) {
// 走到这里说明碰上了 checkAttachable 之后的竞态窗口（另一个请求把同一个
// 附件挂走了）。必须回滚已产生的副作用，否则收件方会拿到一封没有附件的
// 邮件，而发件方以为整次请求失败了。
//
// 三件事都要退：邮件本身、本次往返预算、relay 幂等键。
// 错误均忽略：响应已由 attachAll 写出，回滚失败只能记日志。
_ = repo.DeleteMailByID(r.Context(), mailID)
if !relayFree {
repo.RefundSessionBudget(r.Context(), sessionID)
}
if relay != "" {
_ = repo.ReleaseRelay(r.Context(), agentName, relayKey)
}
return
}