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

17 Commits

Author SHA1 Message Date
JianFeeeee
453f451fbb fix(permission): 人类的备注必须到达模型 + 决策回执不再被当成新任务 
用户报的「很严重的问题」：被拒绝的 agent 看不到授权备注，且看不到他发的回复邮件。
按数据查到了两个**真缺陷**，都在桥的权限回路上（不是猜测，三层证据）。

## 缺陷一：备注在桥内被连丢三处

网关其实一路都带着备注（`CreateDecisionMail(..., req.Note)` 把备注写进决策邮件正文，
SSE payload 里也有 `"note"`），但桥的三个环节只传 decision：
  index.mjs  `pool.routePermission(relayKey, String(data.decision))`
  pool.mjs   `child.send({type:'permission_decision', relayKey, decision})`
  worker.mjs `resolve(String(msg.decision))`
模型最终看到的只有 `用户拒绝了这次 bash 调用`（pi 会话转录逐字可查）。

现场：人类写「我说了让你拉取仓库到program下你听不懂吗」，模型不知道要改什么，
把同一条命令换个写法又问了 —— 会话里连问 **9 次**（22:16–22:26）。

## 缺陷二：决策回执照样被当"新任务"投递 + 等人的邮件被堵在后面

决策是**双通道**送达：SSE `permission_decision`（唤醒停放的 worker）+ 一封普通形状的
邮件（"Re: 权限请求 - 拒绝"）。以前两条都会起动作 ⇒ 同一件事被处理两次；而这条会话
的新邮件在 worker 停放期间只能排队。实测：人类 22:18:08 发出的更正
「不对，不是让你拉取到agentmail仓库，是让你拉取到program仓库！！」
直到 22:26:30（worker 回合结束）才被模型看到 —— **8 分钟**里它一直在错误的目录上打转。
转录里那封更正确实是模型自己 `read_mail` 读到的（不是没人给它）。

## 改动

- 网关：`CreateDecisionMail` 写 `mail_type='permission_decision'` —— 桥据此区分
  「控制面回执」与「新任务」。
- pi 桥（新增 `lib/denial-reason.js`、`lib/waiting-mails.js`）：
  · 备注随决策一路透传到**模型看到的拒绝理由**（工具拦截与通知投递两条路都带）；
  · 恢复停放的 worker 时，顺带把「等人期间新到、尚未标记已读」的邮件附进理由，
    模型当场就能改道（这正是那 8 分钟的洞）；
  · 决策回执不再起新任务轮次（记进 deliveredMails）；若决策事件尚未到达，
    退化为 B-4.3 的通知投递，且没有会话时不凭空新开。

## 判据

- `test/permission-note.test.mjs`：11 条（备注进理由、无备注不得凭空造说明、
  等人期间的邮件要点名 read_inbox、只挑本会话非权限类未交付的、上限、旧回包缺
  session_id 不能丢邮件、接线 8 处形状、判据自检）。
- **扰动验证**：把备注从 `pool.mjs` 的 send 里去掉 → 接线判据 2 条红；恢复 → 11 绿。
- 既有 pi 套件 420/420；server 10 包全绿（新增 1 条 Go 判据验决策邮件的类型与备注正文）。

## 现场证据（可复核）

- 桥日志：9 次 `权限 <key> 决策 同意/拒绝（决策人 jianf）已转交 worker`，全程不含备注；
  「worker 2135211 等待权限决策，让出并发额度（停放 1/5）」
- 会话转录：`{"toolName":"bash","content":[{"text":"用户拒绝了这次 bash 调用"}]}` ×6
 2026-09-13 22:47:25 +08:00
JianFeeeee
77699e216b fix(webui): 新到的授权请求藏在折叠分组里 —— 徽标动了，内容看不见 
用户报告："我点到授权界面，才更新显示授权请求"。

先排除了推送本身：实测徽标是**实时**更新的（gui-lab 授权 7→8、jianf 1→2，
都没导航）。问题在内容：`PermissionList` 的展开状态
`const openSet = expanded ?? new Set(autoOpen)` —— 一旦手动点过一次，
`expanded` 就冻结成"点的那一刻"的快照，此后新到的待决请求落在一个折叠的分组里：
徽标数字变了，正文却看不见，直到离开再回到授权页（组件重挂载、`expanded`
回到 null、默认展开重算）才出现。

这违反代码自己的设计意图（注释写着「有待决策请求的会话默认展开：那些是在等人
动手的，藏起来等于没解决问题」）。

修法：加一条**状态迁移**判据 —— 新出现的待决邮件（`sessionId:mailId`）让它所在
的会话自动展开。用 mail_id 而不是"会话有没有待决"作判据，是因为实测撞到的正是
"会话早就有待决、用户把它折叠了，之后又来了一条"；而用户在那之后再手动折叠同一
条不会被弹开（没有新 mail_id）。

验证：
  · 真浏览器复现：授权 2 → 3 而新请求正文不可见，重进页面才可见（复现成功）
  · 新增 `test/components/PermissionList-autopen.test.tsx`（3 条，含反向对照）
  · 扰动验证：撤掉修复 → 2 条目标判据红、对照判据仍绿；恢复 → 3/3
  · 部署后同一探针复验：折叠状态下新请求**立刻可见**，不再需要重进页面
  · 前端 239 测试全绿；桌面重打包与 WebUI 同源（index-jaRgHqX2.js）

顺带修掉一个**更严重的缺陷**（在做「用 zcode 写个网页」时被 agent 自己报出来的）：

  fix(plugins): zcode 的 read_mail 永远返回空正文

agent 回信原话：「read_mail 返回的正文是空的，收件箱预览在「点击计数…」处被截断」
—— 它因此只看到前两条要求，写出来的页面漏了第 3 条（生成时间）。

根因在 `lib/inbox-format.js` 的渲染端：

    const body = m?.body_preview || m?.body || '';
    lines.push(`内容: ${String(body).slice(0, bodyLimit)}`);

zcode 的 read_mail 用 `bodyLimit = 0` 表示"要全文"（HTTP 侧 `?body_limit=0`
也确实是这个语义，服务端返回了完整正文），但这里 `slice(0, 0)` 把正文渲染成
**空字符串** ⇒ 模型永远读不到全文，只能看收件箱里那段预览。

修法：`bodyLimit <= 0` 视为不截断；不截断时优先取 `body`（单封接口可能同时带
`body_preview`，那是短的那个）。四份副本逐字节同源（`check-shared-libs.sh`
通过），每个桥各加 2 条判据：0 = 不截断、不截断时优先全文。
扰动验证：退回旧写法 → 2 条红。

端到端验证：让 zcode 读全文并原样回报最后一行（一个随机标记）。
修复后它精确回出 `最后一行标记：ZTOKEN-2c7561fd` ✓ —— 修复前这不可能。

四家桥都已重新部署到新快照（pi/opencode/dsh/zcode），部署漂移检查：
「四个宿主都在跑当前代码」。测试基线：pi 417 / opencode 323 / dsh 372 / zcode 382。
 2026-09-13 10:39:26 +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
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
a60ab66a40 refactor(plugins): 删掉「摆了一套权限规则却没人调用、且形状没人能消费」的死代码 
# 问题

`lib/permission-mode.js` 里的 `opencodePermissions(mode)` 实现完整、注释详实
（含 6 条实测结论）、还有 9 条测试把行为钉住；opencode 的 `index.js` 第 45 行
确实 import 了它 —— 然后**全文件再没有第二次出现**。

静态审计要花力气才能发现它是死的，而读代码的人会理所当然地以为
「opencode 的 plan 档由这套规则拦着」。实际 opencode 是 advisory。

比 9.17（给了按钮不实现）更深一层：那只是没实现，这个是**看起来像实现**。

# 它不只是没接上，而是接不上

查 1.18.29 的 SDK 类型定义，三条都排除：

  SessionCreateData.body 只有 { parentID, title }；query 只有 { directory }
      → 会话级根本没有 permission，也没有 agent
  permission 只存在于 Config / AgentConfig，且是 map 形状
      → { edit, bash, webfetch, doom_loop, external_directory } → ask|allow|deny
  Permission 事件（permission.updated 的 properties）没有 action 字段
      → { id, type, pattern?, sessionID, messageID, callID?, title, metadata, time }

而函数返回的是 `{permission, action, pattern}[]` —— **与三者都不匹配**，
并且 deny 了 `task`（本版本 permission 的合法键里没有 task）。

所以不是「加一行调用就生效」，而是**输出没有任何消费者**。

# 为什么 opencode 的 per-session 强制做不到（如实说明）

Config / AgentConfig 是配置文件级（全局或项目级）。邮件桥若靠改配置给某条会话
加 plan 限制，会连带锁住这个人**其他所有**会话的同一工具 —— 一条 plan 档的邮件
把人身兼的其他工作一起禁掉，不可接受。

opencode 目前唯一的拦截路径是「它自己先问 → 桥转发 → 服务端按档位 409 →
桥当场 block」，**前提是它的配置恰好是 ask**；若配置直接 allow，桥连
permission.updated 都看不到。这就是它只能是 advisory 的原因，不是缺工作量。

# 改动

- 删除 `opencodePermissions` 及其 doc 注释、`OpencodePermissionRule` 接口声明
  （三份共用库同时改，改后 md5 仍逐字节相同）
- 删除 opencode/index.js 里那行未使用的 import
- 删除 9 条针对该函数的断言（三桥各 9 条）
- **6 条实测结论没有丢** —— 搬进 `docs/PLUGIN-CONTRACT.md` 新增的 §9.18，
  连同上面那三条类型证据与「为什么 per-session 做不到」

删掉而非保留，是因为留下的就是陷阱：函数存在、注释写着「实测过」、
测试还全绿，唯一缺的是调用点 —— 下一个人会以为档位在这里被强制。

# 验证

- `deploy/check-shared-libs.sh` → 共用模块三方同源
- 三桥 `npm test` 全绿：pi 400 / dsh 360 / opencode 311，0 失败
  （删除前 pi 409 / opencode 320，各 −9 即被删断言；dsh 另有并发提交新增测试，
  净 −9 后为 360）
- `node --check` 四个改动文件全过；ESM 动态 import 该 lib 成功，
  导出里已无 `opencodePermissions`，index.js 只引用仍存在的符号
- 本改动不影响运行时行为（删的是一个从未执行的函数与一个未使用的 import）
 2026-09-11 23:59:24 +08:00
JianFeeeee
4050827e5c feat(permission): 新增第三种强制力 partial —— DSH 如实自报，不再冒充 native 
# 问题

审计发现 DSH 自报 mode_enforcement=native，而实测它的 Landlock 沙箱受内核 ABI
版本限制、拦截覆盖不完整（PLAN.md L5 自己写的就是 dsh = Landlock partial）。

只有 native / advisory 两个取值时，这个平台无论标哪个都是在说假话：
  - 标 native → 人会以为 plan 档是硬保证，把它当安全边界依赖；
  - 标 advisory → 又低估了它（确实在拦），而「平台无法强制」会让模型
    在本可依赖的边界上过度保守。
多一个取值比多说一句假话便宜。

# 改动

- Go models：EnforcementPartial = "partial"，ValidEnforcement 接受它；
  NormalizeEnforcement 对显式自报值一律原样保留（partial 降级到任一极端都是假话），
  未知值仍然 fail-closed 到 advisory。
- 三桥共用 lib/permission-mode.js（逐字节同源）：ENFORCE_PARTIAL +
  modeBriefing 三态措辞。partial 版必须同时做到两件事：
  说清「覆盖不完整」，并收回 native 那句「都会被平台拦下」的承诺
  —— 否则模型会以为越界一定被拦，于是不必自己小心。
- 前端 PermissionChip：三个点形区分（实心 / 靶心 / 空心）+ 三套 tooltip 文案；
  认不出的强制力按 advisory（与后端同方向）。
- DSH 插件心跳改报 partial。
- 顺带修正活跃 DSH 会话的历史快照：那批 native 是插件当时的**误报**，
  不是能力变化，因此把 status<>'archived' 的 dsh 会话改为 partial；
  归档会话按设计保留（不重写已结束的历史）。改前已 sqlite3 .backup 备份。

# 验证

- agents.mode_enforcement：dsh 由 native 变为 partial（心跳生效）
- Go 全量、三桥插件 320/362/409、前端 196 全绿（新增 PermissionChip 11 例）
- 三桥共用模块同源校验通过
- 关键判据：partial 的措辞与 native/advisory 两两不同，且不含「无法强制」
 2026-09-11 12:04:06 +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
a44fd6949b feat: 权限档位体系（三档 plan/workspace/full + 四桥 from_session_id） 
L2 核心改动：sessions 表补 permission_mode / permission_enforcement 两列
（sqlite + pg 同步），三桥 lib/permission-mode.js 翻译档位到平台原生配置，
homeagent advisory 模式提示词告知模型实际强制力。四桥全部携带 from_session_id
供 relay 去重与会话回溯。

FromHuman / ToHuman 判据已加入心跳 payload 与 notify/mail.go。
 2026-09-06 15:16:49 +08:00
JianFeeeee
13fcb00acc feat: relay-key 共用模块（三桥 + homeagent） 
Sha256 clamp relay_key 过 160 字节上限，避免服务端 400
被 worker 当暂时失败让位，导致邮件驱动会话无本地 UI 静默挂死。

新增 relay_key.go / relay-key.js + 15 个纯函数测试。
 2026-09-06 15:16:34 +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