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/test/workspace.test.mjs

@@ -13,14 +13,16 @@ import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir, homedir } from 'node:os';
 import { join } from 'node:path';
-import { resolveWorkspaceCwd, ensureCwd } from '../lib/workspace.js';
+import { resolveWorkspaceCwd, ensureCwd, mailSessionFallback } from '../lib/workspace.js';
 
-const fallbackOf = key => join(homedir(), '.dsh', 'mail-sessions', key);
+// 兜底目录现在由调用方给（各平台不同）。DSH 用 mailSessionFallback，
+// opencode 用插件启动时的 directory。
+const fallbackOf = key => mailSessionFallback(key);
 
 test('存在的绝对路径直接用作 cwd', () => {
   const dir = mkdtempSync(join(tmpdir(), 'ws-test-'));
   try {
-    const got = resolveWorkspaceCwd(dir, 'mail-1');
+    const got = resolveWorkspaceCwd(dir, fallbackOf('mail-1'));
     assert.equal(got.cwd, dir);
     assert.equal(got.grouped, true);
   } finally {
@@ -31,8 +33,8 @@ test('存在的绝对路径直接用作 cwd', () => {
 test('不变量：同一 path 的多封邮件得到同一个 cwd（这才能同组）', () => {
   const dir = mkdtempSync(join(tmpdir(), 'ws-test-'));
   try {
-    const a = resolveWorkspaceCwd(dir, 'mail-aaa');
-    const b = resolveWorkspaceCwd(dir, 'mail-bbb');
+    const a = resolveWorkspaceCwd(dir, fallbackOf('mail-aaa'));
+    const b = resolveWorkspaceCwd(dir, fallbackOf('mail-bbb'));
     assert.equal(a.cwd, b.cwd, 'fallbackKey 不同却应得到同一个 cwd');
   } finally {
     rmSync(dir, { recursive: true, force: true });
@@ -40,14 +42,14 @@ test('不变量：同一 path 的多封邮件得到同一个 cwd（这才能同
 });
 
 test('path 为空时回退到兜底目录', () => {
-  const got = resolveWorkspaceCwd('', 'mail-2');
+  const got = resolveWorkspaceCwd('', fallbackOf('mail-2'));
   assert.equal(got.cwd, fallbackOf('mail-2'));
   assert.equal(got.grouped, false);
 });
 
 test('path 缺失/非字符串时回退', () => {
   for (const v of [undefined, null, 42, {}]) {
-    const got = resolveWorkspaceCwd(v, 'mail-3');
+    const got = resolveWorkspaceCwd(v, fallbackOf('mail-3'));
     assert.equal(got.grouped, false);
     assert.equal(got.cwd, fallbackOf('mail-3'));
   }
@@ -56,7 +58,7 @@ test('path 缺失/非字符串时回退', () => {
 test('不变量：不存在的目录不创建，回退到兜底', () => {
   // 一个笔误（/home/porgram/x）不该在磁盘上落下真目录 ——
   // Agent 会在里面一无所获地干活，比明确回退更难排查。
-  const got = resolveWorkspaceCwd('/nonexistent/path/xyz-should-not-exist', 'mail-4');
+  const got = resolveWorkspaceCwd('/nonexistent/path/xyz-should-not-exist', fallbackOf('mail-4'));
   assert.equal(got.grouped, false);
   assert.equal(got.cwd, fallbackOf('mail-4'));
 });
@@ -65,7 +67,7 @@ test('不变量：相对路径被拒绝', () => {
   // cwd 的相对基准是 harness 进程的启动目录，systemd 下通常是 /，
   // 那是个与邮件语义完全无关的量。
   for (const rel of ['relative/path', './x', '../y', 'src']) {
-    const got = resolveWorkspaceCwd(rel, 'mail-5');
+    const got = resolveWorkspaceCwd(rel, fallbackOf('mail-5'));
     assert.equal(got.grouped, false, `${rel} 不该被当作工作目录`);
   }
 });
@@ -75,7 +77,7 @@ test('指向文件而非目录时回退', () => {
   const file = join(dir, 'a-file');
   writeFileSync(file, 'x');
   try {
-    const got = resolveWorkspaceCwd(file, 'mail-6');
+    const got = resolveWorkspaceCwd(file, fallbackOf('mail-6'));
     assert.equal(got.grouped, false);
   } finally {
     rmSync(dir, { recursive: true, force: true });
@@ -85,7 +87,7 @@ test('指向文件而非目录时回退', () => {
 test('两端空白被修掉', () => {
   const dir = mkdtempSync(join(tmpdir(), 'ws-test-'));
   try {
-    const got = resolveWorkspaceCwd(`  ${dir}  `, 'mail-7');
+    const got = resolveWorkspaceCwd(`  ${dir}  `, fallbackOf('mail-7'));
     assert.equal(got.cwd, dir);
     assert.equal(got.grouped, true);
   } finally {
@@ -99,14 +101,28 @@ test('ensureCwd 只建兜底目录，不碰寻址指定的目录', () => {
     const target = join(base, 'made-by-ensure');
     ensureCwd(target, false);
     // 建出来了
-    const got = resolveWorkspaceCwd(target, 'x');
+    const got = resolveWorkspaceCwd(target, '');
     assert.equal(got.grouped, true, 'ensureCwd 应已创建该目录');
 
     // grouped=true 时不该创建（那种目录本来就存在）
     const never = join(base, 'should-not-exist');
     ensureCwd(never, true);
-    assert.equal(resolveWorkspaceCwd(never, 'x').grouped, false);
+    assert.equal(resolveWorkspaceCwd(never, '').grouped, false);
   } finally {
     rmSync(base, { recursive: true, force: true });
   }
 });
+
+test('兜底为空串时返回空 cwd（交给平台自己决定）', () => {
+  // opencode 没配 directory 时就是这种情况：session.create 不带 query.directory，
+  // 由平台按自己的默认规则选目录。比硬塞一个我们猜的路径好。
+  const got = resolveWorkspaceCwd('', '');
+  assert.equal(got.cwd, '');
+  assert.equal(got.grouped, false);
+});
+
+test('mailSessionFallback 同一 key 稳定、不同 key 不同', () => {
+  assert.equal(mailSessionFallback('a'), mailSessionFallback('a'));
+  assert.notEqual(mailSessionFallback('a'), mailSessionFallback('b'));
+  assert.match(mailSessionFallback('a'), /mail-sessions/);
+});