@voko/lite 0.3.1

package/src/mcp/tools.js

@@ -0,0 +1,1367 @@
+/**
+ * VOKO MCP — 24 个工具处理器
+ *
+ * 零 Electron 依赖，所有外部依赖通过 context (cx) 注入。
+ * 全部通过 createToolHandlers(cx) 工厂函数创建。
+ */
+
+const ENDPOINTS = require('../endpoints.json');
+const { buildInvitationPrompt, buildEmailSubject, buildEmailContent } = require('../core/invitation');
+
+/**
+ * 归一化文件消息 content。
+ * 支持：JSON 字符串 / 普通对象 / 纯 URL 字符串。
+ * 纯 URL 会自动提取文件名并补全 {url, name, size, type}。
+ */
+function normalizeFileContent(content) {
+  // 1. 如果是对象，先序列化
+  if (content && typeof content === 'object') {
+    return JSON.stringify(content);
+  }
+  if (typeof content !== 'string') {
+    return JSON.stringify({ url: String(content || ''), name: '', size: 0, type: '' });
+  }
+
+  const trimmed = content.trim();
+
+  // 2. 尝试解析 JSON
+  if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+    try {
+      const obj = JSON.parse(trimmed);
+      const url = obj.url || obj.fileUrl || '';
+      const name = obj.name || obj.fileName || extractFileNameFromUrl(url) || '';
+      const size = typeof obj.size === 'number' ? obj.size : (typeof obj.fileSize === 'number' ? obj.fileSize : 0);
+      const type = obj.type || obj.mimeType || '';
+      return JSON.stringify({ url, name, size, type });
+    } catch (_) {
+      // 解析失败则按普通字符串/URL 处理
+    }
+  }
+
+  // 3. 纯 URL 或普通文本：包装成文件 JSON
+  const isUrl = /^https?:\/\//i.test(trimmed);
+  const url = isUrl ? trimmed : '';
+  const name = isUrl ? (extractFileNameFromUrl(trimmed) || '') : trimmed;
+  return JSON.stringify({ url, name, size: 0, type: '' });
+}
+
+function extractFileNameFromUrl(url) {
+  try {
+    const pathname = new URL(url).pathname;
+    const parts = pathname.split('/');
+    const last = parts[parts.length - 1];
+    return decodeURIComponent(last) || '';
+  } catch (_) {
+    return '';
+  }
+}
+
+/**
+ * 通过 HEAD 请求探测远程文件的 size 和 MIME type。
+ * 失败时返回 { size: 0, type: '' }，不影响发送。
+ */
+async function probeFileMetadata(url) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 8000);
+    const res = await fetch(url, { method: 'HEAD', signal: controller.signal, redirect: 'follow' });
+    clearTimeout(timeout);
+    if (!res.ok) return { size: 0, type: '' };
+    const length = res.headers.get('content-length');
+    const contentType = res.headers.get('content-type') || '';
+    const size = length ? parseInt(length, 10) : 0;
+    return { size: Number.isFinite(size) ? size : 0, type: contentType.split(';')[0].trim() };
+  } catch (_) {
+    return { size: 0, type: '' };
+  }
+}
+
+function createToolHandlers(cx) {
+  // cx: { db, query, exec, sendMessage, sendSystemMessage, startAgentWorker, stopAgentWorker,
+  //        getAgentStatus, registerCapabilities, searchCapabilities, updateAgentProfile, setAgentStatus,
+  //        publishAgent, unpublishAgent,
+  //        generateOSSSignature, agentRegistration,
+  //        getPaymentAuth, savePaymentOrder, getAgentImUid,
+  //        getOpenclawHandler, processPaymentOrder,
+  //        enqueueOwnerIntervention }
+
+  /** 格式化消息行 */
+  function fmtMsg(r) {
+    return {
+      id: r.id,
+      fromUid: r.from_uid,
+      toUid: r.to_uid,
+      content: r.content,
+      timestamp: r.timestamp,
+      messageSeq: r.message_seq,
+      isMe: r.is_me === 1,
+      contentType: r.content_type || 1,
+      agentId: r.agent_id || null,
+    };
+  }
+
+  return {
+
+    // ─── 1 & 2. 注册 ───
+
+    async register_agent(p) {
+      // Step 1：调后端发送邮箱验证码
+      const r = await cx.agentRegistration.sendCode({ email: p.email });
+      if (!r.success) {
+        return { success: false, error: r.error || r.data?.message || '发送验证码失败' };
+      }
+      return { success: true, message: '验证码已发送到邮箱' };
+    },
+
+    async verify_agent_email(p) {
+      // 预览模式：不传 agentId 也不传 agentName，只验码展示 Agent 列表
+      if (!p.agentId && !p.agentName) {
+        const r = await cx.agentRegistration.verifyCodePreview({ email: p.email, code: p.code });
+        if (!r.success) {
+          return { success: false, error: r.error || '验证码错误或已过期' };
+        }
+        const agents = r.agents || [];
+        const needChoice = r.userExists && agents.length > 0;
+        const result = { success: true, needChoice, userExists: r.userExists };
+        if (needChoice) {
+          result.agents = agents;
+          result.message = '该邮箱有如下Agent，请选择某个Agent或提供新的AgentName注册新Agent';
+        } else {
+          result.message = '该邮箱尚未注册VOKO，请为该Agent命名';
+        }
+        return result;
+      }
+
+      // 完整注册：调后端验证验证码
+      const v = await cx.agentRegistration.verifyCode({
+        email: p.email, code: p.code,
+        agentName: p.agentName,
+        agentId: p.agentId,
+      });
+      if (!v.success || !v.data) {
+        return { success: false, error: v.error || v.data?.message || '验证码无效或已过期' };
+      }
+
+      const data = v.data;
+      console.log('[verify_agent_email] 服务端返回:', JSON.stringify(data, null, 2));
+      const agentId = data.agents?.[0]?.agentId;
+      if (!agentId) {
+        return { success: false, error: '服务端未返回 agentId' };
+      }
+
+      const serverUrl = data.imServerUrl || ENDPOINTS.im.wsUrl;
+      const backendType = 'others';
+
+      const firstAgent = data.agents?.[0] || {};
+
+      // Step 2：写入 agents 表（注册，unpublished，不启动 worker）
+      const regRes = cx.agentRegistration.registerAgentInDb({
+        agentId,
+        uid: data.imUid,
+        token: data.imToken,
+        serverUrl,
+        ownerEmail: p.email,
+        backendType,
+        agentName: data.agentName,
+        did: data.did,
+        publicKey: data.publicKey,
+        privateKey: data.privateKey,
+        loginToken: data.loginToken,
+        paymentFeeRate: firstAgent.payment_fee_rate,
+        agentUsageFeeRate: firstAgent.agent_usage_fee_rate,
+      });
+      if (!regRes.success) {
+        return { success: false, error: regRes.error || '写入 agents 表失败' };
+      }
+
+      // Step 3：更新绑定字段
+      const upRes = cx.agentRegistration.updateAgentBinding({
+        agentId,
+        updates: {
+          did: data.did,
+          imUid: data.imUid,
+          imToken: data.imToken,
+          public_key: data.publicKey,
+          private_key: data.privateKey,
+          login_token: data.loginToken,
+          im_server_url: serverUrl,
+        },
+      });
+      if (upRes && !upRes.success) {
+        return { success: false, error: upRes.error || '更新绑定失败' };
+      }
+
+      // Step 4：启动 IM Worker
+      if (cx.startAgentWorker) {
+        cx.startAgentWorker(agentId, { uid: data.imUid, token: data.imToken, serverUrl, backendType: 'others' });
+      }
+
+      return { success: true, message: '注册成功', agentId, agentName: data.agentName };
+    },
+
+    // ─── 3. 编辑 Agent 基础信息 ───
+
+    async update_agent_profile(p) {
+      if (!cx.updateAgentProfile) {
+        return { success: false, error: '当前环境不支持更新 Agent 资料' };
+      }
+      // backendType 仅本地更新，不同步服务端
+      if (p.backendType) {
+        cx.exec(`UPDATE agents SET backend_type=?, updated_at=? WHERE agent_id=?`, [p.backendType, Date.now(), p.agentId]);
+      }
+
+      // 检查是否有需要同步服务端的字段
+      const serverFields = [p.name, p.description, p.short_description, p.category, p.tags, p.iconUrl, p.address, p.contact_phone];
+      if (serverFields.some(v => v !== undefined)) {
+        const result = await cx.updateAgentProfile({
+          db: cx.db,
+          agentId: p.agentId,
+          name: p.name,
+          description: p.description,
+          short_description: p.short_description,
+          category: p.category,
+          tags: p.tags,
+          icon_url: p.iconUrl,
+          address: p.address,
+          contact_phone: p.contact_phone,
+        });
+        return result;
+      }
+
+      return { success: true, message: '本地更新成功' };
+    },
+
+    // ─── 4. 设置 Agent 上下架 / 公开私有状态 ───
+
+    async set_agent_status(p) {
+      if (p.status === 1) {
+        if (!cx.publishAgent) {
+          return { success: false, error: '当前环境不支持发布 Agent' };
+        }
+        return cx.publishAgent({ agentId: p.agentId });
+      }
+      if (p.status === 0) {
+        if (!cx.unpublishAgent) {
+          return { success: false, error: '当前环境不支持下架 Agent' };
+        }
+        return cx.unpublishAgent({ agentId: p.agentId });
+      }
+      return { success: false, error: 'status 必须为 0（下架）或 1（上架）' };
+    },
+
+    // ─── 5. 状态 ───
+
+    async get_status(p) {
+      const agentStatus = cx.getAgentStatus ? cx.getAgentStatus(p.agentId) : null;
+      const warnings = global.__latestWarnings || [];
+      const uptime = process.uptime();
+      const version = cx.version || 'unknown';
+      // others 类型的 agent 无后端连接检测，去掉 backendConnected
+      if (agentStatus && agentStatus.backend_type !== 'openclaw' && agentStatus.backend_type !== 'hermes') {
+        delete agentStatus.backendConnected;
+      }
+      return { agent: agentStatus, warnings, uptime, version };
+    },
+
+    // ─── 5b. 查询 Agent 资料 ───
+
+    async get_agent_profile(p) {
+      const row = cx.query(`SELECT * FROM agents WHERE agent_id=?`, [p.agentId]);
+      if (!row || row.length === 0) {
+        return { success: false, error: 'Agent 不存在' };
+      }
+      const a = row[0];
+      let tags = null;
+      try { if (a.tags) tags = JSON.parse(a.tags); } catch { tags = a.tags; }
+      let ability = null;
+      try { if (a.ability) ability = JSON.parse(a.ability); } catch { ability = a.ability; }
+
+      // 计费模式
+      let pricing = { pricingModel: 'free', price: null, durationMinutes: null, enabled: true };
+      try {
+        const pricingRow = cx.query(`SELECT pricing_model, price, duration_minutes, enabled FROM agent_pricing WHERE agent_id=?`, [p.agentId])[0];
+        if (pricingRow) pricing = { pricingModel: pricingRow.pricing_model, price: pricingRow.price, durationMinutes: pricingRow.duration_minutes, enabled: pricingRow.enabled === 1 };
+      } catch (_) {}
+
+      // 支付认证（是否已配置）
+      let paymentAuthId = null;
+      let paymentConfigured = false;
+      try {
+        const auth = cx.query(`SELECT id FROM payment_auth WHERE id=?`, [a.payment_auth_id])[0];
+        paymentAuthId = a.payment_auth_id || null;
+        paymentConfigured = !!auth;
+      } catch (_) {}
+
+      return {
+        success: true,
+        data: {
+          agentId: a.agent_id,
+          agentName: a.agent_name,
+          description: a.description,
+          shortDescription: a.short_description,
+          category: a.category,
+          categoryLabel: a.category_label,
+          tags,
+          iconUrl: a.icon_url,
+          address: a.address,
+          contactPhone: a.contact_phone,
+          backendType: a.backend_type,
+          publishStatus: a.publish_status,
+          accessMode: a.access_mode,
+          did: a.did,
+          imUid: a.imUid,
+          ownerEmail: a.owner_email,
+          createdAt: a.created_at,
+          updatedAt: a.updated_at,
+          ability,
+          paymentFeeRate: a.payment_fee_rate,
+          agentUsageFeeRate: a.agent_usage_fee_rate,
+          paymentConfigured,
+          pricing,
+        },
+        fieldDescriptions: {
+          agentId: 'Agent 唯一标识',
+          agentName: 'Agent 显示名称（可修改）',
+          description: 'Agent详细描述',
+          shortDescription: 'Agent一句话简短介绍',
+          category: '分类标识（如 travel/finance/health_fitness/education 等）',
+          categoryLabel: '分类中文名称',
+          tags: '标签列表',
+          iconUrl: '头像图片链接',
+          backendType: 'Agent 类型（openclaw, hermes, others=其他）',
+          publishStatus: '发布状态（published=已上架, unpublished=未上架）',
+          paymentFeeRate: '支付手续费率（如 0.006 = 0.6%）',
+          agentUsageFeeRate: '按时计费模式下，平台抽取的佣金比例',
+          paymentConfigured: '是否已配置支付认证',
+          pricing: '订阅方式：pricingModel=free免费/timed按时订阅，price=价格，durationMinutes=时长（分钟），enabled=是否启用',
+          accessMode: '访问模式（public=公开, private=私密/白名单）',
+          address: '地址',
+          contactPhone: '联系电话',
+          did: 'DID标识',
+          imUid: 'IM 系统用户 ID',
+          ownerEmail: '主人邮箱',
+          createdAt: '注册时间（毫秒时间戳）',
+          updatedAt: '最后更新时间（毫秒时间戳）',
+          ability: '普通模式能力列表（JSON 数组）',
+        },
+      };
+    },
+
+    // ─── 6. 能力发现 ───
+
+    async search_capabilities(p) {
+      return cx.searchCapabilities ? await cx.searchCapabilities(p) : { success: false, error: '未实现' };
+    },
+
+    async declare_capabilities(p) {
+      const abilities = p.ability;
+
+      if (!Array.isArray(abilities)) {
+        return { success: false, error: 'ability 必须为数组格式，如 [{"name":"...","fields":[...]}]' };
+      }
+
+      // 读取旧值，用于服务端同步失败时回滚
+      const oldRow = cx.query(`SELECT ability FROM agents WHERE agent_id=?`, [p.agentId]);
+      const oldValue = oldRow?.[0]?.ability || null;
+
+      const jsonStr = JSON.stringify(abilities);
+      cx.exec(`UPDATE agents SET ability=?, updated_at=? WHERE agent_id=?`, [jsonStr, Date.now(), p.agentId]);
+
+      if (cx.registerCapabilities) {
+        const result = await cx.registerCapabilities(p.agentId);
+        if (!result.success) {
+          // 服务端同步失败，回滚本地 DB
+          cx.exec(`UPDATE agents SET ability=?, updated_at=? WHERE agent_id=?`, [oldValue, Date.now(), p.agentId]);
+        }
+        return result;
+      }
+      return { success: true };
+    },
+
+    // ─── 8. 消息 ───
+
+    async send_message(p) {
+      const fromUid = cx.wukongim?.getCurrentUid?.(p.agentId) || 'voko';
+      // 将数字 contentType 映射为字符串 messageType：1=text 2=image 3=file（内部统一按桌面端 4=file 处理）
+      let messageType = 'text';
+      if (p.contentType === 2 || p.contentType === '2' || p.contentType === 'image') messageType = 'image';
+      else if (p.contentType === 3 || p.contentType === '3' || p.contentType === 'file') messageType = 'file';
+      else if (typeof p.contentType === 'string') messageType = p.contentType;
+
+      // 文件消息 content 归一化：支持 JSON 字符串 / 对象 / 纯 URL
+      let content = p.content;
+      if (messageType === 'file') {
+        content = normalizeFileContent(content);
+        // 如果 size 为 0，尝试 HEAD 探测远程文件大小和 MIME type
+        try {
+          const payload = JSON.parse(content);
+          if (!payload.size && payload.url) {
+            const meta = await probeFileMetadata(payload.url);
+            if (meta.size) {
+              payload.size = meta.size;
+              if (meta.type) payload.type = meta.type;
+              content = JSON.stringify(payload);
+            }
+          }
+        } catch (_) {
+          // 非 JSON 时不处理，直接发送
+        }
+      }
+
+      const result = cx.sendMessage(p.agentId, p.toUid, content, fromUid, messageType);
+      // 检测收消息通道是否畅通
+      if (cx.checkReceiveChannel) {
+        const ch = cx.checkReceiveChannel(p.agentId);
+        if (ch && !ch.ok) {
+          result.receiveChannel = { ok: false, channel: ch.channel, suggest: 'voko_fetch_new_messages' };
+        }
+      }
+      return result;
+    },
+
+    // ─── 9. 聊天历史 ───
+
+    async get_chat_history(p) {
+      const limit = Math.min(p.limit || 20, 200);
+      const offset = p.offset || 0;
+      let sql = `SELECT * FROM messages WHERE channel_id=? AND agent_id=?`;
+      const params = [p.channelId, p.agentId];
+      if (p.keyword) { sql += ` AND content LIKE ?`; params.push(`%${p.keyword}%`); }
+      sql += ` ORDER BY timestamp DESC LIMIT ? OFFSET ?`;
+      params.push(limit + 1, offset);
+      const rows = cx.query(sql, params);
+      const hasMore = rows.length > limit;
+      if (hasMore) rows.pop();
+      return { messages: rows.map(fmtMsg), hasMore, count: rows.length, offset };
+    },
+
+    // ─── 10. 访客信息 ───
+
+    async get_visitor_profile(p) {
+      const { visitorId, agentId } = p;
+      const msgLimit = p.limit || 10;
+      const msgOffset = p.offset || 0;
+      const cache = cx.query(`SELECT uid, nickname, avatar_url FROM user_cache WHERE uid=? LIMIT 1`, [visitorId]);
+      const profile = cache && cache[0] ? cache[0] : { uid: visitorId };
+
+      // 消息统计
+      const msgStats = cx.query(`SELECT COUNT(*) as total, MIN(timestamp) as firstAt, MAX(timestamp) as lastAt FROM messages WHERE from_uid=?`, [visitorId]);
+      const totalMessages = msgStats[0]?.total || 0;
+      const firstMessageAt = msgStats[0]?.firstAt || null;
+      const lastMessageAt = msgStats[0]?.lastAt || null;
+
+      // 黑白名单状态（需要 agentId）
+      let isWhitelisted = false, isBlacklisted = false;
+      if (agentId) {
+        isWhitelisted = !!cx.query(`SELECT 1 FROM agent_access_lists WHERE agent_id=? AND list_type='whitelist' AND visitor_id=?`, [agentId, visitorId]).length;
+        isBlacklisted = !!cx.query(`SELECT 1 FROM agent_access_lists WHERE agent_id=? AND list_type='blacklist' AND visitor_id=?`, [agentId, visitorId]).length;
+      }
+
+      // 最近对话（可配置条数、可翻页）
+      const recentSql = agentId
+        ? `SELECT content, timestamp, is_me FROM messages WHERE channel_id=? AND agent_id=? AND content_type!=11 ORDER BY timestamp DESC LIMIT ? OFFSET ?`
+        : `SELECT content, timestamp, is_me FROM messages WHERE channel_id=? AND content_type!=11 ORDER BY timestamp DESC LIMIT ? OFFSET ?`;
+      const recentMulti = msgLimit + 1; // 多取 1 条用来算 hasMore
+      const recentParams = agentId ? [visitorId, agentId, recentMulti, msgOffset] : [visitorId, recentMulti, msgOffset];
+      const recentRows = cx.query(recentSql, recentParams);
+      const hasMore = recentRows.length > msgLimit;
+      if (hasMore) recentRows.pop();
+      const recentMessages = recentRows.reverse().map(r => ({
+        content: r.content,
+        timestamp: r.timestamp,
+        isMe: r.is_me === 1,
+      }));
+
+      // 入站审核统计（只算访客触发的拦截，按 agent 隔离）
+      const auditSql = agentId
+        ? `SELECT is_me, content, timestamp FROM messages WHERE from_uid=? AND agent_id=? AND content_type=11 ORDER BY timestamp DESC LIMIT 50`
+        : `SELECT is_me, content, timestamp FROM messages WHERE from_uid=? AND content_type=11 ORDER BY timestamp DESC LIMIT 50`;
+      const auditParams = agentId ? [visitorId, agentId] : [visitorId];
+      const auditRows = cx.query(auditSql, auditParams);
+      let audit = { totalHits: 0, hardDenyCount: 0, softDenyCount: 0, lastHitAt: null, lastKeyword: null };
+      for (const r of auditRows) {
+        if (r.is_me !== 0) continue; // 只计入站
+        audit.totalHits++;
+        try {
+          const parsed = JSON.parse(r.content);
+          if (parsed.action === 'hard_deny') audit.hardDenyCount++;
+          else if (parsed.action === 'soft_deny') audit.softDenyCount++;
+          if (!audit.lastHitAt || r.timestamp > audit.lastHitAt) {
+            audit.lastHitAt = r.timestamp;
+            audit.lastKeyword = parsed.keyword || null;
+          }
+        } catch (_) {}
+      }
+
+      // 支付记录
+      const paidRows = cx.query(`SELECT 1 FROM payment_orders WHERE visitor_id=? AND status='paid' LIMIT 1`, [visitorId]);
+      const hasPaid = paidRows.length > 0;
+
+      return {
+        visitorId,
+        nickname: profile.nickname || null,
+        avatarUrl: profile.avatar_url || null,
+        totalMessages,
+        firstMessageAt,
+        lastMessageAt,
+        isWhitelisted,
+        isBlacklisted,
+        recentMessages,
+        hasMore,
+        audit,
+        hasPaid,
+      };
+    },
+
+    // ─── 11. 会话列表 ───
+
+    async list_conversations(p) {
+      const limit = Math.min(p.limit || 20, 100);
+      const filter = p.filter || 'unreplied';
+      const rows = cx.query(`SELECT * FROM conversations WHERE agent_id=? ORDER BY last_timestamp DESC LIMIT ?`, [p.agentId, limit]);
+      return {
+        conversations: rows.map(r => {
+          // 查最后一条消息是谁发的（排除审核拦截消息）
+          const lastMsg = cx.query(`SELECT is_me FROM messages WHERE channel_id=? AND agent_id=? AND content_type!=11 ORDER BY timestamp DESC LIMIT 1`, [r.channel_id, p.agentId]);
+          const needsReply = lastMsg?.[0]?.is_me !== 1;
+          // 计算未回复的访客消息数：最后一条 agent 回复之后，还有多少条访客消息
+          let unreadCount = 0;
+          if (needsReply) {
+            const lastAgentReply = cx.query(`SELECT timestamp FROM messages WHERE channel_id=? AND agent_id=? AND is_me=1 AND content_type!=11 ORDER BY timestamp DESC LIMIT 1`, [r.channel_id, p.agentId]);
+            const since = lastAgentReply?.[0]?.timestamp || 0;
+            unreadCount = cx.query(`SELECT COUNT(*) as cnt FROM messages WHERE channel_id=? AND agent_id=? AND is_me=0 AND timestamp > ?`, [r.channel_id, p.agentId, since])[0]?.cnt || 0;
+          }
+          return {
+            channelId: r.channel_id,
+            name: r.name,
+            lastMessage: r.last_message,
+            lastTimestamp: r.last_timestamp,
+            unreadCount,
+            needsReply,
+          };
+        })
+        .filter(c => filter === 'all' || c.needsReply),
+      };
+    },
+
+    // ─── 12. 文件上传 ───
+
+    async get_upload_url(p) {
+      if (!cx.uploadFileToOSS) {
+        return { success: false, error: 'OSS 未配置' };
+      }
+      try {
+        const fs = require('fs');
+        if (!p.filePath) return { success: false, error: '缺少 filePath' };
+        if (!fs.existsSync(p.filePath)) return { success: false, error: '文件不存在: ' + p.filePath };
+        const stat = fs.statSync(p.filePath);
+        const fileName = p.fileName || require('path').basename(p.filePath);
+        const ext = require('path').extname(fileName).toLowerCase();
+        const mimeMap = { '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.gif': 'image/gif', '.webp': 'image/webp', '.bmp': 'image/bmp', '.mp4': 'video/mp4', '.pdf': 'application/pdf', '.doc': 'application/msword', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', '.xls': 'application/vnd.ms-excel', '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', '.zip': 'application/zip', '.mp3': 'audio/mpeg', '.txt': 'text/plain', '.json': 'application/json' };
+        const mimeType = p.contentType || mimeMap[ext] || 'application/octet-stream';
+        const safeName = fileName.replace(/[^a-zA-Z0-9._-]/g, '_');
+        // 图片上传到 chat/images/，其他文件上传到 chat/files/，与桌面端保持一致
+        const imageExts = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'];
+        const dir = imageExts.includes(ext) ? 'chat/images' : 'chat/files';
+        const objectName = `${dir}/${safeName}`;
+        const url = await cx.uploadFileToOSS(p.filePath, objectName, mimeType);
+        return {
+          success: true,
+          url,
+          fileName,
+          fileSize: stat.size,
+          mimeType,
+        };
+      } catch (e) {
+        return { success: false, error: '上传失败: ' + e.message };
+      }
+    },
+
+    // ─── 13. whoami ───
+
+    async whoami(p) {
+      let sql = `SELECT agent_id AS agent_id, agent_name, description, short_description, category, backend_type, publish_status, access_mode, owner_email, created_at FROM agents`;
+      const params = [];
+      if (p.ownerEmail) {
+        sql += ` WHERE owner_email=?`;
+        params.push(p.ownerEmail);
+      }
+      sql += ` ORDER BY created_at ASC`;
+      const rows = cx.query(sql, params);
+      return {
+        agents: rows.map(r => ({
+          agentId: r.agent_id,
+          agentName: r.agent_name,
+          description: r.description,
+          shortDescription: r.short_description,
+          category: r.category,
+          backendType: r.backend_type,
+          publishStatus: r.publish_status,
+          accessMode: r.access_mode,
+          ownerEmail: r.owner_email,
+          createdAt: r.created_at,
+        })),
+      };
+    },
+
+    // ─── 14-16. 人工介入 ───
+
+    async ask_human_for_help(p) {
+      const now = Date.now();
+      const id = `mcp_${now}_${Math.random().toString(36).substr(2, 6)}`;
+      const channelType = cx.getEnabledChannel?.()?.name || null;
+      // 根据 backend 类型决定 session_key 前缀
+      const backendRow = cx.query ? cx.query(`SELECT backend_type FROM agents WHERE agent_id=?`, [p.agentId]) : [];
+      const backendType = backendRow?.[0]?.backend_type || 'openclaw';
+      const prefix = backendType === 'hermes' ? 'hermes' : 'agent';
+      cx.exec(`
+        INSERT INTO owner_interventions (id, agent_id, visitor_id, session_key, problem, agent_suggestion, ask_time, status, channel_type, created_at, updated_at)
+        VALUES (?,?,?,?,?,?,?,'pending',?,?,?)
+      `, [id, p.agentId, p.visitorId, `${prefix}:${p.agentId}:${p.visitorId}`, p.problem, p.suggestion || null, now, channelType, now, now]);
+      // 事件驱动：立即通知主人，不等轮询
+      if (cx.enqueueOwnerIntervention) {
+        cx.enqueueOwnerIntervention({
+          id, visitorId: p.visitorId, agentId: p.agentId,
+          sessionKey: `agent:${p.agentId}:${p.visitorId}`,
+          problem: p.problem, agentSuggestion: p.suggestion || '',
+          askTime: now, skipReply: 0,
+        });
+      }
+      return { success: true, interventionId: id };
+    },
+
+    async check_human_replies(p) {
+      // 按 id 查单条
+      if (p.id) {
+        const r = cx.query(`SELECT * FROM owner_interventions WHERE id=?`, [p.id])[0];
+        return {
+          interventions: r ? [{
+            id: r.id,
+            visitorId: r.visitor_id,
+            problem: r.problem,
+            suggestion: r.agent_suggestion,
+            askTime: r.ask_time,
+            ownerReply: r.owner_reply,
+            replyTime: r.reply_time,
+            status: r.status,
+          }] : [],
+          hasMore: false,
+        };
+      }
+
+      const limit = Math.min(p.limit || 20, 50);
+      const offset = p.offset || 0;
+      const multi = limit + 1;
+
+      // 自动游标：不传 since 时自动记录上次查询的最大 askTime
+      const cursorKey = `check_human_replies:${p.agentId}`;
+      let since = p.since;
+      if (!since && this._checkReplyCursor) {
+        since = this._checkReplyCursor.get(cursorKey);
+      }
+
+      // 构造 SQL
+      const conditions = [`agent_id=?`, `status!='resolved'`];
+      const params = [p.agentId];
+      if (p.visitorId) {
+        conditions.push(`visitor_id=?`);
+        params.push(p.visitorId);
+      }
+      if (since) {
+        conditions.push(`ask_time>?`);
+        params.push(since);
+      }
+      params.push(multi, offset);
+
+      const rows = cx.query(
+        `SELECT * FROM owner_interventions WHERE ${conditions.join(' AND ')} ORDER BY ask_time DESC LIMIT ? OFFSET ?`,
+        params
+      );
+
+      // 更新游标
+      if (!this._checkReplyCursor) this._checkReplyCursor = new Map();
+      if (!p.since && rows.length > 0) {
+        const maxTime = Math.max(...rows.map(r => r.ask_time));
+        this._checkReplyCursor.set(cursorKey, maxTime);
+      }
+      const hasMore = rows.length > limit;
+      if (hasMore) rows.pop();
+      return {
+        interventions: rows.map(r => ({
+          id: r.id,
+          visitorId: r.visitor_id,
+          problem: r.problem,
+          suggestion: r.agent_suggestion,
+          askTime: r.ask_time,
+          ownerReply: r.owner_reply,
+          replyTime: r.reply_time,
+          status: r.status,
+        })),
+        hasMore,
+      };
+    },
+
+    async close_human_request(p) {
+      cx.exec(`UPDATE owner_interventions SET status='resolved', resolved_at=?, updated_at=? WHERE id=?`, [Date.now(), Date.now(), p.id]);
+      return { success: true };
+    },
+
+    // ─── 16. 收款 ───
+
+    async request_payment(p) {
+      const hasAuth = cx.getPaymentAuth ? cx.getPaymentAuth(p.agentId) : null;
+      if (!hasAuth) return { success: false, error: '该 Agent 未配置支付认证，请通知主人配置' };
+      // 前置检查：Agent 必须已注册 DID 和私钥，否则后续无法完成 DID 签名
+      const agentKey = cx.query ? cx.query(`SELECT did, private_key FROM agents WHERE agent_id=? AND did IS NOT NULL AND private_key IS NOT NULL`, [p.agentId]) : [];
+      if (!agentKey || agentKey.length === 0) {
+        return { success: false, error: '该 Agent 未注册 DID 或未配置私钥，无法创建支付订单，请通知主人配置' };
+      }
+      const now = Date.now();
+      const orderId = `po_${now}_${Math.random().toString(36).substr(2, 8)}`;
+      const fromUid = cx.getAgentImUid ? cx.getAgentImUid(p.agentId) : '';
+      cx.savePaymentOrder({ id: orderId, agent_id: p.agentId, visitor_id: p.visitorId, from_uid: fromUid, amount: p.amount, description: p.description || '', type: 'service', status: 'pending', created_at: now, updated_at: now });
+      // 事件驱动：立即处理 pending 订单（DID 签名 → 调支付 API → 生成二维码 → 通知访客）
+      if (cx.processPaymentOrder) {
+        cx.processPaymentOrder({ id: orderId, agent_id: p.agentId, visitor_id: p.visitorId, from_uid: fromUid, amount: p.amount, description: p.description || '' }).catch(err => console.error('[MCP] 处理支付订单失败:', err.message));
+      }
+      return { success: true, orderId };
+    },
+
+    // ─── 18. 查询支付 ───
+
+    async check_payments(p) {
+      // 按 orderId 查单条
+      if (p.orderId) {
+        const r = cx.query(`SELECT id, agent_id, visitor_id, amount, description, order_no, status, created_at, updated_at FROM payment_orders WHERE id=?`, [p.orderId])[0];
+        return {
+          orders: r ? [{
+            orderId: r.id,
+            visitorId: r.visitor_id,
+            amount: r.amount,
+            description: r.description,
+            orderNo: r.order_no,
+            status: r.status,
+            createdAt: r.created_at,
+            updatedAt: r.updated_at,
+          }] : [],
+          hasMore: false,
+        };
+      }
+
+      const limit = Math.min(p.limit || 20, 50);
+      const offset = p.offset || 0;
+      const multi = limit + 1;
+
+      // 自动游标
+      const cursorKey = `check_payments:${p.agentId}`;
+      let since = p.since;
+      if (!since && this._checkPaymentCursor) {
+        since = this._checkPaymentCursor.get(cursorKey);
+      }
+
+      const conditions = [`agent_id=?`];
+      const params = [p.agentId];
+      if (p.visitorId) { conditions.push(`visitor_id=?`); params.push(p.visitorId); }
+      if (p.status) { conditions.push(`status=?`); params.push(p.status); }
+      if (since) { conditions.push(`created_at>?`); params.push(since); }
+      params.push(multi, offset);
+
+      const rows = cx.query(
+        `SELECT id, agent_id, visitor_id, amount, description, order_no, status, created_at, updated_at FROM payment_orders WHERE ${conditions.join(' AND ')} ORDER BY created_at DESC LIMIT ? OFFSET ?`,
+        params
+      );
+
+      // 更新游标
+      if (!this._checkPaymentCursor) this._checkPaymentCursor = new Map();
+      if (!p.since && rows.length > 0) {
+        const maxTime = Math.max(...rows.map(r => r.created_at));
+        this._checkPaymentCursor.set(cursorKey, maxTime);
+      }
+
+      const hasMore = rows.length > limit;
+      if (hasMore) rows.pop();
+      return {
+        orders: rows.map(r => ({
+          orderId: r.id,
+          visitorId: r.visitor_id,
+          amount: r.amount,
+          description: r.description,
+          orderNo: r.order_no,
+          status: r.status,
+          createdAt: r.created_at,
+          updatedAt: r.updated_at,
+        })),
+        hasMore,
+      };
+    },
+
+    // ─── 18b. 支付认证（入账银行卡）───
+
+    async add_payment_auth(p) {
+      const { name, idCard, bankCard, phone, bankCode, bankName } = p;
+      const now = Date.now();
+
+      if (!bankCode) return { success: false, error: 'bankCode 不能为空，请先通过 voko_search_banks 选择银行' };
+      if (!bankCard) return { success: false, error: 'bankCard 不能为空' };
+      const cleanBankCard = String(bankCard).replace(/\s/g, '');
+      if (!/^\d{13,19}$/.test(cleanBankCard)) return { success: false, error: '银行卡号格式不正确，应为13-19位数字' };
+      if (!phone || !/^1\d{10}$/.test(String(phone).trim())) return { success: false, error: '手机号格式不正确' };
+      if (!name) return { success: false, error: '姓名不能为空' };
+      if (!idCard) return { success: false, error: '身份证号不能为空' };
+      if (!/^\d{17}[\dXx]$/.test(String(idCard).trim())) return { success: false, error: '身份证号格式不正确，应为18位' };
+
+      const newId = 'pid_' + now + '_' + Math.random().toString(36).substr(2, 6);
+      cx.exec(`INSERT INTO payment_auth (id, name, id_card, bank_card, phone, receiver_type, bank_code, bank_name, company_name, unified_social_credit_code, legal_name, legal_licence_no, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [newId, name, idCard || '', cleanBankCard || '', phone || '', 1, bankCode || '', bankName || '', '', '', '', '', '未认证', now, now]);
+      return { success: true, id: newId };
+    },
+
+    // ─── 18c. 查看入账银行卡列表 ───
+
+    async list_payment_auth(p) {
+      const keyword = (p.keyword || '').trim();
+      let sql = `SELECT * FROM payment_auth ORDER BY updated_at DESC`;
+      let params = [];
+      if (keyword) {
+        const kw = `%${keyword}%`;
+        sql = `SELECT * FROM payment_auth WHERE name LIKE ? OR bank_card LIKE ? OR phone LIKE ? ORDER BY updated_at DESC`;
+        params = [kw, kw, kw];
+      }
+      const rows = cx.query(sql, params);
+      const receiverStatusLabel = {
+        'none': '未申请', PROCESSING: '申请中', AGREEMENT_SIGNING: '待签署',
+        COMPLETED: '已完成', APPLY_REJECTED: '已拒绝'
+      };
+      const masked = rows.map(r => ({
+        id: r.id,
+        name: r.name,
+        nameMask: r.name ? r.name[0] + '*'.repeat(r.name.length - 1) : '',
+        idCardMask: r.id_card ? r.id_card.substring(0, 4) + '**********' : '',
+        bankCardMask: r.bank_card ? r.bank_card.substring(0, 4) + '****' + r.bank_card.slice(-4) : '',
+        phoneMask: r.phone ? r.phone.substring(0, 3) + '****' + r.phone.slice(-4) : '',
+        receiverType: r.receiver_type,
+        receiverTypeLabel: r.receiver_type === 2 ? '对公' : '对私',
+        receiverApplyStatus: r.receiver_apply_status,
+        receiverApplyStatusLabel: receiverStatusLabel[r.receiver_apply_status] || r.status || '未知',
+        bankCode: r.bank_code,
+        bankName: r.bank_name,
+        companyName: r.company_name,
+        status: r.status,
+        createdAt: r.created_at,
+        updatedAt: r.updated_at,
+      }));
+      return { success: true, data: masked };
+    },
+
+    // ─── 18d. 删除入账银行卡 ───
+
+    async delete_payment_auth(p) {
+      if (!p.id) return { success: false, error: '缺少 id' };
+      // 若该银行卡已被 Agent 绑定，先解除绑定
+      cx.exec(`UPDATE agents SET payment_auth_id = NULL, updated_at = ? WHERE payment_auth_id = ?`, [Date.now(), p.id]);
+      cx.exec(`DELETE FROM payment_auth WHERE id = ?`, [p.id]);
+      return { success: true };
+    },
+
+    // ─── 18e. 申请认证 ───
+
+    async apply_payment_auth(p) {
+      const { paymentAuthId, email: explicitEmail } = p;
+      if (!paymentAuthId) return { success: false, error: '缺少 paymentAuthId' };
+
+      const auth = cx.query(`SELECT * FROM payment_auth WHERE id = ?`, [paymentAuthId])[0];
+      if (!auth) return { success: false, error: '未找到支付认证信息' };
+
+      let email = explicitEmail ? String(explicitEmail).trim().toLowerCase() : '';
+      if (!email) {
+        const boundAgent = cx.query(`SELECT owner_email FROM agents WHERE payment_auth_id = ? AND owner_email IS NOT NULL LIMIT 1`, [paymentAuthId])[0];
+        email = boundAgent?.owner_email || '';
+      }
+      if (!email) {
+        const anyAgent = cx.query(`SELECT owner_email FROM agents WHERE owner_email IS NOT NULL LIMIT 1`)[0];
+        email = anyAgent?.owner_email || '';
+      }
+      if (!email) return { success: false, error: '无法获取用户邮箱，请先通过邮箱验证码登录/注册，或显式传入 email' };
+
+      if (!cx.getUserAccessToken || !cx.VOKO_API_URL) {
+        return { success: false, error: 'MCP 上下文未提供 getUserAccessToken 或 VOKO_API_URL' };
+      }
+      const userToken = cx.getUserAccessToken(email);
+      if (!userToken) return { success: false, error: '缺少 User Access Token，请先通过邮箱验证码登录/注册以获取' };
+
+      const type = auth.receiver_type || 1;
+      const body = {
+        email,
+        type,
+        receiverName: type === 2 ? (auth.company_name || auth.name) : auth.name,
+        licenceNo: type === 2 ? (auth.unified_social_credit_code || auth.id_card) : auth.id_card,
+        bankCardNo: auth.bank_card,
+        bankCode: auth.bank_code || '',
+        mobile: auth.phone,
+      };
+      if (type === 2) {
+        if (auth.legal_name) body.legalName = auth.legal_name;
+        if (auth.legal_licence_no) body.legalLicenceNo = auth.legal_licence_no;
+      }
+
+      const resp = await fetch(`${cx.VOKO_API_URL}/api/external/v1/payment/receiver/apply`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${userToken}` },
+        body: JSON.stringify(body)
+      });
+      const result = await resp.json();
+      const data = result.data || {};
+      const failMsg = result.msg || result.message || '';
+
+      if (result.code !== 200) return { success: false, error: failMsg || '申请认证失败', code: result.code, data };
+
+      const now = Date.now();
+      let applyStatus = data.receiverApplyStatus || 'PROCESSING';
+      if (data.alreadyRegistered) applyStatus = 'COMPLETED';
+      let statusUpdate = auth.status || '未认证';
+      const upstreamMsg = data.upstreamMsg || data.hint || failMsg || '';
+      if (applyStatus === 'APPLY_REJECTED' && upstreamMsg) statusUpdate = '拒绝: ' + upstreamMsg.substring(0, 100);
+
+      cx.exec(`UPDATE payment_auth SET request_no = ?, receiver_no = ?, receiver_apply_status = ?, receiver_sign_status = ?, receiver_sign_url = ?, merchant_sign_url = ?, payment_user_uid = ?, status = ?, updated_at = ? WHERE id = ?`,
+        [data.requestNo || '', data.receiverNo || '', applyStatus, data.receiverSignStatus || '', data.receiverSignUrl || '', data.merchantSignUrl || '', data.paymentUserUid || '', statusUpdate, now, paymentAuthId]);
+      return { success: true, data };
+    },
+
+    // ─── 18f. 搜索银行总行 ───
+
+    async search_banks(p) {
+      const keyword = (p.keyword || '').trim();
+      let rows;
+      if (!keyword) {
+        rows = cx.query(`SELECT * FROM bank_head_offices ORDER BY id LIMIT 50`);
+      } else {
+        const kw = `%${keyword}%`;
+        rows = cx.query(`SELECT * FROM bank_head_offices WHERE code LIKE ? OR name LIKE ? OR short_name LIKE ? ORDER BY id LIMIT 50`, [kw, kw, kw]);
+      }
+      return { success: true, data: rows.map(r => ({ code: r.code, name: r.name, shortName: r.short_name })) };
+    },
+
+    // ─── 18f. Agent 绑定入账银行卡 ───
+
+    async bind_agent_payment_auth(p) {
+      const { agentId, paymentAuthId } = p;
+      if (!agentId || !paymentAuthId) return { success: false, error: '缺少 agentId 或 paymentAuthId' };
+
+      const auth = cx.query(`SELECT payment_user_uid, request_no, id_card, unified_social_credit_code, receiver_type FROM payment_auth WHERE id = ?`, [paymentAuthId])[0];
+      if (!auth) return { success: false, error: '未找到支付认证信息' };
+      if (!auth.payment_user_uid && !auth.request_no) {
+        return { success: false, error: '该银行卡尚未申请认证，请先调用 voko_apply_payment_auth 完成认证（receiverApplyStatus=COMPLETED 后再绑定）' };
+      }
+
+      const agent = cx.query(`SELECT owner_email, did, private_key FROM agents WHERE agent_id = ?`, [agentId])[0];
+      if (!agent) return { success: false, error: '未找到 Agent' };
+      if (!agent.did) return { success: false, error: 'Agent 未注册 DID' };
+      if (!agent.private_key) return { success: false, error: 'Agent 未配置私钥' };
+
+      // 1. 本地绑定
+      cx.exec(`UPDATE agents SET payment_auth_id = ? WHERE agent_id = ?`, [paymentAuthId, agentId]);
+      const bound = cx.query(`SELECT payment_fee_rate, agent_usage_fee_rate FROM agents WHERE payment_auth_id = ? AND agent_id != ? LIMIT 1`, [paymentAuthId, agentId])[0];
+      if (bound) {
+        cx.exec(`UPDATE agents SET payment_fee_rate = ?, agent_usage_fee_rate = ? WHERE agent_id = ?`, [bound.payment_fee_rate, bound.agent_usage_fee_rate, agentId]);
+      }
+
+      // 2. 服务端 link-agent 同步
+      if (!cx.signDidRequest) {
+        return { success: true, warning: '本地绑定成功，但 MCP 上下文未提供 signDidRequest，未同步服务端' };
+      }
+
+      try {
+        const bizFields = { email: agent.owner_email || '', agentDid: agent.did };
+        if (auth.payment_user_uid) {
+          bizFields.paymentUserUid = auth.payment_user_uid;
+        } else if (auth.request_no) {
+          bizFields.requestNo = auth.request_no;
+        } else {
+          bizFields.licenceNo = auth.receiver_type === 2 ? (auth.unified_social_credit_code || auth.id_card) : auth.id_card;
+          if (auth.receiver_type) bizFields.type = auth.receiver_type;
+        }
+
+        const authFields = await cx.signDidRequest(agent.did, agent.private_key, bizFields);
+        const body = { ...authFields, ...bizFields };
+
+        const resp = await fetch(ENDPOINTS.payment.baseUrl + '/payment/receiver/link-agent', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(body)
+        });
+        const result = await resp.json();
+        if (result.code === 200) {
+          const data = result.data || {};
+          const feeRate = data.paymentFeeRate;
+          const usageRate = data.agentUsageFeeRate;
+          if (feeRate != null || usageRate != null) {
+            const s = []; const v = [];
+            if (feeRate != null) { s.push('payment_fee_rate = ?'); v.push(feeRate); }
+            if (usageRate != null) { s.push('agent_usage_fee_rate = ?'); v.push(usageRate); }
+            v.push(agentId);
+            cx.exec(`UPDATE agents SET ${s.join(', ')} WHERE agent_id = ?`, v);
+          }
+          return { success: true, data };
+        }
+        return { success: false, error: result.msg || '绑定失败', code: result.code };
+      } catch (e) {
+        console.error('[MCP] bind_agent_payment_auth link-agent 失败:', e.message);
+        return { success: false, error: e.message };
+      }
+    },
+
+    // ─── 19. 计费模式 ───
+
+    async agent_pricing(p) {
+      // 设置了 pricingModel 则为写操作
+      if (p.pricingModel) {
+        const now = Date.now();
+        const isFree = p.pricingModel === 'free';
+        const finalTrial = isFree ? null : (p.trialMinutes ?? 3);
+        const existing = cx.query(`SELECT id FROM agent_pricing WHERE agent_id=?`, [p.agentId]);
+        if (existing && existing.length > 0) {
+          cx.exec(`UPDATE agent_pricing SET pricing_model=?, price=?, duration_minutes=?, trial_minutes=?, enabled=1, updated_at=? WHERE agent_id=?`,
+            [p.pricingModel, isFree ? null : (p.price || null), isFree ? null : (p.durationMinutes || null), finalTrial, now, p.agentId]);
+        } else {
+          const id = 'ap_' + now + '_' + Math.random().toString(36).substr(2, 6);
+          cx.exec(`INSERT INTO agent_pricing (id, agent_id, pricing_model, price, duration_minutes, trial_minutes, enabled, created_at, updated_at) VALUES (?,?,?,?,?,?,1,?,?)`,
+            [id, p.agentId, p.pricingModel, isFree ? null : (p.price || null), isFree ? null : (p.durationMinutes || null), finalTrial, now, now]);
+        }
+        return { success: true };
+      }
+
+      // 不传 pricingModel 则为查询
+      const row = cx.query(`SELECT * FROM agent_pricing WHERE agent_id=?`, [p.agentId])[0] || null;
+      return {
+        agentId: p.agentId,
+        pricingModel: row?.pricing_model || 'free',
+        price: row?.price || null,
+        durationMinutes: row?.duration_minutes || null,
+        trialMinutes: row?.trial_minutes ?? 3,
+        enabled: row?.enabled !== 0,
+      };
+    },
+
+    // ─── 20. 轮询新消息 ───
+
+    _fetchCursors: new Map(),
+
+    _channelCursorKey(agentId, channelId) {
+      return `${agentId}:${channelId}`;
+    },
+
+    _getChannelCursor(agentId, channelId) {
+      return this._fetchCursors.get(this._channelCursorKey(agentId, channelId)) ?? 0;
+    },
+
+    _setChannelCursor(agentId, channelId, seq) {
+      const key = this._channelCursorKey(agentId, channelId);
+      const current = this._fetchCursors.get(key) || 0;
+      if (seq > current) this._fetchCursors.set(key, seq);
+    },
+
+    async fetch_new_messages(p) {
+      const blockTimeout = p.blockTimeout || 0;
+      const limit = Math.min(p.limit || 50, 200);
+      const onlyReplies = p.onlyReplies !== false;
+
+      // 单访客模式：key 用 agentId:visitorId，行为和以前一致
+      if (p.visitorId) {
+        const key = this._channelCursorKey(p.agentId, p.visitorId);
+        const seq = p.messageSeq ?? this._fetchCursors.get(key) ?? 0;
+
+        if (blockTimeout > 0) {
+          const prev = this._fetchBlocks?.get(key);
+          if (prev) prev.abort();
+          if (!this._fetchBlocks) this._fetchBlocks = new Map();
+          const ctrl = { aborted: false };
+          this._fetchBlocks.set(key, ctrl);
+          try {
+            const rows = await this._pollSingleChannel(p.agentId, p.visitorId, seq, limit, onlyReplies, blockTimeout, ctrl);
+            if (rows.length > 0) {
+              const maxSeq = Math.max(...rows.map(r => r.message_seq || 0));
+              this._setChannelCursor(p.agentId, p.visitorId, maxSeq);
+            }
+            const hasMore = rows.length > limit;
+            if (hasMore) rows.pop();
+            return { messages: rows.map(fmtMsg), hasMore, count: rows.length };
+          } finally {
+            if (this._fetchBlocks?.get(key) === ctrl) this._fetchBlocks.delete(key);
+          }
+        }
+
+        const rows = this._queryMessages(p.agentId, p.visitorId, seq, onlyReplies, limit);
+        const hasMore = rows.length > limit;
+        if (hasMore) rows.pop();
+        if (rows.length > 0) {
+          const maxSeq = Math.max(...rows.map(r => r.message_seq || 0));
+          this._setChannelCursor(p.agentId, p.visitorId, maxSeq);
+        }
+        return { messages: rows.map(fmtMsg), hasMore, count: rows.length };
+      }
+
+      // ─── 全量模式（不指定 visitorId）：按 channel 分别维护游标 ───
+      // 因为 WuKongIM 的 message_seq 是按 channel 独立的，用单一全局游标
+      // 会导致低 seq channel 的新消息被漏掉。
+      const channels = cx.query(
+        `SELECT channel_id FROM messages WHERE agent_id=? GROUP BY channel_id`,
+        [p.agentId]
+      );
+
+      const allRows = [];
+      for (const { channel_id: channelId } of channels) {
+        const autoCursor = this._getChannelCursor(p.agentId, channelId);
+        let seq = autoCursor;
+        // 该 channel 首次拉取且用户传了全局 messageSeq 时：
+        // 仅当该 channel 的最大 seq 大于全局阈值，才把 messageSeq 作为起始点；
+        // 否则从 0 开始，避免低 seq channel 的新消息被全局高 seq 漏掉。
+        if (seq === 0 && p.messageSeq != null) {
+          const maxRow = cx.query(
+            `SELECT MAX(message_seq) as max_seq FROM messages WHERE agent_id=? AND channel_id=?`,
+            [p.agentId, channelId]
+          );
+          const channelMaxSeq = maxRow[0]?.max_seq || 0;
+          if (channelMaxSeq >= p.messageSeq) {
+            seq = p.messageSeq;
+          }
+        }
+        const rows = this._queryMessages(p.agentId, channelId, seq, onlyReplies, limit);
+        allRows.push(...rows);
+      }
+
+      // 合并后按 message_seq 升序，保证分页稳定
+      allRows.sort((a, b) => (a.message_seq || 0) - (b.message_seq || 0));
+
+      const hasMore = allRows.length > limit;
+      if (hasMore) allRows.length = limit;
+
+      // 更新各 channel 自动游标
+      for (const row of allRows) {
+        this._setChannelCursor(p.agentId, row.channel_id, row.message_seq || 0);
+      }
+
+      return { messages: allRows.map(fmtMsg), hasMore, count: allRows.length };
+    },
+
+    _queryMessages(agentId, channelId, seq, onlyReplies, limit) {
+      let sql = `SELECT * FROM messages WHERE agent_id=? AND channel_id=? AND message_seq > ?`;
+      const params = [agentId, channelId, seq];
+      if (onlyReplies) sql += ` AND is_me!=1`;
+      sql += ` ORDER BY message_seq ASC LIMIT ?`;
+      params.push(limit + 1);
+      return cx.query(sql, params);
+    },
+
+    // 阻塞轮询单 channel：被取消时返回空数组
+    async _pollSingleChannel(agentId, channelId, seq, limit, onlyReplies, timeoutSec, ctrl) {
+      const start = Date.now();
+      while (!ctrl.aborted) {
+        const rows = this._queryMessages(agentId, channelId, seq, onlyReplies, limit);
+        if (rows.length > 0) return rows;
+        if (Date.now() - start >= timeoutSec * 1000) return [];
+        await new Promise(r => setTimeout(r, 1000));
+      }
+      return [];
+    },
+
+    // ─── 18. 白名单管理 ───
+
+    async manage_whitelist(p) {
+      const ac = require('../core/access-control-api');
+      if (p.action === 'remove') {
+        return ac.removeEntryByVisitor(cx.db || db, p.agentId, p.visitorId, 'whitelist');
+      }
+      return ac.addEntry(cx.db || db, { agentId: p.agentId, listType: 'whitelist', visitorId: p.visitorId, reason: p.reason }, {
+        onWhitelistAdded: (aid, vid) => {
+          if (cx.sendSystemMessage) {
+            cx.sendSystemMessage(aid, vid, '【系统消息】好友申请已通过，可以继续交流。', Math.floor(Date.now() / 1000));
+          }
+        }
+      });
+    },
+
+    // ─── 19. 黑名单管理 ───
+
+    async manage_blacklist(p) {
+      const ac = require('../core/access-control-api');
+      if (p.action === 'remove') {
+        return ac.removeEntryByVisitor(cx.db || db, p.agentId, p.visitorId, 'blacklist');
+      }
+      return ac.addEntry(cx.db || db, { agentId: p.agentId, listType: 'blacklist', visitorId: p.visitorId, reason: p.reason });
+    },
+
+    // ─── 20. 查看黑白名单 ───
+
+    async list_access_lists(p) {
+      const ac = require('../core/access-control-api');
+      return ac.getList(cx.db || db, { agentId: p.agentId, listType: p.listType });
+    },
+
+    // ─── 21. 白名单模式 ───
+
+    async set_private_mode(p) {
+      if (cx.toggleWhitelistMode) {
+        return cx.toggleWhitelistMode({ agentId: p.agentId, enabled: p.enabled });
+      }
+      const newMode = p.enabled ? 'private' : 'public';
+      cx.exec(`UPDATE agents SET access_mode=?, updated_at=? WHERE agent_id=?`, [newMode, Date.now(), p.agentId]);
+      if (cx.registerCapabilities) {
+        await cx.registerCapabilities(p.agentId, { discoverable: !p.enabled });
+      }
+      return { success: true, accessMode: newMode };
+    },
+
+    // ─── 31. 邀请好友 ───
+
+    // ═══════════════════════════════════════════
+    //  审核规则管理
+    // ═══════════════════════════════════════════
+
+    async list_audit_rules(p) {
+      const sql = p.direction
+        ? 'SELECT * FROM audit_rules WHERE direction = ? ORDER BY is_default DESC, created_at ASC'
+        : 'SELECT * FROM audit_rules ORDER BY is_default DESC, created_at ASC';
+      const rows = p.direction ? cx.query(sql, [p.direction]) : cx.query(sql);
+      return { success: true, data: rows };
+    },
+
+    async manage_audit_rules(p) {
+      if (p.action === 'add') {
+        if (!p.direction || !p.keyword || !p.actionType) {
+          return { success: false, error: 'add 需要 direction, keyword, actionType' };
+        }
+        const id = `audit_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;
+        cx.exec(
+          `INSERT INTO audit_rules (id, direction, keyword, action, prompt, is_default, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 0, ?, ?)`,
+          [id, p.direction, p.keyword, p.actionType, p.prompt || null, Date.now(), Date.now()]
+        );
+        return { success: true, id, message: `审核规则已添加 (${id})` };
+      }
+
+      if (p.action === 'update') {
+        if (!p.ruleId) return { success: false, error: 'update 需要 ruleId' };
+        const sets = []; const vals = [];
+        if (p.keyword !== undefined) { sets.push('keyword = ?'); vals.push(p.keyword); }
+        if (p.actionType !== undefined) { sets.push('action = ?'); vals.push(p.actionType); }
+        if (p.prompt !== undefined) { sets.push('prompt = ?'); vals.push(p.prompt); }
+        if (sets.length === 0) return { success: false, error: '无可更新的字段' };
+        sets.push('updated_at = ?'); vals.push(Date.now());
+        vals.push(p.ruleId);
+        cx.exec(`UPDATE audit_rules SET ${sets.join(', ')} WHERE id = ?`, vals);
+        return { success: true, message: `审核规则已更新 (${p.ruleId})` };
+      }
+
+      if (p.action === 'delete') {
+        if (!p.ruleId) return { success: false, error: 'delete 需要 ruleId' };
+        cx.exec('DELETE FROM audit_rules WHERE id = ?', [p.ruleId]);
+        return { success: true, message: `审核规则已删除 (${p.ruleId})` };
+      }
+
+      return { success: false, error: `未知 action: ${p.action}` };
+    },
+
+    async invite_friend(p) {
+      const { agentId, friendEmail: rawEmails, friendName } = p;
+      const row = cx.query(`SELECT agent_name, owner_email, did FROM agents WHERE agent_id=?`, [agentId]);
+      if (!row?.[0]) return { success: false, error: 'Agent 不存在' };
+      const myName = row[0].agent_name || agentId;
+      const ownerDid = row[0].did;
+      console.log('[Invite] agentId=' + agentId + ' myName=' + myName + ' rawEmails=' + rawEmails);
+
+      // 解析多个邮箱：逗号/分号/换行分隔，去重，过滤掉主人自己
+      const ownerEmail = (row[0].owner_email || '').trim().toLowerCase();
+      const emailList = [...new Set(
+        (rawEmails || '').split(/[,;\n\r，]+/).map(e => e.trim().toLowerCase()).filter(Boolean)
+      )].filter(e => e !== ownerEmail);
+      if (emailList.length === 0) return { success: false, error: '没有有效的受邀邮箱' };
+      console.log('[Invite] 有效受邀邮箱数=' + emailList.length + ' list=' + emailList.join(','));
+
+      const guideUrl = 'http://files.vokovoko.com/chat/files/VOKO_MCP_GUIDE.md';
+      const currentVer = (() => { try { return require('../../package.json').version; } catch (_) { return '0.0.0'; } })();
+
+      // 从 latest.yml 获取最新版本号
+      let latestVer = currentVer;
+      try {
+        const resp = await fetch('http://files.vokovoko.com/updates/latest.yml');
+        if (resp.ok) {
+          const text = await resp.text();
+          const m = text.match(/^version:\s*(\S+)/m);
+          if (m) latestVer = m[1];
+        }
+      } catch (_) {}
+      const downloadUrl = `http://files.vokovoko.com/updates/VOKO-Desktop-Setup-${latestVer}.exe`;
+
+      // 每个邮箱生成独立的邀请码，入库（已有未使用的不重复生成）
+      const invites = emailList.map(email => {
+        const existing = cx.query(`SELECT code FROM friend_invitations WHERE agent_id=? AND friend_email=?`, [agentId, email]);
+        if (existing?.[0]?.code) {
+          console.log('[Invite] 复用邀请码 agent=' + agentId + ' email=' + email + ' code=' + existing[0].code);
+          return { email, code: existing[0].code };
+        }
+        const code = Math.random().toString(36).substring(2, 8).toUpperCase();
+        cx.exec(`INSERT OR REPLACE INTO friend_invitations (code, agent_id, friend_email, whitelisted, created_at) VALUES (?, ?, ?, 0, ?)`,
+          [code, agentId, email, Date.now()]);
+        console.log('[Invite] 生成邀请码 agent=' + agentId + ' email=' + email + ' code=' + code);
+        return { email, code };
+      });
+
+      // 每个邀请者生成独立的提示词
+      const invitationPrompts = invites.map(inv => ({
+        email: inv.email,
+        code: inv.code,
+        prompt: buildInvitationPrompt({
+          myName, ownerEmail: row[0].owner_email, version: currentVer, guideUrl, downloadUrl,
+          friendEmail: inv.email, inviteCode: inv.code
+        })
+      }));
+
+      // 通过 VOKO 系统邮件发送邀请（每封邮件独立生成提示词，含各自邮箱和邀请码）
+      const emailResults = [];
+      console.log('[Invite] 准备发送邮件 agentEmailApi=' + !!cx.agentEmailApi + ' ownerDid=' + (ownerDid || '无'));
+      if (!cx.agentEmailApi) console.log('[Invite] cx.agentEmailApi 不存在');
+      if (!ownerDid) console.log('[Invite] Agent 无 DID');
+      if (cx.agentEmailApi && ownerDid) {
+        for (const inv of invites) {
+          try {
+            const prompt = buildInvitationPrompt({
+              myName, ownerEmail: row[0].owner_email, version: currentVer, guideUrl, downloadUrl,
+              friendEmail: inv.email, inviteCode: inv.code
+            });
+            const sendRes = await cx.agentEmailApi.send(ownerDid, prompt, {
+              to: inv.email,
+              subject: buildEmailSubject(myName),
+              external_id: `invite-${inv.code}`,
+              reply_enabled: false,
+            });
+            const sent = !!sendRes?.message_id;
+            emailResults.push({ email: inv.email, code: inv.code, sent, message_id: sendRes?.message_id || null });
+            console.log('[Invite] 邮件发送 ' + (sent ? '成功' : '失败') + ' email=' + inv.email + ' code=' + inv.code + ' msgId=' + (sendRes?.message_id || '-'));
+          } catch (e) {
+            emailResults.push({ email: inv.email, code: inv.code, sent: false, note: e.message });
+            console.log('[Invite] 邮件发送异常 email=' + inv.email + ' code=' + inv.code + ' err=' + e.message);
+          }
+        }
+      } else {
+        // 无法发送邮件时，为每个邀请记录失败原因
+        for (const inv of invites) {
+          emailResults.push({ email: inv.email, code: inv.code, sent: false, note: !cx.agentEmailApi ? '邮件服务未就绪' : 'Agent 未注册 DID' });
+        }
+      }
+
+      return {
+        success: true,
+        agentId,
+        myName,
+        guideUrl,
+        downloadUrl,
+        currentVersion: currentVer,
+        invites,
+        invitationPrompts,
+        emailSent: emailResults.length > 0 ? emailResults : null,
+        instructions: `已将 ${invites.length} 位好友的邀请码入库，并通过邮件发送邀请提示词。好友发来的消息包含对应邀请码时自动通过并加入白名单。`,
+      };
+    },
+  };
+}
+
+module.exports = { createToolHandlers };