|
|
d015d3694c
|
test(zcode): 把门禁判决实验收进仓库（test/manual/gate-e2e.py）
它是「yolo + 自有工具面 + 我们自己的门禁」这个姿态**唯一**的决定性验证：
批了→命令真执行（比对文件内容，不只看回信）；拒了→命令真没执行（文件不存在）
**且回信把成因说成「人拒绝」而不是「超时」**；同会话第三次调用仍产生新请求
并在获批后执行（幂等键按调用唯一）。之前只放在 /root 下，会随环境丢弃。
顺手修两处会骗人的东西：
1. **不要用 `python3 run.py | tee log` 再取 `$?`** —— 那是 tee 的退出码（恒 0）。
实测踩过：脚本自己打印 5/6（有失败），后台任务通知却报 exit-code 0，
日志里那句 `EXIT=0` 完全是噪声。现在脚本把**自己的** exit_code 写进证据文件，
README 也改成 `set -o pipefail` 的调用方式。
（同源问题第三次：PIPESTATUS 在 dash 下报错、`go build | head` 假绿、这次是 tee。）
2. **备注文字不再显示在通过项旁边** —— 通过的判据曾挂着「很可能又被当成重复请求
丢弃了」这种失败提示，会把「全绿」读成「有问题」。
已从仓库路径连跑三次 13/13（不同标记），确认收进仓库后仍可用。
|
2026-09-12 19:11:58 +08:00 |
|
|
|
3a6d572020
|
feat(zcode): 工具加 MCP 注解 + headless 档位映射改为 plan（否则一个工具都用不了）
## 逆出 ZCode 的 MCP 权限判定，并据此让工具真的可用
逐字逆自 CLI 产物：
Ari(): annotations.readOnlyHint === true → riskLevel "low"
annotations.destructiveHint === true → riskLevel "high"
needsApproval = true ← **硬编码为真，与注解无关**
checkBuildMode(): needsApproval || destructive || sideEffectScope !== "none" → ask
checkPlanMode(): permissionName === "mcp" && !destructive → allow
两条合起来的结论不直观但很关键：
- **build 档下每一个 MCP 工具都要审批**（needsApproval 恒真），而 headless
模式没有交互式审批客户端 ⇒ 全被拒。实测：模型连 read_inbox 都调不动，
只能从提示词里猜；更糟的是它**绕道**用 Bash 去读网关的 sqlite WAL 文件
（它自己在回信里如实交代了这件事）。
- **plan 档下只要不声明 destructive，MCP 工具直接放行**。
于是两处改动：
1. `lib/tools.mjs` 给每个工具加真实注解（读类 readOnlyHint，写类
destructiveHint:false——它们确实不破坏任何东西）；`lib/mcp-rpc.mjs` 透传
annotations。**漏传不是"少个提示"，而是工具在该档下全被拒**。
2. `src/turn-mode.mjs` 的 workspace 档映射从 build 改为 **plan**。
build 在本环境等于「什么都不能做」，那不是保守而是不可用；plan 才是真的
fail-closed：危险的自带工具被平台直接拒，能用的只有我们声明为非破坏性的工具。
日志会明确写出为什么退档。可用 `AGENTMAIL_ZCODE_MODE_MAP` 覆盖
（平台修好钩子后只改配置就能恢复 build，不必等发版）。
## 真模型验证
场景 A 的判据同时加强：**正文本标记只出现在邮件正文里**（驱动的提示词只带主题
与 mail_id），所以模型必须真的读信才可能答对。通过 —— 约 20-30 秒一轮。
反过来说，早先那版「通过」是假的：标记在主题里，模型从提示词抄一遍就行。
## 仍然做不到的（见 README 已知缺口）
授权桥（PermissionRequest 钩子）在本版本（3.10.2 / CLI 0.16.5）**不可用**：
有时根本不触发，触发时在 ~5ms 内失败且**命令从未被 spawn**
（用「钩子写 marker 文件」的副作用验证，process 与 command 两种类型都一样）。
所以 workspace 档「危险操作问人」目前在 headless 下无法实现。
单元 329/329。
|
2026-09-12 16:49:28 +08:00 |
|
|
|
42816b4d1e
|
fix(zcode): 真模型跑通后发现的三处缺陷（register / 工具活动日志 / SSE 关停）
真模型端到端（场景 A 通过：6893 事件、175 秒、530 字回信）把三处只有真跑才
暴露的问题照了出来：
1. **register 调不通**：驱动按 pi 的客户端 API 写了 `client.register()`，
而本插件的 GatewayClient 没有这个方法 —— 靠此前手工注册过才没暴露。
补上后才发现第二个坑：`/agent/register` 的认证与其它接口**不同**，
它只认 `Authorization: Bearer` 或 **body 里的 `secret`**，不认 `X-Agent-Secret`
头（其它接口认）。实测报错：
HTTP 400 需要 Authorization: Bearer <密钥> 或 body 里的 secret
所以没密钥时把 secret 放进 body。
2. **一轮 6893 条事件，日志里什么也看不见**：邮件驱动的会话没有界面，
「模型正在干什么」只能来自日志，否则一个五分钟的回合与一个卡死的回合
在外部完全一样。新增 `describeRunEvent`，只记工具调用与权限事件
（全记等于没有日志），并由 runTurn 通过 onEvent 逐个交出来。
3. **关停没真断 SSE**：驱动调的是 `client.stopSSE?.()`，而客户端没有这个方法
（`?.` 让它静默变成空操作）。改成持有 createSSEClient 的句柄并在关停时 stop。
验证：单元 325/325、授权桥 e2e 5/5、驱动 e2e（桩）7/7、快照握手 12 项。
|
2026-09-12 16:16:37 +08:00 |
|
|
|
c5e1d562eb
|
feat(zcode): 邮件驱动 —— 收到来信就自动开工，并把结论回信
第三步（补齐一等 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。
|
2026-09-12 14:58:36 +08:00 |
|
|
|
c774904c0c
|
feat(zcode): 授权桥 —— PermissionRequest 钩子把危险工具授权交给人
第二步：让 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 没有人类的会话。
|
2026-09-12 14:09:10 +08:00 |
|
