feat: L0 线协议冻结 + 附件链路修复 + 人/Agent 区分
L0 核心： - 严格解码 Decode(DisallowUnknownFields) 全覆盖 29 个 DecodeBody 调用点 - DecodeLenient 心跳专用：容忍新字段但回报 unknown_fields - 400 消息列出本端点接受的全部字段（jsonFieldNames 反射 tag） - 日历 status 校验（create 补字段 + update 拦非法值） - 新增 strictdecode_test.go 10 例 + blob/list_test.go 6 例 A-4 附件挂载回滚：checkAttachable 在 CreateMail 前校验，失败按 解挂→释放 relay→删邮件→退预算回滚，幽灵邮件这条路堵住了 A-5 反向 GC：blob.Store.List() 枚举磁盘（跳 .upload-*）， SweepUnreferencedBlobs 按 attachments + calendar_attachments 反查， 48h 年龄下限兜上传窗口。已接进每小时 sweep 循环 C 人/Agent 区分：四个读路径 + threadCols 补 from_human / to_human （EXISTS users 判定），models.Mail 加 ToHuman。前端判据从 workspace 启发式改成显式布尔，mailCounterpart/sessionCounterpart 从 session_workspace 取 path（修 dsh@dsh 拼接 bug） 契约文档：SSE new_mail 补 4 字段（in_reply_to/from_human/ permission_mode/permission_enforcement），B-5 加 B-5.6 （Agent→Agent 不转发），B-3.4 MUST 改条件式，心跳补 mode_enforcement + unknown_fields，demo 死链修复 + from_human 检查 验收清单加 Agent→Agent 负向对照项
This commit is contained in:
208
plugins/opencode-mail-bridge/lib/bounded.js
Normal file
208
plugins/opencode-mail-bridge/lib/bounded.js
Normal file
@ -0,0 +1,208 @@
|
||||
/**
|
||||
* 有界容器 —— 给插件里那些「只增不减」的映射表兜底。
|
||||
*
|
||||
* # 为什么需要它
|
||||
*
|
||||
* 桥是**常驻进程**（pi 的守护进程能跑几十天，opencode/DSH 的插件跟着平台一起活）。
|
||||
* 里面每一张 `Map`/`Set` 都在回答「这条会话/这封邮件我处理过吗」，键来自外部
|
||||
* 事件流 —— 会话数与邮件数随时间单调增长，键却没有出口。
|
||||
*
|
||||
* 单条成本很小（uuid 键 + 短字符串值，几十到几百字节），所以它不是几小时内撑爆
|
||||
* 内存的那种故障。实际形态是：跑够久之后进程里躺着几十万个再也不会被查到的条目，
|
||||
* 且 **GC 回收不了**（还被强引用着）。这类问题不会在开发和测试里出现，
|
||||
* 只在生产上跑了几周后表现为「重启一下就好了」。
|
||||
*
|
||||
* # 淘汰策略：丢最久没被访问的
|
||||
*
|
||||
* JS 的 `Map`/`Set` 保证插入顺序，所以「删掉再插入」等价于「移到队尾」。
|
||||
* 读也算访问（`get`/`has` 会刷新顺序），于是长期活跃的会话不会因为条目老被丢掉 ——
|
||||
* 被淘汰的总是「很久没人问过」的那些。
|
||||
*
|
||||
* # 上限分表定义，因为丢一条的后果差别很大
|
||||
*
|
||||
* - `deliveredMails` 丢一条 → 那封邮件**理论上**可能被重复投递。但它防的两种
|
||||
* 重复（心跳与 SSE 建连之间的窗口、SSE 断线重放）都发生在秒到分钟级，
|
||||
* 几千封之前的 mail_id 不可能再来 —— 淘汰是安全的。
|
||||
*
|
||||
* - 会话级映射丢一条 → 那条会话下次来信时被当成新会话，平台侧上下文断掉。
|
||||
* 这是**真的行为退化**，所以上限给得大得多，并且优先靠 `session_archived`
|
||||
* 主动清理，让上限只当兜底。
|
||||
*
|
||||
* # 不要用它装「还在等结果的东西」
|
||||
*
|
||||
* 待决权限询问（opencode 的 `pendingPermissions`、DSH 的 `pendingApprovals`）
|
||||
* 里存的是 `resolve` 回调。静默淘汰一条会让对应的 `await` **永远不返回** ——
|
||||
* 平台侧那次工具调用就挂死了。那些表有确定的清理路径（决策到达 / 超时 / 拆插件
|
||||
* 时 fail closed），不该套上界。上界只适合「记录已经发生过的事实」的表。
|
||||
*
|
||||
* 三平台共用，必须逐字节相同（deploy/check-shared-libs.sh 校验）。
|
||||
*/
|
||||
|
||||
/**
|
||||
* 已投递邮件 id 的记忆上限。
|
||||
*
|
||||
* 2000 覆盖的是去重真正需要的时间窗：SSE 重放最多回放服务端环形缓冲的 500 条
|
||||
* 事件，一次补拉最多 5 封。留 2000 是三个数量级的余量，内存代价约 200KB。
|
||||
*/
|
||||
export const MAX_TRACKED_MAILS = 2000;
|
||||
|
||||
/**
|
||||
* 会话级映射的条目上限。
|
||||
*
|
||||
* 淘汰一条会让那条会话失去平台侧上下文，所以这个数字要远大于「同时在推进的
|
||||
* 任务数」。500 条 × 每条几百字节 ≈ 150KB —— 便宜到没有理由抠。
|
||||
*
|
||||
* 真正的清理来自 `session_archived`：会话归档后它的映射再无用处，那是确定性
|
||||
* 时机；上限兜的是「一直不归档」。
|
||||
*/
|
||||
export const MAX_TRACKED_SESSIONS = 500;
|
||||
|
||||
function normalizeLimit(limit) {
|
||||
const n = Number(limit);
|
||||
// 上限必须是正整数：0 会让每次 set 之后立刻把自己淘汰掉（表恒空，去重全部
|
||||
// 失效且不报错），NaN 会让 while 条件恒假（退化成无界）。两种都是静默的
|
||||
// 错误行为，不如当场拒绝。
|
||||
if (!Number.isFinite(n) || n < 1) {
|
||||
throw new RangeError(`有界容器的上限必须是 >= 1 的整数，收到 ${limit}`);
|
||||
}
|
||||
return Math.floor(n);
|
||||
}
|
||||
|
||||
/**
|
||||
* 有界 Map，超过上限时丢弃最久未访问的条目。
|
||||
*
|
||||
* 只实现桥里真正用到的那几个方法 —— 不做成 Map 的完整替身，那样会掩盖
|
||||
* 「这张表是有界的」这个必须被看见的事实。
|
||||
*/
|
||||
export class BoundedMap {
|
||||
/** @param {number} limit 条目上限 */
|
||||
constructor(limit) {
|
||||
this.limit = normalizeLimit(limit);
|
||||
/** @type {Map<any, any>} */
|
||||
this.map = new Map();
|
||||
/** 累计淘汰条数，观测用（日志里能看出上限是否设得太小）。 */
|
||||
this.evicted = 0;
|
||||
}
|
||||
|
||||
get size() {
|
||||
return this.map.size;
|
||||
}
|
||||
|
||||
has(key) {
|
||||
return this.map.has(key);
|
||||
}
|
||||
|
||||
/**
|
||||
* 取值并把该键移到队尾。
|
||||
*
|
||||
* 读也算访问：一条会话只要还在收信就会被反复 get，不刷新的话它会因为
|
||||
* 「插入得早」被淘汰 —— 那恰好淘汰了最该留的那些。
|
||||
*/
|
||||
get(key) {
|
||||
if (!this.map.has(key)) return undefined;
|
||||
const value = this.map.get(key);
|
||||
this.map.delete(key);
|
||||
this.map.set(key, value);
|
||||
return value;
|
||||
}
|
||||
|
||||
/** 取值但**不**刷新顺序。给「只是想看一眼」的场合。 */
|
||||
peek(key) {
|
||||
return this.map.get(key);
|
||||
}
|
||||
|
||||
set(key, value) {
|
||||
// 已存在时先删：Map 的 set 不改变已有键的位置，不删就刷不了活跃度。
|
||||
if (this.map.has(key)) this.map.delete(key);
|
||||
this.map.set(key, value);
|
||||
while (this.map.size > this.limit) {
|
||||
const oldest = this.map.keys().next().value;
|
||||
this.map.delete(oldest);
|
||||
this.evicted++;
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
delete(key) {
|
||||
return this.map.delete(key);
|
||||
}
|
||||
|
||||
clear() {
|
||||
this.map.clear();
|
||||
}
|
||||
|
||||
keys() {
|
||||
return this.map.keys();
|
||||
}
|
||||
|
||||
values() {
|
||||
return this.map.values();
|
||||
}
|
||||
|
||||
entries() {
|
||||
return this.map.entries();
|
||||
}
|
||||
|
||||
[Symbol.iterator]() {
|
||||
return this.map[Symbol.iterator]();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 有界 Set，超过上限时丢弃最久未访问的成员。
|
||||
*
|
||||
* `has` 也刷新顺序：与 `BoundedMap.get` 同理。对 `deliveredMails` 这意味着
|
||||
* 「刚被去重挡下的那封」会留得更久，正合语义。
|
||||
*/
|
||||
export class BoundedSet {
|
||||
/** @param {number} limit 成员上限 */
|
||||
constructor(limit) {
|
||||
this.limit = normalizeLimit(limit);
|
||||
/** @type {Set<any>} */
|
||||
this.set = new Set();
|
||||
this.evicted = 0;
|
||||
}
|
||||
|
||||
get size() {
|
||||
return this.set.size;
|
||||
}
|
||||
|
||||
has(value) {
|
||||
if (!this.set.has(value)) return false;
|
||||
this.set.delete(value);
|
||||
this.set.add(value);
|
||||
return true;
|
||||
}
|
||||
|
||||
/** 判断存在但**不**刷新顺序。 */
|
||||
peek(value) {
|
||||
return this.set.has(value);
|
||||
}
|
||||
|
||||
add(value) {
|
||||
if (this.set.has(value)) this.set.delete(value);
|
||||
this.set.add(value);
|
||||
while (this.set.size > this.limit) {
|
||||
const oldest = this.set.values().next().value;
|
||||
this.set.delete(oldest);
|
||||
this.evicted++;
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
delete(value) {
|
||||
return this.set.delete(value);
|
||||
}
|
||||
|
||||
clear() {
|
||||
this.set.clear();
|
||||
}
|
||||
|
||||
values() {
|
||||
return this.set.values();
|
||||
}
|
||||
|
||||
[Symbol.iterator]() {
|
||||
return this.set[Symbol.iterator]();
|
||||
}
|
||||
}
|
||||
@ -7,6 +7,8 @@
|
||||
// 实测踩过 —— 插件静默不加载，邮件全都投不进去。
|
||||
// 因此入口文件只能 `export default`，其余东西一律搁在这里。
|
||||
|
||||
import { BoundedMap, MAX_TRACKED_SESSIONS } from './bounded.js';
|
||||
|
||||
/** 取三维地址的名字段：admin@root.alias -> admin */
|
||||
export function addrName(addr) {
|
||||
return String(addr || "").split("@")[0].trim();
|
||||
@ -25,8 +27,18 @@ export function addrName(addr) {
|
||||
*
|
||||
* 窗口是「一轮」：deliverMail 投递新邮件时清空（新一轮开始），
|
||||
* relaySummary 用完即清。
|
||||
*
|
||||
* # 为什么仍要有界
|
||||
*
|
||||
* 上面那些清理路径都要求「这个会话之后还有事发生」。一条只发过一次信、
|
||||
* 之后既没有新邮件也没有 idle 的会话（模型自己发完就没动静了，或者插件在
|
||||
* 那一轮之后重连），条目就永久留下。桥是常驻进程，这种残留会一直累积。
|
||||
*
|
||||
* 淘汰是安全的：条目的语义是「本轮已经亲手回过」，而「本轮」是分钟级的。
|
||||
* 丢掉一条很久以前的记录最坏结果是那条会话下一次 idle 时多转一封总结，
|
||||
* 而服务端的 relay_key 幂等还会兜一层。
|
||||
*/
|
||||
export const explicitSends = new Map(); // opencode session id -> { names:Set, replyTos:Set }
|
||||
export const explicitSends = new BoundedMap(MAX_TRACKED_SESSIONS); // opencode session id -> { names:Set, replyTos:Set }
|
||||
|
||||
/** 记下模型这一轮主动发了信，给谁、回的哪封。 */
|
||||
export function noteExplicitSend(sessionID, to, replyTo) {
|
||||
|
||||
Reference in New Issue
Block a user