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

12 Commits

Author SHA1 Message Date
JianFeeeee
e3c10cbd65 fix(pi-bridge)★★: 身份绑定冲突时中止，不再以错误身份继续运行 
2026-10-05。起因是一份 bug 报告里的三条，我只认了其中一条真的。

## 先说报告里那两条**不成立**的（我实测了）

① 「服务端会用 200 + {"error":…} 返回业务失败，所以回执是假成功」

   实测穷举所有失败路径，**没有一条 200 带 error**：
       跨会话读 403   缺 workspace 400   坏凭证 401   邮件不存在 404
       send 缺参数 400   收件人不存在 404
   根因：`Error(w, status, msg)` 的 status 是必填参数，
   全仓不存在 `Error(w, 200, …)`。所以 `post()` 只在 `!res.ok` 时抛错是对的。

② 「sent_total=0 说明没发出去」

   **Agent 身份没有「已发送」端点**：
       GET /api/v1/me/mail/sent → 401（那是人类端点）
   Agent 能用的邮件端点只有 mail/{id}、mail/{id}/thread、contacts、calendar。
   `sent_total=0` 不是「计数为 0」，是**根本查不到** ——
   把「查不到」读成「没发出去」，这是整条误判链的起点。

   而实际证据是**信送到了**：
       mail_id 317a0b4b…  from laptoppi-win → jianf
       mail_reads: reader_name=jianf, read_at=2026-10-05 02:55:49
   （发信后 13 分钟被人亲自读了）

## 报告里那条**真的**：换 key 后不自知

它的根因描述准确：身份由密钥决定，而配置在模块加载期读入，改 env 不热生效。
本仓库的桥同构（`index.mjs` 顶部 `const AGENT_SECRET = process.env…`），
且启动日志只印**本地配置里**的名字 —— 于是漂移在日志里看不出来。

## 修法：服务端早就内置了这道闸，桥没接

实测 `POST /api/v1/agent/register`：

    {"name":"pi"} + dsh 的 key
    → {"error":"该密钥已绑定到 Agent \"dsh\"，不能用于注册 \"pi\""}

「这把 key 到底是谁的」服务端能权威回答。
旧代码把注册失败**当普通错误打印一行就继续跑** —— 于是继续以错误身份
发信/收信/上报心跳，而日志里那句「身份 ${AGENT_NAME}」读起来一切正常。

两处改动：

1. **冲突时中止**：识别 `/已绑定到 Agent/` 后 `throw`，
   并打印**怎么查**（sqlite 查 agent_keys）、**怎么改**（改 env + 必须重启）。
   ★ 只对绑定冲突停 —— 密钥无效 / 网络不通属可恢复的，
     停掉会连带 SSE 与心跳，而那两样本就该重试后自愈。

2. **启动日志印 key 前 8 位**：身份实际由密钥决定，只印配置里的名字
   不足以代表真实身份。现在一行能对出来：

       已接入 http://127.0.0.1:8180，身份 pi（密钥认证 c31044d6…）

   ★ 印 8 位不发全串 —— 避开日志泄密。

## 判据（新建，5 格，3 变异全红）

变异① 只记日志不中止 → 转红
变异② 认不出冲突     → 转红
变异③ 日志不印 key 片段 → 转红

pi 桥全量：533 → **538 格**（+5），0 失败。已部署并重启线上服务。

## 没能修的：Windows 上那个扩展

`C:\Users\21989\.pi\agent\extensions\agentmail.ts` 本机不可达。
它需要做的两件事，本仓库这个提交就是参照：

1. 注册/首次调用时拿服务端权威答复核对身份，不一致就**停下并说清怎么查**
2. 启动日志同时印出 `agent_name` + `key 前 8 位`，让漂移可见
 2026-10-05 11:04:55 +08:00
JianFeeeee
4175c0ba45 fix(bridge): ★ 投递即标已读 —— 修「桥重启 → 重投 → 回声」 
用户 2026-09-26 原话：
  「我都不记得我下达这个任务，是你的桥自动重投存在 bug」
  「就是你的错误的重投机制造成了回声」

# 我上一轮把因果搞反了

我先认定是「两个 Agent 自发辩论」，还为此写了第三道防线（数 Agent↔Agent
连续往返）。**方向错了** —— 是**桥把同一封信反复投递**，每次投递起一个
worker 回信，回信又触发下一轮。模型在做什么？它在回答一封被重复投进来的
旧信。用户根本不知道有这回事。

# 根因：deliveredMails 只在内存，库里的 status 从没被写

投递路径（SSE `new_mail` / 心跳补投 / 决策回执）只做两件事：起 worker、
把 id 记进 `deliveredMails`。**没有任何一处调 `/mail/read`** —— 桥里唯一
那处标已读在 `read_inbox` 工具里，要等模型自己去读收件箱。

于是每封被投递的信**永远是 unread**；而 `catchUp` 按 `status=unread` 拉
⇒ 桥一重启（**每次部署都会**），积压的"未读"被当成离线漏投**再投一遍**。

# 实证（不是推断）

· 5 个 mail_id 各出现在**两条不同 pi 会话**里：
    f06129f4 → 04:54:45 投进 01a0a2bd
             → 08:01:20 投进 01a0daf0
  （而那封信库里已有 1 封回信 —— 它早就被处理过）
· 同一封信被投两次 ⇒ 两个 worker 各回一封 ⇒ 对方收到两封 ⇒ 各回两封…
· pi 收件箱 287 封 unread 中 **187 封已经回过信了**
  （`EXISTS(SELECT 1 FROM mails r WHERE r.parent_mail_id=m.mail_id)`）
· 两条会话各烧到 463 / 268 封
· 桥侧：同一邮件会话 id 前缀 `01a0a2bd` 出现在 **4 个** pi 会话文件里
  （投了两次 + 别的历史残留）

# 修法：内存与库必须同时写

`deliveredMails` 是**内存**集合，重启即丢；数据库的 status 才是跨重启的
"我接管过了"记录。两者只写其一 ⇒ 口径不一致 ⇒ 重投。

新增 `markDelivered(id)`：**凡是标记"我接管了这封"的地方都走它**
（SSE / 补投 / 决策回执三个投递点），同时写内存与库。漏一处就是一条重投
路径 —— 这正是缺陷的形状（四处各自 add，没有一处标已读）。

标已读只改 status，不改内容、不删行；`read_inbox` 传 `status=all` 照常可见。
而"已交给一个 worker 处理"正是那封信此刻的真实状态 —— 库里本来就该记这件事，
而不是"模型有没有顺手调过 read_inbox"。

# 四个桥：三个有缺陷，第四个早已修过

| 桥 | 投递标已读 | 说明 |
| --- | --- | --- |
| pi | ✗ → ✓ | 三处 add 都不标 |
| opencode | ✗ → ✓ | 同上 |
| dsh | ✗ → ✓ | 同上 |
| **homeagent** | **✓ 早有** | `ledger` 落盘，跨进程 |

homeagent 不用这个修法：它的 `ledger` 记 `delivered`/`completed` 两个状态，
只有 `completed` 才跳过（投过但被中断的**仍然重投**并带说明）—— 那份设计的
注释里就写着 18:59:38 那次实测，比我今天这个修法更早也更完整。
所以对它只做了「补投按工作区收窄」那一半（见下条）。

# 附带修：homeagent 的 workspace 收窄（我今天打破了它）

我先部署服务端（缺 workspace 直接 400）并修了三个桥，**漏了 homeagent**
⇒ 线上 07:42 起持续报 `read_inbox 工具执行失败: HTTP 400 缺少 workspace`。
这是我造成的，靠自己的日志发现的（pid 还是重启前的旧进程 2291455）。

修法与另三个同源：`currentWorkspace`（信封的 `to_workspace`）在回合期间暂存
（与 `currentSessionID` 同一形状、同一生命周期），`inboxURL`/`scopeQuery` 带上它，
补投从"读一次全局收件箱"改为逐工作区（清单来自心跳的 `pending_workspaces`）。

# 清理重投燃料

151 封归档（80 封回声：会话全程无人类 + 71 封 `permission_decision` 不可投）。
★ 用 `archived` 而不是 `read` —— `read` 还能被 `status=all` 拉出来重投。
判据用服务端自己的口径（`unreadFor` = `m.status<>'archived'` 且
`mail_reads` 无该读者），不手写 SQL 猜语义。

后置：pi / dsh / opencode / homeagent 在**所有工作区**的 unread 全部为 0。

# 判据

· `delivery-marks-read.test.mjs` × 3（pi / opencode / dsh）各 4 条：
  核心那条钉的是「`deliveredMails.add` **只允许**出现在 markDelivered 内部」——
  任何别处直接 add 就是绕过标已读的重投路径。另加自检反例。
  变异验证：绕过投递点 / markDelivered 不写库 / 补投绕过，三处全判红。
· `inbox_workspace_test.go`（homeagent）5 条：URL 带 workspace、带不到时不带
  （让服务端 400：错误可见好过静默越界）、补投逐工作区、两处投递路径都设工作区
  且都清空。变异 3 处全判红。
· 改了两条既有判据（pi / dsh 的 permission-note）：原来钉
  `deliveredMails.add(decisionMailID)` —— 那个形状**就是**缺陷载体。
  语义没变（仍"不再当新任务"），载体变了。

全量：pi 517 / opencode 344 / dsh 407 / homeagent 除一条既有的
`TestSDKPinMatchesBuildMachinePointer`（依赖构建机路径，改动前后同样红）全绿。
 2026-09-26 09:18:39 +08:00
JianFeeeee
7634be8966 fix(inbox): 收件箱按**工作区**收窄（三维地址的 path 位此前从未被使用） 
用户 12 天前就提过（`552fbc7` 只修了 session_id 那一维），这轮才真修。
用户原话：「难道让一个不在项目工作区的 agentsession 去修工程吗？」

# 缺陷（生产实测，2026-09-26）

在 `mc` 工作区干活的 pi 读收件箱拿到 **200 封，其中 191 封属于
`/home/program/agentmail`** —— 它照着那些信里的断言去改 agentmail 的代码，
把手上的 mc 活丢在一边。用户当场问它「你怎么干着干着修 agentmail 去了？」
（这条对话就在 mc 会话的 jsonl 里）

根因：`ListInboxScoped` 的 WHERE 只有 `m.to_name = $1`（+ 可选 session_id），
**没有任何 workspace 条件**。三维地址 `name@path.session` 的 path 位
在收件箱侧从未生效 —— 那不是"另一种语义"，是没兑现契约。

# 三条守卫全部只覆盖自动转发，防不住这个

| 守卫 | 只覆盖 | 为何无效 |
| --- | --- | --- |
| 会话预算 | `relay != ""` 才扣 | 这批信 relay=0（模型主动发）⇒ 不扣 |
| maxRelayHops=5 | 同上，只数 relay | 同上 ⇒ 不进那个分支 |
| 插件自动转发守卫 | 插件代劳时 | 日志明说"本轮不自动转发" ⇒ 模型自己发的不受管 |

# 服务端

· `ListInboxScoped` / `CountUnreadScoped` / `MarkAllInboxReadForSession`
  三处统一加 `s.workspace = $N`（用会话的 workspace，不用 mails.to_workspace：
  后者是信封字段、可能是抄送或历史遗留；"线索属于哪个工作区"是会话属性）。
  ★ 三处必须是**同一个谓词** —— 列表看不到的信却被"全部标掉"标掉就是静默丢信
  （session_scope_test.go 记过这个形状）。
· **workspace 在 Agent 侧必需，缺了 400**（用户裁定：「不带 workspace 是错误
  发件格式，直接退回！」）。旧语义（不带=全部）正是缺陷本身，不留兼容回退。
· 人类侧**不过滤**（一个人跨工作区，WebUI 按 session_workspace 分组显示）——
  所以"必需"这条约束放在 Handler 而不是 repo 层：它是接口契约，不是数据层不变量。
· 新增 `UnreadWorkspaces`：心跳是**进程级**（一个桥服务所有工作区），没有
  "我的工作区"可言；但只有总数桥不知道去哪个工作区补投 ⇒ 心跳回
  `pending_workspaces` 清单，桥逐个消费。
· 决策载荷补 `workspace`（服务端知道 session→workspace，插件重启后推不出来）。
· `TouchAgentLastSeen` 从 HeartbeatAgent 拆出：middleware 在每个认证请求上都调它，
  而那时工作区还没解析（请求体没读），原来在白算一次 CountUnread。

# 三个插件（pi / opencode / dsh）

· 读类工具带 `workspace`；补投从"读一次全局收件箱"改为**逐工作区**读。
· pi：worker 信封的 `to_workspace` 经闭包递进工具（不是会话文件 header 的 cwd ——
  后者是"会话上次落在哪"，前者是"这封信寄到哪个工作区"）。
· opencode/dsh：插件常驻、信封在 deliverMail 那刻就消费掉了 ⇒ 新增
  `sessionWorkspace` 映射（键与既有 reverseMap 同一把）。
· 修一处真 bug：`UnreadWorkspaces` 原先会返回相对路径工作区（历史库里有
  `workspace='root'`），桥侧实测撞 400（`补投工作区 root 失败`）⇒ 只报可寻址的。

# 实测凭据

· 改前：`pi` 的收件箱 200 封混 3 个工作区（agentmail 191 / TrueAgent 7 / huawei 2）
· 改后：agentmail=100（total 228）、mc=16、TrueAgent=7 —— 各工作区独立
· 不带 workspace ⇒ **HTTP 400**，话术给出可执行步骤
· 桥日志：`rw=/home/newqqagent/plugindev/editdoc-upgrade` —— 终于是别的工作区了
  （改前 78 次 worker 启动**全部**是 `/home/program/agentmail`）

# 判据

· `server/internal/repo/workspace_scope_test.go`（3 条）：
  两向收窄 + **反向对照**（不带时两条都看得到 ⇒ 证明是收窄不是清空）+
  未读数同口径 + 相对路径必须报错
· `plugins/pi-mail-bridge/test/inbox-workspace-scope.test.mjs`（4 条）：接线 +
  取信封而非 cwd + 补投逐工作区 + 判据自检
· dsh 那条 `取不到会话时退回整体收件箱` **改了**：它钉的"退回整体"正是缺陷，
  现在钉"两维各自缺席时各自不带、服务端 400 让错误可见"
· 变异验证：服务端 2 处 + 插件 3 处，全部判红后恢复回绿

全量：server `go test ./...` 绿；三插件 513+340+403 全绿。
 2026-09-26 07:44:33 +08:00
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
f9d757b5e5 chore: directory migration - gateway→server, web→client/electron 2026-09-08 19:16:35 +08:00
JianFeeeee
0c98fab4d5 pi: 档位判定 tool_call hook + 心跳报 native 
- worker.mjs: mailContext 加 permissionMode 字段（从 SSE payload 读入）
- tool_call hook 增加档位判定：
  full → 不拦截任何工具（直接 return）
  plan → 被守卫工具（bash/write/edit）一律 block + 返回原因说明
  workspace → 走原有问人流程（不变）
- index.mjs 心跳上报 mode_enforcement: 'native'
- 导入 normalizeMode/MODE_FULL/MODE_PLAN 从 lib/permission-mode.js
- 377 测试全过
 2026-09-06 19:19:42 +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
c941fa0f87 DSH 续谈分支不刷回信上下文 → 第二封的回信挂在第一封上 
## 症状

全流程回归时发现：同一条 dsh 会话的第二封邮件，回信主题写的是**第一封**的主题，
`parent_mail_id` 也指向第一封。实测（旧版负向对照）：

  jianf  负向对照 第一封
  dsh    Re: 负向对照 第一封   parent=48c4fedc  ← 对
  jianf  负向对照 第二封
  dsh    Re: 负向对照 第一封   parent=48c4fedc  ← 错，应为「第二封」

模型答的内容是对的（收到甲 / 收到乙），坏的是回信的主题与线索归属 ——
在收件箱里看起来像「同一封信被回了两遍」，而第二封的回复无处可寻。

## 根因

`mailContexts` 只在两处写入：`bindAdopted`（接管时）与新开会话分支。
`deliverMail` 的**续谈分支**（`existing` 且 agent 还活着）不写 —— 于是自动转发
用的还是第一封的 subject / mailID。

pi 与 opencode 都没有这个问题：pi 的 worker 一封一进程，每次重建 mailContext；
opencode 在 `deliverMail` 开头统一刷，注释写的就是「一个会话里可能来过多封信，
只保留最近那封」。DSH 漏了这一处，语义与另两个平台不一致。

## 修法

续谈分支进入 `locked()` 后先刷 `mailContexts`（`kind === 'mail'` 才刷 ——
权限通知不是新来信，不该改回信目标）。

## 顺带：pi 主进程删掉不会被调用的 createMailTools

工具是给模型调的，而重构后主进程没有会话。`connect_to_server` 换坐标的闭环在
pool 的 `onReconfigure` 里（工具跑在 worker，worker 回报给主进程）。
schema 约束由 `test/tool-schema.test.mjs` 直接验 `createMailTools`，
不需要在主进程建一份没人用的副本。

## 验证

- 旧版负向对照：确认第二封的回信 parent 指向第一封（复现）
- 修复后：`Re: 修复确认 甲` parent=d879f429 / `Re: 修复确认 乙` parent=e8f216a2，
  各自归位
- 四平台同发一封（pi 接管会话 + dsh/opencode/homeagent 抄送）：四封回信全部到位
- dsh 219 / pi 269 / tsc 0
 2026-09-04 21:00:11 +08:00
JianFeeeee
8e501f041e pi 桥改为工作进程池 + homeagent 落盘投递账本 
## pi 桥：模型工作下到子进程（并发模型重构）

主进程原来自己跑模型，而 pi 的会话装载是同步的：`SessionManager.open()` 走
`openSync` + `readSync` 循环把整个 `.jsonl` 读进内存并逐行 JSON.parse。实测本机
最大那条会话 23MB，`open` 一次**阻塞事件循环 118ms**；模型跑起来后 SDK 内部还有
更多同步工作。SSE 读循环在那期间完全停住 → 后续邮件卡在 TCP 缓冲区 → 久到
Gateway 认为连接死了 → 重连 → 重放。

上一轮我在几个调用点前加 `setImmediate` 是无效的仪式（让出一次之后同步工作照样
占满线程），已回退。这一轮把模型工作整体搬进子进程：实测同样的活在 fork 出的
子进程里跑，主进程事件循环阻塞 **0ms**。

- 新增 `src/worker.mjs`：一封邮件一个进程，跑完就退。权限询问期间的挂起只影响
  那一个 worker（原来 `await new Promise(...)` 等人决策，整座桥不再收信）。
- 新增 `src/pool.mjs`：**不同会话并发**（上限 3，每个 worker 约 140MB RSS）、
  **同一会话严格串行**（pi 假定「一文件一持有者」，两个进程同时装载同一条会话
  文件会让各自的内存索引看不见对方追加的行 → 会话树分叉）、满载排队不丢邮件、
  硬超时 SIGKILL 回收卡死进程。
- `src/index.mjs` 只剩 I/O 与调度：SSE、心跳、去重、分派。
- 选进程而不是 `worker_threads`：模型会跑 bash/write/edit，一次 OOM 不该带走
  整座桥。两者实测都能建起 AgentSession，但线程与主线程共享堆和生命周期。
- 「接管会话短暂持有」那套机制（adopted / adoptTimers / releaseAdopted + 兜底
  计时器）整个删掉 —— worker 退出**就是**释放，且普通会话与接管会话一视同仁。
- 轮次超时 60s → 10 分钟：60s 那个数字是「主进程要腾出手收下一封」的产物，
  worker 没有这个理由，等真结论更准（带工具调用的一轮跑几分钟很正常）。
- IPC 只传路径与标量（sessionFile / cwd / grants / 命名指纹）—— AgentSession
  跨不了进程边界，worker 每次从 sessionFile 重新装载。

`test/pool.test.mjs` +19 例，真 fork 子进程、用桩 worker（不装 SDK）跑毫秒级：
并发上限、同会话串行、不同会话真并发（判据是两个进程的心跳交错，不是 running
map 里有两个条目）、sessionFile/grants/命名指纹跨 worker 传递、config() 每次重取、
硬超时回收、权限决策路由、决策原文透传、worker 退出后清路由、mailDrivenIDs、
kind 透传、stop 先发 shutdown 再杀。跑过三组负向对照确认用例真能抓回归：
拆掉串行守卫 / 不传 sessionFile+grants / 硬超时不杀，对应用例分别失败。

## homeagent：投递去重必须落盘

用户报的重复投递不是上一轮那个 bug。两段提示词的措辞差异指出了来源：
SSE 那段写「你把本轮工作做完」，补投那段写「你把结论说出来就行」。

`deliveredMails` 是进程内的 map，而 homeagent 的插件跑在**子进程**里：

  1. 18:59:38 邮件落库，旧插件进程的 SSE 收到，注入第一次
  2. 同一秒 homed 被重启，那一轮被掐断（`context canceled`）
  3. 18:59:45 新进程起来，`deliveredMails` 是空的
  4. 心跳报 `pending_mails: 1`（第一轮没跑完 → read_inbox 没执行 → 仍未读）
     → catchUp 注入第二次

**不能只记「投过没有」**：那会把「重复」换成「丢件」—— 第 2 步里发件人没收到
回信，而记录说「已投过」→ 永远跳过。丢件比重复严重，重复至少人能看出来。

新增 `ledger.go`：JSONL 账本记两个状态。`completed` 才跳过；`delivered` 但未
`completed` 的仍然重投，但提示词前面插一段说明「上一轮被中断，别把同一件事做
两次」。落在 SDK 的 `Settings().DataDir()`；拿不到时退回 key 文件目录；目录不可
写时退化为纯内存（不比修复前差，也不该让插件起不来）。

- 判定与记录在同一把锁里：SSE 与 catchUp 两个 goroutine 的竞态
- 每行写完 fsync：这个文件的全部意义就是「进程死了之后还算数」
- 坏行跳过而不是报错退出（崩溃时最后一行可能写残）→ 那封退化为重投，安全
- 14 天保留期；过期过半时「临时文件 + rename」压实
- `shortID()` 替代 `id[:8]`：日志不该有能力 panic 掉投递协程

`ledger_test.go` +14 例，含两组负向对照（只记「投过」→ 丢件用例失败；不读账本
→ 跨进程用例失败）。

## 契约文档

`B-7.7`（MUST）：子进程形式的插件去重必须落盘且区分「投过」与「跑完」，含事故
时序、两状态表、何时标 completed。已知取舍那节标注投递账本是唯一必须落盘的状态。
验收清单加「模型跑到一半重启宿主」一项。

## 生产验证

- pi 三封 → 三条会话：三个 worker PID 并存，回信「收到 1/2/3」各落自己线索
- pi 同一会话两封：严格串行（收到A 19:26:39 → 收到B 19:26:48，全程单 worker）
- pi 主进程事件循环阻塞 1ms（旧版单进程 open 23MB 一次就 118ms）
- homeagent 正常一封：账本 `c:false` → `c:true`，一封回信
- homeagent 处理中重启：日志「上一轮被中断，带说明重投」，**只有一封 Re:**
- homeagent 再次重启：账本 2 条 completed，不再投递，会话邮件数不变
- gateway 7 包 / web 176+26 / pi 269 / dsh 219 / opencode 201 / homeagent 14
 2026-09-04 20:33:44 +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
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