feat(zcode): AgentMail 的 ZCode 插件 —— MCP 工具面 + 官方宿主启动验证
ZCode 用插件扩展能力（.zcode-plugin/plugin.json 声明 skills/commands/hooks/
mcpServers），所以适配它的正确形状是**插件**而不是又一个独立桥进程。
本提交是第一步：把 AgentMail 的工具面做成 MCP 服务器。
协议层（lib/mcp-rpc.mjs）手写，不引 @modelcontextprotocol/sdk：
协议面只有 initialize / notifications/initialized / tools/list / tools/call，
手写可省掉一条构建链与 1MB 打包产物（与 pi/opencode/dsh 三桥零运行时依赖的
取向一致），并让这一层成为可穷举的纯函数。分帧照官方插件产物实测确认是
换行分隔 JSON（Content-Length 出现 0 次，StdioServerTransport + split("\n")）。
工具面（lib/tools.mjs）与另三个桥**同名同参**，渲染走共用的
addressing/inbox-format/discovery（逐字节同源，已纳入 check-shared-libs.sh）。
测试里有一条断言直接拿 pi 桥的工具名做对照：少一个就让某平台行为与其它平台不同，
那种问题只在单平台复现，排查代价最高。
两处按真实缺陷定的行为：
- 工具失败回 result+isError 而非 JSON-RPC error —— 后者会让模型看不到失败原因，
只能重试（opencode 连试 6 次发不出附件正是这个后果）
- attachment_ids 声明放宽为 anyOf 数组/字符串并在桥侧归一 —— 模型常写成
JSON 字符串，服务端严格解码会拒（同样来自 opencode 那次失败）
入口 mcp/server.mjs 修掉一个真实缺陷：stdin 关闭即 process.exit 会杀掉在途请求，
表现为「协议全对但访问网关的调用完全没有响应」。现按在途计数 drain，
且把 stdout 写入也计入，避免最后一条响应卡在缓冲区。
顺带修 check-shared-libs.sh 的一个既有假绿：本机 PATH 上的 diff 是鸿蒙 SDK
工具链的 diff，不认 -q 且对不同的文件仍返回 0 —— 于是该检查器**一直是永真输出**。
改用 cmp -s，并加自检（判据本身必须先被证明能发现差异）。反向验证：
让 zcode 或 pi 的共用模块分叉，检查器都正确报错并返回 1。
验证：
- 单元 33 项 + 继承共用测试 87 项 = 120/120
- `zcode plugins list` → agentmail@inline [enabled]，mcp: plugin:agentmail:agentmail
- 经官方 `node zcode.cjs __zcode-plugin-host <server.mjs>` 启动 → 握手与 tools/list 正常
- 真实网关调用：以 zcode 身份 read_inbox / suggest_address / list_contacts 均返回
This commit is contained in:
393
plugins/zcode-mail-bridge/lib/tools.mjs
Normal file
393
plugins/zcode-mail-bridge/lib/tools.mjs
Normal file
@ -0,0 +1,393 @@
|
||||
/**
|
||||
* 暴露给 ZCode 模型的 AgentMail 工具。
|
||||
*
|
||||
* # 为什么工具集与另三个桥完全相同
|
||||
*
|
||||
* 同一件事在不同平台上应该有同一种做法。工具名（`read_inbox` / `send_mail` /
|
||||
* `download_attachment` …）、参数名、以及**渲染文本**都对齐 pi / dsh / opencode：
|
||||
* 渲染走 `lib/inbox-format.js` 与 `lib/discovery.js`（逐字节同源），
|
||||
* 所以模型在任一平台上看到的收件箱是同一个样子。
|
||||
*
|
||||
* 一旦这里少一个参数或换一种说法，就会出现「某个平台上模型不会回信」这类
|
||||
* 只在单一平台复现的问题 —— 而排查时最费时间的正是「它到底和别的平台哪里不一样」。
|
||||
*
|
||||
* # 与平台无关
|
||||
*
|
||||
* 本模块不认识 MCP，也不认识 ZCode：它只是一组
|
||||
* `{name, description, inputSchema, run(args) -> string}`。
|
||||
* 协议那层在 lib/mcp-rpc.mjs，入口在 mcp/server.mjs。
|
||||
*/
|
||||
|
||||
import {
|
||||
renderInbox,
|
||||
renderMail,
|
||||
idsToMarkRead,
|
||||
formatSize,
|
||||
DEFAULT_INBOX_STATUS,
|
||||
DEFAULT_INBOX_LIMIT
|
||||
} from './inbox-format.js';
|
||||
import {
|
||||
renderNameSuggestions,
|
||||
renderPathSuggestions,
|
||||
renderSessionSuggestions,
|
||||
renderParticipants,
|
||||
renderContacts,
|
||||
renderThread
|
||||
} from './discovery.js';
|
||||
import { normalizeAttachmentIDs } from './attachment-ids.js';
|
||||
import { uploadLocalFile, downloadToFile } from './gateway.mjs';
|
||||
|
||||
/** 正文在列表里的截断长度（与另三端一致）。 */
|
||||
const BODY_LIMIT = 200;
|
||||
|
||||
const str = (v, fallback = '') => (typeof v === 'string' ? v : fallback);
|
||||
const obj = v => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
|
||||
|
||||
/**
|
||||
* 构造工具集。
|
||||
*
|
||||
* @param {{client: import('./gateway.mjs').GatewayClient, agentName: string}} deps
|
||||
*/
|
||||
export function buildTools({ client, agentName }) {
|
||||
/**
|
||||
* 每次调用前校验配置。缺密钥时在此明确报错 ——
|
||||
* 否则模型看到的是一个 401，而它会去重试而不是告诉人「插件没配密钥」。
|
||||
*/
|
||||
const guard = () => {
|
||||
const missing = client.checkConfig();
|
||||
if (missing.length) {
|
||||
throw new Error(
|
||||
`AgentMail 未配置完成：缺少 ${missing.join('、')}。` +
|
||||
`请在 ZCode 的插件设置里填写，或为 ZCode 进程设置同名环境变量。`
|
||||
);
|
||||
}
|
||||
};
|
||||
|
||||
const tools = [];
|
||||
|
||||
// ─── 读 ────────────────────────────────────────────────────────
|
||||
tools.push({
|
||||
name: 'read_inbox',
|
||||
description:
|
||||
'查阅收件箱中的邮件。收到新邮件通知后应立即调用此工具。' +
|
||||
'每封含 mail_id、发件人、主题、正文与附件清单（带 attachment_id）。',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
status: { type: 'string', description: '过滤条件 unread|all，默认 unread' },
|
||||
limit: { type: 'number', description: '返回数量，默认 5' }
|
||||
}
|
||||
},
|
||||
async run(args) {
|
||||
guard();
|
||||
const a = obj(args);
|
||||
const status = str(a.status) || DEFAULT_INBOX_STATUS;
|
||||
const limit = Number.isFinite(a.limit) ? a.limit : DEFAULT_INBOX_LIMIT;
|
||||
const { mails } = await client.get(
|
||||
`/mail/inbox?status=${encodeURIComponent(status)}&limit=${limit}`
|
||||
);
|
||||
const listed = renderInbox(mails, BODY_LIMIT, agentName);
|
||||
|
||||
const ids = idsToMarkRead(a.status, mails);
|
||||
if (ids.length) {
|
||||
// 标记失败不该让读取失败：正文已经取到了，代价只是下次重复看到。
|
||||
client.post('/mail/read', { mail_ids: ids }).catch(() => {});
|
||||
}
|
||||
return listed;
|
||||
}
|
||||
});
|
||||
|
||||
tools.push({
|
||||
name: 'read_mail',
|
||||
description: '读取一封邮件的完整正文、附件清单与可投递地址（mail_id 从 read_inbox 获得）。',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: { mail_id: { type: 'string', description: '要读哪封' } },
|
||||
required: ['mail_id']
|
||||
},
|
||||
async run(args) {
|
||||
guard();
|
||||
const id = str(obj(args).mail_id);
|
||||
if (!id) throw new Error('缺少 mail_id');
|
||||
const data = await client.get(`/agent/mail/${encodeURIComponent(id)}?body_limit=0`);
|
||||
const mail = data?.mail || data;
|
||||
const lines = [renderMail(mail, 0, agentName)];
|
||||
if (Array.isArray(data?.participants) && data.participants.length) {
|
||||
lines.push('', renderParticipants(data));
|
||||
}
|
||||
if (data?.reply_address) {
|
||||
lines.push('', `回信给发件人用 ${data.reply_address}，或传 reply_to=${id}。`);
|
||||
}
|
||||
return lines.join('\n');
|
||||
}
|
||||
});
|
||||
|
||||
tools.push({
|
||||
name: 'read_thread',
|
||||
description: '查看一封邮件所在线索的完整往来（谁回了谁、谁还没回）。多方协作时用它避免重复提问。',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
mail_id: { type: 'string', description: '线索中任一封邮件的 ID' },
|
||||
offset: { type: 'number', description: '分页偏移，续取时传上次返回的 next_offset' }
|
||||
},
|
||||
required: ['mail_id']
|
||||
},
|
||||
async run(args) {
|
||||
guard();
|
||||
const a = obj(args);
|
||||
const id = str(a.mail_id);
|
||||
if (!id) throw new Error('缺少 mail_id');
|
||||
const qs = Number.isFinite(a.offset) ? `?offset=${a.offset}` : '';
|
||||
const data = await client.get(`/agent/mail/${encodeURIComponent(id)}/thread${qs}`);
|
||||
return renderThread(data, agentName);
|
||||
}
|
||||
});
|
||||
|
||||
// ─── 写 ────────────────────────────────────────────────────────
|
||||
tools.push({
|
||||
name: 'send_mail',
|
||||
description:
|
||||
'发送邮件。三维地址 name@path.session：省略 session 投递到默认会话，' +
|
||||
'.new 强制新建，.具体别名 必须已存在。回复来信请传 reply_to。',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
to: { type: 'string', description: '收件人三维地址，如 admin@/home/program/x' },
|
||||
subject: { type: 'string', description: '邮件主题' },
|
||||
body: { type: 'string', description: '邮件正文（Markdown）' },
|
||||
cc: { type: 'string', description: '抄送，逗号分隔多个三维地址' },
|
||||
reply_to: { type: 'string', description: '回复某封邮件时传其 mail_id' },
|
||||
session_alias: { type: 'string', description: '给新会话命名（仅 .new 时生效）' },
|
||||
attachment_ids: {
|
||||
// 声明成「数组或字符串」而不是纯数组：
|
||||
// 模型常把数组写成 JSON 字符串（`"[\"id\"]"`），
|
||||
// opencode 上就是这样连试 6 次失败、最后放弃整个任务。
|
||||
// 声明放宽 + 下面归一，两条一起才拦得住。
|
||||
description: '附件 ID 列表（先用 upload_attachment 取得）',
|
||||
anyOf: [
|
||||
{ type: 'array', items: { type: 'string' } },
|
||||
{ type: 'string', description: '单个 ID，或形如 ["a","b"] 的 JSON 数组字符串' }
|
||||
]
|
||||
},
|
||||
max_rounds: { type: 'number', description: '给这条新会话设定往返预算（仅新建时有效）' }
|
||||
},
|
||||
required: ['to', 'subject', 'body']
|
||||
},
|
||||
async run(args) {
|
||||
guard();
|
||||
const a = obj(args);
|
||||
const to = str(a.to);
|
||||
const subject = str(a.subject);
|
||||
const body = str(a.body);
|
||||
if (!to || !subject || !body) throw new Error('缺少必填字段：to, subject, body');
|
||||
const payload = { to, subject, body };
|
||||
if (str(a.cc)) payload.cc = str(a.cc);
|
||||
if (str(a.reply_to)) payload.reply_to = str(a.reply_to);
|
||||
if (str(a.session_alias)) payload.session_alias = str(a.session_alias);
|
||||
if (Number.isFinite(a.max_rounds)) payload.max_rounds = a.max_rounds;
|
||||
const ids = normalizeAttachmentIDs(a.attachment_ids);
|
||||
if (ids.length) payload.attachment_ids = ids;
|
||||
|
||||
const result = await client.post('/mail/send', payload);
|
||||
const parts = [`邮件已发送（ID: ${result?.mail_id ?? '?'}`];
|
||||
if (result?.session_id) parts.push(`，会话: ${result.session_id}`);
|
||||
if (result?.session_alias) parts.push(`，别名: ${result.session_alias}`);
|
||||
parts.push('）。');
|
||||
if (result?.budget_remaining !== undefined) {
|
||||
parts.push(`本任务剩余往返：${result.budget_remaining}。`);
|
||||
}
|
||||
return parts.join('');
|
||||
}
|
||||
});
|
||||
|
||||
tools.push({
|
||||
name: 'forward_mail',
|
||||
description:
|
||||
'转发一封邮件给新的收件人（自动引用原文与附件）。与回复不同：回复落回原会话，转发按目标地址另行定位会话。',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
mail_id: { type: 'string', description: '要转发的邮件 ID' },
|
||||
to: { type: 'string', description: '新收件人的三维地址' },
|
||||
comment: { type: 'string', description: '转发说明，置于引用原文之前' }
|
||||
},
|
||||
required: ['mail_id', 'to']
|
||||
},
|
||||
async run(args) {
|
||||
guard();
|
||||
const a = obj(args);
|
||||
if (!str(a.mail_id) || !str(a.to)) throw new Error('缺少 mail_id 或 to');
|
||||
const result = await client.post(
|
||||
`/mail/${encodeURIComponent(str(a.mail_id))}/forward`,
|
||||
{ to: str(a.to), comment: str(a.comment) }
|
||||
);
|
||||
return `已转发（新邮件 ID: ${result?.mail_id ?? '?'}，会话: ${result?.session_id ?? '?'}）。`;
|
||||
}
|
||||
});
|
||||
|
||||
// ─── 附件 ──────────────────────────────────────────────────────
|
||||
tools.push({
|
||||
name: 'upload_attachment',
|
||||
description:
|
||||
'上传本地文件作为邮件附件，返回 attachment_id。' +
|
||||
'拿到 id 后必须在 send_mail 的 attachment_ids 里带上，附件才会随邮件发出。',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: { file_path: { type: 'string', description: '本地文件绝对路径' } },
|
||||
required: ['file_path']
|
||||
},
|
||||
async run(args) {
|
||||
guard();
|
||||
const p = str(obj(args).file_path);
|
||||
if (!p) throw new Error('缺少 file_path');
|
||||
const a = await uploadLocalFile(client, p);
|
||||
return (
|
||||
`已上传 ${a.filename}（${formatSize(a.size_bytes)}）。attachment_id: ${a.attachment_id}\n` +
|
||||
`在 send_mail 的 attachment_ids 里带上这个 id 才会随邮件发出。`
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
tools.push({
|
||||
name: 'download_attachment',
|
||||
description: '下载邮件附件到本地文件。attachment_id 从 read_inbox 的附件清单里取。',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
attachment_id: { type: 'string', description: '附件 ID' },
|
||||
save_path: { type: 'string', description: '保存到的本地绝对路径' }
|
||||
},
|
||||
required: ['attachment_id', 'save_path']
|
||||
},
|
||||
async run(args) {
|
||||
guard();
|
||||
const a = obj(args);
|
||||
const id = str(a.attachment_id);
|
||||
const save = str(a.save_path);
|
||||
if (!id || !save) throw new Error('缺少 attachment_id 或 save_path');
|
||||
const size = await downloadToFile(client, id, save);
|
||||
return `已保存到 ${save}（${formatSize(size)}）`;
|
||||
}
|
||||
});
|
||||
|
||||
// ─── 寻址发现 ──────────────────────────────────────────────────
|
||||
tools.push({
|
||||
name: 'suggest_address',
|
||||
description:
|
||||
'查询可用的收件人地址，用于精准发信。不带参数给候选收件人名；带 name 给它可用的' +
|
||||
'工作目录；name+path 都带则给该目录下可续谈的会话与现成地址。',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
name: { type: 'string', description: '收件人名，如 pi / admin' },
|
||||
path: { type: 'string', description: '工作目录绝对路径' }
|
||||
}
|
||||
},
|
||||
async run(args) {
|
||||
guard();
|
||||
const a = obj(args);
|
||||
const name = str(a.name);
|
||||
const path = str(a.path);
|
||||
const qs = new URLSearchParams();
|
||||
if (name) qs.set('name', name);
|
||||
if (path) qs.set('path', path);
|
||||
const data = await client.get(`/agent/contacts/suggest?${qs.toString()}`);
|
||||
if (!name) return renderNameSuggestions(data?.names || data?.suggestions || []);
|
||||
if (!path) return renderPathSuggestions(data?.paths || [], name);
|
||||
return renderSessionSuggestions(data, name, path);
|
||||
}
|
||||
});
|
||||
|
||||
tools.push({
|
||||
name: 'list_contacts',
|
||||
description: '列出自己参与过的全部会话及各自的可投递地址、未读数、剩余往返预算。',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: { limit: { type: 'number', description: '最多列出多少条，默认 20' } }
|
||||
},
|
||||
async run(args) {
|
||||
guard();
|
||||
const limit = Number.isFinite(obj(args).limit) ? obj(args).limit : 20;
|
||||
const data = await client.get(`/agent/contacts?limit=${limit}`);
|
||||
return renderContacts(data, limit);
|
||||
}
|
||||
});
|
||||
|
||||
tools.push({
|
||||
name: 'session_participants',
|
||||
description:
|
||||
'列出某条会话的全部参与方（发件人/收件人/抄送方）及各自的可投递地址，并标出谁还没回应。' +
|
||||
'要回给抄收方或向第三方转达时先用它拿地址。',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: { session_id: { type: 'string', description: '会话 ID' } },
|
||||
required: ['session_id']
|
||||
},
|
||||
async run(args) {
|
||||
guard();
|
||||
const sid = str(obj(args).session_id);
|
||||
if (!sid) throw new Error('缺少 session_id');
|
||||
const data = await client.get(`/agent/sessions/${encodeURIComponent(sid)}/participants`);
|
||||
return renderParticipants(data);
|
||||
}
|
||||
});
|
||||
|
||||
// ─── 连接与登记 ────────────────────────────────────────────────
|
||||
tools.push({
|
||||
name: 'connect_to_server',
|
||||
description:
|
||||
'连接到 AgentMail Gateway：用当前配置的身份完成登记，并报告连通性。' +
|
||||
'首次安装或换了 Gateway 地址时调用。',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
gateway_url: { type: 'string', description: 'Gateway 地址；省略则用当前配置' },
|
||||
key_token: { type: 'string', description: '管理员签发的 Agent 密钥；省略则用当前配置' }
|
||||
}
|
||||
},
|
||||
async run(args) {
|
||||
// 刻意**不走 guard**：密钥没配好时，这个工具正是用来把问题说清楚的那个。
|
||||
// 若也直接抛「未配置完成」，模型只能转述一句抱怨，人不知道该去哪里填。
|
||||
const a = obj(args);
|
||||
const url = (str(a.gateway_url) || client.baseURL).replace(/\/+$/, '');
|
||||
const key = str(a.key_token) || client.agentKey;
|
||||
const missing = client.checkConfig();
|
||||
if (!agentName || (!key && !client.agentSecret)) {
|
||||
return (
|
||||
`AgentMail 尚未配置完成：缺少 ${missing.join('、')}。\n` +
|
||||
`请在 ZCode 的插件设置里填写，或为 ZCode 进程设置同名环境变量后重启。\n` +
|
||||
`（当前解析到的 Gateway 地址：${url}）`
|
||||
);
|
||||
}
|
||||
const res = await fetch(`${url}/api/v1/agent/register`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
...(key
|
||||
? { Authorization: `Bearer ${key}` }
|
||||
: { 'X-Agent-Secret': client.agentSecret })
|
||||
},
|
||||
body: JSON.stringify({ name: agentName, platform: 'zcode' })
|
||||
});
|
||||
const text = await res.text();
|
||||
let data = {};
|
||||
try {
|
||||
data = text ? JSON.parse(text) : {};
|
||||
} catch {
|
||||
data = {};
|
||||
}
|
||||
if (!res.ok) {
|
||||
return `登记失败（HTTP ${res.status}）：${data.error || data.message || text.slice(0, 200)}`;
|
||||
}
|
||||
return `已连接 ${url}，身份 ${agentName}（状态：${data.status || 'ok'}）。`;
|
||||
}
|
||||
});
|
||||
|
||||
return tools;
|
||||
}
|
||||
|
||||
/** 便捷：把工具集变成 `name -> tool` 的映射，供分发层使用。 */
|
||||
export function indexTools(tools) {
|
||||
return new Map(tools.map(t => [t.name, t]));
|
||||
}
|
||||
Reference in New Issue
Block a user