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 字节。
This commit is contained in:
@ -6,6 +6,14 @@ import { join, dirname, basename } from "node:path";
|
||||
// 自动转发去重的纯逻辑放在 lib/ 里：opencode 会把入口模块的每一个导出
|
||||
// 都当成插件工厂，入口文件多导出一个东西就会 "Plugin export is not a function"。
|
||||
import { snapshotOpencodeSessions } from "./lib/session-snapshot.js";
|
||||
import { resolveWorkspaceCwd } from "./lib/workspace.js";
|
||||
import {
|
||||
renderInbox,
|
||||
idsToMarkRead,
|
||||
formatSize,
|
||||
DEFAULT_INBOX_STATUS,
|
||||
DEFAULT_INBOX_LIMIT,
|
||||
} from "./lib/inbox-format.js";
|
||||
import {
|
||||
explicitSends,
|
||||
noteExplicitSend,
|
||||
@ -222,58 +230,26 @@ const readInboxTool = {
|
||||
limit: z.number().optional().describe("返回数量，默认 5"),
|
||||
},
|
||||
async execute(args) {
|
||||
const filter = args.filter || "unread";
|
||||
const limit = args.limit || 5;
|
||||
const filter = args.filter || DEFAULT_INBOX_STATUS;
|
||||
const limit = args.limit || DEFAULT_INBOX_LIMIT;
|
||||
const data = await apiGet(`/mail/inbox?status=${filter}&limit=${limit}`);
|
||||
if (!data.mails || data.mails.length === 0) return "收件箱为空。";
|
||||
const listed = data.mails.map((m) => {
|
||||
const lines = [
|
||||
`[${m.status}] ${m.from_name}: ${m.subject}`,
|
||||
`邮件 ID: ${m.mail_id}`,
|
||||
`会话: #${m.session_alias || "未命名"}`,
|
||||
];
|
||||
// 必须把 attachment_id 一起给出：不然模型知道「有附件」却无从下载
|
||||
if (m.attachments?.length) {
|
||||
lines.push(
|
||||
"附件: " +
|
||||
m.attachments
|
||||
.map(a => `${a.filename}（${formatSize(a.size_bytes)}, id=${a.attachment_id}）`)
|
||||
.join("、")
|
||||
);
|
||||
lines.push("下载附件请用 download_attachment 工具。");
|
||||
}
|
||||
lines.push(`内容: ${(m.body_preview || m.body || "").substring(0, 200)}`);
|
||||
return lines.join("\n");
|
||||
}).join("\n\n");
|
||||
|
||||
// 读过就标掉。不标的话下次拉收件箱还是这一批，
|
||||
// 处理过的信和新来的信混在一起，模型分不清哪封该回。
|
||||
//
|
||||
// 只标本次真正列出来的（而不是全部未读）：limit 之外的还没看过，
|
||||
// 一并标掉等于让它们凭空消失。
|
||||
if (args.filter !== "all") {
|
||||
const ids = data.mails.map(m => m.mail_id).filter(Boolean);
|
||||
if (ids.length) {
|
||||
// 标记失败不该让 read_inbox 失败 —— 正文已经取到了，
|
||||
// 代价只是下次会重复看到，比丢掉这次读取轻。
|
||||
apiPost("/mail/read", { mail_ids: ids }).catch(e =>
|
||||
console.error("[mail-bridge] 标记已读失败:", e?.message || e)
|
||||
);
|
||||
}
|
||||
// 渲染与已读策略放 lib/inbox-format.js：它们与平台 SDK 无关，
|
||||
// 各平台插件必须一致（见该文件里每条规则对应的错误行为）。
|
||||
const listed = renderInbox(data.mails);
|
||||
|
||||
const ids = idsToMarkRead(args.filter, data.mails);
|
||||
if (ids.length) {
|
||||
// 标记失败不该让 read_inbox 失败 —— 正文已经取到了，
|
||||
// 代价只是下次会重复看到，比丢掉这次读取轻。
|
||||
apiPost("/mail/read", { mail_ids: ids }).catch(e =>
|
||||
console.error("[mail-bridge] 标记已读失败:", e?.message || e)
|
||||
);
|
||||
}
|
||||
|
||||
return listed;
|
||||
},
|
||||
};
|
||||
|
||||
/** 人类可读的字节数，用于附件清单展示。 */
|
||||
function formatSize(n) {
|
||||
if (typeof n !== "number") return "?";
|
||||
if (n < 1024) return `${n} B`;
|
||||
if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
|
||||
return `${(n / 1024 / 1024).toFixed(1)} MB`;
|
||||
}
|
||||
|
||||
const uploadAttachmentTool = {
|
||||
description:
|
||||
"上传本地文件作为邮件附件，返回 attachment_id。" +
|
||||
@ -480,9 +456,14 @@ async function resolveSessionForMail(client, directory, data, kind) {
|
||||
// 三维地址 name@path.session 的 path 就是「希望它在哪儿干活」。用固定的
|
||||
// directory 会让所有邮件会话都挤在同一个目录里，与地址写的完全无关；
|
||||
// 而 opencode 按 directory 归属项目，写错了会话就归到别的项目下。
|
||||
const wantDir = typeof data.to_workspace === "string" && data.to_workspace.trim()
|
||||
? data.to_workspace.trim()
|
||||
: directory;
|
||||
//
|
||||
// 校验逻辑与 DSH 侧共用（lib/workspace.js）：目录不存在时不创建、
|
||||
// 拒绝相对路径。opencode 的兜底是插件启动时的 directory。
|
||||
const { cwd: wantDir, grouped } = resolveWorkspaceCwd(data.to_workspace, directory);
|
||||
if (!grouped && data.to_workspace) {
|
||||
console.error(
|
||||
`[mail-bridge] 工作目录 ${data.to_workspace} 不可用，回退到 ${wantDir || "(平台默认)"}`);
|
||||
}
|
||||
|
||||
// 故意不传 title：opencode 只在标题缺省时才让模型按首轮对话生成摘要标题，
|
||||
// 传了占位标题就等于掐掉平台自己的命名机制。标题稍后由 session.updated 事件回写。
|
||||
|
||||
Reference in New Issue
Block a user