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 字节。

docs/API.md

@@ -298,7 +298,7 @@ PUT              /admin/quotas/{name}      设默认预算 {default_rounds}
 
 ```
 POST /agent/register           注册（Bearer <agent_key> 或 body.secret）
-POST /agent/heartbeat          心跳，响应含 pending_mails 与 quota
+POST /agent/heartbeat          心跳，响应含 pending_mails 与 stats；可带平台会话快照
 POST /mail/send                发信（扣配额）
 GET  /mail/inbox               收件箱（含附件清单）
 POST /mail/read                批量标记已读（不给 mail_ids = 全部标掉）
@@ -312,6 +312,36 @@ POST /sessions/{id}/sync       回写平台侧生成的会话标题/slug
 发信与转发扣**本任务（会话）的往返预算**。
 只限制主动发信，不限制收信 —— 卡住收信只会让邮件凭空消失。
 
+### 心跳与平台会话快照
+
+```bash
+# 最简形式：保活
+curl -X POST {host}/api/v1/agent/heartbeat -H "Authorization: Bearer $AGENT_KEY"
+
+# 带平台会话快照（插件应当这样做）
+curl -X POST {host}/api/v1/agent/heartbeat -H "Authorization: Bearer $AGENT_KEY" \
+  -d '{"platform_sessions":[
+        {"platform_id":"ses_abc","workspace":"/home/program/agentmail",
+         "slug":"witty-planet","title":"重构导入路径",
+         "mail_driven":false,"updated_at":"2026-09-02T11:41:16.744Z"}
+      ]}'
+```
+
+**心跳不能省。** Gateway 靠 `last_seen` 判在线，不发心跳的 Agent 会被当成离线。
+间隔 30 秒。
+
+`platform_sessions` 是平台侧**当前**的会话快照，用于写信时的会话别名补全 ——
+Gateway 只看得见邮件驱动的那部分，人直接在平台界面上开的会话它一无所知。
+
+- **整表替换**：平台侧删掉的会话必须从候选里消失（session 位是三态语义，
+  指向不存在的会话会直接 404）
+- **省略该字段与传空数组语义不同**：拉不到列表时**省略**（保留服务端现有镜像）；
+  空数组的语义是「平台侧确实一条会话都没有」，会把镜像抹掉
+- 单次上限 200 条，按最近活跃排序后截断
+
+字段要求见 [插件适配指南](PLUGIN-GUIDE.md#四平台会话快照上报)（含 subagent 过滤、
+slug 去重等规则）。
+
 ### 标记已读
 
 ```bash
@@ -370,6 +400,24 @@ GET /events/stream
 
 事件类型：`connected`、`new_mail`、`permission_decision`、`session_update`、`session_archived`、`agent_online`。
 
+`new_mail` 的 payload：
+
+```json
+{
+  "mail_id": "...", "session_id": "...", "from_name": "admin",
+  "subject": "...", "mail_type": "normal", "role": "to",
+  "to_workspace": "/home/program/agentmail"
+}
+```
+
+`to_workspace` 是**收件方那个地址的 path 位**（抄送方拿到的是自己那个地址的，
+不是主收件人的）。插件应当用它作为会话的工作目录 —— 自己拼一个临时目录会让
+平台按 cwd 分组时把所有邮件会话归进「未分组」。
+
+`permission_decision` 的 payload 含 `relay_key`（上游权限询问的 id）与
+`session_id`：前者让插件对上平台侧那条待决询问，后者是插件重启丢了内存映射时
+的兜底 —— 那种情况下决策会被当作一封普通通知投进会话。
+
 按收件人分流：Agent 凭证订阅 Agent 通道，用户凭证订阅该用户的通道。
 不能只报 `X-Agent-Name` 而不给凭证 —— 那等于任何人报个名字就能读走别人的新邮件通知。