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

plugins/dsh-mail-bridge/src/index.ts

@@ -28,7 +28,14 @@ import {
   modelTitle,
 } from '../lib/message.js';
 import { snapshotDshSessions, slugFromTitle } from '../lib/session-snapshot.js';
-import { resolveWorkspaceCwd, ensureCwd } from '../lib/workspace.js';
+import { resolveWorkspaceCwd, ensureCwd, mailSessionFallback } from '../lib/workspace.js';
+import {
+  renderInbox,
+  idsToMarkRead,
+  formatSize,
+  DEFAULT_INBOX_STATUS,
+  DEFAULT_INBOX_LIMIT,
+} from '../lib/inbox-format.js';
 
 // ─── 凭证管理 ───
 
@@ -320,7 +327,8 @@ export function apply(ctx: any, config: PluginConfig): void {
     // 之前这里硬拼 `~/.dsh/mail-sessions/mail-<uuid>` —— 每封邮件一个全新的空目录。
     // DSH 按 cwd 给会话分组，于是所有邮件会话既不属于任何项目、彼此也不同组，
     // 界面上全落进「未分组」。path 位本来就是「希望它在哪儿干活」。
-    const { cwd, grouped } = resolveWorkspaceCwd(data.to_workspace, sessionId);
+    const { cwd, grouped } = resolveWorkspaceCwd(
+      data.to_workspace, mailSessionFallback(sessionId));
     ensureCwd(cwd, grouped);
     if (!grouped && data.to_workspace) {
       ctx.logger.warn(
@@ -456,25 +464,35 @@ export function apply(ctx: any, config: PluginConfig): void {
     // read_inbox
     ctx.tools.register(defineTool({
       name: 'read_inbox',
-      description: '读取收件箱邮件列表。返回最新的邮件，每封含 mail_id、发件人、主题、正文、附件清单。',
+      description: '查阅收件箱中的邮件。收到新邮件通知后应立即调用此工具。每封含 mail_id、发件人、主题、正文与附件清单（带 attachment_id）。',
       parameters: {
-        status: { type: 'string', description: '过滤状态（all/unread/read）' },
-        limit: { type: 'number', description: '返回数量上限' },
+        status: { type: 'string', description: '过滤条件 unread|all，默认 unread' },
+        limit: { type: 'number', description: '返回数量，默认 5' },
       },
       output: {
         schema: { type: 'string' },
         render: (_args: any, value: string) => [{ type: 'text', text: value }],
       },
       async execute(args: any): Promise<string> {
+        const status = args.status || DEFAULT_INBOX_STATUS;
         const { mails } = await client.get(
-          `/mail/inbox?status=${args.status || 'all'}&limit=${args.limit || 20}`
+          `/mail/inbox?status=${status}&limit=${args.limit || DEFAULT_INBOX_LIMIT}`
         );
-        if (!mails?.length) return '收件箱为空。';
-        return mails.map((m: any) => {
-          const att = m.attachments?.length
-            ? ` [附件: ${m.attachments.map((a: any) => a.filename).join(', ')}]` : '';
-          return `- ID: ${m.mail_id} | ${m.from_name} | ${m.subject}${att}\n  ${m.body.slice(0, 200)}`;
-        }).join('\n');
+
+        // 渲染与已读策略放 lib/inbox-format.js：它们与平台 SDK 无关，
+        // 各平台插件必须一致（见该文件里每条规则对应的错误行为）。
+        const listed = renderInbox(mails);
+
+        // 读过就标掉，否则每次拉收件箱都重复捞同一批，
+        // 处理过的和新来的混在一起，模型分不清哪封该回。
+        const ids = idsToMarkRead(args.status, mails);
+        if (ids.length) {
+          // 标记失败不该让 read_inbox 失败：正文已经取到了，
+          // 代价只是下次重复看到，比丢掉这次读取轻。
+          client.post('/mail/read', { mail_ids: ids }).catch((e: any) =>
+            ctx.logger.error(`[dsh-mail-bridge] 标记已读失败: ${e?.message || e}`));
+        }
+        return listed;
       },
     }));
 
@@ -500,7 +518,7 @@ export function apply(ctx: any, config: PluginConfig): void {
         const json = await res.json() as any;
         if (!res.ok) throw new Error(json?.error || `HTTP ${res.status}`);
         const a = json.attachment;
-        return `已上传 ${a.filename}（${a.size_bytes} 字节）。attachment_id: ${a.attachment_id}`;
+        return `已上传 ${a.filename}（${formatSize(a.size_bytes)}）。attachment_id: ${a.attachment_id}`;
       },
     }));
 
@@ -523,7 +541,7 @@ export function apply(ctx: any, config: PluginConfig): void {
         if (!res.ok) throw new Error(`下载失败: HTTP ${res.status}`);
         const buf = Buffer.from(await res.arrayBuffer());
         await writeFile(args.save_path, buf);
-        return `已保存到 ${args.save_path}（${buf.length} 字节）`;
+        return `已保存到 ${args.save_path}（${formatSize(buf.length)}）`;
       },
     }));