JianFeeeee
c774904c0c
第二步：让 ZCode 上的 Bash/Write/Edit 授权走 AgentMail 的人工审批，
而不是只靠本地界面。
钩子契约从 CLI 产物里逆出来（不猜协议）：
- 输入走 stdin：{hook_event_name, tool_name, tool_input, session_id, permission_mode…}
- 输出走 stdout，schema **严格**：{"decision":"approve"} / {"decision":"block","reason"}
多一个键就会报 "Hook stdout failed HookJSONOutput schema validation"
- 空输出 / 不以 { 开头 = 不表态；exit 2 = 拒绝；其它非零 = 钩子失败
- 注入的环境变量含 ZCODE_PLUGIN_ROOT / ZCODE_PLUGIN_DATA / ZCODE_SESSION_ID
（MCP 配置里用 ZCODE_SESSION_ID 反而会抛「需要运行时会话上下文」）
档位判定与 pi 桥逐条对齐（plan 直接拒 / workspace 问人 / full 批准），
判定逻辑抽成纯函数 lib/hook-policy.mjs 以便穷举：
其中 full 档必须**返回批准而不是不表态** —— 钩子一旦触发说明 ZCode 本会去问人，
不表态等于让那个询问照常发生，full 档就退化成了 workspace 档。
钩子自己开 SSE 等决定，不依赖桥进程：网关的 SSE 是扇出的
（clients 按唯一 id 存，SendToAgent 推给该 Agent 的所有客户端），
一次性进程也能订阅到自己那条 permission_decision。这样交互模式下同样可用
（人自己开着 ZCode 干活时并没有桥在跑）。先建连再发请求是有意的：
反过来会有一个窗口，人在窗口内点的同意推送给当时还不存在的客户端。
fail closed 但区分模式：永久失败（409/4xx）一律拒绝；暂时失败在
AGENTMAIL_SESSION_ID 非空（邮件驱动、没有本地界面兜底）时拒绝，
交互模式则不表态让人就地决定。
「一直同意」落盘（lib/grants-file.mjs）：钩子是一个事件一个进程，
不落盘那个选项就是骗人的。判定仍交给共用的 permission-grants.js。
共用模块同源范围扩到 9 个（新增 permission-mode / relay-key /
permission-grants / sse-client）—— 档位语义与决策判定分叉会让「同意」
在 ZCode 上悄悄变成另一种意思。
验证：
- 单元 229/229（新增 hook-policy 14 项、grants-file 8 项，含反向对照）
- 共用模块四方同源检查通过
- 授权桥端到端 5/5，全部带反向对照：
同意→approve；拒绝→block 且原因必须来自人的拒绝（不能是超时兜底）；
plan 档拒绝且**不产生**任何权限邮件；无人可问(409)→fail closed；
非守卫工具→不表态
- `zcode plugins list` → agentmail@inline [enabled]，hooks: 1，
mcp: plugin:agentmail:agentmail
我自己写错的两处判据（都已修，值得记下）：
1. 待决权限列表里有历史积压（实测 6 条，含其它 Agent 的条目），
只按「第一条新的」取会拿到无关请求 —— 于是人点了同意而钩子在等自己那条，
最后超时。第一版还把这个超时误报成「拒绝路径通过」。
现在按「启动前快照差集 + session_id + agent_name」三重过滤。
2. 「无人可问」控制组最初传了个非 UUID 的 session id，走的是 400（参数错），
验不到 409 那条真实路径。改为真的造一条只有 Agent 没有人类的会话。
128 lines
5.2 KiB
JavaScript
128 lines
5.2 KiB
JavaScript
/**
|
||
* relay_key 长度收敛 —— 四个平台共用。
|
||
*
|
||
* ## 为什么需要它
|
||
*
|
||
* relay_key 是免配额通道的幂等键，服务端列宽 160 字节（超了返回 400）。
|
||
* 插件按「会话 id + 某个平台侧调用 id」拼这个键，平常七十来字节，很安全。
|
||
*
|
||
* 但生产上踩到一次：pi 会话里 bash 的 relay_key 突然超限，报文
|
||
* 「relay_key 过长（上限 160 字节）」。查真实会话文件后发现 toolCallId
|
||
* 有两种形态：
|
||
*
|
||
* toolu_bdrk_01F6roEBHa8nic1mYiyLgNWK 35 字节
|
||
* toolu_bdrk_01FsWUWhEs4arnEWo44gqzLC~sig1:CAISoQIK… 437 ~ 13601 字节
|
||
*
|
||
* 启用 extended thinking 时 Bedrock 把**思考签名**拼进了 toolCallId。
|
||
* 同一条会话里两种形态混着出现，于是同一个 Agent 的权限询问随机成功随机失败。
|
||
*
|
||
* 后果不只是「这一次没送达」：那次失败被归入「暂时失败 → 让位给本地决策」，
|
||
* 而邮件驱动的 worker 没有 TUI，没有人可问 —— 那次 bash 调用**没有任何人
|
||
* 批准就执行了**。守卫形同虚设。
|
||
*
|
||
* ## 为什么用哈希而不是直接截断
|
||
*
|
||
* 直接截断会让两次不同的调用撞成同一个键（前缀相同后缀被切掉），
|
||
* 而这个键的全部意义是幂等：撞键意味着第二次询问被服务端当成重复请求丢掉。
|
||
* sha256 的碰撞概率可以忽略，且**同样的输入永远得到同样的输出** ——
|
||
* 这一点是必须的：插件重启后重放同一轮，必须算出同一个键。
|
||
*
|
||
* ## 为什么保留可读前缀
|
||
*
|
||
* 纯哈希在日志里没法看出是哪条会话。保留前缀让 `grep 会话id` 仍然有用。
|
||
* 前缀按**字节**截断并回退到字符边界 —— 键里可能有中文（邮件主题派生的键），
|
||
* 按字符数算会超字节上限，按字节硬切会切出半个字符。
|
||
*/
|
||
|
||
import { createHash } from 'node:crypto';
|
||
|
||
/** 服务端 relay_key 列宽（字节）。与 gateway 侧 160 保持一致。 */
|
||
export const RELAY_KEY_MAX_BYTES = 160;
|
||
|
||
/** `:sha256:` + 64 位 hex */
|
||
const HASH_SUFFIX_BYTES = 8 + 64;
|
||
|
||
/**
|
||
* UTF-8 字节数。
|
||
*
|
||
* @param {string} s
|
||
* @returns {number}
|
||
*/
|
||
export function byteLength(s) {
|
||
return Buffer.byteLength(String(s ?? ''), 'utf8');
|
||
}
|
||
|
||
/**
|
||
* 按字节截断，回退到最近的字符边界（不产生半个字符）。
|
||
*
|
||
* @param {string} s
|
||
* @param {number} maxBytes
|
||
* @returns {string}
|
||
*/
|
||
export function truncateToBytes(s, maxBytes) {
|
||
const str = String(s ?? '');
|
||
if (maxBytes <= 0) return '';
|
||
const buf = Buffer.from(str, 'utf8');
|
||
if (buf.length <= maxBytes) return str;
|
||
|
||
let end = maxBytes;
|
||
// UTF-8 续字节是 10xxxxxx。若第一个被丢掉的字节是续字节，
|
||
// 说明切点落在字符中间 —— 往前退到该字符的首字节之前。
|
||
while (end > 0 && (buf[end] & 0xc0) === 0x80) end--;
|
||
return buf.subarray(0, end).toString('utf8');
|
||
}
|
||
|
||
/**
|
||
* 把 relay_key 收敛到服务端能接受的长度。
|
||
*
|
||
* 未超限时**原样返回** —— 这一点很重要：绝大多数键本来就合规，
|
||
* 改写它们会让插件升级前后算出不同的键，等于把已发出的询问变成新询问。
|
||
*
|
||
* @param {string} key 原始键
|
||
* @param {number} [limit] 上限字节数，默认 RELAY_KEY_MAX_BYTES
|
||
* @returns {string} 长度不超过 limit 的键
|
||
*/
|
||
export function clampRelayKey(key, limit = RELAY_KEY_MAX_BYTES) {
|
||
const raw = String(key ?? '');
|
||
if (byteLength(raw) <= limit) return raw;
|
||
|
||
const hash = createHash('sha256').update(raw, 'utf8').digest('hex');
|
||
const suffix = `:sha256:${hash}`;
|
||
// 上限小到装不下哈希时只留哈希（截断哈希仍然确定，只是碰撞面变大；
|
||
// 这条路径在真实配置下不会走到 —— 160 远大于 72）。
|
||
if (limit <= HASH_SUFFIX_BYTES) return truncateToBytes(hash, limit);
|
||
|
||
const prefix = truncateToBytes(raw, limit - HASH_SUFFIX_BYTES);
|
||
return `${prefix}${suffix}`;
|
||
}
|
||
|
||
/**
|
||
* 这次失败是不是「永远不会成功」。
|
||
*
|
||
* ## 为什么必须分类
|
||
*
|
||
* 插件在权限询问发送失败时有两条路：让位给平台本地决策，或当场 block。
|
||
* 原来除 409 之外一律当「暂时失败」让位 —— 而 400（请求本身不合法）
|
||
* 重试一万次也是 400。邮件驱动的会话**没有本地 UI**，让位等于让守卫消失：
|
||
* 生产实测一次 bash 就这样在无人批准的情况下执行了。
|
||
*
|
||
* ## 判据
|
||
*
|
||
* - 4xx（除 408 / 429）= 永久：请求本身有问题，重试不会变好
|
||
* - 408 / 429 = 暂时：超时与限流，等一会儿真的可能成功
|
||
* - 5xx = 暂时：服务端的问题
|
||
* - 无 status（网络层错误、DNS、连接被拒）= 暂时
|
||
*
|
||
* 401 归到永久：密钥无效要人去后台重新登记，不是等一等就好的事
|
||
* （本会话实测过一次 —— opencode 拿着已撤销的密钥重试了 18 小时）。
|
||
*
|
||
* @param {{status?: number}} err
|
||
* @returns {boolean} true = 永久失败，插件必须当场表态
|
||
*/
|
||
export function isPermanentFailure(err) {
|
||
const status = Number(err?.status);
|
||
if (!Number.isFinite(status) || status <= 0) return false; // 网络层错误 → 暂时
|
||
if (status === 408 || status === 429) return false; // 超时 / 限流 → 暂时
|
||
return status >= 400 && status < 500;
|
||
}
|