JianFeeeee
c5e1d562eb
第三步（补齐一等 Agent 的另一半）：驱动进程订阅 SSE，按邮件起一轮 headless
ZCode，取最终文本回信。
## --mode 是必传的（不传等于关掉授权系统）
ZCode 的权限判定里 `mode === "yolo"` 一律 allow
（"Yolo mode bypasses permission prompts"），而 `--prompt` 的默认 mode **就是 yolo**。
所以驱动不传 --mode 时：授权钩子根本不会触发，整个授权系统**静默消失** ——
不报错，只是没有任何询问，看起来一切正常。
档位映射（依据是 CLI 产物里的规则表，不是猜）：
plan → --mode plan （mode.plan.nonReadOnly：非只读一律拒）
workspace → --mode build（mode.build.highRisk / sideEffect：Bash/Write/Edit → ask）
full → --mode yolo （刻意绕过）
buildRunArgs 收不到 mode 直接抛错；测试里有一条反向对照钉住「只有 full 能得到 yolo」，
含大写 FULL（共用库 normalizeMode 严格匹配，落回 default 而不是 yolo —— 好性质，也钉住）。
## 一轮怎么跑
node <zcode.cjs> --prompt <提示词> --output-format stream-json \
--cwd <工作目录> --mode <m> [--resume sess_xxx] --max-turns N
用 stream-json 而不是 --json：`--json` 全程无输出，一个卡住的回合与一个正在
干活的回合在外部完全一样，而邮件驱动的会话没有界面，日志是唯一能看见它的地方。
输出契约（逐条事件 + 末尾 {type:"result",sessionId,response}）同样逆自 CLI 产物。
会话延续靠 --resume + 存回的 sess_…：丢了它模型每封信都从零开始。
## 回信策略（与另三桥同源）
- 人来信 → 自动把本轮最终文本回过去（relay:'summary' + relay_key 走免配额通道）
- Agent 来信 → **不**自动回（Agent 间必须自己 send_mail，否则两边把对方的
「已收到」当待办，无限客套）
- 一轮跑不起来 → **必回**失败信，且给出 ZCode 自己的成因（没登录/缺模型配置/
CLI 路径不对）。没有本地界面时，什么都不发等于「信发出去了，然后再无音讯」。
刻意不复用共用库那份 renderFailureReport：它的建议是「调整可用模型范围」，
对 ZCode 什么也解决不了。
- 模型这一轮自己发过信 → 让位。工具跑在 ZCode 派生的 MCP 服务器**进程**里，
与驱动内存不通，所以经 lib/explicit-sends.mjs 落盘对齐（不记的后果线上实测过：
收件箱里两封说同一件事的邮件，311 与 342 字节）。
## 两处健壮性（都是实现时自己发现的真问题）
- 超时必须**必然** settle：既不退也不报错的孩子会让 Promise 永不 settle，
而队列是串行的 → 那封信永远挂住、后面的信全都不再被处理。
现在 SIGTERM → SIGKILL → 无论如何收尾；定时器刻意不 unref
（unref 过的定时器让「没有其它句柄」的进程直接退出，收尾根本没机会跑）。
- 关停时终止在途回合：否则 systemd 杀掉驱动后那个 ZCode 还在跑工具，
而既没有驱动看着它、也没有本地界面看着它。
## 自报强制力只声明得出来的事
驱动启动时读自己的 hooks/hooks.json，确认 PermissionRequest 已注册才报 native，
否则报 advisory 并在日志里写明原因 —— 不替一个不存在的能力背书。
## 验证
- 单元 320/320（新增 90 项：turn-mode 8、zcode-run 17、driver 19、prompt 14 +
继承的共用测试；含反向对照）
- 邮件驱动端到端 7/7 × 3 次连跑稳定：桩 CLI 替掉 ZCode，真网关真邮件 ——
SSE 订阅、去重、工作目录、档位映射、参数拼装（--mode 必须对）、
stream-json 解析、回信、Agent 来信不回、CLI 失败必回失败信
- 授权桥端到端 5/5 × 3 次连跑稳定
- 共用模块四方同源（新纳入 catchup/relay-dedup/relay-policy/workspace，
反向验证：让 workspace.js 分叉会被抓住）
## 我自己写错并被测试抓出来的三处（值得记）
1. 验证脚本把人类发信写成了 /api/v1/mail/send（**Agent** 路由）→ 401。
报错「Missing Authorization: Bearer …」其实已经指明走错了路由表。
2. findReply 按「驱动验证（人）」这种片段找，第二次跑时命中了**上一轮遗留的回信**
→ 正文比对失败、后续参数核对变成「无法判定」。收件箱是跨轮次共享的持久状态，
必须按唯一 marker 定位（与之前「待决权限列表」那次是同一类错误）。
3. 停旧驱动只发 SIGTERM 不等退出 → 新旧两个驱动同时订阅 SSE，
同一封信被回两次，判据取到哪封取决于时序 → 时灵时不灵。改成等 exit 事件。
另：桩脚本用 process.exit 截断管道写入，导致 stderr 时有时无 —— 改用 exitCode。
108 lines
4.1 KiB
JavaScript
108 lines
4.1 KiB
JavaScript
/**
|
||
* 「模型这一轮自己发了信」的记录 —— MCP 服务器写，驱动读。
|
||
*
|
||
* # 为什么不能直接用共用的 relay-dedup
|
||
*
|
||
* `lib/relay-dedup.js` 的记录活在**进程内**（一个 BoundedMap）。在 pi 桥那里
|
||
* 工具与转发在同一个进程里，这没问题；但在 ZCode 这里，工具跑在 ZCode 派生出来的
|
||
* **MCP 服务器进程**里，而转发决定由**驱动进程**做 —— 两个进程，内存不共享。
|
||
*
|
||
* 不修这个的后果是线上实测过的：模型自己带着附件发了一封，驱动又把它的收尾话
|
||
* 转了一遍，收件箱里出现两封说同一件事的邮件（311 与 342 字节），
|
||
* 而其中带附件的那封才是模型真正想发的。
|
||
*
|
||
* 所以这里只做一件事：把记录落成 JSONL，让驱动能把「本轮发过什么」重建成
|
||
* 共用判据要的形状（`{names:Set, replyTos:Set}`），判定仍然交给
|
||
* `shouldSkipAutoRelay` —— 判据不能各平台自己写一份。
|
||
*
|
||
* # 位置必须两端一致
|
||
*
|
||
* 驱动起 ZCode 时把自己的环境传下去，ZCode 再起 MCP 服务器时继承同一份，
|
||
* 于是两边解析出同一个路径。解析顺序见 `explicitSendsFile`：
|
||
* 与授权表的 `grantsFilePath` 同构（都优先 AGENTMAIL_CONFIG_DIR）。
|
||
*/
|
||
|
||
import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
|
||
import { dirname, join } from 'node:path';
|
||
import { homedir } from 'node:os';
|
||
import { addrName } from './relay-dedup.js';
|
||
|
||
/** 超过这个条数就重写文件，只留最近的。记录本身是「本轮」级别的，留太多没意义。 */
|
||
const MAX_LINES = 500;
|
||
|
||
export function explicitSendsFile(env = process.env) {
|
||
if (env.AGENTMAIL_ZCODE_SENDS_FILE) return env.AGENTMAIL_ZCODE_SENDS_FILE;
|
||
if (env.AGENTMAIL_CONFIG_DIR) return join(env.AGENTMAIL_CONFIG_DIR, 'explicit-sends.jsonl');
|
||
if (env.ZCODE_PLUGIN_DATA) return join(env.ZCODE_PLUGIN_DATA, 'explicit-sends.jsonl');
|
||
return join(homedir(), '.agentmail-zcode', 'explicit-sends.jsonl');
|
||
}
|
||
|
||
/**
|
||
* 记一条「模型自己发的信」。
|
||
*
|
||
* 失败**不能**让 send_mail 失败：信已经发出去了。最坏后果是驱动多转一封总结，
|
||
* 而服务端的 relay_key 幂等还会兜一层。
|
||
*/
|
||
export function noteExplicitSendFile(file, { sessionId, to, replyTo, ts } = {}) {
|
||
if (!sessionId || !to) return false;
|
||
const line = JSON.stringify({
|
||
session_id: String(sessionId),
|
||
to: String(to),
|
||
reply_to: replyTo ? String(replyTo) : '',
|
||
ts: Number.isFinite(ts) ? ts : Date.now()
|
||
});
|
||
try {
|
||
mkdirSync(dirname(file), { recursive: true });
|
||
let lines = [];
|
||
try {
|
||
lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
|
||
} catch {
|
||
lines = [];
|
||
}
|
||
lines.push(line);
|
||
// 有界：这个文件活到桥重启为止，条目会一直累积（见文件头注释）。
|
||
if (lines.length > MAX_LINES) lines = lines.slice(-MAX_LINES);
|
||
// 原子替换：驱动可能正在读，半截 JSON 会被跳过（无害，但会让去重偶尔失灵）。
|
||
const tmp = `${file}.tmp-${process.pid}`;
|
||
writeFileSync(tmp, `${lines.join('\n')}\n`, 'utf8');
|
||
renameSync(tmp, file);
|
||
return true;
|
||
} catch {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 读回某条会话在 `since` 之后的主动发信记录。
|
||
*
|
||
* @param {string} file
|
||
* @param {{sessionId: string, since?: number}} opts
|
||
* @returns {{names: Set<string>, replyTos: Set<string>}} 直接可交给 shouldSkipAutoRelay
|
||
*/
|
||
export function readExplicitSends(file, { sessionId, since = 0 } = {}) {
|
||
const out = { names: new Set(), replyTos: new Set() };
|
||
if (!sessionId) return out;
|
||
let raw;
|
||
try {
|
||
raw = readFileSync(file, 'utf8');
|
||
} catch {
|
||
return out;
|
||
}
|
||
for (const line of raw.split('\n')) {
|
||
const t = line.trim();
|
||
if (!t) continue;
|
||
let rec;
|
||
try {
|
||
rec = JSON.parse(t);
|
||
} catch {
|
||
continue; // 写了一半的行：跳过
|
||
}
|
||
if (rec?.session_id !== String(sessionId)) continue;
|
||
if (since && Number(rec.ts) < since) continue;
|
||
const name = addrName(rec.to);
|
||
if (name) out.names.add(name);
|
||
if (rec.reply_to) out.replyTos.add(String(rec.reply_to));
|
||
}
|
||
return out;
|
||
}
|