jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
188 Commits 1 Branch 0 Tags
22c9be7181cdc4c8aa5e66074ab5108abc54775e
Commit Graph

34 Commits

Author SHA1 Message Date
JianFeeeee
ca96f77a4b fix(appearance): 浏览器里同步从来没跑起来（三处叠加）+ 部署链加"前端不得比源码旧"闸门 
用户说「webui 你也没改呢」。查证：**部署是活的**（本地产物 = 线上产物、CSS 里壁纸
修复的规则都在、入口 `Cache-Control: no-cache`、资源哈希+immutable）——是我新加的
"外观存服务端"那套在**浏览器**里根本没生效。沿途挖出三处叠加缺陷 + 一处部署链真空子：

## ① 路径写成绝对 `/api/v1/...`（双前缀 ⇒ 404）

`resolveBase()` 解析出来的 base 已经含 `/api/v1`（默认就是它），既有调用者传的都是
`/me/mail/inbox` 这种**相对基地址**的形状。我写成 `/api/v1/me/appearance` ⇒ 实际请求
`/api/v1/api/v1/me/appearance` ⇒ 404。
**单测全绿却没抓住**：我只断言了方法、报文，没断言 URL。现在补了 URL 判据
（含"不得出现 /api/v1/api/v1"这条）。

## ② 浏览器密码登录只有 cookie、没有 Bearer ⇒ `currentAuth()` 直接短路

`currentAuth()` 原先要求 token 非空，而密码登录只建 cookie 会话（桌面端粘贴用户密钥
才设 Bearer）⇒ WebUI 里 `pull/push` 从来没跑过。已放宽为"只要有 base"，并补了两条
判据（cookie 会话也要能拉、能推）。
（"完全没有网关地址 ⇒ local-only"这条判据删掉了：`resolveBase()` 总有默认值，
那个状态到不了 —— 判据不量够不着的对象。）

## ③ 服务端"无记录"时拿默认值覆盖本地

首次启用同步时每个老用户都会中招：服务端回默认值（theme=system / bg=none），
客户端照着应用 ⇒ **用户已有的主题与本地壁纸被静默重置**。现在改为"以本地为准、
推上去认领"，并补判据（含"有记录时以服务端为准"的反向对照）。

## ④ 部署链真空子：dist 比源码旧也能"同步成功"

改完源码忘了 `vite build`，`redeploy-gateway.sh` 照样把旧 dist 打进二进制 —— 这正是
①在线上一直没被发现的直接原因。现在部署脚本会比对 `src/**` 与 `dist/index.html`
的 mtime，旧了就 **FAIL** 并提示先 build。

## 顺带：我自己在真实账号上留的测试数据

线上 E2E 时我把 `theme=dark/bg=preset(dusk)/dim=35` PUT 到了 **jianf** 这个真实账号
（应该用测试账号）。已删掉那条记录（接口现在回 `saved:false`），配合 ③ 的修复，
用户本地那份外观会被认领上去而不会被覆盖。

## 验证

- 浏览器实测（自带无头 Chromium + 真实功能，非注入 CSS）：
  `200 GET /api/v1/me/appearance` → `data-bg=on`、`dark=true`、本地缓存写入 ✓
- 三张对比图（自定义图片档 / 关背景 / 预设渐变）已随邮件发给用户
- 前端 253 条（含新增 URL 判据与 cookie 会话判据）、server 10 包、打包一致性全绿
 2026-09-14 08:59:32 +08:00
JianFeeeee
69b1887eae chore(deploy): 清理部署残留（1.0GB）+ 把清理写成可复跑脚本 
用户说「清理一下」。实测 /opt/agentmail 累计 1.3GB：
- 网关旧二进制 33 份 × 24MB ≈ 790MB（每次 redeploy 留一份，从 09-05 起没清过）
- 插件快照：opencode 6 份 339MB、dsh 7 份 195MB、zcode 16 份、pi 9 份
- /tmp 里的部署前数据库备份 10 份（tmpfs，占内存）

新增 `deploy/prune-deploy-artifacts.sh`（可复跑，不手敲 rm），两条硬规矩：
① **保留回滚窗口**：网关留最新 3 份、每个插件留最新 3 份快照，`current` 永远保留
（发布纪律要求有回滚目标，所以不是全清）；
② ★ **绝不删正在使用的快照**：扫 /proc 的 cmdline 与 cwd，命中就跳过。

执行结果：**/opt/agentmail 1305MB → 302MB（释放 1003MB）**，7 个服务全部 active，
`current` 指向未变，`check-deploy-drift` 仍报「四个宿主都在跑当前代码」。

## 过程中的一处自纠

"在用"闸门第一版有**自我匹配**缺陷：我的测试命令把路径写在命令行里，于是扫 /proc 时
扫到了自己 ⇒ 对不存在的路径也判"在用"（与 `pkill -f` 杀掉自己那条命令同一类）。
已改为排除本进程及其祖先链，并**换正确方式重测**（路径从文件读、不进 cmdline）：
在用快照判"在用" ✓、不存在的路径不误判 ✓ —— 判据两侧都验过才敢执行删除。

文档：docs/DEV-TOOLING.md 记了用法与那两条规矩。
 2026-09-14 08:43:54 +08:00
JianFeeeee
51789ee72e deploy: 标准目录部署 —— 运行时不再依赖源码目录 
用户注意到：「当前 agentmail 是在源码目录部署的，应当改为标准目录部署」。
查证后有三处实证（都不是猜测）：

1. ★ **失败通知钩子执行的是仓库里的脚本**
   （`/home/program/agentmail/deploy/service-failure-notify.mjs`，8 处引用：
   4 个 drop-in + zcode/zcode-mail-bridge 单元 + agentmail-failure-flush）。
   仓库一挪/一改名，故障通知就**静默失效** —— 而那条管线正是用来报告服务故障的。
2. **opencode-serve 的 cwd 就是源码目录**（`WorkingDirectory=/home/program/agentmail`）。
3. ★ **仓库里的 `deploy/*.service` 是旧的源码目录版本**（ExecStart 指向
   `/home/program/agentmail/plugins/...`），而机器上的已被改过 —— 也就是说
   **谁跑一次 install.sh 就会把部署退回源码目录**。drop-in 更是只存在于 /etc 里，
   仓库完全没有它们。

## 改动

- **唯一真相**：`deploy/systemd/` 镜像 systemd 目录结构，收进全部单元与 drop-in
  （8 个单元 + 12 个 drop-in），路径全部改到 `/opt`。
- 运行时脚本装到 **`/opt/agentmail/bin/service-failure-notify.mjs`**（自包含，
  无相对导入）；`install.sh` 与 `redeploy-gateway.sh` 都会幂等地装它。
- opencode 的 cwd 改为 `/opt/agentmail`（与网关一致），已重启生效
  （`/proc/<pid>/cwd` 已核）。
- 删掉 `deploy/*.service` 的旧副本，避免两个真相。
- dsh 的 `cordis.patch.yml` 注释里的安装示例也改到标准位置（运行时用的是环境变量，
  那条注释是唯一残留）。

## 判据（`deploy/check-deploy-drift.mjs` 新增「标准目录部署」四条 + 自检）

① 任何 unit/drop-in 都不得引用源码目录；② 已安装单元与 `deploy/systemd/` 逐字节一致；
③ 通知脚本在标准位置且可执行；④ 各服务的 cwd/ExecStart 不在源码目录
（homeagent/dsh/zcode 是**别的产品**的标准位置，按白名单放行）。
自检两个样本：引用源码目录的必须红、干净样本必须绿（证明不是恒真）。

顺带修掉一处**真漂移**：仓库里 dsh 的 `dist/index.js` 落后于部署件（改了 src 没重建），
重建后 `check-deploy-drift` 报「四个宿主都在跑当前代码」。

## 复核

- `/etc/systemd/system/` 引用仓库：**0** 个文件；`/opt/agentmail` 下只剩旧二进制/备份里
  的构建路径（Go 嵌的源码路径，无害）与一条注释。
- 四个宿主都在跑当前代码；标准目录四项全绿。
- 全部服务 active，opencode/网关 cwd 均已在安装根下。
 2026-09-14 08:38:33 +08:00
JianFeeeee
2922fb711f fix(deploy): 故障通知的三处缺陷 —— 死信目录、隔夜补投、失败无原因 
起因：用户邮箱里「[dsh] 桥服务异常终止」反复出现。查下来有两层。

**第一层：崩溃本身（已修，是历史）**
dsh 在 2026-09-12 11:40 起崩溃循环，根因是当时那次插件快照切换后
`/root/.dsh/profiles/web/node_modules/dsh-mail-bridge/cordis.patch.yml` 不存在
（`failed to read overlay … ENOENT`）→ 起不来 → systemd 反复重启。
现在快照里该文件在、dsh `NRestarts=0`、今天 0 次失败。

**第二层：通知管线本身坏了（本次修）**

1. ★ **死信目录**：`zcode.service`（应用单元）既没有 `AGENTMAIL_AGENT_NAME` 也没有
   密钥，报告就落进 `unknown-agent/` —— 而 flush **只读自己那个 Agent 的目录**，
   于是 25 份 zcode 崩溃告警永久投不出去。修法是两件事：
   · `resolveIdentity()`：身份按「单元 env → 单元名推导 → /etc/agentmail/<agent>.env」
     解析；`zcode.service`→zcode、`pi-mail-bridge.service`→pi……
   · 支持 `AGENTMAIL_AGENT_SECRET`：zcode 只配了 secret 没有 key，而脚本原先只认
     Bearer key ⇒ 就算目录对了也发不出去（网关的 AgentAuth 两种都认）。

2. ★ **隔夜补投**：补投原先只在**同一个单元**的下次 `ExecStartPost` 跑，于是
   网关不可达时攒下的报告要等到那个服务自己重启才补投 —— 实测 4 封 Sep-12 的
   告警在 Sep-13 10:35 才到。现在新增 `agentmail-failure-flush.timer`（每 10 分钟
   `--flush-all`），它遍历所有 Agent 目录、按目录名逐个解析身份后补投。
   过时报告还会在主题与正文上标 **「补投：这是 N 分钟前的故障报告，不代表现在仍在
   故障」**（原先正文里只有昨天的时间戳，读起来像刚崩）。

3. **补投失败只报数不报因**：`catch { failed++ }` → 日志只有 `spool: sent=0 failed=4`，
   没人知道卡在哪。现在每条失败都带回原因（HTTP 状态码/网关不可达/身份未配置）。

4. 顺带两处准确性问题：
   · 主题写**单元名**而不是笼统的「桥服务」—— 25 封标题写着"桥服务异常终止"，
     实际崩的是 zcode **应用**单元，照标题去查桥方向就错了。
   · `created_at_ms` 是我们的元数据，但 `/mail/send` 是**严格解码**的（实测 400
     不认识的字段）→ 发送前剥离，线格式保持干净。

判据：新增 `deploy/service-failure-notify.test.mjs`（12 条，含假网关做真实投递、
严格解码断言、补投标记的正反两向）。端到端验证：模拟"没有身份的 zcode.service
崩溃"——修复前落 `unknown-agent/` 永久死信；现在**真的投出去了**，且
`from_name=zcode`、主题 `[zcode] zcode.service 异常终止 #…`。

积压清理：27 份（dsh 2 + unknown-agent 25）全部来自 09-12 那两轮崩溃、事件已在
邮箱与 journal 里出现过，按**不再补投**处理（避免把隔夜告警灌进邮箱），
原始文件留档 /root/gotmp/failure-spool-backlog-20260913.tar.gz（600），
spool 目录留 README.md 说明。
 2026-09-13 11:06:01 +08:00
JianFeeeee
630b5bfdd7 fix(bridges): 续谈失败静默 + duplicate_relay 静默挂死（两个都是「人那边什么都收不到」） 
同一类问题在两个地方：出事的当下看不出来，表现是「信发出去了，然后再无音讯」。

## 1）pi 的续谈失败不回失败信（实测缺口）

模型侧 402（余额不足）时，**新会话**那条路会回一封「处理失败」，而**续谈**那条路
只写日志就 `throw` —— 发件人什么都收不到。邮件驱动的会话没有本地界面可以看，
没有这封信就等于静默挂死。复现条件很普通：往一条**已存在**的会话再发一封信。

修法与邻居一致：续谈失败也回失败信。但**不能复用**共用库的 `renderFailureReport`
——那段文案说「划定范围内的模型全部调用失败」并建议「调整可用模型范围」，
而续谈是**故意不降级**的（换模型＝换会话＝丢掉上下文，而上下文正是发件人指定
这条会话的原因）。照抄等于让人去调一个在这里无效的旋钮，他会去改配置，
然后发现依然失败。新增 `renderResumeFailure`：点明是续谈、附上游错误原文、
建议「确实要换模型就新建一条会话」。

**活体验证**（模型侧仍是 402，失败本身就是测试条件）：发一封进 pi 的已有会话，
5 秒内收到失败信，内容含 402 原文且不再出现「调整模型范围」。

顺带把 pi 里 2 处没 clamp 的 relay_key 收敛（上一轮审计只看了权限键）。

## 2）duplicate_relay：只有 zcode 认，另三桥会等一个永远不会来的决策

网关对重复的 relay_key 回 **HTTP 200 `{status:"duplicate_relay"}` 并提前返回**：
不建请求、不发邮件、**永远不会有人来决策**。zcode 桥认它并当场失败，而
pi/opencode/dsh 把它当成功，接着等 `permission_decision` 事件 —— pi 那句
`await new Promise(...)` 连超时都没有。这是 zcode 上一轮那个缺陷的同类，
只是发生在另三个桥上。

- `lib/relay-key.js`（**共用**，四处逐字节同源）新增 `isDuplicateRelay` /
  `DUPLICATE_RELAY_STATUS`：它长得像成功（200），所以必须单独认；对「发信」
  那一侧重复就该当成功（幂等），但对「等一个决定」那一侧它与故障后果相同。
- pi / opencode / dsh 三桥在权限转发处接上判据并**当场拒绝**
  （各自用自己的拒绝形状：`block: true` / `output.status = "deny"` / `'rejected'`）。
- zcode 里那份本地实现收敛到共用库（同一判据不该有两个定义）。

## 3）新增接线断言（带判据自检）

`test/permission-forward-wiring.test.mjs`（pi/opencode/dsh 三份同一内容）：
纯函数测试对这类缺口天生无能为力（函数是对的，只是没人调用它），所以它读源码
验形态，钉住「判据在、落在权限转发这条路上、给出本桥形状的拒绝」。

三条自检都在写的过程中抓到了我自己的错：
- 第一次 `ROOT` 算错 → 过滤后 0 个桥、循环全不跑而「全绿」→ 加了
  「找不到装着各桥的目录就判红」；
- 顺序判据写成「在文件里最早的 await 之前」，量到了别处的等待 → 三桥全红，
  改成「必须在上报之后」；
- dsh 是**两段式**（`.then` 里抛、`catch` 的 `duplicateRelay` 分支里拒），
  第一版抽取套错了分支 → 永远找不到 `return 'rejected'`。
扰动验证：把 pi 的判据禁用后该条变红，还原即绿（改动前后都核对了字节数）。

而 dsh 那条也暴露了：我把返回形状写成了 opencode 的 `{status:'deny'}`，
**`tsc` 没报错**（返回类型是宽联合），只有对着邻居读才发现 DSH 要的是
`'rejected'` 字符串 + `noteDenial`。

## 4）部署脚本：zcode 分支现在会重启驱动

`redeploy-plugin.sh` 的 zcode 分支只切软链（宿主是 ZCode 应用，不能重启它），
但**驱动是我们自己的 unit** —— 不重启它，进程里跑的还是切换前的代码。
这个由刚写的 `check-deploy-drift.mjs` 当场抓到（它比进程启动时刻与软链切换时刻），
而当时所有其它检查都是绿的。已补上重启并验证。

## 复查

四桥全量 413 / 321 / 370 / 380 全绿；共用库四方同源；部署漂移四项全通过；
四桥真发真收冒烟（dsh/opencode/zcode 正常回信；pi 因模型侧 402 回失败信 ——
这正是上面第 1 条要修的路径）。

另：写这段时踩到一个自伤 —— 用 `npx asar extract-file <asar> dist/index.html`
检查包内容时，它把文件**写进了 cwd**，正好覆盖掉 Vite 的源码模板
`client/electron/index.html`（下次构建会拿被污染的模板去构建）。已还原并重建，
产物哈希与之前一致。要看 asar 内容请用 `@electron/asar` 的 API（返回 Buffer），
别用这个 CLI 子命令。
 2026-09-12 23:13:48 +08:00
JianFeeeee
b53afd4523 chore(deploy): 部署漂移检查器 —— 快照是不是还等于仓库、进程到底在跑哪份代码 
「部署脚本跑过了」不等于「线上跑的是当前代码」。三种各自独立的漂移，谁都不会
在意，直到出问题时才发现线上是几天前的行为：

  1. 仓库改了、快照没重新部署（快照是独立副本）
  2. **软链切了、进程没重启** —— `current` 只是个符号链接，切换它不会重载
     已在跑的进程，进程持有的是启动那一刻加载进内存的代码
  3. 单元/配置改了、没 daemon-reload 或没重装

`node deploy/check-deploy-drift.mjs`（`--self-check` / `--json`）把三件事变成
可判定的：逐字节比内容（**不用 diff** —— 本机 PATH 上那个是鸿蒙工具链里的，
对内容不同的文件仍返回 0）、读进程真实 argv、比进程启动时刻与软链切换时刻。

## 判据必须按宿主真实的加载方式分开写（这是踩出来的）

第一版对四个宿主用同一套判据（「单元 ExecStart 指向 current」+「进程 argv 里有
快照路径」），结果 **opencode 与 dsh 双双假红**：它们的插件由**宿主进程**加载，
argv 里永远只有宿主自己的可执行文件。永假条件在检查器里表现为「稳定的红灯」，
人会学会忽略它。

| 宿主 | 谁加载 | 从哪里读 | 切换后要重启吗 |
|---|---|---|---|
| pi / zcode | 自己的进程 | unit 的 ExecStart | 要（启动时加载） |
| dsh | dsh 宿主 | profile `link:` → `node_modules` 软链 | 要（服务启动时） |
| opencode | opencode 宿主 | `opencode.jsonc` 的 `plugin:` | 不要（会话创建时惰加载） |

## 判据自检也修了一次

第一版自检「宿主表：运行时加载的宿主必须标记需要重启」写的是
`h.restartOnSwitch !== false`，而 `undefined` 也被放过 —— 于是 pi/zcode 的
`restartOnSwitch` 缺省成 undefined、落进「惰加载」分支、判据**永真**。
现在这条判据抽成纯函数 `judgeRestart`，自检用**行为用例**盖住：
旧进程 + 启动时加载的宿主必须判红、惰加载的宿主不判红、切换后启动的一律放行、
读不到启动时刻时不据此判红、容差内不判红。

## 扰动实验（在真实对象上证明判据会红）

- 改一个仓库运行文件 → pi 的「① 运行文件与仓库一致」变红，恢复即绿 ✓
- 只把 pi 的软链 mtime 拨到刚刚（模拟「切了没重启」）→ 「④」变红并指出原因 ✓
- 把 dsh 与 opencode 的软链都拨动 → **dsh 红、opencode 绿**（惰加载该保持绿）✓
  全部拨动均已在实验后还原并复核为绿。

## 当前结论

四个宿主都在跑当前代码（pi/opencode/dsh 的快照自 11:45 起未变，其间无提交
动过它们的运行文件；zcode 是 18:57 的快照）。「三桥加载规范化」的切换本身
早已完成，缺的是这条可复跑的判据 —— 补齐了。

另外修了 `redeploy-plugin.sh` 的一个静默问题：`usage()` 按**行号范围**截取头部
注释（`sed -n '2,40p'`），我这次的注释把退出码那段挤到 40 行之后，`--help`
就少了半页。已同步范围并就地记下这个陷阱。
 2026-09-12 20:39:22 +08:00
JianFeeeee
a00cbf36fc feat(zcode): yolo + 自有工具面 + 我们自己的执行门禁（headless 真正能干活了） 
按用户裁定「yolo_own_tools」实现：平台让开（--mode yolo），它自带的一切
「能动机器」的工具被 --disallowed-tools 拿掉，执行类动作改由我们自己的
run_command / write_file 承担，而门禁就在这两个工具里 —— 逐次向发件人请示。

## 为什么必须走这条路（实测，不是推断）

MCP 工具的 needsApproval 在产物里**硬编码为 true**（与 annotations 无关），
而 build/edit 档的判定最后一条是「需要审批 → ask」；headless 没有审批客户端
可问 ⇒ **每个 MCP 工具都被拒**（连 read_inbox 都调不动）。
我们本想让平台把询问转给钩子，但 PermissionRequest 在本版本（3.10.2 / CLI 0.16.5）
**不可靠**：有时压根不注册，触发时也无条件在 ~5ms 内失败、命令从未被 spawn
（用「钩子写 marker 文件」的副作用验证）。

于是选择只剩两个：「平台问、但问不到人 → 全拒」与「平台不问、我们自己问」。
后者才既可用又可审计。代价（平台不再提供第二道防线）写进了 README 的残余风险。

## 新增

- `lib/approval.mjs`：授权往返的唯一实现（钩子与工具共用，否则必然漂移）。
  三条不可动摇的规矩：只有明确同意才放行（判据是共用库的前缀白名单，
  不是「不等于拒绝」）；永久失败（409/4xx）当场拒绝并把服务端建议带给模型；
  暂时失败看有没有本地界面 —— 判据用**调用方传的 sessionId**（单一事实来源，
  不再另读环境变量）。自己开 SSE 等决定，先建连再发请求。
- `lib/action-tools.mjs`：`run_command` / `write_file`。输出上限、超时上限、
  默认 cwd=工作区；拒绝时**抛错**（MCP 层转 isError）而不是返回「已处理」——
  opencode 上「工具失败但报成功」导致模型连试 6 次后放弃整个任务的教训。
  平台保护目录（网关数据库/插件代码/服务单元/密钥目录）**无论谁批准都不写**，
  且判定在门禁之前（不消耗人的注意力）——防的是自我强化：邮件驱动的 Agent
  可能被来信诱导去改自己的插件代码，改完下一轮就换了一套规则。
- `REVIEWED_DENYLIST`（32 项）：逐条按「不拿掉会怎样」分类。名单来自 CLI 产物里
  模型可见工具名的**权威注册表**（aIn 那个 28 项数组）+ 另一份更宽的候选集并集，
  **不采信模型自述**（基线里它用某个没点名的方式真的创建了文件）。
  最容易被漏掉的是 `js` / `mcp__node_repl__js`：它挂在 MCP 上、
  产物里自述「can run arbitrary JavaScript with full Node privileges, like Bash」。
- 提示词的能力说明（分档）：告诉模型自带工具被禁、动手要用哪两个工具、
  会被请示；并明确「被拒是业务结果，不要重试、不要绕道」。

## 修掉三个真缺陷（都是实测撞出来的）

1. **幂等键按「会话+工具」取 → 同会话第二次调用被静默吞掉**。
   网关对重复 relay_key 返回 **HTTP 200** `{status:"duplicate_relay"}` 并提前返回：
   不建请求、不发邮件、**永远不会有人来决策**。于是工具干等 → 被 MCP 调用超时
   砍掉 → 模型回报「30 秒内未获批准」。从状态码到措辞全看不出问题，归因还完全
   错了（像是人没理它）。改为**按调用唯一**（保留会话/工具前缀便于反查），
   并把 duplicate_relay 当成可读的拒绝（fail fast，不再干等）。
2. **授权窗口被 MCP 调用超时截断**。ZCode 对 MCP 工具调用有超时（默认量级 30 秒），
   而门禁要等人。已在插件清单声明 `mcpServers.agentmail.timeoutMs=600000`
   （实测生效：40 秒的命令没被砍，墙钟 50 秒通过），并让门禁**自己**把等待夹到
   timeoutMs - 余量之下（`resolveWaitMs`）——被客户端杀掉时连理由都发不出去，
   所以必须由我们自己先 settle。
3. **`--allowed-tools` 在 help 里写着但解析器不认**（`Unknown option`）。
   留着会拼出一条永远跑不起来的命令行，现在 `buildRunArgs` 直接抛错并指出
   替代方案。我在这里误判过一次：先看到「文件没创建」就以为白名单生效，
   其实进程只是没退到 usage。判据缺了「进程真的执行了」这一环。

## 自报改成如实

detectModeEnforcement 以前拿「钩子已注册」当 native 的凭据 —— yolo 下钩子
根本不会触发，那等于替一个不存在的能力背书。现在先看**我们那条链**是否就绪
（yolo + 禁用清单里真的有 Bash/js），就绪才报 native，并在理由里点明谁在把关
（实测输出：「执行类动作只能经我们自己的门禁…平台自带危险工具已禁用 32 项」）。

## 验证

- 单测 376/376（新增 47 条）。重点在反向对照：一句「拒绝/deny/空串/平台自己的
  shutdown 哨兵都不放行」之外，还验了「别人的决策不能拿来用（relay_key 配对）」、
  「超时必须真的拒绝」、「同一会话两次调用必须用不同的幂等键」、
  「重复请求要当场拒绝而不是干等」；执行工具的每条拒绝场景都配一个**文件系统断言**
  （「抛错了」不等于「副作用没发生」），保护目录还验了 `..`/`./` 绕不过去。
- 真模型端到端（`/root/e2e-zcode-gate/run.py`，13/13）：
  批 → 命令真执行（文件内容=标记）；拒 → 命令真没执行（文件不存在）
  且回信把成因说成「人拒绝」而**不是**「超时」；同会话第三次调用仍能产生新请求
  并在获批后执行。判据本身也修了两处（授权请求邮件里带标记会被误当成回信；
  备注在通过项旁边显示会误导）。
- 部署：`deploy/redeploy-plugin.sh zcode` 快照切换 + 握手自检；
  驱动单元改为跑快照（生产不跑仓库工作区），env 与清单超时的关系写进注释。
- 顺手清掉一个遗留驱动进程（跑的是仓库路径的旧代码、连着网关 SSE、会抢邮件）。

## 判据纪律（本轮又踩到、已写进代码注释）

「文件没被创建」不能区分「被拦住了」与「进程根本没跑」；
「未获批准」不能区分「人拒绝」与「窗口被截断」；
「工具报错」不能区分「命令失败」与「工具坏了」。
每一处都改成了验到**具体成因**。
 2026-09-12 19:05:54 +08:00
JianFeeeee
6a7356ebe7 fix(zcode): 软链部署下入口静默不执行 + 部署脚本支持 zcode 快照 
## 缺陷：入口判断不解析软链 → 生产形态下 main() 从不执行

`mcp/server.mjs` 与 `src/index.mjs` 都这么判断是否被直接执行：

    import.meta.url === `file://${process.argv[1]}`

而 ESM 的 `import.meta.url` 是**解析过软链的真实路径**，argv 是命令行里写的那个。
生产布局是软链（`/opt/agentmail/plugins/<name>/current` → 时间戳目录），
于是两者不等、`main()` 从不执行：**没有输出、没有报错、退出码 0**。

它是被部署脚本的后置验证抓到的：第一次从快照起 MCP 服务器时
「握手 0 个工具、stderr 一个字都没有」，而同一个文件从仓库路径跑完全正常
（仓库路径没有软链）。这类缺陷只在部署形态下出现，本地怎么试都对；
表现（静默成功）又与「功能没被调用」一模一样。

修法：新增 `lib/is-main.mjs`，**两侧都 realpath** 后比较（只归一 != 「同一文件」）。
单测含目录软链、文件软链、文件不存在（保守判否，避免被 import 时误跑一遍）。

## 部署脚本：引入 HOST 概念，四个插件一条部署路径

pi/opencode/dsh 的宿主是 systemd 单元，zcode 的宿主是 ZCode 应用本身 ——
没有我们的单元可重启。于是：

- `HOST=systemd`：重启单元 + 看网关库里有没有新心跳（原有判据）
- `HOST=zcode`：**从快照起一次 MCP 服务器并走完握手**，这与 ZCode 加载插件
  走的是同一份入口代码；另查 `plugins list` 报告的路径是不是 current

后置验证带**判据自检**：握手函数对坏路径必须返回 0，否则判据本身失效就拒绝通过。
计数用 `grep -o | wc -l` 而不是 `grep -c` —— 每条响应只占一行，tools/list 的
11 个工具名全在同一行，用 -c 会得到 2，把好快照判失败（实测踩过）。

## 生产已切到快照

`/opt/agentmail/plugins/zcode-mail-bridge/current → 20260912-150547`，
`~/.zcode/cli/config.json` 的 `plugins.dirs` 已指向 current，
`zcode plugins list` 报的路径就是快照路径。仓库不再是生产代码。

验证：单测 325/325；快照握手 12 个 name 字段；官方 __zcode-plugin-host 从快照
启动正常；钩子从快照跑通 409 → block；坏路径能被握手判据发现（反向对照）。
 2026-09-12 15:06:49 +08:00
JianFeeeee
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
JianFeeeee
4b129b5f49 chore(deploy): 同源清单纳入 ZCode 授权桥用到的 4 个共用模块 
permission-mode / relay-key / permission-grants / sse-client 的
实现与测试一并同步 —— 档位语义与决策判定若分叉，「同意」在 ZCode 上
会悄悄变成另一种意思。
 2026-09-12 14:10:44 +08:00
JianFeeeee
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
JianFeeeee
9204f019a1 fix(deploy): 故障告警按 invocation 分会话 —— 崩溃循环时告警不再被护栏挡下 
# 问题（实测）

服务反复崩溃时，故障告警**送不出去**。

链路：告警邮件带 `relay:"summary"`（走免预算通道），而服务端按
`AutoAliasFor(收件人, 主题)` 派生会话别名 —— **主题相同即同一条会话**。于是崩溃
循环下多封告警全落进同一条会话，而网关对会话内**连续**的中继邮件有
`maxRelayHops=5` 的硬上限（防两个 Agent 互相唤醒的正当护栏）→ 第 6 封起返回 403：

    POST /api/v1/mail/send ... - 403 245B        （网关 NRestarts=0，一直在正常服务）

报告只能落 spool，等下次 ExecStartPost `--flush` 才补投。实测 dsh 崩溃循环
（我自己的部署缺陷所致）时的六条告警全部 spooled —— 而**服务反复崩溃正是最需要
告警送达的时刻**。

# 修法

主题带上本次启动的 `INVOCATION_ID` 短号：`[dsh] 桥服务异常终止 #5ce6a845`。
主题变了，别名与会话随之分开，每次崩溃各自可投递。

**护栏不削弱**：它针对的是 agent↔agent 互相唤醒，不是同一个人收多条故障通知。
副作用是崩溃循环产生多条会话而非一条线程 —— 对"服务在崩"这件事，分开计数比合并成
一条更容易发现问题。

`INVOCATION_ID` 缺失时退回 `Date.now()+randomUUID()` 的哈希：宁可每次不同，
也不能因为拿不到标识而退回"主题相同 → 告警又被挡下"。

# 验证（三条，含两个反向对照）

  不同 invocation      → 主题各不相同（每次崩溃各自成会话）
  无 invocation（兜底） → 每次仍各不相同（不会退回同主题）
  同一 invocation 重报 → 主题相同（一次崩溃仍是一条会话，不刷屏）

注：第二次验证第一次跑时"失败"，是因为**我的测试假设错了** —— 父环境里本来就继承了
`INVOCATION_ID`，两次跑用的是同一个 id。用 `env -u INVOCATION_ID` 才真正走到兜底分支。
 2026-09-12 11:56:48 +08:00
JianFeeeee
c9209e4adc fix(deploy): 失败通知不再把所有失败都说成「Gateway 不可达」 
# 误导的来源

`reportFailure` 只在 `result.sent` 上分叉，而 sent 为假同时覆盖「fetch 抛」「HTTP 4xx/5xx」，
于是两种情况都打印同一句话。

# 实测代价

切换插件时 dsh 进了崩溃循环（我自己的部署缺陷所致），通知脚本连打六条
「Gateway 不可达」并写进 spool —— 而网关**一直在正常服务**（NRestarts=0），
日志里真实响应是 **HTTP 403**：

    POST http://127.0.0.1:8180/api/v1/mail/send ... - 403 245B

403 的原因是同一会话连续中继邮件撞上防「两个 Agent 互相唤醒」的跳数上限
（`maxRelayHops=5`）：告警邮件的会话别名由主题派生，崩溃循环下六封落进同一条会话。

一句话把人送去查网络，而问题在策略层 —— **故障通知本身给出误导性诊断，
是「静默失败」的另一种形态**。

# 修法

新增 `describeSendError`：`Gateway HTTP <status>: <body>` 归类为「网关可达，但返回
HTTP xxx（附响应体）」；只有 fetch 本身失败 / AbortError 才说「不可达」/「超时」。

双向验证（真实走代码路径，都不实际发信）：
  网关指向关闭端口     → 「网关不可达：fetch failed」
  真网关 + 坏密钥      → 「网关可达，但返回 HTTP 401：{"error":"密钥无效"}」
 2026-09-12 11:52:52 +08:00
JianFeeeee
cbe5ef5cec fix(deploy): 快照改整包复制 + 存活判据改看网关心跳 —— 修两个会毁掉生产的缺陷 
切换三个桥时这两个缺陷都真的触发了，记下来避免重犯。

# 缺陷一：白名单拷贝漏文件 → 服务直接起不来

第一版 staging 用白名单：`package.json lib src index.js dist`，漏掉了 dsh 的
`cordis.patch.yml`（dsh 读它做 overlay 配置）。后果不是「少个文件」而是**服务崩溃循环**：

    Error: dsh: failed to read overlay .../dsh-mail-bridge/cordis.patch.yml: ENOENT

白名单的失败模式天生如此：**默认不带**，漏一个就等启动时炸，而那时旧版本已经被换掉。
改为整包复制 + 剔除明确不需要的（`test/`、`.git`、`node_modules/.cache`、`*.log`）。

# 缺陷二：存活判据写成了某一个平台特有的措辞

第一版后置验证 grep 日志里的「已接入」。那句话**只有 pi 与 opencode 会打印**，
dsh 启动时只输出 `dsh web: http://127.0.0.1:3080` —— 于是**一次成功的 dsh 部署
被判成失败**，脚本按设计回滚……回滚到了缺 cordis.patch.yml 的坏快照，
把 dsh 推进崩溃循环。

改为查网关库（平台无关，且是真的端到端）：

    SELECT count(*) FROM agents WHERE agent_name='$PLUGIN' AND last_seen > '$RESTART_AT'

**时刻必须用 UTC**：`agents.last_seen` 是 UTC（CURRENT_TIMESTAMP 语义），
而 `date` 默认给本地时间 —— 拿 11:44 去比 03:44 会永远为假，于是每次部署都被判成
「桥没连上」并回滚，**门禁主动破坏生产**。已用 `date -u`。

判据双向验证过：以「3 分钟前」为重启时刻 → 命中 1；以未来时刻 → 命中 0。

# 本次切换结果

  pi       /opt/agentmail/plugins/pi-mail-bridge/current/src/index.mjs
  opencode /opt/agentmail/plugins/opencode-mail-bridge/current/index.js
  dsh      /opt/agentmail/plugins/dsh-mail-bridge/current/dist/index.js

三处配置已迁移（备份在 /root/config-backups/pre-snapshot-20260912-113826/）：
pi 的 unit、opencode.jsonc 的 plugin 项、dsh profile 的 link:（含 pnpm install 重建软链）。

验证：三桥进程**打开仓库文件数均为 0**；快照与仓库文件 inode 不同（独立副本）；
四个 Agent 心跳新鲜；dsh 读 cordis.patch.yml 走的就是该软链（坏快照时它起不来，
好快照时它 active —— 这条是最硬的证据）。
 2026-09-12 11:47:32 +08:00
JianFeeeee
0549975555 feat(deploy): 插件规范化部署 —— 生产跑仓库外快照，可回滚 
# 问题（实测的加载形态）

    pi        systemd: node /home/program/agentmail/plugins/pi-mail-bridge/src/index.mjs
    opencode  opencode.jsonc: "file:///home/program/agentmail/plugins/opencode-mail-bridge"
    dsh       profiles/web/package.json: "dsh-mail-bridge": "link:/home/program/.../dsh-mail-bridge"

三个桥跑的都是**仓库工作区**。于是：一次编辑 + 重启就是上线（没有构建、没有评审、
没有版本）；**没有回滚目标**（网关有 `.bak-<时间戳>`，三个桥一个都没有）；
`git checkout` / `git stash` / 半成品编辑会静默改变线上行为；仓库同时兼作构建目录
（`dist/`、`node_modules/` 都在里面）。

对照：homeagent 插件本来就是这个规范形态（跑 `/home/newqqagent/plugins/
homeagent-mail-bridge/plugin.bin` 部署副本）—— 所以这里不是发明新办法，
而是把已有的那个形态推广到三个 JS 桥。

# 本提交只交付工具与门禁，**未切换生产**

`deploy/redeploy-plugin.sh <pi|opencode|dsh> [--stage-only]`：

  1 前置断言 → 2 staging（仓库外）→ 3 门禁 → 4 原子切换 `ln -sfn <ts> current`
  → 5 重启 → 6 后置验证 → 任一步失败即切回 `.prev` 并重启

后置验证不只看 `systemctl is-active`：桥可能进程活着却没连上 Gateway
（密钥失效、Gateway 未起、依赖在惰加载时才暴露），所以**必须以日志出现
「已接入」为准**，45 秒轮询。

需要编译的插件（dsh）**产出到 staging**，不写仓库的 `dist/`：先在仓库构建再拷贝
会有两个问题 —— 失败的构建也会 emit（tsc 默认 `noEmitOnError=false`）导致仓库产物
被半成品覆盖；以及生产产物与工作区之间多一条看不见的耦合。

# 依赖门禁：不能用 require.resolve

`deploy/check-plugin-snapshot.mjs` 从入口递归收集静态 import/export/动态
import/require 的说明符并逐个解析。

**判据用 ESM 而非 CJS 解析**——这是实测教训：`@earendil-works/pi-coding-agent`
的 `exports` 只声明 `"import"`，`require.resolve` 抛 ERR_PACKAGE_PATH_NOT_EXPORTED，
而插件是 `import` 它的、实际毫无问题。用错 API 会让门禁**报假缺陷**，
而假缺陷比不检查更糟（会让人去修一个没坏的东西）。

也不能只比对 `package.json` 的 dependencies：pi 的 dependencies 是 `{}`，
而它 import 了 `@earendil-works/pi-coding-agent` —— 声明是假的，只查声明等于空跑。

# 已验证（干跑，未切换、未重启）

  pi       20/20 说明符可解析          opencode 23/23          dsh 26/26
  dsh 经 tsc 构建到 staging 后通过

反向验证：拿掉一个依赖 → 门禁 rc=1 并点名该说明符（不是空转）。
 2026-09-12 11:36:25 +08:00
JianFeeeee
b374ce1f20 fix(plugins): 附件 id 归一 —— 修 opencode「做完全部活却发不出附件」 
# 现象（全功能演练抓到，根因来自 opencode 自己的内部记录）

opencode 把四个步骤全做完了（2× download_attachment、read 读到内容、
upload_attachment 成功），却在最后一步卡死：`send_mail` 连续 **6 次**失败，
然后放弃整个任务，自述为「attachment_ids 参数有框架级序列化 bug」。

真实形状（从 opencode 的 part 表里取出的原始输入）：

    input.attachment_ids = "[\"10e73e9f-c2a9-4226-bdb5-34ef1b340eb8\"]"   ← 字符串
    error: 字段 "attachment_ids" 类型不对：期望 string 数组，收到 string

模型把数组写成了 **JSON 字符串**，桥原样转发，服务端的严格解码器按契约拒收。

# 修在哪一层

**不在服务端放宽。** 那个「严格」是刻意的，挡的是字段名拼错、结构写错这类真
错误 —— 松开之后真 bug 会被静默接受（同一封邮件少几个附件，HTTP 仍是 200）。

**在桥这一层收。** 桥是适配器：模型侧的形状天生不可靠，而适配器的职责就是把
不可靠的输入归一成契约要求的形状。对模型宽容、对服务端严格 —— 这与
homeagent 那个 Go 插件里的 `stringList` 是同一个判断（那边注释写着「也接受
单个字符串……拒绝它只会换来一次重试，而意图毫无歧义」）。

接受的形状：数组 / JSON 数组字符串 / 单个 id / 逗号或空白分隔 / 混进 null
与数字时丢掉坏的保留好的。空串与 null 一并丢掉，与服务端
`parseAttachmentIDs` 保持一致。

# 三桥同源

新增共用模块 `lib/attachment-ids.js` + 同名测试，已加入
`deploy/check-shared-libs.sh` 的两个清单（实现与测试都必须逐字节相同 ——
只同步实现不同步测试，等于允许一侧偷偷放宽约定）。
三份 md5 一致，检查脚本通过。

# 测试

`test/attachment-ids.test.mjs` 17 条，三桥各一份。含**反向对照**：把 JSON 字符串
分支去掉后必须变红（实测 3 条失败）—— 否则这条判据就是空转，事故会复发。

全量：pi 401 / dsh 361 / opencode 312，0 失败。
 2026-09-12 11:20:13 +08:00
JianFeeeee
19a3161ee4 feat(pi): 交互式 pi 会话接入邮件工具（send_mail/read_inbox 等 10 个） 
问题（⑧）：守护进程用 noExtensions:true 起会话，它的邮件工具只给模型在邮件
会话里用；人在 TUI 里敲的 pi 拿不到。结果是平台的建设者自己收不到邮件 ——
一个「邮件驱动」的平台，维护者只能绕到 curl + 密钥直连 Gateway 才能看收件箱。

新增 plugins/pi-mail-bridge/extension/index.ts：把同一套工具（createMailTools）
注册到交互式会话。两者是同一条 AgentMail 身份（agent pi）的两个入口，与 DSH 的
「TUI + 邮箱是同一个 Agent」一致。

密钥解析顺序（交互式 pi 的环境里没有 AGENTMAIL_*）：
  1. 进程环境
  2. AGENTMAIL_ENV_FILE（默认 /etc/agentmail/pi.env）—— 与守护进程同一把密钥，
     因此身份一致
  3. AGENTMAIL_CONFIG_DIR/agent.key 或 ~/.agentmail/agent.key
     （兼容 key 与 key_token 两种字段名；实测本机文件用的是 key_token，
      只认 key 会静默读不到）
拿不到密钥时不注册任何工具并明确告知 —— 挂一组永远 401 的工具比没有更糟。

不注册 connect_to_server：它会重写 Gateway 坐标并重新登记密钥，而交互式会话与
守护进程共用同一身份，一次 TUI 对话不该改到守护进程的配置。

为什么不会重复注册（读 SDK 实现确认，并用探针实测）：
  resource-loader.js 里 noExtensions 为真时只用 cliEnabledExtensions，
  settings.json 的 extensions 数组被排除 —— 即 noExtensions:true 只加载
  命令行 -e 传入的扩展。
  探针：noExtensions=true → 扩展数=0；false → 16 个且含 pi-mail-bridge。

deploy/install.sh 增加幂等的扩展注册步骤（写入 settings.json 的 extensions）。

验证：headless pi 实际调用 read_inbox 返回真实邮件主题；工具清单含
send_mail/read_inbox/read_mail/forward_mail/upload_attachment/download_attachment/
suggest_address/list_contacts/session_participants/read_thread（10 个），
connect_to_server 按设计排除。
 2026-09-11 11:32:47 +08:00
JianFeeeee
f91efd2d8d feat(question): DSH ask_user_question 桥接 + 前端问答面板 + 待办字段全路径透出 
问题（P0）：DSH 有两个独立的人机交互 seam —— approval/request（危险工具审批）
与 ask_user_question → ctx.userQuestions（模型主动提问）。原来只桥接了前者。
邮件驱动的会话没有本地 UI，而 ask() 的 provider 是 DSH host 注册的本地 UI 实现，
于是在那里等人点选永久等不到，那一轮工具调用**静默挂死**。

修法（不抢注全局 provider —— registerProvider 只允许一个活动实例，抢注会让
平台自己的界面失效）：在 tools/execute around-dispatch 里只对**邮件驱动**的
会话接管 ask_user_question，其余原样 next()。失败一律当场报错而不是 next()：
下一个 answerer 是本地 UI，邮件会话没有兜底 UI，放过去就是挂死。

- lib/user-question.js（三桥逐字节同源，14 例测试）：DSH questions[] ↔ AgentMail
  单问题询问邮件的双向映射。多问题时把选项并集摊平、按 label 归属分配回各问题
  （label 认不出来就不猜测放行）；无选项题走自由文本 custom。
- Gateway：kind=question 且无选项时**不再**回落「同意/拒绝」（那会让自由文本
  问题变成两个毫无意义的按钮）；主题按类型区分「权限请求 / 需要回答」；
  推送 payload 带上 permission_kind / multi_select / options。
- mails.permission_kind / permission_multi_select 此前只存在于结构体与写入路径，
  五个读路径的 SELECT/Scan 都没带 —— 前端永远拿到空串，把提问渲染成批准/拒绝。
  container 修正五处并加 repo 测试（含反向验证：删掉任一处字段，测试即失败）。
- 前端 PermissionPanel：question 走「勾选 + 自由文本」，多选/单选、空回答禁止提交；
  approval 路径不变（回归测试覆盖）。

测试：opencode 316 / dsh 349 / pi 405 / 前端 185 / Go 全量 全绿。
 2026-09-11 10:44:18 +08:00
JianFeeeee
c401eb2da2 fix(bridges): SSE 跨分片保帧 + Last-Event-ID；pi worker 有界重投；systemd 故障上报；清理误提交二进制 
三个平台桥原本各自手写 SSE 解析，有两个共同的静默丢事件缺陷：
  1. evt/data 是每次 read() 的局部变量 —— TCP 把一帧
     'event: x\ndata: {...}\n\n' 切在换行处时，前半段的 event 名被丢掉、
     后半段只剩 data，整帧静默丢弃。表现为「新邮件偶尔收不到」
     「权限决策点了没反应」，日志里一个字都没有。
  2. 重连不带 Last-Event-ID —— 断线期间的事件留在服务端 per-agent 环形
     缓冲里永远回放不出来（pi 与 homeagent 已正确使用，DSH/opencode 没有）。

修法：抽出共用 lib/sse-client.js（三桥逐字节同源，check-shared-libs 校验），
把「跨 chunk 保帧状态」与「Last-Event-ID 断点续传」写对一次。pi 桥的
gateway.mjs 也改为复用同一实现（保留 reconfigure 时清断点的语义）。

pi worker 丢任务：worker 未回报 done 就退出（SIGKILL/OOM/崩溃）时，
主进程原来只记一行日志就 pump() —— 那封邮件永远没有回音。改为按
1s/2s 退避有界重投（默认 3 次），到上限记「放弃」并可观测。

systemd 故障上报：四个宿主服务接入 service-failure-notify.mjs 的
ExecStopPost/--report 与 ExecStartPost/--flush。进程内 uncaughtException
捕获不了 SIGKILL/OOM，只能由 systemd 统一覆盖。正常 stop/restart 不发信。

仓库卫生：server/server（24MB 构建产物，f9d757b 误提交）移出版本库。

测试：opencode 302 / dsh 335 / pi 391 全绿（新增 12 例 SSE 帧解析 +
2 例 worker 重投）；Go 全量通过；四平台重启后在线且无错误。
 2026-09-11 10:27:41 +08:00
JianFeeeee
f9d757b5e5 chore: directory migration - gateway→server, web→client/electron 2026-09-08 19:16:35 +08:00
JianFeeeee
79c4171c9d feat: L0 线协议冻结 + 附件链路修复 + 人/Agent 区分 
L0 核心：
- 严格解码 Decode(DisallowUnknownFields) 全覆盖 29 个 DecodeBody 调用点
- DecodeLenient 心跳专用：容忍新字段但回报 unknown_fields
- 400 消息列出本端点接受的全部字段（jsonFieldNames 反射 tag）
- 日历 status 校验（create 补字段 + update 拦非法值）
- 新增 strictdecode_test.go 10 例 + blob/list_test.go 6 例

A-4 附件挂载回滚：checkAttachable 在 CreateMail 前校验，失败按
解挂→释放 relay→删邮件→退预算回滚，幽灵邮件这条路堵住了

A-5 反向 GC：blob.Store.List() 枚举磁盘（跳 .upload-*），
SweepUnreferencedBlobs 按 attachments + calendar_attachments 反查，
48h 年龄下限兜上传窗口。已接进每小时 sweep 循环

C 人/Agent 区分：四个读路径 + threadCols 补 from_human / to_human
（EXISTS users 判定），models.Mail 加 ToHuman。前端判据从
workspace 启发式改成显式布尔，mailCounterpart/sessionCounterpart
从 session_workspace 取 path（修 dsh@dsh 拼接 bug）

契约文档：SSE new_mail 补 4 字段（in_reply_to/from_human/
permission_mode/permission_enforcement），B-5 加 B-5.6
（Agent→Agent 不转发），B-3.4 MUST 改条件式，心跳补 mode_enforcement
+ unknown_fields，demo 死链修复 + from_human 检查
验收清单加 Agent→Agent 负向对照项
 2026-09-06 15:18:06 +08:00
JianFeeeee
a101c2fada 停用/恢复文案说清密钥不会自动回来 + 原子部署脚本 
## 起因

本会话踩到一次：浏览器测试点了 opencode 的「停用」按钮验证确认流程，
停用连带撤销全部密钥。插件从此拿着已撤销的密钥重试了 18 小时
（gateway 日志 2690 次 401），而 UI 只说了「已停用」。

恢复时同样没提示「密钥不会自动回来」，点完恢复以为就完事了。

## 文案

后端 `AdminSetAgentStatus`：
- 停用 detail 补一句「停用期间别人发信给它会收到 409」
- 恢复 detail 改成「停用时撤销的密钥不会自动回来 —— 必须在密钥面板
  重新签发一把并写进该插件的配置，否则它会一直拿旧密钥重试并被拒（401）」
- 恢复响应加 `needs_new_key: true` 字段，前端可据此做更强的提示

前端 QuotaPanel：恢复成功的 notice 不再是「已恢复」四个字，
把重新签发这一步说全；面板说明与按钮 title 同步。

## AdminDeleteAgent 两处修正

- 硬编码 `name == "jianf"` 改成按 `repo.IsHumanUser` 判定 —— 换管理员时
  硬编码会失效，而人类账号不该走 Agent 删除端点
- detail 原来说「日历事件已保留」，实际 `DeleteAgent` 把 active 事件置为
  cancelled（留着会由调度器一直触发，而发信人已不存在）。文案改成实际行为

## deploy/redeploy-gateway.sh（新）

日常改后端不必重跑 install.sh（它重装 npm 依赖、重写 systemd 单元、
重新生成 env）。这个脚本做手工 `stop → cp → start` 不做的四件事：

- `sqlite3 .backup` 备份数据库 + 立即 `PRAGMA integrity_check` 复核。
  不用 cp：WAL 模式下 cp 会拿到主库与 -wal 不同步的快照
- `install -m 0755` 原子替换二进制。install 本质是 rename，要么完整
  换掉要么原样不动；cp 是就地写入，中途失败会留下半截文件且旧的已被覆盖
- 旧二进制留档并打印可直接粘贴的回滚命令
- 后置验证清单：服务 active / /health 可达 / 近 2 分钟无 panic /
  SSE 重连计数。任一项不过**自动回滚**，不「先上着再修」

`--dry-run` 只打印动作，`--skip-tests` 急救用，`--skip-web` 跳过前端同步。
纪律来自 git-release-discipline skill 第五章。

## 验证

- 脚本 dry-run + 真实跑通一次：备份 integrity_check=ok、原子替换、
  9 个 SSE 客户端重连、验证四项全绿
- 停用/恢复文案线上实测；`DELETE /admin/agents/jianf` → 403「是人类用户」
- 端到端：jianf → opencode「部署脚本验收」→ 回信「部署验收 OK」
- 全量测试：gateway 全包 / web 176 / opencode 217 / pi 288 / dsh 241 /
  homeagent go ok；三方共用模块同源检查通过
 2026-09-05 10:10:13 +08:00
JianFeeeee
784192d8c4 Agent→Agent 不自动转发 + 提示词区分新活/回复/补投 
## 设计规则：Agent 之间不自动转发

自动转发存在的理由是「人不该等模型记得调 send_mail」—— 收件方是人时这是
纯收益。**收件方是另一个 Agent 时这个理由不成立，而且有害**：双方的插件都
会自动回一封，于是两个模型都以为「我只要把话说完就行」，实际在持续互相唤醒。
生产实测 pi 与 dsh 客套 6 轮直到撞上连续 relay 跳数上限。

规则现在写死在共用模块 `lib/relay-policy.js`（三平台逐字节相同）：
- `autoRelayDecision` — 插件该不该替模型开口
- `replyInstruction` — 提示词怎么跟模型说（人类 vs Agent 各一套措辞）
- `inboundHeadline` — 进来的是新活、回复、还是补投

`from_human` 缺失时保守按 Agent 处理：宁可让模型多调一次 send_mail，
也不能承诺一个不会发生的自动回信让发件方白等。

## Gateway 侧：`in_reply_to` + `from_human`

- `notify.Mail` 新增 `ParentMailID`（非空 = 这是对收件方某封信的回复）
- `notify.Mail` 新增 `FromHuman`（走 `repo.IsHumanUser`）
- SSE payload 里叫 `in_reply_to` / `from_human`
- 四个调用点全部传入：handler/mail（转发后产出的邮件，parentMailID 从
  resolveTarget 取）、handler/me（同理）、handler/forward（传空串，
  因为对收件方而言那封原邮件不在它的线索里）、scheduler/calendar（传空串）
- `ListInbox` 的 SELECT 加 `EXISTS (SELECT 1 FROM users u WHERE u.username = m.from_name)`
  → `models.Mail.FromHuman`，让补拉路径也有这个信号

## 提示词分流

三种处境各一套标题：
- 新活（人类）：「你收到一封新邮件」+ 「回信不用你自己发：…」
- 新活（Agent）：「你收到一封新邮件（对方是一个 Agent）」+ 「插件不会替你
  回信。需要回复时你必须自己调 send_mail…请先判断是否真的需要回复」
- 回复到了：「你上一封信的回复到了。**这不是新任务**。」
- 补投：在标题里说明「离线期间积压」

## homeagent 特殊处理

Go 插件不能直接 `import('../lib/relay-policy.js')`，因此新增 `relay_policy.go`
（Go 对应物）+ `relay_policy_test.go`（11 例，逐条对齐 Node 侧判据）。
`sseLoop` / `catchUp` 两条路径都接上。

## `mailEvent` 命名类型

homeagent 的 SSE 事件解析 / handleNewMail / handlePermissionDecision 三处
原来各写一遍匿名 struct（字段列表几乎相同），加 `from_human` / `in_reply_to`
时漏改一处 → 编译报错但错误信息是两串几乎相同的字段列表，极难定位。
提成 `mailEvent` 命名类型：一处改、三处跟着走。

## 测试

- `lib/relay-policy.test.mjs`（Node）16 例：含「replyInstruction 与
  autoRelayDecision 不得互相矛盾」「Agent 来信的标题要点名且回复要明确反对」
- `relay_policy_test.go`（Go）11 例：逐条对齐 Node 侧
- `turn.test.mjs` +3 例：from_human 缺失时按 Agent 处理 / Agent 来信时改口 /
  回复到了说「不是新任务」；删掉两条旧的「必定自动转发」断言
- 共用脚本 `check-shared-libs.sh` +1 个文件（relay-policy）
- pi 288 / dsh 241 / opencode 217 / homeagent 14 / gateway 8 包全绿
 2026-09-04 23:52:52 +08:00
JianFeeeee
255c799a40 feat(adopt): 邮件可投进平台上已存在的会话（TUI 与邮箱同一入口） 
人在平台界面（pi TUI / opencode / DSH GUI）里开的会话，此前无法被邮件投进去。
补全早就把它们列为候选（agent_platform_sessions 镜像，插件心跳上报），
但投递侧的 FindNamedSessionFor 只查 sessions 表 —— 选中后只能得到 404。
候选列表在承诺一件做不到的事。

TUI 与邮箱是同一个 Agent 的两个入口，不是两套隔离的世界。

## Gateway

sessions 表加 platform_id 列 + 部分索引。resolveTarget 的 SessionNamed 分支
本侧查不到时再查镜像，命中则「接管」：本侧建一条会话并绑定 platform_id，
之后每次投递都在 SSE 事件里带 platform_session_id。

- FindPlatformSession(agent, slug, workspace) 查镜像
- FindSessionByPlatformID 防重复接管（一条平台会话只能被接管一次，
  否则同一条对话在邮箱里裂成多条互不相干的线索）
- AdoptPlatformSession 建会话 + 绑定 + 别名复用平台 slug（撞名自动加后缀）
- PlatformIDOf 供 notifyRecipients 读

三处语义决定：
- workspace 以平台会话为准（它的 cwd 创建时就定了）。地址 path 位不同则不命中，
  否则邮件会投进另一个项目的会话
- 主题优先用平台侧标题（它代表整条对话在谈什么，也是补全里显示的）
- 接管计入 AllowNewSession 速率限制 —— 镜像里可能有几百条 slug，
  不计的话它是绕过限流的后门

## 插件

字段解析与失败话术抽成共用模块 lib/adopt.js（三方逐字节相同 + 进同源校验）：
字段名各写一遍时少个下划线就静默退化成「每封邮件新开一条」，而那个错误不抛异常。

- opencode：session.get 确认存在 → 照常 promptAsync（服务端持有会话，单一写者）
- DSH：复用 startAgent 的 resume 分支，会话 id 换成平台自己那个；
  界面上正开着时直接 followup（两个 handle 会各自写日志，replay 过不去）
- pi：SessionManager.open(file) → 跑一轮 → dispose，不放进长期缓存

pi 必须短暂持有：SDK 无任何锁机制（flock/lockfile 命中 0），活着的
SessionManager 不 watch 文件 —— 外部追加的行看不见，算出的 parentId 指向
对方不知道的 entry，会话树分叉。写入是纯 append 所以文件不会坏。
配套三处：isStreaming 时不释放（否则杀掉排队中的下一封）、兜底计时器
（轮次超时 ×2，unref）、接管会话跳过命名同步。

最后一条是实测撞出来的：别名撞名时 Gateway 加后缀，而定稿别名又回写进 pi
会话文件 → 下次心跳上报的 slug 变成带后缀那个，人从补全里选的名字凭空消失。
opencode/DSH 无此环（它们的 slug 只读不写）。

接管后必须加入 mailDriven 集合，否则邮件投进去了却永远没有回音。

## 迁移顺序

idx_sessions_platform 不能写在 init_sqlite.sql 里：那个脚本在
addMissingColumns 之前执行，而已部署的库里 sessions 表已存在
（CREATE TABLE IF NOT EXISTS 不补列）→ 索引建在不存在的列上，
整个迁移中断、服务起不来（生产实测）。依赖补出来的列的索引一律放
migrate.go 的 sqliteAddIndexes。PG 侧用 ALTER TABLE ADD COLUMN IF NOT EXISTS。

## 生产验证

- pi × 2（agent-only-chain / mail-probe-alias）、opencode（glowing-moon）、
  dsh（查看工程与插件适配指南）四条链路接管成功
- dsh 那次回信准确说出了界面上聊过的内容 → 上下文确实装回来了
- 第二封复用同一条本侧会话，平台侧无新增改名条目
- 回归：opencode 普通 .new + 别名续谈 + used_rounds=0（免配额通道未受影响）

## 其他

pi-mail-bridge 补 systemd 单元（此前是 setsid 裸进程，重启机器不会拉起）：
陈锁清理 ExecStartPre、MemoryMax=4G、TimeoutStopSec=10。
配置目录必须与 opencode 分开（共用会让后起的读到对方密钥或撞单实例锁）。

PLUGIN-CONTRACT.md 加 B-3.7 / B-3.8 + new_mail 字段表 + 检查清单验收项。

测试：repo +10 例（adopt_test.go）；三插件各 +7 例（adopt.test.mjs）
 2026-09-04 11:14:44 +08:00
JianFeeeee
2996f9af9c fix(plugins): 409 时当场表态 + DSH 补投按会话串行 
**409 = 永远不会成功**（没有人类可路由）。原来三个插件都在失败时让位给
平台本地 UI —— 但邮件驱动的会话**没有 TUI**，让位之后 waterfall 跑到尾
依旧无人应答，仍是无声挂死。

HTTP 客户端必须把 err.status 与 err.body 挂到 error 上：只看 message
字符串分不出「暂时失败（502，该重试）」与「永远不会成功（409）」，
两种都会被当成前者，而前者会永久挂住会话。

三平台表态方式不同但语义统一：
- opencode: output.status = "deny" + output.reason 带服务端原文
- dsh: return 'rejected'（ApprovalOutcome 只认 allowed-once/rejected/
  cancelled，写 'denied' 不报错而是被当未知值静默失效）
- pi: return { block: true, reason }

其余失败（502 等）保持原行为，让位本地 UI。

---

**DSH 补投并发**（同一文件，故并入本次提交）

生产日志：`补投 5 封（共 16 封未读）`，9 秒后三封失败
`message "undefined" is already pending`。串行 for...of 并未真正串行 ——
awaitFirstTurn 在**首个 token** 就放行，turn 尚未结束下一封已 followup。

新增 waitForTurnEnd（等 turn/end 而非首 chunk）与 sessionLocks/locked()
按会话串行化。live-agent 路径原来直接 followup 就返回，现在也进锁。
120s 超时兜底，模型完全无响应时不会把后续邮件永久卡住。

权限场景下锁会持有到人类决策完 —— 这是正确行为：两封都需要授权时
第二封排队，比同时弹两个授权请求更合理。

顺带把 rename-proposal 纳入 check-shared-libs.sh 的同源校验。
 2026-09-03 21:10:48 +08:00
JianFeeeee
f321380fa3 fix: relay 死循环防护 + DSH 工作区注册修复 + homeagent 工具集补齐 + 三插件 connect_to_server 
## relay 死循环防护（两道防线）

### 主防线：免配额只给发往人类的 relay（handler/mail.go）

原设计：relay 走免配额通道（harness 搬运不该算模型自主发信）。
问题：收件方是另一个同样会自动转发的 Agent 时，整个回路里没有任何
一处在计数——生产上跑出过 41 封（会话 f3d824ce），间隔从 15 分钟
缩到 5 秒，且用了 37 封才烧掉 4/20 预算。

改为：repo.IsHumanUser(to.Name) 判定。Agent→Agent 的 relay 照样扣预算。

顺带修次序问题：原来是「先占幂等键再扣预算」，预算耗尽时幂等键
已被占用，加了额度也无法重发。现在预算失败会 ReleaseRelay 还回去。

### 兜底：hop_limit 列接通（repo/relayhops.go）

schema 里早有 hop_limit INT DEFAULT 5，从未有代码读它。
CountTrailingRelayHops 从最新邮件往前扫，遇到第一封非 relay
邮件即停（中间有一封自主发信或人类插话就归零）。

5 测试：空会话 / 只数 relay / 自主发信打断归零 / 达到上限 / 按会话独立

## DSH 工作区注册修复

问题：上一轮加的 workspaceRegistry.create(cwd) 用了兜底值 cwd（来自
resolveWorkspaceCwd，可能是 ~/.dsh/mail-sessions/mail-<uuid>），
而不是会话 header 里的真实 cwd。两者不一致时 attachSession 拒绝，
且 create 已先执行，每封邮件都往注册表里塞一条空的垃圾 workspace。

修复：读 handle.agent.session.header.cwd —— create 路径下是 meta.cwd，
resume 路径下是持久化 header 里那个。

## homeagent 插件：11 工具齐平 opencode

tools.go 新增：read_mail / forward_mail / suggest_address /
list_contacts / session_participants / read_thread / connect_to_server
+ handleConnectToServer（注册到 Gateway 前先用候选坐标试注册，
成功才写回 p.gwURL/p.key，失败不破坏原配置）

关键修：Plugin.name（插件名，homed 注册用）与 Plugin.agentName
（AgentMail 身份，Gateway 密钥绑定用）是两个命名空间。
它们混淆会导致 403：「该密钥已绑定到 Agent 'homeagent'，不能用于
注册 'homeagent-mail-bridge'」。现已分开，并在 systemd drop-in
里显式设 AGENTMAIL_AGENT_NAME=homeagent。

## 三插件补齐 connect_to_server

之前只有 opencode 有。后果：Gateway 换地址或密钥需要重新登记时，
opencode 里的模型能自己修好，其他平台只能干等环境变量被人改。

DSH 版：从 GatewayClient 内部调 register()，成功后写回 client.baseURL
与 client.agentKey 当场生效。

pi 版：新导出 KEY_FILE / saveLocalKey（从 gateway.mjs），connect
工具直接用。

# 测试

relayhops_test.go 5 例
opencode 172 / dsh 188 / pi 214 全绿
check-shared-libs.sh 三方同源（rename-proposal 已纳入校验）
 2026-09-03 15:01:52 +08:00
JianFeeeee
e6fd2fafdc feat: agent 邮件寻址能力全面补齐 + .new 别名替换 
## 别名替换（让 .new 邮件可寻址）

repo/autoalias.go: AutoAliasFor + EnsureSessionAlias
- .new 建完会话立刻给别名（形如 dsh-重构导入路径）
- 名字与主题都要：只用主题跨 Agent 撞名，只用名字看不出聊什么
- sanitizeAliasPart 只留 unicode.IsLetter/IsDigit，其余折 -
- 撞名追加 -2/-3，全占用退 session-<uuid前8位>
- 不复用 SyncSessionAlias：那个假定已存在且跳过 manual
- 条件写入 WHERE alias IS NULL OR ''，并发安全
- resolveTarget 的 .new 与默认会话两条路径都调

notifyRecipients 加三个字段（每个收件方拿到自己那个地址的版本）：
- session_alias / reply_address / self_address
- 别名为空时退回省略 session 位，绝不写 new

FormatAddress(name,path,session) 空 path 也必须留 @ 与 .

## Agent 侧寻址发现（五个只读端点）

handler/agent_discovery.go:
- /agent/contacts + /agent/contacts/suggest（三段式补全）
- /agent/mail/{id} + /agent/mail/{id}/thread
- /agent/sessions/{id}/participants
- 不复用人类路由：scope 不同、审计需求不同
- 一律只读：归档/改名/权限决策仍只有人能做

repo/participants.go: SessionParticipants 逐封扫 from/to/cc
- Roles 用集合、MailCount 只数发信（0=还没开口的人）
- 发件人 path 不取 from_workspace（那列存的是 Agent 名）

repo.SuggestPaths 重写：mails.to_workspace（按 MAX(created_at) 倒序）
+ agents.workspaces 并集。原只读 workspaces，官方插件传 [] 永远空

## 共用模块（三插件逐字节相同）

lib/addressing.js: formatAddress/roleOf/replyAddressFor/selfAddressFor/participantsOfMail
lib/discovery.js: renderNameSuggestions/renderPathSuggestions/renderSessionSuggestions/
                  renderParticipants/renderContacts/renderThread

lib/inbox-format.js: renderMail 新增收件人/身份/可投递地址三段
  - selfName 参数（兼容旧调用不传的情况）

check-shared-libs.sh 纳入 addressing + discovery

## 插件侧

opencode: suggest_address + list_contacts + session_participants + read_thread + read_mail
dsh: 同上 + forward_mail（此前只有 opencode 有）+ upload_attachment 改真 multipart
pi: 同上（createMailTools 加 agentName 参数）

dsh: ctx.agents.create id collision 改为 readSession 探测后 resume
dsh: 关键路径日志改 console.error（ctx.logger 不进 journalctl）

## 测试

repo: autoalias_test.go 11 + participants_test.go 7 = 18 例
plugins: addressing.test 17 + discovery.test 23 + inbox-format.test 31 = 71 例
go test ./... + npm test（opencode 155 + dsh 173 + pi 199）全绿
端到端验证：admin 发 dsh@....new 抄送 opencode@....new
  → dsh 用 session_participants 取到地址 → send_mail 给 opencode
  → 地址取自工具返回值（.crisp-planet），未手工拼写
 2026-09-03 12:09:12 +08:00
JianFeeeee
289f37f7fb docs: PLUGIN-GUIDE 重写为 PLUGIN-CONTRACT（可核对的插件规格） 
原 PLUGIN-GUIDE 是叙事式的「怎么做 + 踩过的坑」，读者要自己从散文里推断
「我到底必须做什么」。接第三个平台时这不够用 —— 尤其当照着实现的是一个代理。

改为规格式，编号可引用、强度明确标注、每条尽量给出可机械核对的判据。
旧文档的内容全部保留（迁进第八、九节），另补上原先没有的四类：

## 一、能力矩阵（新增）

回答「这个平台能不能接」。七项必需能力（C-1..C-7）加七项可选（C-8..C-14），
每项给出判据。附一个七问自检 —— 任何一问答不出来就先别写代码。

其中 C-4「轮次结束信号必须能区分成功与出错」在两次适配里都被漏掉过，
两次都造成「无效模型被判成成功」，所以单独标了出来。

## 二、行为约定（重写）

原先散在各节的要求收拢成一个状态机，按事件逐条规定：B-1 启动 / B-2 心跳 /
B-3 new_mail / B-4 permission_decision / B-5 轮次结束 / B-6 无法处理时回信 /
B-7 启动补拉 / B-8 权限询问 / B-9 关停。

## 四、降级语义（新增）

平台缺某项能力时的确切退化路径（D-1..D-7）。原文档只说了「可选」，
没说缺了之后该怎么办 —— 于是「不支持权限钩子」很容易被实现成
「提供 request_permission 工具补偿」，而那正是 I-1 反对的模式。

## 六、不变量与禁止事项（新增）

12 条 MUST NOT，每条附「违反会怎样」。这些是测试全绿、跑起来也不报错，
但行为就是错的那类问题 —— 例如拉取失败时传 [] 而非省略字段会清空服务端目录。

## 七、验收清单（新增）

八组可勾选项，每条给出具体命令：grep 自查禁止事项、sqlite3 查在线状态与
配额未被消耗、停插件发信再启动看补投日志。

## 核对过的事实

写完逐项核对了代码，不是凭记忆：
- 12 个端点全部在 main.go 里存在且方法一致
- 发信 9 个字段名与 sendMailRequest 的 json tag 一致
- 心跳响应 12 个字段名与 handler 一致
- 九个数字（30s 心跳 / 25MB 附件 / 20 次每小时 / 补投 5 封 / 快照 200 条 /
  模型上限 10 / 目录上限 300 / 降级超时 60s / inbox 默认 5）都能在代码里找到出处
- 验收清单里的六条 sqlite 查询都在生产库上跑通
- 38 个编号无重复，18 处交叉引用全部有定义

引用同步：PLAN.md、PHASE7-REMAINING.md、API.md、README.md、
install.sh、check-shared-libs.sh。
 2026-09-03 08:09:54 +08:00
JianFeeeee
9e5c557cdf feat: 跨主机 Agent 验证 + 离线邮件补投 + 400 指向具体字段 
7.8「跨主机 Agent 发现」原计划（Gateway + Registry 拆分、etcd/Consul 注册）
取消，改为验证现有协议已经够用。验证过程暴露两个真实缺陷，一并修掉。

## 为什么不做注册中心

它要解决「Gateway 怎么找到 Agent」，而这个问题在本架构里不存在：
连接方向是单向的 —— Agent 主动连 Gateway，Gateway 从不外呼。
远端 Agent 只需要一个公网 URL 加一把密钥，被叫方自己会打进来。
注册中心要解决的「被叫方在哪」根本没出现过。

同一个理由此前已经决定了平台会话同步走插件上报而不是 Gateway 拉取。

## 验证方式：一个纯标准库脚本

`deploy/remote-agent-demo.py` 在另一台主机（192.168.2.106）上跑，
不装 AgentMail 的任何代码。注册 / 心跳（带模型目录）/ SSE 长连 /
收件箱 / 标记已读 / 发信全通，Gateway 侧 status=online 且 last_seen 随心跳推进。
完整一轮往返跑通：admin 发给 remotebot@/tmp/remotebot-ws，脚本回信入库。

「协议层面已支持」的含义就是这个：跨主机不需要新组件，只需要三个环境变量。

## 缺陷一：SSE 只推连上之后的事件，没人补拉积压

写那个脚本时第一版只挂了 SSE，启动前发的邮件永远不会被处理。
查了才发现**两个正式插件也有这个洞** —— 原以为它们做了补拉，实际没有。
后果比明确的失败更难排查：邮件躺在收件箱里，而发件人以为 Agent 收到了。

新增共用模块 `lib/catchup.js`，两插件在首个成功心跳后补投一次。五条约束
都对应一种具体的坏行为：

- 只在**首个**心跳后补 —— 每轮都补会把「模型正在处理中、尚未标已读」的
  邮件重复投递
- 串行、一次最多 5 封 —— 每封都要起一轮模型，并发放出去等于对上游打 N 个
  并发请求，且最后几封要等前面全部跑完
- 与 SSE 共用 deliveredMails 去重 —— 心跳与 SSE 建连之间有个窗口，
  那期间到的邮件两条路都会到
- 按时间**正序**投（收件箱倒序返回）—— 倒着塞进去同一会话的上下文是乱的
- permission 类不补投 —— 原来的工具调用早随进程没了，没有可恢复的上下文

端到端两平台各验一次：停插件 → 发信 → 启插件 → 日志「补投 1 封离线期间的
邮件」→ 回信入库；随后在线再发一封确认只回一次。

## 缺陷二：400 只说 "Invalid JSON"，不说是哪个字段

脚本把 `workspaces` 传成字符串数组（它要 `[{name, path}]`），
得到的只是一句固定文案，只能靠翻服务端结构体才能发现。
两个官方插件都传 `workspaces: []`，所以这个洞一直没暴露；
第三方客户端没有「翻服务端源码」这个条件。

新增 `handler.DecodeBody`，22 处 `Decode` + 固定文案的调用点全部换过去：

    {"error": "字段 \"workspaces\" 类型不对：期望 object，收到 string"}
    {"error": "JSON 语法错误（第 8 字节处）"}
    {"error": "请求体为空"}

刻意不回显 encoding/json 的原文 —— 它带 Go 类型名（models.Workspace），
那是本侧的实现细节，不该出现在公开 API 的响应里。期望类型用 JSON 的说法。
截断的 JSON 走 io.ErrUnexpectedEOF 而不是 json.SyntaxError，单独一条分支，
否则会落到笼统的兜底文案里（写测试时才发现）。

## 验证

- Go：13 个新测试（decode_test.go 含「不得泄漏 Go 类型名」断言）
- 插件：两侧各 10 个补投测试，共 200 个
- 共用模块同源校验通过（catchup 已纳入 check-shared-libs.sh）
- 生产已部署
 2026-09-02 22:47:31 +08:00
JianFeeeee
89356d4a9b feat: 每平台可用模型范围 + 降级尝试 + 失败回报 
配置页为每个 Agent 平台划定「邮件场景下可用的模型」，插件按顺序逐个尝试，
全部失败把原因封装成邮件回复。目录由插件上报、管理员只做勾选 —— 手打模型名
会打错，而打错的后果要到真发邮件时才暴露成一次失败。

## 目录上报走心跳，不另设端点

模型清单会在运行中变（换 provider 配置、上游上下线、换 API key）。
只在注册时报一次的话目录会静静变陈，管理员在配置页选中一个平台其实调不到的
模型。心跳本来就是 30 秒一次的现成通道；另设一个 POST 等于给「目录是谁写的」
留两个答案，排查时要同时看两处。

心跳响应回传 `allowed_models`，因此管理员改了范围后最多一个周期生效，
不必重启插件。

与 platform_sessions 同一约定：拉不到目录时**省略字段**（保留现有目录），
传空数组会把配置页清成空白。

## 目录与选择分两张表

模型会从平台目录里消失（上游临时下线、换了 provider 配置）。合成一张带
allowed 标记的表时，整行被删就连带把管理员的选择也删了，模型回来还得重配一遍。
分开存之后「选了什么」是持久的，目录只决定「这一项现在是否可用」；
已选但不在目录里的标为 stale 显示出来 —— 不显示会让人以为自己没选过它。

## 最难的一点：模型失败不是同步抛出的

两个平台都踩了。`promptAsync()` 立即返回、`ctx.agents.create()` 不校验模型，
只包 try/catch 的话第二个模型永远不会被试到 —— 第一个无效模型会被判成成功。

必须等异步结论：
- opencode → `session.error` 事件（event 钩子在 deliverMail 之外，
  因此用 turnWatchers 表把两者接起来）
- DSH → `turn/end` 的 `reason.kind === 'error'`

DSH 还有个陷阱：**`assistant/chunk` 不能当成功信号**，它的 `finish` 子类型
也带错误 —— `{chunk:{type:'finish',reason:{kind:'error',failure:{code:'NO_ADAPTER'}}}}`。
实测「无效 provider 却判成功」正是因为把任意 chunk 当成了走通。判据要落在
chunk 的类型上：finish 看 reason，其余才意味着模型真的在产出。

超时按成功处理（60 秒窗口）：模型可能只是很慢，把慢当成失败会在换模型的同时
把已经在跑的那一轮丢掉。

DSH 换模型要换会话 id（`<原 id>-r1`）并 dispose 失败那个 agent：复用同一个 id
会让重试接在一条已经出错的会话后面，不 dispose 则 agent/status 还会为那个
死会话触发一次自动转发。

## 其他决策

- **范围优先于环境变量**：范围是运行时可改的策略，`AGENTMAIL_REPLY_*` 是部署时
  的兜底。反过来的话管理员在配置页改了却不生效，得去改 service 文件重启
- **范围为空返回 `[undefined]` 而非 `[]`**：空数组会让调用方一次都不试，
  而「管理员没配」的正确含义是不限定，不是「一个都不许用」
- **上限 10 个**：降级是串行的，选 50 个意味着最坏情况下一封邮件要等 50 次超时
- 前端 key 按**第一个** `/` 切分 provider/model：model id 可能含 `/`
  （如 `org/model-name`），按最后一个切会把 provider 切错
- 保存后用服务端返回的结果刷新界面而非回显入参：repo 层会跳过重复与空字段

## 验证

- Go 10 个新测试（含「模型从目录消失后选择必须留存」的直接回归）
- 两插件各 18 个模型范围测试，共 180 个
- 端到端四轮：正常路由 → 全部无效（收到失败回报邮件，used_rounds 保持 0
  确认走了免配额通道）→ DSH 降级（fake-a 失败 → llmsproxy/AUTO 成功）→
  opencode 降级（nonexistent/bad 失败 → AUTO 成功，日志确认「前 1 个失败」）
- 生产已部署，前端「模型范围」页可用
 2026-09-02 21:34:55 +08:00
JianFeeeee
7c9be9fd58 docs: 插件适配指南 + 共用模块提取（为接入更多平台做准备） 
两次适配（opencode、DeepSeek Harness）里的方法与坑此前散落在提交信息和
代码注释里，接第三个平台时要重新翻。这次固化成文档，并把与平台 SDK 无关的
逻辑提到共用模块。

## docs/PLUGIN-GUIDE.md

八节：职责边界、必须实现的六件事、会话命名回写、平台会话快照上报、
平台差异对照表、踩过的坑（按排查成本降序）、新平台适配清单、共用模块清单。

三条设计原则贯穿全文，后面每一节都是它们的推论：

1. **平台原生信号才是真相来源**，不要求模型「记得」调工具 —— 因此不提供
   request_permission（改挂权限钩子）、不要求模型主动回信（改在「一轮结束」
   的平台信号上自动转发）
2. **插件代劳的转发不消耗配额** —— 因此这两类转发带 relay + relay_key
3. **平台命名优先** —— 因此创建会话时不传占位标题（那会掐掉平台自己的命名机制）

「踩过的坑」一节按排查成本排序，头一条是花了一下午的 followup() 参数形状。

## 共用模块提取

`lib/inbox-format.js`（新）：收件箱渲染与已读策略。三条规则各对应一次错误行为，
而它们与平台 SDK 无关：

- 附件必须带 attachment_id（只说「有附件」模型无从下载）
- 抄送人要显示（不显示模型以为是私信，回信时漏掉其他参与方）
- 只标本次列出的、status=all 时不标（limit 之外的还没看过；把历史邮件标成已读
  会让下一轮的新邮件混在里面认不出来）

顺带修好两处不一致：DSH 的 read_inbox 此前**完全没有标记已读**（每轮重复捞同一批），
且默认 status=all（同上）；附件大小两边一个显示字节数一个显示 KB/MB。

`lib/workspace.js`：提到两侧共用。签名从 (workspace, fallbackKey) 改为
(workspace, fallback) —— 各平台的兜底不同：opencode 有插件启动时的 directory，
DSH 只能落到 ~/.dsh/mail-sessions/<会话>（mailSessionFallback）。
opencode 侧此前是内联的三行判断，没有「目录不存在时不创建」与「拒绝相对路径」
这两条保护。

## deploy/check-shared-libs.sh

`lib/` 与 `test/` 下的共用文件必须逐字节相同，纳入 install.sh 门禁。

一侧改了另一侧没改，两个平台的行为就会悄悄分叉：同一封邮件在 opencode 那边
标了已读、在 DSH 那边没标，而两处代码看起来都「对」。这类分叉没有测试能发现，
只能靠 diff。

## 文档同步

- PLAN.md §7.7 从「待做」改为已完成，补 7.7.1（工作目录归属）与
  7.7.2（平台会话快照）两节，记录根因而非只记改法
- API.md 加「心跳与平台会话快照」章节；SSE 章节补 new_mail 与
  permission_decision 的 payload 说明（to_workspace 的语义、relay_key 的用途）
- PHASE7-REMAINING.md 移除已完成的 7.7，新增「每平台可用模型范围」的进展
  （repo 层已就绪，handler/插件/前端待做）
- README 文档索引与项目结构

验证：两插件共 136 个测试通过，同源校验通过，Go/前端全绿；
端到端发信 → DSH 用新的 read_inbox 渲染读取 → 自动回信 213 字节。
 2026-09-02 20:28:19 +08:00
JianFeeeee
ca64d12057 feat: 工作区归属修复 + 平台会话同步 + 对话树整树展开 + DSH 插件 
四个各自独立的生产缺陷，共同的根源都是「本该属于会话的属性没有存在会话上」。

## 1. dsh 指定工作目录完全失效（所有会话落进「未分组」）

插件建会话时用的 cwd 是自己拼的 `~/.dsh/mail-sessions/mail-<uuid>` ——
每封邮件一个全新的空目录。DSH 与 opencode 都按 cwd 给会话分组，于是所有
邮件会话既不属于任何项目、彼此也不同组。

而 Gateway 从来没把地址里的 path 位发给插件：`notifyRecipients` 的 payload
只有 mail_id/session_id/from_name/subject，`to_workspace` 虽然入库了却不在
SSE 事件里，插件即使想用也拿不到。

- SSE `new_mail` 事件加 `to_workspace`。**每个收件方拿到自己那个地址的 path**，
  不是主收件人的 —— 抄送给 opencode@/a 与主发给 dsh@/b 是两个工作区
- 两个插件的 cwd 都改为取寻址的 path 位；不存在的目录**不创建**而是回退到
  兜底目录（一个笔误不该在磁盘上落下真目录，Agent 会在里面一无所获地干活）
- 拒绝相对路径：cwd 的相对基准是 harness 进程的启动目录，systemd 下通常是 `/`

## 2. 会话别名列不出工作区下的历史会话（无法选择）

workspace 只存在于 `mails.to_workspace` 上，「这个工作区下有哪些会话」必须
JOIN mails 再从收发双方的 workspace 里猜。而 Agent 回信时 from_workspace
填的是 **Agent 名**而不是路径，旧条件 `to_workspace = $p OR from_workspace = $p`
在只剩 Agent 回信可匹配时两边都对不上。

- `sessions.workspace` 新列，`CreateSession` 从地址的 path 位带入
- `SuggestSessionCandidates` 取代 `SuggestSessionsFor`：以会话自己的 workspace
  为权威，历史会话（该列为空）回退到 mails 反推 —— 升级后老会话不该消失
- `FindOrCreateDefaultSession` 同步改用会话的 workspace

## 3. 平台侧会话在补全里根本不存在

人直接在 opencode/DSH 界面上开的会话，Gateway 一无所知。

新增 `agent_platform_sessions` 镜像表，插件在心跳里上报快照。
**上报而非 Gateway 反向拉取**：当前架构是单向的（Agent 持密钥主动连 Gateway，
Gateway 从不外呼），反向拉取需要它保存各平台的地址与凭证，那是另一套信任模型。

- 与 sessions 表分开存：镜像里是别人家的会话，id 属于平台的 id 空间，没有
  本侧的 owner/预算/邮件。混进 sessions 会让每一处「按会话鉴权」都要先判断
  这条到底是不是真的本侧会话
- **整表替换而非增量合并**：平台侧删掉的会话必须从候选里消失 —— session 位是
  三态语义，指向不存在的会话直接 404
- **nil 与空数组语义不同**：插件拉不到列表时省略该字段（保留镜像），
  而不是传空数组把镜像抹掉
- **subagent 子会话不上报**：实测 DSH 的 list 里混着 49 条子会话，标题就是
  派活的提示词前缀（九条都叫 "You are auditing ONE file"），slug 全撞名；
  它们是父 agent 内部的工作单元，人往里发邮件毫无意义
- **slug 撞名只留最近那条**：服务端只能取其中一条，上报同名项只会让补全里
  出现几个点哪个都不确定的候选
- DSH 插件此前**完全没有心跳** —— Gateway 靠 last_seen 判在线，一直靠注册撑着

补全候选带标题与来源：`suggestions` 保留纯字符串数组（不打破已部署的前端与
第三方客户端），新增同序的 `candidates`。过滤时标题也参与匹配 —— 人记得的是
「缓存选型」而不是 brisk-harbor 这种随机短名。

## 4. 对话树看不见抄送与转发产生的分支

旧实现从锚点分「祖先链 + 子树」两路展开，而**兄弟节点既不是锚点的祖先也不是
它的子孙**：一封抄送给两个 Agent 的邮件收到两个回复，从其中一个看树永远看不到
另一个；挂在原件上的转发分支同理。

改为先 `ThreadRootOf` 上溯到线索根，再从根整树 BFS。只剩一个加载方向，
因此不再需要滚动位置补偿。前端补上抄送人列表与转发标记 —— 树上两个兄弟节点
为什么并列，唯一的解释就是父邮件抄送给了两个人。

## 5. DSH 插件（Phase 7.7）

卡了一下午的 `Cannot read properties of undefined (reading 'kind')` 根因是
`followup()` 的参数形状：DSH 要完整的 UserMessage（content + source），
而我照抄了 opencode 的 parts 数组。错误抛在 agent-loop 内部，不指向调用点。

- `agent/status` → idle 时自动转发最后一条 assistant 消息（对应 opencode 的
  session.idle），复用 relay-dedup 让位于模型的主动回信，走免配额通道
- `approval/request` 权限询问转邮件问人。与 opencode 的差异：那边的
  permission.ask 是同步钩子只能立即返回 ask，DSH 这边是异步 waterfall，
  可以真的等人 —— 拆插件时未决询问一律 fail closed，否则 await 永不返回
- 会话别名由模型标题派生（保留中文，去掉 `.` `@` `/` 等寻址分隔符 ——
  留在别名里会让它自己被解析器切开）
- 逻辑放 lib/ 下的纯函数并加测试：三类约定都是「错了不当场报错、只在深处
  炸一个无关错误」

## 其他

- `deploy/reset-demo.sh`：清空演示邮件数据，保留账号与密钥。备份用 `.backup`
  而非 cp（WAL 下 cp 拿到的是缺尾巴的库）；手工按依赖顺序删（SQLite 的
  foreign_keys 默认关，声明了 REFERENCES 也不级联）；只在目标是默认库时才碰
  systemd（演练时误停过一次生产服务）
- 插件 dist/ 不进版本库，install.sh 负责构建
- `permission_decision` 事件补 session_id：插件重启丢了待决映射时要靠它定位会话
 2026-09-02 20:05:51 +08:00
JianFeeeee
07e6b789b2 feat: 配额下沉到会话 + 窄屏覆盖式布局 + 工作列表卡片视图 
## 配额重构：废除 Agent 终身额度

原实现在 agents 上放一个 max_rounds/used_rounds 计数器，used_rounds 单调递增、
永不重置 —— 跑满就要管理员手工重置才能再干活。那是把一次性资源模型套在长期
在线的服务上，且并行任务互相抢额度。

改为：
- 唯一被强制的预算是【会话】的往返预算（sessions.max_rounds/used_rounds），
  写信时给、对话页里随时改 —— 配额的语义是「这件事值得多少个来回」，
  那是任务的属性而不是 Agent 的属性
- agents.default_rounds 只作为「派给这个 Agent 的新任务」的默认值（默认 20）
- agents.used_rounds 降级为纯统计
- 新建会话速率限制（1h/20 条）堵住用 .new 开一串新会话绕过预算；
  人类不受限（agentLimiterKey 返回空串即不计量）

## 窄屏适配（用户反馈「窄屏基本不可用」）

原先只有三栏并排：60(导航)+320(列表)+详情，375px 屏上详情被挤到 0。

第一版做成「一次只显示一栏」，用户纠正应当是新页面覆盖老页面并带动画，
于是重做为覆盖式：
- NarrowStack：底层列表始终挂载，详情绝对定位盖在上面。两个好处 ——
  列表滚动位置与选中态天然保留；退出动画有东西可播（直接卸载再渲染另一个
  组件的话，没有任何一帧能让旧页面往右滑出去）
- 因此必须区分「逻辑上是否打开」与「是否还在 DOM 里」：关闭时先播 200ms
  滑出，动画结束才卸载
- 入场用双层 requestAnimationFrame：必须让浏览器至少绘制一帧「在右侧之外」
  的状态，否则挂载与 translate-x-0 在同一帧内完成，transition 不触发
- 窄屏专属控件用 useIsNarrow() 条件渲染而非 md:hidden —— 后者只是视觉隐藏，
  宽屏用户按 Tab 会聚焦到看不见的返回按钮
- 底部导航 + 抽屉侧栏 + env(safe-area-inset-bottom)

## 工作列表卡片视图（Phase 7.1 最后一项）

中间栏可切列表/卡片。列表答「跟谁在聊」，卡片答「在聊什么、进展如何」：
主题 + 最新一封的发件人与摘要 + 往返预算徽标。

- 两种视图共用同一份数据与同一套动作；归档确认框也共用 —— 归档是破坏性操作，
  换个视图就换套确认 UI 只会让人对「自己点了什么」更没底
- 预算徽标在「不限」时不显示（对每张卡片都成立的「0/0」是纯噪声）
- 数据一次取回，不让卡片为每条会话再打一次库

## 修掉的缺陷

- GET /me/sessions 一直 500：ListSessionsFor 的 SELECT 加了预算两列却没加进
  Scan，列数不匹配。联系人栏一条数据都拉不到，而错误只是「Failed to list sessions」
- GET /sessions/{id} 忘了填充附件：前端会话视图走的是这个端点，于是 Agent
  回信里的附件在 UI 上完全不存在（另一个端点填了但没人调用）
- 插件曾完全没在加载：为了可测在 index.js 里 export 了辅助函数与一个 Map，
  而 opencode 把入口模块的每一个导出都当成插件工厂逐个检查，多导出一个 Map
  就 "Plugin export is not a function"，插件静默失效、邮件全投不进去。
  逻辑挪到 lib/relay-dedup.js，并加断言钉住「入口只有 default 导出」
- 同一件事发两封邮件：模型带附件主动回信后，session.idle 又把它最后那段话
  自动转了一遍（生产实测 311 与 342 字节各一封）。explicitSends 记录本轮
  主动发信，自动转发据此让位；relay_key 幂等管不了这个 —— 那个键保证的是
  「同一条消息不转两次」
- SQLite 时间戳只有秒精度：同秒插入的多封邮件排序不确定（实测同秒插 5 封，
  顺序由随机 UUID 决定）。「会话里最早那封」（决定联系人身份）与「最后那封」
  （决定最新进展）都会取错。NOW() 升到微秒 + mails 的 INSERT 显式传它
  （改 schema 默认值只对新库生效，SQLite 没有 ALTER COLUMN）+ 所有
  ORDER BY created_at 补 mail_id 兜底
- fillAttachments 从逐封查询改成一次 IN(...)：原来是 N+1，200 封的会话打开
  要打 200 次库
- repo 层 5 处 rows.Next() 循环补 rows.Err()：没有它，读到一半连接断掉会
  静默返回部分结果，UI 上表现为「邮件凭空少了几封」
- go:embed 占位页改名 placeholder.html：叫 index.html 会被 Vite 产物覆盖并
  提交进去，而它引用的 assets/ 是被忽略的 —— 新克隆打开是白屏

## 回复/转发栏

- 两处都加抄送（可折叠）；原邮件带抄送时多一个「回复全部」，回填用
  cc_list[].raw 而非重拼 name@path（后者会丢掉会话段）
- 会话视图每张卡片加转发入口：转发之前只存在于单封邮件视图，而人多数时间
  待在会话视图里，等于功能在 UI 上找不到
- ReplyBar 的错误从 console.error 改为显示出来：预算耗尽、地址不存在、
  速率限制都走这条路，之前点发送毫无反应

## 测试

- repo: 列顺序（三个 SQL 分支）、卡片字段、previewRunes 边界、时间戳亚秒精度、
  批量附件查询、速率限制（80 goroutine 断言恰好 20 条通过）
- web: 窄屏布局 16 条结构性断言（覆盖而非分栏、延迟卸载、双层 rAF、
  条件渲染而非 md:hidden）
- 插件: 自动转发去重 17 条（含「入口只有 default 导出」不变量）
- install.sh 把插件测试也纳入部署前门禁
 2026-09-02 14:16:46 +08:00
JianFeeeee
0e754617a4 feat: AgentMail —— 以邮件为统一范式的多智能体协作平台 
Go 单二进制网关 + React 前端 + opencode 桥接插件。部署产物是
「一个二进制加一个 .db 文件」：前端经 go:embed 打进二进制，
数据库默认内置 SQLite，systemd 托管。

核心设计
- 三维寻址 name@path.session，按最后一个 . 切分；session 位三态：
  省略=默认会话 / new=强制新建 / 具体别名=必须已存在（否则 404 无法送达）
- 会话别名默认复用 Agent 平台自己的命名机制（opencode 的 slug 与模型生成的
  标题），不在本侧另造一套；人显式定过的别名不被平台同步覆盖
- 对话树不建 tree_nodes 表：parent_mail_id 已完整编码树结构，
  再维护一张表就是第二份真相。用递归 CTE 查，按方向分块加载
- 附件内容存磁盘、按 sha256 内容寻址，数据库只存元数据；天然去重，
  且路径与用户 filename 无关，杜绝 ../ 穿越
- 配额约束的是模型的自主发信，不是 harness 的转发：插件代劳的权限询问与
  最终总结走免配额通道，靠上游消息 id 做幂等键而非计数
- 往返预算下沉到会话（写信时给、对话页里改）+ Agent 全局配额，两层都要过

后端 gateway/
- models/repo/handler/middleware/sse/blob 分层；两方言（SQLite/PostgreSQL）
  共用一份 repo 层 SQL，差异集中在 internal/db
- 多用户认证（bcrypt cost12、登录限速、会话隔离、权限边界）
- 密钥体系：Agent 密钥与用户密钥分表，三种生命周期；登记式密钥让全文
  只从客户端流向服务器一次
- 所有「判断 + 自增」都在同一条 UPDATE 里（配额、预算、one_time 密钥、
  附件挂载），并发下不会刷穿

前端 web/
- 三栏布局、三段式地址补全、权限卡片、密钥面板、配额面板、对话树、附件
- 全站纯 SVG 图标，不使用 emoji
- api/ 即可复用的客户端 SDK：基地址与凭证集中在 api/config.ts

插件 plugins/opencode-mail-bridge/
- 六个工具 + 两类自动转发（permission.ask 钩子接管平台原生权限询问、
  session.idle 时转发本轮总结）
 2026-09-02 10:29:26 +08:00