|
|
be0693821b
|
fix(agents): 四家桥的 read_inbox 一律按会话收窄（dsh/opencode/zcode/homeagent）
用户：「你还是没修好不同 session agent 收件箱隔离的问题」。上一轮我只修了 **pi**，
另外四家还漏着 —— 它们是**每一家各自实现** read_inbox，不修就还是漏。
## 缺陷
列表按 Agent 列（整个收件箱），而 read_inbox 按契约把**列出来的都标成已读**
⇒ A 会话的回合会把 B 会话的未读标掉 ⇒ B 之后按 `?status=unread` 补投时
再也看不到那封信（静默丢信，不是"少看一封"）。用户是在别的 Agent 上看到它的。
## 四家的修法（各自平台能力不同，但都要"并发安全"）
| 桥 | 会话来源 | 为什么这样做 |
|---|---|---|
| dsh | 工具第二参数 `exec.agent.id` → `reverseMap` | 平台就在上下文里给了会话；**不能用模块级"当前会话"变量**（同进程可能同时跑多条会话的回合，会互相覆盖） |
| opencode | 工具第二参数 `context.sessionID` → `reverseMap` | 同上 |
| zcode | `AGENTMAIL_SESSION_ID`（在**调用时**读） | 一轮一个进程，驱动本来就注入它给授权钩子用；调用时读，避免将来复用进程拿到旧值 |
| homeagent | `p.currentSessionID`（回合开始设、结束清） | Go 插件，本来就有这个状态 |
取不到会话一律**退回整体收件箱**（历史行为），不猜 —— 猜错就是静默丢信。
## 判据
- 服务端语义：`server/internal/repo/session_scope_test.go`（读 A 不动 B、列表收窄、
计数与列表口径一致）。
- 桥侧接线：dsh 4 条、opencode 3 条、zcode 3 条、homeagent Go 1 条
（`TestInboxURLScopedBySession`，直接断言拼出来的 URL）。
每家都带**判据自检**：拿旧写法喂进来必须判红；dsh/opencode 还专门断言
"不得用模块级当前会话变量"。
- **部署件**（不是仓库）：四家的部署快照里都能 grep 到 `session_id=`。
- **线上实测**：用 opencode 自己的 Agent 身份请求收窄列表 —— 会话 A 3 封、
会话 B 0 封、两者无交集、且都是全量的子集。
套件：opencode **331**、dsh **381**、zcode **385**、homeagent ok，全绿。
四家桥已重新部署（dsh/opencode/zcode 快照切换 + homeagent 新 plugin.bin 并重启），
四个服务均 active。
|
2026-09-14 12:07:45 +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 |
|
|
|
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 |
|
|
|
e0e6f86d94
|
feat(zcode): AgentMail 的 ZCode 插件 —— MCP 工具面 + 官方宿主启动验证
ZCode 用插件扩展能力（.zcode-plugin/plugin.json 声明 skills/commands/hooks/
mcpServers），所以适配它的正确形状是**插件**而不是又一个独立桥进程。
本提交是第一步：把 AgentMail 的工具面做成 MCP 服务器。
协议层（lib/mcp-rpc.mjs）手写，不引 @modelcontextprotocol/sdk：
协议面只有 initialize / notifications/initialized / tools/list / tools/call，
手写可省掉一条构建链与 1MB 打包产物（与 pi/opencode/dsh 三桥零运行时依赖的
取向一致），并让这一层成为可穷举的纯函数。分帧照官方插件产物实测确认是
换行分隔 JSON（Content-Length 出现 0 次，StdioServerTransport + split("\n")）。
工具面（lib/tools.mjs）与另三个桥**同名同参**，渲染走共用的
addressing/inbox-format/discovery（逐字节同源，已纳入 check-shared-libs.sh）。
测试里有一条断言直接拿 pi 桥的工具名做对照：少一个就让某平台行为与其它平台不同，
那种问题只在单平台复现，排查代价最高。
两处按真实缺陷定的行为：
- 工具失败回 result+isError 而非 JSON-RPC error —— 后者会让模型看不到失败原因，
只能重试（opencode 连试 6 次发不出附件正是这个后果）
- attachment_ids 声明放宽为 anyOf 数组/字符串并在桥侧归一 —— 模型常写成
JSON 字符串，服务端严格解码会拒（同样来自 opencode 那次失败）
入口 mcp/server.mjs 修掉一个真实缺陷：stdin 关闭即 process.exit 会杀掉在途请求，
表现为「协议全对但访问网关的调用完全没有响应」。现按在途计数 drain，
且把 stdout 写入也计入，避免最后一条响应卡在缓冲区。
顺带修 check-shared-libs.sh 的一个既有假绿：本机 PATH 上的 diff 是鸿蒙 SDK
工具链的 diff，不认 -q 且对不同的文件仍返回 0 —— 于是该检查器**一直是永真输出**。
改用 cmp -s，并加自检（判据本身必须先被证明能发现差异）。反向验证：
让 zcode 或 pi 的共用模块分叉，检查器都正确报错并返回 1。
验证：
- 单元 33 项 + 继承共用测试 87 项 = 120/120
- `zcode plugins list` → agentmail@inline [enabled]，mcp: plugin:agentmail:agentmail
- 经官方 `node zcode.cjs __zcode-plugin-host <server.mjs>` 启动 → 握手与 tools/list 正常
- 真实网关调用：以 zcode 身份 read_inbox / suggest_address / list_contacts 均返回
|
2026-09-12 13:47:51 +08:00 |
|
