JianFeeeee
7c9be9fd58
两次适配（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 字节。
78 lines
3.2 KiB
JavaScript
78 lines
3.2 KiB
JavaScript
/**
|
||
* 邮件寻址里的工作目录（三维地址 name@path.session 的 path 位）。
|
||
*
|
||
* 这个模块存在的理由是一次真实故障：插件建会话时用的 cwd 是自己拼的
|
||
* `~/.dsh/mail-sessions/mail-<uuid>` —— 每封邮件一个全新的空目录。
|
||
* DSH 与 opencode 都按 cwd 给会话分组，于是所有邮件会话既不属于任何项目、
|
||
* 彼此也不同组，界面上全落进「未分组」。
|
||
*
|
||
* path 位本来就是「希望它在哪儿干活」，插件只需照用。
|
||
*/
|
||
|
||
import { existsSync, mkdirSync, statSync } from 'node:fs';
|
||
import { homedir } from 'node:os';
|
||
import { isAbsolute, join, resolve } from 'node:path';
|
||
|
||
/**
|
||
* 校验寻址里的工作目录，不可用时返回调用方给的兜底。
|
||
*
|
||
* 决策顺序：
|
||
* 1. path 位是一个已存在的目录 → 直接用它（同 path 的多封邮件天然同组）
|
||
* 2. path 位非空但目录不存在 → **不创建**，返回兜底
|
||
* 3. path 位为空（地址写成 `dsh` 而不带 `@/path`）→ 兜底
|
||
*
|
||
* 为什么不给不存在的 path 建目录：那等于让一个笔误（`/home/porgram/x`）
|
||
* 在磁盘上落下一个真目录，而 Agent 会在里面一无所获地干活 ——
|
||
* 用户看到会话建起来了却什么都做不了，比明确落到兜底目录更难排查。
|
||
*
|
||
* 为什么拒绝相对路径：cwd 的相对基准是 harness 进程的启动目录，
|
||
* 那是个与邮件语义无关的量（systemd 下通常是 `/`）。
|
||
*
|
||
* 兜底由调用方给，因为各平台的兜底不同：opencode 有插件启动时的 directory
|
||
* 可用，DSH 没有、只能落到 `~/.dsh/mail-sessions/<会话>`（见 mailSessionFallback）。
|
||
*
|
||
* @param {string} workspace 事件里的 to_workspace
|
||
* @param {string} fallback 不可用时的兜底目录（可为空串 = 交给平台自己决定）
|
||
* @returns {{cwd: string, grouped: boolean}} grouped 为真表示落在了寻址指定的目录里
|
||
*/
|
||
export function resolveWorkspaceCwd(workspace, fallback) {
|
||
const raw = typeof workspace === 'string' ? workspace.trim() : '';
|
||
const fb = typeof fallback === 'string' ? fallback : '';
|
||
|
||
if (!raw || !isAbsolute(raw)) return { cwd: fb, grouped: false };
|
||
|
||
const abs = resolve(raw);
|
||
try {
|
||
if (existsSync(abs) && statSync(abs).isDirectory()) {
|
||
return { cwd: abs, grouped: true };
|
||
}
|
||
} catch {
|
||
// 权限不足等：当作不可用
|
||
}
|
||
return { cwd: fb, grouped: false };
|
||
}
|
||
|
||
/**
|
||
* 没有天然兜底的平台（DSH）用这个：`~/.dsh/mail-sessions/<会话 id>`。
|
||
* @param {string} sessionKey 会话标识
|
||
* @returns {string}
|
||
*/
|
||
export function mailSessionFallback(sessionKey) {
|
||
return join(homedir(), '.dsh', 'mail-sessions', String(sessionKey || 'default'));
|
||
}
|
||
|
||
/**
|
||
* 确保兜底目录存在。寻址指定的目录本来就存在（否则不会被选中），
|
||
* 只有兜底目录需要现建。
|
||
* @param {string} cwd resolveWorkspaceCwd 的结果
|
||
* @param {boolean} grouped 是否落在寻址指定的目录里
|
||
*/
|
||
export function ensureCwd(cwd, grouped) {
|
||
if (grouped || !cwd) return;
|
||
try {
|
||
mkdirSync(cwd, { recursive: true });
|
||
} catch {
|
||
// 建不出来就让 harness 自己报错，这里不该吞掉真实原因
|
||
}
|
||
}
|