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 没有人类的会话。
103 lines
3.9 KiB
JavaScript
103 lines
3.9 KiB
JavaScript
/**
|
||
* 「一直同意」的跨进程持久化。
|
||
*
|
||
* # 为什么需要文件
|
||
*
|
||
* ZCode 的钩子是**一个事件一个进程** —— 批准完就退出。pi 桥那边的授权集合活在
|
||
* 常驻 worker 里（靠会话快照跨 worker），而这里没有可依附的常驻内存：
|
||
* 不落盘的话「一直同意」只在本次调用有效，而下一次调用是个新进程，
|
||
* 会再问一遍 —— 那个选项就成了骗人的（pi 桥的注释里原话是
|
||
* 「否则这个选项在骗人」）。
|
||
*
|
||
* # 判定语义不在这里
|
||
*
|
||
* 「什么是同意」「什么是一直同意」全部来自共用的 `lib/permission-grants.js`
|
||
* （逐字节同源）。本模块只管把结果存下来，不自己写判定正则 ——
|
||
* 那正是各平台会悄悄分叉的地方。
|
||
*
|
||
* # 并发
|
||
*
|
||
* 读-改-写。同一会话的两次授权请求几乎不会同时发生（ZCode 串行执行工具），
|
||
* 且写入是原子替换（临时文件 + rename），所以最坏情况是「后写覆盖先写」，
|
||
* 不会读到半截 JSON。真要并发也只会多问一次，不会漏判。
|
||
*/
|
||
|
||
import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
|
||
import { dirname, join } from 'node:path';
|
||
import { homedir } from 'node:os';
|
||
import { isAlwaysDecision } from './permission-grants.js';
|
||
|
||
/**
|
||
* 授权表文件的位置。
|
||
*
|
||
* 优先用显式配置，其次插件数据目录（ZCode 会注入 `ZCODE_PLUGIN_DATA`），
|
||
* 最后退回家目录下的固定名。三者都不存在的情况极罕见，
|
||
* 但必须有确定答案 —— 退回家目录至少让功能可用。
|
||
*/
|
||
export function grantsFilePath(env = process.env) {
|
||
if (env.AGENTMAIL_ZCODE_GRANTS_FILE) return env.AGENTMAIL_ZCODE_GRANTS_FILE;
|
||
if (env.AGENTMAIL_CONFIG_DIR) return join(env.AGENTMAIL_CONFIG_DIR, 'permission-grants.json');
|
||
if (env.ZCODE_PLUGIN_DATA) return join(env.ZCODE_PLUGIN_DATA, 'permission-grants.json');
|
||
return join(homedir(), '.agentmail-zcode', 'permission-grants.json');
|
||
}
|
||
|
||
/** 读盘。文件不存在或内容坏掉都当空表 —— 授权表读不出来不该让钩子崩。 */
|
||
export function loadGrants(filePath) {
|
||
try {
|
||
const raw = JSON.parse(readFileSync(filePath, 'utf8'));
|
||
const out = new Map();
|
||
for (const [session, tools] of Object.entries(raw?.sessions ?? {})) {
|
||
if (Array.isArray(tools)) out.set(session, new Set(tools.filter(t => typeof t === 'string')));
|
||
}
|
||
return out;
|
||
} catch {
|
||
return new Map();
|
||
}
|
||
}
|
||
|
||
function saveGrants(filePath, grants) {
|
||
const sessions = {};
|
||
for (const [session, tools] of grants) sessions[session] = [...tools];
|
||
const payload = { version: 1, sessions };
|
||
mkdirSync(dirname(filePath), { recursive: true });
|
||
// 原子替换：直接覆盖写会让并发读者看到半截 JSON（而上面的 load 会把它
|
||
// 当成空表，于是刚给的授权静默消失）。
|
||
const tmp = `${filePath}.tmp-${process.pid}`;
|
||
writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
|
||
renameSync(tmp, filePath);
|
||
}
|
||
|
||
/**
|
||
* 基于文件的授权表。
|
||
*
|
||
* @param {string} filePath
|
||
*/
|
||
export function createFileGrantStore(filePath) {
|
||
const grants = loadGrants(filePath);
|
||
|
||
return {
|
||
isGranted(sessionId, toolName) {
|
||
if (!sessionId || !toolName) return false;
|
||
return grants.get(sessionId)?.has(toolName) ?? false;
|
||
},
|
||
|
||
/** 只在决策文本确实是「一直同意」时落盘（判定交给共用库）。 */
|
||
grant(sessionId, toolName, decision) {
|
||
if (!sessionId || !toolName) return false;
|
||
if (!isAlwaysDecision(decision)) return false;
|
||
let set = grants.get(sessionId);
|
||
if (!set) grants.set(sessionId, (set = new Set()));
|
||
set.add(toolName);
|
||
saveGrants(filePath, grants);
|
||
return true;
|
||
},
|
||
|
||
/** 撤销整条会话的免批（换模型重开会话时用）。 */
|
||
revokeSession(sessionId) {
|
||
if (!grants.delete(sessionId)) return false;
|
||
saveGrants(filePath, grants);
|
||
return true;
|
||
}
|
||
};
|
||
}
|